Managing the PSUB Process

In this section:

• Changing PSUB Job Number Sequencing
  
• Viewing the Status of a Submitted Batch Job
  
• Removing the PSUB Service
  
• Viewing Log and Output Files on the Screen
  
• Using Job Sets to Control Execution Order
  
• Tracking PSUB Processes
  

Changing PSUB Job Number Sequencing

A sequence generator numbers Oracle Clinical submitted batch jobs. By default, at each submission the generator increments by 10 the database seed number you provide during back end installation. Change the default by running alter_psub_seq.sql, found in the INSTALL directory, which lists current settings and asks for:

• start value – number to append to the initial job ID

• increment – the value to add to the job ID for each subsequent job.

For example:

Start Value	Increment	Job ID Numbers
1	10	1, 11, 21, 31…
21	100	21, 121, 221, 321…

The value entered for the "start value" for the PSUB batch job number does not need to be the same as the database seed.

Tip:

If users are accessing multiple databases, keep the batch job numbers generated by each database unique so that the log files do not collide.

Keep the increment of the batch job numbers as small as possible so that batch job numbers do not grow too large.

Viewing the Status of a Submitted Batch Job

You view the status of submitted batch jobs in the Submitted Batch Jobs window, which you access by selecting: Admin, then PSUB/Reports Jobs, and Batch Jobs. This window provides information about the batch jobs, including logs, output file names, and stop jobs you have submitted. The most recently submitted jobs are listed first.

You cannot use this window to update fields. If you are viewing this form while the job is executing, requery the form periodically to see the statuses change, or press the Auto Refresh button. Press the button again to turn off the auto query.

If a particular PSUB process (service) fails, you can start another PSUB service for that database on another server. You do not receive a specific notification if a PSUB service fails.

Oracle Clinical 5.0 and later support one PSUB service per database that can run on any one of the RAC nodes or on a non-RAC server. Since Oracle Clinical cannot detect whether multiple PSUB services are running, such a situation is unpredictable.

Batch job execution statuses:

• ENTERED = User has requested submission of the job.

• SUBMITTED = Job has been submitted to the batch queue.

• SUBMIT_FAILED = Job failed to be submitted to the batch queue.

• STARTED = Job is currently executing.

• SUCCESS = Job has completed successfully.

• FAILURE = Job has completed unsuccessfully. Reason displayed in Failure Text field.

• STOPPED = Job has been stopped by the Stop button.

• STOP_FAILED = Job has not responded to the Stop button.

Removing the PSUB Service

On Windows, you can remove (uninstall) the PSUB service as follows:

1. Log in to the Windows server as Administrator or as a user with administrative privileges.

2. Open a Command Prompt window:

   • If you logged in as Administrator, click Start, then Run, then enter cmd.

   • If you logged in as a different user with administrative privileges, click Start, type cmd in the Start search box, then right-click cmd in the list and click Run as administrator.

3. Set environment variables for the database name and code environment; see Setting Environment Variables on the Command Line

4. Enter the following commands:

   cd %RXC_BIN%
   rxcpsdps -remove database-connect-string database_instance_name
   

5. Log out from this Administrator session.

Viewing Log and Output Files on the Screen

In this section:

• Viewing Logs that Concern Execution of PSUB Processes
  
• Viewing Logs for Individual PSUB Jobs
  
• Printing Output or Log Files
  

Viewing Logs that Concern Execution of PSUB Processes

The PSUB service writes to log files pointed to by the variable RXC_CENTRAL_LOG. RXC_CENTRAL_LOG is defined as $rxc_root/log (on UNIX), or %rxc_root%\log (on Windows). Do not redefine this variable to any other values.

Note:

On UNIX systems, you must stop the PSUB service to view the contents of this log file, because it will be locked.

However, the following file can be read while the PSUB service is running:

Operating System	Example Path and File Name for Log File
UNIX	$RXC_CENTRAL_LOG/rxcpsd_instance_environment_1.log
Windows	%RXC_CENTRAL_LOG%\rxcpsd_instance_environment_1.log

If the process is running in verbose mode more information is written to the log file. You cannot switch from non-verbose to verbose modes while the process is running; you must stop and restart the process to switch mode.

Viewing Logs for Individual PSUB Jobs

Log and output files are always placed in the log directory in your home directory on the server on which PSUB is running. You cannot update log and output file names. The names of the files are structured such that the unique batch job ID for the job is given an:

• "l" prefix for the log file

• "o" for the output file.

For example, a batch job ID of 12345 would have an output file name of:

• $RXC_LOG/user/o12345.out (for UNIX)

• %RXC_LOG%\o12345.out (for Windows)

and a log file name of:

• $RXC_LOG/12345.log (for UNIX)

• %RXC_LOG%\12345.log (for Windows)

To view the output or log file on the screen, click the View Output or View Log button and enter the relevant information in the window.

Printing Output or Log Files

To print the output or log file, press the Print Output or Print Log button. In the pop-up box, specify the printer.

For printing, PSUB uses the standard lp command (on UNIX) or print functions (on Windows). No other environment variables control printing.

Printing from PSUB jobs on a UNIX server to a Windows spooler is not supported.

Using Job Sets to Control Execution Order

You can create a job set to control the execution order when you want jobs that depend on other jobs to execute only if the jobs on which they depend have successfully executed. If any of the jobs in a job set exits with a status of SUBMIT-FAILED or STOPPED, the whole job set aborts with a status of FAILURE.

Note:

All jobs included in a job set must have a saved parameter set. No job included in a job set can have a LOCAL_IMMEDIATE mode of execution

The steps to use job sets to control execution order are:

• Create a Job Set
  
• Submit a Job Set
  

Create a Job Set

1. Save a parameter set for each job to be included in the job set, if that has not been done already.

2. Select Admin, then PSUB Jobs, and Job Sets.

3. Enter a name for the job set (alphabetic characters only).

4. In the Job Label field, enter a short name for the first job in the sequence. You use this name in the fields under JOB LABEL to the right.

   Note:

   No jobs included in a job set can have a LOCAL_IMMEDIATE mode of execution

5. Enter the name of the saved parameter set for the job. list of values available.

6. Set the timeout limit for the job in minutes. Default: 720 (12 hours).

7. The next three fields set the execution order and conditional branching. Enter the job label for the job you want to run next if the current job runs successfully, fails, or times out. If you leave one of these fields blank, the entire job set will stop executing if the current job has the corresponding result. For example, if you leave the Failure field blank and the current job fails, Oracle Clinical stops executing the entire job set.

Oracle Clinical enters the task name for the parameter set you entered.

Repeat this process for each job in the job set.

Submit a Job Set

1. Select Admin, then PSUB Jobs, and Submit Job Set.

2. Enter a job set name. An list of values is available.

3. Click Submit Job.

A job set controls the execution order for a specified set of jobs, so that jobs that depend on other jobs will execute only if the jobs on which they depend have been successfully executed. If any of the jobs in a job set exits with a status of SUBMIT-FAILED or STOPPED, the whole job set aborts with a status of FAILURE. You create job sets by selecting Admin, then PSUB, and Job Set.

Note:

It is not necessary to wait until Oracle Clinical has executed one job before you submit another job.

Tracking PSUB Processes

Before starting a PSUB service, you may want to know the answer to such questions as, "Where was PSUB last running?", or "Where was PSUB running on such-and-such a date?" You can query the table RXC.PSUB_PROCESS_LOG to find out, for a given database, the instance, the environment, and the time a PSUB service was started and the time it was stopped.

Table 8-1 Description of Table RXC.PSUB_PROCESS_LOG

Column Name	Type	Description
PSUB_PROCESS_LOG_ID	NUMBER	ID
HOST	VARCHAR2(64)	Host name
SERVER_OS	VARCHAR2(8)	The type of operating system on the server where PSUB runs
START_TS	DATE	The time stamp when the PSUB service started
CODE_ENVIRONMENT	VARCHAR2(20)	Code environment
VERBOSE	VARCHAR2(1)	Y or N
STOP_TS	DATE	The time stamp when the PSUB service stopped

For example, this query will give you the host and code environment of the last time PSUB was started against the database:

SQL> select start_ts, host, code_environment
  2  from psub_process_log
  3  where start_ts = (
  4  select max(start_ts) from psub_process_log);

This query will list all starts and stops, in time order:

SQL> select start_ts, stop_ts, host, code_environment
  2  from psub_process_log
  3  order by 1;