SQL*XT for ORACLE - Bull On-line Support...

Database ProductsSQL-CMA

SQL*XT for ORACLEGCOS 7 SQL Client Mode Access User's Guide

GCOS 747 A2 01EL Rev 00

47 A2 01EL Rev 00

Database ProductsSQL-CMA

SQL*XT for ORACLEGCOS 7 SQL Client Mode Access User's

GuideGCOS 7

Subject: This manual describes the SQL CMA (Client ModeAccess) on GCOS 7 for Oracle Database

Software Supported: GCOS7-V9 TS9910 (or later)Artemis and Diane

Oracle 8i/9i on Windows 2000

GCOS 7 SQL-CMA version 2.1

Date: May 2003

Bull S.A. CEDOC357 Avenue PATTONB.P. 2084549008 ANGERS Cedex 01FRANCE

47 A2 01EL Rev 00

Copyright © Bull S.A., 2003

Bull acknowledges the rights of proprietors of trademarks mentioned herein.

No part of this publication may be reproduced, stored in a retrieval system or transmitted in any form orby any means, electronic, mechanical or otherwise without the prior written permission of the publisher.

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 eventis Bull liable to anyone for any indirect, special, or consequential damages.The information and specifications in this document are subject to change without notice.Consult your Bull Marketing Representative for product or service availability.

47 A2 01EL iii

Preface

This manual describes the GCOS 7 SQL CMA (Client Mode Access) product forOracle1 Data Base.

This product is intended for anyone who wishes to perform networking operationswith databases from GCOS 7 platforms : Artemis or Diane.

The information contained in this manual is relevant to end-users, applicationprogrammers and system administrators.

Chapter 1 introduces SQL CMA and its main components and their functions.

Chapter 2 describes the SQL CMA main components in more detail. In particular, itdescribes CMAGEN (CMA Source Generator) and CMATP (CMA TransactionProcessing interface).

Chapter 3 explains how to create a SQL CMA application (including how to get auser source to conform to the SQL CMA rules, for example, Naming Convention,Limitations, etc.).

Chapter 4 describes the generation process for the SQL CMA product.

Chapter 5 explains how to configure and enable the CMANET protocolcommunication.

Chapter 6 describes the use of SQL CMA in a batch environment.

Chapter 7 describes the use of SQL CMA in a TP (Transaction Processing)environment.

A Glossary defines some of the terms used in the manual.

1 Oracle, Oracle8i, Oracle9i, PL/SQL, Pro*COBOL are trademarks or registered trademarks of Oracle Corporation.

SQL server, Windows 2000, Visual C++ are trademarks or registered trademarks of Microsoft Corporation.Micro Focus, Net Express are trademarks or registered trademarks of Merant Corporation.

Scope andObjectives

IntendedReaders

Structure

GCOS 7 SQL CMA User's Guide

iv 47 A2 01EL

47 A2 01EL v

Table of Contents

1. What is SQL CMA?

1.1 WHAT IS SQL CMA? ......................................................................................................1-11.1.1 CLIENT SERVER MODEL.................................................................................1-21.1.2 SQL CMA MODEL .............................................................................................1-2

1.2 SQL CMA COMPONENTS .............................................................................................1-41.2.1 CMAGEN MODULE: SOURCE GENERATOR .................................................1-51.2.2 CMANET MODULE: COMMUNICATION INTERFACE.....................................1-61.2.3 CMATP MODULE: TRANSACTIONAL INTERFACE ........................................1-7

1.2.3.1 Connection Cache mechanism .........................................................1-71.2.3.2 Commit Synchronization mechanism ................................................1-7

1.3 CURRENT GCOS 7 SQL CMA OFFER..........................................................................1-8

2. Description of SQL CMA Components

2.1 SQL CMA SOURCE GENERATOR: CMAGEN..............................................................2-12.1.1 GENERATED SQL CMA SOURCES.................................................................2-22.1.2 DEBUG OPTION ...............................................................................................2-32.1.3 LOGGING OF SQL CMA GENERATOR ...........................................................2-4

2.1.3.1 Generator LOG file: «<LOG_DIR>\cmagen.log».............................2-52.1.3.2 Declared Symbol Log file: «<LOG_DIR>\cmasymb.log» ................2-72.1.3.3 Referenced Symbol Log file:«<LOG_DIR>\cmafindsymb.log» ......2-8

2.1.4 ERRORS FROM SQL CMA GENERATION....................................................2-10

2.2 SQL CMA COMMUNICATION INTERFACE: CMANET ...............................................2-24

2.3 SQL CMA TRANSACTIONAL INTERFACE: CMATP...................................................2-25


vi 47 A2 01EL

3. Defining SQL CMA Applications

3.1 COBOL SOURCES ON GCOS 7....................................................................................3-13.1.1 FORMAT OF COBOL SOURCE........................................................................3-13.1.2 COBOL DATA TYPES .......................................................................................3-4

3.2 SQL CMA COBOL RULES..............................................................................................3-43.2.1 EMBEDDED SQL AND PL/SQL ........................................................................3-53.2.2 SQL CMA COBOL DATA TYPES......................................................................3-5

3.3 USING DATABASE SQL VARIABLES ...........................................................................3-63.3.1 DECLARING SQL VARIABLES.........................................................................3-6

3.3.1.1 SQL Variable Name...........................................................................3-73.3.1.2 Comments .........................................................................................3-73.3.1.3 Continuation Lines.............................................................................3-83.3.1.4 PICTURE Attribute of SQL Variables ................................................3-83.3.1.5 RENAMES Attribute of SQL Variables ..............................................3-9

3.3.2 REFERENCING SQL VARIABLES....................................................................3-93.3.2.1 Comments .........................................................................................3-93.3.2.2 Continuation Lines...........................................................................3-103.3.2.3 Referencing SQL Arrays of Variables .............................................3-113.3.2.4 Referencing SQL Elementary Variables..........................................3-12

3.4 INCLUDE FILES .........................................................................................................3-133.4.1 SQLCA INCLUDE FILE ...................................................................................3-143.4.2 ORACA INCLUDE FILE...................................................................................3-153.4.3 ORDINARY INCLUDE FILE.............................................................................3-153.4.4 SQLCA STRUCTURE......................................................................................3-16

3.5 SQL CMA APPLICATIONS...........................................................................................3-183.5.1 RESTRICTIONS ON DECLARE STATEMENT...............................................3-18

3.5.1.1 Declare cursor with input variable ...................................................3-183.5.1.2 Declare cursor with output variable .................................................3-20

3.5.2 RESTRICTION ON CURSOR OPERATION UNDER TDS .............................3-21

3.6 SQL CMA TP DESCRIPTION.......................................................................................3-223.6.1 SQL CMA TP CACHE CONCEPT...................................................................3-22

3.6.1.1 SQL CMA TP Context Cache definition ..........................................3-223.6.1.2 SQL CMA TP Context states...........................................................3-233.6.1.3 Why a SQL CMA TP Context cache? .............................................3-24

3.6.2 CONNECT ACTION.........................................................................................3-243.6.2.1 CONNECT action provided by Oracle.............................................3-243.6.2.2 Relationship between CONNECT action and SQL CMA TP

Context ............................................................................................3-253.6.2.3 CONNECT action errors..................................................................3-26

3.6.3 COMMITMENTS..............................................................................................3-26

Preface

47 A2 01EL vii

3.6.4 COMMIT ACTION............................................................................................3-273.6.4.1 Implicit commitment.........................................................................3-273.6.4.2 Explicit commitment.........................................................................3-273.6.4.3 SQL COMMIT statement .................................................................3-273.6.4.4 Examples of COMMIT actions.........................................................3-283.6.4.5 Automatic restart .............................................................................3-293.6.4.6 Relationship between COMMIT action and SQL CMA TP context .3-30

3.6.5 ROLLBACK ACTION .......................................................................................3-303.6.5.1 ROLLBACK statement provided by Oracle .....................................3-303.6.5.2 Examples of ROLLBACK actions ....................................................3-313.6.5.3 Relationship between ROLLBACK action and SQL CMA TP

context .............................................................................................3-32

3.7 SQL CMA TP ERRORS ................................................................................................3-32

4. SQL CMA Installer

4.1 PREREQUISITES4-24.1.1 ORACLE PRODUCT .........................................................................................4-24.1.2 MERANT/MICRO FOCUS PRODUCT ..............................................................4-24.1.3 C COMPILER PRODUCT..................................................................................4-24.1.4 SQL CMA PRODUCT ........................................................................................4-2

4.2 STARTING SQL CMA CMAINST PRODUCT.................................................................4-34.2.1 INTERACTIVE PROGRAM CMAINST .............................................................4-4

4.3 STARTING SQL CMA SOURCE GENERATION............................................................4-54.3.1 «LIST NAME» AND «SOURCES NAME(s)» PARAMETERS...........................4-64.3.2 «ORACLE SETTINGS» PARAMETERS ...........................................................4-74.3.3 «APPLICATION RUNNING IN» PARAMETER .................................................4-84.3.4 «DEBUG MODE» PARAMETER.......................................................................4-84.3.5 «LOGGING FILE NAME» PARAMETER...........................................................4-94.3.6 VALIDATION OF SOURCES TO GENERATE..................................................4-9

4.4 STARTING SQL CMA SERVER BUILDING.................................................................4-104.4.1 «SERVER BINARY NAME» PARAMETER.....................................................4-114.4.2 «LIST NAME» AND «SOURCE NAME(s)» PARAMETERS ...........................4-124.4.3 «APPLICATION RUNNING IN» PARAMETER ...............................................4-134.4.4 «LOGGING FILE NAME» PARAMETER.........................................................4-13

4.5 FINAL REPORT of SQL CMA INSTALLER ..................................................................4-14

4.6 SQL CMA INSTALLER ERRORS .................................................................................4-15


viii 47 A2 01EL

5. Enable CMANET Communication

5.1 CONFIGURING THE MACHINES...................................................................................5-2

5.2 STARTING SQL CMAservice..........................................................................................5-25.2.1 ENVIRONMENT VARIABLE CMA_HOME_SQL...............................................5-25.2.2 CMASERVICE IN DEBUG MODE : FILE “CMADEBUG.TXT” ..........................5-35.2.3 STARTING OPTIONAL CMALISTENER...........................................................5-45.2.4 STOPPING OPTIONAL CMA LISTENER .........................................................5-6

5.3 LOGGING OF CMAservice (AND OPTIONAL CMA LISTENER ) ..................................5-7

5.4 CMAservice and CMA LISTENER ERRORS..................................................................5-9

5.5 LOGGING OF SQL CMA PROCESSES.......................................................................5-12

5.6 COMMUNICATION ERRORS.......................................................................................5-13

6. Using SQL CMA in Batch Mode

6.1 PREREQUISITES ...........................................................................................................6-16.1.1 SQL CMA PRODUCT ON GCOS7....................................................................6-16.1.2 SERVER EXECUTABLE ON WINDOWS 2000.................................................6-16.1.3 CMANET ENABLED ..........................................................................................6-1

6.2 BUILDING A SQL CMA COBOL CLIENT IN BATCH MODE .........................................6-26.2.1 TRANSFER SOURCES FROM WINDOWS 2000 TO GCOS7........................6-26.2.2 MOVE SQL CMA INCLUDE FILES ...................................................................6-36.2.3 COMPILE CLIENT SOURCES ..........................................................................6-36.2.4 LINK CLIENT OBJECTS....................................................................................6-3

6.3 CLIENT APPLICATION EXECUTION.............................................................................6-3

7. Using SQL CMA in Transactional Mode

7.1 PREREQUISITES ...........................................................................................................7-17.1.1 SQL CMA PRODUCT ON GCOS7....................................................................7-17.1.2 SERVER EXECUTABLE ON WINDOWS 2000.................................................7-17.1.3 CMANET ENABLED ..........................................................................................7-1

7.2 BUILDING A SQL CMA TP APPLICATION ....................................................................7-27.2.1 TRANSFER SOURCES TO GCOS7 .................................................................7-27.2.2 MOVE SQL CMA INCLUDE FILES ...................................................................7-27.2.3 COMPILE CLIENT SOURCES ..........................................................................7-27.2.4 LINK CLIENT OBJECTS....................................................................................7-2

Preface

47 A2 01EL ix

7.3 PREPARING THE TDS ENVIRONMENT.......................................................................7-37.3.1 TDS GENERATION ...........................................................................................7-3

7.3.1.1 Modifying the STDS file .....................................................................7-37.3.1.2 Running TP7GEN JCL ......................................................................7-4

7.3.2 DATABASE OBJECT FOR TP MODE : CMATP TABLE ..................................7-4

7.4 TDS EXECUTION ...........................................................................................................7-57.4.1 RUNNING SQL CMA TRANSACTIONS............................................................7-57.4.2 CONTROLLING SQL CMA EXECUTION WITH CMATDS TRANSACTION ....7-6

7.5 SQL CMA TP ERROR CODES.......................................................................................7-7

Glossary

Index


x 47 A2 01EL

Table of Graphics

Figure 1-1. Client-Server Model ...............................................................................................1-2Figure 1-2. SQL CMA Model ....................................................................................................1-3Figure 4-1. Starting SQL CMA CMAINST Product...................................................................4-3Figure 4-2. Interactive Program CMAINST ..............................................................................4-4Figure 4-3. Starting SQL CMA Source Generation ..................................................................4-6Figure 4-4. Starting SQL CMA Server Building ........................................................................4-11

Table 3-1. Format of COBOL Source.......................................................................................3-1Table 3-2. SQL CMA COBOL Type: «DAT» ............................................................................3-2Table 3-3. SQL CMA COBOL Type: «CBL» ............................................................................3-2Table 3-4. SQL CMA COBOL Type: «COB»............................................................................3-3Table 3-5. SQL CMA COBOL Type: «CBX» ............................................................................3-3Table 3-6. COBOL Data Representation on GCOS 7..............................................................3-4Table 3-7. COBOL Data Type Conversion...............................................................................3-5

Figures

Tables

47 A2 01EL 1-1

1. What is SQL CMA?

This chapter provides a global description of GCOS 7 SQL CMA and includes thefollowing information:

• SQL CMA General Description

• SQL CMA Components

• GCOS 7 SQL CMA offer.

The current SQL CMA product accepts Client applications :

• running in batch or TP mode

• accessing some Microsoft SQL server or Oracle databases

• using the standard COBOL language.

The product description is more general.

1.1 WHAT IS SQL CMA?

SQL CMA (Client Mode Access) is the general name to identify a solution whichallows a client application, running on a mainframe system, to access a databaselocated on AIX-Based Systems or Windows 2000 systems.

GCOS 7 SQL CMA is the specific SQL CMA product adapted to the GCOS 7client mainframe.

SQL CMA is a software product that allows client applications running in Batch orTransactional mode (TP) on mainframes, to access a remote relational databasesuch as Microsoft SQL server or ORACLE located on Windows 2000 platforms orAIX-Based platforms, without the database environment being installed andrunning on the mainframes.

SQL CMA brings the capability to access several various databases and to get auser application independent of the evolution of the database release.


1-2 47 A2 01EL

1.1.1 CLIENT SERVER MODEL

SQL CMA is based on the Client/Server Model which is the common technologyof most database suppliers.

Figure 1-1. Client-Server Model

There are two tasks, each one running on a different machine, and both of themcommunicating by using some communication protocols.

1.1.2 SQL CMA MODEL

Database suppliers provide a normalized SQL application programmatic interface(SQL API) that enables a programmer to create applications with databasemanagement capabilities.

Embedded SQL

A programmer can write a source application in any of the standard languages andadd some SQL statements among the other statements, just as if they were ordinarystatements of the language.

These SQL statements are named Embedded SQL statements.

SQL Preprocessing

SQL CMA is based on the SQL preprocessing principle.

In this principle, the source application, including the Embedded SQL statements,is processed by an Embedded SQL preprocessor that converts the specific SQL

Business logic

+

embedded SQL

database

server

What is SQL CMA?

47 A2 01EL 1-3

statements into procedure calls and special data structures, and produces newsource code that will be compiled and linked with the database libraries to get afinal application.

A user SQL application needs a database environment to be locally installed on theclient platform, because the Embedded SQL statements have to be preprocessed bythe appropriate database pre-compilers. SQL CMA removes this requirement fromthe Client mainframe because it performs the SQL processing on the remoteWindows 2000 or AIX-Based system.

Using appropriate tools which translate the SQL statements into specific functions,SQL CMA makes a user application independent of the SQL evolution and of thedatabase releases.

SQL CMA generates a new source code enabling the remote execution of theEmbedded SQL statements from a user database application (with SQL statementsembedded to manipulate database objects).

Figure 1-2. SQL CMA Model

Businesslogic

+

function calls

EmbeddedSQL

database

server


1-4 47 A2 01EL

1.2 SQL CMA COMPONENTS

According to the database preprocessing architecture explained previously, SQLCMA acts as a database pre-compiler.

It analyses the user application which includes some SQL statements, andtranslates it into two output source programs:

• one running on the mainframe client,

• one running on the Windows 2000 or AIX-Based server.

The source program on the Client site is named the SQL CMA client programwhile the other one is named the SQL CMA server program.

The SQL CMA generated source programs are compiled and linked in theirrespective environments (Mainframe and Windows 2000 or AIX-Based system).

The SQL CMA client program, on the mainframe, does not need any databaseenvironment such as libraries, include files, ... to be compiled and linked.

The SQL CMA server program, on the Windows 2000 server or on the AIX-Basedserver needs the standard database environment: pre-compilers, include files,database libraries, ... to be compiled and linked because it includes the SQLstatements that manipulates the database objects.

Both SQL CMA source programs communicate one with the other through a SQLCMA communication interface based on the TCP/IP protocol.

SQL CMA is composed of several modules:

CMAGEN SQL CMA Source Generator

CMANET SQL CMA Communication layer

CMATP SQL CMA Transactional interface

Each of these is described below.

What is SQL CMA?

47 A2 01EL 1-5

1.2.1 CMAGEN MODULE: SOURCE GENERATOR

According to the standard database approach, a client database application withEmbedded SQL statements is translated by a database pre-compiler to get astandard source code. This one is then compiled and linked with database librariesto get a final application.

CMAGEN, the SQL CMA Source Generator, acts as a pre-compiler, i.e. it analysesthe input application which includes the Embedded SQL statements, generates twooutput programs:

• a SQL CMA client program,

• a SQL CMA server program.

SQL CMA client program

The SQL CMA client program is a mapping of the initial user application inwhich the Embedded SQL statements have been replaced by SQL CMA sequences.These SQL CMA sequences call specific CMANET functions in order tocommunicate with the server site.

The SQL CMA client program is then transferred, compiled and linked with theCMANET libraries on the mainframe system to produce a new client applicationrunning in Batch or TP mode.

SQL CMA server program

The SQL CMA server program is independent of the initial user application butdefines a set of functions including the Embedded SQL statements referenced inthe initial user application. The SQL CMA server program has to be pre-processedby the appropriate database pre-compiler just as a standard client databaseapplication. Then, it has to be compiled and linked with the database and theCMANET libraries on the Windows 2000 system or AIX-Based system to get aserver application.

The SQL CMA server program is strictly dependent on the SQL referenced in theuser application. Therefore, any modification in the SQL statements causes theclient and server sources to be re-generated.

CMAGEN operates in the Windows 2000 environment.


1-6 47 A2 01EL

1.2.2 CMANET MODULE: COMMUNICATION INTERFACE

CMANET is the software layer that cooperates with a communication protocolsupported by the mainframe and the Windows 2000 system to provide acommunication interface between the generated SQL CMA applications.

The communication protocol supported by the CMANET software is the standardTCP/IP communication protocol, available on the mainframe and Windows 2000platform.

CMANET has a set of specific communication functions that:

• enable a connection to be established,

• exchange messages,

• control data flow between the client and the server processes.

The communication functions perform standard operations such as connecting anddisconnecting sessions, sending and receiving messages.

CMANET also includes a set of conversion functions that ensure the data typecompatibility between the heterogeneous systems: Mainframe and Windows 2000.

CMANET is an internal module, not fully detailed, so the CMANET functions arenot assumed to be called outside the SQL statement translation in the userapplication.

The CMANET module is composed of 2 layers:

• one is provided for the mainframe system, to enable the SQL CMA clientprogram to be linked,

• the other one for Windows 2000, to enable the SQL CMA server program to belinked.

A SQL CMA listener service is also provided (on Windows 2000). The SQL CMAlistener service function is to:

• listen for the client connection requests,

• accept the connection establishment,

• start the appropriate SQL CMA server process.

The SQL CMA listener is part of the CMANET module on Windows 2000; it is aWindows 2000 service.

What is SQL CMA?

47 A2 01EL 1-7

1.2.3 CMATP MODULE: TRANSACTIONAL INTERFACE

Some SQL CMA applications are Transactional applications. For example, theseapplications run in the TDS environment on the GCOS 7 platform.

The CMATP modules provide functions to ensure the data integrity through aCommit Synchronization mechanism and to increase the performance through aConnection Cache mechanism.

1.2.3.1 Connection Cache mechanism

The Connection Cache principle is to reuse physical connections as much aspossible by mapping logical connections on a unique physical connection. So,physical connecting, whose time cost is heavy, is greatly reduced.

A Commitment Unit uses contexts, i.e. working areas to handle the set ofconnections called inside the Commitment Unit. Each context is recorded in aCache Table and can be reused by other Commitment Units if it is available.

Specific sequences performing the Connection Cache handling are automaticallyinserted by CMAGEN in the SQL CMA Client source. These sequences call asuccession of CMATP functions.

1.2.3.2 Commit Synchronization mechanism

The transactional monitor activates the CMATP module for the CommitSynchronization mechanism by performing successive calls:

• a first call is made at the beginning of the Commitment Unit to initialize thecommunication interface between the two parts,

• a second one is made at the end of the Commitment Unit to commit onedatabase.


1-8 47 A2 01EL

1.3 CURRENT GCOS 7 SQL CMA OFFER

The current SQL CMA product, presently offered on the GCOS 7 platforms,accepts Client applications supporting Microsoft SQL server or Oracle databaseaccesses, and using the standard COBOL language running in batch or TP mode.

SQL CMA product environment is restricted to GCOS7 / Windows 2000environment with the database on the Windows 2000 component or on anotherWindows or AIX-Based system.

The Oracle 8i or 9i Client software is requested on the Windows 2000 side: itprovides the Oracle Pro*Cobol pre-compiler.

The Merant/MicroFocus product “Net Express 3.1” is requested on the Windows2000 side: it provides a COBOL compiler.

The Visual C++ compiler version 6.0 (standard version) is requested on theWindows 2000 side: it is used during the application server building phase.

For SQL Server access refer to documentation:

SQL*MT FOR SQL SERVER ref: 47A2 22UR Rev04

❑

47 A2 01EL 2-1

2. Description of SQL CMA Components

This chapter describes the main SQL CMA components for Client applicationssupporting Oracle 8i/9i database accesses, and using the standard COBOLlanguage.

These components are :

• CMAGEN,

• CMANET,

• CMATP.

2.1 SQL CMA SOURCE GENERATOR: CMAGEN

As mentioned in the previous chapter, SQL CMA enables a user applicationrunning on a mainframe to access a remote Windows 2000 or AIX-Based databasewithout the database environment being installed on the mainframe. Thisfunctionality is supplied because the processing of Embedded SQL statements,which needs the database environment such as libraries and pre-compilers, is doneon the Windows 2000 side.

CMAGEN converts the Embedded SQL statements into SQL CMA function calls.This ensures that the remote CMAGEN is the module collecting all the SQL CMAGenerators with their working environments.

First, a user source, including Embedded SQL statements, is submitted to a SQLCMA Generator. A SQL CMA Generator is a tool ensuring the translation of SQLstatements into specific SQL CMA functions within the user source.

Generator Executable

This executable is used through the SQL CMA Installer (MFC application =cmainst.exe). Refer to Chapter 4 for more information.

A SQL CMA Generator is supplied for each supported couplet : Database andLanguage.


2-2 47 A2 01EL

This release provides the generator «cmag-Oracle» which is the SQL CMAGenerator executable used to translate user sources manipulating Oracle objectsthrough the COBOL language.

2.1.1 GENERATED SQL CMA SOURCES

After a SQL CMA Source generation, several source files, named Generated SQLCMA Sources, are produced. Some files are created to run on the Clientmainframe, others are intended for the Windows 2000 Server. These source filesare recognizable because they are identified according to the name of the user file.

A user database source is named: «<name>.<suffix>»

where:

«<name>» is the user source radix

«<suffix>» is the standard suffix of a database application:«pco» for Oracle

The SQL CMA Source generator produces the following files:

Generated Client files for GCOS7:

«<name>cli_cob» Source code

«<name>cli_h» Include file.

Generated Server files for Windows 2000:

«<name>svr.cbl» Source code.

A work file «<name>.lst» is created to hold the list of the remote SQL CMAfunctions. This work file is only scanned by the SQL CMA Installer.

The Generated Client files, which map the initial user source without SQL code,will be transferred, compiled and linked with the CMANET libraries on the Clientmainframe.

The Generated Server files, which hold the SQL statements of the initial usersource, will be precompiled, compiled and linked with the database and theCMANET libraries on the Windows 2000 server.

Description of SQL CMA Components

47 A2 01EL 2-3

Additional output files are also generated:

«<name>svr.lis» which is the Oracle pre-compilation listing file

«<name>svr.lst» which is the Merant Cobol compilation listing file

2.1.2 DEBUG OPTION

A SQL CMA Generator performs several successive operations such as:

• Lexical analysis of the user source, according to the SQL rules adapted to thecurrent database.

• Building of a Symbol Table collecting all the SQL variables declared in the SQL«Declare Section».

• Translation of the SQL statements into specific SQL CMA sequences.

A DEBUG mode is proposed to get a track of these various phases. This trackingmay be required by the Support team to understand abnormal results.

Before you start a SQL CMA Source Generation, the SQL CMA Installer needs theDEBUG or NO DEBUG mode to be defined.

Running in NO DEBUG mode, the current SQL CMA Generator reports in thegenerator Log file only the errors detected during its processing.

In case of DEBUG mode, a full tracking is printed in the generator Log file. Aninput DEBUG option can be used to request this tracking to be normal or detailed.

The following DEBUG options are available:

Lexical Analysis Debug: «No debug» or «Normal Debug»

Default is «No debug».This option lists in the Generator Log file differentlexical objects such as SQL statements, strings,variables, ... detected in the initial user source.

Symbol Table Debug: «No Debug», «Normal Debug» or «Detailed Debug»

Default is «Normal Debug».This option logs the «SQL Symbol Table», i.e. it liststhe SQL variables declared in the SQL «DeclareSection», with their characteristics (Name, type,length).


2-4 47 A2 01EL

Symbol Research Debug: «No Debug», «Normal Debug» or «Detailed Debug»

Default is «Normal Debug».This option logs the SQL variables referenced in theSQL statements, with their declarative characteristics(Name, type, length).

The «Detailed DEBUG» option reports each symbol of the initial user source.Memory space is required if setting this option because the Generator Log filecould rapidly grow due to the flow of information.

2.1.3 LOGGING OF SQL CMA GENERATOR

Before you start a SQL CMA Source Generation, the SQL CMA Installer needs the“logfile directory” to be defined. Default value is the value of the environmentvariable “TEMP”, for example “TEMP” value is “<LOG_DIR>”

The SQL CMA generator manages a Generator log file to hold the errors issuedduring SQL CMA Source generation:

«<LOG_DIR>\cmagen.log»

The «Lexical Analysis Debug» option also records the tracking information in:

«<LOG_DIR>\cmagen.log»

The «Symbol Table debug» option creates a special «Declared Symbol file» tohold the SQL Symbol Table:

«<LOG_DIR>\cmasymb.log»

The «Symbol Research debug» option creates a special «Referenced Symbol file»to hold the referenced SQL variables:

«<LOG_DIR>\cmafindsymb.log»


47 A2 01EL 2-5

2.1.3.1 Generator LOG file: «<LOG_DIR>\cmagen.log»

The Generator Log file «<LOG_DIR>\cmagen.log» contains the errors detectedduring the SQL CMA Source generation.

This file is also used to hold DEBUG information if lexical debugging is required.

The following specific information is logged during the SQL CMA sourceGeneration:

• Header of a SQL CMA source Generation

• Description of an Error message

• Description of a Lexical DEBUG message

SQL CMA Header

A SQL CMA Generator starts logging by printing a SQL CMA header such as:

• Generator release

• Name of the user source to process

• Running mode of the user application

• DEBUG mode

• DEBUG options if DEBUG mode is required.

Examples:

Here are examples of «<LOG_DIR>\cmagen.log» headers:

CMA*GENerator 2.1.0. Production: <<appli.pco>> Logging file.Generation of BATCH application.DEBUG mode is ENABLED for:

Lexical AnalysisSymbol Table Building (Detailed)Referenced Symbol Search

CMA*GENerator 2.1.0. Production: <<appli.pco>> Logging file.

Generation of BATCH application.DEBUG mode is DISABLED.


2-6 47 A2 01EL

Generation Error Message

A Generation error message is logged according to the following format:

Name of the User source currently processed(Include files are analyzed too)

Current Line number in the source fileDate and timeText of the current source lineGeneration error detected: Number and Text

Examples:

Here are examples of generation error logging:

<<appli.pco>>, line 34 at 10-FEB-2003 15:45:30:01 B1 PIC S9999999 SYNC LEFT COMP-1

CMA-0015 COMP-1 item is limited to 4 decimal digits.

<<appli.pco>>, line 37 at 10-FEB-2003 15:45:30:01 B3 COMP-1 SYNC LEFT PIC S9(10)V999.

CMA-0017 A PICTURE string with a scaling factor is notcompatible with this USAGE.

Lexical DEBUG Message

A lexical DEBUG message is logged according to the following format:

DEBUG keywordDate and timeClass of the current source line (SQL statement, string,SQL variable...)(Text of the current source line

Examples:

Below are examples of lexical DEBUG logging:

DEBUG trace at 10-FEB-2003 15:46:39:Detection of DECLARE SECTION beginning.

DEBUG trace at 10-FEB-2003 15:48:09:EXEC statement:EXEC SQL INCLUDE SQLCA END-EXEC.

A SQL CMA Generator ends the logging by printing a line.


47 A2 01EL 2-7

The SQL CMA Generation logging is appended to «<LOG_DIR>\cmagen.log».

2.1.3.2 Declared Symbol Log file: «<LOG_DIR>\cmasymb.log»

The Declared Symbol Log file: «<LOG_DIR>\cmasymb.log» is created if the«Symbol Table debug» option is set before performing the SQL CMA sourceGeneration.

«<LOG_DIR>\cmasymb.log» describes the SQL variables, declared in the SQL«Declare Section» which are then referenced in SQL statements.

In a COBOL source, the SQL variable attributes are described as follows:

Name of the User source in which the variable is declaredVariable nameLEVEL numberUSAGE clausePICTURE clauseGlobal Size of the variableSize 0f the V9 part of the PICTURE clauseSize 0f the S9 part of the PICTURE clauseLink addresses.

Examples:

Below are examples of «<LOG_DIR>\cmasymb.log» records:

«01 VAR3 COMPUTATIONAL-2.» is described as follows

<<appli.pco>> Variable declaration:Symbol Name: VAR3Buffer Address: 0x20022f98Level: 01USAGE Type: COMP-2OCCURS Loop: 0PICTURE string: NULLPICTURE size: 0PICTURE S9 size: 0PICTURE V9 size: 0Next Buffer Address: 0x20029e38Previous Buffer Address: 0x20026c98

«... 05 VAR4 OCCURS 5 TIMES PIC S9(7)V99 COMP-3 VALUE ZERO.» isdescribed as follows:


2-8 47 A2 01EL

<<appli.pco>> Variable declaration:Symbol Name: VAR4Buffer Address: 0x20022f98Level: 05USAGE Type: COMP-3OCCURS Loop: 5PICTURE string: S9(7)V99PICTURE size: 9PICTURE S9 size: 7PICTURE V9 size: 2Next Buffer Address: 0x2002a268Previous Buffer Address: 0x20026c98

A SQL CMA Generator ends the declaration debugging by printing a line.

The SQL CMA declaration debugging is appended in«<LOG_DIR>\cmasymb.log».

2.1.3.3 Referenced Symbol Log file:«<LOG_DIR>\cmafindsymb.log»

The Referenced Symbol Log file: «<LOG_DIR>\cmasymb.log» is created if the«Symbol Research debug» option is set before performing the SQL CMA sourceGeneration.

«<LOG_DIR>\cmafindsymb.log» describes the SQL variables referenced in theSQL statements.

There are two kinds of referenced variables: Input variables and Outputvariables:

Input SQL variables («USER to KERNEL») are input parameters of a SQLstatement so, their value must be transmitted by theclient application to the server process.

Output SQL variables («KERNEL to USER») are output parameters of aSQL statement so, their value is returned by the serverprocess to the client application.

The description of a referenced SQL variable in«<LOG_DIR>\cmafindsymb.log» looks like the description of a declared SQLvariable in «<LOG_DIR>\cmafindsymb.log».


47 A2 01EL 2-9

A record in «<LOG_DIR>\cmafindsymb.log» has the following description:

Name of the User source in which the variable is referencedVariable type: Input or Output variable:

<<USER to KERNEL>><<KERNEL to USER>>

To get details about the other attributes, refer to the previous paragraph.

A SQL CMA Generator ends the debugging by printing a line.

The SQL CMA debugging of referenced SQL variables is appended in«<LOG_DIR>\cmafindsymb.log».

Examples:

Below are examples of «<LOG_DIR>\cmafindsymb.log» records (in a COBOLsource):

<<EXEC SQL SELECT EMPNO INTO :VAR3 FROM EMP WHERE DEPTNO = :VAR4END-EXEC.>>

<<appli.pco>>,line 22 Referenced variable: VAR3 (sent from KERNELto USER)

Symbol Name: VAR3Buffer Address: 0x20026ce8Level: 01USAGE Type: COMP-2OCCURS Loop: 0PICTURE string: NULLPICTURE size: 0PICTURE S9 size: 0PICTURE V9 size: 0Next Buffer Address: 0x20027118Previous Buffer Address: 0x0

<<appli.pco>>,line 23 Referenced variable: VAR4 (sent from USER toKERNEL)

Symbol Name: VAR4Buffer Address: 0x20027548Level: 05USAGE Type: COMP-3OCCURS Loop: 5PICTURE string: S9(7)V99PICTURE size: 9PICTURE S9 size: 7PICTURE V9 size: 2Next Buffer Address: 0x0Previous Buffer Address: 0x20027118


2-10 47 A2 01EL

2.1.4 ERRORS FROM SQL CMA GENERATION

The Embedded SQL in COBOL source can be ANSI 92 or Oracle SQL.

*** CMA-0000 Error while opening the ‘xxx’ file.

Cause:

The SQL CMA Generator was unable to open a temporary file for internal use.

There may be:

• insufficient disk space,

• too many open files,

• read-only protection on the output directory.

Action:

Make sure that:

• there is enough disk space,

• the limit for open files is set high enough,

• the protection on the directory allows opening a file for writing.

*** CMA-0010 Error while a host variable descriptor is allocated .

Cause:

A system error was returned by Windows 2000 during memory space allocation.The «alloc» system function was invoked.

Action:

To fix the problem, contact your support team representative .


47 A2 01EL 2-11

*** CMA-0011 Garbled characters in the variable declaration.

Cause:

Some characters were not recognized during the Lexical analysis of the currentstatement.

Action:

Check the statement syntax and make sure that garbled characters are not addedwithin the declaration.

*** CMA-0012 Host variable name has already been found.

Cause:

There is syntax error in the COBOL declaration. A variable name is defined twicein the COBOL declaration.

Action:

Correct the syntax of the COBOL declaration according to the COBOLdocumentation.

*** CMA-0013 The USAGE clause has already been declared.

Cause:

There is syntax error in the COBOL declaration. A USAGE clause is defined twicein the variable declaration.

Action:

Correct the syntax of the COBOL declaration according to the COBOLdocumentation.


2-12 47 A2 01EL

*** CMA-0014 No PICTURE clause defined.

Cause:

According to the COBOL rules, this USAGE clause requires a PICTURE clause tobe defined.

Action:

Correct the COBOL declaration according to the COBOL documentation.

*** CMA-0015 COMP-1 item is limited to 4 decimal digits.

Cause:

This COBOL data type has a size limitation according to the COBOL rules. Thecurrent declaration exceeds the maximum value allowed by the COBOL compiler.

Action:

Correct the data type size in the COBOL declaration as indicated in the errormessage.

*** CMA-0016 A PICTURE clause is not compatible with this datatype.

Cause:

According to the COBOL rules, this USAGE clause must not be associated with aPICTURE clause.

Action:



47 A2 01EL 2-13

*** CMA-0017 A PICTURE string with a scaling factor is not compatible with thisUSAGE.

Cause:

According to the COBOL rules, this USAGE clause must not be associated with aPICTURE clause with a scaling factor.

Action:


*** CMA-0018 A garbled type (xxx) is detected. Internal error while building theSymbol Table.

Cause:

An internal error message is logged by the SQL CMA Generator.

Action:

To fix the problem, contact your support team representative.

*** CMA-0019 COMP-2 item is limited to 9 decimal digits.

Cause:

This COBOL data type has a size limitation according to the COBOL rules. TheSQL variable declaration exceeds the maximum value allowed by the COBOLcompiler.

Action:

Correct the data type size in the SQL variable declaration as indicated in the errormessage.


2-14 47 A2 01EL

*** CMA-0020 WARNING: A ‘FILLER’ declaration is not expected in DECLARE sectionby some COBOL Precompilers.

Cause:

The COBOL reserved word «FILLER» is used to declare a SQL variable name.Some database precompilers issue an error while precompiling such a SQL variabledeclaration.

Action:

The SQL CMA Generator warns the user about this error case. Do not use«FILLER» keyword to declare a SQL variable name.

*** CMA-0031 The type (xxx) of ‘yyy’ variable could not be recognized.

Cause:

This is an internal error message.

Action:


*** CMA-0032 The CMA*TP CONNECT sequence could not be generated.

Cause:

The current SQL CONNECT statement could not be replaced by a SQL CMAsequence.

Some lexical errors, detected while analyzing the declaration of the CONNECTvariables, caused the garbled SQL variables to be removed from the Symbol Table.The SQL CMA Generator is not able to insert the CMATP sequence which requiresall the CONNECT variables to be defined.

Action:

Check the declaration of the SQL variables referenced in the SQL CONNECTstatement and correct the syntax according to the error message.


47 A2 01EL 2-15

*** CMA-0033 The CMA*TP COMMIT sequence could not be generated.

Cause:

The current SQL COMMIT statement could not be replaced by a SQL CMAsequence.

Some lexical errors, detected while analyzing the declaration of the COMMITvariables, caused the garbled SQL variables to be removed from the Symbol Table.The SQL CMA Generator is not able to insert the CMATP sequence which requiresall the COMMIT variables to be defined.

Action:

Check the declaration of the SQL variables referenced in the SQL COMMITstatement and correct the syntax according to the error message.

*** CMA-0034 Error while a label block is allocated

Cause:

A system error was returned by Windows 2000 during memory space allocation.The «alloc» system function was invoked.

Action:


*** CMA-0050 Referenced variable ‘xxx’ has not a unique declaration.

Cause:

This variable name has been declared more than once. The SQL CMA Generatorneeds more precision to determine the variable name invoked in the statement.

Action:

If the referenced variable is an elementary data item, you could qualify it with itscomplete group items to avoid ambiguity. Otherwise, change the variable name.


2-16 47 A2 01EL

*** CMA-0051 Referenced variable ‘xxx’ has no valid declaration.

Cause:

This variable referenced could not be found in the Symbol Table. Some lexicalerrors, detected while analyzing the variable declaration, caused the garbledvariable to be removed from the Symbol Table. The SQL CMA Generator is unableto process the SQL statement which requires all its referenced variables to bedefined.

Action:

Check the declaration of this variable, referenced in the current SQL statement, andcorrect the declaration error.

*** CMA-0052 Referenced variable ‘xxx’ must be an elementary item not a groupone.

Cause:

A SQL statement could not reference a group item, only elementary items could bereferenced. This restriction is imposed by some database precompilers that issue anerror while precompiling such a SQL statement.

Suppose that the declaration is:

01 VAR1.05 VAR11 PIX X(3).05 VAR12 PIX X(3).

The group item VAR1 must not be directly referenced in a SQL statement.

Consequently, the following statement is invalid:

EXEC SELECT COL1 INTO :VAR1 FROM TABLE1 WHERE...

However, the following statement is valid:

EXEC SELECT COL1, COL2 INTO :VAR11, :VAR12FROM TABLE1 WHERE...

Action:

Correct the referenced SQL variable according to the SQL CMA rules.


47 A2 01EL 2-17

*** CMA-0053 Referenced variable ‘xxx’, with a 01|77 level number, must not bedeclared inside a group item.

Cause:

There is a syntax error in the COBOL declaration of this variable. A variabledeclared with a 01 or 77 level number must not be an elementary data item.

Action:


*** CMA-0054 Referenced variable ‘xxx’ must be fully detailed until anelementary item.

Cause:

The SQL CMA Generator imposes a naming convention on an elementary namewhich is qualified.

Suppose the following declaration:01 VAR1.02 VAR12.03 VAR111 PIX X(3).

The elementary name VAR111 could be referenced in a SQL statement such as:

• if the name «VAR111» is unique in the «Declare Section»:EXEC SELECT COL1 INTO :VAR111 FROM TABLE1 WHERE...

• or to avoid ambiguity, if the name «VAR111» is not unique in the «DeclareSection»:

EXEC SELECT COL1 INTO :VAR111 OF VAR12 OF VAR1FROM TABLE1 WHERE...

A partial qualification is rejected by the SQL CMA Generator:

EXEC SELECT COL1 INTO :VAR111 OF VAR1FROM TABLE1 WHERE...


2-18 47 A2 01EL

Action:

Correct the referenced SQL variable according to the SQL CMA rules.

*** CMA-0055 WARNING: A group item ‘xxx’ with a 77 level number is not expectedby some COBOL Precompilers.

Cause:

A group item declared with «77» level number is not allowed by some databaseprecompilers which issue an error while precompiling such a SQL variabledeclaration.

Action:

The SQL CMA Generator warns the user about this error case. Declare the groupitem with «01» level if possible.

*** CMA-0056 Error while a host ident buffer is allocated .

Cause:

A system error is returned by Windows 2000 during memory space allocation. The«alloc» system function was invoked.

Action:

To fix the problem, contact your support team representative .

*** CMA-0060 Garbled context ‘xxx’ is to be restored.

Cause:


Action:



47 A2 01EL 2-19

*** CMA-0061 Garbled simple type found in host variable declaration: ’xxx’.’

Cause:


Action:


*** CMA-0062 Incorrect referenced host variable in EXEC statement.

Cause:


Action:


*** CMA-0063 Error while a include descriptor is allocated .

Cause:


Action:



2-20 47 A2 01EL

*** CMA-0064 WARNING: This COBOL type is ignored by CMA Generator.

Cause:

Some database precompilers do not allow the following COBOL data types to beused in a SQL variable declaration: BIT.

These COBOL data types are not processed by the SQL CMA Generator when theyare used in SQL variable declarations.

Action:

The SQL CMA Generator warns the user about this error case.

*** CMA-0066 Error while a CMA*Gen context is allocated.

Cause:


Action:

To fix the problem, contact your support team representative

*** CMA-0067 Error while INCLUDE checking: Infinite include loop detected on‘xxx’.

Cause:

The SQL CMA Generator prevents a source file from including itself. This is toprevent the Generator from looping indefinitely.

Action:

Correct the syntax of the INCLUDE command, according to the SQL CMA rules.


47 A2 01EL 2-21

*** CMA-0068 EXEC SQL INCLUDE statement only accepts local INCLUDE filename.

Cause:

Some COBOL precompiler supports preprocessor statements such as: «EXEC SQLINCLUDE» statement that allows to include files containing only SQL statements.

It is possible to write an INCLUDE statement using the name of the file or thepathname as follows:

EXEC SQL INCLUDE filename END-EXEC.

EXEC SQL INCLUDE ‘pathname’ END-EXEC with quote marks.

The OpenESQL and the SQL CMA Generator accept only the first pattern to beused. They do not process a SQL INCLUDE statement containing a pathnamereference.

Action:

Transform the «pathname» parameter to a «filename» parameter and transfer thereferenced INCLUDE file locally.

*** CMA-0070 Error while compilation descriptor is allocated.

Cause:


Action:

To fix the problem, contact your support team representative


2-22 47 A2 01EL

*** CMA-0071 Syntax error: Include name must not be quoted.

Cause:

The «COPY» COBOL command used to include files is processed by the SQLCMA Generator if the command is inserted within the SQL «Declare Section».

The SQL CMA Generator rejects a quoted include name because some COBOLcompilers issue an error while precompiling such a COBOL statement.

Action:

Correct the syntax of the COPY command according to the SQL CMA rules.

*** CMA-0072 CMA*Gen only supports an ANSI-Compliant Database.

Cause:

The «BEGIN WORK» is used to define a transactional sequence when a non-ANSIdatabase is to be accessed.

The SQL CMA Generator accepts only ANSI-compliant databases to be accessedin Transactional mode.

Action:

SQL CMA applications, running in a TP environment, could access only ANSI-compliant databases.


47 A2 01EL 2-23

*** CMA-0073 This COBOL feature is not supported.

Cause:

Some database precompilers do not allow the following standard COBOL featuresto be used in an SQL variable declaration:

IS EXTERNALIS GLOBALRENAMESSYNCHRONIZED RIGHT

These COBOL features are refused by the SQL CMA Generator when they areused in SQL variable declarations.

Action:

Correct the SQL variable declarations which use these COBOL features


2-24 47 A2 01EL

2.2 SQL CMA COMMUNICATION INTERFACE: CMANET

CMANET is the software layer that cooperates with a communications protocolsupported by the mainframe and the Windows 2000 systems to provide acommunications interface between the SQL CMA Client and Server processes.

The communications protocol supported by the CMANET software is the standardTCP/IP communications protocol, available both on the mainframe (SOCKG7product) and Windows 2000 platforms (WINSOCK2).

As previously mentioned, CMANET supports the following functionality:

• Exchange SQL CMA messages between the Client and the Server processes,

• Convert the SQL CMA messages on the server side to ensure the data typecompatibility.

CMANET has 2 parts, installed both on the mainframe and Windows 2000platforms:

• On the mainframe, the Linked Unit (LKU) «H_CMANET», located in theSharable Module (SM) «H_SM_DCM» , is delivered in the file«SYS.DCM.SYSTEM».

• On Windows 2000, several classes of files are delivered to compile and link theuser sources:

− The code independent of the user application and of the database distributionis delivered as a DLL (Dynamic Link library) named dllCMANET.dll(delivered with dllCMANET.lib and dllCMANET.h). This code concerns theconversion and the trace.

− The following source file depends on the user application. It includes the mainand some of the socket functions. It is compiled by the SQL CMA Installerduring the SQL CMA Application Server building: «cmasvr.c»

− The INCLUDE files and COBOL COPY files delivered are necessary for theuser application to be correctly compiled. (cmabuf.h, cmacst.h andCMA_H.CPY)

• On Windows 2000, a TCP/IP listener is provided to accept the client connectionsand start the appropriate SQL CMA application Server process(es).

This listener is a Windows 2000 service «CMAservice.exe» : startup is automaticwhen it is selected at install time. Any action is to be done via Start-> ControlPanel -> Administrative Tools -> Services. The default port is 9007 (refer to the file“services” in the directory system32\etc\drivers). You may modify the line thatcontains the string “cmaserver”. If you need debugging information, modify thedelivered file CmaDebug.txt and set debug=YES. In this case, the file


47 A2 01EL 2-25

“CMAservice.log” (in the TEMP directory) contains more information and all theCMA applications are launched with the debug mode (all information is written infiles named “cmasql_<pid>.log” ,in the TEMP directory).

Another executable «CMAlistener.exe» is delivered, and may be launched onanother port (option port = ) and with the option debug. Start it with Start ->Programs -> SQL-CMA -> CmaOptionalListener. An executable “CMAstop.exe”is provided to stop the CMA listener(s) (Start it with Start -> Programs -> SQL-CMA -> CmaStop).

The CMANET files are usually referenced as the «CMANET library» in thefollowing chapters of this document.

The CMA application server is built from a Cobol source with calls to Oracle SQLlayer and the CMANET files. It will use Oracle SQL library and the COBOLRuntime to execute the requests on the database (ORASQL8.DLL andCBLRTSS.DLL).

2.3 SQL CMA TRANSACTIONAL INTERFACE: CMATP

The CMATP module provides functions to get a SQL CMA application running inTP mode on the mainframe.

Writing an SQL CMA Transactional application is described completely inChapter 3 and building and using SQL CMA application in TP mode is described inChapter 7.


2-26 47 A2 01EL

❑

47 A2 01EL 3-1

3. Defining SQL CMA Applications

This chapter explains how to make a user application consistent with the SQLCMA rules.

A user database application must first comply with the language and database rulesapplied on the mainframe.

SQL CMA imposes some limitations and writing conventions to the SQL variablesand statements used within the user source.

3.1 COBOL SOURCES ON GCOS 7

A user source written in COBOL must follow the local rules supported on themainframe. Refer to the appropriate reference manuals.SQL CMA accepts as input COBOL sources conform to the GCOS 7 COBOL 85standard.

3.1.1 FORMAT OF COBOL SOURCE

The COBOL reference format describes a line of COBOL text in terms of characterpositions in a line as shown below:

Table 3-1. Format of COBOL Source

Columns Used Forx to y Sequence number areay+1 Indicator areay+2 to z Area Az+1 to the line end Area B8 characters before the end of line Card identifier area

The length of area B depends upon the actual line length of the program andwhether the optional «8 character card identifier area» is included.

ORACLE 7 SQL CMA User's Guide

3-2 47 A2 01EL

The use of the «sequence number area» and the «card identifier area» can becontrolled by specifying the language type of the COBOL program and by usingthe CARDID parameter of the CBL command (COBOL compiler on GCOS 7).

The language type of the COBOL program is specified when the file is created:

• by the TYPE parameter of a MOVE command:TYPE=COBOLX

• by the W request of an EDIT command:W(CBX) program

A SQL CMA COBOL source is held in one of the formats shown in the following 4tables:

Table 3-2. SQL CMA COBOL Type: «DAT»

Character Positions Used For1-6 Sequence number area7 Indicator area8-11 Area AFrom position 12 to 8 positions before the end ofthe line (Area B can extend up to characterposition 247)

Area B

Last 8 characters to 255 Card identifier area

The language type of this COBOL file is «DATASSF or DAT».

The CARDID option of the CBL command is set to 1.

Table 3-3. SQL CMA COBOL Type: «CBL»

Character Positions Used For1-6 Sequence number area7 Indicator area8-11 Area AFrom position 12 to the end of the line(Area B can extend up to character position 255)

Area B

Not Applicable Card identifier area

The language type of this COBOL file is «DATASSF or DAT».


Defining SQL CMA Applications

47 A2 01EL 3-3

Table 3-4. SQL CMA COBOL Type: «COB»

Character Positions Used ForNot Applicable Sequence number area1 Indicator area2-5 Area AFrom position 6 to 8 positions before the end ofthe line (Area B can extend up to characterposition 247)

Area B

Last 8 characters Card identifier

The language type of this COBOL file is «COBOL or COB».


Table 3-5. SQL CMA COBOL Type: «CBX»

Character Positions Used ForNot Applicable Sequence number area1 Indicator area2-5 Area AFrom position 6 to the end of the line(Area B can extend up to character position 255)

Area B

Not Applicable Card identifier

The language type of this COBOL file is «COBOLX or CBX».

The CARDID option of the CBL command is not relevant.


3-4 47 A2 01EL

3.1.2 COBOL DATA TYPES

Here is the COBOL data representation on GCOS 7.

Table 3-6. COBOL Data Representation on GCOS 7

USAGE Clause Machine Description PICTURE ClauseDISPLAY EBCDIC byte RequiredCOMP Packed decimal RequiredPACKED-DECIMAL Packed decimal RequiredBINARY 16-bit or 32-bit fixed binary RequiredCOMP-1 16-bit fixed binary Not RequiredCOMP-2 32-bit fixed binary Not RequiredCOMP-3 Packed decimal RequiredCOMP-5 Packed decimal RequiredCOMP-8 Packed decimal RequiredCOMP-9 Floating single precision Not AllowedCOMP-10 Floating double precision Not AllowedCOMP-15 Floating quadruple precision Not AllowedBIT 1 bit per character position RequiredPOINTER 32-bit direct address Not AllowedINDEX 6 bytes Not Allowed

Both the words «COMP» and «COMPUTATIONAL» are allowed.

3.2 SQL CMA COBOL RULES

As stated above, SQL CMA translates the user source into two generated SQLCMA sources intended to run on GCOS 7 and Windows 2000 systems respectively.

SQL CMA does the following:

1. it performs a lexical analysis of the initial user source,

2. it builds a Symbol table to hold the declared variables,

3. it generates the final SQL CMA sources.

As COBOL compilers on GCOS 7 are different from the Merant/Micro Focuscompiler used on Windows 2000, SQL CMA must get the generated sources whichare «compilable» on their respective systems. So, a data type mapping of thedeclared variables and some writing rules are necessary.


47 A2 01EL 3-5

3.2.1 EMBEDDED SQL AND PL/SQL

The product is restricted to embedded SQL and PL/SQL. The term embeddedrefers to SQL or PL/SQL statements placed within the application program anddelimited by EXEC SQL / END-EXEC keywords.

The variables must be declared either within the Oracle DECLARE SECTION orin the embedded PL/SQL block.

This means Oracle Call Interface (OCI) and Dynamic SQL method 4 are notsupported because they use Cobol call statements (OCI) or declaratives outside theOracle Declare Section (SQLDA in Dynamic SQL method 4).

3.2.2 SQL CMA COBOL DATA TYPES

The standard COBOL data types are converted in the generated SQL CMA files asfollows:

Table 3-7. COBOL Data Type Conversion

COBOL TypesUser Source (GCOS 7)

COBOL TypesCMA Client Source

(GCOS 7)

COBOL TypesCMA Server Source

( Windows 2000 )BINARY COMP-2 COMP-5 S9(9)COMP COMP-3 COMP-3COMP-1 COMP-1 COMP-5 S9(4)COMP-2 COMP-2 COMP-5 S9(9)COMP-3 COMP-3 COMP-3COMP-5 COMP-3 COMP-3COMP-8 COMP-8 COMP-3COMP-9 COMP-10 COMP-2COMP-10 COMP-10 COMP-2COMP-15 COMP-10 COMP-2DISPLAY DISPLAY DISPLAYPACKED-DECIMAL PACKED-DECIMAL PACKED-DECIMAL

SQL CMA does not support all the standard COBOL data types: «INDEX»,«POINTER» and «BIT» are rejected because these data types cause theMerant/Micro Focus pre-compiler on Windows 2000 to generate an error.The single FLOAT COMP-1 on Windows 2000 is not allowed as a host variable.

To avoid this situation, SQL CMA anticipates and points out such COBOL datatypes if they are found in declarations of variables.

Note: These rules affect only the SQL variables, not the other variablesdeclared within the user source. All other variables can accept any


3-6 47 A2 01EL

standard COBOL data type as attribute. For the SQL variables, seethe next paragraph.

3.3 USING DATABASE SQL VARIABLES

To get details about how to produce a user COBOL application, refer to theappropriate documentation provided by the database suppliers.

However, SQL CMA imposes some limitations and writing conventions on SQLvariables and statements. These are described in the following paragraphs.

The following paragraphs describe the restrictions imposed by SQL CMA eitherbecause of:

• Database pre-compiler restrictions,

or

• SQL CMA limitations.

3.3.1 DECLARING SQL VARIABLES

A SQL variable, referenced in SQL statements, must be declared in a standard areanamed «DECLARE SECTION» as described in the database documentation.

A «DECLARE SECTION» is delimited by the «EXEC SQL BEGIN DECLARESECTION END-EXEC» and «EXEC SQL END DECLARE SECTION END-EXEC» statements.

Only SQL variables are analyzed by SQL CMA. Other COBOL variables declaredoutside the «DECLARE SECTION» are ignored.

Several «DECLARE SECTION» areas may be defined inside a user program.However, the SQL variable names dispatched in the different «DECLARESECTION» areas must be unique in the whole user program, i.e. the same SQLvariable name must not be used in two declarations.

Hereafter are the restrictions on «DECLARE SECTION» prescribed by theDatabase Suppliers and SQL CMA.


47 A2 01EL 3-7

3.3.1.1 SQL Variable Name

• SQL variable names must consist only of letters, digits and hyphens and mustbegin with a letter.

• SQL CMA differentiates between upper case letters and lower case letters. Forexample, in the following declarations, VAR1 and var1 are two different SQLvariables:

01 VAR1 PIC X(10).01 var1 PIC X(10).

• A SQL variable must not be a COBOL reserved word.

3.3.1.2 Comments

As the database pre-compiler does, SQL CMA allows comment lines to be insertedin the «DECLARE SECTION».

The Standard COBOL comment lines may be placed between two SQL variabledeclarations.

The database comment lines (Double dash comment indicator) may be placed atthe end of SQL variable declarations. For example:

*COMMENT for VAR101 VAR1 PIC X(10)./COMMENT for VAR201 VAR2 PIC X(11).01 VAR1 PIC X(10). -- COMMENT for VAR101 VAR2 PIC X(11). -- COMMENT for VAR2

You are strongly recommended not to split a SQL variable declaration with acomment sequence, but to insert it either before or after the declaration.


3-8 47 A2 01EL

3.3.1.3 Continuation Lines

COBOL compilers allow you to continue words from one line to the next using acontinuation indicator: a hyphen «-» in the «indicator area» column.

SQL CMA allows only SQL variable names and level numbers to be split. All theother COBOL clauses must not be split (reserved words, PICTURE clause...).

The following 3 declarations are equivalent

01 VAR1 COMP-1.

01 VA-R1 COMP-1.

0-1 VA- R1 COMP-1.

A hyphen in the «indicator area» of a line indicates that the first non-blankcharacter in Area B of the current line is the successor of the last non-blankcharacter of the preceding line, without any intervening space.

3.3.1.4 PICTURE Attribute of SQL Variables

The COBOL PICTURE clauses you can specify in the «DECLARE SECTION»are shown below:

PIC X...X or PIC X(n)PIC S9...9 or S9(n)PIC S9...9V9...9 or S9(n)V9(n)

PICTURE clause for SQL variables do not allow you to use the followingcharacters:

• A and P such as PIC SV9(n)

• Editing characters such as Z / + , - . ,

• Only signed numbers (PIC S...) are allowed:

− PIC 9999 or PIC 9(n) are forbidden.

• There must be no sign clause.


47 A2 01EL 3-9

3.3.1.5 RENAMES Attribute of SQL Variables

SQL CMA generates a SQL CMA error when a SQL variable with «RENAMES»attribute is referenced in a SQL statement:

CMA-0052 Referenced variable «VAR1» must be an elementary item not a group one.

A SQL variable with the «RENAMES» attribute could cause SQL CMA errors onthe SQL variables declared just after this declaration.

The preceding clauses apply only to SQL variables. Variables declared outside the«DECLARE SECTION» can include the «RENAMES» clause.

3.3.2 REFERENCING SQL VARIABLES

SQL variables represent normal COBOL variables that you use in SQL statements.When a SQL variable is used in a SQL statement, you must precede its name with acolon «:».

For example:

:SQLVAR

The restrictions and naming conventions to apply when referencing a SQL variableare given below.

3.3.2.1 Comments

COBOL comment lines may be placed within SQL statements. Comment lines startwith an asterisk in the «indicator area».

You can also place ANSI SQL-style comments which start with a double dash,within SQL statements, at the end of line.

You are strongly recommended not to split an EXEC statement with a commentsequence, but to insert it before «EXEC SQL» clause or after «END-EXEC.»clause.


3-10 47 A2 01EL

Example:

* this is a COBOL comment lineEXEC SQL INSERT INTO TAB (COL1,COL2,COL3)VALUES (:VAR1,:VAR2,:VAR3)END-EXEC. -- this is an ANSI SQL comment line* this is a COBOL comment line

Example:

Do not place a comment line within a list of referenced SQL variables.

* this comment line is in the right placeEXEC SQL INSERT INTO TAB (COL1,COL2,COL3)VALUES (

:VAR1,

* this comment line is in the wrong place:VAR2, -- this comment line is in the wrong place:VAR3)

END-EXEC. -- this comment line is in the right place

3.3.2.2 Continuation Lines

COBOL compilers allows to continue words from one line to the next using acontinuation indicator: a hyphen «-» in «indicator area» column.

SQL CMA allows SQL variable names to be split in a SQL statement.

The following declarations are equivalent:

EXEC SQL INSERT INTO TAB (COL1,COL2,COL3)VALUES (:VAR1,:VAR2,:VAR3 ) END-EXEC.

EXEC SQL INSERT INTO TAB (COL1,COL2,COL3)VALUES (:V-AR1, :VA- R2, :VAR-3 ) END-EXEC.

All other keywords (EXEC, SQL, END-EXEC...) in the SQL statement must not becontinued from one line to the next. Otherwise, SQL CMA will not recognize them.


47 A2 01EL 3-11

3.3.2.3 Referencing SQL Arrays of Variables

SQL CMA understands and supports the declaration of arrays of variables. So, itallows the use of array names or elements of an array within SQL statements.

Example:

You declare the following array:

EXEC SQL BEGIN DECLARE SECTION END-EXEC.01 VAR1 PIC X(10) OCCURS 3 TIMES.01 INDEX COMP-1 VALUE 3.

EXEC SQL END DECLARE SECTION END-EXEC.

You can use the following code:

EXEC SQL INSERT INTO TAB (COL1,COL2,COL3)VALUES (:VAR1(1),:VAR1(2),:VAR1(INDEX)) END-EXEC.

You can use the following code:

EXEC SQL INSERT INTO TAB (COL1,COL2,COL3)VALUES (:VAR1 ) END-EXEC.

Subscripts of array elements must not be arrays themselves.

A subscript identifier must be declared in the «DECLARE SECTION» area asshown in the example: INDEX.

Note: The use of subscripted array elements in a SQL CMA sourcecauses the following warning while compiling the generated Serversource:

«Table item not subscripted or indexed, first occurrence assumed.»

You may ignore this compilation warning.


3-12 47 A2 01EL

3.3.2.4 Referencing SQL Elementary Variables

You can declare group items as SQL variables in the «DECLARE SECTION».

You cannot reference group items in SQL statements.

However, you can reference elementary items wherever SQL variables are allowed.

Examples:

You declare the following group items:

EXEC SQL BEGIN DECLARE SECTION END-EXEC.01 VAR1.

02 VAR11 PIC X(2).03 VAR111 PIC X(2).03 VAR112 PIC X(3).

EXEC SQL END DECLARE SECTION END-EXEC.

The following statement is invalid:

EXEC SQL SELECT COL1, COL2INTO :VAR1 FROM TAB1 WHERE....

The following statement is valid:

EXEC SQL SELECT COL1, COL2INTO :VAR111,:VAR112FROM TAB1 WHERE....

Elementary names need not be unique because they can be qualified to avoidambiguity, using the «OF» COBOL clause. For example:

EXEC SQL SELECT COL1, COL2INTO :VAR111 OF VAR11 OF VAR1,

:VAR112 OF VAR11 OF VAR1FROM TAB1 WHERE....

If an elementary item is to be qualified, it must be fully defined up to the highestlevel, even if that would be unnecessary in COBOL .

The next example is valid for COBOL compilers, but invalid for SQL CMA:

EXEC SQL SELECT COL1, COL2INTO :VAR111 OF VAR1,

:VAR112 OF VAR11FROM TAB1 WHERE....


47 A2 01EL 3-13

Do not use the «IN» clause to qualify SQL items because some databaseprecompilers reject it:

EXEC SQL SELECT COL1, COL2INTO :VAR111 IN VAR11 IN VAR1,

:VAR112 IN VAR11 IN VAR1FROM TAB1 WHERE....

In this case, SQL CMA considers the «IN» COBOL keyword as part of the EXECstatement and not part of the referenced SQL variable.

3.4 INCLUDE FILES

A user COBOL source could include other COBOL sources using an «EXEC SQLINCLUDE» preprocessor statement (described later in this chapter) and the«COPY» COBOL command.

The INCLUDE file must get a file format compatible with the calling programformat.

The GCOS 7 COBOL rule is the following:

• CBX file must include CBX files.

• COB file must include COB files.

• DAT or CBL files must include DAT files.

• COBOL compilers ignore the «CARDID» parameter when an INCLUDE file isbeing analyzed.

SQL CMA follows the same rule as the COBOL compilers.

Be careful to include files with a correct COBOL format because an INCLUDE filewith an incorrect format could cause an SQL CMA generation failure.

SQL CMA generates the INCLUDE statements such that:

EXEC SQL INCLUDE <filename> END-EXEC. in user source.

is translated into:

COPY <client_file>. in Generated Clientsource.

EXEC SQL INCLUDE <server_file> END-EXEC. in Generated Serversource.


3-14 47 A2 01EL

COPY <filename>. in user source.

is translated into:

COPY <client_file>. in Generated Client source.

COPY <server_file>. in Generated Server source.

The «EXEC SQL INCLUDE» preprocessor statement is always analyzed by SQLCMA, wherever it is located.

The COBOL COPY statement is analyzed only if it is inserted in the «DECLARESECTION». Otherwise, SQL CMA ignores it.

You must use the «EXEC SQL INCLUDE» statement to include files that containonly SQL statements.

3.4.1 SQLCA INCLUDE FILE

Error reporting is done exclusively through SQLCA structure whatever the value ofthe processing MODE (ANSI or ORACLE).

A user source must include the «SQLCA» SQL file.

You are strongly recommended to use the «EXEC SQL INCLUDE» preprocessorstatement to declare the SQLCA file because the COPY COBOL command needsfull a SQLCA pathname to be declared.

SQL CMA processes the EXEC SQL INCLUDE declaration as follows:

EXEC SQL INCLUDE SQLCA END-EXEC. in user source.

is translated into:

COPY SQLCAORA_<CBX|COB|DAT>. in Generated Client source.

EXEC SQL INCLUDE SQLCA END-EXEC. in Generated Server source.

SQL CMA processes the COBOL COPY command as follows:

COPY SQLCA. in user source.

is translated into:

COPY SQLCAORA_<CBX|COB|DAT>. in Generated Client source.

COPY SQLCA. in Generated Server source.


47 A2 01EL 3-15

3.4.2 ORACA INCLUDE FILE

Oracle ORACA include file is not supported.

3.4.3 ORDINARY INCLUDE FILE

A user source can call INCLUDE files other than the SQLCA file using the «EXECSQL INCLUDE» preprocessor statement or the COPY COBOL command declaredinside the «DECLARE SECTION».

An ordinary INCLUDE filename is an alphanumeric character string (letters anddigits). The special characters ‘-’ or ‘_’ are also allowed to respect the specificity ofGCOS 7 and Windows 2000 filenames.

Dot characters ‘.’ are not allowed in the INCLUDE filename.

SQL CMA processes the EXEC SQL INCLUDE declaration as follows:

EXEC SQL INCLUDE filename END-EXEC. in user source.

is translated into:

COPY cli_filename. in Generated Clientsource.

EXEC SQL INCLUDE svr_filename END-EXEC. in Generated Serversource.

SQL CMA processes the COBOL COPY command as follows:

COPY filename. in user source.

is translated into:

COPY cli_filename. in Generated Client source.

COPY «svr_filename». in Generated Server source.

where «filename» is a simple INCLUDE filename.


3-16 47 A2 01EL

Path names are defined differently on GCOS and Windows 2000. An INCLUDEpathname would not be processed by the SQL CMA Generator unless all thereferenced INCLUDE filenames are present in the «cmainst» Install directory atSQL CMA Source Generation. The SQL CMA Generator scans only this localdirectory.

Note: The SQL CMA Generator does not allow a COBOL program to benested in another COBOL program, i.e. there must be only oneIDENTIFICATION division in the user source analyzed by SQLCMA Generator. So, an INCLUDE file must not include a COBOLprogram with an IDENTIFICATION division.

3.4.4 SQLCA STRUCTURE

After each SQL statement execution, the database kernel returns the OracleSQLCA record filled with error or warning information and other informationrelevant to the nature of the data handled.

A user source must contain the SQLCA record, i.e. it must include the «SQLCA»file provided in the database distribution.

The SQLCA record contents vary depending on the database editor but the SQLCAstructure still contains the following fields:

SQLCODE: Holds the Oracle error code of the executed SQLstatement.

0 The statement ran without error.

>0 (positive) The statement ran, but an exception was generated.100 (when MODE=ANSI) or 1403 (whenMODE=ORACLE) FETCH statement was issued, butno more rows satisfy the SELECT statement criteriaused to define the cursor. No rows were processed.

< 0 (negative) The statement did not run due to an application,database, system, or network error.

SQLERRM: Holds the error message parameter (Text and length).

SQLERRP: Holds internal information.

SQLERRD: Array of six integer status codes (codes not in thefields listed later are reserved).sqlerrd[3] Number of rows affected.sqlerrd[5] Parse error offset.


47 A2 01EL 3-17

SQLWARN: This parameter is an array of 8 elements.They are used as WARNING flags.Each element holds specific information according theSQL statement executed and to the databaseconcerned.

The SQLCA fields are described succinctly here. To get a detailed description ontheir meanings, you must refer to the appropriate database documentation.

As the SQLCA structure is not a constant structure, SQL CMA handles its ownSQLCA record which only holds the constant fields listed previously.

The SQLCA structure is declared in the «SQLCAORA_<CBX|COB|DAT>» files.

That is the reason why a SQLCA INCLUDE statement is translated into a:

«COPY SQLCAORA_<CBX|COB|DAT>»

statement in the generated SQL CMA Client file as detailed in the INCLUDEparagraph.

The SQLCAORA files are provided and must be present on the mainframeenvironment when a SQL CMA Client is to be compiled and linked.

As a generated SQL CMA Client source holds only SQLCAORA fields, it is notpossible for a user source to reference other data specific to a database supplier.


3-18 47 A2 01EL

3.5 SQL CMA APPLICATIONS

A user application including Oracle management capabilities must be written incompliance with the standard Oracle documentation:

• Documentation in line of Oracle database : http://docs.oracle.com

• Net Express documentation for ESQL in COBOL source and OpenESQL.

The following paragraphs describe the restrictions imposed by SQL CMA becauseof some OpenESQL precompiler restrictions or due to SQL CMA limitations.

3.5.1 RESTRICTIONS ON DECLARE STATEMENT

SQL CMA does not support a «DECLARE CURSOR» SQL statement referencingexplicit input or output SQL variables.

3.5.1.1 Declare cursor with input variable

Input SQL variables are given by the user program to the database server to processthe SQL statement: WHERE clause of SQL statements can use input SQLvariables.

When a «DECLARE CURSOR» statement is used to hold a SQL statementdefinition, the SQL statement is parsed and processed further, using the «OPEN»statement. Using SQL CMA, the input variables are transferred to the serverprogram when processing the «DECLARE CURSOR» statement and cannot be re-evaluated on the «OPEN» statement.

Example (Non-supported SQL Sequence):

The following SQL sequence is not supported:

EXEC SQL DECLARE C1 CURSOR FORSELECT ENAME FROM EMP WHERE DEPTNO = :PDEPTNO

END-EXEC.*

EXEC SQL WHENEVER NOT FOUND GO TO CHECK-FETCH END-EXEC.DEPT-LOOP.

DISPLAY "Department Number? " WITH NO ADVANCING.ACCEPT DEPTNON.IF DEPTNON = 0 GO TO EXIT-STOP.MOVE DEPTNON TO PDEPTNO.

*EXEC SQL

OPEN C1END-EXEC.


47 A2 01EL 3-19

FETCH-LOOP.EXEC SQL

FETCH C1 INTO :PENAMEEND-EXEC.GO TO FETCH-LOOP.

CHECK-FETCH.GO TO DEPT-LOOP.

Example (Replacement SQL Sequence):

The previous "non-supported" sequence could be made valid by using thefollowing:

DEPT-LOOP.DISPLAY "Department Number? " WITH NO ADVANCING.ACCEPT DEPTNON.IF DEPTNON = 0 GO TO EXIT-STOP.MOVE DEPTNON TO PDEPTNO.

*EXEC SQL WHENEVER NOT FOUND CONTINUE END-EXEC.EXEC SQL DECLARE C1 CURSOR FOR

SELECT ENAME FROM EMP WHERE DEPTNO = :PDEPTNOEND-EXEC.

*EXEC SQL WHENEVER NOT FOUND GO TO CHECK-FETCH END-EXEC.

*EXEC SQL

OPEN C1END-EXEC.

FETCH-LOOP.EXEC SQL

FETCH C1 INTO :PENAMEEND-EXEC.GO TO FETCH-LOOP.

CHECK-FETCH.GO TO DEPT-LOOP.

The DEPT-LOOP has been moved before the «DECLARE CURSOR» to transferthe new value of PDEPTNO, and an extra WHENEVER … CONTINUE has beenadded before the «DECLARE CURSOR» to overwrite the NOT FOUNDSQLCODE set by the previous FETCH.


3-20 47 A2 01EL

3.5.1.2 Declare cursor with output variable

Output SQL variables are the result of SQL statement processing and their valuesare returned by the server process: SELECT statements use output SQL variables.

When a «DECLARE CURSOR» statement is used to hold a SQL statementdefinition, the SQL statement is parsed and processed further, using the «OPEN»statement.

Currently, SQL CMA is not able to retrieve implicit Output SQL variables.However, SQL CMA supports the dynamic SQL sequence statements: PREPAREand DECLARE which may be used to get round this problem.



EXEC SQL DECLARE CURSOR1 CURSOR FORSELECT COL1, COL2, COL3INTO :VAR1, :VAR2, :VAR3FROM TABLE1WHERE COL1 = ‘A’

END-EXEC.EXEC SQL OPEN CURSOR1 END-EXEC.EXEC SQL FETCH CURSOR1 END-EXEC.


The previous "non-supported" sequence could be made valid by using either of thefollowing:

EXEC SQL DECLARE CURSOR1 CURSOR FORSELECT COL1, COL2, COL3FROM TABLE1WHERE COL1 = ‘A’

END-EXEC.EXEC SQL OPEN CURSOR1 END-EXEC.EXEC SQL FETCH CURSOR1 INTO :VAR1, :VAR2, :VAR3 END-EXEC.

or

EXEC SQL PREPARE PREP1 FROM<<SELECT COL1, COL2, COL3FROM TABLE1WHERE COL1 = ‘A’>>

END-EXEC.EXEC SQL DECLARE CURSOR1 CURSOR FOR PREP1 END-EXEC.EXEC SQL OPEN CURSOR1 END-EXEC.EXEC SQL FETCH CURSOR1 INTO :VAR1, :VAR2, :VAR3 END-EXEC.


47 A2 01EL 3-21

This restriction on the «DECLARE CURSOR» statement is applied only if theoutput SQL variables are referenced inside.

3.5.2 RESTRICTION ON CURSOR OPERATION UNDER TDS

When the connection to the database is done using a logical database identifier ( ATclause), it is mandatory to identify the logical connection on each cursor statement.

This is necessary because SQL CMA maintains a connection cache for TDS andmust identify the connection on each statement.



EXEC SQL CONNECT :USR IDENTIFIED BY :PSWAT :DBID USING :HST

END-EXEC.EXEC SQL AT :DBID PREPARE PREP1 FROM

<<SELECT COL1, COL2, COL3FROM TABLE1WHERE COL1 = ‘A’>>

END-EXEC.EXEC SQL DECLARE CURSOR1 CURSOR FOR PREP1 END-EXEC.EXEC SQL OPEN CURSOR1 END-EXEC.EXEC SQL FETCH CURSOR1 INTO :VAR1, :VAR2, :VAR3 END-EXEC.EXEC SQL CLOSE CURSOR1 END-EXEC.


The previous "non-supported" sequence could be made valid by using thefollowing:

EXEC SQL CONNECT :USR IDENTIFIED BY :PSWAT :DBID USING :HST

END-EXEC.EXEC SQL AT :DBID PREPARE PREP1 FROM

<<SELECT COL1, COL2, COL3FROM TABLE1WHERE COL1 = ‘A’>>

END-EXEC.EXEC SQL AT :DBID DECLARE CURSOR1 CURSOR FOR PREP1 END-EXEC.EXEC SQL AT :DBID OPEN CURSOR1 END-EXEC.EXEC SQL AT :DBID FETCH CURSOR1 INTO :VAR1, :VAR2, :VAR3 END-EXEC.EXEC SQL AT :DBID CLOSE CURSOR1 END-EXEC.


3-22 47 A2 01EL

3.6 SQL CMA TP DESCRIPTION

This section describes the SQL CMA TP mechanism resulting from the use ofspecific SQL commands such as CONNECT, COMMIT and ROLLBACK whichhave specific behavior in the TDS environment.

3.6.1 SQL CMA TP CACHE CONCEPT

3.6.1.1 SQL CMA TP Context Cache definition

To understand the SQL CMA TP Context Cache concept, some definitions areneeded:

Physical Connection is a telecommunication link established between aClient and a Server site. Data is exchanged via this linkaccording to a defined protocol (CMANET in the SQLCMA product).

Database Connection is a link to a remote database between a ClientDatabase application and a Server Database. It isidentified by a unique profile which is composed of theCONNECT action parameters:

− Database identification− Connection name− User/Password clause

Logical Connection is a virtual link mapped on a Physical Connection anda Database connection (previously established by otherCONNECT actions).


47 A2 01EL 3-23

Some SQL CMA terms must be defined:

SQL CMA TP Connection Entry

specifies a Database Connection. Its name is acombination of the CONNECT action parameters.

SQL CMA TP Context is a set of SQL CMA TP Connection Entries. The firstSQL CMA TP Connection Entry has a particularitybecause it is associated with a Physical Connection. Itsname is the same as the first SQL CMA TP ConnectionEntry. A SQL CMA TP Context is associated with aunique TDS commitment unit until it ends.

SQL CMA TP Context Cache

is a set of SQL CMA TP Contexts. Each entry of thistable holds the name of a SQL CMA TP Context. TheSQL CMA TP Context Cache is used by all thecommitment units in the TDS.

These objects are handled inside a TDS commitment unit. The CONNECT actionis analyzed to determine if the connection is a Physical or a Database or a Logicalconnection.

3.6.1.2 SQL CMA TP Context states

A SQL CMA TP Context is associated with a TDS commitment unit.

A SQL CMA TP Context has several states:

UNUSED There are no physical connections, the SQL CMA TPContext is just initialized.

FREE The SQL CMA TP Context is free and may be used bya TDS commitment unit. The SQL CMA TP Contextkeeps a Physical Connection and some DatabaseConnections established between the Client and Serversites.

BUSY The SQL CMA TP Context is already used by a TDScommitment unit and is no longer available for anotherTDS commitment unit. The SQL CMA TP Contextkeeps a Physical Connection and some DatabaseConnections established between the Client and Serversites.


3-24 47 A2 01EL

DAMAGED The SQL CMA TP Context is garbled, so it is declaredunavailable during the execution of the currentcommitment unit. The SQL CMA TP Contextssignaled as DAMAGED are all cleaned (UNUSEDstate) at the end of the commitment unit.

3.6.1.3 Why a SQL CMA TP Context cache?

SQL CMA maintains a cache of SQL CMA TP Contexts to hold the databaseconnections and the cursor parsing. Contexts may be «shared» by several SQLCMA users.

Sharing the contexts saves unnecessary Physical Connections and reduces thenumber of Servers needed to serve the TP application. Consequently, the memoryrequirements and CPU consumption are greatly reduced.

3.6.2 CONNECT ACTION

A CONNECT action is performed when some specific SQL statements are detectedin the SQL CMA TP application.

The CONNECT action, used to log on to the database, must be the first SQLstatement in the TDS commitment unit.

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

3.6.2.1 CONNECT action provided by Oracle

The CONNECT action is started by the following EXEC SQL statements:

EXEC SQLCONNECT <usr> IDENTIFIED BY <psw>[AT <dbid>] [USING <alias>]END-EXEC.

where: < usr >, <psw>, <dbid>, and <alias> are strings of 30 bytes long

To get more details about these SQL statements and their parameters, refer to thestandard «Programmer’s Guide to the Oracle Precompilers» manual.

The "EXEC SQL CONNECT" statement is the only one allowed to establish aconnect with an Oracle database.


47 A2 01EL 3-25

3.6.2.2 Relationship between CONNECT action and SQL CMA TP Context

The CONNECT action handles the SQL CMA TP Context Cache as follows:

First CONNECT Action in a TDS Commitment Unit:

When the first CONNECT action is detected in a TDS commitment unit:

1. The Context Cache Manager searches a SQL CMA TP Context signaled asFREE to get a Physical connection established previously. It must also find aSQL CMA TP Context whose name maps the current CONNECT parameters.

If a SQL CMA TP Context is found, this context will be used by the TDScommitment unit until it ends, so the context is declared BUSY.

If no SQL CMA TP Context is found, a SQL CMA TP Context Cache entrysignaled as UNUSED is reserved. Then, a new SQL CMA TP Context iscreated, identified by the current CONNECT parameters.

2. A Physical Connection is established between the Client and Server sites.

3. A SQL CONNECT order is sent to the remote Server.

4. A SQL CMA TP Connection entry is created in the SQL CMA TP Context ifthe Database Connection succeeds.

5. The new SQL CMA TP Context is declared BUSY.

Next EXEC SQL CONNECT in the TDS Commitment Unit:

1. The Context Cache Manager gets the SQL CMA TP Context allocated by thefirst CONNECT action in the TDS commitment unit.

2. The SQL CMA TP Connection entries associated with the current SQL CMATP Context are scanned to check if a Database Connection is not alreadyestablished.

3. A SQL CONNECT order is sent if the current CONNECT action is notalready done. Then, a SQL CMA TP Connection entry is created and added tothe SQL CMA TP Context.

This algorithm will be applied for each TDS commitment unit.


3-26 47 A2 01EL

3.6.2.3 CONNECT action errors

If a SQL CMA TP Connection Entry could not be created, all the other SQL CMATP Connection Entries of the current SQL CMA TP Context are removed, i.e. theirstates are declared FREE. The SQL CMA TP Context is declared FREE too.

An error message is returned to inform the SQL CMA application.

If the SQL CMA TP Context Cache is full, an error message is returned to informthe SQL CMA TP application.

3.6.3 COMMITMENTS

When a SQL CMA TP application runs in the TDS environment, all commitmentsunits are handled by TDS (as far as possible).

SQL CMA TP defines some main rules to handle the commitment:

• The commitment of a database is deferred to the end of the commitmentunit regardless of where a commit request appears in the code.

• If only one database is accessed inside a commitment unit (whether itincludes a SQL COMMIT statement or not), this database is reallycommitted at the end of the commitment unit.

• If several databases are accessed inside the commitment unit, then:

− If no SQL COMMIT statement is present in the commitment unit:

The last database referenced just before the end of the commitment unitis really committed at the end of the commitment unit. All otherdatabases referenced during the commitment unit execution are rolledback.

− Some SQL COMMIT statements are present in the commitment unit:

Only the first SQL COMMIT statement is taken into account.

The database referenced just before the first SQL COMMIT statement isreally committed at the end of the commitment unit. All other databasesreferenced during the commitment unit execution are rolled back.

These rules are applied if no error has occurred.

WARNING

As "EXEC SQL COMMIT" statement execution is deferred to the end ofTPR, the syntax errors are not detected for that statement.


47 A2 01EL 3-27

3.6.4 COMMIT ACTION

A COMMIT action is used to commit all modifications made to the databaseduring a commitment unit execution.

SQL CMA TP imposes the commitment to be done at the end of a commitmentunit. A commitment may be implicit or explicit.

A commitment is explicit when a specific function or a SQL statement is detectedin the SQL CMA TP application.

3.6.4.1 Implicit commitment

Even if no explicit commitment is specified, an implicit commitment is performedat the end of the commitment unit.

The last database referenced just before the end of the commitment unit is reallycommitted. The other databases are rolled back.

3.6.4.2 Explicit commitment

An explicit commitment can be caused by a call to the TDS «DFCMIT» procedureor by inserting a SQL COMMIT statement in the SQL CMA TP application.

The TDS «DFCMIT» procedure acts according to the TDS rules, i.e. the lastdatabase referenced just before the end of the commitment unit is really committedand the others are rolled back.

The SQL COMMIT action differs from the «DFCMIT» action because thedatabase really committed is the database explicitly referenced by the SQLCOMMIT statement.

Only the first SQL COMMIT statement is analyzed. All other SQL COMMITstatements are ignored.

3.6.4.3 SQL COMMIT statement

A COMMIT action is required when the following SQL statement is inserted:

EXEC SQL [AT <dbid>] COMMIT WORK END-EXEC.

To get more details about this SQL statement, refer to the standard manual«Programmer’s Guide to the Oracle Precompilers».


3-28 47 A2 01EL

3.6.4.4 Examples of COMMIT actions

Here are examples of different commitment actions.

The following commitment units update two Oracle databases: DB1 and DB2.

Example 1: Commitment using ‘DFCMIT’

IDENTIFICATION DIVISIONPROGRAM-ID. XXX....EXEC SQL CONNECT … AT DB1 USING … END-EXEC....EXEC SQL CONNECT … AT DB2 USING … END-EXEC....EXEC SQL AT DB1 INSERT INTO T1 VALUES (100) END-EXEC....EXEC SQL AT DB2 INSERT INTO T2 VALUES (100) END-EXEC....CALL ‘DFCMIT’....EXIT.

At the end of the commitment unit, only the DB2 database is really committedbecause it is the last database referenced before the end of the commitment unit.The DB1 database is rolled back and the corresponding INSERT is lost.

Example 2: Commitment using ‘SQL COMMIT’

IDENTIFICATION DIVISIONPROGRAM-ID. XXX....EXEC SQL CONNECT … AT DB1 USING … END-EXEC....EXEC SQL CONNECT … AT DB2 USING … END-EXEC....EXEC SQL AT DB1 INSERT INTO T1 VALUES (100) END-EXEC....EXEC SQL AT DB2 INSERT INTO T2 VALUES (100) END-EXEC....EXEC SQL AT DB1 COMMIT WORK END-EXEC....EXIT.

At the end of the commitment unit, only the DB1 database is really committedbecause it is explicitly referenced on the SQL COMMIT statement. The DB2database is rolled back and the corresponding INSERT is lost.


47 A2 01EL 3-29

Example 3: Commitment using several ‘SQL COMMIT’

IDENTIFICATION DIVISIONPROGRAM-ID. XXX....EXEC SQL CONNECT … AT DB1 USING … END-EXEC....EXEC SQL CONNECT … AT DB2 USING … END-EXEC....EXEC SQL AT DB1 INSERT INTO T1 VALUES (100) END-EXEC....EXEC SQL AT DB1 COMMIT WORK END-EXEC....EXEC SQL AT DB2 INSERT INTO T2 VALUES (100) END-EXEC.EXEC SQL AT DB2 COMMIT WORK END-EXEC....EXIT.

At the end of the commitment unit, only the DB1 database is really committedbecause it is the first database explicitly referenced by a SQL COMMIT statement.The DB2 database is rolled back and the corresponding INSERT is lost accordingto the SQL CMA TP rules.

3.6.4.5 Automatic restart

The automatic restart facility is activated when a commitment fails.

The TDS monitor cannot report synchronously a commitment failure to a SQLCMA TP application, so a restart is necessary to know the commitment status.

When the commitment unit restarts, SQL CMA TP asks for the commitment statuson the first SQL statement (which is a CONNECT action). So, the automatic restartnormally relative to a COMMIT action could disturb a CONNECT action.


3-30 47 A2 01EL

3.6.4.6 Relationship between COMMIT action and SQL CMA TP context

At the end of a commitment unit, SQL CMA TP performs several actions:

1. COMMIT one database according to the SQL CMA TP rules.

A SQL COMMIT statement is sent to the appropriate database and the SQLreturn status is analyzed. The current SQL CMA TP context is set to FREE.

2. ROLLBACK all other databases referenced in the SQL CMA TP application.

A SQL ROLLBACK statement is sent to the different databases and the SQLreturn statuses are analyzed.A wrong return status causes a physical telecommunication disconnection andthe current SQL CMA TP Context is set to UNUSED.

If the SQL COMMIT statement returns a garbled status or no response is receivedfrom the remote database, the automatic restart is activated.

3.6.5 ROLLBACK ACTION

Unlike the COMMIT action, a ROLLBACK action is always synchronouslyexecuted, i.e. it is not deferred to the end of the commitment unit.

A ROLLBACK action cancels a transaction and undoes any changes that occurredsince the beginning of the commitment unit.

A ROLLBACK action affects only the current database.

The ROLLBACK action does not affect the processing of the SQL CMA TPapplication, and has no effect of the other referenced databases.

3.6.5.1 ROLLBACK statement provided by Oracle

A ROLLBACK action is required when inserting the following SQL statement:

EXEC SQL [AT <dbid>] ROLLBACK [WORK] END-EXEC.

To get more details about this SQL statement, refer to the standard «Programmer’sGuide to the Oracle Precompilers» manual.


47 A2 01EL 3-31

3.6.5.2 Examples of ROLLBACK actions

Below are examples of different ROLLBACK actions.

Example 1: ROLLBACK action on one database

IDENTIFICATION DIVISIONPROGRAM-ID. XXX....EXEC SQL CONNECT … USING … END-EXEC....EXEC SQL INSERT INTO T1 VALUES (100) END-EXEC....EXEC SQL ROLLBACK WORK END-EXEC....EXEC SQL INSERT INTO T2 VALUES (100) END-EXEC....EXEC SQL COMMIT WORK END-EXEC....EXIT.

The ROLLBACK statement is executed synchronously, so the first INSERTstatement is immediately rolled back.

The processing of the TPR continues; the second INSERT statement is executed,the SQL COMMIT statement is detected.

Finally, the second INSERT is committed at the end of the commitment unit.

Example 2: ROLLBACK action when two databases are referenced

IDENTIFICATION DIVISIONPROGRAM-ID. XXX....EXEC SQL CONNECT … AT DB1 USING … END-EXEC....EXEC SQL CONNECT … AT DB2 USING … END-EXEC....EXEC SQL AT DB1 INSERT INTO T1 VALUES (100) END-EXEC....EXEC SQL AT DB2 INSERT INTO T2 VALUES (100) END-EXEC....EXEC SQL AT DB2 ROLLBACK WORK END-EXEC....EXEC SQL AT DB1 COMMIT WORK END-EXEC....EXIT.

When the ROLLBACK statement is executed, the INSERT statement executed onthe DB2 database is immediately rolled back.


3-32 47 A2 01EL

The processing of the TPR continues. The SQL COMMIT statement is detected.Finally, the INSERT action on the DB1 database is committed at the end of thecommitment unit.

3.6.5.3 Relationship between ROLLBACK action and SQL CMA TP context

A ROLLBACK statement has no effect on the current SQL CMA TP context.

3.7 SQL CMA TP ERRORS

SQL CMA TP errors are returned in the SQLCODE variable that must be checkedto take appropriate actions.

Most of errors cannot cause data inconsistency in the database, but some errors (theerrors -5 and -6) must be handled carefully and an appropriate error treatmentcould be an abort of the current transaction.

However, if such an error occurs in a commitment unit where database changeshave been deferred, you must save all the critical data in a secure area such as theTRANSACTION-STORAGE.

Alternatively, you can undo the changes performed in the previous commitmentunit. To do this, all the data necessary to undo these changes must have been savedin a secure area and the previous commitment unit has to move them intoTRANSACTION-STORAGE.

47 A2 01EL 4-1

4. SQL CMA Installer

This chapter explains how to build the SQL CMA sources and how to generate theSQL CMA executable in the appropriate environments: Mainframe and Windows2000.

A SQL CMA Installer (cmainst.exe) is provided on Windows 2000 to administerSQL CMA. This consists of generating the SQL CMA sources, and building theSQL CMA Server executable on Windows 2000.

The SQL CMA Client executable is built in the mainframe environment. Thisoperation is not processed by the SQL CMA Installer.

Building the SQL CMA Server requires the Oracle 8i or 9i Client software to beinstalled (Pro*Cobol component), Merant/Micro Focus Net Express COBOLcompiler to be installed (it uses the COBOL compiler, cbllink and cobol runtime)and also a C compiler (Visual C++ version 6.0, option standard)

This section details the steps necessary to get the SQL CMA Installer up andrunning, and how to process the following actions:

• Starting SQL CMA Installer

• Starting SQL CMA Source generation

• Starting SQL CMA Server building


4-2 47 A2 01EL

4.1 PREREQUISITES

4.1.1 ORACLE PRODUCT

At least the Client software is required : if not, a warning message is sent duringthe SQL CMA installation (InstallShield).

Oracle Pro*COBOL is necessary for SQL CMA source generation phase, andOracle runtime client libraries are necessary for execution phase.

If the TDS mode is used, a specific table CMATP must be created on each database(it is used via ESQL in the TDS application).You may use the file ORA-CMATP.sql (delivered in the directory “C:\ProgramFiles\Bull\SQL-CMA\Cmagen”).

4.1.2 MERANT/MICRO FOCUS PRODUCT

This product is required : if not, a warning message is sent during the SQL CMAinstallation (InstallShield).

COBOL compiler is used for SQL CMA sever building phase, and COBOLruntime library is necessary for execution phase.

4.1.3 C COMPILER PRODUCT

A Visual C++ Compiler version 6.0 must be installed with the option “REGISTERENVIRONMENT VARIABLE” and with update of the environment variables (lib,include, path). It is used during SQL CMA server building phase.

4.1.4 SQL CMA PRODUCT

Install shield proposes to download the CMA product in the directory “C:\ProgramFiles\Bull\SQL-CMA” : you may choose another directory.

If the CMA product is downloaded on the directory “C:\Program Files\Bull\SQL-CMA”, Install shield builds a specific environment variable CMA_HOME_SQLwith the value “C:\Program Files\Bull\SQL-CMA\Cmanet\CmaExec”.

If default value, the executable cmainst.exe is in the directory “C:\ProgramFiles\Bull\SQL-CMA\Cmagen”. Install Shield builds a shortcut named “CMAinst”in “Start -> Programs ->SQL-CMA”.

SQL CMA Installer

47 A2 01EL 4-3

4.2 STARTING SQL CMA CMAINST PRODUCT

Figure 4-1. Starting SQL CMA CMAINST Product

You may also open a Windows command processor, use the CHDIR Command togo in the “C:\Program Files\Bull\SQL-CMA\Cmagen” directory and type cmainst

The product cmainst will start a Graphical User Interface to generate sources andbuild server executable.


4-4 47 A2 01EL

4.2.1 INTERACTIVE PROGRAM CMAINST

Figure 4-2. Interactive Program CMAINST

The SQL CMA Installer is an interactive program that provides the ability to:

• Generate SQL CMA Client and Server sources from a user application

• Build the SQL CMA Server executable, ready to be started on Windows 2000.

These actions can be performed by selecting the right options proposed on the mainscreen. Each SQL CMA option :

• propose a working directory “C:\Program Files\Bull\SQL-CMA\Cmagen\work”This directory contains some samples.It is possible to use another directory for your working directory (during cmainstexecution). You will copy your input files (sources *.pco) in it and get youroutput files (client files, server executable,…) in it.

• Propose a logfile directory

• collects its own input parameters by displaying some request screens

A SQL CMA operation could be canceled by entering the specific key, as indicatedat the top of the current screen. This causes a return to the main screen.

SQL CMA Installer

47 A2 01EL 4-5

4.3 STARTING SQL CMA SOURCE GENERATION

First you must transfer GCOS7 COBOL user sources from DPS7000 to Windows2000 (Refer to paragraph 4.3.1 for Windows 2000 source name syntax).

From a user program, the SQL CMA Source generation launch :

1. cmag-Oracle.exe to build two output programs:

• a SQL CMA GCOS7 COBOL client program

• a SQL CMA Pro*COBOL server program.

2. Oracle Pro*COBOL precompiler to build:

• a SQL CMA Merant COBOL server program.

Each user program is characterized by several parameters such as:

• The DATABASE to access: Oracle database

• The programming LANGUAGE: COBOL

• The application running mode: BATCH or TP

These input parameters are required by the SQL CMA generator to build the SQLCMA sources.

The generated SQL CMA sources are built locally in the «cmainst» directory. Theymust stay there, if a SQL CMA server building operation is to be performed later.

The SQL CMA Source Generation proposes a recapitulative screen before startingthe requested operation.

The screen relative to the SQL CMA source generation needs the followingparameters to be input in order to find out the user program characteristics.


4-6 47 A2 01EL

Figure 4-3. Starting SQL CMA Source Generation

4.3.1 «LIST NAME» AND «SOURCES NAME(S)» PARAMETERS

The SQL CMA source generator needs the SQL CMA source name as input.

A source name is a character string which contains neither the «-» nor the «_»characters. These specific characters cause COBOL compiling errors.

The Source name syntax allowed by the SQL CMA Installer is Prog.pco

For ease of use, the SQL CMA Installer accepts a list of source names to beentered. Instead of a list, you can give a «file of SOURCE list» containing thenames of the SQL CMA Source to generate : this list should be a text file withsuffix “.txt”. Each line defines a name of a SQL CMA Source as shown hereafter:

SQL CMA Installer

47 A2 01EL 4-7

File of SOURCE List for Oracle (Mylist.txt)

prog1.pcoprog2.pcoprog3.pcoprog4.pco

With the browse button, you may change select input file or input list in anydirectory : the current working directory is updated.

No File of SOURCE List

If no «file of SOURCE list» is provided, a message “** You must give input LISTor SOURCE NAME(s)” is sent and the window «SOURCE GENERATION » issent again .

The SQL CMA Installer stores the list of the source names and performs a separategeneration of each source name. This method avoids calling the SQL CMAgeneration screen each time a user source is to be analyzed.

4.3.2 «ORACLE SETTINGS» PARAMETERS

Format

Select the GCOS7 Cobol format of the Source(s). Refer to chapter 3 forexplanations.

SQL mode

Select the SQL Mode. It can be ANSI (ROW NOT FOUND SQLCODE equals+100) or ORACLE (ROW NOT FOUND SQLCODE equals +1403).

ProCobol precompiler option string

Specify here yours specific Pro*COBOL options.

Some useful options are:

picx = charf | varchar2 varchar2 is Oracle7 precompilerbehaviour

sqlcheck = syntax | semantics | full required for embedded PL/SQL

userid = user/password@alias required for embedded PL/SQL

unsafe_null = no | yes yes allows fetching null without variableindicator


4-8 47 A2 01EL

Refer to «Programmer’s Guide to the Oracle Precompilers» documentation for allavailable options.

4.3.3 «APPLICATION RUNNING IN» PARAMETER

This parameter indicates the running mode of the user application to the SQL CMAGenerator, either:

• BATCH mode, or

• Transactional environment (TP).

This parameter causes the SQL CMA Generator to insert specific sequencesperforming the Connection Cache handling in the SQL CMA Client source. Thesesequences call a succession of CMATP functions.

If the user gives a list of user source names to be translated, the «ApplicationRunning in» parameter is applied to all the source names of the list. This meansthat if the TP parameter is chosen, all the user sources listed during this phase willbe generated with TP sequences inserted in their code.

During the Installshield phase, you must choose the default value (TP or BATCH)used in the CMAinst. This option is stored in a file named “CmainstOptions.txt” inthe CmaGen directory, and may be modified after the installation.

4.3.4 «DEBUG MODE» PARAMETER

This parameter is useful to get a detailed reporting during the Source generationsteps.

The DEBUG options are fully explained in the «DEBUG option» paragraph inChapter 2.

When the DEBUG mode is selected, all the possible DEBUG options aredisplayed:

• Lexical Analysis Debug

• Symbol Table Debug

• Symbol Research Debug

The default value for this parameter is NO DEBUG.

SQL CMA Installer

47 A2 01EL 4-9

4.3.5 «LOGGING FILE NAME» PARAMETER

This Logging file provides a record of the SQL CMA Source Generation process. Itlists any errors issued at installation time.

To get an accurate and comprehensive tracking of an Installation failure, refer tothe Logging file.

During a SQL CMA source generation, the following steps are performed by theInstaller:

1. Analyze the Input parameters.

2. Generate the SQL CMA Client and Server sources with their include files.

By default, the logging file is named «<TEMP>1\cmainst.log».

If desired, you can choose another logging file name or directory.

4.3.6 VALIDATION OF SOURCES TO GENERATE

The following request allows the user to validate the input parameters beforestarting the SQL CMA Source Generation.

A final screen is displayed to summarize the Source characteristics, whose nameshave been previously entered, as follows:

SOURCE to proceed: xxx.pco

Access to << ORACLE>> Database.COBOL Language with CBX format.

Running in <<TP>> mode.

No DEBUG mode during the source generation.

You may accept (OK) or invalidate (CANCEL).

1 <TEMP> is the value of the environment variable “TEMP”


4-10 47 A2 01EL

4.4 STARTING SQL CMA SERVER BUILDING

The SQL CMA Installer builds a SQL CMA Server executable ready to be startedon Windows 2000.

To build the Server executable it performs the following steps:

• retrieve the includes files (cmabuf.h,cmacst.h, dllCMANET.h), the copy cobolfile (CMA_H.CPY) and the source file cmasvr.c in the directory“C:\ProgramFiles\Bull\SQL-CMA\Cmagen\INCLUDE”

• retrieve the library file dllCMANET.lib in the directory “C:\ProgramFiles\Bull\SQL-CMA\Cmagen\lib”

• Merant/Micro Focus COBOL phase : compile the generated SQL CMA serverprogram(s) (COBOL source) specified by the user

• Merant/Micro Focus cbllink phase : link the generated SQL CMA server objectsin a xx_Cobol.dll (if SERVER BINARY NAME = xx)

• Visual C++ compiler cl phase : compile the CMANET sources (cmasvr.c) . Ituses an include file which depends on the user application

• Visual C++ link phase : link the cmasvr.obj with the dllCMANET library, theuser xx_Cobol.lib and the specific database libraries to get an executable

This assumes that, at least, an Oracle Client environment (libraries, include files,...) is installed locally and is accessible from the SQL CMA Installer.

The SQL CMA Server building is characterized by several parameters such as:

• The name of the application server that will be started on Windows 2000.

• The list of the SQL CMA server objects that compose the executable.

• The application running mode: BATCH or TP.

These parameters are necessary for the SQL CMA Installer to be able to build theSQL CMA Server executable.

SQL CMA Installer

47 A2 01EL 4-11

Figure 4-4. Starting SQL CMA Server Building

To identify the SQL CMA Server components, the SQL CMA Server buildingscreen needs the following parameters to be input.

4.4.1 «SERVER BINARY NAME» PARAMETER

This parameter identifies the SQL CMA Server program which will be started onWindows 2000 in order to communicate with the SQL CMA Client programrunning on the mainframe. This program will process SQL statements whenrequested by the SQL CMA Client program through CMANET messages.

The SQL CMA Client and Server programs share information statically (SQLCMA tables are inserted during the SQL CMA Source generation) to provide SQLCMA working integrity. This ensures that a SQL CMA Client is not


4-12 47 A2 01EL

communicating with a SQL CMA Server issued from another SQL CMAgeneration.

The «SERVER BINARY NAME» parameter is exchanged at connection timebetween the SQL CMA Client and its respective SQL CMA Server to ensure thateach one accesses. This parameter is a string limited to 20 characters maximum.

4.4.2 «LIST NAME» AND «SOURCE NAME(S)» PARAMETERS

During the SQL CMA Server building, the SQL CMA Installer needs the SQLCMA source name. The radix of «file1.pco» is «file1».

From the input radix, the SQL CMA Installer reconstitutes the SQL CMA Clientincluding the filename (<radix>cli_h) and extracts SQL CMA information insertedpreviously (during the SQL CMA generation of the user source).

The SQL CMA Installer is able to restore the filenames of all the generated SQLCMA sources.

All the generated SQL CMA sources (Include and code files) must be located in thecurrent working directory.

To improve ease of use, the SQL CMA Installer accepts a list of files to be entered,for example mylist.txt.

The list of files could be entered differently such as:

• A «file of SOURCE list» containing the names of the SQL CMA Source to link.Each line defines a name of a SQL CMA Source as follows:

prog1.pcoprog2.pco

• The «file of SOURCE list» may be the same as the one provided during the SQLCMA source Generation .

• If no «file of SOURCE list» is provided, a message “** You must give inputLIST or SOURCE NAME(s)” is sent and the window «SERVER BUILDING »is sent again .

The SQL CMA Installer does not accept the same file name to be defined twice.

The object files listed on this request, will be linked with the dllCMANET and thedatabase libraries to get an executable, running on Windows 2000, whose name isdefined by the «SERVER BINARY NAME» parameter.

In TP mode, you must specify all SQL CMA sources for a given TDS. That is, youmust have one Server Binary Executable by TDS application.

SQL CMA Installer

47 A2 01EL 4-13

4.4.3 «APPLICATION RUNNING IN» PARAMETER

This parameter indicates the running mode of the user application to the SQL CMAGenerator. The modes are:

• BATCH mode,

• Transactional environment (TP).

This parameter is used to insert specific SQL CMA information to enable the SQLCMA Client and Server processes to communicate with each other.

The Default value for this parameter is selected at installation time and may bemodified (refer to paragraph 4.3.3 «Application running in» parameter).

4.4.4 «LOGGING FILE NAME» PARAMETER

This Logging file provides a record of the SQL CMA Server building process. Itincludes a list of any errors issued at installation time.

To get an accurate and comprehensive tracking of an Installation failure, refer tothe Logging file.

During a SQL CMA Server building, the following steps are performed by theInstaller:

1. Analyze the Input parameters,

2. Check the current database environment,

3. Update the include files,

4. Compile some specific SQL CMA files. (Some CMANET files are dependentof the user application),

5. Link the Server executable.

By default, the logging file is named «<TEMP>1\cmainst.log». If desired, you canchoose another logging file name or directory.

1 <TEMP> is the value of the environment variable “TEMP”


4-14 47 A2 01EL

4.5 FINAL REPORT OF SQL CMA INSTALLER

The SQL CMA Installer returns status information relative both to the Installerprocessing and to the SQL CMA action required.

At the end of the Installer processing, the following status indicates whether thecurrent SQL CMA request has been performed successfully or has failed:

SQL CMA SOURCE generation has been processed/failed.Refer to «Logging_file» to get status information.

SQL CMA «xxxx» SERVER building generation has been processed/failed.Refer to «Logging_file» to get status information.

The added message informs the user about CMAGEN errors, issued at SQL CMAsource generation. The user can refer to the SQL CMA generator Log file to getmore details about the errors (in order to fix them).

Some SQL CMA errors have been logged in «C:\WINNT\Temp\cmagen.log»

When the server building is successful, this message is sent:

>>> You have to transfer this executable xxxxx.exe and the dllxxxxx_Cobol.dll in the directory set by the Environment VariableCMA_HOME_SQL

SQL CMA Installer

47 A2 01EL 4-15

4.6 SQL CMA INSTALLER ERRORS

*** CMAINST: Server Name «xxx» is too long (20 characters max).

Cause:

The name of the Server, running on Windows 2000, has a length limited to 20characters.

Action:

Choose a shorter name to identify the Server executable.

*** CMAINST: Source name ‘xxx’ has forbidden characters (’-’ or ’_’).

Cause:

To bypass the specific language rules and to get a universal solution, the CMAInstaller rejects a source name including either of the two special characters ‘-’ or‘_’.

Action:

Enter a user source name which respects the previous syntax restriction.

*** CMAINST: Problems to start SQL CMA Generator: cmag-Oracle

Cause:

This error message indicates that the SQL CMA generators invoked in the errormessage could not be started successfully.

Action:

Check that the SQL CMA Generator executable is accessible to the system(Pathname declared correctly).


4-16 47 A2 01EL

*** CMAINST: Source list file ‘xxx’ could not be opened.

Cause:

The input source list file «xxx» could not be found and opened.

Action:

Check the input list file name (pathname and file name).

To get information about the syntactic rules, refer to Chapter 4.

*** CMAINST: Source file ‘xxx’ could not be opened.

Cause:

The input source file «xxx» could not be found and opened.

Action:

Check the input source name value (pathname and source name).

To get information about the syntactic rules, refer to Chapter 4.

*** CMAINST: The object file ‘xxx’ must be unique in the link list.

Cause:

The SQL CMA Server building needs the list of user filenames that compose theSQL CMA server executable. The same filename must not be redefined twice inone list.

Action:

Change the duplicate filename.

*** CMAINST: Source Suffix ‘xxx’ is not allowed.

Cause:

The SQL CMA Installer recognizes only the standard suffix “.pco” to identify auser application.

Action:

Enter a user source name correctly suffixed according to the type of database.

SQL CMA Installer

47 A2 01EL 4-17

*** CMAINST: Include file ‘xxxcli_h’ could not be opened.

Cause:

To find the source suffix that identifies the Database and Language characteristics,the SQL CMA Installer uses information stored in the SQL CMA Client includefile «xxxcli_h». This file must be located in the «cmainst» current directory.

This error message indicates that the SQL CMA Client include file could not befound and opened.

Action:

If the «xxxcli_h» include file has been moved, you can transfer it manually to the«cmainst» directory with the correct access rights. Otherwise, to remove thisanomaly, you must perform a new SQL CMA generation of the «xxx» source file.

*** CMAINST: Include file ‘xxxcli_h’ could not be read.

Cause:

To find out the source suffix that identifies the Database and Languagecharacteristics, the SQL CMA Installer uses information stored in the SQL CMAClient include file «xxxcli_h». This file must be located in the «cmainst» currentdirectory.

This error message indicates that the SQL CMA Client include file could not beread.

Action:

Check the read access rights of the «xxxcli_h» include file.

*** CMAINST: Include file ‘xxxcli_h’ has not a right header.

Cause:

To determine the source suffix that identifies the Database and Languagecharacteristics, the SQL CMA Installer uses information stored in the SQL CMAClient include file «xxxcli_h». This file must be located in the «cmainst» currentdirectory.

This error message indicates that this hidden information is garbled.


4-18 47 A2 01EL

Action:

To correct this anomaly, you need to perform a new SQL CMA generation of the«xxx» source file.

The following Error messages are internal messages. If you get one of them,contact your support team representative to fix the problem.

*** CMAINST; Input file not found.

*** CMAINST: Input information is garbled.

*** CMAINST: Input file already defined.

*** CMAINST: Server name not defined.

*** CMAINST: Server Name already defined.

*** CMAINST: Server file not found.

*** CMAINST: Server Include file not found.

*** CMAINST: Client Include file not found.

*** CMAINST: Action parameter is not defined.

*** CMAINST: Action already defined.

47 A2 01EL 5-1

5. Enable CMANET Communication

This chapter explains how to enable the SQL CMA processes communicationbetween the client mainframe and the Windows 2000 server.

The SQL CMA processes communicate with each other according to theClient/Server as follows:

• A SQL CMA Service (CMAservice.exe) is started on Windows 2000 to listen forincoming Client connections across the network,

• A SQL CMA Client running on the mainframe sends a connection request to theSQL CMA Service through a common telecommunications port,

• After the telecommunications link is established, the SQL CMA service startsthe appropriate SQL CMA Server process and directs the Client requests to thisnew process,

• The SQL CMA Client can now exchange messages via the CMANET layer, withthe SQL CMA Server process running on Windows 2000.

So that the SQL CMA processes communicate one with the other, acommunications protocol is necessary for one node to transfer information toanother.

The SQL CMA communications interface CMANET is based on the standardtelecommunications protocol TCP/IP.

The following paragraphs describe the steps necessary to get the SQL CMAprocesses up and running:

• Starting SQL CMA Service

• Starting and stopping optional CMA Listener


5-2 47 A2 01EL

5.1 CONFIGURING THE MACHINES

The mainframe and the Windows 2000 server, that are involved in the network,must be configured to communicate as a TCP/IP client or server.

Refer to the TCP/IP documentation, available on each system, to perform theappropriate configuration tasks.

The following parameters are necessary to get the SQL CMA processes up andrunning:

• A TCP/IP port number (default is 9007) 1

• The name of the Windows 2000 Server machine, relevant for the client site.

5.2 STARTING SQL CMAservice

SQL CMA provides a Windows 2000 service named “CMAservice”, executable«CMAservice.exe», which is supplied in the CMANET module, path<CMA>\CmaNet2

This CMAservice can be started at the end of the installation with startup type =automatic. You should stop, or start it with the services administrative tool(Settings -> Control Panel -> Administrative tools -> Services)

Another SQL CMA listener could be run simultaneously on the same Windows2000 server, in order to debug new applications without impact on the productionapplications : refer to paragraph 5.2.3 for more information

5.2.1 ENVIRONMENT VARIABLE CMA_HOME_SQL

After all the SQL CMA operations such as Source Generation and Server buildinghave been completed, a SQL CMA application server is generated in the currentworking directory. This process has been described in the previous chapters.

These server executables (demo.exe and demo_Cobol.dll if “server binary name” =demo) may be transferred anywhere. However, the SQL CMA service (or listener)must know their location to be able to start them.

1 Install Shield updates the file etc/services with the port 9007 (if no line found with string cmaserver)

2 . <CMA> is the directory used by Install Shield (default is “C:\Program Files\Bull\SQL-CMA”)

Enable CMANET Communication

47 A2 01EL 5-3

The SQL CMA Service (or listener) use CMA_HOME_SQL : default value ( setby Install Shield) is <CMA>\CmaNet\CmaExec. This variable specifies the fullpathname where all the SQL CMA Servers and the file dllCMANET.dll are located.

5.2.2 CMASERVICE IN DEBUG MODE : FILE “CMADEBUG.TXT”

CMAservice is launched when the Windows 2000 starts (service with startup type= automatic) and uses the port corresponding to cmaserver in the file etc/services(default is 9007).

CMAservice adds some information in the event log (application log).You may read these informations with the event viewer,Start-> Control panel -> Administrative tools -> Event viewer.

If you need some trace information (debug mode), you have to update the fileCMAdebug.txt found in the directory <CMA>\CmaNet\CmaExec3.

The initial file CMAdebug.txt contains the line “ DEBUG=NO”.

If you change this line (with any editor such as notepad) to “debug = YES”,

• you will get trace information in the file <TEMP>4\CMAservice.log

• your CMA applications will be launched in debug mode : all the send andreceive buffers will be dumped in a file cmasql_<pid>.log, where <pid> is thepid of your CMA application

This file is read when the CMAservice is launched and on every connect action(before starting any application).This debug option reduces the performance.

Refer to paragraph 5.3 for more information.

3 <CMA> is the directory used by Install Shield (default is “C:\Program Files\Bull\SQL-CMA”)

4 <TEMP> is the value of the system environment variable “TEMP”


5-4 47 A2 01EL

5.2.3 STARTING OPTIONAL CMALISTENER

When a second listener is used, the administrator must start it on the Windows2000 system.

Install Shield adds shortcuts for the product SQL-CMA (CMAinst andCmaOptionalListener) in START -> PROGRAMS -> SQL-CMA. You may addany parameters to the shortcut CmaOptionalListener (change properties ->target "C:\Program Files\Bull\SQL-CMA\Cmanet\CMAlistener.exe" debug port=6349)

The complete syntax to start the SQL CMA Listener is:

CMAlistener [debug] [port=<port_number or service_name>]

where:

debug Optional parameter to enable «CMAlistener» to run inDEBUG mode. The DEBUG messages are logged inthe appropriate log file.

port= <port_number or service_name>

TCP/IP parameter to specify on which you want tostart «CMAlistener».

The TCP/IP driver needs a parameter named «port number» to know where aprocess connects. The optional input parameter «port=» could be specified as anumber or as a character string:

port=<number> indicates the TCP/IP port number on which«CMAlistener» listens.

port=<string> is a service name defined in the TCP/IP configurationfile:C:\WINNT\system32\drivers\etc\services asfollows:<string> 1000/tcp

no port is defined: The service name «cmaserver» must be declared inC:\WINNT\system32\drivers\etc\services asfollows:cmaserver 9007/tcp (only if the CMAservice is notalready running)

If no port is defined and that the service name «cmaserver» is unknown,the SQL CMA Listener issues the error message: “*** CMAlistener: SERVICES file lookup failure forservice=cmaserver (error_code=11004). ***” andends.


47 A2 01EL 5-5

The SQL CMA Listener converts the service name into a port number to get aconsistent interface with the TCP/IP driver. To get more details about thisconfiguration file, refer to the appropriate TCP/IP documentation.

Examples:

The following lines are included in «C:\WINNT\system32\drivers\etc\services»:

cmaserver 9007/tcpmycma 1202/tcp

You can start the SQL CMA listener as follows:

CMAlistener

«CMAlistener» connects on port number: 9007.

CMAlistener port=1500

«CMAlistener» explicitly connects on port number: 1500.

CMAlistener port=mycma

«CMAlistener» connects on port number: 1202.

The SQL CMA clients must imperatively refer to the port number on which theSQL CMA listener listens.

Note: If several SQL CMA listeners must run simultaneously, they haveto be connected on different port numbers.

Optional CMAlistener Final Report

When the SQL CMA Listener starts, a message is displayed to give a final status.

Starting CMA Listener on port XXXX.

The final status could be an error message if the listener is unable to start.


5-6 47 A2 01EL

5.2.4 STOPPING OPTIONAL CMA LISTENER

An executable «cmastop.exe» is provided to stop the «CMAlistener» processes.

The complete syntax to stop the SQL CMA Listener is:

cmastop [debug] [port=<port_number or service_name>]

where:

debug Optional parameter to enable «CMAstop» to run inDEBUG mode. The DEBUG messages are printed tostderr.

<port_number or service_name>

identifies the SQL CMA Listener process to bestopped. You enter the same value as the input TCP/IPport specified in the «CMAlistener» command line atstart-up. If no value is specified, all the running SQLCMA listeners are stopped.

This optional parameter can be specified as a number or as a character string:

<number> indicates the TCP/IP port number on which«CMAlistener» is connected.

<string> indicates the service name on which «CMAlistener» isconnected.

The «cmastop» procedure displays an explicit message (to return a final status) asfollows:All CMA servers are removed.CMA server on port XXX is removed.CMA server on service YY is removed.

No CMA server is running.No CMA server on port XXX is found.No CMA server on service YY is found.

Some CMA servers could not be removed.CMA server on port XXX could not be removed.CMA server on service YY could not be removed.


47 A2 01EL 5-7

5.3 LOGGING OF CMAservice (AND OPTIONAL CMA LISTENER )

CMAservice:

The CMAservice displays no error on the screen. A log file named“C:\WINNT\Temp\CMAservice.log” is opened (if the system variable TEMP is“C:\WINNT\Temp”).

This log file lists the input parameters of «CMAservice» and logs the errorsdetected while a client connection is required.

Optional CMA listener:

The SQL CMA listener displays the errors issued at start-up on the screen. Then, alog file named «C:\WINNT\Tmp\cmaserver_<port_number>.log» is opened(if the user variable TEMP is “C:\WINNT\Tmp”, user that launched the optionalCMAlistener).

Each SQL CMA Listener handles its own log file because the log filename isindexed by the port number on which the process is listening:

C:\WINNT\Tmp\cmaserver_1201.logC:\WINNT\Tmp\cmaserver_1202.log

This log file lists the input parameters of «CMAlistener» and logs the errorsdetected while a client connection is required.

CMAservice ( and optional CMAlistener) :

The log file is also used to hold DEBUG information if the SQL CMA Listener hasbeen started with the DEBUG option.

Example of a log file with no DEBUG option:

_________________________________________________________________

C.M.A. Network Server 2.1.0. Production: Logging file.

Service Started at 28-FEB-2003 08:24:51 (current PID=1232)

CMA_HOME_SQL is "D:\Program Files\Bull\SQL-CMA\CmaNet\CmaExec"

LOGGING mode is ENABLED. DEBUG mode is DISABLED.

Starting C.M.A SERVICE on port 9007.

28-FEB-2003 08:24:51 Waiting for connection request on port 9007...

Stopped at 03-MAR-2003 10:49:51

_________________________________________________________________


5-8 47 A2 01EL

Example of a log file with the DEBUG option:

_________________________________________________________________

C.M.A. Network Server 2.1.0. Production: Logging file.

Service Started at 06-MAR-2003 08:08:56 (current PID=5864)

CMA_HOME_SQL is "D:\Program Files\Bull\SQL-CMA\CmaNet\CmaExec"

LOGGING mode is ENABLED. DEBUG mode is ENABLED.

Starting C.M.A SERVICE on port 9007.

06-MAR-2003 08:08:56 Waiting for connection request on port 9007...

accept -> socket = 228...

ChildFunc >>> Thread = 2316 working on socket = 232

**************************

06-MAR-2003 08:13:33 DEBUG: Client network address is 172.31.32.86.

06-MAR-2003 08:13:38 DEBUG: Remote connection is required from

"172.31.32.86" site.

06-MAR-2003 08:13:38 DEBUG: Received buffer: length=0, index=0.

06-MAR-2003 08:13:38 DEBUG: Get remote message of 20 bytes long.

06-MAR-2003 08:13:38 DEBUG: Get "server_name" network message:

Length=20.

06-MAR-2003 08:13:38 DEBUG: Starting the application: tdscrsfnc03 (232,1)

child_action >>> start Process Id = 5688

06-MAR-2003 08:13:38 DEBUG: Application Process (5688) died with

exitcode=0.

>>> CMA--SERVICE: shutdown = 232 (after Application Process (5688) died) .

<<<

>>> CMA--SERVICE: closesocket = 232 (after Application Process (5688) died)

. <<<

accept -> socket = 244...

ChildFunc >>> Thread = 2188 working on socket = 240

**************************


47 A2 01EL 5-9

5.4 CMAservice and CMA LISTENER ERRORS

The following errors could be issued when the SQL CMA listener starts:

***CMAlistener: SERVICES file lookup failure (error code=xxx). ***

Cause:

A TCP/IP error was returned during the port search.

The «getservbyname» TCP/IP function was invoked.

Action:

Analyze the error code value to get the failure reason.

***CMAlistener: can’t create socket (error code =xxx). ***.

Cause:

A TCP/IP error was returned during the socket creation. The «socket» TCP/IPfunction was invoked.

Action:


***CMAlistener: can’t bind to socket (error code =xxx). ***

Cause:

A TCP/IP error was returned during the socket binding. The «bind» TCP/IPfunction was invoked.

Action:



5-10 47 A2 01EL

***CMAlistener: port address already in use. ***

Cause:

The error code («Address in Use») was returned during the socket binding. The«bind» TCP/IP function was invoked.

Either:

• a «CMAlistener» process was already running on this TCP/IP port, or

• you tried to start up «CMAlistener» right after you shut it down, and the systemdid not have enough time to free the resource, or

• another process is already running on this TCP/IP port .

Action:

In the first case, you take no action.

In the second case, wait for a minute before re-invoking «cmaserver» on thatTCP/IP port.

>>>> CMAlistener: CMA environment not found (CMA_HOME_SQL not defined). ***

Cause:

The CMA_HOME_SQL environment variable is not defined. The SQL CMAListener will uses the default path <CMA>\Cmanet\Cmaexec. To get informationabout this variable, refer to the «Setting environment variable» paragraph.

Action:

Declare this variable in the Windows 2000 environment (refer to MSDN)

***CMAlistener: unable to open logfile ’xxx’. ***

Cause:

The SQL CMA Listener was unable to open a Log file. There might insufficientdisk space, too many open files, or read-only protection on the output directory.

Action:

Make sure there is enough disk space, that the limit for open files is set highenough, and that protection on the directory allows opening a file for writing.


47 A2 01EL 5-11

*** usage: CMAlistener [debug] [port=<port number or service name>] ***

Cause:

This message is displayed when an input parameter is garbled. A service name notdeclared in «C:\WINNT\system32\drivers\etc\» could cause this error message tobe issued.

Action:

Correct the command line which starts «CMAlistener» and update«C:\WINNT\system32\drivers\etc\».

The following errors could be issued when the SQL CMA listener is running:

*** Error while accepting the remote connection (error code =xxx). ***

Cause:

The «CMAlistener» failed to accept the connection from the client process.

Action:


*** Error while starting ‘yyy’ application (error code=xxx). ***

Cause:

A system error was returned by Windows 2000 during a process creation. The“CreateProcess” function was invoked.

Action:

Analyze the error code value returned by Windows 2000 to get the failure reason.


5-12 47 A2 01EL

*** Error while reading ‘yyy’ network message (error code =xxx). ***

Cause:

A system error was returned by Windows 2000 during a socket reading. The «read»system function was invoked.

‘yyy’ indicates what kind of message was expected.

Action:

Analyze the error code value returned by Windows 2000 to get the failure reason.

5.5 LOGGING OF SQL CMA PROCESSES

When a SQL CMA link is established between the SQL CMA Client and Serverprocesses, a log file named «C:\WINNT\Temp\cmasql_<pid>».log is opened onthe Windows 2000 server, to hold the errors detected during the SQL CMAexchanges (Data sending and receiving).

Each SQL CMA Server handles its own log file because the log filename isindexed by the current process identification (P.I.D):

Example:

Suppose a SQL CMA Server named «demo3.exe» was started by the SQLCMAservice after a SQL CMA Client connection request.

The Windows task manager displays the following processinformation:demo3.exe 60898 ….

The Log file created by this SQL CMA Server, is named:

C:\WINNT\Temp\cmasql_60898.log

The SQL CMA Server process is started with input parameters such as a socketnumber and a DEBUG parameter. The DEBUG parameter is got from the«CMAservice» option (See the previous paragraphs).

The log file is used to hold DEBUG information if the DEBUG option is required.


47 A2 01EL 5-13

5.6 COMMUNICATION ERRORS

The SQL CMA Client returns an error code to inform the user that thecommunication failed.

Some error codes need the DEBUG mode to be active on the Server site.

An error message will be logged if the communication error is due to a remoteserver disconnection.

*** -9501 ***

Cause:

A TCP/IP error was returned during the socket creation. The «socket» TCP/IPfunction was invoked.

Action:

Check that the TCP/IP software is correctly installed on the mainframe and verifythat all the TCP/IP processes are running (the OPEN7 and the SOCKG7 daemon).


*** -9502 ***

Cause:

The CMASERVER_HOST or CMASERVER_PORT option parameters have agarbled value.

Either CMASERVER_HOST has a NULL value or CMASERVER_HOST is notdefined in the « /etc/hosts» configuration file (on the OPEN7 side). This causes anerror to be returned by the «gethostbyname» system function.

Either CMASERVER_PORT has a NULL value

Action:

Correct the command line which invokes the CMASERVER_HOST andCMASERVER_PORT parameters and update «/etc/hosts» if necessary.


5-14 47 A2 01EL

*** -9503 ***

Cause:

A TCP/IP error was returned during the socket connection. The «connect» TCP/IPfunction was invoked.

Action:

Check that the TCP/IP software is correctly installed on the mainframe and verifythat all the TCP/IP processes are running. (the OPEN7 and the SOCKG7 daemonon GCOS7 and the CMAlistener on the Windows).

To fix this problem, contact your support team representative.

*** -9504 ***

Cause:

A TCP/IP error was returned while the socket availability is being checked. The«cmaget_sockcli» CMA function was invoked.

Action:


*** -9505 ***

Cause:

A TCP/IP error was returned during the socket writing. The «send» TCP/IPfunction was invoked.

Action:

Check that the TCP/IP software is correctly installed on the mainframe and verifythat all the TCP/IP processes are running. (the OPEN7 and the SOCKG7 daemon).



47 A2 01EL 5-15

*** -9506 ***

Cause:

A TCP/IP error was returned during the socket reading. The «recv» TCP/IPfunction was invoked.

Action:

Check that the TCP/IP software is correctly installed on the mainframe and verifythat all the TCP/IP processes are running. (the OPEN7 and the SOCKG7 daemon).


*** -9510 ***

Cause:

Timeout error. The communication between CMA client and server is not possiblefor Network problems.

Action:

Contact your Network support.

*** 111 ***

Cause:

The SQL CMA license is not available so, the current product could not be used.

Action:

Check that the Marketing Identifier of SQL CMA is correctly installed on thesystem.



5-16 47 A2 01EL

❑

47 A2 01EL 6-1

6. Using SQL CMA in Batch Mode

This chapter explains how to build the SQL CMA application on GCOS7 and howto execute a batch application.

6.1 PREREQUISITES

6.1.1 SQL CMA PRODUCT ON GCOS7

SQL CMA libraries must be installed on GCOS7:

• SYS.DCM.CMA.INCLUDE

• SYS.DCM.CMA.SLLIB

• SYS.DCM.SYSTEM

6.1.2 SERVER EXECUTABLE ON WINDOWS 2000

This operation must be performed before building the SQL CMA GCOS7 clientbecause the SQL CMA Client Include files are modified during this phase to insertsome specific SQL CMA information in order to ensure the SQL CMA integrity.

6.1.3 CMANET ENABLED

That is, CMAservice must be started on Windows 2000 and waiting forconnections requests from SQL CMA GCOS7 client.


6-2 47 A2 01EL

6.2 BUILDING A SQL CMA COBOL CLIENT IN BATCH MODE

How to build a SQL CMA GCOS7 Client for Oracle is best explained by anexample:

Suppose that there are two user Oracle COBOL sources named:

«appli1.pco»

and

«appli2.pco»

which compose a BATCH application named:

«appli»

You build «appli» on a GCOS 7 mainframe as follows:

6.2.1 TRANSFER SOURCES FROM WINDOWS 2000 TO GCOS7

The SQL CMA Source generation creates the SQL CMA Client and Server files.

The SQL CMA Client files are named as follows:

For «appli1» user source: «appli1cli_cob», «appli1cli_h»

For «appli2» user source: «appli2cli_cob», «appli2cli_h»

transfer all the SQL CMA Client files (data and code) to a «SL» Source library onthe mainframe. The files are:

«appli1cli_cob»,«appli1cli_h»,«appli2cli_cob»,«appli2cli_h»

For COBOL files, the COBOL format (CBX,COB,DAT) must be respected duringthe transfer. To get details about these GCOS 7 COBOL formats, refer toChapter 3.

Using SQL CMA in Batch Mode

47 A2 01EL 6-3

6.2.2 MOVE SQL CMA INCLUDE FILES

Transfer the SQL CMA COBOL include files from «SYS.DCM.CMA.INCLUDE»to a user «SL» library. The files are:

«SQLCAORA_<CBX | COB | DAT>»«CMA_<CBX | COB | DAT>_H»

6.2.3 COMPILE CLIENT SOURCES

Compile the two SQL CMA Client sources: «appli1cli_cob», «appli2cli_cob» onthe mainframe (according to the COBOL compiler rules).

6.2.4 LINK CLIENT OBJECTS

Link the two SQL CMA object files in an «LM» Load Module library with theclause USEDSM=H_SM_DCM in the Link Job (JCL).

«H_SM_DCM» is included in «SYS.DCM.SYSTEM» and must be LOADEDwith MNSYS (Maintain System). This step may be added by the GCOS7System Administrator in the system startup.

A comfile example for batch link mode, ORACLEG_LNK, is delivered in thelibrary SYS.DCM.CMA.SLLIB

The resulting «LM» can be executed as a standard GCOS 7 application.

6.3 CLIENT APPLICATION EXECUTION

The BATCH JOB of a SQL CMA Client is started with the following list ofoptions:

options=’CMASERVER_HOST=<server> CMASERVER_PORT=<port> ‘

where:

<server> is the name of the Windows 2000 server machine.

<port> is the TCP/IP port number on which a SQL CMAlistener is connected.

Note: A space must be added at the end of the input parameters such as:

|CMASERVER_HOST=trifide | and |CMASERVER_PORT=1790


6-4 47 A2 01EL

❑

47 A2 01EL 7-1

7. Using SQL CMA in Transactional Mode

This chapter describes how SQL CMA works when a user application is running inTP mode.

You must be familiar with the TDS terminology and functionality. If necessary,refer to the standard TDS Administrator’s and User’s Guides to get the generalinformation.

7.1 PREREQUISITES

7.1.1 SQL CMA PRODUCT ON GCOS7

SQL CMA libraries must be installed on GCOS7:

• SYS.DCM.CMA.INCLUDE

• SYS.DCM.CMA.SLLIB

• SYS.DCM.SYSTEM

7.1.2 SERVER EXECUTABLE ON WINDOWS 2000

This operation must be performed before building the SQL CMA GCOS7 clientbecause the SQL CMA Client Include files are modified during this phase to insertsome specific SQL CMA information in order to ensure the SQL CMA integrity.

7.1.3 CMANET ENABLED

That is, CMAservice must be started on Windows 2000 and waiting forconnections requests from SQL CMA GCOS7 client.


7-2 47 A2 01EL

7.2 BUILDING A SQL CMA TP APPLICATION

7.2.1 TRANSFER SOURCES TO GCOS7

Transfer the Generated SQL CMA Client sources (concerning the SQL CMA TPapplication) to the «SL» source library on the mainframe. The files are:

«xxxcli_cob»«xxxcli_h»

Respect the COBOL format (CBX, COB, DAT) during the transfer. For detailsabout these GCOS 7 COBOL formats, refer to Chapter 3.

7.2.2 MOVE SQL CMA INCLUDE FILES

Transfer the SQL CMA COBOL include files from «SYS.DCM.CMA.INCLUDE»to a user «SL» library. The files are:

«SQLCAORA_<CBX | COB | DAT>»«CMA_<CBX | COB | DAT>_H»

7.2.3 COMPILE CLIENT SOURCES

Compile the SQL CMA Client sources on the mainframe (according to the COBOLcompiler rules).

7.2.4 LINK CLIENT OBJECTS

Link the SQL CMA TP application into a TPR sharable module as follows:

LINK_PGLM=<appli_name>SM=1INLIB=<appli_culib>COMPFILE=<TDS_name>.sllib..TP7LINKTPRLIB=<TDS_name>.smlib

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

It is also possible to link application in TDS used procedure.

Using SQL CMA in Transactional Mode

47 A2 01EL 7-3

7.3 PREPARING THE TDS ENVIRONMENT

You must inform the TDS monitor that a SQL CMA Application will run in TPmode.

Some actions must be performed on the mainframe and on the Oracle Databasebefore running a SQL CMA TP application in the TDS environment.

7.3.1 TDS GENERATION

7.3.1.1 Modifying the STDS file

1. Insert the following clause in the STDS file (after the clause SIMULTANEITY)ATTACH SHARABLE MODULE H_SM_DCM.

2. The following clause must be inserted in the STDS file at Generation timeCMA SERVICE USED

In the TRANSACTION SECTION, the «CMA SERVICE USED» clause allowsthe transaction to access the databases on the remote Windows 2000 site.

Example:

MESSAGE "TPSELECT" ASSIGN TO TPSELECTCMA SERVICE USEDAUTHORITY-CODES ARE 0,1.

3. Declare the CMATDS transaction

A SQL CMA Client application needs input parameters such as «remote Windows2000 host» and «Listener port number» to be defined in order to access the remotedatabases.

These input parameters are loaded by a specific transaction named «CMATDS».

Before starting «CMATDS», the following lines must be added in the STDS file:

MESSAGE «CMA» ASSIGN TO CMATDSAUTHORITY-CODE ARE 0,1.*END


7-4 47 A2 01EL

The «CMATDS» transaction is composed of the «CMATDS_COBOL» sourcewhich is delivered in the «SYS.DCM.CMA.SLLIB» library with DAT type. Thistransaction will use the copy-cobol file COMMUNIC-SECTION (delivered in thesame library)

The «CMATDS_COBOL» source must be compiled and linked. The compileoptions: CARDID=0 and LEVEL=NSTD are to be used at compilation time.

This transaction may be part of your TDS startup.

7.3.1.2 Running TP7GEN JCL

You must add the following clause after the «CHECKSTX» keyword:

CMASTLIB = <name>

where <name> is the SYSTEM FILE which contains the CMATP sharable module.

This clause is requested if this file is different from the “SYS.DCM.SYSTEM”

7.3.2 DATABASE OBJECT FOR TP MODE : CMATP TABLE

To use the SQL CMA TP facilities, each Oracle database needs a special table:CMATP. This table is described in the member: ORA-CMATP.sql , which isprovided in the directory C:\Program Files\Bull\SQL-CMA\CmaGen on theWindows 2000 server.You must execute ORA-CMATP.sql under the user SYS on each Oracle databaseyou want to access using SQL CMA in TDS mode.

This file contains:

CREATE TABLE SYS$CMATP( USID VARCHAR2(20), TID INTEGER );CREATE UNIQUE INDEX CMATPIDX ON SYS$CMATP (USID);GRANT ALL ON SYS$CMATP TO PUBLIC;CREATE PUBLIC SYNONYM CMATP FOR SYS$CMATP;


47 A2 01EL 7-5

7.4 TDS EXECUTION

7.4.1 RUNNING SQL CMA TRANSACTIONS

1. launch TDS application

You must add SQL CMA system file in the JOBLIB parameter if it is differentfrom “SYS.DCM.SYSTEM”.

2. set SQL CMA server machine using CMATDS transaction

The «CMATDS» transaction could be started as follows:

CMA CMAHOST=<server> CMAPORT=<port_number>

where:

<server> is the Windows 2000 server machine.

<port_number> is the TCP/IP port number on which a SQL CMAservice (or an optional CMA listener) is connected.

3. execute SQL CMA transactions

You are now ready to execute SQL CMA transactions.


7-6 47 A2 01EL

7.4.2 CONTROLLING SQL CMA EXECUTION WITH CMATDS TRANSACTION

It is possible to control SQL CMA TP execution using the CMATDS transaction :

CMA CMAHOST=<server> CMAPORT=<port_number>[TRACE=OFF/ON] [CLEAR= NO/YES][MAXTIM=<val1>] [TIMOUT=<val2>] [MAXWAT=<val3>]

where:

<server> is the Windows 2000 server machine.

<port_number> is the TCP/IP port number on which a SQL CMAservice (or an optional CMA listener) is connected.

<TRACE> is the tracing option (useful if problems occur) to traceon GCOS 7 (system trace in TDS domain).

<CLEAR> is the «cleaner» option to re-initialize a garbled SQLCMA TP Context.

<MAXTIM> specify the maximum time (in seconds) allowed for anSQL statement to execute. If the execution of an SQLstatement takes more than MAXTIM to execute, thecurrent Oracle operation is cancelled, the commitmentunit is rolled back and the TDS transaction is abortedwith error code –9510.Val1 must be comprise between 1 and 1000, defaultvalue is 30 seconds.

<TIMOUT> specify the maximum time (in seconds) allowed towait for an answer from the remote server module.Val2 must be comprise between 1 and 1000, defaultvalue is 20 seconds.

<MAXWAT> specify the maximum time (in milliseconds) a TPR canwait to re-establish an Oracle connection that has beenlost during the commit phase. Val3 must be comprisebetween 60000 and 100000, default value is 120000.

The «CMATDS» transaction must be performed each time the input parametersdefining the remote Windows 2000 site change.

All changes made to CMAHOST, CMAPORT, TRACE, CLEAR, MAXTIM,TIMOUT and MAXWAT parameters are written in the TDS CTLN file andremains valid until the new COLD restart of TDS.


47 A2 01EL 7-7

If the input parameters are garbled, the error status (-9503) is returned to the SQLCMA application.

CMATDS with the CLEAR parameter is used in specific cases described later inthis chapter.

7.5 SQL CMA TP ERROR CODES

*** SQLCODE = 111

Cause:

The SQL CMA product is incorrectly installed.

The Marketing Identifier is not available.

Action:


*** SQLCODE = -1

Cause:

A system error is returned during memory space allocation or memory access.

Action:

Start the «CMATDS» transaction with the «CLEAR» parameter to clean thecurrent SQL CMA TP Context. The physical telecommunication connection isreleased and the current SQL CMA TP Context is set to UNUSED.

Restart the SQL CMA TP application.


7-8 47 A2 01EL

*** SQLCODE = -2

Cause:

All the TDS cache entries are used.

Action:

Start the «CMATDS» transaction with the «CLEAR» parameter to clean thecurrent SQL CMA TP Context. The physical telecommunication connection isreleased and the current SQL CMA TP Context is set to UNUSED.


*** SQLCODE = -5

Cause:

The commit action fails at the end of the current commitment unit.Telecommunication problems occurred after the SQL COMMIT statement has beensent to the database, so no acknowledgment has been received from the remote site.

During the automatic restart, the SQL CMA TP application is informed that thedatabase has been successfully committed. The commitment unit could not be re-executed because that would cause a double updating of the database.

Action:

If no data needs to be re-initialized to get the next commitment unit available, donot execute the current commitment unit and start the next one. Otherwise, abortthe current TDS transaction.

*** SQLCODE = -6

Cause:

The same kind of failure occurs but TDS could not successfully re-connect to theremote database. It is not possible to get the COMMIT status returned by thedatabase server.

Action:

It is not possible to get the real COMMIT status. Therefore, you must use othermeans to check the data integrity between the database and TDS.


47 A2 01EL 7-9

*** SQLCODE = -11

Cause:

The current SQL CMA TP Context is inconsistent for an internal reason. The SQLCMA TP Context is set to DAMAGED.

Action:

Start the «CMATDS» transaction with «CLEAR» parameter to clean the currentSQL CMA TP Context. The physical telecommunication connection is released andthe current SQL CMA TP Context is set to UNUSED.


*** SQLCODE = -12

Cause:

The database identifier of the CONNECT statement is already used by an activeconnection in the same Commitment Unit

Action:

Check user program and use distinct database identifier for each CONNECTstatement in a given Commitment Unit.

*** SQLCODE = -22

Cause:

The automatic restart following a COMMIT failure has failed.

Action:



7-10 47 A2 01EL

*** SQLCODE = -23

Cause:

The commit action fails at the end of the current commitment unit.

A database error is returned concerning the CMATP table, necessary to handle theCOMMIT action.

During the automatic restart, the SQL CMA TP application is informed about thedatabase error on the first CONNECT statement.

Action:

Check that the CMATP table is created correctly in the accessed database andrestart the SQL CMA TP application.

*** SQLCODE = -1803

Cause:

Connection is not established

Action:

Check program, to test and process SQL connection errors.

*** SQLCODE = 10

Cause:

Several SQL COMMIT statements are detected in a commitment unit.

This warning is returned to inform the SQL CMA TP application that only thedatabase referenced before the first SQL COMMIT statement will be reallycommitted.

Action:

Not Applicable.

47 A2 01EL g-1

Glossary

CMAAbbreviation of Client Mode Access

client-server architectureSoftware architecture based on a separation of processing between two CPUs. One acts as a clientrequesting and receiving services. The other acts as a server providing services in a transaction.

communication protocolA set of implemented standards or rules governing the transmission of data across a network. Acommunications protocol includes detailed specifications for data transmission. A protocol may beimplemented in several layers, including software and hardware, and may connect homogenous andheterogeneous computers.

client processA process that can connect to another process on a remote system.In the Client/Server model of communications, the client process must request the services of aserver, usually an application or utility, running on a computer, that requests the services of adatabase on a remote or local computer.

Declare SectionYou must declare all program variables to be used in SQL statements in the Declare section. If youuse an undeclared SQL variable in a SQL statement, an error message is issued at precompile time.

The Declare section begins as follows:

EXEC SQL BEGIN DECLARE SECTION

and ends with the statement:

EXEC SQL END DECLARE SECTION

DefaultA standard value that a parameter will assume unless you specify another.

distributed environmentA specification which allows applications to access data on more than one CPU (and often manytypes of computers ranging from PCs to mainframes) within a computer system or network.


g-2 47 A2 01EL

heterogeneous systemsTerm used to describe a computing environment consisting of systems made by different vendorstypically running different operating systems.

Host variableSee the «SQL variable» definition.

layerA collection of related functions that comprise one level of hierarchy of functions. Each layerspecifies its own functions and assumes that lower level functions are provided.

listenerA process in charge of incoming Client connections across the network.

mainframeGlobal term to indicate proprietary machines such as BULL GCOS 7, BULL GCOS 8, ...

OracleName of a relational database (and the company which supplies it).

precompilerA database precompiler is a programming tool that enables you to embed SQL statements in a high-level source program. The precompiler translates the embedded SQL statements into standarddatabase runtime library calls.

processA single entity performing a set of tasks in an operating-system environment. It is the smallest unitof processing that can be executed by a computer system. It consists of sequence of interdependentand indivisible instructions.

protocolA set of standards, or rules, governing the operations of a communications link.

server processA process that can connect to another process on a remote system. In the Client/server model ofcommunication, the server process must provide the services requested by the Client process on anetwork.

SQLStructured Query Language is a standard language used to create, manage, and reference relationaldatabases.

SQL serverName of a relational database (Microsoft is the company which supplies it).

SQL statementA SQL statement is a command that manipulates and query database objects such as INSERT,UPDATE, DELETE, and SELECT statements using the normalized SQL language syntax. Whenthe SQL statement is placed within an application program, it is called «Embedded SQL statement»and a precompiler is needed to process it.

Glossary

47 A2 01EL g-3

SQL variableA SQL variable (also called Host variable) is a program variable used in a SQL statement that mustbe declared in the Declare Section. It is the key to communication between a User program and theDatabase.

TCP/IPA telecommunication protocol composed of two layers:

Transmission Control Protocol (TCP)Internet Protocol (IP)

TCP ensures information accuracy.IP dispatches information around the network.

TDSTransactional mechanism on the GCOS 7 system.

TPRTransactional Processing Routine.


g-4 47 A2 01EL

❑

47 A2 01EL i-1

Index

AApplication Running In parameter 4-8, 4-13automatic restart 3-29

Ccache mechanism 1-7, 3-22CBL 3-2CBX 3-3, 3-13, 3-14, 3-17, 6-2, 6-3, 7-2client process g-1client program 1-5, 4-5Client/Server 1-2, g-1CMA g-1CMA_HOME_SQL 4-2, 5-2CMA-0052 error 3-9cmafindsymb.log 2-4, 2-8, 2-9CMAGEN 1-4, 1-5, 2-1cmagen.log 2-4, 2-5, 2-6, 4-14CMAINST

Build Server parametersApplication Running In 4-13LIST name 4-12Logging File Name 4-13Server BINARY NAME 4-11SOURCES NAME(s) 4-12

Generate Sources parametersApplication Running In 4-8DEBUG mode 2-3, 4-8Format 4-7LIST name 4-6Logfile directory 2-4Logging File Name 4-9ProCobol option string 4-7

SOURCES NAME(s) 4-6SQL mode 4-7

CMANET 1-4, 1-6, 2-24, 4-10, 6-1, 7-1CmaOptionalListener 2-25, 5-6, 5-7, 5-9CmaOptionalListener errors 5-11CMAservice 1-6, 2-24, 5-2, 5-3, 5-9, 6-1, 7-1CMAservice errors 5-9cmasymb.log 2-4, 2-7CMATDS transaction 7-3, 7-5, 7-6CMATP 1-4, 1-7, 2-25, 3-22CMATP table 4-2, 7-4COB 3-3, 3-13, 3-14, 3-17, 6-2, 6-3, 7-2COBOL

data conversion 3-5GCOS 7 data types 3-4INCLUDE files 3-13, 3-14, 3-15source format 3-1types

CBL (GCOS7 COBOL) 3-2CBX (GCOS7 COBOL) 3-3COB (GCOS7 COBOL) 3-3DAT (GCOS7 COBOL) 3-2

comments 3-7, 3-9commit synchronization mechanism 1-7commitments

automatic restart 3-29explicit 3-27handlind 3-26implicit 3-27SQL COMMIT 3-27

communication interface 1-6, 2-24communication protocol g-1connection cache mechanism 1-7, 3-22cursor

restriction on DECLARE statement 3-18,3-20


i-2 47 A2 01EL

restriction with TDS 3-21

DDAT 3-2, 3-13, 3-14, 3-17, 6-2, 6-3, 7-2data conversion 3-5DEBUG mode parameter 2-3, 4-8DECLARE CURSOR 3-18, 3-20, 3-21Declare Section g-1DFCMIT statement 3-27distributed environment g-1Dynamic SQL 3-5

EEmbedded SQL 1-2, 3-5error messages

CMA-0052 3-9CMAGEN errors

CMA-0000 2-10CMA-0010 2-10CMA-0011 2-11CMA-0012 2-11CMA-0013 2-11CMA-0014 2-12CMA-0015 2-12CMA-0016 2-12CMA-0017 2-13CMA-0018 2-13CMA-0019 2-13CMA-0020 2-14CMA-0031 2-14CMA-0032 2-14CMA-0033 2-15CMA-0034 2-15CMA-0050 2-15CMA-0051 2-16CMA-0052 2-16CMA-0053 2-17CMA-0054 2-17CMA-0055 2-18CMA-0056 2-18CMA-0060 2-18CMA-0061 2-19CMA-0062 2-19

CMA-0063 2-19CMA-0064 2-20CMA-0066 2-20CMA-0067 2-20CMA-0068 2-21CMA-0070 2-21CMA-0071 2-22CMA-0072 2-22CMA-0073 2-23

CMANET ERRORS111 5-15-9501 5-13-9502 5-13-9503 5-14-9504 5-14-9505 5-14-9506 5-15-9510 5-15

CmaOptionalListener errors 5-11CMAservice errors 5-9CMATP errors

SQLCODE = -1 7-7SQLCODE = 10 7-10SQLCODE = -11 7-9SQLCODE = 111 7-7SQLCODE = -12 7-9SQLCODE = -1803 7-10SQLCODE = -2 7-8SQLCODE = -22 7-9SQLCODE = -23 7-10SQLCODE = -5 7-8SQLCODE = -6 7-8

explicit commitment 3-27

FFormat parameter 4-7

GGCOS 7 COBOL data types 3-4generated client files 2-2generated server files 2-2, 4-10

Erreur! Style non défini.

47 A2 01EL i-3

HH_CMANET 2-24H_SM_DCM 6-3, 7-2Handling TP errors 3-32heterogeneous system g-2host variable g-2

Iimplicit commitment 3-27INCLUDE files 3-13, 3-14, 3-15

Llayer 1-4, 1-6, g-2lexical analysis debug 2-3lexical debug message 2-6LIST name parameter 4-6, 4-12Listener g-2Logfile directory 2-4logging

CmaOptionalListener 5-7SQL CMA server process 5-12

Logging File Name parameter 4-9, 4-13

Mmainframe g-2Merant/Micro Focus 1-8, 4-2, 4-10

NNet Express 1-8, 3-18

OOCI 3-5ORACA 3-15ORACLE 1-1, 1-8, 3-18, 4-2, 4-5, g-2ORACLEG_LNK 6-3

PPL/SQL 3-5precompiler 1-2, 1-8, 3-6, 4-5, 4-7, g-2process g-2ProCobol option string parameter 4-7protocol g-2

Rrestriction

cursor operation with TDS 3-21SQL Declare Cursor statement 3-18, 3-20

ROLLBACK action 3-30

SServer BINARY NAME parameter 4-11server process g-2server process logging 5-12server program 1-5, 4-5source generator 1-5, 2-1SOURCES NAME(s) parameter 4-6, 4-12SQL g-2SQL arrays of variables 3-11SQL CMA

client program 1-4, 1-5data conversion 3-5generated client files 2-2generated server files 2-2server process 5-12server program 1-4, 1-5

SQL COMMIT statement 3-26, 3-27SQL CONNECT statement 3-24SQL mode parameter 4-7SQL referencing elementary variables 3-12SQL restriction on cursor operation with TDS

3-21SQL restriction on Declare Cursor statement

3-18, 3-20SQL ROLLBACK statement 3-30SQL server 1-8, g-2SQL statement g-2SQL variables 3-6, 3-9, g-3SQLCA 3-14, 3-16


i-4 47 A2 01EL

SQLCODE (SQLCA) 3-16SQLERRD (SQLCA) 3-17SQLWARN (SQLCA) 3-17starting CMAservice 5-2stopping CmaOptionalListener 5-6symbol research debug 2-4symbol table debug 2-3synchronization mechanism 1-7

TTCP/IP g-3TDS g-3TP7GEN 7-4TPR g-3transactional interface 1-7, 2-25

VVisual C++ 4-2, 4-10

Vos remarques sur ce document / Technical publications remarks form

Titre / Title : GCOS 7 SQL Client Mode Access User's Guide

N° Référence / Reference No. : 47 A2 01EL Rev 00 Date / Dated : May 2003

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 S.A.CEDOCAtelier de reprographie357, Avenue Patton BP 2084549008 ANGERS Cedex 01FRANCE

Date post:	05-Feb-2018
Category:	Documents
Upload:	duongtuyen
View:	218 times
Download:	0 times

SQL*XT for ORACLE - Bull On-line Support...

Documents