CTGTask Object |
Active Web |
 |
|
CTGTask Object |
Active Web |
|
A CTGTask object is used for executing a task in a Mainframe PROIV application environment via the CICS Transaction Gateway. In order to use this object you must have a working Mainframe PROIV application configured to use the CICS transaction gateway for Tasks.
Please note that a copy of the CTG client jar file (ctgclient.jar) from IBM will need to be added to the WEB-INF/lib directory of this web application before this functionality can be used. This is available from the CICS Transaction Gateway installation media.
The CTGTask object is licensed separately and a Gateway Licence File will need to be obtained from Northgate. The object will function fully for 2 hours for evaluation purposes, at which point the application server will need to be restarted to continue use.
The CTGTask Object requires that the program specified in the constructor is the PROIV Mainframe API program running on Mainframe PROIV Version 5.0. The version 4.1 release of PROIV does not support some of the features required by this object. Please contact Northgate for upgrade routes available if you do not already have this version.
For Task execution through the PROIV Bus rather than through the CICS Transaction Gateway, see the Task Object.
The CTGTask object allows you to define the task and its environment, execute it and then collect the result set returned by the task.
CTGTask objects are of class CTGTask.
|
Property |
Description |
|
delimiter |
The code point value of the delimiter character used to do the delimiter split. The default is 44 (a comma). |
|
delimiterSplit |
If this property is set to 'true' the CTGTask object will collect PROIV Task 'report' output as an array of arrays rather than an array of delimiter separated strings. This is done by converting each row in the PROIV task 'report' output from a delimiter-separated string to an array. If the collectReports property is not true this property will have no affect. The default value is ‘false’ which means report data will be collected as an array of delimiter separated Strings. |
|
error |
An error message If an error has occurred. If no error has occurred then it will be null. The error messages are explained below: Execute error - The PROIV task had an error condition. This string will be followed by the error message from the PROIV environment. |
|
parameters |
A script object used to hold all the input and output parameters used by the PROIV Task. Parameters are either strings or a single dimensional array of strings. |
|
prototype |
A reference to the Object Prototype. This property does not enumerate and can not be deleted but can be changed. |
|
reportOutput |
This is a result set from the PROIV 'report' task. It is in the form of an array of delimiter separated strings where one element represents one line of report output. This property will only be present if the PROIV Task actually produced a report output and nextReport() has been called. |
|
taskName |
The name of a PROIV Task. This is the task that will be executed by the execute function. Whenever this property is set the parameters property is automatically cleared. |
|
Function |
Description |
|
execute() |
Causes the Task object to execute the PROIV task using its properties and the parameters set up in the 'parameters' object. The parameters returned from the PROIV Task are put in the 'parameters' object. Returns true if there were no errors. The error property will contain an error string if there was an error. |
|
nextReport() |
Use this function when processing report output from a PROIV Task. Returns true if there is a report result set available in the reportOutput property. Returns false if there are no more report result sets. |
Once a CTGTask object has been created (see the CTGTask Constructor below) you will then need to set any parameters required for the task. The parameters property holds the task parameters required for both input to the PROIV task and output from the PROIV task.
e.g.
myTask.parameters.TASK_PARAMETER_1 = 22;
myTask.parameters.TASK_PARAMETER_2 = "foo";
This example sets two input parameters the first called TASK_PARAMETER_1 and the second called TASK_PARAMETER_2.
e.g.
var result1 = myTask.parameters.TASK_PARAMETER_3;
var result2 = myTask.parameters.TASK_PARAMETER_4;
This example shows that a task returned two output parameters when it was executed and these can be obtained from the parameters property.
Both input and output parameters can be strings or arrays of strings. Whether a parameter is an array or not depends on the PROIV task. Output parameters will be updated by the task and an array parameter can update the whole or part of the array.
A PROIV Task can return report data. The report data can then be retrieved by calling the Task nextReport() function to prepare the data from the next report (a PROIV Task can return more than one report in a single task) and then accessing the reportOutput property for the report rows.
The CTGTask constructor is used to create new CTGTask objects.
var myCTGTask = new CTGTask(taskName, hostName, codiv, operatorID, operatorPassword, systemUserName, systemUserPassword, CICSRegion, GatewayPort, CICSProgram, Kernel);
A new Task object is created using the arguments (these are described below).
taskName - The name of the PROIV task to be executed.
host - The DNS name or IP address of the machine hosting the CICS Gateway.
codiv - The PROIV company/division code to use by the kernel.
operatorID - The PROIV operator-id to use by the kernel.
operatorPassword - The password to use for PROIV operator-id.
systemUserID – The RACF ID used for authentication on the Mainframe.
systemUserPassword - The password relating to the RACF ID.
CICSRegion – The CICS region required for PROIV.
GatewayPort - The port on which the CICS Gateway is listening.
CICSProgram – The Mainframe program to run (usually PRO4API2).
Kernel – The kernel to use.
Shown below is the CTGTask object prototype chain.
When the constructor is run as a function without the new operator it has exactly the same behaviour as using the new operator.
Constructor properties are read only (they can not be changed or deleted) and it is not possible to add new properties to the Constructor.
|
Property |
Description |
|
prototype |
A reference to the Object Prototype. This property does not enumerate and cannot be changed or deleted. |
The CTGTask constructor has no predefined functions.
Topic ID: 150043