SybCommand class

index

# SybCommand

SybCommand implements CS_COMMAND structure of SyBase Client Library.

### Class Method

new ( con, cmd, type=CS_LANG_CMD )
  Initiate a command.
  (This method corresponds to ct_command of Sybase Client Library.)

  Parameters:

  - con
    SybConnection object.

  - cmd
    Language command

  - type
    The type of command to initiate
    The value of type is a constant that is defined in SybConstant module.
    However, I support only CS_LANG_CMD and CS_SEND_DATA_CMD yet.

  If error has occurred, then it raise a RuntimeError exception.

cursor_new ( con, csrname, langcmd, opt=CS_UNUSED )
  Initiates a command, and declares a cursor.
  This method corresponds to ct_cmd_alloc() + ct_cursor( CS_CURSOR_DECLARE) of Sybase Client Library.

  Parameters:

  - con
    SybConnection object.

  - csrname
    a cursor name

  - langcmd
    The SQL text that represents the body of the cursor.
    e.g. "select xxx,yyy from table for update of yyy"

  - opt
    The option to declare the cursor.
    However, every options are not supported. Only CS_FOR_UPDATE, CS_READ_ONLY and CS_UNUSED are supported.

  If error has occurred, then it raise a RuntimeError exception.

  The cursor is available until a delete method is called or Ruby's garbage collector finds this.

### Methods

send
  Send a command to the server
  (This method corresponds to ct_send of Sybase Client Library.)

  Returns TRUE if it was successful, or FALSE if not

delete
  Deallocate a command.
  If the command has a Client-Library cursor that was assigned with cursor_new, then the cursor will be deallocated too.

  Returns TRUE if it was deleted successfully.

results
  Set up results data to be processed, and returns a results type as follows.

  CS_CMD_SUCCEED | The success of a command that returns no data
  CS_CMD_DONE | The results of a command have been completely processed.
  CS_CMD_FAIL | The server encountered an error while executing a command
  CS_ROW_RESULT | Regular row results
  CS_PARAM_RESULT | Parameter results
  CS_STATUS_RESULT | Stored procedure return status results.
  CS_COMPUTE_RESULT | Compute row results

bind_columns ( maxcolumns=nil )
  This method calls ct_bind of SyBase Client Library, and binds server results to Ruby's variables.
  It returns an array of columns name.

  Parameters:

  - maxcolumns
    The maximum column number to bind
    nil means binding all columns.
    Zero means binding no columns.

fetch ( strip=true )
  Retrieves one result data.
  This method corresponds to ct_fetch of Sybase Client Library.

  Parameters

  Strips the trailing white spaces if strip is TRUE.

  Returns:
  Returns the status and an array of result row.
  (status, row ) = cmdobj.fetch()
  The status has the following values.
  - false -- Initialization error
  - SybConstant::CS_END_DATA
  - SybConstant::CS_SUCCEED
  - SybConstant::CS_ROW_FAIL
  - SybConstant::CS_FAIL
  - SybConstant::CS_CANCELED

fetchloop ( maxrows=0, strip=true, bcol=nil, rproc=nil)
  Retrieves all result data.

  Returns an array of two elements, the first element is array of column names , the second element is row datas as an array of array.
  --> [ [column-name ...] [ [row-data-1] [row-data-2] .... ] ]

  If error has occurred, then it returns FALSE.

  Parameters

  - maxrows
    The maximum number of rows to fetch.
    maxrows=0 means unlimited.

  - strip
    Strips the trailing white spaces if strip is TRUE.

  - bcol
    The maximum column number to bind
    nil means binding all columns.
    Zero means binding no columns.

  - rproc
    Whenever one row is retrieved, this block is called

    rproc { |cmd,status, column,row| .... }
    The blocks parameters

      cmd | SybCommand object
      status | SybConstant::CS_SUCCEED or SybConstant::CS_ROW_FAIL
      column | The array of column names
      row | The array of a row data

    The block's return value

      true: | The row's value is added to the fetchloop's return value
      nil: | The row's value is not added to the fetchloop's return value (When large number of rows are retrieved, this is effective in order to save memory)
      false: | Stop to iterates

cancel ( type=SybConstant::CS_CANCEL_CURRENT )
  Cancel a command.
  This method corresponds to ct_cancel of Sybase Client Library.

  Returns TRUE if it was successful

  Parameters:

  - type
    SybConstant::CS_CANCEL_CURRENT, SybConstant::CS_CANCEL_ATTN, or SybConstant::CS_CANCEL_ALL

setprop ( proptype, val )
  Sets Client-Library properties at the command structure levels.
  This method corresponds to ct_cmd_props(CS_SET) of Sybase Client Library.

  The proptype parameter must be a constant that is defined in SybConstant module.

  Returns TRUE if it was successful, or FALSE if not

getprop ( proptype )
  Retrieves Client-Library properties at the command structure levels.
  This method corresponds to ct_cmd_props(CS_GET) of Sybase Client Library.

  The value of proptype must be a constant that is defined in SybConstant module.

res_info ( type )
  Retrieves current result set or command information.
  This method corresponds to ct_res_info of Sybase Client Library.

  The value of type must be a constant that is defined in SybConstant module.

get_iodesc ( item )
  Retrieves a data I/O descriptor.

  Parameters:

  - item
    The number of the IMAGE/TEXT column (start at 1).

  Returns a SybIODesc object if it was successful.
  If error has occurred, then it returns SybConstant::CS_FAIL.

  (Please see the Sybase OpenClient manual pages on ct_data_info for further details.)

set_iodesc ( iodesc )
  Define a data I/O descriptor.

  Parameters:

  - iodesc
    SybIODesc object to define

  Returns a SybConstant::CS_SUCCEED if it was successful.
  If error has occurred, then it returns SybConstant::CS_FAIL.

  (Please see the Sybase OpenClient manual pages on ct_data_info for further details.)

get_data ( item, fetchsize )
  Reads a chunk of data from the server

  Parameters:

  - item
    The column number of the Image/Text column (start at 1).

  - fetchsize
    The number of bytes to read. If fetchsize is 0, it updates the I/O descriptor for the item without retrieving any data.

  Returns
  This method returns a status and a String object as an array.
  e.g.
  (status, buffer ) = cmdobj.get_data( 3, 1024)

  status has the following values

  - SybConstant::CS_END_ITEM
  - SybConstant::CS_END_DATA
  - SybConstant::CS_SUCCEED
  - SybConstant::CS_FAIL
  If there is no data to read, buffer becomes nil

  (Please see the Sybase OpenClient manual pages on ct_get_data for further details.)

send_data ( data )
  Sends a chunk of TEXT/IMAGE data to the server

  Parameters:

  - data
    A String object to send

  Returns
  - SybConstant::CS_SUCCEED
    It was successful
  - SybConstant::CS_FAIL
    It failed
  - SybConstant::CS_CANCELED
    The operation was canceled

  (Please see the Sybase OpenClient manual pages on ct_send_data for further details.)

cursor_state ()
  Gets current cursor's status
  (This method corresponds to ct_cmd_props( cmd, CS_GET, CS_CUR_STATUS ) of Sybase Client Library.)

  Returns :
  If no cursor exists, then it returns SybConstant::CS_CURSTAT_NONE.
  If return value is not CS_CURSTAT_NONE, the application determines the cursor status by applying the bitmask values listed in the following.

  - SybConstant::CS_CURSTAT_CLOSED
  - SybConstant:: CS_CURSTAT_DECLARED
  - SybConstant::CS_CURSTAT_ROWCOUNT
  - SybConstant::CS_CURSTAT_OPEN
  - SybConstant::CS_CURSTAT_UPDATABLE
  - SybConstant:: CS_CURSTAT_RDONLY

cursor_rows ( rows )
  This method corresponds to ct_cursor ( CS_CURSOR_ROWS ) of Sybase Client Library.

  Parameters:

  - rows
    The number of rows to be returned with a single fetch request.

cursor_open ()
  This method corresponds to ct_cursor( CS_CURSOR_OPEN ) of Sybase Client Library.

cursor_option( opt )
  This method corresponds to ct_cursor( CS_CURSOR_OPTION ) of Sybase Client Library.

  Parameters

  - opt
    SybConstant::CS_FOR_UPDATA or
    SybConstant::CS_READ_ONLY or
    nil( SybConstant::CS_UNUSED )

cursor_update ( table, sql )
  This method corresponds to ct_cursor( CS_CURSOR_UPDATE ) of Sybase Client Library.

  Parameters

  - table
    The table name to update.
  - sql
    The sql update statement.

cursor_delete( table )
  This method corresponds to ct_cursor( CS_CURSOR_DELETE) of Sybase Client Library.

  Parameters

  - table
    The name of the table to delete from.

cursor_close()
  This method corresponds to ct_cursor( CS_CURSOR_CLOSE) of Sybase Client Library.