Browsing and inquiry commands

Important:
The API commands described here are different in kind from the commands described previously in this section.

The commands described previously in this section are the basic commands used by application programmers to create BTS applications.

The commands described here have more specialized uses. They might be used, for example, in a utility program written to investigate a stuck process. A typical BTS business application should not need to inquire on or browse the objects it creates, and therefore will not use these commands.

CICS® business transaction services provide a set of commands that enable programs to search for and examine BTS objects. These commands can be summarized as:

Browsing commands
Used to locate BTS objects, and to retrieve some or all of their attributes.
Inquiry commands
Used to retrieve the attributes of specific BTS objects (which may have been located by browsing).

The object-identifiers and names retrieved from the browsing or inquiry commands can be specified on a subset of the other BTS API commands. This allows actions to be started against specified activities, processes, and data-containers.

Browsing commands

The browsing commands allow BTS objects to be located and their relationships to each other examined. The objects that can be browsed are:

Each browse has three commands associated with it:10

STARTBROWSE
STARTBROWSE:
  1. Tells CICS to begin a browse of a specified type of BTS object.
  2. Defines the scope of the browse. In most cases, 11 an absence of additional arguments indicates that the browse is to have the scope of the current activity.
  3. Returns a browse token which must be included on the remaining commands within the browse.
GETNEXT
Locates the next object within the scope of the browse, or returns the END condition if there are no more to be found.

GETNEXT always returns sufficient information to allow additional actions to be taken. For example, in a browse of the children of a specified parent activity, the GETNEXT ACTIVITY command returns both the name and the identifier (ACTIVITYID) of the next child activity that it finds. The name could be used to decide where the current browse should be paused. The identifier could be used to start a new browse--which might be of the child activity’s containers, for instance.

ENDBROWSE
Ends the browse.

Inquiry commands

A program can get details of a specific BTS object by issuing an INQUIRE command. You can inquire on:

The object inquired upon may have been located by browsing. For example, a program can use a browse to locate an activity, then issue an INQUIRE ACTIVITYID command to find out the name of the program associated with the activity, the userid under whose authority it runs, or its current completion status.

Note:
All INQUIRE commands try to locate a record on a BTS repository data set, and to read information from it if found. This operation does not obtain an exclusive control lock for the record; therefore the data in the record may change while the operation is taking place.

Be careful when issuing INQUIRE commands from within programs that execute as part of an activity, if the commands refer to records which may be modified by the same program. The INQUIRE command always goes to the repository for the record it needs, and may not see changes made by the program. This can lead to unexpected results. For example, a program might define a new activity and then issue a command to inquire upon it, only to be told that the activity does not exist (because the activity-record has not yet been committed to the repository).

Tokens and identifiers

A browse token uniquely identifies a browse within a CICS region. The same token returned on a STARTBROWSE command must be supplied on the corresponding GETNEXT and ENDBROWSE commands. CICS discards it after the ENDBROWSE.

The lifetime of a browse token is from a STARTBROWSE to an ENDBROWSE or syncpoint, whichever comes first. Therefore, your applications:

An activity identifier is a means of uniquely referring to an instance of an activity that has been retrieved from a BTS repository data set. Once an activity identifier or a process name is known, it can be used as a scoping argument to a new browse. It can also be specified on certain API commands which cause actions to be taken against existing activities or processes, or their containers and events--see Commands which take identifiers returned by browse operations. The lifetime of an activity identifier is the same as that of the activity it refers to. Thus, it can be used after an ENDBROWSE and after a syncpoint.

A data-container or an event cannot be identified in the same way as an activity or a process, because it forms part of a record on a BTS repository data set. Instead, it must be referenced through the activity or process to which it belongs.

Commands which take identifiers returned by browse operations

It is essential that the systems programmer should be able to modify a business transaction after it has started. This is particularly important if the transaction gets into a state where it cannot complete. A user-written utility program could, for example:

  1. Use a series of browses to locate a particular process or activity
  2. When the process or activity is found, inquire about its state
  3. Gain control of the process or activity by issuing an ACQUIRE command
  4. Correct a processing problem by issuing a further command or commands.

You can specify the activity identifier returned by a GETNEXT ACTIVITY, GETNEXT PROCESS, or INQUIRE PROCESS command on any of the following commands:

You can specify the process name returned by a GETNEXT PROCESS (or INQUIRE ACTIVITYID) command on any of the following commands:

After you have acquired a process or activity, you could, for example, issue one or more of the following commands against it:

Browsing examples

This section contains some examples of how the browsing and inquiry commands can be used.

Example 1

An application, which has not issued any requests to BTS, wants to see if a particular container belongs to a child of the root activity of a particular process, whose name and type are known.

Figure 66. Browsing example 1
   EXEC CICS INQUIRE PROCESS(pname)
                     PROCESSTYPE(ptype)
                     ACTIVITYID(root_id)
 
   if process found then browse the children of its root activity
     EXEC CICS STARTBROWSE ACTIVITY
                       ACTIVITYID(root_id)
                       BROWSETOKEN(root_token)
     EXEC CICS GETNEXT ACTIVITY(child_name)
                       BROWSETOKEN(root_token)
                       ACTIVITYID(child_id)
     loop while the child is not found and there are more activities
       EXEC CICS GETNEXT ACTIVITY(child_name)
                         BROWSETOKEN(root_token)
                         ACTIVITYID(child_id)
     end child activity browse loop
 
     if the child we are looking for is found then browse its containers
       EXEC CICS STARTBROWSE CONTAINER
                         ACTIVITYID(child_id)
                         BROWSETOKEN(c_token)
       EXEC CICS GETNEXT CONTAINER(c_name)
                         BROWSETOKEN(c_token)
       loop while container not found and there are more containers
         EXEC CICS GETNEXT CONTAINER(c_name)
                           BROWSETOKEN(c_token)
       end container browse loop
 
       EXEC CICS ENDBROWSE CONTAINER BROWSETOKEN(c_token)
     EXEC CICS ENDBROWSE ACTIVITY BROWSETOKEN(root_token)

Example 2

An application, which has not issued any requests to BTS, wants to know whether a particular data-container is one of the global containers associated with a particular process. If it is not, the program wants to know whether the container is owned by the root activity of that process.

Figure 67. Browsing example 2
   EXEC CICS INQUIRE PROCESS(pname) PROCESSTYPE(ptype)
                     ACTIVITYID(root_id)
 
   if process found then browse its containers
     EXEC CICS STARTBROWSE CONTAINER PROCESS(pname) PROCESSTYPE(ptype)
                     BROWSETOKEN(c_token_1)
     EXEC CICS GET NEXT CONTAINER(c_name)
                     BROWSETOKEN(c_token_1)
     loop while container not found and there are more containers
       EXEC CICS GET NEXT CONTAINER(c_name)
                       BROWSETOKEN(c_token_1)
     end process container browse loop
 
     if container not found browse the root activity's containers
       EXEC CICS STARTBROWSE CONTAINER ACTIVITYID(root_id)
                         BROWSETOKEN(c_token_2)
       EXEC CICS GETNEXT CONTAINER(c_name)
                         BROWSETOKEN(c_token_2)
      loop while container not found and there are more containers
        EXEC CICS GETNEXT CONTAINER(c_name)
                          BROWSETOKEN(c_token_2)
      end root activity's container browse loop
 
      EXEC CICS ENDBROWSE CONTAINER BROWSETOKEN(c_token_2)
   EXEC CICS ENDBROWSE CONTAINER BROWSETOKEN(c_token_1)

Example 3

A program running as an activation of an activity wants to find whether a named event has been defined to any of its children--that is, whether the event exists in any of the children’s event pools. If the event exists, the program wants to retrieve its fire status.

Because the program starts an activity browse on which no activity identifier or process name is specified, BTS browses the current activity. The program retrieves the identifier of each child activity, and uses this to browse the child’s events.

Activity identifiers remain valid after the browse that obtained them has ended. (They are valid for the life of the activity itself.) To illustrate this, the program uses the identifier of the activity whose event pool contains the named event, on an INQUIRE EVENT command, after it has ended the browse.

Figure 68. Browsing example 3
   EXEC CICS STARTBROWSE ACTIVITY BROWSETOKEN(parent_token)
   loop until the event is found or there are no more child activities
     EXEC CICS GETNEXT ACTIVITY(child_activity_name)
                       BROWSETOKEN(parent_token)
                       ACTIVITYID(child_activity_id)
     EXEC CICS STARTBROWSE EVENT ACTIVITYID(child_activity_id)
                       BROWSETOKEN(event_token)
     loop until event found or there are no more events
       EXEC CICS GETNEXT EVENT(event_name)
                         BROWSETOKEN(event_token)
     end event browse loop
 
     EXEC CICS ENDBROWSE EVENT BROWSETOKEN(event_token)
 
   end child activity browse loop
   EXEC CICS ENDBROWSE ACTIVITY BROWSETOKEN(parent_token)
   EXEC CICS INQUIRE EVENT(event_name)
                     ACTIVITYID(child_activity_id)
                     FIRESTATUS(fstatus)

Related concepts
Process- and activity-related commands
Container commands
Event-related commands
System events
Using the BTS API to write business applications
The Sale example application
Related reference
BTS application programming commands

10.
Process-types are a special case. They are browsed using the START, NEXT, and END options of the INQUIRE PROCESSTYPE command. INQUIRE PROCESSTYPE is described in BTS system programming commands.
11.
That is, apart from browses of processes and process-types.

[[ Contents Previous Page | Next Page Index ]]