Using the API

The API can be used with programs that you develop with Oracle Pro*C and Microsoft Visual C++. See the requirements section of the Oracle Clinical Installation Guide for the supported version Oracle Pro*C and Microsoft Visual C++. The following files are provided to use in your development, and are available on the Oracle Clinical Web Server in the opa_home/oc/dcapi folder. Please note that DCAPI binaries are compiled for 64-bit. This means that the bin folder contains all the 64-bit libraries and calling application need to be in 64-bit.

• dcapi.h: Include this header file in your C files and set the header file path in your Microsoft Visual C++ project definition to the directory that contains dcapi.h.
• dcapi.lib: Include this library file in the list of files used to link your program and set the library path of your Microsoft Visual C++ project definition to the directory that contains dcapi.lib.
• dcapi.dll: Include this file in your system path during runtime.

For more information, see:

• File Locations
  
• Setting Up Linkage in Microsoft Visual C++
  
• Sample C Programs
  
• Auditing Considerations
  
• Auditing and Backward Compatibility
  

File Locations

The Oracle Clinical Installer automatically loads the DCAPI files onto the Oracle Clinical Web Server during the Front End installation. The DCAPI files are available in the oracle_home/oc/dcapi folder, and are required by Oracle Clinical. To link to these files in a different location, copy the DCAPI files to that location instead of moving them.

To build an application using DCAPI, the C++ compiler must know where the header and library files are, and what libraries to link against. The following section describes how to do this in Visual Studio 2010.

Setting Up Linkage in Microsoft Visual C++

To use the header file and library file in your Microsoft Visual C++ projects, within Visual Studio, right click on your project in the Solution Explorer and bring up the project's Properties dialog. You need to change the settings for both Debug and Release versions, so under the Configuration field, select “All Configurations". The following example shows how to do so in Microsoft Visual C++ 10.0; the steps may differ if you use another version.

See the following:

• Header File
  
• Static Library File
  

Header File

Select the C/C++ category of properties, and pick the General options under that. In the Additional Include Directories property, add the semicolon-separated directory where dcapi.h is available

Static Library File

To change the settings for both Debug and Release versions, go to the Properties dialog under the Configuration field and select All Configurations.

Select the Linker category of properties then pick the Input option. In the Additional Dependencies property, add the DCAPI library dcapi.lib.

Sample C Programs

OPA provides a selection of sample programs that illustrate the use of DCAPI functions in the following tasks for a document:

• Initial Log-in
• Key Changes
• First-pass data entry
• Update
• Browse
• Soft Delete

This document is available on My Oracle Support. Search for article ID 315201.1 and click the dcapi_samples.pc link from that note.

Auditing Considerations

Many DCAPI functions use two new data elements that provide auditing information: the audit change reason and a reason for the change. These data elements are part of the new AuditInfo structure, which is a direct parameter for the DCAPI functions SetResponseData, SetDataComment, and DeleteRepeat and an indirect parameter for the functions SetRdci and SetRdcm.

AuditInfo is also a new component of other existing data structures in the DCAPI, adding audit capabilities to these structures. All DCAPI functions that use these structures are affected by the change.

RdciKeysRecord: The external system will use AuditInfo to provide the audit change reason and an optional comment, in addition to the new set of keys or comment definition, in the RdciKeysRecord. The RdciKeysRecord structure will also include another boolean called audit_only_flag to indicate whether only an audit reason and no key or comment changes is provided. If an audit reason is required and it is not provided and the system is unable to derive or default one, the API call will fail. This change affects the DCAPI functions CreateRdci and SetRdci.

RdciRecord: The external system uses AuditInfo to retrieve the audit reason and comment (if any) provided earlier during an RDCI key or comment change or a soft delete, in addition to the full set of RDCI elements, in the RdciRecord. Adding AuditInfo to this structure affects the functions CreateRdci, GetRdci, ProcessRdci, SetRdci and FetchRdci.

RdcmKeysRecord: This structure will be updated to include the AuditInfo structure. AuditInfo is the structure that the external system will use to provide audit reason and an optional comment, in addition to the new set of keys or comment definition, in the RdciKeysRecord. If an audit reason is required and it is not provided, and the system is unable to derive or default one, the API call will fail. This change affects the SetRdcm function.

RdcmRecord: This structure will be updated to include the AuditInfo structure. This is the structure that the external system will use to retrieve the audit reason and comment (if any) provided earlier during an RDCM key or comment change, in addition to the full set of RDCM elements, in the RdcmRecord. This change affects the functions GetRdcm and SetRdcm.

RepeatId: This structure will be updated to include the AuditInfo structure. The boolean needs_audit will be set to TRUE to indicate if a audit reason is needed and is missing. The external system uses this structure to provide the audit reason and an optional comment when deleting a repeat.

DataComment: This structure will be updated to include the AuditInfo structure. The external system uses AuditInfo to provide the audit reason and an optional comment, in addition to the investigator comment definition, in the DataComment. This change affects the following DCAPI functions: CreateRdci, SetRdci, GetRdci, FetchRdci, ProcessRdci, SetRdcm, GetRdcm, DeleteRepeat and SetDataComment.

The values to these new parameters will be initialized to NULL and will be cleared upon saving of a transaction.

Auditing and Backward Compatibility

DCAPI functions require an audit change reason each time you make a change to a document. To enable backward compatibility with programs you have written to interface with earlier Oracle Clinical releases, this release includes two new reference codelists that you can supply with default values for the audit change reason.

To enable backward compatibility for pre-4.5 interfacing programs, perform these steps:

1. Re-compile and re-link your existing interfacing programs with the Release 4.5 version of the header file (dcapi.h) and library file (dcapi.lib).
2. Populate the new reference codelists with the default values you want to use for the audit change reason. Because the audit change reason supplied depends on the change you make, you can provide separate default values for:

• Key or Comments Changes to RDCIs/RDCMs, and Soft-deletions of Documents
  
• Investigator Comment Changes
  
• Deletion of Repeats
  

Key or Comments Changes to RDCIs/RDCMs, and Soft-deletions of Documents

To find the default audit reason for Header changes (RDCI or RDCM Key change, RDCI or RDCM Comment change and when Soft-Deleting a document), the system refers to the reference code list 'RDCI CHANGE REASON TYPE CODE' as the primary and to 'RDCI CHANGE REASON2 TYPE CODE' as the secondary reference codelist. The system attempts to find a default audit reason by looking for "DCAPI" as a comma-separated string in the long value of either one of the reference codelists.

Investigator Comment Changes

To find a default audit reason for Investigator Comment changes (a change to responses), the system refers to the reference code list 'DATA CHANGE REASON TYPE CODE' as the primary and to 'DATA CHANGE REASON2 TYPE CODE' as the secondary reference codelist. The system attempts to find a default audit reason by looking for “DCAPIINV" in the long value of either one of the reference codelists.

Deletion of Repeats

To find a default audit reason for Delete Repeat (a change to responses), the system refers to the reference code list 'DATA CHANGE REASON TYPE CODE' as the primary and to 'DATA CHANGE REASON2 TYPE CODE' as the secondary reference codelist. The system attempts to find a default audit reason by looking for "DCAPIDEL" in the long value of the either one of the reference codelists.