Execution_Function

This function is responsible for coordinating the execution of a Load Set, Data Mart, or Program. It must call several public APIs. These are documented in the Oracle Life Sciences Data Hub Application Programming Interface Guide. See also "Planning for Object Execution".

The execution function must do the following:

1. Fetch the current job ID. Use the public API CDR_PUB_EXE_RUNTIME.GETCURRENTLYEXECUTINGJOBID.
2. If required, build a collection of BLOBs or CLOBs and the corresponding BLOB or CLOB file names for the files that the Oracle LSH Distributed Processing (DP) Server must download when it runs the job, and call public API CDR_PUB_EXE_EXTERNAL.CREATETEMPLOBS to upload the BLOBs or CLOBs to a temporary table. This constitutes the job payload.
3. Build an XML file to send to the DP Server so that the DP Server can start executing the job. To create the XML file, call public API CDR_PUB_EXE_EXTERNAL.GENERATEXMLPAYLOAD. This constitutes the XML payload; see "Example 2-2".
4. Start the job execution by calling public API CDR_PUB_EXE_EXTERNAL.SENDJOB.

   The DP Server then receives the XML payload, downloads the job payload, and starts the job.

5. The function must wait for the job to complete. Call public API CDR_PUB_EXE_EXTERNAL.WAITFORFINALSTATUS.

   The Wait For Final Status API returns 1 if the job completes without warnings, 2 if the job completes with warnings, and 3 if the job fails.

6. If the job succeeds, return 0; else return 1.

   If the job produces one or more outputs, the DP Server loads the BLOB or CLOB file(s) into a temporary table. Your postexecution function should retrieve these files; see "Post_Execution_Function".

Example 2-1 XML Payload Required File Structure

<?xml version="1.0" ?>
<EXEJOB EXEJOB_VERSION="1.0">
<JOB ID="797120006" TYPE="exe">
<SURROGATEJOBID>797120006</SURROGATEJOBID>
<PRREFID>42580001</PRREFID>
<CONFIGID>0</CONFIGID>
<WORKDIR>/user/oracle/sas92/SasWork/ip1dv102</WORKDIR>
<PROGRAM>/user/oracle/sas92/sasNormal</PROGRAM>
<RUNSCRIPT>runSasJob</RUNSCRIPT>
<OUTPUTPATH>Output</OUTPUTPATH>
<PRIORITY>$JOBPRIORITIES$NORMAL</PRIORITY>
<SCHEMA>ZZ_CDR_SI_610001</SCHEMA>
<USERID>797120006</USERID>
<SUBDIRS><DIR NAME="SOURCE" /><DIR NAME="Output" /><DIR NAME="LSH_RS" />
</SUBDIRS>
</JOB>
</EXEJOB>

The Execution_Function requires the following signature:

function <funcname>return number;

Example 2-2 XML Payload

For technologies that run outside the database and therefore use the operator CdrService_1, you can call API CDR_PUB_EXE_EXTERNAL.GENERATEXMLPAYLOAD to produce a default XML payload file. If your technology requires additional functionality—for example, passing additional values to the job—your execution function can produce an XML file with the information your adapter requires. However, your execution function must use the same structure.

The required XML payload file structure is:

<?xml version="1.0" ?>
<EXEJOB EXEJOB_VERSION="1.0">
<JOB ID="id_of_currently_executed_job" TYPE="exe">
<SURROGATEJOBID>id_of_master_job_or_same</SURROGATEJOBID>
<PRREFID>prref_id_of_the_executing_program</PRREFID>
<CONFIGID>0</CONFIGID>
<WORKDIR>/user/oracle/work_directory</WORKDIR>
<PROGRAM>/user/oracle/execution_command_location/execution_command_script</PROGRAM>
<RUNSCRIPT>entry_point_run_script</RUNSCRIPT>
<OUTPUTPATH>Output_path</OUTPUTPATH>
<PRIORITY>$JOBPRIORITIES$NORMAL</PRIORITY>
<SCHEMA>ZZ_account_from_service_instance</SCHEMA>
<USERID>(optional)</USERID>
<SUBDIRS><DIR NAME="first_subdirectory" /><DIR NAME="another_subdirectory" /><DIR NAME="yet_another_subdirectory" />
</SUBDIRS>
</JOB>
</EXEJOB>

Additional information:

• Job ID and Surrogate Job ID. If the job is has only a single process, these two IDs are the same. If there is a master job and a subjob, the Job ID is for the master job's ID and the Surrogate Job ID is for the current subjob.

• Prrefid. The Prrefid of the object being executed. You can use API CDR_PUB_EXE_RUNTIME.GETJOBINFO to get this ID from the CDR_SUBMISSIONS table.

• Configid. The object ID of the object being executed.

• Workdir. This is the location set up under the DP Server directory for jobs of this type and named as the Root Directory in the service definition. It is stored in the ROOT_DIRECTORY column of the CDR_SERVICES table. The DP Server creates a subdirectory here for each job with the job ID as a name, containing the files required for the job.

• Program. (Optional) This value is stored in the PROGRAM column of the CDR_SERVICES table.

• Run Script. Your execution function must generate a script for each job that includes the service instance assigned to the job and provides the actual starting point for the job execution.

• Output Path. Enter the path for the DP Server Home/log directory.

• Priority. The priority requested by the user for the service instance. Possible values are: $JOBPRIORITIES$NORMAL, $JOBPRIORITIES$HIGH, or $JOBPRIORITIES$LOW.

• Schema. The ZZ% account of the service instance. You can use the SERVICE_INSTANCE_ID to get the ZZ account from the table CDR_SERVICE_INSTANCES.

• User ID. This value is not required. It is used only by one shipped adapter.

• Subdirectories.

See the Oracle Life Sciences Data Hub Application Programming Interface Guide for information on execution-related APIs.