Keywords: sybase

## 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)