Centura SQLHost Client Developer's Guide - Index of

Centura SQLHost

Client Developer’s Guide20-2370-1002

ered, SQL/

f erica s,

by

PC, ks

ca

eir

TrademarksCentura, , the Centura logo, Centura net.db, Gupta, the Gupta logo, Gupta Powthe Gupta Powered logo, Fast Facts, Object Nationalizer, Quest, QuickObjects, API, SQLBase, SQLBase Exchange, SQLConsole, SQLGateway, SQLHost, SQLNetwork, SQLRouter, SQLTalk, and Team Object Manager are trademarks oCentura Software Corporation and may be registered in the United States of Amand/or other countries. SQLWindows is a registered trademark and TeamWindowReportWindows and EditWindows are trademarks exclusively used and licensedCentura Software Corporation.

IBM and IBM PC are registered trademarks of International Business Machines Corporation.

Database Manager, DB2, CICS, MVS, NCP, OS/2, DB2/2, DDCS/2, SQL/DS, APDRDA, VTAM, SNA, Presentation Manager, SAA, and Token-Ring are trademarof International Business Machines Corporation.

Microsoft, MS-DOS, and MS-OS/2 are registered trademarks of Microsoft Corporation. Windows is a trademark of Microsoft Corporation.

Microsoft, Win32, Windows, Windows NT and Visual Basic are either registered trademarks or trademarks of Microsoft Corporation in the United States of Ameriand/or other countries.

NetWare and Novell are registered trademarks of Novell, Inc.; NetWare LoadableModule and NetWare Requester are trademarks of Novell, Inc.

Abend-Aid is a registered trademark of Compuware Corporation.

Ethernet is a registered trademark of Xerox Corporation.

CompuServe is a registered trademark of CompuServe Incorporated.

All other brand and product names are trademarks or registered trademarks of threspective owners.

Portions of this software are copyright 1991-94 by Intersolv, Inc.

CopyrightCopyright 1992-1998 by Centura SoftwareCorporation. All rights reserved.Centura SQLHost Installation and Operation Guide20-2370-1002December 1998

ContentsQuerying and Publishing on the Web

Preface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii

Who should read this manual . . . . . . . . . . . . . . . . viii

Developer Requirements . . . . . . . . . . . . . . . . . . . viii

What is in this manual. . . . . . . . . . . . . . . . . . . . . . viii

Notation conventions . . . . . . . . . . . . . . . . . . . . . . . ix

Other helpful resources . . . . . . . . . . . . . . . . . . . . . ix

Send comments to . . . . . . . . . . . . . . . . . . . . . . . . . .x

1 About SQLHost . . . . . . . . . . . . . . . . . . . . . . . . 1 - 1

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 - 2

Connectivity Options. . . . . . . . . . . . . . . . . . . . . . 1 - 2

Host Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 - 4

2 Topics On Developing Client Applications2 - 1

Autocommit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 - 2

Bind variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 - 3

Binding numeric character data . . . . . . . . . . . . . . . . 2 - 3

COMMIT on normal conversation disconnect . . . . . . 2 - 4

Cursors, contexts, handles, and connections . . . . . . 2 - 4

Cursor-context preservation (CCP). . . . . . . . . . . . . . 2 - 5

Database access cycle . . . . . . . . . . . . . . . . . . . . . . . 2 - 6

Database Restrictions . . . . . . . . . . . . . . . . . . . . . . . . 2 - 7

Headings for derived columns . . . . . . . . . . . . . . 2 - 7

Isolation levels . . . . . . . . . . . . . . . . . . . . . . . . . . 2 - 7

Describe information . . . . . . . . . . . . . . . . . . . . . . . . . 2 - 7

Error processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 - 8

Frontend result sets (FERS) . . . . . . . . . . . . . . . . . . . 2 - 9

Lock time-out. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 - 11

Querying and Publishing on the Web iii

Multiple connections, locks, and deadlocks . . . . . . 2 - 12

Null handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 - 12

Optimizing network traffic . . . . . . . . . . . . . . . . . . . . 2 - 13

Message compression . . . . . . . . . . . . . . . . . . . 2 - 13

Array fetching . . . . . . . . . . . . . . . . . . . . . . . . . . 2 - 14

Bulk execute . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 - 14

Adjustable message buffer sizes . . . . . . . . . . . 2 - 14

Positioned updates . . . . . . . . . . . . . . . . . . . . . . . . . 2 - 15

Pre-fetching rows . . . . . . . . . . . . . . . . . . . . . . . . . . 2 - 15

Re-entrancy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 - 16

Stored Procedures . . . . . . . . . . . . . . . . . . . . . . . . . 2 - 16

About Stored Procedures . . . . . . . . . . . . . . . . . 2 - 16

SQLBase stored commands support . . . . . . . . 2 - 17

SQLHost support for stored procedures . . . . . . 2 - 17

SQL/API code sample . . . . . . . . . . . . . . . . . . . 2 - 18

System catalog access . . . . . . . . . . . . . . . . . . . . . . 2 - 19

3 Testing Connections with SQLTalk for Win-dows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

About SQLTalk for Windows . . . . . . . . . . . . . . . . . . . . 3-2

How to use SQLTalk for Windows . . . . . . . . . . . . . . . 3-2

Setting up SQLTalk . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2

16 bit Windows Client . . . . . . . . . . . . . . . . . . . . . . 3-2

32 bit Windows Client . . . . . . . . . . . . . . . . . . . . . . 3-3

Verifying the Client . . . . . . . . . . . . . . . . . . . . . . . . 3-4

If you cannot connect . . . . . . . . . . . . . . . . . . . . . . . . . 3-8

iv Querying and Publishing on the Web

4 Using SQLWindows Functions . . . . . . . . 4-1

About SQLWindows . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2

Setting and getting SQLHost parameters . . . . . . . . . . 4-2

Using program variables . . . . . . . . . . . . . . . . . . . . . . . 4-3

Using describe information . . . . . . . . . . . . . . . . . . . . . 4-4

Processing null data . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4

Processing errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5

Using frontend result sets (FERS) . . . . . . . . . . . . . . . 4-5

5 Using SQL/API Functions . . . . . . . . . . . . . . 5-1

About the SQL/API . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2

Supported functions and parameters . . . . . . . . . . . . . 5-2

Bulk Execute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5

Bind variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5

Describe information . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6

Using SQL/API functions with FERS. . . . . . . . . . . . . . 5-6

Processing LONG VARCHAR data. . . . . . . . . . . . . . . 5-7

Processing null data . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7

Pre-fetching rows . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8

6 Using Quest . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

About Quest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2

Accessing DB2 system catalog information using Quest6-2

Improving access to system catalog information . . . . 6-3

Customizing table creation . . . . . . . . . . . . . . . . . . . . . 6-3

Extracting data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4

Improving performance by minimizing locking . . . . . . 6-4

7 Using DBExplorer . . . . . . . . . . . . . . . . . . . . . . 7-1

About DBExplorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2

Using DBExplorer with SQLHost. . . . . . . . . . . . . . . . . 7-3

Creating a Table with DBExplorer and SQLHost . . . . 7-5

Querying and Publishing on the Web v

8 Data Type Implementation . . . . . . . . . . . . . 8-1

Translating data types. . . . . . . . . . . . . . . . . . . . . . . . . 8-2

Data type support for SQLNetwork . . . . . . . . . . . . . . . 8-2

Maximum record size . . . . . . . . . . . . . . . . . . . . . . . . . 8-3

STRING. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4

LONG STRING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4

NUMBER. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-5

DATE and TIME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-5

NULLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-6

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

SQLHost Client Developer’s Guide

Preface

Centura SQLHost Client Developer’s Guide provides useful information to help you in design and develop client applications for Centura Software Corporation’s SQLHost.

In this preface, you find information about:

• Who should read this manual

• Developer requirements

• What is in this manual

• Conventions used in the manual

• How to send us your comments

SQLHost Client Developer’s Guide vii

Preface

re

Who should read this manualThe manual is intended for:

• Developers who design and code client applications for PCs.

• System programmers and LAN administrators.

• End-users who help design client applications.

Developer RequirementsTo use this manual, you must be:

• Familiar with your PC environment.

• Able to use Microsoft Windows.

• Familiar with your PC LAN environment and the communications softwathat connects the PC to the server and, if applicable, the gateway.

• Able to edit Windows control files, such as AUTOEXEC.BAT, CONFIG.SYS, and *.INI files.

What is in this manualSQLHost Client Developer’s Guide is written for anyone using Centura SQLHost.

Summary of chaptersThis manual is organized into the following chapters.

1 About SQLHost Introduces SQLHost.

2 Topics on Developing Client Applications

Discusses various topics that relate to the development of client applications for SQLHost.

3 Testing Connections with SQLTalk for Windows

Explains how to use SQLTalk to test your connection between the client and server.

4 Using SQLWindows Functions

Describes special uses of SQLWindows functions with SQLHost.

5 Using SQL/API Functions Lists the SQL/API functions supported by SQLHost.

6 Using Quest Discusses using Quest with SQLHost.

7 Using DBExplorer Discusses using DBExplorer with SQLHost.

8 Data Type Implementation Provides information about data types.

viii SQLHost Client Developer’s Guide

s

e ns,

ut users.

ers luding nline

,

Notation conventionsThe table below shows the notation conventions used throughout this manual.

Other helpful resourcesCentura Books Online. The Centura document suite is available online. This document collection lets you perform full-text indexed searches across the entiredocument suite, navigate the table of contents using the expandable/collapsible browser, or print any chapter. Open the collection by selecting the Centura BookOnline icon from the Start menu or by double-clicking on the launcher icon in the program group.

Online Help. This is an extensive context-sensitive online help system. The onlinhelp offers a quick way to find information on topics including menu items, functiomessages, and objects.

World Wide Web. Centura Software’s world wide Web site contains information aboCentura Software Corporation’s partners, products, sales, support, training, and The URL is http://www.centurasoft.com.

The technical services section of our Web site is a valuable resource for customwith technical support issues, and addresses a variety of topics and services, inctechnical support case status, commonly asked questions, access to Centura’s onewsgroups, links to shareware tools, product bulletins, white papers, and downloadable product updates.

Our Web site also includes information on training, including course descriptionsclass schedules, and certified training partners.

Notation Explanation

You A user who reads this manual

User The end-user of applications that you write

bold type Menu items, push buttons, field names, items you select, and keyboard keys you press

Courier 10 code examples

SQL.INI Program names and file names

Warnin g: Precaution

Important: Vital information

Note: Supplemental information

SQLHost Client Developer’s Guide ix

Send comments toAnyone reading this manual can contribute to it. If you have any comments or suggestions, please send them to:

Technical Publications DepartmentCentura Software Corporation975 Island DriveRedwood Shores, CA 94065

or send email, with comments or suggestions to:

[email protected]

SQLHost Client Developer’s Guide

Chapter 1

About SQLHost

This chapter provides an overview to the SQLHost product line. It explains the various connectivity options, methods, and installation options.

SQLHost Client Developer’s Guide 1-1

Chapter 1 About SQLHost

ntura

ne

s of

al le it was

in and rking

ls. re

ols.

stall.

OverviewThe SQLHost product line is provided by Centura Software to enable Centura products to access DB2 and other host data. SQLHost is fully integrated into CeSoftware’s product lines giving seamless access through the Centura SQL/API, SQLWindows, and other Centura provided software.

Connectivity OptionsHost access from PC-based LANs has traditionally been a difficult and error proprocess. SQLHost is a product that eases PC LAN access to the mainframe by providing network transport support. In addition, it provides help in configuring connectivity, allowing a LAN-based programmer to concentrate on the essentialdata access, namely the user interface design and logistics.

Mainframe MVS systems have traditionally only supported SNA networks. LogicUnits such as APPC (LU 6.2) were used. This LU type was widely used to enabMVS subsystems (such as CICS) to communicate with each other and, becauseso widely used on the mainframe, it was easily adapted to connectivity to LANs.Unfortunately APPC connectivity entails significant configuration and a large amount of mainframe based knowledge. In recent years, TCP/IP has increased popularity in the mainframe network protocol market largely because of its speedease of configuration. SQLHost supports the use of both these mainframe netwoprotocols.

PC LANs have traditionally used NetBIOS or IPX/SPX as their principal protocoRecent advances have moved LANs more towards TCP/IP, but IPX/SPX LANs astill firmly entrenched.

SQLHost supports both TCP/IP and IPX/SPX as client-based networking protoc

Because the SQLHost architecture supports the various network protocols as pluggable features, it is up to you to choose the particular type of protocol you in

1-2 SQLHost Client Developer’s Guide

Overview

ost.

d.

gh as:

do and

The following table illustrates the various network protocol connections to SQLH

The protocols are available on the platforms where they are most commonly use

The direct client to host TCP/IP configuration is the simplest to configure, althouyour specific company may have reasons for not using this direct method, such

• You do not have TCP/IP installed or configured on the mainframe. If younot want to install TCP/IP, or are already experts in APPC configuration

Client Client to Gateway Gateway to Host Host

IPX/SPX IPX/SPX None None

TCP/IP TCP/IP TCP/IP TCP/IP

Client PC

LAN

TCP/IPIPX/SPX

IPX/SPX or TCP/IP TCP/IP

SQLGateway for

NetWare

MVS

APPC or TCP/IP


Chapter 1 About SQLHost

PC

ore net

IS own

this PPC e

The to be ble.

any

tic B2 CS st/

ic SQL

ere twork the ion. ent, ing

troubleshooting, you may want to use SQLGateway for NetWare with APconnectivity to the mainframe.

• You have TCP/IP installed on the mainframe but need to protect the information from unrestricted usage. You may choose to install one or mSQLGateways that are connected to your TCP/IP LAN on a specific subthat is allowed access to the mainframe through the mainframe firewall.Client PCs are only allowed access to SQLHost through the gateway computers. The gateways allow the MIS group a point of control. The Mgroup can setup firewalls to and from the gateway and if needed close dthe gateway to easily terminate all connections to SQLHost.

• You do not have TCP/IP as a commonly used client network protocol. In case, you would use IPX/SPX to get to the gateway and then use either Aor TCP/IP to get to the mainframe (whichever is more comfortable for thmainframe MIS group).

Host OptionsOnce you have determined the network protocols you want to use to access themainframe, the next step is deciding which version of SQLHost should be used.first step is to decide what type of mainframe data is to be accessed. If the data accessed is ad-hoc DB2 data that can be updated, then SQLHost/DB2 is availaSQLHost/DB2 allows access to DB2 data through dynamic SQL. It also allows multiple fetch cursors and simultaneous updating and browsing of DB2 data. Accessing DB2 data is easy through SQLHost because the client need only concentrate on the tuning and syntax of the actual DB2 statement without doingmainframe coding or network transport coding. The client application can be a sophisticated multi-table join or simple single row query. The application programming can be as easy to use as DBExplorer or a more complicated logisuser interface generated through the 4th GL SQLWindows provides. SQLHost/Dcomes with either CICS support, for companies that are comfortable with the CIenvironment and controls, or as a standalone MVS task. Both flavors of SQLHoDB2 support APPC and TCP/IP.

If more sophisticated mainframe data access is required, such as access to stator non-DB2 data sources, Centura provides SQLHost/Application Services. SQLHost/AS, which runs under CICS, provides a programming environment whhost programming can be concentrated on accessing the data instead of the neprotocol and packet shipping. Client side programming can concentrate on datadisplay and manipulation. SQLHost/AS provides a series of routines to structuredata access methodology and to retrieve and update the data in a DB2 like fashBecause SQLHost/AS is fully integrated into the Centura programming environmretrieval and updating of data from SQLHost/AS data sources is seamless, makthe data look just like another relational data source.


Overview

ing

les

r for

2

Reasons to choose SQLHost/AS include:

• To provide access to DB2 but not allow ad-hoc updating of DB2 tables. UsSQLHost/AS, you can provide controls (in addition to the normal DB2 controls) to ensure the DB2 data is updated with full compliance to any ruyour shop may have.

• To provide access to DB2 without the data access cycle, making it easiethe client to update the data.

• To provide access only to static SQL that has been produced by the DBexperts on the mainframe.

• To provide data access that allows combining DB2 data with other data sources such as VSAM files or IDMS database.

• To provide data access to non-relational data such as flat files.

• To perform a procedure that is completely non-data related.


f

e ed w the xplain

SQLHost/Application Services Developer’s Guide

Chapter 2

Topics On Developing Client Applications

This chapter discusses a variety of topics that are relevant to the development oclient applications using either SAL (Scalable Application Language) or a 3GL language (such as C) and the SQL/API. The topics are arranged alphabetically.

Connecting to DB2 a client application can be as simple as a CREATE TABLE statement, or as complex as a Positioned Update with a multitable join. The morcomplex the functionality of the application program, the more controls are needover how data is accessed and updated. The following is a list of topics that shoapplication program how to control the database access cycle. The topics also ehow Centura software interracts with the database access cycle.

SQLHost/Application Services Developer’s Guide 2-1

Chapter 2 Topics On Developing Client Applications

QL

, but

or

cted ly,

ary date

es so

f you same

end

is

AutocommitIf you set autocommit on, SQLHost commits changes automatically after each Scommand. If autocommit is off (the default), the SQLHost commits changes onlywhen you issue a COMMIT command.

Use of autocommit means you do not have to issue explicit COMMIT statementsit also means you cannot logically group multiple statements.

With autocommit on:

• SQLHost/DB2 issues a COMMIT at the end of every logical unit of work (at ROLLBACK, if a bad return code is received).

Note: All other connections made to the same SQLHost/DB2 transaction scope will be affewhen SQLHost automatically issues the COMMIT and ROLLBACK statements. Previousmultiple connections were not allowed. They are now allowed and the programmer is responsible for transaction scoping.

With autocommit off:

• You are responsible for the timely use of a COMMIT to reduce unnecesslocking that could restrict access to data for other users (either read or uplocks).

• You are responsible for the appropriate grouping of the database updatthat only the appropriate changes are cancelled.

An explicit COMMIT (either manual or automatic) or ROLLBACK affects all cursors connected to the same server with the same user name. This happens iare using a SQLGateway to make the connection, or all cursors connected to theserver if you are using TCP/IP direct connection.

When you use bind variables with autocommit, the unit of work is defined by the of the execute. Because of this definition, you cannot issue multiple execute statements while autocommit is on without losing the context of the compile. Thapplies to the context of all other cursors within that transaction scope.

For instructions on using this feature, read the function documentation on SqlSetParameter() and DBP_AUTOCOMMIT (for SQLWindows) and sqlset() and SQLPAUT (for the SQL/API) in the SQLBase SQL Application Programmers Interface Reference.

2-2 SQLHost/Application Services Developer’s Guide

Bind variables

ers) ind) a

SQL s for

Host/

he ert type

on

data

Bind variablesBind variables (also called program variables, host variables, or parameter markrefer to data values associated with a SQL statement. Bind variables associate (bsyntactic location in a SQL statement with a data value in that statement.

A bind variable in a SQL statement indicates that data from a variable in the application is bound to it each time the statement executes. This feature allows astatement to be compiled once and executed repeatedly with a new set of valuethe bind variables each time the statement is executed.

Bind variables normally can appear as items in a select list or as variables in a WHERE clause.

Note: DB2 does not support bind variables in a select list for dynamic SQL. Because SQLDB2 uses dynamic SQL, you cannot use bind variables in a select list.

For more information, refer to:

• SAL -- Using program variables on page 3-3.

• SQL/API -- Bind variables on page 4-6.

• Data Type Implementation -- Bind variables on page 6-6 (discusses NUMBER data type).

• Data Type Implementation -- NUMBER on page 6-6 (discusses bind variables with DATE and TIME data types).

Binding numeric character dataBecause DB2 has strict type checking, it is impossible to insert numeric data in tform of a null terminated string using a bind variable. Use SQLHost/DB2 to convthe null terminated string to the appropriate numeric data type by specifying the of numeric output on the bind command.

With SQLTalk, this is done using the $DATATYPES Numeric directive.

With the SQL/API, this is done by specifying the appropriate program data type the bind API request.

With SQLWindows and Centura Team Developer, this is done by specifying the type of the fields as a Number.



text pport

f data f e ws

the

e ble.

a rt of

icitly

e up an

COMMIT on normal conversation disconnectA DB2 COMMIT is performed when SQLHost/DB2 detects that the number of connected cursors is zero. This prevents data integrity problems when a client application ends before sending a COMMIT.

Cursors, contexts, handles, and connectionsThe terms cursor, context, handle, and connection are sometimes used interchangeably. At times, the handle from a SqlConnect() is called a 'cursor', but it is simply a context (if the database supports cursors). If that context is the first conto a database, SQLWindows and SQL/API applications create a connection to suit.

In SQLHost/DB2, a cursor represents a structure on the server that keeps track opointers and provides application-to-server communication. As a logical model owork, a cursor represents a context handle, rather than a single connection to thdatabase. Wherever the database servers allow it, the Centura architecture allomultiple cursors in a single connection, as well as multiple connections:

• Connected to the same table for two different activities -- the first cursor (for a SELECT) keeps track of the 'current' cursor position in a result table onserver while a second cursor updates or deletes data.

• Connected to two different tables -- the first cursor updates a column in ontable based on a value from the second cursor connected to the other ta

• Connected to two different databases -- each database maintains its own transaction and rollback recovery.

SQLHost allows up to 50 simultaneous connection cursors between a client andgiven instance of SQLHost/DB2. Simultaneous connection cursors interact as pathe same transaction; thus, a COMMIT or ROLLBACK on any one of these 50 cursors affects the other 49 whether these are done explicitly by the user, or implby autocommit.

When a client issues an initial CONNECT request to SQLHost, an instance of SQLHost/DB2 is created. Additional connection requests from that instance of thclient application that do not use a different database name and/or user ID open additional connection cursor to that instance of SQLHost/DB2.

Additional instances of SQLHost/DB2 can be connected to by:

• Changing the database name.

• Changing the user ID (for gateway connections only).

• Changing the client application.


Cursor-context preservation (CCP)

tion be

s

for e urns ;

rning

that, MIT.

tion

ase

hSql),

• Changing the client machines.

Syncpoints do not cross instances of SQLHost/DB2.

An application using a given database name and user ID can open a maximum of 50 connections. With each new instance of a database name or user ID, the applicaopens another connection. In addition, the maximum number of cursors that canopened is limited by Microsoft Windows resources. Windows gives each task (the executable and all DLLs that it uses) a fixed number of file handles. SQLWindowcan handle up to 40 file handles.

IF SqlResultSets() (the default) is on for SQLWindows, or if SqlResultSets with SALPFRS is turned on, SQLHost/DB2 manages the result sets for databases it supports in frontend result sets (FERS). Each handle consumes two file handleseach FERS file, using resources much more quickly. When all the resources havbeen consumed and the client application requests another handle, SQL/API retan error to the client application. SQLWindows uses some handles when it startshowever, if your application does not need FERS, you can save resources by tuoff SqlResultSets() or sqlset() SQLPFRS

SQLWindows defaults to frontend results sets off (sqlset w/SQLPFRS)s

Cursor-context preservation (CCP)Cursor-context preservation (CCP) is a per-cursor settable environment variablewhen enabled, allows an application to maintain an active result set after a COM

Note: A ROLLBACK always destroys the cursor context for all cursors within the transacscope no matter what setting is selected on the client or the server.

The default for CCP is 'off' (disabled). Enable CCP by using:

• sqlset() with SQLPPCX

• SqlSetParameter() with DBP_PRESERVE

ROLLBACKA ROLLBACK always destroys the FERS and destroys the position in the databtable by closing the database cursor.

For example, if an application prepares and executes a SELECT statement on (issues a ROLLBACK, and then issues SqlFetchNext(hSql), the application receives the error 201 No compiled command because it is attempting to perform an operation without first compiling a SQL statement .



t

. Do e

del

a client

to

hat ode is

o

a tion

that

a

Note: SQLHost/DB2 supports CCP after a COMMIT, but does not preserve CCP after a ROLLBACK.

Frontend result sets (FERS)With CCP enabled, the rows in FERS remain available for scrolling until the nexSELECT. COMMITs issued against data on a server are not reflected in the FERS on a client. If the data on the server changes, the client FERS becomes out of datenot rely on values in your data set to maintain data integrity. Always check uniqukeys such as TIMESTAMP and ROWID when updating.

Database access cycleThe translation between a client application and a server is provided through theCentura application programming interface, SQL/API. This request-response mohas several discrete phases of communication:

1. A client connects to the server by passing a string that contains the name of database, a user ID, and a password. The SQL/API returns a handle to the that identifies the connection. The client uses this handle in subsequent commands.

2. At the prepare phase (the compile phase), the client sends a command string the server requesting an action.

Note: For EARLY describe, the client may not know the data types or lengths of the items tcommand returns. It can call an (early) describe function asking the server to return informationthat describes the command's output. For operations other than SELECT, only a status creturned.

3. If appropriate, the client tells the SQL/API the location of future bind variables (input data) for the command. The Bind command tells the SQL/API where tlook for the BIND data when the execute occurs and what data type to tell SQLHost to translate it to.

4. The client asks SQLHost/DB2 to execute the command. When appropriate, datis retrieved from the bind variable location. The data and other bind informais sent with the execute message.

Note: For LATE describe, the client may not know the data types or lengths of the items the command returns. It can call a (late) describe function asking the server to return information that describes the command's output. For operations other than SELECT, only status code is returned.


Database Restrictions

e run-

on has

n.

other

t the

ive

ffer

rom a

t the ions

5. If processing a SELECT command, the client fetches the output. The server mayreturn as many rows as possible in one message, which the Centura run-timsystem on the client stores in a buffer. The client fetches each row from the time system by calling a fetch function.

6. When the client is finished processing, it disconnects.

Steps 2 through 6 are repeated for as many commands as the client applicatito process.

Database Restrictions

Headings for derived columnsDB2 does not return a heading for a derived column. Accordingly, with DB2, the sqldes(), sqldsc(), and sqlgdi() functions do not return a heading for a derived colum

Isolation levelsIsolation levels control how access to the tables in a database by one user affectsusers accessing the same tables on SQLHost/DB2.

With DB2 isolation levels are set when you bind the plan. You cannot change anisolation level from a client application because DB2 does not support dynamic modification of isolation levels.

For descriptions of supported isolation levels, refer to your DB2 documentation.

Describe informationCentura client applications use DESCRIBE for a variety of functions, including:

• Data type translation, inserting long data -- to ensure correct translation between the data type specified by the application and the data type thaserver expects.

• Buffer allocation -- to ensure that enough buffer space is allocated to receincoming data from the server.

• Data offset -- to keep track of data from the server transmitted as one bufor an entire row, as opposed to discrete data items.

You use the DESCRIBE command to request a description of the data returned fdynamic query.

SQLWindows and Quest applications require describe information to learn aboureturn columns of a query (for example, data type and length). SQL/API applicatdo not require describe information.



lly ved,

pport

ou

he

roy

ine ply

If you are developing a SQL/API application, set describe information using the SQLPDIS parameter of sqlset(). The valid settings are:

• SQLDELY -- early

This option allows the client application to set the select buffer dynamicabased on the information returned about the size of the data being retrierather than having to programmatically set the buffer. This is the defaultsetting.

• SQLDDLD -- delayed

This option reduces message traffic for database servers that do not suseparate compile and execute operations (like SQL Server).

• SQLDNVR -- never

If the client application does not require the describe information, then ycan reduce message traffic by using describe never. Using describe never in combination with the prefetch feature of Centura products can result in tquickest performance in returning the first rows in a result set.

Note: If you turn off describe information in a SQLWindows or Quest application, you destthe application's context. This may lead to unpredictable results.

Error processingA client application receives an error message if:

• The SQL/API detects an error.

• SQLHost detects an error.

• The database returns an error.

The error response contains three pieces of information:

• Error number or code.

• Database error number or code.

• Database error text.

Use the sqlerr() function for error processing. This function attempts to return theerror number (in either the 6,000 or 20,000 range) and the DB2 error text. This function returns error text from ERROR.SQL only if DB2 provides no error text.

SQLHost reports DB2 errors with a number between 6,002 and 6,999. To determthe DB2 error number, subtract 6,000 from the SQLHost error number and multiby -1. For example, SQLHost returns error number 6131 for DB2 error -131.


Frontend result sets (FERS)

er and e of ata, f

ery een

t sets

RS

wsing he

cts ust

le s that

Frontend result sets (FERS)Frontend result sets (FERS) are the storage areas for rows fetched from the servdelivered to the client (frontend). By taking a snapshot of the result set at the timfetch, the SQL/API provides backward and forward scrolling access to fetched deven when the database does not. This powerful feature provides a great deal oflexibility to client applications, but also can have performance and resource implications. Developers should understand the way their databases, as well as Centura clients, handle connections and cursors.

FERS are created in SQLWindows when a client application executes a SQL quagainst a SQLHost/DB2-supported database and result sets have not explicitly bdisabled. FERS are created in SQL/API when the user turns them on. The resulare fetched into a cache, called a frontend result set (FERS) file, on the client.

You cannot SELECT for UPDATE (positioned cursors) if the named cursor has FEenabled.

Note: Some databases, most notably SQLBase, support scrolling result sets. The user broon the client application actually moves forward and backward through the result set on tserver.

For instructions on changing or checking FERS, read:

• SQLWindows -- Using frontend result sets (FERS) on page 3-5.

• SQL/API -- Using SQL/API functions with FERS on page 4-7.

For more information about features that have an impact on FERS, read:

• Cursors, contexts, handles, and connections on page 1-3.

• CCP and frontend result sets on page 1-6.

Storing FERSFERS files are temporary flat files on the client computer. They are named FRSn (with no extension) where n is a positive integer. The first file is called FRS1, the second FRS2, and so on.

The files are deleted when the application requests another compile or disconnefrom the server. If the application ends abnormally and leaves these files, you mdelete them manually.

Note: SQLHost provides data-on-demand for servers that do not have backward scrollabcursors with a feature called frontend result sets (FERS). The names of the temporary filehold these result sets begin with "FRS".



t

n a ed n

e, this f the

in the

ong r of

FERS may be located in:

• The path indicated by calling the SQL/API sqlset() with the SQLPLRD parameter.

• The current Windows working directory.

How client applications use FERSTo use FERS, the client application must have the feature enabled (be result semode); this is the SQLWindows default setting.

One useful application of FERS involves prefetching data in order to release all shared locks. The client application can prefetch all the rows from the database server, using sqlnrr() or SqlGetResultSetCount() to retrieve the data.

FERS and performanceYou can affect performance by the number of rows you retrieve when you positiocursor with FERS enabled. Since FERS are created by delivering all the recordspreceding the selected row to the client, fetching more rows than you actually necauses unnecessary delay at the time of fetch. Also, repositioning the cursors cacause additional rows to be retrieved.

For example, you can use SqlGetResultSetCount() to set the maximum scroll positionon a table window for an application that runs against SQLBase. To get the valuSQLHost/API prefetches all the rows in the result set's table into a FERS file. Incase, you must consider the trade-off between the time required for completion oprefetch and the importance of getting the result set count to your application.

The number of rows cached is also determined by the number of rows returned SQL/API request. The following features affect the number of rows SQLHost returns:

• Prefech

• inmessage buffer size

• compression

• FOR UPDATE

• array fetching

FERS and long dataNormally long data is not maintained in the FERS files. You can read and write ldata when using frontend result sets by using the SQL/API SQLPLFF parametethe sqlset() command.


Lock time-out

grity. ing me.

not bled, he

nd client ch, it

rity ion

me

a not

. If it nd

s

sages

r.

Maintaining data integrityFERS may require you to make compromises between concurrency and data inteIf locks are put on pages, tables, or rows to prevent users from reading or changdata while someone is working with it, fewer users may be able to work at one ti

If the application does not lock the rows that display, the data in those rows maybe current when they are updated. This situation typically arises with FERS enabecause you cannot use positioned cursors (to maintain the cursor position on tserver) and FERS at the same time.

When FERS are enabled, a client application issues a fetch or positioning call, aretrieves rows from the database. The rows are placed in a result set file on the (frontend). When the client application receives user requests after the initial fetretrieves the information from the result set file on the client machine.

When using FERS, the client application is responsible for maintaining data integbetween the result set file on the client and the table in the server. If the applicatlocks the rows being displayed, they remain locked until the transaction ends. (Because positioned updates require that the cursor in the result set be at the saposition as the cursor in the table, rows are retrieved one at a time, reducing performance.)

With FERS, the SELECT for UPDATE alerts the database that the select is usingCURRENT OF (positioned) cursor, which enforces single-row fetches. If you do disable FERS, you get an error.

Lock time-outLock time-out is the amount of time a server waits for a resource to be availablecannot complete an action within the time-out, the server stops the transaction arolls back any changes.

Note: Control lock time-out through DB2 services, not through SQLHost.Message queue

Windows maintains two types of message queues:

• Application message queues

• System message queue

Each application has its own message queue. The system queue maintains meson mouse clicks, keyboard input, and other hardware-related events. Windows notifies the active application of these events via the system queue as they occu



on it zing

t it trol

the

an

ed

n

e first

e or eans

Quest and the system queueQuest always drains the system queue within its callback function and either actsimmediately, or stores it for later processing. As a result, actions such as minimithe application work fine. Mouse clicks in the client area are either acted on or ignored.

SQLWindows and the system queueSQLWindows does not drain the system queue. For instance, if a user clicks themouse in the client area following a server request, Windows cannot relinquish control to other tasks because the current application would never have anotheropportunity to receive the message(s) waiting in the system queue. As a result, Windows refuses to pass control and the system appears to be processing synchronously.

To avoid this behavior in SQLWindows, either click outside the application so thadoes not receive these messages or use Ctrl-Esc to bring up the task list. Either way,Windows moves the SQLWindows application to the background and permits conto pass to other applications.

Multiple connections, locks, and deadlocksYou can connect applications simultaneously on a client workstation for many ofdatabases. However, the SQL/API processes messages in a single-threaded, synchronous manner; it must receive a response to the first message before it csend a second one. This requirement can cause a deadlock, as in the followingexample:

1. The first application performs an update, which is sent to the database. Thedatabase locks the row before performing the command. (The lock is releasonly when the application sends a COMMIT or ROLLBACK.)

2. A second application tries to update the same row before the first applicatioCOMMITs. The row is locked; the database server waits for the lock to be released, which means that the application does not receive a response. Thapplication cannot send a COMMIT.

Null handlingNull values (nulls) are special values that can appear as column values in a basderived table. The designation is intended to represent an unknown value and m'information missing'. Arithmetic and scalar comparison operators treat nulls according to very specific rules.


Optimizing network traffic

the

ng

LHost

etch

cters. is

P

DB2 does not support zero length character strings with bind variables, so you must use a null value to write this information to DB2.

If you are using SQLWindows/32 (also known as Centura Builder) you may use STRING_Null constant. For both SQLWindows/32 and SQLWindows (16 bit) youcan also use the setzerolengthstringstonull keyword in your client SQL.INI file. Reference the SQLHost Installation and Operation Guide for more information on this keyword.

You can also use the SQL/API to manipulate nulls. For more information, refer toProcessing null data in Chapter 4.

Optimizing network trafficTo optimize network traffic between a client and server, SQLHost has the followifeatures:

• Message compression.

• Array fetching --You can fetch multiple rows in a SELECT at one time, rather than fetching single rows at a time.

• Bulk execute--The data for UPDATE, INSERT or DELETE is sent to the server in batches (rather than row by row).

• Adjustable message buffer sizes.

Message compressionWhen message compression is on, messages sent between the client and the SQare compressed. This means that:

• Messages are shorter.

• More rows can be packed into a single message during bulk insert and foperations.

The compression algorithm uses run-length encoding to collapse repeating charaThe compression is performed incrementally as each component of a message posted.

Message compression is enabled for an individual cursor by setting the SQLPCMparameter to On (1). This can be done in SAL by the SqlSetParameterAll ( ) function and in SQL/API by the sqlset ( ) function.

By default, SQLPCMP is off (0).



a s

the

e

r e tput e

that ot

ickly.

by

L by

Array fetching Array fetching lets the client fetch multiple rows of data into an array buffer with single message to the server, reducing network message traffic. Array fetching ialways enabled.

Bulk execute

Bulk execute works in the other direction (from the client to the server), enablingmessage from the workstation to move data to the server in one batch (in bulk).

Note: You cannot use bulk execute with SQLWindows/32, or SQLWindows. It can only bused with SQL/API applications. For further information refer to Chapter 4.

Adjustable message buffer sizesNetwork traffic is also affected by the size of the input message buffer (for arrayfetching) and the output message buffer (for bulk execute). These are per cursosettable parameters. The buffers are defined relative to the client. Input messagbuffer applies to messages sent from the server (SQLHost) to the client, and oumessage buffers are used to send SQL statements and data from the client to thserver. The buffer sizes are adjusted dynamically to contain at least one SQL statement, or a single row of data being returned from a SELECT query.

Warning: The buffer sized should be optimized to whether the APPC buffer size the gateway is using or to the TCP/IP packet sizes that your network is using. Noptimizing these buffer size can cause severe performance degradation.

Input message buffer

With a small buffer, fewer rows are returned at a single time. More buffers are required, and message traffic increases, but the first rows are returned more qu

The default input message buffer size is 2000 bytes and can be modified in SALusing the SqlSetInMessage ( ) function and in SQL/API by the sqlims ( ) function.

Output message bufferThe default output message buffer size is 1000 bytes, and can be modified in SAusing the SqlSetOutMessage ( ) function and in SQL/API by the sqloms ( ) function.


Positioned updates

at use tinue for rsor.

te a

ent. e

ws

Positioned updates

Positioned updates, also referred to as CURRENT OF CURSOR, are updates thtwo active cursors. They are useful when an application needs to update and confetching operations. The first cursor sets a cursor's name and selects some dataupdate; the second cursor updates that data based on the position of the first cu

Use the FOR UPDATE clause to position the cursor.

Using the CURRENT OF clauseThe following procedure explains the use of the CURRENT OF clause.

1. Set a named cursor by calling SqlOpen().

2. Issue a SELECT statement using the named cursor.

3. Use an UPDATE statement with the CURRENT OF clause when users initiarow change.

This example shows the steps in SAL (for SQLWindows):

Call SqlPrepare(hSqlA, 'SELECT PROPNUM, CITY, PRICE,REALTIME FROM REALTYFOR UPDATE OF PRICE INTO :COL1,:COL2,:COL3,:COL4')

IF NOT SqlOpen(hSqlA, 'CUR1')…

IF NOT SqlFetchNext(hSqlA, nRetVal)…

IF NOT SqlPrepare(hSqlB, 'UPDATE REALTYSET PRICE =:COL3WHERE CURRENT OF CUR1')

…Call SqlExecute (hSqlB)

Pre-fetching rowsWhen sqlexe() or sqlcex() is called, as many rows as will fit in the input message buffer are automatically fetched in one message exchange for a SELECT statemColumn describe information is returned before the first group of rows in the sammessage.

For more information on using this feature with the SQL/API, read Prefetching roon page 4-9.



o or ueued

m

ntly r uests.

dures. the

er

side e ny his

Re-entrancySQL/API is not truly re-entrant. To prevent applications from calling themselves,SQL/API serializes entrancy by tasks on a first-come, first-served basis. This arrangement may cause extended delays in processing server requests when twmore applications request connectivity services concurrently, since access is a qprocess on a single execution thread.

The Centura module that processes SQL/API requests, is re-entrant, but only frodifferent applications. Any task that re-enters SQLAPIW.DLL or SQLWNTM.DLLwhile waiting for a server request receives an error.

Note: Since SQL/API yields to Windows, there are subtle ways in which you can inadvertere-enter your application. The most common situation is an application using SAM_Timemessages. You may have to disable these timer messages temporarily during server req

Stored Procedures

About Stored ProceduresRelational database vendors use one of two methods to implement stored proceOne method is to define a meta-language for the procedure and use SQL to addmeta-language procedure to the database catalog, then call that procedure eithdirectly or through a trigger. This method is used by SQLBase, Oracle, Informix,SQLServer, and Ingres.

The other method is to write the procedure in a server side language and let it reon a server platform. Then catalog entries are made into the database to indicatwhere the procedure is and what the procedures interface is. Users can invoke aprocedure they are authorized to invoke if it is defined in the database catalog. Tmethod is used with DB2 and Sybase stored procedures.

When the procedure is written, the programmer must do the following:

• Precompile with the DB2 precompiler.

• Compile.

• Link-edit into an MVS load library in the DB2 steplib concatenation.

• Bind to DB2 using BIND PACKAGE.

• Defined the stored procedure to SYSIBM.SYSPROCEDURES.

• GRANT EXECUTE to the appropriate users.


Stored Procedures

of:

eta-e e text

able

for s of ieve t les

one

ed the

of a ly the

Defining the procedures to SYSIBM.SYSPROCEDURES allows the specification

• Input only parameters (names, datatypes and lengths).

• Output only parameters (names, datatypes and lengths).

• Input/Output parameters (names, datatypes and lengths).

• Whether the procedures supports NULL values.

• The language of the procedure (for linkage conventions).

• The name of the load module.

• The name of the plan/package for the load module.

SQLBase stored commands supportSQLBase stored procedures support is referred to as Stored Commands. The mlanguage SQLBase uses for its procedures or commands is essentially the samlanguage SQLTalk uses. When a stored command is required, the user uses thesqlsto() command to define the command name and the text of the command. Thof the command can contain one or more SQL commands. When the sqlsto() command is issued, SQLBase updates the SYSADM.SYSCOMMANDS system tto define the procedure to the database.

After the command is stored, a user can Retrieve it (the equivilant of the compileregular commands) by using the sqlret() command. Retrieve can retrieve a seriestored commands simply by listing them as comma separated values on the retrcommand. The retrieve command returns descriptor information about the outpuvariables and indicates the number of bind variables and number of input variab(note that the SQLBase SQL/API does not allow for the description of input parameters).

After the command(s) is(are) retrieved the user Executes the command and thenFetches the returned data. A SQLBase stored command can contain more than row of returned data.

Stored commands are multirow and are affected by CCP. Procedures are droppsqldst() command is used.

SQLHost support for stored proceduresThe DB2 definition of a unique identification of a stored procedure includes the Procedure Name, an Authorization ID and an LUName. Therefore any invocationDB2 Stored Procedure must be able to specify all three parameters. However, onprocedure name is required



nd re

e a the e

in

s.

The SQLBase syntax on the sqlret() command only allows for a procedure name should be specified and in fact the SQLTalk syntax for the RETRIEVE commandonly allows for the specification of one name after the RETRIEVE keyword.

To invoke DB2 stored procedures through SQLHost, three name value pairs areavailable:

• PROCEDURE(name)

• AUTHID(name)

• LUNAME(name)

Only PROCEDURE is required. The user can specify either or both of AUTHID aLUNAME. AUTHID or LUNAME are not used as an identification for the proceduif they are not specified.

DB2 does not have the equivilant of the RETRIEVE command. In order to invokstored procedure, the client application (DB2SERVR in this case) needs to issueSQL CALL command specifying the procedure name and optionally the AUTHIDand/or LUNAME. When the SQL CALL is issued, the bind variables (including thINPUT, OUTPUT and INOUT parameters) are specified in the SQLDA.

After the SQL CALL is executed, the OUTPUT and INOUT parameters will contathe output values. DB2 V4 only allows for a one row result set from a stored procedure call so there is no associated Fetch cursor and no multiple row fetche

SQL/API code sample#define SQL_32BITTARG 1#include "sql.h"#include "string.h"#include "stdio.h"

void main(){

SQLTAPI ret;SQLTCUR cur;char procname[30];SQLTDALprocl;SQLTSCAscap;SQLTDAL procbufl;char procbuf[18];SQLTDAL authbufl;char authbuf[8];SQLTDAL lubufl;char lubuf[8];

ret = sqlcnc(&cur, "sqlh/myuserid/mypwd", 0);


System catalog access

stem data e catalogs

ns of access g is

printf("connect ret = %d\n", ret);if (ret == 0){

strcpy(procname, "PROC(SAMPLE) AUTHID(MYUSERID) LUNAME(MYLU) ");

procl = strlen(procname);ret = sqlret(cur, (SQLTDAP)procname, procl);printf("retrieve ret = %d\n", ret);

strcpy(procbuf, "SAMPLE");procbufl = strlen(procbuf);strcpy(authbuf, "MYUSERID");authbufl = strlen(authbuf);strcpy(lubuf, "MYLU");lubufl = strlen(lubuf);scap = 0;ret = sqlbnd(cur, "PROCNM", 6, procbuf, procbufl, scap,

SQLPBUF);printf("bind 1 ret = %d\n", ret);ret = sqlbnd(cur, "AUTHID", 6, authbuf, authbufl, scap,

SQLPBUF);printf("bind 2 ret = %d\n", ret);ret = sqlbnd(cur, "LUNAM", 5, lubuf, lubufl, scap, SQLPBUF);printf("bind 3 ret = %d\n", ret);ret = sqlexe(cur);printf("execute ret = %d\n", ret);

ret = sqldis(cur);printf("disconnect ret = %d\n", ret);

}return;

}

System catalog accessEach SQL database management system describes its data in a collection of sytables called a system catalog. These tables contain information about the user tables, indexes, views, and authorization, and are automatically created when thdatabase is created. The database management system refers to these system while processing SQL statements.

Tools like Quest, need to be able to learn dynamically about the tables and columa database. They use system catalog queries for this purpose. Applications can the system catalog using SQL statements, but the structure of the system catalodifferent for each SQL database.



ese tables.

SQLHost provides client applications with a common view of system catalogs. Thviews, created by running scripts, represent a subset of the base system catalog

Note: For information on running the VIEWS.DB2 views script, read the SQLHost Installation and Operation Guide.



Chapter 3

Testing Connections with SQLTalk for Windows

This chapter describes using SQLTalk to test the connection between client andserver.


Chapter 3 Testing Connections with SQLTalk for Windows

n

ther

r

der lable ctly

ing

About SQLTalk for WindowsSQLTalk is an interactive query program provided to help you test the connectiofrom a client to a server.

How to use SQLTalk for WindowsUse SQLTalk for Windows only to test the connection between client and server.SQLTalk is not supported as a database query or administration tool for RDBMs othan SQLBase. SQLTalk does not prevent you from issuing commands that youserver or driver may not support; this can have can have unpredictable results.

Setting up SQLTalk Decide what client protocol you need.

SQLHost supports two client side network protocols, IPX/SPX and TCP/IP. In orfor a client machine to connect to SQLHost one of these protocols must be avaito the clients. IPX/SPX requires that SQLGateway for NetWare be installed. WithTCP/IP the connection can be made either with SQLGateway for NetWare or direto SQLHost depending on the host protocols that are configured.

16 bit Windows ClientTo support IPX/SPX on the client side, the comdll SQLSPXW.DLL must be available.

To support TCP/IP on the client side the comdll SQLWSOCK.DLL must be available.

1. Change the SQL.INI

To enable IPX/SPX on the client side the client SQL.INI should have the following entries

[winclient.dll]

comdll=SQLSPXW

[winclient.spxw]

To enable TCP/IP on the client side the client SQL.INI should have the followentries

[winclient.dll]

comdll=sqlwsock


Setting up SQLTalk

e

use

ble.

le.

ing

e

use

[winclient.wsock]

serverpath= server_name,host_name or IP _address,port#service_name[,service_name]

where host_name or IP_address identifies either the SQLGateway or mainfram

port# identifies the port that SQLHost or the gateway has been defined to

service_name is the tpname of the SQLHost transaction

32 bit Windows ClientTo support IPX/SPX on the client side the comdll SQLSPX32.DLL must be availa

To support TCP/IP on the client side the comdll SQLWS32.DLL must be availab

1. Change the SQL.INI

To enable IPX/SPX on the client side the client SQL.INI should have the following entries

[win32client.dll]

comdll=SQLSPX32

[win32client.spx32]

To enable TCP/IP on the client side the client SQL.INI should have the followentries

[win32client.dll]

comdll=sqlws32

[win32client.ws32]

serverpath= server_name,host_name or IP _address,port#service_name[,service_name]

where host_name or IP_address identifies either the SQLGateway or mainfram

port# identifies the port that SQLHost or the gateway has been defined to

service_name is the tpname of the SQLHost transaction



e

ing

Verifying the Client

Start SQLTalkInvoke SQLTalk for Windows by issuing selecting the installed icon from the SQLHost installation or issuing the SQLTALK command from the DOS prompt.

Connect to the Server (for gateway)If you are connecting to SQLHost through SQLGateway for NetWare first test thconnection to the gateway by connecting to the gateway itself. Find out the SERVERNAME of the gateway by asking your gateway administrator or by lookat the screen after hitting F1 on the gateway screen itself.

Then, from inside SQLTalk issue the command

set server server_name;

and hit CTRL-ENTER

If the output window shows

SERVER IS SET

then you are correctly configured to reach the gateway machine.

If the output window shows

Error: Cannot connect to server

then you are not configured properly.


Setting up SQLTalk

A good connection



LHost

A bad connection.

Connect to the databaseIssue the command:

Connect dbname userid/password;

where dbname is the database name advertised by the gateway or the CICS SQtransaction id or the program name for DB2SERVR as known by GTIMON.


Setting up SQLTalk

s
where userid and password are the MVS userid and password authorized to accesSQLHost.
A good connection.

Now you have verified your connection to SQLHost is valid.



If you cannot connectRead Chapter 11,Verifying and Troubleshooting in the SQLHost Installation and Operation Guide.



Chapter 4

Using SQLWindows Functions

This chapter discusses using SQLWindows functions with SQLHost.


Chapter 4 Using SQLWindows Functions

ping

g

ers:

ters")

L/

About SQLWindowsSQLWindows, Centura's application development system, is designed for develodatabase applications that run under Microsoft Windows 3.1, 95, and NT.

The programming language used by SQLWindows is known as SAL (Scalable Application Language). SAL has a wealth of built-in functions to make developinclient/server applications easy and enjoyable.

Setting and getting SQLHost parametersSQLWindows has two sets of functions that you can use to set and get paramet

• SqlSetParameter( ) and SqlGetParameter( )

• SqlSetParameterAll( ) and SqlGetParameterAll( )

SqlSetParameter( ) and SqlGetParameter( )Use these functions only with predefined DBP_* parameters ("database paramethat have been defined for and are controlled by SQLWindows. They include:

• DBP_AUTOCOMMIT

• DBP_BRAND

• DBP_PRESERVE

• DBP_VERSION

SqlSetParameterAll( ) and SqlGetParameterAll( )These functions work not only with the DBP_* parameters, but with all the parameters defined in the file SQL.H, and the DBP_* parameters defined in SQLNWKCN.APL (a SQLWindows include file containing parameters specific toSQLHost).

About the file SQL.HThe file SQL.H defines function prototypes, constants, and data types for the SQAPI. To use a parameter defined in SQL.H in SQLWindows, look up the numeric value of the parameter you want to set or get in SQL.H, then enter its numeric value as the second argument to the function. (If you are writing the program in C, #include the header file and use the SQLP* constants directly.)

About the file SQLNWKCN.APLThe file SQLNWKCN.APL is a SQLWindows include file for Centura connectivityproducts. It defines useful DBP_* constants for SQLWindows applications that communicate using SQLHost.


Using program variables

an

f a

the CH

the

To use a constant defined in SQLNWKCN.APL, include the file in your SQLWindows application. Then, include the name in SQLNWKCN.APL (rather tha value from SQL.H) to represent the parameter you set or get.

For example, to turn on Centura's message compression:

SqlSetParameterAll(hSql,DBP_COMPRESS,1,',TRUE)

Using program variablesThere are two types of program variables: bind variables and describe (or INTO)variables.

You can use bind variables with SQLWindows in a:

• WHERE clause;

• VALUES clause in an INSERT statement;

• SET clause in an UPDATE statement.

You can use describe variables with SQLWindows in an:

• INTO clause in a SELECT statement.

The program variable is preceded with a colon (:) and is followed by the name oSAL-defined variable. For example:

SELECT title

FROM books

INTO :dfTitle

WHERE AUTHOR = :dfAuth

Program variables are not always processed as you might expect. For example,INTO clause in the statements of a SQLWindows application is stripped from thePREPARE string before being processed further. SQLWindows accepts the FETdata into its own local storage, then copies it into the variables defined by the SQLWindows application.

In addition, although SQLWindows variable names can be specified in WHERE,VALUES, and SET clauses, these variable names are not passed to SQLHost. SQLWindows replaces the variable names with the positional number for that variable, then binds the variable by number.

SQLHost/Application Services host developers (who must specify the "name" ofbind variables) must refer to the variables by their positional numbers, not their names. Thus,



1.

ince

le

l

s

SELECT title

FROM books

INTO :dfTitle

WHERE AUTHOR = :dfAuthis transformed intoSELECT title

FROM books

WHERE AUTHOR = :1before being sent to the target database for processing.

Using describe informationThe server side application BIND EVENT will receive the "bind data number" asIt should return the "bind data name as "1".

SQLWindows applications require describe information to learn about the return columns of a query.

Note: Do not change the setting for describe information in a SQLWindows application, sthis destroys the application's context and prevents you from selecting data.

Processing null dataDB2 does not support zero-length character strings with bind variables. To handnull values, use the STRING_Null constant available in SQL/API. For 16 bit applications written in SQLWindows (before the introduction of the STRING_Nulconstant use the setzerolengthstringstonull SQL.INI keyword to forces to work with DB2 correctly.

Binding null dataTo bind null data, call either ssqlbna() or sqlbnu() after calling sqlcom() and before calling sqlexe(). Both the sqlbna() function, which binds by name, and the sqlbnu() function, which binds by number, have an argument for the null indicator.

Checking the null indicatorUse the sqlgdi() function (get describe information) to find out if the null indicator iset. The sqlgdi() function also returns everything that the sqldsc() and sqldes() functions return.


Processing errors

r

ted

ber

he

an

e

Fetching null dataBy default, sqlfet() returns 0 (successful) in the pfc variable (set by the sqlssb() function) if the value of a column is null. This default maintains compatibility withreleases of Centura's SQLBase and related connectivity tools prior to version 5.

To set the pfc variable so that it returns the FETRNUL status to indicate whether onot the fetched column has a null value, turn on SQLPNIE.

For example, to instruct sqlfet() to return FETRNUL for the fetch on cursor_1 for the first item in the SELECT list into character buffer data, call:

sqlssb (cursor_1, 1, SQLBUF, 1, 1, 0,

SQLNPTR, FETRNUL)

Processing errorsSQLWindows has four standard functions for processing errors:

• SqlGetError ( ) – If the error number is in the range 1 - 5,999 or 7,001- 20,000, searches the file SQL.ERROR.; otherwise, it returns the translaerror number and database error message from SQLHost.

This function is recommended because it returns the database error numand error text, which are more useful than the ERROR.SQL text. This function is the default for SQLWindows and Quest error processing.

• SqlGetErrorText( ) -- Returns an error message.

If the text for the given number is in ERROR.SQL, the text of the error message is returned; otherwise, the database error number is returned.

• SqlError( ) -- Returns an error number.

• SqlErrorText( ) -- Displays the reason and remedy text (if any) defined for terror . If no reason and remedy text is defined, "message not found" is displayed.

Using frontend result sets (FERS)SqlSetResultSet( ) turns result set mode on or off. After you form a result set, you cposition to any row by calling SqlFetchRow. You can also call SqlFetchNext( ) and SqlFetchPrevious( ).

SQLWindows applications default to result set mode. You create the result set filwhen you call SqlPrepare( ) -- or when you call SqlExecute( ), if you didn't make an intervening call to SqlPrepare( ).



lt

e of

You remove the result set file when result set mode is turned off SqlSetResultSet( ), after a SqlDisconnect( ), or after a COMMIT or ROLLBACK. If cursor-context preservation is not on, a COMMIT or ROLLBACK removes the file. If cursor-context preservation is on, a COMMIT or ROLLBACK does not remove the resuset file.

Note: Operating with result sets mode on uses more Windows file handles. Excessive usresults may restrict the number of database connections an application can make.


s


Chapter 5

Using SQL/API Functions

This chapter lists the SQL/API functions supported by SQLHost. It also describedifferences in using the SQL/API specifically with SQLHost. Use this chapter in conjunction with the standard SQL/API documentation.


Chapter 5 Using SQL/API Functions

ta in t does

host piler

host rver,

pre-

rs nk it , it soft

can s

About the SQL/APISQL (Structured Query Language) can define, manipulate, control, and query daa relational database. However, because SQL is not a programming language, inot provide procedural logic, extensive data typing, or variables.

In programming with SQL you have two choices:

• Use embedded SQL to insert SQL statements directly into the program'ssource code (for example, C). This approach requires a special pre-comto accept the combined source code and convert it into an executable program.

• Use an application program interface (API) to access the database. Thecode uses the API functions to send SQL statements to the database seand then uses them again to retrieve query results. You do not need to compile the programs.

SQL/API is the Centura application program interface library. Typically, developeuse the API functions with a programming language, compile the program, and lito the API library. Although you may see the library referred to as a C/API librarycan be used with programming languages other than C and C++, including MicroVisual Basic. For information about SQL/API library functions, read the SQL Application Programming Interface Reference.

Supported functions and parametersSQLHost supports only a subset of SQL/API functions, and the parameters thatbe used with the sqlset() and sqlget() functions. The parameter values are constantenumerated in the SQL.H file for the SQL/API and the COBOL pre-compiler.

Supported SQL/API functions

Note: Only the functions in this list are supported by SQLHost.

sqlbbr()sqlbef()sqlber()sqlblk()sqlbln()sqlbna()sqlbnd()sqlbnn()sqlbnu()sqlcbv()sqlcex()


Supported functions and parameters

sqlcmt()sqlcnc()sqlcom()sqlcpy()sqlcrs()sqlcty()sqldbn()sqldes()sqldir()sqldis()sqldon()sqldsc()sqlelo()sqlerr()sqletx()sqlexe()sqlfer()sqlfet()sqlgdi()sqlget()sqlgfi()sqlgls()sqlims()sqlini()sqllsk()sqlnbv()sqlnrr()sqlnsi()sqloms()sqlprs()sqlrbf()sqlrbk()sqlrcd()sqlrlo()sqlrow()sqlscn()sqlset()sqlspr()sqlsrs()sqlssb()sqltec()sqlwlo()sqlxad()sqlxcn()sqlxda()sqlxdp()sqlxdv()



sqlxer()sqlxml()sqlxnp()sqlxsb()

Supported sqlset() parameters

Note: Only the parameters in this list are supported by SQLHost.

SQLPAUTSQLPBLKSQLPCIDSQLPCMPSQLPDDBSQLPDISSQLPDPWSQLPDUSSQLPFRSSQLPGBCSQLPLABSQLPLFFSQLPLRDSQLPNIESQLPPCXSQLPRESSQLPRSYS

Supported sqlget() parameters

Note: Only the parameters in this list are supported by SQLHost.

SQLPAUTSQLPBRNSQLPCMPSQLPDBNSQLPDDBSQLPDISSQLPDPWSQLPDUSSQLPEXESQLPFRSSQLPGBCSQLPHEPSQLPLFFSQLPLRDSQLPNIE


Bulk Execute

put

ing a

s ment

ut

are

re run-

r

SQLPPCXSQLPRESSQLPVER

Bulk ExecuteThe number of multi-row inserts and deletes is determined by the size of the outmessage buffer. This can be set by the following function:

• sqloms() -- Set the message buffer size.

You can use several functions to control and manipulate data:

• sqlblk() -- Enable and disable bulk execute.

• sqlbef() -- Flush data from the execute buffer.

• sqlber() -- Return error codes for bulk execute operations.

You cannot use bulk execute if a SQL statement has any long data types (includCHAR or VARCHAR greater than 254 bytes) as bind values. A call to sqlelo() notifies the SQL/API that a long data type column is involved and bulk execute iautomatically disabled. Bulk execute cannot be enabled until the next SQL stateis compiled.

Bulk execute is implemented in three steps:

1. Bulk execute accumulates rows of database commands until either the outpmessage buffer is full or the sqlbef() flushes the buffer out.

2. The application calls sqlexe() after each group of statements, but no messagessent out; bound column data accumulates in the buffer.

3. When the buffer is full or flushed left, SQLHost/DB2 batches the data into a network message. It then hands the message to the communications softwatime system, which sends it over the network to the database server.

Bind variablesYou can use bind variables wherever a data value is allowed, specifically with:

• WHERE clauses.

• VALUES clause in an INSERT statement.

• SET clauses in an UPDATE statement.

The bind variable name begins with a colon (:) and is followed by either a numbe(using the sqlbnn()function) or name (using the sqlbnd() function). For long data types, use sqlbln() and sqlbld(). For example,



ind ent,

al

te

ou

e the

ich file.

SELECT * FROM BOOKS WHERE AUTHOR = :1

SELECT * FROM BOOKS WHERE AUTHOR = :authWith DB2, you cannot reuse bind variables in the same statement. DB2 handlesdynamic SQL with bind variables by requiring the application to change all the bvariables to a question mark (?). If you re-use bind variables in the same statemDB2 cannot associate them because they all appear as question marks.

If you bind by number with sqlbnn(), the name of the variable must be the positionindicator of that variable in the statement. For example, a query with three bind variables should use variable names :1, :2, and :3. It would be incorrect to use variable names :1, :1, and :2.

Describe informationUsing the SQLPDIS parameter of sqlset(), you can control when (and if) describe information for a SELECT statement is sent to the client. You can use:

• SQLDELY -- To get the information after the compile but before the execu(the default setting).

• SQLDDLD -- To get the information after the execute.

• SQLDNVR -- To not get the describe information.

Using SQL/API functions with FERSThe SQL/API functions compatible with FERS (Frontend result sets) are:

• sqlcrs() -- Disables FERS (result set mode). Once this function is called, ycannot name or save result sets.

• sqlget() -- Use the SQLPFRS parameter to show if FERS are enabled. UsSQLPRES parameter to show the restriction mode.

• sqlims() -- Sets the size of the input message buffer for the application, whcan adjust the number of rows fetched at one time to put into the FERS

• sqlnrr() -- Forces a fetch of all rows.

• sqlprs() -- Repositions the cursor in a result set.

• sqlset() -- SQLPLRD changes the client result set directory.

• sqlsrs() -- Enables FERS and create the first result set file.

Note: Restriction sets are SQLBase feature and not available with any other database.


Processing LONG VARCHAR data

le

Processing LONG VARCHAR dataUse the following SQL/API functions to process LONG VARCHAR data:

Processing null dataDB2 does not support zero-length character strings with bind variables. To handnull values, use the SQL/API functions described below. In addition there is a setzerolengthstringstonull SQL.INI keyword that forces applications written withoutusing the correct bind functions to work with DB2 correctly.

Binding null dataTo bind null data, call either sqlbna() or sqlbnu() after calling sqlcom() and before calling sqlexe(). Both the sqlbna() function, which binds by name, and the sqlbnu() function, which binds by number, have an argument for the null indicator.

SQL/API Function Description

sqlrlo() Read a LONG VARCHAR column.

sqlgls() Return the number of bytes in a LONG VARCHAR column.

sqllsk() ;Set a position within a LONG VARCHAR column to start reading.

sqlbld()Associate a bind variable with an alphanumeric name for a LONG VARCHAR column in a SQL statement to a program variable.

sqlbln()Associate a bind variable with a numeric name for a LONG VARCHAR column in a SQL statement to a program variable.

sqlwlo() Write a LONG VARCHAR column.

sqlelo() End a long operation after reading or writing a LONG VARCHAR column



s

or

s

ows

first

Checking the null indicatorUse the sqlgdi() function (get describe information) to find out if the null indicator iset. The sqlgdi() function also returns everything that the sqldsc() and sqldes() functions return.

Fetching null dataBy default, sqlfet() returns 0 (successful) in the pfc variable (set by the sqlssb() function) if the value of a column is null. This default maintains compatibility withreleases of Centura's SQLBase and related connectivity tools prior to version 5.

To set the pfc variable so that it returns the FETRNUL status to indicate whether not the fetched column has a null value, turn on SQLPNIE.

For example, to instruct sqlfet() to return FETRNUL for the fetch on cursor_1 for the first item in the SELECT list into character buffer data, call:

sqlssb (cursor_1, 1, SQLBUF, 1, 1, 0,

SQLNPTR, FETRNUL)

Pre-fetching rowsWhen sqlexe() or sqlcex() is called, the first group of rows is automatically fetched afollows:

• sqlexe() executes the SELECT statement and fetches the first group of rin one message exchange.

• sqlcex() compiles and executes the SELECT statement, and fetches thegroup of rows in one message exchange.

If the SQLPDIS parameter is set to SQLDELY (early) or SQLDDLD (delayed) theserver sends the describe information before the first group of rows in the samemessage.



Chapter 6

Using Quest

This chapter discusses issues that arise when using Quest with SQLHost.


Chapter 6 Using Quest

t’s

earn ation

ata n. E d pre-

hat help

trict icant

t ral alid

bles

t

About QuestQuest is a 16 bit client/server query and reporting tool for SQL databases. Quesactivity modules let you access and manipulate data from relational databases supported by SQLHost.

Quest lets you build queries through pointing and clicking, reducing the need to lSQL. You can save time and standardize a corporate look easily by pre-buildingqueries and formulas and saving them as templates for everyone in your organizto use.

The powerful Quest report writer generates reports quickly and easily from any dsource. You can tailor your reports with formatting, formulas, and object insertioThe Quest report writer fully supports Microsoft Windows standards, such as OLand DDE, so you can share data with other Windows applications, as well as adexisting images to new reports.

Building forms is also easy with Quest. You can develop form-based interfaces tquery and update data from SQL databases. This form-based interface can alsoyou as a developer by providing application prototyping facilities like full master/detail relationships, field validation, and table lookup forms.

Accessing DB2 system catalog information using QuestQuest uses a series of Centura predefined SQL queries that operate against theSYSSQL views installed with SQLHost.

The Views script is designed to be generic. It can be tuned at the user site to resthe data made available to Quest. Tuning the SYSSQL views can result in signifQuest performance improvement.

For example:

The SYSSQL.SYSTABLES view is designed to return only the tables the currenuser id has some authority for. To do this, the view does a select that joins seveDB2 subsystem tables. The view uses a join because the UNION syntax is not vin a view. This query is known to be very slow.

An option would be to remove the table join from the query understanding the taQuest displays are not necessarily all available to the user.

Other parameters can be added to the view to restrict the tables returned if, for instance, it is known that only a subset of the tables should be available to Quesusers.

Additional changes might be to add the secondary authids to the authority checkjoins.


Improving access to system catalog information

ng

, t:

base

ecial ote user.

f talog base m

ified.

.

Before using Quest verify you have a valid 16 bit Windows connections by readiSetting up SQLTalk Connection in Ch. 11 of the Centura SQLHost Installation and Operation Guide.

Improving access to system catalog informationBecause end-user data management tools need information about lists of tablesviews, and columns, they must frequently access the system catalog. As a resul

• System degradation, or locking and contention problems, can make dataperformance unacceptably slow.

• Remote databases, especially those on a WAN, suffer performance degradation and financial costs for each query/response cycle.

• Database systems with large numbers of tables are slow to respond.

• catalog on the client’s local server. The catalog cache is a cache is a spSQLBase database called SQLCAT that contains a snapshot of the remdatabase’s system catalog. The cache is managed separately for each

• To help solve some of these problems, Quest can reduce the number oqueries from the client to a remote database by "caching" the system caon the client’s local server. The catalog cache is a special SQLBase datacalled SQLCAT that contains a snapshot of the remote database’s systecatalog. The cache is managed separately for each user.

Although catalog information is cached, data is retrieved from the database specThis assures that you always get the latest data.

To use catalog caching with a remote server during a Quest session, the local SQLBase server, (sqldbw or sqlwsv ), must be the first comdll listed in the [winclient.dll] section of the SQL.INI file.

Customizing table creationYou can customize Quest table creation to use table spaces on your DB2 system

Creating tables in table spaces1. From the activity bar, select the appropriate database.

2. Choose Database Configure (Alt, U, D, C) from the Utilities menu.

Quest displays the Configure Database dialog box.

3. Click Options.

4. Type databasename.tablename in the Additional Create Table Parameters field.


Chapter 6 Using Quest

then

ase,

For more information about the Database Configure dialog box, read the Quest User’s Guide.

Extracting dataTo extract data from one database and put it into another with Quest, you can:

• Create a new table from a table that has the data or definition you want, copy and paste data from one table to another.

• Extract data into a .CSV data file, then import the .CSV file into the newdatabase.

For more information, read Quest User’s Guide.

Improving performance by minimizing lockingUsing Quest may at times result in locks being applied against the remote databreducing performance. To minimize this:

• Bind for maximum concurrency.

• Complete updates, rather than leaving them outstanding.

• Minimize the number of open Quest activities.


h

Chapter 7

Using DBExplorer

This chapter discusses how to use Centura Database Explorer (DBExplorer) witSQLHost.


Chapter 7 Using DBExplorer

ws/

ased

rces.

nts t a r that bases

lick

to

e of ence eep

About DBExplorerDatabase Explorer (DBExplorer) provides a consistent and unified designtime interface for accessing databases that is fully integrated into Centura SQLWindo32. You can create, browse, and modify database components such as:

• Tables

• Indexes

• Views

Database Explorer lets you create a consistent programming interface for callingstored procedures using Scalable Application Language (SAL) across different database platforms.You accomplish this by generating SAL functional classes bon stored procedures.

Database Explorer also lets you design and create reports. You can:

• Design and print various types of reports to meet your reporting needs.

• Format each report element with easily accessible formatting options.

• Display summary calculations to neatly arrange your report.

• Import and display graphics from different sources.

• Design a report template you can use repeatedly with different data sou

When you first open Database Explorer, it lists the database brand in the Contetab. You can expand the tree view to list the database brands there. If you selecdatabase brand in the tree view, the Contents tab lists the running databases fobrand. You can also expand a database brand in the tree view to list running datathere.

To connect to a database, double-click it in either view. Fill in the Login tab and cConnect. After you connect, the tree view and the Contents tab contain four components:

• Tables

• Views

• Indexes

Click the component you want to display or right-click the database component create a new one.

When you are viewing the contents of Tables, Indexes, or Views you can click onthe items and enter a letter on the keyboard to move the focus to the first occurrof an item that begins with that letter. To move the focus down the set of items, kentering that letter.


Using DBExplorer with SQLHost

e

dow,

, the ent. If n.

olbar. urn

o use wse on an

e t tility.

lid ps

e

For connectivity information, read the book, Connecting Centura Objects to Databases. You can read the printed version, or you can read it online (if you havinstalled the Centura Books online component).

Context (right-click) menus Context menus that you display by pressing the right mouse button show menu options available in a particular context like a database, item in the database, winportion of a window, or even column in a table.

Sorting columnsTo sort items displayed on the Contents tab, click a column header. For exampleContents tab has columns in this order: Tables, Table Creator, Label, and Commyou click Table Creator, items are resorted according to the names in this colum

Database Menu and Database Explorer toolbarYou can select tasks either from the Database menu or the Database Explorer toIf you do not want to use the toolbar, you can turn it off and hide it from view. To tit off, select Views, Toolbars.

To help developers work with all database schemes, DBExplorer includes easy tscheme management functionality. Centura Database Explorer allows you to brocreate or modify datatbase object like table views and indexes. Since it is based intuitive explorer mataphor, it simplifies database structure navigation. It also includes full data preview capabilites for quickly reviewing database content. ThDBExplorer works with all popular data sources in the same easy and consistenmanner. You can write queries, edit data, and execute SQL scripts all from one u

Using DBExplorer with SQLHostBefore attempting to use DBExplorer with SQLHost first verify that you have a va32 bit connection from your windows workstation to SQLHost by following the stein the Testing Connections with SQLTalk section in Chapter 3.

After you have verified you connection to SQLHost with the 32 bit SQLTalk, maksure the SQL.INI used with the SQLTalk connection is the same SQL.INI in the directory with SQLWindows 32 bit (Centura Team Developer)

1. Start SQLWindows 32 bit by clicking on the icon in the program group.

2. From the Database menu select Open Database Explorer

3. Expand the Database Explorer tree by clicking on the ‘+’ icon.

4. Right click on DB2 in the Database Explorer tree.

5. From the context menu select Add To List.



.

es. ript

was

d of

ry. entire educe the est

6. On the Add To List window select the Database tab

7. Fill in the database, userid and password fields for the SQLHost connection

8. Click OK.

At this point DBExplorer will show you tree branches for Tables, Views and IndexIf you expand any of these trees DBExplorer queries SQLHost for a list of all theTables, Views or Indexes. The query is performed against the SYSSQL views scinstalled with SQLHost.

The data returned from the query will depend somewhat on how the views scriptinstalled. The default script does a two or three table UNION select against SYSIBM.SYSTABLES, SYSIBM.SYSTABAUTH and SYSIBM.SYSUSERAUTH.The purpose of this union is to return just a list of the tables that the userid you connected with has some sort of authorization for the reason it’s a UNION insteaa JOIN is because VIEWS do not support JOIN.

Unfortunately the result of this three way table UNION is a long running DB2 queAlso because of the way the DB2 database is setup a list of all the tables in the database may be quite a few tables. It is possible to tune these queries and to rthe number of tables returned by the queries but this should start with adjusting VIEWS script for SYSSQL that was installed with SQLHost. DBExplorer and Quare the only Centura applications using these views.


Creating a Table with DBExplorer and SQLHost

.

h and

rer

ript

ee

Creating a Table with DBExplorer and SQLHostNow that you have connected successfully to SQLHost it’s time to create a table

View the DBExplorer database tree so that you see the SQLHost dbname brancthree subbranches labelled TABLES, VIEWS, INDEXES.

A success dbname connection.

9. Right click on the Tables icon to get the context menu. At this point DBExplowill retrieve a list of all tables defined to DB2. What tables are retrieved are determined by the userid you connected with and the syntax of the views scinstalled with SQLHost.

10. From the context menu select NEW TABLE. On the right pane you should sthe CREATE TABLE dialog.



name will

ame ns

ta ale

B2

been

T

11. In the field TABLE NAME type the name of the table you wish to create. Remember that DB2 restricts this name to 8 characters. Make sure this tableis in upper case. If the table name is not in upper case problem retrieving dataoccur.

12. Enter an optional table LABEL and DESCRIPTION.

13. Tab to the column description table window in the middle of the pane. In the nfield enter the name of the first column. Remember that DB2 restricts columnames to 8 characters.

14. Tab to the DATA TYPE column. A drop down list box appears. Select the datype of the column. Depend on the data type selected the Width and the Sccolumns will be enabled.

15. Tab to the WIDTH and SCALE columns and type appropriate values for a Dtable.

16. Continue to enter values for the columns descriptions until all columns have entered.

17. Note that at the bottom of the right hand pane is a field labelled OPTIONALCREATE TABLE PARAMETERS. If you need to enter additional CREATE TABLE parameters such as the IN clause, EDITPROC, VALIDPROC, AUDIor LIKE clause enter those parameters here.



ght

he its.

s te an

A table created with three columns and an IN clause.

18. Now it is time to create the table and move on to inserting the data. Either riclick on the table window (where the columns are listed) and select APPLY EDITS from the context menu, or right click on the UNTITLED table name on tleft pane. A message box will appear asking you if you want to save your edSelect YES. At this point DBExplorer will CREATE the table.

19. You will not be able to insert data into the table because DBExplorer requiretables to have atleast one unique index to control table modifications. To creaindex Select the INDEXES branch on the left pane under the datase name.

20. Type in the INDEX name, the table name and select the UNIQUE INDEX checkbox and select atleast one column to use as the index.

21. Select OK.



w ata

ill

er is

Creating the index.

22. After the index is created you will see the INDEX INFORMATION table windowhere you can modify the index if necessary. You are now ready to insert dinto your table.

23. Reselect your table from the TABLES branch.

24. Select the DATA tab on the bottom of the left pane. DBExplorer then issuesqueries to retrieve all the data that is currently in the table.

25. Hit the Insert key while focus is on the left pane. A table window insert row wappear half way down the table window.

26. Type in the row data . Continue inserting rows until the data you want to entcomplete.



into

New data about to be inserted.

27. Right click on the table window and select APPLY EDITS to insert the data the table. DBExplorer then issues the appropriate insert statement and thenrefreshes the table windows with a new select of the data.



ion.

The data is now inserted and committed to the database.

28. Disconnect from DB2 by selecting Disconnect from the Database menu opt


en t.


Chapter 8

Data Type Implementation

This chapter provides information about data types. This information is useful whwriting or modifying applications that access data sources supported by SQLHos


Chapter 8 Data Type Implementation

es.

t

ata

tions.

or

Translating data typesWhen writing SQLWindows applications, you use the SQLWindows program typThese types are converted internally to equivalent "database" data types — the SQLD* types returned by sqldes(). Quest uses the "external" data types — the SQLE* types returned by sqldsc().

Client application program types do not have the same granularity as DB2, and SQLBase column types. Especially when working with long data types, you musmake provisions to mitigate:

• Limitation of STRINGs by the SQL/API to 254 bytes.

• Distinction in many databases that prevents you from inserting CHAR d(or simply data retrieved into a STRING) back into a numeric data field.

• Differences in granularity that may reduce the precision and or scale of numeric data types and compromise data integrity.

• Differences in maximum sizes that may result in truncated data (and compromise data integrity).

This chapter describes the differences and describe the impact on client applica

Note: SQLWindows does not have direct access to the bind API. When you insert DATETIME data into DB2 with bind variables, you must use the Format option to supply DB2 with bind information. For more information, read DATE and TIME on page 8-65.

Data type support for SQLNetwork.

SQLWindows Data Type

SQL/API External Type (and length)

Column Types for

DB2 DB2/2 SQLBase

STRING SQLECHR1 ≤ n ≤ 254

CHARDefault: 1

1 ≤ n ≤ 254

CHAR1 ≤ n ≤ 254Default: 1

CHAR1 ≤ n ≤ 254Length specification required.

SQLEVAR1 ≤ n ≤ 254

VARCHAR1 ≤ n ≤ M

VARCHAR1 ≤ n ≤ 4,000

VARCHAR1 ≤ n ≤ 254Length specification required.

LONG STRING SQLELON LONG VARCHARMax. length

LONG VARCHAR1 ≤ n ≤ 32,700

LONG VARCHAR

no maximum


Maximum record size

ROC

p = precision (the total number of digits)

s = scale (the number of digits to the right of the decimal point)

M = a value that depends on the physical structure of the database.

Maximum record sizeDB2 imposes restrictions on the maximum record size. For DB2, the maximum record size depends on the page size of the table space and whether the EDITPclause of the CREATE TABLE command is specified.

The following table illustrates the range of maximum record sizes for DB2.

NUMBER

Formats: unformatted, currency, decimal, invisible, or percentage.

Maximum # of characters=22

SQLEDEC DECIMAL (DEC)1 ≤ p ≤ 31

0 ≤ s ≤ precision of #

n = 1 - 1031 to 1031 - 1

DECIMAL/DEC1 ≤ p ≤ 31

0 ≤ s≤ precision of #

n = 1 - 1031 to 1031 - 1

DECIMAL/DEC1 ≤ p ≤ 15;

0 ≤ s≤ precision of #

n = 1 - 1015 to 1015 - 1

SQLEFLO REAL/FLOAT~5.4E-79 ≤ n ≤ 7.2E+75

DOUBLE PRECISION~5.4E-79 ≤ n ≤ 7.2E+75

FLOAT-1.79769E+308 ≤ n ≤ -2.225E-307;2.225E-307 ≤ n ≤ -1.79769E+308;also n = 0

REAL

FLOAT

DOUBLE PRECISION22 ≤ p ≤ 53

SQLEINT INTEGER/INT-2,147,483,648≤ n ≤ +2,147,483,647

INTEGER-2,147,483,64 ≤ n ≤ +2,147,483,647

INTEGER-2,147,483,648 ≤ n ≤ +2,147,483,647

p: up to 10 digits

SQLESMA SMALLINT-32,768 ≤ n ≤ +32,767

SMALLINT-32,768 ≤ n ≤ +32,767

SMALLINT-32,768 ≤ n ≤ +32,767

p: up to 5 digits

DATE/TIME

Format: Date, Time, Date/Time, Invisible

SQLEDAT DATE DATE DATE

SQLETIM TIME TIME TIME

SQLETMS TIMESTAMP TIMESTAMP TIMESTAMP

EDITPROC ON? Page Size = 4 KB Page Size = 32 KB

NO 4,056 32,714

YES 4,046 32,704

SQLWindows Data Type

SQL/API External Type (and length)

Column Types for

DB2 DB2/2 SQLBase



d in

Gs.

tions

to ary, e

s can

mn

a

STRINGSQLWindows STRING data items have no length restriction. However, when useconjunction with the SQL/API and CHAR and VARCHAR data types, they are limited to 254 bytes. Treat the data items longer than 254 bytes as LONG STRINQuest users see a LONG column if the selected item is really a CHAR or a VARCHAR with length greater than 254. SQL/API applications must use the appropriate functions for processing long data. SQL/API developers should get describe information if any doubt exists about the correct data type, and use functhat process long data as appropriate.

LONG STRINGSQLHost currently limits SQLWindows long strings to SQLELON, which includes data longer than 254 bytes of CHAR and VARCHAR.

When a client application communicates with SQLHost, it uses a LONG columnhold all types of long data. SQLWindows makes no distinction between text, binor other long data types. The data length is unlimited; SQLWindows functions usSQL/API calls sqlwlo() to write long data and sqlrlo() to read it.

Client applications can process any long data in block mode. SQLHost databasestore strings of unlimited lengths (given enough disk space) in tables with LONGfields, or LONG VARCHAR fields of unspecified length.

SQLHost maps CHAR and VARCHAR columns greater than 254 bytes to LONGSTRING data types (LONG VARCHAR). You can use the following SQL/API functions to process these LONG VARCHAR mapped data types:

• sqlrlo() – Read a LONG column.

• sqlgls() – Return the number of bytes in a column.

• sqllsk() – Set a position within a column to start reading.

• sqlbld() – Associate a bind variable with an alphanumeric name for a coluin a SQL statement to a program variable.

• sqlbln() – Associate a bind variable with a numeric name for a column inSQL statement to a program variable.

• sqlwlo() – Write a LONG column.

• sqlelo() – End a long operation after reading or writing column.


NUMBER

ter ot

an 23

ion.

:

PI

ed ble

n

fault or

fy

NUMBERCentura’s products allow a maximum of 22 characters of numeric data. If you ennumeric data with character string presentation, make sure that the string does nhave more than 22 characters. A SQL statement with numeric data longer than 22 characters generates the error "invalid number". The output value is also less thcharacters, if presented in character string format. If the data has more than 22 characters, it is presented in exponential format, resulting perhaps in less precis

Floating point numbers in DB2 have a range of magnitude that is approximately

5.4 x 10-79 < n > 7.2 x 1075Candidates for floating point bind variables are numbers in scientific notation, ornumbers where the precision is greater than 22, because this is what the SQL/Asupports.

Any number that is a candidate for a floating point bind variable in DB2 is checkbefore being used. If the API determines that the number falls outside the acceptarange, the client receives an error message.

Floating point columns fetched from DB2 tables are displayed in scientific notatioby the client application. The precision is accurate to 14 decimal digits.

DATE and TIMEInternally, SQLWindows stores the DATE and TIME data types in a format that includes both date and time values. For DATE data, SQLWindows supplies a dezero value for time. For TIME data, SQLWindows supplies a zero default value fthe date portion.

If you insert SQLWindows DATE or TIME data into DB2 with bind variables, specithe format of the data using the Format option of the fields Customizer. This tells SQLWindows how to bind the data.

For example, in the United States, select the MM-dd-yy format for DATE data, and the hh:mm:ss AMPM format for TIME data.

Note: If you do not format DATE or TIME data as described above, DB2 rejects the data because SQLHost cannot correctly truncate the bind data .



se or eans

NULLsNull values (NULLS) are special values that can appear as column values in a baderived table. The designation is intended to represent an unknown value and m"information missing". Arithmetic and scalar comparison operators treat nulls according to very specific rules.

The following SQL/API functions work with NULLS:

• sqlbna() and sqlbnu() both have an argument for the NULL indicator. Callone of them after sqlcom() and before sqlexe() to bind NULL data.

• sqlgdi() returns the NULL indicator for a column in a SELECT list, in addition to returning all the descriptive information that sqldes() and sqldsc() return.

• sqlfet() returns 0 (successful) in the pfc variable (allocated by the sqlssb() function) if the value of a column is NULL. This default maintains compatibility with versions of SQLBase prior to version 5 and related connectivity tools.

To set the pfc variable so that it returns the FETRNUL status to indicate that the fetched column has a NULL value, turn on SQLPNIE.


Index
Aarray processing 5-5autocommit
multiple execute statements 2 - 2

Bbind variables

by number 5-6re-using in the same SQL statement 5-6See also program variables, SQL/API 5-5with dynamic SQL 5-6

bufferssetting size of 5-6

bulk executelong data types 5-5

Ccatalog cache 6-3columns

headings for derived 2 - 7cursors

creating additional 2 - 4maximum number 2 - 5simultaneous connections 2 - 4

Ddata

extracting, in Quest 6-4data dictionaries. See system catalogs 2 - 19data types

convertingDATE/TIME 8-3LONG STRING 8-2NUMBER 8-3STRING 8-2

LONG VARCHARassociating bind variable to program variable 5-7returning number of bytes 5-7setting position for reading 5-7terminating a read or write 5-7writing 5-7

DATE. <See>See data typesDBP_PRESERVE 2 - 5derived columns. See columns 2 - 7

Eenvironment variables

Quest catalog cache 6-3

errorsno compiled command 2 - 5

FFERS

changing directory 5-6creating first file 5-6disabling 5-6enabling 5-6forcing fetch of all rows 5-6repositioning cursor 5-6showing if enabled 5-6showing restriction mode 5-6supported SQL/API functions 5-6

FETRNUL 4-5, 5-8

Iisolation levels 2 - 7

Llocking

minimizing, in Quest 6-4LONG VARCHAR

processing 5-7LONG VARCHAR. See data types 5-7LONG. <See>See data types

Mmulti-row inserts and deletes. See array processing 5-5

Nnull

databinding 4-4, 5-7checking the null indicator 4-4, 5-8fetching 4-5, 5-8processing 4-4, 5-7

NUMBER. <See>See data types

Ppfc variable 4-5, 5-8prefetching rows 5-8

QQuest

catalog cache 6-3introduced 6-2

SQLHost Client Developer’s Guide Index-1

Index

Ssetting

Quest catalog cache 6-3SQL.H 5-2SQL/API

and bind variables 5-5describe information

when sent to client 5-6introduced 5-2

SQL/API functionssqlbef() 5-5sqlber() 5-5sqlbld() 5-5, 5-7sqlblk() 5-5sqlbln() 5-7sqlbna() 4-4, 5-7sqlbnd() 5-5sqlbnn() 5-5sqlbnu() 4-4, 5-7sqlcrs() 5-6sqldes() 2 - 7, 4-4, 5-8sqldsc() 2 - 7sqlelo() 5-7sqlfet() 4-5, 5-8sqlgdi() 2 - 7, 4-4, 5-8sqlget() 5-6sqlget() parameters 5-4sqlgls() 5-7sqlims() 5-6sqllsk() 5-7sqlnrr() 2 - 10, 5-6sqloms() 5-5sqlprs() 5-6sqlrlo() 5-7sqlset() 5-6sqlset() parameters 5-4sqlsrs() 5-6sqlwlo() 5-7supported in SQLNetwork 5-2

SQLDDLD 5-6, 5-8SQLDELY 5-6, 5-8SQLDNVR 5-6SQLECHR 8-2SQLPDIS 5-6, 5-8SQLPNIE 4-5, 5-8SQLPPCX 2 - 5SQLWindows functions

SqlGetResultSetCount() 2 - 10

STRING. <See>See data typessystem catalogs

accessing 6-3

Ttables

customizing creation of in Quest 6-3TIME. <See>See data types

Index-2 SQLHost Client Developer’s Guide

Documents

Centura SQLHost Client Developer's Guide - Index of