FairCom DB Function Descriptions
ctSQLImportTable
|
|
|
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) */
SQLCBFX clbkfnX; /* new extended callback function */
pTEXT rowidfld; /* --rowid_fld: name of the rowid field NULL to not expose it */
pTEXT rowididx; /* --rowid_idx: name of the rowid index NULL to not expose it */
pTEXT tls_cert; /* --tls: TLS cert file, SQLIMP_BASE_TLS for TLS with no certificate checking */
(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 FairCom DB API API functions. An application using only ISAM or Low-Level functions can call ctSQLImportTable() provided the application #includes the FairCom DB API header file ctdbsdk.h and links with a c-tree client library that is built with underlying FairCom DB API 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 were 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.
tls_cert field:
The tls_cert member can be set to:
1) NULL to not use TLS.
2) SQLIMP_BASE_TLS to use a basic TLS connection with encryption but no certificate checking.
3) A string containing the name of a certificate file to use TLS with a certificate.
Reuse of logon:
This API call differs from others as it directly instantiates a client connection to the server for this specific task. V11.5 introduced a mode to reuse the existing connection. The srvnam member can be set to SQLIMP_REUSE_LOGON to force the SQL Import connection to use the existing client connection when already connected to the server.
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 |
CTSQLCB_GRANT_GROUP_RO |
37 |
grant read-only access to the group the table belongs to. it returns group name in extras (max IDZ including terminator) |
CTSQLCB_RETURN_ROWID_FLD |
38 |
expose to SQL rowid field with given name |
CTSQLCB_RETURN_ROWID_IDX |
39 |
expose to SQL rowid index with given name |
Example
CTBOOL 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 |
CTDBRET_OK |
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;
