ExecuteMultivariate
Launches multivariate Procedure execution.
Syntax
short int ExecuteMultivariate(MvInfo*mv,DCIAPIFlagpreserve_lock),double*return_job_id));
Parameters
mv (in) Criteria for multivariate validation submission. This parameter is a structure of type MvInfo.
preserve_lock (in) A flag indicating whether the lock on the API RDCI record should be preserved or released. If the value is TRUE, the lock remains; if the value is FALSE, the lock is released.
return_job_id (out) A unique identifier of the submitted job.
Return Value
SUCCESS or FAILURE or WARNING.
Comments
This function allows the calling application to submit multivariate Procedures for execution. Execution is performed on demand for a given patient, either on a DCM basis or not, depending upon the criteria chosen for submission. Once this function is called, control is immediately returned to the application; all processing takes place in the background. As soon as the function completes its processing, the results of the execution become available in Oracle Clinical tables. For information about how to define the execution context for a Procedure, see "Procedure Classification".
Results polling
From the API submission, the returned argument (return_job_id) acts as a handle for subsequent status/results polling.
Execution is tracked in a table called MV_EXECUTION_LOG, which contains the information that is listed in the following table.
Table 7-8 MV execution log information
| Column Name | Type/Size | Nullability | Possible Values |
|---|---|---|---|
|
JOB_ID |
NUMBER |
NOT NULL |
- |
|
SESSION_ID |
NUMBER |
NOT NULL |
- |
|
EXECUTION_STATUS |
VARCHAR2(15) |
NOT NULL |
SUBMITTED, EXECUTING, COMPLETED, SUCCESS, WARNING, FAILURE |
|
OUTCOME_STATUS |
VARCHAR2(15) |
- |
- |
|
EXECUTION_SUBMITTED_TS |
DATE |
NOT NULL |
- |
|
EXECUTION_START_TS |
DATE |
- |
- |
|
EXECUTION_END_TS |
DATE |
- |
- |
|
EXECUTION_CONTEXT |
VARCHAR2(15) |
NOT NULL |
- |
|
PROCEDURE_ID |
NUMBER(10) |
- |
- |
|
PROCEDURE_VERSION_SN |
NUMBER(3) |
- |
- |
|
PATIENT_ID |
NUMBER(10) |
NOT NULL |
- |
|
DCM_ID |
NUMBER(10) |
- |
- |
|
TOT_NEW_DISC |
NUMBER(10) |
- |
- |
|
TOT_SAME_DISC |
NUMBER(10) |
- |
- |
|
TOT_OBS_DISC |
NUMBER(10) |
- |
- |
The client application can:
- check EXECUTION_STATUS at any time by using the JOB_ID unique identifier.
- browse all submissions for a given user session by querying the SESSION_ID field.
When the job is submitted a corresponding row is added to the table with an:
- EXECUTION_STATUS of SUBMITTED.
- EXECUTION_SUBMITTED_TS of SYSDATE.
When DBMS_JOB starts executing the job:
- EXECUTION_STATUS is updated to EXECUTING.
- EXECUTION_START_TS is updated to SYSDATE.
Finally, upon execution completion:
- EXECUTION_STATUS changes to COMPLETED.
- OUTCOME_STATUS updates accordingly.
- The total number of new discrepancies is now available in TOT_NEW_DISC.
- The total number of unchanged discrepancies is now available in TOT_SAME_DISC.
- The total number of obsolete discrepancies is now available in TOT_OBS_DISC.
- EXECUTION_END_TS is populated with SYSDATE.
Discrepancy information can be queried from the DISCREPANCY_MANAGEMENT view which is described in the Oracle Clinical Stable Interface Technical Reference Manual.
Error Messages
Table 7-9 Error Messages for ExecuteMultivariate
| Number | Severity | Message |
|---|---|---|
|
284900 |
ERR |
User does not have the privilege to call function in the current mode. |
|
285000 |
ERR |
Function called out of sequence. |
|
285900 |
ERR |
No current OCL database connection open. Use ConnectOCL to connect to OCL database. |
|
291000 |
ERR |
Patient position is invalid. |
|
297100 |
ERR |
Changes pending. |
|
297200 |
ERR |
Invalid execution context. |
|
297300 |
ERR |
Procedure ID is required for SINGLE execution context. |
|
297400 |
ERR |
Procedure version is required for SINGLE execution context. |
|
297500 |
ERR |
Invalid Procedure (nonexistent, retired or pre-3.1 style). |
|
297600 |
WRN |
Procedure is not active or needs to be regenerated. |
|
297700 |
WRN |
Procedure is not compiled. |
|
297800 |
ERR |
DCM ID is required for ON-LINE/DCM execution context. |
|
297900 |
ERR |
DCM ID does not apply for ON-LINE execution context. |
|
298000 |
ERR |
DCM ID does not apply for SINGLE execution context. |
|
298100 |
ERR |
Procedure ID and version must be -1 for ON-LINE and ON-LINE/DCM execution contexts. |
|
298200 |
ERR |
Mandatory patient position ID is missing. |
|
298300 |
ERR |
Invalid preserve lock value. |
|
298400 |
ERR |
Mandatory clinical study ID is missing. |
|
298500 |
ERR |
Mandatory clinical study version number is missing. |
|
298600 |
ERR |
Invalid mode value. |
|
298700 |
ERR |
Invalid debug flag value. |
|
298800 |
ERR |
Mandatory execution context is missing. |
|
300200 |
ERR |
This patient is frozen. |
|
303600 |
ERR |
Invalid patient. |
|
304400 |
WRN |
No procedures qualify for execution. |
|
304500 |
ERR |
Cannot preserve lock as the Received DCI is not locked. |
|
304600 |
ERR |
Function does not exist. |
|
304700 |
ERR |
Privilege does not exist. |
|
304800 |
ERR |
User is not authorized to call this function. |
|
313800 |
ERR |
User is not authorized to call ExecuteMultivariate (not granted RXCLIN_MOD privilege) |
Related Functions
None.
Parent topic: Data Capture API Functions