Browsing resource definitions

The INQUIRE commands that apply to resources normally retrieve information about a single resource that you name when you issue the command. However, there is another form that enables you to browse through some or all of the definitions of a given type.

The documentation for each INQUIRE command states whether or not the browse options are supported for that resource type.

You can inquire on or browse private resources for applications deployed on platforms. For supported resource types, a CICS® resource is private if the resource is defined in a CICS bundle that is packaged and installed as part of an application, either as part of the application bundle, or as part of the application binding bundle. CICS resources of other resource types that are defined as part of applications, and CICS resources that are defined by any other methods, are publicly available for all tasks. These resources are known as public resources.

The following CICS resources are supported as private resources for applications:

LIBRARY resources, which represent one or more data sets, known as dynamic program LIBRARY concatenations, from which program load modules can be loaded.
PACKAGESET resources, which represent Db2® collections and are used to qualify which table in a Db2 database an unqualified EXEC SQL request refers to.
POLICY resources, which represent one or more rules that manage the behavior of user tasks in CICS regions.
PROGRAM resources, which represent an application program. A program that is auto-installed by a task for an application that is deployed on a platform is also private to that version of the application.

When you issue the EXEC CICS INQUIRE command, by default, CICS searches for the resources that are available to the program where the command is issued. If the command is issued from a public program, you see the public resources of that type. If the command is issued from a program that is running with an application context, you see the private resources for the current application context, and the public resources of that type. You can also choose to browse the private resources for a specific application.

How to browse resource definitions

You browse resource definitions in three steps:

Starting a browse of the resource definitions. For more information, see Starting a browse.
Retrieving the next resource. For more information, see Retrieving the next resource.
Ending the browse of the resource definitions. To do so, you issue an INQUIRE command for the resource type with just the END option:
```
INQUIRE resource-type END
```

Rules for browsing: When browsing resource definitions, mind the following rules:

Your position in a browse is associated with your task, so that it is preserved across LINK and XCTL commands. 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.
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.

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.

Exception conditions for browsing

A number of error conditions can occur on the browse forms of an INQUIRE command in addition to those conditions that apply to the single-resource form of the command.

These conditions are as follows:

APPNOTFOUND

RESP2 values:

1: A START command has been issued specifying an application context. The named application is not found.

END

RESP2 values:

2: INQUIRE NEXT has been issued, but there are no more resource definitions of the type being browsed.
8: INQUIRE NEXT has been issued, but the resource being browsed has been deleted since the start of the browse

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.