Get Message Information

GetMsgInfo

The GetMsgInfo procedure returns the message text, severity level and second level text for a previously defined message stored in a message file.

The GetMsgInfo procedure can be used to extract a message from an existing message file. The message's message data may be embedded in the returned message message text. Both message text and second level message text is returned along with the message severity.

XT_MsgInfo-Struct  GetMsgInfo(
 szMsgID         7A    Const 
 szMsgFile      21A    Const OPTIONS(*NOPASS : *OMIT)
 szMsgData     512A    Const OPTIONS(*NOPASS : *VARSIZE)
 nMsgDataLen    10I 0  Const OPTIONS(*NOPASS)
)

See also: GetMsgText, GetMsgPrefix, SetMsgPrefix

Parameters

szMsgID
[input Char(7) const]  This parameter specifies the message ID to be retrieved. A full or partial message ID may be specified. That is a full message ID including the 3-character message prefix, or just the 4-position message ID "number" may be passed. If the message ID is less than 4 position in length, it is padded on the left with zeros.
 

Valid formats for message identifiers are as follows:

 *...v....1
'CFP1006'
'1006'
'CFP0106'
'106'
 
szMsgFile [optional]
[input Char(21) const]  Message file name. This parameter consists of two parts (1) in the first 10 positions, the name of the message file, and (2) in the second 10 positions, the name of the library containing the message file For example:
 
 *...v....1....v....2
'QCPFMSG   QSYS      '
 

An alternative syntax is also supported for the message file name parameter. The alternate syntax allows you to specify the message file name similar to that of an OS/400 CL command, that is it may be qualified using qualified name syntax, as follows:

 *...v....1....v....2
'QSYS/QCPFMSG        '
 

If this parameter is NOT specified, the default message file name is used. The default message file name may be set by calling the SetMsgPrefix() procedure. This parameter overrides any value specified for SetMsgPrefix(). In addition, once a message file name has been specified, it is used as the new default message file name. Subsequent calls to GetMsgText and GetMsgInfo use this new default message file name.

 

szMsgData [optional]
[input VChar(512) const]  Specify the message data that will be substituted within the returned message text. The length of the value passed on this parameter must be specified on the nMsgDataLength parameter.
 
nMsgDataLength  [optional]
[input Int4 (10i0) const]  Specify the length of the message data specified on the 2nd parameter, szMsgData. You can use the %SIZE(mdvalue) built-in function to specify the length of the message data parameter. Substitute the name of the field you pass for the szMsgData parameter in place of the mdvalue.  

 

Overriding the Message Settings

To override the default message file name being used to extract the information by the message procedures, use the SetMsgProp (Set message properties) procedure. The default message file name is QCPFMSG on the library list.

Return Value

The return value is an XT_MSGINFO data structure, whose format is as follows:

     D XT_MsgInfo     DS                  Inz

      /IF       DEFINED(*V5R1M0)

      /IF   NOT DEFINED(XT_NO_V5)

     D                                     QUALIFIED BASED(XT_NULL)

      /ENDIF                                     

      /ENDIF

     D   tk_MsgID                     7A

     D   tk_MsgSev                    2S 0

     D   tk_MsgFile                  10A

     D   tk_MsgFileLib...

     D                               10A

     D   tk_nMsgTextLen...

     D                               10I 0

     D   tk_MsgText                 512A

     D   tk_nSecLvlLen...

     D                               10I 0

     D   tk_SecLvl                 4096A

This data structure is declared in the MSG source member of the QCPYSRC source file. If you are running OS/400 Version 5.1 or later, you must use this data structure as a "template" and not store data in it directly. That is if you are running OS/400 Version 5.1 or later, declare a data structure based on XT_MSGINFO using the LIKEDS keyword.

Subfield Attributes Description
tk_MsgID Char(7) The full message ID returned.
tk_MsgSev Dec(2,0) The message severity.
tk_MsgFile Char(10) The name of the message file where the message info was extracted.
tk_MsgFileLib Char(10) The name of the library where the message file is located.
tk_nMsgTextLen Int4(10i0) The length of the 1st-level message text.
tk_MsgText Char(512) The 1st-level message text.
tk_nSecLvlLen Int4(10i0) The length of the 2nd-level message text.
tk_SecLvl Char(4096) The 2nd-level message text.

If the function fails, check the XT_ERROR data structure's subfield XT_ERRMsgID for the error message ID indicating why the message retrieval was not successful.

If you are porting an application to OS/400 Version 5 from OS/400 Version 4, you may avoid the OS/400 Version 5.1 and later extensions in the RPG xTools by declaring the XT_NO_V5 identifier in your source members, as follows:


     H/DEFINE  XT_NO_V5

This /DEFINE statement should be embedded near the top of your source member, prior to any /INCLUDE or /INCLUDE statements. If specified, code created for OS/400 Version 4 will continue to compile and function on Version 5 and later as it does on Version 4.

To utilize the Version 5 features of the RPG xTools, such as qualified data structures and data structure templates, do not define this identifier in your source code.

Example

To retrieve message information for a message ID, such as CPF1006 from the message file QCPFMSG, the following example may be used:

.....DName+++++++++++EUDS.......Length+TDc.Functions++++++++++++++++++++++++++
     /INCLUDE XTOOLS/QCPYSRC,msg
     D myMsgInfo       DS                  LikeDS(XT_MSGINFO)
     D szMsgText       S            132A   
 
.....CSRn01..............OpCode(ex)Extended-factor2+++++++++++++++++++++++++++
     C                   Eval      myMsgInfo = GetMsgInfo('1006')
     C                   eval      szMsgText = myMsgText.tk_MsgText

In this example, the 1st and 2nd-level message text along with the message severity for CPF1006 is returned to the MYMSGINFO data structure. Note if you are running OS/400 Version 4, the LIKEDS keyword is not supported in RPG IV, therefore you will need to use the LIKE() keyword and use unqualified subfield names.

In this example, the message information is returned to the MyMsgInfo data structure and copied into the szMsgText field.

 

Get Message Text

GetMsgText

The GetMsgText procedure returns the 1st-level message text of a previously defined message, stored in a message file.

The GetMsgText procedure can be used to extract a message from an existing message file and insert substitution data (if provided). 

char-value  GetMsgText(
 szMsgID         7A    Const
 szMsgFile      21A    Const OPTIONS(*NOPASS : *OMIT)
 szMsgData     512A    Const OPTIONS(*NOPASS : *VARSIZE)
 nMsgDataLen    10I 0  Const OPTIONS(*NOPASS)
)

See also: GetMsgInfo, SetMsgPrefix

Parameters

szMsgID
[input Char(7) const]  This parameter specifies the message ID to be retrieved. A full or partial message ID may be specified. That is a full message ID including the 3-character message prefix, or just the 4-position message ID "number" may be passed. If the message ID is less than 4 position in length, it is padded on the left with zeros.
 

Valid formats for message identifiers are as follows:

 *...v....1
'CFP1006'
'1006'
'CFP0106'
'106'
 
szMsgFile [optional]
[input Char(21) const]  Message file name. This parameter consists of two parts (1) in the first 10 positions, the name of the message file, and (2) in the second 10 positions, the name of the library containing the message file For example:
 
 *...v....1....v....2
'QCPFMSG   QSYS      '
 

An alternative syntax is also supported for the message file name parameter. The alternate syntax allows you to specify the message file name similar to that of an OS/400 CL command, that is it may be qualified using qualified name syntax, as follows:

 *...v....1....v....2
'QSYS/QCPFMSG        '
 

If this parameter is NOT specified, the default message file name is used. The default message file name may be set by calling the SetMsgPrefix() procedure. This parameter overrides any value specified for SetMsgPrefix(). In addition, once a message file name has been specified, it is used as the new default message file name. Subsequent calls to GetMsgText() and GetMsgInfo() use this new default message file name.

 
szMsgData [optional]
[input VChar(512) const]  Specify the message data that will be substituted within the returned message text. The length of the value specified for this parameter must be specified on the 3rd parameter, nMsgDataLength. You can use the %SIZE built-in function or %LEN() built-in function to calculate the length of the value specified for this parameter.
 
nMsgDataLength  [optional]
[input Int4 (10i0) const]  Specify the length of the message data specified on the 2nd parameter, szMsgData. If the szMsgData parameter is unspecified, is not required.

Get Message Prefix

GetMsgPrefix

The GetMsgPrefix procedure returns the current message prefix or message file name used as default values if they are not provided.

The GetMsgPrefix procedure can be used to retrieve the current default message prefix or message file name. 

char-value  GetMsgPrefix(
 nOption     10I 0  Const OPTIONS(*NOPASS)
)

See also: GetMsgText, GetMsgInfo SetMsgPrefix

Parameters

nOption  [optional]
[input Int4 (10i0) const]  The option parameter indicates which information is returned.
 
If 0 is or no value is passed, the default message prefix is returned.
If 1 is specified, the default message file is returned as a 20-position character value. Position 1 to 10 contain the message file name, position 11 to 20 contain the message file library.

 

Set Message Prefix

SetMsgPrefix

The SetMsgPrefix procedure sets the default message prefix and message file name.

The SetMsgPrefix procedure can be used to change the default message prefix and message file name. These defaults are used by the GetMsgText and GetMsgInfo procedures. 

char-value  SetMsgPrefix(
 szMsgPrefix     7A    Const OPTIONS(*NOPASS : *OMIT)
 szMsgFile      21A    Const OPTIONS(*NOPASS)
)

See also: GetMsgText, GetMsgInfo, GetMsgPrefix

Parameters

szMsgPrefix [optional]
[input VChar(7) const]  This parameter specifies the message prefix to be used when a full message ID is not specified on the GetMsgText and GetMsgInfo procedures. The message prefix must be at least 3 characters in length and no more than 6 characters in length.
 
szMsgFile [optional]
[input Char(21) const]  The default message file name used by the GetMsgText and GetMsgInfo procedures when their MSGFILE parameter is not specified.
 
This parameter consists of two parts (1) in the first 10 positions, the name of the message file, and (2) in the second 10 positions, the name of the library containing the message file For example:
 *...v....1....v....2
'QCPFMSG   QSYS      '
 

An alternative syntax is also supported for the message file name parameter. The alternate syntax allows you to specify the message file name similar to that of an OS/400 CL command, that is it may be qualified using qualified name syntax, as follows:

 *...v....1....v....2
'QSYS/QCPFMSG        '