ESE Routines > ESEJob

# ESEJob

The ESEJob class represents the ESE job that is produced whenever a task is run. It provides the ability to monitor the job's status and retrieve both input and output parameters.

## Methods

- ESEJob::Cancel
- ESEJob::GetParameter
- ESEJob::GetParameters
- ESEJob::Info
- ESEJob::JSON
- ESEJob::Monitor

## Examples

### Example 1

The job object can be used to get the values of input and output parameters. The following example will run the task and only return when the task is completed. Then the status can be checked and the output parameter values retrieved.

Task = ESE.FindTask( 'localhost', 8181, 'ese_addition' )

Job = Task.Run( a = 1, b = 2 )

Info = Job.Info()

IF ( Info.Status eq ESE.jobSucceeded ) THEN BEGIN

PRINT, Job.a ; 'a' is an input parameter

PRINT, Job.b ; 'b' is an input parameter

PRINT, Job.answer ; 'answer' is an output parameter

ENDIF ELSE BEGIN

PRINT, 'Uh oh...'

ENDELSE

### Example 2

When multiple asynchronous jobs are run in parallel, the "join" functionality of the ESE class can be used to wait until all the jobs have completed. In this example, one task object is acquired and then it is run multiple times.

Task = ESE.findTask( 'localhost', 8181, 'smooth_sailing' )

n = 4

jobs = objarr( n )

FOR i = 0, n - 1 DO BEGIN

jobs[ i ] = Task.Run( /ASYNC )

ENDFOR

status = ESE.Join( jobs )

IF ( min( status ) ) THEN BEGIN

PRINT, 'Jobs ran successfully.'

FOREACH j, jobs, index DO BEGIN

PRINT, 'Job[', strtrim( index, 2 ) + '] URL = ' + j.outputFile[ 'url' ]

ENDFOREACH

ENDIF ELSE BEGIN

PRINT, 'Uh oh...'

FOREACH j, jobs, index DO BEGIN

IF ( status[ index ] eq 0 ) THEN !null = j.cancel()

ENDFOREACH

ENDELSE

The for loop at lines 5 through 7 runs 4 jobs in parallel. The join at line 9 blocks execution until all 4 jobs have either completed successfully or one has failed. The join returns a status array of zeros and ones, indicating which jobs succeeded and which failed or are still running. If jobs are still running, it may be desirable to cancel them.

Note: The join method has options for reporting status changes.

## Properties

### INPUTPARAMETER (IDLVariable, Get)

The value of the specified input parameter as an IDL variable.

### OUTPARAMETER (IDLVariable, Get)

The value of the specified parameter as an IDL variable. Conversion from JSON to IDL is either performed by default routines or by custom routines. If the job did not complete successfully, then the return value is !null.

# ESEJob::Cancel

This method cancels a queued, submitted, or executing job. This method has no effect on jobs that are no longer running.

## Example

Task = ESE.FindTask( 'localhost', 8181, 'smooth_sailing' )

Job = Task.Run( /ASYNC )

Canceled = Job.Cancel()

## Syntax

Result = Obj.[ESEJob::]Cancel()

## Return Value

The return value indicates success or failure of the cancellation request (!true or !false).

## Arguments

None.

## Keywords

None.

# ESEJob::GetParameter

GetParameter returns an ESETaskParameter object for the named parameter.

## Example

Task = ESE.FindTask( 'localhost', 8181, 'ese_addition' )

Job = Task.Run( a = 1, b = 2 )

Parameter = Job.GetParameter( 'answer' )

## Syntax

Result = Obj.[ESEJob::]GetParameter( Name )

## Return Value

Returns an ESETaskParameter object for the named parameter. If the parameter does not exist, then it returns !null.

## Arguments

### Name

Specifies the name of the particular parameter to return.

## Keywords

None.

# ESEJob::GetParameters

GetParameters returns a list of ESETaskParameter objects.

## Example

Task = ESE.FindTask( 'localhost', 8181, 'ese_addition' )

Job = Task.Run( a = 1, b = 2 )

Parameters = Job.GetParameters()

## Syntax

Result = Obj.[ESEJob::]GetParameters( [ /NAMES ])

## Return Value

Returns a list of ESETaskParameter objects. If the task does not have any parameters then returns an empty list. If NAMES is set, it returns an array of parameter names, or returns !null if the task does not have any parameters.

## Arguments

None.

## Keywords

### NAMES

Set this keyword to return just the names of parameters instead of ESETaskParameter objects.

# ESEJob::Info

Returns a dictionary with all the properties of the job.

## Example

Task = ESE.FindTask( 'localhost', 8181, 'ese_addition' )

Job = Task.Run( a = 1, b = 2 )

Info = Job.Info()

Status = Info.Status

## Syntax

Result = Obj.[ESEJob::]Info()

## Return Value

The return value is a dictionary with the following fields:

- Id: (integer) The job's identifier.
- Status: (string) The job's overall status: ESE.jobQueued, ESE.jobSubmitted, ESE.jobExecuting, ESE.jobSucceeded, ESE.jobFailed, ESE.jobCancelling, ESE.jobCancelled, ESE.jobTimedOut.
- Progress: (integer) The progress percentage, as reported by the running task with a range of [0,100].
- ProgressMessage: (string) The progress message, as reported by the running task.
- ErrorMessage: (string) The error message from the job's JSON or from the ESE API.
- taskURI: (object) The URI of the task that produced the job.
- taskName: (object) The name of the task that produced the job.
- httpRequest: (string) The full HTTP request string used to run the task.

## Arguments

None.

## Keywords

None.

# ESEJob::JSON

Returns the job's JSON.

## Example

Task = ESE.FindTask( 'localhost', 8181, 'ese_addition' )

Job = Task.Run( a = 1, b = 2 )

JSON = Job.JSON()

## Syntax

Result = Obj.[ESEJob::]JSON()

## Return Value

Returns the job's status JSON as a string. This JSON contains all information the ESE system knows about the job.

## Arguments

None.

## Keywords

None.

# ESEJob::Monitor

The Monitor method provides the ability to monitor a job for job status and progress changes.

The specified callback is invoked whenever the monitor notices that the job status or progress number changed. This is useful for only asynchronous jobs.

## Example

In this example a "smooth sailing" job is monitored and its progress is printed to the IDL console:

Task = ESE.FindTask( 'localhost', 8181, 'smooth_sailing' )

Job = Task.Run( /ASYNC)

Job.Monitor, 'handleJobChange'

The callback is:

PRO handleJobChange, Job, userData

PRINT, 'Job Progress: ' + strtrim( info.Progress, 2 )

END

## Syntax

Obj.[ESEJob::]Monitor, Callback [, USER_DATA = value ] [, REQUESTS_PER_SECOND = double ]

## Return Value

None.

## Arguments

### Callback

The name of a procedure to invoke whenever the job changes status or progress.

## Keywords

### REQUESTS_PER_SECOND

The number of times per second to check on the job's status. The default is 1.0.

### USER_DATA

An optional value to pass to the callback.

## Version History

IDL 8.4.1 | Introduced

## See Also

ESE, ESETaskParameter