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.

`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`

`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`