[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

Content starts here HP OpenVMS DCL Dictionary

HP OpenVMS DCL Dictionary


Previous Contents Index

ACME Server

Dynamically loads and activates an ACME agent. An ACME agent is a shareable image that conforms to the ACME agent plug-in interface.

By default, the ACME_SERVER looks for an ACME agent file named prefix$name_ACMESHR.EXE, where prefix is VMS and name is the case insensitive string specified by NAME. The prefix can be overridden by the FACILITY keyword. Otherwise, a complete file specification can be specified with the FILE keyword.

A maximum of eight ACME agents can be configured.

The number of server threads can be specified prior to enabling ACME agent request processing by using the THREADS_MAX keyword. A maximum of 32 server threads can be specified. The default is four threads. (Specifying more threads than request-slots is not advised.)

The number of request slots is fixed at eight with three of those slots reserved for use by privileged $ACM callers.

/DISABLE

The /DISABLE qualifier is supported by the ACME server.

ACME Server

Disable (shutdown) all ACME agents. Additional ACME agents can be configured.

/ENABLE[=NAME=(name[,...])]

The /ENABLE qualifier is supported by the ACME server.

ACME Server

Enables one or more ACME agents in the specified order. Ordering of ACME agents is significant, as the ACME_SERVER processes user authentication requests in the order specified. The name variable is a case-insensitive string argument.

If you do not specify the NAME keyword, the same list of ACME agents will be enabled that were enabled by a previous /ENABLE command. If no previous /ENABLE command was issued, all configured ACME agents are enabled.

/EXIT

The /EXIT qualifier is supported by the ACME, Registry, and Security servers.

ACME Server

Requests a graceful shutdown of the ACME agents. The ACME_SERVER process will be shut down after pending requests are completed.

Registry and Security Servers

Stops the detached security server process, or stops the Registry server on the specified node or nodes in the cluster.

Cannot be used with the /ABORT, /RESTART, or /START qualifiers.

/LOG

/NOLOG (default)

The /LOG and /NOLOG qualifiers are supported by the ACME and Registry servers.

ACME Server

Creates and opens a new log file. The log file is named SYS$MANAGER:ACME$SERVER.LOG. It may be redirected by defining the system logical name ACME$SERVER.

Registry Server

Closes the current Registry server log file and creates a new file.

/MASTER

The /MASTER qualifier is supported by the Registry server.

Registry Server

Issues the command to the Registry master server only.

Requires SYSLCK privilege.

Cannot be used with the /CLUSTER, /NODE, or /START qualifiers.

/NODE=(node-name[,...])

The /NODE qualifier is supported by the ACME and Registry servers.

ACME Server

Issues the SET command to the ACME server on the specified nodes in the order they are entered. The node names must be located within the current cluster.

Registry Server

Issues the SET command to the Registry servers on the specified nodes in the order they are entered. The node names must be within the current cluster.

Cannot be used with the /CLUSTER or /MASTER qualifiers.

/RESTART

The /RESTART qualifier is supported by the ACME, Registry, and Security servers.

ACME Server

Requests a graceful shutdown of the ACME agents. The ACME_SERVER process will be shut down after pending requests are completed.

A new process will be created and the contents of the ACME$SERVER_RESTART file will be replayed. The restart file can be directed to a different location by defining the system logical name ACME$SERVER_RESTART. This file is automatically deleted following a restart.

All configuration commands issued since server startup are written to the staging file SYS$MANAGER:ACME$SERVER_CONFIG.TMP and transferred to the restart file prior to restart. The staging file can be directed to a different location by defining the system logical name ACME$SERVER_CONFIG. This file is automatically deleted at process termination.

The default path for ACME$SERVER_RESTART is: SYS$MANAGER:ACME$SERVER_RESTART.DAT

Registry and Security Servers

Restarts the detached security server process, or restarts the Registry server on the specified node or nodes in the cluster.

Cannot be used with the /ABORT, /EXIT, or /START qualifiers.

/RESUME

The /RESUME qualifier is supported by the ACME server.

ACME Server

Resumes normal operation following use of the /SUSPEND qualifier.

/START

The /START qualifier is supported by the ACME, Registry, and Security servers.

/START cannot be used with the /ABORT, /EXIT, or /RESTART qualifiers.

ACME and Registry Servers

Starts the server process. The following options are available:

To change the default privileges:


/PRIVILEGES=(privilege[,...])

To change the default UIC:


/UIC=uic

To change the default quotas:


/AST_LIMIT=n
/BUFFER_LIMIT=n
/ENQUEUE_LIMIT=n
/EXTENT=n
/FILE_LIMIT=n
/IO_BUFFERED=n
/IO_DIRECT=n
/JOB_TABLE_QUOTA=n
/MAXIMUM_WORKING_SET=n
/PAGE_FILE=n
/QUEUE_LIMIT=n
/SUBPROCESS_LIMIT=n
/WORKING_SET=n

You can use the following alternate syntax to specify a list of quotas and their values:


/QUOTAS=(quota=n[,...])

quota is a PQL-style quota name (for example: ASTLM, BIOLM)

Refer to the $CREPRC system service in the HP OpenVMS System Services Reference Manual for a list of PQL-style quota names and descriptions.

To change the image dump setting:


/DUMP (default)
/NODUMP

Forces a process dump in the event of an abnormal process termination. The dump is written to SYS$MANAGER: using the image filename and .DMP extension.

Security Server

Starts the detached security server process.

/SUSPEND

The /SUSPEND qualifier is supported by the ACME server.

ACME Server

Suspends operation after all pending requests are completed.

ACME agents are returned to their initial state (open files are closed, for example). This permits system management functions, such as system backups, to be performed without file-open conflicts.

See also the /RESUME qualifier.

/TRACE=n

/NOTRACE

The /TRACE and /NOTRACE qualifiers are supported by the ACME server.

ACME Server

Enables trace mode in the ACME$SERVER log file. Opens the log file if not already opened.

n is a bit-mask with the following assigned bits:


0   agent             Enable agent tracing
1   general           General (non-specific) tracing
2   vm                VM operations
3   ast               AST processing
4   wqe               WQE parameter values
5   report            Agent status/attributes operations
6   message           Messaging operations
7   dialogue          Dialogue operations
8   resource          Agent resource operations
9   callout           Agent callout routine
10  callout_status    Agent callout return status

If you specify /NOTRACE, trace mode is disabled and the log file remains open.

/WAIT

/NOWAIT (default)

The /WAIT and /NOWAIT qualifiers are supported by the ACME server.

ACME Server

Returns to caller once the server returns a status other than ACME$_BUSY.

Can only be used with /EXIT, /DISABLE, and /SUSPEND qualifiers.


Examples

#1

$ SET SERVER SECURITY_SERVER/EXIT
      

This command stops the detached security server process.

#2

$ SET SERVER SECURITY_SERVER/RESTART
      

This command restarts the detached security server process.

#3

$ SET SERVER REGISTRY_SERVER/RESTART/MASTER
      

This command restarts the detached Registry server on the master server.

#4

$ SET SERVER REGISTRY_SERVER/LOG/CLUSTER
      

This command closes the current log files and opens new files on all systems across the cluster.

#5

$ SET SERVER REGISTRY_SERVER/EXIT/NODE=(KAKADU,CAIRNS)
      

This command stops the detached Registry server process on nodes KAKADU and CAIRNS.


SET SHADOW (Alpha Only)

Changes the characteristics of shadow sets created using Volume Shadowing for OpenVMS. For more information about volume shadowing, refer to HP Volume Shadowing for OpenVMS.

Requires VOLPRO (volume protection override) and PHY_IO (physical I/O) privileges.


Format

SET SHADOW [device-name[:][,...]]


Parameter

device-name[:][,...]

Specifies the name of one or more shadow sets (DSAnnnn:) or shadow set members (ddcu:), depending on the command qualifiers (see parameter formats specified in some qualifier descriptions).

Where applicable, if no device name is supplied, the specified qualifiers apply to all shadow sets mounted on the node from which the command is executed.


Description

The SET SHADOW command and its qualifiers are designed to give the user greater control over the behavior of shadow sets. These commands act upon the shadow set (also known as the virtual unit) or, in some cases, on the individual shadow set member that you specify. The qualifier settings remain in effect until they are changed using either the SET SHADOW or SET DEVICE command or until the shadow set or shadow set member is dismounted. If the shadow set is remounted or a shadow set member is returned to the shadow set from which it was dismounted, the settings must be specified again.

As noted previously, some SET SHADOW qualifiers also can be specified using the SET DEVICE command, where they have the same effect. However, if your focus is on changing characteristics of shadow sets, the SET SHADOW command provides more options.


Qualifiers

/ABORT_VIRTUAL_UNIT DSAnnnn:

Aborts mount verification on a shadow set.

Use this qualifier when you know that the unit cannot be recovered. When you use this qualifier, the shadow set must be in mount verification. The shadow set aborts mount verification immediately on the node from which the command is issued. If the shadow set is not in mount verification, this command returns the error %SYSTEM-E-UNSUPPORTED, unsupported operation or function.

After this command completes, the shadow set still must be dismounted. Use the following command to dismount the shadow set:


$ DISMOUNT/ABORT DSAnnnn:

/COPY_SOURCE {ddcu: | DSAnnnn:}

Specifies which source member of a shadow set will be used as the source for read data during full copy operations when a third member is added to the shadow set. This qualifier affects only copy operations that do not use disk copy data (DCD) commands.

Some storage controllers, such as the HSG80, have a read-ahead cache, which significantly improves single-disk read performance. Copy operations normally alternate reads between the two source members, which effectively nullifies the benefits of the read-ahead cache. This qualifier lets you force all reads from a single, specified source member for a copy operation.

If only a shadow set (DSAnnnn:) is specified, all reads for full copy operations will be performed from the disk that is the current "master" member, regardless of physical location of the disk.

If a shadow set member (ddcu:) is specified, that member will be used as the source of all copy operations. This allows you to choose a local source member, rather than a remote master member.

/DEMAND_MERGE

Initiates a merge operation on the specified shadow set. This qualifier is useful if the shadow set was created with the INITIALIZE/SHADOW command without the use of the /ERASE qualifier. For more information about using /DEMAND_MERGE, refer to the HP Volume Shadowing for OpenVMS manual.

/FORCE_REMOVAL ddcu:

Expels the specified shadow set member from the shadow set.

If connectivity to a device has been lost and the shadow set is in mount verification, this qualifier causes the member to be expelled from the shadow set immediately.

If the shadow set is not currently in mount verification, no immediate action is taken. If connectivity to a device has been lost but the shadow set is not in mount verification, this qualifier lets you flag the member to be expelled from the shadow set, as soon as it does enter mount verification.

The specified device must be a member of a shadow set that is mounted on the node where the command is issued.

/LOG

Instructs the volume shadowing software to display a brief message confirming that the SET SHADOW command completed. If /OUTPUT is also specified, this information is written to the output file.

/MEMBER_TIMEOUT=n ddcu:

Specifies the timeout value to be used for a shadow set member.

The value supplied by this qualifier overrides the system parameter SHADOW_MBR_TMO for this specific device. Each member of a shadow set can be assigned a different MEMBER_TIMEOUT value.

The valid range for n is 1 to 16777215 seconds.

The specified device must be a member of a shadow set that is mounted on the node where the command is issued.

/MVTIMEOUT=n DSAnnnn:

Specifies the mount verification timeout value to be used for the shadow set specified by its virtual unit name (DSAnnnn:).

The value supplied by this qualifier overrides the value specified by the system parameter MVTIMEOUT for this specific shadow set.

The valid range for n is 1 to 16777215 seconds.

The specified shadow set must be mounted on the node where the command is issued.

/OUTPUT=file-name

Outputs any messages to the specified file.

/READ_COST=n {ddcu: | DSAnnnn:}

Enables you to modify the default cost assigned to each shadow set member (ddcu:). By modifying the assignments, you can bias the reads in favor of one member of a two-member shadow set, or, in the case of three-member shadow sets, in favor of one or two members of the set over the remaining members. The device specified must be a shadow set or member of a shadow set that is mounted on the node where the command is issued.

The valid range for the specified cost is 1 to 65,535 units.

The shadowing driver assigns default READ_COST values to shadow set members when each member is initially mounted. The default value depends on the device type and its configuration relative to the system mounting it. The following list of device types is ordered by the default READ_COST assignments, from the lowest cost to the highest cost:

  • DECram device
  • Directly connected device in the same physical location
  • Directly connected device in a remote location
  • DECram served device
  • Default value for other served devices

The value supplied by the /READ_COST qualifier overrides the default assignment. The shadowing driver adds the value of the current queue depth of the shadow set member to the READ_COST value and then reads from the member with the lowest value.

Different systems in the cluster can assign different costs to each shadow set member.

When this qualifier specifies a shadow set (DSAnnnn:) instead of a shadow set member, the /READ_COST qualifier switches the read cost setting for all shadow set members back to the default read cost settings established automatically by the shadowing software. The specified shadow set must be mounted on the node where the command is issued. In this case, the value specified for the cost can be any number because it will be ignored.

If the /SITE command qualifier has been specified, the shadowing driver takes site values into account when it assigns default READ_COST values. In order for the shadowing software to determine whether a device is in the category of "directly connected device in a remote location," the /SITE command qualifier must have been applied to both the shadow set and the shadow set member.

Reads requested for a shadow set from a system at site 1 are performed from a shadow set member that is also at site 1. Reads requested for the same shadow set from site 2 can read from the member located at site 2.

/SITE=n {DSAnnnn: | ddcu:}

Indicates to the shadowing driver the site location of the specified shadow set (DSAnnnn:) or shadow set member (ddcu:).

The SHADOW_SITE_ID system parameter defines the default site location of the shadow set. You can override the default location of the shadow set with the /SITE qualifier.

The valid range for the site location, represented by n, is 1 through 255.

After you apply this qualifier, the setting remains in effect until you change it either with this command or with the SET DEVICE/SITE command.

This qualifier can improve read performance because the member that is physically local to the system will be the preferred disk from which to read, provided that you specify the /SITE qualifier for each shadow set member and for the shadow set. (In a Fibre Channel configuration, shadow set members at different sites are directly attached to the system. For the Volume Shadowing and cluster software, there is no distinction between local and remote in multiple-site Fibre Channel configurations.)


Example


$ ! Command sequence used on system 1 at site 1:
$ MOUNT/SYSTEM DSA0:/SHADOW=($1$DGA0:,$1$DGA1:) TEST
$ SET SHADOW/SITE=1  DSA0:
$ !
$ ! Command sequence used on system 2 at site 2:
$ MOUNT/SYSTEM DSA0:/SHADOW=($1$DGA0:,$1$DGA1:) TEST
$ SET SHADOW/SITE=2  DSA0:
$ !
$ ! Commands used on both system 1 and system 2:
$ SET SHADOW/SITE=1  $1$DGA0:
$ SET SHADOW/SITE=2  $1$DGA1:

      

In this example, the system at site 1 will perform all reads from $1$DGA0, which is the physically local disk, while the system at site 2 will perform all reads from its physically local disk, $1$DGA1.


SET SYMBOL

Controls access to local and global symbols in command procedures.

Format

SET SYMBOL


Description

The SET SYMBOL command controls access to local and global symbols in command procedures by treating symbols as undefined. Because all global and local symbols defined in an outer procedure level are accessible to inner procedure levels, it is often necessary to mask these symbols without deleting them.

The SET SYMBOL command also controls whether DCL will attempt to translate the verb string (the first token on the command line) as a symbol before processing the line. The default behavior is that the translation is attempted. The advantage to changing this behavior is that a command procedure will not be affected by outer procedure level environments when invoking a command.

The symbol scoping context is different for local and global symbols. Local symbols are procedure level dependent. Local symbols defined in an outer subroutine level can be read at any inner subroutine level, but they cannot be written to. If you assign a value to a symbol that is local to an outer subroutine level, a new symbol is created at the current subroutine level; however, the symbol in the outer procedure level is not modified.

This means that the SET SYMBOL/SCOPE=NOLOCAL command causes all local symbols defined at an outer procedure level to be inaccessible to the current procedure level and any inner levels. For example, if SET SYMBOL/SCOPE=NOLOCAL was specified at procedure levels 2 and 4, procedure level 2 can read (but not write to) only level 2 local symbols. Level 3 can read (but not write to) level 2 local symbols and can read and write to level 3 local symbols. Level 4 can read and write to only level 4 local symbols.

Global symbols are procedure-level independent. The current global symbol scoping context is applied subsequently to all procedure levels. Specifying the /SCOPE=NOGLOBAL qualifier causes all global symbols to become inaccessible for all subsequent commands until either the /SCOPE=GLOBAL qualifier is specified or the procedure exits to a previous level at which global symbols were accessible. In addition, specifying the /SCOPE=NOGLOBAL qualifier prevents you from creating any new global symbols until the /SCOPE=GLOBAL qualifier is specified.

When you exit a procedure level to return to a previous procedure, the symbol scoping context from the previous level is restored for both local and global symbols.

To display the current symbol scoping state, use the lexical function F$ENVIRONMENT("SYMBOL_SCOPE").


Qualifiers

/ALL (default)

Specifies that the values of the /SCOPE qualifier pertain both to the translation of the first token on a command line and to general symbol substitution.

The /ALL qualifier is incompatible with the /GENERAL or the /VERB qualifier.

/GENERAL

Specifies that the values of the /SCOPE qualifier pertain to the translation of all symbols except the first token on a command line.

The /GENERAL qualifier is incompatible with the /ALL or the /VERB qualifier.

/SCOPE=(keyword,...)

Controls access to local and global symbols. Lets you treat symbols as being undefined. Possible keywords are as follows:
NOLOCAL Causes all local symbols defined in outer procedure levels to be treated as being undefined by the current procedure and by all inner procedure levels.
LOCAL Removes any symbol translation limit set by the current procedure level.
NOGLOBAL Causes all global symbols to be inaccessible to the current procedure level and to all inner procedure levels unless otherwise changed.
GLOBAL Restores access to all global symbols.

/VERB

Specifies that the values of the /SCOPE qualifier pertain to the translation of the first token on a command line as a symbol before processing only. It does not affect general symbol substitution.

Note

Caution must be used if the SET SYMBOL/VERB/SCOPE command is used more than once in a command procedure. Because DCL uses the translation behavior when looking for a label or subroutine, execution may be different running in one mode than in another. HP recommends that the SET SYMBOL/VERB/SCOPE command be used once as part of the command procedure setup and left in that mode for the duration of the procedure.

The /VERB qualifier is incompatible with the /ALL or the /GENERAL qualifier.


Examples

#1

$ SET SYMBOL/SCOPE=NOLOCAL
      

In this example, all local symbols defined in outer procedure levels are now undefined for the current procedure level and all inner procedure levels.

#2

$ SET SYMBOL/SCOPE=NOGLOBAL
      

In this example, all global symbols are now inaccessible to the current procedure level and all inner procedure levels unless otherwise changed.

#3

$ NOW :== SHOW TIME
$ !
$ NOW
   3-NOV-2001 11:48:58
$ !
$ SET SYMBOL /VERB /SCOPE=NOGLOBAL
$ NOW
%DCL-W-IVVERB, unrecognized command verb-check validity and spelling
 \NOW\
$ !
$ SHOW SYMBOL NOW
  NOW == "SHOW TIME"
      

This example demonstrates the use of the /VERB qualifier.

The symbol NOW is assigned to the SHOW TIME command. The next line shows the default behavior, where DCL attempts to translate the first string on the command line (NOW). Because NOW translates to the SHOW TIME command, this is used instead of NOW.

The SET SYMBOL command on the next line changes the behavior so that DCL does not attempt a translation. When NOW is subsequently entered, DCL uses the string NOW as the command verb and cannot find it in the command table. This results in the error message.

Notice that the scoping of the verb translation has no effect on general symbol translations, as demonstrated by the SHOW SYMBOL command in the example.


Previous Next Contents Index