7.1.1 Unit list acquisition API

This API acquires information about the job groups, jobnets, and jobs of a specified unit or under that unit. Specify the unit whose information you want to acquire, by writing conditions. If you write multiple conditions, a list of units that satisfy all conditions is acquired.

If no units satisfy the conditions, a unit list containing no units is returned. Information of the units for which the login JP1 user does not have view permission is not included in the acquisition result. The maximum number of information units that can be acquired is 1,000. If the number of units to be acquired exceeds 1,000, change the conditions to reduce the number of units to be acquired.

Execution privileges

The logged in user must have one of the following JP1 permissions for the unit whose information is to be acquired:

JP1_AJS_Admin privileges
JP1_AJS_Manager privileges
JP1_AJS_Editor privileges
JP1_AJS_Operator privileges
JP1_AJS_Guest privileges

Request format

Request line

GET /application/component/apiVersion/objects/statuses?query httpVersion

API version

Information that uniquely identifies a resource

None

Parameter

The following table lists and describes the parameters that can be specified for query.

Table 7‒1: List of parameters for the unit list acquisition API
Parameter	Description of the value	Required?
`mode`	Specify the fixed value `search`.	Y
`manager`	Specify the manager host name or IP address by using a character string in the range from 1 to 255 bytes.	Y
`serviceName`	Specify the scheduler service name by using a character string in the range from 1 to 30 bytes.	Y
`location`	Specify the full name of the upper unit (job group or jobnet) of the unit whose information you want to acquire, by using a character string in the range from 1 to 930 bytes.	Y
`searchLowerUnits`	Specify whether to acquire the information of the units directly under the unit specified for the `location` parameter or the information of all units under that specified unit, by using a character string constant specified for the `LowerType` constant. For details about the `LowerType` constant, see 7.4.2(1) LowerType. If you do not specify this parameter, `NO` (the units directory under the specified unit) is assumed.	Y
`searchTarget`	Specify whether to acquire only the definition of the unit or both the definition and status of the unit, by using a character string constant specified for the `SearchTargetType` constant. For details about the `SearchTargetType` constant, see 7.4.2(2) SearchTargetType. If you specify `DEFINITION` (definition), the settings for the following parameters are ignored: `execID` `generation` `periodBegin` `periodEnd` `status` `delayStatus` `holdPlan` `execHost` `execHostMatchMethods` If you do not specify this parameter, `DEFINITION_AND_STATUS` (definition and status) is assumed.	--
`unitName`	Specify the name of the unit whose information you want to acquire. You can specify this parameter only when you specify the unit name comparison method by using the `unitNameMatchMethods` parameter. If you specify `No` (do not use for the search condition) for the unit name comparison method, this parameter setting is ignored. The number of bytes that can be specified for the unit name differs, depending on the value specified for the `unitNameMatchMethods` parameter. The following shows the values that can be specified for the `unitNameMatchMethods` parameter, and the number of bytes that can be specified for this parameter: `EQ`, `BW`, `EW`, `NE`, `CO`, `NC`: 1 to 30 bytes `RE`: 1 to 64 bytes	--
`unitNameMatchMethods`	Specify how to compare the unit name, by using a character string constant specified for the `MatchMethods` constant. For details about the `MatchMethods` constant, see 7.4.2(3) MatchMethods. If you specify `NO` (do not use for the search condition), all unit names will be acquired. If you do not specify this parameter, `NO` is assumed.	--
`execID`	Specify the execution ID of the unit whose information you want to acquire, in the format of `@`[`mmmm`]{`A` to `Z`}`nnnn` (for example, `@10A200`). You can specify this parameter only when you specify `EXECID` (acquire the generation of the specified execution ID) for the `generation` parameter. If you specify another value, this parameter setting is ignored.	--
`unitType`	Specify the type of the unit whose information you want to acquire, by using a character string constant specified for the `UnitType` constant. For details about the `UnitType` constant, see 7.4.2(4) UnitType. If you specify `NO` (do not use for the search condition), all unit types will be acquired. If you specify `GROUP` (such as a job group), the settings for the following parameters are ignored: `execID` `generation` `periodBegin` `periodEnd` `status` `delayStatus` `holdPlan` `execHost` `execHostMatchMethods` `releaseID` `releaseInfoSearchMethods` If you specify `ROOT` (such as the root jobnet) or `NET` (such as a jobnet), the settings for the following parameters are ignored: `execHost` `execHostMatchMethods` If you do not specify this parameter, `NO` is assumed.	--
`generation`	Specify the generation of the unit whose information you want to acquire, by using a character string constant specified for the `GenerationType` constant. For details about the `GenerationType` constant, see 7.4.2(5) GenerationType. If you do not specify this parameter, `STATUS` (latest status) is assumed.	--
`periodBegin`	Specify the start time of the generation of the unit whose information you want to acquire, in the `YYYY-MM-DDThh:mm` format. The generations that exist after the specified time will be acquired. You can specify the following values: `YYYY`: Specify the year. The following are the possible values for the year: If the version of JP1/AJS3 - Web Console is 13-00 or later and the version of the connection-destination JP1/AJS3 - Manager is 13-00 or later: `1994` to the value specified for the `SCHEDULELIMIT` environment setting parameter (unit: year)^# In cases other than the above: `1994` to `2036` (unit: year) `MM`: Specify the month. You can specify the month in the range from `01` to `12` (unit: month). `DD`: Specify the day. You can specify the day in the range from `01` to the last day of the specified month (unit: day). `hh`: Specify the hour. You can specify the hour in the range from `00` to `23` (unit: hour). `mm`: Specify the minute. You can specify the minute in the range from `00` to `59` (unit: minute). Specify the date by using the local date for the scheduler service of the request-destination JP1/AJS3 - Manager. You can specify this parameter only when you specify `PERIOD` (specify period) for the `generation` parameter. If you specify another value, this parameter setting is ignored. The end time of the period is specified for the `periodEnd` parameter. Specify a time that is earlier than the end time specified for the `periodEnd` parameter.	--
`periodEnd`	Specify the end time of the generation of the unit whose information you want to acquire, in the `YYYY-MM-DDThh:mm` format. The generations that exist before the specified time will be acquired. You can specify the following values: `YYYY`: Specify the year. The following are the possible values for the year: If the version of JP1/AJS3 - Web Console is 13-00 or later and the version of the connection-destination JP1/AJS3 - Manager is 13-00 or later: `1994` to the value specified for the `SCHEDULELIMIT` environment setting parameter (unit: year)^# In cases other than the above: `1994` to `2036` (unit: year) `MM`: Specify the month. You can specify the month in the range from `01` to `12` (unit: month). `DD`: Specify the day. You can specify the day in the range from `01` to the last day of the specified month (unit: day). `hh`: Specify the hour. You can specify the hour in the range from `00` to `23` (unit: hour). `mm`: Specify the minute. You can specify the minute in the range from `00` to `59` (unit: minute). Specify the date by using the local date for the scheduler service of the request-destination JP1/AJS3 - Manager. Specify this parameter only if you specify `PERIOD` (specify period) for the `generation` parameter. If you specify another value, this parameter setting is ignored. Specify the start time of the period by using the `periodBegin` parameter. Specify a time that is equal to or later than the start time specified for the `periodBegin` parameter.	--
`status`	Specify the status of the unit whose information you want to acquire, by using a character string constant specified for the `UnitStatus` constant. For details about the `UnitStatus` constant, see 7.4.2(6) UnitStatus. If you specify `NO` (do not use for the search condition), all unit statuses will be acquired. If you specify `UNREGISTERED` (unregistered), the settings for the following parameters are ignored: `execID` `generation` `periodBegin` `periodEnd` `delayStatus` `holdPlan` `execHost` `execHostMatchMethods` When you specify `UNREGISTERED` (unregistered), if you are using the jobnet release function, multiple information sets might be acquired for a unit name. In such a case, specify the `releaseInfoSearchMethods` and `releaseID` parameters to identify the acquisition target. If you do not specify this parameter, `NO` is assumed.	--
`delayStatus`	Specify the delay status of the unit whose information you want to acquire, by using a character string constant specified for the `DelayType` constant. For details about the `DelayType` constant, see 7.4.2(7) DelayType. If you do not specify this parameter, `NO` (delay is not considered in the search condition) is assumed.	--
`holdPlan`	Specify whether there is a hold plan for the unit whose information you want to acquire, by using a character string constant specified for the `HoldPlan` constant. For details about the `HoldPlan` constant, see 7.4.2(8) HoldPlan. If you specify `PLAN_YES` (there is a hold plan), information of the generations whose processing is waiting for execution, being held, or has finished will be acquired. In this case, information of the generations whose processing has finished will also be acquired, so information of the generations whose processing is held at re-execution will also be acquired. If you acquire information only of the specified generations (for example, whose processing is waiting for execution or finished execution), specify the `generation` and `status` parameters simultaneously to identify the generations whose information will be acquired. If you do not specify this parameter, `NO` (hold plan is not considered in the search condition) is assumed.	--
`unitComment`	Specify the comment for the unit whose information you want to acquire. You can specify this parameter only when you specify the comment comparison method by using the `unitCommentMatchMethods` parameter. If you specify `NO` (do not use for the search condition) for the comment comparison method, this parameter setting is ignored. If you specify `EQ` (perfect match) for the comment comparison method, and a null character string (0 bytes) for this parameter, the units for which no comment is defined will be acquired. The number of bytes that can be specified for the comment differs, depending on the value specified for the `unitCommentMatchMethods` parameter. The following shows the values that can be specified for the `unitCommentMatchMethods` parameter, and the number of bytes that can be specified for this parameter: `EQ`, `NE`: 0 to 80 bytes `BW`, `EW`, `CO`, `NC`: 1 to 80 bytes `RE`: 1 to 164 bytes	--
`unitCommentMatchMethods`	Specify how to collate the comment of the unit, by using a character string constant specified for the `MatchMethods` constant. For details about the `MatchMethods` constant, see 7.4.2(3) MatchMethods. If you do not specify this parameter, `NO` (do not use for the search condition) is assumed.	--
`execHost`	Specify the host that executes the unit whose information you want to acquire. Specify the name of the agent host that actually executed the unit, not the execution agent defined in the unit definition. You can specify this parameter only when you specify how to collate the execution host name by using the `execHostMatchMethods` parameter. If you specify `NO` (do not use for the search condition) for the execution host name comparison method, this parameter setting is ignored. If you specify `EQ` (perfect match) for the execution host name comparison method, and a null character string (0 bytes) for this parameter, the jobs whose execution host has not been determined and that are waiting for execution will be acquired. The number of bytes that can be specified for the execution host differs, depending on the value specified for the `execHostMatchMethods` parameter. The following shows the values that can be specified for the `execHostMatchMethods` parameter, and the number of bytes that can be specified for this parameter: `EQ`, `NE`: 0 to 255 bytes `BW`, `EW`, `CO`, `NC`: 1 to 255 bytes `RE`: 1 to 514 bytes	--
`execHostMatchMethods`	Specify how to collate the execution host name of the unit, by using a character string constant specified for the `MatchMethods` constant. For details about the `MatchMethods` constant, see 7.4.2(3) MatchMethods. If you do not specify this parameter, `NO` (do not use for the search condition) is assumed.	--
`releaseID`	Specify the release ID of the unit whose information you want to acquire, by using a character string in the range from 1 to 30 bytes. Specify this parameter only if you specify `ID` (release ID) for the `releaseInfoSearchMethods` parameter. If you specify another value, this parameter setting is ignored.	--
`releaseInfoSearchMethods`	Specify how to acquire release information, by using a character string constant specified for the `ReleaseInfoSearchMethods` constant. For details about the `ReleaseInfoSearchMethods` constant, see 7.4.2(9) ReleaseInfoSearchMethods. If you specify `NO` (do not use for the search condition), all release information sets will be acquired. If you do not specify this parameter, `NO` is assumed.	--

Legend:

Y: Required

--: Optional

#

For details about the SCHEDULELIMIT environment setting parameter of the connection-destination JP1/AJS3 - Manager, see 20.4.2(123) SCHEDULELIMIT in the JP1/Automatic Job Management System 3 Configuration Guide.

You can check the version of JP1/AJS3 - Web Console from the return value (productVersionNumber) of the version information acquisition API function. You can check the version of the connection-destination JP1/AJS3 - Manager from the return value (protocolVersionNumber) of the JP1/AJS3 - Manager protocol version acquisition API function.

For details about the version information acquisition API, see 7.1.37 Version information acquisition API.

For details about the JP1/AJS3 - Manager protocol version acquisition API, see 7.1.38 JP1/AJS3 - Manager protocol version acquisition API.

Status code

The following table lists and describes the status codes returned as a response:

Status code	Text description	Description
200	OK	The unit list was successfully acquired.
400	Bad Request	The query character string is invalid.
401	Unauthorized	Authentication is required.
403	Forbidden	The operator does not have execution permission.
404	Not found	The operator does not have access permission for the resource, or the resource does not exist.
409	Conflict	The processing cannot be continued because the request is inconsistent with the current resource status.
412	Precondition failed	The Web Console server is not available.
500	Server-side error	A processing error occurred in the Web Console server.

Response format

Message Body

{
  "statuses":[resource-for-status-monitoring,...],
  "all":whether-all-information-sets-could-be-acquired
}

Return values

If the status code is 200, the following information is returned:

Member	Data type	Description
`statuses`	object[]	Returns an array of resources for status monitoring. If there is no unit that satisfies the condition, an array with 0 elements is returned. For details about the resources for status monitoring, see 7.2.1 Resource for status monitoring.
`all`	boolean	Returns whether all information sets could be acquired. If the number of acquired units does not exceed 1,000, `true` is returned. If the number of acquired units exceeds 1,000, `false` is returned. However, the acquisition results do not contain information about units for which the login JP1 user does not have reference permission. Therefore, even if information about such units has not been acquired, `true` is returned if the number of acquired units does not exceed 1,000.

Member

Data type

Description

statuses

object[]

Returns an array of resources for status monitoring. If there is no unit that satisfies the condition, an array with 0 elements is returned. For details about the resources for status monitoring, see 7.2.1 Resource for status monitoring.

all

boolean

Returns whether all information sets could be acquired.

If the number of acquired units does not exceed 1,000, true is returned. If the number of acquired units exceeds 1,000, false is returned.

However, the acquisition results do not contain information about units for which the login JP1 user does not have reference permission. Therefore, even if information about such units has not been acquired, true is returned if the number of acquired units does not exceed 1,000.

Example

The following shows an example of using the API to acquire the unit list (latest status) directly under the job group (/JobGroup).

Example request:

GET /ajs/api/v1/objects/statuses?mode=search&manager=HOSTM&serviceName=AJSROOT1&location=%2FJobGroup HTTP/1.1
Host: HOSTW:22252
Accept-Language: ja
X-AJS-Authorization: dXNlcjpwYXNzd29yZA==

Example response (message body):

{
  "statuses": [
    {
      "definition": {
        "owner": "jp1admin",
        "customJobType": "",
        "registerStatus": "YES",
        "rootJobnetName": "/JobGroup/Jobnet",
        "recoveryUnit": false,
        "unitType": "ROOTNET",
        "unitComment": "",
        "simpleUnitName": "Jobnet",
        "parameters": "",
        "execAgent": "",
        "execFileName": "",
        "wait": false,
        "jobnetReleaseUnit": false,
        "jp1ResourceGroup": "",
        "unitName": "/JobGroup/Jobnet",
        "unitID": 1560
      },
      "release": null,
      "unitStatus": {
        "status": "RUNNING",
        "execHost": "",
        "startDelayStatus": "NO",
        "nestStartDelayStatus": "NO",
        "endDelayStatus": "NO",
        "nestEndDelayStatus": "NO",
        "startDelayTime": "",
        "endDelayTime": "",
        "changeType": "NO",
        "registerTime": "",
        "jobNumber": -1,
        "retCode": "",
        "simpleUnitName": "Jobnet",
        "schStartTime": "2015-09-02T00:00:00+09:00",
        "reStartTime": "",
        "endTime": "",
        "holdAttr": "NO",
        "startTime": "2015-09-02T22:50:28+09:00",
        "unitName": "/JobGroup/Jobnet",
        "execID": "@A2959"
      }
    }
  ],
  "all": true
}

To Page Top