Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle Enterprise Scheduler
11g Release 1 (11.1.1.7)

Part Number E24713-04
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

7 Using Parameters and System Properties

This chapter describes how you can define parameters and values in the Oracle Enterprise Scheduler metadata and runtime services 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 defined property.

This chapter includes the following sections:

7.1 Introduction to Using Parameters and System Properties

You can define Oracle Enterprise Scheduler parameters as follows:

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 7.4, "Using System Properties".

7.1.1 What You Need to Know About Application Defined Property and System Property Naming

Oracle Enterprise Scheduler application defined and system properties are case sensitive. For example the application defined property name USER_PARA and user_para represent different parameters in Oracle Enterprise Scheduler.

When you use application defined properties, 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 defined properties with names that start with "SYS_" (case-insensitive).

7.1.2 What You Need to Know About Parameter Conflict Resolution and Parameter Materialization

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 7-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 7-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 7-1 Parameter Precedence Levels

Object Level

JobType

1 - Lowest Level

JobDefinition

2

job set step

3

job set

4

Job request (via RequestParameters passed to submitRequest())

5 - Highest Level


7.1.2.1 What You Need to Know About Job Definition Parameter Materialization

Figure 7-1 illustrates the order of precedence taken by parameters defined in various components.

Figure 7-1 Parameter Precedence

Parameter precedence
Description of "Figure 7-1 Parameter Precedence"

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.

7.1.2.2 What You Need to Know About Job Set Level Parameter Materialization

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.

  1. Job type and job definition (if the step is a job definition) or job set (if the step is a job set).

  2. Job set step.

  3. Parent request properties and system properties (parent is step's parent job set).

  4. Scoped request properties.

Figure 7-2 illustrates the parameter precedence for job set steps.

Figure 7-2 Parameter Precedence for Job Set Steps

Parameter precedence for job set steps
Description of "Figure 7-2 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 7-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.

7.2 Using Parameters with the Metadata Service

Oracle Enterprise Scheduler metadata includes parameters that you can associate with a metadata object. The parameters can include both application defined properties 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 7-2.

Table 7-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 true, subsequent objects in the parameter precedence hierarchy, such as request submission parameter, cannot change the parameter value. Typically a read-only parameter will have a default value that cannot be changed by subsequent objects.

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 7.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 DATETIME that represents a date as a java.util.Calendar object.


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 7.1.2, "What You Need to Know About Parameter Conflict Resolution and Parameter Materialization".

7.2.1 How to Use Parameters and System Properties in Metadata Objects

Example 7-1 shows code that uses a ParameterList to set parameter and system property values in a metadata object.

Example 7-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 7-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 defined 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.

7.3 Using Parameters with the Runtime Service

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.

7.3.1 How to Use Parameters with the Runtime Service

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 defined property. 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 7-2 shows code using a RequestParameters object with the add() method to set a system property value.

Example 7-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.

7.3.2 How to Use Parameters with a Step ID for Job Set Steps

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 7-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 7-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.

7.4 Using System Properties

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 7-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 7-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 7-3 System Properties

Name Description

ALLOW_MULT_PENDING

Specifies whether multiple pending requests for the same job definition is allowed. This property has no meaning for a job set step.

Type: BOOLEAN

APPLICATION

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: STRING

ASYNC_REQUEST_TIMEOUT

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: LONG

BIZ_ERROR_EXIT_CODE

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: STRING

CLASS_NAME

Specifies the Java executable for a Java job request. This should be the name of a Java class that implements the oracle.as.scheduler.Executable interface. This property is required for a Java job type. It is not used for other job types.

Type: STRING

CMDLINE

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: STRING

EFFECTIVE_APPLICATION

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 EFFECTIVE_APPLICATION system property. This property can only be specified via metadata and cannot be specified as a submission parameter.

Type: STRING

ENVIRONMENT_VARIABLES

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: STRING

EXECUTE_PAST

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:

  • TRUE: All instances specified by a schedule are generated regardless of the time of generation.

  • FALSE: Instances with a scheduled execution time in the past (that is, before the time of generation) will not be generated.

If this property is not specified, the system defaults to TRUE.

Type: BOOLEAN

EXTERNAL_ID

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: STRING

GROUP_NAME

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: STRING

INPUT_LIST

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: STRING

LISTENER

Specifies the event listener class associated with the request. This should be the name of a Java class that implements the oracle.as.scheduler.EventListener interface.

Type: STRING

LOCALE

Specifies the locale associated with the request.

Type: STRING

OUTPUT_LIST

Specifies output from a request.

The output of a serial job set is the OUTPUT_LIST of the last step. The output of a parallel job set is the concatenation of the OUTPUT_LIST of all the steps, in no guaranteed order, with oracle.as.scheduler.SystemProperty.OUTPUT_LIST_DELIMITER as a separator.

Type: STRING

POST_PROCESS

Specifies the post-process callout handler class. This should be the name of a Java class that implements the oracle.as.scheduler.PostProcessHandler interface.

Type: STRING

PRE_PROCESS

Specifies the pre-process callout handler class. This should be the name of a Java class that implements the oracle.as.scheduler.PreProcessHandler interface.

Type: STRING

PRIORITY

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: INTEGER

PROCEDURE_NAME

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: STRING

PRODUCT

Specifies the product within the application that submitted the request.

Type: STRING

REDIRECTED_OUTPUT_FILE

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: STRING

REPROCESS_DELAY

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: INTEGER

REQUEST_CATEGORY

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: STRING

REQUEST_EXPIRATION

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: INTEGER

REQUESTED_PROCESSOR

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 oracle.as.scheduler.WorkAssignment (specialization) must allow the execution of such requests, otherwise the request will never be executed. If the specified node is not running, the request will remain in READY state and will not be executed until the node is restarted.

Type: STRING

RETRIES

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: INTEGER

RUNAS_APPLICATIONID

Specifies the runAs identifier that should be used to execute the request. Normally, a request runs as the submitting user. However, if this property is set in the metadata of the job associated with the request, then the request executes under the user identified by this property. This property can only be specified via metadata and cannot be specified as a submission parameter.

Type: STRING

SELECT_STATE

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 SELECT_STATE must be set to true. If SELECT_STATE is not specified on a job set step, the state of the step will be included in the determination of the state of the job set.

Type: BOOLEAN

SQL_JOB_CLASS

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: STRING

SUBMITTING_APPLICATION

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: STRING

SUCCESS_EXIT_CODE

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: STRING

USER_FILE_DIR

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 USER_FILE_DIR property is automatically added for the request if the configuration parameter is currently set and USER_FILE_DIR property was not specified for the request. If the property is added, it will be initialized to the value of the configuration parameter. The property will not be added if the configuration parameter is not set at the time of request submission.

Type: STRING

USER_NAME

Specifies the name of the user used to execute the request. Normally this is the submitting user unless the RUNAS_APPLICATIONID property was set in the job metadata. This property is automatically set by Oracle Enterprise Scheduler during request submission.

Type: STRING

WARNING_EXIT_CODE

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: STRING

WORK_DIR_ROOT

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: STRING