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:
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.
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
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.
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.
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).
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.
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:
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:
This section contains some examples of how the browsing and inquiry commands can be used.
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.
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)
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.
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)
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.
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)