HELPLIB.HLB  —  RUN
    Executes an image within the context of your process (see the
    Image subtopic).

    Creates a subprocess or a detached process to run an image and
    deletes the process when the image completes execution (see the
    Process subtopic).

1  –  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. See the OpenVMS User's
       Manual for additional information.

    Format

      RUN  filespec

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

1.2  –  Qualifier

1.2.1    /DEBUG

       /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, see the VSI
    OpenVMS Debugger Manual.

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

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

1.3  –  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

       OpenVMS I64 DEBUG64 Version V8.3-014

      %DEBUG-I-INITIAL, Language:IMACRO, Module: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.

2  –  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

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

2.2  –  Qualifiers

2.2.1    /ACCOUNTING

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

2.2.2    /AST_LIMIT

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

2.2.3    /AUTHORIZE

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

2.2.4    /BUFFER_LIMIT

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

2.2.5    /DELAY

       /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 described for
    entering delta times in the OpenVMS User's Manual or the online
    help topic Date.

    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.

2.2.6    /DETACHED

    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.

2.2.7    /DUMP

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

2.2.8    /ENQUEUE_LIMIT

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

2.2.9    /ERROR

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

2.2.10    /EXTENT

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

2.2.11    /FILE_LIMIT

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

2.2.12    /INPUT

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

2.2.13    /INTERVAL

       /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 described in the
    OpenVMS User's Manual or the online help topic Date.

    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.

2.2.14    /IO_BUFFERED

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

2.2.15    /IO_DIRECT

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

2.2.16    /JOB_TABLE_QUOTA

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

2.2.17    /KERNEL_THREAD_LIMIT

       /KERNEL_THREAD_LIMIT=n

    Sets the limit of the number of kernel threads that can be
    created in the new process. If the value specified is higher than
    the SYSGEN parameter MULTITHREAD, an error message is returned.
    Specifying the value 0 makes the process use the systemwide
    limit set by the MULTITHREAD parameter.

2.2.18    /MAILBOX

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

2.2.19    /MAXIMUM_WORKING_SET

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

2.2.20    /ON

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

2.2.21    /OUTPUT

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

2.2.22    /PAGE_FILE

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

2.2.23    /PRIORITY

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

    The default priority is that of the current process.

2.2.24    /PRIVILEGES

       /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, see the VSI 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.

2.2.25    /PROCESS_NAME

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

2.2.26    /QUEUE_LIMIT

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

2.2.27    /RESOURCE_WAIT

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

2.2.28    /SCHEDULE

       /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 given for
    entering absolute time values in the OpenVMS User's Manual or the
    online help topic Date.

2.2.29    /SERVICE_FAILURE

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

2.2.30    /SSLOG_ENABLE

       /SSLOG_ENABLE[=COUNT=n] [,FLAGS=[NO]ARG]

    Valid on Alpha and Integrity server systems only.

    Requires CMEXEC, CMKRNL, or SETPRV privilege to log argument
    values. The SYSGEN parameter SYSSER_LOGGING must be enabled or
    the command will fail.

    Creates a process with system service logging enabled.

    Keywords are as follows:

    Keyword        Explanation

    COUNT=n        Specifies how many P2-space buffers to log.
                   (Default: 2)

    FLAGS=[NO]ARG  Specifies whether or not service argument values
                   are to be logged. The default is ARG, which
                   requires privileges. If the value is ARG but you
                   lack privilege, no argument values are logged.

    When enabling SSLOG for a process, you can specify the number
    of buffers to be used for logging. Buffers are allocated in P2
    space and are charged against the process's paging file quota.
    Each buffer is 65,024(10) bytes or FE00(16) bytes. The buffer
    space remains allocated and the quota charged until the process
    is deleted.

    Before you delete the process, stop the logging and close the log
    file by executing the SET PROCESS/SSLOG=STATE=UNLOAD command. The
    log file does not close automatically.

    To analyze the log file, use the DCL command ANALYZE/SSLOG, which
    is described in online help and in the System Service Logging
    chapter of the VSI OpenVMS System Analysis Tools Manual.

2.2.31    /SUBPROCESS_LIMIT

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

2.2.32    /SWAPPING

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

2.2.33    /TIME_LIMIT

       /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
    described in the OpenVMS User's Manual or the online help topic
    Date.

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

2.2.35    /UIC

       /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 VSI OpenVMS Guide to
    System Security.

2.2.36    /WORKING_SET

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

2.3  –  Examples

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

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

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

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

    5.$ 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.
Close Help