15.10 - Messages for Return Codes - Call-Level Interface Version 2

Teradata Call-Level Interface Version 2 Reference for Mainframe-Attached Systems

Call-Level Interface Version 2
Programming Reference

When a CLIv2 routine that uses the DBCAREA returns a non-zero return code, an associated error message is also returned. The message will be contained either in Message Text within the DBCAREA or in the area addressed by Message Area Pointer. A message is never returned in both places.

  • If Message Area Pointer is specified, it is used; otherwise, Message Text is used.
  • Message Text is a fixed size field in the DBCAREA, so the maximum length of a message is the size of that area, 76 bytes. Message Text Length contains the actual number of bytes in the message.
  • Message Area Pointer addresses an area supplied by the application whose length is specified by Message Area Length.
  • Message Length contains the actual number of bytes in the message. The maximum value of this field is 65535.
  • Messages are normally built using the character set specified for the session when the request is initiated; however, if an error is detected before this character set is known, the default CLIv2 character set is used. The character set used to construct the message is indicated by Message Charset Used.

    If an error occurs while building a message, the Message Return Code field contains a CLIv2 return code. When this code is not zero, the text of the message may or may not be usable, depending on the nature of the error.

    Each message begins with the three characters “CLI” followed by a four‑digit message number. If the actual message text cannot be used, one of the following parenthesized phrases is used:

  • '(UNDEFINED MESSAGE NUMBER)' if an invalid message number was requested.
  • '(REQUIRED MESSAGE TABLE IS NOT AVAILABLE)' if messages were not available in the specified language.
  • The message language for each session is specified by the Language Id and Country Id options.


    Because the message language can differ for every request, the appropriate message definitions are loaded into virtual storage when messages must be built and deleted from virtual storage afterwards. These actions involve a certain performance penalty that is normally negligible since CLIv2 return codes are unusual events. However, the design of applications should consider the potential penalty in numerous invocations of CLIv2 routines that return error messages when errors are expected, such as continuous invocations until a transient error condition clears (a communication loss, for example).