HP OpenVMS systems documentation

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, refer to that chapter in this manual.

The DELETE subcommand deletes a scheduling class from the class scheduler database file.

Format

CLASS_SCHEDULE DELETE class_name

Parameter

class_name

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

Qualifiers

None.

The MODIFY subcommand changes the characteristics of a scheduling class.

Format

CLASS_SCHEDULE MODIFY class_name

Parameter

class_name

Specifies the name of the scheduling class. You must specify a class name with the MODIFY 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

To remove a time restriction, specify a zero (0) for the time percentage associated with a particular range of hours.

To remove a name or uic value, you must specify a minus sign in front of each name or value.

The RESUME subcommand complements the suspend command. You use this command to resume a scheduling class that is currently suspended.

Format

CLASS_SCHEDULE RESUME class_name

Parameter

class_name

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

Qualifiers

None.

The SHOW subcommand displays the characteristics of a scheduling class.

Format

CLASS_SCHEDULE SHOW [class_name] [/qualifier]

Parameter

class_name

Specifies the name of the scheduling class. You must specify a class name or the /ALL qualifier with the SHOW command. The maximum length for the class name is 16 characters.

Qualifiers

/ALL

Displays all scheduling classes. The qualifier must be specified if no class name is given.

/FULL

Displays all information about this scheduling class.

Description

By default, a limited display of data is shown by the SHOW subcommand. The default displays the following:

• Name
• Maximum CPU time or times for each range of hours
• Primary days and secondary days
• Windfall settings

The SUSPEND subcommand suspends the specified scheduling class.

Format

CLASS_SCHEDULE SUSPEND class_name

Parameter

class_name

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

Qualifiers

None.

Description

When you suspend a scheduling class, all processes that are part of the scheduling class remain as part of the class but are granted unlimited CPU time.