A run file specifies a process to be spawned, and how it is to be spawned. It describes three things:
Initially, the set of command line arguments, the library path prefix, and the library path suffix are empty; and the set of environment strings is a copy of the current environment of the process doing the spawning. The run file specifies modifications to this initial state, which are applied in the order that they appear in the file. The process is spawned after the entire run file has been processed, and the handle to the file has been closed. Run files are opened for parsing in deny write mode.
A run file is a text file comprising a series of directives, one per line, plus blank lines and comments. A line whose first non-whitespace character is a colon is a comment, and the remainder of the line is ignored.
Variable substitution is performed in certain directives, allowing the use of environment variables to parameterise directives. Certain implicit variables are defined, which provide useful automatically generated default values for some environment variables.
A run file directive comprises a keyword, possibly followed by data. The following directives are defined:
The environment is cleared. All environment strings are deleted. This directive is used if one doesn't want the spawned process to inherit any of the spawning process' environment.
A string with the name name and the value value is added to the environment, replacing any environment string of the same name if one is already present. To include whitespace or quotation marks in value, it must be surrounded by quotation marks. Literal quotation marks must then be escaped by prepending a backslash in front of them.
Variable substitution is applied to value. This allows environment variables to be set in terms of other, already existing, environment variables, for example.
Examples:
setenv COMSPEC "%APPS%\JdeBP\CMD\Bin\Cmd.EXE" setenv IU_MAILTO_INIT "/trigger:\\SEM32\\IU\\SMTP\\PD /QUEUE:%_BOOT%:\Public\Maildrop"
The string with the name name is removed from the environment. This allows strings to be selectively removed from the environment.
A string with the name name and the value value is added to the environment, if such a string does not exist. If it does exist, then value is prepended to the existing string, inserting a semi-colon (';') between the prior content and the value being prepended.
Examples:
prependpath PATH "%APPS%\JdeBP\IU\Bin" prependpath DPATH "%APPS%\JdeBP\IU\Data"
A string with the name name and the value value is added to the environment, if such a string does not exist. If it does exist, then value is apppended to the existing string, inserting a semi-colon (';') between the prior content and the value being apppended.
The name of the executable program file that is to form the process' image is set to filename. No error will be generated if this directive occurs more than once in the file, although because later occurrences override earlier ones only the final occurrence will actually matter.
Variable substitution is applied to filename.
Examples:
PROGRAM %COMSPEC% PROGRAM %APPS%\JdeBP\IU\Bin\DNSRCPD.EXE
The string string is appended to the set of command lines that are passed to the process. By convention, the first such string, argument string number 0, is the name of the program under which it is being invoked. (Forgetting to specify this first argument is a common error.)
The programs in the Internet Utilities, the 32-bit Command Interpreter, and the the OS/2 Command Line Utilities version 2.2. can all accept and will process multiple argument strings. However, most other OS/2 programs only process the second argument string in the list, argument string number 1, and ignore all of the others. For such programs, the entire command tail must be specified as a single argument.
For example:
PROGRAM %COMSPEC% ARGUMENT CMD ARGUMENT /C DEL /S C:\TEMP\*
Variable substitution is applied to string.
Examples:
PROGRAM %APPS%\JdeBP\CLU\Bin\XDIR.EXE ARGUMENT XDIR ARGUMENT %HOME%\ ARGUMENT %USERPROFILE%\
If the program being invoked is one that performs its own environment variable substitution on its arguments, as the command interpreter does, variable substitution will occur twice. Variable substitition can be deferred until the second time, the variable substitution performed by the command being run, by doubling the percent characters in the string.
The service process is started such that it inherits directory as its current working directory. No error will be generated if this directive occurs more than once in the file, although because later occurrences override earlier ones only the final occurrence will actually matter.
Variable substitution is applied to directory.
The service process is started such that it inherits path as its library path prefix. No error will be generated if this directive occurs more than once in the file, although because later occurrences override earlier ones only the final occurrence will actually matter.
Variable substitution is applied to path.
The service process is started such that it inherits path as its library path suffix. No error will be generated if this directive occurs more than once in the file, although because later occurrences override earlier ones only the final occurrence will actually matter.
Variable substitution is applied to path.
Variable substitution replaces all occurences of a name preceded by a percent, '%', character with a value.
Normally, the name ends with a second percent character, and is the name
of an environment variable. As in the variable substitution done by the
command interpreter, environment variable names may contain spaces and
other punctuation characters. The second percent character is required in
order to mark the end of the variable name. For example, in
argument %A %B %C %D
the environment variable names are "A " and "C ". In this
example "B " and "D " are in fact simply literal text that is
passed on to the directive unchanged.
The value used to replace the name is that of the environment variable.
For example, in
setenv OLD_PATH %PATH%
the value used by the SETENV directive will actually be the value of the
PATH environment variable at the time that variable substitution occurred.
Note: Environment variable names are case-sensitive.
If an environment variable of the given name does not exist, then if the
name is that of an
implicit variable
the value of that implicit variable is substituted. For example, in
argument %_DATE%
the value of the _DATE implicit variable will be used, unless an explicit
environment variable called "_DATE" exists (which is not usually the case
in most system configurations).
Otherwise if no environment variable of the given name exists, and no
implicit variable of the given name exists, no substitution occurs and the
text is left unchanged in its original form (including both of the percent
characters). For example, in
argument %NO_SUCH_VARIABLE%
the value of the argument, assuming that no environment variable with the
name "NO_SUCH_VARIABLE" exists, will be the literal text
"%NO_SUCH_VARIABLE%".
Certain special expansion sequences do not end with a percent character, and override normal environment variable substitution.
A percent character followed immediately by a decimal number indicates a
parameter replacement. For example, the directive
argument %1 %2
will, after expansion, result in the values of the first and second
replacement parameters being applied as arguments to the program being
run.
The following sequences are also special and override normal environment variable substitution. They are replaced with the given values:
If an environment variable of a given name does not exist, some environment variables have what are, in effect, default, implicit, values, as follows:
Note: The implicit variables that relate to the date and time default to using the current local time and the local timezone. For correct operation, the hardware real-time clock must be set to TAI (or UTC as a close aproxmation thereto) and the TZ environment variable must be properly set. (This may come as a surprise to people who have not shed this particular piece of DOS Think. See how 32-bit OS/2 was actually originally designed to keep time.