Module Informix::Cursor
In: lib/informix.rb
ext/informixc.c

The Cursor module provides shortcuts for creating cursor objects that lets you retrieve, update and insert records.

Depending on the query and options given, one of three classes of cursors is returned: SequentialCursor, ScrollCursor or InsertCursor.

Methods

new   new0   open  

Public Class methods

new(db, query, options = nil) {|cur| ...}

Shortcut to create a cursor object based on query using options.

The cursor object is passed to the block if it‘s given, and automatically dropped when the block terminates, returning the value of the block.

options can be a Hash object with the following possible keys: 

  :scroll => true or false
  :hold   => true or false

[Source]

     # File lib/informix.rb, line 338
338:     def self.new(db, query, options = nil)
339:       if options
340:         Hash === options||raise(TypeError,"options must be supplied as a Hash")
341:       end
342:       cur = new0(db, query, options)
343:       return cur unless block_given?
344:       begin
345:         yield cur
346:       ensure
347:         cur.drop
348:       end
349:     end
new0(...)

The underlying class method that prepares a cursor and creates the respective cursor object.

[Source]

/*
 * The underlying class method that prepares a cursor and creates
 * the respective cursor object.
 */
static VALUE
rb_cursor_s_new0(int argc, VALUE *argv, VALUE self)
{
        VALUE db, query, options, ret;
        VALUE scroll, hold;
        struct sqlda *output;
        cursor_t c, *cur;
        database_t *dbt;
        long id;
/*
 *      EXEC SQL begin declare section;
 */
#line 3102 "informixc.ec"
#line 3103 "informixc.ec"
  char *c_query;
  char *cid, *sid, *did;
/*
 *      EXEC SQL end   declare section;
 */
#line 3105 "informixc.ec"


        memset(&c, 0, sizeof(c));
        rb_scan_args(argc, argv, "21", &db, &query, &options);
        Data_Get_Struct(db, database_t, dbt);
        did = dbt->database_id;
/*
 *      EXEC SQL set connection :did;
 */
#line 3111 "informixc.ec"
  {
#line 3111 "informixc.ec"
  sqli_connect_set(0, did, 0);
#line 3111 "informixc.ec"
  }

        if (SQLCODE < 0)
                raise_ifx_extended();

        c.db = db;
        c.database_id = did;
        scroll = hold = Qfalse;
        id = dbt->idcount++;
        snprintf(c.cursor_id, sizeof(c.cursor_id), "CUR%lX", id);
        snprintf(c.stmt_id, sizeof(c.stmt_id), "STMT%lX", id);
        cid = c.cursor_id; sid = c.stmt_id;
        c_query = StringValueCStr(query);

        if (!NIL_P(options)) {
                Check_Type(options, T_HASH);
                scroll = rb_hash_aref(options, sym_scroll);
                hold = rb_hash_aref(options, sym_hold);
        }

/*
 *      EXEC SQL prepare :sid from :c_query;
 */
#line 3131 "informixc.ec"
  {
#line 3131 "informixc.ec"
  sqli_prep(ESQLINTVERSION, sid, c_query,(ifx_literal_t *)0, (ifx_namelist_t *)0, -1, 0, 0 ); 
#line 3131 "informixc.ec"
  }
        if (SQLCODE < 0)
                raise_ifx_extended();

        if (RTEST(scroll) && RTEST(hold))
/*
 *              EXEC SQL declare :cid scroll cursor with hold for :sid;
 */
#line 3136 "informixc.ec"
  {
#line 3136 "informixc.ec"
  sqli_curs_decl_dynm(ESQLINTVERSION, sqli_curs_locate(ESQLINTVERSION, cid, 0), cid, sqli_curs_locate(ESQLINTVERSION, sid, 1), 4128, 0);
#line 3136 "informixc.ec"
  }
        else if (RTEST(hold))
/*
 *              EXEC SQL declare :cid cursor with hold for :sid;
 */
#line 3138 "informixc.ec"
  {
#line 3138 "informixc.ec"
  sqli_curs_decl_dynm(ESQLINTVERSION, sqli_curs_locate(ESQLINTVERSION, cid, 0), cid, sqli_curs_locate(ESQLINTVERSION, sid, 1), 4096, 0);
#line 3138 "informixc.ec"
  }
        else if (RTEST(scroll))
/*
 *              EXEC SQL declare :cid scroll cursor for :sid;
 */
#line 3140 "informixc.ec"
  {
#line 3140 "informixc.ec"
  sqli_curs_decl_dynm(ESQLINTVERSION, sqli_curs_locate(ESQLINTVERSION, cid, 0), cid, sqli_curs_locate(ESQLINTVERSION, sid, 1), 32, 0);
#line 3140 "informixc.ec"
  }
        else
/*
 *              EXEC SQL declare :cid cursor for :sid;
 */
#line 3142 "informixc.ec"
  {
#line 3142 "informixc.ec"
  sqli_curs_decl_dynm(ESQLINTVERSION, sqli_curs_locate(ESQLINTVERSION, cid, 0), cid, sqli_curs_locate(ESQLINTVERSION, sid, 1), 0, 0);
#line 3142 "informixc.ec"
  }

        if (SQLCODE < 0)
                raise_ifx_extended();

        alloc_input_slots(&c, c_query);
/*
 *      EXEC SQL describe :sid into output;
 */
#line 3148 "informixc.ec"
  {
#line 3148 "informixc.ec"
  sqli_describe_stmt(ESQLINTVERSION, sqli_curs_locate(ESQLINTVERSION, sid, 257), &output, 0);
#line 3148 "informixc.ec"
  }
        c.daOutput = output;

        c.is_select = (SQLCODE == 0 || SQLCODE == SQ_EXECPROC);

        if (c.is_select) {
                alloc_output_slots(&c);
                if (scroll)
                        ret = cursorbase_alloc(rb_cScrollCursor);
                else
                        ret = cursorbase_alloc(rb_cSequentialCursor);
        }
        else {
                xfree(c.daOutput);
                c.daOutput = NULL;
                ret = cursorbase_alloc(rb_cInsertCursor);
        }
        Data_Get_Struct(ret, cursor_t, cur);
        memcpy(cur, &c, sizeof(cursor_t));

        return ret;
}
open(db, query, options = nil) {|cur| ...}

Shortcut to create and open a cursor object based on query using options in a single step.

The cursor object is passed to the block if it‘s given, and automatically dropped when the block terminates, returning the value of the block.

options can be a Hash object with the following possible keys: 

  :scroll => true or false
  :hold   => true or false
  :params => input parameters as an Array or nil

[Source]

     # File lib/informix.rb, line 363
363:     def self.open(db, query, options = nil)
364:       params = nil
365:       if options
366:         Hash === options||raise(TypeError,"options must be supplied as a Hash")
367:         (params = options[:params]) && (Array === params ||
368:                    raise(TypeError,"params must be supplied as an Array"))
369:       end
370:       cur = new(db, query, options)
371:       params ? cur.open(*params) : cur.open
372:       return cur unless block_given?
373:       begin
374:         yield cur
375:       ensure
376:         cur.drop
377:       end
378:     end

[Validate]