cma-sqlserver sql*mt for sql...

Database Products

CMA-SQLserverSQL*MT for SQL Server

SQL Client Mode Access User’s Guide

47 A2 22UR Rev03

47 A2 22UR Rev03

Database Products

CMA-SQLserverSQL*MT for SQL Server

GCOS 7 SQL Client Mode Access User’s Guide

Subject: This manual describes the CMA –SQLserver (Client ModeAccess) on GCOS 7.

Special Instructions:

Software Supported: GCOS 7-V7 TS7458 (or later)Artemis and DianeSQLserver7.0 on Windows 2000GCOS 7 CMA-SQLserver version 1.2

Software/Hardware required:

Date: May 2002

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

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

47 A2 22UR Rev03

Copyright © Bull S.A., 2002

Bull acknowledges the rights of proprietors of trademarks mentioned herein.

Your suggestions and criticisms concerning the form, contents and presentation of this manual are invited.A form is provided at the end of this manual for this purpose.

No part of this publication may be reproduced, stored in a retrieval system or transmitted in any form or by anymeans, 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 event is Bullliable to anyone for any indirect, special, or consequential damages.The information and specifications in this document are subject to change without notice.Consult your Bull Marketing Representative for product or service availability.

47 A2 22UR Rev03 iii

Preface

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

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 theirfunctionality’s.

Chapter 2 describes the SQL CMA main components in more detail. Inparticular, it describes CMAGEN (CMA Source Generator) andCMATP (CMA Transaction Processing interface).

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

Chapter 4 describes the installation process for the SQL CMA product. TheError Messages issued by the SQL CMA Installer are alsodetailed in this chapter.

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

Chapter 6 explains how to start a SQL CMA Client process on themainframe and how to configure and start the correspondingserver process on NT.

Appendix A Sample

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

Purpose

Audience

Structure ofthis Manual


iv 47 A2 22UR Rev03

47 A2 22UR Rev03 v

Table of Contents

1. Introduction

1.1 What Is SQL CMA?......................................................................................................... 1-1

1.1.1 Client Server Model ........................................................................................... 1-2

1.1.2 SQL.................................................................................................................... 1-2

1.2 SQL CMA Components................................................................................................... 1-3

1.2.1 CMAGEN Module: Source Generator................................................................ 1-4

1.2.2 CMANET Module: Communication Interface..................................................... 1-5

1.2.3 CMATP Module: Transactional Interface........................................................... 1-61.2.3.1 Connection Cache Mechanism ......................................................... 1-61.2.3.2 Commit Synchronization Mechanism................................................ 1-6

1.3 Current GCOS 7 SQL CMA Offer ................................................................................... 1-7

2. Description of SQL CMA Components

2.1 SQL CMA Source Generator: CMAGEN ........................................................................ 2-1

2.1.1 Generated SQL CMA Sources .......................................................................... 2-2

2.1.2 DEBUG Option................................................................................................... 2-3

2.1.3 Logging of SQL CMA Generator........................................................................ 2-42.1.3.1 Generator LOG File: «C:\WINNT\Temp\cmagen.log» ...................... 2-42.1.3.2 Declared Symbol Log file: «C:\WINNT\Temp\cmasymb.log» ........... 2-62.1.3.3 Referenced Symbol Log file:«C:\WINNT\Temp\cmafindsymb.log» .. 2-8

2.1.4 Errors from CMA SQL_server Generation....................................................... 2-10

2.2 SQL CMA Communications Interface: CMANET.......................................................... 2-19

2.3 SQL CMA Transactional Interface: CMATP.................................................................. 2-20

3. Defining SQL CMA Applications

3.1 COBOL Sources on GCOS 7.......................................................................................... 3-1

3.1.1 Format of COBOL Source ................................................................................. 3-1

3.1.2 COBOL Data Types........................................................................................... 3-4


vi 47 A2 22UR Rev03

3.2 SQL CMA COBOL Rules ................................................................................................ 3-4

3.2.1 SQL CMA COBOL Data Types.......................................................................... 3-5

3.3 Using Database SQL Variables ...................................................................................... 3-6

3.3.1 Declaring SQL Variables.................................................................................... 3-63.3.1.1 SQL Variable Name........................................................................... 3-63.3.1.2 Comments ......................................................................................... 3-73.3.1.3 Continuation Lines............................................................................. 3-73.3.1.4 PICTURE Attribute of SQL Variables ................................................ 3-83.3.1.5 RENAMES Attribute of SQL Variables.............................................. 3-8

3.3.2 Referencing SQL Variables ............................................................................... 3-83.3.2.1 Comments ......................................................................................... 3-93.3.2.2 Continuation Lines........................................................................... 3-103.3.2.3 Referencing SQL Arrays of Variables ............................................. 3-103.3.2.4 Referencing SQL Elementary Variables.......................................... 3-11

3.4 Include Files .................................................................................................................. 3-12

3.4.1 SQLCA Include File ......................................................................................... 3-13

3.4.2 Ordinary INCLUDE File.................................................................................... 3-14

3.4.3 SQLCA Structure ............................................................................................. 3-15

3.5 SQL CMA Applications.................................................................................................. 3-16

3.5.1 DATABASE Object Names.............................................................................. 3-16

3.5.2 Restrictions on Declare Statement .................................................................. 3-17

4. SQL CMA Installer

4.1 Setting Environment Variables........................................................................................ 4-2

4.1.1 Merant/Micro Focus Product.............................................................................. 4-2

4.1.2 C compiler Product ............................................................................................ 4-2

4.1.3 SQL-server Product ........................................................................................... 4-2

4.1.4 SQL CMA Product ............................................................................................. 4-2

4.2 CMA Product ................................................................................................................... 4-3

4.2.1 Interactive Program cmainst.exe ....................................................................... 4-4

4.3 Starting SQL CMA Source Generation ........................................................................... 4-4

4.3.1 «FILE of SOURCE list» and «SOURCE NAME» Parameters........................... 4-5

4.3.2 «APPLICATION RUNNING MODE» Parameter ............................................... 4-6

4.3.3 «SQL CMA DEBUG» Parameter ....................................................................... 4-6

4.3.4 «LOGGING FILE NAME» Parameter ................................................................ 4-7

4.3.5 Validation of SOURCES to Generate ................................................................ 4-7

4.4 Starting SQL CMA Server Building ................................................................................. 4-8

4.4.1 «SERVER BINARY NAME» Parameter ............................................................ 4-9

4.4.2 «FILE of SOURCE list» and «RADIX OF THE OBJECT FILE» Parameters .... 4-9

4.4.3 «APPLICATION RUNNING MODE» Parameter ............................................. 4-10

47 A2 22UR Rev03 vii

4.4.4 «LOGGING FILE NAME» Parameter .............................................................. 4-10

4.5 Starting SQL CMA Client Building................................................................................. 4-11

4.5.1 Building a SQL CMA COBOL Client in Batch Mode........................................ 4-11

4.6 Final Report of SQL CMA Installer................................................................................ 4-12

4.7 SQL CMA Installer Errors.............................................................................................. 4-13

5. Using SQL CMA in Transactional Mode

5.1 Building a SQL CMA TP Application............................................................................... 5-1

5.2 Preparing the TP7 Environment...................................................................................... 5-2

5.2.1 Modifications in the STDS: «CMA SERVICE USED» Clause andATTACH SHARABLE MODULE........................................................................ 5-2

5.2.2 TP7GEN JCL ..................................................................................................... 5-3

5.3 Preparing the SQL CMA TP Environment ...................................................................... 5-3

5.3.1 «CMATDS» Transaction.................................................................................... 5-3

5.3.2 Database Object for TP Mode: CMATP............................................................. 5-4

5.4 SQL CMA TP Description ............................................................................................... 5-5

5.4.1 SQL CMA TP Cache Concept ........................................................................... 5-55.4.1.1 SQL CMA TP Context Cache Definition............................................ 5-55.4.1.2 SQL CMA TP Context States ............................................................ 5-65.4.1.3 Why a SQL CMA TP Context Cache?............................................... 5-6

5.4.2 CONNECT Action .............................................................................................. 5-75.4.2.1 CONNECT Action Provided by SQL SERVER ................................. 5-75.4.2.2 Relationship between CONNECT Action and

SQL CMA TP Context ....................................................................... 5-75.4.2.3 CONNECT Action Errors................................................................... 5-8

5.4.3 Commitments..................................................................................................... 5-8

5.4.4 COMMIT Action ................................................................................................. 5-95.4.4.1 Implicit Commitment ........................................................................ 5-105.4.4.2 Explicit Commitment........................................................................ 5-105.4.4.3 SQL COMMIT Statement Provided by SQL SERVER.................... 5-105.4.4.4 Examples of Commit Actions .......................................................... 5-115.4.4.5 Automatic Restart ............................................................................ 5-125.4.4.6 Relationship between COMMIT Action and

SQL CMA TP Context ..................................................................... 5-13

5.4.5 ROLLBACK Action........................................................................................... 5-135.4.5.1 ROLLBACK Statement Provided by SQL Server............................ 5-135.4.5.2 Examples of ROLLBACK Actions.................................................... 5-145.4.5.3 Relationship between ROLLBACK Action and

SQL CMA TP Context ..................................................................... 5-15

5.5 SQL CMA TP Errors...................................................................................................... 5-15

5.6 SQL CMA TP Error Codes ............................................................................................ 5-16


viii 47 A2 22UR Rev03

6. Starting SQL CMA Processes

6.1 Configuring the Machines ............................................................................................... 6-2

6.2 Starting SQL CMA Service.............................................................................................. 6-2

6.2.1 Environment Variable CMA_HOME_SQL ......................................................... 6-2

6.2.2 CMAservice in Debug Mode: File “CMAdebug.txt”............................................ 6-3

6.2.3 Starting Optional CMAlistener ........................................................................... 6-3

6.2.4 Optional CMAlistener Final Report .................................................................... 6-5

6.2.5 Stopping Optional CMA Listener ....................................................................... 6-6

6.3 Logging of CMAservice (and Optional CMA Listener) .................................................... 6-7

6.4 CMAservice and CMA LISTENER Errors ....................................................................... 6-8

6.5 Starting SQL CMA Client Process in BATCH Mode ..................................................... 6-11

6.6 Starting SQL CMA Client Process in TP Mode............................................................. 6-11

6.7 Logging of SQL CMA Processes .................................................................................. 6-12

6.8 Communication Errors .................................................................................................. 6-13

A. Sample

A.1 Description ......................................................................................................................A-1

A.2 CMA Install: Sources Generation and Server Building ...................................................A-1

A.3 Application Generation....................................................................................................A-4

A.4 Server Building ................................................................................................................A-7

A.5 Initial Source with ESQL in COBOL: mfselect.cbl...........................................................A-9

A.6 GCOS7 Client File: mfselectcli_cob (Produced by CMAG-SQLserver)........................A-12

A.7 GCOS7 Client File: mfselectcli_h (Produced by CMAG-SQLserver)............................A-18

A.8 W2K Server Files: mfselectsvr.cbl (Produced by CMAG-SQLserver) ..........................A-19

A.9 W2K Server Files: cmadyn_MyExample.h (Produced by CMAG-SQLserver)..............A-21

A.10 Execution Report...........................................................................................................A-22

Glossary

47 A2 22UR Rev03 ix

Table of Graphics

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

Tables


x 47 A2 22UR Rev03

47 A2 22UR Rev03 1-1

1. Introduction

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 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 a UNIX or W2K system.

GCOS 7 SQL CMA is the specific SQL CMA product adapted to the GCOS clientmainframe.

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, ORACLE, INFORMIX or SYBASE located onWINDOWS platforms or UNIX platforms, without the database environment beinginstalled and running 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 22UR Rev03

1.1.1 Client Server Model

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

There are two tasks, each running on a different machine, which communicate withone another by using some communication protocols.

1.1.2 SQL

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 SQLstatements into procedure calls and special data structures and produces new sourcecode that will be compiled and linked with the database libraries to get a finalapplication.

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 precompilers. SQL CMA removes this requirement fromthe Client mainframe because it performs the SQL processing on the remote W2Kor UNIX 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 that enables the remote execution of theEmbedded SQL statements from a user database application (with SQL statementsembedded to manipulate database objects).

Introduction

47 A2 22UR Rev03 1-3

1.2 SQL CMA Components

According to the database preprocessing architecture explained previously, SQLCMA acts as a database precompiler.

It analyses the user application which includes some SQL statements, translates itinto 2 output source programs:

• one running on the mainframe client,

• and the other running on the W2K or UNIX server.

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

The SQL CMA generated source programs are compiled and linked in theirrespective environments (Mainframe and W2K or UNIX ).

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 W2K server or the UNIX server needs thestandard database environment: precompilers, include files, database libraries, ... tobe compiled and linked because it includes the SQL statements that manipulatesthe database objects.

The two SQL CMA source programs communicate with one another through aSQL CMA 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.


1-4 47 A2 22UR Rev03

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 precompiler to get a standardsource code. This is then compiled and linked with database libraries to get a finalapplication.

CMAGEN, the SQL CMA Source Generator, acts as a precompiler, that is, itanalyses the input application which includes the Embedded SQL statements,generates two output programs:

• a SQL CMA client source,

• a SQL CMA server source.

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 precompiler just as a standard client databaseapplication. Then, it has to be compiled and linked with the database and theCMANET libraries on the W2K system or UNIX system to get a serverapplication.

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

CMAGEN operates in the W2K or UNIX environment.

Introduction

47 A2 22UR Rev03 1-5

1.2.2 CMANET Module: Communication Interface

CMANET is the software layer that cooperates with a communication protocolsupported by the mainframe and the W2K or UNIX systems 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, W2K platforms andUNIX platforms.

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 W2K (orUNIX).

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

• the other for W2K or UNIX, to enable the SQL CMA server program to belinked.

A SQL CMA listener is also provided (on W2K or UNIX). The SQL CMA listenerfunctionality is to:

• listen for the client connection requests,

• accept the connection establishment, and

• start the appropriate SQL CMA server process.

The SQL CMA listener is part of the CMANET module on W2K (it is a W2Kservice) or UNIX.


1-6 47 A2 22UR Rev03

1.2.3 CMATP Module: Transactional Interface

Some SQL CMA applications are Transactional applications. For example, theseapplications run in the TP7 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, that is, 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 CMA TP 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, and

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

Introduction

47 A2 22UR Rev03 1-7

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 database accessesand using the standard COBOL language, running in batch or TP mode.

The SQLserver version 7.0 is used for testing on platforms with Windows 2000 andWindows NT4.0.

The Merant/MicroFocus product “Net Express 3.1” is requested on the W2K side:it provides a precompiler (OpenESQL) for ESQL(embedded SQL) in COBOLsources and a COBOL compiler.The OpenESQL compiler generates “ODBC calls” to the Sqlserver.

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


1-8 47 A2 22UR Rev03

�

47 A2 22UR Rev03 2-1

2. Description of SQL CMA Components

This chapter describes the main SQL CMA components for Client applicationssupporting Microsoft SQL server 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 W2K database without the databaseenvironment being installed on the mainframe. This functionality is suppliedbecause the processing of Embedded SQL statements, which needs the databaseenvironment such as libraries and pre-compilers, is done on the W2K side.

CMAGEN converts the Embedded SQL statements into SQL CMA function calls.This ensures the remote CMAGEN is the module which collects 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 which ensures the translation ofSQL statements 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 par. 4 for more information.

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

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


2-2 47 A2 22UR Rev03

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 Server NT. These source files arerecognizable 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:«cbl» for SQLserver (the line “$SET SQL (dbman=ODBC)” isinserted at the beginning of the file, in order to pre-process this filewith OpenESQL before the cobol compilation).

The SQL CMA Source generator produces the following files:

Generated Client files:

«<name>cli_cob Source code«<name>cli_h» Include file.

Generated Server files:

«<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 Server NT.

Description of SQL CMA Components

47 A2 22UR Rev03 2-3

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 that this tracking be normal ordetailed.

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», that is, itlists the SQL variables declared in the SQL «DeclareSection», with their characteristics (Name, type,length).

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 grows due to the flow of information.


2-4 47 A2 22UR Rev03

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 “ C:\WINNT\Temp\”

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

« C:\WINNT\Temp\cmagen.log»

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

« C:\WINNT\Temp\ cmagen.log»

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

« C:\WINNT\Temp\ cmasymb.log»

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

« C:\WINNT\Temp\ cmafindsymb.log»

2.1.3.1 Generator LOG File: «C:\WINNT\Temp\cmagen.log»

The Generator Log file «C:\WINNT\Temp\cmagen.log» contains the errorsdetected during 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.


47 A2 22UR Rev03 2-5

EXAMPLES:

Here are examples of «C:\WINNT\Temp\cmagen.log» headers:

CMA*GENerator 1.0.0. Production: <<appli.cbl>> Logging file.

Generation of BATCH application.DEBUG mode is ENABLED for: Lexical Analysis Symbol Table Building Symbol Table Building (Detailed) Referenced Symbol Search Referenced Symbol Search (Detailed)

CMA*GENerator 1.0.0. Production: <<appli.cbl>> Logging file.

Generation of BATCH application.DEBUG mode is DISABLED.

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.cbl>>, line 34 at 15-APR-96 15:45:30:01 B1 PIC S9999999 SYNC LEFT COMP-1

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

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

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


2-6 47 A2 22UR Rev03

Lexical DEBUG Message

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

DEBUG keyword Date and time Class 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 15-APR-96 15:46:39:Detection of DECLARE SECTION beginning.

DEBUG trace at 15-APR-96 15:48:09:EXEC statement:EXEC SQL INCLUDE SQLCA END-EXEC.

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

The SQL CMA Generation logging is appended to«C:\WINNT\Temp\cmagen.log».

2.1.3.2 Declared Symbol Log file: «C:\WINNT\Temp\cmasymb.log»

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

«C:\WINNT\Temp\cmasymb.log» describes the SQL variables, declared in theSQL «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.


47 A2 22UR Rev03 2-7

EXAMPLES:

Below are examples of «C:\WINNT\Temp\cmasymb.log» records:

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

<<appli.cbl>> Variable declaration: Symbol Name: VAR3 Buffer Address: 0x20022f98 Level: 01 USAGE Type: COMP-2 OCCURS Loop: 0 PICTURE string: NULL PICTURE size: 0 PICTURE S9 size: 0 PICTURE V9 size: 0 Next Buffer Address: 0x20029e38 Previous Buffer Address: 0x20026c98

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

<<appli.cbl>> Variable declaration: Symbol Name: VAR4 Buffer Address: 0x20022f98 Level: 05 USAGE Type: COMP-3 OCCURS Loop: 5 PICTURE string: S9(7)V99 PICTURE size: 9 PICTURE S9 size: 7 PICTURE V9 size: 2 Next Buffer Address: 0x2002a268 Previous Buffer Address: 0x20026c98

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

The SQL CMA declaration debugging is appended in«C:\WINNT\Temp\cmasymb.log».


2-8 47 A2 22UR Rev03

2.1.3.3 Referenced Symbol Log file:«C:\WINNT\Temp\cmafindsymb.log»

The Referenced Symbol Log file: «C:\WINNT\Temp\cmasymb.log» is created ifthe «Symbol Research debug» option is set before performing the SQL CMAsource Generation.

«C:\WINNT\Temp\cmafindsymb.log» describes the SQL variables referenced inthe SQL 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 variablein«C:\WINNT\Temp\cmafindsymb.log» looks like the description of a declaredSQL variable in «C:\WINNT\Temp\cmafindsymb.log».

A record in «C:\WINNT\Temp\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«C:\WINNT\Temp\cmafindsymb.log».


47 A2 22UR Rev03 2-9

EXAMPLES:

Below are examples of «C:\WINNT\Temp\cmafindsymb.log» records (in aCOBOL source):

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

<<appli.cbl>>,line 22 Referenced variable: VAR3 (sent from KERNELto USER) Symbol Name: VAR3 Buffer Address: 0x20026ce8 Level: 01 USAGE Type: COMP-2 OCCURS Loop: 0 PICTURE string: NULL PICTURE size: 0 PICTURE S9 size: 0 PICTURE V9 size: 0 Next Buffer Address: 0x20027118 Previous Buffer Address: 0x0

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

Symbol Name: VAR4 Buffer Address: 0x20027548 Level: 05 USAGE Type: COMP-3 OCCURS Loop: 5 PICTURE string: S9(7)V99 PICTURE size: 9 PICTURE S9 size: 7 PICTURE V9 size: 2 Next Buffer Address: 0x0 Previous Buffer Address: 0x20027118


2-10 47 A2 22UR Rev03

2.1.4 Errors from CMA SQL_server Generation

The Embedded SQL in COBOL source must be ANSI 92 in this version.Specific T-SQL are not supported.

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

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

There may be:

• insufficient disk space,• too many open files, or• read-only protection on the output directory.

Make sure that:

• there is enough disk space,• the limit for open files is set high enough, and• the protection on the directory allows opening a file for writing.

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

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

To fix the problem, contact your support team representative .

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

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

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

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

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

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

Cause:

Action:

Cause:

Action:

Cause:

Action:

Cause:

Action:


47 A2 22UR Rev03 2-11

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

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

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

*** CMA-0014 No PICTURE clause defined.

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

Correct the COBOL declaration according to the COBOL documentation.

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

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

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.

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


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

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


Cause:

Action:

Cause:

Action:

Cause:

Action:

Cause:

Action:

Cause:

Action:


2-12 47 A2 22UR Rev03

*** CMA-0018 A garbled type (xxx) is detected. Internal error whilebuilding the Symbol Table.

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

To fix the problem, contact your support team representative.

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

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

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

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

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.

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

*** CMA-0021 The predefined type has already been declared. (to be updatedwith SQL data types supported by OpenESQL if any)

There is a syntax error in the COBOL declaration.

One of the following INFORMIX predefined data types:

SQLCHAR, SQLNCHAR, SQLINT, SQLSMINT, SQLDATE, SQLDECIMAL,SQLMONEY, DATE_TYPE, VARCHAR, NVARCHAR, FILE

is defined twice in the variable declaration.

Correct the syntax of the SQL variable declaration. Refer to the INFORMIXdocumentation to get details about the data type declarations.

Cause:

Action:

Cause:

Action:

Cause:

Action:

Cause:

Action:


47 A2 22UR Rev03 2-13

*** CMA-0022 This predefined type has got an incorrect dimension value. (tobe updated with SQL data types supported by OpenESQL if any)

There is a syntax error in the COBOL declaration. This current INFORMIXpredefined data type has null dimensions.

Correct the syntax of the SQL variable declaration. To get details about the datatype declarations, refer to the INFORMIX documentation.

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

This is an internal error message.


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

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 CMA*TP sequence whichrequires all the CONNECT variables to be defined.

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

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

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 CMA*TP sequence whichrequires all the COMMIT variables to be defined.

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

Cause:

Action:

Cause:

Action:

Cause:

Action:

Cause:

Action:


2-14 47 A2 22UR Rev03

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

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


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

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

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.

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

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.

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

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

Cause:

Action

Cause:

Action:

Cause:

Action:

Cause:


47 A2 22UR Rev03 2-15

However, the following statement is valid:

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

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

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

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.


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

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 VAR1 FROM TABLE1 WHERE...

A partial qualification is rejected by the SQL CMA Generator:

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

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

Action:

Cause:

Action:

Cause:

Action:


2-16 47 A2 22UR Rev03

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

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

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.

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


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



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



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



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



Cause:

Action:

Cause:

Action:

Cause:

Action:

Cause:

Action:

Cause:

Action:

Cause:

Action:


47 A2 22UR Rev03 2-17

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

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.

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

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


To fix the problem, contact your support team representative

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

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

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

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

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.

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

Cause:

Action:

Cause:

Action:

Cause:

Action:

Cause:

Action:


2-18 47 A2 22UR Rev03

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


To fix the problem, contact your support team representative

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

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.

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

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

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.

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

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

Some database precompilers do not allow the following standard COBOL featuresto be used in an SQL variable declaration: IS EXTERNAL IS GLOBAL RENAMES SYNCHRONIZED RIGHT

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

Correct the SQL variable declarations which use these COBOL features.

Cause:

Action:

Cause:

Action:

Cause:

Action:

Cause:

Action:


47 A2 22UR Rev03 2-19

2.2 SQL CMA Communications Interface: CMANET

CMANET is the software layer that cooperates with a communications protocolsupported by the mainframe and the W2K systems to provide a communicationsinterface 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 W2K 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 W2K platforms:

• 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 W2K, several classes of files are delivered to compile and link the usersources:

− The code independant 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 W2K, a TCP/IP listener is provided to accept the client connections and startthe appropriate SQL CMA application Server process(es).

− This listener is a W2K service «CMAservice.exe»: startup is automatic. Anyaction is to be done via Start-> Control Panel -> Administrative Tools ->Services. The default port is 9007 (refer to the file “services” in the directorysystem32\etc\drivers). You may modify the line that contains the string“cmaserver”. If you need debugging information, modify the delivered fileCmaDebug.txt and set debug=YES. In this case, the file “CMAservice.log”(in the TEMP directory) contains more information and all the CMAapplications are launched with the debug mode (all information is written infiles named “cmasql_<pid>.log” ,in the TEMP directory).


2-20 47 A2 22UR Rev03

− Another executable «CMAlistener.exe» is delivered, and may be launched onanother port (option port = ) and with the option debug. Start it with Start ->Programs -> CMA - SQLserver -> CmaOptionalListener. An executable“CMAstop.exe” is provided to stop the CMA listener(s) (Start it with Start ->Programs -> CMA - SQLserver -> 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 embedded SQL andthe CMANET files. It will use the ODBC API and the COBOL Runtime to executethe requests on the SQL server (ODBCRW32.DLL and CBLRTSS.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.

The SQL CMA Transactional mechanism is described completely in Chapter 5.

47 A2 22UR Rev03 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.


3-2 47 A2 22UR Rev03

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 of theline (Area B can extend up to character position 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 22UR Rev03 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 of theline (Area B can extend up to character position 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 22UR Rev03

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 2 generated SQL CMAsources intended to run on GCOS 7 and W2K 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, and

3. it generates the final SQL CMA sources.

As COBOL compilers on GCOS 7 are different from the Merant/Mico Focuscompiler used on W2K, SQL CMA must get the generated sources which are«compilable» on their respective systems. So, a data type mapping of the declaredvariables and some writing rules are necessary.


47 A2 22UR Rev03 3-5

3.2.1 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 (GCOS7)

COBOL TypesCMA Client Source(GCOS 7)

COBOL TypesCMA Server Source(W2K)

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 this data type cause the Merant/MicroFocus pre-compiler on W2K to generate an error.The single FLOAT COMP-1 on W2K 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 variables declaredwithin the user source. All other variables can accept any standard COBOL datatype as attribute. For the SQL variables, see the next paragraph.


3-6 47 A2 22UR Rev03

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 precompiler 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, that is, the same SQLvariable name must not be used in 2 declarations.

Below are the restrictions on «DECLARE SECTION» prescribed by the DatabaseSuppliers and SQL CMA.

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 2 different SQLvariables:

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

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


47 A2 22UR Rev03 3-7

3.3.1.2 Comments

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

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

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

*COMMENT for VAR1 01 VAR1 PIC X(10). /COMMENT for VAR2 01 VAR2 PIC X(11). 01 VAR1 PIC X(10). -- COMMENT for VAR1 01 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.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-8 47 A2 22UR Rev03

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.

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

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 «:» or a dollar sign «$».

For example:

:SQLVARor$SQLVAR

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


47 A2 22UR Rev03 3-9

3.3.2.1 Comments

COBOL comment lines may be placed within SQL statements. Comment lines startwith an asterisk in the «identificator 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.

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-10 47 A2 22UR Rev03

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.

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.


47 A2 22UR Rev03 3-11

NOTE:The use of subscripted array elements in a SQL CMA source causes thefollowing warning while compiling the generated Server source: (TBC)

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

You may ignore this compilation warning.

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.


3-12 47 A2 22UR Rev03

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

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.


47 A2 22UR Rev03 3-13

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

EXEC SQL INCLUDE <server_file> END-EXEC. in Generated Server source.

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

A user source must include the «SQLCA» ANSI-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 SQLCAINF_<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 SQLCAINF_<CBX|COB|DAT>. in Generated Client source.COPY SQLCA. in Generated Server source.


3-14 47 A2 22UR Rev03

3.4.2 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 W2K 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 Client source.EXEC SQL INCLUDE svr_filename END-EXEC. in Generated Server source.

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.

Path names are defined differently on GCOS and W2K. An INCLUDE pathnamewould not be processed by the SQL CMA Generator unless all the referencedINCLUDE filenames are present in the «cmainst» Install directory at SQL CMASource Generation. The SQL CMA Generator scans only this local directory.

NOTE:The SQL CMA Generator does not allow a COBOL program to be nested inanother COBOL program, that is, there must be only one IDENTIFICATIONdivision in the user source analyzed by SQL CMA Generator. So, an INCLUDEfile must not include a COBOL program with an IDENTIFICATION division.


47 A2 22UR Rev03 3-15

3.4.3 SQLCA Structure

After each SQL statement executes, the database kernel returns the ANSI-SQLSQLCA 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, that is, 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 SQL Server error code of the executed SQLstatement.

0 The statement ran without error.1 The statement ran, but an exception was generated.100 A FETCH statement was issued, but no more rows satisfy the SELECTstatement criteria used to define the cursor. No rows were processed.< 0 (negative) The statement did not run due to an application, database, system, ornetwork error.

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

SQLERRP: Holds internal information.

SQLERRD:

Array of six integer status codes (codes not in the fields listed later are reserved).sqlerrd[1] Microsoft® SQL Server™ error number.sqlerrd[2] SQL Server severity level.sqlerrd[3] Number of rows affected.sqlwarn Eight warning flags, each containing a blank or W

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

SQLSTATE: run-time error codes.

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 «SQLCAINF_<CBX|COB|DAT>» files.


3-16 47 A2 22UR Rev03

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

«COPY SQLCAINF_<CBX|COB|DAT>»

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

The SQLCAINF 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 SQLCAINF fields, it is notpossible for a user source to reference other data specific to a database supplier.

3.5 SQL CMA Applications

A user application including SQLserver management capabilities must be writtenin compliance with the standard SQLserver documentation:

• Documentation in line of Microsoft SQLServer: Syntax, Tutorial and Reference

• 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 DATABASE Object Names

The following syntaxes are ambiguous for SQL CMA:To avoid ambiguity in a SQL variable reference (because of the colon «:»), youmust write the above syntaxes with a double «:» as follows:

database::identifier database::owner.identifier database::’owner’.identifier

database@dbservername::identifier database@dbservername::owner.identifier database@dbservername::’owner’.identifier

SQL CMA generates the right syntax in the SQL CMA Client and Server sources.

Be careful to respect this SQL CMA rule. Otherwise, the single colon analysismeans a SQL variable is looked for.


47 A2 22UR Rev03 3-17

3.5.2 Restrictions on Declare Statement

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

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.

EXAMPLE (NON-SUPPORTED SQL SEQUENCE):

The following SQL sequence is not supported:

EXEC SQL DECLARE CURSOR1 CURSOR FOR SELECT COL1, COL2, COL3 INTO :VAR1, :VAR2, :VAR3 FROM TABLE1 WHERE COL1 = ‘A’END-EXEC.EXEC SQL OPEN CURSOR1 END-EXEC.EXEC SQL FETCH CURSOR1 END-EXEC.

EXAMPLE (REPLACEMENT SQL SEQUENCE):

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

EXEC SQL DECLARE CURSOR1 CURSOR FOR SELECT COL1, COL2, COL3 FROM TABLE1 WHERE 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, COL3 FROM TABLE1 WHERE COL1 = ‘A’>>END-EXEC.


3-18 47 A2 22UR Rev03

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.

This restriction on the «DECLARE CURSOR» statement is applied only if theoutput SQL variables are referenced inside. However, SQL CMA supports a«DECLARE CURSOR» statement including input SQL variables.

47 A2 22UR Rev03 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 andWINDOWS (NT4, 2000).

A SQL CMA Installer (cmainst.exe) is provided on windows to administer SQLCMA. This consists of generating the SQL CMA sources and building the SQLCMA Server executable on WINDOWS (NT4, 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 Merant/Micro Focus COBOLcompiler to be installed (it uses the COBOL compiler with the OpenESQL option,cbllink and cobol runtime) and also a C compiler (Visual C++ version 6.0, optionstandard)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

• Starting SQL CMA Client building on the Mainframe


4-2 47 A2 22UR Rev03

4.1 Setting Environment Variables

1 environment variable (CMA_HOME_SQL) is set or updated by Install Shield forthe SQL CMA Installer product. It concerns the SQL CMA product.

4.1.1 Merant/Micro Focus Product

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

No update of path, lib or include with the version CMA SQLserver 1.2.0.0: theCMA installer will read information in the register.

4.1.2 C compiler Product

A standard installation of the Visual C++ Compiler version 6.0 is requested withupdate of the environment variables (lib, include, path).

4.1.3 SQL-server Product

A standard installation of the SQL server version 7.0 on windows NT4 or 2000 issufficient when building applications BATCH mode.

If the TDS mode is used, a specific table CMATP must be created on eachdatabase (it is used via ESQL in the TDS application).You may use the “request analyser” of the SQLserver product and open the fileSQL-CMATP.sql (delivered in the directory “C:\Program Files\Bull\CMA-SQLserver\Cmagen”).

4.1.4 SQL CMA Product

The CMAservice (and the optional CMAlistener) need the CMA_HOME_SQLvariable to be defined. It is used during the execution phase, and specifies thedirectory that contains the CMA application executables and dll.

If the CMA product is downloaded on the directory“C:\Program Files\Bull\CMA-SQLserver”, Install shield builds a specificenvironment variable CMA_HOME_SQL with the value“C:\Program Files\Bull\CMA-SQLserver\Cmanet\CmaExec”.

SQL CMA Installer

47 A2 22UR Rev03 4-3

4.2 CMA Product

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

If default value, the executable cmainst.exe is in the directory“C:\Program Files\Bull\CMA-SQLserver \Cmagen”

Install Shield builds a shortcut named “CMAinst” in“Start -> Programs ->Cma-Sqlserver”.

Refer to par SAMPLE for complete information.

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

The product cmainst will:

• propose a working directory“C:\Program Files\Bull\CMA-SQLserver \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 *.cbl) in it and get youroutput files (client files, server executable,…) in it.

• propose a logfile directory

In the generation phase,

• launch the cmag-SQLserver.exe with appropriate parameters

In the server building phase,

• retrieve the includes files (cmabuf.h,cmacst.h, dllCMANET.h),the copy cobol file (CMA_h.CPY)and the source file cmasvr.cin the directory “C:\Program Files\Bull\CMA-SQLserver \Cmagen\INCLUDE”

• retrieve the library file dllCMANET.libin the directory “C:\Program Files\Bull\CMA-SQLserver \Cmagen\lib”

• launch the cobol (for each input file) and cbllink with appropriate parameters

• launch cl and link with appropriate parameters


4-4 47 A2 22UR Rev03

4.2.1 Interactive Program cmainst.exe

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

These actions can be performed by selecting the right options proposed on the mainscreen. Each SQL CMA action collects its own input parameters by displayingsome request screens. The SQL CMA Source Generation proposes a recapitulativescreen before starting the requested operation.

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.

4.3 Starting SQL CMA Source Generation

As mentioned previously, from a user program, the SQL CMA Source generationbuilds two output programs:

• a SQL CMA client source, and

• a SQL CMA server source.

Each user program is characterized by several parameters such as:

• The DATABASE to access: Microsoft SQL server

• 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 screen relative to the SQL CMA source generation needs the followingparameters to be input in order to find out the user program characteristics.

SQL CMA Installer

47 A2 22UR Rev03 4-5

4.3.1 «FILE of SOURCE list» and «SOURCE NAME» 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.cbl

For COBOL source code, the format is CBX.

To get an explanation of this COBOL format, refer to Chapter 3.

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

File of SOURCE List for SQL server (Mylist.txt)

prog1.cblprog2.cblprog3.cblprog4.cbl

With the browse button, you may change select input file or inputlist in any directory : 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-6 47 A2 22UR Rev03

4.3.2 «APPLICATION RUNNING MODE» 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 mode» 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.

The Default value for this parameter is the batch mode.

4.3.3 «SQL CMA DEBUG» 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 Debugging

• Symbol Table Building

• Symbol Research Debug

The default value for this parameter is NO DEBUG.

SQL CMA Installer

47 A2 22UR Rev03 4-7

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

The Logging file is overwritten for each SQL CMA option. This prevents it fromgrowing rapidly and taking too much memory space.

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 «C:\WINNT\Temp\cmainst.log».

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

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

Access to << SQL server>> Database. COBOL Language with CBX format.

Running in <<BATCH>> mode.

No DEBUG mode during the source generation.

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


4-8 47 A2 22UR Rev03

4.4 Starting SQL CMA Server Building

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

The SQL CMA Installer performs the following steps to build the Serverexecutable on W2K

• 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). It usesan 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 a SQL server database environment (libraries, include files, ...) isinstalled locally and is accessible from the SQL CMA Installer.

Microsoft SQL server Environment

To install the SQLserver database environment correctly, refer to the appropriatedatabase documentation.

To install the Merant / Micro Focus environment, refer to the productdocumentation.

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

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

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

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

SQL CMA Installer

47 A2 22UR Rev03 4-9

4.4.1 «SERVER BINARY NAME» Parameter

This parameter identifies the SQL CMA Server program which will be started onwindows in order to communicate with the SQL CMA Client program running onthe mainframe. This program will process SQL statements when requested by theSQL 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 notcommunicating 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 the right partner.

This parameter is a string limited to 20 characters maximum.

4.4.2 «FILE of SOURCE list» and «RADIX OF THE OBJECT FILE» Parameters

During the SQL CMA Server building, the SQL CMA Installer needs the SQLCMA source name. The radix of «file1.cbl» 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.cbl prog2.cbl

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


4-10 47 A2 22UR Rev03

• 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 W2K, whose name is defined bythe «SERVER BINARY NAME» parameter.

4.4.3 «APPLICATION RUNNING MODE» Parameter

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

• BATCH mode, or

• 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 TP mode.

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.

The Logging file is overwritten for each SQL CMA option. This prevents it fromgrowing rapidly and taking too much memory space.

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 «C:\WINNT\Temp\cmainst.log». If desired,you can choose another logging file name or directory.

SQL CMA Installer

47 A2 22UR Rev03 4-11

4.5 Starting SQL CMA Client Building

This operation must be performed after the SQL CMA Server building operationbecause 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.

4.5.1 Building a SQL CMA COBOL Client in Batch Mode

How to build a CMA for SQL server Client is best explained by an example:

Suppose that there are two user SQL server COBOL sources named:

«appli1.cbl»

and

«appli2.cbl»

which compose a BATCH application named:

«appli»

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»

Building Procedure

You build «appli» on a GCOS 7 mainframe as follows:

1. Transfer all the SQL CMA Client files (data and code) to a «SL» Sourcelibrary on the mainframe. The files are:

«appli1cli_cob»,«appli1cli_h»,«appli2cli_cob»,«appli2cli_h»

For COBOL files, the COBOL format (CBX,COB,DAT) must be respectedduring the transfer. To get details about these GCOS 7 COBOL formats, referto Chapter 3.


4-12 47 A2 22UR Rev03

2. Transfer the SQL CMA COBOL include files from«SYS.DCM.CMA.INCLUDE» to a user «SL» library (lang=CBX). The filesare:

«SQLCAINF_CBX»«cma_cbx_h»

3. Compile the two SQL CMA Client sources: «appli1cli_cob», «appli2cli_cob»on the mainframe (according to the COBOL compiler rules).

4. Link the two SQL CMA object files in an «LM» Load Module library withthe clause USEDSM=H_SM_DCM in the Link Job (JCL).

«H_SM_DCM» is included in «SYS.DCM.SYSTEM» and must beLOADED with MNSYS (Maintain System). This step may be added bythe GCOS7 System Administrator in the system startup.

5. The resulting «LM» can be executed as a standard GCOS 7 application.

4.6 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 successfull, 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 22UR Rev03 4-13

4.7 SQL CMA Installer Errors

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

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

Choose a shorter name to identify the Server executable.

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

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‘_’.

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

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

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

Check that the SQL CMA Generator executable is:

• accessible to the system (Pathname declared correctly).

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

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

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.

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

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

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

Cause:

Action:

Cause:

Action:

Cause:

Action:

Cause:

Action:

Cause:

Action:


4-14 47 A2 22UR Rev03

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

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.

Change the duplicate filename.

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

The SQL CMA Installer recognizes only the standard suffix “.cbl” to identify a userapplication.

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

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

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.

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.

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.

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

Cause:

Action:

Cause:

Action:

Cause:

Action:

Cause:

Action:

SQL CMA Installer

47 A2 22UR Rev03 4-15

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

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.

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

he following Error messages are internal messages. If you get one of them, contactyour 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.

Cause:

Action:


4-16 47 A2 22UR Rev03

�

47 A2 22UR Rev03 5-1

5. 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 TP7 terminology and functionality. If necessary,refer to the standard TP7 Administrator’s and User’s Guides to get the generalinformation.

5.1 Building a SQL CMA TP Application

You must perform the following actions:

1. Write the SQL CMA TP application including the Embedded SQL statementsaccording to the rules described in Chapter 3.

2. Process the SQL CMA TP application on W2K using the SQL CMAGenerator and the SQL CMA Installer. Refer to the paragraph «SQL CMAGenerator» in Chapter 2 and the paragraph «SQL CMA Installer» inChapter 4.

3. Transfer the Generated SQL CMA Client sources (concerning the SQL CMATP application) to the «SL» source library on the mainframe. The files are:

«xxxcli_cob» «xxxcli_h»

Respect the COBOL format (CBX) during the transfer. For details about theseGCOS 7 COBOL formats, refer to Chapter 3.

4. Transfer the SQL CMA COBOL include files from«SYS.DCM.CMA.INCLUDE» to a user «SL» library. The files are:

«SQLCAINF_CBX» «cma_cbx_h»

5. Compile the SQL CMA Client sources on the mainframe (according to theCOBOL compiler rules).


5-2 47 A2 22UR Rev03

6. Link the SQL CMA TP application into a TPR sharable module as follows:

LINK_PG LM=<appli_name> SM=1 INLIB=<appli_culib> COMPFILE=<TP7_name>.sllib..TP7LINKTPR LIB=<TP7_name>.smlib

7. Load the TPR sharable module (and the H_SM_DCM sharable module, if notalready done) into backing store using MNSYS (SYSMAINT).

5.2 Preparing the TP7 Environment

You must inform the TP7 monitor that a SQL CMA Application will run in TPmode.

5.2.1 Modifications in the STDS: «CMA SERVICE USED» Clause and ATTACHSHARABLE MODULE

The following clause must be inserted in the STDS file at Generation time (afterthe clause SIMULTANEITY) :

ATTACH SHARABLE MODULE H_SM_DCM.

In the TRANSACTION SECTION, the «CMA SERVICE USED» clause allowsthe transaction to access the databases on the remote NT site.

The following clause must be inserted in the STDS file at Generation time:

CMA SERVICE USED

In the TRANSACTION SECTION, the «CMA SERVICE USED» clause allowsthe transaction to access the databases on the remote W2K site.

EXAMPLE:

MESSAGE "TPSELECT" ASSIGN TO TPSELECTCMA SERVICE USEDAUTHORITY-CODES ARE 0,1.

Using SQL CMA in Transactional Mode

47 A2 22UR Rev03 5-3

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

For example CMASTLIB=SI7-OP53.DCM.SYSTEM;

5.3 Preparing the SQL CMA TP Environment

Some actions must be performed on the mainframe and on W2K before running aSQL CMA TP application in the TP7 environment.

A specific transaction named «CMATDS» must be started in the TP7 environment.Some objects must be created in the databases accessed on the remote W2K server.

5.3.1 «CMATDS» Transaction

A SQL CMA Client application needs some input parameters such as «remoteW2K 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

The «CMATDS» transaction could be then started as follows:

CMA CMAHOST=<server> CMAPORT=<port_number>[TRACE=OFF/ON] [CLEAR=YES/NO]

where:

<server> is the W2K server machine.

<port_number> is the TCP/IP port number on which a SQL CMAservice (or an optional CMA listener) is connected.


5-4 47 A2 22UR Rev03

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

The «CMATDS» transaction must be performed each time the input parametersdefining the remote W2K site change.

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.

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.

5.3.2 Database Object for TP Mode: CMATP

To use the SQL CMA TP facilities, each SQL SERVER database needs a specialtable: CMATP. This table is described in the member: CrtabCMATP.sql , which isprovided in the directory C:\Program Files\Bull\CMA-SQLserver\CmaGen on theW2K server.You must execute Crtab-CMATP.sql under the SQLserver query analyseror osql program (syntax: osql –u <user> -P <password> -i CrtabCMATP.sql).

This file contains:

<<<<<<

CREATE TABLE CMATP

( USID CHAR(20),

TID INTEGER );

CREATE UNIQUE INDEX CMATPIDX ON CMATP (USID);

GRANT ALL ON CMATP TO PUBLIC;

>>>>


47 A2 22UR Rev03 5-5

5.4 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 TP7 environment.

5.4.1 SQL CMA TP Cache Concept

5.4.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 identificationConnection nameUser/Password clause

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

Some SQL CMA terms must be defined:

SQL CMA TP Connection Entryspecifies 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 TP7 commitment unit until it ends.


5-6 47 A2 22UR Rev03

SQL CMA TP Context Cacheis 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 TP7.

These objects are handled inside a TP7 commitment unit. The CONNECT action isanalyzed to determine if the connection is a Physical or a Database or a Logicalconnection.

5.4.1.2 SQL CMA TP Context States

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

A SQL CMA TP Context has several states:

UNUSED There are no physical connections, the SQL CMA TP Context isjust initialized.

FREE The SQL CMA TP Context is free and may be used by a TP7commitment unit. The SQL CMA TP Context keeps a PhysicalConnection and some Database Connections established betweenthe Client and Server sites.

BUSY The SQL CMA TP Context is already used by a TP7 commitmentunit and is no longer available for another TP7 commitment unit.The SQL CMA TP Context keeps a Physical Connection andsome Database Connections established between the Client andServer sites.

DAMAGED The SQL CMA TP Context is garbled, so it is declaredunavailable during the execution of the current commitment unit.The SQL CMA TP Contexts signalled as DAMAGED are allcleaned (UNUSED state) at the end of the commitment unit.

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


47 A2 22UR Rev03 5-7

5.4.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 TP7 commitment unit.

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

5.4.2.1 CONNECT Action Provided by SQL SERVER

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

EXEC SQL CONNECT TO <database_env>

AS <con_name> [USER login[.password ]

END-EXEC.

where: <database_env>, <con_name>, <user>, and <pwd_name> are strings of30 bytes long

To get more details about these SQL statements and their parameters, refer to thestandard «SQL SERVER Guide to SQL» manual.

The "EXEC SQL CONNECT" statement is the only one allowed to establish aconnect with an SQL SERVER database in transactional mode.

5.4.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 TP7 Commitment Unit:

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

1. The Context Cache Manager searches a SQL CMA TP Context signalled 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 TP7commitment unit until it ends, so the context is declared BUSY.

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


5-8 47 A2 22UR Rev03

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 TP7 Commitment Unit:

1. The Context Cache Manager gets the SQL CMA TP Context allocated by thefirst CONNECT action in the TP7 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 TP7 commitment unit.

5.4.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, that is,their states 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.

5.4.3 Commitments

The CMA application server is built from a cobol source with embedded SQL andthe CMANET files. It will use the ODBC API to execute the requests on theSQLserver.

This ODBC API does not take in account explicit transactions but only transactionsin automatic and implicit validation mode.

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


47 A2 22UR Rev03 5-9

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.

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

5.4.4 COMMIT Action

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

SQL CMA TP imposes that the commitment 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.


5-10 47 A2 22UR Rev03

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

5.4.4.2 Explicit Commitment

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

The TP7 «DFCMIT» procedure acts according to the TP7 rules, that is, 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 last database referenced just before the SQLCOMMIT statement.

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

5.4.4.3 SQL COMMIT Statement Provided by SQL SERVER

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

EXEC SQL COMMIT WORK END-EXEC.

To get more details about this SQL statement, refer to the standard manual «SQLSERVER Guide to SQL».


47 A2 22UR Rev03 5-11

5.4.4.4 Examples of Commit Actions

Here are examples of different commitment actions.

The following commitment units update two SQL SERVER databases: DB1 andDB2.

EXAMPLE 1: Commitment using ‘DFCMIT’

IDENTIFICATION DIVISIONPROGRAM-ID. XXX....EXEC SQL CONNECT TO ‘server.DB1’ AS ‘A’ END-EXEC....EXEC SQL CONNECT TO ‘server.DB2’ AS ‘B’ END-EXEC....EXEC SQL SET CONNECTION ‘A’ END-EXEC.EXEC SQL INSERT INTO T1 VALUES (100) END-EXEC....EXEC SQL SET CONNECTION ‘B’ END-EXEC.EXEC SQL 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 TO ‘server.DB1’ AS ‘A’ END-EXEC....EXEC SQL CONNECT TO ‘server.DB2’ AS ‘B’ END-EXEC....EXEC SQL SET CONNECTION ‘A’ END-EXEC.EXEC SQL INSERT INTO T1 VALUES (100) END-EXEC....EXEC SQL SET CONNECTION ‘B’ END-EXEC.EXEC SQL INSERT INTO T2 VALUES (100) END-EXEC....EXEC SQL COMMIT WORK END-EXEC....EXIT.


5-12 47 A2 22UR Rev03

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

EXAMPLE 3: Commitment using several ‘SQL COMMIT’

IDENTIFICATION DIVISIONPROGRAM-ID. XXX....EXEC SQL CONNECT TO ‘server.DB1’ AS ‘A’ END-EXEC....EXEC SQL CONNECT TO ‘server.DB2’ AS ‘END-EXEC....EXEC SQL SET CONNECTION ‘A’ END-EXEC.EXEC SQL INSERT INTO T1 VALUES (100) END-EXEC....EXEC SQL COMMIT WORK END-EXEC....EXEC SQL SET CONNECTION ‘B’ END-EXEC.EXEC SQL INSERT INTO T2 VALUES (100) END-EXEC.EXEC SQL COMMIT WORK END-EXEC....EXIT.

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

5.4.4.5 Automatic Restart

The automatic restart facility is activated when a commitment fails.

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


47 A2 22UR Rev03 5-13

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

5.4.5 ROLLBACK Action

Unlike the COMMIT action, a ROLLBACK action is always synchronouslyexecuted, that is, 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.

5.4.5.1 ROLLBACK Statement Provided by SQL Server

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

EXEC SQL ROLLBACK [WORK] END-EXEC.

To get more details about this SQL statement, refer to the standard «SQL SERVERGuide to SQL» manual.


5-14 47 A2 22UR Rev03

5.4.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 ‘server.DB1’ AS ‘A’ 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 TO ‘server.DB1’ AS ‘A’ END-EXEC....EXEC SQL CONNECT TO ‘server.DB2’ AS ‘B’ END-EXEC....EXEC SQL SET CONNECTION ‘A’ END-EXEC.EXEC SQL INSERT INTO T1 VALUES (100) END-EXEC....EXEC SQL SET CONNECTION ‘B’ END-EXEC.EXEC SQL INSERT INTO T2 VALUES (100) END-EXEC....EXEC SQL ROLLBACK WORK END-EXEC....EXEC SQL SET CONNECTION ‘A’ END-EXEC.EXEC SQL COMMIT WORK END-EXEC....EXIT.


47 A2 22UR Rev03 5-15

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

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.

5.4.5.3 Relationship between ROLLBACK Action and SQL CMA TP Context

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

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


5-16 47 A2 22UR Rev03

5.6 SQL CMA TP Error Codes

*** SQLCODE = -1

A system error is returned during memory space allocation or memory access.

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.

*** SQLCODE = -2

All the TDS cache entries are used.

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

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.

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

*** SQLCODE = -6

The same kind of failure occurs but TP7 could not successfully re-connect to theremote database. It is not possible to get the COMMIT status returned by thedatabase server.

It is not possible to get the real COMMIT status. Therefore, you must use othermeans to check the data integrity between the database and TP7.

Cause:

Action:

Cause:

Action:

Cause:

Action:

Cause:

Action:


47 A2 22UR Rev03 5-17

*** SQLCODE = -11

The current SQL CMA TP Context is inconsistent for an internal reason. The SQLCMA TP Context is set to DAMAGED.

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

The automatic restart following a COMMIT failure has failed.


*** SQLCODE = -23

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.

Check that the CMATP table is created correctly in the accessed database andrestart the SQL CMA TP application.

*** SQLCODE = 10

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.

Not Applicable.

Cause:

Action:

Cause:

Action:

Cause:

Action:

Cause:

Action:


5-18 47 A2 22UR Rev03

*** SQLCODE = 111

The SQL CMA product is incorrectly installed.

The Marketing Identifier is not available.


Cause:

Action:

47 A2 22UR Rev03 6-1

6. Starting SQL CMA Processes

This chapter explains how to start the SQL CMA processes on the client mainframeand on the W2K server (or NT4 server).1

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

• A SQL CMA Service (W2K service : CMAservice.exe) is started on W2K tolisten for incoming 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 W2K.

For the SQL CMA processes to communicate with each other, a communicationsprotocol is necessary for one node to transfer information to another.

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

• Starting SQL CMA Client Process

1 In this chapter, “W2K server” is used for both W2K and NT4 versions


6-2 47 A2 22UR Rev03

6.1 Configuring the Machines

The mainframe and the W2K server, that are involved in the network, must beconfigured 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) 2

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

6.2 Starting SQL CMA Service

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

This CMAservice is 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 W2K server,in order to debug new applications without impact on the production applications:refer to par 6.2.3 for more information

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

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

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

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

Starting SQL CMA Processes

47 A2 22UR Rev03 6-3

6.2.2 CMAservice in Debug Mode: File “CMAdebug.txt”

CMAservice is launched when the W2K starts (W2K 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 evnt 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\CmaExec.

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>5\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 par 6.3 for more information.

6.2.3 Starting Optional CMAlistener

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

Install Shield adds shortcuts for the product CMA-SQLserver (cmainst andCMAlistener) in START -> PROGRAMS . You may add any parameters to theshortcut CMAlistener (change properties ->target "C:\Program Files\Bull\CMA-SQLserver\Cmanet\CMAlistener.exe" debugport=6349)

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

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


6-4 47 A2 22UR Rev03

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 as follows:<string> 1000/tcp

no port is defined: The service name «cmaserver» must be declared inC:\WINNT\system32\drivers\etc\services as follows: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.

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.


47 A2 22UR Rev03 6-5

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 have to beconnected on different port numbers.

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


6-6 47 A2 22UR Rev03

6.2.5 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 22UR Rev03 6-7

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

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 1.0.0. Production: Logging file.

Started at 19-APR-96 14:25:16:CMA_HOME_SQL is ”C:\WINNT\CMA”LOGGING mode is ENABLED. DEBUG mode is DISABLED.

19-APR-96 14:25:16 Waiting for connection request on port 5002...

Stopped at 19-APR-96 14:25:24_________________________________________________________________


6-8 47 A2 22UR Rev03

EXAMPLE OF A LOG FILE WITH THE DEBUG OPTION:

_________________________________________________________________

C.M.A. Network Server 1.0.0. Production: Logging file.

Started at 19-APR-96 14:25:16:

CMA_HOME_SQL is C:\WINNT\CMA”

LOGGING mode is ENABLED. DEBUG mode is ENABLES.

19-APR-96 14:25:16 Waiting for connection request on port 5002...

**************************

26-MAR-96 14:01:10 DEBUG: Client network address is 129.182.131.27.

26-MAR-96 14:01:11 DEBUG: Remote connection is required from <<bc09>> site.

26-MAR-96 14:01:11 DEBUG: Received buffer: length=0, index=0.

26-MAR-96 14:01:11 DEBUG: Get remote message of 20 bytes long.

26-MAR-96 14:01:11 DEBUG: Get <<server_name>> network message:

Length=20

26-MAR-96 14:01:11 DEBUG: Starting the application: demo1 (5,1)

Process Id = 38262

26-MAR-96 15:55:46 DEBUG: Application Process (38262) died with exitcode=0.

**************************

_________________________________________________________________

6.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). ***

A TCP/IP error was returned during the port search.

The «getservbyname» TCP/IP function was invoked.

Analyze the error code value to get the failure reason.

***CMAlistener: can’t create socket (error code =xxx). ***.

A TCP/IP error was returned during the socket creation. The «socket» TCP/IPfunction was invoked.


Cause:

Action:

Cause:

Action:


47 A2 22UR Rev03 6-9

***CMAlistener: can’t bind to socket (error code =xxx). ***

A TCP/IP error was returned during the socket binding. The «bind» TCP/IPfunction was invoked.


***CMAlistener: port address already in use. ***

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 .

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

The CMA_HOME_SQL environment variable is not defined. The SQL CMAListener will uses the default patch CMA/Cmanet/Cmaexec. To get informationabout this variable, refer to the «Setting environment variable» paragraph.

Declare this variable in the W2K environment (refer to MSDN)

***CMAlistener: unable to open logfile ’xxx’. ***

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.

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.

Cause:

Action:

Cause:

Action:

Cause:

Action:

Cause:

Action:


6-10 47 A2 22UR Rev03

*** usage: CMAlistener [debug] [port=<port number or service name>] ***

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.

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

The «CMAlistener» failed to accept the connection from the client process.


*** Error while starting ‘yyy’ application (error code=xxx). ***

A system error was returned by W2K during a process creation. The“CreateProcess” function was invoked.

Analyze the error code value returned by W2K to get the failure reason.

*** Error while reading ‘yyy’ network message (error code =xxx). ***

A system error was returned by W2K during a socket reading. The «read» systemfunction was invoked.

‘yyy’ indicates what kind of message was expected.

Analyze the error code value returned by W2K to get the failure reason.

Cause:

Action:

Cause:

Action:

Cause:

Action:

Cause:

Action:


47 A2 22UR Rev03 6-11

6.5 Starting SQL CMA Client Process in BATCH Mode

When a SQL CMA listener is running on the W2K Server, a SQL CMA Client canconnect to the server system.

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

Check that «H_SM_DCM» is loaded from «SYS.DCM.SYSTEM» before startingany SQL CMA Client application.

Here is an example of how to start the Client BATCH job: «appli»

exec_pg appli lib=cma.V1.lmoptions=’CMASERVER_HOST=trifide CMASERVER_PORT=1790 ‘

6.6 Starting SQL CMA Client Process in TP Mode

A SQL CMA TP application is started such as described in the standard TP7Administrator’s and User’s Guides.


6-12 47 A2 22UR Rev03

6.7 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 W2K server, to hold the errors detected during the SQL CMA exchanges (Datasending 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 22UR Rev03 6-13

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

A TCP/IP error was returned during the socket creation. The «socket» TCP/IPfunction was invoked.

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

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

Correct the command line which invokes the CMASERVER_HOST andCMASERVER_PORT parameters and update «/etc/hosts» if necessary.

*** -9503 ***

A TCP/IP error was returned during the socket connection. The «connect» TCP/IPfunction was invoked.

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.

Cause:

Action:

Cause:

Action:

Cause:

Action:


6-14 47 A2 22UR Rev03

*** -9504 ***

A TCP/IP error was returned while the socket availability is being checked. The«cmaget_sockcli» CMA function was invoked.


*** -9505 ***

A TCP/IP error was returned during the socket writing. The «send» TCP/IPfunction was invoked.

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


*** -9506 ***

A TCP/IP error was returned during the socket reading. The «recv» TCP/IPfunction was invoked.

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

Timeout error. The communication between CMA client and server is not possiblefor Network problems.

Contact your Network support.

*** 111 ***

The SQL CMA license is not available so, the current product could not be used.

Check that the Marketing Identifier of SQL CMA is correctly installed on thesystem.


Cause:

Action:

Cause:

Action:

Cause:

Action:

Cause:

Action:

Cause:

Action:

47 A2 22UR Rev03 A-1

A. Sample

A.1 Description

This example MFSELECT is based on the file mfselect.cbl that contains ESQLstatements.

It illustrates the use of SELECT...INTO and cursor based data retrieval(DECLARE, OPEN, FETCH, CLOSE).

It requires the data source “AbSqlServer”, system DSN with ODBC driver = localSQLserver, user=sa, null password and “default database = pubs”. MFSELECTassumes a AUTHORS table is available at the data source.

MFSELECT connects to the database and retrieves and displays the row forau_lname =’White’ from the AUTHORS table using a SELECT...INTO statement.It then retrieves and displays rows for all customers in the state ‘CA’.

A.2 CMA Install: Sources Generation and Server Building

This file mfselect.cbl (in the directory C:\PROGRAM FILES\BULL\CMA-SQLSERVER\CmaGen\work) is processed by the application tool cmainst.exe(accessed by Start -> Programs -> CMA-SQLserver -> cmainst or directly in thedirectory C:\PROGRAM FILES\BULL\CMA-SQLSERVER\CmaGen) on theW2K system with 2 phases.

1. The first phase is the “SQL C.M.A Source Generation”: it uses theapplication cmag-SQLserver.exe. The required options areGCOS_MODE=BATCH (COBOL FORMAT is CBX). This process willprovide these files:

GCOS7 client files : mfselectcli_cob and mfselectcli_h.

These files will be modified in the second phase: don’t transfer them toGCOS7 from now.

W2K server files : mfselectsvr.cbl and cmadyn_MyExample.h.


A-2 47 A2 22UR Rev03

2. The second phase is the “SQL C.M.A Server building”: it uses the NetExpress product (Merant/Microfocus OpenESQL, COBOL compilers andCBLLINK) and the C compiler and linker.The required options are GCOS_MODE=BATCH and EXECUTABLE name= MyExample.

• This process will update the GCOS7 client files: mfselectcli_cob andmfselectcli_h. These files must be transferred on GCOS7 withCOBOL format = CBX during the transfer.The compilation requests that you access to the COPY COBOL files«SQLCAINF_CBX» and «cma_cbx_h» in the «SYS.DCM.CMA.INCLUDE»library.

Link the CU MFSELECT in an «LM» Load Module library with the clausesUSEDSM=H_SM_DCM, STARTASG=(PRIVATE=30) 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.

The resulting «LM» can be executed as a standard GCOS 7 application withoptions= ‘CMASERVER_HOST=frcls0507 CMASERVER_PORT=9007 ';

• The files mfselectsvr.cbl and cmadyn_MyExample.h (dynamically built bycmainst.exe) are used on the W2K system to build the server MyExample.exeand the Dynamic Link Library MyExample_Cobol.dll.The compilation requests some COPY COBOL files: CMA_H.CPY deliveredwith the CMA product (directory C:\PROGRAM FILES\BULL\CMA-SQLSERVER\CmaGen\INCLUDE) and SQLCA.CPY delivered with theMerant/Microfocus Net Express product.The link uses the files odbcrw32.lib, cblrtssi.lib and dllCMANET.lib.

C:\PROGRAM FILES\BULL\CMA-SQLSERVER\CmaGen>dir18/01/2001 18:00 180 224 cmag-SQLserver.exe29/01/2001 10:39 73 728 cmainst.exe26/01/2001 11:25 <DIR> INCLUDE26/01/2001 11:25 <DIR> LIB26/01/2001 09:37 152 SQL-CMATP.sql29/01/2001 12:57 <DIR> work

C:\PROGRAM FILES\BULL\CMA-SQLSERVER\CmaGen>dir LIB18/01/2001 17:20 3 264 dllCMANET.lib

C:\PROGRAM FILES\BULL\CMA-SQLSERVER\CmaGen>dir INCLUDE17/08/2000 14:42 989 cmabuf.h16/08/2000 16:23 2 193 cmacst.h26/01/2001 10:25 4 130 cmasvr.c07/09/2000 09:38 2 476 CMA_H.CPY19/09/2000 13:34 1 065 dllCMANET.h

Sample

47 A2 22UR Rev03 A-3

C:\PROGRAM FILES\BULL\CMA-SQLSERVER\CmaGen>dir work26/01/2001 11:16 10 043 dyno.cbl19/10/2000 10:02 3 134 mfselect.cbl18/12/2000 16:43 84 TPlist26/01/2001 15:16 3 544 TPstd01crtab.cbl26/01/2001 15:16 3 421 TPstd01drtab.cbl26/01/2001 15:16 3 792 TPstd01ins.cbl26/01/2001 15:16 3 985 TPstd01sel.cbl26/01/2001 15:16 3 690 TPstd01upd.cbl26/01/2001 16:33 296 TPstd01_scenario

This executable may be launched byStart -> Programs -> CMA-SQLserver -> CMAinst


A-4 47 A2 22UR Rev03

A.3 Application Generation

Sample

47 A2 22UR Rev03 A-5

When debug options, this screen allows to choice


A-6 47 A2 22UR Rev03

You have to confirm your options

Results messages are written in a console window.

If one error occurs during the source generation,

you will obtain this message box “generate sources failed **”and a message in the console window:

SQL C.M.A. SOURCE generation (file mfselect.cbl) has been processed.

**** Severe errors detected during CMA*GEN Analysis ****Refer to C:\WINNT\Tmp\cmagen.log" to get more information.

You have the same info in C:\WINNT\Tmp\\cmainst.log(if logfile directory = C:\WINNT\Tmp)

Read information in “cmagen.log” and change your input files.

If generation is successful:

message in the console window:

SQL C.M.A. SOURCE generation (file mfselect.cbl) has been processed.

>>> No errors detected during CMA*GEN analysis

Sample

47 A2 22UR Rev03 A-7

A.4 Server Building

Results messages are written in a console window.

If one error occurs during the server building:

you will obtain this message box “ Build Server failed **”

and a message in the console window:

SQL C.M.A "MyExample" SERVER Building has been processed. Start the SERVER Building: MyExample COBOL phase for mfselect

SQL C.M.A. "MyExample" SERVER Building has failed. Refer to "C:\WINNT\Tmp\cmainst.log" to get status information.


A-8 47 A2 22UR Rev03

If server building is successful:

message in the console window:

Start the SERVER Building: MyExample COBOL phase for mfselect cbllink phase compile cmasvr.c (cl phase) link phase >>> You have to transfer this executable MyExample.exe and the dll MyExample_Cobol.dll in the directory C:\Program Files\Bull\CMA-SQLserver\CmaNet\CmaExec

SQL C.M.A "MyExample" SERVER Building has been processed

You have to transfer this executable MyExample.exe andthe dll MyExample_Cobol.dll in the directory

C:\Program Files\Bull\CMA-SQLserver\CmaNet\CmaExec

The CMAservice search the CMA user applications in this directory (thatcorrespond to the Environment Variable CMA_HOME_SQL, set during theInstallShield phase).

C:\PROGRAM FILES\BULL\CMA-SQLSERVER\CmaGen>C:\PROGRAM FILES\BULL\CMA-SQLSERVER\CmaGen\work>ls /lrt C:\PROGRAM FILES\BULL\CMA-SQLSERVER\CmaGen\work\*.*--a-- 3134 Thu Oct 19 10:02:36 2000 mfselect.cbl--a-- 84 Mon Dec 18 16:43:06 2000 TPlist--a-- 10043 Fri Jan 26 11:16:40 2001 dyno.cbl--a-- 3421 Fri Jan 26 15:16:02 2001 TPstd01drtab.cbl--a-- 3544 Fri Jan 26 15:16:02 2001 TPstd01crtab.cbl--a-- 3985 Fri Jan 26 15:16:04 2001 TPstd01sel.cbl--a-- 3792 Fri Jan 26 15:16:04 2001 TPstd01ins.cbl--a-- 3690 Fri Jan 26 15:16:06 2001 TPstd01upd.cbl--a-- 296 Fri Jan 26 16:33:19 2001 TPstd01_scenario--a-- 11980 Mon Jan 29 10:48:06 2001 mfselectcli_cob--a-- 106 Mon Jan 29 10:48:06 2001 mfselect.lst--a-- 5022 Mon Jan 29 12:56:44 2001 mfselectsvr.cbl--a-- 388 Mon Jan 29 12:56:44 2001 mfselectcli_h--a-- 24576 Mon Jan 29 12:56:47 2001 MyExample_Cobol.dll--a-- 32768 Mon Jan 29 12:56:51 2001 MyExample.exe

Sample

47 A2 22UR Rev03 A-9

A.5 Initial Source with ESQL in COBOL: mfselect.cbl

***************************************************************** Copyright (C) 1996-2000 MERANT International Ltd. All Rights Reserved* This demonstration program is provided for use by users of* MERANT products and may be used, modified and* distributed as part of your application provided that you* properly acknowledge the copyright of MERANT in this* material.**--------------------------------------------------------------- CONTROL DIVISION. DEFAULT SECTION. DISPLAY IS ALTERNATE CONSOLE. IDENTIFICATION DIVISION. PROGRAM-ID. MFSELECT.

* ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. DPS7. OBJECT-COMPUTER. DPS7.**Declare variables.* DATA DIVISION.

WORKING-STORAGE SECTION.

* Include the SQL Communications Area. This includes the* definitions of SQLCODE, etcEXEC SQL INCLUDE SQLCA END-EXEC

EXEC SQL BEGIN DECLARE SECTION END-EXEC. 01 paulname pic x(20). 01 paddress pic x(40). 01 pcity pic x(20). 01 pstate pic x(20).EXEC SQL END DECLARE SECTION END-EXEC.

* procedure division. main-para.EXEC SQL CONNECT TO "AbSqlServer" END-EXEC.* system DSN with ODBC driver = local SQLserver,user=sa* and "default database = pubs " loop-point. if sqlcode not = 0 display "Error: not connected" display sqlcode display sqlerrmc stop run end-if


A-10 47 A2 22UR Rev03

display ’Select ... into test’

display " " move ’White’ to paulnameEXEC SQL SELECT address, city INTO :paddress, :pcity FROM authors WHERE au_lname = :paulnameEND-EXEC

if sqlcode not = 0 if sqlcode = 100 display "No author found" else display sqlcode display sqlerrmc end-if else display "Address for " paulname " is " paddress display "City for " paulname " is " pcity end-if

display ’Cursor fetch test’

display " " move ’CA’ to pstateEXEC SQL DECLARE cust-curs CURSOR FOR select au_lname, address , city from authors where state = :pstate order by au_lnameEND-EXEC

EXEC SQL OPEN cust-curs END-EXEC

if sqlcode not = 0 display sqlcode display sqlerrmc else

display "authors in state " pstate

perform until sqlcode not equal to 0

EXEC SQL FETCH cust-curs INTO :paulname , :paddress, :pcity END-EXEC

display " "

if sqlcode = 100 display "End of results" end-if

Sample

47 A2 22UR Rev03 A-11

if sqlcode not = 0 display sqlcode display sqlerrmc else display "AUL_NAME " paulname display "ADDRESS " paddress display "CITY " pcity end-if

end-perform

end-if

EXEC SQL CLOSE cust-curs END-EXEC

EXEC SQL DISCONNECT CURRENTEND-EXEC if sqlcode not = 0 display sqlcode display sqlerrmc end-if

exit program.


A-12 47 A2 22UR Rev03

A.6 GCOS7 Client File: mfselectcli_cob (Produced byCMAG-SQLserver)

***************************************************************** Copyright (C) 1996-2000 MERANT International Ltd. All Rights Reserved* This demonstration program is provided for use by users of* MERANT products and may be used, modified and* distributed as part of your application provided that you* properly acknowledge the copyright of MERANT in this* material.**--------------------------------------------------------------- CONTROL DIVISION. DEFAULT SECTION. DISPLAY IS ALTERNATE CONSOLE. IDENTIFICATION DIVISION. PROGRAM-ID. MFSELECT.

* ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. DPS7. OBJECT-COMPUTER. DPS7.**Declare variables.* DATA DIVISION.

WORKING-STORAGE SECTION.

COPY cma_cbx_h. COPY mfselectcli_h.

* Include the SQL Communications Area. This includes the* definitions of SQLCODE, etc

* SQL stmt #1* EXEC SQL INCLUDE SQLCA END-EXEC COPY SQLCAINF_CBX.

* SQL stmt #2* EXEC SQL BEGIN DECLARE SECTION END-EXEC.

01 paulname pic x(20). 01 paddress pic x(40). 01 pcity pic x(20). 01 pstate pic x(20).

* SQL stmt #3* EXEC SQL END DECLARE SECTION END-EXEC.

Sample

47 A2 22UR Rev03 A-13

* procedure division. main-para.

* SQL stmt #4* EXEC SQL CONNECT TO "AbSqlServer" END-EXEC.

IF CMASOCKCLI EQUAL TO 0 THEN CALL "CMACONNECT" USING CMA-RETCODE CMASOCKCLI mfselectEXE END-IF

MOVE LENGTH OF mfselectEXE TO CMA-LENGTH CALL "CMAPUTPARAM" USING CMA-RETCODE CMA-SNDBUF CMA-RCVBUF CMASOCKCLI mfselectEXE CMA-LENGTH MOVE LENGTH OF mfselectID TO CMA-LENGTH CALL "CMAPUTPARAM" USING CMA-RETCODE CMA-SNDBUF CMA-RCVBUF CMASOCKCLI mfselectID CMA-LENGTH MOVE LENGTH OF mfselectstmt4 TO CMA-LENGTH CALL "CMAPUTPARAM" USING CMA-RETCODE CMA-SNDBUF CMA-RCVBUF CMASOCKCLI mfselectstmt4 CMA-LENGTH

MOVE LENGTH OF SQLCA TO CMA-LENGTH CALL "CMAGETPARAM" USING CMA-RETCODE CMA-SNDBUF CMA-RCVBUF CMASOCKCLI SQLCA CMA-LENGTH IF CMA-RETCODE NOT EQUAL 0 THEN MOVE CMA-RETCODE TO SQLCODE IN SQLCA MOVE LENGTH OF SQLERRMC IN SQLCA TO SQLERRML IN SQLCA CALL "CMANETERROR" USING SQLERRMC IN SQLCA SQLERRML IN SQLCA SQLCODE IN SQLCA MOVE 0 TO CMA-RETCODE END-IF MOVE 1 TO FOUND.

* system DSN with ODBC driver = local SQLserver,user=sa* and "default database = pubs " loop-point. if sqlcode not = 0 display "Error: not connected" display sqlcode display sqlerrmc stop run end-if

display ’Select ... into test’

display " " move ’White’ to paulname

* SQL stmt #5* EXEC SQL* SELECT address, city INTO :paddress, :pcity* FROM authors* WHERE au_lname = :paulname*END-EXEC

MOVE LENGTH OF mfselectEXE TO CMA-LENGTH


A-14 47 A2 22UR Rev03

CALL "CMAPUTPARAM" USING CMA-RETCODE CMA-SNDBUF CMA-RCVBUF CMASOCKCLI mfselectEXE CMA-LENGTH MOVE LENGTH OF mfselectID TO CMA-LENGTH CALL "CMAPUTPARAM" USING CMA-RETCODE CMA-SNDBUF CMA-RCVBUF CMASOCKCLI mfselectID CMA-LENGTH MOVE LENGTH OF mfselectstmt5 TO CMA-LENGTH CALL "CMAPUTPARAM" USING CMA-RETCODE CMA-SNDBUF CMA-RCVBUF CMASOCKCLI mfselectstmt5 CMA-LENGTH

MOVE LENGTH OF paulname TO CMA-LENGTH CALL "CMAPUTPARAM" USING CMA-RETCODE CMA-SNDBUF CMA-RCVBUF CMASOCKCLI paulname CMA-LENGTH

MOVE LENGTH OF SQLCA TO CMA-LENGTH CALL "CMAGETPARAM" USING CMA-RETCODE CMA-SNDBUF CMA-RCVBUF CMASOCKCLI SQLCA CMA-LENGTH MOVE LENGTH OF paddress TO CMA-LENGTH CALL "CMAGETPARAM" USING CMA-RETCODE CMA-SNDBUF CMA-RCVBUF CMASOCKCLI paddress CMA-LENGTH MOVE LENGTH OF pcity TO CMA-LENGTH CALL "CMAGETPARAM" USING CMA-RETCODE CMA-SNDBUF CMA-RCVBUF CMASOCKCLI pcity CMA-LENGTH IF CMA-RETCODE NOT EQUAL 0 THEN MOVE CMA-RETCODE TO SQLCODE IN SQLCA MOVE LENGTH OF SQLERRMC IN SQLCA TO SQLERRML IN SQLCA CALL "CMANETERROR" USING SQLERRMC IN SQLCA SQLERRML IN SQLCA SQLCODE IN SQLCA MOVE 0 TO CMA-RETCODE END-IF MOVE 1 TO FOUND

if sqlcode not = 0 if sqlcode = 100 display "No author found" else display sqlcode display sqlerrmc end-if else display "Address for " paulname " is " paddress display "City for " paulname " is " pcity end-if

display ’Cursor fetch test’

display " " move ’CA’ to pstate

* SQL stmt #6* EXEC SQL* DECLARE cust-curs CURSOR FOR* select au_lname, address , city from authors* where state = :pstate* order by au_lname*END-EXEC

Sample

47 A2 22UR Rev03 A-15


MOVE LENGTH OF pstate TO CMA-LENGTH CALL "CMAPUTPARAM" USING CMA-RETCODE CMA-SNDBUF CMA-RCVBUF CMASOCKCLI pstate CMA-LENGTH

MOVE LENGTH OF SQLCA TO CMA-LENGTH CALL "CMAGETPARAM" USING CMA-RETCODE CMA-SNDBUF CMA-RCVBUF CMASOCKCLI SQLCA CMA-LENGTH IF CMA-RETCODE NOT EQUAL 0 THEN MOVE CMA-RETCODE TO SQLCODE IN SQLCA MOVE LENGTH OF SQLERRMC IN SQLCA TO SQLERRML IN SQLCA CALL "CMANETERROR" USING SQLERRMC IN SQLCA SQLERRML IN SQLCA SQLCODE IN SQLCA MOVE 0 TO CMA-RETCODE END-IF MOVE 1 TO FOUND

* SQL stmt #7* EXEC SQL OPEN cust-curs END-EXEC




A-16 47 A2 22UR Rev03

if sqlcode not = 0 display sqlcode display sqlerrmc else

display "authors in state " pstate

perform until sqlcode not equal to 0

* SQL stmt #8* EXEC SQL* FETCH cust-curs INTO* :paulname , :paddress, :pcity* END-EXEC


MOVE LENGTH OF SQLCA TO CMA-LENGTH CALL "CMAGETPARAM" USING CMA-RETCODE CMA-SNDBUF CMA-RCVBUF CMASOCKCLI SQLCA CMA-LENGTH MOVE LENGTH OF paulname TO CMA-LENGTH CALL "CMAGETPARAM" USING CMA-RETCODE CMA-SNDBUF CMA-RCVBUF CMASOCKCLI paulname CMA-LENGTH MOVE LENGTH OF paddress TO CMA-LENGTH CALL "CMAGETPARAM" USING CMA-RETCODE CMA-SNDBUF CMA-RCVBUF CMASOCKCLI paddress CMA-LENGTH MOVE LENGTH OF pcity TO CMA-LENGTH CALL "CMAGETPARAM" USING CMA-RETCODE CMA-SNDBUF CMA-RCVBUF CMASOCKCLI pcity CMA-LENGTH IF CMA-RETCODE NOT EQUAL 0 THEN MOVE CMA-RETCODE TO SQLCODE IN SQLCA MOVE LENGTH OF SQLERRMC IN SQLCA TO SQLERRML IN SQLCA CALL "CMANETERROR" USING SQLERRMC IN SQLCA SQLERRML IN SQLCA SQLCODE IN SQLCA MOVE 0 TO CMA-RETCODE END-IF MOVE 1 TO FOUND

display " "

if sqlcode = 100 display "End of results" end-if

if sqlcode not = 0 display sqlcode display sqlerrmc

Sample

47 A2 22UR Rev03 A-17

else display "AUL_NAME " paulname display "ADDRESS " paddress display "CITY " pcity end-if

end-perform

end-if

* SQL stmt #9* EXEC SQL CLOSE cust-curs END-EXEC



* SQL stmt #10* EXEC SQL* DISCONNECT CURRENT*END-EXEC



A-18 47 A2 22UR Rev03


if sqlcode not = 0 display sqlcode display sqlerrmc end-if

exit program.

A.7 GCOS7 Client File: mfselectcli_h (Produced by CMAG-SQLserver)

*mfselect.cbl-CBX* 01 mfselectstmt4 COMP-2 VALUE 0. 01 mfselectstmt5 COMP-2 VALUE 1. 01 mfselectstmt6 COMP-2 VALUE 2. 01 mfselectstmt7 COMP-2 VALUE 3. 01 mfselectstmt8 COMP-2 VALUE 4. 01 mfselectstmt9 COMP-2 VALUE 5. 01 mfselectstmt10 COMP-2 VALUE 6.

01 mfselectID COMP-2 VALUE 0. 01 mfselectEXE PIC X(20) VALUE "MyExample".

01 CMASOCKCLI COMP-2 IS EXTERNAL.

Sample

47 A2 22UR Rev03 A-19

A.8 W2K Server Files: mfselectsvr.cbl (Produced byCMAG-SQLserver)

$SET SQL(dbman=ODBC) IDENTIFICATION DIVISION. PROGRAM-ID. MFSELECT. DATA DIVISION. WORKING-STORAGE SECTION.

01 CMA-INDEX PIC S9(9) COMP-5. 01 mypointer procedure-pointer.

COPY "CMA_H".

* SQL stmt #1 * EXEC SQL INCLUDE SQLCA END-EXEC EXEC SQL INCLUDE SQLCA END-EXEC.

* SQL stmt #2 EXEC SQL BEGIN DECLARE SECTION END-EXEC. 01 paulname pic x(20). 01 paddress pic x(40). 01 pcity pic x(20). 01 pstate pic x(20).

* SQL stmt #3 EXEC SQL END DECLARE SECTION END-EXEC.

PROCEDURE DIVISION USING CMA-INDEX. BEGIN-CMA.

GO TO CMA-BEGIN.

* SQL stmt #4 mfselectstmt4. EXEC SQL CONNECT TO "AbSqlServer" END-EXEC.

MOVE LENGTH OF SQLCA-INF TO CMA-LENGTH CALL "CMAPUTPARAM" USING CMA-SQLCA-INF-TYPE SQLCA CMA-LENGTH CMA-ONE GO TO CMA-END.

* SQL stmt #5 mfselectstmt5. MOVE LENGTH OF paulname TO CMA-LENGTH CALL "CMAGETPARAM" USING CMA-STRING-TYPE paulname CMA-LENGTH CMA-ONE

EXEC SQL SELECT address, city INTO :paddress, :pcity FROM authors


A-20 47 A2 22UR Rev03

WHERE au_lname = :paulname END-EXEC

MOVE LENGTH OF SQLCA-INF TO CMA-LENGTH CALL "CMAPUTPARAM" USING CMA-SQLCA-INF-TYPE SQLCA CMA-LENGTH CMA-ONE MOVE LENGTH OF paddress TO CMA-LENGTH CALL "CMAPUTPARAM" USING CMA-STRING-TYPE paddress CMA-LENGTH CMA-ONE MOVE LENGTH OF pcity TO CMA-LENGTH CALL "CMAPUTPARAM" USING CMA-STRING-TYPE pcity CMA-LENGTH CMA-ONE GO TO CMA-END.

* SQL stmt #6 mfselectstmt6. MOVE LENGTH OF pstate TO CMA-LENGTH CALL "CMAGETPARAM" USING CMA-STRING-TYPE pstate CMA-LENGTH CMA-ONE

EXEC SQL DECLARE cust-curs CURSOR FOR select au_lname, address , city from authors where state = :pstate order by au_lname END-EXEC


* SQL stmt #7 mfselectstmt7. EXEC SQL OPEN cust-curs END-EXEC


* SQL stmt #8 mfselectstmt8.

EXEC SQL FETCH cust-curs INTO :paulname , :paddress, :pcity END-EXEC

MOVE LENGTH OF SQLCA-INF TO CMA-LENGTH

Sample

47 A2 22UR Rev03 A-21

CALL "CMAPUTPARAM" USING CMA-SQLCA-INF-TYPE SQLCA CMA-LENGTH CMA-ONE MOVE LENGTH OF paulname TO CMA-LENGTH CALL "CMAPUTPARAM" USING CMA-STRING-TYPE paulname CMA-LENGTH CMA-ONE MOVE LENGTH OF paddress TO CMA-LENGTH CALL "CMAPUTPARAM" USING CMA-STRING-TYPE paddress CMA-LENGTH CMA-ONE MOVE LENGTH OF pcity TO CMA-LENGTH CALL "CMAPUTPARAM" USING CMA-STRING-TYPE pcity CMA-LENGTH CMA-ONE GO TO CMA-END.

* SQL stmt #9 mfselectstmt9. EXEC SQL CLOSE cust-curs END-EXEC


* SQL stmt #10 mfselectstmt10. EXEC SQL DISCONNECT CURRENT END-EXEC


CMA-BEGIN. set mypointer to entry "dllCMANET" GO TO mfselectstmt4 mfselectstmt5 mfselectstmt6 mfselectstmt7 mfselectstmt8 mfselectstmt9 mfselectstmt10 DEPENDING ON CMA-INDEX. CMA-END. exit program returning 0.

A.9 W2K Server Files: cmadyn_MyExample.h (Produced byCMAG-SQLserver)

void MFSELECT();struct { char * exec_nme; void (* cobol_func)(); void (** other_func)(); } module_list_tab[1]={"MyExample",MFSELECT,NULL};


A-22 47 A2 22UR Rev03

A.10 Execution Report

The GCOS7 machine is named BY16 and the W2K server is named frcls0507. TheCMAservice on frcls0507 is listening on the port=9007.

In a JCL file:

$STEP MFSELECT OP53.ABLMLIBSM

OPTIONS=’CMASERVER_HOST=frcls0507 CMASERVER_PORT=9007 ’

In IOF:

BY16:exec_pg MFSELECT lib=OP53.ABLMLIBSM –

options= ‘CMASERVER_HOST=frcls0507 CMASERVER_PORT=9007 ';

MFSELECT Select ... into test

MFSELECT

MFSELECT Address for White is 10932 Bigge Rd.

MFSELECT City for White is Menlo Park

MFSELECT Cursor fetch test

MFSELECT

MFSELECT authors in state CA

MFSELECT

MFSELECT AUL_NAME Bennet

MFSELECT ADDRESS 6223 Bateman St.

MFSELECT CITY Berkeley

MFSELECT

MFSELECT AUL_NAME Carson

MFSELECT ADDRESS 589 Darwin Ln.

MFSELECT CITY Berkeley

MFSELECT

MFSELECT AUL_NAME Dull

MFSELECT ADDRESS 3410 Blonde St.

MFSELECT CITY Palo Alto

MFSELECT

MFSELECT AUL_NAME Green

MFSELECT ADDRESS 309 63rd St. #411

MFSELECT CITY Oakland

MFSELECT

MFSELECT AUL_NAME Gringlesby

MFSELECT ADDRESS PO Box 792

MFSELECT CITY Covelo

MFSELECT

MFSELECT AUL_NAME Hunter

MFSELECT ADDRESS 3410 Blonde St.

MFSELECT CITY Palo Alto

MFSELECT

MFSELECT AUL_NAME Karsen

MFSELECT ADDRESS 5720 McAuley St.


MFSELECT

Sample

47 A2 22UR Rev03 A-23

MFSELECT AUL_NAME Locksley

MFSELECT ADDRESS 18 Broadway Av.

MFSELECT CITY San Francisco

MFSELECT

MFSELECT AUL_NAME MacFeather

MFSELECT ADDRESS 44 Upland Hts.


MFSELECT

MFSELECT AUL_NAME McBadden

MFSELECT ADDRESS 301 Putnam

MFSELECT CITY Vacaville

MFSELECT

MFSELECT AUL_NAME O’Leary

MFSELECT ADDRESS 22 Cleveland Av. #14

MFSELECT CITY San Jose

MFSELECT

MFSELECT AUL_NAME Straight

MFSELECT ADDRESS 5420 College Av.


MFSELECT

MFSELECT AUL_NAME Stringer

MFSELECT ADDRESS 5420 Telegraph Av.


MFSELECT

MFSELECT AUL_NAME White

MFSELECT ADDRESS 10932 Bigge Rd.

MFSELECT CITY Menlo Park

MFSELECT

MFSELECT AUL_NAME Yokomoto

MFSELECT ADDRESS 3 Silver Ct.

MFSELECT CITY Walnut Creek

MFSELECT

MFSELECT End of results

MFSELECT 100

MFSELECT ....d...A. oo

BY16:


A-24 47 A2 22UR Rev03

47 A2 22UR Rev03 g-1

Glossary

C

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.

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.

CMAAbbreviation of Client Mode Access.

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.

D

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.


g-2 47 A2 22UR Rev03

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.

H

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.

I

INFORMIXName of a relational database (and the company which supplies it).

L

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.

M

mainframeGlobal term to indicate proprietary machines such as BULL GCOS 7, BULL GCOS 8, ...

P

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.

Glossary

47 A2 22UR Rev03 g-3

protocolA set of standards, or rules, governing the operations of a communications link.

S

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.

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.

SYBASEName of a relational database (and the company which supplies it).

T

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.

TP7Transactional mechanism on the GCOS 7 system.

TPRTransactional Processing Routine.


g-4 47 A2 22UR Rev03

47 A2 22UR Rev03 i-1

Index

1

111 error message 6-14

9

-9501 error message 6-13-9502 error message 6-13-9503 error message 6-13-9504 error message 6-14-9505 error message 6-14-9506 error message 6-14

A

accessing INFORMIX (via SQL CMA) 1-1accessing SYBASE (via SQL CMA) 1-1APPLICATION RUNNING MODE

parameter 4-6, 4-10applications 3-16arrays of variables 3-10automatic restart 5-12

B

building SQL CMA TP application 5-1

C

cache mechanism 1-6CBL (SQL CMA COBOL type) 3-2CBX (SQL CMA COBOL type) 3-3Clause, CMA SERVICE USED 5-2client building

INFORMIX 4-11starting 4-11

client processdefinition g-1starting 6-11

client program 1-4Client/Server 1-2, g-1CMA

definition g-1CMA SERVICE USED clause 5-2CMA_HOME variable

setting 6-2CMA-0000 error message 2-10CMA-0010 error message 2-10CMA-0011 error message 2-10CMA-0012 error message 2-10CMA-0013 error message 2-11CMA-0014 error message 2-11CMA-0015 error message 2-11CMA-0016 error message 2-11CMA-0017 error message 2-11CMA-0018 error message 2-12CMA-0019 error message 2-12CMA-0020 error message 2-12CMA-0021 error message 2-12CMA-0022 error message 2-13CMA-0031 error message 2-13CMA-0032 error message 2-13


i-2 47 A2 22UR Rev03

CMA-0033 error message 2-13CMA-0034 error message 2-14CMA-0050 error message 2-14CMA-0051 error message 2-14CMA-0052 error message 2-14, 3-8CMA-0053 error message 2-15CMA-0054 error message 2-15CMA-0055 error message 2-16CMA-0056 error message 2-16CMA-0060 error message 2-16CMA-0061 error message 2-16CMA-0062 error message 2-16CMA-0063 error message 2-16CMA-0064 error message 2-17CMA-0066 error message 2-17CMA-0067 error message 2-17CMA-0068 error message 2-17CMA-0070 error message 2-18CMA-0071 error message 2-18CMA-0072 error message 2-18CMA-0073 error message 2-18CMAGEN component 1-4, 2-1CMAINST error message 4-13, 4-14CMANET component 1-5, 2-19cmaserver error message 6-8, 6-9CMATDS transaction 5-3CMATP module 1-6, 2-20, 5-4COB (SQL CMA COBOL type) 3-3COBOL

GCOS 7 data types 3-4INCLUDE files 3-12, 3-14source format 3-1SQL CMA rules 3-4

commentsin SQL CMA 3-7

commit synchronization mechanism 1-6commitments

automatic restart 5-12explicit 5-10handlind 5-8implicit 5-10

communication protocol g-1communications interface 2-19components of SQL CMA

CMAGEN 1-4, 2-1CMANET 1-5, 2-19CMATP 1-6, 2-20

connection cache mechanism 1-6

D

DAT (SQL CMA COBOL type) 3-2data conversion

SQL CMA COBOL 3-5data representation

GCOS 7 COBOL 3-4database objects for TP 5-4DEBUG option 2-3debugging 2-6Declare Section

definition g-1declaring

SQL variables 3-6Default g-1DFCMIT statement 5-11distributed environment g-2

E

elementary variables 3-11Embedded SQL 1-2environment

distributed g-2setting INFORMIX variables 4-3

error messages111 6-14-9501 6-13-9502 6-13-9503 6-13-9504 6-14-9505 6-14-9506 6-14CMA-0000 2-10CMA-0010 2-10CMA-0011 2-10CMA-0012 2-10CMA-0013 2-11CMA-0014 2-11CMA-0015 2-11CMA-0016 2-11CMA-0017 2-11CMA-0018 2-12CMA-0019 2-12CMA-0020 2-12CMA-0021 2-12

Index

47 A2 22UR Rev03 i-3

error messages (con’t)CMA-0022 2-13CMA-0031 2-13CMA-0032 2-13CMA-0033 2-13CMA-0034 2-14CMA-0050 2-14CMA-0051 2-14CMA-0052 2-14, 3-8CMA-0053 2-15CMA-0054 2-15CMA-0055 2-16CMA-0056 2-16CMA-0060 2-16CMA-0061 2-16CMA-0062 2-16CMA-0063 2-16CMA-0064 2-17CMA-0066 2-17CMA-0067 2-17CMA-0068 2-17CMA-0070 2-18CMA-0071 2-18CMA-0072 2-18CMA-0073 2-18CMAINST 4-13, 4-14cmaserver 6-8, 6-9Listener 6-10SQLCODE = -1 5-16SQLCODE = 10 5-17SQLCODE = -11 5-17SQLCODE = 111 5-18SQLCODE = -22 5-17SQLCODE = -23 5-17SQLCODE = -5 5-16SQLCODE = -6 5-16

explicit commitment 5-10

F

FILE OF SOURCE LIST parameter 4-5, 4-9files

generated 2-2INCLUDE (COBOL) 3-12, 3-14INCLUDE (SQLCA) 3-13

formatsCOBOL source 3-1

G

GCOS 7 COBOL data types 3-4generated files 2-2

H

heterogeneous system g-2host variable g-2

I

implicit commitment 5-10INCLUDE files

COBOL 3-12, 3-14SQLCA 3-13

INFORMIXaccessing via SQL CMA 1-1client building 4-11definition g-2generated SQL CMA source 2-2ROLLBACK statement 5-13SQL CMA applications 3-16SQL COMMIT statement 5-10

installingstarting SQL CMA Installer 4-3

L

layer g-2lexical debug message 2-6Listener

definition g-2error messages 6-10logging 6-7starting 6-2stopping 6-6

logging 2-4SQL CMA Listener 6-7SQL CMA process 6-12

LOGGING FILE NAMEparameter 4-7, 4-10


i-4 47 A2 22UR Rev03

M

mainframe g-2

P

parametersAPPLICATION RUNNING

MODE 4-6, 4-10FILE OF SOURCE LIST 4-5, 4-9LOGGING FILE NAME 4-7, 4-10RADIX OF THE OBJECT FILE 4-9SERVER BINARY NAME 4-9SOURCE NAME 4-5SQL CMA DEBUG 4-6SQLCODE 3-15SQLERRD 3-15SQLERRM 3-15SQLERRP 3-15SQLWARN 3-15

precompiler g-2preprocessing, SQL 1-2process

definition g-1, g-2logging 6-12

protocol g-1, g-3

R

RADIX OF THE OBJECT FILEparameter 4-9

referencingSQL arrays of variables 3-10SQL elementary variables 3-11SQL variables 3-8

ROLLBACK action 5-13rules

comments in SQL CMA 3-7SQL CMA COBOL 3-4SQL CMA data conversion 3-5

S

serverprocess g-3program 1-4start building 4-8

SERVER BINARY NAME parameter 4-9setting

CMA_HOME variables 6-2INFORMIX environment variables 4-3

source formatsCOBOL 3-1

source generator 1-4, 2-1, 4-4SOURCE NAME parameter 4-5SQL

definition g-3Embedded 1-2preprocessing 1-2referencing arrays of variables 3-10referencing elementary variables 3-11referencing variables 3-8

SQL CMAbuilding INFORMIX client 4-11building TP application 5-1client process 6-11client program 1-4CMAGEN module 1-4, 2-1CMANET module 1-5, 2-19CMATP module 1-6, 2-20comments 3-7components 1-3definition 1-1environment 5-3INFORMIX applications 3-16Installer 4-3Listener 6-2, 6-6, 6-7logging 2-4logging processes 6-12server program 1-4starting client building 4-11starting server building 4-8starting source generation 4-4TP cache 5-5TP Description 5-5TP errors 5-15

Index

47 A2 22UR Rev03 i-5

SQL CMA COBOLCBL type 3-2CBX type 3-3COB type 3-3DAT type 3-2data conversion 3-5rules 3-4

SQL CMA DEBUG parameter 4-6SQL COMMIT statement 5-11, 5-12SQL statement g-3SQL variables

declaring 3-6definition g-3using 3-6

SQLCAINCLUDE files 3-13structure 3-15

SQLCODE = -1 error message 5-16SQLCODE = 10 error message 5-17SQLCODE = -11 error message 5-17SQLCODE = 111 error message 5-18SQLCODE = -22 error message 5-17SQLCODE = -23 error message 5-17SQLCODE = -5 error message 5-16SQLCODE = -6 error message 5-16SQLCODE parameter 3-15SQLERRD parameter 3-15SQLERRM parameter 3-15SQLERRP parameter 3-15SQLWARN parameter 3-15starting

client building 4-11server building 4-8source generator 4-4SQL CMA Installer 4-3

starting SQL CMA client process 6-11starting SQL CMA Listener 6-2stopping SQL CMA Listener 6-6SYBASE

accessing via SQL CMA 1-1definition g-3generated SQL CMA source 2-2

symbol research debug 2-3symbol table debug 2-3synchronization mechanism 1-6

T

TCP/IP g-3TP application, building 5-1TP7 5-2, g-3TP7GEN 5-3TPR g-3Transaction, CMATDS 5-3transactional interface 2-20types

CBL (SQL CMA COBOL) 3-2CBX (SQL CMA COBOL) 3-3COB (SQL CMA COBOL) 3-3DAT (SQL CMA COBOL) 3-2GCOS 7 COBOL 3-4

U

using SQL variables 3-6

V

variablesdeclaring SQL variables 3-6referencing 3-8referencing arrays 3-10referencing elementary 3-11setting CMA_HOME 6-2setting INFORMIX environment 4-3using SQL variables 3-6


i-6 47 A2 22UR Rev03

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 22UR Rev03 Date / Dated : May 2002

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

Bull HN Information Systems Inc.Publication Order EntryFAX: (800) 611-6030MA30/415300 Concord Rd.Billerica, MA 01821U.S.A.

cma-sqlserver sql*mt for sql...

Documents