HP OpenVMS Systems Documentation

Content starts here HP OpenVMS System Management Utilities Reference Manual

HP OpenVMS System Management Utilities Reference Manual


Previous Contents Index

IO CREATE_WWID (Alpha Only)

Assigns a specific, previously unused device name to a specific, previously unused worldwide identifier (WWID) from the SYSMAN IO LIST_WWID display.

HP recommends that you execute this command clusterwide and that you follow the command with a SYSMAN IO AUTOCONFIGURE command to actually configure the device.


Format

IO CREATE_WWID devnam_string/WWID=wwid_string


Parameter

devnam_string

Specifies a device-name string. The string must be in the form $2$MGAn, where n is less than 9999.

Qualifier

/WWID=wwid_string

Specifies a WWID string that comes directly from a SYSMAN IO LIST_WWID display.

This qualifier is required.


Description

This command is an alternative to the SYSMAN IO FIND_WWID command, which selects system-generated device names for the discovered WWIDs. Do not, however, use the SYSMAN IO CREATE_WWID command after the SYSMAN IO FIND_WWID command to redefine WWID correlations. Also, do not specify device and WWID strings in the SYSMAN IO CREATE_WWID command that are specified elsewhere in the cluster.

Example


SYSMAN> SET ENVIRONMENT/CLUSTER
SYSMAN> IO CREATE_WWID $2$MGA5/WWID=04100022:"DEC TZ89 (C) DECCX939S2777"
SYSMAN> IO CREATE_WWID $2$MGA3/WWID=02000008:500E-09E0-0005-30D7
SYSMAN> IO AUTOCONFIGURE
      

The commands in this example create two device names, $2$MGA5 and $2$MGA3, and configure the devices.

IO FIND_WWID (Alpha Only)

The SYSMAN IO FIND_WWID command probes all Fibre Channel ports, detects all previously undiscovered tapes and medium changers behind a Network Storage Router (NSR) or a Modular Data Router (MDR), and assigns a worldwide identifier (WWID) to each one.

The command also displays a list of the devices and their assigned device names and automatically records this information in the SYS$SYSTEM:SYS$DEVICES.DAT file. Finally, the command updates relevant local and clusterwide memory structures.

To configure newly attached Fibre Channel tapes, use this command prior to running the SYSMAN command IO AUTOCONFIGURE.

You must have CMKRNL privilege to use the SYSMAN IO FIND_WWID command.

For more information about Fibre Channel, see the Guidelines for OpenVMS Cluster Configurations.


Format

IO FIND_WWID


Description

Prior to configuring a tape device on Fibre Channel ports, the worldwide identifier (WWID) of the device must be detected and stored, along with a device name, in the text file SYS$SYSTEM:SYS$DEVICES.DAT. You use the SYSMAN command IO FIND_WWID to accomplish this.

The SYSMAN IO FIND_WWID command probes all Fibre Channel ports and locates all tape and medium changer devices. For tapes and medium changers that have not been detected by any previous SYSMAN IO FIND_WWID command, IO FIND_WWID assigns a device name, retrieves the WWID of the device, stores the device name and WWID data in the SYS$SYSTEM:SYS$DEVICES.DAT file, and updates memory structures.

Because the main goal of SYSMAN IO FIND_WWID is to populate the SYS$DEVICES.DAT file, you need to invoke the SYSMAN IO FIND_WWID command only one time for each new device. Note that using the SYSMAN IO FIND_WWID command for the first time detects all existing tape and medium changer devices on the system at that time.

Once the information is stored in the file, subsequent use of the SYSMAN IO AUTOCONFIGURE command reads the file and configures the tape and medium changer devices automatically, loading or connecting the device drivers as needed. The SYS$DEVICES.DAT file is read during each system reboot, initiating the automatic configuration of tapes and medium changers on the Fibre Channel. (SYSMAN IO FIND_WWID does not load or connect the actual device drivers.)

Note

If you add more devices to the system at a later time, you must powercycle the MDR to update internal mapping information. You must also run the SYSMAN IO FIND_WWID command again to append the new device information to the SYS$DEVICES.DAT file.

Similarly, for the Network Storage Router (NSR), the LUN map must be updated.

In an OpenVMS cluster environment, you must run the SYSMAN IO FIND_WWID command on each node in the cluster to update various data structures in memory. Alternatively, you can run SYSMAN IO FIND_WWID on one node, and then reboot the other nodes that share that same system disk, because the SYS$DEVICES.DAT file is read at boot time and causes memory structures to be correctly initialized.

In the case of multiple system disks in the cluster, ensure that all copies of the SYS$DEVICES.DAT file are kept consistent, preferably by running the SYSMAN IO FIND_WWID command on all nodes. Alternatively, you can run IO FIND_WWID to update just one SYS$DEVICES.DAT file, and then manually edit the remaining SYS$DEVICES.DAT files by cutting and pasting the appropriate devnam/WWID records from the original file to the target files.

HP recommends that you refrain from copying the entire original file to another system disk, because the SYS$DEVICES.DAT file is also used to define Port Allocation Classes, and PAC entries could be inadvertently transferred to the target system.


Example


SYSMAN> IO FIND_WWID
%SYSMAN-I-OUTPUT, command execution on node SAMPLE
On port _SAMPLE$PGA0:, the following tape WWIDs and their proposed
device names have been found but not yet configured:

      [Device $2$GGA0]
      WWID=04100024:"DEC     TL800    (C) DEC3G9CCR82A017"

      [Device $2$MGA0]
      WWID=04100022:"DEC     TZ89     (C) DECCX939S2777"

      [Device $2$MGA1]
      WWID=04100022:"DEC     TZ89     (C) DECCX942S6295"

      

This is a configuration example using a TL891 tape library. The SYSMAN command IO FIND_WWID displays a list of all previously undiscovered tape devices and their device names.

Note that the overall WWID consists of everything to the right of the equal sign. Each such WWID is unique; however, the header portion might not be unique, because the header reflects only the basic type and length of the the WWID data.

The SYSMAN IO FIND_WWID command automatically records the information about the new tape devices in SYS$SYSTEM:SYS$DEVICES.DAT:


$ TYPE SYS$SYSTEM:SYS$DEVICES.DAT
!
! Updated 23-OCT-2002 14:17:41.85:  DEC TL800
!
[Device $2$GGA0]
WWID=04100024:"DEC     TL800    (C) DEC3G9CCR82A017"
!
!
! Updated 23-OCT-2002 14:17:41.93:  DEC TZ89
!
[Device $2$MGA0]
WWID=04100022:"DEC     TZ89     (C) DECCX939S2777"
!
!
! Updated 23-OCT-2002 14:17:42.01:  DEC TZ89
!
[Device $2$MGA1]
WWID=04100022:"DEC     TZ89     (C) DECCX942S6295"
!

You would then use the SYSMAN command IO CONFIGURE to configure these devices. After you completed this step, the SHOW DEVICE/FULL command would display the worldwide identifier of the tape.

IO LIST_WWID (Alpha Only)

Applies only to tape devices on Fibre Channel. Lists all tape device WWIDs that are not yet configured on Fibre Channel.

You can use the output of this command as input to the SYSMAN IO CREATE_WWID and SYSMAN IO REPLACE_WWID commands.


Format

IO LIST_WWID


Example


SYSMAN> IO LIST_WWID
%SYSMAN-I-OUTPUT, command execution on node ROCKY

On port _ROCKY$PGA0:, the following tape WWIDs are not yet configured:

Target 3, LUN 1, COMPAQ   SuperDLT1
WWID=02000008:500E-09E0-0005-30D7

Target 3, LUN 3, COMPAQ   SDX-500C
WWID=0C000008:0800-4606-C00D-473F

Target 4, LUN 1, COMPAQ   SuperDLT1
WWID=02000008:500E-09E0-0005-30D7

Target 4, LUN 3, COMPAQ   SDX-500C
WWID=0C000008:0800-4606-C00D-473F

      

In this example, each drive is listed twice because the tape bridge is dual-ported, with one FC port at target 3 and the other FC port at target 4.

IO LOAD (Alpha Only)

On Alpha systems, loads an I/O driver. On VAX systems, use the SYSGEN command LOAD.

You must have CMKRNL and SYSLCK privileges to use the SYSMAN IO LOAD command.

Note

Be very careful when issuing a SYSMAN IO LOAD command because the system does little error-checking.

Format

IO LOAD filespec


Parameter

filespec

Specifies the file name of the driver to be loaded. This parameter is required.

Qualifier

/LOG=(ALL,DPT)

Controls whether SYSMAN displays information about drivers that have been loaded. The default value for the /LOG qualifier is /LOG=ALL. The driver prologue table (DPT) address is displayed when either /LOG=DPT or /LOG=ALL is specified.

Description

The SYSMAN IO LOAD command loads an I/O driver. VAX system managers use the SYSGEN command LOAD. You must have CMKRNL and SYSLCK privileges to use the SYSMAN IO LOAD command.

Example


SYSMAN> IO LOAD/LOG SYS$DKDRIVER
%SYSMAN-I-IOADDRESS, the DPT is located at address 80D5A000
      

This example loads device SYS$DKDRIVER and displays the address of the driver prologue table (DPT).

IO REBUILD (Alpha Only)

On Alpha systems, rebuilds device configuration tables in preparation for using the SYSMAN IO AUTOCONFIGURE command to reconfigure the system.

You must have CMKRNL privilege to use the SYSMAN IO REBUILD command.


Format

IO REBUILD


Parameters

None.

Qualifier

/VERIFY

Causes SYSMAN to read and process the files SYS$SYSTEM:SYS$USER_CONFIG.DAT and SYS$SYSTEM:CONFIG.DAT, but not to apply the files to the I/O database. Messages will be displayed for any errors that are encountered. This command can be used by developers to test new changes to SYS$SYSTEM:SYS$USER_CONFIG.DAT without modifying the current system.

Description

The SYSMAN IO REBUILD command rebuilds the system's device configuration tables by reading and parsing the SYS$SYSTEM:SYS$USER_CONFIG.DAT and SYS$SYSTEM:SYS$CONFIG.DAT files.

To debug modifications to the SYS$SYSTEM:SYS$USER_CONFIG.DAT file, you can use the SYSMAN IO REBUILD and SYSMAN IO AUTOCONFIGURE commands to load drivers without having to reboot. Once you load a driver for an adapter, however, you cannot reload it without rebooting the system.


Example


SYSMAN> IO REBUILD
SYSMAN> IO AUTOCONFIGURE

      

The first command in this example rebuilds device configuration tables. The second command reads the device configuration tables and loads drivers for newly defined drivers.

IO REPLACE_WWID (Alpha Only)

This command allows a user to replace one tape drive behind a Network Storage Router (NSR) with another tape drive at the same Fibre Channel (FC) Logical Unit Number (LUN) location.

This command updates all the necessary file and memory data structures with the WWID of the new tape drive. The name of the replacement drive will be the same as the name of the original drive.

This command is primarily intended to be used when a hardware problem occurs on a tape drive, and a replacement drive must installed in its place.

The command requires CMKRNL privilege. It applies only to FC tapes behind a Fibre Channel tape bridge such as an NSR or MDR (Modular Data Router).

For more information about Fibre Channel, see the Guidelines for OpenVMS Cluster Configurations.


Format

IO REPLACE_WWID devnam_string/WWID=wwid_string


Parameter

devnam_string

Specifies a tape device name.

Qualifier

/WWID=wwid_string

Specifies a string that comes directly from a SYSMAN IO LIST_WWID display. The use of this qualifier is appropriate only under the circumstances explained in the description below.

Description

You can use the two parameters, devnam_string and wwid_string, with the REPLACE_WWID command to replace a broken tape device with a new device. The command automatically updates the data structures that record the new devnam-WWID correlation, and the device automiatically begins to function correctly.

This command is useful in two different cases:

  • In one case, the drive might malfunction and need to be replaced immediately without rebooting the system. If this happens, the drive is physically replaced with a new drive, and the command SYSMAN IO REPLACE_WWID $2$MGAn is issued clusterwide. The /WWID qualifier is not appropriate in this case, because the new WWID is automatically detected using information stored in the device's data structures.
  • In the other case, the drive might malfunction and not be replaced until after the system has been shut down or rebooted. The device name no longer appears in the SHOW DEVICE display because the device failed to configure during the reboot.
    The configuration failure occurred either because the broken drive did not respond, or because the new drive has a different WWID from the one SYSMAN IO AUTOCONFIGURE expected at boot time. Therefore, in this situation, in which the device name is in SYS$DEVICES.DAT but not in the SHOW DEVICE display, use the /WWID qualifier to define the new devnam-WWID correlation.
    Follow these steps clusterwide:
    1. Execute the SYSMAN IO LIST_WWID command to display the new WWID.
    2. Use the command SYSMAN IO REPLACE_WWID $2$MGAn/WWID=new_wwid to define the new correlation.
    3. Use the SYSMAN IO AUTOCONFIGURE command to configure the device.

When you use the SYSMAN IO LIST_WWID command, keep in mind that:

  • You must set the replacement device to the same SCSI target ID as the original device.
  • You must stop all activity on the device before issuing the SYSMAN IO REPLACE_WWID command.
  • The command requires CMKRNL privilege and applies only to FC tapes behind an NSR or MDR.

Example


SYSMAN> SET ENVIRONMENT/CLUSTER
SYSMAN> IO REPLACE_WWID $2$MGA3/WWID=02000008:500E-09E0-0005-30D7
SYSMAN> IO AUTOCONFIGURE
      

In this example, the device named $2$MGA3 malfunctioned and was replaced while the system was down. Upon reboot, the drive did not get configured, because its new WWID did not match the WWID that OpenVMS expected. Therefore, the user redefines the devnam-WWID correlation and is then able to configure $2$MGA3 correctly. The specified WWID comes from the output of the SYSMAN IO LIST_WWID command.

IO SCSI_PATH_VERIFY (Alpha Only)

On Alpha systems, the SYSMAN IO SCSI_PATH_VERIFY subcommand checks each SCSI and FC path in the system to determine whether the attached device has been changed. If a device change is detected, then the SCSI or FC path is disconnected in the IO database. This allows the path to be reconfigured on the new device, by using the SYSMAN IO AUTOCONFIGURE command.

You must have CMKRNL privilege to use the SYSMAN IO SCSI_PATH_VERIFY command.


Format

IO SCSI_PATH_VERIFY


Parameters

None.

Qualifiers

None.

Description

You usually enter the SYSMAN IO SCSI_PATH_VERIFY command after performing an online reconfiguration of a SCSI or an FC interconnect. The command reads the device type and device identifier on each SCSI and FC path in the system. If the device does not match the data stored in the IO database, then the path is disconnected in the IO database. Following a SYSMAN IO SCSI_PATH_VERIFY command, you usually enter a SYSMAN IO AUTOCONFIGURE command, which updates the IO database to match the new SCSI or FC configuration.

Example


SYSMAN> IO SCSI_PATH_VERIFY
SYSMAN> IO AUTOCONFIGURE

      

The first command in this example checks all SCSI paths and disconnects the ones that are no longer valid. The second command autoconfigures all devices that are physically attached to the system.

IO SET EXCLUDE (Alpha Only)

On Alpha systems, sets the permanent exclusion list to be used when configuring devices automatically.

Format

IO SET EXCLUDE = device_name


Parameter

device_name

Specifies the device type to be excluded from automatic configuration. Use valid device names or mnemonics that indicate the devices to be included in the permanent exclusion list. You can specify wildcards.

Qualifiers

None.

Description

Sets the permanent exclusion list to be used when configuring devices.

You can use this command to permanently specify device autoconfiguration to exclude Fibre Channel port driver devices (FG) and any SCSI port driver devices (PK) at each system boot. (To specify permanently the exclusion or inclusion of devices for the duration of a manual configuration command, use the /EXCLUDE or /SELECT qualifier with the SYSMAN IO AUTOCONFIGURE command.)

You cannot use the SYSMAN IO SET EXCLUDE command to exclude any of the following device types:

  • SCSI class-driver devices (DK, MK, GK) whose names include a port allocation class or an HSZ allocation class
  • Fibre Channel class-driver devices (PG, DG, GG)

This restriction also applies to SCSI devices on OpenVMS Alpha Version 7.1 systems, if the SCSI device names include a port allocation class.


Example


SYSMAN> IO SET EXCLUDE=(DKC500,DKD*)
      

This example specifies that DKC500 and all DKD devices are not to be autoconfigured.

Refer to the /SELECT qualifier for additional examples that show how to specify device names.

IO SET PREFIX (Alpha Only)

On Alpha systems, sets the prefix list that is used to manufacture the IOGEN Configuration Building Module (ICBM) names.

Format

IO SET PREFIX =icbm_prefix


Parameter

icbm_prefix

Specifies ICBM prefixes. These prefixes are used by the SYSMAN IO AUTOCONFIGURE command to build ICBM image names.

Qualifiers

None.

Description

The SYSMAN IO SET PREFIX command sets the prefix list which is used to manufacture ICBM names.

Example


SYSMAN> IO SET PREFIX=(SYS$,PSI$,VME_)
      

This example specifies the prefix names used by SYSMAN IO AUTOCONFIGURE to build the ICBM names. The prefixes are SYS$, PSI$, and VME_.

IO SHOW BUS (Alpha Only)

On Alpha systems, lists all the buses, node numbers, bus names, TR numbers, and base CSR addresses on the system. This display exists primarily for internal engineering support.

On VAX systems, use the SYSGEN command SHOW/BUS.


Parameters

None.

Qualifiers

None.

Description

The SYSMAN IO SHOW BUS command lists all the buses, node numbers, bus names, TR numbers, and base CSR addresses. This display exists primarily for internal engineering support. You must have CMKRNL privilege to use SYSMAN IO SHOW BUS.

Example


SYSMAN> IO SHOW BUS
_Bus__________Node_TR#__Name____________Base CSR__________
LSB           0    1    EV3 4MB        FFFFFFFF86FA0000
LSB           6    1    MEM            FFFFFFFF86FC4000
LSB           7    1    MEM            FFFFFFFF86FCA000
LSB           8    1    IOP            FFFFFFFF86FD0000
XZA XMI-SCSI  0    3    XZA-SCSI       0000008001880000
XZA XMI-SCSI  1    3    XZA-SCSI       0000008001880000
XZA XMI-SCSI  0    4    XZA-SCSI       0000008001900000
XZA XMI-SCSI  1    4    XZA-SCSI       0000008001900000
XMI           4    2    LAMB           0000008001A00000
DEMNA         0    5    Generic XMI    0000008001E80000
DEMNA         0    6    Generic XMI    0000008001F00000
      

This example is from a DEC 7000 Model 600. Displays vary among different Alpha systems.

The indentation levels are deliberate in this display. They indicate the hierarchy of the adapter control blocks in the system. The column titles in the display have the following meanings:

Column Titles Meaning
Bus Identity of the bus
Node Index into the associated bus array; the bus slot
TR# Nexus number of the adapter to which the specified device is connected
Name Name of the device
Base CSR Base CSR address of the device

On Alpha systems, you can use the SDA command CLUE CONFIG to display additional information including hardware adapters and devices. This command is documented in the OpenVMS Alpha System Dump Analyzer Utility Manual.

For more information about loading and configuing device drivers, refer to Writing OpenVMS Alpha Device Drivers in C.

IO SHOW DEVICE (Alpha Only)

On Alpha systems, displays information about device drivers loaded into the system, the devices connected to them, and their I/O databases. All addresses are in hexadecimal and are virtual. On VAX systems, use the SYSGEN command SHOW/DEVICE.

Format

IO SHOW DEVICE


Parameters

None.

Qualifiers

None.

Description

The SYSMAN IO SHOW DEVICE command displays information about the device drivers loaded into the system, the devices connected to them, and their I/O databases.

The SYSMAN IO SHOW DEVICE command specifies that the following information be displayed about the specified device driver:

Driver Name of the driver
Dev Name of each device connected to the driver
DDB Address of the device's device data block
CRB Address of the device's channel request block
IDB Address of the device's interrupt dispatch block
Unit Number of each unit on the device
UCB Address of each unit's unit control block

All addresses are in hexadecimal and are virtual.

Refer to A Comparison of System Management on OpenVMS AXP and OpenVMS VAX (archived but available on the OpenVMS Documentation CD-ROM). and the HP OpenVMS System Manager's Manual for additional information about SYSMAN.


Example


SYSMAN> IO SHOW DEVICE
      

The following example is a sample display produced by the SYSMAN IO SHOW DEVICE command:


__Driver________Dev_DDB______CRB______IDB______Unit_UCB_____
SYS$FTDRIVER
                FTA 802CE930 802D1250 802D04C0
                                                 0 801C3710
SYS$EUDRIVER
                EUA 802D0D80 802D1330 802D0D10
                                                 0 801E35A0
SYS$DKDRIVER
                DKI 802D0FB0 802D0F40 802D0E60
                                                 0 801E2520
SYS$PKADRIVER
                PKI 802D1100 802D13A0 802D1090
                                                 0 801E1210
SYS$TTDRIVER
OPERATOR
NLDRIVER

SYS$TTDRIVER, OPERATOR, and NLDRIVER do not have devices associated with them.

IO SHOW EXCLUDE (Alpha Only)

On Alpha systems, displays the permanent exclusion list used in the autoconfiguration of devices.

Format

IO SHOW EXCLUDE


Parameters

None.

Qualifiers

None.

Description

The SYSMAN IO SHOW EXCLUDE command displays the permanent exclusion list on the console. This list is used in the autoconfiguration of devices.

Example


SYSMAN> IO SHOW EXCLUDE
%SYSMAN-I-IOEXCLUDE, the current permanent exclusion list is: DKC500,DKD*
      

This example shows the permanent exclusion list used in the autoconfiguration of devices; the current list contains DKC500 and all DKD devices.

IO SHOW PREFIX (Alpha Only)

On Alpha systems, displays the current prefix list used in the manufacture of IOGEN Configuration Building Module (ICBM) names.

Format

IO SHOW PREFIX


Parameters

None.

Qualifiers

None.

Description

The SYSMAN IO SHOW PREFIX command displays the current prefix list on the console. This list is used by the SYSMAN IO AUTOCONFIGURE command to build ICBM names.

Example


SYSMAN> IO SHOW PREFIX
%SYSMAN-I-IOPREFIX, the current prefix list is: SYS$,PSI$,VME_
      

This example shows the prefixes used by SYSMAN IO AUTOCONFIGURE to build ICBM names.

LICENSE LOAD

Activates licenses registered in the LICENSE database.

Requires CMKRNL, SYSNAM, and SYSPRV privileges.

Note

Except for the number of status messages returned, the following commands are functionally equivalent:


SYSMAN> LICENSE LOAD
$ LICENSE LOAD

To see all the status messages on remote nodes for the DCL command, you can use the following SYSMAN command:


SYSMAN> DO LICENSE LOAD

Format

LICENSE LOAD product


Parameter

product

Specifies the name of the product whose license you want to activate.

Qualifiers

/DATABASE=filespec

Specifies the location of the LICENSE database. The default file specification is SYS$COMMON:[SYSEXE]LMF$LICENSE.LDB. Using the /DATABASE qualifier is not necessary if you use the default LICENSE database name and location.

/PRODUCER=string

Specifies the name of the company that owns the product for which you have a license. Use this qualifier only if the product is from a company other than HP.

Description

You can use the LICENSE LOAD command to activate licenses on multiple systems and on nonlocal systems in the system management environment. The SYSMAN LICENSE commands are a subset of the License Management Facility (LMF) commands. For more information about the LMF, refer to the OpenVMS License Management Utility Manual.

Example


SYSMAN> LICENSE LOAD FORTRAN
      

This example activates the license for HP Fortran for OpenVMS. Because the license is for a HP product, the command does not include the /PRODUCER qualifier.

LICENSE UNLOAD

Deactivates licenses registered in the LICENSE database.

Requires CMKRNL, SYSNAM, and SYSPRV privileges.


Format

LICENSE UNLOAD [product]


Parameter

product

Specifies the name of the product whose license you want to deactivate. If you enter the LICENSE UNLOAD command without specifying a product name, the system deactivates all available registered licenses.

Qualifier

/PRODUCER=string

Specifies the name of the company that owns the product for which you have a license. Use this qualifier only if the product is from a company other than HP.

Description

You can use the LICENSE UNLOAD command to deactivate licenses on multiple systems and on nonlocal systems in the system management environment. The SYSMAN LICENSE commands are a subset of the License Management Facility (LMF) commands. For more information about the LMF, refer to the OpenVMS License Management Utility Manual.

Example


SYSMAN> LICENSE UNLOAD FORTRAN
      

This command deactivates the license for HP Fortran for OpenVMS. Because the license is for a HP product, the command does not include the /PRODUCER qualifier.

PARAMETERS DISABLE CHECKS

Bypasses validation of parameter values. SYSMAN parameter validation ensures that the parameters fall within the defined minimum and maximum values specified in the PARAMETERS SET command.

Format

PARAMETERS DISABLE CHECKS


Parameters

None.

Qualifiers

None.

Description

The PARAMETERS DISABLE CHECKS command enables you to override minimum and maximum values established for system parameters. SYSMAN does parameter checks by default. If you attempt to set parameter values outside the allowable limits when checks are enabled, the operating system issues an error message. By disabling checks you can set parameter values regardless of the minimum and maximum limits.

Note

Range checks are enabled by default because HP suggests that systems operate within these minimum and maximum values. Setting parameters outside these limits can result in system failures or hangs.

Example


SYSMAN> SET ENVIRONMENT/CLUSTER
SYSMAN> SET PROFILE/DEFAULT=SYS$SYSTEM/PRIVILEGES=CMEXEC
SYSMAN> PARAMETERS SET MAXPROCESSCNT 10
%SMI-E-OUTRANGE, parameter is out of range
SYSMAN> PARAMETERS DISABLE CHECKS
SYSMAN> PARAMETERS SET MAXPROCESSCNT 10
      

In this example, the initial attempt to set MAXPROCESSCNT below the minimum fails because range checks are enabled. However, once range checks are disabled, the PARAMETERS SET MAXPROCESSCNT command succeeds.

PARAMETERS ENABLE CHECKS

Validates all parameter values to ensure that they fall within the defined minimum and maximum values.

Because range checks are enabled by default, use PARAMETERS ENABLE CHECKS after entering a PARAMETERS DISABLE CHECKS command.


Format

PARAMETERS ENABLE CHECKS


Parameters

None.

Qualifiers

None.

Example


SYSMAN> PARAMETERS DISABLE CHECKS
SYSMAN> PARAMETERS SET WSMAX 20
SYSMAN> PARAMETERS ENABLE CHECKS
SYSMAN> PARAMETERS SET WSMAX 30
%SMI-E-OUTRANGE, parameter is out of range
SYSMAN> PARAMETERS SHOW WSMAX
Parameter Name    Current  Default  Minimum  Maximum Unit  Dynamic
WSMAX                2000     1024       60   6400 pages

      

The PARAMETERS ENABLE CHECKS command in this example shows that when range checking is disabled, the system accepts a working set value (WSMAX) of 20. However, once range checking is enabled with the PARAMETERS ENABLE CHECKS command, the system does not accept a WSMAX below the minimum, which is 60.

PARAMETERS SET

Changes the value of a specific parameter in the work area.

The PARAMETERS SET command does not modify parameter files, the current system parameter file on disk, or the active system. For information about performing these modifications, see the PARAMETERS WRITE command.


Format

PARAMETERS SET parameter-name [value]


/STARTUP filespec


Parameters

parameter-name

Specifies the name of the parameter to modify. Instead of a name, you can enter a period (.) to change the value of the most recently displayed or the most recently modified parameter. See the PARAMETERS SHOW command for an example of using the period in place of a parameter name.

For a list of system parameters and further information about them, use the command HELP PARAMETERS.

value

Specifies the new value for the parameter. Enclose values for ASCII parameters in quotation marks if they contain embedded spaces or other special characters.

Typically the value is an integer or the keyword DEFAULT. The keyword DEFAULT sets the parameter to its default value. The PARAMETERS SHOW command displays the defined minimum, maximum, and default values for the parameter, which are required unless range checking is disabled with the command PARAMETERS DISABLE CHECKS.


Qualifier

/STARTUP filespec

Sets the name of the site-independent startup procedure to the given file specification. A file specification has a maximum length of 31 characters. The initial startup command procedure is SYS$SYSTEM:STARTUP.COM.

Examples

#1

SYSMAN> PARAMETERS SET PFCDEFAULT 20
      

This command assigns a value of 20 to the PFCDEFAULT parameter.

#2

SYSMAN> PARAMETERS SET GBLSECTIONS DEFAULT
      

This command assigns the default value (40) to the GBLSECTIONS parameter.

#3

SYSMAN> PARAMETERS SET/STARTUP SYS$SYSTEM:XSTARTUP.COM
      

This command assigns SYS$SYSTEM:XSTARTUP.COM as the current site-independent startup command procedure.

PARAMETERS SHOW

Displays the value of a parameter or a group of parameters in the work area. In addition, the command shows the minimum, maximum, and default values of a parameter and its unit of measure.

Format

PARAMETERS SHOW [parameter-name]


Parameter

parameter-name

Specifies the name of a parameter or a period (.). A period is interpreted as a request for the parameter specified in the last PARAMETERS SET or PARAMETERS SHOW command. The parameter name can be abbreviated, but the abbreviation must be unique because SYSMAN selects the first parameter that matches.

Qualifiers

/ACP

Displays all Files--11 ACP parameters.

/ALL

Displays the values of all active parameters.

/CLUSTER

Displays all parameters specific to clusters.

/DYNAMIC

Displays all parameters that would be in effect immediately after you enter a PARAMETERS WRITE ACTIVE command.

/GEN

Displays all general parameters.

/HEX

Displays numeric parameters in hexadecimal rather than decimal radix. Specify the /HEX system parameter name or the parameter type. If you specify the /HEX qualifier with the /NAMES qualifier, /HEX is ignored.

/JOB

Displays all job controller parameters.

/LGI

Displays all LOGIN security control parameters.

/MAJOR

Displays the most important parameters.

/MULTIPROCESSING

Displays parameters specific to multiprocessing.

/NAMES

Displays only parameter names. You can combine other qualifiers with this one.

/OUTPUT

Directs output to the specified file rather than SYS$OUTPUT. Without a file specification, the output goes to SYSMAN.LIS in the current directory.

/PAUSE

Controls the rate at which the system displays information about parameters.

/PQL

Displays the parameters for all default process quotas.

/RMS

Displays all parameters specific to OpenVMS Record Management Services (RMS).

/SCS

Displays all parameters specific to OpenVMS Cluster System Communications Services.

/SPECIAL

Displays all special control parameters.

/STARTUP

Displays the name of the site-independent startup procedure.

/SYS

Displays all active system parameters.

/TTY

Displays all parameters for terminal drivers.

Description

SYSMAN displays parameters in decimal unless you specify the /HEX qualifier. ASCII values are always displayed in ASCII.

Abbreviations for parameter names must be unique because SYSMAN displays the first parameter matching the abbreviation. Ambiguity checks do not occur. For example, a specification of PARAMETERS SHOW GBL displays the GBLSECTIONS parameter. To display the GBLPAGFIL parameter, you must specify PARAMETERS SHOW GBLPAGF to avoid displaying the GBLPAGES parameter.

You can use a period (.) to indicate that you want to work with the system parameter that you specified in the last PARAMETERS SET or PARAMETERS SHOW command.


Examples

#1

SYSMAN> PARAMETERS SHOW GBLSECTIONS
Parameter Name    Current   Default   Minimum     Maximum Unit  Dynamic
GBLSECTIONS           100        40        20     -1  Sections

SYSMAN> PARAMETERS SET . 110
SYSMAN> PARAMETERS SHOW .
Parameter Name    Current   Default   Minimum     Maximum Unit  Dynamic
GBLSECTIONS           110        40        20     -1  Sections
      

In this example, the user first displays the values of the GBLSECTIONS parameter and then refers to the parameter with a period to set its current value to 110. The next PARAMETERS SHOW command also uses the period notation to obtain confirmation that the change occurred.

#2

SYSMAN> PARAMETERS SHOW/ACP
      

This command produces output similar to the following example:



Parameters in use: Active
Parameter Name        Current   Default   Minimum   Maximum Unit  Dynamic
ACP_MULTIPLE                0         1         0         1 Boolean     D
ACP_SHARE                   1         1         0         1 Boolean
ACP_MAPCACHE               52         8         1        -1 Pages       D
ACP_HDRCACHE              138       128         2        -1 Pages       D
ACP_DIRCACHE              138        80         2        -1 Pages       D
ACP_DINDXCACHE             37        25         2        -1 Pages       D
ACP_WORKSET                 0         0         0        -1 Pages       D
ACP_FIDCACHE               64        64         0        -1 File-Ids    D
ACP_EXTCACHE               64        64         0        -1 Extents     D
ACP_EXTLIMIT              300       300         0      1000 Percent/10  D
ACP_QUOCACHE              130        64         0        -1 Users       D
ACP_SYSACC                  4         8         0        -1 Directories D
ACP_MAXREAD                32        32         1        64 Blocks      D
ACP_WINDOW                  7         7         1        -1 Pointers    D
ACP_WRITEBACK               1         1         0         1 Boolean     D
ACP_DATACHECK               2         2         0         3 Bit-mask    D
ACP_BASEPRIO                8         8         4        31 Priority    D
ACP_SWAPFLGS               14        15         0        15 Bit-mask    D
ACP_XQP_RES                 1         1         0         1 Boolean
ACP_REBLDSYS                0         1         0         1 Boolean


#3

SYSMAN> PARAMETERS SHOW/ACP/HEX
      

This command produces a hexadecimal display of the values of the ACP system parameters.



Parameters in use: Active
Parameter Name        Current   Default   Minimum   Maximum Unit  Dynamic
ACP_MULTIPLE         00000000  00000001  00000000  00000001 Boolean     D
ACP_SHARE            00000001  00000001  00000000  00000001 Boolean
ACP_MAPCACHE         00000034  00000008  00000001  FFFFFFFF Pages       D
ACP_HDRCACHE         0000008A  00000080  00000002  FFFFFFFF Pages       D
ACP_DIRCACHE         0000008A  00000050  00000002  FFFFFFFF Pages       D
ACP_DNDXCACHE        00000025  00000019  00000002  FFFFFFFF Pages       D
ACP_WORKSET          00000000  00000000  00000000  FFFFFFFF Pages       D
ACP_FIDCACHE         00000040  00000040  00000000  FFFFFFFF File-Ids    D
ACP_EXTCACHE         00000040  00000040  00000000  FFFFFFFF Extents     D
ACP_EXTLIMIT         0000012C  0000012C  00000000  000003E8 Percent/10  D
ACP_QUOCACHE         00000082  00000040  00000000  FFFFFFFF Users       D
ACP_SYSACC           00000004  00000008  00000000  FFFFFFFF Directories D
ACP_MAXREAD          00000020  00000020  00000001  00000040 Blocks      D
ACP_WINDOW           00000007  00000007  00000001  FFFFFFFF Pointers    D
ACP_WRITEBACK        00000001  00000001  00000000  00000001 Boolean     D
ACP_DATACHECK        00000002  00000002  00000000  00000003 Bit-mask    D
ACP_BASEPRIO         00000008  00000008  00000004  0000001F Priority    D
ACP_SWAPFLGS         0000000E  0000000F  00000000  0000000F Bit-mask    D
ACP_XQP_RES          00000001  00000001  00000000  00000001 Boolean
ACP_REBLDSYS         00000000  00000001  00000000  00000001 Boolean


#4

SYSMAN> PARAMETERS SHOW/STARTUP
Startup command file = SYS$SYSTEM:STARTUP.COM
      

This command displays the name of the site-independent startup command procedure.


SYSMAN> PARAMETERS SHOW/PAUSE MAXPROCESSCNT


Node EXPERT:   Parameters in use: ACTIVE

Parameter Name         Current    Default    Minimum    Maximum Unit  Dynamic
--------------         -------    -------    -------    ------- ----  -------
MAXPROCESSCNT              160         32         12       8192 Processes


Press return to continue [Return]


Node MODERN:   Parameters in use: ACTIVE

Parameter Name         Current    Default    Minimum    Maximum Unit  Dynamic
--------------         -------    -------    -------    ------- ----  -------
MAXPROCESSCNT              157         32         12       8192 Processes


Press return to continue [Return]



Node IMPOSE:   Parameters in use: ACTIVE

Parameter Name         Current    Default    Minimum    Maximum Unit  Dynamic
--------------         -------    -------    -------    ------- ----  -------
MAXPROCESSCNT               50         32         12       8192 Processes


Press return to continue [Return]

.
.
.

The command in this example allows you to control the rate at which the information is displayed.

PARAMETERS USE

Reads a set of system parameters into the work area for display or modification.

Format

PARAMETERS USE source


Parameter

source

The source of a system parameter file for data to be read into the work area. The source can be any of the following items:
ACTIVE Read parameters from memory. When you invoke SYSMAN, active values are in effect.
CURRENT Read parameters from the default system parameter file, which is the source for parameters when you boot the system. Using the current parameters requires read (R) access to the system parameters file.
  • On Alpha systems, the file that contains current parameters is SYS$SYSTEM:ALPHAVMSSYS.PAR.
  • On VAX systems, the file that contains current parameters is SYS$SYSTEM:VAXVMSSYS.PAR.
filespec Read parameters from a previously created system parameter file. The default file type is .PAR. You need read access to the file.
DEFAULT Read a parameter set containing the default values for all parameters. These values are supplied with the operating system.

Qualifiers

None.

Description

Depending on the source you enter with the command, PARAMETERS USE activates the parameter values:
  • Stored in memory (ACTIVE)
  • Stored in the default boot parameter file (CURRENT)
  • From another file (filespec)
  • From the system default values (DEFAULT)

Example


SYSMAN> PARAMETERS USE DEFAULT
SYSMAN> SET STARTUP_P1 "MIN"

      

The first command activates the default parameter values that are supplied with the operating system. The second command sets the STARTUP_P1 system parameter to "minimum." This avoids starting all layered products on a system that is not tuned for them, which might cause the system to hang.

PARAMETERS WRITE

Writes the contents of the work area to memory, to disk, or to a file, depending on the destination that you specify.

Format

PARAMETERS WRITE destination


Parameter

destination

The destination of a new parameter file can be any of the following ones:
ACTIVE Write parameters to memory. Using the ACTIVE parameter requires CMKRNL privilege.
CURRENT Write parameters to the system parameters file, which contains the current parameters on disk. Using the current parameter requires write (W) access to the system parameters file.
  • On Alpha systems, the file that contains current parameters is SYS$SYSTEM:ALPHAVMSSYS.PAR.
  • On VAX systems, the file that contains current parameters is SYS$SYSTEM:VAXVMSSYS.PAR.
filespec Write parameters to a file. The default file type is .PAR and you need write access to the file.

Qualifiers

None.

Description

The PARAMETERS WRITE command writes the system parameter values and the name of the site-independent startup command procedure from the work area to the active system in memory, the current system parameter file on disk, or your choice of a parameter file. You can write only dynamic parameter values to the active system.

Both the PARAMETERS WRITE ACTIVE and PARAMETERS WRITE CURRENT commands send a message to OPCOM to record the event.


Examples

#1

SYSMAN> PARAMETERS WRITE SYS$SYSTEM:SPECIAL
      

This command creates a new parameter specification file.

#2

SYSMAN> PARAMETERS WRITE CURRENT
      

This command modifies the current system parameter file on disk (SYS$SYSTEM:ALPHAVMSSYS.PAR).

RESERVED_MEMORY ADD (Alpha Only)

On Alpha systems, adds an entry to the Reserved Memory Registry data file. Changes and additions to the Reserved Memory Registry data file do not take effect until the next reboot of the system.

Use the RESERVED_MEMORY ADD command to reserve an amount of physical memory that might be needed at a future time. Use the /ALLOCATE qualifier to set aside one or more blocks of physical memory during the boot process. Using the /ALLOCATE qualifier allows memory to be sufficiently contiguous and aligned to be used with granularity hints.

AUTOGEN processes the Reserved Memory Registry data file in its GETDATA phase. AUTOGEN takes the size of all entries into account when calculating system parameters that depend on the available amount of physical memory.

AUTOGEN uses the reservation size of all entries to calculate the initial size of the global page table unless the entry was specified as /NOGLOBAL_SECTION.

For more information about the Reserved Memory Registry, refer to the HP OpenVMS System Manager's Manual and the OpenVMS Programming Concepts Manual.


Format

RESERVED_MEMORY ADD name


Parameter

name

Name of the memory reservation. You must specify a name.

If the reservation is for a memory resident global section, the name of the reservation must be the same as the global section name.


Qualifiers

/ALLOCATE

/NOALLOCATE (default)

Allocates pages during the next reboot of the system. The physical alignment of the pages is based on the maximum granularity hint factor that can be used to map the pages without exceeding the size of the memory reservation. (See the introduction to this section for more information about the /ALLOCATE qualifier.)

Possible granularity hint factors are 512 pages (or 4 MB) and 64 pages (or 512 KB). Therefore, assuming an 8 KB system page size, reserved memory is physically aligned as follows:

  • size >= 4 MB: physically aligned on a 4 MB boundary
  • size < 4 MB: physically aligned on a 512 KB boundary

If you specify /NOALLOCATE, or do not specify /ALLOCATE, memory is reserved only by reducing the system's fluid page count, but no specific pages are set aside.

/GLOBAL_SECTION (default)

/NOGLOBAL_SECTION

/NOGLOBAL_SECTION indicates that the memory qualifier is for a privileged application instead of a group or system global section. (/GLOBAL_SECTION indicates that the memory qualifier is for a group or system global section.) You cannot use /NOGLOBAL_SECTION with the qualifiers /GROUP, /SYSGBL, or /PAGE_TABLES.

/GROUP=n

Establishes that the reserved memory is for a group global section. The value n specifies the UIC group number (in octal) of the process that creates the group global section. Only processes within the creator's UIC group number are allowed access to the global section. For example, if a process with the UIC of [6,100] is the creator of the group global section, the group number for the /GROUP qualifier is 6.

You cannot use the /GROUP qualifier with either /SYSGBL or /NOGLOBAL_SECTION qualifiers.

/PAGE_TABLES (default)

/NOPAGE_TABLES

Reserves additional memory for shared page tables. When the memory-resident global section is created, shared page tables are created for the global section. If you do not specify /ALLOCATE (or if you specify /NOALLOCATE), the additional reserved memory is deducted only from the system's fluid page count. If you specify /ALLOCATE, additional pages are allocated for the shared page table during the next reboot of the system, and the additional reserved memory is deducted from the system's fluid page count.

If you do not specify /PAGE_TABLES, or if you specify /NOPAGE_TABLES, additional memory is not reserved for shared page tables. When the memory-resident global section is created, shared page tables are not created for the global section.

/RAD=n

Specifies the preferred resource affinity domain (RAD) for the reservation you want to make. The value of n is the number of the RAD you specify. If you omit this qualifier, or if this RAD does not have sufficient memory, any other RAD can satisfy the reservation request, and the first available memory section will be used.

The /ALLOCATE qualifier is enforced implicitly when you specify a RAD.

Refer to Section 22.4 for an example procedure that shows how to use SYSMAN RAD qualifiers and options.

/SIZE=size of reserved memory, in MBs

Specifies the number of megabytes to be deducted from the system's fluid page count for this memory-resident global section when the VMS$RESERVED_MEMORY.DATA data file is read during system initialization.

/SYSGBL

Indicates that a reservation is for a system global memory-resident section.

You cannot combine this qualifier with the /GROUP or /NOGLOBAL_SECTION qualifier. This qualifier is the default unless you specify /GROUP or /NOGLOBAL_SECTION.

/ZERO

/NOZERO (default)

/ZERO implies /ALLOCATE. If you specify /ZERO, preallocated pages are zeroed during system initialization. Zeroed pages are required for memory-resident global sections; however, the pages do not need to be zeroed during system initialization.

/NOALLOCATE implies /NOZERO because /ZERO is incompatible with /NOALLOCATE. If you do not specify /ZERO, or if you specify /NOZERO, preallocated pages are not zeroed during system initialization. Instead, these pages are zeroed when the global section is created.


Description

The OpenVMS operating system allows you to reserve non-fluid memory for use within a memory-resident global demand-zero section. The reserved memory can be simply a deduction from the system's fluid memory size, or it can be preallocated as physical pages.

Using the Reserved Memory Registry ensures that AUTOGEN tunes the system properly not to include memory-resident section pages in its calculation of the system's fluid page count. AUTOGEN sizes the system page file, the number of process, and the working set maximum size based on the system's fluid page count. A system can experience severe performance problems if AUTOGEN adjusts parameters based on a fluid page count that does not account for the physical memory that is permanently reserved for some other purpose.

Using the Reserved Memory Registry also ensures that memory is available for memory-resident sections when the allocate option is used.

Users of reserved, non-fluid memory enter the characteristics of the memory into a data file that is read during the system initialization (boot-time). The file is called SYS$SYSTEM:VMS$RESERVED_MEMORY.DATA, and you use the SYSMAN utility to maintain it.

Note

Do not edit the SYS$SYSTEM:VMS$RESERVED_MEMORY.DATA data file.

VMS$RESERVED_MEMORY.DATA is read during system initialization. For each entry in this data file, the number of megabytes is deducted from the system's fluid page count for this memory-resident global section as specified by the /SIZE qualifier on the RESERVED_MEMORY ADD command. If /PAGE_TABLES was specified, the amount of memory required for the shared page tables mapping the memory-resident global section is deducted from the system's fluid page count as well.

The following table summarizes the effects of qualifiers on the RESERVED_MEMORY ADD command:

Qualifier Effect
/ALLOCATE A block of physical pages is also allocated and set aside for the memory-resident global section.
/PAGE_TABLES An additional block of physical pages is allocated and set aside for the shared page tables. The pages have a physical alignment appropriate to use the largest granularity hint factor for the block.
/ZERO The pages are zeroed during system initialization or when the system is idle.
/NOZERO The pages are zeroed when the memory-resident global section is created.

If you set the system parameter STARTUP_P1 to "MIN", entries in the Reserved Memory Registry are ignored, and memory is not reserved.

During system initialization while processing the Reserved Memory Registry data file, if the system encounters errors reserving fluid pages or allocating physical pages, it issues a warning to the console, and the system continues to boot; the request, however, is not granted.


Example


SYSMAN> RESERVED_MEMORY ADD DFW$GS_1 /NOPAGE /GROUP=100 /SIZE=1
SYSMAN> RESERVED_MEMORY ADD DFW$GS_2 /PAGE /SIZE=2 /ALLOC /ZERO
SYSMAN> RESERVED_MEMORY ADD DFW$GS_3 /PAGE /SIZE=3
      

The commands in this example add entries to the Reserved Memory Registry data file. (The example for the RESERVED_MEMORY SHOW command displays the values for these entries.)

RESERVED_MEMORY EXTEND (Alpha Only)

On Alpha systems, adds sections of memory if you want to specify more than one resource affinity domain (RAD) for a single reservation.

EXTEND does not allow you to specify any of the /ALLOCATE, /ZERO, or /PAGE_TABLES flags. The existing reservation determines the state of these flags. The /ALLOCATE flag is set implicitly with EXTEND, whether or not it was set for the initial reservation.

To add a memory section without specifying a RAD, use the /NORAD qualifier.

Refer to Section 22.4 for an example procedure that shows how to use SYSMAN RAD qualifiers and options.


Format

RESERVED_MEMORY EXTEND name


Parameter

name

Name of the memory reservation. You must specify a name.

If the reservation is for a memory resident global section, the name of the reservation must be the same as the global section name.


Qualifiers

/RAD=n

/NORAD

Specifies an additional memory section if you want to specify more than one RAD for a single reservation.

Use /NORAD to add a memory section without specifying a RAD.

/SIZE=size of reserved memory, in MBs

Specifies the number of megabytes to be deducted from the system's fluid page count for this memory-resident global section when the VMS$RESERVED_MEMORY.DATA data file is read during system initialization.

RESERVED_MEMORY FREE (Alpha Only)

On a running Alpha system, frees reserved memory. This command does not affect the contents of the Reserved Memory Registry data file; it affects only the running system.

Format

RESERVED_MEMORY FREE name


Parameter

name

Name of the memory reservation. You must specify a name.

Qualifiers

/GLOBAL_SECTION (default)

/NOGLOBAL_SECTION

/NOGLOBAL_SECTION indicates that the memory qualifier is for a privileged application instead of a group or system global section. (/GLOBAL_SECTION indicates that the memory qualifier is for a group or system global section.) You cannot use /NOGLOBAL_SECTION with the qualifiers /GROUP, /SYSGBL, or /PAGE_TABLES.

/GROUP=n

You must specify /GROUP if the memory-resident global section is a group global section. Do not specify /GROUP if the memory-resident global section is a system global section. The value n is the UIC group number (in octal) associated with the memory-resident being freed.

You cannot use the /GROUP qualifier with either /SYSGBL or /NOGLOBAL_SECTION qualifiers.

/SYSGBL

Indicates that a reservation is for a system global, memory-resident section.

You cannot combine this qualifier with the /GROUP or /NOGLOBAL_SECTION qualifier. This qualifier is the default unless you specify /GROUP or /NOGLOBAL_SECTION.


Description

If physical pages were not preallocated during system initialization for this global section, the reserved memory is simply added to the system's fluid page count. Otherwise, the pages are deallocated to the system's free or zeroed page list.

If page tables are also reserved for the named memory-resident global section, the reserved memory for the shared page tables is also freed. If part of the named reservation is still used, the amount of reserved memory not currently in use is freed. The system displays an informational message that indicates if the named global section is using some portion of the reserved memory.


Example


SYSMAN> RESERVED_MEMORY FREE DFW$GS_2
%SMI-S-RMRFREPAG, pages successfully freed from reservation
SYSMAN> RESERVED_MEMORY SHOW
%SYSMAN-I-OUTPUT, command execution on node PIPERI
Name                     Pages  In Use Group    PTs  Alloced Zeroed
DFW$GS_3                  384        0 SYSGBL    No  No      No
DFW$GS_1                  128        0 00000100  No  No      No
DFW$GS_3                    1        0 SYSGBL   Yes  No      No
      

In this example, the first command frees reserved memory in DFW$GS_2. The second command displays reserved memory in the running system for DFW$GS_3 and DFW$GS_1, but not for DFW$GS_2, which has no reserved memory.

RESERVED_MEMORY LIST (Alpha Only)

On Alpha systems, provides a preview of this reservation as it is currently stored in the Reserved Memory Registry data file. If no reservation is specified, all current reservations are displayed.

Use this qualifier to ensure that a reservation will be made as intended.

Refer to Section 22.4 for an example procedure that shows how to use SYSMAN resource affinity domain RAD qualifiers and options.


Format

RESERVED_MEMORY LIST name


Parameter

name

Name of the reservation you want to verify in the Reserved Memory Registry data file.

Qualifiers

/GLOBAL_SECTION (default)

/NOGLOBAL_SECTION

/NOGLOBAL_SECTION indicates that the memory qualifier is for a privileged application instead of a group or system global section. (/GLOBAL_SECTION indicates that the memory qualifier is for a group or system global section.) You cannot use /NOGLOBAL_SECTION with the qualifiers /GROUP, /SYSGBL, or /PAGE_TABLES.

/GROUP=n

You must specify /GROUP if the memory-resident global section is a group global section. Do not specify /GROUP if the memory-resident global section is a system global section. The value n is the UIC group number (in octal) associated with the memory-resident being freed.

You cannot use the /GROUP qualifier with either /SYSGBL or /NOGLOBAL_SECTION qualifiers.

/SYSGBL

Indicates that a reservation is for a system global, memory-resident section.

You cannot combine this qualifier with the /GROUP or /NOGLOBAL_SECTION qualifier. This qualifier is the default unless you specify /GROUP or /NOGLOBAL_SECTION.

RESERVED_MEMORY MODIFY (Alpha Only)

On Alpha systems, allows you to modify an existing entry in the Reserved Memory Registry data file.

Refer to Section 22.4 for an example procedure that shows how to use SYSMAN RAD qualifiers and options.


Format

RESERVED_MEMORY MODIFY name


Parameter

name

Name associated with the entry being removed. You must specify a name.

Qualifiers

/ALLOCATE

/NOALLOCATE (default)

Allocates pages during the next reboot of the system as specified on the command line. (The default is taken from the existing Reserved Memory Registry entry.) The physical alignment of the pages is based on the maximum granularity hint factor that can be used to map the pages depending on the size of the reserved memory.

Possible granularity hint factors are 512 pages (or 4 MB) and 64 pages (or 512 KB). Therefore, assuming an 8-KB system page size, reserved memory is physically aligned as follows:

  • size >= 4 MB: physically aligned on a 4-MB boundary
  • size < 4 MB: physically aligned on a 512-KB boundary

If you specify /NOALLOCATE, or if you do not specify /ALLOCATE, memory is reserved only by reducing the system's fluid page count, but no specific pages are set aside.

/GLOBAL_SECTION (default)

/NOGLOBAL_SECTION

/NOGLOBAL_SECTION indicates that the memory qualifier is for a privileged application instead of a group or system global section. (/GLOBAL_SECTION indicates that the memory qualifier is for a group or system global section.) You cannot use /NOGLOBAL_SECTION with the qualifiers /GROUP, /SYSGBL, or /PAGE_TABLES.

/GROUP=n

Establishes that the reserved memory is for a group global section. The value n specifies the UIC group number (in octal) of the process that creates the group global section. Only processes within the creator's UIC group number are allowed access to the global section. For example, if a process with the UIC of [6,100] is the creator of the group global section, the group number for the /GROUP qualifier is 6.

You cannot use the /GROUP qualifier with either /SYSGBL or /NOGLOBAL_SECTION qualifiers.

/NEW_RAD=nn

/NONEW_RAD

Use NEW_RAD to change the RAD assignment for an entry. Do this by first specifying /RAD=n to identify the entry you want to change and then specify /NEW_RAD=nn to identify the new RAD. Use only /NEW_RAD=nn (without the /RAD qualifier) if the old entry did not have a RAD assigned.

/PAGE_TABLES (default)

/NOPAGE_TABLES

Reserves additional memory for shared page tables system as specified on the command line. (The default is taken from the existing Memory Registry.)

When the memory-resident global section is created, shared page tables are created for the global section. If you do not specify /ALLOCATE, or if you specify /NOALLOCATE, the additional reserved memory is deducted from the system's fluid page count. If you specify /ALLOCATE, additional pages are allocated for the shared page table during the next reboot of the system, and the additional reserved memory is deducted from the system's fluid page count.

If you do not specify /PAGE_TABLES, or if you specify /NOPAGE_TABLES, additional memory is not reserved for shared page tables. When the memory-resident global section is created, shared page tables are not created for the global section.

You cannot specify /PAGE_TABLES if the reservation has the attribute /NOGLOBAL_SECTION.

/RAD=n

/NORAD

MODIFY/RAD=n affects only the entry for the specified resource affinity domain (RAD). The value of n is the RAD you specify.

Usage Rules

  • Do not use MODIFY/RAD=n to change the size of a reservation for an entry without a specified number or to change the state of the /ZERO or /PAGE_TABLES flags. (Flags are always consistent for all entries in a given reservation.)
  • To change the RAD assignment for an entry, specify /RAD=n to identify the entry you want to change and /NEW_RAD=nn to identify the new RAD. Use only /NEW_RAD=nn (without the /RAD qualifier) if the old entry did not have a RAD assigned.
  • Use MODIFY name /NORAD if you no longer want to tie memory for this reservation to any specific RADs. SYSMAN compresses multiple entries into a single entry for an unspecified RAD with the total memory size as the sum of all RAD entries for this reservation.

/SIZE=size of reserved memory, in MBs

Specifies the number of megabytes to be deducted from the system's fluid page count for this memory-resident global section when the VMS$RESERVED_MEMORY.DATA data file is read during system initialization. The default value for /SIZE is taken from the existing Reserved Memory Registry.

/SYSGBL

Indicates that a reservation is for a system global memory resident section.

You cannot combine this qualifier with the /GROUP or /NOGLOBAL_SECTION qualifier. This qualifier is the default unless you specify /GROUP or /NOGLOBAL_SECTION.

/ZERO

/NOZERO (default)

/ZERO implies /ALLOCATE. If you specify /ZERO, preallocated pages are zeroed during system initialization. Zeroed pages are required for memory-resident global sections; however, the pages do not need to be zeroed during system initialization. The default value is taken from existing Reserved Memory Registry entry.

/NOALLOCATE implies /NOZERO because /ZERO is incompatible with /NOALLOCATE. If you do not specify /ZERO, or if you specify /NOZERO, preallocated pages are not zeroed during system initialization. Instead, these pages are zeroed when the global section is created.


Description

The Reserved Memory Registry entry to be modified is identified by the combination of the following items:
name
/[NO]GLOBAL_SECTION
/GROUP=n
/SYSGBL

The values of these qualifiers are the same as for the RESERVED_MEMORY ADD command.


Example


SYSMAN>  RESERVED_MEMORY MODIFY
X234567890123456789012345678901/SIZ=2/ZERO
$ TYPE SYS$SYSTEM:VMS$RESERVED_MEMORY.DATA
! VMS$RESERVED_MEMORY.DATA
! Do NOT edit this file
! Modify with SYSMAN RESERVED_MEMORY commands
! A = /ALLOCATE, Z = /ZERO, P = /PAGE_TABLES, VERSION = 1
! SIZE (MB) RESERVATION NAME                            GROUP  A Z P
1          X23456789012345678901234567890               1      0 0 1
2          X234567890123456789012345678901              SYSGBL 1 1 1
1          X2345678901234567890123456789012             NOGBL  0 0 0
SYSMAN> EXIT
$
      

The command in this example modifies an entry to reserve 2 MB of memory and to allocate and zero this memory at boot time.

RESERVED_MEMORY REMOVE (Alpha Only)

On Alpha systems, removes a reserved memory entry from the Reserved Memory Registry data file. This command takes effect on the next reboot and does not affect the running systems.

Format

RESERVED_MEMORY REMOVE name


Parameter

name

Name associated with the entry being removed. You must specify a name.

If page tables are reserved for the named memory-resident global section, the additional reserved memory is also removed.


Qualifiers

/GLOBAL_SECTION (default)

/NOGLOBAL_SECTION

/NOGLOBAL_SECTION indicates that the memory qualifier is for a privileged application instead of a group or system global section. (/GLOBAL_SECTION indicates that the memory qualifier is for a group or system global section.) You cannot use /NOGLOBAL_SECTION with the qualifiers /GROUP, /SYSGBL, or /PAGE_TABLES.

/GROUP=n

You must specify /GROUP if the memory-resident global section is a group global section. Do not specify /GROUP if the memory-resident global section is a system global section. The value n is the UIC group number (in octal) associated with the memory-resident section being removed. You cannot use the /GROUP qualifier with either /SYSGBL or /NOGLOBAL_SECTION parameters.

/SYSGBL

Indicates that a reservation is for a system global memory resident section.

You cannot combine this qualifier with the /GROUP or /NOGLOBAL_SECTION qualifier. This qualifier is the default unless you specify /GROUP or /NOGLOBAL_SECTION.


Example


SYSMAN> RESERVED_MEMORY ADD DFW$GS1/SIZE=1
SYSMAN> RESERVED_MEMORY REMOVE DFW$GS1
      

The first command in this example adds DFW$GS1; the second command removes it.

RESERVED_MEMORY SHOW (Alpha Only)

On Alpha systems, displays the memory reservations on the running system.

The display includes how much of the reserved memory is currently in use by the named global section. It also includes how much memory is reserved and currently in use for page tables, if any, and the blocks of physical pages reserved.


Format

RESERVED_MEMORY SHOW name


Parameter

name

Name associated with the entry being displayed within the running system. If you do not specify a name, the system displays the reserved memory for all registered global sections.

Qualifiers

/GLOBAL_SECTION (default)

/NOGLOBAL_SECTION

/NOGLOBAL_SECTION indicates that the memory qualifier is for a privileged application instead of a group or system global section. (/GLOBAL_SECTION indicates that the memory qualifier is for a group or system global section.) You cannot use /NOGLOBAL_SECTION with the qualifiers /GROUP, /SYSGBL, or /PAGE_TABLES.

/GROUP=n

You must specify /GROUP if the memory-resident global section is a group global section. Do not specify /GROUP if the memory-resident global section is a system global section. The value n is the UIC group number (in octal) associated with the memory-resident section being displayed. You can use the /GROUP qualifier only if you specify name. You cannot use the /GROUP qualifier with either /SYSGBL or /NOGLOBAL_SECTION parameters.

/SYSGBL

Indicates that a reservation is for a system global memory resident section.

You cannot combine this qualifier with the /GROUP or /NOGLOBAL_SECTION qualifier. This qualifier is the default unless you specify /GROUP or /NOGLOBAL_SECTION.


Example


SYSMAN> RESERVED_MEMORY SHOW
%SYSMAN-I-OUTPUT, command execution on node PIPER
Name                     Pages  In Use Group    PTs  Alloced Zeroed
DFW$GS_3                  384        0 SYSGBL    No  No      No
DFW$GS_2                  256        0 SYSGBL    No Yes     Yes
DFW$GS_1                  128        0 00000100  No  No      No
DFW$GS_3                    1        0 SYSGBL   Yes  No      No
DFW$GS_2                    1        0 SYSGBL   Yes Yes      No

      

The command in this example displays the memory reservations on a running system.

SET ENVIRONMENT

Defines the nodes or cluster to which subsequent commands apply.

Requires OPER or SETPRV privilege on all nodes in the target environment.


Format

SET ENVIRONMENT


Parameters

None.

Qualifiers

/CLUSTER

Specifies that all subsequent commands apply to all nodes in the cluster. By default, the management environment is the local cluster. Specify a nonlocal cluster by naming one cluster member with the /NODE qualifier.

/NODE=(node1,node2,...)

Specifies that SYSMAN execute subsequent commands on the given DECnet nodes. If accompanied by the /CLUSTER qualifier, the environment becomes the cluster where the given DECnet node is a member. A node name can be a system name, cluster alias, or logical name. However, before you can use logical names to define the command environment, you must set up the logical name table SYSMAN$NODE_TABLE. For more information about defining the SYSMAN logical name table, refer to the HP OpenVMS System Manager's Manual.

/USERNAME=username

Specifies that this user name should be used for access control purposes on another node. You can use this qualifier only in conjunction with the /CLUSTER or /NODE qualifiers. SYSMAN uses the current user name if none is supplied. SYSMAN prompts for a password whenever you specify a new user name.

Note

The account specified must have only a primary password. Accounts with secondary passwords are not supported.

Description

The SET ENVIRONMENT command defines the target nodes or cluster for subsequent commands. When invoked, the system management environment is the local node where you are running SYSMAN. You can change the environment to any other nodes in the cluster, the entire cluster, or any nodes or cluster available through DECnet.

Designate an OpenVMS Cluster environment with the /CLUSTER qualifier. When specifying a nonlocal cluster, also include the /NODE qualifier to identify the cluster.

If your environment consists of VAX and Alpha nodes, see the DO command for information about creating logicals to manage each platform as an environment.

You can display the current environment with the command SHOW ENVIRONMENT. To adjust privileges and defaults for the current environment, use the SET PROFILE command.

An environment exists until you exit from SYSMAN or establish another command context with the SET ENVIRONMENT command.


Examples

#1

SYSMAN> SET ENVIRONMENT/CLUSTER
%SYSMAN-I-ENV, Current command environment:
        Clusterwide on local cluster
        Username ALEXIS    will be used on nonlocal nodes

      

This command defines the command environment as the local cluster. SYSMAN confirms the new environment.

#2

SYSMAN> SET ENVIRONMENT/NODE=NODE21/CLUSTER
Remote Password:

%SYSMAN-I-ENV, Current command environment:
        Clusterwide on remote node NODE21
        Username ALEXIS    will be used on nonlocal nodes

      

This command establishes a management environment on the cluster where NODE21 is a member. SYSMAN prompts for a password because it is a nonlocal environment.

#3

SYSMAN> SET ENVIRONMENT/NODE=(NODE21,NODE22,NODE23)
%SYSMAN-I-ENV, Current command environment:
        Individual nodes: NODE21,NODE22,NODE23
        Username ALEXIS   will be used on nonlocal nodes

      

This command defines the management environment to be three individual nodes.

#4

$ CREATE/NAME_TABLE/PARENT=LNM$SYSTEM_DIRECTORY -
_$ SYSMAN$NODE_TABLE
$ DEFINE LAVCS SYS1,SYS2,SYS3,SYS4/TABLE=SYSMAN$NODE_TABLE
$ RUN SYS$SYSTEM:SYSMAN
SYSMAN> SET ENVIRONMENT/NODE=(LAVCS)
%SYSMAN-I-ENV, Current command environment:
        Individual nodes: SYS1,SYS2,SYS3,SYS4
        Username ALEXIS   will be used on nonlocal nodes

      

The commands in this example set up the logical name table SYSMAN$NODE_TABLE, define a logical name (LAVCS), and use the logical name to define the command environment.

SET PROFILE

Temporarily modifies a user's current privileges and default device and directory.

Format

SET PROFILE


Parameters

None.

Qualifiers

/DEFAULT=device:[directory]

Specifies the default disk device and directory name that the system should use in this environment to locate and catalog files.

/PRIVILEGES=(priv1,priv2...)

Specifies the privileges to add to the current privileges. Any enhanced privileges must be authorized.

/VERIFY

/NOVERIFY (default)

Specifies whether you want DCL verification (both procedure and image) for future DO commands.

Description

The SET PROFILE command modifies process attributes for the current management environment. After considering the privilege requirements of commands that you intend to use in an environment, you can add or delete current privileges, if they are authorized. You can also set a new default device and directory, as well as use the SET PROFILE/[NO]VERIFY command to control DCL command verification in SYSMAN. Other attributes of your process remain constant. The profile is in effect until you change it, reset the environment, or exit from SYSMAN. The HP OpenVMS System Manager's Manual discusses profile changes in more detail.

Examples

#1

SYSMAN> SET PROFILE/DEFAULT=WORK1:[ALEXIS]
      

This command changes the default device and directory in the user account to directory ALEXIS on device WORK1.

#2

SYSMAN> SET PROFILE/PRIVILEGES=(SYSPRV,CMKRNL)/VERIFY
      

This command makes the authorized privileges, SYSPRV and CMKRNL, part of the current privileges, and turns on DCL verification. The privileges remain in effect until the environment changes, you enter another SET PROFILE command, or you exit.

SET TIMEOUT

Establishes the amount of time SYSMAN waits for a node to respond. Once the time limit expires, SYSMAN proceeds to execute the command on the next node in the environment.

Format

SET TIMEOUT time


Parameter

time

Specifies a delta time value, which has the following format:

hh:mm:ss[.cc.]

This is the amount of time that SYSMAN waits for a node to respond. SYSMAN waits indefinitely---by default it has no timeout period. Refer to the OpenVMS User's Manual for a description of delta time values.


Qualifiers

None.

Example


SYSMAN> SET TIMEOUT 00:00:30
%SYSMAN-I-TIMEVAL, timeout value is 00:00:30
SYSMAN> CONFIGURATION SHOW TIME
System time on node NODE21: 19-JUN-2002  14:22:33
%SYSMAN-I-NODERR, error returned from node NODE22
%SMI-E-TIMEOUT, remote operation has timed out
System time on node NODE23: 19-JUN-2002  14:23:15
      

This command establishes a timeout period of 30 seconds. Because NODE22 did not respond within 30 seconds, SYSMAN displays an error message and proceeds to execute the command on the next node in the environment.

SHOW ENVIRONMENT

Displays the target nodes or cluster where SYSMAN is executing commands.

Format

SHOW ENVIRONMENT


Parameters

None.

Qualifiers

None.

Description

The SHOW ENVIRONMENT command displays the current management environment. It can be the local cluster, local or remote nodes, or a nonlocal cluster. SYSMAN indicates if the environment is limited to individual nodes or if it is clusterwide. It also shows the current user name.

The environment exists until you exit from SYSMAN or enter another SET ENVIRONMENT command.


Examples

#1

SYSMAN> SHOW ENVIRONMENT
%SYSMAN-I-ENV, Current command environment:
        Clusterwide on local cluster
        Username ALEXIS   will be used on nonlocal nodes
      

This command shows the current environment is the local cluster. User name ALEXIS will be used on other nodes in the cluster.

#2

SYSMAN> SHOW ENVIRONMENT
%SYSMAN-I-ENV, Current command environment:
        Clusterwide on remote cluster NODE21
        Username ALEXIS   will be used on nonlocal nodes
      

This command shows that the command environment is a nonlocal cluster where NODE21 is a member.

#3

SYSMAN> SHOW ENVIRONMENT
%SYSMAN-I-ENV, Current command environment:
        Individual nodes: NODE22,NODE23
        At least one node is not in local cluster
        Username ALEXIS   will be used on nonlocal nodes
      

This command shows that the command environment consists of two nodes.

SHOW KEY

Displays key definitions created with the DEFINE/KEY command.

Format

SHOW KEY [key-name]


Parameter

key-name

Specifies the name of the key whose definition you want displayed. See the DEFINE/KEY command for a list of valid key names.

Qualifiers

/ALL

Displays all the key definitions in the specified state or states. Specifying a key name is not necessary.

/BRIEF

Displays only the key definition. By default, the system displays all the qualifiers associated with the key definition, including any specified state, unless you use the /BRIEF qualifier.

/DIRECTORY

Displays the names of all the states for which you have defined keys. If you have not defined keys, the SHOW KEY/DIRECTORY command displays the DEFAULT and GOLD states (which is the default SYSMAN keypad).

/STATE=(state, state...)

Specifies the name of a state for which the specified key definitions are to be displayed. If you select more than one state name, separate them with commas and enclose the list in parentheses.

Description

Specifies the name of the key whose definition you want displayed. See the DEFINE/KEY command for a list of valid key names.

Example


SYSMAN> SHOW KEY/ALL
DEFAULT keypad definitions:
  KP0 = "SHOW ENVIRONMENT" (echo)
  KP1 = "SHOW PROFILE" (echo)
SYSMAN>
      

This command displays all the key definitions currently in effect.

SHOW PROFILE

Displays the privileges and the default device and directory being used in the current environment.

Format

SHOW PROFILE


Parameters

None.

Qualifiers

/DEFAULT

Displays the default disk device and directory name that the system uses in this environment to locate and catalog files.

/PRIVILEGES

Displays only the privileges in effect for the current environment.

Description

The SHOW PROFILE command displays the privileges and the default device and directory that is being used in the current environment. You can modify these attributes with the SET PROFILE command.

These values remain in effect until you change environments or enter another SET PROFILE command.


Example


SYSMAN> SHOW PROFILE
%SYSMAN-I-DEFDIR, Default directory on node NODE21  -- WORK1:[BERGERON]
%SYSMAN-I-DEFPRIV, Process privileges on node NODE21 --
        TMPMGX
        OPER
        NETMBX
        SYSPRV
      

This command shows the default device and directory as well as current privileges.

SHOW TIMEOUT

Displays the amount of time SYSMAN waits for a node to respond. By default, there is no timeout period.

Format

SHOW TIMEOUT


Parameters

None.

Qualifiers

None.

Example


SYSMAN> SHOW TIMEOUT
%SYSMAN-I-TIMEVAL, timeout value is 00:00:04.00
      

This command displays the current timeout value, which is 4 seconds.

SHUTDOWN NODE

Shuts down one or more nodes in an OpenVMS Cluster.

The SHUTDOWN NODE command invokes SYS$SYSTEM:SHUTDOWN to shut down one node or multiple nodes, as you specify, in the current management environment. You can enter the shutdown command in one command line, instead of executing the SHUTDOWN.COM procedure on each node individually.

Requires SETPRV privilege or all of the following privileges: CMKRNL, EXQUOTA, LOG_IO, OPER, SYSNAM, SYSPRV, TMPMBX, WORLD.


Format

SHUTDOWN NODE


Parameters

None.

Qualifiers

/AUTOMATIC_REBOOT

/NOAUTOMATIC_REBOOT (default)

Reboots the system automatically when the shutdown is complete.

/CLUSTER_SHUTDOWN

/NOCLUSTER_SHUTDOWN (default)

Shuts down the entire cluster.

When you use the /CLUSTER_SHUTDOWN qualifier, each node suspends activity just short of shutting down completely, until all other nodes in the cluster have reached the same point in the shutdown procedure.

You must specify this option on every cluster node. If any one node is not shut down completely, the clusterwide shutdown cannot occur.

You should use the SET ENVIRONMENT/CLUSTER command before you issue a SHUTDOWN NODE/CLUSTER_SHUTDOWN command to ensure that all nodes in the cluster are shutting down.

/DISABLE_AUTOSTART

Specifies the number of minutes before shutdown when autostart queues running on the node are marked stop pending and are subject to failover to another node.

Using this qualifier gives you control over when the autostart failover process begins. By default, the value equals that of the /MINUTES_TO_SHUTDOWN qualifier.

Determine the appropriate number of minutes for your configuration by weighing a smoother transition against completing a maximum number of jobs before shutdown. The larger the value, the smoother the transition will be. The smaller the value, the more jobs will execute on the node.

/INVOKE_SYSHUTDOWN (default)

/NOINVOKE_SYSHUTDOWN

Invokes a site-specific shutdown procedure.

/MINUTES_TO_SHUTDOWN=number

The number of minutes until shutdown occurs. If the system logical name SHUTDOWN$MINIMUM_MINUTES is defined, its integer value is the minimum value that you can enter. Therefore, if the logical name is defined as 10, you must specify at least 10 minutes to final shutdown or an error message displays. If the logical name is not defined, and you do not enter a value, 0 minutes is the default.

/POWER_OFF

Specifies that the system is to power off after shutdown is complete.

/REASON=text

The reason for the shutdown (one line).

/REBOOT_CHECK

/NOREBOOT_CHECK (default)

Checks for basic operating system files and notifies you if any are missing. Be sure to replace missing files before rebooting.

/REBOOT_TIME=time

The time when you expect to reboot the system such as IMMEDIATELY, IN 10 MINUTES, 2 P.M., or 14:00:00. Shutdown displays this time in a shutdown message to users.

/REMOVE_NODE

/NOREMOVE_NODE (default)

Removes a node from the active cluster quorum. Use this qualifier when you do not expect the shut-down node to rejoin the cluster for an extended period.

When you use the /REMOVE_NODE qualifier, active quorum in the remainder of the cluster is adjusted downward to reflect the fact that the removed node's votes no longer contribute to the quorum value. The shutdown procedure readjusts the quorum by issuing the SET CLUSTER/EXPECTED_VOTES command.

You can reset options by using the following command:


SYSMAN> STARTUP SET OPTIONS/NOVERIFY/NOCHECKPOINTING

For more information about cluster management, refer to OpenVMS Cluster Systems.

/SAVE_FEEDBACK

/NOSAVE_FEEDBACK (default)

Records feedback data collected from the system since it was last booted and creates a new version of the AUTOGEN feedback data file, which you can use the next time you run AUTOGEN.

/SPIN_DOWN_DISKS

/NOSPIN_DOWN_DISKS (default)

Spins down disks. You cannot spin down the system disk.

Description

Because SYSMAN enables you to define the target environment, you can perform a shutdown on your local node, your own cluster, or a subset of nodes on your cluster. If you are shutting down a local node, SYSMAN does not require you to remain logged in to the system during the shutdown, as long as you set the environment to the local node. See the SHUTDOWN NODE command examples and the SET ENVIRONMENT command for more information.

In shutting down the system, the shutdown procedure:

  1. At decreasing time intervals, broadcasts a message to users to log out.
  2. Defines the system logical SHUTDOWN$TIME to reflect the value entered with the /MINUTES_TO_SHUTDOWN qualifier. For example, if you entered /MINUTES_TO_SHUTDOWN=10 at 12:00, the shutdown time would be 12:10.
    To see if a shutdown is in progress or determine the actual time for shutdown, use the command SHOW LOGICAL SHUTDOWN$TIME.
  3. At six minutes or less before shutdown, disables all nonoperator logins. If DECnet is running, it is shut down.
  4. At one minute before shutdown, stops batch and device queues and the system job queue manager.
  5. At zero minutes before shutdown, invokes the site-specific command procedure SYS$MANAGER:SHUTDWN.COM.
  6. Stops all user processes; however, system processes continue. Ancillary control processes (ACPs) may delete themselves when their mounted volumes are finally dismounted.
  7. Stops the secondary processor on dual-processor systems.
  8. Removes all installed images.
  9. Dismounts volumes and spins down disks, if you requested it. Does not spin down the system disk and the quorum disk, if a quorum disk is present.
  10. Closes the operator's log file.
  11. Invokes SYS$SYSTEM:OPCRASH to shut down the system.
  12. Displays the following message if you did not request an automatic reboot:


    SYSTEM SHUTDOWN COMPLETE - USE CONSOLE TO HALT SYSTEM
    

    If you requested an automatic reboot, the system reboots, provided the necessary controls are set.

Examples

#1

SYSMAN> SET ENVIRONMENT/CLUSTER
SYSMAN> SHUTDOWN NODE/MINUTES_TO_SHUTDOWN=15/REBOOT_TIME="later"-
_SYSMAN>  /REASON="SOFTWARE UPGRADE"/REBOOT_CHECK/CLUSTER_SHUTDOWN
      

The first command in this example ensures that all nodes in the cluster will shut down. The second command requests a shutdown for the entire cluster and a reboot check for any missing operating system files. The following messages are displayed to users on the cluster:


SHUTDOWN message on NODE21, from user SYSTEM at NODE21$0PA0: 12:00:00:20
NODE21 will shut down in 15 minutes; back up later. Please log off NODE21.
SOFTWARE UPGRADE

SHUTDOWN message on NODE22, from user SYSTEM at NODE22$0PA0: 12:00:00:22
NODE22 will shut down in 15 minutes; back up later. Please log off NODE22.
SOFTWARE UPGRADE

SHUTDOWN message on NODE23, from user SYSTEM at NODE23$0PA0: 12:00:00:24
NODE23 will shut down in 15 minutes; back up later. Please log off NODE23.
SOFTWARE UPGRADE
#2

SYSMAN> SET ENVIRONMENT/NODE=0
Password:
SYSMAN> SHUTDOWN NODE/MINUTES=120
%SYSMAN-I-SHUTDOWN, SHUTDOWN request sent to node
SYSMAN> EXIT
$ LOGOUT
      

This example shuts down the local node in 2 hours. As long as you set the environment to the local node, a subprocess of the SMISERVER system detached process runs shutdown, and remaining logged into the system during the shutdown is not necessary. If you do not set the environment to the local node, the shutdown runs via a subprocess of the current process, requiring that you remain logged in during the shutdown cycle.

SPAWN

Creates a subprocess of the current process. The context of the subprocess is copied from the current process. You can use the SPAWN command to leave SYSMAN temporarily, perform other tasks (such as displaying a directory listing or printing a file), and return to SYSMAN.

Note that SPAWN performs actions on the local node only. If you want to execute DCL commands or command procedures throughout your environment, use the DO command.

Requires TMPMBX or PRMMBX user privilege. The SPAWN command does not manage terminal characteristics. You cannot use the SPAWN and ATTACH commands if your terminal has an associated mailbox.


Format

SPAWN [command-string]


Parameter

command-string

Specifies a command string of fewer than 132 characters that you want executed in the context of the created subprocess. When the command completes execution, the subprocess terminates and control returns to the parent process. If you specify both a command string and the /INPUT qualifier, the command string executes before additional commands are obtained from the /INPUT qualifier.

Qualifiers

/INPUT=filespec

Specifies an input file containing one or more DCL command strings that you want executed by the spawned subprocess. If you specify a command string along with an input file, the command string gets processed before the commands in the input file. When processing is complete, the subprocess terminates.

/LOGICAL_NAMES (default)

/NOLOGICAL_NAMES

Specifies that the logical names of the parent process are copied to the subprocess. When you do not want the subprocess to use the logical names of the parent process, enter the /NOLOGICAL_NAMES qualifier.

/OUTPUT=filespec

Identifies the output file to which the results of the operation are written. Specify an output other than SYS$OUTPUT whenever you use the /NOWAIT qualifier. This prevents output from being displayed while you are specifying new commands. If you omit the /OUTPUT qualifier, output gets written to the current SYS$OUTPUT device.

/PROCESS=subprocess-name

Specifies the name of the subprocess that you want to create. The default subprocess name is in the format USERNAME_n.

/SYMBOLS (default)

/NOSYMBOLS

Determines whether the system passes DCL global and local symbols to the subprocess.

/WAIT (default)

/NOWAIT

Controls whether the system waits until the subprocess completes before you can specify more commands. The /NOWAIT qualifier enables you to specify new commands while the specified subprocess is running. If you specify the /NOWAIT qualifier, use the /OUTPUT qualifier to direct the output to a file instead of displaying it on the screen. Doing this prevents your terminal from being used by more than one process simultaneously.

Description

The SPAWN command creates a subprocess of your current process with the following attributes copied from the parent process:
  • All symbols except $RESTART, $SEVERITY, and $STATUS
  • Key definitions
  • The current keypad state
  • The current prompt string
  • All process logical names and logical name tables except those explicitly marked CONFINE or those created in executive or kernel mode
  • Default disk and directory
  • Current SET MESSAGE settings
  • Current process privileges
  • Control and verification states

Note that some attributes, such as the process's current command tables, are not copied.

When the subprocess is created, the process-permanent open files and any image or procedure context are not copied from the parent process. The subprocess is set to command level 0 (DCL level with the current prompt).

If you do not specify the /PROCESS qualifier, the name of this subprocess is composed of the same base name as the parent process and a unique number. For example, if the parent process name is SMITH, the subprocess name can be SMITH_1, SMITH_2, and so on.

The LOGIN.COM file of the parent process is not executed for the subprocess because the context is copied separately, allowing quicker initialization of the subprocess. When the /WAIT qualifier is in effect, the parent process remains in hibernation until the subprocess terminates or returns control to the parent by way of the ATTACH command.

More than one process simultaneously attempts to use the same input or output stream when several processes share that stream and you perform one of the following actions:

  • Terminate a subprocess to which you are not currently attached.
  • Terminate a process that is not spawned from the process to which you are currently attached.

Use the LOGOUT command to terminate the subprocess and return to the parent process. You can also use the ATTACH command (see ATTACH) to transfer control of the terminal to another process in the subprocess tree, including the parent process. (The SHOW PROCESS/SUBPROCESSES command displays the processes in the subprocess tree and points to the current process.)

Note

Because a tree of subprocesses can be established using the SPAWN command, you must be careful when terminating any process in the tree. When a process is terminated, all subprocesses below that point in the tree are automatically terminated.

Qualifiers used with the SPAWN command must directly follow the command verb. The command string parameter begins after the last qualifier and continues to the end of the command line.


Examples

#1

SYSMAN> SPAWN DIR SYS$MANAGER:SITE*.*

Directory CLU$COMMON:[SYSMGR]

SITE$STARTUP.COM;5

Total of 1 file.

SYSMAN>

      

This command enables you to enter the DIRECTORY command in DCL to see if a site-specific startup file is in the directory. After the DIRECTORY command executes, control returns to the parent process.

#2

SYSMAN> SPAWN
$ EDIT SITE$STARTUP.COM
   .
   .
   .
$ LOGOUT
Process SYSTEM_1 logged out at 28-JUN-2002 10:05:17.24
SYSMAN>

      

This example shows how you can use the SPAWN command to leave SYSMAN and edit a file. The LOGOUT command returns you to SYSMAN.

#3

SYSMAN> SPAWN /NOLOGICAL_NAMES SET HOST
_Node: NODE21
   .
   .
   .
$ LOGOUT
%REM-S-END, control returned to node _NODE22::

SPAWN>

This example shows how you can use the SPAWN command to create a subprocess in which you can use the SET HOST command. When you want to leave NODE21, enter the LOGOUT command. The /NOLOGICAL_NAMES qualifier prevents the logical names of the parent process from being copied to the subprocess.

STARTUP ADD

Adds a component to the startup database.

Requires read (R) and write (W) access to the startup database.


Format

STARTUP ADD FILE filespec


Parameters

FILE

Adds a component to the startup database. SYSMAN modifies STARTUP$STARTUP_LAYERED by default.

filespec

Specifies which file to add to the startup database. Each component of the startup database must have a file type of .COM or .EXE and reside in SYS$STARTUP.

Qualifiers

/CONFIRM

/NOCONFIRM (default)

Controls whether SYSMAN displays the file specification of each file before adding it to the startup database and requests you to confirm the addition. If you specify /CONFIRM, you must respond to the prompt with a Y (Yes) or a T (True) and press Return before the file is added. If you enter anything else, such as N or No, the requested file is not added.

/LOG

/NOLOG (default)

Controls whether the STARTUP ADD command displays the file specification of each file after it has been added.

/MODE=mode

Specifies the mode of execution for the file. Valid modes include DIRECT, SPAWN, BATCH, or ANY, as described in the HP OpenVMS System Manager's Manual.

/NODE=(node1,node2,...,noden)

Names the nodes within the cluster that run the file during startup. By default, a startup file executes on all nodes in the cluster.

/PARAMETER=(P1:arg1,P2:arg2,...,P8:arg8)

Specifies the parameters that are to be passed to the file during startup. Parameters that are omitted receive the default parameters defined by the system parameter STARTUP_Pn. If STARTUP_Pn is blank, "FULL" is used as parameter 1 (P1) and is passed by STARTUP.COM to each startup component file. If you want a blank P1 parameter given to a specific component file, use the command:


SYSMAN> STARTUP MODIFY FILE component.com/PARAM=P1:""

/PHASE=phase-name

Indicates the phase within system startup when the file is to be executed. Valid phases include LPBEGIN, LPMAIN, LPBETA, and END. LPMAIN is the default.

Description

The STARTUP ADD command adds a component to the startup database. Startup components are the command procedures or executable files that perform actual startup work. Files from the startup database are used to start the operating system, site-specific programs, and layered products. STARTUP$STARTUP_VMS and STARTUP$STARTUP_LAYERED list the components of the startup database.

Because an OpenVMS Cluster typically shares one copy of the startup database, the SYSMAN environment can be defined as clustered or as a single node within the cluster.


Example


SYSMAN> STARTUP ADD FILE /MODE=DIRECT /PHASE=LPMAIN -
_SYSMAN> DECSET$ENVMGR_STARTUP.COM
      

This command adds a record to the startup database that starts the DECSET environment manager software.

STARTUP DISABLE

Prevents a file in the startup database from executing.

Requires read (R) and write (W) access to the startup database.


Format

STARTUP DISABLE FILE filespec


Parameters

FILE

Disables a component of the startup database. SYSMAN modifies STARTUP$STARTUP_LAYERED by default.

filespec

Specifies the name of a component in the startup database. The startup file must reside in SYS$STARTUP and have a file type of .COM or .EXE. The asterisk (*) and percent (%) wildcard characters are permitted.

Qualifiers

/CONFIRM

/NOCONFIRM (default)

Controls whether the STARTUP DISABLE command displays the file specification of each file before disabling it in the startup database and requests you to confirm that the file be disabled. If you specify /CONFIRM, you must respond to the prompt with a Y (Yes) or a T (True) and press Return before the file is disabled. If you enter anything else, such as N or No, the requested file is not disabled.

/LOG

/NOLOG (default)

Controls whether the STARTUP DISABLE command displays the file specification of each file after it has been disabled.

/NODE=(node1,node2,...,noden)

Identifies nodes within the cluster that do not run the file during startup. By default, the startup file is disabled on all nodes in the cluster.

/PHASE=phase-name

Indicates the phase of system startup in which the specified file normally executes. Valid phases include LPBEGIN, LPMAIN, LPBETA, and END. LPMAIN is the default.

Description

The STARTUP DISABLE command prevents a file in the startup database from executing. The command edits a record in the startup database, temporarily disabling the file.

Example


SYSMAN> STARTUP DISABLE FILE /NODE=NODE21 DECSET$ENVMGR_STARTUP.COM
      

This command modifies the startup database so that the DECset environment manager will not be installed on NODE21.

STARTUP ENABLE

Enables a previously disabled file in the startup database to execute during system startup.

Requires read (R) and write (W) access to the startup database.


Format

STARTUP ENABLE FILE filespec


Parameters

FILE

Enables a component of the startup database. SYSMAN modifies STARTUP$STARTUP_LAYERED by default.

filespec

Specifies the name of the startup file that you are enabling. Wildcard characters are accepted.

Qualifiers

/CONFIRM

/NOCONFIRM (default)

Controls whether the STARTUP ENABLE command displays the file specification of each file before enabling it in the startup database and requests you to confirm that the file be enabled. If you specify /CONFIRM, you must respond to the prompt with a Y (Yes) or a T (True) and press Return before the file is enabled. If you enter anything else, such as N or No, the requested file is not enabled.

/LOG

/NOLOG (default)

Controls whether the STARTUP ENABLE command displays the file specification of each file after it has been enabled.

/NODE=(node1,node2,...,noden)

Names nodes within the cluster where the file will be enabled. By default, the startup file is enabled on all nodes.

/PHASE=phase-name

Indicates the phase within system startup when the specified file is to be enabled. Valid phases include LPBEGIN, LPMAIN, LPBETA, and END. LPMAIN is the default.

Description

The STARTUP ENABLE command permits a file that was previously disabled to execute during system startup.

Example


SYSMAN> STARTUP ENABLE FILE /NODE=NODE22 DECSET$ENVMGR_STARTUP.COM
      

This command modifies the startup database. NODE22 will have the DECSET environment manager installed at startup.

STARTUP MODIFY

Changes information associated with a startup file in the startup database.

Requires read (R) and write (W) access to the startup database.


Format

STARTUP MODIFY FILE filespec


Parameters

FILE

Modifies a record in the startup database. SYSMAN modifies STARTUP$STARTUP_LAYERED by default.

filespec

Selects a startup file for modification. Wildcard characters are accepted.

Qualifiers

/CONFIRM

/NOCONFIRM (default)

Controls whether the STARTUP MODIFY command displays the file specification of each file before modifying its startup characteristics in the startup data file and requests you to confirm that the file characteristics be modified. If you specify /CONFIRM, you must respond to the prompt with a Y (Yes) or a T (True) and press Return before the file is modified. If you enter anything else, such as N or No, the requested file is not modified.

/LOG

NOLOG (default)

Controls whether the STARTUP MODIFY command displays the file specification of each file after its startup characteristics have been modified.

/MODE=mode

Changes the mode of execution for a startup file. Valid modes include DIRECT, SPAWN, BATCH, or ANY, as described in the HP OpenVMS System Manager's Manual.

/NAME=filespec

Changes the name of the startup file. The file must reside in SYS$STARTUP.

/PARAMETER=(P1:arg1,P2:arg2,...,P8:arg8)

Changes the parameters that are to be passed to the file during startup. Parameters that are omitted receive the default parameters defined by the system parameter STARTUP_Pn. If STARTUP_Pn is blank, "FULL" is used as parameter 1 (P1) and is passed by STARTUP.COM to each startup component file. If you want a blank P1 parameter given to a specific component file, use the command:


SYSMAN> STARTUP MODIFY FILE component.com/PARAM=P1:""

/PHASE=phase-name

Selects startup files for modification based on the phase in which they run. Valid phases include LPBEGIN, LPMAIN, LPBETA, and END. LPMAIN is the default.

Description

The STARTUP MODIFY command edits startup information associated with components in the startup database. For example, the command can rename a file or change the parameters that are passed to a file during startup. You can select a group of files for modification based on the phase in which they run.

Example


SYSMAN> STARTUP MODIFY FILE DECSET$ENVMGR_STARTUP.COM -
_SYSMAN> /PARAM=(P3:TRUE,P4:FALSE) /CONFIRM
      

This command changes two startup parameters for the command procedure DECSET$ENVMGR_STARTUP.COM.

STARTUP REMOVE

Removes a record in the startup database, so the specified startup file no longer executes during system startup.

Requires read (R) and write (W) access to the startup database.


Format

STARTUP REMOVE FILE filespec


Parameters

FILE

Removes a component from the startup database. SYSMAN modifies STARTUP$STARTUP_LAYERED by default.

filespec

Specifies the name of the file to remove from the startup database. Wildcard characters are accepted.

Qualifiers

/CONFIRM

/NOCONFIRM (default)

Controls whether the STARTUP REMOVE command displays the file specification of each file before deleting its record in the startup database and requests you to confirm that the file be deleted. If you specify /CONFIRM, you must respond to the prompt with a Y (Yes) or a T (True) and press Return before the file is removed. If you enter anything else, such as N or No, the requested file is not removed.

/LOG

/NOLOG (default)

Controls whether SYSMAN displays the file specification of each file after it has been removed.

/PHASE=phase-name

Indicates the phase of system startup from which the file will be removed. Valid phases include LPBEGIN, LPMAIN, LPBETA, and END.

Example


SYSMAN> STARTUP REMOVE FILE DECSET$ENVMGR_STARTUP.COM /LOG
      

This command takes the file DECSET$ENVMGR_STARTUP.COM out of the startup database.

STARTUP SET DATABASE

Establishes the current startup database.

Format

STARTUP SET DATABASE database


Parameter

database

Specifies the name of the target database, which is STARTUP$STARTUP_LAYERED by default. The second database, STARTUP$STARTUP_VMS, is available for viewing; however, HP recommends that you do not modify it.

Qualifiers

None.

Example


SYSMAN> STARTUP SET DATABASE STARTUP$STARTUP_LAYERED
%SYSMAN-I-NEWCOMPFIL, current component file is now STARTUP$STARTUP_LAYERED
SYSMAN> STARTUP SHOW FILE
%SYSMAN-I-COMPFIL, contents of component database on node LUCERN
Phase    Mode    File
-----    ----    ---------------------------
LPBEGIN  DIRECT  VMS$LPBEGIN_070_STARTUP.COM
LPMAIN   DIRECT  FOR$LPMAIN_070_STARTUP.COM

      

The commands in this example establish the layered products database as the default, so it can be displayed.

STARTUP SET OPTIONS

Controls logging and display of information for one or more nodes in a cluster during startup.

Requires READ (R) and WRITE (W) access to the current system parameter file on disk: SYS$SYSTEM:VAXVMSSYS.PAR (for VAX systems) or SYS$SYSTEM:ALPHAVMSSYS.PAR (for Alpha systems).


Format

STARTUP SET OPTIONS


Parameters

None.

Qualifiers

/CHECKPOINTING

/NOCHECKPOINTING

Displays informational messages describing the time and status of each startup phase and component procedure.

The value of the system parameter STARTUP_P2 that corresponds to /OUTPUT=CHECKPOINTING is "C".

/OUTPUT=FILE,CONSOLE

Sends output generated by using the /VERIFY qualifier to a file or to the system console. If you choose the FILE option, it creates SYS$SPECIFIC:[SYSEXE]STARTUP.LOG.

The value of the system parameter STARTUP_P2 that corresponds to /OUTPUT=FILE is "D".

/VERIFY=FULL,PARTIAL

/NOVERIFY

Displays startup procedures as they execute. This qualifier defines the system parameter STARTUP_P2 to have the appropriate value based on the options you choose. (/VERIFY with no value following it is the equivalent of /VERIFY=full.)

/VERIFY options are in the following table:

Value Description
FULL Displays every line of DCL executed by startup component procedures and by STARTUP.COM.

The value of the system parameter STARTUP_P2 that corresponds to this option is "V".

PARTIAL Displays every line of DCL executed by startup component procedures, but does not display DCL executed by STARTUP.COM.

The value of the system parameter STARTUP_P2 that corresponds to this option is "P".

Caution

All STARTUP_P2 parameter values modified by the SYSMAN STARTUP OPTIONS will be overridden by the AUTOGEN command procedure. To preserve any parameter modifications made with SYSMAN, edit the SYS$SYSTEM:MODPARAMS.DAT file, as explained in the HP OpenVMS System Manager's Manual.

Description

The STARTUP SET OPTIONS command enables you to control logging and checkpointing during startup. You can control the amount of information logged (full or partial) and where it is displayed (file or console). You can also choose checkpointing, which displays informational messages about the time and status of each phase during startup.

The default options are /NOCHECKPOINTING, /OUTPUT=CONSOLE, and /NOVERIFY.

Because SYSMAN enables you to define the target environment, you can perform startup logging on your local node, your own cluster, and a subset of nodes on your cluster. See the SET ENVIRONMENT command for more information.


Example


SYSMAN> STARTUP SET OPTIONS/VERIFY=FULL/OUTPUT=FILE/CHECKPOINTING
      

This example requests startup logging with full verification, output to SYS$SPECIFIC:[SYSEXE]STARTUP.LOG, and checkpointing. The corresponding value for system parameter STARTUP_P2 is "VDC".

STARTUP SHOW

Displays the name of the current startup database or its components as well as the startup logging options selected with the STARTUP SET OPTIONS command.

Format

STARTUP SHOW DATABASE


FILE
OPTIONS


Parameters

DATABASE

Displays the name of the current startup database. The two startup databases are STARTUP$STARTUP_LAYERED and STARTUP$STARTUP_VMS. HP recommends that you do not modify the STARTUP$STARTUP_VMS database.

FILE

Displays the contents of the current startup database. The display includes the file name, phase, and mode of execution for each component in the database.

OPTIONS

Displays the options selected when using the STARTUP SET OPTIONS command.

Qualifiers

/FULL

Displays full information about each component in the database. In addition to the phase, file name, and mode of execution for each startup component, SYSMAN displays the nodes on which the file executes and the parameters passed to the file. This qualifier is relevant with the FILE parameter.

/NODE

Displays the nodes within the cluster on which the file executes. By default, a startup file executes on all nodes in an environment. This qualifier is relevant with the FILE parameter.

/OUTPUT=filespec

Redirects command output from SYS$OUTPUT to the file named with the qualifier. Without a filespec, SYSMAN writes the output to SYSMAN.LIS in the current directory.

/PARAMETERS

Lists the parameters with which the startup file executes. Parameters that are not specified receive the defaults defined by the system parameter STARTUP_Pn. If STARTUP_Pn is blank, "FULL" is used as parameter 1 (P1) and is passed by STARTUP.COM to each startup component file. If you want a blank P1 parameter given to a specific component file, see the /PARAMETER qualifier under STARTUP MODIFY command for instructions.

/PHASE=phase-name

Displays components that execute in a specific phase of system startup. Valid phases include LPBEGIN, LPMAIN, LPBETA, and END. LPMAIN is the default. This qualifier is relevant with the FILE parameter.

Example


SYSMAN> STARTUP SET DATABASE STARTUP$STARTUP_VMS
SYSMAN> STARTUP SHOW FILE
%SYSMAN-I-COMPFIL, contents of component database on node LUCERN
Phase        Mode    File
-----        ----    --------------------------------
BASEENVIRON  DIRECT  VMS$BASEENVIRON_050_LIB.COM
BASEENVIRON  CALLED  VMS$BASEENVIRON_050_SMISERVER.COM
BASEENVIRON  DIRECT  VMS$BASEENVIRON_050_VMS.COM
.
.
.

      

The commands in this example display the contents of the startup database.

SYS_LOADABLE ADD

Adds an entry in the system images file SYS$UPDATE:VMS$SYSTEM_IMAGES.IDX.

Caution

The SYS_LOADABLE ADD command is not intended for general use. Only advanced system programmers should use this command.

Format

SYS_LOADABLE ADD product image


Parameters

product

A 1- to 8-character product mnemonic that uniquely identifies a loadable image. For user-written images, this should typically contain the string _LOCAL_.

image

The file name of the system loadable image you want to add. A file name is the only value you can specify for this parameter. Do not specify a device, directory, file type, or wildcard characters.

Qualifiers

/LOAD_STEP

Indicates the step of the booting process at which you want the image loaded. Valid load steps are INIT (which causes the system initialization code to load the image), and SYSINIT (which causes the SYSINIT process to load the image).

If you do not specify a value for the /LOAD_STEP qualifier, it defaults to SYSINIT.

/LOG

/NOLOG (default)

Controls whether the SYS_LOADABLE ADD command displays a notification after the entry has been added.

/MESSAGE

Enables you to specify the text of a message that is displayed when the appropriate condition is met (see the /SEVERITY qualifier). The default message is "system image load failed".

/SEVERITY

Determines how the image load status will affect console output and booting progress. You can specify the following values for this qualifier:
Value Description
FATAL If an error occurs loading the image, display the error message and BUGCHECK information.
INFORMATION Display the message and continue processing.
SUCCESS Continue even if loading the image produces an error. Does not display the message.
WARNING If an error occurs loading the image, display the error message and continue processing.

If you do not specify a value for the /SEVERITY qualifier, it defaults to WARNING.


Description

The SYS_LOADABLE ADD command adds an entry to the system images file SYS$UPDATE:VMS$SYSTEM_IMAGES.IDX. You can then process this file using the command procedure SYS$UPDATE:VMS$SYSTEM_IMAGES.COM. Processing the file with VMS$SYSTEM_IMAGES.COM generates a new system images data file that the system uses when it boots.

If the file SYS$UPDATE:VMS$SYSTEM_IMAGES.IDX does not exist, the SYS_LOADABLE ADD command creates a new one.

SYS_LOADABLE REMOVE

Removes an entry in the system images file SYS$UPDATE:VMS$SYSTEM_IMAGES.IDX.

Caution

The SYS_LOADABLE REMOVE command is not intended for general use. Only advanced system programmers should use this command.

Format

SYS_LOADABLE REMOVE product


image


Parameters

product

A 1- to 8-character product mnemonic that uniquely identifies a loadable image. For user-written images this should typically contain the string _LOCAL_.

image

The file name of the system loadable image you want to remove. A file name is the only value you can specify for this parameter. Do not specify a device, directory, file type, or wildcard characters.

Qualifier

/LOG

/NOLOG (default)

Controls whether the SYS_LOADABLE REMOVE command displays a notification after the entry has been removed.

Description

The SYS_LOADABLE REMOVE command removes an entry from the system images file SYS$UPDATE:VMS$SYSTEM_IMAGES.IDX. You can then process this file using the command procedure SYS$UPDATE:VMS$SYSTEM_IMAGES.COM. Processing the file with VMS$SYSTEM_IMAGES.COM generates a new system images data file that the system uses when it boots.

If the file SYS$UPDATE:VMS$SYSTEM_IMAGES.IDX does not exist, the SYS_LOADABLE REMOVE command creates a new, empty one.

22.4 RAD Example

The following example procedure shows how to use SYSMAN resource affinity domain (RAD) qualifiers and options.
  1. Show that no reserved memory registry exists:


    SYSMAN> reserved_memory list
    %SYSMAN-I-NODERR, error returned from node PIPERI
    -RMS-E-FNF, file not found
    
  2. Add a reservation for a group global section and display the new reservation:


    SYSMAN> reserved_memory add ak_sec/gr=4711 /size=16 /zero /page_tables
    SYSMAN> reserved_memory list
    
    %SYSMAN-I-OUTPUT, command execution on node PIPERI
    Reservation Name             Group    RAD  Size (MB)  Pages  Attributes
    AK_SEC                       4711     ANY         16   2048  Allocated Zeroed
    AK_SEC                       4711                         2  PageTables Allocated
    
  3. Modify the reservation to have memory assigned from each of four RADs; display the result:


    SYSMAN> reserved_memory modify ak_sec/gr=4711 /new_rad=0 /size=4
    SYSMAN> reserved_memory extend ak_sec/gr=4711 /rad=1 /size=4
    SYSMAN> reserved_memory extend ak_sec/gr=4711 /rad=2 /size=4
    SYSMAN> reserved_memory extend ak_sec/gr=4711 /rad=3 /size=4
    SYSMAN> reserved_memory list
    
    %SYSMAN-I-OUTPUT, command execution on node PIPERI
    Reservation Name             Group    RAD  Size (MB)      Pages  Attributes
    AK_SEC                       4711       0          4        512  Allocated Zeroed
    AK_SEC                       4711       1          4        512  Allocated Zeroed
    AK_SEC                       4711       2          4        512  Allocated Zeroed
    AK_SEC                       4711       3          4        512  Allocated Zeroed
    AK_SEC                       4711                             2  PageTables Allocated
    
  4. Modify the reservation to no longer zero allocated pages at boot time. Note that you can change properties such as /ZERO, /ALLOCATE, /PAGE_TABLES only for the reservation as a whole, not for a specific RAD.


    SYSMAN> reserved_memory modify ak_sec/gr=4711 /nozero
    SYSMAN> reserved_memory list
    
    %SYSMAN-I-OUTPUT, command execution on node PIPERI
    Reservation Name              Group    RAD  Size (MB)      Pages  Attributes
    AK_SEC                        4711       0          4        512  Allocated
    AK_SEC                        4711       1          4        512  Allocated
    AK_SEC                        4711       2          4        512  Allocated
    AK_SEC                        4711       3          4        512  Allocated
    AK_SEC                        4711                             2  PageTables Allocated
    
  5. Modify the reservation to no longer request memory from specific RADs. Note that the overall size remains unchanged.


    SYSMAN> reserved_memory modify ak_sec/gr=4711 /norad
    SYSMAN> reserved_memory list
    
    %SYSMAN-I-OUTPUT, command execution on node PIPERI
    Reservation Name           Group    RAD  Size (MB)      Pages  Attributes
    AK_SEC                     4711     ANY         16       2048  Allocated
    AK_SEC                     4711                             2  PageTables Allocated
    
    
  6. Starting with a reservation allocated across multiple RADs, request that memory no longer be allocated at boot time. Note that this implies that memory is no longer allocated from specific RADs.
    Reservation prior to change:


    SYSMAN> reserved_memory list
    
    %SYSMAN-I-OUTPUT, command execution on node PIPERI
    Reservation Name   Group    RAD  Size (MB)      Pages  Attributes
    AK_SEC             4711       0         4        512  Allocated
    AK_SEC             4711       1         4        512  Allocated
    AK_SEC             4711       2         4        512  Allocated
    AK_SEC             4711       3         4        512  Allocated
    AK_SEC             4711                            2  PageTables Allocated
    
    

    Command to no longer allocate at boot time:


    SYSMAN> reserved_memory modify ak_sec/gr=4711 /noalloc
    

    New state of reservation:


    SYSMAN> reserved_memory list
    
    %SYSMAN-I-OUTPUT, command execution on node PIPERI
    Reservation Name           Group    RAD  Size (MB)      Pages  Attributes
    AK_SEC                     4711     ANY         16       2048
    AK_SEC                     4711                             2  PageTables
    
  7. To change the size of a reservation with an assigned RAD, or to change the reservation to use a different RAD, you must specify the current RAD.
    Reservation prior to change:


    SYSMAN> reserved_memory list
    
    %SYSMAN-I-OUTPUT, command execution on node PIPERI
    Reservation Name           Group    RAD  Size (MB)      Pages  Attributes
    AK_SEC                     4711       2         16       2048  Allocated
    AK_SEC                     4711                             2  PageTables Allocated
    

    Attempt to change reservation size:


    SYSMAN> reserved_memory mod ak_sec/gr=4711 /size=20
    %SYSMAN-I-NODERR, error returned from node PIPERI
    -SMI-E-RMRNOMATCH, no records matched search criteria
    
        Correct command:
     SYSMAN> reserved_memory mod ak_sec/gr=4711 /rad=2 /size=20
    

    New state of reservation:


    SYSMAN> reserved_memory list
    
    %SYSMAN-I-OUTPUT, command execution on node PIPERI
    Reservation Name           Group    RAD  Size (MB)  Pages  Attributes
    AK_SEC                      4711     2         20    2560  Allocated
    AK_SEC                      4711                        3  PageTables Allocated
    


Chapter 23
USB Configuration Manager (UCM)

23.1 UCM Description

The USB (Universal Serial Bus) Configuration Manager (UCM) utility allows you to connect a computer to a variety of devices using a single four-wire cable. More specifically, UCM does the following:
  • Records events such as plugging or unplugging devices and errors that occur on a USB bus. This is the USB event-logging function of UCM.
  • Maps physical devices to persistent device names (based on either serial number or bus location).
  • Manages additions, deletions, and modifications to devices configured on the system.

23.2 USB and UCM Concepts

The following sections introduce and explain USB and UCM.

23.2.1 Introduction to USB

Universal Serial Bus (USB) is a communications architecture that enables a computer to interconnect a variety of devices using a single four-wire cable. The purpose of USB is to provide a user-friendly way to connect low- and medium-speed devices to host computers.

The USB connects USB devices to the USB host, which, in turn, connects with a host computer system. Each USB has only one host, labeled USB Host in Figure 23-1. (A host, however, can have multiple USBs.)

Figure 23-1 USB Configuration


The USB host is integrated with a root hub, which provides one or more attachment points for devices. The USB physical interconnections from each hub form a star, with a hub at the center of each star.

Point-to-point wire connections link the USB host to a hub or a function, or a hub to another hub or function. Hubs and functions are USB devices that do the following:

  • Hubs provide additional attachment points to the USB.
  • Functions provide capabilities to the system, such as a mouse or a keyboard.

Figure 23-2 shows that up to six hubs can be chained to create a tiered configuration. The path of a device is determined by its location in the structure; for example, the path to the printer LPA0: in Figure 23-2 is 1.1.2.3.1.4. (Note, however, that the numbers printed on the physical hub might not match the numbers that UCM displays.)

Figure 23-2 Hub Tiers


The OpenVMS device names of USB devices are as follows:

Device Name Description
KBD n 1 Keyboard
MOU n 1 Mouse
TXA n 1 Modem
LPA n 1 Printer driver
HID0 Special-case driver that users cannot access
UCM0 Hub driver (one per system)

1The value of n can be between 0 and 9999.

The UCM works with the hub driver to configure USB-supported devices.

23.2.2 UCM Concepts and Operation

The UCM is made up of client and server layers. The user interacts with the client layer, and the client layer interacts with the server layer. It is the server layer that interacts with the USB. Figure 23-3 shows the interaction of these layers.

Figure 23-3 UCM Architecture


As the figure indicates, the UCM server maintains the event-logging file and the generic and permanent list files. These files are passed to the UCM client, which can display the files to the user. (The types of lists that the UCM server uses are explained in Section 23.2.2.1.) The UCM server is in contact with the UCM driver, SYS$HUBDRIVER, which maintains connections with other layers of the architecture.

23.2.2.1 Types of UCM Lists

The UCM server has the following three types of lists:

  • Generic list
    This list contains descriptions of devices that UCM supports. The generic list is part of the file-based device configuration information that is maintained on the system. (Refer to Chapter 8 of the HP OpenVMS System Manager's Manual.)
    The installation process creates this list. A device that has no matching entry in the generic list is an unknown device type and cannot be configured.
  • Tentative list
    This is a list of devices that UCM will configure if you tell it to. The tentative list, which is in memory, disappears when the server is restarted or when the system reboots.
  • Permanent list
    This list contains devices that UCM configures if the device is connected to the bus. The permanent list supplies a persistent name for a USB device; that is, the name is maintained across reboots and server restarts.
    Persistent names work somewhat differently on devices that have or do not have serial numbers:
    • On a device with a serial number, a persistent name always works.
    • On a device without a serial number, a name is persistent only if you attach the device in the same place on the hub each time you attach it.

    A running system has only one permanent list, which UCM reads from SYS$SYSTEM:USB$UCM_DEVICES.DAT. For most customers, this is the minimal file that OpenVMS provides in SYS$COMMON:[SYSEXE].

Caution

Never delete USB$UCM_DEVICES.DAT. Deleting this file might result in the inability to use your USB attached devices.

23.2.2.2 How UCM Configures Devices

At system startup time, the following steps occur:

  1. OpenVMS starts the UCM server, which does the following:
    1. Reads the generic list of supported devices.
    2. Reads the permanent list for descriptions of devices.
  2. UCM initializes an empty tentative list.
  3. UCM turns on the USB bus; a device on the bus announces itself.
  4. UCM checks for device data on the permanent list. If device data is on the permanent list, UCM loads it and makes it available.
    If device data is not on the list, UCM performs the next step.
  5. UCM checks for data on the generic list. If device data is on this list, UCM uses it to make an entry in the tentative list.
    The data stays on the tentative list until the user either adds the device to or deletes the device from the permanent list.

    Notes

    In configuring devices, keep in mind the following:
    • Unplugging a device does not delete a tentative item.
    • Each replugging of a device creates a new tentative item.
    • A device added to the permanent list following UCM startup is not configured (that is, it is not available for use) until the device is subsequently disconnected and reconnected (unplugged and replugged).
    • Any modification to the permanent list creates a new version of the file.
  6. Steps 3 through 5 repeat until all devices on all buses are processed.
  7. UCM waits for a user request or until a device is plugged in or unplugged.

Log Files

UCM uses the following log file to record disconnections, connections, and errors:


SYS$MANAGER:USB$UCM_EVENTS.LOG

You do not need special permission to access the event log. However, you do need OPER privilege to use the UCM command SET LOG/NEW command to create a new log file. ( Section 23.5 contains a table listing UCM commands and the privileges required to issue each command.)

23.3 Using UCM to Manage Devices and View Events

You can use UCM commands to select the devices you want to configure and to view USB events such as connections, disconnections, and errors. The following sections explain how to configure USB devices and how to view USB device information.

23.3.1 Configuring Devices

Before the system can configure a USB device, the device must have a corresponding entry on the permanent list. Although a few entries are included as part of USB installation, these entries provide only minimal support for a mouse and a keyboard. For most devices, you need to take certain steps to add an entry to the permanent list.

When you connect a USB device of a known type that has no entry on the permanent list, UCM uses information in the read-only generic list to create an entry in the tentative list. You must approve the entry before UCM creates an entry in the permanent list.

The following section explains how to create an entry in the permanent list.

Creating an Entry in the Permanent List

To set up a device to be configured, add the device as an entry in the permanent list. Once you do this, UCM recognizes the device each time you connect it.

In the following example, you connect a printer to the USB. The printer is a known device type; in other words, it has an entry in the generic list. However, it does not yet have an entry in the permanent list.

Follow these steps to configure the device:

  1. Physically connect the printer.
  2. Enter the UCM command to enter the UCM environment and to display a message about configured and unconfigured devices on your system:


    $ UCM
    UCM>
    
  3. To display more information about the unconfigured device, enter the following command:


    $ UCM
    Universal Serial Bus Configuration Manager, Version V1.0
    
    UCM> SHOW DEVICE /UNCONFIGURED
    
    DEVICE
    DEVICE_TYPE                     TENTATIVE
    DEVICE_NAME_ROOT                LP
    UNIT_NUMBER                     0
    BUS                             1
    PATH                            1.0.0.0.0.0
    END_DEVICE
    
    UCM>
    

    Note that the display on your screen might be somewhat different from the one you see here.
  4. Next, you must approve the entry by entering the ADD command. For example:


    UCM> ADD DEVICE LPA0:
    
    UCM> EXIT
    

    This command places the device information in the permanent list.
  5. The last step before using the printer is to unplug the printer and reconnect it. This makes the device available for use. (If a device has no serial number, you must either plug it into the same port, or use the MODIFY command to indicate its new location.)
    When you reconnect the printer, its serial number and vendor ID identify it as LPA0:. UCM configures the device and makes it available for use.
    Note that this step is not necessary if the UCM server is restarted or if the system is rebooted.

23.3.2 Viewing Events

The UCM event logger records events such as device connections and disconnections and certain types of errors. To see this information, you use the UCM utility SHOW EVENTS command. You can also use qualifiers to limit the display of various types of events.

Events stored in the event log include the following:

  • A device was configured or deconfigured.
  • A known device was connected but not configured.
  • An unknown device was connected.
  • Text messages were sent by USB drivers.

The following sections explain how to display information about unknown devices and configuration failures.

23.3.2.1 Information About Unknown Devices

The UCM records unknown device connections in its event log. You can view this information by adding the /TYPE=UNKNOWN qualifier to the SHOW EVENT command.

The information in the following example includes the vendor ID, the product ID, and other optional device-supplied information. If an unknown device is connected to the USB, you might want to view only events showing the activity of unknown devices for today; for example:


UCM> SHOW EVENTS /TYPE=UNKNOWN /SINCE=TODAY

Date        Time        Type         Priority Component
--------------------------------------------------------------------------------
22-AUG-2002 13:04:23.26 UNKNOWN      NORMAL   UCM UNKNOWN DEVICE
     Message: VENDOR_ID = 1118.PRODUCT_ID = 8.RELEASE_NUMBER = 256.BUS_NUMBER
     = 1.PATH = 1.0.0.0.0.0.DEVICE_CLASS = 0.DEVICE_SUB_CLASS =
     0.DEVICE_PROTOCOL = 0.NUMBER_OF_INTERFACES = 1.NUMBER_OF_CONFIGURATIONS
     = 1.MANUFACTURER_STRING = Microsoft.PRODUCT_STRING =
     Microsoft SideWinder Precision Pro (USB).CONFIGURATION_NUMBER = 0.

UCM>

Note that the display on your screen might be somewhat different from the one you see here.

23.3.2.2 Information about Configuration Failures

When UCM does not configure a device---because UCM cannot find an entry in the permanent list or because of a driver error---it stores this information in the event log. You can view such information using the SHOW EVENTS command and a qualifier that limits the display. For example:


UCM> SHOW EVENTS /SINCE=YESTERDAY

Date        Time        Type         Priority Component
-------------------------------------------------------------------------
28-AUG-2002 17:43:47.09 DRIVER       NORMAL   HUBDRIVER
        Message: Find a driver for DeviceClass/DeviceSubClass = 0x2/0x0

28-AUG-2002 17:43:47.09 UNKNOWN      NORMAL   UCM UNKNOWN DEVICE
        Message: VENDOR_ID = 4483.PRODUCT_ID = 16392.RELEASE_NUMBER =
        256.BUS_NUMBER = 3.PATH = 1.1.4.4.0.0.DEVICE_CLASS =
        2.DEVICE_SUB_CLASS = 0.DEVICE_PROTOCOL = 0.NUMBER_OF_INTERFACES =
        2.NUMBER_OF_CONFIGURATIONS = 2.MANUFACTURER_STRING
        = HP Computer Corp., Inc..PRODUCT_STRING = HP USB
        Modem.CONFIGURATION_NUMBER = 0.

28-AUG-2002 17:43:47.24 DRIVER       NORMAL   HUBDRIVER
        Message: hub_configure_device Unable to find Interface Driver


28-AUG-2002 17:43:47.24 DRIVER       NORMAL   HUBDRIVER
        Message: Find a driver for InterfaceClass/InterfaceSubClass/
        Protocol = 0xff/0xff/0xff

28-AUG-2002 17:43:49.17 UCM          CRITICAL ucm_config_request
        Message: %SYSTEM-W-DEVEXISTS, device unit already exists

28-AUG-2002 17:43:50.17 DRIVER       NORMAL   HUBDRIVER
        Message: Configured device TXA3 using driver SYS$YCDRIVER:

28-AUG-2002 17:43:56.11 DRIVER       NORMAL   HUBDRIVER         Message: Device on bus 3 at port 1 bus tier 4 can exceed the         bus power available

UCM> exit

Note that the display on your screen might be somewhat different from the one you see here.

The last message in this example, which is in bold type, indicates that there is insufficient power in the hub to supply the device. Therefore, UCM will not configure the device.

If no entry for the device is in the generic list, the log displays what is known about the device. If an error caused the failure, the error code is listed in the log.

23.4 UCM Usage Summary

The Universal Serial Bus (USB) Configuration Manager (UCM) utility allows you to connect a computer to a variety of USB devices using a single four-wire cable.


Format

UCM

To invoke UCM, enter UCM at the DCL command prompt ($):


$ UCM

UCM>

At the UCM> prompt, you can enter any of the UCM commands described briefly in Section 23.5 and in more detail in the following sections.

Alternatively, you can enter UCM commands at the DCL prompt. For example:


$ UCM RELOAD
$

To exit from UCM, enter the EXIT command at the UCM> prompt, or press Ctrl/Z.

23.5 UCM Commands

The following table summarizes the UCM commands.

Command Description Privilege Required
ADD DEVICE Allows you to add a new device to the collection of known USB devices. SYSPRV
DELETE DEVICE Allows you to remove a device from the collection of known devices. SYSPRV
EXIT Exits the UCM utility. None
HELP Provides online help information for using the UCM commands. None
MODIFY DEVICE Modifies the unit number or flags of an entry in the permanent list. The changes take effect immediately. SYSPRV
RELOAD Reads the generic and permanent lists from disk. SYSPRV
RESTART Restarts the configuration server. CMKRNL
SET LOG/NEW Creates a new version of the event log file. OPER
SHOW DEVICE Displays configured and unconfigured devices that are connected to the USB. None
SHOW EVENTS Displays events in the event log file. None

ADD DEVICE

Allows you to add a new device to the collection of known USB devices.

Requires SYSPRV privilege.


Format

ADD DEVICE device-name:


Parameter

device-name:

The name of the device whose characteristics are to be added. The device name has the form ddcu, where:
dd is the device code---for example, LP. (The driver name corresponds to the device code; in this case, the driver name would be SYS$LPDRIVER.)
c is the controller designation A through Z; unless UCM specifies a different letter, all USB devices are A.
u is the unit number (0 through 9999).

OpenVMS device names are made up of the two-character device code, followed by the controller designation, then by the unit number (which can be 1 to 4 characters long), then by a colon (:).


Qualifiers

/BUS_NUMBER=number

Specifies the USB bus number of the device. This parameter is required to identify a particular device on a system that has multiple USB buses. If you do not use this qualifier, the bus number defaults to zero.

The number can be any number from 0 through 25.

/PATH=(n1[.n2.n3.n4.n5.n6])

Specifies the path to the device on the bus. The path is used to uniquely identify a device if the device does not have a serial number. The path specification is a series of six or fewer nonzero numbers, where:
n1 is the number of the port on the root hub (at tier 0).
n2 through n6 are port numbers for downstream hubs at tiers 1, 2, 3, 4, and 5. (If you do not specify trailing zeros, the UCM server supplies them.)

For example, /PATH=1.4.3 indicates that the device is plugged into port 3 of the second tier hub, which is plugged into port 4 of the first tier hub, which in turn is plugged into the root hub 1.

For a more detailed explanation of path specifications, see Figure 23-2 and the text that introduces the figure.

/UNIT_NUMBER=number

Unit numbers can be between 0 and 9999. By default, UCM selects the next available unit number. This qualifier allows you to change the unit number to suit your needs.

Example


$  UCM
Universal Serial Bus Configuration Manager, Version V1.0
UCM> SHOW DEVICE /UNCONFIGURED

DEVICE
DEVICE_TYPE                     TENTATIVE
DEVICE_NAME_ROOT                AG
UNIT_NUMBER                     0
BUS                             1
PATH                            1.0.0.0.0.0
END_DEVICE

UCM> ADD DEVICE AGA0:

UCM> SHOW DEVICE /PERMANENT /FULL AGA0:

DEVICE
DEVICE_TYPE                     PERMANENT
DEVICE_NAME_ROOT                AG
UNIT_NUMBER                     0
DRIVER                          SYS$AGDRIVER.EXE
BUS_NUMBER                      1
PATH                            1.0.0.0.0.0
HID_USAGE_DATA                  65540
BEGIN_INTERFACE
HID_USAGE_DATA                  65540
END_INTERFACE
END_DEVICE

UCM>
      

In this example, the first UCM command SHOW DEVICE /UNCONFIGURED indicates that the device has not yet been configured. It displays only the information that appears in the generic list: the device name root, the unit number, the bus, and the path.

After the ADD DEVICE command, the second SHOW DEVICE command, with the /PERMANENT and /FULL qualifiers, displays the information in the permanent list. The list includes the name of the driver assigned to the device, the bus number; and the Human Interface Device (HID) usage data number, which is used to configures devices in the HID interface class. Examples of HID devices are keyboards, mice, joysticks, and so on.

DELETE DEVICE

Allows you to remove a device from the the permanent list.

Requires SYSPRV privilege.


Format

DELETE DEVICE device-name:


Parameters

device-name:

The name of the device whose characteristics are to be deleted. The device name has the form ddcu, where:
dd is the device code---for example, LP. (The driver name corresponds to the device code; in this case, the driver name would be SYS$LPDRIVER.)
c is the controller designation A through Z; unless UCM specifies a different letter, all USB devices are A.
u is the unit number (0 through 9999).

OpenVMS device names are made up of the two-character device code, followed by the controller designation, then by the unit number (which can be 1 to 4 characters long), then by a colon (:).


Example


$  UCM
Universal Serial Bus Configuration Manager, Version V1.0

UCM> SHOW DEVICE /PERMANENT AGA0:

DEVICE
DEVICE_TYPE                     PERMANENT
DEVICE_NAME_ROOT                AG
UNIT_NUMBER                     0
BUS                             1
PATH                            1.0.0.0.0.0
END_DEVICE

UCM> DELETE DEVICE AGA0:

UCM> SHOW DEVICE /PERMANENT AGA0:

%USB-E-NOSUCHDEV, Device name or device unit not found

UCM>
      

In this example, the first SHOW DEVICE AGA0: command displays information about the device that is in the permanent list. After the DELETE DEVICE AGA0: command, the second SHOW DEVICE AGA0: command displays an error message indicating that the device is no longer in the permanent list.

EXIT

Stops the execution of UCM and returns control to DCL command level. You can also press Ctrl/Z to perform the same function.

Format

EXIT

HELP

Provides online help for using the UCM commands.

Format

HELP [command-name]


Parameter

command-name

The name of a UCM command. When you enter the HELP command with a command name, UCM displays a list of all the command keywords used with the command.

Example


UCM> HELP RESTART

RESTART

     Restarts the configuration server.  This command should be used
     only if the server is no longer responding to configuration requests
     or if the client cannot get the server to respond to commands.  Use
     of this command requires the CMKRNL privilege.

     Format

       RESTART

 Additional information available:

  Qualifiers
  /CONFIRM

RESTART Subtopic?
      

The HELP RESTART command describes the command, shows its format, and indicates what additional information is available, such as qualifiers. It then prompts you to enter the name of the /CONFIRM qualifier to display information about this qualifier.

MODIFY DEVICE

Allows you to modify the path and unit number of a device in the permanent list. The changes take place immediately.

Requires SYSPRV privilege.


Format

MODIFY DEVICE device-name:


Parameter

device-name:

The name of the device whose characteristics are to be modified. The device name has the form ddcu, where:
dd is the device code---for example, LP. (The driver name corresponds to the device code; in this case, the driver name would be SYS$LPDRIVER.)
c is the controller designation A through Z; unless UCM specifies a different letter, all USB devices are A.
u is the unit number (0 through 9999).

OpenVMS device names are made up of the two-character device code, followed by the controller designation, then by the unit number (which can be 1 to 4 characters long), and then by a colon (:).


Qualifiers

/BUS_NUMBER=number

Specifies the USB bus number of the device. This parameter is required to identify a particular device on a system that has multiple USB buses. If you do not use this qualifier, the bus number defaults to zero.

The number can be any number from 0 through 25.

/PATH=(n1[.n2.n3.n4.n5.n6])

Specifies the path to the device on the bus. The path is used to uniquely identify a device if the device does not have a serial number. The path specification is a series of six or fewer numbers, where:
n1 is the number of the root hub (at tier 0).
n2 through n6 are port numbers for downstream hubs at tiers 1, 2, 3, 4, and 5.

For example, /PATH=1.4.3 indicates that the device is in turn plugged into port 3 of the second tier, which is plugged into port 4 of the first tier, which in turn is plugged into the root hub 1.

/UNIT_NUMBER=number

Unit numbers can be between 0 and 9999. By default, the configuration code selects the next available unit number. This qualifier allows you to change the unit number to suit your needs.

Example


$  UCM
Universal Serial Bus Configuration Manager, Version V1.0

UCM> SHOW DEVICE /UNCONFIGURED

DEVICE
DEVICE_TYPE                     TENTATIVE
DEVICE_NAME_ROOT                AG
UNIT_NUMBER                     0
BUS                             1
PATH                            1.0.0.0.0.0
END_DEVICE

UCM> ADD DEVICE AGA0:

UCM> MODIFY DEVICE AGA0:/UNIT=9999

UCM> SHOW DEVICE /PERMANENT /FULL AGA9999:

DEVICE
DEVICE_TYPE                     PERMANENT
DEVICE_NAME_ROOT                AG
UNIT_NUMBER                     9999
DRIVER                          SYS$AGDRIVER.EXE
BUS_NUMBER                      1
PATH                            1.0.0.0.0.0
HID_USAGE_DATA                  65540
BEGIN_INTERFACE
HID_USAGE_DATA                  65540
END_INTERFACE
END_DEVICE

UCM>
      

The first SHOW DEVICE command displays information from the generic list about the unconfigured AG device. The ADD DEVICE command adds the device to the permanent list, and the MODIFY DEVICE command changes the unit number of the device. The second SHOW DEVICE command displays this change.

RELOAD

Forces the configuration server to reload the configuration data from the generic and permanent device files and to rebuild the lists. This allows you to add a new device type and lets the server find out about it without restarting UCM.

Requires SYSPRV privilege.


Format

RELOAD

RESTART

Restarts the configuration server.

Note

Use this command only if the server no longer responds to configuration requests or client commands.

Requires CMKRNL privilege.


Format

RESTART


Qualifier

/CONFIRM (default)
/NOCONFIRM

Asks you to confirm the restart of the configuration server. If you answer yes, the configuration server is restarted. If you answer no, the operation is not performed.

Example


$  UCM
UCM> RESTART

Restart UCM Server? [N]: yes

Waiting for UCM Server image to exit....
Waiting for UCM Server image to restart....
%USB-S-SRVRRESTART, Identification of new UCM Server is 00000217

UCM>
      

Following the RESTART command, UCM prompts you to confirm this command. The system assigns a new identification number to the UCM server when it restarts.

SET LOG

Tells the configuration server to create a new log file. You must use the /NEW qualifier with this command.

Requires OPER privilege.


Format

SET LOG /NEW


Qualifier

/NEW

Creates a new SYS$MANAGER:USB$UCM_EVENTS.DAT file. This qualifier is required with the SET LOG command.

SHOW DEVICE

Displays information about devices.

Format

SHOW DEVICE device-name:


Parameter

device-name:

The name of the device whose characteristics are to be displayed. The device name has the form ddcu, where:
dd is the device code---for example, LP. (The driver name corresponds to the device code; in this case, the driver name would be SYS$LPDRIVER.)
c is the controller designation A through Z; unless UCM specifies a different letter, all USB devices are A.
u is the unit number (0 through 9999.)

OpenVMS device names are made up of the two-character device code, followed by the controller designation, then by the unit number (which can be 1 to 4 characters long), and then by a colon (:).


Display_Qualifiers

/BRIEF (default)

Displays summary information for each device.

/FULL

Displays complete information for each device.

Selection_Qualifiers

/ALL (default)

Displays all device entries, including those that the /CONFIGURED, /GENERIC, /PERMANENT, /PHYSICAL, and /UNCONFIGURED qualifiers display.

/CONFIGURED

Displays all the devices connected to the bus that have been configured successfully.

/GENERIC

Displays the devices that are on the generic device list.

/PERMANENT

Displays the devices for which the system automatically loads device drivers if the devices are plugged in.

/PHYSICAL

Displays the devices that are connected to the bus even if drivers for these devices are not loaded.

/UNCONFIGURED

Displays devices that are attached to the bus and that have drivers, but that do not have entries in the permanent list. (These are also known as tentative devices.)

You must execute an ADD DEVICE command to make these devices part of the permanent list. Once the drivers have been added, the device is automatically configured the next time it is plugged in.


Example


$  UCM
UCM> SHOW DEVICE /PERMANENT /FULL DNA3:

DEVICE
DEVICE_TYPE                     PERMANENT
DEVICE_NAME_ROOT                DN
UNIT_NUMBER                     3
DRIVER                          SYS$DNDRIVER.EXE
USB_CONFIG_TYPE                 INTERFACE
VENDOR_ID                       3519
PRODUCT_ID                      768
RELEASE_NUMBER                  4352
BUS_NUMBER                      1
PATH                            1.0.0.0.0.0
DEVICE_CLASS                    0
DEVICE_SUB_CLASS                0
DEVICE_PROTOCOL                 0
NUMBER_OF_INTERFACES            1
CONFIGURATION_VALUE             2
NUMBER_OF_CONFIGURATIONS        1
SERIAL_NUMBER                   2B0301060D97A4C8
MANUFACTURER_STRING             QTS
PRODUCT_STRING                  USB 2.0 ATAPI Bridge
CONFIGURATION_NUMBER            0
BEGIN_INTERFACE
INTERFACE_CLASS                 8
INTERFACE_SUB_CLASS             6
INTERFACE_PROTOCOL              80
END_INTERFACE
END_DEVICE

UCM>
      

In this example, the SHOW DEVICE command displays complete information about DNA3:.

SHOW EVENTS

Displays important events that occur on the USB bus. Data displayed can include information about device events, such as removals, connections, unrecognized devices, new devices, and so on.

Format

SHOW EVENTS


Qualifiers

/BEFORE=time

Selects events that occurred before the specified time. You can specify time as an absolute time, as a combination of absolute and delta times, or as the keyword TODAY (default), TOMORROW, or YESTERDAY. Times are expressed in standard OpenVMS date/time format.

/OUTPUT=file-name

Writes the selected events to the specified file. By default, output is sent to the current SYS$OUTPUT device (usually your terminal).

You cannot use the /OUTPUT qualifier with the /PAGE qualifier.

/PAGE
/NOPAGE (default)

Controls how information is displayed. /PAGE displays events on one screen at a time.

You cannot use the /PAGE qualifier with the /OUTPUT qualifier.

/SINCE=time

Selects only those events that occurred on or after the specified time. You can specify time as absolute time, as a combination of absolute and delta times, or as the keyword TODAY (default) or YESTERDAY.

/TYPE=event-type

Selects only the specified type of events. Valid event-types are the following:
ALL All event-types (default).
CONFIGURED Device was recognized and configured.
DECONFIGURE Device was removed from the bus.
DRIVER Driver events.
UCM UCM server events.
UNCONFIGURE Device was recognized but not configured.
UNKNOWN Event type is unknown.

/VALUE=event-number

Selects only the events specified by the event number. In a future version of this product, you will be able to use this qualifier as an alternative to the /TYPE qualifier for events that do not have an assigned keyword.

Example


$  UCM
Universal Serial Bus Configuration Manager, Version V1.0

UCM> SHOW EVENTS /SINCE=YESTERDAY

USB EVENT LISTING
-----------------
Date        Time        Type         Priority Component
-----------------------------------------------------------------------
31-JUL-2002 11:46:20.76 DRIVER       NORMAL   HUBDRIVER
   Message: Find a driver for DeviceClass/DeviceSubClass = 0x9/0x0     1

31-JUL-2002 11:46:20.76 DRIVER       NORMAL   HUBDRIVER
   Message: Configured device UCM0 using driver SYS$HUBDRIVER:         2)

31-JUL-2002 11:46:21.06 DRIVER       NORMAL   HUBDRIVER
   Message: Find a driver for DeviceClass/DeviceSubClass = 0x0/0x0     3)

31-JUL-2002 11:46:21.31 UNKNOWN      NORMAL   UCM UNKNOWN DEVICE
   Message: VENDOR_ID = 3519.PRODUCT_ID = 768.RELEASE_NUMBER =
   4352.BUS_NUMBER = 1.PATH = 1.0.0.0.0.0.DEVICE_CLASS =
   0.DEVICE_SUB_CLASS = 0.DEVICE_PROTOCOL = 0.NUMBER_OF_INTERFACES =
   1.NUMBER_OF_CONFIGURATIONS = 1.SERIAL_NUMBER =
   2B0301060D97A4C8.MANUFACTUR                                         4)

31-JUL-2002 11:46:21.31 DRIVER       NORMAL   HUBDRIVER
   Message: Find a driver for InterfaceClass/InterfaceSubClass/
   Protocol = 0x8/0x6/0x50                                             5)

31-JUL-2002 11:46:21.46 DRIVER       NORMAL   HUBDRIVER
   Message: Configured device DNA3 using driver SYS$DNDRIVER:          6)

 1-AUG-2002 11:16:07.71 DECONFIGURED NORMAL   HUBDRIVER
   Message: Deconfiguring device on bus 1 at port 1 bus tier 1 usb
   address 2                                                           7)
      

Note that the display on your screen might be somewhat different from the one you see here.

Numbers in the example correspond to the following explanations:

  1. UCM saw the root hub.
  2. UCM configured the root hub.
  3. UCM saw a new device.
  4. Data about the new device in number 3 is displayed.
  5. For the device in number 3, UCM attempted to locate a drive based on device interface data.
  6. UCM found and loaded the driver for the device in number 3.
  7. The device specified in the message line was unplugged.


Chapter 24
XA Gateway Control Program Utility (XGCP)(Alpha Only)

24.1 XGCP Description

On OpenVMS Alpha systems, the XA Gateway Control Program utility (XGCP) provides the management interface to the DECdtm XA Gateway and creates the transaction logs used by the DECdtm XA Gateway. It can also be used to stop and restart the XA Gateway server.

The Gateway allows a DECdtm-compliant resource manager, such as RMS Journaling or Oracle Rdb, to be used with an XA-compliant transaction manager.

24.2 XGCP Commands

The following table summarizes XGCP commands:

Command Description
CREATE_LOG Creates a new XA Gateway log
EXIT Exits XGCP
START_SERVER Starts the XA Gateway server
STOP_SERVER Stops the XA Gateway server

24.3 XGCP Usage Summary


Format

RUN SYS$SYSTEM: XGCP

Description

To invoke XGCP, enter the following command at the DCL prompt:


$ RUN SYS$SYSTEM:XGCP

XGCP displays the following prompt, at which you can enter any XGCP command:


XGCP>

To exit from XGCP, enter the EXIT command at the XGCP> prompt, or press Ctrl/Z.

CREATE_LOG

Creates a new XA Gateway log. Requires SYSPRV privilege or read/write access to the SYS$JOURNAL directory.

Format

CREATE_LOG /GATEWAY_NAME=name /SIZE=size


Parameters

None.

Qualifiers

/GATEWAY_NAME=name

This qualifier is required. Specify a gateway name of up to 15 characters.

Creates a gateway log named SYS$JOURNAL:name.DDTM$XG_JOURNAL. Create a separate Gateway log for each Gateway name under which you want your XA applications to run.

/SIZE=size

Specifies the initial size of the log, in blocks. If you omit this qualifier, the log is created with an initial size of 242 blocks. The log file is automatically expanded in size when necessary.

Example


XGCP> CREATE_LOG/GATEWAY_NAME=MYLOG1/SIZE=150
      

The command in this example creates a gateway log named SYS$JOURNAL:MYLOG1.DDTM$XG_JOURNAL. Its initial size is 150 blocks.

EXIT

Exits XGCP. You can also press Ctrl/Z to exit from XGCP.

Format

EXIT


Parameters

None.

Qualifiers

None.

START_SERVER

Starts the XA Gateway server. Requires IMPERSONATE privilege.

Format

START_SERVER


Parameters

None.

Qualifiers

None.

Example


XGCP> START_SERVER
      

The command in this example executes the DCL command file SYS$STARTUP:DDTM$XG_STARTUP.COM, which starts the server process called DDTM$XG_SERVER.

STOP_SERVER

Stops the XA Gateway server process, called DDTM$XG_SERVER, on the current node.

Requires OPER, SYSPRV and AUDIT privileges.


Format

STOP_SERVER


Parameters

None.

Qualifiers

None.

Example


XGCP> STOP_SERVER
      

The command in this example stops the Gateway server process, called DDTM$XG_SERVER.


Appendix A
ACL Editor Keypad Editing Commands

By default, the access control list editor (ACL editor) prompts you for each access control entry (ACE) and provides values for some of the fields within an ACE. You can navigate the ACE fields by using keypad commands, such as FIELD and ITEM.

This appendix describes all the keypad editing commands supplied by the ACL editor. You can supplement or change these key definitions by modifying and recompiling the ACL editor section file SYS$LIBRARY:ACLEDIT.TPU (see Appendix B for more information). To get help on the ACL editor keypad commands, press PF2.

A.1 ACL Editor Keypad Commands

Figure A-1 shows the default ACL editor keypad commands for LK201 keyboards. The numeric keypad on VT100-series terminals is identical to that of the LK201 keyboard shown in Figure A-1; VT100 terminals, however, do not have the supplemental editing keypad (keys E1 through E6).

Figure A-1 Keypad for an LK201-Series Keyboard


Table A-1 describes each of the keypad commands you can use with the ACL editor. In this table, KPn refers to a keypad key labeled with the number n. For example, KP4 refers to the keypad key labeled with the number 4.

Table A-1 ACL Editor Keypad Commands
Command Key or
Key Sequence
Description
ADVANCE KP4 Sets the current direction forward for the FIND, FNDNXT, MOVE SCREEN, OVER ACE, and WORD commands. Movement is toward the end of the ACL.
ADV FIELD GOLD-KP7 Completes the current ACE field and moves the cursor to the next ACE field.
BACKUP KP5 Reverses the current direction for the FIND, FNDNXT, MOVE SCREEN, OVER ACE, and WORD keys. Movement is toward the beginning of the ACL.
BOTTOM GOLD-KP4 Positions the cursor after the last line of the last ACE. Any entries you add are placed at the end of the ACL.
DEL ACE PF4 Deletes the entire ACE in which the cursor is positioned and stores it in the delete-ACE buffer.
DEL C Comma Deletes the character on which the cursor is positioned and stores it in the delete-character buffer.
DEL EOL GOLD-KP2 Deletes text from the current cursor position to the end of the line and stores it in the delete-line buffer.
DEL W Minus Deletes the text from the current cursor position to the beginning of the next word and stores it in the delete-word buffer.
ENTER Enter Indicates that the current ACE is complete. The ACL editor terminates the insertion and verifies that the syntax of the ACE is complete. You can press the Enter key while the cursor is located at any position within the ACE. (Pressing the Return key produces the same results.)
EOL KP2 Moves the cursor to the end of the current line.
FIELD KP7 Completes the current ACE field and moves the cursor to the next ACE field or subfield, inserting text as needed. If the ACL editor is not in prompt mode, the ACL editor advances to the next field in the current ACE.
FIND GOLD-PF3 Searches for an occurrence of a string. Press the FIND key and then enter the string from the main keyboard. Press the ENTER key to search for the string in the current direction, or the ADVANCE or BACKUP key to change the search direction.
FNDNXT PF3 Searches in the current direction for the next occurrence of the string previously entered with the FIND key.
GOLD PF1 When pressed before another keypad key, specifies the second key's alternate function (the bottom function on the keypad diagram).
HELP PF2 Displays information about using the editing keypad.
HELP FMT GOLD-PF2 Displays information about ACE formats.
INSERT GOLD-KP0 Moves all text from the current line down one line, leaving a blank line where an ACE is to be inserted.
ITEM Period Selects the next item for the current ACE field. If the ACL editor is not in prompt mode, this key is ignored.
MOVE SCREEN KP8 Moves the cursor one screen in the current direction (see ADVANCE or BACKUP). A screen is defined as two-thirds the number of lines in the display.
OVER ACE KP0 Moves the cursor to the beginning of the next ACE (if the direction is set to ADVANCE) or to the beginning of the previous ACE (if the direction is set to BACKUP).
TOP GOLD-KP5 Moves the cursor position to the first character of the first ACE in the access control list.
UND ACE GOLD-PF4 Inserts the contents of the delete-ACE buffer in front of the ACE in which the cursor is currently positioned.
UND C GOLD-Comma Inserts the contents of the delete-character buffer directly in front of the cursor.
UND W GOLD-Hyphen Inserts the contents of the delete-word buffer directly in front of the cursor.
WORD KP1 Moves the cursor one word forward (if the direction is set to ADVANCE) or backward (if the direction is set to BACKUP).

A.2 Additional ACL Editing Keys and Key Sequences

In addition to keypad editing, the ACL editor lets you use other keyboard keys and key sequences to perform editing functions. Table A-2 describes these additional ACL editing keys and key sequences. Keys in parentheses indicate the equivalent key for an LK201-series keyboard.

Table A-2 Additional ACL Editing Keys and Key Sequences
Key or Sequence Action Taken When Key or Sequence Is Pressed
DOWN ARROW KEY Moves the cursor to the character directly in line below it. If the ACE in which the cursor is positioned is new, the ACL editor processes the ACE before moving the cursor. If the entry is incomplete or formatted incorrectly, an error occurs and the cursor does not move.
LEFT ARROW KEY Moves the cursor one character to the left. If the cursor is at the left margin, moves it to the rightmost character in the line above.
RIGHT ARROW KEY Moves the cursor one character to the right. If the cursor is at the right margin, moves it to the leftmost character in the line below.
UP ARROW KEY Moves the cursor to the character directly in line above it. If the ACE in which the cursor is positioned is new, the ACL editor processes the ACE before moving the cursor. If the entry is incomplete or formatted incorrectly, an error occurs and the cursor does not move.
GOLD- <- Shifts the text in the display window 8 characters to the left.
GOLD--> Shifts the text in the display window 8 characters to the right.
Backspace (F12) Moves the cursor to the beginning of the current line.
Ctrl/A Changes the current mode from insert mode to overstrike mode or from overstrike mode to insert mode. Insert mode (the default) inserts a character to the left of the current character. Overstrike mode replaces the current character.
Ctrl/D Allows you to execute one TPU command.
Ctrl/H Moves the cursor to the beginning of the line. (Performs the same function as the backspace key.)
Ctrl/J Deletes the text from the cursor back to the beginning of the word. (Performs the same function as the linefeed key.)
Ctrl/R Refreshes the screen display. Clears and redraws the screen, deleting any extraneous characters or messages that might have appeared on the screen but are not part of the ACL you are editing. (Performs the same function as Ctrl/W.)
GOLD-Ctrl/R Returns the ACL to its original state before the ACL editor was invoked. (Performs the same function as GOLD-Ctrl/W.)
Ctrl/U Deletes the text from the cursor to the beginning of the line.
GOLD-Ctrl/U Inserts the contents of the deleted-line buffer into the line at the current position. The line might wrap automatically.
Ctrl/W See Ctrl/R.
GOLD-Ctrl/W See GOLD Ctrl/R.
Ctrl/Z Ends the editing session and updates the ACL. (Unless otherwise specified, any recovery and journal files are deleted.)
GOLD-Ctrl/Z Ends (quits) the editing session without saving any of the changes made to the ACL. (Unless otherwise specified, any recovery and journal files are deleted.)
DELETE KEY Deletes the character to the left of the cursor.
Linefeed (F13) Deletes the text from the cursor back to the beginning of the word. If the cursor is positioned at the first character of the word, deletes to the beginning of the previous word.
Tab Moves the text located to the right of the cursor to the next tab stop.

A.3 ACL Editing Keys on the Supplemental Keypad (LK201-Series Keyboards)

You can use the supplemental keypad on an LK201-series keyboard to move sections of text from one part of an ACL to another. However, note that certain supplemental editing keys (Insert Here, Remove, and Select) require a PASTE buffer, which is not enabled by default. To enable the PASTE buffer for the current editing session, perform the following actions:

  1. Press Ctrl/D.
  2. At the TPU command: prompt, enter the following statement:


    TPU command: ACLEDIT$X_PASTE_BUFFER:=1
    
  3. Press Ctrl/D again, and enter the following statement:


    TPU command: ACLEDIT$X_CHECK_MODIFY:=0
    

    Setting the value of the ACLEDIT$X_CHECK_MODIFY variable to 0 prevents the ACL editor from checking for a modifiable ACE. The two features (support for the PASTE buffer and the check for a modifiable ACE) are not compatible.

To enable the PASTE buffer for all ACL editing sessions, change the values of the variables ACLEDIT$X_PASTE_BUFFER and ACLEDIT$X_CHECK_MODIFY in the ACL editor section file and recompile the file (see Appendix B).

Table A-3 describes the supplemental keypad keys you can use with the ACL editor.

Table A-3 ACL Editing Keys on the Supplemental Keypad
Key or
Key Sequence
Description
Find Elicits the Search for: prompt as the first step in the FIND operation. Type the search string after the prompt; then, press either the Do key or the Enter key to process the search. Performs the same function as the FIND keypad command.
Insert Here Indicates where an ACE is to be inserted or, if support for the PASTE buffer is enabled, indicates the line where the selected text in the PASTE buffer is to be inserted.
Remove Removes the selected text to the PASTE buffer. Each time you press the Remove key, the ACL editor deletes the previous contents of the PASTE buffer.
GOLD-Remove (COPY) Copies the selected text to the PASTE buffer. Each time you use the COPY command, the ACL editor deletes the previous contents of the PASTE buffer.
Select Marks the beginning of a range of text to be removed or copied to the PASTE buffer. Press the Select key. Then, move the cursor to include the desired amount of text to be removed or copied. Press either Remove or GOLD-Remove (COPY) to complete the operation.
Prev Screen Moves the cursor to the previous screen. By default, a screen is defined as two-thirds the number of lines in the display.
Next Screen Moves the cursor one screen forward. By default, a screen is defined as two-thirds the number of lines in the display.


Appendix B
Customizing the ACL Editor

You can modify the access control list editor (ACL editor) by modifying and recompiling the ACL section file SYS$LIBRARY:ACLEDIT.TPU (the source file used to create the compiled ACL section file SYS$LIBRARY:ACLEDT$SECTION.TPU$SECTION). You can also create your own ACL section file.

Refer to the DEC Text Processing Utility Reference Manual for more information about writing and processing section files.

B.1 Modifying Variables in the ACL Section File

Table B-1 lists the ACL section file variables and their defaults.

Table B-1 ACL Section File Variables
Variable Meaning
ACLEDIT$X_CHECK_DUPLICATES Controls whether a check for duplicate ACEs is made. This variable can take the following values:
0 No duplicate ACE check is made.
1 A duplicate ACE check is made. If the ACE to be entered matches an existing ACE, an error message is returned. This is the default.
ACLEDIT$X_CHECK_MODIFY Allows or disallows modification of ACEs. This variable can take the following values:
0 The ACE can be modified.
1 The ACE cannot be modified. If an attempt is made to modify the ACE, it is replaced with the original ACE. This is the default.
ACLEDIT$X_DIRECTORY_FILE Indicates whether the object is a directory file. This variable can take the following values:
0 The object is not a directory file.
1 The object is a directory file.
ACLEDIT$X_PASTE_BUFFER Controls whether PASTE buffer support is enabled for VT200 series terminals. This variable can take the following values:
0 PASTE buffer support is disabled. This is the default.
1 PASTE buffer support is enabled.
ACLEDIT$X_PROMPT Controls whether automatic text insertion (prompt mode) is enabled. This variable can take the following values:
0 Prompt mode is disabled.
1 Prompt mode is enabled. This is the default.
ACLEDIT$X_USE_DEFAULT_OPT Controls whether the DEFAULT option can be used with nondirectory ACEs. This variable can take the following values:
0 The DEFAULT option can only be used with ACEs of directory (.DIR) files. This is the default.
1 The DEFAULT option is available for use with ACEs of all object types.
ACLEDIT$C_WINDOW_SHIFT Specifies the number of columns to shift the edit window in the direction wanted, GOLD key and left arrow for a left shift and GOLD key and right arrow for a right shift. The default is 8 columns.

If you modify any of the variables in Table B-1 or change any other part of the ACL section file, recompile the section file with the following command:


$ EDIT/TPU/NOSECTION/COMMAND=SYS$LIBRARY:ACLEDIT

Use the preceding command if you make changes directly to the source code file (SYS$LIBRARY:ACLEDIT) that creates the compiled ACL section file SYS$LIBRARY:ACLEDT$SECTION. If you add a private command file to the existing ACL section file, recompile the section file using the following command:


$ EDIT/TPU/SECTION=SYS$LIBRARY:ACLEDT$SECTION/COMMAND=CUSTOM_ACL.TPU

The compiled DECtpu ACL section file is placed in your current directory. To use the new section file, perform one of the following actions:

  • Move the compiled section file, ACLEDT$SECTION.TPU$SECTION, to the SYS$LIBRARY directory. This changes the default ACL editor section file for all users.
  • Keep the compiled section file in your directory and define the logical name ACLEDT$SECTION in your LOGIN.COM file to point to the file, as follows:


    $ DEFINE ACLEDT$SECTION yourdisk:[yourdir]ACLEDT$SECTION
    

Note that the default file type for the section file before compiling (the source file) is TPU, and the default file type for the compiled section file is TPU$SECTION.

For more information about writing and processing a DECtpu section file, refer to the DEC Text Processing Utility Reference Manual.

B.2 Using the ACL Editor CALL_USER Routine

The ACL editor CALL_USER routine is part of the shareable image SYS$LIBRARY:ACLEDTSHR.EXE. You can incorporate the ACL editor CALL_USER routine with its existing function codes into your own ACL section file, or you can write your own CALL_USER routine that recognizes a different set of function codes.

The ACL editor CALL_USER routine recognizes only those functions used by the ACL editor DECtpu section file. All other function codes are passed to a user-supplied CALL_USER routine; if the high-order word of the CALL_USER function code contains the ACL editor facility code (277 in decimal or 115 in hexadecimal), it is handled by the ACL editor CALL_USER routine. Otherwise, an attempt is made to locate a user-supplied CALL_USER routine. Refer to the description of the CALL_USER routine in the DEC Text Processing Utility Reference Manual for more information about creating your own CALL_USER routine.

Table B-2 describes the CALL_USER routine function codes supported by the ACL editor.

Table B-2 CALL_USER Function Codes
Function
Code
Mnemonic Description
18153473 ACLEDIT$C_PARSE_ACE Parses the input string (ACE) and returns the parsed (binary) ACE if no errors are found. Otherwise, the returned string contains a zero as the first two characters, and the unparsed portion of the input ACE as the remainder of the string.
18153474 ACLEDIT$C_CHECK_MODIFY Returns the string "READ_WRITE" if the ACE can be modified by the user. Otherwise, returns the string "READ_ONLY."
18153475 ACLEDIT$C_PROMPT_MODE Returns the string "PROMPT_MODE" if the prompt mode option was specified. Otherwise, returns the string "NOPROMPT_MODE."
18153476 ACLEDIT$C_CHECK_ACE Parses the input string (ACE) and returns the parsed (binary) ACE if no errors are found. Otherwise, the ACE text is highlighted in reverse video and a DECtpu variable of the form ACLEDIT$X_RANGE_x is created to identify the ACE in error. (The "x" is a sequential number starting with 1.)
18153477 ACLEDIT$C_CHECK_DIR Returns the string "DIRECTORY_FILE" if the object being edited is a directory file. Otherwise, returns the string "NODIRECTORY_FILE."
18153478 ACLEDIT$C_SET_CANDIDATE Parses the input string (ACE) and returns the string "PARSE_OK" if no error was encountered. Otherwise, returns the string "PARSE_ERROR." If the parse was successful, a check is made for duplicate ACEs using the CALL_USER function ACLEDIT$C_CHECK_DUP.
18153479 ACLEDIT$C_CHECK_DUP Parses the input string (ACE) and returns the string "PARSE_ERROR" if an error was encountered. Otherwise, the parsed (binary) ACE is compared with the candidate ACE set by the CALL_USER function ACLEDIT$C_SET_CANDIDATE. Returns the string "DUPLICATE_ACE" if the ACE is a duplicate, or "UNIQUE_ACE" if it is not a duplicate.
18153482 ACLEDIT$C_MESSAGE Assumes the input string is a system error code and returns in the ACL editor message window the message text associated with the error code.


Appendix C
Accounting Information for Programmers

Table C-1 gives a summary of the system services that relate to accounting. No system service reads accounting files; to do this you must use knowledge of the structure of accounting files.

Table C-1 Summary of Accounting System Services
System Service Description
$CREPRC Creates a process in which accounting can be disabled.
$SNDJBC Controls what resources are logged in the current accounting file, or logs a user-defined record in the current accounting file.

This appendix describes the structure of an accounting file. It is for programmers who want to access accounting data directly.

Note

The formats described here are subject to change without notice in a future release.

The symbols and offsets described in this appendix are defined by the $ACRDEF macro in the STARLET library.

C.1 Format of an Accounting File Record

An accounting record consists of an accounting record header and a number of information packets. The number and type of information packets depend on the type of the record.

Figure C-1 illustrates the general format of an accounting record. Table C-2 describes the fields in the record header. The type field in the record header is subdivided into five fields, described in Table C-3.

Figure C-1 Format of an Accounting Record


Table C-2 Fields in an Accounting Record Header
Symbolic Offset Description
ACR$W_TYPE Identifies the type of the record. This field is subdivided into five fields, described in Table C-3. (word)
ACR$W_LENGTH Total length of the record, in bytes. (word)
ACR$Q_SYSTIME System time (64-bit absolute time). (quadword)

Table C-3 ACR$W_TYPE Fields in an Accounting Record Header
Symbolic Offset Description
ACR$V_PACKET Identifies this header as a record header. This bit must be 0. (1 bit)
ACR$V_TYPE Identifies the type of the record. The eight record types are described in Table C-4. (7 bits)
ACR$V_SUBTYPE Identifies the type of process with which the record is associated. The subtypes (4 bits) are:
Symbol Meaning
ACR$K_BATCH Batch process
ACR$K_DETACHED Detached process
ACR$K_INTERACTIVE Interactive process
ACR$K_NETWORK Network process
ACR$K_SUBPROCESS Subprocess

Note that this field is only meaningful for records of type ACR$K_IMGDEL and ACR$K_PRCDEL.

ACR$V_VERSION Identifies the version of the accounting file record structure. The versions (3 bits) are:
Symbol Meaning
ACR$K_VERSION2 VAX/VMS Version 2.0
ACR$K_VERSION3T VAX/VMS Version 3.0 field test
ACR$K_VERSION3 OpenVMS Alpha Version 1.0 and VAX/VMS Version 3.0 and later versions of Alpha and VAX
ACR$V_CUSTOMER Identifies whether the record was written by HP software or by customer software. If this bit is 0, the record was written by HP software. If this bit is 1, the record was written by customer software. (1 bit)

Note

ACR$K_CURVER = Current version. Set equal to ACR$K_VERSION3 in this release.

C.1.1 Types of Accounting Record

The type of an accounting record identifies the type of event that caused the record to be logged. The eight types of accounting records are shown in Table C-4. This table shows the information packets contained in each type of record.

Table C-4 Types of Accounting Record
Symbol Event Information Packets
ACR$K_FILE_BL The accounting file was opened ACR$K_FILENAME
ACR$K_FILE_FL The accounting file was closed ACR$K_FILENAME
ACR$K_IMGDEL An image terminated ACR$K_ID
ACR$K_RESOURCE
ACR$K_IMAGENAME
ACR$K_LOGFAIL A login attempt failed ACR$K_ID
ACR$K_RESOURCE
ACR$K_PRCDEL A process terminated ACR$K_ID
ACR$K_RESOURCE
ACR$K_PRINT A print job finished ACR$K_ID
ACR$K_PRINT
ACR$K_SYSINIT The system was initialized ACR$K_ID
ACR$K_RESOURCE
ACR$K_USER An accounting message was sent by the $SNDJBC system service ACR$K_ID
ACR$K_USER_DATA

C.1.2 Format of an Information Packet

The header, in each of the six types of information packets, defines the type of packet as follows:

  • File name packet (ACR$K_FILENAME)
  • Identification packet (ACR$K_ID)
  • Image name packet (ACR$K_IMAGENAME)
  • Print resource packet (ACR$K_PRINT)
  • Resource packet (ACR$K_RESOURCE)
  • User data packet (ACR$K_USER_DATA)

Section C.1.2.1 describes the general format of an information packet. Section C.1.2.2 to Section C.1.2.7 describe the format of each type of information packet.

C.1.2.1 General Format

Each information packet contains a packet header, followed by data fields. The data fields can contain fixed-length data, variable-length data, or offsets to variable-length data. Offsets contain the distance in bytes from the beginning of the packet to the variable-length data.

All variable-length data are represented as counted strings. Variable-length data follow the last fixed-length data field in the packet. Figure C-2 shows the general format of an information packet. An information packet may not have values in all of its data fields.

See Section C.1.2.2 to Section C.1.2.7 for complete descriptions of the data fields contained in each information packet.

All information packets start with a packet header that has ACR$W_LENGTH and ACR$W_TYPE fields (see Table C-5 and Table C-6).

Figure C-2 Format of an Information Packet


Table C-5 Fields in an Information Packet Header
Symbolic Offset Description
ACR$W_TYPE Identifies the type of the packet. This field is subdivided into five fields, described in Table C-6. (word)
ACR$W_LENGTH Total length of the packet, in bytes. (word)

Table C-6 ACR$W_TYPE Fields in an Information Packet Header
Symbolic Offset Description
ACR$V_PACKET Identifies this header as a packet header. This bit must be 1. (1 bit)
ACR$V_TYPE Identifies the type of the packet. The six packet types (7 bits) are:
Symbol Description
ACR$K_FILENAME File name packet
ACR$K_ID Identification packet
ACR$K_IMAGENAME Image name packet
ACR$K_PRINT Print resource packet
ACR$K_RESOURCE Resource packet
ACR$K_USER_DATA User data packet
ACR$V_SUBTYPE Identifies the packet subtype; reserved for future use. (4 bits)
ACR$V_VERSION See Table C-3.
ACR$V_CUSTOMER See Table C-3.

C.1.2.2 File Name Packet (ACR$K_FILENAME)

The file name packet contains the name of the accounting file. Figure C-3 shows the format of the file name packet. Table C-7 describes the field contained in the packet. See Section C.1.2.1 for information on the packet header.

Figure C-3 Format of a File Name Packet


Table C-7 Data Fields in a File Name Packet
Symbolic Offset Description
ACR$T_FILENAME Name of the file (counted ASCII string that gives full file specification).

C.1.2.3 Identification Packet (ACR$K_ID)

The identification packet identifies the process that caused the record to be logged.

Figure C-4 shows the format of the identification packet. Table C-8 describes the fields contained in the packet. See Section C.1.2.1 for information on the packet header.

Figure C-4 Format of an Identification Packet


Table C-8 Data Fields in an Identification Packet
Symbolic Offset Description
ACR$L_PID Process identifier (PID) of the process. (longword)
ACR$L_OWNER PID of the parent process. (longword)
ACR$L_UIC UIC of the process. The UIC can be addressed as two separate words: ACR$W_MEM for the member number, and ACR$W_GRP for the group number. (longword)
ACR$Q_PRIV Privileges held by the process. (quadword)
ACR$B_PRI Base priority of the process. (byte)
ACR$B_IDFLGS Flags byte; full address and full name present if low bit is set.
ACR$W_USERNAME Offset to counted ASCII string containing the user name of the process. (word)
ACR$W_ACCOUNT Offset to counted ASCII string containing the account name of the process. (word)
ACR$W_NODENAME Offset to counted ASCII string containing the Phase W node name of the remote process. (word)
ACR$W_TERMINAL Offset to counted ASCII string containing the terminal name. (word)
ACR$W_JOBNAME Offset to counted ASCII string containing the job name. (word)
ACR$L_JOBID Identification of the print or batch job (queue entry number). (longword)
ACR$W_QUEUE Offset to counted ASCII string containing the name of the queue with which a batch or print job is associated. (word)
ACR$W_NODEADDR Offset to a counted binary string containing the Phase W remote node address. (word)
ACR$W_REMOTEID Offset to counted ASCII string containing the remote ID of the remote process (varies with network implementation and use). (word)
ACR$W_FULLADDR Offset to a counted binary string containing the complete remote node network address. On a DECnet-Plus system, this is the remote node's NSAP address.
ACR$W_FULLNAME Offset to a counted ASCII string containing the complete remote node name. On a DECnet-Plus system, this is the remote node's full name.

C.1.2.4 Image Name Packet (ACR$K_IMAGENAME)

The image name packet contains the name of the image executed by the identified process.

Figure C-5 shows the format of the image name packet. Table C-9 describes the field contained in the packet. See Section C.1.2.1 for information on the packet header.

Figure C-5 Format of an Image Name Packet


Table C-9 Data Field in an Image Name Packet
Symbolic Offset Description
ACR$T_IMAGENAME Name of the image (counted ASCII string that gives full file specification).

C.1.2.5 Print Resource Packet (ACR$K_PRINT)

The print resource packet contains information about print jobs.

Figure C-6 shows the format of the print resource packet. Table C-10 describes the fields contained in the packet. See Section C.1.2.1 for information on the packet header.

Figure C-6 Format of a Print Resource Packet


Table C-10 Data Fields in a Print Resource Packet
Symbolic Offset Description
ACR$L_PRINTSTS Status of the print job. (longword)
ACR$Q_QUETIME Time the job was queued. (64-bit absolute time)
ACR$Q_BEGTIME Time the job was started. (64-bit absolute time)
ACR$L_SYMCPUTIM Symbiont CPU time (always zero). (longword)
ACR$L_PAGECNT Number of pages printed. (longword)
ACR$L_QIOCNT Number of QIOs issued to the printer. (longword)
ACR$L_GETCNT Number of GETs from the file that was printed. (longword)

C.1.2.6 Resource Packet (ACR$K_RESOURCE)

The resource packet contains information about the identified process.

Figure C-7 shows the format of a resource packet. Table C-11 describes the fields contained in the packet. See Section C.1.2.1 for information on the packet header.

Figure C-7 Format of a Resource Packet


Table C-11 Data Fields in a Resource Packet
Symbolic Offset Description
ACR$Q_LOGIN 64-bit absolute time at which the image was run or the process was created. (quadword)
ACR$L_STATUS Final exit status of the image, or for a process, the final status of the last image executed in the process. (longword)
ACR$L_IMGCNT Number of images run by the process. (longword)
ACR$L_CPUTIME Total CPU time used by the image or process, measured in units of 10 milliseconds. This includes any vector CPU time. (longword)
ACR$L_FAULTS Number of hard and soft page faults incurred by the image or process. (longword)
ACR$L_FAULTIO Number of hard page faults incurred by the image or process. (longword)
ACR$L_WSPEAK Maximum working set size used by the image or process. (longword)
ACR$L_PAGEFL Maximum page file usage. (longword)
ACR$L_DIOCNT Number of direct I/Os made by the image or process. (longword)
ACR$L_BIOCNT Number of buffered I/Os made by the image or process. (longword)
ACR$L_VOLUMES Number of volumes mounted by the image or process. (longword)
ACR$L_VP_CPUTIME Vector CPU time used by the image or process, measured in units of 10 milliseconds. (longword)

C.1.2.7 User Data Packet (ACR$K_USER_DATA)

The user data packet contains an accounting message sent by the $SNDJBC system service.

Figure C-8 shows the format of the user data packet. Table C-12 describes the fields contained in the packet. See Section C.1.2.1 for information on the packet header.

Figure C-8 Format of a User Data Packet


Table C-12 Data Field in a User Data Packet
Symbolic Offset Description
ACR$T_USER_DATA Up to 255 bytes of data (counted string).


Appendix D
ANALYZE/DISK_STRUCTURE---Stage Checks

ANALYZE/DISK_STRUCTURE performs the verification of a volume or volume set in eight distinct stages. During these stages, ANALYZE/DISK_STRUCTURE compiles information that is used in reporting errors and performing repairs.

Before ANALYZE/DISK_STRUCTURE can proceed with each stage, it must perform the following four initialization functions:

  • Read the device name, validate access to the device, and save the device name
  • Read the user-specified file names for the /LIST and /USAGE qualifiers, if specified, and open the files
  • Assign all appropriate channels to the device being checked
  • Write-lock the volume set to prevent simultaneous updates

The following sections describe the eight stages that ANALYZE/DISK_STRUCTURE goes through while verifying a disk. These descriptions assume that you specified the /REPAIR qualifier in the command. An annotated ANALYZE/DISK_STRUCTURE listing is included at the end of this appendix.

D.1 Stage 1

In Stage 1, ANALYZE/DISK_STRUCTURE gathers various volume information (such as cluster size, volume labels, and the number of volumes in the set) from several reserved files, verifies the information for accuracy, reports all discrepancies, and corrects problems discovered during this stage.

ANALYZE/DISK_STRUCTURE identifies the volume and all the characteristics of that volume by using the parameters of the home block in INDEXF.SYS. When ANALYZE/DISK_STRUCTURE confirms this information, it builds a current version of VOLSET.SYS in memory and reads and verifies the status control block (SCB) of BITMAP.SYS.

ANALYZE/DISK_STRUCTURE then compares the volume-set attributes for the version of VOLSET.SYS in memory to the attributes listed in the version of VOLSET.SYS resident on the volume, reports discrepancies, and corrects errors.

D.2 Stage 2

In Stage 2, ANALYZE/DISK_STRUCTURE copies the current version of QUOTA.SYS into working memory, and establishes the structure on which another QUOTA.SYS file is built during subsequent stages. In Stage 7, these copies are compared with each other and inconsistencies are reported.

D.3 Stage 3

Stage 3 checks consist of ANALYZE/DISK_STRUCTURE operations that use the reserved file INDEXF.SYS. During Stage 3, ANALYZE/DISK_STRUCTURE opens INDEXF.SYS, reads each file header, and completes the following steps:

  • Validates each file's FID, and confirms that all files can be retrieved through the FID
  • Validates the header and the revision date of each file
  • Validates any extension headers of each file
  • Confirms that each segment number reflects the proper sequence of extension headers

ANALYZE/DISK_STRUCTURE also performs the following operations during Stage 3:

  • Builds a map of header linkage so that ambiguities can be detected
  • Determines the high block (HIBLK) and end-of-file block (EFBLK) record attributes and compares these values with the recorded values in INDEXF.SYS
  • Checks the high-water mark (HIWATERMARK)

While performing these checks, ANALYZE/DISK_STRUCTURE builds several maps that it uses in subsequent stages. Table D-1 briefly describes each map built in Stage 3.

Table D-1 Stage 3 Maps
Bitmap Function
Valid file numbers The current state of the bitmap for INDEXF.SYS
Lost file numbers All the valid file numbers not yet found in a directory
Directory files List of all directory files
Extension linkages List of all valid extension headers
Multiply allocated clusters List of all clusters that are referenced by more than one header
Allocated clusters All allocated clusters on the volume (or volume set)
System map The new storage bitmap
Valid file backlink A map of all valid file backlinks
Invalid backlink A map of all invalid backlinks

D.4 Stage 4

In Stage 4, ANALYZE/DISK_STRUCTURE builds a current version of BITMAP.SYS using the maps built during Stage 3. In addition, ANALYZE/DISK_STRUCTURE reports any discrepancies between the headers' maps and the storage bitmap. In Stage 4, ANALYZE/DISK_STRUCTURE performs the following operations:

  • Copies BITMAP.SYS into working memory
  • Compares the corrected version of BITMAP.SYS with a map built from INDEXF.SYS

  • Writes a corrected version of BITMAP.SYS to disk
  • Reports multiply allocated clusters

D.5 Stage 5

In this stage, ANALYZE/DISK_STRUCTURE completes a pass of all entries in the invalid backlink map. ANALYZE/DISK_STRUCTURE searches the directory hierarchy of the volume to confirm that all files included in INDEXF.SYS are retrievable through the directory structure. In addition, ANALYZE/DISK_STRUCTURE identifies lost directories and attempts to reestablish valid backlinks to those directories.

In Stage 5, ANALYZE/DISK_STRUCTURE performs the following operations:

  • Confirms the locations of all directories listed in the directory map (compiled in Stage 3) and the subsequent files in those directories
  • Enters all directories indicated as lost and locates a valid parent (if any)

D.6 Stage 6

Stage 6 is essentially a cleanup operation for lost file headers. Following Stage 5, ANALYZE/DISK_STRUCTURE is left with a list of files that are truly lost---files that have backlinks to nonexistent directories. These files were not traceable through the directory structure. ANALYZE/DISK_STRUCTURE is also left with a list of files with bad backlinks; these files are traceable through the directory structure, but the backlinks of the files do not point back to the directory that contains them.

During Stage 6, ANALYZE/DISK_STRUCTURE performs the following operations:

  • Checks the backlink map to locate all files with invalid backlinks, then repairs backlinks
  • Checks the lost file bitmap for lost files and places lost files in [SYSLOST] if you specified /REPAIR
  • If you specified the /USAGE qualifier, creates an entry for each lost file

D.7 Stage 7

In this stage, ANALYZE/DISK_STRUCTURE compares the values stored in the quota file built during Stage 2 with those stored in the reserved file QUOTA.SYS. During Stage 7, ANALYZE/DISK_STRUCTURE opens QUOTA.SYS and performs the following operations:

  • Compares the block usage for each UIC listed in QUOTA.SYS to parallel statistics listed in the copy of QUOTA.SYS built in Stage 2
  • Modifies QUOTA.SYS such that values in QUOTA.SYS match values in the copy built in Stage 2
  • Closes QUOTA.SYS

D.8 Stage 8

Throughout the first seven stages, ANALYZE/DISK_STRUCTURE places operations that cannot be performed during a particular stage on a deferred list. The list includes FIDs sorted by operation. In Stage 8, ANALYZE/DISK_STRUCTURE performs all operations stored on the deferred list. In Stage 8, ANALYZE/DISK_STRUCTURE performs the following operations:

  • Removes an FID from the deferred list, renames the file, and adds the file to SYSLOST.DIR or to a user-specified directory
  • Updates QUOTA.SYS to reflect all additional blocks used by the UIC that received the lost file
  • Updates VOLSET.SYS to correct inconsistencies discovered during previous ANALYZE/DISK_STRUCTURE stages

D.9 Annotated Example

The following example is an annotated sample of an ANALYZE/DISK_STRUCTURE session. The command used to generate this example did not include the /REPAIR qualifier.


%VERIFY-I-BADHEADER, file (487,173,1) MAIL$0004008EEAEE0572.MAI;1 (1)
        invalid file header
%VERIFY-I-BADHEADER, file (531,112,1) MAIL$0004008EEFBB198B.MAI;1
        invalid file header
%VERIFY-I-BADHEADER, file (589,104,1) MAIL$0004008EEAF199B9.MAI;1
        invalid file header
%VERIFY-I-BADHEADER, file (604,157,1) MAIL$0004008EF12C3B28.MAI;1
        invalid file header
%VERIFY-I-BADHEADER, file (674,247,1) MAIL$0004008EF6053C9B.MAI;1
        invalid file header
%VERIFY-I-BADHEADER, file (688,41,1) MAIL$0004008EF608AFF4.MAI;1
        invalid file header
%VERIFY-I-BADHEADER, file (689,135,1) MAIL$0004008EEE445A31.MAI;1
        invalid file header
%VERIFY-I-BADHEADER, file (750,71,1) MAIL$0004008EEED19ADF.MAI;1
        invalid file header
%VERIFY-I-BADHEADER, file (753,217,1) MAIL$0004008EE7C4A017.MAI;1
        invalid file header
%VERIFY-I-BADHEADER, file (780,236,1) MAIL$0004008EF777ACA8.MAI;1
        invalid file header
%VERIFY-I-BADHEADER, file (852,57,1) MAIL$0004008EF06C15F6.MAI;1
        invalid file header
%VERIFY-I-BADHEADER, file (856,44,1) MAIL$0004008EE7D2520D.MAI;1
        invalid file header
%VERIFY-I-BADHEADER, file (1059,42,1) MAIL$0004008EEB045608.MAI;1
        invalid file header
%VERIFY-I-BADHEADER, file (1134,76,1) MAIL$0004008EE9EC806D.MAI;1
        invalid file header
%VERIFY-I-BADHEADER, file (1316,147,1) MAIL$0004008EEEDA734F.MAI;1
        invalid file header
%VERIFY-I-BADHEADER, file (1350,74,1) MAIL$0004008EE89BA8B0.MAI;1
        invalid file header
%VERIFY-I-BADHEADER, file (1351,64,1) MAIL$0004008EEB09B036.MAI;1
        invalid file header
%VERIFY-I-BADHEADER, file (1490,104,1) MAIL$0004008EE8B448B0.MAI;1
        invalid file header
%VERIFY-I-BADHEADER, file (1493,106,1) LASTNOTIC.NIL;1
        invalid file header
%VERIFY-I-BADHEADER, file (1548,204,1) MAIL$0004008EF7B4D1B8.MAI;1
        invalid file header
%VERIFY-I-BADHEADER, file (1613,61,1) MAIL$0004008EECEE4BA5.MAI;1
        invalid file header
%VERIFY-I-BADHEADER, file (1812,81,1) MAIL$0004008EE7DF05EC.MAI;1
        invalid file header
%VERIFY-I-BADHEADER, file (1848,26,1) MAIL$0004008EF78659B9.MAI;1
        invalid file header
%VERIFY-I-BADHEADER, file (1983,34119,1) MAIL$0004008EE7E49C13.MAI;1
        invalid file header
%VERIFY-I-BADHEADER, file (1987,33907,1) REMIND.CAL;9
        invalid file header
%VERIFY-I-BADHEADER, file (2196,123,1) MAIL$0004008EE6FA2DC9.MAI;1
        invalid file header
%VERIFY-I-BADHEADER, file (2372,125,1) MAIL$0004008EF06339F9.MAI;1
        invalid file header
%VERIFY-I-BADHEADER, file (2569,67,1) MAIL$0004008EF2BF0C15.MAI;1
        invalid file header
%VERIFY-I-BADHEADER, file (2605,72,1) MAIL$0004008EE856FC73.MAI;1
        invalid file header
%VERIFY-I-BADHEADER, file (2616,70,1) MAIL$0004008EF063C04F.MAI;1
        invalid file header
%VERIFY-I-BADHEADER, file (2774,29818,1) LASTNOTIC.NIL;1
        invalid file header
%VERIFY-I-ALLOCCLR, blocks incorrectly marked allocated (2)
        LBN 442398 to 445538, RVN 1
%VERIFY-I-BADHEADER, file (487,0,1) MAIL$0004008EEAEE0572.MAI;1  (3)
        invalid file header
%VERIFY-I-LOSTEXTHDR, file (487,0,1)
        lost extension file header
%VERIFY-I-BADHEADER, file (531,0,1) MAIL$0004008EEFBB198B.MAI;1
        invalid file header
%VERIFY-I-LOSTEXTHDR, file (531,0,1)
        lost extension file header
%VERIFY-I-BADHEADER, file (589,0,1) MAIL$0004008EEAF199B9.MAI;1
        invalid file header
%VERIFY-I-LOSTEXTHDR, file (589,0,1)
        lost extension file header
%VERIFY-I-BADHEADER, file (604,0,1) MAIL$0004008EF12C3B28.MAI;1
        invalid file header
%VERIFY-I-LOSTEXTHDR, file (604,0,1)
        lost extension file header
%VERIFY-I-BADHEADER, file (674,0,1) MAIL$0004008EF6053C9B.MAI;1
        invalid file header
%VERIFY-I-LOSTEXTHDR, file (674,0,1)
        lost extension file header
%VERIFY-I-BADHEADER, file (688,0,1) MAIL$0004008EF608AFF4.MAI;1
        invalid file header
%VERIFY-I-LOSTEXTHDR, file (688,0,1)
        lost extension file header
%VERIFY-I-BADHEADER, file (689,0,1) MAIL$0004008EEE445A31.MAI;1
        invalid file header
%VERIFY-I-LOSTEXTHDR, file (689,0,1)
        lost extension file header
%VERIFY-I-BADHEADER, file (750,0,1) MAIL$0004008EEED19ADF.MAI;1
        invalid file header
%VERIFY-I-LOSTEXTHDR, file (750,0,1)
        lost extension file header
%VERIFY-I-BADHEADER, file (753,0,1) MAIL$0004008EE7C4A017.MAI;1
        invalid file header
%VERIFY-I-LOSTEXTHDR, file (753,0,1)
        lost extension file header
%VERIFY-I-BADHEADER, file (780,0,1) MAIL$0004008EF777ACA8.MAI;1
        invalid file header
%VERIFY-I-LOSTEXTHDR, file (780,0,1)
        lost extension file header
%VERIFY-I-BADHEADER, file (852,0,1) MAIL$0004008EF06C15F6.MAI;1
        invalid file header
%VERIFY-I-LOSTEXTHDR, file (852,0,1)
        lost extension file header
%VERIFY-I-BADHEADER, file (856,0,1) MAIL$0004008EE7D2520D.MAI;1
        invalid file header
%VERIFY-I-LOSTEXTHDR, file (856,0,1)
        lost extension file header
%VERIFY-I-BADHEADER, file (1059,0,1) MAIL$0004008EEB045608.MAI;1
        invalid file header
%VERIFY-I-LOSTEXTHDR, file (1059,0,1)
        lost extension file header
%VERIFY-I-BADHEADER, file (1134,0,1) MAIL$0004008EE9EC806D.MAI;1
        invalid file header
%VERIFY-I-LOSTEXTHDR, file (1134,0,1)
        lost extension file header
%VERIFY-I-BADHEADER, file (1316,0,1) MAIL$0004008EEEDA734F.MAI;1
        invalid file header
%VERIFY-I-LOSTEXTHDR, file (1316,0,1)
        lost extension file header
%VERIFY-I-BADHEADER, file (1350,0,1) MAIL$0004008EE89BA8B0.MAI;1
        invalid file header
%VERIFY-I-LOSTEXTHDR, file (1350,0,1)
        lost extension file header
%VERIFY-I-BADHEADER, file (1351,0,1) MAIL$0004008EEB09B036.MAI;1
        invalid file header
%VERIFY-I-LOSTEXTHDR, file (1351,0,1)
        lost extension file header
%VERIFY-I-BADHEADER, file (1490,0,1) MAIL$0004008EE8B448B0.MAI;1
        invalid file header
%VERIFY-I-LOSTEXTHDR, file (1490,0,1)
        lost extension file header
%VERIFY-I-BADHEADER, file (1493,0,1) LASTNOTIC.NIL;1
        invalid file header
%VERIFY-I-LOSTEXTHDR, file (1493,0,1)
        lost extension file header
%VERIFY-I-BADHEADER, file (1548,0,1) MAIL$0004008EF7B4D1B8.MAI;1
        invalid file header
%VERIFY-I-LOSTEXTHDR, file (1548,0,1)
        lost extension file header
%VERIFY-I-BADHEADER, file (1613,0,1) MAIL$0004008EECEE4BA5.MAI;1
        invalid file header
%VERIFY-I-LOSTEXTHDR, file (1613,0,1)
        lost extension file header
%VERIFY-I-BADHEADER, file (1812,0,1) MAIL$0004008EE7DF05EC.MAI;1
        invalid file header
%VERIFY-I-LOSTEXTHDR, file (1812,0,1)
        lost extension file header
%VERIFY-I-BADHEADER, file (1848,0,1) MAIL$0004008EF78659B9.MAI;1
        invalid file header
%VERIFY-I-LOSTEXTHDR, file (1848,0,1)
        lost extension file header
%VERIFY-I-BADHEADER, file (1983,0,1) MAIL$0004008EE7E49C13.MAI;1
        invalid file header
%VERIFY-I-LOSTEXTHDR, file (1983,0,1)
        lost extension file header
%VERIFY-I-BADHEADER, file (1987,0,1) REMIND.CAL;9
        invalid file header
%VERIFY-I-LOSTEXTHDR, file (1987,0,1)
        lost extension file header
%VERIFY-I-BADHEADER, file (2196,0,1) MAIL$0004008EE6FA2DC9.MAI;1
        invalid file header
%VERIFY-I-LOSTEXTHDR, file (2196,0,1)
        lost extension file header
%VERIFY-I-BADHEADER, file (2372,0,1) MAIL$0004008EF06339F9.MAI;1
        invalid file header
%VERIFY-I-LOSTEXTHDR, file (2372,0,1)
        lost extension file header
%VERIFY-I-BADHEADER, file (2569,0,1) MAIL$0004008EF2BF0C15.MAI;1
        invalid file header
%VERIFY-I-LOSTEXTHDR, file (2569,0,1)
        lost extension file header
%VERIFY-I-BADHEADER, file (2605,0,1) MAIL$0004008EE856FC73.MAI;1
        invalid file header
%VERIFY-I-LOSTEXTHDR, file (2605,0,1)
        lost extension file header
%VERIFY-I-BADHEADER, file (2616,0,1) MAIL$0004008EF063C04F.MAI;1
        invalid file header
%VERIFY-I-LOSTEXTHDR, file (2616,0,1)
        lost extension file header
%VERIFY-I-BADHEADER, file (2774,0,1) LASTNOTIC.NIL;1
        invalid file header
%VERIFY-I-LOSTEXTHDR, file (2774,0,1)
        lost extension file header
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [ALLWAY]NOTES.LOG;25 (4)
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [BLAIN.BOOTS]LOADER.OBJ;1
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [BLAIN.BOOTS]SYSGEN.OBJ;1
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [BLAIN]MAIL_20600841.TMP;1
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [BLAIN]NETSERVER.LOG;181
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [BLAIN]NETSERVER.LOG;180
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [BLAIN]NETSERVER.LOG;179
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [BLAIN]NETSERVER.LOG;178
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [BLAIN]NETSERVER.LOG;170
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [BOEMUS.MAIL]MAIL$0004008EF94A72A0.MAI;1
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [BOEMUS]NETSERVER.LOG;10
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [BOEMUS]UPDATE.LOG;1
%VERIFY-I-BACKLINK, incorrect directory back link [CALGON.GER]OBJ.DIR;1
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [CALGON]T.TMP;1
%VERIFY-I-BACKLINK, incorrect directory back link [CLABIN.BACKUP.TMPSRC]BACKDEF.SDL;1
%VERIFY-I-BACKLINK, incorrect directory back link [CLABIN.BACKUP.TMPSRC]COMMON.REQ;1
%VERIFY-I-BACKLINK, incorrect directory back link [CLABIN.BACKUP.TMPSRC]DUMMY.MSG;1
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [CLABIN.NMAIL]NMAIL.LOG;77
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [CLABIN.NMAIL]NMAIL.LOG;76
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [DESIN.8800]2840HT86.GNC;1
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [DESIN.8800]2840TP86.GNC;1
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [DOWNE.MAIL]MAIL$0004008EF94A79B3.MAI;1
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [DOWNE.PRO]MORT.OBJ;15
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [DOWNE.PRO]OUTPUT.LOG;36
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [DOWNE.PRO]OUTPUT.LOG;35
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [DOWNE.PRO]OUTPUT.LOG;34
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [DOWNE.PRO]OUTPUT.LOG;33
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [DOWNE.PRO]OUTPUT.LOG;32
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [DOWNE.PRO]OUTPUT.LOG;31
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [DOWNE.PRO]OUTPUT.LOG;30
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [GAMBLE]CONFLICTS.LIS;1
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [GAMBLE.DOC]SMP.LOCK;6
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [GAMBLE]NETSERVER.LOG;5
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [GAMBLE.NMAIL]NMAIL.LOG;22
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [GAMBLE.NMAIL]NMAIL.LOG;21
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [GILLEY.MAIL]MAIL$0004008EF94A7B70.MAI;1
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [GILLEY]NETSERVER.LOG;657
%VERIFY-I-BADDIRENT, invalid file identification in
directory entry [GILLEY]NETSERVER.LOG;656
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [HALL]2.LOG;33
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [HALL]2.LOG;32
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [HALL]2.LOG;31
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [HALL]2.LOG;30
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [HALL]2.LOG;29
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [HALL]2.LOG;28
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [HALL]2.LOG;27
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [HALL]2.LOG;26
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [HALL]2.LOG;25
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [HALL]2.LOG;24
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [NAMOLLY]NETSERVER.LOG;2
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [NAMOLLY]NETSERVER.LOG;1
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [RUSS]082654.LOG;1
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [SCHROEDER.LOGIN]NETSERVER.LOG;17
%VERIFY-I-BADDIR, directory [SYSLOST.BOOTS] has invalid format
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [THOEN]NETSERVER.LOG;374
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [THOEN]NETSERVER.LOG;373
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [THOEN]NETSERVER.LOG;367
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [THOMAS.MAIL]MAIL$0004008EF94D75EB.MAI;1
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [THOMAS.MAIL]MAIL$0004008EF955DDF3.MAI;1
%VERIFY-I-BADDIRENT, invalid file identification in directory entry [THOMAS.MAIL]MAIL$0004008EFD118B44.MAI;1
%VERIFY-I-LOSTSCAN, due to directory errors, lost files will not be entered (5)
%VERIFY-I-INCQUOTA, QUOTA.SYS indicates 69663 blocks used, actual use is 69740 blocks for [11,402] (6)
%VERIFY-I-INCQUOTA, QUOTA.SYS indicates 1764 blocks used, actual use is 1770 blocks for [12,12]
%VERIFY-I-INCQUOTA, QUOTA.SYS indicates 0 blocks used, actual use is 31 blocks for [11,720]

  1. ANALYZE/DISK_STRUCTURE has completed the first two stages, and is beginning Stage 3. Stage 1 involves collection and verification of various volume information. ANALYZE/DISK_STRUCTURE found no problems with volume information. In Stage 2, ANALYZE/DISK_STRUCTURE copies the current version of QUOTA.SYS to working memory, and builds the structure on which a new copy is built during subsequent stages. The first error message is produced by Stage 3. Stage 3 uses the reserved file INDEXF.SYS to locate a variety of file problems. Here, Stage 3 detects a number of invalid file headers. Note that the error message includes the FID and the file name.
  2. This error message is produced during Stage 4, during which ANALYZE/DISK_STRUCTURE builds a current version of BITMAP.SYS, resolves multiple references to extension headers, and corrects discrepancies in the map sections of headers. Here, ANALYZE/DISK_STRUCTURE has found that the specified logical blocks on the specified relative volume were marked allocated in the storage bit map, but were not allocated to a file.
  3. This message marks the beginning of Stage 5. Here, messages stating "lost extension file header" and "invalid file header" indicate that ANALYZE/DISK_STRUCTURE is performing a pass of all entries placed on the invalid backlink map. This map was created in Stage 3.
  4. This message marks the beginning of the second phase of Stage 5, in which ANALYZE/DISK_STRUCTURE confirms that all files in INDEX.SYS are retrievable through the directory structure. Here, the series of "invalid file identification..." messages indicates those directory entries that did not contain a valid file identification.
  5. This message is produced by Stage 6, which is essentially a cleanup phase for lost files. This message indicates that ANALYZE/DISK_STRUCTURE encountered errors during the directory scan that were reported in previous messages. As a result, the file is not entered in directory [SYSLOST].
  6. Here, ANALYZE/DISK_STRUCTURE begins Stage 7, in which it compares values stored in the quota file built during Stage 2 with values in the reserved file QUOTA.SYS. The last three messages here indicate discrepancies between the two files.
    Note that no messages were produced during Stage 8. During Stage 8, ANALYZE/DISK_STRUCTURE executes all operations placed on the deferred list, and if you specified /REPAIR, updates QUOTA.SYS and VOLSET.SYS as necessary.


Appendix E
ANALYZE/DISK_STRUCTURE---Usage File

When you specify the /USAGE qualifier, ANALYZE/DISK_STRUCTURE creates a disk usage accounting file. The first record of this file, the identification record, contains a summary of the disk and volume characteristics. The identification record is followed by many file summary records, one record for each file on the disk. Each file summary record contains the owner, size, and name of a file.

The identification record is characterized by the type code USG$K_IDENT in the USG$B_TYPE field of the record. Table E-1 contains a description of all the fields in this record.

Table E-1 Identification Record Format (Length USG$K_IDENT_LEN)
Field Meaning
USG$L_SERIALNUM Serial number of the volume. This is an octal longword value.
USG$T_STRUCNAM Volume set name (if the volume is part of a volume set). For a Files-11 Structure Level 1 volume, this field contains binary zeros; for a Files-11 Structure Level 2 or 5 volume that is not part of a volume set, this field contains spaces. The length of this field is USG$S_STRUCNAME.
USG$T_VOLNAME Volume name of relative volume 1. The length of this field is USG$S_VOLNAME.
USG$T_OWNERNAME Volume owner name. The length of this field is USG$S_OWNERNAME.
USG$T_FORMAT Volume format type. For a Files-11 Structure Level 1 volume, this field contains "DECFILE11A"; for a Files-11 Structure Level 2 or 5 volume, this field contains "DECFILE11B". The length of this field is USG$S_FORMAT.
USG$Q_TIME Quadword system time when this usage file was created. The length of this field is USG$S_TIME.

Each file summary record is characterized by the type code USG$K_FILE in the USG$B_TYPE field of the record. Table E-2 contains a description of all the fields in these records.

Table E-2 File Record Format (Length USG$K_FILE_LEN)
Field Meaning
USG$L_FILEOWNER File owner UIC. This can be considered as a single longword value or as two word values (USG$W_UICMEMBER and USG$W_UICGROUP).
USG$W_UICMEMBER The member field of the file owner UIC. This is an octal word value.
USG$W_UICGROUP The group field of the file owner UIC. This is an octal word value.
USG$L_ALLOCATED Number of blocks allocated to the file, including file headers. This is a decimal longword value.
USG$L_USED Number of blocks used, up to and including the end-of-file block. This is a decimal longword value.
USG$W_DIR_LEN Length of the directory string portion of USG$T_FILESPEC, including the brackets. This is a decimal word value.
USG$W_SPEC_LEN Length of the complete file specification in USG$T_FILESPEC. This is a decimal word value.
USG$T_FILESPEC File specification, in the following format:

[dir]nam.typ;ver

This field is of variable length. A file that has more than one directory entry is listed under the first file specification found. A lost file has an empty directory string "[]" and the file name is taken from the file header. In some cases this information does not exist; you must take this into consideration when you write application programs to process the usage file. The length of this field is USG$S_FILESPEC.

The symbolic names referenced in both the identification and the file summary records are defined in the system definition macro $USGDEF. The length of the identification record is USG$K_IDENT_LEN. The length of a file summary record is USG$K_FILE_LEN.


Appendix F
Security Audit Message Format

This appendix describes the format of the auditing messages written to the security auditing log file. The default audit log file SECURITY.AUDIT$JOURNAL is created by default in the SYS$COMMON:[SYSMGR] directory.

Each security audit record consists of a header packet followed by one or more data packets, as shown in Figure F-1. The number of data packets depends on the type of information being sent. This appendix describes the format of the audit header and its data packets as well as the contents of the data packets.

Figure F-1 Format of a Security Audit Message


F.1 Audit Header Packet

Table F-1 describes the fields contained in Figure F-2.

Figure F-2 Audit Header Packet Format


Table F-1 Description of the Audit Header Fields
Field Symbolic Offset Contents
Type NSA$W_RECORD_TYPE Indicates the type of event that has occurred. See Table F-2 for details.
Subtype NSA$W_RECORD_SUBTYPE Further defines the type of event that has occurred. See Table F-2 for details.
Flags NSA$W_FLAGS Identifies any flags associated with the audited event. See Table F-3 for details. Reserved to HP. (Word)
Packet count NSA$W_PACKET_COUNT Number of data packets in the audit record. (Word)
Record size NSA$W_RECORD_SIZE Total size of the audit message; the size represents the header packet plus all its data packets. (Word)
Version NSA$C_VERSION_3 Indicates the version of the security auditing facility. The symbol NSA$C_VERSION_3 indicates the current version. (Byte)
Facility NSA$W_FACILITY The facility code for the generated event. By default, this field is zero, indicating a system-generated event. (Word)

When you enter subtypes, do not include a prefix, as shown in Table F-2.

Symbols representing the types or subtypes of security events are listed in Table F-2. For each audit event record type defined by NSA$W_RECORD_TYPE, there is a record subtype defined by the symbol NSA$W_RECORD_SUBTYPE, which further defines the event.

Table F-2 Description of Audit Event Types and Subtypes
Symbols for Event Types and Subtypes Meaning
NSA$C_MSG_AUDIT Systemwide change to auditing
  ALARM_STATE Events enabled as alarms
  AUDIT_DISABLED Audit events disabled
  AUDIT_ENABLED Audit events enabled
  AUDIT_INITIATE Audit server startup
  AUDIT_LOG_FIRST First entry in audit log (backward link)
  AUDIT_LOG_FINAL Final entry in audit log (forward link)
  AUDIT_STATE Events enabled as audits
  AUDIT_TERMINATE Audit server shutdown
  SNAPSHOT_ABORT 1 System snapshot attempt has aborted
  SNAPSHOT_ACCESS 1 Snapshot file access/deaccess
  SNAPSHOT_SAVE 1 System snapshot save in progress
  SNAPSHOT_STARTUP 1 System booted from a snapshot file
     
NSA$C_MSG_BREAKIN Break-in attempt detected
  BATCH Batch process
  DETACHED Detached process
  DIALUP Dialup interactive process
  LOCAL Local interactive process
  NETWORK Network server task
  REMOTE Interactive process from another network node
  SUBPROCESS Subprocess
     
NSA$C_MSG_CONNECTION Logical link connection or termination
  CNX_ABORT Connection aborted
  CNX_ACCEPT Connection accepted
  CNX_DECNET_CREATE DECnet logical link created
  CNX_DECNET_DELETE DECnet logical link disconnected
  CNX_DISCONNECT Connection disconnected
  CNX_INC_ABORT Incoming connection request aborted
  CNX_INC_ACCEPT Incoming connection request accepted
  CNX_INC_DISCONNECT Incoming connection disconnected
  CNX_INC_REJECT Incoming connection request rejected
  CNX_INC_REQUEST Incoming connection request
  CNX_IPC_CLOSE Interprocess communication association closed
  CNX_IPC_OPEN Interprocess communication association opened
  CNX_REJECT Connection rejected
  CNX_REQUEST Connection requested
     
NSA$C_MSG_INSTALL Use of the Install utility (INSTALL)
  INSTALL_ADD Known image installed
  INSTALL_REMOVE Known image deleted
     
NSA$C_MSG_LOGFAIL Login failure
  See subtypes for
NSA$C_MSG_BREAKIN
     
NSA$C_MSG_LOGIN Successful login
  See subtypes for
NSA$C_MSG_BREAKIN
     
NSA$C_MSG_LOGOUT Successful logout
  See subtypes for
NSA$C_MSG_BREAKIN
     
NSA$C_MSG_MOUNT Volume mount or dismount
  VOL_DISMOUNT Volume dismount
  VOL_MOUNT Volume mount
     
NSA$C_MSG_NCP Modification to network configuration database
  NCP_COMMAND Network Control Program (NCP) command issued
     
NSA$C_MSG_NETPROXY Modification to network proxy database
  NETPROXY_ADD Record added to network proxy authorization file
  NETPROXY_DELETE Record removed from network proxy authorization file
  NETPROXY_MODIFY Record modified in network proxy authorization file
     
NSA$C_MSG_OBJ_ACCESS Object access attempted
  OBJ_ACCESS Access attempted to create, delete, or deaccess an object
     
NSA$C_MSG_OBJ_CREATE Object creation attempted
  OBJ_CREATE Access attempted to create an object
     
NSA$C_MSG_OBJ_DEACCESS Object deaccessed
  OBJ_DEACCESS Attempt to complete access to an object
     
NSA$C_MSG_OBJ_DELETE Object deletion attempted
  OBJ_DELETE Object deletion attempted
     
NSA$C_MSG_PROCESS Process controlled through a system service
  PRC_CANWAK Process wakeup canceled
  PRC_CREPRC Process created
  PRC_DELPRC Process deleted
  PRC_FORCEX Process exit forced
  PRC_GETJPI Process information gathered
  PRC_GRANTID Process identifier granted
  PRC_RESUME Process resumed
  PRC_REVOKID Process identifier revoked
  PRC_SCHDWK Process wakeup scheduled
  PRC_SETPRI Process priority altered
  PRC_SIGPRC Process exception issued
  PRC_SUSPND Process suspended
  PRC_TERM Process termination notification requested
  PRC_WAKE Process wakeup issued
     
NSA$C_MSG_PRVAUD Use of privilege
  PRVAUD_FAILURE Unsuccessful use of privilege
  PRVAUD_SUCCESS Successful use of privilege
     
NSA$C_MSG_RIGHTSDB Modification to the rights database
  RDB_ADD_ID Identifier added to rights database
  RDB_CREATE Rights database created
  RDB_GRANT_ID Identifier granted to user
  RDB_MOD_HOLDER List of identifier holders modified
  RDB_MOD_ID Identifier name or attributes modified
  RDB_REM_ID Identifier removed from rights database
  RDB_REVOKE_ID Identifier taken away from user
     
NSA$C_MSG_SYSGEN Use of the System Generation utility (SYSGEN)
  SYSGEN_SET System parameter modified
     
NSA$C_MSG_SYSTIME Modification to system time
  SYSTIM_SET System time set
  SYSTIM_CAL System time calibrated
     
NSA$C_MSG_SYSUAF Modification to system user authorization file (SYSUAF)
  SYSUAF_ADD Record added to system user authorization file
  SYSUAF_COPY Record added to system user authorization file
  SYSUAF_DELETE Record deleted from system user authorization file
  SYSUAF_MODIFY Record modified in system user authorization file
  SYSUAF_RENAME Record renamed in system user authorization file

1Obsolete as of OpenVMS Version 7.1

Table F-3 identifies any flags associated with the audited event.

The symbol NSA$K_MSG_HDR_LENGTH defines the current size of the message header (in bytes).

Table F-3 Description of Audit Event Flags
Symbol Meaning
NSA$M_ACL Event generated by an alarm access control entry (ACE) or an audit ACE.
NSA$M_ALARM Event is a security alarm.
NSA$M_AUDIT Event is a security audit.
NSA$M_FLUSH Event forced the audit server to write all buffered event messages to the audit log file.
NSA$M_FOREIGN Event occurred outside of the system trusted computing base.
NSA$M_MANDATORY Event resulted from a mandatory process audit.

Note

All other flags besides those listed in the table are reserved by HP.

F.2 Audit Data Packets

Figure F-3 illustrates the format of an audit data packet. NSA$K_PKT_HDR_LENGTH defines the current size of each packet header (in bytes).

Note that audit data packets do not appear in any predefined order within an event message, and packet types can appear more than once throughout the event message.

For examples of the types of data appearing in different event messages, refer to the appendix of alarm messages in the HP OpenVMS Guide to System Security.

Figure F-3 Audit Data Packet Format


Table F-4 describes the fields contained in these packets.

Table F-4 Description of the Audit Data Packet
Field Symbolic Offset Contents
Packet size NSA$W_PACKET_SIZE Indicates the size of the data packet. (Word)
Packet type NSA$W_PACKET_TYPE Indicates the type of data in the packet, as described in Table F-5.
Packet data NSA$R_PACKET_DATA Variable length field containing the packet data.

Table F-5 describes the types of data in audit packets.

Table F-5 Types of Data in Audit Packets
Symbol Packet Contents
NSA$_ACCESS_DESIRED Access requested or granted to the object as defined by $ARMDEF (Longword)
NSA$_ACCESS_MODE Access mode of the process (Byte)
NSA$_ACCOUNT Account name associated with the process (String of 1-32 characters)
NSA$_ALARM_NAME Name of the user (or the security class operators terminal) to receive the record (String of 1-32 characters)
NSA$_ASSOCIATION_NAME Interprocess communication (IPC) association name (String of 1-256 characters)
NSA$_AUDIT_FLAGS Bit mask of enabled or disabled events. This is reserved to HP. (40-byte record) (String of 1-65 characters)
NSA$_AUDIT_NAME Journal file to receive the audit record (String of 1-65 characters)
NSA$_COMMAND_LINE Command line the user entered (String of 1-2048 characters)
NSA$_CONNECTION_ID Interprocess communication (IPC) connection identification (Longword)
NSA$_DECNET_LINK_ID DECnet logical link identification (Longword)
NSA$_DECNET_OBJECT_NAME DECnet object name (String of 1-16 characters)
NSA$_DECNET_OBJECT_NUMBER DECnet object number (Longword)
NSA$_DEFAULT_USERNAME Default local user name for incoming network proxy requests (String of 1-32 characters)
NSA$_DEVICE_NAME Device name where the volume resides (String of 1-64 characters)
NSA$_DIRECTORY_ENTRY Directory entry associated with file system operation (Longword)
NSA$_DIRECTORY_ID Directory file identification (Array of 3 words)
NSA$_DIRECTORY_NAME Directory file name
NSA$_DISMOUNT_FLAGS The $DMTDEF macro in STARLET defines the dismount flags; each flag is one quadword.
NSA$_EFC_NAME Event flag cluster name (String of 1-16 characters)
NSA$_EVENT_FACILITY Facility code for the generated event (Word)
NSA$_FIELD_NAME Name of the field being modified. This is used in combination with NSA$_ORIGINAL_DATA and NSA$_NEW_DATA. (String of 1-256 characters)
NSA$_FILE_ID File identification (Array of words)
NSA$_FINAL_STATUS Status (successful or unsuccessful) causing the auditing facility to be invoked (Longword)
NSA$_HOLDER_NAME Name of user holding the identifier (String of 1-32 characters)
NSA$_HOLDER_OWNER Owner (UIC) of holder (Longword)
NSA$_ID_ATTRIBUTES Attributes of the identifier, which are defined by the $KGBDEF macro in STARLET (Longword)
NSA$_IDENTIFIERS_USED Identifiers (from the access control entry (ACE) granting access) used to gain access to the object (Array of longwords)
NSA$_ID_NAME Name of the identifier (String of 1-32 characters)
NSA$_ID_NEW_ATTRIBUTES New attributes of the identifier, which are defined by the $KGBDEF macro in STARLET (Longword)
NSA$_ID_NEW_NAME New name of the identifier (String of 1-32 characters)
NSA$_ID_NEW_VALUE New value of the identifier (Longword)
NSA$_ID_VALUE Value of the identifier (Longword)
NSA$_ID_VALUE_ASCII Identification value provided by $IDTOASC (Longword)
NSA$_IMAGE_NAME Name of the image being executed when the event took place (String of 1-1024 characters)
NSA$_INSTALL_FILE The name of the installed file (String of 1-255 characters)
NSA$_INSTALL_FLAGS The INSTALL flags correspond to qualifiers for the Install utility (for example, NSA$M_INS_EXECUTE_ONLY); each flag is one longword.
NSA$_LNM_PARENT_NAME Name of the parent logical name table (String of 1-31 characters)
NSA$_LNM_TABLE_NAME Name of the logical name table (String of 1-31 characters)
NSA$_LOCAL_USERNAME User name of the account available for incoming network proxy requests (String of 1-32 characters)
NSA$_LOGICAL_NAME Logical name associated with the device (String of 1-255 characters)
NSA$_MAILBOX_UNIT Mailbox unit number (Longword)
NSA$_MATCHING_ACE ACE granting or denying access (Array of bytes)
NSA$_MESSAGE Associated message code; see NSA$_MSGFILNAM for translation (Longword)
NSA$_MOUNT_FLAGS The MOUNT flags defined by the $MNTDEF macro in STARLET (Longword)
NSA$_MSGFILNAM Message file containing the translation for the message code in NSA$_MESSAGE (String of 1-255 characters)
NSA$_NEW_DATA Contents of the field named in NSA$_FIELD_NAME after the event occurred. NSA$_ORIGINAL_DATA contains the field contents prior to the event. (String of 1-n characters)
NSA$_NEW_IMAGE_NAME Name of the new image (String of 1-1024 characters)
NSA$_NEW_OWNER New process owner (UIC) (Longword)
NSA$_NEW_PRIORITY New process priority (Longword)
NSA$_NEW_PRIVILEGES New privileges (Quadword)
NSA$_NEW_PROCESS_ID New identification of the process (Longword)
NSA$_NEW_PROCESS_NAME New name of the process (String of 1-15 characters)
NSA$_NEW_PROCESS_OWNER New owner (UIC) of the process (Longword)
NSA$_NEW_USERNAME New user name (String of 1-32 characters)
NSA$_NOP Packet in static event list to omit from processing
NSA$_OBJECT_CLASS Object class name, as defined by the system or by the user (String of 1-23 characters)
NSA$_OBJECT_MAX_CLASS The minimum access classification of the object (20-byte record)
NSA$_OBJECT_MIN_CLASS The minimum access classification of the object (20-byte record)
NSA$_OBJECT_NAME Object's name (String of 1-255 characters)
NSA$_OBJECT_NAME_2 Alternate object name; currently applies to file-backed global sections where the alternate name of global section is the file name. (String of 1-255 characters)
NSA$_OBJECT_OWNER UIC or general identifier of the process causing the auditable event (Longword)
NSA$_OBJECT_PROTECTION UIC-based protection of the object (Vector of words or longwords)
NSA$_OBJECT_TYPE Object's type code, as listed in $ACLDEF. (String of 1-23 characters)
NSA$_OLD_PRIORITY Former process priority (Longword)
NSA$_OLD_PRIVILEGES Former privileges (Quadword)
NSA$_ORIGINAL_DATA Contents of the field named in NSA$_FIELD_NAME before the event occurred. NSA$_NEW_DATA contains the field contents following the event. (String of 1-n characters)
NSA$_PARAMS_INUSE Set of parameter values given to the SYSGEN command USE (String of 1-255 characters)
NSA$_PARAMS_WRITE File name for the SYSGEN command WRITE (String of 1-255 characters)
NSA$_PARENT_ID Process identifier (PID) of the parent process; only used when auditing events pertaining to a subprocess (Longword)
NSA$_PARENT_NAME Parent's process name; only used when auditing events pertaining to a subprocess (String of 1-15 characters)
NSA$_PARENT_OWNER Owner (UIC) of the parent process (Longword)
NSA$_PARENT_USERNAME User name associated with the parent process (String of 1-32 characters)
NSA$_PASSWORD Password used in unsuccessful break-in attempt (String of 1-32 characters)
NSA$_PRIVILEGES Privilege mask (Quadword)
NSA$_PRIVS_MISSING Privileges that are lacking (Longword or quadword)
NSA$_PRIVS_USED Privileges used to gain access to the object (Longword or quadword)
NSA$_PROCESS_ID PID of the process causing the auditable event (Longword)
NSA$_PROCESS_NAME Process' name that caused the auditable event (String of 1-15 characters)
NSA$_REM_ASSOCIATION_NAME Interprocess communication (IPC) remote association name (String of 1-256 characters)
NSA$_REMOTE_LINK_ID Remote logical link identification number (Longword)
NSA$_REMOTE_NODE_ID DECnet address of the remote process (Longword)
NSA$_REMOTE_NODENAME DECnet node name of the remote process (String of 1-6 characters)
NSA$_REMOTE_USERNAME User name of the remote process (String of 1-32 characters)
NSA$_REQUEST_NUMBER Request number associated with the system service call (Longword)
NSA$_RESOURCE_NAME Lock resource name (String of 1-32 characters)
NSA$_SECTION_NAME Global section name (String of 1-42 characters)
NSA$_SNAPSHOT_BOOTFILE The name of the snapshot boot file, the saved system image file from which the system just booted (String of 1-255 characters)
NSA$_SNAPSHOT_SAVE_FILNAM The name of the snapshot save file, which is the original location of the snapshot file at the time that the system was saved (String of 1-255 characters)
NSA$_SNAPSHOT_TIME The time the picture of the configuration was taken and saved in the snapshot boot file (Quadword)
NSA$_SOURCE_PROCESS_ID Identification of process originating the request (Longword)
NSA$_SUBJECT_CLASS The current access class of the process causing the auditable event (A 20-byte record)
NSA$_SUBJECT_OWNER Owner (UIC) of the process causing the event (Longword)
NSA$_SYSTEM_ID SCS identification of the cluster node where the event took place (SYSGEN parameter SCSSYSTEMID) (Longword)
NSA$_SYSTEM_NAME System Communication Services (SCS) node name where the event took place (SYSGEN parameter SCSNODE) (String of 1-6 characters)
NSA$_SYSTEM_SERVICE_NAME Name of the system service associated with the event (String of 1-256 characters)
NSA$_SYSTIM_NEW New system time (Quadword)
NSA$_SYSTIM_OLD Old system time (Quadword)
NSA$_TARGET_DEVICE_NAME Target device name (String of 1-64 characters)
NSA$_TARGET_PROCESS_CLASS The target process classification. (A 20-byte vector)
NSA$_TARGET_PROCESS_ID Target process identifier (PID) (Longword)
NSA$_TARGET_PROCESS_NAME Target process name (String of 1-64 characters)
NSA$_TARGET_PROCESS_OWNER Target process owner (UIC) (Longword)
NSA$_TARGET_USERNAME Target user name (String of 1-32 characters)
NSA$_TERMINAL Name of the terminal to which the process was connected when the auditable event occurred (String of 1-256 characters)
NSA$_TIME_STAMP The time that the event occurred (Quadword)
NSA$_TRANSPORT_NAME Name of transport: interprocess communication (IPC), DECnet, or System Management Integrator (SMI), which handles requests from the SYSMAN utility (String of 1-256 characters)
NSA$_UAF_ADD Name of the authorization record being added (String of 1-32 characters)
NSA$_UAF_COPY Original and new names of the authorization record being copied (String of 1-32 characters)
NSA$_UAF_DELETE Name of the authorization record being removed (String of 1-32 characters)
NSA$_UAF_FIELDS Fields being changed in an authorization record and their new values. This is reserved to HP. (Quadword bit mask)
NSA$_UAF_MODIFY Name of the authorization record being modified (String of 1-32 characters)
NSA$_UAF_RENAME Name of the authorization record being renamed (String of 1-32 characters)
NSA$_UAF_SOURCE User name of the source record for an Authorize utility (AUTHORIZE) copy operation (String of 1-32 characters)
NSA$_USERNAME User name of process causing the auditable event (String of 1-32 characters)
NSA$_VOLUME_NAME Volume name (String of 1-15 characters)
NSA$_VOLUME_SET_NAME Volume set name (String of 1-15 characters)


Previous Next Contents Index