Attributes for MRO CONNECTION

Describes the syntax and attributes of CONNECTION resource definitions for MRO connections.

For other types of connection, see:

You define an MRO link by using one CONNECTION resource definition and its associated parallel sessions by using one SESSIONS resource definition. The following attributes are significant:

Attribute	On CONNECTION resource definition	On SESSIONS resource definition
ACCESSMETHOD	IRC or XM. IRC is used to open and close the links.	n/a
PROTOCOL	Leave blank	LU61
SENDPFX, SENDCOUNT, RECEIVEPFX, RECEIVECOUNT	n/a	In one SESSIONS resource definition, you specify a number of send sessions and a number of receive sessions. The values that you specify in these attributes are used to determine the names of the TCT entries that are created when the resource definition is installed. (See Installing CONNECTION resource definitions.)

Syntax of MRO CONNECTION

Attributes of MRO CONNECTION

ACCESSMETHOD({IRC|XM})

Specifies the access method to be used for this connection. For an MRO connection, specify this as IRC for interregion communication or XM for cross-memory services. IRC is used to open and close the links.

IRC: Communication between the local CICS® region and the region defined by this CONNECTION resource definition is through the interregion communication (IRC) program DFHIRP, using the SVC (as opposed to cross-memory (XM)) mode of DFHIRP. Note that the use of IRC here is more specific than its general use. You can use IRC for multiregion operation (MRO) for regions that are in the same z/OS® 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 z/OS 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 SVCs.

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 z/OS images within a sysplex, and the CONNECTION resource definition 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|MIXIDPE||PERSISTENTVERIFY})

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

LOCAL: CICS does not require the client to supply a user identifier, or a password. All requests run under the user ID that you specify on the SECURITYNAME attribute.
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.
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 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|ALL|YES})

Specifies how sessions are to be established (that is, BIND is to be performed).

ALL: On the CONNECTION resource definition, ALL is equivalent to YES, but you can specify ALL to be consistent with the session resource definition.
Do not specify AUTOCONNECT(ALL) 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.

CONNECTION(name)

Specifies the name of this CONNECTION resource definition. The name can be up to four characters in length.

Acceptable characters:

A-Z 0-9 $ @ #

Valid characters are listed as they render when the code page is IBM®-037. If a different EBCDIC code page is used, be aware of variant characters, as documented in Variant characters.

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 resource definitions. You should not have a TERMINAL resource definition and a CONNECTION resource definition with the same name.

CONNTYPE({SPECIFIC|GENERIC})

Specifies the nature of the connection.

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.

A user is a program that has issued an Initialize_User request (or for which an Initialize_User request has been issued), with a unique name per TCB. For example:

A simple client program running under z/OS can be a single user of the external CICS interface.
A client program running under z/OS can open several pipes and issue external CICS interface calls over them sequentially, on behalf of different vendor packages. In this case, from the viewpoint of the client program, each of the packages is a user, identified by a unique user name. Thus a single client program can operate on behalf of multiple users.
A program running under z/OS can attach several TCBs, under each of which a vendor package issues external CICS interface calls on its own behalf. Each package is a client program in its own right, and runs under its own TCB. Each is also a user, with a unique user name.

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

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

Specifies the type of data stream.

3270: The data stream is a 3270 data stream as defined in the type 6.1 logical unit (LUTYPE6.1) architecture.
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.

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. There are no restrictions on the characters that you can use. However, if you use parentheses, ensure that for each left parenthesis there is a matching right parenthesis. 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 $ @ #

Valid characters are listed as they render when the code page is IBM-037. If a different EBCDIC code page is used, be aware of variant characters, as documented in Variant characters.

Any lowercase characters that you enter are converted to uppercase.

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

INSERVICE({YES|NO})

Specifies the status of the connection that is being defined.

NO: The connection cannot receive messages or transmit input.
YES: Transactions can be initiated and messages can be sent automatically 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 (deadlock timeout) 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 maximum 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 exit for managing MRO and APPC intersystem queues.

You can also specify the NOQUEUE|NOSUSPEND option on the ALLOCATE command to prevent an explicit request being queued. See ALLOCATE (APPC).

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 $ @ #

Valid characters are listed as they render when the code page is IBM-037. If a different EBCDIC code page is used, be aware of variant characters, as documented in Variant characters.

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 APPC link to a z/OS Communications Server generic resource group. In which case, 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.

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 workstations.; Be aware that some synclevel 1 resources may become synclevel 2, depending on how they connect to CICS. For example, if CICS TX 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 CICS TX-connected through a PPC gateway.

Some rules about NETNAME and APPLID:

If an installed CONNECTION resource definition has the same name as an installed IPCONN resource definition, the APPLID of the IPCONN resource definition must match the NETNAME of the CONNECTION resource 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 resource 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(blank)

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

blank: Leave the PROTOCOL blank here for MRO. On the SESSIONS definition, specify LU61 as the PROTOCOL.

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.

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 queue limit will come into play as soon as all the primary sessions are in use.

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.

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.

USEDFLTUSER({NO|YES})

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.

XLNACTION({KEEP|FORCE})

XLNACTION specifies the action to be taken when a new logname

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.

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 workstations.; Be aware that some synclevel 1 resources may become synclevel 2, depending on how they connect to CICS. For example, if CICS TX 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 CICS TX-connected through a PPC gateway.

Some rules about NETNAME and APPLID:

If an installed CONNECTION resource definition has the same name as an installed IPCONN resource definition, the APPLID of the IPCONN resource definition must match the NETNAME of the CONNECTION resource 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 resource 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.

is received from the partner system. Receipt of a new logname indicates that the partner has deleted its recovery information.

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