Example: Opening a Client-Library connection

The following code fragment, taken from the ctfirst.c migration sample program, illustrates opening a Client-Library connection:

... deleted initialization code ...
/*
** Step 1.
** Allocate a CS_CONTEXT structure and initialize Client-Libary. The 
** EXIT_ON_FAIL() macro used for return code error checking is defined in 
** dbtoctex.h. If the return code passed to EXIT_ON_FAIL() is not CS_SUCCEED, ** it:
- Cleans up the context structure if the pointer is not NULL.
- Exits to the operating system. 
**
-- if (dbinit() == FAIL 
-- exit(ERREXIT);
*/ret = cs_ctx_alloc(CS_VERSION_150, &context);
EXIT_ON_FAIL(context, ret, "Could not allocate context.");ret = ct_init(context, CS_VERSION_150);
EXIT_ON_FAIL(context, ret, "Client-Library initialization failed.");/* 
... deleted code that defines callback handlers ...

/* 
** Step 3. 
** Connect to the server named by the DSQUERY environment
** variable using the credentials defined in dbtoctex.h
**
**  3a. Allocate a CS_CONNECTION structure.
**  3b. Insert the username, password, and other login parameters 
** into the connection structure.
**  3c. Call ct_connect(), passing the CS_CONNECTION as an argument.
*/
/* 
** Step 3a.
** Allocate a CS_CONNECTION structure. The CS_CONNECTION replaces 
** DB-Library's LOGINREC and DBPROCESS structures. The LOGINREC
** fields are connection properties in Client-Library.
** 
-- login = dblogin();
-- if (login == (LOGINREC *) NULL)
-- {
--   fprintf(ERR_CH, "dblogin() failed. Exiting.\n");
--   dbexit();
--   exit(ERREXIT);
-- }
*/
ret = ct_con_alloc(context, &conn);
EXIT_ON_FAIL(context, ret, "Allocate connection structure failed.");
/* 
** Step 3b.
** Put the username, password, and other login information into the
** connection structure. We do this with ct_con_props() calls.
** After the connection is open, Client-Library makes these properties
** read-only.
**
** USER and PASSWORD are defined in dbtoctex.h
**

-- DBSETLUSER(login, USER);

-- DBSETLPWD(login, PASSWORD);

-- DBSETLAPP(login, "dbfirst");
*/
ret = ct_con_props(conn, CS_SET, CS_USERNAME, USER, STRLEN(USER), NULL);
EXIT_ON_FAIL(context, ret, "Set connection username failed.");
ret = ct_con_props(conn, CS_SET, CS_PASSWORD, PASSWORD, STRLEN(PASSWORD),NULL);
EXIT_ON_FAIL(context, ret, "Set connection password failed.");
ret = ct_con_props(conn, CS_SET, CS_APPNAME, "ctfirst", STRLEN("ctfirst"),       NULL);
EXIT_ON_FAIL(context, ret, "Set connection application name failed.");
/* 
** Step 3c.
** Call ct_connect() to open the connection. Unlike dbopen(), ct_connect()
** uses a connection structure which is already allocated.
**
-- dbproc = dbopen(login, NULL);
-- if (dbproc == (DBPROCESS *) NULL)
-- {
--   fprintf(ERR_CH, "Connect attempt failed. Exiting.\n");
--   dbexit();

--   exit(ERREXIT);
-- }

*/
ret = ct_connect(conn, NULL, STRLEN(NULL));

EXIT_ON_FAIL(context, ret, "Connection attempt failed.");
... deleted command code ...
/*
** Step 5. 
** Close our connection. CS_UNUSED as the second ct_close() parameter 

** requests an "orderly" close. This means that we expect the connection to
** be idle. If we had issued a command to the server, but had not

** read all the results sent by the server, then the connection would
** not be idle and this call would fail.
**
** If ct_close() were to fail here, then the code in EXIT_ON_FAIL() would
** ct_exit(CS_FORCE_EXIT) to force all connections closed before exiting.
**
-- dbclose(dbproc);
*/
ret = ct_close(conn, CS_UNUSED);
EXIT_ON_FAIL(context, ret, "Orderly connection-close failed.");
ret = ct_con_drop(conn);
EXIT_ON_FAIL(context, ret, "ct_con_drop() failed.");
/*
** Clean up Client-Library.
** ct_exit(context, CS_UNUSED) requests an "orderly" exit -- this
** call fails if we have open connections. If it fails, EXIT_ON_FAIL()
** calls ct_exit(context, CS_FORCE_EXIT) to force cleanup of Client-Library.
*/
ret = ct_exit(context, CS_UNUSED);
EXIT_ON_FAIL(context, ret, "ct_exit(CS_UNUSED) failed.");
/*
** Clean up CS-Library. cs_ctx_drop() always fails if ct_init()
** succeeded on the context but ct_exit() did not (or if ct_exit() 
** was not called at all).
*/
(CS_VOID) cs_ctx_drop(context);
context = (CS_CONTEXT *) NULL;
exit(NORMAL_EXIT);
}
... deleted error callback routine code ...