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