Follows an ALLOCATE command to initiate an advanced program-to-program communications (APPC) mapped conversation with a program that is running on a remote system. (An APPC conversation allows a program to send data to, and receive data from, a program that is running in a remote system. Programming that uses APPC conversations is called Distributed Transaction Programming (DTP). For guidance information about DTP, see Distributed transaction processing (DTP).)
Syntax
CONNECT PROCESS >>-CONNECT PROCESS--CONVID(name)--PROCNAME(data-area)-----------> >--PROCLENGTH(data-value)--SYNCLEVEL(data-value)----------------> >--+-------------------------------------------+----------------> '-PIPLIST(data-value)--PIPLENGTH(data-area)-' >--+-------------+--------------------------------------------->< '-STATE(cvda)-'
Conditions: INVREQ, LENGERR, NOTALLOC, SYSBUSY, SYSIDER
Description
CONNECT PROCESS allows an application to specify the name of the process with which it wants to communicate in the remote system. It can also specify the synchronization level to use during the conversation with the remote process. It can optionally specify the process initialization parameter (PIP) data that is to be sent to the remote process.
Options
- CONVID(name)
- Identifies the conversation to which the command relates. The four-byte name identifies the token that is returned in the EIBRSRCE field in the EXEC Interface Block (EIB) by a previously run ALLOCATE command.
- PIPLENGTH(data-value)
- Specifies, as a 16-bit binary value, the total length of the list that is specified by PIPLIST.
- PIPLIST(data-area)
- Specifies
the PIP data that is to be sent to the remote region. The PIP list
consists of variable-length records in a single buffer, each containing
a single PIP. Each PIP starts with a two-byte inclusive length field
(LL), followed by a two-byte reserved field, and then the parameter
data. Note: Current AIX® SNA limitations specify that only 16 64-character fields of PIP data, which must not contain space characters, can be transmitted. If the data that is transmitted does not conform to this, the CONNECT PROCESS command apparently succeeds, but the next DTP command returns TERMERR.
- PROCLENGTH(data-value)
- Specifies, as a 16-bit binary value, the length of the process name that is specified by the PROCNAME option.
- PROCNAME(data-area)
- Specifies
the partner process (in CICS® terms, the transaction) that
is to be connected in the remote region.
Process names (PROCNAMEs) that are received by CICS must not exceed four bytes. However, PROCNAMEs that are flowed to other CICS systems or to other APPC applications can be longer than four bytes, depending on the requirements of that system.
Do not embed null (X'00') characters in the transaction name. CICS accepts only as far as the first null character that is found, and ignores the rest of the transaction name.
- STATE(cvda)
- Obtains the state of the current conversation. See STATE.
- SYNCLEVEL(data-value)
- Specifies,
as a 16-bit binary value, the synchronization level for the current
conversation. The possible values for a region are:
- 0
- none
- 1
- confirm
- 2
- syncpoint
If you connect to another region, you cannot specify a level that is greater than that which the remote region can support; otherwise, CICS cannot perform the CONNECT PROCESS command (or a later request if the command is buffered).
Conditions
- INVREQ
- Occurs
for the following conditions, depending on the options that are specified
on the CONNECT PROCESS command:
- A synchronization level other than 0, 1, or 2 has been requested in the SYNCLEVEL option.
- A synchronization level of 2 has been requested but cannot be supported on the session in use.
- An attempt was made to use a distributed transaction processing (DTP) command on a valid non-DTP CONVID.
- A remotely linked-to program attempted to execute a CONNECT PROCESS command that refers to the principal facility.
Default action: Terminates the task abnormally.
- LENGERR
- Occurs
for the following conditions:
- A value outside the range 1 through 32 is supplied in the PROCLENGTH option.
- An out-of-range value is supplied in the PIPLENGTH option.
- A PIP length element (LL) has a value less than 4.
- The sum of the length elements (LLs) in the PIP list does not equal the value that is specified by PIPLENGTH.
Default action: Terminates the task abnormally.
- NOTALLOC
- Occurs
if the specified CONVID value does not relate to a conversation owned
by the application.
Default action: Terminates the task abnormally.
- SYSBUSY
- Occurs
if CICS cannot connect to the remote region that
is named in the previously run ALLOCATE command. This condition occurs
with the CONNECT PROCESSS command only if you specify NOQUEUE or NOSUSPEND
on the ALLOCATE command. (If the ALLOCATE command is specified without
the NOQUEUE or NOSUSPEND qualifier, the SYSBUSY condition occurs on
the ALLOCATE command.) Note that this error is not generated when
TCP/IP is used.
Default action: Terminates the task abnormally.
- SYSIDERR
- Occurs
if either of the following occurs:
- The remote system that is specified in the SYSID option of the previous ALLOCATE command is not available.
- The modename that is specified in the PROFILE option of the previous ALLOCATE command is not defined for the SNA connection.
Note: Mode names do not exist for TCP/IP connections.Therefore, this error is not generated if the SYSID option of the ALLOCATE command is specified as a TCP/IP connection.
Default action: Terminates the task abnormally.