========================================================================= G C O S - 8 C O B O L W O R K B E N C H v1.4.52 32bit RELEASE ========================================================================= DBSP SUPPORT NOTES ================== TABLE OF CONTENTS ================= INTRODUCTION REQUIREMENTS INSTALLATION COMPILING TESTING SAMPLES HINTS & TIPS KNOWN LIMITATIONS/ERRORS INTRODUCTION ============ This document describes features specific to DBSP Support. This information will later be included in the G8WB 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 GCOS CMA Preprocessor and DBSP environment is used to split application programs into a GCOS part and a UNIX part, and glue these together during execution. With DSP Support, G8WB 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: G8WB 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 G8WB. Note: The path for PRO*COBOL, ex. c:\orant\bin, must be amended to PATH setting, otherwise G8WB 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 NOT part G8WB release V1.4.40, but included as an optional components in V1.4.52 (or higher) updates. When installed as part of an update, NO configuration files are updated and you are required to manually amend a few entries into existing G8WB configuration files. Following describes the configuration files involved: Preprocessor - $g8wbgdir\G8WB.CFG DBMS configuration - $g8wbddir\DBMS.CFG 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 invisble 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 GCOS provides various features for pre-load and pre-connect of DBSP programs, however since G8WB use dynamic linking, pre-connect configuration must be done differently. Pre-load configuration is not relevant in G8WB 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 G8WB, but treated as a comment by GCOS. 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: G8WB 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 COBOL-DBSP is available in CHAR and GUI environment. DBSP sources are treated like any other source types, i.e. import, export etc., and it's the COBOL-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 G8WB 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 GCOS, since most of the SQL syntax is checked by PRO*COBOL. A few of the CMA limitation are enforced by G8WB preprocessor, and these will use the same error message as GCOS. 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 ------------- G8WB support standard COBOL-85 Copy handling, and is thus compatible with DBSP compilation with COPY Preprocessor on GCOS. Command ------- A new command has been added for checking of DBSP programs through command files: WB W8 CHKCDBSP program Work Files ---------- By default, G8WB 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 GCOS 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 GCOS 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 G8WB (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: G8WB 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. G8WB includes a copy of the same sample programs, however, these are only installed if you select SAMPLES during G8WB 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: G8WB does not replace SQL Commit and Rollback verbs like CMA, but process these ASIS (like Commit=Oracle mode on GCOS). o CHECKPOINT_FILES: G8WB does NOT execute 'ON EXCEPTION' phrase for this service call. To make execution compatible with GCOS, use CALL within exception and consult the checkpoint-status field with IF verb. o Please refer also to limitations described in text above. ========================================================================= GCOS-8 COBOL Workbench is a trademark of B & C Solution Sarl. All other trademarks and trade names belong to their respective companies. ========================================================================= Copyright (C) 1998-2001 B & C Solution Sarl. All Rights Reserved.