7.1.6 Fixed execution registration API
This API performs fixed execution registration for the specified jobnet.
For details about fixed execution registration, see 4.1.1(3) Fixed execution in the manual JP1/Automatic Job Management System 3 Overview.
For additional information about fixed execution by specifying a specific date and time, see 4.5.2 Adding an execution schedule to a jobnet in the manual JP1/Automatic Job Management System 3 Overview.
- Execution privileges
-
The login JP1 user must have one of the following JP1 permissions for the unit for which fixed execution registration is performed:
-
JP1_AJS_Admin privileges
-
JP1_AJS_Manager privileges
-
JP1_AJS_Operator privileges
-
- Request format
-
- Request line
POST /application/component/apiVersion/objects/definitions/unitName/actions/registerFixedExec/invoke httpVersion
- Message Body
{ "parameters":{ "manager":"manager-host-name-or-IP-address", "serviceName":"scheduler-service-name", "fixedScheduleFrom":"start-date-of-the-fixed-schedule-period", "fixedScheduleTo":"end-date-of-the-fixed-schedule-period", "futureGeneration":future-generation, "startTime":"date-and-time-to-start-jobnet-execution", "passedDaemonStarts":"behavior-when-the-planned-time-has-passed-at-the-startup-of-the-scheduler-service", "holding":whether-to-hold-execution-of-the-jobnet, "macro":[macro-variable-object,...] } }
- API version
-
v1
- Information that uniquely identifies a resource
-
The table below describes the information that uniquely identifies a resource.
If a parameter is not specified or is specified incorrectly, an error with the status code 404 occurs because the resource cannot be uniquely identified.
Information that uniquely identifies a resource
Data type
Description
Required?
unitName
String
Specify the full name of the unit to be requested, by using a character string in the range from 1 to 930 bytes.
Y
- Legend:
-
Y: Required
- Parameter
-
The following table lists and describes the parameters that can be specified for parameters in the request message body.
Table 7‒6: List of parameters for the fixed execution registration API Parameter
Data type
Description of the value
Required?
manager
String
Specify the manager host name or IP address by using a character string in the range from 1 to 255 bytes.
Y
serviceName
String
Specify the scheduler service name by using a character string in the range from 1 to 30 bytes.
Y
fixedScheduleFrom#1
string
Specify this parameter to perform fixed execution registration by specifying a fixed period.
Specify the start date of the fixed schedule period in which a fixed execution schedule is executed, in the YYYY-MM-DD format. 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)#2
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).
Specify the date by using the local date for the scheduler service of the request-destination JP1/AJS3 - Manager.
If you specify the start date of the fixed schedule period, ensure that you specify the end date of the fixed schedule period. If you do not specify the end date, an error occurs.
If you do not want to specify the fixed schedule period, specify null for this parameter, or do not specify this parameter.
--
fixedScheduleTo#1
String
Specify this parameter to perform fixed execution registration by specifying a fixed period.
Specify the end date of the fixed schedule period in which a fixed execution schedule is executed, in the YYYY-MM-DD format. 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)#2
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).
Specify the date by using the local date for the scheduler service of the request-destination JP1/AJS3 - Manager.
If you specify the start date of the fixed schedule period, ensure that you specify the end date of the fixed schedule period. If you do not specify the end date, an error occurs.
If you do not want to specify the fixed schedule period, specify null for this parameter, or do not specify this parameter.
--
futureGeneration#1
int
Specify this parameter to perform fixed execution registration by specifying the number of future generations.
Specify the number of times an execution schedule will be created. You can specify a value in the range from 1 to 99 (unit: generation).
If you do not specify the future generation, do not specify this parameter, or specify 0 for this parameter.
--
startTime#1
String
Specify this parameter to add an execution schedule by specifying the date and time regardless of the schedule definition for the jobnet.
Specify the date and time to start execution of the jobnet in YYYY-MM-DDThh:mm format.
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)#2
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 47 (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 the JP1/AJS3 - Web Console version is 11-10 or later. Before specifying this parameter, make sure that the return value of the version information acquisition API (productVersionNumber) is 111000 or greater.
For details about the version information acquisition API, see 7.1.37 Version information acquisition API.
--
passedDaemonStarts
string
Specify the behavior when the planned time has passed at the startup of the scheduler service, by using a character string constant specified for the PlannedTimePassedType constant. For details about the PlannedTimePassedType constant, see 7.4.3(1) PlannedTimePassedType.
The setting of this parameter is valid only when the startup mode of the scheduler service is warm start or disaster recovery start.
For this parameter, the operation performed when the fixed period or the number of future generations is specified differs from the operation performed when the date and time are specified.
The operation performed is as follows:
-
If the fixed period and the number of future generations are specified without specifying this parameter, an error occurs.
-
If the date and time are specified without specifying this parameter or with null specified for this parameter, IMMEDIATE (execute immediately) is assumed. You can specify this parameter only when the JP1/AJS3 - Web Console version is 11-10 or later and the version of connection-destination JP1/AJS3 - Manager is 11-10 or later. Before specifying this parameter, make sure that the return value of the version information acquisition API (productVersionNumber) is 111000 or greater. Also, make sure that the return value of the API (protocolVersionNumber) that acquires the protocol version of JP1/AJS3 - Manager is 1110 or greater.
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.
--
holding
boolean
Specify whether to hold execution of the jobnet when fixed execution registration is performed. If you want to hold execution, specify true. If you do not want to hold execution, specify false.
If you specify true, hold is set for the first execution generation of generations that are created when execution registration is performed.
If you do not specify this parameter, false is assumed.
You can specify this parameter only when the JP1/AJS3 - Web Console version is 11-10 or later and the version of connection-destination JP1/AJS3 - Manager is 11-10 or later. Before specifying this parameter, make sure that the return value of the version information acquisition API (productVersionNumber) is 111000 or greater. Also, make sure that the return value of the API (protocolVersionNumber) that acquires the protocol version of JP1/AJS3 - Manager is 1110 or greater.
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.
--
macro
object[]
Specify the information to be set for the macro variables used by the jobs under the root jobnet, in the format of an array of the objects of the macro variables.
For details about the macro variable object, see 7.3.5 Macro variable object.
You can specify a maximum of 32 macro variables. If you specify multiple macro variables, ensure that the value of number-of-bytes-for-the-macro-variable-names + number-of-bytes-for-the-passing-information + 4 becomes 4,085 or less. If you specify the same macro variable multiple times, the passing information of the macro variable that is specified for the first time is passed.
If you do not want to pass macro variables, do not specify this parameter, or specify null for this parameter.
--
- Legend:
-
Y: Required
--: Optional
- #1
-
You must specify the fixed period (fixedScheduleFrom and fixedScheduleTo), the number of future generations (futureGeneration), or addition of an execution schedule by specifying the date and time (startTime). If you do not specify a monitoring procedure (or if null is specified), an error occurs.
You can specify the fixed period together with the number of future generations. However, addition of an execution schedule by specifying the date and time cannot be specified with the fixed period or the number of future generations. If they are specified together, an error occurs.
- #2
-
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
Fixed execution registration was successful.
400
Bad Request
An argument 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
-
- Response message body when the fixed period and the number of future generations are specified
-
None (The size of the response message body is 0 bytes.)
- Response message body when the date and time are specified
{ "execID":"execution-ID" }
- Return values
-
- If the fixed period and the number of future generations are specified:
-
None (The size of the response message body is 0 bytes.)
- If the date and time are specified:
-
If the status code is 200, the following information is returned:
Member
Data type
Description
execID
String
Returns the execution ID in the format of @[mmmm]{A to Z}nnnn (for example, @10A200).
- Example 1
-
The following shows an example of using the API that performs fixed execution registration by specifying the period.
- Example request:
POST /ajs/api/v1/objects/definitions/%2FJobGroup%2FJobnet/actions/registerFixedExec/invoke HTTP/1.1 Host: HOSTW:22252 Accept-Language: ja Content-type: application/json X-AJS-Authorization: dXNlcjpwYXNzd29yZA== { "parameters":{ "manager":"HOSTM", "serviceName":"AJSROOT1", "fixedScheduleFrom":"2015-09-07", "fixedScheduleTo":"2015-09-11", "passedDaemonStarts":"IMMEDIATE" } }
- Example 2
-
The following shows an example of using the API that performs fixed execution registration by specifying the future generation number and macro variables.
- Example request:
POST /ajs/api/v1/objects/definitions/%2FJobGroup%2FJobnet/actions/registerFixedExec/invoke HTTP/1.1 Host: HOSTW:22252 Accept-Language: ja Content-type: application/json X-AJS-Authorization: dXNlcjpwYXNzd29yZA== { "parameters":{ "manager":"HOSTM", "serviceName":"AJSROOT1", "futureGeneration":5, "passedDaemonStarts":"IMMEDIATE", "macro":[{"name":"AJS2KEY1","value":"1"},{"name":"AJS2KEY2","value":"2"}] } }
- Example 3
-
The following shows an example of using the API that adds an execution schedule by specifying the date and time regardless of the schedule definition for the jobnet.
- Example request:
POST /ajs/api/v1/objects/definitions/%2FJobGroup%2FJobnet/actions/registerFixedExec/invoke HTTP/1.1 Host: HOSTW:22252 Accept-Language: ja Content-type: application/json X-AJS-Authorization: dXNlcjpwYXNzd29yZA== { "parameters":{ "manager":"HOSTM", "serviceName":"AJSROOT1", "startTime":"2016-09-07T08:30", "passedDaemonStarts":"IMMEDIATE" } }
- Example response (message body):
{ "execID": "@A100" }
- Example 4
-
The following shows an example of using the API that holds starting the first execution of a jobnet during registration for fixed execution.
- Example request:
POST /ajs/api/v1/objects/definitions/%2FJobGroup%2FJobnet/actions/registerFixedExec/invoke HTTP/1.1 Host: HOSTW:22252 Accept-Language: ja Content-type: application/json X-AJS-Authorization: dXNlcjpwYXNzd29yZA== { "parameters":{ "manager":"HOSTM", "serviceName":"AJSROOT1", "fixedScheduleFrom":"2016-09-07", "fixedScheduleTo":"2016-09-11", "passedDaemonStarts":"IMMEDIATE", "holding":true } }