Appendix A: Automation for Batch ThruPut APIs

GSQ request/response

This request can be used to obtain counts for jobs in the General Services Queue. The queue is broken down into 13 buckets:

GSQ request

The body_gsq block of the request may be empty or it may contain the following tags:

• included containing control center and/or type names. It may be empty. Jobs that belong to the control centers/types listed here will be included in the counts returned in the response XML.
• excluded containing control center and/or type names. It may be empty. Jobs that belong to the control centers/types listed here will be excluded from the counts returned in the response XML.

• auto contains either text Y or N. Y indicates that the request is performed in the auto-refresh mode. N indicates that the request is initiated manually, by user pressing the refresh button (or its equivalent).

  Success

  Tip

  The same control center tag can belong to either the included tag or the excluded tag, but never to both of them.

GSQ request example

GSQ response

The body_gsq block of the response contains a list of service_group blocks, one per each service group defined in the active policy. Each service_group contains one control_center tag having the control center name, one type tag having a name for the type, and 13 section tags. Each section tag represents a particular bucket in the General Services queue. They can be identified by a value of ix tag inside the section block. This value is a number from 0 through 12 representing the bucket index (see the list above). In addition to the ix tag, each section block contains the following tags:

• nn containing a count for non-delayed non-exceptional jobs.
• dn containing a count for delayed non-exceptional jobs.
• ne containing a count for non-delayed exceptional jobs.
• de containing a count for delayed exceptional jobs.

The sum of the four counts is the total number of jobs that belong to a particular bucket of the General Services Queue and a particular Service Group.

GSQ response example

HCA request/response

This request can be used to retrieve the capacity management information from Automation for Batch ThruPut. The information typically covers a few hours of capacity management data.

HCA request

The body_hca block of the request can be empty (in which case the entire set of data is going to be returned in the response) or it can specify that only certain information is required. In the latter case, one or more of the following tags can be specified in the body_hca:

• lpar contains an LPAR name.
• self contains an LPAR name.
• group contains an LPAR group name.
• set contains an LPAR set name (not CMP set).
• setcmp contains a CMP LPAR set name (not a regular LPAR set).

HCA request example

HCA response

The body_hca block of the response contains a list of LPAR tags, one per LPAR known to Automation for Batch ThruPut. Each LPAR tag contains the following mandatory tags:

• name contains the name of the LPAR.
• status contains either string Active or Inactive reflecting the LPAR status.

Active LPARs can contain a list of entry tags with the capacity management data covering few last hours and sorted by the date and time values so that the most recent entry goes first.

Each entry contains the following tags:

• date_time contains the date and time of the moment the data in this entry tag was obtained. The value of this tag is a string in the following format: yyyymmddhhMMssth.
• sync contains either Y or N, depending on the data status (synced or not).
• self contains information on the LPAR itself. There is only one self tag per entry.
• group is optional and contains information on the LPAR Group that this LPAR is part of. There is only one group tag per entry.
• set is optional and contains information on the LPAR set that this LPAR is part of. It is possible to have more than one set tag per entry because an LPAR can be part of more than one LPAR Set.
• setcmp  is optional and contains information on the CMP LPAR Set of which this LPAR is part of. It is possible to have more than one setcmp tag per entry because an LPAR can be part of more than one CMP LPAR Set.
• name is included in the group, set, and setcmp tags and contains the name of the corresponding LPAR Group or (CMP) LPAR Set.
• int is included in the self, group, set and setcmp tags. It contains a normalized CPU consumption value measured during a 5-minute interval for the corresponding entity.
• avg is included in the self, group, set and setcmp tags. It contains the 4-Hour average value for the corresponding entity.
• limit is included in the self, group, set and setcmp tags. It contains the CPU consumption limit set for the entity. If empty, it means that there is no limit set. The value of this tag is usually the same in all entry tags for the corresponding entities. This is because changing the limit is an involved procedure that requires re-activating a new policy and/or making some system changes.
• intcmp is included in the setcmp tag only. It contains a normalized CPU consumption value measured during a 5-minute interval for the corresponding entity in the CMP scope.
• avgcmp  is included in the setcmp tag only. It contains the 4-Hour Average value for the corresponding entity in the CMP scope.
• limitcmp  is included in the setcmp tag only. It contains the CPU consumption limit set for the CMPLPAR Set in the CMP scope. If empty, it means that there is no limit set.
• cap_level  is included in the self tag only. It indicates if one of the defined capacity levels has been reached. If so, the level number (1-5) is the value of the tag. If not, the tag is empty.
• cap_percent  is included in the self tag only. This value will tell you how much time of this 5 minute measurement interval the LPAR has been capped. The value is in the percentage form. 100% indicates that the LPAR has been capped for the entire 5 minute interval. 0% indicates that the LPAR was not capped at all.
• cap_reason  is included in the self tag only. If one of the defined capacity levels has been reached, it indicates the entity for which the corresponding limit was defined. Examples of the possible values: LPAR(SLM1), GROUP(ALLSLM), SET(ALLSLM), SETCMP(ALLZOS), SETCMP(ALLZOS,CMP). The difference between the last two reasons is that CMP LPAR SETALLZOS has two limits--one in the CPC scope and another in the CMP scope. To indicate the latter case, comma CMP is appended to the SET name.

HCA response example

HSL request/response

This request can be used to obtain a Batch Service Level for the current time interval. The time interval is five minutes long starting at a five minute boundary (hh:00, hh:05, and so on).

HSL request

The body_hsl block of the request is empty.

HSL request example

HSL response

The body_hsl block of the response contains a list of entry tags. Each entry block represents the average Batch Service Level during a certain time interval and has the following tags:

• date_time The time stamp indicating the date and time for the last Batch Service Level sample used to calculate the average value. The time stamp has the following format: yyyymmddhhMMssth.
• gs_ix The "bucket" index representing the average Service Level value for the General Services queue. Its value is an integer number in the range 0-12.
• ps_ix The  "bucket"  index representing the average Service Level value for the Production Services queue. Its value is an integer number in the range 0-7 or number 12. This is because jobs in the Production Services queue can never be in the buckets with indices 8-11.

The entry tags are sent in the order of the date_time values with the most recent one coming first. Under certain circumstances, the Batch Selection point information may not be available for one or more intervals in one or both queues. This can happen during periods of low activity when too few samples are available to calculate the selection point average. If this is the case, the corresponding gs_ix and/or ps_ix tags may have no index value (empty strings).

 HSL response example

HSQ request/response

This request can be used to obtain cached data containing the number of jobs in the General Services Queue for each minute during the last n-minute interval. The n is defined in the TM/GUI parameters.

HSQ request (versions 0001 and 0002)

The body_hsq block of the request is empty.

HSQ request example

HSQ response

The body_hsq block of the response contains a list of entry tags. Each entry block represents the state of the queue at a certain time and has the following tags:

Version 0001

• date_time contains date and time this entry represents. The format of the value is: yyyymmddhhMMssth.
• gs_queue contains the number of jobs in General Services Queue at the time.

The entries occur in the order of date_time value with the most recent date_time appearing first in the list.

Version 0002

The versions 0001 and 0002 of the request are identical. But the version 0002 response has an additional tag in the entry block:

• ps_queue contains the number of jobs in Production Services Queue at the time.

Thus, the version 0002 of the HSQ request/response can be used to obtain the cached data containing the number of jobs in both General Services and Production Services Queues for each minute during the last n-minute interval.

HSQ response example

HXA request/response

This request can be used to retrieve the MPX Status information from Automation for Batch ThruPut. The information typically covers a few hours of MPX status data and includes the CPU consumption 4-hour average as well as CPU consumption sample values for all MPX LPAR Sets defined in the current SLM policy.

HXA request

The body_hxa block of the request can be empty (in which case the entire set of data is going to be returned in the response) or it can specify that only certain information is required. In the latter case one or more of the following tags can be specified in the body_hxa:

• mpx_lpar_set contains an MPX LPAR Set name.
• cpc contains a CPC name.

HXA request example

HXA response

The body_hxa block of the response contains a list of mpx_lpar_set tags, one per each MPX LPAR Set known to Automation for Batch ThruPut. Each of these tags contains the following mandatory tag:

• name contains the name of the MPX LPAR Set.

Provided there was enough time for Automation for Batch ThruPut to collect the data, each mpx_lpar_set tag also contains a list of entry tags with the capacity management data covering few last hours and sorted by the date and time values so that the most recent entry goes first.

Each entry contains the following tags:

• date_time contains the date and time of the moment the data in this entry tag was obtained. The value of this tag is a string in the following format: yyyymmddhhMMssth.
• self contains information on the MPX LPAR Set itself. There is only one self tag per entry.
• cpc  contains information on the total CPU consumption by all LPARS of the MPX LPAR Set that is part of this CPC. It is possible, and likely, to have more than one cpc tag per entry.
• name contains the name of the CPC and is included in the cpc tags.
• int contains a normalized CPU consumption value measured during a 5-minute interval and is included in the self and cpc tags.
• avg contains the 4-Hours Average value and is included in the self and cpc tags.
• limit this tag is included in the self tag only. It contains the CPU consumption limit set for the MPXLPAR Set. If empty, it means that there is no limit set. The value of this tag is usually the same in all entry tags for the corresponding MPX LPAR Set. This is because changing the limit requires reactivation of a new policy.

HXA response example

In addition to the generic error codes, the following request-specific error codes in the error_code tag of the failed response are possible:

0001 TM/GUI data missing in Data Space.

0002 No data was collected in the TM/GUI data space. The historical MPX data container is empty. TM address space was just restarted.

PSQ request/response

This request is used to obtain counts for jobs in the Production Services (PS) Queue. Each PS queue is divided into 9 buckets:

• Minimum (index 0)
• Minimum + 1/4 (index 1)
• Minimum + 2/4 (index 2)
• Minimum + 3/4 (index 3)
• Target (index 4)
• Target + 1/4 (index 5)
• Target + 2/4 (index 6)
• Target + 3/4 (index 7)
• Late (index 12)

The number in parenthesis represents an index of the queue bucket.

It is evident that the indices have gaps. This is because a PS queue can be viewed as a GS queue with some buckets restricted for critical jobs to go in the Late bucket. In this model, jobs in the Production Services Queue are never placed in any of the Acceptable buckets. When a Production Services job is leaving the Target + 3/4 bucket it jumps directly to the Late bucket.

As a result, there are 9 x (number of service groups) groups of counts in the response XML. Each group of counts contains 4 counts representing jobs with the following properties:

• Non-delayed, non-exceptional
• Delayed, non-exceptional
• Non-delayed, exceptional
• Delayed, exceptional

PSQ request

The body_psq block of the request may be empty or it may contain the following tags:

• included containing  service  group  names.  It  may  be  empty.  Only  jobs  that  belong  to  the  service  groups listed here will be included in the response XML.
• excluded containing service group names. It may be empty. Jobs that belong to the service groups listed here will be excluded from the response XML.
• auto contains either text Y or N. Y means that the request is performed in the auto-refresh mode. N means that the request is initiated manually, by user pressing the refresh button (or its equivalent).

When the included section contains service group names, it is assumed that only jobs from the service groups listed in it are going to be included in the response. When the excluded section contains service group names, it is assumed that jobs from all service groups but those listed in the section are going to be included in the response. It is, therefore, meaningless to include service group names in both included and excluded sections.

A special service group named $$$PCS is reserved for PCS jobs. PCS jobs are those jobs submitted by the CA 7 Scheduler and recognized accordingly by the PCS component of Automation for Batch ThruPut.

Another special service group name is $$$DEF (default). Jobs are assigned to this group when the name of the service group they were requested to be put in does not exist in the currently active policy. This may happen due to a mistake or after a new policy having a different set of service group names was activated.

Specifying a single group name, such as $$$PCS, within the included block ensures that only the counts for PCS jobs are going to be returned in the response.

Specifying this single group name in the excluded block can be used to obtain non-PCS jobs only.

PSQ response

The body_psq block of the response contains a list of service_group blocks, one for each service group defined in the active policy. Each service_group contains one group_name tag having the group name and 13 - 5 = 8 section tags. Each section tag represents a particular queue bucket in the Production Services queue. They can be identified by a value of ix tag inside the section block. This value is one of the numbers: 1-7, 12 representing the bucket index (see the list of sections above). In addition to the ix tag, each section block contains the following tags:

• nn containing a count for non-delayed non-exceptional jobs.
• dn containing a count for delayed non-exceptional jobs.
• ne containing a count for non-delayed exceptional jobs.
• de containing a count for delayed exceptional jobs.

The sum of the four counts is the total number of jobs that belong to a particular bucket of the Production Services Queue and a particular Service Group.

SGD request/response

This request can be used to obtain detailed information (TM/UDF information) about a particular job.

SGD request

The body_sgd block of the request contains the following tags:

• name contains the job name.
• id contains the job JES ID starting with capital J which is followed by a 7 digit number.

SGD request example

SDG response

The body_sgd block of the response contains the following tags:

• name contains the job name.
• id contains the job JES Id starting with capital J which is followed by a 7 digit number.

In addition to these tags, a list of the section tags is included in the body_sgd block. Each of them has the following tags:

• rm contains the resource manager name, such as SLM and JLS. It indicates what information is provided in this section.
• holding contains either N or Y. Y means that this resource manager has a hold on the job.
• line contains a single line of information. There are as many line tags as many lines are in the information block for this resource manager.

SGD response example

SGJ request/response

This request can be used to obtain a list of jobs in SLM General Services Queue.

SGJ request

The body_sgj block of the request may be empty or it may contain the following tags:

• included contains control center and/or type names. It may be empty. Only jobs that belong to the control centers/types listed here will be included in the response XML.
• excluded contains control center and/or type names. It may be empty. Jobs that belong to the control centers/types listed here will be excluded from the response XML.
• delayed contains one of the following indicators: Y- only delayed jobs should be included, N - only non-delayed jobs should be included, A - both delayed and non-delayed jobs should be included in the response.
• exceptional contains one of the following indicators: Y- only exceptional jobs should be included, N - only non-exceptional jobs should be included, A - both exceptional and non-exceptional jobs should be included in the response.
• section_ix_from contains a number representing the queue bucket index. Only the jobs that belong to the bucket(s) with the index greater of equal to the value specified in this tag are going to be included in the response.
• section_ix_to contains a number representing the queue bucket index. Only the jobs that belong to the bucket(s) with the index lesser of equal to the value specified in this tag are going to be included in the response.

The same control center or type can belong to either included tag or excluded tag, but never to both of them.

SGJ request example

SGJ response

The body_sgj block of the response contains a list of job tags. The job tag, in its turn, consists of the following tags:

• name contains a job name.
• id contains a job JES ID starting with capital J which is followed by a 7 digit number.
• owner contains the job’s owner ID (aka TSO user ID).
• control_center contains a control center name this job belongs to.
• type contains a type this job belongs to.
• i contains batch importance of the job.
• position defines the job queue position and can contain one of the following values:
  • M means that the job belongs to a queue bucket with index 0 (the Minimum bucket)
  • M1 means that the job belongs to a queue bucket with index 1 (the Minimum + 1/4 bucket)
  • M2 means that the job belongs to a queue bucket with index 2 (the Minimum + 2/4 bucket)
  • M3 means that the job belongs to a queue bucket with index 3 (the Minimum + 3/4 bucket)
  • T means that the job belongs to a queue bucket with index 4 (the Target bucket)
  • T1 means that the job belongs to a queue bucket with index 5 (the Target + 1/4 bucket)
  • T2 means that the job belongs to a queue bucket with index 6 (the Target + 2/4 bucket)
  • T3 means that the job belongs to a queue bucket with index 7 (the Target + 3/4 bucket)
  • A means that the job belongs to a queue bucket with index 8 (the Acceptable bucket)
  • A1 means that the job belongs to a queue bucket with index 9 (the Acceptable + 1/4 bucket)
  • A2 means that the job belongs to a queue bucket with index 10 (the Acceptable + 2/4 bucket)
  • A3 means that the job belongs to a queue bucket with index 11 (the Acceptable + 3/4 bucket)
  • C means that the job belongs to a queue bucket with index 12 (the Critical bucket)
• ets contains status of the job as well as its estimated time to selection if it is available.
• ets_code contains a number that can be used to sort the ets values (for example, as a column in a table).

SGJ response example

SPJ request/response

This request can be used to obtain a list of jobs in SLM Production Services Queue.

SPJ request

The body_spj block of the request may be empty or it may contain the following tags:

• included contains service group names It may be empty Only jobs that belong to the service groups listed here will be included in the response XML.
• excluded contains service group names. It may be empty. Jobs that belong to the service groups listed here will be excluded from the response XML.
• delayed contains one of the following indicators: Y - only delayed jobs should be included, N - only non-delayed jobs should be included, A - both delayed and non-delayed jobs should be included in the response.
• exceptional contains one of the following indicators: Y - only exceptional jobs should be included, N - only non-exceptional jobs should be included, A - both exceptional and non-exceptional jobs should be included in the response.
• section_ix_from contains a number representing the bucket index. Only the jobs that belong to the bucket(s) with the index greater or equal to the value specified in this tag are going to be included in the response.
• section_ix_to contains a number representing the bucket index. Only the jobs that belong to the bucket(s) with the index lesser or equal to the value specified in this tag are going to be included in the response.

When the included section contains service group names, it is assumed that only jobs from the service groups listed in it are going to be include in the response. When the excluded section contains service group names, it is assumed that jobs from all service groups but ones listed in the section are going to be include in the response. It is, therefore, meaningless to include service group names in both included and excluded sections.

A special service group name is reserved for PCS jobs: $$$PCS. PCS jobs are the jobs submitted by the CA 7 Scheduler and recognized accordingly by the PCS component of Automation for Batch ThruPut.

Another special service group name is $$$DEF (default). Jobs are assigned to this group when the name of the service group they were requested to be put in does not exist in the currently active policy. This may happen due to a mistake or after a new policy having a different set of service group names was activated. Specifying only one group name ($$$PCS, for instance) in the included block will ensure that only PCS jobs are going to be returned in the response. Specifying this single group name in the excluded block can be used to obtain non-PCS jobs only.

SPJ request example

SPJ response

The body_spj block of the response contains a list of job tags. The job tag in its turn consists of the following tags:

• name contains a job name.
• id contains a job JES ID starting with capital J which is followed by a 7 digit number.
• owner contains the job's owner id (aka TSO user id)
• service_group contains a service group name this job belongs to.
• i contains production importance of the job.
• position defines the job queue position and can contain one of the following values:
  • M means that the job belongs to a queue bucket with index 0 (the Minimum bucket)
  • M1 means that the job belongs to a queue bucket with index 1 (the Minimum + 1/4 bucket)
  • M2 means that the job belongs to a queue bucket with index 2 (the Minimum + 2/4 bucket)
  • M3 means that the job belongs to a queue bucket with index 3 (the Minimum + 3/4 bucket)
  • T means that the job belongs to a queue bucket with index 4 (the Target bucket)
  • T1 means that the job belongs to a queue bucket with index 5 (the Target + 1/4 bucket)
  • T2 means that the job belongs to a queue bucket with index 6 (the Target + 2/4 bucket)
  • T3 means that the job belongs to a queue bucket with index 7 (the Target + 3/4 bucket)
  • C means that the job belongs to a queue bucket with index 12 (the Late bucket)
• ets contains status of the job as well as its estimated time to selection if it is available.
• ets_code contains a number that can be used to sort the ets values (for example, as a column in a table)

SPJ response example