IPCONN attributes

Describes the syntax and attributes of the IPCONN resource.

Syntax

Attributes

APPLID({IPCONNname|applid})

Specifies the application identifier (APPLID) of the remote system. If the remote system is a CICS® region, its APPLID is defined on the APPLID parameter. The value for applid can be up to 8 characters in length and must start with an alphabetic character.

Acceptable characters: `A-Z 0-9 $ @ #` Unless you are using the CREATE command, any lowercase characters that you enter are converted to uppercase.

For connections to an extended recovery facility (XRF) CICS region, specify the generic APPLID of the remote region.

If you do not supply an APPLID, CICS uses the IPCONN name.

When the IPCONN is used to connect to an HA cluster, this field must contain the 1 to 8 character value that identifies the cluster. This value distinguishes this IPCONN from all other installed IPCONNs in the region. The name of an APPLID that points at a specific CICS region cannot have the same name as an HA cluster.

Duplicate APPLIDs follow these rules:

You cannot install two or more IPCONN definitions that specify the same APPLID and the same NETWORKID. The combination of APPLID and NETWORKID can be used to ensure unique naming of systems across the network. See the description of the NETWORKID option.
You can install an IPCONN definition that specifies the same APPLID as the NETNAME of an installed MRO, APPC, or LUTYPE6.1 CONNECTION definition.
If an installed IPCONN definition has the same name as an installed CONNECTION definition, the APPLID of the IPCONN definition must match the NETNAME of the CONNECTION definition. If they do not, the resulting message depends on the situation:
- DFHIS3009 if the error is detected during IPCONN autoinstall
- DFHAM4913 if the error is detected during IPCONN installation
- DFHZC6312 if the error is detected during CONNECTION installation or autoinstall
The IPCONN definition takes precedence over the CONNECTION definition; that is, if an IPCONN and a CONNECTION have the same name, CICS uses the IPCONN.
A CONNECTION definition and an IPCONN definition with the same NETNAME and APPLID do not require the same name to allow the possibility of using a distinct sysid for communication over TCP/IP rather than relying on the CICS default of routing all supported function with the IPCONN, if it exists.

These rules are validated at installation time.

AUTOCONNECT({NO|YES})

Specifies whether sessions are to be established when the IPCONN definition is installed (which can happen during CICS initialization, when you issue a subsequent CEDA INSTALL command, or when you use the CEMT or EXEC CICS SET TCPIP OPEN command to start communication with TCP/IP). If the connection cannot be made at these times because the remote system is unavailable, you can later acquire the link by using the CEMT or EXEC CICS SET IPCONN(name) INSERVICE ACQUIRED command, unless the remote system becomes available in the meantime and initiates communications.

NO

CICS does not try to establish sessions when the IPCONN is installed.

YES

CICS tries to establish sessions when the IPCONN is installed.

For connectivity to be achieved when you install the IPCONN definition, note these conditions:

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:
1. The HOST option of the IPCONN definition on the remote region must specify this region.
2. 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.
3. 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.

You cannot specify AUTOCONNECT(YES) when PORT(NO) is specified.

CERTIFICATE(label)

Specifies the label of an X.509 certificate to be used as a client certificate during the SSL handshake when the IPIC connection is acquired, if the TCPIPSERVICE resource identified by the HOST and PORT definitions is defined with SSL(CLIENTAUTH). If this attribute is omitted, the default certificate defined in the key ring for the CICS region user ID is used.

Certificate labels can be up to 32 bytes long.

The certificate must be stored in a key ring in the external security manager database. For more information, see Building a key ring manually.

If you specify this attribute, you must also specify SSL(YES).

CIPHERS(value)

The CIPHERS attribute can be specified in either of two ways:

Recommended: The name of the SSL cipher suite specification file, which is a z/OS® UNIX file in the security/ciphers subdirectory of the directory that is specified by the USSCONFIG system initialization parameter. For example, if USSCONFIG is set to /var/cicsts/dfhconfig and CIPHERS is set to strongciphers.xml, the fully qualified file name is /var/cicsts/dfhconfig/security/ciphers/strongciphers.xml. For more information, see Creating an SSL cipher suite specification file.
A string of up to 56 hexadecimal digits that is interpreted as a list of up to 28 2-digit cipher suite codes.

When you use the CEDA transaction to define the resource, CICS automatically initializes the attribute with a default list of acceptable codes. For CICS to initialize the attribute, the KEYRING system initialization parameter must be specified in the CICS region where you are running CEDA. If KEYRING is not set, CICS does not initialize the attribute. The default list of 2-digit ciphers is 3538392F3233.

You can reorder the cipher codes or remove them from the initial list. However, you cannot add cipher codes that are not in the default list for the specified encryption level. To reset the value to the default list of codes, delete all of the cipher suite codes. The field is automatically repopulated with the default list.

When you use DFHCSDUP to define the resource, the CIPHERS attribute is not populated with a default value. If the resource is used to establish a secure connection and the CIPHERS attribute is empty, CICS uses the default list of 2-digit ciphers. An INQUIRE on the resource that is created in this manner, returns an empty string for the CIPHERS value.

Any unsupported ciphers are removed at run time. A list of the removed ciphers is reported in messages DFHSO0145 and DFHSO0146.

For more information, see Cipher suites and cipher suite specification files.

DESCRIPTION(text)

You can provide a description of the resource that you are defining in this field. The description text can be up to 58 characters in length. No restrictions apply to the characters that you can use. However, if you use parentheses, ensure that each left parenthesis has a matching right one. If you use the CREATE command, code 2 apostrophes for each single apostrophe in the text.

GROUP(groupname)

Every resource definition must have a GROUP name. The resource definition becomes a member of the group and is installed in the CICS system when the group is installed.

Acceptable characters: `A-Z 0-9 $ @ #` Any lowercase characters you enter are converted to uppercase.

The GROUP name can be up to eight characters in length. Lowercase characters are treated as uppercase characters.

HA({NO|YES})

Specifies whether the IPCONN can be used to connect to a high-availability cluster.

NO: This is the default value. The IPCONN cannot be used to connect to a high-availability cluster.

YES: The IPCONN must connect to a region that is part of a high-availability cluster.

HOST(hostname)

Specifies the host name of the remote system or its IPv4 or IPv6 address. The name can be up to 116 characters long. You can specify IPv4 and IPv6 addresses in a number of acceptable formats. See IP addresses for more information about address formats.

If you specify an IPv6 address (or a host name that resolves to an IPv6 address), ensure that you are operating in a dual-mode (IPv4 and IPv6) environment and that the client or server that you are communicating with is also operating in a dual-mode (IPv4 and IPv6) environment. For more information about IPv6, see Understanding IPv6 and CICS.

The HOST attribute must contain only alphanumeric characters, hyphens (-), colons (:), or periods (.), although you cannot use colons when specifying a character host name instead of an IP address. CICS validates the host name at define time. The host name can be entered in uppercase, lowercase, or mixed case characters, but if a character host name is specified instead of an IP address, the host name is converted to lowercase in the IPCONN definition.

HOST is ignored when the SENDCOUNT attribute is zero. HOST is a required attribute when SENDCOUNT is greater than zero.

IDPROP({NOTALLOWED||OPTIONAL|REQUIRED})

Specifies whether the distributed identity is transmitted to the connected system by the sender. The IDPROP attribute is meaningful only if a connection extends outside a sysplex and is used primarily to prevent distributed identities being transmitted between enterprises. If the connection is between systems in the same sysplex, the connection operates as if IDPROP(OPTIONAL) is specified and ignores any other setting.

Distributed identities flow only if the connected systems meet all the following criteria:

Both systems are participating in identity propagation. See Support and requirements for identity propagation.
The systems are in the same sysplex or are connected by using SSL.
The receiving system has USERAUTH(IDENTIFY) specified in the IPCONN resource definition.

NOTALLOWED: A user ID associated with the sending transaction is sent for requests that use this connection. NOTALLOWED is the default value.
REQUIRED: A distributed identity is required for requests that use this connection. If REQUIRED is specified, the receiving system must support distributed identities. The user ID associated with the sending transaction is not sent.
OPTIONAL: A distributed identity is sent, if available. The user ID associated with the sending transaction is also sent.

INSERVICE({NO|YES})

Specifies the status of the IPCONN resource when it is installed.

NO: The connection cannot receive messages or transmit output.
YES: The connection is available for use.

IPCONN(IPCONNname)

Specifies the name of this IPCONN definition. The name can be up to 8 characters in length.

Acceptable characters: `A-Z 0-9 $ @ #` Unless you are using the CREATE command, any lowercase characters that you enter are converted to uppercase.

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, that use 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: You can specify the name (SYSID) of the remote, target region, of a DPL request in these ways:

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

The IPCONN name can be the same as the name of an installed MRO or APPC CONNECTION definition.

LINKAUTH({CERTUSER|SECUSER})

Specifies how the user ID for link security is established in a CICS system with security initialized (SEC=YES).

CERTUSER

TCP/IP communication with the partner system must be configured for SSL and a certificate must be received from the partner system during SSL handshake.

The IPCONN resource must refer to a TCPIPSERVICE resource that is defined with SSL(CLIENTAUTH).

The received certificate must be defined to the external security manager so that it is associated with a user ID, which is used to establish link security.

SECUSER

Specifies that the user ID specified in the SECURITYNAME attribute is used to establish link security.

The default value is LINKAUTH(SECUSER)

MAXQTIME({NO|seconds})

Specifies the maximum time that queued allocate requests, waiting for free sessions on this connection, can wait before the queue is purged.

Note:

The maximum queuing time is used only if a limit to the length of the queue is specified on the QUEUELIMIT option.
The time limit is applied only when the queue length has reached the QUEUELIMIT value.

NO

CICS maintains the queue of allocate requests that are waiting for a free session. No limit is set on the length of time that requests can remain queued, although the DTIMOUT mechanisms can apply to individual requests.

seconds

The approximate maximum time, in seconds, that allocate requests waiting for a free session can be queued, when this connection appears to be unresponsive; seconds must be in the range 0 - 9999.

When the queue of allocate requests reaches its maximum length (specified by the QUEUELIMIT attribute), and a new allocate request is received for the connection, if the rate of processing for the queue indicates that, on average, the new allocate takes more than the maximum queue time, the queue is purged, and message DFHIS500 is issued. When the queue is purged, queued allocate requests return SYSIDERR.

No further queuing takes place until the connection has successfully freed a session. At this point, CICS issues a DFHIS5001 message and resumes normal queuing.

MIRRORLIFE({REQUEST|TASK|UOW})

Specifies the minimum lifetime of the mirror task for function-shipped file control, transient data, and temporary storage requests received by this region. Normally, mirror tasks are terminated as soon as possible to keep the number of active tasks to a minimum and to avoid holding on to a session for long periods. However, for some applications it is more efficient to retain both the mirror task and the session until the next sync point, although this retention is not required for data integrity. For example, a transaction that issues many READ FILE requests to a remote system might be better served by a single mirror task instead of a separate mirror task for each request. In this way, you can reduce the overhead of allocating sessions on the sending side and attaching mirror tasks on the receiving side. The specified MIRRORLIFE value is not reflected in the lifetime of the mirror task until a file control, transient data, or temporary storage request is function shipped.

REQUEST: The mirror task terminates as soon as possible. For unrecoverable work that does not require a mirror to hold on to a session in the resource-owning region (for example, a non-update READ FILE request) this is after the request has been processed. For unrecoverable work that requires the mirror to hold on to a session (for example, file browse requests), this is as soon as the need for the hold state has been completed (for example, the ENDBR is issued). For recoverable work, the mirror remains until the next sync point. This is the default value.
TASK: The mirror task remains available to the application that issues the remote request until the task of the application ends. This value saves the overhead of reallocating a session and reattaching the mirror task for a subsequent request following a user sync point. Do not specify this value when long-running tasks might be used to function ship file control, transient data, or temporary storage requests because once the session is allocated to a task it is not freed until the task ends, even it is not being used. The session is not available for use by other tasks until it is freed.
UOW: The mirror transaction remains available to the application that issues the remote request until the next sync point is issued. This value saves the overhead of reestablishing communication with the mirror transaction if the application has more function-shipping file control, transient data, or temporary storage requests in this unit of work.

This parameter is valid when it is specified on the IPCONN of the resource-owning region. Specify the TASK or UOW values with this parameter with caution, especially if DPL requests with SYNCONRETURN or TRANSID are used.

NETWORKID(networkID)

Specifies the network ID of the remote system. The remote system network ID is either its z/OS Communications Server NETID or, for VTAM=NO systems, the value of its UOWNETQL system initialization parameter.

If NETWORKID is not specified, CICS assumes that the remote system is in the same network as the local system. In this instance, CICS uses the z/OS Communications Server NETID, or the value of the UOWNETQL system initialization parameter, of this CICS (that is, the CICS on which this definition is installed).

Specify NETWORKID if you want to connect to a remote system that is in a different network and therefore has a different z/OS Communications Server NETID or UOWNETQL value. In this instance, it might be possible for two or more remote systems to have the same APPLID. Although CICS APPLIDs must be unique within a sysplex, you might, for example, want to connect to a system outside the sysplex or in a different sysplex. The combination of APPLID and NETWORKID attributes ensures that the remote system is referred to by a unique name.

The NETWORKID value must match the remote system network ID.

When it is not specified, the NETWORKID value is derived when the IPCONN resource is first installed and is not changed between warm starts, even if the local NETID value changes.

The name can be up to 8 characters in length and follows assembler language rules. It must start with an alphabetic character.

Acceptable characters: `A-Z 0-9 $ @ #` Unless you are using the CREATE command, any lowercase characters that you enter are converted to uppercase.

PORT(NO|number)

Specifies the decimal number of the port on which the remote region listens.

NO

This IPCONN resource is not used for outbound requests (that is, it has no send sessions) when connecting from the CICS Transaction Gateway.

NO is not valid for CICS to CICS IPCONN resources.

NO forces the value of AUTOCONNECT to NO.

number

A value in the range 1 - 65535. The port number is combined with the HOST value to determine the destination for outbound requests on this IPCONN resource.

QUEUELIMIT({NO|number})

Specifies the maximum number of allocate requests that CICS is to queue while waiting for free sessions:

NO: No limit applies to the number of allocate requests that CICS can queue while waiting for a free session.
number: The maximum number of allocate requests, in the range 0 - 9999, that CICS can queue on the connection while waiting for a free session. When the number of queued allocate requests reaches this limit, subsequent allocate requests fail, returning SYSIDERR, until the queue drops below the limit.

RECEIVECOUNT({1|number})

Specifies, in the range 1 - 999, the number of receive sessions; that is, sessions that receive incoming requests. The number of receive sessions that are used depends also on the number of send sessions defined in the remote system. When the connection is established, these values are exchanged and the lower value is used.

SECURITYNAME(name)

Specifies the user ID used to establish link security.

In a CICS system with security initialized (SEC=YES), and with LINKAUTH(SECUSER) in use, the security name is used to establish the authority of the remote system.

The security name must be a valid RACF® user ID on this region. Access to protected resources on this region is based on the RACF user profile and its group membership. If the security name is not a valid RACF user ID when the IPCONN is installed, CICS uses the default user ID for the security name.

The default value is the default user ID.

SENDCOUNT({0|number})

Specifies, in the range 0 - 999, the number of send sessions; that is, sessions that send outgoing requests. The number of send sessions that are used depends also on the number of receive sessions defined in the remote system. When the connection is established, these values are exchanged and the lower value is used. If 0 is specified, this IPCONN can process only incoming work. It cannot send requests to the connected system.

SENDCOUNT(0) is not valid for CICS to CICS IPCONN resources.

SENDCOUNT(0) forces PORT(NO). A SENDCOUNT value greater than zero requires PORT to have a numeric value.

An attempt to acquire an IPCONN resource that has SENDCOUNT(0) fails because no port is defined.

SSL({NO|YES})

Specifies whether Secure Sockets Layer (SSL) is used for encrypting the transmitted data. Note that, when using SSL, MAXSSLTCBs should be set to a value that is at least twice the number of IPIC connections that use SSL by the CICS region.

NO: The Secure Sockets Layer (SSL) is not used. No security checks are applied when the connection is being acquired. No encryption is applied to outbound messages.
YES: If the SEC system initialization parameter is set to YES, the Secure Sockets Layer (SSL) is used. If the TCPIPSERVICE resource identified by the HOST and PORT attributes is defined with SSL(CLIENTAUTH), CICS extracts the client certificate named in the CERTIFICATE attribute, and uses it when acquiring the IPIC connection to the partner system. SSL encryption processing is applied to all messages sent from this IPCONN resource. The level of encryption depends on the value of the CIPHERS option.

TCPIPSERVICE(name)

Specifies the name of a TCPIPSERVICE definition, with PROTOCOL(IPIC), that defines the attributes of the inbound processing for this IPCONN resource.

USERAUTH({LOCAL|IDENTIFY|VERIFY|DEFAULTUSER})

Specifies how the user ID for attach-time user security is established in a CICS system with security initialized (SEC=YES).

LOCAL: CICS does not accept a user ID or password from clients. All requests run under the link user ID or the default user ID if there is no link user ID.
IDENTIFY: Incoming attach requests must specify a user ID. Enter IDENTIFY when the connecting system is trusted to pre-authenticate users, for example, if it is another CICS or CICS TG system.; SSL client authentication must be in use or the connecting system must be in the same sysplex.
VERIFY: Incoming attach requests must specify a user ID and password. Specify VERIFY when connecting systems are unidentified and cannot be trusted.
DEFAULTUSER: CICS does not accept a user ID and password from the partner system. All requests run under the default user ID.

XLNACTION({KEEP|FORCE})

Specifies the action to be taken when a new logname is received from the partner system. Receipt of a new logname indicates that the partner has deleted its recovery information.

KEEP: Recovery information is kept, and no predefined actions are taken for indoubt units of work.
The connection cannot perform new work that requires sync level 2 protocols until all outstanding recoverable work with the partner (that is, indoubt UOWs, or information relevant to UOWs that were indoubt on the partner system under the old logname) is completed, using the CEMT or SPI interface. Therefore, because the connection is being used for CICS-to-CICS communication, which always uses the sync level 2 protocols, the connection cannot be acquired until all outstanding recoverable work with the partner has completed.
FORCE: Before any new work with the new logname is started, the predefined decisions for indoubt units of work (UOWs), as defined by the indoubt attributes of the TRANSACTION definition, are implemented. CICS also deletes any information retained for possible resolution of UOWs that were indoubt on the partner system.
Attention: Data integrity might be compromised if you use this option.

The XLNACTION parameter is ignored for IPCONN definitions used by the CICS Transaction Gateway.