sql programming guide

Cincom® MANTIS®

SQL Programming Guide

P39-1381-01

For Android™, iOS®, Windows®, OS X®, Linux®, UNIX®, and OpenVMS®

Version 3.5.01

Cincom® MANTIS® SQL Programming Guide Publication Number P39-1381-01 © 2018, 2019 Cincom Systems, Inc. All Rights Reserved This document contains unpublished, confidential, and proprietary information of Cincom. No disclosure or use of any portion of the contents of these materials may be made without the express written consent of Cincom. See https://www.cincom.com/us/company/terms-policies for a list of Cincom trademarks and other trademarks that may appear in Cincom product documentation. All other trademarks are trademarks or registered trademarks of their respective companies. Cincom Systems, Inc. 55 Merchant Street Cincinnati, Ohio 45246-3732 USA PHONE: +1 513 612 2300 FAX: +1 513 612 2000 WORLD WIDE WEB: http://www.cincom.com

Attention: Some Cincom products, programs, or services referred to in this publication may not be available in all countries in which Cincom does business. Additionally, some Cincom products, programs, or services may not be available for all operating systems or all product releases. Contact your Cincom representative to be certain the items are available to you. External Web site disclaimer: Cincom Systems, Inc. does not own, nor does it warrant the accuracy, adequacy or completeness of, the information and materials contained in linked documentation, and expressly disclaims liability for any errors or omissions in the information and materials. No warranty of any kind, implied, express or statutory, including but not limited to the warranties of non-infringement of third party rights, title, merchantability, fitness for a particular purpose and freedom from computer virus, is given in conjunction with the information and materials contained in this linked documentation. Nothing contained herein constitutes nor is intended to constitute an offer, inducement, promise, or contract of any kind. The data, information, and materials contained herein are for informational purposes only and are not represented to be error free. Any links are provided as a courtesy. They are not intended to nor do they constitute an endorsement by Cincom Systems, Inc. of the linked materials.

https://www.cincom.com/us/company/terms-policies

http://www.cincom.com/

Release information for this manual Cincom® MANTIS® SQL Programming Guide, P39-1381-01, is dated June 1, 2019. This document supports release 3.5.01 of MANTIS®.

Cincom Technical Support for MANTIS® To contact support, please visit https://supportWeb.cincom.com.

https://supportweb.cincom.com/

SQL Programming Guide, P39-1381 4 Contents

Contents

1. Software requirements for MANTIS SQL Support ............................... 8

Software requirements for using MANTIS SQL Support with ODBC ................................. 8 Operating systems on which the MANTIS Server supports ODBC .............................. 8 Special ODBC support consideration for a MANTIS Server on Android or iOS ............... 8 Special ODBC support requirement for a MANTIS Server on Linux or UNIX .................. 8

Software requirements for using MANTIS SQL Support with Common platform DB2 ........... 9 Software requirements for using MANTIS SQL Support with Oracle .............................. 10 Software requirements for using MANTIS SQL Support with Common platform SUPRA ....... 11 Software requirements for using MANTIS SQL Support with Oracle Rdb ......................... 12

2. MANTIS SQL Support overview .................................................... 13

Introduction to MANTIS SQL Support ................................................................... 13 MANTIS SQL Support and non-SQL MANTIS applications ............................................ 14 Embedding SQL statements in a MANTIS application program .................................... 15 Variables in MANTIS SQL Support ....................................................................... 16 Differences between SQL in MANTIS and SQL in COBOL ............................................ 17 Logical names .............................................................................................. 18 Static and dynamic SQL .................................................................................. 19 Security in MANTIS SQL support ......................................................................... 20

3. System maintenance for MANTIS SQL Support ................................. 21

Introduction to system maintenance for MANTIS SQL Support .................................... 21 Connect to a database .................................................................................... 22

Connect to an ODBC database ..................................................................... 22 Connect to a Common platform DB2 database .................................................. 22 Connect to an Oracle database .................................................................... 22 Connect to a SUPRA database ...................................................................... 22 Connect to an Oracle Rdb database on OpenVMS .............................................. 22

MANTIS SQL options ....................................................................................... 23 Update the MANTIS User profile with the default SQL DBTYPE ................................... 24

4. Connect to and disconnect from a database ................................... 25

Connect to and disconnect from an ODBC database ................................................ 25 Explicitly connect to an ODBC data source ...................................................... 25 Disconnect from an ODBC database ............................................................... 25

Connect to and disconnect from a non-mainframe DB2 database ................................ 27 Connect to a non-mainframe DB2 database ..................................................... 27 Disconnect from a non-mainframe DB2 database .............................................. 28

Connect to and disconnect from an Oracle database ............................................... 30 Connect to an Oracle database .................................................................... 30 Disconnect from an Oracle database ............................................................. 31

Connect to or disconnect from a SUPRA database .................................................. 32 Connect to a SUPRA database ...................................................................... 32 Disconnect from a SUPRA database ............................................................... 33

Connect to or disconnect from an Oracle Rdb database ........................................... 34


Connect to an Oracle Rdb database ............................................................... 34 Disconnect from an Oracle Rdb database ........................................................ 35

5. Embedding SQL statements in MANTIS programs .............................. 36

Introduction to embedding SQL statements in a MANTIS program................................ 36 Rules for embedding SQL statements in a MANTIS program ....................................... 37

Follow the standard SQL syntax rules ............................................................. 37 Embed an SQL statement as a standard MANTIS comment ................................... 37 Follow the standard MANTIS comment rules .................................................... 37 Place an SQL statement within an EXEC_SQL-END block ...................................... 37 Place only one SQL statement within an EXEC_SQL-END block .............................. 37 Apart from the SQL statement, do not include any other MANTIS statements in an EXEC_SQL-END block .............................................................................................. 38 Do not place a comment or a MANTIS statement on the same line as an SQL statement38 Within an EXEC_SQL-END block, use a colon to represent a host variable (the colon will not represent a new statement) ........................................................................ 39 If desired, split an SQL statement across multiple comment lines within an EXEC_SQL-END block........................................................................................................... 39 In an SQL statement, use as many spaces as desired .......................................... 39 If you use a colon to attach an SQL statement to an EXEC_SQL statement, that SQL statement exists within the EXEC_SQL-END block ........................................................... 40 If you place a MANTIS statement on the same line as the END in an EXEC_SQL-END block, MANTIS does not execute that statement ........................................................ 40 A MANTIS comment is permitted to be on the same line as the END in an EXEC_SQL-END block........................................................................................................... 40

Host variables .............................................................................................. 41 Introduction to host variables ...................................................................... 41 Declare host variables ............................................................................... 41 Types of host variables .............................................................................. 41 Input host variables .................................................................................. 42 Output host variables ................................................................................ 42 Host variables as parameters of SQL statements ............................................... 43 Use host variables to reference MANTIS array values .......................................... 43 (Oracle only) Oracle array-processing support .................................................. 43 MANTIS data types vs. SQL data types ............................................................ 43

Indicator variables ........................................................................................ 45 Introduction to indicator variables ................................................................ 45 Declare indicator variables ......................................................................... 45 With SELECT or FETCH, use indicator variable for columns with possible NULL values . 46

6. Data conversion between MANTIS SQL Support and supported databases47

Data conversion between MANTIS SQL Support and ODBC databases ............................ 47 Data conversion between MANTIS SQL Support and DB2 databases .............................. 48 Data conversion between MANTIS SQL Support and Oracle database ............................ 49 Data conversion between MANTIS SQL Support and SUPRA databases ........................... 50 Data conversion between MANTIS SQL support and Oracle Rdb databases ..................... 51

7. Programming considerations for SQL ............................................ 52

Introduction to SQL programming considerations ................................................... 52 MANTIS SQL Support and SQL statements ............................................................. 53

How MANTIS SQL Support processes SQL statements .......................................... 53 SQL statements and cursors as SQL entities ..................................................... 53


Varying line numbers associated with an EXEC_SQL-END block ................................... 54 Introduction to varying line numbers associated with an EXEC_SQL-END block........... 54 Line number associated with an EXEC_SQL-END block in an unbound program ........... 54 Line number associated with an EXEC_SQL-END block in a bound program ............... 54

Scope of cursors, statements, and SQLDA data structures ......................................... 56 Scope of cursors, statements, and SQLDA data structures under ODBC and SUPRA ...... 56 Scope of cursors, statements, and SQLDA data structures under DB2, Oracle, and Oracle Rdb........................................................................................................... 56

Using the MANTIS EXEC_SQL statement for multiple-session support ............................ 58 SQL WHENEVER statement ............................................................................... 60

Differences between WHENEVER statement in MANTIS SQL Support and WHENEVER statement in SQL in COBOL.......................................................................................... 60 Syntax for MANTIS SQL Support WHENEVER statement ........................................ 60 Quick reference for WHENEVER conditions and default actions ............................. 63 Sample code for DO, FAULT, and CONTINUE .................................................... 63 Declarative (COBOL) vs. interpretive (MANTIS) WHENEVER statements .................... 63

SQL FINISH statement (ODBC and SUPRA only) ....................................................... 65 SQL SET DBNAME statement (ODBC, SUPRA, and Oracle only) .................................... 66 SQLCA function and SQLCA statement ................................................................. 67

SQLCA in SQL in COBOL vs. SQLCA in MANTIS SQL Support.................................... 67 SQLCA syntax .......................................................................................... 67 SQLCA elements ...................................................................................... 68 Additional MANTIS SQL Support elements for the SQLCA statement ........................ 70

COMMIT/ROLLBACK in SQL and COMMIT/RESET in MANTIS SQL Support ......................... 72 For DB2, don't use the RELEASE parameter for COMMIT/ROLLBACK ........................ 72 Database and COMMIT ............................................................................... 72 COMMIT/ROLLBACK vs. COMMIT/RESET .......................................................... 72 Scope of an SQL COMMIT statement .............................................................. 72 COMMIT and terminal input ......................................................................... 72 COMMIT/RESET and SQL cursor position .......................................................... 72 When MANTIS COMMIT executes ................................................................... 72 When MANTIS RESET executes ..................................................................... 73 Be careful of a terminal input request by Program Design ................................... 73 Be careful of COMMIT/RESET ....................................................................... 73 ROLLBACK on failed COMMIT (Oracle and DB2 only) ........................................... 73 Notes specific to Oracle Rdb ....................................................................... 73

SQL-related error messages ............................................................................. 74 Message sources ...................................................................................... 74 Information that MANTIS generally displays for an error ...................................... 74 Information that MANTIS displays for an error from the database system ................. 74

8. Dynamic SQL in MANTIS SQL Support ............................................ 75

Who should read this chapter? .......................................................................... 75 Dynamic SQL overview.................................................................................... 76

Dynamic SQL definition .............................................................................. 76 Principal statements for dynamically executing SQL statements ............................ 76 SQLDA data structure ................................................................................ 76 Defining data about SQL statements and host variables ...................................... 76 SQL statements that you cannot execute dynamically (DB2, Oracle, and Oracle Rdb only)........................................................................................................... 77 Auto-cursor FETCH statements (DB2, Oracle, and Oracle Rdb only) ........................ 78 Executing a statement dynamically ............................................................... 78 Dynamic SQL sample code for creating an SQLDA data structure ........................... 78

SQLDA data structure ..................................................................................... 81


Introduction to the SQLDA data structure ....................................................... 81 Allocate an SQLDA data structure ................................................................. 83 Deallocate an SQLDA data structure .............................................................. 84 Move data from your program into an SQLDA header element ............................... 85 Move data from your program into an SQLDA repeating element ........................... 89 SQLDA function syntax for moving data from an SQLDA header element into your program........................................................................................................... 96 Move data from an SQLDA repeating element into your program ........................... 97 Cursors for prepared statements (Oracle and DB2 only) .................................... 102

A. MANTIS SQL sample programs ................................................... 103

Introduction to the MANTIS SQL sample programs ................................................ 103 INSERT routines .......................................................................................... 104

Static INSERT routine .............................................................................. 104 Dynamic INSERT routine ........................................................................... 105

UPDATE routines ......................................................................................... 107 A static UPDATE routine ........................................................................... 107 Dynamic UPDATE routines ........................................................................ 107

SELECT routines .......................................................................................... 112 Static SELECT routine .............................................................................. 112 Dynamic SELECT routines ......................................................................... 113

DELETE routines ......................................................................................... 116 Static DELETE routine ............................................................................. 116 Dynamic DELETE routine .......................................................................... 116

Dynamic QUERY-like functions ........................................................................ 118 ODBC and SUPRA dynamic QUERY-like function .............................................. 118 DB2 dynamic QUERY-like function ............................................................... 120 Oracle dynamic QUERY-like function ........................................................... 121 Oracle Rdb dynamic QUERY-like function ...................................................... 124

Dynamic column SELECT routines .................................................................... 127 ODBC and SUPRA dynamic column SELECT routine ........................................... 127 DB2, Oracle, and Oracle Rdb dynamic column SELECT routine ............................ 128

B. Features of SQL not supported by MANTIS SQL Support ................... 130

Host variables cannot be specified in a SELECT list ............................................... 130 Exact syntax-error line number reference is not always supported ............................ 131 Using a single instruction, you cannot copy the contents of one SQLDA structure into another.............................................................................................................. 132 MANTIS programs with dynamic SQL statements are not portable to or from mainframe MANTIS.............................................................................................................. 133

C. Differences between MANTIS SQL Support and SQL in COBOL ........... 134

D. Differences between MANTIS and SQL ........................................ 136

Index .................................................................................... 137

SQL Programming Guide, P39-1381 8 Chapter: 1. Software requirements for MANTIS SQL Support Section: Software requirements for using MANTIS SQL Support with ODBC

1. Software requirements for MANTIS SQL Support Software requirements for using MANTIS SQL Support with ODBC

Operating systems on which the MANTIS Server supports ODBC For a list of operating systems on which ODBC is supported, refer to the Cincom Product Release Catalog PDF file. To access this PDF file, register with Cincom SupportWeb at the following URL:

http://supportweb.cincom.com

Special ODBC support consideration for a MANTIS Server on Android or iOS

The MANTIS Server, running on Android or iOS, can use a Cincom-provided, pre-built, ODBC-accessible SQLite database. This database is automatically available to the MANTIS Server and requires no installation or configuration. To access this database, use the generic MANTIS EXEC_SQL statement, which is documented in this guide.

SQLite is a public-domain, self-contained, server-less, zero-configuration, transactional SQL database engine. For more information on SQLite, see the following Web site:

www.sqlite.org

(See the External Web site disclaimer.)

Special ODBC support requirement for a MANTIS Server on Linux or UNIX

For a MANTIS Server running on any of the above operating systems, except for Linux and UNIX, the ODBC driver manager is available by default. However, for a MANTIS Server running on Linux or UNIX, this is not the case. On Linux and UNIX, for the MANTIS Server to use ODBC, a MANTIS Server administrator must specifically set up the appropriate ODBC driver manager: unixODBC. When unixODBC is set up as one of the running ODBC driver managers, MANTIS programs can use it to communicate with DBMS servers. You can download unixODBC from the following Web site:

www.unixodbc.org

(See the External Web site disclaimer.)

http://supportweb.cincom.com/

http://www.sqlite.org/

http://www.unixodbc.org/

SQL Programming Guide, P39-1381 9 Chapter: 1. Software requirements for MANTIS SQL Support Section: Software requirements for using MANTIS SQL Support with Common platform DB2

Software requirements for using MANTIS SQL Support with Common platform DB2

For a list of operating systems on which DB2 is supported, and a list of supported DB2 database versions, refer to the Cincom Product Release Catalog PDF file. To access this PDF file, register with Cincom SupportWeb at the following URL:


Before you run the MANTIS program, the MANTIS DB2 administrator must perform a binding process in order to store a MANTIS package in the database. Below is the required bind file information for the MANTIS DB2 administrator:

Name: db2_int.bnd Directory in which it's located: $MAN_ROOT/libdb2

Below is sample code for binding MANTIS against a DB2 sample database:

CD $MAN_ROOT/libdb2

DB2 CONNECT TO SAMPLE USER DB2INST1 USING IBMDB2

DB2 BIND DB2_INT.BND

For detailed information about the DB2 BIND command, refer to the Command Reference for DB2.


SQL Programming Guide, P39-1381 10 Chapter: 1. Software requirements for MANTIS SQL Support Section: Software requirements for using MANTIS SQL Support with Oracle

Software requirements for using MANTIS SQL Support with Oracle For a list of operating systems on which Oracle is supported, and a list of supported Oracle database versions, refer to the Cincom Product Release Catalog PDF file. To access this PDF file, register with Cincom SupportWeb at the following URL:


For MANTIS dynamic SQL Support, cursor names are not known at the time of the PREPARE, since MANTIS executes interpretively. MANTIS resolves this problem by declaring cursors for all prepared statements that could possibly require them. These statements include:

DECLARE Static SELECT Statements that are parameters to PREPARE


SQL Programming Guide, P39-1381 11 Chapter: 1. Software requirements for MANTIS SQL Support Section: Software requirements for using MANTIS SQL Support with Common platform SUPRA

Software requirements for using MANTIS SQL Support with Common platform SUPRA

For a list of operating systems on which SUPRA is supported, and a list of supported SUPRA database versions, refer to the Cincom Product Release Catalog PDF file. To access this PDF file, register with Cincom SupportWeb at the following URL:



SQL Programming Guide, P39-1381 12 Chapter: 1. Software requirements for MANTIS SQL Support Section: Software requirements for using MANTIS SQL Support with Oracle Rdb

Software requirements for using MANTIS SQL Support with Oracle Rdb For a list of operating systems on which SUPRA is supported, and a list of supported SUPRA database versions, refer to the Cincom Product Release Catalog PDF file. To access this PDF file, register with Cincom SupportWeb at the following URL:



SQL Programming Guide, P39-1381 13 Chapter: 2. MANTIS SQL Support overview Section: Introduction to MANTIS SQL Support

2. MANTIS SQL Support overview Introduction to MANTIS SQL Support

MANTIS is an application development system that enables you to interactively perform the following for applications:

Develop Test Execute Document

MANTIS SQL Support, an extended version of MANTIS, enables you to create MANTIS applications that use SQL to access database systems.

SQL Programming Guide, P39-1381 14 Chapter: 2. MANTIS SQL Support overview Section: MANTIS SQL Support and non-SQL MANTIS applications

MANTIS SQL Support and non-SQL MANTIS applications The presence of MANTIS SQL Support doesn't affect non-SQL MANTIS applications. Therefore, MANTIS SQL Support programs can run concurrently with, or in conjunction with, non-SQL MANTIS programs, without them affecting each other.

SQL Programming Guide, P39-1381 15 Chapter: 2. MANTIS SQL Support overview Section: Embedding SQL statements in a MANTIS application program

Embedding SQL statements in a MANTIS application program Embed SQL statements in a MANTIS application program as standard MANTIS comments. To embed an SQL statement, perform the following:

Using the appropriate editor, open a MANTIS application program to which you would like to add an embedded SQL statement.

On a new line, enter an EXEC_SQL statement. On the next line, enter a desired SQL statement.

Although you can enter only one SQL statement in an EXEC_SQL-END block, you can split this statement across multiple lines. Begin each line of your SQL statement with the comment character: a vertical bar (|).

On the next line, enter an END statement.

The appearance of a MANTIS program with embedded SQL statements is similar to the appearance of the preprocessor output for SQL statements embedded in other host languages, such as COBOL.

See the following sample code for an embedded SQL statement:

TEXT EMP_NAME(30)

BIG EMP_SAL

EXEC_SQL

| SELECT SALARY

| INTO :EMPL_SAL

| FROM EMPLOYEE_TABLE

| WHERE NAME=:EMP_NAME

END

DO BONUS_ROUTINE

As MANTIS SQL Support encounters each SQL statement in a MANTIS program, MANTIS SQL Support performs the following:

Transparently prepares the SQL statement for execution. Executes the SQL statement.

MANTIS variables in SQL statements are called host variables. Syntactically, a colon always precedes a host variable in an SQL statement. For more information on Host variables, see the section titled Host variables.

SQL Programming Guide, P39-1381 16 Chapter: 2. MANTIS SQL Support overview Section: Variables in MANTIS SQL Support

Variables in MANTIS SQL Support See the following sections:

Host variables. Each host variable is preceded by a colon. "Input host variables" pass data to SQL. "Output host variables" receive data from the database. Host variables are also used as parameters of SQL statements.

Indicator variables. An "indicator variable" is optionally specified along with a host variable. The database sets the indicator variable to indicate a null value or to signal that a value was truncated.

SQL Programming Guide, P39-1381 17 Chapter: 2. MANTIS SQL Support overview Section: Differences between SQL in MANTIS and SQL in COBOL

Differences between SQL in MANTIS and SQL in COBOL The SQL implementation in MANTIS SQL Support is similar to the SQL implementations in third-generation languages like FORTRAN and COBOL.

For convenience, this manual refers to all third-generation SQL implementations as "SQL in COBOL."

There are differences between MANTIS SQL Support and SQL in COBOL. These differences are mostly due to the interpretive (as opposed to compiled) nature of the MANTIS language. For a summary of these differences, see the appendix titled Differences between MANTIS SQL Support and SQL in COBOL.

SQL Programming Guide, P39-1381 18 Chapter: 2. MANTIS SQL Support overview Section: Logical names

Logical names In this guide, the term "logical name" refers to an identifier or variable that stands for another name or value. Logical-name implementation depends on the operating system:

For the MANTIS Server on all supported Common platform operating systems except OpenVMS. Logical names are implemented as environment variables. You must ensure that any shell variables that you want to affect MANTIS are exported or inherited into the environment in which the MANTIS Server is executing.

For the MANTIS Server on OpenVMS. The logical names used by MANTIS correspond directly to OpenVMS logical names.

SQL Programming Guide, P39-1381 19 Chapter: 2. MANTIS SQL Support overview Section: Static and dynamic SQL

Static and dynamic SQL A MANTIS SQL Support application can be either of the following:

Static. All SQL statements are defined before run-time. Dynamic. All SQL statements are defined at run-time. That is, SQL statements are

specified during program execution.

SQL Programming Guide, P39-1381 20 Chapter: 2. MANTIS SQL Support overview Section: Security in MANTIS SQL support

Security in MANTIS SQL support Together, the database system and the MANTIS Server handle security in MANTIS SQL Support. Ensure that users have authorized access to the views that they require.

SQL Programming Guide, P39-1381 21 Chapter: 3. System maintenance for MANTIS SQL Support Section: Introduction to system maintenance for MANTIS SQL Support

3. System maintenance for MANTIS SQL Support Introduction to system maintenance for MANTIS SQL Support

The considerations in this chapter assume that you've installed the MANTIS Server. If you're installing the MANTIS Server or MANTIS SQL Support, refer to the following:

MANTIS Administration, P39-1321 MANTIS Server Installation and Startup for Windows, OS X, Linux, and UNIX, P39-

1316 MANTIS Server Installation and Startup for OpenVMS, P39-1305

This chapter supplements those publications. As the MASTER User, you alone have access to certain facilities and information related to MANTIS Server configuration.

SQL Programming Guide, P39-1381 22 Chapter: 3. System maintenance for MANTIS SQL Support Section: Connect to a database

Connect to a database

Connect to an ODBC database If you're using an ODBC database, a MANTIS application must establish a connection to an ODBC data source through an SQL CONNECT statement before issuing other SQL query statements. For more information and an example, see Explicitly connect to an ODBC data source.

Connect to a Common platform DB2 database If you're using a DB2 database, you can connect to the database either explicitly, using an SQL CONNECT statement, or implicitly. For more information, see Explicitly or implicitly connect to a Common platform DB2 database. For examples, see the following:

Explicitly connect to a DB2 server using all default values Explicitly connect to a DB2 server named SAMPLE Explicitly connect to a DB2 server using MANTIS variables for user name and

password

Connect to an Oracle database If you're using an Oracle database, you can connect to the database either explicitly, using an SQL CONNECT statement, or implicitly. For more information, see the following:

Explicitly or implicitly connect to an Oracle database Connection to an Oracle database and multiple-session support

Connect to a SUPRA database If you're using a SUPRA database, you can connect to the database either explicitly, using an SQL CONNECT statement, or implicitly. For more information, see the following:

Explicitly or implicitly connect to a SUPRA database OpenVMS connection consideration for SUPRA Connection to the SUPRA database and multiple session support

Connect to an Oracle Rdb database on OpenVMS If you're using an Oracle Rdb database on OpenVMS, you can connect to the database either explicitly, using an SQL CONNECT statement, or implicitly. For more information, see the following:

Automatically connect to the Oracle Rdb database identified by SQL$DATABASE Define MANTIS logical MANTIS_RDI_IF to connect to an Oracle Rdb database

SQL Programming Guide, P39-1381 23 Chapter: 3. System maintenance for MANTIS SQL Support Section: MANTIS SQL options

MANTIS SQL options Two MANTIS options affect SQL support:

SQLSSNINC SQLVARINC

For information on these options, refer to MANTIS Facilities, P39-1301.

SQL Programming Guide, P39-1381 24 Chapter: 3. System maintenance for MANTIS SQL Support Section: Update the MANTIS User profile with the default SQL DBTYPE

Update the MANTIS User profile with the default SQL DBTYPE As needed, for each MANTIS User Profile, specify the default SQL DBTYPE in the User profile's Default SQL DBTYPE field. In this field, specify one of the following SQL DBTYPEs:

DB2 ODBC ORACLE RDB SUPRA

When the user signs on to MANTIS, the default DBTYPE sets the user's current SQL DBTYPE. The current DBTYPE always determines which SQL database system is used by the MANTIS Server. At any time, the following MANTIS statements can change the current DBTYPE:

EXEC_SQL SQLCA

Not all DBTYPEs are supported on all operating systems. For example:

Oracle Rdb runs only on the OpenVMS operating system. DB2 (for Common platform systems) runs only on the AIX operating system.

SQL Programming Guide, P39-1381 25 Chapter: 4. Connect to and disconnect from a database Section: Connect to and disconnect from an ODBC database

4. Connect to and disconnect from a database Connect to and disconnect from an ODBC database

Explicitly connect to an ODBC data source In Windows, use the Control Panel's Administrative Tools item to create the ODBC data source. A MANTIS application must establish a connection to an ODBC data source through a SQL CONNECT statement before issuing other SQL query statements.

For more on the host variables that you can use in a CONNECT statement, see Using host variables.

The following example connects to an ODBC data source with name SAMPLE, user-name USR1, and password USR:

SQLCA("DBTYPE")="ODBC"

EXEC_SQL

| CONNECT TO SAMPLE USER USR1 USING USR

END

Disconnect from an ODBC database

Explicitly or implicitly disconnect from an ODBC database

MANTIS disconnects from the Oracle database by executing the SQL COMMIT WORK RELEASE statement. MANTIS can execute the COMMIT WORK RELEASE statement in either of the following ways:

Explicitly. Performed by a MANTIS program. The format for this statement is: EXEC_SQL:| COMMIT [WORK] RELEASE

Implicitly. Performed by the MANTIS nucleus.

For more possible causes of disconnection, see Possible causes of disconnection from an ODBC database.

Possible causes of disconnection from an ODBC database

Possible causes of disconnection are:

A MANTIS program executes an SQL COMMIT WORK RELEASE statement. For example: EXEC_SQL:| COMMIT [WORK] RELEASE

A MANTIS program executes an SQL FINISH statement. For example: EXEC_SQL:| FINISH

MANTIS main program context cleanup. This occurs in the following circumstances:

SQL Programming Guide, P39-1381 26 Chapter: 4. Connect to and disconnect from a database Section: Connect to and disconnect from an ODBC database

- The MANTIS nucleus releases the current TEST program context in Program Design as the result of a NEW, LOAD, EDIT, or RUN command.

- The user exits the Program Design Facility. - A main program terminates in RUN mode; that is, when the program's not under

Program Design's control. A MANTIS program executes a MANTIS CHAIN statement. Disconnection occurs

only if the MANTIS option for database sign-off on a CHAIN statement is enabled. In MANTIS Facilities, P39-1301, see the description of the SIGNOFFCHAIN/NOSIGNOFFCHAIN option.

SQL Programming Guide, P39-1381 27 Chapter: 4. Connect to and disconnect from a database Section: Connect to and disconnect from a non-mainframe DB2 database

Connect to and disconnect from a non-mainframe DB2 database

Connect to a non-mainframe DB2 database

Explicitly or implicitly connect to a Common platform DB2 database

You can connect to a DB2 database in either of the following ways:

Explicitly. Do this through the SQL CONNECT statement:

Implicitly. Occurs when there is no CONNECT statement and the first SQL

statement is executed. The MANTIS Server on all supported operating systems except OpenVMS supports the implicit sign-on facility provided by DB2.

MANTIS supports the DB2 type 1 database connection.

For more information on the DB2 type 1 database connection, refer to the SQL Reference DB2 manual.

Consider the following for a MANTIS connection to DB2:

One concurrent connection. MANTIS program can only connect to one DB2 application server at a time.

"DB2 implicit connect" and implicit connection. If a "DB2 implicit connect" is available, the MANTIS program implicitly connects to the default DB2 application server.

Explicit connection. A MANTIS program can explicitly connect to a server that is different from the currently connected DB2 server.

Examples of explicit connection to a non-mainframe DB2 database

Explicitly connect to a Common platform DB2 server using all default values In this example, you connect to the DB2 server using default values for the following:

Server Username Password

See the following sample code:

EXEC_SQL

| CONNECT

END


Explicitly connect to a Common platform DB2 server named SAMPLE In this example, you connect to the DB2 server named SAMPLE using default values for the following:

Username Password


EXEC_SQL

| CONNECT TO SAMPLE

END

Explicitly connect to a DB2 server using MANTIS variables for user name and password In this example, you connect to the default DB2 server using MANTIS variables for the following:

User name Password


EXEC_SQL

| CONNECT USER :AIXUSER USING :PASSWORD

END

Disconnect from a non-mainframe DB2 database

Explicitly or implicitly disconnect from a Common platform DB2 database

MANTIS detaches from the DB2 database by executing the SQL CONNECT RESET statement. MANTIS can execute the CONNECT RESET statement in either of the following ways:

Explicitly. Performed by a MANTIS program. The format for this statement is: EXEC_SQL: | CONNECT RESET END


For more possible causes of disconnection, see Possible causes of disconnection from a DB2 database.

Possible causes of disconnection from a Common platform DB2 database


A MANTIS program executes an SQL CONNECT RESET statement. The format for this statement is: EXEC_SQL: | CONNECT RESET END

MANTIS main program context cleanup. This occurs in the following circumstances: - The MANTIS nucleus releases the current TEST program context in Program

Design as the result of a NEW, LOAD, EDIT, or RUN command. - The user exits the Program Design Facility.


- A main program terminates in RUN mode; that is, when that main program is not under Program Design's control.

A MANTIS program executes a MANTIS CHAIN statement. Disconnection occurs only if the MANTIS option for database sign-off on a CHAIN statement is enabled. In MANTIS Facilities, P39-1301, see the description of the SIGNOFFCHAIN/NOSIGNOFFCHAIN option.

A CONNECT TO statement changes the DB2 application server that is connected to the MANTIS program.

SQL Programming Guide, P39-1381 30 Chapter: 4. Connect to and disconnect from a database Section: Connect to and disconnect from an Oracle database

Connect to and disconnect from an Oracle database

Connect to an Oracle database

Explicitly or implicitly connect to an Oracle database

You can connect to an Oracle database in either of the following ways:


Implicitly. Occurs when there is no CONNECT statement and the first SQL

statement is executed. The MANTIS Server supports four logical names that provide information for the implicit sign-on. The four logical names are: - For the MANTIS Server on all supported operating systems except OpenVMS:

o MANTIS_SQL_USER = "SQL-user-name" o MANTIS_SQL_PASS = "SQL-user-password" o MANTIS_SQL_DBNAME = "SQL-data-base-name" o ORACLE_DRIVER = "Oracle-driver-name"

- For the MANTIS Server on OpenVMS: o DEFINE MANTIS_SQL_USER = "SQL-user-name" o DEFINE MANTIS_SQL_PASS = "SQL-user-password" o DEFINE MANTIS_SQL_DBNAME = "SQL-data-base-name" o DEFINE ORACLE_DRIVER = "Oracle-driver-name"

If the MANTIS_SQL_* logical names don't cause a successful CONNECT, then the native implicit CONNECT is attempted. If there are no logical names, MANTIS doesn't connect to Oracle and issues a fault message. You might want to use SQLCA ("SQLCODE") to find the failure's cause.

Connection to an Oracle database and multiple-session support

Multiple-session support is a feature that enables you to connect up to five Oracle databases concurrently. In your MANTIS program, you can specify the name of the Oracle database in one of the following ways:

Using an SQLCA statement. For example: SQLCA("DBNAME")= "ORACLE"

See the section titled SQLCA function and SQLCA statement.

Using an EXEC_SQL statement. For example: EXEC_SQL("ORACLE" [, session-no]

See Using the MANTIS EXEC_SQL statement for multiple-session support.

MANTIS uses the specified DBNAME on the next implicit or explicit database connection. Having specified the database name, you can then specify the Oracle session number that's associated with a database connection. You can specify the session number only on an EXEC_SQL statement.

SQL Programming Guide, P39-1381 31 Chapter: 4. Connect to and disconnect from a database Section: Connect to and disconnect from an Oracle database

Disconnect from an Oracle database

Explicitly or implicitly disconnect from an Oracle database

MANTIS detaches from the Oracle database by executing the SQL COMMIT WORK RELEASE statement. MANTIS can execute the COMMIT WORK RELEASE statement in two ways:

Explicitly. Performed by a MANTIS program. The format for this statement is: EXEC_SQL: | CONNECT [WORK] RELEASE


For more possible causes of disconnection, see Possible causes of disconnection from an Oracle database.

Possible causes of disconnection from an Oracle database


A MANTIS program executes an SQL COMMIT WORK RELEASE statement. The format for this statement is:

For example:

EXEC_SQL: | COMMIT [ WORK ] RELEASE

The RELEASE parameter is a request to disconnect from the database upon successful completion of the COMMIT or ROLLBACK.


Design as the result of a NEW, LOAD, EDIT, or RUN command. - The user exits the Program Design Facility. - A main program terminates in RUN mode; that is, when that main program is

not under Program Design's control. A MANTIS program executes a MANTIS CHAIN statement. Disconnection occurs


SQL Programming Guide, P39-1381 32 Chapter: 4. Connect to and disconnect from a database Section: Connect to or disconnect from a SUPRA database

Connect to or disconnect from a SUPRA database

Connect to a SUPRA database

Explicitly or implicitly connect to a SUPRA database

You can connect to a SUPRA DRDM in either of the following ways:


If the SUPRA session is already connected when an SQL CONNECT is issued, MANTIS performs an implicit COMMIT WORK RELEASE before reconnecting. For more information on using the SQL CONNECT statement, refer to your SUPRA Server documentation.

Implicitly. Occurs when there is no CONNECT statement and the first SQL statement is executed. The MANTIS Server supports three logical names that provide information for the implicit sign-on. The three logical names are: - MANTIS_SQL_USER = "SQL-user-name" - MANTIS_SQL_PASS = "SQL-user-password" - MANTIS_SQL_DBNAME = "SQL-data-base-name"

If the MANTIS_SQL_* logical names don't cause a successful CONNECT, then the native implicit CONNECT is attempted using the associated RVX logical names). If there are no logical names, MANTIS doesn't connect to the SUPRA DRDM and issues a fault message. You might want to use SQLCA("SQLCODE") to find the failure's cause.

OpenVMS connection consideration for SUPRA

The MANTIS logical name MANTIS_SUP_IF must be defined in order for the MANTIS Server to connect to the SUPRA SQL database. This logical name is defined in the MANTIS_CLASS_XXXX_INIT.COM procedure, in which XXXX is the class name.

Connection to the SUPRA database and multiple session support

Multiple-session support is a feature that enables you to connect up to eight SUPRA databases concurrently. In your MANTIS program, you can specify the name of the SUPRA database in one of the following ways:

Using an SQLCA statement. For example: SQLCA("DBNAME")="SUPRA"

See SQLCA function and SQLCA statement.

Using an SQL SET DBNAME statement. For example: EXEC_SQL:| SET DBNAME dbname-spec

See SQL SET DBNAME statement.

Using a MANTIS EXEC_SQL statement. For example: EXEC_SQL ("SUPRA" [, session-no])

See Using the MANTIS EXEC_SQL statement for multiple-session support.

SQL Programming Guide, P39-1381 33 Chapter: 4. Connect to and disconnect from a database Section: Connect to or disconnect from a SUPRA database

MANTIS uses the specified DBNAME on the next implicit or explicit database connection. Having specified the database name, you can then specify the SUPRA session number that's associated with a database connection. You can specify the session number only on an EXEC_SQL statement.

Disconnect from a SUPRA database

Explicitly or implicitly disconnect from a SUPRA database

MANTIS detaches from the Oracle database by executing the SQL COMMIT WORK RELEASE statement. MANTIS can execute the COMMIT WORK RELEASE statement in two ways:

Explicitly. Performed by a MANTIS program. Implicitly. Performed by the MANTIS nucleus.

For more on possible causes of disconnection, see Possible causes of disconnection from a SUPRA database.

Possible causes of disconnection from a SUPRA database



For example:



A MANTIS program executes a SQL FINISH statement. For example: EXEC_SQL:| FINISH





SQL Programming Guide, P39-1381 34 Chapter: 4. Connect to and disconnect from a database Section: Connect to or disconnect from an Oracle Rdb database

Connect to or disconnect from an Oracle Rdb database

Connect to an Oracle Rdb database

Automatically connect to the Oracle Rdb database identified by SQL$DATABASE

The MANTIS RDI interface performs automatic attachment to the Oracle Rdb database identified by the logical name SQL$DATABASE. This method of attachment is the same as that used by third generation language programs (such as FORTRAN or COBOL) that are processed by the RDB precompilers.

MANTIS doesn't support explicit database connection by any embedded SQL statement such as the SUPRA CONNECT statement. However, MANTIS supports setting of the logical name SQL$DATABASE in the following ways:

SQLCA("DBNAME")="RDB" (see SQLCA syntax) EXEC_SQL: | SET DBNAME dbname-spec The MANTIS SET $LOGICAL statement EXEC_SQL("RDB")

The new value of SQL$DATABASE is set in the PROCESS logical name table in USER mode.

Define MANTIS logical MANTIS_RDI_IF to connect to an Oracle Rdb database

The MANTIS logical MANTIS_RDI_IF must be defined in order to connect to the RDB SQL database. This logical is defined in the following procedure, in which XXXX is the class name:

MANTIS_CLASS_XXXX_INIT.COM

MANTIS interface to Rdb

MANTIS interfaces to Oracle Rdb via a dynamically loaded shareable image. This image is identified by the logical name MANTIS_RDI_IF, and it's referred to as the RDI interface. This interface imposes certain limitations and restrictions on the Rdb support in MANTIS. The primary limitation is that MANTIS executes all embedded SQL statements dynamically, and MANTIS dynamic SQL support is merely another layer over its underlying use of dynamic SQL.

Another limitation involves the relationship between embedded SQL statements and cursor names. MANTIS must PREPARE all embedded SQL statements before executing them. The RDI interface requires that when a statement is prepared, the cursor name associated with that statement must also be nominated on the same call.

However, for MANTIS dynamic SQL support, cursor names are not known at the time of the PREPARE (since MANTIS executes interpretively). MANTIS resolves this problem by declaring cursors for all prepared statements that could possibly require them. These statements include:


SQL Programming Guide, P39-1381 35 Chapter: 4. Connect to and disconnect from a database Section: Connect to or disconnect from an Oracle Rdb database

In this manual, the term "real cursor" is used to refer to cursors declared internally by MANTIS, to distinguish them from cursor names declared in a MANTIS program. When a real cursor is created for a non-SELECT dynamic statement, it is (effectively) a wasted resource.

The RDI interface supplied on the MANTIS release tape supports up to 100 cursors with no limit on the number of statements.

Disconnect from an Oracle Rdb database

Explicitly or implicitly disconnect from an Oracle Rdb database

MANTIS detaches from the Oracle Rdb database by executing the SQL FINISH statement. This can be performed explicitly by a MANTIS program, or implicitly by the MANTIS Nucleus.

Possible causes of disconnection from an Oracle Rdb database



For example:



A MANTIS program executes a SQL FINISH statement. For example: EXEC_SQL:| FINISH





SQL Programming Guide, P39-1381 36 Chapter: 5. Embedding SQL statements in MANTIS programs Section: Introduction to embedding SQL statements in a MANTIS program

5. Embedding SQL statements in MANTIS programs Introduction to embedding SQL statements in a MANTIS program

This chapter describes:

Rules you must follow when embedding SQL statements in a MANTIS program How to use host variables How to use indicator variables

A general working knowledge of the following is assumed:

MANTIS programming language. For more information on MANTIS language conventions, refer to MANTIS Language, P39-1311.

Your database system. SQL. For details, refer to the appropriate guide in your database system's

documentation set.

SQL Programming Guide, P39-1381 37 Chapter: 5. Embedding SQL statements in MANTIS programs Section: Rules for embedding SQL statements in a MANTIS program

Rules for embedding SQL statements in a MANTIS program

Follow the standard SQL syntax rules Follow the standard SQL syntax rules for SQL statements embedded within a MANTIS program. For details, refer to the appropriate guide for your database.

Embed an SQL statement as a standard MANTIS comment Embed an SQL statement in a MANTIS application program as a standard MANTIS comment. That is, precede the SQL statement with a vertical bar (|).

Follow the standard MANTIS comment rules For SQL statements embedded within a MANTIS program, follow the MANTIS comment rules. To find these rules, refer to MANTIS Language, P39-1311.

Place an SQL statement within an EXEC_SQL-END block Place an SQL statement within an EXEC_SQL-END block.

Statements within the EXEC_SQL-END block are indented.

See the following valid sample code:

EXEC_SQL

| OPEN C1

END

Place only one SQL statement within an EXEC_SQL-END block Place only one SQL statement within an EXEC_SQL-END block.

You can divide a single SQL statement across several lines.

The following sample code is valid because it contains a single SQL statement that is divided across several lines:

EXEC_SQL

| SELECT SALARY

| INTO :EMPL_SAL



END

(Invalid code) See the following invalid sample code. It's invalid because the EXEC_SQL-END block contains three separate SQL statements, and only one is permitted:

EXEC_SQL Invalid: Three SQL statements

| OPEN C1 in the EXEC_SQL-END block.

| FETCH C1 INTO ...

| CLOSE C1

END


Apart from the SQL statement, do not include any other MANTIS statements in an EXEC_SQL-END block

Apart from the SQL statement, don't include any other MANTIS statements or comments in an EXEC_SQL-END block. MANTIS SQL Support permits only the SQL statement within the SQL statement's EXEC_SQL-END block.

Any text between EXEC_SQL and END must be part of an SQL statement and must be preceded by a vertical bar (|). Once MANTIS SQL Support encounters a vertical bar, the rest of the physical line is considered a single SQL statement, and other MANTIS statements or comments aren't permitted.

(Invalid code) See the following invalid sample code:

EXEC_SQL Invalid: A statement other than a

| OPEN C1 comment is between EXEC_SQL and

OPENED=TRUE END.

END


EXEC_SQL Invalid: A MANTIS statement is

| OPEN C1:OPENED=TRUE appended to a valid SQL statement.

END


EXEC_SQL Invalid: A comment is appended

| OPEN C1:|EMPLOYEE CURSOR to a valid SQL statement.

END

Do not place a comment or a MANTIS statement on the same line as an SQL statement

Don't place a comment or another MANTIS statement on the same line as an SQL statement. Once MANTIS SQL Support encounters a vertical bar, MANTIS SQL Support considers the rest of the physical line to be a single SQL statement.

The following sample code is invalid (shows what to avoid). See the following invalid sample code:

(Invalid code) In the following sample code, a MANTIS statement is appended to a valid SQL statement: EXEC_SQL

| OPEN C1:OPENED=TRUE

END

(Invalid code) In the following sample code, a MANTIS comment is appended t o a valid SQL statement: EXEC_SQL

| OPEN C1:|EMPLOYEE CURSOR

END


Within an EXEC_SQL-END block, use a colon to represent a host variable (the colon will not represent a new statement)

Use a colon within an EXEC_SQL-END block to represent a host variable. The colon doesn't represent a new statement, even though, outside of an EXEC_SQL-END block, the colon is the MANTIS statement-separator character. See the following sample code. In this code, "C1" is an SQL entity and "A" is a host variable:

EXEC_SQL

| FETCH C1 INTO :A C1 is an SQL entity;

END A is a MANTIS host variable

If desired, split an SQL statement across multiple comment lines within an EXEC_SQL-END block

If desired, you can split an SQL statement across multiple comment lines within an EXEC_SQL-END block. MANTIS reads the text in two or more consecutive comment lines, within the same EXEC_SQL-END block, as if it were separated by a single blank. That is, all of the text lines, together, compose one statement.

SQL text literals (characters between apostrophes) cannot span multiple comment lines.

The following two pieces of sample code are equivalent:

EXEC_SQL ...is equivalent to... EXEC_SQL

| OPEN | OPEN C1

| C1 END

END

In an SQL statement, use as many spaces as desired In an SQL statement, use as many spaces as desired. MANTIS SQL Support treats multiple blanks at the beginning or end of an SQL statement, or spaces between words on the same line, as a single blank. Consider the usage of spaces in the following sample code:

The following two pieces of sample code are equivalent: EXEC_SQL ...is equivalent to... EXEC_SQL

| OPEN C1 | OPEN C1

END END

The following two pieces of sample code are equivalent because multiple spaces between words are compressed: EXEC_SQL ...is equivalent to... EXEC_SQL

| | OPEN C1

| OPEN END

| C1

|

END


If you use a colon to attach an SQL statement to an EXEC_SQL statement, that SQL statement exists within the EXEC_SQL-END block

If you use a colon (the MANTIS statement-separator character) to attach an SQL statement to an EXEC_SQL statement, that SQL statement exists within the EXEC_SQL-END lock. The SQL statement is considered to all or part of the single SQL statement that is allowed within the EXEC_SQL-END block.

Consider the following valid sample code, in which the first part of the SQL statement is attached to the EXEC_SQL statement and the second part of the SQL statement is within the EXEC_SQL-END block:

EXEC_SQL: | FETCH C1 ... Valid

| INTO :EMPL

END

See the following valid example:

EXEC_SQL:| SELECT ... Valid

| FROM

| WHERE

END

If you place a MANTIS statement on the same line as the END in an EXEC_SQL-END block, MANTIS does not execute that statement

If you place a MANTIS statement on the same line as the END in an EXEC_SQL-END block, MANTIS doesn't execute that statement. This is consistent with the way MANTIS treats a MANTIS statement added to an END in each of the following kinds of MANTIS block:

IF-END WHILE-END FOR-END WHEN-END UNTIL-END

See the following sample code, in which MANTIS disregards "OPENED=TRUE":

EXEC_SQL

| OPEN C1

END:OPENED=TRUE

A MANTIS comment is permitted to be on the same line as the END in an EXEC_SQL-END block

A MANTIS comment is permitted to be on the same line as the END in an EXEC_SQL-END block. Consider the following sample code, in which the comment is on the same line as the END:

EXEC_SQL

| OPEN C1

END :| C1 IDENTIFIES TAG FILE ENTRIES A valid comment

SQL Programming Guide, P39-1381 41 Chapter: 5. Embedding SQL statements in MANTIS programs Section: Host variables

Host variables

Introduction to host variables A "host variable" is a MANTIS variable, in a SQL statement, that's used to provide input to, or receive output from, the connected database. A host variable is identified within an SQL statement by a colon prefix. In the following example, EMPL is a host (MANTIS) variable.

SMALL EMPL

EXEC_SQL

| FETCH CURSOR1 INTO :EMPL

END

See the following sample code, in which "SALARY" is a host variable:

EXEC_SQL

| INSERT INTO OWNER.TAB (COLA)

| VALUES (:SALARY * 1.1)

END

Declare host variables You can declare a variable in either of the following ways:

Explicitly. You can explicitly declare a host variable before it appears in the SQL statement, and you can declare this variable to be any type.

If necessary, you can explicitly declare a host variable as a type other than BIG, which is the type used for implicit declaration.

Implicitly. If you don't explicitly declare a host variable, MANTIS implicitly declares the host variable the first time MANTIS uses it, just as MANTIS does with other MANTIS variables. MANTIS automatically declares an implicitly defined host variable, referenced in an SQL statement, as a MANTIS BIG variable.

A MANTIS BIG variable is a numeric floating-point variable that is 16 digits long.

See the following sample code for explicit and implicit declaration. The two pieces of sample code are equivalent:

Explicit declaration. See the following sample code: BIG A

EXEC_SQL

| FETCH C1 INTO :A

END

Implicit declaration. See the following sample code: EXEC_SQL

|FETCH C1 INTO :A

END

Types of host variables There are three kinds of host variables:

Input host variables


Output host variables Host variables as parameters of SQL statements

In addition, you can include an indicator variable along with a host variable in an SQL statement.

Input host variables An input host variable is a MANTIS variable that is:

Passed to SQL Used to perform one of the following:

- Select data - Insert data - Delete data - Update data

The "input" in "input host variable" is from the perspective of the database, not the MANTIS program. Therefore, the input host variable provides output from the MANTIS program and input to the database.

In the following sample code, ":EMP_NAME" is an input host variable:

TEXT EMP_NAME(30)

BIG EMP_SAL

WHILE SQLCA("SQLCODE")<>1403

EXEC_SQL

| SELECT SALARY

| INTO :EMPL_SAL



END

END

DO BONUS_ROUTINE

Output host variables An output host variable is a MANTIS variable that receives data from a database. "Output" in "output host variable" is from the perspective of the database, not the MANTIS program. Therefore, the output host variable provides output from the DB2 database and input to the MANTIS program.

In the following sample code, ":EMPL_SAL" is an output host variable.

TEXT EMP_NAME(30)

BIG EMP_SAL


EXEC_SQL

| SELECT SALARY

| INTO :EMPL_SAL



END

END


DO BONUS_ROUTINE

Host variables as parameters of SQL statements You can use host variables as parameters of SQL statements. In the following sample code, ":EMP_NAME" is a parameter of an SQL statement:

TEXT EMP_NAME(30)

BIG EMP_SAL


EXEC_SQL

| SELECT SALARY

| INTO :EMPL_SAL



END

END

DO BONUS_ROUTINE

Use host variables to reference MANTIS array values You can use a host variable as an item in a MANTIS array. You can use arithmetic expressions and MANTIS functions to specify subscripts of host variables. In the sample code below, a subscript of a host variable refers to an item in a MANTIS array:

In the sample code below, all code following the colon must conform to MANTIS syntax. MANTIS rules apply to subscripting even though the subscript is located in an SQL statement.

You can prefix only the host variable with a colon. You cannot use a colon to prefix any of the other MANTIS variables to which you refer in subscript expressions. In the sample code below, a colon doesn't prefix the variables N and T, and these variables are assumed to be MANTIS variables.

SMALL EMPL (20,40)

EXEC_SQL

| FETCH ENTRY1 INTO :EMPL(1+N,INT(T))

END

(Oracle only) Oracle array-processing support MANTIS SQL Support for Oracle has been enhanced to support array processing. This enhancement enables one SQL statement to process multiple SQL rows. MANTIS numeric and text arrays can be used as Oracle SQL host variables. The FOR SQL keyword is supported to allow specification of the number of rows.

For more information, refer to the Oracle SQL Language Reference Manual.

MANTIS data types vs. SQL data types When the connected database system transfers data from one of its variables to a host variable, MANTIS causes the database system to automatically convert the data's type from an SQL type to a MANTIS type.


When MANTIS transfers data from one of its host variables to the connected database system, MANTIS causes the database to automatically convert the data's type from a MANTIS type to an SQL type.

For a summary describing how database systems convert to and from MANTIS data types, see one of the following topics:

Data conversion between MANTIS SQL Support and ODBC databases Data conversion between MANTIS SQL Support and DB2 databases Data conversion between MANTIS SQL Support and Oracle databases Data conversion between MANTIS SQL Support and SUPRA databases Data conversion between MANTIS SQL Support and Oracle Rdb databases

During data-type translation from a database variable to an SQL variable, any of the following problems can occur:

Rounding Truncation Overflow

SQL Programming Guide, P39-1381 45 Chapter: 5. Embedding SQL statements in MANTIS programs Section: Indicator variables

Indicator variables

Introduction to indicator variables Optionally, in SQL statements, you can include an indicator variable along with a host variable. As its name implies, the indicator variable indicates whether the host variable:

Contains a real value Is NULL or MISSING Contains a value that was truncated (this doesn't apply to Oracle Rdb databases)

Indicator variables are interpreted as follows:

Value Meaning

=0 The host variable is a defined value. No error has occurred.

<0 The host variable is a NULL or MISSING value.

>0 This contains the original column length due to a truncated value.

This doesn't apply to Oracle Rdb databases.

An indicator variable is prefixed with a colon and immediately follows the corresponding host variable (or subscript expression). In the following example, EMPLIV and NAMEIV are indicator variables.

EXEC_SQL:| SELECT EMPLNO, EMPLNA

| INTO :EMPL(15,3):EMPLIV, :NAME:NAMEIV

| FROM EMPLOYEES WHERE DEPT = 17

END

Declare indicator variables Like host variables, indicator variables can be declared in either of the following ways:

Explicitly. Consider the following: - When you explicitly define a variable, you can use only a numeric variable as

an indicator variable.

For descriptions of variable types, see one of the following topics:

Data conversion between MANTIS SQL Support and ODBC databases Data conversion between MANTIS SQL Support and DB2 databases Data conversion between MANTIS SQL Support and Oracle databases Data conversion between MANTIS SQL Support and SUPRA databases

- If you explicitly define an indicator variable as a floating-point value, the database still interprets it as an integer. Therefore, a value of -0.9 in an indicator variable doesn't specify a NULL or MISSING value (that is, a value that is less than zero). Instead, the value is converted to zero before it's interpreted.

Implicitly. By default, MANTIS defines the indicator variable as a MANTIS BIG variable.

SQL Programming Guide, P39-1381 46 Chapter: 5. Embedding SQL statements in MANTIS programs Section: Indicator variables

With SELECT or FETCH, use indicator variable for columns with possible NULL values

When you're using SELECT or FETCH to read data from the database, supply an indicator variable for each column that might contain a NULL value. Check the value of the indicator variable before examining the host variable data. If the indicator variable shows that the column is NULL, the value of the host variable is undefined.

SQL Programming Guide, P39-1381 47 Chapter: 6. Data conversion between MANTIS SQL Support and supported databases Section: Data conversion between MANTIS SQL Support and ODBC databases

6. Data conversion between MANTIS SQL Support and supported databases Data conversion between MANTIS SQL Support and ODBC databases

In MANTIS SQL Support, data is always manipulated as a MANTIS data type. When a data value is transferred between MANTIS and SQL, MANTIS causes the database system to automatically convert its data type to a MANTIS-compatible data type (if the host variable and the SQL variable are of compatible types). The following table lists permissible data conversions. Check the notes for information about overflow, truncation, and rounding. Any combination of MANTIS and SQL data types not listed in the following table will result in a run-time error. Truncation is indicated through the SQLWARN elements in the SQLCA and indicator variables, if used.

Numeric rounding and overflow conditions depend on the precision of the column specified in the table definition. While overflow is an ODBC ERROR condition, rounding may or may not be flagged as an ODBC WARNING condition, depending on the data types involved.

SQL Data Type

MANTIS Data Type

Possible Conditions, MANTIS to SQL

Possible Conditions, SQL to MANTIS

0 (Fixed) INTEGER Overflow Rounding, Overflow

SMALL Rounding, Overflow Rounding

BIG Rounding, Overflow Rounding

DECIMAL Rounding, Overflow Rounding, Overflow

1 (Float) INTEGER Rounding Rounding, Overflow

SMALL Rounding Rounding

BIG Rounding Rounding


2 (Character) TEXT Truncation Truncation

4 (Date) TEXT Truncation Truncation

5 (Time) TEXT Truncation Truncation

6 (String) TEXT Truncation Truncation

SQL Programming Guide, P39-1381 48 Chapter: 6. Data conversion between MANTIS SQL Support and supported databases Section: Data conversion between MANTIS SQL Support and DB2 databases

Data conversion between MANTIS SQL Support and DB2 databases DB2 performs data conversion between all data types (including between numeric and string data types). Be sure to match host variable data types with database columns so that you obtain correct results.

The following table shows valid data type conversions:

SQL Data Type

MANTIS Data Type(s)



Consideration

DECIMAL BIG, SMALL Overflow Loss of precision

INTEGER BIG, SMALL Overflow Loss of precision

SMALLINT BIG, SMALL Overflow

FLOAT BIG, SMALL When converting from an SQL FLOAT variable to a MANTIS SMALL variable, overflow and/or loss of precision may occur.

CHAR VARCHAR

TEXT Truncation Truncation The string can have a variable length, from 1 to 65535 characters.

DATE TEXT If TEXT size is less than 10, truncation may occur.

TIME TEXT If TEXT size is less than 8, truncation may occur.

TIMESTAMP TEXT If TEXT size is less than 26, truncation may occur.

SQL Programming Guide, P39-1381 49 Chapter: 6. Data conversion between MANTIS SQL Support and supported databases Section: Data conversion between MANTIS SQL Support and Oracle database

Data conversion between MANTIS SQL Support and Oracle database Oracle performs data conversion between all data types, including conversions between numeric and string data types. Be sure to match host variable data types with database columns so that correct results are obtained.

The following Oracle data types can be returned in the SQLDA data structure:

SQLTYPE Description

09 VARCHAR Variable-length string up to length 65535

01 CHAR Space-padded character string

04 NUMBER 4- or 8-byte floating point, depending on SQLLEN

03 NUMBER(38) 4-byte integer

03 NUMBER(38) 2-byte integer

12 DATE 7-byte field in Oracle internal date-time format

MANTIS data types can only be the following:

BIG DECIMAL INTEGER SMALL TEXT

Because of this limited selection of MANTIS data types, data-transfer between MANTIS host variables and database columns frequently involve conversions.

The following conversion error conditions apply:

For a conversion of a MANTIS string value to an ORACLE NUMBER: - The MANTIS string isn't a valid number in decimal or scientific E-notation. - The MANTIS string contains commas. - The magnitude of the converted MANTIS string is greater than the magnitude

supported by the target NUMBER(p). MANTIS numeric <--> ORACLE NUMBER: The magnitude of the source number is

greater than the magnitude supported by the target NUMBER. For a conversion of a MANTIS string value to an ORACLE DATE:

The string format should be:

DD MON YY

- The MANTIS string is fewer than eight characters in length. - The MANTIS string doesn't specify a valid date and time (up to its length or to

16 places, whichever is less).

SQL Programming Guide, P39-1381 50 Chapter: 6. Data conversion between MANTIS SQL Support and supported databases Section: Data conversion between MANTIS SQL Support and SUPRA databases

Data conversion between MANTIS SQL Support and SUPRA databases In MANTIS SQL Support, data is always manipulated as a MANTIS data type. When a data value is transferred between MANTIS and SQL, MANTIS causes the database system to automatically convert its data type to a MANTIS-compatible data type (if the host variable and the SQL variable are of compatible types). The following table lists permissible data conversions.

Check the notes for information about overflow, truncation, and rounding. Any combination of MANTIS and SQL data types, not listed in the following table, results in a run-time error. Truncation is indicated through the SQLWARN elements in the SQLCA and indicator variables, if used.

Numeric rounding and overflow conditions depend on the precision of the column specified in the table definition. While overflow is a SUPRA ERROR condition, rounding might or might not be flagged as a SUPRA WARNING condition, depending on the data types involved.

SQL Data Type

MANTIS Data Type(s)



0 (Fixed) INTEGER Overflow Rounding, Overflow

SMALL Rounding, Overflow Rounding

BIG Rounding, Overflow Rounding


1 (Float) INTEGER Rounding Rounding, Overflow

SMALL Rounding Rounding

BIG Rounding Rounding


2 (Character) TEXT Truncation Truncation

4 (Date) TEXT Truncation Truncation

5 (Time) TEXT Truncation Truncation

6 (String) TEXT Truncation Truncation

SQL Programming Guide, P39-1381 51 Chapter: 6. Data conversion between MANTIS SQL Support and supported databases Section: Data conversion between MANTIS SQL support and Oracle Rdb databases

Data conversion between MANTIS SQL support and Oracle Rdb databases

Rdb performs data conversion between all data types, including conversions between numeric and string data types. Be sure to match host variable data types with database columns so that correct results are obtained.

Rdb does not flag truncation of data as a warning.

The following Rdb data types can be returned in the SQLDA.

SQLTYPE Description

449 VARCHAR Variable length string up to length 65535

453 CHAR Space padded character string

481 FLOAT 4- or 8-byte floating point, depending on SQLLEN

485 DECIMAL Packed-decimal with precision and scale specified by SQLLEN

497 INTEGER 4-byte integer

501 SMALLINT 2-byte integer

503 DATE 64-bit number in OpenVMS absolute date-time format

505 QUADWORD 8-byte integer

MANTIS data types can only be INTEGER, SMALL, BIG, DECIMAL or TEXT, but can be mapped to any Oracle Rdb data type, so data transfer between MANTIS host variables and database columns may frequently involve conversions. The following conversion error conditions apply:

MANTIS string --> Oracle Rdb numeric: - The MANTIS string is not a valid number in decimal or scientific E notation. - The MANTIS string contains commas. - The magnitude of the converted MANTIS string is greater than the magnitude

supported by the target number. - The magnitude of the converted MANTIS string is greater than the magnitude

supported by the target number. MANTIS numeric <--> Oracle Rdb number. The magnitude of the source number

is greater than the magnitude supported by the target number. MANTIS string --> Oracle Rdb DATE:

String format should be "YYYYMMDDHHMMSSNN".

- The MANTIS string is less than 8 characters in length. - The MANTIS string does not specify a valid date and time (up to its length or to

16 places, whichever is less).

SQL Programming Guide, P39-1381 52 Chapter: 7. Programming considerations for SQL Section: Introduction to SQL programming considerations

7. Programming considerations for SQL Introduction to SQL programming considerations

To use MANTIS SQL Support, you simply embed the appropriate SQL statements in your MANTIS application program as standard MANTIS comments, enclosed in EXEC_SQL-END blocks.

MANTIS SQL Support's interpretive nature has several program design implications. Before you begin writing MANTIS SQL Support programs, learn about these implications, which are described throughout this chapter.

SQL Programming Guide, P39-1381 53 Chapter: 7. Programming considerations for SQL Section: MANTIS SQL Support and SQL statements

MANTIS SQL Support and SQL statements

How MANTIS SQL Support processes SQL statements As MANTIS SQL Support encounters each SQL statement, it prepares the SQL statement for execution and then executes the SQL statement. In effect, it performs the same steps that are performed for a COBOL program containing embedded SQL statements. These steps are:

Preprocess Compile Link Load

However, unlike a COBOL program, the MANTIS program (including its SQL statements) can be modified and then, through the RUN command, immediately re-executed.

SQL statements and cursors as SQL entities Both cursors and SQL statements are SQL entities and not MANTIS entities. Because of this, you cannot perform the following:

Pass them as parameters Use them in non-SQL MANTIS statements

SQL Programming Guide, P39-1381 54 Chapter: 7. Programming considerations for SQL Section: Varying line numbers associated with an EXEC_SQL-END block

Varying line numbers associated with an EXEC_SQL-END block

Introduction to varying line numbers associated with an EXEC_SQL-END block

An EXEC_SQL-END block can span several program lines. However, when you execute the EXEC_SQL-END block, MANTIS SQL Support internally stores the block as a single line of text. Exactly which line number MANTIS associates with the EXEC_SQL-END block depends on whether the MANTIS program is bound or unbound. For details, see the following topics:

Line number associated with an EXEC_SQL-END block in an unbound program Line number associated with an EXEC_SQL-END block in a bound program

Line number associated with an EXEC_SQL-END block in an unbound program

MANTIS SQL Support stores an EXEC_SQL-END block internally as a single line of text. If the program is unbound, MANTIS associates this single line with different program lines for different purposes:

For executing the program: For the purpose of program execution, MANTIS associates the EXEC_SQL-END block with the first line in the EXEC_SQL-END block. For example, to execute the sample code below, enter the following: RUN 6

For labeling an error message: For the purpose of labeling an error-message, MANTIS associates the EXEC_SQL-END block with the last line in the EXEC_SQL-END block. Therefore, if MANTIS encounters an error in the sample code below, it returns the appropriate error message and displays "9" for line 9.


...

6 EXEC_SQL

7 | SELECT * FROM table-name

8 | WHERE col-name > :MIN_VALUE

9 END

Line number associated with an EXEC_SQL-END block in a bound program

MANTIS SQL Support stores an EXEC_SQL-END block internally as a single line of text. If the program is bound, MANTIS associates this single line with the line number of the last SQL statement (the line immediately preceding the END statement; in the case of the sample code below, line 8). For example, to execute the following sample code, enter the following:

RUN 8

If MANTIS encounters an error in the program block, it returns the appropriate error message and displays "8" for line 8.

See the following sample code: ...

6 EXEC_SQL

7 | SELECT * FROM table-name

SQL Programming Guide, P39-1381 55 Chapter: 7. Programming considerations for SQL Section: Varying line numbers associated with an EXEC_SQL-END block

8 | WHERE col-name > :MIN_VALUE

9 END

SQL Programming Guide, P39-1381 56 Chapter: 7. Programming considerations for SQL Section: Scope of cursors, statements, and SQLDA data structures

Scope of cursors, statements, and SQLDA data structures

Scope of cursors, statements, and SQLDA data structures under ODBC and SUPRA

SQL statement names are MANTIS entities and not SQL entities. Hence, their scope is limited strictly to the program or external subprogram in which they are PREPARED.

SQL cursors are SQL entities and MANTIS entities. Cursors are global to ODBC but local to a MANTIS program context. A cursor is synonymous with the name of a result table and as such may be used in FETCH statements when not even DECLARED or OPENED explicitly.

Because MANTIS interprets cursor names differently in different statements, a cursor name can be DECLARED and OPENED in one program and used in a FETCH statement in an external subprogram. However, you cannot OPEN a cursor which is DECLARED in a calling program context. This is because MANTIS uses the cursor name to link the OPEN statement to the DECLARE statement, and cursor names are local in scope from MANTIS' point of view.

The following examples illustrate this point:

Scope of cursors, statements, and SQLDA data structures under DB2, Oracle, and Oracle Rdb

Basic elements of dynamic SQL programs

The following are identified by names and are basic to dynamic SQL programs:

Cursors Statements SQLDA data structures

SQL Programming Guide, P39-1381 57 Chapter: 7. Programming considerations for SQL Section: Scope of cursors, statements, and SQLDA data structures

Local scope for cursor name, statement name, or SQLDA name

The scope of a cursor name, statement name, or SQLDA data structure name is local. That is, it's limited to the program or external subprogram context in which the name is declared. When a cursor name, statement name, or SQLDA name is re-declared in an external subprogram, the name refers to a different structure.

Mapping MANTIS cursor names and MANTIS statement names onto database cursor names and database statement names

MANTIS maps cursor names and statement names onto database cursor names and statement names. The scope of the database cursor names and statement names is one of the following:

MANTIS main program Entire connect time to the database

MANTIS cursors and real cursor names

The mapping of cursor names requires further explanation since certain error conditions relating to open cursors can cause error messages to display real cursor names.

As each MANTIS cursor is opened, the MANTIS nucleus allocates and maps a global real cursor name of the form "Cnnn" (where "nnn" is a three-digit number allocated by MANTIS) to the MANTIS cursor name. Therefore, each MANTIS external subprogram maps a range of real cursor names.

When the EXIT subprogram executes, MANTIS closes all open real cursors. This frees up that range of real cursor names for the next subprogram to be called, or for the same subprogram to be invoked again.

The limited scope of a MANTIS cursor name is illustrated by the following mapping:

MANTIS cursor C1 in main program MAIN might be mapped to real cursor C001. MANTIS cursor C1 in external subprogram SUB might be mapped to real cursor

C006.

SQL Programming Guide, P39-1381 58 Chapter: 7. Programming considerations for SQL Section: Using the MANTIS EXEC_SQL statement for multiple-session support

Using the MANTIS EXEC_SQL statement for multiple-session support This topic discusses the use of EXEC_SQL for multiple-session support.

This guide's examples have already demonstrated the EXEC_SQL statement's common usage. For this examples, see Place an SQL statement within an EXEC_SQL-END block.

Below is the syntax definition for the EXEC_SQL statement:

exp1

Description When you require multiple database connections, specify one of the following:

Database subsystem type (DBTYPE) One of the following:

- DB2 SQL CONNECT session number - ODBC SQL CONNECT session number - Oracle SQL CONNECT session number - SUPRA SQL CONNECT session number

Format One of the following:

Text expression. One of the following: - DB2 - ODBC - ORACLE - RDB - SUPRA

Numeric expression. One of the following: - For ODBC and SUPRA—A session number ranging from 1-8. - For DB2 and Oracle—A session number ranging from 1-5.

Consideration If you use a numeric session number, the current DBTYPE must be DB2, ODBC, ORACLE, or SUPRA.

exp2

Description Optional. When you have used exp1 to specify one of the following as the DBTYPE, use exp2 to specify the connect session number:

DB2 ODBC ORACLE SUPRA

Format A numeric expression, equal to one of the following:

SQL Programming Guide, P39-1381 59 Chapter: 7. Programming considerations for SQL Section: Using the MANTIS EXEC_SQL statement for multiple-session support

For ODBC and SUPRA. A session number ranging from 1-8. For DB2 and Oracle. A session number ranging from 1-5.

General considerations

Consider the following:

Multiple session support. This refers to both of the following: - The ability to connect to different SQL databases concurrently. As an example,

MANTIS can connect to both SUPRA and ORACLE databases. As another example, MANTIS can connect to both ODBC and Oracle Rdb databases concurrently.

- The ability to have multiple connections to a single database. You can only do this with certain databases, such as SUPRA or ODBC.

You can connect to only one Oracle Rdb or DB2 database at a time.

Current DBTYPE. The current DBTYPE, an element of the EXEC_SQL statement, is the default DBTYPE that's used when a DBTYPE is not specified in an EXEC_SQL statement. The current DBTYPE, once set, remains in place until it's changed in one of the following two ways: - Explicitly—Performed by another EXEC_SQL or SQLCA statement. - Implicitly—Performed when you sign on to another MANTIS User.

The MASTER User can specify your default DBTYPE in your MANTIS User profile. If the MASTER User doesn't specify this, MANTIS uses SUPRA as the default DBTYPE.

Not all DBTYPEs are supported on all operating systems. For example:

Oracle Rdb support is available only on the OpenVMS operating system. Common platform DB2 support is available only on the AIX operating

system.

SQL Programming Guide, P39-1381 60 Chapter: 7. Programming considerations for SQL Section: SQL WHENEVER statement

SQL WHENEVER statement

Differences between WHENEVER statement in MANTIS SQL Support and WHENEVER statement in SQL in COBOL

The WHENEVER statement in MANTIS SQL Support differs from the one in "SQL in COBOL" in the following ways:

WHENEVER settings. Due to the interpretive nature of MANTIS, WHENEVER settings, when used with conditional statements, may have different effects than they would under SQL in COBOL. By "WHENEVER setting," we mean the combination of a condition (such as SQLWARNING) and an action (such as CONTINUE) specified by the WHENEVER statement. For example, consider the following statements: WHENEVER SQLWARNING CONTINUE

WHENEVER SQLERROR FAULT

Ranges of applicability for WHENEVER settings. In an SQL WHENEVER statement, MANTIS SQL Support's WHENEVER settings may have different ranges of applicability than the WHENEVER settings in "SQL in COBOL."

DO statement vs. GOTO statement. In an SQL WHENEVER statement, MANTIS SQL Support uses the MANTIS DO statement where "SQL in COBOL" would use a GOTO clause.

FAULT statement vs. STOP statement. In an SQL WHENEVER statement, MANTIS SQL Support uses the FAULT statement, while "SQL in COBOL" would use a STOP statement. FAULT is an extra WHENEVER action that enables program termination upon occurrences of a specified condition.

Default for the SQLERROR condition. In an SQL WHENEVER statement, MANTIS SQL Support uses a default of FAULT for the SQLERROR condition, while "SQL in COBOL" uses a default of CONTINUE for the SQLERROR condition.

Syntax for MANTIS SQL Support WHENEVER statement Below is the syntax for the MANTIS SQL Support WHENEVER statement:

Any action (DO, FAULT, or CONTINUE) can be selected for any condition:

For ODBC and SUPRA, the conditions are: - SQLERROR - SQLWARNING - NOT FOUND - SQLEXCEPTION

For DB2, Oracle, and Oracle Rdb, the conditions are: - SQLERROR - SQLWARNING - NOT FOUND

WHENEVER condition action

condition

Description Required. Specifies the condition for which you're checking.

Options Valid conditions are:

SQLERROR


SQLWARNING NOT FOUND (ODBC and SUPRA Only) SQLEXCEPTION

These conditions are explained below:

Option Description Default Action

SQLERROR Optional. Indicates both of the following: The database returned an error code as the result of an

SQL statement SQLCODE < 0

FAULT

SQLWARNING Optional. Indicates both of the following: SQLCA ("SQLWARN0") = "W" SQLCODE = 0

CONTINUE

NOT FOUND Optional. Indicates just one of the following: The database cannot find a row to satisfy your SQL statement ...or There are no more rows to fetch (SQLCODE = 100)

CONTINUE

(ODBC and SUPRA Only) SQLEXCEPTION

Optional. Handles SQL timeout error conditions. Timeouts can be configured for database locks as well as database access.

CONTINUE

action

Description Required. Specifies the action to be taken when the named condition is met.

Options Valid actions are the following:

DO entry-name[(parms)] FAULT CONTINUE

These actions are explained below:


Option Description Considerations

DO entry-name[(parms)]

Optional. Indicates one of the following: Standard MANTIS internal DO Standard MANTIS external DO Whenever the named condition is encountered, WHENEVER-DO transfers control to the specified internal subroutine or external program.

This option corresponds to the WHENEVER-GOTO SQL statement of "SQL in COBOL's" WHENEVER-DO statement.

The following steps are performed: WHENEVER-DO transfers control from the calling program to an internal subroutine or to an external program. In the process, WHENEVER-DO passes the DO argument values (current at the execution time of the EXEC_SQL statement preceding the DO statement) to the internal subroutine or to the external program. The internal subroutine or external program executes its logic. This logic can include any MANTIS logic, such as CHAIN, EXIT, or STOP statements. The EXIT subroutine returns control to the calling program. The calling program resumes at the first statement following the EXEC_SQL-END block in which the DO is located. The WHENEVER-DO statement resembles

the existing functionality of the SET TRAP statement in MANTIS. If the DO portion of a WHENEVER-DO statement contains an error, MANTIS returns a MANTIS error message associated with the DO statement, not an SQL WHENEVER-type error. With the error message, MANTIS displays the number of the subroutine line that contains the error. If any part of a WHENEVER statement contains an error, MANTIS detects that error whether the WHENEVER statement is in the execution path or not.

DO is executed as a result of an SQL statement raising the condition with which the DO action is associated.

FAULT Optional. Performs both of the following: Terminates program

execution. Displays the generated

database-system message in the form of a MANTIS fault (error) message.

MANTIS SQL Support only intercepts the specified condition and faults the MANTIS program if WHENEVER condition FAULT is in effect. Remember that FAULT is the default action for SQLERROR.

CONTINUE Optional. When the named condition occurs, CONTINUE permits program execution to proceed without interruption. After the named condition occurs, your program should check SQLCODE for the results of each EXEC_SQL.


Quick reference for WHENEVER conditions and default actions The table below provides a quick reference for each WHENEVER condition and its associated default action:

WHENEVER Condition Supported on Default Action

SQLERROR DB2, ODBC, Oracle, Oracle Rdb, and SUPRA FAULT

SQLWARNING DB2, ODBC, Oracle, Oracle Rdb, and SUPRA CONTINUE

NOT FOUND DB2, ODBC, Oracle, Oracle Rdb, and SUPRA CONTINUE

SQLEXCEPTION ODBC and SUPRA CONTINUE

Sample code for DO, FAULT, and CONTINUE

DB2, ODBC, Oracle, Oracle Rdb, and SUPRA sample code |

| SET 'WHENEVER' SETTINGS TO DESIRED VALUES

|

EXEC_SQL

| WHENEVER SQLERROR DO DO_ROUTINE(PARM1,PARM2,PARM3)

END

EXEC_SQL:| WHENEVER SQLWARNING FAULT

END

EXEC_SQL:| WHENEVER NOT FOUND CONTINUE

END

ODBC and SUPRA sample code END

EXEC_SQL:| WHENEVER SQLEXCEPTION CONTINUE

END

Declarative (COBOL) vs. interpretive (MANTIS) WHENEVER statements

Declarative WHENEVER statement for SQL embedded in COBOL

When SQL is embedded in COBOL, WHENEVER is a declarative statement. WHENEVER is processed when the user precompiles the program, rather than when the user executes the program. Thus, in a COBOL program, the current "WHENEVER setting" is determined by sequential position in the program, regardless of the execution path at runtime. Contrast this with an interpretive WHENEVER statement for SQL embedded in MANTIS.

By "WHENEVER setting," we mean the combination of a condition (such as SQLWARNING) and an action (such as CONTINUE) specified by the WHENEVER statement. For example, consider the following statement:

WHENEVER SQLWARNING CONTINUE

In this statement, SQLWARNING is the condition and CONTINUE is the action. Together, they make up the setting.

Remember that a WHENEVER setting is an accumulation of three settings for DB2, Oracle, and Oracle Rdb, and four settings for ODBC and SUPRA:

For DB2, Oracle, and Oracle Rdb:


- One setting for the condition SQLERROR - One setting for the condition SQLWARNING - One setting for the condition NOT FOUND

For ODBC and SUPRA: One additional setting for the condition SQLEXCEPTION

Interpretive WHENEVER statement for SQL embedded in MANTIS

When SQL is embedded in MANTIS, WHENEVER is an interpretive statement. The last-executed WHENEVER statement is in effect regardless of its position in the program sequence. Contrast this with a declarative WHENEVER statement for SQL embedded in COBOL.

When the difference between MANTIS SQL Support and SQL in COBOL is important

The difference between MANTIS SQL Support (last-executed WHENEVER being in effect) and "SQL in COBOL" (most recent WHENEVER in program sequence being in effect) is important when you use a WHENEVER statement with conditional statements.

The following figure shows the different effects of a declarative vs. interpretive WHENEVER statement. In this figure, C represents a condition and 1 and 2 represent actions.

The consideration illustrated in the figure above also applies to the following MANTIS structures:

FOR UNTIL WHEN IF

Scope of the WHENEVER statement

The scope of the WHENEVER statement is both of the following:

The current MANTIS DOLEVEL Every EXEC_SQL until a new WHENEVER is executed

If you don't want the default WHENEVER settings, make each externally done program issue WHENEVER.

SQL Programming Guide, P39-1381 65 Chapter: 7. Programming considerations for SQL Section: SQL FINISH statement (ODBC and SUPRA only)

SQL FINISH statement (ODBC and SUPRA only) For ODBC and SUPRA databases, we provide the FINISH statement for compatibility with MANTIS SQL support for Oracle Rdb. It's a request to disconnect from the specified (or default) ODBC or SUPRA session. It is functionally equivalent to the COMMIT WORK RELEASE statement.

The FINISH statement syntax is below:

FINISH

SQL Programming Guide, P39-1381 66 Chapter: 7. Programming considerations for SQL Section: SQL SET DBNAME statement (ODBC, SUPRA, and Oracle only)

SQL SET DBNAME statement (ODBC, SUPRA, and Oracle only) For ODBC, SUPRA, and Oracle databases, this statement provides an alternate way to change the setting of SQLCA("DBNAME"). It enables you to specify the database names to use in all subsequent connects. For more information, see SQLCA elements.

The SET DBNAME statement syntax is below:

SQL Programming Guide, P39-1381 67 Chapter: 7. Programming considerations for SQL Section: SQLCA function and SQLCA statement

SQLCA function and SQLCA statement

SQLCA in SQL in COBOL vs. SQLCA in MANTIS SQL Support

SQLCA in "SQL in COBOL"

In "SQL in COBOL," the SQLCA (SQL Communications Area) is a data structure. An "SQL in COBOL" application accesses elements in the SQLCA as items of data.

SQLCA in MANTIS SQL Support

In MANTIS SQL Support, the following two items provide all standard SQLCA capabilities:

SQLCA function. For reading SQLCA structure elements. SQLCA statement. For writing SQLCA structure elements.

SQLCA syntax Below is the syntax for:

SQLCA function. For reading SQLCA structure elements:

sqlca-element = SQLCA(element_name)

SQLCA statement. For writing SQLCA structure elements:

SQLCA(element_name) = sqlca-element-value

Consider the following elements:

sqlca-element

Description Required. Specifies a MANTIS variable or array element to receive the value of your SQLCA element.

Format Valid MANTIS variable reference:

Scalar variable Subscripted array Substring reference

Consideration The data type of sqlca-element must be compatible with the data type of the SQLCA element referenced as element_name in the SQLCA function.

element_name

Description Required. Specifies one of the following:

A text literal that is the name of the element to be returned or read. A text variable containing the name of the element to be returned or read.

Format Text expression evaluating to a valid SQLCA element, as listed in the topic SQLCA elements.

Considerations

You can specify element_name in two different ways: - As a text literal—When you specify element_name as a text literal, you must

use quotation marks (""). For example: IF SQLCA("SQLCODE")<ZERO

DO ERROR_CONDITION_ROUTINE


END

- In a text variable—For example: CACODE="SQLCODE"

IF SQLCA(CACODE)<ZERO

DO ERROR_CONDITION_ROUTINE

END

Because the SQLCA function is a built-in function, it isn't declared. Cincom doesn't require or recommend an INCLUDE SQLCA statement.

sqlca-element-value

Description Required. Specifies a value to be assigned to your SQLCA element.

Format Valid text or numeric MANTIS expression, or text literal, of the appropriate type (dependent upon the element type)

Considerations

The data type of sqlca-element-value must be compatible with the data type of the SQLCA element referenced as element_name in the SQLCA statement.

Cincom has added an additional element, DBTYPE, to MANTIS SQL Support. For more information, see DBTYPE, an additional element for the SQLCA statement.

SQLCA elements The table below lists the compatible MANTIS data type for each SQLCA element name.

The following SQLCA elements are read-only:

SQLCABC SQLCAID SQLERRML SQLEXT

Although values can be written into the other elements, doing so doesn't pass any information to the database. In addition, since the database writes to these elements, their contents may be destroyed at each EXEC_SQL statement execution. For more information, see SQLERRMC, an additional element for the SQLCA statement.

If you move a data value from an SQLCA element to a MANTIS variable of shorter length, some of the right-hand characters are truncated. For example, this occurs if you move an eight-character SQLCA element to a six-character MANTIS variable.

For portable, non-volatile MANTIS software, consider the entire SQLCA structure to be read-only.

SQLCA Element Name

Compatible MANTIS Data Type (MANTIS Variable)

Element Contents

Usage Notes

DBTYPE TEXT (6) Database with which MANTIS SQL Support will communicate.

Fully supported. See DBTYPE, an additional element for the SQLCA statement.


SQLCA Element Name


Element Contents

Usage Notes

DBNAME TEXT (64) Database name used in all subsequent connects.

Fully supported. See DBNAME, an additional element for the SQLCA statement.

SQLCAID TEXT(8) SQLCA Read-only. Eye-catcher. Set by SQL.

SQLCABC One of the following: For ODBC, SUPRA,

Oracle, and Oracle Rdb: NUMERIC

For DB2: BIG

Length of SQLCA. Read-only. Set by SQL.

SQLCODE One of the following: For ODBC, SUPRA,


For DB2: BIG

Code indicating results of SQL statement execution.

SQLERRML

For SUPRA, Oracle, and Oracle Rdb only.

NUMERIC Read-only.

SQLERRMC TEXT(70) Tokens for insertion into SQL error message text.

Read-only. See SQLERRMC, an additional element for the SQLCA statement.

SQLERRP TEXT(8) SQL diagnostic data.

SQLERRDn One of the following: For ODBC, SUPRA,


For DB2: BIG

SQL diagnostic data. n ranges from 1–6.

SQLEXT

For ODBC and SUPRA only.

TEXT (84) Read-only.

SQLSTATE

For DB2 only.

TEXT(5) Indicates the result of SQL statement execution.


SQLCA Element Name


Element Contents

Usage Notes

SQLWARNn TEXT(1) SQL warning flags. One of the following: For DB2:

n ranges from 0-A.

For ODBC and SUPRA: n ranges from 0–F.

For Oracle and Oracle Rdb: n ranges from 0–7.

Additional MANTIS SQL Support elements for the SQLCA statement

DBTYPE, an additional element for the SQLCA statement

The DBTYPE element for the SQLCA statement enables you to specify the database with which MANTIS SQL Support will communicate.

Below is the syntax for DBTYPE:

SQLCA("DBTYPE")

Below are the DBTYPE element details:

DBTYPE

Description Specifies a text value, one to six characters in length, for the current DBTYPE.

For more information on the DBTYPE, see Update the User Profile with the default SQL DBTYPE.

Format The following DBTYPE values are valid:

DB2 ODBC ORACLE RDB SUPRA

Consideration By default, after execution of the SQLCA("DBTYPE") statement, all executed EXEC_SQL statements access the relational database implied by the DBTYPE.

DBNAME, an additional element for the SQLCA statement (ODBC, Oracle, and Oracle Rdb only)

For ODBC, Oracle, and Oracle Rdb, the DBNAME element for the SQLCA statement enables you to specify the database name used in all subsequent connects.


Below is the syntax for DBNAME:

SQLCA("DBNAME")

Below are the DBNAME element details:

DBNAME

Description Specifies a database name.

Format A text value, 1-64 characters in length.

Consideration If you don't specify a database name, MANTIS obtains it from:

For Common platform databases other than Oracle Rdb: The translation of the logical name MANTIS_SQL_DBNAME.

For Oracle Rdb: The translation of the logical name SQL$DATABASE.

SQLERRMC, an additional element for the SQLCA statement

The SQLERRMC element and associated length parameter returns the error message text for the current SQLCODE.

Below is the syntax for SQLERRMC:

SQLCA("SQLERRMC")

Below are the SQLERRMC element details:

SQLERRMC

Description Returns the error message text for the current SQLCODE.

Considerations

The SQLERRMC element and associated length parameter returns the error message text for the current SQLCODE. For example: EXEC_SQL

...

END

IF SQLCA("SQLCODE")<0

SHOW SQLCA("SQLERRMC");

END

SQLCA ("SQLCODE") is reset to zero at an implicit COMMIT. Any solicited input while MANTIS has COMMIT ON causes an implicit COMMIT. MANTIS always issues an implicit COMMIT at any terminal read operation, unless the program or user explicitly turns the automatic COMMIT logic off with the COMMIT OFF statement.

(ODBC and SUPRA Only) If your system administrator doesn't install the text of ODBC or SUPRA error messages, the following message is displayed for all database errors: 750 SQLERROR:nnnn:

In this message, the value "nnnn" is the number for the SQL error.

SQL Programming Guide, P39-1381 72 Chapter: 7. Programming considerations for SQL Section: COMMIT/ROLLBACK in SQL and COMMIT/RESET in MANTIS SQL Support

COMMIT/ROLLBACK in SQL and COMMIT/RESET in MANTIS SQL Support Regarding SQL's COMMIT/ROLLBACK statement and MANTIS SQL Support's COMMIT/RESET statement, consider the following.

For DB2, don't use the RELEASE parameter for COMMIT/ROLLBACK Cincom recommends that you do not use the COMMIT/ROLLBACK RELEASE parameter. This parameter is a request to disconnect from the database upon successful completion of the COMMIT or ROLLBACK. Rather than the RELEASE parameter, use the SQL CONNECT RESET statement to disconnect from the database.

Database and COMMIT By default, the MANTIS nucleus automatically issues COMMIT every time MANTIS reads from the terminal for a CONVERSE, OBTAIN, or WAIT statement. Be careful when using COMMIT and RESET in applications with embedded SQL.

COMMIT/ROLLBACK vs. COMMIT/RESET Regarding COMMIT/ROLLBACK vs. COMMIT/RESET, consider these issues. MANTIS SQL Support's COMMIT and ROLLBACK statements have exactly the same effect on the database as the MANTIS COMMIT and RESET statements. An executed SQL COMMIT or ROLLBACK doesn't imply a MANTIS COMMIT or RESET. However, an executed MANTIS COMMIT or RESET implies an SQL COMMIT or ROLLBACK. The MANTIS COMMIT/RESET statements COMMIT/ROLLBACK the current SQL transaction. Embedded SQL COMMIT/ROLLBACK statements affect only the SQL database.

Scope of an SQL COMMIT statement Execution of an SQL COMMIT statement commits only SQL, and only for the specified SQL session. However, in MANTIS, COMMIT and RESET commit everything, including SQL.

COMMIT and terminal input MANTIS automatically performs a COMMIT at terminal input.

COMMIT/RESET and SQL cursor position COMMIT/RESET can affect SQL cursor position. For more information on cursor positioning, refer to the following MANTIS manuals:

For DB2. SQL Reference DB2 guide. For Oracle. Oracle Reference Manual. For Oracle Rdb. VAX SQL Reference Manual, AA JM32B TE.

When MANTIS COMMIT executes MANTIS COMMIT executes in the following circumstances:

MANTIS encounters a MANTIS COMMIT statement. Any MANTIS program (including Program Design, when you are reading command

lines) encounters any terminal input function (CONVERSE, OBTAIN, WAIT, or MORE prompt), unless you have specified COMMIT OFF.

When MANTIS runs the main program cleanup, before database disconnection.

SQL Programming Guide, P39-1381 73 Chapter: 7. Programming considerations for SQL Section: COMMIT/ROLLBACK in SQL and COMMIT/RESET in MANTIS SQL Support

When MANTIS RESET executes MANTIS RESET executes in the following circumstances:

MANTIS encounters a MANTIS RESET statement. A MANTIS FAULT (excluding a breakpoint fault) occurs.

Be careful of a terminal input request by Program Design When Program Design makes a terminal input request, beware of the request's effect. Your MANTIS program might go into a resource wait state because it is attempting to update a table that another user is reading (via SELECT).

Be careful of COMMIT/RESET Carefully consider the use of COMMIT and RESET in your embedded SQL applications.

If you're in Program Design and have set a breakpoint, a RESET doesn't occur when program execution encounters a breakpoint (the breakpoint is a FAULT condition). However, unless you've performed a COMMIT OFF, an automatic COMMIT occurs when Program Design prompts you for the next input line. This could result in unintentional COMMITs of database transactions.

ROLLBACK on failed COMMIT (Oracle and DB2 only) When a MANTIS COMMIT fails to COMMIT the database, MANTIS automatically attempts to ROLLBACK only the database.

Notes specific to Oracle Rdb Some database updates may not be validated until they are committed (for INTEGRITY). For example, when you attempt to insert a NULL value into a column with the NOT NULL attribute, your SQL COMMIT statement may fail, and will continue to fail until the transaction containing the illegal operation is rolled back.

COMMIT closes all open cursors. If your cursors have to remain open across any terminal input, you must include a MANTIS COMMIT OFF statement in your main program.

SQL Programming Guide, P39-1381 74 Chapter: 7. Programming considerations for SQL Section: SQL-related error messages

SQL-related error messages

Message sources You can receive messages from three sources:

MANTIS nucleus MANTIS SQL Support The database system

Information that MANTIS generally displays for an error When MANTIS encounters an error, it generally displays the following:

Fault message Statement in which the error occurred Text of the line containing the statement in which the error occurred

For details on all of MANTIS's error messages, refer to MANTIS Messages and Codes, P39-1331.

Information that MANTIS displays for an error from the database system

An error message from the database system consists of the following:

The following three-character code: 750. The following text string: SQLERROR. The three- or four-digit SQLCODE value. In the following format sample, nnnn

represents this. The SQLCODE value's associated text message. In the following format sample,

###... represents this.

Here is the format sample:

750 SQLERROR:nnnn: ###...

As an example, consider the following ODBC or SUPRA database error:

750 SQLERROR:-803: INVALID NUMERIC INPUT PARAMETER

This error would be returned from ODBC or SUPRA if an SQLCODE indicating invalid string constants was returned to the SQLCA, and the WHENEVER SQLERROR condition was set to FAULT.

SQL Programming Guide, P39-1381 75 Chapter: 8. Dynamic SQL in MANTIS SQL Support Section: Who should read this chapter?

8. Dynamic SQL in MANTIS SQL Support Who should read this chapter?

Read this chapter if:

You're new to dynamic SQL programming. You're new to dynamic SQL programming in MANTIS SQL Support, but have

experience with dynamic SQL programming in other languages

Dynamic SQL in MANTIS SQL Support differs from dynamic SQL in other languages.

SQL Programming Guide, P39-1381 76 Chapter: 8. Dynamic SQL in MANTIS SQL Support Section: Dynamic SQL overview

Dynamic SQL overview

Dynamic SQL definition Dynamic SQL is a method for executing SQL statements when a program needs the following information, but does not possess this information before the program executes:

SQL statements Tables Column names

As an example, an application must use dynamic SQL if, during program execution, it requires a user to interactively enter an SQL statement at the terminal. The ISQL utility is an example of such an application.

Principal statements for dynamically executing SQL statements You can dynamically execute almost any statement that you would find in a static application. The principal statements enabling you to dynamically execute SQL statements are:

PREPARE DESCRIBE EXECUTE EXECUTE IMMEDIATE DECLARE (alternate form) OPEN (alternate form) FETCH (alternate form)

You accomplish communication to and from the database using the statements listed above and an SQLDA data structure.

SQLDA data structure You accomplish communication to and from the database using the statements listed in Principal statements for dynamically executing SQL statements and an SQLDA data structure. The SQLDA data structure used in database communication is a representation and repository of the data being transferred. The SQLDA data structure used in database communication consists of the following:

Header elements. Repeating elements. Each repeating element group is sometimes called an

SQLVAR.

The SQLDA data structure contains metadata (for example, data length and data type) about the data passing between your program and the database.

Defining data about SQL statements and host variables A single program can contain static SQL statements, dynamic SQL statements, or both:

Only static SQL statements. The SQL preprocessor defines the data about the MANTIS program's SQL statements and host variables.

Only dynamic SQL statements. The MANTIS program procedurally defines data about its SQL statements and host variables.


Both static and dynamic SQL statements. The MANTIS program procedurally defines data about its dynamic SQL statements and host variables, and the SQL preprocessor defines data about the MANTIS program's static SQL statements and host variables.

SQL statements that you cannot execute dynamically (DB2, Oracle, and Oracle Rdb only)

You cannot execute all DB2, Oracle, or Oracle Rdb statements dynamically. An example of a statement that you cannot execute dynamically is the SELECT statement. Because MANTIS SQL Support executes all embedded SQL statements dynamically, MANTIS must overcome this limitation on the SELECT statement. It does this by implicitly performing DECLARE and OPEN statements for each static SELECT statement.

For DB2 and Oracle, you cannot execute the following SQL statements dynamically through the dynamic PREPARE and EXECUTE statements:

CLOSE CREATE VIEW DECLARE CURSOR DESCRIBE EXECUTE FETCH OPEN PREPARE RELEASE SELECT [INTO] WHENEVER

For Oracle Rdb, you cannot execute the following SQL statements dynamically through the dynamic PREPARE and EXECUTE statements:

BEGIN DECLARE SECTION* CLOSE CREATE VIEW DECLARE CURSOR DECLARE STATEMENT** DECLARE TABLE** DESCRIBE EDIT END DECLARE SECTION* EXECUTE EXPORT FETCH FINISH IMPORT INCLUDE* INTEGRATE** OPEN PREPARE SELECT [ INTO ] QUIT


RELEASE SET** SHOW** WHENEVER

* May be embedded in a MANTIS program, but are ignored when executed.

** Not supported in MANTIS programs, and will cause errors when executed.

Auto-cursor FETCH statements (DB2, Oracle, and Oracle Rdb only) To support dynamic SQL, MANTIS uses auto-cursor FETCH statements. In the embedded SQL FETCH statement, the cursor-name is optional. An auto-cursor FETCH statement always applies to the most recently executed static SELECT statement (which may be in a calling program context).

Executing a statement dynamically To execute a statement dynamically, you usually perform the following:

1. Use the PREPARE statement to prepare the SQL statement. 2. If you're retrieving, inserting, or updating data, use program logic to manipulate

the SQLDA data structure. This SQLDA manipulation can include: - Allocating and expanding an SQLDA data structure. - Using the DESCRIBE statement to retrieve metadata from SQL. - Causing data transfer between SQL and MANTIS variables.

For an illustration of how dynamically executed SQL statements and the SQLDA data structure work together in dynamic routines, see one of the following topics:

DB2 dynamic SQL sample code for creating an SQLDA data structure ODBC, Oracle, and SUPRA dynamic SQL sample code for creating an SQLDA

data structure

3. Use the EXECUTE statement to execute the SQL statement.

Dynamic SQL sample code for creating an SQLDA data structure

DB2 dynamic SQL sample code for creating an SQLDA data structure

The following sample code provides an example of how to create an SQLDA data structure. This code includes examples of the built-in SQLDA statement and SQLDA function (described in the section titled SQLDA data structure).

For details on the syntax for the PREPARE, DESCRIBE, and EXECUTE statements used in this sample code, refer to the SQL Reference DB2 guide.

Below is sample code for creating an SQLDA data structure:

TEXT UPDATE_STMT(250)

TEXT DA:DA="sqlda-name"

SQLDA(DA)=NEW

EXEC_SQL:|PREPARE stmt-name FROM :UPDATE_STMT

END

EXEC_SQL:|DESCRIBE stmt-name INTO sqlda-name

END

FOR I=1 TO SQLDA(DA,"SQLD")


SQLDA(DA,"SQLHOSTVAR",I)=input-parameter

END

EXEC_SQL:|EXECUTE stmt-name USING DESCRIPTOR sqlda-name

END

In the preceding sample code, the following occur:

1. The first SQLDA statement allocates the SQLDA data structure. 2. The PREPARE statement dynamically compiles the SQL statement. 3. The DESCRIBE statement returns metadata about the results of the SQL statement

in the SQLDA data structure. 4. (This statement is optional) The second SQLDA statement supplies values for input

host variables. 5. The EXECUTE statement tells the processor to execute the named statement.

At the end of the program, you may include the SQLDA built-in function to transfer data from a host variable.

To find dynamic and static sample code for the following, see the appendix titled MANTIS SQL sample programs:

INSERT UPDATE SELECT DELETE A dynamic QUERY-like routine A dynamic column SELECT routine

ODBC, Oracle, and SUPRA dynamic SQL sample code for creating an SQLDA data structure

The following sample code provides an example of how to create an SQLDA data structure. This code includes examples of the built-in SQLDA statement and SQLDA function (described in the section titled SQLDA data structure).

Below is sample code for creating an SQLDA data structure, using a SELECT statement with input parameters:

TEXT DA:DA="sqlda-name"

SQLDA(DA)=NEW

TEXT SELECT_STMT(250)

EXEC_SQL:| PREPARE stmt-name INTO sqlda-name FROM :SELECT_STMT

END

EXEC_SQL:| DECLARE cursor-name CURSOR FOR stmt-name

END

SQLDA(DA,"SQLHOSTVAR",I)=input-parameter:| I = 1 TO SQLDA(DA,"SQLN")

EXEC_SQL:| OPEN cursor-name USING DESCRIPTOR sqlda-name

END

In the preceding sample code, the following occur:

1. The first SQLDA statement allocates the SQLDA data structure. 2. The PREPARE statement dynamically compiles the SQL statement. 3. The DESCRIBE statement returns metadata about the results of the SQL statement

in the SQLDA data structure.


4. (This statement is optional) The second SQLDA statement supplies values for input host variables.

5. The EXECUTE statement tells the processor to execute the named statement. 6. (This statement is optional) At the end of the program, you can include the SQLDA

built-in function to transfer data from a host variable.

To find dynamic and static sample code for the following routines, see the appendix titled MANTIS SQL sample programs:

INSERT UPDATE SELECT DELETE A dynamic QUERY-like routine A dynamic column SELECT routine

SQL Programming Guide, P39-1381 81 Chapter: 8. Dynamic SQL in MANTIS SQL Support Section: SQLDA data structure

SQLDA data structure

Introduction to the SQLDA data structure In dynamic SQL support, SQL communicates with your program via an SQLDA (SQL Descriptor Area) data structure. An SQLDA data structure holds "information about data" (known as metadata) that's transferred between your program and the database.

The figures below represent the structure of an SQLDA data structure. They contain the following elements:

Header elements. These are the first four elements in the figure below. They occur once per SQLDA data structure.

Repeating elements. One of the following: - For ODBC and SUPRA. These are the next nine elements in the figure below.

They repeat once per data item:

- For DB2, Oracle, and Oracle Rdb. These are the next six elements in the

figure below. They repeat once per data item:


A data item is one of the following:

One column of an SQL table. This is the output from SQL to your program. The value of a host variable. This is the input to SQL from your program.

The maximum number of entries in a data item is 300.

For more information on header elements and repeating elements, see the following topics:

SQLDA header elements SQLDA repeating elements

SQLDA names must follow the rules for MANTIS variable names so that the MANTIS parser can recognize them in embedded SQL statements.

MANTIS SQL Support differs from other programming languages in SQLDA element declaration and access:

Other programming languages. To declare and access SQLDA elements, you must perform the following:

Explicitly declare each SQLDA element as a data area in your program. Access the SQLDA elements through programming statements. MANTIS SQL Support. When you declare an SQLDA data structure, MANTIS SQL

Support automatically builds an SQLDA data structure with all of the elements shown in the preceding figure that applies to your database.

An SQLDA data structure contains the default number of repeating elements (your MASTER User set this in your SQLVARINC MANTIS Options). Your MANTIS program can modify this value.


The built-in SQLDA statement and built-in SQLDA function enable your MANTIS program to create and maintain SQLDA data structures. You can then use programmed dynamic SQL statements with these SQLDA data structures.

Use the SQLDA statement and function for different purposes:

SQLDA statement. Your MANTIS program can use the SQLDA statement to perform the following: - Create a named SQLDA data structure. - Send information (input host variable information) to SQL.

In the SQLDA statement, the sqlda-name parameter must include a text expression or literal that contains the name of a valid MANTIS variable.

SQLDA function. Your program can use the SQLDA function to retrieve information (output host variable information) about SQL table columns.

In the syntax described below, you must replace the following with standard MANTIS variables, literals, or expressions:

sqlda-name header-element

For a list of header elements, see SQLDA header elements.

repeating-element

For a list of repeating elements, see SQLDA repeating elements.

index (refers to the sequential occurrence of the repeating element group in the SQLDA data structure)

The following topics provide format samples for various uses of the SQLDA statement and SQLDA function:

Using the SQLDA statement: - Allocate an SQLDA data structure:

SQLDA (sqlda-name)=NEW

- Deallocate an SQLDA data structure: SQLDA (sqlda-name)=QUIT

- Move data from your program into an SQLDA header element: SQLDA (sqlda-name, header-element)=expression

- Move data from your program into an SQLDA repeating element: SQLDA (sqlda-name, repeating-element, index)=expression

Using the SQLDA function: - Move data from an SQLDA header element into your program:

mantis-variable=SQLDA (sqlda-name, header-element)

- Move data from an SQLDA repeating element into your program: mantis-variable=SQLDA (sqlda-name, repeating-element, index)

Allocate an SQLDA data structure Use this SQLDA statement to allocate a new SQLDA data structure.

SQLDA(sqlda-name) = NEW


sqlda-name

Description Required. Specifies the name of the new SQLDA data structure.

Format MANTIS text expression, 1–18 characters in length.

Consideration The expression result must be a valid MANTIS symbolic name with a length of 1–18 characters.



This statement allocates a new, empty SQLDA data structure with the default number of repeating elements. (At installation, your MASTER User sets the default number of repeating elements as one of your MANTIS Options.)

Within your program, you can modify an SQLDA data structure's size by resetting the value of SQLMAX (see the SQLMAX discussion).

If you use an SQLDA statement to declare a second SQLDA data structure with the same name as a first, pre-existing SQLDA data structure, MANTIS ignores your second SQLDA statement.

The scope of an SQLDA data structure is the current DO level. As an example, you can create two SQLDA data structures, both with the same name, on two different DO levels. However, within a single DO level, you can access only SQLDA data structures defined for that DO level.

Example


SQLDA("SQLDA1")=NEW

Deallocate an SQLDA data structure Use this SQLDA statement to deallocate an SQLDA data structure.

SQLDA(sqlda-name) = QUIT

sqlda-name

Description Required. Specifies the name of the SQLDA data structure to be deallocated.

Format MANTIS text expression, 1–18 characters in length.

Consideration The sqlda-name text expression must specify the name of a previously allocated SQLDA data structure. This text expression can be any valid MANTIS text expression or text literal.



This statement deallocates an existing SQLDA data structure by name. When a DO level is exited, MANTIS automatically deallocates all SQLDA data

structures that were defined at that DO level.


If you execute a RUN without specifying a line number, MANTIS automatically deallocates all SQLDA data structures.

A RUN with a line number can produce unpredictable results if you have modified the program in which you are running the specific line.

Example


SQLDA("SQLDA1")=QUIT

Move data from your program into an SQLDA header element

SQLDA statement for moving data from your program into an SQLDA header element

Use the following SQLDA statement to set header or column-name information in the SQLDA data structure.

SQLDA(sqlda-name,header-element) = expression

sqlda-name

Description Required. Specifies the name of a previously allocated SQLDA data structure.

header-element

Description Required. Specifies the name of the SQLDA header element into which you are moving data.

Format MANTIS text expression

Options You can set only these three header elements:

SQLN (In DB2, Oracle, and Oracle Rdb support, SQLN and SQLMAX are the same) SQLMAX SQLD

See the table below.

Header Element

Description

Example

SQLN In DB2, Oracle, and Oracle Rdb support, SQLN and

SQLMAX are the same. In ODBC and SUPRA support, SQLN is the total number of host variables in the SQLDA. This value can range from one to SQLMAX. A DESCRIBE statement normally sets this value. Your program must also sometimes set SQLN; for example, when you're inserting data.

SQLDA("DA1","SQLN")=10


Header Element

Description

Example

SQLMAX SQLMAX is the number of repeating groups in the physical SQLDA structure. The value can range from 1 to 300. Setting this number in your program causes the SQLDA to expand or contract by the specified number of repetitions. Once physically expanded, the space occupied by the SQLDA never physically contracts. For example, if an SQLDA named DA1 has 20 repeating occurrences, the statement at right reduces the logical occurrences to 5. However, physical space for 20 remains.

These example numbers are arbitrary.

SQLDA("DA1","SQLMAX")=5

SQLD One of the following: For ODBC and SUPRA. SQLD is the total number of

output host variables in the statement. The value of SQLD must be less than or equal to SQLN. SQLD cannot be set to a value greater than the current value of SQLN.

For DB2. The number of repeating groups currently in use. SQL sets it as the result of a PREPARE INTO or DESCRIBE statement. However, when necessary, the program can set it.

For Oracle and Oracle Rdb. The number of SELECT LIST columns, or the number of host variable MARKERS currently described in the SQLDA repeating elements. An SQLDA cannot describe both SELECT LIST columns and MARKERS at the same time. When processing a dynamic SELECT statement containing input host variable parameters, the statement must be DESCRIBED twice:

To obtain the number and type of input parameters which must be supplied in an OPEN statement To obtain the number and type of output column results from a FETCH statement.

SQLDA("DA1","SQLD")=8

Considerations


For more information on possible header-element values, see the table under SQLDA header elements.

The other header element illustrated in Introduction to the SQLDA data structure, SQLDAID, is read-only. If you attempt to use a read-only element in this SQLDA statement, you generate a fault.

MANTIS performs the DESCRIBE SELECT LIST on your behalf, using the SQLDA named in the USING clause of the FETCH statement. You're responsible for describing MARKERS into the SQLDA named in the OPEN statement's USING clause.

expression

Description Required. Specifies the SQLDA variable count.


Format Standard MANTIS variable, literal, or expression. A MANTIS numeric expression.

Consideration Since all settable SQLDA header elements are numeric, the expression must also always be numeric.

General consideration

A third-generation language like FORTRAN or COBOL handles the execution of a DESCRIBE statement differently than MANTIS SQL Support:

Third-generation language behavior. The SQLDA data structure is too small if SQLMAX—for ODBC and SUPRA—or SQLN—for DB2, Oracle, and Oracle Rdb—is less than the number of items that will be returned as a result of the PREPARE INTO statement (for database types other than ODBC) or the DESCRIBE statement. In this case, SQL sets SQLN to the required number and terminates. The program must then expand the SQLDA data structure to the required size.

MANTIS SQL Support behavior. If the SQLDA data structure is too small to accept the results of a DESCRIBE statement, MANTIS SQL Support automatically expands the SQLDA data structure to the required size. To check the number of repeating elements after MANTIS executes the DESCRIBE statement, examine the SQLN (for ODBC and SUPRA) or SQLD (for DB2, Oracle, and Oracle Rdb) value.

Example

Consider the following sample code:

SQLDA("SQLDA1","SQLN") = TOTAL_NEEDED

SQLDA header elements

The table below lists the SQLDA header elements. Use this table to complete the SQLDA statement's header-element syntax element. For more on the SQLDA statement, see SQLDA statement syntax for moving data from your program into an SQLDA header element.

Element Function How It's Set Results Updatable?

SQLDAID Eye catcher One of the following: For ODBC. Set by

SQL. For DB2. Set by DB2. For Oracle or Oracle

Rdb. Set by Oracle. For SUPRA. Set by

SQL.

Normally contains "SQLDA"

No



SQLD One of the following: For ODBC.

Current number of columns described in the SQLDA data structure.

For DB2. Total number of output host variables in SQLDA.

For SUPRA. Total number of output host variables in SQLDA.

For Oracle and Oracle Rdb. Current number of SELECT LIST columns or host variable MARKERS described in the SQLDA.

One of the following: For ODBC and

SUPRA. Set, as a result of a DESCRIBE statement, to the number of output host variables (except for DESCRIBE in FETCH USING DESCRIPTOR). In this DESCRIBE statement, SQLD is set to the number of result-table columns.

For DB2. Can be set in the following ways: - Automatically set

as a result of a PREPARE INTO or DESCRIBE statement.

- Manually set by the SQLDA statement.

For Oracle and Oracle Rdb. Set as a result of PREPARE INTO and DESCRIBE statements. It can be set by the SQLDA statement, but this is unnecessary because MANTIS always does implicit DESCRIBE MARKERS when necessary.


SUPRA. Number of output MANTIS variables described in SQLDA.

For DB2, Oracle, and Oracle Rdb. Number of input or output variables described in SQLDA.

Yes



SQLMAX One of the following: For ODBC

and SUPRA. Total number of repeating groups in the SQLDA data structure.

For DB2, Oracle, and Oracle Rdb. Same as SQLN. Total number of host variables in the SQLDA data structure.

Can be set in the following ways: Automatically set

when MANTIS allocates SQLDA, using a value from the MANTIS Options.

In a program, manually set by the SQLDA statement.

Number of repeating groups allocated.

Yes

SQLN One of the following: For ODBC

and SUPRA. Total number of host variables in SQLDA.

For DB2, Oracle, and Oracle Rdb. Same as SQLMAX. See SQLMAX.


SUPRA. Set, as a result of a DESCRIBE, to the total number of host variable parameters in the statement (except for DESCRIBE in FETCH USING DESCRIPTOR) where SQLN is set to the number of result table columns.

For DB2, Oracle, and Oracle Rdb. Same as SQLMAX. See the SQLMAX table row.


SUPRA. Number of output MANTIS variables described in SQLDA.

For DB2, Oracle, and Oracle Rdb. Same as SQLMAX. See the SQLMAX table row.

Yes

Move data from your program into an SQLDA repeating element

SQLDA statement syntax for moving data from your program into an SQLDA repeating element

Use the following SQLDA statement to supply values for input host variables, setting the values of repeating elements.


SQLDA(sqlda-name, repeating-element, index) = expression

sqlda-name

Description Required. Specifies the name of a previously allocated SQLDA.

repeating-element

Description Required. Specifies the name of the repeating element into which you're moving data.

Options There are different options for ODBC/SUPRA and for DB2/Oracle:

For ODBC and SUPRA: - SQLCOLNAME - SQLHOSTIND - SQLHOSTVAR

For DB2, Oracle, and Oracle Rdb: You can set the following three repeating elements: - SQLDATA - SQLIND - SQLNAME

For ODBC and SUPRA:

ODBC and SUPRA Repeating Element

Description

SQLCOLNAME Specifies the column name returned by SQL. SQLCOLNAME has a type of TEXT and a length of 18.

Your program can also set the column name.

Although you can modify the SQLCOLNAME element, your modifications don't affect the database. In addition, the database writes to the SQLCOLNAME element, so the SQLCOLNAME element's contents might be destroyed each time MANTIS executes an EXEC_SQL statement.

SQLHOSTIND Specifies the indicator value. The indicator value indicates the host variable's status: Contains a real value Is NULL Is MISSING

For more information on indicator variables, see the section titled Indicator variables.

Possible indicator values and their meanings include: Less than zero. The host variable data is NULL or MISSING. Greater than or equal to zero. The host variable contains real values.


ODBC and SUPRA Repeating Element

Description

SQLHOSTVAR Has different behavior in third-generation languages and in MANTIS SQL Support: Third-generation language behavior. The SQLHOSTVAR element holds a four-byte

binary address that a program and the database use to access the data item being transferred between the program and the database. A third-generation program must acquire space for the data item and place the space's address in this element.

MANTIS SQL Support behavior. The MANTIS nucleus uses the SQLHOSTVAR element to automatically perform the following actions when you transfer data into the SQLDA data structure:

Allocate a data area for the data item. Expand the data area, if necessary. Set the value of SQLHOSTVAR to the address of the data area. MANTIS SQL Support uses this address internally, and your program doesn't need to manipulate this value. Move data from the MANTIS host variable into the SQLDA data area. Set SQLCOLTYPE and SQLCOLLENGTH to match the definition of the MANTIS variable, according to the SQLCOLTYPE values discussed in MANTIS SQL Support data-type conversion. The MANTIS program sets SQLCOLLENGTH to the length of the MANTIS variable. Considerations If you're transferring data out of the SQLDA, the SQLHOSTVAR element simply

performs the transfer. The SQLHOSTVAR element might have a type of numeric or string. When you don't

know, in advance, the type of data that you want to retrieve from the database, use the SQLCOLTYPE and SQLHOSTVARTY elements to determine the data type.

For DB2, Oracle, and Oracle Rdb:


DB2, Oracle, and Oracle Rdb Repeating Element

Description

SQLDATA Has different behavior in third-generation languages and in MANTIS SQL Support: Third-generation languages. The SQLDATA element holds a four-byte

binary address that a program and the database use to access the data item being transferred between the program and database. A third-generation program must acquire space for the data item and place the space's address in this element.

MANTIS SQL Support. The MANTIS nucleus uses the SQLDATA element to automatically perform the following actions when you transfer data into the SQLDA data structure:

Do one of the following, as necessary: o Allocate a data area for the data item. o Expand the data area.

Set the value of SQLDATA to the address of the data area. MANTIS SQL Support uses this address internally, and your program does not need to manipulate this value. Move data from the MANTIS host variable into the SQLDA data area. Set SQLTYPE and SQLLEN to match the definition of the MANTIS variable, according to the SQLTYPE values discussed in MANTIS SQL Support data-type conversion. The MANTIS program sets SQLLEN to the length of the MANTIS variable. Considerations Consider the following: If you're transferring data out of the SQLDA, the SQLDATA element simply

performs the transfer. The SQLDATA element might have a type of numeric or string. When you

don't know, in advance, the type of data you want to retrieve from the database, use the SQLTYPE elements to determine the data type.

SQLIND Specifies the indicator value. The indicator value indicates the status of the host variable: Contains a real value Is NULL or MISSING Possible indicator values and their meanings are: Less than zero. The host variable data is NULL or MISSING. Greater than or equal to zero. The host variable contains real values.

For more information on indicator variables, see the section titled Indicator variables.


DB2, Oracle, and Oracle Rdb Repeating Element

Description

SQLNAME Specifies the column name returned by SQL. Your program can also set the column name. SQLNAME has a type of TEXT and a length of 18.

Although you can modify the SQLNAME element, your modifications don't affect the database. In addition, the database writes to the SQLNAME element, so the SQLNAME element's contents might be destroyed each time MANTIS executes an EXEC_SQL statement.

index

Description Required. Specifies the sequential occurrence of the repeating element into which you're moving data. The occurrence is relative to one rather than zero. For example, the eighth occurrence of the repeating element has an index value of eight.

Format MANTIS numeric expression.

expression

Description Required. Specifies an SQLVAR element value.

Format Standard MANTIS variable, literal, or expression

Considerations Consider the following:

The expression can be either text or numeric. There are no limitations on the expression.

Example


SQLDA ("SQLDA1","SQLHOSTVAR",9) = SALARY


MANTIS sets: - SQLCOLLENGTH (ODBC and SUPRA), SQLLENGTH (DB2), or SQLLEN (Oracle and

Oracle Rdb) to the length of the MANTIS expression. - SQLHOSTVARTY (ODBC and SUPRA) or SQLTYPE (DB2, Oracle, and Oracle Rdb)

to the equivalent data type in MANTIS (a data type conversion table appears in MANTIS SQL Support data-type conversion).

DB2, Oracle, and Oracle Rdb. For compatibility with MANTIS support for SUPRA SQL, MANTIS recognizes the SUPRA SQL element names as equivalent to the DB2, Oracle, and Oracle Rdb element names. Use the element names as follows:

DB2 SQL (DB2) and OpenVMS_SQL (Oracle)

SUPRA_SQL

SQLNAME SQLCOLNAME


DB2 SQL (DB2) and OpenVMS_SQL (Oracle)

SUPRA_SQL

SQLIND SQLHOSTIND

SQLDATA SQLHOSTVAR

SQLLEN SQLCOLLENGTH

SQLTYPE SQLCOLTYPE/SQLHOSTVARTY

DB2, Oracle, and Oracle Rdb. MANTIS SQL Support uses the SQLTYPE element to perform the following: - Describe the data type in the DB2, Oracle, or Oracle Rdb database. - Receive the host variable data type from MANTIS.

Whenever you use the SQLDA statement to set SQLDATA, MANTIS sets:

- SQLLEN to the length of the MANTIS expression - SQLTYPE to the MANTIS data type

At this point, previous contents of the elements, which a previous DESCRIBE statement might have set, could be lost.

MANTIS SQL Support data-type conversion

ODBC MANTIS SQL Support data-type conversion

ODBC MANTIS SQLDA MANTIS

Data Type Data Code

(SQLCOLTYPE)

Data Type

Data Code (SQLHOSTVARTY)

Data Type

Character 2 Character string (filled with blanks) 6 TEXT

Date 4 Character string 3 TEXT

Fixed 0 Integer (4 bytes, signed) Float (8 bytes)

1 3

INTEGER BIG/SMALL

Float 1 Integer (4 bytes, signed) Float (8 bytes) Fixed point decimal

1 3 5

INTEGER BIG/SMALL DECIMAL

String 6 Character string (with non-printable characters)

8 TEXT

Time 5 Character string 3 TEXT

DB2 MANTIS SQL Support data-type conversion

SQL Data Type

Description

SQL Type (Documented in DB2 SQL Reference Manual)

SQL Type Set by MANTIS

MANTIS Type

CHAR Fixed length string 452/453 448/449 TEXT

DATE Calendar Date 384/385 448/449 TEXT

DECIMAL Packed decimal number

484/485 480/481 BIG


SQL Data Type

Description

SQL Type (Documented in DB2 SQL Reference Manual)

SQL Type Set by MANTIS

MANTIS Type

FLOAT Floating point number

480/481 480/481 BIG

INTEGER Long integer 496/497 480/481 BIG

TIME Time 388/389 448/449 TEXT

TIMESTAMP Timestamp 392/393 448/449 TEXT

SMALLINT Short integer 500/501 480/481 BIG

VARCHAR Variable String 448/449 448/449 TEXT

SUPRA MANTIS SQL Support data-type conversion

SUPRA DRDM Data Type Data Code

(SQLCOLTYPE)

MANTIS SQLDA Data Type Data Code

(SQLHOSTVARTY)

MANTIS Data Type Data Code

Fixed 0 Integer (4 bytes, signed) Float (8 bytes)

1 3

INTEGER BIG/SMALL

Float 1 Integer (4 bytes, signed) Float (8 bytes) Fixed-point decimal

1 3 5

INTEGER BIG/SMALL DECIMAL

Character 2 Character string (filled with blanks)

6 TEXT

Date 4 Character string 3 TEXT

Time 5 Character string 3 TEXT

String 6 Character string (with non-printable characters)

8 TEXT

Note that certain representations of numeric data in the SQL database may cause conversion errors in the data values. You can avoid this by using the appropriate MANTIS numeric data type.

Oracle MANTIS SQL Support data-type conversion

Oracle

Description

SQLTYPE Set by MANTIS

MANTIS Type

CHAR Blank padded string 1 TEXT

DATE 7-byte Oracle date-time Cent YYMMDDHHMMSS 12 TEXT

DECIMAL Packed decimal 2 TEXT

INTEGER 4-byte integer 2 BIG*

NUMBER Floating point 2 SMALL/BIG

NUMBER(38) 2 byte integer, 4 byte integer 2 SMALL/BIG


Oracle

Description


MANTIS Type

SMALLINT 2-byte integer 2 BIG*

VARCHAR Varying string to 64K 1 TEXT

* MANTIS uses BIG to read integer data from the database because there might be an implied decimal point; for example, INTEGER(2).

The SQLDA statement is used to assign either string or numeric MANTIS data to an SQLDA repeating element. MANTIS sets the SQLTYPE to 1, 2 or 12 accordingly. If the SQLDA statement is not used in this way, MANTIS assigns SQLTYPES as shown in the table above, replacing the existing values of SQLTYPE.

Oracle Rdb MANTIS SQL Support data-type conversion

Rdb Type

Description


MANTIS Type

CHAR 453 Blank padded string 449 TEXT / MIXED / KANJI

DATE 503 64-bit integer 449 TEXT / MIXED / KANJI

DECIMAL 485 Packed-decimal 485 TEXT

FLOAT 481 Floating point 481 SMALL / BIG

INTEGER 497 4-byte integer 481 BIG*

QUADWORD 505 8-byte integer 485 DECIMAL**

SMALLINT 501 2-byte integer 481 BIG*

VARCHAR 449 Varying string to 64K 449 TEXT / MIXED / KANJI * MANTIS uses BIG to read integer data from the database because there may be an implied decimal

point, for example, INTEGER(2). ** MANTIS uses DECIMAL to read QUADWORD column data from the database in case they contain more

significant digits than a BIG variable can hold.

SQLDA function syntax for moving data from an SQLDA header element into your program

Use this SQLDA function to read header elements.

mantis-variable = SQLDA(sqlda-name,header-element)

mantis-variable

Description Required. Specifies the name into which the SQLDA header element is to be placed.

Format MANTIS variable or MANTIS array occurrence.

sqlda-name

Description Required. Specifies the name of a previously allocated SQLDA data structure.

Format MANTIS text expression.

header-element

Description Required. Specifies the name of the header element that you're reading.




No index value is permitted. You can read all header elements.

Example


TOTAL_NEEDED = SQLDA("SQLDA1","SQLN")

Move data from an SQLDA repeating element into your program

SQLDA function syntax for moving data from an SQLDA repeating element into your program

Use this SQLDA function to transfer data from a repeating element into a MANTIS variable in your program.

mantis-variable = SQLDA(sqlda-name, repeating-element, index)

mantis-variable

Description Required. Specifies the destination into which the SQLDA repeating element is to be placed.

Format MANTIS variable or array element reference.

sqlda-name

Description Required. Specifies the name of a previously allocated SQLDA.

Format MANTIS text expression. Standard MANTIS variable or MANTIS array element reference.

repeating-element

Description Required. Specifies the name of the repeating element to be read.


Consideration To fill out this element, see the table in the topic SQLDA repeating elements.

index

Description Required. Specifies the sequential occurrence of the repeating element to be read. The occurrence is relative to one, rather than zero; for example, the eighth occurrence of the repeating element has an index value of eight.

Format MANTIS numeric expression.



You can read all repeating elements. Data types between repeating elements and MANTIS variables must match.


Example


EMPLOYEE_NUMBER = SQLDA("SQLDA1","SQLHOSTVAR",1)

SQLDA repeating elements

ODBC and SUPRA SQLDA repeating elements The following tables list the SQLDA repeating elements. Use this table to complete the repeating-element syntax element in the SQLDA statement, in the topic Syntax to move data from an SQLDA repeating element into your program.

Element Function How Set/When Used

Results Updatable?

SQLCOLNAME SQL column name.

Set by DRDM as the result of a DESCRIBE; can be set by program.

A column or header name.

Yes

SQLCOLIO Indicates whether parameter is input or output.

Set by DRDM as the result of a DESCRIBE.

0 = input 1 = output

No

SQLCOLMODE Indicates whether null values are allowed.

Set as the result of a DESCRIBE.

0 = not allowed < > 0 = allowed No

No

SQLCOLTYPE Data type as it resides on the database. Code differs depending on whether it is set by SQLCOLTYPE or SQLHOSTVARTY*.

Set by DRDM as the result of a DESCRIBE.

INTEGER BIG DECIMAL TEXT

No SQLCOLTYPE 0 Fixed 1 Float 2 Character 3 Byte 4 Date 5 Time 6 String

SQLCOLLENGTH Total number of bytes used to store the data.

Set by DRDM as the result of a DESCRIBE or by MANTIS when data is transferred by SQLHOSTVAR.

INTEGER: 4 BIG/SMALL: 8 DECIMAL, TEXT: maximum column length when set by DESCRIBE MANTIS variable current length when set by SQLDA.

No


Element Function How Set/When Used

Results Updatable?

SQLCOLFRAC Number of decimal positions for FIXED column types.

Set by DRDM as the result of a DESCRIBE and not used by MANTIS since all numeric data is floating point.

-1 for FLOAT column types.

No

SQLHOSTIND Contains the value of the indicator variable.

Used to indicate the presence of null variables and truncated data. Set by DRDM during SQL function: can be set by your program.

= 0 Defined value; no errors < 0 Null value > 0 Original column length due to truncated value

Yes

SQLHOSTVARTY Contains the data type of the data in the SQLDA*.

Set by MANTIS when SQLHOSTVAR is used.

SQLHOSTVARTY** INTEGER 1—

Integer (4) BIG/SMALL 3—

Float (8) DECIMAL 5—

Fixed-point decimal

TEXT 15—Variable-length character string

No

SQLHOSTVAR Subfunction that physically transfers data between MANTIS data areas and the SQLDA data areas.

Used to transfer value of variable between database and MANTIS.

Data stored in MANTIS variable or SQLDA; SQLCOLTYPE and SQLCOLLENGTH set according to value being transferred when data is moved into SQLDA.

Yes

DB2, Oracle, and Oracle Rdb SQLDA repeating elements The following tables list the SQLDA repeating elements. Use this table to complete the repeating-element syntax element in the SQLDA statement, in the topic Syntax to move data from an SQLDA repeating element into your program.


Element Function How Set/When Used Results Updateable?

SQLNAME / SQLCOLNAME

SQL column name Can be set in the following ways: By the

database, as the result of a PREPARE INTO statement

By the database, as the result of a DESCRIBE statement

Column name Yes

SQLTYPE / SQLCOLTYPE

One of the following: Data type

in the database

Host-variable data type

Can be set in the following ways: By the



By MANTIS, prior to an EXECUTE statement

By MANTIS, prior to an OPEN statement

By MANTIS, prior to a FETCH statement

By the MANTIS SQLDA statement

See MANTIS SQL support data type conversion.

No



SQLLEN / SQLCOLLENGTH

One of the following: Maximum

number of bytes for a column in the database

Actual number of host-variable bytes




By MANTIS, prior to an EXECUTE statement




Results in one of the following: 4 for

numeric columns

8 for numeric columns

Maximum string length

Actual string length

No

SQLFRAC / SQLCOLFRAC

One of the following: For DB2.

Number of decimal places for DECIMAL and FLOAT.

For Oracle and Oracle Rdb. Number of decimal places for INTEGER, SMALLINT, or QUADWORD data types.




Number of places specified in the CREATE TABLE statement

No



SQLIND / SQLHOSTIND

The value of the NULL or MISSING indicator variable.


database, as the result of a FETCH statement


Results in one of the following: A value that

is less than or equal to -1

NULL A value that

is defined and addressed by SQLDATA

Yes

SQLDATA / SQLHOSTVAR

Address host-variable data.

Can be set in the following ways: By MANTIS,

prior to an EXECUTE statement




Results in one of the following: Address of

MANTIS variable in the MANTIS data work area

Address of MANTIS data after being copied or converted into work buffer

Yes

Cursors for prepared statements (Oracle and DB2 only) For MANTIS Dynamic SQL Support, cursor names are not known at the time of the PREPARE. This is because MANTIS executes interpretively. MANTIS resolves this problem by declaring cursors for all prepared statements that could possibly require them. These statements include:


SQL Programming Guide, P39-1381 103 Appendix: A. MANTIS SQL sample programs Section: Introduction to the MANTIS SQL sample programs

A. MANTIS SQL sample programs Introduction to the MANTIS SQL sample programs

Regarding the sample programs in this appendix, consider the following:

For clarity, these programs do not contain the following: - Error-checking logic - Display logic

These programs contain hard-coded employee information. Each static program has the same functionality as the dynamic program that

follows it.

You can access these example programs by running EXAMPLES:APPLICATIONS and, from the menu, selecting SQL EXAMPLES.

SQL Programming Guide, P39-1381 104 Appendix: A. MANTIS SQL sample programs Section: INSERT routines

INSERT routines

Static INSERT routine This program, which supports DB2, ODBC, Oracle, Oracle Rdb, and SUPRA, provides an example of a static SQL "INSERT" statement. It inserts one employee into an employee table.

ENTRY STATIC_INSERT

|

| THIS PROGRAM IS AN EXAMPLE OF A STATIC SQL "INSERT"

| STATEMENT. IT INSERTS ONE EMPLOYEE INTO AN EMPLOYEE

| TABLE.

|

BIG HIRE_DATE,BIRTH_DATE,JOB_CODE,SALARY,EDUCATION_LEVEL

TEXT EMPLOYEE_NUMBER(6),FIRST_NAME(20)

'MIDDLE_INITIAL(1),LAST_NAME(20)

TEXT PHONE_NUMBER(4),WORK_DEPARTMENT(3),SEX(1)

|

EMPLOYEE_NUMBER="000120"

FIRST_NAME="SEAN"

MIDDLE_INITIAL=" "

LAST_NAME="O'CONNELL"

BIRTH_DATE=421018

HIRE_DATE=631205

JOB_CODE=58

EDUCATION_LEVEL=14

SALARY=29250

PHONE_NUMBER="2167"

WORK_DEPARTMENT="A00"

SEX="M"

|

EXEC_SQL:| INSERT INTO FRED.TEMPL

| (EMPNO,

| FIRSTNME,

| MIDINIT,

| LASTNAME,

| BRTHDATE,

| HIREDATE,

| JOBCODE,

| EDUCLVL,

| SALARY,

| PHONENO,

| WORKDEPT,

| SEX)

| VALUES (:EMPLOYEE_NUMBER,


| :FIRST_NAME,

| :MIDDLE_INITIAL,

| :LAST_NAME,

| :BIRTH_DATE,

| :HIRE_DATE,

| :JOB_CODE,

| :EDUCATION_LEVEL,

| :SALARY,

| :PHONE_NUMBER,

| :WORK_DEPARTMENT,

| :SEX)

END

EXIT

Dynamic INSERT routine This program, which supports ODBC, DB2, Oracle, Oracle Rdb, and SUPRA, provides an example of a dynamic SQL "INSERT" statement. It inserts one employee into an employee table.

ENTRY DYNAMIC_INSERT

|

| THIS PROGRAM IS AN EXAMPLE OF A DYNAMIC SQL "INSERT"

| STATEMENT. IT INSERTS ONE EMPLOYEE INTO AN EMPLOYEE

| TABLE.

|

BIG HIRE_DATE,BIRTH_DATE,JOB_CODE,SALARY

BIG EDUCATION_LEVEL


TEXT MIDDLE_INITIAL(1),LAST_NAME(20)

TEXT PHONE_NUMBER(4),WORK_DEPARTMENT(3),SEX(1)

TEXT SQL_TEXT(254)

|


FIRST_NAME="SEAN"

MIDDLE_INITIAL=" "

LAST_NAME="O'CONNELL"

BIRTH_DATE=421018

HIRE_DATE=631205

JOB_CODE=58

EDUCATION_LEVEL=14

SALARY=29250

PHONE_NUMBER="2167"

WORK_DEPARTMENT="A00"

SEX="M"

|

SQL_TEXT="INSERT INTO FRED.TEMPL"


'"(EMPNO, FIRSTNME, MIDINIT, LASTNAME, BRTHDATE",

'"HIREDATE, JOBCODE, EDUCLVL, SALARY, PHONENO",

'"WORKDEPT, SEX)"

'"VALUES (?,?,?,?,?,?,?,?,?,?,?,?)"

|

EXEC_SQL:| PREPARE S1 FROM :SQL_TEXT

END

|

SQLDA("SQLDA1")=NEW

SQLDA("SQLDA1","SQLMAX")=12

EXEC_SQL:| DESCRIBE S1 INTO SQLDA1

END

SQLDA("SQLDA1","SQLDATA",1)=EMPLOYEE_NUMBER

SQLDA("SQLDA1","SQLDATA",2)=FIRST_NAME

SQLDA("SQLDA1","SQLDATA",3)=MIDDLE_INITIAL

SQLDA("SQLDA1","SQLDATA",4)=LAST_NAME

SQLDA("SQLDA1","SQLDATA",5)=BIRTH_DATE

SQLDA("SQLDA1","SQLDATA",6)=HIRE_DATE

SQLDA("SQLDA1","SQLDATA",7)=JOB_CODE

SQLDA("SQLDA1","SQLDATA",8)=EDUCATION_LEVEL

SQLDA("SQLDA1","SQLDATA",9)=SALARY

SQLDA("SQLDA1","SQLDATA",10)=PHONE_NUMBER

SQLDA("SQLDA1","SQLDATA",11)=WORK_DEPARTMENT

SQLDA("SQLDA1","SQLDATA",12)=SEX

|

EXEC_SQL:| EXECUTE S1 USING DESCRIPTOR SQLDA1

END

EXIT

SQL Programming Guide, P39-1381 107 Appendix: A. MANTIS SQL sample programs Section: UPDATE routines

UPDATE routines

A static UPDATE routine This program, which supports ODBC, DB2, Oracle, Oracle Rdb, and SUPRA, provides an example of a static SQL "UPDATE" statement. It updates one employee from an employee table.

ENTRY STATIC_UPDATE

|

| THIS PROGRAM IS AN EXAMPLE OF A STATIC SQL "UPDATE"

| STATEMENT. IT UPDATES ONE EMPLOYEE FROM AN EMPLOYEE

| TABLE.

|

BIG HIRE_DATE,BIRTH_DATE

TEXT EMPLOYEE_NUMBER(6)

TEXT FIRST_NAME(20),MIDDLE_INITIAL(1),LAST_NAME(20)

|


FIRST_NAME="JOHN"

MIDDLE_INITIAL="H"

LAST_NAME="DOE"

BIRTH_DATE=490113

HIRE_DATE=880120

|

EXEC_SQL

|

| UPDATE FRED.TEMPL

|

| SET FIRSTNME = :FIRST_NAME,

| MIDINIT = :MIDDLE_INITIAL,

| LASTNAME = :LAST_NAME,

| BRTHDATE = :BIRTH_DATE,

| HIREDATE = :HIRE_DATE

|

| WHERE EMPNO = :EMPLOYEE_NUMBER

END

EXIT

Dynamic UPDATE routines

ODBC and SUPRA dynamic UPDATE routine

This program, which supports ODBC and SUPRA, provides an example of a dynamic SQL "UPDATE" statement. It updates one employee from an employee table.

ENTRY DYNAMIC_UPDATE

|

| THIS PROGRAM (ODBC) IS AN EXAMPLE OF A DYNAMIC SQL "UPDATE"



| TABLE.

|


TEXT EMPLOYEE_NUMBER(6),FIRST_NAME(20),MIDDLE_INITIAL(1),LAST_NAME(20)

TEXT DA(18),DAPARM(8)

TEXT SQL_TEXT(254)

|


FIRST_NAME="JOHN"

MIDDLE_INITIAL="H"

LAST_NAME="DOE"

BIRTH_DATE=490113

HIRE_DATE=880120

|

SQL_TEXT="UPDATE FRED.TEMPL SET"

SQL_TEXT=SQL_TEXT+"FIRSTNME = ?, MIDINIT = ?, LASTNAME = ?,"

SQL_TEXT=SQL_TEXT+"BRTHDATE = ?, HIREDATE = ?"

SQL_TEXT=SQL_TEXT+"WHERE EMPNO = ?"

|


END

|

SQLDA("SQLDA1")=NEW

DA="SQLDA1"

DAPARM="SQLHOSTVAR"

SQLDA(DA,"SQLMAX")=6


END

SQLDA(DA,DAPARM,1)=FIRST_NAME

SQLDA(DA,DAPARM,2)=MIDDLE_INITIAL

SQLDA(DA,DAPARM,3)=LAST_NAME

SQLDA(DA,DAPARM,4)=BIRTH_DATE

SQLDA(DA,DAPARM,5)=HIRE_DATE

SQLDA(DA,DAPARM,6)=EMPLOYEE_NUMBER

|


END

EXIT

DB2 dynamic UPDATE routine

This program, which supports DB2, provides an example of a dynamic SQL "UPDATE" statement. It updates one employee from an employee table.



|

| THIS PROGRAM (DB2) IS AN EXAMPLE OF A DYNAMIC SQL "UPDATE"


| TABLE.

|


TEXT EMPLOYEE_NUMBER(6),FIRST_NAME(20),

'MIDDLE_INITIAL(1),LAST_NAME(20)


TEXT SQL_TEXT(254)

|


FIRST_NAME="JOHN"

MIDDLE_INITIAL="H"

LAST_NAME="DOE"

BIRTH_DATE=490113

HIRE_DATE=880120

|


'"FIRSTNME = ?, MIDINIT = ?, LASTNAME = ?,"

'"BRTHDATE = ?, HIREDATE = ?"

'"WHERE EMPNO = ?"

|


END

|

SQLDA("SQLDA1")=NEW

DA="SQLDA1"

DAPARM="SQLDATA"

SQLDA(DA,"SQLD")=6


END







|


END

EXIT


Oracle and Oracle Rdb dynamic UPDATE routine

This program, which supports Oracle and Oracle Rdb, provides an example of a dynamic SQL "UPDATE" statement. It updates one employee from an employee table.


|

| THIS PROGRAM IS AN EXAMPLE OF A DYNAMIC SQL "UPDATE"


| TABLE.

|


TEXT EMPLOYEE_NUMBER(6),FIRST_NAME(20),MIDDLE_INITIAL(1),LAST_NAME(20)


TEXT SQL_TEXT(254)

|


FIRST_NAME="JOHN"

MIDDLE_INITIAL="H"

LAST_NAME="DOE"

BIRTH_DATE=490113

HIRE_DATE=880120

|


'"FIRSTNME = ?, MIDINIT = ?, LASTNAME = ?,"

'"BRTHDATE = ?, HIREDATE = ?"

'"WHERE EMPNO = ?"

|


END

|

SQLDA("SQLDA1")=NEW

DA="SQLDA1"

DAPARM="SQLDATA"

SQLDA(DA,"SQLMAX")=6


END







|


END


EXIT

SQL Programming Guide, P39-1381 112 Appendix: A. MANTIS SQL sample programs Section: SELECT routines

SELECT routines

Static SELECT routine This program, which supports DB2, ODBC, Oracle, Oracle Rdb, and SUPRA, provides an example of a static SQL "SELECT" statement. It retrieves employee information for one employee, from an employee table.

ENTRY STATIC_SELECT

|

| THIS PROGRAM IS AN EXAMPLE OF A STATIC SQL "SELECT"

| STATEMENT. IT RETRIEVES EMPLOYEE INFORMATION FOR ONE

| EMPLOYEE FROM AN EMPLOYEE TABLE.

|

BIG HIRE_DATE,BIRTH_DATE,JOB_CODE,SALARY

BIG EDUCATION_LEVEL


TEXT MIDDLE_INITIAL(1),LAST_NAME(20)

TEXT WORK_DEPARTMENT(3),PHONE_NUMBER(3),SEX(1)


|

EXEC_SQL:| DECLARE C1 CURSOR FOR

| SELECT * FROM FRED.TEMPL


END

EXEC_SQL:| OPEN C1

END

EXEC_SQL:| FETCH C1 INTO :EMPLOYEE_NUMBER,

| :FIRST_NAME,

| :MIDDLE_INITIAL,

| :LAST_NAME,

| :WORK_DEPARTMENT,

| :PHONE_NUMBER,

| :HIRE_DATE,

| :JOB_CODE,

| :EDUCATION_LEVEL,

| :SEX,

| :BIRTH_DATE,

| :SALARY

END

EXEC_SQL:| CLOSE C1

END

EXIT


Dynamic SELECT routines

ODBC and SUPRA dynamic SELECT routine

This program, which supports ODBC and SUPRA, provides an example of a dynamic SQL "SELECT" statement. It retrieves employee information for one employee, from an employee table.

ENTRY DYNAMIC_SELECT

|

| THIS PROGRAM IS AN EXAMPLE OF A DYNAMIC SQL "SELECT"


| EMPLOYEE, FROM AN EMPLOYEE TABLE.

|





TEXT SQL_TEXT(254)

|


SQL_TEXT="SELECT * FROM FRED.TEMPL"

'"WHERE EMPNO = ?"

|


END

EXEC_SQL:| DECLARE C1 CURSOR FOR S1

END

EXEC_SQL:| OPEN C1 USING :EMPLOYEE_NUMBER

END

SQL_TEXT="FETCH C1 USING DESCRIPTOR"


END

SQLDA("SQLDA1")=NEW


END


END

EXEC_SQL:| CLOSE C1

END

|

EMPLOYEE_NUMBER=SQLDA("SQLDA1","SQLHOSTVAR",1)

FIRST_NAME=SQLDA("SQLDA1","SQLHOSTVAR",2)

MIDDLE_INITIAL=SQLDA("SQLDA1","SQLHOSTVAR",3)

LAST_NAME=SQLDA("SQLDA1","SQLHOSTVAR",4)

WORK_DEPARTMENT=SQLDA("SQLDA1","SQLHOSTVAR",5)

PHONE_NUMBER=SQLDA("SQLDA1","SQLHOSTVAR",6)


HIRE_DATE=SQLDA("SQLDA1","SQLHOSTVAR",7)

JOB_CODE=SQLDA("SQLDA1","SQLHOSTVAR",8)

EDUCATION_LEVEL=SQLDA("SQLDA1","SQLHOSTVAR",9)

SEX=SQLDA("SQLDA1","SQLHOSTVAR",10)

BIRTH_DATE=SQLDA("SQLDA1","SQLHOSTVAR",11)

SALARY=SQLDA("SQLDA1","SQLHOSTVAR",12)

EXIT

DB2, Oracle, and Oracle Rdb dynamic SELECT routine

This program, which supports DB2, Oracle, and Oracle Rdb, provides an example of a dynamic SQL "SELECT" statement. It retrieves employee information for one employee, from an employee table.

ENTRY DYNAMIC_SELECT

|

| THIS PROGRAM IS AN EXAMPLE OF A DYNAMIC SQL "SELECT"


| EMPLOYEE, FROM AN EMPLOYEE TABLE.

|





TEXT SQL_TEXT(254)

|


SQL_TEXT="SELECT * FROM FRED.TEMPL"

'"WHERE EMPNO = ?"

|


END

EXEC_SQL:| DECLARE C1 CURSOR FOR S1

END

EXEC_SQL:| OPEN C1 USING :EMPLOYEE_NUMBER

END

SQL_TEXT="FETCH C1 USING DESCRIPTOR"


END

SQLDA("SQLDA1")=NEW


END


END

EXEC_SQL:| CLOSE C1

END

|


EMPLOYEE_NUMBER=SQLDA("SQLDA1","SQLDATA",1)

FIRST_NAME=SQLDA("SQLDA1","SQLDATA",2)

MIDDLE_INITIAL=SQLDA("SQLDA1","SQLDATA",3)

LAST_NAME=SQLDA("SQLDA1","SQLDATA",4)

WORK_DEPARTMENT=SQLDA("SQLDA1","SQLDATA",5)

PHONE_NUMBER=SQLDA("SQLDA1","SQLDATA",6)

HIRE_DATE=SQLDA("SQLDA1","SQLDATA",7)

JOB_CODE=SQLDA("SQLDA1","SQLDATA",8)

EDUCATION_LEVEL=SQLDA("SQLDA1","SQLDATA",9)

SEX=SQLDA("SQLDA1","SQLDATA",10)

BIRTH_DATE=SQLDA("SQLDA1","SQLDATA",11)

SALARY=SQLDA("SQLDA1","SQLDATA",12)

EXIT

SQL Programming Guide, P39-1381 116 Appendix: A. MANTIS SQL sample programs Section: DELETE routines

DELETE routines

Static DELETE routine This program, which supports ODBC, DB2, Oracle, Oracle Rdb, and SUPRA, provides an example of a static SQL "DELETE" statement. It deletes one employee from an employee table.

ENTRY STATIC_DELETE

|

| THIS PROGRAM IS AN EXAMPLE OF A STATIC SQL "DELETE"

| STATEMENT. IT DELETES ONE EMPLOYEE FROM AN EMPLOYEE

| TABLE.

|


EMPLOYEE_NUMBER "000120"

EXEC_SQL

|

| DELETE FROM FRED.TEMPL

|


END

EXIT

Dynamic DELETE routine This program, which supports ODBC, DB2, Oracle, Oracle Rdb, and SUPRA, provides an example of a static SQL "DELETE" statement. It deletes one employee from an employee table.

For a DELETE routine, using an SQLDA is unnecessary because no data is transferred between the database system and the MANTIS program.

ENTRY DYNAMIC_DELETE

|

| THIS PROGRAM IS AN EXAMPLE OF A DYNAMIC SQL "DELETE"

| STATEMENT. IT DELETES ONE EMPLOYEE FROM AN EMPLOYEE

| TABLE.

|

TEXT EMPLOYEE_NUMBER(6),SQL_TEXT(254)

EMPLOYEE_NUMBER "000120"

SQL_TEXT="DELETE FROM FRED.TEMPL WHERE EMPNO = ?"

|

EXEC_SQL

|

| PREPARE S1 FROM :SQL_TEXT

|

END

EXEC_SQL

SQL Programming Guide, P39-1381 117 Appendix: A. MANTIS SQL sample programs Section: DELETE routines

|

| EXECUTE S1 USING :EMPLOYEE_NUMBER

|

END

EXIT

SQL Programming Guide, P39-1381 118 Appendix: A. MANTIS SQL sample programs Section: Dynamic QUERY-like functions

Dynamic QUERY-like functions

ODBC and SUPRA dynamic QUERY-like function This program, which supports ODBC and SUPRA, enables you to perform the following at your terminal:

1. Interactively execute SQL statements. 2. Display the column data resulting from the execution of those statements.

See the following sample code for a dynamic QUERY-like function:

ENTRY SQL_QUERY

|

| This example illustrates the use of dynamic SQL to

| perform a QUERY-like function.

|

| E.g.:

| INSERT INTO table VALUES (?,?,...)

| SELECT * FROM table

| SELECT * FROM table WHERE column > ?

| SELECT * FROM table INTO ?,?,... WHERE column = ?

| COMMIT WORK RELEASE is NOT recommended

|

TEXT STMT(255),TEXT_PARM(80),DA_CMD,DA_FETCH

DA_CMD="DA_CMD"

DA_FETCH="DA_FETCH"

SQLDA(DA_CMD)=NEW

SQLDA(DA_FETCH)=NEW

EXEC_SQL:|WHENEVER SQLERROR DO QHANDLER

END

|

WHILE NOT(FINISHED)

|

| Prompt for next SQL statement and execute it

|

STMT=""

SHOW "SQL>";:OBTAIN STMT

IF KEY<>"ENTER"OR STMT=""

FINISHED=TRUE

ELSE

UNPAD STMT BEFORE

STMT=UPPERCASE(STMT)

IF POINT(STMT-"?")=0:| Any host variables?

SQLDA(DA_CMD,"SQLN")=0

SQLDA(DA_CMD,"SQLD")=0

EXEC_SQL:|EXECUTE IMMEDIATE :STMT

END


ELSE:| Yes, use SQLDA

EXEC_SQL:|PREPARE S1 INTO DA_CMD FROM :STMT

END

IF SQLDA(DA_CMD,"SQLN")>SQLDA(DA_CMD,"SQLD")

DO SQLDA_INPUT(DA_CMD)

END

EXEC_SQL:|EXECUTE S1 USING DESCRIPTOR DA_CMD

END

END

IF SQLCA("SQLCODE")=0

IF STMT(1,6)="SELECT"AND POINT(STMT-"INTO")=0

|

| A SELECT without an INTO clause:

| FETCH all rows from result table

|

WHILE SQLCA("SQLCODE")=0

EXEC_SQL:|FETCH USING DESCRIPTOR DA_FETCH

END


DO SQLDA_OUTPUT(DA_FETCH)

END

END

ELSE:| No result table to process

IF SQLDA(DA_CMD,"SQLD")>0 AND SQLCA("SQLCODE")=0

DO SQLDA_OUTPUT(DA_CMD)

END

END

END

END

END

EXIT

|

| Allow continuation after failure to execute SQL

| statement

ENTRY QHANDLER

SHOW "*** SQL ERROR CODE =";SQLCA("SQLCODE")

SHOW "***";SQLCA("SQLERRMC")

SHOW "*** Press RETURN to continue, CANCEL to stop";:WAIT

IF KEY<>"ENTER"

STOP

END

EXIT

|

| Process Input host-variable parameters (?)

|


ENTRY SQLDA_INPUT(DA)

I=0

WHILE I<SQLDA(DA,"SQLN")

I=I+1

IF SQLDA(DA,"SQLCOLIO",I)=0:| An Input parameter

SHOW "Enter Input parameter";I;";";

WHEN SQLDA(DA,"SQLCOLTYPE",I)<2

OBTAIN BIG_PARM

SQLDA(DA,"SQLHOSTVAR",I)=BIG_PARM

WHEN SQLDA(DA,"SQLCOLTYPE",I)>2

TEXT BUFFER

OBTAIN TEXT_PARM

SQLDA(DA,"SQLHOSTVAR",I)=TEXT_PARM

END

END

END

EXIT

|

| Process Output host-variable parameters

|

ENTRY SQLDA_OUTPUT(DA)

I=0

WHILE I<SQLDA(DA,"SQLN")

I=I+1

IF SQLDA(DA,"SQLCOLIO",I)=1:| An Output parameter

SHOW SQLDA(DA,"SQLHOSTVAR",I),

END

END

SHOW

EXIT

DB2 dynamic QUERY-like function This program, which supports DB2, enables you to perform the following:

1. Interactively execute SQL statements 2. At your terminal, display the column data resulting from the execution of those

statements


ENTRY DB2_QUERY

CLEAR

HEAD "DYNAMIC EXAMPLE"

|



|

TEXT STMT(80),TMP(6),DA


PROGRAM DB2_SHOW_TABLE("EXAMPLES:DB2_SHOW_TABLE","CASINO")

DA="DA"

SQLDA(DA)=NEW

EXEC_SQL:| WHENEVER SQLERROR DO QHANDLER

END

WHILE NOT(FINISHED):| Prompt SQL statements

STMT="":ERROR=FALSE

SHOW "SQL>";:OBTAIN STMT


FINISHED=TRUE

ELSE

UNPAD STMT BEFORE

TMP=UPPERCASE(STMT(1,6))

IF TMP<>"SELECT"

EXEC_SQL:| EXECUTE IMMEDIATE :STMT

END

ELSE

EXEC_SQL:| PREPARE S1 FROM :STMT

END

IF NOT(ERROR)

EXEC_SQL:| DESCRIBE S1 INTO DA

END


DO DB2_SHOW_TABLE(STMT)

END

END

END

END

END

EXIT

|

| Allow continuation after failure to execute SQL statement

|

ENTRY QHANDLER


SHOW "*** SQL MESSAGE =";SQLCA("SQLERRMC")

ERROR=TRUE

SHOW "*** Press RETURN to continue";:WAIT

EXIT

Oracle dynamic QUERY-like function This program, which supports Oracle, enables you to perform the following at your terminal:

1. Interactively execute SQL statements. 2. Display the column data resulting from the execution of those statements.



ENTRY VMS_QUERY

|



|

TEXT STMT(255),TEXT_PARM(80),DA_MARKERS,DA_SELECT

PROGRAM VMS_SHOW_TABLE("EXAMPLES:VMS_SHOW_TABLE","CASINO")

DA_MARKERS="DA_MARKERS"

DA_SELECT="DA_SELECT"

SQLDA(DA_MARKERS)=NEW

SQLDA(DA_SELECT)=NEW

| Define SQL Error Handler - QHANDLER


END

| Prompt SQL statements and execute them

WHILE NOT(FINISHED):

STMT="":ERROR=FALSE

SHOW "SQL>":OBTAIN STMT


FINISHED=TRUE

ELSE

EXEC_SQL:| PREPARE S1 SELECT LIST INTO DA_SELECT FROM :STMT

END

IF NOT(ERROR)

EXEC_SQL:| DESCRIBE S1 MARKERS INTO DA_MARKERS

END


IF SQLDA(DA_SELECT,"SQLD")>0:| If it's a SELECT STATEMENT

DO VMS_SHOW_TABLE(STMT)

ELSE

IF SQLDA(DA_MARKERS,"SQLD")>0

DO SQLDA_INPUT(DA_MARKERS)

EXEC_SQL:| EXECUTE S1 USING DESCRIPTOR DA_MARKERS

END

ELSE:| No host variable parameters


END

END

END

END

END

END

END


EXIT

|


ENTRY QHANDLER



ERROR=TRUE

SHOW "*** press RETURN to continue";:WAIT

EXIT

|


NINPUT=SQLDA(DA,"SQLD")

BIG NVAL:TEXT TYPE(15),TVAL(50)

I=1

WHILE I<=NINPUT

DO SQLTYPE(DA,I,TYPE)

SHOW "Input";I;"("TYPE(2)")";

IF TYPE(1,1)="N"

OBTAIN NVAL:SQLDA(DA,"sqldata",I)=NVAL

SQLDA(DA,"SQLDATA",I)=NVAL

ELSE

OBTAIN TVAL:SQLDA(DA,"sqldata",I)=TVAL

SQLDA(DA,"SQLDATA",I)=TVAL

END

I=I+1

END

EXIT

|

ENTRY SQLTYPE(DA,VARX,TYPE)

TC=SQLDA(DA,"SQLTYPE",I)

WHEN TC=449

TYPE="TVARCHAR"

WHEN TC=453

TYPE="TCHAR"

WHEN TC=481

TYPE="NFLOAT"

WHEN TC=485

TYPE="NDECIMAL"

WHEN TC=497

TYPE="NINTEGER"

WHEN TC=501

TYPE="NSMALLINT"

WHEN TC=503

TYPE="TDATE"

WHEN TC=505


TYPE="NQUADWORD"

END WHEN

EXIT

Oracle Rdb dynamic QUERY-like function This program, which supports Oracle Rdb, enables you to perform the following at your terminal:

Interactively execute SQL statements. Display the column data resulting from the execution of those statements.


ENTRY RDB_QUERY

|



|

TEXT STMT(255),TEXT_PARM(80),DA_MARKERS,DA_SELECT

PROGRAM RDB_SHOW_TABLE("EXAMPLES:RDB_SHOW_TABLE","CASINO")

DA_MARKERS="DA_MARKERS"

DA_SELECT="DA_SELECT"

SQLDA(DA_MARKERS)=NEW

SQLDA(DA_SELECT)=NEW

| Define SQL Error Handler - QHANDLER


END

| Prompt SQL statements and execute them

WHILE NOT(FINISHED):

STMT="":ERROR=FALSE

SHOW "SQL>":OBTAIN STMT


FINISHED=TRUE

ELSE

EXEC_SQL:| PREPARE S1 SELECT LIST INTO DA_SELECT FROM :STMT

END

IF NOT(ERROR)

EXEC_SQL:| DESCRIBE S1 MARKERS INTO DA_MARKERS

END


IF SQLDA(DA_SELECT,"SQLD")>0:| If it's a SELECT STATEMENT

DO RDB_SHOW_TABLE(STMT)

ELSE

IF SQLDA(DA_MARKERS,"SQLD")>0

DO SQLDA_INPUT(DA_MARKERS)

EXEC_SQL:| EXECUTE S1 USING DESCRIPTOR DA_MARKERS

END


ELSE:| No host variable parameters


END

END

END

END

END

END

END

EXIT


ENTRY QHANDLER



ERROR=TRUE

SHOW "*** press RETURN to continue";:WAIT

EXIT

|


NINPUT=SQLDA(DA,"SQLD")

BIG NVAL:TEXT TYPE(15),TVAL(50)

I=1

WHILE I<=NINPUT

DO SQLTYPE(DA,I,TYPE)

SHOW "Input";I;"("TYPE(2)")";

IF TYPE(1,1)="N"

OBTAIN NVAL:SQLDA(DA,"sqldata",I)=NVAL

SQLDA(DA,"SQLDATA",I)=NVAL

ELSE

OBTAIN TVAL:SQLDA(DA,"sqldata",I)=TVAL

SQLDA(DA,"SQLDATA",I)=TVAL

END

I=I+1

END

EXIT

|

ENTRY SQLTYPE(DA,VARX,TYPE)

TC=SQLDA(DA,"SQLTYPE",I)

WHEN TC=449

TYPE="TVARCHAR"

WHEN TC=453

TYPE="TCHAR"

WHEN TC=481

TYPE="NFLOAT"

WHEN TC=485


TYPE="NDECIMAL"

WHEN TC=497

TYPE="NINTEGER"

WHEN TC=501

TYPE="NSMALLINT"

WHEN TC=503

TYPE="TDATE"

WHEN TC=505

TYPE="NQUADWORD"

END WHEN

EXIT

SQL Programming Guide, P39-1381 127 Appendix: A. MANTIS SQL sample programs Section: Dynamic column SELECT routines

Dynamic column SELECT routines

ODBC and SUPRA dynamic column SELECT routine This program, which supports ODBC, uses dynamically executed statements to retrieve, from a user-specified table, each column's:

Name Type Length First-row data

See below:

ENTRY SQL_LIST_COLUMNS

|

| THIS PROGRAM LISTS COLUMNS BASED ON TABLE NAME

|

TEXT TABLE_NAME(32)

TEXT SQL_FUNCTION(100):| Contains the SQL statement

SHOW "PLEASE ENTER TABLE NAME:"

OBTAIN TABLE_NAME

SQL_FUNCTION="SELECT * FROM "+TABLE_NAME:| Creates the SQL statement

EXEC_SQL

| EXECUTE IMMEDIATE :SQL_FUNCTION

END:| Creates the result set

SQL_FUNCTION="FETCH USING DESCRIPTOR"

EXEC_SQL:| PREPARE S1 FROM :SQL_FUNCTION

END:| Prepares the SQL statement

SQLDA("SQLDA1")=NEW


END:| Returns table column data into the SQLDA


END:| Retrieves first row of data from the table

COUNTER=1

SHOW "COLUMN NAME",AT(25),"TYPE",AT(45),"LENGTH",AT(55),"DATA"

WHILE COUNTER<SQLDA("SQLDA1","SQLD")

SHOW SQLDA("SQLDA1","SQLCOLNAME",COUNTER):| Displays returned data

'AT(25),SQLDA("SQLDA1","SQLCOLTYPE",COUNTER)

'AT(45),SQLDA("SQLDA1","SQLCOLLENGTH",COUNTER)

'AT(55),SQLDA("SQLDA1","SQLHOSTVAR",COUNTER)

COUNTER=COUNTER+1

END

WAIT


EXIT

DB2, Oracle, and Oracle Rdb dynamic column SELECT routine This program, which supports DB2 and Oracle, uses dynamically executed statements to retrieve, from a user-specified table, each column's:

Name Type Length First-row data

See below:

ENTRY SQL_LIST_COLUMNS

|

| THIS PROGRAM LISTS COLUMNS BASED ON TABLE NAME

|

TEXT TABLE_NAME(32)

TEXT SQL_FUNCTION(100):| Contains the SQL statement

COUNTER=1

SHOW "PLEASE ENTER TABLE NAME:"

OBTAIN TABLE_NAME

SQL_FUNCTION="SELECT * FROM "+TABLE_NAME:| Creates the SQL statement

EXEC_SQL

| EXECUTE IMMEDIATE :SQL_FUNCTION

END:| Creates the result set

SQL_FUNCTION="FETCH USING DESCRIPTOR"

EXEC_SQL:| PREPARE S1 FROM :SQL_FUNCTION

END:| Prepares the SQL statement

SQLDA("SQLDA1")=NEW


END:| Returns table column data into the SQLDA


END:| Retrieves first row of data from the table

COUNTER=COUNTER+1

SHOW "COLUMN NAME",AT(25),"TYPE",AT(45),

'"LENGTH",AT(55),"DATA"

WHILE COUNTER<SQLDA("SQLDA1","SQLD")

SHOW SQLDA("SQLDA1","SQLCOLNAME",COUNTER):| Displays returned data

'AT(25),SQLDA("SQLDA1","SQLTYPE",COUNTER)

'AT(45),SQLDA("SQLDA1","SQLLENGTH",COUNTER)

'AT(55),SQLDA("SQLDA1","SQLDATA",COUNTER)

COUNTER=COUNTER+1


END

WAIT

EXIT

SQL Programming Guide, P39-1381 130 Appendix: B. Features of SQL not supported by MANTIS SQL Support Section: Host variables cannot be specified in a SELECT list

B. Features of SQL not supported by MANTIS SQL Support Host variables cannot be specified in a SELECT list

Consider the following example, which is invalid because it specifies VZ as a host variable in a SELECT list:

SELECT A,:VZ,C

INTO :VA,:VB,:VC

SQL Programming Guide, P39-1381 131 Appendix: B. Features of SQL not supported by MANTIS SQL Support Section: Exact syntax-error line number reference is not always supported

Exact syntax-error line number reference is not always supported In the execution of an SQL statement, once control is transferred to the database system, MANTIS cannot keep track of where the error was encountered. For the rest of this bullet point, consider the following sample code:

X=X+1

EXEC_SQL

|SELECT A,B,C

|INTO :VA,:VB),:VC <--- Error: the ")" on ":VB)".

|FROM TABLE.1

|WHERE A=1

END

X=X-VA

An error occurs in the INTO clause of the preceding sample code. In this INTO clause, there should not be a right-parenthesis. MANTIS SQL Support reports this error differently for a bound program than for an unbound program:

For a bound program. In the FAULT, MANTIS points to the line of the last SQL statement (the line immediately preceding the END statement).

For an unbound program. In the FAULT, MANTIS points to the last line in the program block.

See below:

X=X+1

EXEC_SQL

|SELECT A,B,C

|INTO :VA,:VB),:VC <--- Error: the ")" on ":VB)".

|FROM TABLE.1

|WHERE A=1 <--- FAULTS display this line for a bound program.

END <--- FAULTS display this line for an unbound program.

X=X-VA

SQL Programming Guide, P39-1381 132 Appendix: B. Features of SQL not supported by MANTIS SQL Support Section: Using a single instruction, you cannot copy the contents of one SQLDA structure into another

Using a single instruction, you cannot copy the contents of one SQLDA structure into another

Using a single instruction, you cannot implicitly copy the contents of one SQLDA data structure into another. For example, MANTIS SQL Support doesn't permit the following statement:

SQLDA("NAME2") = SQLDA("NAME1")

However, you can individually pass each element of one SQLDA data structure to the corresponding element of a different SQLDA data structure.

SQL Programming Guide, P39-1381 133 Appendix: B. Features of SQL not supported by MANTIS SQL Support Section: MANTIS programs with dynamic SQL statements are not portable to or from mainframe MANTIS

MANTIS programs with dynamic SQL statements are not portable to or from mainframe MANTIS

MANTIS programs containing dynamic SQL statements are not portable between MANTIS SQL Support for the MANTIS Server for z/OS and z/VSE, and MANTIS SQL Support for the MANTIS Server (which runs on the supported Common platform operating systems).

Although you cannot port programs containing dynamic SQL statements between the two systems, you can port programs containing static embedded SQL between the two systems.

SQL Programming Guide, P39-1381 134 Appendix: C. Differences between MANTIS SQL Support and SQL in COBOL Section: MANTIS programs with dynamic SQL statements are not portable to or from mainframe MANTIS

C. Differences between MANTIS SQL Support and SQL in COBOL

SQL in MANTIS SQL Support is very similar to SQL in third-generation languages such as FORTRAN and COBOL.

For convenience, this guide refers to all third-generation SQL implementations as "SQL in COBOL."

However, there are some differences, which this appendix summarizes. More information is provided in the sections linked below.

Consider the following differences between MANTIS SQL Support and SQL in COBOL:

MANTIS SQL Support permits no MANTIS comments (that are not all or part of an SQL statement) within an EXEC_SQL-END block. In a MANTIS program, you must embed an SQL statement as a standard MANTIS comment and surround the SQL statement with an EXEC_SQL-END block. MANTIS SQL Support considers all comments within this block to be SQL statement text. For example, consider the following sample code in the EXEC_SQL-END block: EXEC_SQL

| SELECT SALARY

| INTO :EMPL_SAL



END

COBOL, however, permits comments within an EXEC_SQL-END block.

Accessing SQLCA elements. MANTIS SQL Support accesses SQLCA elements through the SQLCA statement and the SQLCA function, while SQL in COBOL accesses SQLCA elements as data items. For more information, see the section titled SQLCA function and SQLCA statement.

Accessing elements in SQLDA data structures. MANTIS SQL Support accesses SQLDA elements through the SQLDA statement and the SQLDA function, while SQL in COBOL accesses SQLDA elements as data items. For more information, see the following topics: - Scope of cursors, statements, and SQLDA data structures under ODBC and

SUPRA - Scope of cursors, statements, and SQLDA data structures under DB2, Oracle,

and Oracle Rdb Message sources. In a MANTIS SQL Support application, messages come to you from

three sources: - MANTIS nucleus - MANTIS SQL Support - Database system

To find detailed explanations for, and actions to take in response to, MANTIS SQL Support messages, refer to MANTIS Messages and Codes, P39-1331.

SQL Programming Guide, P39-1381 135 Appendix: C. Differences between MANTIS SQL Support and SQL in COBOL Section: MANTIS programs with dynamic SQL statements are not portable to or from mainframe MANTIS

SQLCA and SQLDA functions vs. SQL INCLUDE statements. MANTIS SQL Support uses the SQLCA and SQLDA functions where SQL in COBOL would use SQL INCLUDE statements. (MANTIS SQL Support does not support an SQL INCLUDE statement; INCLUDE denotes a preprocessor action.) For more information on: - SQLCA—See the section titled SQLCA function and SQLCA statement. - SQLDA—See the following topics:

o Scope of cursors, statements, and SQLDA data structures under ODBC o Scope of cursors, statements, and SQLDA data structures under DB2

DECLARE statements. In MANTIS SQL Support, unlike in SQL in COBOL, DECLARE statements are unnecessary for tables and views.

In the SQL WHENEVER statement. See Differences between WHENEVER statement in MANTIS SQL Support and WHENEVER statement in SQL in COBOL.

SQL Programming Guide, P39-1381 136 Appendix: D. Differences between MANTIS and SQL Section: MANTIS programs with dynamic SQL statements are not portable to or from mainframe MANTIS

D. Differences between MANTIS and SQL

Consider the following differences between MANTIS and SQL:

SQL and MANTIS use different character-string-constant delimiters. In MANTIS, double quotes (") delimit character-string constants. However, in SQL, apostrophes (') delimit character-string constants.

SQL and MANTIS use different data types. This requires conversion between the two kinds of data types. Permitted data type conversions are listed in the following topics: - Data conversion between MANTIS SQL Support and ODBC databases - Data conversion between MANTIS SQL Support and DB2 databases - Data conversion between MANTIS SQL Support and the Oracle database - Data conversion between MANTIS SQL Support and SUPRA databases - Data conversion between MANTIS SQL support and Oracle Rdb databases

SQL supports many more data types than MANTIS. Only data-type codes for MANTIS-compatible data types are returned in the SQLCOLTYPE element of an SQLDA data structure. Valid data types are therefore limited to those listed in the topic SQLCA elements.

SQL Programming Guide, P39-1381 137 Index

Index C

Connect to and disconnect from a database

Connect to and disconnect from a non-mainframe DB2 database

Explicitly connect to a DB2 server using MANTIS variables for user name and password 28

Explicitly connect to a non-mainframe DB2 server named SAMPLE 28

Explicitly connect to a non-mainframe DB2 server using all default values 27

Explicitly or implicitly connect to a non-mainframe DB2 database 27

Explicitly or implicitly disconnect from a non-mainframe DB2 database 28

Possible causes of disconnection from a non-mainframe DB2 database 28

Connect to and disconnect from an ODBC database

Explicitly connect to an ODBC data source 25

Explicitly or implicitly disconnect from an ODBC database 25

Possible causes of disconnection from an ODBC database 25

Connect to and disconnect from an Oracle database

Connection to an Oracle database and multiple-session support 30

Explicitly or implicitly connect to an Oracle database 30

Explicitly or implicitly disconnect from an Oracle database 31

Possible causes of disconnection from an Oracle database 31

Connect to or disconnect from a SUPRA database

Connection to the SUPRA database and multiple session support 32

Explicitly or implicitly connect to a SUPRA database 32

Explicitly or implicitly disconnect from a SUPRA database 33

OpenVMS connection consideration 32

Possible causes of disconnection from a SUPRA database 33

Connect to or disconnect from an Oracle Rdb database

Automatically connect to the Oracle Rdb database identified by SQL$DATABASE 34

Define MANTIS logical MANTIS_RDI_IF to connect to an Oracle Rdb database 34

Explicitly or implicitly disconnect from an Oracle Rdb database 35

MANTIS interface to Rdb 34

D

Data conversion between MANTIS SQL Support and supported databases

Data conversion between MANTIS SQL Support and DB2 databases 48

Data conversion between MANTIS SQL Support and ODBC databases 47

Data conversion between MANTIS SQL Support and Oracle database 49

Data conversion between MANTIS SQL support and Oracle Rdb databases 51

Data conversion between MANTIS SQL Support and SUPRA databases 50

Differences between MANTIS and SQL 136

Differences between MANTIS SQL Support and SQL in COBOL 134

Dynamic SQL in MANTIS SQL Support

Dynamic SQL overview Auto-cursor FETCH statements

(DB2_ Oracle_ and Oracle Rdb only) 78

DB2 dynamic SQL sample code for creating an SQLDA data structure 78

Defining data about SQL statements and host variables 76

Dynamic SQL definition 76 Executing a statement

dynamically 78


ODBC_ Oracle_ and SUPRA dynamic SQL sample code for creating an SQLDA data structure 79

Principal statements for dynamically executing SQL statements 76

SQL statements that you cannot execute dynamically (DB2_ Oracle_ and Oracle Rdb only) 77

SQLDA data structure 76 SQL data structure

Allocate an SQLDA data structure 83

Cursors for prepared statements (Oracle and DB2 only) 102

Deallocate an SQLDA data structure 84

Introduction to the SQLDA data structure 81

Move data from an SQLDA repeating element into your program

DB2, Oracle, and Oracle Rdb SQLDA repeating elements 99

ODBC and SUPRA SQLDA repeating elements 98

SQLDA function syntax for moving data from an SQLDA repeating element into your program 97

Move data from your program into an SQLDA header element

SQLDA header elements 87

SQLDA statement for moving data from your program into an SQLDA header element 85

Move data from your program into an SQLDA repeating element

DB2 MANTIS SQL Support data-type conversion 94

ODBC MANTIS SQL Support data-type conversion 94

Oracle MANTIS SQL Support data-type conversion 95

Oracle Rdb MANTIS SQL Support data-type conversion 96

SQLDA statement syntax for moving data from your program into an SQLDA header element 89

SUPRA MANTIS SQL Support data-type conversion 95

SQLDA function syntax for moving data from an SQLDA header element into your program 96

Who should read this chapter? 75

F

Features 130, 131, 132 Features of SQL not supported by

MANTIS SQL Support MANTIS programs with dynamic

SQL statements are not portable to or from mainframe MANTIS 133

H

Host variables (non-mainframe) (Oracle only) Oracle array-

processing support 43 Declare host variables 41 Host variables as parameters of

SQL statements 43 Input host variables 42 Introduction to host variables 41 MANTIS data types vs. SQL data

types 43 Output host variables 42 Types of host variables 41 Use host variables to reference

MANTIS array values 43

I

Indicator variables (non-mainframe)

Declare indicator variables 45 Introduction to indicator

variables 45 With SELECT or FETCH_ use

indicator variable for columns with possible NULL values 46

M

MANTIS SQL sample programs DB2 dynamic QUERY-like function

120 DB2 dynamic UPDATE routine 108 DB2, Oracle, and Oracle Rdb

dynamic SELECT routine 114 Dynamic INSERT routine 105


Introduction to the MANTIS SQL sample programs 103

ODBC and SUPRA dynamic QUERY-like function 118

ODBC and SUPRA dynamic SELECT routine 113

ODBC and SUPRA dynamic UPDATE routine 107

Oracle and Oracle Rdb dynamic UPDATE routine 110

Oracle dynamic QUERY-like function 121

Oracle Rdb dynamic QUERY-like function 124

Static DELETE routine 116 Static INSERT routine 104 Static SELECT routine 112 Static UPDATE routine 107

MANTIS SQL Support overview Differences between SQL in

MANTIS and SQL in COBOL 17 Embedding SQL statements in a

MANTIS application program 15

Introduction to MANTIS SQL Support 13

Logical names 18 MANTIS SQL Support and non-SQL

MANTIS applications 14 Security in MANTIS SQL support

20 Static and dynamic SQL 19 Variables in MANTIS SQL Support

16

P

Programming considerations for SQL

COMMIT/ROLLBACK in SQL and COMMIT/RESET in MANTIS SQL Support 72

Introduction to SQL programming considerations 52

MANTIS SQL Support and SQL statements

How MANTIS SQL Support processes SQL statements 53

SQL statements and cursors as SQL entities 53

Scope of cursors, statements, and SQLDA data structures

Scope of cursors, statements, and SQLDA data structures under DB2, Oracle, and Oracle Rdb 56

Scope of cursors, statements, and SQLDA data structures under ODBC and SUPRA 56

SQL FINISH statement (ODBC and SUPRA only) 65

SQL SET DBNAME statement (ODBC_ SUPRA_ and Oracle only) 66

SQL WHENEVER statement Declarative (COBOL) vs.

interpretive (MANTIS) WHENEVER statements

Declarative WHENEVER statement for SQL embedded in COBOL 63

Interpretive WHENEVER statement for SQL embedded in MANTIS 64

Scope of the WHENEVER statement 64

When the difference between MANTIS SQL Support and SQL in COBOL is important 64

Differences between WHENEVER statement in MANTIS SQL Support and WHENEVER statement in SQL in COBOL 60

Quick reference for WHENEVER conditions and default actions 63

Sample code for DO, FAULT, and CONTINUE 63

Syntax for MANTIS SQL Support WHENEVER statement 60

SQLCA function and SQLCA statement

DBNAME_ an additional element for the SQLCA statement (ODBC_ Oracle_ and Oracle Rdb only) 70

DBTYPE_ an additional element for the SQLCA statement 70

SQLCA elements 68 SQLCA in SQL in COBOL vs.

SQLCA in MANTIS SQL Support 67

SQLCA syntax 67 SQLERRMC_ an additional

element for the SQLCA statement 71

SQL-related error messages 74 Using the MANTIS EXEC_SQL

statement for multiple-session support 58

Varying line numbers associated with an EXEC_SQL-END block

Introduction to varying line numbers associated with an EXEC_SQL-END block 54


Line number associated with an EXEC_SQL-END block in a bound program 54

Line number associated with an EXEC_SQL-END block in an unbound program 54

S

Software requirements Software requirements for using

MANTIS SQL Support with non-mainframe DB2 9

Software requirements for using MANTIS SQL Support with non-mainframe SUPRA 11

Software requirements for using MANTIS SQL Support with ODBC

Operating systems on which the MANTIS Server supports ODBC 8

Special ODBC support consideration for a MANTIS Server on Android or iOS 8

Special ODBC support requirement for a MANTIS Server on Linux or UNIX 8

Software requirements for using MANTIS SQL Support with Oracle 10

Software requirements for using MANTIS SQL Support with Oracle Rdb 12

SQL statements, embedding in MANTIS programs

Host variables (Oracle only) Oracle array-

processing support 43 Declare host variables 41 Host variables as parameters

of SQL statements 43 Input host variables 42 Introduction to host variables

41 MANTIS data types vs. SQL

data types 43 Output host variables 42 Types of host variables 41 Use host variables to

reference MANTIS array values 43

Indicator variables Declare indicator variables 45 Introduction to indicator

variables 45 With SELECT or FETCH_ use

indicator variable for columns with possible NULL values 46

Introduction to embedding SQL statements in a MANTIS program 36

Rules for embedding SQL statements in a MANTIS program

A MANTIS comment is permitted to be on the same line as the END in an EXEC_SQL-END block 40

Apart from the SQL statement_ do not include any other MANTIS statements in an EXEC_SQL-END block 38

Do not place a comment or a MANTIS statement on the same line as an SQL statement 38

Embed an SQL statement as a standard MANTIS comment 37

Follow the standard MANTIS comment rules 37

Follow the standard SQL syntax rules 37

If desired_ split an SQL statement across multiple comment lines within an EXEC_SQL-END block 39

If you place a MANTIS statement on the same line as the END in an EXEC_SQL-END block_ MANTIS does not execute that statement 40

If you use a colon to attach an SQL statement to an EXEC_SQL statement_ that SQL statement exists within the EXEC_SQL-END block 40

In an SQL statement_ use as many spaces as desired 39

Place an SQL statement within an EXEC_SQL-END block 37

Place only one SQL statement within an EXEC_SQL-END block 37

Within an EXEC_SQL-END block_ use a colon to represent a host variable 39

System maintenance in MANTIS SQL Support

Connect to a database 22 Introduction to system

maintenance 21 MANTIS SQL options 23 Update the MANTIS User profile

with the default SQL DBTYPE 24

sql programming guide

Documents