CREATE IPCONN

Define and install an IPCONN in the local CICS® region.

Syntax

Warning: System commands are powerful as they provide information about the state of the system and allow changes to be made to it. System commands should be used only by authorized applications and users.

Activate security checks on commands by specifying the XCMD system initialization parameter and by ensuring that command security checking is active for the transaction (either by specifying CMDSEC(YES) on the TRANSACTION resource definition or by specifying ALWAYS on the CMDSEC system initialization parameter).

CREATE IPCONN

CREATE IPCONN attribute values

Conditions: ILLOGIC, INVREQ, LENGERR, NOTAUTH

NOHANDLE, RESP, and RESP2 are common options that can be added to all EXEC CICS commands to process error conditions. They are not explicitly included in the command syntax diagram and option descriptions. For information about these common options and EXEC CICS command syntax, see EXEC CICS command format and programming considerations.

Note to COBOL programmers: In the preceding syntax, you must use ATTRIBUTES(data-area) instead of ATTRIBUTES(data-value).

Description

The CREATE IPCONN command installs an IPCONN definition with the attributes specified on the command. It does not use a resource definition stored in the CSD. If there is already an IPCONN with the name you specify in the local CICS region, the new definition replaces the old one; if not, the new definition is added.

Note: CREATE IPCONN creates a TCP/IP communication link to a remote system. See also CREATE CONNECTION. Like an IPCONN, a CONNECTION defines a communication link to a remote system, but in this case the connection uses the APPC or LUTYPE6.1 communication protocol (intersystem communication), or the IRC, XM, or XCF/MRO access method (multiregion operation).

Note that for connectivity to be achieved when you install the IPCONN definition:

The TCPIPSERVICE definition named on the TCPIPSERVICE option of this IPCONN definition must also be installed in this region and must specify PROTOCOL(IPIC).
Corresponding IPCONN and TCPIPSERVICE definitions must be installed in the remote region. Characteristics of corresponding IPCONN and TCPIPSERVICE definitions are as follows:
- The HOST option of the IPCONN definition on the remote region must specify this region.
- The PORT option of the IPCONN definition on the remote region must specify the same port number as that specified on the PORTNUMBER option of the local TCPIPSERVICE definition named by this IPCONN.
- The TCPIPSERVICE definition on the remote region (named by the IPCONN definition on the remote region) must specify PROTOCOL(IPIC) and, on its PORTNUMBER option, the same port number as that specified by the PORT option of this IPCONN.

If this IPCONN is used for distributed program link (DPL), transaction routing, function shipping file control, transient data, or temporary storage requests between CICS regions over an IPIC connection, its name must match the 4-character local name (SYSID) by which CICS knows the remote system, padded with four trailing blanks.

Note: The name (SYSID) of the remote, target region, of a DPL request can be specified by using any of the following methods:

The REMOTESYSTEM option of the installed PROGRAM definition
The SYSID option of the EXEC CICS LINK PROGRAM command
The dynamic routing program

For details of the attributes of IPCONN and TCPIPSERVICE definitions, see IPCONN resources and TCPIPSERVICE resource. For guidance on defining IPIC connections, see Defining IPIC connections .

A syncpoint is implicit in CREATE IPCONN processing, except when an exception condition is detected early in processing the command. Uncommitted changes to recoverable resources made up to that point in the task are committed if the CREATE executes successfully, and rolled back if not.

See Using EXEC CICS CREATE commands to define resources for other general rules governing CREATE commands.

The CREATE commands are not audited because their actions are recorded by other messages.

Options

ATTRIBUTES(data-value)

Specifies the attributes of the IPCONN that is being added. The list of attributes must be coded as a single character string using the syntax shown in IPCONN resources. See The ATTRIBUTES option for general rules for specifying attributes, and IPCONN resources for details about specific attributes.

ATTRLEN(data-value)

Specifies the length in bytes of the character string supplied in the ATTRIBUTES option, as a halfword binary value. The length must not exceed 32767 bytes.

IPCONN(data-value)

Specifies the 8-character name of the connection to the remote system (that is, the name of the IPCONN definition to be created).

LOGMESSAGE(cvda)

Specifies whether CICS logs the attributes used for the resource that is created. CVDA values are as follows:

LOG: The resource attributes are logged to the CSDL transient data queue.
NOLOG: The resource attributes are not logged.

Conditions

ILLOGIC

RESP2 values:

2: The command cannot be executed because an earlier CONNECTION or TERMINAL pool definition has not yet been completed.

INVREQ

RESP2 values:

n: There is a syntax error in the ATTRIBUTES string, or an error occurred during either the discard or resource definition phase of the processing. See RESP2 values for CREATE and CSD commands for information on RESP2 values.
7: The LOGMESSAGE CVDA value is not valid.
200: The command was executed in a program defined with an EXECUTIONSET value of DPLSUBSET, or a program invoked from a remote system by a distributed program link without the SYNCONRETURN option.

LENGERR

RESP2 values:

1: The length you have specified in ATTRLEN is negative.

NOTAUTH

RESP2 values:

100: The user associated with the issuing task is not authorized to use this command.
102: The user associated with the task issuing the CREATE IPCONN command is not an authorized surrogate of the user specified in the SECURITYNAME option.