Calling API Functions
The Data Capture API enforces rules about when you can call an API function. These rules are associated with the state of the data. The API considers the data to be in one of the following states.
Pre-Connection
This state occurs when the your application is running but not connected to the Oracle Clinical database. The API function ConnectOCL connects you to the Oracle Clinical database. All other Data Capture API functions require a connection to the Oracle Clinical database.
If you call a Data Capture API function, and you are not connected to the database, you receive an error message. Once connected to the Oracle Clinical database, you can disconnect or set study context from any of the remaining four states.
Pre-Study
This state occurs immediately after your program connects to the Oracle Clinical database and means that the study for which you are planning to enter data is unknown to the API. The SetStudyContext API function provides this context information. Any of the API functions that attempt to retrieve or set data require the study context and return an error if called in this state. Because SetExternalContext does not affect Oracle Clinical data, it can be called in this state.
In-Study with Empty RDCI/RDCM Buffer
This state occurs when the program has set the study context but has not called any API functions that update RDCI/RDCM data. RDCI/RDCM data must always be entered before response data because responses are associated with RDCMs that belong to RDCIs.
To proceed with entering RDCI/RDCM and responses data, you must either create a new RDCI by calling CreateRdci or fetch an existing RDCI to browse or update by calling FetchRdci. Either of these two functions will switch you into the RDCIRDCMWork state. There are no pending changes to RDCI/RDCM data or responses data in this state, so APIs that commit data to the database — EnrollPatient, SetActualEvent, SetPageStatus, and ExecuteMultivariate — can be called. You can call SetExternalContext from this state as well.
RDCIRDCMWork
This state occurs when the program is retrieving or updating RDCI/RDCM data; while in this state, you cannot call functions that retrieve or update RDCI/RDCM data. The function SetExternalContext does not commit data or retrieve/update responses data, so it can be called in this state.
Pending changes must be saved to the database, using WriteRdciRdcm; otherwise they must be discarded using FlushRdciRdcm before more response data can be entered. InitializeRdcmResponses then brings you to the ResponsesWork state.
Once all pending changes have been saved or discarded, the program can call EnrollPatient, SetActualEvent, SetPageStatus, and ExecuteMultivariate to commit data. These API functions do not commit data if there are pending changes, because incomplete RDCI/RDCM information would cause data corruption.
ResponsesWork
This state occurs when your program is retrieving or updating response data. The API functions that update the RDCI/RDCM data cannot be called in this state.
Once all pending changes have been saved (using WriteResponses) or discarded (using FlushResponses), the program can commit data by calling EnrollPatient, SetActualEvent, SetPageStatus, and ExecuteMultivariate. These functions cannot be called if there are pending changes, because the functions would commit incomplete responses information to the Oracle Clinical database which would cause data corruption. The program can return to either the RDCIRDCMWork state or In-Study with Empty RDCIRDCM Buffer state by calling, saving, or discarding any pending changes.
For more information, see:
Parent topic: Data Capture API Overview
Functional State Mapping Information
This section describes the functional states in which you can call each of the DCAPI functions. Because ConnectOCL is associated with only one state, the Pre-Connection state, this function is not listed.
Can be called in:
- In-Study with Empty RDCI/RDCM Buffer.
- RDCI/RDCM Work, but only if there are no changes pending. If an audit comment is required and has not been provided before you call CreateRdci in this state, it returns an error.
Can be called in RDCI/RDCM Work, but only if there are no changes pending. If an audit comment is required and has not been provided before you call DeleteRdci in this state, it returns an error.
Can be called in Responses Work. If an audit comment is required and has not been provided before you call DeleteRepeat in this state, it returns an error.
Can be called in:
- Pre-Study
- In-Study with Empty RDCI/RDCM Buffer
- RDCI/RDCM Work, but only if there are no changes pending
- Responses Work, but only if there are no changes pending
Can be called in:
- In-Study with Empty RDCI/RDCM Buffer
- RDCI/RDCM Work, but only if there are no changes pending. Even if there are no changes pending, EnrollPatient cannot be called in this state if the RDCI was fetched for update until the database lock is released.
- Responses Work, but only if there are no changes pending. Even if there are no changes pending, EnrollPatient cannot be called in this state if the RDCI was fetched for update until the database lock is released.
Can be called in:
- Pre-Study
- In-Study with Empty RDCI/RDCM Buffer
- RDCI/RDCM Work, but only if there are no changes pending
- Responses Work, but only if there are no changes pending
Can be called in:
- In-Study with Empty RDCI/RDCM Buffer
- RDCI/RDCM Work, but only if there are no changes pending. If an audit comment is required and has not been provided before you call FetchRdci, the system returns an error.
Can be called in RDCI/RDCM Work
Can be called in Responses Work. If an audit comment is required and has not been provided before you call FlushResponses, the system returns an error.
Can be called in Responses Work. If an audit comment is required and has not been provided before you call GetManualDiscrepancy, the system returns an error.
Can be called in Responses Work. If an audit comment is required and has not been provided before you call GetNumRows, the system returns an error.
Can be called in Responses Work. If an audit comment is required and has not been provided before you call GetQuestGroupId, the system returns an error.
Can be called in Responses Work. If an audit comment is required and has not been provided before you call GetQuestionId, the system returns an error.
Can be called in RDCI/RDCM Work.
Can be called in RDCI/RDCM Work, but only if there are no pending RDCI changes. If pending RDCI changes exist, process them by calling ProcessRdci.
Can be called in RDCI/RDCM Work, but only if there are no pending RDCI changes. If pending RDCI changes exist, process them by calling ProcessRdci.
Can be called in Responses Work. If an audit comment is required and has not been provided before you call GetResponse, the system returns an error.
Can be called in Responses Work. If an audit comment is required and has not been provided before you call GetUnivDiscrepancy, the system returns an error.
Can be called in RDCI/RDCM Work
Can be called in Responses Work. If an audit comment is required and has not been provided before you call InsertRepeat, the system returns an error.
Can be called in RDCI/RDCM Work
Can be called in RDCI/RDCM Work, but only if there are no pending RDCI changes. If pending RDCI changes exist, process them by calling ProcessRdci.
Can be called in:
- Pre-Study
- In-Study with Empty RDCI/RDCM Buffer
- RDCI/RDCM Work, but only if there are no changes pending. Even if there are no changes pending, this API function cannot be called in this state if the RDCI was fetched for update until the database lock is released.
- Responses Work, but only if there are no changes pending. Even if there are no changes pending, this API function cannot be called in this state if the RDCI was fetched for update until the database lock is released.
Can be called in Responses Work. If an audit comment is required and has not been provided before you call this API function, the function will return an error.
Can be called in:
- Pre-Study
- In-Study with Empty RDCI/RDCM Buffer
- RDCI/RDCM Work, but only if there are no changes pending.
Can be called from Responses Work. If an audit comment is required and has not been provided before you call this API function, the function will return an error.
Can be called from Responses Work. If an audit comment is required and has not been provided before you call this API function, the function will return an error.
Can be called from:
- Pre-Study
- In-Study with Empty RDCI/RDCM Buffer
- RDCI/RDCM Work, but only if there are no changes pending. Even if there are no changes pending, this API function cannot be called in this state if the RDCI was fetched for update until the database lock is released.
- Responses Work, but only if there are no changes pending. Even if there are no changes pending, this API function cannot be called in this state if the RDCI was fetched for update until the database lock is released.
Can be called from RDCI/RDCM Work
Can be called from RDCI/RDCM Work, but only if there are no pending RDCI changes. You can process these pending changes by calling ProcessRdci.
Can be called from Responses Work
Can be called from:
- Pre-Study
- In-Study with Empty RDCI/RDCM Buffer
- RDCI/RDCM Work, but only if there are no changes pending.
- Responses Work, but only if there are no changes pending.
Can be called from Responses Work. If an audit comment is required and has not been provided before you call SetUnivDiscrepancy, it returns an error.
Can be called from RDCI/RDCM Work, but only if there are no pending RDCI changes. You can process these pending changes by calling ProcessRdci.
Can be called from Responses Work. If an audit comment is required and has not been provided before you call this API function, the function will return an error.
Parent topic: Calling API Functions
Functional State Transition Diagram
The following diagram illustrates the required transitions to move from one state to another in the API.
* If called with preserve lock, otherwise brings you to In-Study with Empty RDCIRDCM Buffer state.
Parent topic: Calling API Functions