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.