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 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.

The JOB Environment

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.

JOB Implications for Directories

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.

JOB Processparameters

The following sections describe the processparameters available for the JOB command in GT.M.

CMD[LINE]="strlit"

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].

DEF[AULT]=strlit

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.

ERR[OR]=strlit

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.

GBL[DIR]=strlit

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.

IN[PUT]=strlit

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] 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 JOB command, the passed socket is closed and is no longer available to the parent process.

[Note] 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.

PASS[CURLVN]

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.

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

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.

Examples of JOB

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.