CONNECTION attributes

Describes the syntax and attributes of the CONNECTION resource.

Attributes for APPC connections

Note: VTAM® is now z/OS® Communications Server.

Attributes for MRO connections

Attributes for LU type 6.1 connections

Attributes for indirect connections

ACCESSMETHOD({VTAM|INDIRECT|IRC|XM})

specifies the access method to be used for this connection.

VTAM: Communication between the local CICS® region and the system defined by this connection definition is through z/OS Communications Server. You can use z/OS Communications Server intersystem communication (ISC) for systems that are in different MVS™ images or in different address spaces in the same MVS image.
INDIRECT: Communication between the local CICS system and the system defined by this connection definition is through the system named in the INDSYS operand.
IRC: Communication between the local CICS region and the region defined by this connection definition is through the interregion communication (IRC) program DFHIRP, using the SVC (as opposed to cross-memory (XM)) mode of DFHIRP.
Note: This use of the term IRC is more specific than its general use.
You can use IRC for multiregion operation (MRO) for regions that are in the same MVS image or in different MVS images within a sysplex.
XM: MRO communication between the local CICS region and the region defined by its CONNECTION definition uses MVS cross-memory services. Initial connection is through the interregion communication (IRC) program DFHIRP, using the cross-memory (XM) (as opposed to the SVC) mode of DFHIRP. You can use XM for multiregion operation for regions that are in the same MVS image, or in different MVS images within a sysplex.
Note: The CICS type 3 SVC is still required with XM because DFHIRP is used when the link is opened. For further information about SVCs, see Installing the CICS Type 3 SVC.

MVS cross-memory services are used only if the ACCESSMETHOD of the other end of the link is also defined as XM.

If the MRO partners reside in different MVS images within a sysplex, and the CONNECTION specifies IRC or XM, CICS automatically uses XCF as the access method, and ignores the IRC or XM specification.

Note: You cannot define XCF explicitly; if you want to use XCF, you must specify IRC or XM. See Cross-system multiregion operation (XCF/MRO) for more information about XCF.

ATTACHSEC({LOCAL|IDENTIFY|VERIFY|PERSISTENT|MIXIDPE})

specifies the level of attach-time user security required for the connection.

IDENTIFY: Incoming attach requests must specify a user identifier. Enter IDENTIFY when the connecting system has a security manager; for example, if it is another CICS system.
LOCAL: CICS does not require the client to supply to supply a user identifier, or a password. All requests will run under the userid specified in the SECURITYNAME attribute. If the PROTOCOL attribute on the CONNECTION definition is LU6.1, you must specify LOCAL.
MIXIDPE: Incoming attach requests may be using either or both IDENTIFY or PERSISTENT security types. The security type used depends on the incoming attach request.
PERSISTENT: Incoming attach requests must specify a user identifier and a user password on the first attach request. Subsequent attach requests require only the user identifier. This should be used only between a programmable workstation, (for example, an IBM® Personal Computer) and CICS.
VERIFY: Incoming attach requests must specify a user identifier and a user password. Enter VERIFY when the connecting system has no security manager and hence cannot be trusted. Do not specify VERIFY for CICS-to-CICS communication, because CICS does not send passwords.

AUTOCONNECT({NO|YES|ALL})

For systems using ACCESSMETHOD(VTAM), you specify with AUTOCONNECT(YES) or (ALL) that sessions are to be established (that is, BIND is to be performed). Such sessions are set up during CICS initialization, or when you use the CEMT or EXEC CICS SET VTAM OPEN command to start communication with z/OS Communications Server. If the connection cannot be made at these times because the remote system is unavailable, you must subsequently acquire the link by using the CEMT or EXEC CICS SET CONNECTION(sysid) INSERVICE ACQUIRED command, unless the remote system becomes available in the meantime and itself initiates communications.

For APPC connections with SINGLESESS(NO) specified, CICS tries to bind, on system start-up, the LU services manager sessions in mode group SNASVCMG.

For connection definitions with SINGLESESS(YES) specified, the AUTOCONNECT operand is ignored. Use the AUTOCONNECT operand of the session definition instead.

ALL: On this definition, ALL is equivalent to YES, but you can specify ALL to be consistent with the session definition.
AUTOCONNECT(ALL) should not be specified for connections to other CICS systems, because this can cause a bind-race.
NO: CICS does not attempt to bind sessions when the connection is established.
YES: CICS attempts to bind only contention-winning sessions when the connection is established.

The AUTOCONNECT option is not applicable on an LU6.1 connection definition. For LU6.1 connections, specify AUTOCONNECT(YES) on the SESSIONS definition if you want the connection to be established at initialization or CEDA install. Specify AUTOCONNECT(NO) on the SESSIONS definition if you do not want the connection to be established at initialization or CEDA install.

BINDPASSWORD

This attribute is obsolete, but is supported to provide compatibility with earlier releases of CICS. For more information, see .

BINDSECURITY({NO|YES}) (APPC only)

specifies whether an ESM is being used for bind-time security.

NO: No external bind-time security is required.
YES: If security is active and the XAPPC system initialization parameter is set to YES, CICS attempts to extract the session key from RACF® in order to perform bind-time security. If no RACF profile is available, the bind fails.

CONNECTION(name)

specifies the name of this connection definition. The name can be up to four 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.

This is the name specified as REMOTESYSTEM on file, terminal, transaction, and program definitions. You should not have a terminal definition and a connection definition with the same name.

CONNTYPE({SPECIFIC|GENERIC})

For external CICS interface (EXCI) connections, this specifies the nature of the connection.

GENERIC: The connection is for communication from a non-CICS client program to the CICS system, and is generic. A generic connection is an MRO link with a number of sessions to be shared by multiple EXCI users. For a generic connection you cannot specify the NETNAME attribute.
SPECIFIC: The connection is for communication from a non-CICS client program to the CICS region, and is specific. A specific connection is an MRO link with one or more sessions dedicated to a single user in a client program. For a specific connection, NETNAME is mandatory.

DATASTREAM({USER|3270|SCS|STRFIELD|LMS})

specifies the type of data stream.

LMS: The data stream is a Logical Message Services (LMS) data stream consisting of FMH4s and FMH8s as defined in the LUTYPE6.1 architecture.
SCS: The data stream is an SCS data stream as defined in the LUTYPE6.1 architecture.
STRFIELD: The data stream is a structured field data stream as defined in the LUTYPE6.1 architecture.
USER: Let DATASTREAM default to USER if the data stream is user-defined. If you are communicating between multiple CICS systems, always let DATASTREAM default to USER.
3270: The data stream is a 3270 data stream as defined in the type 6.1 logical unit (LUTYPE6.1) architecture.

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 for each left parenthesis there is a matching right one. If you use the CREATE command, for each single apostrophe in the text, code two apostrophes.

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 that you enter are converted to uppercase.

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

INDSYS(connection)

specifies the name of another CONNECTION that defines an intermediate system used to relay communications between this system and the remote system. The name can be up to four 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.

You may specify an intermediate system only if you specify ACCESSMETHOD(INDIRECT).

INSERVICE({YES|NO})

specifies the status of the connection that is being defined.

NO: The connection can neither receive messages nor transmit input.
YES: Transactions may be initiated and messages may automatically be sent across the connection.

MAXQTIME({NO|seconds})

specifies a time control on the wait time for queued allocate requests waiting for free sessions on a connection that appears to be unresponsive. The maximum queue time is used only if a queue limit is specified for QUEUELIMIT, and then the time limit is applied only when the queue length has reached the queue limit value.

NO

CICS maintains the queue of allocate requests that are waiting for a free session. No time limit is set for the length of time that requests can remain queued (though the DTIMOUT mechanisms can apply to individual requests). In this case, a value of X'FFFF' is passed on the XZIQUE parameter list (in field UEPEMXQT).

seconds

The approximate upper limit on the time that allocate requests can be queued for a connection that appears to be unresponsive. The number represents seconds in the range 0 through 9999.

CICS uses the maximum queue time attribute to control a queue of allocate requests waiting. When the number of queued allocate requests reaches the queue limit (QUEUELIMIT), 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 DFHZC2300 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 DFHZC2301 and resumes normal queuing.

You can also control the queuing of allocate requests through an XZIQUE global user exit program. This allows you to use statistics provided by CICS, which report the state of the link. You can use these statistics, in combination with the queue limit and maximum queue time values you specify, to make more specialized decisions about queues.

The MAXQTIME value is passed to an XZIQUE global user exit program on the XZIQUE parameter list, if the exit is enabled. See XZIQUE for programming information about writing an XZIQUE global user exit program.

You can also specify the NOQUEUE|NOSUSPEND option on the ALLOCATE command to prevent an explicit request being queued. See for programming information about these API options.

NETNAME(netname)

specifies the network name that identifies the remote system. The name can be up to eight characters in length. The name 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.

The NETNAME is the APPLID of the remote system or region, unless you are defining an LUTYPE6.1 or APPC link to a z/OS Communications Server generic resource group.

If you are defining an LUTYPE6.1 link to a generic resource, NETNAME must specify the generic resource name, not the APPLID of one of the group members.
If you are defining an APPC link to a generic resource, NETNAME can specify either the group's generic resource name or the APPLID (member name) of one of the group members. However, if you specify a member name, and this CICS is not itself a member of a CICS generic resource, the connection must always be acquired by this CICS (this CICS being the CICS region in which the connection definition is installed).

For z/OS Communications Server, the APPLID is the label of the remote VTAM VBUILD TYPE=APPL statement.

If you do not supply a NETNAME, the CONNECTION name is used by default.

There are some rules about duplicate NETNAMEs. You cannot have:

Two or more APPC links with the same NETNAME
An APPC link and an LUTYPE6.1 link with the same NETNAME
Two or more IRC connections with the same NETNAME
Two or more remote APPC connections with the same NETNAME.
A remote APPC connection with the same NETNAME as any other connection or local terminal.

You can have:

An IRC connection and an LUTYPE6.1 connection with the same NETNAME
An IRC connection and an APPC connection with the same NETNAME
Two or more LUTYPE6.1 connections with the same NETNAME
Any connection with the same NETNAME as a remote terminal.

For connections that use the z/OS Communications Server LU alias facility:

APPC synclevel 1: If the CICS region supports z/OS Communications Server dynamic LU alias (that is, LUAPFX=xx is specified on the CICS region's APPL statement) this NETNAME is assumed to be in the same network as the CICS region. If it is not the resource must have a local z/OS Communications Server CDRSC definition with LUALIAS=netname defined, where netname must match the NETNAME defined on this CONNECTION definition. Synclevel 1 APPC connections are generally work stations.
Be aware that some synclevel 1 resources may become synclevel 2, depending on how they connect to CICS. For example, if TXSeries® does not use a PPC gateway, the connection is synclevel 1. If it does use a PPC gateway, it is synclevel 2.
APPC synclevel 2 and LUTYPE6.1: This NETNAME is assumed to be unique. CICS matches it against the network name defined in the z/OS Communications Server APPL statement. These connections are generally CICS-to-CICS but could, for example, be TXSeries-connected through a PPC gateway.

Some rules about NETNAME and APPLID:

- If an installed CONNECTION definition has the same name as an installed IPCONN definition, the APPLID of the IPCONN definition must match the NETNAME of the CONNECTION definition. If they do not, the message that results depends on the situation:
- DFHIS3009 if the error is detected during IPCONN autoinstall
- DFHAM4913 if the error is detected during IPCONN install
- DFHZC6312 if the error is detected during CONNECTION install 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 connection.
a CONNECTION and an IPCONN with the same NETNAME and APPLID do not have to have the same name.
This allows the possibility to use a distinct sysid for communication over TCP/IP rather than relying on the CICS default of routing all supported function via the IPCONN, if it exists.

PROTOCOL({APPC|LU61|EXCI|blank})

specifies the type of protocol that is to be used for the link.

APPC (LUTYPE6.2 protocol): Advanced program-to-program communication, or APPC protocol. This is the default value for ACCESSMETHOD(VTAM). Specify this for CICS-CICS ISC.
blank: MRO between CICS regions. You must leave the PROTOCOL blank for MRO, and on the SESSIONS definition you must specify LU6.1 as the PROTOCOL.
EXCI: The external CICS interface. Specify this to indicate that this connection is for use by a non-CICS client program using the external CICS interface.
LU61: LUTYPE6.1 protocol. Specify this for CICS-CICS ISC or CICS-IMS ISC, but not for MRO.

PSRECOVERY({SYSDEFAULT|NONE})

In a CICS region running with persistent sessions support, this specifies whether, and how, LU6.2 sessions are recovered on system restart within the persistent session delay interval.

NONE

All sessions are unbound as out-of-service with no CNOS recovery.

SYSDEFAULT

If a failed CICS system is restarted within the persistent session delay interval, the following actions occur:

User modegroups are recovered to the SESSIONS RECOVOPTION value.
The SNASVCMG modegroup is recovered.
The connection is returned in ACQUIRED state and the last negotiated CNOS state is returned

QUEUELIMIT({NO|number})

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

NO: There is no limit set to the number of allocate requests that CICS can queue while waiting for a free session. In this case, a value of X'FFFF' is passed on the XZIQUE parameter list (in field UEPQUELM).
number: The maximum number of allocate requests, in the range 0 through 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 return SYSIDERR until the queue drops below the limit.
This queue limit is passed to an XZIQUE global user exit program on the XZIQUE parameter list if the exit is enabled.

You can also control the queuing of allocate requests through the MAXQTIME attribute, and through an XZIQUE global user exit program. See the MAXQTIME attribute for more information about controlling queues.

Note: BIND re-negotiation is not triggered, even if there are unused secondary sessions. Unless the CEMT SET MODE command is used to force re-negotiation, the queuelimit will come into play as soon as all the primary sessions are in use.

RECORDFORMAT({U|VB})

specifies the type of SNA chain.

U: Let RECORDFORMAT default to U if the SNA chain is a single, unblocked stream of data. You can have private block algorithms within the SNA chain. Let RECORDFORMAT default to U if you are communicating between multiple CICS systems.
VB: The SNA chain is formatted according to the VLVB standard as defined in the LUTYPE6.1 architecture.

REMOTENAME(connection)

specifies the name by which the APPC connection for transaction routing is known in the system or region that owns the connection. The name can be up to four 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.

The remote system or region can be an APPC device (see APPC devices for transaction routing).

REMOTESYSNET(netname)

specifies the network name (APPLID) of the system that owns the connection. The name can be up to eight characters in length. It follows assembler language rules, 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.

Use REMOTESYSNET when transaction routing to remote APPC systems or devices, and there is no direct link between the region in which this definition is installed and the system that owns the connection to the remote device. You do not need to specify REMOTESYSNET if:

You are defining a local connection (that is, REMOTESYSTEM is not specified, or specifies the sysid of the local system).
REMOTESYSTEM names a direct link to the system that owns the connection. However, there is one special case: if the connection-owning region is a member of a z/OS Communications Server generic resources group and the direct link to it is an APPC connection, you may need to specify REMOTESYSNET. REMOTESYSNET is needed in this case if the NETNAME specified on the CONNECTION definition for the direct link is the generic resource name of the connection-owning region (not the applid).

REMOTESYSTEM(connection)

specifies the name that identifies the intercommunication link to the system that owns the connection. The name can be up to four 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.

This is the CONNECTION name on the connection definition for the intercommunication link.

REMOTESYSTEM is used for transaction routing to remote APPC systems or devices. If it is not specified, or if it is specified as the sysid of the local system, this connection is local to this system. If the name is that of another system, the connection is remote. You can therefore use the same definition for the connection in both the local system and a remote system.

If there are intermediate systems between this CICS and the region that owns the (connection to the) device, REMOTESYSTEM should specify the first link in the path to the device-owning region. If there is more than one possible path, it should specify the first link in the preferred path.

SECURITYNAME(userid)

For APPC and LU6.1 links only, this is the security name of the remote system.

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

Note: If USERID is specified in the SESSIONS definition associated with the connection definition, it overrides the userid specified in the SECURITYNAME attribute, and is used for link security.

The security name (or USERID on the sessions definition) must be a valid RACF userid on your system. Access to protected resources on your system is based on the RACF user profile and its group membership.

SINGLESESS({NO|YES})

specifies whether the definition is for an APPC terminal on a single session APPC link to CICS.

NO: The definition is not for a single session APPC link to CICS.
YES: The definition is for an APPC terminal on a single session APPC link to CICS.

The MODENAME attribute of the SESSIONS definition can be used to supply a modename for the single session mode set.

An APPC single session terminal can also be defined as a TERMINAL-TYPETERM definition. Both the TERMINAL-TYPETERM definition and the CONNECTION definition can be autoinstalled. If you are considering using autoinstall, see Autoinstalling z/OS Communications Server terminals.

USEDFLTUSER({NO|YES}) (APPC and MRO only)

specifies the action that is taken when an inbound FMH5 does not contain the security information implied by the ATTACHSEC attribute.

NO: The attach request is rejected, and a protocol violation message is issued.
YES: The attach is accepted, and the default user ID is associated with the transaction.

For more information, see Implementing LU6.2 security and Implementing MRO security.

XLNACTION({KEEP|FORCE}) (APPC and MRO only)

XLNACTION 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.

Note: MRO here covers connections with ACCESSMETHOD set to either IRC or XM.

FORCE

The predefined decisions for indoubt UOWs (as defined by the indoubt attributes of the transaction definition) are implemented, before any new work with the new logname is started. CICS also deletes any information retained for possible resolution of UOWs that were indoubt at the partner system.

Attention: Data integrity may be compromised if you use this option.

KEEP

Recovery information is kept, and no action is taken for indoubt units of work.

For IRC, the connection continues with new work. Resolve indoubt UOWs using the CEMT or SPI interface.

For APPC, the connection is unable to perform new work that requires synclevel 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.