SQL-CMA SQL*XT for ORACLE

Transcription

1 Database Products SQL-CMA SQL*XT for ORACLE GCOS 7 SQL Client Mode Access User's Guide GCOS 7 47 A2 01EL Rev 00

2 Database Products SQL-CMA SQL*XT for ORACLE GCOS 7 SQL Client Mode Access User's Guide GCOS 7 Subject: This manual describes the SQL CMA (Client Mode Access) on GCOS 7 for Oracle Database Software Supported: GCOS7-V9 TS9910 (or later) Artemis and Diane Oracle 8i/9i on Windows 2000 GCOS 7 SQL-CMA version 2.1 Date: May 2003 Bull S.A. CEDOC 357 Avenue PATTON B.P ANGERS Cedex 01 FRANCE 47 A2 01EL Rev 00

3 Copyright Bull S.A., 2003 Bull acknowledges the rights of proprietors of trademarks mentioned herein. No part of this publication may be reproduced, stored in a retrieval system or transmitted in any form or by any means, electronic, mechanical or otherwise without the prior written permission of the publisher. Bull disclaims the implied warranties of merchantability and fitness for a particular purpose and makes no express warranties except as may be stated in its written agreement with and for its customer. In no event is Bull liable to anyone for any indirect, special, or consequential damages. The information and specifications in this document are subject to change without notice. Consult your Bull Marketing Representative for product or service availability. 47 A2 01EL Rev 00

4 Preface Scope and Objectives This manual describes the GCOS 7 SQL CMA (Client Mode Access) product for Oracle 1 Data Base. This product is intended for anyone who wishes to perform networking operations with databases from GCOS 7 platforms : Artemis or Diane. Intended Readers The information contained in this manual is relevant to end-users, application programmers and system administrators. Structure Chapter 1 introduces SQL CMA and its main components and their functions. Chapter 2 describes the SQL CMA main components in more detail. In particular, it describes CMAGEN (CMA Source Generator) and CMATP (CMA Transaction Processing interface). Chapter 3 explains how to create a SQL CMA application (including how to get a user source to conform to the SQL CMA rules, for example, Naming Convention, Limitations, etc.). Chapter 4 describes the generation process for the SQL CMA product. Chapter 5 explains how to configure and enable the CMANET protocol communication. Chapter 6 describes the use of SQL CMA in a batch environment. Chapter 7 describes the use of SQL CMA in a TP (Transaction Processing) environment. A Glossary defines some of the terms used in the manual. 1 Oracle, Oracle8i, Oracle9i, PL/SQL, Pro*COBOL are trademarks or registered trademarks of Oracle Corporation. SQL server, Windows 2000, Visual C++ are trademarks or registered trademarks of Microsoft Corporation. Micro Focus, Net Express are trademarks or registered trademarks of Merant Corporation. 47 A2 01EL iii

5 GCOS 7 SQL CMA User's Guide iv 47 A2 01EL

6 Table of Contents 1. What is SQL CMA? 1.1 WHAT IS SQL CMA? CLIENT SERVER MODEL SQL CMA MODEL SQL CMA COMPONENTS CMAGEN MODULE: SOURCE GENERATOR CMANET MODULE: COMMUNICATION INTERFACE CMATP MODULE: TRANSACTIONAL INTERFACE Connection Cache mechanism Commit Synchronization mechanism CURRENT GCOS 7 SQL CMA OFFER Description of SQL CMA Components 2.1 SQL CMA SOURCE GENERATOR: CMAGEN GENERATED SQL CMA SOURCES DEBUG OPTION LOGGING OF SQL CMA GENERATOR Generator LOG file: «<LOG_DIR>\cmagen.log» Declared Symbol Log file: «<LOG_DIR>\cmasymb.log» Referenced Symbol Log file:«<log_dir>\cmafindsymb.log» ERRORS FROM SQL CMA GENERATION SQL CMA COMMUNICATION INTERFACE: CMANET SQL CMA TRANSACTIONAL INTERFACE: CMATP A2 01EL v

7 GCOS 7 SQL CMA User's Guide 3. Defining SQL CMA Applications 3.1 COBOL SOURCES ON GCOS FORMAT OF COBOL SOURCE COBOL DATA TYPES SQL CMA COBOL RULES EMBEDDED SQL AND PL/SQL SQL CMA COBOL DATA TYPES USING DATABASE SQL VARIABLES DECLARING SQL VARIABLES SQL Variable Name Comments Continuation Lines PICTURE Attribute of SQL Variables RENAMES Attribute of SQL Variables REFERENCING SQL VARIABLES Comments Continuation Lines Referencing SQL Arrays of Variables Referencing SQL Elementary Variables INCLUDE FILES SQLCA INCLUDE FILE ORACA INCLUDE FILE ORDINARY INCLUDE FILE SQLCA STRUCTURE SQL CMA APPLICATIONS RESTRICTIONS ON DECLARE STATEMENT Declare cursor with input variable Declare cursor with output variable RESTRICTION ON CURSOR OPERATION UNDER TDS SQL CMA TP DESCRIPTION SQL CMA TP CACHE CONCEPT SQL CMA TP Context Cache definition SQL CMA TP Context states Why a SQL CMA TP Context cache? CONNECT ACTION CONNECT action provided by Oracle Relationship between CONNECT action and SQL CMA TP Context CONNECT action errors COMMITMENTS vi 47 A2 01EL

8 Preface COMMIT ACTION Implicit commitment Explicit commitment SQL COMMIT statement Examples of COMMIT actions Automatic restart Relationship between COMMIT action and SQL CMA TP context ROLLBACK ACTION ROLLBACK statement provided by Oracle Examples of ROLLBACK actions Relationship between ROLLBACK action and SQL CMA TP context SQL CMA TP ERRORS SQL CMA Installer 4.1 PREREQUISITES ORACLE PRODUCT MERANT/MICRO FOCUS PRODUCT C COMPILER PRODUCT SQL CMA PRODUCT STARTING SQL CMA CMAINST PRODUCT INTERACTIVE PROGRAM CMAINST STARTING SQL CMA SOURCE GENERATION «LIST NAME» AND «SOURCES NAME(s)» PARAMETERS «ORACLE SETTINGS» PARAMETERS «APPLICATION RUNNING IN» PARAMETER «DEBUG MODE» PARAMETER «LOGGING FILE NAME» PARAMETER VALIDATION OF SOURCES TO GENERATE STARTING SQL CMA SERVER BUILDING «SERVER BINARY NAME» PARAMETER «LIST NAME» AND «SOURCE NAME(s)» PARAMETERS «APPLICATION RUNNING IN» PARAMETER «LOGGING FILE NAME» PARAMETER FINAL REPORT of SQL CMA INSTALLER SQL CMA INSTALLER ERRORS A2 01EL vii

9 GCOS 7 SQL CMA User's Guide 5. Enable CMANET Communication 5.1 CONFIGURING THE MACHINES STARTING SQL CMAservice ENVIRONMENT VARIABLE CMA_HOME_SQL CMASERVICE IN DEBUG MODE : FILE CMADEBUG.TXT STARTING OPTIONAL CMALISTENER STOPPING OPTIONAL CMA LISTENER LOGGING OF CMAservice (AND OPTIONAL CMA LISTENER ) CMAservice and CMA LISTENER ERRORS LOGGING OF SQL CMA PROCESSES COMMUNICATION ERRORS Using SQL CMA in Batch Mode 6.1 PREREQUISITES SQL CMA PRODUCT ON GCOS SERVER EXECUTABLE ON WINDOWS CMANET ENABLED BUILDING A SQL CMA COBOL CLIENT IN BATCH MODE TRANSFER SOURCES FROM WINDOWS 2000 TO GCOS MOVE SQL CMA INCLUDE FILES COMPILE CLIENT SOURCES LINK CLIENT OBJECTS CLIENT APPLICATION EXECUTION Using SQL CMA in Transactional Mode 7.1 PREREQUISITES SQL CMA PRODUCT ON GCOS SERVER EXECUTABLE ON WINDOWS CMANET ENABLED BUILDING A SQL CMA TP APPLICATION TRANSFER SOURCES TO GCOS MOVE SQL CMA INCLUDE FILES COMPILE CLIENT SOURCES LINK CLIENT OBJECTS viii 47 A2 01EL

10 Preface 7.3 PREPARING THE TDS ENVIRONMENT TDS GENERATION Modifying the STDS file Running TP7GEN JCL DATABASE OBJECT FOR TP MODE : CMATP TABLE TDS EXECUTION RUNNING SQL CMA TRANSACTIONS CONTROLLING SQL CMA EXECUTION WITH CMATDS TRANSACTION SQL CMA TP ERROR CODES Glossary Index 47 A2 01EL ix

11 GCOS 7 SQL CMA User's Guide Table of Graphics Figures Figure 1-1. Client-Server Model Figure 1-2. SQL CMA Model Figure 4-1. Starting SQL CMA CMAINST Product Figure 4-2. Interactive Program CMAINST Figure 4-3. Starting SQL CMA Source Generation Figure 4-4. Starting SQL CMA Server Building Tables Table 3-1. Format of COBOL Source Table 3-2. SQL CMA COBOL Type: «DAT» Table 3-3. SQL CMA COBOL Type: «CBL» Table 3-4. SQL CMA COBOL Type: «COB» Table 3-5. SQL CMA COBOL Type: «CBX» Table 3-6. COBOL Data Representation on GCOS Table 3-7. COBOL Data Type Conversion x 47 A2 01EL

12 1. What is SQL CMA? This chapter provides a global description of GCOS 7 SQL CMA and includes the following information: SQL CMA General Description SQL CMA Components GCOS 7 SQL CMA offer. The current SQL CMA product accepts Client applications : running in batch or TP mode accessing some Microsoft SQL server or Oracle databases using the standard COBOL language. The product description is more general. 1.1 WHAT IS SQL CMA? SQL CMA (Client Mode Access) is the general name to identify a solution which allows a client application, running on a mainframe system, to access a database located on AIX-Based Systems or Windows 2000 systems. GCOS 7 SQL CMA is the specific SQL CMA product adapted to the GCOS 7 client mainframe. SQL CMA is a software product that allows client applications running in Batch or Transactional mode (TP) on mainframes, to access a remote relational database such as Microsoft SQL server or ORACLE located on Windows 2000 platforms or AIX-Based platforms, without the database environment being installed and running on the mainframes. SQL CMA brings the capability to access several various databases and to get a user application independent of the evolution of the database release. 47 A2 01EL 1-1

13 GCOS 7 SQL CMA User's Guide CLIENT SERVER MODEL SQL CMA is based on the Client/Server Model which is the common technology of most database suppliers. Business logic + embedded SQL database server Figure 1-1. Client-Server Model There are two tasks, each one running on a different machine, and both of them communicating by using some communication protocols SQL CMA MODEL Database suppliers provide a normalized SQL application programmatic interface (SQL API) that enables a programmer to create applications with database management capabilities. Embedded SQL A programmer can write a source application in any of the standard languages and add some SQL statements among the other statements, just as if they were ordinary statements of the language. These SQL statements are named Embedded SQL statements. SQL Preprocessing SQL CMA is based on the SQL preprocessing principle. In this principle, the source application, including the Embedded SQL statements, is processed by an Embedded SQL preprocessor that converts the specific SQL A2 01EL

14 What is SQL CMA? statements into procedure calls and special data structures, and produces new source code that will be compiled and linked with the database libraries to get a final application. A user SQL application needs a database environment to be locally installed on the client platform, because the Embedded SQL statements have to be preprocessed by the appropriate database pre-compilers. SQL CMA removes this requirement from the Client mainframe because it performs the SQL processing on the remote Windows 2000 or AIX-Based system. Using appropriate tools which translate the SQL statements into specific functions, SQL CMA makes a user application independent of the SQL evolution and of the database releases. SQL CMA generates a new source code enabling the remote execution of the Embedded SQL statements from a user database application (with SQL statements embedded to manipulate database objects). Business logic + function calls Embedded SQL database server Figure 1-2. SQL CMA Model 47 A2 01EL 1-3

15 GCOS 7 SQL CMA User's Guide 1.2 SQL CMA COMPONENTS According to the database preprocessing architecture explained previously, SQL CMA acts as a database pre-compiler. It analyses the user application which includes some SQL statements, and translates it into two output source programs: one running on the mainframe client, one running on the Windows 2000 or AIX-Based server. The source program on the Client site is named the SQL CMA client program while the other one is named the SQL CMA server program. The SQL CMA generated source programs are compiled and linked in their respective environments (Mainframe and Windows 2000 or AIX-Based system). The SQL CMA client program, on the mainframe, does not need any database environment such as libraries, include files,... to be compiled and linked. The SQL CMA server program, on the Windows 2000 server or on the AIX-Based server needs the standard database environment: pre-compilers, include files, database libraries,... to be compiled and linked because it includes the SQL statements that manipulates the database objects. Both SQL CMA source programs communicate one with the other through a SQL CMA communication interface based on the TCP/IP protocol. SQL CMA is composed of several modules: CMAGEN CMANET CMATP SQL CMA Source Generator SQL CMA Communication layer SQL CMA Transactional interface Each of these is described below A2 01EL

16 What is SQL CMA? CMAGEN MODULE: SOURCE GENERATOR According to the standard database approach, a client database application with Embedded SQL statements is translated by a database pre-compiler to get a standard source code. This one is then compiled and linked with database libraries to get a final application. CMAGEN, the SQL CMA Source Generator, acts as a pre-compiler, i.e. it analyses the input application which includes the Embedded SQL statements, generates two output programs: a SQL CMA client program, a SQL CMA server program. SQL CMA client program The SQL CMA client program is a mapping of the initial user application in which the Embedded SQL statements have been replaced by SQL CMA sequences. These SQL CMA sequences call specific CMANET functions in order to communicate with the server site. The SQL CMA client program is then transferred, compiled and linked with the CMANET libraries on the mainframe system to produce a new client application running in Batch or TP mode. SQL CMA server program The SQL CMA server program is independent of the initial user application but defines a set of functions including the Embedded SQL statements referenced in the initial user application. The SQL CMA server program has to be pre-processed by the appropriate database pre-compiler just as a standard client database application. Then, it has to be compiled and linked with the database and the CMANET libraries on the Windows 2000 system or AIX-Based system to get a server application. The SQL CMA server program is strictly dependent on the SQL referenced in the user application. Therefore, any modification in the SQL statements causes the client and server sources to be re-generated. CMAGEN operates in the Windows 2000 environment. 47 A2 01EL 1-5

17 GCOS 7 SQL CMA User's Guide CMANET MODULE: COMMUNICATION INTERFACE CMANET is the software layer that cooperates with a communication protocol supported by the mainframe and the Windows 2000 system to provide a communication interface between the generated SQL CMA applications. The communication protocol supported by the CMANET software is the standard TCP/IP communication protocol, available on the mainframe and Windows 2000 platform. 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 and disconnecting sessions, sending and receiving messages. CMANET also includes a set of conversion functions that ensure the data type compatibility between the heterogeneous systems: Mainframe and Windows CMANET is an internal module, not fully detailed, so the CMANET functions are not assumed to be called outside the SQL statement translation in the user application. The CMANET module is composed of 2 layers: one is provided for the mainframe system, to enable the SQL CMA client program to be linked, the other one for Windows 2000, to enable the SQL CMA server program to be linked. A SQL CMA listener service is also provided (on Windows 2000). The SQL CMA listener service function is to: listen for the client connection requests, accept the connection establishment, start the appropriate SQL CMA server process. The SQL CMA listener is part of the CMANET module on Windows 2000; it is a Windows 2000 service A2 01EL

18 What is SQL CMA? CMATP MODULE: TRANSACTIONAL INTERFACE Some SQL CMA applications are Transactional applications. For example, these applications run in the TDS environment on the GCOS 7 platform. The CMATP modules provide functions to ensure the data integrity through a Commit Synchronization mechanism and to increase the performance through a Connection Cache mechanism Connection Cache mechanism The Connection Cache principle is to reuse physical connections as much as possible by mapping logical connections on a unique physical connection. So, physical connecting, whose time cost is heavy, is greatly reduced. A Commitment Unit uses contexts, i.e. working areas to handle the set of connections called inside the Commitment Unit. Each context is recorded in a Cache Table and can be reused by other Commitment Units if it is available. Specific sequences performing the Connection Cache handling are automatically inserted by CMAGEN in the SQL CMA Client source. These sequences call a succession of CMATP functions Commit Synchronization mechanism The transactional monitor activates the CMATP module for the Commit Synchronization mechanism by performing successive calls: a first call is made at the beginning of the Commitment Unit to initialize the communication interface between the two parts, a second one is made at the end of the Commitment Unit to commit one database. 47 A2 01EL 1-7

19 GCOS 7 SQL CMA User's Guide 1.3 CURRENT GCOS 7 SQL CMA OFFER The current SQL CMA product, presently offered on the GCOS 7 platforms, accepts Client applications supporting Microsoft SQL server or Oracle database accesses, and using the standard COBOL language running in batch or TP mode. SQL CMA product environment is restricted to GCOS7 / Windows 2000 environment with the database on the Windows 2000 component or on another Windows or AIX-Based system. The Oracle 8i or 9i Client software is requested on the Windows 2000 side: it provides the Oracle Pro*Cobol pre-compiler. The Merant/MicroFocus product Net Express 3.1 is requested on the Windows 2000 side: it provides a COBOL compiler. The Visual C++ compiler version 6.0 (standard version) is requested on the Windows 2000 side: it is used during the application server building phase. For SQL Server access refer to documentation: SQL*MT FOR SQL SERVER ref: 47A2 22UR Rev A2 01EL

20 2. Description of SQL CMA Components This chapter describes the main SQL CMA components for Client applications supporting Oracle 8i/9i database accesses, and using the standard COBOL language. These components are : CMAGEN, CMANET, CMATP. 2.1 SQL CMA SOURCE GENERATOR: CMAGEN As mentioned in the previous chapter, SQL CMA enables a user application running on a mainframe to access a remote Windows 2000 or AIX-Based database without the database environment being installed on the mainframe. This functionality is supplied because the processing of Embedded SQL statements, which needs the database environment such as libraries and pre-compilers, is done on the Windows 2000 side. CMAGEN converts the Embedded SQL statements into SQL CMA function calls. This ensures that the remote CMAGEN is the module collecting all the SQL CMA Generators with their working environments. First, a user source, including Embedded SQL statements, is submitted to a SQL CMA Generator. A SQL CMA Generator is a tool ensuring the translation of SQL 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 Chapter 4 for more information. A SQL CMA Generator is supplied for each supported couplet : Database and Language. 47 A2 01EL 2-1

21 GCOS 7 SQL CMA User's Guide This release provides the generator «cmag-oracle» which is the SQL CMA Generator executable used to translate user sources manipulating Oracle objects through the COBOL language GENERATED SQL CMA SOURCES After a SQL CMA Source generation, several source files, named Generated SQL CMA Sources, are produced. Some files are created to run on the Client mainframe, others are intended for the Windows 2000 Server. These source files are recognizable because they are identified according to the name of the user file. A user database source is named: «<name>.<suffix>» where: «<name>» «<suffix>» is the user source radix is the standard suffix of a database application: «pco» for Oracle The SQL CMA Source generator produces the following files: Generated Client files for GCOS7: «<name>cli_cob» «<name>cli_h» Source code Include file. Generated Server files for Windows 2000: «<name>svr.cbl» Source code. A work file «<name>.lst» is created to hold the list of the remote SQL CMA functions. 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 Client mainframe. The Generated Server files, which hold the SQL statements of the initial user source, will be precompiled, compiled and linked with the database and the CMANET libraries on the Windows 2000 server A2 01EL

22 Description of SQL CMA Components Additional output files are also generated: «<name>svr.lis» which is the Oracle pre-compilation listing file «<name>svr.lst» which is the Merant Cobol compilation listing file 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 the current 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 tracking may be required by the Support team to understand abnormal results. Before you start a SQL CMA Source Generation, the SQL CMA Installer needs the DEBUG or NO DEBUG mode to be defined. Running in NO DEBUG mode, the current SQL CMA Generator reports in the generator Log file only the errors detected during its processing. In case of DEBUG mode, a full tracking is printed in the generator Log file. An input DEBUG option can be used to request this tracking to be normal or detailed. The following DEBUG options are available: Lexical Analysis Debug: «No debug» or «Normal Debug» Default is «No debug». This option lists in the Generator Log file different lexical objects such as SQL statements, strings, variables,... detected in the initial user source. Symbol Table Debug: «No Debug», «Normal Debug» or «Detailed Debug» Default is «Normal Debug». This option logs the «SQL Symbol Table», i.e. it lists the SQL variables declared in the SQL «Declare Section», with their characteristics (Name, type, length). 47 A2 01EL 2-3

23 GCOS 7 SQL CMA User's Guide Symbol Research Debug: «No Debug», «Normal Debug» or «Detailed Debug» Default is «Normal Debug». This option logs the SQL variables referenced in the SQL 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 file could rapidly grow due to the flow of information 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 environment variable TEMP, for example TEMP value is <LOG_DIR> The SQL CMA generator manages a Generator log file to hold the errors issued during SQL CMA Source generation: «<LOG_DIR>\cmagen.log» The «Lexical Analysis Debug» option also records the tracking information in: «<LOG_DIR>\cmagen.log» The «Symbol Table debug» option creates a special «Declared Symbol file» to hold the SQL Symbol Table: «<LOG_DIR>\cmasymb.log» The «Symbol Research debug» option creates a special «Referenced Symbol file» to hold the referenced SQL variables: «<LOG_DIR>\cmafindsymb.log» A2 01EL

24 Description of SQL CMA Components Generator LOG file: «<LOG_DIR>\cmagen.log» The Generator Log file «<LOG_DIR>\cmagen.log» contains the errors detected 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 source Generation: Header of a SQL CMA source Generation Description of an Error message Description of a Lexical DEBUG message SQL CMA Header A SQL CMA Generator starts logging by printing a SQL CMA header such as: Generator release Name of the user source to process Running mode of the user application DEBUG mode DEBUG options if DEBUG mode is required. Examples: Here are examples of «<LOG_DIR>\cmagen.log» headers: CMA*GENerator Production: <<appli.pco>> Logging file. Generation of BATCH application. DEBUG mode is ENABLED for: Lexical Analysis Symbol Table Building (Detailed) Referenced Symbol Search CMA*GENerator Production: <<appli.pco>> Logging file. Generation of BATCH application. DEBUG mode is DISABLED. 47 A2 01EL 2-5

25 GCOS 7 SQL CMA User's Guide 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 file Date and time Text of the current source line Generation error detected: Number and Text Examples: Here are examples of generation error logging: <<appli.pco>>, line 34 at 10-FEB :45:30: 01 B1 PIC S SYNC LEFT COMP-1 CMA-0015 COMP-1 item is limited to 4 decimal digits. <<appli.pco>>, line 37 at 10-FEB :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. 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 10-FEB :46:39: Detection of DECLARE SECTION beginning. DEBUG trace at 10-FEB :48:09: EXEC statement: EXEC SQL INCLUDE SQLCA END-EXEC. A SQL CMA Generator ends the logging by printing a line A2 01EL

26 Description of SQL CMA Components The SQL CMA Generation logging is appended to «<LOG_DIR>\cmagen.log» Declared Symbol Log file: «<LOG_DIR>\cmasymb.log» The Declared Symbol Log file: «<LOG_DIR>\cmasymb.log» is created if the «Symbol Table debug» option is set before performing the SQL CMA source Generation. «<LOG_DIR>\cmasymb.log» describes the SQL variables, declared in the SQL «Declare Section» which are then referenced in SQL statements. In a COBOL source, the SQL variable attributes are described as follows: Name of the User source in which the variable is declared Variable name LEVEL number USAGE clause PICTURE clause Global Size of the variable Size 0f the V9 part of the PICTURE clause Size 0f the S9 part of the PICTURE clause Link addresses. Examples: Below are examples of «<LOG_DIR>\cmasymb.log» records: «01 VAR3 COMPUTATIONAL-2.» is described as follows <<appli.pco>> Variable declaration: Symbol Name: 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 « VAR4 OCCURS 5 TIMES PIC S9(7)V99 COMP-3 VALUE ZERO.» is described as follows: 47 A2 01EL 2-7

27 GCOS 7 SQL CMA User's Guide <<appli.pco>> 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 «<LOG_DIR>\cmasymb.log» Referenced Symbol Log file:«<log_dir>\cmafindsymb.log» The Referenced Symbol Log file: «<LOG_DIR>\cmasymb.log» is created if the «Symbol Research debug» option is set before performing the SQL CMA source Generation. «<LOG_DIR>\cmafindsymb.log» describes the SQL variables referenced in the SQL statements. There are two kinds of referenced variables: Input variables and Output variables: Input SQL variables Output SQL variables («USER to KERNEL») are input parameters of a SQL statement so, their value must be transmitted by the client application to the server process. («KERNEL to USER») are output parameters of a SQL statement so, their value is returned by the server process to the client application. The description of a referenced SQL variable in «<LOG_DIR>\cmafindsymb.log» looks like the description of a declared SQL variable in «<LOG_DIR>\cmafindsymb.log» A2 01EL

28 Description of SQL CMA Components A record in «<LOG_DIR>\cmafindsymb.log» has the following description: Name of the User source in which the variable is referenced Variable type: Input or Output variable: <<USER to KERNEL>> <<KERNEL to USER>> To get details about the other attributes, refer to the previous paragraph. A SQL CMA Generator ends the debugging by printing a line. The SQL CMA debugging of referenced SQL variables is appended in «<LOG_DIR>\cmafindsymb.log». Examples: Below are examples of «<LOG_DIR>\cmafindsymb.log» records (in a COBOL source): <<EXEC SQL SELECT EMPNO INTO :VAR3 FROM EMP WHERE DEPTNO = :VAR4 END-EXEC.>> <<appli.pco>>,line 22 Referenced variable: VAR3 (sent from KERNEL to 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: 0x Previous Buffer Address: 0x0 <<appli.pco>>,line 23 Referenced variable: VAR4 (sent from USER to KERNEL) Symbol Name: VAR4 Buffer Address: 0x 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: 0x A2 01EL 2-9

29 GCOS 7 SQL CMA User's Guide ERRORS FROM SQL CMA GENERATION The Embedded SQL in COBOL source can be ANSI 92 or Oracle SQL. *** CMA-0000 Error while opening the xxx file. The SQL CMA Generator was unable to open a temporary file for internal use. There may be: insufficient disk space, too many open files, read-only protection on the output directory. Make sure that: there is enough disk space, the limit for open files is set high enough, the protection on the directory allows opening a file for writing. *** CMA-0010 Error while a host variable descriptor is allocated. A system error was returned by Windows 2000 during memory space allocation. The «alloc» system function was invoked. To fix the problem, contact your support team representative A2 01EL

30 Description of SQL CMA Components *** CMA-0011 Garbled characters in the variable declaration. Some characters were not recognized during the Lexical analysis of the current statement. Check the statement syntax and make sure that garbled characters are not added within the declaration. *** CMA-0012 Host variable name has already been found. There is syntax error in the COBOL declaration. A variable name is defined twice in the COBOL declaration. Correct the syntax of the COBOL declaration according to the COBOL documentation. *** CMA-0013 The USAGE clause has already been declared. There is syntax error in the COBOL declaration. A USAGE clause is defined twice in the variable declaration. Correct the syntax of the COBOL declaration according to the COBOL documentation. 47 A2 01EL 2-11

31 GCOS 7 SQL CMA User's Guide *** CMA-0014 No PICTURE clause defined. According to the COBOL rules, this USAGE clause requires a PICTURE clause to be 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. The current declaration exceeds the maximum value allowed by the COBOL compiler. Correct the data type size in the COBOL declaration as indicated in the error message. *** CMA-0016 A PICTURE clause is not compatible with this datatype. According to the COBOL rules, this USAGE clause must not be associated with a PICTURE clause. Correct the COBOL declaration according to the COBOL documentation A2 01EL

32 Description of SQL CMA Components *** CMA-0017 A PICTURE string with a scaling factor is not compatible with this USAGE. According to the COBOL rules, this USAGE clause must not be associated with a PICTURE clause with a scaling factor. Correct the COBOL declaration according to the COBOL documentation. *** CMA-0018 A garbled type (xxx) is detected. Internal error while building 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. The SQL variable declaration exceeds the maximum value allowed by the COBOL compiler. Correct the data type size in the SQL variable declaration as indicated in the error message. 47 A2 01EL 2-13

33 GCOS 7 SQL CMA User's Guide *** CMA-0020 WARNING: A FILLER declaration is not expected in DECLARE section 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 variable declaration. The SQL CMA Generator warns the user about this error case. Do not use «FILLER» keyword to declare a SQL variable name. *** CMA-0031 The type (xxx) of yyy variable could not be recognized. This is an internal error message. To fix the problem, contact your support team representative. *** CMA-0032 The CMA*TP CONNECT sequence could not be generated. The current SQL CONNECT statement could not be replaced by a SQL CMA sequence. Some lexical errors, detected while analyzing the declaration of the CONNECT variables, caused the garbled SQL variables to be removed from the Symbol Table. The SQL CMA Generator is not able to insert the CMATP sequence which requires all the CONNECT variables to be defined. Check the declaration of the SQL variables referenced in the SQL CONNECT statement and correct the syntax according to the error message A2 01EL

34 Description of SQL CMA Components *** CMA-0033 The CMA*TP COMMIT sequence could not be generated. The current SQL COMMIT statement could not be replaced by a SQL CMA sequence. Some lexical errors, detected while analyzing the declaration of the COMMIT variables, caused the garbled SQL variables to be removed from the Symbol Table. The SQL CMA Generator is not able to insert the CMATP sequence which requires all the COMMIT variables to be defined. Check the declaration of the SQL variables referenced in the SQL COMMIT statement and correct the syntax according to the error message. *** CMA-0034 Error while a label block is allocated A system error was returned by Windows 2000 during memory space allocation. The «alloc» system function was invoked. To fix the problem, contact your support team representative. *** CMA-0050 Referenced variable xxx has not a unique declaration. This variable name has been declared more than once. The SQL CMA Generator needs 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 its complete group items to avoid ambiguity. Otherwise, change the variable name. 47 A2 01EL 2-15

35 GCOS 7 SQL CMA User's Guide *** CMA-0051 Referenced variable xxx has no valid declaration. This variable referenced could not be found in the Symbol Table. Some lexical errors, detected while analyzing the variable declaration, caused the garbled variable to be removed from the Symbol Table. The SQL CMA Generator is unable to process the SQL statement which requires all its referenced variables to be defined. Check the declaration of this variable, referenced in the current SQL statement, and correct the declaration error. *** CMA-0052 Referenced variable xxx must be an elementary item not a group one. A SQL statement could not reference a group item, only elementary items could be referenced. This restriction is imposed by some database precompilers that issue an error while precompiling such a SQL statement. Suppose that the declaration is: 01 VAR1. 05 VAR11 PIX X(3). 05 VAR12 PIX X(3). The group item VAR1 must not be directly referenced in a SQL statement. Consequently, the following statement is invalid: EXEC SELECT COL1 INTO :VAR1 FROM TABLE1 WHERE... However, the following statement is valid: EXEC SELECT COL1, COL2 INTO :VAR11, :VAR12 FROM TABLE1 WHERE... Correct the referenced SQL variable according to the SQL CMA rules A2 01EL

36 Description of SQL CMA Components *** CMA-0053 Referenced variable xxx, with a level number, must not be declared inside a group item. There is a syntax error in the COBOL declaration of this variable. A variable declared with a 01 or 77 level number must not be an elementary data item. Correct the COBOL declaration according to the COBOL documentation. *** CMA-0054 Referenced variable xxx must be fully detailed until an elementary item. The SQL CMA Generator imposes a naming convention on an elementary name which is qualified. Suppose the following declaration: 01 VAR1. 02 VAR 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 «Declare Section»: 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 VAR1 FROM TABLE1 WHERE A2 01EL 2-17

37 GCOS 7 SQL CMA User's Guide Correct the referenced SQL variable according to the SQL CMA rules. *** CMA-0055 WARNING: A group item xxx with a 77 level number is not expected by some COBOL Precompilers. A group item declared with «77» level number is not allowed by some database precompilers which issue an error while precompiling such a SQL variable declaration. The SQL CMA Generator warns the user about this error case. Declare the group item with «01» level if possible. *** CMA-0056 Error while a host ident buffer is allocated. A system error is returned by Windows 2000 during memory space allocation. The «alloc» system function was invoked. To fix the problem, contact your support team representative. *** CMA-0060 Garbled context xxx is to be restored. This is an internal error message. To fix the problem, contact your support team representative A2 01EL

38 Description of SQL CMA Components *** CMA-0061 Garbled simple type found in host variable declaration: xxx. This is an internal error message. To fix the problem, contact your support team representative. *** CMA-0062 Incorrect referenced host variable in EXEC statement. This is an internal error message. To fix the problem, contact your support team representative. *** CMA-0063 Error while a include descriptor is allocated. A system error is returned by Windows 2000 during memory space allocation. The «alloc» system function was invoked. To fix the problem, contact your support team representative. 47 A2 01EL 2-19

39 GCOS 7 SQL CMA User's Guide *** CMA-0064 WARNING: This COBOL type is ignored by CMA Generator. Some database precompilers do not allow the following COBOL data types to be used in a SQL variable declaration: BIT. These COBOL data types are not processed by the SQL CMA Generator when they are 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. A system error is returned by Windows 2000 during memory space allocation. The «alloc» system function was invoked. To fix the problem, contact your support team representative *** CMA-0067 Error while INCLUDE checking: Infinite include loop detected on xxx. The SQL CMA Generator prevents a source file from including itself. This is to prevent the Generator from looping indefinitely. Correct the syntax of the INCLUDE command, according to the SQL CMA rules A2 01EL

40 Description of SQL CMA Components *** CMA-0068 EXEC SQL INCLUDE statement only accepts local INCLUDE filename. Some COBOL precompiler supports preprocessor statements such as: «EXEC SQL INCLUDE» 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 the pathname 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 be used. They do not process a SQL INCLUDE statement containing a pathname reference. Transform the «pathname» parameter to a «filename» parameter and transfer the referenced INCLUDE file locally. *** CMA-0070 Error while compilation descriptor is allocated. A system error is returned by Windows 2000 during memory space allocation. The «alloc» system function was invoked. To fix the problem, contact your support team representative 47 A2 01EL 2-21

41 GCOS 7 SQL CMA User's Guide *** CMA-0071 Syntax error: Include name must not be quoted. The «COPY» COBOL command used to include files is processed by the SQL CMA Generator if the command is inserted within the SQL «Declare Section». The SQL CMA Generator rejects a quoted include name because some COBOL compilers 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-ansi database is to be accessed. The SQL CMA Generator accepts only ANSI-compliant databases to be accessed in Transactional mode. SQL CMA applications, running in a TP environment, could access only ANSIcompliant databases A2 01EL

42 Description of SQL CMA Components *** CMA-0073 This COBOL feature is not supported. Some database precompilers do not allow the following standard COBOL features to 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 are used in SQL variable declarations. Correct the SQL variable declarations which use these COBOL features 47 A2 01EL 2-23

43 GCOS 7 SQL CMA User's Guide 2.2 SQL CMA COMMUNICATION INTERFACE: CMANET CMANET is the software layer that cooperates with a communications protocol supported by the mainframe and the Windows 2000 systems to provide a communications interface between the SQL CMA Client and Server processes. The communications protocol supported by the CMANET software is the standard TCP/IP communications protocol, available both on the mainframe (SOCKG7 product) and Windows 2000 platforms (WINSOCK2). As previously mentioned, CMANET supports the following functionality: Exchange SQL CMA messages between the Client and the Server processes, Convert the SQL CMA messages on the server side to ensure the data type compatibility. CMANET has 2 parts, installed both on the mainframe and Windows 2000 platforms: On the mainframe, the Linked Unit (LKU) «H_CMANET», located in the Sharable Module (SM) «H_SM_DCM», is delivered in the file «SYS.DCM.SYSTEM». On Windows 2000, several classes of files are delivered to compile and link the user sources: The code independent of the user application and of the database distribution is delivered as a DLL (Dynamic Link library) named dllcmanet.dll (delivered with dllcmanet.lib and dllcmanet.h). This code concerns the conversion and the trace. The following source file depends on the user application. It includes the main and some of the socket functions. It is compiled by the SQL CMA Installer during the SQL CMA Application Server building: «cmasvr.c» The INCLUDE files and COBOL COPY files delivered are necessary for the user application to be correctly compiled. (cmabuf.h, cmacst.h and CMA_H.CPY) On Windows 2000, a TCP/IP listener is provided to accept the client connections and start the appropriate SQL CMA application Server process(es). This listener is a Windows 2000 service «CMAservice.exe» : startup is automatic when it is selected at install time. Any action is to be done via Start-> Control Panel -> Administrative Tools -> Services. The default port is 9007 (refer to the file services in the directory system32\etc\drivers). You may modify the line that contains the string cmaserver. If you need debugging information, modify the delivered file CmaDebug.txt and set debug=yes. In this case, the file A2 01EL

44 Description of SQL CMA Components CMAservice.log (in the TEMP directory) contains more information and all the CMA applications are launched with the debug mode (all information is written in files named cmasql_<pid>.log,in the TEMP directory). Another executable «CMAlistener.exe» is delivered, and may be launched on another port (option port = ) and with the option debug. Start it with Start -> Programs -> SQL-CMA -> CmaOptionalListener. An executable CMAstop.exe is provided to stop the CMA listener(s) (Start it with Start -> Programs -> SQL- CMA -> CmaStop). The CMANET files are usually referenced as the «CMANET library» in the following chapters of this document. The CMA application server is built from a Cobol source with calls to Oracle SQL layer and the CMANET files. It will use Oracle SQL library and the COBOL Runtime to execute the requests on the database (ORASQL8.DLL and CBLRTSS.DLL). 2.3 SQL CMA TRANSACTIONAL INTERFACE: CMATP The CMATP module provides functions to get a SQL CMA application running in TP mode on the mainframe. Writing an SQL CMA Transactional application is described completely in Chapter 3 and building and using SQL CMA application in TP mode is described in Chapter A2 01EL 2-25

45 GCOS 7 SQL CMA User's Guide A2 01EL

46 3. Defining SQL CMA Applications This chapter explains how to make a user application consistent with the SQL CMA rules. A user database application must first comply with the language and database rules applied on the mainframe. SQL CMA imposes some limitations and writing conventions to the SQL variables and 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 the mainframe. Refer to the appropriate reference manuals. SQL CMA accepts as input COBOL sources conform to the GCOS 7 COBOL 85 standard FORMAT OF COBOL SOURCE The COBOL reference format describes a line of COBOL text in terms of character positions in a line as shown below: Table 3-1. Format of COBOL Source Columns Used For x to y Sequence number area y+1 Indicator area y+2 to z Area A z+1 to the line end Area B 8 characters before the end of line Card identifier area The length of area B depends upon the actual line length of the program and whether the optional «8 character card identifier area» is included. 47 A2 01EL 3-1

47 ORACLE 7 SQL CMA User's Guide The use of the «sequence number area» and the «card identifier area» can be controlled by specifying the language type of the COBOL program and by using the 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 4 tables: Table 3-2. SQL CMA COBOL Type: «DAT» Character Positions Used For 1-6 Sequence number area 7 Indicator area 8-11 Area A From position 12 to 8 positions before the end of Area B the line (Area B can extend up to character position 247) 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 For 1-6 Sequence number area 7 Indicator area 8-11 Area A From position 12 to the end of the line Area B (Area B can extend up to character position 255) Not Applicable Card identifier area The language type of this COBOL file is «DATASSF or DAT». The CARDID option of the CBL command is set to A2 01EL

48 Defining SQL CMA Applications Table 3-4. SQL CMA COBOL Type: «COB» Character Positions Used For Not Applicable Sequence number area 1 Indicator area 2-5 Area A From position 6 to 8 positions before the end of Area B the line (Area B can extend up to character position 247) Last 8 characters Card identifier The language type of this COBOL file is «COBOL or COB». The CARDID option of the CBL command is set to 1. Table 3-5. SQL CMA COBOL Type: «CBX» Character Positions Used For Not Applicable Sequence number area 1 Indicator area 2-5 Area A From position 6 to the end of the line Area B (Area B can extend up to character position 255) 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. 47 A2 01EL 3-3

49 ORACLE 7 SQL CMA User's Guide 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 Clause DISPLAY EBCDIC byte Required COMP Packed decimal Required PACKED-DECIMAL Packed decimal Required BINARY 16-bit or 32-bit fixed binary Required COMP-1 16-bit fixed binary Not Required COMP-2 32-bit fixed binary Not Required COMP-3 Packed decimal Required COMP-5 Packed decimal Required COMP-8 Packed decimal Required COMP-9 Floating single precision Not Allowed COMP-10 Floating double precision Not Allowed COMP-15 Floating quadruple precision Not Allowed BIT 1 bit per character position Required POINTER 32-bit direct address Not Allowed INDEX 6 bytes Not Allowed Both the words «COMP» and «COMPUTATIONAL» are allowed. 3.2 SQL CMA COBOL RULES As stated above, SQL CMA translates the user source into two generated SQL CMA sources intended to run on GCOS 7 and Windows 2000 systems respectively. SQL CMA does the following: 1. it performs a lexical analysis of the initial user source, 2. it builds a Symbol table to hold the declared variables, 3. it generates the final SQL CMA sources. As COBOL compilers on GCOS 7 are different from the Merant/Micro Focus compiler used on Windows 2000, SQL CMA must get the generated sources which are «compilable» on their respective systems. So, a data type mapping of the declared variables and some writing rules are necessary A2 01EL

50 Defining SQL CMA Applications EMBEDDED SQL AND PL/SQL The product is restricted to embedded SQL and PL/SQL. The term embedded refers to SQL or PL/SQL statements placed within the application program and delimited by EXEC SQL / END-EXEC keywords. The variables must be declared either within the Oracle DECLARE SECTION or in the embedded PL/SQL block. This means Oracle Call Interface (OCI) and Dynamic SQL method 4 are not supported because they use Cobol call statements (OCI) or declaratives outside the Oracle Declare Section (SQLDA in Dynamic SQL method 4) SQL CMA COBOL DATA TYPES The standard COBOL data types are converted in the generated SQL CMA files as follows: Table 3-7. COBOL Data Type Conversion COBOL Types User Source (GCOS 7) COBOL Types CMA Client Source (GCOS 7) COBOL Types CMA Server Source ( Windows 2000 ) BINARY COMP-2 COMP-5 S9(9) COMP COMP-3 COMP-3 COMP-1 COMP-1 COMP-5 S9(4) COMP-2 COMP-2 COMP-5 S9(9) COMP-3 COMP-3 COMP-3 COMP-5 COMP-3 COMP-3 COMP-8 COMP-8 COMP-3 COMP-9 COMP-10 COMP-2 COMP-10 COMP-10 COMP-2 COMP-15 COMP-10 COMP-2 DISPLAY DISPLAY DISPLAY PACKED-DECIMAL PACKED-DECIMAL PACKED-DECIMAL SQL CMA does not support all the standard COBOL data types: «INDEX», «POINTER» and «BIT» are rejected because these data types cause the Merant/Micro Focus pre-compiler on Windows 2000 to generate an error. The single FLOAT COMP-1 on Windows 2000 is not allowed as a host variable. To avoid this situation, SQL CMA anticipates and points out such COBOL data types if they are found in declarations of variables. Note: These rules affect only the SQL variables, not the other variables declared within the user source. All other variables can accept any 47 A2 01EL 3-5

51 ORACLE 7 SQL CMA User's Guide standard COBOL data type as attribute. For the SQL variables, see the next paragraph. 3.3 USING DATABASE SQL VARIABLES To get details about how to produce a user COBOL application, refer to the appropriate documentation provided by the database suppliers. However, SQL CMA imposes some limitations and writing conventions on SQL variables and statements. These are described in the following paragraphs. The following paragraphs describe the restrictions imposed by SQL CMA either because of: Database pre-compiler restrictions, or SQL CMA limitations DECLARING SQL VARIABLES A SQL variable, referenced in SQL statements, must be declared in a standard area named «DECLARE SECTION» as described in the database documentation. A «DECLARE SECTION» is delimited by the «EXEC SQL BEGIN DECLARE SECTION END-EXEC» and «EXEC SQL END DECLARE SECTION END- EXEC» statements. Only SQL variables are analyzed by SQL CMA. Other COBOL variables declared outside 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 «DECLARE SECTION» areas must be unique in the whole user program, i.e. the same SQL variable name must not be used in two declarations. Hereafter are the restrictions on «DECLARE SECTION» prescribed by the Database Suppliers and SQL CMA A2 01EL

52 Defining SQL CMA Applications SQL Variable Name SQL variable names must consist only of letters, digits and hyphens and must begin with a letter. SQL CMA differentiates between upper case letters and lower case letters. For example, in the following declarations, VAR1 and var1 are two different SQL variables: 01 VAR1 PIC X(10). 01 var1 PIC X(10). A SQL variable must not be a COBOL reserved word Comments As the database pre-compiler does, SQL CMA allows comment lines to be inserted in the «DECLARE SECTION». The Standard COBOL comment lines may be placed between two SQL variable declarations. The database comment lines (Double dash comment indicator) may be placed at the 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 a comment sequence, but to insert it either before or after the declaration. 47 A2 01EL 3-7

53 ORACLE 7 SQL CMA User's Guide Continuation Lines COBOL compilers allow you to continue words from one line to the next using a continuation indicator: a hyphen «-» in the «indicator area» column. SQL CMA allows only SQL variable names and level numbers to be split. All the other COBOL clauses must not be split (reserved words, PICTURE clause...). The following 3 declarations are equivalent 01 VAR1 COMP VA -R1 COMP VA - R1 COMP-1. A hyphen in the «indicator area» of a line indicates that the first non-blank character in Area B of the current line is the successor of the last non-blank character of the preceding line, without any intervening space 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 following characters: 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 A2 01EL

54 Defining SQL CMA Applications RENAMES Attribute of SQL Variables SQL CMA generates a SQL CMA error when a SQL variable with «RENAMES» attribute is referenced in a SQL statement: CMA-0052 Referenced variable «VAR1» must be an elementary item not a group one. A SQL variable with the «RENAMES» attribute could cause SQL CMA errors on the 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 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 a colon «:». For example: :SQLVAR The restrictions and naming conventions to apply when referencing a SQL variable are given below Comments COBOL comment lines may be placed within SQL statements. Comment lines start with an asterisk in the «indicator area». You can also place ANSI SQL-style comments which start with a double dash, within SQL statements, at the end of line. You are strongly recommended not to split an EXEC statement with a comment sequence, but to insert it before «EXEC SQL» clause or after «END-EXEC.» clause. 47 A2 01EL 3-9

55 ORACLE 7 SQL CMA User's Guide Example: * this is a COBOL comment line EXEC 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 place EXEC 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 Continuation Lines COBOL compilers allows to continue words from one line to the next using a continuation 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 be continued from one line to the next. Otherwise, SQL CMA will not recognize them A2 01EL

56 Defining SQL CMA Applications Referencing SQL Arrays of Variables SQL CMA understands and supports the declaration of arrays of variables. So, it allows 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 as shown in the example: INDEX. Note: The use of subscripted array elements in a SQL CMA source causes the following warning while compiling the generated Server source: «Table item not subscripted or indexed, first occurrence assumed.» You may ignore this compilation warning. 47 A2 01EL 3-11

57 ORACLE 7 SQL CMA User's Guide 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, COL2 INTO :VAR1 FROM TAB1 WHERE... The following statement is valid: EXEC SQL SELECT COL1, COL2 INTO :VAR111,:VAR112 FROM TAB1 WHERE... Elementary names need not be unique because they can be qualified to avoid ambiguity, using the «OF» COBOL clause. For example: EXEC SQL SELECT COL1, COL2 INTO :VAR111 OF VAR11 OF VAR1, :VAR112 OF VAR11 OF VAR1 FROM TAB1 WHERE... If an elementary item is to be qualified, it must be fully defined up to the highest level, even if that would be unnecessary in COBOL. The next example is valid for COBOL compilers, but invalid for SQL CMA: EXEC SQL SELECT COL1, COL2 INTO :VAR111 OF VAR1, :VAR112 OF VAR11 FROM TAB1 WHERE A2 01EL

58 Defining SQL CMA Applications Do not use the «IN» clause to qualify SQL items because some database precompilers reject it: EXEC SQL SELECT COL1, COL2 INTO :VAR111 IN VAR11 IN VAR1, :VAR112 IN VAR11 IN VAR1 FROM TAB1 WHERE... In this case, SQL CMA considers the «IN» COBOL keyword as part of the EXEC statement and not part of the referenced SQL variable. 3.4 INCLUDE FILES A user COBOL source could include other COBOL sources using an «EXEC SQL INCLUDE» preprocessor statement (described later in this chapter) and the «COPY» COBOL command. The INCLUDE file must get a file format compatible with the calling program format. 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 is being analyzed. SQL CMA follows the same rule as the COBOL compilers. Be careful to include files with a correct COBOL format because an INCLUDE file with an incorrect format could cause an SQL CMA generation failure. SQL CMA generates the INCLUDE statements such that: EXEC SQL INCLUDE <filename> END-EXEC. in user source. is translated into: COPY <client_file>. in Generated Client source. EXEC SQL INCLUDE <server_file> END-EXEC. in Generated Server source. 47 A2 01EL 3-13

59 ORACLE 7 SQL CMA User's Guide COPY <filename>. in user source. is translated into: COPY <client_file>. COPY <server_file>. in Generated Client source. in Generated Server source. The «EXEC SQL INCLUDE» preprocessor statement is always analyzed by SQL CMA, wherever it is located. The COBOL COPY statement is analyzed only if it is inserted in the «DECLARE SECTION». Otherwise, SQL CMA ignores it. You must use the «EXEC SQL INCLUDE» statement to include files that contain only SQL statements SQLCA INCLUDE FILE Error reporting is done exclusively through SQLCA structure whatever the value of the processing MODE (ANSI or ORACLE). A user source must include the «SQLCA» SQL file. You are strongly recommended to use the «EXEC SQL INCLUDE» preprocessor statement to declare the SQLCA file because the COPY COBOL command needs full a SQLCA pathname to be declared. SQL CMA processes the EXEC SQL INCLUDE declaration as follows: EXEC SQL INCLUDE SQLCA END-EXEC. in user source. is translated into: COPY SQLCAORA_<CBX COB DAT>. in Generated Client source. EXEC SQL INCLUDE SQLCA END-EXEC. in Generated Server source. SQL CMA processes the COBOL COPY command as follows: COPY SQLCA. in user source. is translated into: COPY SQLCAORA_<CBX COB DAT>. COPY SQLCA. in Generated Client source. in Generated Server source A2 01EL

60 Defining SQL CMA Applications ORACA INCLUDE FILE Oracle ORACA include file is not supported ORDINARY INCLUDE FILE A user source can call INCLUDE files other than the SQLCA file using the «EXEC SQL INCLUDE» preprocessor statement or the COPY COBOL command declared inside the «DECLARE SECTION». An ordinary INCLUDE filename is an alphanumeric character string (letters and digits). The special characters - or _ are also allowed to respect the specificity of GCOS 7 and Windows 2000 filenames. Dot characters. are not allowed in the INCLUDE filename. SQL CMA processes the EXEC SQL INCLUDE declaration as follows: EXEC SQL INCLUDE filename END-EXEC. in user source. is translated into: COPY cli_filename. EXEC SQL INCLUDE svr_filename END-EXEC. in Generated Client source. in Generated Server source. SQL CMA processes the COBOL COPY command as follows: COPY filename. in user source. is translated into: COPY cli_filename. COPY «svr_filename». in Generated Client source. in Generated Server source. where «filename» is a simple INCLUDE filename. 47 A2 01EL 3-15

61 ORACLE 7 SQL CMA User's Guide Path names are defined differently on GCOS and Windows An INCLUDE pathname would not be processed by the SQL CMA Generator unless all the referenced INCLUDE filenames are present in the «cmainst» Install directory at SQL CMA Source Generation. The SQL CMA Generator scans only this local directory. Note: The SQL CMA Generator does not allow a COBOL program to be nested in another COBOL program, i.e. there must be only one IDENTIFICATION division in the user source analyzed by SQL CMA Generator. So, an INCLUDE file must not include a COBOL program with an IDENTIFICATION division SQLCA STRUCTURE After each SQL statement execution, the database kernel returns the Oracle SQLCA record filled with error or warning information and other information relevant to the nature of the data handled. A user source must contain the SQLCA record, i.e. it must include the «SQLCA» file provided in the database distribution. The SQLCA record contents vary depending on the database editor but the SQLCA structure still contains the following fields: SQLCODE: Holds the Oracle error code of the executed SQL statement. 0 The statement ran without error. >0 (positive) The statement ran, but an exception was generated. 100 (when MODE=ANSI) or 1403 (when MODE=ORACLE) FETCH statement was issued, but no more rows satisfy the SELECT statement criteria used to define the cursor. No rows were processed. < 0 (negative) The statement did not run due to an application, database, system, or network error. SQLERRM: SQLERRP: SQLERRD: Holds the error message parameter (Text and length). Holds internal information. Array of six integer status codes (codes not in the fields listed later are reserved). sqlerrd[3] Number of rows affected. sqlerrd[5] Parse error offset A2 01EL

62 Defining SQL CMA Applications SQLWARN: This parameter is an array of 8 elements. They are used as WARNING flags. Each element holds specific information according the SQL statement executed and to the database concerned. The SQLCA fields are described succinctly here. To get a detailed description on their meanings, you must refer to the appropriate database documentation. As the SQLCA structure is not a constant structure, SQL CMA handles its own SQLCA record which only holds the constant fields listed previously. The SQLCA structure is declared in the «SQLCAORA_<CBX COB DAT>» files. That is the reason why a SQLCA INCLUDE statement is translated into a: «COPY SQLCAORA_<CBX COB DAT>» statement in the generated SQL CMA Client file as detailed in the INCLUDE paragraph. The SQLCAORA files are provided and must be present on the mainframe environment when a SQL CMA Client is to be compiled and linked. As a generated SQL CMA Client source holds only SQLCAORA fields, it is not possible for a user source to reference other data specific to a database supplier. 47 A2 01EL 3-17

63 ORACLE 7 SQL CMA User's Guide 3.5 SQL CMA APPLICATIONS A user application including Oracle management capabilities must be written in compliance with the standard Oracle documentation: Documentation in line of Oracle database : Net Express documentation for ESQL in COBOL source and OpenESQL. The following paragraphs describe the restrictions imposed by SQL CMA because of some OpenESQL precompiler restrictions or due to SQL CMA limitations RESTRICTIONS ON DECLARE STATEMENT SQL CMA does not support a «DECLARE CURSOR» SQL statement referencing explicit input or output SQL variables Declare cursor with input variable Input SQL variables are given by the user program to the database server to process the SQL statement: WHERE clause of SQL statements can use input SQL variables. When a «DECLARE CURSOR» statement is used to hold a SQL statement definition, the SQL statement is parsed and processed further, using the «OPEN» statement. Using SQL CMA, the input variables are transferred to the server program when processing the «DECLARE CURSOR» statement and cannot be reevaluated on the «OPEN» statement. Example (Non-supported SQL Sequence): The following SQL sequence is not supported: EXEC SQL DECLARE C1 CURSOR FOR SELECT ENAME FROM EMP WHERE DEPTNO = :PDEPTNO END-EXEC. * EXEC SQL WHENEVER NOT FOUND GO TO CHECK-FETCH END-EXEC. DEPT-LOOP. DISPLAY "Department Number? " WITH NO ADVANCING. ACCEPT DEPTNON. IF DEPTNON = 0 GO TO EXIT-STOP. MOVE DEPTNON TO PDEPTNO. * EXEC SQL OPEN C1 END-EXEC A2 01EL

64 Defining SQL CMA Applications FETCH-LOOP. EXEC SQL FETCH C1 INTO :PENAME END-EXEC. GO TO FETCH-LOOP. CHECK-FETCH. GO TO DEPT-LOOP. Example (Replacement SQL Sequence): The previous "non-supported" sequence could be made valid by using the following: DEPT-LOOP. DISPLAY "Department Number? " WITH NO ADVANCING. ACCEPT DEPTNON. IF DEPTNON = 0 GO TO EXIT-STOP. MOVE DEPTNON TO PDEPTNO. * EXEC SQL WHENEVER NOT FOUND CONTINUE END-EXEC. EXEC SQL DECLARE C1 CURSOR FOR SELECT ENAME FROM EMP WHERE DEPTNO = :PDEPTNO END-EXEC. * EXEC SQL WHENEVER NOT FOUND GO TO CHECK-FETCH END-EXEC. * EXEC SQL OPEN C1 END-EXEC. FETCH-LOOP. EXEC SQL FETCH C1 INTO :PENAME END-EXEC. GO TO FETCH-LOOP. CHECK-FETCH. GO TO DEPT-LOOP. The DEPT-LOOP has been moved before the «DECLARE CURSOR» to transfer the new value of PDEPTNO, and an extra WHENEVER CONTINUE has been added before the «DECLARE CURSOR» to overwrite the NOT FOUND SQLCODE set by the previous FETCH. 47 A2 01EL 3-19

65 ORACLE 7 SQL CMA User's Guide Declare cursor with output variable Output SQL variables are the result of SQL statement processing and their values are returned by the server process: SELECT statements use output SQL variables. When a «DECLARE CURSOR» statement is used to hold a SQL statement definition, 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: PREPARE and 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 the following: 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. 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 A2 01EL

66 Defining SQL CMA Applications This restriction on the «DECLARE CURSOR» statement is applied only if the output SQL variables are referenced inside RESTRICTION ON CURSOR OPERATION UNDER TDS When the connection to the database is done using a logical database identifier ( AT clause), it is mandatory to identify the logical connection on each cursor statement. This is necessary because SQL CMA maintains a connection cache for TDS and must identify the connection on each statement. Example (Non-supported SQL Sequence): The following SQL sequence is not supported: EXEC SQL CONNECT :USR IDENTIFIED BY :PSW AT :DBID USING :HST END-EXEC. EXEC SQL AT :DBID PREPARE PREP1 FROM <<SELECT COL1, COL2, COL3 FROM TABLE1 WHERE COL1 = A >> END-EXEC. EXEC SQL DECLARE CURSOR1 CURSOR FOR PREP1 END-EXEC. EXEC SQL OPEN CURSOR1 END-EXEC. EXEC SQL FETCH CURSOR1 INTO :VAR1, :VAR2, :VAR3 END-EXEC. EXEC SQL CLOSE CURSOR1 END-EXEC. Example (Replacement SQL Sequence): The previous "non-supported" sequence could be made valid by using the following: EXEC SQL CONNECT :USR IDENTIFIED BY :PSW AT :DBID USING :HST END-EXEC. EXEC SQL AT :DBID PREPARE PREP1 FROM <<SELECT COL1, COL2, COL3 FROM TABLE1 WHERE COL1 = A >> END-EXEC. EXEC SQL AT :DBID DECLARE CURSOR1 CURSOR FOR PREP1 END-EXEC. EXEC SQL AT :DBID OPEN CURSOR1 END-EXEC. EXEC SQL AT :DBID FETCH CURSOR1 INTO :VAR1, :VAR2, :VAR3 END-EXEC. EXEC SQL AT :DBID CLOSE CURSOR1 END-EXEC. 47 A2 01EL 3-21

67 ORACLE 7 SQL CMA User's Guide 3.6 SQL CMA TP DESCRIPTION This section describes the SQL CMA TP mechanism resulting from the use of specific SQL commands such as CONNECT, COMMIT and ROLLBACK which have specific behavior in the TDS environment SQL CMA TP CACHE CONCEPT SQL CMA TP Context Cache definition To understand the SQL CMA TP Context Cache concept, some definitions are needed: Physical Connection Database Connection is a telecommunication link established between a Client and a Server site. Data is exchanged via this link according to a defined protocol (CMANET in the SQL CMA product). is a link to a remote database between a Client Database application and a Server Database. It is identified by a unique profile which is composed of the CONNECT action parameters: Database identification Connection name User/Password clause Logical Connection is a virtual link mapped on a Physical Connection and a Database connection (previously established by other CONNECT actions) A2 01EL

68 Defining SQL CMA Applications Some SQL CMA terms must be defined: SQL CMA TP Connection Entry specifies a Database Connection. Its name is a combination of the CONNECT action parameters. SQL CMA TP Context is a set of SQL CMA TP Connection Entries. The first SQL CMA TP Connection Entry has a particularity because it is associated with a Physical Connection. Its name is the same as the first SQL CMA TP Connection Entry. A SQL CMA TP Context is associated with a unique TDS commitment unit until it ends. SQL CMA TP Context Cache is a set of SQL CMA TP Contexts. Each entry of this table holds the name of a SQL CMA TP Context. The SQL CMA TP Context Cache is used by all the commitment units in the TDS. These objects are handled inside a TDS commitment unit. The CONNECT action is analyzed to determine if the connection is a Physical or a Database or a Logical connection SQL CMA TP Context states A SQL CMA TP Context is associated with a TDS commitment unit. A SQL CMA TP Context has several states: UNUSED FREE BUSY There are no physical connections, the SQL CMA TP Context is just initialized. The SQL CMA TP Context is free and may be used by a TDS commitment unit. The SQL CMA TP Context keeps a Physical Connection and some Database Connections established between the Client and Server sites. The SQL CMA TP Context is already used by a TDS commitment unit and is no longer available for another TDS commitment unit. The SQL CMA TP Context keeps a Physical Connection and some Database Connections established between the Client and Server sites. 47 A2 01EL 3-23

69 ORACLE 7 SQL CMA User's Guide DAMAGED The SQL CMA TP Context is garbled, so it is declared unavailable during the execution of the current commitment unit. The SQL CMA TP Contexts signaled as DAMAGED are all cleaned (UNUSED state) at the end of the commitment unit Why a SQL CMA TP Context cache? SQL CMA maintains a cache of SQL CMA TP Contexts to hold the database connections and the cursor parsing. Contexts may be «shared» by several SQL CMA users. Sharing the contexts saves unnecessary Physical Connections and reduces the number of Servers needed to serve the TP application. Consequently, the memory requirements and CPU consumption are greatly reduced CONNECT ACTION A CONNECT action is performed when some specific SQL statements are detected in the SQL CMA TP application. The CONNECT action, used to log on to the database, must be the first SQL statement in the TDS commitment unit. Only declarative SQL statements and host language code can logically precede the CONNECT action CONNECT action provided by Oracle The CONNECT action is started by the following EXEC SQL statements: EXEC SQL CONNECT <usr> IDENTIFIED BY <psw> [AT <dbid>] [USING <alias>] END-EXEC. where: < usr >, <psw>, <dbid>, and <alias> are strings of 30 bytes long To get more details about these SQL statements and their parameters, refer to the standard «Programmer s Guide to the Oracle Precompilers» manual. The "EXEC SQL CONNECT" statement is the only one allowed to establish a connect with an Oracle database A2 01EL

70 Defining SQL CMA Applications Relationship between CONNECT action and SQL CMA TP Context The CONNECT action handles the SQL CMA TP Context Cache as follows: First CONNECT Action in a TDS Commitment Unit: When the first CONNECT action is detected in a TDS commitment unit: 1. The Context Cache Manager searches a SQL CMA TP Context signaled as FREE to get a Physical connection established previously. It must also find a SQL 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 TDS commitment unit until it ends, so the context is declared BUSY. If no SQL CMA TP Context is found, a SQL CMA TP Context Cache entry signaled as UNUSED is reserved. Then, a new SQL CMA TP Context is created, identified by the current CONNECT parameters. 2. A Physical Connection is established between the Client and Server sites. 3. A SQL CONNECT order is sent to the remote Server. 4. A SQL CMA TP Connection entry is created in the SQL CMA TP Context if the Database Connection succeeds. 5. The new SQL CMA TP Context is declared BUSY. Next EXEC SQL CONNECT in the TDS Commitment Unit: 1. The Context Cache Manager gets the SQL CMA TP Context allocated by the first CONNECT action in the TDS commitment unit. 2. The SQL CMA TP Connection entries associated with the current SQL CMA TP Context are scanned to check if a Database Connection is not already established. 3. A SQL CONNECT order is sent if the current CONNECT action is not already done. Then, a SQL CMA TP Connection entry is created and added to the SQL CMA TP Context. This algorithm will be applied for each TDS commitment unit. 47 A2 01EL 3-25

71 ORACLE 7 SQL CMA User's Guide CONNECT action errors If a SQL CMA TP Connection Entry could not be created, all the other SQL CMA TP Connection Entries of the current SQL CMA TP Context are removed, i.e. 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 inform the SQL CMA TP application COMMITMENTS When a SQL CMA TP application runs in the TDS environment, all commitments units are handled by TDS (as far as possible). SQL CMA TP defines some main rules to handle the commitment: The commitment of a database is deferred to the end of the commitment unit regardless of where a commit request appears in the code. If only one database is accessed inside a commitment unit (whether it includes a SQL COMMIT statement or not), this database is really committed 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 unit is really committed at the end of the commitment unit. All other databases referenced during the commitment unit execution are rolled back. 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 is really committed at the end of the commitment unit. All other databases referenced during the commitment unit execution are rolled back. These rules are applied if no error has occurred. WARNING As "EXEC SQL COMMIT" statement execution is deferred to the end of TPR, the syntax errors are not detected for that statement A2 01EL

72 Defining SQL CMA Applications COMMIT ACTION A COMMIT action is used to commit all modifications made to the database during a commitment unit execution. SQL CMA TP imposes the commitment to be done at the end of a commitment unit. A commitment may be implicit or explicit. A commitment is explicit when a specific function or a SQL statement is detected in the SQL CMA TP application Implicit commitment Even if no explicit commitment is specified, an implicit commitment is performed at the end of the commitment unit. The last database referenced just before the end of the commitment unit is really committed. The other databases are rolled back Explicit commitment An explicit commitment can be caused by a call to the TDS «DFCMIT» procedure or by inserting a SQL COMMIT statement in the SQL CMA TP application. The TDS «DFCMIT» procedure acts according to the TDS rules, i.e. the last database referenced just before the end of the commitment unit is really committed and the others are rolled back. The SQL COMMIT action differs from the «DFCMIT» action because the database really committed is the database explicitly referenced by the SQL COMMIT statement. Only the first SQL COMMIT statement is analyzed. All other SQL COMMIT statements are ignored SQL COMMIT statement A COMMIT action is required when the following SQL statement is inserted: EXEC SQL [AT <dbid>] COMMIT WORK END-EXEC. To get more details about this SQL statement, refer to the standard manual «Programmer s Guide to the Oracle Precompilers». 47 A2 01EL 3-27

73 ORACLE 7 SQL CMA User's Guide Examples of COMMIT actions Here are examples of different commitment actions. The following commitment units update two Oracle databases: DB1 and DB2. Example 1: Commitment using DFCMIT IDENTIFICATION DIVISION PROGRAM-ID. XXX.... EXEC SQL CONNECT AT DB1 USING END-EXEC.... EXEC SQL CONNECT AT DB2 USING END-EXEC.... EXEC SQL AT DB1 INSERT INTO T1 VALUES (100) END-EXEC.... EXEC SQL AT DB2 INSERT INTO T2 VALUES (100) END-EXEC.... CALL DFCMIT.... EXIT. At the end of the commitment unit, only the DB2 database is really committed because 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 DIVISION PROGRAM-ID. XXX.... EXEC SQL CONNECT AT DB1 USING END-EXEC.... EXEC SQL CONNECT AT DB2 USING END-EXEC.... EXEC SQL AT DB1 INSERT INTO T1 VALUES (100) END-EXEC.... EXEC SQL AT DB2 INSERT INTO T2 VALUES (100) END-EXEC.... EXEC SQL AT DB1 COMMIT WORK END-EXEC.... EXIT. At the end of the commitment unit, only the DB1 database is really committed because it is explicitly referenced on the SQL COMMIT statement. The DB2 database is rolled back and the corresponding INSERT is lost A2 01EL

74 Defining SQL CMA Applications Example 3: Commitment using several SQL COMMIT IDENTIFICATION DIVISION PROGRAM-ID. XXX.... EXEC SQL CONNECT AT DB1 USING END-EXEC.... EXEC SQL CONNECT AT DB2 USING END-EXEC.... EXEC SQL AT DB1 INSERT INTO T1 VALUES (100) END-EXEC.... EXEC SQL AT DB1 COMMIT WORK END-EXEC.... EXEC SQL AT DB2 INSERT INTO T2 VALUES (100) END-EXEC. EXEC SQL AT DB2 COMMIT WORK END-EXEC.... EXIT. At the end of the commitment unit, only the DB1 database is really committed because it is the first database explicitly referenced by a SQL COMMIT statement. The DB2 database is rolled back and the corresponding INSERT is lost according to the SQL CMA TP rules Automatic restart The automatic restart facility is activated when a commitment fails. The TDS monitor cannot report synchronously a commitment failure to a SQL CMA TP application, so a restart is necessary to know the commitment status. When the commitment unit restarts, SQL CMA TP asks for the commitment status on the first SQL statement (which is a CONNECT action). So, the automatic restart normally relative to a COMMIT action could disturb a CONNECT action. 47 A2 01EL 3-29

75 ORACLE 7 SQL CMA User's Guide 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 SQL return 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 SQL return statuses are analyzed. A wrong return status causes a physical telecommunication disconnection and the current SQL CMA TP Context is set to UNUSED. If the SQL COMMIT statement returns a garbled status or no response is received from the remote database, the automatic restart is activated ROLLBACK ACTION Unlike the COMMIT action, a ROLLBACK action is always synchronously executed, i.e. it is not deferred to the end of the commitment unit. A ROLLBACK action cancels a transaction and undoes any changes that occurred since 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 TP application, and has no effect of the other referenced databases ROLLBACK statement provided by Oracle A ROLLBACK action is required when inserting the following SQL statement: EXEC SQL [AT <dbid>] ROLLBACK [WORK] END-EXEC. To get more details about this SQL statement, refer to the standard «Programmer s Guide to the Oracle Precompilers» manual A2 01EL

76 Defining SQL CMA Applications Examples of ROLLBACK actions Below are examples of different ROLLBACK actions. Example 1: ROLLBACK action on one database IDENTIFICATION DIVISION PROGRAM-ID. XXX.... EXEC SQL CONNECT USING END-EXEC.... EXEC SQL INSERT INTO T1 VALUES (100) END-EXEC.... EXEC SQL ROLLBACK WORK END-EXEC.... EXEC SQL INSERT INTO T2 VALUES (100) END-EXEC.... EXEC SQL COMMIT WORK END-EXEC.... EXIT. The ROLLBACK statement is executed synchronously, so the first INSERT statement 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 DIVISION PROGRAM-ID. XXX.... EXEC SQL CONNECT AT DB1 USING END-EXEC.... EXEC SQL CONNECT AT DB2 USING END-EXEC.... EXEC SQL AT DB1 INSERT INTO T1 VALUES (100) END-EXEC.... EXEC SQL AT DB2 INSERT INTO T2 VALUES (100) END-EXEC.... EXEC SQL AT DB2 ROLLBACK WORK END-EXEC.... EXEC SQL AT DB1 COMMIT WORK END-EXEC.... EXIT. When the ROLLBACK statement is executed, the INSERT statement executed on the DB2 database is immediately rolled back. 47 A2 01EL 3-31

77 ORACLE 7 SQL CMA User's Guide 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 the commitment unit Relationship between ROLLBACK action and SQL CMA TP context A ROLLBACK statement has no effect on the current SQL CMA TP context. 3.7 SQL CMA TP ERRORS SQL CMA TP errors are returned in the SQLCODE variable that must be checked to take appropriate actions. Most of errors cannot cause data inconsistency in the database, but some errors (the errors -5 and -6) must be handled carefully and an appropriate error treatment could be an abort of the current transaction. However, if such an error occurs in a commitment unit where database changes have been deferred, you must save all the critical data in a secure area such as the TRANSACTION-STORAGE. Alternatively, you can undo the changes performed in the previous commitment unit. To do this, all the data necessary to undo these changes must have been saved in a secure area and the previous commitment unit has to move them into TRANSACTION-STORAGE A2 01EL

78 4. SQL CMA Installer This chapter explains how to build the SQL CMA sources and how to generate the SQL CMA executable in the appropriate environments: Mainframe and Windows A SQL CMA Installer (cmainst.exe) is provided on Windows 2000 to administer SQL CMA. This consists of generating the SQL CMA sources, and building the SQL CMA Server executable on Windows The SQL CMA Client executable is built in the mainframe environment. This operation is not processed by the SQL CMA Installer. Building the SQL CMA Server requires the Oracle 8i or 9i Client software to be installed (Pro*Cobol component), Merant/Micro Focus Net Express COBOL compiler to be installed (it uses the COBOL compiler, cbllink and cobol runtime) and also a C compiler (Visual C++ version 6.0, option standard) This section details the steps necessary to get the SQL CMA Installer up and running, and how to process the following actions: Starting SQL CMA Installer Starting SQL CMA Source generation Starting SQL CMA Server building 47 A2 01EL 4-1

79 GCOS 7 SQL CMA User's Guide 4.1 PREREQUISITES ORACLE PRODUCT At least the Client software is required : if not, a warning message is sent during the SQL CMA installation (InstallShield). Oracle Pro*COBOL is necessary for SQL CMA source generation phase, and Oracle runtime client libraries are necessary for execution phase. If the TDS mode is used, a specific table CMATP must be created on each database (it is used via ESQL in the TDS application). You may use the file ORA-CMATP.sql (delivered in the directory C:\Program Files\Bull\SQL-CMA\Cmagen ) MERANT/MICRO FOCUS PRODUCT This product is required : if not, a warning message is sent during the SQL CMA installation (InstallShield). COBOL compiler is used for SQL CMA sever building phase, and COBOL runtime library is necessary for execution phase C COMPILER PRODUCT A Visual C++ Compiler version 6.0 must be installed with the option REGISTER ENVIRONMENT VARIABLE and with update of the environment variables (lib, include, path). It is used during SQL CMA server building phase SQL CMA PRODUCT Install shield proposes to download the CMA product in the directory C:\Program Files\Bull\SQL-CMA : you may choose another directory. If the CMA product is downloaded on the directory C:\Program Files\Bull\SQL- CMA, Install shield builds a specific environment variable CMA_HOME_SQL with the value C:\Program Files\Bull\SQL-CMA\Cmanet\CmaExec. If default value, the executable cmainst.exe is in the directory C:\Program Files\Bull\SQL-CMA\Cmagen. Install Shield builds a shortcut named CMAinst in Start -> Programs ->SQL-CMA A2 01EL

80 SQL CMA Installer 4.2 STARTING SQL CMA CMAINST PRODUCT Figure 4-1. Starting SQL CMA CMAINST Product You may also open a Windows command processor, use the CHDIR Command to go in the C:\Program Files\Bull\SQL-CMA\Cmagen directory and type cmainst The product cmainst will start a Graphical User Interface to generate sources and build server executable. 47 A2 01EL 4-3

81 GCOS 7 SQL CMA User's Guide INTERACTIVE PROGRAM CMAINST Figure 4-2. Interactive Program CMAINST The SQL CMA Installer is an interactive program that provides the ability to: Generate SQL CMA Client and Server sources from a user application Build the SQL CMA Server executable, ready to be started on Windows These actions can be performed by selecting the right options proposed on the main screen. Each SQL CMA option : propose a working directory C:\Program Files\Bull\SQL-CMA\Cmagen\work This directory contains some samples. It is possible to use another directory for your working directory (during cmainst execution). You will copy your input files (sources *.pco) in it and get your output files (client files, server executable, ) in it. Propose a logfile directory collects its own input parameters by displaying some request screens A SQL CMA operation could be canceled by entering the specific key, as indicated at the top of the current screen. This causes a return to the main screen A2 01EL

82 SQL CMA Installer 4.3 STARTING SQL CMA SOURCE GENERATION First you must transfer GCOS7 COBOL user sources from DPS7000 to Windows 2000 (Refer to paragraph for Windows 2000 source name syntax). From a user program, the SQL CMA Source generation launch : 1. cmag-oracle.exe to build two output programs: a SQL CMA GCOS7 COBOL client program a SQL CMA Pro*COBOL server program. 2. Oracle Pro*COBOL precompiler to build: a SQL CMA Merant COBOL server program. Each user program is characterized by several parameters such as: The DATABASE to access: Oracle database The programming LANGUAGE: COBOL The application running mode: BATCH or TP These input parameters are required by the SQL CMA generator to build the SQL CMA sources. The generated SQL CMA sources are built locally in the «cmainst» directory. They must stay there, if a SQL CMA server building operation is to be performed later. The SQL CMA Source Generation proposes a recapitulative screen before starting the requested operation. The screen relative to the SQL CMA source generation needs the following parameters to be input in order to find out the user program characteristics. 47 A2 01EL 4-5

83 GCOS 7 SQL CMA User's Guide Figure 4-3. Starting SQL CMA Source Generation «LIST NAME» AND «SOURCES NAME(S)» PARAMETERS The SQL CMA source generator needs the SQL CMA source name as input. A source name is a character string which contains neither the «-» nor the «_» characters. These specific characters cause COBOL compiling errors. The Source name syntax allowed by the SQL CMA Installer is Prog.pco For ease of use, the SQL CMA Installer accepts a list of source names to be entered. Instead of a list, you can give a «file of SOURCE list» containing the names of the SQL CMA Source to generate : this list should be a text file with suffix.txt. Each line defines a name of a SQL CMA Source as shown hereafter: A2 01EL

84 SQL CMA Installer File of SOURCE List for Oracle (Mylist.txt) prog1.pco prog2.pco prog3.pco prog4.pco With the browse button, you may change select input file or input list 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 LIST or SOURCE NAME(s) is sent and the window «SOURCE GENERATION» is sent again. The SQL CMA Installer stores the list of the source names and performs a separate generation of each source name. This method avoids calling the SQL CMA generation screen each time a user source is to be analyzed «ORACLE SETTINGS» PARAMETERS Format Select the GCOS7 Cobol format of the Source(s). Refer to chapter 3 for explanations. SQL mode Select the SQL Mode. It can be ANSI (ROW NOT FOUND SQLCODE equals +100) or ORACLE (ROW NOT FOUND SQLCODE equals +1403). ProCobol precompiler option string Specify here yours specific Pro*COBOL options. Some useful options are: picx = charf varchar2 varchar2 is Oracle7 precompiler behaviour sqlcheck = syntax semantics full required for embedded PL/SQL userid = user/password@alias required for embedded PL/SQL unsafe_null = no yes yes allows fetching null without variable indicator 47 A2 01EL 4-7

85 GCOS 7 SQL CMA User's Guide Refer to «Programmer s Guide to the Oracle Precompilers» documentation for all available options «APPLICATION RUNNING IN» PARAMETER This parameter indicates the running mode of the user application to the SQL CMA Generator, either: BATCH mode, or Transactional environment (TP). This parameter causes the SQL CMA Generator to insert specific sequences performing the Connection Cache handling in the SQL CMA Client source. These sequences call a succession of CMATP functions. If the user gives a list of user source names to be translated, the «Application Running in» parameter is applied to all the source names of the list. This means that if the TP parameter is chosen, all the user sources listed during this phase will be generated with TP sequences inserted in their code. During the Installshield phase, you must choose the default value (TP or BATCH) used in the CMAinst. This option is stored in a file named CmainstOptions.txt in the CmaGen directory, and may be modified after the installation «DEBUG MODE» PARAMETER This parameter is useful to get a detailed reporting during the Source generation steps. The DEBUG options are fully explained in the «DEBUG option» paragraph in Chapter 2. When the DEBUG mode is selected, all the possible DEBUG options are displayed: Lexical Analysis Debug Symbol Table Debug Symbol Research Debug The default value for this parameter is NO DEBUG A2 01EL

86 SQL CMA Installer «LOGGING FILE NAME» PARAMETER This Logging file provides a record of the SQL CMA Source Generation process. It lists any errors issued at installation time. To get an accurate and comprehensive tracking of an Installation failure, refer to the Logging file. During a SQL CMA source generation, the following steps are performed by the Installer: 1. Analyze the Input parameters. 2. Generate the SQL CMA Client and Server sources with their include files. By default, the logging file is named «<TEMP> 1 \cmainst.log». If desired, you can choose another logging file name or directory VALIDATION OF SOURCES TO GENERATE The following request allows the user to validate the input parameters before starting the SQL CMA Source Generation. A final screen is displayed to summarize the Source characteristics, whose names have been previously entered, as follows: SOURCE to proceed: xxx.pco Access to << ORACLE>> Database. COBOL Language with CBX format. Running in <<TP>> mode. No DEBUG mode during the source generation. You may accept (OK) or invalidate (CANCEL). 1 <TEMP> is the value of the environment variable TEMP 47 A2 01EL 4-9

87 GCOS 7 SQL CMA User's Guide 4.4 STARTING SQL CMA SERVER BUILDING The SQL CMA Installer builds a SQL CMA Server executable ready to be started on Windows To build the Server executable it performs the following steps: retrieve the includes files (cmabuf.h,cmacst.h, dllcmanet.h), the copy cobol file (CMA_H.CPY) and the source file cmasvr.c in the directory C:\Program Files\Bull\SQL-CMA\Cmagen\INCLUDE retrieve the library file dllcmanet.lib in the directory C:\Program Files\Bull\SQL-CMA\Cmagen\lib Merant/Micro Focus COBOL phase : compile the generated SQL CMA server program(s) (COBOL source) specified by the user Merant/Micro Focus cbllink phase : link the generated SQL CMA server objects in a xx_cobol.dll (if SERVER BINARY NAME = xx) Visual C++ compiler cl phase : compile the CMANET sources (cmasvr.c). It uses an include file which depends on the user application Visual C++ link phase : link the cmasvr.obj with the dllcmanet library, the user xx_cobol.lib and the specific database libraries to get an executable This assumes that, at least, an Oracle Client environment (libraries, include files,...) is installed locally and is accessible from the SQL CMA Installer. The SQL CMA Server building is characterized by several parameters such as: The name of the application server that will be started on Windows 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 the SQL CMA Server executable A2 01EL

88 SQL CMA Installer Figure 4-4. Starting SQL CMA Server Building To identify the SQL CMA Server components, the SQL CMA Server building screen needs the following parameters to be input «SERVER BINARY NAME» PARAMETER This parameter identifies the SQL CMA Server program which will be started on Windows 2000 in order to communicate with the SQL CMA Client program running on the mainframe. This program will process SQL statements when requested by the SQL CMA Client program through CMANET messages. The SQL CMA Client and Server programs share information statically (SQL CMA tables are inserted during the SQL CMA Source generation) to provide SQL CMA working integrity. This ensures that a SQL CMA Client is not 47 A2 01EL 4-11