home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 8 Other / 08-Other.zip / tblcp2.zip / tblcop2.INF (.txt) < prev    next >
OS/2 Help File  |  1993-10-28  |  16KB  |  417 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. About the Table Copier ΓòÉΓòÉΓòÉ
  3.  
  4. This utility is designed to copy the result of an SQL "Select" statement from 
  5. one database (source) to one or more target databases at one or more target LUs 
  6. (targets).  Since this is a DB2/2 utility, you can copy a table from/to any 
  7. database that can be accessed via DB2/2 APIs (i.e. not only DB2/2 databases 
  8. per-se, but any database DB2/2 supports connects to, such as DRDA databases 
  9. (DB2,SQL/DS,etc.)).  The utility consists of two programs, one of which 
  10. connects to the source database, the other of which connects to the target 
  11. database.  This is necessary because DB2/2 does not allow a single process to 
  12. simultaneously connect to two or more databases. 
  13.  
  14. The "exporter" (source) and "importer" (target) talk to each other using Appc. 
  15. This transport mechanism has the advantage of allowing the exporter and 
  16. importer to run on different OS/2 machines.  The only necessary relationship 
  17. between two participating OS/2 machines is that they be "mutually Lu6.2 
  18. addressable."  That is, the exporter machine must be able to bind an Lu6.2 
  19. session with the importer machine.  Needless to say, this requires 
  20. Communications Manager in addition to Database Manager. 
  21.  
  22. The exporter can "distribute" the table it is copying to multiple targets at 
  23. once (a separate instance of the importer is started at each target). 
  24.  
  25. The process is always driven from the exporter side, because that is where the 
  26. SQL Select statement (which defines the table to be copied) is supplied.  The 
  27. exporter is implemented as a Rexx external function. This was done because the 
  28. exporter requires many parameters and Rexx compound variables (stems) provide 
  29. an easy way to pass such structures into a compiled program.  Besides, if it's 
  30. callable from Rexx, it can be used anywhere in OS/2. 
  31.  
  32.  
  33.   Author:        Dave Boll
  34.                  (CompuServe = 74170,2016)
  35.                  IBMMAIL(USFMCFKF)
  36.   Release Date:  28 October, 1993
  37.   Version:       1.2 (for DB2/2)
  38.  
  39.   Copyright 1993 Dave Boll
  40.  
  41.  
  42. ΓòÉΓòÉΓòÉ 2. New in this release ΓòÉΓòÉΓòÉ
  43.  
  44. This release contains a few fixes and some new features. 
  45.  
  46. New Features:
  47.  
  48.   - Ability to limit number of rows fetched and sent.
  49.     (Thanks to suggestion by Jean-Claude Marchier)
  50.   - Ability to specify fetch/send ratio
  51.   - Ability to supply an argument to the follow-up command string
  52.     sent to importer.
  53.   - Ability to specify a userid/password for APPC conversation
  54.     security which is independent of that used for target database
  55.     logon.
  56.   - Format of each target's result string changed to be more usable
  57.  
  58. Bug Fixes:
  59.  
  60.   - Was not treating empty follow-up command string properly.
  61.   - Code to log SQL statement failures in the importer
  62.  
  63.  
  64. ΓòÉΓòÉΓòÉ 3. How to Use It ΓòÉΓòÉΓòÉ
  65.  
  66. How to register the table copier as a Rexx function: 
  67.  
  68. In order to use the function, you have to register it with Rexx like this:
  69.  
  70.   call rxfuncadd yourfuncname,'tblcop2e','tblcop2e'
  71.  
  72. where:
  73.  
  74.   yourfuncname = any name by which you want to refer to the function in
  75.                  your Rexx programs
  76.  
  77.  
  78. ΓòÉΓòÉΓòÉ 4. Tips, Restrictions, Recommendations ΓòÉΓòÉΓòÉ
  79.  
  80. Important notes: 
  81.  
  82.   - The DLL "tblcop2e.dll" must be in your "LIBPATH" for the Rexx
  83.     external function "tblcop2e" to work.
  84.  
  85.   - The exporter and importer components of the utility will attempt to bind
  86.     themselves to the source and target databases (respectively) if necessary.
  87.     First, if the "tblcop2e.bnd" file is in the same directory as the
  88.     "tblcop2e.dll" DLL was loaded from, this will be used to bind.  And if the
  89.     "tblcop2i.bnd" file is in the same directory as the "tblcop2i.exe" EXE was
  90.     loaded from, this will be used to bind.
  91.     In each case, if the corresponding .BND file is not found in the respective
  92.     directory, the "DPATH" will be searched for a bind file.  If none is
  93.     found, the utility will fail.
  94.  
  95.   - The function "tblcop2e" is NOT designed to be run on multiple threads
  96.     of the same process.  If you try to run the function on multiple threads
  97.     of the same process, results will be unpredictable.
  98.  
  99.   - The components of this utility are 32-bit code and therefore will
  100.     only run on OS/2 2.x versions.
  101.  
  102.  
  103. ΓòÉΓòÉΓòÉ 5. Syntax ΓòÉΓòÉΓòÉ
  104.  
  105. The basic syntax is: 
  106.  
  107.  
  108.   info = tablecopy(fromdb,selstmt,targstem[,fromid][,frompw][,cmtfreq]
  109.                    [,nodata][,appcmode][,fetchlim][,fsratio])
  110.  
  111. where:
  112.  
  113.   fromdb   = name of source database, from the perspective of the
  114.              machine where the exporter is running
  115.  
  116.   selstmt  = actual text of an SQL Select statement whose result table
  117.              you want copied.  This statement may not contain any host
  118.              variables or parameter markers.  That is, it is restricted
  119.              in the same way as an SQL statement in QMF or SPUFI.  In
  120.              addition, since the statement is prepared and executed
  121.              dynamically, the auth-id running the exporter must have
  122.              whatever privileges are necessary to perform the select.
  123.              It is recommended that you always specify the "For Fetch
  124.              Only" clause on your select statement as this will cause
  125.              block fetch at the source database, if it is remote from
  126.              the source machine.
  127.  
  128.   targstem = the actual name of a Rexx stem (such as "st.") under
  129.              which are mapped the parameters for 1-n targets as such:
  130.  
  131.                stem.n.1  = target Lu name
  132.                stem.n.2  = target database name
  133.                stem.n.3  = target table name
  134.                stem.n.4  = userid to be used for logon to target database
  135.                stem.n.5  = password to be used with "stem.n.4"
  136.                stem.n.6  = copy option which governs how table is copied
  137.                            to target
  138.                stem.n.7  = alter option which tells importer how to
  139.                            handle surplus columns
  140.                stem.n.8  = convert short-enough LongVarChar to VarChar
  141.                stem.n.9  = use Appc Security
  142.                stem.n.10 = altnerate column names for target table
  143.                stem.n.11 = follow-up command string to be executed at
  144.                            target after table copy is complete (such
  145.                            as DDL, etc.)
  146.                stem.n.12 = Argument to program specified in stem.n.11
  147.                stem.n.13 = Alternate Appc Security Userid
  148.                stem.n.14 = Alternate Appc Security Password
  149.  
  150.   fromid   = userid to be used for logon to source database
  151.  
  152.   frompw   = password to be used for logon to source database
  153.  
  154.   cmtfreq  = commit frequency, causes a commit at target(s) every time
  155.              this many rows have been processed (keeps log file size down).
  156.  
  157.   nodata   = causes source table's structure to be copied without
  158.              sending its rows (still allows follow-up command string),
  159.              allowing the DDL of a table to be distributed.
  160.  
  161.   appcmode = alternate APPC Mode Name to be used in conversation(s)
  162.              between exporter and importer (default is "#BATCH").
  163.  
  164.   fetchlim = integer specifying maximum number of rows to be fetched
  165.              and sent (default is all rows from SELECT statement).
  166.  
  167.   fsratio  = fetch/send ratio, which allows you to send every "nth"
  168.              row (default is every row (i.e. fsratio = 1)).
  169.  
  170.  
  171. ΓòÉΓòÉΓòÉ 6. Target parameter info ΓòÉΓòÉΓòÉ
  172.  
  173. The target parameter structure defines where/how to distribute table. 
  174.  
  175.  
  176.   Specific information about the elements of the target parameter structure:
  177.  
  178.     stem.n.1  = target Lu name (REQUIRED)
  179.                 - can be either an lu alias, a fully qualified luname
  180.                   or an asterisk (*) to indicate same as originating lu
  181.  
  182.     stem.n.2  = target database name (as catalogued at the target Lu) (REQUIRED)
  183.                 - this name is the local alias of the target database
  184.                   at the target lu.  This allows you to "leapfrog"
  185.                   databases by addressing a database at a remote lu
  186.                   which is in turn remote from that lu.
  187.  
  188.     stem.n.3  = target table name (REQUIRED)
  189.  
  190.     stem.n.4  = userid to be used for logon to target database (REQUIRED)
  191.                 - this userid is also used for Appc Security, if
  192.                   such is requested with "stem.n.9" (see below)
  193.  
  194.     stem.n.5  = password to be used for logon to target database (REQUIRED)
  195.                 - this password is also used for Appc Security, if
  196.                   such is requested with "stem.n.9" (see below)
  197.  
  198.     stem.n.6  = copy option governs how table is copied to target (OPTIONAL)
  199.                 Valid values are:
  200.                   C - Create
  201.                       (DEFAULT)
  202.                       Table will be created at target database.  This
  203.                       will fail if table already exists at target.
  204.                   R - Replace
  205.                       Table will be created at target database, or droppoed
  206.                       and then created if it already existed.
  207.                   A - Append
  208.                       Rows sent are added to existing rows in target
  209.                       table.
  210.                   O - Overlay
  211.                       All rows in target table are deleted, then sent
  212.                       rows are inserted in their place.
  213.                   I - Insert_Update
  214.                       Each sent row is inserted, or used to update if
  215.                       row of same primary/sole-unique key already exists.
  216.                       Should be used instead of "Update_Insert" if most
  217.                       sent rows will be "inserts" because fewer SQL
  218.                       statements will be executed.
  219.                   U - Update_Insert
  220.                       Each sent row updates row of same primary/sole-unique
  221.                       key if it exists, or is inserted otherwise.
  222.                       Should be used instead of "Insert_Update" if most
  223.                       sent rows will be "updates" because fewer SQL
  224.                       statements will be executed.
  225.  
  226.     stem.n.7  = alter option indicates how to handle surplus columns (OPTIONAL)
  227.                 To determine what are surplus columns, the leading columns of
  228.                 the sent table are compared with the corresponding columns of
  229.                 the target table (if it exists).  If all leading columns match
  230.                 exactly (same data type, except nullability, and same precision
  231.                 and scale, and same column name), and copy option is APPEND,
  232.                 OVERLAY, INSERT_UPDATE, UPDATE_INSERT, then alter option will
  233.                 be honored.  For instance, if the target table has 6 columns,
  234.                 but the table being sent has 8 columns, do I want to alter
  235.                 the target table to add the 2 new columns of the incoming
  236.                 table, or ignore these new columns, or reject the copy?
  237.                 Valid values are:
  238.                   A - alter target table to add new columns before
  239.                       inserting/updating rows
  240.                   I - ignore surplus columns (that is, for each sent
  241.                       row, discard the surplus columns)
  242.                   R - reject the copy if structures do not match exactly
  243.                       (DEFAULT)
  244.  
  245.     stem.n.8  = convert short-enough LongVarChar to VarChar (OPTIONAL)
  246.                 From DB2/2, a DB2 column which describes as having a
  247.                 length > 255 bytes and < 4000 bytes appears as LongVarChar,
  248.                 though the same column in DB2/2 could be just VarChar.
  249.                 This option allows such columns to be created in DB2/2 as
  250.                 just VarChar of the appropriate length.
  251.                 Valid values:
  252.                   N - Don't convert LongVarChar->VarChar
  253.                       (DEFAULT)
  254.                   Y - Do Convert LongVarChar->VarChar
  255.  
  256.     stem.n.9  = use Appc Security (OPTIONAL)
  257.                 when allocating conversation to importer at target,
  258.                 use Appc conversation security.
  259.                 Valid values:
  260.                   N - Don't use conversation security
  261.                       (DEFAULT)
  262.                   Y - Do Use conversation security
  263.  
  264.     stem.n.10 = alternate column names (OPTIONAL)
  265.                 specification of alternate column names for target
  266.                 table.  This is a blank delimited list of the form:
  267.                   colno.colname colno.colname colno.colname ...
  268.                 where:
  269.                   colno   = the relative column number to be renamed
  270.                             (for a table with "n" columns, valid
  271.                              values are 1-n)
  272.                   colname = new name for the column (1-18 characters)
  273.  
  274.                 an example of an alternate column list specification:
  275.  
  276.                   "3.new_col3  5.first_name  2.second_col"
  277.  
  278.     stem.n.11 = follow-up command string (OPTIONAL)
  279.                 - follow-up command string to be executed at target
  280.                   after table copy is complete.  This string is
  281.                   interpreted directly by the Rexx interpreter at the
  282.                   target machine as a Rexx program.  Thus, whatever
  283.                   you send must be legal Rexx program source code.
  284.                   Typically, this feature could be used to execute DDL
  285.                   after the copy has completed, but since you're talking
  286.                   to the Rexx interpreter, you obviously could do lots
  287.                   of other things.  This includes deleting files and
  288.                   the like, which is why you may want to secure the
  289.                   importer at the target machine to require appc security.
  290.  
  291.     stem.n.12 = Argument to program specified in stem.n.11
  292.                 - this is a way to pass data to the program string
  293.  
  294.     stem.n.13 = Alternate Appc Security Userid (OPTIONAL)
  295.                 - this is used when Appc Security is requested, but
  296.                   the userid to be used for Appc Security must be
  297.                   different from that used for the target database
  298.                   logon.  If Appc Security is requested, but this
  299.                   value is not supplied, then the target database
  300.                   logon userid will be used in its place.
  301.     stem.n.14 = Alternate Appc Security Password (OPTIONAL)
  302.                 - this is used when Appc Security is requested, but
  303.                   the password to be used for Appc Security must be
  304.                   different from that used for the target database
  305.                   logon.  If Appc Security is requested, but this
  306.                   value is not supplied, then the target database
  307.                   logon password will be used in its place.
  308.  
  309.  
  310. ΓòÉΓòÉΓòÉ 7. Results ΓòÉΓòÉΓòÉ
  311.  
  312. The result of the copy to each target is returned under the stem used to supply 
  313. target parameters for that target as "stem.n" for target "n". 
  314.  
  315. You can disect the result for each target as such:
  316.  
  317.   do i=1 to stem.0
  318.     parse var stem.n copyresult ' ' commandresult
  319.   end
  320.  
  321. where:
  322.  
  323.   copyresult    = string which indicates copy statistics as such:
  324.  
  325.                     #rows:rcvd=#rcvd,isrt=#isrt,updt=#updt
  326.  
  327.   commandresult = byte for byte result returned from your Rexx
  328.                   command string as executed by the importer
  329.  
  330. The function itself returns a value which indicates its success ('0')
  331. or failure (not '0')
  332.  
  333.  
  334. ΓòÉΓòÉΓòÉ 8. How it works ΓòÉΓòÉΓòÉ
  335.  
  336. The exporter starts a conversation with an instance of the importer for each 
  337. target specified.  The exporter can distribute the same copy of a table to 
  338. multiple targets in one invocation.  The mechanisms are somewhat like this: 
  339.  
  340.  
  341.   Sending LU                               Receiving LU
  342.   (tblcop2e)                               (tblcop2i)
  343.   ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ                        ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  344.   Γöé               Γöé                        Γöé                   Γöé
  345.   Γöé From Database Γöé          APPC          Γöé Target Database #1Γöé
  346.   Γöé Select Stmt.  ΓöéΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ>Γöé Target Table #1   Γöé
  347.   Γöé               Γöé  Γöé                     Γöé                   Γöé
  348.   Γöé               Γöé<ΓöÇΓöéΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöé                   Γöé
  349.   Γöé               Γöé  Γöé   ^                 Γöé                   Γöé
  350.   Γöé               Γöé  Γöé   Γöé                 Γöé                   Γöé
  351.   ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ  Γöé   Γöé                 ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  352.                      Γöé   Γöé
  353.                      Γöé   Γöé                 Receiving LU
  354.                      Γöé   Γöé                 (tblcop2i)
  355.                      Γöé   Γöé                 ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  356.                      Γöé   Γöé                 Γöé                    Γöé
  357.                      Γöé   Γöé   APPC          Γöé Target Database #2 Γöé
  358.                      ΓööΓöÇΓöÇΓöÇΓöéΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ>Γöé Target Table #2    Γöé
  359.                          Γöé                 Γöé                    Γöé
  360.                          ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöé                    Γöé
  361.                                            Γöé                    Γöé
  362.                                            Γöé                    Γöé
  363.                                            ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  364.  
  365.                                 .
  366.                                 .
  367.                                 .
  368.                                 .
  369.                                 .
  370.                                 .
  371.  
  372.  
  373. If you are copying a table from a database on one machine to a remote
  374. database (another DB2/2), it is best to have the importer run on the
  375. machine where the remote database resides because then its SQL will
  376. execute locally on that machine.  However, the exporter and importer
  377. can each connect to a database which is remote from the machine on
  378. which they are running.
  379.  
  380.  
  381. ΓòÉΓòÉΓòÉ 9. Communications Manager Configuration ΓòÉΓòÉΓòÉ
  382.  
  383. Because the utility uses Appc for communication between the exporter and the 
  384. importer, certain features of the Comm. Mgr. SNA configuration must be set up. 
  385.  
  386.  
  387. Suggested configuration values in the .NDF of a target machine:
  388.  
  389.   DEFINE_TP tp_name(TBLCOP2I)
  390.             filespec(c:\tblcop2i.exe)
  391.             conv_security_rqd(no)        /* or this could be "yes" */
  392.             conversation_type(mapped)    /* MUST be mapped */
  393.             program_type(vio_windowable)
  394.             sync_level(either)           /* "either" or "confirm" */
  395.             tp_operation(nonqueued_am_started);
  396.  
  397. or, to avoid explicit definition of TP:
  398.  
  399.   DEFINE_DEFAULTS  IMPLICIT_INBOUND_PLU_SUPPORT(YES)
  400.                    DEFAULT_MODE_NAME(#BATCH)
  401.                    MAX_MC_LL_SEND_SIZE(32767)
  402.                    DIRECTORY_FOR_INBOUND_ATTACHES(*)
  403.                    DEFAULT_TP_OPERATION(NONQUEUED_AM_STARTED)
  404.                    DEFAULT_TP_PROGRAM_TYPE(VIO_WINDOWABLE)
  405.                    DEFAULT_TP_CONV_SECURITY_RQD(NO)
  406.                    MAX_HELD_ALERTS(10);
  407.  
  408.  
  409. ΓòÉΓòÉΓòÉ 10. Possible Uses ΓòÉΓòÉΓòÉ
  410.  
  411. The utility can be used to copy/merge tables within a single database on a 
  412. single machine, among databases on a single machine, or among databases on 
  413. several machines.  The number of targets for a given copy operation is limited 
  414. only by available memory. 
  415.  
  416. This utility can be used to efficiently download data from DB2 or SQL/DS into 
  417. DB2/2 databases if you have DDCS/2 available.