|
|
|
ctSQLImportTable
Imports a table to the FairCom data dictionaries.
Note: See the fget_input note below for an important Compatibility Change in V11.2.3 and later.
Declaration
The function prototype is as follows:
NINT ctSQLImportTable(pCTSQLIMPOPTS pctsqlimpopts);
Description
The caller passes the address of a CTSQLIMPOPTS structure, which specifies the table import options (corresponding command-line flags in parentheses). The full CTSQLIMPOPTS structure is defined in ctdbsdk.h, which is as follows in V11.2.3 and later (the remarks indicate the corresponding ctsqlimp options):
pTEXT tblnam; /* <table_name>: name of table to import */
pTEXT symnam; /* -n <symbolic_name>: symbolic table name */
pTEXT prefix; /* -q <prefix>: table name prefix */
pTEXT dbsnam; /* -d <database_name>: name of FairCom DB SQL database
(default: ctreeSQL) */
pTEXT srvnam; /* -s <server_name>: FairCom DB SQL Server name
(default: FAIRCOMS) */
pTEXT usrnam; /* -u <user_name>: userid for connecting to
FairCom DB SQL Server */
pTEXT usrpwd; /* -a <password>: password for authentication */
pTEXT tblown; /* -o <owner>: assign table owner */
pTEXT prikey; /* -m <idname>: set 'idxname' as primary key */
pTEXT paddin; /* -f <s|z|sz>: force string padding to
(s)paces (z)eroes or (sz)spaces zero terminated */
SQLCBF clbkfn; /* callback function */
NINT chkfld; /* -k: skip fields that don't comply with conventional
identifier rules */
NINT skpidx; /* -x: skip indices */
NINT rmlink; /* -r: unlink table from database */
NINT frctbl; /* -c: allow table names that don't comply with */
NINT grntpb; /* -b: grant public access permissions */
NINT nonint; /* -i: non-interactive mode: ignore errors and continue */
NINT grntro; /* -B: grant public read-only access permissions
(V10.3 and later) */
NINT promot; /* -p: promote unsigned types to greater signed type */
NINT prmver; /* -P: promote unsigned types to greater signed type and
set check for fitting value */
NINT strinz; /* -z: allow indices with missing string terminator in
key segments */
NINT lobsiz; /* -l <size>: specify LONGVAR* field size threshold */
NINT ignnam; /* -g: ignore existing index name in IFIL resource */
NINT nintrl; /* -j: non-interactive relink of existing table */
pTEXT script; /* -w: build script file with CREATE statements
(don't import table) */
pTEXT extdef; /* -e: get DODA definitions in XML format from 'xmlfile */
PRINTFNC print_message; /* ctSQLImportTable print message function */
GETINPUT fget_input; /* ctSQLImportTable interactive mode input function */
pVOID usertag; /* user tag for print_message and fget_input */
NINT dropstrict; /* error out when dropping table if missing in
dictionaries */
CTBOOL keepextra; /* keep existing permissions and synonym
(does not remove nor add them),
there is no ctsqlimp switch for this option */
(If you are using a FairCom version earlier than V11.2.3, see the CTSQLIMPOPTS structure prior to V11.2.3 page.)
ctSQLImportTable() is implemented with c-treeDB API functions. An application using only ISAM or Low-Level functions can call ctSQLImportTable() provided the application #includes the c-treeDB header file ctdbsdk.h and links with a c-tree client library that is built with underlying c-treeDB C API support.
Notes:
Exclusive Open:
Prior to V12, this function call needed an exclusive open. This requirement has been relaxed starting in V12 forward.
fget_input:
Setting fget_input to SQLIMP_CBK_FNC or NULL implies that the ctSQLImportTable requests input and simply behaves as default or as specified in the callback.
Compatibility Change (V11.2.3 and later): When using this setting, the “nonint” member needs to be set to 1 (non-interactive) or the ctSQLImportTable fails because of bad setting (c-treeDB error 4004, cannot be interactive without an input function).
Setting fget_input to SQLIMP_IO_FNC indicates to use the default input function of ctsqlimp utility. This was the default ctSQLImportTable behavior before this change, with some exceptions that where ignored.
Setting fget_input to a pointer to a function with this prototype:
pTEXT GETINPUT (pTEXT Message, pTEXT Buffer, NINT MaxCount, pVOID tag);
clbkfn field:
The clbkfn field can be used to specify a callback function called by ctSQLImportTable() in certain situations. If no callback function address is specified, c-tree uses the default callback function SQLLinkCallback() found in ctsqlimp.c. This default callback function prompts the user for input in some situations. To avoid these prompts, developers can implement their own version of this function and can pass the address of this function to ctSQLImportTable() by setting the clbkfn field to the address of the custom callback function.
Reuse of logon:
The srvnam member can be set to SQLIMP_REUSE_LOGON to indicate the internal code should not attempt a new session logon but reuse the current c-tree environment, which is already logged. Note that this is enforced by the code for server-side calls.
For server-side calls the srvnam member can be set to SQLIMP_REUSE_DB and usrnam to a ctdbdatabase handle (instead to a database name) to indicate the internal logic should neither attempt to log onto a new session nor connect to a new database but reuse the database handle passed in and the session it belongs to.
print_message:
Setting print_message to SQLIMP_CBK_FNC or NULL implies that the ctSQLImportTable does not print any message.
Setting print_message to SQLIMP_IO_FNC instructs it to use the default messaging reporting of the ctsqlimp utility (default ctSQLImportTable behavior before V11.2.3).
Setting the pointer to a function with this prototype:
VOID PRINTFNC(NINT lvl, pTEXT msg, pVOID tag)
SQLIMP_PRINT_EMSG - error message
SQLIMP_PRINT_WMSG - warning message
SQLIMP_PRINT_MSG - generic message
Call Back Function
Prototype
CTBOOL SQLLinkCallback(CTSQLCB_MODE mode, pTEXT msg, CTBOOL def, pVOID extra)
CTSQLCB_MODE |
enum |
Function |
|---|---|---|
CTSQLCB_ERROR |
1 |
handle error |
CTSQLCB_WARNING |
2 |
handle warning |
CTSQLCB_CONFIRM_SKIPIDX |
3 |
confirm skipping index import |
CTSQLCB_CONFIRM_PUTIFIL |
4 |
confirm PUTIFIL update |
CTSQLCB_CONFIRM_NOPUTIFIL |
5 |
confirm continuing after skipping PUTIFIL |
CTSQLCB_CONFIRM_REPLACELNK |
6 |
confirm replacing existing table link |
CTSQLCB_CONFIRM_CHANGEPAD |
7 |
confirm changing string pad strategy |
CTSQLCB_CONFIRM_SPACEPAD |
8 |
confirm space padding or zeroes padding |
CTSQLCB_CONFIRM_NULLTERM |
9 |
confirm NULL terminator |
CTSQLCB_CONFIRM_PUTPAD |
10 |
confirm updating PAD resource |
CTSQLCB_CONFIRM_NOPUTPAD |
11 |
confirm continuing after skipping upd PAD |
CTSQLCB_CONFIRM_SKPHIDFLD |
12 |
confirm skip of FC-ODBC hidden field |
CTSQLCB_CONFIRM_SKPHFLDIDX |
13 |
confirm skip of hidden field's indexes |
CTSQLCB_RETURN_SYMTBLNAME |
14 |
return alternate symbolic table name |
CTSQLCB_ELAB_IDX |
15 |
confirm index elaboration |
CTSQLCB_PROMOTE_UINT |
16 |
promote unsigned integer to greater signed type |
CTSQLCB_RETURN_PRIIDXNAME |
17 |
return primary key index name |
CTSQLCB_RETURN_TBLUID |
18 |
return table id |
CTSQLCB_STRING_PARTSEG |
19 |
allow segments on strings missing last byte |
CTSQLCB_FORCE_PADDING |
20 |
force string padding |
CTSQLCB_RETURN_MAXFLDLEN |
21 |
return maximum length of fields |
CTSQLCB_RETURN_IDXMETHOD |
22 |
return SQL index method id |
CTSQLCB_CONFIRM_NONCONVIDS |
23 |
confirm import of non-conventional identifiers |
CTSQLCB_GRANT_PUBLIC |
24 |
grant access to public (all SQL users) |
CTSQLCB_CONFIRM_PRIIDX |
25 |
confirm if primary key (NO calls #17 YES is primary) |
CTSQLCB_RETURN_TBLPREFIX |
26 |
return prefix to table name |
CTSQLCB_CONFIRM_MAXIDXENTRIES |
27 |
confirm continuing on reaching max idx fields |
CTSQLCB_PROMOTE_UINT_CHECK |
28 |
add check constraint for promoted unsigned integer |
CTSQLCB_GRANT_PUBLIC_RO |
29 |
grant read-only access to public (all SQL users) |
CTSQLCB_CONFIRM_MAXKEYSEG |
30 |
confirm continuing when #of seg > MAX_KEY_SEG |
CTSQLCB_CONFIRM_MAXIDX |
31 |
confirm continuing when #of indices > MAX_DAT_KEY |
CTSQLCB_CONFIRM_INDEXTRUNC |
32 |
allow indexes with rightmost segment(s) on hidden field(s) |
CTSQLCB_RETURN_TBLORIGIN |
33 |
return table origin (10 chars) |
CTSQLCB_CONFIRM_SKPREGFLD |
34 |
confirm hiding of a field that would be exposed |
CTSQLCB_CONFIRM_KEEPEXTRAS |
35 |
keep information in sys*auth and sys synonyms tables during unlink/link operation |
CTSQLCB_CONFIRM_NULKEY_IMP |
36 |
confirm import of ISAM keys with NUL key support |
Example
SQLCBF myCB(CTSQLCB_MODE mode, pTEXT msg, CTBOOL def, pVOID extra) {
unsigned char input[256], *ch;
ch = &input[0];
switch (mode)
{
case CTSQLCB_ERROR:
printf("ERROR: %S\n", msg);
return def;
case CTSQLCB_WARNING:
printf("WARNING %s\n", msg);
return def;
case CTSQLCB_CONFIRM_SPACEPAD:
case CTSQLCB_CONFIRM_CHANGEPAD:
case CTSQLCB_CONFIRM_PUTIFIL:
return NO;
/* following modes that defaults to YES in non-interactive mode */
case CTSQLCB_CONFIRM_NOPUTIFIL:
case CTSQLCB_CONFIRM_NOPUTPAD:
return YES;
case CTSQLCB_CONFIRM_REPLACELNK:
return YES;
}
return def;
}
NINT main (NINT argc, pTEXT argv[])
{
NINT rc = 0;
CTSQLIMPOPTS impopts;
ctsfill(&impopts, 0, sizeof(impopts));
impopts.tblnam = ".\\customer.dat";
impopts.symnam = "customer";
impopts.dbsnam = "ctreeSQL";
impopts.srvnam = "FAIRCOMS@localhost";
impopts.usrnam = "ADMIN";
impopts.usrpwd = "ADMIN";
impopts.clbkfn = myCB;
impopts.nintrl = 1;
impopts.nonint = 0;
impopts.fget_input = SQLIMP_IO_FNC;
if (!(rc = ctSQLImportTable(&impopts)))
ctrt_printf("Import ok\n");
else
ctrt_printf("Import failed: %d, %d\n", rc, sysiocod);
}
Returns
Value |
Symbolic Constant |
Explanation |
|---|---|---|
0 |
NO_ERROR |
Successful operation. |
12 |
FNOP_ERR |
Could not open file. Either file does not exist, filnam points to incorrect file name, or file is locked by another process. Check sysiocod for the system-level error. For ISAM functions, check isam_fil for the specific file number. For the client/server model only, if a file open returns FNOP_ERR, check sysiocod. If sysiocod = FCNF_COD, (-8), the file exists but there is file mode conflict preventing the file from being opened. For example, requesting an ctEXCLUSIVE open when the file is already open ctSHARED. The failure to open the file with system error 32 could happen due to third-party backup software having the file open even if it does not lock regions of the file. For example, if the software has the file open in exclusive mode, an attempt by c-tree to open the file in shared or exclusive mode will fail. If the software has the file open in shared mode, an attempt by c-tree to open the file in exclusive mode will fail. |
See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.
Example
NINT rc;
CTSQLIMPOPTS impopts;
ctsfill(&impopts, 0, sizeof(impopts));
impopts.tblnam = ".\\qasqlimp.dat";
impopts.symnam = "inventory";
impopts.dbsnam = "ctreeSQL";
impopts.srvnam = "FAIRCOMS@localhost";
impopts.usrnam = "ADMIN";
impopts.usrpwd = "ADMIN";
impopts.clbkfn = mySQLLinkCallback;
if (!(rc = ctSQLImportTable(&impopts)))
ctrt_printf("Import ok\n");
else
ctrt_printf("Import failed: %d\n", rc);
History
V11.2.3 and later has ability to optionally retain SQL grants and synonyms on table drop such that they can be retained on subsequent table link. Refer to CTSQLIMPOPTS keepextra member.
|
|
|
If you are using a version of FairCom DB prior to V11.2.3, the CTSQLIMPOPTS structure is as follows. (If you are using the current version of FairCom DB, see the ctSQLImportTable (ctSQLImportTable, ctSQLImportTable) documentation):
typedef struct tagCTSQLIMPOPTS {
pTEXT tblnam; /* name of table to import */
pTEXT symnam; /* (-n) symbolic table name */
pTEXT prefix; /* (-q) table name prefix */
pTEXT dbsnam; /* (-d) name of c-treeSQL database (default: ctreeSQL) */
pTEXT srvnam; /* (-s) FairCom DB SQL Server name (default: FAIRCOMS) */
pTEXT usrnam; /* (-u) userid for connecting to FairCom DB SQL Server */
pTEXT usrpwd; /* (-a) password for authentication */
pTEXT tblown; /* (-o) assign table owner */
SQLCBF clbkfn; /* callback function */
NINT chkfld; /* (-k) skip fields that don't comply with
conventional identifier rules */
NINT skpidx; /* (-x) skip indexes */
NINT rmlink; /* (-r) unlink table from database */
NINT frctbl; /* (-c) allow table names that don't comply with */
NINT grntpb; /* (-b) grant public access permissions */
NINT nonint; /* (-i) non-interactive mode: ignore errors and continue */
} CTSQLIMPOPTS, *pCTSQLIMPOPTS;
