Batch Execution

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.

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 corresponding fields 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.

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 "Job After Action" for tools modeled as Model Job or Tool Job. The action specified under the "Job After 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 also 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.