|
The INQUIRE and SET commands allow user-written system programs to look at the information that defines a named CICS
resource (the installed definition's runtime values) and to change some of the values.
The INQUIRE and SET commands give access to the following CICS resources:
- Connections
- Definition stanza entries
- Files
- Journals
- Mode names
- Programs
- Queued requests
- Regions
- Statistics
- Tasks
- Temporary storage queues
- Terminals
- Trace activities
- Transactions
- Transient data queues
The facilities that are provided are similar to those of the CEMT transaction.
Changes to the resource attributes apply only for the duration of the current CICS session and are supported only within
the local region.
They are therefore lost when CICS is autostarted.
Although the INQUIRE and SET commands have functions that you can use in application programs, these commands are intended
primarily for user-written system programs and not for general application programs.
For example, you can use these commands to provide a customized version of CEMT.
Some INQUIRE and SET System Programming Interface (SPI) commands and some SPI options to existing INQUIRE and SET commands
support the CICSPlex(R) System Manager (CICSPlex(R) SM), which is the IBM System-390 management product for CICS
networks.
CICSPlex SM provides a single system image of the CICS regions in an enterprise, with the ability to manage those regions
from a single point of control.
The following commands enable support of this product:
The following commands have options to encompass the SPI functions.
CICS returns a null value when the functions do not apply to its platform:
The INQUIRE command also has special forms that enable you to browse all the runtime definitions that you are authorized
to access for a particular resource.
For more information, see Browsing resource definitions.
The INQUIRE and SET commands have all the advantages of other EXEC CICS commands.
In particular, they are supported by CECI, the Command Level Interpreter transaction, and by the Execution Diagnostic
Facility (EDF).
Note the following general points:
The INQUIRE command allows you to retrieve information about a single named resource.
The command also has special forms that allow you to browse all the runtime definitions that you are authorized to access
for a particular resource.
You can browse the definitions for the following resources:
- Connections
- Files
- Journals
- Programs
- Terminals
- Transactions
- Transient data queues
CICS does not attempt to retrieve definitions that you are not authorized to access.
No locking of the retrieved information occurs, which means that a definition can change at any time during the browse.
No facility is available for selective browsing; that is, for returning entries only if they meet particular conditions.
The general command format of a browse operation has the following standard pattern:
INQUIRE resource START
INQUIRE resource(data-area) NEXT
[other options same as for INQUIRE resource]
INQUIRE resource END
where resource represents the resource type (for example, PROGRAM).
Descriptions follow of each of the command forms.
The information that is given applies to all browse operations.
- INQUIRE resource START
-
This command positions an internal pointer at the first definition that you are authorized to access in the relevant CICS
resource definitions.
The command does not retrieve any information, nor does it allow you to specify a start point.
CICS allows only a one-browse of a particular resource type at any one time in a given task.
The ILLOGIC condition occurs if a browse is already in progress when an application issues an INQUIRE START command.
- INQUIRE resource (data-area) NEXT
-
The first time this command is issued, it retrieves the name and any requested attributes of the first resource definition.
On each subsequent occasion, the command retrieves the name and attributes of the next resource definition.
The END condition occurs when you have already retrieved all the definitions that you are authorized to access in the
relevant CICS resource definitions.
CICS does not change any data areas that are specified on the command. Note that the default action for the END condition
is to terminate the task abnormally, so you need to detect its occurrence.
You cannot request a selective browse of the resource definitions, and you can browse only forward.
All optional attributes that you specify are output fields only, and CICS ignores them on input.
CICS maintains a pointer to the current browse position at the transaction level.
CICS does not reset this when an application issues LINK or XCTL commands.
The ILLOGIC condition occurs if an application issues an INQUIRE NEXT command for a resource type that has had no previous
INQUIRE START command successfully issued.
- INQUIRE resource END
-
This command ends the browse and frees any held resources.
You can end a browse at any time after issuing the INQUIRE START command.
If you do not issue an INQUIRE END command, the browse terminates at the end of the transaction.
The browse is not terminated if the application issues an EXEC CICS SYNCPOINT command.
The ILLOGIC condition occurs if an application issues an INQUIRE END command for a resource type that has had no previous
INQUIRE START command successfully issued.
The following COBOL example shows a browse of the Program Definitions (PD) that retrieves the name and language of each
program that is defined in the PD.
CICS browses the complete set of PD entries, so the application issues the INQUIRE PROGRAM NEXT command until the END
condition arises, then issues the INQUIRE PROGRAM END command.
Figure 1. Browsing the Program Definitions (PD) with COBOL
If you issue an INQUIRE command to find out the value of an attribute that is not applicable to the named resource, CICS
returns a null value in the data area that you have defined.
CICS also returns a null value if the information that you have requested is not available at the time of the inquiry.
Null values depend on the format of the user-defined data area, and are defined as follows:
- Character fields are blanks.
- Binary fields are -1.
- Pointer fields are X'FF000000'.
- C programs return zero as the null value.
- CICS-Value Data Area (CVDA) fields are DFHVALUE(NOTAPPLIC). For more information,
see CICS-value data areas (CVDA).
If you issue a SET command that includes one or more null argument values, CICS ignores the corresponding attributes.
This allows the possibility of coding general SET commands in which some attributes can be left as they are, without having
to issue an INQUIRE command first to establish what the current values are.
You are most likely to want to do this when the field is defined as a CVDA.
However, in all cases, if you simply leave out an optional attribute from a SET command, CICS does not change its value.
For CVDAs on SET commands, you can code the null value as DFHVALUE(IGNORE), where IGNORE is equivalent to (and has the same
value as) NOTAPPLIC on INQUIRE commands. You code the SET command as in the following COBOL example:
WS-SYMBOLNAME = DFHVALUE(IGNORE)
EXEC CICS SET
FILE(WS-FILENAME)
READABLE
ADDABLE
DELETE(WS-SYMBOLNAME)
END-EXEC.
You can then read from, and add to, the file.
The delete status remains the same as it was before the SET FILE command was issued.
Simply leaving out the DELETE option from the command gives the same effect, but this approach lacks flexibility for
some coding conditions.
For more information about the use of CVDAs, see Appendix F, CVDAs recognized by the translator.
For other related information, see TXSeries for Multiplatforms Administration Reference.
© Copyright IBM Corp.
|
