Additional Topics > Programming with the ESE API

# Programming with the ESE API

The ESE API enables IDL programs to perform remote processing using the ENVI Services Engine. To use the API, you need IDL and an ESE server that is running locally or remotely.

The benefits of remote processing are:

- It allows processing to be performed where the data is located. Instead of bringing the data to the processing, the processing is brought to the data. This is especially important when the data is large, relative to the capacity of the network connection.
- It is often performed on a powerful server.
- Algorithms can be easily shared among users. The ENVI Services Engine makes tasks available to all users, who can use built-in ENVITasks or uploaded custom tasks. These tasks are well-defined, atomic units of processing, much like a function. See the ENVI Services Engine Help for details.

The benefits of using the ESE API to run ESE tasks are:

- Simplified Web Services: Programming is done in IDL, with little need to understand web technologies. The API forms HTTP requests, performs network communication, and manages execution. Error checking and robustness are built into the API.
- Task Chaining: The API makes it easy to chain tasks, taking the output from one task and using as the input to the next task.
- Parallel Processing: The API has methods that assist the synchronization of the client application and multiple, concurrent tasks.

The API can be used by IDL desktop applications and tasks since they are written in IDL. For example, a task could be implemented as an amalgamation of several other tasks that are chained or even running concurrently.

## Getting Started with the ESE API

The ESE API provides classes that represent "things" in the ENVI Services Engine. For example, there is an ESEServer class that represents an ESE installation. There are ESETask and ESEJob classes that mirror their counterparts in ESE. Folders and services have ESEFolder and ESEService objects. Applications need only use a handful of these classes.

One class that does not have an ENVI Services Engine counterpart is the ESE class. This is a static class that provides a starting point to writing an ESE client application. It is never instantiated and has only static methods. Typically applications will start by using ESE::FindTask, ESE::GetTask or ESE::GetServer, depending on whether you want to quickly run a task, or introspect the ESE installation. The ESE class also has mechanisms for controlling jobs that are running concurrently and for handling custom data types.

A common pattern for running a task is:

- Get the task. Call ESE::FindTask or ESE::GetTask to get an ESETask object. ESE::FindTask searches the ESE installation for the named task. Regular expressions searches are possible. If a matching task is not found then, !null is returned.
- Run the task. Invoke the task's run method. The task's parameters are set by using them as keywords to run. A task's full set of parameters, both input and output, can be discovered using the ESE Admin Console. You can also use ESETask::GetParameters to introspect a task for its parameters. The return value from ESETask::Run is an ESEJob object. Every time a task object has its run method called, a new ESEJob object is generated. These job objects should match the ones visible in the admin console.
- Check the job's status. The ESEJob objects have metadata with the job's status, which indicates if they have run successfully or not. All the possible states of a job are present as constants in the ESE class. For example, to check for success, compare the job's status metadata to ESE.jobSucceeded.
- Get the result. Successful jobs have their output parameters presented as object properties. For example, the "ese_addition" task (which is included with ESE) has the output parameter "answer." Both input and output parameters can be accessed by using IDL's "dot" notation.

For example:

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

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

Info = Job.Info()

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

PRINT, strtrim( job.a, 2 ) + ' + ' + strtrim( job.b, 2 ) + ' = ' + strtrim( job.answer, 2 )

ENDIF ELSE BEGIN

PRINT, 'Error: ' + Info.Status

ENDELSE

## Highlights of the ESE API

As described previously, you can use the ESE API can to find tasks, run them, and get results. The ESE API topics provide details of the API's capabilities. Some highlights of those capabilities are:

- Run a job asynchronously by using the /ASYNC keyword of ESETask::Run.
- Synchronize on multiple concurrently executing jobs by invoking ESE::Join.
- Monitor a job without blocking by using ESEJob::Monitor.
- Upload and download data to a server by using ESEServer::UploadFile and ESEServer::DownloadFile. The best practice is to do the processing where the data resides.
- Handle custom task data types by using the serialization and deserialization mechanisms of the ESE class.