Using XML

When you generate a task interface object, a task file is always generated regardless of your other selections. Task files contain metadata about one or more task definitions created in Task Builder. They are used during run-time to help parse the client-supplied instance XML for an ICA call. The parsing and processing of the input XML with the help of the metadata in the task file is what allows Services Builder to create a COMMAREA image of data to send to CICS in order to run one of the existing programs on the host.

The Workflow

This is an example of a general synchronous workflow:

  1. A client calls open() and passes the unique identifier (for example, a URL or file name) of a task file. All task inputs and outputs must comply with the metadata associated with that task in the task file supplied in the open(task_file_identifier) call.

  2. The runtime service retrieves the task file.

  3. The client can call getMetaData(String task_id) to find out what tasks are available and what they "look" like, and metadata will be returned as an XML string.

  4. If necessary, the client sets the timeOut and maxSize properties.

  5. The client calls execute() and specifies a task and the input data needed to execute the task.

  6. The runtime service processes the client-supplied XML input using the metadata from the task file, initiates the execution of the call to the host program, and returns when done.

  7. The client loops and calls getData to retrieve the results and then checks the available property to see if more data is remaining.

  8. The runtime service returns up to the maximum size (maxSize property) of the retrieved data and sets the available property to the size of any remaining data.

  9. The client calls close() when the task is finished executing.

  10. The runtime service releases resources as needed.
Description Example
Instantiate the connector class for your Synapta Services Builder. The examples create the instance "myconnector." CICSConnectorAccess myconnector = new
Continued line CICSConnectorAccess();
Initialize your connector by opening your task file. The argument is the path to the file. (path\to\my_connector.xml);
Get the metadata for your task. If the task id is -1, then all tasks are returned. String xmlString = myconnector.getMetaData(-1);
Optionally, set a timeout for the task execution. The default is "-1", indicating no timeout is set. myconnector.setTimeOut("-1");
Optionally, set the maximum return data size. The default is -1, indicating all data is returned. myconnector.setMaxSize(-1);
Execute the task. The argument is the task id and the task inputs as xml. myconnector.execute(task_id, inputXML);
Retrieve the data. String outputXML = myconnector.getData
Continued line(task_id);
Close the runtime service. myconnector.close();
Related Topics
Bullet Using Tasks in Your Applications
Bullet IConnectorAccess Sample Code
Bullet Attachmate Javadocs