SET VTAM

Modify the CICS VTAM connection.

Read syntax diagramSkip visual syntax diagramSET VTAM
 
>>-SET VTAM--+------------------+------------------------------->
             +-OPENSTATUS(cvda)-+
             +-CLOSED-----------+
             +-FORCECLOSE-------+
             +-IMMCLOSE---------+
             '-OPEN-------------'
 
>--+--------------------------------+--+--------------+--------><
   +-PSDINTERVAL(data-value)--------+  '-DEREGISTERED-'
   | .----------------------------. |
   | V                            | |
   '---+------------------------+-+-'
       +-PSDINTHRS(data-value)--+
       +-PSDINTMINS(data-value)-+
       '-PSDINTSECS(data-value)-'
 

Conditions: INVREQ, IOERR, NOTAUTH

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

Description

The SET VTAM command allows you to:

Options

DEREGISTERED
specifies that CICS is to be removed from the VTAM generic resource that it is currently a member of. If you deregister a region from membership of a generic resource, you should end any affinities that it owns--see the PERFORM ENDAFFINITY command.

Generic resources are described in the CICS® Intercommunication Guide.

OPENSTATUS(cvda)
specifies whether or not CICS is to have a connection to VTAM (that is, whether the VTAM ACB is to be open or closed) and, if CICS must close the ACB to comply, how the shutdown should be done. CVDA values are:
CLOSED
The connection is to be closed. If it is currently open, CICS is to quiesce all VTAM activity and then close the VTAM ACB. Tasks using VTAM terminals or sessions are allowed to complete before closure, but new tasks requiring VTAM are not begun.
FORCECLOSE
The connection is to be closed. If currently open, CICS is to close the VTAM ACB immediately. Both VTAM sessions and tasks using VTAM terminate abnormally as a result.
IMMCLOSE
The connection is to be closed. If currently open, CICS is to terminate abnormally any tasks using VTAM immediately, do an orderly shutdown of all its VTAM sessions, and then close the VTAM ACB.
OPEN
A connection is to be open. If the VTAM ACB is closed, CICS is to open it.

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

PSDINTERVAL(data-value)
specifies the persistent session delay (PSD) interval value, which determines whether and for how long VTAM is to hold sessions in recovery-pending state after a CICS failure. The range for the value is 0-23:59:59. Zero causes the persistent session feature not to be used; sessions are terminated at the time of the failure.
Note:
Zero is the only value allowed in a system which is eligible for the extended recovery facility; see the XRFSTATUS option in the INQUIRE SYSTEM command.

When you specify a PSD interval, CICS sets the system initialization option PSDINT (see the CICS System Definition Guide for more about this option). CICS passes this value to VTAM whenever it opens the ACB. This occurs immediately if you specify an OPENSTATUS value of OPEN in the same SET SYSTEM command, or if the VTAM 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 VTAM is below the level that supports persistent sessions (Version 3.4.1), VTAM rejects the PSD request. CICS then sets the PSDINT system option value to zero and returns an INVREQ condition, but goes on to continue any other processing you requested. The INVREQ occurs when the value is passed to VTAM, which may be later than the command that set it, as explained above. Consequently, you can get this condition on a command that does not specify a PSD interval.

The PSD 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 could 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 PSD interval, in fullword binary form (see the PSDINTERVAL option).
PSDINTMINS(data-value)
specifies the minutes component of the PSD interval, in fullword binary form (see the PSDINTERVAL option).
PSDINTSECS(data-value)
specifies the seconds component of the PSD interval, in fullword binary form (see the PSDINTERVAL option).

Conditions

INVREQ
RESP2 values:
1
VTAM 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
VTAM reported an error while an attempt was being made to set the PSD interval.
10
A PSD interval has been specified but either the VTAM currently in use (or the VTAM library used when the terminal control table was assembled) does not support persistent sessions. The interval may have been specified earlier than this command; see the PSDINTERVAL description. If OPEN was also requested, CICS has opened the VTAM 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 VTAM connection.
13
An error occurred during recovery of sessions, and the VTAM 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 VTAM, during this activity. OPEN requests are processed as usual as soon as cleanup is complete.
16
Your attempt to deregister CICS from a VTAM generic resource failed because CICS is not registered as a member of a generic resource group.
IOERR
RESP2 values:
n
An error occurred during the opening of the ACB. If CICS could not process the request, the RESP2 value is 3. If VTAM detected the failure, CICS returns the VTAM FDBK2 code in RESP2: you can look up these errors in the VTAM Programming manual, 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.
[[ Contents Previous Page | Next Page Index ]]