Offers a brief introduction to ORACLE/TDS. Provides the information you need to run an ORACLE/TDS application.

Transcription

1

2

3 May 1999

4 1992, 1999

5 Preface Scope and Objectives This manual introduces the reader to the ORACLE/TDS facilities and demonstrates how to access ORACLE databases from TDS applications. The preparation and execution of ORACLE/TDS applications (along with the TDS-specific features of Pro*COBOL and Pro*C) are described in full. General knowledge of Pro*COBOL and Pro*C is assumed. Intended Readers This document is aimed at programmers or systems developers who need to write Transaction Processing Routines (TPRs) containing embedded SQL statements that access ORACLE databases. For users of COBOL and C, prior knowledge of Pro*COBOL and Pro*C in both batch and IOF environments is assumed. The appropriate documentary references are the Programmer's Guide to the Precompilers, the Pro*COBOL Supplement and the Pro*C Supplement. In addition, programmers should be generally familiar with the ORACLE and TDS products. Administrators who are responsible for ORACLE/TDS application systems should refer to the optimization and tuning hints given in Sections 4 and 5. Structure of this document Section 1 Section 2 Section 3 Section 4 Section 5 Offers a brief introduction to ORACLE/TDS. Describes how to code, precompile, compile, and link Pro*COBOL TPRs. There is special emphasis on the CONNECT, COMMIT, and ROLLBACK statements. Provides the information you need to run an ORACLE/TDS application. Shows how to call entry points in the H_ORATDS sharable module. Demonstrates various techniques for optimizing the performance of an ORACLE/TDS application. 47 A2 14UR Rev03 iii

6 ORACLE7/TDS User's Guide Section 6 Section 7 Section 8 Appendix A Appendix B Appendix C Appendix D Appendix E Appendix F Appendix G Appendix H Appendix I Glossary Deals with certain rules and restrictions to be taken into account when using ORACLE/TDS. Deals with aspects specific to TDS-XA. Deals with aspects specific to the support of Pro*C under ORACLE7/TDS. Lists and describes the ORACLE/TDS SQLCODE error conditions. Lists sample COPY files. Lists the TDSCLEAN transaction. Lists the SAMPLE transaction. Lists the FETCH transaction. Lists the ORATDS transaction. Gives references and terms for the specialized processors. Lists the H_XAEVT transaction. Lists the error in commit phase during TDS execution. Defines terms that have a particular meaning in an ORACLE/TDS context. Related documents TDS Administrator's Guide...47 A2 32UT TDS COBOL Programmer's Guide...47 A2 33UT TDS C Programmer's Guide...47 A2 07UT ORACLE7 Documentatio n The complete GCOS 7/ORACLE7 manual set is given in the latest revision of the following manual: ORACLE7 Documentation Catalog...47 A2 10UR In particular, readers must be able to refer to the ORACLE manuals that deal specifically with Pro*COBOL and Pro*C. They are: Programmer's Guide to the ORACLE Precompilers...86 A2 77CR PL/SQL 2.1 and Precompilers 1.6 Addendum...86 A2 74CR Pro*COBOL Supplement...86 A2 79CR Pro*C Supplement...86 A2 78CR ORACLE7 Server SQL Language Reference Manual iv 47 A2 14UR Rev03

7 Preface Readers working at sites where ORACLE is running in a High Availability environment must be able to refer to: ORACLE7/TDS-HA User's Guide...47 A2 16UR Syntax Notation The following syntax notation is used in this document: <variable> A variable in angle brackets indicates a value (or string) to be input by the user. [syntax] Optional syntax. 47 A2 14UR Rev03 v

8 ORACLE7/TDS User's Guide vi 47 A2 14UR Rev03

9 Table of Contents 1. Introducing ORACLE/TDS 1.1 Overview Prerequisites Benefits Architecture Restrictions SQL*NET Sharing between TDS, IOF, BATCH ORACLE/TDS with XA ORACLE/TDS with PRO*C Administration and Maintenance Error Codes Building An Oracle/Tds Subsystem (TDS SIDE) The TDS Generation Program The "USE ORACLE" Clause ORACLE-DEF... ORACLE-ENDDEF Block The USE XA Clause Example of a STDS File Preparing TPRs Building AN ORACLE/TDS SUBSYSTEM (ORACLE SIDE) Migration From ORACLE V ORACLE V6/TDS Applications ORACLE Transactions Writing Pro*COBOL TPRs For TDS 2.1 Connecting To Oracle The SQL*Net Context Cache Physical Connection Definition Logical Connection Definition SQL*Net Context Definition A2 14UR Rev03 vii

10 ORACLE7/TDS User's Guide Why a SQL*Net Context Cache? How Does the SQL*Net Context Cache Work? Common Syntax of a CONNECT Statement Default Databases and Connections The default Database The default connection Database Identifiers (SQL*Net) The SQL*Net Syntax for Connecting Automatic Logons Automatic Restart EXEC SQL CONNECT Errors Commitments Using Implicit Commitment Using CALL "DFCMIT" Using the COMMIT Statement Automatic Disconnection from ORACLE After COMMIT Each TDS Commitment Commits Only One ORACLE Database Commit Separate Databases in Separate TPRs EXEC SQL COMMIT Errors Rollback The ROLLBACK Statement The TDS "ROLL-BACK" Primitive The TDS "INVCMIT" Primitive The TDS "NOCMIT" Primitive FOR DEBUG Clause Data Definition Statements Handling Runtime Errors Using the WHENEVER Statement Using the ORACLE Communications Area (ORACA) Precompiling, Compiling And Linking Precompiling a Pro*COBOL TPR Compiling a Pro*COBOL TPR Linking a Pro*COBOL TPR Example of JCL stream generating a Pro*COBOL TPR Running an ORACLE/TDS Application 3.1 The Tds_Sql File The Oracle Communications Server (Cor) Starting COR Stopping COR viii 47 A2 14UR Rev03

11 3.3 The Oracle Database Server Starting ORACLE Adding Extra Connections Stopping ORACLE The H_Oratds Sharable Module Tds Error Messages Relating To Oracle Tuning ORACLE/TDS: Configuration Parameters 4.1 Setting Configuration Parameters At Generation Time Setting Configuration Parameters Dynamically Transaction Description How to Use ORATDS Description of the "ORACLE" Transaction Parameters MAXTIM Parameter MAXWAT Parameter TIMOUT Parameter CSIZE Parameter TRACELVL Parameter Tracefile Parameter Description of KEYWORDs "ORACLE DISPLAY" "ORACLE ENABLE" "ORACLE DISABLE" "ORACLE TERM" "ORACLE WAIT" "ORACLE TRACEON" "ORACLE TRACEOFF" "ORACLE TRACE" Oracle/Tds Statistics Job Occurrence Report Statistics The CASTAT Transaction Setting MAXOPENCURSORS VIA THE "SETMXC" ENTRY POINT MAXOPENCURSORS With SETMXC MAXOPENCURSORS Without SETMXC Using SETMXC Getting Cursor Statistics Via The "Orastat" Entry Point The ORACATDS Structure Layout Using ORASTAT Optimizing ORACLE/TDS Applications 5.1 Sizing The Oracle Context Cache A2 14UR Rev03 ix

12 ORACLE7/TDS User's Guide Sizing Simple Transactions Sizing Complex Transactions Sizing Combined Simple and Complex Transactions Terminal Conversation Committing Before Each Terminal Conversation Handling Cursors Controlling The Number Of User-Ids Optimizing Connect Statements Local Connection Cache Processing GENERAL Oracle Optimization TECHNIQUES Saving CPU Time - Use of Cursors Database Server Database Design Using Several Distinct ORACLE Databases ORACLE/TDS Rules and Restrictions 6.1 The Number Of Connected Terminals ORACLE Processes Updating Ufas OR IDS/II Databases With Oracle Databases Separate Commitment Units Data Consistency Deadlocks Avoiding Deadlocks - Example Creating Deadlocks - Example Controlled Common-Storage Updating Data in Controlled Common-Storage Reading Data in Controlled Common-Storage Non-Controlled Common-Storage The ORACA Structure National Language Support The Spawn Function Opening And Closing GCOS 7 FILES Iqs Roll Forward ORACLE7/TDS-XA x 47 A2 14UR Rev03

13 7.1 Overview Environment Operation Heuristic Decisions TDS Resynchronization with XA TDS Restart User Interface TDS Generation and Application Monitoring TDS Generation Application Monitoring Server Configuration TPR Programming CONNECT Statement and ORACLE7/TDS Cache Manager Using Precompilers with ORACLE XA SQL-Based Restrictions Checking the Synchronization State The H_XAEVT Special Transaction HA And XCP2 Compatibility Writing Pro*C TPRs for TDS 8.1 Introduction Programming Rules Connecting to ORACLE Commitments Rollback Data Definition Statements Handling Runtime Errors Precompiling, Compiling, And Linking Precompiling Compiling Linking Other C Language Variations Setting Configuration Parameters Dynamically Obtaining Cursor Statistics via the orastat Entry Point A. SQLCODE Error Conditions A.1 Sqlcode = A-1 A.2 Sqlcode = A-2 A.3 Sqlcode = A-2 47 A2 14UR Rev03 xi

14 ORACLE7/TDS User's Guide A.4 Sqlcode = A-2 A.5 Sqlcode = A-3 A.6 Sqlcode = A-3 A.7 Sqlcode = A-4 A.8 Sqlcode = A-5 A.9 Sqlcode = A-5 A.10 Sqlcode = A-5 A.11 Sqlcode = A-6 A.12 Sqlcode = A-6 A.13 Sqlcode = A-7 A.14 Sqlcode = A-7 A.15 Sqlcode = A-8 A.16 Sqlcode = A-8 A.17 Sqlcode = A-8 A.18 Sqlcode = A-9 A.19 Sqlcode = A-9 A.20 Sqlcode = A-9 A.21 Sqlcode = A-10 A.22 Sqlcode = A-10 A.23 Sqlcode = A-11 A.24 Sqlcode = A-11 A.25 Sqlcode = A-11 A.26 Sqlcode = A-12 A.27 Sqlcode = A-12 A.28 Sqlcode = A-13 A.29 Sqlcode = A-13 A.30 Sqlcode = A-13 A.31 Sqlcode = A-14 A.32 Sqlcode = A-14 B. Sample COPY Files C. The TDSTCLEAN Transaction C.1 Purpose...C-1 xii 47 A2 14UR Rev03

15 C.2 Transaction Description...C-1 C.3 How To Use...C-2 C.3.1 Description of the "TCLEAN" IDENTs...C-3 C The SPWNT Parameter...C-3 C The IDLET Parameter...C-5 C.3.2 Description of "TCLEAN" transaction KEYWORDs...C-6 C "TCLEAN DISPLAY"...C-6 C "TCLEAN STOP"...C-7 D. The SAMPLE Transaction E. The FETCH Transaction F. The "ORATDS" Transaction G. Specialized Processors G.1 Specialized Processor Specifics...G-1 G.2 TERMINOLOGY For Specialized Processors...G-1 H. Example of the H_XAEVT Transaction I. Error in Commit Phase During TDS Execution Glossary Index 47 A2 14UR Rev03 xiii

16 ORACLE7/TDS User's Guide Table of Graphics Figures 1-1. Two TDS Applications Sharing the Same ORACLE Database A TDS Application Accessing Two ORACLE Databases Two TDS applications Sharing Two ORACLE Databases ORACLE/TDS Development Stages (TDS Side) TDS-XA/ORACLE in the DTP Model xiv 47 A2 14UR Rev03

17 1. Introducing ORACLE/TDS 1.1 Overview Prerequisites The following software products must be present: GCOS 7 as follows: GCOS 7-V6 Technical Status 6150 is required as the basic minimum, GCOS 7-V6 minimum Technical Status 6152 is required to take advantage of the new way to configure the ORACLE/TDS layer (see Section 4), GCOS 7-V7 Technical Status 7458 is required to use ORACLE7/TDS-XA (see Section 7) or Pro*C (see Section 8). ORACLE Version 7 named ORACLE7. The TDS Transaction Monitor Benefits The main benefits of ORACLE/TDS can be summarized as follows: GCOS 7 transactional applications are able to access ORACLE databases. ORACLE/TDS is suitable for departmental production applications (built on an ORACLE database) and complements high throughput transactional applications (built in IDS/II and TDS). The security and reliability of the TDS environment is allied with the flexibility of relational ORACLE data structures. The same TDS application can simultaneously access ORACLE data, IDS/II databases, and UFAS files. A TPR can update either an ORACLE database or IDS/II and UFAS data. 47 A2 14UR Rev03 1-1

18 ORACLE7/TDS User's Guide ORACLE production systems and ORACLE decision support systems can coexist on the same ORACLE database. A single ORACLE database can be accessed simultaneously from IOF, batch, and TDS, and from remote applications via SQL*Net. A much larger number of ORACLE users can be supported under TDS than under IOF. Context caching lets multiple users of a TDS application share a single ORACLE process in the ORACLE database server. Logical connections are retained; physical reconnections are unnecessary Architecture ORACLE/TDS is based on the client/server model, and the two-task architecture of ORACLE. The ORACLE server runs independently of the TDS application. One consequence of this architecture is that several TDS applications can access the same ORACLE database simultaneously. In addition, the SQL*Net facility is available to TDS programmers, enabling a TPR to access several ORACLE databases simultaneously. Figures 1-1, 1-2, and 1-3 show several possible TDS Applications Sharing the Same ORACLE Database@Fig. 0-1@ TDS application number 1 TDS application number 2 ORACLE database server A Figure 1-1. Two TDS Applications Sharing the Same ORACLE TDS Application Accessing Two ORACLE Databases@Fig. 1-2@ A2 14UR Rev03

19 Introducing ORACLE/TDS TDS application number 1 ORACLE database server A ORACLE database server B Figure 1-2. A TDS Application Accessing Two ORACLE TDS applications Sharing Two ORACLE Databases@Fig. 2-3@ TDS application number 1 TDS application number 2 ORACLE database server A ORACLE database server B Figure 1-3. Two TDS applications Sharing Two ORACLE Databases Restrictions The current version of ORACLE/TDS supports both Pro*COBOL and Pro*C. This means that a TDS programmer can use either the Pro*COBOL or the Pro*C precompiler to generate TPRs containing SQL verbs. All the standard Pro*COBOL and Pro*C functions are available. In the TDS environment, however, the CONNECT, COMMIT and ROLLBACK statements do not behave as they do in the IOF environment. All statements that are "autocommitted", such as DDL and DCL statements, must also be used carefully in a TDS environment. See Section A2 14UR Rev03 1-3

20 ORACLE7/TDS User's Guide Otherwise, Pro*COBOL and Pro*C programs written for the TDS environment are fully compatible with the IOF environment. Each code sequence containing SQL statements (but no terminal I/Os) which executes correctly in the TDS environment will execute the same way in the IOF environment. This means that you can test sequences of SQL code in interactive IOF with a test ORACLE database before embedding it in a TPR SQL*NET ORACLE databases accessed from TDS applications may reside on the same (local) system, or on a different (remote) GCOS 7 or UNIX - Bull system. In the second case, ORACLE databases are accessed using SQL*Net. Two SQL*Net versions are available. The first one (SQL*Net V1) is described in the SQL*Net V1 with ORACLE7 User's Guide manual. The second one (SQL*Net V2) is described in the SQL*Net V2 with GCOS 7 User's Guide manual Sharing between TDS, IOF, BATCH ORACLE databases may be shared by several TDS applications, and may simultaneously be shared with IOF or batch jobs ORACLE/TDS with XA Differences applicable to the use of ORACLE/TDS with the X/OPEN DTP model are discussed in Chapter ORACLE/TDS with PRO*C The main part of this manual is written using Pro*COBOL examples. Developers who wish to use Pro*C should refer to Section 8 which discusses the differences applicable to this environment Administration and Maintenance ORACLE databases are maintained with the standard ORACLE tools and are separate from the TDS application. They have their own redo log files and rollback segments A2 14UR Rev03

21 Introducing ORACLE/TDS The administrator has various means available for tuning an ORACLE/TDS system. Later sections of this manual refer to tuning and optimization techniques. Standard ORACLE administrative tasks are fully described in the ORACLE7 Server Administrator's Guide and ORACLE7 Server Addendum Error Codes ORACLE/TDS has a special set of error codes. Appendix A lists them. SQLCODE is set to a negative value from -1 through -31. The accompanying message is preceded by "ORAT-" plus the code. NOTE: Standard ORACLE error messages are preceded by "ORA-". 1.2 Building An Oracle/Tds Subsystem (TDS SIDE) The TDS Generation Program Using ORACLE in your TDS application implies that you inform TDS at Generation Time through the "USE ORACLE" clause in the STDS file. This is the only mandatory change that is to be made in this file; see the description of this clause further on. However, if your system has GCOS 7 Technical Status TS6152 or later, you may use the new way of configuring ORACLE/TDS. In this new way, you can define a block in the STDS file (reserved to ORACLE) to set the ORACLE/TDS configuration parameters at generation time. One of these parameters is DEFAULT_DATABASE that overrides the USE clause. 47 A2 14UR Rev03 1-5

22 ORACLE7/TDS User's Guide The "USE ORACLE" Clause The "USE ORACLE" clause is added as the last entry of the TDS section. This statement can take one of the two following formats: USE ORACLE. The name of the default database is the same as the 4- character TDS application name unless a specific clause has been added in the ORACLE block of the STDS (DEFAULT_DATABASE is <name-50>). The ORACLE block is available only if your GCOS 7-V6 Technical Status is at least TS6152. USE ORACLE-BASE-<name>. The name of the default database is the one specified by <name-50>, unless you specified another DEFAULT_DATABASE in the ORACLE block (only available with GCOS 7-V6 TS6152 or later). NOTE: you must not use a non-alphanumeric character (such as '.') in the <name-50> parameter ORACLE-DEF... ORACLE-ENDDEF Block The features described here may be used only with GCOS 7-V6 TS6152 or later. If you try to use them with an earlier version of GCOS 7, the TDS generation step (TP7GEN) will abort with severity 3, and you will get following message in Xron:2:2 output of this step: "*** UNEXPECTED STATEMENT. LOOK FOR THE NEXT MANDATORY ONE."... The general format of the ORACLE block inside the STDS file ORACLE-DEF <keyword> IS <value> ORACLE-ENDDEF This block must be located after the "INPUT-OUTPUT SECTION" and before the "TRANSACTION SECTION" of the STDS file. The allowed configuration parameters (<keyword>) are the MAXTIM MAXWAT TIMOUT A2 14UR Rev03

23 Introducing ORACLE/TDS CSIZE TRACELVL DEFAULT_DATABASE Section 4 gives all the details on rules of syntax, signification and validity ranges of these parameters (except for DEFAULT_DATABASE). In fact, a specific care is to be taken while using DEFAULT_DATABASE parameter: it sets the default database name for the TDS session, and it cannot be modified through the ORACLE transaction (all the other parameters may be so modified). "DEFAULT_DATABASE IS <name-50>" specified in the ORACLE-DEF... ORACLE-ENDDEF block always overrides the "USE ORACLE" clause. The following table displays the result of different combinations you can GCOS 7-V6 USE Clause ORACLE Block Result ****************************************************************** TS < 6152 USE ORACLE not allowed TDS name TS < 6152 USE ORACLE-BASE-<name> not allowed <name> TS >= 6152 USE ORACLE not used TDS name TS >= 6152 USE ORACLE DEFAULT_DATABASE IS <name> <name> GCOS7 V6 USE ORACLE-BASE-<name> not used TS >= 6152 <name> TS >= 6152 USE ORACLE-BASE-<name1> DEFAULT_DATABASE IS <name2> <name2> ****************************************************************** In the table, the "Result" column shows the name which is actually effective. In the "ORACLE Block" column, "not used" refers to the cases where the block is available but you choose not to use it. As it is much easier to use the "ORACLE-DEF... ORACLE-ENDEF" block, you are strongly recommended to use "DEFAULT_DATABASE IS <name>" instead of "USE ORACLE-BASE-<name>". For example, this allows you to use '.' in the 47 A2 14UR Rev03 1-7

24 ORACLE7/TDS User's Guide database name which can be very important on GCOS 7 as it makes comprehension easier The USE XA Clause A TDS-XA is an application where some transactions call on services provided by XA Resource Managers while others do not. When a transaction wishes to use XA services, the USE XA clause must be specified in the "TRANSACTION SECTION" of the STDS file Example of a STDS File Below is a sample skeleton of the STDS file for a simple ORACLE/TDS TDS SECTION PROGRAM-ID. ORAT. SIMULTANEITY IS 3. RESERVE 10 AREAS. DEFAULT TRANSACTION-STORAGE SIZE IS PRIVATE STORAGE IS MESSAGE-LENGTH IS 9999 MAXIMUM. TPR-TIME-LIMIT IS 5000 MSEC. { USE ORACLE. } { } Optional { USE-ORACLE-BASE-<name-50>. } INPUT-OUTPUT SECTION. *END { ORACLE-DEF } If TS >= TS6152, { MAXTIM IS } this block is optional. { MAXWAT IS } { DEFAULT_DATABASE IS ORNG. } If TS < TS6152, { ORACLE-ENDDEF } this block is not permitted. TRANSACTION SECTION. MESSAGE "SAMPLE" ASSIGN TO SAMPLE AUTHORITY-CODES ARE 0,1. *END MESSAGE "ORACLE" ASSIGN TO ORATDS AUTHORITY-CODES ARE 0,1. *END A2 14UR Rev03

25 Introducing ORACLE/TDS NOTES: 1. The last MESSAGE clause assigns the ORATDS transaction which tunes the ORACLE/TDS interface. See Section 4 and Appendix C. 2. ORACLE in a High Availability environment is not a subject for this manual. See the ORACLE7/TDS-HA User's Guide for HA specifics. If the ORACLE/TDS application is to operate in the HA environment, append the "WATCHED BY CMSC." clause to the PROGRAM-ID clause Preparing TPRs The typical order of events is as follows: 1. Write and test the SQL code sequences using ORACLE under IOF. 2. Write the Pro*COBOL or Pro*C TPRs incorporating the tested SQL statements. 3. Precompile each TPR using PCC (the Pro*COBOL or Pro*C precompiler). Note that Pro*COBOL supports COBOL-85 only. 4. Compile each precompiled TPR using the appropriate COBOL-85 or C compiler. 5. Link the TPRs into a TPR sharable module. 6. Load the TPR sharable module (and the H_ORATDS sharable module if not already done) into backing store, using SYSMAINT. The stages involved on the ORACLE side (SOR, COR, SQL*DBA, H_ORACLE and so on) are summarized at the end of this section and are explained further in Sections 3 and 4 and in the ORACLE7 Installation Guide. If you plan to use SQL*Net V2 you must refer to chapter 3 of the SQL*Net V2 with GCOS 7 User's Guide. Figure 1-4 illustrates the TDS side stages in the development of an ORACLE/TDS Development Stages (TDS Side)@Fig. 3-4@ 47 A2 14UR Rev03 1-9

26 ORACLE7/TDS User's Guide TPRs with embedded SQL PCC precompiler C or COBOL compiler LINKER TDS Generation Program TPR SM Backing Store H_ORATDS SM SYSMAINT TPR Sharable Module TDS Execution H_ORACLE SM Figure 1-4. ORACLE/TDS Development Stages (TDS Side) 1.3 Building AN ORACLE/TDS SUBSYSTEM (ORACLE SIDE) The typical order of events is as follows: 1. Install ORACLE in the standard way following the instructions given in the ORACLE7 Installation Guide. 2. Load the ORACLE sharable modules into backing store: H_ORACLE and H_ORATDS. Follow the standard instructions given in the ORACLE7 Installation Guide. 3. Ensure the ORACLE/TDS specific table called SYS$TDS is available to each ORACLE server. See Section Activate the ORACLE communications server (COR processor) on each site to be accessed. See Section If SQL*Net V2 connections must be available to ORACLE7/TDS, make sure you have access to SQL*Net V2 configuration files and it is advisable to activate one (or more) SQL*Net V2 Adapter (SQLNET_ADAPTER). See Section A2 14UR Rev03

27 Introducing ORACLE/TDS 6. Activate the ORACLE database server, using SOR, for each ORACLE database. See Section Start database activity, using SQL*DBA. See Section 3. The administrator needs to pay attention to the tuning and optimization mechanisms of ORACLE/TDS. See Sections 4 and 5. HA-specific action may be necessary - refer to the ORACLE7/TDS-HA User's Guide for information. 1.4 Migration From ORACLE V ORACLE V6/TDS Applications The H_ORATDS sharable module delivered with ORACLE7/TDS is capable of running Pro*COBOL programs precompiled with version 1.3 ORACLE precompilers. Version 1.3 is the version of ORACLE precompilers delivered with ORACLE V6 on DPS This means that you do not have to re-precompile, recompile, and re-link ORACLE V6/TDS applications to run them with ORACLE7/TDS. However, if you run ORACLE V6/TDS applications in this way, these TDS applications will not benefit from the improvements and new features introduced with version 1.5 of ORACLE precompilers. Version 1.5 is the version of ORACLE precompilers delivered with ORACLE7 on DPS You cannot mix Pro*COBOL programs precompiled with version 1.3 (precompilers) and programs precompiled with version 1.5 (precompilers) in the same TDS application. If the ORACLE/TDS layer detects such a mixed application, the following message is returned to the TDS application: "ORAT-13: Mixing formerly and newly precompilations is forbidden." ORACLE Transactions Note that the following 3 sources delivered with ORACLE V6: ORATDS_COB74T CASTAT_COB74T TCLEAN_COB74T are replaced by the following 3 sources: ORATDS_COBOL CASTAT_COBOL 47 A2 14UR Rev

28 ORACLE7/TDS User's Guide TCLEAN_COBOL for ORACLE7. These are in the SL library created at ORACLE installation on site. These modifications result in an incompatibility between ORACLE7 and the administration transactions generated for ORACLE V6. In order to use these transactions with ORACLE7/TDS, you must re-compile these sources (with the standard COBOL compiler options CARDID = 0, LEVEL = NSTD) and re-link them (with the standard LINKER delivered with GCOS 7). An attempt to use these ORACLE V6 transactions under ORACLE7/TDS (without re-compiling and re-linking them) may cause problems (for example, "EX 0E-01 fault data descriptor") A2 14UR Rev03

29 2. Writing Pro*COBOL TPRs For TDS This section describes how to write TPRs in Pro*COBOL that contain SQL statements. For the differences concerning programmers using Pro*C, see section 8. Specifically, this means: showing the impact on Pro*COBOL programming when the target environment is TDS (and not IOF), the process of embedding SQL statements in COBOL TPRs. The CONNECT, COMMIT, and ROLLBACK statements work differently in an ORACLE/TDS environment. A major part of this section shows, by means of programming examples, how to use these statements. It is assumed that programmers are already familiar with TDS COBOL and with SQL. If necessary, refer to the TDS COBOL Programmer's Guide and the ORACLE7 Server SQL Language Reference Manual. In addition, those who are not already used to writing Pro*COBOL programs for use under IOF must refer to the specific Programmatic Interfaces documentation concerning Pro*COBOL. To build a Pro*COBOL TPR containing SQL statements, the process is the following: write a TPR with SQL statements precompile it using the Pro*COBOL precompiler compile it using the COBOL compiler link it into a TPR sharable module There is therefore an additional step (the precompilation) over and above the normal process of TPR preparation. 2.1 Connecting To Oracle The CONNECT statement is used to log on to an ORACLE database. You can find its detailed description in the "ORACLE Precompilers Programmer's Guide". 47 A2 14UR Rev03 2-1

30 ORACLE7/TDS User's Guide This section only describes how the CONNECT statement works in an ORACLE/TDS environment. The CONNECT statement must be the first executable SQL statement in the TDS commitment unit. Only declarative SQL statements and host language code can logically precede the CONNECT statement The SQL*Net Context Cache Physical Connection Definition A physical connection is a link between the TDS application and the ORACLE server. Data exchanges are executed through this link. It is a connection in two-task mode, as described in the standard ORACLE documentation. A physical connection is identified by its profile which results of the combination of the CONNECT statement parameters: username, password, dbname (SQL*Net syntax to log on to the target database), dbid (logical database identifier specified in the AT clause). Note that the SQL*Net context cache is case sensitive Logical Connection Definition This is a new concept introduced for ORACLE/TDS needs. We can define it as follows: The CONNECT statement acts as a logical connection. The end of a TDS commitment unit (normal or abnormal) acts as a logical disconnection for all the databases connected in the commitment unit. A logical connection is always mapped on a physical connection. A given logical connection is not always mapped on the same physical connection A2 14UR Rev03

31 Writing Pro*COBOL TPRs For TDS SQL*Net Context Definition An SQL*Net context is a set of physical connections to ORACLE databases. One context is associated with one commitment unit. It means that all the connections relative to the same TDS commitment unit are linked to a SQL*Net context cache entry and make up the SQL*Net context. Among all these connections, the first one is very important because it has a great influence on the algorithms of the SQL*Net contexts cache manager. An SQL*Net context cache entry may have one of the three following states: UNUSED: There are no physical connections, the cache entry is just formatted. FREE: There are physical connections on which no logical connections are mapped. BUSY: There are physical connections on which logical connections are mapped Why a SQL*Net Context Cache? ORACLE/TDS maintains a cache of SQL*Net contexts which are used for database connections and cursor parsing. In some cases (see below), contexts can be "shared" by ORACLE/TDS users. Context sharing saves unnecessary physical connections and cursor parsing, and reduces the number of processes in ORACLE servers to service a particular TDS application. There is a consequent reduction in main memory requirements and CPU consumption to support the application How Does the SQL*Net Context Cache Work? 1. Connection Processing Each time a CONNECT statement is executed, the SQL*Net contexts cache manager is called. First CONNECT in a TDS commitment unit: When it is the first CONNECT of a commitment unit, the cache manager tries to retrieve a FREE SQL*Net context cache entry containing a physical connection whose profile matches with the current connection. This search may need two steps: 47 A2 14UR Rev03 2-3

32 ORACLE7/TDS User's Guide If a first scan, focused on the first connection of each SQL*Net context entry, does not retrieve, A second scan occurs: this looks at all the connections of each SQL*Net context. If the search fails, a new SQL*Net context is needed, and has to be allocated. Next CONNECTs of the TDS commitment unit: When it is not the first CONNECT of a commitment unit, the cache manager has to retrieve the SQL*Net context cache entry allocated for the commitment unit during the first CONNECT, and add a new connection entry. 2. SQL*Net context allocation The CSIZE parameter specifies the size of the SQL*Net context cache. If no matching SQL*Net context has been retrieved, a new one has to be allocated. The allocation processing depends on the SQL*Net context cache state as follows: If the cache is not full, a new SQL*Net context is created. If the cache is full but at least one FREE context exists, the oldest FREE context is reassigned. Consequently, all the physical connections associated with this context are broken and the associated cursors are lost. If the cache is full and no FREE context exists, the cache is extended. A new SQL*Net context is created, but the CSIZE value remains unchanged Common Syntax of a CONNECT Statement The common syntax of a CONNECT statement is the EXEC SQL CONNECT :username IDENTIFIED BY :password AT db_name USING :db_string END-EXEC. In the TDS environment, the size of the database identifier used in the AT clause (db_name) as well as the size of host variables involved in the CONNECT statement are limited. The username host variable cannot be declared as a character string larger than PIC X(30). The password host variable cannot be declared as a character string larger than PIC X(20). The db_string host variable cannot be declared as a character string larger than PIC X(50). The db_name identifier cannot be a character string larger than 8 characters A2 14UR Rev03

33 Writing Pro*COBOL TPRs For TDS If one of these limits is exceeded, the following error message is returned to the TDS application: "ORAT-25:Invalid host variable definition." Default Databases and Connections The default Database The default database is the database to which a COBOL program executing a CONNECT statement is connected if an explicit database specification is omitted. Under IOF, the default database has the same name as the user's current working directory, unless an explicit name is specified through the keyword INSTANCE (synonym OWD). Under TDS, as explained in Section 1, the default database is determined by the type of USE clause that appears in the TDS Generation Program The default connection A default connection is made by a CONNECT statement not using an AT clause. SQL statements without an AT clause are executed against the default connection. Conversely, a non-default connection is made by a CONNECT statement using an AT clause. SQL statements with an AT clause are executed against the non-default connection Database Identifiers (SQL*Net) The AT clause specifies a database identifier. 47 A2 14UR Rev03 2-5

34 ORACLE7/TDS User's Guide EXAMPLE: Non-default connection EXEC SQL DECLARE DB1 DATABASE END-EXEC. EXEC SQL CONNECT :USR IDENTIFIED BY :PWD AT DB1 USING :HST END-EXEC. EXEC SQL AT DB1 INSERT INTO T1 VALUES (100) END-EXEC. The database identifier "DB1" is defined in the CONNECT statement to be a symbolic identifier for the database whose access path is contained in the host variable HST. Therefore, you must use an AT clause with each SQL statement which is executed on the DB1 database. In a TDS commitment, you cannot execute an SQL statement referencing a database identifier, before a CONNECT statement referencing the same database identifier is executed. Otherwise, one of the following error messages will be returned to the TDS application: or "ORAT-15:No connected database." "ORAT-16:Not logged on the target database." In a TDS commitment, you can execute two CONNECT statements referencing the same database identifier but they must have the same user identification and the same database access path. For EXEC SQL CONNECT US1 IDENTIFIED BY PWD1 AT DB1 USING HST1... EXEC SQL CONNECT US1 IDENTIFIED BY PWD1 AT DB1 USING HST1 is valid, EXEC SQL CONNECT US1 IDENTIFIED BY PWD1 AT DB1 USING HST1... EXEC SQL CONNECT US2 IDENTIFIED BY PWD2 AT DB1 USING HST2 is not valid. The following error message will be returned to the TDS application: "ORAT-20:Database logical name already used." In the "Programmer's Guide to the ORACLE Precompilers", it is stated that SQL statements using the AT clause (with database identifier) now support the AT :host_variable clause A2 14UR Rev03

35 Writing Pro*COBOL TPRs For TDS Starting from O7320B the SQL statements using the AT clause (CONNECT statement included), now support the AT :host_variable clause. In a TDS environment, the number of distinct database identifiers is limited to 12 for a COBOL program (not including the default connection). At execution time, the following error message will be returned to a TDS application which run a COBOL program using more than 12 distinct database identifiers. "ORAT-27:Maximum number of database identifiers exceeded." The SQL*Net Syntax for Connecting The communicating points in a network are called nodes. SQL*Net lets you transmit information over the network from one node to another. The general syntax for connecting to a database { [<prefix>:][<node>:]<instance-name> } { <alias> } <prefix> supported under ORACLE7/TDS are "D:" (SQL*Net V1 ISO/DSA) and "T:" (SQL*Net V1 TCP/IP). <node> refers to the remote system supporting the database to connect to ($<system-name> for ISO/DSA connections, <system-name> for TCP/IP connections). <instance-name> is a character string which identifies a database server. For a server running on DPS 7000, it corresponds to the INSTANCE name of the database server (INSTANCE name of database servers can be displayed by using the LIST_SVR command - refer to the ORACLE7 Guide to Processor and Utilities). For a server running on UNIX, it corresponds to the ORACLE SID of the database server. <alias> refers to an SQL*Net V2 alias. The general syntax for connecting to the default database on the local node is: [D:] The general syntax for connecting to a non-default database on the local node is: [D:]<instance-name> The general syntax for connecting a non-default database on a remote node is: 47 A2 14UR Rev03 2-7

36 ORACLE7/TDS User's Guide or or [D:]$<system-name>:<instance-name> T:<system-name>:<instance-name> <alias> In a TDS environment, it is not possible to connect to a default database on a remote node. Conflicts between notations like and <instance-name> <alias> are solved according to the following rule: if it runs, on the local node, a database server with an INSTANCE name equal to the <instance-name> or <alias> string (checking case-sensitive), connection will be made to this local server. if not, the <instance-name> or <alias> string will be interpreted as an SQL*Net V2 alias to be resolved. In a TDS environment, only the "D:" and "T:" driver prefixes are supported. If another prefix or a bad prefix is used, the following error message will be returned to the TDS application: "ORAT-31: unsupported driver prefix" Concerning the "T:" driver prefix, only connection to Bull platforms are allowed. A try to connect to other platforms will return the following error message to the TDS application: "ORAT-29: Connection to remote host failed (unsupported machine)" EXAMPLE OF EXEC SQL DECLARE DB1 DATABASE END-EXEC. EXEC SQL CONNECT :USR IDENTIFIED BY :PWD AT DB1 USING :HST END-EXEC A2 14UR Rev03

37 Writing Pro*COBOL TPRs For TDS For a database located on the same machine, running under the name ORA7DB, the HST variable must contain, for example, the string "D:ORA7DB" (or simply, "ORA7DB"). For a database located on a remote system named ARE2, running under the name ORA7DB, the HST variable must contain "D:$ARE2:ORA7DB". For a database located on a remote system named DPX210, running under the ORACLE SID ORADPX, the HST variable must contain "T:DPX210:ORADPX". If HST contains the string "MY_DB": if it runs on the same machine, a database server with an INSTANCE name equal to MY_DB, connection will be tried against this server; otherwise, MY_DB will be interpreted as an SQL*Net V2 alias described in a TNSNAMES_ORA configuration file Automatic Logons Usually, you establish a connection to ORACLE as EXEC SQL CONNECT :username IDENTIFIED BY :password END-EXEC. or you can use the statement: EXEC SQL CONNECT :userpwd END-EXEC. To use the automatic logon, you declare the userpwd host variable as a PIC X(1) COBOL datatype and initialize it with a slash (/) character. In this case, you automatically log on to ORACLE with the userid OPS$username. In a TDS environment, username is the identifier, specified at TDS logon, of the user who started the COBOL program containing the automatic logon. If this identifier is more than 8 bytes, the name is truncated. For example, if you connect to TDS as ORAOPER15, you connect to ORACLE as OPS$ORAOPER1 (because of the truncation). Be careful when using the automatic logon feature under TDS. Each time a new TDS user starts a COBOL program containing such a logon, a physical connection to ORACLE is established. 47 A2 14UR Rev03 2-9

38 ORACLE7/TDS User's Guide Automatic Restart The automatic restart facility has some effect on the visibility of the CONNECT statement. In most cases, a commitment unit will complete correctly after several retries. You can specify the maximum time during which a failed commitment can be retried (see Section 4). However, sometimes it is possible that a commitment unit fails definitely. If the failure occurs at commit time, it cannot be notified synchronously to the user's program. Therefore, the commitment is restarted and an error is returned to the TPR (reporting that the CONNECT statement has failed) EXEC SQL CONNECT Errors SQLCODE values which can be returned on a CONNECT statement relate to: failures during the connection phase, failures during the commit phase. Remedial action depends on the precise nature of the error. The returned SQLCODE value provides information to cater for each eventuality. CONNECT statements may cause particular SQLCODE errors in a TDS environment. See Appendix A. A simple way of handling SQLCODE errors is to abort the current transaction. A CONNECT statement in a Pro*COBOL TPR may fail with the following error message: "ORAT-12:No vacant processes. Retry later." This means that the basic ORACLE database server does not have enough processes. Use the SOR A command to increase the number of processes, as described in Section Commitments When a Pro*COBOL program runs in a TDS environment, all commitment units are managed by TDS as far as possible. Information relative to the state of the ORACLE commitment are stored in the TDS swap file and in the SYS$TDS table of the database (to commit). It is used to A2 14UR Rev03

39 Writing Pro*COBOL TPRs For TDS provide the state of the ORACLE database (committed or not) if TDS restarts the commitment unit. This has the following important consequences: The explicit commitment of an ORACLE database through the EXEC SQL COMMIT statement is deferred to the end of the TPR regardless of where the commit request appears in the code. Only one ORACLE database is committed when TDS actually commits. Any other ORACLE databases are rolled back (see paragraph 2.3.5). Note that in the following cases, no consistency between TDS and ORACLE commitments is ensured because TDS does not know that ORACLE commits: The COBOL program executes an SQL statement which is autocommitted. The COBOL program executes a PL/SQL block containing a COMMIT statement. The COBOL program executes a stored procedure, a package, or a trigger containing a COMMIT statement. In each of these 3 cases, if TDS restarts the commitment unit, updates to ORACLE databases may be executed twice. Another important difference between the TDS and IOF environments is that when a TPR actually commits, all the databases connected in the commitment unit are logically disconnected. See paragraph It is as if a COMMIT WORK RELEASE statement had been executed simultaneously for each connected database. No more SQL statements can be executed until a CONNECT statement is issued. See paragraph The various commit options and commit behaviours are illustrated in the examples that follow Using Implicit Commitment The IMPLICIT COMMITMENT function of TDS defines the end of each TPR preceding a terminal conversation as the end of a commitment unit. EXAMPLE: Using implicit commitment If the IMPLICIT COMMITMENT function of TDS is used, the CONNECT statement and the INSERT statement are executed, and are committed as soon as the TPR 47 A2 14UR Rev

40 ORACLE7/TDS User's Guide IDENTIFICATION DIVISION. PROGRAM-ID. CMT1.... EXEC SQL CONNECT :USR IDENTIFIED BY :PWD END-EXEC. EXEC SQL INSERT INTO T1 VALUES (100) END-EXEC.... SEND CD-OUT FROM SND-BUFF WITH EGI.... EXIT PROGRAM Using CALL "DFCMIT" The CALL "DFCMIT" procedure requests a commitment to be taken at the end of the TPR A2 14UR Rev03

41 Writing Pro*COBOL TPRs For TDS EXAMPLE: Using a commitment (CALL IDENTIFICATION DIVISION. PROGRAM-ID. CMT2.... EXEC SQL CONNECT :USR IDENTIFIED BY :PWD END-EXEC.... EXEC SQL INSERT INTO T1 VALUES (100) END-EXEC.... CALL "DFCMIT".... EXEC SQL INSERT INTO T2 VALUES (101) END-EXEC.... EXIT PROGRAM. In this case, the two INSERT statements are committed together after the TPR ends, whether or not the IMPLICIT COMMITMENT function of TDS is used. As the execution of the TDS commit requested through the statement CALL "DFCMIT" is deferred to the end of the TPR, the TPR "CMT2" is functionally equivalent to the following one IDENTIFICATION DIVISION. PROGRAM-ID. CMT2-LIKE.... EXEC SQL CONNECT :USR IDENTIFIED BY :PWD END-EXEC.... EXEC SQL INSERT INTO T1 VALUES (100) END-EXEC.... EXEC SQL INSERT INTO T2 VALUES (101) END-EXEC.... CALL "DFCMIT".... EXIT PROGRAM Using the COMMIT Statement The COMMIT statement can be used instead of the TDS statement CALL "DFCMIT" to request TDS to commit at the end of the current TPR. 1. EXEC SQL COMMIT WORK END-EXEC. 47 A2 14UR Rev

42 ORACLE7/TDS User's Guide It commits the database associated with the default connection regardless of where the COMMIT statement appears. 2. EXEC SQL AT <db> COMMIT WORK END-EXEC. It commits the specified database regardless of where the COMMIT statement appears. The RELEASE option associated with the COMMIT statement is not supported in the TDS environment. Whether you specify RELEASE or not, the behaviour of the COMMIT statement is the same; it does not free resources and it does not log off the database. EXAMPLE: Using the SQL COMMIT statement The following TPR "CMT3" is equivalent to "CMT2-LIKE" (shown previously): IDENTIFICATION DIVISION. PROGRAM-ID. CMT3.... EXEC SQL CONNECT :USR IDENTIFIED BY :PWD END-EXEC.... EXEC SQL INSERT INTO T1 VALUES (100) END-EXEC.... EXEC SQL INSERT INTO T2 VALUES (101) END-EXEC.... EXEC SQL COMMIT WORK END-EXEC.... EXIT PROGRAM Automatic Disconnection from ORACLE After COMMIT The TDS commitment unit acts as a logical disconnection of all the databases of the SQL*Net context. EXAMPLE: Disconnection Look at the following TPRS ("BEGCMT4" and A2 14UR Rev03

43 Writing Pro*COBOL TPRs For TDS IDENTIFICATION DIVISION. PROGRAM-ID. BEGCMT4.... EXEC SQL CONNECT :USR IDENTIFIED BY :PWD END-EXEC.... EXEC SQL INSERT INTO T1 VALUES (100) END-EXEC.... SEND CD-OUT FROM SND-BUFF WITH EGI MOVE "ENDCMT4" TO NEXT-TPR EXIT PROGRAM. IDENTIFICATION DIVISION. PROGRAM-ID. ENDCMT EXEC SQL INSERT INTO T1 VALUES (101) END-EXEC EXEC SQL COMMIT WORK END-EXEC EXIT PROGRAM. These two TPRs will execute correctly as long as the IMPLICIT COMMITMENT function of TDS is not used. Otherwise, an implicit commitment takes place after the execution of the TPR "BEGCMT4", and you are disconnected from the ORACLE database. The INSERT statement in the TPR "ENDCMT4" fails since you are no longer connected to the ORACLE database. If you need to commit the ORACLE database at the end of the TPR "BEGCMT4" (using an implicit or explicit commit), then you must put another CONNECT statement at the beginning of the TPR "ENDCMT4". This will restore the connection to the database and ensure that the INSERT statement does not fail due to previous disconnection. 47 A2 14UR Rev

44 ORACLE7/TDS User's Guide So, if the TPR "ENDCMT4" is modified as shown below, the two TPRs will always execute sequentially as required, even if no commit occurs at the end of the TPR "BEGCMT4". IDENTIFICATION DIVISION. PROGRAM-ID. ENDCMT EXEC SQL CONNECT :USR IDENTIFIED BY :PWD END-EXEC EXEC SQL INSERT INTO T1 VALUES (101) END-EXEC EXEC SQL COMMIT WORK RELEASE END-EXEC EXIT PROGRAM Each TDS Commitment Commits Only One ORACLE Database When TDS commits, only one of the connected ORACLE databases is committed; all other ORACLE databases are rolled back. By default, when no COMMIT statement is used, the TPR commits the target ORACLE database of the last SQL statement to be executed. If two ORACLE databases have to be committed, use different TPRs (or different executions of the same TPR) and update only one ORACLE database per TPR. See paragraph The two examples that follow are intended to illustrate the way that commitments work. EXAMPLE: Default commitment The following TPR "CMT5" updates two ORACLE databases: the default database, and the database whose identification is contained in the host variable HST (referenced by the symbol DB1). IDENTIFICATION DIVISION. PROGRAM-ID. CMT A2 14UR Rev03