Product Documentation

FairCom ISAM for C

Previous Topic

Next Topic

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 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 were ignored.

Setting fget_input to a pointer to a function with this prototype:

pTEXT GETINPUT (pTEXT Message, pTEXT Buffer, NINT MaxCount, pVOID tag);

  • Message is the prompt to "display".
  • Buffer is the output buffer where the input should be placed.
  • MaxCount in the maximum size of the buffer.
  • tag is the “usertag” specified in the CTSQLIMPOPTS used when calling the ctSQLImportTable function

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)

  • msg is the message to be printed.
  • lvl is one of the following:

    SQLIMP_PRINT_EMSG - error message

    SQLIMP_PRINT_WMSG - warning message

    SQLIMP_PRINT_MSG - generic message

  • tag is the “usertag” specified in the CTSQLIMPOPTS used when calling the ctSQLImportTable function. It may be useful to pass information like the file handle to print or a Windows handle for GUI.

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


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.

Previous Topic

Next Topic

CTSQLIMPOPTS structure prior to V11.2.3

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;

TOCIndex