SESSIONS attributes

Describes the syntax and attributes of the SESSIONS resource.

Attributes for APPC sessions

Attributes for MRO and LU61 sessions

Attributes for EXCI sessions

AUTOCONNECT({NO|YES|ALL})

specifies how connections are to be established. What you have to specify for LU6.1 and APPC sessions is discussed below:

APPC sessions

For a z/OS® Communications Server-connected system that has AUTOCONNECT(YES) or (ALL) on the connection definition:

NO: CICS® does not attempt to bind any sessions when the connection is established. However, one or more user sessions may be allocated as part of any ACQUIRE CONNECTION processing which takes place.
YES or ALL: A contention-winner session is established (that is, BIND is performed) during CICS initialization, or when communication with z/OS Communications Server is started using the CEMT SET VTAM® OPEN command. If the connection cannot be made at this time because the remote system is unavailable, the link must be subsequently acquired using the CEMT SET CONNECTION(sysid) INSERVICE ACQUIRED command, unless the remote system becomes available in the meantime and itself initiates communications.
AUTOCONNECT(ALL) should not be specified for sessions to other CICS systems, because this can cause a bind race.

For a z/OS Communications Server-connected system that has AUTOCONNECT(NO) on the CONNECTION definition:

ALL: All sessions, not just contention winners, are established when the connection is acquired by issuing CEMT SET CONNECTION(name) ACQUIRED, or when the remote system itself initiates communication.
NO: CICS does not attempt to bind any sessions when the connection is established. However, one or more user sessions may be allocated as part of any ACQUIRE CONNECTION processing that takes place.
YES: Contention-winner sessions are established when the connection is acquired by issuing CEMT SET CONNECTION(sysid) ACQUIRED, or when the remote system itself initiates communication.

LU6.1 sessions

Specify AUTOCONNECT(YES) on the SESSIONS if you want the connection to be established at initialization or CEDA install.

Specify AUTOCONNECT(NO) on the SESSIONS if you do not want the connection to be established at initialization or CEDA installation.

BUILDCHAIN({YES|NO})

specifies whether CICS is to perform chain assembly before passing the input data to the application program.

NO: Any TIOA received by an application program from this logical unit contains one request unit (RU).
YES: Any terminal input/output area (TIOA) received by an application program from this logical unit contains a complete chain.

CONNECTION(connection)

specifies the name of the connection definition that you want to use with this session 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.

Note that the CONNECTION definition must be in the same GROUP as the SESSIONS definition.

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.

DISCREQ({NO|YES})

specifies whether disconnect requests are to be honored. DISCREQ applies to LUTYPE6.1 ISC sessions, but not to MRO sessions where CICS is not dealing with z/OS Communications Server devices.

DISCREQ does not apply to APPC (LUTYPE6.2) sessions. When APPC is used, individual sessions are acquired as transactions need them, then are subsequently freed. Because it is possible to have multiple sessions between APPC logical units, there should never be a problem of one request holding up another. It is not possible to disconnect an individual APPC session; instead, you can issue a CEMT SET CONNECTION RELEASED command.

NO: CICS is not to honor a disconnect request for a z/OS Communications Server device.
YES: CICS is to honor a disconnect request for a z/OS Communications Server device, and issue a z/OS Communications Server CLSDST macro instruction to terminate the z/OS Communications Server session with that logical unit.
CESF LOGOFF or GOODNIGHT commands issued from the terminal also cause disconnection if you specify DISCREQ(YES).

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.

INSERVICE

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

IOAREALEN({0|value1},{0|value2})

specifies the length, in bytes, of the terminal input/output area to be used for processing messages transmitted on the MRO link.

value1: value1 specifies the minimum size of a terminal input/output area to be passed to an application program when a RECEIVE command is issued.
value2: If value2 is not specified, or is less than value1, it defaults to the value of value1.
You can specify value2 as greater than or equal to value1. In this case, when the size of an input message exceeds value1, CICS uses a terminal input/output area (TIOA) value2 bytes long. When a transaction is attached on an MRO link, CICS uses a TIOA that is long enough to contain the initial input message. Otherwise, if the input message size also exceeds value2, the node abnormal condition program sends an exception response to the terminal.

You can waste both real and virtual storage by specifying an IOAREALEN value that is too large for most messages transmitted on your MRO link. On the other hand, if you specify an IOAREALEN value that is either zero or smaller than most of your messages, excessive FREEMAIN and GETMAIN activity may occur. This results in additional processor requirements.

MAXIMUM({1|value1},{0|value2}) (APPC only)

specifies the maximum number of sessions that are to be supported for the modeset. Value1 must be greater than or equal to value2.

1|value1: The maximum number of sessions in the group. This value can be in the range 1 through 999. The default is 1.
0|value2: The maximum number of sessions that are to be supported as contention winners. This value can be in the range 0 to 999. The default is 0. Note that this operand has no meaning for a single session connection.

SNA allows some resources (for example, switched lines) to be defined in the network as limited resources. At bind time, z/OS Communications Server indicates to CICS whether the bind is over a limited resource. When a CICS task frees a session across a limited resource, CICS unbinds the session if no other task wants to use it.

If the sessions are to use limited resources, specify MAXIMUM(value1,0). This causes any unbound session to be reset so that either side can then bind it as a winner when it is next required.

For further information on the effects of the MAXIMUM option, and the use of limited resources, see Effects of the MAXIMUM option of the SESSIONS resource

MODENAME(modename) (APPC only)

specifies the name that identifies a group of sessions for use on an APPC connection. The name can be up to eight characters in length, and must be the name of a z/OS Communications Server LOGMODE entry defined to z/OS Communications Server. It must not be the reserved name SNASVCMG. If you omit the modename it defaults to blanks. See Defining groups of APPC sessions for more information about z/OS Communications Server modenames.

The MODENAME must be unique for each group of sessions defined for any one intersystem link. That is, the MODENAME must be unique among the SESSIONS definitions related to one CONNECTION definition. It is passed to z/OS Communications Server as the LOGMODE name.

NEPCLASS({0|tranclass})

specifies the transaction class for the node error program. This value acts as the default.

0: This results in a link to the default node error program module.
tranclass: The transaction class for the (nondefault) node error program module. The value can be in the range 1 through 255. For programming information about the node error program, see Writing a node error program.

The NEPCLASS attribute is ignored for SNASVCMGR sessions.

NETNAMEQ(netnameq)

specifies the name by which the remote IMS system knows this particular session. This is used for CICS-IMS sessions. The name can be up to eight characters in length. The acceptable characters are: A-Z 0-9 $ @ # . / - _ % & ¢ ? ! : | " = ¬ , ; < and >. Lowercase characters are converted to uppercase except when using the CREATE command.

OPERID

OPERPRIORITY

OPERRSL

OPERSECURITY

These attributes ares obsolete, but are supported to provide compatibility with earlier releases of CICS.

PROTOCOL({APPC|LU61|EXCI})

specifies the type of protocol that is to be used for an intercommunication link (ISC or MRO).

APPC (LUTYPE6.2): Advanced program-to-program communication (APPC) protocol. Specify this for CICS-CICS ISC.
EXCI: The external CICS interface. Specify this to indicate that the sessions are for use by a non-CICS client program using the external CICS interface.
LU61: LUTYPE6.1 protocol. Specify this for CICS-CICS ISC, for CICS-IMS, or for MRO.

RECEIVECOUNT(number)

For MRO, and z/OS Communications Server LU6.1 sessions, and for sessions with EXCI clients, specifies the number of receive sessions; that is, sessions that normally receive before sending:

MRO receive sessions (including sessions with EXCI clients) always receive before sending.
z/OS Communications Server LU6.1 receive sessions normally receive before sending, but may send before receiving when there is a shortage of suitable send sessions.

If you do not specify the RECEIVECOUNT attribute, there are no receive sessions.

The number of receive sessions you can specify depends upon the length of the prefix specified in the RECEIVEPFX attribute:

If you use the default receive prefix (<), or your own 1-character prefix, you can specify 1 through 999 receive sessions.
If you use a 2-character prefix, you can specify 1 through 99 receive sessions.

You should also ensure that the value specified matches the number of send sessions in the partner system:

If the partner is another CICS system, the value should match the SENDCOUNT specified in the partner system.
If the partner is an EXCI client, you cannot specify the number of send sessions in the partner. However, there is an upper limit of send sessions in an EXCI address space. When this limit is reached, IRP rejects further requests for a session with SYSTEM_ERROR reason code 608. For information about how the limit is specified for the CICS system, see EXCI pipe allocation.

RECEIVEPFX({<|prefix})

specifies a 1-or 2-character prefix that CICS is to use as the first one or two characters of the receive session names (the names of the terminal control table terminal entries (TCTTEs) for the sessions).

Prefixes must not cause a conflict with an existing connection or terminal name.

< (MRO and EXCI sessions)

For MRO and EXCI sessions, if you do not specify your own receive prefix, CICS enforces the default prefix—the less-than symbol (<), which is used in conjunction with the receive count to generate receive session names.

CICS creates the last three characters of the session names. The acceptable characters are A-Z 1-9. These 3-character identifiers begin with the letters AAA, and continue in ascending sequence until the number of session entries reaches the limit set by the RECEIVECOUNT value. Note that receive session names are generated after the send sessions, and they follow in the same sequence.

For example, if the last session name generated for the send sessions is >AAJ, using the default sendprefix (>) CICS generates the receive session names as <AAK, <AAL, <AAM, and so on. (This method of generation of session identifiers is the same as for APPC sessions, except for the initial prefix symbol.)

If you use more than 46656 sessions (<AAA to <999), CICS allocates the next range of AAA< to 999<, again in a similar manner to APPC sessions.

A region with more than 46656 sessions might not perform well. You should consider the alternative of increasing the number of CICS regions.

Although you can define up to 93312 MRO sessions there is a current restriction that prevents you from attempting to acquire more than 65535 sessions in one attempt. This might occur when CICS starts or for a CEDA install for more than 65536 sessions if ALL the partner regions are up and running. Further sessions can be acquired later.

Note: If you specify your own prefix, CICS generates the session names in the same way as it does for LUTYPE6.1 sessions.

prefix (LUTYPE6.1 sessions)

If the sessions are on LUTYPE6.1 ISC connections, you must specify a 1-or 2-character prefix. Do not use the default < symbol for LUTYPE6.1 sessions.

For LUTYPE6.1 sessions (and MRO if you specify your own 1-or 2-character prefix), CICS generates session names by appending a number to the prefix, either in the range 1 through 99, or 1 through 999. The number begins with 1 and is incremented by 1 until the specified RECEIVECOUNT is reached.

RECEIVESIZE({4096|number})

specifies the maximum z/OS Communications Server request unit (RU) size that these sessions are capable of receiving. The value must be between 1 and 30720 for LU61 sessions, or 256 and 30720 for APPC sessions. The default is 4096.

The value specified is transmitted to the connected logical unit. This value may be rounded down by CICS, depending on what value you specified, because the value must be transmitted in an architected form. The value may be negotiated down still further at BIND time.

If CICS is the secondary LU session, this indicates the maximum z/OS Communications Server request unit (RU) size that these sessions are capable of sending.

RECOVNOTIFY

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

RECOVOPTION({SYSDEFAULT|CLEARCONV| RELEASESESS|UNCONDREL|NONE})

This option applies to the recovery of sessions in a CICS region running with z/OS Communications Server persistent sessions, or with XRF.

z/OS Communications Server persistent sessions: In a CICS region running with persistent session support, this option specifies how you want CICS to recover the session, and return the terminal to service on system restart within the persistent session delay interval.

XRF: In a CICS region running with XRF support, this option specifies how you want CICS to recover the session, and return the terminal to service after an XRF takeover.

For all recovery options other than NONE, if the action taken is a z/OS Communications Server UNBIND, the UNBIND is followed by a z/OS Communications Server SIMLOGON.

CLEARCONV

z/OS Communications Server persistent sessions: CLEARCONV is not supported for APPC sessions. It defaults to SYSDEFAULT.

XRF: If AUTOCONNECT(YES) is specified, the session is restarted. If AUTOCONNECT(NO) is specified, the session is unbound.

NONE

z/OS Communications Server persistent sessions: In a CICS region running with persistent sessions support, this specifies that the session is not to be recovered at system restart within the persistent session delay interval: in effect, the sessions on the modegroup have no persistent sessions support. LU6.2 sessions are unbound and the modegroup CNOS value is reset to zero. After system restart, the session is reconnected automatically if you specify AUTOCONNECT(YES).

XRF: In a CICS region running with XRF support, this specifies that the logon state is not tracked by the alternate system, and the terminal session is not automatically recovered after a takeover; in effect, the terminal has no XRF support. After takeover, the terminal is reconnected automatically by the alternate system, if you specify AUTOCONNECT(YES).

RELEASESESS

z/OS Communications Server persistent sessions: RELEASESESS is not supported for APPC sessions. It defaults to SYSDEFAULT.

XRF: If AUTOCONNECT(YES) is specified, the session is restarted. If AUTOCONNECT(NO) is specified, the session is unbound.

SYSDEFAULT

z/OS Communications Server persistent sessions: In a CICS region running with persistent sessions support, this specifies that CICS is to select the optimum procedure to recover a session on system restart within the persistent session delay interval, depending on the session activity and on the characteristics of the terminal.

Although sessions are recovered, any transactions in-flight at the time of the failure are abended and not recovered. Transactions are also abended if the recovered session is being used by another CICS region over an APPC connection.

CICS recovers the session with the least possible impact, in one of the following ways:

If the session was not busy at the time that CICS failed, no action is required.
If the session was busy at the time that CICS failed, CICS issues a DEALLOCATE(ABEND) (equivalent to an EXEC CICS ISSUE ABEND) for the APPC conversation in progress at the time of the failure.
If neither of these events apply, the session is unbound.

XRF: If AUTOCONNECT(YES) is specified, the session is restarted. If AUTOCONNECT(NO) is specified, the session is unbound.

UNCONDREL

Requires CICS to send an UNBIND request to release the active session. The UNBIND is sent whether or not the session was busy at the time of system restart (in the case of persistent sessions support) or takeover (in the case of XRF).

RELREQ({NO|YES})

specifies whether CICS is to release the logical unit upon request by another z/OS Communications Server application program.

SENDCOUNT(number)

For MRO, and z/OS Communications Server LU6.1 sessions only, specifies the number of send sessions; that is, sessions that normally send before receiving:

MRO send sessions always send before receiving
z/OS Communications Server LU6.1 send sessions normally send before receiving, but may receive before sending when there is a shortage of suitable receive sessions

The number of send sessions you can specify depends upon the length of the prefix specified in the SENDPFX attribute:

If you use the default send prefix (>), or your own 1-character prefix, you can specify 1 through 999 send sessions
If you use a 2-character prefix, you can specify 1 through 99 send sessions.

You should also ensure that the value specified matches the number of receive sessions in the partner system:

If the partner is another CICS system, the value should match the RECEIVECOUNT specified in the partner system

If you do not specify the SENDCOUNT attribute, there are no send sessions. Do not specify the SENDCOUNT attribute when the partner is an EXCI client

SENDPFX({>|prefix})

specifies a 1-or 2-character prefix that CICS is to use as the first one or two characters of the send session names (the names of the terminal control table terminal entries (TCTTEs) for the sessions).

Prefixes must not cause a conflict with an existing connection or terminal name.

> (MRO sessions)

For MRO sessions, if you do not specify your own send prefix, CICS enforces the default prefix—the greater-than symbol (>), which is used in conjunction with the send count to generate send session names.

CICS creates the last three characters of the session names from the alphanumeric characters A through Z, and 1 through 9. These 3-character identifiers begin with the letters AAA, and continue in ascending sequence until the number of session entries reaches the limit set by the SENDCOUNT value.

For example, using the default prefix (>), CICS generates session names as >AAA, >AAB, >AAC, and so on. If you use more than 46656 sessions (>AAA to >999), CICS allocates the next range of AAA> to 999>. (This method of generation of session identifiers is the same as for APPC sessions, except for the initial symbol.)

A region with more than 46656 sessions might not perform well. You should consider the alternative of increasing the number of CICS regions.

Although you can define up to 93312 MRO sessions there is a current restriction that prevents you from attempting to acquire more than 65535 sessions in one attempt. This might occur during CICS start up or for a CEDA install for more than 65536 sessions if ALL the partner regions are up and running. Further sessions can be acquired later.

Note: If you specify your own prefix, CICS generates the session names in the same way as it does for LUTYPE6.1 sessions.

prefix (for LUTYPE6.1 sessions)

If the sessions are on LUTYPE6.1 ISC connections, you must specify a 1-or 2-character prefix. Do not use the default > symbol for LUTYPE6.1 sessions.

For LUTYPE6.1 sessions (and MRO if you specify your own 1-or 2-character prefix), CICS generates session names by appending a number to the prefix, either in the range 1 through 99, or 1 through 999. The number begins with 1 and are incremented by 1 until the specified SENDCOUNT is reached.

SENDSIZE({4096|number})

specifies the maximum z/OS Communications Server request unit (RU) size that these sessions are capable of sending. The value must be between 1 and 30720 for LU61 sessions, or between 256 and 30720 for APPC sessions. The default is 4096. The value may be negotiated down at bind time. Increasing the value of SENDSIZE causes more storage to be allocated for the session but may decrease the number of physical messages sent between the two nodes.

If CICS is the secondary LU session, this attribute indicates the maximum z/OS Communications Server request unit (RU) size that these sessions are capable of receiving. The value must be between 256 and 30720.

SESSIONS(name)

specifies the name of this SESSIONS definition. The name can be up to eight characters in length.

Acceptable characters:

A-Z a-z 0-9 $ @ # . / - _ % & ? ! : | " = ¬ , ; < >

This name is used to identify the SESSIONS definition on the CSD file. It is not used within the active CICS system.

SESSNAME(sessname)

specifies the symbolic identification to be used as the local half of a session qualifier pair in a CICS intercommunication parallel session. The name can be up to four characters in length.

Acceptable characters:

A-Z a-z 0-9 $ @ # . / - _ % & ? ! : | " = ¬ , ; < >

SESSPRIORITY({0|priority})

specifies the terminal priority. This decimal value (0 through 255) is used in establishing the overall transaction processing priority. (Transaction processing priority is equal to the sum of the terminal priority, transaction priority, and operator priority; this must not exceed 255.)

TRANSACTION

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

USERAREALEN({0|number})

Specify the length, in bytes, of the user area for this session, in the range 0 through 255. It should be made as small as possible. The terminal user area is initialized to zeros when the session is installed.

The terminal user area might be located in 31-bit storage or in 24-bit storage, depending on the value of the TCTUALOC system initialization parameter. The default is that the terminal user area can be in either 31-bit storage or 24-bit storage, but CICS uses 31-bit storage wherever possible. If you require the terminal user area to be in 24-bit storage, because you have application programs that are not capable of 31-bit addressing, specify the system initialization parameter TCTUALOC=BELOW for the CICS region.

USERID(userid)

specifies a user identifier used for sign-on (SEC=YES) and referred to in security error messages, security violation messages, and the audit trail. It must be a valid userid defined to the security manager, or operators will be unable to sign on. All access to protected resources depends on USERID.

This USERID overrides a SECURITYNAME specified on the CONNECTION definition.

The name can be up to eight 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.