ORACLE 7 / TDS User's Guide - Bullsupport.bull.com/ols/product/system/gcos7/gcos7-com/g7... · 2006. 4. 11. · with the ORACLE and TDS products. Administrators who are responsible

ORACLE 7 / TDS

User's Guide

DPS

7000/XTA

NO

VASC

ALE

7000

Database Products: ORACLE

REFERENCE47 A2 14UR 03

DPS7000/XTANOVASCALE 7000

ORACLE 7 / TDSUser's Guide

Database Products: ORACLE

May 1999

BULL CEDOC

357 AVENUE PATTON

B.P.20845

49008 ANGERS CEDEX 01

FRANCE

REFERENCE47 A2 14UR 03

The following copyright notice protects this book under Copyright laws which prohibit such actions as, but notlimited to, copying, distributing, modifying, and making derivative works.

Copyright Bull SAS 1992, 1999

Printed in France

Suggestions and criticisms concerning the form, content, and presentation of thisbook are invited. A form is provided at the end of this book for this purpose.

To order additional copies of this book or other Bull Technical Publications, youare invited to use the Ordering Form also provided at the end of this book.

Trademarks and Acknowledgements

We acknowledge the right of proprietors of trademarks mentioned in this book.

Intel® and Itanium® are registered trademarks of Intel Corporation.

Windows® and Microsoft® software are registered trademarks of Microsoft Corporation.

UNIX® is a registered trademark in the United States of America and other countries licensed exclusively throughthe Open Group.

Linux® is a registered trademark of Linus Torvalds.

The information in this document is subject to change without notice. Bull will not be liable for errors containedherein, or for incidental or consequential damages in connection with the use of this material.

47 A2 14UR Rev03 iii

Preface

This manual introduces the reader to the ORACLE/TDS facilities and demonstrateshow to access ORACLE databases from TDS applications.

The preparation and execution of ORACLE/TDS applications (along with theTDS-specific features of Pro*COBOL and Pro*C) are described in full. Generalknowledge of Pro*COBOL and Pro*C is assumed.

This document is aimed at programmers or systems developers who need to writeTransaction Processing Routines (TPRs) containing embedded SQL statements thataccess ORACLE databases.

For users of COBOL and C, prior knowledge of Pro*COBOL and Pro*C in bothbatch and IOF environments is assumed. The appropriate documentary referencesare the Programmer's Guide to the Precompilers, the Pro*COBOL Supplement andthe Pro*C Supplement . In addition, programmers should be generally familiarwith the ORACLE and TDS products.

Administrators who are responsible for ORACLE/TDS application systems shouldrefer to the optimization and tuning hints given in Sections 4 and 5.

Section 1 Offers a brief introduction to ORACLE/TDS.

Section 2 Describes how to code, precompile, compile, and linkPro*COBOL TPRs. There is special emphasis on theCONNECT, COMMIT, and ROLLBACK statements.

Section 3 Provides the information you need to run anORACLE/TDS application.

Section 4 Shows how to call entry points in the H_ORATDSsharable module.

Section 5 Demonstrates various techniques for optimizing theperformance of an ORACLE/TDS application.

Scope andObjectives

IntendedReaders

Structure ofthis document

ORACLE7/TDS User's Guide

iv 47 A2 14UR Rev03

Section 6 Deals with certain rules and restrictions to be takeninto account when using ORACLE/TDS.

Section 7 Deals with aspects specific to TDS-XA.

Section 8 Deals with aspects specific to the support of Pro*Cunder ORACLE7/TDS.

Appendix A Lists and describes the ORACLE/TDS SQLCODEerror conditions.

Appendix B Lists sample COPY files.

Appendix C Lists the TDSCLEAN transaction.

Appendix D Lists the SAMPLE transaction.

Appendix E Lists the FETCH transaction.

Appendix F Lists the ORATDS transaction.

Appendix G Gives references and terms for the specializedprocessors.

Appendix H Lists the H_XAEVT transaction.

Appendix I Lists the error in commit phase during TDS execution.

Glossary Defines terms that have a particular meaning in anORACLE/TDS context.

TDS Administrator's Guide...................................................................47 A2 32UTTDS COBOL Programmer's Guide .......................................................47 A2 33UTTDS C Programmer's Guide .................................................................47 A2 07UT

The complete GCOS 7/ORACLE7 manual set is given in the latest revision of thefollowing manual:

ORACLE7 Documentation Catalog ......................................................47 A2 10UR

In particular, readers must be able to refer to the ORACLE manuals that dealspecifically with Pro*COBOL and Pro*C. They are:

Programmer's Guide to the ORACLE Precompilers ..............................86 A2 77CRPL/SQL 2.1 and Precompilers 1.6 Addendum .......................................86 A2 74CRPro*COBOL Supplement......................................................................86 A2 79CRPro*C Supplement................................................................................86 A2 78CRORACLE7 Server SQL Language Reference Manual ....................................778-70

Relateddocuments

ORACLE7Documentation

Preface

47 A2 14UR Rev03 v

Readers working at sites where ORACLE is running in a High Availabilityenvironment must be able to refer to:

ORACLE7/TDS-HA User's Guide .........................................................47 A2 16UR

The following syntax notation is used in this document:

A variable in angle brackets indicates a value (orstring) to be input by the user.

[syntax] Optional syntax.

SyntaxNotation


vi 47 A2 14UR Rev03

q

47 A2 14UR Rev03 vii

Table of Contents

1. Introducing ORACLE/TDS

1.1 Overview.................................................................................................................... 1-1

1.1.1 Prerequisites ................................................................................................. 1-1

1.1.2 Benefits ......................................................................................................... 1-11.1.3 Architecture ................................................................................................... 1-21.1.4 Restrictions.................................................................................................... 1-3

1.1.5 SQL*NET ...................................................................................................... 1-41.1.6 Sharing between TDS, IOF, BATCH .............................................................. 1-4

1.1.7 ORACLE/TDS with XA................................................................................... 1-41.1.8 ORACLE/TDS with PRO*C............................................................................ 1-41.1.9 Administration and Maintenance .................................................................... 1-4

1.1.10 Error Codes ................................................................................................... 1-5

1.2 Building An Oracle/Tds Subsystem (TDS SIDE) ......................................................... 1-5

1.2.1 The TDS Generation Program ....................................................................... 1-51.2.1.1 The "USE ORACLE" Clause .......................................................... 1-61.2.1.2 ORACLE-DEF ... ORACLE-ENDDEF Block.................................... 1-61.2.1.3 The USE XA Clause....................................................................... 1-81.2.1.4 Example of a STDS File................................................................. 1-8

1.2.2 Preparing TPRs ............................................................................................. 1-9

1.3 Building AN ORACLE/TDS SUBSYSTEM (ORACLE SIDE) .......................................1-10

1.4 Migration From ORACLE V6......................................................................................1-11

1.4.1 ORACLE V6/TDS Applications......................................................................1-111.4.2 ORACLE Transactions..................................................................................1-11

2. Writing Pro*COBOL TPRs For TDS

2.1 Connecting To Oracle................................................................................................. 2-1

2.1.1 The SQL*Net Context Cache ......................................................................... 2-22.1.1.1 Physical Connection Definition ....................................................... 2-22.1.1.2 Logical Connection Definition ......................................................... 2-22.1.1.3 SQL*Net Context Definition............................................................ 2-3


viii 47 A2 14UR Rev03

2.1.1.4 Why a SQL*Net Context Cache?.................................................... 2-32.1.1.5 How Does the SQL*Net Context Cache Work? .............................. 2-3

2.1.2 Common Syntax of a CONNECT Statement .................................................. 2-42.1.3 Default Databases and Connections .............................................................. 2-5

2.1.3.1 The default Database..................................................................... 2-52.1.3.2 The default connection................................................................... 2-52.1.3.3 Database Identifiers (SQL*Net) ...................................................... 2-52.1.3.4 The SQL*Net Syntax for Connecting .............................................. 2-7

2.1.4 Automatic Logons.......................................................................................... 2-9

2.1.5 Automatic Restart .........................................................................................2-102.1.6 EXEC SQL CONNECT Errors.......................................................................2-10

2.2 Commitments ............................................................................................................2-10

2.2.1 Using Implicit Commitment ...........................................................................2-11

2.2.2 Using CALL "DFCMIT"..................................................................................2-122.2.3 Using the COMMIT Statement ......................................................................2-13

2.2.4 Automatic Disconnection from ORACLE After COMMIT................................2-142.2.5 Each TDS Commitment Commits Only One ORACLE Database...................2-16

2.2.6 Commit Separate Databases in Separate TPRs............................................2-182.2.7 EXEC SQL COMMIT Errors..........................................................................2-20

2.3 Rollback ....................................................................................................................2-20

2.3.1 The ROLLBACK Statement ..........................................................................2-21

2.3.2 The TDS "ROLL-BACK" Primitive .................................................................2-222.3.3 The TDS "INVCMIT" Primitive.......................................................................2-23

2.3.4 The TDS "NOCMIT" Primitive .......................................................................2-242.3.5 FOR DEBUG Clause ....................................................................................2-24

2.4 Data Definition Statements ........................................................................................2-24

2.5 Handling Runtime Errors ...........................................................................................2-26

2.5.1 Using the WHENEVER Statement ................................................................2-27

2.5.2 Using the ORACLE Communications Area (ORACA)....................................2-27

2.6 Precompiling, Compiling And Linking.........................................................................2-28

2.6.1 Precompiling a Pro*COBOL TPR..................................................................2-282.6.2 Compiling a Pro*COBOL TPR.......................................................................2-28

2.6.3 Linking a Pro*COBOL TPR...........................................................................2-292.6.4 Example of JCL stream generating a Pro*COBOL TPR.................................2-29

3. Running an ORACLE/TDS Application

3.1 The Tds_Sql File ........................................................................................................ 3-1

3.2 The Oracle Communications Server (Cor) .................................................................. 3-1

3.2.1 Starting COR................................................................................................. 3-2

3.2.2 Stopping COR ............................................................................................... 3-2

47 A2 14UR Rev03 ix

3.3 The Oracle Database Server ...................................................................................... 3-2

3.3.1 Starting ORACLE .......................................................................................... 3-23.3.2 Adding Extra Connections.............................................................................. 3-3

3.3.3 Stopping ORACLE......................................................................................... 3-3

3.4 The H_Oratds Sharable Module ................................................................................. 3-3

3.5 Tds Error Messages Relating To Oracle ..................................................................... 3-5

4. Tuning ORACLE/TDS: Configuration Parameters

4.1 Setting Configuration Parameters At Generation Time................................................ 4-1

4.2 Setting Configuration Parameters Dynamically ........................................................... 4-4

4.2.1 Transaction Description ................................................................................. 4-44.2.2 How to Use ORATDS .................................................................................... 4-4

4.2.3 Description of the "ORACLE" Transaction Parameters ................................... 4-64.2.3.1 MAXTIM Parameter ....................................................................... 4-64.2.3.2 MAXWAT Parameter ..................................................................... 4-74.2.3.3 TIMOUT Parameter ....................................................................... 4-84.2.3.4 CSIZE Parameter .......................................................................... 4-84.2.3.5 TRACELVL Parameter................................................................... 4-94.2.3.6 Tracefile Parameter ....................................................................... 4-9

4.2.4 Description of KEYWORDs...........................................................................4-104.2.4.1 "ORACLE DISPLAY".....................................................................4-104.2.4.2 "ORACLE ENABLE" .....................................................................4-104.2.4.3 "ORACLE DISABLE".....................................................................4-114.2.4.4 "ORACLE TERM" .........................................................................4-114.2.4.5 "ORACLE WAIT" ..........................................................................4-124.2.4.6 "ORACLE TRACEON" ..................................................................4-134.2.4.7 "ORACLE TRACEOFF" ................................................................4-134.2.4.8 "ORACLE TRACE" .......................................................................4-13

4.3 Oracle/Tds Statistics..................................................................................................4-14

4.3.1 Job Occurrence Report Statistics ..................................................................4-14

4.3.2 The CASTAT Transaction.............................................................................4-16

4.4 Setting MAXOPENCURSORS VIA THE "SETMXC" ENTRY POINT ..........................4-17

4.4.1 MAXOPENCURSORS With SETMXC...........................................................4-184.4.2 MAXOPENCURSORS Without SETMXC......................................................4-18

4.4.3 Using SETMXC ............................................................................................4-18

4.5 Getting Cursor Statistics Via The "Orastat" Entry Point ..............................................4-19

4.5.1 The ORACATDS Structure Layout ................................................................4-19

4.5.2 Using ORASTAT ..........................................................................................4-20

5. Optimizing ORACLE/TDS Applications

5.1 Sizing The Oracle Context Cache............................................................................... 5-1


x 47 A2 14UR Rev03

5.1.1 Sizing Simple Transactions............................................................................ 5-3

5.1.2 Sizing Complex Transactions......................................................................... 5-35.1.3 Sizing Combined Simple and Complex Transactions...................................... 5-5

5.2 Terminal Conversation ............................................................................................... 5-6

5.2.1 Committing Before Each Terminal Conversation ............................................ 5-65.2.2 Handling Cursors ........................................................................................... 5-6

5.3 Controlling The Number Of User-Ids ........................................................................... 5-8

5.4 Optimizing Connect Statements.................................................................................. 5-8

5.4.1 Local Connection........................................................................................... 5-8

5.4.2 Cache Processing.......................................................................................... 5-9

5.5 GENERAL Oracle Optimization TECHNIQUES..........................................................5-10

5.5.1 Saving CPU Time - Use of Cursors ...............................................................5-105.5.2 Database Server...........................................................................................5-11

5.5.3 Database Design ..........................................................................................5-115.5.4 Using Several Distinct ORACLE Databases ..................................................5-12

6. ORACLE/TDS Rules and Restrictions

6.1 The Number Of Connected Terminals......................................................................... 6-1

6.2 ORACLE Processes ................................................................................................... 6-2

6.3 Updating Ufas OR IDS/II Databases With Oracle Databases....................................... 6-2

6.3.1 Separate Commitment Units .......................................................................... 6-2

6.3.2 Data Consistency........................................................................................... 6-2

6.4 Deadlocks .................................................................................................................. 6-3

6.4.1 Avoiding Deadlocks - Example....................................................................... 6-3

6.4.2 Creating Deadlocks - Example....................................................................... 6-4

6.5 Controlled Common-Storage ...................................................................................... 6-5

6.5.1 Updating Data in Controlled Common-Storage............................................... 6-56.5.2 Reading Data in Controlled Common-Storage................................................ 6-5

6.5.3 Non-Controlled Common-Storage.................................................................. 6-6

6.6 The ORACA Structure ................................................................................................ 6-6

6.7 National Language Support ........................................................................................ 6-6

6.8 The Spawn Function................................................................................................... 6-6

6.9 Opening And Closing GCOS 7 FILES......................................................................... 6-7

6.10 Iqs.............................................................................................................................. 6-7

6.11 Roll Forward............................................................................................................... 6-7

7. ORACLE7/TDS-XA

47 A2 14UR Rev03 xi

7.1 Overview.................................................................................................................... 7-1

7.1.1 Environment .................................................................................................. 7-2

7.2 Operation ................................................................................................................... 7-3

7.2.1 Heuristic Decisions ........................................................................................ 7-3

7.2.2 TDS Resynchronization with XA .................................................................... 7-37.2.3 TDS Restart................................................................................................... 7-3

7.3 User Interface............................................................................................................. 7-3

7.3.1 TDS Generation and Application Monitoring................................................... 7-47.3.1.1 TDS Generation............................................................................. 7-47.3.1.2 Application Monitoring.................................................................... 7-5

7.3.2 Server Configuration...................................................................................... 7-57.3.3 TPR Programming......................................................................................... 7-5

7.3.3.1 CONNECT Statement and ORACLE7/TDS Cache Manager .......... 7-57.3.3.2 Using Precompilers with ORACLE XA............................................ 7-67.3.3.3 SQL-Based Restrictions................................................................. 7-67.3.3.4 Checking the Synchronization State............................................... 7-77.3.3.5 The H_XAEVT Special Transaction................................................ 7-7

7.4 HA And XCP2 Compatibility........................................................................................ 7-8

8. Writing Pro*C TPRs for TDS

8.1 Introduction ................................................................................................................ 8-1

8.2 Programming Rules.................................................................................................... 8-1

8.2.1 Connecting to ORACLE................................................................................. 8-18.2.2 Commitments ................................................................................................ 8-2

8.2.3 Rollback ........................................................................................................ 8-28.2.4 Data Definition Statements ............................................................................ 8-28.2.5 Handling Runtime Errors................................................................................ 8-2

8.3 Precompiling, Compiling, And Linking......................................................................... 8-3

8.3.1 Precompiling.................................................................................................. 8-38.3.2 Compiling ...................................................................................................... 8-3

8.3.3 Linking........................................................................................................... 8-3

8.4 Other C Language Variations...................................................................................... 8-3

8.4.1 Setting Configuration Parameters Dynamically............................................... 8-38.4.2 Obtaining Cursor Statistics via the orastat Entry Point................................... 8-4

A. SQLCODE Error Conditions

A.1 Sqlcode = -1............................................................................................................... A-1

A.2 Sqlcode = -2............................................................................................................... A-2

A.3 Sqlcode = -3............................................................................................................... A-2


xii 47 A2 14UR Rev03

A.4 Sqlcode = -4............................................................................................................... A-2

A.5 Sqlcode = -5............................................................................................................... A-3

A.6 Sqlcode = -6............................................................................................................... A-3

A.7 Sqlcode = -7............................................................................................................... A-4

A.8 Sqlcode = -8............................................................................................................... A-5

A.9 Sqlcode = -9............................................................................................................... A-5

A.10 Sqlcode = -10............................................................................................................. A-5

A.11 Sqlcode = -11............................................................................................................. A-6

A.12 Sqlcode = -12............................................................................................................. A-6

A.13 Sqlcode = -13............................................................................................................. A-7

A.14 Sqlcode = -14............................................................................................................. A-7

A.15 Sqlcode = -15............................................................................................................. A-8

A.16 Sqlcode = -16............................................................................................................. A-8

A.17 Sqlcode = -17............................................................................................................. A-8

A.18 Sqlcode = -18............................................................................................................. A-9

A.19 Sqlcode = -19............................................................................................................. A-9

A.20 Sqlcode = -20............................................................................................................. A-9

A.21 Sqlcode = -21........................................................................................................... A-10

A.22 Sqlcode = -22........................................................................................................... A-10

A.23 Sqlcode = - 23.......................................................................................................... A-11

A.24 Sqlcode = - 24.......................................................................................................... A-11

A.25 Sqlcode = - 25.......................................................................................................... A-11

A.26 Sqlcode = - 26.......................................................................................................... A-12

A.27 Sqlcode = - 27.......................................................................................................... A-12

A.28 Sqlcode = - 28.......................................................................................................... A-13

A.29 Sqlcode = - 29.......................................................................................................... A-13

A.30 Sqlcode = - 30.......................................................................................................... A-13

A.31 Sqlcode = - 31.......................................................................................................... A-14

A.32 Sqlcode = - 34.......................................................................................................... A-14

B. Sample COPY Files

C. The TDSTCLEAN Transaction

C.1 Purpose......................................................................................................................C-1

47 A2 14UR Rev03 xiii

C.2 Transaction Description..............................................................................................C-1

C.3 How To Use ...............................................................................................................C-2

C.3.1 Description of the "TCLEAN" IDENTs ............................................................C-3C.3.1.1 The SPWNT Parameter .................................................................C-3C.3.1.2 The IDLET Parameter ....................................................................C-5

C.3.2 Description of "TCLEAN" transaction KEYWORDs.........................................C-6C.3.2.1 "TCLEAN DISPLAY" ......................................................................C-6C.3.2.2 "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


xiv 47 A2 14UR Rev03

Table of Graphics

Figures

1-1. Two TDS Applications Sharing the Same ORACLE Database..................................... 1-21-2. A TDS Application Accessing Two ORACLE Databases ............................................. 1-31-3. Two TDS applications Sharing Two ORACLE Databases............................................ 1-31-4. ORACLE/TDS Development Stages (TDS Side)........................................................1-107-1. TDS-XA/ORACLE in the DTP Model........................................................................... 7-2

47 A2 14UR Rev03 1-1

1. Introducing ORACLE/TDS

1.1 Overview

1.1.1 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.

1.1.2 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 anORACLE 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 flexibilityof relational ORACLE data structures.

• The same TDS application can simultaneously access ORACLE data, IDS/IIdatabases, and UFAS files. A TPR can update either an ORACLE database orIDS/II and UFAS data.


1-2 47 A2 14UR Rev03

• ORACLE production systems and ORACLE decision support systems cancoexist 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 thanunder IOF.

• Context caching lets multiple users of a TDS application share a singleORACLE process in the ORACLE database server. Logical connections areretained; physical reconnections are unnecessary.

1.1.3 Architecture

ORACLE/TDS is based on the client/server model, and the two-task architecture ofORACLE.

The ORACLE server runs independently of the TDS application. Oneconsequence of this architecture is that several TDS applications can access thesame ORACLE database simultaneously. In addition, the SQL*Net facility isavailable to TDS programmers, enabling a TPR to access several ORACLEdatabases simultaneously.

Figures 1-1, 1-2, and 1-3 show several possible implementations:

@GRP@@NE@Two TDS Applications Sharing the Same ORACLEDatabase@Fig. 0-1@

TDS applicationnumber 1

ORACLE databaseserver A


Figure 1-1. Two TDS Applications Sharing the Same ORACLE Database

@GRP@@NE@A TDS Application Accessing Two ORACLE Databases@Fig. 1-2@

Introducing ORACLE/TDS

47 A2 14UR Rev03 1-3



ORACLE databaseserver B

Figure 1-2. A TDS Application Accessing Two ORACLE Databases

@GRP@@NE@Two TDS applications Sharing Two ORACLE Databases@Fig. 2-3@



ORACLE databaseserver B


Figure 1-3. Two TDS applications Sharing Two ORACLE Databases

1.1.4 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*Cprecompiler to generate TPRs containing SQL verbs.

All the standard Pro*COBOL and Pro*C functions are available. In the TDSenvironment, however, the CONNECT, COMMIT and ROLLBACK statements donot behave as they do in the IOF environment. All statements that are"autocommitted", such as DDL and DCL statements, must also be used carefully ina TDS environment. See Section 2.


1-4 47 A2 14UR Rev03

Otherwise, Pro*COBOL and Pro*C programs written for the TDS environment arefully compatible with the IOF environment. Each code sequence containing SQLstatements (but no terminal I/Os) which executes correctly in the TDS environmentwill execute the same way in the IOF environment. This means that you can testsequences of SQL code in interactive IOF with a test ORACLE database beforeembedding it in a TPR.

1.1.5 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 thesecond case, ORACLE databases are accessed using SQL*Net.

Two SQL*Net versions are available. The first one (SQL*Net V1) is described inthe SQL*Net V1 with ORACLE7 User's Guide manual. The second one (SQL*NetV2) is described in the SQL*Net V2 with GCOS 7 User's Guide manual.

1.1.6 Sharing between TDS, IOF, BATCH

ORACLE databases may be shared by several TDS applications, and maysimultaneously be shared with IOF or batch jobs.

1.1.7 ORACLE/TDS with XA

Differences applicable to the use of ORACLE/TDS with the X/OPEN DTP modelare discussed in Chapter 7.

1.1.8 ORACLE/TDS with PRO*C

The main part of this manual is written using Pro*COBOL examples. Developerswho wish to use Pro*C should refer to Section 8 which discusses the differencesapplicable to this environment.

1.1.9 Administration and Maintenance

ORACLE databases are maintained with the standard ORACLE tools and areseparate from the TDS application. They have their own redo log files androllback segments.


47 A2 14UR Rev03 1-5

The administrator has various means available for tuning an ORACLE/TDSsystem. Later sections of this manual refer to tuning and optimization techniques.

Standard ORACLE administrative tasks are fully described in the ORACLE7Server Administrator's Guide and ORACLE7 Server Addendum.

1.1.10 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 accompanyingmessage 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)

1.2.1 The TDS Generation Program

Using ORACLE in your TDS application implies that you inform TDS atGeneration 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 descriptionof this clause further on.

However, if your system has GCOS 7 Technical Status TS6152 or later, you mayuse the new way of configuring ORACLE/TDS. In this new way, you can define ablock in the STDS file (reserved to ORACLE) to set the ORACLE/TDSconfiguration parameters at generation time. One of these parameters isDEFAULT_DATABASE that overrides the USE clause.


1-6 47 A2 14UR Rev03

1.2.1.1 The "USE ORACLE" Clause

The "USE ORACLE" clause is added as the last entry of the TDS section. Thisstatement 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 specificclause has been added in the ORACLE block of theSTDS (DEFAULT_DATABASE is ). TheORACLE block is available only if your GCOS 7-V6Technical Status is at least TS6152.

USE ORACLE-BASE-. The name of the default database is the onespecified by , unless you specified anotherDEFAULT_DATABASE in the ORACLE block (onlyavailable with GCOS 7-V6 TS6152 or later).

NOTE: you must not use a non-alphanumericcharacter (such as '.') in the parameter.

1.2.1.2 ORACLE-DEF ... ORACLE-ENDDEF Block

The features described here may be used only with GCOS 7-V6 TS6152 or later. Ifyou 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 inXron:2:2 output of this step: "*** UNEXPECTED STATEMENT. LOOK FORTHE NEXT MANDATORY ONE."....

The general format of the ORACLE block inside the STDS file is:

@LST@@NE@@@ ORACLE-DEF IS 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 () are the following:

@LST@@NE@@@ MAXTIM MAXWAT TIMOUT


47 A2 14UR Rev03 1-7

CSIZE TRACELVL DEFAULT_DATABASE

Section 4 gives all the details on rules of syntax, signification and validity rangesof these parameters (except for DEFAULT_DATABASE).

In fact, a specific care is to be taken while using DEFAULT_DATABASEparameter: it sets the default database name for the TDS session, and it cannot bemodified through the ORACLE transaction (all the other parameters may be somodified).

"DEFAULT_DATABASE IS " 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 use:

@LST@@NE@@@GCOS 7-V6 USE Clause ORACLE Block Result******************************************************************TS < 6152 USE ORACLE not allowed TDS name------------------------------------------------------------------TS < 6152 USE ORACLE-BASE- not allowed ------------------------------------------------------------------TS >= 6152 USE ORACLE not used TDS name------------------------------------------------------------------TS >= 6152 USE ORACLE DEFAULT_DATABASE IS ------------------------------------------------------------------GCOS7 V6 USE ORACLE-BASE- not usedTS >= 6152 ------------------------------------------------------------------TS >= 6152 USE ORACLE-BASE- DEFAULT_DATABASE IS ******************************************************************

In the table, the "Result" column shows the name which is actually effective. Inthe "ORACLE Block" column, "not used" refers to the cases where the block isavailable but you choose not to use it.

As it is much easier to use the "ORACLE-DEF ... ORACLE-ENDEF" block, youare strongly recommended to use "DEFAULT_DATABASE IS " instead of"USE ORACLE-BASE-". For example, this allows you to use '.' in the


1-8 47 A2 14UR Rev03

database name which can be very important on GCOS 7 as it makescomprehension easier.

1.2.1.3 The USE XA Clause

A TDS-XA is an application where some transactions call on services provided byXA Resource Managers while others do not. When a transaction wishes to use XAservices, the USE XA clause must be specified in the "TRANSACTIONSECTION" of the STDS file.

1.2.1.4 Example of a STDS File

Below is a sample skeleton of the STDS file for a simple ORACLE/TDSapplication:

@LST@@NE@@@TDS SECTIONPROGRAM-ID. ORAT.SIMULTANEITY IS 3.RESERVE 10 AREAS.DEFAULT TRANSACTION-STORAGE SIZE IS 4096.PRIVATE STORAGE IS 2048.MESSAGE-LENGTH IS 9999 MAXIMUM.TPR-TIME-LIMIT IS 5000 MSEC.{ USE ORACLE. }{ } Optional{ USE-ORACLE-BASE-. }INPUT-OUTPUT SECTION.*END{ ORACLE-DEF } If TS >= TS6152,{ MAXTIM IS 20000. } this block is optional.{ MAXWAT IS 79000. }{ DEFAULT_DATABASE IS ORNG. } If TS < TS6152,{ ORACLE-ENDDEF } this block is not permitted.TRANSACTION SECTION.MESSAGE "SAMPLE" ASSIGN TO SAMPLEAUTHORITY-CODES ARE 0,1.*ENDMESSAGE "ORACLE" ASSIGN TO ORATDSAUTHORITY-CODES ARE 0,1.*END


47 A2 14UR Rev03 1-9

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 thismanual. See the ORACLE7/TDS-HA User's Guide for HA specifics. If theORACLE/TDS application is to operate in the HA environment, appendthe "WATCHED BY CMSC." clause to the PROGRAM-ID clause.

1.2.2 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 SQLstatements.

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 Ccompiler.

5. Link the TPRs into a TPR sharable module.

6. Load the TPR sharable module (and the H_ORATDS sharable module if notalready done) into backing store, using SYSMAINT.

The stages involved on the ORACLE side (SOR, COR, SQL*DBA, H_ORACLEand so on) are summarized at the end of this section and are explained further inSections 3 and 4 and in the ORACLE7 Installation Guide. If you plan to useSQL*Net V2 you must refer to chapter 3 of the SQL*Net V2 with GCOS 7 User'sGuide.

Figure 1-4 illustrates the TDS side stages in the development of an ORACLE/TDSapplication.

@GRP@@NE@ORACLE/TDS Development Stages (TDS Side)@Fig. 3-4@


1-10 47 A2 14UR Rev03

TPRs withembedded SQL

PCCprecompiler LINKER

TPRSharableModule

BackingStore

TDSGenerationProgram

TDSExecution

H_ORATDSSM

H_ORACLESM

C orCOBOLcompiler

SYSMAINT

TPRSM

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 theORACLE7 Installation Guide.

2. Load the ORACLE sharable modules into backing store: H_ORACLE andH_ORATDS. Follow the standard instructions given in the ORACLE7Installation Guide.

3. Ensure the ORACLE/TDS specific table called SYS$TDS is available to eachORACLE server. See Section 3.

4. Activate the ORACLE communications server (COR processor) on each siteto be accessed. See Section 3.

5. If SQL*Net V2 connections must be available to ORACLE7/TDS, make sureyou have access to SQL*Net V2 configuration files and it is advisable toactivate one (or more) SQL*Net V2 Adapter (SQLNET_ADAPTER). SeeSection 3.


47 A2 14UR Rev03 1-11

6. Activate the ORACLE database server, using SOR, for each ORACLEdatabase. See Section 3.

7. Start database activity, using SQL*DBA. See Section 3.

The administrator needs to pay attention to the tuning and optimizationmechanisms of ORACLE/TDS. See Sections 4 and 5.

HA-specific action may be necessary - refer to the ORACLE7/TDS-HA User'sGuide for information.

1.4 Migration From ORACLE V6

1.4.1 ORACLE V6/TDS Applications

The H_ORATDS sharable module delivered with ORACLE7/TDS is capable ofrunning Pro*COBOL programs precompiled with version 1.3 ORACLEprecompilers. Version 1.3 is the version of ORACLE precompilers delivered withORACLE V6 on DPS 7000. This means that you do not have to re-precompile, re-compile, and re-link ORACLE V6/TDS applications to run them withORACLE7/TDS. However, if you run ORACLE V6/TDS applications in this way,these TDS applications will not benefit from the improvements and new featuresintroduced with version 1.5 of ORACLE precompilers. Version 1.5 is the versionof ORACLE precompilers delivered with ORACLE7 on DPS 7000.

You cannot mix Pro*COBOL programs precompiled with version 1.3(precompilers) and programs precompiled with version 1.5 (precompilers) in thesame TDS application. If the ORACLE/TDS layer detects such a mixedapplication, the following message is returned to the TDS application:

"ORAT-13: Mixing formerly and newly precompilations is forbidden."

1.4.2 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


1-12 47 A2 14UR Rev03

• TCLEAN_COBOL

for ORACLE7. These are in the SL library created at ORACLE installation onsite.

These modifications result in an incompatibility between ORACLE7 and theadministration transactions generated for ORACLE V6.

In order to use these transactions with ORACLE7/TDS, you must re-compilethese sources (with the standard COBOL compiler options CARDID = 0,LEVEL = NSTD) and re-link them (with the standard LINKER deliveredwith GCOS 7).

An attempt to use these ORACLE V6 transactions under ORACLE7/TDS (withoutre-compiling and re-linking them) may cause problems (for example, "EX 0E-01fault data descriptor").

47 A2 14UR Rev03 2-1

2. Writing Pro*COBOL TPRs For TDS

This section describes how to write TPRs in Pro*COBOL that contain SQLstatements. For the differences concerning programmers using Pro*C, seesection 8.

Specifically, this means:

• showing the impact on Pro*COBOL programming when the target environmentis TDS (and not IOF),

• the process of embedding SQL statements in COBOL TPRs.

The CONNECT, COMMIT, and ROLLBACK statements work differently in anORACLE/TDS environment. A major part of this section shows, by means ofprogramming examples, how to use these statements.

It is assumed that programmers are already familiar with TDS COBOL and withSQL. If necessary, refer to the TDS COBOL Programmer's Guide and theORACLE7 Server SQL Language Reference Manual. In addition, those who arenot already used to writing Pro*COBOL programs for use under IOF must refer tothe specific Programmatic Interfaces documentation concerning Pro*COBOL.

To build a Pro*COBOL TPR containing SQL statements, the process is thefollowing:

• 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 thenormal process of TPR preparation.

2.1 Connecting To Oracle

The CONNECT statement is used to log on to an ORACLE database. You can findits detailed description in the "ORACLE Precompilers Programmer's Guide".


2-2 47 A2 14UR Rev03

This section only describes how the CONNECT statement works in anORACLE/TDS environment.

The CONNECT statement must be the first executable SQL statement in the TDScommitment unit.

Only declarative SQL statements and host language code can logically precede theCONNECT statement.

2.1.1 The SQL*Net Context Cache

2.1.1.1 Physical Connection Definition

A physical connection is a link between the TDS application and the ORACLEserver. Data exchanges are executed through this link.

It is a connection in two-task mode, as described in the standard ORACLEdocumentation.

A physical connection is identified by its profile which results of the combinationof 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.

2.1.1.2 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.

Writing Pro*COBOL TPRs For TDS

47 A2 14UR Rev03 2-3

2.1.1.3 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 theconnections relative to the same TDS commitment unit are linked to a SQL*Netcontext cache entry and make up the SQL*Net context.

Among all these connections, the first one is very important because it has a greatinfluence 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 aremapped.

• BUSY: There are physical connections on which logical connections aremapped.

2.1.1.4 Why a SQL*Net Context Cache?

ORACLE/TDS maintains a cache of SQL*Net contexts which are used fordatabase connections and cursor parsing. In some cases (see below), contexts canbe "shared" by ORACLE/TDS users.

Context sharing saves unnecessary physical connections and cursor parsing, andreduces the number of processes in ORACLE servers to service a particular TDSapplication. There is a consequent reduction in main memory requirements andCPU consumption to support the application.

2.1.1.5 How Does the SQL*Net Context Cache Work?

1. Connection Processing

Each time a CONNECT statement is executed, the SQL*Net contexts cachemanager is called.

First CONNECT in a TDS commitment unit:

When it is the first CONNECT of a commitment unit, the cache manager triesto retrieve a FREE SQL*Net context cache entry containing a physicalconnection whose profile matches with the current connection.

This search may need two steps:


2-4 47 A2 14UR Rev03

− If a first scan, focused on the first connection of each SQL*Net contextentry, does not retrieve,

− A second scan occurs: this looks at all the connections of each SQL*Netcontext.

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 managerhas to retrieve the SQL*Net context cache entry allocated for the commitmentunit 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 beallocated. The allocation processing depends on the SQL*Net context cachestate 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 connectionsassociated 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. Anew SQL*Net context is created, but the CSIZE value remains unchanged.

2.1.2 Common Syntax of a CONNECT Statement

The common syntax of a CONNECT statement is the following:

@LST@@NE@@@

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 CONNECTstatement are limited.

The username host variable cannot be declared as a character string larger thanPIC X(30).

The password host variable cannot be declared as a character string larger thanPIC X(20).

The db_string host variable cannot be declared as a character string larger thanPIC X(50).

The db_name identifier cannot be a character string larger than 8 characters.


47 A2 14UR Rev03 2-5

If one of these limits is exceeded, the following error message is returned to theTDS application:

"ORAT-25:Invalid host variable definition."

2.1.3 Default Databases and Connections

2.1.3.1 The default Database

The default database is the database to which a COBOL program executing aCONNECT statement is connected if an explicit database specification is omitted.

Under IOF, the default database has the same name as the user's current workingdirectory, 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 thetype of USE clause that appears in the TDS Generation Program.

2.1.3.2 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 anAT clause. SQL statements with an AT clause are executed against the non-defaultconnection.

2.1.3.3 Database Identifiers (SQL*Net)

The AT clause specifies a database identifier.


2-6 47 A2 14UR Rev03

EXAMPLE: Non-default connection

@LST@@NE@@@EXEC SQL DECLARE DB1 DATABASE END-EXEC.EXEC SQL CONNECT :USR IDENTIFIED BY :PWD AT DB1 USING :HSTEND-EXEC.EXEC SQL AT DB1 INSERT INTO T1 VALUES (100) END-EXEC.

q

The database identifier "DB1" is defined in the CONNECT statement to be asymbolic identifier for the database whose access path is contained in the hostvariable HST. Therefore, you must use an AT clause with each SQL statementwhich is executed on the DB1 database.

In a TDS commitment, you cannot execute an SQL statement referencing adatabase identifier, before a CONNECT statement referencing the same databaseidentifier is executed. Otherwise, one of the following error messages will bereturned to the TDS application:

"ORAT-15:No connected database."

or

"ORAT-16:Not logged on the target database."

In a TDS commitment, you can execute two CONNECT statements referencing thesame database identifier but they must have the same user identification and thesame database access path.

For example,

@LST@@NE@@@EXEC SQL CONNECT US1 IDENTIFIED BY PWD1 AT DB1 USING HST1 ........EXEC SQL CONNECT US1 IDENTIFIED BY PWD1 AT DB1 USING HST1

is valid, but:

@LST@@NE@@@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 SQLstatements using the AT clause (with database identifier) now support the AT:host_variable clause.


47 A2 14UR Rev03 2-7

Starting from O7320B the SQL statements using the AT clause (CONNECTstatement included), now support the AT :host_variable clause.

In a TDS environment, the number of distinct database identifiers is limited to 12for a COBOL program (not including the default connection). At execution time,the following error message will be returned to a TDS application which run aCOBOL program using more than 12 distinct database identifiers.

"ORAT-27:Maximum number of database identifiers exceeded."

2.1.3.4 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 is:

@LST@@NE@@@ { [:][:] } { }

supported under ORACLE7/TDS are "D:" (SQL*Net V1ISO/DSA) and "T:" (SQL*Net V1 TCP/IP).

refers to the remote system supporting the database to connect to($ for ISO/DSA connections, for TCP/IPconnections).

is a character string which identifies a database server.For a server running on DPS 7000, it corresponds to the INSTANCE name of thedatabase server (INSTANCE name of database servers can be displayed by usingthe LIST_SVR command - refer to the ORACLE7 Guide to Processor andUtilities).For a server running on UNIX, it corresponds to the ORACLE SID of the databaseserver.

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:]

The general syntax for connecting a non-default database on a remote node is:


2-8 47 A2 14UR Rev03

[D:]$:

or

T::

or

In a TDS environment, it is not possible to connect to a default database on aremote node.

Conflicts between notations like

and

are solved according to the following rule:

• if it runs, on the local node, a database server with an INSTANCE name equal tothe or string (checking case-sensitive), connection willbe made to this local server.

• if not, the or string will be interpreted as an SQL*NetV2 alias to be resolved.

In a TDS environment, only the "D:" and "T:" driver prefixes are supported. Ifanother prefix or a bad prefix is used, the following error message will be returnedto the TDS application:

"ORAT-31: unsupported driver prefix"

Concerning the "T:" driver prefix, only connection to Bull platforms are allowed. Atry to connect to other platforms will return the following error message to the TDSapplication:

"ORAT-29: Connection to remote host failed (unsupported machine)"

EXAMPLE OF CONNECTION

@LST@@NE@@@EXEC SQL DECLARE DB1 DATABASE END-EXEC.EXEC SQL CONNECT :USR IDENTIFIED BY :PWD AT DB1 USING :HSTEND-EXEC.

q


47 A2 14UR Rev03 2-9

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 nameORA7DB, the HST variable must contain "D:$ARE2:ORA7DB".

For a database located on a remote system named DPX210, running under theORACLE 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 nameequal to MY_DB, connection will be tried against this server;

• otherwise, MY_DB will be interpreted as an SQL*Net V2 alias described in aTNSNAMES_ORA configuration file.

2.1.4 Automatic Logons

Usually, you establish a connection to ORACLE as follows:

@LST@@NE@@@ 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, youautomatically log on to ORACLE with the userid OPS$username.

In a TDS environment, username is the identifier, specified at TDS logon, of theuser who started the COBOL program containing the automatic logon. If thisidentifier is more than 8 bytes, the name is truncated. For example, if you connectto TDS as ORAOPER15, you connect to ORACLE as OPS$ORAOPER1 (becauseof the truncation).

Be careful when using the automatic logon feature under TDS. Each time a newTDS user starts a COBOL program containing such a logon, a physical connectionto ORACLE is established.


2-10 47 A2 14UR Rev03

2.1.5 Automatic Restart

The automatic restart facility has some effect on the visibility of the CONNECTstatement.

In most cases, a commitment unit will complete correctly after several retries. Youcan 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 thefailure occurs at commit time, it cannot be notified synchronously to the user'sprogram. Therefore, the commitment is restarted and an error is returned to theTPR (reporting that the CONNECT statement has failed).

2.1.6 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 returnedSQLCODE value provides information to cater for each eventuality.

CONNECT statements may cause particular SQLCODE errors in a TDSenvironment. 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 errormessage:

"ORAT-12:No vacant processes. Retry later."

This means that the basic ORACLE database server does not have enoughprocesses. Use the SOR A command to increase the number of processes, asdescribed in Section 3.

2.2 Commitments

When a Pro*COBOL program runs in a TDS environment, all commitmentunits are managed by TDS as far as possible.

Information relative to the state of the ORACLE commitment are stored in theTDS swap file and in the SYS$TDS table of the database (to commit). It is used to


47 A2 14UR Rev03 2-11

provide the state of the ORACLE database (committed or not) if TDS restarts thecommitment unit.

This has the following important consequences:

• The explicit commitment of an ORACLE database through the EXEC SQLCOMMIT statement is deferred to the end of the TPR regardless of wherethe commit request appears in the code.

• Only one ORACLE database is committed when TDS actually commits. Anyother ORACLE databases are rolled back (see paragraph 2.3.5).

Note that in the following cases, no consistency between TDS and ORACLEcommitments 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 COMMITstatement.

• The COBOL program executes a stored procedure, a package, or a triggercontaining a COMMIT statement.

In each of these 3 cases, if TDS restarts the commitment unit, updates toORACLE databases may be executed twice.

Another important difference between the TDS and IOF environments is that whena TPR actually commits, all the databases connected in the commitment unit arelogically disconnected. See paragraph 2.3.1.

It is as if a COMMIT WORK RELEASE statement had been executedsimultaneously for each connected database. No more SQL statements can beexecuted until a CONNECT statement is issued. See paragraph 2.3.4.

The various commit options and commit behaviours are illustrated in the examplesthat follow.

2.2.1 Using Implicit Commitment

The IMPLICIT COMMITMENT function of TDS defines the end of each TPRpreceding a terminal conversation as the end of a commitment unit.

EXAMPLE: Using implicit commitment

If the IMPLICIT COMMITMENT function of TDS is used, the CONNECTstatement and the INSERT statement are executed, and are committed as soon asthe TPR ends.

@LST@@NE@@@


2-12 47 A2 14UR Rev03

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.

q

2.2.2 Using CALL "DFCMIT"

The CALL "DFCMIT" procedure requests a commitment to be taken at the end ofthe TPR.


47 A2 14UR Rev03 2-13

EXAMPLE: Using a commitment (CALL "DFCMIT")

@LST@@NE@@@


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 TPRends, 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 functionallyequivalent to the following one ("CMT2-LIKE"):

@LST@@NE@@@


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.

q

2.2.3 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.


2-14 47 A2 14UR Rev03

It commits the database associated with the default connection regardless ofwhere the COMMIT statement appears.

2. EXEC SQL AT COMMIT WORK END-EXEC.

It commits the specified database regardless of where the COMMIT statementappears.

The RELEASE option associated with the COMMIT statement is not supported inthe TDS environment.

Whether you specify RELEASE or not, the behaviour of the COMMIT statement isthe 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):

@LST@@NE@@@


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.q

2.2.4 Automatic Disconnection from ORACLE After COMMIT

The TDS commitment unit acts as a logical disconnection of all the databases ofthe SQL*Net context.

EXAMPLE: Disconnection

Look at the following TPRS ("BEGCMT4" and "ENDCMT4").

@LST@@NE@@@


47 A2 14UR Rev03 2-15


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.


PROGRAM-ID. ENDCMT4.......EXEC SQL INSERT INTO T1 VALUES (101) END-EXEC.......EXEC SQL COMMIT WORK END-EXEC.......EXIT PROGRAM.

q

These two TPRs will execute correctly as long as the IMPLICITCOMMITMENT 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. TheINSERT statement in the TPR "ENDCMT4" fails since you are no longerconnected 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 CONNECTstatement at the beginning of the TPR "ENDCMT4". This will restore theconnection to the database and ensure that the INSERT statement does not fail dueto previous disconnection.


2-16 47 A2 14UR Rev03

So, if the TPR "ENDCMT4" is modified as shown below, the two TPRs willalways execute sequentially as required, even if no commit occurs at the end of theTPR "BEGCMT4".

@LST@@NE@@@


PROGRAM-ID. ENDCMT4.......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.

2.2.5 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 COMMITstatement is used, the TPR commits the target ORACLE database of the last SQLstatement to be executed.

If two ORACLE databases have to be committed, use different TPRs (or differentexecutions of the same TPR) and update only one ORACLE database per TPR.See paragraph 2.2.6.

The two examples that follow are intended to illustrate the way that commitmentswork.

EXAMPLE: Default commitment

The following TPR "CMT5" updates two ORACLE databases: the defaultdatabase, and the database whose identification is contained in the host variableHST (referenced by the symbol DB1).

@LST@@NE@@@


PROGRAM-ID. CMT5.


47 A2 14UR Rev03 2-17

...


EXEC SQL CONNECT :USR IDENTIFIED BY :PWD AT DB1 USING :HSTEND-EXEC.


EXEC SQL AT DB1 INSERT INTO T2 VALUES (100) END-EXEC.

CALL "DFCMIT".

EXIT PROGRAM.

q

At the end of the TPR, only the database DB1 is committed because this is thedatabase on which the last statement was executed. The default database is rolledback, and the corresponding INSERT statement is lost.

To override the default, you use the COMMIT WORK statement. This forces acommitment 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 onthe default database, even if the last statement in the TPR refers to a differentdatabase.

@LST@@NE@@@


PROGRAM-ID. CMT5.

...


EXEC SQL CONNECT :USR IDENTIFIED BY :PWD AT DB1 USING :HSTEND-EXEC.




2-18 47 A2 14UR Rev03

EXEC SQL COMMIT WORK END-EXEC.

EXIT PROGRAM.

q

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 theCOMMIT WORK statement instead of the standard CALL "DFCMIT" or theIMPLICIT COMMITMENT option of TDS.

2.2.6 Commit Separate Databases in Separate TPRs

If several COMMIT WORK statements applying to several different ORACLEdatabases are executed within the same TPR, the following error message will bereturned to the TDS application after the execution of the second COMMITWORK statement:

"ORAT-17:Commit on several databases not allowed"

In this case, the only database that is committed is the one referenced by the firstCOMMIT statement (unless a ROLLBACK is requested to rollback all thedatabases).

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 separateTPRs:

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 commitments.

@LST@@NE@@@


PROGRAM-ID. UPD1.

...



47 A2 14UR Rev03 2-19



MOVE "UPD2" TO NEXT-TPR.

EXIT PROGRAM.


PROGRAM-ID. UPD2.

...

EXEC SQL CONNECT :USR IDENTIFIED BY :PWD AT DB1 USING :HOSTEND-EXEC.


EXEC SQL AT DB1 COMMIT WORK END-EXEC.

EXIT PROGRAM.

q

EXAMPLE: Update two databases by writing a "two path" TPR

An alternative to using two separate TPRs to update two ORACLE databases is towrite a "two-path" TPR where the paths are mutually exclusive and where eachpath is determined by the current value of a switch variable.

The TPR "CMT6" sequentially updates two ORACLE databases. The TPR willexecute twice, producing two commitment units updating one database each.

The TPR uses a switch variable to determine which database is to be updated andcommitted.

@LST@@NE@@@


PROGRAM-ID. CMT6....

IF PHASE = 2 GO TO UPD2.



2-20 47 A2 14UR Rev03



MOVE 2 TO PHASE.

MOVE "CMT6" TO NEXT-TPR.

GO TO END-OF-TPR.

UPD2.

EXEC SQL CONNECT :USR IDENTIFIED BY :PWD AT DB1 USING :HST END-EXEC.



MOVE 1 TO PHASE.

MOVE ALL SPACES TO NEXT-TPR.

END-OF-TPR.

EXIT PROGRAM.

q

"PHASE" is a numeric variable used as a switch. It is declared inTRANSACTION-STORAGE and initialized to 1.

2.2.7 EXEC SQL COMMIT Errors

COMMIT statements may cause certain errors in a TDS environment. SeeAppendix A.

Failures during the commit phase (at TPR TERM) induce the restart of the TDScommitment unit, in order to notify errors to the TDS application on everyCONNECT statement of the commitment unit. See Appendix A.

2.3 Rollback

The various rollback options are illustrated in the examples that follow.


47 A2 14UR Rev03 2-21

2.3.1 The ROLLBACK Statement

The ROLLBACK statement is always executed synchronously; that is, it is notdeferred to the end of the current TPR.

ROLLBACK affects only the ORACLE database to which it is applied - either thedefault ORACLE database or a specific one (using the AT clause).

ROLLBACK does not affect the processing of the current TPR, updates made toanother 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 isexecuted synchronously. The TPR can continue; another database can becommitted.

2. EXEC SQL AT ROLLBACK WORK END-EXEC.

This rolls back the ORACLE database specified by only. It is executedsynchronously. The TPR can continue; another database can be committed.

The RELEASE option associated with the ROLLBACK statement is not supportedin a TDS environment. The COMMIT statement behaves in the same way with orwithout the RELEASE option, that is, COMMIT does not free resources and itdoes 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, butcommits the second update.

The ROLLBACK statement is executed synchronously, so the first INSERTstatement is immediately rolled back. The processing of the current TPRcontinues; the second INSERT statement is executed, a commitment is requested,and finally, at the end of the TPR, the second INSERT is committed.

@LST@@NE@@@


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.


2-22 47 A2 14UR Rev03

EXIT PROGRAM.

q

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 statementrefers, by default, to the default database.

The COMMIT WORK statement commits the update on database DB1.

@LST@@NE@@@


PROGRAM-ID. ROL2.

...


EXEC SQL CONNECT :USR IDENTIFIED BY :PWD

AT DB1 USING :HST END-EXEC.



EXEC SQL ROLLBACK WORK END-EXEC.


EXIT PROGRAM.

2.3.2 The TDS "ROLL-BACK" Primitive

The TDS "ROLL-BACK" procedure rolls back the transaction to the first TPR ofthe current commitment unit.

It undoes work done on all the ORACLE databases of the SQL*Net contextsince the last commitment.

Such a rollback is managed by TDS, and is immediate. TPR processing isinterrupted; the transaction is restarted after the rollback.

Such a rollback induces a logical disconnection of all the databases of theSQL*Net context.


47 A2 14UR Rev03 2-23

EXAMPLE: Using the TDS CALL "ROLL-BACK" primitive

If the TPR "ROL3" detects an - for example, some data hasbeen modified by another user so that the context of the current TPR is no longervalid - the TPR issues a CALL "ROLL-BACK" to request all the work done sincethe last commit to be undone. This triggers a rollback of all the databases of theSQL*Net context, and each one is logically disconnected.

When TDS restarts TPR execution (to try to perform the processing again), thePro*COBOL statements are executed again as if for the first time.

@LST@@NE@@@


PROGRAM-ID. ROL3.

...



...

IF CALL "ROLL-BACK".

...


EXIT PROGRAM.

q

2.3.3 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, insteadof 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 isa commitment point.


2-24 47 A2 14UR Rev03

If you execute an EXEC SQL COMMIT statement and a CALL "INVCMIT"statement in the same TPR, the TDS commitment and consequently the ORACLEcommitment will be invalidated at the end of the TPR.

2.3.4 The TDS "NOCMIT" Primitive

The TDS "NOCMIT" procedure cancels the commitment action at the end of thecurrent TPR, unless the TPR is the last TPR of the transaction.

The CALL "NOCMIT" cancels any EXEC SQL COMMIT statement calledbeforehand in the same TPR.

2.3.5 FOR DEBUG Clause

You can specify the FOR DEBUG clause in the MESSAGE statement of theTRANSACTION SECTION of the STDS. This is used to denote the transactionswhich are to be debugged.

DEBUG mode affects the connected ORACLE databases in the following way: ateach commitment point of a transaction which is FOR DEBUG, the ORACLEdatabases are rolled back instead of being committed, just as for UFAS files orIDS/II databases.

2.4 Data Definition Statements

Data Definition statements (DDL) are used to define, maintain, and drop databaseobjects (such as tables or views).

DDL statements are "autocommitted". This makes them tricky to use in a TPRcontaining DML statements. Their use can lead to the desynchronization ofcommitments between TDS and the corresponding ORACLE database server.

If you have to use DCL or DDL statements in a TDS application, we stronglyrecommend you to issue them within a separate commitment unit (whichimplies a separate TPR). Otherwise, DML statements may easily be committed bya DCL or DDL command. The consequent risk is that the DML might be executedmore 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 run-time.


47 A2 14UR Rev03 2-25

EXAMPLE: DDL and DML statements in the same TPR

This TPR "DDL1" could desynchronize commitments. The DDL statementCREATE TABLE is issued (and carries out a commitment) before the INSERTstatement is supposed to be committed.

@LST@@NE@@@


PROGRAM-ID. DDL1.

...



EXEC SQL CREATE TABLE T2 (X NUMBER) END-EXEC.


...

EXIT PROGRAM.

q

EXAMPLE: DDL and DML statements in separate TPRs

The TPRs "DDL2" and "DDL3" are executed sequentially; there is no risk that theINSERT statement will be executed more than once.

@LST@@NE@@@


PROGRAM-ID. DDL2.

...




MOVE "DDL3" TO NEXT-TPR.

...


2-26 47 A2 14UR Rev03

EXIT PROGRAM.


PROGRAM-ID. DDL3.

...


EXEC SQL CREATE TABLE T2 (X NUMBER) END-EXEC.


...

EXIT PROGRAM.

q

NOTE:In both previous examples, the CREATE statement may be executed twice ormore if the TPR executing this statement fails before taking a successfulcommitment. Bear this in mind each time you include a DDL statement in aTPR. In the above examples, SQLCODE may be set after the execution of theCREATE statement to a value indicating that the table already exists eventhough 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 theORACLE/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 ORACLEerror codes.

So you must use the “WHENEVER SQLERROR” clause to be sure to detect allpossible errors.


47 A2 14UR Rev03 2-27

2.5.1 Using the WHENEVER Statement

You code the WHENEVER statement using the following syntax:

EXEC SQL WHENEVER END-EXEC

In the ORACLE/TDS environment, the STOP action is not supported. If you useit, you will have an abort of the TPR (return code: TP7 2, USEREQ) if thecondition is met.

2.5.2 Using the ORACLE Communications Area (ORACA)

Two entry points: ORASTAT and GETSTM may be called from a COBOLprogram to get a subset of information recorded in the ORACA structure.

The ORASTAT entry point which provides information about cursor cachestatistics 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 TPR:

@LST@@NE@@@

01 MESS-BUFF PIC X(70).01 BUFF-SIZE PIC S9(9) COMP-2.01 MESS-LGT PIC S9(9) COMP-2.

If connected to ORACLE, you can call GETSTM using the syntax:

@LST@@NE@@@

MOVE 70 TO BUFF-SIZE. CALL "GETSTM" USING MESS-BUFF, BUFF-SIZE, MESS-LGT

where

MESS-BUFF is the text buffer in which you want ORACLE to storethe SQL statement in error.

BUFF-SIZE is an integer variable that specifies the maximum sizeof the buffer in bytes.

MESS-LGT is an integer variable in which ORACLE stores actuallength 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


2-28 47 A2 14UR Rev03

GETSTM, before being connected or when SQLCODE is zero, the text buffer maybe filled with blank characters or you can get a prior invalid SQL statement.

2.6 Precomp

Documents

ORACLE 7 / TDS User's Guide - Bullsupport.bull.com/ols/product/system/gcos7/gcos7-com/g7... · 2006. 4. 11. · with the ORACLE and TDS products. Administrators who are responsible