Retrieve XML Service Information (QSCRXMLI) API

The Retrieve XML Service Information (QSCRXMLI) API lists service information like messages from a nonprogram message queue or messages sent to the program message queue of a job, in XML format, and optionally stores the output in a stream file.

The Retrieve XML Service Information API cannot be used to list messages sent to the QHST message queue.

New messages are prevented from being added to or removed from the message queue listed during the use of the QSCRXMLI API.

See Open List of Messages (QGYOLMSG) API or Open List of Job Log Messages (QGYOLJBL) API for the description of the message fields returned.

Authorities and Locks

Output File Authority (if output stored in a stream file)

Authority to the path and file are determined by the open() API. For details, see the Authorities section of the open()--Open File API for files opened with an access mode of O_WRONLY and O_TRUNC.

Output File Lock

*SHRNUP

Message Queue

*USE

Message Queue Library

*EXECUTE

User Space Lock

*EXCLRD

Job Authority

• *JOBCTL special authority if the job for which messages are being listed has a different user profile from that of the job that calls the QSCRXMLI API.
• *ALLOBJ and *JOBCTL special authorities if the job for which messages are being retrieved has *ALLOBJ and *JOBCTL special authority. As an alternative to having *ALLOBJ authority, the user calling the API can be authorized to the All Object Job Log function of Operating System through iSeries Navigator's Application Administration support. The Change Function Usage (CHGFCNUSG) command, with a function ID of QIBM_ACCESS_ALLOBJ_JOBLOG, can also be used to change the list of users that are allowed to access a job log that has *ALLOBJ special authority.

For additional information on job authorities, see Plan and set up system security.

Required Parameter Group

Destination information

INPUT; CHAR(*)

Provides information about the destination for the generated XML output.

• If DEST0100 is specified for the destination format name, this parameter contains a 4-byte integer which is the size of the receiver variable (parameter 3).
• If DEST0200 is specified for the destination format name, this parameter contains a structure which gives the path name of the stream file where the generated XML output is to be stored.

Destination format name

INPUT; CHAR(8)

The destination format to determine where the generated XML output will be stored. Possible values are:

DEST0100	Return the XML output in the receiver variable.
DEST0200	Return the XML output in a stream file using the path name coded in the destination information parameter.

Receiver variable

OUTPUT; CHAR(*)

The variable that is to receive the generated XML output. The variable is used only when the destination format name is DEST0100. If the receiver variable is not large enough to hold all of the generated XML output, no XML output is returned.

Receiver format name

INPUT; CHAR(8)

The format of the generated XML output to be returned. You must use one of the following format names:

SIRV0100

The information returned to the caller of this API. For more information, see SIRV0100 Format.

Service selection information

INPUT; CHAR(*)

The information that identifies the source of the service information to be returned. The format of this information depends on the specified Service selection format name.

Service selection format name

INPUT; CHAR(8)

Indicates where the service information will be retrieved from. The possible values are:

SSIF0100	The list of messages will be retrieved from a nonprogram message queue as specified in SSIF0100 Service Selection Information from a Nonprogram Message Queue Format.
SSIF0200	The list of messages will be retrieved from a program message queue of a job as specified in SSIF0200 Service Selection Information from a Porgram Message of a Job Format.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

DEST0100 Format

Field Descriptions

Length of receiver variable. The length of the receiver variable. If the length is larger than the size of the receiver variable, the results may not be predictable. The minimum length is 8 bytes.

DEST0200 Format

The destination information parameter (parameter 1) specifies the file path name where the generated XML output is to be returned for the DEST0200 format. See Path name format for information on specifying the output stream file path name.

SIRV0100 Format

The following information is returned in the receiver variable for the DEST0100 format.

Field Descriptions

Bytes available. The number of bytes of data available to be returned. All available data is returned if enough space is provided.

Bytes returned. The number of bytes of data returned.

XML data. The XML output of the service information returned. If the receiver variable is not large enough to hold the entire XML output or if an unexpected error occurs while writing to the receiver variable, no data will be returned.

XML data length. The length of the XML data being returned.

SSIF0100 Service Selection Information from a Nonprogram Message Queue Format

Field Descriptions

Message queue library. The name of the library where the message queue is located.

Message queue name. The name of the message queue whose messages are to be listed.

SSIF0200 Service Selection Information from a Program Message Queue of a Job Format

Field Descriptions

Qualified job name. The name of the job whose messages are to be listed. The qualified job name has three parts:

Usage Notes

The output file path name is represented by the 'Path name' field in the 'Path Name Format' structure when using the DEST0200 destination format. The output file path name is used to store the generated XML output. The output stream file is opened for writing only, in text-only mode, in CCSID 1208, and allows sharing with readers only. If the output stream file exists, the file is truncated to zero length before writing any data. If the output stream file already exists, it should have been created with a CCSID of 1208; otherwise, the resulting XML output may not be usable. If the output file does not exist, it will be created with a CCSID of 1208 before attempting to write the XML output to it. The output file is created so that the file owner has read and write permission to it. The output file can be replaced if the user has the authority to do so. For more information on authority requirements for stream files, see the open()--Open File API in the Integrated File System section of the APIs in the Information Center.

Error Messages

The following messages may be sent from this function: