Document revision date: 30 March 2001

## OpenVMS DCL Dictionary

Previous | Contents | Index

## RUN (Image)

> Executes an image within the context of your process. You can abbreviate the RUN command to a single letter, R.

> Note If you are invoking an image that requires one or more parameters, you must use the Automatic Foreign Command format or the Foreign Command format. Refer to the OpenVMS User's Manual for additional information.

### Format

> RUN filespec

### Parameter

> #### filespec

> Specifies an executable image to be executed. The file type defaults to .EXE. The asterisk (*) and the percent sign (%) wildcard characters are not allowed.

### Description

> This command executes an image within the context of your process. You can abbreviate the RUN command to a single letter, R.

> When working with installed images, if you specify an image name in the command line with an explicit version number (or a semicolon), the image runs with current process privileges. If you do not specify an explicit version number (or semicolon), the image runs with any privileges with which it was installed. Refer to the OpenVMS System Management Utilities Reference Manual: A--L for more information about the Install utility.

> If you invoke an image locally, you must have read (R) or execute (E) access to the image. If you have DECnet software installed and want to execute an image over the network, you must have read (R) access to the image.

> If you are invoking an image that requires one or more parameters, you must use the Automatic Foreign Command format or the Foreign Command format. For additional information, see the string assignment statement (:=) in the OpenVMS DCL Dictionary: A--M, and refer to the OpenVMS User's Manual.

### Qualifier

> #### /DEBUG

> #### /NODEBUG

> Executes the image under control of the debugger. The default is the /DEBUG qualifier if the image is linked with the /DEBUG qualifier and the /NODEBUG qualifier if the image is linked without the /DEBUG qualifier. The /DEBUG qualifier is invalid if the image is linked with the /NOTRACEBACK qualifier. The /NODEBUG qualifier overrides the effect of the LINK/DEBUG command. If the image was linked with the /TRACEBACK qualifier, traceback reporting is performed when an error occurs.

> If the image was not linked with the debugger, you can specify the /DEBUG qualifier to request the debugger at execution time; however, if the /NOTRACEBACK qualifier was specified when the image was linked, the /DEBUG qualifier is invalid.

> For a complete description of the OpenVMS Debugger, refer to the OpenVMS Debugger Manual.

> To get help on debugger commands from the DCL level, type the following command:

>     $ HELP/LIBRARY=SYS$HELP:DBG$HELP DEBUG

###

#### Examples

#1
    $ RUN LIBRA

> The image LIBRA.EXE starts executing in the process. If the image LIBRA has been installed with amplified privileges, it runs with those privileges because you have not explicitly specified a version number or a semicolon. Alternatively, the image LIBRA.EXE still runs with its amplified privileges, if you enter the RUN command as follows:

>     $ RUN LIBRA.EXE

#2
    $ MACRO/ENABLE=DEBUG ORION
    $ LINK/DEBUG ORION
    $ RUN ORION

         VAX DEBUG Version 5.4

    %DEBUG-I-INITIAL, language is MACRO, module set to 'ORION'
    DBG>
       .
       .
       .
    $ RUN/NODEBUG ORION

> A program is compiled, linked, and run with the debugger. Subsequently, a RUN/NODEBUG command requests that the debugger, which is present in the image, not issue a prompt. If an error occurs while the image executes, the debugger can perform traceback and report on the error.

#3
    $ RUN AQUARIUS.EXE;1

> The image AQUARIUS.EXE starts executing in the process. If the image AQUARIUS.EXE has been installed with amplified privileges, it does not run with those privileges because you have specified a version number. Instead, the image runs with current process privileges only. When you specify a version number (or even just a semicolon), the image activator does not search its list of special images that have been installed with privileges. The process AQUARIUS still runs with only normal process privileges if you enter the RUN command as follows:

>     $ RUN AQUARIUS.EXE;

> In this case, however, the highest version of the image AQUARIUS runs.

## RUN (Process)

> Creates a subprocess or a detached process to run an image and deletes the process when the image completes execution. A subprocess is created if any of the qualifiers except the /UIC or the /DETACHED qualifier is specified. A detached process is created if the /UIC or the /DETACHED qualifier is specified and you have the IMPERSONATE user privilege.

### Format

> RUN filespec

### Parameter

> #### filespec

> Specifies the file name of an executable image to be executed in a separate process. The default file type is .EXE. The asterisk (*) and the percent sign (%) wildcard characters are not allowed in the file specification.

### Description

> The RUN command creates a process to execute the specified image. If you specify the /UIC or the /DETACHED qualifier, the RUN command creates a detached process; otherwise, the RUN command creates a subprocess.

> When you specify any qualifiers with the RUN command, the RUN command creates a process and displays the process identification (PID) code in SYS$OUTPUT. The newly created process executes the image named in the file specification. When the image has finished executing, the system deletes the process that was running that image.

> By default, the RUN command creates a subprocess with the same user identification code (UIC), current disk and directory defaults, privileges, and priority as the current process.

> If the detached process terminates unexpectedly and you want to find out why, you can use the Accounting utility to display the final exit status of the process. For more information, see the OpenVMS System Management Utilities Reference Manual.

> Both the /DETACHED and the /UIC qualifiers request the RUN command to create a detached process. You must have the user privilege IMPERSONATE or CMKRNL to create a detached process with a different UIC. When you create a detached process, the resource quotas are established as follows:

> - If you do not specify a value for a particular quota, that quota is given the value of the corresponding PQL_D* (default) system parameter.
> - If you specify a value for a particular quota, that value is compared with the quotas for the creator process (maximum) and the system parameters PQL_M* (minimum). If the value you specify is within the allowed range, it is used for the new process. If you specify a value greater than the creator process's quota, the creator process's quota is used. If the specified value is less than the corresponding system parameter, the system parameter value is substituted.

> However, if you have the IMPERSONATE or CMKRNL privilege, you can specify any quotas for the detached process.

> Input, Output, and Error Streams

> Use the following qualifiers to assign equivalence names for the logical names SYS$INPUT, SYS$OUTPUT, and SYS$ERROR for the process:

> > /INPUT
> > /OUTPUT
> > /ERROR

> The equivalence names you specify for these process-permanent files are interpreted within the context of the process you are creating. For example, file type defaults, and logical name use and translation are image- and language-dependent.

> Defining Process Attributes

> Use the following qualifiers to override the default attributes for a process:

> > /ACCOUNTING
> > /DUMP
> > /PRIORITY
> > /PRIVILEGES
> > /PROCESS_NAME
> > /SERVICE_FAILURE
> > /SWAPPING

> Assigning Resource Quotas

> When you enter a RUN command to create a process, you can define quotas to restrict the amount of various system resources available to the process. The following resource quota is deductible when you create a subprocess; that is, the value you specify is subtracted from your current quota and given to the subprocess:

> Qualifier | Quota
> --- | ---
> /TIME_LIMIT | CPUTIME

> The quota amount is returned to your current process when the subprocess is deleted.

> The system defines minimum values for each specifiable quota. If you specify a quota that is below the minimum, or if you specify a deductible quota that reduces your current quota below the minimum, the RUN command cannot create the process. To determine your current quotas, enter the SHOW PROCESS/QUOTAS command.

> You can also specify limits for nondeductible quotas. Nondeductible quotas are established and maintained separately for each process and subprocess. The following qualifiers specify nondeductible quotas:

> Qualifier | Quota
> --- | ---
> /AST_LIMIT | ASTLM
> /EXTENT | WSEXTENT
> /IO_BUFFERED | BIOLM
> /IO_DIRECT | DIOLM
> /MAXIMUM_WORKING_SET | WSQUOTA
> /WORKING_SET | WSDEFAULT

> A third type of quota treatment is pooling. Pooled quotas are established when a detached process is created. They are shared by that process and all its descendent subprocesses. Charges against pooled quota values are subtracted from the current available totals as they are used and are added back to the total when they are not being used. The following qualifiers specify pooled quotas:

> Qualifier | Quota
> --- | ---
> /BUFFER_LIMIT | BYTLM
> /ENQUEUE_LIMIT | ENQLM
> /FILE_LIMIT | FILLM
> /PAGE_FILE | PGFLQUOTA
> /QUEUE_LIMIT | TQELM
> /SUBPROCESS_LIMIT | PRCLM

> 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.

> Previous | Next | Contents | Index

> | privacy and legal statement |
> 9996PRO_046.HTML