From To Description Type

41 44 Length of replacement data or impromptu Integer(10)

message text returned

45 48 Length of replacement data or impromptu Integer(10)

message text available

49 * Replacement data or impromptu message Char(*)

text

Bytes returned defines the length of all information returned in the format. When
you attempt to receive a message and the message is not found, the following
results occur:
• The value of the bytes returned field is 8.
• The value of the bytes available field is 0.

The message severity, identifier, type, and key contain information about the
received message.

The last field in this format contains the values for substitution variables in a
predefined message, or the text of an impromptu message.

5.4.2.3 List Job Log Messages (QMHLJOBL) API

The List Job Log Messages (QMHLJOBL) API lists messages sent to the job
message queue of a job. This API gets the requested message information and
returns it in a user space in the format specified in the parameter list.

The generated list replaces any existing information in the user space. If the user
space is not large enough to contain the data to be returned, the user space is
increased to the maximum user space size allowed (16 MB) or the maximum
amount of storage allowed to the user of the API.

This API has required parameters only, which are shown in Table 42.
Table 42. Required parameter group for QMHLJOBL

Number Description Use Data type

1 Qualified user space name Input Char(20)

2 Format name Input Char(8)

3 Message selection information Input Char(*)

4 Size of message selection information Input Integer(10)

5 Format of message selection information Input Char(8)

6 Error code I/O Char(*)

The Qualified user space name parameter specifies the user space that receives
the generated list, and the library in which it is located. The first 10 characters
contain the user space name, and the second 10 characters contain the user
space library.

The format of the returned message information is defined by the format name
parameter. The valid format name is LJOB0100.

177
 The message selection parameters determine the job message queue and
messages to be selected. For the format name for the message selection
information parameter, you can use JSLT0100 or JSLT0200. The formats are the
same with the exception that the JSLT0200 format allows you to specify the
CCSID for the returned message data.

JSLT0100 format
Table 43 shows the message selection information that can be defined using the
format JSLT0100.
Table 43. JSLT0100 format

From To Description Type

1 4 Maximum messages requested Integer(10)

5 14 List direction Char(10)

15 24 Qualified job name Char(10)

25 34 Qualified user name Char(10)

35 40 Qualified job number Char(6)

41 56 Internal job identifier Char(16)

57 60 Starting message key Char(4)

61 64 Maximum message length Integer(10)

65 68 Maximum message help length Integer(10)

69 72 Offset to identifiers of fields to return Integer(10)

73 76 Number of fields to return Integer(10)

77 80 Offset to call message queue name Integer(10)

81 84 Length of call message queue name Integer(10)

The offsets to these fields Identifiers of fields to return Array(*) of

are specified in the Integer(10)
previous offset variables.
Call message queue name Char(*)

Maximum messages requested specifies the maximum number of messages to

be returned. To list all messages in the job log in the specified list direction from
the starting message key, use the special value of -1.

List direction specifies the direction to list messages. Valid values are *NEXT or
*PRV.

To identify the job whose messages are to be listed, you can use either job name,
user name and job number, or internal job identifier provided by the List Job
(QUSLJOB) API. The value "*" in a job name is used to identify a current job.

Starting message key specifies a key to begin searching for messages. You can
use these special values for the message key:
'00000000'X Start searching from the oldest message in the queue.
'FFFFFFFF'X Start searching from the newest message in the queue.

178 Who Knew You Could Do That with RPG IV?

The maximum message length parameters specify the number of characters of
text that this API returns. The special value of -1 defines that the maximum length
will be used.

At the end of format LJOB0100, one or more selected fields are returned. They
are defined by special identifiers, such as "0302" for a message with replacement
data. The user must specify their number and offset to these fields.

The last field in format LJOB0100 specifies the name of the call message queue
from which the messages are listed. You must use one of these values:
* Messages from every call stack entry of the job are listed.
*EXT Only messages sent to the external message queue (*EXT) of the job
are to be listed.

Format of generated lists

To provide a consistent design and use of the user space (*USRSPC) objects, the
OS/400 list APIs use a common data structure. The list APIs are those APIs that
generate a list and have a user space parameter, such as the List Job Log
Messages (QMHLJOBL). The user space created with QMHLJOBL API consists
of the following areas:
• A user area
• A generic header
• An input parameter section
• A header section
• LJOB0100 format
Figure 24 on page 180 shows the general data structure for list APIs.

179
 Generic Header Section
64 Byte User Area

Size of Generic Header

.
.
.
Offset and Size of Input
Parameter Section

Offset and Size of Header

Section

Offset and Size of List Data

Section

Number and Size of List

Entries
Input Parameter Section

Header Section (60 Bytes)

Entry 1 List Data Section

(Entries are in LJOB0100
Entry 2 format)
Entry 3
.
.
.
Last Entry

Figure 24. General data structure for list APIs

Generic header format

Table 44 shows the layout of the generic header format for an original program
model (OPM) program.
Table 44. Generic header format

From To Description Type

1 64 User area Char(64)

65 68 Size of generic header Integer(10)

69 72 Structure’s release and level Char(4)

73 80 Format name Char(8)

81 90 API used Char(10)

91 103 Date and time created Char(13)

104 104 Information status Char(1)

105 108 Size of user space used Integer(10)

109 112 Offset to input parameter section Integer(10)

113 116 Size of input parameter section Integer(10)

117 120 Offset to header section Integer(10)

121 124 Size of header section Integer(10)

180 Who Knew You Could Do That with RPG IV?

 From To Description Type

125 128 Offset to list data section Integer(10)

129 132 Size of list data section Integer(10)

133 136 Number of list entries Integer(10)

137 140 Size of each entry Integer(10)

141 144 CCSID of data in the list entries Integer(10)

Input parameter section format

This section contains an exact copy of all the parameters coded in the call to the
API. Table 45 shows the layout of the input parameter section format.
Table 45. Input parameter section format

From To Description Type

1 10 User space name specified Char(10)

11 20 User space library specified Char(10)

21 28 Format name specified Char(8)

29 36 Format of message selection information Char(8)

specified

37 40 Size of message selection information Integer(10)

specified

41 44 Maximum messages requested specified Integer(10)

45 54 List direction specified Char(10)

55 64 Job name specified Char(10)

65 74 User profile specified Char(10)

75 80 Job number specified Char(6)

81 96 Internal job identifier specified Char(16)

97 100 Staring message key specified Char(4)

101 104 Maximum message length specified Integer(10)

105 108 Maximum message help length specified Integer(10)

109 112 Offset to identifiers of fields to return Integer(10)

specified

113 116 Number of fields to return specified Integer(10)

117 120 Offset to call message queue specified Integer(10)

121 124 Length of call message queue specified Integer(10)

125 128 Coded character set identifier specified Integer(10)

129 * Reserved Char(*)

The offsets to these fields Identifiers of fields to return specified Array(*) of

are specified in the Integer(10)
previous offset variables.
Call message queue specified Char(*)

181
 Header section format
This section contains information about the current values of parameters used by
this invocation of the API. Table 46 shows the layout of the header section format.
Table 46. Header section format

From To Description Type

1 10 User space name used Char(10)

11 20 User space library used Char(10)

21 24 Starting message key used Char(4)

25 28 Ending message key used Char(4)

29 38 Job name used Char(10)

39 48 User profile used Char(10)

49 54 Job number used Char(6)

55 56 Reserved Char(2)

57 60 Coded character set identifier used Integer(10)

LJOB0100 format
Table 47 shows the information returned in the list data section of the user space
for the LJOB0100 format. The offsets listed are from the beginning of the user
space. The structure defined by this format is repeated for each message entry
returned.
Table 47. LJOB0100 format

From To Description Type

1 4 Offset to the next entry Integer(10)

5 8 Offset to fields returned Integer(10)

9 12 Number of fields returned Integer(10)

13 16 Message severity Integer(10)

17 23 Message identifier Char(7)

24 25 Message type Char(2)

26 29 Message key Char(4)

30 39 Message file name Char(10)

40 49 Message file library specified at send time Char(10)

50 56 Date sent Char(7)

57 62 Time sent Char(6)

63 * Reserved Char(*)

182 Who Knew You Could Do That with RPG IV?

 From To Description Type

These fields repeat for Offset to the next field information returned Integer(10)
each identifier specified.
Length of field information returned Integer(10)

Identifier field Integer(10)

Type of data Char(1)

Status of data Char(1)

Reserved Char(14)

Length of data Integer(10)

Data Char(*)

Reserved Char(*)

5.4.3 Programming with message handling APIs

Message handling APIs are used in an RPG IV program the same way as other
OPM APIs. They can be used to establish communication between programs by
sending messages instead of transferring program parameters. This technique is
similar to the use of data queues for program communication, but is limited to the
programs within the same job.

For the sake of simplicity, we use immediate messages in our examples instead
of predefined messages, which must be defined in the message file.

5.4.3.1 Source code for prototypes MSGPROTO

Source member MSGPROTO contains prototypes for calling the message
handling APIs QMHSNDPM, QMHRCVPM, and QMHLJOBL.

* Filename MSGPROTO from APISRC in RPGISCOOL

* Prototype for API QMHSNDPM - Send Program Message

D SendMessage Pr ExtPgm('QMHSNDPM') 1
D MsgId 7A
D QualMsgFile 20A
D MsgData 30A
D MsgDataLen 10I 0 Const
D MsgType 10A Const
D CallStEntry 10A
D CallStCount 10I 0
D MsgKey 4A
D Error 16A

* Prototype for API QMHRCVPM - Receive Program Message

D RcvMessage Pr ExtPgm('QMHRCVPM') 2
D MsgData 78A
D MsgDataLen 10I 0 Const
D FormatName 8A Const
D CallStEntry 10A
D CallStCount 10I 0
D MsgType 10A Const
D MsgKey 4A
D WaitTime 10I 0
D MsgAction 10A Const
D Error 16A

* Prototype for API QMHLJOBL - List Job Log Messages

D ListJobLog Pr ExtPgm('QMHLJOBL') 3
D QualUserSpc 20A
D FormatRet 8A Const
D SelInfo 84A
D SelInfoSize 10I 0 Const

183