CSLULGTP: retrieving command responses directly to a REXX stem variable
By issuing the CSLULGTP request, you can retrieve command responses from IMS Operations Manager (OM) and put the command response into a REXX stem variable. The REXX program then refers to the information in the stem variable, rather than parsing XML statements as it does with the CSLULGTS request.
- stem_name
-
After the CSLULGTP request completes, the REXX stem variable is populated with the command response that is returned by OM. The REXX program can then refer to the command response for further operations.
During initialization, the REXX stem variable is set to null before being processed. Any fields that are not explicitly set as output by the CSLULGTP request will be null on return from the CSLULGTP call.
- token_name
- The name of the command and response token (CART). The token name should match the name specified on the CART subcommand.
- wait_time
A timeout value for the CSLULGTP command. The CSLULGTP command waits until the command completes, but the wait lasts only as long as the time specified. The wait time is in the format MMMMM:SS or ssssss. Enclose this value in quotes.
The maximum timeout value is 99999:59. If you do not specify a value for this parameter, the command times out after a very short delay of less than one tenth of a second.
IMS checks whether the command completed or timed out every 0.01 seconds if the value of wait_time is less than ten seconds. If the value is larger than ten seconds, IMS checks every second instead.
This timeout value is not the same as the timeout value for the WAIT subcommand; however, the value of wait_time should be at least as long as the value specified on the WAIT subcommand. Otherwise, no command response are received for long running commands.
If no response is received the first time, you can issue the CSLULGTP command again.
Intermittent results can occur when stem_name, token_name, and wait_time parameters are not coded on the CSLULGTP call.
Sample code for retrieving command responses using the CSLULGTP request
The following examples provide a code sample of the CSLULGTP request.
Example #1: In the example, the IMS command QRY TRAN NAME(A) is issued, and the CSLULGTP request is used to retrieve the command response.
Address LINK 'CSLULXSB'
Address IMSSPOC
"ims PLEX1"
"wait 5:00"
cartid = 'PROD12'
"CART" cartid
"QRY TRAN NAME(A*)"
results = cslulgtp('qinfo.', cartid,"5:00")
If qinfo.ctl.rc = 0 Then
Do
say "OM name =("qinfo.ctl.omname")"
say "command master =("qinfo.cmd.master")"
EndExample #2: This program issues the IMS UPD PGM command and processes the command responses. The following actions are taken based on the completion code:
0 - OK - say command complete for program 'program name'
10 - not found - issue CRE PGM command
73 - PSB scheduled - issue /DIS ACT REG command
other completion code - say invalid CC for program
/*-------------------------------------------------------------
| Establish IMS rexx environment. |
-------------------------------------------------------------*/
Address LINK 'CSLULXSB'
Address IMSSPOC
"IMS PLEX1"
"WAIT 5:00"
"CART CMDTOKEN"
/*---------------------------------------------------------------------------
| Issue an IMS command |
---------------------------------------------------------------------------*/
"UPD PGM NAME(APOL1,BMP255,PGMX,PGMY) SET(SCHDTYPE(SERIAL))"
/*---------------------------------------------------------------------------
| Get command responses |
---------------------------------------------------------------------------*/
spoc_rc = CSLULGTP('stem1.','CMDTOKEN',"59")
/*---------------------------------------------------------------------------
| Get some data for diag |
---------------------------------------------------------------------------*/
Say '*DATA: '
Say '*CMD issued = ' stem1.cmd.input
Say '*SPOC rc = ' spoc_rc
Say '*Command rc = ' stem1.ctl.rc
Say '*Command rsn= ' stem1.ctl.rsn
row = 1
if stem1.cmderr.0 > 0 then do
Say '*Num of errors =' stem1.cmderr.0
Say '*CMD error RC =' stem1.cmderr.row.rc
Say '*CMD error RSN =' stem1.cmderr.row.rsn
end /* if */
if stem1.rsp.0 > 0 then do
Say '*Num of rsp rows =' stem1.rsp.0
end /* if */
if stem1.rsp.0 > 0 then do
/* print each line of the stem.report */
Do n = 1 to stem1.report.0
Say stem1.report.n
End
end /* if */
say ' '
/*---------------------------------------------------------------------------
| Process responses |
---------------------------------------------------------------------------*/
spoc_rc = left(spoc_rc,2)
if spoc_rc >< '08' then do /* process response if GTP ran ok */
/*-------------------------------------------------------------
| Process the stem response if IMS return code is |
| X'00000000' or X'00000004' or X'0000000C'. |
------------------------------------------------------------*/
row = 1
imsrc = left(stem1.cmderr.row.rc,2)
If (imsrc = 00) | (imsrc = 04) | (ims.rc = 0C) then do
if stem1.RSP.0 > 0 then do
cccol = 3 /* set col num for CC */
cctxtcol = 4 /* set col num for CCtext */
do row = 1 to stem1.RSP.0
stem_cc.row = stem1.RSP.row.cccol
stem_cctxt.row = stem1.RSP.row.cctxtcol
say '*Completion code on row 'row ': 'stem_cc.row
say '*Completion code text on row 'row ': 'stem_cctxt.row
stem_cc.row = stem1.RSP.row.cccol
stem_cctxt.row = stem1.RSP.row.cctxtcol
select
/*-------------------------------------------------------------
| Process case 1 |
------------------------------------------------------------*/
when left(stem_cc.row,2) = 0 then do
say 'Command complete for program' stem1.RSP.row.1
say ' '
end
/*-------------------------------------------------------------
| Process case 2. |
| When completion code is X'10', resource not found, issue |
| a CREATE PGM command to create a program like the default |
| descriptor. |
------------------------------------------------------------*/
when left(stem_cc.row,2) = 10 then do
say 'Issue CREATE PGM command for' stem1.RSP.row.1
arg1 = stem1.rsp.row.1 /* extract pgmname to arg1 */
"CREATE PGM NAME("arg1")" /* issue CRE cmd with arg1 */
spoc_rc1 = CSLULGTP('stem2.','CMDTOKEN',"59")
if stem2.rsp.0 > 0 then do
/* print each line of the stem.report */
Do n = 1 to stem2.report.0
Say stem2.report.n
End
say ' '
end /* if */
end /* when */
/*-------------------------------------------------------------
| Process case 3 |
| When completion code is X'73', program scheduled, issue |
| a DISPLAY ACTIVE REGION command to see the active regions. |
| The region needs to be stopped and the UPD command retried. |
------------------------------------------------------------*/
when left(stem_cc.row,2) = 73 then do
say 'Program ' stem1.RSP.row.1 'is scheduled'
"/DISPLAY ACT REGION"
spoc_rc2 = CSLULGTP('stem3.','CMDTOKEN',"59")
/* print the response from each IMS */
if stem3.MSGDATA.MSG.1.0 > 0 then do
do x = 1 TO stem3.MSGDATA.NAME.0
SAY stem3.MSGDATA.NAME.X
do y = 1 TO stem3.MSGDATA.MSG.X.0
SAY stem3.MSGDATA.MSG.X.Y
end/*end do y loop */
end /* end do x loop */
end /* end if */
say 'Issue /STOP REGION commnd and retry UPD cmd'
say ' '
end /* when */
/*-------------------------------------------------------------
| For all other completion codes print the error compcode. |
------------------------------------------------------------*/
otherwise do
say 'Invalid CC for program' stem1.RSP.row.1
say ' '
end /* otherwise */
end /* select */
end /* do loop */
end /* if (imsrc = 00) | . . .*/
/*-------------------------------------------------------------
| Print IMS rc and rsn for all other error rc/rsn. |
------------------------------------------------------------*/
Else do
say '*IMS RC & RSN = ' stem1.ctl.rc stem1.ctl.rsn
end /* else */
end /* if spoc_rc >< '08' */
/*-------------------------------------------------------------
| Exit program |
------------------------------------------------------------*/
"END" /* SPOC */
EXIT /* REXX */ The say instructions in the previous example refer to elements of the REXX stem variable. The CSLULGTP request sets the suffix of the stem variable. The following table shows the possible suffix variable names that are set when the CSLULGTP request creates the stem variable.
| XML tag | Variable name |
|---|---|
| <?xml version="1.0"?> | stem.xmlversion |
| <!DOCTYPE imsout SYSTEM "imsout.dtd"> | stem.dtd |
| <imsout> | N/A |
| <ctl> | N/A |
|
stem.ctl.omname |
|
stem.ctl.omvsn |
|
stem.ctl.xmlvsn |
|
stem.ctl.statime |
|
stem.ctl.stotime |
|
stem.ctl.rqsttkn1 |
|
stem.ctl.rc |
|
stem.ctl.rsn |
|
stem.ctl.rsnmsg |
|
stem.ctl.rsntxt |
| </ctl> | N/A |
| <cmderr> | stem.cmderr.0 |
| <mbr name="membername"> | stem.cmderr.x.name |
|
stem.cmderr.x.typ |
|
stem.cmderr.x.styp |
|
stem.cmderr.x.rc |
|
stem.cmderr.x.rsn |
|
stem.cmderr.x.rsntxt |
| </mbr> | N/A |
| </cmderr> | N/A |
| <cmdsecerr> | N/A |
| <exit> | N/A |
|
stem.cmdsecerr.exit.rc |
|
stem.cmdsecerr.exit.userdata |
| </exit> | N/A |
| <saf> | N/A |
|
stem.cmdsecerr.saf.r |
|
stem.cmdsecerr.saf.racfrc |
|
stem.cmdsecerr.saf.racfrsn |
| </saf> | N/A |
| </cmdsecerr> | N/A |
| <cmd> | N/A |
|
stem.cmd.master |
|
stem.cmd.userid |
|
stem.cmd.verb |
|
stem.cmd.kwd |
|
stem.cmd.input |
| </cmd> | N/A |
| <cmdrsphdr> | N/A |
| <hdr></hdr> | |
| </cmdrsphdr> | N/A |
| <cmdrspdata> | N/A |
|
|
| </cmdrspdata> | N/A |
| <msgdata> | N/A |
| <mbr name="membername"> | |
| <msg> </msg> | |
| </mbr> | N/A |
| </msgdata> | N/A |
| </imsout> | N/A |
| N/A | |
Where the suffix variables:
- stem
- user-defined stem name
- x
- row number of command response
- y
- column number of command response
report.
msgdata instead."QRY TRAN SHOW(PSB,QCNT)"
results = cslulgtp('friday_status.', cartid,"1:30")
If friday_status.report.0 > 0 Then
Do
say friday_status.report.0
Do x = 1 to friday_status.report.0
say friday_status.report.x
End
End The program would have results like this, where each line of the stem has a line of a formatted report.
6
Response for: QRY TRAN SHOW(PSB,QCNT)
Trancode MbrName CC PSBname QCnt LQCnt
ADDINV IMS2 0 0
ADDINV IMS2 0 DFSSAM04 2
ADDINV SYS3 0 DFSSAM04 1
ADDPART IMS2 0 0 Handling errors when using the CSLULGTP function
The CSLULGTP function will not
set the ctl.rc
and ctl.rsn
stem variables if an error
is encountered in the function itself. It is therefore highly recommended
that any REXX program that uses the CSLULGTP function first check
the IMSRC and IMSREASON REXX variables before any other processing
continues to determine whether the function completed successfully.
If
the IMSRC variable is nonzero, and the error was encountered in CSLULGTP
itself, the value in IMSRC will begin with 08
. In this case,
the ctl.rc
and ctl.rsn
stem variables are not set and
no data is returned in the stem variables.
The IMSRC and IMSREASON errors that can be returned are documented in the macro CSLUXRR.
For
other errors (where the IMSRC variable is nonzero and does not begin
with 08
), the ctl.rc
and ctl.rsn
stem variables
will contain the command return code and reason code, and some of
the other stem variables are set based on the command response. For
example, if an invalid verb was entered, no command response data
will be returned, but the ctl.rc
and ctl.rsn
stem variables
as well as the REXX IMSRC and IMSREASON variables will be set.