16.20 - Message-text - 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

Message-text is a 76-byte field that is the text of the message indicated by Return Code. The language of the text is specified by the Language-id and the Country-id options.

In this language... The variable name for Message-text is...
COBOL DBCAREA-MSG-TEXT
PL/I MSG_TEXT
C, C++ msg_text
IBM Assembler DBCMSG
This routine... Does this for Message-text...
DBCHINI writes
DBCHCL writes
Message-text is used by... To...
applications read

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.

If the character set requires more than one byte per character, it may exceed the size of Message-text. Message-area-pointer may be used to provide a larger area for the message.

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.