The JOB command initiates another GT.M process that executes the named routine.
$ZJOB is set to the pid of the process created by the JOB command. For more details, refer to “$ZJob”.
The format of the JOB command is:
J[OB][:tvexpr] entryref[(expr[,...])] [:[(keyword[=value][:...])][:numexpr]][,...]
The optional truth-valued expression immediately following the command is a command postconditional that controls whether or not GT.M executes the command.
The required entryref specifies a location at which the new process starts.
The optional parameter list enclosed in parentheses () contains parameters to pass to the routine entry point.
If the JOB specifies a parameter list, the entryref location must start with a label and a formallist. M prohibits entryrefs with offsets during parameter passing.
The optional elements in the parameter list specify expressions that the JOB evaluates and passes as values; because the JOB command creates a new process, its arguments cannot specify pass-by-reference.
The keywords specify optional processparameters that control aspects of the environment for the new process.
If the JOB command has only one processparameter, the surrounding parentheses are optional.
Some keywords take numeric or string literals delimited by an equal sign (=) as arguments. Because the values are constants, strings must be enclosed in quotation marks (" "), and variable arguments require that the entire argument be constructed and referenced using indirection.
The optional numeric expression specifies a time in seconds after which the command should timeout if unsuccessful; 0 results in a single attempt.
When a JOB command contains no processparameters, double colons (::) separate the time-out numeric expression from the entryref.
An indirection operator and an expression atom, evaluating to a list of one or more JOB command arguments, form a legal argument for a JOB command.
The maximum command-line length for a JOB command is 8192 bytes.
If the parent process is operating in UTF-8 mode, the JOB'd process also operates in UTF-8 mode.
If your background process must have a different mode from its parent, then create a shell script to alter the environment as needed, and spawn it with a ZSYstem command using ZSYstem "/path/to/shell/script &".
The operating system deletes the resultant process when execution of its GT.M process is complete. The resultant process executes asynchrounously with the current process. Once GT.M starts the resultant process, the current process continues.
If a JOB command specifies a timeout, and GT.M creates the resultant process before the timeout elapses, JOB sets $TEST to true (1). If GT.M cannot create the process within the specified timeout, JOB sets $TEST to false (0). If a JOB command does not specify a timeout, the execution of the command does not affect $TEST.
If GT.M cannot create the process because of something that is unlikely to change during the timeout interval, such as invalid DEFAULT directory specification, or the parameter list is too long, the JOB command generates a run-time error. If the command does not specify a timeout and the environment does not provide adequate resources, the process waits until resources become available to create the resultant process.
When the JOB is forked, UNIX creates the environment for the new process by copying the environment of the process issuing the JOB command and making a few minor modifications. By default, the standard input is assigned to the null device, the standard output is assigned to routinename.mjo, and the standard error is assigned to routinename.mje.
By default, GT.M uses the current working directory of the parent process for the working directory of the initiated process.
If the files specified by processparameters, do not exist, and GT.M does not have permission to create them, the JOBed process terminates. When the corresponding files are in the current working directory, the OUTPUT, INPUT, and ERROR processparameters do not require a full pathname.
The following sections describe the processparameters available for the JOB command in GT.M.
The string literal specifies the $ZCMDLINE of the JOB'd process.
Note that the contents of CMD[LINE] appear in process listings. This can be useful for application administrators to identify process purpose. Be aware of the risks of exposing protected information by including that in CMD[LINE].
The string literal specifies the default directory.
The maximum directory length is 255 characters.
If the JOB command does not specify a DEFAULT directory, GT.M uses the current default directory of the parent process.
strlit specifies the stderr of the JOBbed process. strlit can either be a file or a DETACHed socket (that is, a socket from the socket pool). To pass a DETACHed socket as the stderr of the JOBbed process, specify strlit in the form of "SOCKET:<handle>" where <handle> is the socket handle. On successful completion of the JOBbed process, the passed socket is closed and is no longer available to the parent process.
The maximum string length is 255 characters.
By default, JOB constructs the error file from the routinename using a file extension of .mje: the default directory of the process created by the JOB command.
The string literal specifies a value for the environment variable gtmgbldir.
The maximum string length is 255 characters.
By default, the job uses the same specification for gtmgbldir as that defined in $ZGBLDIR for the process using the JOB command.
strlit specifies the stdin of the JOBbed process. strlit can either be a file or a DETACHed socket (that is, a socket from the socket pool). To pass a DETACHed socket as the stdin of the JOBbed process, specify strlit in the form of "SOCKET:<handle>" where <handle> is the socket handle. On successful completion of the JOB command, the passed socket is closed and is no longer available to the parent process.
![[Note]](../common/images/note.jpg) | Note |
|---|---|
Specify a DETACHed socket in both INPUT and OUTPUT parameters to pass it as the $PRINCIPAL of the JOBbed process. |
The maximum string length is 255 characters.
GT.M does not supply a default file extension.
By default, the job takes its input from the null device.
strlit specifies the stdout of the JOBbed process. strlit can either be a file or a DETACHed socket (that is, a socket from the socket pool). To pass a DETACHed socket as the stdout of the job, specify strlit in the form of "SOCKET:<handle>" where <handle> is the socket handle. On successful completion of the JOB command, the passed socket is closed and is no longer available to the parent process.
| Note |
|---|---|
Specify a DETACHed socket in both INPUT and OUTPUT parameters to pass it as the $PRINCIPAL of the JOBbed process. |
The maximum string length is 255 characters.
By default, JOB constructs the output file pathname from the routinename using a file extension of .mjo and the current default directory of the process created by the JOB command.
With the PASSCURLVN jobparameter, the JOB'd process inherits the current collation, local variables, aliases, and alias containers from the current stack level of the parent process. Therefore, a ZWRITE in the JOB'd process has the same output, except for any out of scope aliases, as a ZWRITE in the context of the JOB command. If the JOB command finds a ZWRITE representation of any lvn, consisting of its full name, its subscripts, corresponding value, quotes and the equal-sign (=), exceeding 1MiB, it produces a JOBLVN2LONG error in the parent process, and a JOBLVNDETAIL error in the error output stream of the JOB'd process. If a JOB command does not specify PASSCURLVN, the JOB'd process(es) inherits no local variables from the parent, although it can receive values passed as parameters to an actuallist entryref. While not an inexpensive command, you can use the "exclusive" NEW command to control the context passed to the JOB'd process; for example, adding "NEW (LOCALA,LOCALB)" before the JOB command would pass only LOCALA and LOCALB.
If a parameter in the formal list of JOB'ed entryref shares the same name with a local in the parent process, the parameter passing facility applies the actuallist in the JOB command argument to the formallist at the invoked label superseding any local variable passed from the parent process by the PASSCURLVN option.
Specifies the location of the shell script that executes before running the named routine.
The JOBbed process spawns a shell session to execute the shell script. If the shell script fails, the JOB'd process terminates without running the named routine. Because STARTUP executes in a separate shell, it has no impact on the environment of the JOB'd process, which is inherited from the parent. STARTUP is useful for actions such as creating directories. Use PIPE devices instead of the JOB command to control the environment of a spawned process.
The processparameters are summarized in the following table.
|
JOB Processparameters | |||
|---|---|---|---|
|
PARAMETER |
DEFAULT |
MINIMUM |
MAXIMUM |
|
DEF[AULT]=strlit |
Same directory as the process issuing the JOB command |
none |
255 characters |
|
ERR[OR]=strlit |
./routinename.mje |
none |
255 characters |
|
GBL[DIR] |
Same as gtmgbldir for the process issuing the JOB command |
none |
255 characters |
|
IN[PUT]=strlit |
Null device |
none |
255 characters |
|
OUT[PUT]=strlit |
./routinename.mjo |
none |
255 characters |
|
PASS[CURLVN] |
Only pass any formallist values |
N/A |
ZWRITE key/value representations of any lvn must not exceed 1MiB |
|
STA[RTUP]=strlit |
none |
none |
Determined by the maximum length a file pathname can have on the operating system, which is at least 255 bytes on all systems which GT.M currently supports. |
Example:
GTM>JOB ^TEST("V54001","")This creates a job that starts doing the routine ^TEST (with 2 parameters) in the current working directory.
Example:
JOB PRINTLABELS(TYPE,PRNTR,WAITIM)
This passes three values (TYPE, PRNTR, and WAITIM) to the new job, which starts at the label PRINTLABELS of the current routine.
Example:
set jout="serverjob.mjo"
set jerr="serverjob.mje"
job @("check(a,b):(OUTPUT="""_jout_""":ERROR="""_jerr_""")")
This passes two values (a and b) to the new job, which starts at the label check of the current routine. It also specifies that the stdout of the jobbed process to be the file name stored in the local variable jout and stderr to be the file name stored in the local variable jerr.
Example:
Refer to the sockexamplemulti31.m program in Using Socket Devices section for more examples on the JOB command.
