Keywords: sybase

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