| Oracle® Clinical Administrator's Guide Release 4.6 Part Number A83791-06 |
|
|
View PDF |
| Oracle® Clinical Administrator's Guide Release 4.6 Part Number A83791-06 |
|
|
View PDF |
The Oracle Clinical parameterized job and report submission facility (PSUB) submits jobs to execute either on the Reports Server or on the back end server. Oracle Clinical uses Oracle Reports for reports, job sets and scheduling. The back end server, also called the PSUB server, handles only jobs implemented in PL/SQL or a third-generation language (3GL). You cannot alter which server is used for a given job; this is determined by the way in which each PSUB job has been coded.
When you take an action runs a report or PSUB job, the job submission form displays the type of job (either PSUB or Reports Server) at the top of the form.
Use the information in this section to manage PSUB jobs, such as:
reviewing the installation
diagnosing and recovering from installation failures, and
understanding how other system changes affect the consistency of the installation.
Note:
For information on managing Oracle Reports jobs, see the Oracle Application Server Reports Queue Manager documentation.This section includes the following topics:
Before submitting batch job requests, a user should have the following:
an OPS$ database account
an account on the PSUB server
a record in the Oracle Accounts table
a log directory on the PSUB server
a log directory for reports output
For instructions on setting up user accounts, see "Setting Up User Accounts".
Note:
On Windows only:All Oracle Clinical users must also have operating system-level accounts on the Windows server running the PSUB service.
The Windows server that runs the PSUB service must belong to the same domain as the Windows server that runs the Oracle database.
This Oracle database security feature prevents unauthorized users from logging in over a network connection. For information on database security, see the your Oracle database documentation.
When a client issues a PSUB request to run a job or report, it sends a message, via a database pipe to the PSUB process, that includes the batch job ID and the primary key into the RXC.BATCH_JOBS table.
When the process receives this message from the database pipe, it reads the job information from the RXC.BATCH_JOBS table and submits the job on the user's behalf with the PSUB Launcher (PSLAUNCH).
In submitting the job, the process creates the following files, where nnnn represents the batch job ID reported to the user in a dialog box
The system creates these files in the user's RXC_LOG directory, which you can see in the Oracle Accounts form:
| Filename format | Description of file contents |
|---|---|
| lnnnn.log | Log file of a user's PSUB job. Note that the initial character is the letter L, not the number one. |
| onnnn.out | Output from a report job. |
| pnnnn.log | Log file for a print request from the Submitted Batch Jobs form. |
The DBMS_PIPE mechanism is an asynchronous protocol, so messages remain in the pipe until read by the process. This means that if a user makes a PSUB request and the process is not running, the request is read when the process is started again. Also, the DBA can safely stop and restart the process in a production environment, provided the delay is not too long. All nonblocking requests are processed, and all blocking requests start when the process comes up or times out.
Blocking jobs are usually of short duration and run in a mode where the system does not allow the user to proceed before their completion. Job completion status (SUCCESS or FAILURE) can be reported to the user immediately after the job completes. Blocking jobs in Oracle Clinical include:
Default layout generation
Moving a data entry screen to production
Generating a Validation Procedure
When an application server submits a blocking job, it sends information through a common database pipe and then waits on an application server-specific receiving pipe for completion (execution) information, which it receives from PSUB. The pipe is maintained by the application and is named with a unique session name. Time-out on the receiving pipe for the application server occurs after 5 minutes, at which point the following message appears: "Failed to get response from server - Batch Job Id <nnnn>". Timing out happens for a variety of reasons, including:
The rxcprod user is not set up properly.
Job execution is slow, so more than 5 minutes elapse before completion.
The PSUB process is not running.
Too many jobs in the batch queue cause the current job to be pending; or it started after the other jobs were completed.
The server machine is too slow for the current load.
The job is executing but is waiting for some resource.
The client is not connected to an OPS$ Oracle account; or the client does not have an operating system account on the server.
The queue is in a stopped state.
Nonblocking jobs include all reports, all jobs launched from the PSUB submission screen, and randomization.
Users are not notified when nonblocking batch jobs complete. To check the job's status, they can execute a query in the Submitted Batch Jobs form, accessible via:
the Job Status button in the Submission of module window
the Batch Jobs item from the Action in-form menu
this command, entered from the rxcprod or system manager account:
$ at -l
This section contains the following topics:
This section contains the following topics:
To start the process on UNIX:
Log on as rxcprod to the UNIX back end server computer.
Run the startup script.
The startup script has the following syntax:
start_psub instance environment verbose
where instance refers to a generic instance name, and environment to a code environment. This starts up PSUB in verbose mode, which means additional information is placed in the process log file to help in debugging PSUB problems.
Log in as rxcprod to start PSUB. For example:
$ start_psub prod 46 verbose
If the process is already running, the script exits with an error message.
The start_psub shell script is run interactively as part of the user's current shell. This script runs the executable rxcpsdps as a background process, which is the PSUB process. Creating the background process should take only a few seconds.
Search for an instance of the rxcpsdps process.
For example:
$ ps -ef | grep -i rxcpsdps rxcprod 0 12750 1 0 15:52:43 ? 0:00 rxcpsdps verbose dev 40 rxcprod 0 22142 1 0 18:50:39 ? 0:01 rxcpsdps verbose test 40
If the PSUB process fails to start, check for errors in rxcpsd_instance_environment_1.log and rxcpsd_instance_environment_2.log in the $RXC_CENTRAL_LOG directory.
The preferred way to stop the PSUB process, because it ensures a graceful exit, is with the following utility, from either the opapps or rxcprod account, after setting the correct environment:
stop_psub instance environment rxc_password
On UNIX systems, you can automate the process of starting and stopping PSUB.
The following example shell scripts for Sun Solaris show how to make the process start automatically at system startup:
# File: /etc/init.d/dbora ORA_HOME=/u01/app/oracle/product/11.1.0.7.0 ORA_OWNER=oracle if [ ! -f $ORA_HOME/bin/dbstart -o ! -d $ORA_HOME ] then echo 'Oracle startup: cannot start' exit fi case "$1" in 'start') echo 'Starting Oracle...' su - $ORA_OWNER -c $ORA_HOME/bin/dbstart su - $ORA_OWNER -c "lsnrctl start" su - rxcprod -c start_psub ;; 'stop') echo 'Stopping Oracle...' su - rxcprod -c stop_psub su - $ORA_OWNER -c $ORA_HOME/bin/dbshut ;; esac # File: start_psub # Start database 1 start_psub venus 46 # Start database 2 start_psub pluto 46
With an OPS$ Oracle account you can automate the shutdown of the PSUB process on UNIX so that it does not require the entry of a password. For example, you can grant the OPS$RXCPROD user access to shut down the PSUB process:
$ sqlplus rxc/password
SQL> grant execute on stop_psub_daemon to ops$rxcprod
The PSUB process may then be shut down with the command:
$ rxcpstop.sh /
The entire process of starting up and shutting down Oracle Clinical instances can be automated. The following example shell scripts for Sun Solaris show how.
# File: /etc/init.d/dbora ORA_HOME=/u01/app/oracle/product/11.1.0.7.0 ORA_OWNER=oracle if [ ! -f $ORA_HOME/bin/dbstart -o ! -d $ORA_HOME ] then echo 'Oracle startup: cannot start' exit fi case "$1" in 'start') echo 'Starting Oracle...' su - $ORA_OWNER -c $ORA_HOME/bin/dbstart su - $ORA_OWNER -c "lsnrctl start" su - rxcprod -c start_psub ;; 'stop') echo 'Stopping Oracle...' su - rxcprod -c stop_psub su - $ORA_OWNER -c $ORA_HOME/bin/dbshut ;; esac # File: stop_psub # Stop database 1 stop_psub venus 46 # Stop database 2 stop_psub pluto 46
This section contains the following topics:
On Windows, you must first install the PSUB process as a service:
Log in to the Windows server as Administrator.
Open a Command Prompt window and enter the following commands:
set p1=database-connect-string set p2=code-environment opa_setup cd %RXC_BIN% rxcpsdps -install database-connect-string database-instance-name
Open the computer's Services control panel.
In the Services dialog box, select the PSUB service and open the Properties window.
In the General tab window, set the Startup Type to Manual.
In the Log On tab window, click This Account, and choose rxcprod. The system prompts you for the password for the rxcprod user.
Enter and confirm the password, and click OK.
Log out from this Administrator session.
After installing the PSUB service and setting its parameters as Administrator, you start it as rxcprod:
Log in as rxcprod.
Open the computer's Services control panel.
In the General tab window, select the PSUB Service and enter values for the Start Parameters as follows:
database-connect-string code-environment [verbose | noverbose] value-of-rxc_root
For example:
db2x2 46 verbose c:\\opapps\\oc\\46
Note that if you need a backslash (\) in the text box, you must double it (\\).
Click the Start button.
Click OK to close the PSUB Service Properties window.
Do not use Enterprise Manager to stop rxcprod sessions on Windows; instead, use the Control Panel on the appropriate local machines.
To stop the PSUB service, follow these steps:
Log in as rxcprod.
Open the Services control panel.
In the Services dialog box, select the PSUB service for the particular database and open the Properties window. The PSUB service for db2x2, for example, might appear as:
psub service db2x2
In the Properties window, click Stop.
This section contains the following topics:
You must first install PSUB; see "Installing PSUB in Windows".
The batch file is required in large databases that take so much time to come up during a server reboot so that the system tries to start PSUB before the database is fully up. In this case the PSUB process does not start and an error like the following appears in the PSUB log file (found in the drive:\opapps\oc\46\log directory):
ERROR:Daemon error while connecting:/@devoc ORA-1033: ORACLE initialization or shutdown in progress
You can specify that the PSUB service starts automatically when the Windows PSUB server re-boots. The service parameters are read from system environment variable with name PSUBSERVICE concatenated with database name, such as:
PSUBSERVICESUN6X2
where "SUN6x2" is the database name.
To create a system environment in Windows:
Select System in the Control Panel.
Select the Advanced tab, select Environment Variables.
Define the System Environment variable in the lower portion of the window, using the format: database id code environment verbose RXC_ROOT
For example, for the variable "PSUBSERVICESUN6X2":
sun6x2 46 verbose t:\\opapps\\oc\\46
Create a batch file called 'psub_start1.bat' in the %RXC_ROOT%/log directory (for example, D:\opapps\oc\46\log) with the following contents.
cmd /c echo Current Date/time= %DATE% %TIME% > psub_start1.log
cmd /c echo Starting Time Delay > psub_start1.log
ping localhost -n 180 > nul
cmd /c net start "PSUB Service database_id" > psub_start1.log
Notes:
"PSUB Service database_id" is the PSUB service name that appears in the Services window (under Administrative Tools from the Control Panel).
You can repeat the following command for different databases if needed:
cmd /c net start "PSUB Service database_id" > psub_start1.log
The 'ping localhost' command introduces a time delay to ensure that the database is up before starting PSUB. You can increase this value—set to 180 seconds (3 minutes) in the example above—if required.
To schedule batch file execution:
Make sure that the Task Scheduler service is started in the Services Window (under Administrative Tools from the Control Panel).
Navigate to Scheduled Tasks in the Control Panel.
Open the Add Scheduled Task wizard and click Next. The Scheduled Task Wizard window appears.
Click on Browse. The Browse window appears.
Go to the directory where 'psub_start1.bat' is saved and then select psub_start1.bat. The task name is displayed as psub_start1. You can modify the name.
Under 'Perform this task, select 'When my computer starts' and click Next.
On the next screen ensure that the ADMINISTRATOR username/password is used.
Click Next and click Finish.
To test, shut down the service if necessary (see "Stopping PSUB Manually in Windows") and double-click on file 'psub_start1.bat' to test that it starts the PSUB service. Verify that the log file 'psub_start1.log' is created in the same directory unless a different path was specified.
In the Services Window under Administrator Tools in the Control Panel, change the Startup Type of the PSUB Service to Manual.
To test, restart the computer and check the Services window to see if the PSUB service has started. If it has, submit a PSUB job such as Batch Validation and check if it runs.
For convenience add a shortcut for psub_start1.bat on the desktop to manually start PSUB by double-clicking the icon.
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.
Tips: 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.
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. 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.
On Windows, you can remove (uninstall) the PSUB service as follows:
Log in as Administrator.
Open a Command Prompt window and enter the following commands:
set p1=database-connect-string set p2=code-environment opa_setup cd %RXC_BIN% rxcpsdps -remove database-connect-string database_instance_name
Log out from this Administrator session.
This section includes the following topics:
The PSUB process 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 process to view the contents of this log file, because it will be locked.However, the following file can be read while the PSUB process is running:
| Operating System | Example path/filename 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.
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/o12345.out (for UNIX), or %RXC_LOG%\o12345.out (for Windows), and a log file name of $RXC_LOG/l12345.log (for UNIX), or %RXC_LOG%\l12345.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.
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.
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. The basic steps are:
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 executionSave a parameter set for each job to be included in the job set, if that has not been done already.
Select Admin, then PSUB Jobs, and Job Sets.
Enter a name for the job set (alphabetic characters only).
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 executionEnter the name of the saved parameter set for the job. list of values available.
Set the timeout limit for the job in minutes. Default: 720 (12 hours).
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.
Select Admin, then PSUB Jobs, and Submit Job Set.
Enter a job set name. An list of values is available.
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.Before starting a PSUB process, 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 process was started and the time it was stopped.
| Name | Type | Description |
|---|---|---|
| PSUB_PROCESS_LOG_ID | NUMBER | |
| HOST | VARCHAR2(64) | |
| SERVER_OS | VARCHAR2(8) | The type of operating system on the server where PSUB runs |
| START_TS | DATE | The time stamp when the PSUB process started |
| CODE_ENVIRONMENT | VARCHAR2(20) | |
| VERBOSE | VARCHAR2(1) | |
| STOP_TS | DATE | The time stamp when the PSUB process 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;
Oracle Clinical manages batch jobs through entries in these reference codelists, refer to Chapter 7, "Reference Codelists" for additional information:
|
 Copyright © 1996, 2011, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|