SetRdcm

Assigns the value of the parameter rdcm_keys_rec to a specific API RDCM record. It also returns the contents of the updated API RDCM record in the parameter rdcm_rec. The component items of API RDCM record which are not component items of rdcm_keys_rec, such as all the numeric ID items, are implicitly assigned by this function. Patient ID, for example, is not a key field but instead is populated implicitly once the external patient identifier is supplied and validated. This process is the reason that the function returns the updated API RDCM record in the output parameter rdcm_rec.

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

Table 7-35 Error Messages for SetRdcm

Number	Severity	Message
284900	ERR	User does not have the privilege to call function in the current mode.
285000	ERR	Function called out of sequence.
285900	ERR	No current OCL database connection open. Use ConnectOCL to connect to OCL database.
286100	ERR	RDCM with this received_dcm_id does not exist.
286600	ERR	Audit reason required and not provided.
291400	ERR	Clinical planned event is invalid for the current study.
294600	ERR	Invalid lab.
291700	ERR	Discrete value does not exist or is inactive.
291800	ERR	Discrete value could not be validated.
291900	ERR	Value must be Y or N.
293500	ERR	Cannot set to N (not blank) when Received DCI is blank.
297000	ERR	Null or invalid input pointers provided.
299800	ERR	Date cannot exceed today's date.
304600	ERR	Function does not exist.
304700	ERR	Privilege does not exist.
305800	ERR	Invalid DCM date.
305900	ERR	Invalid DCM time.
306100	ERR	Changes pending that have not been processed.
306800	ERR	Invalid audit reason.
306900	ERR	No update allowed to the RDCM buffer.
307000	ERR	Cannot call this function if you have not locked the record.
309400	ERR	Date is not applicable.
309500	ERR	Date is not updateable.
309600	ERR	Time is not applicable.
309700	ERR	Time is not updateable.
309800	ERR	Visit name is not applicable.
309900	ERR	Visit name is not updateable.
310000	ERR	Subevent number is not applicable.
310100	ERR	Subevent number is not updateable.
310600	ERR	Blank flag is not applicable.
310700	ERR	Blank flag is not updateable.
310800	ERR	Comment is not applicable.
310900	ERR	Comment is not updateable.
311000	ERR	Qualifying value is not applicable.
311100	ERR	Qualifying value is not updateable.
311200	ERR	Lab is not applicable.
311300	ERR	Lab is not updateable.
311400	ERR	Data comment is not applicable.
311500	ERR	Data comment is not updateable.
314900	ERR	Received DCM is accessible; please use Key Changes to change Blank Flag.
315200	WRN	Responses exist for this RDCM. Changing the Blank Flag to 'Y' will cause them to be irrevocably deleted.
345400	ERR	Qualifying value can only be changed to the default value defined at the DCI module.
659700	ERR	No default audit reason.
659800	ERR	More than one default audit reason found.
660000	ERR	Cannot use system-generated audit reason.

Related Functions

GetRdcm, GetRdcmArr, WriteRdciRdcm

Parent topic: Data Capture API Functions