|
|
|
FairCom Server supports loading a Full-Text Index (FTI) with existing records in the background. To simplify the use of background load thread for FTI at creation time, the c-treeDB functions listed below have been implemented:
Note: It is not possible to delete an FTI for which a background load has been started and still not finished. Attempting this operation causes the ctdbAlterTable() to fail with error CTDBRET_LOADISACTIVE (4166 new error code).
For advanced users, see:
|
|
|
For Advanced Users
FairCom Server supports loading a Full-Text Index (FTI) with existing records in the background. This means that an FTI can be quickly created with the data file open in exclusive mode, and then the data file can be closed and reopened in shared mode to permit other connections to access the file while the original connection requests a background thread to load the FTI from the records in the data file.
The status of the background load can be monitored. When the background load is requested, it is assigned a user-defined load identifier. The status of all requested background load operations for a particular data file is stored as a resource in that data file.
The following information is stored for each background load:
/* Background load (of index or record update callback) details: */
typedef struct bgldinf {
LONG8 queuedtime; /* time at which the load was queued */
LONG8 statustime; /* time at which current status was reported */
LONG8 offset; /* current offset in file */
BGLDSTT status; /* current load status */
LONG errcod; /* background load error code */
LONG curpct; /* current percentage complete */
LONG pad; /* padding for structure alignment */
TEXT cbname[BGLDIDZ];/* name of the callback function */
TEXT loadid[BGLDIDZ];/* ID for this background load operation */
} BGLDINF, *pBGLDINF;
Note: The Full-Text Index must be committed before it can be used. An FTI cannot be created and dropped in the same transaction.
Requesting a background load of an FTI
To request a background load of an FTI, call the ctRecordUpdateCallbackControl() function, specifying an opcode of RUCBCTLqueuecallback and the name of the FTI's record update callback function, which is $FTS$indexname.
Below is an example showing the background load of the FTI named myFTSidx001 on the file qafulltextsearch.dat, using a load identifier of myftsload. This load identifier can be used to monitor the progress of the background load. Note that in this example, datno is the data file number for the data file, which the application has already opened:
RUCBCTL rucbctl;
RUCBQCB rucbqcb;
memset(&rucbctl,0,sizeof(rucbctl));
memset(&rucbqcb,0,sizeof(rucbqcb));
rucbctl.verson = RUCBCTL_VERS_V01;
rucbctl.opcode = RUCBCTLqueuecallback;
rucbctl.bufsiz = sizeof(rucbqcb);
rucbctl.bufptr = (pTEXT) &rucbqcb;
rucbqcb.verson = RUCBQCB_VERS_V01;
rucbqcb.datnam = "qafulltextsearch.dat";
rucbqcb.datno = datno;
rucbqcb.cbname = "$FTS$myFTSidx001";
rucbqcb.loadid = "myftsload";
if ((rc = (COUNT) ctRecordUpdateCallbackControl(&rucbctl))) {
printf("Error: Failed to queue record update callback invocation: %d (%d)\n",
rc,sysiocod);
goto err_ret;
}
printf("Successfully queued record update callback invocation.\n");
The dfkutl utility supports an option to request a background load of an FTI. Use the -queuecbkload option, specifying the name of the data file, the callback, and the load ID. Here is an example:
dfkctl -queuecbkload qafulltextsearch.dat $FTS$myFTSidx001 myftsload
Successfully queued callback invocation for file qafulltextsearch.dat.
Monitoring a background load of a full text index
To monitor the status of a background load of a full text index, call the ctGetBackgroundLoadStatus() function, specifying the data file number and the load identifier. Below is an example:
printf("Waiting for full text index update to complete...\n");
while (1) {
pBGLDRES
pbgldres;
BGLDRES
bgldres;
NINT rc,reslen;
/* Read status from resource. */
reslen = sizeof(bgldres);
pbgldres = &bgldqres;
if (!(rc = ctGetBackgroundLoadStatus(datno,rucbqcb.loadid,&pbgldres,&reslen))) {
printf("Queued callback load resource: status=%d offset=" ctLLnd(10) " (%3d%%)\n",
bgldres.bgldi[0].status,bgldres.bgldi[0].offset,bgldres.bgldi[0].curpct);
if (pbgldres->bgldi[0].status == BGLD_SUCCEEDED) {
printf("Full text index background load completed successfully.\n");
break;
} else if (pbgldres->bgldi[0].status == BGLD_FAILED) {
rc = bgldres.bgldi[0].errcod;
printf("Error: Full text index background load terminated with error %d\n",
rc);
break;
} else {
ctThrdSleep(200);
}
} else {
printf("Error: Failed to read background load status: %d\n", rc);
break;
}
}
The dfkutl utility supports an option to read the status of a background load of a full text index. Use the -getbgload option, specifying the name of the data file and the load id. Here is an example:
dfkctl -getbgload qafulltextsearch.dat myftsload -h 1 -i 1 1
status errcod offset curpct callback
succeeded 0 1214400 100% $FTS$myFTSidx001
loadid: myftsload
queuedtime: Wed Sep 6 12:18:40 2017
statustime: Wed Sep 6 12:16:58 2017
If the load id is not specified, the status of all background loads for a data file is displayed. The background load status is stored in a resource in the data file. The status entries remain in the resource even after the background load completes so the status can be examined after load completion. To delete an entry from this resource, use the dfkctl utility's -delbgload option, specifying the name of the data file and optionally the load ID. If no load id is specified, all entries are deleted from the resource. Here is an example:
dfkctl -delbgload qafulltextsearch.dat myftsload
Successfully deleted status of all background loads for file qafulltextsearch.dat
Requesting a background load of a c-tree B+-tree index
c-tree also supports a background load of a c-tree B+-tree index by calling the ctDeferredIndexControl() function with opcode of ctDeferredIndexControl. It is now possible to assign a load ID to the background load of a B+-tree index.
Below is an example. Note the use of DFKQIL structure version 2 instead of version 1. Version 2 of the structure adds a loadid field:
DFKCTL dfkctl;
DFKQIL dfkqil;
LONG idxlst[1];
memset(&dfkctl,0,sizeof(dfkctl));
memset(&dfkqil,0,sizeof(dfkqil));
dfkctl.verson = DFKCTL_VERS_V01;
dfkctl.opcode = DFKCTLqueueload;
dfkctl.bufsiz = sizeof(dfkqil);
dfkctl.bufptr = (pTEXT) &dfkqil;
dfkqil.verson = DFKQIL_VERS_V02;
dfkqil.datno = datno;
dfkqil.numidx = 1;
idxlst[0] = datno + 1;
dfkqil.idxlst = idxlst;
dfkqil.loadid = "myindexload";
if ((rc = ctDeferredIndexControl(&dfkctl)) != NO_ERROR) {
printf("Error: Failed to schedule index load: %d\n",
rc);
goto err_ret;
}
printf("Successfully scheduled index load.\n");
The dfkutl utility supports an option to request a background load of a B+-tree index. Use the -queueidxload option, specifying the name of the data file, the callback, and the load id. Here is an example:
dfkctl -queueidxload qafulltextsearch.dat 1 id=myftsload
Successfully queued callback invocation for file qafulltextsearch.dat.
See Also
