Keywords: sybase

## 3.6 CS_COMMAND Objects

Calling the `ct_cmd_alloc()` method of a `CS_CONNECTION` object will create a `CS_COMMAND` object. When the `CS_COMMAND` object is deallocated the Sybase `ct_cmd_drop()` function will be called for the command.

`CS_COMMAND` objects have the following interface:

`is_eed`
  A read only integer which indicates when the `CS_COMMAND` object is an extended error data command structure.

`conn`
  This is a read only reference to the parent `CS_CONNECTION` object. This prevents the connection from being dropped while the command still exists.

`strip`
  An integer which controls right whitespace stripping of `char` columns. The default value is inherited from the parent connection when the command is created.

`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 parent connection when the command is created.

`ct_bind`(num, datafmt)
  Calls the Sybase-CT `ct_bind()` function and returns a tuple containing the Sybase result code and a `DataBuf` object which is used to retrieve data from the column identified by num. `None` is returned as the `DataBuf` object when the result code is not `CS_SUCCEED`. The Sybase-CT `ct_bind()` function is called like this:

        status = ct_bind(cmd, num, &datafmt, databuf->buff, databuf->copied, databuf->indicator);

  See the description of the `ct_describe()` method for an example of how to use this method in Python.

`ct_cancel`(type)
  Calls the Sybase `ct_cancel()` function like this:

        status = ct_cancel(NULL, cmd, type);

  Returns the Sybase result code.

`ct_cmd_drop`()
  Calls the Sybase-CT `ct_cmd_drop()` function like this:

        status = ct_cmd_drop(cmd);

  Returns the Sybase result code.

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

`ct_command`(type [, ...])
  Calls the Sybase-CT `ct_command()` function and returns the result code. The type argument determines the type and number of additional arguments.

  When type is `CS_LANG_CMD` the method must be called like this:

  `ct_command(CS_LANG_CMD, sql_text [, option `= CS_UNUSED`])`

  Then the Sybase-CT `ct_command()` function is called like this:

        status = ct_command(cmd, CS_LANG_CMD, sql_text, CS_NULLTERM, option);

  When type is `CS_RPC_CMD` the method must be called like this:

  `ct_command(CS_RPC_CMD, proc_name [, option `= CS_UNUSED`])`

  Then the Sybase-CT `ct_command()` function is called like this:

        status = ct_command(cmd, CS_RPC_CMD, proc_name, CS_NULLTERM, option);

  When type is `CS_MSG_CMD` the method must be called like this:

  `ct_command(CS_MSG_CMD, msg_num)`

  Then the Sybase-CT `ct_command()` function is called like this:

        status = ct_command(cmd, CS_MSG_CMD, &msg_num, CS_UNUSED, CS_UNUSED);

  When type is `CS_PACKAGE_CMD` the method must be called like this:

  `ct_command(CS_PACKAGE_CMD, pkg_name)`

  Then the Sybase-CT `ct_command()` function is called like this:

        status = ct_command(cmd, CS_PACKAGE_CMD, pkg_name, CS_NULLTERM, CS_UNUSED);

  When type is `CS_SEND_DATA_CMD` the method must be called like this:

  `ct_command(CS_SEND_DATA_CMD)`

  Then the Sybase-CT `ct_command()` function is called like this:

        status = ct_command(cmd, CS_SEND_DATA_CMD, NULL, CS_UNUSED, CS_COLUMN_DATA);

  For an explanation of the argument semantics please refer to the Sybase documentation.

`ct_cursor`(type [, ...])
  Calls the Sybase `ct_cursor()` function and returns the result code. The type argument determines the type and number of additional arguments.

  When type is `CS_CURSOR_DECLARE` the method must be called like this:

  `ct_cursor(CS_CURSOR_DECLARE, cursor_id, sql_text [, option `= CS_UNUSED`])`

  Then the Sybase-CT `ct_cursor()` function is called like this:

        status = ct_cursor(cmd, CS_CURSOR_DECLARE, cursor_id, CS_NULLTERM, sql_text, CS_NULLTERM, option);

  When type is `CS_CURSOR_UPDATE` the method must be called like this:

  `ct_cursor(CS_CURSOR_UPDATE, table_name, sql_text [, option `= CS_UNUSED`])`

  Then the Sybase-CT `ct_cursor()` function is called like this:

        status = ct_cursor(cmd, CS_CURSOR_UPDATE, table_name, CS_NULLTERM, sql_text, CS_NULLTERM, option);

  When type is `CS_CURSOR_OPTION` the method must be called like this:

  `ct_cursor(CS_CURSOR_OPTION [, option `= CS_UNUSED`])`

  Then the Sybase-CT `ct_cursor()` function is called like this:

        status = ct_cursor(cmd, CS_CURSOR_OPTION, NULL, CS_UNUSED, NULL, CS_UNUSED, option);

  When type is `CS_CURSOR_OPEN` the method must be called like this:

  `ct_cursor(CS_CURSOR_OPEN [, option `= CS_UNUSED`])`

  Then the Sybase-CT `ct_cursor()` function is called like this:

        status = ct_cursor(cmd, CS_CURSOR_OPEN, NULL, CS_UNUSED, NULL, CS_UNUSED, option);

  When type is `CS_CURSOR_CLOSE` the method must be called like this:

  `ct_cursor(CS_CURSOR_CLOSE [, option `= CS_UNUSED`])`

  Then the Sybase-CT `ct_cursor()` function is called like this:

        status = ct_cursor(cmd, CS_CURSOR_CLOSE, NULL, CS_UNUSED, NULL, CS_UNUSED, option);

  When type is `CS_CURSOR_ROWS` the method must be called like this:

  `ct_cursor(CS_CURSOR_ROWS, num_rows)`

  Then the Sybase-CT `ct_cursor()` function is called like this:

        status = ct_cursor(cmd, CS_CURSOR_ROWS, NULL, CS_UNUSED, NULL, CS_UNUSED, num_rows);

  When type is `CS_CURSOR_DELETE` the method must be called like this:

  `ct_cursor(CS_CURSOR_DELETE, table_name)`

  Then the Sybase-CT `ct_cursor()` function is called like this:

        status = ct_cursor(cmd, CS_CURSOR_DELETE, table_name, CS_NULLTERM, NULL, CS_UNUSED, CS_UNUSED);

  When type is `CS_CURSOR_DEALLOC` the method must be called like this:

  `ct_cursor(CS_CURSOR_DEALLOC)`

  Then the Sybase-CT `ct_cursor()` function is called like this:

        status = ct_cursor(cmd, CS_CURSOR_DEALLOC, NULL, CS_UNUSED, NULL, CS_UNUSED, CS_UNUSED);

  For an explanation of the argument semantics please refer to the Sybase documentation.

  The `cursor_sel.py`, `cursor_upd.py`, and `dynamic_cur.py` example programs contain examples of this function.

`ct_data_info`(action, ...)
  Sets and retrieves column IO descriptors.

  When action is `CS_SET` the method must be called like this:

  `ct_data_info(CS_SET, iodesc)`

  Returns the Sybase result code. The Sybase-CT `ct_data_info()` function is called like this:

        status = ct_data_info(cmd, CS_SET, CS_UNUSED, &iodesc);

  When action is `CS_GET` the method must be called like this:

  `ct_data_info(CS_SET, num)`

  Returns a tuple containing the Sybase result code and an `CS_IODESC` object. If the result code is not `CS_SUCCEED` then `None` is returned as the `CS_IODESC` object. The Sybase-CT `ct_data_info()` function is called like this:

        status = ct_data_info(cmd, CS_GET, num, &iodesc);

  For an explanation of the argument semantics please refer to the Sybase documentation.

  The `mult_text.py` example program contains examples of this function.

`ct_describe`(num)
  Calls the Sybase `ct_describe()` function and returns a tuple containing the Sybase result code and a `CS_DATAFMT` object which describes the column identified by num. `None` is returned as the `CS_DATAFMT` object when the result code is not `CS_SUCCEED`.

  The Sybase-CT `ct_describe()` function is called like this:

        status = ct_describe(cmd, num, &datafmt);

  The following constructs a list of buffers for retrieving a number of rows from a command object.

        def row_bind(cmd, count = 1):
            status, num_cols = cmd.ct_res_info(CS_NUMDATA)
            if status != CS_SUCCEED:
                raise 'ct_res_info'
            bufs = []
            for i in range(num_cols):
                status, fmt = cmd.ct_describe(i + 1)
                if status != CS_SUCCEED:
                    raise 'ct_describe'
                fmt.count = count
                status, buf = cmd.ct_bind(i + 1, fmt)
                if status != CS_SUCCEED:
                    raise 'ct_bind'
                bufs.append(buf)
            return bufs

`ct_dynamic`(type, ...)
  Calls the Sybase `ct_dynamic()` function and returns the result code. The type argument determines the type and number of additional arguments.

  When type is `CS_CURSOR_DECLARE` the method must be called like this:

  `ct_dynamic(CS_CURSOR_DECLARE, dyn_id, cursor_id)`

  Then the Sybase-CT `ct_dynamic()` function is called like this:

        status = ct_dynamic(cmd, CS_CURSOR_DECLARE, dyn_id, CS_NULLTERM, cursor_id, CS_NULLTERM);

  When type is `CS_DEALLOC` the method must be called like this:

  `ct_dynamic(CS_DEALLOC, dyn_id)`

  Then the Sybase-CT `ct_dynamic()` function is called like this:

        status = ct_dynamic(cmd, CS_DEALLOC, dyn_id, CS_NULLTERM, NULL, CS_UNUSED);

  When type is `CS_DESCRIBE_INPUT` the method must be called like this:

  `ct_dynamic(CS_DESCRIBE_INPUT, dyn_id)`

  Then the Sybase-CT `ct_dynamic()` function is called like this:

        status = ct_dynamic(cmd, CS_DESCRIBE_INPUT, dyn_id, CS_NULLTERM, NULL, CS_UNUSED);

  When type is `CS_DESCRIBE_OUTPUT` the method must be called like this:

  `ct_dynamic(CS_DESCRIBE_OUTPUT, dyn_id)`

  Then the Sybase-CT `ct_dynamic()` function is called like this:

        status = ct_dynamic(cmd, CS_DESCRIBE_OUTPUT, dyn_id, CS_NULLTERM, NULL, CS_UNUSED);

  When type is `CS_EXECUTE` the method must be called like this:

  `ct_dynamic(CS_EXECUTE, dyn_id)`

  Then the Sybase-CT `ct_dynamic()` function is called like this:

        status = ct_dynamic(cmd, CS_EXECUTE, dyn_id, CS_NULLTERM, NULL, CS_UNUSED);

  When type is `CS_EXEC_IMMEDIATE` the method must be called like this:

  `ct_dynamic(CS_EXEC_IMMEDIATE, sql_text)`

  Then the Sybase-CT `ct_dynamic()` function is called like this:

        status = ct_dynamic(cmd, CS_EXEC_IMMEDIATE, NULL, CS_UNUSED, sql_text, CS_NULLTERM);

  When type is `CS_EXECUTE` the method must be called like this:

  `ct_dynamic(CS_PREPARE, dyn_id, sql_text)`

  Then the Sybase-CT `ct_dynamic()` function is called like this:

        status = ct_dynamic(cmd, CS_PREPARE, dyn_id, CS_NULLTERM, sql_text, CS_NULLTERM);

  For an explanation of the argument semantics please refer to the Sybase documentation.

  The `dynamic_cur.py`, and `dynamic_ins.py` example programs contain examples of this function.

`ct_fetch`()
  Calls the Sybase `ct_fetch()` function and returns a tuple containing the Sybase result code and the number of rows read (for array binding).

  The Sybase-CT `ct_fetch()` function is called like this:

        status = ct_fetch(cmd, CS_UNUSED, CS_UNUSED, CS_UNUSED, &rows_read);

`ct_get_data`(num, databuf)
  Calls the Sybase `ct_get_data()` function and returns a tuple containing the Sybase result code and the length of the data for item number num which was read into the `DataBuf` object in the databuf argument.

  The Sybase-CT `ct_get_data()` function is called like this:

        status = ct_get_data(cmd, num, databuf->buff, databuf->fmt.maxlength, databuf->copied);

  The following will retrieve the contents of a BLOB column:

        def get_blob_column(cmd, col):
            fmt = CS_DATAFMT()
            fmt.maxlength = 32768
            buf = DataBuf(fmt)
            parts = []
            while 1:
                status, count = cmd.ct_get_data(col, buf)
                if count:
                    parts.append(buf[0])
                if status != CS_SUCCEED:
                    break
            return string.join(parts, '')

`ct_param`(param)
  Calls the Sybase `ct_param()` function and returns the Sybase result code.

  The param argument is usually an instance of the `DataBuf` class. A `CS_DATAFMT` object can be used in a cursor declare context to define the format of the host variable.

  When param is a `DataBuf` the Sybase-CT `ct_param()` function is called like this:

        status = ct_param(cmd, &databuf->fmt, databuf->buff, databuf->copied[0], databuf->indicator[0]);

  When param is a `CS_DATAFMT` the Sybase-CT `ct_param()` function is called like this:

        status = ct_param(cmd, &datafmt, NULL, CS_UNUSED, CS_UNUSED);

  The semantics of the `CS_DATAFMT` attributes are quite complex. Please refer to the Sybase documentation.

`ct_res_info`(type)
  Calls the Sybase `ct_res_info()` function. The return result depends upon the value of the type argument.

  type | return values
  `CS_BROWSE_INFO` | `status, bool`
  `CS_CMD_NUMBER` | `status, int`
  `CS_MSGTYPE` | `status, int`
  `CS_NUM_COMPUTES` | `status, int`
  `CS_NUMDATA` | `status, int`
  `CS_NUMORDER_COLS` | `status, int`
  `CS_ORDERBY_COLS` | `status, list of int`
  `CS_ROW_COUNT` | `status, int`
  `CS_TRANS_STATE` | `status, int`

  Depending on type the Sybase-CT `ct_res_info()` function is called like this:

        status = ct_res_info(cmd, CS_BROWSE_INFO, &bool_val, CS_UNUSED, NULL);

        status = ct_res_info(cmd, CS_MSGTYPE, &ushort_val, CS_UNUSED, NULL);

        status = ct_res_info(cmd, CS_CMD_NUMBER, &int_val, CS_UNUSED, NULL);

        status = ct_res_info(cmd, CS_NUM_COMPUTES, &int_val, CS_UNUSED, NULL);

        status = ct_res_info(cmd, CS_NUMDATA, &int_val, CS_UNUSED, NULL);

        status = ct_res_info(cmd, CS_NUMORDERCOLS, &int_val, CS_UNUSED, NULL);

        status = ct_res_info(cmd, CS_ROW_COUNT, &int_val, CS_UNUSED, NULL);

        status = ct_res_info(cmd, CS_TRANS_STATE, &int_val, CS_UNUSED, NULL);

        status = ct_res_info(cmd, CS_NUMORDERCOLS, &int_val, CS_UNUSED, NULL);
        status = ct_res_info(cmd, CS_ORDERBY_COLS, col_nums, sizeof(*col_nums) * int_val, NULL);

`ct_results`()
  Calls the Sybase `ct_results()` function and returns a tuple containing the Sybase result code and the result type returned by the Sybase function.

  The Sybase-CT `ct_results()` function is called like this:

        status = ct_results(cmd, &result);

`ct_send`()
  Calls the Sybase `ct_send()` function and returns the Sybase result code.

  The Sybase-CT `ct_send()` function is called like this:

        status = ct_send(cmd);

`ct_send_data`(databuf)
  Calls the Sybase `ct_send_data()` function and returns the Sybase result code. The databuf argument must be a `DataBuf` object.

  The Sybase-CT `ct_send_data()` function is called like this:

        status = ct_send_data(cmd, databuf->buff, databuf->copied[0]);

`ct_setparam`(databuf)
  Calls the Sybase `ct_setparam()` function and returns the Sybase result code. The databuf argument must be a `DataBuf` object.

  The Sybase-CT `ct_setparam()` function is called like this:

        status = ct_setparam(cmd, &databuf->fmt, databuf->buff, databuf->copied, databuf->indicator);