XML tags returned as CSL OM responses

Different XML tags can be returned as CSL OM responses. Each tag name is delimited by the characters < and >. Tags can be nested within parent tags to encapsulate related information.

Data or other sets of tags are contained between these start and end tags. In the list of tags, indentation indicates that the tags are nested within the parent tags.

<?xml version "1.0"?>

The version of XML used in this output.

<!DOCTYPE imsout SYSTEM "imsout.dtd">

The DOCTYPE tag identifies the file that contains the document type definition (DTD). The DTD describes the structure that is supported for this type of XML document. Users of z/OS® can find the DTD information in the CSLOMDTD member, located in the IMS™.SDFSRESL data set.

<imsout> </imsout>

The <imsout> </imsout> tags encapsulate the output from OM. These tags are returned on every request.

<ctl> </ctl>

The <ctl> </ctl> tags encapsulate the control information that is returned by OM. These tags are returned on every request and include the following control information:

<omname>om name</omname>: Indicates the name of the OM that processed this request. The name is specified on the OMNAME= execution parameter of the CSLOIxxx PROCLIB member.
<omvsn>om version number</omvsn>: Indicates the OM version number.
<xmlvsn>xml version number</xmlvsn>: Indicates the XML version number.
<statime>starttime</statime>: Indicates the time that OM started processing the request. The field is in the following format: yyyy.ddd hh:mm:ss.th
<stotime>stoptime</stotime>: Indicates the time that OM completed request processing. The field is in the following format: yyyy.ddd hh:mm:ss.th
<staseq>startsequence</staseq>: Indicates the sequence value when OM started processing the request. This value can be used for sorting and is in printable EBCDIC hexadecimal format.
<stoseq>stopsequence</stoseq>: Indicates the sequence value when OM stopped processing the request. This value can be used for sorting and is in printable EBCDIC hexadecimal format.
<rqsttkn1>requesttoken1</rqsttkn1>: Indicates the user-specified RQSTTKN1 value that is associated with the response. OM converts unprintable characters to periods (.) in the output.
<rqsttkn2>requesttoken2</rqsttkn2>: Indicates the user-specified RQSTTKN2 value that is associated with the response. OM converts unprintable characters to periods (.) in the output.
<rc>returncode</rc>: The return code for the request in printable EBCDIC hexadecimal format.
<rsn>reasoncode</rsn>: The reason code for the request in printable EBCDIC hexadecimal format.
<uom>unsolicited output message</uom>: Indicates that the XML is for an unsolicited output message

<cmdclients> </cmdclients>

Encapsulates information about OM clients. These tags can be returned on a QUERY(CMDCLIENTS) request.

<mbr name="membername"></mbr>

Indicates the name of the IMSplex member that is registered for commands.

<typ>membertype</typ>: Indicates the type of IMSplex member.
<styp>membersubtype</styp>: Indicates the IMSplex member subtype. OM converts unprintable characters to periods (.) in the output.
<vsn>memberversion</vsn>: Indicates the member version number.
<jobname>memberjobname</jobname>: Indicates the member job name.

<cmddtd> </cmddtd>

Encapsulates the Document Type Definition (DTD) that are defined by OM for command syntax and OM output XML. These tags can be returned on a QUERY(CMDSYNTAX) request.

<cmdsyntax> </cmdsyntax>

Encapsulates the XML definitions for the commands that are registered to OM from all of its clients. These tags can be returned on a QUERY(CMDSYNTAX) request.

<cmdtext> </cmdtext>

Encapsulates the translatable text strings that are associated with the XML command syntax tags. These tags can be returned on a QUERY(CMDSYNTAX) request.

<cmd> </cmd>

Encapsulates the command information that was passed to OM. These tags can be returned on a command request. The output returned in these tags is what was provided on the CMD= parameter on the CSLOMBLD macro. The following tags are included within the <cmd> tags:

<master> </master>

Encapsulates the name of the command processing client that was tagged as the master when sending the command. This information will not be present unless the command was successfully sent to at least one command processing client.

<userid> </userid>

Encapsulates the user ID of the originator of the command.

<verb> </verb>

Encapsulates the short form of the command verb that was processed by OM. The verb might have been passed to OM in a long form.

<kwd> </kwd>

Encapsulates the command keyword that was processed by OM.

<input> </input>

Encapsulates the actual input command string that was passed to OM. The following characters are converted to periods (.) to maintain the validity of the output XML:

Greater than signs (>)
Less than signs (<)
Ampersands (&)
Non-printable characters

<cmdrsphdr> </cmdrsphdr>

Encapsulates the command header information that describes the data fields returned in the command response. These tags can be returned on a command request.

<hdr ... />

Defines the attributes of columns of data fields.

The command response header information is in the format shown in the following format example:

<hdr slbl="ss" llbl="llll" scope="c" sort="d" key="e" scroll="f" len="g" dtype="h" align="i" skipb="no"/>

slbl

Short label used to match data description with data value that is returned by the <cmdrspdata> tag.

The short label values vary by command. Refer to the documentation for each command to determine what values can be returned for a specific command.

llbl

Long label that can be used as the table column header.

The long label values vary by command. Refer to the documentation for each command to determine what values can be returned for a specific command.

scope

Indicates if the data is global or local.

GBL: Indicates that the data is global. For query output, global data applies to all resources of the same name, but is returned only once in the command response for a specific resource name. Global information applies to other rows of the same resource name for different IMSplex member names. The resource name is the data field identified by a KEY="1" attribute. If an application chooses to transform the command response data into a table to be displayed for a user, the global data value can be propagated to other rows for the same resource name.
LCL: Indicates that the data is local. For query output, local data applies only to a specific resource name in a specific IMS. Different IMS systems can return different values for local data fields. Each IMS returns its local value when it is available. If an application chooses to transform the command response data into a table to be displayed for a user, the local data value should not be propagated to other rows for the same resource name.

sort

Indicates whether or not this field should be sorted or the sort direction.

A: Sort in ascending order.
D: Sort in descending order.
N: Do not sort field.

key

Indicates the sort priority for this field.

0: Field is not sorted.
1: The highest priority sort field.
2: The second highest priority sort field.
n: The n the priority sort field.

The priority value indicated on KEY= in the <cmdrsphdr> tag has been predetermined. Some command responses can specify multiple sort fields. Several fields are listed within the <cmdrsphdr> tags with their sort priorities:

Trancode - 1
MbrName - 4
CC - 0
PSBname - 0
QCnt - 2
LCls - 0
LQCnt - 3

The following code example causes the command results to be sorted with the following priority:

Trancode
Qcnt
LQcnt
MbrName

<?xml version="1.0"?>
<!DOCTYPE imsout SYSTEM "imsout.dtd">
<imsout>
<ctl>
<omname>OM1OM   </omname>
<omvsn>1.1.0</omvsn>
<xmlvsn>1   </xmlvsn>
<statime>2002.261 18:33:56.425140</statime>
<stotime>2002.261 18:33:56.487941</stotime>
<staseq>B8400987409B4A0E</staseq>
<stoseq>B84009874FF05409</stoseq>
<rqsttkn1>USRT002 10113356</rqsttkn1>
<rc>00000000</rc>
<rsn>00000000</rsn>
</ctl>
<cmd>
<master>IMS2    </master>
<userid>USRT002 </userid>
<verb>QRY </verb>
<kwd>TRAN            </kwd>
<input>QRY TRAN NAME(ADD*) SHOW(PSB,QCNT,CLASS) </input>
</cmd>
<cmdrsphdr>
<hdr slbl="TRAN" llbl="Trancode" scope="LCL" sort="a" key="1" 
scroll="no" len="8" dtype="CHAR" align="left" />
<hdr slbl="MBR" llbl="MbrName" scope="LCL" sort="a" key="4" 
scroll="no" len="8" dtype="CHAR" align="left" />
<hdr slbl="CC" llbl="CC" scope="LCL" sort="n" key="0" 
scroll="yes" len="4" dtype="INT" align="right" />
<hdr slbl="PSB" llbl="PSBname" scope="LCL" sort="n" key="0" 
scroll="yes" len="8" dtype="CHAR" align="left" />
<hdr slbl="Q" llbl="QCnt" scope="GBL" sort="d" key="2"
scroll="yes" len="8" dtype="INT" align="right" />
<hdr slbl="LCLS" llbl="LCls" scope="LCL" sort="n" key="0" 
scroll="yes" len="3" dtype="INT" align="right" />
<hdr slbl="LQ" llbl="LQCnt" scope="LCL" sort="d" key="3" 
scroll="yes" len="8" dtype="INT" align="right" /></cmdrsphdr>
<cmdrspdata>
<rsp>TRAN(ADDPART ) MBR(IMS2    ) CC(   0) PSB(DFSSAM04) LCLS(  4)      
LQ(   0) </rsp>
<rsp>TRAN(ADDINV  ) MBR(IMS2    ) CC(   0) PSB(DFSSAM04) LCLS(  4)      
LQ(   0) </rsp>
<rsp>TRAN(ADDPART ) MBR(IMS2    ) CC(   0) Q(    0) </rsp>
<rsp>TRAN(ADDINV  ) MBR(IMS2    ) CC(   0) Q(    0) </rsp>
<rsp>TRAN(ADDPART ) MBR(SYS3    ) CC(   0) PSB(DFSSAM04) LCLS(  4)      
LQ(   0) </rsp>
<rsp>TRAN(ADDINV  ) MBR(SYS3    ) CC(   0) PSB(DFSSAM04) LCLS(  4)      
LQ(   3) </rsp>
</cmdrspdata>
</imsout>

If two records have the same Trancode, they are sorted by Qcnt. If they also have the same Qcnt, they are sorted by LQcnt. If they have the same LQcnt value, they are sorted by MbrName, and so on, until the n^th sort field is used.

The results of the XML in the previous code are displayed in the following code sample.

Response for: QRY TRAN NAME(ADD*) SHOW(PSB,QCNT,CLASS)

Trancode MbrName    CC PSBname      QCnt LCls    LQCnt
ADDINV   IMS2        0                 0              
ADDINV   SYS3        0 DFSSAM04             4        3
ADDINV   IMS2        0 DFSSAM04             4        0
ADDPART  IMS2        0                 0              
ADDPART  IMS2        0 DFSSAM04             4        0
ADDPART  SYS3        0 DFSSAM04             4        0

Depending on which fields were selected using the SHOW parameter of the QUERY command, not all intermediate priority value fields will be displayed. That is, the results could display fields whose priority values were set at 1 and 4, but not display fields whose priority values were set at 2 and 3. A program might leave the records in the original order, sort them using the predetermined priority values, or sort by other fields using criteria set locally by the user.

scroll

Indicates whether this field is scrolled off of the screen when TSO SPOC shifts the screen to the right.

NO: Do not scroll the field.
YES: Allow the field to scroll off the screen.

len

Maximum length of data (data returned could contain fewer characters). If a table of data is being created from the output response, this value can be used to determine the width of the column that is displayed for this attribute. If the value for this field is '*', this is a variable length field.

dtype

Describes the original data type. All data is returned in character format. However, some fields represent numeric data. Data that originated as integer might need to be converted from character to integer in order to perform mathematical calculations.

CHAR: The output field represents character data.
INT: The output field is the character representation of integer data.

align

Indicates recommended column alignment if data is to be formatted into columns.

RIGHT: Data is right-aligned, for example, numeric data.
CENTER: Data is centered.
LEFT: Data is left-aligned, for example, character data.

skipb

no: The column is displayed on the TSO SPOC output, even if no client returned any information for this column. This is the default.
yes: The column is not displayed on the TSO SPOC output if no client returned any information for this column.

<cmdrspdata> </cmdrspdata>

Encapsulates the command response detail information. These tags can be returned on a command request. The tags contain the actual data that is described by the <cmdrsphdr> </cmdrsphdr> tags.

Refer to the documentation for each command to determine what values can be returned for a specific command.

<rsp>response data</rsp>

Contains a logical line of command response output for a particular resource. The response data contains various tags in the form name(value). The name maps to short label (slbl=) values in the <hdr> tag. This is shown in the following example, with the values TRAN and PSB.

<cmdrsphdr>
<hdr slbl="TRAN"    llbl="Trancode"... />
<hdr slbl="PSB"     llbl="PSBname" ... />
</cmdrsphdr>
<cmdrspdata>
<rsp>TRAN(A        ) PSB(A11      ) </rsp>
<rsp>TRAN(B        ) PSB(B22      ) </rsp>
<rsp>TRAN(C        ) PSB(C33      ) </rsp>
</cmdrspdata>

The <hdr> tag includes a long label value (llbl=), which can be used as column headings. This is shown in the following output example, specifically Trancode and PSBname.

Trancode  PSBname
A         A11
B         B22
C         C33

The values included in the response data propagate the data columns of the SPOC output. Other tags in the <hdr> tag describe formatting attributes for values in that column.

<msgdata> </msgdata>

Encapsulates pre-built IMS messages. The messages can be of any type including informational, warning, or error messages. These tags can be returned on a command request.

<mbr name="membername"></mbr>

Indicates the name of the IMSplex member that returned the message.

<msg>message data</msg>: Contains a logical command response output for a resource in a message format. The message starts with a message number (for example, DFSnnnnI). There is no LL field or X'15' new line character.

<cmderr> </cmderr>

Encapsulates the return and reason code information returned by OM or a command processing client. These tags are returned on command requests when an error specific to a command processing client must be returned. For each IMSplex member with an error, the following information is returned.

<mbr name="membername"></mbr>

Indicates the name of the IMSplex member for which an error was detected.

<typ>membertype</typ>: Indicates the type of IMSplex member.
<styp>membersubtype</styp>: Indicates the IMSplex member subtype. OM converts unprintable characters to periods (.) in the output.
<rc>returncode</rc>: Indicates the return code for the IMSplex member in printable EBCDIC hexadecimal format.
<rsn>reasoncode</rsn>: Indicates the reason code for the IMSplex member in printable EBCDIC hexadecimal format.

<cmdsecerr> </cmdsecerr>

Encapsulates the return and reason code information returned by the OM security exit, SAF and RACF®, or equivalent. If the OM security exit rejected the command for any reason, the user data from the security exit is also encapsulated here.

<exit> </exit>

Encapsulates the return code and user data from the OM security exit.

<rc>returncode</rc>: Indicates the return code from the OM security exit in printable EBCDIC hexadecimal format.
<userdata>userdata</userdata>: Indicates the user data returned from the OM security exit in the OSCX_USERDATA field of the OM Command Security user exit parameter list (CSLOSCX). OM converts unprintable characters to periods (.) in the output.

<saf> </saf>

Encapsulates the return and reason codes from the SAF and RACF or an equivalent.

<rc>returncode</rc>: Indicates the return code from the SAF in printable EBCDIC hexadecimal format.
<racfrc>racfreturncode</racfrc>: Indicates the return code from RACF or equivalent security product in printable EBCDIC hexadecimal format.
<racfrsn>racfreasoncode</racfrsn>: Indicates the reason code from RACF or equivalent security product in printable EBCDIC hexadecimal format.