Inquiry commands

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:

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:

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 STATISTICSStart of change, EXTRACT STATISTICSEnd of change and EXTRACT EXIT.

Browsing resource definitions

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).

Starting a browse

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:

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:

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.

Retrieving the next resource

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:

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.

Ending the browse

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

Browse example

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.

Rules for browsing

In addition to the syntax changes described above, there are some rules you should note about browsing resource definitions:

  1. 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.
  2. 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.
  3. A SYNCPOINT command does not end a browse or affect your position in it.
  4. Resource definitions are not locked during a browse, and another task may change the definitions while you are inquiring on them.
  5. 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.
  6. 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.
  7. 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.

Exception conditions for browsing

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.

SET commands

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:

[[ Contents Previous Page | Next Page Index ]]