home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / rexxgdb2.zip / ReadMe.1st < prev    next >
Text File  |  1997-08-10  |  11KB  |  248 lines
  1. ************************************************************************
  2.                                 REXXGDB2
  3.  
  4.             Release Highlights, Tips, and Last-minute notes
  5. ************************************************************************
  6.  
  7.  
  8. Version 1.30                                   Sunday, August 10th, 1997
  9. ========================================================================
  10. 1. Dynamically generate HTML-encoded files for Lists, Listboxes, Images,
  11.    Textarea, etc. from your SQL Select statements
  12.  
  13. 2. Include descriptions and examples how to utilize RexxGDB2 from within
  14.    Goserve (Freeware Web Server for OS/2 Warp by Mike Cowlishaw,
  15.    IBM Fellow, IBM UK Laboratories)
  16.  
  17. 3. Select Large Objects Into Files
  18.  
  19. 4. Use resources more efficiently
  20.  
  21. 5. Safer and more robust support of multi-threaded Rexx programs
  22.    running in multiple processes within the same (client) PC
  23.  
  24.          Please read the updated REXXGDB2.INF for more details.
  25.  
  26.  
  27. Examples of what this RexxGDB2 version is able to do:
  28. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  29. 1. The following program is complete and executes only about one second.
  30.    It builds a complete table-encoded HTML file for your SQL query and
  31.    launches your browser to view it...
  32.  
  33.    /* rexx */
  34.    call rxfuncadd       'g2loadfuncs', 'REXXGDB2', 'g2loadfuncs'
  35.    call g2loadfuncs
  36.    call g2connectshare  'SAMPLE'
  37.    call g2h             'www.htm', 1, '<FORM METHOD="POST">'
  38.    call g2hselect2table 'www.htm', 1, 'Select * from staff', 999
  39.    call g2h             'www.htm', 1, '</FORM>'
  40.    'netscape file:///www.htm'
  41.    return
  42.  
  43.  
  44. 2. We were able to run simultaneously and safely many multi-threaded
  45.    Rexx programs, each calling RexxGDB2 G2Select functions, in multiple
  46.    processes for numerous hours, including those running within PMRexx.
  47. ------------------------------------------------------------------------
  48.  
  49.  
  50.  
  51. Version 1.20                                 Sunday, November 17th, 1996
  52. ========================================================================
  53. 1. Intel 486-optimized
  54.    The new version is now optimized for Intel 486-class processors.
  55.    The functions still run on Intel 386, Pentium or newer processors.
  56.  
  57. 2. G2GetToken is introduced to obtain a surrogate key (unique number)
  58.    from a table dedicated for keys.
  59.  
  60.          Please read the updated REXXGDB2.INF for more details.
  61. ------------------------------------------------------------------------
  62.  
  63.  
  64.  
  65. Version 1.10                                   Sunday, August 11th, 1996
  66. ========================================================================
  67. 1. Multi-threaded support
  68.    The new version has been improved to work properly in a multi-
  69.    threaded REXX environment.
  70.  
  71. 2. G2Immediate, G2SelectCols, G2SelectData, G2SelectForm, and
  72.    G2SelectOne can now receive a long SQL statement from REXX caller
  73.    programs.  Please read the updated REXXGDB2.INF for more details.
  74.  
  75. 3. G2SelectData, G2SelectForm, and G2SelectOne now correctly handle long
  76.    character columns (VARCHAR, LONG VARCHAR, etc.).
  77.    Please read the updated REXXGDB2.INF for more details.
  78.  
  79. 4. G2SelectOne handles long characters as follows:
  80.    It now also populates a 'special REXX variable', like G2SQLCODE,
  81.    called G2LONGRESULT.
  82.  
  83.    G2LONGRESULT contains REXX NULL character ('') if the value returned
  84.    is not longer than 254 characters.
  85.  
  86.    Otherwise, i.e. if the (VARCHAR, LONG VARCHAR, etc.) value is longer
  87.    than 254 characters, G2LONGRESULT contains the entire string (not
  88.    truncated).  The function (G2SelectOne) in this case still returns
  89.    the first (left most) 254 characters of the string.
  90.  
  91.    Please read the updated REXXGDB2.INF for more details.
  92.  
  93. 5. As with the previous version, this one was also created using USERID
  94.    as the owner of the (REXXGDB2) package.
  95.  
  96.    If necessary, you could execute something similar to the following
  97.    SQL statement using DB2 CLP from an OS/2 command prompt to grant
  98.    users access to the REXXGDB2 functions:
  99.  
  100.    ===> DB2 GRANT EXECUTE ON PACKAGE USERID.REXXGDB2 TO PUBLIC
  101.  
  102. 6. CUDFGDB2.ZIP containing some additional DB2/2 User-defined Functions
  103.    which can be used as scalar functions is now included as part of this
  104.    package.
  105. ------------------------------------------------------------------------
  106.  
  107.  
  108.  
  109. Version 1.00                                 Sunday, December 10th, 1995
  110. ========================================================================
  111.  
  112. 1. Before running test programs, make sure that DB2/2 has been started
  113.    and/or you're connected to an active DB2/2 server.
  114.  
  115. 2. All test programs are using SAMPLE database
  116.    If you're using DB2/2 2.x single user version, you can create
  117.    SAMPLE database by issuing DB2SAMPL on an OS/2 command prompt.
  118.    Otherwise, contact your DB2/2 DBA or modify the test programs
  119.    to use your test database.  In the latter case, make sure that
  120.    you also change the test SQL statements so that ORG and STAFF
  121.    tables are replaced accordingly.
  122.  
  123. 3. Use caution in using G2SetCurPkgSet function.  The last set package-
  124.    set will still be in affect within the same process, even if you are
  125.    running another program.  This could cause problems if the following
  126.    programs do not have the same collection identifier.
  127.  
  128.    As an example, if you start an OS/2 command prompt and run G2FUNCS,
  129.    and upon its completion, within the same OS/2 command prompt, start
  130.    RUN-EXEC or RUN-G2, you would have a problem since DB2AR used to
  131.    load SQLEXEC and SQLDBS does not have the same collection id. last
  132.    set in G2FUNCS, which is G2GOISO.  The first dynamic SQL in the
  133.    (later) program will return SQLCODE -805.
  134.  
  135.    Currently, no solution is at hand to solve this problem other than
  136.    by closing the current session (using EXIT on the OS/2 command
  137.    prompt), and/or start another OS/2 command prompt to run subsequent
  138.    programs.
  139.  
  140.    Again, this problem only occurs when you change the current
  141.    packageset collection identifier (using G2SetCurPkgSet).
  142.    G2Funcs shows how to use it and why it could be beneficial to
  143.    utilize this feature in some cases.
  144.  
  145.    A way to avoid the above problem is to first run programs which do
  146.    not change the default packageset before those which do.
  147.    In other words, in the above example, it would be okay to first run
  148.    RUN-EXEC and/or RUN-G2 before G2Funcs.  Subsequently, you could also
  149.    run G2Funcs multiple times within the same OS/2 command prompt
  150.    since G2Funcs sets the current packageset to the one that it created.
  151.  
  152. 4. To get fair results, make sure you run the benchmark test programs
  153.    several times and record the best performance of each of the
  154.    programs.  The first run of each of the programs may be much slower
  155.    due to program tokenization, DB2/2 connection, and functions loads.
  156.  
  157. 5. Program tokenizations
  158.    To be able to produce good benchmark results, when comparing IBM
  159.    and Quercus REXX engines for OS/2, you must first understand when
  160.    the engines tokenize the REXX source codes and what they do with
  161.    the tokenized codes.
  162.  
  163.    Using IBM OS/2 Procedures Language 2/REXX
  164.    - Implicit tokenization
  165.      During first program execution, or when the interpreter detects
  166.      that the source codes do not (longer) match with the (previously)
  167.      tokenized codes in the corresponding Extended Attribute file.
  168.    - Explicit tokenization
  169.      By running the program on an OS/2 command prompt and passing
  170.      parameter //t (or //T) such as: myprog //t
  171.      In this case, the program is actually not executed nor is the
  172.      parameter //t (or //T) passed to the REXX program.
  173.    - Notes
  174.      As discussed above, IBM places REXX tokenized codes in the
  175.      Extended Attribute file which can only hold up to 64 kbytes of
  176.      information.  If the tokenized (textual) REXX program codes file
  177.      is larger than 64 kbytes, the tokenized codes will not be saved
  178.      which means that the tokenization will always be implicitly done
  179.      on any execution.
  180.  
  181.    Using Quercus Personal/REXX for OS/2 version 3.0
  182.    - Implicit tokenization
  183.      During every program execution, when the interpreter detects that
  184.      the tokenized codes are not in the (program) file, following the
  185.      end-of-file marker.
  186.    - Explicit tokenization
  187.      By running the program on an OS/2 command prompt and passing
  188.      parameter //T such as: myprog //T, or by running PREXX30 using
  189.      parameter /O such as: PREXX30 /O myprog.
  190.      In this case, the program is actually not executed nor is the
  191.      parameter //T passed to the REXX program.
  192.    - Notes
  193.      As discussed above, Quercus places REXX tokenized codes in the
  194.      same (textual) REXX program file, following the first end-of-file
  195.      marker.
  196.  
  197.      The tokenized codes are normally not visible to the programmers
  198.      as most text editors only read a file up to the end-of-file marker.
  199.      These editors will consequently also 'remove' those tokenized
  200.      codes when the REXX program is modified and saved.
  201.  
  202.      This mechanism solves at least the following problems:
  203.      * Source codes are not necessary to run with Personal/REXX
  204.      * Size of the tokenized codes is only limited by disk space
  205.  
  206.      On the negative side:
  207.      * Tokenized codes must be explicitly rebuilt when the source codes
  208.        are modified.
  209.  
  210. 6. Tips in using dynamic SQL in REXX to access DB2/2 2.x database
  211.  
  212.    - Always first set the current query optimization = 0
  213.      This minimizes the time used by the DB2/2 2.x engine to prepare
  214.      the SQL.  By default, IBM sets the current query optimization = 5.
  215.  
  216.      If necessary, adjust the current query optimization for some
  217.      (dynamic) SQL statements to deliver optimum response time
  218.      (i.e. total time to prepare + open cursor + (multiple) fetch(es))
  219.  
  220.    - Use SQL parameter marker (?) selectively
  221.      As a rule of thumb, do not use the parameter marker in the SQL
  222.      if the prepared SQL is not going to be used more than 5 times
  223.      within the same program execution.
  224.  
  225.      Instead, prepare a complete SQL statement in the REXX program and
  226.      then pass it to the DB2/2 engine (via SQLEXEC) for preparation
  227.      there.  If the data in the SQL statement contains single quotes,
  228.      make sure those single quotes are repeated in the SQL string
  229.      before the SQL string is passed in the DB2/2 SQL preparation.
  230.  
  231.      Example:
  232.        UPDATE EMPLOYEE SET LASTNAME = 'O'Brien' WHERE CLIENTID = 123
  233.  
  234.      must first be translated into
  235.        UPDATE EMPLOYEE SET LASTNAME = 'O''Brien' WHERE CLIENTID = 123
  236. ------------------------------------------------------------------------
  237.  
  238.             Thank you for considering and/or using REXXGDB2.
  239.  
  240.  
  241.                               Simon Husin
  242.                          Global Automation Co.
  243.                             Kent, Washington
  244.                                  U.S.A.
  245.  
  246.                          E-mail: husin@ibm.net
  247.                           Fax: 1-206-813-8202
  248.