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

45 Writing Pro*COBOL TPRs For TDS... EXEC SQL CONNECT :USR IDENTIFIED BY :PWD END-EXEC. EXEC SQL CONNECT :USR IDENTIFIED BY :PWD AT DB1 USING :HST END-EXEC. EXEC SQL INSERT INTO T1 VALUES (100) END-EXEC. EXEC SQL AT DB1 INSERT INTO T2 VALUES (100) END-EXEC. CALL "DFCMIT". EXIT PROGRAM. At the end of the TPR, only the database DB1 is committed because this is the database on which the last statement was executed. The default database is rolled back, and the corresponding INSERT statement is lost. To override the default, you use the COMMIT WORK statement. This forces a commitment on the database you wish to commit and not on the last one accessed. EXAMPLE: Using the COMMIT WORK statement In the following example, the COMMIT WORK statement forces a commitment on the default database, even if the last statement in the TPR refers to a different IDENTIFICATION DIVISION. PROGRAM-ID. CMT5.... EXEC SQL CONNECT :USR IDENTIFIED BY :PWD END-EXEC. EXEC SQL CONNECT :USR IDENTIFIED BY :PWD AT DB1 USING :HST END-EXEC. EXEC SQL INSERT INTO T1 VALUES (100) END-EXEC. EXEC SQL AT DB1 INSERT INTO T2 VALUES (100) END-EXEC. 47 A2 14UR Rev

46 ORACLE7/TDS User's Guide EXEC SQL COMMIT WORK END-EXEC. EXIT PROGRAM. A commitment is taken by the COMMIT WORK statement on the default database (that is, the one which has no AT clause). When several ORACLE databases are connected, we recommend using the COMMIT WORK statement instead of the standard CALL "DFCMIT" or the IMPLICIT COMMITMENT option of TDS Commit Separate Databases in Separate TPRs If several COMMIT WORK statements applying to several different ORACLE databases are executed within the same TPR, the following error message will be returned to the TDS application after the execution of the second COMMIT WORK statement: "ORAT-17:Commit on several databases not allowed" In this case, the only database that is committed is the one referenced by the first COMMIT statement (unless a ROLLBACK is requested to rollback all the databases). If two ORACLE databases have to be committed, commit them in separate TPRs (or in different executions of the same TPR). EXAMPLE: Commit two databases by taking the commitments in separate TPRs: The TPR "CMT5" (shown previously) is split into two separate TPRs "UPD1" and "UPD2". Connection, insertion, and commitment are performed separately for each database. This is the recommended way to perform IDENTIFICATION DIVISION. PROGRAM-ID. UPD1.... EXEC SQL CONNECT :USR IDENTIFIED BY :PWD END-EXEC A2 14UR Rev03

47 Writing Pro*COBOL TPRs For TDS EXEC SQL INSERT INTO T1 VALUES (100) END-EXEC. EXEC SQL COMMIT WORK END-EXEC. MOVE "UPD2" TO NEXT-TPR. EXIT PROGRAM. IDENTIFICATION DIVISION. PROGRAM-ID. UPD2.... EXEC SQL CONNECT :USR IDENTIFIED BY :PWD AT DB1 USING :HOST END-EXEC. EXEC SQL AT DB1 INSERT INTO T2 VALUES (100) END-EXEC. EXEC SQL AT DB1 COMMIT WORK END-EXEC. EXIT PROGRAM. EXAMPLE: Update two databases by writing a "two path" TPR An alternative to using two separate TPRs to update two ORACLE databases is to write a "two-path" TPR where the paths are mutually exclusive and where each path is determined by the current value of a switch variable. The TPR "CMT6" sequentially updates two ORACLE databases. The TPR will execute twice, producing two commitment units updating one database each. The TPR uses a switch variable to determine which database is to be updated and IDENTIFICATION DIVISION. PROGRAM-ID. CMT6.... IF PHASE = 2 GO TO UPD2. EXEC SQL CONNECT :USR IDENTIFIED BY :PWD END-EXEC. 47 A2 14UR Rev

48 ORACLE7/TDS User's Guide UPD2. EXEC SQL INSERT INTO T1 VALUES (100) END-EXEC. EXEC SQL COMMIT WORK END-EXEC. MOVE 2 TO PHASE. MOVE "CMT6" TO NEXT-TPR. GO TO END-OF-TPR. EXEC SQL CONNECT :USR IDENTIFIED BY :PWD AT DB1 USING :HST END-EXEC. EXEC SQL AT DB1 INSERT INTO T2 VALUES (100) END-EXEC. EXEC SQL AT DB1 COMMIT WORK END-EXEC. MOVE 1 TO PHASE. MOVE ALL SPACES TO NEXT-TPR. END-OF-TPR. EXIT PROGRAM. "PHASE" is a numeric variable used as a switch. It is declared in TRANSACTION-STORAGE and initialized to EXEC SQL COMMIT Errors COMMIT statements may cause certain errors in a TDS environment. See Appendix A. Failures during the commit phase (at TPR TERM) induce the restart of the TDS commitment unit, in order to notify errors to the TDS application on every CONNECT statement of the commitment unit. See Appendix A. 2.3 Rollback The various rollback options are illustrated in the examples that follow A2 14UR Rev03

49 Writing Pro*COBOL TPRs For TDS The ROLLBACK Statement The ROLLBACK statement is always executed synchronously; that is, it is not deferred to the end of the current TPR. ROLLBACK affects only the ORACLE database to which it is applied - either the default ORACLE database or a specific one (using the AT clause). ROLLBACK does not affect the processing of the current TPR, updates made to another ORACLE database, or subsequent updates made to the same database. 1. EXEC SQL ROLLBACK WORK END-EXEC. This rolls back the database associated with the default connection. It is executed synchronously. The TPR can continue; another database can be committed. 2. EXEC SQL AT <db> ROLLBACK WORK END-EXEC. This rolls back the ORACLE database specified by <db> only. It is executed synchronously. The TPR can continue; another database can be committed. The RELEASE option associated with the ROLLBACK statement is not supported in a TDS environment. The COMMIT statement behaves in the same way with or without the RELEASE option, that is, COMMIT does not free resources and it does not log off the database. EXAMPLE: ROLLBACK The two examples that follow are intended to illustrate the way that rollback works. The TPR "ROL1" rolls back the first update to the default ORACLE database, but commits the second update. The ROLLBACK statement is executed synchronously, so the first INSERT statement is immediately rolled back. The processing of the current TPR continues; the second INSERT statement is executed, a commitment is requested, and finally, at the end of the TPR, the second INSERT is IDENTIFICATION DIVISION. PROGRAM-ID. ROL1.... EXEC SQL CONNECT :USR IDENTIFIED BY :PWD END-EXEC. EXEC SQL INSERT INTO T1 VALUES (100) END-EXEC. EXEC SQL ROLLBACK WORK END-EXEC. EXEC SQL INSERT INTO T2 VALUES (101) END-EXEC. EXEC SQL COMMIT WORK END-EXEC. 47 A2 14UR Rev

50 ORACLE7/TDS User's Guide EXIT PROGRAM. The TPR "ROL2" connects to the default database, and to an other database DB1. A value is inserted into a table on each database. The ROLLBACK statement refers, by default, to the default database. The COMMIT WORK statement commits the update on database IDENTIFICATION DIVISION. PROGRAM-ID. ROL2.... EXEC SQL CONNECT :USR IDENTIFIED BY :PWD END-EXEC. EXEC SQL CONNECT :USR IDENTIFIED BY :PWD AT DB1 USING :HST END-EXEC. EXEC SQL INSERT INTO T1 VALUES (100) END-EXEC. EXEC SQL AT DB1 INSERT INTO T2 VALUES (101) END-EXEC. EXEC SQL ROLLBACK WORK END-EXEC. EXEC SQL AT DB1 COMMIT WORK END-EXEC. EXIT PROGRAM The TDS "ROLL-BACK" Primitive The TDS "ROLL-BACK" procedure rolls back the transaction to the first TPR of the current commitment unit. It undoes work done on all the ORACLE databases of the SQL*Net context since the last commitment. Such a rollback is managed by TDS, and is immediate. TPR processing is interrupted; the transaction is restarted after the rollback. Such a rollback induces a logical disconnection of all the databases of the SQL*Net context A2 14UR Rev03

51 Writing Pro*COBOL TPRs For TDS EXAMPLE: Using the TDS CALL "ROLL-BACK" primitive If the TPR "ROL3" detects an <abnormal-condition> - for example, some data has been modified by another user so that the context of the current TPR is no longer valid - the TPR issues a CALL "ROLL-BACK" to request all the work done since the last commit to be undone. This triggers a rollback of all the databases of the SQL*Net context, and each one is logically disconnected. When TDS restarts TPR execution (to try to perform the processing again), the Pro*COBOL statements are executed again as if for the first IDENTIFICATION DIVISION. PROGRAM-ID. ROL3.... EXEC SQL CONNECT :USR IDENTIFIED BY :PWD END-EXEC. EXEC SQL INSERT INTO T1 VALUES (100) END-EXEC.... IF <abnormal-condition> CALL "ROLL-BACK".... EXEC SQL COMMIT WORK END-EXEC. EXIT PROGRAM The TDS "INVCMIT" Primitive The TDS "INVCMIT" procedure invalidates the current commitment unit. It forces a rollback on all the ORACLE databases of the SQL*Net context, instead of a commit at the next commitment point. In this case, the TPR is not restarted. The processing continues with the next TPR. Execution of a CALL "INVCMIT" statement does not mean that the end of TPR is a commitment point. 47 A2 14UR Rev

52 ORACLE7/TDS User's Guide If you execute an EXEC SQL COMMIT statement and a CALL "INVCMIT" statement in the same TPR, the TDS commitment and consequently the ORACLE commitment will be invalidated at the end of the TPR The TDS "NOCMIT" Primitive The TDS "NOCMIT" procedure cancels the commitment action at the end of the current TPR, unless the TPR is the last TPR of the transaction. The CALL "NOCMIT" cancels any EXEC SQL COMMIT statement called beforehand in the same TPR FOR DEBUG Clause You can specify the FOR DEBUG clause in the MESSAGE statement of the TRANSACTION SECTION of the STDS. This is used to denote the transactions which are to be debugged. DEBUG mode affects the connected ORACLE databases in the following way: at each commitment point of a transaction which is FOR DEBUG, the ORACLE databases are rolled back instead of being committed, just as for UFAS files or IDS/II databases. 2.4 Data Definition Statements Data Definition statements (DDL) are used to define, maintain, and drop database objects (such as tables or views). DDL statements are "autocommitted". This makes them tricky to use in a TPR containing DML statements. Their use can lead to the desynchronization of commitments between TDS and the corresponding ORACLE database server. If you have to use DCL or DDL statements in a TDS application, we strongly recommend you to issue them within a separate commitment unit (which implies a separate TPR). Otherwise, DML statements may easily be committed by a DCL or DDL command. The consequent risk is that the DML might be executed more than once if the TPR fails before it has completed, and is then restarted. NOTE: Use of DDL statements in TPRs is not forbidden, and is not checked at runtime A2 14UR Rev03

53 Writing Pro*COBOL TPRs For TDS EXAMPLE: DDL and DML statements in the same TPR This TPR "DDL1" could desynchronize commitments. The DDL statement CREATE TABLE is issued (and carries out a commitment) before the INSERT statement is supposed to be IDENTIFICATION DIVISION. PROGRAM-ID. DDL1.... EXEC SQL CONNECT :USR IDENTIFIED BY :PWD END-EXEC. EXEC SQL INSERT INTO T1 VALUES (100) END-EXEC. EXEC SQL CREATE TABLE T2 (X NUMBER) END-EXEC. EXEC SQL COMMIT WORK END-EXEC.... EXIT PROGRAM. EXAMPLE: DDL and DML statements in separate TPRs The TPRs "DDL2" and "DDL3" are executed sequentially; there is no risk that the INSERT statement will be executed more than IDENTIFICATION DIVISION. PROGRAM-ID. DDL2.... EXEC SQL CONNECT :USR IDENTIFIED BY :PWD END-EXEC. EXEC SQL INSERT INTO T1 VALUES (100) END-EXEC. EXEC SQL COMMIT WORK END-EXEC. MOVE "DDL3" TO NEXT-TPR A2 14UR Rev

54 ORACLE7/TDS User's Guide EXIT PROGRAM. IDENTIFICATION DIVISION. PROGRAM-ID. DDL3.... EXEC SQL CONNECT :USR IDENTIFIED BY :PWD END-EXEC. EXEC SQL CREATE TABLE T2 (X NUMBER) END-EXEC. EXEC SQL COMMIT WORK END-EXEC.... EXIT PROGRAM. NOTE: In both previous examples, the CREATE statement may be executed twice or more if the TPR executing this statement fails before taking a successful commitment. Bear this in mind each time you include a DDL statement in a TPR. In the above examples, SQLCODE may be set after the execution of the CREATE statement to a value indicating that the table already exists even though it did not exist before the first execution of the TPR. 2.5 Handling Runtime Errors This section intends to describe specifics and restrictions of error reporting in the ORACLE/TDS environment. For more details concerning error handling, you may refer to Chapter 7 of the "ORACLE Precompilers Programmer's Guide". Starting from O7340A some ORACLE/TDS error codes are replaced by ORACLE error codes. So you must use the WHENEVER SQLERROR clause to be sure to detect all possible errors A2 14UR Rev03

55 Writing Pro*COBOL TPRs For TDS Using the WHENEVER Statement You code the WHENEVER statement using the following syntax: EXEC SQL WHENEVER <condition> <action> END-EXEC In the ORACLE/TDS environment, the STOP action is not supported. If you use it, you will have an abort of the TPR (return code: TP7 2, USEREQ) if the condition is met Using the ORACLE Communications Area (ORACA) Two entry points: ORASTAT and GETSTM may be called from a COBOL program to get a subset of information recorded in the ORACA structure. The ORASTAT entry point which provides information about cursor cache statistics is discussed in Section 4. The GETSTM entry point helps you find faulty SQL statements. To use GETSTM, you define the following variables in the 01 MESS-BUFF PIC X(70). 01 BUFF-SIZE PIC S9(9) COMP MESS-LGT PIC S9(9) COMP-2. If connected to ORACLE, you can call GETSTM using the where MOVE 70 TO BUFF-SIZE. CALL "GETSTM" USING MESS-BUFF, BUFF-SIZE, MESS-LGT MESS-BUFF BUFF-SIZE MESS-LGT is the text buffer in which you want ORACLE to store the SQL statement in error. is an integer variable that specifies the maximum size of the buffer in bytes. is an integer variable in which ORACLE stores actual length of the SQL statement in error. Notice that GETSTM has to be called only when a SQL error has occurred. Always make sure SQLCODE is negative before calling GETSTM. If you call 47 A2 14UR Rev

56 ORACLE7/TDS User's Guide GETSTM, before being connected or when SQLCODE is zero, the text buffer may be filled with blank characters or you can get a prior invalid SQL statement. 2.6 Precompiling, Compiling And Linking Precompiling a Pro*COBOL TPR To precompile a Pro*COBOL TPR, use PCC (the PreCompiler, Common). This is described in the ORACLE7 Guide to Processors and Utilities. With ORACLE7 and version 1.5 of the precompilers, there is no difference at precompiler level, between precompiling a Pro*COBOL program for TDS and precompiling for IOF and batch. EXAMPLE: Using PCC to precompile a TPR S: PCC INAME=MYDIR.SL..MYTPR HOST=COBOL; Successful precompilation produces an output source file named MYTPR_PCC in the MYDIR.SL library. This file must then be compiled by the COBOL-85 compiler (see further on) Compiling a Pro*COBOL TPR There is no difference at compiler level between compiling a Pro*COBOL program for TDS, and compiling for IOF or batch. Refer to the ORACLE7 Guide to Processors and Utilities for the standard descriptions. But there are two special GCOS 7 compilation options which must be specified with the COBOL 85 compilers. They are: LEVEL=NSTD CARDID=0 This is because PCC sometimes generates non-standard COBOL statements, and produces an output source file in raw format A2 14UR Rev03

57 Writing Pro*COBOL TPRs For TDS EXAMPLE: Compiling a Pro*COBOL TPR To compile the TPR MYTPR_PCC, enter: S: CBL MYTPR_PCC MYDIR.SL LEVEL=NSTD CARDID=0; Linking a Pro*COBOL TPR There is no difference at linkage level between linking a Pro*COBOL program for TDS, and linking for IOF or batch. Refer to the ORACLE7 Guide to Processors and Utilities for full details. There are no special statements for TDS to be added at link time. The only difference for TDS is that the subfile created by the TDS generation step (TP7LINKTPR) must be used to link all the TPRs of a TDS application. The ORACLE_LNK subfile which contains LINKER statements for ORACLE batch programs is not used. EXAMPLE: Linking a Pro*COBOL TPR S: LK MYPGID SM COMFILE=MYTDS.SLLIB..TP7LINKTPR OUTLIB=MYTDS.SMLIB; The above example assumes that the file MYTPR contains MYPGID as COBOL program identification Example of JCL stream generating a Pro*COBOL TPR This example shows a JCL stream that calls PCC to precompile a Pro*COBOL TPR, calls the GCOS 7 COBOL 85 compiler to compile it, and calls LINKER to link it. The complete JCL stream is retained to help 1 $JOB SAMPLE HOLDOUT CLASS=B; 2 MVL MD1=DACV05 DVC1=MS/D500 3 ORADIR=ORA7 4 OWD=ORA7DB 5 LDIR=APPLI 6 MSGDIR=ORA7 47 A2 14UR Rev

58 ORACLE7/TDS User's Guide 7 LANGUAGE=AMERICAN 8 TDS=OTDS 9 FORMAT=ANSI 10 TPR=SAMPLE; 11 OVL BANINF=(GENERATION,&TPR,&USER,QTX---V7); 12 COMM '************************************************'; 13 COMM '*** GENERATION JOB FOR SQL/COBOL TPR ***'; 14 COMM '************************************************'; 15 PCC: 16 JOBLIB SM &ORADIR.SM; 17 STEP H_OR_PC0 &ORADIR.LM DUMP=NO 18 OPTIONS=&OWD'/'&LDIR'/'&MSGDIR'/'&LANGUAGE'/* INAME='&LDIR'.SL..'&TPR' 19 FORMAT='&FORMAT' 20 INCLUDE='&ORADIR'.SL 21 USERID=PHAM/PHA 22 IRECLEN=132 ORECLEN=132 PAGELEN=56; 23 SIZE 100; 24 ENDSTEP; 25 JUMP COB SEV LT 3; 26 SEND 'SAMPLE: STEP PCC ABORTED TPR= '&TPR'!'; 27 JUMP ABORT; 28 COB: 29 LIB SL INLIB1=&LDIR.SL; 30 COBOL SOURCE=&TPR!!_PCC 31 MAP, 32 XREF,ILN 33 LEVEL=NSTD,NCARDID, 34 CULIB=&LDIR.CU; 35 JUMP LNK SEV LT 3; 36 SEND 'SAMPLE: STEP COBOL ABORTED TPR= '&TPR'!'; 37 JUMP ABORT; 38 LNK: 39 JUMP CONTINUE; 40 LINKER &TPR,SM; 41 INLIB=&LDIR.CU 42 OUTLIB=&LDIR.SM 43 COMFILE=(&TDS.SLLIB MD=&MD1 DVC=&DVC1 SUBFILE=TP7LINKTPR) ; 44 JUMP EXIT SEV LT 3; 45 SEND 'SAMPLE: STEP LINKER ABORTED TPR= '&TPR'!'; 46 ABORT: 47 JUMP CONTINUE; 48 LET SW1 1; 49 IV SAVEJOR OTI.COMMON.JCL VL=(,&LDIR.WORK,JOR_SAMPLE); 50 EXIT: 51 JUMP END SW1 EQ 0; 52 SEND 'CHECK JOR_SAMPLE IN LIB=&LDIR.WORK'; 53 LET SEV 3; 54 END: 55 $ENDJOB; A2 14UR Rev03

59 3. Running an ORACLE/TDS Application To run an ORACLE/TDS application, four preparatory steps are necessary in addition to the standard TDS preparation: Ensure that the GCOS 7-specific file TDS_SQL is executed at database creation time. Activate the ORACLE communications server(s) using COR. Start the ORACLE database server(s) using SOR and SQL*DBA. Load the H_ORATDS module into backing store. This section describes these four steps. The standard ORACLE installation procedures, including the loading of the H_ORACLE and H_ORATDS sharable modules, is described in the ORACLE7 Installation Guide. If using ORACLE in a TDS-HA environment, you will need the ORACLE7/TDS-HA User's Guide. 3.1 The Tds_Sql File To use the ORACLE/TDS facilities via an ORACLE server, the ORACLE database needs a special table: SYS$TDS. This table is described in the member TDS_SQL (which is provided in the standard ORACLE delivery kit). After the database has been created, use SQL*Plus or SQL*DBA (note in this case the file must be processed under the SYS user-id) to execute the contents of the TDS_SQL script. For example: 3.2 The Oracle Communications Server (Cor) A TDS application cannot access an ORACLE database unless the ORACLE communications server (COR) is active. 47 A2 14UR Rev03 3-1

60 ORACLE7/TDS User's Guide If you plan to use SQL*Net V2 connections from your ORACLE/TDS application, ensure that your site is correctly configured for using SQL*Net V2 (configuration files,...) Furthermore, use of an SQL*Net V2 Adapter is recommended (refer to chapter 3 of the SQL*Net V2 with GCOS 7 User's Guide) Starting COR To start the ORACLE communications server, use the COR command from any IOF terminal: S: COR I; COR starts a batch job which issues a message as soon as the server is ready Stopping COR To stop the ORACLE communications server, use the COR command again: S: COR S; NOTE: This does not terminate existing ORACLE communications instantly, but it prevents new ones from being established. 3.3 The Oracle Database Server ORACLE database servers are managed independently of the TDS applications from which they are accessed Starting ORACLE Starting ORACLE involves two distinct stages: Launching the database server with the SOR command. Starting database activity with the SQL*DBA processor. For instructions, refer to the ORACLE7 Guide to Processors and Utilities A2 14UR Rev03

61 Running an ORACLE/TDS Application Adding Extra Connections 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. The number of available user processes of ORACLE should be equal to the number of contexts of the SQL*NET cache, determined by the CSIZE value. See the relevant chapters for the SQL*NET context cache and CSIZE. You can use the SOR A command to increase the number of processes of the ORACLE server. For instructions, refer to the ORACLE7 Guide to Processors and Utilities Stopping ORACLE Stopping ORACLE involves two distinct stages: Shutting down the database with the SQL*DBA processor. Stopping database activity with the SOR command. For instructions, refer to the ORACLE7 Guide to Processors and Utilities. If the TDS application is still running, you must dynamically disable the connections between TDS users and the database server by using the ORACLE transaction with TERM option. 3.4 The H_Oratds Sharable Module The H_ORATDS sharable module is a component of the ORACLE/TDS run-time package. It is the interface between ORACLE and TDS, and is packaged in the standard ORACLE delivery kit. Load H_ORATDS into backing store before the TDS application is started so that it is accessible to the TDS application load module at run-time. To carry out the loading process, include a STEP in the JCL that launches the TDS application. A JOBLIB SM statement must also be present which specifies the Sharable Module library where H_ORATDS has been installed, as well as the one or two other Sharable Module libraries where the TPRs reside. 47 A2 14UR Rev03 3-3

62 ORACLE7/TDS User's Guide EXAMPLE: The JCL below shows how the H_ORATDS and TPR sharable modules are loaded into backing store. The TDS name is ORAT, and the H_ORATDS sharable module is packaged in the ORA7.ST sys.system file. The H_ORATDS and TPR sharable modules are reloaded each time the job is launched. There can be three SMLIBs with the JOBLIB statement. $JOB ORAT; $SYSMAINT COMFILE=*LDSM SIZEOPT=(500); $INPUT LDSM JVALUES; INSST ORA7.ST; SM; LOAD SM=H_ORATDS REPLACE; QUIT; $ENDINPUT; $SYSMAINT COMFILE=*LDTPR SIZEOPT=(500); $INPUT LDTPR JVALUES; SM; INLIB1 ORAT.SMLIB; INLIB2 ORAT.SMLIB2; LOAD SM=TPR INLIB1 INLIB2 REPLACE; QUIT; $ENDINPUT; $JOBLIB SM ORAT.SMLIB ORAT.SMLIB2 ORA7.ST; $STEP ORAT (ORAT.LMLIB) REPEAT DUMP=DATA; $SIZE 300 POOLSIZE=50 NBBUF=120; $ASSIGN DBUGFILE ORAT.DEBUG FILESTAT=CAT SHARE=DIR; $ASSIGN H_BJRNL MD=550U50 DVC=MS/D500 FILESTAT=TEMPRY NEXT POOL; $DEFINE H_CTLM JOURNAL=BEFORE; $ENDSTEP; $ENDJOB; NOTE: You can use the MODIFY_TDS Master Terminal command to dynamically switch the Sharable Module library order of priority A2 14UR Rev03

63 Running an ORACLE/TDS Application 3.5 Tds Error Messages Relating To Oracle MU86. ORACLE INITIALIZATION FAILED Meaning: Action: The SM containing ORACLE is not loaded; or the correct library is not specified in the JOBLIB statement. Ensure that the SM containing ORACLE is loaded; or ensure that the correct library is specified in the JOBLIB statement. MU87. ERROR DETECTED IN ORACLE/TDS PROTOCOL Action: None - internal error. 47 A2 14UR Rev03 3-5

64 ORACLE7/TDS User's Guide A2 14UR Rev03

65 4. Tuning ORACLE/TDS: Configuration Parameters The configuration parameters of the ORACLE/TDS layer are used to tune the access to ORACLE databases for the current application. Once initialized (either at TDS generation time or at first launching of the TDS, depending on GCOS 7 technical status (see further on)), they can be dynamically modified through the "ORACLE" transaction. The current configuration parameters available with your ORACLE7/TDS version are : MAXTIM MAXWAT TIMOUT CSIZE TRACELVL DEFAULT_DATABASE (not dynamically updatable) For details on validity range or exact signification of each of these parameters, refer to the corresponding paragraph in the "ORACLE" transaction description. 4.1 Setting Configuration Parameters At Generation Time Starting with GCOS 7 Technical Status 6152, a new interface between TDS and ORACLE/TDS is provided. This makes ORACLE/TDS more independent from TDS. It is possible to modify, add or suppress ORACLE/TDS configuration parameters without having to wait for the next GCOS 7 Technical Status. With this new interface, the TDS or ORACLE administrator is able to set ORACLE/TDS configuration parameters by manipulating an ORACLE reserved block in the STDS file. The dynamic changes of the configuration parameters values will remain visible until the next COLD restart of TDS; at that time, the values will return to those set at TP7GEN time. 47 A2 14UR Rev03 4-1

66 ORACLE7/TDS User's Guide GCOS 7 Technical Status Earlier than TS6152 If the Technical Status of your GCOS 7 is earlier than TS6152 (that is, < TS6152), you cannot use this new visibility. In this case: Do not change your STDS. Otherwise, the TP7GEN step aborts, and you get the message "*** UNEXPECTED STATEMENT. LOOK FOR THE NEXT MANDATORY ONE" in the Xron:2:2 output of this step. Note that dynamically changed values are lost at warm restart. GCOS 7 Technical Status TS6152 or Later If the Technical Status of your GCOS 7 is at least TS6152 (that is, >= TS6152), you can choose to use the new facility or not to use it. If you choose not to use the new facility: Your old STDS file will be supported as it is: no change is necessary. In that case, values for the configuration parameters will be default values: the visibility remains the same as for ORACLE V6. These values are: MAXTIM = 20000, MAXWAT = , TIMOUT = 20000, CSIZE = 16, TRACELVL = 1. Dynamically changed values will in any case remain valid until next TDS COLD restart. Note that at the first COLD restart after a TDS generation, you will get a warning message during the startup phase of your TDS: MU08 Xxxx.3 TDS : <tds-name> WARNING, REASON : ERROR WHILE ACCESSING RECORD IN TDS SYSTEM FILE RC=B >XUFAS 81,RECNFD A TDS previously used with ORACLE V6/TDS must be stopped/started with the COLD option. Otherwise the startup phase will be aborted with the error message: MU08 Xxxx.3 TDS : <tds-name> FATAL ABORT, REASON : ORACLE INITIALIZATION FAILED RC=B >XUFAS 81,RECNFD This is due to the new interface between TDS and ORACLE7/TDS. ORACLE tries to read the record corresponding to the ORACLE block in the STDS. As A2 14UR Rev03

67 Tuning ORACLE/TDS: Configuration Parameters this record does not exist (because there is no such block), a WARNING is issued. If you choose to use the new facility, then you can start your ORACLE7/TDS application with configuration values different from the default values. In that case, use the new facility of ORACLE block in the STDS file. You set the values in the ORACLE block using the usual STDS syntax: The ORACLE block starts with "ORACLE-DEF". The ORACLE block ends with "ORACLE-ENDDEF". The ORACLE block must be located after the INPUT-OUTPUT section and before the TRANSACTION-SECTION. Inside the block, you must follow a few rules: each line must use the following format: <keyword> IS <value>. use one line for each value: for example, you may not write MAXTIM IS MAXWAT IS but write instead: MAXTIM IS MAXWAT IS you should end each line with one point ('.') you may use lowercases as well as uppercases. As soon as a syntax error is detected in one line, the analysis is stopped and TP7GEN results in an error. None of the lines preceding and following the erroneous line is taken into account. In case of error, the JOR of the TDS generation indicates: "STD 1, OPTERR" and scanning of the Xron:2:2 output will give you the reason of the error. For example, with a STDS file as below: ORACLE-DEF MAXTIM IS 40. MAXWAT IS the following error message will be recorded in the Xxx:2:2 of the TP7GEN step: ORACLE-DEF MAXTIM IS 40. MAXWAT IS ORACLE-ENDDEF TG75-*** ERRONEOUS PARAGRAPH:ORACLE-DEF..ORACLE- ENDDEF 47 A2 14UR Rev03 4-3

68 ORACLE7/TDS User's Guide Value out of bounds for parameter: MAXTIM The usage of the DEFAULT_DATABASE parameter is not the same as the other parameters. It cannot be updated through the "ORACLE" transaction and interacts with the "USE ORACLE" clause of the STDS; all details are given in the paragraph 1.9 of Chapter 1 of this guide. IMPORTANT NOTE: You must launch your TP7GEN step with the value of the keyword ORASTLIB set to the SMLIB which contains the H_ORATDS Sharable Module. 4.2 Setting Configuration Parameters Dynamically Transaction Description The ORACLE/TDS configuration parameters visible just after first startup of your TDS application may be dynamically modified through the "ORACLE" transaction. If your Technical Status is TS6152 or later (that is, >= TS6152), these dynamic changes will be lost at warm restart. Otherwise (new interface starting with TS6152, see preceding paragraph), they will remain valid until next COLD restart. The "ORACLE" transaction is associated with the ORATDS_COBOL program. This program is delivered with your ORACLE7 version. This transaction is used to dynamically tune the ORACLE/TDS interface. It implements the call to an entry point named ORATCONF in the ORACLE/TDS sharable module H_ORATDS. This entry point interacts with TDS to effectively change the configuration parameters and make them remain until the next COLD restart (if TS >= TS6152) How to Use ORATDS To use ORATDS, assign the "ORACLE" message to the ORATDS linkage unit in the TDS Generation Program. Add the following lines to the TRANSACTION SECTION of the STDS member: MESSAGE "ORACLE" ASSIGN TO ORATDS AUTHORITY-CODES ARE 0,1. *END A2 14UR Rev03

69 Tuning ORACLE/TDS: Configuration Parameters The ORACLE transaction has several parameters for tuning the ORACLE/TDS interface. These parameters may be divided into two categories: IDENTs and KEYWORDs. IDENTs IDENTs are used to update values in the corresponding fields of the TDSSEG. The syntax for these parameters must include an "=", for example MAXWAT = Both uppercase and lowercase letters are accepted. The IDENTs accepted are listed below: MAXTIM, MAXWAT, TIMOUT, CSIZE, TRACELVL. KEYWORDs KEYWORDs represent an action to be taken, such as enable/disable connection to ORACLE Databases from the TDS application. Both uppercase and lowercase letters are accepted. The KEYWORDs accepted are listed below: DISPLAY, ENABLE, DISABLE, TERM, WAIT, TRACEON, TRACEOFF, TRACE. All these parameters are described separately below. Restrictions 47 A2 14UR Rev03 4-5

70 ORACLE7/TDS User's Guide The following restrictions apply to the syntax that you may use after the "ORACLE" transaction name. It is forbidden to mix parameters of the two categories. For example, you may not specify: ORACLE MAXTIM = 2000 ENABLE Neither of the parameters will be taken into account. You cannot specify two different actions at the same time. For example, "ORACLE ENABLE DISPLAY" is rejected neither action is done. However, you can set two (or more) different idents in the same transaction call, as long as your line does not exceed 80 useful characters (i.e. not including "ORACLE "). Note that if an error is detected in any of the idents, none of the idents is taken into account Description of the "ORACLE" Transaction Parameters After each modification of one of the configuration parameters, all of them are displayed upon the terminal MAXTIM Parameter The MAXTIM parameter specifies the maximum time in milliseconds allowed for an SQL statement to execute. The variable provided for this parameter must be of type PIC S9(9) COMP-2. If the execution of an SQL statement takes more than MAXTIM to execute, the current ORACLE operation is cancelled, the commitment unit is rolled back, and the TDS transaction is aborted. The return code issued is "ORACLE 38, TIMEOUT". Setting MAXTIM The default value is milliseconds. The minimum value is 1000 milliseconds. The maximum value is milliseconds. The default value of MAXTIM is the same as the default value of TIMOUT (see below). If the value of MAXTIM is no greater than the value of TIMOUT, the A2 14UR Rev03

71 Tuning ORACLE/TDS: Configuration Parameters deadlock detection mechanism of TIMOUT with automatic rollback is never used since the value of MAXTIM takes precedence. If MAXTIM is set to 0, the current value is left unchanged MAXWAT Parameter The MAXWAT parameter specifies the maximum time a TPR can wait to reestablish an ORACLE connection that has been lost during the commit phase. The variable provided for this parameter must be of type PIC S9(9) COMP-2. Setting MAXWAT The default value is milliseconds. The minimum value is milliseconds. The maximum value is milliseconds. MAXWAT should be set to a value which corresponds to the maximum time the ORACLE database may be unavailable; that is, at least for the duration of a warm restart of the ORACLE database. It is also advisable to add the time necessary to restore and roll forward the database after a disk crash. If this parameter is set to 0, the current value is left unchanged. MAXWAT Exceeded When TDS does not succeed in connecting to an ORACLE server after MAXWAT milliseconds, an error is returned (on the CONNECT statement of the TPR) through SQLCODE -6 ("Unrecoverable Timeout error"). In that case, the status of the ORACLE data remain unknown for the current commitment unit (they may have been committed or rolled back). Specific action to recover this error depends on the application: if the Commitment Unit did not modify any ORACLE data, SQLCODE=-6 should be processed as a simple CONNECT failure (no risk of data being damaged). if data has been modified, abort the C.U. and check data in the database. 47 A2 14UR Rev03 4-7

72 ORACLE7/TDS User's Guide TIMOUT Parameter TIMOUT specifies the maximum time a TPR is allowed to wait for a non-available resource in an ORACLE database. It is used to detect deadlocks between databases. The variable provided for this parameter must be of type PIC S9(9) COMP-2. When the timeout event occurs, the current ORACLE operation is cancelled, the commitment unit is rolled back, and then restarted. Setting TIMOUT The default value is milliseconds. The minimum value is 1000 milliseconds. The maximum value is milliseconds. If TIMOUT is set to 0, the current value is left unchanged CSIZE Parameter The CSIZE parameter specifies the number of ORACLE contexts which can be cached by the ORACLE/TDS interface. This can help optimize the performance of ORACLE/TDS applications. Setting CSIZE The default value for CSIZE is 16. Minimum value is -1. This indicates that no ORACLE context is cached. Maximum value is If set to 0, the current value is left unchanged. In the Job Occurrence Report (JOR) of the ORACLE/TDS session you will find statistics relating to the ORACLE/TDS cache. These will help in determining an optimum value for CSIZE. Changing the value of CSIZE may have direct consequences to the performance of your TDS application. So, you must be aware of the fact that: Reducing the CSIZE value reduces the number of ORACLE/TDS contexts cached. Then, "x" cache entries will be destroyed (where x = actual cache size - new CSIZE). This results in the physical disconnection of all connections A2 14UR Rev03

73 Tuning ORACLE/TDS: Configuration Parameters entries linked to each of these cache entries. The deleted cache entries are the oldest FREE entries. Setting CSIZE to -1 disconnects all FREE entries in the cache, which allows the shutdown of the accessed ORACLE servers without stopping your TDS application (cache size is reduced to 0). For more information on ORACLE/TDS context caching, please refer to Chapter TRACELVL Parameter This parameter specifies the TRACE level. There are two different trace levels: 1. the TRACE mechanism is not activated, 2. the basic TRACE mechanism is on. ORACLE/TDS events are traced. 3. detailed; SQLNET events are also traced. When you use "ORACLE TRACEON", the TRACELVL is set to 1. When you use "ORACLE TRACEOFF", the TRACELVL is set to Tracefile Parameter Starting from O7340A the trace file processing has change: using the ORACLE transaction a user can specify a trace file which will be written in the «TDSname.SLLIB»: trace file name will be of the form «subfilename_trc» - command to issue is: ORACLE TRACEFILE = subfilename[_trc] it is possible to change trace file during the TDS session by issuing a new ORACLE transaction command. This, first close the current subfilename_trc and then, opens the new one if a trace level is active and no trace file mentioned ORACLE7 opens the ORACLE_TRC subfile in the «TDSname.SLLIB». the new TRACELVL accepted values are: 0: no trace active, 2: minimum level of trace active, -1: (minus one) maximum level of trace active. 47 A2 14UR Rev03 4-9

74 ORACLE7/TDS User's Guide Description of KEYWORDs "ORACLE DISPLAY" This keyword displays the values of all configuration parameters on terminal console. It also displays the status of the communication between the TPR and the ORACLE server. ************************************************************ * ORA/TDS Configuration * * * * MAXTIM = * * MAXWAT = * * TIMOUT = * * CSIZE = * * TRACELVL = ************************************************************ * ORA/TDS Layer status * * * * ORA/TDS communication ready * ************************************************************ "ORACLE ENABLE" If the communication with the ORACLE server has ceased, this keyword allows new connections to be established (by unsetting one bit). This function does not wait for the COR to be ready. If there is no COR, a return code NOINIT is produced, and following message is ************************************************************* * ORA/TDS Layer status * * * * ORA/TDS Communication not available: COR server not ready * ************************************************************* A2 14UR Rev03

75 Tuning ORACLE/TDS: Configuration Parameters If you want to wait for the COR on your connection, see the keyword "WAIT" further on. When communication is established, you get: ************************************************************* * ORA/TDS Layer status * * * * ORA/TDS communication ready * ************************************************************* "ORACLE DISABLE" You may use this keyword if you want to prevent new connections to be established to the ORACLE server. The cache is not cleaned, and existing connections are not stopped. A status on established connections is given: if all connections are stopped when you ask for DISABLE action, you ************************************************************** * ORA/TDS Layer status * * * * All ORA/TDS connections stopped;new connections prohibited * ************************************************************** if there are still connections, you ************************************************************** * ORA/TDS Layer status * * * * Oracle connections still alive; New connections prohibited * ************************************************************** "ORACLE TERM" This keyword permits you to: 47 A2 14UR Rev

76 ORACLE7/TDS User's Guide terminate all connections to the ORACLE servers, prevent new connections (in the same way as the DISABLE keyword), disable communication with the COR by terminating the session. You may have to wait until all commitment units are terminated before disconnecting. In that case, you will get: ************************************************************** * ORA/TDS Layer status * * * * Waits for users disconnection * ************************************************************** Once all users are disconnected, you ************************************************************** * ORA/TDS Layer status * * * * ORA/TDS communication disabled * ************************************************************** "ORACLE WAIT" This does the same as "ORACLE ENABLE", except that it waits for the COR to be ready (if it is not ************************************************************** * ORA/TDS Layer status * * * * Wait for ORA/TDS communication to be ready * ************************************************************** A2 14UR Rev03

77 Tuning ORACLE/TDS: Configuration Parameters "ORACLE TRACEON" This keyword permits to switch on the System Trace mechanism. ************************************************************** * ORA/TDS Layer status * * * * ORA/TDS trace level is 1 : basic * ************************************************************** "ORACLE TRACEOFF" This keyword permits to switch off the trace ************************************************************** * ORA/TDS Layer status * * * * ORA/TDS trace mode is off * ************************************************************** "ORACLE TRACE" This keyword displays the status of the System Trace mechanism: basic, detailed, off. You get one of the two preceding messages, ************************************************************** * ORA/TDS Layer status * * * 47 A2 14UR Rev

78 ORACLE7/TDS User's Guide * ORA/TDS trace level is 2 : detailed * ************************************************************** if the trace level has been set to detailed through "ORACLE TRACELVL=2". 4.3 Oracle/Tds Statistics Job Occurrence Report Statistics Statistics are displayed in the Job Occurrence Report (JOR) of the TDS application when the TDS application terminates. The information concerns: The SQL*Net context cache, Memory consumption, The cursor cache. Below is the set of statistics displayed in the ************************************************************** * ORACLE/TDS STATISTICS * * * **** Contexts Cache statistics **** * * * Cache Size (last value): : * * Nb of CTX Ent Used : Nb of XA CTX Ent Used : * * Nb of CTX Ent Reassign : Nb of Physical Connects: * * * **** Memory statistics **** * * * Nb of Used Small Segs : Nb of Used Large Segs : * * Total Memory Used (Kb) : Limit Nb of Small Segs : * * * **** Cursor statistics **** * * * Nb of Open Cursors : Nb of Cursor Reassign : * * Nb of Stmt parses : Nb of Stmt executions : * ************************************************************** A2 14UR Rev03

79 Tuning ORACLE/TDS: Configuration Parameters The meaning of these statistics is as follows: Cache Size Nb of CTX Ent Used Nb of XA CTX Ent Used Nb of CTX Ent Reassign Nb of Physical Connects Nb of Used Small Segs Nb of Used Large Segs Total Memory Used Limit Nb of Small Segs Nb of Open Cursors Nb of Cursor Reassign Nb of Stmt parses This gives the value of the CSIZE parameter at the time the TDS application stops. The maximum number of simultaneously valid SQL*Net contexts in the cache during the TDS session. A valid SQL*Net context is one which contains at least one physical connection to an ORACLE server. As defined in section 2, it is a FREE or a BUSY SQL*Net context. The maximum number of simultaneously valid SQL*Net XA contexts in the cache during the TDS session. See Section 7 for more details on XA. The number of FREE SQL*Net contexts which have been reassigned. All the physical connections of such a context are broken before establishing new connections with different profiles. This indicates the number of physical connections to ORACLE servers which have been established during the TDS session. This indicates the number of 64K segments which have been used by the ORACLE/TDS layer during the TDS session. This indicates the number of large segments which have been used by the ORACLE/TDS layer during the TDS session. This indicates the memory consumption in Kbytes of the ORACLE/TDS layer. This indicates the number of small segments which can be used before memory allocation takes place in large segments. This indicates the number of cursors used during the TDS session. This indicates the number of cursor reassignments during the TDS session. This indicates the number of SQL statements parsed, during the TDS session. 47 A2 14UR Rev

80 ORACLE7/TDS User's Guide Nb of Stmt executions This indicates the number of SQL statements executed. For performance purposes, some of the counters associated with the above statistics are updated without locking any resources. For this reason, those statistics may be a little inaccurate The CASTAT Transaction The CASTAT transaction is used to dynamically display statistics on the SQL*Net context cache and the memory consumption. Source of the transaction is delivered in the standard ORACLE kit. The name of the source program is CASTAT_COBOL. To use CASTAT: compile the CASTAT_COBOL program, link it in the TPR sharable module, and assign the "CASTAT" message to the CASTAT linkage unit in the STDS file of your TDS application. Below is the set of statistics displayed by the CASTAT ************************************************************** ******* ORA/TDS Statistics ******* * * * ORA/TDS Version : * * Context Cache Size : * * Nb of Busy Entries : * * Nb of Free Entries : * * Nb of Busy XA Entries : * * Nb of Free XA Entries : * * Nb of Reassigned Entries: * * Nb of Small segments : * * Nb of Large segments : * * Memory Used (Kbytes) : * ************************************************************** The meaning of these statistics is as follows: ORA/TDS Version Context Cache Size Version of the H_ORATDS sharable module used by the TDS application This gives the current value of the CSIZE parameter A2 14UR Rev03

81 Tuning ORACLE/TDS: Configuration Parameters Nb of Busy Entries Nb of Free Entries Nb of Busy XA Entries Nb of Free XA Entries Nb of Reassigned Entries Nb of Small Segments Nb of Large Segments Total Memory Used This value gives the current number of SQL*Net contexts in the cache which are associated with a commitment unit in execution. This value gives the current number of SQL*Net contexts in the cache which contain one or more valid connections to ORACLE servers, but which are not associated with a commitment unit in execution. This value gives the current number of SQL*Net XA contexts in the cache which are associated with a commitment unit in execution. See Section 7 for more details concerning XA. This value gives the current number of SQL*Net XA contexts in the cache which contain one or more valid connections to ORACLE servers, but which are not associated with a commitment unit in execution. See Section 7 for more details concerning XA. This value gives the current number of FREE SQL*Net contexts which have been reassigned. All the physical connections of such a context are broken before establishing new connections with different profiles. This indicates the current number of 64K segments which are used by the ORACLE/TDS layer. This indicates the current number of large segments which are used by the ORACLE/TDS layer. This indicates the current memory consumption, in Kbytes, of the ORACLE/TDS layer. 4.4 Setting MAXOPENCURSORS VIA THE "SETMXC" ENTRY POINT There is an entry point called "SETMXC" in the H_ORATDS sharable module. This allows you to reduce the value of the MAXOPENCURSORS parameter for all the TPRs of your TDS application without re-precompiling, compiling and linking your application MAXOPENCURSORS With SETMXC When connecting to the ORACLE server, the following algorithm is used to set the value of MAXOPENCURSORS to be associated with the physical connection: 47 A2 14UR Rev

82 ORACLE7/TDS User's Guide MAXOPENCURSORS = MINIMUM { MAXOPENCURSORS (SETMXC), MAXOPENCURSORS (tpr), 500 (H_ORATDS limit) } MAXOPENCURSORS Without SETMXC If SETMXC is not used, MAXOPENCURSORS is set as MAXOPENCURSORS = MINIMUM { MAXOPENCURSORS (tpr), 500 (H_ORATDS limit) } Using SETMXC To use SETMXC, define the following variables in the 77 I-MAXOPCURS PIC S9(9) COMP O-RTCD COMP-2. To call SETMXC, use the COBOL CALL statement: CALL "SETMXC" USING I-MAXOPCURS O-RTCD Return codes are as O-RTCD = 0 O-RTCD = -1 successful execution ORACLE/TDS structures not initialized O-RTCD = -2 invalid value - must be 0 through A2 14UR Rev03

83 Tuning ORACLE/TDS: Configuration Parameters 4.5 Getting Cursor Statistics Via The "Orastat" Entry Point The ORACLE Communications Area (ORACA) is not supported in the TDS environment. In the H_ORATDS sharable module, there is an entry point "ORASTAT" which provides information about the cursor cache statistics. This information is usually recorded in the ORACA structure. ORASTAT puts information into the ORACATDS structure described in the member ORACATDS_CBL which is delivered in the ORACLE SL library. The information in ORACATDS is equivalent to that contained in the ORACLE Communications Area (ORACA). We can consider the ORACATDS structure to be a subset of the standard ORACA. ORACATDS provides information about the following: cursor cache statistics a program's use of ORACLE resources The ORACATDS Structure Layout The ORACATDS structure has the following 01 ORACATDS. Logical database identifier. 05 DBID PIC X(8). 05 DBID-LG PIC S9(9) COMP-2 VALUE ZERO. Cursor cache statistics. 05 ORAHOC PIC S9(9) COMP-2 VALUE ZERO. 05 ORAMOC PIC S9(9) COMP-2 VALUE ZERO. 05 ORACOC PIC S9(9) COMP-2 VALUE ZERO. 05 ORANOR PIC S9(9) COMP-2 VALUE ZERO. 05 ORANPR PIC S9(9) COMP-2 VALUE ZERO. 05 ORANEX PIC S9(9) COMP-2 VALUE ZERO. 47 A2 14UR Rev

84 ORACLE7/TDS User's Guide The meaning of the cursor cache statistics is as follows: ORAHOC ORAMOC ORACOC ORANOR ORANPR ORANEX The maximum number of ORACLE cursors that can be simultaneously opened. It represents the value of the MAXOPENCURSORS parameter that was taken into account at connection time. The maximum number of cursors requested during an ORACLE session (associated with a physical connection). The value may be higher than ORAHOC if MAXOPENCURSORS was set too low, which forced PCC to extend the cursor cache. The current number of used cursors. The number of cursor cache reassignments required by a TPR. The number should be kept as low as possible - it represents the amount of "thrashing" going on in the cursor cache. The number of SQL statements parsed. The number of SQL statements executed. Keep the ratio of this number to ORANPR as high as possible to avoid unnecessary reparsing Using ORASTAT Make a call to ORASTAT from a TPR as EXEC SQL INCLUDE SQLCA END-EXEC. EXEC SQL INCLUDE ORACATDS END-EXEC.... MOVE "MYDBID" TO DBID IN ORACATDS. MOVE 6 TO DBID-LG IN ORACATDS. CALL "ORASTAT" USING SQLCA ORACATDS A2 14UR Rev03

85 Tuning ORACLE/TDS: Configuration Parameters The SQLCA and ORACATDS structures must be declared outside the Declare Section of the program. To recap, SQLCA handles standard SQL communications; ORACATDS handles ORACLE/TDS communications. If the TPR executes correctly, the fields in the ORACATDS structure are initialized. You should call ORASTAT: every time a CONNECT statement is issued, at the end of the TPR. When a connection is only logical, cursors from previous TPR executions remain available for use - as we saw earlier in this section. In this case, when you call ORASTAT after a CONNECT statement, the information in ORACATDS is still there from the previous execution(s). So information about the resources used by the current TPR execution are obtained by taking the difference between the endof-tpr statistics and the connection-time statistics. If a TPR issues several connections, you can define an ORACATDS_CBL type file for each connection. Each file declares a new ORACATDS type structure which can be passed as a parameter to ORASTAT. The name of the structure (the 01 level) must of course be different for each file. Before calling ORASTAT, you must initialize the DBID and DBID-LG fields with (respectively) the logical database connection identifier and the length of that identifier. If (as is the default) there is no logical identifier at connection time, you just need to move 0 to DBID-LG. The DBID-LG field is already initialized to 0 in the delivered file ORACATDS_CBL. For more on SQLCA and how to diagnose error conditions, refer to the standard ORACLE precompiler documentation. 47 A2 14UR Rev

86 ORACLE7/TDS User's Guide A2 14UR Rev03

87 5. Optimizing ORACLE/TDS Applications Optimization techniques can lead to significantly improved performance from an ORACLE/TDS application. This section covers the following: Sizing the ORACLE context cache. Commitments. User-ids with TDS. CONNECT statements. Other ORACLE optimization techniques. 5.1 Sizing The Oracle Context Cache The ORACLE context cache must be correctly sized to get the best performance from your TDS application. The size is specified by the CSIZE parameter which was introduced in Section 4. Optimizing the value of CSIZE for a given TDS application involves counting the number of distinct database-id/database-name/user-id combinations which are used in all TPRs of the TDS application. This number is named DBUSRID. The optimal value of CSIZE is equal to: CSIZE = DBUSRID * Maximum number of simultaneous active commitment units Of course, calculating the number of simultaneous active commitment units is not very easy. Thus, to set the CSIZE, we defined several algorithms according to the type of transaction (simple or complex). Various cases are dealt with in this section. Look at the following examples to compute DBUSRID. 47 A2 14UR Rev03 5-1

88 ORACLE7/TDS User's Guide EXAMPLE 1: If your application contains the following TPRs: TPR1 connecting to database ORAT with user-id SCOTT and database-id DB1 TPR2 connecting to database ORAT with user-id SCOTT and database id DB1 TPR3 connecting to database ORAT with user-id SYSTEM and database id DB1 then the number of distinct database-id/database-name/user-id combinations is 2. The combinations are: DB1/ORAT/SCOTT DB1/ORAT/SYSTEM EXAMPLE 2: If your application contains the following TPRs: TPRA connecting to database ORAT with user-id SCOTT and database id DB1. TPRB connecting to database TDSO with user-id SCOTT and database id DB1. TPRC connecting to database TDSO with user-id SYSTEM and database id DB1. TPRD connecting to database TDSO with user-id SYSTEM and database id DB1. TPRE connecting to database TDSO with user-id SYSTEM and database id DB2. In this case, the number of distinct database-id/database-name/user-id combinations is 4. The combinations are: DB1/ORAT/SCOTT DB1/TDSO/SCOTT DB1/TDSO/SYSTEM DB2/TDSO/SYSTEM A2 14UR Rev03

89 Optimizing ORACLE/TDS Applications Sizing Simple Transactions Here, we define a simple transaction as one where each conversation with a user's terminal is preceded by a commitment. This is a very common occurrence. It prevents a user from holding a resource for longer than necessary. To calculate an optimal value for CSIZE in this case, we need only DBUSRID and the simultaneity level of the TDS application (SIMU). Use the following algorithm: Algorithm: CSIZE = DBUSRID * SIMU EXAMPLE: Simple Transaction A TDS application contains three different transactions T1, T2, and T3. These all connect to ORACLE and commit ORACLE data within a single TPR without any terminal conversation. They all connect to ORACLE using a specific user-id; the simultaneity level of the TDS application is 5. So in this case we have: DBUSRID = 3 SIMU = 5 Therefore: CSIZE = 3 * 5 (which makes 15) Notice that in this case the number of transactions has no impact on CSIZE Sizing Complex Transactions A complex transaction can be defined simply as one where a commit is not executed before each terminal conversation. Since a commit has not been executed, the ORACLE context remains busy during the whole terminal conversation. This may take a rather long time, and this context cannot be re-used by another user. 47 A2 14UR Rev03 5-3

90 ORACLE7/TDS User's Guide Definition: We define the think-time of terminal users as THINK. Think-time is the total time elapsed in seconds between the time the CONNECT statement is executed and the time the next COMMIT statement is executed for the same database. Definition: We define the time interval which elapses between two executions of the same transaction by the same user as INTER. Definition: We define the number of terminal users as USERS. Algorithm: To calculate an optimal value for CSIZE in this case, we need to know the average think-time for each user. Use the following algorithm: CSIZE = (DBUSRID * USERS * THINK) / (INTER + THINK) EXAMPLE: Complex Transaction A TDS application contains a single TDS transaction T1. T1 comprises two screens containing fields which are filled by the terminal user. The following takes place: the user enters the TDS transaction name T1. This triggers the execution of the first TPR TPR1 which connects to the ORACLE database, makes some updates, and sends the first screen to the user's terminal. The user thinks for 30 seconds, fills in the form and presses ENTER. This triggers the execution of a second TPR TPR2 which checks against data in the ORACLE database and sends back a second screen to the user's terminal. The user verifies the data, fills a validation field which takes 15 seconds, and presses ENTER again. This in turn triggers the execution of a third TPR TPR3 which makes final updates to the ORACLE database and commits. The terminal user might then talk to a customer for 5 minutes before entering the transaction name T1 again for the next operation A2 14UR Rev03

91 Optimizing ORACLE/TDS Applications The number of terminals connected to the application is 100. Depending on the data entered on the first screen, the TPR that connects to ORACLE may use 5 different ORACLE user-id's. The example gives us the following information: THINK = 45 seconds ( ) INTER = 300 seconds (5 minutes) USERS = 100 DBUSRID = 5 Therefore: CSIZE = (5 * 100 * 45) / ( ) (making 66) Sizing Combined Simple and Complex Transactions For a TDS application containing both simple and complex transactions, calculate the optimal value of CSIZE separately for each type of transaction. Effectively, this means for each type of commitment unit, since a TDS transaction may contain several commitment units. First compute the optimal value for commitment units where no terminal conversation takes place between the connection to ORACLE and the next commitment. Use the method described above in Sizing Simple Transactions. Then, compute the optimal value for commitment units where a terminal conversation does take place between the connection to ORACLE and the next commitment. Use the method described above in Sizing Complex Transactions. Add the two results. The values of DBUSRID used in the two methods may be different because distinct commitment units can connect to ORACLE under distinct user-id's. Algorithm: The final formula is: CSIZE = (DBUSRID1*SIMU) + (DBUSRID2*USERS*THINK)/(INTER+THINK) SUMMARY: 47 A2 14UR Rev03 5-5

92 ORACLE7/TDS User's Guide The methods described here should provide a good estimate of the optimal CSIZE value for a given situation. As with all optimization techniques, however, you may have to experiment a little to tune a particular application finely. Look at the "Nb CTX Ent Reassign" statistic in the JOR of your TDS application. Try to keep its value as low as possible to get the best performance. Ideally, its value should be equal to Terminal Conversation Committing Before Each Terminal Conversation As we have seen above, the number of commitment units that are simultaneously active determines both the number of ORACLE contexts to be managed, and the number of processes that the ORACLE servers need. If possible, therefore, take a commitment before each terminal conversation: ORACLE processes in the database server can then be re-used by other users. If the entire application takes commitments before each terminal conversation, the number of ORACLE contexts and the number of ORACLE processes required in the ORACLE database server do not depend on the total number of TDS application users Handling Cursors You can use terminal conversation between each fetch execution to fetch from a cursor. This means: execute a fetch in the TPR give the user the selected database tuples loop back and do another fetch... and so on To do this, write a TPR which loops on itself until an end-of-fetch condition is detected. WARNING: Do not commit between each fetch execution! This is because a commit would disconnect you from the database. A commitment is taken only when an end-of fetch condition is reached. This frees the ORACLE context and makes it available to other users A2 14UR Rev03

93 Optimizing ORACLE/TDS Applications EXAMPLE: Looping until end-of-fetch condition The TPR "SELT1" loops on itself until an end-of-fetch condition is met: IDENTIFICATION DIVISION. PROGRAM-ID. SELT1.... IF PHASE = 2 GO TO SENDNEXT. EXEC SQL CONNECT :USR IDENTIFIED BY :PWD END-EXEC. EXEC SQL DECLARE C1 CURSOR FOR SELECT X FROM T1 END-EXEC. EXEC SQL OPEN C1 END-EXEC. MOVE "SELT1" TO NEXT-TPR. MOVE 2 TO PHASE. GO TO END-OF-TPR. SENDNEXT. EXEC SQL FETCH C1 INTO V END-EXEC. IF SQLCODE = 1403 MOVE ALL SPACES TO NEXT-TPR MOVE 1 TO PHASE GO TO END-OF-TPR....display variable V on the terminal... END-OF-TPR. EXIT PROGRAM. NOTE: This implementation is not necessarily the best one for performance. Remember that if you do not commit before the end-of-fetch condition is met, 47 A2 14UR Rev03 5-7

94 ORACLE7/TDS User's Guide the process in the ORACLE server remains unavailable to other users. Since there may be many terminal conversations, the server may be unavailable for a long time. You can avoid this situation by fetching all ROWIDs that correspond to the selection criteria within a single TPR, and then by immediately logically disconnecting. This frees the ORACLE context. The ROWIDs are saved in TRANSACTION-STORAGE. Then, once the TPR has been reconnected to ORACLE, fetch one row, and commit for each terminal conversation. This enables the multiplexing of many users on the same ORACLE context. (For an example, see the FETCH transaction in Appendix E.) However, the FETCHed ROWIDs are not locked so you may get inconsistent results if another user modifies a row after you select its ROWID but before you display it. 5.3 Controlling The Number Of User-Ids We recommend that user-ids correspond to the various access requirements (or profiles) for a given ORACLE database. Instead of using many different ORACLE user-ids to control access rights to data, use the TDS authority codes. Thus access rights are given for each TDS transaction for each user. The number of ORACLE contexts to be cached, and the number of ORACLE processes are directly proportional to the number of different ORACLE user-id's used in the TDS application. 5.4 Optimizing Connect Statements Local Connection If the ORACLE/TDS application has to connect to a database server running on the same machine, for performance reasons, be sure to use the fully optimized local connection. The general format of a CONNECT issued from an ORACLE/TDS application is the following: EXEC SQL CONNECT :USR IDENTIFIED BY :PWD AT DB1 [ USING :HST ] An optimized local connection is established depending on two conditions: A2 14UR Rev03

95 Optimizing ORACLE/TDS Applications the "USING :HST" clause is not used: local connection to the default database is performed. the "USING :HST" clause is used: be sure that HST variable contains the "D:" prefix or a string corresponding (checking case sensitive) to the name of the INSTANCE running locally. Do not use the "T:" prefix or an SQL*Net V2 alias. It will work but performance will be less. Moreover, when multiple ORACLE databases are accessed by the same TPR, (or if the same database is connected more than once using several different user-ids), Cache Processing CONNECT statements must all be executed at the beginning of the TPR. To optimize the SQL*Net context cache processing, the first CONNECT statements to be executed should be those that connect to the least used databases. Efficient cache management means multiplexing the maximum number of users while using the minimum number of processes. See the examples that follow. EXAMPLE 1: Optimizing Cache Processing The application contains 2 TPRs that connect to ORACLE databases in the following way (always using the same user-id): TPR1 connects to database B1 and database B2. TPR2 connects to database B1 and database B3. To optimize the cache processing, TPR1 must connect to B2 first, before connecting to B1. In the same way, TPR2 must connect to B3 first, before connecting to B1. This is because when the first CONNECT is requested, the cache manager tries to choose an existing context which contains a connection to the requested server. In Example 1 - if the CONNECT to B1 is requested first - the cache manager can choose a context that contains a connection to B1 and B2, or to B1 and B3. But it cannot decide which to choose because the next CONNECT statement is unknown. So in many cases, a physical disconnection of B2 and a physical connection of B3 will be necessary for TPR2, just as a physical disconnection of B3 and a physical connection of B2 will be necessary for TPR1. To optimize performance and to enable the cache manager to choose the correct ORACLE context, TPR1 must connect the B2 database first, and TPR2 must connect the B3 database first. 47 A2 14UR Rev03 5-9

96 ORACLE7/TDS User's Guide EXAMPLE 2: Optimizing Cache Processing Suppose now that we have the following TPRs in our TDS application: TPR1 connects to database B2 and database B1. TPR2 connects to database B2 only. When the cache manager chooses a context for TPR2, it may choose one which was previously used by TPR1; that is, a context which contains a connection to B1. Since the B1 database is not required by TPR2, B1 must be disconnected before TPR2 is processed. Accordingly, this has a negative effect on TPR2 execution time because a physical disconnection consumes more resources than a logical one. The same applies to TPR1 which has to physically connect to B1 if it reuses this context. To optimize performance in this case, add a superfluous connect to the B1 database in TPR2. This will avoid needless disconnections and connections. 5.5 GENERAL Oracle Optimization TECHNIQUES Certain optimization techniques can be applied more generally to ORACLE itself. They are discussed below Saving CPU Time - Use of Cursors The OPEN_CURSORS parameter of INIT.ORA file gives the maximum number of simultaneous cursors allowed per ORACLE USER PROCESS (dedicated server process). This value can be reduced (but not increased) for each relevant application with the use of the MAXOPENCURSORS parameter of the PCC OPEN_CURSORS MAXOPENCURSORS for TDS Default value Maximum value unlimited A2 14UR Rev03

97 Optimizing ORACLE/TDS Applications These 2 parameters must respect the following rule: OPEN_CURSORS >= MAXOPENCURSORS + 6 So, the OPEN_CURSORS value must be adjusted, depending on the highest value of MAXOPENCURSORS. Advice for the MAXOPENCURSORS value: Do not forget to specify a high enough value for the MAXOPENCURSORS parameter. This will save a significant amount of CPU time. The MAXOPENCURSORS parameter limits the maximum number of cursors which can be simultaneously open for an ORACLE user. In the TDS environment, the MAXOPENCURSORS associated with a connection is the one of the TPR which has actually executed the physical connection. Bear in mind that an ORACLE user can multiplex a lot of TDS users so he/she must be able to keep all their cursors opened in their context. Look at "Nb of Cursor Reassign" and "Nb of Stmt executions" statistics in the JOR of your TDS application. Try to keep the ratio "Nb of Cursor Reassign" to "Nb of Stmt executions" as low as possible to get the best performance Database Server Take care to tune the parameters of each ORACLE7 database server correctly. Refer to the ORACLE7 Server Administrator's Guide. Each ORACLE database server should run with a high priority Database Design The database itself should be designed correctly: all necessary indexes should be created clusters should be used when possible use the space parameters associated with tablespaces to spread the I/O load Refer to the ORACLE7 Server Administrator's Guide and the ORACLE7 Server Application Developer's Guide for tips on how to tune the ORACLE database server itself finely. 47 A2 14UR Rev

98 ORACLE7/TDS User's Guide Using Several Distinct ORACLE Databases If a TDS application handles varied information, store the data in several distinct ORACLE databases. This is especially useful if the data is updated very frequently because it avoids reaching the limits of the ORACLE journalizing mechanism. Using different ORACLE databases is possible only if data from different databases is never updated in the same commitment unit. For example, you may have one database containing personnel records, and another for customer information. In such cases, updating is logically separate A2 14UR Rev03

99 6. ORACLE/TDS Rules and Restrictions This section deals with the current limits and restrictions imposed by ORACLE/TDS. The following subjects are discussed: The maximum number of terminals that can be connected to a TDS application. ORACLE processes. Dual updating (UFAS or IDS/II databases, with ORACLE databases). Deadlock detection. Controlled common-storage. The ORACA structure. National Language Support. The spawn function. Opening and closing GCOS 7 files. IQS. The roll forward operation. 6.1 The Number Of Connected Terminals The maximum number of terminals that can be connected depends on the type of the application. For applications where no terminal conversation takes place between each CONNECT to ORACLE and the next commitment, the limit is the standard TDS limit. For other types of application, the limit is generally governed by the resources needed by the ORACLE database servers to execute efficiently. Such resources are: number of processes, main memory, CPU time. 47 A2 14UR Rev03 6-1

100 ORACLE7/TDS User's Guide 6.2 ORACLE Processes An ORACLE database needs a number of user processes that roughly equals the optimal value of the CSIZE parameter (discussed at length in earlier sections). The optimal value for CSIZE will indicate whether the "processes" resource is critical for your ORACLE/TDS application or not. The maximum number of processes depends on the limits imposed by the particular version of GCOS 7 under which ORACLE is running. Refer to the System Installation Configuration and Updating Guide for specific information on your system. 6.3 Updating Ufas OR IDS/II Databases With Oracle Databases Separate Commitment Units Dual updates (that is, updating UFAS or IDS/II data, and ORACLE data) must be done in separate commitment units. If dual updates take place in the same commitment unit, and an error takes place during the commit phase of TDS, it is possible that the ORACLE data has been committed but the UFAS or IDS/II data has not. You can detect this situation by testing SQLCODE. If SQLCODE = -5 on the first attempted CONNECT statement of the commitment unit, it indicates that it is a redo of the commitment unit and that ORACLE data has been committed. See Appendix A for the list of SQLCODE values. Proceed as follows: Commit UFAS or IDS/II data first. Move the information needed for updating the ORACLE database into TRANSACTION-STORAGE. Update the ORACLE data in the next commitment unit Data Consistency There is no data consistency problem if either ORACLE data or UFAS and IDS/II data is updated within the same commitment unit A2 14UR Rev03

101 ORACLE/TDS Rules and Restrictions Therefore, if an ORACLE database is updated, any other UFAS file or IDS/II database can also be read in the same commitment unit. Similarly, if a UFAS file or IDS/II database is updated, any ORACLE database can also be read in the same commitment unit. Deadlocks, however, provide a potential problem. They will be detected by the time-out mechanism only. See "DEADLOCKS" below. 6.4 Deadlocks Deadlocks involving UFAS or IDS/II data and ORACLE data are currently detected only by a time-out mechanism. Such deadlocks are to be avoided because they adversely affect the global performance of ORACLE/TDS applications. Reduce the risk of such deadlocks by accessing UFAS or IDS/II data first in each commitment unit. If the ORACLE data is accessed after UFAS and IDS/II, the deadlock (as described above) cannot occur Avoiding Deadlocks - Example EXAMPLE 1: Avoiding deadlocks between UFAS or IDS/II data and ORACLE TPRA: TPRB: Update UFAS,IDS/II record A. Update UFAS,IDS/II record A. Update UFAS,IDS/II record B. Update UFAS,IDS/II record C. Update ORACLE tuple T. Update ORACLE tuple T. Update ORACLE table T1. Commit. Commit. When the first ORACLE lock is requested, that lock can never be held by another user who is waiting for a UFAS or IDS/II lock. This is because, in both TPRA and TPRB, the UFAS and IDS/II data is updated first, then the ORACLE data is updated. 47 A2 14UR Rev03 6-3

102 ORACLE7/TDS User's Guide Deadlocks may occur, however, if the TPRs are coded in different ways. See Example 2 below Creating Deadlocks - Example EXAMPLE 2: Creating a deadlock TPRA: TPRB: Update UFAS,IDS/II record A. Update UFAS,IDS/II record B. Update ORACLE tuple T. Update ORACLE tuple T. Update UFAS,IDS/II record B. Update ORACLE tuple T1. Update UFAS,IDS/II record C. Commit. Commit. When a user executes TPRB, he may hold the lock on tuple T and then wait for the lock on record B. But the lock on record B is already held by a user executing TPRA who is himself waiting for the lock on tuple T. The problem arises because the UFAS and IDS/II data is updated first in TPRA, and the ORACLE data is updated first in TPRB. Avoid this problem by using the same updating pattern in all commitment units: Update data in UFAS,IDS/II database... Update data in ORACLE database... Commit A2 14UR Rev03

103 ORACLE/TDS Rules and Restrictions... Update data in ORACLE database... Update data in UFAS,IDS/II database... Commit 6.5 Controlled Common-Storage Controlled common-storage is implemented internally as UFAS file blocks. Controlled common-storage carries the same restrictions that apply to UFAS and IDS/II updates Updating Data in Controlled Common-Storage To prevent deadlocks, updates to data in controlled common-storage should be carried out within a commitment unit where no update of ORACLE data takes place. If you are updating data in an ORACLE database and data in controlled commonstorage in the same commitment unit, the same problem occurs as with dual updating of UFAS, IDS/II data and ORACLE data (see above). If an error occurs during the commit phase of TDS, the commitment unit is automatically restarted. However, the ORACLE data may already have been committed. If so, SQLCODE is set to -5 on the first CONNECT statement. See Appendix A. To avoid this, commit controlled common-storage first, and save all the data needed to perform ORACLE database updates in the next commitment unit Reading Data in Controlled Common-Storage If ORACLE data is only read in a commitment unit, ORACLE does not take any locks. In this case, controlled common-storage can be accessed at any time and there is no consistency problem at all. When controlled common-storage is only read, there is no consistency problem but the risk of deadlock remains because locks are always acquired to access controlled common-storage. 47 A2 14UR Rev03 6-5

104 ORACLE7/TDS User's Guide Non-Controlled Common-Storage For non-controlled common-storage, no restriction applies. 6.6 The ORACA Structure Starting from O7340A the Oracle ORACA structure is supported in the ORACLE/TDS environment. 6.7 National Language Support Starting from O7340A a TDS client can use NLS characteristics. It is only necessary to place an INIT_ENV file in the «TDSname.SLLIB» with the desired features. Note that: values given in the INIT_ENV file are valid for the whole TDS (all transactions), when the INIT_ENV file is missing, the default America/American environment is supplied, do not use values in your INIT_ENV file that leads to use all available langages, this can provoque exception in the ORACLE7/TDS code. A good value can be up to two langages. Refer to LXINST command in 47 A2 12UR for more information. 6.8 The Spawn Function The spawn function implementation makes use of a UFAS file internally. The same restrictions as for controlled common-storage apply to the spawn function. Avoid updating ORACLE data in a commitment unit where the spawn function is used. This avoids deadlocks and problems of data consistency. In cases where updating of ORACLE data is definitely required, it should be carried out in the next commitment unit. The necessary data must be stored in TRANSACTION-STORAGE in the current commitment unit. If ORACLE data is only read in a commitment unit, the spawn function can be activated at any time A2 14UR Rev03

105 ORACLE/TDS Rules and Restrictions 6.9 Opening And Closing GCOS 7 FILES Do not update ORACLE data in commitment units where GCOS 7 files are closed. The internal close mechanism of TDS makes use of the spawn function so the same problems of deadlocks and data consistency can occur. The internal open mechanism is not spawned; the open is done when the commitment is taken. You can, however, read ORACLE data without any problem inside a commitment unit where GCOS 7 files are opened or closed Iqs You cannot use IQS query programs in a transaction that accesses an ORACLE database; IQS/TDS and ORACLE/TDS cannot coexist in the same transaction Roll Forward If a media fails, the roll forward operation for the ORACLE database remains manual. The user must ensure consistency between the ORACLE database and the information managed by the TDS application. No checking is done to verify that the state of an ORACLE database which has been restored is consistent with the state of the data in the TDS application. 47 A2 14UR Rev03 6-7

106 ORACLE7/TDS User's Guide A2 14UR Rev03

107 7. ORACLE7/TDS-XA 7.1 Overview A TDS-XA is a transactional application where some transactions call on services offered by XA while others do not. TDS-XA/ORACLE is a part of the X/OPEN Distributed Processing (DTP) model. It enables a single Commitment Unit (CU) to update ORACLE databases, IDS/II databases, and UFAS files simultaneously. The CU can also simultaneously update several ORACLE databases. This means that all updates done within the TX (on UFAS files, IDS/II databases and ORACLE7 databases) will all be committed or rolled back at the end of the CU, under the control of TDS-XA. The ORACLE databases can be either local or remote, and on either a GCOS 7 site or a UNIX site. Figure 7-1 shows how TDS-XA/ORACLE fits in with the DTP model. ORACLE7 Resource Managers (RMs) only are shown in the DTP Model@Fig. 0-1@ 47 A2 14UR Rev03 7-1

108 ORACLE7/TDS User's Guide AP TPRs Pro*COBOL or Pro*C statements TDS ORACLE7/TDS TDS-XA ORACLE7/TDS-XA XA ORACLE7 TM RMs Figure 7-1. TDS-XA/ORACLE in the DTP Model TDS-XA, ORACLE7/TDS-XA, AND ALL THE ORACLE7 XA RMs are involved in a two-phase commitment protocol where TDS-XA and ORACLE7/TDS-XA play the role of the Transaction Manager (TM): Phase 1: RMs are required to "prepare" to commit. Phase 2: the commitment is performed. Both phases are under the control of the TM in a global transaction, which is divided into branches corresponding to the RMs Environment ORACLE7/TDS-XA requires GCOS 7-V7 minimum TS Since ORACLE7/TDS has a client/server architecture, if the ORACLE7 server part is located on a GCOS 7 system, the MI "Distributed" must be installed. There is no particular constraint if only the client part is installed on GCOS A2 14UR Rev03

109 ORACLE7/TDS-XA 7.2 Operation Heuristic Decisions Some RMs may employ heuristic decision-making: an ORACLE7 database administrator may decide to commit or rollback the work of a prepared transaction branch independently of the TM in order to unlock shared resources. This may leave the RM in an inconsistent state in which case, when TDS-XA tells the ORACLE7 database to complete the branch, it will reply that it has already done so. The ORACLE7 database must retain this information even if it matches the TM's decision so that the TM can call it again to authorize it to forget the branch TDS Resynchronization with XA If a failure disrupts the protocol, the commitment unit is said to be desynchronized. Resynchronization consists in completing the commitment unit, and is necessary to ensure data integrity across the distributed system. Modifications via the ORACLE7 Resource Managers are validated at the commitment points defined (implicitly or explicitly) by the TPRs, at the same time as for UFAS or IDS/II databases and committable TDS services. Each time a CU becomes desynchronized, TDS-XA automatically starts the reporting transaction H_XAEVT (see below, The H_XAEVT Special Transaction) to help the user solve the problem. After resynchronization, it starts the transaction again to give a final report for the CU. A full description of this special transaction is given later in this Section and an example of resynchronization after detection of an error is given in Appendix I TDS Restart At TDS warm restart, resynchronization with XA RMs is performed for each CU of the previous TDS session that is still active for XA. 7.3 User Interface Users concerned by TDS-XA/ORACLE are: 47 A2 14UR Rev03 7-3

110 ORACLE7/TDS User's Guide the TDS administrator responsible for the generation step and for monitoring the TDS application, the GCOS 7 system administrator and the ORACLE database administrator who are responsible for data consistency, the TDS programmer who is responsible for programming transactions that are committed with XA TDS Generation and Application Monitoring TDS Generation TDS Section The XA-RESYNC-DELAY clause specifies the time between two resynchronization attempts by an XA commitment unit: [ XA-RESYNC-DELAY [IS] {dec4 300 } ] Transaction Section Include the following clause to allow the transaction to use XA services: XA SERVICE USED ORACLE-DEF... ORACLE-ENDDEF Block Add two new parameters for XA transactions: XA-USER IS <name30>. XA-PASSWORD IS <name20>. These are the user name and password used at TDS restart for connection and to request all ORACLE databases to provide the list of CUs to be resynchronized. The default values are SYSTEM/MANAGER. This user/password needs only to have select privilege on the V$XATRANS$ view on all databases accessed A2 14UR Rev03

111 ORACLE7/TDS-XA Application Monitoring The master commands specific to XA are documented in the TDS Administrator's Guide Server Configuration Make sure that the V$XATRANS$ view exists on all ORACLE7 databases. You can create the view by running the SQL script xaview_sql. Execute this SQL script under the ORACLE server user sys. The select privilege on V$XATRANS$ must be given to all ORACLE7/TDS-XA users, including the XA user/password given in the TDS generation. For more details, see the ORACLE RDBMS Administrator's Guide. ORACLE documentation is listed in the ORACLE7 Documentation Catalog TPR Programming CONNECT Statement and ORACLE7/TDS Cache Manager The ORACLE7/TDS Cache Manager is designed to multiplex the users of an ORACLE7 application on a small number of ORACLE processes. A "logical connection" is defined for each CONNECT statement with a given profile (user, password, (AT)DBn, host). This connection is mapped on a physical connection to the ORACLE process which was established at the time of the first CONNECT with the given profile. The physical connection is not stopped until TDS stops or until the ORACLE7 administrator requests that it be stopped through the ORACLE transaction. Each commitment unit is represented by a CACHE entry, and all connections within this CU are represented by CONNECTION entries chained on the CACHE entry. The connection cache contains all physical connections that are active on all ORACLE databases being accessed by TDS as follows: The XA connections are represented by XA CONNECTION entries chained on an XA CACHE entry which in turn represents an XA commitment unit (the transaction has been declared XA in the STDS). Non-XA connections are represented by non-xa CACHE entries. The algorithm defined to reuse entries supposes that a non-xa connection cannot be reused for an XA connection even of the connection profile is the same. 47 A2 14UR Rev03 7-5

112 ORACLE7/TDS User's Guide Therefore the CISIZE parameter representing the CACHE size must be considered as having one part for the XA entries and another part for the non-xa entries. The cache size has a great impact on performance, so bear this factor in mind when dimensioning the cache. Use the XA and other parameters as follows: the CSIZE parameter is the total size of the context cache, XA and non-xa. CASTAT transaction statistics: number of non-xa busy entries, number of non-xa free entries number of XA busy entries, number of XA free entries JOR statistics: number of CTX entries used for non-xa, number of CTX entries used for XA, The following processing is specific to XA mode: up to eight database identifiers can be controlled in the processing of a CU in a TDS-XA, connection errors are rejected with the SQL code ORAT-28. To obtain the explicit XA error codes, it is necessary to set the ORACLE trace level to value 2 and to restart the TPR with trace print XA domain activated. Messages are written in the TDS debug file. See the appropriate TDS Programmer's Guide for full syntax of the TDS trace commands Using Precompilers with ORACLE XA When used in an ORACLE XA application, cursors are valid only for the duration of the transaction. Therefore, you must open explicit cursors after the transaction begins and close them before the commit or rollback. You must use the option release-cursor=yes when compiling your precompiler application SQL-Based Restrictions The following restrictions apply due to SQL constraints: Rollbacks and Commits: Because the Transaction Manager is responsible for coordinating and managing the progress of the transaction, the application must not contain any ORACLE server-specific statement that would independently roll back or commit a transaction: A2 14UR Rev03

113 ORACLE7/TDS-XA do not use EXEC SQL ROLLBACK WORK for precompiler applications. Either arrange for the transaction to be rolled back by the initiator or call INVCMIT, do not use the EXEC SQL COMMIT WORK statement in a precompiler application. Use DFCMIT instead to end a transaction. DDL Statements: Because a DDL statement such as CREATE TABLE implies an implicit commit, the ORACLE XA application cannot execute any SQL DDL statements. Savepoint: Do not use savepoint. For example, do not use EXEC SQL SAVEPOINT <savepointname>. Read Only Transactions: Do not use read only transactions. For example, do not execute SQL statements such as SET TRANSACTION READ ONLY. EXECSQL: Do not use the EXEC SQL command to connect or disconnect. That is, do not use EXEC SQL COMMIT WORK RELEASE or EXEC SQL ROLLBACK WORK RELEASE Checking the Synchronization State You are strongly advised to start each XA TPR with a call to the "GET- SYNCSTATE" procedure (COBOL) or the h_get_syncstate function (C language) to obtain the synchronization state of the committed data. See the appropriate TDS Programmer's Guide for full details The H_XAEVT Special Transaction To handle situations of data consistency, you are strongly advised to rewrite the H_XAEVT special transaction using the ORACLE7/TDS-XA procedure H_OR_XARMSOFCU. See appendix H for an example of the H_XAEVT special transaction. The H_OR_XARMSOFCU procedure is designed to return a list of all the RMs being accessed by a given CU, together with the state of this CU in relation to the RMs accessed. The call to H_OR_XARMSOFCU must occur in the first TPR of the H_XAEVT transaction. Format: 47 A2 14UR Rev03 7-7

114 ORACLE7/TDS User's Guide H_OR_XARMSOFCU (RMLIST_PTR, RMNB) Parameters: RMLIST_PTR RMNB is an input parameter that provides a pointer to an area that will be filled by ORACLE/TDS-XA with RMNB entries, one for each RM accessed during the currency of this CU. The area is allocated by the caller (a TPR in C or COBOL) and is sized for a maximum of eight entries of the following type: XA_ENTRY XA_GBLFORID PIC X(40) global transaction id XA_DBID PIC X(8) database identifier XA_RMIDENT PIC X(44) RM identifier XA_STATUS COMP-1 Status of last commit for this RM is an output parameter receiving the effective number of RMs accessed during the currency of the CU and corresponding to the number of entries in the array pointed by RMLIST_PTR. The troubleshooting of distributed transaction problems is then handled as follows: when XA_STATUS is not done, XA_RMIDENT identifies the desynchronized RM, the database manager checks the RM and verifies the status of the transaction indicated by XA_GBLFORID in the DBA_2PC_PENDING table, he takes a heuristic decision or arranges for the communication link to be restored, then waits for completion of resynchronization. For a full description of the H_XAEVT transaction, see the appropriate TDS Programmer's Guide. 7.4 HA And XCP2 Compatibility A TDS-XA can also be a TDS-HA. It can also be a TDS-XCP2. In this case, the XCP2 synchronization level is SYNCPOINT and the PPC Syncpoint Manager is the commit coordinator relative to the TDS application, rather than TDS itself. The Syncpoint orders are transmitted to ORACLE7/TDS through the TDS Commit Manager thus providing XCP2 and XA compatibility A2 14UR Rev03

115 ORACLE7/TDS-XA NOTE: If an inconsistency results from a heuristic decision on the part of an XA Resource Manager, the fact will not be disseminated in the XCP2 commitment tree. This is a restraint of the LU.6 protocol where heuristic decisions are not known beyond two XCP2 nodes. 47 A2 14UR Rev03 7-9

116 ORACLE7/TDS User's Guide A2 14UR Rev03

117 8. Writing Pro*C TPRs for TDS This section describes how to write TPRs containing SQL statements. It discusses the differences applicable to use of C language as opposed to use of COBOL as dealt with in section 2. It is assumed that programmers are already familiar with TDS C and with SQL. If necessary, refer to the TDS C 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 Interface documentation concerning Pro*C. 8.1 Introduction To build a Pro*C TPR containing SQL statements, the general procedure is: write the TPR with the SQL statements, precompile it using the Pro*C compiler, compile it using the C 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. 8.2 Programming Rules Connecting to ORACLE The language used in the TPR has no impact on the aspects of SQL*Net context cache management such as physical and logical connection, SQL*Net cache entry states, etc. Note that if two TPRs, one written in C and the other in COBOL, use the same physical connection profile, they could share the same SQL*Net context 47 A2 14UR Rev03 8-1

118 ORACLE7/TDS User's Guide since the physical connection is not identified using the language of the TPR. See Physical Connection Definition in section Commitments The rules relating to commitment described in section 2 for TPRs in COBOL apply equally to TPRs written in C language.. Use the call h_dfcmit() in place of CALL "DFCMIT" Rollback The rules relating to rollback described in section 2 for TPRs in COBOL apply equally to TPRs written in C language.. Use the calls h_rollback(), h_invcmit, and h_nocmit respectively in place of CALL "ROLL-BACK", CALL "INVCMIT", and CALL "NOCMIT" Data Definition Statements The usual rules apply as for DDL/DCL statements Handling Runtime Errors As with COBOL TPRs (see Using the ORACLE Communications Area (ORACA) in section 2, the ORACA structure is not supported. A call to the getstm entry point is done as extern void getstm(); char mess_buf{70}; int buff_size; int mess_lgt; buff_size=70; getstm (&mess_buf, &buff_size, &mess_lgt); A2 14UR Rev03

119 Writing Pro*C TPRs for TDS 8.3 Precompiling, Compiling, And Linking Precompiling To precompile a Pro*C TPR, use PCC with the HOST parameter set the value C. EXAMPLE: PCC INAME = MYDIR.SL..MYTPR HOST = C; Successful precompilation produces an output source file named MYTPR_PCC in the library MYDIR_SL Compiling The file MYTPR_PCC in the library MYDIR_SL must then be compiled by the C compiler. When compiling a C TPR, some options are mandatory (for instance, LEVEL =GCOS 7). See the TDS C Language Programmer's Guide for a full description of the options that are mandatory in this context Linking The linkage phase is identical to that used for a COBOL TPR. See Linking a Pro*COBOL TPR in section 2 and the TDS C Language Programmer's Guide. 8.4 Other C Language Variations Setting Configuration Parameters Dynamically The source programs required to implement the ORACLE, CASTAT, and TCLEAN transactions are delivered only in their COBOL version. To make a call to the SETMXC entry point, use the following form: 47 A2 14UR Rev03 8-3

120 ORACLE7/TDS User's Guide extern void SETMXC(); int i-maxopcurs, o-rtcd; i-maxopcurs =...; SETMXC (i-maxopcurs, o-rtcd); Obtaining Cursor Statistics via the orastat Entry Point Declare the oracatds structure by using the ORACATDS-C member which is delivered in the ORACLE SL library. To make a call to orastat from a TPR, use the following EXEC SQL INCLUDE SQLCA; #define ORACATDS_INIT; EXEC SQL INCLUDE ORACATDS END_EXEC; extern void orastat();... strcpy (oracatds.dbid, "MYDBID"); oractds.dbid_lg = 6; orastat (&sqlca, &oracatds); A2 14UR Rev03

121 A. SQLCODE Error Conditions Error conditions may occur when a Pro*COBOL statement is executed. A negative error code (between -1 and -27) is placed in the SQLCODE field. You must test SQLCODE correctly in the TPR. Most error conditions cannot cause data inconsistency between ORACLE data and TPR data. Errors -5 and -6, however, require careful handling. The standard way of dealing with these errors is to abort the current transaction. However, if such an error occurs in a commitment unit where updates have been deferred (for example, because of multiple database updates), you must save all critical data in a secure location, such as TRANSACTION-STORAGE. Alternatively, you can undo the updates done within the previous commitment unit. To do this, all the data needed to undo those updates must have been saved in a secure location. For example, it can be moved into TRANSACTION-STORAGE by the previous commitment unit. The values of SQLCODE specific to ORACLE/TDS are listed on the following pages, along with an explanation of the cause and suggested remedial action. A.1 Sqlcode = -1 " " Cause: This is a functional code. It is used as a specific interface between the ORACLE/TDS layer and the code generated by the Pro*COBOL precompiler. No error message is associated with this code. Action: 47 A2 14UR Rev03 A-1

122 ORACLE7/TDS User's Guide None. A.2 Sqlcode = -2 "ORAT-2: Connect failed: communications server not ready." Cause: The CONNECT statement has failed because communication with the ORACLE communications server has not yet been established by your TDS application. Action: Abort the current transaction. Your TDS administrator is responsible for dealing with this problem. He has to check that the ORACLE communications server has been activated. If not, he will use the COR command under IOF to start it. Otherwise, he will wait for it to be ready and then will use the "ORACLE ENABLE" transaction to enable communication between COR and your TDS application. A.3 Sqlcode = -3 "ORAT-3: Internal error: abnormal end of cache processing." Cause: This is an internal error message and should not normally be issued. Action: Contact your customer support representative. A.4 Sqlcode = -4 "ORAT-4: ORACLE not available for this TDS application." Cause: A-2 47 A2 14UR Rev03

123 SQLCODE Error Conditions ORACLE cannot work with this TDS application because the necessary initializations have not been done. Action: Check that one of the allowed "USE ORACLE" options has been specified in the TDS Generation Program which produced the run-time TDS Load Module. Check also that necessary system patches have been installed on your system. A.5 Sqlcode = -5 "ORAT-5: ORACLE database already committed." Cause: A failure occurred during the commit phase of the current commitment unit; the SQL*Net connection was lost just after the commit request was sent to the ORACLE server so the acknowledgement was not received. When TDS restarted the commitment unit and was able to reconnect to the ORACLE server, it was detected that the ORACLE server could finally commit. However, the commitment unit cannot be re-executed because this would lead, for example, to "double updating". Action: If no data needs to be reconstructed for the execution of the next commitment unit, skip the execution of the current commitment unit and continue with the execution of the next one. Otherwise, abort the current TDS transaction. A.6 Sqlcode = -6 "ORAT-6: Unrecoverable timeout error." Cause: The same failure as above occurred but TDS could not re-connect to the ORACLE server in time. The status of the ORACLE data updated by the current commitment unit is unknown. 47 A2 14UR Rev03 A-3

124 ORACLE7/TDS User's Guide Action: If no ORACLE data has been modified by the current commitment unit (that is, only SELECT statements have been executed), the current transaction should be aborted because the ORACLE server is no longer available. It is not therefore possible to continue with the current transaction. If ORACLE data has been modified, either retry by executing CALL "ROLL- BACK", or abort the current transaction. Data integrity is preserved because ORACLE did either commit or roll back, but you must check by other means whether ORACLE has committed or not. Save the necessary information in a secure location - such as TRANSACTION-STORAGE - to enable you to do this. A.7 Sqlcode = -7 "ORAT-7: Timeout at commit time while executing an SQL stmt." Cause: At the end of a TDS commitment unit, one of the following statements has been interrupted because of the triggering of the timeout mechanism: INSERT in the SYS$TDS table of the database to commit. UPDATE in the SYS$TDS table of the database to commit. COMMIT of the database. ROLLBACK of the database. No acknowledgement of the break request has been received from the server, so the physical connection is broken. The commitment unit will be restarted by TDS and a SELECT statement on the SYS$TDS table will be executed to see the state of the ORACLE commitment. On the first CONNECT statement, one of the following SQLCODE will be returned to the COBOL program: SQLCODE=-5 "ORAT-5: ORACLE database already committed." SQLCODE=-23 "ORAT-23: CU restarted to notify an error during commit:code=-7." Action If the program receives the SQLCODE -5, see paragraph A.5. Check the system load of your machine, increase values of the TIMEOUT and MAXTIM parameters, then try to re-execute your transaction. A-4 47 A2 14UR Rev03

125 SQLCODE Error Conditions A.8 Sqlcode = -8 "ORAT-8: ORACLE connections disabled." Cause: Connections with ORACLE databases from the TDS application have been disabled through the execution of the "ORACLE" transaction, or have not yet been enabled. Action: Abort the current transaction. Contact your TDS administrator who has probably decided to stop ORACLE/TDS connections on the system. To restart ORACLE processing, he will use the "ORACLE ENABLE" transaction. A.9 Sqlcode = -9 "ORAT-9: Internal error. Cache entry inconsistency." Cause: This is an internal error message and should not normally be issued. Action: Contact your customer support representative. A.10 Sqlcode = -10 "ORAT-10: Internal error: ssmget error in osntds." Cause: The allocation of a semaphore needed to set up a physical connection with an ORACLE server has failed. 47 A2 14UR Rev03 A-5

126 ORACLE7/TDS User's Guide This is an internal error message and should not normally be issued. Action: Contact your customer support representative. A.11 Sqlcode = -11 "ORAT-11: Strong disconnection of communications server." Cause: The ORACLE communications server has suddenly been made unavailable; for example it has been killed. Action: Abort the current transaction. Restart the ORACLE communications server using the COR command under IOF. A.12 Sqlcode = -12 "ORAT-12: <message received from the COR>." Cause: When trying to set up a physical connection to an ORACLE server, an error message has been received from the COR. Action: It depends on the error message which is returned. For example: When the message is: "ORAT-12: No server active with name #### on site ####.", A-6 47 A2 14UR Rev03

127 SQLCODE Error Conditions activate this database server by using the SOR and SQLDBA commands, or wait for it to become ready if it has already been started. When the message is: "ORAT-12: No vacant processes. Retry later.", increase the number of processes in your database server by using the SOR A command. A.13 Sqlcode = -13 "ORAT-13: Mixing formerly and newly precompilations is forbidden." Cause: The TDS application contains Pro*COBOL programs precompiled with version 1.3 of the precompilers and Pro*COBOL programs precompiled with version 1.5 of the precompilers. Such a mix is not supported. Action: Make your precompilations uniform (by precompiling with the same version of the precompilers, then re-compiling, and re-linking). Then, restart your TDS application. A.14 Sqlcode = -14 "ORAT-14: Unable to allocate memory in the TDS side." Cause: Memory allocation required by the ORACLE/TDS layer or by the SQL run-time has failed. Action: Contact your customer support representative. 47 A2 14UR Rev03 A-7

128 ORACLE7/TDS User's Guide A.15 Sqlcode = -15 "ORAT-15: No connected database." Cause: An SQL statement (other than CONNECT) has been executed while no ORACLE database was connected. Action: Check your application program. Remember that each commit disconnects from all connected databases. Verify that your program or another program did a successful connect to the required database prior to the execution of this statement. A.16 Sqlcode = -16 "ORAT-16: Not logged on the target database." Cause: An SQL statement (other than CONNECT) has been executed without being connected to the target database. Action: Check your application program. Remember that each commit disconnects from all connected databases. Verify that your program or another program did a successful connect to the required database prior to the execution of this statement. A.17 Sqlcode = -17 "ORAT-17: Commit on several databases not allowed." Cause: The commit of several databases has been requested within the same TPR. This is currently not allowed. A-8 47 A2 14UR Rev03

129 SQLCODE Error Conditions Action: Remove one of the COMMIT statements, and commit this database in a subsequent TPR. A.18 Sqlcode = -18 "ORAT-18: The program can be run under IOF or batch only." Cause: The TPR has been precompiled without specifying the appropriate value for the HOST parameter. This error message can be returned, only if you precompile your COBOL program with version 1.3 of the Pro*COBOL precompiler (delivered with ORACLE V6). Action: Re-precompile your COBOL program with the Pro*COBOL precompiler delivered with ORACLE7 (version 1.5). Re-compile it, re-link it and re-load your TPR sharable module. A.19 Sqlcode = -19 "ORAT-19: Internal error: inconsistency in ORACLE/TDS data." Cause: This is an internal error message and should not normally be issued. Action: Contact your customer support representative. A.20 Sqlcode = -20 "ORAT-20: Database logical name already used" 47 A2 14UR Rev03 A-9

130 ORACLE7/TDS User's Guide Cause: A CONNECT statement has failed because the logical name has already been used for a previous connection in the current commitment unit. Action: Avoid requesting several connections in a single commitment unit which uses the same logical database name. A.21 Sqlcode = -21 "ORAT-21: A host variable in the AT clause is not supported." Cause: An SQL statement has failed, because a host variable is specified in the AT clause. Action: Avoid using a host variable in the AT clause: it is not supported in the TDS environment. A.22 Sqlcode = -22 "ORAT-22: Restart loop" Cause: The TPR falls into an automatic restart loop. Action: Look at the Job Occurrence Report (JOR) of the TDS application: internal errors will probably be logged. Contact your customer support representative. A A2 14UR Rev03

131 SQLCODE Error Conditions A.23 Sqlcode = - 23 "ORAT-23: CU restarted to notify an error during commit:code=####" Cause: This error may occur, during access to the SYS$TDS table involved in the commit protocol between TDS and ORACLE, or during the commit of the ORACLE database. As this error appears at TPR ending, outside the scope of the user's program, it cannot be notified synchronously. So the CU is rolled back, silently restarted, and the error is returned to the user's program on the first CONNECT statement of the commitment unit. Action: Look at the error code in the message and refer to the "Error Messages and Codes Manual" documentation. If the code is a negative one, refer to the suitable code description in this chapter. For example, if the code is 942, check existence of the SYS$TDS table in the database and run the TDS_SQL script if required. A.24 Sqlcode = - 24 "ORAT-24: Problem during cursor identification" Cause: A SQL statement has failed due to a problem during the cursor identification. This is an internal error message and should not normally be issued. Action: Contact your customer support representative. A.25 Sqlcode = - 25 "ORAT-25: Invalid host variable definition" 47 A2 14UR Rev03 A-11

132 ORACLE7/TDS User's Guide Cause: A connect statement has failed because at least one of the CONNECT parameters is invalid. It may be wrongly declared or wrongly initialized. Action: Check the CONNECT parameters of your application program. A.26 Sqlcode = - 26 "ORAT-26: Failed to allocate a new SQL*Net context." Cause: Allocation of a SQL*Net context has failed at connection time. This is an internal error message and should not normally be issued. Action: Contact your customer support representative. A.27 Sqlcode = - 27 "ORAT-27: Maximum number of database identifiers exceeded." Cause: The number of distinct database identifiers used in the application program is beyond the authorized limit which is fixed at 12 for non-xa applications and at 8 for XA applications. Action: Check your application program. A A2 14UR Rev03

133 SQLCODE Error Conditions A.28 Sqlcode = - 28 "ORAT-28: Error occurred in an XA function." Cause: An error occurred at connection time, such as an invalid connect string, Resource Manager not available, etc. Action: Check the connection parameters and availability of RMs. If ORACLE trace and TPR XA trace are active, see the full error message in the TDS debug file. A.29 Sqlcode = - 29 "ORAT-29: Connection to remote host failed (unsupported machine)" Cause: A try to connect to an unsupported machine by using SQL*Net has been executed. Only connections to DPS 7000 or UNIX-BULL platform are allowed. Action: Check the SQL*Net connect parameters of your application. A.30 Sqlcode = - 30 "ORAT-30: This verb is not allowed in an XA context." Cause: "EXEC SQL COMMIT" was issued in an XA context. Action: Remove the offending verb, or replace it by a call DFCMIT. 47 A2 14UR Rev03 A-13

134 ORACLE7/TDS User's Guide A.31 Sqlcode = - 31 "ORAT-31: unsupported driver prefix." Cause: The given driver prefix (see chapter 2) is not supported under ORACLE7/TDS. Action: Check the SQL*Net connect parameters of your application program. A.32 Sqlcode = - 34 "ORAT-34: CMA access not allowed. Cause: There has been an attempt to connect a remote UNIX machine using SQL*Net. Action: A specific Marketing Identifier is mandatory to use this function. Contact your customer support representative. A A2 14UR Rev03

135 B. Sample COPY Files The following source files are referenced in the examples contained in the other Appendices of this manual. They are included in TPRs by using the COBOL COPY statement. The CONSTANT-STORAGE and TDS-STORAGE files are stored in the <tdsname>.cobol library following the TDS generation. The COMMUNIC-SECTION file is delivered in the.sl library under the directory name of your ORACLE installation. CONSTANT-STORAGE 1 01 CONSTANT-STORAGE. 2 * CARRIAGE RETURN 3 02 CR PIC X. 4 * LINE FEED 5 02 LF PIC X. 6 * FORM FEED ( CLEAR SCREEN ) 7 02 FF PIC X. 8 * PAGE RETURN ( HOME ) 9 02 PR PIC X. 10 * BLINK BLK PIC X. 12 * BELL BEL PIC X. 14 * END OF MEDIUM EM PIC X. 16 * FORWARD SPACE FS PIC X. TDS-STORAGE 47 A2 14UR Rev03 B-1

136 ORACLE7/TDS User's Guide 1 01 TDS-STORAGE SYMBOLIC-QUEUE PIC X(12) PRIOR-TPR PIC X(12) CURRENT-TPR PIC X(12) NEXT-TPR PIC X(12) ON-ABORT-TPR PIC X(12) ABORT-CODE COMP USER-ID PIC X(8) TX-MODE PIC RESTART-STATUS PIC TRANSACTION-SERIAL-NUMBER COMP TPR-SERIAL-NUMBER COMP WAIT-TIME COMP ABORT-ICC PIC X(8) RESTART-CODE PIC X(1) USER-FULLNAME PIC X(12) NO-RESTART PIC X(1) REST-CVSTAT PIC X(1). 10 CD CD-IN FOR INPUT 20 SYMBOLIC QUEUE IS QUEUE-IN 30 MESSAGE DATE IS DATE-IN 40 MESSAGE TIME IS TIME-IN 50 SYMBOLIC SOURCE IS SOURCE-IN 60 TEXT LENGTH IS LENGTH-IN 70 END KEY IS KEY-IN 80 STATUS KEY IS STATUS-IN 90 MESSAGE COUNT IS COUNT-IN. 100 CD CD-OUT FOR OUTPUT 110 DESTINATION COUNT IS COUNT-OUT 120 TEXT LENGTH IS LENGTH-OUT 130 STATUS KEY IS STATUS-OUT 140 ERROR KEY IS ERROR-OUT 150 SYMBOLIC DESTINATION IS DEST-OUT. B-2 47 A2 14UR Rev03

137 C. The TDSTCLEAN Transaction C.1 Purpose A cleaning mechanism has been implemented to automatically clean the ORACLE/TDS cache. This mechanism is activated through a new Transaction, named TDSTCLEAN. The cleaning mechanism consists in physically disconnecting all ORACLE sessions associated with every FREE SQL*Net context in the cache. When the continuous inactive time of a SQL*Net context exceeds a value defined by the TDS and Database administrator (IDLET), the cleaning mechanism disconnects it. The cleaning mechanism scans the cache periodically (every SPWNT seconds) to find inactive contexts. C.2 Transaction Description The "TDSTCLEAN" transaction is associated with the TCLEAN_COBOL program, which is delivered with your ORACLE7 version. This program implements the call to an entry point, named TCLEANANAL, in the H_ORATDS sharable module. This entry point analyzes the parameter string and starts the disconnection mechanism (if parameters are valid). It spawns a second TCLEAN transaction, that effectively scans the cache every SPWNT seconds in order to suppress all FREE SQL*Net contexts which have been inactive for more than IDLET seconds. This spawned transaction is a multi-tpr transaction that passes from one TPR to the NEXT one every SPWT seconds, until the mechanism is deactivated. The code for the spawning transaction and for the spawned transaction (first TPR and NEXT-TPRs) are both located in the TCLEAN_COBOL program. 47 A2 14UR Rev03 C-1

138 ORACLE7/TDS User's Guide C.3 How To Use To use TDSTCLEAN, assign the "TCLEAN" message to the ORATDS linkage unit in the TDS Generation Program. Add the following lines to the TRANSACTION SECTION of the STDS member: MESSAGE "TCLEAN" ASSIGN TO TDSTCLEAN AUTHORITY-CODES ARE 0,1. *END The TDSTCLEAN transaction has several parameters for launching the TCLEAN mechanism. These parameters may be divided into two categories: IDENTs and KEYWORDs. IDENTs IDENTs are used to update TSPWNN and TIDLE values in the TDSSEG. The syntax for these parameters must include an "=", for example SPWNT = 90. Both uppercase and lowercase letters are accepted. The following IDENTS are accepted: SPWNT IDLET KEYWORDs KEYWORDs represent an action to be taken to modify the TCLEAN mechanism. Both uppercase and lowercase letters are accepted. The following KEYWORDs are accepted: DISPLAY STOP All these parameters are described below. Restrictions A few restrictions apply to the syntax you may use after the "TCLEAN" transaction name. C-2 47 A2 14UR Rev03

139 The TDSTCLEAN Transaction It is forbidden to mix parameters of the two categories. For example, you may not specify: TCLEAN SPWNT= 90 DISPLAY Neither parameter is taken into account. You cannot take two different actions at the same time. For example, the following is rejected: TCLEAN STOP DISPLAY Neither of the two actions is done. But you can set the two IDENTs at the same time. Further, in certain cases, the mechanism will not start unless both IDENTs are set. For details, see the description of SPWNT and IDLET below. However if an error is detected for one of the two IDENTs, neither of them is taken into account. You are recommended to issue a "TCLEAN DISPLAY" command before any action on TCLEAN mechanism. In fact, this mechanism has a big impact on your application and you must not launch it in an erroneous way. For example, setting SPWNT will automatically launch the mechanism if IDLET is set (due to a previous activation). This IDLET may not be the one you want to use, so it is important to check it before any action. C.3.1 Description of the "TCLEAN" IDENTs After each valid modification of one of the configuration parameters, all of them are displayed upon terminal. C The SPWNT Parameter The SPWNT parameter specifies the interval (in seconds) between two TPRs of the spawned transaction. The variable provided for this parameter must be of type PIC S9(9) COMP-2. When the TCLEAN mechanism is not initiated, you must set SPWNT as well as IDLET to launch it. The value of SPWNT will be used at the end of the TPR. It is put in WAIT-TIME which corresponds to the time the transaction will wait for before moving on to NEXT-TPR. There is no default value for SPWNT. You must give an explicit value to launch the disconnection mechanism. 47 A2 14UR Rev03 C-3

140 ORACLE7/TDS User's Guide The minimum value is 0. You may use 0 if the TCLEAN mechanism is active and you want to stop it without changing the IDLET value. This is useful if you want to stop the disconnection for a while but you know you will start it again in the same conditions. In this case, do not use "TCLEAN STOP" but TCLEAN SPWNT=0". The maximum value is seconds. If you try to set SPWNT value without having given a value for IDLET, you will get: *************************************************************** * TCLEAN mechanism * * * * No value for IDLET; mechanism won't start * *************************************************************** If you set valid values for IDLET and SPWNT, the TCLEAN mechanism will be activated and you get: *************************************************************** * TCLEAN mechanism * * * * TCLEAN will be spawned with following values : * *************************************************************** * SPWNT = * * IDLET = * *************************************************************** TCLEAN SPAWNED If you change SPWNT value through "TCLEAN SPWNT= xx " and the mechanism is active, you will get: *************************************************************** * TCLEAN mechanism * * * * Parameters updated * *************************************************************** * SPWNT = * * IDLET = * *************************************************************** C-4 47 A2 14UR Rev03

141 The TDSTCLEAN Transaction If you want to stop the mechanism by "TCLEAN SPWNT= 0", you will get: *************************************************************** * TCLEAN mechanism * * * * TCLEAN mechanism will be stopped * *************************************************************** C The IDLET Parameter The IDLET parameter specifies the maximum time in seconds during which an ORACLE session may be inactive if the TCLEAN mechanism is initiated. If an SQL*Net context is inactive for more than IDLET seconds at cache scanning time (every SPWNT seconds), all connections entries linked to this SQL*Net context are suppressed. The variable provided for this parameter must be of type PIC S9(9) COMP-2. There is no default value for IDLET. You must give an explicit value to launch the disconnection mechanism. The minimum value is 1 second. If TCLEAN mechanism has never been launched or has been stopped by "TCLEAN STOP", the value for IDLET is 0 (you may check this with "TCLEAN DISPLAY") and the TCLEAN mechanism will not be able to start until you specify a non-zero value. This is an implementation choice to make you choose the IDLET value when you launch TCLEAN mechanism. The maximum value is seconds. If you try to set an IDLET value and the SPWNT has not been set, you get: *************************************************************** * TCLEAN mechanism * * * * TCLEAN mechanism is not active : parameter won't be updated * *************************************************************** If you change the IDLET value through "TCLEAN IDLET= xx " and the mechanism is active, you will get: 47 A2 14UR Rev03 C-5

142 ORACLE7/TDS User's Guide *************************************************************** * TCLEAN mechanism * * * * Parameters updated * *************************************************************** * SPWNT = * * IDLET = * *************************************************************** In that case, you must be aware of the fact that this new value for IDLET will not be taken into account immediately, but at the next execution of the TPR of the spawned transaction. This is possibly as much as SPWNT seconds later. During this gap, the maximum time of inactivity for FREE entries remains the old value of IDLET. C.3.2 Description of "TCLEAN" transaction KEYWORDs C "TCLEAN DISPLAY" This keyword permits you to display the values of SPWNT and IDLET parameters, as well as the status of the TCLEAN mechanism in itself. *************************************************************** * TCLEAN mechanism * * * * TCLEAN mechanism is not active * *************************************************************** * SPWNT = 0 * * IDLET = * *************************************************************** In this case, SPWNT is always 0. or *************************************************************** * TCLEAN mechanism * * * * TCLEAN mechanism is active * C-6 47 A2 14UR Rev03

143 The TDSTCLEAN Transaction *************************************************************** * SPWNT = * * IDLET = * *************************************************************** This command should be issued before any action on TCLEAN mechanism. C "TCLEAN STOP" This command permits you to stop the TCLEAN mechanism by resetting SPWNT to 0. IDLET is also reset to 0, so that next activation cannot be effected without having set a new value. If you try to stop TCLEAN and mechanism is already stopped, you get: *************************************************************** * TCLEAN mechanism * * * * TCLEAN mechanism is not active * *************************************************************** * SPWNT = 0 * * IDLET = 0 * *************************************************************** In this case, both values are set to 0: If the mechanism was active, you get: *************************************************************** * TCLEAN mechanism * * * * TCLEAN mechanism will be stopped * *************************************************************** 47 A2 14UR Rev03 C-7

144 ORACLE7/TDS User's Guide C-8 47 A2 14UR Rev03

145 D. The SAMPLE Transaction In the source library delivered with an ORACLE kit, there are two demonstration programs which can run in the TDS environment: SAMPLE and FETCHDEM. FETCHDEM program is detailed in Appendix E. SAMPLE is a program which adds new employee records to the emp table. Checking is done to ensure the integrity of the database. If your working directory has been set up correctly, you can prepare the SAMPLE transaction by following these steps: PCC INAME=SAMPLE HOST=COBOL IRECLEN=132 INCLUDE=INSTALLDIR.SL; CBL SAMPLE_PCC.SL LEVEL=NSTD CARDID=0 WARN=NO; LK SAMPLE SM OUTLIB=MYTDS.SMLIB COMFILE=MYTDS.SLLIB..TP7LINKTPR; Add the USE ORACLE clause, and assign a message clause to the SAMPLE TPR, in the STDS file of your TDS application. Log on to your TDS application and start the SAMPLE transaction, with valid parameters to connect to the ORACLE database: SAMPLE username/password/host The program queries the user as follows: Enter employee name : Enter employee job : Enter employee salary : Enter employee dept : Insertion terminates if <return> is entered when the employee name is requested. If an error is detected (invalid dept,...), the transaction also terminates. A connect is done after the information needed to perform database updates has been obtained from the user. A commit is executed after every successful insertion. 47 A2 14UR Rev03 D-1

146 ORACLE7/TDS User's Guide Note that in the first commitment unit, two CONNECT statements are executed: one to perform internal checking and the other in the standard insertion processing. It does not result in an error. When executing the second CONNECT statement, the SQL*Net context cache manager retrieves the context allocated for the commitment, retrieves an active connection with the same profile and thus skips the connection processing. In the statements shown in the rest of this Appendix, some lines were too long to fit in this manual. These lines have either been folded or have had some spaces suppressed. 001 IDENTIFICATION DIVISION. 002 * 003 PROGRAM-ID. SAMPLE. 004 * 005 ENVIRONMENT DIVISION. 006 * 007 CONFIGURATION SECTION. 008 SOURCE-COMPUTER. BULL-DPS OBJECT-COMPUTER. BULL-DPS * 011 DATA DIVISION. 012 * 013 WORKING-STORAGE SECTION. 014 * 015 * 016 EXEC SQL BEGIN DECLARE SECTION END-EXEC. 017 * USERID PIC X(20) VALUE SPACES PASSWORD PIC X(20) VALUE SPACES HOST PIC X(20) VALUE SPACES PEMPNO PIC S9(9) COMP-2 VALUE IEMPNO PIC S9(4) COMP-1 VALUE ENAMESIZE PIC S9999 COMP-1 VALUE JOBSIZE PIC S9999 COMP-1 VALUE DNAMESIZE PIC S9999 COMP-1 VALUE PENAME PIC X(12) VALUE SPACES PJOB PIC X(12) VALUE SPACES PSAL PIC S99999 COMP-3 VALUE PDEPTNO PIC S9999 COMP-1 VALUE PDNAME PIC X(15) VALUE SPACES. 031 * 032 EXEC SQL END DECLARE SECTION END-EXEC. 033 * 034 EXEC SQL INCLUDE SQLCA END-EXEC. 035 ********************************************************* 036 ********** INPUT PARAMETERS ********** 037 ********************************************************* D-2 47 A2 14UR Rev03

147 The SAMPLE Transaction 038 * RCV-BUFF TXNAME PIC X(7) RCV-PARAMS PIC X(73). 042 * ENAME-L PIC S9999 COMP-1 VALUE JOB-L PIC S9999 COMP-1 VALUE DNAME-L PIC S9999 COMP-1 VALUE EMPNOX PIC ZZZZZ9 DISPLAY DEPTNOX PIC X(4) DISPLAY DEPTNON PIC S9999 DISPLAY SALX PIC X(5) DISPLAY SALU PIC S99999 DISPLAY SALN PIC S99999 DISPLAY SIGN LEADING SEPARATE. 052 * EMPNO-N PIC X(6) VALUE ":EMPNO" ENAME-N PIC X(6) VALUE ":ENAME" JOB-N PIC X(4) VALUE ":JOB" SAL-N PIC X(4) VALUE ":SAL" DEPTNO-N PIC X(7) VALUE ":DEPTNO". 058 * 059 ********************************************************* 060 ********** MESSAGES ********** 061 ********************************************************* 062 * ASK-EMP PIC X(23) VALUE "Enter employee name: " ASK-JOB PIC X(23) VALUE "Enter employee job: " ASK-SAL PIC X(23) VALUE "Enter employee salary: " ASK-DEPTNO PIC X(23) VALUE "Enter employee dept: ". 067 * SND-BUFF PIC X(80) SWITCHES WS-NO-DATA PIC X(3) VALUE "YES" RCV-NO-DATA VALUE "YES" RCV-DATA VALUE "NO". 073 * SND-LVL PIC 9 VALUE NUM-DISPLAY PIC * 077 LINKAGE SECTION. 078 COPY TDS-STORAGE. 079 COPY CONSTANT-STORAGE PRIVATE-STORAGE TX-USERID PIC X(20) TX-PASSWORD PIC X(20) TX-HOST PIC X(20) TX-PEMPNO PIC S9(9) COMP TX-PENAME PIC X(12) TX-PJOB PIC X(12) TX-PSAL PIC S99999 COMP TX-PDEPTNO PIC S9999 COMP A2 14UR Rev03 D-3

148 ORACLE7/TDS User's Guide TURN PIC * 091 COMMUNICATION SECTION. 092 COPY COMMUNIC-SECTION. 093 * 094 PROCEDURE DIVISION USING TDS-STORAGE CONSTANT-STORAGE 095 PRIVATE-STORAGE. 096 A000-CODE SECTION. 097 A001-BEGIN. 098 PERFORM B100-RECEIVE. 099 MOVE "SAMPLE" TO NEXT-TPR. 100 IF PRIOR-TPR = SPACES 101 MOVE 0 TO TX-PEMPNO 102 MOVE SPACES TO TX-USERID 103 MOVE SPACES TO TX-PASSWORD 104 MOVE SPACES TO TX-HOST 105 IF RCV-PARAMS = SPACES 106 MOVE SPACES TO NEXT-TPR 107 STRING " Invalid Connection parameters " CR LF 108 DELIMITED BY SIZE INTO SND-BUFF 109 PERFORM B100-SEND 110 GO TO END-OF-TPR 111 ELSE 112 UNSTRING RCV-PARAMS DELIMITED BY "/" 113 INTO TX-USERID TX-PASSWORD TX-HOST 114 END-IF 115 PERFORM ORA-CONNECT 116 PERFORM INTERNAL-CHECKING 117 MOVE 23 TO LENGTH-OUT 118 STRING ASK-EMP DELIMITED BY SIZE INTO SND-BUFF 119 PERFORM B100-SEND 120 MOVE 1 TO TURN 121 GO TO END-OF-TPR 122 END-IF 123 GO TO T1, T2, T3, T4 DEPENDING ON TURN. 124 * 125 T IF WS-NO-DATA = "YES" 127 MOVE SPACES TO NEXT-TPR 128 MOVE 23 TO LENGTH-OUT 129 STRING " End of Insertion " CR LF 130 DELIMITED BY SIZE INTO SND-BUFF 131 PERFORM B100-SEND 132 GO TO END-OF-TPR 133 END-IF 134 MOVE RCV-BUFF TO TX-PENAME. 135 MOVE 23 TO LENGTH-OUT. 136 STRING ASK-JOB DELIMITED BY SIZE INTO SND-BUFF. 137 PERFORM B100-SEND. 138 MOVE 2 TO TURN. 139 GO TO END-OF-TPR. D-4 47 A2 14UR Rev03

149 The SAMPLE Transaction 140 T MOVE RCV-BUFF TO TX-PJOB. 142 MOVE 23 TO LENGTH-OUT. 143 STRING ASK-SAL DELIMITED BY SIZE INTO SND-BUFF. 144 PERFORM B100-SEND. 145 MOVE 3 TO TURN. 146 GO TO END-OF-TPR. 147 T MOVE RCV-BUFF TO SALX. 149 UNSTRING SALX DELIMITED BY SPACE INTO SALU. 150 MOVE SALU TO SALN. 151 MOVE SALN TO TX-PSAL. 152 PERFORM ASK-DEPT. 153 MOVE 4 TO TURN. 154 GO TO END-OF-TPR. 155 T MOVE RCV-BUFF TO DEPTNOX. 157 UNSTRING DEPTNOX DELIMITED BY SPACE INTO DEPTNON. 158 MOVE DEPTNON TO TX-PDEPTNO. 159 PERFORM ORA-CONNECT. 160 PERFORM CHECK-DEPT. 161 PERFORM INSERT-RECORD. 162 MOVE 23 TO LENGTH-OUT. 163 STRING ASK-EMP DELIMITED BY SIZE INTO SND-BUFF. 164 PERFORM B100-SEND. 165 MOVE 1 TO TURN. 166 GO TO END-OF-TPR. 167 * 168 EXEC SQL WHENEVER SQLWARNING CONTINUE END-EXEC. 169 EXEC SQL WHENEVER SQLERROR GOTO ORA-ERR END-EXEC. 170 EXEC SQL WHENEVER NOT FOUND GOTO ORA-ERR END-EXEC. 171 * 172 * ***************** ORA-CONNECT ********************* 173 ORA-CONNECT. 174 * 175 MOVE TX-USERID TO USERID. 176 MOVE TX-PASSWORD TO PASSWORD. 177 MOVE TX-HOST TO HOST. 178 EXEC SQL 179 CONNECT :USERID IDENTIFIED BY :PASSWORD 180 USING :HOST 181 END-EXEC. 182 STRING " Connected " LF CR 183 DELIMITED BY SIZE INTO SND-BUFF. 184 PERFORM B100-SENDLVL * 186 * 187 * ***************** INTERNAL-CHECKING ***************** 188 INTERNAL-CHECKING. 189 * 190 * RETRIEVE THE CURRENT MAXIMUM EMPLOYEE NUMBER 47 A2 14UR Rev03 D-5

150 ORACLE7/TDS User's Guide 191 * 192 EXEC SQL SELECT NVL(MAX(EMPNO),0) INTO :PEMPNO:IEMPNO 194 FROM EMP 195 END-EXEC. 196 * 197 * CHECK TO SEE THAT EMPLOYEE NAME, JOB AND DEPT. NAME 198 * FIT IN THE BUFFER. 199 * 200 EXEC SQL SELECT WIDTH 201 INTO :ENAMESIZE 202 FROM SYS.COL 203 WHERE TNAME = 'EMP' AND CNAME = 'ENAME' 204 END-EXEC. 205 * 206 IF ENAMESIZE > ENAME-L 207 STRING "ENAME too large for buffer. Call your supervisor." 208 LF CR DELIMITED BY SIZE INTO SND-BUFF 209 PERFORM B100-SEND 210 MOVE SPACES TO NEXT-TPR 211 GO TO END-OF-TPR 212 END-IF 213 * 214 EXEC SQL SELECT WIDTH 215 INTO :JOBSIZE 216 FROM SYS.COL 217 WHERE TNAME = 'EMP' AND CNAME = 'JOB' 218 END-EXEC. 219 * 220 IF JOBSIZE > JOB-L 221 STRING "JOB too large for buffer. Call your supervisor." 222 LF CR DELIMITED BY SIZE INTO SND-BUFF 223 PERFORM B100-SEND 224 MOVE SPACES TO NEXT-TPR 225 GO TO END-OF-TPR 226 END-IF 227 * 228 EXEC SQL SELECT WIDTH 229 INTO :DNAMESIZE 230 FROM SYS.COL 231 WHERE TNAME = 'DEPT' AND CNAME = 'DNAME' 232 END-EXEC. 233 * 234 IF DNAMESIZE > DNAME-L 235 STRING "DEPT is too large for buffer. Call your supervisor." 236 LF CR DELIMITED BY SIZE INTO SND-BUFF 237 PERFORM B100-SEND 238 MOVE SPACES TO NEXT-TPR D-6 47 A2 14UR Rev03

151 The SAMPLE Transaction 239 GO TO END-OF-TPR 240 END-IF. 241 * 242 * ********************* ASK-DEPT ********************** 243 * 244 ASK-DEPT. 245 MOVE 23 TO LENGTH-OUT. 246 STRING ASK-DEPTNO DELIMITED BY SIZE INTO SND-BUFF. 247 PERFORM B100-SEND. 248 * 249 * 250 * ********************* CHECK-DEPT ********************* 251 CHECK-DEPT. 252 * 253 * CHECK FOR A VALID DEPARTMENT NUMBER 254 * 255 MOVE SPACES TO PDNAME. 256 MOVE TX-PDEPTNO TO PDEPTNO. 257 * 258 EXEC SQL WHENEVER NOT FOUND GOTO NO-SUCHDEPT END-EXEC. 259 EXEC SQL SELECT DNAME 260 INTO :PDNAME 261 FROM DEPT 262 WHERE DEPTNO=:PDEPTNO 263 END-EXEC. 264 * 265 * 266 * ***************** INSERT-RECORD ********************** 267 INSERT-RECORD. 268 * 269 MOVE TX-PENAME TO PENAME. 270 MOVE TX-PJOB TO PJOB. 271 MOVE TX-PSAL TO PSAL. 272 MOVE TX-PEMPNO TO PEMPNO. 273 EXEC SQL WHENEVER NOT FOUND GOTO ORA-ERR END-EXEC 274 EXEC SQL INSERT INTO EMP (EMPNO,ENAME,JOB,SAL,DEPTNO) 275 VALUES (:PEMPNO,:PENAME,:PJOB,:PSAL,:PDEPTNO) 276 END-EXEC. 277 * 278 MOVE PEMPNO TO EMPNOX. 279 STRING PENAME, " added to the ", PDNAME, 280 " department as employee number ", EMPNOX CR LF 281 DELIMITED BY SIZE INTO SND-BUFF. 282 PERFORM B100-SENDLVL * 284 * MAKE SURE THAT EACH RECORD IS COMMITTED TO THE DATABASE. 285 * 286 EXEC SQL 287 COMMIT WORK 288 END-EXEC. 47 A2 14UR Rev03 D-7

152 ORACLE7/TDS User's Guide 289 * 290 ADD 10 TO TX-PEMPNO. 291 * 292 * ********************* RECEIVE ************************* 293 B100-RECEIVE. 294 MOVE SYMBOLIC-QUEUE TO QUEUE-IN. 295 MOVE SPACES TO RCV-BUFF. 296 MOVE 80 TO LENGTH-IN. 297 MOVE "NO" TO WS-NO-DATA. 298 RECEIVE CD-IN MESSAGE INTO RCV-BUFF 299 NO DATA MOVE "YES" TO WS-NO-DATA. 300 IF STATUS-IN NOT = "00" 301 MOVE SPACES TO NEXT-TPR 302 DISPLAY "*** RECEIVE NON OK *** STATUS KEY = ", 303 STATUS-IN UPON ALTERNATE CONSOLE 304 GO TO END-OF-TPR. 305 IF RCV-BUFF = SPACES MOVE "YES" TO WS-NO-DATA. 306 MOVE SPACES TO SND-BUFF. 307 MOVE SOURCE-IN TO DEST-OUT. 308 MOVE 1 TO COUNT-OUT. 309 MOVE 80 TO LENGTH-OUT. 310 * 311 * 312 * ********************* SEND ************************** 313 B100-SEND. 314 MOVE 3 TO SND-LVL. 315 SEND CD-OUT FROM SND-BUFF WITH SND-LVL. 316 IF STATUS-OUT NOT = "00" 317 DISPLAY "*** SEND NOT OK *** STATUS KEY = " 318 STATUS-OUT UPON ALTERNATE CONSOLE. 319 MOVE SPACES TO SND-BUFF. 320 * 321 * 322 B100-SENDLVL MOVE 2 TO SND-LVL. 324 SEND CD-OUT FROM SND-BUFF WITH SND-LVL AFTER ADVANCING IF STATUS-OUT NOT = "00" 326 DISPLAY "*** SEND NOT OK *** STATUS KEY = " 327 STATUS-OUT UPON ALTERNATE CONSOLE. 328 MOVE SPACES TO SND-BUFF. 329 * 330 ******************************************************** 331 * DISPLAY ORACLE ERROR NOTICE. 332 ******************************************************** 333 ORA-ERR. 334 * 335 STRING "You have encountered an ORACLE error." CR LF 336 DELIMITED BY SIZE INTO SND-BUFF. 337 PERFORM B100-SENDLVL MOVE SQLCODE TO NUM-DISPLAY. D-8 47 A2 14UR Rev03

153 The SAMPLE Transaction 339 STRING "SQLCODE: ", NUM-DISPLAY CR LF 340 DELIMITED BY SIZE INTO SND-BUFF. 341 PERFORM B100-SENDLVL STRING "ERRMSG: ", SQLERRMC CR LF 343 DELIMITED BY SIZE INTO SND-BUFF. 344 PERFORM B100-SEND. 345 MOVE SPACES TO NEXT-TPR. 346 GO TO END-OF-TPR. 347 * 348 NO-SUCHDEPT. 349 STRING "No such department: ", DEPTNOX, 350 " Insertion has failed..." CR LF 351 DELIMITED BY SIZE INTO SND-BUFF. 352 PERFORM B100-SENDLVL MOVE 5 TO TURN. 354 GO TO END-OF-TPR. 355 * 356 * 357 END-OF-TPR. 358 EXIT PROGRAM. 47 A2 14UR Rev03 D-9

154 ORACLE7/TDS User's Guide D A2 14UR Rev03

155 E. The FETCH Transaction The FETCHDEM program shows how to handle an ORACLE cursor with terminal conversation. The TPR fetches the ROWIDs of the tuples which match the WHERE condition; then re-fetches the tuples one at a time using the ROWIDs. It assumes that no selected tuple is deleted while the transaction is executing, so that the rowids stay valid. If your working directory has been set up correctly, you can prepare the FETCH transaction by following these steps: PCC INAME=FETCHDEM HOST=COBOL IRECLEN=132 INCLUDE=INSTALLDIR.SL; CBL FETCHDEM_PCC.SL LEVEL=NSTD CARDID=0 WARN=NO; LK FETCH SM OUTLIB=MYTDS.SMLIB COMFILE=MYTDS.SLLIB..TP7LINKTPR; Add the USE ORACLE clause, and assign a message clause to the FETCH TPR, in the STDS file of your TDS application. Log on to your TDS application and start the FETCH transaction, with valid parameters to connect to the ORACLE database: FETCH username/password/host The program queries the user as follows: Enter WHERE clause for the following statement: 'Select ENAME, SAL from EMP where' You may answer (for example) deptno=10 The program displays the statement executed, the number of selected tuples, the different ways to control the transaction's processing, and then the first selected tuple: 47 A2 14UR Rev03 E-1

156 ORACLE7/TDS User's Guide Select ENAME, SAL from EMP where deptno= records selected To go on, say + To stop current display, say / To exit the transaction, say STOP NAME SALARY CLARK Continue the transaction's processing by entering + or /, or stop it by entering STOP. 001 IDENTIFICATION DIVISION. 002 * 003 PROGRAM-ID. FETCH. 004 * 005 ENVIRONMENT DIVISION. 006 * 007 CONFIGURATION SECTION. 008 SOURCE-COMPUTER. BULL-DPS OBJECT-COMPUTER. BULL-DPS * 011 DATA DIVISION. 012 * 013 WORKING-STORAGE SECTION. 014 ********************************************************* 015 ********** ORACLE DECLARE SECTION ********** 016 ********************************************************* 017 * 018 EXEC SQL BEGIN DECLARE SECTION END-EXEC. 019 * USERID PIC X(15) VALUE SPACES PASSWORD PIC X(15) VALUE SPACES HOST PIC X(12) VALUE SPACES FINAL-SQL-STRING PIC X(100) VALUE SPACES ROWID PIC X(18) VALUE SPACES SAL PIC S9(9) COMP-2 VALUE ZERO ENAME PIC X(15) VALUE SPACES. 027 * 028 EXEC SQL END DECLARE SECTION END-EXEC. 029 * 030 EXEC SQL DECLARE DB1 DATABASE END-EXEC. 031 * 032 EXEC SQL INCLUDE SQLCA END-EXEC. E-2 47 A2 14UR Rev03

157 The FETCH Transaction 033 ********************************************************* 034 ********** INPUT PARAMETERS ********** 035 ********************************************************* 036 * RCV-BUFF TXNAME PIC X(6) RCV-PARAMS PIC X(74). 040 * 041 ********************************************************* 042 ********** MESSAGES ********** 043 ********************************************************* 044 * SND-RESPONSES SND-SAL PIC -9(10) SND-TX-END PIC X(18) 048 VALUE "End of Transaction" SND-SELECT PIC X(32) 050 VALUE "Select ENAME, SAL from EMP where" SND-SELECTED PIC X(17) 052 VALUE " records selected" SND-WHERE PIC X(47) 054 VALUE "Enter WHERE clause for the following statement:" SND-NA-SAL PIC X(32) 056 VALUE " NAME SALARY" SND-LINE PIC X(32) 058 VALUE " " SND-END-SEL PIC X(16) 060 VALUE "End of selection" SND-TOO-MANY PIC X(31) 062 VALUE "More than 220 selected records." SND-RW PIC X(7) 064 VALUE "ROWID= " SND-DISAPPEARED PIC X(18) 066 VALUE " has disappeared!" SND-GO-ON PIC X(32) 068 VALUE "To go on, say +" SND-SLASH PIC X(32) 070 VALUE "To stop current display, say /" SND-STOP PIC X(35) 072 VALUE "To exit the transaction, say STOP" SND-INV-INPUT PIC X(20) 074 VALUE "Invalid input string" SND-OPNERR PIC X(18) 076 VALUE "Open cursor error:" SND-FETCHERR PIC X(17) 078 VALUE "Exec fetch error:" SND-CNCTERR PIC X(14) 080 VALUE "Connect error:" SND-PREPERR PIC X(14) 082 VALUE "Prepare error:". 47 A2 14UR Rev03 E-3

158 ORACLE7/TDS User's Guide SND-CLOSERR PIC X(12) 084 VALUE "Close error:". 085 * SND-BUFF PIC X(150). 087 * 088 ********************************************************* 089 ********** WORKING VARIABLES ********** 090 ********************************************************* 091 * SEL-ROWID PIC X(41) 093 VALUE "Select ROWIDTOCHAR(rowid) from emp where " SWITCHES WS-NO-DATA PIC X(3) VALUE "YES" RCV-NO-DATA VALUE "YES" RCV-DATA VALUE "NO". 098 * SND-LVL PIC * 101 ********************************************************* 102 ********** LINKAGE SECTION ********** 103 ********************************************************* 104 * 105 LINKAGE SECTION. 106 COPY TDS-STORAGE. 107 COPY CONSTANT-STORAGE PRIV-AND-TX-STORAGE PRIVATE-STORAGE PIC X(1024) TRANSACTION-STORAGE ID-DB1 PIC S9(9) COMP TX-USR PIC X(15) TX-PWD PIC X(15) TX-HST PIC X(12) TX-CUR-FETCH PIC X(1) TX-EGI PIC X(1) TX-NB-ROWID PIC 9(3) TX-CUR-ROWNB PIC 9(3) TX-ROWID PIC X(18) OCCURS 220 TIMES. 120 * 121 COMMUNICATION SECTION. 122 COPY COMMUNIC-SECTION. 123 * 124 PROCEDURE DIVISION USING TDS-STORAGE CONSTANT-STORAGE 125 PRIV-AND-TX-STORAGE. 126 ********************************************************* 127 ********** M A I N P R O G R A M ********** 128 ********************************************************* 129 * 130 A100-FETCH. 131 MOVE 1 TO SND-LVL. 132 MOVE SYMBOLIC-QUEUE TO QUEUE-IN. 133 MOVE SPACES TO RCV-BUFF. E-4 47 A2 14UR Rev03

159 The FETCH Transaction 134 MOVE 80 TO LENGTH-IN. 135 MOVE "NO" TO WS-NO-DATA. 136 RECEIVE CD-IN MESSAGE INTO RCV-BUFF 137 NO DATA MOVE "YES" TO WS-NO-DATA. 138 IF STATUS-IN NOT = "00" 139 MOVE SPACES TO NEXT-TPR 140 DISPLAY "*** RECEIVE NON OK *** STATUS KEY = ", 141 STATUS-IN UPON ALTERNATE CONSOLE 142 GO TO END-OF-END. 143 IF RCV-PARAMS = SPACES MOVE "YES" TO WS-NO-DATA. 144 MOVE SOURCE-IN TO DEST-OUT. 145 MOVE 1 TO COUNT-OUT. 146 MOVE "FETCH" TO NEXT-TPR. 147 * 148 IF PRIOR-TPR = SPACES 149 PERFORM B100-RCV-PARAMS 150 PERFORM B300-ASK-WHERE 151 GO TO END-OF-CU. 152 * 153 IF TX-EGI = "Y" AND RCV-BUFF = "STOP" 154 MOVE SPACES TO NEXT-TPR 155 MOVE 18 TO LENGTH-OUT 156 STRING SND-TX-END LF CR DELIMITED BY SIZE 157 INTO SND-BUFF 158 PERFORM D100-SEND 159 GO TO END-OF-CU. 160 * 161 IF TX-CUR-FETCH = "N" 162 PERFORM B400-FETCH-ROWID THRU B400-END 163 MOVE "N" TO TX-EGI 164 MOVE 2 TO LENGTH-OUT 165 MOVE 2 TO SND-LVL 166 STRING LF CR DELIMITED BY SIZE INTO SND-BUFF 167 PERFORM D100-SEND 168 GO TO END-OF-END. 169 * 170 IF TX-EGI = "N" OR RCV-BUFF = "+" 171 PERFORM B500-SELECT THRU B500-END 172 GO TO END-OF-CU. 173 * 174 IF RCV-BUFF NOT = "/" 175 MOVE 22 TO LENGTH-OUT 176 STRING SND-INV-INPUT LF CR DELIMITED BY SIZE 177 INTO SND-BUFF 178 PERFORM D100-SEND. 179 * 180 PERFORM B700-SEND-ENDSEL. 181 PERFORM B300-ASK-WHERE 182 GO TO END-OF-CU. 183 * 184 ********************************************************* 47 A2 14UR Rev03 E-5

160 ORACLE7/TDS User's Guide 185 ********** E N D O F M A I N P R O G R A M ******** 186 ********************************************************* 187 * 188 B100-RCV-PARAMS. 189 ********************************************************* 190 ********** RECEIVE INPUT PARAMETERS ********** 191 ********************************************************* 192 * 193 MOVE SPACES TO TX-USR. 194 MOVE SPACES TO TX-PWD. 195 MOVE SPACES TO TX-HST. 196 IF RCV-NO-DATA 197 MOVE "SCOTT" TO TX-USR 198 MOVE "TIGER" TO TX-PWD 199 ELSE 200 UNSTRING RCV-PARAMS DELIMITED BY "/" 201 INTO TX-USR TX-PWD TX-HST. 202 * 203 B200-ORACLE-CONNECT. 204 ********************************************************* 205 ********** ORACLE CONNECTION REQUEST ********** 206 ********************************************************* 207 * 208 MOVE TX-USR TO USERID. 209 MOVE TX-PWD TO PASSWORD. 210 MOVE TX-HST TO HOST. 211 EXEC SQL 212 CONNECT :USERID IDENTIFIED BY :PASSWORD 213 AT DB1 USING :HOST 214 END-EXEC. 215 * 216 IF SQLCODE IS LESS THAN 0 GO TO Z100-LOG-ERROR. 217 * 218 B300-ASK-WHERE. 219 ********************************************************* 220 ********* ASK FOR THE STATEMENT "WHERE" ******** 221 ********************************************************* 222 MOVE 89 TO LENGTH-OUT. 223 STRING SND-WHERE CR LF " '" SND-SELECT "'" LF CR 224 DELIMITED BY SIZE INTO SND-BUFF. 225 PERFORM D100-SEND. 226 MOVE "N" TO TX-CUR-FETCH. 227 * 228 B400-FETCH-ROWID. 229 * 230 PERFORM B200-ORACLE-CONNECT. 231 * 232 ********************************************************* 233 ********** PREPARE SELECT STATEMENT ********** 234 ********************************************************* 235 STRING SND-SELECT " " RCV-BUFF DELIMITED BY SIZE E-6 47 A2 14UR Rev03

161 The FETCH Transaction 236 INTO FINAL-SQL-STRING. 237 MOVE 102 TO LENGTH-OUT. 238 STRING FINAL-SQL-STRING LF CR DELIMITED BY SIZE 239 INTO SND-BUFF. 240 PERFORM D100-SEND. 241 MOVE SPACES TO SND-BUFF. 242 MOVE SPACES TO FINAL-SQL-STRING. 243 STRING SEL-ROWID RCV-BUFF DELIMITED BY SIZE 244 INTO FINAL-SQL-STRING. 245 * 246 EXEC SQL AT DB1 247 DECLARE S1 STATEMENT END-EXEC. 248 EXEC SQL 249 PREPARE S1 FROM :FINAL-SQL-STRING 250 END-EXEC. 251 IF SQLCODE IS LESS THAN 0 GO TO Z200-PREP-ERROR. 252 * 253 EXEC SQL DECLARE S2 CURSOR FOR S1 END-EXEC. 254 EXEC SQL OPEN S2 END-EXEC. 255 IF SQLCODE IS LESS THAN 0 GO TO Z300-OPEN-ERROR. 256 * 257 MOVE "Y" TO TX-CUR-FETCH. 258 MOVE 0 TO TX-NB-ROWID. 259 MOVE 1 TO TX-CUR-ROWNB. 260 ********************************************************* 261 ********** EXECUTION OF FETCH STATEMENTS ******** 262 ********************************************************* 263 BOUCLE. 264 EXEC SQL FETCH S2 INTO :ROWID END-EXEC. 265 IF SQLCODE IS LESS THAN 0 GO TO Z400-FETCH-ERROR. 266 IF SQLCODE = MOVE 22 TO LENGTH-OUT 268 STRING TX-NB-ROWID SND-SELECTED LF CR 269 DELIMITED BY SIZE INTO SND-BUFF 270 GO TO B400-SEND. 271 IF TX-NB-ROWID IS LESS THAN ADD 1 TO TX-NB-ROWID 273 MOVE ROWID TO TX-ROWID (TX-NB-ROWID) 274 GO TO BOUCLE. 275 STRING CR LF SND-TOO-MANY DELIMITED BY SIZE 276 INTO SND-BUFF. 277 B400-SEND. 278 PERFORM D100-SEND. 279 EXEC SQL CLOSE S2 END-EXEC. 280 IF SQLCODE IS LESS THAN 0 GO TO Z500-CLOSE-ERROR. 281 CALL "DFCMIT". 282 IF TX-NB-ROWID = PERFORM B300-ASK-WHERE 284 GO TO END-OF-TPR. 285 IF TX-NB-ROWID > STRING SND-GO-ON LF CR SND-SLASH LF CR SND-STOP LF CR 47 A2 14UR Rev03 E-7

162 ORACLE7/TDS User's Guide 287 DELIMITED BY SIZE INTO SND-BUFF 288 MOVE 103 TO LENGTH-OUT 289 PERFORM D100-SEND. 290 B400-END. 291 EXIT. 292 * 293 B500-SELECT. 294 ********************************************************* 295 ****** EXECUTION OF SELECT STATEMENT (WITH ROWID) ******* 296 ********************************************************* 297 * 298 PERFORM B200-ORACLE-CONNECT. 299 * 300 MOVE TX-ROWID (TX-CUR-ROWNB) TO ROWID. 301 * 302 EXEC SQL AT DB1 303 SELECT ENAME, SAL INTO :ENAME, :SAL FROM EMP 304 WHERE ROWID = CHARTOROWID(:ROWID) 305 END-EXEC. 306 * 307 IF SQLCODE IS LESS THAN 0 PERFORM Z400-FETCH-ERROR. 308 IF SQLCODE = STRING SND-RW TX-ROWID (TX-CUR-ROWNB) SND-DISAPPEARED 310 LF CR DELIMITED BY SIZE INTO SND-BUFF 311 MOVE 45 TO LENGTH-OUT 312 PERFORM D100-SEND 313 ELSE 314 MOVE 80 TO LENGTH-OUT 315 STRING " " LF CR SND-NA-SAL LF CR SND-LINE LF CR 316 DELIMITED BY SIZE INTO SND-BUFF 317 PERFORM D100-SEND 318 MOVE SAL TO SND-SAL 319 MOVE 32 TO LENGTH-OUT 320 STRING " " ENAME " " SND-SAL DELIMITED BY SIZE 321 INTO SND-BUFF 322 PERFORM D100-SEND. 323 * 324 ADD 1 TO TX-CUR-ROWNB. 325 IF TX-CUR-ROWNB > TX-NB-ROWID 326 PERFORM B700-SEND-ENDSEL 327 PERFORM B300-ASK-WHERE. 328 B500-END. 329 EXIT. 330 * 331 B700-SEND-ENDSEL. 332 ********************************************************* 333 ********** SEND STRING : "End of selection" ********* 334 ********************************************************* 335 MOVE 20 TO LENGTH-OUT. E-8 47 A2 14UR Rev03

163 The FETCH Transaction 336 STRING LF CR SND-END-SEL LF CR DELIMITED BY SIZE 337 INTO SND-BUFF. 338 PERFORM D100-SEND. 339 * 340 D100-SEND. 341 ********************************************************* 342 ********** SEND ROUTINE ********** 343 ********************************************************* 344 SEND CD-OUT FROM SND-BUFF WITH SND-LVL AFTER ADVANCING IF STATUS-OUT NOT = "00" 346 DISPLAY "*** SEND NOT OK *** STATUS KEY = " 347 STATUS-OUT UPON ALTERNATE CONSOLE. 348 * 349 ********************************************************* 350 ********** ERROR ROUTINES ********** 351 ********************************************************* 352 Z100-LOG-ERROR. 353 STRING SND-CNCTERR LF CR SQLERRMC LF CR DELIMITED BY SIZE 354 INTO SND-BUFF. 355 COMPUTE LENGTH-OUT = SQLERRML + 18; 356 PERFORM D100-SEND. 357 STRING USERID PASSWORD HOST LF CR DELIMITED BY SIZE 358 INTO SND-BUFF. 359 MOVE 40 TO LENGTH-OUT. 360 PERFORM D100-SEND. 361 MOVE SPACES TO NEXT-TPR. 362 GO TO END-OF-CU. 363 * 364 Z101-ERROR. 365 PERFORM D100-SEND. 366 PERFORM Z001-ERROR-ROUTINE. 367 EXEC SQL AT DB1 ROLLBACK WORK END-EXEC. 368 IF SQLCODE IS LESS THAN 0 PERFORM Z001-ERROR-ROUTINE. 369 PERFORM B700-SEND-ENDSEL. 370 PERFORM B300-ASK-WHERE. 371 GO TO END-OF-TPR. 372 * 373 Z200-PREP-ERROR. 374 STRING LF CR SND-PREPERR DELIMITED BY SIZE 375 INTO SND-BUFF. 376 MOVE 16 TO LENGTH-OUT. 377 PERFORM Z101-ERROR. 378 * 379 Z300-OPEN-ERROR. 380 STRING LF CR SND-OPNERR DELIMITED BY SIZE 381 INTO SND-BUFF. 382 MOVE 20 TO LENGTH-OUT. 383 PERFORM Z101-ERROR. 47 A2 14UR Rev03 E-9

164 ORACLE7/TDS User's Guide 384 * 385 Z400-FETCH-ERROR. 386 STRING LF CR SND-FETCHERR DELIMITED BY SIZE 387 INTO SND-BUFF. 388 MOVE 19 TO LENGTH-OUT. 389 PERFORM Z101-ERROR. 390 * 391 Z500-CLOSE-ERROR. 392 STRING LF CR SND-CLOSERR DELIMITED BY SIZE 393 INTO SND-BUFF. 394 MOVE 14 TO LENGTH-OUT. 395 PERFORM Z101-ERROR. 396 * 397 Z001-ERROR-ROUTINE. 398 STRING SQLERRMC LF CR DELIMITED BY SIZE INTO SND-BUFF. 399 COMPUTE LENGTH-OUT = 2 + SQLERRML. 400 PERFORM D100-SEND. 401 * 402 END-OF-CU. 403 CALL "DFCMIT". 404 * 405 END-OF-TPR. 406 MOVE "Y" TO TX-EGI. 407 MOVE 3 TO LENGTH-OUT. 408 STRING " " LF CR DELIMITED BY SIZE INTO SND-BUFF. 409 MOVE 3 TO SND-LVL. 410 PERFORM D100-SEND. 411 * 412 END-OF-END. 413 EXIT PROGRAM. E A2 14UR Rev03

165 F. The "ORATDS" Transaction The ORATDS transaction is used to dynamically tune ORACLE/TDS configuration parameters. The following program is the source of the transaction and shows how the call to the ORATCONF entry point is done. In the statements shown below, some lines were too long to fit in this manual. These lines were folded or some spaces were suppressed. All details on the use of the transaction, its parameters and their scope... are given in Chapter 4 of this guide. 001 IDENTIFICATION DIVISION. 002 * 003 PROGRAM-ID. ORATDS. 004 * 005 ENVIRONMENT DIVISION. 006 * 007 CONFIGURATION SECTION. 008 SOURCE-COMPUTER. BULL-DPS OBJECT-COMPUTER. BULL-DPS * 011 DATA DIVISION. 012 WORKING-STORAGE SECTION. 013 ****************************************************** 014 ********** INPUT PARAMETERS ********* 015 ****************************************************** 016 * RCV-BUFF TX-NAME PIC X(7) RCV-PARAMETERS PIC X(73). 020 * 021 ****************************************************** 022 ********** OUTPUT VALUES ********** 023 ****************************************************** 024 * SEND-BUFFER PIC X(80). 026 * O-PARAMS. 47 A2 14UR Rev03 F-1

166 ORACLE7/TDS User's Guide O-RTCD COMP O-MAXTIM COMP O-MAXWAT COMP O-TIMOUT COMP O-CSIZE COMP O-NCNCT COMP O-TRCLVL COMP O-MESSAGE O-MESS1 PIC X(65) O-LINE1 PIC X(1) O-MESSAGE O-MESS2 PIC X(65) O-LINE2 PIC X(1) D-TIMOUT PIC -(10) D-MAXTIM PIC -(10) D-MAXWAT PIC -(10) D-CSIZE PIC -(10) D-TRCLVL PIC -(10) SEND-TITLE PIC X(69) 048 VALUE "********** ORA/TDS Configuration **********" SEND-STATUS PIC X(69) 050 VALUE "********** ORA/TDS Layer Status **********" SEND-STARS PIC X(69) 052 VALUE "*********************************** **********************************" SEND-HYPHENS PIC X(69) 054 VALUE "* *" SEND-TIMOUT PIC X(30) 056 VALUE "* TIMOUT=" SEND-MAXTIM PIC X(30) 058 VALUE "* MAXTIM=" SEND-MAXWAT PIC X(30) 060 VALUE "* MAXWAT=" SEND-CSIZE PIC X(30) 062 VALUE "* CSIZE =" SEND-TRCLVL PIC X(30) 064 VALUE "* TRCLVL=" SEND-STARTMESS PIC X(2) 066 VALUE "* " SEND-ENDMESS PIC X(2) 068 VALUE " *" SEND-ENDLINE PIC X(28) 070 VALUE " *". 071 * 072 ****************************************************** 073 ********** ERROR MESSAGES ********** 074 ****************************************************** 075 * 076 * F-2 47 A2 14UR Rev03

167 The "ORATDS" Transaction 077 ****************************************************** 078 ********** ORACLE RESPONSES ********** 079 ****************************************************** 080 * 081 ****************************************************** 082 ********** WORKING VARIABLES ********** 083 ****************************************************** 084 * SEND-LEVEL PIC 9 VALUE DISPLAY-DONE PIC 9 VALUE * 088 LINKAGE SECTION. 089 COPY TDS-STORAGE. 090 COPY CONSTANT-STORAGE TRANSACTION-STORAGE I-PARAMS PIC X(73). 093 * 094 COMMUNICATION SECTION. 095 COPY COMMUNIC-SECTION. 096 * 097 PROCEDURE DIVISION USING TDS-STORAGE CONSTANT-STORAGE 098 TRANSACTION-STORAGE. 099 * 100 ****************************************************** 101 ********** RECEIVE INPUT PARAMETERS ********* 102 ****************************************************** 103 * 104 A001-RECEIVE. 105 MOVE SPACES TO RCV-PARAMETERS. 106 MOVE SYMBOLIC-QUEUE TO QUEUE-IN. 107 MOVE 80 TO LENGTH-IN. 108 RECEIVE CD-IN MESSAGE INTO RCV-BUFF 109 NO DATA MOVE SPACES TO RCV-PARAMETERS. 110 IF STATUS-IN NOT = "00" 111 DISPLAY "*** RECEIVE NON OK *** STATUS KEY = ", 112 STATUS-IN UPON ALTERNATE CONSOLE 113 GO TO END-OF-TPR. 114 MOVE SOURCE-IN TO DEST-OUT. 115 MOVE 1 TO COUNT-OUT. 116 MOVE 2 TO SEND-LEVEL. 117 MOVE 70 TO LENGTH-OUT. 118 * 119 GO TO A002-ORATDS. 120 * 121 ****************************************************** 122 ********** CALL ORACLE PRIMITIVE ********** 123 ****************************************************** 124 * 125 A002-ORATDS. 126 IF PRIOR-TPR NOT = CURRENT-TPR 47 A2 14UR Rev03 F-3

168 ORACLE7/TDS User's Guide 127 MOVE RCV-PARAMETERS TO I-PARAMS 128 ELSE MOVE I-PARAMS TO RCV-PARAMETERS. 129 CALL "ORATCONF" USING RCV-PARAMETERS O-PARAMS. 130 IF (O-RTCD = -1) 131 PERFORM A400-SEND-ENTETE 132 PERFORM A400-SEND-MESS. 133 IF O-RTCD = PERFORM A003-DISPLAY. 135 IF (O-RTCD = 2) OR (O-RTCD = 7) 136 MOVE 10 TO WAIT-TIME 137 MOVE CURRENT-TPR TO NEXT-TPR 138 IF PRIOR-TPR NOT = CURRENT-TPR 139 PERFORM A400-SEND-ENTETE 140 STRING SEND-STARTMESS O-MESS1 SEND-ENDMESS CR DELIMITED BY SIZE INTO SEND-BUFFER 141 PERFORM A005-SEND-BUFFER 142 GO TO END-OF-TPR 143 ELSE GO TO END-OF-TPR. 144 MOVE 2 TO SEND-LEVEL. 145 MOVE 70 TO LENGTH-OUT. 146 IF (DISPLAY-DONE = 0) 147 STRING SEND-STARS CR DELIMITED BY SIZE INTO SEND-BUFFER 148 PERFORM A005-SEND-BUFFER. 149 STRING SEND-STATUS CR DELIMITED BY SIZE INTO SEND-BUFFER 150 PERFORM A005-SEND-BUFFER. 151 STRING SEND-HYPHENS CR DELIMITED BY SIZE INTO SEND-BUFFER 152 PERFORM A005-SEND-BUFFER. 153 PERFORM A400-SEND-MESS. 154 * 155 * 156 A400-SEND-ENTETE. 157 STRING SEND-STARS CR DELIMITED BY SIZE INTO SEND-BUFFER 158 PERFORM A005-SEND-BUFFER 159 STRING SEND-TITLE CR DELIMITED BY SIZE INTO SEND-BUFFER 160 PERFORM A005-SEND-BUFFER 161 STRING SEND-HYPHENS CR DELIMITED BY SIZE INTO SEND-BUFFER 162 PERFORM A005-SEND-BUFFER. 163 * 164 A400-SEND-MESS. 165 STRING SEND-STARTMESS O-MESS1 SEND-ENDMESS CR DELIMITED BY SIZE INTO SEND-BUFFER 166 PERFORM A005-SEND-BUFFER 167 STRING SEND-STARTMESS O-MESS2 SEND-ENDMESS CR DELIMITED BY SIZE INTO SEND-BUFFER 168 PERFORM A005-SEND-BUFFER F-4 47 A2 14UR Rev03

169 The "ORATDS" Transaction 169 MOVE 3 TO SEND-LEVEL 170 MOVE 72 TO LENGTH-OUT 171 STRING SEND-STARS CR LF DELIMITED BY SIZE INTO SEND-BUFFER 172 GO TO A005-SEND-BUFFER. 173 * 174 ****************************************************** 175 ********** SEND ORACLE'S RESPONSE ********** 176 ****************************************************** 177 * 178 * 179 * 180 A003-DISPLAY. 181 MOVE 1 TO DISPLAY-DONE 182 MOVE 2 TO SEND-LEVEL 183 MOVE 70 TO LENGTH-OUT 184 PERFORM A400-SEND-ENTETE. 185 MOVE O-TIMOUT TO D-TIMOUT 186 MOVE O-MAXTIM TO D-MAXTIM 187 MOVE O-MAXWAT TO D-MAXWAT 188 MOVE O-CSIZE TO D-CSIZE 189 MOVE O-TRCLVL TO D-TRCLVL 190 STRING SEND-TIMOUT D-TIMOUT SEND-ENDLINE CR 191 DELIMITED BY SIZE INTO SEND-BUFFER 192 PERFORM A005-SEND-BUFFER 193 STRING SEND-MAXTIM D-MAXTIM SEND-ENDLINE CR 194 DELIMITED BY SIZE INTO SEND-BUFFER 195 PERFORM A005-SEND-BUFFER 196 STRING SEND-MAXWAT D-MAXWAT SEND-ENDLINE CR 197 DELIMITED BY SIZE INTO SEND-BUFFER 198 PERFORM A005-SEND-BUFFER 199 STRING SEND-CSIZE D-CSIZE SEND-ENDLINE CR 200 DELIMITED BY SIZE INTO SEND-BUFFER 201 PERFORM A005-SEND-BUFFER 202 STRING SEND-TRCLVL D-TRCLVL SEND-ENDLINE CR 203 DELIMITED BY SIZE INTO SEND-BUFFER 204 PERFORM A005-SEND-BUFFER 205 STRING SEND-STARS CR DELIMITED BY SIZE INTO SEND-BUFFER 206 PERFORM A005-SEND-BUFFER A005-SEND-BUFFER. 210 SEND CD-OUT FROM SEND-BUFFER WITH SEND-LEVEL AFTER ADVANCING IF STATUS-OUT IS NOT = "00" 212 DISPLAY "*** SEND NOT OK *** STATUS KEY = " 213 STATUS-OUT UPON ALTERNATE CONSOLE. 214 * 215 END-OF-TPR. 47 A2 14UR Rev03 F-5

170 ORACLE7/TDS User's Guide 216 EXIT PROGRAM. F-6 47 A2 14UR Rev03

171 G. Specialized Processors G.1 Specialized Processor Specifics The specialized processors (co- processors) are HRP (High Relational Performance), Backend Server, PSP (Parallel Specialized Processors) and CDP (Customer Dedicated Processor). It is outside the scope of this appendix to discuss details of the co-processor. Refer to other books as follows: For resource management specifics: see the ARM User's Guide, 47 A2 11US, and the System Operator's Guide, 47 A2 60UU, that cover GCOS 7-V6. For the associated console messages: see the GCOS 7-V6 Console Messages, 47 A2 61UU. For SBR specifics: see the System Behaviour Reporter documentation. G.2 TERMINOLOGY For Specialized Processors You may see the following terms used in documents that describe aspects of the specialized processors: CoPro step Standard step EPU, FPU, GPU A step that can use both specialized processors and standard processors. A step that can use only standard IPU processors. 3 groups of specialized processor starting from the use of CDPs. 47 A2 14UR Rev03 G-1

172 ORACLE7/TDS User's Guide IPU The standard "native" DPS 7000 processor able to execute any kind of process, including ORACLE. Chronological evolution of the specialized processors: HRP (and X-HRP) Backend Server PSP CDP High Relational Performance processor. Package including four HRP's. Parallel Specialized Processors. Customer Dedicated Processor. All the specialized processors (HRP, Backend Server and PSP) are available to ORACLE activities to improve the throughput of ORACLE applications. They provide a combination hardware, firmware, and software optimization for the execution of ORACLE processes (which can also use standard IPU's). G-2 47 A2 14UR Rev03

173 H. Example of the H_XAEVT Transaction IDENTIFICATION DIVISION. * PROGRAM-ID. XAEVT. * ENVIRONMENT DIVISION. * CONFIGURATION SECTION. SOURCE-COMPUTER. BULL-DPS7000. OBJECT-COMPUTER. BULL-DPS7000. * DATA DIVISION. WORKING-STORAGE SECTION. * ************************************************************* *********** INPUT PARAMETERS ********** ************************************************************* * 01 XAEVT-MSG. 02 TPR-NAME PIC X(12). 02 USER-NAME PIC X(12). 02 OCCUR-NB COMP TDS-XA-STATUS COMP XA-GLOBAL-STATUS COMP-1. ************************************************************* ***************** OUTPUT VALUES ********** ************************************************************* * 01 DESYNC-LINE PIC X(58) VALUE "* XA DESYNCHRONIZATION EVENT...*". 01 RESYNC-LINE PIC X(58) VALUE "*... XA RESYNCHRONIZATION. (CHECK RESULT). *". 01 TITLE-LINE PIC X(58) VALUE "* RM STATUS *". 01 STAR-LINE PIC X(58) VALUE "**************************************************". 01 DASH-LINE PIC X(58) VALUE "* *". 01 DBID-LINE. 47 A2 14UR Rev03 H-1

174 ORACLE7/TDS User's Guide 02 FILLER PIC X(12) VALUE "* dbid: ". 02 BUF-DBID PIC X(44). 02 FILLER PIC X(2) VALUE " *". 01 RMIDENT-LINE. 02 FILLER PIC X(12) VALUE "* rmid: ". 02 BUF-RMIDENT PIC X(44). 02 FILLER PIC X(2) VALUE " *". 01 STATUS-LINE. 02 FILLER PIC X(12) VALUE "* status: ". 02 BUF-STATUS PIC X(44). 02 FILLER PIC X(2) VALUE " *". 01 GBLFORID-LINE. 02 FILLER PIC X(12) VALUE "* gblforid: ". 02 BUF-GBLFORID PIC X(44). 02 FILLER PIC X(2) VALUE " *". * 01 RMLIST. 02 RMARRAY OCCURS 8 TIMES. 03 XA-GBLFORID PIC X(40). 03 XA-DBID PIC X(8). 03 XA-RMIDENT PIC X(44). 03 XA-STATUS COMP-1. * ************************************************************* ********** WORKING VARIABLES ********** ************************************************************* * 01 TDS-XA-STATUS-VALUES. 05 ROLLED-BACK COMP-1 VALUE COMMITTED COMP-1 VALUE XA-STATUS-VALUES. 05 OK COMP-1 VALUE RDONLY COMP-1 VALUE RETRY COMP-1 VALUE HEURMIX COMP-1 VALUE HEURRB COMP-1 VALUE HEURCOM COMP-1 VALUE HEURHAZ COMP-1 VALUE RB COMP-1 VALUE RMERR COMP-1 VALUE NOTA COMP-1 VALUE INVAL COMP-1 VALUE PROTO COMP-1 VALUE RMFAIL COMP-1 VALUE -7. * 77 O-RMNB COMP I COMP STATUS-STRING PIC X(18). 77 T-STATUS-STRING PIC X(8) VALUE "COMMIT". * LINKAGE SECTION. H-2 47 A2 14UR Rev03

175 Example of the H_XAEVT Transaction COPY TDS-STORAGE. COPY CONSTANT-STORAGE. * 01 TRANSACTION-STORAGE PIC X(100). COMMUNICATION SECTION. CD CDIN FOR INPUT SYMBOLIC QUEUE SQI MESSAGE DATE MDI MESSAGE TIME MTI SYMBOLIC SOURCE SSI TEXT LENGTH TLI END KEY EKI STATUS KEY SKI MESSAGE COUNT MCI. * PROCEDURE DIVISION USING TDS-STORAGE CONSTANT-STORAGE TRANSACTION-STORAGE. * ************************************************************* ********** RECEIVE INPUT PARAMETERS ********** ************************************************************* * A001-RECEIVE. MOVE SYMBOLIC-QUEUE TO SQI DISPLAY "XAEVT TRANSACTION ACTIVATED" UPON ALTERNATE CONSOLE. RECEIVE CDIN MESSAGE INTO XAEVT-MSG. IF SKI NOT = "00" GO ABORT. DISPLAY STAR-LINE UPON ALTERNATE CONSOLE. IF OCCUR-NB = 1 DISPLAY DESYNC-LINE UPON ALTERNATE CONSOLE ELSE DISPLAY RESYNC-LINE UPON ALTERNATE CONSOLE. DISPLAY STAR-LINE UPON ALTERNATE CONSOLE. IF TDS-XA-STATUS IS EQUAL TO ROLLED-BACK MOVE "ROLLBACK" TO T-STATUS-STRING. IF XA-GLOBAL-STATUS IS EQUAL TO OK MOVE "DONE" TO STATUS-STRING. IF XA-GLOBAL-STATUS IS EQUAL TO RETRY MOVE "RETRY" TO STATUS-STRING. IF XA-GLOBAL-STATUS IS EQUAL TO HEURCOM MOVE "HEURISTIC-COMMIT" TO STATUS-STRING. IF XA-GLOBAL-STATUS IS EQUAL TO HEURRB MOVE "HEURISTIC-ROLLBACK" TO STATUS-STRING. IF XA-GLOBAL-STATUS IS EQUAL TO HEURMIX MOVE "HEURISTIC-MIXED" TO STATUS-STRING. IF XA-GLOBAL-STATUS IS EQUAL TO HEURHAZ MOVE "HEURISTIC-HAZARD" TO STATUS-STRING. IF XA-GLOBAL-STATUS IS EQUAL TO RMERR MOVE "RMERR" TO STATUS-STRING. IF XA-GLOBAL-STATUS IS EQUAL TO RMFAIL MOVE "RMFAIL" TO STATUS-STRING. IF XA-GLOBAL-STATUS IS EQUAL TO NOTA 47 A2 14UR Rev03 H-3

176 ORACLE7/TDS User's Guide MOVE "NOTA" TO STATUS-STRING. DISPLAY "TPR-NAME: " TPR-NAME UPON ALTERNATE CONSOLE. DISPLAY "USER-NAME: " USER-NAME UPON ALTERNATE CONSOLE. DISPLAY "TDS-XA-STATUS: " T-STATUS-STRING UPON ALTERNATE CONSOLE. DISPLAY "XA-GLOBAL-STATUS: " STATUS-STRING UPON ALTERNATE CONSOLE. * ************************************************************* ********* CALL H_OR_XARMSOFCU PRIMITIVE ********* ************************************************************* * A002-ORACLE. CALL "H_OR_XARMSOFCU" USING ADDRESS OF RMLIST O-RMNB. IF O-RMNB NOT EQUAL TO 0 DISPLAY STAR-LINE UPON ALTERNATE CONSOLE DISPLAY TITLE-LINE UPON ALTERNATE CONSOLE DISPLAY STAR-LINE UPON ALTERNATE CONSOLE PERFORM PROCESS-RM TEST AFTER VARYING I FROM 1 BY 1 UNTIL I EQUAL O-RMNB DISPLAY STAR-LINE UPON ALTERNATE CONSOLE ELSE DISPLAY "ORA/TDS structures not initialized" UPON ALTERNATE CONSOLE END-IF. GO TO END-OF-TPR. * PROCESS-RM. IF I NOT EQUAL TO 1 DISPLAY DASH-LINE UPON ALTERNATE CONSOLE. MOVE XA-DBID (I) TO BUF-DBID. DISPLAY DBID-LINE UPON ALTERNATE CONSOLE. MOVE XA-RMIDENT (I) TO BUF-RMIDENT. DISPLAY RMIDENT-LINE UPON ALTERNATE CONSOLE. IF XA-STATUS (I) IS EQUAL TO RETRY MOVE "RETRY" TO BUF-STATUS. IF XA-STATUS (I) IS EQUAL TO HEURCOM MOVE "HEURISTIC-COMMIT" TO BUF-STATUS. IF XA-STATUS (I) IS EQUAL TO HEURRB MOVE "HEURISTIC-ROLLBACK" TO BUF-STATUS. IF XA-STATUS (I) IS EQUAL TO HEURMIX MOVE "HEURISTIC-MIXED" TO BUF-STATUS. IF XA-STATUS (I) IS EQUAL TO HEURHAZ MOVE "HEURISTIC-HAZARD" TO BUF-STATUS. IF XA-STATUS (I) IS EQUAL TO RMERR MOVE "RMERR" TO BUF-STATUS. IF XA-STATUS (I) IS EQUAL TO NOTA MOVE "NOTA" TO BUF-STATUS. IF XA-STATUS (I) IS EQUAL TO INVAL MOVE "INVAL" TO BUF-STATUS. IF XA-STATUS (I) IS EQUAL TO PROTO H-4 47 A2 14UR Rev03

177 Example of the H_XAEVT Transaction MOVE "PROTO" TO BUF-STATUS. IF XA-STATUS (I) IS EQUAL TO RMFAIL MOVE "RMFAIL" TO BUF-STATUS. IF XA-STATUS (I) IS EQUAL TO OK MOVE "DONE" TO BUF-STATUS. DISPLAY STATUS-LINE UPON ALTERNATE CONSOLE. IF XA-STATUS (I) IS NOT EQUAL TO NOTE AND XA-STATUS (I) IS NOT EQUAL TO OK MOVE XA-GBLFORID (I) TO BUF-GBLFORID DISPLAY GBLFORID-LINE UPON ALTERNATE CONSOLE. * ABORT. CALL "ABORT". END-OF-TPR. MOVE SPACES TO NEXT-TPR. EXIT PROGRAM. 47 A2 14UR Rev03 H-5

178 ORACLE7/TDS User's Guide H-6 47 A2 14UR Rev03

179 I. Error in Commit Phase During TDS Execution S: MWINLIB BIN ORA.O7106D.BIN; S: SQLDBA SMLIB=ORA.O7106D.SM LMLIB=ORA.O7106D.LM; >>>10:28 SQLDBA 7106D SQL*DBA: Release Production on Mon Apr 22 10:28: Copyright (c) Oracle Corporation 1979, All rights reserved. Oracle7 Server Release Production Release With the distributed, replication and parallel query options PL/SQL Release Production SQLDBA> SET INSTANCE D:ORANG.T7DB; Oracle7 Server Release Production Release With the distributed, replication and parallel query options PL/SQL Release Production SQLDBA> CONNECT INTERNAL; Connected. SQLDBA> STARTUP OPEN DBNRG; ORACLE instance started. Database mounted. Database opened. Total System Global Area bytes Fixed Size bytes Variable Size bytes Database Buffers bytes Redo Buffers bytes SQLDBA> connect sys/change_on_install; Connected. SQLDBA> select * from dba_2pc_pending; LOCAL_TRAN_ID GLOBAL_TRAN_ID STATE MIX A TRAN_COMMENT FAIL_TIME FORCE_TIM RETRY_TIM OS _USER O S_TERMINAL 47 A2 14UR Rev03 I-1

180 ORACLE7/TDS User's Guide HOST DB_USER COMMIT# rows selected. ******Table empty in dba_2pc_pending****************************************************** SQLDBA> disconnect; Disconnected. SQLDBA> exit; SQL*DBA complete. <<<10:29 S: S: S: EJ TDSRUNXA_J LIB=.SL VL=#CAT('ORSTLIB=',%H_ORACLE_STLIB); S: MOM LISTEN; --> BREAK TO RETURN TO INT MODE -->10.29 X2718 IN ORXA USER=ORAOPER1 CLASS=C SPR=5 STATION=BC09 -->10.29 X2718 STARTED ORXA ORAOPER1 C --> 7106A <<< ORA/TDS communication ready >>> --> OP90 X COMMANDS FAMILY: H_ORXA CREATED --> TX50 TDS : ORXA STARTED; YOU ARE MASTER TERMINAL OPERATOR --> TX50 TDS : ORXA COLD RESTART IS PERFORMED --> READY TDS Ready S: S: EJECT; --> TX87 TDS : ORXA, ORAOPER3 CONNECTED FROM BC09TILS -->10.31 X XAEVT XAEVT TRANSACTION ACTIVATED -->10.31 X XAEVT ******************************************************** -->10.31 X XAEVT * XA DESYNCHRONIZATION EVENT... -->10.31 X XAEVT ******************************************************** -->10.31 X XAEVT TPR-NAME: TINSERT1 -->10.31 X XAEVT USER-NAME: ORAOPER3 -->10.31 X XAEVT TDS-XA-STATUS: COMMIT -->10.31 X XAEVT XA-GLOBAL-STATUS: RMFAIL -->10.31 X XAEVT ******************************************************** -->10.31 X XAEVT * RMs STATUS -->10.31 X XAEVT ******************************************************** -->10.31 X XAEVT * dbid: DB1 -->10.31 X XAEVT * rmid: D:ORNG.T7DB -->10.31 X XAEVT * status: DONE -->10.31 X XAEVT * >10.31 X XAEVT * dbid: DB2 -->10.31 X XAEVT * rmid: D:ORANG.T7DB -->10.31 X XAEVT * status: RMFAIL -->10.31 X XAEVT * gblforid: C2C3F0F9D6D9E7C11B74ABC >10.31 X XAEVT ******************************************************* --> TX51 TDS : ORXA, ORAOPER3 DISCONNECTED FROM BC09TILS *****Error detected in the TPR tinsert1 for the database ORANG.T7DB: ORNG.T7BD successful committed* *****Error detected in the TPR tinsert1 for the database ORANG.T7DB:RMFAIL when trying to I-2 47 A2 14UR Rev03

181 Error in Commit Phase During TDS Execution commit: *****ORNG.T7BD successful committed* S: SQLDBA >>>10:31 SQLDBA 7106D SQL*DBA: Release Production on Mon Apr 22 10:31: Copyright (c) Oracle Corporation 1979, All rights reserved. Oracle7 Server Release Production Release With the distributed, replication and parallel query options PL/SQL Release Production SQLDBA> connect scott/tiger; ORA-01034: ORACLE not available ORA-04134: Error in attaching the SGA (SMSGET) IOR rejection (shutdown,startup...),retry later *****Database was down - restart it ******************************************************* SQLDBA> connect internal; Connected. SQLDBA> startup open dbnrg ORACLE instance started. Database mounted. Database opened. Total System Global Area bytes Fixed Size bytes Variable Size bytes Database Buffers bytes Redo Buffers bytes SQLDBA> select * from dba_2pc_pending; LOCAL_TRAN_ID GLOBAL_TRAN_ID STATE MIX A TRAN_COMMENT FAIL_TIME FORCE_TIM RETRY_TIM OS _USER O S_TERMINAL HOST DB_USER COMMIT# C2C3F0F9D6D9E7C11B74ABC prepared no *****Global transaction status is "prepared". Wait for end of resynchronization phase*************** 22-APR APR-96 OR AOPER1 O RAOPER row selected. SQLDBA> disconnect; Disconnected. 47 A2 14UR Rev03 I-3

182 ORACLE7/TDS User's Guide SQLDBA> exit; SQL*DBA complete. <<<10:33 S: S: -->10.34 X XAEVT XAEVT TRANSACTION ACTIVATED -->10.34 X XAEVT ******************************************************* -->10.34 X XAEVT *... XA RESYNCHRONIZATION. (CHECK RESULT). -->10.34 X XAEVT ******************************************************* -->10.34 X XAEVT TPR-NAME: TINSERT1 -->10.34 X XAEVT USER-NAME: ORAOPER3 -->10.34 X XAEVT TDS-XA-STATUS: COMMIT -->10.34 X XAEVT XA-GLOBAL-STATUS: DONE -->10.34 X XAEVT ******************************************************* -->10.34 X XAEVT * RMs STATUS -->10.34 X XAEVT ******************************************************* -->10.34 X XAEVT * dbid: DB1 -->10.34 X XAEVT * rmid: D:ORNG.T7DB -->10.34 X XAEVT * status: DONE *****Successful end of resynchronization phase********************************************** -->10.34 X XAEVT * >10.34 X XAEVT * dbid: DB2 -->10.34 X XAEVT * rmid: D:ORANG.T7DB -->10.34 X XAEVT * status: DONE *****Successful end of resynchronization phase********************************************** -->10.34 X XAEVT ******************************************************* S: TTDS TDS=ORXA MODE=COLD; TX54 TDS : ORXA, TTDS COMMAND COMPLETED S: EJECT; S: UFI SCOTT/TIGER; >>>10:34 UFI 7106D SQL*Plus: Release Production on Mon Apr 22 10:34: Copyright (c) Oracle Corporation 1979, All rights reserved. Warning: Product user profile information not loaded! Error in disabling roles in product user profile. Connected to: Oracle7 Server Release Production Release With the distributed, replication and parallel query options PL/SQL Release Production --> TX53 TDS : ORXA SHUTDOWN --> 7106A <<< ORA/TDS communication shutdown completed >>> SQL> select * from emp where ename ='ASTERIX'; EMPNO ENAME JOB MGR HIREDATE SAL COMM DEPTNO ASTERIX TEST 30-JUN *****Update done on table **************************************************************** SQL> exit; Disconnected from Oracle7 Server Release Production Release With the distributed, replication and parallel query options PL/SQL Release Production <<<10:34 I-4 47 A2 14UR Rev03

183 Error in Commit Phase During TDS Execution S: 47 A2 14UR Rev03 I-5

184 ORACLE7/TDS User's Guide I-6 47 A2 14UR Rev03

185 Glossary A ATMI Application to Transaction Manager Interface (X/OPEN terminology). C Client/Server Model The client system (a PC, mini, or mainframe) must request the services of the server system (a mini or mainframe; never a PC). The client is the machine where the application resides. Commitment point A point in an application where the work done since the last commitment point is deemed valid. Updates are wholly and definitively applied to the data, and made visible to other users. The start of the application execution is a commitment point. Under ORACLE/TDS, only the end of a TPR can be a commitment point since all commitment requests are deferred to the end of the current TPR. The beginning and the end of a TDS transaction are also commitment points. Commitment unit A commitment unit (CU) represents the work done between two commitment points. This definition is valid both for ORACLE and for TDS. All work done between the two commitment points will be wholly applied to the data, or wholly ignored. In standard ORACLE terminology, a commitment unit is a "logical unit of work". Complex transaction A complex transaction is one where a commit is not executed before each terminal conversation. This means that the context remains busy during the entire terminal conversation. Cursor An area of memory acting as the interface between the user and the ORACLE kernel which assures the dynamic compilation of a SQL statement. It is a data structure managed by ORACLE code and associated with a DML statement. 47 A2 14UR Rev03 g-1

186 ORACLE7/TDS User's Guide D For each SELECT, INSERT, UPDATE and DELETE statement, a cursor is opened, either explicitly by the user, or implicitly by ORACLE. DCL statement A Data Control Language SQL statement. Such statements are GRANT and REVOKE. They are used to control the access rights to ORACLE databases. DCL statements autocommit so their use in TPRs must be carefully judged. DDL statement A Data Definition Language SQL statement. Such statements are CREATE TABLE, CREATE INDEX, and ALTER TABLE. They are used to create, modify, and erase database objects. DDL statements autocommit so their use in TPRs must be carefully judged. DML statement A Data Manipulation Language SQL statement. Such statements are SELECT, INSERT, UPDATE and DELETE. They are used to insert, update, and delete the contents of tables. Distributed Transaction Processing (DTP) The DTP model is defined by X/OPEN for distributed transaction processing. It envisages three software components: an application program, a resource manager component (typically a database management system), and a transaction manager. E EXEC SQL and END-EXEC Every SQL statement which is embedded in a COBOL program must be preceded by the "EXEC SQL" command prefix and followed by an "END-EXEC." command suffix. This is to enable the PCC precompiler to recognize them. END-EXEC must be followed by a period. F For example: MOVE 0 TO X. EXEC SQL INSERT INTO T1 VALUES (1) END-EXEC. MOVE "YES" TO FLAG. H HA High Availability. g-2 47 A2 14UR Rev03

187 Glossary O ORACLE The relational database management system (RDBMS) provided with GCOS 7. ORACLE is a trademark of ORACLE Corporation, California, USA, registered in the US patent office. P Parsing The parsing of an SQL statement associated with a given cursor is the compilation phase of cursor processing. A SQL statement associated with a cursor does not need to be re-parsed each time the cursor is to be executed. The parsing of an SQL statement can be done explicitly using the EXEC SQL PREPARE statement. PCC Stands for PreCompiler, Common. Name of the ORACLE command that precompiles programs containing embedded SQL statements into programs containing calls to the SQL run-time package. Such precompiled programs can be compiled using the standard GCOS 7 compiler for the applicable language. The language currently supported in the ORACLE/TDS environment is COBOL-85. Pro*COBOL The ORACLE tool which enables programmers to embed SQL statements into COBOL programs. R RM Resource Manager (X/OPEN terminology), typically a database management system. S Simple transaction A simple transaction is characterized as one where each terminal conversation is preceded by a commitment. This prevents a user from holding a resource for longer than necessary. SQL Structured Query Language, a language designed by IBM research and normalized by the ANSI and ISO organizations. It has been adopted by ANSI as a standard language for interacting with relational databases. 47 A2 14UR Rev03 g-3

188 ORACLE7/TDS User's Guide T TDS Transaction Driven Subsystem, the transactional monitor of GCOS 7. Think-time The time (in seconds) between the execution of a CONNECT statement and the time the next COMMIT statement is executed for the same database. TM Transaction Manager (X/OPEN terminology). TPR Transaction Processing Routine. A user-written application program designed to run in the TDS environment TPRs are written in a superset of COBOL called TDS COBOL. Transaction (TDS transaction) A set of one or more TPRs. A transaction is invoked by TDS terminal users when a valid name is entered, and it is executed by the TDS monitor. In TDS terminology, a transaction may contain several commitment units. In ORACLE terminology, a transaction is a synonym of commitment unit. In this document, a "transaction" always refers to the TDS concept of transaction. Two-task architecture The technique whereby two separate tasks - or processes - communicate with one another by the interprocess communication facilities provided by GCOS 7 to accomplish a single job. The application runs as a separate task from the server task. For example, the ORACLE kernel acts as the server processor while an ORACLE application acts as the front-end or driving process. X XA The interface between a transaction manager and a resource manager according to the DTP model definition. It specifies an interface for a 2-phase commitment protocol. XCP2 extended Cooperation Protocol level-2. An application level protocol for cooperation between distributed transactional applications. Compatible with LU6.2 and manages Syncpoint-Protocol. X/OPEN Organization for the normalization of open systems. g-4 47 A2 14UR Rev03

189 Index A Access rights 5-8 Administration 1-4 Application to Transaction Manager Interface g-1 Architecture 1-2 AT clause 2-5 ATMI g-1 Authority code 5-8 Automatic logons 2-9 Automatic restart 2-10 B Backend Server G-2 Benefits 1-1 C C language 8-1 Cache Manager 7-5 Cache processing 5-9 CALL DFCMIT 2-12 CALL INVCMIT 2-23 CALL NOCMIT 2-24 CALL ROLL-BACK 2-22 CARDID parameter 2-28 CDP G-2 Closing files 6-7 Cluster 5-11 COBOL COBOL compiler 2-28 COMMIT statement 1-3, 2-13, 2-20 COMMIT WORK RELEASE 2-14 Commitment heuristic decisions 7-3 Commitment point g-1 Commitment unit 2-10, 2-25, 5-6, 6-2, 6-3, g-1 Common-storage 6-5 COMMUNICATION SECTION sample B-2 Communications server 3-1 Compilation 2-28 Complex transaction 5-3, g-1 CONNECT statement 1-3, 2-1, 5-9 connection profile, shared 8-1 CONSTANT-STORAGE sample B-1 Context 5-8 Context cache 5-1 Conversation 5-6 CoPro step G-1 Co-processor G-1 COPY file samples B-1 COR 3-1 CPU time 5-11 CSIZE parameter 5-1, 6-2 Cursor 5-6, g-1 Customer Dedicated Processor G-2 D Data consistency 6-2, 6-5 Data definition statements 8-2 Database 1-4 Database design 5-11 Database server 3-2, 3-3, 5-11 DCL statement g-2 DDL statement g-2 DDL statements A2 14UR Rev03 i-1

190 ORACLE7/TDS User's Guide D Deadlock 6-3, 6-5 Default connection 2-5 Default database 2-5 Distributed Transaction Processing g-2 DML statement g-2 DTP g-2 E END-EXEC g-2 EPU G-1 Error message 3-3, 3-5, A-1 EXEC SQL g-2 Extension Processor Unit G-1 Extra connections 3-3 F FETCH transaction E-1 FOR DEBUG 2-24 G GETSTM 2-27 H H_ORATDS sharable module 3-3 HA 1-9 Heuristic decisions commitment 7-3 rollback 7-3 High Availability 1-9 High Relational Performance G-2 HRP G-2 I IDS/II 6-2, 6-3 Implicit commitment 2-11 Index 5-11 INSTANCE 2-5 Instruction Processor Unit G-2 IPU G-2 IQS 6-7 J Job Occurrence Report 4-14 JOR 4-14 L LEVEL parameter 2-28 LINK_PG statement 2-29 Linking 2-29 Logical connection 2-2 Logical disconnection 2-2, 2-14 M Maintenance 1-4 MAXOPENCURSORS parameter 4-17, 4-20, 5-11 MODIFY_TDS 3-4 Multiple databases 5-12 N National language support 6-6 O OPEN_CURSORS 5-10 Opening files 6-7 Optimization 5-1, 5-10 ORACA 2-27 ORACA structure 4-19, 6-6, 8-2 ORACATDS structure 4-19 ORACATDS_CBL 4-19 ORACLE g-3 ORACLE_LNK subfile 2-29 ORACLE7/TDS Cache Manager 7-5 ORACOC 4-20 ORAHOC 4-20 ORAMOC 4-20 i-2 47 A2 14UR Rev03

191 Index O ORANEX 4-20 ORANOR 4-20 ORANPR 4-20 ORASTAT entry point 4-19 OWD 2-5 P Parallel Specialized Processors G-2 Parsing g-3 PCC 2-28, 5-11, g-3 Physical connection 2-2 Precompilation 2-28, 5-11 PreCompiler, Common g-3 Prerequisites 1-1 Pro*C TPR compiling 8-3 linking 8-3 precompiling 8-3 Pro*COBOL 1-3, 2-1, g-3 Process 5-8, 6-2 Programming 2-1 PSP G-2 R Resource Manager g-3 Restrictions 1-3 Roll forward 6-7 Rollback heuristic decisions 7-3 ROLLBACK statement 1-3, 2-21 ROWID 5-8, E-1 S SAMPLE transaction D-1 SETMXC entry point 4-17 Simple transaction 5-3, g-3 SOR 3-2 Spawn function 6-6 SQL g-3 SQL statements in TPRs 8-1 SQL*Net 1-4 SQL*Net context 2-3 SQLCODE 2-10, 6-2, 6-5, A-1 Standard step G-1 Statistics 4-14 T Tablespace 5-11 TDS g-4 TDS Explicit commitment 2-12 TDS transaction g-4 TDS_SQL file 3-1 TDS-HA 7-8 TDS-STORAGE sample B-2 TDS-XA 1-4 resynchronization 7-3 TDS-XCP2 7-8 Terminal 6-1 Think-time g-4 Time-out 6-3 TP7LINKTPR subfile 2-29 TPR 2-1 commitment 8-2 rollback 8-2 Transaction g-4 Transaction Driven Subsystem g-4 Transaction Processing Routine g-4 TRANSACTION-STORAGE 5-8, 6-6 Two-task architecture g-4 U UFAS 6-2, 6-3 USE XA clause 1-8 User-id 5-8 W WHENEVER statement A2 14UR Rev03 i-3

192 ORACLE7/TDS User's Guide X X/OPEN g-4 XA g-4 XCP2 g-4 i-4 47 A2 14UR Rev03

193 May 1999

194 _ [ ] _ [ ] _ [ ] _ [ ] _ [ ] _ [ ] _ [ ] _ [ ] _ [ ] _ [ ] _ [ ] _ [ ] [ ]

195

196