| Oracle® Fusion Applications Developer's Guide for Oracle Enterprise Scheduler 11g Release 1 (11.1.1.5) Part Number E10142-01 |
|
|
View PDF |
| Oracle® Fusion Applications Developer's Guide for Oracle Enterprise Scheduler 11g Release 1 (11.1.1.5) Part Number E10142-01 |
|
|
View PDF |
Using Oracle Enterprise Scheduler you can define parameters in the metadata service and you can define new parameters or provide new values for existing parameters in the runtime service when you submit a job request. A given parameter may represent a value for an Oracle Enterprise Scheduler system property or a value for an application-specific parameter.
This chapter includes the following sections:
You can define Oracle Enterprise Scheduler parameters as follows:
In metadata associated with a job definition, a job type, or a job set.
In the request parameters when a job request is submitted. A request parameter can override a parameter specified in metadata or can specify a value for a parameter not previously defined in the metadata associated with a job request (subject to certain constraints). You can also add new parameters or update parameter values (subject to certain constraints) after a job request has been submitted.
Oracle Enterprise Scheduler System Properties are parameters with names that Oracle Enterprise Scheduler reserves. For some system properties Oracle Enterprise Scheduler also defines the values or provides a default value if you do not specify a value. For more information on the Oracle Enterprise Scheduler system properties, see Section 5.4, "Using System Properties".
Oracle Enterprise Scheduler parameters and system properties are case sensitive. For example the parameter name USER_PARA and user_para represent different parameters in Oracle Enterprise Scheduler.
When you use parameters note that Oracle Enterprise Scheduler reserves the names starting with "SYS_" (case-insensitive) for Oracle Enterprise Scheduler defined system properties. Thus, you should not use application-level parameters with names that start with "SYS_" (case-insensitive).
When submitting a job request, Oracle Enterprise Scheduler combines parameters specified in the job metadata with any submission parameters to form the runtime request parameters. The runtime parameters are saved to the database runtime store and used for subsequent processing of the request. The metadata parameters are obtained from the job definition, job type, and if applicable, the job set as they are defined in the metadata repository at the time of submission. Any subsequent changes to the metadata is normally not seen or used as the request is processed. Oracle Enterprise Scheduler resolves parameter conflicts for parameters with the same name associated with the job metadata or the submit parameters.
A parameter conflict can occur in the following cases:
A parameter is defined repeatedly with different values. For example if the SystemProperty.PRIORITY property is set with different values in the job type and in the job definition associated with a request.
A parameter is defined repeatedly and at least one definition is specified as read-only with the ParameterInfo readonly flag set to true.
To resolve conflicts with parameters Oracle Enterprise Scheduler uses one of the following conflict resolution models and the parameter value inheritance hierarchy shown in Table 5-1:
Last definition wins: used when the same parameter is defined repeatedly with the readonly flag set to false in all cases. In the last definition wins model, conflicts are resolved according to the precedence rules where the highest level wins (last definition). For example a property specified at the job request level wins over the same property specified at the job definition level.
First read-only definition wins: used when the same parameter is defined repeatedly and at least one definition is read-only (the ParameterInfo readonly flag is set to true.) In the first read-only definition wins model, parameter conflicts are resolved according to the precedence rules shown in Table 5-1, lowest level wins. For example a readonly parameter specified at the job type definition level wins over the same property specified at the job definition level, read-only or not.
Table 5-1 Parameter Precedence Levels
| Object | Level |
|---|---|
|
|
1 - Lowest Level |
|
|
2 |
|
job set step |
3 |
|
|
4 |
|
Job request (via |
5 - Highest Level |
Figure 5-1 illustrates the order of precedence taken by parameters defined in various components.
In the case of a job request, the parameters defined by the job type take first precedence, followed by the parameters defined in the job definition. The parameters submitted with the job request take final precedence. In the case of a job set request, the parameters defined in the job set take first precedence, followed by the parameters defined by the job request run as a child of the job set.
When the job set step parameters are materialized, if the job set defines any of the following system properties as read-only, and those properties are defined in the definition of the topmost job set, that is the job set of the absolute parent, the job set values will override the values set at the job set step level. This causes every definition, job definition or job set definition, that runs in the context of a specific job set to run with the same values.
PRIORITY
REQUEST_EXPIRATION
RETRIES, only if the step definition value is > 0
There is an exception for RETRIES because a value of 0 may mean that the job is not capable of being restarted. So if a step is defined with RETRIES = 0, it is not overridden, but if the step has RETRIES > 0, it will be overridden with the job set value.
Properties for a job set step request are materialized during the processing of a job set when the step is reached. Properties for a job step request are materialized in the following order.
Job type and job definition (if the step is a job definition) or job set (if the step is a job set).
Job set step.
Parent request properties and system properties (parent is step's parent job set).
Scoped request properties.
Figure 5-2 illustrates the parameter precedence for job set steps.
When job sets include steps that are job sets, this is a nested job set. For a nested job set, the precedence shown in Table 5-1 applies. When a nested job set is reached, Oracle Enterprise Scheduler applies the parameters of the parent request and the parameters of the parent request follow the same precedence. The effect is that parameters of the parent request, job set and job set step are inherited by nested job sets.
Oracle Enterprise Scheduler metadata includes parameters that you can associate with a metadata object. The parameters can include both application level parameters and system properties for a given definition (metadata object). An instance of the ParameterList class declares the parameters for a given job definition, job type or job set. To set parameters for a given job definition, job type, or job set definition, you can use a ParameterList object with the setParameters() method for the metadata object or you can use the constructor and supply a ParameterList. To supply parameter information in a parameter list, each ParameterList object includes ParameterInfo objects that represent parameters, such that each parameter is defined with properties as shown in Table 5-2.
Table 5-2 ParameterInfo Parameter Properties
| Parameter Property | Description |
|---|---|
|
Name |
Specifies the parameter name. |
|
Value |
Specifies the parameter value. |
|
Readonly |
This boolean flag can be set for each parameter. This flag indicates whether the parameter is read-only. When Note that the value of a read-only parameter can be changed in the object itself where this parameter is defined. For example if this parameter is defined in a job type as a read-only parameter, its value can be changed in the job type definition itself, but a job definition that uses the job type or a request submission parameter cannot override the value, subject to the conflict resolution rules specified for parameter values. For more information, see Section 5.1.2, "What You Need to Know About Parameter Conflict Resolution and Parameter Materialization". |
|
Legacy |
A boolean that specifies that a parameter should be visible when used in a GUI. |
|
DataType |
Values can only be one of the supported types, including: Boolean, Integer, Long, String, and |
You can set parameters at different levels appropriate to parameter precedence rules for a job request. For example, you can set parameters that apply for a job type, a job definition, a job set, a job set step, or a request submission parameter. For information about the precedence rules, see Section 5.1.2, "What You Need to Know About Parameter Conflict Resolution and Parameter Materialization".
Example 5-1 shows code that uses a ParameterList to set parameter and system property values in a metadata object.
Example 5-1 Adding Parameters and System Properties in a Metadata Object
String name = "JobDescription_name";
MetadataObjectId jobtype;
.
.
.
JobDefinition jd = new JobDefinition(name, jobtype);
ParameterList parlist = new ParameterList();
parlist.add(SystemProperty.APPLICATION, "METADATA_UNITTEST_APP", false);
parlist.add(SystemProperty.PRODUCT, "METADATA_UNITTEST_PROD", false);
parlist.add(SystemProperty.CLASS_NAME, "oracle.as.scheduler.myself", false);
parlist.add(SystemProperty.RETRIES, "2", false);
parlist.add(SystemProperty.REQUEST_EXPIRATION, "60", false);
parlist.add("MyProp", "Value", false);
parlist.add("MyReadOnlyProp", "readyOnlyValue", true);
jd.setParameters(parlist);
Example 5-1, shows the following important steps for using parameters with a metadata object:
You need a reference to a metadata service handle to create the metadata object where you want to add parameters.
You need to use the ParameterList add() method to add parameter information.
You can use a SystemProperty as the name for a parameter to specify a value for a system property.
You can specify an application specific property by using a name that you define with the parameter information in a ParameterList.
You need to use a metadata object setParameters() method to apply the parameters specified in the ParameterList to the metadata object. In this case, use the job definition setParameters() method.
You can specify parameters when a job request is submitted by supplying a RequestParameters object with submitRequest(). A request parameter can override a parameter specified in metadata or can specify a value for a parameter not previously defined in the metadata associated with a job request (subject to certain constraints). You can also use the runtime service setRequestParameter() method to set or modify request parameters (subject to certain constraints) after the request has been submitted.
The submitRequest() method will validate each request parameter against its definition in the metadata, if one exists. Such validations include checking the data type of the parameter against the data type specified in the metadata, checking the read-only constraint for the parameter, and so on. If a given request parameter does not exist in the corresponding metadata, the data type for the parameter is determined by doing an instanceof on the parameter value. The data type of a request parameter value must be one of the supported types specified by ParameterInfo.DataType.
If the value of a request parameter is null and the property has not been assigned in the metadata, it defaults to the STRING data type when calling submitRequest(). Oracle Enterprise Scheduler assigns a null value to the parameter. As such, a parameter need not be assigned in the metadata.
The RuntimeService setRequestParameter() method, which is similar to updateRequestParameter(), allows a previously undefined request parameter to be set by a job during execution.
When you submit a job request you set a parameter in a RequestParameters object. This parameter may represent an Oracle Enterprise Scheduler system property or an application-specific parameter. The RequestParameters parameter value may be used to override a parameter specified in metadata, or to specify the value for a parameter not previously defined in metadata associated with the job request.
Example 5-2 shows code using a RequestParameters object with the add() method to set a system property value.
Example 5-2 Using the PRIORITY System Property with Request Parameters
import oracle.as.scheduler.RequestParameters;
import oracle.as.scheduler.MetadataObjectId;
import oracle.as.scheduler.RuntimeService;
import oracle.as.scheduler.RuntimeServiceHandle;
import oracle.as.scheduler.SystemProperty;
RuntimeService runtime;
RuntimeServiceHandle rs_handle;
MetadataObjectId jobSetId;
int startsIn;
long requestID = 0L;
RequestParameters req_par = new RequestParameters();
req_par.add(SystemProperty.PRIORITY, new Integer(7));
Calendar start = Calendar.getInstance();
start.add(Calendar.SECOND, startsIn);
requestID =
runtime.submitRequest(rs_handle,"My job set", jobSetId, start, req_par);
.
.
.
The example assumes that there is a user-created runtimeServiceHandle named rs_handle.
The RequestParameters object is a container for all the parameters for a request. Some of the RequestParameters methods take a step ID as an argument. Such methods allow you to specify parameters for a job set at request submission, where parameters can be specified for, or scoped to, individual steps associated with a job set request. For such methods, the step ID argument identifies the step within the job set to which the given parameter applies. For non-job set requests, the step ID does not apply, but you can use the parameter as required by your application requirements.
When a step ID is specified in a RequestParameters method such as add(), you need to specify the step ID using the following format:
id1.id2.id3...
where the fully qualified step ID identifies the unique step, node, in the job set hierarchy (tree).
Parameters without a step ID in a job set request are treated as global parameters and they apply to each step of the job set request. The step ID argument for RequestParameters provides the capability to support shared parameters, where the parameter can apply to both a job set and either a job definition or a job type.
Oracle Enterprise Scheduler prepends the step ID to the name in the form of stepId:name to generate the unique identifier, with a colon as a separator.
Example 5-3 shows code using a RequestParameters object with a step ID specified with the add() method to set a system property value for a step in a job set.
Example 5-3 Using the CLASS_NAME System Property with Job Set Request Parameters
import oracle.as.scheduler.RequestParameters;
import oracle.as.scheduler.MetadataObjectId;
import oracle.as.scheduler.RuntimeService;
import oracle.as.scheduler.RuntimeServiceHandle;
import oracle.as.scheduler.SystemProperty;
RuntimeService runtime;
RuntimeServiceHandle rs_handle;
MetadataObjectId jobSetId;
int startsIn;
long requestID = 0L;
RequestParameters req_par = new RequestParameters();
req_par.add(SystemProperty.PRIORITY, "stepId-1", new Integer(8));
req_par.add(SystemProperty.PRIORITY, "stepId-2.stepId-1", new Integer(6));
Calendar start = Calendar.getInstance();
start.add(Calendar.SECOND, startsIn);
requestID =
runtime.submitRequest(rs_handle,"My job set", jobSetId, start, req_par);
.
.
.
The example assumes that there is a user-created runtimeServiceHandle named rs_handle.
Oracle Enterprise Scheduler represents parameter names that are known to and used by the system in the SystemProperty class. You can specify system properties as parameter names in the application metadata and using request parameters when a request is submitted. Oracle Enterprise Scheduler sets certain system properties when a request is submitted or at some point in the life cycle of a request.
Table 5-3 lists the available system properties, as defined in oracle.as.scheduler.SystemProperty. Most system properties are common to all job types while some system properties are specific to a particular job type, as indicated in the descriptions in Table 5-3.
When you use parameters, note that Oracle Enterprise Scheduler reserves the parameter names starting with "SYS_" (case-insensitive) for Oracle Enterprise Scheduler defined properties.
Table 5-3 System Properties
| Name | Description |
|---|---|
|
|
Specifies whether multiple pending requests for the same job definition is allowed. This property has no meaning for a job set step. Type: |
|
|
Specifies the logical name of the Java EE application used for request processing. This property is automatically set by Oracle Enterprise Scheduler during request submission. Type: |
|
|
Specifies the time, in minutes, that the processor waits for an asynchronous request after it has begun execution. Following this period, the request is considered to have timed out. Type: |
|
|
Specifies the process exit code for a process job request that denotes an execution business error. If this property is not specified, the system treats a process exit code of 4 as an execution business error. This property is optional for a process job type. It is not used for other job types. Type: |
|
|
Specifies the Java executable for a Java job request. This should be the name of a Java class that implements the Type: |
|
|
Specifies the command line used to invoke an external program for a Process job request. This property is required for a Process job type. It is not used for other job types. Type: |
|
|
Specifies the logical name of the Java EE application that will be the effective application used to process the request. A job definition, job type, or a job set step can be associated with a different application by defining the Type: |
|
|
Specifies the environment variables to be set for the spawned process of a Process job request.The property value should be a comma separated list of name value pairs (name=value) representing the environment variables to be set. This property is optional for a process job type. It is not used for other job types. Type: |
|
|
Specifies whether instances of a repeating request with an execution time in the past should be generated. Instances are never generated before the requested start time nor after the requested end time. To cause past instances to be generated, you must set this property to TRUE and specify the requested start time as the initial time from which instances should be generated. Note that a null requested start time defaults to the current time. Valid values for this property are:
If this property is not specified, the system defaults to Type: |
|
|
Specifies an identifier for an external portion of an asynchronous Java job. For example, an asynchronous Java job usually invokes some remote process and then returns control to Oracle Enterprise Scheduler. This property can be used to identify the remote process. This property should be set by the job implementation of asynchronous Java jobs when the identifier is known. It is never set by Oracle Enterprise Scheduler. Type: |
|
|
Specifies the name of the Oracle Enterprise Scheduler isolation group to which this request is bound. This property is automatically set by Oracle Enterprise Scheduler during request submission. Type: |
|
|
Specifies input to a request. The input to a serial job set is forwarded as input to the first step only. The input to a parallel job set is forwarded as input to all the parallel steps. Oracle Enterprise Scheduler imposes no format on the value of this property. Type: |
|
|
Specifies the event listener class associated with the request. This should be the name of a Java class that implements the Type: |
|
|
Specifies the locale associated with the request. Type: |
|
|
Specifies output from a request. The output of a serial job set is the Type: |
|
|
Specifies the post-process callout handler class. This should be the name of a Java class that implements the Type: |
|
|
Specifies the pre-process callout handler class. This should be the name of a Java class that implements the Type: |
|
|
Specifies the request processing priority. The priority interval is [0..9] with 0 as the lowest priority and 9 as the highest. Default: If this property is not specified, the system default value used is 4. Type: |
|
|
Specifies the name of the PL/SQL stored procedure to be called for a SQL job request. The stored procedure should be specified using schema.name format. The property is required for a SQL job type. It is not used for other job types. Type: |
|
|
Specifies the product within the application that submitted the request. Type: |
|
|
Specifies the file where standard output and error streams are redirected for a Process job request. This represents the full path of the log file where the standard output and error streams are redirected for the spawned process when the request is executed. This property is optional for a Process job type. It is not used for other job types. Type: |
|
|
Specifies the callout handler processing delay time. This represents the time, in minutes, to delay request processing when a delay is requested by a callback handler. Default: If this property is not specified, the system default used is 5. Type: |
|
|
Specifies an application-specific label for a request. The label, defined by an application or system administrator, allows administrators to group job requests according to their own specific needs. Type: |
|
|
Specifies the expiration time for a request. This represents the time, in minutes, that a request will expire after its scheduled execution time. A expiration value of zero (0) means that the request never expires. If this property is not specified, the system default value used is 0. Request expiration only applies to requests that are waiting to run. If a request waits longer than the specified expiration period, it does not run. After a request starts running the request expiration no longer applies. Type: |
|
|
Specifies the request processor node on which the request should be processed. This allows processor affinity to be specified for a request. If this property is not specified, the request can run on any available request processor node. In general, this property should not be specified. If this property is specified for a request, the request processor's work assignments Type: |
|
|
Specifies the retry limit for a failed request. If request execution fails, the request will retried up to the number of times specified by this property until the request succeeds. If retry limit is zero (0), a failed request will not be retried. Default: If this property is not specified, the system default used is 0. Type: |
|
|
Specifies the Type: |
|
|
Specifies whether the result state of a job set step affects the eventual state of its parent job set. In order for the state of a job set step to be considered when determining the state of the job set, the Type: |
|
|
Specifies an Oracle Enterprise Scheduler job class to be assigned to the Oracle Enterprise Scheduler job used to execute a SQL job request. This property need not be specified unless the job used for a job request is associated with a particular Oracle Database resource consumer group or has affinity to a database service. If this property is not specified, a default Oracle Enterprise Scheduler job class is used for the job that executes the SQL request. That job class is associated with the default resource consumer group. It belongs to the default service, such that it has no service affinity and, in an Oracle RAC environment, any one of the database instances within the cluster might run the job. No additional privilege or grant is required for an Oracle Enterprise Scheduler SQL job request to use that default job class. This property is optional for a SQL job type. It is not used for other job types. Type: |
|
|
Specifies the logical name of the Java EE application for the submitted (absolute parent) request. This property is automatically set by Oracle Enterprise Scheduler during request submission. Type: |
|
|
Specifies the process exit code for a Process job request that denotes an execution success. If this property is not specified the system treats a process exit code of 0 as execution success. This property is optional for a Process job type. It is not used for other job types. Type: |
|
|
Specifies a base directory in the file system where files, such as input and output files, may be stored for use by the request executable. Oracle Enterprise Scheduler supports a configuration parameter that specifies a file directory where requests may store files. At request submission, a time of request submission. Type: |
|
|
Specifies the name of the user used to execute the request. Normally this is the submitting user unless the Type: |
|
|
Specifies the process exit code for a Process job request that denotes an execution warning. If this property is not specified, the system treats a process exit code of 3 as execution warning. This property is optional for a Process job type. It is not used for other job types. Type: |
|
|
Specifies the working directory for the spawned process of a Process job request. This property is optional for a Process job type. It is not used for other job types. Type: |
|
 Copyright © 2011, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|