1 RUN Executes an image within the context of your process (see Image). If you are invoking an image requiring one or more parameters, you must use the Automatic Foreign Command format or the Foreign Command format. Creates a subprocess or a detached process to run an image and deletes the process when the image completes execution (see Process). 2 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 3 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. 3 Qualifier /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, 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 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 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. 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 3 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. 3 Qualifiers /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. /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. /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. /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. /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 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 /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 /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 /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 /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 /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 /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 /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 /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 /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 /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 /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 /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 /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 /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 /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 /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 /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 /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=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 /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 /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 /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 /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 /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 /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 /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=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 /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. 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. Status: 200 OK Content-Type: text/plain; charset=ISO-8859-1 Last-Modified: Sat, 03 May 2014 07:56:20 GMT Script-Control: X-stream-mode=1 1 RUNOFF Invokes the DIGITAL Standard Runoff (DSR) text formatter to format one or more ASCII files (see file). Invokes the DIGITAL Standard Runoff (DSR) Table of Contents utility to create an .RNT file that can be processed by DSR to make a table of contents (see /CONTENTS). Invokes the DIGITAL Standard Runoff (DSR) Indexing utility to create an .RNX file that can be processed by DSR to create an index (see /INDEX). 2 file 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. The RUNOFF command allows you to do the following: o Adjust the amount of text on a page. o Control the position of text on a page. o Control underlining, overwriting, and bolding of text. o Override some DSR commands and flags in your input file. o Process all or part of your input file. o Create an intermediate file for indexes or tables of contents. For a complete description of the DSR formatter, including more information about the RUNOFF command, refer to the OpenVMS DIGITAL Standard Runoff Reference Manual. Format RUNOFF filespec[,...] 3 Parameter filespec[,...] Specifies one or more ASCII files (containing text and DSR commands) to be formatted by the RUNOFF command. The input file type defaults to .RNO; you must specify the file type for .RNT and .RNX files. Wildcard characters are not allowed in the file specification. DSR produces an output file having the same file name as the input file. The output file type depends on the input file type. The default output file type is .MEM. For a list of input file types and the associated output file types, refer to the OpenVMS DIGITAL Standard Runoff Reference Manual. Specify SYS$INPUT to type the input from your terminal or a command procedure; terminate input from the terminal by pressing Ctrl/Z. 3 Qualifiers /BACKSPACE Positional qualifier. Controls whether DSR uses the ASCII backspace character to perform character-by-character overprinting. By default, DSR performs line-by-line overprinting. /BOLD /BOLD[=n] /NOBOLD Positional qualifier. Specifies the number of times characters are overstruck in a bolding operation. You can specify the number of times DSR overprints flagged text by stating a value for n. The value n must be 0 or a positive integer and defaults to 1. A specification of /BOLD=0 or /NOBOLD disables all boldface printing, even if the appropriate flags are recognized and enabled. /CHANGE_BARS /CHANGE_BARS[=character] /NOCHANGE_BARS Positional qualifier. Controls whether DSR generates change bars in the formatted file. The default change bar character is the vertical bar (|). The change bars appear 3 spaces to the left of the lines of text that you have marked for change bars. For information on the .BEGIN BAR and .END BAR commands, enter HELP DSR at the DCL prompt. You can replace the default change bar character by supplying a substitute character for the /CHANGE_BARS[=character] qualifier. You must specify the replacement character as either a character enclosed in quotation marks (" ") or as an octal, decimal, or hexadecimal value for the desired character. The /CHANGE_BARS qualifier without a value uses the default change bar character (|). The /NOCHANGE_BARS qualifier overrides any change bar commands in the input file and disables the output of change bars. /DEBUG /DEBUG[=(option[,...])] /NODEBUG (default) Positional qualifier. Traces certain operations by placing the DSR commands in the output file. You can specify the following options: o ALL Specifies all five options (CONDITIONALS, CONTENTS, FILES, INDEX, and SAVE_RESTORE). o CONDITIONALS Causes DSR to ignore all conditional processing commands (.IF, .IFNOT, .ELSE, .ENDIF) in the input file. DSR includes both true and false conditional information in the output file along with formatted text. For further details on the .IF, .IFNOT, .ELSE, .ENDIF, and .VARIABLE commands and the /VARIANT qualifier, enter HELP DSR at the DCL prompt. o CONTENTS Causes DSR to output all .SEND TOC commands along with the text being sent to the table of contents. o FILES Causes DSR to output all .REQUIRE commands as well as the text of the require files. o INDEX Causes DSR to output the indexing commands, .INDEX and .ENTRY, in addition to the text to which they refer. o SAVE_RESTORE Causes DSR to output all .SAVE and .RESTORE commands. If you specify only one option, you can omit the parentheses. If you specify /DEBUG without specifying any options, ALL is assumed. /DEVICE /DEVICE=(option[,...]) Positional qualifier. Controls whether DSR generates an output file (.LNI) that is suitable for printing on an LN01, an LN01E, or an LN03 laser printer. If you do not get the output that you expect when you print an .LNI file on an LN01 or an LN01E printer, check with your system manager. The OpenVMS DIGITAL Standard Runoff Reference Manual contains information for system managers about setting LN01 and LN01E laser printers to print .LNI files. You can choose options from the following list to indicate output device, page orientation, and type of emphasis for flagged characters in your .LNI file: o LN01 Produces an output file suitable for printing on an LN01 laser printer; the default paper size is 8 1/2 by 11 inches; the default mode is PORTRAIT. The output file name is the same as the input file name; the default file type is .LNI. This option is incompatible with the LN01E option. o LN01E Produces an output file suitable for printing on an LN01E laser printer using the standard European paper size (A4). The output file name is the same as the input file name. The default file type is .LNI; the default mode is PORTRAIT. This option is incompatible with the LN01 option. o LN03 Produces an output file suitable for printing on an LN03 laser printer; the default paper size is 8 1/2 by 11 inches. The output file name is the same as the input file name. The default file type is .LNI; the default mode is PORTRAIT. o LANDSCAPE Causes the appropriate fonts for landscape mode to be loaded into an LN01 printer; pages are printed with the long dimension at the top and use a smaller type size. (The page is 11 inches wide and 8 1/2 inches long.) Allowable page dimensions are 0 to 73 lines per page and 0 to 132 characters per line. This option is incompatible with the PORTRAIT option. o PORTRAIT (default) Causes the appropriate fonts for portrait mode to be loaded into an LN01 printer; pages are printed with the short dimension at the top and use a larger type size. (The page is 8 1/2 inches wide and 11 inches long.) Allowable page dimensions are 0 to 66 lines per page and 0 to 80 characters per line. This option is incompatible with the LANDSCAPE option. PORTRAIT mode is the default when you specify /DEVICE=LN01, /DEVICE=LN01E, or /DEVICE=LN03. o ITALIC (default) Causes the italic and bold-italic fonts to be loaded into an LN01 printer, and makes characters flagged for underlining appear in italic type. Italicized characters can also appear in boldface type, depending on the type of emphasis you specify in your input file. The LN03 printer requires no loading of fonts, because default fonts are present. Text flagged for emphasis is printed in italic type if the current font has the ITALIC attribute; otherwise the flagged text is underlined. o UNDERLINE Causes the text and bold fonts to be loaded into an LN01 printer, and underlines characters flagged for underlining. The LN01 printer allows only 63 consecutive characters (counting a space as a character) to be underlined per line. If you want to underline individual words and not the spaces between them, you will be able to underline only 63 words per line. This option is incompatible with the ITALIC option. DSR does not report an error if the user exceeds this limit of the hardware. On an LN03 printer, the flagged text is underlined if you have specified the UNDERLINE option. The printer does not default to italic even if the current font has the ITALIC attribute. /DOWN /DOWN[=n] /NODOWN (default) Positional qualifier. Controls whether DSR inserts a specified number of blank lines at the top of each page. These blank lines precede any header information. The number of blank lines you specify (n) does not affect the number of text lines on a page. For example, if you specify /DOWN=10 with a .PAGE SIZE of 58 lines, up to 58 lines of text will be output after 10 blank lines. If you specify the /DOWN qualifier without a value, five blank lines are inserted. If you specify /DOWN=0 or omit the qualifier, no blank lines are inserted, except those associated with the print device or header layout. /FORM_SIZE /FORM_SIZE=n Specifies the maximum number of lines per page including running heads and running feet. Defaults to /FORM_SIZE=66, which is standard for 11-inch paper. For laser printers, set the number of lines as follows: Paper Size Lines Mode 8.05 69 Landscape 8.28 71 Landscape (LN01E default) 8.51 73 Landscape (LN01, LN03 default) 11.00 66 Portrait (LN01, LN03 default) 11.66 70 Portrait (LN01E default) 12.33 74 Portrait 13.00 78 Portrait 14.00 84 Portrait When used with the /SIMULATE qualifier, the /FORM_SIZE qualifier controls the physical size of the page by putting out line feeds to match the number specified by the value n. When used with the /NOSIMULATE qualifier, the /FORM_SIZE=n qualifier causes DSR to suppress the form feed that DSR would normally insert at the line number specified by the value n. If the number of lines that DSR is going to put on any given page does not match the value n, a form-feed character is written into the output file. The default value for the value n is derived from the OpenVMS Run-Time Library (RTL) routine LIB$LP_LINES. This defaults to 66 unless the logical SYS$LP_LINES is defined, in which case the assigned value is used. To change the default value, specify a different value for the /FORM_SIZE=n qualifier. /INTERMEDIATE /INTERMEDIATE[=filespec] /NOINTERMEDIATE (default) Positional qualifier. Controls whether DSR generates an intermediate output file that can be used as input to the DSR table of contents utility and the DSR indexing utility. For more information on producing tables of contents and indexes, see the descriptions of the /CONTENTS and /INDEX qualifiers. If you specify the /INTERMEDIATE qualifier, DSR creates an output file that has the same file name as the input file and a file type of .BRN. To rename the output file, supply a file specification that is different from the default values. /LOG /LOG /NOLOG (default) Controls whether a termination message is displayed at the terminal after successful completion of the DSR operation. The message states the DSR version number, the number of diagnostic messages (if any), the number of output pages, and the output file specification. If you specify the /INTERMEDIATE qualifier, the message also includes the number of index records produced and the number of table of contents records produced. If there are errors in processing, DSR displays a message on the terminal even if the /NOLOG qualifier is specified. /MESSAGES /MESSAGES=(option[,...]) Positional qualifier. Specifies the destination of all DSR error messages. To indicate a specific destination, use one or both of the following options: OUTPUT Messages are sent to the output .MEM file. USER Messages are displayed on the terminal (SYS$ERROR). If you specify both options, separate them with commas and enclose the list in parentheses. The default, /MESSAGES=(OUTPUT,USER), sends messages to the output .MEM file and displays them on the terminal. /OUTPUT /OUTPUT[=filespec] /NOOUTPUT Positional qualifier. Specifies that an output file is to be produced and optionally names it. If you specify the /OUTPUT qualifier without a file specification, or if you omit the qualifier, the directory and file name default to that of the DSR file. If you specify the /NOOUTPUT qualifier, no output file is produced. The output file type depends on the input file type. The default input file type is .RNO and the default output file type is .MEM. The file type defaults to one of the following: Output Input File file .BLB .RNB .CCO .RNC .DOC .RND .ERR .RNE .HLP .RNH .LNI .RNO with /DEVICE set to LN01, LN01E, or LN03 .MAN .RNM .MEC .RNT .MEM .RNO with no /DEVICE qualifier specification .MEX .RNX .OPR .RNP .PLM .RNL .STD .RNS For a complete list of input file types and the associated output file types, refer to the OpenVMS DIGITAL Standard Runoff Reference Manual. To change the name of the output file, supply a file specification for the value filespec. The /OUTPUT=SYS$OUTPUT qualifier causes output to be sent to the terminal rather than to a disk file. You can use the value SYS$OUTPUT when you are logged in to a hardcopy terminal device that uses a daisy wheel. The /NOOUTPUT qualifier suppresses the creation of an output file. Using the /NOOUTPUT qualifier with the /INTERMEDIATE qualifier causes DSR to produce only an intermediate .BRN file and not a formatted output file. You can also use the /NOOUTPUT qualifier to check an input file for errors without using system resources to generate a formatted output file. /PAGES /PAGES=string Positional qualifier. Specifies that only the pages within the specified range be generated as output. By default, DSR generates output for all pages. Specify the range as follows: start-page-number:end-page-number,... You can specify up to five ranges (for example, /PAGES="2-9:2-12, 4-1:4-10, 5-9:5-9, A-1:A-3, and Index-1:Index-5"). You can omit the colon (:) and the end page number on the last range. You can omit the quotation marks (" ") if you specify only one range. Page numbers must be specified in their default form, not the form specified in a .DISPLAY command. You can specify just the appendix letter or name to produce an entire appendix. You can specify just the word INDEX to produce an entire index. If you specify only a starting page number, output begins at the specified page and continues to the end of the file. To output a single page, the start range and end range must be the same (for example, /PAGES=5:5). For an entire appendix, only a letter is required (for example, /PAGES=A). For an entire index, only the word INDEX is required (/PAGES=INDEX). You can refer to specific appendix or index pages with a numeric suffix such as INDEX-10. Note that the /PAGES qualifier does not recognize any display modes. You must specify the default form of page numbers (5-15) rather than any special form you may have specified with the .DISPLAY NUMBER command (for example, V-15). For details on the .DISPLAY NUMBER command, enter HELP DSR at the DCL prompt. /PAUSE /PAUSE /NOPAUSE (default) Controls whether DSR pauses after printing each page of output. You can use the /PAUSE qualifier to insert single sheets of paper or reproduction masters into hardcopy output devices. When output is halted, the terminal bell rings to remind you to insert a new form. Press the space bar to resume processing. Do not use this qualifier in a batch job. /REVERSE_EMPHASIS Positional qualifier. Directs DSR to change the order in which flagged text is underlined on an output device. If you use this qualifier, the printer first prints the characters to be underlined, then issues a carriage return without a line feed, and finally prints the underscores to underline the flagged text. If you view your file on the terminal, the flagged text is overwritten by the underline character. /RIGHT /RIGHT[=n] /NORIGHT (default except for LN01) Positional qualifier. Causes the text on each page (including header information) to be shifted to the right the number of columns specified by n. This qualifier does not affect the page width. If you specify the /RIGHT qualifier without specifying a number, text is shifted five spaces to the right. If you specify a value of zero or omit the qualifier, no shift occurs. The defaults (if the /RIGHT qualifier is not specified) for LN01 files are as follows: Mode LN01 LN01E LN03 Landscape 9 13 9 Portrait 2 2 2 /SEPARATE_UNDERLINE /SEPARATE_UNDERLINE[="character"] Positional qualifier. Prints underlines as separate characters on the next line instead of overstriking with underscores on the same line. The value specifies the character to be used for the underline character and defaults to a hyphen (-). You can specify the underline character as a single printable character or as a number preceded by a radix indicator (%D, %O, or %X) to represent the ASCII value of a printable or nonprintable character. This qualifier is incompatible with the /[NO]UNDERLINE_CHARACTER qualifier. /SEQUENCE /SEQUENCE /NOSEQUENCE (default) Positional qualifier. Controls whether DSR precedes the lines in the output file with the line numbers of the corresponding lines in the DSR file. For editors that generate line numbers in the input file, the /SEQUENCE qualifier causes similar numbering to appear in the output file. The line numbers appear in the left margin at the beginning of each line of output. If the text editor does not generate sequential numbers in the input file, sequential numbers are still generated in the output file, but without leading zeros. /SIMULATE /SIMULATE /NOSIMULATE (default) Controls whether DSR uses line feeds or form feeds to advance to the top of each page. For devices that do not have a form-feed capability, use the /SIMULATE qualifier to generate enough blank lines to cause a skip to the top of each new page. The /SIMULATE qualifier also causes a pause before the first page of output. To continue after the pause, press the space bar. /UNDERLINE_CHARACTER /UNDERLINE_CHARACTER[="character"] /NOUNDERLINE_CHARACTER Positional qualifier. Specifies the character to be used for the underline character. Defaults to an underscore (_). You can specify the underline character as a single printable character (enclosed in quotation marks) or as a number preceded by a radix indicator (%D, %O, or %X) to represent the ASCII value of a printable or nonprintable character. A specification of /NOUNDERLINE_CHARACTER overrides any .ENABLE UNDERLINING command in the DSR file. This qualifier is incompatible with the /SEPARATE_UNDERLINE qualifier. /VARIANT /VARIANT="string[,...]" Positional qualifier. Controls the processing of the conditional commands (.IF, .IFNOT, .ELSE, and .ENDIF) by specifying the names of the segments to be processed. For descriptions of the conditional commands, enter HELP DSR at the DCL prompt. You must name conditional structures introduced by the .IF command to process them. You must name conditional structures introduced by the .IFNOT command to exclude them. You must not name conditional structures introduced by the .ELSE command to process them. If you specify only one name in a string, you can omit the quotation marks (" "). 3 Examples 1.$ RUNOFF CHAPT1.RNO The RUNOFF command in this example takes the input file, CHAPT1.RNO, and writes formatted output to the file CHAPT1.MEM. 2.$ RUNOFF CHAPT1/RIGHT=10,CHAPT2 The RUNOFF command in this example produces a CHAPT1.MEM file with margins 10 spaces to the right of the margins specified in the input file CHAPT1.RNO. It also generates a CHAPT2.MEM file whose margins are not affected by the /RIGHT=10 qualifier. 3.$ RUNOFF/OUTPUT=SYS$OUTPUT TEXT.DAT,INTRO The RUNOFF command in this example sends output to the terminal rather than to a disk file. The qualifier applies to both the input files, TEXT.DAT and INTRO.RNO. 4.$ RUNOFF/NOOUTPUT/INTERMEDIATE - _$CHAPT1,CHAPT2,CHAPT3,CHAPT4,CHAPT5/LOG The RUNOFF command in this example generates intermediate .BRN files for each of the input files. The .BRN files are used as input for the DSR table of contents utility, and for the DSR indexing utility. The /NOOUTPUT qualifier suppresses the generation of formatted text files for each input file. The /LOG qualifier produces a termination message after DSR processes each file. 2 /CONTENTS Invokes the DIGITAL Standard Runoff (DSR) Table of Contents utility to create an .RNT file that can be processed by DSR to make a table of contents. The input file for this command is an intermediate binary file (.BRN) that is produced with the RUNOFF command and the /INTERMEDIATE qualifier. Qualifiers to this command allow you to specify the following characteristics for table of contents entries: o Using boldface type or underlining for entries o Deepest header level to be included o Running page numbers or chapter-oriented page numbers o Displaying or not displaying section numbers For a complete description of the DSR Table of Contents utility, see the OpenVMS DIGITAL Standard Runoff Reference Manual. Format RUNOFF/CONTENTS filespec[,...] or filespec[+...] 3 Parameter filespec[,...] or filespec[+...] Specifies one or more intermediate binary files (.BRN) that contain information (chapter titles, header levels, sections, and so on) for making a table of contents. To create a .BRN file, use the RUNOFF command with the /INTERMEDIATE qualifier. See the RUNOFF command for more information on the /INTERMEDIATE qualifier. If you omit the input file type, the DSR Table of Contents utility uses a default file type of .BRN. The RUNOFF/CONTENTS command also processes BTC files that the previous version of DSR produced. For single input files, the DSR Table of Contents utility produces an output file with the same file name as the input file. The output file type is .RNT. If you separate multiple input files with commas (,), separate .RNT files for each input file are created. If you separate multiple input files with plus signs (+), a single .RNT file that contains table of contents information for all of the input files is created. The default output file name is the same as the first input file name; the default file type is .RNT. Wildcard characters are not allowed in the file specification. 3 Qualifiers /BOLD /BOLD /NOBOLD (default) Controls whether the boldface type specified in chapter and header titles in the input file appears in the table of contents. If you specify the /BOLD qualifier, the text flagged for boldface type in the body of the document is marked for overprinting in the finished table of contents. If you specify the /NOBOLD qualifier, the text flagged for boldface type in the document is not overprinted in the table of contents. /DEEPEST_HEADER /DEEPEST_HEADER=n Controls how many levels of header levels are output in the table of contents. You can specify any number of header levels (up to six) to be displayed by changing the value of n. The default is /DEEPEST_HEADER=6. /IDENTIFICATION /IDENTIFICATION /NOIDENTIFICATION (default) Controls whether the current version number of the DSR table of contents utility is reported. /INDENT /INDENT /NOINDENT (default) Controls how many spaces the header levels after level 1 are indented in the table of contents. If you omit this qualifier, or if you specify the /NOINDENT qualifier, all header levels after header level 1 are indented 2 spaces. If you specify the /INDENT qualifier, each header level after header level 1 is indented 2 spaces beyond the preceding header level. /LOG /LOG /NOLOG (default) Controls whether the DSR Table of Contents utility displays the name of each input file as it is processed and after it is processed. The name of each output file created may also be displayed. If there are any errors in processing, the DSR Table of Contents utility sends messages to the terminal even if the /NOLOG qualifier is in effect. /OUTPUT /OUTPUT[=filespec] /NOOUTPUT Specifies that an output file is to be produced and optionally names it. If you specify the /OUTPUT qualifier without a file specification, or if you omit the qualifier entirely, the output file name matches the input file name. The default file type is .RNT. You can change the name of the output file by supplying a file specification for the value filespec. The /NOOUTPUT qualifier suppresses the creation of an output file. You can use the /NOOUTPUT qualifier to check an input file for errors without using system resources to generate an output file. /PAGE_NUMBERS /PAGE_NUMBERS=(option[,...]) Controls whether the page number references in the table of contents are running page numbers or chapter-oriented page numbers; also controls how many levels of headers have page references listed in the table of contents. You can specify the following options: o LEVEL=n Specifies that header levels up to and including header level n have page numbers listed in the table of contents. The default is to display page numbers for six levels of headers. o NORUNNING Specifies chapter-oriented page numbers (such as 1-3, 10-42). You can specify chapter-oriented numbers for the table of contents even if the document does not have chapter-oriented numbers. NORUNNING is the default. o RUNNING Specifies running page numbers (such as 3, 42). You can specify running page numbers for the table of contents even if the document does not have running page numbers. If you supply more than one option, separate them with commas and enclose the list in parentheses. /REQUIRE /REQUIRE=filespec /NOREQUIRE (default) Allows you to change or delete the heading on the first page of a table of contents. The default heading is the word CONTENTS centered on the page and followed by one blank line. You can either substitute another word as a heading, or have no heading. To change the heading, do one of the following: o If you do not want any heading, specify a null file as the file specification for /REQUIRE. $ RUNOFF/CONTENTS/REQUIRE=nl: o If you want to use a different heading, create or edit a file that specifies the heading that you want. Use the file that you create as the file specification for the /REQUIRE qualifier. When you use the /REQUIRE qualifier, the default heading for the first page of the contents is not generated. The file that you are "requiring" must provide the heading. The file can contain both DSR commands that change the format of the first page and the text that you want to appear at the top of the page. Or the file can contain only DSR commands to format the first page of the contents. For example, you can put the command .FIGURE 10 in the file. This command generates 10 blank lines at the top of the first page of the table of contents. You can use these blank lines for later pasteup. /SECTION_NUMBERS /SECTION_NUMBERS (default) /NOSECTION_NUMBERS Controls whether the DSR Table of Contents utility displays section numbers in the table of contents. The /SECTION_NUMBERS qualifier displays section numbers for all header levels in the table of contents. The /NOSECTION_NUMBERS qualifier suppresses the display of section numbers for all header levels. /UNDERLINE /UNDERLINE /NOUNDERLINE (default) Controls whether the underlining specified in chapter and header titles in the input file appears in the table of contents. If you specify the /UNDERLINE qualifier, the text flagged for underlining in the body of the document is underlined in the table of contents. If you specify the /NOUNDERLINE qualifier, the text flagged for underlining in the body of the document is not underlined in the table of contents. 3 Examples 1.$ RUNOFF/INTERMEDIATE CHPT1,CHPT2,CHPT3 Before using the RUNOFF/CONTENTS command, you must use the RUNOFF/INTERMEDIATE command to create a .BRN file as input for the DSR Table of Contents utility. The command line in this example creates three separate files: CHPT1.BRN, CHPT2.BRN, and CHPT3.BRN. 2.$ RUNOFF/CONTENTS CHPT1.BRN In this example, the RUNOFF/CONTENTS command takes the file CHPT1.BRN as input and creates CHPT1.RNT, which can be processed by DSR to produce a final table of contents for Chapter 1. 3.$ RUNOFF/CONTENTS/INDENT/NOSECTION_NUMBERS CHPT2 The command in this example takes the file CHPT2.BRN as input and creates CHPT2.RNT. When processed with the RUNOFF command, the .RNT file will produce a table of contents in which each header level after header level 1 is indented 2 spaces beyond the preceding header level. The table of contents will not have section numbers listed. See the following example for a sample command line for processing .RNT files. 4.$ RUNOFF/LOG CHPT2.RNT The command in this example produces CHPT2.MEC, which is a formatted table of contents. You can use the TYPE or the PRINT command to view the table of contents. 2 /INDEX Invokes the DIGITAL Standard Runoff (DSR) Indexing utility to create an .RNX file that can be processed by DSR to create an index. The input file for this command is an intermediate binary file (.BRN) that is produced with the RUNOFF command and the /INTERMEDIATE qualifier (see the RUNOFF command). For a complete description of the DSR Indexing utility, refer to the OpenVMS DIGITAL Standard Runoff Reference Manual. The formatted index is a 2-column index with balanced columns on each page. This index can be used for draft copies or for final production. Qualifiers to this command allow you to specify the following characteristics for index entries: o Running page numbers or chapter-oriented page numbers o The number of lines of index entries per page o Special text and heading on the first page of the index Format RUNOFF/INDEX filespec[,...] or filespec[+...] 3 Parameter filespec[,...] or filespec[+...] Specifies one or more intermediate binary files (.BRN) that contain information (index entries, page number references, and so on) for making an index. To create a .BRN file, use the RUNOFF command with the /INTERMEDIATE qualifier. See the RUNOFF command for more information on the /INTERMEDIATE qualifier. If you omit the input file type, the DSR Indexing utility uses a default file type of .BRN. The RUNOFF/INDEX command also processes .BIX files that the previous version of DSR produced. For single input files, the DSR Indexing utility produces an output file with the same file name as the input file. The output file type is .RNX. If you separate multiple input files with commas (,), separate .RNX files for each input file are created. If you separate multiple input files with plus signs (+), a single .RNX file that contains indexing information for all of the input files is created. The default output file name is the same as the first input file name; the default file type is .RNX. Wildcard characters are not allowed in the file specification. 3 Qualifiers /IDENTIFICATION /IDENTIFICATION /NOIDENTIFICATION (default) Reports the current version number of the DSR Indexing utility. /LINES_PER_PAGE /LINES_PER_PAGE=n Specifies, with the value n, the number of lines of index entries on each page of the finished index. This number does not include the number of lines required for running heads and feet. The default is 55 lines. This value is designed to work properly in the default formatting environment of DSR. You must calculate the value n if you change the default environment in any of the following ways: o If you use subtitles in the document that requires the .RNX file. o If you make the page length for the document anything other than 58 lines per page. o If you use any .LAYOUT command other than zero. To calculate the correct value for the /LINES_PER_PAGE qualifier, use the following formula: /LINES_PER_PAGE=n n = .PAGE SIZE ( the first parameter is length value) minus 4 if subtitles are used, minus 3 if no subtitles minus the number of lines reserved for .LAYOUT 1, .LAYOUT 2, or .LAYOUT 3. /LOG /LOG /NOLOG (default) Controls whether the DSR Indexing utility displays the name of each input file as it is processed and after it is processed, as well as the name of each output file created. If there are any errors in processing, the RUNOFF/INDEX command sends messages to the terminal even if the /NOLOG qualifier is in effect. /OUTPUT /OUTPUT[=filespec] /NOOUTPUT Specifies that an output file is to be produced and optionally names it. If you specify the /OUTPUT qualifier without a file specification, or if you omit the qualifier entirely, the output file name matches the input file name. The default file type is .RNX. You can change the name of the output file by supplying a file specification for the value filespec. The /NOOUTPUT qualifier suppresses the creation of an output file. You can use the /NOOUTPUT qualifier to check an input file for errors without using system resources to generate an output file. /PAGE_NUMBERS /PAGE_NUMBERS=option Controls whether the page number references in the index are running page numbers or chapter-oriented page numbers. To specify the type of page numbers you want, select from the following options: Option Purpose NORUNNING Specifies chapter-oriented page numbers (such as 1- 3, 10-42). You can specify chapter-oriented numbers for an index even if they do not appear in the document. The NORUNNING option is the default. RUNNING Specifies running page numbers (such as 1, 50, 230). You can specify running page numbers for an index even if the document does not display running page numbers. /REQUIRE /REQUIRE=filespec /NOREQUIRE (default) Allows you to change the heading on the first page of an index. The default heading is the word INDEX centered on the page and followed by three blank lines. The substitute heading is contained in the file you specify, which can contain DSR commands and text. To change the heading: 1. Create or edit a file that specifies the format and the text that you want as the heading on the first index page. 2. Use the file you create as the filespec parameter for the /REQUIRE qualifier. When you use the /REQUIRE qualifier, the default heading for the first page of the index is not generated. Your file must provide the heading. The file can contain DSR commands and text that you want to appear at the top of the first page of the index, or it can contain only DSR commands. For example, you can put the DSR command .FIGURE 10 in the file. This command generates 10 lines of white space at the top of the first page of the index. You can use these blank lines for later pasteup. For a sample file that changes the index heading, refer to the OpenVMS DIGITAL Standard Runoff Reference Manual. If you are adding lines of text or white space to the heading on the first page of the index, you must allow space for this addition. Use the /RESERVE=n qualifier to provide the space you need. See the /RESERVE qualifier for more information. /RESERVE /RESERVE=n /NORESERVE (default) Allows you to reserve space at the top of the first page of the index for text or white space that you want to include with the /REQUIRE=filespec qualifier. Determine how many lines of text or white space you are adding to the top of the first page of the index. Use this number as the value n for the /RESERVE qualifier. 3 Examples 1.$ RUNOFF/INTERMEDIATE CHPT1,CHPT2,CHPT3 Before using the RUNOFF/INDEX command, you must create a .BRN file as input for the DSR Indexing utility. The command in this example creates three separate files: CHPT1.BRN, CHPT2.BRN, and CHPT3.BRN. 2.$ RUNOFF/INDEX CHPT1.BRN In this example, the RUNOFF/INDEX command takes the file CHPT1.BRN as input and creates CHPT1.RNX, which can be processed by DSR to produce an index for Chapter 1. 3.$ RUNOFF/INDEX/LINE_PER_PAGE=52 CHPT2 In this example, the RUNOFF/INDEX command takes the file CHPT2.BRN as input and creates CHPT2.RNX. The .RNX file produces an index with 52 lines of index entries per page. The lines per page had to be adjusted because the writer used a page layout with the page numbers centered at the bottom of the page (.LAYOUT 1, .LAYOUT 2, .LAYOUT 3). This page layout takes up three more spaces than .LAYOUT 0, which is the default for DSR. To produce the final index, you must use the .RNX file as input to DSR. See the following example. 4.$ RUNOFF CHPT2.RNX In this example, the RUNOFF command produces CHPT2.MEX, which is a formatted index. You can type or print this file to view the index.