File: cqgen.rb [ruby-odbc-0.99995 Documentation]

Last Modified
  2015-11-23 18:01:23 +0000
Requires
  - odbc

## Description

cqgen.rb - Poor man's C code generator to automatically

    make access wrappers for ODBC datasources.

This file is part of "ODBC-Ruby binding"

Copyright (c) 2006 Christian Werner <chw@ch-werner.de>

See the file "COPYING" for information on usage and redistribution of this file and for a DISCLAIMER OF ALL WARRANTIES.

Pre-requisites:

    * Ruby 1.6 or 1.8
    * Ruby/ODBC >= 0.996
    * Acesss to a ODBC datasource with properly
      loaded schema for the wrappers to generate

Functions in this module

    cqgen DSName, UID, PWD, CFName, SQL, [ParmTypes, ParmNames]

      DSName:    name of datasource to connect
      UID:       user name on datasource
      PWD:       password on datasource
      CFName:    name for C function
      SQL:       SQL text of one query yielding
                 one result set
      ParmTypes: (optional, array) types for
                 query parameters
      ParmNames: (optional, array) names for
                 query parameters

      use this function to make C code for
      SELECT/UPDATE/DELETE/INSERT SQL statements.
      The "ParmTypes" is useful since many ODBC drivers
      cannot return the proper types in SQLDescribeParam().

    cqgen_test
      append test functions and skeleton test main()
      to end of C file

    cqgen_output c_name, h_name
      write C source code, 'c_name' for functions,
      'h_name' for optional header file

Specification file sample

---BOF---

    require 'cqgen'
    # simple query
    cqgen 'bla', '', '', "GetResults", %q{
      select * from results
    }
    # query with parameters using last DSN
    cqgen nil, nil, nil, "GetResultsGt", %q{
      select * from results where funfactor > ?
    }
    # update with parameters using other DSN
    cqgen 'bla2', '', '', "IncrFunFactor", %q{
      update results set funfactor = ? where funfactor < ?
    }, [ ODBC::SQL_INTEGER, ODBC::SQL_INTEGER ],
       [ "newfunfactor", "maxfunfactor" ]
    cqgen_test
    cqgen_output 'bla_wrap.c'

---EOF---

Run this file with a command line like

    $ ruby sample-file
    $ cc -c bla_wrap.c
    or
    $ cc -o bla_wrap_test bla_wrap.c -DTEST_cqgen_all -lodbc

Depending on the SQL text, cqgen writes one or more C functions and zero or one structure typedefs. The structure typedefs are merged when possible, thus you should write the least specific queries on top of the specification file.

In the sample:

    * function GetResults_init to initiate the query
    * function GetResults to retrieve one result row
    * function GetResults_deinit to release resources
      associated with the query
    * struct RESULT_GetResults for representation of
      one result row

    * function GetResultsGt_init with one parameter par1
    * macro GetResultsGt aliased to GetResults
      (function reused from 1st query)
    * macro GetResultsGt_deinit aliased to GetResults_deinit
      (function reused from 1st query)
    * struct RESULT_GetResults for representation of
      one result row (struct name reused from 1st query)

    * function IncrFunFactor with two parameters named
      "newfunfactor" and "maxfunfactor" and an SQLINTEGER
      reference for the number of affected rows