This chapter covers two aspects of intercommunication:
CallCoordinator provides support for multiregion operation (MRO) within CICS. This allows your business applications to operate either in the same region as CallCoordinator or in a different region from CallCoordinator. When operating in different regions, application programs can still use the application programming interfaces (APIs) to access resources in the CallCoordinator region. This can help you to balance the load between regions and obtain optimal performance within CICS. Also this enables you to use a sysplex environment. For more information about MRO, refer to the CICS/MVS Intercommunication Guide. For more information about sysplex, refer to OS/390 V2R4.0 Parallel Sysplex Overview.
No additional application programming is needed for multiregion operation with CallCoordinator. The APIs themselves are coded to do the following:
In a MRO environment where there is one COR, all the AORs must have access to the connection ID (SysId) of the COR. This is done by defining a dummy remote program name (CAMIMROC) in all the AORs. The REMOTE SYSTEM name on the program definition is the connection ID of the COR.
MRO support uses the DPL command of CICS. This allows the data in one CICS region to be available to programs running in another region. For each API, two complementary invocations of the API program (one in the calling program's region, one in CallCoordinator region) execute simultaneously to perform the API function, and return control and API-provided data to the calling application program (see Figure 1).
Multiple Application Owning Regions enables you to share selected system resources. Each region runs independently and is protected from errors that occur in other regions (see Figure 2). This sharing of resources is transparent to the end user.
CallCoordinator provides APIs that allow a transaction to access CallCoordinator data. The APIs, when invoked through a CICS LINK facility, first determine if the calling program resides in the same CICS region as the CallCoordinator application. If this is the case, the API processes the calling program's request and then returns data and control to the calling program. If the calling program is found to be in a region different from the CallCoordinator region, the API uses a Distributed Program Link command to the CallCoordinator region, which invokes the API with the original Commarea in the CallCoordinator region.
When the API completes in the CallCoordinator region, control is returned to the calling region with the updated Commarea. This in turn is returned to the user's calling program. The API program executes in both the calling program's region and the CallCoordinator region simultaneously. This facilitates the communication required between regions for transmission of the calling program's request and the API program's response (see Figure 2).
To identify the terminal with which to communicate, CallCoordinator must have a terminal definition including its characteristics and the region it belongs to. To meet this requirement, the Agent Sign On API is invoked in the remote region, which uses START to start a transaction in the CallCoordinator region (the V795 transaction). This causes the Terminal Control Table Terminal Entry (TCTTE) to be shipped to the CallCoordinator region. In subsequent INQUIRE commands, CallCoordinator requires the SysId of the TOR in order to start a transaction via Screen Presentation Manager. Terminal definitions for CallCoordinator agents must be defined as "shippable".
In CICS for MVS/ESA(TM) V4.1 and later there are two parameters: DSHIPIDL and DSHIPINT, which represent the Idle time and Interval, respectively, that CICS will use to determine if and when to delete TCTTE information. If an agent has been inactive for the period of time specified in the DSHIPIDL parameter, their TCTTE information may be removed from the CallCoordinator region. Subsequent INQUIRE requests will then fail. If the agent signs off from CallCoordinator and then signs back on again, the TCTTE information will be recreated.
DSHIPIDL and DSHIPINT should be set to zero for no deletion, within the CallCoordinator region. These parameters reside in the System Initialization Table (SIT) and can be checked or set using CEMT I DEL. Overtype one or both of the INT and IDL parameters and press ENTER to change.
In a sysplex environment there may be more than one COR. The AOR must have access to the connection name (SysId) of all the CORs so that the APIs can be routed to the correct COR. This information is made available in shared Temporary Storage Queues (TSQs) and Coupling Facility Data Tables (CFDTs). The TSQs and CFDTs are created at CallCoordinator initialization. This arrangement allows multiple CORs to exist and for the API request to be processed by the appropriate COR.
CallCoordinator APIs can be put into the following categories:
For more information about configuring for MRO, and sysplex, refer to the Installation part of the CallPath CallCoordinator/CICS System Management Guide
All APIs on entry call the API router program. This program returns a number of return codes to the APIs. If there is an error the API fails with a return code 8, and the following reason codes:
For further information, see the book CallPath CallCoordinator/CICS Problem Determination.
Application programs that use the CallCoordinator exits must be defined and installed in the CallCoordinator AOR.
Here are some examples of CallCoordinator environment configurations.
Figure 1. Application Program Interface (API) MRO Support Structure (Non-Sysplex)
Figure 2. The CallCoordinator MRO Environment
Figure 3. A CallCoordinator Sysplex Environment
The CallCoordinator APIs can also be invoked from a remote system (CICS, IMS(TM), RS/6000®, OS/2®, or any other platform/system) using LU 6.2/ CPIC mapped conversations. In order to accomplish this it is necessary to format a DTP record to consist of a header as follows:
APINAME is the name of a CallCoordinator API., for example CAMI775C.
APICALEN is the length of the API Communications Data Area.
Figure 4. DTP record for COBOL
01 DTP-RECORD-HEADER.
05 TRANSID PIC X(04) VALUE 'V790'.
05 APINAME PIC X(08).
05 APICALEN PIC S9(4) COMP.
|
Figure 5. DTP record for Assembler
HEADER DS 0H ALIGN RECORD TRANSID DS CL4'V790' CICS TRANID OF BACKEND SERVER APINAME DS CL8 NAME OF API TO LINK TO APICALEN DS H LENGTH OF COMMAREA THAT FOLLOWS. |
The API Communications Data Area then immediately follows the above header. The COBOL versions of these Communications Data Areas are shipped as source with CallCoordinator, so this can be accomplished by appending the COBOL version of the header with the following statement:
COPY CAMC775 REPLACING == 01 CAMC775-COMMAREA. ==
BY == 05 CAMC775-COMMAREA. ==.
To set the APICALEN field up correctly, the following COBOL statement could be used:
MOVE CAMC775-COMMAREA-LEN TO APICALEN.
where CAMC775 can be the name of any CallCoordinator API Communications Data Area.
For Assembler, write a DSECT that defines a data area that is exactly equivalent in layout to the COBOL copy book.
Having set up the DTP record as given above, issue the relevant LU 6.2/ CPIC verbs to complete the conversation.
Figure 6. Conversation held across the LU6.2 link with V790
Remote system CallCoordinator(V790)
------------- ---------------------
1.Allocate the conversation.
2.Send the DTP record
3.Receive the DTP record
4.Send the updated DTP rec.
5.Receive the updated DTP rec.
Below is an example where the COBOL application runs in a
CICS system CICSA and CallCoordinator runs on CICSB:
CICSA CICSB(V790)
----- -----------
1. EXEC CICS ALLOCATE
SYSID(CICSB)
NOHANDLE
END-EXEC.
MOVE EIBRSRCE TO SESS-NAME.
2. EXEC CICS CONVERSE
SESSION(SESS-NAME) EXEC CICS RECEIVE....
FROM(DTPRECORD) EXEC CICS LINK.......
FROMLENGTH(DTPRLEN) EXEC CICS SEND.......
INTO(APICOMMAREA) EXEC CICS FREE.......
TOLENGTH(APICALEN)
END-EXEC.
(See Note 1. below)
3. EXEC CICS FREE
SESSION(SESS-NAME)
END-EXEC.
|
Notes:
