2.1.5 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 stderr. The default value is inherited from the parent connection when the command is created.

ct_bind (num, datafmt)
Calls the Sybase ct_bind() function passing the num and datafmt arguments. It returns a tuple containing the Sybase result code and a DataBuf object which is used to retrieve data from the column identified by num.

See the description of the ct_describe() method for an example.

ct_cancel (type)
Calls the Sybase ct_cancel() function passing a NULL CS_CONNECTION, the wrapped CS_COMMAND pointer and the integer type argument and returns the Sybase result code.

ct_cmd_drop ()
Calls the Sybase ct_cmd_drop() function and 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_command() function and returns the result code.

The type argument controls determines the type and number of additional arguments.

ct_command(CS_LANG_CMD, sql_text [, options])

ct_command(CS_RPC_CMD, proc_name [, options])

ct_command(CS_MSG_CMD, msg_num)

ct_command(CS_PACKAGE_CMD, pkg_name)

ct_command(CS_SEND_DATA_CMD)

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 controls determines the type and number of additional arguments.

ct_cursor(CS_CURSOR_DECLARE, cursor_id, sql_text [, options])

ct_cursor(CS_CURSOR_UPDATE, table_name, sql_text [, options])

ct_cursor(CS_CURSOR_OPTION [, options])

ct_cursor(CS_CURSOR_OPEN [, options])

ct_cursor(CS_CURSOR_CLOSE [, options])

ct_cursor(CS_CURSOR_ROWS, num_rows)

ct_cursor(CS_CURSOR_DELETE, table_name)

ct_cursor(CS_CURSOR_DEALLOC)

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, num [, iodesc])
Sets and retrieves column IO descriptors.

When action is CS_SET the iodesc argument must be supplied and the method returns the Sybase result code.

When action is CS_GET the method returns a tuple containing the Sybase result code and an CS_IODESC object.

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

    status, iodesc = cmd.ct_data_info(CS_GET, 2)
    if status != CS_SUCCEED:
        raise CTError(cmd.conn, 'ct_data_info failed')
    if cmd.ct_command(CS_SEND_DATA_CMD) != CS_SUCCEED:
        raise CTError(cmd.conn, 'ct_command failed')
    iodesc.total_txtlen = len(newdata)
    iodesc.log_on_update = CS_TRUE
    if cmd.ct_data_info(CS_SET, iodesc) != CS_SUCCEED:
        raise CTError(cmd.conn, 'ct_data_info failed')

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

ct_describe (num)
Calls the Sybase ct_describe() function passing the num argument and 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.

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

ct_dynamic (type [, ...])
Calls the Sybase ct_dynamic() function and returns the result code.

The type argument controls determines the type and number of additional arguments.

ct_dynamic(CS_CURSOR_DECLARE, dynamic_id, cursor_id)

ct_dynamic(CS_DEALLOC, dynamic_id)

ct_dynamic(CS_DESCRIBE_INPUT, dynamic_id)

ct_dynamic(CS_DESCRIBE_OUTPUT, dynamic_id)

ct_dynamic(CS_EXECUTE, dynamic_id)

ct_dynamic(CS_EXEC_IMMEDIATE, sql_text)

ct_dynamic(CS_PREPARE, dynamic_id, sql_text)

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.

Modified from the dynamic_ins.py program:

def do_dynamic_insert(cmd, insert_statement, repeat_count):
    if cmd.ct_dynamic(CS_PREPARE, 'd_insert', insert_statement) != CS_SUCCEED:
        raise CTError(cmd.conn, 'ct_dynamic CS_PREPARE failed')
    if cmd.ct_send() != CS_SUCCEED:
        raise CTError(cmd.conn, 'ct_send failed')
    handle_returns(cmd)
    for i in range(repeat_count):
        col = raw_input('Enter value for col ( int ) ')
        if cmd.ct_dynamic(CS_EXECUTE, 'd_insert') != CS_SUCCEED:
            raise CTError(cmd.conn, 'ct_dynamic CS_EXECUTE failed')
        buf = DataBuf(int(col))
        buf.status = CS_INPUTVALUE
        if cmd.ct_param(buf) != CS_SUCCEED:
            raise CTError(cmd.conn, 'ct_param failed')
        if cmd.ct_send() != CS_SUCCEED:
            raise CTError(cmd.conn, 'ct_send failed')
        handle_returns(cmd)
    if cmd.ct_dynamic(CS_DEALLOC, 'd_insert') != CS_SUCCEED:
        raise CTError(cmd.conn, 'ct_dynamic CS_DEALLOC failed')
    if cmd.ct_send() != CS_SUCCEED:
        raise CTError(cmd.conn, 'ct_send failed')
    handle_returns(cmd)

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

From the Sybase.py module:

    def fetch_rows(self, bufs):
        '''Fetch rows into bufs.

        When bound to buffers for a single row, return a row tuple.
        When bound to multiple row buffers, return a list of row
        tuples.
        '''
        cmd = self._cmd
        status, rows_read = cmd.ct_fetch()
        if status == CS_SUCCEED:
            pass
        elif status == CS_END_DATA:
            return None
        elif status in (CS_ROW_FAIL, CS_FAIL, CS_CANCELED,
                        CS_PENDING, CS_BUSY):
            err = _build_ct_except(cmd.conn, 'ct_fetch')
            self.abort_quietly()
            raise InternalError(err)
        if bufs[0].count > 1:
            rows = []
            for i in xrange(rows_read):
                rows.append(_extract_row(bufs, i))
            return rows
        else:
            return _extract_row(bufs, 0)

ct_get_data (num, buf)
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 buf argument.

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

The buf 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.

The sematics 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

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.

if cmd.ct_command(CS_LANG_CMD, 'select * from pubs..titles') != CS_SUCCEED:
    raise CTError(cmd.conn, 'ct_command')
if cmd.ct_send() != CS_SUCCEED:
    raise CTError(cmd.conn, 'ct_send')
while 1:
    status, result = cmd.ct_results()
    if status == CS_END_RESULTS:
        break
    elif status != CS_SUCCEED:
        raise CTError(cmd.conn, 'ct_results')
    if result in (CS_COMPUTE_RESULT, CS_CURSOR_RESULT,
                  CS_PARAM_RESULT, CS_ROW_RESULT, CS_STATUS_RESULT):
        bufs = row_bind(cmd, 16)
        fetch_logical_result(bufs)
    elif result not in (CS_CMD_DONE, CS_CMD_SUCCEED):
        raise CTError(cmd.conn, 'ct_results')

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

status, cmd = conn.ct_cmd_alloc()
if status != CS_SUCCEED:
    raise CTError(cmd.conn, 'ct_cmd_alloc')
if cmd.ct_command(CS_LANG_CMD, 'select * from pubs..titles') != CS_SUCCEED:
    raise CTError(cmd.conn, 'ct_command')
if cmd.ct_send() != CS_SUCCEED:
    raise CTError(cmd.conn, 'ct_send')

ct_send_data (buf)
Calls the Sybase ct_send_data() function and returns the Sybase result code.

ct_setparam (buf)