Updated: 11 December 1998

OpenVMS DCL Dictionary

Hibernation and Scheduled Wakeup Requests

Use the following qualifiers to schedule execution of the image:

• /DELAY
• /INTERVAL
• /SCHEDULE

If you specify any of these qualifiers, the RUN command creates the process and places it in hibernation. The process cannot execute the image until it is awakened. Time values specified with these three qualifiers control when the process is awakened to execute the specified image.

You can schedule wakeup requests for a specified delta time (/DELAY qualifier) or absolute time (/SCHEDULE qualifier). You can also schedule wakeup requests for recurrent intervals with the /INTERVAL qualifier. If you specify an interval time, the created process is awakened to execute the specified image at fixed time intervals. If the image terminates normally (for example, by a RET instruction), the process returns to a state of hibernation, awaiting the next scheduled wakeup time and user-mode exit handlers are not called. At the next wakeup time, the image is recalled at its entry point; the image is not reactivated. If the image terminates abnormally, or by an $EXIT command, or by a $FORCEX command, the process does not return to hibernation, further scheduling requests are terminated, user-mode exit handlers are called, the image exits, and the created process is deleted.

Use the /PROCESS_NAME qualifier to give the created process a name. You can use this process name in a subsequent STOP or CANCEL command. A STOP command terminates execution of the image in the process and causes the process to be deleted. The CANCEL command cancels wakeup requests that are scheduled but have not yet been delivered.

Qualifiers

/ACCOUNTING (default)

/NOACCOUNTING

Requires ACNT (accounting) privilege to use the /NOACCOUNTING qualifier.

The /NOACCOUNTING qualifier stops the current accounting file tracking the resources used by the created process.

The /ACCOUNTING qualifier (the default) has no effect.

/AST_LIMIT=quota

Specifies the maximum number of asynchronous system traps (ASTs) that the created process can have outstanding.

If you do specify an AST limit quota, the default quota established at system generation time is used. The minimum required for any process to execute is 2.

The AST limit quota is nondeductible.

/AUTHORIZE

/NOAUTHORIZE (default)

Requires IMPERSONATE privilege.

When the image to be executed is the system login image (LOGINOUT.EXE), this qualifier searches the user authorization file (UAF) to validate a detached process. The /NOAUTHORIZE qualifier creates a detached process that runs under the control of the command interpreter.

When you specify the /AUTHORIZE qualifier, quotas are derived from the user authorization file (UAF) record of the process' owner. Any qualifiers to the RUN command that specify other quotas are ignored in favor of the UAF quotas.

When you specify the /NOAUTHORIZE qualifier, quotas are derived from the system parameters that set process quota default limits (parameters prefixed with PQL_D).

Specify the /AUTHORIZE qualifier if you want the login image to check the UAF whenever a detached process is created. The process-permanent files specified by the /INPUT and /OUTPUT qualifiers are made available to the command interpreter for input and output.

/BUFFER_LIMIT=quota

Specifies the maximum amount of memory, in bytes, that the process can use for buffered I/O operations or for temporary mailbox creation.

If you do not specify a buffered I/O quota, the default value established at system generation time is used. The minimum amount required for any process to execute is 1024 bytes.

The buffer limit quota is pooled.

/DELAY=delta-time

Places the created process in hibernation and awakens it after a specified time interval.

Specify the delta time according to the rules for entering delta times given in the OpenVMS User's Manual or the online help topic DCL_Tips (subtopic Date_Time).

If you specify both the /DELAY and /INTERVAL qualifiers, the first wakeup request occurs at the time specified by the /DELAY qualifier. All subsequent wakeup requests occur at the interval specified by the /INTERVAL qualifier.

/DETACHED

/NODETACHED

Creates a detached process with the same user identification code (UIC) as the current process. (To create a detached process with a different UIC, use the /UIC qualifier.) By default, the created process is not a detached process.

By default, resource quotas for the detached process are limited by the quotas of the creator process (maximum) and the system parameters PQL_M* (minimum). The IMPERSONATE or CMKRNL privilege allows you to specify any quotas for the detached process that exceed the normal range. Unless you have the IMPERSONATE or CMKRNL privilege, the maximum number of detached processes that you can create is limited to the quota defined by MAX_DETACH in your UAF.

/DUMP

/NODUMP (default)

When an image terminates because of an unhandled error, the /DUMP qualifier causes the contents of the address space to be written to the file named image-name.DMP in the process's default device and directory. You can then use the Analyze/Process_Dump utility to analyze the dump.

/ENQUEUE_LIMIT=quota

Specifies the maximum number of locks that a process can have outstanding at any one time.

The default quota is that established at system generation time. The minimum required for any process to operate is 2.

/ERROR=filespec

Defines an equivalence name string of 1 to 63 alphanumeric characters for the logical device name SYS$ERROR. The logical name and equivalence name are placed in the process logical name table for the created process. (The /ERROR qualifier is ignored if you are running SYS$SYSTEM:LOGINOUT.)

/EXTENT=quota

Specifies the maximum size to which the image being executed in the process can increase its physical memory size.

The default quota is that established at system generation time. The minimum value required for any process to execute is 10 pages.

Specify the value of n as a number of 512-byte pagelets on Alpha or 512-byte pages on VAX. Note that the operating system rounds up this value to the nearest CPU-specific page so that actual amount of physical memory allowed may be larger than the specified amount on Alpha.

The extent quota is nondeductible.

/FILE_LIMIT=quota

Specifies the maximum number of files that a process can have open at any one time.

The default quota is the quota established at system generation time. The minimum amount required for any process to execute is 2.

The file limit quota is pooled.

/INPUT=filespec

Defines an equivalence name string of 1 to 63 characters for SYS$INPUT. The logical name and equivalence name are placed in the process logical name table for the created process.

/INTERVAL=delta-time

Requests that the created process be placed in hibernation and be awakened at regularly scheduled intervals.

Specify the delta time according to the rules given in the OpenVMS User's Manual or the online help topic DCL_Tips (subtopic Date_Time).

If you specify the /DELAY or the /SCHEDULE qualifier with the /INTERVAL qualifier, the first wakeup request occurs at the time specified by the /DELAY or the /SCHEDULE qualifier; all subsequent wakeup requests occur at intervals specified by the /INTERVAL qualifier. If you specify neither the /DELAY nor the /SCHEDULE qualifier with the /INTERVAL qualifier, the first wakeup request occurs immediately by default.

/IO_BUFFERED=quota

Specifies the maximum number of system-buffered I/O operations that the created process can have outstanding at any one time.

The default quota is the quota established at system generation time. The minimum required for any process to execute is 2.

The buffered I/O quota is nondeductible.

/IO_DIRECT=quota

Specifies the maximum number of direct I/O operations that the created process can have outstanding at any one time.

The default quota is the quota established at system generation time. The minimum required for any process to execute is 2.

The direct I/O quota is nondeductible.

/JOB_TABLE_QUOTA=quota

Allows you to specify a quota for a detached process's jobwide logical name table.

A value of 0 has a special meaning. It means that the table, for all practical purposes, has infinite quota because its quota is pooled with that of its parent table, the system directory table.

Note that the /JOB_TABLE_QUOTA qualifier is relevant only for detached processes. If the /JOB_TABLE_QUOTA qualifier is specified in a RUN command that results in the creation of a subprocess, it is ignored.

/MAILBOX=unit

Specifies the unit number of a mailbox to receive a termination message when the created process is deleted. If no mailbox is specified, the creating process receives no notification when the subprocess or detached process has been deleted.

/MAXIMUM_WORKING_SET=quota

Specifies the maximum size (up to 64K pages) to which the image being executed in the process can increase its working set size. An image can increase its working set size by calling the $ADJWSL (Adjust Working Set Limit) system service.

The default quota is the quota established at system generation time. The minimum value required for any process to execute is 10 pages.

The maximum working set quota is nondeductible.

/ON=node_name

Specifies an OpenVMS Cluster node on which a detached process is to be created. Quotas are determined by comparing the values you specify with the RUN command with the quotas of the creator process (maximum) and the PQL_M* system parameters on the target node (minimum). To specify quotas outside that range, you must have IMPERSONATE or CMKRNL privilege. Omitted quota values default to the values of the PQL_D* system parameters on the target node.

The qualifier value node_name is a 1- to 6-character string containing the SCS node name of the requested node.

For example, to create a process named BAR on node FOO that runs MY_PROG.EXE, enter the following command:

$ RUN $10$DKB100:[SMITH]MY_PROG.EXE /DETACH /ON="FOO"/PROCESS_NAME="BAR"

Note that the disk containing the image must be mounted on the specified node. Because the disk might not be mounted on the node on which the command is entered, the RUN command processor does not check whether the image exists. Consequently, the command can complete without error even though the created process aborts immediately because the image file cannot be found.

/OUTPUT=filespec

Defines an equivalence name string of 1 to 63 characters for the logical device name SYS$OUTPUT. Both the equivalence name and the logical name are placed in the process logical name table for the created process.

/PAGE_FILE=quota

Specifies the maximum number of pages that can be allocated in the paging file for the process. The paging file quota is the amount of secondary storage available during execution of the image.

The default quota is the quota established at system generation time. The minimum value required for a process to execute is 256 pages. The paging file quota is pooled.

/PRIORITY=n

Requires ALTPRI (alter priority) privilege to set the priority higher than your current process.

Specifies the base priority at which the created process executes.

On Alpha, the value of parameter n is a decimal 0 to 63, where 63 is the highest priority and zero is the lowest. Normal priorities range from 0 to 15; real-time priorities range from 16 to 63.

On VAX, the value of parameter n is a decimal 0 to 31, where 31 is the highest priority and zero is the lowest. Normal priorities range from 0 to 15; real-time priorities range from 16 to 31.

The default priority is that of the current process.

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

Requires SETPRV (set privilege) privilege to specify privileges that you do not have.

Defines user privileges for the created process. You can extend any privilege you possess to a process you create. By default, the created process has the same privileges as its creator. If you specify only one privilege, you can omit the parentheses.

For a list of process privileges, refer to the OpenVMS Guide to System Security.

You can also use the keyword NOSAME as the privilege parameter. If you specify /PRIVILEGES=NOSAME, the created process has no privileges.

/PROCESS_NAME=process-name

Specifies a name of 1 to 15 characters for the created process. The process name is implicitly qualified by the group number of the process's user identification code (UIC). By default, the name is null.

/QUEUE_LIMIT=quota

Specifies the maximum number of timer queue entries that the created process can have outstanding at any one time. This number includes timer requests and scheduled wakeup requests.

The default quota is the quota established at system generation time. A process does not require any timer queue quota in order to execute.

The timer queue entry quota is pooled.

/RESOURCE_WAIT (default)

/NORESOURCE_WAIT

Places the created process in a wait state when a resource required for a particular function is not available.

If you specify the /NORESOURCE_WAIT qualifier, the process receives an error status code when a resource is unavailable.

/SCHEDULE=absolute-time

Places the created process in hibernation and awakens it at the specified time.

Specify the absolute time value according to the rules for entering absolute time values given in the OpenVMS User's Manual or the online help topic DCL_Tips (subtopic Date_Time).

/SERVICE_FAILURE

/NOSERVICE_FAILURE (default)

Enables or disables an exception condition notification if an error occurs during a system service request. By default, an error status code is returned to the process.

If you specify the /SERVICE_FAILURE qualifier and an error occurs during a system service request, the process encounters an exception condition.

/SUBPROCESS_LIMIT=quota

Specifies the maximum number of subprocesses that the created process is allowed to create.

The default quota is the quota established at system generation time. A process does not require any subprocess quota in order to execute.

The subprocess limit quota is pooled.

/SWAPPING (default)

/NOSWAPPING

Requires PSWAPM (process swap mode) privilege to inhibit process swapping.

Permits the process to be swapped. The default allows a process to be swapped from the balance set in physical memory to allow other processes to execute.

With /NOSWAPPING in effect, the process is not swapped out of the balance set when it is in a wait state. By default, a process may be swapped out of the balance set whenever it is in a wait state.

/TIME_LIMIT=limit

Specifies the maximum amount of CPU time (in delta time) a created process can use. CPU time is allocated to the created process in units of 10 milliseconds. When it has exhausted its CPU time limit quota, the created process is deleted.

If this quota is not specified and the created process is a detached process, the detached process receives a default value of zero, that is, unlimited CPU time.

If this quota is not specified and the created process is a subprocess, the subprocess receives half the CPU time limit quota of the creating process.

If this quota is specified as zero, the created process has unlimited CPU time providing that the creating process also has unlimited CPU time. If, however, the creating process does not have unlimited CPU time, the created process receives half the CPU time limit quota of the creating process.

The CPU time limit quota is a consumable quota; that is, the amount of CPU time used by the created process is not returned to the creating process when the created process is deleted.

If you restrict CPU time for a process, specify the time limit according to the rules for specifying delta time values, as given in the OpenVMS User's Manual or the online help topic DCL_Tips (subtopic Date_Time).

/TRUSTED

Specifies that the created process is part of the Trusted Computing Base (TCB) and performs its own auditing. The /DETACH qualifier is required as well as the IMPERSONATE privilege.

/UIC=uic

Specifies that the created process be a detached process and assigns it a user identification code (UIC). Specify the UIC by using standard UIC format as described in the OpenVMS Guide to System Security.

/WORKING_SET=default

Specifies the number of pages in the working set of the created process.

The default working set size is the size established at system generation time. The minimum number of pages required for a process to execute is 10 pages. The value specified cannot be greater than the quota specified with /MAXIMUM_WORKING_SET.

The maximum working set quota is nondeductible.

Examples

$ RUN/PROCESS_NAME=SUBA   SCANLINE
%RUN-S-PROC_ID, identification of created process is 00010044.
 
      

In this example, the RUN command creates a subprocess named SUBA to run the image SCANLINE.EXE. The system gives the subprocess an identification number of 00010044.

$ RUN/DELAY=3:30/OUTPUT=BALANCE.OUT BALANCE
      

In this example, the RUN command creates a subprocess to run the image BALANCE.EXE 3 hours and 30 minutes from now; output is written to the file BALANCE.OUT.

$ RUN/INTERVAL=1:40/PROCESS_NAME=STAT   STATCHK
%RUN-S-PROC_ID, identification of created process is 00050023
   .
   .
   .
$ CANCEL STAT
 
      

In this example, the RUN command creates a subprocess named STAT to execute the image STATCHK.EXE. The process is scheduled to execute the image at intervals of 1 hour and 40 minutes. The process hibernates; however, because neither the /DELAY nor the /SCHEDULE qualifier is specified, the first wakeup request occurs immediately.

The CANCEL command subsequently cancels the wakeup requests posted by the /INTERVAL qualifier. If the process is currently executing the image, it completes the execution and hibernates.

$ RUN/PROCESS_NAME=LYRA  LYRA -
_$/OUTPUT=_TTB3: -
_$/ERROR=_TTB3:
%RUN-S-PROC_ID, identification of created process is 000A002F
 
      

In this example, the RUN command creates a subprocess named LYRA to execute the image LYRA.EXE. The /OUTPUT and /ERROR qualifiers assign equivalences to the logical names SYS$OUTPUT and SYS$ERROR for the subprocess. Any messages the subprocess writes to its default output devices are displayed on the terminal TTB3.

$ RUN/UIC=[100,4]/PRIVILEGES=(SAME,NOPSWAPM) -
_$/NORESOURCE_WAIT   OVERSEER
%RUN-S-PROC_ID, identification of created process is 0001002C
 
      

In this example, the RUN command creates a detached process to execute under the UIC [100,4]. The image OVERSEER.EXE is executed. The RUN command gives the process all the privileges of the current process, except the ability to alter its swap mode. The /NORESOURCE_WAIT qualifier disables resource wait mode for the process.

$ DEFINE/GROUP  TEST [MALCOLM.TESTFILES]
$ RUN/PROCESS=SUB  WATCH -
_$/INPUT=TEST:OUT1 -
_$/OUTPUT=F$LOGICAL("SYS$OUTPUT")
%RUN-S-PROC_ID, identification of created process is 0001002E
 
      

In this example, the DEFINE command creates an entry in the group logical name table for the logical name TEST. The RUN command creates a subprocess to execute the image WATCH.EXE.

The /INPUT qualifier defines SYS$INPUT for the subprocesses. The logical name TEST defines the directory for the file OUT1.DAT. Because the logical name TEST is in the group logical name table, the logical name can be translated and referred to by the image WATCH.EXE.

The /OUTPUT qualifier uses the lexical function F$LOGICAL to translate the logical name of the current process's SYS$OUTPUT device. The equivalence name string is equated to the device SYS$OUTPUT for the subprocess.

Invokes the DIGITAL Standard Runoff (DSR) text formatter to format one or more ASCII files. Creates formatted files from source DSR (.RNO) files, unformatted table of contents (.RNT) files, and unformatted index (.RNX) files. Optionally creates intermediate (.BRN) files for input to RUNOFF/CONTENTS and RUNOFF/INDEX commands.

For more information about the RUNOFF, RUNOFF/CONTENTS, and RUNOFF/INDEX commands and for a description of the DSR formatter, refer to the OpenVMS User's Manual and the OpenVMS DIGITAL Standard Runoff Reference Manual or online help.

Format

RUNOFF filespec[,...]

Searches one or more files for the specified strings and displays the lines containing those strings.

Format

SEARCH filespec[,...] search-string[,...]

Parameters

filespec[,...]

Specifies one or more files to be searched. You must specify at least one file name. If you specify more than one file name, separate the file specifications with commas (,).

You can use the asterisk (*) and the percent sign (%) wildcard characters in the file specification.

search-string[,...]

Specifies the character string to be located in the specified files. Enclose strings containing lowercase letters, blanks, or other nonalphanumeric characters (including spaces) in quotation marks (" ").

You can use the /MATCH and /EXACT qualifiers to alter the way that SEARCH matches search strings.

Description

The SEARCH command searches through files for specific character strings; all lines containing occurrences of the strings are displayed. Use the SEARCH qualifiers to tailor the search operation to your specific needs.

The SEARCH command opens the file with shared read (R) and write (W) access. Therefore, any file that has its attributes set to shared write is searched even if it is currently opened by other users.

Qualifiers

/BACKUP

Modifies the time value specified with the /BEFORE or the /SINCE qualifier. The /BACKUP qualifier selects files according to the dates of their most recent backups. This qualifier is incompatible with the /CREATED, /EXPIRED, and /MODIFIED qualifiers, which also allow you to select files according to time attributes. If you specify none of these four time qualifiers, the default is the /CREATED qualifier.

/BEFORE[=time]

Selects only those files dated prior to the specified time. You can specify time as absolute time, as a combination of absolute and delta times, or as one of the following keywords: BOOT, LOGIN, TODAY (default), TOMORROW, or YESTERDAY. Specify one of the following qualifiers with the /BEFORE qualifier to indicate the time attribute to be used as the basis for selection: /BACKUP, /CREATED (default), /EXPIRED, or /MODIFIED.

For complete information on specifying time values, see the OpenVMS User's Manual or the online help topic DCL_Tips (subtopic Date_Time).

/BY_OWNER[=uic]

Selects only those files whose owner user identification code (UIC) matches the specified owner UIC. The default UIC is that of the current process.

Specify the UIC by using standard UIC format as described in the OpenVMS User's Manual.

/CONFIRM

/NOCONFIRM (default)

Controls whether a request is issued before each search operation to confirm that the operation should be performed on that file. The following responses are valid:

YES	NO	QUIT
TRUE	FALSE	Ctrl/Z
1	0	ALL
	[Return]

You can use any combination of uppercase and lowercase letters for word responses. Word responses can be abbreviated to one or more letters (for example, T, TR, or TRU for TRUE), but these abbreviations must be unique. Affirmative answers are YES, TRUE, and 1. Negative answers include: NO, FALSE, 0, and pressing the Return key. Entering QUIT or pressing Ctrl/Z indicates that you want to stop processing the command at that point. When you respond by entering ALL, the command continues to process, but no further prompts are given. If you type a response other than one of those in the list, DCL issues an error message and redisplays the prompt.

/CREATED (default)

Modifies the time value specified with the /BEFORE or the /SINCE qualifier. The /CREATED qualifier selects files based on their dates of creation. This qualifier is incompatible with the /BACKUP, /EXPIRED, and /MODIFIED qualifiers, which also allow you to select files according to time attributes. If you specify none of these four time qualifiers, the default is the /CREATED qualifier.

/EXACT

/NOEXACT (default)

Controls whether the SEARCH command matches the search string exactly or treats uppercase and lowercase letters as equivalents. By default, SEARCH ignores case differences in letters.

Specifying the /EXACT qualifier causes the system to use less CPU time. Therefore, if you are sure of the case of the letters in the string, it is more efficient to use the /EXACT qualifier.

/EXCLUDE=(filespec[,...])

Excludes the specified files from the search operation. You can include a directory but not a device in the file specification. The asterisk (*) and the percent sign (%) wildcard characters are allowed in the file specification. However, you cannot use relative version numbers to exclude a specific version. If you specify only one file, you can omit the parentheses.

/EXPIRED

Modifies the time value specified with the /BEFORE or the /SINCE qualifier. The /EXPIRED qualifier selects files according to their expiration dates. (The expiration date is set with the SET FILE/EXPIRATION_DATE command.) The /EXPIRED qualifier is incompatible with the /BACKUP, /CREATED, and /MODIFIED qualifiers, which also allow you to select files according to time attributes. If you specify none of these four time qualifiers, the default is the /CREATED qualifier.

/FORMAT=option

Formats output in one of the following five ways:

DUMP	Displays all control characters (including <HT>, <CR>, and <LF>) and nonprintable characters as ANSI mnemonics.
NOFF	Replaces control characters in text with ANSI mnemonics (for example, Ctrl/C is replaced with <ETX>). The terminal formatting characters <HT>, <CR>, <LF>, <VT> are passed without change. Form feed characters are replaced with <FF>.
NONULLS	Same as DUMP, but removes all null characters from the input file before reformatting. (In dump mode, the null character is displayed as <NUL>.) NONULLS is convenient when you are searching binary format files, such as EXE or OBJ files, that generally contain many zero bytes.
PASSALL	Moves control and nonprintable characters to the output device without translating them. The terminal driver cannot send 8-bit characters to the terminal unless SET TERMINAL/EIGHT_BIT is already in effect. You can use /FORMAT=PASSALL whenever you do not want the SEARCH command to substitute the ANSI mnemonic for control characters (for example, <BEL> for Ctrl/G).
TEXT	Replaces control characters in text with ANSI mnemonics (for example, Ctrl/C is replaced with <ETX>). The terminal formatting characters <HT>, <CR>, <LF>, <VT>, and <FF> are passed without change. TEXT is the default format.

/HEADING (default)

/NOHEADING

Includes file names in the output file and displays a line of 30 asterisks(*) as a window separator between groups of lines that belong to different files. With the default heading format, file names are printed only when more than one file is specified or when the asterisk (*) and the percent sign (%) wildcard characters are used.

---

Previous

Next

Contents

Index

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

9996PRO_044.HTML