HP OpenVMS DCL Dictionary
HP OpenVMS DCL Dictionary
SET RESTART_VALUE
Assigns a value to the global symbol BATCH$RESTART. This global symbol
defines the location at which a batch job is restarted after its
execution has been interrupted. The SET RESTART_VALUE command is
meaningful only in command procedures.
Format
SET RESTART_VALUE =string
Parameter
string
Specifies a string of up to 255 characters, which specifies the label
at which the batch job should begin executing when it is restarted.
Description
Use the SET RESTART_VALUE command in restartable command procedures. (A
restartable command procedure is a command procedure that is submitted
to run in batch mode with the SUBMIT/RESTART command.) SET
RESTART_VALUE assigns a value to the global symbol BATCH$RESTART, the
location at which the batch job should be restarted after its execution
has been interrupted.
When writing a restartable command procedure, begin each possible
starting point in the command procedure with a label. After the label,
use the SET RESTART_VALUE command to assign the symbol BATCH$RESTART to
equal the label. If the batch job is interrupted by a system crash and
is then restarted, the command procedure can resume execution at the
label pointed to by BATCH$RESTART.
The SET RESTART_VALUE command is used in conjunction with the reserved
global symbol $RESTART. $RESTART is a special symbol that is maintained
by the system and cannot be deleted. $RESTART has the value TRUE if the
batch job has been restarted; otherwise, $RESTART has the value FALSE.
At the beginning of a restartable command procedure, test the value of
the reserved global symbol $RESTART. If $RESTART is true, execute a
GOTO statement using the symbol BATCH$RESTART as the transfer label. If
a SET RESTART_VALUE command was not executed before the batch job was
interrupted, the symbol BATCH$RESTART has no definition and the batch
job should restart from the beginning.
Most of your process environment is not maintained when the system
fails. The only symbols maintained across a system failure are $RESTART
and BATCH$RESTART; therefore, you should redefine any symbols or
process logical names used in your command procedure after each SET
RESTART_VALUE command.
If a command procedure has SET RESTART_VALUE commands in it, but you
want the job to restart at the beginning, enter the SET
ENTRY/NOCHECKPOINT command to delete the global symbol BATCH$RESTART.
Example
|
$ IF $RESTART THEN GOTO 'BATCH$RESTART'
.
.
.
$ FIRSTPART:
$ SET RESTART_VALUE = FIRSTPART
$ RUN PART1
.
.
.
$ SECONDPART:
$ SET RESTART_VALUE = SECONDPART
$ RUN PART2
.
.
.
|
In this example, the first command states that, if $RESTART is true,
the procedure is to jump to the value contained in BATCH$RESTART.
($RESTART is true only if the job has been executed before, that is,
the job is being rerun after a crash or after having been requeued.)
The first SET RESTART_VALUE command assigns the label FIRSTPART to be
equal to the symbol BATCH$RESTART. The next line contains the command
to run PART1.EXE.
The second SET RESTART_VALUE command assigns the label SECONDPART to be
equal to the symbol BATCH$RESTART. The last line shown contains the
command to run PART2.EXE.
When the job is first submitted using the SUBMIT/RESTART command, the
value of $RESTART is FALSE, so the IF expression is ignored. If the job
is stopped during the run of PART1.EXE, the value of BATCH$RESTART is
FIRSTPART. When the job is restarted, the value of $RESTART is TRUE;
therefore, the IF expression is processed and transfers control to the
FIRSTPART label in the procedure. PART1.EXE is rerun.
If the job is stopped during the run of PART2.EXE, the value of
BATCH$RESTART is SECONDPART. When the job is restarted, the value of
$RESTART is TRUE. In this instance, the IF--GOTO command transfers
control to the SECONDPART label in the procedure so that PART2.EXE can
be run. PART1.EXE is not rerun.
SET RIGHTS_LIST
Allows users to modify the process or system rights list. You must
specify either the /DISABLE or the /ENABLE qualifier with the SET
RIGHTS_LIST command.
Format
SET RIGHTS_LIST id-name[,...]
Parameter
id-name[,...]
Specifies identifiers to be added to or removed from the process or
system rights list. The id-name parameter is a string of 1 to
31 alphanumeric characters, underscores (_), and dollar signs ($); each
name must contain at least one nonnumeric character.
Description
The SET RIGHTS_LIST command modifies identifiers in your current
process rights list, the rights list of another process on the system,
or the system rights list. Use the following guidelines to determine
which privileges are required for each case:
- Adding new identifiers or modifying existing identifiers in your
process rights list that do not have the Dynamic attribute requires
CMKRNL (change mode to kernel) privilege.
- Modifying the rights list of other processes on the system requires
CMKRNL privilege and either GROUP or WORLD privilege.
- Modifying the system rights list requires both CMKRNL and SYSNAM
(system logical name) privileges.
- Adding or removing more than ten identifiers using the /ENABLE
qualifier or the /DISABLE qualifier in a single command invocation
requires CMKRNL privilege. You must specify either the /DISABLE or the
/ENABLE qualifier with the SET RIGHTS_LIST command.
This command can also be used to add attributes to existing identifiers.
Qualifiers
/ATTRIBUTES=(keyword[,...])
Specifies attributes to be associated with the identifiers. Attributes
may be added to new or existing identifiers. The following are valid
keywords:
|
DYNAMIC
|
Allows unprivileged holders of the identifier to remove and to restore
the identifier from the process rights list by using the DCL command
SET RIGHTS_LIST.
|
|
NOACCESS
|
Makes any access rights of the identifier null and void. If a user is
granted an identifier with the No Access attribute, that identifier has
no effect on the user's access rights to objects. This attribute is a
modifier for an identifier with the Resource or Subsystem attribute.
|
|
RESOURCE
|
Allows holders of an identifier to charge disk space to the identifier.
Used only for file objects.
|
|
SUBSYSTEM
|
Allows holders of the identifier to create and maintain protected
subsystems by assigning the Subsystem ACE to the application images in
the subsystem. Used only for file objects.
|
To remove an attribute from the identifier, add a NO prefix to the
attribute keyword. For example, to remove the Resource attribute,
specifiy /ATTRIBUTE=NORESOURCE.
The default uses the current processes in the rights database. Use the
command SHOW PROCESS/RIGHTS to see the attributes of the current
process.
/DISABLE
Removes the identifiers from the process or system rights list. You
cannot use the /DISABLE qualifier with the /ENABLE qualifier. Note that
removing more than ten identifiers in a single command invocation
requires CMKRNL privilege.
/ENABLE
Adds the identifiers to the process or system rights list. You cannot
use the /ENABLE qualifier with the /DISABLE qualifier. Note that adding
more than ten identifiers in a single command invocation requires
CMKRNL privilege.
/IDENTIFICATION=pid
Specifies the process identification (PID) value of the process whose
rights list is to be modified. The PID is assigned by the system when
the process is created. When you specify a PID, you can omit the
leading zeros.
If you specify the /IDENTIFICATION qualifier, you cannot use the
/PROCESS qualifier. By default, if neither the /IDENTIFICATION nor the
/PROCESS qualifier is specified, the current process is assumed. You
cannot use the /IDENTIFICATION qualifier with the /SYSTEM qualifier.
/PROCESS[=process-name]
Specifies the name of the process whose rights list is to be modified.
The process name can contain from 1 to 15 alphanumeric characters.
If you specify the /PROCESS qualifier, you cannot use the
/IDENTIFICATION qualifier. By default, if neither the /PROCESS nor the
/IDENTIFICATION qualifier is specified, the current process is assumed.
You cannot use the /PROCESS qualifier with the /SYSTEM qualifier.
/SYSTEM
Specifies that the desired operation (addition or removal of an
identifier) be performed on the system rights list. You cannot use the
/SYSTEM qualifier with the /PROCESS or the /IDENTIFICATION qualifier.
Examples
| #1 |
$ SET RIGHTS_LIST/ENABLE/ATTRIBUTES=RESOURCE MARKETING
|
The SET RIGHTS_LIST command in this example adds the MARKETING
identifier to the process rights list of the current process.
Specifying the RESOURCE attribute allows holders of the MARKETING
identifier to charge resources to it.
| #2 |
$ SET RIGHTS_LIST/ENABLE/SYSTEM PHYSICS101
%SYSTEM-F-NOPRIV, insufficient privilege or object
protection violation
$ SET PROCESS/PRIVILEGES=(CMKRNL,SYSNAM)
$ SET RIGHTS_LIST/ENABLE/SYSTEM PHYSICS101
|
The SET RIGHTS_LIST command in this example adds the PHYSICS101
identifier to the system rights list. You must have both the CMKRNL
(change mode to kernel) and SYSNAM (system logical name) privileges to
modify the system rights list.
SET RMS_DEFAULT
Defines default values for multiblock and multibuffer counts, network
transfer sizes, prolog level, extend quantity, and the query lock
option used by OpenVMS Record Management Services (RMS) for file
operations.
If you set the default value for either the multiblock count or the
multibuffer count at 0, RMS tries to use the process default value or
the system default value, in that order. If these are set at 0, RMS
uses a default value of 1. Defaults are set for sequential, relative,
or indexed file organizations on a process-only basis, unless a
systemwide basis is requested.
Format
SET RMS_DEFAULT
Parameters
None.
Description
Multiblocking and multibuffering of file operations can enhance the
speed of I/O operations with RMS. The defaults set with the SET
RMS_DEFAULT command are applied for all file operations that do not
specify explicit multiblock or multibuffer counts.
For more information on multiblock and multibuffer operations, refer to
the HP OpenVMS System Services Reference Manual.
For indexed files, the SET RMS_DEFAULT command defines default prolog
level options.
For sequential files, the SET RMS_DEFAULT command defines default
extensions. If a default extension is not specified in your program,
the process or system default is used.
For network operations, the SET RMS_DEFAULT command defines network
buffer sizes for transfer.
Qualifiers
/BLOCK_COUNT=count
Specifies a default multiblock count (0 to 127) for record I/O
operations only, where count is the number of blocks
to be allocated for each I/O buffer.
For more information on multiblock count, refer to the description of
the RAB$B_MBC in the OpenVMS Record Management Services Reference Manual.
/BUFFER_COUNT=count
Specifies a default multibuffer count (0 to 255) for local file
operations, where count is the number of buffers to be
allocated. If you use the /SYSTEM qualifier to extend the default value
systemwide, the maximum default value is 127.
When you use the /BUFFER_COUNT qualifier, you can use the /DISK,
/INDEXED, /MAGTAPE, /RELATIVE, /SEQUENTIAL, and /UNIT_RECORD qualifiers
to specify the types of file for which the default is to be applied. If
the /BUFFER_COUNT qualifier is specified without any of these
qualifiers, the /SEQUENTIAL qualifier is assumed. If file type is not
specified, the default is applied to sequential files.
For more information on multibuffer count, refer to the description of
the RAB$B_MBF field in the OpenVMS Record Management Services Reference Manual.
/CONTENTION_POLICY=keyword [/SYSTEM]
Allows you to specify fairness under high contention conditions for
write-shared files at the process or system level. Note that selecting
this option may noticably increase locking overhead.
This option is disabled by default.
In a mixed cluster environment with high contention for specific
buckets, it is possible for accesses to write-shared files on nodes
using read-mode global bucket locking to dominate access to a bucket.
Nodes without this support might be denied timely access to the bucket.
Additionally, it is possible to observe comparable behavior on all
OpenVMS versions when dealing with accesses to write-shared files
without global buffers enabled. A similar fairness issue between lock
conversions and new lock requests may be observed in which the new lock
requests may remain ungranted for an extended period of time. Use the
/CONTENTION_POLICY qualifier to specify fairness under high contention
conditions.
The following table lists valid PROCESS keywords (/SYSTEM not
specified):
| Keyword |
Description |
|
NEVER
|
Never use the higher overhead option to improve fairness for any
write-shared files accessed by this process; minimal overhead.
|
|
SOMETIMES
|
Use this option for fairer bucket access (but higher overhead) to any
write-shared files with global buffers enabled accessed by this process.
|
|
ALWAYS
|
Use this option for fairer bucket access (but higher overhead) to all
write-shared files accessed by this process.
|
|
SYSTEM_DEFAULT (default)
|
Use system setting. Note that this keyword is disallowed with /SYSTEM.
|
The following table lists valid SYSTEM keywords (/SYSTEM also
specified):
| Keyword |
Description |
|
NEVER (default)
|
Never use the higher overhead option to improve fairness for any
write-shared files accessed on the system; minimal overhead.
|
|
SOMETIMES
|
Use this option for fairer bucket access (but higher overhead) to any
write-shared files with global buffers enabled accessed on the system.
|
|
ALWAYS
|
Use this option for fairer bucket access (but higher overhead) to all
write-shared files accessed on the system.
|
/DISK
Applies the specified defaults to disk file operations. Values applied
using the /SEQUENTIAL qualifier take precedence over values applied
using the /DISK qualifier.
/EXTEND_QUANTITY=n
Specifies the number of blocks n to extend a sequential file
where n can range from 0 to 65535. If you do not specify the
/EXTEND_QUANTITY qualifier, RMS calculates its own extend value. The
/EXTEND_QUANTITY qualifier value is used when the program does not
specify an extent quantity explicitly.
/INDEXED
Applies the multibuffer default to indexed file operations.
/MAGTAPE
Applies the multibuffer default to magnetic tape operations. Values
applied using the /SEQUENTIAL qualifier take precedence over values
applied using the /MAGTAPE qualifier.
/NETWORK_BLOCK_COUNT=count
Specifies a default block count (0 to 127) for network access to remote
files, where count is the number of blocks to be allocated for each I/O
buffer.
For remote file access, the buffer size is negotiated between RMS and
the remote system's file access listener (FAL) with the smaller of the
two sizes being selected.
Thus, the /NETWORK_BLOCK_COUNT value places an upper limit on the
network buffer size that is used. It also places an upper limit on the
largest record that may be transferred to or from a remote file. The
largest record must be less than or equal to 512*network_block_count.
(The network_block_count is in block units and the record is in byte
units.)
If you omit the value or specify a value of 0, RMS uses the systemwide
block count value. If this value is also 0, RMS uses a size of one
block.
/PROLOG=n
Specifies a default prolog level for indexed files where acceptable
values for n are 0, 2, or 3. If 0 (default) is specified, RMS
sets an appropriate prolog level.
/QUERY_LOCK=keyword [/SYSTEM]
Enables or disables query locking at the process and system levels.
The following table lists valid PROCESS keywords (/SYSTEM not
specified):
| Keyword |
Description |
|
DISABLE
|
Disable query locking for the duration of any file opens done by images
within the process for any read ($GET or $FIND) record operations that
have both RAB$V_NLK (no lock) and RAB$V_RRL (read-regardless) set in
the RAB$L_ROP field of the RAB (Record Access Block). Disabling query
locking directs RMS not to make any calls to the lock manager for a
read record operation just to find out whether a record is locked by
another stream.
|
|
ENABLE
|
Use RMS's default record locking for images run within this process.
|
|
SYSTEM_DEFAULT (default)
|
Use system setting. Note that this keyword is disallowed with /SYSTEM.
|
The following table lists valid SYSTEM keywords (/SYSTEM also
specified):
| Keyword |
Description |
|
DISABLE
|
Disable query locking for the duration of any file opens done by images
on the system for any read ($GET or $FIND) record operations that have
both RAB$V_NLK (no lock) and RAB$V_RRL (read-regardless) set in the
RAB$L_ROP field of the RAB (Record Access Block). Disabling query
locking directs RMS not to make any calls to the lock manager for a
read record operation just to find out whether a record is locked by
another stream.
|
|
ENABLE (default)
|
Use RMS's default record locking for images run within this process.
|
There is no system parameter associated with the QUERY_LOCK setting.
/RELATIVE
Applies the multibuffer default to relative file operations.
/SEQUENTIAL (default)
Applies the multibuffer default to sequential file operations. The
/SEQUENTIAL qualifier overrides values applied using either the /DISK,
the /MAGNETIC TAPE, or the /UNIT RECORD qualifier.
The /SEQUENTIAL qualifier is the default if you do not specify either
the /RELATIVE or the /INDEXED qualifier.
/SYSTEM
Requires CMKRNL (change mode to kernel) privilege.
Applies specified defaults on a systemwide basis to all file operations.
Systemwide settings are implemented as system parameters, with the
exception of /QUERY_LOCK. For a systemwide setting to survive a system
reboot, it must be written to the system parameter file by using SYSGEN.
/UNIT_RECORD
Applies the multibuffer default to file operations on unit record
devices. Values applied using the /SEQUENTIAL qualifier take precedence
over values applied using the /UNIT_RECORD qualifier.
Examples
| #1 |
$ SET RMS_DEFAULT/BLOCK_COUNT=24
$ SHOW RMS_DEFAULT
MULTI- | MULTIBUFFER COUNTS | NETWORK
BLOCK | Indexed Relative Sequential | BLOCK
COUNT | Disk Magtape Unit Record | COUNT
Process 24 | 0 0 0 0 0 | 0
System 16 | 0 0 0 0 0 | 8
Prolog Extend Quantity QUERY_LOCK
Process 0 0 System
System 0 0 Enabled
CONTENTION_POLICY
Process System
System Never
|
The SET RMS_DEFAULT command in this example sets the multiblock count
for disk file I/O at 24 for user programs that do not set the
multiblock count explicitly. The command applies only to the current
process.
| #2 |
$ SET RMS_DEFAULT/BUFFER_COUNT=8/MAGTAPE
$ SHOW RMS_DEFAULT
MULTI- | MULTIBUFFER COUNTS | NETWORK
BLOCK | Indexed Relative Sequential | BLOCK
COUNT | Disk Magtape Unit Record | COUNT
Process 0 | 0 0 0 8 0 | 0
System 16 | 0 0 0 0 0 | 8
Prolog Extend Quantity QUERY_LOCK
Process 0 0 System
System 0 0 Enabled
CONTENTION_POLICY
Process System
System Never
|
The SET RMS_DEFAULT command in this example defines the default
multibuffer count for I/O magnetic tape operations at 8.
| #3 |
$ SET RMS_DEFAULT/BUFFER_COUNT=7/NETWORK_BLOCK_COUNT=16/SYSTEM
$ SHOW RMS_DEFAULT
MULTI- | MULTIBUFFER COUNTS | NETWORK
BLOCK | Indexed Relative Sequential | BLOCK
COUNT | Disk Magtape Unit Record | COUNT
Process 0 | 0 0 0 0 0 | 0
System 16 | 0 0 7 7 0 | 16
Prolog Extend Quantity QUERY_LOCK
Process 0 0 System
System 0 0 Enabled
CONTENTION_POLICY
Process System
System Never
|
The SET RMS_DEFAULT command in this example defines the systemwide
default multibuffer count at 7 for all sequential file operations on
disk, magnetic tape, and unit record devices. The command also sets the
network block count at 16.
| #4 |
$ SET RMS_DEFAULT/EXTEND=50/INDEXED/BUFFER_COUNT=5
$ SHOW RMS_DEFAULT
MULTI- | MULTIBUFFER COUNTS | NETWORK
BLOCK | Indexed Relative Sequential | BLOCK
COUNT | Disk Magtape Unit Record | COUNT
Process 0 | 5 0 0 0 0 | 0
System 16 | 0 0 0 0 0 | 8
Prolog Extend Quantity QUERY_LOCK
Process 0 50 System
System 0 0 Enabled
CONTENTION_POLICY
Process System
System Never
|
The SET RMS_DEFAULT command in this example sets the default
multibuffer count for I/O operations on indexed files at 5. It also
defines the default extend quantity for sequential I/O operations at 50
blocks. These defaults apply only to disk operations for user programs
that do not set the multiblock count explicitly. These defaults are
limited to the current process.
| #5 |
$ SET RMS_DEFAULT/QUERY_LOCK=DISABLE
$ SHOW RMS_DEFAULT
MULTI- | MULTIBUFFER COUNTS | NETWORK
BLOCK | Indexed Relative Sequential | BLOCK
COUNT | Disk Magtape Unit Record | COUNT
Process 0 | 0 0 0 0 0 | 0
System 16 | 0 0 0 0 0 | 8
Prolog Extend Quantity QUERY_LOCK
Process 0 0 Disabled
System 0 0 Enabled
CONTENTION_POLICY
Process System
System Never
|
The SET RMS_DEFAULT command in this example requests that query locking
be disabled for the duration of any file opens done by images within
this process for any read ($GET or $FIND) record operations that have
both RAB$V_NLK (no lock) and RAB$V_RRL (read-regardless) set in the
RAB$L_ROP field of the RAB (Record Access Block).
|
