9.96 GET_MESSAGE

Note: Built-In Function Rules     Usage Options

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.

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.