Message-area-pointer is a four-byte field that specifies the address of an area into which any error message will be placed when a non-zero return code occurs. The Message-area-length field specifies the length of the addressed area. CLIv2 does not alter this value, so after the value is set, it remains unless changed by an application.
| In this language... | The variable name for Message-area-pointer is... |
|---|---|
| COBOL | DBCIMSGP |
| PL/I | DBCIMSGP |
| C, C++ | dbciIMsgP |
| IBM Assembler | DBCIMSGP |
| This routine... | Does this for Message-area-pointer... |
|---|---|
| DBCHINI | writes |
| DBCHCL | reads |
| Message-area-pointer is used by... | To... |
|---|---|
| applications | writes |
An error message is returned when a CLIv2 routine that uses the DBCAREA ends with a non-zero return code. The message is contained either in the Message-text field 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 not specified, the Message-text field contains the message and Message-text-length returns the length of the message. If Message-area-pointer is specified, the area addressed contains the message and Message-length returns the length of the message.
If an error occurs while building the 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.
The character set used to construct the message is indicated by Message-charset-used. The session character set is always used if it is known, but if the error occurred before this character set is known, the default CLIv2 character set is used.
When a CLIv2 routine that uses the DBCAREA ends with a zero return code, any text from a previous error is overwritten with spaces in the character set indicated by Message-charset-used, and the length of the message is zeroed.