Oracle® Clinical Application Programming Interface Guide Release 5.0 E36998-01 |
|
|
PDF · Mobi · ePub |
This section describes each of the data structures that are used by many of the DCAPI functions. For each structure, the section includes the syntax of the typedef declaration in dcapi.h, the functions and other structures that use this structure, and additional comments about some parameters.
This structure is used to audit changes made to a document for RDCIs, RDCMs, or response changes. Three functions use AuditInfo as a direct parameter, and two others use it indirectly by using structures that contain AuditInfo as a parameter. These functions are:
Direct: SetResponseData, SetDataComment, DeleteRepeat
For instructions on using the AuditInfo structure in conjunction with DeleteRdci, see the section for that function.
typedef struct audit_info { char audit_comment[COMMENT_SIZE+1]; char reason[AUDIT_REASON_SIZE+1]; DCAPIFlag needs_audit ; } AuditInfo;
audit_comment (in/out): This parameter provides a free-text description of the transaction. It could be defaulted by the system or can be user-provided.
reason (in/out): The audit reason parameter must match a value in the reference codelists RDCI CHANGE REASON TYPE CODE or RDCI CHANGE REASON2 TYPE CODE (for RDCI and/or RDCM change or for soft deletion of a document) and DATA CHANGE REASON TYPE CODE or DATA CHANGE REASON2 TYPE CODE (for response changes). This parameter could be defaulted by the system or can be user-provided.
needs_audit (out): This parameter indicates after the function call whether the audit reason was expected but was not provided. If TRUE, an audit reason was required but was not manually provided and the system could not supply a default reason.
typedef struct data_comm { char data_comment[COMMENT_SIZE + 1]; AuditInfo audit ; }DataComment;
data_comment (in)
audit (in): A parameter of type AuditInfo, which tracks audit information about the investigator comment.
If used by SetResponseData, GetUnivDiscrepancy, or GetManualDiscrepancy, the parameters will be populated by the system. If used by SetUnivDiscrepancy or SetManualDiscrepancy, the parameters will be entered manually.
typedef struct disc_info { char disc_type[DISC_TYPE_SIZE+1]; char disc_rev_status[DISC_STATUS_SIZE+1]; char disc_resolu_type[CODE_SIZE+1]; char comment_text[EDMS_COMMENT_SIZE+1]; char internal_comment_text[EDMS_COMMENT_SIZE+1] ; char resolution[EDMS_COMMENT_SIZE+1] ; } DiscInfo;
The following are input parameters when DiscInfo is used by the functions SetUnivDiscrepancy and SetManualDiscrepancy; they are output parameters when used by GetUnivDiscrepancy, GetManualDiscrepancy, SetMiscDiscrepancy, and SetResponseData.
disc_type (in/out): This parameter maps to the reference codelist MANUAL SOURCE TYPE CODE for manual discrepancies. For univariate discrepancies, this parameter is system-generated and should not be changed.
disc_rev_status (in/out): This parameter maps to the installation reference codelist DISCREPANCY REV STATUS CODE.
disc_resolu_type (in/out): This parameter maps to the reference codelist DISCREPANCY RESOLU TYPE CODE.
comment_text (in/out): For univariate discrepancies, the initial value may be system-generated if a corresponding EDMS setup has been already been done. However, this value can be updated. For manual discrepancies, this parameter is a free-text description.
internal_comment_text (in/out): Free text description.
resolution (in/out): Free text description.
The ErrorInfo structure is a standalone element that DCAPI functions use to retrieve errors from the stack.
typedef struct error_info { short int type; int message_id; char message_string[COMMENT_SIZE+1]; char function_name[51]; } ErrorInfo;
type (out): The severity; either ERR (error) or WRN (warning).
message_id (out): the error message ID.
message_string (out): the error message.
function_name (out): the API function.
This structure is used by SetExternalContext to track changes made to data.
typedef struct context_info { char userid[31]; char timestamp[DATE_TIME_SIZE + 1]; char trans_type[61]; char comment[COMMENT_SIZE + 1]; }ExternalContextInfo;
userid (in): the Oracle user who is entering or modifying data.
timestamp (in): date and time of transaction.
trans_type (in): the type of transaction, which must match a value in the EXTERNAL_TRANS_TYPE reference codelist.
comment (in): free-text description of the transaction.
This structure is used by GetQuestGroupId to return the question group ID, given the question group name.
This structure is used by ExecuteMultivariate to specify the criteria for multivariate validation submission.
typedef struct mv_info { char execution_context[16]; double procedure_id ; int procedure_version_sn ; double patient_position_id ; double dcm_id ; double clinical_study_id ; double clinical_study_version_id ; double received_dci_id; short int mode ; DCAPIFlag debug_flag ; } MvInfo;
execution_context (in): Values are ON-LINE/DCM, ON-LINE or SINGLE
procedure_id (in)
procedure_version_sn (in)
patient_position_id (in)
dcm_id (in)
clincial_study_id (in)
clincial_study_version_id (in)
received_dci_id (in)
mode (in): Values are OCL_TEST or OCL_PROD.
debug_flag (in): Values are TRUE or FALSE.
This structure is used by EnrollPatient to enroll a patient in a study.
typedef struct patient_record { char birth_date[DATE_SIZE +1]; char sex[2]; char first_name[16]; char last_name[21]; char initials[5]; char enrollment_date[DATE_SIZE+1]; } PatientRecord;
birth_date (in)
sex (in)
first_name (in)
last_name (in)
initials (in)
enrollment_date (in)
The QuestionId structure is used by GetQuestionId to return the question ID, given the question group name, question name, and occurrence subset number.
typedef struct question_id { char group_name[GROUP_SIZE+1]; char question_name[QUESTION_SIZE+1] ; int qn_occurence_sn; } QuestionId;
group_name (in): the name of its question group.
question_name (in): the name of the question.
qn_occurrence_sn (in): the occurrence subset number.
This structure contains the key values of the RDCI record being created or modified by CreateRdci or SetRdci.
typedef struct rdci_keys_record { char document_number[21] ; char patient[11] ; char dci_short_name[11] ; char dci_date[DATE_SIZE + 1] ; char dci_time[TIME_SIZE + 1] ; char visit_name[21] ; short int subevent_number ; char site[11] ; char investigator[11] ; DCAPIFlag blank_flag ; char comment[COMMENT_SIZE + 1] ; AuditInfo audit ; DCAPIFlag audit_only_flag; } RdciKeysRecord;
document_number (in): Optional for CreateRdci, required for SetRdci.
patient (in): Any unique identifier which the external system can assign to a patient. It is not necessarily the same as the 'patient position id' or the 'patient name'.
dci_short_name (in)
dci_date (in): Can be optional if the DCI does not require a date as part of its definition.
dci_time (in): Only applicable if the current DCI needs them to be collected; otherwise this parameter must be passed as null values. Passing a non-null value for this parameter when it is not applicable will cause the API function to fail. A null value for a character array field is the null ("") string.
visit_name (in)
subevent_number (in)
site (in): Any unique identifier which the external system can assign to a site.It is not necessarily same as the 'site id' or the 'site name'.
investigator (in): Any unique identifier that the external system can assign to an investigator. It is not necessarily the same as the investigator ID or the investigator name.
blank_flag (in): Value passed in are TRUE or FALSE.
comment (in): Free-text description.
audit (in): A parameter of type AuditInfo, which tracks audit information about the RDCI key or comment changes.
audit_only_flag (in): This parameter, if set to TRUE, indicates that the audit reason provided is for soft-deleting a document (via DeleteRdci), rather than for a key or comment change.
This structure contains the contents of the RDCI record that is either being retrieved from the database or being created or modified.
typedef struct rdci_record { char document_number[21] ; char recvd_dci_status_code[16] ; char patient[11] ; char dci_short_name[11] ; char dci_name[31] ; char dci_date[DATE_SIZE + 1] ; char dci_time[TIME_SIZE + 1] ; char visit_name[21] ; int visit_number ; short int subevent_number ; char site[11] ; char investigator[11] ; DCAPIFlag blank_flag ; char comment[COMMENT_SIZE + 1] ; char received_dci_entry_ts[DATE_TIME_SIZE + 1] ; char entered_by[31] ; char end_ts[DATE_TIME_SIZE + 1] ; DCAPIFlag data_lock_flag ; char data_lock_ts[DATE_TIME_SIZE + 1] ; char accessible_ts[DATE_TIME_SIZE + 1] ; char last_status_change_ts[DATE_TIME_SIZE + 1] ; char last_new_ver_ts[DATE_TIME_SIZE + 1] ; char modification_ts[DATE_TIME_SIZE + 1] ; char modified_by[31] ; char log_in_ts[DATE_TIME_SIZE + 1] ; AuditInfo audit ; } RdciRecord;
document_number (out)
recvd_dci_status_code (out)
patient (out)
dci_short_name (out)
dci_name (out)
dci_date (out)
dci_time (out)
visit_name (out)
visit_number (out)
subevent_number (out)
site (out)
investigator (out)
blank_flag (out)
comment (out)
received_dci_entry_ts (out)
entered_by (out)
end_ts (out)
data_lock_flag (out)
data_lock_ts (out)
accessible_ts (out)
last_status_change_ts (out)
last_new_ver_ts (out)
modification_ts (out)
modified_by (out)
log_in_ts (out)
audit (out)
This structure is used by ProcessRdci, FetchRdci, and GetRdcmArr.
rdcm_a (out): an array of the received_dcm_ids of all the RDCM records.
len (in): the number of elements in the array.
This structure contains the key values of the RDCM record being created or modified by SetRdcm.
typedef struct rdcm_keys_record { DCAPIFlag blank_flag ; char qualifying_val[71] ; char dsp_lab[27] ; char visit_name[21] ; short int subevent_number ; char dcm_date[DATE_SIZE + 1] ; char dcm_time[TIME_SIZE + 1] ; char comment[COMMENT_SIZE + 1] ; char data_comment[COMMENT_SIZE + 1] ; AuditInfo audit ; } RdcmKeysRecord;
The parameters qualifying_val, dsp_lab, visit_name, subevent_number, dcm_date, and dcm_time are only applicable if the current DCM needs them to be collected. Otherwise they must be passed in to any API function as null values. Passing a non-null value for any of these items when it is not applicable will cause the API function to fail. A null value for a character array field is the null ("") string. For integers use -1 to indicate a null value.
blank_flag (in): Value passed in is TRUE or FALSE.
qualifying_val (in):
dsp_lab (in):
visit_name (in):
subevent_number (in):
dcm_date (in):
dcm_time (in):
comment (in):
data_comment (in):
audit (in): A parameter of type AuditInfo, which tracks audit information about the RDCM changes.
This structure contains the contents of the RDCM record that is either being retrieved from the database or being created or modified.
typedef struct rdcm_record { char dcm_short_name[5]; char dcm_name[17]; short int dcm_subset_sn; short int dcm_layout_sn; DCAPIFlag blank_flag; char recvd_dcm_status_code[16]; char qualifying_value[71]; char dsp_lab[27]; char visit_name[21]; int visit_number; short int subevent_number; char dcm_date[DATE_SIZE + 1]; char dcm_time[TIME_SIZE + 1]; char comment[COMMENT_SIZE + 1] ; char data_comment[COMMENT_SIZE + 1] ; char recvd_dcm_entry_ts[DATE_TIME_SIZE + 1]; char entered_by[31]; char end_ts[DATE_TIME_SIZE +1]; DCAPIFlag data_lock_flag; char data_lock_ts[DATE_TIME_SIZE + 1]; char accessible_ts[DATE_TIME_SIZE + 1]; char lab_modification_ts[DATE_TIME_SIZE + 1]; char lab_assignment_type_code[16]; char last_status_change_ts[DATE_TIME_SIZE + 1]; char last_data_change_ts[DATE_TIME_SIZE + 1]; char pass1_ts[DATE_TIME_SIZE + 1]; char pass1_by[31]; char pass2_ts[DATE_TIME_SIZE + 1]; char pass2_by[31]; char modification_ts[DATE_TIME_SIZE + 1]; char modified_by[31]; char log_in_ts[DATE_TIME_SIZE + 1]; AuditInfo audit ; } RdcmRecord;
All of the following are output parameters.
dcm_short_name (out)
dcm_name (out)
dcm_subset_sn (out)
dcm_layout_sn (out)
blank_flag (out)
recvd_dcm_status_code (out)
qualifying_value (out)
dsp_lab (out)
visit_name (out)
visit_number (out)
subevent_number (out)
dcm_date (out)
dcm_time (out)
comment (out)
data_comment (out)
recvd_dcm_entry_ts (out)
entered_by (out)
end_ts (out)
data_lock_flag (out)
data_lock_ts (out)
accessible_ts (out)
lab_modification_ts (out)
lab_assignment_type_code (out)
last_status_change_ts (out)
last_data_change_ts (out)
pass1_ts (out)
pass1_by (out)
pass2_ts (out)
pass2_by (out)
modification_ts (out)
modified_by (out)
log_in_ts (out)
audit (out): A parameter of type AuditInfo, which tracks audit information about the RDCM changes
This structure is used by GetResponse to retrieve the data from the database or from the buffer for the response being modified.
typedef struct response_data { char value_text[COMMENT_SIZE + 1]; char data_comment[COMMENT_SIZE + 1]; }ResponseData;
This structure is used by InsertRepeat and DeleteRepeat to identify uniquely the repeat.
group_id (in)
repeat_sn (in)
audit (in): Not used by InsertRepeat. For DeleteRepeat, this parameter of type AuditInfo tracks audit information about the repeat being deleted.
This structure uniquely identifies the response.
typedef struct response_id { double group_id; double question_id; int repeat_sn ; } ResponseId;
Each of the following is an input parameter for the API functions below, except for WriteResponses, where all three are output parameters.
group_id
question_id
repeat_sn
This structure contains the information about the live version of the study.
typedef struct study_record { double clinical_study_id; int clinical_study_version_id; DCAPIFlag study_freeze_flag; DCAPIFlag second_pass_required_flag; DCAPIFlag data_entry_enabled_flag; DCAPIFlag first_pass_from_login_flag; char last_batch_ts[DATE_TIME_SIZE+1]; DCAPIFlag disc_in_browse; DCAPIFlag disc_res_in_de; DCAPIFlag priv_update; DCAPIFlag unenroll_alert; DCAPIFlag browse_acc_only; DCAPIFlag dci_date_required; DCAPIFlag univar_alert; DCAPIFlag thesaurus_lov; DCAPIFlag use_dci_book ; DCAPIFlag ocl_thes_disc; DCAPIFlag ocl_thes_lov; }StudyRecord;
All of these are output parameters.
clinical_study_id (out)
clinical_study_version_id (out)
study_freeze_flag (out): If TRUE, the study is frozen.
second_pass_required_flag (out): If TRUE, second pass required to make data accessible
data_entry_enabled_flag (out): If TRUE, production data entry is enabled
first_pass_from_login_flag (out): If TRUE, allows combined log-in and data entry
last_batch_ts (out)
disc_in_browse (out): If TRUE, allows creation/modification of manual discrepancies in Browse mode.
disc_res_in_de (out): If TRUE, allows discrepancy resolution in data entry.
priv_update (out): If TRUE, allows privileged update.
unenroll_alert (out): If TRUE, unenrolled patient alert is on.
browse_acc_only (out): Browse accessible data only
dci_date_required (out): This parameter is obsolete.
univar_alert (out): If TRUE, operator is alerted when univariate error occurs.
thesaurus_lov (out): If TRUE, LOVs are allowed on Thesaurus DVG-validated fields.
use_dci_book (out): If TRUE, DCI book is used as default entry mode
ocl_thes_disc (out): If TRUE, system creates discrepancies for TMS fields at data entry.
ocl_thes_lov (out): If TRUE, system allows LOVs on TMS fields at data entry.
This structure contains the contents of the response.