Create a new set of records using values from an original set of records to populate the new records. Within the current DRMS session, this function creates a record-set structure (DRMS_RecordSet_t) that contains "copies" of the record structures contained in recset. For each record in recset, a new DRMS_Record_t structure is created and assigned a unique record number from the DRMS database. The values of the keywords, links, and segments of the original record in recset are used to populate the newly created record. If mode == DRMS_SHARE_SEGMENTS, the newly created segments will share the segment files with the original record, i.e. the new record will have the same storage unit number (DSINDEX) as the original record. However, keyword and link data will be replicated. If mode == DRMS_COPY_SEGMENTS, the original record's segment files will be copied to a new storage unit slot, and the copied files will be associated with the new record.
The newly created records are placed in the record cache (DRMS_Env_t->record_cache) and are made writeable and assigned a lifetime of lifetime (please see drms_reclifetime for details on lifetime).
Upon successful completion, the function returns a DRMS_RecordSet_t pointer, and sets *status to 0. If an error occurs, the function returns NULL and sets *status to an appropriate error code defined in drms_statuscodes.h. Typical errors are as follows. If recset does not have any legitimate records, then *status is set to DRMS_ERROR_BADRECORDCOUNT. If there was an error receiving one or more proper record numbers from the database server, then *status is set to DRMS_ERROR_BADSEQUENCE. If an error occurs while creating a SUMS slot directory, then *status is set to DRMS_ERROR_MKDIRFAILED.
The caller owns the allocated memory associated with the returned record set and must release it by calling drms_close_records.