^$JOB (ObjectScript)

Provides InterSystems IRIS process (job) information.

Synopsis

^$JOB(job_number)
^$J(job_number)

Argument

Argument	Description
job_number	The system-specific job number created when you enter the ObjectScript command. Every active InterSystems IRIS process has a unique job number. Logging in to the system initiates a job. On UNIX® systems, the job number is the pid of the child process started when InterSystems IRIS was invoked. job_number must be specified as an integer; hexadecimal values are not supported.

Description

You can use the ^$JOB structured system variable as an argument to the $DATA, $ORDER, and $QUERY functions to get information about the existence of InterSystems IRIS jobs on the local InterSystems IRIS system.

Examples

The following examples show how to use ^$JOB as an argument to the $DATA, $ORDER, and $QUERY functions.

As an Argument to $DATA

$DATA(^$JOB(job_number))

^$JOB as an argument to $DATA returns an integer value that indicates whether the specified job exists as a node in ^$JOB. The integer values that $DATA can return are shown in the following table.

Value	Meaning
0	Job does not exist.
1	Job exists.

The following example tests for the existence of an InterSystems IRIS process.

   SET x=$JOB
   WRITE !,$DATA(^$JOB(x))

The variable x is set to the job number of the current process (for example: 4294219937). The WRITE returns the boolean 1, indicating this process exists.

As an Argument to $ORDER

$ORDER(^$JOB(job_number),direction)

^$JOB as an argument to $ORDER returns the next or previous ^$JOB job number in collating sequence to the job number you specify. If no such job number exists as a ^$JOB node, $ORDER returns a null string.

The direction argument specifies whether to return the next or the previous job number. If you do not provide a direction argument, InterSystems IRIS returns the next job number in collating sequence to the one you specify. For further details, refer to the $ORDER function.

The following subroutine searches the InterSystems IRIS job table and stores the job numbers in a local array named JOB.

JOB
   SET pid=""
   FOR i=1:1 {
      SET pid=$ORDER(^$JOB(pid))
      QUIT:pid="" 
      SET JOB(i)=pid
    }
    WRITE "Total Jobs in Job Table: ",i
    QUIT

As an Argument to $QUERY

$QUERY(^$JOB(job_number))

^$JOB as an argument to $QUERY returns the next ^$JOB job number in collating sequence to the job number you specify. If no such job number exists as a node in ^$JOB, $QUERY returns a null string.

The following example returns the first two jobs in the InterSystems IRIS job table. Note the use of the indirection operator (@):

   SET x=$QUERY(^$JOB(""))
   WRITE !,x
   WRITE !,$QUERY(@x)

returns values for these jobs such as the following:

^$JOB("4294117993")

^$JOB("4294434881")