The New z/VSE Database Connector (DBCLI)

IBM System z – z/VSE – Live Virtual Class

The New z/VSE Database Connector
(DBCLI)
Ingo Franzki
ifranzki@de.ibm.com

© 2012 IBM Corporation


Trademarks
The following are trademarks of the International Business Machines Corporation in the United States, other countries, or both.

Not all common law marks used by IBM are listed on this page. Failure of a mark to appear does not mean that IBM does not use the mark nor does it mean that the product is not
actively marketed or is not significant within its relevant market.
Those trademarks followed by ® are registered trademarks of IBM in the United States; all others are trademarks or common law marks of IBM in the United States.

For a complete list of IBM Trademarks, see www.ibm.com/legal/copytrade.shtml:

*, AS/400®, e business(logo)®, DBE, ESCO, eServer, FICON, IBM®, IBM (logo)®, iSeries®, MVS, OS/390®, pSeries®, RS/6000®, S/30, VM/ESA®, VSE/ESA,
WebSphere®, xSeries®, z/OS®, zSeries®, z/VM®, System i, System i5, System p, System p5, System x, System z, System z9®, BladeCenter®

The following are trademarks or registered trademarks of other companies.

Adobe, the Adobe logo, PostScript, and the PostScript logo are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States, and/or other countries.
Cell Broadband Engine is a trademark of Sony Computer Entertainment, Inc. in the United States, other countries, or both and is used under license therefrom.
Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both.
Intel, Intel logo, Intel Inside, Intel Inside logo, Intel Centrino, Intel Centrino logo, Celeron, Intel Xeon, Intel SpeedStep, Itanium, and Pentium are trademarks or registered trademarks of Intel
Corporation or its subsidiaries in the United States and other countries.
UNIX is a registered trademark of The Open Group in the United States and other countries.
Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both.
ITIL is a registered trademark, and a registered community trademark of the Office of Government Commerce, and is registered in the U.S. Patent and Trademark Office.
IT Infrastructure Library is a registered trademark of the Central Computer and Telecommunications Agency, which is now part of the Office of Government Commerce.
* All other products may be trademarks or registered trademarks of their respective companies.

Notes:
Performance is in Internal Throughput Rate (ITR) ratio based on measurements and projections using standard IBM benchmarks in a controlled environment. The actual throughput that any user will
experience will vary depending upon considerations such as the amount of multiprogramming in the user's job stream, the I/O configuration, the storage configuration, and the workload processed.
Therefore, no assurance can be given that an individual user will achieve throughput improvements equivalent to the performance ratios stated here.
IBM hardware products are manufactured from new parts, or new and serviceable used parts. Regardless, our warranty terms apply.
All customer examples cited or described in this presentation are presented as illustrations of the manner in which some customers have used IBM products and the results they may have achieved. Actual
environmental costs and performance characteristics will vary depending on individual customer configurations and conditions.
This publication was produced in the United States. IBM may not offer the products, services or features discussed in this document in other countries, and the information may be subject to change without
notice. Consult your local IBM business contact for information on the product or services available in your area.
All statements regarding IBM's future direction and intent are subject to change or withdrawal without notice, and represent goals and objectives only.
Information about non-IBM products is obtained from the manufacturers of those products or their published announcements. IBM has not tested those products and cannot confirm the performance,
compatibility, or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.
Prices subject to change without notice. Contact your IBM representative or Business Partner for the most current pricing in your geography.

1 © 2012 IBM Corporation


Agenda

§ Options for using Databases with z/VSE applications
§ z/VSE Database Call Level Interface (DBCLI)
§ DBCLI Concepts
§ COBOL Example
§ Hints & Tips
§ Summary



z/VSE applications accessing Databases

MS
SQL Server

z/VSE
CICS or
batch
Application
DB2/VSE
Server
DRDA Oracle
or Client

with DB2
Local Federation
Database DB2 LUW

MySQL



Options for using Databases with z/VSE applications
§ DB2/VSE or DB2/VM Server z/VSE Remote system
(Linux, Unix, Windows)
– Local database residing in z/VSE or z/VM Batch or CICS
– Lacks support of modern SQL functionality application With Federation:
DRDA
– Only quite old SQL level supported DB2/VSE Oracle, Sybase,
DB2 Server MS SQL, ...
Server/Client

§ DB2/VSE Client Edition
Local DB DB2 Data Data
– Remote database (on Linux, Windows, Unix)
– Communication via DRDA protocol
– Same old SQL level supported as DB2/VSE Server
– Can not use modern SQL functionality provided by DB2 LUW
– Can only access remote DB2 databases
• Other databases (e.g. MS SQL Server, Oracle, etc) can only be accessed through
IBM InfoSphere Federation Server

§ VSAM Redirector
– Primarily used to keep Databases in sync with VSAM data
– Also allows migration from VSAM to database

§ New: z/VSE Database Call Level Interface
– Allows z/VSE applications to access a relational database on any suitable database server
• IBM DB2, IBM Informix, Oracle, MS SQL Server, MySQL, etc.
– Utilize advanced database functions and use SQL statements provided by modern database products



New: z/VSE Database Call Level Interface (DBCLI)
§ Allows z/VSE applications to access a relational database on
any suitable database server
– IBM DB2, IBM Informix, Oracle, MS SQL Server, MySQL, etc.
àThe database product must provide a JDBC driver that supports JDBC V3.0 or later
àUtilize advanced database functions and use SQL statements provided by modern
database products
Requires z/VSE 5.1 plus PTFs (UK78892 and UK78893)

z/VSE Java capable Database Server
platform (may run on the
(e.g. Linux on same system as
Batch or CICS System z) the DBCliServer)
application
DBCLI API
DBCLI Database
DBCliServer
Client (e.g. IBM DB2,
TCP/IP IBM Informix
or local Oracle,
TCP/IP JDBC V3 MS SQL Server,
TCP/IP or MySQL, ...)
Linux Fast Path Driver




§ The z/VSE Database Call Level Interface (DBCLI) provides a programming
interface (API)
– Call interface for use with COBOL, PL/1, Assembler, C and REXX
– Can be used in Batch applications as well as in CICS TS applications
– Supports LE enabled as well as non-LE environments (Assembler, REXX)

§ It provides callable functions for
– Initializing and Terminating the API Environment
– Connecting and Disconnecting to/from the DBCLI Server and the Database
– Executing SQL Statements
– Retrieving query results through cursors
– Handling of Logical Units of Work (Transactions)
– Retrieving Database Meta Data

§ DBCLI can only support what the underlying Database supports



§ The DBCLI API is not compatible with DB2/VSE’s EXEC DB2 preprocessor
interface
– It provides similar functions and concepts
– The API is similar to the ODBC programming interface known from distributed
platforms (ODBC = Open Data Base Connectivity)

§ No preprocessor is needed, instead you code the CALL statements directly
in your program

§ A COBOL example is provided to show how DBCLI can be used in your
applications

§ Documentation is provided in the updated manual
“z/VSE V5R1 e-business Connectors User's Guide” - SC34-2629-01
– Chapter 9 and 22
– Available on z/VSE web page: http://ibm.com/zvse/documentation/#conn



Using the DBCLI API in your applications
§ Using DBCLI in COBOL:
– The COBOL copybook IESDBCOB contains common declarations
CALL 'IESDBCLI' USING FUNCTION ENV-HANDLE parm1 parm2 ... parmN RETCODE.

§ Using DBCLI in PL/1
– The PL/I copybook IESDBPL1 contains common declarations
CALL IESDBCLI(FUNCTION,ENV_HANDLE,parm1,parm2,...,parmN,RETCODE);

§ Using DBCLI in C
– The C header file IESDBC.h contains common declarations
IESDBCLI(function,&env_handle,&parm1,&parm2,...,&parmN,&retcode);

§ Using DBCLI in Assembler
– The Assembler macro IESDBASM contains common declarations
CALL IESDBCLI,(FUNCTION,ENV_HANDLE,parm1,parm2,...,parmN,RETCODE),VL
– The following register conventions apply:
• Register 0, 1, 14, and 15 are used by the interface and must be, if necessary, saved prior to invocation
• Register 13 must point to a 72-byte save area provided by the caller

§ Using DBCLI in REXX
ADDRESS LINKPGM "IESDBCLA FUNCTION ENV_HANDLE parm1 parm2 ... parmN RETCODE"
– All parameters must be initialized with a value of the appropriate length before calling the DBCLI API.
This is especially true for output parameters.
– Fullword binary variables must be initialized to contain 4 bytes (for example, VARIABLE = D2C(0,4) )
– Since the variable is expected to contain a value in binary representation, you must convert the value from the
REXX string representation into the binary representation and vice versa using the REXX functions C2S and
D2C


DBCLI Concepts: Initializing and terminating the environment

When using the API provided by the DBCLI client, you must:

§ Initialize the API environment by calling the INITENV function before calling any other
function
– The INITENV function allocates an environment handle that you must pass to all
subsequent functions
– You can have only one active environment at a time in your program

§ Terminate the API environment (at the end of your program) by calling the TERMENV
function
– The TERMENV function frees all resources allocated by the DBCLI code
– The TERMENV function will also close any "left over" connections or statements
– After the TERMENV function, the environment handle is no longer valid

§ You can set and get various attributes on the environment level
– You do so by calling the SETENVATTR or GETENVATTR function



DBCLI Concepts: Connecting to the DBCLI Server and Database

To access a Database, you must connect to the DBCLI server
and the Vendor database z/VSE Java capable
platform
Database Server
(may run on the
(e.g. Linux on same system as
Batch or CICS System z) the DBCliServer)
application

§ You connect to the DBCLI server (DBCliServer) and the DBCLI API
DBCLI
DBCliServer Database
Client
database by calling the CONNECT function TCP/IP
(e.g. IBM DB2,
IBM Informix
Oracle,
or local
MS SQL Server,
§ You must supply the: TCP/IP or TCP/IP JDBC V3
MySQL, ...)
Linux Fast Path Driver

– IP address or hostname of DBCliServer
– Alias name of the database or the JDBC URL to which you wish to connect
– User-ID and Password to authenticate with the database

§ The CONNECT function allocates a connection handle that you must pass to all subsequent functions that
require a connection
– You can have multiple connections to the same or different DBCLI servers and databases at a time
– Each connection is represented by its own connection handle

§ When you are finished working with a database, you must disconnect from the database and the DBCLI
server (DBCliServer) by calling the DISCONNECT function
– The DISCONNECT function frees the connection handle and all left over statements
(if any) that you have allocated using this connection



DBCLI Concepts: Logical Units of Work (Transactions)

Per default, a connection operates in transaction mode:
§ Any database updates that you perform are contained in a logical unit of work
§ You can end a logical unit of work by calling the COMMIT or ROLLBACK functions:
– The COMMIT function commits all changes done since the beginning of the logical unit
of work and starts a new logical unit of work
– The ROLLBACK function rolls back (reverts) all changes since the beginning of the
logical unit of work or up to a savepoint

§ Usually, you should explicitly call the COMMIT function at the end of the program.
§ If you do not call the COMMIT function, DBCliServer will automatically commit all changes
– if you gracefully close the connection by calling the DISCONNECT function
§ If the connection is dropped (for example, because the program abends), the DBCLI server
rolls back all changes done since the beginning of the last logical unit of work

§ You can set a connection into auto-commit mode
– In auto-commit mode, every SQL statement is treated as its own logical unit of work and
is committed automatically when the statement execution is complete.
• Therefore, you do not have to call the COMMIT or ROLLBACK functions.
– You set a connection into auto-commit mode by calling the SETCONNATTR function to
set the CONNATTR-AUTO-COMMIT attribute to TRUE


DBCLI Concepts: Preparing SQL Statements

In order to execute an SQL statement, you must first prepare the SQL statement
§ During preparation, the database will pre-compile the SQL statement and create an
access plan for the statement
– The access plan is kept as long as the statement exists
– You can then execute the statement as many times as you want

§ The PREPARESTATEMENT function prepares an SQL statement for execution
– It allocates a statement handle that represents the statement
– An application can have multiple prepared statements at a time
§ The PREPARECALL function prepares a stored procedure call statement for execution

§ SQL statements may contain parameters that are evaluated at execution time
– Parameters are marked by a question mark (?) within the SQL statement
– The parameters are numbered in order of appearance, starting with 1

§ After preparing, the application can bind host variables to the parameters using the
BINDPARAMETER function
– When the statement is later executed, the content of the host variables is used and sent
to the database.



DBCLI Concepts: Statement Parameters and Parameter Markers

SQL statements may contain parameters that are evaluated at execution time
§ Parameters are marked by a question mark (?) within the SQL statement
§ The parameters are numbered in order of appearance, starting with 1
§ Parameters can be used for INPUT, OUTPUT or both

SELECT * FROM EMPLOYEE WHERE EMPNO>? AND SALARY>?
Parameter 1 Parameter 2

àAbove statement has 2 parameters

§ When using DB2/VSE preprocessor, above statement would look like:
– SELECT * FROM EMPLOYEE WHERE EMPNO>:empno AND SALARY>:salary

§ The application binds host variables to the parameters using the BINDPARAMETER function
– When the statement is later executed, the content of the host variables is used and sent
to the database
– You also specify the data type and length of the variable with the BINDPARAMETER call
– You do not need to re-bind the parameters when executing the statement a second time

§ You can use the GETNUMPARAMETERS and GETPARAMETERINFO functions to obtain
13
detailed information about the statement parameters © 2012 IBM Corporation


DBCLI Concepts: Executing statements

To execute a statement, you must call the EXECUTE function
§ If the statement was an SQL update statement, you can retrieve the number of rows
updated using the GETUPDATECOUNT function or the UPDATE-COUNT parameter at the
EXECUTE function

§ If the statement was a SQL query statement, you can use a cursor to retrieve (fetch) the
result rows and columns
– A statement can provide multiple results (mostly stored procedures)
– To retrieve the additional results you must call the GETMORERESULTS function
– The GETMORERESULTS function will move to the next available cursor or update count

§ If the statement was a stored procedure call, output parameters are updated with the data
passed back by the stored procedure

§ When you no longer need a statement, you must close it by calling the CLOSESTATEMENT
function:
– The CLOSESTATEMENT function frees the statement handle and closes all cursors (if
any) that may still be open from the last statement execution
§ The statement handle is no longer valid after the CLOSESTATEMENT function



DBCLI Concepts: Result sets and Cursors

The execution on an SQL query returns a result in form of a cursor
§ A cursor allows you to retrieve (fetch) the result rows and columns
– You can use the GETNUMCOLUMNS and GETCOLUMNINFO
functions to obtain detailed information about the cursor's columns
– The columns are numbered in order of appearance, starting at 1

§ To fetch the result rows using the cursor, you must first bind host variables to the columns of
interest
– You bind host variables to the columns of interest by calling the BINDCOLUMN function
– If the FETCH function is called later on, the host variables will be updated with the
contents of the column in the row that has been fetched

§ Per default, the FETCH function processes the cursor from the beginning to the end
– You may reposition with a cursor
• Providing the database supports this and you have created the statement using the
appropriate type (CURSOR-TYPE-SCROLL-INSENSITIVE or CURSOR-TYPE-
SCROLL-SENSITIVE)
§ Repositioning can be performed using either the:
– FETCH function with operations FETCH-PREVIOUS, FETCH-FIRST, FETCH-LAST,
FETCH-ABSOLUTE or FETCH-RELATIVE.
15 – SETPOS function © 2012 IBM Corporation


DBCLI Concepts: Database Meta Data

The DBCLI interface allows you to retrieve meta data from the database
§ This includes functions to get a list of tables, indexes, keys, columns of a table, and so on
§ This information is typically stored in system catalog tables in the database.
– You can also execute regular SELECT statements against the system catalog tables, but
this requires that you know which database system and vendor you are using
– System catalog tables are vendor- and database-specific

§ The DBCLI interface provides a set of database independent functions
to retrieve meta data information.
– These functions are prefixed with 'DB'
– The function DBTABLES for example retries a list of tables
available in the database

§ Please note that some databases may not support all of the meta data functions
DBBESTROWIDENT DBPROCEDURES
DBCATALOGS DBSCHEMAS
DBCOLUMNPRIV DBSUPERTABLES
DBCOLUMNS DBSUPERTYPES
DBCROSSREFERENCE DBTABLEPRIV
DBEXPORTEDKEYS DBTABLES
DBIMPORTEDKEYS DBTABLETYPES
DBINDEXINFO DBTYPEINFO
DBPRIMARYKEYS DBUDTS
DBPROCEDURECOLS DBVERSIONCOLS


COBOL Example

Initialize the environment



COBOL Example

IP or hostname of
DBCLI Server
Database alias name
User-ID & Password

Connect to the
DBCLI Server
and the Database



COBOL Example

SQL Statement
Containing Parameter
Markers (‘?’)

Prepare an
SQL Statement
for later execution



COBOL Example

Bind host variable
“EMPNO”
to parameter
number 1
as STRING



COBOL Example

Bind host variable
“SALARY”
to parameter
number 2
as PACKED decimal



COBOL Example
Assign values

Execute the
statement



COBOL Example

Bind host variable
“FIRSTNAME” to
result set column
number 2


COBOL Example

Fetch all rows



Hints & Tips

§ The DBCLI code is CICS-aware
– If running under CICS, any memory allocations are performed using
EXEC CICS GETMAIN instead of using the GETVIS macro

§ When using the DBCLI API in CICS transactions while CICS operates with storage
protection, all programs using the DBCLI API need to be defined with EXECKEY(CICS)
– This is also true for those programs that link to these programs
– TASKDATAKEY(CICS) for the transaction definition is NOT required.

§ When using the DBCLI API in CICS transactions, the EZA "task-related-user-exit" (TRUE)
has to be activated before these transactions can be run
– For details on how to activate this TRUE, refer to "CICS Considerations for the EZA Interfaces" in the
z/VSE TCP/IP Support, SC34-2640

§ Most JDBC drivers will only accept pure SQL statements
– They will not accept SQL preprocessor statements that are used for DB2 Server for VSE applications

§ The call to the IESDBCLI function must be a static CALL in COBOL
– Do not use the DYNAM compiler option



z/VSE applications accessing Databases

MS
DBCLI SQL Server

And others ...
z/VSE
CICS or
batch
Application

DBCLI DBCLI &
DRDA Oracle

with DB2
DB2 LUW Federation

DBCLI

DBCLI MySQL



Questions ?

Mark your calendar:

IBM System z Technical University
Las Vegas, NV, USA
October 1-5, 2012
Caesars Palace

European GSE/IBM
Technical University for
z/VSE, z/VM and Linux on System z
Mainz, Germany
October 22-24, 2012

http://ibm.com/vse/events/


The New z/VSE Database Connector (DBCLI)

More Related Content

What's hot (12)

Similar to The New z/VSE Database Connector (DBCLI) (20)

More from IBM India Smarter Computing (20)

The New z/VSE Database Connector (DBCLI)