========================================================================= G C O S 8 M A I N F R A M E E X P R E S S v2.5.04 G C O S 8 N E T E X P R E S S v4.0.04 Windows NT/2000/XP RELEASE ========================================================================= DBSP SUPPORT NOTES ================== TABLE OF CONTENTS ================= INTRODUCTION REQUIREMENTS INSTALLATION COMPILING TESTING SAMPLES HINTS & TIPS KNOWN LIMITATIONS/ERRORS DISCLAIMER INTRODUCTION ============ This document describes features specific to DBSP Support. This information will later be included in the MFE8/NE8 documentation set. DBSP programs use the Database Server Processsor, which host a standard Oracle 8 RDBMS, and you are thus able to write GCOS8 batch or TP8 programs which include embedded SQL directives. The GCOS8 CMA Preprocessor and DBSP environment is used to split application programs into a GCOS8 part and a UNIX part, and glue these together during execution. With DBSP Support, MFE8/NE8 allows you to compile DBSP programs locally on the PC Workstation, and test DBSP programs either against a local or remote Oracle 8 RDBMS. Note: MFE8 treat DBSP programs like any other COBOL-74/85 program and use dynamic linking, and a DBSP program is ready to test as soon as it has been checked (compiled) without errors. REQUIREMENTS ============ DBSP Support utilize Oracle PRO*COBOL v8.1.x Preprocessor, and you need to install PRO*COBOL on the same PC Workstation as MFE8. Note: The path for PRO*COBOL, ex. c:\orant\bin, must be amended to PATH setting, otherwise MFE8 will fail to invoke the preprocessor. To provide a more flexible single-user environment, you are able to install Oracle 8 RDBMS on the same PC Workstation (Windows NT/2000 or XP). INSTALLATION ============ DBSP Support is an optional part of MFE8 release V2.5.01. Preprocessor (PREP.CFG) ----------------------- o DBSP-SQLCA-PATH is an optional setting, which may be used to make SQLCA structure visible during animation. The default (no setting) is an invisible SQLCA structure. [DEFAULT-SECTION] DBSP-SQLCA-PATH : "k:\orant\precomp\public\sqlca5.cob" -------- I-> The PRO*COBOL or Oracle 8 path DBMS (DBMS.CFG) --------------- The DBSP Configuration on GCOS8 provides various features for pre-load and pre-connect of DBSP programs, however since MFE8 use dynamic linking, pre-connect configuration must be done differently. Pre-load configuration is not relevant in MFE8 environment. If pre-connect is required, the main source in a batch program or TPR, must include a pre-connect directive, ex. *set>DBSP pre-connect:mytest IDENTIFICATION DIVISION. The directive is recognized by MFE8, but treated as a comment by GCOS8. The pre-connect name 'mytest' will trigger connection to Oracle RDBMS, the first time the program is executed within a commitment unit. The pre-connect name 'mytest' is symbolic, and needs to be mapped to an actual connect string at run-time. A new section within DBMS Configuration may be used to provide such mapping. [DBSP-PRE-CONNECT] ;Symbolic name userid/password[@tnsname] Mytest : scott/tiger@TORA1 Mylocaltest : scott/tiger Note: MFE8 does NOT use DBSP-NAME for connection, instead the it uses the default Oracle server, or a remote Oracle server identified by it's TNSNAME. COMPILING ========= When DBSP support is installed, an additional compile type GCOS8 DBSP is available. DBSP sources are treated like any other source types, i.e. import, export etc., and it's the GCOS8 DBSP compile type which trigger Oracle preprocessing, which is embedded as Phase 3 during the integrated checking process. Source Directives ----------------- Following new source directives may be used: *set>dbsp name:TESTDBSP (default is DBSP) *set>dbsp app:MYAPP1 (default is APP) *set>dbsp exe:MYEXE1 (default is ) *set>dbsp commit:TWO_PHASE (default is ONE_PHASE, options are: ONE_PHASE TWO_PHASE ORACLE *set>dbsp pre-connect:mytest (default is no pre-connect) The Name, App and Exe directives are use to fill DBSP-SERVER-ID structure at run-time. The commit directive is used to set commitment mode during execution, however, current MFE8 does not enforce commitment restrictions. The pre-connect directive is used to trigger pre-connection to Oracle RDBMS. The pre-connect value may be either a symbolic name or a connect string, ex. *set>dbsp pre-connect:scott/tiger@TORA1 *set>dbsp pre-connect:mytest If no pre-connect directive is given, the application must establish a connection to Oracle RDBMS via 'EXEC SQL Connect ...' verb. Note: Use of symbolic pre-connect is recommended, since actual connect string is retrieved at run-time (more flexible configuration). Error Messages -------------- Errors messages from checking/compilation are not compatible with GCOS8, since most of the SQL syntax is checked by PRO*COBOL. A few of the CMA limitation are enforced by MFE8 preprocessor, and these will use the same error message as GCOS8. Note: Checker will only show a one line (first line) error message, however, additional error message lines from PRO*COBOL are visible in the listing (LST file). Copy Handling ------------- MFE8 support standard COBOL-85 Copy handling, and is thus compatible with DBSP compilation with COPY Preprocessor on GCOS8. Command ------- A new command has been added for checking of DBSP programs through command files: RUN WB CHKCDBSP program Work Files ---------- By default, MFE8 will delete all work files used during preprocessing, however the PREP-WORK-FILE:KEEP setting, may be used to save the work file (program.WRK) for debugging purposes. This setting also apply for DBSP programs, however here the WRK file source before PRO*COBOL preprocessing and XWK after PRO*COBOL pre- processing. TESTING ======= Like all GCOS8 source types, DBSP programs are animated using the original program source, and SQL verbs are animated like other COBOL verbs. Batch ----- For batch DBSP programs, only the first program (main or module using DBSP) initializes the commitment unit. The means DBSP-SERVER-ID structure is filled only once, and pre-connection is performed only once. TP8 --- For TP8 DBSP programs, each TX/Phase is considered a commitment unit, and only the first program (TPR or module using DBSP) initializes the commitment unit. The means DBSP-SERVER-ID structure is filled only once, and pre-connection is performed only once. The exception is when SQL Connect verb is used by the application, in which case termination of the commitment unit (TX/Phase) will reset and disconnect all Oracle RDBMS connections. Note: DBSP TPR's are treated as resident after first load, and thus never cancelled. This behavior is not GCOS8 compatible, however, required to avoid problems with open Oracle RDBMS connections. Service Calls ------------- The following DBSP specific service calls are supported: CMADISPLAYERROR CMAGETERRORINFO CMAGETSTATUSNEXT CMASETDBSP (partial only) DBSP_ROLLBACK_FILES Standard DBSP copy is automatically included by MFE8 (like CMA) during checking, and structures are visible during animation. All types of Checkpoint/Rollback service calls and implied Checkpoints/ Rollbacks (TP8) will trigger commitment towards Oracle RDBMS. Note: MFE8 does not enforce any limitations in relation to commit type, i.e. ONE_PHASE, TWO_PHASE or ORACLE, and will act like TWO_PHASE if both IDS-II and DBSP is used within the same commitment unit. SAMPLES ======= BULL supplies DBSP software with a number of simple test programs, which use Oracle sample database to verify correct installation. MFE8 includes a copy of the same sample programs, however, these are only installed if you select SAMPLES during MFE8 Workstation installation/update. The sample programs are located under $g8wbldir\samples\dbsp as follows: batch\proga.cbl - Test connect and select maina.cbl - Test connect, select and module call mainb.cbl - Test connect, select and module call mainc.cbl - Test connect, select and module call subs1.cbl - Modules with connect and select subs2.cbl subu1.cbl subu2.cbl subuc.cbl tp\tpra.cbl - Test connect and select tprb1.cbl - Test chained TPR with connect and select tprb2.cbl tprc1.cbl - Test chained TPR with module call tprc2.cbl tprs1.cbl - Modules with connect and select HINTS & TIPS ============ o Connect: When using SQL Connect verb, special action must be taken if you are not connecting to a local Oracle RDBMS. Ex. need connection to TNSNAME = P333. exec sql begin declare section end-exec. 01 UserName pic x(10) Value "SCOTT". 01 Password pic x(10) Value "TIGER". exec sql end declare section end-exec. change to exec sql begin declare section end-exec. *w8prep gcos8 01 UserName pic x(10) Value "SCOTT". *w8prep g8wb *01 UserName pic x(10) Value "SCOTT@P333". *w8prep 01 Password pic x(10) Value "TIGER". exec sql end declare section end-exec. KNOWN LIMITATIONS/ERRORS ======================== o PRO*COBOL: The Exec/End-exec verb must start in area B of the source line (column 12-72), otherwise PRO*COBOL will flag this as an error. o PRO*COBOL: If Communication section is specified before Linkage section (incorrect sequence), PRO*COBOL is confused and fails without completing preprocessing. o Commit/Rollback: MFE8 does not replace SQL Commit and Rollback verbs like CMA, but process these ASIS (like Commit=Oracle mode on GCOS8). o CHECKPOINT_FILES: MFE8 does NOT execute 'ON EXCEPTION' phrase for this service call. To make execution compatible with GCOS8, use CALL within exception and consult the checkpoint-status field with IF verb. o Please refer also to limitations described in text above. DISCLAIMER ========== THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. B & C SOLUTION DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL B & C SOLUTION OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF B & C SOLUTION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES SO THE FOREGOING LIMITATION MAY NOT APPLY. ========================================================================= GCOS8 Mainframe Express and GCOS Net Express are a trademarks of B & C Solution. All other trademarks and trade names are the property of their respective owners. ========================================================================= Copyright (C) 1998-2003 B & C Solution. All Rights Reserved.