DEFINE PROCESS command: Transfer Control partner

Summary

Privileges

User 0 or system manager

Function

Defines a Transfer Control process for reference by the SOUL TRANSFER statement. The process definition indicates the partner (CICS program or SNA Communications Server application), the type of transfer, and the characteristics of the transfer.

Syntax

DEFINE PROCESS name [LIKE previousname] WITH SCOPE=SYSTEM DESTINATION=processgroupname PARTNER=partnername DATALEN=nnnnn MODE={XCTL | PASS} [TIMEOUT=nnnnn] UIDSOURCE={NONE | CURRENT |OPEN} ACCTSOURCE={NONE | CURRENT | OPEN}

Where:

name	The local Model 204 name for the process being defined. The SOUL TRANSFER statement refers to this process by the name specified. The length of the name must be 1 to 8 characters.
LIKE	Gives the current link the attributes of the link entity referred to by previousname.
SCOPE=SYSTEM	Indicates that the definition is available to all users of the Model 204 system for the entire run.
DESTINATION	Associates the process with the processgroup, processgroupname, defined by the DEFINE PROCESSGROUP command.
PARTNER	The name of the partner (as known in the remote environment) that is the object of the User Language TRANSFER statement and to which control is passed. Acceptable values for partnername (as many as eight characters) depend on what MODE, PROTOCOL, and LOGIN options are defined on the DEFINE PROCESS, DEFINE LINK, and DEFINE PROCESSGROUP commands, respectively: When MODE=XCTL and PROTOCOL=TRANSFER, partnername must be the name of a CICS program. The CICS program is the partner process and the object of the TRANSFER statement. When MODE=PASS and PROTOCOL=TRANSFER, the transfer uses SNA Communications Server. For transfers to another Model 204 region, partnername must be either the name of a processgroup defined in the destination region or the SNA Communications Server applid (User 0 VTAMNAME parameter value) of the destination region. The choice of processgroup or SNA Communications Server applid depends on the LOGIN value of the accompanying DEFINE PROCESSGROUP command. LOGIN can be TRUST or NOTRUST: If both partners are defined with LOGIN=TRUST, the transfer is "trusted": the command line passed to the partner is processed without a qualifying prompt for a password. The partnername value is checked for at the partner. It must be the name of a processgroup defined in the destination Online; if not, a password is prompted for. If either partner is defined with LOGIN=NOTRUST, the transferring user is prompted for a password. The partnername value is not checked for at the partner. It therefore can be either the name of a processgroup in, or the SNA Communications Server applid of, the destination region. For transfers to a non-Model 204 region, partnername must be the SNA Communications Server applid of the destined SNA Communications Server application. The value specified for PARTNER can be as many as eight characters in length.
DATALEN	Determines the maximum size of the data area that can be specified in the TRANSFER statement, and depends on the value of MODE. If MODE=XCTL, the maximum data length is the CRAM buffer size, less 12 bytes. If MODE=PASS, the maximum data length is 144 bytes. The data area passed by the TRANSFER statement when MODE=PASS might include an automatically formatted login command string. When so, you must allow for an additional 12 bytes of overhead without exceeding the DATALEN limit of 144. If the formatted login command string is passed to a "trusted" partner, you must also allow for the length of the passed user ID and the length of the passed processgroup name.
MODE	The program control mechanism to be used. Acceptable values are as follows: XCTL For transfers via CRAM to CICS partners. PASS For transfers via SNA Communications Server to Model 204 or non-Model 204 partners.
TIMEOUT	Provides a terminal timeout facility, that is, the number of seconds a thread waits for notification that a session was established with the destined SNA Communications Server application. Zero specifies no time limit and is the default. TIMEOUT is valid only when MODE=PASS.
UIDSOURCE	The place to obtain the user ID for the login command string passed to the partner. The command string is specially formatted to log into the remote partner and includes the SNA Communications Server applid of the issuing partner. UIDSOURCE options are: NONE The default, this means no command string is formatted by the Transfer Control facility. CURRENT The current user ID is formatted into the passed command string when the TRANSFER statement is invoked. OPEN The user ID that is formatted into the passed command string is taken from the USERID parameter of the TRANSFER statement. UIDSOURCE is valid only when MODE=PASS.
ACCTSOURCE	The place to obtain the account ID for the command string passed to a partner when control is transferred. The ACCTSOURCE options are NONE, CURRENT, and OPEN, and they apply to account ID the same as the UIDSOURCE options apply to user ID. ACCTSOURCE is valid only when MODE=PASS.

Example

Transfer to a CICS program:

DEFINE PROCESS CICSTRN1 WITH - SCOPE=SYSTEM PARTNER=CICSPGM - DESTINATION=GRP1 - DATALEN=256 MODE=XCTL

Transfer from a Model 204 Online to a Model 204 Online:

DEFINE PROCESS M204APR WITH - SCOPE=SYSTEM PARTNER=M204BPG - DESTINATION=M204APG - DATALEN=100 MODE=PASS

Usage notes

All three DEFINE commands (DEFINE LINK, DEFINE PROCESSGROUP, and DEFINE PROCESS) are necessary to fully define the process on the side from which the user is transferred. These commands are also required for the receiving side in a trusted SNA Communications Server transfer.

For detailed information about Transfer Control, refer to Transfer Control facility and to Using Program Communication facilities.