SESSIONS definition attributes

Read syntax diagramSkip visual syntax diagram
>>-SESSIONS(name)--GROUP(groupname)--+-------------------+------>
                                     '-DESCRIPTION(text)-'   

   .-PROTOCOL(APPC)--| Attributes for APPC sessions |---------.   
>--+----------------------------------------------------------+-->
   +-PROTOCOL(LU61)--| Attributes for MRO and LU61 sessions |-+   
   '-PROTOCOL(EXCI)--| Attributes for EXCI sessions |---------'   

   .-AUTOCONNECT(NO)--.  .-BUILDCHAIN(YES)-.   
>--+------------------+--+-----------------+-------------------->
   +-AUTOCONNECT(ALL)-+  '-BUILDCHAIN(NO)--'   
   '-AUTOCONNECT(YES)-'                        

                           .-NEPCLASS(0)---------.   
>--CONNECTION(connection)--+---------------------+-------------->
                           '-NEPCLASS(tranclass)-'   

   .-RECEIVESIZE(4096)---.  .-RECOVOPTION(SYSDEFAULT)--.   
>--+---------------------+--+--------------------------+-------->
   '-RECEIVESIZE(number)-'  +-RECOVOPTION(CLEARCONV)---+   
                            +-RECOVOPTION(NONE)--------+   
                            +-RECOVOPTION(RELEASESESS)-+   
                            '-RECOVOPTION(UNCONDREL)---'   

   .-RELREQ(NO)--.  .-SENDSIZE(4096)---.   
>--+-------------+--+------------------+------------------------>
   '-RELREQ(YES)-'  '-SENDSIZE(number)-'   

   .-SESSPRIORITY(0)--------.  .-USERAREALEN(0)------.   
>--+------------------------+--+---------------------+---------->
   '-SESSPRIORITY(priority)-'  '-USERAREALEN(number)-'   

>--+----------------+------------------------------------------><
   '-USERID(userid)-'   

Read syntax diagramSkip visual syntax diagram
Attributes for APPC sessions

   .-MAXIMUM(1,0)-----------.                           
|--+------------------------+--+--------------------+-----------|
   '-MAXIMUM(value1,value2)-'  '-MODENAME(modename)-'   

Read syntax diagramSkip visual syntax diagram
Attributes for MRO and LU61 sessions

   .-DISCREQ(NO)--.  .-IOAREALEN(0,0)-----------.   
|--+--------------+--+--------------------------+--------------->
   '-DISCREQ(YES)-'  '-IOAREALEN(value1,value2)-'   

>--+--------------------+--------------------------------------->
   '-NETNAMEQ(netnameq)-'   

     .--------------------------.                                                  
     V                          |  .-RECEIVEPFX(<)------.  .-SENDPFX(>)------.     
>--+---+-RECEIVECOUNT(number)-+-+--+--------------------+--+-----------------+-+--|
   |   '-SENDCOUNT(number)----'    '-RECEIVEPFX(prefix)-'  '-SENDPFX(prefix)-' |   
   '-SESSNAME(sessname)--+-RECEIVECOUNT(1)-+-----------------------------------'   
                         '-SENDCOUNT(1)----'                                       

Read syntax diagramSkip visual syntax diagram
Attributes for EXCI sessions

   .-IOAREALEN(0,0)-----------.                         
|--+--------------------------+--RECEIVECOUNT(number)----------->
   '-IOAREALEN(value1,value2)-'                         

   .-RECEIVEPFX(<)------.   
>--+--------------------+---------------------------------------|
   '-RECEIVEPFX(prefix)-'   

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 VTAM®-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 VTAM 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 caused a bind race.

For a VTAM-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 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 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 one. 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 VTAM 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 VTAM device.
YES
CICS is to honor a disconnect request for a VTAM device, and issue a VTAM CLSDST macro instruction to terminate the VTAM 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 lower case characters you enter are converted to upper case.

The GROUP name can be up to eight characters in length. Lowercase characters are treated as uppercase characters. Do not use group names beginning with DFH, because these characters are reserved for use by CICS.

INSERVICE
This attribute is obsolete, but is supported to provide compatibility with earlier releases of CICS. For more information, see Obsolete attributes.
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. Start of changeWhen a transaction is attached on an MRO link, CICS uses a TIOA that is long enough to contain the initial input message. End of change 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. (For further information on the effects of the MAXIMUM option, see the CICS Intercommunication Guide.)

SNA allows some resources (for example, switched lines) to be defined in the network as limited resources. At bind time, VTAM 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 more information on limited resources, see the CICS Intercommunication Guide.

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 VTAM LOGMODE entry defined to VTAM. It must not be the reserved name SNASVCMG. If you omit the modename it defaults to blanks. See the CICS Intercommunication Guide for more information about VTAM 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 VTAM 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 the CICS Customization Guide.

Start of changeThe NEPCLASS attribute is ignored for SNASVCMGR sessions.End of change

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
This attribute is obsolete, but is supported to provide compatibility with earlier releases of CICS. For more information, see Obsolete attributes.
OPERPRIORITY
This attribute is obsolete, but is supported to provide compatibility with earlier releases of CICS. For more information, see Obsolete attributes.
OPERRSL
This attribute is obsolete, but is supported to provide compatibility with earlier releases of CICS. For more information, see Obsolete attributes.
OPERSECURITY
This attribute is obsolete, but is supported to provide compatibility with earlier releases of CICS. For more information, see Obsolete attributes.
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 VTAM 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
  • VTAM LU6.1 receive sessions normally receive before sending, but may send before receiving when there is a shortage of suitable send 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 session in the partner. However, there is an upper limit of 100 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.

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

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 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 (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 VTAM 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 VTAM 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. For more information, see Obsolete attributes.
RECOVOPTION({SYSDEFAULT|CLEARCONV| RELEASESESS|UNCONDREL|NONE})
This option applies to the recovery of sessions in a CICS region running with VTAM persistent sessions, or with XRF.

VTAM 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 VTAM UNBIND, the UNBIND is followed by a VTAM SIMLOGON.
CLEARCONV
VTAM 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
VTAM 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
VTAM 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
VTAM 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 the above applies, 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 VTAM application program.
SENDCOUNT(number)
For MRO, and VTAM 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
  • VTAM 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 VTAM 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 VTAM 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 $ @ # . / - _ % & ¢ ? ! : | " = ¬ , ; < >
For information about entering mixed case information, see Entering mixed case attributes.

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 $ @ # . / - _ % & ¢ ? ! : | " = ¬ , ; < >
For information about entering mixed case information, see Entering mixed case attributes.
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. For more information, see Obsolete attributes.
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 TCT user area is initialized to zeros when the session is installed.

The TCT user area may be located above or below the 16Mb line in virtual storage. Where it is located depends on the value of the TCTUALOC operand of the DFHSIT macro. You should ensure that this is specified correctly to allow successful operation of any programs that are not capable of handling 31-bit addressing.

USERID(userid)
specifies a user identifier used for sign-on (SEC=YES or MIGRATE) 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 you enter are converted to uppercase.