Vary VTS (VV)

Command title

Vary VTS

Description

The VV command varies the access mode of a read-only VTS to read-write and back to read-only.

COBOL syntax

MOVE 'VV'                   TO xxxx-COMMAND.
CALL 'TBLBASE' USING        TB-PARM
                            xxxx-COMMAND-AREA.

C syntax

memcpy( tbCommArea.tbCommand, "VV", 2 );
TBLBASE( &tbParm, &tbCommArea );

Parameters

None

Explanation

This command is intended for varying the access mode of a VTS that has been initialized in read-only mode, i.e. the TSRACCESS option for the VTS is RO. The VTS name must be in the TB-SUBSYSTEM field of the TB-PARM. A request id in the FUNCTION-ID field of the COMMAND-AREA determines what the operation should be.

When a VTS is switched to read-write mode, the job that performs the switch holds a read-write lock on the VTS and no other job or region can access the VTS until it is switched back to read-only mode.

A VTS can only be switched back to read-only by the same job step that holds the read-write lock. If a VTS is locked in read-write mode after the job that holds the lock terminates abnormally, it can be forced back to read-only mode using a special request id.

Each time the access mode of a VTS is successfully varied, the generation number of the VTS is increased by 1. To continue to access a VTS that has its generation number changed, the START-TBUOW field in the COMMAND-AREA must contain an S. More details can be found under 16. START-TBUOW (1 byte).

This command can only be issued by batch programs linked with the linkage editor input, SETCODE AC(1) and run from an authorized library. If the VTS is SAF protected, the userid executing the command must have a minimum of CONTROL access to the VTS.

Return value

FOUND is set to Y if the command is successful.

Error 1072 and its sub-code indicates why the VTS is unavailable. 1072-18 indicates that the VTS is locked in read-write mode. 1072-15 indicates that the VTS generation number has changed.

Error 79 and its sub-code indicates the reason for the error encountered when processing the command.

When executed from a non-authorized library, the program will abend S047.

Notes

It is good practice to switch the VTS back to read-only mode after it has been switched to read-write mode for updating. If this is not done, tableBASE will automatically switch the VTS back to read-only mode upon normal completion of the job step.

Exceptions

Switching a VTS that is already in read-only mode to read-only has no effect even though a FOUND of N is returned. This is true for switching a VTS that is already in read-write mode to read-write. The generation number is not incremented in either case.

See also

7. TB-SUBSYSTEM (8 bytes)

13. FUNCTION-ID (halfword binary)

16. START-TBUOW (1 byte)

10. VTS-GENERATION (2 bytes)