Bull DPS 7000 User's Guidesupport.bull.com/ols/product/system/gcos7/gcos7... · Database Products Bull DPS 7000 User's Guide ORACLE7/TDS User's Guide ... Suggestions and criticisms

47 A2 14UR Rev03

Database Products

Bull DPS 7000User's Guide

ORACLE7/TDS User's Guide

GCOS 7

Subject: The purpose of this guide is to introduce the ORACLE7/TDSfacilities and to show how to use ORACLE7 databases withTDS applications under the GCOS 7 V6 and V7 operatingsystem.

Special Instructions: Revision 03 replaces revision 02 for a new version ofORACLE7. Change bars in the margin indicate differencesbetween revision 03 and 02.

Software Supported: From ORACLE7 version 07106E.GCOS 7-V7 from TS7458

Software/Hardware required:

Date: May 1999

Bull S.A.CEDOCAtelier de reprographie34, rue du Nid de Pie BP 42849004 ANGERS Cedex 01FRANCE

Bull HN Information Systems Inc.Publication Order EntryFAX: (978) 294-7411MA30/865ATechnology ParkBillerica, MA 01821U.S.A.

47 A2 14UR Rev03

Copyright Bull S.A., 1992, 1995, 1996, 1999

Bull acknowledges the rights of proprietors of trademarks mentioned herein.

Suggestions and criticisms concerning the form, content, and presentation of this manual are invited. A form isprovided at the end of this manual for this purpose.

Bull disclaims the implied warranties of merchantability and fitness for a particular purpose and makes noexpress warranties except as may be stated in its written agreement with and for its customer. In no event is Bullliable to anyone for any indirect, special, or consequential damages.

The information and specifications in this document are subject to change without notice. Consult your BullMarketing Representative for product or service availability.

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


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:

<variable> 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 <name-50>). TheORACLE block is available only if your GCOS 7-V6Technical Status is at least TS6152.

USE ORACLE-BASE-<name>. The name of the default database is the onespecified by <name-50>, 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 <name-50> 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 <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 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 <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 use:

@LST@@NE@@@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 usedTS >= 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. 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 <name>" instead of"USE ORACLE-BASE-<name>". 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-<name-50>. }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@@@ { [<prefix>:][<node>:]<instance-name> } { <alias> }

<prefix> supported under ORACLE7/TDS are "D:" (SQL*Net V1ISO/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/IPconnections).

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

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


2-8 47 A2 14UR Rev03

[D:]$<system-name>:<instance-name>

or

T:<system-name>:<instance-name>

or

<alias>

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

Conflicts between notations like

<instance-name>

and

<alias>

are solved according to the following rule:

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

• if not, the <instance-name> or <alias> 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 <db> 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 <db> ROLLBACK WORK END-EXEC.

This rolls back the ORACLE database specified by <db> 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 <abnormal-condition> - 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 <abnormal-condition> 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 <condition> <action> 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 Precompiling, Compiling And Linking

2.6.1 Precompiling a Pro*COBOL TPR

To precompile a Pro*COBOL TPR, use PCC (the PreCompiler, Common). This isdescribed in the ORACLE7 Guide to Processors and Utilities.

With ORACLE7 and version 1.5 of the precompilers, there is no difference atprecompiler level, between precompiling a Pro*COBOL program for TDS andprecompiling 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 inthe MYDIR.SL library.

This file must then be compiled by the COBOL-85 compiler (see further on).

q

2.6.2 Compiling a Pro*COBOL TPR

There is no difference at compiler level between compiling a Pro*COBOL programfor TDS, and compiling for IOF or batch. Refer to the ORACLE7 Guide toProcessors and Utilities for the standard descriptions.

But there are two special GCOS 7 compilation options which must be specifiedwith the COBOL 85 compilers. They are:

LEVEL=NSTD

CARDID=0

This is because PCC sometimes generates non-standard COBOL statements, andproduces an output source file in raw format.


47 A2 14UR Rev03 2-29

EXAMPLE: Compiling a Pro*COBOL TPR

To compile the TPR MYTPR_PCC, enter:

S: CBL MYTPR_PCC MYDIR.SL LEVEL=NSTD CARDID=0;

q

2.6.3 Linking a Pro*COBOL TPR

There is no difference at linkage level between linking a Pro*COBOL program forTDS, and linking for IOF or batch. Refer to the ORACLE7 Guide to Processorsand 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. TheORACLE_LNK subfile which contains LINKER statements for ORACLE batchprograms 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 COBOLprogram identification.

q

2.6.4 Example of JCL stream generating a Pro*COBOL TPR

This example shows a JCL stream that calls PCC to precompile a Pro*COBOLTPR, calls the GCOS 7 COBOL 85 compiler to compile it, and calls LINKER tolink it. The complete JCL stream is retained to help you.

@LST@@NE@@@

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


2-30 47 A2 14UR Rev03

7 LANGUAGE=AMERICAN 8 TDS=OTDS 9 FORMAT=ANSI10 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=NO18 OPTIONS=&OWD'/'&LDIR'/'&MSGDIR'/'&LANGUAGE'/* INAME='&LDIR'.SL..'&TPR'19 FORMAT='&FORMAT'20 INCLUDE='&ORADIR'.SL21 USERID=PHAM/PHA22 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!!_PCC31 MAP,32 XREF,ILN33 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.CU42 OUTLIB=&LDIR.SM43 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;

47 A2 14UR Rev03 3-1

3. Running an ORACLE/TDS Application

To run an ORACLE/TDS application, four preparatory steps are necessary inaddition to the standard TDS preparation:

• Ensure that the GCOS 7-specific file TDS_SQL is executed at database creationtime.

• 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 theH_ORACLE and H_ORATDS sharable modules, is described in the ORACLE7Installation Guide. If using ORACLE in a TDS-HA environment, you will needthe ORACLE7/TDS-HA User's Guide.

3.1 The Tds_Sql File

To use the ORACLE/TDS facilities via an ORACLE server, the ORACLE databaseneeds 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 casethe file must be processed under the SYS user-id) to execute the contents of theTDS_SQL script.

For example: SQLDBA> @TDS;

3.2 The Oracle Communications Server (Cor)

A TDS application cannot access an ORACLE database unless the ORACLEcommunications server (COR) is active.


3-2 47 A2 14UR Rev03

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 (configurationfiles,...)

Furthermore, use of an SQL*Net V2 Adapter is recommended (refer to chapter 3 ofthe SQL*Net V2 with GCOS 7 User's Guide)

3.2.1 Starting COR

To start the ORACLE communications server, use the COR command from anyIOF terminal:

S: COR I;

COR starts a batch job which issues a message as soon as the server is ready.

3.2.2 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 itprevents new ones from being established.

3.3 The Oracle Database Server

ORACLE database servers are managed independently of the TDS applicationsfrom which they are accessed.

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

Running an ORACLE/TDS Application

47 A2 14UR Rev03 3-3

3.3.2 Adding Extra Connections

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.

The number of available user processes of ORACLE should be equal to the numberof contexts of the SQL*NET cache, determined by the CSIZE value. See therelevant chapters for the SQL*NET context cache and CSIZE.

You can use the SOR A command to increase the number of processes of theORACLE server.


3.3.3 Stopping ORACLE

Stopping ORACLE involves two distinct stages:

• Shutting down the database with the SQL*DBA processor.

• Stopping database activity with the SOR command.


If the TDS application is still running, you must dynamically disable theconnections between TDS users and the database server by using the ORACLEtransaction with TERM option.

3.4 The H_Oratds Sharable Module

The H_ORATDS sharable module is a component of the ORACLE/TDS run-timepackage. It is the interface between ORACLE and TDS, and is packaged in thestandard ORACLE delivery kit.

Load H_ORATDS into backing store before the TDS application is started so that itis 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 TDSapplication. A JOBLIB SM statement must also be present which specifies theSharable Module library where H_ORATDS has been installed, as well as the oneor two other Sharable Module libraries where the TPRs reside.


3-4 47 A2 14UR Rev03

EXAMPLE:

q

The JCL below shows how the H_ORATDS and TPR sharable modules are loadedinto backing store.

The TDS name is ORAT, and the H_ORATDS sharable module is packaged in theORA7.ST sys.system file. The H_ORATDS and TPR sharable modules arereloaded each time the job is launched. There can be three SMLIBs with theJOBLIB statement.

@LST@@NE@@@

$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 dynamicallyswitch the Sharable Module library order of priority.

Running an ORACLE/TDS Application

47 A2 14UR Rev03 3-5

3.5 Tds Error Messages Relating To Oracle

MU86. ORACLE INITIALIZATION FAILED

Meaning: The SM containing ORACLE is not loaded; or thecorrect library is not specified in the JOBLIBstatement.

Action: Ensure that the SM containing ORACLE is loaded; orensure that the correct library is specified in theJOBLIB statement.

MU87. ERROR DETECTED IN ORACLE/TDS PROTOCOL

Action: None - internal error.


3-6 47 A2 14UR Rev03

q

47 A2 14UR Rev03 4-1

4. Tuning ORACLE/TDS: ConfigurationParameters

The configuration parameters of the ORACLE/TDS layer are used to tune theaccess 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 dynamicallymodified through the "ORACLE" transaction.

The current configuration parameters available with your ORACLE7/TDS versionare :

• 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 andORACLE/TDS is provided. This makes ORACLE/TDS more independent fromTDS. It is possible to modify, add or suppress ORACLE/TDS configurationparameters without having to wait for the next GCOS 7 Technical Status.

With this new interface, the TDS or ORACLE administrator is able to setORACLE/TDS configuration parameters by manipulating an ORACLE reservedblock in the STDS file. The dynamic changes of the configuration parametersvalues will remain visible until the next COLD restart of TDS; at that time, thevalues will return to those set at TP7GEN time.


4-2 47 A2 14UR Rev03

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 themessage "*** UNEXPECTED STATEMENT. LOOK FOR THE NEXTMANDATORY 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: thevisibility remains the same as for ORACLE V6. These values are:

− MAXTIM = 20000,− MAXWAT = 240000,− TIMOUT = 20000,− CSIZE = 16,− TRACELVL = 1.

• Dynamically changed values will in any case remain valid until next TDSCOLD restart.

• Note that at the first COLD restart after a TDS generation, you will get awarning 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=B3910437->XUFAS 81,RECNFD

• A TDS previously used with ORACLE V6/TDS must be stopped/started withthe COLD option. Otherwise the startup phase will be aborted with the errormessage:

− MU08 Xxxx.3 TDS : <tds-name> FATAL ABORT, REASON :− ORACLE INITIALIZATION FAILED− RC=B3910437->XUFAS 81,RECNFD

• This is due to the new interface between TDS and ORACLE7/TDS. ORACLEtries to read the record corresponding to the ORACLE block in the STDS. As

Tuning ORACLE/TDS: Configuration Parameters

47 A2 14UR Rev03 4-3

this record does not exist (because there is no such block), a WARNING isissued.

If you choose to use the new facility, then you can start your ORACLE7/TDSapplication 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 writeMAXTIM IS 20000 MAXWAT IS 4000.

but write instead:MAXTIM IS 20000.MAXWAT IS 4000.

− 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 andTP7GEN results in an error. None of the lines preceding and following theerroneous 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. Forexample, with a STDS file as below:

− ORACLE-DEF− MAXTIM IS 40.− MAXWAT IS 10000.

• the following error message will be recorded in the Xxx:2:2 of the TP7GENstep:

− ORACLE-DEF− MAXTIM IS 40.− MAXWAT IS 10000.− ORACLE-ENDDEF

TG75-*** ERRONEOUS PARAGRAPH:ORACLE-DEF..ORACLE-ENDDEF


4-4 47 A2 14UR Rev03

Value out of bounds for parameter: MAXTIM

• The usage of the DEFAULT_DATABASE parameter is not the same as theother parameters. It cannot be updated through the "ORACLE" transactionand interacts with the "USE ORACLE" clause of the STDS; all details are givenin the paragraph 1.9 of Chapter 1 of this guide.

IMPORTANT NOTE:You must launch your TP7GEN step with the value of the keyword ORASTLIBset to the SMLIB which contains the H_ORATDS Sharable Module.

4.2 Setting Configuration Parameters Dynamically

4.2.1 Transaction Description

The ORACLE/TDS configuration parameters visible just after first startup of yourTDS application may be dynamically modified through the "ORACLE"transaction.

If your Technical Status is TS6152 or later (that is, >= TS6152), these dynamicchanges will be lost at warm restart. Otherwise (new interface starting withTS6152, 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 usedto dynamically tune the ORACLE/TDS interface. It implements the call to anentry point named ORATCONF in the ORACLE/TDS sharable moduleH_ORATDS. This entry point interacts with TDS to effectively change theconfiguration parameters and make them remain until the next COLD restart (if TS>= TS6152).

4.2.2 How to Use ORATDS

To use ORATDS, assign the "ORACLE" message to the ORATDS linkage unit inthe 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


47 A2 14UR Rev03 4-5

The ORACLE transaction has several parameters for tuning the ORACLE/TDSinterface. These parameters may be divided into two categories: IDENTs andKEYWORDs.

IDENTs

IDENTs are used to update values in the corresponding fields of the TDSSEG. Thesyntax for these parameters must include an "=", for example MAXWAT = 90000.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 toORACLE Databases from the TDS application. Both uppercase and lowercaseletters are accepted.

The KEYWORDs accepted are listed below:

• DISPLAY,

• ENABLE,

• DISABLE,

• TERM,

• WAIT,

• TRACEON,

• TRACEOFF,

• TRACE.

All these parameters are described separately below.

Restrictions


4-6 47 A2 14UR Rev03

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 ENABLENeither 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 takeninto account.

4.2.3 Description of the "ORACLE" Transaction Parameters

After each modification of one of the configuration parameters, all of them aredisplayed upon the terminal.

4.2.3.1 MAXTIM Parameter

The MAXTIM parameter specifies the maximum time in milliseconds allowed foran 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, thecurrent ORACLE operation is cancelled, the commitment unit is rolled back, andthe TDS transaction is aborted. The return code issued is "ORACLE 38,TIMEOUT".

Setting MAXTIM

The default value is 20000 milliseconds.

The minimum value is 1000 milliseconds.

The maximum value is 1000000 milliseconds.

The default value of MAXTIM is the same as the default value of TIMOUT (seebelow). If the value of MAXTIM is no greater than the value of TIMOUT, the


47 A2 14UR Rev03 4-7

deadlock detection mechanism of TIMOUT with automatic rollback is never usedsince the value of MAXTIM takes precedence.

If MAXTIM is set to 0, the current value is left unchanged.

4.2.3.2 MAXWAT Parameter

The MAXWAT parameter specifies the maximum time a TPR can wait to re-establish an ORACLE connection that has been lost during the commit phase.


Setting MAXWAT




MAXWAT should be set to a value which corresponds to the maximum time theORACLE database may be unavailable; that is, at least for the duration of a warmrestart of the ORACLE database. It is also advisable to add the time necessary torestore 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 MAXWATmilliseconds, 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 currentcommitment 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=-6should be processed as a simple CONNECT failure (no risk of data beingdamaged).

• if data has been modified, abort the C.U. and check data in the database.


4-8 47 A2 14UR Rev03

4.2.3.3 TIMOUT Parameter

TIMOUT specifies the maximum time a TPR is allowed to wait for a non-availableresource in an ORACLE database.

It is used to detect deadlocks between databases.


When the timeout event occurs, the current ORACLE operation is cancelled, thecommitment unit is rolled back, and then restarted.

Setting TIMOUT




If TIMOUT is set to 0, the current value is left unchanged.

4.2.3.4 CSIZE Parameter

The CSIZE parameter specifies the number of ORACLE contexts which can becached by the ORACLE/TDS interface. This can help optimize the performance ofORACLE/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 1024.

If set to 0, the current value is left unchanged.

In the Job Occurrence Report (JOR) of the ORACLE/TDS session you will findstatistics relating to the ORACLE/TDS cache. These will help in determining anoptimum value for CSIZE.

Changing the value of CSIZE may have direct consequences to the performance ofyour TDS application. So, you must be aware of the fact that:

• Reducing the CSIZE value reduces the number of ORACLE/TDS contextscached. Then, "x" cache entries will be destroyed (where x = actual cache size -new CSIZE). This results in the physical disconnection of all connections


47 A2 14UR Rev03 4-9

entries linked to each of these cache entries. The deleted cache entries are theoldest FREE entries.

• Setting CSIZE to -1 disconnects all FREE entries in the cache, which allows theshutdown of the accessed ORACLE servers without stopping your TDSapplication (cache size is reduced to 0). For more information onORACLE/TDS context caching, please refer to Chapter 5.

4.2.3.5 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 0.

4.2.3.6 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 writtenin 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 newORACLE transaction command. This, first close the current subfilename_trc andthen, opens the new one

• if a trace level is active and no trace file mentioned ORACLE7 opens theORACLE_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.


4-10 47 A2 14UR Rev03

4.2.4 Description of KEYWORDs

4.2.4.1 "ORACLE DISPLAY"

This keyword displays the values of all configuration parameters on terminalconsole. It also displays the status of the communication between the TPR and theORACLE server.

@LST@@NE@@@

************************************************************* ORA/TDS Configuration **----------------------------------------------------------** MAXTIM = ** MAXWAT = ** TIMOUT = ** CSIZE = ** TRACELVL =************************************************************* ORA/TDS Layer status **----------------------------------------------------------** ORA/TDS communication ready *************************************************************

4.2.4.2 "ORACLE ENABLE"

If the communication with the ORACLE server has ceased, this keyword allowsnew connections to be established (by unsetting one bit). This function does notwait for the COR to be ready. If there is no COR, a return code NOINIT isproduced, and following message is issued:

@LST@@NE@@@

************************************************************** ORA/TDS Layer status **-----------------------------------------------------------** ORA/TDS Communication not available: COR server not ready **************************************************************


47 A2 14UR Rev03 4-11

If you want to wait for the COR on your connection, see the keyword "WAIT"further on.

When communication is established, you get:

@LST@@NE@@@

************************************************************** ORA/TDS Layer status **-----------------------------------------------------------** ORA/TDS communication ready **************************************************************

4.2.4.3 "ORACLE DISABLE"

You may use this keyword if you want to prevent new connections to beestablished to the ORACLE server. The cache is not cleaned, and existingconnections are not stopped. A status on established connections is given:

• if all connections are stopped when you ask for DISABLE action, you get:

@LST@@NE@@@

*************************************************************** ORA/TDS Layer status **------------------------------------------------------------** All ORA/TDS connections stopped;New connections prohibited ***************************************************************

• if there are still connections, you get:

@LST@@NE@@@

*************************************************************** ORA/TDS Layer status **------------------------------------------------------------** Oracle connections still alive; New connections prohibited ***************************************************************

4.2.4.4 "ORACLE TERM"

This keyword permits you to:


4-12 47 A2 14UR Rev03

• 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 beforedisconnecting. In that case, you will get:

@LST@@NE@@@

*************************************************************** ORA/TDS Layer status **------------------------------------------------------------** Waits for users disconnection ***************************************************************

Once all users are disconnected, you get:

@LST@@NE@@@

*************************************************************** ORA/TDS Layer status **------------------------------------------------------------** ORA/TDS communication disabled ***************************************************************

4.2.4.5 "ORACLE WAIT"

This does the same as "ORACLE ENABLE", except that it waits for the COR to beready (if it is not ready).

@LST@@NE@@@

*************************************************************** ORA/TDS Layer status **------------------------------------------------------------** Wait for ORA/TDS communication to be ready ***************************************************************


47 A2 14UR Rev03 4-13

4.2.4.6 "ORACLE TRACEON"

This keyword permits to switch on the System Trace mechanism.

@LST@@NE@@@

*************************************************************** ORA/TDS Layer status **------------------------------------------------------------** ORA/TDS trace level is 1 : basic ***************************************************************

4.2.4.7 "ORACLE TRACEOFF"

This keyword permits to switch off the trace mechanism.

@LST@@NE@@@

*************************************************************** ORA/TDS Layer status **------------------------------------------------------------** ORA/TDS trace mode is off ***************************************************************

4.2.4.8 "ORACLE TRACE"

This keyword displays the status of the System Trace mechanism: basic, detailed,off.

You get one of the two preceding messages, or:

@LST@@NE@@@

*************************************************************** ORA/TDS Layer status **------------------------------------------------------------*


4-14 47 A2 14UR Rev03

* 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

4.3.1 Job Occurrence Report Statistics

Statistics are displayed in the Job Occurrence Report (JOR) of the TDS applicationwhen 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 JOR:

@LST@@NE@@@

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


47 A2 14UR Rev03 4-15

The meaning of these statistics is as follows:

Cache Size This gives the value of the CSIZE parameter at thetime the TDS application stops.

Nb of CTX Ent Used The maximum number of simultaneously validSQL*Net contexts in the cache during the TDSsession. A valid SQL*Net context is one whichcontains at least one physical connection to anORACLE server. As defined in section 2, it is a FREEor a BUSY SQL*Net context.

Nb of XA CTX Ent Used The maximum number of simultaneously validSQL*Net XA contexts in the cache during the TDSsession.See Section 7 for more details on XA.

Nb of CTX Ent Reassign The number of FREE SQL*Net contexts which havebeen reassigned. All the physical connections of sucha context are broken before establishing newconnections with different profiles.

Nb of Physical Connects This indicates the number of physical connections toORACLE servers which have been established duringthe TDS session.

Nb of Used Small Segs This indicates the number of 64K segments whichhave been used by the ORACLE/TDS layer during theTDS session.

Nb of Used Large Segs This indicates the number of large segments whichhave been used by the ORACLE/TDS layer during theTDS session.

Total Memory Used This indicates the memory consumption in Kbytes ofthe ORACLE/TDS layer.

Limit Nb of Small Segs This indicates the number of small segments whichcan be used before memory allocation takes place inlarge segments.

Nb of Open Cursors This indicates the number of cursors used during theTDS session.

Nb of Cursor Reassign This indicates the number of cursor reassignmentsduring the TDS session.

Nb of Stmt parses This indicates the number of SQL statements parsed,during the TDS session.


4-16 47 A2 14UR Rev03

Nb of Stmt executions This indicates the number of SQL statements executed.

For performance purposes, some of the counters associated with the abovestatistics are updated without locking any resources. For this reason, thosestatistics may be a little inaccurate.

4.3.2 The CASTAT Transaction

The CASTAT transaction is used to dynamically display statistics on the SQL*Netcontext cache and the memory consumption.

Source of the transaction is delivered in the standard ORACLE kit. The name ofthe source program is CASTAT_COBOL.

To use CASTAT: compile the CASTAT_COBOL program, link it in the TPRsharable module, and assign the "CASTAT" message to the CASTAT linkage unitin the STDS file of your TDS application.

Below is the set of statistics displayed by the CASTAT transaction:

@LST@@NE@@@

********************************************************************* 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 Version of the H_ORATDS sharable module used bythe TDS application

Context Cache Size This gives the current value of the CSIZE parameter.


47 A2 14UR Rev03 4-17

Nb of Busy Entries This value gives the current number of SQL*Netcontexts in the cache which are associated with acommitment unit in execution.

Nb of Free Entries This value gives the current number of SQL*Netcontexts in the cache which contain one or more validconnections to ORACLE servers, but which are notassociated with a commitment unit in execution.

Nb of Busy XA Entries This value gives the current number of SQL*Net XAcontexts in the cache which are associated with acommitment unit in execution. See Section 7 formore details concerning XA.

Nb of Free XA Entries This value gives the current number of SQL*Net XAcontexts in the cache which contain one or more validconnections to ORACLE servers, but which are notassociated with a commitment unit in execution. SeeSection 7 for more details concerning XA.

Nb of Reassigned Entries This value gives the current number of FREESQL*Net contexts which have been reassigned. Allthe physical connections of such a context are brokenbefore establishing new connections with differentprofiles.

Nb of Small Segments This indicates the current number of 64K segmentswhich are used by the ORACLE/TDS layer.

Nb of Large Segments This indicates the current number of large segmentswhich are used by the ORACLE/TDS layer.

Total Memory Used This indicates the current memory consumption, inKbytes, 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 allthe TPRs of your TDS application without re-precompiling, compiling and linkingyour application.

4.4.1 MAXOPENCURSORS With SETMXC

When connecting to the ORACLE server, the following algorithm is used to set thevalue of MAXOPENCURSORS to be associated with the physical connection:


4-18 47 A2 14UR Rev03

@LST@@NE@@@

MAXOPENCURSORS = MINIMUM { MAXOPENCURSORS (SETMXC), MAXOPENCURSORS (tpr), 500 (H_ORATDS limit) }

4.4.2 MAXOPENCURSORS Without SETMXC

If SETMXC is not used, MAXOPENCURSORS is set as follows:

@LST@@NE@@@

MAXOPENCURSORS = MINIMUM { MAXOPENCURSORS (tpr), 500 (H_ORATDS limit) }

4.4.3 Using SETMXC

To use SETMXC, define the following variables in the TPR:

@LST@@NE@@@

77 I-MAXOPCURS PIC S9(9) COMP-2.77 O-RTCD COMP-2.

To call SETMXC, use the COBOL CALL statement:

CALL "SETMXC" USING I-MAXOPCURS O-RTCD

Return codes are as follows:

@LST@@NE@@@

O-RTCD = 0 successful execution

O-RTCD = -1 ORACLE/TDS structures not initialized

O-RTCD = -2 invalid value - must be 0 through 500


47 A2 14UR Rev03 4-19

4.5 Getting Cursor Statistics Via The "Orastat" Entry Point

The ORACLE Communications Area (ORACA) is not supported in the TDSenvironment. In the H_ORATDS sharable module, there is an entry point"ORASTAT" which provides information about the cursor cache statistics. Thisinformation is usually recorded in the ORACA structure.

ORASTAT puts information into the ORACATDS structure described in themember ORACATDS_CBL which is delivered in the ORACLE SL library. Theinformation in ORACATDS is equivalent to that contained in the ORACLECommunications Area (ORACA). We can consider the ORACATDS structure tobe a subset of the standard ORACA.

ORACATDS provides information about the following:

• cursor cache statistics

• a program's use of ORACLE resources

4.5.1 The ORACATDS Structure Layout

The ORACATDS structure has the following layout:

@LST@@NE@@@

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.


4-20 47 A2 14UR Rev03

The meaning of the cursor cache statistics is as follows:

ORAHOC The maximum number of ORACLE cursors that canbe simultaneously opened. It represents the value ofthe MAXOPENCURSORS parameter that was takeninto account at connection time.

ORAMOC The maximum number of cursors requested during anORACLE session (associated with a physicalconnection). The value may be higher than ORAHOCif MAXOPENCURSORS was set too low, whichforced PCC to extend the cursor cache.

ORACOC The current number of used cursors.

ORANOR The number of cursor cache reassignments required bya TPR. The number should be kept as low as possible- it represents the amount of "thrashing" going on inthe cursor cache.

ORANPR The number of SQL statements parsed.

ORANEX The number of SQL statements executed. Keep theratio of this number to ORANPR as high as possible toavoid unnecessary reparsing.

4.5.2 Using ORASTAT

Make a call to ORASTAT from a TPR as follows:

@LST@@NE@@@

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

............................


47 A2 14UR Rev03 4-21

The SQLCA and ORACATDS structures must be declared outside the DeclareSection of the program.

To recap, SQLCA handles standard SQL communications; ORACATDS handlesORACLE/TDS communications.

If the TPR executes correctly, the fields in the ORACATDS structure areinitialized.

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 remainavailable for use - as we saw earlier in this section. In this case, when you callORASTAT after a CONNECT statement, the information in ORACATDS is stillthere from the previous execution(s). So information about the resources used bythe current TPR execution are obtained by taking the difference between the end-of-TPR statistics and the connection-time statistics.

If a TPR issues several connections, you can define an ORACATDS_CBL type filefor each connection. Each file declares a new ORACATDS type structure whichcan be passed as a parameter to ORASTAT. The name of the structure (the 01level) 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 thatidentifier. If (as is the default) there is no logical identifier at connection time, youjust need to move 0 to DBID-LG. The DBID-LG field is already initialized to 0 inthe delivered file ORACATDS_CBL.

For more on SQLCA and how to diagnose error conditions, refer to the standardORACLE precompiler documentation.


4-22 47 A2 14UR Rev03

q

47 A2 14UR Rev03 5-1

5. Optimizing ORACLE/TDS Applications

Optimization techniques can lead to significantly improved performance from anORACLE/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 performancefrom your TDS application. The size is specified by the CSIZE parameter whichwas introduced in Section 4.

Optimizing the value of CSIZE for a given TDS application involves counting thenumber of distinct database-id/database-name/user-id combinations which are usedin 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 commitmentunits

Of course, calculating the number of simultaneous active commitment units is notvery easy. Thus, to set the CSIZE, we defined several algorithms according to thetype of transaction (simple or complex). Various cases are dealt with in thissection.

Look at the following examples to compute DBUSRID.


5-2 47 A2 14UR Rev03

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

q

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

• TPRD connecting to database TDSO with user-id SYSTEM and database idDB1.

• TPRE connecting to database TDSO with user-id SYSTEM and database idDB2.

In this case, the number of distinct database-id/database-name/user-idcombinations is 4.

The combinations are:

DB1/ORAT/SCOTT

DB1/TDSO/SCOTT

DB1/TDSO/SYSTEM

DB2/TDSO/SYSTEM

q

Optimizing ORACLE/TDS Applications

47 A2 14UR Rev03 5-3

5.1.1 Sizing Simple Transactions

Here, we define a simple transaction as one where each conversation with a user'sterminal is preceded by a commitment. This is a very common occurrence. Itprevents a user from holding a resource for longer than necessary.

To calculate an optimal value for CSIZE in this case, we need only DBUSRID andthe 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 allconnect to ORACLE and commit ORACLE data within a single TPR without anyterminal conversation.

They all connect to ORACLE using a specific user-id; the simultaneity level of theTDS 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.

q

5.1.2 Sizing Complex Transactions

A complex transaction can be defined simply as one where a commit is notexecuted before each terminal conversation.

Since a commit has not been executed, the ORACLE context remains busy duringthe whole terminal conversation. This may take a rather long time, and this contextcannot be re-used by another user.


5-4 47 A2 14UR Rev03

Definition:

We define the think-time of terminal users as THINK.

Think-time is the total time elapsed in seconds between the time the CONNECTstatement is executed and the time the next COMMIT statement is executed for thesame database.

Definition:

We define the time interval which elapses between two executions of the sametransaction 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 averagethink-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 twoscreens containing fields which are filled by the terminal user.

The following takes place: the user enters the TDS transaction name T1. Thistriggers the execution of the first TPR TPR1 which connects to the ORACLEdatabase, 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 theORACLE database and sends back a second screen to the user's terminal. The userverifies the data, fills a validation field which takes 15 seconds, and pressesENTER again.

This in turn triggers the execution of a third TPR TPR3 which makes final updatesto the ORACLE database and commits.

The terminal user might then talk to a customer for 5 minutes before entering thetransaction name T1 again for the next operation.


47 A2 14UR Rev03 5-5

The number of terminals connected to the application is 100. Depending on thedata entered on the first screen, the TPR that connects to ORACLE may use 5different ORACLE user-id's.

The example gives us the following information:

THINK = 45 seconds (30 + 15)

INTER = 300 seconds (5 minutes)

USERS = 100

DBUSRID = 5

Therefore:

CSIZE = (5 * 100 * 45) / (300 + 45) (making 66)

q

5.1.3 Sizing Combined Simple and Complex Transactions

For a TDS application containing both simple and complex transactions, calculatethe optimal value of CSIZE separately for each type of transaction. Effectively,this means for each type of commitment unit, since a TDS transaction may containseveral commitment units.

First compute the optimal value for commitment units where no terminalconversation takes place between the connection to ORACLE and the nextcommitment. Use the method described above in Sizing Simple Transactions.

Then, compute the optimal value for commitment units where a terminalconversation does take place between the connection to ORACLE and the nextcommitment. 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 becausedistinct 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:


5-6 47 A2 14UR Rev03

The methods described here should provide a good estimate of the optimal CSIZEvalue for a given situation. As with all optimization techniques, however, you mayhave 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, itsvalue should be equal to 0.

5.2 Terminal Conversation

5.2.1 Committing Before Each Terminal Conversation

As we have seen above, the number of commitment units that are simultaneouslyactive determines both the number of ORACLE contexts to be managed, and thenumber 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, thenumber of ORACLE contexts and the number of ORACLE processes required inthe ORACLE database server do not depend on the total number of TDSapplication users.

5.2.2 Handling Cursors

You can use terminal conversation between each fetch execution to fetch from acursor. 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 isdetected.

WARNING:Do not commit between each fetch execution! This is because a commit woulddisconnect you from the database. A commitment is taken only when an end-offetch condition is reached. This frees the ORACLE context and makes itavailable to other users.


47 A2 14UR Rev03 5-7

EXAMPLE: Looping until end-of-fetch condition

The TPR "SELT1" loops on itself until an end-of-fetch condition is met:

@LST@@NE@@@


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.

q

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,


5-8 47 A2 14UR Rev03

the process in the ORACLE server remains unavailable to other users. Sincethere may be many terminal conversations, the server may be unavailable for along time.

You can avoid this situation by fetching all ROWIDs that correspond to theselection criteria within a single TPR, and then by immediately logicallydisconnecting. This frees the ORACLE context. The ROWIDs are saved inTRANSACTION-STORAGE. Then, once the TPR has been reconnected toORACLE, fetch one row, and commit for each terminal conversation. Thisenables the multiplexing of many users on the same ORACLE context. (For anexample, see the FETCH transaction in Appendix E.) However, the FETCHedROWIDs are not locked so you may get inconsistent results if another usermodifies 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 (orprofiles) 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 TDStransaction for each user.

The number of ORACLE contexts to be cached, and the number of ORACLEprocesses are directly proportional to the number of different ORACLE user-id'sused in the TDS application.

5.4 Optimizing Connect Statements

5.4.1 Local Connection

If the ORACLE/TDS application has to connect to a database server running on thesame machine, for performance reasons, be sure to use the fully optimized localconnection.

The general format of a CONNECT issued from an ORACLE/TDS application isthe following:

EXEC SQL CONNECT :USR IDENTIFIED BY :PWD AT DB1 [ USING :HST ]

An optimized local connection is established depending on two conditions:


47 A2 14UR Rev03 5-9

• 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 performancewill be less.

Moreover, when multiple ORACLE databases are accessed by the same TPR, (or ifthe same database is connected more than once using several different user-ids),

5.4.2 Cache Processing

CONNECT statements must all be executed at the beginning of the TPR.

To optimize the SQL*Net context cache processing, the first CONNECTstatements to be executed should be those that connect to the least used databases.Efficient cache management means multiplexing the maximum number of userswhile 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 thefollowing way (always using the same user-id):

• TPR1 connects to database B1 and database B2.


To optimize the cache processing, TPR1 must connect to B2 first, beforeconnecting to B1. In the same way, TPR2 must connect to B3 first, beforeconnecting to B1.

This is because when the first CONNECT is requested, the cache manager tries tochoose 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 canchoose a context that contains a connection to B1 and B2, or to B1 and B3. But itcannot 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 B3will be necessary for TPR2, just as a physical disconnection of B3 and a physicalconnection of B2 will be necessary for TPR1.

To optimize performance and to enable the cache manager to choose the correctORACLE context, TPR1 must connect the B2 database first, and TPR2 mustconnect the B3 database first.


5-10 47 A2 14UR Rev03

q

EXAMPLE 2: Optimizing Cache Processing

Suppose now that we have the following TPRs in our TDS application:


• TPR2 connects to database B2 only.

When the cache manager chooses a context for TPR2, it may choose one whichwas 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 beforeTPR2 is processed. Accordingly, this has a negative effect on TPR2 execution timebecause a physical disconnection consumes more resources than a logical one. Thesame applies to TPR1 which has to physically connect to B1 if it reuses thiscontext.

To optimize performance in this case, add a superfluous connect to the B1 databasein TPR2. This will avoid needless disconnections and connections.

q

5.5 GENERAL Oracle Optimization TECHNIQUES

Certain optimization techniques can be applied more generally to ORACLE itself.They are discussed below.

5.5.1 Saving CPU Time - Use of Cursors

The OPEN_CURSORS parameter of INIT.ORA file gives the maximum number ofsimultaneous cursors allowed per ORACLE USER PROCESS (dedicated serverprocess). This value can be reduced (but not increased) for each relevantapplication with the use of the MAXOPENCURSORS parameter of the PCCprecompiler.

@TBL@@NE@@@

OPEN_CURSORS MAXOPENCURSORS for TDSDefault value 50 250Maximum value unlimited 500


47 A2 14UR Rev03 5-11

These 2 parameters must respect the following rule:

OPEN_CURSORS >= MAXOPENCURSORS + 6

So, the OPEN_CURSORS value must be adjusted, depending on the highest valueof MAXOPENCURSORS.

Advice for the MAXOPENCURSORS value:

Do not forget to specify a high enough value for the MAXOPENCURSORSparameter. This will save a significant amount of CPU time. TheMAXOPENCURSORS parameter limits the maximum number of cursors whichcan be simultaneously open for an ORACLE user.

In the TDS environment, the MAXOPENCURSORS associated with a connectionis 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/shemust 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 JORof your TDS application. Try to keep the ratio "Nb of Cursor Reassign" to "Nb ofStmt executions" as low as possible to get the best performance.

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

5.5.3 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 ServerApplication Developer's Guide for tips on how to tune the ORACLE databaseserver itself finely.


5-12 47 A2 14UR Rev03

5.5.4 Using Several Distinct ORACLE Databases

If a TDS application handles varied information, store the data in several distinctORACLE databases. This is especially useful if the data is updated very frequentlybecause it avoids reaching the limits of the ORACLE journalizing mechanism.

Using different ORACLE databases is possible only if data from differentdatabases is never updated in the same commitment unit. For example, you mayhave one database containing personnel records, and another for customerinformation. In such cases, updating is logically separate.

47 A2 14UR Rev03 6-1

6. ORACLE/TDS Rules and Restrictions

This section deals with the current limits and restrictions imposed byORACLE/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 ofthe application.

For applications where no terminal conversation takes place between eachCONNECT to ORACLE and the next commitment, the limit is the standard TDSlimit.

For other types of application, the limit is generally governed by the resourcesneeded by the ORACLE database servers to execute efficiently. Such resourcesare: number of processes, main memory, CPU time.


6-2 47 A2 14UR Rev03

6.2 ORACLE Processes

An ORACLE database needs a number of user processes that roughly equals theoptimal value of the CSIZE parameter (discussed at length in earlier sections).

The optimal value for CSIZE will indicate whether the "processes" resource iscritical for your ORACLE/TDS application or not.

The maximum number of processes depends on the limits imposed by theparticular version of GCOS 7 under which ORACLE is running. Refer to theSystem Installation Configuration and Updating Guide for specific information onyour system.

6.3 Updating Ufas OR IDS/II Databases With Oracle Databases

6.3.1 Separate Commitment Units

Dual updates (that is, updating UFAS or IDS/II data, and ORACLE data) must bedone in separate commitment units.

If dual updates take place in the same commitment unit, and an error takes placeduring the commit phase of TDS, it is possible that the ORACLE data has beencommitted but the UFAS or IDS/II data has not.

You can detect this situation by testing SQLCODE. If SQLCODE = -5 on the firstattempted CONNECT statement of the commitment unit, it indicates that it is aredo of the commitment unit and that ORACLE data has been committed. SeeAppendix 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 intoTRANSACTION-STORAGE.

• Update the ORACLE data in the next commitment unit.

6.3.2 Data Consistency

There is no data consistency problem if either ORACLE data or UFAS and IDS/IIdata is updated within the same commitment unit.

ORACLE/TDS Rules and Restrictions

47 A2 14UR Rev03 6-3

Therefore, if an ORACLE database is updated, any other UFAS file or IDS/IIdatabase can also be read in the same commitment unit.

Similarly, if a UFAS file or IDS/II database is updated, any ORACLE database canalso be read in the same commitment unit.

Deadlocks, however, provide a potential problem. They will be detected by thetime-out mechanism only. See "DEADLOCKS" below.

6.4 Deadlocks

Deadlocks involving UFAS or IDS/II data and ORACLE data are currentlydetected only by a time-out mechanism. Such deadlocks are to be avoided becausethey adversely affect the global performance of ORACLE/TDS applications.

Reduce the risk of such deadlocks by accessing UFAS or IDS/II data first in eachcommitment unit. If the ORACLE data is accessed after UFAS and IDS/II, thedeadlock (as described above) cannot occur.

6.4.1 Avoiding Deadlocks - Example

EXAMPLE 1: Avoiding deadlocks between UFAS or IDS/II data and ORACLEdata:

q

@LST@@NE@@@

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 anotheruser who is waiting for a UFAS or IDS/II lock. This is because, in both TPRA andTPRB, the UFAS and IDS/II data is updated first, then the ORACLE data isupdated.


6-4 47 A2 14UR Rev03

Deadlocks may occur, however, if the TPRs are coded in different ways. SeeExample 2 below.

6.4.2 Creating Deadlocks - Example

EXAMPLE 2: Creating a deadlock situation

q

@LST@@NE@@@

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 thelock on record B. But the lock on record B is already held by a user executingTPRA who is himself waiting for the lock on tuple T. The problem arises becausethe UFAS and IDS/II data is updated first in TPRA, and the ORACLE data isupdated first in TPRB.

Avoid this problem by using the same updating pattern in all commitment units:

Either:

@LST@@NE@@@...Update data in UFAS,IDS/II database...Update data in ORACLE database...Commit

Or:

@LST@@NE@@@


47 A2 14UR Rev03 6-5

...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 andIDS/II updates.

6.5.1 Updating Data in Controlled Common-Storage

To prevent deadlocks, updates to data in controlled common-storage should becarried out within a commitment unit where no update of ORACLE data takesplace.

If you are updating data in an ORACLE database and data in controlled common-storage in the same commitment unit, the same problem occurs as with dualupdating of UFAS, IDS/II data and ORACLE data (see above).

If an error occurs during the commit phase of TDS, the commitment unit isautomatically restarted. However, the ORACLE data may already have beencommitted. If so, SQLCODE is set to -5 on the first CONNECT statement. SeeAppendix A.

To avoid this, commit controlled common-storage first, and save all the dataneeded to perform ORACLE database updates in the next commitment unit.

6.5.2 Reading Data in Controlled Common-Storage

If ORACLE data is only read in a commitment unit, ORACLE does not take anylocks. In this case, controlled common-storage can be accessed at any time andthere is no consistency problem at all.

When controlled common-storage is only read, there is no consistency problem butthe risk of deadlock remains because locks are always acquired to access controlledcommon-storage.


6-6 47 A2 14UR Rev03

6.5.3 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 theORACLE/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 thedesired features.

Note that:

• values given in the INIT_ENV file are valid for the whole TDS (alltransactions),

• when the INIT_ENV file is missing, the default America/American environmentis 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. Thesame restrictions as for controlled common-storage apply to the spawn function.

Avoid updating ORACLE data in a commitment unit where the spawn function isused. This avoids deadlocks and problems of data consistency.

In cases where updating of ORACLE data is definitely required, it should becarried out in the next commitment unit. The necessary data must be stored inTRANSACTION-STORAGE in the current commitment unit.

If ORACLE data is only read in a commitment unit, the spawn function can beactivated at any time.


47 A2 14UR Rev03 6-7

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 sameproblems of deadlocks and data consistency can occur.

The internal open mechanism is not spawned; the open is done when thecommitment is taken.

You can, however, read ORACLE data without any problem inside a commitmentunit where GCOS 7 files are opened or closed.

6.10 Iqs

You cannot use IQS query programs in a transaction that accesses an ORACLEdatabase; IQS/TDS and ORACLE/TDS cannot coexist in the same transaction.

6.11 Roll Forward

If a media fails, the roll forward operation for the ORACLE database remainsmanual.

The user must ensure consistency between the ORACLE database and theinformation managed by the TDS application. No checking is done to verify thatthe state of an ORACLE database which has been restored is consistent with thestate of the data in the TDS application.


6-8 47 A2 14UR Rev03

q

47 A2 14UR Rev03 7-1

7. ORACLE7/TDS-XA

7.1 Overview

A TDS-XA is a transactional application where some transactions call on servicesoffered 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/IIdatabases, and UFAS files simultaneously. The CU can also simultaneously updateseveral ORACLE databases.

This means that all updates done within the TX (on UFAS files, IDS/II databasesand ORACLE7 databases) will all be committed or rolled back at the end of theCU, under the control of TDS-XA.

The ORACLE databases can be either local or remote, and on either a GCOS 7 siteor a UNIX site.

Figure 7-1 shows how TDS-XA/ORACLE fits in with the DTP model. ORACLE7Resource Managers (RMs) only are shown here.

@GRP@@NE@TDS-XA/ORACLE in the DTP Model@Fig. 0-1@


7-2 47 A2 14UR Rev03

TDS

TDS-XA ORACLE7/TDS-XA

ORACLE7/TDS

XA

RMsTM

ORACLE7

AP

TPRsPro*COBOL or Pro*C statements

Figure 7-1. TDS-XA/ORACLE in the DTP Model

TDS-XA, ORACLE7/TDS-XA, AND ALL THE ORACLE7 XA RMs areinvolved in a two-phase commitment protocol where TDS-XA andORACLE7/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 isdivided into branches corresponding to the RMs.

7.1.1 Environment

ORACLE7/TDS-XA requires GCOS 7-V7 minimum TS 7458.

Since ORACLE7/TDS has a client/server architecture, if the ORACLE7 server partis located on a GCOS 7 system, the MI "Distributed" must be installed. There is noparticular constraint if only the client part is installed on GCOS 7.

ORACLE7/TDS-XA

47 A2 14UR Rev03 7-3

7.2 Operation

7.2.1 Heuristic Decisions

Some RMs may employ heuristic decision-making: an ORACLE7 databaseadministrator may decide to commit or rollback the work of a prepared transactionbranch independently of the TM in order to unlock shared resources. This mayleave the RM in an inconsistent state in which case, when TDS-XA tells theORACLE7 database to complete the branch, it will reply that it has already doneso. The ORACLE7 database must retain this information even if it matches theTM's decision so that the TM can call it again to authorize it to forget the branch.

7.2.2 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 toensure data integrity across the distributed system.

Modifications via the ORACLE7 Resource Managers are validated at thecommitment points defined (implicitly or explicitly) by the TPRs, at the same timeas for UFAS or IDS/II databases and committable TDS services.

Each time a CU becomes desynchronized, TDS-XA automatically starts thereporting transaction H_XAEVT (see below, The H_XAEVT Special Transaction)to help the user solve the problem. After resynchronization, it starts the transactionagain to give a final report for the CU.

A full description of this special transaction is given later in this Section and anexample of resynchronization after detection of an error is given in Appendix I.

7.2.3 TDS Restart

At TDS warm restart, resynchronization with XA RMs is performed for each CUof the previous TDS session that is still active for XA.

7.3 User Interface

Users concerned by TDS-XA/ORACLE are:


7-4 47 A2 14UR Rev03

• the TDS administrator responsible for the generation step and for monitoring theTDS application,

• the GCOS 7 system administrator and the ORACLE database administrator whoare responsible for data consistency,

• the TDS programmer who is responsible for programming transactions that arecommitted with XA.

7.3.1 TDS Generation and Application Monitoring

7.3.1.1 TDS Generation

TDS Section

The XA-RESYNC-DELAY clause specifies the time between tworesynchronization 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 torequest 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$ viewon all databases accessed.

ORACLE7/TDS-XA

47 A2 14UR Rev03 7-5

7.3.1.2 Application Monitoring

The master commands specific to XA are documented in the TDS Administrator'sGuide.

7.3.2 Server Configuration

Make sure that the V$XATRANS$ view exists on all ORACLE7 databases. Youcan create the view by running the SQL script xaview_sql. Execute this SQL scriptunder the ORACLE server user sys.

The select privilege on V$XATRANS$ must be given to all ORACLE7/TDS-XAusers, including the XA user/password given in the TDS generation.

For more details, see the ORACLE RDBMS Administrator's Guide. ORACLEdocumentation is listed in the ORACLE7 Documentation Catalog.

7.3.3 TPR Programming

7.3.3.1 CONNECT Statement and ORACLE7/TDS Cache Manager

The ORACLE7/TDS Cache Manager is designed to multiplex the users of anORACLE7 application on a small number of ORACLE processes. A "logicalconnection" is defined for each CONNECT statement with a given profile (user,password, (AT)DBn, host). This connection is mapped on a physical connection tothe ORACLE process which was established at the time of the first CONNECTwith the given profile. The physical connection is not stopped until TDS stops oruntil the ORACLE7 administrator requests that it be stopped through the ORACLEtransaction. Each commitment unit is represented by a CACHE entry, and allconnections within this CU are represented by CONNECTION entries chained onthe CACHE entry.

The connection cache contains all physical connections that are active on allORACLE databases being accessed by TDS as follows:

• The XA connections are represented by XA CONNECTION entries chained onan XA CACHE entry which in turn represents an XA commitment unit (thetransaction 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 cannotbe reused for an XA connection even of the connection profile is the same.


7-6 47 A2 14UR Rev03

Therefore the CISIZE parameter representing the CACHE size must be consideredas having one part for the XA entries and another part for the non-XA entries. Thecache size has a great impact on performance, so bear this factor in mind whendimensioning 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 ina 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 tracelevel 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 TDSProgrammer's Guide for full syntax of the TDS trace commands.

7.3.3.2 Using Precompilers with ORACLE XA

When used in an ORACLE XA application, cursors are valid only for the durationof the transaction. Therefore, you must open explicit cursors after the transactionbegins and close them before the commit or rollback.

You must use the option release-cursor=yes when compiling your precompilerapplication.

7.3.3.3 SQL-Based Restrictions

The following restrictions apply due to SQL constraints:

• Rollbacks and Commits: Because the Transaction Manager is responsible forcoordinating and managing the progress of the transaction, the application mustnot contain any ORACLE server-specific statement that would independentlyroll back or commit a transaction:

ORACLE7/TDS-XA

47 A2 14UR Rev03 7-7

− do not use EXEC SQL ROLLBACK WORK for precompiler applications.Either arrange for the transaction to be rolled back by the initiator or callINVCMIT,

− do not use the EXEC SQL COMMIT WORK statement in a precompilerapplication. Use DFCMIT instead to end a transaction.

• DDL Statements: Because a DDL statement such as CREATE TABLE impliesan implicit commit, the ORACLE XA application cannot execute any SQL DDLstatements.

• Savepoint: Do not use savepoint. For example, do not use EXEC SQLSAVEPOINT <savepointname>.

• Read Only Transactions: Do not use read only transactions. For example, donot 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 SQLROLLBACK WORK RELEASE.

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

7.3.3.5 The H_XAEVT Special Transaction

To handle situations of data consistency, you are strongly advised to rewrite theH_XAEVT special transaction using the ORACLE7/TDS-XA procedureH_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 RMsbeing accessed by a given CU, together with the state of this CU in relation to theRMs accessed.

The call to H_OR_XARMSOFCU must occur in the first TPR of the H_XAEVTtransaction.

Format:


7-8 47 A2 14UR Rev03

H_OR_XARMSOFCU (RMLIST_PTR, RMNB)

Parameters:

RMLIST_PTR is an input parameter that provides a pointer to an areathat will be filled by ORACLE/TDS-XA with RMNBentries, one for each RM accessed during the currencyof this CU. The area is allocated by the caller (a TPRin C or COBOL) and is sized for a maximum of eightentries 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 lastcommit for this RM

RMNB is an output parameter receiving the effective numberof RMs accessed during the currency of the CU andcorresponding to the number of entries in the arraypointed by RMLIST_PTR.

The troubleshooting of distributed transaction problems is then handled as follows:

• when XA_STATUS is not done, XA_RMIDENT identifies the desynchronizedRM,

• the database manager checks the RM and verifies the status of the transactionindicated by XA_GBLFORID in the DBA_2PC_PENDING table,

• he takes a heuristic decision or arranges for the communication link to berestored, then waits for completion of resynchronization.

For a full description of the H_XAEVT transaction, see the appropriate TDSProgrammer'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 isSYNCPOINT and the PPC Syncpoint Manager is the commit coordinator relativeto the TDS application, rather than TDS itself. The Syncpoint orders aretransmitted to ORACLE7/TDS through the TDS Commit Manager thus providingXCP2 and XA compatibility.

ORACLE7/TDS-XA

47 A2 14UR Rev03 7-9

NOTE: If an inconsistency results from a heuristic decision on the part of an XAResource 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 knownbeyond two XCP2 nodes.


7-10 47 A2 14UR Rev03

q

47 A2 14UR Rev03 8-1

8. Writing Pro*C TPRs for TDS

This section describes how to write TPRs containing SQL statements. It discussesthe differences applicable to use of C language as opposed to use of COBOL asdealt with in section 2.

It is assumed that programmers are already familiar with TDS C and with SQL. Ifnecessary, refer to the TDS C Programmer's Guide and the ORACLE7 Server SQLLanguage Reference Manual. In addition, those who are not already used towriting Pro*COBOL programs for use under IOF must refer to the specificProgrammatic 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 thenormal process of TPR preparation.

8.2 Programming Rules

8.2.1 Connecting to ORACLE

The language used in the TPR has no impact on the aspects of SQL*Net contextcache management such as physical and logical connection, SQL*Net cache entrystates, etc. Note that if two TPRs, one written in C and the other in COBOL, usethe same physical connection profile, they could share the same SQL*Net context


8-2 47 A2 14UR Rev03

since the physical connection is not identified using the language of the TPR. SeePhysical Connection Definition in section 2.

8.2.2 Commitments

The rules relating to commitment described in section 2 for TPRs in COBOL applyequally to TPRs written in C language..

Use the call h_dfcmit() in place of CALL "DFCMIT".

8.2.3 Rollback

The rules relating to rollback described in section 2 for TPRs in COBOL applyequally to TPRs written in C language..

Use the calls h_rollback(), h_invcmit, and h_nocmit respectively inplace of CALL "ROLL-BACK", CALL "INVCMIT", and CALL "NOCMIT".

8.2.4 Data Definition Statements

The usual rules apply as for DDL/DCL statements.

8.2.5 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 entrypoint is done as follows:

@LST@@NE@@@

extern void getstm();char mess_buf{70};int buff_size;int mess_lgt;buff_size=70;getstm (&mess_buf, &buff_size, &mess_lgt);

Writing Pro*C TPRs for TDS

47 A2 14UR Rev03 8-3

8.3 Precompiling, Compiling, And Linking

8.3.1 Precompiling

To precompile a Pro*C TPR, use PCC with the HOST parameter set the value C.

EXAMPLE:

q

PCC INAME = MYDIR.SL..MYTPR HOST = C;

Successful precompilation produces an output source file named MYTPR_PCC inthe library MYDIR_SL.

8.3.2 Compiling

The file MYTPR_PCC in the library MYDIR_SL must then be compiled by the Ccompiler. 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 optionsthat are mandatory in this context.

8.3.3 Linking

The linkage phase is identical to that used for a COBOL TPR. See Linking aPro*COBOL TPR in section 2 and the TDS C Language Programmer's Guide.

8.4 Other C Language Variations

8.4.1 Setting Configuration Parameters Dynamically

The source programs required to implement the ORACLE, CASTAT, andTCLEAN transactions are delivered only in their COBOL version.

To make a call to the SETMXC entry point, use the following form:


8-4 47 A2 14UR Rev03

@LST@@NE@@@

extern void SETMXC();int i-maxopcurs, o-rtcd;i-maxopcurs = ...;SETMXC (i-maxopcurs, o-rtcd);

8.4.2 Obtaining Cursor Statistics via the orastat Entry Point

Declare the oracatds structure by using the ORACATDS-C member which isdelivered in the ORACLE SL library.

To make a call to orastat from a TPR, use the following form:

@LST@@NE@@@

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);

47 A2 14UR Rev03 A-1

A. SQLCODE Error Conditions

Error conditions may occur when a Pro*COBOL statement is executed. Anegative error code (between -1 and -27) is placed in the SQLCODE field. Youmust test SQLCODE correctly in the TPR.

Most error conditions cannot cause data inconsistency between ORACLE data andTPR 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 beendeferred (for example, because of multiple database updates), you must save allcritical 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 asecure location. For example, it can be moved into TRANSACTION-STORAGEby the previous commitment unit.

The values of SQLCODE specific to ORACLE/TDS are listed on the followingpages, 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 theORACLE/TDS layer and the code generated by the Pro*COBOL precompiler.

No error message is associated with this code.

Action:


A-2 47 A2 14UR Rev03

None.

A.2 Sqlcode = -2

"ORAT-2: Connect failed: communications server not ready."

Cause:

The CONNECT statement has failed because communication with the ORACLEcommunications server has not yet been established by your TDS application.

Action:

Abort the current transaction. Your TDS administrator is responsible for dealingwith this problem. He has to check that the ORACLE communications server hasbeen 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 "ORACLEENABLE" transaction to enable communication between COR and your TDSapplication.

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:

SQLCODE Error Conditions

47 A2 14UR Rev03 A-3

ORACLE cannot work with this TDS application because the necessaryinitializations have not been done.

Action:

Check that one of the allowed "USE ORACLE" options has been specified in theTDS Generation Program which produced the run-time TDS Load Module. Checkalso 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; theSQL*Net connection was lost just after the commit request was sent to theORACLE server so the acknowledgement was not received. When TDS restartedthe commitment unit and was able to reconnect to the ORACLE server, it wasdetected that the ORACLE server could finally commit. However, thecommitment 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 executionof 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 ORACLEserver in time. The status of the ORACLE data updated by the currentcommitment unit is unknown.


A-4 47 A2 14UR Rev03

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 beaborted because the ORACLE server is no longer available. It is not thereforepossible 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 becauseORACLE did either commit or roll back, but you must check by other meanswhether ORACLE has committed or not. Save the necessary information in asecure 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 beeninterrupted 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 thephysical connection is broken. The commitment unit will be restarted by TDS anda SELECT statement on the SYS$TDS table will be executed to see the state of theORACLE commitment.

On the first CONNECT statement, one of the following SQLCODE will bereturned 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 andMAXTIM parameters, then try to re-execute your transaction.


47 A2 14UR Rev03 A-5

A.8 Sqlcode = -8

"ORAT-8: ORACLE connections disabled."

Cause:

Connections with ORACLE databases from the TDS application have beendisabled through the execution of the "ORACLE" transaction, or have not yet beenenabled.

Action:

Abort the current transaction.

Contact your TDS administrator who has probably decided to stop ORACLE/TDSconnections 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:


Action:


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 anORACLE server has failed.


A-6 47 A2 14UR Rev03


Action:


A.11 Sqlcode = -11

"ORAT-11: Strong disconnection of communications server."

Cause:

The ORACLE communications server has suddenly been made unavailable; forexample it has been killed.

Action:

Abort the current transaction. Restart the ORACLE communications server usingthe 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 errormessage 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 ####.",


47 A2 14UR Rev03 A-7

activate this database server by using the SOR and SQLDBA commands, or waitfor 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 Acommand.

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.3of the precompilers and Pro*COBOL programs precompiled with version 1.5 ofthe precompilers. Such a mix is not supported.

Action:

Make your precompilations uniform (by precompiling with the same version of theprecompilers, then re-compiling, and re-linking). Then, restart your TDSapplication.

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-timehas failed.

Action:



A-8 47 A2 14UR Rev03

A.15 Sqlcode = -15

"ORAT-15: No connected database."

Cause:

An SQL statement (other than CONNECT) has been executed while no ORACLEdatabase was connected.

Action:

Check your application program. Remember that each commit disconnects fromall connected databases. Verify that your program or another program did asuccessful 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 beingconnected to the target database.

Action:

Check your application program. Remember that each commit disconnects fromall connected databases. Verify that your program or another program did asuccessful 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 iscurrently not allowed.


47 A2 14UR Rev03 A-9

Action:

Remove one of the COMMIT statements, and commit this database in a subsequentTPR.

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 theHOST parameter.

This error message can be returned, only if you precompile your COBOL programwith version 1.3 of the Pro*COBOL precompiler (delivered with ORACLE V6).

Action:

Re-precompile your COBOL program with the Pro*COBOL precompiler deliveredwith ORACLE7 (version 1.5). Re-compile it, re-link it and re-load your TPRsharable module.

A.19 Sqlcode = -19

"ORAT-19: Internal error: inconsistency in ORACLE/TDS data."

Cause:


Action:


A.20 Sqlcode = -20

"ORAT-20: Database logical name already used"


A-10 47 A2 14UR Rev03

Cause:

A CONNECT statement has failed because the logical name has already been usedfor a previous connection in the current commitment unit.

Action:

Avoid requesting several connections in a single commitment unit which uses thesame 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 TDSenvironment.

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 errorswill probably be logged.



47 A2 14UR Rev03 A-11

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 commitprotocol between TDS and ORACLE, or during the commit of the ORACLEdatabase.

As this error appears at TPR ending, outside the scope of the user's program, itcannot be notified synchronously. So the CU is rolled back, silently restarted, andthe error is returned to the user's program on the first CONNECT statement of thecommitment unit.

Action:

Look at the error code in the message and refer to the "Error Messages and CodesManual" documentation. If the code is a negative one, refer to the suitable codedescription in this chapter.

For example, if the code is 942, check existence of the SYS$TDS table in thedatabase 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:


A.25 Sqlcode = - 25

"ORAT-25: Invalid host variable definition"


A-12 47 A2 14UR Rev03

Cause:

A connect statement has failed because at least one of the CONNECT parametersis 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.


Action:


A.27 Sqlcode = - 27

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

Cause:

The number of distinct database identifiers used in the application program isbeyond the authorized limit which is fixed at 12 for non-XA applications and at 8for XA applications.

Action:

Check your application program.


47 A2 14UR Rev03 A-13

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, ResourceManager not available, etc.

Action:

Check the connection parameters and availability of RMs. If ORACLE trace andTPR 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.


A-14 47 A2 14UR Rev03

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 yourcustomer support representative.

47 A2 14UR Rev03 B-1

B. Sample COPY Files

The following source files are referenced in the examples contained in the otherAppendices of this manual. They are included in TPRs by using the COBOLCOPY 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 directoryname of your ORACLE installation.

CONSTANT-STORAGE

@LST@@NE@@@

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 * BLINK11 02 BLK PIC X.12 * BELL13 02 BEL PIC X.14 * END OF MEDIUM15 02 EM PIC X.16 * FORWARD SPACE17 02 FS PIC X.

TDS-STORAGE


B-2 47 A2 14UR Rev03

@LST@@NE@@@

1 01 TDS-STORAGE. 2 02 SYMBOLIC-QUEUE PIC X(12). 3 02 PRIOR-TPR PIC X(12). 4 02 CURRENT-TPR PIC X(12). 5 02 NEXT-TPR PIC X(12). 6 02 ON-ABORT-TPR PIC X(12). 7 02 ABORT-CODE COMP-1. 8 02 USER-ID PIC X(8). 9 02 TX-MODE PIC 9.10 02 RESTART-STATUS PIC 9.11 02 TRANSACTION-SERIAL-NUMBER COMP-2.12 02 TPR-SERIAL-NUMBER COMP-1.13 02 WAIT-TIME COMP-1.14 02 ABORT-ICC PIC X(8).15 02 RESTART-CODE PIC X(1).16 02 USER-FULLNAME PIC X(12).17 02 NO-RESTART PIC X(1).18 02 REST-CVSTAT PIC X(1).

COMMUNIC-SECTION

@LST@@NE@@@

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 OUTPUT110 DESTINATION COUNT IS COUNT-OUT120 TEXT LENGTH IS LENGTH-OUT130 STATUS KEY IS STATUS-OUT140 ERROR KEY IS ERROR-OUT150 SYMBOLIC DESTINATION IS DEST-OUT.

47 A2 14UR Rev03 C-1

C. The TDSTCLEAN Transaction

C.1 Purpose

A cleaning mechanism has been implemented to automatically clean theORACLE/TDS cache. This mechanism is activated through a new Transaction,named TDSTCLEAN.

The cleaning mechanism consists in physically disconnecting all ORACLEsessions associated with every FREE SQL*Net context in the cache. When thecontinuous inactive time of a SQL*Net context exceeds a value defined by theTDS and Database administrator (IDLET), the cleaning mechanism disconnects it.The cleaning mechanism scans the cache periodically (every SPWNT seconds) tofind inactive contexts.

C.2 Transaction Description

The "TDSTCLEAN" transaction is associated with the TCLEAN_COBOLprogram, which is delivered with your ORACLE7 version. This programimplements the call to an entry point, named TCLEANANAL, in the H_ORATDSsharable module. This entry point analyzes the parameter string and starts thedisconnection mechanism (if parameters are valid). It spawns a second TCLEANtransaction, that effectively scans the cache every SPWNT seconds in order tosuppress all FREE SQL*Net contexts which have been inactive for more thanIDLET seconds.

This spawned transaction is a multi-TPR transaction that passes from one TPR tothe NEXT one every SPWT seconds, until the mechanism is deactivated.

The code for the spawning transaction and for the spawned transaction (first TPRand NEXT-TPRs) are both located in the TCLEAN_COBOL program.


C-2 47 A2 14UR Rev03

C.3 How To Use

To use TDSTCLEAN, assign the "TCLEAN" message to the ORATDS linkage unitin the TDS Generation Program. Add the following lines to the TRANSACTIONSECTION of the STDS member:

MESSAGE "TCLEAN" ASSIGN TO TDSTCLEAN AUTHORITY-CODES ARE 0,1. *END

The TDSTCLEAN transaction has several parameters for launching the TCLEANmechanism. These parameters may be divided into two categories: IDENTs andKEYWORDs.

IDENTs

IDENTs are used to update TSPWNN and TIDLE values in the TDSSEG. Thesyntax 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.

The TDSTCLEAN Transaction

47 A2 14UR Rev03 C-3

• 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, themechanism will not start unless both IDENTs are set. For details, see thedescription of SPWNT and IDLET below. However if an error is detected forone of the two IDENTs, neither of them is taken into account.

You are recommended to issue a "TCLEAN DISPLAY" command before anyaction on TCLEAN mechanism. In fact, this mechanism has a big impact onyour 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 aprevious activation). This IDLET may not be the one you want to use, so it isimportant 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 themare displayed upon terminal.

C.3.1.1 The SPWNT Parameter

The SPWNT parameter specifies the interval (in seconds) between two TPRs of thespawned transaction.


When the TCLEAN mechanism is not initiated, you must set SPWNT as well asIDLET to launch it.

The value of SPWNT will be used at the end of the TPR. It is put in WAIT-TIMEwhich corresponds to the time the transaction will wait for before moving on toNEXT-TPR.

There is no default value for SPWNT. You must give an explicit value to launchthe disconnection mechanism.


C-4 47 A2 14UR Rev03

The minimum value is 0. You may use 0 if the TCLEAN mechanism is active andyou want to stop it without changing the IDLET value. This is useful if you wantto stop the disconnection for a while but you know you will start it again in thesame conditions. In this case, do not use "TCLEAN STOP" but TCLEANSPWNT=0".

The maximum value is 60000 seconds.

If you try to set SPWNT value without having given a value for IDLET, you willget:

**************************************************************** TCLEAN mechanism **-------------------------------------------------------------** No value for IDLET; mechanism won't start ****************************************************************

If you set valid values for IDLET and SPWNT, the TCLEAN mechanism will beactivated 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 themechanism is active, you will get:

**************************************************************** TCLEAN mechanism **-------------------------------------------------------------** Parameters updated ***************************************************************** SPWNT = ** IDLET = ****************************************************************


47 A2 14UR Rev03 C-5

If you want to stop the mechanism by "TCLEAN SPWNT= 0", you will get:

**************************************************************** TCLEAN mechanism **-------------------------------------------------------------** TCLEAN mechanism will be stopped ****************************************************************

C.3.1.2 The IDLET Parameter

The IDLET parameter specifies the maximum time in seconds during which anORACLE session may be inactive if the TCLEAN mechanism is initiated. If anSQL*Net context is inactive for more than IDLET seconds at cache scanning time(every SPWNT seconds), all connections entries linked to this SQL*Net contextare suppressed.


There is no default value for IDLET. You must give an explicit value to launch thedisconnection 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 "TCLEANDISPLAY") and the TCLEAN mechanism will not be able to start until you specifya non-zero value. This is an implementation choice to make you choose theIDLET value when you launch TCLEAN mechanism.

The maximum value is 60000 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 themechanism is active, you will get:


C-6 47 A2 14UR Rev03

**************************************************************** TCLEAN mechanism **-------------------------------------------------------------** Parameters updated ***************************************************************** SPWNT = ** IDLET = ****************************************************************

In that case, you must be aware of the fact that this new value for IDLET will notbe taken into account immediately, but at the next execution of the TPR of thespawned transaction. This is possibly as much as SPWNT seconds later. Duringthis gap, the maximum time of inactivity for FREE entries remains the old value ofIDLET.

C.3.2 Description of "TCLEAN" transaction KEYWORDs

C.3.2.1 "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 *


47 A2 14UR Rev03 C-7

**************************************************************** SPWNT = ** IDLET = ****************************************************************

This command should be issued before any action on TCLEAN mechanism.

C.3.2.2 "TCLEAN STOP"

This command permits you to stop the TCLEAN mechanism by resetting SPWNTto 0. IDLET is also reset to 0, so that next activation cannot be effected withouthaving 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 ****************************************************************


C-8 47 A2 14UR Rev03

q

47 A2 14UR Rev03 D-1

D. The SAMPLE Transaction

In the source library delivered with an ORACLE kit, there are two demonstrationprograms 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 SAMPLEtransaction 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 validparameters 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 isrequested.If an error is detected (invalid dept, ...), the transaction also terminates.

A connect is done after the information needed to perform database updates hasbeen obtained from the user. A commit is executed after every successful insertion.


D-2 47 A2 14UR Rev03

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, theSQL*Net context cache manager retrieves the context allocated for thecommitment, retrieves an active connection with the same profile and thus skipsthe connection processing.

In the statements shown in the rest of this Appendix, some lines were too long to fitin this manual. These lines have either been folded or have had some spacessuppressed.

001 IDENTIFICATION DIVISION.002 *003 PROGRAM-ID. SAMPLE.004 *005 ENVIRONMENT DIVISION.006 *007 CONFIGURATION SECTION.008 SOURCE-COMPUTER. BULL-DPS7.009 OBJECT-COMPUTER. BULL-DPS7.010 *011 DATA DIVISION.012 *013 WORKING-STORAGE SECTION.014 *015 *016 EXEC SQL BEGIN DECLARE SECTION END-EXEC.017 *018 01 USERID PIC X(20) VALUE SPACES.019 01 PASSWORD PIC X(20) VALUE SPACES.020 01 HOST PIC X(20) VALUE SPACES.021 01 PEMPNO PIC S9(9) COMP-2 VALUE 0.022 01 IEMPNO PIC S9(4) COMP-1 VALUE 0.023 01 ENAMESIZE PIC S9999 COMP-1 VALUE 0.024 01 JOBSIZE PIC S9999 COMP-1 VALUE 0.025 01 DNAMESIZE PIC S9999 COMP-1 VALUE 0.026 01 PENAME PIC X(12) VALUE SPACES.027 01 PJOB PIC X(12) VALUE SPACES.028 01 PSAL PIC S99999 COMP-3 VALUE 0.029 01 PDEPTNO PIC S9999 COMP-1 VALUE 0.030 01 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 *********************************************************

The SAMPLE Transaction

47 A2 14UR Rev03 D-3

038 *039 01 RCV-BUFF.040 05 TXNAME PIC X(7).041 05 RCV-PARAMS PIC X(73).042 *043 01 ENAME-L PIC S9999 COMP-1 VALUE 12.044 01 JOB-L PIC S9999 COMP-1 VALUE 12.045 01 DNAME-L PIC S9999 COMP-1 VALUE 15.046 01 EMPNOX PIC ZZZZZ9 DISPLAY.047 01 DEPTNOX PIC X(4) DISPLAY.048 01 DEPTNON PIC S9999 DISPLAY.049 01 SALX PIC X(5) DISPLAY.050 01 SALU PIC S99999 DISPLAY.051 01 SALN PIC S99999 DISPLAY SIGN LEADING SEPARATE.052 *053 01 EMPNO-N PIC X(6) VALUE ":EMPNO".054 01 ENAME-N PIC X(6) VALUE ":ENAME".055 01 JOB-N PIC X(4) VALUE ":JOB".056 01 SAL-N PIC X(4) VALUE ":SAL".057 01 DEPTNO-N PIC X(7) VALUE ":DEPTNO".058 *059 *********************************************************060 ********** MESSAGES **********061 *********************************************************062 *063 01 ASK-EMP PIC X(23) VALUE "Enter employee name: ".064 01 ASK-JOB PIC X(23) VALUE "Enter employee job: ".065 01 ASK-SAL PIC X(23) VALUE "Enter employee salary: ".066 01 ASK-DEPTNO PIC X(23) VALUE "Enter employee dept: ".067 *068 01 SND-BUFF PIC X(80).069 01 SWITCHES.070 05 WS-NO-DATA PIC X(3) VALUE "YES".071 88 RCV-NO-DATA VALUE "YES".072 88 RCV-DATA VALUE "NO".073 *074 77 SND-LVL PIC 9 VALUE 1.075 01 NUM-DISPLAY PIC +999999999.076 *077 LINKAGE SECTION.078 COPY TDS-STORAGE.079 COPY CONSTANT-STORAGE.080 01 PRIVATE-STORAGE.081 05 TX-USERID PIC X(20).082 05 TX-PASSWORD PIC X(20).083 05 TX-HOST PIC X(20).084 05 TX-PEMPNO PIC S9(9) COMP-2.085 05 TX-PENAME PIC X(12).086 05 TX-PJOB PIC X(12).087 05 TX-PSAL PIC S99999 COMP-3.088 05 TX-PDEPTNO PIC S9999 COMP-1.


D-4 47 A2 14UR Rev03

089 05 TURN PIC 9.090 *091 COMMUNICATION SECTION.092 COPY COMMUNIC-SECTION.093 *094 PROCEDURE DIVISION USING TDS-STORAGE CONSTANT-STORAGE095 PRIVATE-STORAGE.096 A000-CODE SECTION.097 A001-BEGIN.098 PERFORM B100-RECEIVE.099 MOVE "SAMPLE" TO NEXT-TPR.100 IF PRIOR-TPR = SPACES101 MOVE 0 TO TX-PEMPNO102 MOVE SPACES TO TX-USERID103 MOVE SPACES TO TX-PASSWORD104 MOVE SPACES TO TX-HOST105 IF RCV-PARAMS = SPACES106 MOVE SPACES TO NEXT-TPR107 STRING " Invalid Connection parameters " CR LF108 DELIMITED BY SIZE INTO SND-BUFF109 PERFORM B100-SEND110 GO TO END-OF-TPR111 ELSE112 UNSTRING RCV-PARAMS DELIMITED BY "/"113 INTO TX-USERID TX-PASSWORD TX-HOST114 END-IF115 PERFORM ORA-CONNECT116 PERFORM INTERNAL-CHECKING117 MOVE 23 TO LENGTH-OUT118 STRING ASK-EMP DELIMITED BY SIZE INTO SND-BUFF119 PERFORM B100-SEND120 MOVE 1 TO TURN121 GO TO END-OF-TPR122 END-IF123 GO TO T1, T2, T3, T4 DEPENDING ON TURN.124 *125 T1.126 IF WS-NO-DATA = "YES"127 MOVE SPACES TO NEXT-TPR128 MOVE 23 TO LENGTH-OUT129 STRING " End of Insertion " CR LF130 DELIMITED BY SIZE INTO SND-BUFF131 PERFORM B100-SEND132 GO TO END-OF-TPR133 END-IF134 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.


47 A2 14UR Rev03 D-5

140 T2.141 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 T3.148 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 T4.156 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 SQL179 CONNECT :USERID IDENTIFIED BY :PASSWORD180 USING :HOST181 END-EXEC.182 STRING " Connected " LF CR183 DELIMITED BY SIZE INTO SND-BUFF.184 PERFORM B100-SENDLVL2.185 *186 *187 * ***************** INTERNAL-CHECKING *****************188 INTERNAL-CHECKING.189 *190 * RETRIEVE THE CURRENT MAXIMUM EMPLOYEE NUMBER


D-6 47 A2 14UR Rev03

191 *192 EXEC SQL SELECT NVL(MAX(EMPNO),0)+10193 INTO :PEMPNO:IEMPNO194 FROM EMP195 END-EXEC.196 *197 * CHECK TO SEE THAT EMPLOYEE NAME, JOB AND DEPT. NAME198 * FIT IN THE BUFFER.199 *200 EXEC SQL SELECT WIDTH201 INTO :ENAMESIZE202 FROM SYS.COL203 WHERE TNAME = 'EMP' AND CNAME = 'ENAME'204 END-EXEC.205 *206 IF ENAMESIZE > ENAME-L207 STRING "ENAME too large for buffer. Call your supervisor."208 LF CR DELIMITED BY SIZE INTO SND-BUFF209 PERFORM B100-SEND210 MOVE SPACES TO NEXT-TPR211 GO TO END-OF-TPR212 END-IF213 *214 EXEC SQL SELECT WIDTH215 INTO :JOBSIZE216 FROM SYS.COL217 WHERE TNAME = 'EMP' AND CNAME = 'JOB'218 END-EXEC.219 *220 IF JOBSIZE > JOB-L221 STRING "JOB too large for buffer. Call your supervisor."222 LF CR DELIMITED BY SIZE INTO SND-BUFF223 PERFORM B100-SEND224 MOVE SPACES TO NEXT-TPR225 GO TO END-OF-TPR226 END-IF227 *228 EXEC SQL SELECT WIDTH229 INTO :DNAMESIZE230 FROM SYS.COL231 WHERE TNAME = 'DEPT' AND CNAME = 'DNAME'232 END-EXEC.233 *234 IF DNAMESIZE > DNAME-L235 STRING "DEPT is too large for buffer. Call your supervisor."236 LF CR DELIMITED BY SIZE INTO SND-BUFF237 PERFORM B100-SEND238 MOVE SPACES TO NEXT-TPR


47 A2 14UR Rev03 D-7

239 GO TO END-OF-TPR240 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 NUMBER254 *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 DNAME260 INTO :PDNAME261 FROM DEPT262 WHERE DEPTNO=:PDEPTNO263 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-EXEC274 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 LF281 DELIMITED BY SIZE INTO SND-BUFF.282 PERFORM B100-SENDLVL2.283 *284 * MAKE SURE THAT EACH RECORD IS COMMITTED TO THE DATABASE.285 *286 EXEC SQL287 COMMIT WORK288 END-EXEC.


D-8 47 A2 14UR Rev03

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-BUFF299 NO DATA MOVE "YES" TO WS-NO-DATA.300 IF STATUS-IN NOT = "00"301 MOVE SPACES TO NEXT-TPR302 DISPLAY "*** RECEIVE NON OK *** STATUS KEY = ",303 STATUS-IN UPON ALTERNATE CONSOLE304 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-SENDLVL2.323 MOVE 2 TO SND-LVL.324 SEND CD-OUT FROM SND-BUFF WITH SND-LVL AFTER ADVANCING 1.325 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 LF336 DELIMITED BY SIZE INTO SND-BUFF.337 PERFORM B100-SENDLVL2.338 MOVE SQLCODE TO NUM-DISPLAY.


47 A2 14UR Rev03 D-9

339 STRING "SQLCODE: ", NUM-DISPLAY CR LF340 DELIMITED BY SIZE INTO SND-BUFF.341 PERFORM B100-SENDLVL2.342 STRING "ERRMSG: ", SQLERRMC CR LF343 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 LF351 DELIMITED BY SIZE INTO SND-BUFF.352 PERFORM B100-SENDLVL2.353 MOVE 5 TO TURN.354 GO TO END-OF-TPR.355 *356 *357 END-OF-TPR.358 EXIT PROGRAM.


D-10 47 A2 14UR Rev03

q

47 A2 14UR Rev03 E-1

E. The FETCH Transaction

The FETCHDEM program shows how to handle an ORACLE cursor with terminalconversation. The TPR fetches the ROWIDs of the tuples which match theWHERE condition; then re-fetches the tuples one at a time using the ROWIDs. Itassumes that no selected tuple is deleted while the transaction is executing, so thatthe rowids stay valid.

If your working directory has been set up correctly, you can prepare the FETCHtransaction 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, inthe STDS file of your TDS application. Log on to your TDS application and startthe FETCH transaction, with valid parameters to connect to the ORACLEdatabase:

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, thedifferent ways to control the transaction's processing, and then the first selectedtuple:


E-2 47 A2 14UR Rev03

Select ENAME, SAL from EMP where deptno=10003 records selected

To go on, say +To stop current display, say /To exit the transaction, say STOP

NAME SALARY ------ -------- CLARK 00002450

Continue the transaction's processing by entering + or /, or stop it by enteringSTOP.

001 IDENTIFICATION DIVISION.002 *003 PROGRAM-ID. FETCH.004 *005 ENVIRONMENT DIVISION.006 *007 CONFIGURATION SECTION.008 SOURCE-COMPUTER. BULL-DPS7.009 OBJECT-COMPUTER. BULL-DPS7.010 *011 DATA DIVISION.012 *013 WORKING-STORAGE SECTION.014 *********************************************************015 ********** ORACLE DECLARE SECTION **********016 *********************************************************017 *018 EXEC SQL BEGIN DECLARE SECTION END-EXEC.019 *020 01 USERID PIC X(15) VALUE SPACES.021 01 PASSWORD PIC X(15) VALUE SPACES.022 01 HOST PIC X(12) VALUE SPACES.023 01 FINAL-SQL-STRING PIC X(100) VALUE SPACES.024 01 ROWID PIC X(18) VALUE SPACES.025 01 SAL PIC S9(9) COMP-2 VALUE ZERO.026 01 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.

The FETCH Transaction

47 A2 14UR Rev03 E-3

033 *********************************************************034 ********** INPUT PARAMETERS **********035 *********************************************************036 *037 01 RCV-BUFF.038 05 TXNAME PIC X(6).039 05 RCV-PARAMS PIC X(74).040 *041 *********************************************************042 ********** MESSAGES **********043 *********************************************************044 *045 01 SND-RESPONSES.046 05 SND-SAL PIC -9(10).047 05 SND-TX-END PIC X(18)048 VALUE "End of Transaction".049 05 SND-SELECT PIC X(32)050 VALUE "Select ENAME, SAL from EMP where".051 05 SND-SELECTED PIC X(17)052 VALUE " records selected".053 05 SND-WHERE PIC X(47)054 VALUE "Enter WHERE clause for the following statement:".055 05 SND-NA-SAL PIC X(32)056 VALUE " NAME SALARY".057 05 SND-LINE PIC X(32)058 VALUE " ______ ________".059 05 SND-END-SEL PIC X(16)060 VALUE "End of selection".061 05 SND-TOO-MANY PIC X(31)062 VALUE "More than 220 selected records.".063 05 SND-RW PIC X(7)064 VALUE "ROWID= ".065 05 SND-DISAPPEARED PIC X(18)066 VALUE " has disappeared !".067 05 SND-GO-ON PIC X(32)068 VALUE "To go on, say +".069 05 SND-SLASH PIC X(32)070 VALUE "To stop current display, say /".071 05 SND-STOP PIC X(35)072 VALUE "To exit the transaction, say STOP".073 05 SND-INV-INPUT PIC X(20)074 VALUE "Invalid input string".075 05 SND-OPNERR PIC X(18)076 VALUE "Open cursor error:".077 05 SND-FETCHERR PIC X(17)078 VALUE "Exec fetch error:".079 05 SND-CNCTERR PIC X(14)080 VALUE "Connect error:".081 05 SND-PREPERR PIC X(14)082 VALUE "Prepare error:".


E-4 47 A2 14UR Rev03

083 05 SND-CLOSERR PIC X(12)084 VALUE "Close error:".085 *086 01 SND-BUFF PIC X(150).087 *088 *********************************************************089 ********** WORKING VARIABLES **********090 *********************************************************091 *092 01 SEL-ROWID PIC X(41)093 VALUE "Select ROWIDTOCHAR(rowid) from emp where ".094 01 SWITCHES.095 05 WS-NO-DATA PIC X(3) VALUE "YES".096 88 RCV-NO-DATA VALUE "YES".097 88 RCV-DATA VALUE "NO".098 *099 77 SND-LVL PIC 9.100 *101 *********************************************************102 ********** LINKAGE SECTION **********103 *********************************************************104 *105 LINKAGE SECTION.106 COPY TDS-STORAGE.107 COPY CONSTANT-STORAGE.108 01 PRIV-AND-TX-STORAGE.109 02 PRIVATE-STORAGE PIC X(1024).110 02 TRANSACTION-STORAGE.111 03 ID-DB1 PIC S9(9) COMP-2.112 03 TX-USR PIC X(15).113 03 TX-PWD PIC X(15).114 03 TX-HST PIC X(12).115 03 TX-CUR-FETCH PIC X(1).116 03 TX-EGI PIC X(1).117 03 TX-NB-ROWID PIC 9(3).118 03 TX-CUR-ROWNB PIC 9(3).119 03 TX-ROWID PIC X(18) OCCURS 220 TIMES.120 *121 COMMUNICATION SECTION.122 COPY COMMUNIC-SECTION.123 *124 PROCEDURE DIVISION USING TDS-STORAGE CONSTANT-STORAGE125 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.


47 A2 14UR Rev03 E-5

134 MOVE 80 TO LENGTH-IN.135 MOVE "NO" TO WS-NO-DATA.136 RECEIVE CD-IN MESSAGE INTO RCV-BUFF137 NO DATA MOVE "YES" TO WS-NO-DATA.138 IF STATUS-IN NOT = "00"139 MOVE SPACES TO NEXT-TPR140 DISPLAY "*** RECEIVE NON OK *** STATUS KEY = ",141 STATUS-IN UPON ALTERNATE CONSOLE142 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 = SPACES149 PERFORM B100-RCV-PARAMS150 PERFORM B300-ASK-WHERE151 GO TO END-OF-CU.152 *153 IF TX-EGI = "Y" AND RCV-BUFF = "STOP"154 MOVE SPACES TO NEXT-TPR155 MOVE 18 TO LENGTH-OUT156 STRING SND-TX-END LF CR DELIMITED BY SIZE157 INTO SND-BUFF158 PERFORM D100-SEND159 GO TO END-OF-CU.160 *161 IF TX-CUR-FETCH = "N"162 PERFORM B400-FETCH-ROWID THRU B400-END163 MOVE "N" TO TX-EGI164 MOVE 2 TO LENGTH-OUT165 MOVE 2 TO SND-LVL166 STRING LF CR DELIMITED BY SIZE INTO SND-BUFF167 PERFORM D100-SEND168 GO TO END-OF-END.169 *170 IF TX-EGI = "N" OR RCV-BUFF = "+"171 PERFORM B500-SELECT THRU B500-END172 GO TO END-OF-CU.173 *174 IF RCV-BUFF NOT = "/"175 MOVE 22 TO LENGTH-OUT176 STRING SND-INV-INPUT LF CR DELIMITED BY SIZE177 INTO SND-BUFF178 PERFORM D100-SEND.179 *180 PERFORM B700-SEND-ENDSEL.181 PERFORM B300-ASK-WHERE182 GO TO END-OF-CU.183 *184 *********************************************************


E-6 47 A2 14UR Rev03

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-DATA197 MOVE "SCOTT" TO TX-USR198 MOVE "TIGER" TO TX-PWD199 ELSE200 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 SQL212 CONNECT :USERID IDENTIFIED BY :PASSWORD213 AT DB1 USING :HOST214 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 CR224 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


47 A2 14UR Rev03 E-7

236 INTO FINAL-SQL-STRING.237 MOVE 102 TO LENGTH-OUT.238 STRING FINAL-SQL-STRING LF CR DELIMITED BY SIZE239 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 SIZE244 INTO FINAL-SQL-STRING.245 *246 EXEC SQL AT DB1247 DECLARE S1 STATEMENT END-EXEC.248 EXEC SQL249 PREPARE S1 FROM :FINAL-SQL-STRING250 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 = 1403267 MOVE 22 TO LENGTH-OUT268 STRING TX-NB-ROWID SND-SELECTED LF CR269 DELIMITED BY SIZE INTO SND-BUFF270 GO TO B400-SEND.271 IF TX-NB-ROWID IS LESS THAN 220272 ADD 1 TO TX-NB-ROWID273 MOVE ROWID TO TX-ROWID (TX-NB-ROWID)274 GO TO BOUCLE.275 STRING CR LF SND-TOO-MANY DELIMITED BY SIZE276 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 = 0283 PERFORM B300-ASK-WHERE284 GO TO END-OF-TPR.285 IF TX-NB-ROWID > 1286 STRING SND-GO-ON LF CR SND-SLASH LF CR SND-STOP LF CR


E-8 47 A2 14UR Rev03

287 DELIMITED BY SIZE INTO SND-BUFF288 MOVE 103 TO LENGTH-OUT289 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 DB1303 SELECT ENAME , SAL INTO :ENAME , :SAL FROM EMP304 WHERE ROWID = CHARTOROWID(:ROWID)305 END-EXEC.306 *307 IF SQLCODE IS LESS THAN 0 PERFORM Z400-FETCH-ERROR.308 IF SQLCODE = 1403309 STRING SND-RW TX-ROWID (TX-CUR-ROWNB) SND-DISAPPEARED310 LF CR DELIMITED BY SIZE INTO SND-BUFF311 MOVE 45 TO LENGTH-OUT312 PERFORM D100-SEND313 ELSE314 MOVE 80 TO LENGTH-OUT315 STRING " " LF CR SND-NA-SAL LF CR SND-LINE LF CR316 DELIMITED BY SIZE INTO SND-BUFF317 PERFORM D100-SEND318 MOVE SAL TO SND-SAL319 MOVE 32 TO LENGTH-OUT320 STRING " " ENAME " " SND-SAL DELIMITED BY SIZE321 INTO SND-BUFF322 PERFORM D100-SEND.323 *324 ADD 1 TO TX-CUR-ROWNB.325 IF TX-CUR-ROWNB > TX-NB-ROWID326 PERFORM B700-SEND-ENDSEL327 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.


47 A2 14UR Rev03 E-9

336 STRING LF CR SND-END-SEL LF CR DELIMITED BY SIZE337 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 1.345 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 SIZE354 INTO SND-BUFF.355 COMPUTE LENGTH-OUT = SQLERRML + 18;356 PERFORM D100-SEND.357 STRING USERID PASSWORD HOST LF CR DELIMITED BY SIZE358 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 SIZE375 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 SIZE381 INTO SND-BUFF.382 MOVE 20 TO LENGTH-OUT.383 PERFORM Z101-ERROR.


E-10 47 A2 14UR Rev03

384 *385 Z400-FETCH-ERROR.386 STRING LF CR SND-FETCHERR DELIMITED BY SIZE387 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 SIZE393 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.

47 A2 14UR Rev03 F-1

F. The "ORATDS" Transaction

The ORATDS transaction is used to dynamically tune ORACLE/TDSconfiguration parameters.

The following program is the source of the transaction and shows how the call tothe ORATCONF entry point is done. In the statements shown below, some lineswere too long to fit in this manual. These lines were folded or some spaces weresuppressed.

All details on the use of the transaction, its parameters and their scope... are givenin 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-DPS7.009 OBJECT-COMPUTER. BULL-DPS7.010 *011 DATA DIVISION.012 WORKING-STORAGE SECTION.013 ******************************************************014 ********** INPUT PARAMETERS *********015 ******************************************************016 *017 01 RCV-BUFF.018 02 TX-NAME PIC X(7).019 02 RCV-PARAMETERS PIC X(73).020 *021 ******************************************************022 ********** OUTPUT VALUES **********023 ******************************************************024 *025 01 SEND-BUFFER PIC X(80).026 *027 01 O-PARAMS.


F-2 47 A2 14UR Rev03

028 02 O-RTCD COMP-2.029 02 O-MAXTIM COMP-2.030 02 O-MAXWAT COMP-2.031 02 O-TIMOUT COMP-2.032 02 O-CSIZE COMP-2.033 02 O-NCNCT COMP-2.034 02 O-TRCLVL COMP-2.035 02 O-MESSAGE1.036 05 O-MESS1 PIC X(65).037 05 O-LINE1 PIC X(1).038 02 O-MESSAGE2.039 05 O-MESS2 PIC X(65).040 05 O-LINE2 PIC X(1).041 01 D-TIMOUT PIC -(10)9.042 01 D-MAXTIM PIC -(10)9.043 01 D-MAXWAT PIC -(10)9.044 01 D-CSIZE PIC -(10)9.045 01 D-TRCLVL PIC -(10)9.046047 01 SEND-TITLE PIC X(69)048 VALUE "********** ORA/TDS Configuration **********".049 01 SEND-STATUS PIC X(69)050 VALUE "********** ORA/TDS Layer Status **********".051 01 SEND-STARS PIC X(69)052 VALUE "*********************************** **********************************".053 01 SEND-HYPHENS PIC X(69)054 VALUE "* ------------------------------------------ ----------------------- *".055 01 SEND-TIMOUT PIC X(30)056 VALUE "* TIMOUT=".057 01 SEND-MAXTIM PIC X(30)058 VALUE "* MAXTIM=".059 01 SEND-MAXWAT PIC X(30)060 VALUE "* MAXWAT=".061 01 SEND-CSIZE PIC X(30)062 VALUE "* CSIZE =".063 01 SEND-TRCLVL PIC X(30)064 VALUE "* TRCLVL=".065 01 SEND-STARTMESS PIC X(2)066 VALUE "* ".067 01 SEND-ENDMESS PIC X(2)068 VALUE " *".069 01 SEND-ENDLINE PIC X(28)070 VALUE " *".071 *072 ******************************************************073 ********** ERROR MESSAGES **********074 ******************************************************075 *076 *

The "ORATDS" Transaction

47 A2 14UR Rev03 F-3

077 ******************************************************078 ********** ORACLE RESPONSES **********079 ******************************************************080 *081 ******************************************************082 ********** WORKING VARIABLES **********083 ******************************************************084 *085 77 SEND-LEVEL PIC 9 VALUE 3.086 77 DISPLAY-DONE PIC 9 VALUE 0.087 *088 LINKAGE SECTION.089 COPY TDS-STORAGE.090 COPY CONSTANT-STORAGE.091 01 TRANSACTION-STORAGE.092 02 I-PARAMS PIC X(73).093 *094 COMMUNICATION SECTION.095 COPY COMMUNIC-SECTION.096 *097 PROCEDURE DIVISION USING TDS-STORAGE CONSTANT-STORAGE098 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-BUFF109 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 CONSOLE113 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


F-4 47 A2 14UR Rev03

127 MOVE RCV-PARAMETERS TO I-PARAMS128 ELSE MOVE I-PARAMS TO RCV-PARAMETERS.129 CALL "ORATCONF" USING RCV-PARAMETERS O-PARAMS.130 IF (O-RTCD = -1)131 PERFORM A400-SEND-ENTETE132 PERFORM A400-SEND-MESS.133 IF O-RTCD = 1134 PERFORM A003-DISPLAY.135 IF (O-RTCD = 2) OR (O-RTCD = 7)136 MOVE 10 TO WAIT-TIME137 MOVE CURRENT-TPR TO NEXT-TPR138 IF PRIOR-TPR NOT = CURRENT-TPR139 PERFORM A400-SEND-ENTETE140 STRING SEND-STARTMESS O-MESS1 SEND-ENDMESS CR DELIMITED BY SIZE INTO SEND-BUFFER141 PERFORM A005-SEND-BUFFER142 GO TO END-OF-TPR143 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-BUFFER148 PERFORM A005-SEND-BUFFER.149 STRING SEND-STATUS CR DELIMITED BY SIZE INTO SEND-BUFFER150 PERFORM A005-SEND-BUFFER.151 STRING SEND-HYPHENS CR DELIMITED BY SIZE INTO SEND-BUFFER152 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-BUFFER158 PERFORM A005-SEND-BUFFER159 STRING SEND-TITLE CR DELIMITED BY SIZE INTO SEND-BUFFER160 PERFORM A005-SEND-BUFFER161 STRING SEND-HYPHENS CR DELIMITED BY SIZE INTO SEND-BUFFER162 PERFORM A005-SEND-BUFFER.163 *164 A400-SEND-MESS.165 STRING SEND-STARTMESS O-MESS1 SEND-ENDMESS CR DELIMITED BY SIZE INTO SEND-BUFFER166 PERFORM A005-SEND-BUFFER167 STRING SEND-STARTMESS O-MESS2 SEND-ENDMESS CR DELIMITED BY SIZE INTO SEND-BUFFER168 PERFORM A005-SEND-BUFFER

The "ORATDS" Transaction

47 A2 14UR Rev03 F-5

169 MOVE 3 TO SEND-LEVEL170 MOVE 72 TO LENGTH-OUT171 STRING SEND-STARS CR LF DELIMITED BY SIZE INTO SEND-BUFFER172 GO TO A005-SEND-BUFFER.173 *174 ******************************************************175 ********** SEND ORACLE'S RESPONSE **********176 ******************************************************177 *178 *179 *180 A003-DISPLAY.181 MOVE 1 TO DISPLAY-DONE182 MOVE 2 TO SEND-LEVEL183 MOVE 70 TO LENGTH-OUT184 PERFORM A400-SEND-ENTETE.185 MOVE O-TIMOUT TO D-TIMOUT186 MOVE O-MAXTIM TO D-MAXTIM187 MOVE O-MAXWAT TO D-MAXWAT188 MOVE O-CSIZE TO D-CSIZE189 MOVE O-TRCLVL TO D-TRCLVL190 STRING SEND-TIMOUT D-TIMOUT SEND-ENDLINE CR191 DELIMITED BY SIZE INTO SEND-BUFFER192 PERFORM A005-SEND-BUFFER193 STRING SEND-MAXTIM D-MAXTIM SEND-ENDLINE CR194 DELIMITED BY SIZE INTO SEND-BUFFER195 PERFORM A005-SEND-BUFFER196 STRING SEND-MAXWAT D-MAXWAT SEND-ENDLINE CR197 DELIMITED BY SIZE INTO SEND-BUFFER198 PERFORM A005-SEND-BUFFER199 STRING SEND-CSIZE D-CSIZE SEND-ENDLINE CR200 DELIMITED BY SIZE INTO SEND-BUFFER201 PERFORM A005-SEND-BUFFER202 STRING SEND-TRCLVL D-TRCLVL SEND-ENDLINE CR203 DELIMITED BY SIZE INTO SEND-BUFFER204 PERFORM A005-SEND-BUFFER205 STRING SEND-STARS CR DELIMITED BY SIZE INTO SEND-BUFFER206 PERFORM A005-SEND-BUFFER.207208209 A005-SEND-BUFFER.210 SEND CD-OUT FROM SEND-BUFFER WITH SEND-LEVEL AFTER ADVANCING 1.211 IF STATUS-OUT IS NOT = "00"212 DISPLAY "*** SEND NOT OK *** STATUS KEY = "213 STATUS-OUT UPON ALTERNATE CONSOLE.214 *215 END-OF-TPR.


F-6 47 A2 14UR Rev03

216 EXIT PROGRAM.

47 A2 14UR Rev03 G-1

G. Specialized Processors

G.1 Specialized Processor Specifics

The specialized processors (co- processors) are HRP (High RelationalPerformance), 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 theSystem Operator's Guide, 47 A2 60UU, that coverGCOS 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 thespecialized processors:

CoPro step A step that can use both specialized processors andstandard processors.

Standard step A step that can use only standard IPU processors.

EPU, FPU, GPU 3 groups of specialized processor starting from the useof CDPs.


G-2 47 A2 14UR Rev03

IPU The standard "native" DPS 7000 processor able toexecute any kind of process, including ORACLE.

Chronological evolution of the specialized processors:

HRP (and X-HRP) High Relational Performance processor.

Backend Server Package including four HRP's.

PSP Parallel Specialized Processors.

CDP Customer Dedicated Processor.

All the specialized processors (HRP, Backend Server and PSP) are available toORACLE activities to improve the throughput of ORACLE applications. Theyprovide a combination hardware, firmware, and software optimization for theexecution of ORACLE processes (which can also use standard IPU's).

47 A2 14UR Rev03 H-1

H. Example of the H_XAEVT Transaction

@LST@@NE@@@

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-1. 02 TDS-XA-STATUS COMP-1. 02 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.


H-2 47 A2 14UR Rev03

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 0. 05 COMMITTED COMP-1 VALUE 1.01 XA-STATUS-VALUES. 05 OK COMP-1 VALUE 0. 05 RDONLY COMP-1 VALUE 3. 05 RETRY COMP-1 VALUE 4. 05 HEURMIX COMP-1 VALUE 5. 05 HEURRB COMP-1 VALUE 6. 05 HEURCOM COMP-1 VALUE 7. 05 HEURHAZ COMP-1 VALUE 8. 05 RB COMP-1 VALUE 100. 05 RMERR COMP-1 VALUE -3. 05 NOTA COMP-1 VALUE -4. 05 INVAL COMP-1 VALUE -5. 05 PROTO COMP-1 VALUE -6. 05 RMFAIL COMP-1 VALUE -7.*77 O-RMNB COMP-1.77 I COMP-1.77 STATUS-STRING PIC X(18).77 T-STATUS-STRING PIC X(8) VALUE "COMMIT".*LINKAGE SECTION.

Example of the H_XAEVT Transaction

47 A2 14UR Rev03 H-3

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


H-4 47 A2 14UR Rev03

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 UNTILI EQUAL O-RMNB DISPLAY STAR-LINE UPON ALTERNATE CONSOLE ELSE DISPLAY "ORA/TDS structures not initialized" UPONALTERNATE 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

Example of the H_XAEVT Transaction

47 A2 14UR Rev03 H-5

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.


H-6 47 A2 14UR Rev03

q

47 A2 14UR Rev03 I-1

I. Error in Commit Phase During TDSExecution

@LST@@NE@@@

S: MWINLIB BIN ORA.O7106D.BIN;

S: SQLDBA SMLIB=ORA.O7106D.SM LMLIB=ORA.O7106D.LM;

>>>10:28 SQLDBA 7106D

SQL*DBA: Release 7.1.6.2.0 - Production on Mon Apr 22 10:28:34 1996

Copyright (c) Oracle Corporation 1979, 1994. All rights reserved.

Oracle7 Server Release 7.1.6.2.0 - Production Release

With the distributed, replication and parallel query options

PL/SQL Release 2.1.6.2.0 - Production

SQLDBA> SET INSTANCE D:ORANG.T7DB;




SQLDBA> CONNECT INTERNAL;

Connected.

SQLDBA> STARTUP OPEN DBNRG;

ORACLE instance started.

Database mounted.

Database opened.

Total System Global Area 5666448 bytes

Fixed Size 37760 bytes

Variable Size 4776720 bytes

Database Buffers 819200 bytes

Redo Buffers 32768 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


I-2 47 A2 14UR Rev03

-------------------------------------------------------------------------------

HOST

--------------------------------------------------------------------------------

DB_USER COMMIT#

------------------------------ -----------------

0 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 X2718.3 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 X2718.3 XAEVT XAEVT TRANSACTION ACTIVATED

-->10.31 X2718.3 XAEVT ********************************************************

-->10.31 X2718.3 XAEVT * XA DESYNCHRONIZATION EVENT ...

-->10.31 X2718.3 XAEVT ********************************************************

-->10.31 X2718.3 XAEVT TPR-NAME: TINSERT1

-->10.31 X2718.3 XAEVT USER-NAME: ORAOPER3

-->10.31 X2718.3 XAEVT TDS-XA-STATUS: COMMIT

-->10.31 X2718.3 XAEVT XA-GLOBAL-STATUS: RMFAIL

-->10.31 X2718.3 XAEVT ********************************************************

-->10.31 X2718.3 XAEVT * RMs STATUS

-->10.31 X2718.3 XAEVT ********************************************************

-->10.31 X2718.3 XAEVT * dbid: DB1

-->10.31 X2718.3 XAEVT * rmid: D:ORNG.T7DB

-->10.31 X2718.3 XAEVT * status: DONE

-->10.31 X2718.3 XAEVT * -----------------------------------------------------

-->10.31 X2718.3 XAEVT * dbid: DB2

-->10.31 X2718.3 XAEVT * rmid: D:ORANG.T7DB

-->10.31 X2718.3 XAEVT * status: RMFAIL

-->10.31 X2718.3 XAEVT * gblforid: C2C3F0F9D6D9E7C11B74ABC70000001000000006

-->10.31 X2718.3 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

Error in Commit Phase During TDS Execution

47 A2 14UR Rev03 I-3

commit:

*****ORNG.T7BD successful committed*

S: SQLDBA

>>>10:31 SQLDBA 7106D

SQL*DBA: Release 7.1.6.2.0 - Production on Mon Apr 22 10:31:58 1996





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 5666448 bytes

Fixed Size 37760 bytes

Variable Size 4776720 bytes

Database Buffers 819200 bytes

Redo Buffers 32768 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#

------------------------------ ----------------

0.39.97 0.C2C3F0F9D6D9E7C11B74ABC70000001000000006

prepared no

*****Global transaction status is "prepared". Wait for end of resynchronization

phase***************

22-APR-96 22-APR-96 OR

AOPER1 O

RAOPER3

7469

1 row selected.

SQLDBA> disconnect;

Disconnected.


I-4 47 A2 14UR Rev03

SQLDBA> exit;

SQL*DBA complete.

<<<10:33

S:

S:

-->10.34 X2718.3 XAEVT XAEVT TRANSACTION ACTIVATED

-->10.34 X2718.3 XAEVT *******************************************************

-->10.34 X2718.3 XAEVT * ... XA RESYNCHRONIZATION. (CHECK RESULT).

-->10.34 X2718.3 XAEVT *******************************************************

-->10.34 X2718.3 XAEVT TPR-NAME: TINSERT1

-->10.34 X2718.3 XAEVT USER-NAME: ORAOPER3

-->10.34 X2718.3 XAEVT TDS-XA-STATUS: COMMIT

-->10.34 X2718.3 XAEVT XA-GLOBAL-STATUS: DONE

-->10.34 X2718.3 XAEVT *******************************************************

-->10.34 X2718.3 XAEVT * RMs STATUS

-->10.34 X2718.3 XAEVT *******************************************************

-->10.34 X2718.3 XAEVT * dbid: DB1

-->10.34 X2718.3 XAEVT * rmid: D:ORNG.T7DB


*****Successful end of resynchronization phase**********************************************

-->10.34 X2718.3 XAEVT * -----------------------------------------------------

-->10.34 X2718.3 XAEVT * dbid: DB2

-->10.34 X2718.3 XAEVT * rmid: D:ORANG.T7DB


*****Successful end of resynchronization phase**********************************************

-->10.34 X2718.3 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 3.1.3.7.1 - Production on Mon Apr 22 10:34:46 1996


Warning: Product user profile information not loaded!

Error in disabling roles in product user profile.

Connected to:




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

------- ---------- --------- ------- --------- ------- ------- -------

9000 ASTERIX TEST 30-JUN-88 4500 10

*****Update done on table ****************************************************************

SQL> exit;

Disconnected from Oracle7 Server Release 7.1.6.2.0 - Production Release



<<<10:34

Error in Commit Phase During TDS Execution

47 A2 14UR Rev03 I-5

S:


I-6 47 A2 14UR Rev03

q

47 A2 14UR Rev03 g-1

Glossary

A

ATMIApplication to Transaction Manager Interface (X/OPEN terminology).

C

Client/Server ModelThe client system (a PC, mini, or mainframe) must request the services of the server system (a minior mainframe; never a PC).The client is the machine where the application resides.

Commitment pointA 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 commitmentrequests are deferred to the end of the current TPR.The beginning and the end of a TDS transaction are also commitment points.

Commitment unitA commitment unit (CU) represents the work done between two commitment points. Thisdefinition is valid both for ORACLE and for TDS.All work done between the two commitment points will be wholly applied to the data, or whollyignored.In standard ORACLE terminology, a commitment unit is a "logical unit of work".

Complex transactionA 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.

CursorAn area of memory acting as the interface between the user and the ORACLE kernel which assuresthe dynamic compilation of a SQL statement.It is a data structure managed by ORACLE code and associated with a DML statement.


g-2 47 A2 14UR Rev03

For each SELECT, INSERT, UPDATE and DELETE statement, a cursor is opened, either explicitlyby the user, or implicitly by ORACLE.

D

DCL statementA Data Control Language SQL statement. Such statements are GRANT and REVOKE. They areused to control the access rights to ORACLE databases. DCL statements autocommit so their usein TPRs must be carefully judged.

DDL statementA Data Definition Language SQL statement. Such statements are CREATE TABLE, CREATEINDEX, and ALTER TABLE. They are used to create, modify, and erase database objects. DDLstatements autocommit so their use in TPRs must be carefully judged.

DML statementA Data Manipulation Language SQL statement. Such statements are SELECT, INSERT, UPDATEand 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 threesoftware components: an application program, a resource manager component (typically a databasemanagement system), and a transaction manager.

E

EXEC SQL and END-EXECEvery SQL statement which is embedded in a COBOL program must be preceded by the "EXECSQL" command prefix and followed by an "END-EXEC." command suffix. This is to enable thePCC 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

HAHigh Availability.

Glossary

47 A2 14UR Rev03 g-3

O

ORACLEThe relational database management system (RDBMS) provided with GCOS 7. ORACLE is atrademark of ORACLE Corporation, California, USA, registered in the US patent office.

P

ParsingThe parsing of an SQL statement associated with a given cursor is the compilation phase of cursorprocessing.A SQL statement associated with a cursor does not need to be re-parsed each time the cursor is tobe executed.The parsing of an SQL statement can be done explicitly using the EXEC SQL PREPAREstatement.

PCCStands for PreCompiler, Common. Name of the ORACLE command that precompiles programscontaining 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 theapplicable language.The language currently supported in the ORACLE/TDS environment is COBOL-85.

Pro*COBOLThe ORACLE tool which enables programmers to embed SQL statements into COBOL programs.

R

RMResource Manager (X/OPEN terminology), typically a database management system.

S

Simple transactionA simple transaction is characterized as one where each terminal conversation is preceded by acommitment. This prevents a user from holding a resource for longer than necessary.

SQLStructured Query Language, a language designed by IBM research and normalized by the ANSIand ISO organizations. It has been adopted by ANSI as a standard language for interacting withrelational databases.


g-4 47 A2 14UR Rev03

T

TDSTransaction Driven Subsystem, the transactional monitor of GCOS 7.

Think-timeThe time (in seconds) between the execution of a CONNECT statement and the time the nextCOMMIT statement is executed for the same database.

TMTransaction Manager (X/OPEN terminology).

TPRTransaction Processing Routine. A user-written application program designed to run in the TDSenvironment 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 isentered, 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 architectureThe technique whereby two separate tasks - or processes - communicate with one another by theinterprocess communication facilities provided by GCOS 7 to accomplish a single job. Theapplication runs as a separate task from the server task. For example, the ORACLE kernel acts asthe server processor while an ORACLE application acts as the front-end or driving process.

X

XAThe interface between a transaction manager and a resource manager according to the DTP modeldefinition. It specifies an interface for a 2-phase commitment protocol.

XCP2eXtended Cooperation Protocol level-2. An application level protocol for cooperation betweendistributed transactional applications. Compatible with LU6.2 and manages Syncpoint-Protocol.

X/OPENOrganization for the normalization of open systems.

47 A2 14UR Rev03 i-1

Index

A

Access rights 5-8Administration 1-4Application to Transaction Manager Interface

g-1Architecture 1-2AT clause 2-5ATMI g-1Authority code 5-8Automatic logons 2-9Automatic restart 2-10

B

Backend Server G-2Benefits 1-1

C

C language 8-1Cache Manager 7-5Cache processing 5-9CALL DFCMIT 2-12CALL INVCMIT 2-23CALL NOCMIT 2-24CALL ROLL-BACK 2-22CARDID parameter 2-28CDP G-2Closing files 6-7Cluster 5-11COBOL 85 2-28COBOL compiler 2-28COMMIT statement 1-3, 2-13, 2-20

COMMIT WORK RELEASE 2-14Commitment

heuristic decisions 7-3Commitment point g-1Commitment unit 2-10, 2-25, 5-6, 6-2, 6-3,

g-1Common-storage 6-5COMMUNICATION SECTION sample B-2Communications server 3-1Compilation 2-28Complex transaction 5-3, g-1CONNECT statement 1-3, 2-1, 5-9connection profile, shared 8-1CONSTANT-STORAGE sample B-1Context 5-8Context cache 5-1Conversation 5-6CoPro step G-1Co-processor G-1COPY file samples B-1COR 3-1CPU time 5-11CSIZE parameter 5-1, 6-2Cursor 5-6, g-1Customer Dedicated Processor G-2

D

Data consistency 6-2, 6-5Data definition statements 8-2Database 1-4Database design 5-11Database server 3-2, 3-3, 5-11DCL statement g-2DDL statement g-2DDL statements 2-24


i-2 47 A2 14UR Rev03

D

Deadlock 6-3, 6-5Default connection 2-5Default database 2-5Distributed Transaction Processing g-2DML statement g-2DTP g-2

E

END-EXEC g-2EPU G-1Error message 3-3, 3-5, A-1EXEC SQL g-2Extension Processor Unit G-1Extra connections 3-3

F

FETCH transaction E-1FOR DEBUG 2-24

G

GETSTM 2-27

H

H_ORATDS sharable module 3-3HA 1-9Heuristic decisions

commitment 7-3rollback 7-3

High Availability 1-9High Relational Performance G-2HRP G-2

I

IDS/II 6-2, 6-3Implicit commitment 2-11Index 5-11INSTANCE 2-5

Instruction Processor Unit G-2IPU G-2IQS 6-7

J

Job Occurrence Report 4-14JOR 4-14

L

LEVEL parameter 2-28LINK_PG statement 2-29Linking 2-29Logical connection 2-2Logical disconnection 2-2, 2-14

M

Maintenance 1-4MAXOPENCURSORS parameter 4-17, 4-

20, 5-11MODIFY_TDS 3-4Multiple databases 5-12

N

National language support 6-6

O

OPEN_CURSORS 5-10Opening files 6-7Optimization 5-1, 5-10ORACA 2-27ORACA structure 4-19, 6-6, 8-2ORACATDS structure 4-19ORACATDS_CBL 4-19ORACLE g-3ORACLE_LNK subfile 2-29ORACLE7/TDS Cache Manager 7-5ORACOC 4-20ORAHOC 4-20ORAMOC 4-20

Index

47 A2 14UR Rev03 i-3

O

ORANEX 4-20ORANOR 4-20ORANPR 4-20ORASTAT entry point 4-19OWD 2-5

P

Parallel Specialized Processors G-2Parsing g-3PCC 2-28, 5-11, g-3Physical connection 2-2Precompilation 2-28, 5-11PreCompiler, Common g-3Prerequisites 1-1Pro*C TPR

compiling 8-3linking 8-3precompiling 8-3

Pro*COBOL 1-3, 2-1, g-3Process 5-8, 6-2Programming 2-1PSP G-2

R

Resource Manager g-3Restrictions 1-3Roll forward 6-7Rollback

heuristic decisions 7-3ROLLBACK statement 1-3, 2-21ROWID 5-8, E-1

S

SAMPLE transaction D-1SETMXC entry point 4-17Simple transaction 5-3, g-3SOR 3-2Spawn function 6-6SQL g-3SQL statements in TPRs 8-1

SQL*Net 1-4SQL*Net context 2-3SQLCODE 2-10, 6-2, 6-5, A-1Standard step G-1Statistics 4-14

T

Tablespace 5-11TDS g-4TDS Explicit commitment 2-12TDS transaction g-4TDS_SQL file 3-1TDS-HA 7-8TDS-STORAGE sample B-2TDS-XA 1-4

resynchronization 7-3TDS-XCP2 7-8Terminal 6-1Think-time g-4Time-out 6-3TP7LINKTPR subfile 2-29TPR 2-1

commitment 8-2rollback 8-2

Transaction g-4Transaction Driven Subsystem g-4Transaction Processing Routine g-4TRANSACTION-STORAGE 5-8, 6-6Two-task architecture g-4

U

UFAS 6-2, 6-3USE XA clause 1-8User-id 5-8

W

WHENEVER statement 2-27


i-4 47 A2 14UR Rev03

X

X/OPEN g-4XA g-4XCP2 g-4

Vos remarques sur ce document / Technical publications remarks form

Titre / Title : ORACLE7/TDS User's Guide

N° Référence / Reference No. : 47 A2 14UR Rev03 Date / Dated : May 1999

ERREURS DETECTEES / ERRORS IN PUBLICATION

AMELIORATIONS SUGGEREES / SUGGESTIONS FOR IMPROVEMENT TO PUBLICATION

Vos remarques et suggestions seront attentivement examinées. Si vous désirez une réponse écrite,veuillez indiquer ci-après votre adresse postale complète.Your comments will be promptly investigated by qualified personnel and action will be taken asrequired. If you require a written reply, furnish your complete mailing address below.

NOM / NAME : _______________________________________ DATE : _______________________

SOCIETE / COMPANY : _______________________________________

ADRESSE / ADDRESS : _______________________________________

_______________________________________

Remettez cet imprimé à un responsable Bull S.A. ou envoyez-le directement à :Please give this technical publications remarks form to your Bull S.A. representative or mail to:

Bull Electronics Angers S.A. Bull HN Information Systems Inc.CEDOC Publication Order EntryAtelier de reprographie FAX: (508) 294-741134, rue du Nid de Pie – BP 428 MA02/423S49004 ANGERS Cedex 01 Technology ParkFRANCE Billerica, MA 01821

U.S.A.

Documents

Bull DPS 7000 User's Guidesupport.bull.com/ols/product/system/gcos7/gcos7... · Database Products Bull DPS 7000 User's Guide ORACLE7/TDS User's Guide ... Suggestions and criticisms