Using Program Communication facilities

Overview

Program Communication, available on CICS, CMS, and SNA Communications Server (formerly VTAM) full-screen threads (IODEV=11, IODEV=41, and IODEV=7, respectively), allows SOUL requests to communicate with user-written CICS programs, CMS EXECs, or SNA Communications Server applications. The Program Communication facilities, that is, TPROCESS (Terminal Process) and Transfer Control, allow a SOUL request to do the following:

• TPROCESS — Identify, trigger execution of, and communicate with a CICS partner program or CMS partner EXEC
• Transfer Control — Identify a CICS partner program or SNA Communications Server partner application, transfer control to the program or application, and pass it a parameter area

In addition, Model 204 provides program-to-program processing support through its distributed application facility, Horizon, an optional feature. Model 204 applications can communicate through SNA Communications Server with one or more other programs using program-to-program processing. Communication takes place over an SNA network, using verbs and protocols conforming to LU 6.2 architecture. Horizon uses SOUL statements and Model 204 commands, and might require IODEV=27 threads.

This topic provides a summary of system management information for the support of the Program Communication facilities. Horizon is described in the Horizon wiki topics. IODEV=27 threads are discussed in Horizon (IODEV=27).

Preparing for TPROCESS communication

TPROCESS communication works under CICS or CMS. SOUL requests communicate with a CICS program or CMS EXEC by issuing the OPEN PROCESS and CLOSE PROCESS commands and using SEND, RECEIVE, FLUSH PROCESS, and SIGNAL PROCESS statements.

The calls used by CICS and CMS are the following:

• CICS communicates with the SOUL request by calling the IFCSA, IFSEND, IFRECV, and IFSGNL functions resolved by the IFPPCI module.
• CMS EXEC communicates with the SOUL request through the IFSENDX, IFRECV, and IFSGNL subcommands.

The following sections describe the system manager actions required to enable TPROCESS. The operation of the TPROCESS and Transfer Control facilities is described in Program Communication facilities.

Defining the partners

Before a SOUL request can communicate with either CICS or CMS, you must define a partner process (CICS program or CMS EXEC) for reference by SOUL statements. Define the process and its attributes with the DEFINE LINK, DEFINE PROCESSGROUP, and DEFINE PROCESS commands. These commands connect the process to a link, identify the communication protocol to be used with the partner process, and define the partner process you must enable the link defined by the DEFINE LINK command with the OPEN LINK command.

Preparing for CICS TPROCESS

Linking to IFPPCI

You must link the CICS program identified by the DEFINE command with the IFPPCI module.

IFPPCI has five entry points (IFCSA, IFPREP, IFSEND, IFRECV, and IFSGNL) that the CICS program can call. These calls are described in CICS TPROCESS calls.

Installing the full-screen CICS Interface

The PPT entry for the full screen CICS Interface module name (M204PSFS) must specify a TWA size.

Specifying buffer sizes

Screen and CRAM buffer sizes are dependent on the model type and LOUTPB size specification. The LOUTPB parameter for IODEV=11 determines the CRAM buffer size. Set LOUTPB slightly larger than the screen size for the 3270 model type used. If users are resetting model types, set LOUTPB to match the largest screen size.

Preparing for CMS TPROCESS

Installing the M204USR module

In CMS, the reentrant M204USR module, which must be installed as a saved segment or as a nucleus extension (see the Rocket Model 204 z/VM Installation Guide), acts as the interface that calls a CMS EXEC (REXX or EXEC2) to communicate with a SOUL request through subcommands. M204USR is the module name, if the M204USR module is installed as a saved segment. M204USR is the module name, if the M204USR module is installed as a nucleus extension.

Installing M204USR as a saved segment or nucleus extension avoids the possibility of overlaying the interface module by commands that run in the user area.

Constraints

Model 204 supports communication between a SOUL request and one concurrent CMS partner process, subject to the following constraints:

• The CMS partner process must be written in System Product Interpreter language (REXX) or EXEC2. Communication occurs through the standard CMS SUBCOM interface, which is supported by these languages.
• If any program executed by the CMS partner process terminates abnormally, the user's thread is disconnected.

For more information

Functions and subcommands used in TPROCESS are described in CMS TPROCESS communication.

Preparing for Transfer Control communication

In Transfer Control, SOUL requests transfer control to a CICS program or SNA Communications Server application by issuing the TRANSFER statement. Control is passed to the CICS or SNA Communications Server application partner process, and the CICS or SNA Communications Server application user is disconnected from Model 204.

This section presents overview information for the system manager about the Transfer Control facility. The primary source for operational information for the facility is Transfer Control facility.

SNA Communications Server transfers are more complex

CICS transfers are within a single region (between the Model 204 CICS Interface and a CICS program running in the same region). SNA Communications Server transfers are between SNA Communications Server regions, using the PASS option of the CLSDST macro. SNA Communications Server transfers are more complex:

• Inter-regional security concerns might require a transfer to provide for login and password processing at the destination region.

  DEFINE command and TRANSFER statement format and execution options available only for SNA Communications Server transfers determine how the command string passed in the transfer is processed at the destination.

• You might have to specially format the passed command-line data to suit a non-Model 204 destination application.

  When the destination application is another Model 204 region, the login string can be automatically formatted by specifying the appropriate DEFINE PROCESSGROUP option. In this case, the login string is also encrypted; it is decrypted at the destination Model 204 region.

• A CICS transfer failure leaves the user in the CICS Interface, whereas a SNA Communications Server transfer failure can leave the user in SNA Communications Server between applications.

  A user can successfully transfer via SNA Communications Server to an application in another region but fail login requirements at the destination application. A mechanism is required to return the user from SNA Communications Server to the original Model 204 environment or to another SNA Communications Server application.

  The $Remote function returns the VTAMNAME parameter value of the region from which the SNA Communications Server transfer issues. This facilitates the transfer of the user back to the initial Model 204 region.

• If a SNA Communications Server TRANSFER fails, Model 204 attempts to get the terminal back by issuing an OPNDST with the ACQUIRE option. Therefore, if the Online is to support SNA Communications Server TRANSFER, the VTAMNAME APPL definition must contain AUTH=(PASS,ACQ).

Defining the partners

Before a SOUL request can transfer control to either CICS or SNA Communications Server, you must define a partner process (CICS program or SNA Communications Server application) for reference by SOUL statements. Define the partner and its attributes with the DEFINE LINK, DEFINE PROCESSGROUP, and DEFINE PROCESS commands. These commands connect the process to a link, identify the communication protocol to be used with the partner process, and define the partner process.

In addition, the link defined by the DEFINE LINK command must be enabled with the OPEN LINK command.

Transferring to CICS

The CICS partner process must be a CICS program defined to CICS.

After the SOUL TRANSFER statement completes successfully, the user is disconnected from Model 204 and transferred to the specified CICS partner process.

Data passed to CICS via the TRANSFER statement PASSING clause is written to a Temporary Storage Queue named by combining the CICS user's terminal ID and the string PSFS. The CICS partner reads the data from the Temporary Storage Queue and processing continues according to the CICS program.

Transferring to SNA Communications Server

After the SOUL request containing the TRANSFER statement transfers the user to the destination region, and a session is established with the destination SNA Communications Server application, the user is notified that the session is established and is disconnected from Model 204. Data passed in the transfer (for example, Model 204 commands) is acted upon in the destination application.

If SNA Communications Server fails to establish a session with the destination application, the user is notified that the session is not established. The user is not disconnected from Model 204, and control returns to the request that contains the TRANSFER statement.

The application transferred to is responsible for transferring the user back to the original region or to another SNA Communications Server application.

Proper login and handling of the passed command string requires coordination between the security options specified in the DEFINE commands and the TRANSFER statement. Selection of these security options is discussed in Security for Model 204-to-Model 204 transfers.