Sybase Module Manual

Previous: 3.4 CS_LOCALE Objects Up: 3 sybasect Next: 3.6 CS_COMMAND Objects

---

3.5 CS_CONNECTION Objects

Calling the ct_con_alloc() method of a CS_CONTEXT object will create a CS_CONNECTION object. When the CS_CONNECTION object is deallocated the Sybase ct_con_drop() function will be called for the connection.

CS_CONNECTION objects have the following interface:

ctx

This is a read only reference to the parent CS_CONTEXT object. This prevents the context from being dropped while the connection still exists.

strip

An integer which controls right whitespace stripping of char columns. The default value is zero.

debug

An integer which controls printing of debug messages to the debug file established by the set_debug() function. The default value is inherited from the CS_CONTEXT object.

ct_diag(operation [, ...])

Manage Sybase error messages for the connection.

When operation is CS_INIT a single argument is accepted and the Sybase result code is returned. The Sybase ct_diag() function is called like this:

status = ct_diag(conn, CS_INIT, CS_UNUSED, CS_UNUSED, NULL);

When operation is CS_MSGLIMIT two additional arguments are expected; type and num. The Sybase result code is returned. The Sybase ct_diag() function is called like this:

status = ct_diag(conn, CS_MSGLIMIT, type, CS_UNUSED, &num);

When operation is CS_CLEAR an additional type argument is accepted and the Sybase result code is returned. The Sybase ct_diag() function is called like this:

status = ct_diag(conn, CS_CLEAR, type, CS_UNUSED, NULL);

When operation is CS_GET two additional arguments are expected; type and index. A tuple is returned which contains the Sybase result code and the requested CS_SERVERMSG or CS_CLIENTMSG message. None is returned as the message object when the result code is not CS_SUCCEED. The Sybase ct_diag() function is called like this:

status = ct_diag(conn, CS_GET, type, index, &msg);

When operation is CS_STATUS an additional type argument is accepted. A tuple is returned which contains the Sybase result code and the number of messages available for retrieval. The Sybase ct_diag() function is called like this:

status = ct_diag(conn, CS_STATUS, type, CS_UNUSED, &num);

When operation is CS_EED_CMD two additional arguments are expected; type and index. A tuple is returned which contains the Sybase result code and a CS_COMMAND object which is used to retrieve extended error data. The Sybase ct_diag() function is called like this:

status = ct_diag(conn, CS_EED_CMD, type, index, &eed);

The following will retrieve and print all messages from a connection.

def print_msgs(conn, type):
    status, num_msgs = conn.ct_diag(CS_STATUS, type)
    if status != CS_SUCCEED:
        return
    for i in range(num_msgs):
        status, msg = conn.ct_diag(CS_GET, type, i + 1)
        if status != CS_SUCCEED:
            continue
        for attr in dir(msg):
            print '%s: %s' % (attr, getattr(msg, attr))

def print_all_msgs(conn):
    print_msgs(conn, CS_SERVERMSG_TYPE)
    print_msgs(conn, CS_CLIENTMSG_TYPE)
    conn.ct_diag(CS_CLEAR, CS_ALLMSG_TYPE)

ct_cancel(type)

Calls the Sybase ct_cancel() function and returns the Sybase result code. The Sybase ct_cancel() function is called like this:

status = ct_cancel(conn, NULL, type);

ct_connect([server = None])

Calls the Sybase ct_connect() function and returns the Sybase result code. The Sybase ct_connect() function is called like this:

status = ct_connect(conn, server, CS_NULLTERM);

When no server argument is supplied the Sybase ct_connect() function is called like this:

status = ct_connect(conn, NULL, 0);

ct_cmd_alloc()

Allocates and returns a new CS_COMMAND object which is used to send commands over the connection. Calls the Sybase-CT ct_callback() function like this:

status = ct_cmd_alloc(conn, &cmd);

The result is a tuple containing the Sybase result code and a new instance of the CS_COMMAND class. None is returned as the CS_COMMAND object when the result code is not CS_SUCCEED.

blk_alloc([version = BLK_VERSION_100])

Allocates and returns a new CS_BLKDESC object which is used to perform bulkcopy over the connection. Calls the Sybase blk_alloc() function like this:

status = blk_alloc(conn, version, &blk);

The result is a tuple containing the Sybase result code and a new instance of the CS_BLKDESC class. None is returned as the CS_BLKDESC object when the result code is not CS_SUCCEED.

ct_close([option = CS_UNUSED])

Calls the Sybase ct_close() function like this:

status = ct_close(conn, option);

Returns the Sybase result code.

ct_con_drop()

Calls the Sybase ct_con_drop() function like this:

status = ct_con_drop(conn);

Returns the Sybase result code.

This method will be automatically called when the CS_CONNECTION object is deleted. Applications do not need to call the method.

ct_con_props(action, property [, value])

Sets, retrieves and clears properties of the connection object.

When action is CS_SET a compatible value argument must be supplied and the method returns the Sybase result code. The Sybase-CT ct_con_props() function is called like this:

/* boolean property value */
status = ct_con_props(conn, CS_SET, property, &bool_value, CS_UNUSED, NULL);

/* int property value */
status = ct_con_props(conn, CS_SET, property, &int_value, CS_UNUSED, NULL);

/* string property value */
status = ct_con_props(conn, CS_SET, property, str_value, CS_NULLTERM, NULL);

When action is CS_GET the method returns a tuple containing the Sybase result code and the property value. The Sybase-CT ct_con_props() function is called like this:

/* boolean property value */
status = ct_con_props(conn, CS_GET, property, &bool_value, CS_UNUSED, NULL);

/* int property value */
status = ct_con_props(conn, CS_GET, property, &int_value, CS_UNUSED, NULL);

/* string property value */
status = ct_con_props(conn, CS_GET, property, str_buff, sizeof(str_buff), &buff_len);

When action is CS_CLEAR the method returns the Sybase result code. The Sybase-CT ct_con_props() function is called like this:

status = ct_con_props(conn, CS_CLEAR, property, NULL, CS_UNUSED, NULL);

The recognised properties are:

property	type
CS_ANSI_BINDS	bool
CS_ASYNC_NOTIFS	bool
CS_BULK_LOGIN	bool
CS_CHARSETCNV	bool
CS_CONFIG_BY_SERVERNAME	bool
CS_DIAG_TIMEOUT	bool
CS_DISABLE_POLL	bool
CS_DS_COPY	bool
CS_DS_EXPANDALIAS	bool
CS_DS_FAILOVER	bool
CS_EXPOSE_FMTS	bool
CS_EXTERNAL_CONFIG	bool
CS_EXTRA_INF	bool
CS_HIDDEN_KEYS	bool
CS_LOGIN_STATUS	bool
CS_NOCHARSETCNV_REQD	bool
CS_SEC_APPDEFINED	bool
CS_SEC_CHALLENGE	bool
CS_SEC_CHANBIND	bool
CS_SEC_CONFIDENTIALITY	bool
CS_SEC_DATAORIGIN	bool
CS_SEC_DELEGATION	bool
CS_SEC_DETECTREPLAY	bool
CS_SEC_DETECTSEQ	bool
CS_SEC_ENCRYPTION	bool
CS_SEC_INTEGRITY	bool
CS_SEC_MUTUALAUTH	bool
CS_SEC_NEGOTIATE	bool
CS_SEC_NETWORKAUTH	bool
CS_CON_STATUS	int
CS_LOOP_DELAY	int
CS_RETRY_COUNT	int
CS_NETIO	int
CS_TEXTLIMIT	int
CS_DS_SEARCH	int
CS_DS_SIZELIMIT	int
CS_DS_TIMELIMIT	int
CS_ENDPOINT	int
CS_PACKETSIZE	int
CS_SEC_CREDTIMEOUT	int
CS_SEC_SESSTIMEOUT	int
CS_APPNAME	string
CS_HOSTNAME	string
CS_PASSWORD	string
CS_SERVERNAME	string
CS_USERNAME	string
CS_TDS_VERSION	string
CS_DS_DITBASE	string
CS_DS_PASSWORD	string
CS_DS_PRINCIPAL	string
CS_DS_PROVIDER	string
CS_SEC_KEYTAB	string
CS_SEC_MECHANISM	string
CS_SEC_SERVERPRINCIPAL	string
CS_TRANSACTION_NAME	string
CS_LOC_PROP	CS_LOCALE
CS_EED_CMD	CS_COMMAND

For an explanation of the property values and get/set/clear semantics please refer to the Sybase documentation.

The following will allocate a connection from a library context, initialise the connection for in-line message handling, and connect to the named server using the specified username and password.

def connect_db(ctx, server, user, passwd):
    status, conn = ctx.ct_con_alloc()
    if status != CS_SUCCEED:
        raise CSError(ctx, 'ct_con_alloc')
    if conn.ct_diag(CS_INIT) != CS_SUCCEED:
        raise CTError(conn, 'ct_diag')
    if conn.ct_con_props(CS_SET, CS_USERNAME, user) != CS_SUCCEED:
        raise CTError(conn, 'ct_con_props CS_USERNAME')
    if conn.ct_con_props(CS_SET, CS_PASSWORD, passwd) != CS_SUCCEED:
        raise CTError(conn, 'ct_con_props CS_PASSWORD')
    if conn.ct_connect(server) != CS_SUCCEED:
        raise CTError(conn, 'ct_connect')
    return conn

ct_options(action, option [, value])

Sets, retrieves and clears server query processing options for connection.

When action is CS_SET a compatible value argument must be supplied and the method returns the Sybase result code. The Sybase-CT ct_options() function is called like this:

/* bool option value */
status = ct_options(conn, CS_SET, option, &bool_value, CS_UNUSED, NULL);

/* int option value */
status = ct_options(conn, CS_SET, option, &int_value, CS_UNUSED, NULL);

/* string option value */
status = ct_options(conn, CS_SET, option, str_value, CS_NULLTERM, NULL);

/* locale option value */
status = ct_options(conn, CS_SET, option, locale, CS_UNUSED, NULL);

When action is CS_GET the method returns a tuple containing the Sybase result code and the option value. The Sybase-CT ct_options() function is called like this:

/* bool option value */
status = ct_options(conn, CS_GET, option, &bool_value, CS_UNUSED, NULL);

/* int option value */
status = ct_options(conn, CS_GET, option, &int_value, CS_UNUSED, NULL);

/* string option value */
status = ct_options(conn, CS_GET, option, str_buff, sizeof(str_buff), &buff_len);

When action is CS_CLEAR the method returns the Sybase result code. The Sybase-CT ct_options() function is called like this:

status = ct_options(conn, CS_CLEAR, option, NULL, CS_UNUSED, NULL);

The recognised options are:

option	type
CS_OPT_ANSINULL	bool
CS_OPT_ANSIPERM	bool
CS_OPT_ARITHABORT	bool
CS_OPT_ARITHIGNORE	bool
CS_OPT_CHAINXACTS	bool
CS_OPT_CURCLOSEONXACT	bool
CS_OPT_FIPSFLAG	bool
CS_OPT_FORCEPLAN	bool
CS_OPT_FORMATONLY	bool
CS_OPT_GETDATA	bool
CS_OPT_NOCOUNT	bool
CS_OPT_NOEXEC	bool
CS_OPT_PARSEONLY	bool
CS_OPT_QUOTED_IDENT	bool
CS_OPT_RESTREES	bool
CS_OPT_SHOWPLAN	bool
CS_OPT_STATS_IO	bool
CS_OPT_STATS_TIME	bool
CS_OPT_STR_RTRUNC	bool
CS_OPT_TRUNCIGNORE	bool
CS_OPT_DATEFIRST	int
CS_OPT_DATEFORMAT	int
CS_OPT_ISOLATION	int
CS_OPT_ROWCOUNT	int
CS_OPT_TEXTSIZE	int
CS_OPT_AUTHOFF	string
CS_OPT_AUTHON	string
CS_OPT_CURREAD	string
CS_OPT_CURWRITE	string
CS_OPT_IDENTITYOFF	string
CS_OPT_IDENTITYON	string

For an explanation of the option values and get/set/clear semantics please refer to the Sybase documentation.

---

Sybase Module Manual

Previous: 3.4 CS_LOCALE Objects Up: 3 sybasect Next: 3.6 CS_COMMAND Objects

---

Release 0.37, documentation updated on April 07, 2005.