This procedure returns error message text specified by the error number in NUM and in the language designated in LANG_NAME. The desired length of the return message can be specified in the MSG_LEN parameter. If the returned text is shorter than the length specified, the procedure pads the remaining portion of the record with blanks.

An entire message consists of the following three parts:

Part or all of the message text can be returned. Note that the header part starts at MSG[0], the short description at MSG[80], and the long description at MSG[160]. For example, if MSG_LEN is specified to be equal to 200 characters, then MSG would contain the header message padded with blanks to 80, if necessary, followed by the short description padded with blanks to 160, if necessary, followed by 40 characters of the long description.

The requested message length should be at least 80 characters, equal to one line of text. Anything less results in an incomplete message. It is recommended that you use either a length of 80, 160, or 999. The value of 999 causes the entire message to be returned.

This procedure might be used to retrieve the text of an error message so that it can be displayed by a program.

Example

This example illustrates how to get the message text associated with a CENTRALSUPPORT error message. Assume that the sample call to VALIDATE_NAME_RETURN_NUM returns error number 3004 (CS_NO_NUM_FOUNDV). When an error is returned this example gets the first 160 characters (2 lines) of the message text for that error.

BEGIN 
 $ INCLUDE INTL="SYMBOL/INTL/ALGOL/PROPERTIES." 10000000 - 49999999

  FILE OUT(KIND=DISK,UNITS=CHARACTERS,FILEUSE=IO,FILETYPE=0,NEWFILE,
           MAXRECSIZE=80,TITLE="OUT/ALGOL/GET_CS_MSG.");

  EBCDIC ARRAY CCSVSNNAME[0:17]
             ,LANG[0:17]
             ,MSG[0:159];
  INTEGER MSG_LEN
        ,NUM
        ,RESULT1
        ,RESULT2;

  REPLACE CCSVSNNAME[0] BY "BADNAME" FOR 7;
  RESULT1 := VALIDATE_NAME_RETURN_NUM(CS_CHARACTER_SETV,CCSVSNNAME, NUM);
  WRITE(OUT,<"RESULT FROM VALIDATE_NAME_RETURN_NUM = ",J4>,RESULT1);
  IF RESULT1 NEQ CS_DATAOKV THEN
     BEGIN
     MSG_LEN := 160;
     RESULT2 := GET_CS_MSG(RESULT1, LANG, MSG, MSG_LEN);
     WRITE(OUT,<"RESULT FROM GETCSMSG = ",J4>,RESULT2);
     WRITE(OUT,<"MSG =">);
     WRITE(OUT,<A80>,MSG[0]);
     WRITE(OUT,<A80>,MSG[80]);
     END;
   CLOSE(OUT,LOCK);
END.

Output

RESULT FROM VALIDATE_NAME_RETURN_NUM = 3004
RESULT FROM GETCSMSG = 1
MSG =>>> CENTRALSUPPORT INTERFACE ERROR (#3004) <<<
INVALID CHARACTER SET OR CCSVERSION NAME

In this call, the parameters have the following meanings:

RESULT1 is an integer passed by reference to the procedure. It specifies an error that was returned by a library procedure. The error numbers and their meanings are listed at the end of this section.

LANG is an EBCDIC array passed to the procedure. It specifies the language to be used for the message text. If this parameter contains all blanks or zeros, the procedure uses the default language hierarchy to determine the language to be used. Refer to the MultiLingual System Administration, Operations, and Programming Guide for details about determining the valid language names on the system and for the explanation of the hierarchy.

MSG is an EBCDIC array returned by the procedure. It contains the message text associated with the error number specified.

MSG_LEN in an integer passed to the procedure. For input, it specifies the maximum length of the message to be returned. It also contains an update value as an output parameter. If MSG_LEN is equal to 0 (zero), one line of text (80 characters) is returned. If MSG_LEN is between 1 and 79, then only a partial message is returned. MSG_LEN should not be greater than the size of the MSG array. Recommended values for MSG_LEN are 80, 160, or a large number, such as 999, that returns all of the message. For output, MSG_LEN specifies the actual length of the message returned by the procedure.

RESULT2 is an integer returned by the procedure. It indicates whether or not an error occurred during the execution of the procedure. An explanation of the error result values and messages can be found at the end of this section. The values returned by this procedure include: