Adds a new record to the automatic login facility (ALF) database. You can also create records for proxy accounts.

Requires read (R) and write (W) access to the SYSALF database (SYS$SYSTEM:SYSALF.DAT by default).

Format

ALF ADD device user

Parameters

device

Specifies the terminal name or port name that you want to assign to a user name. The parameter device must be a terminal name if you do not specify qualifiers on the command line, and can be either a logical name or an abbreviated device name. This parameter accepts a maximum of 63 characters, including devices for proxy accounts.

user

Specifies the user name of the account that you want to assign to a particular terminal or port.

Qualifiers

/TERMINAL (default)

Checks whether the device name you specified is a terminal on the target system. The parameter device can be a logical name or an abbreviated device name, which SYSMAN translates to a full device name.

/PORT

Checks whether the device name you specified is a valid port. If the port name contains special characters, such as a slash (/), or if it contains lowercase letters that you want to preserve, you must enclose the port name within quotation marks (" ").

Be aware that anything within quotation marks is written literally to the ALF database file. For example, if the actual port name contains uppercase letters as well as special characters, be sure to specify uppercase letters within the quotation marks. Otherwise, a mismatch will occur between the actual port name and what is specified in the SYSALF.DAT file.

/PROXY

Checks that the device name is in the NODE::USERNAME format.

/LOG

Displays the device names and user names as they are added to the ALF database.

Description

You can use the ALF ADD command to associate a terminal or port with a particular user name. This will enable certain users to log in to certain terminals or ports without specifying a user name.

The ALF ADD command adds a new record to the ALF database.

Examples

SYSMAN> ALF ADD TTA3 JBERGERON 
SYSMAN> ALF ADD "MN34C3/LC-1-2" FMARTIN /PORT 
 
      

In this example, the first command assigns terminal TTA3 to user JBERGERON. The second command assigns port MN34C3/LC-1-2 to user FMARTIN.

SYSMAN> ALF ADD VMS:.ZKO.VMSORG.SYSMAN.CLIENT1::SYSTEM FOOBAR
      

In this example, VMS:.ZKO.VMSORG.SYSMAN.CLIENT1::SYSTEM is the value for the device parameter, which is assigned to FOOBAR.

ALF REMOVE

Removes one or more records from the ALF database.

Requires read (R) and write (W) access to the SYSALF database (SYS$SYSTEM:SYSALF.DAT).

Format

ALF REMOVE device

Parameter

device

Specifies the terminal name or port name whose record you want to remove from ALF. The device name is required, even if you use qualifiers with the ALF REMOVE command.

You can use wildcard characters in the terminal name or port name. For example, if you specify the device TTA*, the system removes all records that start with the string TTA. The system does not, however, remove any records that start with the string <nodename>$TTA (where <nodename> is the system's SCSNODE name). To remove records starting with $, you would have to specify $TTA* or use two wildcards: *TTA*.

If you omit wildcard characters and enter a REMOVE command, SYSMAN attempts to match the device name exactly. If more than one record matches the criteria, SYSMAN displays an error message.

Qualifiers

/USERNAME=user

Enables you to remove a record in ALF for a specific user associated with a device. You must also enter the device when you use the /USERNAME qualifier. You can use wildcard characters with the /USERNAME qualifier.

/CONFIRM

Displays a message asking you to verify that you want to remove the record.

/LOG

Displays each device name and user name after it has been removed from the ALF database.

Description

The ALF REMOVE command removes one or more records from the ALF database.

Examples

SYSMAN> ALF REMOVE WORK1/USERNAME=*
      

The command in this example removes the records of the WORK1 device from the ALF datebase for all users. The asterisk (*) replaces user names.

SYSMAN> ALF REMOVE */USERNAME=*
      

The command in this example removes all records from the ALF database. The first asterisk (*) replaces device names; the second asterisk replaces user names.

SYSMAN> ALF REMOVE _TTA3:
SYSMAN> ALF REMOVE */USERNAME=SMITHSON
 
      

In this example, the first command removes the record for terminal TTA3. The second command removes all records (for all devices) assigned to user name SMITHSON.

SYSMAN> ALF REMOVE *TTA*
      

The command in this example removes all records for devices containing the string TTA.

SYSMAN> REMOVE TTA
      

This command produces the following error message:

%SYSMAN-E-ALFWILCRDREQ, more than one record might match - Wildcard or unit number of device required.

For example, the following command issued from a system running OpenVMS Version 6.1 or lower to a system running OpenVMS Version 6.2 produces no error messages and deletes all records that match FOOBAR$TTA:

SYSMAN> SET ENVIRONMENT/NODE=FOOBAR ! FOOBAR runs OpenVMS Version 6.2 %SYSMAN-I-ENV, current command environment: Individual nodes: FOOBAR Username SYSTEM will be used on nonlocal nodes SYSMAN> ALF REMOVE TTA ! Does not produce an error message SYSMAN>

If you issue the same command from a system running OpenVMS Version 6.1 or lower to another system running OpenVMS Version 6.1 or lower, it produces the following error message:

%SYSMAN-I-NODERR, error returned from node FOO -SMI-E-ALFNOMATCH, no records matched search criteria

This is due to incorrect processing of wildcards prior to OpenVMS Version 6.2.

ALF SHOW

Displays one or more records from the ALF database.

Requires read (R) and write (W) access to the SYSALF database (SYS$SYSTEM:SYSALF.DAT).

Format

ALF SHOW [device]

Parameter

[device]

Specifies the terminal name or port name whose record you want to display. You can use wildcard characters in the terminal name or port name. Certain restrictions in wildcard matching of ALF records exist, as shown in the examples section.

Qualifiers

/USERNAME=user

Displays the records held by the specified user. You can use wildcard characters with this qualifier.

/OUTPUT[=filespec]

Directs the output of the command to a file. If you do not include a file specification with this qualifier, SYSMAN writes the output to the file SYSMAN.LIS in your default directory.

Description

The ALF SHOW command displays one or more records in the ALF database.

Examples

SYSMAN> ALF SHOW TTA* /USERNAME=MANESS /OUTPUT=ALF.TXT 
 
      

In this example, the records for all terminals named TTAx that are assigned to user MANESS are selected and directed to the file ALF.TXT.

SYSMAN> ALF SHOW TTA*
      

This command displays only those records that start with the string TTA.

SYSMAN> ALF SHOW TTA
      

This command displays only those records that start with the string <nodename>$TTA.

SYSMAN> ALF SHOW *TTA
      

This command displays records that have device names ending with TTA.

SYSMAN> ALF SHOW *TTA*
      

This command displays all records that contain the string TTA.

Transfers control from your current process (which then hibernates) to the specified process in your job.

The ATTACH and SPAWN commands cannot be used if your terminal has an associated mailbox.

Format

ATTACH [process-name]

Parameter

process-name

Specifies the name of a parent process or a spawned subprocess to which control passes. The process must already exist, be part of your current job tree, and share the same input stream as your current process. However, the process cannot be your current process or a subprocess created with the /NOWAIT qualifier.

Process names can contain from 1 to 15 alphanumeric characters. If a connection to the specified process cannot be made, an error message is displayed.

Qualifier

/PARENT

Enables you to attach to the parent process. If no parent process exists, you receive an error message.

Description

The ATTACH command connects your input stream to another process. You can use the ATTACH command to change control from one subprocess to another subprocess or to the parent process.

When you enter the ATTACH command, the parent process goes into hibernation and your input stream connects to the specified destination process. You can use the ATTACH command to connect to a subprocess that is part of a current job (left hibernating as a result of the SPAWN/WAIT command or another ATTACH command) as long as the connection is valid. No connection can be made to the current process, to a process that is not part of the current job, or to a process that does not exist. If you attempt any of these connections, you receive an error message.

You can also use the ATTACH command in conjunction with the SPAWN/WAIT command to return to a parent process without terminating the created subprocess. See the description of the SPAWN command for more details.

Example

$ SPAWN
%DCL-S-SPAWNED, process SYSTEM_1 spawned
%DCL-S-ATTACHED, terminal now attached to process SYSTEM_1
$ RUN SYS$SYSTEM:SYSMAN
SYSMAN> ATTACH SYSTEM
%DCL-S-RETURNED, control returned to process SYSTEM
$
      

In this example, the SPAWN command creates a subprocess (SYSTEM_1). After you invoke SYSMAN and enter the ATTACH command, you transfer the terminal's control back to the parent process (SYSTEM).

The ADD command creates a new scheduling class.

The class scheduler provides the ability to limit the amount of CPU time that a system's users receive by placing users in scheduling classes. Each class is assigned a percentage of the overall system CPU time. As the system runs, the combined set of users in a class is limited to the percentage of CPU execution time allocated to their class.

Users might get some additional CPU time if the qualifier /WINDFALL is enabled for their scheduling class. Enabling the qualifier /WINDFALL allows the system to give a small amount of CPU time to a scheduling class when the scheduling class's allotted time has been depleted, but a free CPU is available.

Format

CLASS_SCHEDULE ADD class_name

Parameter

class_name

Specifies the name of the scheduling class. You must specify a class name with the ADD command. The maximum length for this name is 16 characters.

Qualifiers

/ACCOUNT

Specifies which user is part of this scheduling class. This is part of a user's SYSUAF record.

The syntax for this qualifier is as follows:

[/ACCOUNT = (name1, name2,...name"n")]

/CPULIMIT

Defines the maximum amount of CPU time that this scheduling class can receive for the specified days and hours. You must specify this qualifier when adding a class.

The syntax for this qualifier is as follows:

/CPULIMIT = ([primary], [h1-h2=time%],[h1=time%], [,...],[secondary],[h1-h2=time%],[h1=time%],[,...])

The h1-h2=time% syntax allows you to specify a range of hours followed by the maximum amount of CPU time (expressed as a percentage) to be associated with this set of hours. The first set of hours after the keyword PRIMARY specifies hours on primary days; the set of hours after the keyword SECONDARY specifies hours on secondary days. The hours are inclusive; if you class schedule a given hour, access extends to the end of that hour.

/PRIMEDAYS

Allows you to define which days are primary days and which days are secondary days.

The syntax for this qualifier is as follows:

[/PRIMEDAYS = ([no]day[,...])]

You specify primary days as MON, TUE, WED, THU, FRI, SAT, and SUN. You specify secondary days as NOMON, NOTUE, NOWED, NOTHU, NOFRI, NOSAT, and NOSUN.

The default is MON through FRI and NOSAT and NOSUN. Any days omitted from the list take their default value. You can use the DCL command, SET DAY, to override the class definition of primary and secondary days.

/UIC

Specifies which users are part of this scheduling class. This is part of a user's SYSUAF record.

The syntax for this qualifier is as follows:

[/UIC = (uic1,uic2,...uic"n")]

/USERNAME

Specifies which user is part of this scheduling class. This is part of a user's SYSUAF record.

The syntax for this qualifier is as follows:

[/USERNAME = (name1, name2,...name"n")]

/WINDFALL

Specifies that all processes in the scheduling class are eligible for windfall.

The syntax for this qualifier is as follows:

[/WINDFALL])

By enabling windfall, you allow processes in the scheduling class to receive a "windfall", that is, a small percentage of CPU time, when the class's allotted CPU time has been depleted, and a CPU is idle. Rather than let the CPU remain idle, you might decide that it is better to let these processes execute, even if it means giving them more than their alloted time.

The default value is for windfall to be disabled.

Description

The format for the CLASS_SCHEDULE ADD command is as follows:

SYSMAN> CLASS_SCHEDULE ADD class_name

You can use the /ACCOUNT, /UIC, or /USERNAME qualifier to specify which users are to be part of a scheduling class.

The Class Scheduler Database

The class scheduler database is a permanent database that allows OpenVMS to class schedule processes automatically after a system has been booted and rebooted. This database resides on the system disk in SYS$SYSTEM:VMS$CLASS_SCHEDULE.DATA. SYSMAN creates this file as an RMS indexed file when the first scheduling class is created with the SYSMAN command CLASS_SCHEDULE ADD.

You can have a common class scheduler database for all cluster nodes, or you can have a separate database for one node or for a small group of nodes. Using a common database can be helpful in simplifying system management. However, you must be aware of the issues raised in the following examples:

• Example 1
  Within a single database---common or separate---you can have only one set of parameters for each class. For example,

  SYSMAN> SET ENV/NODE=X SYSMAN> CLASS ADD class1 /USERNAME=(user1) /CPULIMIT=(0-2=100%,3-23=30%) SYSMAN> SET ENV/NODE=Y SYSMAN> CLASS ADD class1 /USERNAME=(user1) /CPULIMIT=(0-2=40%,3-23=20%)

  
  With a database that is common to both nodes X and Y, the second command produces an error because you have given the same class different parameters. With separate databases for nodes X and Y, the second command works.

• Example 2
  The system must also be able to assign a process to a unique class. You can specify the same user---or other identifying information---in several classes as long as you define these classes on separate nodes. For example:

  SYSMAN> SET ENV/NODE=X SYSMAN> CLASS ADD class1 /USERNAME=(user1) /CPULIMIT=(0-2=100%,3-23=30%) SYSMAN> SET ENV/NODE=Y SYSMAN> CLASS ADD class2 /USERNAME=(user1) /CPULIMIT=(0-2=40%,3-23=20%)

  
  This example works on a database that is common to both nodes X and Y because the two sets of parameters also have different class names. The system can determine the class for user1 by checking the node on which user1 is running.

• Example 3
  The following example is incorrect on both common and separate databases because the system cannot determine whether user1 is a member of class1 or class2, since they are both defined for NODE X.

  SYSMAN> SET ENV/NODE=X SYSMAN> CLASS ADD class1 /USERNAME=(user1) /CPULIMIT=(0-2=100%,3-23=30%) SYSMAN> CLASS ADD class2 /USERNAME=(user1) /CPULIMIT=(0-2=40%,3-23=20%)

• Example 4
  In addition to specifying nodes explicitly, as shown in the preceding examples, you can also specify that a class applies to the entire cluster. For example:

  SYSMAN> SET ENV /CLUSTER SYSMAN> CLASS ADD class1 /USERNAME=(user1) /CPULIMIT=(0-2=100%,3-23=30%)

  
  In this example, not only is class1 defined for all nodes in the cluster, but class1 will also be defined for any node that you might add to the cluster later---as long as the new node uses the same database.
  Note that if you define a class with the environment set to CLUSTER, the command SYSMAN> CLASS SHOW/FULL lists that class with the notation "Nodes: All Cluster Members," even if the database is not common to all cluster nodes. To prevent confusion, HP recommends using a common database.

Defining the Logical Name VMS$CLASS_SCHEDULE

If you wish to have a common class scheduler database on a cluster with different system disks, or if you want to have a separate database for each node on a cluster with a common system disk, on each node define the system logical name VMS$CLASS_SCHEDULE to point to the location of the database that you want that node to use. For example, in SYSTARTUP_VMS.COM, include the following command:

$ DEFINE/SYSTEM VMS$CLASS_SCHEDULE disk:[directory]VMS$CLASS_SCHEDULE.DATA

where:

disk:[directory] represents the disk and directory where you want the database file to reside.

The Class Scheduler Database and Process Creation

By using a permanent class scheduler, a process is placed in a scheduling class, if appropriate, at process creation time. When a new process is created, the system determines whether this process belongs to a scheduling class. To determine this, the system relies on data in the SYSUAF file. Because the Loginout image already has information about the process from this file, Loginout class-schedules the process if it determines that the process belongs to a scheduling class.

Two other types of processes to consider during process creation are subprocess and detached process:

• A subprocess becomes part of the same scheduling class as the parent process, even though the subprocess might not match the criteria of the class. That is, the subprocess's user and account name and/or UIC might not be part of the class's record.
• A detached process joins the same scheduling class as the process that creates it unless the detached process executes the LOGINOUT image (LOGINOUT.EXE) during process creation. If a detached process executes LOGINOUT, it joins a class if it matches the class criteria in the class scheduler database.

Although a process can join a scheduling class at process creation time, you can change or modify its scheduling class during runtime with the SET PROCESS/SCHEDULING_CLASS command.

Determining If a Process is Class-Scheduled

You can determine whether a process is class-scheduled by any of the following methods:

• Either of the following DCL commands:

  $ SHOW SYSTEM/SCHEDULING_CLASS $ SHOW SYSTEM/FULL

  
  For more information about the DCL command SHOW SYSTEM, see HP OpenVMS DCL Dictionary: N--Z.

• The SYS$GETJPI system service, using the JPI$_SCHED_CLASS_NAME item
  For more information about the SYS$GETJPI system service, see HP OpenVMS System Services Reference Manual: A--GETUAI.
• The AUTHORIZE utility
  When a new user is added to the SYSUAF file, or when a user's record is modified, AUTHORIZE searches the class scheduler database file to determine if this user is a member of a scheduling class. If it is, then AUTHORIZE displays the following message:

  UAF-I-INCLASS, user belongs to at least 1 selecting class

  
  For more information about the AUTHORIZE utility, see that chapter in this manual.