3.3 CS_CONTEXT Objects

Calling the cs_ctx_alloc() or cs_ctx_global() function will create a CS_CONTEXT object. When the CS_CONTEXT object is deallocated the Sybase cs_ctx_drop() function will be called for the context.

CS_CONTEXT objects have the following interface:

debug: An integer which controls printing of debug messages to the debug file established by the set_debug() function. The default value is zero.

debug_msg(msg): If the debug member is non-zero the msg argument will be written to the debug file established by the set_debug() function.

cs_config(action, property [, value])

Configures, retrieves and clears properties of the comn library for the context.

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

/* bool property value */
status = cs_config(ctx, CS_SET, property, &bool_value, CS_UNUSED, NULL);

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

/* string property value */
status = cs_config(ctx, CS_SET, property, str_value, CS_NULLTERM, NULL);

/* locale property value */
status = cs_config(ctx, CS_SET, property, locale, CS_UNUSED, NULL);

/* callback property value */
status = cs_config(ctx, CS_SET, property, cslib_cb, CS_UNUSED, NULL);

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

/* bool property value */
status = cs_config(ctx, CS_GET, property, &bool_value, CS_UNUSED, NULL);

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

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

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

status = cs_config(ctx, CS_CLEAR, property, NULL, CS_UNUSED, NULL);

The recognised properties are:

property type

CS_EXTERNAL_CONFIG bool

CS_EXTRA_INF bool

CS_NOAPI_CHK bool

CS_VERSION int

CS_APPNAME string

CS_CONFIG_FILE string

CS_LOC_PROP locale

CS_MESSAGE_CB function

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

ct_callback(action, type [, cb_func = None])

Installs, removes, or queries current Sybase callback function. This is only available when the sybasect module has been compiled without the WANT_THREADS macro defined in sybasect.h.

When CS_SET is passed as the action argument the Sybase-CT ct_callback() function is called like this:

status = ct_callback(ctx, NULL, CS_SET, type, cb_func);

The cb_func argument is stored inside the CS_CONTEXT object. Whenever a callback of the specified type is called by the Sybase CT library, the sybasect wrapper locates the corresponding CS_CONTEXT object and calls the stored function.

If None is passed in the cb_func argument the callback identified by type will be removed. The Sybase result code is returned.

When action is CS_GET the Sybase-CT ct_callback() function is called like this:

status = ct_callback(ctx, NULL, CS_GET, type, &cb_func);

The return value is a two element tuple containing the Sybase result code and the current callback function. When the Sybase result code is not CS_SUCCEED or there is no current callback, the returned function will be None.

The type argument identifies the callback function type. Currently only the following callback functions are supported.

type callback function arguments

CS_CLIENTMSG_CB ctx, conn, msg

CS_SERVERMSG_CB ctx, conn, msg

The following will allocate and initialise a CT library context then will install a callback.

from sybasect import *

def ctlib_server_msg_handler(conn, cmd, msg):
    return CS_SUCCEED

status, ctx = cs_ctx_alloc()
if status != CS_SUCCEED:
    raise CSError(ctx, 'cs_ctx_alloc')
if ctx.ct_init(CS_VERSION_100):
    raise CSError(ctx, 'ct_init')
if ctx.ct_callback(CS_SET, CS_SERVERMSG_CB,
                   ctlib_server_msg_handler) != CS_SUCCEED:
    raise CSError(ctx, 'ct_callback')

ct_loc_alloc()

Allocates a new CS_LOCALE object which is used to control locale settings. Calls the Sybase-CT ct_loc_alloc() function like this:

status = ct_loc_alloc(ctx, &locale);

Returns a tuple containing the Sybase result code and a new instance of the CS_LOCALE class constructed from the locale returned by ct_loc_alloc(). None is returned as the CS_LOCALE object when the result code is not CS_SUCCEED.

ct_con_alloc()

Allocates a new CS_CONNECTION object which is used to connect to a Sybase server. Calls the Sybase-CT ct_callback() function like this:

status = ct_con_alloc(ctx, &conn);

Returns a tuple containing the Sybase result code and a new instance of the CS_CONNECTION class constructed from the conn returned by ct_con_alloc(). None is returned as the CS_CONNECTION object when the result code is not CS_SUCCEED.

ct_config(action, property [, value])

Sets, retrieves and clears properties of the context 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_config() function is called like this:

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

/* string property value */
status = ct_config(ctx, 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_callback() function is called like this:

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

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

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

status = ct_config(ctx, CS_CLEAR, property, NULL, CS_UNUSED, NULL);

The recognised properties are:

property type

CS_LOGIN_TIMEOUT int

CS_MAX_CONNECT int

CS_NETIO int

CS_NO_TRUNCATE int

CS_TEXTLIMIT int

CS_TIMEOUT int

CS_VERSION int

CS_IFILE string

CS_VER_STRING string

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

ct_exit([option = CS_UNUSED])

Calls the Sybase ct_exit() function like this:

status = ct_exit(ctx, option);

Returns the Sybase result code.

ct_init([version = CS_VERSION_100])

Initialises the context object and tells the CT library which version of behaviour is expected. This method must be called immediately after creating the context. The Sybase ct_init() function is called like this:

status = ct_init(ctx, version);

Returns the Sybase result code.

cs_ctx_drop()

Calls the Sybase cs_ctx_drop() function like this:

status = cs_ctx_drop(ctx);

Returns the Sybase result code.

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

cs_diag(operation [, ...])

Manage Open Client/Server error messages for the context.

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

status = cs_diag(ctx, 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 cs_diag() function is called like this:

status = cs_diag(ctx, 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 cs_diag() function is called like this:

status = cs_diag(ctx, CS_CLEAR, type, CS_UNUSED, NULL);

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

status = cs_diag(ctx, 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 cs_diag() function is called like this:

status = cs_diag(ctx, CS_STATUS, type, CS_UNUSED, &num);

The following will retrieve and print all messages from the context.

def print_msgs(ctx):
    status, num_msgs = ctx.cs_diag(CS_STATUS, CS_CLIENTMSG_TYPE)
    if status == CS_SUCCEED:
        for i in range(num_msgs):
            status, msg = ctx.cs_diag(CS_GET, CS_CLIENTMSG_TYPE, i + 1)
            if status != CS_SUCCEED:
                continue
            for attr in dir(msg):
                print '%s: %s' % (attr, getattr(msg, attr))
    ctx.cs_diag(CS_CLEAR, CS_CLIENTMSG_TYPE)

`property`	type
`CS_EXTERNAL_CONFIG`	`bool`
`CS_EXTRA_INF`	`bool`
`CS_NOAPI_CHK`	`bool`
`CS_VERSION`	`int`
`CS_APPNAME`	`string`
`CS_CONFIG_FILE`	`string`
`CS_LOC_PROP`	`locale`
`CS_MESSAGE_CB`	`function`

`type`	callback function arguments
`CS_CLIENTMSG_CB`	`ctx, conn, msg`
`CS_SERVERMSG_CB`	`ctx, conn, msg`

`property`	type
`CS_LOGIN_TIMEOUT`	`int`
`CS_MAX_CONNECT`	`int`
`CS_NETIO`	`int`
`CS_NO_TRUNCATE`	`int`
`CS_TEXTLIMIT`	`int`
`CS_TIMEOUT`	`int`
`CS_VERSION`	`int`
`CS_IFILE`	`string`
`CS_VER_STRING`	`string`