CREATE IPCONN
Define and install an IPCONN in the local CICS region.
Conditions: ILLOGIC, INVREQ, LENGERR, NOTAUTH
Note to COBOL programmers: In
the syntax above, 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 to be used for distributed program link
(DPL) between CICS TS 3.2 or later regions, or transaction routing
between CICS® TS 4.1 or
later regions, or function shipping file control, transient data,
or temporary storage requests between CICS TS 4.2 or
later regions, using IPIC connectivity, 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 definition attributes and TCPIPSERVICE definition attributes. For guidance on defining IPIC connections, see Defining IP interconnectivity links .
A sync point 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 Creating resource definitions for other general rules governing CREATE commands.
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 attributes. See The ATTRIBUTES option for general rules for specifying attributes, and IPCONN definition attributes 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 EXEC CICS CREATE and EXEC CICS 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.