Special Notes About the API

Review the following rules before you begin to develop your application. Instructions are written for someone with a working knowledge of Microsoft Visual C++ 6.0.

See the following:

• Accessible Documents
  
• Date Formats
  
• Error Handling
  
• Indicating NULL for Number Fields
  
• Overall Memory Allocation and Management
  
• Memory Allocation Rules for Data Entry
  

Accessible Documents

The documentation includes several references to the term accessible documents. Every Oracle Clinical study has properties indicating if first and second pass Data Entry are necessary. A RDCI is considered accessible when any of its RDCMs become accessible.

An RDCM is considered accessible if it meets any of the following criteria:

• The RDCM was batch loaded
• Pass 1 has been completed for the RDCM and Pass 2 is not required
• Pass 2 is required for the RDCM and has been completed

Date Formats

All date, time and date-time arguments to the API function calls are of type character array. This information is translated to Oracle dates internally by the API functions, so to remove ambiguity during translation, the dates, times, and date-times must be input in the following formats: YYYYMMDD, HH24MISS, and YYYYMMDDHH24MISS. The hours, HH, are specified in military time (values from 00 to 23 inclusively). These formats are referred to as the API date, time, and date-time formats respectively.

Error Handling

API functions will return a SUCCESS, FAILURE, or WARNING, defined as "short int" in the header file (SUCCESS = 0, FAILURE = 1, WARNING = 2). In the case of FAILURE or WARNING, the external application can use the GetError API function to get the message ID, text, and type from the error message stack. The external application can also use GetErrorStackSize to assess the depth of the stack and then call GetError repeatedly until no errors remain. If GetError returns SUCCESS your application should process the errors. For a complete list of error messages, see Error Messages. If GetError returns the message ID -1, an internal Oracle Clinical error has occurred.

WARNING:

An internal Oracle Clinical error can corrupt data. If you encounter this kind of error, immediately roll back your data. The external application should continue retrieving the errors and ignoring them until the error stack is empty.

Indicating NULL for Number Fields

Your application should put -1 in numeric (double, short, int) fields to indicate a null value to Oracle Clinical. Similarly, Oracle Clinical returns -1 for these fields to indicate a null value in the database. The Visit Number field can have a valid negative value. If the visit number has a value of -1, your application must check for a visit name. When the visit name is null and the visit number is -1, the visit number is null in the database as well.

Overall Memory Allocation and Management

The API functions described manage allocation and deallocation of memory for the internal data structures they use. Your application must manage allocation and deallocation of memory for arguments to API calls that accept pointers to variables. For example, in a call to GetRdci, your program must allocate the memory for the argument of type RdciRecord.

Memory Allocation Rules for Data Entry

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 receive an error message.

For a document with existing responses, InitializeRdcmResponses allocates memory to hold response values for all questions in all existing repeats in all question groups in the RDCM. The user can then retrieve or set values for these responses. However, for repeating groups, if the user wants to retrieve or set the response of a new repeat that does not exist in the database, the user must begin by inserting a repeat.

For repeating groups with n > 1 repeats, InsertRepeat needs to be called. This function allocates memory to hold response values for all questions in the i-th repeat for the group (where 1 < i <= n).

It is not necessary to enter response values immediately after inserting the repeat; the user of the API functions can first insert the necessary repeats in all question groups and then set the values for the responses. However, response values for at least one question should be entered for all inserted repeats in all question groups, otherwise WriteResponses will return FAILURE.

To delete an existing repeat, use the DeleteRepeat call. This does not free the memory allocated for holding the responses in the API Responses buffer; it simply marks the corresponding responses as deleted. They will be processed at commit time and marked accordingly in the database. The deleted repeats are archived in the database. Users can run either an Oracle Clinical audit report or their own audit report to view the deleted repeats.