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 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 JOBbed process, the passed socket is closed and is no longer available to the parent process.
![[Note]](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 JOBbed process, 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.
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 |
|
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 on which GT.M is supported. |
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:
Refer to the sockexamplemulti3.m program in “Socket Device Examples” for more examples on the JOB command.