9 116 GET_MESSAGE

9.116 GET_MESSAGE

Þ Note: Built-In Function Rules.

Gets the details of the next message from the program queue of the RDML function.

Normally the returned message details are then processed or printed by the RDML function in some non-standard way.

Messages on the program queue of an RDML function normally displayed on line 22/24 of the next screen presented to the user and then automatically cleared / removed.

Messages may have been placed on the program message queue by operating system commands, Built-In Functions, invalid I/O requests and/or RDML commands such as MESSAGE, VALUECHECK, etc.

 

Portability Considerations

This BIF does not retrieve the Message File or Message Id number when running under LANSA SuperServer. See the note following the example below.

 

For use with

LANSA for i YES Visual LANSA for Windows YES Visual LANSA for Linux YES

 

Arguments

No Type Req/ Opt Description Min Len Max Len Min Dec Max Dec 1 A Opt Remove message from queue Y - message is removed N - message is not removed Default value is Y. 1 1

 

Return Values

No Type Req/ Opt Description Min Len Max Len Min Dec Max Dec 1 A Req Message return code OK = message returned NO = no message found 2 2     2 A Opt Message text 1 132     3 A Opt Message number 1 7     4 A Opt Message file name 1 10     5 A Opt Message file library 1 10     6 A Opt Message substitution variable 1 132

 

Example

Insert a new name and address into file NAMES in a batch program. If an error is detected, print details of the name and address an exception report with all associated error messages.

DEFINE     FIELD(#ERRTXT) TYPE(*CHAR) LENGTH(100) 
           LABEL('Error :')
DEF_LINE   NAME(#NAME)  FIELDS(#CUSTNO #ADDRESS1 
                               #ADDRESS2 #ZIPCODE)
DEF_LINE   NAME(#ERROR) FIELDS(#ERRTXT) IDENTIFY(*LABEL)

INSERT     FIELDS(#NAME) TO_FILE(NAMES) VAL_ERROR(*NEXT)
IF_STATUS  IS_NOT(*OKAY)
      PRINT      LINE(#NAME)
      USE        BUILTIN(GET_MESSAGE) TO_GET(#RETCODE #ERRTXT)
      DOWHILE    COND('#RETCODE = OK')
           PRINT      LINE(#ERROR)
           USE        BUILTIN(GET_MESSAGE) 
                      TO_GET(#RETCODE #ERRTXT)
      ENDWHILE
ENDIF

Note:

Running the same program under IBM i and in LANSA SuperServer mode will produce different messages.
A retrieved message using this BIF on the IBM i will display:

Message text:      Record to be updated has been changed by another job/user
Message number:    IOM0017
Message file name: DC@M01

Running in LANSA SuperServer mode (against the IBM i) will display:

Message text:      Record to be updated has been changed by another job/user
Message number:    *STCMSG
Message file name: 2

This is a design consideration that, due to technical complexities, will not be changed in the short term.