CICS QUERY
This command invokes MainView for CICS interactive services, such as SUMMARY, MONITOR, PROBLEM, SUBPOOL, and so on.
Command | Parameters |
|---|---|
CICS QUERY | Command |
QUERY is executed on behalf of the target CICS system. When QUERY is used, data normally sent to the terminal is written into variables that the EXEC can analyze. The output returned from the command is written into the LOCAL variables LINE1 through LINExx, which correspond to the lines of the screen image.
The variable IMFNOL contains the number of lines of output. These variables need to be retrieved using the VGET statement before they can be used.
The output is similar to output produced through the same service of a MainView for CICS terminal session, but this output does not have screen attributes in the variables. The returned data does not contain the header lines, which are displayed when invoking the service under the TS (unless they contain variable data).
Some applications that are accessible through the QUERY command are scrollable applications and therefore need to be accessed more than once to retrieve all the data. For all scrollable applications, except the TASK display, a parameter is passed to the QUERY command that contains the resource name of the last resource on the screen. This action causes the data to be returned, starting with the resource specified by the parameter. To return all of the data for the TASK display, a special parameter (/FWDnnnn, where nnnn is a numeric value) is provided. The Exec should test the variable that contains the number of lines returned (IMFNOL), and if at least 23 lines were returned, an attempt is made to scroll forward by using the /FWDnnnn parameter on subsequent calls. See Example 1.
You might need to experiment with the correct offsets to use when sub-stringing particular items. Changes to MainView for CICS display formats might affect EXECs that process this data.
For most MainView for CICS services, two header lines are omitted before the data is returned in the LOCAL variables. There are some exceptions to this standard.
One exception is those services that contain variable data in one of the header lines. For these services, the header line containing the variable data and all subsequent lines are returned.
Another exception is those services which contain either one or two blank header lines. For these services, the header lines are not returned at all. However, all blanks that might be interspersed within the detail lines of a specific display are passed to the EXEC. You must accommodate for these lines in the EXEC.
The following table describes the parameters:
Parameter | Function | Notes |
|---|---|---|
Command | a MainView for CICS service request, referred to in format descriptions in the MainView for CICS Online Services Reference Manual | No quotation marks are required around this operand. |
Example 1
This example demonstrates how to use the QUERY command to gather CICS subpool information.
A brief discussion follows the example.
REXX EXEC example:
'IMFEXEC CICS QUERY SUBPOOL'
/* DSA PERCENTAGE IS NOW IN MSG #2, COLUMNS 14-16 */
'IMFEXEC VGET LINE2 LOCAL'
DSAPERC = SUBSTR(LINE2,14,2)
IF DSAPERC < 50 THEN CALL LOKAY
CLIST example:
/* DSA PERCENTAGE IS NOW IN MSG #2, COLUMNS 14-16 */
IMFEXEC VGET LINE2 LOCAL
SET DSAPERC = SUBSTR (14:16,LINE2)
IF DSAPERC < 50 THEN GOTO LOKAY
This sample command shows an EXEC that interprets the DSA utilization percentage. This command could be used to influence decisions that are made within an EXEC that is scheduled when message FT041S (task using excessive storage) is issued.
Example 2
This example demonstrates how to use the QUERY command to gather data from a scrollable application (other than the Task display). This EXEC is called from the BBI journal or another EXEC or Rule.
Example from the BBI journal: %CICSFILE CICSPROD
/* REXX exec to count the number of files with zero updates */
/* and return a message to the BBI journal indicating that */
/* number. */
/*-------------------------------------------------------------*/
arg name region pad
'IMFEXEC SETTGT ''region'''
count = '0' /* Init counter */
lastscreen = 0 /* Init flag */
notfirst = 0 /* Set first call */
fname = '' /* Null for first call */
'IMFEXEC VDCL FILEDATA LIST(name type status lsr read add update',
'getupd browse delete)' /* Set up variable list */
do until lastscreen
'IMFEXEC CICS QUERY FILE' fname'' /* Get 1st/next scrn */
do i = 1 to IMFNOL
if notfirst & i = 1 then nop
else
do
'IMFEXEC VGET LINE'i' INTO(FILEDATA) LOCAL'
/* Check each line */
if IMFCC /= '0000' then
leave /* If VGET prob, stop */
if update = '0' then /* The one I want? */
count = count + 1 /* Y, count it */
end
end
if imfnol < 23 then
lastscreen = 1
fname = name /* Set cursor position */
notfirst = 1 /* No longer first call */
end
'IMFEXEC MSG 'CICSFILE: There are' count' files with 0 updates.''
exit
CLIST example:
/*-------------------------------------------------------------*/
/* Clist exec to count the number of files with zero updates */
/* and return a message to the BBI journal indicating that */
/* number. */
/*-------------------------------------------------------------*/
IMFEXEC SETTGT '&STR(®ION)' /* Set region name */
SET COUNT = 0 /* Init counter */
SET LASTSCREEN = &STR(NO) /* Remember location */
SET FNAME = &STR() /* Null for first call */
SET NOTFIRST = &STR(NO) /* Set first call */
IMFEXEC VDCL FILEDATA LIST(NAME TYPE STATUS LSR READ ADD UPDATE +
GETUPD BROWSE DELETE) /* Set up variable list */
DO UNTIL &STR(&LASTSCREEN) = &STR(YES)
IMFEXEC CICS QUERY FILE &FNAME /* Get 1st/next scrn */
SET I = 1 /* Init loop counter */
DO WHILE (&I LE &IMFNOL)
IF &STR(&NOTFIRST) = &STR(YES) AND &I = 1 THEN +
DO
END
ELSE +
DO
IMFEXEC VGET LINE&I INTO(FILEDATA) LOCAL
/* Check each line */
IF &IMFCC NE &STR(0000) THEN +
GOTO ENDLOOP /* If VGET prob, stop */
IF &UPDATE = &STR(0) THEN +
SET &COUNT = &COUNT + 1 /* If so, count it */
END
SET &I = &I + 1 /* Bump up counter */
END
Example 3
This example demonstrates how to use the QUERY command to gather data from the TASK display. This EXEC is called from the BBI journal or another EXEC or Rule.
Example from the BBI journal: %CICSTASK CICSPROD CEMT
/* REXX exec to count the number of tasks running a particular */
/* transaction in CICS and return a message to the BBI journal */
/* indicating that number. */
/*-------------------------------------------------------------*/
arg name region tran pad
'IMFEXEC SETTGT ''region'''
scroll = '0' /* Init scroll count */
count = '0' /* Init counter */
lastscreen = 0 /* Init flag */
do until lastscreen
'IMFEXEC CICS QUERY TASK * * /FWD'scroll'' /* Get 1st/next scrn */
do i = 1 to IMFNOL
'IMFEXEC VGET LINE'i' LOCAL' /* Check each line */
if IMFCC /= '0000' then
leave /* If VGET prob, stop */
if substr(value(line||i),8,4) = tran then
/* The one I want? */
count = count + 1 /* Y, count it */
end
if imfnol < 23 then
lastscreen = 1
scroll = scroll + 23 /* Set scroll amount */
end
'IMFEXEC MSG 'CICSTASK: There are' count' tasks running' tran'.''
exit
CLIST example:
/*-------------------------------------------------------------*/
/* Clist exec to count the number of tasks running a particular*/
/* transaction in CICS and return a message to the BBI journal */
/* indicating that number. */
/*-------------------------------------------------------------*/
IMFEXEC SETTGT '&STR(®ION)' /* Set region name */
SET &SCROLL = 0 /* Init scroll amount */
SET &COUNT = 0 /* Init counter */
SET &LASTSCREEN = STR(NO) /* Remember location */
SET &I = 1 /* Init loop counter */
DO UNTIL &STR(&LASTSCREEN) = &STR(YES)
IMFEXEC CICS QUERY TASK * * /FWD&SCROLL /* Get 1st/Next screen */
DO WHILE (&I LE &IMFNOL)
IMFEXEC VGET LINE&I LOCAL /* Check each line */
SET OUTLINE = &SYSNSUB(2,&&LINE&I)
IF &STR(&IMFCC) NE &STR(0000) THEN +
GOTO ENDLOOP /* If VGET prob, stop */
/* The one I want? */
IF &SUBSTR(8:11,&STR(&OUTLINE)) = &STR(&TRAN) THEN +
SET &COUNT = &COUNT + 1 /* Y, COUNT IT */
SET &I = &I + 1 /* Bump up counter */
END