EBP Web Services

Introduction

This is part of the Heirloom Computing Elastic Batch Platform forum on paas.heirloomcomputing.com.

Heirloom Computing Elastic Batch Platform - Job Entry Subsystem is controlled through a set of HTTP requests that produce XML documents as a response. Requests can be a browser submitted HTML form with the required request parameters or a simple URL issued from a command-line HTTP tool such as curl(1) or wget(1). The latter affords the possibility of integrating Heirloom Computing EBP into other business process modeling (BPM) tools. Similarly, since Heirloom Computing EBP supports the ability to invoke arbitrary scripts as part of a job or a single job step, Heirloom Computing EBP can control other BPM tools through their command-line interface.

Most often though, Heirloom Computing EBP Web services will be invoked through a rich Internet application environment such as the Elastic Scheduler Platform (ESP) portion of the Heirloom Platform-as-a-Service Administration Dashboard. From that Web 2.0 application interface you can view the jobs that are queued up, pool a number of EBP instances residing on cloud instances or a local server farm. ESP will capture report datasets onto cloud storage so the execution engines (the EBP subsytem) can be powered off or on as needed without having to have a EBP system active to, say, view report output datasets.

However you invoke the Heirloom Computing EBP Web Services the operations described in this API documentation will remain largely unchanged. The REST Web service requests and the response packet for each are described below.

Requests to and responses from the REST Web service requests follow the EBP XML Web Services Definition Language and the EBP XML Schema (also attached to this article below).

 

Class Define

Define a job class wrapping a number of execution time bounding attributes together. To submit a batch job for a certain class there must be a predefined class for it. For example, a class A job class may accept short running programs of 10 seconds or less whereas a class B would be defined for jobs with long execution (wall clock) time and large memory consumption. Jobs are submitted to EBP which determines which class best fits it. When initiators for that class are started at particular times of night or when certain events (e.g., cloud instance start-up), jobs in the queue begin executing.

Required Parameters

Parm	Description	Units
Class:	The unique class identifier.	letter, digit or name
Type:	The type of execution environment associated with this class consisting of one of the following, JCL -- IBM zOS JES2 JCL JCS -- IBM VSE JCS JEC -- IBM zOS JES2 Job Execution Control (JOBGROUP definition) COBOL -- Elastic COBOL compiled into Java jar file JAVA -- Java jar file PYTHON -- python scripts SCRIPT - sh, bash, csh, ksh scripts
Max CPU Time:	The maximum CPU time that a job may spend executing under this Job Class. Jobs that take longer than this specified amount of time will be terminated.	sec

Optional Parameters

Parm	Description	Units
Max Memory:	Indicates the maximum amount of RAM to be made available to a job and its subprograms throughout the life of the job. Default is no limit.	mb
Max Network:	The limitations in network bandwidth transmission this job may consume over its lifespan. Default is no limit.	mb
Max File:	The total size of all files written to disk during the jobs execution timeframe -- not counting database size. Default is no limit.	mb
Max Elapsed Time:	The elapsed, or "wall clock", time a job may take. A stagnant job that is awaiting resources or one operating slowly on an overloaded system may be subject to cancellation if this limitation is exceeded. Default is no limit.	sec

Response

<defineresponse timestamp="2019-06-28T03:10:11">
  <defined>
    <maxnetworksize>30</maxnetworksize>
    <maxfilesize>30</maxfilesize>
    <maxcputime>10</maxcputime>
    <class>C</class>
    <maxmemorysize>30</maxmemorysize>
    <type>JCL</type>
    <maxwalltime>300</maxwalltime>
  </defined>
</defineresponse>


<defineresponse timestamp="2019-06-28T05:03:33">
  <error status="200" code="HCI712E">$HASP712E Class 'A' already defined"</error>
</defineresponse>
 

---

 

Initiator Start

Start one or more initiators of a defined class or classes. Batch jobs in the input queue only run if there are initiators started for that class, although any number of jobs can be submitted to a defined class before there are initiators started to run them. Each initiator can run at most one concurrent job. Initiators can be programmed to start at a particular time and stop at a later time. Initiators can be started for more than one class.  For example, specifying classes B,A,DEE in this Web service would cause the started initiator to look for waiting class B jobs and run them before looking for class A jobs.  If none are available to run then class DEE jobs in the queue would be examined.  If no jobs from any of these classes are ready to run (based on  dataset DISPositions, among other factors) the initiator sleeps until such time that a job is ready to run.

For more advanced scheduling, see the scheduling tools on paas.heirloomcomputing.com. Start only the number of initiators needed to run most jobs concurrently. On 50-MIPS cloud instances (1 CPU core) this means approximately 1-2 "small" (10-30 second duration) batch classes and one "large" (30 minute elapsed time) class initiators. Generally, at the beginning of a batch window start more smaller class initiators and then open up larger initiators later in the evening. When there is no work for an initiator to do (local input job queue is empty), it will consult with the cloud-based Task Scheduler for more jobs waiting to be dispatched to a pool of EBP instances. Failing that, the initiator will idle until jobs have been queued and are ready to run. A job is ready to run only if all of its resources are available for shared or exclusive use (based on JCL criteria). Further, only one job of a particular job name may execute at once, even if there are multiple initiators ready to handle it. Thus, a series of jobs all named "COMPILE2" will execute consecutively.

Required Parameters

Parm	Description	Units
Class:	The class of initiator to start. Must correspond to an currently defined class.  A list of comma-separated classes indicates that the initiator will look for all jobs of any of the classes from the first listed to the last.	list of letter, digit or names

Optional Parameters

Parm	Description	Units
Number:	The number of initiators of this class to start. Default is 1.
Start:	If supplied, indicates when the group of initiator are to start. Default is to start immediately.	(yyyy-mm-ddThh:mm:ss)
Stop:	If supplied, indicates when the group of initiator should quiesce. Shutdown is gradual, existing jobs still running will be allowed to finish but no new jobs will be started by an initiator that is waiting to stop. Default is to not shutdown.	(yyyy-mm-ddThh:mm:ss)

Response

The response document will include all the initiator IDs of that class that have been started.

<startresponse timestamp="2019-06-28T04:59:23">
  <started>
    <startat>2019-10-31T22:00:00</startat> 
    <stopat>2063-08-04T22:00:00</stopat> <n>3</n> 
    <class>A</class>
    <initiators>
      <initiator>62500</initiator> 
      <initiator>87781</initiator>
      <initiator>60189</initiator> 
    </initiators>
  </started>
</startresponse>

<startresponse timestamp="2019-06-28T05:02:03"> 
  <error status="200" code="HCI706E">$HASP706E Class 'G' not defined</error> </startresponse>

---

 

Job Submit

Submits a job to the Heirloom Computing EBP input queue. Jobs must be submitted to a defined class but not have initiators running for that class. Jobs will only execute once initiators are running to invoke them. The job is examined (1) when it is submitted, (2) when it is evaluated to determine if it is ready to run and (3) when it is started by an initiator. Any number of JCL or other job scripting errors may be detected at any stage and those errors are subject to ABENDing the job before any of the programs referenced within it begin running. If it is determined through analysis that a job does not meet the criteria of the class to which it was submitted, it may be requeued by an initiator of one class and put back into the input queue of another class.

Required Parameters

Parm	Description		Units
Deck:	The Job input deck is submitted as part of the HTTP POST request to the Web service where the posted document is the job to run. The job must be of a job type (e.g., JCL, Python, COBOL command line application) accepted by a defined job class. Analysis of the job type is based on the initial statements of the job. Note that what is submitted are instructions on how to invoke programs, not the binary programs themselves. In the case of COBOL command line applications the script is the command-line necessary to invoke the program. For submitted JCL the programs that are invoked are contained in the EBP file system as determined by EBP Configuration Settings.

Optional Parameters

Parm	Description	Units
Class:	The class the job should be submitted to. An error occurs if the submitted script doesn't correspond to the type or runtime specifications of the class, or if the class does not exist. Default is to determine job class based on submitted deck	letter, digit or name
Hold	Submit the job to the class in a hold status. Held jobs will not start executing even if an initiator is available to run them.	yes|no
Type	The type of script to submit, by default the first few lines are examined to determine the type:  starting with "//JOBNAME JOB"  (JES2 JCL), "//  JOB JOBNAME"  (VSE JCS), "//GRPNAME JOBGROUP" (JES2 JEC) "#!/usr/bin/python (Python script), "#!/bin/sh" (shell script), "0x05" (Java JAR magic number)	JCL|JCS|JEC COBOL|JAVA| PYTHON|SCRIPT
parm1 parm2 parm3	Arbitrary symbolic parameter names and values passed as submit parameters to the job for replacement when the job is run. Although the EBP home page SUBMIT form has space for three such parameters, any number may be supplied to the Web service.

Response

<submitresponse timestamp="2019-06-28T05:05:02">
  <submitted>
    <jobname>TEST04</jobname>
    <hold>no</hold>
    <job>82694</job>
    <class>A</class>
    <message>
        $HASP151I JOB 82694 TEST04 SUBMITTED TO INTERNAL READER
    </message>
  </submitted>
</submitresponse>


<submitresponse timestamp="2019-06-28T05:08:17">
  <error status="200" code="HCI706E">$HASP706E Class 'G' not defined</error>
</submitresponse>

---

 

List

This is the single function to query the state of a number of Heirloom Computing EBP attributes. You can learn about all of the defined classes, queued jobs and outputs (by the IDs of each) by issuing the Web service without parameters. Supplying an ID for one of those objects will detail the information about that element of EBP. And List is used to return output datasets (reports) that were generated as part of the job execution. Note: Reports come out in the same form the program wrote them, not in XML format. Reports should be printable, there is no provision for returning binary documents generated from a job.

Required Parameters

None. If no parameters are supplied, EBP responds with information about all of the defined classes, started initiators, input queued jobs and output datasets.  If one or more of the parameters are given as "*" then all the list of IDs or names for that type are presented.

Optional Parameters

Parm	Description	Units
Class	Provide details about an individual defined job class. No default.	Letter, digit or name
Initiator:	Provide details about an individual class initiator corresponding to its 5-digit ID. No default.	ID
Job:	Provide details about an individual submitted job. No default.	ID or Name
Jobgroup:	Provide details about a JOBGROUP defined through a submitted JEC dec	ID or Name
Full:	For Job Groups, provide full (default, true) or job-dependency-only info (false)	true|false|yes|no|1|0
Output:	Provide details about the output of a job. Only completed jobs (not running or queued) will be shown. No default.	ID or Name
Step:	Used in conjunction with an Output ID (only), this will return the output dataset corresponding to a particular output DD name associated with this job step name. No default	Name or Name.Proc-Step-Name
DD:	Used in conjunction with an Output ID (only), this will return the output dataset corresponding to a particular output DD name associated with this job step name. The DD Name is referenced in the input job deck. For JCL, the DD name must be tied ot a SYSOUT specification. Some DD names are, MSG The overall report of the job execution by EBP (no Step name is supplied) STDOUT The standard output from a command-line program or script STDERR The standard error from a command-line program or script SYSOUT The system output from a program within a JCL job step SYSERR The system error from a program within a JCL job step SYSPRINT The report output from many common system utilities No default.	Name
Eclipse	Used by the Eclipse COBOL IDE EBP Server view. Behavior is similar to specifying no parameters however in this case additional job information such as state/type/class etc are also returned when providing eclipse (1, true, yes)	true|false|yes|no|1|0

Response

List with no parameters:

XML Tag	Description
classes	The group of classes currently defined
class	The class letter, digit or name
jobgroups	The group of job groups currently defined
jobgroup	The job group name
jobs	The group of jobs that have been submitted
job	The job number
outputs	The group of outputs from jobs that have been run
output	The output number
initiators	The group of initiators defined
initiator	The initiator number

 Example:

<listresponse timestamp="2019-06-28T05:27:46">
  <listed>
    <classes>
      <class>D</class>
      <class>A</class>
      <class>B</class>
    </classes>
    <jobs>
      <job>58450</job>
      <job>77732</job>
      <job>82694</job>
      <job>58251</job>
    </jobs>
    <jobgroups>
      <jobgroup>MYGROUP</jobgroup>
    </jobgroups>
    <outputs>
      <output>58450</output>
      <output>77732</output>
      <output>82694</output>
      <output>58251</output>
    </outputs>
    <initiators>
      <initiator>62500</initiator>
      <initiator>87781</initiator>
      <initiator>60189</initiator>
      <initiator>65646</initiator>
      <initiator>16283</initiator>
    </initiators>
  </listed>
</listresponse>

List while specifying eclipse=yes as a parameter (issued by Elastic IDE plug-in to Eclipse):

<listresponse timestamp="2019-06-28T05:27:46">
  <listed>
    <classes>
      <class>A</class>
    </classes>
    <jobs>
      <job>58450</job>
    </jobs>
    <jobsdesc>
       <jobdesc>58450,TEST01,A,JCL,EBP,TERMINATED,2019-06-01T23:15:44,2019-06-01T23:15:44,2019-06-01T23:15:46,0,WITH CC 0,</jobdesc>
    </jobsdesc>
    <jobgroups>
      <jobgroup>MYGROUP</jobgroup>
    </jobgroups>
    <outputs>
      <output>58450</output>
    </outputs>
    <initiators>
      <initiator>62500</initiator>
    </initiators>
  </listed>
</listresponse>

 

List while specifying a class parameter

XML Tag	Description
classname	The class letter, digit or name this describes
type	The type of job this class defines. JCL - IBM z/OS (S/360) Job Control Language JCS - IBM iSeries (AS/400) Job Control Statements JEC - IBM z/OS Job Execution Control PYTHON - Python executable scripts COBOL - Direct COBOL program execution SCRIPT - Shell or Windows executable scripts
maxcputime	The maximum CPU time enforced by initiators of this class (when ebpstart monitoring has been configured)
maxmemorysize	The maximum memory size of jobs in this class (when ebpstart monitoring has been configured)
maxnetworksize	The maximum network transmission size of jobs in this class (when ebpstart monitoring has been configured)
maxfilesize	The maximum file size that can be created by jobs as enforced by initiators of this class (when ebpstart monitoring has been configured)
maxwalltime	The maximum CPU time enforced by initiators of this class (when ebpstart monitoring has been configured)

Example:

<listresponse timestamp="2019-06-28T05:29:21">
  <listed>
    <class>
      <classname>A</classname>
      <type>JCL</type>
      <maxcputime>10</maxcputime>
      <maxmemorysize>30</maxmemorysize>
      <maxnetworksize>30</maxnetworksize>
      <maxfilesize>30</maxfilesize>
      <maxwalltime>20</maxwalltime>
    </class>
  </listed>
</listresponse>

 

 

List while specifying a job ID parameter

XML Tag	Description
jobid	The numeric job identifier
jobname	The job identifier from the JOB card
classname	The class name from the JOB card or assigned by EBP
type	The type of job this class defines. JCL - IBM z/OS (S/360) Job Control Language JCS - IBM iSeries (AS/400) Job Control Statements JEC - IBM z/OS Job Execution Control PYTHON - Python executable scripts COBOL - Direct COBOL program execution SCRIPT - Shell or Windows executable scripts
msgclass	The output message class from the JOB card MSGCLASS parameter or assigned by the system
time	The CPU time from the JOB card or 0 if unspecified
dataset	The output dataset containing the JCL text, in the EBP configured job input queue
status	The current status of the job. QUEUED - The job is awaiting execution RUNNING - The job is currently running TERMINATED - The job has completed execution CANCELED - The job has been canceled ABORTED - The job has been aborted ERROR - The job cannot be queued due to a severe error HELD - The job has been intentionally held from execution, awaiting a RESTART web service SUSPENDED - The job was suspended during execution FLUSHED - The job has been removed from the system after a period of time
debugport	When Remote Debugging has been configured in EBP and this job is awaiting a debug attachment, indicates the port number to attach from a Java debugger
submitparms	When a job has been submitted with parameters, like job-specific PARMLIB names and values
owneruser	When run under EBP Resource Access Control (RAC) the user that owns this job, EBP being the default user id
ownergroups	When run under EBP Resource Access Control (RAC) the groups that control this job, EBP being the default group id
submitted	The date and time the job was submitted
initiated	The date and time the job started execution
terminated	The date and time the job finished execution
message	The final message, if any, of the job's execution

Example:

<listresponse timestamp="2019-06-28T05:32:02">
  <listed>
    <job>
      <jobid>48232</jobid>
      <jobname>TEST01</jobname>
      <classname>A</classname>
      <type>JCL</type>
      <msgclass>A</msgclass>
      <time>0</time>
      <dataset>job_input_queue/JOB48232.txt</dataset>
      <status>TERMINATED</status>
      <debugport/>
      <submitparms/>
      <owneruser>EBP</owneruser>
      <ownergroups/>
      <submitted>2019-06-13T20:26:15</submitted>
      <initiated>2019-06-13T20:26:16</initiated>
      <completed>2019-06-13T20:26:16</completed>
      <message>WITH CC 0</message>
    </job>
  </listed>
</listresponse>

 

 

List while specifying a output ID parameter

XML Tag	Description
jobid	The numeric job identifier
jobname	The name of the job
returncode	The return (condition) code for the job as a whole
msgclass	The output message class for this job
message	The final message, if any, for this job
status	The status of the output for this completed job READY - The output is ready to be viewed or printed NOTREADY - The job is in progress and output cannot be viewed CLEAN - The output has been printed and removed from the system PROBLEM - A problem has occurred in printing this output
lastcompletedstep	In the event of a job that has been checkpointed this is the last completed step.
msgddname	Always MSG, the location of the job's messages
msgdatasetname	The message dataset in the job output spool
msgdatasetpath	The full path name of the message dataset
spool	The enclosing group of spooled outputs for this job, by step and DD name
step	The enclosing group of spooled outputs within a step of the job
name	The step name (and possibly proc name and proc step name)
dd	The enclosing group of spooled outputs for this step name, by DD card assignment
ddname	The DD name for this spooled output file
msgclass	The output spool class letter, number or name, or * for the same as the enclosing job's MSGCLASS
datasetname	The output spool's dataset name within the EBP configured output spool
datasetpath	The fully qualified output spool path, assuming an output spool has not been defined (e.g., printer) that manages it
temporary	Indicator that the output dataset is temporary, or can be removed after an EBP shutdown/restart

Example:

<listresponse timestamp="2019-06-28T05:34:00">
  <listed>
    <output>
    <job>58450</job>
    <jobname>TEST14</jobname>
    <returncode>0</returncode>
    <msgclass>A</msgclass>
    <message/>
    <status>ready</status>
    <lastcompletedstep/>
    <msgddname>MSG</msgddname>
    <msgdatasetname>OUT58450__MSG.txt</msgdatasetname>
    <msgdatasetath>/path/to/job_output_queue/OUT58450__MSG.txt</msgdatasetpath>
    <spool>
    <step>
      <name>STEP1.PROCID01</name>
      <dd>
        <ddname>SYSERR</ddname>
        <msgclass>*</msgclass>
        <temporary>true</temporary>
        <datasetname>OUT58450_STEP1.PROCID01_SYSERR.txt</datasetname>
        <datasetpath>/path/to/job_output_queue/OUT58450_STEP1.PROCID01_SYSERR.txt</datasetpath>
      </dd>
      <dd>
        <ddname>SYSOUT</ddname>
        <msgclass>*</msgclass>
        <temporary>true</temporary>
        <datasetname>OUT58450_STEP1.PROCID01_SYSOUT.txt</datasetname>
        <datasetpath>/path/to/job_output_queue/OUT58450_STEP1.PROCID01_SYSOUT.txt</datasetpath>
      </dd>
    </step>
    <step>
      <name>STEP2.PROCID01</name>
      <dd>
        <ddname>SYSERR</ddname>
        <msgclass>*</msgclass>
        <temporary>true</temporary>
        <datasetname>OUT58450_STEP2.PROCID01_SYSERR.txt</datasetname>
        <datasetpath>/path/to/job_output_queue/OUT58450_STEP2.PROCID01_SYSERR.txt</datasetpath>
      </dd>
      <dd>
        <ddname>SYSOUT</ddname>
        <msgclass>*</msgclass>
        <temporary>true</temporary>
        <datasetname>OUT58450_STEP2.PROCID01_SYSOUT.txt</datasetname>
        <datasetpath>/path/to/job_output_queue/OUT58450_STEP2.PROCID01_SYSOUT.txt</datasetpath>
      </dd>
    </step>
    </spool>
    </output>
  </listed>
</listresponse>

 

 

List while specifying a output ID and DD parameter of MSG parameter (no step parameter)

Description

When output ID, step name and DD name are provided, the output dataset itself is generated without XML tags

Example:

HEIRLOOM COMPUTING INC - JOB ENTRY SUBSYSTEM

$HASP111I JOB 95519 (TEST04) STARTED AT 2019-06-28 05:39:04 ON CLASS A
$HASP117I JCL SCAN START
$HASP118I          //* :....1....:....2....:....3....:....4....:....5....:....6....:....7.
$HASP118I          //TEST04   JOB  (HCIACCT),'Hello World job',CLASS=A,MSGCLASS=A,
$HASP118I          //              MSGLEVEL=(2,2),NOTIFY=USERID
$HASP118I          //* copy a message to the printer.  (LIST output for DD name MSG, no 
$HASP118I          //* step, step name STEPID01 / DD name SYSUT2 and STEPID01 / SYSPRINT)
$HASP118I          //STEPID01 EXEC PGM=IEBGENER
$HASP118I          //SYSIN    DD   DUMMY
$HASP118I          //SYSPRINT DD   SYSOUT=*
$HASP118I          //SYSUT1   DD   *
$HASP118I          Hello Heirloom Computing EBP World!
$HASP118I          /*
$HASP118I          //SYSUT2   DD   SYSOUT=A
$HASP118I          //* :....1....:....2....:....3....:....4....:....5....:....6....:....7.
$HASP117I JCL SCAN END

$HASP125I JOB ANALYSIS START
$HASP126I              JOB ATTRIBUTE NAME: TEST04
$HASP126I              JOB ATTRIBUTE CLASS: A
$HASP126I              JOB ATTRIBUTE ACCOUNT: HCIACCT
$HASP126I              JOB ATTRIBUTE PROGRAMMER: Hello World job

$HASP126I              STEP ATTRIBUTE NAME: STEPID01
$HASP126I              STEP ATTRIBUTE PGM: IEBGENER
$HASP126I              DD ATTRIBUTE NAME: SYSIN
$HASP126I              DD ATTRIBUTE NAME: SYSPRINT
$HASP126I              DD ATTRIBUTE NAME: SYSUT1
$HASP126I              DD ATTRIBUTE NAME: SYSUT2

$HASP125I JOB ANALYSIS STOP


$HASP135I JOB STEP STEPID01          EXECUTION STARTED    AT 2019-06-28 05:39:04
$HASP136I JOB STEP STEPID01          EXECUTION TERMINATED AT 2019-06-28 05:39:05 WITH RC 0

$HASP112I JOB 95519 (TEST04) TERMINATED AT 2019-06-28 05:39:05 WITH CC 0
   

---

 

System Quiesce

Puts the overall EBP subsystem into a quiesce state. Running jobs are allowed to finish but no new jobs are started ... even if there are idling initiators available. Used as a prelude to system stop. Use the List Web service to determine what jobs are running before shutting the system down. Can also be used (with the Reset option) to carry out a full system reset, which removes all input jobs, output datasets, classes and initiators and reloads the system configuration. Restore to a normal running system with the Wakeup option.

Required Parameters

None. Supplying no parameters indicates that the system quiesce should begin.

Optional Parameters

Parm	Description	Units
Wakeup	Specifying no puts the system in a quiesce state, yes wakes it from that state. Default no.	yes|no
Reset	Carry out a system reset. Warning: Removes all jobs, outputs, initiators and classes. Default no.	yes|no

Response

<queisceresponse timestamp="2019-06-28T05:45:07">
  <queisced>
    <wakeup>no</wakeup>
    <reset>no</reset>
  </queisced>
</queisceresponse>

---

 

Release Resources

Releases resources locked by EBP during job runs. Default behavior is to release resources only for jobs that have completed,aborted or cancelled.

Required Parameters

Parm	Description	Units
jobid	The unique job identifier for which resources should be released. '*' indicates all jobs.	5 digit jobid Or '*'

 

Optional Parameters

Parm	Description	Units
dsn	A ',' separated list of specific resources that should be released	Resource DD name. For e.g A.B.C,E.F.G
ignorejobstatus	Set to true to ignore the default behavior of releasing resources only for jobs that have completed,cancelled or aborted	yes|true|1|0|false|no

 

Cancel Job

Cancel a running or queued job. A canceled job can be listed or purged, but not restarted.

Required Parameters

Job ID of the running or queued job.

Parm	Description	Units
Job	The unique job identifier to cancel.

Response

<cancelresponse timestamp="2019-06-28T05:47:28">
  <canceled> 
    <job>95519</job>
  </canceled>
</cancelresponse>

 

Purge Output

Purges output from a stopped job. This removes all output datasets queued for a job. To completely remove all trace of a job, both Cancel and Purge it.

Required Parameters

Parm	Description	Units
Job	Job ID of the finished job.

Response

<purgeresponse timestamp="2019-06-28T05:47:28">
  <purged>
    <job>95519</job>
  </purged>
</purgeresponse>

---

 

Initiator Stop

Stop one or more previously started initiator of a certain class or a specific initiator. Stopping an initiator does not terminate jobs running under it. The initiator will not accept new jobs until the current one finishes, and then it will cease to exist.

Required Parameters

Parm	Description	Units
Class:	The job class whose initiator(s) are to be stopped.	Letter, digit, name or list of classes

Optional Parameters

Parm	Description	Units
N:	The number of initiators to stop of the given class if a specific initiator ID is not given. Default 1.	number
Initiator:	A specific initiator ID to stop. No default.	ID

Response

<stopresponse timestamp="2019-06-28T06:02:26">
  <stopped>
    <n>1</n>
    <class>A</class>
    <initiators>
      <initiator>53625</initiator>
    </initiators>
  </stopped>
</stopresponse>

---

Undefine Class

Remove a job class. All jobs that are in the input queue for that class will be flushed from the system. All initiators that are running at the time will be stopped. Their running jobs will be asked to stop. This operation may take several minutes to complete as jobs and initiators are shut down.

Required Parameters

Parm	Description	Units
Class:	The job class to remove.	Letter, digit or name

Optional Parameters

None

Response

<undefineresponse timestamp="2019-06-28T06:02:26">
  <undefined>
    <class>A</class>
  </undefined>
</undefineresponse>

---

 

Checkpoint Job

Checkpoint (suspend) a running job, holding onto its current state (temp spool, input spool, output spool) and placing it in the suspend state. The current step of the running job is ABENDed with a code S08F.  Datasets that were in use remain locked to other jobs that might be queued waiting for them. The restart Web service is used to move suspended jobs to the queued state. It is subject to moving to the running state when an initiator is available for that class.

Queued jobs may be checkpointed and are moved to the held state The restart Web service is used to move held jobs to the queued state. It is subject to moving to the running state when an initiator is available for that class.

Required Parameters

Parm	Description	Units
Job:	The job ID to checkpoint.	ID

Optional Parameters

None

Response

<checkpointresponse timestamp="2019-06-28T06:19:18">
  <checkpointed>
    <job>69032</job>
  </checkpointed>
</checkpointresponse>

<checkpointresponse timestamp="2019-06-28T06:16:39">
  <error status="200" code="HCI724E">
    $HASP724E Job '81812' in state 'finished' is not restartable
  </error>
</checkpointresponse>

---

 

Restart Job

Move a job from the held or suspended state to a queued state, where it can be run by an initiator of that class.  Jobs that were suspended resume at the step they were executing at the time checkpointed.

Required Parameters

Parm	Description	Units
Job:	Job ID of the queued or held job to be restarted	ID or Name

Optional Parameters

None

Response

<restartresponse timestamp="2019-06-28T06:20:41">
  <restarted>
    <job>69032</job>
  </restarted>
</restartresponse>

---

 

Lock Resource

Used internally to coordinate between EBP nodes operating within an EBP-Plex. Only one operation can be used from a browser or from a Web services client other than another EBP-Plex node.  The LIST operation will display all currently locked resources known to that node.  If the node is acting as an EBP Plex peer (lock coordinator), it will  report all locks within the EBP-Plex.

The LIST operation displays EBP-Plex status

• ebpplex - Displayed as on if multiple nodes are coordinating or off is operating as a single-node EBP
• peer - Indicates the nodes participating in this EBP-Plex (one per node), the top 2 being the "top peers" that coordinate locks among the EBP-Plex

The LIST operation will display the following information about resources

• name - The resource that is locked by this node
• jobid - The job ID this resource is associated
• type - The type of resource, either dataset name (DSN) or job name (JOB)
• intent - Whether the resource is locked for exclusive (EXC) or shared (SHR) use
• term - Whether the resource is locked SHORT (within a step) or LONG (within a job) term

Required Parameters

Parm	Description	Units
Oper:	The locking operation to be performed. LOCK-lock a resource; UNLK-unlock a locked resource; CHEK-check the status of an EBP-Plex peer; LIST-list status of the EBP-Plex; HELO-announce this node joining an EBP-Plex; GDAY-announce this node leaving an EBP-Plex.	HELO CHEK GDAY LOCK UNLK LIST

Optional Parameters

Parm	Description	Units
From:	The external URL from which the requesting EBP node will be known by other nodes	URL
To:	The external URL this EBP node will be known by other nodes	URL
JobID:	The job id this resource is associated with	Number
JobName:	The job name this resource is associated with	Number
Top1:	One of the "top peers" in the EBP-Plex	URL
Top2:	Another of the "top peers" in the EBP-Plex	URL
Proxy:	Whether operating as a proxy	yes | no
dsn_any	The resource name to lock (the parm name) and lock type (value)	EXC | SHR

Response

<lockresponse timestamp="2019-08-15T05:32:17">
  <locked>
    <from>http://localhost:8080/ebp/</from>
    <ebpplex>on</ebpplex>
    <message>OK</message>
    <oper>LIST</oper>
    <peer class="1">http://localhost:8085/ebp</peer>
    <peer class="2">http://localhost:8086/ebp</peer>
    <peer class="3">http://localhost:8087/ebp</peer>
    <peer class="4">http://localhost:8088/ebp</peer>
    <peer class="5">http://localhost:8089/ebp</peer>
    <resources>
      <resource>
        <name>ecobol.jar</name>
        <type>DSN</type>
        <intent>SHR</intent>
        <jobid>30725</jobid>
        <term>LONG</term>
      </resource>
      <resource>
        <name>HCI00.TESTALL.LOG</name>
        <type>DSN</type>
        <intent>EXC</intent>
        <jobid>30725</jobid>
        <term>SHORT</term>
      </resource>
      <resource>
        <name>TESTALL</name>
        <type>JOB</type>
        <intent>EXC</intent>
        <jobid>30725</jobid>
        <term>LONG</term>
      </resource>
    </resources>
  </locked>
</lockresponse>

---

 

Configure EBP

Configure the Heirloom Computing EBP system. Without parameters, the service will display the current value of all settable parameters. Providing a config parameter (only) will show that parameter. Supplying both a name and value will set the configuration parameter. See EBP Configuration for a description of configuration parameters. POSTing an XML document containing the configuration settings is a way to restore a system to the state it was last saved. In the table below Name and Value indicate the name and value of the configuration item, which would be specified on the web service as, for example,  /config?jcllib.3=$HOME

Required Parameters

Parm	Description	Units
Name	The configuration parameter name, as found in the ebp.properties file. If not supplied, the list of all configurable properties and their values are returned in the response.
Value	The new value. If not supplied the current value of the configuration parameter is returned in the response.

Response

<configresponse timestamp="2019-06-28T06:14:25">
  <configged>
    <jcllib n="3">$HOME/jcl_system_lib</jcllib>
  </configged>
</configresponse>

---

 

Configuration Web Form

The EBP default home page contains forms that will submit each Web service. The form allows any of the configuration settings to be made.  Multiple configuration changes can be made with a single submit.  For example, to set the EBP error reporting level select the pull-down menu next to Error Level and select Debug, Info, Warning or Error. To set the systemlib.4 setting (the 4th location EBP will search for utilities and command programs referenced in an EXEC card) the # pull down next to the System Lib configuration is set to 4 and the operating system directory is entered beside it.

Click the OK button to apply all the changes set on the form.  A new window containing an XML representation of those changed settings will appear in the browser. To view current configurations click the Show button.  If one or more group configuration lists (e.g., all the PARMLIB symbolics and their values), check the box next to the group setting (Parmlib:).

All configuration settings may be saved into a file (Save) or restored from that file (Choose File, Load) for example when installing a new version of EBP or moving EBP from one environment to another.

Invoking Web Services

You can invoke Web services from any client application by using that application's library to issue HTTP requests and process the response.  In Java this is done with the HttpURLConnection class.  It can also be invoked from the Linux shell commands wget or curl. These commands are also available for Windows.

• wget http://localhost:8080/ebp/config?errorlevel=W
• curl  --form "fileupload=@compoundinterestjob.jcl" http://localhost:8080/ebp/submit

An XML response generated from the Web service is sent to the standard output or can be captured to a file with another flag:

<?xml version="1.0" encoding="UTF-8" ?>
<submitresponse timestamp="2013-07-23T18:08:54">
  <submitted>
    <class>A</class>
    <hold>no</hold>
    <job>88517</job>
    <jobname>COMPINT</jobname>
    <message>
        $HASP151I JOB 88517 COMPINT SUBMITTED TO INTERNAL READER
    </message>   
  </submitted>
</submitresponse>

The formal EBP XML Schema Definition and EBP XML Web Services Definition Language description of the web services are attached to this article as well as on the Web site downloads area.

<jobdesc>77732   ,TEST01,A,JCL,EBP,TERMINATED,2019-06-01T23:15:44,2019-06-01T23:15:44,2019-06-01T23:15:46,0,WITH CC 0,</jobdesc>