This chapter describes how to use Oracle Enterprise Scheduler to create process jobs, which run a script or binary command in a forked process.
This chapter includes the following sections:
For information about how to use the Runtime Service, see Using the Runtime Service.
Oracle Enterprise Scheduler lets you run job requests of different types, including: Java classes, PL/SQL stored procedures, or process jobs that run as spawned jobs. To use Oracle Enterprise Scheduler to run process type jobs you need to specify certain metadata to define the characteristics of the process type job that you want to run. You may also want to specify properties of the job request, such as the schedule for when it runs.
Specifying a process type job request with Oracle Enterprise Scheduler is a three step process:
You create or obtain the script or binary command that you want to run with Oracle Enterprise Scheduler. We do not cover this step because we assume that you have previously created the script or command for the spawned process.
Using the Oracle Enterprise Scheduler APIs in your application, you create job type and job definition objects and store these objects to the metadata repository.
Using the Oracle Enterprise Scheduler APIs you submit a job request. For information about how to submit a request, see Using the Runtime Service.
After you create an application that uses the Oracle Enterprise Scheduler APIs, you need to package and deploy the application.
At runtime, after you submit a job request you can monitor and manage the job request. For more information on monitoring and managing job requests, see Using the Runtime Service.
To use process type jobs with Oracle Enterprise Scheduler, you need to locate the Metadata Service and create a job definition. You create a job definition by specifying a name and a job type. When you create a job definition you also need to set certain system properties. You can store the job definition in the metadata repository using the Metadata Service.
For information about how to use the Metadata Service, see Using the Metadata Service .
An Oracle Enterprise Scheduler JobType object specifies an execution type and defines a common set of properties for a job request. A job type can be defined and then shared among one or more job definitions. Oracle Enterprise Scheduler supports three execution types:
JAVA_TYPE: for job definitions that are implemented in Java and run in the container.
SQL_TYPE: for job definitions that run as PL/SQL stored procedures in a database server.
PROCESS_TYPE: for job definitions that are binaries and scripts that run as separate processes under the control of the host operating system.
When you specify the JobType you can also specify SystemProperties that define the characteristics associated with the JobType. Table 14-1 describes the properties that specify how the request should be processed if the request results in spawning a process for a process job type.
Table 14-1 System Properties for Process Type Jobs
| System Property | Description |
|---|---|
|
|
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. |
|
|
Command line required for invoking an external program. |
|
|
A comma-separated list of name/value pairs (name=value) representing the environment variables to be set for spawned processes. |
|
|
Specifies the file where standard output and error streams are redirected for a process job request. |
|
|
The Oracle WebLogic Server node on which a spawned job is executed. |
|
|
The process exit code for a process job request that denotes a successful execution. If this property is not specified, the system treats a process exit code of 0 as a successful completion. |
|
|
The process exit code for a spawned job that denotes a successful execution. If this property is not specified, the system treats a process exit code of 3 as a warning exit. |
|
|
The working directory for a spawned process. |
For more information about system properties, see Using Parameters and System Properties .
Example 14-1 shows a sample job definition with a PROCESS_TYPE.
As shown in Example 14-1, when you create and store a process job type, you do the following:
Use the JobType constructor and supply a String name and a JobType.ExecutionType.PROCESS_TYPE argument.
Obtain the metadata pointer, as shown in Accessing the Metadata Service. Use the Metadata Service addJobType() method to store the JobType in metadata.
The MedatdataObjectId, returned by addJobType(), uniquely identifies metadata objects in the metadata repository using a unique identifier.
Example 14-1 Creating an Oracle Enterprise Scheduler Job Definition and Setting Job Definition Properties
import oracle.as.scheduler.ConcurrentUpdateException;
import oracle.as.scheduler.JobType;
import oracle.as.scheduler.JobDefinition;
import oracle.as.scheduler.MetadataService;
import oracle.as.scheduler.MetadataServiceHandle;
import oracle.as.scheduler.MetadataObjectId;
import oracle.as.scheduler.MetadataServiceException;
import oracle.as.scheduler.ParameterInfo;
import oracle.as.scheduler.ParameterInfo.DataType;
import oracle.as.scheduler.ParameterList;
import oracle.as.scheduler.SystemProperty;
import oracle.as.scheduler.ValidationException;
void createDefinition( )
throws MetadataServiceException,ConcurrentUpdateException,
ValidationException
{
MetadataService metadata = ...
MetadataServiceHandle mshandle = null;
try
{
ParameterInfo pinfo;
ParameterList plist;
mshandle = metadata.open();
// Define and add a PL/SQL job type for the application metadata.
String jobTypeName = "ProcessJobDefType";
JobType jobType = null;
MetadataObjectId jobTypeId = null;
jobType = new JobType(jobTypeName, JobType.ExecutionType.
PROCESS_TYPE);
plist = new ParameterList();
pinfo = SystemProperty.getSysPropInfo(SystemProperty.CMDLINE);
plist.add(pinfo.getName(), pinfo.getDataType(), "/bin/myprogram
arg1 arg2", false);
pinfo = SystemProperty.getSysPropInfo(SystemProperty.
ENVIRONMENT_VARIABLES);
plist.add(pinfo.getName(), pinfo.getDataType(),
"LD_LIBRARY_PATH=/usr/lib", false);
pinfo = SystemProperty.getSysPropInfo(SystemProperty.PRODUCT);
plist.add(pinfo.getName(), pinfo.getDataType(), "HOW_TO_PROD", false);
jobType.setParameters(plist);
jobTypeId = metadata.addJobType(mshandle, jobType, "HOW_TO_PROD");
// Define and add a job definition for the application metadata.
String jobDefName = "ProcessJobDef";
JobDefinition jobDef = null;
MetadataObjectId jobDefId = null;
jobDef = new JobDefinition(jobDefName, jobTypeId);
jobDef.setDescription("Demo Process Type Job Definition " +
jobDefName);
plist = new ParameterList();
plist.add("myJobdefProp", DataType.STRING, "myJobdefVal", false);
pinfo = SystemProperty.getSysPropInfo(SystemProperty.
REDIRECTED_OUTPUT_FILE);
plist.add(pinfo.getName(), pinfo.getDataType(), "/tmp/" + jobDefName
+ ".out", false);
jobDef.setParameters(plist);
jobDefId = metadata.addJobDefinition(mshandle, jobDef, "HOW_TO_PROD");
}
catch (Exception e)
{
[...]
}
finally
{
// Close metadata service handle in finally block.
if (null != mshandle)
{
metadata.close(mshandle);
mshandle = null;
}
}
}
To use process type jobs, you need to create and store a job definition.
Note:
After you create a job definition with a job type, you cannot change the type or the job definition name. To change the job type or the job definition name, you need to create a new job definition.
Example 14-1 shows how to create a job definition using the job definition constructor and the job type. Table 14-1 describes some of the system properties that are associated with the job definition.
As shown in Example 14-1, when you create and store a job definition you do the following:
Use the JobDefinition constructor and supply a String name and a MetadataObjectID that points to a job type stored in the metadata.
Set the appropriate properties for the new job definition.
Obtain the metadata pointer, as shown in Accessing the Metadata Service. Then, use the Metadata Service addJobDefinition() method to store the job definition in the metadata repository and to return a MetadataObjectID.
Oracle Enterprise Scheduler requires an agent handler to manage individual process jobs. The agent handler validates, spawns, monitors and controls process job execution, and also returns the exit status of process jobs to Oracle Enterprise Scheduler. The agent handler also monitors Oracle Enterprise Scheduler availability and handles job cancellation requests. In the event of abnormal job termination (or job cancellation requests), the agent handler terminates the spawned process (along with its children) and exits. It detects the operating system type and uses appropriate system calls to invoke, manage and terminate process jobs.
The Oracle Enterprise Scheduler agent handler can generate its log under the /tmp folder. Log generation must be enabled by setting the Oracle Enterprise Scheduler log level to FINE, FINER or FINEST and ensuring read and write access to the /tmp folder. One log file is generated for each process job invocation. The log file lists the process job invocation log, including a list of environment variables, the command line and redirected output file specified for the process job, process ID and exit code for the process job or errors detected while spawning the process.
Oracle Enterprise Scheduler provides two different agent handlers, the Java agent handler and the Perl agent handler. Both agent handlers are functionally equivalent with the exception that the Java agent handler does not support terminate-spawned-process-on-restart behavior on Windows.
By default, Oracle Enterprise Scheduler uses the Java agent handler for requests in standard and extended mode. It always uses the Perl agent handler for requests in Fusion mode. To use the Perl agent handler in standard and extended request modes, you must add the PerlCommand property to the ess-config.xml file associated with the hosting application running the process job as shown in the following example.
<EssProperties>
<EssProperty key="RequestFileDirectory" value="/tmp/ess/requestFileDirectory"/>
<EssProperty key="RequestFileDirectoryShared" value="false"/>
...
<EssProperty key="PerlCommand" value="/usr/bin/perl"/>
</EssProperties>
You can use token substitution to specify environment dependent values like directory names. Refer to Using Tokens and Logical Clusters for more information.
The Oracle Enterprise Scheduler Perl agent handler requires Oracle Perl version 5.10 or later. Instructions for installing Perl to support process jobs can be found in the chapter "Configuring Perl to Support Process Jobs" in Oracle Fusion Middleware Administering Oracle Enterprise Scheduler.
Note:
If you run Oracle Enterprise Scheduler in a Fusion Applications environment you must use the Perl agent handler.
Individual process jobs can use different locales and encoding as determined by the locale environment variable settings applicable to the process job at execution time. For a process job, Oracle Enterprise Scheduler imports the request log and output file into the content store after completing the request.
Locale environment variables for a process job can be specified at multiple places including the process job definition and the hosting application's ess-config.xml file. The locale resolution logic for a process job uses the following precedence order to determine the effective LC_ALL and LANG environment variable values for the request:
SYS_environment variables associated with the request (highest precedence)
The hosting application's ess-config.xml file
The WebLogic server locale (lowest precedence)
For every process job, the effective locale and encoding is determined based on the above precedence order (with the effective LC_ALL value overriding the effective LANG value). This encoding applies to the log only, and not the output.