|
|
|
AfterRecRead(), AfterRecWrite(), AfterRecConv(), BeforeOpens(),and BeforeFirst() are callback functions that can be used to perform verifications on the record being migrated, implementing custom error handling, setting table and record properties, etc.
The callbacks have the following prototype:
NINT (* MigrFunc) (CTHANDLE Source, CTHANDLE Dest, CTDBRET err);
The callbacks should handle the error code passed in and return one of:
AfterRecRead(): The migration logic calls this function callback after having read a record from the source table. It is important to note this callback is not called immediately by c-treeDB API after reading the record from the table at the ISAM level, but by the migration logic after c-treeDB API reads the record and performs any c-treeDB API internal operations needed for c-treeDB API functionalities. When this function is implemented, it should perform error handling. The Source parameter is the record handle. Dest is always NULL.
AfterRecWrite(): This function callback is called after having written a record to the destination table. Source and Dest parameters of the function call are record handles.
AfterRecConv(): This function callback is called after converting the source record into the destination record. This is most useful for error checking. Source and Dest parameters of the function call are record handles.
BeforeOpens(): This function callback is called before opening the tables. Source and Dest parameters of the function call are table handles.
BeforeFirst(): This function callback is called before reading the first record, hence before starting the actual record migration. Source and Dest parameters of the function call are table handles.
Error Handling Callback
ErrorMessage(): When specified, this function callback is called in order to display error messages. If set to NULL, the error message display is skipped.
The function prototype is as follows:
VOID (* ErrMsgFunc) (pTEXT msg);
msg is the error message. You can take advantage of this callback if you need to output error messages inside the callbacks implementation by using the macro PRINT_ERROR(msg).
Memory Usage
memoryKB: This is the amount of memory to use for the rebuild (default is 50Mb).
Source and Destination Objects:
hSourceTbl, hDestTbl: These are pointers to the source and destination table handles. These can be set to NULL and, in this case, the handles are allocated and freed internally. Providing these handles is useful in cases when it is necessary to set a table property, such as a callback at c-treeDB API level. The handle must not be active; there should be no open table linked to the handle.
hSourceRec, hDestRec: These are pointers to the source and destination record handles. These can be set to NULL and, in this case, the handles are allocated and freed internally. The handle must relate to the proper table (i.e., hSourceRec = ctdbAllocRecord(hSourceTbl);)
Field Mappings
fmap: This is the structure where the bulk of your customizations will take place. This is a pointer to a field conversion array, which is NULL for default behavior. When this field is not NULL, it is expected to contain an array of FieldMap elements. The number of elements in the array MUST equal the number of fields in the destination table (do not count internal c-treeDB API fields). Each element is related to a field in the destination table in order, i.e., the first field corresponds to the first element in the array, the second field to the second array element and so forth. This structure provides a mechanism allowing code to read a field (sfldno) from a source table and store this field in a string used to insert the field into the destination record using ctdbSetFieldAsString().
FieldMap has the following definition:
typedef struct _fieldmap {
NINT sfldno;
GetBufferLenFunc GetBufferLen;
GetFieldFunc GetFieldAsString;
IsNullFunc IsNullField;
pTEXT dfl_value;
} FieldMap;
sfldno: This is the field number on the source table. Set to CT_MIGRATE_NEW_FIELD in the case when there is no corresponding field in the source table.
GetBufferLen: This optional pointer points to a function returning the size of the string used when retrieving the source field into a string using the GetFieldAsString function pointer. When this field is not specified, the field is copied without any kind of conversion, i.e., a binary copy.
The function prototype is as follows:
VRLEN (* GetBufferLenFunc) (CTHANDLE Handle, NINT FieldNbr);
Where Handle is the record handle the logic will pass to the function and FieldNbr is the field number on the source table. The function should return the buffer size.
GetFieldAsString: This optional pointer refers to a function to convert the field in the source record into a proper string that can be stored into the destination field using the ctdbSetFieldAsString() function. Please notice that the destination field does not necessarily need to be a string field as c-treeDB API is able to convert the string into the appropriate field type. When GetBufferLen is not specified, this is copied without any conversion.
The function prototype is as follows:
CTDBRET (* GetFieldFunc) (CTHANDLE Handle, NINT FieldNbr, CTSTRING pValue, VRLEN size);
Where Handle is the record handle, FieldNbr is the field number in the source table, pValue is a buffer of size bytes that the function must fill with the proper information as fetched from the source record. The function should return CTDBRET_OK on success, otherwise an error code.
Where Handle is the record handle, FieldNbr is the field number in the source table. The function should return YES if the field is NULL (or should be considered as NULL), NO otherwise.
dfl_value: A string containing the default value to store in the field when sfldno is CT_MIGRATE_NEW_FIELD or the source field is set to NULL.
