The system programming commands allow you to inquire about the
definition and status of most of the resources defined to CICS®, and about many elements of
the CICS system as well. The
resources about which you can inquire are:
- Autoinstall terminal models (AUTINSTMODEL)
- Bridge facilities used by the 3270 bridge (BRFACILITY)
- Enterprise beans (BEAN)
- Coupling facility data table server connections (CFDTPOOL)
- Connections (CONNECTION and UOWLINK)
- CorbaServers (CORBASERVER)
- DB2® connections (DB2CONN)
- DB2 entries (DB2ENTRY)
- DB2 transactions (DB2TRAN)
- DOC templates (DOCTEMPLATE)
- Deployed JAR files (DJAR)
- Exits (EXITPROGRAM)
- External data sets (DSNAME and UOWDSNFAIL)
- Files (FILE)
- Installed enterprise bean (BEAN)
- Journals (JOURNALNAME and JOURNALMODEL)
- JVMs (JVM)
- JVM profiles (JVMPROFILE)
- Log streams (STREAMNAME)
- Map sets (PROGRAM)
- Partition sets (PROGRAM)
- Partners (PARTNER)
- Pipelines (PIPELINE)
- Process type (PROCESSTYPE)
- Profiles (PROFILE)
- Programs (PROGRAM)
- Request models (REQUESTMODEL)
- Session groups (MODENAME)
- Storage
subpools (SUBPOOL)
- System dump codes (SYSDUMPCODE)
- TCP/IP services (TCPIPSERVICE)
- Temporary storage queues (TSQUEUE and TSQNAME)
- Temporary storage pools (TSPOOL)
- Temporary storage models (TSMODEL)
- Terminals (TERMINAL, NETNAME)
- Transaction classes (TCLASS, TRANCLASS)
- Transaction dump codes (TRANDUMPCODE)
- Transactions (TRANSACTION)
- Transient data queues (TDQUEUE)
URIMAP resource definitions (URIMAP)
Virtual hosts (HOST)
- Web services (WEBSERVICE)
For most resource types, the options in the INQUIRE command correspond
to specific elements in the definition of that resource. Such options
usually have the same or similar names in the INQUIRE command and
in the resource definition. Where they do not, the option text in
this manual notes the corresponding definition option. Consequently,
if you need additional information about the meaning of an option
value, it is often helpful to refer to the definition of the resource
in the CICS Resource Definition Guide.
The system elements about which you can inquire are:
- Autoinstall for terminals (AUTOINSTALL)
- Dispatcher (DISPATCHER)
- Dump data sets (DUMPDS)
- Enqueues (UOWENQ)
- Interregion communication (IRC)
- Monitor (MONITOR)
- MVS™ TCBs (MVSTCB)
- JVM pool (JVMPOOL)
- Requests (REQID)
- Shared class cache (CLASSCACHE)
- Shipped terminal status (DELETSHIPPED)
- Statistics (STATISTICS)
- Storage (STORAGE)
- System status (SYSTEM)
- Tasks (TASK, TASK LIST)
- TCP/IP (TCPIP)
- Tracing (TRACEDEST, TRACEFLAG, TRACETYPE)
- Transactional EXCI (RRMS)
- Units of work (UOW, UOWDSNFAIL, UOWENQ, UOWLINK)
- VTAM®
- Web interface (WEB)
- Work requests (WORKREQUEST)
Most of these elements correspond to system initialization parameters. If you need more information
about them, see the system initialization parameters discussion in the CICS System Definition Guide.
Certain considerations apply to all of the inquiry commands, which
are principally the INQUIREs, but also include COLLECT STATISTICS
, EXTRACT STATISTICS
and EXTRACT EXIT.
- Exception conditions: CICS returns no information when an exception condition
occurs; data-areas named in receiver options are unchanged.
- Exclusive control: A task inquiring about
a resource, system setting, or system component does not get exclusive
control of the object of the inquiry. The information returned may
be changed by another task or system event at any time. The
resource currently being inquired on should not be deleted since the
current resource is used to position to the next resource on a subsequent
GETNEXT command. Only after the subsequent GETNEXT command can the
resource be deleted, since it is no longer required for positioning
within this browse request.
- Browsing: Resources defined in the first
(resource) list can be retrieved sequentially, as explained in Browsing resource definitions.
- Inapplicable options: If you specify a receiver
option that does not apply to the resource about which you are inquiring, CICS generally returns the appropriate "null
value", as defined in Null values. (In a few cases,
an exception is raised; these cases are noted in the command descriptions.)
For
example, if you include BLOCKFORMAT in an INQUIRE TDQUEUE command
that specifies an intrapartition transient data queue, CICS returns the value NOTAPPLIC
to the CVDA you provide, because BLOCKFORMAT is valid for extrapartition
queues only.
The INQUIRE commands that apply to resources ordinarily retrieve
information about a single resource that you
name when you issue the command, and the individual command syntax
discussions in the next section describe them in this form.
However, there is another form that enables you to browse through
some or all of the definitions of a given type. The resource types
that you are allowed to browse are those in the first list in Inquiry commands, plus requests (REQIDs) and units of work (UOWs,
UOWDSNFAILs, UOWENQs, and UOWLINKs).
A browse involves three steps. First, you issue the INQUIRE command
with an additional option, START, to set up the browse. This command
does not produce any information; it just tells CICS what you are going to do. The general form
of the command is:
Browse START
INQUIRE resource-type START
In addition to the START option, there are several differences
in the way you issue this setup command from the normal syntax:
- You identify the resource type only, without providing a resource
name; that is, the resource type appears without its customary data-value.
- You omit all of the options in which CICS returns information to you.
- You also omit options that send information to CICS, other than the resource type. (INQUIRE EXITPROGRAM
and INQUIRE UOWENQ are exceptions to this rule; you can limit the
browse by supplying additional information on the START, as explained
in the descriptions of these commands.)
Generally, CICS returns
resource definitions to you in the order it keeps them internally.
You cannot control this order, and you should not depend on it always
being the same. For a few resource types, however, CICS returns definitions in alphabetic order of
resource name. These are:
- DB2ENTRYs and DB2TRANs
- Programs, map sets, and partition sets
- Temporary storage queues
- Transactions
- Transaction classes
For these resources only, you can specify a starting point for
the browse with the AT option on the INQUIRE START:
START browse AT
INQUIRE resource-type START AT(data-value)
The AT data-value is the name at which you want to start. It must
be in the correct format for a name of the resource type being browsed,
but it does not have to correspond to an installed resource; it is
used only to start the browse at the proper point in the resource
list. CICS restricts the definitions
that it returns on your INQUIRE NEXT commands to resources with names
equal to or greater (in the collating sequence) than the value you
provide.
JVM profiles are also returned in alphabetic order
of resource name, but you cannot use the AT option with the INQUIRE
JVMPROFILE START command.
In the second step of a browse, you issue the INQUIRE command repetitively
with another new option, NEXT. CICS returns
one resource definition for each INQUIRE NEXT. The general format
is:
Browse NEXT
INQUIRE resource-type(data-area) NEXT option...option
Apart from the addition of NEXT, the options are almost the same
on an INQUIRE NEXT as on a single INQUIRE for the same type of resource.
Again, however, there are some differences:
- Instead of specifying the name of the resource (a data-value),
you provide a data-area of the same length for CICS to return the name of the
next resource to you.
- Options by which CICS returns
data to you are used in the same way as on the single-resource form.
- A few options, such as the CONNECTION option on INQUIRE MODENAME,
change their roles in a browse. These differences also are noted in
the commands to which they apply.
You repeat the INQUIRE NEXT command until you have seen the resource
definitions you want or have exhausted the definitions. After you
have retrieved the last of them, CICS raises
the END condition on subsequent INQUIRE NEXTs, leaving any data-areas
you provided unchanged. However, you do not have to retrieve all the
definitions; you can stop the browse at any time.
Stopping the browse is the final step. To do so you issue an INQUIRE
for the resource type with just the END option, thus:
Browse END
INQUIRE resource-type END
Here is an example of a typical browse sequence. This code retrieves
the names of all the files installed in the system and calls a subroutine
to process information about the recovery characteristics if the file
is open.
EXEC CICS INQUIRE FILE START END-EXEC.
PERFORM UNTIL RESPCODE = DFHRESP(END)
EXEC CICS INQUIRE FILE(FILENAME) NEXT
OPENSTATUS(OPENSTAT)
RECOVSTAT(RCVRSTAT)
FWDRECSTATUS(FWDSTAT)
RESP(RESPCODE) END-EXEC
IF RESPCODE = DFHRESP(NORMAL)
IF OPENSTAT = DFHVALUE(OPEN)
CALL RCVY-RTN USING RCVRSTAT FWDSTAT
END-IF
ELSE CALL ERROR-RTN END-IF
END-PERFORM.
EXEC CICS INQUIRE FILE END END-EXEC.
In addition to the syntax changes described above, there are some
rules you should note about browsing resource definitions:
- Your position in a browse is associated with your task, so that
it is preserved across LINK and XCTL commands.
Note:
Programs
that run as part of a program list table (PLT) during CICS initialization or termination
run under a single task. Consequently, they should terminate explicitly
any browse they begin, in order not to conflict with other programs
in the same PLT.
- A task can browse more than one type of resource at the same time,
but can have only one browse in progress for a particular resource
type.
- A SYNCPOINT command does not end a browse or affect your position
in it.
- Resource definitions are not locked during a browse, and another
task may change the definitions while you are inquiring on them.
- Nonetheless, you should always end a resource browse explicitly,
rather than allowing end-of-task processing to do so implicitly, because
a browse holds control blocks that other tasks may require for browsing.
- INQUIRE NEXT commands usually do not cause a task switch. Therefore,
a task browsing a long list of resources may exceed the runaway task
interval without giving up control, causing CICS to abend it with an AICA code. If this occurs,
you need to intersperse a SUSPEND command periodically among your
INQUIRE NEXTs.
- During a browse in a task for which resource security checking
is in effect, CICS returns
only those definitions that the user is authorized to see. The others
are skipped without any indication.
Two conditions can occur on the browse forms of an INQUIRE command,
in addition to those that apply to the single-resource form of the
command:
- END
- RESP2 values:
- 2
- INQUIRE NEXT has been issued, but there are no more resource
definitions of the type being browsed.
- ILLOGIC
- RESP2 values:
- 1
- A START has been given when a browse of the same resource type
is already in progress, or a NEXT or an END has been given without
a preceding START.
You can change most of the system elements and resource definitions
about which you can inquire, although in general you cannot change
as many option values as you can retrieve. Changes are made with a
SET command naming the resource or system element.
Like the INQUIRE commands, SET commands follow some general rules:
- Exceptions: When a SET command results in
an exception condition, CICS makes
as few of the requested changes as possible. To establish which, if
any, changes have been made, you can issue the corresponding INQUIRE
command.
- Permanence: If you change a system setting
or resource definition element that is ordinarily recorded in the CICS global catalog, the change
is also recorded in the catalog and thus preserved over a warm or
emergency restart. If the information is not ordinarily recorded,
it lasts only for the current execution of CICS. In a cold or initial start, the catalog information
is discarded and all effects of earlier SET commands are lost.
- Recoverability: SET commands are not recoverable.
Their effects are not backed out if the task that issued them abends
or issues a SYNCPOINT ROLLBACK command. Consequently, SET commands
do not lock resources, and you do not need to precede a SET with the
corresponding INQUIRE command.
- "No change" values: Except where there
is a default value for an option, CICS does
not change the value associated with an option that you omit. However,
there is a second way to indicate that you want no change. If you
specify the null value in a sender option that is not required, CICS leaves the option value unchanged.
Although you can get the same effect by omitting the option if there
is no default, the ability to specify a "no change" value allows
you to vary the options in a command as well as the option values,
simplifying your code in some situations.
For example, suppose
you needed to change many different combinations of options, depending
on the outcome of some calculations. Your code might look something
like this:
IF ... MOVE DFHVALUE(NOTDELETABLE) TO DEL
ELSE MOVE DFHVALUE(IGNORE) TO DEL.
IF ... MOVE 2 TO POOL
ELSE MOVE -1 TO POOL.
IF ... MOVE 'TAXID.MASTER' to DSN
ELSE MOVE SPACES TO DSN.
EXEC CICS SET FILE('TAXMSTR ') DELETE(DEL)
LSRPOOLID(POOL) DSNAME(DSN) END-EXEC.
See Null values for more about null values.
Note:
There
are a few options, such as the NEXTTRANSID option in a SET TERMINAL
command, for which blanks (the null value for a character field) are
a meaningful value. For these options, there is no null value, and
you must omit the option if you do not want to change its value; these
cases are noted in the option descriptions.
[[ Contents Previous Page | Next Page Index ]]