7 Data Capture API Functions

Syntax

short int ConnectOCL(char *user,  
    char *password,
    char *database,
    short int mode,
    double *sessionid);

Parameters

user (in) The OCL database user name.

password (in) The OCL database user password.

database (in) The OCL database name.

mode (in)

• Either OCL_TEST or OCL_PROD for a standalone application.

• Either 2 (Production) or 3 (Test) to share the same database session.

sessionid (out) The session ID for the current session.

Return Value

SUCCESS or FAILURE or WARNING.

Comments

None.

Error Messages

Related Functions

DisconnectOCL, SetStudyContext, SetExternalContext

Syntax

short int CreateRdci(RdciKeysRecord *rdci_keys_rec,
     int rdcirdcm_mode,
     RdciRecord *rdci_rec );

Parameters

rdci_keys_rec (in) A structure of type RdciKeysRecord containing the key values of the API RDCI record to be created.

rdcirdcm_mode (in) The mode to be used for executing this function. It also stays in effect as the RDCIRDCM mode up to the next call of either CreateRdci or FetchRdci. Values are INITIAL_LOGIN or KEY_CHANGES.

rdci_rec (out) A structure of type RdciRecord that the function fills in with the content of the created API RDCI record.

Return Value

SUCCESS or FAILURE or WARNING.

Comments

The function creates an RDCI record in the API RDCI buffer using the keys passed in, and returns the contents of the API RDCI record created. The component items of an API RDCI record that are not component items of rdci_keys_rec, such as all the numeric ID items, are implicitly assigned by this function. You use this function to:

1. flush the RDCIRDCM buffer.

2. validate each individual non-null item passed in rdci_keys_rec.

   All of these items must pass validation in order for the creation to take place; otherwise no creation takes place and the function returns FAILURE. The RDCI-RDCM buffer will still be empty as a result of the flush.

You use SetRdci to:

• assign values to the items of API RDCI record that are not assigned by CreateRdci.

• change the values of the items assigned by CreateRdci.

Error Messages

Related Functions

SetRdci, GetRdci, ProcessRdci, FetchRdci, WriteRdciRdcm

Syntax

short int DeleteRdci();

Parameters

None.

Return Value

SUCCESS or FAILURE.

Comments

None.

Error Messages

Related Functions

CreateRdci, FetchRdci, GetRdci, ProcessRdci, SetRdci,WriteRdciRdcm

Syntax

short int DeleteRepeat(RepeatId*repeat_identifier );

Parameters

repeat_identifier (in) A parameter of type RepeatId, which contains the unique identifier for the question group repeat and the AuditInfo structure for this repeat.

Return Value

SUCCESS or FAILURE.

Comments

This function re-sequences all repeats following the one that was deleted, if any, by subtracting 1 from the repeat sequence number for all questions in the group in those repeats.

Error Messages

Related Functions

InitializeRdcmResponses, InsertRepeat

Syntax

short int DisconnectOCL();

Parameters

None.

Return Value

SUCCESS or FAILURE.

Comments

None.

Error Messages

Related Function

ConnectOCL

Syntax

short int EnrollPatient(double pat_pos_id,
    PatientRecord *pat_rec);

Parameters

pat_pos_id (in) The PATIENT_POSITION_ID for the patient you want to enroll. This parameter is the unique identifier in the database.

pat_rec (in) A structure of type PatientRecord.

Return Value

SUCCESS or FAILURE or WARNING.

Comments

This function performs a database commit.

Error Messages

Related Functions

None.

Syntax

short int ExecuteMultivariate(MvInfo *mv,
   DCIAPIFlag preserve_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.

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

Related Functions

None.

Syntax

short int FetchRdci(double received_dci_id,

    DCIAPIFlag lock_flag,
    int rdcirdcm_mode,
    RdciRecord *rdci_rec,
    RdcmArr *rdcm_arr);

Parameters

received_dci_id (in) The received_dci_id of the RDCI record to be fetched. Use the stable interface to retrieve the correct ID. See the Oracle Clinical Stable Interface Technical Reference Manual for the documented data model.

lock_flag (in) A flag indicating whether the specified RDCI record should be locked or not. Values are true for a locked record or false for an unlocked record.

rdcirdcm_mode (in) The mode to be used for executing this function. It also stays in effect as the RDCIRDCM mode up to the next call of either CreateRdci or FetchRdci. Values are initial_log-in, first_pass_entry, key_changes, update or browse.

rdci_rec (out) A structure of type RdciRecord that the function fills in with the content of the just-populated API RDCI record.

rdcm_arr (out) A structure of type RdcmArr consisting of an array of the RECEIVED_DCM_IDs of all underlying RDCM records fetched along with the specified RDCI record, and the number of elements in that array that the function fills in.

Return Value

SUCCESS or FAILURE or WARNING.

Comments

FetchRdci flushes the RDCIRDCM buffer, then searches the database for an RDCI record whose received_dci_id equals the parameter received_dci_id. If FetchRdci finds a record, the function:

1. fetches the record, in the specified locking mode, into the API RDCI buffer.

2. fetches all the underlying RDCM records into the API RDCM buffer.

3. returns the contents of the populated API RDCI record in the parameter rdci_rec.

4. returns the RECEIVED_DCM_IDs of all the populated API RDCM records in the array component of the parameter rdcm_arr.

However, if FetchRdci does not find an appropriate record, it fails. It also fails if it finds the record but cannot get the lock required by the parameter lock_flag. A FAILURE happening at any point during the steps above causes the function to stop with FAILURE without reversing the effect of the flush.

Error Messages

Related Functions

GetRdci, SetRdci, ProcessRdci, CreateRdci, WriteRdciRdcm

Syntax

short int FlushRdciRdcm (DCIAPIFlag discard_changes);

Parameters

discard_changes (in) A flag indicating whether or not this function should discard any changes pending in the RDCIRDCM buffer prior to starting its work to flush the buffer. If the value is FALSE the function returns an error if there are changes pending.

Return Value

SUCCESS or FAILURE.

Comments

This function only affects the information in the RDCIRDCM buffer. It does not affect buffered response data. To flush the data, see FlushResponses.

Error Messages

Related Function

WriteRdciRdcm

Syntax

short int FlushResponses(DCIAPIFlag discard_changes,

    DCIAPIFlag preserve_lock);

Parameters

discard_changes (in) A flag indicating whether this function should discard any changes pending in the Responses buffer prior to starting its work to flush the buffer. If the value is FALSE the function returns an error if there are changes pending, leaving the buffer intact.

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.

FALSE – the lock on the API RDCI record is released.

Return Value

SUCCESS or FAILURE.

Comments

This function does not affect the RDCIRDCM buffer. To flush the header file, see FlushRdciRdcm.

Error Messages

Related Functions

SetResponseData, GetResponse, WriteResponses

Syntax

short int GetError(ErrorInfo *err_info);

Parameters

err_info (out) – This parameter contains the information about the error in a structure of type ErrorInfo.

Return Value

SUCCESS or FAILURE.

Comments

If any unexpected internal database errors are encountered during the execution of the APIs — running out of table space, for example — the call stack and the error message encountered by the deepest routine are saved in an internal error stack. Each time GetError is called, the next entry in the stack, if any, is returned; otherwise an error is raised.

Error Messages

Related Function

GetErrorStackSize

Syntax

short int GetErrorStackSize(int *size);

Parameters

size (out) Set to the depth of the error message stack.

Return Value

SUCCESS or FAILURE.

Comments

If any unexpected internal database errors are encountered during the execution of the APIs — running out of table space, for example — the call stack and the error message encountered by the deepest routine are saved in an internal error stack. This function returns the depth of the stack.

Error Messages

Related Function

GetError

Syntax

short int GetManualDiscrepancy(ResponseId *response_identifier,

    DiscInfo *return_discrepancy_info);

Parameters

response_identifier (in) contains the unique identifier for this response in a data structure of type ResponseId.

return_discrepancy_info (out) contains the manual discrepancy information for this response in a structure of type DiscInfo.

Return Value

SUCCESS or FAILURE.

Comments

The response_identifier uniquely identifies the response that is being processed by the external system. Upon calling this function Oracle Clinical locates the response in the database and places the manual discrepancy information for this response into the disc_info structure.

If this is an existing document, the buffers are populated with data from the database. If some manual discrepancy has been previously added for this response, that data would be returned. Otherwise NULL values would be used to populate the output structures.

If this is a new document, and SetManualDiscrepancy has never been called for this response, NULL values would be used to populate the input variable. Otherwise, the data from the last SetManualDiscrepancy call would be returned. This applies also in the case of existing documents.

Error Messages

Related Functions

InitializeRdcmResponses, SetManualDiscrepancy

Syntax

short int GetNumRows(double dcm_group_id,

    int *num_rows);

Parameters

dcm_group_id (in) The question_group_id of the DCM question group.

num_rows (out) The number of rows for this DCM question group.

Return Value

SUCCESS or FAILURE.

Comments

The group_identifier uniquely identifies the question_group. Upon calling this function Oracle Clinical returns the number of rows that are present for this group in the internal buffer.

Error Messages

Related Functions

InitializeRdcmResponses, InsertRepeat, DeleteRepeat

Syntax

short int GetQuestGroupId(GroupId *group_identifier,

    double *group_id);

Parameters

group_identifier (in) contains the unique name of the DCM question group in a data structure of type GroupId.

group_id (out) The internal question_group_id for the DCM question group identified by the group name.

Return Value

SUCCESS or FAILURE.

Comments

The group_identifier uniquely identifies the DCM question group. Upon calling this function Oracle Clinical locates the group in its internal structure and returns the group_id DCM question. The current state of the internal buffers — that is, the current DCM and subset_number — determines the behavior of Oracle Clinical.

Error Messages

Related Functions

GetResponse, GetQuestionId

Syntax

short int GetQuestionId(QuestionId *question_identifier,

    double *question_id);

Parameters

question_identifier (in) contains the unique identifier for the question in a data structure of type QuestionId.

question_id (out) The internal dcm_question_id for the DCM question identified by the question_identifier.

Return Value

SUCCESS or FAILURE.

Comments

The question_identifier uniquely identifies the group that is being processed by the external system. Upon calling this function Oracle Clinical locates the question in its internal structure and gets the question_id. Oracle Clinical functions based on the current state of its internal buffers, that is, the current DCM and the subset_number.

Error Messages

Related Functions

GetResponse, GetQuestGroupId

Syntax

short int GetRdci(RdciRecord *rdci_rec);

Parameters

rdci_rec (out) contains the contents of the API RDCI record in a data structure of type RdciRecord.

Return Value

SUCCESS or FAILURE.

Comments

This function fails if the API RDCI buffer is empty. In order to:

• populate an empty API RDCI buffer, see CreateRdci and FetchRdci.

• change the contents of the API RDCI record, see SetRdci.

• process the API RDCI record as a unit, see ProcessRdci.

Error Messages

Related Functions

SetRdci, ProcessRdci, CreateRdci, FetchRdci, WriteRdciRdcm

Syntax

short int GetRdcm(double received_dcm_id,

    RdcmRecord *rdcm_rec);

Parameters

received_dcm_id (in) The RECEIVED_DCM_ID of the API RDCM record to be returned.

rdcm_rec (out) contains the contents of the specified API RDCM record in a data structure of type RdcmRecord.

Return Value

SUCCESS or FAILURE.

Comments

This function fails if:

• the API RDCI buffer is empty.

• there are changes pending in the API RDCI buffer that have not yet been processed through a call to ProcessRdci.

• there is no API RDCM record whose RECEIVED_DCM_ID equals the parameter received_dcm_id.

In order to:

• populate an empty API RDCI buffer, see FetchRdci or CreateRdci.

• change the contents of a certain API RDCM record, see SetRdcm.

• process an API RDCM record as a unit, see ProcessRdcm.

Error Messages

Related Functions

SetRdcm, ProcessRdcm, GetRdcmArr, WriteRdciRdcm

Syntax

short int GetRdcmArr(RdcmArr *rdcm_arr);

Parameters

rdcm_arr (out): a structure of type RdcmArr containing an array of the RECEIVED_DCM_IDs of all API RDCM records and the number of elements in that array.

Return Value

SUCCESS or FAILURE.

Comments

This function fails if:

• the API RDCI buffer is empty.

• there are changes pending in the API RDCI buffer that have not yet been processed through a call to ProcessRdci.

In order to:

• to get the API RDCM records, see GetRdcm.

• to process an API RDCM record as a unit, see ProcessRdcm.

Error Messages

Related Functions

GetRdcm, SetRdcm, ProcessRdcm, WriteRdciRdcm

Syntax

short int GetResponse(ResponseId *response_identifier,
    ResponseData *response_data,
    double *response_id,
    short  int *disc_type);

Parameters

response_identifier (in) A ResponseId structure containing the unique identifier for this response.

response_data (out) A pointer to the ResponseData structure containing the data for this response and the data comment for this response.

response_id (out) The response_id of the response identified by a response_identifier.

disc_type (out) Indicates whether or not the response has a discrepancy. If yes, it describes the discrepancy type which may be univariate (U), manual (M), or both (B).

Return Value

SUCCESS or FAILURE.

Comments

InitializeRdcmResponses should be called before calling GetResponse to initialize the API Responses buffer with the definition of the DCM.

The response_identifier uniquely identifies the response that is being processed by the external system. Upon calling this function, Oracle Clinical locates the response in its internal structure and gets the data, comment and discrepancy information for this response into the output variables. The output variables, which are provided to hold the data, comment and discrepancy information, should be allocated by the calling routine.

If this is a new document, and SetResponseData and/or SetDataComment and/or SetUnivDiscrepancy has never been called for this response, NULL values would be used to populate the output variable. Otherwise, the data from the last SetResponseData and/or SetDataComment and/or SetUnivDiscrepancy call would be returned. This applies also in the case of existing documents, with one exception:

• if the question has a repeating default, even if SetResponseData has not been called for the response, the value of the repeating default, if provided, is returned.

For ordinary defaults, the default value is returned only for the first repeat. For repeats greater than 1, SetResponseData must be called with the appropriate default value.

Error Messages

Related Functions

InitializeRdcmResponses, SetDataComment, SetResponseData, SetUnivDiscrepancy, GetUnivDiscrepancy, GetManualDiscrepancy

Syntax

short int GetUnivDiscrepancy(ResponseId *response_identifier,

    DiscInfo *return_discrepancy_info);

Parameters

response_identifier (in) The ResponseId definition containing the unique identifier for this response.

return_discrepancy_info (out) The DiscInfo containing the discrepancy information for this response.

Return Value

SUCCESS or FAILURE.

Comments

The response_identifier uniquely identifies the response that is being proceeded by the external system. Upon calling this function Oracle Clinical locates the response in its internal structure and gets the discrepancy information for this response into the input variables. The input variables, which are provided for holding the discrepancy information, should be allocated by the calling routine.

For existing documents, if a discrepancy has been previously added for this response, that information would be returned. The function returns FAILURE otherwise.

For new documents, if SetResponseData and/or SetUnivDiscrepancy has never been called for this response, the function returns FAILURE because no discrepancies exist. Otherwise, the discrepancy information created by the last SetResponseData and/or SetUnivDiscrepancy call would be returned. This applies also in the case of existing documents.

Error Messages

Related Functions

InitializeRdcmResponses, SetResponseData, SetUnivDiscrepancy

Syntax

short int InitializeRdcmResponses(double received_dcm_id,

    int responses_mode);

Parameters

received_dcm_id (in) The internal key for this document.

responses_mode (in) The mode to be used for the execution of this function. Valid values for this mode include:

• INITIAL_LOGIN

• KEY_CHANGES

• FIRST_PASS_ENTRY

• UPDATE

• BROWSE

Return Value

SUCCESS or FAILURE or WARNING.

Comments

InitializeRdcmResponses handles memory allocation. If you attempt to set or get response values for a question in a particular repeat in a question group without creating a repeat first, you will receive an error message. For more information about memory allocation, see "Memory Allocation Rules for Data Entry".

Prior to calling this function, the RDCIRDCM buffers must be populated. The external application obtains the received_dcm_id from the stable views or from RDCI/RDCM APIs. The received_dcm_id uniquely identifies the document that is being used by the external system. Upon calling this function, Oracle Clinical initializes its internal structures with the definition of the DCM for which this document has been or will be entered and the data (if any) that had been earlier entered for this document. If this is a new document — a document with no existing data — the responses for the first repeat in all the question groups in this document are initialized to BLANK and the remaining repeats are not initialized.

An error is returned if:

• the document status is incompatible with the mode of data entry — for example, if the user attempts to update responses on a document with status RECEIVED.

• the mode of data entry is incompatible with the mode of Log-In — for example, if the user attempts in Log-In to update a document reserved in non-locking mode.

• the user does not have the adequate privileges for the attempted data entry operation.

• the study is not enabled for data entry in production mode.

Error Messages

Related Function

WriteResponses

Syntax

short int InsertRepeat(RepeatId *repeat_identifier);

Parameters

repeat_identifier (in) The RepeatId containing the unique identifier for this repeat.

Return Value

SUCCESS or FAILURE.

Comments

The repeat_identifier uniquely identifies the row that is being processed by the external system (returning FAILURE if the row does not exist). Upon calling this function, Oracle Clinical inserts a new record (with all data values initialized to NULL) in its internal buffers. The API returns a FAILURE if the repeat sequence number exceeds the maximum repeats specified for the question group. SetResponseData needs to be called to update the response values as and when they are entered.

In InitializeRdcmResponses, Oracle Clinical automatically creates the first row in each group, so this function accepts repeat sequence numbers greater than or equal to 1 only.

Error Messages

Related Functions

InitializeRdcmResponses, SetResponseData

Purpose

Once you have completed all of the appropriate keys in the DCI, use this function to:

• validate the RDCI record as a unit.

• review interdependencies between fields.

• verify that there are no duplicate pre-existing RDCIs in the database.

• create RDCM records in the RDCM buffer for RDCMs that do not yet exist.

• perform data cascades from the API RDCI record to the existing RDCM records.

After this function verifies that the header is complete, it brings the appropriate DCMs to the buffers, and returns both the API RDCI record and an array containing the RECEIVED_DCM_IDs of all the API RDCM records.

The component items of the RDCI record that are also component items of RDCI_KEYS_REC — Investigator and Site, for example — might be implicitly assigned by this function. The component items of the RDCI record that are not component items of the RDCI_KEYS — Patient Position ID and Internal Timestamp, for example — are derived from the interface and implicitly returned by the system. For this reason the function returns the updated API RDCI record in the output parameter RDCI_REC.

Syntax

short int ProcessRdci(RdciRecord *rdci_rec,

    RdcmArr *rdcm_arr);

Parameters

rdci_rec (out) The updated contents of the API RDCI record in a RdciRecord structure.

rdcm_arr (out) A RdcmArr structure consisting of an array of the RECEIVED_DCM_IDs of all API RDCM records and the number of elements in that array.

Return Value

SUCCESS or FAILURE or WARNING.

Comments

This function fails if:

• The API RDCI buffer is empty.

• The API RDCI record exists in the database and has not been locked.

  To learn about locking the API RDCI record see FetchRdci, WriteRdciRdcm, WriteResponses,and FlushResponses.

To validate the API RDCI record as a unit, this function:

1. checks that all the mandatory items in the API RDCI record are populated.

2. performs cross-item validation.

3. performs uniqueness validation for the API RDCI record.

In interactive applications, at any point in time, the FE is working on one buffer only; either the FE RDCI buffer or the FE RDCM buffer. If it wants to switch from working on the FE RDCI buffer to working on the FE RDCM buffer, it should follow these steps first:

1. Call ProcessRdci if there are changes pending in the API RDCI record that have not been processed through a call to ProcessRdci.

2. Refresh the FE RDCM buffer because step 1 could have resulted in changes being cascaded to the API RDCM records. Cascaded changes will include deleting the existing API RDCM records and creating new ones in case the FE has changed the DCI_NAME in the API RDCI record. In this case the FE should clear the FE RDCM buffer altogether and populate it with the new API RDCM records.

To write the contents of the API RDCIRDCM buffer to the database, see WriteRdciRdcm. WriteRdciRdcm fails if there are changes pending in the API RDCI record that have not been processed through a call to ProcessRdci.

Error Messages

Related Functions

GetRdci, SetRdci, CreateRdci, FetchRdci, WriteRdciRdcm

Purpose

This function verifies that the selected RDCM record in the API RDCM buffer is a unit that includes all necessary data. For example, if the DCM requires a qualifying value, this function checks to see if one is supplied. In addition, this function verifies:

• interdependencies between fields.

• that there are no duplicate RDCMs in the API RDCM buffer.

• that there are no duplicate pre-existing RDCMs in the database.

When this function identifies a duplicate RDCM in the buffer, it returns the ID of that record in the double *RECEIVED_DCM_IDs parameter. When this function identifies a duplicate RDCM in the database, it returns an error and includes the document number of the duplicate record within the error message text.

Syntax

short int ProcessRdcm(double received_dcm_id,

    double *received_dcm_id_dup);

Parameters

received_dcm_id (in) The RECEIVED_DCM_ID of the API RDCM record to be validated.

received_dcm_ids (out) The RECEIVED_DCM_ID of the first duplicate API RDCM record encountered. This parameter will contain null if there is no duplicate API RDCM record encountered.

Return Value

SUCCESS or FAILURE or WARNING.

Comments

This function fails if:

• the API RDCI buffer is empty.

• the API RDCI record exists in the database and has not been locked.

  To learn about locking the API RDCI record see FetchRdci, WriteRdciRdcm, WriteResponses,and FlushResponses. To learn about privileges, see the "Functional State Mapping Information" and the "Functional State Transition Diagram".

• there are changes pending in the API RDCI buffer that have not yet been processed through a call to ProcessRdci.

• there is no API RDCM record whose RECEIVED_DCM_ID equals the parameter received_dcm_id.

To validate an API RDCM record as a unit, this function:

1. checks that all the mandatory items in the API RDCM record are populated.

2. performs cross-item validation.

3. performs uniqueness validation for the API RDCM record. If the function finds a duplicate within the other API RDCM records, it returns its RECEIVED_DCM_ID in the output parameter RECEIVED_DCM_IDs along with an error message. However, if the function finds a duplicate under another RDCI in the database, it returns an error message.

WriteRdciRdcm also validates each of the API RDCM records as part of its processing. This function is provided in order to give the FE a facility to determine early in the process whether individual API RDCM records are valid.

To write the contents of the API RDCIRDCM buffer to the database, see WriteRdciRdcm.

Error Messages

Related Functions

SetRdcm, GetRdcm, GetRdcmArr, WriteRdciRdcm

Syntax

short int SetActualEvent(double actual_event_id,

    ActualEventsRecord *actual_event);

Parameters

actual_event_id (in) The ACTUAL_EVENT_ID of the row you want to update.

ActualEventsRecord (in) The new contents with which you want to update the specified Actual Event record. This parameter is in a structure of type ActualEventsRecord.

Return Value

SUCCESS or FAILURE or WARNING.

Comments

None.

Error Messages

Related Functions

None.

Syntax

short int SetDataComment(ResponseId *response_identifier;

    DataComment *data_comm);

Parameters

response_identifier (in) The ResponseId definition containing the unique identifier for this response.

data_comm (in) A DataComment structure containing the data (investigator) comment for this response.

Return Value

SUCCESS or FAILURE.

Comments

The response_identifier uniquely identifies the response that is being processed by the external system. Upon calling SetDataComment, Oracle Clinical locates the response in its internal structure and updates the data (investigator) comment information for this response from the input variables provided for holding this information. These input variables should be allocated and initialized before calling the routine.

Error Messages

Related Functions

InitializeRdcmResponses, GetResponse

Syntax

short int SetExternalContext(ExternalContextInfo *context_info);

Parameters

context_info (in) A structure of type ExternalContextInfo.

Return Value

SUCCESS or FAILURE.

Comments

This function validates the value of the parameter context_info. It validates the trans_type item by checking that it contains a value from the reference codelist EXTERNAL_TRANS_TYPE. If it does not contain a value, the value STANDARD will be used. If the validation succeeds, the value of context_info will immediately take effect as the new external context info and the function returns SUCCESS; otherwise, the function will return FAILURE leaving the existing external context info intact.

The values set through a call to SetExternalContext will be reflected in all the subsequently created RDCI_HISTORY records until the next call of SetExternalContext or the call of DisconnectOCL, whichever comes first. No auditing records will be created if SetExternalContext has never been called since the last call to ConnectOCL.

An RDCI record in the API RDCI buffer will have only one audit record created for it upon the first writing to the database done due to a call of either WriteRdciRdcm or WriteResponses. Successive writing to the database while the same RDCI record is still in the API RDCI buffer will cause more audit records to be created for it only if a call to SetExternalContext has taken place after the last time an audit record was created for it.

In contrast to the API, Oracle Clinical does not maintain the RDCI_HISTORY table in the sense that it does not create or update records of that table.

The RDCI_HISTORY table will not be replicated and there are no reports running against it.

Error Messages

Related Functions

ConnectOCL, DisconnectOCL

Syntax

short int SetManualDiscrepancy(ResponseId *response_identifier,

    DiscInfo *discrepancy_info);

Parameters

response_identifier (in) The ResponseId definition containing the unique identifier for this response.

discrepancy_info (in) The DiscInfo definition containing the discrepancy information for this response.

Return Value

SUCCESS or FAILURE.

Comments

The response_identifier parameter uniquely identifies the response that is being processed by the external system. Upon calling SetManualDiscrepancy, Oracle Clinical locates the response in its internal structure and updates the manual discrepancy (operator comment) information for this response from the input variables provided for holding this information. These input variables should be allocated and initialized before calling the routine.

If the user has the privilege to create operator comments in browse mode and the document was fetched in locked mode, SetManualDiscrepancy may be invoked even in browse mode. In this respect it differs from other functions that set response and/or discrepancy values which may not be called in browse mode.

Error Messages

Related Functions

InitializeRdcmResponses, GetManualDiscrepancy

Syntax

short int SetMiscDiscrepancy(long disc_id, char *disc_subtype, DiscInfo *discrepancy_info);

Parameters

disc_id (in) The discrepancy ID for the discrepancy being updated.

disc_subtype (in) Type of discrepancy. Valid types are UNIVARIATE, MANUAL, INDICATOR, MULTIVARIATE or MANUAL HEADER.

discrepancy_info (in) The DiscInfo definition containing the discrepancy information. Only the resolution field in the structure DiscInfo is used.

Return Value

SUCCESS or FAILURE.

Comments

The disc_id and subtype parameters uniquely identify the discrepancy that is being processed by the external system. Upon calling SetMiscDiscrepancy, Oracle Clinical locates the discrepancy in its internal structure and updates the resolution comment or text for this discrepancy from the input variables provided for holding this information. These input variables should be allocated and initialized before calling the routine. The remaining fields should be initialized, otherwise a warning is raised.

If any of the remaining fields contain a non-null value, then a warning is raised.

Only discrepancies in status 'CURRENT' can be updated using this routine.

Error Messages

Related Functions

InitializeRdcmResponses

Syntax

short int SetPageStatus(double received_page_id,

    char *page_status);

Parameters

received_page_id (in) The RECEIVED_PAGE_ID of the received page whose status is to be updated.

page_status (in) The new status of the specified received page.

Return Value

SUCCESS or FAILURE.

Comments

This function will first lock the RDCI record to which the specified page belongs. If it cannot, it will fail; otherwise it will validate the new status and update the received page with the new status.

Error Messages

Related Functions

None.

Syntax

short int SetRdci(RdciKeysRecord *rdci_keys_rec,

    RdciRecord *rdci_rec);

Parameters

rdci_keys_rec (in): The RdciKeysRecord definition containing the value that you want to assign to the API RDCI record.

rdci_rec (out): The RdciRecord definition containing the contents of the updated API RDCI record.

Return Value

SUCCESS or FAILURE or WARNING.

Comments

This function fails if:

• the API RDCI buffer is empty.

• the API RDCI record exists in the database and has not been locked, or its locked but the user does not have the privilege required for SetPageStatus. To learn about locking the API RDCI record see FetchRdci, WriteRdciRdcm, WriteResponses and FlushResponses. To learn about privileges, see the "Functional State Mapping Information" and the "Functional State Transition Diagram".

Only the items of rdci_keys_rec that have a value different from that of the corresponding item in the API RDCI record will be considered. These items will be validated first. All of them have to pass validation in order for the update to take place; otherwise no update will take place and the function will return FAILURE. The type of validation taking place here is individual item validation whereas cross-item validation will happen as part of the validation of the API RDCI record as a unit which takes place in ProcessRdci.

If this function fails, rdci_rec will be empty; if it succeeds rdci_rec will contain the current contents of the updated API RDCI record.

To populate an empty API RDCI buffer, see CreateRdci and FetchRdci.

Error Messages

Related Functions

GetRdci, ProcessRdci, CreateRdci, FetchRdci, WriteRdciRdcm

Syntax

short int SetRdcm(double received_dcm_id,

    RdcmKeysRecord *rdcm_keys_rec,
    RdcmRecord *rdcm_rec);

Parameters

received_dcm_id (in) The RECEIVED_DCM_ID of the API RDCM record to be updated.

rdcm_keys_rec (in) The RdcmKeysRecord definition containing the value that you want to assign to the specified API RDCM record.

rdcm_rec (out) The RdcmRecord definition containing the contents of the updated API RDCM record.

Return Value

SUCCESS or FAILURE.

Comments

This function fails if:

• the API RDCI buffer is empty.

• the API RDCI record exists in the database and has not been locked, or it is locked but the user does not have the privilege required for SetRdcm.

  To learn about locking the API RDCI record, see GetRdci, FetchRdci, FlushRdciRdcm, FlushResponses, WriteRdciRdcm, and WriteResponses. To learn about privileges, see the "Functional State Mapping Information" and the "Functional State Transition Diagram".

• there are changes pending in the API RDCI buffer that have not yet been processed through a call to ProcessRdci.

• there is no API RDCM record whose RECEIVED_DCM_ID equals the parameter received_dcm_id.

Only the items of rdcm_keys_rec that have a value different from that of the corresponding item in the specified API RDCM record will be considered. These items will be validated first. All of them have to pass validation in order for the update to take place; otherwise no update will take place and the function will return FAILURE. The type of validation taking place in SetRdcm is individual item validation, whereas cross-item validation will happen as part of the validation of the API RDCM record as a unit. Cross-item validation takes place in both ProcessRdcm and WriteRdciRdcm.

If the API RDCM record contains items related to DCM definitions, such as dcm_date and dcm_time, and those items take their values, by definition, from the corresponding items in the API RDCI record, then the values passed in for these items in SetRdcm should be the same as the values of these items in the API RDCM record. If this is not the case, the function will fail. This restriction does not apply, however, if those items do not take their values from the API RDCI record. The current values of an API RDCI record can be obtained through a call to GetRdcm.

If this function fails, rdcm_rec is empty, and if it succeeds rdcm_rec contains the current contents of the updated API RDCM record.

To populate an empty API RDCI buffer, see CreateRdci and FetchRdci.

Error Messages

Related Functions

GetRdcm, GetRdcmArr, WriteRdciRdcm

Syntax

short int SetResponseData(ResponseId *response_identifier,

    ValueText *value,
    AuditInfo *audit_comment,
    DiscInfo *return_discrepancy_info,
    DCIAPIFlag *needs_audit);

Parameters

response_identifier (in) The ResponseId definition containing the unique identifier for this response.

value (in) A pointer to the ValueText structure containing the data for this response.

audit_comment (in) An AuditInfo structure holding the audit comment for this response.

return_discrepancy_info (out) A DiscInfo structure containing the discrepancy information for this response.

needs_audit (out) Indicates whether the response requires audit comment.

Return Value

SUCCESS or FAILURE or WARNING.

Comments

The response_identifier uniquely identifies the response that is being processed by the external system. Upon calling SetResponseData, Oracle Clinical locates the response in its internal structure and updates the audit comment information for this response from the input variables provided for holding this information. These input variables should be allocated and initialized before calling the routine.

While updating the data, the function checks the data for a univariate discrepancy and returns any discrepancy found in the structure provided for that purpose. If updating the data clears existing discrepancies, the discrepancy buffer is also cleared.

If this document is accessible and the API is in UPDATE mode, the audit comment is mandatory. SetResponseData returns FAILURE if the audit comment is needed but not provided — however, the internal buffers are updated with the rest of the information provided and the needs_audit flag is set. The user must call SetResponseData again with the missing audit comment information before calling any other API functions which will return FAILURE if invoked. Once the response has been updated with the audit comment information, you may continue with further processing by invoking other API functions.

If the RDCM is accessible, then the audit comment is mandatory to change the data. Otherwise, the API function will return FAILURE if the audit comment is not supplied.

Error Messages

Related Functions

InitializeRdcmResponses, GetResponse, GetUnivDiscrepancy

Syntax

short int SetStudyContext(char *study,

    StudyRecord *study_rec);

Parameters

study (in) The study name.

study_rec (out) A StudyRecord structure containing information about the live version of the study.

Return Value

SUCCESS or FAILURE.

Comments

This function takes these processing steps:

1. Set the new study context, using the parameter study, replacing the existing study context. If it fails in setting the study context it will return FAILURE, leaving the existing study context intact.

2. Flush the API RDCIRDCM buffer and consequently the Responses buffer.

Error Messages

Related Functions

ConnectOCL, DisconnectOCL

Syntax

short int SetUnivDiscrepancy(ResponseId *response_identifier,

    DiscInfo *discrepancy_info);

Parameters

response_identifier (in) The ResponseId structure definition containing the unique identifier for this response.

discrepancy_info (in) The DiscInfo structure definition containing the discrepancy information for this response.

Return Value

SUCCESS or FAILURE.

Comments

The response_identifier uniquely identifies the response that is being processed by the external system. Upon calling SetUnivDiscrepancy, Oracle Clinical locates the response in its internal structure and updates the discrepancy information for this response from the input variables provided for holding this information. These input variables should be allocated and initialized before calling the routine.

Error Messages

Related Functions

InitializeRdcmResponses, GetResponse, GetUnivDiscrepancy

Syntax

short int WriteRdciRdcm (DCIAPIFlag preserve_lock,

    double *received_dcm_id,
    double *received_dcm_id_dup);

Parameters

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 will be kept and if it is FALSE, it will be released.

received_dcm_id (out) The RECEIVED_DCM_ID of either the first API RDCM record to fail validation in steps 1 or 2 below or the first API RDCM record in a pair of duplicate API RDCM records found in step 3 below.

received_dcm_id_dup (out) The RECEIVED_DCM_ID of the second API RDCM record in a pair of duplicate API RDCM records. This parameter will contain null if there are no duplicate API RDCM records encountered.

Return Value

SUCCESS or FAILURE or WARNING.

Comments

To validate each API RDCM record as a unit, this function takes these steps for each API RDCM record:

1. The function checks that all the mandatory items in the API RDCM record are populated.

2. WriteRdciRdcm performs cross-item validation. If either the previous step or this step fails, the function stops with FAILURE returning in the output parameter received_dcm_id the RECEIVED_DCM_ID of the API RDCM record and null in the parameter received_dcm_id_dup.

3. The function performs uniqueness validation for the API RDCM record. If it finds a duplicate within the other API RDCM records it returns the following values:

   • In the output parameter received_dcm_id, the function returns the RECEIVED_DCM_ID of the API RDCM record currently being validated.

   • In the output parameter received_dcm_id_dup, the function returns the RECEIVED_DCM_ID of the duplicate API RDCM record found, in addition to an error message.

   If, on the other hand, WriteRdciRdcm finds a duplicate under another RDCI in the database, the function just returns an error message.

As part of the validation it carries out, this function will change the value of the blank flag of the API RDCI record to bring it in sync with the set of blank flag values of all the API RDCM records, if this change is necessary.

This function also assigns values to the time stamp items of both the API RDCI record and the API RDCM records.

To see the effects of this function on the API RDCIRDCM buffer, the front end has to call GetRdci and GetRdcm.

To validate a single API RDCM record, see ProcessRdcm.

Error Messages

Related Functions

CreateRdci, FetchRdci, SetRdci, GetRdci, ProcessRdci

Syntax

short int WriteResponses(DCIAPIFlag incomplete,

    DCIAPIFlag preserve_lock,
    ResponseId *response_identifier);

Parameters

incomplete (in) – Specify whether responses should be saved in incomplete mode. Value is TRUE or FALSE.

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 will be kept and if it is FALSE, it will be released.

response_identifier (out) – A ResponseId structure containing the unique identifier of the failed response.

Return Value

SUCCESS or FAILURE or WARNING.

Comments

None.

Error Messages

Related Functions

SetResponseData, GetResponse, FlushResponses