An ISPF tool can be modeled to run as an ISPF batch job. Use the attribute RunAsJob of the tool descriptor to model a tool to be executed as a batch job.
The value Model Job means the tool is executed as an ISPF batch job. The submission of the tool as a batch job is handled in this case by the AWM ISPF tool interface. Any attached ISPF tool can be configured as Model Job with no need to make any changes to the tool logic. Use this setting for long running background processing tools which do not contain any logic for submitting a batch job, for example, tools to build a program. One advantage of this Run As Job mode is that the AWM output is generated in the same way as for an ISPF tool which is executed in the foreground. If the tool has a Job After Action modelled the tool output is processed after the execution of this Job After Action.
The value Tool Job is meant for tools which already contain logic to submit a batch job, for example, by creating a job via ISPF file tailoring and submitting it. If the tool is modeled as Tool Job you should return the job identifier and job name to the AWM client using the ISPF shared pool variables TAUTOJID and TAUTOJNA respectively or setting the correspondingfields in the ISPF table TAUTOJOB, see below.
If a tool submits more than one batch job or a tool submitting a batch job is called in a MassProcessing action the tool can set the variables TAUTOJID and TAUTOJNA in the ISPF table TAUTOJOB. This ISPF table is provided by the AWM ISPF interface and is open when the tool is called. The table TAUTOJOB is not sorted and contains the name columns TAUTOJID, TAUTOJNA, and TAUTOJPD. The two variables TAUTOJID and TAUTOJNA should not be set in the ISPF shared pool in this case. Otherwise, the job would be shown twice in the Jobs view. The table field TAUTOJPD is meant to pass the name of a job output parameter data set. This field is only relevant if the ISPF is modelled as Tool Job. If the ISPF tool is modelled as Model Job, the AWM ISPF tool interface creates the job output parameter data set. If the ISPF tool is modelled as Tool Job, the job output parameter data set is only relevant when a "Job After Action" is modelled for the tool. In this case the content of the job output parameter data set is read and interpreted by AWM when the "Job After Action" is executed. The ISPF tool has to create the job output data set and pass the name of the data set via TAUTOJPD. The job output parameter data set can contain formatted lines which are consumed by AWM. The following table shows sample entries of the job output parameter data set and their meaning.
| Sample Line | Description |
|---|---|
| TOOL: TAUTOXYZ | tool name TAUTOXYZ |
| RC: 4 | return code of the batch tool (4 in this case) |
| DATE: 18/12/24 | date |
| OUTPARM: PGM0001,COBOL,DB2 | output parameters as modelled for the batch tool |
| ENDPARM: | end marker of the parameter entries |
| OUTMSG(E): Dataset U1234567.TEST.CBL doesn’t exist! | message to display including severity (I,W,E) in parentheses |
The job submit messages should be added to the ISPF table TAUTOTBM if more than one message should be returned by the tool.
The following is a REXX code snippet which shows how a tool can create and submit a batch job and set the shared pool variables TAUTOJID and TAUTOJNA.
REXX Example 1:
wmsg = ''
subdsn = CREATEJOB('PGMBLD') /* call to the subroutine CREATEJOB (listed below) */
/* Submit batch job */
msgmode = OUTTRAP('submsg.') /* trap the submit system messages */
submsg.0 = 0
Address TSO "SUBMIT '"subdsn"'" /* TSO submit the job subdsn */
subrc = rc
msgmode = OUTTRAP('OFF') /* set the message mode off via OUTTRAP */
If subrc ^= 0 Then Do
wmsg = 'Batch job not submitted.'
Call EXIT 12 wsmg
End
Do k = 1 To submsg.0 /* validate the stem variable submsg */
Say Strip(submsg.k)
If subrc ^= 0 Then /* if the job submit failed, just return the error message lines */
wmsg = wmsg Strip(submsg.k)
Else Do
Parse Value submsg.k With msgid . jname '(' jobid ')' . /* parse the standard system submit message */
If msgid = 'IKJ56250I' Then Do
tautojid = jobid
tautojna = jname
ADDRESS ISPEXEC 'VPUT (TAUTOJID, TAUTOJNA) SHARED' /* put the variables TAUTOJID and TAUTOJNA in the ISPF shared pool */
wmsg = 'Batch job' jname'('jobid') successfully submitted'
End
End
End
If subrc ^= 0 Then
Call EXIT subrc wmsg
/********************************************************************
Subroutine to create a Member via ISPF Skeleton
Parameter:
xskel: Skeletonname
********************************************************************/
CREATEJOB:
Parse Upper Arg xskel .
/* standard ISPF file tailoring processing to create a job for batch submission */
/* we use a standard subroutine ISPF in REXX to call ISPF functions */
ADDRESS ISPEXEC "FTCLOSE"
"FTOPEN TEMP"
"FTINCL" xskel
"FTCLOSE"
"VGET ZTEMPF SHARED" /* the ISPF variable ZTEMPF contains the name of the file in which the job was created */
ADDRESS TSO
t_ddname = ztempf
Return t_ddname
The values put into the shared pool variable TAUTOJID and TAUTOJNA are displayed in an informational message window on the client side for tools modeled as Tool Job.
Jobs created by tools modeled as Model Job or Tool Job are listed in the Jobs view. This view monitors the execution status of the created job. The status changes from executing to done when the batch job has finished on the remote system. This also displays a notification message at the bottom right corner (main monitor). The notification automatically fades out after a default duration of 10 seconds. This behavior can be customized under the MVS function package in AWM models. See MVS Function Package for more information.
The Jobs view provides a context menu action to browse the output of the job.
You can model an After Job action for tools modeled as Model Job or Tool Job. The action specified under the After Job action attribute in the tool descriptor is added to the context menu of the generated job in the Jobs view. The "Job After Action" has access to the whole execution context which was available when the batch tool was submitted. The "Job After Action" is typically used to display output information generated by the job, such as build results. An advantage of tools modeled as Model Job and Tool Job is that the result of the tool is kept in the job output and can be reviewed at a later time.
The Jobs view provides an action to personalize the job card for jobs submitted by tools modeled as Model Job and also for jobs modeled as Tool Job if the batch job submitted by the tool supports the AWM job card. See ISPF Exits for more information.