home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 14 Text / 14-Text.zip / DB2COM.ZIP / DB2COM.DOC
Text File  |  1993-02-21  |  37KB  |  895 lines
  1.  
  2.  
  3.   DB2 Application Development
  4.  
  5.   on the Workstation
  6.  
  7.   5 January, 1993
  8.  
  9.   Phil Singleton
  10.   Richard Hoffman
  11.   Bertha Dodel
  12.  
  13.  
  14.   This paper contains information on certain aspects of developing 
  15.   DB2* applications using AD/Cycle* facilities and the OS/2* 
  16.   Database Manager (Extended Services 1.0 Database Manager) on a 
  17.   workstation.
  18.  
  19.   The paper states IBM's* strategy for developing host-based database 
  20.   applications using AD/Cycle, and describes how to deal with certain 
  21.   features of DB2 and Extended Services 1.0 Database Manager that are 
  22.   not source compatible. This will not be an exhaustive list of 
  23.   differences between the two products.
  24.  
  25.   This minor revision of the paper contains only one change - to refer 
  26.   to the Extended Services 1.0 Database Manager by its proper name.
  27.  
  28.  
  29.  
  30.  
  31.  
  32.   Special Notices
  33.  
  34.   This document is intended to assist application developers, database 
  35.   administrators and system programmers in designing and implementing 
  36.   applications intended for use with DB2, where the application is 
  37.   developed on the workstation before porting it up to the DB2 host. 
  38.   IBM field personnel can provide this document to customers who might 
  39.   benefit from this information.
  40.  
  41.  
  42.   References in this publication to IBM products, programs, or 
  43.   services do not imply that IBM intends to make these available in 
  44.   all countries in which IBM operates.
  45.  
  46.   IBM may have patents or pending patent applications covering subject 
  47.   matter in this publication. The furnishing of this publication 
  48.   does not give you any license to these patents. You can send license 
  49.   inquiries, in writing, to the IBM Director of Commercial Relations, 
  50.   IBM Corporation, Purchase, NY 10577, USA.
  51.  
  52.   The information contained in this publication has not been submitted 
  53.   to any formal IBM test and is distributed on an 'AS IS' basis 
  54.   without any warranty either expressed or implied, including but not 
  55.   limited to, the implied warranties of merchantability or fitness for 
  56.   a particular purpose. This disclaimer does not apply if inconsistent 
  57.   with local law. The use of this information or the implementation of 
  58.   any of these techniques is a customer responsibility and depends on 
  59.   the customer's ability to evaluate and integrate them into the 
  60.   customer's operational environment. While each item may have been 
  61.   reviewed by IBM for accuracy in a specific situation, there is no 
  62.   guarantee that the same or similar results will be obtained 
  63.   elsewhere. Customers attempting to adapt these techniques to their 
  64.   own environments do so at their own risk.
  65.  
  66.  
  67.  
  68.   Trademarks
  69.  
  70.   The following terms, denoted by an asterisk (*) on the first usage 
  71.   of each in this publication, are trademarks of the IBM Corporation 
  72.   in the United States and/or other countries:
  73.  
  74.   AD/Cycle MVS
  75.   CICS OS/2
  76.   DB2 SAA
  77.   IBM
  78.  
  79.  
  80.  
  81.   Strategy for Database Application Development
  82.  
  83.   The AD/Cycle framework is a framework which covers all the phases for 
  84.   developing and maintaining applications throughout the entire 
  85.   development process. The AD/Cycle framework is made up of both the 
  86.   platform and the tools to perform the full range of application 
  87.   development activities from enterprise modeling through development. 
  88.   The strategy for AD/Cycle is to provide these services on a 
  89.   workstation even when
  90.  
  91.   the target operating environment may be on a host system.
  92.  
  93.   When developing applications that include database services, Extended 
  94.   Services 1.0 Database Manager can be a valuable tool. Extended 
  95.   Services 1.0 Database Manager provides strategic functions such as 
  96.   the SAA* Database CPI, and remote data access. A high degree of 
  97.   compatibility between Extended Services 1.0 Database Manager and 
  98.   other IBM database systems allows development of applications for 
  99.   several target platforms.
  100.  
  101.   The focus of this paper is on a particular instance of this general 
  102.   capability: to develop and maintain DB2 applications using Extended 
  103.   Services 1.0 Database Manager, CSP, and the Micro Focus COBOL/2 
  104.   Workbench.
  105.  
  106.   AD/Cycle's direction is to support coding and unit test activities at 
  107.   the workstation. This objective is
  108.  
  109.   accomplished through a combination of development and unit test tools 
  110.   (e.g., Micro Focus COBOL/2 Workbench, CSP AD) and compatible function 
  111.   (e.g., SAA Database Interface).
  112.  
  113.   SAA Database and IBM's open systems strategy provides a high degree 
  114.   of consistency between relational databases including Extended 
  115.   Services 1.0 Database Manager and DB2. In addition to the function 
  116.   included in SAA, it is IBM's objective to provide the consistency 
  117.   that will allow development and unit test of most relational database 
  118.   applications on the workstation which are targeted for running on a 
  119.   host.
  120.  
  121.   AD/Cycle also will help the developers to system test their 
  122.   applications in the target execution environment.  Such assistance 
  123.   includes debug tools, regression test drivers, debug analysis, etc.
  124.  
  125.   For workstations that are connected through DDCS/2 to a host running 
  126.   DB2, the SQL statements can be tested directly on DB2 while the 
  127.   application is running on the workstation. The application can direct 
  128.   the
  129.  
  130.   SQL statements to DB2 using distributed database. This can be 
  131.   advantageous to the installation in several ways. First, the 
  132.   application can run against existing databases; test databases need 
  133.   not be created on the workstation. Second, almost all of the DB2 SQL 
  134.   statements can be used through distributed database, even those not 
  135.   supported by Extended Services 1.0 Database Manager
  136.  
  137.  
  138.   Applicability
  139.  
  140.   The statements and suggestions in this paper assume the following 
  141.   release levels of the applicable products:
  142.  
  143.   ~ DB2 V2R3 ~ OS/2 ES 1.0 DBM
  144.  
  145.   ~ CSP/370AD V4
  146.  
  147.   ~ CSP/370RS V2 ~ CSP/2AD V1
  148.  
  149.   ~ CSP/2RS V1
  150.  
  151.   ~ Micro Focus COBOL/2 Workbench V2.5 ~ Micro Focus Host Compatibility 
  152.   Option for IBM Database Manager V1.0
  153.  
  154.   The level of SQL referred to in this document is IBM SAA Database 
  155.   (SQL) Level 2 and SQL extensions provided by DB2 V2R3.
  156.  
  157.  
  158.  
  159.   Compatibility
  160.  
  161.   IBM took major steps toward product compatibility when it launched 
  162.   SAA. Included in SAA were provisions for a common user interface, 
  163.   common application program interface, and common communication 
  164.   support. SAA was subsequently enhanced to provide additional 
  165.   interfaces, frameworks, and tools to increase compatibility for users 
  166.   and software developers.
  167.  
  168.  
  169.   SAA provides a very substantial base of common function for the 
  170.   application developer, and this includes the common function 
  171.   available in the programming languages and the database managers. In 
  172.   particular, the SAA Database Interface provides all of the basic 
  173.   needs for accessing and manipulating data in relational databases. 
  174.   Also, the AD/Cycle application development facilities provide all of 
  175.   the steps necessary in the application development life cycle.
  176.  
  177.   As robust as the SAA capabilities are, IBM knows that even higher 
  178.   levels of compatibility will further cut development time and 
  179.   increase programmer productivity. Our strategy is to increase the 
  180.   compatibility between our products. Each product release should add 
  181.   to the level of compatibility. IBM will continue to assess customer 
  182.   needs and will make improvements that make application development 
  183.   easier and better.  The following functional items demonstrate this 
  184.   strategic commitment.
  185.  
  186.  
  187.   Recent Compatibility Enhancements in Extended Services 1.0
  188.  
  189.   Database Manager
  190.  
  191.   With the availability of OS/2 Extended Services 1.0, (which includes 
  192.   Extended Services 1.0 Database Manager) new support has been added 
  193.   which removes some of the incompatibilities between DB2 and OS/2 EE 
  194.   DBM. Customers who migrate from OS/2 EE DBM to Extended Services 1.0 
  195.   Database Manager can take advantage of increased compatibility in the 
  196.   following areas.
  197.  
  198.  
  199.   Date/time Arithmetic and Scalar Functions
  200.  
  201.   SQL allows certain addition and subtraction operations on date/time 
  202.   values such as the subtraction of one date from another to obtain a 
  203.   date duration. SQL also has certain scalar functions associated with 
  204.   date/time values such as a DAY function which can extract the day 
  205.   part out of a timestamp. This capability relieves the application 
  206.   programmer from having to extract parts of a datetime value, convert 
  207.   them to numeric data, perform the arithmetic, and convert the result.
  208.  
  209.  
  210.   DB2 supports date/time data types, date/time arithmetic, and the 
  211.   date/time functions. Prior to ES 1.0, the OS/2 DBM supported the 
  212.   date/time data types, but not the arithmetic or functions. This 
  213.   support is now available in Extended Services 1.0 Database Manager.
  214.  
  215.   Collating Sequence
  216.  
  217.  
  218.   DB2 runs on an EBCDIC machine. OS/2 runs on an ASCII machine. The 
  219.   collating sequence of characters is different between these two 
  220.   encoding schemes. In addition, the OS/2 EE DBM implemented a 
  221.   collating sequence that merged upper and lower case letters next to 
  222.   each other. The results of character comparison or ordering was 
  223.   different between the systems if the character strings included 
  224.   upper and lower case or non-alphabetic characters. The difference 
  225.   affected predicate evaluation, order by, and group by processing.
  226.  
  227.   This problem is resolved in Extended Services 1.0 Database Manager by 
  228.   choosing a collating sequence when the database is created. This may 
  229.   be the EBCDIC collating sequence or some other collating sequence. 
  230.   The collating sequence is specified by the 'COLLATE USER  collating 
  231.   string ' clause on the CREATE DATABASE statement (see the example on 
  232.   page 14).
  233.  
  234.  
  235.   FOR UPDATE clause
  236.  
  237.   The FOR UPDATE clause is used in the declaration of a cursor when the 
  238.   cursor will be referred to in a positioned UPDATE statement. It 
  239.   notifies the database manager that updates might take place and that 
  240.   the appropriate locks should be obtained. If the clause is not 
  241.   specified, updates through that cursor are normally not allowed.
  242.  
  243.  
  244.   DB2 allows an exception to this rule if either of two precompiler 
  245.   options, NOFOR or STDSQL(86), are in effect when the application is 
  246.   prepared. The OS/2 EE DBM provides no exceptions, so some 
  247.   installations running this level of DBM have to include the FOR 
  248.   UPDATE clause when porting their DB2 applications down to the 
  249.   workstation. Extended Services 1.0 Database Manager provides a  
  250.   precompiler option, STDLBL, which allows the same exception as does 
  251.   DB2.  Through the use of these precompiler options, application 
  252.   source compatibility can be achieved.
  253.  
  254.   NUMERIC Data Type
  255.  
  256.   The NUMERIC data type is quite similar to the DECIMAL data type, but 
  257.   with enforced precision.  Some DB2 applications, probably those 
  258.   written to conform to ISO-ANSI standards, might have used NUMERIC 
  259.   instead of DECIMAL. The NUMERIC data type is not supported by the 
  260.   OS/2 EE DBM but IS supported by Extended Services 1.0 Database 
  261.   Manager. Applications using the NUMERIC data type can now be ported 
  262.   to the workstation.
  263.  
  264.  
  265.   SQLSTATE
  266.  
  267.   SQLCODEs and SQLSTATEs are return codes that are made available to 
  268.   the application after execution of an SQL statement. Both codes 
  269.   reflect either successful completion or a particular error condition.  
  270.   There are hundreds of SQLCODES defined for each DBM and they are 
  271.   usually not compatible between DBMs. SQLSTATEs, on the other hand, 
  272.   are designed to be compatible between database managers and some of 
  273.   them are standardized in the ISO-ANSI standards.
  274.  
  275.   If an application checks only for success or failure, then SQLCODE 
  276.   can be used compatibly between DBMs. If an application is designed to 
  277.   check for particular classes or types of errors, then only SQLSTATE 
  278.   would be reliably compatible between DBMs. DB2 and Extended Services 
  279.   1.0 Database
  280.  
  281.   Manager implement SQLSTATE, the OS/2 EE DBM does not.
  282.  
  283.   DECLARE TABLE
  284.  
  285.   The DECLARE TABLE statement is used for program documentation and can 
  286.   provide the DB2 precompiler with information useful for error 
  287.   checking the SQL statements in an application program.
  288.  
  289.   DB2 applications which contain this statement cannot be ported to the 
  290.   OS/2 EE DBM. A syntax error will result during program preparation on 
  291.   the workstation. Extended Services 1.0 Database Manager allows this 
  292.   statement to pass through the precompiler without generating a syntax 
  293.   error.  Extended Services 1.0 Database Manager does not use this 
  294.   statement for any error checking.
  295.  
  296.   DECLARE STATEMENT
  297.  
  298.  
  299.   The DECLARE STATEMENT statement is used for program documentation. It 
  300.   declares names that are used to identify prepared SQL statements. DB2 
  301.   applications which contain this statement cannot be ported to the 
  302.   OS/2 EE DBM. A syntax error will result during program preparation on 
  303.   the workstation. Extended Services 1.0 Database Manager allows this 
  304.   statement to pass through the precompiler without generating a 
  305.   syntax error. Extended Services 1.0 Database Manager does not use 
  306.   this statement for any error checking.
  307.  
  308.  
  309.   Incompatibilities Resolved Using CSP
  310.  
  311.  
  312.   In general, CSP provides a high level of compatibility for 
  313.   applications that are developed for different operating 
  314.   environments. CSP application developers need only concern themselves 
  315.   with the SQL statements used in the applications and ensure that the 
  316.   SQL statements are compatible between DB2 and Extended Services 1.0 
  317.   Database Manager
  318.  
  319.   If practical, the CSP application should be written so that CSP 
  320.   automatically generates the needed SQL statements. CSP will tailor 
  321.   the SQL statements, if necessary, to the target environment. In this 
  322.   case, the application can be portable at the source level.
  323.  
  324.  
  325.   Logical NOT Sign (^)
  326.  
  327.   DB2 allows the ]^ X symbol to be used in SQL. It is not supported in 
  328.   Extended Services 1.0 Database Manager because the ]^ X symbol is 
  329.   not a symbol in any of the ASCII code pages currently defined for 
  330.   OS/2. Adding it to a new set of code pages and providing support for 
  331.   the new set is a significant change to all of OS/2 and its 
  332.   components. Instead, it is easier to translate operators containing 
  333.   the ]^ X symbol to the SAA "<>" characters at precompile time.
  334.  
  335.   CSP automatically converts the ]^ X symbol to the universal NOT 
  336.   ("<>") sign.
  337.  
  338.  
  339.   Use of the ]^ X symbol should be discouraged. The alternative coding 
  340.   above is much more widely accepted.
  341.  
  342.   SQL Data Types
  343.  
  344.   Certain character strings and graphic strings (i.e., those having 
  345.   lengths greater than 254 and 127 respectively) have different 
  346.   SQLTYPE codes assigned them by DB2 and the OS/2 DBMs. CSP resolves 
  347.   this difference by changing the OS/2 number to the equivalent DB2 
  348.   number before returning control to the application.
  349.  
  350.   Incompatibilities Resolved Using the Micro Focus COBOL/2
  351.  
  352.   Workbench
  353.  
  354.   Certain features of the Micro Focus COBOL/2 Workbench assist in 
  355.   writing compatible applications. In addition, Micro Focus has 
  356.   released a Host Compatibility Option for use with their COBOL/2 
  357.   Workbench.  This option contains several enhancements that improve 
  358.   compatibility between DB2 and Extended Services 1.0 Database Manager 
  359.   applications. A brief description of the useful features in the 
  360.   Workbench and the Host Compatibility Option follows:
  361.  
  362.  
  363.   COBOL COMP Declarations
  364.  
  365.   DB2 DCLGEN output contains COBOL COMP declarations which are not 
  366.   tolerated in OS/2. This means that a DB2 application which contains 
  367.   DCLGEN output may not port to the workstation without change. In 
  368.   addition, the COBOL data type for an integer on S/390 and OS/400 is 
  369.   COMP-4.  The COBOL data type for an integer on OS/2 is COMP-5. These 
  370.   declarations must be changed when
  371.  
  372.   the application is ported between OS/2 and another platform.
  373.  
  374.   The Micro Focus COBOL/2 Workbench can relieve the programmer from 
  375.   this concern. Small integers can be declared with USAGE BINARY, 
  376.   COMP, COMP-4, or COMP-5.
  377.  
  378.   Declare Section
  379.  
  380.  
  381.   A declare section of a program is the place where host variables are 
  382.   usually declared. The declare section is begun by a BEGIN DECLARE 
  383.   SECTION statement and ended by an END DECLARE SECTION statement. A 
  384.   declare section is required by the OS/2 DBMs but not always by DB2. 
  385.   In DB2, (and except in the C language or whenever the STDSQL(86) 
  386.   precompiler option is is effect) host variables can be declared 
  387.   either in or out of a declare section. Some DB2 applications, 
  388.   therefore, will not easily port to the workstation.
  389.  
  390.   The Micro Focus COBOL/2 Workbench eliminates this problem for the 
  391.   programmer because the compiler does not require the BEGIN DECLARE 
  392.   SECTION and END DECLARE SECTION statements.
  393.  
  394.   This feature is enabled using the the SQLDB2 directive.
  395.  
  396.  
  397.   INCLUDE Text
  398.  
  399.   The SQL INCLUDE statement inserts declarations or code into a source 
  400.   program during precompilation. This can be very useful for copying 
  401.   common host variable declarations into the source programs.  In OS/2, 
  402.   the INCLUDE statement only allows specific SQLCA and SQLDA 
  403.   declarations to be copied into the program. Normally, a DB2 
  404.   application which is written to INCLUDE source code could not
  405.  
  406.   be ported to the workstation without change.
  407.  
  408.   The Micro Focus COBOL/2 Workbench interprets the statements "EXEC SQL 
  409.   INCLUDE filename END-EXEC" the same as the COBOL "COPY filename." 
  410.   statement. The named file may contain any COBOL statements that a 
  411.   copybook can, including further EXEC SQL statements. This is 
  412.   compatible with DB2.
  413.  
  414.  
  415.   Host Variables in Structures
  416.  
  417.   In DB2, applications written in PL/I, C, and COBOL can declare their 
  418.   host variables as host structures. That is, several variables can 
  419.   be collected together into a structure, and a single structure name 
  420.   can be referenced in an SQL statement instead of the individual 
  421.   variable names. This is an important shorthand method, especially 
  422.   when a table contains many columns and FETCHing a row would result in 
  423.   assigning many host variables.
  424.  
  425.   The OS/2 DBMs do not allow host structures. A DB2 application that 
  426.   contains host structure declarations cannot normally be ported to 
  427.   the workstation without significant changes.
  428.  
  429.   The Micro Focus COBOL/2 Workbench, however, recognizes host 
  430.   structures and arrays of indicator
  431.  
  432.   variables and so enables compatible application source code.
  433.  
  434.   The SQLDB2 directive must be set to enable the use of group host 
  435.   variables and group indicator arrays.
  436.  
  437.   Implicit Connection
  438.  
  439.  
  440.   An MVS application is implicitly connected to the database manager 
  441.   identified in a bind option (defaulted to the local DB2 subsystem). 
  442.   In the OS/2 DBMs a START USING DATABASE statement must be issued to 
  443.   connect to a database; there is no implicit connection. The START 
  444.   USING DATABASE statement is not tolerated by DB2. An application 
  445.   cannot be ported between OS/2 and other platforms without a change.
  446.  
  447.   When using Micro Focus COBOL/2 Workbench, this statement can be 
  448.   omitted from the application.  The proper OS/2 database will 
  449.   automatically be started by the application if it is compiled using 
  450.   the SQLINIT and SQLDB directives.
  451.  
  452.  
  453.   EBCDIC Data
  454.  
  455.   Although Extended Services 1.0 Database Manager provides for an 
  456.   EBCDIC collating sequence, the data is stored in the database encoded 
  457.   in ASCII. As the data is retrieved and returned into host variables, 
  458.   it remains ASCII encoded. Some developers have found it necessary (or 
  459.   more convenient) to handle EBCDIC data within their programs. If the 
  460.   application can tolerate data conversion during execution, the Micro 
  461.   Focus Host Compatibility Option provides for this by inserting 
  462.   statements into the application to convert the host variable data 
  463.   between EBCDIC and ASCII.
  464.  
  465.  
  466.   The CHARSET(EBCDIC) directive enables this conversion.
  467.  
  468.   DB2 Data Definition Statements
  469.  
  470.   The Micro Focus Host Compatibility Option allows certain 
  471.   DB2-exclusive SQL statements to be used in a COBOL program or in an 
  472.   off-line batch utility. This facility helps to create a database on 
  473.   the workstation that is similar to the one on the host, using the 
  474.   same SQL statements that are used on the
  475.  
  476.   host. Examples of these statements are CREATE DATABASE, ALTER TABLE, 
  477.   DROP INDEX, and COMMENT ON TABLE.
  478.  
  479.   Other DB2 statements that are not needed or don't make sense on OS/2 
  480.   are parsed by the Micro Focus Host Compatibility Option but are 
  481.   treated as comments. This allows the statements to remain in the 
  482.   application where they will be used by DB2 but ignored on OS/2 and 
  483.   still achieve equivalent results.
  484.  
  485.  
  486.   SQLCODE Mapping
  487.  
  488.   Many of the SQLCODEs used to report error conditions are not the same 
  489.   between DB2 and Extended Services 1.0 Database Manager. If SQLCODE 
  490.   needs to be used instead of SQLSTATE (see ]SQLSTATEX on page 5), the 
  491.   Micro Focus Host Compatibility Option provides a mapping facility to 
  492.   support the translation of Extended Services 1.0 Database Manager 
  493.   SQLCODEs to their DB2 equivalent for special situations.
  494.  
  495.  
  496.   Logical NOT Sign (^)
  497.  
  498.   DB2 allows the ]^ X symbol to be used in SQL. It is not supported in 
  499.   Extended Services 1.0 Database Manager (see ]Logical NOT Sign (^ )X 
  500.   on page 6).
  501.  
  502.   The Micro Focus COBOL Workbench will perform the following 
  503.   translations in source programs when the SQLNOT directive is properly 
  504.   set.
  505.  
  506.   ^= is translated to <> ^< is translated to >= ^> is translated to <=
  507.  
  508.  
  509.   Use of the ]^ X symbol should be discouraged. The alternative coding 
  510.   above is much more widely accepted.
  511.  
  512.   DCLGEN
  513.  
  514.  
  515.   DB2's DCLGEN utility produces table declarations and host structures 
  516.   which can be included in application programs. This automates the 
  517.   task of declaring variables that correspond to the database tables. 
  518.   The OS/2 DBMs have no such utility making it a little harder to 
  519.   develop applications on the workstation.
  520.  
  521.   The Micro Focus Host Compatibility Option provides a DCLGEN facility 
  522.   that creates a COBOL copy member with a DECLARE TABLE and host 
  523.   variable structures from the Extended Services 1.0 Database Manager 
  524.   table definition.
  525.  
  526.  
  527.   Extended Services 1.0 Database Manager Directions
  528.  
  529.  
  530.   The following items have been identified as compatibility 
  531.   enhancements that IBM is interested in for future releases of 
  532.   Extended Services 1.0 Database Manager. The appearance of the items 
  533.   here is NOT a guarantee that this function will be supplied.
  534.  
  535.  
  536.   NOT NULL WITH DEFAULT
  537.  
  538.  
  539.   NOT NULL WITH DEFAULT is a clause in the CREATE TABLE or ALTER TABLE 
  540.   statement that prevents a column from containing null values, and 
  541.   allows a default value other than the null value. The default value 
  542.   depends on the data type of the column (0, blank, empty string, 
  543.   etc.). DB2 supports this clause but the OS/2 DBMs do not. When 
  544.   Extended Services 1.0 Database Manager supports this clause, it will 
  545.   be easier to create tables on the host and the workstation that are 
  546.   the same.
  547.  
  548.   Until this support is provided, workstation tables must be created 
  549.   and explicitly loaded with the appropriate values corresponding to 
  550.   the DB2 defaults.
  551.  
  552.  
  553.   CONNECT
  554.  
  555.   The CONNECT statement connects an application process to the 
  556.   application server identified in the statement. In the current OS/2 
  557.   DBMs, the CONNECT statement is not supported, however, the START 
  558.   USING DATABASE statement is used for similar purposes. When Extended 
  559.   Services 1.0 Database Manager supports the CONNECT statement, 
  560.   applications needing explicit connections can be ported between 
  561.   platforms without having to change between CONNECT and START USING 
  562.   DATABASE.
  563.  
  564.  
  565.   CURRENT SERVER Special Register
  566.  
  567.   The CURRENT SERVER special register identifies the current 
  568.   application server. An application can obtain this value to determine 
  569.   to which server it is currently connected. DB2 supports this special 
  570.   register but the OS/2 DBMs do not. Until support is provided in 
  571.   Extended Services 1.0 Database Manager, applications will have to be 
  572.   written to test for their server in another way. This is easily done. 
  573.   For example, each server could have a small, one-column, one-row 
  574.   table with the server's name
  575.  
  576.   as the value in the table. The table name would be the same in all 
  577.   servers. The application could retrieve the value from the table to 
  578.   determine the current server.
  579.  
  580.   CURRENT TIMEZONE Special Register
  581.  
  582.   The CURRENT TIMEZONE special register specifies the difference 
  583.   between Coordinated Universal Time (UTC, formerly Greenwich Mean 
  584.   Time) and the local time at the application server. Subtracting
  585.  
  586.   CURRENT TIMEZONE from a local time results in a value that represents 
  587.   UTC. This is an ease-of-use feature that may be useful to 
  588.   applications that are sensitive to time zones or need coordinated 
  589.   timestamps.
  590.  
  591.   Until this support is available in Extended Services 1.0 Database 
  592.   Manager, applications that are sensitive to timezone differences 
  593.   must keep track of the differences some other way, e.g., a hard-coded 
  594.   constant in the application or a value stored in a small table in 
  595.   the database, etc.
  596.  
  597.   Escape Clause on LIKE Predicate
  598.  
  599.   The LIKE predicate searches for strings that have a certain pattern. 
  600.   It is used for finding data where, for example, the exact spelling of 
  601.   a name is not known. Two special characters, the underscore and the 
  602.   percent sign, are normally used as "wild card" characters in the 
  603.   search pattern. If either of these characters are needed as actual 
  604.   matching characters in the search pattern, then some way must be 
  605.   found to specify that they should not be treated as "wild cards". The 
  606.   escape clause does this. DB2 supports the escape clause. The OS/2 
  607.   DBMs do not.
  608.  
  609.   Until Extended Services 1.0 Database Manager supports the escape 
  610.   clause, applications developed on the workstation will be restricted 
  611.   from using this feature.
  612.  
  613.  
  614.   UPDATE Privilege on Columns
  615.  
  616.   DB2 has an option on the GRANT table privileges statement that allows 
  617.   an UPDATE operation on only those columns identified in a column 
  618.   list. The Extended Services 1.0 Database Manager GRANT statement 
  619.   applies to an entire table and not to specific columns.
  620.  
  621.   Until Extended Services 1.0 Database Manager supports this 
  622.   capability, applications developed on the
  623.  
  624.   workstation will be restricted from using this feature.
  625.  
  626.   String Concatenation
  627.  
  628.   Extended Services 1.0 Database Manager does not provide a concatenate 
  629.   operation for two or more character strings. This function is 
  630.   available in DB2.
  631.  
  632.  
  633.   Until Extended Services 1.0 Database Manager supports this 
  634.   capability, applications developed on the workstation will be 
  635.   restricted from using this feature.
  636.  
  637.   Numeric Data Type Conversion Functions
  638.  
  639.   The DECIMAL, INTEGER, FLOAT, and VALUE functions are provided by DB2, 
  640.   but not in
  641.  
  642.   Extended Services 1.0 Database Manager.
  643.  
  644.   Until Extended Services 1.0 Database Manager supports these 
  645.   functions, applications developed on the workstation will be 
  646.   restricted from using them.
  647.  
  648.   Aliases
  649.  
  650.  
  651.   Aliases are names that can be assigned to tables or views. This can 
  652.   be useful when porting an application from one environment to 
  653.   another. The database object name can change between environments but 
  654.   the alias name within the application can remain the same. The 
  655.   application need not be modified.
  656.  
  657.   A synonym is like an alias, with a few differences. No authorization 
  658.   is required to define a synonym.  A synonym can only refer to a local 
  659.   table or view. An alias can be defined on an undefined name.  
  660.   Dropping a table or view has no effect on its aliases. An alias can 
  661.   be used by any authorization ID.A synonym can only be used by the 
  662.   authid that created it. See the DB2 SQL Reference for more 
  663.   information. 
  664.  
  665.   DB2 supports aliases and synonyms but Extended Services 1.0 Database 
  666.   Manager does not.
  667.  
  668.  
  669.   Aliases should be used instead of synonyms. It is more likely that 
  670.   Extended Services 1.0 Database Manager will implement aliases than 
  671.   synonyms.
  672.  
  673.   Until Extended Services 1.0 Database Manager supports aliases, the 
  674.   convenience of their use is not available on the workstation. The 
  675.   workaround for this is to have identical authids and object names on 
  676.   both the host and the workstation. In some cases, a view with a 
  677.   portable name can be used as a substitute for an alias.
  678.  
  679.  
  680.  
  681.   Note:  The following three items are of concern only if the 
  682.   application developer is interested in conforming to the ISO-ANSI 
  683.   standards for SQL and needs to code these functions as specified in 
  684.   the standards. Otherwise, it is easy to find compatible 
  685.   alternatives to these functions.
  686.  
  687.  
  688.   UNIQUE Clause on CREATE TABLE
  689.  
  690.   The UNIQUE clause defines a unique key composed of identified 
  691.   columns. Unique keys are used to ensure that there are no duplicate 
  692.   rows in a table. This clause is available in DB2 but not in Extended 
  693.   Services 1.0 Database Manager.
  694.  
  695.  
  696.   Until Extended Services 1.0 Database Manager supports this clause, 
  697.   unique keys can be defined using the CREATE INDEX statement, but 
  698.   applications doing this would not conform to ISO-ANSI SQL.
  699.  
  700.   Stand-Alone SQLCODE
  701.  
  702.   SQLCODE is an SQL return code that has been historically included in 
  703.   a control block called the SQLCA in IBM products. The ISO-ANSI 
  704.   standards define SQLCODE to be a stand-alone variable
  705.  
  706.   instead of a field in a control block. DB2 has a precompiler option 
  707.   that designates which form of SQLCODE will be used in an application 
  708.   program. Extended Services 1.0 Database Manager does not have this 
  709.   option.
  710.  
  711.   The obvious circumvention for this problem is to use the SQLCODE 
  712.   field of the SQLCA and not generate the standalone SQLCODE variable, 
  713.   however, applications doing this would not conform to ISO-ANSI SQL.
  714.  
  715.  
  716.   INDICATOR Keyword
  717.  
  718.   Indicator variables are used with host variables to designate that 
  719.   the host variable contains the null value. Host variables and 
  720.   indicator variables are declared in an application in the general 
  721.   form:
  722.  
  723.   :V1 INDICATOR :V2
  724.  
  725.  
  726.   where V1 is the host variable, the word INDICATOR is an optional 
  727.   keyword, and V2 is the indicator variable. Extended Services 1.0 
  728.   Database Manager does not allow the optional INDICATOR keyword.
  729.  
  730.  
  731.   The obvious workaround for this is to leave "INDICATOR" out of the 
  732.   declaration. It is optional in ISO-ANSI SQL.
  733.  
  734.  
  735.  
  736.  
  737.   Workarounds, Tools, and Helpful Hints
  738.  
  739.  
  740.   Message Formatting Modules
  741.  
  742.   SQLAINTP in OS/2 and DSNTIAR in DB2 are modules having similar 
  743.   function, the formatting of exception messages. Each module has 
  744.   different parameter requirements. Mapping from one to the other is 
  745.   required for compatibility.
  746.  
  747.  
  748.   The following pseudocode is an outline of what can be done to provide 
  749.   the mapping. The strategy is for the application to call the DB2 
  750.   module DSNTIAR. When running on the host, DSNTIAR is executed to 
  751.   format the message. When running on the workstation, this mapping 
  752.   module, also named DSNTIAR, gets control, re-maps the parameters to 
  753.   the OS/2 format, then calls the OS/2 formatting module SQLAINTP.
  754.  
  755.  
  756.   int DSNTIAR (sqlca, message, lrecl);
  757.  
  758.   /* One difference between sqlaintp and DSNTIAR is that */ /* DNSTIAR 
  759.   returns the message to a varchar, while sqlaintp */ /* returns the 
  760.   message to a null-terminated string.*
  761.  
  762.   struct {short int l; char m5241:} message;
  763.  
  764.   /* DSNTIAR assumes that at least 240 bytes are available. */
  765.  
  766.   rc = sqlaintp (message.m, 241, lrecl, sqlca);
  767.  
  768.   /* The other difference is the return */ /* code. This mapping is 
  769.   approximate. */
  770.  
  771.   if (rc > 0 && rc < 241) then {message.l = rc; rc = 0;} if (rc > 240) 
  772.   then {message.l = rc; rc = 4;} if (rc == -4) then {rc = 8;} if (rc == 
  773.   -5) then {rc = 12;} if (rc == -1) then {rc = 16;}
  774.  
  775.   return (rc);
  776.  
  777.   end DSNTIAR.
  778.  
  779.  
  780.   COMMIT/ROLLBACK WORK
  781.  
  782.   It is good coding practice to issue a COMMIT or a ROLLBACK (or the 
  783.   equivalent CICS Syncpoint) before ending an application program. If 
  784.   this isn't done, an implicit COMMIT is performed as the application 
  785.   process terminates. In certain circumstances, the effect of the 
  786.   implicit action can be different between DB2 and Extended Services 
  787.   1.0 Database Manager.
  788.  
  789.   There is no current plan to change Extended Services 1.0 Database 
  790.   Manager or DB2 so that the default action is the same in all cases. 
  791.   To ensure that the results are as expected, an explicit COMMIT or 
  792.   ROLLBACK should be issued in the application just prior to 
  793.   termination.
  794.  
  795.   EBCDIC Collating Sequence on the Workstation
  796.  
  797.   The following REXX procedure is an example of a way to define a 
  798.   database with an EBCDIC collating sequence on the workstation.  /* 
  799.   create an EBCDIC database (PC codepage=850, mainframe codepage=500) 
  800.   */
  801.  
  802.   /* LOAD REXX INTERFACE TO DBM*/ if Rxfuncquery('SQLEXEC') \= 0 then 
  803.   rcy = Rxfuncadd('SQLEXEC','SQLAR','SQLEXEC')
  804.  
  805.   if Rxfuncquery('SQLDBS') \= 0 then rcy = 
  806.   Rxfuncadd('SQLDBS','SQLAR','SQLDBS')
  807.  
  808.   /* GET DB NAME, DRIVE FROM ARGUMENTS */ arg dbname drive comment
  809.  
  810.   if dbname='' then do say 'Usage is "DB2DB dbname 5drive 5comment::"' 
  811.   exit end
  812.  
  813.   /* Collating Sequence from \SQLLIB\SQLECSRX.CMD: */ /* SOURCE = ASCII 
  814.   850; TARGET = EBCDIC 500 */
  815.  
  816.   SQLE_850_500 = '00010203372D2E2F1605250B0C0D0E0F'x||, 
  817.   '101112133C3D322618193F271C1D1E1F'x||, 
  818.   '404F7F7B5B6C507D4D5D5C4E6B604B61'x||, 
  819.   'F0F1F2F3F4F5F6F7F8F97A5E4C7E6E6F'x||, 
  820.   '7CC1C2C3C4C5C6C7C8C9D1D2D3D4D5D6'x||, 
  821.   'D7D8D9E2E3E4E5E6E7E8E94AE05A5F6D'x||, 
  822.   '79818283848586878889919293949596'x||, 
  823.   '979899A2A3A4A5A6A7A8A9C0BBD0A107'x||, 
  824.   '68DC5142434447485253545756586367'x||, 
  825.   '719C9ECBCCCDDBDDDFECFC70B180BFFF'x||, 
  826.   '4555CEDE49699A9BABAFBAB8B7AA8A8B'x||, 
  827.   '2B2C092128656264B438313433B0B224'x||, 
  828.   '22172906202A46661A35083936303A9F'x||, 
  829.   '8CAC7273740A757677231514046A783B'x||, 
  830.   'EE59EBEDCFEFA08EAEFEFBFD8DADBCBE'x||, 
  831.   'CA8F1BB9B6B5E19D90BDB3DAFAEA3E41'x
  832.  
  833.   /* BUILD "CREATE DATABASE" STRING */
  834.  
  835.   string = 'CREATE DATABASE 'dbname if drive <> '' then string = 
  836.   string' ON 'drive if comment <> '' then string = string' WITH 
  837.   "'comment'"' string = string' COLLATE USER :SQLE_850_500'
  838.  
  839.   /* DO IT */ call sqldbs string if SQLCA.SQLCODE <> 0 then say 
  840.   "SQLCODE="SQLCA.SQLCODE
  841.  
  842.   Testing the Collating Sequence on a Database
  843.  
  844.   The following REXX procedure is an example of a way in which the user 
  845.   can interrogate the collating sequence of a database on the 
  846.   workstation.
  847.  
  848.   /* Query collating sequence of database */
  849.  
  850.   /* LOAD REXX INTERFACE TO DBM*/ if Rxfuncquery('SQLEXEC') \= 0 then 
  851.   rcy = Rxfuncadd('SQLEXEC','SQLAR','SQLEXEC')
  852.  
  853.   if Rxfuncquery('SQLDBS') \= 0 then rcy = 
  854.   Rxfuncadd('SQLDBS','SQLAR','SQLDBS')
  855.  
  856.   /* GET DB NAME, DRIVE FROM ARGUMENTS */ arg dbname
  857.  
  858.   if dbname='' then do say 'Usage is "QCOLLATE dbname"' exit end
  859.  
  860.   call sqldbs 'START USING DATABASE 'dbname if SQLCA.SQLCODE<0 & 
  861.   SQLCA.SQLCODE<>-1098 then do say "Can't start: SQLCODE="SQLCA.SQLCODE 
  862.   exit end
  863.  
  864.   stmt = 'CREATE TABLE QCOLLATE.QCOLLATE (C CHAR(1))' call sqlexec 
  865.   'EXECUTE IMMEDIATE :stmt' if SQLCA.SQLCODE<0 then do say "Can't 
  866.   create test table: SQLCODE="SQLCA.SQLCODE signal finis end
  867.  
  868.   stmt = 'INSERT INTO QCOLLATE.QCOLLATE VALUES(?)' call sqlexec 
  869.   'PREPARE S1 FROM :stmt' if SQLCA.SQLCODE<0 then do say "Can't prepare 
  870.   insert stmt: SQLCODE="SQLCA.SQLCODE signal finis end
  871.  
  872.   do i=0 to 255 c = "'"d2c(i)"'" call sqlexec 'EXECUTE S1 USING :c' if 
  873.   SQLCA.SQLCODE<0 then do say "Can't insert row "i": 
  874.   SQLCODE="SQLCA.SQLCODE signal finis end end
  875.  
  876.   stmt = 'SELECT C FROM QCOLLATE.QCOLLATE ORDER BY C'
  877.  
  878.   call sqlexec 'DECLARE C2 CURSOR FOR S2' if SQLCA.SQLCODE<0 then do 
  879.   say "Can't declare cursor: SQLCODE="SQLCA.SQLCODE signal finis end
  880.  
  881.  
  882.   call sqlexec 'PREPARE S2 FROM :stmt' if SQLCA.SQLCODE<0 then do say 
  883.   "Can't prepare select stmt: SQLCODE="SQLCA.SQLCODE signal finis end
  884.  
  885.   call sqlexec 'OPEN C2' if SQLCA.SQLCODE<0 then do say "Can't open 
  886.   cursor: SQLCODE="SQLCA.SQLCODE signal finis end
  887.  
  888.   do i=0 to 15 string = '' do j=0 to 15 call sqlexec 'FETCH C2 INTO :c' 
  889.   if SQLCA.SQLCODE<0 then do say "Can't read cursor: 
  890.   SQLCODE="SQLCA.SQLCODE signal finis end if c<' ' then string=string' 
  891.   ^'d2c(c2d(c)+c2d('@')) else string = string' 'c end say string end
  892.  
  893.   finis:  call sqlexec 'CLOSE C2' call sqlexec 'ROLLBACK' call sqldbs 
  894.   'STOP USING DATABASE' exit
  895.