Retrieve XML Service Information (QSCRXMLI) API

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

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

See the Open List of Messages (QGYOLMSG) API, Open List of Job Log Messages (QGYOLJBL) API, or Open List of History Log Messages (QMHOLHST) 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 that calls the API can be authorized to the All Object Job Log function of the IBM^® i operating system through System i™ 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.
SSIF0300	The list of messages will be retrieved from the History Log as specified in SSIF0300 Service Selection Information from the History Log.

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:

SSIF0300 Service Selection Information from the History Log

Field Descriptions

End by date. Specifies the ending date for messages and jobs to be listed. If blank, *END will be used.

One of the following is used to specify the ending date before which or on which the data must have been logged.

*CURRENT

The current day is the last day for which logged data is listed.

*END

The last day on which data was logged is the last day for which the logged data is listed. If *END is specified, an ending time value other than *AVAIL is ignored.

end-date

The format of this field is in CYYMMDD as follows, with the last 3 bytes of the field ignored:

C	Century, where 0 indicates years 19xx and 1 indicates years 20xx.
YY	Year
MM	Month
DD	Day

End by time. Specifies the ending time for messages and jobs to be listed. If blank, *AVAIL will be used.

One of the following is used to specify the ending time before which the data must have been logged.

*AVAIL

Any logged data that is available for the specified ending date is listed.

end-time

Specify the ending time for the specified ending date that indicates the logged data to be listed. The time is specified in 24-hour format and the format of this field is in the HHMMSS as follows, with the last 4 bytes of the field ignored:

HH	Hour
MM	Minute
SS	Second

End by time microseconds. Specifies the ending times microseconds. Messages will be listed up to and including this time if available. If blank, 0 will be used.

Jobs to list. Specifies the specific jobs (if any) for which messages in the log are listed. The messages for the specified jobs are retrieved only if they were logged in the period of time, message severity, message types and messages specified on the call. If the offset and number of jobs to list are 0 all available jobs will be listed.

• job-name
• user-name/job-name
• job-number/user-name/job-name

If a job name is not qualified with a user name and number, all jobs by that name in the log, within the selection will have their messages returned. Use blanks for the job-number or user-name if the job-name is to be listed for all job-number/user-names. Up to 5 jobs are supported.

Length of the fixed portion of the information. Specifies the length of the fixed portion of the selection information. It must be set to 92.

Message IDs list. Specifies the specific message IDs to be retrieved or omitted. Up to 100 message IDs are supported. If not specified, all of the messages will be listed for the jobs, message severity, message types and times specified. If the offset list contents indicator and number message IDs are 0 all available messages will be listed. To select specific generic types of messages, specify the 3-character code that identifies the message file followed by all zeros. For example, CPF0000 specifies that all CPF messages that meet the specifications of the previous parameters are selected or omitted. If an identifier is specified as pppnn00, any message beginning with the specified five characters (pppnn) can be selected or omitted.

Format of Message IDs list:

Message IDs list contents indicator. Specifies if the messages IDs in the list are to be omitted or selected. To omit the message ids in the list set this field to 1. To select the message ids in the list set this field to 0. If not specified, 0 will be used.

Message severity. The minimum severity of the messages to be listed. Possible values are 0 through 99. Specify 0 to list all messages for the jobs, times, message types and message ids specified. If not specified, 0 will be used.

Message types list. Specifies the specific message types to be retrieved or omitted. Up to 10 message types are supported. If not specified all of the messages will be listed for the jobs, message severity and times specified. If the offset and number of message types are 0, all available message types will be listed.

Format of Message types list:

Valid message type values and their meanings follow:

Message types list contents indicator. Specifies if the message types in the list are to be omitted or selected. To omit the message types in the list set this field to 1. To select the message types in the list set this field to 0. If not specified, 0 will be used.

Number of jobs to list. Specifies the number of jobs to list. Specifying 0 for this field will list all jobs available for the time, message severity, message types and message ids specified. A maximum of 5 jobs can be specified. If the number of jobs to list does not match the number of jobs specified unpredictable results may occur. If not specified, 0 will be used.

Number of message IDs in list. Specifies the number of message ids in the list. Specifying 0 for this field will list all messages available for the time, jobs, message types and severity level specified. A maximum of 100 message ids can be specified. If the number of message ids in list does not match the message ids in the list unpredictable results may occur. If not specified, 0 will be used.

Number of message types in list. Specifies the number of message types in the list. Specifying 0 for this field will list all message types available for the time, jobs, message ids and severity level specified. A maximum of 9 message types can be specified. If the number of message types in list does not match the message types in the list unpredictable results may occur. If not specified, 0 will be used.

Offset to jobs to list. The offset, in bytes, from the beginning of the message selection information format to the beginning of the jobs to list entry. Specifying 0 for this field and number of jobs to list will list all jobs available for the time, message severity, message types and message ids specified. If this is set to 0, the number of jobs to list must also be set to 0. If not specified, 0 will be used.

Offset to list of message IDs. The offset, in bytes, from the beginning of the message selection information format to the beginning of the message ids list entry. Specifying 0 for this field, message IDs list contents indicator and number of message IDs in list will list all messages available for the time, message severity, message types and jobs to list specified. If this is set to 0, the number of message ids in list must also be set to 0. If not specified, 0 will be used.

Offset to list of message types. The offset, in bytes, from the beginning of the message selection information format to the beginning of the message types list entry. Specifying 0 for this field, message types list contents indicator and number of message types in list will list all message types available for the time, message IDs, message severity and jobs to list specified. If this is set to 0 the number of message types in list must also be set to 0. If not specified, 0 will be used.

Reserved. An ignored field.

Start date. Specifies the starting date for messages and jobs to be listed. If not specified, *CURRENT will be used.

One of the following is used to specify the starting date on which or after which the data must have been logged. Any entries logged before the specified date are not listed.

*CURRENT

The logged data for the current day and between the specified starting and ending times (if specified) is listed.

*BEGIN

The logged data from the beginning of the log is listed.

start-date

The format of this field is in the CYYMMDD as follows, with the last 3 bytes of the field ignored:

C	Century, where 0 indicates years 19xx and 1 indicates years 20xx.
YY	Year
MM	Month
DD	Day

Start time. Specifies the starting time for messages and jobs to be listed. If not specified, *AVAIL will be used.

One of the following is used to specify the starting time at which or after which the data must have been logged. Any entries logged before the specified time and date are not listed.

*AVAIL

Any logged data that is available for the specified starting date is listed.

start-time

Specify the starting time for the specified starting date that indicates the logged data to be listed. The time is specified in 24-hour format and the format of this field is in the HHMMSS as follows, with the last 4 bytes of the field ignored:

HH	Hour
MM	Minute
SS	Second

Start after time microseconds. Specifies the starting times microseconds to be used. The messages listed will be listed after this time. If blank, 0 will be used.

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:

[ Back to top | Problem Management APIs | APIs by category ]