Job

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.

	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.

OUT[PUT]=strlit

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.

STA[RTUP]="/path/to/shell/script"

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.

JOB Processparameter Summary Table

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.