|
|
|
ctAlterSchema
Declaration
NINT ctAlterSchema(FILNO datno, pVOID precdsc);
Record Descriptor
typedef struct recdsc {
LONG rdtype; /* type (version macro) of record descriptor */
LONG rdcount; /* number of entries in record descriptor */
LONG oldrln; /* old data record length */
LONG newrln; /* new data record length */
pVOID prdspec; /* record descriptor specification */
} RCDSC, *pRCDSC, **ppRCDSC;
/* record descriptor, version 2 */
typedef struct recdsc2 {
LONG rdtype; /* type of record descriptor - ctRDSCver2 */
LONG rdcount; /* number of entries in record descriptor */
LONG oldrln; /* old data record length */
LONG newrln; /* new data record length */
pTEXT dllname; /* optional field conversion DLL name */
pVOID prdspec; /* record descriptor specification */
} RCDSC2, * pRCDSC2, ** ppRCDSC2;
#define RCACTnochange 0 /* no changes to this field */
#define RCACTaddfield 1 /* add this field */
#define RCACTdelfield 2 /* delete this field */
#define RCACTupdfield 3 /* change attributes of this field */
Description
Alter an existing table schema. This function enables the hot alter table function. To use this feature, first create a file that uses the flexible record support attribute, ctFLEXREC, bit in the splval field of the extended create block structure for the data file. For example:
IFIL myifil = { ... };
XCREBLK xcreblk[2];
NINT rc;
memset(xcreblk,0,sizeof(xcreblk));
xcreblk[0].splval = ctFLEXREC;
rc = CREIFILX8(&myifil, NULL, NULL, 0, NULL, NULL, xcreblk);
Example
RCDSC recdsc = { 0 };
RCSCHD fieldlist[] = {
{RCACTaddfield, "newfield", CT_STRING, 128, "", 1},
{RCACTnochange, "custnum", CT_INT4, 4},
{RCACTdelfield, "field1", CT_STRING, 32},
{RCACTnochange, "field2", CT_STRING, 32},
{RCACTnochange, "field3", CT_STRING, 32}
};
recdsc.rdtype = ctRDSCver1;
recdsc.rdcount = sizeof(fieldlist)/sizeof(*fieldlist);
recdsc.prdspec = fieldlist;
recdsc.oldrln = 0;
recdsc.newrln = 0;
if ((rc = ctAlterSchema(datno, &recdsc))) {
qa_err_printf("Error: Failed to change file schema: %d\n",
rc);
goto err_ret;
Field Conversion Callback
V13 added the ability to define custom field conversions during alter table. It is now possible to include a custom shared library to be used with ctAlterSchema().
This function accepts parameters that use the record descriptor base structure of type RCDSC, and an array of record descriptor structure of type RCSCHD. To support this field conversion feature, we define a new structure, RCDSC2, that contains a field pTEXT dllname to hold the field conversion DLL name, and we defined a new structure RCSCHD2, that contains a field pTEXT fncname to hold the field conversion function name.
The data type of the precdsc pointer in ctAlterSchema() was changed to pVOID such that either a pointer to the RCDSC structure or the RCDSC2 structure can be specified.
To use version 2 of these structures, use the RCDSC2 and RCSCHD2 structures and set the RCDSC2 rdtype field to ctRDSCver2.
The function prototype for the user-defined field conversion function convertfield() is shown here. Note the use of the pRCSCHDN data type, which is a pointer to the current version of RCSCHD structure. The field conversion function should check that the version value passed to the function matches the version of the RCSCHD structure (1 or 2) that the conversion function is using.
NINT convertfield(NINT verson, pRCSCHDN pschema, ppTEXT pdp, pVRLEN premlen, ppTEXT psp, VRLEN datlen, TEXT dbyte, TEXT pbyte)
[IN] verson: Version of pschema structure.
[IN] pschema: Record descriptor for this field.
[IN,OUT] pdp: Destination data pointer.
[IN,OUT] premlen: Remaining length in output buffer.
[IN,OUT] psp: Source data pointer.
[IN] datlen: Number of bytes from source data pointer to end of record image.
[IN] dbyte: String delimiter byte.
[IN] pbyte: String padding byte.
Returns a c-tree error code. NO_ERROR indicates success.
Diagnostics
We added a companion utility function, ctGetRecordConverters(), that can be used to read the record converter information that is stored in the data file by a hot alter schema operation. The ctinfo utility uses this function to read and display the record converter information.
NINT ctGetRecordConverters(FILNO datno, pTEXT buffer, pVRLEN pbuflen);
[IN] datno- Data file number.
[OUT] buffer- Output buffer.
[IN/OUT] pbuflen- On input, holds the size of the output buffer in bytes. If the output buffer is too small to hold the output data, the function returns VBSZ_ERR and sets *pbuflen to the required buffer size in bytes. On success, holds the size of the data that was written to the output buffer.
ctGetRecordConverters() reads the record converters from the specified data file. The record converters are written to the output buffer as a null-terminated string in JSON format.
Returns a c-tree error code. NO_ERROR(0) indicates success.
Example code for a field conversion function can be found in
ctree\source\ctrucbdll.c in the function qaflexrec015_convertfield().
Compatibility
Our implementation approach for version 2 of the hot alter feature allows existing code to operate without any changes. If a new client attempts to use the new feature with an old server, its function call fails with error FVER_ERR (43). Even if a call to ctAlterSchema() specifies version 2 of the hot alter structures, the function call data is sent to the server in version 1 format unless the new structure fields are used, and the record converter is stored in version 1 format in the data file. This makes it possible to preserve backward compatibility of a v2 client with v1 servers.
Contact FairCom if you're interested in implementing this callback capability.
Return Values
Value |
Symbolic Constant |
Explanation |
|---|---|---|
0 |
CTDBRET_OK |
Successful operation. |
See c-tree Plus Error Codes for a complete listing of valid c-tree Plus error values.
Example
See Also
