9 Creating and Using Process Jobs

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:

Section 9.1, "Introduction to Creating Process Job Definitions"
Section 9.2, "Creating and Storing Job Definitions for Process Job Types"

For information about how to use the Runtime Service, see Chapter 14, "Using the Runtime Service".

9.1 Introduction to Creating Process Job Definitions

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 Chapter 14, "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 Chapter 14, "Using the Runtime Service".

9.2 Creating and Storing Job Definitions for Process Job Types

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 Chapter 6, "Using the Metadata Service".

9.2.1 How to Create and Store a Process Job Type

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 9-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 9-1 System Properties for Process Type Jobs

System Property	Description
`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.
`CMDLINE`	Command line required for invoking an external program.
`ENVIRONMENT_VARIABLES`	A comma-separated list of name/value pairs (name=value) representing the environment variables to be set for spawned processes.
`REDIRECTED_OUTPUT_FILE`	Specifies the file where standard output and error streams are redirected for a process job request.
`REQUESTED_PROCESSOR`	The Oracle WebLogic Server node on which a spawned job is executed.
`SUCCESS_EXIT_CODE`	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.
`WARNING_EXIT_CODE`	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.
`WORK_DIR_ROOT`	The working directory for a spawned process.

For more information about system properties, see Chapter 7, "Using Parameters and System Properties."

Example 9-1 shows a sample job type definition with a PROCESS_TYPE.

Example 9-1 Creating an Oracle Enterprise Scheduler JobType and Setting JobType 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;
            }
        }
    }

As shown in Example 9-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 Section 6.2, "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.

9.2.2 How to Create and Store a Process Type Job Definition

To use process type jobs, you need to create and store a job definition.

Note:

Once 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 9-1 shows how to create a job definition using the job definition constructor and the job type. Table 9-1 describes some of the system properties that are associated with the job definition.

As shown in Example 9-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 Section 6.2, "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.

9.3 Using a Perl Agent Handler for Process Jobs

Oracle Enterprise Scheduler requires a Perl agent to manage individual process jobs. The Perl agent is responsible for validating, spawning, monitoring and controlling process job execution, as well as returning the exit status of process jobs to Oracle Enterprise Scheduler. The Perl agent also monitors Oracle Enterprise Scheduler availability and handles job cancellation requests. In the event of abnormal job termination (or job cancellation requests), the Perl agent 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 Perl agent can generate its log under the /tmp folder. This 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 Perl agent requires Oracle Perl version 5.10 or later.