This section describes the things you need to do to install CallPath/CICS after you have copied the release from the tape or cartridge.
Before you install CallPath/CICS, generate the installation library (generate a partitioned data set containing the installation job streams and other installation data). Then use SMP/E to install the CallPath/CICS program libraries. Refer to the Program Directory for detailed instructions on how to do this.
Installing the CallPath/CICS program libraries creates the following data sets:
You should perform the following tasks in the order they are listed:
Before you begin to install your system, you must make decisions about:
If your existing system has only one CICS region, decide whether:
Figure 1 shows CallPath/CICS installed in a system with only one CICS region.
Figure 1. CallPath/CICS in a Single CICS Region
If your system already has more than one CICS region, you can either:
For information about including MRO in your CICS system, refer to the appropriate CICS Intercommunication Guide (see "CICS library").
You need an LU6.2 session to each CallPath SwitchServer/2. Map out the CICS SYSIDNTs and APPLIDs of each region and the names of the MRO links that connect them.
Figure 2 shows CallPath/CICS installed in a CICS system with MRO.
Figure 2. CallPath/CICS with CICS Multiregion Operation (MRO)
All CallPath/CICS objects are prefixed with EQ. The names of inserts to tables in CallPath/CICS CICS regions are prefixed with one of:
To satisfy CallPath/CICS naming conventions, you need to:
Select which of the following optional CallPath/CICS facilities you need:
You are supplied with a partitioned data set (PDS) named SEQZMACS. Each of its members is a CICS macro definition insert for CallPath/CICS in the primary CallPath/CICS region or a secondary CallPath/CICS MRO region. You need to customize some of the inserts and include them in your CICS tables.
If you are installing CallPath/CICS in a single CICS region or in a primary CallPath/CICS region of an MRO system, you will need to modify:
For remote MRO regions you will need to modify:
Inserts are supplied for each of the necessary CICS tables (except the SIT), for both primary and secondary CallPath/CICS regions. The SIT parameters for each region type are supplied in the form of overrides (SYSIN input to the CICS JCL).
If you are installing CallPath/CICS in a single CICS region, use the following procedures to modify the necessary CICS tables. If you are enabling use of CallPath/CICS in more than one region, follow the procedures in this section only for the primary CallPath/CICS region. For remote CallPath/CICS regions, see "CallPath/CICS From a Remote MRO Region".
If you prefer not to use overrides, change your existing SIT to include these parameters:
These parameters and their required values are contained in EQZSYSPD, which is in SEQZSAMP.
You are supplied with two DCT inserts:
When CallPath/CICS is unable to write to its own message log, it writes system messages to the transient data queue CSSL.
The definition for CSSL is supplied with CICS and is contained in members DFH$DCTD and DFH$DCTR of the CICS SAMPLIB data set.
To customize the DCT:
DFHDCT TYPE=INITIAL COPY other SDSCI definitions COPY EQZPDCTE COPY other extra-partition definitions COPY EQZPDCTI |
There are two PLTs, and they are optional:
PLTPI: You need a PLTPI if you want to do any of these things automatically at CICS startup:
Each program call in the CallPath/CICS API is a CICS task-related user exit (TRUE). If you do not use a PLTPI, you need to initialize TRUEs manually using the transaction EQTI each time you start CallPath/CICS. You can enter the transaction either at any CICS terminal or at a sequential terminal.
The startup list is supplied in EQZPPLTS and has the suffix VS.
PLTSD: You need a PLTSD if you want to shutdown the administration subsystem automatically during the first quiesce stage of CICS controlled shutdown. The shutdown list is supplied in EQZPPLTT and has the suffix VT.
The supplied PLTs can either be modified and incorporated into your existing PLTs, or they can be assembled and link-edited as they stand. To customize the PLTs:
If you are enabling use of CallPath/CICS from a remote CICS region, use the following procedures to modify the necessary CICS tables.
EQZMDCT defines a remote transient data (TD) queue to the primary region. When CallPath/CICS runs in a remote region, it uses the queue to write messages to its message log.
To customize the DCT:
Note: When CallPath/CICS is unable to write to its own message log, it writes messages to the transient data queue CSSL.
If you do not use a PLT you have to initialize TRUEs manually using the transaction EQTI before you use CallPath/CICS in the remote region. You can enter the transaction either at any CICS terminal, or at a sequential terminal.
You are supplied with the PLT insert EQZMPLT. If you do not need the supplied PLT insert, or if you merge it into an existing PLT, you need to modify your PPT.
To customize the PLT:
The JCL utilities you need are contained in SEQZSAMP:
There are separate instructions for installing CallPath/CICS in a single CICS region and for installing it in a secondary CallPath/CICS region.
If you are installing CallPath/CICS for OS/390 in a single CICS region or the primary region of an MRO system, make the following changes to either EQZRDP41 or EQZRDPTS: make the following changes to EQZRDOPJ:
The job adds all program definitions to group EQZPRPPT, all transaction definitions to group EQZPRPCT, all file definitions to group EQZPRFCT and, for CICS Transaction Server releases, all transient data queue definitions to group EQZPRDCT. Then it includes the groups in a group list called VICLIST. To meet your local installation standards, you can:
If you are enabling use of CallPath/CICS from a remote CICS region, make the following changes to EQZRDM41 or EQZRDMTS:
The job adds all program definitions to group EQZMOPPT, all transaction definitions to group EQZMOPCT and, for CICS Transaction Server releases, all transient data queue definitions to group EQZMODCT. Then it includes the groups in a list called VICLIST. To meet your local installation standards, you can:
The procedures described in this section are for the primary CallPath/CICS region only.
You need to:
To create shared reference files, use the JCL
EQZINIAJ supplied in SEQZSAMP.
Table 2 shows the member names and library names
of the input data sets.
| Sublibrary name | Member name | Contents |
|---|---|---|
| SEQZSAMP | EQZMSGSD | Message text |
| SEQZSAMP | EQZHELPD | Cross reference files for online help |
| SEQZSAMP | EQZINIAD | SYSIN input |
To create the shared reference files:
If you are using CICS dynamic allocation, make sure the data set high-level qualifiers match the names you specified in the RDO file definitions. If you are not using CICS dynamic allocation, make sure the data set names match the names you define in EQZCJCLD in "Allocating VSAM Files".
Table 3 shows the output from the job.
Table 3. Output Data Sets From EQZINIAJ
| Name | Type | Contents |
|---|---|---|
| EQZMSGS | VSAM KSDS | List of system messages loaded from SEQZSAMP |
| EQZHELP | VSAM KSDS | List of help maps loaded from SEQZSAMP. |
Work files are system files that can be used by only one primary
CallPath/CICS region.
To create work files, use
the JCL utility EQZINIBJ supplied in SEQZSAMP.
Table 4 shows the member names and library names
of the input data sets.
| Library name | Member name | Contents |
|---|---|---|
| SEQZDAT1 | EQZSWCH | Dummy switch record |
| SEQZSAMP | EQZINIBD | SYSIN input. |
To create work files:
If you are using CICS dynamic allocation, make sure the data set high-level qualifiers match the names you specified in the FCT. If you are not using CICS dynamic allocation, make sure the data set names match the names you define in EQZCJCLD in "Allocating VSAM Files".
Table 5 shows the output from the job.
Table 5. Output Data Sets From EQZINIBJ
| Name | Type | Contents |
|---|---|---|
| EQZSWCH | VSAM KSDS | Switch description record loaded from SEQZDAT1 |
| EQZCLOG | VSAM ESDS | Not loaded |
| EQZTRCA | VSAM ESDS | Not loaded |
| EQZTRCB | VSAM ESDS | Not loaded |
| EQZLOGA | VSAM KSDS | Not loaded |
| EQZLOGB | VSAM KSDS | Not loaded |
| EQZTRFA | VSAM ESDS | Not loaded |
| EQZTRFB | VSAM ESDS | Not loaded |
| EQZEVNT | VSAM KSDS | Not loaded |
| EQZSPI | VSAM ESDS | Not loaded |
If you want to use optional CallPath/CICS facilities, you need to customize the CallPath/CICS JCL before you create data sets to contain it.
You are supplied with JCL for two optional facilities, which:
If you want your CallPath/CICS system to include the facility to print the system messages log, you need to customize EQZPRNTC:
If you want your CallPath/CICS system to include the facility to archive log files, you need to customize EQZBKUPC and EQZDGDGJ.
To customize EQZBKUPC:
To customize EQZDGDGJ:
Note: The GDG definition creates a catalog entry only. You do not need to specify a volume.
To create data sets that contain the CallPath/CICS JCL,
use the JCL utility EQZINICJ supplied in SEQZSAMP.
Table 6 shows the member names and library names
of the input data sets.
| Library name | Member name | Contents |
|---|---|---|
| SEQZSAMP | EQZBKUPC | Customized archive JCL |
| SEQZSAMP | EQZPRNTC | Customized print JCL |
| SEQZSAMP | EQZINICD | SYSIN input |
To create the CallPath/CICS data sets:
If you are using CICS dynamic allocation, make sure the data set high-level qualifiers match the names you specified in the FCT. If you are not using CICS dynamic allocation, make sure the data set names match the names you define in EQZCJCLD in "Allocating VSAM Files".
Table 7 shows the output from the job.
Table 7. Output Data Sets From EQZINICD
| Name | Type | Contents |
|---|---|---|
| EQZBKUP | ESDS | Loaded from EQZBKUPC |
| EQZPRNT | ESDS | Loaded from EQZPRNTC |
CallPath/CICS needs a switch description record in its switch description file for each of the switches it is to communicate with. The switch description record can specify which program calls a particular switch supports and which event messages the switch can monitor.
There is no need to create each switch description record from scratch. You can create a switch description record dynamically based on an existing switch description (a cloned copy).
To create your initial switch description records, create a record that includes both a switch name of your choice and the appropriate switch characteristic record from EQZSWDT. You can also define test switches for use only with the switch simulator by creating extra entries in the switch description file. Do not create or define communication links ("Task 8: Creating Communication Links" and "Task 9: Defining Communication Links") for test switches.
It is also possible to add a switch dynamically while the system is running, the switch will be based on a switch previously defined from EQZSWDT, for more information see Chapter 5, "Managing Switch Communications".
| Migrating from an earlier Release |
|---|
|
If you are migrating from an earlier release and wish to use your existing EQZSWCH file, run DFHCSDUP to MIGRATE TABLE(DFHFCT). When this has completed successfully use CEDA to set Add to Yes for file EQZSWCH, this can be done by CEDA DI FILE(EQZSWCH) G(*) and then ALter against the file. This does not need to be done with a new installation. |
Member EQZSWDT in partitioned data set SEQZDAT2 contains records describing the characteristics of each type of switch that you can use with CallPath/CICS. It also contains a general record that defines a switch that supports all the CallPath/CICS program calls and supports monitoring all event messages.
The following list shows some of the switches supported by CallCoordinator, but with knowledge of your particular switch you can create the appropriate switch description record to suit your applications requirements. You can also use the GENERAL-ALL SWITCH FUNCTIONS switch description. CallCoordinator then accepts all application requests and these requests are sent to CallPath SwitchServer/2. Requests not supported by the switch are rejected by CallPath SwitchServer/2.
Against each switch a descriptive text is given that identifies the switch. You use this to specify which switch description records you want created. (Ref #4.)
Note: Blanks in the record name are part of the record key.
Job EQZSWLDJ (supplied in SEQZSAMP) adds one or more switch description records to the switch description file. It reads two input files:
Member EQZSWLDJ is a job that adds one or more switch description records to the switch description file. It reads input from SYSIPT. The output from the utility is one or more records on the VSAM file EQZSWCH. Each record consists of a switch name and the appropriate switch characteristics.
To create switch description records using job EQZSWLDJ:
For example, to add three switch description records to the file, you need to create the following JCL:
//EQZSWNM DD * SWITCH01IBM COM300 B2.3.8 K1.1 SWITCH02NT MERIDIAN 1 K1.1 TESTSW1 IBM COM300 B2.3.8 K1.1 /* |
Possible return codes are listed below:
A message is also written to the SYSOUT file. Note that you can add more switches to the file at a later date, if you need to.
CallPath/CICS uses the system configuration table (SCT):
You need to create the SCT using the following supplied in the library SEQZMACS:
EQZSCTAJ (contained in SEQZSAMP) is a sample job to assemble and link-edit the SCT.
To create the SCT:
If you are installing CallPath/CICS with CICS MRO, see Figure 3 for examples of the values to enter.
Example parameter values for the SCT for this system are shown in Figure 4.
Figure 4. Example Parameter Values for an MRO System
EQZTSCT EQZSCT APPLNREG=(APPLICB,APPLICA,APPLICC,APPLICD),
SUBSYSID=(SYSA,SYSX,SYSP,SYSP),
SUBSYREG=APPLICA,
TOTALSTG=08000,
MAXMSGS=01000,
QCLNTIME=00030,
DATECODE=2,
DATESEP=/,
TIMESEP=:,
LOG=Y,
TD=N,
LOGW=Y,
LOGI=N,
LOGA=Y,
LOGU=Y,
DESTIDW=CSSL,
DESTIDI=CSSL,
DESTIDA=CSSL,
DESTIDU=CSMT
|
The assembler source, EQZTSCT, contains the following parameters:
Note: You still need these parameters if you do not use MRO.
A list of the VTAM APPLIDs of all the regions that will use CallPath/CICS. The same VTAM APPLIDs must appear in the SIT for the primary CallPath/CICS region and each secondary CallPath/CICS region.
A list of the SYSIDs of the CallPath/CICS primary region from the perspective of each of the secondary regions specified in the first parameter. The first SYSID in the list corresponds to the region whose APPLID is first in the corresponding list for the APPLNREG parameter, and so forth. Consequently, APPLNREG and SUBSYSID should have an equal number of entries. The SYSID for any secondary CallPath/CICS region is the same as the MRO connection name from the secondary CallPath/CICS region to the primary CallPath/CICS region.
Note: The primary CallPath/CICS region also needs an entry in APPLNREG and SUBSYSID. Its SYSID is the same as the SYSIDNT parameter in the SIT for the primary region.
The APPLID of the primary CallPath/CICS region.
Note: Do not set these parameters automatically to their maximum values, or you might cause problems with your CICS system. If you are in doubt about the value you should specify for a particular parameter, use the example values specified for the EQZTSCT macro in Figure 4.
The maximum amount of storage in KB that can be used by CallPath/CICS for its internal dynamically allocated tables. A number in the range 1000-32 000. See also "Using CICS storage above the 16MB line"
Note: You must not set CallPath/CICS or CallPath/CICS storage parameters to values higher than those supported by the MVS system, or CICS will stall.
The maximum number of messages that the application message queue can hold. A number in the range 0-16 000.
The MAXMSGS parameter should be set with care. If the number specified is exceeded, CallPath/CICS will discard messages that are destined for the application. The rate at which messages are processed within CallPath/CICS varies with the applications ability to process these messages. Transaction EQDA (see "Diagnostic Aids") can be used to monitor system activity and to select an appropriate value for the MAXMSGS parameter.
The amount of time (minutes) that an unreferenced application program name is left before the program name and all objects such as call profiles and message queues are deleted when you run the Queue Clean program (see topic "Freeing Resources"). A number in the range 0-2880 (representing 0-48 hours).
A number in the range 1-8 that represents one of the following formats:
Note: These formats assume the chosen separator character is a slash (/).
The date separator character. The character slash (/) is suggested, but you can specify a different character.
The time separator character. The character colon (:) is suggested, but you can specify a different character.
You can direct CallPath/CICS messages to transient data queues as well as to the VSAM message files EQZLOGA and EQZLOGB. You can also control messages by their severity. The parameters are:
The LOG parameter can take the following values:
You can control which messages are written using the LOGx parameter, where x may be one of the following:
For example, specify LOGW=N in the SCT to prevent warning messages from being written to the VSAM file or transient data destination; LOGW=Y allows these messages to be written. Similarly, use LOGA, LOGI, and LOGU parameters to control the sending of action, information, and user messages.
The TD parameter can take the following values:
where:
You use this parameter to direct action, information, user, and warning messages to different transient data destinations. For example, if you specify DESTIDW=CSSL and DESTIDA=CSSL, the warning and action messages are directed to CSSL. The user and information messages could be written elsewhere.
It is easier for IBM personnel to solve problems if all messages are written to the VSAM message log files. If you choose to implement a strategy that prevents all the information from being readily available to support personnel, delays may occur in resolving problems.
You need to modify the CICS JCL in the primary CallPath/CICS region.
This section describes how to override SIT parameters using SYSIN input to the CICS JCL. If you have already included the required parameters in your SIT, skip this section.
SIT parameters are contained in the following data sets which are supplied in SEQZSAMP:
In each data set you need to customize:
Make sure the primary CallPath/CICS region contains the following EQZRDR DD statement that points to the MVS reader-interpreter queue. The statement is supplied in EQZCJCLD in SEQZSAMP.
//EQZRDR DD SYSOUT=(S,INTRDR),DCB=(LRECL=80,BLKSIZE=80) |
If you intend to use SCT overrides, you will need to add a new DD statement to your startup JCL. The statement will have the ddname, EQZIN as specified in the Transient Data queue RDO definition for TDQueue, EQIN. The overrides can be provided either inline as SYSIN or in predefined sequential dataset.
If you do not intend to use SCT overrides, add the following EQZIN DD statement to prevent warning messages at startup. The statement is provided in EQZWCLD in SEQZSAMP.
//EQZIN DD DUMMY
| Note |
|---|
| Do this only if you do not plan to use CICS dynamic allocation. |
Data definition (DD) statements to allocate VSAM files to your primary CallPath/CICS CICS JCL are contained in EQZCJCLD in SEQZSAMP.
To allocate VSAM files:
CallPath/CICS uses an LUTYPE6.2 link to communicate with each CallPath SwitchServer/2. You need to create each link using RDO or a macro definition. An LUTYPE6.2 link is needed between the primary CallPath/CICS region and CallPath SwitchServer/2. MRO links are needed between the primary CallPath/CICS region and secondary CallPath/CICS regions.
You are recommended to define each of these components using RDO. This way, you can redefine links without shutting down and restarting CICS.
An LUTYPE6.2 link to CallPath SwitchServer/2 needs:
Appendix B, "Definitions Required for Network Connections" contains examples of each of these definitions.
You need to define two CICS connections to CallPath SwitchServer/2, one for send and one for receive. Each connection definition needs its own session definition.
If you are using LUTYPE6.2 for communication between the primary CallPath/CICS region and a remote region, the remote region must be the bind winner of at least one more session than the peak number of simultaneously running tasks using CallPath/CICS in MRO mode.
If you are using IRC for communication between the primary CallPath/CICS region and a remote region, the SENDCOUNT in the CallPath/CICS remote region must be at least one greater than the peak number of simultaneously running tasks using CallPath/CICS in MRO mode.
You must define the LUTYPE6.2 links between CallPath/CICS and CallPath SwitchServer/2 to VTAM. You need the following VTAM table entries:
After creating an LU6.2 communication path to CallPath SwitchServer/2, you need to define it to CallPath/CICS using the CallPath/CICS administration panels. The information is added to the appropriate switch description record. To define a link to CallPath SwitchServer/2:
You see the Switch Description Configuration List panel, which lists all the switches for which you have created a switch description record.
You see the Switch Description Configuration Details panel for the switch.
See "What to Enter in Each Field". For communications with a switch to be automatically started when the administration subsystem is started, the following requirements must be met:
CallPath/CICS is supplied with an installation verification program (IVP) to check that it has been installed successfully on the host. Verification is an important part of the installation process and you should not consider installation to be complete until you have run the IVP.
You can also run the IVP at any time after installation. You might want to run it if your application programs report problems or if you are advised to do so by logged messages.
The IVP checks:
You can run the IVP either in the primary CallPath/CICS region or in a secondary CallPath/CICS region. The type of region is automatically identified by the IVP when it accesses the SCT load module. When it runs in a secondary CallPath/CICS region, the IVP can validate only the items that are defined in that region.
The IVP does not validate the communication links to CallPath SwitchServer/2.
To run the IVP:
You see the Installation Verification Menu panel (shown in Figure 5.)
Choose this option only from a remote CallPath/CICS region.
Figure 5. Installation Verification Menu Panel
EQZMV01 Installation Verification Menu
Select one of the following options by typing an option number.
Then press Enter.
_ 1. Verify transactions/programs/maps/transient data queues/files
2. Verify remote region support links from CallPath/CICS MRO regions only
3. View messages
IBM CallPath for OS/390
5655-B34 (C) Copyright by IBM Corp. 1991, 1999. All rights reserved.
F1=Help F3=Exit F11=Panel ID F12=Cancel
|
You see the Installation Verification Progress Messages panel.
Figure 6. Installation Verification Progress Messages Panel
EQZMV02 Installation Verification Progress Messages The installation verification program is running Checking transactions/programs/maps Checking transient data queues Checking files Checking help maps |
As the IVP runs, you see progress messages on the panel showing which check is being performed. Figure 6 shows all the progress messages in the sequence that they appear when you select 1 on the Installation Verification Menu.
The IVP ends either when it has performed all its checks or when it encounters an error from which it is unable to recover. When the program ends, a message tells you if it discovered any errors in the installation.
You see the Installation Verification Message Listing panel.
Appendix A, "System Messages" contains a list of all the messages the IVP can display. Each message is explained and you are advised what action to take.
