Messages for Return Codes
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.
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.
Notice:
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).