Request resources
Component: | BS2000 |
Functional area: | Job processing |
Domain: | JOB |
Privileges: | STD-PROCESSING |
Function
The SECURE-RESOURCE-ALLOCATION command reserves resources required by the job for execution. This reservation guarantees that subsequent accesses to resources will not be rejected by the system.
Within an interactive or batch job the following resources can be reserved by means of the SECURE-RESOURCE-ALLOCATION command:
private volumes (disks, tapes)
devices for private volumes (disk devices, tape devices)
files, file generations and file generation groups on private and public volumes.
Reservation of a file also results in the reservation of the disk or tape containing it and, in turn, the reservation of the respective device.
Explicit reservations can be made for
devices, by means of the DEVICE or UNIT operand
volumes, by means of the DISK or TAPE operand
files, by means of the FILE operand.
Implicitly reserved are devices or volumes which are required for an explicitly reserved file or volume.
If a device type is both implicitly and explicitly reserved in a command at the same time, the system will attempt to provide the sum of the implicitly and explicitly reserved devices.
A resource is exclusively reserved if no other job can use it while it is reserved. It is termed shareable if the system ensures free access during the reservation period, although other jobs can use the resource as well.
An existing reservation is canceled:
with every SECURE-RESOURCE-ALLOCATION command (even without operands). All previously reserved private resources are released (even those reserved only implicitly)
with the REMOVE-FILE-LINK command.
REMOVE-FILE-LINK cancels the reservation of a file and of the associated disk/tape as required. The reservation of devices is retained if this is requested in the REMOVE-FILE-LINK command with RELEASE-DEVICE=*NO.
If disks/tapes or devices assigned to the file are also implicitly reserved by other files or disks/tapes, these disks/tapes and devices are not released until all system references have been cleared.with the WAIT-EVENT command (UNTIL=*USER-SWITCHES(...) operand).
at job end (EXIT-JOB, LOGOFF, CANCEL-JOB).
The SECURE-RESOURCE-ALLOCATION command is rejected if:
a program is loaded and assignments with USE=SPECIAL exist.
a tape file to be reserved is open.
the TFT entry of a tape file to be reserved is locked with /LOCK-FILE-LINK.
a public volume is supposed to be reserved explicitly.
one of the requested resources cannot be made available (see WAIT operand).
implicitly requested devices do not exist or not in adequate numbers
a nonprivileged user tries to reserve a file under the TSOS user ID or the standard system user ID exclusively.
the job has opened files on volumes which were to be reserved exclusively This is possible if SECURE-RESOURCE-ALLOCATION is issued within a procedure file and the file was previously allocated to a private volume of a logical system file (e.g. ASSIGN-SYSLST).
Each SECURE-RESOURCE-ALLOCATION command (even one without operands) first releases all private resources which were previously reserved (implicit RELEASE). TFT entries will not be deleted, and do not need to be recreated. However, the device reservations linked to the existing TFT entries are canceled.
If a volume which is not yet mounted is reserved, for tapes by default a PREMOUNT message (for tapes) is sent to the operator terminal (can be changed with MODIFY-MOUNT-PARAMETER). Private disk must be online or be made available during the execution of the command.
If any of the requested resources cannot be reserved, no reservation at all is made. Depending on the job type and what is specified for the WAIT operand, the system either issues a message or places the job in the Secure queue until all requested resources are available or until the specified wait time elapses. Note, however, that the system branches to the next SET-JOB-STEP, EXIT-JOB or LOGOFF command if implicitly requested devices or the necessary number of devices do not exist.
If the operator rejects a resource request (MOUNT message on the console), no reservation is made and the system branches, in batch mode, to the next SET-JOB-STEP, EXIT-JOB or LOGOFF command.
If the command is rejected (e.g. resources not available), all volumes previously made available to the job are released again.
Whether a private disk can be reserved depends on the setting of the parameters “USER-ALLOCATION”, “SYSTEM-ALLOCATION” and “OPERATOR-CONTROL”. The user can query these via the SHOW-DISK-STATUS command.
Notes on tape processing
For any tape volume reserved by /SECURE-RESOURCE-ALLOCATION VOLUME (explicit reservation) or by /SECURE-RESOURCE-ALLOCATION FILE (implicit reservation), the VOLUME-PHASE will be set to PREMOUNT (see the command SHOW-TAPE-STATUS, SHOW-RESOURCE-ALLOCATION). In other words, this tape is pre-reserved solely to prevent the use of the same volume by another job. However, no input/output operations have yet taken place on the volume. There is an implicit device reservation. Between the time of OPEN and CLOSE, the PHASE for the tape is IN-USE (i.e. the tape is being processed). Following the CLOSE, the PHASE is set back to PREMOUNT.
Remote file access (see also the “RFA” manual [31])
Files may also be reserved in a remote system via RFA. However, only files may be specified in this command and these must all belong to the same system.
The local TFT contains entries for all remote files which are being processed. Exclusively reserved remote files are not included; the same applies to remote files after input of the REMOVE-FILE-LINK command.
In order to avoid a deadlock situation, a SECURE-RESOURCE-ALLOCATION command without operands is sent to all RFA partner tasks during the disconnection phase at the start of command execution (unless the task is itself an RFA partner task).
Access to migrated files (for details see the “HSMS” manual [18])
Files migrated by means of HSMS to one of the hierarchical storage levels S1 or S2 can be implicitly recalled via /SECURE-RESOURCE-ALLOCATION, FILE=*PAR(filename) (implicit recall). HSMS outputs a summary report in this case.
Format
SECURE-RESOURCE-ALLOCATION | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Operands
DEVICE = *NO / list-poss(11): *PARAMETERS(...)
Specifies whether devices are to be reserved.
DEVICE = *NO
No devices will be reserved by their device type.
DEVICE = list-poss(11): *PARAMETERS(...)
Specifies the number and type of devices to be reserved. No more than eleven different types of devices may be reserved.
TYPE = <device> / <structured-name 1..8> / <alphanum-name 1..8>
Specifies which device type is to be reserved.
A disk device should not be reserved using the TYPE operand because the associated disk can be used by privileged applications (such as FDDRL or VOLIN) in usage mode SPECIAL only.
Tape and cartridge tape devices are reserved by specifying a valid volume type (see also section "Device types for DMS tape processing"). Volume types WORK and TAPE can be used only for applications for which WORK and TAPE respectively have also been specified as volume type (in the CREATE-FILE command, for example).
The available device types can be determined from the output from the SHOW-DEVICE-CONFIGURATION command with UNIT=*SELECT(CLASS=*DEVICE, ATTRIBUTE=*ATTACHED) (see also the device table in section "Device type table" (device type column)).
See also the TYPE operand for reserving disks (DISK) and tapes (TAPE).
NUMBER = 1 / <integer 0..255>
Number of devices of the specified type that are to be reserved.
LOCATION = *USER-DEFAULT / *NONE / <alphanum-name 1..8> / *BY-FILENAME(...)
Only for reservation of tape devices
Either describes the way in which the location is determined or designates the location itself.
LOCATION = *USER-DEFAULT
The device administration should select suitable device groups. If the chargeable MAREN subsystem is loaded, the device administration should use MAREN (MAREN Exit) to obtain the appropriate device depot information.
LOCATION = *NONE
The devices to be reserved should be taken from the device group which is not assigned to a device depot (the RESTPOOL; see ADD-DEVICE-DEPOT command).
LOCATION = <alphanum-name 1..8>
Designates the storage location (device depot) from whose assigned device group the tape devices to be reserved are to be selected. Assignments of tape devices to device depots are defined by system support staff using the ADD-DEVICE-DEPOT command. These assignments can be listed with the SHOW-DEVICE-DEPOT command.
LOCATION = *BY-FILENAME(...)
The device administration must use the chargeable MAREN subsystem to find out where the tape is located. The specified file name is passed to MAREN. In conjunction with MAREN Exit, MAREN uses this name to find out where the relevant tape is stored. The procedure for obtaining depot information on MARENLM or MAREN-Exits is described in the “MAREN” manual [23].
If the location returned by MAREN is not one of the depots declared with ADD-DEVICE-DEPOT, processing continues without a depot specification. In this respect note the following:
If all tape devices are assigned to depots, the command is rejected with a return code of NKS0015, and any other device reservation (e.g. using a FILE or OPEN macro) is rejected with an appropriate return code.
If suitable devices with no depot assignment are available (from the RESTPOOL), the device request is implemented from this pool.
NAME = <filename 1..54>
If the “devices” in this pool are ones which have simply been generated to allow for future additions but are not physically present, tasks may end up waiting permanently on the device queue. Any such tasks can be listed with the SHOW-RESOURCE-REQUESTS command (the RESOURCES REQUESTED output contains a device type designation with no depot specification).
The location of the tape on which the specified file is archived is ascertained.
UNIT = *NO / list-poss(48): <alphanum-name 2..2> / <alphanum-name 4..4>
Mnemonic (two- or four-character) device name of the device to be reserved. The device is reserved exclusively for this job.
A disk device should not be reserved using the UNIT operand because the associated disk can be used by privileged applications (such as FDDRL or VOLIN) in usage mode SPECIAL only.
UNIT = *NO
No device is being reserved by specifying its UNIT.
UNIT = list-poss(48): <alphanum-name 2..2>
Mnemonic device name (2 characters) of the tape device which is to be reserved; the device will be exclusively reserved, and can also be used in non-DMS mode.
UNIT = list-poss(48): <alphanum-name 4..4>
Mnemonic device name (4 characters) of the tape device which is to be reserved; the device will be exclusively reserved, and can also be used in non-DMS mode.
DISK = *NO / list-poss(48): *PARAMETERS(...)
Specifies whether a private disk is to be reserved.
DISK = list-poss(48): *PARAMETERS(...)
For each private disk which is to be reserved, the volume serial number (VSN), the disk device type and the type of reservation must be specified. A maximum of 48 private disks can be reserved.
The “DMS” usage mode is implicitly defined for the volumes.
Whether a device can be reserved or not depends on the values of the “USER-ALLOCATION”, “SYSTEM-ALLOCATION” and “OPERATOR-CONTROL” settings defined by system support staff using the SET-DISK-DEFAULTS and SET-DISK-PARAMETER commands. Users can request information about these values using the SHOW-DISK-DEFAULTS and SHOW-DISK-STATUS commands.
VOLUME = <alphanum-name 1..6>
Specifies the volume serial number(s) of the disk(s) to be reserved.
TYPE = <device>
Specifies the type of device on which the disk is to be mounted.
Only device types known within the system are accepted. In interactive mode, the possible device types are displayed with DEVICE-TYPE=?.
The available device types are shown in the output of the SHOW-DEVICE-CONFIGURATION command with UNIT=*SELECT(CLASS=*DEVICE,ATTRIBUTE= *ATTACHED) (see also the device table in section "Device type table" (device type column)).
ALLOCATION = *SHARED / *EXCLUSIVE
Specifies the reservation mode for the disk to be reserved.
ALLOCATION = *SHARED
Disk access by other jobs is permitted.
ALLOCATION = *EXCLUSIVE
Exclusive reservation: this means that the resource may not be used by any other jobs.
TAPE = *NO / list-poss(48): *PARAMETERS(...)
Specifies whether a tape is to be reserved. This reservation is always exclusive.
TAPE = list-poss(48): *PARAMETERS(...)
Specifies the volume serial number, device type and desired type of access for each tape to be reserved. A maximum of 48 tapes may be reserved.
The *DMS* usage mode is implicitly defined for the volumes. Reservations for the “SPECIAL” or “WORK” usage modes are possible only in explicit device reservations.
Points to note when using storage locations (MAREN subsystem)
When reserving a volume and the implicit device reservation linked to it, the device administration uses the chargeable MAREN subsystem to determine the storage location of the volume.
If the volume identifier is entered in the MAREN catalog, the storage location indicated there is used for the device reservation. Otherwise, the default storage location supplied by MAREN or the storage location determined by using the MARENLM or MAREN-EXITS routine is used (see the “MAREN, Volume 1” manual [23]).
VOLUME = <alphanum-name 1..6>
Specifies the volume serial number of the volume to be reserved.
TYPE = *BY-VOLUME-CATALOG / <device>
Identifies the type of device on which the volume is to be mounted.
Only device types or volume types known within the system are accepted. In interactive mode, the possible device and volume types are displayed with DEVICE-TYPE=?. Volume types WORK and TAPE can be used only for applications for which WORK and TAPE respectively have also been specified as volume type (in the CREATE-FILE command, for example).
TYPE = *BY-VOLUME-CATALOG
The device type is determined via MAREN device substitution. If this function is not available, the command is rejected.
ACCESS = *READ / *WRITE
Specifies the type of accesses for which the tape must be mounted. The purpose of this operand is to inform the operator in the mount or premount request whether the tape should be mounted with the write protection lock activated or deactivated.
ACCESS = *READ
The tape is only to be read. The write protection lock must not be disabled.
Tapes are not write-protected by default. If a write access is attempted to a tape which was requested without a write-enable ring, the processing will merely be interrupted and the system will request the operator to remount the tape with the write protection lock disabled.
ACCESS = *WRITE
The tape is to be written. The operator will be asked in the mount request to disable the write protection lock.
MOUNT = *YES / *NO
Specifies whether the implicit device reservation is to be executed immediately when the SEC-RES command is executed.
MOUNT = *YES
The system reserves the volume and device and issues the premount message on the operator terminal.
MOUNT = *NO
The system will reserve the volume but not the required device; no premount message will be output. The device will be reserved offline; this reservation will not be output if the command SHOW-RESOURCE-ALLOCATION is issued.
FILE = *NO / list-poss(48): *PARAMETERS(...)
Specifies whether a file, file generation or file generation group is to be reserved. Access to the file must be permitted (see SHOW-FILE-ATTRIBUTES command).
FILE = *NO
No file/file generation is to be reserved.
FILE = list-poss(48): *PARAMETERS(...)
The name must be specified for each file which is to be reserved; for tape files, the reservation details must also be specified (ACCESS, MOUNT), and for disk files the type of reservation. A maximum of 48 files can be reserved.
For tape files, the reservation is always exclusive; for disk files, it depends on the ALLOCATION operand.
NAME = <filename 1..54>
Identifies a cataloged file, file generation or system file. If the file/FGG specified by NAME is not cataloged, the job will not be put into the SECURE queue. In interactive mode, an error message will be output, in batch mode spin-off will be initiated.
If the file specified by NAME is cataloged under another user’s ID, the file/FGG must be shareable. All the disks belonging to it will be reserved as shareable and mounted.
For files on SPDs (shareable private disks), the reservation is noted in the F1 label on the disk. This reservation is also taken into account by accesses from other computers. In multiprocessor systems, any reservation for a file which is not on a locally available pubset will be rejected.
If no other details are specified by a file reservation, the following default values will apply:
Disk files: The associated disks will be mounted and treated as shareable. The file will be reserved as shareable, but can also be reserved exclusively (ALLOCATION). If the file is spread across several private disks, all the volumes concerned will be reserved.
Tape files: The associated tapes will always be reserved exclusively. This has the effect that all the files which are on these tapes are also exclusively reserved. The tape device will be implicitly reserved (see MOUNT operand).
The reserved tapes will be mounted with the write protection lock enabled (see ACCESS operand).
If the file is spread across several tapes, then a device will only be automatically reserved for the first volume (depending on the MOUNT operand).
ACCESS = *READ / *WRITE
This operand is only evaluated for tape files:
Specifies whether the associated tapes are to be mounted for reading only, or for writing as well. The purpose of this operand is to inform the operator in the mount request whether the tape should be mounted with the write protection lock enabled or disabled.
ACCESS = *READ
The tape is only to be read. The write protection lock must not be disabled. Tapes are not write-protected by default.
ACCESS = *WRITE
The tape is to be written. The operator will be asked in the mount request to disable the write protection lock.
MOUNT = 1 / <integer 0..255>
This operand is only evaluated for tape files:
Specifies how many tape devices are to be implicitly reserved. The tapes will be selected in the sequence in which they are recorded in the catalog. For these tapes, MOUNT messages will be output on the operator’s terminal for the devices which are implicitly reserved.
When using storage locations, the device administration determines the storage location as when reserving via the TAPE operand.
MOUNT = 1
Only one device will be implicitly reserved.
MOUNT = <integer 0..255>
The specified number of devices will be implicitly reserved.
If the number of devices implicitly reserved is less than there are tapes recorded in the catalog, then the remaining tapes will be reserved without a corresponding device reservation (offline).
If the number of devices specified is more than there are tapes recorded in the catalog, then only as many implicit device reservations will be executed as there are tapes in the catalog.
ALLOCATION = *SHARED / *EXCLUSIVE
This operand is only evaluated for disk files: Specifies whether the file/file generation specified by the NAME operand is to be reserved as shareable or exclusive, i.e. whether other jobs may access the reserved disk file or not.
ALLOCATION = *SHARED
A check will be made to see whether the file exists. It is still accessible for other jobs (both read and write access). The required disks and devices will be implicitly reserved and remain shareable (USE=DMS). No check will be made to see whether the file is already exclusively reserved. The file can still be exclusively reserved by another task.
ALLOCATION = *EXCLUSIVE
The file will be reserved exclusively for the calling job, and is therefore not accessible for other jobs; disks and devices are reserved as shareable. A file can only be reserved exclusively if it is not open or not already exclusively reserved by another job.
Files belonging to the user ID TSOS or the system default ID cannot be exclusively reserved by other users.
If a file generation group is specified, all the file generations which comprise it will be locked against access from outside.
WAIT = *PARAMETERS(...)
Determines the maximum time that the job should wait for the fulfillment of its reservation request. When this waiting time has expired, the request will be rejected.
The waiting time includes also the time required to fetch back any files which have been migrated (by HSMS).
TIME = *TASK-STD / <integer 1..2097152 seconds>
Specifies the maximum waiting time in seconds. The accuracy is in the order of minutes. If the command requires volumes to be mounted, any reservation which specifies a waiting time of less than 180 seconds will be rejected.
TIME = *TASK-STD
TASK-STD is the default setting:
The system makes a distinction between interactive and batch modes.
Interactive mode:
The command will be rejected if the requested resources are reserved and it will be necessary to wait for their release.
Batch mode:
There is no limit on the waiting period. As a rule, the job will wait for the defined period for the resources to be mounted and become available. If the requests have not been fulfilled by the end of this period, spin-off will be initiated (branch to /SET-JOB-STEP).
TIME = <integer 1..2097152 seconds>
Waiting time in seconds: 0 <= integer <= 2097152 (approx. 582 hours or 24 days); the accuracy is of the order of minutes.
If a number < 180 is specified for the TIME operand, then the command will be rejected if a volume needs to be mounted or confirmation from the operator is required for a disk request.
EVENT = *ALL-MOUNT / *DISK-MOUNT
Specifies whether the mounting of tapes is to be synchronous or not with the reservation within the specified waiting time, i.e. whether to wait for a response to the mount or premount messages.
Mount requests for disks must always be satisfied within the waiting time.
EVENT = *ALL-MOUNT
Within the specified waiting period, the job will wait until all the requested volumes have been mounted, i.e. until the operator has responded to all the MOUNT messages. In this case, the mount requests will be synchronous.
EVENT = *DISK-MOUNT
The job will not wait if tapes have been requested; it will only wait for the mounting of private disks. This means that mount request and reservation are asynchronous for tapes, but on the other hand, for disks they are synchronous.
Even if a reservation is satisfied, a subsequent mount request may still be rejected, and hence cause an error (spin-off).
Return codes
(SC2) | SC1 | Maincode | Meaning |
|---|---|---|---|
0 | CMD0001 | Command executed | |
32 | NKS0036 | Internal error | |
64 | NKS0001 | Tape file open or in HOLD state | |
64 | NKS0003 | Request local and remote files | |
64 | NKS0004 | Request for a public disk | |
64 | NKS0005 | Incompatible reservation modes | |
64 | NKS0006 | Task deadlock | |
64 | NKS0007 | Request for an invalid device type | |
64 | NKS0009 | Wait time too short for operator contact | |
64 | NKS0013 | Program loaded and USE=SPECIAL considerations | |
64 | NKS0035 | Resources not available at present | |
64 | NKS0037 | Termination due to CANCEL-JOB or shutdown | |
64 | NKS0044 | Syntax error in command | |
64 | NKS0045 | Request for resources from multiple systems | |
64 | NKS0048 | Operator was unable to mount volume | |
64 | NKS0049 | Requested resources not available on the system | |
64 | NKS0050 | Command aborted after wait time elapsed | |
64 | NKS0051 | No exclusive reservation of files under the standard system user ID | |
64 | NKS0052 | Tape not online (wait time too short) | |
64 | NKS0064 | Reservation via device type not permitted | |
64 | NKS0065 | File migrated and HSMS not loaded | |
64 | NKS0066 | File migrated and internal HSMS error | |
64 | NKS0067 | File migrated; recall not possible without delay | |
64 | NKS0080 | Error on processing a list object | |
64 | NKS0098 | Error in RFA call |
Examples
Example 1: Reserving a file
The interactive job DIALOG1 reserves the file X.BEFORE for its use with the command:
/sec-res file=par(name=x.before,alloc=*excl).
Thereafter, if the interactive job DIALOG2 wants to read this file with the command SHOW-FILE, it receives the error message DMS0D99:
/show-user-sta inf=*prog
%NAME TSN TYPE SIZE CURR-CMD %DIALOG1 1CZI 3 DIALOG SECURE-RESOURCE-ALLOCATION %DIALOG2 1E1C 3 DIALOG SHOW-USER-STATUS
/show-file x.vorher
% SHO0003 'DMS' REPORTED ERROR '0D99'. COMMAND NOT PROCESSED
/help-msg dms0d99,lang=E
% DMS0D99 FILEWRITE PROTECTED OR ALREADY IN USE % ? Possible errors: % 1) Attempt to open a locked file.; % 2) Attempt to open a read-only file in a mode other than INPUT % or REVERSE.; % 3) Attempt to open an ISAM or PAM file in SHARED UPDATE mode when % it has already been opened as nonshareable by another user. % 4) Attempt to open an ISAM or PAM file in an OPEN mode intended to % prohibit opening of the file when one or more users have already % opened it. % 5) Attempt to open an ISAM file with LOCKENV=XCS. % 6) File is currently being processed by a C-COPY command. % ! Correct and try again later.
Example 2: Reserving two or more magnetic tape cartridge units
/sec-res dev=((type=tape-c4,num=1,location=d023ze02), (type=tape-u4,num=1,location=d023ze02))—————————————————— (1)
/sec-res dev=((type=tape-c4,num=1,location=roboter1), (type=tape-u4,num=1,location=roboter2))—————————————————— (2)
(1) | The SECURE-RESOURCE-ALLOCATION command reserves a magnetic tape cartridge device of type TAPE-C4 and one of type TAPE-U4. Both devices should be fetched from the storage location D023ZE02. |
(2) | The SECURE-RESOURCE-ALLOCATION command reserves a magnetic tape cartridge device of type TAPE-C4 and one of type TAPE-U4. The devices should be fetched from the storage locations ROBOTER1 and ROBOTER2. |
Example 3: Reserving a tape
/set-logon-parameters ...
. . .
/sec-res tape=par(vol=b0000a,type=tape) ——————————————————————————————— (1)
/start-prog from-f=prog.test
/sec-res ———————————————————————————————————————————————————————— (2)
(1) | The SECURE-RES command reserves a tape with the volume serial number B0000A exclusively for this interactive process. To permit its use, a 9-track tape device is assigned to the job. |
(2) | All the resources reserved for this job are now released. |
See also the example for the SHOW-RESOURCE-ALLOCATION command.