SybCommand class

目次に戻る

# SybCommand

SyBase クライアントライブラリーの CS_COMMAND構造体のRubyへの 実装です。

### クラスメソッド

new ( con, cmd, type=CS_LANG_CMD )
  T-SQL、ストアドプロシジャなどのコマンドを開始します。
  (SyBase Client-Library の ct_cmd_alloc + ct_command に相当)

  con には、SybConnectionオブ ジェクトを指定してください。

  cmd には、"select xxx,yyy from table" などのT-SQLコマンドストリ ングを指定します。

  type には、開始するコマンドのタイプを、SybConstant モジュー ルの定数で指定します。
  現在、サポートしているのは、CS_LANG_CMD と CS_SEND_DATA_CMDだけです。

  エラーが生じると、RuntimeError 例外を発生します。

cursor_new ( con, csrname, langcmd, opt=CS_UNUSED )
  コマンドを開始し、同時にクライアントライブラリー カーソルの割り当てを行ないます。
  (SyBase Client-Library の ct_cmd_alloc + ct_cursor(CS_CURSOR_DECLARE) に相当)

  con には、SybConnectionオブ ジェクトを指定してください。

  csrname には、割り当てるカーソルの名前を指定します

  langcmd には、"select xxx,yyy from table for update of yyy" などのカーソルボディを表す SQL コマンドストリングを指定します。

  opt には、カーソル割り当てのオプションを、SybConstant モジュー ルの定数で指定します。
  現在、サポートしているのは、CS_FOR_UPDATE と CS_READ_ONLY及びデフォルトのCS_UNUSEDだけです。

  エラーが生じると、RuntimeError 例外を発生します。

  割り当てられたカーソルは、deleteメソッドを発行 するか、 SybCommand オブジェクトがガベージコレクションされる時に廃棄 されます。

### メソッド

send
  コマンドを SyBase SQLサーバに送信します（SyBase CTLib の ct_sendに相 当）
  成功すると、 true を返します。

delete
  コマンドを廃棄します。
  cursor_new で割り当てられたカーソルも廃棄されます。

  成功すると、 true を返します。

results
  結果セットを検索し、以下の結果タイプが返却されます。

  - nil -- もう処理すべき結果セットがない
  - false -- エラー
  - SybConstant::CS_CMD_SUCCEED (ローを返さないコマンドの正常終了通知)
  - SybConstant::CS_CMD_DONE (コマンドの正常処理を通知)
  - SybConstant::CS_CMD_FAIL(サーバエラーを通知)
  - SybConstant::CS_ROW_RESULT(通常ロー結果)
  - SybConstant::CS_PARAM_RESULT(リターンパラメータ結果)
  - SybConstant::CS_STATUS_RESULT(ストアドプロシジャー リターンステータス)
  - SybConstant::CS_COMPUTE_RESULT(compute ロー結果)

bind_columns (maxcolumns=nil)
  SyBase CTLib の ct_bind を発行し、SybCommand オブジェクトの内部変数 にバインドし、カラム名の配列を返します。
  Ruby変数へは、bind_columns 実行の後、fetch メソッドを実行 してからバインドされます。

  maxcolumns には通常 nil を指定しますが、データ I/O 記述子構造体 (SybIODesc)を検索する時は、ここに、 バインドする最大カラム番号を指定します。
  0 はバインドしません。

  なを、このメソッドによって返されるカラム名の配列には、バインドしなかっ たカラム名も含まれます。

fetch ( strip=true)
  Sybase CTLib の ct_fetch に相当します。

  結果ローを、一つだけフェッチし、フェッチステータスとロー配列を返します。
  (status, row ) = cmdobj.fetch()
  status は、以下の値を持ちます。

  - false -- 初期化エラー
  - SybConstant::CS_END_DATA 返すべきローがない
  - SybConstant::CS_SUCCEED 正常にローをフェッチした
  - SybConstant::CS_ROW_FAIL
  - SybConstant::CS_FAIL
  - SybConstant::CS_CANCELED

    stripがtrue なら フェッチした項目の後続ブランクを切り詰めます。

fetchloop (maxrows=0, strip=true, bcol=nil, rproc=nil)
  結果ローを、全てフェッチし、正常終了の場合は 長さ２の配列を返し、エラー時 は falseを返します。
  返却値配列の最初の要素は、カラム情報の配列で、２番目の要素は、データ ローの配列の配列です。

  maxrows
    フェッチする最大のロー数で、０は制限なしです。

  strip
    true なら フェッチした項目の後続ブランクを切り詰めます。
  bcol
    通常は、nil を指定しますが、データ I/O 記述子構造体 (SybIODesc)を検索する時は、ここに、 バインドする最大カラム番号を指定します。
    0 はバインドしません。
  rproc
    1 ローフェッチする度に呼び出される、ユーザ定義の手続きオブジェクトです。

    rproc { |cmd,status,column,row| .... }

      cmd | SybCommand オブジェクト
      status | SybConstant::CS_SUCCEED または SybConstant::CS_ROW_FAIL
      column | カラム名配列
      row | ローデータの配列

    リターン値

      true | rowをfetchloopが返すロー配列に加える
      nil | rowをfetchloopが返すロー配列に加えない。 (巨大ローを検索する時に、メモリを節約するのに使える)
      false | fetch をキャンセルする。

fetch_rowfail( on )
  fetchloop メソッドにおいて、CS_ROW_FAIL のローを検索結果として返すか どうかを設定します。

  fetch_rowfail(true) なら、CS_ROW_FAIL のロー結果は、fetchloopの結果に含まれま すが、fetch_rowfail(false)なら、CS_ROW_FAIL のロー結果はnilと して、fetchloopの結果に含まれます。

  fetchloop メソッドのデフォルトの振舞いは、fetch_rowfail(false) です。

cancel (type=SybConstant::CS_CANCEL_CURRENT )
  コマンドとコマンド結果を無効にします(SyBase CTLib の ct_cancelに相当)

  type には、SybConstant::CS_CANCEL_CURRENT、SybConstant::CS_CANCEL_ATTN、 SybConstant::CS_CANCEL_ALLのいずれかを設定できます。

  成功すると、 true を返します。

setprop(proptype, val)
  コマンドレベルでの、クライアントライブラリー特性を設定し、成功すると true、失敗すると falseを返します。 (SyBase CTlib の ct_cmd_props(CS_SET) に相当)

  proptype には、SybConstantで定義され ている定数を指定してください。

getprop(proptype)
  コマンドレベルでの、クライアントライブラリー特性を検索します。 (SyBase CTlib の ct_cmd_props(CS_GET) に相当)

  proptype には、SybConstantで定義され ている定数を指定してください。

res_info(type)
  結果セット情報を検索します。 (SyBase CTlib の ct_res_info に相当)

  type には、SybConstantで定義され ている定数を指定してください。

get_iodesc(item)
  SyBase CTlib の ct_data_info() API によって、SybIODesc （データ I/O 記述子構造体）を検索します。

  item には、対象となるデータ項目のカラム番号（start from 1）を指定 します。

  成功すれば、SybIODesc オブジェクトを返し、失敗すれば、 SybConstant::CS_FAILなどを返します

set_iodesc(iodesc)
  SyBase CTlib の ct_data_info() API によって、SybIODesc （データ I/O 記述子構造体）を設定します。

  iodesc には、設定すべきSybIODescオブジェクトを指定します。

  成功すれば、SybConstant::CS_SUCCEEDを返し、失敗すれば、 SybConstant::CS_FAILなどを返します

get_data(item, fetchsize)
  SyBase CTlib の ct_get_data() API によって、データの固まりをサーバから読み込みます。
  item には、対象となるデータ項目のカラム番号（start=1）を指定 し、fetchsizeには、読み出すバイトサイズを指定します。
  get_iodescメソッドによる SybIODesc オブジェクトを検索するためだけに 使用する場合、fetchsize = 0 の指定も可能です。

  返り値は、ステータス情報と読み出したデータ（String オブジェクト）の 配列になります。
  例
  (status, buffer ) = cmdobj.get_data( 3, 1024)

  statusは以下の値を持ちます。
  SybConstant::CS_END_ITEM
  SybConstant::CS_END_DATA
  SybConstant::CS_SUCCEED
  SybConstant::CS_FAIL
  何もデータを読み出さなかった場合は、buffer = nil になります

send_data(data)
  SyBase CTlib の ct_get_data() API によって、データの固まりをサーバに送り込みます。

  data には、送るデータを String オブジェクトで指定します。

  返り値は、
  SybConstant::CS_SUCCEED ----- 成功
  SybConstant::CS_FAIL または SybConstant::CS_CANCELED ------ 失敗
  です。

  注意：
  同じ接続で継続中の SybCommand オブジェクトがある場合エラーします。

cursor_state()
  現在のカーソルステータスを取得します。

  Client-Library の ct_cmd_props( cmd, CS_GET, CS_CUR_STATUS )に相当 します。

  カーソルがない場合は、 SybConstant::CS_CURSTAT_NONE を返し、カーソル がある場合は、

  - 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)
  Client-Library の ct_cursor( CS_CURSOR_ROWS )に相当 します。
  rows には、１回のフェッチ要求で返されるロー数を指定します。

cursor_open()
  Client-Library の ct_cursor( CS_CURSOR_OPEN )に相当 します。

cursor_option(opt)
  Client-Library の ct_cursor( CS_CURSOR_OPTION )に相当 します。
  opt は、SybConstant::CS_FOR_UPDATA, SybConstant::CS_READ_ONLY, nil(SybConstant::CS_UNUSED) を指定します。

cursor_update(table, sql)
  Client-Library の ct_cursor( CS_CURSOR_UPDATE )に相当 します。
  table には更新するテーブル名、sql には update SQLコマンドを指定しま す

cursor_delete(table)
  Client-Library の ct_cursor( CS_CURSOR_DELETE )に相当 します。
  table には削除するローのテーブル名を指定します。

cursor_close()
  Client-Library の ct_cursor( CS_CURSOR_CLOSE )に相当 します。