SET VTAM

Modify the z/OS® Communications Server connection for CICS®. VTAM® is a previous name for the z/OS Communications Server.

SET VTAM

Read syntax diagramSkip visual syntax diagramSET VTAMOPENSTATUS(cvda)CLOSEDFORCECLOSEIMMCLOSEOPENPSDINTERVAL(data-value)PSDINTHRS(data-value)PSDINTMINS(data-value)PSDINTSECS(data-value)DEREGISTERED

Conditions: INVREQ, IOERR, NOTAUTH

For more information about the use of CVDAs, see CICS-value data areas (CVDAs).

Description

Use the SET VTAM command to complete the following tasks:
  • Establish or stop the CICS connection to the Communications Server.
  • Modify the persistent session delay interval value that CICS passes to the Communications Server.
  • Deregister CICS from membership of a Communications Server generic resource.

Options

DEREGISTERED
Specifies that CICS is to be removed from the Communications Server generic resource of which it is currently a member. If you deregister a region from membership of a generic resource, you must end any affinities that it owns; see the PERFORM ENDAFFINITY command.

Generic resources are described in Workload balancing in a sysplex.

OPENSTATUS(cvda)
Specifies whether or not CICS is to have a connection to the Communications Server (that is, whether the Communications Server ACB is to be open or closed) and, if CICS must close the ACB to comply, how the shutdown will be performed. CVDA values are as follows:
CLOSED
The connection is to be closed. If it is currently open, CICS is to quiesce all Communications Server activity and then close the Communications Server ACB. Tasks using Communications Server SNA LUs or sessions are allowed to complete before closure, but new tasks requiring the Communications Server are not begun.
FORCECLOSE
The connection is to be closed. If currently open, CICS is to close the Communications Server ACB immediately. Both Communications Server sessions and tasks using the Communications Server end abnormally as a result.
IMMCLOSE
The connection is to be closed. If currently open, CICS is to end abnormally any tasks using the Communications Server immediately, perform an orderly shutdown of all its Communications Server sessions, and then close the Communications Server ACB.
OPEN
A connection is to be open. If the Communications Server ACB is closed, CICS is to open it.

If CICS is using the Communications Server multinode persistent sessions, and the Communications Server has been restarted after an abend, opening the Communications Server ACB causes CICS to restore the persistent sessions that the Communications Server has retained. However, CICS does not restore APPC synclevel 2 sessions, which are unbound.

PSDINTERVAL(data-value)
Specifies the persistent session delay interval value, which states if, and for how long, the Communications Server is to hold sessions in a recovery-pending state if a failure occurs. The range for the value is 0 – 23:59:59. The value of PSDINTERVAL is not recorded in the global catalog.

If zero is set, sessions are not retained and are stopped at the time of the failure, so persistent sessions support is not exploited.

  • If you specify SNPS (the default) or MNPS for the PSTYPE system initialization parameter for the CICS region, set a nonzero value for the persistent session delay interval, so that sessions are retained.
  • If you specify NOPS (no persistent sessions support) for the PSTYPE system initialization parameter, a zero value is required for the persistent session delay interval.

When you specify a persistent session delay interval, CICS sets the PSDINT system initialization parameter. CICS passes this value to the Communications Server whenever it opens the ACB. The value is passed immediately if you specify an OPENSTATUS value of OPEN in the same SET SYSTEM command, or if the Communications Server ACB is already open and you do not close it. If the ACB is closed or being closed, or if the open attempt fails, the new value is established on the next successful open.

If the Communications Server is below the level that supports persistent sessions, the Communications Server rejects the request. CICS then sets the PSDINT system option value to zero and returns an INVREQ condition, but goes on to continue any other processing that you requested. The INVREQ occurs when the value is passed to the Communications Server, which might be later than the command that set it, as explained above. Consequently, you can see this condition on a command that does not specify a persistent session delay interval.

The persistent session delay interval can be expressed in several ways:
  • A 4-byte packed decimal composite, in the format 0hhmmss+, using the PSDINTERVAL option.
  • With separate hours, minutes, and seconds, using the PSDINTHRS, PSDINTMINS, and PSDINTSECS options. You can use these options singly or in any combination.
When you use PSDINTERVAL or more than one of the separate options, the minutes and seconds portions of the value must not be greater than 59. PSDINTMINS or PSDINTSECS used alone can exceed 59. For example, you can express an interval of 1 hour and 30 minutes in any of the following ways:
  • PSDINTERVAL(13000)
  • PSDINTHRS(1), PSDINTMINS(30)
  • PSDINTMINS(90)
  • PSDINTSECS(5400)
PSDINTHRS(data-value)
Specifies the hours component of the persistent session delay interval, in fullword binary form. See the PSDINTERVAL option.
PSDINTMINS(data-value)
Specifies the minutes component of the persistent session delay interval, in fullword binary form. See the PSDINTERVAL option.
PSDINTSECS(data-value)
Specifies the seconds component of the persistent session delay interval, in fullword binary form. See the PSDINTERVAL option.

Conditions

INVREQ
RESP2 values:
1
The Communications Server is not present in the system.
2
OPENSTATUS has an invalid CVDA value.
4
The PSDINTERVAL value is out of range.
5
The PSDINTHRS value is out of range.
6
The PSDINTMINS value is out of range.
7
The PSDINTSECS value is out of range.
8
A PSDINTERVAL value > 0 was specified in an XRF-eligible system.
9
The Communications Server reported an error while an attempt was being made to set the persistent session delay interval.
10
A persistent session delay interval has been specified but either the Communications Server currently in use (or the Communications Server library used when the terminal control table was assembled) does not support persistent sessions. The interval might have been specified earlier than this command; see the PSDINTERVAL description. If OPEN was also requested, CICS has opened the Communications Server ACB.
11
The ACB has opened successfully, but an error occurred in at least one of the sessions that persisted from the previous failure.
12
Your OPEN request did not complete because another task subsequently requested a close of the Communications Server connection.
13
An error occurred during recovery of sessions, and the Communications Server ACB is closed as a result.
14
CICS is performing cleanup processing following a predatory XRF takeover. CICS rejects OPEN requests with this error, without invoking the Communications Server, during this activity. OPEN requests are processed as usual as soon as cleanup is complete.
16
Your attempt to deregister CICS from a Communications Server generic resource failed because CICS is not registered as a member of a generic resource group.
22
An attempt was made to change PSDINTERVAL, PSDINTHRS, PSDINTMINS, or PSDINTSECS to a nonzero value with the system initialization parameter PSTYPE=NOPS in effect. The request was rejected.
IOERR
RESP2 values:
n
An error occurred during the opening of the ACB. If CICS was unable to process the request, the RESP2 value is 3. If the Communications Server detected the failure, CICS returns the FDBK2 code in RESP2: you can look up these errors in z/OS Communications Server SNA Programming, under ACB OPEN and CLOSE return codes.
NOTAUTH
RESP2 values:
100
The user associated with the issuing task is not authorized to use this command.