16.20 - Messages for Return Codes - Teradata Tools and Utilities

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

prodname
Teradata Tools and Utilities
vrm_release
16.20
created_date
September 2019
category
Programming Reference
featnum
B035-2417-108K

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).