Adaptive Server Anywhere Guide de programmation - Sybase

Adaptive Server ®
Anywhere
Guide de programmation
Dernière mise à jour : Octobre 2002
Réf. du document : 03945-01-0802-01

Copyright © 1989–2002 Sybase, Inc. Copyright partiel © 2001-2002 iAnywhere Solutions, Inc. Tous droits réservés.
Tout ou partie de cette publication ne peut être reproduit, transmis ou traduit, sous quelque forme ou par quelque moyen que ce soit (électronique,
mécanique, manuel, optique ou autre) sans l'accord écrit préalable d'iAnywhere Solutions, Inc. iAnywhere Solutions, Inc. est une filiale de Sybase,
Inc.
Sybase, SYBASE (logo), AccelaTrade, ADA Workbench, Adaptable Windowing Environment, Adaptive Component Architecture, Adaptive Server,
Adaptive Server Anywhere, Adaptive Server Enterprise, Adaptive Server Enterprise Monitor, Adaptive Server Enterprise Replication, Adaptive
Server Everywhere, Adaptive Server IQ, Adaptive Warehouse, AnswerBase, Anywhere Studio, Application Manager, AppModeler,
APT Workbench, APT-Build, APT-Edit, APT-Execute, APT-FORMS, APT-Library, APT-Translator, ASEP, Backup Server, BayCam, Bit-Wise,
BizTracker, Certified PowerBuilder Developer, Certified SYBASE Professional, Certified SYBASE Professional (logo), ClearConnect, Client
Services, Client-Library, CodeBank, Column Design, ComponentPack, Connection Manager, Convoy/DM, Copernicus, CSP, Data Pipeline, Data
Workbench, DataArchitect, Database Analyzer, DataExpress, DataServer, DataWindow, DB-Library, dbQueue, Developers Workbench, Direct
Connect Anywhere, DirectConnect, Distribution Director, Dynamo, e-ADK, E-Anywhere, e-Biz Integrator, E-Whatever, EC-GATEWAY, ECMAP,
ECRTP, eFulfillment Accelerator, Electronic Case Management, Embedded SQL, EMS, Enterprise Application Studio, Enterprise Client/Server,
Enterprise Connect, Enterprise Data Studio, Enterprise Manager, Enterprise SQL Server Manager, Enterprise Work Architecture, Enterprise Work
Designer, Enterprise Work Modeler, eProcurement Accelerator, eremote, Everything Works Better When Everything Works Together, EWA,
Financial Fusion, Financial Fusion Server, First Impression, Formula One, Gateway Manager, GeoPoint, iAnywhere, iAnywhere Solutions,
ImpactNow, Industry Warehouse Studio, InfoMaker, Information Anywhere, Information Everywhere, InformationConnect, InstaHelp, Intellidex,
InternetBuilder, iremote, iScript, Jaguar CTS, jConnect for JDBC, KnowledgeBase, Logical Memory Manager, MainframeConnect, Maintenance
Express, MAP, MDI Access Server, MDI Database Gateway, media.splash, MetaWorks, MethodSet, ML Query, MobiCATS, MySupport,
Net-Gateway, Net-Library, New Era of Networks, Next Generation Learning, Next Generation Learning Studio, O DEVICE, OASiS, OASiS (logo),
ObjectConnect, ObjectCycle, OmniConnect, OmniSQL Access Module, OmniSQL Toolkit, Open Biz, Open Business Interchange, Open Client,
Open Client/Server, Open Client/Server Interfaces, Open ClientConnect, Open Gateway, Open Server, Open ServerConnect, Open Solutions,
Optima++, Partnerships that Work, PB-Gen, PC APT Execute, PC DB-Net, PC Net Library, PhysicalArchitect, Pocket PowerBuilder,
PocketBuilder, Power Through Knowledge, Power++, power.stop, PowerAMC, PowerBuilder, PowerBuilder Foundation Class Library,
PowerDesigner, PowerDimensions, PowerDynamo, Powering the New Economy, PowerJ, PowerScript, PowerSite, PowerSocket, Powersoft,
Powersoft Portfolio, Powersoft Professional, PowerStage, PowerStudio, PowerTips, PowerWare Desktop, PowerWare Enterprise, ProcessAnalyst,
Rapport, Relational Beans, Replication Agent, Replication Driver, Replication Server, Replication Server Manager, Replication Toolkit, Report
Workbench, Report-Execute, Resource Manager, RW-DisplayLib, RW-Library, S Designor, S-Designor, S.W.I.F.T. Message Format Libraries,
SAFE, SAFE/PRO, SDF, Secure SQL Server, Secure SQL Toolset, Security Guardian, SKILS, smart.partners, smart.parts, smart.script,
SQL Advantage, SQL Anywhere, SQL Anywhere Studio, SQL Code Checker, SQL Debug, SQL Edit, SQL Edit/TPU, SQL Everywhere,
SQL Modeler, SQL Remote, SQL Server, SQL Server Manager, SQL Server SNMP SubAgent, SQL Server/CFT, SQL Server/DBM, SQL SMART,
SQL Station, SQL Toolset, SQLJ, Stage III Engineering, Startup.Com, STEP, SupportNow, Sybase Central, Sybase Client/Server Interfaces, Sybase
Development Framework, Sybase Financial Server, Sybase Gateways, Sybase Learning Connection, Sybase MPP, Sybase SQL Desktop, Sybase
SQL Lifecycle, Sybase SQL Workgroup, Sybase Synergy Program, Sybase User Workbench, Sybase Virtual Server Architecture, SybaseWare,
Syber Financial, SyberAssist, SybMD, SyBooks, System 10, System 11, System XI (logo), SystemTools, Tabular Data Stream, The Enterprise
Client/Server Company, The Extensible Software Platform, The Future Is Wide Open, The Learning Connection, The Model For Client/Server
Solutions, The Online Information Center, The Power of One, TradeForce, Transact-SQL, Translation Toolkit, Turning Imagination Into Reality,
UltraLite, UNIBOM, Unilib, Uninull, Unisep, Unistring, URK Runtime Kit for UniCode, Viewer, Visual Components, VisualSpeller, VisualWriter,
VQL, Warehouse Control Center, Warehouse Studio, Warehouse WORKS, WarehouseArchitect, Watcom, Watcom SQL, Watcom SQL Server,
Web Deployment Kit, Web.PB, Web.SQL, WebSights, WebViewer, WorkGroup SQL Server, XA-Library, XA-Server et XP Server sont des
marques de Sybase, Inc. ou de ses filiales.
Tous les autres noms de produit, société ou marque appartiennent à leurs propriétaires respectifs.
Dernière mise à jour : Octobre 2002. Réf. du document : 03945-01-0802-01.

Table des matières
Préface ............................................................................. vii
Documentation SQL Anywhere Studio ...................................viii
Conventions ............................................................................. xi
La base de données exemple Adaptive Server
Anywhere ................................................................................xiv
Source d'informations complémentaires................................. xv
1 Présentation de l'interface de programmation ................ 1
Interface de programmation ODBC ..........................................2
Interface de programmation OLE DB........................................3
Interface de programmation Embedded SQL ...........................4
Interface de programmation JDBC ...........................................5
Interface de programmation Open Client..................................6
2 Utilisation de SQL dans les applications ......................... 9
Exécution d'instructions SQL dans les
applications .............................................................................10
Préparation des instructions ...................................................12
Présentation des curseurs ......................................................15
Utilisation des curseurs...........................................................20
Choix d'un type de curseur .....................................................25
Curseurs Adaptive Server Anywhere......................................29
Description des jeux de résultats ............................................45
Contrôle des transactions dans les applications.....................47
3 Présentation de Java dans la base de données ............ 51
Introduction .............................................................................52
FAQ concernant Java dans la base de données....................55
Séminaire Java .......................................................................62
Environnement d'exécution pour Java dans la
base de données.....................................................................73
Didacticiel : Java dans la base de données -
Exercice pratique ....................................................................82
iii

4 Utilisation de Java dans la base de données ................ 91
Introduction ............................................................................. 92
Configuration de la base de données pour Java .................... 95
Installation de classes Java dans une base de
données ................................................................................ 101
Création de colonnes d'objets Java...................................... 106
Insertion, mise à jour et suppression d'objets
Java....................................................................................... 108
Recherche d'objets Java....................................................... 114
Comparaison des champs et des objets Java...................... 116
Fonctionnalités spéciales des classes Java dans
la base de données............................................................... 120
Stockage des objets Java..................................................... 127
Conception d'une base de données Java............................. 130
Utilisation de colonnes calculées avec les classes
Java....................................................................................... 134
Configuration de la mémoire pour Java................................ 137
5 Accès aux données via JDBC....................................... 139
Présentation de JBDC .......................................................... 140
Utilisation du gestionnaire JDBC jConnect ........................... 147
Utilisation de la passerelle JDBC-ODBC .............................. 152
Etablissement de connexions JDBC..................................... 154
Utilisation de JDBC pour accéder aux données ................... 162
Création d'applications distribuées ....................................... 171
6 Programmation avec Embedded SQL.......................... 177
Introduction ........................................................................... 178
Exemples de programmes Embedded SQL ......................... 186
Types de données Embedded SQL...................................... 192
Utilisation des variables hôte ................................................ 196
Zone de communication SQL (SQLCA)................................ 205
Lecture de données .............................................................. 211
SQL statique et SQL dynamique .......................................... 221
Zone descripteur SQL (SQLDA) ........................................... 226
Envoi et extraction de valeurs longues ................................. 235
Utilisation de procédures stockées ....................................... 241
Techniques de programmation Embedded SQL .................. 245
Préprocesseur SQL .............................................................. 247
Références des fonctions de bibliothèque............................ 251
Récapitulatif des commandes Embedded SQL.................... 270
iv

7 Programmation avec ODBC.......................................... 275
Présentation d'ODBC............................................................276
Création d'applications ODBC ..............................................278
Exemples ODBC...................................................................283
Descripteurs ODBC...............................................................285
Connexion à une source de données ...................................288
Exécution d'instructions SQL ................................................292
Jeux de résultats ...................................................................297
Appel de procédures stockées..............................................302
Gestion des erreurs...............................................................304
8 Interface Outils de base de données............................ 309
Introduction à l'interface Outils de base de
données ................................................................................310
Utilisation de l'interface Outils de base de
données ................................................................................311
Fonctions DBTools................................................................320
Structures DBTools...............................................................332
Types d'énumération DBTools..............................................364
9 Les interfaces de programmation OLE DB et
ADO ................................................................................ 367
Introduction à OLE DB ..........................................................368
Programmation ADO avec Adaptive Server
Anywhere ..............................................................................370
Interfaces OLE DB supportées .............................................378
10 Interface Open Client..................................................... 385
Préalables à la création d'applications
Open Client ...........................................................................386
Correspondances entre les types de données .....................387
SQL dans les applications Open Client ................................389
Limites d'Adaptive Server Anywhere avec Open
Client .....................................................................................392
11 Transactions distribuées et architecture à trois
niveaux ........................................................................... 393
Introduction ...........................................................................394
Architecture informatique à trois niveaux..............................395
Utilisation des transactions distribuées.................................399
Utilisation d'EAServer avec Adaptive Server
Anywhere ..............................................................................401
v

12 Déploiement de bases de données et
d'applications ................................................................ 405
Présentation du déploiement ................................................ 406
Répertoires d'installation et noms de fichiers ....................... 409
Utilisation des objets et modèles InstallShield
pour le déploiement .............................................................. 414
Déploiement avec une installation silencieuse ..................... 416
Déploiement des applications clientes.................................. 420
Déploiement des outils d'administration ............................... 431
Déploiement des serveurs de base de données .................. 432
Déploiement d'applications de base de données
embarquées .......................................................................... 435
13 Messages d’erreur du préprocesseur SQL.................. 439
Messages d'erreur du préprocesseur SQL
indexés par valeur de message d'erreur............................... 440
Erreurs SQLPP ..................................................................... 444
vi
Index............................................................................... 461

Préface
Présentation
A qui s'adresse ce
manuel ?
Ce manuel explique comment construire et déployer les applications de base
de données à l'aide des langages de programmation C, C++ et Java. Les
utilisateurs de Visual Basic et PowerBuilder peuvent recourir aux interfaces
de programmation fournies par ces outils.
Ce manuel s'adresse aux développeurs d'application qui écrivent des
programmes fonctionnant directement avec l'une des interfaces d'Adaptive
Server Anywhere.
Si vous utilisez un outil de développement tel que PowerBuilder ou Visual
Basic, lesquels disposent de leur propre interface de base de données audessus
d'ODBC, vous n'êtes pas concerné par ce manuel.
vii

Documentation SQL Anywhere Studio
viii
Ce manuel fait partie de la documentation SQL Anywhere Studio. Cette
section décrit les différents manuels de la documentation et explique
comment les utiliser.
La documentation de SQL Anywhere Studio
La documentation de SQL Anywhere Studio comprend les manuels
suivants :
♦ Présentation de SQL Anywhere Studio Ce manuel présente les
technologies de gestion de base de données et de synchronisation
offertes par SQL Anywhere Studio. Il inclut des didacticiels destinés à
vous initier aux différentes parties qui composent SQL Anywhere
Studio.
♦ Nouvelles fonctionnalités de SQL Anywhere Studio Ce manuel
s'adresse aux utilisateurs des versions antérieures du logiciel. Il
répertorie les nouvelles fonctionnalités de la version actuelle et des
versions précédentes du produit et décrit les procédures de mise à
niveau.
♦ ASA - Mise en route Ce manuel s'adresse aux utilisateurs qui
découvrent les bases de données relationnelles et Adaptive Server
Anywhere. Il permet de maîtriser rapidement le système de gestion de
base de données Adaptive Server Anywhere et inclut des présentations
sur la conception, la construction et l'exploitation des bases de données.
♦ ASA - Guide d’administration Ce manuel traite du lancement, de la
gestion et de la configuration des bases de données.
♦ ASA - Guide de l’utilisateur SQL Ce manuel explique comment
concevoir et créer des bases de données, comment importer, exporter et
modifier des données, comment récupérer des données et construire des
procédures stockées et des triggers.
♦ ASA - Manuel de référence SQL Ce manuel de référence fournit une
description complète du langage SQL utilisé par Adaptive Server
Anywhere. Il présente également les tables et procédures système
d'Adaptive Server Anywhere.
♦ ASA - Guide de programmation Ce manuel explique comment
construire et déployer les applications de base de données à l'aide des
langages de programmation C, C++ et Java. Les utilisateurs de Visual
Basic et PowerBuilder peuvent recourir aux interfaces de
programmation fournies par ces outils.

Formats de la documentation
♦ ASA - Messages d’erreur Ce manuel fournit la liste complète des
messages d'erreur d'Adaptive Server Anywhere, ainsi que des
informations de diagnostic.
♦ ASA - Système de sécurité C2 Dans le cadre des critères d'évaluation
de la sécurité des systèmes informatiques (TCSEC, Trusted Computer
System Evaluation Criteria), le gouvernement américain a décerné la
classe C2 à Adaptive Server Anywhere 7.0. Ce manuel s'adresse plus
particulièrement à ceux qui souhaitent utiliser la version actuelle
d'Adaptive Server Anywhere conformément aux exigences de
l'environnement certifié C2. Ce manuel n’inclut pas les fonctionnalités
de sécurité ajoutées au produit depuis la certification.
♦ Synchronisation MobiLink - Guide de l’utilisateur Ce manuel décrit
tous les aspects du système de synchronisation des données MobiLink
pour l'informatique mobile, qui permet le partage des données entre une
base Oracle, Sybase, Microsoft ou IBM unique et plusieurs bases de
données Adaptive Server Anywhere ou UltraLite.
♦ SQL Remote - Guide de l’utilisateur Ce manuel décrit tous les aspects
du système de réplication des données SQL Remote pour l'informatique
mobile. Ce système permet le partage des données entre une seule base
Adaptive Server Anywhere ou Adaptive Server Enterprise et plusieurs
bases de données Adaptive Server Anywhere via un lien indirect tel que
la messagerie électronique ou le transfert de fichiers.
♦ UltraLite - Guide de l’utilisateur Ce manuel décrit comment construire
des applications de base de données pour de petits périphériques tels que
les organiseurs de poche, à l'aide de la technologie de déploiement
UltraLite pour les bases de données Adaptive Server Anywhere.
♦ UltraLite User’s Guide to PenRight! MobileBuilder (disponible en
version anglaise seulement) Ce manuel s'adresse aux utilisateurs de
l'outil de développement PenRight! MobileBuilder. Il décrit comment
utiliser la technologie UltraLite dans l'environnement de programmation
MobileBuilder.
♦ SQL Anywhere Studio - Aide Ce manuel est exclusivement disponible
en ligne. Il inclut l'aide contextuelle de Sybase Central,
d'Interactive SQL et d'autres outils graphiques.
PowerAMC et InfoMaker disposent également de leur propre documentation
en ligne.
La documentation de SQL Anywhere Studio se présente sous les formats
suivants :
ix

x
♦ Documentation en ligne Elle inclut toute la documentation de
SQL Anywhere Studio, y compris les livres imprimés et l'aide
contextuelle des outils SQL Anywhere. Elle est mise à jour à chaque
version de maintenance du produit et constitue la source de
documentation la plus complète et la plus récente.
Pour accéder à la documentation en ligne sous les systèmes
d'exploitation Windows, choisissez Démarrer➤Programmes➤Sybase
SQL Anywhere 8➤Documentation en ligne. Vous pouvez explorer cette
documentation à partir du sommaire, de l'index et à l'aide de la fonction
de recherche de l'Aide HTML dans le volet gauche ou en utilisant les
liens et les menus dans le volet droit.
Pour accéder à la documentation en ligne sous les systèmes
d'exploitation UNIX, exécutez la commande suivante à l'invite de
commandes :
dbbooks
♦ Manuels imprimables Les manuels SQL Anywhere sont fournis sous
format PDF et se lisent avec Adobe Acrobat Reader.
Les fichiers PDF sont disponibles sur le CD-ROM dans le répertoire
pdf_docs. Vous pouvez décider de les installer lors de l'exécution du
programme d'installation.
♦ Manuels imprimés Le coffret SQL Anywhere Studio comprend les
manuels suivants :
♦ Présentation de SQL Anywhere Studio
♦ ASA - Mise en route
♦ SQL Anywhere Studio Guide de référence rapide. Ce manuel est
exclusivement disponible sous forme imprimée.
La totalité des manuels est disponible sous le nom de Documentation
SQL Anywhere auprès de Sybase ou à la boutique en ligne de Sybase,
l'e-Shop, à l'adresse suivante : http://e-shop.sybase.com/cgibin/eshop.storefront/.

Conventions
Conventions syntaxiques
Cette section décrit les conventions syntaxiques, typographiques et
graphiques employées dans ce manuel.
Les exemples de syntaxe SQL s'appuient sur les conventions suivantes :
♦ Mots-clés Tous les mots-clés SQL sont indiqués en majuscules. Par
exemple :
ALTER TABLE [ propriétaire.]nom_table
♦ Marques de réservation Les éléments à remplacer par des expressions
ou des identificateurs appropriés apparaissent en italique. Par exemple :
ALTER TABLE [ propriétaire.]nom_table
♦ Eléments répétitifs Dans une liste contenant des éléments qui se
répètent, le nom d'un élément de la liste est suivi de points de suspension
(...). Par exemple :
ADD définition_colonne [ contrainte_colonne, … ]
Une liste peut comprendre un ou plusieurs éléments. Dans ce dernier
cas, les éléments sont séparés par une virgule.
♦ Eléments facultatifs Les éléments facultatifs d'une instruction sont
placés entre crochets.
RELEASE SAVEPOINT [nom_pointdesauvegarde]
Les crochets indiquent que le paramètre nom_pointdesauvegarde est
facultatif. Les crochets ne doivent pas être saisis.
♦ Options Lorsqu'un seul élément de la liste (ou aucun) doit être déclaré,
les éléments sont séparés par des barres verticales et la liste est placée
entre crochets.
[ ASC | DESC ]
Par exemple, vous pouvez choisir le paramètre ASC ou DESC, ou aucun
des deux. Les crochets ne doivent pas être saisis.
♦ Options obligatoires Lorsque vous devez obligatoirement spécifier une
valeur, les choix possibles sont placés entre accolades.
[ QUOTES { ON | OFF } ]
Si l'option QUOTES est sélectionnée, ON ou OFF doit également être
spécifié. Les crochets et les accolades ne doivent pas être saisis.
xi

Icônes
xii
♦ Options multiples Si vous choisissez plusieurs options, séparez vos
choix par des virgules.
{ CONNECT, DBA, RESOURCE }
Les icônes suivantes sont utilisées dans cette documentation :

Icône Signification
API
Application cliente
Serveur de base de données (par exemple, Sybase
Adaptive Server Anywhere ou Adaptive Server
Enterprise).
Application et serveur de base de données UltraLite.
Dans UltraLite, le serveur de base de données et
l'application font partie du même processus.
Base de données. Dans certains diagrammes élaborés,
l'icône peut servir à représenter à la fois la base de
données et le serveur qui la gère.
Middleware de réplication ou de synchronisation. Ils
participent au partage des données entre les bases.
Exemples : serveur de synchronisation MobiLink,
agent de message SQL Remote et agent de réplication
LTM qui sont utilisés avec le Replication Server.
Sybase Replication Server
Interface de programmation
xiii

La base de données exemple Adaptive Server
Anywhere
xiv
De nombreux exemples de la documentation font appel à la base de données
exemple Adaptive Server Anywhere.
La base de données exemple est stockée dans un fichier appelé asademo.db
et situé dans votre répertoire SQL Anywhere.
Cette base de données représente une petite société. Elle contient des
informations concernant la société (employés, services et finances), les
produits et les ventes (commandes, clients et contacts). Toutes les
informations contenues dans la base de données relèvent de la pure fiction.
La figure suivante montre les tables de la base de données exemple et leurs
relations.
product
id integer
name char(15)
description char(30)
size char(18)
color char(6)
quantity integer
unit_price numeric(15,2)
customer
id integer
fname char(15)
lname char(20)
address char(35)
city char(20)
state char(2)
zip char(10)
phone char(12)
company_name char(35)
contact
id integer
last_name char(15)
first_name char(15)
title char(2)
street char(30)
city char(20)
state char(2)
zip char(5)
phone char(10)
fax char(10)
id = prod_id
id = cust_id
asademo.db
sales_order_items
id integer
line_id smallint
prod_id integer
quantity integer
ship_date date
id = id
sales_order
id integer
cust_id integer
order_date date
fin_code_id char(2)
region char(7)
sales_rep integer
code = fin_code_id
emp_id = sales_rep
fin_code
code char(2)
type char(10)
description char(50)
code = code
fin_data
year char(4)
quarter char(2)
code char(2)
amount numeric(9)
employee
emp_id integer
manager_id integer
emp_fname char(20)
emp_lname char(20)
dept_id integer
street char(40)
city char(20)
state char(4)
zip_code char(9)
phone char(10)
status char(1)
ss_number char(11)
salary numeric(20,3)
start_date date
termination_date date
birth_date date
bene_health_ins char(1)
bene_life_ins char(1)
bene_day_care char(1)
sex char(1)
dept_id = dept_id
emp_id = dept_head_id
department
dept_id integer
dept_name char(40)
dept_head_id integer

Source d'informations complémentaires
Si vous avez des observations sur le contenu de cette documentation et sur le
logiciel, nous vous serions reconnaissants de nous en faire part.
Vous pouvez nous les adresser par l'intermédiaire des forums (newsgroups)
mis en place pour discuter des technologies de SQL Anywhere. Ces forums
sont accessibles sur le serveur forums.sybase.com.
Les forums se déclinent comme suit :
♦ sybase.public.sqlanywhere.general.
♦ sybase.public.sqlanywhere.linux.
♦ sybase.public.sqlanywhere.mobilink.
♦ sybase.public.sqlanywhere.product_futures_discussion.
♦ sybase.public.sqlanywhere.replication.
♦ sybase.public.sqlanywhere.ultralite.
Dédit de responsabilité pour les forums
La société iAnywhere Solutions n'est nullement tenue de fournir des
solutions, des informations ou des avis concernant ses forums. Elle n'est
pas dans l'obligation de fournir un service supplémentaire autre que celui
de l'opérateur système prévu pour contrôler le service et garantir son
fonctionnement ainsi que sa disponibilité.
Les conseillers techniques d'iAnywhere Solutions ainsi que d'autres
catégories de personnel participent à l'exploitation du forum lorsque leurs
disponibilités le leur permettent. Ils apportent leur aide de manière
bénévole et ne peuvent pas être disponibles régulièrement pour fournir des
solutions ou des informations. Leur aptitude à fournir une aide dépend de
leur charge de travail.
xv

xvi

CHAPITRE 1
Présentation de l'interface de
programmation
Présentation
Sommaire
Ce chapitre présente les interfaces de programmation
d'Adaptive Server Anywhere. Toute application cliente utilise une de ces
interfaces pour communiquer avec la base de données.
Sujet Page
Interface de programmation ODBC 2
Interface de programmation OLE DB 3
Interface de programmation Embedded SQL 4
Interface de programmation JDBC 5
Interface de programmation Open Client 6
1

Interface de programmation ODBC
Interface de programmation ODBC
2
ODBC (Open Database Connectivity) est une interface CLI (call level
interface) standard développée par Microsoft. Elle est fondée sur la
spécification CLI SQL Access Group. Les applications ODBC sont
exécutables sur n'importe quelle source de données dotée d'un pilote ODBC.
Vous devez utiliser ODBC si vous voulez que votre application soit
transférable vers d'autres sources de données disposant de pilotes ODBC. En
outre, si vous préférez utiliser une API, utilisez ODBC.
ODBC est une interface de bas niveau, semblable à Embedded SQL. Elle
permet d'accéder à la plupart des fonctionnalités
d'Adaptive Server Anywhere. ODBC est disponible sous la forme d'une DLL
dans tous les systèmes d'exploitation Windows à l'exception de
Windows CE. Pour UNIX, elle est fournie sous forme de bibliothèque.
Microsoft ODBC Software Development Kit constitue la documentation
principale d'ODBC. Ce manuel contient des notes complémentaires,
spécifiquement fournies à l'intention des développeurs
Adaptive Server Anywhere pour ODBC.
$ ODBC est décrit dans "Programmation avec ODBC", page 275.

Chapitre 1 Présentation de l'interface de programmation
Interface de programmation OLE DB
OLE DB est un ensemble d’interfaces COM (Component Object Model)
développées par Microsoft, qui fournissent aux applications un accès
uniformisé aux données stockées dans diverses sources d'information et
permettent de mettre en oeuvre des services de base de données
supplémentaires. Ces interfaces supportent les nombreuses
fonctionnalités SGBD appropriées à l'environnement de stockage, lui
permettant ainsi de partager ses données.
ADO est un modèle d'objet qui permet d'atteindre, de modifier et de mettre à
jour par programmation un grand nombre de sources de données par
l'intermédiaire des interfaces du système OLE DB. ADO est également
développé par Microsoft. La plupart des développeurs utilisent l'interface de
programmation OLE DB en écrivant dans l'API ADO, et non en accédant
directement à l'API OLE DB.
Adaptive Server Anywhere inclut un fournisseur OLE DB pour les
programmeurs OLE DB et ADO.
La documentation principale relative à la programmation OLE DB et ADO
provient du Microsoft Developer Network. Ce manuel contient des notes
complémentaires, spécifiquement fournies à l'intention des développeurs
Adaptive Server Anywhere pour ADO et OLE DB.
$ Pour plus d'informations, reportez-vous au chapitre "Les interfaces de
programmation OLE DB et ADO", page 367.
3

Interface de programmation Embedded SQL
Interface de programmation Embedded SQL
4
Embedded SQL est un système dans lequel les commandes SQL sont
imbriquées directement dans un fichier source C ou C++. Un préprocesseur
convertit ces instructions en appels à une bibliothèque d'exécution.
Embedded SQL est une norme ISO/ANSI et IBM.
Embedded SQL peut être porté sur d'autres bases de données et
environnements, et offre des fonctions équivalentes dans tous les
environnements d'exploitation. Il fournit toutes les fonctionnalités
disponibles dans le produit. Même si l'idée d'imbriquer des instructions SQL
(plutôt que des appels de fonction) dans du code C peut paraître déroutante
au début, Embedded SQL reste d'un maniement aisé.
$ Embedded SQL est présenté dans le chapitre "Programmation avec
Embedded SQL", page 177.

Chapitre 1 Présentation de l'interface de programmation
Interface de programmation JDBC
JDBC est une interface call level pour les applications Java. Développée par
Sun Microsystems, JDBC fournit aux programmeurs Java une interface
uniforme pour différentes bases de données relationnelles et constitue une
base commune pour les conceptions d'outils et d'interfaces de niveau
supérieur. JDBC, désormais un composant standard de Java, est incluse dans
le JDK.
SQL Anywhere Studio fournit un pilote Java JDBC pur, nommé Sybase
jConnect. Il comprend également une passerelle JDBC-ODBC. Tous deux
font l'objet d'une description dans la rubrique "Accès aux données via
JDBC", page 139. Pour obtenir des informations sur le choix d'un pilote,
reportez-vous à "Choix d'un pilote JDBC", page 141.
JDBC constitue, côté client, une interface de programmation mais également,
côté serveur, une méthode d'accès aux données Java de la base. C'est pour
cela que JDBC est documentée en tant que composant de Java dans la base
de données.
$ L'interface JDBC n'est pas décrite dans le présent manuel. Pour obtenir
une description de JDBC, reportez-vous au chapitre "Accès aux données via
JDBC", page 139.
5

Interface de programmation Open Client
Interface de programmation Open Client
Contexte
d’utilisation d’Open
Client
Architecture d’Open Client
Client-Library et
DB-Library
Services de réseau
6
Sybase Open Client fournit des applications clientes, des produits tiers et
d’autres produits Sybase avec les interfaces requises pour communiquer avec
Adaptive Server Anywhere et d’autres Open Servers.
Envisagez d’utiliser l’interface Open Client si la compatibilité avec
Adaptive Server Enterprise vous préoccupe ou si vous utilisez d'autres
produits Sybase qui supportent l'interface Open Client, notamment
Replication Server.
$ L'interface Open Client est décrite dans le chapitre "Interface Open
Client", page 385.
$ Pour plus d'informations sur l'interface Open Client, reportez-vous au
chapitre "Adaptive Server Anywhere exploité comme un Open Server",
page 111 du document ASA Guide d’administration.
On peut considérer qu'Open Client est constitué de deux composants : les
interfaces de programmation et les services de réseau.
Open Client offre deux interfaces de programmation principales pour écrire
les applications clients : DB-Library et Client-Library.
Open Client DB-Library supporte les anciennes applications Open Client ;
cette interface de programmation est complètement distincte de Client-
Library. DB-Library est documentée dans Open Client DB-Library/C
Reference Manual, fourni avec le produit Sybase Open Client.
Les programmes Client-Library sont aussi dépendants de CS-Library, qui
fournit des routines utilisées à la fois dans les applications Client-Library et
Server-Library. Les applications Client-Library peuvent également utiliser
des routines Bulk-Library pour faciliter les transferts de données à haut débit.
CS-Library et Bulk-Library sont incluses dans Sybase Open Client,
disponible séparément.
Les services de réseau Open Client comprennent Sybase Net-Library, qui
assure le support des protocoles de réseau spécifiques, tels que TCP/IP et
DECnet. L'interface Net-Library est invisible pour les programmeurs
d'applications. Toutefois, sur certaines plates-formes, une application peut
nécessiter un pilote Net-Library spécifique selon la configuration réseau.
Selon la plate-forme hôte, le pilote Net-Library est spécifié par la
configuration Sybase du système ou au moment de la compilation et de la
liaison de vos programmes.

Chapitre 1 Présentation de l'interface de programmation
$ Des instructions de configuration du pilote sont fournies dans Open
Client/Server - Manuel de configuration.
$ Des instructions relatives à l'élaboration de programmes Client-Library
sont fournies dans Open Client/Server Programmer’s Supplement.
7

Interface de programmation Open Client
8

CHAPITRE 2
Utilisation de SQL dans les applications
Présentation
Sommaire
Bien que de nombreux aspects du développement d'applications de base de
données dépendent de votre outil de développement d'applications, de
l'interface de base de données et du langage de programmation, un certain
nombre de problèmes et de principes sont communs.
Ce chapitre présente quelques techniques et principes communs à quasiment
toutes les interfaces et donne des indications pour trouver des informations
complémentaires. Il ne prétend pas être un guide détaillé de programmation.
Sujet Page
Exécution d'instructions SQL dans les applications 10
Préparation des instructions 12
Présentation des curseurs 15
Utilisation des curseurs 20
Choix d'un type de curseur 25
Curseurs Adaptive Server Anywhere 29
Description des jeux de résultats 45
Contrôle des transactions dans les applications 47
9

Exécution d'instructions SQL dans les applications
Exécution d'instructions SQL dans les
applications
10
Le mode d'intégration d'instructions SQL dans une application dépend de
l'outil de développement des applications et de l'interface de programmation
utilisés.
♦ ODBC Si vous écrivez directement dans l'interface de programmation
ODBC, les instructions SQL apparaissent dans les appels de fonction.
Par exemple, l'appel de fonction C suivant exécute une instruction
DELETE :
SQLExecDirect( stmt,
"DELETE FROM employee
WHERE emp_id = 105",
SQL_NTS );
♦ JDBC Si vous travaillez sous l'interface de programmation JDBC, vous
pouvez exécuter les instructions SQL en invoquant les méthodes de
l'objet statement. Par exemple :
stmt.executeUpdate(
"DELETE FROM employee
WHERE emp_id = 105" );
♦ Embedded SQL Si vous utilisez Embedded SQL, mettez le mot-clé
EXEC SQL en préfixe à vos instructions SQL en langage C. Le code est
ensuite traité par un préprocesseur avant d'être compilé. Par exemple :
EXEC SQL EXECUTE IMMEDIATE
’DELETE FROM employee
WHERE emp_id = 105’;
♦ Sybase Open Client Si vous travaillez sous l'interface Sybase Open
Client, vos instructions SQL apparaissent dans des appels de fonction.
Par exemple, les deux appels suivants exécutent une instruction
DELETE :
ret = ct_command(cmd, CS_LANG_CMD,
"DELETE FROM employee
WHERE emp_id=105"
CS_NULLTERM,
CS_UNUSED);
ret = ct_send(cmd);
♦ Outils de développement d'applications Les outils de développement
d'applications tels que ceux de la famille Sybase Enterprise Application
Studio fournissent leurs propres objets SQL, qui utilisent soit ODBC
(PowerBuilder), soit JDBC (Power J).

Applications dans
le serveur
Chapitre 2 Utilisation de SQL dans les applications
$ Pour plus de détails sur l'intégration de SQL dans votre application,
reportez-vous à la documentation de votre outil de développement. Si vous
exploitez ODBC ou JDBC, consultez le kit de développement logiciel pour
ces interfaces.
$ Pour plus d'informations sur la programmation avec Embedded SQL,
reportez-vous au chapitre "Programmation avec Embedded SQL", page 177.
A de nombreux égards, les procédures stockées et les triggers agissent
comme des applications ou des parties d'application exécutées à l'intérieur du
serveur. Vous pouvez utiliser pour des procédures stockées la plupart des
techniques décrites ici. Les procédures stockées utilisent des instructions très
similaires aux instructions Embedded SQL.
$ Pour plus d'informations sur les procédures stockées et les triggers,
reportez-vous au chapitre "Utilisation des procédures, des triggers et des
batchs", page 541 du document ASA Guide de l’utilisateur SQL.
Les classes Java présentes dans la base de données peuvent utiliser l'interface
JDBC exactement comme les applications Java en dehors du serveur. Ce
chapitre traite de quelques aspects de JDBC. Pour plus d'informations sur
JDBC, reportez-vous au chapitre "Accès aux données via JDBC", page 139.
11

Préparation des instructions
Préparation des instructions
Instructions
préparées et
amélioration des
performances
Ne préparez pas
les instructions qui
ne seront
exécutées qu'une
fois
12
Chaque fois qu'une instruction est envoyée à une base de données, le serveur
doit d'abord la préparer. La préparation de l'instruction englobe plusieurs
tâches :
♦ Analyse de l'instruction et conversion en un format interne.
♦ Vérification de toutes les références aux objets de base de données, en
contrôlant, par exemple, l'existence des colonnes nommées dans la liste
d'une requête.
♦ Si l'instruction implique des jointures ou des sous-requêtes, génération
d'un plan d'accès par l'optimiseur de requêtes.
♦ Exécution de l'instruction une fois toutes ces opérations accomplies.
Si vous utilisez une même instruction de façon répétitive, par exemple pour
insérer des lignes dans une table, le fait de répéter la préparation de
l'instruction entraîne une surcharge importante et inutile. Pour éliminer cette
surcharge, certaines interfaces de programmation de bases de données
autorisent le recours à des instructions préparées. Une instruction préparée
est une instruction contenant une série de marques de réservation. Au
moment de l'exécuter, il vous suffit d'attribuer des valeurs aux marques de
réservation au lieu de recommencer entièrement la préparation de
l'instruction.
Le recours aux instructions préparées est particulièrement utile pour effectuer
plusieurs actions identiques, par exemple pour insérer plusieurs lignes.
L'utilisation d'instructions préparées implique généralement les étapes
suivantes :
1 Préparation de l'instruction Cette étape consiste généralement à fournir
l'instruction avec des marques de réservation et non des valeurs.
2 Exécution à plusieurs reprises de l'instruction préparée Dans cette
étape, vous fournissez les valeurs à utiliser chaque fois que l'instruction
est exécutée. Il est inutile de préparer chaque fois l'instruction.
3 Suppression de l’instruction Dans cette étape, vous libérez les
ressources associées à l'instruction préparée. Certaines interfaces de
programmation gèrent automatiquement cette étape.
En général, il est superflu de préparer des instructions si elles ne doivent être
exécutées qu'une seule fois. La préparation et l'exécution d'une instruction
ponctuelle pénalisent légèrement les performances et compliquent
inutilement votre application.

Instructions préparées
Chapitre 2 Utilisation de SQL dans les applications
Dans certaines interfaces, toutefois, vous n'avez pas besoin de préparer une
instruction pour l'associer à un curseur.
$ Pour plus d'informations sur les curseurs, reportez-vous à la section
"Présentation des curseurs", page 15.
Les appels requis pour préparer et exécuter les instructions ne font pas partie
du SQL et ils diffèrent en fonction des interfaces. Chacune des interfaces de
programmation d'Adaptive Server Anywhere offre une méthode permettant
d'exploiter des instructions préparées.
Cette section donne un bref aperçu de l'utilisation des instructions préparées.
La procédure générale est identique, mais les détails varient d'une interface à
l'autre. Pour illustrer cela, nous allons comparer le mode d'utilisation
d'instructions préparées dans différentes interfaces.
v Pour utiliser une instruction préparée (générique) :
1 Préparez l'instruction.
2 Définissez les paramètres de liaison, qui contiennent les valeurs dans
l’instruction.
3 Affectez des valeurs aux paramètres de liaison.
4 Exécutez l'instruction.
5 Répétez les étapes 3 et 4 autant de fois que nécessaire.
6 L'opération terminée, supprimez l'instruction. Cette étape est inutile dans
JDBC, dans la mesure où les mécanismes de défragmentation de la
mémoire de Java le font à votre place.
v Pour utiliser une instruction préparée (Embedded SQL) :
1 Préparez l'instruction avec la commande EXEC SQL PREPARE.
2 Affectez des valeurs aux paramètres dans l'instruction.
3 Exécutez l'instruction avec la commande EXE SQL EXECUTE.
4 Libérez les ressources associées à l'instruction, en utilisant la commande
EXEC SQL DROP.
v Pour utiliser une instruction préparée (ODBC) :
1 Préparez l'instruction via SQLPrepare.
13

Préparation des instructions
14
2 Effectuez la liaison des paramètres de l'instruction avec
SQLBindParameter.
3 Exécutez l'instruction avec SQLExecute.
4 Supprimez l'instruction avec SQLFreeStmt.
$ Pour plus d'informations, reportez-vous à la section "Exécution des
instructions préparées", page 295 et à la documentation SDK ODBC.
v Pour utiliser une instruction préparée (JDBC) :
1 Préparez l'instruction avec la méthode prepareStatement de l'objet de
connexion. Vous obtenez un objet instruction préparée.
2 Définissez les paramètres de l'instruction avec les méthodes setType
adaptées de l'objet instruction préparée. Type est ici le type de données
affecté.
3 Définissez les paramètres de l'instruction avec la méthode appropriée de
l'objet instruction préparée. Pour les insertions, mises à jour et
suppressions, il s'agit de la méthode executeUpdate.
$ Pour plus d'informations sur les instructions préparées dans JDBC,
reportez-vous à la section "Utilisation d'instructions préparées pour un
accès optimisé", page 167.
v Pour utiliser une instruction préparée (Open Client) :
1 Préparez l'instruction via la fonction ct_dynamic, avec un paramètre de
type CS_PREPARE.
2 Définissez les paramètres de l'instruction avec ct_param.
3 Exécutez l'instruction via ct_dynamic avec un paramètre de type
CS_EXECUTE.
4 Libérez les ressources associées à l'instruction via ct_dynamic avec un
paramètre de type CS_DEALLOC.
$ Pour plus d'informations sur l'utilisation d'instructions préparées
dans Open Client, reportez-vous à la section "SQL dans les applications
Open Client", page 389.

Présentation des curseurs
Qu’est-ce qu’un curseur ?
Positions du
curseur
Chapitre 2 Utilisation de SQL dans les applications
Lorsque vous exécutez une requête dans une application, le jeu de résultats
est constitué d'un certain nombre de lignes. En général, vous ne connaissez
pas le nombre de lignes que l'application recevra avant d'exécuter la requête.
Les curseurs constituent un moyen de gérer les jeux de résultats d'une
requête dans les applications.
Le mode d'utilisation effective des curseurs, de même que les types de
curseurs disponibles, dépendent de l'interface de programmation. JDBC 1.0
n'offre qu'une gestion rudimentaire des jeux de résultats, tandis qu'ODBC et
Embedded SQL proposent plusieurs types de curseur. Les curseurs Open
Client se limitent au simple déplacement vers l'avant dans un jeu de résultats.
Les curseurs vous permettent d'exécuter les tâches suivantes au sein de
n'importe quelle interface de programmation :
♦ Naviguer dans les résultats d'une requête.
♦ Effectuer des insertions, des mises à jour et des suppressions de données
sous-jacentes en tout point d'un jeu de résultats.
D'autre part, certaines interfaces de programmation proposent des fonctions
spécifiques pour optimiser le renvoi des jeux de résultats à l'application, de
sorte que vous pouvez améliorer sensiblement ses performances.
$ Pour plus d'informations sur les types de curseurs disponibles dans les
différentes interfaces de programmation, reportez-vous à la section
"Disponibilité des curseurs", page 25.
Un curseur est un nom associé à un jeu de résultats issu d'une instruction
SELECT ou d'un appel de procédure stockée.
Le curseur est un descripteur du jeu de résultats. Il détient à tout moment une
position bien définie au sein du jeu de résultats. Un curseur permet
d'examiner, voire de manipuler, les données ligne par ligne. Dans Adaptive
Server Anywhere, les curseurs permettent les déplacements vers l'avant et
vers l'arrière dans les résultats d'une requête.
Vous pouvez positionner les curseurs aux endroits suivants :
♦ avant la première ligne du jeu de résultats ;
♦ sur une ligne du jeu de résultats ;
♦ après la dernière ligne du jeu de résultats.
15

Présentation des curseurs
16
La position du curseur et le jeu de résultats sont tenus à jour sur le serveur de
base de données. Des lignes sont extraites par le client à des fins d'affichage
et de traitement, une par une ou plusieurs à la fois. Il est en effet inutile de
transmettre entièrement le jeu de résultats au client.
Avantages liés à l'utilisation de curseurs
Si l'utilisation de curseurs dans les applications de base de données est
facultative, elle présente toutefois un certain nombre d'avantages. Ces
avantages sont liés au fait que si vous n'utilisez pas de curseur, l'intégralité
du jeu de résultats doit être transférée au client à des fins de traitement et
d'affichage.

Etapes d’utilisation d’un curseur
Chapitre 2 Utilisation de SQL dans les applications
♦ Mémoire côté client Pour les résultats volumineux, le stockage d'un jeu
de résultats complet sur le client peut se traduire par une augmentation
des besoins en mémoire.
♦ Temps de réponse Les curseurs peuvent fournir les premières lignes
avant la création complète du jeu de résultats. Si vous n'utilisez pas de
curseur, le jeu de résultats doit être entièrement transféré pour que
l'application puisse en afficher les lignes.
♦ Contrôle de la concurrence d'accès Si vous mettez des données à jour
sans utiliser de curseur dans votre application, vous devez envoyer des
instructions SQL distinctes au serveur de base de données pour
appliquer les modifications. Ceci peut donner lieu à des problèmes de
concurrence d'accès si le jeu de résultats a changé depuis la requête du
client. Ces problèmes peuvent à leur tour entraîner des pertes de mise à
jour.
Les curseurs agissent comme des pointeurs sur les données sous-jacentes
et soumettent donc les modifications apportées à des contraintes de
concurrence d'accès.
Les étapes d'utilisation d'un curseur ne sont pas les mêmes selon que vous
utilisez Embedded SQL ou d'autres interfaces.
v Pour utiliser un curseur (Embedded SQL) :
1 Préparez une instruction.
En général, les curseurs utilisent un descripteur d'instruction plutôt
qu'une chaîne. Vous devez préparer une instruction pour disposer d'un
pointeur.
$ Pour plus d'informations sur la préparation d'une instruction,
reportez-vous à la section "Préparation des instructions", page 12.
2 Déclarez le curseur.
Chaque curseur référence une instruction SELECT ou CALL donnée.
Lorsque vous déclarez un curseur, vous définissez son nom et l'interface
à laquelle il fait référence.
$ Pour plus d'informations, reportez-vous à la section "Instruction
DECLARE CURSOR [ESQL] [SP]", page 401 du document ASA
Manuel de référence SQL.
3 Ouvrez le curseur.
17

Présentation des curseurs
18
$ Pour plus d'informations, reportez-vous à la section "Instruction
OPEN [ESQL] [SP]", page 508 du document ASA Manuel de référence
SQL.
Dans le cas d'une instruction CALL, l'ouverture du curseur entraîne
l'exécution de la requête jusqu'au point où la première ligne est en passe
d'être obtenue.
4 Lisez les résultats.
Une simple opération d'extraction déplace le curseur sur la ligne
suivante du jeu de résultats ; toutefois, les fonctions d'Adaptive Server
Anywhere permettent des mouvements plus complexes. Les fonctions de
lecture disponibles dépendent de la manière dont vous déclarez le
curseur.
$ Pour plus d'informations, reportez-vous aux sections "Instruction
FETCH [ESQL] [SP]", page 446 du document ASA Manuel de référence
SQL et "Lecture de données", page 211.
5 Fermez le curseur.
Lorsque vous ne l'utilisez plus, fermez le curseur. Cette opération lève
les verrous posés sur les données sous-jacentes.
$ Pour plus d'informations, reportez-vous à la section "Instruction
CLOSE [ESQL] [SP]", page 276 du document ASA Manuel de référence
SQL.
6 Supprimez l’instruction.
Pour libérer la mémoire associée au curseur et à l'instruction
correspondante, vous devez libérer l'instruction.
$ Pour plus d'informations, reportez-vous à la section "Instruction
DROP STATEMENT [ESQL]", page 427 du document ASA Manuel de
référence SQL.
v Pour utiliser un curseur (ODBC, JDBC ou Open Client) :
1 Préparez et exécutez une instruction.
Exécutez l'instruction comme vous le faites habituellement sous cette
interface. Vous pouvez préparer l'instruction avant de l'exécuter ou
l'exécuter directement.
2 Vérifiez si l'instruction renvoie un jeu de résultats.
Un curseur est ouvert par défaut lors de l'exécution d'une instruction qui
crée un jeu de résultats. Lors de son ouverture, le curseur est positionné
avant la première ligne du jeu de résultats.

Prélecture de
lignes
Chapitre 2 Utilisation de SQL dans les applications
3 Lisez les résultats.
Une simple opération de lecture déplace le curseur sur la ligne suivante
du jeu de résultats ; toutefois, les fonctions de lecture d'Adaptive Server
Anywhere permettent des mouvements plus complexes.
4 Fermez le curseur.
Lorsque vous ne l'utilisez plus, fermez le curseur afin de libérer les
ressources associées.
5 Libérez l'instruction.
Si vous avez utilisé une instruction préparée, libérez-la pour récupérer
de la mémoire.
Parfois, la bibliothèque d'interface procède à une optimisation des
performances (prélecture des résultats, par exemple) de manière transparente.
Il est donc possible que les étapes dans l'application cliente ne correspondent
pas exactement aux opérations logicielles.
19

Utilisation des curseurs
Utilisation des curseurs
Positionnement du curseur
20
Cette section traite de l'exécution de différentes opérations utilisant des
curseurs.
Lors de son ouverture, un curseur est placé avant la première ligne. Vous
pouvez lui donner une position absolue par rapport au début ou à la fin des
résultats de la requête, ou une position relative à sa position courante. La
façon dont vous pouvez modifier la position du curseur et les opérations
possibles dépendent de l'interface de programmation.
Le nombre de positions de ligne que vous pouvez extraire dans un curseur est
fonction de la taille d'un entier. Vous pouvez extraire des lignes numérotées
jusqu'à 2 147 483 646, ce qui correspond à la valeur que peut contenir un
entier, moins un. Lorsque vous utilisez des nombres négatifs (comptage des
lignes à partir de la fin), vous pouvez extraire un nombre de lignes égal à la
plus grande valeur négative que peut contenir un entier, plus un.
Vous pouvez utiliser des opérations spécifiques de mise à jour (UPDATE) et
de suppression (DELETE) positionnées pour mettre à jour ou supprimer une
ligne à la position courante du curseur. Si le curseur est positionné avant la
première ligne ou après la dernière ligne, une erreur Aucune ligne de curseur
n'est actuellement sélectionnée est renvoyé.

Chapitre 2 Utilisation de SQL dans les applications
Problèmes liés au positionnement du curseur
Les insertions et certaines mises à jour apportées aux curseurs à sensibilité
indéfinie peuvent engendrer des problèmes de positionnement. Adaptive
Server Anywhere ne place les lignes insérées à une position prévisible
d'un curseur que si l'instruction SELECT comporte une clause
ORDER BY. Dans certains cas, la ligne insérée n'apparaît pas avant que le
curseur soit fermé puis rouvert.
Dans Adaptive Server Anywhere, ce problème survient lorsqu'une table
de travail a dû être créée pour ouvrir le curseur (pour une description
détaillée, reportez-vous à la section "Utilisation de tables de travail dans le
traitement des requêtes", page 170 du document ASA Guide de
l’utilisateur SQL).
L'instruction UPDATE peut provoquer le déplacement d'une ligne dans le
curseur. Cela se produit si le curseur inclut une clause ORDER BY qui
utilise un index existant (aucune table de travail n'est créée). Les curseurs
STATIC SCROLL réduisent ces problèmes, mais consomment plus de
mémoire et de traitement.
Configuration des curseurs à l'ouverture
A l'ouverture d'un curseur, vous pouvez configurer les éléments suivants :
♦ Niveau d’isolement Vous pouvez définir explicitement le niveau
d'isolement des opérations sur un curseur, de sorte qu'il soit différent du
niveau d'isolement défini pour la transaction. Pour ce faire, définissez
l'option ISOLATION_LEVEL.
$ Pour plus d'informations, reportez-vous à la section "Option
ISOLATION_LEVEL", page 623 du document ASA Guide
d’administration.
♦ Maintien Par défaut, les curseurs dans Embedded SQL sont fermés à la
fin d'une transaction. Ouvrir un curseur avec la clause WITH HOLD
permet de le maintenir ouvert jusqu'à la fin de la connexion ou jusqu'à sa
fermeture explicite. Par défaut, ODBC, JDBC et Open Client laissent les
curseurs ouverts à la fin des transactions.
Extraction de lignes via un curseur
Le plus simple, pour traiter le jeu de résultats d'une requête via un curseur,
est de parcourir toutes les lignes des résultats jusqu'à la fin.
21

Utilisation des curseurs
Extraction multiligne
22
v Pour parcourir entièrement les lignes d'un jeu de résultats :
1 Déclarez et ouvrez le curseur (Embedded SQL), ou exécutez une
instruction qui renvoie un jeu de résultats (ODBC, JDBC ou Open
Client).
2 Lisez les lignes jusqu'à obtenir un message La ligne est introuvable.
3 Fermez le curseur.
Le mode d'exécution de l'étape 2 dépend de l'interface utilisée. Par exemple :
♦ ODBC SQLFetch, SQLExtendedFetch ou SQLFetchScroll déplace le
curseur sur la ligne suivante et renvoie les données.
$ Pour plus d'informations sur les curseurs dans ODBC, reportezvous
à la section "Jeux de résultats", page 297.
♦ Embedded SQL L'instruction FETCH exécute la même opération.
$ Pour plus d'informations sur l'utilisation des curseurs dans
Embedded SQL, reportez-vous à la section "Utilisation de curseurs dans
Embedded SQL", page 212.
♦ JDBC La méthode next de l'objet ResultSet déplace le curseur et
renvoie les données.
$ Pour plus d'informations sur l'utilisation de l'objet ResultSet dans
JDBC, reportez-vous à la section "Requêtes avec JDBC", page 166.
♦ Open Client La fonction ct_fetch déplace le curseur sur la ligne
suivante et renvoie les données.
$ Pour plus d'informations sur les curseurs dans les applications
Open Client, reportez-vous à la section "Curseurs", page 390.
Cette section traite de l'extraction simultanée de plusieurs lignes, technique
susceptible d'améliorer les performances.
Ne confondez pas extraction multiligne et préextraction de lignes (décrite
plus loin). L'extraction multiligne est réalisée par l'application, tandis que la
préextraction est transparente pour l'application ; elle améliore également les
performances.

Extraction
multiligne
Utilisation de
l’extraction
multiligne
Chapitre 2 Utilisation de SQL dans les applications
Certaines interfaces permettent d'extraire simultanément plusieurs lignes
dans les champs suivants d'un tableau. D'une façon générale, moins vous
exécutez d'extractions distinctes, moindre est le nombre de requêtes
auxquelles doit répondre le serveur et meilleures sont les performances. Une
instruction FETCH modifiée qui extrait plusieurs lignes est également
appelée extraction étendue. Les curseurs utilisant les extractions multiligne
sont parfois appelés curseurs bloc ou curseurs "fat".
♦ Dans ODBC, vous pouvez fixer le nombre de lignes renvoyées par
chaque appel à SQLFetchScroll ou SQLExtendedFetch en définissant
l'attribut SQL_ROWSET_SIZE.
♦ Dans Embedded SQL, l'instruction FETCH permet de contrôler le
nombre de lignes extraites simultanément, via la clause ARRAY.
♦ Open Client et JDBC ne supportent pas les extractions multiligne. Ils
utilisent la préextraction.
Extraction par des curseurs avec défilement
ODBC et Embedded SQL proposent des méthodes permettant d'exploiter les
curseurs avec défilement et défilement dynamique. Ces méthodes permettent
d'avancer de plusieurs lignes en une fois ou de remonter dans le jeu de
résultats.
Les interfaces JDBC et Open Client ne supportent pas les curseurs avec
défilement.
La prélecture n'est pas applicable aux opérations de défilement. Par exemple,
l'extraction d'une ligne située avant la ligne courante ne permet pas la
préextraction de plusieurs lignes en amont.
Modification de lignes via un curseur
Les curseurs ne servent pas seulement à lire les résultats d'une requête. Vous
pouvez également modifier les données d'une base pendant le traitement d'un
curseur. Ces opérations sont généralement appelées opérations de mise à jour
(UPDATE) et de suppression (DELETE) positionnées, ou opérations PUT
s'il s'agit d'une insertion (INSERT).
Les mises à jour et les suppressions positionnées ne sont pas admises dans
tous les jeux de résultats de requêtes. Si vous exécutez une requête sur une
vue non modifiable, aucune modification ne peut être apportée à la table
sous-jacente. De plus, si la requête implique une jointure, vous devez
spécifier la table dans laquelle effectuer la suppression, ou les colonnes à
mettre à jour lorsque vous exécutez l'opération.
23

Utilisation des curseurs
Table dans
laquelle sont
supprimées les
lignes
24
Les insertions via un curseur ne peuvent être exécutées que si les colonnes
non insérées admettent la valeur NULL ou sont dotées d'une valeur par
défaut.
ODBC, Embedded SQL et Open Client autorisent la modification des
données via un curseur, mais pas JDBC 1.1. Avec Open Client, vous pouvez
supprimer et mettre à jour des lignes, mais vous ne pouvez en insérer que
dans une requête portant sur une seule table.
Si vous tentez une suppression positionnée via un curseur, la table dans
laquelle les lignes sont supprimées est déterminée comme suit :
1 Si aucune clause FROM n'est incluse, le curseur ne doit pointer que sur
une seule table.
2 Si le curseur concerne une requête jointe (ce qui inclut les vues
contenant une jointure), la clause FROM doit être employée. Seule la
ligne courante de la table spécifiée est supprimée. Les autres tables
participant à la jointure demeurent inchangées.
3 Si une clause FROM est incluse mais qu'aucun propriétaire de table n'est
spécifié, la valeur spécif_table est d'abord comparée aux alias existants :
$ Pour plus d'information, reportez-vous à la section "Clause
FROM", page 455 du document ASA Manuel de référence SQL.
4 S'il existe un alias, la valeur spécif_table est identifiée avec cet alias.
5 Si aucun alias n'a été défini, la valeur spécif_table doit identifier sans
ambiguïté le nom d'une table appartenant au curseur.
6 Si une clause FROM est incluse et qu'un nom de propriétaire est
spécifié, la valeur spécif_table doit identifier sans ambiguïté le nom
d'une table appartenant au curseur.
7 Vous pouvez utiliser l'instruction DELETE positionnée sur un curseur
ouvert sur une vue, à condition que celle-ci soit modifiable.
Annulation des opérations sur un curseur
Vous pouvez annuler une requête via une fonction de l'interface. Dans
Interactive SQL, vous pouvez annuler une requête en cliquant sur le bouton
Interrompt l'instruction SQL de la barre d'outils (ou en choisissant Arrêter
dans le menu SQL).
Si vous annulez une requête qui exécute une opération avec le curseur, la
position du curseur est indéterminée. Une fois la requête annulée, vous devez
localiser le curseur à l'aide de sa position absolue ou le fermer, juste après
l'annulation.

Choix d’un type de curseur
Disponibilité des curseurs
Propriétés de curseur
Chapitre 2 Utilisation de SQL dans les applications
Cette section décrit les mappages entre les curseurs Adaptive Server
Anywhere et les options proposées par les interfaces de programmation
supportées par Adaptive Server Anywhere.
$ Pour plus d'informations sur les curseurs Adaptive Server Anywhere,
reportez-vous à la section "Curseurs Adaptive Server Anywhere", page 29.
Toutes les interfaces ne supportent pas tous les types de curseur.
♦ ODBC et OLE DB (ADO) supportent tous les types de curseur.
$ Pour plus d'informations, reportez-vous à la section "Jeux de
résultats", page 297.
♦ Embedded SQL supporte tous les types de curseur.
♦ Pour JDBC:
♦ jConnect 4.x ne fournit que des curseurs à sensibilité indéfinie.
♦ jConnect 5.x supporte tous les types de curseurs, avec toutefois une
baisse de performances pour les curseurs avec défilement.
♦ La passerelle JDBC-ODBC supporte tous les types de curseurs.
♦ Sybase Open Client supporte uniquement les curseurs à sensibilité
indéfinie. Par ailleurs, l'utilisation de curseurs non uniques et
modifiables a des effets très néfastes sur les performances.
C'est à l'interface de programmation que vous demandez un type de curseur,
que ce soit de façon explicite ou implicite. Les types de curseur proposés
varient selon les bibliothèques d'interface. Par exemple, JDBC et ODBC
offrent des types de curseur différents.
Chaque type de curseur présente plusieurs caractéristiques :
♦ Unicité Lorsqu'un curseur est déclaré unique, la requête est contrainte de
renvoyer toutes les colonnes nécessaires pour identifier chaque ligne de
façon unique. Cela signifie souvent le renvoi de toutes les colonnes de la
clé primaire. Toute colonne requise mais non spécifiée est ajoutée dans
le jeu de résultats. Le type de curseur par défaut est non-unique.
25

Choix d’un type de curseur
26
♦ Possibilité de mise à jour Un curseur déclaré comme étant en lecture
seule ne peut pas être utilisé dans une opération de mise à jour ou de
suppression positionnée. Le type de curseur par défaut est modifiable.
♦ Défilement Vous pouvez déclarer des curseurs qui auront des
comportements différents lors de leur déplacement dans le jeu de
résultats. Certains curseurs ne peuvent extraire que la ligne courante ou
la suivante. D'autres peuvent se déplacer vers l'avant ou vers l'arrière
dans le jeu de résultats.
♦ Sensibilité Les modifications apportées à la base de données peuvent
être visibles ou non via un curseur.
Ces caractéristiques peuvent avoir des effets secondaires considérables sur
les performances et l'utilisation de mémoire du serveur de base de données.
Adaptive Server Anywhere propose des curseurs offrant différentes
combinaisons de ces caractéristiques. Lorsque vous demandez un curseur
d'un type donné, Adaptive Server Anywhere tente de répondre au mieux aux
critères spécifiés. Les sections suivantes expliquent comment les curseurs
Adaptive Server Anywhere correspondent aux types de curseur spécifiés
dans les interfaces de programmation.
Dans certains cas, il est impossible de réunir toutes les caractéristiques
souhaitées. Par exemple, dans Adaptive Server Anywhere, les curseurs
insensibles doivent être en lecture seule, pour les raisons décrites ci-après. Si
votre application demande un curseur insensible modifiable, un autre type de
curseur (tenant compte des valeurs) est fourni à la place.
Demande de curseurs Adaptive Server Anywhere
ODBC et OLE DB
Lorsque vous demandez un type de curseur depuis votre application cliente,
Adaptive Server Anywhere en propose un. Les curseurs Adaptive Server
Anywhere sont définis en fonction de la sensibilité du jeu de résultats aux
modifications apportées aux données sous-jacentes, et non du type spécifié
dans l'interface de programmation. Selon le type demandé, Adaptive Server
Anywhere propose un curseur dont le comportement correspond à ce type.
La sensibilité des curseurs Adaptive Server Anywhere est établie en fonction
de la demande de type de curseur de la part du client.
Le tableau suivant illustre la sensibilité du curseur définie en fonction des
différents types de curseur avec défilement ODBC.

Exceptions
Embedded SQL
Exceptions
Type de curseur avec
défilement ODBC
Chapitre 2 Utilisation de SQL dans les applications
STATIC Insensible
Curseur Adaptive Server Anywhere
KEYSET Tenant compte des valeurs
DYNAMIC Sensible
MIXED Tenant compte des valeurs
$ Pour plus d’informations sur les curseurs Adaptive Server Anywhere et
leur comportement, reportez-vous à la section "Curseurs Adaptive Server
Anywhere", page 29. Pour plus d'informations sur la demande d'un type de
curseur dans ODBC, reportez-vous à la section "Choix des caractéristiques
d'un curseur", page 297.
Si un curseur STATIC est demandé comme modifiable, un curseur tenant
compte des valeurs est fourni à la place et un avertissement est émis.
Si un curseur DYNAMIC ou MIXED est demandé et si la requête ne peut
pas être exécutée sans utiliser de tables de travail, un avertissement est émis
et un curseur à sensibilité indéfinie est fourni à la place.
Pour demander un curseur depuis une application Embedded SQL, vous
indiquez le type de curseur dans l'instruction DECLARE. Le tableau suivant
illustre la sensibilité des curseurs définie en fonction des différentes
demandes possibles.
Type de curseur Curseur Adaptive Server Anywhere
NO SCROLL A sensibilité indéfinie
DYNAMIC SCROLL A sensibilité indéfinie
SCROLL Tenant compte des valeurs
INSENSITIVE Insensible
SENSITIVE Sensible
Si un curseur DYNAMIC SCROLL ou NO SCROLL est demandé comme
modifiable, c'est un curseur sensible ou tenant compte des valeurs qui est
proposé. Il est impossible de prévoir lequel des deux curseurs sera fourni.
Cette incertitude correspond à la définition d'une sensibilité indéfinie.
Si un curseur INSENSITIVE est demandé comme modifiable, c'est un
curseur tenant compte des valeurs qui est fourni.
27

Choix d’un type de curseur
JDBC
Open Client
Signets et curseurs
Curseurs bloc
28
Si un curseur DYNAMIC SCROLL est demandé, si l'option de base de
données PREFETCH est définie à OFF et si le plan d'exécution de la requête
n'implique aucune table de travail, il est possible qu'un curseur sensible soit
fourni. Là encore, cette incertitude correspond à la définition d'une sensibilité
indéfinie.
Un seul type de curseur est disponible pour les applications JDBC. Il s'agit
d'un curseur à sensibilité indéfinie. Dans JDBC, vous exécutez une
instruction ExecuteQuery pour ouvrir un curseur.
Un seul type de curseur est disponible pour les applications Open Client. Il
s'agit d'un curseur à sensibilité indéfinie.
ODBC fournit des signets, qui sont des valeurs utilisées pour identifier des
lignes dans un curseur. Adaptive Server Anywhere accepte des signets pour
tous les types de curseur à l'exception des curseurs dynamiques.
ODBC fournit un type de curseur appelé curseur bloc. Avec un curseur bloc,
vous pouvez utiliser SQLFetchScroll ou SQLExtendedFetch pour lire un
bloc de lignes au lieu d'une seule ligne. Les curseurs bloc se comportent
comme des extractions SQL ARRAY dans Embedded SQL.

Chapitre 2 Utilisation de SQL dans les applications
Curseurs Adaptive Server Anywhere
Modification de
l’appartenance, de
l’ordre et des
valeurs
Une fois ouvert, un curseur est associé à un jeu de résultats. Il reste ouvert
ainsi pendant un certain temps. Pendant cette durée, il est possible que le jeu
de résultats associé au curseur soit modifié, soit via le curseur lui-même, soit
par d'autres transactions en fonction du niveau d'isolement requis. Certains
curseurs permettent d'afficher les modifications apportées aux données sousjacentes,
tandis que d'autres n'en font pas état. Cette différence de
comportement par rapport aux modifications apportées aux données sousjacentes
est appelée sensibilité du curseur.
Adaptive Server Anywhere propose des curseurs offrant différentes
caractéristiques de sensibilité. Cette section définit le concept de sensibilité
et décrit les caractéristiques des curseurs dans ce domaine.
Vous devez au préalable avoir lu la section "Qu'est-ce qu'un curseur ?",
page 15
Les modifications apportées aux données sous-jacentes peuvent avoir
plusieurs répercussions sur le jeu de résultats d'un curseur :
♦ Appartenance Lignes du jeu de résultats, identifiées par leur valeur de
clé primaire.
♦ Ordre Ordre des lignes dans le jeu de résultats.
♦ Valeur Valeur des lignes du jeu de résultats.
Prenons l'exemple d'une table simple contenant des informations sur les
employés (emp_id étant la colonne de clé primaire) :
emp_id emp_lname
1 Whitney
2 Cobb
3 Chin
Un curseur sur la requête suivante renvoie tous les résultats de la table par
ordre de clé primaire :
SELECT emp_id, emp_lname
FROM employee
ORDER BY emp_id
L'appartenance du jeu de résultats pourrait être modifiée en ajoutant ou en
supprimant une ligne. Les valeurs pourraient être modifiées en changeant un
des noms figurant dans la table. Quant à l'ordre, il pourrait lui aussi être
modifié en changeant la valeur de clé primaire d'un des employés.
29

Curseurs Adaptive Server Anywhere
Modifications
visibles et
invisibles
30
Selon le niveau d’isolement requis, il est possible de modifier l’appartenance,
l'ordre et les valeurs du jeu de résultats d'un curseur après l'ouverture de
celui-ci. Le type de curseur utilisé détermine si le jeu de résultats visible par
l'application peut changer ou non pour refléter ces modifications.
Les modifications apportées aux données sous-jacentes peuvent être visibles
ou invisibles par le biais du curseur. Une modification visible est un
changement reporté dans le jeu de résultats du curseur. Les modifications des
données sous-jacentes non répercutées dans le jeu de résultats du curseur
sont invisibles.
Généralités sur la sensibilité des curseurs
Les curseurs Adaptive Server Anywhere sont classés selon leur sensibilité
aux modifications apportées aux données sous-jacentes. La sensibilité des
curseurs est en particulier définie en termes de visibilité des modifications.
♦ Curseurs insensibles Le jeu de résultats est fixé lors de l'ouverture du
curseur. Les modifications apportées aux données sous-jacentes ne sont
pas visibles.
$ Pour plus d'informations, reportez-vous à la section "Curseurs
insensibles", page 35.
♦ Curseurs sensibles Le jeu de résultats peut être modifié après
l'ouverture du curseur. Les modifications apportées aux données sousjacentes
sont visibles.
$ Pour plus d'informations, reportez-vous à la section "Curseurs
sensibles", page 36.
♦ Curseurs à sensibilité indéfinie Les modifications peuvent être
répercutées sur l'appartenance, l'ordre ou les valeurs du jeu de résultats
du curseur, ou ne pas être prises en compte du tout.
$ Pour plus d'informations, reportez-vous à la section "Curseurs à
sensibilité indéfinie", page 38.
♦ Curseurs tenant compte des valeurs Les modifications apportées
à l'ordre ou aux valeurs des données sous-jacentes sont répercutées.
L'appartenance du jeu de résultats est fixé lors de l'ouverture du curseur.
$ Pour plus d'informations, reportez-vous à la section "Curseurs
tenant compte des valeurs", page 39.
Les différentes exigences en matière de curseurs entraînent des contraintes
sur l'exécution, donc les performances. Pour plus d'informations, reportezvous
à la section "Sensibilité du curseur et performances", page 42.

Chapitre 2 Utilisation de SQL dans les applications
Exemple de sensibilité du curseur : suppression d'une ligne
Cet exemple utilise une requête simple pour illustrer comment différents
curseurs réagissent à la suppression d'une ligne du jeu de résultats.
La succession des événements est la suivante :
1 Une application ouvre un curseur sur la requête suivante, qui concerne la
base de données exemple :
SELECT emp_id, emp_lname
FROM employee
ORDER BY emp_id
emp_id emp_lname
102 Whitney
105 Cobb
160 Breault
… …
2 L'application extrait la première ligne (102) au moyen du curseur.
3 L'application extrait la ligne suivante (105) au moyen du curseur.
4 Une autre transaction supprime l'employé 102 (Whitney) et valide la
modification.
Dans ce cas, les résultats des actions du curseur varient selon sa sensibilité :
♦ Curseur insensible L'instruction DELETE n'est répercutée ni sur
l'appartenance, si sur les valeurs du jeu de résultats associé au curseur.
Action Résultat
Extraction de la ligne
précédente
Extraction de la
première ligne
(extraction absolue)
Extraction de la
deuxième ligne
(extraction absolue)
Renvoie la copie originale de la ligne (102).
Renvoie la copie originale de la ligne (102).
Renvoie la ligne inchangée (105).
♦ Curseur sensible L'appartenance du jeu de résultats a changé, de sorte
que la ligne 105 est désormais la première du jeu de résultats.
31

Curseurs Adaptive Server Anywhere
32
Action Résultat
Extraction de la ligne
précédente
Extraction de la
première ligne
(extraction absolue)
Extraction de la
deuxième ligne
(extraction absolue)
Renvoie une erreur La ligne est introuvable. Il
n'y a pas de ligne précédente.
Renvoie la ligne 105.
Renvoie la ligne 160.
♦ Curseur tenant compte des valeurs L'appartenance du jeu de résultats
étant fixe, la ligne 105 est toujours la deuxième du jeu de résultats.
L'instruction DELETE est répercutée sur les valeurs du curseur et crée
un "vide" dans le jeu de résultats.
Action Résultat
Extraction de la ligne
précédente
Extraction de la
première ligne
(extraction absolue)
Extraction de la
deuxième ligne
(extraction absolue)
Renvoie le message Aucune ligne de curseur
n'est actuellement sélectionnée. Il existe
désormais un vide dans le curseur à la place de la
première ligne.
Renvoie le message Aucune ligne de curseur
n'est actuellement sélectionnée. Il existe
désormais un vide dans le curseur à la place de la
première ligne.
Renvoie la ligne 105.
♦ Curseur à sensibilité indéfinie L’effet des modifications sur
l'appartenance et les valeurs du jeu de résultats est indéterminé. La
réponse à une extraction de la ligne précédente, de la première ligne ou
de la deuxième dépend de la méthode d'optimisation de la requête, selon
que cette méthode implique la formation d'une table de travail et que la
ligne extraite a été préextraite à partir du client.
Pour la plupart des applications, la sensibilité du curseur est sans
importance, d'où l'avantage des curseurs à sensibilité indéfinie. Ainsi, si
vous utilisez un curseur en lecture seule à défilement avant uniquement,
aucune modification sous-jacente n'est visible. De même, si vous utilisez
un niveau d'isolement élevé, les modifications sous-jacentes sont
interdites.

Chapitre 2 Utilisation de SQL dans les applications
Exemple de sensibilité du curseur : mise à jour d'une ligne
Cet exemple utilise une requête simple pour illustrer comment différents
types de curseur réagissent à la mise à jour d'une ligne du jeu de résultats
entraînant une modification de l'ordre des résultats.
La succession des événements est la suivante :
1 Une application ouvre un curseur sur la requête suivante, qui concerne la
base de données exemple.
SELECT emp_id, emp_lname
FROM employee
emp_id emp_lname
102 Whitney
105 Cobb
160 Breault
… …
2 L'application extrait la première ligne (102) au moyen du curseur.
3 L'application extrait la ligne suivante (105) au moyen du curseur.
4 Une autre transaction remplace l'ID de l'employé 102 (Whitney) par 165
et valide la modification.
Dans ce cas, les résultats des actions du curseur varient selon sa sensibilité :
♦ Curseur insensible L'instruction UPDATE n'est répercutée ni sur
l'appartenance, si sur les valeurs du jeu de résultats associé au curseur.
Action Résultat
Extraction de la ligne
précédente
Extraction de la
première ligne
(extraction absolue)
Extraction de la
deuxième ligne
(extraction absolue)
Renvoie la copie originale de la ligne (102).
Renvoie la copie originale de la ligne (102).
Renvoie la ligne inchangée (105).
♦ Curseur sensible L'appartenance du jeu de résultats a changé, de sorte
que la ligne 105 est désormais la première du jeu de résultats.
33

Curseurs Adaptive Server Anywhere
34
Action Résultat
Extraction de la ligne
précédente
Extraction de la
première ligne
(extraction absolue)
Extraction de la
deuxième ligne
(extraction absolue)
Renvoie une erreur La ligne est introuvable.
L'appartenance du jeu de résultats a changé :
105 est désormais la première ligne. Le curseur est
placé avant la première ligne.
Renvoie la ligne 105.
Renvoie la ligne 160.
En outre, une extraction sur un curseur sensible renvoie l’avertissement
SQLE_ROW_UPDATED_WARNING si la ligne a été modifiée depuis sa
dernière extraction. L'avertissement n'est émis qu'une seule fois. Les
lectures suivantes de la même ligne ne le génèrent pas.
De même, une mise à jour ou une suppression positionnée effectuée via
le curseur sur une ligne depuis sa dernière extraction renvoie l'erreur
SQLE_ROW_UPDATED_SINCE_READ. L'application doit de
nouveau extraire la ligne avant de pouvoir exécuter une opération de
mise à jour ou de suppression sur un curseur sensible.
Toute mise à jour d'une colonne entraîne un avertissement ou une erreur,
même si cette colonne n'est pas référencée par le curseur. Par exemple,
un curseur positionné sur une requête renvoyant emp_lname signale la
mise à jour, même si seule la colonne salary a été modifiée.
♦ Curseur tenant compte des valeurs L'appartenance du jeu de résultats
étant fixe, la ligne 105 est toujours la deuxième du jeu de résultats.
L'instruction DELETE est répercutée sur les valeurs du curseur et crée
un "vide" dans le jeu de résultats.

Curseurs insensibles
Normes
Chapitre 2 Utilisation de SQL dans les applications
Action Résultat
Extraction de la ligne
précédente
Extraction de la
première ligne
(extraction absolue)
Extraction de la
deuxième ligne
(extraction absolue)
Renvoie une erreur La ligne est introuvable.
L'appartenance du jeu de résultats a changé :
105 est désormais la première ligne. Le curseur est
positionné sur l'emplacement "vide" : il se trouve
avant la ligne 105.
Renvoie une erreur La ligne est introuvable.
L'appartenance du jeu de résultats a changé :
105 est désormais la première ligne. Le curseur est
positionné sur le "vide" : il se trouve avant la
ligne 105.
Renvoie la ligne 105.
♦ Curseur à sensibilité indéfinie L’effet des modifications sur
l'appartenance et les valeurs du jeu de résultats est indéterminé. La
réponse à une extraction de la ligne précédente, de la première ligne ou
de la deuxième dépend de la méthode d'optimisation de la requête, selon
que cette méthode implique la formation d'une table de travail ou que la
ligne extraite a été préextraite à partir du client.
Pas d’avertissements ni d’erreurs en mode bulkcopy
Aucun avertissement ni message d'erreur n'est généré en mode bulkcopy
(option -b du serveur de base de données).
Ces curseurs sont insensibles en termes d'appartenance, d'ordre et de valeurs.
Aucune modification apportée après leur ouverture n'est visible.
Les curseurs insensibles ne sont utilisés qu'en lecture seule.
Les curseurs insensibles correspondent à la définition de la norme ISO/ANSI
en matière de curseurs insensibles et aux curseurs statiques ODBC.
35

Curseurs Adaptive Server Anywhere
Interfaces de
programmation
Description
Curseurs sensibles
Normes
36
Interface Type de
curseur
ODBC, OLE DB
et ADO
Embedded SQL INSENSITIVE
ou NO SCROLL
JDBC Non supporté.
Open Client Non supporté.
Commentaire
Statique Si un curseur statique modifiable est
demandé, un curseur tenant compte des
valeurs est utilisé à la place.
Les curseurs insensibles renvoient toujours des lignes répondant aux critères
de sélection de la requête, dans l'ordre spécifié par la clause ORDER BY.
Le jeu de résultats d'un curseur insensible est matérialisé sous forme de table
de travail lors de l'ouverture du curseur. Les conséquences sont les
suivantes :
♦ Si le jeu de résultats est très volumineux, l'espace disque et la mémoire
nécessaires pour le gérer peuvent être importants.
♦ Aucune ligne n'est renvoyée à l'application avant l'assemblage du jeu de
résultats sous forme de table de travail. Pour les requêtes complexes, il
peut ainsi s'écouler un certain temps avant que la première ligne ne soit
renvoyée à l'application.
♦ Les lignes suivantes peuvent être directement extraites de la table de
travail et sont donc renvoyées plus rapidement. La bibliothèque cliente
peut préextraire plusieurs lignes à la fois, ce qui améliore encore les
performances.
♦ Les instructions ROLLBACK et ROLLBACK TO SAVEPOINT n'ont
aucune incidence sur les curseurs insensibles.
Ces curseurs sont sensibles en termes d'appartenance, d'ordre et de valeurs.
Ils peuvent être utilisés pour les types de curseur en lecture seule ou
modifiables.
Les curseurs sensibles correspondent à la définition de la norme ISO/ANSI
en matière de curseurs sensibles, et aux curseurs dynamiques ODBC.

Interfaces de
programmation
Description
Interface Type de
curseur
ODBC, OLE DB
et ADO
Chapitre 2 Utilisation de SQL dans les applications
Dynamique
Commentaire
Embedded SQL SENSITIVE Egalement fourni en réponse à une
demande de curseur DYNAMIC
SCROLL lorsqu'aucune table de travail
n'est requise et que l'option PREFETCH
est désactivée (OFF).
Toutes les modifications sont visibles via le curseur, y compris celles
apportées au moyen du curseur et par d'autres transactions. Des niveaux
d'isolement supérieurs peuvent masquer certaines modifications apportées
dans d'autres transactions en raison d'un verrouillage.
Toutes les modifications apportées à l'appartenance, à l'ordre et aux valeurs
de colonne du curseur sont visibles. Par exemple, si un curseur sensible
contient une jointure et si une valeur d'une des tables sous-jacentes est
modifiée, toutes les lignes de résultat reposant sur cette ligne de base
affichent la nouvelle valeur. L'appartenance et l'ordre du jeu de résultats
peuvent changer à chaque extraction.
Les curseurs sensibles renvoient toujours des lignes répondant aux critères de
sélection de la requête, dans l'ordre spécifié par la clause ORDER BY.
L'appartenance, l'ordre et les valeurs du jeu de résultats peuvent être
modifiés.
La mise en oeuvre des curseurs sensibles est soumise à certaines restrictions :
♦ Les lignes ne peuvent pas être préextraites, puisque les modifications
apportées aux lignes préextraites ne seraient pas visibles via le curseur.
Cette restriction peut avoir des répercussions sur les performances.
♦ Les curseurs sensibles doivent être mis en oeuvre sans table de travail,
puisque les modifications apportées aux lignes stockées sous forme de
tables de travail ne seraient pas visibles via le curseur.
♦ Cette restriction limite le choix de l'optimiseur en matière de méthode de
jointure et peut donc avoir des répercussions sur les performances.
♦ Pour certaines requêtes, l'optimiseur est incapable d'établir un plan ne
comportant pas de table de travail qui rendrait le curseur sensible.
37

Curseurs Adaptive Server Anywhere
Curseurs à sensibilité indéfinie
Normes
Interfaces de
programmation
38
Les tables de travail sont généralement utilisées pour trier et regrouper
les résultats intermédiaires. Elles ne sont pas nécessaires pour le tri si les
lignes sont accessibles au moyen d'un index. S'il est impossible d'établir
une liste exhaustive des requêtes qui utilisent des tables de travail, en
voici toutefois quelques-unes :
♦ Requêtes UNION, même si UNION ALL n'utilise pas
nécessairement des tables de travail.
♦ Instructions comprenant une clause ORDER BY, si la colonne
ORDER BY ne comporte pas d'index.
♦ Requêtes optimisées à l'aide d'une jointure de hachage.
♦ La plupart des requêtes impliquant une clause DISTINCT ou
GROUP BY.
Dans ces cas, Adaptive Server Anywhere renvoie une erreur à
l'application ou remplace le curseur par un curseur à sensibilité indéfinie
avant d'émettre un avertissement.
$ Pour plus d'informations sur l'optimisation des requêtes et
l'utilisation de tables de travail, reportez-vous à la section "Optimisation
et exécution des requêtes", page 333 du document ASA Guide de
l’utilisateur SQL.
La sensibilité de ces curseurs en termes d'appartenance, d'ordre ou de valeurs
est mal définie. La souplesse autorisée en matière de sensibilité permet
d'optimiser les performances de ces curseurs.
Les curseurs à sensibilité indéfinie ne sont utilisés que pour les types de
curseur en lecture seule.
Les curseurs à sensibilité indéfinie correspondent à la définition de la norme
ISO/ANSI en matière de curseurs à sensibilité indéfinie, et aux curseurs
ODBC de sensibilité indéterminée.
Interface Type de curseur
ODBC, OLE DB et ADO Sensibilité indéterminée
Embedded SQL DYNAMIC SCROLL

Description
Chapitre 2 Utilisation de SQL dans les applications
Une demande de curseur à sensibilité indéfinie impose peu de restrictions sur
les méthodes qu'Adaptive Server Anywhere peut utiliser pour optimiser la
requête et renvoyer des lignes à l'application. Ces raisons expliquent que les
curseurs à sensibilité indéfinie offrent les meilleures performances.
L'optimiseur est en particulier libre d'utiliser n'importe quel moyen de
matérialisation des résultats intermédiaires sous forme de tables de travail, et
les lignes peuvent être préextraites par le client.
Adaptive Server Anywhere n'offre aucune garantie quant à la visibilité des
modifications apportées aux lignes sous-jacentes de base. Certaines
modifications peuvent être visibles, d'autres non. L'appartenance et l'ordre du
jeu de résultats peuvent changer à chaque extraction. Ainsi, il est possible
qu'après une modification des lignes de base, seules certaines colonnes mises
à jour soient reportées dans les résultats du curseur.
Il n'est pas certain que les curseurs à sensibilité indéfinie renvoient des lignes
répondant aux critères de sélection et à l'ordre spécifiés dans la requête.
L'appartenance des lignes est fixée à l'ouverture du curseur, mais les
modifications suivantes apportées aux valeurs sous-jacentes sont répercutées
sur les résultats.
Les curseurs à sensibilité indéfinie renvoient toujours des lignes
correspondant aux clauses WHERE et ORDER BY du client au moment où
l'appartenance du curseur est établie. En cas de modification des valeurs de
colonne après l'ouverture du curseur, il est possible que des lignes ne
correspondant plus aux clauses WHERE et ORDER BY soient renvoyées.
Curseurs tenant compte des valeurs
Normes
Interfaces de
programmation
Ces curseurs sont insensibles en termes d'appartenance et sensibles en
matière d'ordre et de valeurs du jeu de résultats.
Ils peuvent être utilisés pour les types de curseur en lecture seule ou
modifiables.
Les curseurs tenant compte des valeurs ne correspondent à aucune définition
de norme ISO/ANSI. Ils correspondent aux curseurs keyset ODBC.
Interface Type de curseur
ODBC, OLE DB et ADO Keyset
Embedded SQL SCROLL
JDBC Keyset
Open Client Keyset
39

Curseurs Adaptive Server Anywhere
Description
40
Si l'application extrait une ligne composée d'une ligne sous-jacente de base
ayant été modifiée, la valeur mise à jour et l'état SQL_ROW_UPDATED
doivent lui être transmis. Si l'application tente d'extraire une ligne qui était
composée d'une ligne sous-jacente de base supprimée, un état
SQL_ROW_DELETED doit lui être transmis.
Les modifications apportées aux valeurs de clé primaire retirent la ligne du
jeu de résultats (opération traitée comme une suppression suivie d'une
insertion). Lorsqu'une ligne du jeu de résultats est supprimée (que ce soit du
curseur ou en dehors du curseur) et qu'une nouvelle ligne comportant la
même valeur de clé est insérée, il s'agit d'un cas particulier. La nouvelle ligne
remplace alors l'ancienne, au même endroit.
Il n'est pas certain que les lignes du jeu de résultats répondent aux critères de
sélection ou à l'ordre indiqués dans la requête. L'appartenance des lignes
étant fixée lors de l'ouverture du curseur, les modifications suivantes, qui
font qu'une ligne ne correspond plus à la clause WHERE ou ORDER BY,
sont sans effet sur l'appartenance de la ligne, ni sur sa position.
Toutes les valeurs sont sensibles aux modifications apportées via le curseur.
La sensibilité de l'appartenance aux modifications apportées via le curseur
est contrôlée par l'option ODBC SQL_STATIC_SENSITIVITY. Si cette
option est activée, les insertions effectuées au moyen du curseur ajoutent la
ligne dans le curseur. Dans le cas contraire, elles ne sont pas incluses dans le
jeu de résultats. Les suppressions effectuées via le curseur retirent la ligne du
jeu de résultats, ce qui empêche tout "vide" renvoyant l'état
SQL_ROW_DELETED.
Les curseurs tenant compte des valeurs utilisent une table keyset. A
l'ouverture du curseur, Adaptive Server Anywhere remplit une table de
travail avec des informations qui identifient chaque ligne faisant partie du jeu
de résultats. Lors du défilement du jeu de résultats, la table keyset est utilisée
pour en identifier l'appartenance. En revanche, les valeurs sont extraites, si
nécessaire, à partir des tables sous-jacentes.
La propriété d'appartenance fixe des curseurs tenant compte des valeurs
permet à votre application de mémoriser la position des lignes d'un curseur
avec la certitude que ces positions ne changeront pas. Pour plus
d'informations, reportez-vous à la section "Exemple de sensibilité du
curseur : suppression d'une ligne", page 31.
♦ Si une ligne a été mise à jour ou est susceptible de l'avoir été depuis
l'ouverture du curseur, Adaptive Server Anywhere renvoie un état
SQLE_ROW_UPDATED_WARNING lors de l'extraction de la ligne.
L'avertissement n'est émis qu'une seule fois. Il ne réapparaît pas en cas
de nouvelle extraction de la ligne.

Chapitre 2 Utilisation de SQL dans les applications
La mise à jour d'une colonne de la ligne entraîne cet avertissement,
même si cette colonne n'est pas référencée par le curseur. Par exemple,
un curseur positionné sur emp_lname et emp_fname signale la mise à
jour, même si seule la colonne birthdate est modifiée. Ces messages et
conditions d'erreur n'apparaissent pas lorsque les opérations de mise à
jour sont effectuées en mode bulkcopy (option -b du serveur de base de
données) et que le verrouillage de ligne est désactivé. Voir
"Considérations sur les performances relatives au déplacement de
données", page 450 du document ASA Guide de l’utilisateur SQL.
$ Pour plus d'informations, reportez-vous à la section "La ligne a été
mise à jour depuis la dernière fois qu'elle a été lue", page 176 du
document ASA Messages d’erreur.
♦ Une tentative d'exécution de mise à jour ou de suppression positionnée
sur une ligne ayant été modifiée depuis sa dernière extraction renvoie
une erreur SQLE_ROW_UPDATED_SINCE_READ et annule
l'instruction. L'application doit de nouveau extraire la ligne avant de
pouvoir exécuter l'opération UPDATE ou DELETE.
La mise à jour d'une colonne de la ligne entraîne cette erreur, même si la
colonne n'est pas référencée par le curseur. Cette erreur ne se produit pas
en mode bulkcopy.
$ Pour plus d'informations, reportez-vous à la section "La ligne a été
modifiée depuis qu'elle a été lue pour la dernière fois - l'opération est
annulée", page 176 du document ASA Messages d’erreur.
♦ Si une ligne a été supprimée après l'ouverture du curseur, que ce soit au
moyen du curseur ou par une autre transaction, un vide est créé dans le
curseur. L'appartenance du curseur étant fixe, une position de ligne est
réservée, mais l'opération DELETE est répercutée sur la valeur modifiée
de la ligne. Si vous extrayez la ligne au niveau de ce vide, une erreur
Aucune ligne de curseur n'est actuellement sélectionnée
(état SQL 24503) est générée. Elle indique qu'il n'existe pas de ligne
courante, et le curseur reste positionné sur le vide. Vous pouvez éviter
les vides en utilisant des curseurs sensibles, dont l'appartenance change
avec les valeurs.
$ Pour plus d'informations, reportez-vous à la section "Aucune ligne
de curseur n'est actuellement sélectionnée", page 88 du document ASA
Messages d’erreur.
Avec les curseurs tenant compte des valeurs, les lignes ne peuvent pas être
préextraites. Cette restriction peut avoir des répercussions sur les
performances.
41

Curseurs Adaptive Server Anywhere
Sensibilité du curseur et performances
42
Il existe un compromis entre les performances et les autres propriétés du
curseur. C'est en particulier le cas lorsqu'un curseur est rendu modifiable.
Des restrictions sont alors imposées au traitement et à la transmission de la
requête du curseur, d'où une réduction des performances. De même, imposer
des conditions de sensibilité du curseur peut entraîner une diminution de ses
performances.
Pour saisir pourquoi la possibilité de mise à jour et la sensibilité des curseurs
ont une incidence sur les performances, vous devez comprendre comment la
base de données transmet les résultats visibles via un curseur à l'application
cliente.
Les résultats peuvent être stockés dans deux emplacements intermédiaires
pour des raisons de performances :
♦ Tables de travail Les résultats intermédiaires ou finaux peuvent être
stockés sous forme de tables de travail. Les curseurs tenant compte des
valeurs utilisent une table de travail des valeurs de clé primaire. Les
caractéristiques de la requête peuvent également amener l'optimiseur à
utiliser des tables de travail dans le plan d'exécution qu'il a choisi.
♦ Préextraction Dans une communication, le client peut extraire des
lignes dans un buffer de son côté pour éviter qu'une demande soit
envoyée au serveur de base de données pour chaque ligne.
Application
cliente
Pilote ODBC ou
bibliothèque réseau
Prélecture
de lignes
Serveur de base
de données
Table de
travail
La définition de la sensibilité et de la possibilité de mise à jour limitent
l'utilisation des emplacements intermédiaires.
Les curseurs modifiables ne peuvent pas utiliser de tables de travail, ni
préextraire des résultats. S'ils y étaient autorisés, ils seraient vulnérables en
termes de perte de mises à jour. Par exemple :
1 Une application ouvre un curseur sur la requête suivante, qui concerne la
base de données exemple.

Préextraction de lignes
Chapitre 2 Utilisation de SQL dans les applications
SELECT id, quantity
FROM product
id quantity
300 28
301 54
302 75
… …
2 L’application extrait la ligne comportant l’id 300 au moyen du curseur.
3 Une autre transaction met la ligne à jour au moyen de l'instruction
suivante :
UPDATE product
SET quantity = quantity - 10
WHERE id = 300
4 L'application remplace la valeur de la ligne via le curseur par
(quantity - 5 ).
5 La valeur correcte finale de la ligne est 13. Si le curseur avait préextrait
la ligne, sa nouvelle valeur aurait été 23. La mise à jour de l'autre
transaction aurait donc été perdue.
La sensibilité est soumise à des restrictions de même ordre. Pour plus
d'informations, reportez-vous à la description des différents types de curseur.
Prélecture et extractions multiligne sont deux opérations distinctes. Vous
pouvez effectuer une prélecture sans instruction explicite de l'application
cliente. La prélecture extrait des lignes d'un serveur pour les placer dans un
buffer du côté client, mais ne met ces lignes à disposition de l'application
cliente que lorsque la ligne concernée est lue par l'application.
Par défaut, la bibliothèque client Adaptive Server Anywhere effectue une
prélecture de plusieurs lignes dès qu'une application lit une ligne. Elle stocke
les lignes supplémentaires dans un buffer.
La prélecture améliore les performances en réduisant le trafic client/serveur,
et accélère les opérations en mettant à disposition plusieurs lignes
simultanément sans qu'il soit nécessaire de demander au serveur chaque ligne
ou chaque bloc de lignes séparément.
$ Pour plus d'informations sur le contrôle des préextractions, reportezvous
à la section "Option PREFETCH", page 646 du document ASA Guide
d’administration.
43

Curseurs Adaptive Server Anywhere
Contrôle de la
prélecture à partir
d'une application
44
♦ L'option PREFETCH permet d'indiquer si une prélecture doit avoir lieu
ou non. Elle peut être définie à ON ou OFF pour une seule connexion.
ON est la valeur par défaut.
♦ Dans Embedded SQL, vous pouvez contrôler la préextraction lorsque
vous ouvrez un curseur, ou en spécifiant la clause BLOCK dans une
opération FETCH.
L'application peut spécifier la clause BLOCK, qui permet de préciser le
nombre maximal de lignes pouvant être contenues dans un bloc. Par
exemple, spécifiez BLOCK 5 pour extraire et afficher 5 lignes à la fois.
BLOCK 0 ne permet d'extraire qu'un seul enregistrement à la fois et
génère un FETCH RELATIVE 0 (réextraction de la ligne).
Bien qu'il soit possible de désactiver la prélecture en définissant un
paramètre de connexion au niveau de l'application, il est préférable
d'utiliser BLOCK=0 à la place d'une option PREFETCH définie à OFF.
$ Pour plus d'informations, reportez-vous à la section "Option
PREFETCH", page 646 du document ASA Guide d’administration.
♦ Dans Open Client, vous pouvez contrôler la prélecture, une fois le
curseur déclaré, mais pas encore ouvert, via ct_cursor avec
CS_CURSOR_ROWS.
Sensibilité du curseur et niveaux d'isolement
La sensibilité du curseur et les niveaux d'isolement des transactions
répondent au problème de la concurrence d'accès, mais de façon différente.
En choisissant un niveau d'isolement pour une transaction (généralement au
niveau de la connexion), vous déterminez à quel moment des verrous sont
appliqués aux lignes de la base de données. Les verrous empêchent les autres
transactions d'accéder aux valeurs de la base ou de les modifier.
En choisissant une sensibilité de curseur, vous déterminez les modifications
visibles par l'application au moyen du curseur. En définissant la sensibilité
du curseur, vous ne déterminez pas à quel moment des verrous sont posés sur
les lignes de la base de données, pas plus que vous ne limitez les
modifications autorisées dans la base elle-même.

Description des jeux de résultats
Chapitre 2 Utilisation de SQL dans les applications
Certaines applications construisent des instructions SQL qui ne peuvent pas
être entièrement spécifiées dans l'application. Ainsi, dans certains cas, les
instructions dépendent de la réponse que l'utilisateur va apporter, de sorte
que l'application ne sait pas exactement quelle information renvoyer ; c'est
par exemple le cas lorsqu'une application de génération de rapport autorise
un utilisateur à sélectionner les colonnes qu'il souhaite afficher.
Dans ce type de situation, l'application doit faire appel à une méthode pour
rechercher les informations sur la nature du jeu de résultats et sur son
contenu. Les informations sur la nature du jeu de résultats, appelées
descripteur, identifient la structure des données, y compris le nombre et le
type de colonnes qu'il est prévu de renvoyer. Une fois que l'application a
déterminé la nature du jeu de résultats, elle peut récupérer directement son
contenu.
Ces métadonnées du jeu de résultats (c'est-à-dire les informations sur la
nature et le contenu des données) sont manipulées par des descripteurs. Le
processus d'obtention et de gestion des métadonnées du jeu de résultats
s'appelle la description.
Les jeux de résultats étant généralement obtenus à partir des curseurs,
descripteurs et curseurs sont étroitement liés, bien que dans certaines
interfaces, l'utilisation des descripteurs soit transparente pour l'utilisateur. En
règle générale, les instructions qui requièrent un descripteur sont soit des
instructions SELECT, soit des procédures stockées qui renvoient des jeux de
résultats.
La séquence d'utilisation d'un descripteur avec une opération fondée sur un
curseur est la suivante :
1 Allouez le descripteur. Cette opération peut être implicite, bien que
certaines interfaces autorisent l'allocation implicite.
2 Préparez l'instruction.
3 Décrivez l'instruction. Si celle-ci est un appel de procédure stockée ou
un batch et si le résultat ne dépend pas d'une clause de résultat dans la
définition de la procédure, la description doit intervenir après l'ouverture
du curseur.
4 Déclarez et ouvrez un curseur pour l'instruction (Embedded SQL) ou
exécutez l'instruction.
5 Récupérez le descripteur et modifiez si nécessaire la zone allouée. Cette
opération est souvent implicite.
6 Lisez et traitez les résultats de l'instruction.
45

Description des jeux de résultats
Remarques sur la
mise en oeuvre
46
7 Annulez l’allocation du descripteur.
8 Ferme le curseur.
9 Supprimez l’instruction. Certaines interfaces le font automatiquement.
♦ Dans Embedded SQL, une structure SQLDA (SQL Descriptor Area)
contient les informations propres au descripteur.
$ Pour plus d'informations, reportez-vous à la section "Zone
descripteur SQL (SQLDA)", page 226.
♦ Dans ODBC, un gestionnaire de descripteur, alloué via
SQLAllocHandle, donne accès aux champs des descripteurs. Vous
manipulez ces champs à l'aide de SQLSetDescRec, SQLSetDescField,
SQLGetDescRec et SQLGetDescField.
Vous pouvez également utiliser SQLDescribeCol et SQLColAttributes
pour obtenir des informations sur les colonnes.
♦ Dans Open Client, vous pouvez utiliser ct_dynamic pour préparer une
instruction et ct_describe pour décrire le jeu de résultats obtenu. Mais il
est également possible d'utiliser ct_command pour envoyer une
instruction SQL sans préparation préalable, puis ct_results pour gérer
les lignes renvoyées une par une. C'est la méthode la plus courante pour
le développement d'applications Open Client.
♦ Dans JDBC, la classe java.SQL.ResultSetMetaData fournit des
informations sur les jeux de résultats.
♦ Vous pouvez également utiliser des descripteurs pour envoyer des
données au moteur (avec une instruction INSERT, par exemple).
Toutefois, ce type de descripteur diffère de celui mis en oeuvre dans des
jeux de résultats.
$ Pour plus d'informations sur les paramètres d'entrée et de sortie de
l'instruction DESCRIBE, reportez-vous à la section "Instruction
DESCRIBE [ESQL]", page 414 du document ASA Manuel de référence
SQL.

Chapitre 2 Utilisation de SQL dans les applications
Contrôle des transactions dans les applications
Les transactions sont des ensembles atomiques d’instructions SQL. Toutes
les instructions d'une transaction sont exécutées ou aucune ne l'est. Cette
section traite de quelques aspects des transactions dans les applications.
$ Pour en savoir plus sur les transactions, reportez-vous au chapitre
"Transactions et niveaux d'isolement", page 93 du document ASA Guide de
l’utilisateur SQL.
Définition du mode autocommit ou commit manuel
Les interfaces de programmation de bases de données peuvent fonctionner en
mode commit manuel ou autocommit.
♦ Mode commit manuel Les opérations ne sont validées que lorsque
l'application effectue une opération COMMIT explicite ou lorsque le
serveur de base de données procède à une validation automatique, par
exemple lors de l'exécution d'une instruction ALTER TABLE ou de
toute autre instruction de définition de données. Le mode commit
manuel est quelquefois appelé mode chaîné.
Pour utiliser des transactions dans votre application, notamment des
transactions imbriquées et des points de sauvegarde, vous devez
travailler en mode commit manuel.
♦ Mode autocommit Chaque instruction est traitée comme une transaction
distincte. Ce mode revient en effet à ajouter une instruction COMMIT à
la fin de chacune de vos commandes. Le mode autocommit est
quelquefois appelé mode non chaîné.
Ce mode de fonctionnement peut avoir des répercussions sur les
performances et le comportement de votre application. Ne l'utilisez pas si
l'intégrité transactionnelle doit être respectée dans votre application.
$ Pour plus d'informations sur les effets du mode autocommit sur les
performances, reportez-vous à la section "Désactivez le mode de validation
automatique", page 158 du document ASA Guide de l’utilisateur SQL.
Contrôle du comportement du mode autocommit
La façon dont vous contrôlez le comportement de votre application en
matière de validation dépend de l'interface de programmation utilisée. Selon
l'interface, la mise en oeuvre du mode autocommit peut en effet être
effectuée côté client ou côté serveur.
47

Contrôle des transactions dans les applications
48
$ Pour plus d'informations, reportez-vous à la section "Détails de mise en
oeuvre du mode autocommit", page 48.
v Pour contrôler le mode autocommit (ODBC) :
♦ Par défaut, ODBC opère en mode autocommit. La façon dont vous
pouvez désactiver le mode autocommit varie selon que vous utilisez
directement ODBC ou un outil de développement d'applications. Si vous
procédez à la programmation directement dans l'interface ODBC,
définissez l'attribut de connexion SQL_ATTR_AUTOCOMMIT.
v Pour contrôler le mode autocommit (JDBC) :
♦ Par défaut, JDBC opère en mode autocommit. Pour désactiver le mode
autocommit, utilisez la méthode setAutoCommit de l'objet Connection :
conn.setAutoCommit( false );
v Pour contrôler le mode autocommit (Open Client) :
♦ Par défaut, une connexion établie via Open Client opère en mode
autocommit. Vous pouvez changer de mode en définissant l'option de
base de données CHAINED à ON dans votre application, par le biais
d'une instruction similaire à celle qui suit :
SET OPTION CHAINED=’ON’
v Pour contrôler le mode autocommit (Embedded SQL) :
♦ Par défaut, les applications Embedded SQL opèrent en mode commit
manuel. Pour activer le mode autocommit, définissez l'option de base de
données CHAINED à OFF par le biais d'une instruction similaire à celle
qui suit :
SET OPTION CHAINED=’OFF’
Détails de mise en oeuvre du mode autocommit
La section précédente, "Contrôle du comportement du mode autocommit",
page 47, décrit comment contrôler le comportement du mode autocommit à
partir de chacune des interfaces de programmation d'Adaptive Server
Anywhere. Le comportement du mode autocommit varie légèrement selon
l'interface que vous utilisez et la façon dont vous le contrôlez.
Il peut être mis en oeuvre de deux façons :
♦ Autocommit côté client Lorsqu’une application utilise le mode
autocommit, la bibliothèque cliente émet une instruction COMMIT
après chaque instruction SQL exécutée.

Contrôle du niveau d'isolement
Curseurs et transactions
Chapitre 2 Utilisation de SQL dans les applications
Adaptive Server Anywhere se sert du mode autocommit côté client pour
les applications ODBC et OLE DB.
♦ Autocommit côté serveur Lorsqu’une application utilise le mode
autocommit, le serveur de base de données émet une instruction
COMMIT après chaque instruction SQL. Ce comportement est contrôlé,
implicitement en ce qui concerne JDBC, par l'option de base de données
CHAINED.
Adaptive Server Anywhere se sert du mode autocommit côté serveur
pour les applications Embedded SQL, JDBC et Open Client.
Il existe une différence entre le mode autocommit côté client et côté serveur
en cas d'instructions composées telles que les procédures stockées ou les
triggers. Côté client, une procédure stockée est une instruction unique. Le
mode autocommit envoie donc une instruction COMMIT une fois la
procédure entièrement exécutée. Du point de vue du serveur de base de
données, la procédure stockée peut être composée de plusieurs
instructions SQL. Le mode autocommit côté serveur émet alors une
instruction COMMIT après chaque instruction SQL de la procédure.
Ne combinez pas les mises en oeuvre côté client et côté serveur
N'utilisez pas l'option CHAINED en même temps que le mode
autocommit dans une application ODBC ou OLE DB.
Le niveau d'isolement d'une connexion active est défini via l'option de base
de données ISOLATION_LEVEL.
Certaines interfaces, telle qu'ODBC, permettent de définir le niveau
d'isolement d'une connexion au moment de la connexion. Ce niveau peut être
réinitialisé ultérieurement via l'option de base de données
ISOLATION_LEVEL.
En général, un curseur est fermé lorsqu'un COMMIT est exécuté. Il existe
deux exceptions :
♦ L'option de base de données CLOSE_ON_ENDTRANS a la
valeur OFF.
♦ Un curseur est ouvert avec la clause WITH HOLD, ce qui est le
comportement par défaut avec Open Client et JDBC.
49

Contrôle des transactions dans les applications
ROLLBACK et
curseurs
Points de
sauvegarde
Curseurs et
niveaux
d’isolement
50
Dans l’un ou l’autre cas, le curseur reste ouvert en cas de COMMIT.
Si une transaction est annulée, les curseurs sont fermés, sauf ceux ouverts
WITH HOLD. Cependant, n'oubliez pas qu'après une annulation, le contenu
des curseurs, quels qu'ils soient, n'est pas fiable.
L'avant-projet de norme ISO SQL3 spécifie qu'après une annulation, tous les
curseurs (même ceux ouverts avec la clause WITH HOLD) doivent être
fermés. Pour ce faire, donnez à l'option
ANSI_CLOSE_CURSORS_AT_ROLLBACK la valeur ON.
Si une transaction est annulée jusqu'à un point de sauvegarde et si l'option
ANSI_CLOSE_CURSORS_AT_ROLLBACK a la valeur ON, tous les
curseurs ouverts après le point de sauvegarde (même ceux ouverts avec la
clause WITH HOLD) sont fermés.
Vous pouvez modifier le niveau d'isolement d'une connexion pendant une
transaction via l'instruction SET OPTION pour modifier l'option
ISOLATION_LEVEL. Toutefois, ce changement n'a d'incidence que sur les
curseurs fermés.

CHAPITRE 3
Présentation de Java dans la base de
données
Présentation
Sommaire
Ce chapitre présente les concepts de l'utilisation de Java dans la base de
données et décrit les avantages qu'elle procure.
Adaptive Server Anywhere est un environnement d'exécution de Java.
Véritable extension naturelle de SQL, Java fait d'Adaptive Server Anywhere
une véritable plate-forme pour la prochaine génération d'applications
d'entreprise.
Sujet Page
Introduction 52
FAQ concernant Java dans la base de données 55
Séminaire Java 62
Environnement d'exécution pour Java dans la base de données 73
Didacticiel : Java dans la base de données - Exercice pratique 82
51

Introduction
Introduction
Composant sous
licence séparée
La norme SQLJ
52
Adaptive Server Anywhere est un environnement d'exécution de Java.
Cela signifie que les classes Java peuvent être exécutées dans le serveur de la
base de données. Cette intégration d'un environnement d'exécution des
classes Java dans le serveur de la base de données ouvre de très vastes
perspectives en matière de gestion et de stockage des données et de la
logique.
Au niveau de la base de données, Java apporte les avantages suivants :
♦ Vous pouvez réutiliser les composants Java dans les différentes couches
de l'application (client, niveau intermédiaire et serveur) et les appliquer
aux endroits qui vous paraissent les plus pertinents. Adaptive Server
Anywhere devient une véritable plate-forme pour l'informatique
distribuée.
♦ Java est un langage bien plus puissant que les procédures stockées pour
intégrer de la logique dans la base de données.
♦ Les classes Java deviennent de puissants types de données définis par
l'utilisateur.
♦ Les méthodes des classes Java offrent de nouvelles fonctions accessibles
depuis SQL.
♦ Vous pouvez utiliser Java dans la base de données sans mettre en péril
son intégrité, sa sécurité ou sa fiabilité.
Java dans la base de données est un composant faisant l'objet d'une licence
séparée. Pour commander ce composant, utilisez le formulaire disponible
dans votre package SQL Anywhere Studio package ou reportez-vous à
l'adresse http://www.sybase.com/detail?id=1015780.
Java dans la base de données repose sur les normes proposées SQLJ Partie 1
et SQLJ Partie 2. SQLJ Partie 1 fournit les spécifications pour les appels de
méthodes statiques comme les procédures stockées SQL et les fonctions
définies par l'utilisateur. SQLJ Partie 2 fournit les spécifications d'utilisation
des classes Java, telles que les domaines SQL.
Présentation de Java dans la base de données
Java est un langage de programmation relativement récent pour lequel la
base de connaissances, certes en plein développement, reste limitée. La
présente documentation s'adresse non seulement à tous ceux qui ne
maîtrisent pas encore ce langage, ses possibilités, sa syntaxe et son
utilisation, mais aussi aux développeurs Java expérimentés.

Documentation
relative à Java
Chapitre 3 Présentation de Java dans la base de données
Ces derniers découvriront avec profit l'utilisation de Java dans la base de
données. Adaptive Server Anywhere accroît non seulement les capacités de
la base de données grâce à Java, mais élargit aussi les possibilités de Java en
l'associant à la base de données.
Le tableau suivant présente les différents éléments de la documentation
relative à l'utilisation de Java dans la base de données.
Titre Fonction
"Présentation de Java dans la
base de données", page 51 (le
présent chapitre)
"Utilisation de Java dans la
base de données", page 91
"Accès aux données via
JDBC", page 139
"Débogage d'une logique dans
une base de données",
page 607 du document ASA
Guide de l’utilisateur SQL
Documentation d'Adaptive
Server Anywhere
Reference guide to Sun's Java
API
Thinking in Java, de Bruce
Eckel.
Utilisation de la documentation Java
Présentation des concepts de Java et de leur
application dans Adaptive Server Anywhere.
Présentation des différentes étapes de
l'utilisation de Java dans la base de données.
Description de l'accès aux données à partir des
classes Java, et notamment l'informatique
distribuée.
Présentation des procédures de test et de
débogage du code Java exécuté dans la base de
données.
Le Manuel de référence SQL comprend des
informations sur les extensions SQL qui
supportent Java dans la base de données.
Guide en ligne relatif aux classes, champs et
méthodes de l'API Java. Disponible uniquement
comme aide Windows.
Documentation en ligne pour l'apprentissage de
la programmation en Java. Disponible au
format PDF d'Adobe dans le sous-répertoire
Samples\ASA\Java du répertoire
SQL Anywhere.
Le tableau suivant indique quelles parties de la documentation relative à Java
consulter en fonction des thèmes recherchés. Ces orientations n'ont qu'une
valeur indicative et ne doivent en rien brider votre exploration de l'utilisation
de Java dans la base de données.
53

Introduction
54
Si... Consultez...
Vous débutez dans la programmation
orientée objet.
Vous voulez une définition de termes tels
que instance, champ et méthode de
classe.
Vous maîtrisez déjà le développement en
Java et souhaitez juste quelques
informations pour démarrer.
Vous voulez connaître les fonctionnalités
clés de Java dans la base de données.
Vous voulez maîtriser l'accès aux
données à partir de Java.
Vous voulez préparer une base de
données pour Java.
Vous voulez consulter une liste complète
des API Java gérées.
Vous voulez obtenir des informations de
référence sur Java pendant l'utilisation
d'une classe d'API Java.
Vous voulez découvrir un exemple
d'informatique distribuée.
"Séminaire Java", page 62
Thinking in Java de Bruce Eckel.
"Séminaire Java", page 62
"Environnement d'exécution pour
Java dans la base de données",
page 73
"Didacticiel : Java dans la base de
données - Exercice pratique", page 82
"FAQ concernant Java dans la base
de données", page 55
"Accès aux données via JDBC",
page 139
"Configuration de la base de données
pour Java", page 95
"Types de données de classe Java",
page 82 du document ASA Manuel de
référence SQL
Le guide en ligne des classes d'API
Java (Aide Windows uniquement)
"Création d'applications distribuées",
page 171.

Chapitre 3 Présentation de Java dans la base de données
FAQ concernant Java dans la base de données
Cette section présente les fonctionnalités clés de Java dans la base de
données.
Fonctionnalités clés de Java dans la base de données
Tous les points ci-dessous sont décrits en détail dans les sections suivantes.
♦ Exécution de Java dans le serveur de la base de données Une
machine virtuelle (VM) Java interne exécute le code Java dans le
serveur de la base de données.
♦ Appel de Java à partir de SQL Vous pouvez appeler les fonctions Java
(méthodes) à partir d'instructions SQL. Les méthodes Java constituent
un langage bien plus puissant que les procédures stockées SQL pour
ajouter de la logique à la base de données.
♦ Accès aux données depuis Java Un gestionnaire JDBC interne permet
d'accéder aux données depuis Java.
♦ Débogage de Java dans la base de données Le débogueur Sybase
permet de tester et déboguer les classes Java dans la base de données.
♦ Utilisation de classes Java comme types de données Toute classe
Java installée dans une base de données est utilisable comme type de
données d'une colonne dans une table ou une variable.
♦ Enregistrement d’objets Java dans des tables Toute instance d'une
classe Java (un objet Java) peut être enregistrée sous forme de valeur
dans une table. Vous pouvez insérer les objets Java dans une table,
exécuter des instructions SELECT sur les champs et les méthodes des
objets stockés dans une table et extraire les objets Java d'une table.
Avec cette fonctionnalité, Adaptive Server Anywhere devient une base
de données relationnelle objet, capable de gérer les objets sans altérer la
fonctionnalité relationnelle existante.
♦ Préservation de SQL L'utilisation de Java n'altère en rien l'action des
instructions SQL existantes ou celle d'autres aspects des bases de
données relationnelles non Java.
55

FAQ concernant Java dans la base de données
Stockage des instructions Java dans la base de données
56
Java est un langage orienté objet, c'est-à-dire que ses instructions (son code
source) se présentent sous forme de classes. Pour exécuter Java dans une
base de données, vous devez écrire les instructions Java, puis les compiler en
classes (code octet), c'est-à-dire en fichiers binaires contenant les
instructions Java, en dehors de la base de données.
Ensuite, vous installez ces classes compilées dans la base de données. Une
fois installées, ces classes peuvent être exécutées dans le serveur de la base
de données.
Adaptive Server Anywhere est un environnement d'exécution des classes
Java, pas un environnement de développement Java. Pour écrire et compiler
en Java, il faut un environnement de développement Java, tel que
Sybase PowerJ ou le Java Development Kit de Sun Microsystems.
$ Pour plus d'informations, reportez-vous à la section "Installation de
classes Java dans une base de données", page 101.
Exécution de Java dans une base de données
Différences avec
une machine
virtuelle autonome
Adaptive Server Anywhere comprend une machine virtuelle Java qui est
exécutée dans l'environnement de la base de données. La machine virtuelle
Sybase Java interprète les instructions Java compilées, puis les exécute dans
le serveur de la base de données.
En plus de la machine virtuelle, le processeur de requêtes SQL du serveur de
la base de données a également été étendu de façon à pouvoir lancer la
machine virtuelle pour exécuter des instructions Java. Il peut aussi traiter des
requêtes à partir de la machine virtuelle, pour permettre l'accès aux données
depuis Java.
Exécuter du code Java à l'aide d'une machine virtuelle standard (comme la
machine virtuelle Sun Java java.exe) n'est pas la même chose qu'exécuter du
code Java dans la base de données. En effet, la machine virtuelle Sun est
exécutée à partir d'une ligne de commande, tandis que la machine virtuelle
Java d'Adaptive Server Anywhere est disponible à tous moments pour
exécuter une opération Java requise dans l'exécution d'une instruction SQL.
En outre, l'interpréteur Java de Sybase est inaccessible depuis l'extérieur. Il
est utilisé uniquement lorsque l'exécution d'une instruction SQL implique la
réalisation d'une opération Java. Lorsque cela est nécessaire, le serveur de la
base de données lance automatiquement la machine virtuelle. Vous
n'intervenez à aucun moment pour lancer ou arrêter la machine virtuelle.

Avantages de Java
Chapitre 3 Présentation de Java dans la base de données
Java offre un certain nombre de fonctionnalités parfaitement adaptées à son
utilisation dans la base de données.
♦ Recherche approfondie d'erreurs lors de la compilation.
♦ Gestion intégrée des erreurs sur la base d'une méthodologie clairement
définie.
♦ Défragmentation intégrée de la mémoire (récupération de la mémoire).
♦ Elimination de nombreuses techniques de programmation sujettes aux
bugs.
♦ Puissantes fonctionnalités de sécurité.
♦ Le code Java étant interprété, aucune opération n'est exécutée si elle ne
peut pas être acceptée par la machine virtuelle.
Plates-formes supportant Java dans la base de données
Java dans la base de données n'est pas supporté par Windows CE. Il est
supporté par les autres plates-formes Windows, UNIX et NetWare.
Utilisation combinée de Java et SQL
L'intégration de Java dans la base de données a été conçue pour constituer
une extension naturelle et ouverte à la fonctionnalité SQL existante.
♦ Appel des opérations Java à partir de SQL Sybase a étendu la gamme
des expressions SQL pour y inclure les propriétés et méthodes des objets
Java, ce qui permet d'intégrer des opérations Java dans une instruction
SQL.
♦ Classes Java, véritables domaines Le stockage des classes Java
s'opère via les mêmes instructions SQL que celles employées pour les
types de données SQL classiques.
Vous pouvez utiliser de nombreuses classes de l'API Java contenues dans le
JDK (Java Development Kit) de Sun Microsystems. Vous pouvez également
utiliser des classes créées et compilées par les développeurs Java.
57

FAQ concernant Java dans la base de données
Présentation de l'API Java
Accès à Java à partir de SQL
58
L’API (Application Programmer’s Interface) Java est un ensemble de classes
créé par Sun Microsystems. Elle offre une gamme de fonctionnalités de base
que les développeurs Java peuvent utiliser et même développer. C'est elle qui
confère à Java toute sa valeur.
A elle seule, l'API Java offre un nombre considérable de fonctionnalités.
Toute base de données capable d'utiliser le code Java comporte une part
importante de l'API Java. En l'occurrence, il s'agit de la majorité des classes
non visuelles de l'API Java, auxquelles sont déjà habitués les développeurs
qui utilisent le JDK (Java Development Kit) de Sun Microsystems.
$ Pour plus d'informations sur les API Java supportées, reportez-vous à la
section "Packages Java supportés", page 83 du document ASA Manuel de
référence SQL.
L'API Java peut être utilisée dans des classes, mais également dans des
procédures stockées et des instructions SQL. Vous pouvez effectivement
considérer les classes de l'API Java comme des extensions des fonctions
intégrées proposées par SQL.
Par exemple, la fonction SQL PI(*) renvoie la valeur de PI. La classe API
Java java.lang.Math comprend un champ parallèle appelé PI renvoyant la
même valeur. Cependant, java.lang.Math comporte également un champ
nommé E qui renvoie la base des logarithmes naturels, ainsi qu'une méthode
calculant le reste sur deux arguments, comme le prévoit la norme IEEE 754.
D'autres éléments de l'API Java offrent des fonctionnalités encore plus
spécialisées. Par exemple, java.util.Stack génère une file d'attente LIFO
(dernier entré, premier sorti) capable de stocker une liste triée,
java.util.HashTable met en correspondance des valeurs et des clés, et
java.util.StringTokenizer découpe une chaîne de caractères en mots.
$ Pour plus d'informations, reportez-vous à la section "Insertion, mise à
jour et suppression d'objets Java", page 108.

Classes Java supportées
Chapitre 3 Présentation de Java dans la base de données
La base de données ne supporte pas toutes le classes de l'API Java. Certaines
classes, telles que le package java.awt qui contient des composants
d'interface utilisateur destinés à des applications, n'ont pas leur place dans un
serveur de base de données. D'autres, notamment certaines parties de java.io,
ont trait à l'écriture d'informations sur disque et ne sont pas supportées dans
l'environnement de serveur de base de données.
$ Pour plus d'informations sur les classes supportées et non supportées,
reportez-vous aux sections "Packages Java supportés", page 83 du document
ASA Manuel de référence SQL et "Packages et classes Java non supportés",
page 84 du document ASA Manuel de référence SQL.
Utilisation de classes Java personnelles dans des bases de
données
Vous pouvez installer vos propres classes Java dans une base de données. Par
exemple, il peut s'agir d'une classe Employee ou Package créée par un
développeur qui l'a écrite en Java, puis compilée à l'aide d'un compilateur
Java.
Les classes Java créées par l'utilisateur peuvent contenir des informations sur
le sujet, ainsi que certains éléments de logique de calcul. Dès lors que ces
classes sont installées dans une base de données, Adaptive Server Anywhere
vous permet de les utiliser dans tous les compartiments et toutes les
opérations de la base, et d'exécuter leur fonctionnalité (sous forme de
méthodes de classe ou d'instance) aussi facilement que vous appelez une
procédure stockée.
Différence entre classes Java et procédures stockées
Les classes Java sont différentes des procédures stockées. Les procédures
stockées sont écrites en SQL ; pour leur part, les classes Java reposent sur
un langage beaucoup plus puissant et peuvent néanmoins être appelées
depuis des applications clientes de la même manière que les procédures
stockées.
Lorsqu'une classe Java est installée dans une base de données, elle est
disponible en tant que domaine. Vous utilisez une classe Java dans les
mêmes circonstances qu'un type de données SQL intégré : comme type de
colonne dans une table ou comme type de variable.
59

FAQ concernant Java dans la base de données
Accès aux données via Java
60
Par exemple, si une classe nommée Address a été installée dans une base de
données, la colonne Addr d'une table peut être de type Address. Cela
implique que seuls les objets basés sur la classe Address peuvent être
enregistrés comme valeurs de ligne dans cette colonne.
$ Pour plus d'informations, reportez-vous à la section "Installation de
classes Java dans une base de données", page 101.
L'interface JDBC est un standard de l'industrie spécifiquement développée
pour l'accès aux systèmes de base de données. Les classes JDBC sont donc
conçues pour permettre la connexion à une base de données, la demande de
données via des instructions SQL et le renvoi de jeux de résultats
exploitables dans l'application cliente.
Normalement, les classes JDBC sont utilisées dans une application cliente et
les constructeurs de systèmes de base de données fournissent un pilote JDBC
permettant aux classes JDBC d'établir une connexion.
La connexion à Adaptive Server Anywhere depuis une application cliente via
JDBC est possible à l'aide de jConnect ou d'une passerelle JDBC/ODBC.
Adaptive Server Anywhere propose également un gestionnaire JDBC interne
grâce auquel les classes Java installées dans une base de données peuvent
utiliser les classes JDBC qui exécutent des instructions SQL.
$ Pour plus d'informations, reportez-vous à la section "Accès aux données
via JDBC", page 139.
Déplacement de classes du client vers le serveur
Vous pouvez créer des classes Java que vous déplacerez au besoin entre les
niveaux d'une application d'entreprise. Une même classe Java peut ainsi être
intégrée dans l'application cliente, à un niveau intermédiaire ou dans la base
de données, c'est-à-dire à l'emplacement le plus approprié.
Une classe contenant des règles de gestion, des données ou une combinaison
des deux peut être déplacée vers n'importe quel niveau du système
d'entreprise, y compris le serveur ; cette flexibilité permet une utilisation
optimale des ressources. Ainsi, les clients de l'entreprise peuvent développer
leurs applications à l'aide d'un langage de programmation unique, dans une
architecture multiniveaux et en bénéficiant d'une flexibilité incomparable.

Création d'applications distribuées
Chapitre 3 Présentation de Java dans la base de données
Vous pouvez créer une application dont certains éléments fonctionnent dans
la base de données et certains autres sur la machine cliente. Vous pouvez
transférer des objets Java du serveur vers le client, tout comme vous
transférez des données SQL telles que des chaînes de caractères et des
valeurs numériques.
$ Pour plus d'informations, reportez-vous à la section "Création
d'applications distribuées", page 171.
Opérations impossibles avec Java dans la base de données
Adaptive Server Anywhere est un environnement d'exécution des classes
Java, pas un environnement de développement Java.
Vous ne pouvez donc pas exécuter les tâches suivantes dans la base de
données :
♦ Editer des fichiers source de classes (fichiers *.java).
♦ Compiler des fichiers source de classes (fichiers *.java).
♦ Exécuter des API Java non supportées, telles que des classes visuelles et
d'applet.
♦ Exécuter des méthodes Java qui requièrent l'exécution de méthodes
natives. Toutes les classes installées dans la base de données doivent être
Java à 100 %.
Les classes Java utilisées dans Adaptive Server Anywhere doivent être
écrites et compilées à l'aide d'un outil de développement d'applications Java,
puis installées dans une base de données, pour y être utilisées, testées ou
déboguées.
61

Séminaire Java
Séminaire Java
Les classes Java
Exemple
62
Cette section présente les concepts fondamentaux de Java. A l'issue de cette
section, vous serez capable d'examiner du code Java, par exemple une simple
définition de classe ou l'appel d'une méthode, et de comprendre parfaitement
de quoi il s'agit.
Répertoire d'exemples Java
Certaines classes présentées comme exemples dans ce document se
trouvent dans le répertoire d'exemples Java Samples\ASA|Java du
répertoire d'installation de SQL Anywhere.
Chaque exemple de classe Java est constitué de deux fichiers : la source
Java et la classe compilée. Vous pouvez immédiatement installer dans une
base de données la version compilée des exemples de classe Java, sans
aucune modification préalable.
Une classe Java combine des données et des fonctionnalités, à savoir qu'elle
contient des informations et peut exécuter des calculs. Pour bien appréhender
le concept de classe, concevez-la comme une entité, une représentation
abstraite de choses.
Par exemple, vous pouvez créer une classe Invoice qui reproduit les factures
papier utilisées tous les jours dans le commerce. Tout comme une facture
papier comprend certaines informations (détail des articles, débiteur, date
d'émission, montant dû et échéance), une instance de la classe Invoice peut
contenir ces mêmes informations. Les classes stockent les informations dans
des champs.
Outre la description des données, une classe peut effectuer des calculs et des
opérations logiques. Par exemple, vous pouvez faire en sorte que la classe
Invoice calcule le montant de la taxe due sur les articles et l'ajoute au soustotal
pour donner un total final, sans intervention de l'utilisateur. Une telle
classe pourrait même contrôler que la facture finale comprend bien toutes les
informations essentielles, ou encore indiquer le dépassement de l'échéance
ou les règlements partiels. Les calculs et autres opérations logiques sont
réalisés par les méthodes de la classe.
Le code Java ci-dessous déclare une classe nommée Invoice. Cette
déclaration, qui est stockée dans un fichier nommé Invoice.java, peut ensuite
être compilée en classe Java à l'aide d'un compilateur Java.

Sous-classes Java
Les objets Java
Chapitre 3 Présentation de Java dans la base de données
Compilation des classes Java
La compilation d'une source de classe Java crée un nouveau fichier
portant le même nom mais avec une autre extension. Ainsi, la compilation
d'Invoice.java crée un fichier nommé Invoice.class qui peut alors être
utilisé dans une application Java et exécuté par une machine virtuelle
Java.
L'outil Sun JDK pour la compilation des déclarations de classes est
javac.exe.
public class Invoice {
// Pour l’heure, cette classe ne sait rien et
..// n'exécute rien
}
Le mot-clé class est suivi du nom de la classe. La syntaxe comprend une
accolade ouverte et une accolade fermée. Tous les éléments déclarés entre les
accolades (champs ou méthodes) font partie de la classe.
En fait, le code Java est uniquement constitué de déclarations de classes.
Même la procédure Java qu'un interpréteur Java exécute automatiquement
pour créer et gérer d'autres objets (la méthode main qui marque souvent le
début de votre application) est également placée au sein d'une déclaration de
classe.
Vous pouvez définir des sous-classes d'autres classes. Une classe qui est une
sous-classe d'une autre classe peut utiliser les champs et les méthodes de la
classe parent : on parle alors d'héritage. Vous pouvez définir des champs et
des méthodes supplémentaires qui s'appliquent uniquement à la sous-classe
et redéfinir la signification des champs et méthodes hérités.
Java est un langage à hiérarchie unique, ce qui signifie que toutes les classes
créées ou utilisées héritent au final d'une seule classe. Ainsi, les classes de
niveau inférieur (situées plus haut dans la hiérarchie) doivent être présentes
avant que les classes de niveau supérieur puissent être utilisées. Le jeu de
classes de base requis pour exécuter des applications Java s'appelle l'API
Java ou classes d'exécution Java.
Une classe est un modèle qui définit les capacités d'un objet, tout comme le
formulaire de facture indique les informations à mentionner.
63

Séminaire Java
Méthodes et
champs
Constructeurs de classe
64
Les classes ne contiennent pas d'informations spécifiques sur les objets. En
réalité, votre application crée, ou instancie, des objets, en s'appuyant sur la
classe (modèle) et ce sont ces objets qui contiennent les données ou
exécutent des calculs. L'objet instancié est appelé instance de la classe.
Ainsi, un objet Invoice est une instance de la classe Invoice. La classe définit
les capacités de l'objet, mais l'objet est l'expression de la classe, qui confère à
cette dernière sa signification et son utilité.
Dans l'exemple de la facture, le formulaire définit le cadre d'action de toutes
les factures basées sur ce modèle. Il existe un seul formulaire, mais un
nombre indéfini de factures possibles. Le formulaire impose une définition,
mais ce sont les factures qui la concrétisent.
De la même manière, c'est l'objet Invoice qui est créé, qui stocke des
informations, puis qui est lui-même stocké, extrait, modifié, mis à jour, etc.
Tout comme vous pouvez créer de nombreuses factures différentes à partir
d'un même modèle, vous pouvez générer de nombreux objets distincts à
partir d'une même classe.
Une méthode correspond à la partie d'une classe qui produit une action (une
fonction qui exécute un calcul ou interagit avec d'autres objets) pour le
compte de la classe. Les méthodes acceptent les arguments et peuvent
renvoyer une valeur à la fonction d'appel. Si aucune valeur renvoyée n'est
nécessaire, une méthode peut renvoyer void. Les classes peuvent comprendre
un nombre illimité de méthodes.
Un champ est la partie de la classe qui contient les informations. Lorsque
vous créez un objet de type classe_Java, ses champs contiennent les valeurs
uniques de cet objet.
Vous créez un objet en appelant un constructeur de classe. Un constructeur
est une méthode qui présente les propriétés suivantes :
♦ Une méthode constructeur possède le même nom que la classe mais pas
de type de données déclarées. Par exemple, un constructeur simple pour
la classe Product serait déclaré comme suit :
Product () {
...code constructeur ici...
}
♦ Si vous ne spécifiez aucune méthode constructeur dans votre définition
de classe, une méthode par défaut fournie par l'objet de base Java est
utilisée.

Les champs
Exemples
Les méthodes
Chapitre 3 Présentation de Java dans la base de données
♦ Vous pouvez spécifier plusieurs constructeurs pour chaque classe, avec
différents nombres et types d'arguments. Lorsqu'un constructeur est
appelé, le constructeur qui porte le nombre et le type d'arguments
appropriés est utilisé.
Il existe deux catégories de champs Java :
♦ Champs d’instance Chaque objet possède son propre jeu de champs
d'instance, créés au même moment que l'objet. Ces champs contiennent
des informations spécifiques sur cette instance. Par exemple, le champ
lineItem1Description de la classe Invoice contient la description d'un
article dans une facture particulière. Vous ne pouvez accéder aux
champs d'instance que par une référence à un objet.
♦ Champs de classe Un champ de classe contient des informations
indépendantes des instances. Un champ de classe est créé lors du
chargement initial de la classe et aucune autre instance n'est créée, quel
que soit le nombre d'objets qui le seront. Vous accédez aux champs de
classe par le nom de la classe ou par une référence à l'objet.
Pour déclarer un champ dans une classe, indiquez son type, puis son nom
suivi d'un point-virgule (;). Pour déclarer un champ de classe, utilisez le motclé
Java static dans la déclaration. Vous déclarez les champs dans le corps de
la classe et non dans une méthode ; une variable déclarée dans une méthode
devient partie intégrante de la méthode, non de la classe.
La déclaration ci-après de la classe Invoice comporte quatre champs qui
correspondent à des informations relatives à deux articles pris en compte
dans une facture.
public class Invoice {
// Les champs d'une facture contiennent les données
de la facture
public String lineItem1Description;
public int lineItem1Cost;
}
public String lineItem2Description;
public int lineItem2Cost;
Il existe deux catégories de méthodes Java :
65

Séminaire Java
66
♦ Méthodes d'instance Une méthode totalSum de la classe Invoice, qui
calculerait et ajouterait le montant de la taxe, puis renverrait le total de
tous les coûts, ne se révélerait utile que si elle était appelée en même
temps qu'un objet Invoice qui additionnerait le prix des différents
articles. En effet, le calcul ne peut être exécuté que sur un objet puisque
c'est l'objet qui contient les lignes de coût relatives aux articles, et non la
classe.
♦ Méthodes de classe Ces méthodes (ou méthodes statiques) peuvent
être appelées sans création préalable d'objet. Seuls les noms de la classe
et de la méthode sont nécessaires pour appeler une méthode de classe.
Tout comme les méthodes d'instance, les méthodes de classe acceptent
les arguments et renvoient des valeurs. En règle générale, les méthodes
de classe exécutent une fonction d'utilitaire ou d'information liée à la
fonctionnalité globale de la classe.
Les méthodes de classe n'ont pas accès aux champs d'instance.
Pour déclarer une méthode, indiquez le type de valeur qu'elle renvoie, son
nom et les paramètres qu'elle accepte. Comme pour la déclaration de classe,
le corps de la méthode (qui contient le code) est placé entre accolades.
public class Invoice {
}
// Champs
public String lineItem1Description;
public double lineItem1Cost;
public String lineItem2Description;
public double lineItem2Cost;
// Une méthode
public double totalSum() {
double runningsum;
}
runningsum = lineItem1Cost + lineItem2Cost;
runningsum = runningsum * 1.15;
return runningsum;
Une variable nommée runningsum est déclarée dans le corps de la méthode
totalSum. Elle a pour fonction de contenir la somme du premier et du
second élément de coût. Ce sous-total est ensuite multiplié par 15 % (le taux
de la taxe) pour donner le total.

Exemple
Exemple
Chapitre 3 Présentation de Java dans la base de données
La variable locale (telle qu'elle est appelée dans le corps de la méthode) est
ensuite renvoyée à la fonction d'appel. Lorsqu'elle est appelée, la méthode
totalSum renvoie la somme des deux champs d'articles, augmentée du
montant de la taxe due sur ces articles.
La méthode parseInt de la classe java.lang.Integer (fournie avec Adaptive
Server Anywhere) est un exemple de méthode de classe. Lorsque vous lui
soumettez une chaîne en argument, la méthode parseInt renvoie la version
de la chaîne en nombres entiers.
Par exemple, pour la valeur de chaîne "1", la méthode parseInt renvoie 1 (la
valeur en nombres entiers) sans créer au préalable d'instance de la classe
java.lang.Integer, comme l'indique l'extrait de code Java ci-dessous.
String num = "1";
int i = java.lang.Integer.parseInt( num );
La version suivante de la classe Invoice comprend une méthode d'instance et
une méthode de classe. La méthode de classe nommée rateOfTaxation
renvoie le taux appliqué par la classe pour calculer le total de la facture.
Faire de la méthode rateOfTaxation une méthode de classe (plutôt qu'un
champ ou une méthode d'instance) présente un avantage puisque les autres
classes et procédures peuvent ensuite utiliser les valeurs qu'elle renvoie sans
avoir à créer au préalable une instance de la classe. Seuls les noms de la
classe et de la méthode sont nécessaires pour renvoyer le taux appliqué par
cette classe.
Le fait de définir rateofTaxation comme méthode à la place d'un champ
permet au développeur d'applications de modifier le mode de calcul du taux
sans que cela ait d'incidence sur les objets, applications ou procédures qui
utilisent ses valeurs de retour. Dans les versions d'Invoice que nous verrons
par la suite, la valeur renvoyée par la méthode de classe rateOfTaxation
sera basée sur un calcul bien plus compliqué sans incidence sur les autres
méthodes utilisant cette valeur.
public class Invoice {
// Champs
public String lineItem1Description;
public double lineItem1Cost;
public String lineItem2Description;
public double lineItem2Cost;
67

Séminaire Java
68
}
// Méthode d'instance
public double totalSum() {
double runningsum;
double taxfactor = 1 + Invoice.rateOfTaxation();
runningsum = lineItem1Cost + lineItem2Cost;
runningsum = runningsum * taxfactor;
return runningsum;
}
// Méthode de classe
public static double rateOfTaxation() {
double rate;
rate = .15;
}
return rate;
Langages orientés objet et procéduraux
Java est basé sur
les classes
Si vous êtes plus habitué aux langages procéduraux, tels que C ou les
procédures stockées SQL, qu'aux langages orientés objet, vous trouverez
dans cette section une présentation des similitudes et différences
fondamentales entre ces deux types de langages.
Dans Java, la classe est la principale unité structurelle du code.
Une classe Java peut être comparée à un regroupement de procédures et de
variables car elles se rapportent toutes à une catégorie spécifique identifiable.
Toutefois, c'est le mode d'utilisation des classes qui distingue les langages
orientés objet des langages procéduraux. Lors de son exécution, une
application écrite dans un langage procédural est généralement chargée une
fois dans la mémoire, puis elle soumet un mode prédéfini d'exécution à
l'utilisateur.
Dans les langages orientés objet tels que Java, une classe est utilisée comme
un modèle : une définition de l'exécution potentielle du programme.
Plusieurs copies d'une classe peuvent être créées et chargées
dynamiquement, selon les besoins, chaque instance de la classe pouvant
contenir ses propres données, valeurs et mode d'exécution. Vous pouvez
exécuter ou agir sur chaque classe chargée, indépendamment des autres
classes en mémoire.

Glossaire Java
Packages
Public et privé
Constructeurs
Chapitre 3 Présentation de Java dans la base de données
Une classe chargée en mémoire pour être exécutée est dite instanciée. Cette
classe instanciée est alors appelée un objet. Il s'agit d'une application dérivée
d'une classe et spécifiquement configurée, de sorte qu'elle comporte des
valeurs uniques ou que ses méthodes sont exécutées indépendamment des
autres instances de la classe.
Les définitions proposées ici soulignent certains aspects des classes Java.
Elles ne visent en aucun cas à proposer une source complète de
connaissances sur le langage Java, mais elles peuvent être de quelque utilité
dans l'utilisation des classes Java dans Adaptive Server Anywhere.
$ Pour plus d'informations sur le langage Java, reportez-vous à la
documentation en ligne Thinking in Java, de Bruce Eckel, qui est fourni avec
Adaptive Server Anywhere dans le fichier Samples\ASA\Java\Tjava.pdf.
Un package est un groupe de classes qui ont une catégorie ou un rôle
communs. Un membre d'un package dispose de privilèges lui permettant
d'accéder aux méthodes et données d'autres membres du package, d'où la
nécessité du modificateur d'accès protected.
Un package est l'équivalent Java d'une bibliothèque. Il s'agit d'un ensemble
de classes accessibles via l'instruction import. L'instruction Java suivante
importe la bibliothèque d'utilitaires de l'API Java.
import java.util.*
D'ordinaire, les packages sont contenus dans des fichiers JAR, qui ont
l'extension .jar ou .zip.
Un modificateur d'accès détermine la visibilité (mot-clé public, private ou
protected précédant toute déclaration) d'un champ, d'une méthode ou d'une
classe pour les autres objets Java.
♦ Une classe, une méthode ou un champ public est visible partout.
♦ Une classe, une méthode ou un champ private n'est visible que dans les
méthodes définies au sein de cette classe.
♦ Une méthode ou un champ protected est visible pour les méthodes
définies au sein de cette classe, dans les sous-classes de la classe ou dans
d'autres classes du même package.
♦ La visibilité par défaut, ou package, signifie que la méthode ou le champ
est visible dans la classe ou par d'autres classes du même package.
Un constructeur est une méthode spéciale d'une classe Java qui est appelée
lorsqu'une instance de la classe est créée.
69

Séminaire Java
Défragmentation
de la mémoire
Interfaces
Traitement des erreurs dans Java
70
Les classes peuvent définir leurs propres constructeurs, y compris des
constructeurs multiples et prioritaires. Ce sont les arguments utilisés dans la
tentative de création d'un objet qui déterminent quel constructeur est
employé. En effet, lorsque le type, le nombre et l'ordre des arguments utilisés
pour créer une instance de la classe correspondent à l'un des constructeurs de
la classe, c'est celui-ci qui est retenu pour créer l'objet.
Une défragmentation de la mémoire supprime automatiquement tout objet
auquel ne mène aucune référence, à l'exception des objets stockés en tant que
valeurs dans une table.
Il n'existe pas de méthode destructeur dans Java (comme c'est le cas dans
C++). Les classes Java peuvent définir leur propre méthode finalize pour les
opérations d'élimination lorsqu'un objet est supprimé durant une
défragmentation de la mémoire.
Les classes Java ne peuvent hériter que d'une seule autre classe. Java fait
appel à des interfaces plutôt qu'à l'héritage multiple. Une classe peut mettre
en oeuvre plusieurs interfaces, chacune définissant un ensemble de
méthodes et de profils de méthodes qui doivent être mis en oeuvre par la
classe pour que celle-ci puisse être compilée.
Une interface définit les méthodes et champs statiques que la classe doit
déclarer. La mise en oeuvre des méthodes et champs déclarés dans une
interface s'opère au sein de la classe qui utilise l'interface. L'interface définit
ce que la classe doit déclarer, mais c'est la classe qui détermine le mode de
mise en oeuvre.
Le code de traitement des erreurs de Java est distinct du code de traitement
normal.
Les erreurs génèrent un objet Exception représentant l'erreur. C'est ce qu'on
appelle déclencher une exception. Toute exception déclenchée met fin au
programme Java, à moins qu'elle ne soit détectée et gérée de la manière
voulue à un certain niveau de l'application.
Les classes de l'API Java, comme les classes créées par l'utilisateur, peuvent
déclencher des exceptions. En fait, les utilisateurs peuvent créer leurs propres
classes d'exception, qui sont ensuite déclenchées par leurs classes
personnalisées.
En l'absence de routine de gestion des exceptions dans le corps de la
méthode où survient l'exception, la recherche d'une routine se poursuit
jusqu'à la pile d'appels. Si la recherche atteint le sommet de la pile d'appels
sans avoir trouvé de routine, c'est la routine par défaut de l'interpréteur Java
exécutant l'application qui est appelée, et le programme est interrompu.

Types d’erreur
dans Java
Chapitre 3 Présentation de Java dans la base de données
Dans Adaptive Server Anywhere, si une instruction SQL appelle une
méthode Java et qu'une exception non gérée est déclenchée, alors une erreur
SQL est générée.
Toutes les erreurs survenant dans Java sont dérivées de deux types de classes
d'erreur : Exception et Error. En règle générale, les erreurs de type
Exception sont gérées par le code de gestion des erreurs dans le corps de la
méthode. Les erreurs de type Error concernent les erreurs internes et les
erreurs d'épuisement des ressources survenant dans le système d'exécution de
Java.
Les erreurs de la classe Exception sont déclenchées et détectées. Le code de
gestion des exceptions se caractérise par des blocs de code try, catch et
finally.
Un bloc try exécute du code susceptible de générer une erreur. Un bloc
catch est un code qui est exécuté si une erreur est générée pendant
l'exécution d'un bloc try.
Un bloc finally définit un bloc de code qui est exécuté, qu'une erreur soit
générée et détectée ou non. Il est généralement utilisé pour les opérations
d'élimination et pour le code qui ne peut en aucun cas être omis.
Les erreurs de la classe Exception sont de deux types : les exceptions
d'exécution et les autres.
Les erreurs générées par le système d'exécution sont des exceptions
implicites dans le sens où il n'est pas nécessaire de les gérer explicitement en
tant qu'élément de chaque déclaration de classe ou de méthode.
Par exemple, une exception de table hors limites peut survenir dès lors que
vous utilisez une table, mais il n'est pas nécessaire que l'erreur figure dans la
déclaration de la classe ou de la méthode qui utilise la table.
Toutes les autres exceptions sont explicites. Si la méthode appelée peut
déclencher une erreur, celle-ci doit être explicitement détectée par la classe
utilisant la méthode de déclenchement d'exceptions, ou bien cette classe doit
explicitement déclencher l'erreur elle-même en identifiant, dans sa
déclaration de classe, l'exception qu'elle est susceptible de générer. D'une
façon générale, les exceptions explicites doivent être explicitement gérées.
Une méthode doit déclarer toutes les erreurs explicites qu'elle déclenche, ou
bien détecter toutes les erreurs explicites susceptibles d'être déclenchées.
Les exceptions qui ne relèvent pas de l'exécution sont contrôlées au moment
de la compilation. Le plus souvent, les exceptions d'exécution sont
provoquées par des erreurs de programmation. Java détecte bon nombre de
ces erreurs lors de la compilation, avant que le code ne soit exécuté.
71

Séminaire Java
72
Chaque méthode Java dispose d'une voie d'exécution de substitution, de sorte
que toutes les méthodes Java sont intégralement exécutées, même si ce n'est
pas toujours de la manière normale. Si le type d'erreur déclenché n'est pas
détecté, il est passé à la méthode ou au bloc de code suivant dans la pile.

Chapitre 3 Présentation de Java dans la base de données
Environnement d'exécution pour Java dans la
base de données
Cette section décrit l'environnement d'exécution Sybase pour Java, ainsi que
ce qui le distingue d'un environnement d'exécution Java standard.
Versions de Java et JDBC supportées
Classes d'exécution Java
La machine virtuelle Sybase Java vous offre le choix entre les interfaces de
programmation JDK 1.1, JDK 1.2 et JDK 1.3. Les versions spécifiques
fournies sont JDK 1.1.8 et 1.3.
Entre les versions 1.0 et 1.1 du JDK, plusieurs nouvelles API ont été
introduites. Par ailleurs, certaines sont désormais déconseillées et pourraient
même ne plus être supportées dans les futures versions.
Un fichier de classe Java qui utilise l'une de ces API génère un avertissement
lorsqu'il est compilé, mais il est néanmoins exécuté sur une machine virtuelle
Java répondant aux standards de la version 1.1, comme par exemple la
machine virtuelle Sybase.
Le pilote JDBC interne supporte la version 2 de JDBC.
$ Pour plus d'informations sur les API JDK supportées, reportez-vous à la
section "Packages Java supportés", page 83 du document ASA Manuel de
référence SQL.
$ Pour plus d'informations sur la création d'une base de données
supportant Java, reportez-vous à la section "Configuration de la base de
données pour Java", page 95.
Les classes d'exécution Java sont les classes de niveau inférieur qui sont
installées pour une base de données au moment de sa création ou de sa
configuration pour Java. Ces classes comprennent un sous-ensemble de l'API
Java. Elles font partie du JDK (Java Development Kit) de Sun.
Les classes d'exécution offrent une fonctionnalité de base à partir de laquelle
des applications peuvent être créées. Elles sont toujours disponibles pour les
classes de la base de données.
Vous pouvez incorporer les classes d'exécution Java dans des classes créées
par l'utilisateur. Elles peuvent soit hériter leur fonctionnalité soit l'utiliser au
sein d'un calcul ou d'une opération dans une méthode.
73

Environnement d'exécution pour Java dans la base de données
Exemples
Classes définies par l'utilisateur
74
Voici certaines classes d'API Java fournies avec les classes d'exécution Java :
♦ Les types de données Java primitifs Tous les types de données
primitifs (natifs) en Java ont une classe correspondante. Permettant non
seulement de créer des objets de ces types, ces classes offrent également
une plus grande fonctionnalité, qui se révèle souvent utile.
Le type de données Java int a une classe correspondante :
java.lang.Integer.
♦ Le package utility Le package java.util.* contient un certain nombre de
classes très utiles, dont la fonctionnalité n'a pas d'équivalent dans les
fonctions SQL disponibles dans Adaptive Server Anywhere.
Voici quelques-unes de ces classes :
♦ Hashtable met en correspondance clés et valeurs.
♦ StringTokenizer décompose une chaîne en mots.
♦ Vector contient une table d'objets dimensionnable dynamiquement.
♦ Stack comprend une pile d'objets de type dernier entré, premier
sorti (LIFO).
♦ JDBC pour opérations SQL Le package java.SQL.* contient les
classes dont les objets Java ont besoin pour extraire des données de la
base à l'aide d'instructions SQL.
Contrairement aux classes définies par l'utilisateur, les classes d'exécution ne
sont pas stockées dans la base de données. Elles sont stockées dans des
fichiers du sous-répertoire java, se trouvant lui-même dans le répertoire
d'installation d'Adaptive Server Anywhere.
Les classes définies par l'utilisateur sont installées dans une base de données
à l'aide de l'instruction INSTALL. Une fois installées, elles sont utilisables
par d'autres classes de la base de données. Si elles sont publiques, elles sont
accessibles à partir de SQL en tant que domaines.
$ Pour plus d'informations sur l'installation de classes, reportez-vous à la
section "Installation de classes Java dans une base de données", page 101.
Identification des méthodes et champs Java
Le point dans SQL
Dans les instructions SQL, le point (.) identifie les colonnes des tables,
comme dans la requête suivante :

Le point dans Java
Appel de méthodes
Java depuis SQL
Chapitre 3 Présentation de Java dans la base de données
SELECT employee.emp_id
FROM employee
Le point indique également l'appartenance des objets dans les noms d'objets
qualifiés :
SELECT emp_id
FROM DBA.employee
Dans Java, le point sert d'opérateur pour appeler les méthodes ou accéder
aux champs d'une classe ou d'un objet Java. Il sert aussi d'identificateur des
noms de classes, comme dans le nom de classe intégralement qualifié
java.util.Hashtable.
Dans l'extrait de code Java ci-après, le point est utilisé comme élément d'un
identificateur sur la première ligne de code. Sur la seconde ligne, il sert
d'opérateur.
java.util.Random rnd = new java.util.Random();
int i = rnd.nextInt();
Dans SQL, l'opérateur point peut être remplacé par le double chevron (>>).
L'opérateur point convient plus à Java mais peut donner lieu à des ambiguïtés
sur les noms SQL existants. Le double chevron (>>) est moins ambigu.
>> dans SQL est différent de >> dans Java
Dans les instructions SQL, l'opérateur double chevron convient ; seul
l'opérateur point est utilisé dans Java. Dans une classe Java, le double
chevron n'est pas un substitut de l'opérateur point et son rôle de décalage
du bit de droite a une signification totalement différente.
Par exemple, le batch suivant d'instructions SQL est valide :
CREATE VARIABLE rnd java.util.Random;
SET rnd = NEW java.util.Random();
SELECT rnd>>nextInt();
Le résultat de l'instruction SELECT est un entier généré de manière aléatoire.
Sur la base de la variable créée dans l'exemple de code SQL précédent,
l'instruction SQL suivante présente l'utilisation correcte d'une méthode de
classe :
SELECT java.lang.Math>>abs( rnd>>nextInt() );
75

Environnement d'exécution pour Java dans la base de données
Java fait la distinction majuscules/minuscules
Types de données
Chaînes en Java et SQL
76
La syntaxe Java fonctionne précisément de la manière escomptée et la
syntaxe SQL n'est en rien altérée par la présence de classes Java. Cela est
vrai, même si une instruction SQL contient les deux syntaxes, SQL et Java.
Pour anodine qu'elle paraisse, cette information n'en a pas moins
d'importantes implications.
Java fait la distinction majuscules/minuscules. Ainsi, la classe Java FindOut
est totalement différente de la classe Findout. SQL ne fait pas la distinction
majuscules/minuscules en ce qui concerne les mots-clés et les identificateurs.
Cette distinction majuscules/minuscules que fait Java est préservée même
lorsque Java est imbriqué dans une instruction SQL qui, elle, ne la fait pas.
Les parties Java de l'instruction doivent donc respecter la distinction
majuscules/minuscules, tandis que les autres parties peuvent être écrites
indifféremment en majuscules ou en minuscules.
Par exemple, l'instruction SQL suivante est exécutée normalement puisque la
casse des objets, classes et opérateurs Java est respectée, alors même que la
casse du reste de l'instruction varie.
SeLeCt java.lang.Math.random();
Une classe Java employée comme type de données d'une colonne est utilisée
comme un type de données SQL défini par l'utilisateur. Cela étant, elle fait
quand même la distinction majuscules/minuscules. Cette convention évite
toute confusion entre les classes Java distinguées par la casse uniquement.
Dans Java, les littéraux de chaîne sont identifiés par des guillemets doubles,
comme dans l'extrait de code suivant :
String str = "Ceci est une chaîne";
En revanche, dans SQL, les chaînes sont marquées par des guillemets
simples (les guillemets doubles indiquant un identificateur), comme dans
l'instruction SQL suivante :
INSERT INTO TABLE DBA.t1
VALUES( ’Bonjour’ )
Utilisez toujours des guillemets doubles dans le code source Java et des
guillemets simples dans les instructions SQL.
Par exemple, les instructions SQL suivantes sont valides :
CREATE VARIABLE str char(20);
set str = new java.lang.String( ’Nouvel objet’ )

Chapitre 3 Présentation de Java dans la base de données
Et l'extrait de code Java suivant est valide également, s'il est utilisé dans une
classe Java :
String str = new java.lang.String(
"Nouvel objet" );
Impression dans la ligne de commande
Utilisation de la méthode main
L'impression dans la sortie standard permet de contrôler rapidement les
valeurs des variables et les résultats d'exécution à différents points
d'exécution du code. Lorsque la méthode sur la seconde ligne de l'extrait
suivant de code Java arrive à exécution, l'argument de chaîne qu'elle accepte
est imprimé dans la sortie standard :
String str = "Bonjour à tous";
System.out.println( str );
Dans Adaptive Server Anywhere, la sortie standard se fait dans la fenêtre du
serveur. L'exécution dans la base de données du code Java ci-dessus produit
le même résultat que l'instruction SQL suivante :
MESSAGE 'Bonjour à tous'
Lorsqu'une classe contient une méthode main correspondant à la déclaration
de méthode suivante, elle est automatiquement exécutée par la plupart des
environnements d'exécution Java, notamment l'interpréteur Java Sun.
Normalement, cette méthode statique est exécutée uniquement si la classe est
appelée par l'interpréteur Java.
public static void main( String args[ ] ) { }
Cette classe est utile pour tester la fonctionnalité des objets Java ; vous êtes
ainsi assuré que cette méthode sera la première appelée lors du démarrage du
système d'exécution Java de Sun.
Dans Adaptive Server Anywhere, le système d'exécution Java reste toujours
accessible. La fonctionnalité des objets et méthodes peut néanmoins être
testée d'une manière dynamique et adaptée à l'aide d'instructions SQL. A
bien des égards, cette méthode se révèle d'ailleurs beaucoup plus flexible.
77

Environnement d'exécution pour Java dans la base de données
Portée et durée
78
Les variables SQL ne durent que le temps de la connexion. Cette
caractéristique, déjà présente dans les versions précédentes d'Adaptive Server
Anywhere, reste vraie, que la variable soit une classe Java ou un type de
données SQL natif.
La durée des classes Java est analogue à celle des tables d'une base de
données. Dans une base de données, les tables existent jusqu'à leur
suppression, qu'elles contiennent des données ou non ou que les données
aient été utilisées ou non. Les classes Java installées dans une base de
données fonctionnent de la même manière : elles sont disponibles tant
qu'elles n'ont pas été explicitement supprimées avec une instruction
REMOVE.
$ Pour plus d'informations sur la suppression de classes, reportez-vous à
la section "Instruction REMOVE", page 532 du document ASA Manuel de
référence SQL.
Une méthode de classe installée dans une classe Java peut être appelée à tout
moment, à l'aide d'une instruction SQL. L'instruction suivante peut être
exécutée en n'importe quel point où les instructions SQL sont exécutables :
Select java.lang.Math.abs(-342)
Un objet Java est disponible sous deux formes uniquement : en tant que
valeur d'une variable ou comme valeur d'une table.
Caractères d'échappement Java dans les instructions SQL
En code Java, vous pouvez utiliser des caractères d'échappement pour insérer
certains caractères spéciaux dans des chaînes. L'exemple de code ci-après
insère une nouvelle ligne et une tabulation devant une phrase contenant une
apostrophe.
String str = "\n\t\Ceci est le littéral de chaîne de
l\'objet.";
Les caractères d'échappement Java sont autorisés dans Adaptive Server
Anywhere uniquement lorsqu'ils sont utilisés par les classes Java. En
revanche, dans SQL, les règles applicables aux chaînes SQL doivent être
observées.
Par exemple, pour transmettre une valeur de chaîne à un champ à l'aide d'une
instruction SQL, vous pouvez utiliser l'instruction suivante, mais pas les
caractères d'échappement Java.
set obj.str = '\nCeci est le champ de chaîne de
l''objet';

Conflits de mots-clés
Chapitre 3 Présentation de Java dans la base de données
$ Pour plus d'informations sur les règles de gestion des chaînes SQL,
reportez-vous à la section "Chaînes", page 9 du document ASA Manuel de
référence SQL.
Des conflits peuvent survenir entre les mots-clés SQL et les noms des classes
Java, y compris les classes d'API. C'est le cas lorsque le nom d'une classe,
par exemple la classe Date qui appartient au package java.util.*, est
référencé. En effet, SQL réserve le mot Date pour l'utiliser comme mot-clé,
alors qu'il est également le nom d'une classe Java.
En cas d'ambiguïté, vous pouvez utiliser des guillemets doubles pour
indiquer que le mot en question n'est pas employé comme mot réservé SQL.
Par exemple, l'instruction SQL suivante provoque une erreur car Date est un
mot-clé dont l'usage est réservé dans SQL :
Utilisation des instructions import
-- Cette instruction est incorrecte
CREATE VARIABLE dt java.util.Date
En revanche, les deux instructions ci-après fonctionnent correctement car le
mot Date est mis entre guillemets doubles :
CREATE VARIABLE dt java.util."Date";
SET dt = NEW java.util."Date"(1997, 11, 22, 16, 11, 01)
La variable dt contient maintenant la date : 22 novembre 1997, 16:11.
Dans une déclaration de classe Java, il n'est pas rare d'inclure une instruction
import pour accéder aux classes d'un autre package. Vous pouvez référencer
des classes importées en utilisant des noms de classe non qualifiés.
Par exemple, la classe Stack du package java.util peut être référencée de
deux manières :
♦ soit en utilisant explicitement le nom java.util.Stack ;
♦ soit en utilisant le nom Stack et en ajoutant l'instruction import
suivante :
import java.util.*
79

Environnement d'exécution pour Java dans la base de données
Les classes
situées plus haut
dans la hiérarchie
doivent être
installées.
80
Toute classe référencée par une autre classe, soit explicitement à l'aide d'un
nom intégralement qualifié, soit implicitement via une instruction import,
doit aussi être installée dans la base de données.
L'instruction import fonctionne de la manière voulue dans les classes
compilées. Cependant, dans l'environnement d'exécution Adaptive Server
Anywhere, il n'existe pas d'équivalent à l'instruction import. Tous les noms
de classe utilisés dans les instructions SQL ou les procédures stockées
doivent donc être intégralement qualifiés. Par exemple, pour créer une
variable de type String, la classe est référencée à l'aide du nom intégralement
qualifié : java.lang.String.
Utilisation de la variable CLASSPATH
CLASSPATH
ignorée à
l'exécution
Utilisation de
CLASSPATH pour
installer des
classes
La variable d'environnement CLASSPATH permet à l'environnement
d'exécution Java de Sun et au compilateur Java Sun JDK de localiser les
classes référencées dans le code Java. Une variable CLASSPATH indique le
lien entre le code Java et le chemin d'accès au fichier ou l'URL des classes
référencées. Par exemple, import java.io.* permet de référencer toutes
les classes du package java.io sans nom intégralement qualifié. Pour
exploiter des classes du package java.io, seul le nom de la classe est requis
dans le code Java suivant. La variable d'environnement classpath sur le
système où doit être compilée la déclaration de classe Java doit indiquer
l'emplacement du répertoire Java, racine du package java.io.
La variable d'environnement CLASSPATH n'a pas d'incidence sur
l'environnement d'exécution d'Adaptive Server Anywhere pendant
l'exécution des opérations Java, car les classes sont stockées dans la base de
données et non dans des fichiers ou des archives externes.
La variable classpath permet néanmoins de localiser un fichier pendant
l'installation de classes. Par exemple, l'instruction suivante installe dans une
base de données une classe Java créée par l'utilisateur en spécifiant
uniquement le nom du fichier, sans son chemin. (Vous noterez que cette
instruction ne comporte aucune opération Java.)
INSTALL JAVA NEW
FROM FILE ’Invoice.class’
Si le fichier se trouve dans un répertoire ou un fichier .zip spécifié par la
variable classpath, Adaptive Server Anywhere localise le fichier et installe la
classe.

Champs publics
Chapitre 3 Présentation de Java dans la base de données
Dans la programmation orientée objet, les champs de classe sont
fréquemment définis comme étant privés et leurs valeurs sont accessibles
uniquement via des méthodes publiques.
Bon nombre des exemples de la présente documentation concernent des
champs publics, pour des raisons de concision et de facilité de lecture. En
outre, dans Adaptive Server Anywhere, les champs publics offrent de
meilleures performances que les méthodes publiques d'accès.
Dans cette documentation, une classe Java créée par l'utilisateur pour être
utilisée dans Adaptive Server Anywhere présente, par convention, ses
valeurs principales dans ses champs. Les méthodes, quant à elles,
contiennent des éléments de logique et d'automatisation du calcul
susceptibles d'agir sur ces champs.
81

Didacticiel : Java dans la base de données - Exercice pratique
Didacticiel : Java dans la base de données -
Exercice pratique
Configuration
requise
Ressources
82
Ce didacticiel constitue une initiation en matière d'appel d'opérations Java
sur des classes et des objets Java à l'aide d'instructions SQL. Il explique
comment installer une classe Java dans la base de données. Il explique
également comment accéder à la classe ainsi qu'à ses membres et ses
méthodes à l'aide d'instructions SQL. Ce didacticiel s'appuie sur la classe
Invoice créée dans la section "Séminaire Java", page 62.
Pour suivre ce didacticiel, le logiciel Java dans la base de données doit être
installé. Le JDK (Java Development Kit) doit également être installé, y
compris le compilateur Java (javac).
Le code source et les fichiers batch correspondant à cet exemple se trouvent
dans le sous-répertoire Samples\ASA|InvoiceJava du répertoire
SQL Anywhere.
Création et compilation d'un exemple de classe Java
La première étape consiste à écrire le code Java et à le compiler. Cette
opération est effectuée hors de la base de données.
v Pour créer et compiler la classe :
1 Créez le fichier Invoice.java contenant le code suivant :

Chapitre 3 Présentation de Java dans la base de données
public class Invoice {
}
// Champs
public String lineItem1Description;
public double lineItem1Cost;
public String lineItem2Description;
public double lineItem2Cost;
// Méthode d'instance
public double totalSum() {
double runningsum;
double taxfactor = 1 + Invoice.rateOfTaxation();
}
runningsum = lineItem1Cost + lineItem2Cost;
runningsum = runningsum * taxfactor;
return runningsum;
// Méthode de classe
public static double rateOfTaxation() {
double rate;
rate = .15;
}
return rate;
Le code source de cette classe se trouve dans le fichier
Samples\ASA|JavaInvoice\Invoice.java, accessible dans le répertoire
SQL Anywhere.
2 Compilez le fichier afin de générer le fichier Invoice.class.
A partir d'une invite de commande dans le même répertoire que celui du
fichier Invoice.java, exécutez la commande suivante :
javac *.java
Installation de l’exemple de classe Java
La classe est compilée et peut à présent être installée dans la base de
données.
Vous devez installer les classes Java dans une base de données avant de
pouvoir les utiliser. Vous pouvez installer des classes à partir de
Sybase Central ou d'Interactive SQL. Cette section fournit des instructions
pour les deux modes d'installation. Choisissez la méthode qui vous convient
le mieux.
83

Didacticiel : Java dans la base de données - Exercice pratique
Remarques
84
v Pour installer la classe dans la base de données exemple à partir de
Sybase Central :
1 Démarrez Sybase Central et connectez-vous à la base de données
exemple.
2 Ouvrez le dossier Objets Java et double-cliquez sur Ajouter une classe
Java. L'assistant de création d'une classe Java s'affiche.
3 Cliquez sur Parcourir, puis recherchez Invoice.class dans le sousrépertoire
Samples\ASA\JavaInvoice du répertoire d'installation de
SQL Anywhere.
4 Cliquez sur Terminer pour quitter l'assistant.
v Pour installer la classe dans la base de données exemple à partir
d'Interactive SQL :
1 Démarrez Interactive SQL et connectez-vous à la base de données
exemple.
2 Dans le volet Instructions SQL d'Interactive SQL, entrez la commande
suivante :
INSTALL JAVA NEW
FROM FILE
’chemin\\samples\\ASA\\JavaInvoice\\Invoice.class’
chemin correspondant au répertoire SQL Anywhere.
La classe est à présent installée dans la base de données exemple.
♦ A ce stade, aucune opération Java dans la base de données n'a encore eu
lieu. La classe a été installée dans la base de données et est prête à servir
de type de données pour une variable ou une colonne dans une table.
♦ Les modifications apportées au fichier de la classe à partir de ce moment
ne sont pas automatiquement répercutées dans la copie de la classe dans
la base de données. Vous devez réinstaller les classes pour que les
modifications soient prises en compte.
$ Pour plus d'informations sur l'installation de classes et la mise à jour
d'une classe installée, reportez-vous à la section "Installation de classes Java
dans une base de données", page 101.
Création d'une variable SQL de type Invoice
Cette section explique comment créer une variable SQL qui référence un
objet Java de type Invoice.

Chapitre 3 Présentation de Java dans la base de données
Distinction majuscules/minuscules
Java faisant la distinction majuscules/minuscules, les parties en Java des
exemples donnés ci-après indiquent précisément la casse requise. La
syntaxe SQL est donnée en majuscules.
1 A partir d'Interactive SQL, exécutez l'instruction ci-après pour créer une
variable SQL nommée Inv de type Invoice, Invoice étant la classe Java
que vous avez installée dans la base de données.
CREATE VARIABLE Inv Invoice
Une fois créée, la variable ne peut accepter de valeur que si son type de
données et le type de données déclaré sont identiques ou si la valeur est
une sous-classe du type déclaré. Dans le cas présent, la variable Inv peut
contenir uniquement une référence à un objet de type Invoice ou une
sous-classe d'Invoice.
Initialement, la variable Inv est NULL puisque aucune valeur ne lui a
été transmise.
2 Pour identifier la valeur courante de la variable Inv, exécutez
l'instruction suivante :
select IfNull(Inv,
'Pas de référence à un objet',
'Variable not null : contient une référence à un
objet')
A ce stade, la variable ne comporte aucune référence à un objet.
3 Affectez une valeur à Inv.
Vous devez créer une instance de la classe Invoice à l'aide du mot-clé
NEW.
SET Inv = NEW Invoice();
La variable Inv comporte désormais une référence à un objet Java. Pour
le vérifier, vous pouvez exécuter l'instruction à partir de l'étape 2.
La variable Inv contient une référence à un objet Java de type Invoice.
Avec cette référence, vous pouvez maintenant accéder à tous les champs
de l'objet et appeler ses méthodes.
Accès aux champs et aux méthodes de l'objet Java
Si une variable (ou la valeur d’une colonne dans une table) contient une
référence à un objet Java, des valeurs peuvent être transmises aux champs de
l'objet et ses méthodes peuvent être appelées.
85

Didacticiel : Java dans la base de données - Exercice pratique
Méthodes d'appel
et champs qui
référencent
86
Par exemple, la variable de type Invoice que vous avez créée dans la section
précédente contient une référence à un objet Invoice et comporte quatre
champs dont la valeur peut être définie via des instructions SQL.
v Pour accéder aux champs de l'objet Invoice :
1 A partir d’Interactive SQL, exécutez les instructions SQL ci-après afin
de définir les valeurs des champs de la variable Inv.
SET Inv.lineItem1Description = ’Work boots’;
SET Inv.lineItem1Cost = ’79.99’;
SET Inv.lineItem2Description = ’Hay fork’;
SET Inv.lineItem2Cost = ’37.49’;
Chaque instruction SQL transmet une valeur à un champ dans
l'objet Java référencé par Inv.
2 Exécutez les instructions SELECT sur la variable. Chacune des
instructions SQL suivantes renvoie ainsi la valeur courante d'un champ
de l'objet Java référencé par Inv.
SELECT Inv.lineItem1Description;
SELECT Inv.lineItem1Cost;
SELECT Inv.lineItem2Description;
SELECT Inv.lineItem2Cost;
3 Utilisez un champ de la variable Inv dans une expression SQL.
Exécutez l'instruction SQL suivante et assurez-vous d'avoir exécuté les
instructions SQL mentionnées précédemment.
SELECT * FROM PRODUCT
WHERE unit_price < Inv.lineItem2Cost;
Disposant non seulement de champs publics, la classe Invoice comporte
également une méthode d'instance que vous pouvez appeler.
v Pour appeler les méthodes de l'objet Invoice :
♦ A partir d’Interactive SQL, exécutez l'instruction SQL suivante qui
appelle la méthode totalSum() de l'objet référencé par la variable Inv.
Elle renvoie la somme des deux champs de coût augmentée du montant
de la taxe perçue sur cette somme.
SELECT Inv.totalSum();
Les noms de méthode sont toujours suivis de parenthèses, même s'ils ne
prennent pas d'argument. Les noms de champ ne sont pas suivis de
parenthèses.

Chapitre 3 Présentation de Java dans la base de données
La méthode totalSum() ne prend aucun argument, mais renvoie une valeur.
Les parenthèses sont employées même si la méthode ne prend aucun
argument dans la mesure où une opération Java est appelée.
Pour Java dans la base de données, l'accès direct à un champ est plus rapide
que l'appel d'une méthode. L'accès à un champ ne requiert pas l'appel de la
machine virtuelle Java, alors que l'appel d'une méthode exige que la machine
virtuelle exécute la méthode.
Comme indiqué dans la définition de la classe Invoice donnée au début de
cette section, la méthode d'instance totalSum utilise la méthode de classe
rateOfTaxation.
Cette méthode est accessible directement depuis une instruction SQL.
SELECT Invoice.rateOfTaxation();
Vous noterez que c'est le nom de la classe qui est utilisé et pas le nom d'une
variable contenant une référence à un objet Invoice. Cette approche est
conforme à la manière dont Java gère les méthodes de classe, alors même
qu'il s'agit ici d'une instruction SQL. Une méthode de classe peut être
appelée même si aucun objet basé sur cette classe n'a été instancié.
Ainsi, les méthodes de classe ne nécessitent pas d'instance de la classe pour
opérer correctement, mais elles peuvent néanmoins être appelées sur un
objet. L'instruction SQL suivante produit les mêmes résultats que celle
précédemment exécutée.
SELECT Inv.rateOfTaxation();
Enregistrement d’objets Java dans des tables
Lorsqu'une classe Java est installée dans une base de données, elle est
disponible en tant que nouveau type de données. Les colonnes d'une table
peuvent être du type classe_Java, qui correspond au nom d'une classe Java
publique installée. Vous pouvez ensuite créer un objet Java et l'ajouter à une
table en tant que valeur d'une colonne.
v Pour utiliser la classe Invoice dans une table :
1 Créez une table avec une colonne de type Invoice.
A partir d'Interactive SQL, exécutez l'instruction SQL suivante :
CREATE TABLE T1 (
ID int,
JCol Invoice
);
87

Didacticiel : Java dans la base de données - Exercice pratique
88
La colonne JCol accepte uniquement des objets de type Invoice ou
d’une de ses sous-classes.
2 A l’aide de la variable Inv qui contient une référence à un objet Java de
type Invoice, exécutez l'instruction SQL suivante pour ajouter une ligne
à la table T1.
INSERT INTO T1
VALUES( 1, Inv );
Une fois que vous avez ajouté un objet dans la table T1, vous pouvez
exécuter des instructions select qui appellent les champs et les méthodes
des objets de la table.
3 Par exemple, l'instruction SQL suivante renvoie la valeur du champ
lineItem1Description de tous les objets de la table T1 (à ce stade, la
table ne doit contenir qu'un seul objet).
SELECT ID, JCol.lineItem1Description
FROM T1;
Vous pouvez exécuter des instructions SELECT similaires qui appellent
d'autres champs et méthodes de l'objet.
4 La seconde méthode pour créer un objet Java et l'ajouter à une table fait
appel à l'expression suivante, qui crée automatiquement un objet Java et
renvoie une référence s'y rapportant.
NEW Javaclassname()
5 Cette expression peut être utilisée de plusieurs manières. Par exemple,
exécutez l'instruction SQL suivante pour créer un objet Java et l'insérer
dans la table T1 :
INSERT INTO T1
VALUES ( 2, NEW Invoice() );
6 Exécutez l'instruction SQL suivante pour vérifier que ces deux objets ont
bien été enregistrés en tant que valeurs de la colonne JCol dans la table
T1.
select id, JCol.totalSum()
FROM t1
Le résultat de la colonne JCol (la deuxième ligne renvoyée par
l'instruction ci-dessus) doit être 0, parce que les champs de cet objet
n'ont pas de valeur et que la méthode totalSum opère un calcul
arithmétique sur ces champs.

Renvoi d'un objet à l'aide d'une requête
Chapitre 3 Présentation de Java dans la base de données
Outre l'accès aux champs et aux méthodes, vous pouvez également récupérer
un objet entier d'une table à l'aide d'une requête.
v Pour accéder aux objets Invoice stockés dans une table :
♦ A partir d’Interactive SQL, exécutez la série d'instructions ci-après pour
créer une nouvelle variable et transmettre une valeur (elle ne peut
contenir qu'une référence à un objet de type Invoice). La référence à un
objet transmise à la variable a été générée à l'aide de la table T1.
CREATE VARIABLE Inv2 Invoice;
set Inv2 = (select JCol from T1 where ID = 2);
SET Inv2.lineItem1Description = ’Sweet feed’;
SET Inv2.lineItem2Description = ’Drive belt’;
La valeur des champs lineItem1Description et lineItem2Description a
été modifiée dans la variable Inv2, mais pas dans la table d'où provient
la valeur de cette variable.
Ce fonctionnement est cohérent avec le mode de traitement courant des
variables SQL : la variable Inv comporte une référence à un objet Java.
La valeur indiquée dans la table source de la référence de la variable
n'est modifiée qu'après l'exécution d'une instruction UPDATE.
89

Didacticiel : Java dans la base de données - Exercice pratique
90

CHAPITRE 4
Utilisation de Java dans la base de données
Présentation
Sommaire
Avant de
commencer
Ce chapitre explique comment ajouter des classes et des objets Java à la base
de données, et comment utiliser ces objets dans une base de données
relationnelle.
Sujet Page
Introduction 92
Configuration de la base de données pour Java 95
Installation de classes Java dans une base de données 101
Création de colonnes d'objets Java 106
Insertion, mise à jour et suppression d'objets Java 108
Recherche d'objets Java 114
Comparaison des champs et des objets Java 116
Fonctionnalités spéciales des classes Java dans la base de données 120
Stockage des objets Java 127
Conception d'une base de données Java 130
Utilisation de colonnes calculées avec les classes Java 134
Configuration de la mémoire pour Java 137
Pour utiliser les exemples fournis dans ce chapitre, commencez par exécuter
le fichier Samples\ASA\Java\jdemo.sql du répertoire SQL Anywhere.
$ Pour obtenir plus d'informations et des instructions complètes, reportezvous
aux exemples de la section "Installation des exemples Java", page 92.
91

Introduction
Introduction
Installation des exemples Java
92
Ce chapitre explique comment accomplir des tâches en utilisant Java dans la
base de données, notamment :
♦ Comment configurer une base de données pour Java Vous devez
accomplir plusieurs tâches pour préparer la base de données à
l'utilisation de Java.
♦ Installation de classes Java Vous devez installer des classes Java dans
une base de données pour qu'elles soient disponibles sur le serveur.
♦ Propriétés des colonnes Java Cette section explique comment les
colonnes contenant des types de données de classe Java se placent dans
un modèle relationnel.
♦ Conception d'une base de données Java Cette section donne des
conseils pour créer des bases de données utilisant des classes Java.
La plupart des exemples figurant dans ce chapitre utilise un ensemble de
classes et de tables ajouté dans la base de données exemple. Les tables
présentées contiennent les mêmes informations que celles figurant sous le
même nom dans la base de données exemple mais l'ID utilisateur de leur
propriétaire est jdba. Ces tables utilisent les types de données de classe Java
plutôt que des données relationnelles simples pour gérer les
informations.Vous trouverez l'exemple dans le sous-répertoire
Samples\ASA\Java du répertoire SQL Anywhere.
Les tables exemple ont une vocation didactique uniquement
Les tables exemple servent à illustrer les différentes fonctionnalités Java.
Elles ne doivent pas être considérées comme une méthode à suivre pour
reconcevoir la base de données. Vous devez choisir les types de données
et autres fonctionnalités Java en fonction de votre cas particulier
L'installation des exemples Java s'effectue en deux étapes :
1 Configurez la base de données exemple pour Java.
2 Ajoutez les exemples de classes et de tables Java.

Chapitre 4 Utilisation de Java dans la base de données
v Pour configurer la base de données exemple pour Java :
1 Démarrez Interactive SQL et connectez-vous à la base de données
exemple.
2 Dans le volet Instructions SQL d'Interactive SQL, entrez l'instruction
suivante :
ALTER DATABASE UPGRADE JAVA JDK ’1.3’
3 Arrêtez Interactive SQL et la base de données exemple.
Vous devez arrêter la base de données asademo.db avant de pouvoir
utiliser les fonctionnalités Java.
v Pour ajouter des tables et des classes Java dans la base de
données exemple :
1 Démarrez Interactive SQL et connectez-vous à la base de données
exemple.
2 Dans le volet Instructions SQL d'Interactive SQL, entrez l'instruction
suivante :
READ "chemin\\Samples\\ASA\\Java\\jdemo.sql"
chemin correspondant au répertoire SQL Anywhere. Cette opération
exécute les instructions du fichier de commandes jdemo.sql. Cette
exécution peut prendre un certain temps.
Vous pouvez visualiser le script Samples\ASA\Java\jdemo.sql à l'aide d'un
éditeur de texte. Le script exécute les tâches suivantes :
1 Installation de la classe JDBCExamples.
2 Création de l'ID utilisateur JDBA auquel sont associés le mot de passe
SQL et les droits DBA, et affectation de l'ID JDBA à l'utilisateur courant.
3 Installation du fichier JAR asademo.jar. Ce fichier contient les
définitions de classe utilisées dans les tables.
4 Création, sous l'ID utilisateur JDBA, des tables suivantes :
♦ product
♦ contact
♦ customer
♦ employee
♦ sales_order
♦ sales_order_items
93

Introduction
94
Le tout forme un sous-ensemble des tables de la base de données
exemple.
5 Insertion dans les tables Java des données des tables standard portant le
même nom. Cette étape fait appel aux instructions INSERT à partir de
SELECT. Elle peut prendre un certain temps.
6 Création d'index et de clés étrangères pour ajouter au schéma des
contraintes d'intégrité.
Gestion de l'environnement d'exécution pour Java
Tâches de gestion
pour Java
Outils de gestion
pour Java
L'environnement d'exécution de Java est le suivant :
♦ La machine virtuelle Java (JVM) de Sybase Exécutée sur le serveur de
la base de données, la JVM interprète et exécute les fichiers de classe
Java compilés.
♦ Les classes Java d'exécution Lorsque vous créez une base de
données, un ensemble de classes Java devient disponible pour la base.
Les applications Java dans la base de données ont besoin de ces classes
d'exécution pour fonctionner correctement.
Pour fournir un environnement d'exécution à Java, exécutez les tâches
suivantes :
♦ Configuration de la base de données pour Java Cette tâche consiste à
garantir la disponibilité des classes intégrées et la mise au niveau de la
base de données aux normes de la version 8.
$ Pour plus d'informations, reportez-vous à la section "Configuration
de la base de données pour Java", page 95.
♦ Installation des classes nécessaires aux utilisateurs Cette tâche
consiste à s'assurer que les classes qui ne sont pas des classes
d'exécution sont installées et à jour.
$ Pour plus d'informations, reportez-vous à la section "Installation de
classes Java dans une base de données", page 101.
♦ Configuration du serveur Configurez le serveur de façon à disposer de
suffisamment de mémoire pour exécuter les tâches Java.
$ Pour plus d'informations, reportez-vous à la section "Configuration
de la mémoire pour Java", page 137.
Toutes ces tâches peuvent être exécutées à partir de Sybase Central ou
d'Interactive SQL.

Chapitre 4 Utilisation de Java dans la base de données
Configuration de la base de données pour Java
Contre-indications
L'environnement d'exécution d'Adaptive Server Anywhere pour Java doit
comporter une JVM ainsi que les classes d'exécution Java de Sybase. Vous
devez configurer une base de données pour Java afin de pouvoir utiliser les
classes d'exécution Java.
Java dans la base de données est un composant de SQL Anywhere Studio
faisant l'objet d'une licence séparée.
Les nouvelles bases de données sont par défaut non configurées
pour Java
Lorsque vous créez une base de données avec Adaptive Server Anywhere,
la base n'est, par défaut, pas configurée pour Java.
Java est un langage à hiérarchie unique, ce qui signifie que toutes les classes
créées ou utilisées ne peuvent hériter que d'une classe (et une seule). Ainsi,
les classes de niveau inférieur (situées plus haut dans la hiérarchie) doivent
être présentes pour que les classes de niveau supérieur puissent être utilisées.
Le jeu de classes de base requis pour exécuter des applications Java s'appelle
API Java ou classes d'exécution Java.
La configuration d'une base de données pour Java crée de nombreuses
entrées supplémentaires dans les tables système. Par conséquent, la base de
données occupe davantage d'espace et son exécution requiert environ 200 ko
de mémoire supplémentaire, même si vous n'utilisez pas les fonctionnalités
Java.
Si vous n'envisagez pas d'utiliser Java prochainement et que votre
environnement d'exécution est limité en mémoire, il est préférable de ne pas
effectuer la configuration pour Java.
Les classes d'exécution Java de Sybase
Les classes d'exécution Java de Sybase sont stockées sur le disque et non
dans la base de données, comme les autres classes. Les classes d'exécution
Java de Sybase sont stockées dans les suivants fichiers. Ces fichiers se
trouvent dans le sous-répertoire Java du répertoire SQL Anywhere :
♦ 1.1\classes.zip Sous licence Sun Microsystems, ce fichier contient un
sous-ensemble des classes d'exécution Java de Sun Microsystem pour
JDK 1.1.8.
95

Configuration de la base de données pour Java
Les fichiers JAR
Packages installés
96
♦ 1.3\rt.jar Sous licence Sun Microsystems, ce fichier contient un sousensemble
des classes d'exécution Java de Sun Microsystems pour
JDK 1.3.
♦ asajdbc.zip Ce fichier contient les classes du gestionnaire JDBC interne
de Sybase pour JDK 1.1.
♦ asajrt12.zip Ce fichier contient les classes du gestionnaire JDBC interne
de Sybase pour JDK 1.2 et JDK 1.3.
Lorsque vous configurez une base de données pour Java, vous mettez aussi à
jour les tables système avec la liste des classes disponibles dans les fichiers
système JAR. Cela vous permet de parcourir la hiérarchie des classes depuis
Sybase Central bien que les classes ne se trouvent pas dans la base de
données.
Les noms des classes d'exécution sont enregistrés dans la base de données,
dans les fichiers JAR suivants :
♦ ASAJRT Les noms des classes issus du fichier asajdbc.zip sont stockés
ici.
♦ ASAJDBCDRV Les noms des classes issus du fichier jdbcdrv.zip sont
stockés ici.
♦ ASASystem Les noms des classes issus du fichier classes.zip sont
stockés ici.
Ces classes d'exécution incluent les packages suivants :
♦ java Ces packages sont les classes d'exécution Java de Sun
Microsystems supportées.
$ Pour une liste complète des API Java reconnues, reportez-vous à la
section "Packages Java supportés", page 83 du document ASA Manuel
de référence SQL.
♦ com.sybase Ces packages fournissent le support JDBC côté serveur.
♦ sun Ces packages sont fournis par Sun Microsystems.
♦ sybase.sql Ces packages font partie du support JDBC côté serveur de
Sybase.

Chapitre 4 Utilisation de Java dans la base de données
Avertissement : Ne pas installer de classes provenant d’une autre
version du JDK de Sun
Certaines classes du kit JDK de Sun portent le même nom que les classes
d'exécution Java de Sybase qui doivent être installées dans une base de
données pour exécuter des opérations Java.
Ne remplacez pas le fichier classes.zip qui se trouve dans Adaptive Server
Anywhere. L'utilisation d'une autre version de ces classes peut entraîner
des problèmes de compatibilité avec la machine virtuelle Java de Sybase.
Pour configurer une base de données pour Java, utilisez uniquement les
données dans cette section.
Méthodes de configuration pour Java
Création des bases
de données
Mise à niveau des
bases de données
Les bases de données peuvent être configurées pour Java lors de leur
création, de leur mise à niveau ou à tout autre moment par une opération
distincte.
Il y a plusieurs façons de créer une base de données configurée pour Java :
♦ A l'aide de l'instruction CREATE DATABASE.
$ Pour la syntaxe à utiliser, reportez-vous à la section "Instruction
CREATE DATABASE", page 289 du document ASA Manuel de
référence SQL.
♦ A l’aide de l’utilitaire dbinit.
$ Pour plus d'informations, reportez-vous à la section "Création
d'une base de données à l'aide de l'utilitaire dbinit", page 502 du
document ASA Guide d’administration.
♦ A l'aide de Sybase Central.
$ Pour plus d'informations, reportez-vous à la section "Création
d'une base de données", page 29 du document ASA Guide de l’utilisateur
SQL.
Il existe différentes méthodes pour mettre à niveau une base de données
configurée pour Java en la faisant évoluer de la version 5 à la version 8,
comme suit :
♦ A l'aide de l'instruction ALTER DATABASE.
$ Pour la syntaxe à utiliser, reportez-vous à la section "Instruction
ALTER DATABASE", page 216 du document ASA Manuel de
référence SQL.
97

Configuration de la base de données pour Java
98
♦ A l'aide de l'utilitaire de mise à niveau dbupgrad.exe.
$ Pour plus d'informations, reportez-vous à la section "Mise à niveau
d'une base de données à l'aide de l'utilitaire dbupgrad", page 569 du
document ASA Guide d’administration.
♦ Sybase Central.
$ Pour plus de détails reportez-vous à "Mise à niveau d'une base de
données à l'aide de l'utilitaire dbupgrad", page 569 du document ASA
Guide d’administration.
Si vous choisissez de ne pas installer Java dans la base de données, toutes les
opérations de base de données qui ne font pas appel à des opérations Java
seront entièrement exploitables et fonctionneront normalement.
Nouvelles bases de données et Java
Options CREATE
DATABASE
Utilitaire de
création de la base
de données
Par défaut, Adaptive Server Anywhere n'installe pas les classes d'exécution
Java de Sybase chaque fois que vous créez une base de données. Toutefois,
l'installation de ce composant sous licence séparée est facultative et contrôlée
par la méthode que vous utilisez pour créer la base de données.
L'instruction SQL CREATE DATABASE possède une option appelée
JAVA. Pour configurer une base de données pour Java, affectez à l'option la
valeur ON. Pour désactiver Java, affectez-lui la valeur OFF. Par défaut, cette
option est définie avec la valeur OFF.
Par exemple, l'instruction suivante crée le fichier de base de données pour
Java temp.db :
CREATE DATABASE ’c:\\sybase\\asa8\\temp’ JAVA ON
L'instruction suivante crée le fichier de base de données temp2.db, qui ne
supporte pas Java.
CREATE DATABASE ’c:\\sybase\\asa8\\temp2’
Vous pouvez créer des bases de données à l'aide de création de bases de
données dbinit.exe. Cet utilitaire comporte des options qui permettent de
contrôler l'installation des classes d'exécution Java dans la base de données.
Par défaut, ces classes sont ne sont pas installées.
Vous pouvez également utiliser ces options lorsque vous créez une base de
données à l'aide de Sybase Central.

Chapitre 4 Utilisation de Java dans la base de données
Mise à niveau des bases de données et de Java
Utilitaire de mise à
niveau des bases
de données
Vous pouvez mettre à niveau des bases de données existantes créées avec des
versions antérieures du logiciel à l'aide de l'utilitaire de mise à niveau ou de
l'instruction ALTER DATABASE.
La mise à niveau des bases de données selon les normes
d'Adaptive Server Anywhere version 8 peut être effectuée à l'aide de
l'utilitaire dbupgrad.exe. L'option –jr permet d'empêcher l'installation des
classes d'exécution Java de Sybase.
$ Pour plus d'informations sur les conditions dans lesquelles Java dans la
base de données est inclus dans une base de données mise à niveau, reportezvous
à la section "Mise à niveau d'une base de données à l'aide de l'utilitaire
dbupgrad", page 569 du document ASA Guide d’administration.
Configuration de la base de données pour Java
Si, au moment de sa création ou de sa mise à niveau, vous avez choisi de ne
pas configurer la base de données pour Java, vous avez toujours la possibilité
d'ajouter les classes Java ultérieurement, soit depuis Sybase Central, soit
depuis Interactive SQL.
v Pour ajouter des classes d'exécution Java dans une base de
données à partir de Sybase Central :
1 Connectez-vous à la base de données à partir de Sybase Central en tant
qu'utilisateur détenant les droits DBA.
2 Effectuez un clic droit sur la base de données, puis choisissez Mettre la
base de données à niveau.
3 Cliquez sur Suivant sur la page introductive de l'assistant.
4 Dans la liste, sélectionnez la base de données que vous souhaitez mettre
à niveau.
5 Si vous le souhaitez, vous pouvez demander la création d'une copie de
sauvegarde de la base de données. Cliquez sur Suivant.
6 Si vous le souhaitez, vous pouvez installer le support de métadonnées
jConnect. Cliquez sur Suivant.
7 Sélectionnez l'option Installer le support Java. Vous devez choisir la
version de JDK à installer. Les classes par défaut sont les classes JDK
1.3. Pour les bases de données créées avec la version 7.x, les classes par
défaut sont les classes JDK 1.1.8.
99

Configuration de la base de données pour Java
100
8 Suivez la suite des instructions affichées par l'assistant.
v Pour ajouter des classes d'exécution Java dans une base de
données à partir de SQL :
1 Connectez-vous à la base de données à partir d'Interactive SQL en tant
qu'utilisateur détenant les droits DBA.
2 Exécutez l'instruction suivante :
ALTER DATABASE UPGRADE JAVA ON
$ Pour plus d'informations, reportez-vous à la section "Instruction
ALTER DATABASE", page 216 du document ASA Manuel de
référence SQL.
3 Relancez la base de données afin que le support Java soit effectif.
Configuration d'une base de données pour Java à l'aide de
Sybase Central
Vous pouvez utiliser Sybase Central pour créer des bases de données à l'aide
des assistants. Durant l'opération de création ou de mise à niveau, l'assistant
vous demande si les classes d'exécution Java doivent être installées ou non.
L'option par défaut configure la base de données pour Java.
Dans Sybase Central, vous disposez de deux méthodes pour créer ou mettre à
niveau une base de données :
♦ Création d'une base de données à partir du dossier Utilitaires.
♦ Mise à niveau d'une base de données à partir du dossier Utilitaires afin
de la mettre à niveau et la faire évoluer vers une version disposant de
fonctionnalités Java.

Chapitre 4 Utilisation de Java dans la base de données
Installation de classes Java dans une base de
données
Création d'une classe
Vous devez compiler la classe Java avant de l’installer dans une base de
données. L'installation peut se faire de plusieurs façons :
♦ Par classe Vous installez chaque classe dans la base de données à partir
du fichier de la classe compilée. Les fichiers de classe portent
généralement l'extension .class.
♦ Par fichier JAR Vous installez plusieurs classes à la fois par le biais
d'un fichier JAR compacté ou non. Les fichiers JAR ont en général
l'extension .jar ou .zip. Adaptive Server Anywhere supporte tous les
fichiers JAR compactés créés avec l'utilitaire JAR de Sun et certains
autres formats de compression JAR.
Cette section explique comment installer les classes Java une fois compilées.
Vous devez détenir les droits DBA pour installer une classe ou un
fichier JAR.
La procédure de création d'une classe se compose des étapes ci-dessous. Le
détail de chaque étape peut varier selon qu'un outil de développement Java
tel que Sybase PowerJ est utilisé ou non.
v Pour créer une classe :
1 Définissez une classe Ecrivez le code Java qui définit votre classe. Si
vous utilisez le kit SDK de Sun Java, vous travaillez dans un éditeur de
texte. Si vous utilisez un outil de développement de type Sybase PowerJ,
suivez les instructions fournies par l'outil.
Utilisez uniquement les classes supportées
Si votre classe utilise des classes d'exécution Java, vérifiez que ces
classes figurent bien dans la liste des classes supportées que vous
trouverez à la section "Packages Java supportés", page 83 du
document ASA Manuel de référence SQL.
Les classes utilisateur doivent être 100 % Java. Les méthodes natives
ne sont pas autorisées.
101

Installation de classes Java dans une base de données
Installation d’une classe
102
2 Nommez et sauvegardez la classe définie Sauvegardez votre
déclaration de classe (code Java) dans un fichier portant l'extension
.java. Vous devez donner au fichier exactement le même nom que la
classe, en respectant les majuscules et minuscules.
Par exemple, une classe appelée Utility doit être sauvegardée dans un
fichier Utility.java.
3 Compilez la classe Cette étape sert à convertir la déclaration de classe,
qui contient du code Java, en un nouveau fichier, séparé, contenant du
code octet. Ce nouveau fichier porte le même nom que le fichier en code
Java mais avec l'extension .class. Une classe Java compilée peut être
exécutée dans un environnement d'exécution Java, quelle que soit la
plate-forme qui a servi à sa compilation ou le système d'exploitation
utilisé.
Le kit JDK de Sun contient un compilateur Java, Javac.exe.
Uniquement les bases de données configurées pour Java
N'importe quel fichier de classe compilé Java peut être installé dans
une base de données. Toutefois, les opérations Java qui utilisent une
classe installée ne peuvent s'exécuter que si la base de données a été
configurée pour Java, comme indiqué dans la section "Configuration
de la base de données pour Java", page 95.
Pour que la classe Java que vous avez créée soit disponible dans la base de
données, vous devez l'installer soit à partir de Sybase Central, soit à l'aide de
l'instruction INSTALL depuis Interactive SQL ou une autre application.
Vous devez connaître le chemin d'accès à la classe et le nom de fichier
correspondant.
Vous devez détenir les droits administrateur de la base de données (DBA)
pour pouvoir installer une classe.
v Pour installer une classe à partir de Sybase Central
1 Connectez-vous à une base de données avec les droits DBA.
2 Ouvrez le dossier Objets Java de la base de données.
3 Double-cliquez sur Ajouter une classe Java.
4 Suivez les instructions de l'assistant.

Installation d’un fichier JAR
Chapitre 4 Utilisation de Java dans la base de données
v Pour installer une classe à partir de SQL :
1 Connectez-vous à une base de données avec les droits DBA.
2 Exécutez l'instruction suivante :
INSTALL JAVA NEW
FROM FILE ’chemin\\NomClasse.class’
chemin correspondant au nom du répertoire contenant le fichier de classe
et NomClasse.class correspondant au nom du fichier de classe.
Deux barres obliques inversées (\\) sont nécessaires pour que la barre
oblique inversée ne soit pas interprétée comme un caractère
d'échappement.
Par exemple, pour installer une classe dans le fichier Utility.class résidant
dans le répertoire c:\source, vous devez spécifier l'instruction suivante :
INSTALL JAVA NEW
FROM FILE ’c:\\source\\Utility.class’
Si vous indiquez un chemin d'accès relatif, il doit se rapporter au
répertoire de travail courant du serveur de base de données.
$ Pour plus d'informations, reportez-vous aux sections "Instruction
INSTALL", page 489 du document ASA Manuel de référence SQL et
"Suppression d’objets Java, de classes et de fichiers JAR", page 112.
Il est utile et courant de regrouper des classes associées dans un package et
de stocker le ou les package(s) créé(s) dans un fichier JAR. Pour plus
d'informations sur les fichiers JAR et les packages, reportez-vous à la
documentation en ligne annexe Thinking in Java, ou à tout autre ouvrage
traitant de la programmation en Java.
Pour installer un fichier JAR, suivez la même procédure que pour installer un
fichier de classe. Un fichier JAR porte l'extension JAR ou ZIP. Chaque
fichier JAR doit avoir un nom dans la base de données. Utilisez de
préférence le même nom que le fichier JAR sans l'extension. Par exemple, si
vous installez le fichier JAR monjar.zip, donnez-lui le nom monjar.
$ Pour plus d'informations, reportez-vous aux sections "Instruction
INSTALL", page 489 du document ASA Manuel de référence SQL et
"Suppression d’objets Java, de classes et de fichiers JAR", page 112.
103

Installation de classes Java dans une base de données
104
v Pour installer un fichier JAR à partir de Sybase Central
1 Connectez-vous à une base de données avec les droits DBA.
2 Ouvrez le dossier Objets Java de la base de données.
3 Double-cliquez sur Ajouter un fichier JAR.
4 Suivez les instructions de l'assistant.
v Pour installer un fichier JAR à partir de SQL :
1 Connectez-vous à une base de données avec les droits DBA.
2 Entrez la commande suivante :
INSTALL JAVA NEW
JAR ’nomjar’
FROM FILE ’chemin\\NomJar.jar’
Mise à jour des classes et des fichiers JAR
Les objets Java
actuels et les
classes mises à
jour
Prise en compte
des mises à jour
Vous pouvez mettre à jour les classes et les fichiers JAR à l'aide de
Sybase Central, de l'instruction INSTALL d'Interactive SQL ou d'autres
applications clientes.
Pour ce faire, vous devez détenir les droits DBA et disposer d'une version
plus récente du fichier JAR ou du fichier de classe compilé sur le disque.
Plusieurs occurrences d'une classe Java peuvent résider dans la base de
données sous forme d'objets Java. C'est par exemple le cas lorsque des
valeurs dans une colonne utilisent cette classe comme type de données.
Malgré la mise à jour de la classe, les anciennes valeurs restent disponibles,
même si les champs et les méthodes stockés dans les tables sont
incompatibles avec la nouvelle définition de classe.
Cependant, les nouvelles lignes que vous insérez doivent être compatibles
avec la nouvelle définition.
La nouvelle définition n'est utilisée que par les connexions qui sont établies
ou utilisent la classe pour la première fois après installation de la classe. Dès
qu'une définition de classe est chargée par la machine virtuelle, elle est
stockée en mémoire jusqu'à la fermeture de la connexion.
Si, pendant la connexion en cours, vous avez fait appel à une classe Java ou à
un objet associé à cette classe, vous devez vous déconnecter puis vous
reconnecter pour utiliser la nouvelle définition de classe.

Objets stockés et
sérialisés
Chapitre 4 Utilisation de Java dans la base de données
$ Pour comprendre pourquoi une nouvelle connexion est nécessaire pour
la prise en compte des mises à jour, il faut saisir le principe de
fonctionnement de la machine virtuelle. Pour plus d'informations, reportezvous
à la section "Configuration de la mémoire pour Java", page 137.
Si les objets Java peuvent utiliser la nouvelle définition de classe, c'est parce
qu'ils ont été stockés de façon sérialisée. Le format de sérialisation utilisé a
été spécialement conçu pour la base de données. Il ne s'agit pas du format
développé par Sun Microsystems. Les opérations de sérialisation et de
désérialisation sont exécutées en interne par la machine virtuelle de Sybase,
de sorte qu'aucun problème de compatibilité ne se pose.
v Pour mettre à jour une classe ou un fichier JAR à partir de
Sybase Central :
1 Connectez-vous à une base de données avec les droits DBA.
2 Ouvrez le dossier Objets Java.
3 Recherchez la classe ou le fichier JAR à mettre à jour.
4 Cliquez avec le bouton droit de la souris sur la classe ou le fichier JAR
et sélectionnez Mettre à jour dans le menu contextuel.
5 Dans la boîte de dialogue qui s'affiche, spécifiez le nom et
l'emplacement de la classe ou du fichier JAR à mettre à jour. Au besoin,
cliquez sur le bouton Parcourir.
Conseil
Vous pouvez aussi mettre à jour une classe Java ou un fichier JAR en
cliquant sur Mettre à niveau maintenant dans l'onglet Général de la feuille
de propriétés correspondante.
v Pour mettre à jour une classe ou un fichier JAR à partir de SQL :
1 Connectez-vous à une base de données avec les droits DBA.
2 Exécutez l'instruction suivante :
INSTALL JAVA UPDATE
[ JAR ’nomjar’ ]
FROM FILE ’nomfichier’
Si vous mettez à jour un fichier JAR, entrez son nom tel qu'il est connu
dans la base de données.
$ Pour plus d'informations, reportez-vous à la section "Instruction
INSTALL", page 489 du document ASA Manuel de référence SQL.
105

Création de colonnes d'objets Java
Création de colonnes d'objets Java
106
Cette section explique comment les colonnes de types de données de classe
Java se placent dans le cadre SQL standard.
Création de colonnes de types de données Java
Distinction
majuscules/
minuscules
N'importe qu'elle classe Java installée peut être utilisée comme type de
données. Vous devez utiliser le nom intégralement qualifié du type de
données.
Par exemple, l'instruction CREATE TABLE ci-dessous insère une colonne
qui comporte des colonnes de types de données Java asademo.Name et
asademo.ContactInfo. Dans cet exemple, Name et ContactInfo sont des
classes à l'intérieur du package asademo.
CREATE TABLE jdba.customer
(
id integer NOT NULL,
company_name CHAR(35) NOT NULL,
JName asademo.Name NOT NULL,
JContactInfo asademo.ContactInfo NOT NULL,
PRIMARY KEY (id)
)
Contrairement aux types de données SQL, les types Java font la distinction
majuscules/minuscules. Vous devez fournir le nom exact de chaque partie du
type de données en respectant les minuscules et les majuscules.
Valeurs par défaut et entrées NULL dans les colonnes Java
Vous pouvez utiliser les valeurs proposées par défaut dans les colonnes Java
et laisser des entrées vides (valeur NULL).
Colonnes Java et valeurs par défaut Toute fonction du type de données
et toute valeur par défaut prédéfinie est acceptée comme valeur par défaut
dans les colonnes. Vous pouvez utiliser n'importe quelle fonction du type de
données approprié (par exemple, de la même classe que la colonne) comme
valeur par défaut pour les colonnes Java.
Colonnes Java et valeur NULL Les colonnes Java acceptent la valeur
NULL. Si aucune valeur par défaut n'a été définie dans une colonne de type
Java et que la colonne accepte la valeur NULL, cette valeur est attribuée à la
colonne.

Chapitre 4 Utilisation de Java dans la base de données
Si une valeur Java n'a pas été définie, elle prend la valeur NULL. Cette
valeur Java est mappée sur la SQL NULL et vous pouvez utiliser les critères
de recherche IS NULL et IS NOT NULL. Supposons par exemple que la
description de l'objet Java Product dans une colonne appelée JProd n'a pas
été définie ; vous pouvez rechercher tous les produits de valeur non NULL
correspondant à la description, comme suit :
SELECT *
FROM product
WHERE JProd>>description IS NULL
107

Insertion, mise à jour et suppression d'objets Java
Insertion, mise à jour et suppression d'objets
Java
Création de tables
Java exemple
Classe exemple
108
Cette section explique comment les instructions de manipulation des
données SQL standard s'appliquent aux colonnes Java.
Chaque point décrit dans cette section est illustré à l'aide d'un exemple
concret qui utilise la table Product de la base de données exemple et la classe
Product. Consultez au préalable le fichier
Samples\ASA\Java\asademo\Product.java stocké dans le répertoire
SQL Anywhere.
Les exemples fournis dans cette section supposent que les tables Java ont
déjà été ajoutées à la base de données exemple et qu'elles sont connectées à
l'ID utilisateur jDBA doté du mot de passe SQL.
$ Pour plus d'informations, reportez-vous à la section "Installation des
exemples Java", page 92.
Cette section décrit la classe utilisée en exemple dans les rubriques qui
suivent.
La définition de la classe Product se trouve dans le fichier
Samples\ASA\Java\asademo\Product.java, du répertoire SQL Anywhere.
Une partie est reproduite ci-après :
package asademo;
public class Product implements java.io.Serializable {
// champs publics
public String name ;
public String description ;
public String size ;
public String color;
public int quantity ;
public java.math.BigDecimal unit_price ;
// Constructeur par défaut
Product () {
unit_price = new java.math.BigDecimal( 10.00 );
name = "Unknown";
size = "One size fits all";

Remarques
Insertion d’objets Java
}
Chapitre 4 Utilisation de Java dans la base de données
// Constructeur utilisant tous les arguments
disponibles
Product ( String inColor,
String inDescription,
String inName,
int inQuantity,
String inSize,
java.math.BigDecimal inUnit_price
) {
color = inColor;
description = inDescription;
name = inName;
quantity = inQuantity;
size = inSize;
unit_price=inUnit_price;
}
public String toString() {
return size + " " + name + ": " +
unit_price.toString();
}
♦ La classe Product possède plusieurs champs publics ; ceux-ci
correspondent à certaines colonnes de la table DBA.Product qui doivent
être rassemblées dans cette classe.
♦ La méthode toString est fournie pour plus de convivialité. Lorsque vous
insérez un nom d'objet dans une liste de sélection, la méthode toString
s'exécute et la chaîne renvoyée s'affiche.
♦ Certaines méthodes servent à définir et accéder aux champs. Elles
s'utilisent généralement en programmation orientée objet afin d'éviter
l'accès direct aux champs. Pour des raisons pratiques, les champs
proposés en exemple sont publics.
Lorsque vous ajoutez à l'aide de l'instruction INSERT une ligne dans une
table dotée d'une colonne Java, vous devez insérer un objet Java dans la
colonne Java.
L'insertion d'un objet Java peut s'effectuer de deux façons : avec SQL ou à
partir d'autres classes Java exécutées dans la base de données, à l'aide de
JDBC.
109

Insertion, mise à jour et suppression d'objets Java
Insertion d'un objet Java à partir de SQL
Insertion d’un objet
à l'aide d'un
constructeur
Insertion d'un objet
à partir de la
variable SQL
110
Vous pouvez insérer un objet Java à l'aide d'un constructeur ou utiliser des
variables SQL pour construire l'objet Java à insérer.
Lorsque vous ajoutez une valeur dans une colonne portant un type de
données de classe Java, vous insérez un objet Java. Les champs du nouvel
objet doivent convenir à n'importe quel champ public et les méthodes qui
définissent des champs privés doivent pouvoir être appelées.
v Pour insérer un objet Java :
♦ Insérez avec l'instruction INSERT une nouvelle instance de la classe
Product dans la table product comme suit :
INSERT
INTO product ( ID, JProd )
VALUES ( 702, NEW asademo.Product() )
Appliquez cet exemple sur la base de données exemple avec l'ID
utilisateur jdba, une fois que le script jdemo.sql a été exécuté.
Le mot-clé NEW appelle le constructeur par défaut de la classe Product
dans le package asademo.
Vous pouvez également définir les valeurs de champ d'un objet dans une
variable de la classe correspondante, au lieu d'utiliser le constructeur.
v Pour insérer un objet Java avec des variables SQL :
1 Créez une variable SQL du type de classe Java :
CREATE VARIABLE ProductVar asademo.Product
2 Attribuez un nouvel objet à la variable, à l'aide du constructeur de
classe :
SET ProductVar = NEW asademo.Product()
3 Attribuez les valeurs aux champs de l'objet :
SET ProductVar>>color = ’Black’;
SET ProductVar>>description = ’Steel tipped boots’;
SET ProductVar>>name = ’Work boots’;
SET ProductVar>>quantity = 40;
SET ProductVar>>size = ’Extra Large’;
SET ProductVar>>unit_price = 79.99;
4 Insérez la variable dans la table :
INSERT
INTO Product ( id, JProd )
VALUES ( 800, ProductVar )

Insertion d’un objet avec Java
Chapitre 4 Utilisation de Java dans la base de données
5 Vérifiez que la valeur a été insérée.
SELECT *
FROM product
WHERE id=800
6 Annulez les modifications apportées au cours de cet exercice.
ROLLBACK
Mise à jour des objets Java
Mise à jour de
l'objet entier
Il est courant d'utiliser des variables SQL dans les procédures stockées et
dans d'autres utilisations de SQL pour construire une logique de
programmation au sein de la base de données. Java offre un moyen plus
puissant d'accomplir cette tâche. Par exemple, vous pouvez utiliser des
classes Java côté serveur avec JBDC pour insérer des objets dans les tables.
Vous pouvez insérer un objet dans une table à l'aide d'une instruction
préparée JDBC.
Une instruction préparée utilise des marques de réservation pour les
variables. Vous pouvez ensuite utiliser la méthode setObject de l'objet
PreparedStatement.
Vous pouvez utiliser des instructions préparées pour insérer des objets à
partir de JDBC, côté client ou côté serveur.
$ Pour plus d'informations sur l'utilisation des instructions préparées,
reportez vous à la section "Insertion et extraction d'objets", page 169.
Vous pouvez mettre à jour la valeur d'une colonne Java de plusieurs façons :
♦ en mettant à jour la totalité de l'objet,
♦ en mettant à jour certains champs de l'objet.
La procédure de mise à jour d'un objet est quasiment identique à celle
utilisée pour insérer les objets.
♦ A partir de SQL, vous pouvez utiliser un constructeur pour mettre à jour
l'objet complet : le constructeur crée alors un nouvel objet. Il suffit
ensuite de mettre à jour les champs comme souhaité.
♦ A partir de SQL, vous pouvez utiliser une variable SQL pour contenir
l'objet, puis mettre à jour la ligne qui doit contenir la variable.
♦ A partir de JDBC, utilisez une instruction préparée et la méthode
PreparedStatement.setObject.
111

Insertion, mise à jour et suppression d'objets Java
Mise à jour des
champs de l'objet
Utilisation des
méthodes SET
112
Chaque champ d'un objet porte des types de données correspondant à des
types de données SQL. Le mappage des types SQL en Java se fait selon le
principe décrit à la section "Conversions entre types de données Java et
SQL", page 91 du document ASA Manuel de référence SQL.
L’instruction UPDATE permet de faire une mise à jour par champ :
UPDATE Product
SET JProd.unit_price = 16.00
WHERE ID = 302
Dans la version initiale de Java dans la base de données, il fallait exécuter
une fonction particulière (EVALUATE) pour effectuer des mises à jour.
Cette opération n'a plus lieu d'être.
Pour mettre à jour un champ Java, le type de données Java du champ doit
correspondre à un type SQL : l'expression à droite de la clause SET doit
correspondre à ce type. Vous devrez peut-être faire appel à la fonction CAST
pour rechercher les types de données appropriés.
$ Pour plus d'informations sur les mappages de types de données entre
Java et SQL, reportez-vous à la section "Conversions entre types de données
Java et SQL", page 91 du document ASA Manuel de référence SQL.
En programmation Java, il est courant de ne pas accéder directement aux
champs, mais d'utiliser des méthodes pour accéder à la valeur et la définir.
Généralement, ces méthodes renvoient void. Vous pouvez utiliser des
méthodes SET dans SQL pour mettre à jour une colonne :
UPDATE jdba.Product
SET JProd.setName( ’Tank Top’)
WHERE id=302
L'utilisation des méthodes est moins rapide que l'adressage direct des champs
car elle nécessite l'exécution de la machine virtuelle Java.
$ Pour plus d'informations, reportez-vous à la section "Valeur renvoyée
par les méthodes renvoyant void", page 122.
Suppression d’objets Java, de classes et de fichiers JAR
Les lignes contenant des objets Java sont supprimées exactement comme
d'autres lignes. La clause WHERE dans l'instruction DELETE peut contenir
des objets Java ou des champs et des méthodes.
$ Pour plus d'informations, reportez-vous à la section "Instruction
DELETE", page 410 du document ASA Manuel de référence SQL.
Avec Sybase Central, vous pouvez aussi supprimer une classe Java complète
ou un fichier JAR.

Chapitre 4 Utilisation de Java dans la base de données
v Pour supprimer une classe ou un fichier JAR à partir de
Sybase Central :
1 Ouvrez le dossier Objets Java.
2 Recherchez la classe ou le fichier JAR à supprimer.
3 Cliquez avec le bouton droit de la souris sur la classe ou le fichier JAR
et sélectionnez Supprimer dans le menu contextuel.
$ Voir aussi
♦ "Installation d'une classe", page 102
♦ "Installation d'un fichier JAR", page 103
113

Recherche d’objets Java
Recherche d’objets Java
Récupération de la
totalité de l'objet
Récupération des
champs de l'objet
114
Vous pouvez récupérer la valeur d'une colonne Java de plusieurs façons :
♦ en récupérant la totalité de l'objet,
♦ en récupérant certains champs de l'objet.
Vous pouvez créer dans SQL une variable du type approprié et attribuer à
cette variable une valeur qui figure dans l'objet. Cependant, c'est dans une
application Java que vous aurez le plus besoin d'utiliser l'objet entier.
Vous pouvez récupérer un objet dans une classe Java côté serveur en utilisant
la méthode getObject de l'instruction ResultSet. Vous pouvez également
récupérer un objet dans une application Java côté client.
$ Pour plus d'informations sur la récupération d'objets à l'aide de JDBC,
reportez-vous à la section "Requêtes avec JDBC", page 166.
Chaque champ d'un objet porte des types de données correspondant à des
types de données SQL. Le mappage des types SQL en Java se fait selon le
principe décrit à la section "Conversions entre types de données Java et
SQL", page 91 du document ASA Manuel de référence SQL.
♦ Vous pouvez récupérer des champs individuels en les incluant à la liste
de sélection d'une requête, comme illustré dans l'exemple suivant :
SELECT JProd>>unit_price
FROM product
WHERE ID = 400
♦ Si vous utilisez des méthodes pour définir et rechercher les valeurs de
vos champs, comme cela se fait souvent dans la programmation orientée
objet, vous pouvez inclure une méthode getField à votre recherche :
SELECT JProd>>getName()
FROM Product
WHERE ID = 401
$ Pour plus d'informations sur l'utilisation des objets avec la clause
WHERE et sur la comparaison d'objets, reportez-vous à la section
"Comparaison des champs et des objets Java", page 116.
Conseil relatif aux performances
L'obtention directe d'un champ est plus rapide que l'appel d'une méthode
qui obtient le champ car les appels de méthode nécessitent la machine
virtuelle Java.

Liste des noms de
colonnes par
SELECT
Chapitre 4 Utilisation de Java dans la base de données
Vous pouvez afficher le nom des colonnes dans une liste de sélection, en
tapant la requête suivante :
SELECT JProd
FROM jdba.product
Cette requête renvoie la sérialisation Sun de l'objet à l'application cliente.
Lorsque vous exécutez une requête qui récupère un objet dans
Interactive SQL, elle affiche la valeur renvoyée par la méthode toString de
l'objet. Pour la classe Product, la méthode toString affiche, en une seule
chaîne de caractères, la taille, le nom et le prix unitaire de l'objet. Le résultat
de la requête est le suivant :
JProd
Small Tee Shirt: 9.00
Medium Tee Shirt: 14.00
One size fits all Tee Shirt: 14.00
One size fits all Baseball Cap: 9.00
One size fits all Baseball Cap: 10.00
One size fits all Visor: 7.00
One size fits all Visor: 7.00
Large Sweatshirt: 24.00
Large Sweatshirt: 24.00
Medium Shorts: 15.00
115

Comparaison des champs et des objets Java
Comparaison des champs et des objets Java
Types de
comparaison
d’objets Java
116
Les classes Java publiques sont des domaines définis de manière bien plus
détaillée que les domaines SQL. C'est d'ailleurs pourquoi le comportement
des colonnes Java dans une base de données relationnelle est différent de
celui des colonnes contenant des types de données SQL traditionnelles.
La méthode de comparaison des objets influe notamment sur :
♦ Les requêtes comportant une clause ORDER BY ou GROUP BY, un
mot-clé DISTINCT ou une fonction agrégée.
♦ Les instructions qui utilisent des conditions d'égalité ou d'inégalité.
♦ Les index et les colonnes uniques.
♦ Les colonnes de clés primaires et étrangères.
Le tri et l'agencement des lignes d'une requête ou d'un index impliquent la
comparaison des valeurs de chaque ligne. Dans le cas d'une colonne Java,
vous pouvez effectuer des comparaisons en procédant comme suit :
♦ Effectuer une comparaison sur un champ public Vous pouvez
comparer un champ public de la même manière que vous comparez une
ligne ordinaire. Par exemple, exécutez la requête suivante :
SELECT name, JProd>>unit_price
FROM Product
ORDER BY JProd>>unit_price
Vous pouvez utiliser ce type de comparaison dans les requêtes, mais pas
dans les index ni dans les colonnes de clés.
♦ Effectuer une comparaison à l'aide de la méthode compareTo Les
objets Java intégrant une méthode compareTo peuvent faire l'objet
d'une comparaison. La classe Product, sur laquelle est basée la colonne
JProd, intègre une méthode compareTo qui compare les objets basés
sur le champ unit_price. Vous pouvez ainsi effectuer la requête
suivante :
SELECT name, JProd>>unit_price
FROM Product
ORDER BY JProd
La comparaison requise par la clause ORDER BY est automatiquement
effectuée sur la base de la méthode compareTo.

Comparaison d’objets Java
Configuration
requise par la
méthode
compareTo
Exemple
Chapitre 4 Utilisation de Java dans la base de données
Pour comparer deux objets du même type, vous devez appliquer une
méthode compareTo.
♦ Pour utiliser comme clés primaires, index ou colonnes uniques les
colonnes de types de données Java, la classe de colonne doit mettre en
oeuvre une méthode compareTo.
♦ Pour utiliser les clauses ORDER BY, GROUP BY ou DISTINCT dans
une requête, les valeurs de la colonne doivent faire l'objet d'une
comparaison. La classe de colonne doit intégrer une méthode
compareTo pour que ces clauses puissent être reconnues.
♦ Les fonctions incluant des comparaisons, telles que MAX et MIN, ne
peuvent être appliquées à une classe Java que si cette dernière intègre
une méthode compareTo.
La méthode compareTo doit être associée aux propriétés suivantes :
♦ Portée La méthode doit être visible de manière externe, c'est-à-dire qu'il
doit s'agir d'une méthode public.
♦ Arguments La méthode ne prend en compte qu'un argument, qui est un
objet du type en cours. L'objet en cours est comparé à l'objet fourni. Par
exemple, Product.compareTo est associé à l'argument suivant :
compareTo( Product anotherProduct )
Cette méthode compare l'objet anotherProduct, du type Product, à
l'objet en cours.
♦ Valeurs renvoyées La méthode compareTo doit renvoyer des données
de type int suivantes :
♦ Entier négatif La valeur de l'objet en cours est inférieure à celle de
l'objet fourni. Pour des raisons de compatibilité avec les méthodes
compareTo des classes Java de base, il est recommande de renvoyer
la valeur -1 dans ce cas.
♦ Zéro La valeur de l'objet en cours est identique à celle de l'objet
fourni.
♦ Entier positif La valeur de l'objet en cours est supérieure à celle de
l'objet fourni. Pour des raisons de compatibilité avec les méthodes
compareTo des classes Java de base, il est recommandé de renvoyer
la valeur 1 dans ce cas.
La classe Product installée dans la base de données exemple avec les classes
exemple intègre une méthode compareTo, comme illustré ci-après :
public int compareTo( Product anotherProduct ) {
117

Comparaison des champs et des objets Java
Compatibilité de
toString et
compareTo
118
// Compare d’abord les prix
// puis toString()
int lVal = unit_price.intValue();
int rVal = anotherProduct.unit_price.intValue();
if ( lVal > rVal ) {
return 1;
}
else if (lVal < rVal ) {
return -1;
}
else {
return toString().compareTo(
anotherProduct.toString() );{
}
}
}
Cette méthode compare le prix unitaire de chaque objet. Si tous les prix sont
identiques, la comparaison porte sur les noms (à l'aide d'une comparaison de
chaîne Java, et non de chaîne de base de données). Deux objets sont
considérés comme étant identiques s'ils ont le même prix unitaire et le même
nom.
Si vous incluez une colonne Java dans liste de sélection d'une requête puis
que vous l'exécutez dans Interactive SQL, la valeur de la méthode toString
est renvoyée. La méthode compareTo est utilisée pour comparer des
colonnes. Si les méthodes toString et compareTo ne sont pas utilisées de
manière cohérente, vous risquez d'obtenir des résultats surprenants. Une
requête DISTINCT, par exemple, peut renvoyer des lignes dupliquées.
Supposons que la classe Product de la base de données exemple intègre une
méthode toString, qui a renvoyé le nom du produit, et une méthode
compareTo basée sur le prix. Les valeurs renvoyées par la requête suivante,
exécutée dans Interactive SQL, seraient dupliquées :
SELECT DISTINCT JProd
FROM product
JProd
Tee-shirt
Tee-shirt
Baseball Cap
Visor
Sweat-shirt
Shorts

Chapitre 4 Utilisation de Java dans la base de données
Dans cet exemple, la valeur renvoyée est déterminée par toString. Le motclé
DISTINCT élimine les valeurs dupliquées définies par compareTo. Le
fait que ces deux méthodes aient été mises en oeuvre de manière
indépendante explique que les lignes renvoyées soient dupliquées.
119

Fonctionnalités spéciales des classes Java dans la base de données
Fonctionnalités spéciales des classes Java dans
la base de données
Classes supportées
Appel de la méthode main
120
Cette section décrit les fonctionnalités des classes Java utilisées dans la base
de données.
Vous ne pouvez pas utiliser toutes les classes du JDK. Les classes
d'exécution Java utilisables dans le serveur de base de données appartiennent
à un sous-ensemble de l'API Java.
$ Pour plus d'informations sur les packages supportés, reportez-vous à la
section "Packages Java supportés", page 83 du document ASA Manuel de
référence SQL.
En général, vous appelez des applications Java (hors de la base) en exécutant
la machine virtuelle Java sur une classe comportant une méthode main.
Par exemple, la classe JDBCExamples stockée dans le fichier
Samples\ASA\Java\JDBCExamples.java du répertoire SQL Anywhere
comporte une méthode main. Lorsque vous exécutez cette classe à partir de
la ligne de commande à l'aide d'une commande du type ci-après, la méthode
main est exécutée :
java JDBCExamples
$ Pour plus d'informations sur l'exécution de la classe JDBCExamples,
reportez-vous à la section "Etablissement de connexions JDBC", page 154.
v Pour appeler la méthode main d'une classe à partir de SQL :
1 Déclarez la méthode avec un tableau de chaînes faisant office
d'argument :
public static void main( java.lang.String[] args ){
...
}
2 Appelez la méthode main à l'aide de l'instruction CALL.
Chaque élément du tableau de chaînes doit être de type CHAR ou
VARCHAR, ou une chaîne littérale.

Exemple
Chapitre 4 Utilisation de Java dans la base de données
La classe suivante contient une méthode main qui écrit les arguments dans
l'ordre inverse :
public class ReverseWrite {
public static void main( String[] args ){
int i:
for( i = args.length; i > 0 ; i-- ){
System.out.print( args[ i-1 ] );
}
}
}
Pour exécuter cette méthode à partir de SQL, procédez comme suit :
call ReverseWrite.main( ’ one’, ’ two’, ’three’ )
La fenêtre du serveur de base de données affiche le résultat suivant :
three two one
Utilisation de threads dans les applications Java
Sérialisation des
appels JDBC
Erreur de procedure introuvable
Grâce aux fonctionnalités du package java.lang.Thread, vous pouvez
utiliser plusieurs threads dans une application Java. Chaque thread Java est
un thread de moteur, dépendant du nombre de threads qu'autorise l'option du
serveur de base de données -gn.
Vous pouvez synchroniser, suspendre, reprendre, interrompre ou arrêter les
threads des applications Java.
$ Pour plus d'informations sur les threads de serveur de base de données,
reportez-vous à la section "Option de serveur -gn", page 153 du document
ASA Guide d’administration.
Tous les appels en direction du gestionnaire JDBC côté serveur sont
sérialisés, de sorte qu'à tout moment, un seul thread exécute activement
JDBC.
Si vous vous trompez dans le nombre d'arguments lors de l'appel d'une
méthode Java ou que vous utilisez un type de données inapproprié, le serveur
renvoie l'erreur La procedure est introuvable. Vous devez alors vérifier le
nombre et le type des arguments.
$ Pour plus d'informations sur la conversion des types entre SQL et Java,
reportez-vous à la section "Conversions entre types de données Java et SQL",
page 91 du document ASA Manuel de référence SQL.
121

Fonctionnalités spéciales des classes Java dans la base de données
Valeur renvoyée par les méthodes renvoyant void
122
Vous pouvez utiliser des méthodes Java dans des instructions SQL chaque
fois que vous pouvez utiliser une expression. Vérifiez toutefois que le type
de données renvoyées par la méthode Java correspond au type de données
SQL approprié.
$ Pour plus d'informations sur le mappage des types de données entre
Java et SQL, reportez-vous à la section "Conversions entre types de données
Java et SQL", page 91 du document ASA Manuel de référence SQL.
Lorsqu'une méthode renvoie une valeur de type void, la valeur this est
renvoyée dans SQL, c'est-à-dire l'objet lui-même. Cette fonctionnalité
n'affecte que les appels émanant de SQL, et non de Java.
Elle se révèle particulièrement utile dans les instructions UPDATE, où les
méthodes set renvoient généralement la valeur void. Vous pouvez utiliser
l'instruction UPDATE suivante dans la base de données exemple :
update jdba.product
set JProd = JProd.setName(’Tank Top’)
where id=302
La méthode setName renvoie la valeur void et, par conséquent, renvoie
l'objet Product à SQL.
Renvoi de jeux de résultats à partir de méthodes Java
Cette section explique comment écrire une méthode Java qui renvoie des
jeux de résultats. Vous devez écrire une méthode Java qui renvoie un jeu de
résultats à l'environnement appelant et l'encapsuler dans une procédure
stockée SQL déclarée comme EXTERNAL NAME de LANGUAGE JAVA.
v Pour renvoyer des jeux de résultats à partir de d'une méthode Java :
1 Vérifiez que la méthode Java est déclarée publique et statique dans une
classe publique.
2 Pour chaque jeu de résultats que doit renvoyer la méthode, vérifiez que
celle-ci contient un paramètre de type java.sql.ResultSet[]. Ces
paramètres de jeux de résultats doivent se trouver à la fin de la liste des
paramètres.
3 Dans la méthode, créez d'abord une instance de java.sql.ResultSet, puis
affectez-la à un des paramètres ResultSet[].

Exemple
Chapitre 4 Utilisation de Java dans la base de données
4 Créez une procédure stockée SQL du type EXTERNAL NAME
LANGUAGE JAVA. Ce type de procédure encapsule la méthode Java.
Vous pouvez utiliser un curseur sur le jeu de résultats de la procédure
SQL, exactement comme toute autre procédure qui renvoie des jeux de
résultats.
$ Pour plus informations sur la syntaxe des procédures stockées qui
encapsulent des méthodes Java, reportez-vous à la section "Instruction
CREATE PROCEDURE", page 321 du document ASA Manuel de
référence SQL.
La classe simple suivante est dotée d'une seule méthode, laquelle effectue
une requête et transmet le jeu de résultats à l'environnement appelant.
import java.sql.*;
public class MyResultSet {
public static void return_rset( ResultSet[] rset1 )
throws SQLException {
Connection conn = DriverManager.getConnection(
"jdbc:default:connection" );
Statement stmt = conn.createStatement();
ResultSet rset =
stmt.executeQuery (
"SELECT CAST( JName.lastName " +
"AS CHAR( 50 ) )" +
"FROM jdba.contact " );
rset1[0] = rset;
}
}
Le jeu de résultats est présenté à SQL via une instruction CREATE
PROCEDURE qui indique le nombre de jeux de résultats renvoyés à partir
de la procédure et la signature de la méthode Java.
Vous pouvez définir une instruction CREATE PROCEDURE indiquant un
jeu de résultats, comme suit :
CREATE PROCEDURE result_set()
DYNAMIC RESULT SETS 1
EXTERNAL NAME
’MyResultSet.return_rset ([Ljava/sql/ResultSet;)V’
LANGUAGE JAVA
Vous pouvez ouvrir un curseur sur cette procédure comme sur n'importe
quelle procédure ASA renvoyant des jeux de résultats.
La chaîne (Ljava/sql/ResultSet;)V est une signature de méthode Java, qui
est une représentation compacte, sous forme de caractères, du nombre et du
type des paramètres et de la valeur renvoyée.
123

Fonctionnalités spéciales des classes Java dans la base de données
124
$ Pour plus d'informations sur les signatures des méthodes Java, reportezvous
à la section "Instruction CREATE PROCEDURE", page 321 du
document ASA Manuel de référence SQL.
Renvoi de valeurs de Java via des procédures stockées
Vous pouvez utiliser les procédures stockées créées à l'aide du paramètre
EXTERNAL NAME LANGUAGE JAVA pour encapsuler des méthodes
Java. Cette section explique comment écrire votre méthode Java pour qu'elle
exploite les paramètres OUT ou INOUT dans la procédure stockée.
Java ne supporte pas explicitement les paramètres INOUT ou OUT.
Cependant, vous pouvez utiliser un tableau de ce paramètre. Par exemple,
pour utiliser un paramètre OUT entier, créez un tableau d'un entier
exactement, en procédant comme suit :
public class TestClass {
public static boolean testOut( int[] param ){
param[0] = 123;
return true;
}
}
La procédure suivante utilise la méthode testOut :
CREATE PROCEDURE sp_testOut ( OUT p INTEGER )
EXTERNAL NAME ’TestClass/testOut ([I)Z’
LANGUAGE JAVA
La chaîne ([I)Z est une signature de méthode Java qui indique que la
méthode ne comporte qu'un seul paramètre, qui est un tableau d'entiers, et
renvoie une valeur booléenne. Vous devez définir la méthode de telle
manière que le paramètre OUT ou INOUT à utiliser soit un tableau de type
Java correspondant au type de données SQL du paramètre OUT ou INOUT.
$ Pour plus d'informations sur la syntaxe à utiliser ainsi que la signature
de méthode, reportez-vous à la section "Instruction CREATE
PROCEDURE", page 321 du document ASA Manuel de référence SQL.
$ Pour plus d'informations, reportez-vous à la section "Conversions entre
types de données Java et SQL", page 91 du document ASA Manuel de
référence SQL.

Gestion de la sécurité pour Java
Le gestionnaire de
sécurité par défaut
Contrôle des E/S
de fichiers Java à
l'aide du
gestionnaire de
sécurité par défaut
Chapitre 4 Utilisation de Java dans la base de données
Java dispose de gestionnaires de sécurité qui permettent de contrôler l'accès
des utilisateurs à des fonctionnalités d'application sensibles en termes de
sécurité, notamment l'accès aux fichiers et au réseau. Adaptive Server
Anywhere offre le support suivant pour les gestionnaires de sécurité Java
dans la base de données :
♦ Adaptive Server Anywhere est doté d'un gestionnaire de sécurité par
défaut.
♦ Vous pouvez intégrer votre propre gestionnaire de sécurité.
$ Pour plus d'informations, reportez-vous à la section "Mise en
oeuvre de votre propre gestionnaire de sécurité", page 126.
Le gestionnaire de sécurité par défaut est la classe
com.sybase.asa.jrt.SAGenericSecurityManager. Il exécute les tâches
suivantes :
1 Vérification de la valeur de l'option de base de données
JAVA_INPUT_OUTPUT.
2 Vérification du serveur de base de données pour voir s'il a été démarré
en mode de sécurité C2 à l'aide de l'option du serveur de base de
données -sc.
3 Interdiction d'utilisation des fonctionnalités d'E/S de fichiers Java si la
propriété de connexion est définie avec la valeur OFF.
4 Interdiction d'accès aux packages java.net si le serveur de base de
données fonctionne avec le mode de sécurité C2.
5 Lorsque le gestionnaire de sécurité empêche un utilisateur d'accéder à
une fonctionnalité, il renvoie java.lang.SecurityException.
$ Pour plus d'informations, reportez-vous aux sections "Option
JAVA_INPUT_OUTPUT", page 629 du document ASA Guide
d’administration et "Option de serveur -sc", page 162 du document ASA
Guide d’administration.
Le contrôle des E/S de fichiers Java est effectué par l'intermédiaire de
l'option de base de données JAVA_INPUT_OUTPUT. Par défaut, cette
option est définie avec la valeur OFF, rendant ainsi les E/S de fichier
impossibles.
v Pour autoriser l'accès aux fichiers à l'aide du gestionnaire de
sécurité par défaut :
♦ Affectez à l'option JAVA_INPUT_OUTPUT la valeur ON :
SET OPTION JAVA_INPUT_OUTOUT=’ON’
125

Fonctionnalités spéciales des classes Java dans la base de données
Mise en oeuvre de votre propre gestionnaire de sécurité
Exemple
126
Pour mettre en oeuvre votre propre gestionnaire de sécurité, vous devez
exécuter plusieurs étapes.
v Pour définir votre propre gestionnaire de sécurité :
1 Mettez en oeuvre une classe qui étend java.lang.SecurityManager.
La classe SecurityManager comporte plusieurs méthodes qui permettent
de vérifier si une action particulière est autorisée. Si l'action est
autorisée, la méthode renvoie une valeur en mode non détaillé. Si la
méthode renvoie une valeur, une exception SecurityException est
déclenchée.
Vous devez remplacer les méthodes qui régissent les actions que vous
souhaitez autoriser par des méthodes qui renvoient une valeur en mode
non détaillé. Cette opération peut être effectuée en mettant en oeuvre la
méthode public void.
2 Affectez votre gestionnaire de sécurité aux utilisateurs appropriés.
Pour affecter des gestionnaires de sécurité à un utilisateur, utilisez les
procédures stockées système add_user_security_manager,
update_user_security_manager et delete_user_security_manager. Par
exemple, pour affecter la classe MonGestionnaireSécurité en tant que
gestionnaire de sécurité pour un utilisateur, exécutez la commande
suivante :
call dbo.add_user_security_manager(
nom_utilisateur, 'MonGestionnaireSécurité', NULL )
La classe suivante autorise la lecture de fichiers mais interdit l'écriture :
public class MonGestionnaireSécurité extends
SecurityManager
{ public void checkRead(FileDescriptor) {}
public void checkRead(String) {}
public void checkRead(String, Object) {}
}
Les méthodes SecurityManager.checkWrite ne sont pas remplacées et
empêchent toute opération d'écriture sur les fichiers. Les méthodes
checkRead renvoient une valeur, en mode non détaillé, autorisant ainsi
l'action.

Stockage des objets Java
Remarques
Chapitre 4 Utilisation de Java dans la base de données
Les valeurs Java sont stockées de façon sérialisée. Cela signifie que chaque
ligne inclut les informations suivantes :
♦ un identificateur de version,
♦ un identificateur de la classe (ou de la sous-classe) enregistrée,
♦ les valeurs de champs non statiques et non transitoires de la classe,
♦ des informations sur l'overhead.
La définition de classe n’est pas enregistrée pour chaque ligne.
L'identificateur fournit une référence de définition de classe unique.
Vous pouvez utiliser des objets Java sans connaître précisément leur
fonctionnement, mais leur mode de stockage a une incidence sur les
performances. C'est pourquoi nous vous donnons les quelques informations
qui suivent.
♦ Espace disque L'overhead par ligne varie entre 10 et 15 octets. Si la
classe intègre une seule variable, le stockage requis par l'overhead peut
être identique à celui requis par la variable. En revanche, si la classe
intègre plusieurs variables, l'overhead est négligeable.
♦ Performances Chaque fois qu'une valeur Java est insérée ou mise à
jour, elle doit être sérialisée par la machine virtuelle Java. De même,
chaque fois qu'une valeur Java est utilisée dans une requête, elle doit être
désérialisée par la machine virtuelle. Cela risque d'affecter
considérablement les performances.
Pour éviter cela, utilisez des colonnes calculées.
♦ Index L'utilisation d'index sur des colonnes Java n'est pas très sélective
et n'offre pas les avantages associés aux index appliqués à des données
SQL simples.
♦ Sérialisation Si une classe comprend une méthode readObject ou
writeObject, celles-ci sont appelées lors de la sérialisation ou
désérialisation de l'instance. L'utilisation d'une méthode readObject ou
writeObject peut influer sur les performances, car là encore la machine
virtuelle Java est appelée.
127

Stockage des objets Java
Objets Java et versions de classe
Accès aux lignes
lors de la mise à
jour d'une classe
Objets
inaccessibles
128
Les objets Java enregistrés dans la base de données sont persistant, c'est-àdire
qu'ils existent même si aucun code n'est exécuté. Vous pouvez ainsi
effectuer les actions suivantes :
1 Installer une classe.
2 Créer une table en utilisant cette classe comme type de données pour une
colonne.
3 Insérer des lignes dans la table.
4 Installer une nouvelle version de la classe.
Mais comment utiliser les lignes existantes dans la nouvelle version de la
classe ?
Adaptive Server Anywhere offre des fonctionnalités de gestion de version de
classe qui assurent la compatibilité entre les nouvelles et les anciennes
classes. Les règles d'accès aux anciennes valeurs sont les suivantes :
♦ Si l'ancienne version de la classe comportait un champ sérialisable, mais
que la nouvelle version n'en comporte aucun ou en comporte un non
sérialisable, ce champ est ignoré.
♦ Si la nouvelle version de la classe comporte un champ sérialisable, mais
que l'ancienne version n'en comportait aucun ou en comportait un non
sérialisable, ce champ est réinitialisé à sa valeur par défaut. La valeur
par défaut est NULL (0) pour les types primitifs, FALSE pour les
valeurs booléennes et NULL pour les références d'objets.
♦ Si l'ancienne version incluait une superclasse, mais que la nouvelle n'en
inclut aucune, les données de celle-ci sont ignorées.
♦ Si la nouvelle version inclut une superclasse, mais que l'ancienne n'en
comportait aucune, les données de celle-ci sont réinitialisées à leurs
valeurs par défaut.
♦ Si le type de champ sérialisable est différent d'une version à l'autre, ce
champ est réinitialisé sur les paramètres par défaut. Les conversions de
types ne sont pas supportées, conformément à la sérialisation Sun
Microsystems.
Un objet sérialisé est inaccessible si sa classe ou n'importe laquelle de ses
superclasses a été supprimée de la base de données, quel que soit le moment
de cette suppression. Ce comportement est conforme à la sérialisation Sun
Microsystems.

Déplacement
d'objets entre
bases de données
Utilisation de la
nouvelle classe
Chapitre 4 Utilisation de Java dans la base de données
Le transfert d'objets d'une base de données à une autre est possible, même si
les versions de classe diffèrent. Le transfert entre bases de données suit les
règles suivantes :
♦ Les objets sont répliqués dans une base de données distante.
♦ Une table d'objets est déchargée puis rechargée dans une autre base.
♦ Un fichier journal contenant les objets est converti puis appliqué à une
autre base.
La première fois qu'une classe est utilisée, chaque machine virtuelle de la
connexion charge sa définition.
Lorsque vous installez (INSTALL) une classe, la machine virtuelle de la
connexion est automatiquement redémarrée. De ce fait, vous avez
immédiatement accès à la nouvelle classe.
Pour les autres connexions, la nouvelle classe est chargée lorsque la machine
virtuelle accède à la classe pour la première fois. Si celle-ci est déjà chargée
par une machine virtuelle, la nouvelle classe n'apparaît pour la connexion
correspondante que lorsque la machine virtuelle est redémarrée (par
exemple, à l'aide d'un STOP JAVA et START JAVA).
129

Conception d'une base de données Java
Conception d'une base de données Java
130
La conception des bases de données relationnelles fait l'objet d'une multitude
d'informations théoriques et pratiques. Pour plus d'informations sur la
modélisation Entité/Relation et d'autres approches, consultez la
documentation d'introduction au sujet (reportez-vous à la section
"Conception d'une base de données", page 3 du document ASA Guide de
l’utilisateur SQL) ou des manuels plus avancés.
Aucun corpus comparable, théorique et pratique à la fois, sur le
développement des bases de données relationnelles orientées objet n'existe,
et il en est de même pour les bases relationnelles orientées Java. Nous nous
contenterons donc ici de proposer des suggestions d'utilisation de Java dans
le but d'optimiser l'utilisation des bases de données relationnelles.
Entités et attributs dans un schéma relationnel et orienté objet
Dans la conception de bases de données relationnelles, chaque table décrit
une entité. Ainsi, la base de données exemple comporte les tables Employee,
Customer, Sales_order et Department. Les attributs de ces entités constituent
les colonnes de ces tables : adresse des employés, numéro d'identification des
clients, date des bons de commande, etc. Chaque ligne de la table peut être
considérée comme une instance distincte de l'entité : employé, bon de
commande ou département spécifique.
Dans la programmation orientée objet, chaque classe décrit une entité, les
méthodes et les champs de cette classe décrivant les attributs de l'entité.
Chaque instance de la classe (chaque objet) conserve une instance distincte
de l'entité.
Il peut sembler moins naturel, de ce fait, que les colonnes relationnelles
soient basées sur les classes Java. Une correspondance plus naturelle semble
associer la table et la classe.
Entités et attributs dans la pratique
La distinction entre entité et attribut paraît simple, mais la pratique montre
qu'elle n'est pas toujours aussi évidente.
♦ Une adresse peut être considérée comme l'attribut d'un client. Or, une
adresse est également une entité, qui possède ses propres attributs
comme la rue, la ville, etc.

Chapitre 4 Utilisation de Java dans la base de données
♦ De même, un prix peut être considéré comme l'attribut d'un produit.
Toutefois, c'est également une entité qui comprend les attributs montant
et monnaie.
L'utilité de la base de données relationnelle objet provient justement du fait
qu'il existe deux manières d'exprimer des entités. Vous pouvez, d'une part,
exprimer des entités en tant que tables et, d'autre part, en tant que classes
d'une table. La section suivante illustre ce propos.
Restrictions associées aux bases de données relationnelles
Prenons, par exemple, le cas d’une compagnie d’assurance qui souhaite faire
le suivi de ses clients. Un client pouvant être considéré comme une entité, il
serait logique de ne créer qu'une seule table qui regrouperait tous les clients
de la société.
Toutefois, la clientèle des compagnies d'assurance est variée : assurés,
bénéficiaires ou responsables du paiement des primes. Pour chacun d'entre
eux, la compagnie d'assurance a besoin d'informations spécifiques. Par
exemple, l'adresse suffit pour les bénéficiaires. Par contre, il est utile de
connaître les antécédents médicaux des assurés. Enfin, des informations
financières peuvent être requises pour le client payant les primes.
Aussi, faut-il mieux gérer séparément ces différents types de clients et les
considérer comme des entités distinctes ou considérer le type de client
comme un attribut du client ? Les deux solutions ont leurs limites :
♦ Le fait de créer des tables distinctes pour chaque type de client risque de
générer une base de données très complexe et d'imposer des requêtes
multitables si tous les clients sont concernés.
♦ Mais, d'un autre côté, si vous n'utilisez qu'une seule table, il est difficile
de contrôler l'exactitude des informations pour chaque client. En effet,
certaines colonnes n'étant requises que pour certains clients, autoriser
des valeurs NULL permet l'entrée correcte des données, mais ne l'assure
pas. Il n'existe donc aucun moyen simple, dans la base de données, de
limiter le comportement par défaut à un attribut d'une nouvelle entrée.
Utilisation des classes pour pallier les restrictions des bases de
données relationnelles
Vous pouvez choisir de n’utiliser qu’une table de clients et de n’utiliser que
certaines colonnes avec les classes Java pour pallier les restrictions associées
aux bases de données relationnelles.
131

Conception d'une base de données Java
132
Supposons, par exemple, que des informations différentes sur les contacts
soient requises pour les assurés et les bénéficiaires. Une approche possible
est de définir une colonne fondée sur une classe ContactInformation.
Définissez ensuite les sous-classes HolderContactInformation et
BeneficiaryContactInformation de la classe ContactInformation. Les
nouveaux clients étant entrés par type, vous êtes ainsi certain que les
informations correctes sont spécifiées.
Niveaux d'abstraction des données relationnelles
Les données d'une base de données relationnelle peuvent être regroupées en
fonction de leur objet. Quelles sont les données appartenant à la classe Java
et quelles sont celles qui sont le mieux adaptées aux colonnes de types de
données simples ?
♦ Colonne d'intégrité référentielle Les colonnes de clés primaires et
étrangères incluent généralement des numéros d'identification. Ces
numéros peuvent être appelés données référentielles car leur principal
objectif est de définir la structure de la base de données et la relation
entre les tables.
En général, les données référentielles n'appartiennent pas aux classes
Java. Il est recommandé d'utiliser des entiers et autres types de données
simples. Toutefois il est possible de transformer une colonne de classe
Java en une colonne de clé primaire.
♦ Données indexées Les colonnes généralement indexées peuvent ne pas
faire partie d'une classe Java. Toutefois, la séparation entre les données
indexées et les données non indexées est mal définie.
Grâce aux colonnes calculées, vous pouvez indexer de manière sélective
un champ Java ou une méthode (ou, plutôt, d'autres expressions). Si
vous définissez une colonne de classe Java, puis que vous choisissez
d'indexer un champ ou une méthode de cette colonne, utilisez des
colonnes calculées pour créer une nouvelle colonne à partir de ce champ
ou de cette méthode.
$ Pour plus d'informations, reportez-vous à la section "Utilisation de
colonnes calculées avec les classes Java", page 134.
♦ Données descriptives Les données des colonnes sont souvent des
données descriptives. Utilisées à des fins d'intégrité référentielle, elles
sont rarement indexées, mais souvent utilisées dans les requêtes. Pour
une table d'employés, elles peuvent contenir des informations telles que
la date d'embauche, l'adresse, des informations sur les primes, le salaire,
etc. Il est souvent intéressant de combiner ces données dans un plus petit
nombre de colonnes de type de données de classe Java.

Chapitre 4 Utilisation de Java dans la base de données
Les classes permettent l'abstraction à un niveau compris entre la colonne
relationnelle simple et la table relationnelle.
133

Utilisation de colonnes calculées avec les classes Java
Utilisation de colonnes calculées avec les
classes Java
Utilisation des
colonnes calculées
134
La fonction de colonnes calculées simplifie la conception d'une base de
données Java, facilite l'utilisation des fonctions Java dans les bases de
données existantes et améliore les performances des types de données Java.
Les valeurs d'une colonne calculée proviennent d'autres colonnes. Vous ne
pouvez pas insérer (INSERT) ni mettre à jour (UPDATE) les valeurs de ces
colonnes. Toutefois, toute tentative de mise à jour d'une colonne calculée
déclenche les triggers associés à cette colonne.
Définition des colonnes calculées
Création de tables
avec des colonnes
calculées
Ajout de colonnes
calculées dans des
tables
Utilisées avec les classes Java, les colonnes calculées permettent :
♦ D’exploiter une colonne Java Si vous créez une colonne à l'aide d'un
type de données de classe Java, utilisez les colonnes calculées pour
indexer l'un des champs de la classe. Vous pouvez ajouter une colonne
calculée comportant la valeur d'un champ et indexer ce dernier.
♦ D’ajouter une colonne Java dans une table relationnelle Pour utiliser
certaines fonctions des classes Java en modifiant le moins possible une
base de données existante, ajoutez une colonne Java calculée, dont les
valeurs seront extraites des autres colonnes de la table.
Les colonnes calculées sont déclarées dans l'instruction CREATE TABLE ou
ALTER TABLE.
L'instruction CREATE TABLE suivante permet de créer la table product
dans les tables exemple Java.
CREATE TABLE product
(
id INTEGER NOT NULL,
JProd asademo.Product NOT NULL,
name CHAR(15) COMPUTE ( JProd>>name ),
PRIMARY KEY ("id")
)
L'instruction suivante permet d'ajouter dans la table product une nouvelle
colonne calculée :
ALTER TABLE product
ADD inventory_Value INTEGER
COMPUTE ( JProd.quantity * JProd.unit_price )

Modification de
l’expression pour
les colonnes
calculées
Chapitre 4 Utilisation de Java dans la base de données
Vous pouvez changer l'expression utilisée dans une colonne calculée, à l'aide
de l'instruction ALTER TABLE. L'instruction suivante change l'expression
sur laquelle s'appuie une colonne calculée :
ALTER TABLE nom_table
ALTER nom_colonne SET COMPUTE ( expression )
La colonne est recalculée lors de l'exécution de l'instruction. Si la nouvelle
expression n'est pas correcte, l'instruction ALTER TABLE échoue.
L'instruction suivante rétablit une colonne calculée dans son état de colonne
normale.
ALTER TABLE nom_table
ALTER nom_colonne DROP COMPUTE
Lorsque cette instruction est exécutée, les valeurs de la colonne ne sont pas
modifiées.
Insertion et mise à jour de colonnes calculées
Les colonnes calculées ont une incidence sur les instructions INSERT et
UPDATE valides. La table jdba.product dans les tables exemple Java
possède une colonne calculée (name) que nous utiliserons pour cet exemple.
La définition de la table se présente comme suit :
CREATE TABLE "jdba"."product"
(
"id" INTEGER NOT NULL,
"JProd" asademo.Product NOT NULL,
"name" CHAR(15) COMPUTE( JProd.name ),
PRIMARY KEY ("id")
)
♦ Pas d'insertions ni de mises à jour directes Vous ne pouvez pas
insérer directement une valeur dans une colonne calculée. L'instruction
suivante échoue et renvoie l'erreur Une colonne d’insertion existe en
double :
-- Instruction incorrecte
INSERT INTO PRODUCT (id, name)
VALUES( 3006, 'instruction insert erronée' )
De même, une instruction UPDATE ne peut pas mettre à jour
directement une colonne calculée.
♦ Liste des noms de colonne Vous devez toujours spécifier les noms de
colonne dans les instructions INSERT appliquées à des tables
comportant des colonnes calculées. L'instruction suivante échoue avec
une erreur Le nombre de valeurs spécifiées pour INSERT est erroné :
135

Utilisation de colonnes calculées avec les classes Java
136
-- Instruction incorrecte
INSERT INTO PRODUCT
VALUES( 3007,new asademo.Product() )
Vous devez plutôt indiquer la liste des colonnes, comme suit :
INSERT INTO PRODUCT( id, JProd )
VALUES( 3007,new asademo.Product() )
♦ Triggers Vous pouvez définir des triggers sur une colonne calculée :
toute instruction INSERT ou UPDATE portant sur la colonne
déclenchera le trigger.
A quel moment les colonnes calculées sont recalculées
Les colonnes calculées sont recalculées dans les cas suivants :
♦ Une colonne est supprimée, ajoutée ou renommée.
♦ La table est renommée.
♦ Le type de données ou la clause COMPUTE d'une colonne est
modifié(e).
♦ Une ligne est insérée.
♦ Une ligne est mise à jour.
Les colonnes calculées ne sont pas recalculées sur requête. Si vous utilisez
une expression conditionnée par l'heure ou par l'état de la base de données, la
colonne calculée peut renvoyer un résultat incorrect.

Chapitre 4 Utilisation de Java dans la base de données
Configuration de la mémoire pour Java
Configuration
requise par base
de données et par
connexion
Utilisation de la mémoire
Cette section décrit comment configurer la mémoire pour exécuter Java dans
la base de données et configurer de manière appropriée votre serveur.
La mémoire virtuelle Java requiert une quantité de mémoire cache
importante.
$ Pour plus d'informations sur l'optimisation du cache, reportez-vous à la
section "Utilisation du cache pour améliorer les performances", page 162 du
document ASA Guide de l’utilisateur SQL.
La mémoire requise par la machine virtuelle Java est allouée par base de
données et par connexion.
♦ Les conditions par base de données ne sont pas transférables : elles ne
peuvent pas être paginées vers le disque. Elles doivent donc tenir dans le
cache du serveur. Ce type de mémoire est réservé aux bases de données,
et non au serveur. Pour estimer le cache requis, additionnez la mémoire
requise pour chaque base de données exécutée sur le serveur.
♦ En revanche, la mémoire requise par connexion est transférable, mais
uniquement en tant qu'unité. Elle peut entièrement résider dans le cache
ou dans un fichier temporaire.
La mémoire requise par Java dans les bases de données est utilisée de
différentes manières :
♦ Lorsque vous utilisez Java pour la première fois sur un serveur actif, la
machine virtuelle est chargée dans la mémoire et requiert près de 1,5 Mo
de mémoire. La mémoire utilisée ici fait partie de celle réservée à
l'ensemble de la base. Une machine virtuelle est chargée pour chaque
base de données exploitant Java.
♦ Une nouvelle instance de la machine virtuelle est chargée pour chaque
connexion utilisant Java. La nouvelle instance requiert près de 200 ko
par connexion.
♦ Chaque définition de classe utilisée dans une application Java est
chargée en mémoire. Ce chargement s'opère dans la mémoire de la base
de données : aucune instance distincte n'est requise pour les connexions
individuelles.
137

Configuration de la mémoire pour Java
Gestion de la
mémoire
Démarrage et arrêt
de la machine
virtuelle
138
♦ Toutes les connexions requièrent un ensemble de variables Java
opérationnelles et de l'espace dans les piles d'applications (notamment
pour les arguments de méthode, etc.).
Pour gérer la mémoire, utilisez l'une des méthodes suivantes :
♦ Définissez la taille du cache total Vous devez définir un cache
suffisamment grand pour remplir les conditions requises par la mémoire
non transférable.
La taille du cache est définie au démarrage du serveur, à l'aide de
l'option de ligne de commande -c.
Le plus souvent, un cache de 8 Mo est suffisant.
♦ Définissez la taille du namespace Il s’agit de la taille maximale, en
octets, de l'allocation de mémoire par base de données.
Pour la définir, utilisez l'option JAVA_NAMESPACE_SIZE. Cette
option est globale et ne peut être définie que par un utilisateur détenant
les droits DBA.
♦ Définissez la taille des segments de mémoire L’option
JAVA_HEAP_SIZE définit la taille maximale, en octets, de la mémoire
par connexion.
Vous pouvez la définir pour chaque connexion mais, dans ce cas, vous
devez détenir les droits DBA car cette option modifie la mémoire
disponible pour les autres utilisateurs.
Vous pouvez non seulement configurer la mémoire pour Java, mais aussi
décharger la machine virtuelle lorsque vous n'utilisez pas Java, à l'aide de
l'instruction STOP JAVA. Seul un utilisateur détenant les droits DBA peut
exécuter cette instruction. Sa syntaxe est la suivante :
STOP JAVA
La machine virtuelle est chargée chaque fois qu'une opération Java est
exécutée. Pour la charger explicitement en vue de l'exécution d'opération
Java, entrez l'instruction suivante :
START JAVA

CHAPITRE 5
Accès aux données via JDBC
Présentation
Sommaire
Ce chapitre décrit comment accéder aux données via JDBC.
JDBC peut être utilisé aussi bien à partir des applications clientes que depuis
la base de données. En matière d'intégration de la logique de programmation
dans la base de données, les classes Java utilisant JDBC remplacent
avantageusement les procédures stockées SQL.
Sujet Page
Présentation de JBDC 140
Utilisation du gestionnaire JDBC jConnect 147
Utilisation de la passerelle JDBC-ODBC 152
Etablissement de connexions JDBC 154
Utilisation de JDBC pour accéder aux données 162
Création d'applications distribuées 171
139

Présentation de JBDC
Présentation de JBDC
JDBC et Adaptive
Server Anywhere
Ressources JDBC
140
JDBC offre une interface SQL aux applications Java. Pour accéder à des
données relationnelles à partir de Java, vous utilisez des appels JDBC.
Ce chapitre n'a pas l'ambition d'être un guide complet de l'interface de la base
de données JDBC. Il se contente de proposer quelques exemples simples
pour présenter JDBC et montrer comment l'utiliser sur le client et au sein de
la base de données.
$ Les exemples illustrent les caractéristiques spécifiques de l'utilisation
de JDBC dans Adaptive Server Anywhere. Pour plus d'informations sur la
programmation JDBC, reportez-vous à un manuel de programmation JDBC.
Vous pouvez utiliser JDBC avec Adaptive Server Anywhere dans les
conditions suivantes :
♦ JDBC sur le client Les applications clientes Java peuvent effectuer des
appels JDBC sur Adaptive Server Anywhere. La connexion est établie
par le biais d'un pilote JDBC. SQL Anywhere Studio fournit deux
pilotes JDBC: le pilote jConnect pour les applications Java pures et une
passerelle JDBC-ODBC.
Dans ce chapitre, l'expression application cliente concerne à la fois les
applications exécutées sur la machine d'un utilisateur et la logique
exécutée sur un serveur applicatif de niveau intermédiaire.
♦ JDBC dans la base de données Les classes Java installées dans une
base de données peuvent effectuer des appels JDBC pour accéder aux
données d'une base et les modifier par le biais d'un gestionnaire JDBC
interne.
♦ Logiciel requis Pour utiliser le gestionnaire jConnect de Sybase,
TCP/IP est nécessaire.
Selon votre installation Adaptive Server Anywhere, vous disposez peutêtre
déjà du gestionnaire jConnect de Sybase.
$ Pour plus d'informations sur le gestionnaire jConnect et son
emplacement, reportez-vous à la section "Fichiers du gestionnaire
jConnect", page 147.
♦ Exemples de code source Vous trouverez le code source
correspondant aux exemples de ce chapitre dans le fichier
Samples\ASA\Java\JDBCExamples.java du répertoire SQL Anywhere.
$ Pour plus d'informations sur l'installation des exemples Java, y
compris la classe JDBCExamples, reportez-vous à la section
"Installation des exemples Java", page 92.

Choix d’un pilote JDBC
Structure du programme JDBC
Chapitre 5 Accès aux données via JDBC
Deux pilotes JDBC sont fournis pour Adaptive Server Anywhere:
♦ jConnect Il s’agit d’un pilote 100% pur Java . Il communique avec
Adaptive Server Anywhere en utilisant le protocole client/serveur TDS.
♦ passerelle JDBC-ODBC Ce pilote communique avec Adaptive Server
Anywhere en utilisant le protocole client/serveur Command Sequence.
Son comportement est conforme à ODBC, embedded SQL, et autres
applications OLE DB.
Lorsque vous choisissez le pilote à utiliser, pensez à prendre en considération
les facteurs suivants:
♦ Fonctions Les deux pilotes sont conformes à JDK 2. La passerelle
JDBC-ODBC fournit des curseurs avec défilement complet, qui ne sont
pas disponibles dans jConnect.
♦ Java pur Le pilote jConnect est une solution Java pure. La passerelle
JDBC-ODBC requiert le pilote ODBC d'Adaptive Server Anywhere
ODBC et n'est pas une solution Java pure.
♦ Performances La passerelle JDBC-ODBC garantit dans la plupart des
cas de meilleures performances que le pilote jConnect.
♦ Compatibilité Le protocole TDS, utilisé par le pilote jConnect, est
partagé avec Adaptive Server Enterprise. Certains aspects du
comportement du pilote dépendent de ce protocole, et sont configurés
pour être compatibles avec Adaptive Server Enterprise.
Les deux pilotes sont disponibles pour Windows 95/98/Me et Windows
NT/2000/XP, ainsi que pour les systèmes d'exploitation UNIX et Linux
supportés. Ils ne sont disponibles ni pour NetWare, ni pour Windows CE.
La séquence d'événements ci-après est typique d'une application JDBC :
1 Création d'un objet Connection L'appel d'une méthode de classe
getConnection de la classe DriverManager crée un objet Connection
et établit une connexion avec une base de données.
2 Génération d'un objet Statement L’objet Connection génère un objet
Statement.
141

Présentation de JBDC
142
3 Transmission d’une instruction SQL Une instruction SQL exécutée
dans l'environnement de la base de données est transmise à l'objet
Statement. Si l'instruction est une requête, l'action renvoie un objet
ResultSet .
L'objet ResultSet, qui contient les données renvoyées après exécution de
l'instruction SQL, présente celles-ci ligne par ligne (selon un
fonctionnement comparable à celui du curseur).
4 Bouclage sur les lignes du jeu de résultats La méthode next de
l'objet ResultSet exécute deux actions :
♦ Avance d'une ligne la ligne courante (celle présentée via l'objet
ResultSet ).
♦ Renvoie une valeur booléenne (vrai/faux) indiquant la présence, ou
non, d'une ligne suivante.
5 Récupération des valeurs de chaque ligne Les valeurs de chaque
colonne de l’objet ResultSet sont récupérées, par identification du nom
ou de la position de la colonne. La méthode getDate permet ainsi
d'obtenir la valeur d'une colonne de la ligne en cours.
Les objets Java peuvent utiliser les objets JDBC pour interagir avec une base
de données et obtenir ainsi des données qu'ils peuvent ensuite manipuler ou
utiliser dans d'autres requêtes.
Fonctionnalités JDBC dans la base de données
La version de JDBC que vous utilisez à partir de Java dans la base de
données est déterminée par la version du JDK pour lequel la base de données
est configurée.
♦ Si votre base de données est initialisée avec JDK 1.2 ou JDK 1.3, vous
pouvez utiliser l'API JDBC 2.0.
$ Pour plus d'informations sur la mise à niveau d'une base de
données vers JDK 1.2 ou JDK 1.3, reportez-vous à la section
"Instruction ALTER DATABASE", page 216 du document ASA Manuel
de référence SQL ou "Mise à niveau d'une base de données à l'aide de
l'utilitaire dbupgrad", page 569 du document ASA Guide
d’administration.
♦ Si votre base de données est initialisée avec JDK 1.1, vous pouvez
utiliser les fonctionnalités de JDBC 1.2. Le gestionnaire JDBC interne
pour JDK 1.1 (asajdbc) fournit aux applications Java côté serveur
certaines fonctionnalités de JDBC 2.0 mais il n'offre pas un support total
de JDBC 2.0.

Chapitre 5 Accès aux données via JDBC
$ Pour plus d'informations, reportez-vous à la section "Utilisation des
fonctionnalités JDBC 2.0 à partir de bases de données JDK 1.1",
page 143.
Utilisation des fonctionnalités JDBC 2.0 à partir de bases de données JDK 1.1
Cette section explique comment accéder aux fonctionnalités JDBC 2.0 à
partir de bases de données initialisées avec le support JDK 1.1. Le plus
souvent, la meilleure solution consiste à mettre à niveau Java dans la base de
données vers la version 1.3.
Pour les bases de données initialisées avec le support JDK 1.1, le package
sybase.sql.ASA contient des fonctionnalités qui font partie de JDBC 2.0.
Pour utiliser ces fonctionnalités JDBC 2.0, vous devez convertir vos
objets JDBC en classes correspondantes du package sybase.sql.ASA, au lieu
du package java.sql. Les classes qui sont déclarées dans java.sql sont
limitées aux fonctionnalités de JDBC 1.2.
Les classes du package sybase.sql.ASA sont les suivantes :
Classe JDBC Classe de gestionnaire interne Sybase
java.sql.Connection sybase.sql.ASA.SAConnection
java.sql.Statement sybase.sql.ASA.SAStatement
java.sql.PreparedStatement sybase.sql.ASA.SAPreparedStatement
java.sql.CallableStatement sybase.sql.ASA.SACallableStatement
java.sql.ResultSetMetaData sybase.sql.ASA.SAResultSetMetaData
java.sql.ResultSet sybase.sql.SAResultSet
java.sql.DatabaseMetaData sybase.sql.SADatabaseMetaData
La fonction suivante offre un objet ResultSetMetaData pour une instruction
préparée sans qu'un objet ResultSet ou l'exécution d'une instruction soit
nécessaire. Cette fonction ne fait pas partie du standard JDBC 1.2.
ResultSetMetaData
sybase.sql.ASA.SAPreparedStatement.describe()
Le code suivant permet de lire la ligne précédente dans un jeu de résultats ;
cette fonctionnalité n'est pas supportée dans JDBC 1.2.
import java.sql.*;
import sybase.sql.asa.*;
ResultSet rs;
// code supplémentaire ici
( ( sybase.sql.asa.SAResultSet)rs ).previous();
143

Présentation de JBDC
Restrictions
concernant
JDBC 2.0
144
Les classes suivantes font partie de l’interface basique de JDBC 2.0, mais ne
sont pas disponibles dans le package sybase.sql.ASA :
♦ java.sql.Blob
♦ java.sql.Clob
♦ java.sql.Ref
♦ java.sql.Struct
♦ java.sql.Array
♦ java.sql.Map
Les fonctions basiques JDBC 2.0 suivantes ne sont pas disponibles dans le
package sybase.sql.ASA :

Classe dans
sybase.sql.ASA
Chapitre 5 Accès aux données via JDBC
Fonctions manquantes
SAConnection java.util.Map getTypeMap()
void setTypeMap( java.util.Map map )
SAPreparedStatement void setRef( int pidx, java.sql.Ref r )
void setBlob( int pidx, java.sql.Blob b )
void setClob( int pidx, java.sql.Clob c )
void setArray( int pidx, java.sql.Array a )
SACallableStatement Object getObject( pidx, java.util.Map map )
java.sql.Ref getRef( int pidx )
java.sql.Blob getBlob( int pidx )
java.sql.Clob getClob( int pidx )
java.sql.Array getArray( int pidx )
SAResultSet Object getObject( int cidx, java.util.Map map )
java.sql.Ref getRef( int cidx )
java.sql.Blob getBlob( int cidx )
java.sql.Clob getClob( int cidx )
java.sql.Array getArray( int cidx )
Object getObject( String cName, java.util.Map map )
java.sql.Ref getRef( String cName )
java.sql.Blob getBlob( String cName )
java.sql.Clob getClob( String cName )
java.sql.Array getArray( String cName )
Différences entre les connexions JDBC côté client et côté serveur
La distinction entre JDBC sur le client et JDBC dans le serveur de base de
données porte sur la manière dont s'établissent les connexions avec
l'environnement de la base.
145

Présentation de JBDC
146
♦ Côté client Pour JDBC côté client, l'établissement d'une connexion
requiert le gestionnaire JDBC jConnect de Sybase ou la passerelle
JDBC-ODBC d'Adaptive Server Anywhere. Le passage des arguments à
la méthode DriverManager.getConnection établit la connexion. Du
point de vue de l'application cliente, l'environnement de base de données
est une application externe.
♦ Côté serveur Lorsque JDBC est utilisé à partir du serveur de base de
données, une connexion existe déjà. Une valeur de
jdbc:default:connection est transmise à
DriverManager.getConnection qui autorise alors l'application JDBC à
travailler via la connexion utilisateur en cours. Rapide et efficace, cette
opération est également sûre puisque l'application cliente a déjà rempli
les conditions de sécurité de la base de données pour établir la
connexion. L'ID utilisateur et le mot de passe ont déjà été fournis et il
n'est pas nécessaire de recommencer l'opération. Le gestionnaire JDBC
interne peut se connecter uniquement à la base de données de la
connexion courante.
Vous pouvez écrire des classes JDBC de sorte qu'elles puissent être
exécutées à la fois sur le client et sur le serveur : pour ce faire, utilisez une
seule instruction conditionnelle pour la construction de l'URL. Une
connexion externe requiert le nom de la machine et le numéro de port, tandis
que la connexion interne requiert jdbc:default:connection.

Chapitre 5 Accès aux données via JDBC
Utilisation du gestionnaire JDBC jConnect
Pour utiliser JDBC depuis une application cliente ou une applet, vous devez
vous connecter à Adaptive Server Anywhere via le gestionnaire JDBC
jConnect.
jConnect est fourni avec SQL Anywhere Studio. Si vous avez reçu
Adaptive Server Anywhere en tant qu'élément d'un autre package, vous ne
disposerez pas nécessairement de jConnect. Or, pour utiliser JDBC depuis
des applications clientes, il vous faut jConnect. En revanche, vous pouvez
utiliser JDBC dans la base de données sans jConnect.
Fichiers du gestionnaire jConnect
Définition de la
variable
CLASSPATH pour
jConnect
Le gestionnaire JDBC jConnect est installé dans un ensemble de sousrépertoires
du répertoire Sybase\Shared. Deux versions de jConnect sont
fournies :
♦ jConnect 4.5 Cette version est utilisée pour le développement
d'applications JDK 1.1. jConnect 4.5 est installé dans le répertoire
Sybase\Shared\jConnect-4_5.
jConnect 4.5 est fourni sous la forme d'un ensemble de classes.
♦ jConnect 5.5 Cette version est utilisée pour le développement
d'applications JDK version 1.2 ou ultérieure. jConnect 5.5 est installé
dans le répertoire Sybase\Shared\jConnect-5_5.
jConnect 5.5 est fourni sous la forme d'un fichier JAR nommé
jconn2.jar.
Les exemples de ce chapitre reposent sur l'utilisation de jConnect 5.5. Les
utilisateurs de jConnect 4.5 doivent effectuer les adaptations appropriées.
Pour que votre application utilise jConnect, les classes jConnect doivent
figurer dans la variable d'environnement CLASSPATH lors de la
compilation et de l'exécution afin que le compilateur et l'environnement
d'exécution Java puissent localiser les fichiers requis.
La commande suivante ajoute le gestionnaire jConnect 5.5 dans une variable
d'environnement CLASSPATH existante, où chemin correspond au
répertoire Sybase\Shared.
set classpath=%classpath%;chemin\jConnect-5_5\classes\jconn2.jar
La commande suivante ajoute le gestionnaire jConnect 4.5 dans une variable
d'environnement CLASSPATH existante :
set classpath=%classpath%;chemin\jConnect-4_5\classes
147

Utilisation du gestionnaire JDBC jConnect
Importation des
classes jConnect
148
Les classes de jConnect sont toutes dans le package com.sybase.
Si vous utilisez jConnect 5.5, votre application doit accéder aux classes dans
com.sybase.jdbc2.jdbc. Vous devez importer ces classes au début de chaque
fichier source :
import com.sybase.jdbc2.jdbc.*
Si vous utilisez jConnect 4.5, les classes se trouvent dans com.sybase.jdbc.
Vous devez les importer au début de chaque fichier source :
import com.sybase. jdbc.*
Installation des objets système jConnect dans une base de
données
Si vous envisagez d'accéder aux informations de la table système
(métadonnées de la base) via jConnect, ajoutez tout d'abord les objets
système jConnect à la base.
Par défaut, les objets système jConnect sont ajoutés dans toutes les bases de
données nouvelles. Vous pouvez ajouter les objets jConnect dans la base de
données au moment de sa création, de sa mise à niveau ou ultérieurement.
Vous pouvez installer les objets système jConnect depuis Sybase Central ou
par le biais d'Interactive SQL.
v Pour ajouter des objets système jConnect dans une base de
données à partir de Sybase Central :
1 Connectez-vous à la base sous l'ID d'un utilisateur détenant les droits
DBA.
2 Dans le volet gauche de Sybase Central, cliquez avec le bouton droit sur
l'icône de la base de données et choisissez Installer le support de
métadonnées jConnect dans le menu contextuel.
v Pour ajouter des objets système jConnect dans une base de
données à partir d'Interactive SQL :
♦ Connectez-vous à la base depuis Interactive SQL sous l'ID d'un
utilisateur détenant les droits DBA, puis entrez la commande suivante
dans le volet Instructions SQL :
read chemin\scripts\jcatalog.sql
chemin correspondant au répertoire SQL Anywhere.

Chapitre 5 Accès aux données via JDBC
Conseil
Vous pouvez également utiliser une invite de commandes pour ajouter les
objets système jConnect dans une base de données. A l'invite de
commandes, tapez :
dbisql -c "uid=utilisateur;pwd=mdp"
chemin\scripts\jcatalog.sql
où utilisateur et mdp identifient un utilisateur détenant les droits DBA et
chemin, le répertoire SQL Anywhere.
Chargement du gestionnaire jConnect
Pour pouvoir utiliser jConnect dans votre application, vous devez charger le
gestionnaire en entrant l'instruction suivante :
Class.forName("com.sybase.jdbc2.jdbc.SybDriver").newInstance();
Fourniture d’une URL au serveur
Le fait d'utiliser la méthode newInstance simplifie les choses dans certains
navigateurs.
Pour vous connecter à une base de données via jConnect, vous devez fournir
l'URL (Universal Resource Locator) de la base. La section "Connexion à
partir d'une application JDBC cliente avec jConnect", page 154 donne une
exemple :
StringBuffer temp = new StringBuffer();
// Utilise gestionnaire jConnect...
temp.append("jdbc:sybase:Tds:");
// pour connexion sur nom machine indiqué...
temp.append(_coninfo);
// sur numéro de port par défaut pour ASA...
temp.append(":2638");
// puis connexion.
System.out.println(temp.toString());
conn = DriverManager.getConnection(temp.toString() ,
_props );
L'URL est composée de la manière suivante :
jdbc:sybase:Tds:machine-name:port-number
Les différents composants sont les suivants :
♦ jdbc:sybase:Tds Le gestionnaire JDBC jConnect de Sybase, qui utilise
le protocole d'application TDS.
149

Utilisation du gestionnaire JDBC jConnect
150
♦ machine-name Le nom ou l’adresse IP de la machine sur laquelle le
serveur est exécuté. Pour une connexion entre homologues, vous pouvez
utiliser localhost, qui désigne la machine courante.
♦ port number Le numéro du port sur lequel le serveur de la base de
données est en réception. Le numéro de port affecté à
Adaptive Server Anywhere est le 2638. Si rien ne s'y oppose
spécifiquement, utilisez ce numéro.
La chaîne de connexion ne doit pas comporter plus de 253 caractères.
Spécification d'une base de données sur un serveur
Une ou plusieurs base de données peuvent être simultanément chargées sur
un serveur Adaptive Server Anywhere. L'URL, telle qu'indiquée plus haut,
spécifie un serveur, et non une base de données. La tentative de connexion
est effectuée vers la base de données par défaut sur le serveur.
Vous pouvez spécifier une base de données particulière en indiquant une
forme étendue de l'URL, selon l'une des méthodes ci-après.
Utilisation du
paramètre
ServiceName
Utilisation du
paramètre
RemotePWD
jdbc:sybase:Tds:machine-name:port-number?ServiceName=DBN
Le point d'interrogation suivi d'une série d'affectations est un moyen standard
de fournir des arguments à une URL. La casse de servicename n'est pas
significative, mais il ne doit pas avoir d'espace de part et d'autre du signe =.
Le paramètre DBN est le nom de la base de données.
La méthode la plus courante pour fournir des paramètres de connexion
complémentaires tels que le nom de la base de données ou un fichier de base
de données est d'utiliser le champ RemotePWD. Pour définir RemotePWD
comme champ Properties, utilisez la méthode setRemotePassword().
L'exemple de code ci-dessous montre comment utiliser le champ.
sybDrvr = (SybDriver)Class.forName(
"com.sybase.jdbc2.jdbc.SybDriver" ).newInstance();
props = new Properties();
props.put( "User", "DBA" );
props.put( "Password", "SQL" );
sybDrvr.setRemotePassword(
null, "dbf=asademo.db", props );
Connection con = DriverManager.getConnection(
"jdbc:sybase:Tds:localhost", props );
Via le paramètre de fichier de base de données DBF, vous pouvez lancer une
base de données sur un serveur par le biais de jConnect.. Par défaut, la base
est lancée avec autostop=YES. Si vous spécifiez un DBF ou DBN de
utility_db, la base de données utility est automatiquement lancée.

Chapitre 5 Accès aux données via JDBC
$ Pour plus d'informations, reportez-vous à la section "Utilisation de la
base de données utility", page 241 du document ASA Guide d’administration.
Définition des options de base de données pour les connexions jConnect
Lorsqu'une application se connecte à une base de données en utilisant le
pilote jConnect, il fait appel à deux procédures stockées:
1 sp_tsql_environment définit certaines options de base de données pour
assurer la compatibilité avec le comportement d'Adaptive Server
Enterprise.
2 Puis la procédure spt_mda est appelée, qui définit d'autres options, dont
la procédure spt_mda, qui détermine le paramètrage de
QUOTED_IDENTIFIER. Il est nécessaire de modifier la procédure
spt_mda pour modifier le comportement par défaut.
151

Utilisation de la passerelle JDBC-ODBC
Utilisation de la passerelle JDBC-ODBC
Fichiers requis
Etablissement
d’une connexion
152
La passerelle JDBC-ODBC fournit un pilote JDBC qui, comparé au pilote
JDBC jConnect Java pur, offre certains avantages en termes de fonctions et
de performances, mais qui n'est pas une solution Java pure.
$ Pour obtenir des informations sur le choix du pilote JDBC à utiliser,
reportez-vous à la rubrique "Choix d'un pilote JDBC", page 141.
Le composant Java de la passerelle JDBC-ODBC est inclus dans le fichier
jodbc.jar, installé dans le sous-répertoire Java du répertoire d'installation de
SQL Anywhere. Pour Windows, le composant natif est dbjodbc8.dll, dans le
sous-répertoire win32 du répertoire d'installation de SQL Anywhere. Pour
UNIX et Linux, le composant natif est dbjodbc8.so. Ce composant doit se
trouver dans le chemin d'accès système. Lorsque des applications utilisant ce
pilote sont déployées, vous devez également déployer les fichiers du pilote
ODBC.
Le code suivant illustre la façon d'établir une connexion en utilisant la
passerelle JDBC-ODBC:
String driver, url;
Connection conn;
driver="ianywhere.ml.jdbcodbc.IDriver";
url = "jdbc:odbc:dsn=ASA 8.0 Sample";
Class.forName( driver );
conn = DriverManager.getConnection( url );
Il y a différents points à noter concernant ce code:
♦ Etant donné que les classes sont chargées à l'aide de Class.forName, il
n'est pas nécessaire que le package contenant la passerelle JDBC-ODBC
soit importé en suivant les instructions import.
♦ jodbc.jar doit se trouver dans le chemin d'accès aux classes lorsque vous
lancez l'application.
♦ L'URL contient jdbc:odbc:, suivi d'une chaîne de connexion ODBC
standard. La chaîne de connexion est en général une source de données
ODBC, mais vous pouvez également utiliser des paramètres de
connexion explicitement séparés par des points-virgules en complément
ou à la place de la source de données. Pour plus d'informations sur les
paramètres pouvant être utilisés dans une chaîne de connexion, reportezvous
à la rubrique "Paramètres de connexion", page 75 du document
ASA Guide d’administration.
Si vous n'utilisez pas de source de données, il est nécessaire de spécifier
le pilote ODBC à utiliser en incluant le paramètre du pilote dans votre
chaîne de connexion:

Jeux de caractères
Chapitre 5 Accès aux données via JDBC
url = "jdbc:odbc:";
url += "driver=Adaptive Server Anywhere 8.0;...";
Sous UNIX, la passerelle JDBC-ODBC n’utilise pas d’appels ou de liaisons
unicode ODBC, et n'effectue pas de conversions de caractères. L'envoi de
données non ASCII par le biais de la passerelle a pour effet de détruire les
données.
Sous Windows, la passerelle JDBC-ODBC utilise les appels et les liaisons
unicode ODBC pour convertir entre eux les jeux de caractères.
153

Etablissement de connexions JDBC
Etablissement de connexions JDBC
154
Cette section présente les classes permettant d'établir une connexion JDBC à
une base de données depuis une application Java. Dans les exemples sont
utilisés soit jConnect (côté client), soit Java dans la base de données (côté
serveur). Pour des informations sur l'établissement de connexions par le biais
de la passerelle JDBC-ODBC, reportez-vous à la rubrique "Utilisation de la
passerelle JDBC-ODBC", page 152.
Connexion à partir d'une application JDBC cliente avec jConnect
Code de l’exemple de connexion externe
Pour accéder aux tables système d'une base de données (c'est-à-dire à ses
métadonnées) depuis une application JDBC, vous devez au préalable ajouter
un jeu d'objets système JConnect à votre base. Les classes du gestionnaire
JDBC interne et jConnect partagent les procédures stockées pour le support
des métadonnées. Ces procédures sont installées dans toutes les bases par
défaut. L'option –i de dbinit empêche cette installation.
$ Pour plus d'informations sur l'ajout d'objets système jConnect dans une
base de données, reportez-vous à la section "Utilisation du gestionnaire
JDBC jConnect", page 147.
L'application Java suivante est une application complète de ligne de
commande, qui établit une connexion à une base de données active, imprime
un ensemble d'informations sur votre ligne de commande, puis interrompt
son exécution.
Avant toute chose, une application JDBC doit établir une connexion pour
pouvoir travailler sur les données d'une base.
$ L'exemple ci-après présente une connexion externe (une connexion
client/serveur classique). Pour plus d'informations sur la création d'une
connexion interne à partir de classes Java exécutées au sein du serveur de
base de données, reportez-vous à la section "Etablissement d'une connexion à
partir d'une classe JDBC côté serveur", page 158.
Le code ci-après est le code source des méthodes utilisées pour établir une
connexion. Ce code source figure dans la méthode main et la méthode
ASAConnect du fichier JDBCExamples.java, placé dans le sous-répertoire
Samples\ASA\Java du répertoire SQL Anywhere :

Chapitre 5 Accès aux données via JDBC
import java.sql.*; // JDBC
import com.sybase.jdbc2.jdbc.*; // Sybase jConnect
import java.util.Properties; // Propriétés
import sybase.sql.*; // Utilitaires Sybase
import asademo.*; // Exemples de classes
public class JDBCExamples{
private static Connection conn;
public static void main( String args[] ){
// Etablit une connexion
conn = null;
String machineName = ( args.length == 1 ? args[0] :
"localhost" );
ASAConnect( "DBA", "SQL", machineName );
if( conn!=null ) {
System.out.println( "Réussite connexion" );
}else{
System.out.println( "Echec connexion" );
}
);
}
}
try{
getObjectColumn();
getObjectColumnCastClass();
insertObject();
}
catch( Exception e ){
System.out.println( "Erreur : " + e.getMessage()
e.printStackTrace();
155

Etablissement de connexions JDBC
156
private static void ASAConnect( String userID,
String password,
String machineName ) {
// Connexion à Adaptive Server Anywhere
String coninfo = new String( machineName );
Properties props = new Properties();
props.put( "user", userID );
props.put( "password", password );
props.put("DYNAMIC_PREPARE", "true");
// Charge jConnect
try {
Class.forName( "com.sybase.jdbc2.jdbc.SybDriver"
).newInstance();
String dbURL = "jdbc:sybase:Tds:" + machineName +
":2638/?JCONNECT_VERSION=5";
System.out.println( dbURL );
conn = DriverManager.getConnection( dbURL , props
);
}
catch ( Exception e ) {
System.out.println( "Erreur : " + e.getMessage()
);
e.printStackTrace();
}
}
Fonctionnement de l’exemple de connexion externe
Importation de
packages
L’exemple de connexion externe est une application Java de ligne de
commande.
L'application requiert plusieurs bibliothèques, importées selon les premières
lignes de JDBCExamples.java :
♦ Le package java.sql contient les classes JDBC de Sun Microsystems ,
requises pour toutes les applications JDBC. Elles se trouvent dans le
fichier classes.zip du sous-répertoire Java.
♦ Le gestionnaire JDBC jConnect de Sybase, importé depuis
com.sybase.jdbc2.jdbc, est requis pour toutes les applications
connectées via jConnect.
♦ L'application utilise une liste de propriétés. La classe
java.util.Properties est requise pour la gestion des listes de propriétés.
Elle se trouve dans le fichier classes.zip du sous-répertoire Java.
♦ Le package asademo contient des classes utilisées dans certains
exemples. Ils se trouve dans le fichier Samples\ASA\Java\asademo.jar.

La méthode main
La méthode
ASAConnect
Chapitre 5 Accès aux données via JDBC
Chaque application Java nécessite une classe dotée d'une méthode main, qui
est la méthode appelée au démarrage du programme. Dans notre exemple,
JDBCExamples.main est la seule méthode de l'application.
La méthode JDBCExamples.main effectue les tâches suivantes :
1 Elle traite l'argument de la ligne de commande en utilisant le nom de
machine si celui-ci est fourni. Par défaut, le nom de la machine est
localhost, ce qui convient très bien pour le serveur de base de données
personnel.
2 Elle appelle la méthode ASAConnect pour établir une connexion.
3 Elle exécute plusieurs méthodes qui font défiler des données sur votre
ligne de commande.
La méthode JDBCExamples.ASAConnect effectue les tâches suivantes :
1 Elle établit une connexion à la base de données active par défaut via
jConnect de Sybase.
♦ Class.forName charge jConnect. Le fait d'utiliser la méthode
newInstance simplifie les choses dans certains navigateurs.
♦ Les instructions StringBuffer créent une chaîne de connexion à
partir des chaînes littérales et du nom de machine donnés sur la
ligne de commande.
♦ DriverManager.getConnection établit ensuite une connexion à
l'aide de la chaîne de connexion.
2 Elle repasse la main à la méthode d'appel.
Exécution de l'exemple de connexion externe
Cette section présente la procédure d'exécution de l'exemple de connexion
externe.
v Pour créer et exécuter l'application exemple de connexion externe :
1 Ouvrez la fenêtre de commandes.
2 Positionnez-vous dans le répertoire SQL Anywhere.
3 Positionnez-vous dans le sous-répertoire Samples\ASA\Java.
4 Assurez-vous que la base de données est chargée sur un serveur de base
de données exécutant TCP/IP. Pour démarrer le serveur sur votre
machine locale, utilisez la commande suivante (à partir du sousrépertoire
Samples\ASA\Java) :
start dbeng8 ..\..\..\asademo
157

Etablissement de connexions JDBC
158
5 Pour exécuter l'exemple, entrez, à l'invite de commandes :
java JDBCExamples
Si vous souhaitez répéter l'opération dans un serveur exécuté sur une
autre machine, entrez le nom exact de cette machine. Le nom par défaut
est localhost (qui est un alias du nom de la machine courante).
6 Confirmez qu'une liste de personnes et de produits est bien affichée.
En cas d'échec de la tentative de connexion, c'est un message d'erreur
qui est affiché. Confirmez que vous avez bien exécuté toutes les étapes
requises. Vérifiez que CLASSPATH est correctement définie. Si elle est
incorrecte, CLASSPATH empêche la localisation d'une classe.
$ Pour plus d'informations sur l'utilisation de jConnect, reportez-vous à la
section "Utilisation du gestionnaire JDBC jConnect", page 147 et à la
documentation en ligne relative à jConnect.
Etablissement d'une connexion à partir d'une classe JDBC côté
serveur
Dans JDBC, les instructions SQL sont créées à l'aide de la méthode
createStatement d'un objet Connection. Même les classes exécutées dans le
serveur doivent établir une connexion pour créer un objet Connection.
L'établissement d'une connexion à partir d'une classe JDBC côté serveur est
une opération plus simple que l'établissement d'une connexion externe. En
effet, du fait que la classe côté serveur est exécutée par un utilisateur déjà
connecté, la classe utilise directement la connexion active.
Code de l'exemple de connexion côté serveur
Le code ci-après est le code source de l'exemple. Le code source se trouve
dans la méthode InternalConnect du fichier
Samples\ASA\Java\JDBCExamples.java du répertoire SQL Anywhere :
public static void InternalConnect() {
try {
conn =
DriverManager.getConnection("jdbc:default:connection");
System.out.println("Salut");
}
catch ( Exception e ) {
System.out.println("Erreur : " + e.getMessage());
e.printStackTrace();
}
}
}

Fonctionnement de l'exemple de connexion côté serveur
Chapitre 5 Accès aux données via JDBC
Dans cet exemple, InternalConnect() est la seule méthode utilisée dans
l'application.
L'application ne requiert qu'une des bibliothèques (JDBC) importées selon la
première ligne de la classe JDBCExamples.java. Les autres sont requises
pour les connexions externes. Le package java.sql contient les classes JDBC.
La méthode InternalConnect() effectue les tâches suivantes :
1 Elle établit une connexion à la base de données active par défaut via la
connexion courante.
♦ DriverManager.getConnection établit ensuite une connexion à
l'aide de la chaîne de connexion jdbc:default:connection.
2 Elle imprime Salut dans la sortie standard courante, à savoir la fenêtre
du serveur. System.out.println exécute l'impression.
3 En cas d'erreur lors de la tentative de connexion, un message d'erreur
précisant l'endroit où cette dernière se produit est imprimé dans la
fenêtre du serveur.
Les instructions try et catch offrent un cadre de gestion des erreurs.
4 Elle met fin à la classe.
Exécution de l'exemple de connexion côté serveur
Cette section présente la procédure d'exécution de l'exemple de connexion
côté serveur.
v Pour créer et exécuter l'application exemple de connexion interne :
1 Si ce n’est déjà fait, compilez le fichier JDBCExamples.java. Si vous
utilisez le JDK, vous pouvez le faire dans le répertoire
Samples\ASA\Java à partir d'une invite de commandes :
javac JDBCExamples.java
2 Lancez un serveur de base de données à partir de la base de données
exemple. Pour démarrer le serveur sur votre machine locale, utilisez la
commande suivante (à partir du sous-répertoire Samples\ASA\Java) :
start dbeng8 ..\..\..\asademo
Le protocole réseau TCP/IP n'est pas nécessaire puisque jConnect n'est
pas utilisé.
159

Etablissement de connexions JDBC
160
3 Installez la classe dans la base de données exemple. Une fois connecté à
la base de données exemple, entrez la commande suivante à partir
d'Interactive SQL :
INSTALL JAVA NEW
FROM FILE
’chemin\Samples\ASA\Java\JDBCExamples.class’
où chemin est le chemin d'accès à votre répertoire d'installation.
Vous pouvez aussi installer la classe à l'aide de Sybase Central. Toujours
connecté à la base de données exemple, ouvrez le dossier Objets Java et
double-cliquez sur Ajouter une classe Java. Ensuite, suivez les
instructions fournies par l'assistant.
4 Désormais, vous pouvez appeler la méthode InternalConnect de cette
classe comme s'il s'agissait d'une procédure stockée.
CALL JDBCExamples>>InternalConnect()
La première fois qu'une classe Java est appelée au cours d'une session, la
JVM interne doit être chargée. Cette opération peut prendre quelques
secondes.
5 Vérifiez que le message Salut est bien imprimé dans la fenêtre du
serveur.
Remarques sur les connexions JDBC
♦ Mode AutoCommit La spécification JDBC impose, par défaut,
l'exécution d'une instruction COMMIT à l'issue de toute instruction
modifiant les données. Actuellement, le comportement de JDBC côté
serveur est d'effectuer la validation. Pour définir ce mode, utilisez une
instruction telle que :
conn.setAutoCommit( false );
où conn est l'objet de connexion courant.
♦ Valeurs de connexion par défaut Côté serveur JDBC, seul le premier
appel à getConnection( "jdbc:default:connection" ) crée une nouvelle
connexion avec les valeurs par défaut. Les appels suivants renvoient un
encapsulage de la connexion courante, toutes les propriétés de
connexion étant inchangées. Si vous désactivez AutoCommit (OFF)
dans votre connexion initiale, tous les appels getConnection suivants au
sein du même code Java renvoient une connexion avec AutoCommit sur
OFF.

Chapitre 5 Accès aux données via JDBC
Vous pouvez demander que les propriétés de la connexion soient
réinitialisées à leurs valeurs par défaut une fois la connexion fermée, de
sorte que les connexions suivantes soient établies avec les valeurs JDBC
standard. Pour ce faire, écrivez un code du type :
Connection conn = DriverManager.getConnection("");
boolean oldAutoCommit = conn.getAutoCommit();
try {
// code ici
}
finally {
conn.setAutoCommit( oldAutoCommit );
}
Cela ne s'applique pas uniquement à AutoCommit, mais également aux
autres propriétés de la connexion telles que TransactionIsolation et
isReadOnly.
161

Utilisation de JDBC pour accéder aux données
Utilisation de JDBC pour accéder aux données
Préparation des exemples
Code exemple
162
Les applications Java qui disposent de tout ou partie des classes dans la base
de données sont considérablement avantagées par rapport aux procédures
stockées SQL traditionnelles. Dans cette phase de prise en main, il peut
cependant être utile de faire un parallèle avec les procédures stockées SQL
pour mettre en évidence les capacités de JDBC. Dans les exemples suivants,
nous allons écrire des classes Java qui insèrent une ligne dans la table
Department.
Comme avec les autres interfaces, les instructions SQL dans JDBC peuvent
être soit statiques, soit dynamiques. Les instructions SQL statiques sont
créées dans l'application Java, puis envoyées à la base de données. Le
serveur de base de données analyse l'instruction, élabore un plan d'exécution,
puis exécute l'instruction. Les phases d'analyse et d'élaboration du plan
d'exécution constituent la préparation de l’instruction.
Si une même instruction doit être exécutée plusieurs fois (plusieurs insertions
dans une table, par exemple), une instruction SQL statique peut entraîner un
overhead important puisque la préparation doit être effectuée à chaque
occurrence.
En revanche, une instruction SQL dynamique contient des marques de
réservation. L'instruction est préparée une seule fois, à l'aide de ces marques
de réservation, puis exécutée autant de fois que nécessaire sans nouvelle
préparation.
Dans la présente section, nous utiliserons des instructions SQL statiques. Les
instructions SQL dynamiques seront abordées ultérieurement, dans une autre
section.
Cette section décrit la préparation des exemples pour leur utilisation dans le
reste du chapitre.
Les échantillons de code présentés dans cette section sont issus de la classe
complète Samples\ASA\Java\JDBCExamples.java.
v Pour installer la classe JDBCExamples :
1 Si ce n'est pas déjà fait, installez le fichier JDBCExamples.class dans la
base de données exemple. Une fois connecté à la base de données
exemple à partir d'Interactive SQL, entrez la commande suivante dans le
volet Instructions SQL :
INSTALL JAVA NEW

Chapitre 5 Accès aux données via JDBC
FROM FILE
’chemin\Samples\ASA\Java\JDBCExamples.class’
où chemin est le chemin d'accès à votre répertoire d'installation.
Vous pouvez aussi installer la classe à l'aide de Sybase Central. Toujours
connecté à la base de données exemple, ouvrez le dossier Objets Java et
double-cliquez sur Ajouter une classe Java. Ensuite, suivez les
instructions fournies par l'assistant.
Insertions, mises à jour et suppressions avec JDBC
L’objet Statement exécute des instructions SQL statiques. Ainsi, l'exécution
d'instructions SQL telles que INSERT, UPDATE et DELETE, qui ne
retournent pas de jeux de résultats, s'opère à l'aide de la méthode
executeUpdate de l'objet Statement. Les instructions telles que
CREATE TABLE, et autres instructions de définition des données, peuvent
aussi être exécutées à l'aide de executeUpdate.
Le code suivant montre la procédure d'exécution d'instructions INSERT dans
JDBC. Il utilise une connexion interne contenue dans l'objet Connection
conn. Le code permettant d'insérer des valeurs à partir d'une application
externe via JDBC suppose d'utiliser une autre connexion, sinon il reste
inchangé.
public static void InsertFixed() {
// retourne la connexion courante
conn =
DriverManager.getConnection("jdbc:default:connection");
// Désactivation autocommit
conn.setAutoCommit( false );
Statement stmt = conn.createStatement();
Integer IRows = new Integer( stmt.executeUpdate
("INSERT INTO Department (dept_id, dept_name )"
+ "VALUES (201, 'Eastern Sales')"
) );
// Impression nombre de lignes mises à jour
System.out.println(IRows.toString() + " row
inserted" );
}
Code source disponible
Cet échantillon de code appartient à la méthode InsertFixed de la classe
JDBCExamples, disponible dans le sous-répertoire Samples\ASA\Java
de votre répertoire d'installation.
163

Utilisation de JDBC pour accéder aux données
Remarques
164
♦ La méthode setAutoCommit désactive AutoCommit (OFF), de sorte
que les modifications ne sont validées que si une instruction COMMIT
explicite est exécutée.
♦ La méthode executeUpdate retourne un entier correspondant au nombre
de lignes affectées par l'opération. Dans le cas présent, une instruction
INSERT réussie renverrait la valeur un (1).
♦ Le type de l'entier renvoyé est converti en objet Integer. La classe
Integer, qui constitue une encapsulation du type de données de base int,
inclut quelques méthodes fort utiles telles que toString().
♦ L'entier IRows est converti en chaîne pour être imprimé. La sortie est
dirigée vers la fenêtre du serveur.
v Pour exécuter l'exemple JDBC Insert :
1 Via Interactive SQL, connectez-vous à la base de données exemple avec
l'ID utilisateur DBA.
2 Vérifiez que la classe JDBCExamples est installée. Elle est installée
avec les autres exemples de classes Java.
$ Pour plus d'informations sur l'installation des exemples de classes
Java, reportez-vous à la section "Installation des exemples Java",
page 92.
3 Appelez la méthode comme suit :
CALL JDBCExamples>>InsertFixed()
4 Vérifiez qu'une ligne a été ajoutée dans la table department.
SELECT *
FROM department
Cette ligne, dotée de l'ID 201, n'est pas validée. Vous pouvez exécuter
un ROLLBACK pour supprimer la ligne.
Dans cet exemple, nous avons vu comment créer une classe JDBC très
rudimentaire. Dans les exemples suivants, nous verrons comment l'étoffer.
Transmission d'arguments à des méthodes Java
Nous allons maintenant compléter la méthode InsertFixed, ce qui va nous
permettre d'aborder la transmission d'arguments aux méthodes Java.
La méthode suivante utilise des arguments transmis dans l'appel sous forme
de valeurs à insérer :
public static void InsertArguments(

Remarques
try {
Chapitre 5 Accès aux données via JDBC
String id, String name) {
conn = DriverManager.getConnection(
"jdbc:default:connection" );
String sqlStr = "INSERT INTO Department "
+ " ( dept_id, dept_name )"
+ " VALUES (" + id + ", ’" + nom + "’)";
// Exécution de l'instruction
Statement stmt = conn.createStatement();
Integer IRows = new Integer( stmt.executeUpdate(
sqlStr.toString() ) );
// Impression du nombre de lignes mises à jour
System.out.println(IRows.toString() + "ligne
insérée" );
}
catch ( Exception e ) {
System.out.println("Erreur : " + e.getMessage());
e.printStackTrace();
}
}
♦ Les deux arguments sont l'ID du département (un entier) et son nom
(une chaîne). Dans le cas présent, ces deux arguments sont transmis à la
méthode sous forme de chaîne, puisqu'ils sont utilisés comme éléments
de la chaîne d'instruction SQL.
♦ L'instruction INSERT est statique et elle ne prend aucun paramètre en
plus de l'instruction elle-même.
♦ Si vous vous trompez dans le nombre ou le type des arguments, l'erreur
La procédure est introuvable est renvoyée.
v Pour utiliser une méthode Java avec des arguments :
1 Si ce n'est pas déjà fait, installez le fichier JDBCExamples.class dans la
base de données exemple.
2 Pour ce faire, connectez-vous à la base de données exemple à partir
d'Interactive SQL, puis entrez la commande suivante :
call JDBCExamples>>InsertArguments( ’203’, ’Northern
Sales’ )
3 Vérifiez qu'une nouvelle ligne a bien été ajoutée à la table Department :
SELECT *
FROM Department
4 Annulez les modifications pour laisser la base intacte :
165

Utilisation de JDBC pour accéder aux données
Requêtes avec JDBC
Exécution de
l'exemple
166
ROLLBACK
L’objet Statement permet d'exécuter des requêtes statiques, ainsi que des
instructions qui ne retournent pas de jeux de résultats. Pour exécuter des
requêtes, utilisez la méthode executeQuery de l'objet Statement. Le jeu de
résultats est alors retourné dans un objet ResultSet.
L'échantillon de code ci-après montre comment les requêtes peuvent être
gérées dans JDBC. Il place la valeur totale d'inventaire d'un produit dans une
variable nommée inventory. Le nom du produit est contenu dans la variable
String prodname. Cet exemple figure dans la méthode Query de la classe
JDBCExamples.
Il suppose qu'une connexion interne ou externe a été établie et qu'elle est
maintenue dans l'objet Connection nommé conn.
public static int Query () {
int max_price = 0;
try{
conn = DriverManager.getConnection(
"jdbc:default:connection" );
// Création de la requête
String sqlStr = "SELECT id, unit_price "
+ "FROM product" ;
// Exécution de l'instruction
Statement stmt = conn.createStatement();
ResultSet result = stmt.executeQuery( sqlStr );
while( result.next() ) {
int price = result.getInt(2);
System.out.println( "Le prix est " + price );
if( price > max_price ) {
max_price = price ;
}
}
}
catch( Exception e ) {
System.out.println("Erreur : " + e.getMessage());
e.printStackTrace();
}
return max_price;
}
Une fois la classe JDBCExamples installée dans la base de données
exemple, vous pouvez exécuter cette méthode à l'aide de l'instruction
suivante dans Interactive SQL :

Remarques
select JDBCExamples>>Query()
Chapitre 5 Accès aux données via JDBC
♦ La requête sélectionne la quantité et le prix unitaire de tous les produits
nommés prodname. Les résultats sont renvoyés dans l'objet ResultSet
nommé result.
♦ Une boucle d'itération est appliquée sur chacune des lignes du jeu de
résultats. Cette boucle utilise la méthode next.
♦ Pour chaque ligne, la valeur de chaque colonne est extraite sous forme
de variable entière, à l'aide de la méthode getInt. ResultSet comprend
aussi des méthodes pour d'autres types de données, telles que getString,
getDate et getBinaryString.
Pour la méthode getInt, l'argument est un numéro d'index pour la
colonne (à partir de 1).
La conversion de type de données de SQL en Java est assurée selon la
méthode présentée dans la section "Conversions de types de données
SQL en Java", page 92 du document ASA Manuel de référence SQL.
♦ Adaptive Server Anywhere supporte les curseurs à défilement
bidirectionnel. Toutefois, JDBC propose uniquement la méthode next,
qui correspond à un défilement vers l'avant dans le jeu de résultats.
♦ La méthode retourne la valeur de max_price à l'environnement appelant
et Interactive SQL l'affiche dans le volet Résultats.
Utilisation d'instructions préparées pour un accès optimisé
Exemple
Avec l’interface Statement, vous analysez chaque instruction envoyée à la
base de données, vous générez un plan d'accès et vous exécutez l'instruction.
Les étapes préalables à l'exécution correspondent à la préparation de
l’instruction.
Avec l’interface PreparedStatement, vous pouvez considérablement gagner
en performances. En effet, vous pouvez ainsi préparer une instruction dotée
de marques de réservation, auxquelles vous affectez ensuite des valeurs à son
exécution.
Le recours aux instructions préparées est particulièrement utile pour effectuer
plusieurs actions identiques, par exemple pour insérer plusieurs lignes.
$ Pour plus d'informations sur les instructions préparées, reportez-vous à
la section "Préparation des instructions", page 12.
L'exemple suivant décrit comment utiliser l'interface PreparedStatement,
bien que l'insertion d'une seule ligne ne constitue pas une utilisation optimale
des instructions préparées.
167

Utilisation de JDBC pour accéder aux données
Exécution de
l'exemple
168
La méthode ci-après de la classe JDBCExamples effectue une exécution
préparée :
public static void JInsertPrepared(int id, String name)
try {
conn = DriverManager.getConnection(
"jdbc:default:connection" );
// Création de l'instruction INSERT
// ? est un caractère de marque de réservation
String sqlStr = "INSERT INTO Department "
+ " ( dept_id, dept_name )"
+ "VALUES ( ? , ? )" ;
// Préparation de l'instruction
PreparedStatement stmt = conn.prepareStatement(
sqlStr );
stmt.setInt(1, id);
stmt.setString(2, name );
Integer IRows = new Integer(
stmt.executeUpdate() );
// Impression du nombre de lignes mises à jour
System.out.println(IRows.toString() + "ligne
insérée" );
}
catch ( Exception e ) {
System.out.println("Erreur : " + e.getMessage());
e.printStackTrace();
}
}
Une fois la classe JDBCExamples installée dans la base de données
exemple, l'instruction suivante permet d'exécuter l'instruction donnée en
exemple :
call JDBCExamples>>InsertPrepared(
202, ’Eastern Sales’ )
L'argument de chaîne est placé entre guillemets simples, conformément aux
règles syntaxiques de SQL. En revanche, pour appeler cette méthode depuis
une application Java, délimitez la chaîne avec des guillemets doubles.

Insertion et extraction d’objets
Extraction d’objets
Insertion d’objets
Chapitre 5 Accès aux données via JDBC
En tant qu'interface de bases de données relationnelles, JDBC est
spécifiquement conçu pour extraire et manipuler des types de données SQL
classiques. Adaptive Server Anywhere fournit également des types de
données abstraites sous la forme de classes Java. Le mode d'accès à ces
classes Java via JDBC est fonction de l'opération que vous souhaitez
effectuer, à savoir l'insertion ou l'extraction d'objets.
$ Pour en savoir plus, reportez-vous à la section "Création d'applications
distribuées", page 171.
Pour extraire des objets ainsi que leurs champs et leurs méthodes, plusieurs
solutions sont possibles :
♦ Accès aux méthodes et aux champs Les méthodes et champs Java
peuvent être inclus dans la liste de sélection d'une requête. Ces champs
et méthodes apparaissent ensuite sous forme de colonnes dans le jeu de
résultats, et vous pouvez y accéder via l'une des méthodes ResultSet
standard, telles que getInt ou getString.
♦ Récupération d'un objet Si vous incluez une colonne avec un type de
classe Java dans une liste de sélection d'une requête, vous pouvez
ensuite récupérer l'objet dans une classe Java via la méthode ResultSet
getObject. L'accès aux méthodes et aux champs de cet objet est alors
possible à partir de la classe Java.
Depuis une classe Java côté serveur, la méthode JDBC setObject permet
d'insérer un objet dans une colonne de type classe Java.
Vous pouvez insérer des objets en utilisant une instruction préparée. Par
exemple, l'échantillon de code ci-après insère un objet de type MyJavaClass
dans une colonne de table T :
java.sql.PreparedStatement ps =
conn.prepareStatement("insert T values( ? )" );
ps.setObject( 1, new MyJavaClass() );
ps.executeUpdate();
Vous pouvez également choisir de configurer une variable SQL contenant
l'objet, puis d'insérer cette variable dans la table.
169

Utilisation de JDBC pour accéder aux données
Remarques diverses concernant JDBC
170
♦ Autorisations d'accès A l’instar de toutes les classes Java dans la base
de données, les classes contenant des instructions JDBC sont en accès
libre pour tous les utilisateurs. Il n'existe pas d'équivalent de l'instruction
GRANT EXECUTE, qui autorise l'exécution de certaines procédures, et
il n'est pas nécessaire de qualifier le nom d'une classe du nom de son
propriétaire.
♦ Autorisations d'exécution Les classes Java sont exécutées selon les
autorisations de la connexion qui les exécute. Ce mode est différent de
celui des procédures stockées, exécutées selon les autorisations du
propriétaire.

Création d'applications distribuées
Tâches associées
Conditions
requises pour les
applications
distribuées
Chapitre 5 Accès aux données via JDBC
Dans une application distribuée, certaines parties de la logique de
l'application sont exécutées sur une machine et les autres sur une autre
machine. Avec Adaptive Server Anywhere, vous pouvez créer des
applications Java distribuées, avec une partie de la logique exécutée dans le
serveur de la base, et le reste sur la machine cliente.
Adaptive Server Anywhere est capable d'échanger des objets Java avec un
client Java externe.
Dans une application distribuée, la tâche principale consiste pour
l'application cliente à extraire un objet Java d'une base de données. Cette
section décrit la procédure d'exécution de cette tâche.
Dans d'autres parties de ce chapitre, nous avons vu comment exécuter
plusieurs tâches qui sont certes associées à la récupération d'objets, mais qui
ne consistent pas à récupérer l'objet lui-même. Par exemple :
♦ "Recherche d'objets Java", page 114 décrit comment récupérer un objet
dans une variable SQL. Toutefois, cette section n'indique pas pour autant
comment intégrer l'objet dans l'application Java.
♦ "Recherche d'objets Java", page 114 décrit également comment
récupérer les champs publics et la valeur renvoyée des méthodes Java.
Mais une fois encore, cela n'explique pas comment récupérer un objet
pour l'intégrer dans une application Java.
♦ "Insertion et extraction d'objets", page 169 décrit comment récupérer des
objets dans des classes Java côté serveur. Mais cela ne nous dit toujours
pas comment les récupérer dans une application cliente.
La création d'une application distribuée comprend plusieurs étapes.
v Pour créer une application distribuée :
1 Toute classe exécutée dans le serveur doit mettre en oeuvre l'interface
Serializable. Cela est très simple.
2 L'application côté client doit importer la classe pour que l'objet puisse
être reconstitué côté client.
3 Pour sérialiser l'objet, utilisez la méthode
sybase.sql.ASAUtils.toByteArray côté serveur. Cette opération n'est
nécessaire que pour Adaptive Server Anywhere version 6.0.1 et
inférieure.
171

Création d'applications distribuées
172
4 Pour reconstituer l'objet, utilisez la méthode
sybase.sql.ASAUtils.fromByteArray côté client. Cette opération n'est
nécessaire que pour Adaptive Server Anywhere version 6.0.1 et
inférieure.
Ces tâches sont décrites en détail dans les sections suivantes.
Mise en oeuvre de l’interface Serializable
Les objets sont transmis du serveur à une application cliente sous une forme
dite sérialisée. Cela signifie que chaque ligne inclut les informations
suivantes :
♦ un identificateur de version,
♦ un identificateur de la classe (ou de la sous-classe) enregistrée,
♦ les valeurs des champs non statiques et non transitoires de la classe,
♦ des informations sur l'overhead.
Pour qu'un objet puisse être envoyé à une application cliente, il doit mettre
en oeuvre l'interface Serializable. Fort heureusement, cette tâche est des plus
simples.
v Pour mettre en oeuvre l’interface Serializable
♦ Ajoutez la séquence implements java.io.Serializable à votre définition
de classe.
Par exemple, Samples\ASA\Java\asademo\Product.java met en oeuvre
l'interface Serializable puisqu'elle comprend la déclaration suivante :
public class Product implements java.io.Serializable
Finalement, mettre en oeuvre l'interface Serializable revient juste à
déclarer que la classe peut être sérialisée.
L'interface Serializable ne contient ni méthode, ni variable. Un objet sérialisé
est converti en flux d'octets, ce qui permet de l'enregistrer sur disque ou de
l'envoyer à une autre application Java, où il peut alors être reconstitué, ou
désérialisé.
Un objet Java qui a été sérialisé dans un serveur de base de données, envoyé
à une application cliente, puis désérialisé, est en tous points identique à
l'objet d'origine. Cela étant, il n'est pas indispensable de sérialiser toutes les
variables d'un objet et, pour des questions de sécurité, certaines ne doivent
pas l'être. Ces variables sont déclarées avec le mot-clé transient, comme
dans la déclaration suivante :

transient String password;
Chapitre 5 Accès aux données via JDBC
Lorsqu'un objet avec cette variable est désérialisé, la variable contient
toujours sa valeur par défaut (NULL).
Vous pouvez personnaliser la sérialisation en ajoutant les méthodes
writeObject() et readObject() à vos classes.
$ Pour plus d'informations sur la sérialisation, reportez-vous au JDK
(Java Development Kit) de Sun Microsystems.
Importation d'une classe côté client
Côté client, toute classe qui extrait un objet doit disposer d'un accès à la
définition de classe correspondante pour pouvoir utiliser cet objet. Pour
utiliser la classe Product, qui figure dans le package asademo, vous devez
inclure la ligne suivante dans votre application :
import asademo.*
Exemple d'application distribuée
Pour que ce package puisse être localisé, le fichier asademo.jar doit être
inclus dans votre CLASSPATH.
La classe JDBCExamples.java contient trois méthodes illustrant
l'informatique Java distribuée. Celles-ci sont toutes appelées à partir de la
méthode main. Cette méthode est appelée dans l'exemple de connexion
donné dans la section "Connexion à partir d'une application JDBC cliente
avec jConnect", page 154, qui est un exemple d'application distribuée.
Voici la méthode getObjectColumn de la classe JDBCExamples.
private static void getObjectColumn() throws Exception {
// Renvoie un jeu de résultats à partir d'une colonne
// contenant des objets Java
asademo.ContactInfo ci;
String name;
String sComment ;
if ( conn != null ) {
Statement stmt = conn.createStatement();
ResultSet rs = stmt.executeQuery(
"SELECT JContactInfo FROM jdba.contact"
);
173

Création d'applications distribuées
Ancienne méthode
Sérialisation et
désérialisation des
résultats de
requêtes
174
while ( rs.next() ) {
ci = ( asademo.ContactInfo )rs.getObject(1);
System.out.println( "\n\tRue : " + ci.street +
"Ville : " + ci.city +
"\n\tPays : " + ci.state +
"Téléphone : " + ci.phone +
"\n" );
}
}
}
La méthode getObject est utilisée comme dans le cas de Java interne.
getObject et setObject conseillées
Les méthodes getObject et setObject suppriment la nécessité des
sérialisations et désérialisations explicites qui étaient la règle dans les
versions antérieures du logiciel. La présente section décrit cette ancienne
méthode à l'intention des utilisateurs chargés de la maintenance de code
utilisant ces techniques.
Dans cette section, nous verrons le mode de fonctionnement d'un de ces
exemples. Néanmoins, vous pouvez aussi étudier le code des autres
exemples.
Voici la méthode serializeColumn d'une ancienne version de la classe
JDBCExamples.
private static void serializeColumn() throws Exception {
Statement stmt;
ResultSet rs;
byte arrayb[];
asademo.ContactInfo ci;
String name;
if ( conn != null ) {
stmt = conn.createStatement();
rs = stmt.executeQuery( "SELECT
sybase.sql.ASAUtils.toByteArray( JName.getName() )
AS Name,
sybase.sql.ASAUtils.toByteArray(
jdba.contact.JContactInfo )
FROM jdba.contact" );
while ( rs.next() ) {
arrayb = rs.getBytes("Name");
name = ( String
)sybase.sql.ASAUtils.fromByteArray( arrayb );

Chapitre 5 Accès aux données via JDBC
arrayb = rs.getBytes(2);
ci =
(asademo.ContactInfo)sybase.sql.ASAUtils.fromByteArray(
arrayb );
System.out.println( "Nom : " + name +
"\n\tRue : " + ci.street +
"\n\tVille : " + ci.city +
"\n\tPays : " + ci.state +
"\n\tTéléphone : " + ci.phone
+
"\n" );
}
System.out.println( "\n\n" );
}
}
Voici, dans le détail, le mode de fonctionnement de la méthode :
1 Une connexion existe déjà lorsque la méthode est appelée. L'objet
connexion est contrôlé et, du moment qu'il existe, le code est exécuté.
2 Une requête SQL est créée et exécutée. Cette requête est la suivante :
SELECT
sybase.sql.ASAUtils.toByteArray( JName.getName() )
AS Name,
sybase.sql.ASAUtils.toByteArray(
jdba.contact.JContactInfo )
FROM jdba.contact
Cette instruction lance une requête sur la table jdba.contact. Elle obtient
les résultats à partir des colonnes JName et JContactInfo. Au lieu
d'extraire la colonne ou une méthode de la colonne, la fonction
sybase.sql.ASAUtils.toByteArray convertit les valeurs en flux d'octets
de sorte qu'il puisse être sérialisé.
3 Le client passe en boucle sur les lignes du jeu de résultats. Dans chaque
ligne, la valeur de chaque colonne est désérialisée en un objet.
4 La sortie (System.out.println) indique que les champs et méthodes de
l'objet peuvent être utilisés tout comme ils pouvaient l'être à l'origine.
Autres fonctionnalités des applications distribuées
JDBCExamples.java comprend deux autres méthodes relevant de
l'informatique distribuée :
♦ serializeVariable Cette méthode crée un objet Java natif référencé par
une variable SQL sur le serveur de base de données, puis le transmet à
l'application cliente.
175

Création d'applications distribuées
176
♦ serializeColumnCastClass Identique à la méthode serializeColumn,
cette méthode indique en plus comment reconstituer les sous-classes. La
colonne interrogée (JProd de la table product) est de type
asademo.Product. Certaines lignes sont de type asademo.Hat, qui est
une sous-classe de la classe Product. La classe est reconstituée du côté
client.

CHAPITRE 6
Programmation avec Embedded SQL
Présentation
Sommaire
Ce chapitre explique comment utiliser l’interface de programmation
Embedded SQL avec Adaptive Server Anywhere.
Sujet Page
Introduction 178
Exemples de programmes Embedded SQL 186
Types de données Embedded SQL 192
Utilisation des variables hôte 196
Zone de communication SQL (SQLCA) 205
Lecture de données 211
SQL statique et SQL dynamique 221
Zone descripteur SQL (SQLDA) 226
Envoi et extraction de valeurs longues 235
Utilisation de procédures stockées 241
Techniques de programmation Embedded SQL 245
Préprocesseur SQL 247
Références des fonctions de bibliothèque 251
Récapitulatif des commandes Embedded SQL 270
177

Introduction
Introduction
178
Embedded SQL est une interface de programmation de bases de données
pour les langages C et C++. Elle fait appel à des instructions SQL imbriquées
dans du code source C ou C++. Un préprocesseur SQL traduit ces
instructions SQL en code source C ou C++, que vous compilez par la suite.
Lors de leur exécution, les applications Embedded SQL utilisent une
bibliothèque d'interface Adaptive Server Anywhere pour communiquer
avec le serveur de base de données. La bibliothèque d'interface est une DLL
(dynamic link library) ou une bibliothèque partagée sur la plupart des platesformes.
♦ Sous Windows 95/98, Windows CE et Windows NT/2000, la
bibliothèque d'interface est dblib8.dll.
♦ Sous UNIX, la bibliothèque d'interface est libdblib8.so, libdblib8.sl ou
libdblib8.a, selon le système d'exploitation.
Adaptive Server Anywhere fournit deux versions d'Embedded SQL. La
version statique est plus facile à utiliser mais moins souple que la version
dynamique. Les deux versions sont présentées dans ce chapitre.

Présentation du processus de développement
Code Source C
Préprocesseur
SQL
Compilateur C
Editeur de lien
Application
cliente
Chapitre 6 Programmation avec Embedded SQL
Bibliothèque
d'importation
DLL
DLL
Base de
données
Une fois le programme prétraité et compilé, il est lié à la bibliothèque
d'importation afin que la bibliothèque d'interface
Adaptive Server Anywhere génère un fichier exécutable. Lorsque la base de
données est active, ce fichier exécutable utilise la DLL
d'Adaptive Server Anywhere pour communiquer avec la base de données. Il
n'est pas nécessaire que la base de données soit active lors du prétraitement
du programme.
Sous Windows 95/98 et Windows NT/2000, il existe des bibliothèques
d'importation spécifiques pour Watcom C/C++, Microsoft Visual C++ et
Borland C++.
$ L'utilisation de bibliothèques d'importation est la méthode de
développement standard pour les applications appelant des fonctions dans
des DLL. Toutefois, Adaptive Server Anywhere offre une autre méthode
qu'il est recommandé d'utiliser et qui permet d'éviter le recours aux
bibliothèques d'importation. Pour plus d'informations, reportez-vous à la
section "Chargement dynamique de la bibliothèque d'interface", page 183.
179

Introduction
Exécution du préprocesseur SQL
Ligne de
commande
Compilateurs supportés
180
Le préprocesseur SQL est un exécutable appelé sqlpp.exe.
La ligne de commande SQLPP se présente comme suit :
sqlpp [ options ] nom_fichier_SQL [nom_fichier_résultat]
Le préprocesseur SQL traite un programme en langage C avec
Embedded SQL avant l'exécution du compilateur C ou C++. Le
préprocesseur convertit les instructions SQL en code source C/C++, ce
dernier étant ensuite placé dans le fichier de résultat. L'extension normale
pour les programmes source en Embedded SQL est .sqc. Le nom du fichier
de résultat par défaut est nom_fichier_SQL avec l'extension .c. Si
nom_fichier_SQL comporte déjà l'extension .c, l'extension du fichier de
résultat sera, par défaut, .cc.
$ Pour obtenir la liste complète des options de ligne de commande,
reportez-vous à la section "Préprocesseur SQL", page 247.
Le préprocesseur SQL de langage C a été testé avec les compilateurs
suivants :
Système d'exploitation Compilateur Version
Windows 95/98 et NT/2000 Watcom C/C++ 9.5 et versions
supérieures
Windows 95/98 et NT/2000 Microsoft Visual C/C++ 1.0 et versions
supérieures
Windows 95/98 et NT/2000 Borland C++ 4.5
Windows CE Microsoft Visual C/C++ 5.0
UNIX GNU ou compilateur
natif
NetWare Watcom C/C++ 10.6, 11
$ Pour plus d’informations sur la compilation des NLM NetWare,
reportez-vous à la section "Compilation des modules chargeables NetWare
(NLM)", page 185.

Fichiers d'en-tête Embedded SQL
Chapitre 6 Programmation avec Embedded SQL
Tous les fichiers d'en-tête sont installés dans le sous-répertoire h du
répertoire d'installation d'Adaptive Server Anywhere.
Nom de
fichier
Description
sqlca.h Principal fichier d'en-tête inclus dans tous les programmes
Embedded SQL. Ce fichier contient la définition de structure de
la zone de communication SQL (SQLCA), ainsi que des
prototypes pour toutes les fonctions d'interface de base de
données Embedded SQL.
sqlda.h Définition de structure de la zone descripteur SQL incluse dans
les programmes Embedded SQL qui utilisent du SQL dynamique.
sqldef.h Définition des types de données de l'interface Embedded SQL.
Ce fichier contient également les définitions de structure et les
codes de retour nécessaires au démarrage du serveur de base de
données à partir d'un programme en C.
sqlerr.h Définition des codes d'erreur renvoyés dans le champ sqlcode de
la zone SQLCA.
sqlstate.h Définition des états d'erreur standard SQL ANSI/ISO renvoyés
dans le champ sqlstate de la zone SQLCA.
pshpk1.h,
pshpk2.h,
poppk.h
Bibliothèques d'importation
Ces fichiers d'en-tête assurent une gestion correcte des groupes
de structure. Ils supportent les compilateurs Watcom C/C++,
Microsoft Visual C++, IBM Visual Age et Borland C/C++.
Toutes les bibliothèques d'importation sont installées à l'intérieur du sousrépertoire
lib, dans le sous-répertoire du système d'exploitation du répertoire
d'installation d'Adaptive Server Anywhere. Par exemple, les bibliothèques
d'importation de Windows 95/98 et Windows NT/2000 sont stockées dans le
sous-répertoire win32\lib.
181

Introduction
Exemple simple
182
Système d'exploitation Compilateur Bibliothèque
d'importation
Windows 95/98, Windows NT Watcom C/C++ dblibtw.lib
Windows 95/98, Windows NT Microsoft Visual
C++
Windows CE Microsoft Visual
C++
dblibtm.lib
dblib8.lib
NetWare Watcom C/C++ dblib8.lib
Solaris (applications n’utilisant
pas les threads natifs)
Solaris (applications utilisant les
threads natifs)
Tous les
compilateurs
Tous les
compilateurs
libdblib8.so,
libdbtasks8.so
libdblib8_r.so,
libdbtasks8_r.so
Les bibliothèques libdbtasks8 sont appelées par la bibliothèque libdblib8 .
Certains compilateurs localisent libdbtasks8 automatiquement ; avec d'autres,
vous devez la spécifier explicitement.
Voici un exemple très simple de programme Embedded SQL :
#include
EXEC SQL INCLUDE SQLCA;
main()
{
db_init( &sqlca );
EXEC SQL WHENEVER SQLERROR GOTO error;
EXEC SQL CONNECT "DBA" IDENTIFIED BY "SQL";
EXEC SQL UPDATE employee
SET emp_lname = ’Plankton’
WHERE emp_id = 195;
EXEC SQL COMMIT WORK;
EXEC SQL DISCONNECT;
db_fini( &sqlca );
return( 0 );
}
error:
printf( "echec de mise à jour --- sqlcode = %ld.n",
sqlca.sqlcode );
db_fini( &sqlca );
return( -1 );

Chapitre 6 Programmation avec Embedded SQL
Ce programme effectue la connexion à la base de données, met à jour le nom
de l'employé 195, valide la modification et s'arrête. Il n'existe pratiquement
aucune interaction entre les codes SQL et C dans cet exemple. Dans cet
exemple, le code C est utilisé uniquement pour le contrôle de flux.
L'instruction WHENEVER permet d'effectuer le contrôle d'erreurs. L'action
sur erreur (GOTO, dans cet exemple) est exécutée après toute instruction
SQL ayant généré une erreur.
$ Pour obtenir la description des opérations d'extraction des données,
reportez-vous à la section "Lecture de données", page 211.
Structure des programmes Embedded SQL
Les instructions SQL sont placées (imbriquées) dans du code C ou C++
normal. Toutes les instructions Embedded SQL commencent par les mots
EXEC SQL et se terminent par un point-virgule (;). Les commentaires du
langage C normal peuvent être intégrés aux instructions Embedded SQL.
Tout programme en langage C faisant appel à Embedded SQL doit contenir
l'instruction ci-après avant toute autre instruction Embedded SQL dans le
fichier source :
EXEC SQL INCLUDE SQLCA;
La première instruction Embedded SQL exécutée par le programme en
langage C doit être une instruction CONNECT. L'instruction CONNECT
permet d'établir une connexion avec le serveur de base de données et
d'indiquer l'ID utilisateur utilisé pour autoriser toutes les instructions
exécutées au cours de la connexion.
L'instruction CONNECT doit être la première instruction Embedded SQL
exécutée. Certaines commandes Embedded SQL ne génèrent pas de code C
ou n'établissent aucune communication avec la base de données. Par
conséquent, leur utilisation est autorisée avant l'instruction CONNECT. Il
s'agit notamment des instructions INCLUDE et WHENEVER (pour le
traitement des erreurs).
Chargement dynamique de la bibliothèque d'interface
Il est courant, dans le développement d'applications faisant appel à des
fonctions provenant de DLL, de lier l'application à une bibliothèque
d'importation contenant les définitions des fonctions requises.
183

Introduction
Exemple
184
Cette section présente une alternative à l'utilisation de la bibliothèque
d'importation pour développer des applications Adaptive Server Anywhere.
Il est possible de charger la bibliothèque d'interface
d'Adaptive Server Anywhere dynamiquement, sans créer de lien à la
bibliothèque d'importation, par l'intermédiaire du module esqldll.c qui se
trouve dans le sous-répertoire src du répertoire d'installation. Il est
recommandé d'utiliser esqldll.c car ce module permet de localiser la DLL
d'interface plus facilement et de façon plus stable.
v Pour charger la DLL d'interface de façon dynamique :
1 Votre programme doit appeler db_init_dll pour charger la DLL, puis
db_fini_dll pour la libérer. La fonction db_init_dll doit être appelée
avant toute autre fonction dans l'interface de base de données, et aucune
fonction ne peut être appelée après db_fini_dll.
Les fonctions de bibliothèque db_init et db_fini doivent toujours être
appelées.
2 Vous devez inclure (#include) le fichier d'en-tête esqldll.h avant
l'instruction EXEC SQL INCLUDE SQLCA ou la ligne dans
votre programme Embedded SQL.
3 Vous devez définir une macro SQL OS. Le fichier d'en-tête sqlca.h,
inclus dans esqdll.c, tente de déterminer la macro appropriée et la
définit. Notez cependant que cette opération peut échouer sur certaines
combinaisons plate-forme/compilateur. Dans ce cas, ajoutez une
définition (#define) au début du fichier ou définissez la macro à l'aide
d'une option de compilateur.
Macro Plates-formes
_SQL_OS_WINNT Windows 95/98, Windows CE et
Windows NT/2000
_SQL_OS_UNIX UNIX
_SQL_OS_NETWARE NetWare
4 Compilez esqldll.c.
5 Au lieu d'effectuer la liaison avec la bibliothèque d'importation, liez le
module objet esqldll.obj avec les objets de votre application
Embedded SQL.
Il existe un programme exemple, qui indique comment charger la
bibliothèque d'interface de manière dynamique, dans le sous-répertoire
Samples\ASA\ESQLDynamicLoad du répertoire SQL Anywhere. Le code
source se trouve dans Samples\ASA\ESQLDynamicLoad\sample.sqc.

Chapitre 6 Programmation avec Embedded SQL
Compilation des modules chargeables NetWare (NLM)
Vous devez utiliser le compilateur Watcom C/C++, version 10.6 ou 11.0,
pour compiler les programmes Embedded SQL sous la forme de NLM
(module chargeable NetWare).
v Pour créer un NLM Embedded SQL :
1 Sous Windows, prétraitez le fichier ESQL avec la commande suivante :
sqlpp -o NETWARE fichier_src.sqc
Cette instruction crée un fichier avec l'extension .c.
2 Compilez fichier.c à l'aide du compilateur Watcom (10.6 ou 11.0), en
utilisant l'option /bt=netware.
3 Liez le fichier objet obtenu en utilisant le générateur de liens Watcom
avec les options suivantes :
FORMAT NOVELL
MODULE dblib8
OPTION CASEEXACT
IMPORT @dblib8.imp
LIBRARY dblib8.lib
Les fichiers dblib8.imp et dblib8.lib sont fournis avec Adaptive Server
Anywhere, dans le répertoire nlm\lib. Dans les lignes IMPORT et
LIBRARY, il se peut que vous ayez à préciser le chemin complet.
185

Exemples de programmes Embedded SQL
Exemples de programmes Embedded SQL
186
Des exemples de programmes Embedded SQL sont inclus dans l’installation
d’Adaptive Server Anywhere. Ils sont placés dans le sous-répertoire
Samples\ASA\C du répertoire SQL Anywhere.
♦ L'exemple de curseur statique Embedded SQL, Samples\ASA\C\cur.sqc,
démontre l'utilisation d'instructions SQL statiques.
♦ L'exemple de curseur dynamique Embedded SQL,
Samples\ASA\C\dcur.sqc, démontre l'utilisation d'instructions SQL
dynamiques.
Pour réduire la quantité de code dupliqué par les programmes exemples, les
lignes principales et les fonctions d'impression des données ont été placées
dans des fichiers séparés. Ces fichiers sont mainch.c pour les systèmes en
mode caractères et mainwin.c pour les environnements utilisateur graphiques.
Chaque programme exemple fournit les trois routines suivantes, appelées
depuis les lignes principales :
♦ WSQLEX_Init Etablit une connexion à la base de données et ouvre le
curseur.
♦ WSQLEX_Process_Command Traite les commandes entrées par
l'utilisateur en manipulant le curseur selon les besoins.
♦ WSQLEX_Finish Ferme le curseur et interrompt la connexion avec la
base de données.
La ligne principale a plusieurs fonctions :
1 Appel de la routine WSQLEX_Init.
2 Boucle, obtention de commandes de l'utilisateur et appel de
WSQL_Process_Command jusqu'à ce que l'utilisateur quitte le
programme.
3 Appel de la routine WSQLEX_Finish.
La connexion à la base de données s'effectue à l'aide de la commande
Embedded SQL CONNECT, qui fournit l'ID utilisateur et le mot de passe
appropriés.
En plus de ces exemples, vous trouverez d'autres programmes et fichiers
source faisant partie de SQL Anywhere Studio, qui illustrent des
fonctionnalités disponibles sur des plates-formes spécifiques.

Création des programmes exemples
Chapitre 6 Programmation avec Embedded SQL
Les fichiers utilisés pour créer les programmes exemples sont fournis avec le
code exemple.
♦ Pour les systèmes d'exploitation Windows et les systèmes d'exploitation
NetWare fonctionnant sous Windows, utilisez makeall.bat pour compiler
les programmes exemples.
♦ Pour UNIX, utilisez le script shell makeall.
♦ Pour Windows CE, utilisez le fichier projet dcur.dsp pour Microsoft
Visual C++.
Le format de cette commande est le suivant :
makeall {Exemple} {Plate-forme} {Compilateur}
Le premier paramètre est le nom du programme exemple que vous souhaitez
compiler. C'est l'un des paramètres suivants :
♦ CUR exemple de curseur statique
♦ DCUR exemple de curseur dynamique
♦ ODBC exemple ODBC
Le second paramètre concerne la plate-forme cible. C'est l'un des paramètres
suivants :
♦ WINNT Compile pour Windows NT/2000, Windows 95 et Windows 98
♦ NETWARE Compile pour Netware NLM
Le troisième paramètre est le compilateur à utiliser pour la compilation du
programme. Il peut s'agir de l'un des compilateurs suivants :
♦ WC Watcom C/C++
♦ MC Microsoft C
♦ BC Borland C
Exécution des programmes exemples
Les fichiers exécutables et le code source se trouvent dans le sous-répertoire
Samples\ASA\C.
187

Exemples de programmes Embedded SQL
Exemples
Windows
188
v Pour exécuter le programme exemple de curseur statique :
1 Démarrez le programme :
♦ Démarrez la base de données exemple du serveur personnel
Adaptive Server Anywhere.
♦ Exécutez le fichier Samples\ASA\C\curwnt.exe.
2 Suivez les instructions qui s'affichent à l'écran.
Les différentes commandes agissent sur un curseur de base de données
et affichent les résultats de la requête à l'écran. Tapez la lettre associée à
la commande que vous souhaitez exécuter. Certains systèmes demandent
d'appuyer sur ENTREE après la lettre.
v Pour exécuter le programme exemple de curseur dynamique :
1 Démarrez le programme :
♦ Exécutez le fichier Samples\ASA\C\dcurwnt.exe.
2 Connectez-vous à une base de données.
♦ Chacun des programmes exemples présente une interface utilisateur
de type console qui vous invite à entrer une commande. Pour vous
connecter à la base de données exemple, saisissez la chaîne de
connexion suivante :
DSN=ASA 8.0 Sample
3 Choisissez une table :
♦ Chaque programme exemple vous invite à choisir une table.
Choisissez une des tables de la base de données exemple. Ainsi,
vous pouvez saisir Customer ou Employee.
4 Suivez les instructions qui s'affichent à l'écran.
Les différentes commandes agissent sur un curseur de base de données
et affichent les résultats de la requête à l'écran. Tapez la lettre associée à
la commande que vous souhaitez exécuter. Certains systèmes demandent
d'appuyer sur ENTREE après la lettre.
Les versions Windows des programmes exemples sont de véritables
programmes Windows. Toutefois, afin que le code de l'interface utilisateur
reste relativement compréhensible, certaines simplifications ont été
effectuées. Notamment, ces applications ne réaffichent pas Windows
lorsqu'elles reçoivent des messages WM_PAINT, si ce n'est pour réafficher
l'invite.

Exemple de curseur statique
Exemple de curseur dynamique
Chapitre 6 Programmation avec Embedded SQL
Cet exemple illustre l'emploi des curseurs. Le curseur utilisé ici extrait
certaines informations de la table employee de la base de données exemple.
Il est déclaré statiquement, c'est-à-dire que la véritable instruction SQL qui
permet d'extraire les informations est "codée en dur" dans le programme
source. C'est un bon point de départ pour comprendre le fonctionnement des
curseurs. L'exemple suivant ("Exemple de curseur dynamique", page 189)
reprend ce premier exemple et l'adapte à l'utilisation d'instructions SQL
dynamiques.
$ Pour savoir où se trouve le code source et comment construire ce
programme exemple, reportez-vous à la section "Exemples de programmes
Embedded SQL", page 186.
La routine open_cursor déclare un curseur pour la commande SQL
spécifique et ouvre ce curseur.
L'impression d'une page d'informations est effectuée par la routine print.
Elle exécute autant de boucles qu'il existe de pages (pagesize fois) pour
extraire une ligne unique du curseur et l'imprimer. Notez que la routine
FETCH vérifie la présence d'avertissements (tels que La ligne est
introuvable) et imprime les messages appropriés lorsqu'ils se produisent. De
plus, le curseur est repositionné par le programme sur la ligne qui précède la
ligne affichée en haut de la page de données courante.
Les routines move, top et bottom utilisent le format approprié de
l'instruction FETCH pour positionner le curseur. Notez que l'instruction
FETCH, sous cette forme, n'extrait pas les données ; elle déplace seulement
le curseur. En outre, une routine générale de positionnement relatif, move, a
été mise en oeuvre pour permettre les déplacements dans l'un ou l'autre sens
selon le signe du paramètre.
Lorsque l'utilisateur quitte le programme, le curseur est refermé et la
connexion à la base de données est interrompue. Le curseur est fermé par une
instruction ROLLBACK WORK et la connexion libérée à l'aide de
DISCONNECT.
Cet exemple illustre l'utilisation des curseurs pour une instruction
SQL SELECT dynamique. Il comporte quelques modifications par rapport à
l'exemple de curseur statique. Il est d'ailleurs conseillé de prendre
connaissance de la section "Exemple de curseur statique", page 189 avant de
vous pencher sur cet exemple.
189

Exemples de programmes Embedded SQL
190
$ Pour savoir où se trouve le code source et comment construire ce
programme exemple, reportez-vous à la section "Exemples de programmes
Embedded SQL", page 186.
Le programme dcur permet de sélectionner une table à consulter à l'aide de
la commande n. Il présente ensuite autant d'informations de la table que
l'écran peut en contenir.
Lorsque ce programme est exécuté, il invite l'utilisateur à entrer une chaîne
de connexion de la forme suivante :
uid=DBA;pwd=SQL;dbf=c:\asa\asademo.db
Le programme en langage C avec Embedded SQL se trouve dans le sousrépertoire
Samples\ASA\C du répertoire SQL Anywhere. Il ressemble
beaucoup à l'exemple de curseur statique, à l'exception des fonctions
connect, open_cursor et print.
La fonction connect fait appel à la fonction de l'interface Embedded SQL
db_string_connect pour la connexion à la base de données. Elle gère
également la chaîne de connexion utilisée pour la connexion à la base.
La routine open_cursor génère d'abord l'instruction SELECT :
SELECT * FROM nom_table
où nom_table est un paramètre transmis à la routine. Elle prépare ensuite une
instruction SQL dynamique à l'aide de cette chaîne.
La commande Embedded SQL DESCRIBE permet de compléter la structure
SQLDA avec les résultats de l'instruction SELECT.
Taille de la zone SQLDA
Initialement, la taille de la zone SQLDA (3) est estimée. Si elle n'est pas
suffisamment importante, la taille effective de la liste de sélection
renvoyée par le serveur de base de données est utilisée pour allouer une
taille correcte à la zone SQLDA.
La structure SQLDA est ensuite complétée avec des buffers afin de
pouvoir stocker les chaînes qui constituent le résultat de la requête. La
routine fill_s_sqlda convertit tous les types de données de la zone
SQLDA en DT_STRING, puis alloue des buffers de la taille appropriée.
Un curseur est ensuite déclaré, puis ouvert pour cette instruction. Les
routines de déplacement et de fermeture du curseur restantes sont identiques.
La routine fetch est quelque peu différente : elle place les résultats dans la
structure SQLDA et non dans une liste de variables hôte. La routine print a
été largement modifiée ; elle affiche les résultats de la structure SQLDA sur
toute la largeur de l'écran. Cette routine utilise également les champs "nom"
de la zone SQLDA pour imprimer les en-têtes de chaque colonne.

Exemples de service
Chapitre 6 Programmation avec Embedded SQL
Lorsqu'ils sont compilés pour Windows, les programmes exemples cur.sqc et
dcur.sqc peuvent être exploités en tant que services.
Les deux fichiers contenant le code exemple pour les services Windows sont
le fichier source ntsvc.c et le fichier d'en-tête ntsvc.h. Ce code permet de
lancer un fichier exécutable associé, en tant qu'exécutable normal ou service
Windows.
v Pour exécuter l'un des exemples compilés en tant que service
Windows :
1 Démarrez Sybase Central et ouvrez le dossier Services.
2 Sélectionnez un type de service d'application exemple, puis cliquez sur
OK.
3 Entrez un nom de service dans le champ approprié.
4 Sélectionnez le programme exemple (curwnt.exe ou dcurwnt.exe) dans
le sous-répertoire Samples\ASA\C du répertoire SQL Anywhere.
5 Cliquez sur OK pour lancer l'installation.
6 Cliquez sur Démarrer dans la fenêtre principale pour démarrer le
service.
Lorsque les programmes sont exécutés en tant que services, ils affichent, si
possible, l'interface utilisateur normale. Ils écrivent également le résultat
dans le journal d'événements de l'application (Application Event Log). S'il
est impossible de démarrer l'interface utilisateur, les programmes
enregistrent une page de données dans ce journal, puis s'interrompent.
Ces exemples ont été testés avec les compilateurs Watcom C/C++
version 10.5 et Microsoft Visual C++.
191

Types de données Embedded SQL
Types de données Embedded SQL
192
Le transfert d’informations entre un programme et le serveur de bases de
données n'est possible que si chaque élément de données est assorti d'un
type. Les constantes du type de données Embedded SQL sont précédées du
préfixe DT_ et se trouvent dans le fichier d'en-tête sqldef.h. Vous pouvez
créer une variable hôte de n'importe quel type de données supporté. Vous
pouvez également utiliser ces types de données dans une structure SQLDA
pour transférer des données depuis et vers la base de données.
Vous pouvez définir des variables pour ces types de données en utilisant les
macros DECL_ répertoriées dans sqlca.h. Par exemple, une variable
contenant une valeur BIGINT peut être déclarée avec DECL_BIGINT.
Les types de données suivants sont supportés par l'interface de
programmation Embedded SQL :
♦ DT_BIT Entier signé (8 bits)
♦ DT_SMALLINT Entier signé (16 bits)
♦ DT_UNSMALLINT Entier non signé (16 bits)
♦ DT_TINYINT Entier signé (8 bits)
♦ DT_BIGINT Entier signé (64 bits)
♦ DT_INT Entier signé (32 bits)
♦ DT_UNSINT Entier non signé (16 bits)
♦ DT_FLOAT Nombre en virgule flottante (4 octets).
♦ DT_DOUBLE Nombre en virgule flottante (8 octets).
♦ DT_DECIMAL Décimal condensé.
typedef struct DECIMAL {
char array[1];
} DECIMAL;
♦ DT_STRING Chaîne de caractères terminée par une valeur NULL. Elle
est complétée par des blancs si la base de données est initialisée avec des
chaînes complétées par des blancs.
♦ DT_DATE Chaîne de caractères terminée par une valeur NULL,
correspondant à une date correcte.
♦ DT_TIME Chaîne de caractères terminée par une valeur NULL,
correspondant à une heure correcte.
♦ DT_TIMESTAMP Chaîne de caractères terminée par une valeur NULL,
correspondant à une estampille correcte.

Chapitre 6 Programmation avec Embedded SQL
♦ DT_FIXCHAR Chaîne de caractères de longueur fixe complétée par des
blancs.
♦ DT_VARCHAR Chaîne de caractères de longueur variable comportant
un champ "longueur" de deux octets. Lorsque vous fournissez des
informations au serveur de bases de données, vous devez définir le
champ "longueur". Lors de la lecture d'informations dans le serveur de
bases de données, celui-ci définit le champ "longueur" (non complété).
typedef struct VARCHAR {
unsigned short int len;
char array[1];
} VARCHAR;
♦ DT_LONGVARCHAR Longue chaîne de données de type caractère de
longueur variable. La macro définit une structure similaire à celle qui
suit :
#define DECL_LONGVARCHAR( size ) \
struct { a_sql_uint32 array_len; \
a_sql_uint32 stored_len; \
a_sql_uint32 untrunc_len; \
char array[size+1];\
}
La structure DECL_LONGVARCHAR peut être utilisée avec plus de
32 ko de données. Les données volumineuses peuvent être lues en une
seule opération, ou en plusieurs fois au moyen de l'instruction
GET DATA. Il est également possible de les transmettre au serveur en
une seule opération, ou en plusieurs fois en les ajoutant à une variable de
base de données via l'instruction SET. Ces données ne se terminent pas
par une valeur NULL.
$ Pour plus d'informations, reportez-vous à la section "Envoi et
extraction de valeurs longues", page 235.
♦ DT_BINARY Données binaires de longueur variable comportant un
champ "longueur" de deux octets. Lorsque vous fournissez des
informations au serveur de bases de données, vous devez définir le
champ "longueur". Lors de la lecture d'informations dans le serveur de
bases de données, celui-ci définit le champ "longueur".
typedef struct BINARY {
unsigned short int len;
char array[1];
} BINARY;
♦ DT_LONGBINARY Données binaires longues. La macro définit une
structure similaire à celle qui suit :
193

Types de données Embedded SQL
194
#define DECL_LONGBINARY( size ) \
struct { a_sql_uint32 array_len; \
a_sql_uint32 stored_len; \
a_sql_uint32 untrunc_len; \
char array[size]; \
}
La structure DECL_LONGBINARY peut être utilisée avec plus de
32 ko de données. Les données volumineuses peuvent être lues en une
seule opération, ou en plusieurs fois au moyen de l'instruction
GET DATA. Il est également possible de les transmettre au serveur en
une seule opération, ou en plusieurs fois en les ajoutant à une variable de
base de données via l'instruction SET.
$ Pour plus d'informations, reportez-vous à la section "Envoi et
extraction de valeurs longues", page 235.
♦ DT_TIMESTAMP_STRUCT Structure SQLDATETIME comportant des
champs pour chaque partie d'une estampille.
typedef struct sqldatetime {
unsigned short year; /* par exemple 1999 */
unsigned char month; /* 0-11 */
unsigned char day_of_week; /* 0-6 0=Dimanche */
unsigned short day_of_year; /* 0-365 */
unsigned char day; /* 1-31 */
unsigned char hour; /* 0-23 */
unsigned char minute; /* 0-59 */
unsigned char second; /* 0-59 */
unsigned long microsecond; /* 0-999999 */
} SQLDATETIME;
Vous pouvez faire appel à la structure SQLDATETIME pour récupérer
des champs de type DATE, TIME et TIMESTAMP (ou tout élément
pouvant être converti dans l'un de ces types). Bien souvent, les
applications disposent de leurs propres formats et de leur propre code de
manipulation de date. L'utilisation de cette structure pour la lecture de
données facilite la manipulation des données pour un programmeur.
Notez que les champs DATE, TIME et TIMESTAMP peuvent
également être lus et mis à jour avec n'importe quel type de caractère.
Si vous utilisez une structure SQLDATETIME pour insérer une date,
une heure ou une estampille dans la base de données, les éléments
day_of_year et day_of_week sont ignorés.
$ Pour plus d'informations, reportez-vous aux options de base de
données DATE_FORMAT, TIME_FORMAT,
TIMESTAMP_FORMAT et DATE_ORDER dans le chapitre "Options
de base de données", page 583 du document ASA Guide
d’administration.

Types de base de
données DATE et
TIME
Chapitre 6 Programmation avec Embedded SQL
♦ DT_VARIABLE Chaîne de caractères terminée par une valeur NULL. La
chaîne de caractères doit être le nom d'une variable SQL dont la valeur
est utilisée par le serveur de base de données. Ce type de données est
utilisé uniquement pour fournir des données au serveur. Il ne peut pas
être utilisé lors de la lecture de données depuis le serveur de base de
données.
Les structures sont définies dans le fichier sqlca.h. Les types VARCHAR,
BINARY et DECIMAL contiennent un tableau de un caractère et ne peuvent
donc pas servir à déclarer des variables hôtes ; elles sont toutefois utiles pour
allouer dynamiquement des variables ou pour transtyper d'autres variables.
Dans l'interface Embedded SQL, il n'existe pas de types de données
correspondant aux différents types DATE et TIME de base de données. Tous
ces types de base de données sont lus et mis à jour soit à l'aide de la structure
SQLDATETIME, soit à l'aide de chaînes de caractères.
$ Pour plus d'informations, reportez-vous aux sections "Instruction GET
DATA [ESQL]", page 459 du document ASA Manuel de référence SQL et
"Instruction SET", page 557 du document ASA Manuel de référence SQL.
195

Utilisation des variables hôte
Utilisation des variables hôte
Déclaration des variables hôte
Exemple
196
Les variables hôte sont des variables de langage C identifiées auprès du
préprocesseur SQL. Elles peuvent être utilisées pour transmettre des valeurs
ou pour en recevoir du serveur de base de données.
D'utilisation aisée, les variables hôte présentent néanmoins certaines
restrictions. Le SQL dynamique représente une méthode plus courante pour
transmettre des informations depuis et vers le serveur de base de données à
l'aide de la structure appelée zone descripteur SQL (SQLDA). Le
préprocesseur SQL génère automatiquement un SQLDA pour chaque
instruction dans laquelle des variables hôte sont utilisées.
$ Pour plus d'informations sur le SQL dynamique, reportez-vous à la
section "SQL statique et SQL dynamique", page 221.
Pour être définies, les variables hôte doivent être placées dans une section de
déclaration. Conformément aux normes IBM SAA et ANSI
Embedded SQL, les variables hôte doivent encadrer les déclarations de
variables en langage C normales, comme suit :
EXEC SQL BEGIN DECLARE SECTION;
/* déclaration des variables C */
EXEC SQL END DECLARE SECTION;
Les variables hôte peuvent donc remplacer les constantes dans n'importe
quelle instruction SQL. Lorsque le serveur de base de données exécute la
commande, il utilise la valeur de la variable hôte. Toutefois, sachez que ce
type de variable ne peut pas remplacer un nom de table ou de colonne ; pour
ce faire, un SQL dynamique est requis. Dans une instruction SQL, le nom de
la variable est précédé du signe deux-points (:) pour le distinguer d'autres
identificateurs admis dans l'instruction.
Un préprocesseur SQL standard ne tient pas compte du code en langage C,
excepté dans une section de déclaration (DECLARE SECTION). Les types
et les structures TYPEDEF ne sont donc pas autorisés. En revanche, les
initialiseurs sur les variables sont admis dans une section de déclaration.
♦ L'exemple de code suivant illustre l'utilisation de variables hôte dans une
commande INSERT. La valeur des variables est attribuée par le
programme avant qu'elles ne soient insérées dans la base de données :

Types de variable hôte en langage C
Chapitre 6 Programmation avec Embedded SQL
EXEC SQL BEGIN DECLARE SECTION;
long employee_number;
char employee_name[50];
char employee_initials[8];
char employee_phone[15];
EXEC SQL END DECLARE SECTION;
/* le programme affecte la valeur appropriée à
chaque variable
*/
EXEC SQL INSERT INTO Employee
VALUES (:employee_number, :employee_name,
:employee_initials, :employee_phone );
$ Pour obtenir un exemple plus détaillé, reportez-vous à la section
"Exemple de curseur statique", page 189.
Seul un nombre limité de types de données du langage C est supporté pour
les variables hôte. En outre, certains types de variable hôte n'ont pas de type
correspondant en langage C.
Les macros définies dans le fichier d'en-tête sqlca.h peuvent être utilisées
pour déclarer des variables hôte de plusieurs types : VARCHAR, FIXCHAR,
BINARY, PACKED DECIMAL, LONG VARCHAR, LONG BINARY ou
structure SQLDATETIME. Ils sont utilisés comme suit :
EXEC SQL BEGIN DECLARE SECTION;
DECL_VARCHAR( 10 ) v_varchar;
DECL_FIXCHAR( 10 ) v_fixchar;
DECL_LONGVARCHAR( 32678 ) v_longvarchar;
DECL_BINARY( 4000 ) v_binary;
DECL_LONGBINARY( 128000 ) v_longbinary;
DECL_DECIMAL( 10, 2 ) v_packed_decimal;
DECL_DATETIME v_datetime;
EXEC SQL END DECLARE SECTION;
Le préprocesseur reconnaît ces macros à l'intérieur d'une section de
déclaration et traite la variable en fonction du type correspondant.
Le tableau suivant répertorie les types de variable C admis en tant que
variables hôte et les types de données correspondants dans l'interface
Embedded SQL.
197

Utilisation des variables hôte
198
Type de données en
langage C
short i;
short int i;
unsigned short int i;
long l;
long int l;
unsigned long int l;
Type de données
d'interface Embedded SQL
Description
DT_SMALLINT Entier signé (16 bits)
DT_INT Entier signé (32 bits)
float f; DT_FLOAT Nombre en virgule flottante
(4 octets)
double d; DT_DOUBLE Nombre en virgule flottante
(8 octets)
DECL_DECIMAL(p,s) DT_DECIMAL(p,s) Nombre décimal condensé
char a; /*n=1*/
DECL_FIXCHAR(n) a;
DECL_FIXCHAR a[n];
DT_FIXCHAR(n) Chaîne de caractères de
longueur fixe complétée par
des blancs
char a[n]; /*n>=1*/ DT_STRING(n) Chaîne terminée par une
valeur NULL. Elle est
complétée par des blancs si
la base de données est
initialisée avec des chaînes
complétées par des blancs.
char *a; DT_STRING(32767) Chaîne terminée par une
valeur NULL

Pointeurs sur des
données de type
char
Type de données en
langage C
Chapitre 6 Programmation avec Embedded SQL
Type de données
d'interface Embedded SQL
Description
DECL_VARCHAR(n) a; DT_VARCHAR(n) Chaîne de caractères de
longueur variable
comportant un champ
"longueur" de deux octets.
Non complétée par des
blancs.
DECL_BINARY(n) a; DT_BINARY(n) Données binaires de
longueur variable
comportant un champ
"longueur" de deux octets
DECL_DATETIME a; DT_TIMESTAMP_STRUCT Structure SQLDATETIME
DECL_LONGVARCHAR( n
) a;
DT_LONGVARCHAR Chaîne longue de caractères
de longueur variable
comportant trois champs
"longueur" de 4 octets. Non
complétée par des blancs ni
terminée par une valeur
NULL.
DECL_LONGBINARY( n ) a; DT_LONGBINARY Données binaires longues
de longueur variable
comportant trois champs
"longueur" de 4 octets Non
complétée par des blancs.
Une variable hôte déclarée en tant que pointeur sur des données de type
caractère (char *a) est considérée par l'interface de la base de données
comme ayant une longueur de 32 767 octets. Toute variable hôte de ce type
utilisée pour récupérer des informations de la base de données doit pointer
sur un buffer d'une taille suffisante pour contenir toute valeur susceptible
d'être renvoyée par la base.
Cette solution peut être à l'origine de problèmes lorsque la définition d'une
colonne dans la base a été modifiée et qu'elle est plus grande que lorsque le
programme a été écrit. Une telle opération risque d'altérer la mémoire vive.
De plus, si vous utilisez un compilateur 16 bits, une demande de 32 767
octets risque de provoquer un débordement de la pile du programme. Il est
donc préférable de faire appel à un tableau déclaré, même comme paramètre
d'une fonction où il est transmis en tant que pointeur sur des données de
type char. Les instructions PREPARE peuvent ainsi identifier la taille du
tableau.
199

Utilisation des variables hôte
Portée des
variables hôte
Utilisation des variables hôte
Exemples
200
La section de déclaration d'une variable hôte standard peut être située aux
emplacements où les variables en langage C peuvent normalement être
déclarées. Cela inclut la section de déclaration de paramètres d'une fonction
en langage C. Les variables en langage C ont leur portée normale au sein du
bloc dans lequel elles sont définies. Toutefois, le préprocesseur SQL
n'analysant pas le code en langage C, il ne respecte pas les blocs C.
En ce qui concerne le préprocesseur SQL, les variables hôte sont globales ; il
n'est pas possible que deux de ces variables portent le même nom.
Les variables hôte peuvent être utilisées dans les circonstances suivantes :
♦ Dans les instructions SELECT, INSERT, UPDATE ou DELETE,
partout où un nombre ou une constante de type chaîne est autorisé.
♦ Dans la clause INTO des instructions SELECT et FETCH.
♦ Les variables hôte peuvent également remplacer un nom d'instruction, de
curseur ou d'option dans des commandes spécifiques d'Embedded SQL.
♦ Pour CONNECT, DISCONNECT et SET CONNECT, une variable hôte
peut remplacer un ID utilisateur, un mot de passe, un nom de connexion
ou d'environnement de base de données.
♦ Pour SET OPTION et GET OPTION, une variable hôte peut remplacer
un ID utilisateur, un nom d'option ou une valeur d'option.
♦ Les variables hôte ne peuvent pas remplacer un nom de table ou de
colonne dans une instruction.
♦ L'exemple ci-dessous illustre une syntaxe Embedded SQL correcte :
INCLUDE SQLCA;
long SQLCODE;
sub1() {
char SQLSTATE[6];
exec SQL CREATE TABLE ...
}
♦ L'exemple ci-dessous illustre une syntaxe Embedded SQL incorrecte :

Variables indicateur
Chapitre 6 Programmation avec Embedded SQL
INCLUDE SQLCA;
sub1() {
char SQLSTATE[6];
exec SQL CREATE TABLE...
}
sub2() {
exec SQL DROP TABLE...
// Pas de SQLSTATE dans la portée de cette
instruction
}
♦ Le cas de SQLSTATE et de SQLCODE est important et la norme
ISO/ANSI requiert qu'ils soient définis exactement comme suit :
long SQLCODE;
char SQLSTATE[6];
Les variables indicateur sont des variables en langage C qui fournissent des
informations complémentaires pour les opérations de lecture ou d'insertion
de données. Il existe plusieurs types d'utilisation pour ces variables :
♦ Valeurs NULL Pour permettre aux applications de gérer les valeurs
NULL.
♦ Troncature de chaînes Pour permettre aux applications de gérer les cas
où les valeurs lues doivent être tronquées pour tenir dans les variables
hôte.
♦ Erreurs de conversion Pour stocker les informations relatives aux
erreurs.
Une variable indicateur est une variable hôte de type short int suivant
immédiatement une variable hôte normale dans une instruction SQL. Par
exemple, dans l'instruction INSERT ci-dessous, :ind_phone est une variable
indicateur :
EXEC SQL INSERT INTO Employee
VALUES (:employee_number, :employee_name,
:employee_initials, :employee_phone:ind_phone );
Utilisation de variables indicateur pour gérer les valeurs NULL
Dans les données SQL, la valeur NULL représente un attribut inconnu ou
une information non applicable. Il ne faut pas confondre la valeur NULL de
SQL avec la constante C du même nom (NULL). Cette dernière représente
un pointeur non initialisé ou incorrect.
201

Utilisation des variables hôte
Utilisation de
variables indicateur
pour l’insertion de
valeurs NULL
Utilisation de
variables indicateur
pour la lecture de
valeurs NULL
202
Dans la documentation d’Adaptive Server Anywhere, toute référence à la
valeur NULL renvoie à sa signification relative aux bases de données SQL
indiquée ci-dessus. La constante C est désignée sous le nom de pointeur null
(en minuscules).
La valeur NULL n'est pas de même nature que toute autre valeur de type
défini pour les colonnes. Par conséquent, pour transmettre des valeurs NULL
à la base de données ou en recevoir des résultats NULL, des variables hôte
d'un type particulier sont requises. Les variables indicateur sont utilisées
dans cette optique.
Une instruction INSERT peut contenir une variable indicateur comme suit :
EXEC SQL BEGIN DECLARE SECTION;
short int employee_number;
char employee_name[50];
char employee_initials[6];
char employee_phone[15];
short int ind_phone;
EXEC SQL END DECLARE SECTION;
/*
le programme fournit le numéro d'identification de
l'employé, son nom,
ses initiales et son numéro de téléphone
*/
if( /* numéro de téléphone inconnu */ ) {
ind_phone = -1;
} else {
ind_phone = 0;
}
EXEC SQL INSERT INTO Employee
VALUES (:employee_number, :employee_name,
:employee_initials, :employee_phone:ind_phone );
Si la valeur de la variable indicateur est égale à –1, une valeur NULL est
écrite. Si la valeur est égale à 0 (zéro), la valeur effective de
employee_phone est écrite.
Les variables indicateur sont également utilisées lors de la réception de
données de la base. Elles indiquent qu'une valeur NULL a été lue (indicateur
négatif). Si une valeur NULL est lue dans la base de données et qu'aucune
variable indicateur n'est fournie, une erreur est générée
(SQLE_NO_INDICATOR). Les erreurs sont décrites à la section suivante.
Utilisation de variables indicateur pour les valeurs tronquées
Les variables indicateur permettent d'indiquer les valeurs lues qui ont été
tronquées pour tenir dans une variable hôte. Ainsi, les applications peuvent
gérer la troncature de façon adéquate.

Chapitre 6 Programmation avec Embedded SQL
Si une valeur est tronquée à la lecture, la variable indicateur présente alors
une valeur positive qui contient la longueur effective de la valeur dans la
base de données avant troncature. Si cette valeur a une longueur supérieure à
32 767, la variable indicateur contient la valeur 32 767.
Utilisation de variables indicateur pour les erreurs de conversion
Par défaut, l'option de base de données CONVERSION_ERROR est définie
sur ON (activée) et tout échec de conversion des types de données provoque
une erreur, sans renvoi de ligne.
Vous pouvez utiliser des variables indicateur pour indiquer la colonne qui a
provoqué un échec de conversion du type de données. Si vous désactivez
(OFF) l'option de base de données CONVERSION_ERROR, les échecs de
conversion renvoient un avertissement CANNOT_CONVERT et non une
erreur. Si la colonne sur laquelle l'erreur s'est produite contient une variable
indicateur, cette dernière est prend la valeur -2.
Si vous définissez CONVERSION_ERROR sur OFF lorsque vous insérez
des données dans la base, la valeur NULL est insérée en cas d'échec de
conversion.
Récapitulatif des valeurs des variables indicateur
Le tableau ci-dessous illustre l’utilisation des variables indicateur.
Valeur
indicate
ur
Valeur fournie à la
base de données
Valeur reçue de la base de
données
> 0 Valeur de variable hôte Valeur reçue tronquée (valeur réelle
dans la variable indicateur)
0 Valeur de variable hôte Lecture aboutie ou
CONVERSION_ERROR définie sur
ON
–1 Valeur NULL Résultat NULL
–2 Valeur NULL Erreur de conversion (seulement
lorsque CONVERSION_ERROR est
définie sur OFF). SQLCODE indique
un avertissement
CANNOT_CONVERT
< –2 Valeur NULL Résultat NULL
203

Utilisation des variables hôte
204
$ Pour plus d'informations sur la récupération de valeurs longues,
reportez-vous à la section "Instruction GET DATA [ESQL]", page 459 du
document ASA Manuel de référence SQL.

Chapitre 6 Programmation avec Embedded SQL
Zone de communication SQL (SQLCA)
Codes d’erreur
SQLCA
Champs SQLCA
La zone de communication SQL (SQLCA) est une zone de mémoire qui
permet, pour chaque demande adressée à la base de données, de
communiquer des statistiques et de signaler des erreurs de l'application au
serveur de base de données, et inversement. La zone SQLCA joue le rôle de
descripteur pour le lien de communication entre l'application et la base de
données. Elle est transmise à toutes les fonctions de bibliothèque de base de
données devant communiquer avec le serveur de base de données. Elle est
également transmise implicitement à toutes les instructions SQL.
Une variable SQLCA globale est définie dans la bibliothèque d'interface. Le
préprocesseur génère deux références externes, l'une pour la variable
SQLCA globale et l'autre pour un pointeur sur cette variable. La référence
externe, sqlca, est de type SQLCA. Le pointeur est dénommé sqlcaptr. La
variable globale elle-même est déclarée dans la bibliothèque d'importation.
La zone SQLCA est définie par le fichier d'en-tête sqlca.h, inclus dans le
sous-répertoire h du répertoire d'installation.
En consultant la zone SQLCA, vous pouvez tester un code d'erreur
spécifique. Un code d'erreur s'affiche dans les champs sqlcode et sqlstate
lorsqu'une requête adressée à la base de données provoque une erreur (voir
ci-dessous). Il existe des macros en langage C permettant de référencer le
champ sqlcode, le champ sqlstate et d'autres champs.
Voici la signification des champs de la zone SQLCA :
♦ sqlcaid Champ de type caractère codé sur 8 octets contenant la chaîne
SQLCA, qui identifie la structure SQLCA. Ce champ facilite le
débogage lors de l'analyse du contenu de la mémoire.
♦ sqlcabc Entier long correspondant à la longueur de la structure SQLCA
(136 octets).
♦ sqlcode Entier long spécifiant le code d'erreur lorsque la base de
données détecte une erreur dans une demande. Le fichier d'en-tête
sqlerr.h. contient les définitions des codes d'erreur. Le code est égal à 0
(zéro) pour les opérations réussies, il est positif pour les avertissements
et négatif pour les erreurs.
$ Pour obtenir la liste complète des codes d'erreur, reportez-vous à la
section "Messages d'erreur de bases de données", page 1 du document
ASA Messages d’erreur.
205

Zone de communication SQL (SQLCA)
Tableau sqlerror
206
♦ sqlerrml Indique la longueur des données contenues dans le champ
sqlerrmc.
♦ sqlerrmc Chaîne de caractères (une, plusieurs ou aucune) à insérer dans
un message d'erreur. Certains messages d'erreur contiennent une ou
plusieurs chaînes de réservation (%1, %2, ...) qui sont remplacées par les
chaînes de ce champ.
Par exemple, si une erreur du type La table est introuvable est générée,
sqlerrmc contient le nom de la table qui est inséré à l'endroit approprié
dans le message d'erreur.
$ Pour obtenir la liste complète des messages d'erreur, reportez-vous
à la section "Messages d'erreur de bases de données", page 1 du
document ASA Messages d’erreur.
♦ sqlerrp Réservé.
♦ sqlerrd Table d'entiers longs.
♦ sqlwarn Réservé.
♦ sqlstate Valeur d'état SQLSTATE. La norme SQL ANSI (SQL-92)
définit un nouveau type de valeur renvoyée par une instruction SQL, en
plus de la valeur SQLCODE définie dans des normes antérieures. La
valeur SQLSTATE est toujours une chaîne de cinq caractères terminée
par une valeur NULL, divisée en une classe de deux caractères (les deux
premiers) et une sous-classe de trois caractères. Chaque caractère peut
être un chiffre compris entre 0 et 9 ou une lettre majuscule comprise
entre A et Z.
Toute classe ou sous-classe commençant par un chiffre compris entre 0
et 4 ou une lettre comprise entre A et H, est définie par la norme SQL ;
les autres classes ou sous-classes sont définies lors de la mise en oeuvre.
La valeur SQLSTATE '00000' signifie qu'il n'y a eu ni erreur ni
avertissement.
$ Pour connaître les autres valeurs SQLSTATE, reportez-vous à la
section "Messages d'erreur de bases de données", page 1 du document
ASA Messages d’erreur.
Le tableau du champ sqlerror contient les éléments ci-après :
♦ sqlerrd[1] (SQLIOCOUNT) Nombre effectif d'entrées/sorties requises
pour l'exécution d'une commande.
La base de données ne démarre pas à zéro pour chaque commande.
Votre programme peut attribuer la valeur zéro à cette variable avant
d'exécuter une séquence de commandes. Après l'exécution de la dernière
commande, ce nombre correspond au nombre total d'entrées/sorties pour
toute la séquence de commandes.

Chapitre 6 Programmation avec Embedded SQL
♦ sqlerrd[2] (SQLCOUNT) La valeur de ce champ est fonction de
l'instruction exécutée.
♦ Instructions INSERT, UPDATE, PUT et DELETE Nombre de lignes
traitées par l'instruction.
Sur un curseur OPEN, ce champ est complété soit avec le nombre
effectif de lignes du curseur (c'est-à-dire une valeur supérieure ou
égale à 0), soit avec une valeur estimée de ce nombre (nombre
négatif dont la valeur absolue est cette valeur estimée). C'est le
nombre effectif de lignes qui est pris en compte si le serveur de base
de données peut le calculer sans compter les lignes. La base de
données peut également être configurée de sorte à toujours renvoyer
le nombre réel de lignes par l'intermédiaire de l'option
ROW_COUNTS.
♦ Instruction de curseur FETCH Le champ SQLCOUNT est
complété si un avertissement SQLE_NOTFOUND est renvoyé. Cet
avertissement fournit le nombre de lignes hors de l'intervalle de
positions de curseur possibles renvoyées par une instruction
FETCH RELATIVE ou FETCH ABSOLUTE (un curseur peut se
trouver sur une ligne, avant la première ligne ou après la dernière
ligne). Dans le cas d'une extraction étendue, SQLCOUNT
correspond au nombre de lignes réellement extraites et il est
inférieur ou égal au nombre de lignes demandées. Durant une
extraction étendue, SQLE_NOTFOUND n'est pas défini.
$ Pour plus d'informations sur les extractions étendues, reportezvous
à la section "Extraction simultanée de plusieurs lignes",
page 215.
La valeur est 0 (zéro) si la ligne est introuvable bien que la position
soit correcte, par exemple, en exécutant FETCH RELATIVE 1
lorsque vous êtes positionné sur la dernière ligne d'un curseur. La
valeur est positive si la tentative d'extraction a été effectuée au-delà
de la dernière position du curseur, et négative si elle a été effectuée
avant le début du curseur.
♦ Instruction GET DATA Le champ SQLCOUNT contient la
longueur réelle de la valeur.
♦ Instruction DESCRIBE Dans la clause WITH VARIABLE
RESULT utilisée pour décrire des procédures pouvant générer
plusieurs jeux de résultats, SQLCOUNT est défini sur l'une des
valeurs ci-dessous :
♦ 0 Le jeu de résultats est variable : il convient de décrire l'appel
de procédure après chaque instruction OPEN.
207

Zone de communication SQL (SQLCA)
208
♦ 1 Le jeu de résultats est fixe : aucune nouvelle description n'est
requise.
Dans le cas d'une erreur de syntaxe (SQLE_SYNTAX_ERROR), ce
champ contient la position approximative du caractère dans la
chaîne de commande où l'erreur a été détectée.
♦ sqlerrd[3] (SQLIOESTIMATE) Nombre estimé d'entrées/sorties requises
pour l'exécution de la commande. Ce champ reçoit une valeur pour une
commande OPEN ou EXPLAIN.
Gestion de la zone SQLCA pour le code multi-thread ou réentrant
Vous pouvez insérer des instructions Embedded SQL dans du code
multi-threaded ou réentrant. Cependant, si vous utilisez une connexion
unique, vous êtes limité à une demande active par connexion. Dans une
application multi-threaded, ne faites pas appel à la même connexion de base
de données sur chaque thread, à moins de contrôler l'accès à l'aide d'un
sémaphore.
Il n'existe pas de restrictions sur l'utilisation de connexions séparées sur
chaque thread souhaitant accéder à la base de données. La bibliothèque
d'exécution utilise la zone SQLCA pour distinguer les différents contextes de
thread. Ainsi, chaque thread souhaitant accéder à la base de données doit
disposer de sa propre zone SQLCA.
Une connexion donnée n'est accessible qu'à partir d'une zone SQLCA
unique, à l'exception d'une instruction d'annulation, qui doit être formulée à
partir d'un thread distinct.
$ Pour plus d'informations sur l'annulation des requêtes, reportez-vous à
la section "Mise en oeuvre de la gestion des requêtes", page 245.
Utilisation de plusieurs zones SQLCA
v Pour gérer plusieurs zones SQLCA dans votre application :
1 Vous devez indiquer, pour le préprocesseur SQL, l'option qui génère du
code réentrant (-r). Ce code prend un peu plus de place et est un peu
plus lent, car il ne permet pas d'utiliser les variables globales initialisées
de manière statique. Cette contrainte est toutefois mineure.
2 Chaque zone SQLCA utilisée dans un programme doit être initialisée
par un appel de db_init, puis éliminée par un appel de db_fini.

Utilisation de plusieurs zones SQLCA
Chapitre 6 Programmation avec Embedded SQL
Attention
Sous NetWare, si db_fini n'est pas appelé pour chaque db_init, le
serveur de base de données et le serveur de fichiers NetWare
risquent de s'arrêter.
3 L’instruction Embedded SQL SET SQLCA (voir "Instruction SET
SQLCA [ESQL]", page 572 du document ASA Manuel de référence
SQL) permet d'indiquer au préprocesseur SQL d'utiliser une autre zone
SQLCA pour les requêtes adressées à la base de données. Généralement,
il s'agit d'une instruction de ce type : EXEC SQL SET SQLCA
'task_data->sqlca'. Elle est utilisée en début de programme ou dans un
fichier d'en-tête afin que la référence à la zone SQLCA pointe sur des
données spécifiques de la tâche. Cette instruction ne génère aucun code
et n'influe donc pas sur les performances. Elle modifie l'état interne du
préprocesseur pour que toute référence à la zone SQLCA utilise la
chaîne appropriée.
$ Pour plus d'informations sur la création de zones SQLCA, reportezvous
à la section "Instruction SET SQLCA [ESQL]", page 572 du document
ASA Manuel de référence SQL.
Vous pouvez utiliser plusieurs SQLCA dans tous les environnements
Embedded SQL pris en charge ; dans le cas du code réentrant, le recours à
des zones SQLCA multiples est obligatoire.
Les environnements dans lesquels vous devez faire appel à plusieurs SQLCA
sont détaillés ci-après :
♦ Applications Multi-threaded Si deux threads tentent d'accéder à la
même zone SQLCA, une option de contexte peut entraîner l'utilisation
simultanée de la même zone SQLCA par les deux threads. Chaque
thread doit disposer de sa propre zone SQLCA. Ce peut être également
le cas si une DLL utilisant Embedded SQL est appelée par plusieurs
threads de l'application.
♦ Bibliothèques de liens dynamiques (DLL) et bibliothèques
partagées Une DLL dispose d'un seul segment de données. Pendant que
le serveur de base de données traite une requête d'une application
donnée, il peut céder la priorité à une autre application qui lui envoie
également une requête. Si votre DLL utilise la zone SQLCA globale, les
deux applications utilisent cette dernière simultanément. Chaque
application Windows doit disposer de sa propre zone SQLCA.
209

Zone de communication SQL (SQLCA)
210
♦ DLL avec un segment de données Il est possible de créer une DLL
avec un segment de données unique ou avec un segment de données
pour chaque application. Si votre DLL ne comporte qu'un seul segment
de données, vous ne pouvez pas utiliser la zone SQLCA globale (tout
comme une DLL ne peut pas utiliser la zone SQLCA globale). Chaque
application doit disposer de sa propre zone SQLCA.
Gestion des connexions avec plusieurs zones SQLCA
Il n'est pas nécessaire d'avoir recours à plusieurs zones SQLCA pour vous
connecter à plusieurs bases de données ou pour disposer de plusieurs
connexions à une même base de données.
Chaque zone SQLCA peut avoir une connexion non nommée. Chaque zone
SQLCA dispose d'une connexion active (reportez-vous à la section
"Instruction SET CONNECTION [Interactive SQL] [ESQL]", page 563 du
document ASA Manuel de référence SQL). Toutes les opérations effectuées
par le biais d'une connexion à une base de données particulière doivent
utiliser la même zone SQLCA que celle employée pour établir la connexion.
Verrouillage d’enregistrement
Les opérations effectuées sur plusieurs connexions sont susceptibles d'être
soumises aux mécanismes de verrouillage d'enregistrement normaux et
risquent de se bloquer mutuellement, voire d'entraîner un interblocage.
Pour plus d'informations sur le verrouillage, reportez-vous au chapitre
"Transactions et niveaux d'isolement", page 93 du document ASA Guide
de l’utilisateur SQL.

Lecture de données
Chapitre 6 Programmation avec Embedded SQL
Dans Embedded SQL, la lecture de données s'effectue via l'instruction
SELECT. Deux cas peuvent se présenter :
♦ L’instruction SELECT renvoie au plus une ligne Utilisez une clause
INTO pour affecter les valeurs renvoyées directement aux variables
hôte.
$ Pour plus d'informations, reportez-vous à la section "Instruction
SELECT qui renvoie une ligne au plus", page 211.
♦ L’instruction SELECT renvoie plusieurs lignes Utilisez les curseurs
pour gérer les lignes du jeu de résultats.
$ Pour plus d'informations, reportez-vous à la section "Utilisation de
curseurs dans Embedded SQL", page 212.
$ Les types de données LONG VARCHAR et LONG BINARY sont
gérés différemment des autres types de données. Pour plus d'informations,
reportez-vous à la section "Récupération de données de type LONG",
page 236.
Instruction SELECT qui renvoie une ligne au plus
Exemple
Une requête de ligne unique n'extrait pas plus d'une ligne de la base de
données. L'instruction SELECT d'une requête de ligne unique comporte une
clause INTO, entre la liste de sélection et la clause FROM. La clause INTO
contient une liste de variables hôte destinées à recevoir la valeur de chaque
élément de la liste de sélection. Le nombre de variables hôte doit être
identique au nombre d'éléments de la liste de sélection. Les variables hôte
peuvent être accompagnées de variables indicateur afin d'indiquer les
résultats NULL.
Lors de l'exécution de l'instruction SELECT, le serveur de base de données
récupère les résultats et les place dans les variables hôte. Si le résultat de la
requête contient plusieurs lignes, le serveur renvoie une erreur.
Si la requête n'aboutit pas à la sélection d'une ligne, l'avertissement La ligne
est introuvable est renvoyé. Les erreurs et les avertissements sont renvoyés
dans la structure SQLCA, comme décrit dans la section "Zone de
communication SQL (SQLCA)", page 205.
Par exemple, l'extrait de code suivant renvoie 1 si une ligne de la table
"employee" est lue, 0 si aucune ligne n'est lue et –1 si une erreur se produit.
EXEC SQL BEGIN DECLARE SECTION;
long emp_id;
211

Lecture de données
212
char name[41];
char sex;
char birthdate[15];
short int ind_birthdate;
EXEC SQL END DECLARE SECTION;
. . .
int find_employee( long employee )
{
emp_id = employee;
EXEC SQL SELECT emp_fname ||
’ ’ || emp_lname, sex, birth_date
INTO :name, :sex,
:birthdate:ind_birthdate
FROM "DBA".employee
WHERE emp_id = :emp_id;
if( SQLCODE == SQLE_NOTFOUND ) {
return( 0 ); /* employé introuvable */
} else if( SQLCODE < 0 ) {
return( -1 ); /* erreur */
} else {
return( 1 ); /* employé trouvé */
}
}
Utilisation de curseurs dans Embedded SQL
Un curseur permet d'extraire les lignes du jeu de résultats d'une requête, qui
comporte plusieurs lignes. Un curseur est un descripteur ou un identificateur
pour la requête SQL, et une position dans le jeu de résultats.
$ Pour plus d'informations sur les curseurs, reportez-vous à la section
"Utilisation des curseurs", page 20.
v Pour gérer un curseur dans Embedded SQL :
1 Déclarez un curseur pour une instruction SELECT donnée à l'aide de
l'instruction DECLARE.
2 Ouvrez le curseur à l'aide de l'instruction OPEN.
3 Récupérez une par une les lignes du curseur à l'aide de l'instruction
FETCH.
4 Continuez l'extraction des lignes jusqu'à ce que l'avertissement La ligne
est introuvable soit renvoyé.
Les erreurs et les avertissements sont renvoyés dans la structure
SQLCA, décrite à la section "Zone de communication SQL (SQLCA)",
page 205.

Positionnement du
curseur
Chapitre 6 Programmation avec Embedded SQL
5 Fermez le curseur à l'aide de l'instruction CLOSE.
Par défaut, les curseurs sont automatiquement refermés à la fin d'une
transaction (lors du COMMIT ou du ROLLBACK). Les curseurs ouverts
avec une clause WITH HOLD restent ouverts pour les transactions suivantes,
jusqu'à ce qu'ils soient explicitement refermés.
Voici un exemple simple d'utilisation d'un curseur :
void print_employees( void )
{
EXEC SQL BEGIN DECLARE SECTION;
char name[50];
char sex;
char birthdate[15];
short int ind_birthdate;
EXEC SQL END DECLARE SECTION;
EXEC SQL DECLARE C1 CURSOR FOR
SELECT emp_fname || ’ ’ || emp_lname,
sex, birth_date
FROM "DBA".employee;
EXEC SQL OPEN C1;
for( ;; ) {
EXEC SQL FETCH C1 INTO :name, :sex,
:birthdate:ind_birthdate;
if( SQLCODE == SQLE_NOTFOUND ) {
break;
} else if( SQLCODE < 0 ) {
break;
}
if( ind_birthdate < 0 ) {
strcpy( birthdate, "UNKNOWN" );
}
printf( "Nom : %s Sexe : %c Date de naissance :
%s.n",name, sex, birthdate );
}
EXEC SQL CLOSE C1;
}
$ Des exemples complets d'utilisation des curseurs sont fournis aux
sections "Exemple de curseur statique", page 189 et "Exemple de curseur
dynamique", page 189.
Un curseur peut occuper l'une des trois positions suivantes :
♦ sur une ligne quelconque,
♦ avant la première ligne,
♦ après la dernière ligne.
213

Lecture de données
214
Lors de son ouverture, un curseur est placé avant la première ligne. La
commande FETCH permet de modifier cette position (reportez-vous à la
section "Instruction FETCH [ESQL] [SP]", page 446 du document ASA
Manuel de référence SQL). Il peut occuper une position absolue à partir du
début ou de la fin des résultats de la requête. Il peut aussi être déplacé
relativement à sa position courante.
Il existe une version positionnée des instructions UPDATE et DELETE, qui
peut servir à mettre à jour ou à supprimer la ligne à la position courante du
curseur. Si le curseur est positionné avant la première ligne ou après la
dernière ligne, l'erreur Aucune ligne de curseur n’est actuellement
sélectionnée est renvoyée.
L'instruction PUT permet d'insérer une ligne dans un curseur.

Problèmes liés au
positionnement du
curseur
Chapitre 6 Programmation avec Embedded SQL
Les insertions et certaines mises à jour apportées aux curseurs DYNAMIC
SCROLL (à défilement dynamique) peuvent engendrer des problèmes de
positionnement. Le serveur ne place les lignes insérées dans un curseur à une
position prévisible que si l'instruction SELECT comporte une clause
ORDER BY. Dans certains cas, la ligne insérée n'apparaît pas avant que le
curseur soit fermé puis rouvert.
Avec Adaptive Server Anywhere, ce problème survient si une table
temporaire a dû être créée pour ouvrir le curseur.
$ Pour plus d'informations, reportez-vous à la section "Utilisation de
tables de travail dans le traitement des requêtes", page 170 du document ASA
Guide de l’utilisateur SQL.
L'instruction UPDATE peut provoquer le déplacement d'une ligne dans le
curseur. Cela se produit si le curseur inclut une clause ORDER BY qui
utilise un index existant (aucune table temporaire n'est créée).
Extraction simultanée de plusieurs lignes
Il est possible de modifier l’instruction FETCH afin d’extraire plusieurs
lignes simultanément, ce qui peut améliorer les performances. On parle alors
d'extraction étendue ou de lecture de tableau.
$ Adaptive Server Anywhere prend également en charge des instructions
PUT et INSERT étendues. Pour plus d'informations sur ces instructions,
reportez-vous aux sections "Instruction PUT [ESQL]", page 523 du
document ASA Manuel de référence SQL et "Instruction EXECUTE
[ESQL]", page 437 du document ASA Manuel de référence SQL.
Pour effectuer des extractions étendues en Embedded SQL, vous devez
inclure l'instruction FETCH dans votre code comme suit :
EXEC SQL FETCH . . . ARRAY nnn
où ARRAY nnn est le dernier élément de l'instruction. Le nombre
d'extractions nnn peut être une variable hôte. Le nombre de variables de la
SQLDA doit correspondre au produit de nnn et du nombre de colonnes par
ligne. La première ligne est placée dans les variables SQLDA 0 (zéro) à
(colonnes par ligne)-1, etc.
Le type de chaque colonne doit être identique dans chaque ligne de
la SQLDA. Dans le cas contraire, une erreur SQLDA_INCONSISTENT est
renvoyée.
215

Lecture de données
Exemple
216
Le serveur renvoie dans SQLCOUNT le nombre d’enregistrements extraits,
qui est toujours supérieur à zéro, sauf s'il y a des erreurs ou des
avertissements. Dans le cas d'une extraction étendue, une valeur
SQLCOUNT égale à 1 sans condition d'erreur indique qu'une ligne correcte
a été extraite.
L'exemple suivant illustre l'utilisation d'extractions étendues. Ce code figure
dans le fichier samples\ASA\esqlwidefetch\widefetch.sqc du répertoire
SQL Anywhere.

#include
#include
#include
#include "sqldef.h"
EXEC SQL INCLUDE SQLCA;
Chapitre 6 Programmation avec Embedded SQL
EXEC SQL WHENEVER SQLERROR { PrintSQLError();
goto err; };
static void PrintSQLError()
/*************************/
{
char buffer[200];
}
printf( "erreur SQL %d -- %s\n",
SQLCODE,
sqlerror_message( &sqlca,
buffer,
sizeof( buffer ) ) );
static SQLDA * PrepareSQLDA(
a_sql_statement_number stat0,
unsigned width,
unsigned *cols_per_row )
/*********************************************/
/* Allouez une SQLDA pour récupérer des lignes à partir
de l'instruction identifiée par "stat0". "width"
les lignes sont extraites à chaque requête FETCH.
Le nombre de colonnes par ligne est affecté à
"cols_per_row". */
{
int num_cols;
unsigned row, col, offset;
SQLDA * sqlda;
EXEC SQL BEGIN DECLARE SECTION;
a_sql_statement_number stat;
EXEC SQL END DECLARE SECTION;
stat = stat0;
sqlda = alloc_sqlda( 100 );
if( sqlda == NULL ) return( NULL );
EXEC SQL DESCRIBE :stat INTO sqlda;
*cols_per_row = num_cols = sqlda->sqld;
if( num_cols * width > sqlda->sqln ) {
free_sqlda( sqlda );
sqlda = alloc_sqlda( num_cols * width );
if( sqlda == NULL ) return( NULL );
EXEC SQL DESCRIBE :stat INTO sqlda;
}
// copie dans les lignes (étendues) suivantes
// la première ligne contenue dans SQLDA
217

Lecture de données
218
// définie par describe
sqlda->sqld = num_cols * width;
offset = num_cols;
for( row = 1; row < width; row++ ) {
for( col = 0;
col < num_cols;
col++, offset++ ) {
sqlda->sqlvar[offset].sqltype =
sqlda->sqlvar[col].sqltype;
sqlda->sqlvar[offset].sqllen =
sqlda->sqlvar[col].sqllen;
// facultatif : copie le nom des colonnes
décrites
memcpy( &sqlda->sqlvar[offset].sqlname,
&sqlda->sqlvar[col].sqlname,
sizeof( sqlda->sqlvar[0].sqlname )
);
}
}
fill_s_sqlda( sqlda, 40 );
return( sqlda );
err:
return( NULL );
}
static void PrintFetchedRows( SQLDA * sqlda,
unsigned cols_per_row )
/******************************************/
/* Imprime les lignes déjà extraites de manière étendue
dans SQLDA */
{
long rows_fetched;
int row, col, offset;
}
if( SQLCOUNT == 0 ) {
rows_fetched = 1;
} else {
rows_fetched = SQLCOUNT;
}
printf( "%d lignes extraites :\n", rows_fetched );
for( row = 0; row < rows_fetched; row++ ) {
for( col = 0; col < cols_per_row; col++ ) {
offset = row * cols_per_row + col;
printf( " \"%s\"",
(char *)sqlda->sqlvar[offset]
.sqldata );
}
printf( "\n" );
}

Chapitre 6 Programmation avec Embedded SQL
static int DoQuery( char * query_str0,
unsigned fetch_width0 )
/*****************************************/
/* Instruction select "query_str0" pour extraction
/* étendue avec une largeur de "fetch_width0"
* lignes " */
{
SQLDA * sqlda;
unsigned cols_per_row;
EXEC SQL BEGIN DECLARE SECTION;
a_sql_statement_number stat;
char * query_str;
unsigned fetch_width;
EXEC SQL END DECLARE SECTION;
query_str = query_str0;
fetch_width = fetch_width0;
EXEC SQL PREPARE :stat FROM :query_str;
EXEC SQL DECLARE QCURSOR CURSOR FOR :stat
FOR READ ONLY;
EXEC SQL OPEN QCURSOR;
sqlda = PrepareSQLDA( stat,
fetch_width,
&cols_per_row );
if( sqlda == NULL ) {
printf( "Erreur d'allocation SQLDA\n" );
return( SQLE_NO_MEMORY );
}
for( ;; ) {
EXEC SQL FETCH QCURSOR INTO DESCRIPTOR sqlda
ARRAY :fetch_width;
if( SQLCODE != SQLE_NOERROR ) break;
PrintFetchedRows( sqlda, cols_per_row );
}
EXEC SQL CLOSE QCURSOR;
EXEC SQL DROP STATEMENT :stat;
free_filled_sqlda( sqlda );
err:
return( SQLCODE );
}
void main( int argc, char *argv[] )
/*********************************/
/* Le premier argument facultatif est une instruction
/* select,
* le second argument est l'étendue de l'extraction*/
{
char *query_str =
"select emp_fname, emp_lname from employee";
unsigned fetch_width = 10;
219

Lecture de données
Remarques sur
l’utilisation des
extractions
étendues
220
if( argc > 1 ) {
query_str = argv[1];
if( argc > 2 ) {
fetch_width = atoi( argv[2] );
if( fetch_width < 2 ) {
fetch_width = 2;
}
}
}
db_init( &sqlca );
EXEC SQL CONNECT "dba" IDENTIFIED BY "sql";
DoQuery( query_str, fetch_width );
EXEC SQL DISCONNECT;
err:
db_fini( &sqlca );
}
♦ Dans la fonction PrepareSQLDA, la mémoire SQLDA est allouée au
travers de la fonction alloc_sqlda. Cela permet de réserver de l'espace
pour les variables indicateur sans utiliser la fonction alloc_sqlda_noind.
♦ Lorsque le nombre de lignes extraites est inférieur au nombre demandé
mais pas égal à zéro (à la fin du curseur, par exemple), les éléments
SQLDA correspondant aux lignes non extraites sont renvoyés en tant
que valeurs NULL dans la valeur indicateur. En l'absence de variable
indicateur, une erreur est générée (SQLE_NO_INDICATOR : pas de
variable indicateur pour résultat NULL).
♦ En cas de mise à jour d'une ligne qui est extraite (ce qui génère un
avertissement SQLE_ROW_UPDATED_WARNING) la recherche
s'arrête sur la ligne qui a provoqué l'avertissement. Les valeurs de toutes
les lignes traitées jusqu'à cette dernière (ligne ayant provoqué
l'avertissement comprise) sont renvoyées. SQLCOUNT contient le
nombre de lignes extraites, y compris celle à l'origine de l'avertissement.
Tous les éléments SQLDA restants sont marqués comme valeurs NULL.
♦ En cas de suppression ou de verrouillage d'une ligne qui est extraite (ce
qui provoque la génération d'une erreur SQLE_NO_CURRENT_ROW
ou SQLE_LOCKED) SQLCOUNT contient alors le nombre de lignes
lues avant l'erreur. La ligne à l'origine de l'erreur n'est pas incluse. La
zone SQLDA ne contient pas les valeurs des lignes, les valeurs SQLDA
n'étant pas renvoyées en cas d'erreur. La valeur SQLCOUNT peut servir,
si nécessaire, à repositionner le curseur de façon qu'il puisse lire les
lignes.

SQL statique et SQL dynamique
Instructions SQL statiques
Instructions SQL dynamiques
Chapitre 6 Programmation avec Embedded SQL
Il existe deux façons d'imbriquer des instructions SQL dans un programme
en langage C :
♦ Instructions statiques
♦ Instructions dynamiques
Jusqu'à présent, nous avons traité des instructions SQL statiques. La présente
section fournit une comparaison entre les instructions SQL statiques et
dynamiques.
Toutes les instructions de manipulation et de définition de données SQL
standard peuvent être imbriquées dans un programme en langage C ; pour ce
faire, elles doivent être précédées d'EXEC SQL et se terminer par un pointvirgule
(;). Ces instructions sont dites statiques.
Les instructions statiques peuvent contenir des références à des variables
hôte, comme indiqué dans la section "Utilisation des variables hôte",
page 196. Tous les exemples proposés jusqu'ici utilisaient des instructions
Embedded SQL statiques.
Les variables hôte peuvent remplacer uniquement des constantes de type
chaîne ou des constantes numériques. Elles ne peuvent se substituer à un
nom de colonne ou de table ; de telles opérations requièrent des instructions
dynamiques.
En langage C, les chaînes sont stockées dans des tableaux de caractères. Les
instructions dynamiques sont créées dans des chaînes en langage C. Elles
peuvent ensuite être exécutées à l'aide des instructions PREPARE et
EXECUTE. Ces instructions SQL ne peuvent pas référencer des variables
hôte de la même façon que les instructions statiques, les variables C n'étant
pas accessibles par leur nom lorsque le programme est en cours d'exécution.
221

SQL statique et SQL dynamique
Exemple
222
Pour transférer les informations entre les instructions et les variables en
langage C, on utilise une structure de données appelée Zone descripteur
SQL (SQLDA). Elle peut être définie par le préprocesseur SQL si vous
spécifiez une liste de variables hôte dans la clause USING de la commande
EXECUTE. Ces variables correspondent, de par leur position, à des marques
de réservation, situées dans la position appropriée de la chaîne de commande
préparée.
$ Pour plus d'informations sur SQLDA, reportez-vous à la section "Zone
descripteur SQL (SQLDA)", page 226.
Une marque de réservation est incluse dans l'instruction pour indiquer où
l'on doit accéder aux variables hôte. Une marque de réservation est un point
d'interrogation (?) ou une référence de variable hôte comme dans une
instruction statique (c'est-à-dire un nom de variable hôte précédé d'un signe
deux-points). Dans ce dernier cas, le nom de variable hôte utilisé dans le
texte de l'instruction sert uniquement de marque de réservation et indique
une référence à la zone descripteur SQL.
Une variable hôte permettant de transmettre des informations à la base de
données est appelée variable de liaison.
Par exemple :
EXEC SQL BEGIN DECLARE SECTION;
char comm[200];
char address[30];
char city[20];
short int cityind;
long empnum;
EXEC SQL END DECLARE SECTION;
. . .
sprintf( comm, "update %s set address = :?,
city = :?"
" where employee_number = :?",
tablename );
EXEC SQL PREPARE S1 FROM :comm;
EXEC SQL EXECUTE S1 USING :address, :city:cityind,
:empnum;
Cette méthode requiert de la part du programmeur qu'il sache combien de
variables hôte sont incluses dans l'instruction. Or, ce n'est généralement pas
le cas. Vous pouvez donc définir votre propre structure SQLDA et la
spécifier dans la clause USING de la commande EXECUTE.
L'instruction DESCRIBE BIND VARIABLES renvoie le nom des variables
de liaison trouvées dans une instruction préparée. Un programme en
langage C gère ainsi plus facilement les variables hôte. La méthode générale
est la suivante :
EXEC SQL BEGIN DECLARE SECTION;
char comm[200];

Contenu de la
zone SQLDA
Variables
indicateurs et
valeur NULL
Chapitre 6 Programmation avec Embedded SQL
EXEC SQL END DECLARE SECTION;
. . .
sprintf( comm, "update %s set address = :address,
city = :city"
" where employee_number = :empnum",
tablename );
EXEC SQL PREPARE S1 FROM :comm;
/* Suppose qu'il n'existe pas plus de 10 variables hôte.
Reportez-vous à l'exemple suivant si vous ne pouvez pas
en limiter le nombre */
sqlda = alloc_sqlda( 10 );
EXEC SQL DESCRIBE BIND VARIABLES FOR S1 USING DESCRIPTOR
sqlda;
/* sqlda->sqld indique le nombre de variables hôte. */
/* Renseigne les champs SQLDA_VARIABLE avec des valeurs
fondées sur
les noms de champ de sqlda */
. . .
EXEC SQL EXECUTE S1 USING DESCRIPTOR sqlda;
free_sqlda( sqlda );
La zone SQLDA consiste en un tableau de descripteurs de variables. Chaque
descripteur détaille les attributs de la variable C correspondante ou
l'emplacement dans lequel la base de données enregistre les données (ou d'où
elle les récupère), comme suit :
♦ type de données
♦ longueur si type correspond à une chaîne,
♦ précision et échelle si type est numérique,
♦ adresse mémoire,
♦ variable indicateur.
$ Pour obtenir une description exhaustive de la structure SQLDA,
reportez-vous à la section "Zone descripteur SQL (SQLDA)", page 226.
La variable indicateur permet de transmettre une valeur NULL à la base de
données ou de récupérer une valeur NULL de cette dernière. Elle est
également utilisée par le serveur de base de données pour signaler les
conditions de troncature rencontrées lors d'une opération de base de données.
La variable indicateur prend une valeur positive lorsque l'espace destiné à
recevoir une valeur de la base de données est insuffisant.
$ Pour plus d'informations, reportez-vous à la section "Variables
indicateur", page 201.
223

SQL statique et SQL dynamique
Instruction SELECT dynamique
224
Une instruction SELECT qui ne renvoie qu'une seule ligne peut être préparée
dynamiquement et suivie d'une instruction EXECUTE avec une clause INTO
qui extrait un résultat uniligne. En revanche, les instructions SELECT qui
renvoient plusieurs lignes sont gérées à l'aide de curseurs dynamiques.
Avec les curseurs dynamiques, les résultats sont placés dans une liste de
variables hôte ou dans une SQLDA spécifiée dans l'instruction FETCH
(FETCH INTO ou FETCH USING DESCRIPTOR). Le nombre d'éléments
de la liste de sélection n'étant généralement pas connu du programmeur, la
méthode utilisant une SQLDA est la plus courante. L'instruction
DESCRIBE SELECT LIST définit une SQLDA avec les types des éléments
de la liste de sélection. De l'espace est alors alloué pour les valeurs via la
fonction fill_sqlda() et les informations sont extraites à l'aide de l'instruction
FETCH USING DESCRIPTOR.
Le scénario classique est le suivant :
EXEC SQL BEGIN DECLARE SECTION;
char comm[200];
EXEC SQL END DECLARE SECTION;
int actual_size;
SQLDA * sqlda;
. . .
sprintf( comm, "select * from %s", table_name );
EXEC SQL PREPARE S1 FROM :comm;
/* Le résultat est initialement estimé à 10 colonnes.
S'il est faux,
il est corrigé après la première instruction
DESCRIBE par l'allocation d'une nouvelle SQLDA et la
réexécution de DESCRIBE . */
sqlda = alloc_sqlda( 10 );
EXEC SQL DESCRIBE SELECT LIST FOR S1 USING DESCRIPTOR
sqlda;
if( sqlda->sqld > sqlda->sqln ) {
actual_size = sqlda->sqld;
free_sqlda( sqlda );
sqlda = alloc_sqlda( actual_size );
EXEC SQL DESCRIBE SELECT LIST FOR S1
USING DESCRIPTOR sqlda;
}
fill_sqlda( sqlda );
EXEC SQL DECLARE C1 CURSOR FOR S1;
EXEC SQL OPEN C1;
EXEC SQL WHENEVER NOTFOUND {break};
for( ;; ) {
EXEC SQL FETCH C1 USING DESCRIPTOR sqlda;
/* traite les données */
}

Chapitre 6 Programmation avec Embedded SQL
EXEC SQL CLOSE C1;
EXEC SQL DROP STATEMENT S1;
Suppression des instructions après utilisation
Afin d'éviter toute occupation inutile des ressources, assurez-vous que les
instructions sont supprimées après leur utilisation.
$ Pour plus d'informations sur l'utilisation des curseurs dans une
instruction SELECT dynamique, reportez-vous à la section "Exemple de
curseur dynamique", page 189.
$ Pour plus d'informations sur les fonctions ci-dessus, reportez-vous à la
section "Références des fonctions de bibliothèque", page 251.
225

Zone descripteur SQL (SQLDA)
Zone descripteur SQL (SQLDA)
Le fichier d'en-tête SQLDA
226
La zone SQLDA (zone descripteur SQL) est une structure d'interface utilisée
pour les instructions SQL dynamiques. Cette structure transmet, vers et
depuis la base de données, des informations concernant les variables hôte et
le résultat des instructions SELECT. La zone SQLDA est définie dans le
fichier d'en-tête sqlda.h.
$ Vous pouvez utiliser certaines fonctions de la bibliothèque d'interface
ou de la DLL de la base de données pour gérer les zones SQLDA. Pour en
obtenir la description, reportez-vous à la section "Références des fonctions
de bibliothèque", page 251.
Lorsque des instructions SQL statiques appellent des variables hôte, le
préprocesseur définit une zone SQLDA pour ces variables. Cette zone
SQLDA est utilisée ensuite pour les transmissions vers et depuis le serveur
de base de données.
Le contenu du fichier sqlda.h se présente comme suit :
#ifndef _SQLDA_H_INCLUDED
#define _SQLDA_H_INCLUDED
#define II_SQLDA
#include "sqlca.h"
#if defined( _SQL_PACK_STRUCTURES )
#include "pshpk1.h"
#endif
#define SQL_MAX_NAME_LEN 30
#define _sqldafar _sqlfar
typedef short int a_sql_type;
struct sqlname {
short int length; /* longueur des données caractère /
char data[ SQL_MAX_NAME_LEN ]; /* données */
};
struct sqlvar { /* tableau de descripteurs de variable /
short int sqltype; /* type de variable hôte /
short int sqllen; /* longueur de variable hôte */
void _sqldafar sqldata; /* adresse de la variable */
short int _sqldafar sqlind; /* pointeur indicateur variable */
struct sqlname sqlname;
};

Chapitre 6 Programmation avec Embedded SQL
struct sqlda{
unsigned char sqldaid[8]; /* eye catcher "SQLDA"*/
a_SQL_int32 sqldabc; /* longueur de la structure sqlda*/
short int sqln; /* taille du descripteur en nombre d'entrées /
short int sqld; / nombre de variables identifiées par DESCRIBE*/
struct sqlvar sqlvar[1]; /* tableau des descripteurs de
variables */
};
#define SCALE(sqllen) ((sqllen)/256)
#define PRECISION(sqllen) ((sqllen)&0xff)
#define SET_PRECISION_SCALE(sqllen,precision,scale) \
sqllen = (scale)*256 + (precision)
#define DECIMALSTORAGE(sqllen) (PRECISION(sqllen)/2 + 1)
typedef struct sqlda SQLDA;
typedef struct sqlvar SQLVAR, SQLDA_VARIABLE;
typedef struct sqlname SQLNAME, SQLDA_NAME;
#ifndef SQLDASIZE
#define SQLDASIZE(n) ( sizeof( struct sqlda ) + \
(n-1) * sizeof( struct sqlvar) )
#endif
#if defined( _SQL_PACK_STRUCTURES )
#include "poppk.h"
#endif
#endif
Champs SQLDA
Le tableau suivant décrit les champs de la zone SQLDA :
Champ Description
sqldaid Champ de type caractère codé sur 8 octets contenant la chaîne
SQLDA, qui identifie la structure SQLDA. Ce champ facilite le
débogage lors de l'analyse du contenu de la mémoire.
sqldabc Entier long contenant la longueur de la structure SQLDA.
sqln Nombre de descripteurs de variable du tableau sqlvar.
sqld Nombre de descripteurs de variable corrects (contenant des
informations de description d'une variable hôte). Ce champ est
défini par l'instruction DESCRIBE ou par le programmeur lorsque
des données sont fournies au serveur.
sqlvar Tableau de descripteurs de type struct sqlvar, décrivant chacun
une variable hôte.
227

Zone descripteur SQL (SQLDA)
Descriptions des variables hôte de la zone SQLDA
228
Chacune des structures sqlvar de la zone SQLDA décrit une variable hôte.
Les champs de la structure sqlvar ont les significations suivantes :
♦ sqltype Type de la variable décrite par le descripteur (reportez-vous à la
section "Types de données Embedded SQL", page 192).
Le bit de poids faible indique si les valeurs NULL sont admises. Les
définitions des types admis et des constantes sont fournies dans le fichier
d'en-tête sqldef.h.
Ce champ est renseigné par l'instruction DESCRIBE. Vous pouvez le
définir avec n'importe quel type lorsque vous fournissez ou récupérez
des données à partir du serveur de base de données. Le cas échéant, le
type est automatiquement converti.
♦ sqllen Longueur de la variable. La signification de la longueur dépend
du type indiqué et de la façon dont la zone SQLDA est utilisée.
Pour les variables de type DECIMAL, ce champ est divisé en deux
champs de 1 octet. L'octet de poids fort est la précision et l'octet de poids
faible, l'échelle. Par précision, on entend le nombre total de chiffres. Par
échelle, on entend le nombre de chiffres après la virgule.
Pour les types de données LONG VARCHAR et LONG BINARY, le
champ array_len des structures de type de données
DT_LONGBINARY et DT_LONGVARCHAR est utilisé à la place du
champ sqllen.
$ Pour plus d'informations sur le champ de longueur, reportez-vous à
la section "Valeurs du champ sqllen de la zone SQLDA", page 229.
♦ sqldata Pointeur de quatre octets sur la mémoire occupée par cette
variable. Cette mémoire doit correspondre aux champs sqltype et sqllen.
$ Pour plus d'informations sur les formats de stockage, reportez-vous
à la section "Types de données Embedded SQL", page 192.
Pour les commandes UPDATE et INSERT, cette variable n'est pas
impliquée dans l'opération si le pointeur sqldata est un pointeur NULL.
Pour la commande FETCH, aucune donnée n'est renvoyée si le pointeur
sqldata est un pointeur NULL. En d'autres termes, la colonne renvoyée
par le pointeur sqldata est une colonne non liée.
Si l’instruction DESCRIBE utilise un type LONG NAMES, ce champ
contient alors le nom long de la colonne du jeu de résultats. Si, par
ailleurs, l'instruction DESCRIBE est une instruction de type DESCRIBE
USER TYPES, ce champ contient le nom long du type de données défini
par l'utilisateur et non la colonne. S'il s'agit d'un type de base, le champ
reste vide.

Chapitre 6 Programmation avec Embedded SQL
♦ sqlind Pointeur sur la valeur indicateur. Une valeur indicateur est de
type short int. Une valeur indicateur négative indique une valeur
NULL. Une valeur indicateur positive indique que la variable a été
tronquée par une instruction FETCH ; elle contient la longueur des
données avant troncature. La valeur –2 indique une erreur de conversion
si l'option de base de données CONVERSION_ERROR est définie à
OFF.
$ Pour plus d'informations, reportez-vous à la section "Variables
indicateur", page 201.
Si le pointeur sqlind est le pointeur NULL, aucune variable indicateur
n'existe pour cette variable hôte.
Le champ sqlind est également utilisé par l'instruction DESCRIBE pour
indiquer les types de paramètre. S'il s'agit d'un type de données défini
par l'utilisateur, ce champ a la valeur DT_HAS_USERTYPE_INFO.
Dans ce cas, vous pouvez exécuter DESCRIBE USER TYPES pour
obtenir des informations sur les types de données définis par l'utilisateur.
♦ sqlname Structure de type VARCHAR qui contient un buffer de
longueur et de caractère. Elle est renseignée par une instruction
DESCRIBE et n'a pas d'autre utilisation. Ce champ n'a pas la même
signification pour les deux formats de l'instruction DESCRIBE :
♦ SELECT LIST Le buffer de nom est complété avec l'en-tête de
colonne de l'élément correspondant dans la liste de sélection.
♦ BIND VARIABLES Le buffer de nom est complété soit avec le nom
de la variable hôte utilisée comme variable de liaison, soit avec le
signe "?" si un marqueur de paramètre non nommé est utilisé.
Dans une commande DESCRIBE SELECT LIST, les variables
indicateur présentes sont assorties d'un drapeau signalant si l'élément de
liste de sélection peut être ou non mis à jour. Vous trouverez plus
d'informations sur cet indicateur dans le fichier d'en-tête sqldef.h.
Si l'instruction DESCRIBE est de type DESCRIBE USER TYPES, ce
champ contient le nom long du type de données défini par l'utilisateur et
non la colonne. S'il s'agit d'un type de base, le champ reste vide.
Valeurs du champ sqllen de la zone SQLDA
La longueur du champ sqllen de la structure sqlvar d'une zone SQLDA
intervient dans trois types d'interaction avec le serveur de base de données :
229

Zone descripteur SQL (SQLDA)
Description de valeurs
230
♦ Description de valeurs L’instruction DESCRIBE permet d’obtenir des
informations sur les variables hôte nécessaires pour stocker les données
extraites de la base de données ou pour transmettre des données à cette
base.
$ Reportez-vous à la section "Description de valeurs", page 230.
♦ Extraction de valeurs Extraction de valeurs de la base de données.
$ Reportez-vous à la section "Extraction de valeurs", page 233.
♦ Envoi de valeurs Envoi d'informations à la base de données.
$ Reportez-vous à la section "Envoi de valeurs", page 231.
Cette section décrit ces interactions.
Les tableaux ci-dessous présentent ces interactions. Ces tableaux donnent la
liste des types de constante d'interface (types DT_) figurant dans le fichier
d'en-tête sqldef.h. Ces constantes sont en général placées dans le champ
SQLDA sqltype.
$ Pour plus d'informations sur les valeurs du champ sqltype, reportezvous
à la section "Types de données Embedded SQL", page 192.
Dans du SQL statique, une zone SQLDA est aussi utilisée, mais est générée
et entièrement complétée par le préprocesseur SQL. Dans ce cas, les tableaux
fournissent la correspondance entre les types de variable hôte du langage C
et les constantes d'interface.
Le tableau ci-après indique les valeurs des éléments de structure sqllen et
sqltype renvoyées par la commande DESCRIBE pour les différents types de
base de données (instructions SELECT LIST et BIND VARIABLE
DESCRIBE). Dans le cas d'un type de base de données défini par
l'utilisateur, c'est le type sous-jacent qui est décrit.
Votre programme peut utiliser les types et les longueurs renvoyés par une
instruction DESCRIBE, mais vous pouvez avoir recours à un autre type. Le
serveur de base de données effectue les conversions nécessaires entre deux
types différents. La mémoire sur laquelle pointe le champ sqldata doit
correspondre aux champs sqltype et sqllen.
$ Pour plus d'informations sur les types de données Embedded SQL,
reportez-vous à la section "Types de données Embedded SQL", page 192.

Envoi de valeurs
Type de champ de
base de données
Chapitre 6 Programmation avec Embedded SQL
Type Embedded SQL
renvoyé
BIGINT DT_BIGINT 8
BINARY(n) DT_BINARY n
BIT DT_BIT 1
CHAR(n) DT_FIXCHAR n
Longueur renvoyée
par l'instruction
DESCRIBE
DATE DT_DATE Longueur de la chaîne
formatée la plus longue
DECIMAL(p,s) DT_DECIMAL p = octet de poids fort du
champ "longueur" de la
zone SQLDA, s = octet de
poids faible
DOUBLE DT_DOUBLE 8
FLOAT DT_FLOAT 4
INT DT_INT 4
LONG BINARY DT_LONGBINARY 32767
LONG VARCHAR DT_LONGVARCHAR 32767
REAL DT_FLOAT 4
SMALLINT DT_SMALLINT 2
TIME DT_TIME Longueur de la chaîne
formatée la plus longue
TIMESTAMP DT_TIMESTAMP Longueur de la chaîne
formatée la plus longue
TINYINT DT_TINYINT 1
UNSIGNED BIGINT DT_UNSBIGINT 8
UNSIGNED INT DT_UNSINT 4
UNSIGNED
SMALLINT
DT_UNSSMALLINT 2
VARCHAR(n) DT_VARCHAR n
Le tableau ci-après montre la manière dont vous devez spécifier les
longueurs de valeur lorsque vous fournissez des données au serveur dans la
zone SQLDA.
231

Zone descripteur SQL (SQLDA)
232
Dans ce cas, seuls les types de données répertoriés dans ce tableau sont
admis. Les types DT_DATE, DT_TIME et DT_TIMESTAMP sont gérés de
la même façon que DT_STRING lorsque des informations sont fournies à la
base de données ; la valeur doit être une chaîne de caractères terminée par
une valeur NULL dans un format de date approprié.
Type de données
Embedded SQL
Opération du programme pour définir
la longueur
DT_BIGINT Aucune opération requise
DT_BINARY(n) Longueur du champ de la structure BINARY
DT_BIT Aucune opération requise
DT_DATE Longueur déterminée par \0 en fin de chaîne
DT_DECIMAL(p,s) p = octet de poids fort du champ "longueur"
de la zone SQLDA, s = octet de poids faible
DT_DOUBLE Aucune opération requise
DT_FIXCHAR(n) Longueur de la chaîne déterminée par la
valeur du champ "longueur" de la zone
SQLDA
DT_FLOAT Aucune opération requise
DT_INT Aucune opération requise
DT_LONGBINARY Champ "longueur" ignoré. Reportez-vous à
la section "Envoi de données de type
LONG", page 238.
DT_LONGVARCHAR Champ "longueur" ignoré. Reportez-vous à
la section "Envoi de données de type
LONG", page 238.
DT_SMALLINT Aucune opération requise
DT_STRING Longueur déterminée par \0 en fin de chaîne
DT_TIME Longueur déterminée par \0 en fin de chaîne
DT_TIMESTAMP Longueur déterminée par \0 en fin de chaîne
DT_TIMESTAMP_STRUCT Aucune opération requise
DT_UNSBIGINT Aucune opération requise
DT_UNSINT Aucune opération requise
DT_UNSSMALLINT Aucune opération requise
DT_VARCHAR(n) Longueur du champ de la structure
VARCHAR
DT_VARIABLE Longueur déterminée par \0 en fin de chaîne

Extraction de valeurs
Chapitre 6 Programmation avec Embedded SQL
Le tableau ci-après indique les valeurs du champ "longueur" lors de la
récupération de données depuis la base à l'aide d'une zone SQLDA. Notez
que le champ sqllen n'est jamais modifié lors de la récupération de données.
Dans ce cas, seuls les types de données de l'interface répertoriés dans ce
tableau sont admis. Les types de données DT_DATE, DT_TIME et
DT_TIMESTAMP sont gérés de la même façon que DT_STRING lors de la
récupération d'informations depuis la base de données. La valeur est
formatée en tant que chaîne de caractères au format de date en vigueur.
Type de données
Embedded SQL
Valeur affectée par le
programme au champ
"longueur" lors d'une
réception
Informations de
longueur renvoyées
par la base de
données après
recherche d'une
valeur
DT_BIGINT Aucune opération requise Aucune opération requise
DT_BINARY(n) Longueur maximale de la
structure BINARY (n+2)
Le champ len de la
structure BINARY
contient la longueur réelle
DT_BIT Aucune opération requise Aucune opération requise
DT_DATE Longueur du buffer \0 en fin de chaîne
DT_DECIMAL(p,s) p = octet de poids fort,
s = octet de poids faible
Aucune opération requise
DT_DOUBLE Aucune opération requise Aucune opération requise
DT_FIXCHAR(n) Longueur du buffer Ajout de blancs jusqu'à
longueur des buffers
DT_FLOAT Aucune opération requise Aucune opération requise
DT_INT Aucune opération requise Aucune opération requise
DT_LONGBINARY Champ "longueur" ignoré.
Reportez-vous à la section
"Récupération de données
de type LONG",
page 236.
DT_LONGVARCHAR Champ "longueur" ignoré.
Reportez-vous à la section
"Récupération de données
de type LONG",
page 236.
Champ "longueur" ignoré.
Reportez-vous à la section
"Récupération de données
de type LONG",
page 236.
Champ "longueur" ignoré.
Reportez-vous à la section
"Récupération de données
de type LONG",
page 236.
DT_SMALLINT Aucune opération requise Aucune opération requise
DT_STRING Longueur du buffer \0 en fin de chaîne
233

Zone descripteur SQL (SQLDA)
234
Type de données
Embedded SQL
Valeur affectée par le
programme au champ
"longueur" lors d'une
réception
Informations de
longueur renvoyées
par la base de
données après
recherche d'une
valeur
DT_TIME Longueur du buffer \0 en fin de chaîne
DT_TIMESTAMP Longueur du buffer \0 en fin de chaîne
DT_TIMESTAMP_ST
RUCT
Aucune opération requise Aucune opération requise
DT_UNSBIGINT Aucune opération requise Aucune opération requise
DT_UNSINT Aucune opération requise Aucune opération requise
DT_UNSSMALLINT Aucune opération requise Aucune opération requise
DT_VARCHAR(n) Longueur maximale de la
structure VARCHAR
(n+2)
Le champ len de la
structure VARCHAR
contient la longueur réelle

Chapitre 6 Programmation avec Embedded SQL
Envoi et extraction de valeurs longues
Utilisation de types
de données SQL
statiques
Utilisation de types
de données SQL
dynamiques
La méthode utilisée pour envoyer et récupérer des valeurs
LONG VARCHAR et LONG BINARY dans les applications
Embedded SQL est différente de celle employée pour les autres types de
données. Bien qu'il soit possible d'utiliser les champs SQLDA standard,
ceux-ci sont limités à 32 ko puisque les champs contenant les informations
(sqldata, sqllen et sqlind) sont des valeurs 16-bit. Remplacer ces valeurs par
des valeurs 32-bit interromprait les applications existantes.
La méthode utilisée pour décrire les valeurs LONG VARCHAR et
LONG BINARY est la même que celle employée pour les autres types de
données.
$ Pour plus d'informations sur la récupération et l'envoi de valeurs,
reportez-vous aux sections "Récupération de données de type LONG",
page 236 et "Envoi de données de type LONG", page 238.
Des structures distinctes sont utilisées pour les longueurs allouées, stockées
et non tronquées des types de données LONG BINARY et
LONG VARCHAR. Les types de données SQL statiques sont définis dans le
fichier sqlca.h de la façon suivante :
#define DECL_LONGVARCHAR( size ) \
struct { a_sql_uint32 array_len; \
a_sql_uint32 stored_len; \
a_sql_uint32 untrunc_len; \
char array[size+1];\
}
#define DECL_LONGBINARY( size ) \
struct { a_sql_uint32 array_len; \
a_sql_uint32 stored_len; \
a_sql_uint32 untrunc_len; \
char array[size]; \
}
Pour les types de données SQL dynamiques, définissez le champ sqltype à
DT_LONGVARCHAR ou DT_LONGBINARY. Les structures
LONGBINARY et LONGVARCHAR associées sont les suivantes :
235

Envoi et extraction de valeurs longues
236
typedef struct LONGVARCHAR {
a_sql_uint32 array_len;
/* nombre d'octets alloués dans tableau */
a_sql_uint32 stored_len;
/* nombre d'octets stockés dans tableau
* (jamais supérieur à array_len)
*/
a_sql_uint32 untrunc_len;
/* nombre d'octets dans expression non
* tronquée
* (peut être supérieur à array_len)
*/
char array[1]; /* données */
} LONGVARCHAR, LONGBINARY;
$ Pour plus d'informations sur la mise en oeuvre de cette fonctionnalité
dans vos applications, reportez-vous aux sections "Récupération de données
de type LONG", page 236 et "Envoi de données de type LONG", page 238.
Récupération de données de type LONG
Cette section décrit comment récupérer des valeurs de type LONG de la base
de données. Pour plus d'informations, reportez-vous à la section "Envoi et
extraction de valeurs longues", page 235.
Les procédures sont différentes selon que vous utilisiez des instructions SQL
statiques ou dynamiques.
v Pour recevoir une valeur LONG VARCHAR ou LONG BINARY
(SQL statique) :
1 Déclarez une variable hôte de type DECL_LONGVARCHAR ou
DECL_LONGBINARY.
2 Récupérez les données au moyen d'une instruction FETCH, GET DATA
ou EXECUTE INTO. Adaptive Server Anywhere définit les
informations suivantes :
♦ Variable indicateur La variable indicateur est négative si la valeur
est NULL, égale à 0 (zéro) en l'absence de troncature, ou
correspond à la longueur non tronquée positive en octets jusqu'à une
valeur maximale de 32 767.
$ Pour plus d'informations, reportez-vous à la section "Variables
indicateur", page 201.
♦ stored_len Ce champ DECL_LONGVARCHAR ou
DECL_LONGBINARY contient le nombre d'octets récupérés dans
le tableau. Sa valeur n'est jamais supérieure à celle d'array_len.

Chapitre 6 Programmation avec Embedded SQL
♦ untrunc_len Ce champ DECL_LONGVARCHAR ou
DECL_LONGBINARY contient le nombre d'octets présents sur le
serveur de base de données. Sa valeur est au moins égale à celle de
stored_len. Elle est définie même si la valeur n'est pas tronquée.
v Pour recevoir une valeur dans une structure LONGVARCHAR ou
LONGBINARY (SQL dynamique) :
1 Définissez le champ sqltype à DT_LONGVARCHAR ou
DT_LONGBINARY.
2 Définissez le champ sqldata de façon qu'il pointe sur la structure
LONGVARCHAR ou LONGBINARY.
Vous pouvez utiliser la macro LONGVARCHARSIZE( n ) ou
LONGBINARYSIZE( n ) pour déterminer le nombre total d'octets à
allouer pour insérer n octets de données dans le champ du tableau.
3 Définissez le champ array_len de la structure LONGVARCHAR ou
LONGBINARY au nombre d'octets alloués pour le champ du tableau.
4 Récupérez les données au moyen d'une instruction FETCH, GET DATA
ou EXECUTE INTO. Adaptive Server Anywhere définit les
informations suivantes :
♦ * sqlind Ce champ sqlda est négatif si la valeur est NULL, égal à 0
(zéro) en l'absence de troncature ou correspond à la longueur non
tronquée positive en octets jusqu'à une valeur maximale de 32 767.
♦ stored_len Ce champ LONGVARCHAR ou LONGBINARY
contient le nombre d'octets récupérés dans le tableau. Sa valeur n'est
jamais supérieure à celle d'array_len.
♦ untrunc_len Ce champ LONGVARCHAR ou LONGBINARY
contient le nombre d'octets présents sur le serveur de base de
données. Sa valeur est au moins égale à celle de stored_len. Elle est
définie même si la valeur n'est pas tronquée.
Le code suivant illustre le mécanisme d'extraction de données
LONG VARCHAR au moyen d'instructions Embedded SQL dynamiques. Il
ne s'agit en aucun cas d'une application pratique.
237

Envoi et extraction de valeurs longues
238
#define DATA_LEN 128000
void get_test_var()
/*****************/
{
LONGVARCHAR *longptr;
SQLDA *sqlda;
SQLVAR *sqlvar;
Envoi de données de type LONG
}
sqlda = alloc_sqlda( 1 );
longptr = (LONGVARCHAR *)malloc(
LONGVARCHARSIZE( DATA_LEN ) );
if( sqlda == NULL || longptr == NULL ) {
fatal_error( "Echec de l’allocation" );
}
// init longptr pour la réception de données
longptr->array_len = DATA_LEN;
// init sqlda pour la réception de données
// (sqllen non utilisé avec les types DT_LONG)
sqlda->sqld = 1; // utilisation de 1 sqlvar
sqlvar = &sqlda->sqlvar[0];
sqlvar->sqltype = DT_LONGVARCHAR;
sqlvar->sqldata = longptr;
printf( "lecture de test_var\n" );
EXEC SQL PREPARE select_stmt FROM 'SELECT test_var';
EXEC SQL EXECUTE select_stmt INTO DESCRIPTOR sqlda;
EXEC SQL DROP STATEMENT select_stmt;
printf( "stored_len: %d, untrunc_len: %d,
1er car. : %c, dernier car. : %c\n",
longptr->stored_len,
longptr->untrunc_len,
longptr->array[0],
longptr->array[DATA_LEN-1] );
free_sqlda( sqlda );
free( longptr );
Cette section décrit comment envoyer des valeurs de type LONG à la base de
données à partir d'applications Embedded SQL. Pour plus d'informations,
reportez-vous à la section "Envoi et extraction de valeurs longues", page 235.
Les procédures sont différentes selon que vous utilisiez des instructions SQL
statiques ou dynamiques.

Chapitre 6 Programmation avec Embedded SQL
v Pour envoyer une valeur LONG VARCHAR ou LONG BINARY
(SQL statique) :
1 Déclarez une variable hôte de type DECL_LONGVARCHAR ou
DECL_LONGBINARY.
2 Si vous envoyez une valeur NULL et utilisez une variable indicateur,
attribuez à cette dernière une valeur négative.
$ Pour plus d'informations, reportez-vous à la section "Variables
indicateur", page 201.
3 Définissez le champ stored_len de la structure
DECL_LONGVARCHAR ou DECL_LONGBINARY au nombre
d'octets des données du champ du tableau.
4 Envoyez les données en ouvrant un curseur ou en exécutant l'instruction.
Le code suivant illustre le mécanisme d'envoi de données
LONG VARCHAR au moyen d'instructions Embedded SQL statiques. Il ne
s'agit en aucun cas d'une application pratique.
#define DATA_LEN 12800
EXEC SQL BEGIN DECLARE SECTION;
// SQLPP initialise longdata.array_len
DECL_LONGVARCHAR(128000) longdata;
EXEC SQL END DECLARE SECTION;
void set_test_var()
/*****************/
{
// init longdata pour l'envoi de données
memset( longdata.array, 'a', DATA_LEN );
longdata.stored_len = DATA_LEN;
printf( "Définition de test_var à %d a's\n",
DATA_LEN );
EXEC SQL SET test_var = :longdata;
}
v Pour envoyer une valeur au moyen d’une structure LONGVARCHAR
ou LONGBINARY (SQL dynamique) :
1 Définissez le champ sqltype à DT_LONGVARCHAR ou
DT_LONGBINARY.
2 Si vous envoyez une valeur NULL, attribuez une valeur négative à
* sqlind.
3 Définissez le champ sqldata de façon qu'il pointe sur la structure
LONGVARCHAR ou LONGBINARY.
239

Envoi et extraction de valeurs longues
240
Vous pouvez utiliser la macro LONGVARCHARSIZE( n ) ou
LONGBINARYSIZE( n ) pour déterminer le nombre total d'octets à
allouer pour insérer n octets de données dans le champ du tableau.
4 Définissez le champ array_len de la structure LONGVARCHAR ou
LONGBINARY au nombre d'octets alloués pour le champ du tableau.
5 Définissez le champ stored_len de la structure LONGVARCHAR ou
LONGBINARY au nombre d'octets de données du champ du tableau. Sa
valeur ne doit pas être supérieure à celle d'array_len.
6 Envoyez les données en ouvrant un curseur ou en exécutant l'instruction.

Utilisation de procédures stockées
Chapitre 6 Programmation avec Embedded SQL
Cette section décrit l'utilisation de procédures SQL avec Embedded SQL.
Utilisation de procédures stockées simples
Vous pouvez créer et appeler des procédures stockées avec Embedded SQL.
Une instruction CREATE PROCEDURE peut être imbriquée comme
n'importe quelle autre instruction de définition de données, par exemple
CREATE TABLE. Vous pouvez également imbriquer une instruction CALL
pour exécuter une procédure stockée. Le fragment de code suivant illustre la
création et l'exécution d'une procédure stockée avec Embedded SQL :
EXEC SQL CREATE PROCEDURE pettycash( IN amount
DECIMAL(10,2) )
BEGIN
UPDATE account
SET balance = balance - amount
WHERE name = ’bank’;
UPDATE account
SET balance = balance + amount
WHERE name = ’pettycash expense’;
END;
EXEC SQL CALL pettycash( 10.72 );
Si vous souhaitez transmettre des valeurs de variable hôte à une procédure
stockée ou récupérer les variables de résultat, vous devez préparer et
exécuter une instruction CALL. Le fragment de code suivant illustre
l'utilisation de variables hôte. Les clauses USING et INTO sont utilisées avec
l'instruction EXECUTE.
EXEC SQL BEGIN DECLARE SECTION;
double hv_expense;
double hv_balance;
EXEC SQL END DECLARE SECTION;
241

Utilisation de procédures stockées
242
// code ici
EXEC SQL CREATE PROCEDURE pettycash(
IN expense DECIMAL(10,2),
OUT endbalance DECIMAL(10,2) )
BEGIN
UPDATE account
SET balance = balance - expense
WHERE name = ’bank’;
UPDATE account
SET balance = balance + expense
WHERE name = ’pettycash expense’;
SET endbalance = ( SELECT balance FROM account
WHERE name = ’bank’ );
END;
EXEC SQL PREPARE S1 FROM ’CALL pettycash( ?, ? )’;
EXEC SQL EXECUTE S1 USING :hv_expense INTO :hv_balance;
$ Pour plus d’informations, reportez-vous aux sections "Instruction
EXECUTE [ESQL]", page 437 du document ASA Manuel de référence SQL
et "Instruction PREPARE [ESQL]", page 518 du document ASA Manuel de
référence SQL.
Procédures stockées avec jeux de résultats
Les procédures de base de données peuvent aussi contenir des instructions
SELECT. La procédure est déclarée à l'aide d'une clause RESULT qui
spécifie le nombre, le nom et le type des colonnes du jeu de résultats. Les
colonnes de jeu de résultats sont différentes des paramètres de sortie. Pour
les procédures avec jeux de résultats, vous pouvez remplacer une instruction
SELECT par une instruction CALL dans la déclaration du curseur :
EXEC SQL BEGIN DECLARE SECTION;
char hv_name[100];
EXEC SQL END DECLARE SECTION;
EXEC SQL CREATE PROCEDURE female_employees()
RESULT( name char(50) )
BEGIN
SELECT emp_fname || emp_lname FROM employee
WHERE sex = ’f’;
END;
EXEC SQL PREPARE S1 FROM ’CALL female_employees()’;
EXEC SQL DECLARE C1 CURSOR FOR S1;
EXEC SQL OPEN C1;
for(;;) {

Curseurs
dynamiques pour
les instructions
CALL
Chapitre 6 Programmation avec Embedded SQL
EXEC SQL FETCH C1 INTO :hv_name;
if( SQLCODE != SQLE_NOERROR ) break;
printf( "%s\\n", hv_name );
}
EXEC SQL CLOSE C1;
Dans cet exemple, la procédure a été appelée avec une instruction OPEN, et
non une instruction EXECUTE. L'instruction OPEN provoque l'exécution de
la procédure jusqu'à ce que celle-ci rencontre une instruction SELECT. A ce
point, C1 est un curseur pour l'instruction SELECT au sein de la procédure
de base de données. Vous pouvez utiliser toutes les formes de la commande
FETCH (défilement vers l'arrière et vers l'avant) jusqu'à ce que vous ayez
terminé. L'instruction CLOSE interrompt l'exécution de la procédure.
Si l'instruction SELECT avait été suivie d'une autre instruction dans la
procédure, cette autre instruction n'aurait pas été exécutée. Pour pouvoir
exécuter les instructions qui suivent une instruction SELECT, faites appel à
la commande RESUME nom_curseur. Celle-ci renvoie l'avertissement
SQLE_PROCEDURE_COMPLETE ou SQLE_NOERROR pour signaler
l'existence d'un autre curseur. Cet exemple illustre une procédure comportant
deux instructions SELECT :
EXEC SQL CREATE PROCEDURE people()
RESULT( name char(50) )
BEGIN
SELECT emp_fname || emp_lname
FROM employee;
SELECT fname || lname
FROM customer;
END;
EXEC SQL PREPARE S1 FROM ’CALL people()’;
EXEC SQL DECLARE C1 CURSOR FOR S1;
EXEC SQL OPEN C1;
while( SQLCODE == SQLE_NOERROR ) {
for(;;) {
EXEC SQL FETCH C1 INTO :hv_name;
if( SQLCODE != SQLE_NOERROR ) break;
printf( "%s\\n", hv_name );
}
EXEC SQL RESUME C1;
}
EXEC SQL CLOSE C1;
Les exemples précédents faisaient appel à des curseurs statiques. Il est
également possible d'utiliser des curseurs dynamiques avec l'instruction
CALL.
243

Utilisation de procédures stockées
DESCRIBE ALL
Jeux de résultats
multiples
244
$ Pour obtenir une description des curseurs dynamiques, reportez-vous à
la section "Instruction SELECT dynamique", page 224.
L'instruction DESCRIBE est tout à fait adaptée aux appels de procédure. Une
instruction DESCRIBE OUTPUT génère une zone SQLDA comportant une
description pour chaque colonne du jeu de résultats.
Si la procédure ne dispose pas d'un jeu de résultats, la zone SQLDA inclut
une description pour chaque paramètre INOUT ou OUT de la procédure.
Une instruction DESCRIBE INPUT génère une zone SQLDA comportant
une description pour chaque paramètre IN ou INOUT.
DESCRIBE ALL décrit les paramètres IN, INOUT, OUT et RESULT set.
Elle fournit des informations supplémentaires à l'aide des variables
indicateur de la zone SQLDA.
Les bits DT_PROCEDURE_IN et DT_PROCEDURE_OUT sont définis
dans la variable indicateur lors de la description d'une instruction CALL.
DT_PROCEDURE_IN indique un paramètre IN ou INOUT et
DT_PROCEDURE_OUT, un paramètre INOUT ou OUT. Les colonnes
RESULT mettent à blanc les deux bits.
Après une instruction DESCRIBE OUTPUT, ces bits peuvent servir à
distinguer les instructions comportant des jeux de résultats (qui doivent faire
appel à OPEN, à FETCH, à RESUME et à CLOSE) de celles qui n'en ont pas
(et qui doivent utiliser EXECUTE).
$ Pour obtenir une description complète, reportez-vous à la section
"Instruction DESCRIBE [ESQL]", page 414 du document ASA Manuel de
référence SQL.
Si une procédure renvoie plusieurs jeux de résultats, vous devez indiquer s'ils
changent de forme après chaque instruction RESUME.
C'est le curseur que vous devez décrire, et non l'instruction, notamment sa
position courante.

Chapitre 6 Programmation avec Embedded SQL
Techniques de programmation Embedded SQL
Cette section comporte plusieurs astuces pour les développeurs de
programmes Embedded SQL.
Mise en oeuvre de la gestion des requêtes
Fonctions de sauvegarde
Lorsque le comportement par défaut de la DLL d'interface s'applique, les
applications attendent que chaque requête de base de données soit terminée
avant d'exécuter d'autres fonctions. Il est toutefois possible de modifier ce
comportement à l'aide des fonctions de gestion des requêtes. Par exemple,
lors de l'utilisation d'Interactive SQL, le système d'exploitation reste actif
pendant que l'utilitaire attend une réponse de la base de données et qu'il
effectue certaines tâches dans le même temps.
Vous pouvez maintenir une activité sous Windows pendant une requête de
base de données par l'intermédiaire d'une fonction de rappel (callback). Dans
cette fonction de rappel, vous ne devez pas effectuer d'autres requêtes de
base de données, à l'exception de db_cancel_request. Pour savoir si une
requête est en cours d'exécution, vous pouvez utiliser db_is_working dans
les routines de gestion de messages.
La fonction db_register_a_callback sert à enregistrer les fonctions de rappel
(callback) de l'application :
$ Pour plus d'informations, reportez-vous aux sections suivantes :
♦ "Fonction db_register_a_callback", page 259
♦ "Fonction db_cancel_request", page 255
♦ "Fonction db_is_working", page 258
La fonction db_backup permet d'effectuer une sauvegarde en ligne dans des
applications Embedded SQL. C'est l'utilitaire de sauvegarde qui exécute cette
fonction. Si ce dernier ne permet pas de satisfaire vos besoins en matière de
sauvegarde, il vous suffit d'écrire d'un programme faisant appel à cette
fonction.
245

Techniques de programmation Embedded SQL
246
Instruction BACKUP recommandée
Bien que cette fonction permette d'ajouter des fonctionnalités de
sauvegarde dans une application, il est recommandé d'exécuter cette tâche
par l'intermédiaire de l'instruction BACKUP. Pour plus d'informations,
reportez-vous à la section "Instruction BACKUP", page 259 du document
ASA Manuel de référence SQL.
$ Vous pouvez également accéder directement à l'utilitaire de sauvegarde
par l'intermédiaire de la fonction DBBackup des outils de base de données.
Pour plus d'informations sur cette fonction, reportez-vous à la section
"Fonction DBBackup", page 320.
$ Pour plus d'informations, reportez-vous à la section "Fonction
db_backup", page 252.

Préprocesseur SQL
Syntaxe
Voir aussi
Chapitre 6 Programmation avec Embedded SQL
Le préprocesseur SQL traite un programme C ou C++ contenant le langage
de programmation Embedded SQL, avant que le compilateur ne soit exécuté.
sqlpp [ options ] nom_fichier_sql [ nom_fichier_résultat ]
Option Description
–c "mot_clé=valeur;..." Fournit les paramètres de connexion à la base de
données de référence [UltraLite].
–d Optimise l'espace alloué aux données.
–e niveau Balise toute syntaxe SQL non conforme en tant
qu’erreur.
–f Place le mot-clé far sur les données statiques générées.
-g N'affiche pas d'avertissement UltraLite.
–h longueur_ligne Limite la longueur maximale des lignes de résultat.
–k Inclut la déclaration utilisateur de SQLCODE.
-m version Indique le nom de version pour les scripts de
synchronisation générés.
–n Génère le numéro des lignes.
–o sys_exploitation Indique le système d'exploitation cible.
–p projet Identifie le nom du projet UltraLite.
–q Opère en mode non détaillé. Aucune bannière n'est
imprimée.
–r Génère du code réentrant
–s longueur_chaîne Indique la longueur de chaîne maximale pour le
compilateur.
–w niveau Balise toute syntaxe SQL non conforme en tant
qu’avertissement.
–x Modifie les chaînes SQL codées sur plusieurs octets en
séquences d'échappement.
–z classement Spécifie l'ordre de classement.
"Introduction", page 178
247

Préprocesseur SQL
Description
Options
248
Le préprocesseur SQL traite un programme C ou C++ contenant le langage
de programmation Embedded SQL, avant que le compilateur ne soit exécuté.
SQLPP convertit les instructions SQL de fichier_entrée en langage C source
et les enregistre dans fichier_résultat. L’extension normale pour les
programmes source en Embedded SQL est .sqc. Le nom du fichier de
résultat par défaut est nom_fichier_SQL avec l'extension .c. Si
nom_fichier_SQL comporte déjà l'extension .c, l'extension du fichier de
résultat sera, par défaut, .cc.
–c Cette option est requise lors du prétraitement des fichiers d'une
application UltraLite. La chaîne de connexion doit donner au préprocesseur
SQL accès pour lire et modifier votre base de données de référence.
–d Cette option permet de générer du code qui réduit l'espace des données.
Les structures de données sont réutilisées et initialisées au moment de
l'exécution, avant toute utilisation. Cette opération accroît la taille du code.
–e Balise tout élément en Embedded SQL qui ne fait pas partie d'un
ensemble spécifié par la norme SQL/92, en tant qu'erreur.
level accepte les valeurs suivantes :
♦ e Balise la syntaxe non conforme à la norme SQL/92 au niveau des
entrées.
♦ i Balise la syntaxe non conforme à la norme SQL/92 au niveau
intermédiaire.
♦ f Balise la syntaxe non entièrement conforme à la norme SQL/92.
♦ t Balise les types de variables hôte non standard.
♦ u Balise la syntaxe qui n'est pas supportée par UltraLite
♦ w Autorise toute syntaxe supportée.
-g N'affiche pas d'avertissement spécifique lors de la génération de code
UltraLite.
–h Limite la longueur maximale des lignes générées par sqlpp à num. La
valeur num doit être suivie d'une barre oblique inversée (\) et ne peut pas être
inférieure à 10.
–k Informe le préprocesseur que le programme à compiler inclut une
déclaration utilisateur de SQLCODE.
-m Indique le nom de version pour les scripts de synchronisation générés.
Les scripts de synchronisation générés peuvent être utilisés dans une base de
données consolidée MobiLink pour une synchronisation simple.

Chapitre 6 Programmation avec Embedded SQL
–n Génère des informations sur les numéros de ligne dans le fichier C. Il
s'agit de directives #line placées aux endroits appropriés dans le code C
généré. Si le compilateur que vous employez supporte la directive #line, cette
option lui permet de signaler les erreurs par les numéros de ligne dans le
fichier SQC (celui qui contient les données Embedded SQL) au lieu de
signaler les erreurs par les numéros de ligne dans le fichier C généré par le
préprocesseur SQL. En outre, les directives #line sont utilisées de façon
indirecte par le débogueur de niveau source afin de pouvoir effectuer le
débogage en consultant le fichier SQC.
–o Spécifie le système d'exploitation cible. L'argument spécifié doit
correspondre au système sur lequel vous exécutez le programme. Une
référence à un symbole spécial est générée dans votre programme. Ce
symbole est défini dans la bibliothèque d'interface. Si vous utilisez une
spécification de système d'exploitation ou une bibliothèque inappropriée, une
erreur est détectée par le générateur de liens. Les systèmes supportés sont :
♦ WINDOWS Microsoft Windows 32 bits (Windows 95/98, Windows CE)
♦ WINNT Microsoft Windows NT/2000
♦ NETWARE Novell NetWare
♦ UNIX UNIX
–p Identifie le projet UltraLite auquel appartiennent les fichiers
Embedded SQL. Cette option ne s’applique que lors du traitement de fichiers
d’une application UltraLite.
–q N'imprime aucune bannière.
–r Pour plus d'informations sur le code réentrant, reportez-vous à la section
"Gestion de la zone SQLCA pour le code multi-thread ou réentrant",
page 208.
–s Définit la longueur de chaîne maximale que le préprocesseur peut intégrer
au fichier C. Les chaînes supérieures à cette valeur seront initialisées en
fonction d'une liste de caractères (’a’,’b’,’c’, etc). La plupart des compilateurs
C ne reconnaissent pas les littéraux de chaînes supérieurs à une certaine
limite. Cette option permet de définir cette limite. La valeur par défaut
est 500.
–w Balise tout élément en Embedded SQL qui ne fait pas partie d'un
ensemble spécifié par la norme SQL/92, en tant qu'avertissement.
level accepte les valeurs suivantes :
♦ e Balise la syntaxe non conforme à la norme SQL/92 au niveau des
entrées.
249

Préprocesseur SQL
250
♦ i Balise la syntaxe non conforme à la norme SQL/92 au niveau
intermédiaire.
♦ f Balise la syntaxe non entièrement conforme à la norme SQL/92.
♦ t Balise les types de variables hôte non standard.
♦ u Balise la syntaxe qui n'est pas supportée par UltraLite
♦ w Autorise toute syntaxe supportée.
–x Modifie les chaînes codées sur plusieurs octets en séquences
d'échappement afin qu'elles soient acceptées par les compilateurs.
–z Spécifie l'ordre de classement. Pour obtenir la liste des ordres de
classement conseillés, tapez dbinit –l à l'invite de commandes.
L'ordre de classement permet au préprocesseur d'interpréter les caractères
utilisés dans le code source du programme, par exemple pour identifier les
caractères alphabétiques admis dans les identificateurs. Si l'option -z n'est
pas spécifiée, le préprocesseur tente de choisir un classement possible, en
faisant référence au système d'exploitation et à la variable d'environnement
SQLLOCALE.

Chapitre 6 Programmation avec Embedded SQL
Références des fonctions de bibliothèque
Points d'entrée de
DLL
Fonction alloc_sqlda
Syntaxe
Description
Fonction alloc_sqlda_noind
Syntaxe
Description
Le préprocesseur SQL génère des appels à des fonctions de la bibliothèque
d'interface ou de la DLL. En plus de ces appels, plusieurs fonctions de
bibliothèque permettent d'effectuer plus facilement les opérations de base de
données. La commande EXEC SQL INCLUDE SQLCA inclut des
prototypes de ces fonctions.
La présente section contient une description de ces différentes fonctions.
Les points d'entrée de DLL sont les mêmes, si ce n'est que les prototypes
disposent d'un modificateur approprié pour chaque DLL.
Vous pouvez déclarer les points d'entrée de façon "portable" en utilisant
_esqlentry_, définie dans sqlca.h. Les valeurs obtenues sont les suivantes :
__stdcall
SQLDA *alloc_sqlda( unsigned numvar );
Alloue une zone SQLDA avec des descripteurs pour les variables numvar.
Le champ sqln de la zone SQLDA est initialisé avec la valeur numvar. De
l'espace est alloué aux variables indicateur, les pointeurs indicateur sont
définis de façon à pointer sur cet espace et la valeur indicateur est initialisée
à zéro. Un pointeur NULL est renvoyé si l'allocation de mémoire est
impossible. Il est conseillé d'utiliser cette fonction de préférence à
alloc_sqlda_noind function.
SQLDA *alloc_sqlda_noind( unsigned numvar );
Alloue une zone SQLDA avec des descripteurs pour les variables numvar.
Le champ sqln de la zone SQLDA est initialisé avec la valeur numvar.
Aucun espace n'est alloué aux variables indicateur et les pointeurs indicateur
sont définis avec le pointeur NULL. Un pointeur NULL est renvoyé si
l'allocation de mémoire est impossible.
251

Références des fonctions de bibliothèque
Fonction db_backup
Syntaxe
Autorisation
Description
252
void db_backup(
SQLCA * sqlca,
int op,
int file_num,
unsigned long page_num,
SQLDA * sqlda);
Vous devez être connecté sous un ID utilisateur détenant les droits DBA ou
REMOTE DBA (SQL Remote).
Instruction BACKUP recommandée
Bien que cette fonction permette d'ajouter des fonctionnalités de
sauvegarde dans une application, il est recommandé d'exécuter cette tâche
par l'intermédiaire de l'instruction BACKUP. Pour plus d'informations,
reportez-vous à la section "Instruction BACKUP", page 259 du document
ASA Manuel de référence SQL.
L'opération effectuée est fonction de la valeur du paramètre op :
♦ DB_BACKUP_START Doit être appelé pour qu'une sauvegarde puisse
démarrer. Une seule sauvegarde peut s'exécuter à un moment donné sur
un serveur de base de données. Les points de reprise de la base sont
désactivés jusqu'à la fin de la sauvegarde (db_backup est appelé avec
une valeur op de DB_BACKUP_END). Si la sauvegarde ne peut pas
démarrer, le SQLCODE est SQLE_BACKUP_NOT_STARTED. Dans
le cas contraire, le champ SQLCOUNT de la sqlca prend la valeur de la
taille de chaque page de la base de données. (Les sauvegardes sont
traitées page par page.)
Les paramètres file_num, page_num et sqlda sont ignorés.
♦ DB_BACKUP_OPEN_FILE Ouvre le fichier de base de données spécifié
par file_num, ce qui permet de sauvegarder les pages de ce fichier à
l'aide de DB_BACKUP_READ_PAGE. Le nombre de fichiers admis est
compris entre 0 (zéro) et DB_BACKUP_MAX_FILE pour les fichiers
de base de données principaux, entre 0 et
DB_BACKUP_TRANS_LOG_FILE pour le journal de transactions, et
entre 0 et DB_BACKUP_WRITE_FILE pour l'éventuel fichier d'écriture
de base de données. Si le fichier spécifié n'existe pas, le SQLCODE est
SQLE_NOTFOUND. Dans le cas contraire, SQLCOUNT contient le
nombre de pages du fichier, SQLIOESTIMATE contient une valeur sur
32 bits (POSIX time_t) identifiant l'heure de création du fichier de base
de données, et le nom du fichier du système d'exploitation apparaît dans
le champ sqlerrmc de la zone SQLCA.
Les paramètres page_num et sqlda sont ignorés.

Chapitre 6 Programmation avec Embedded SQL
♦ DB_BACKUP_READ_PAGE Lit une page du fichier de base de données
spécifié par file_num. Le paramètre page_num doit être une valeur
comprise entre 0 et le nombre de pages moins une, renvoyé dans
SQLCOUNT par un appel à db_backup dans le cadre de l'opération
DB_BACKUP_OPEN_FILE. Sinon, SQLCODE est défini sur
SQLE_NOTFOUND. Le descripteur sqlda doit être défini avec une
variable de type DT_BINARY qui pointe sur un buffer. Le buffer doit
être suffisamment grand pour contenir des données binaires de la taille
renvoyée dans le champ SQLCOUNT lors de l'appel à db_backup dans
le cadre de l'opération DB_BACKUP_START.
DT_BINARY contient une indication de longueur de deux octets suivie
des données binaires proprement dites ; la taille du buffer doit donc être
supérieure de deux octets à celle de la page.
Sauvegarde du buffer par l'application
Cet appel crée une copie de la page de base de données spécifiée dans
le buffer, mais l'application peut sauvegarder ce dernier sur un
support de sauvegarde.
♦ DB_BACKUP_READ_RENAME_LOG Action identique à celle de
DB_BACKUP_READ_PAGE, hormis le fait que le serveur de base de
données renomme le journal de transactions et en démarre un nouveau
une fois la dernière page du journal de transactions renvoyée.
S'il ne parvient pas à renommer le journal à l'heure courante (par
exemple, il peut exister des transactions incomplètes dans les bases de
données de la version 7.x ou antérieure), l'erreur
SQLE_BACKUP_CANNOT_RENAME_LOG_YET est générée. Dans
ce cas, n'utilisez pas la page renvoyée, mais relancez la demande jusqu'à
ce que vous receviez SQLE_NOERROR, puis enregistrez la page.
Continuez à lire les pages jusqu'à ce que vous receviez l'erreur
SQLE_NOTFOUND.
L'erreur SQLE_BACKUP_CANNOT_RENAME_LOG_YET peut être
renvoyée plusieurs fois sur plusieurs pages. Dans la boucle de relance,
ajoutez un intervalle de temps afin de ne pas ralentir le serveur avec un
trop grand nombre de demandes.
La condition SQLE_NOTFOUND signifie que la sauvegarde du journal
de transactions a abouti et que le fichier a été renommé. Le nom de
l'ancien fichier de transactions est renvoyé dans le champ sqlerrmc de la
zone SQLCA.
253

Références des fonctions de bibliothèque
254
Vous devez vérifier la valeur sqlda->sqlvar[0].sqlind après un appel
db_backup. Si cette valeur est supérieure à zéro, la dernière page du
journal a été écrite et le fichier journal a été renommé. Le nouveau nom
est toujours sqlca.sqlerrmc, mais la valeur SQLCODE est
SQLE_NOERROR.
Après cela, vous ne devez pas rappeler db_backup, sauf pour fermer
des fichiers et terminer la sauvegarde. Le cas échéant, vous recevez une
deuxième copie de votre fichier journal sauvegardé, ainsi que
SQLE_NOTFOUND.
♦ DB_BACKUP_CLOSE_FILE Cette fonction doit être appelée lorsque le
traitement d'un fichier est terminé, pour refermer le fichier de base de
données spécifié par file_num.
Les paramètres page_num et sqlda sont ignorés.
♦ DB_BACKUP_END Cette fonction doit être appelée à la fin de la
sauvegarde. Aucune autre sauvegarde ne peut démarrer tant que la
sauvegarde en cours n'est pas terminée. Les points de reprise sont de
nouveau activés.
Les paramètres file_num, page_num et sqlda sont ignorés.
Le programme dbbackup utilise l'algorithme suivant. Notez qu'il ne s'agit pas
de code C et qu'aucun contrôle d'erreurs n'est inclus.
db_backup( ... DB_BACKUP_START ... )
alloue des buffers page en fonction de la taille des
pages dans SQLCODE
sqlda = alloc_sqlda( 1 )
sqlda->sqld = 1;
sqlda->sqlvar[0].sqltype = DT_BINARY
sqlda->sqlvar[0].sqldata = allocated buffer
for file_num = 0 to DB_BACKUP_MAX_FILE
db_backup( ... DB_BACKUP_OPEN_FILE, file_num ... )
if SQLCODE == SQLE_NO_ERROR
/* Le fichier existe */
num_pages = SQLCOUNT
file_time = SQLE_IO_ESTIMATE
ouvre le fichier de backup avec le nom indiqué dans
sqlca.sqlerrmc
for page_num = 0 to num_pages - 1
db_backup( ... DB_BACKUP_READ_PAGE,
file_num, page_num, sqlda )
écrit les buffers page dans le fichier de
sauvegarde
next page_num
close backup file
db_backup( ... DB_BACKUP_CLOSE_FILE, file_num ... )
end if
next file_num

Fonction db_cancel_request
Syntaxe
Description
Fonction db_delete_file
Syntaxe
Autorisation
Description
Chapitre 6 Programmation avec Embedded SQL
backup up file DB_BACKUP_WRITE_FILE as above
backup up file DB_BACKUP_TRANS_LOG_FILE as above
free page buffer
db_backup( ... DB_BACKUP_END ... )
int db_cancel_request( SQLCA *sqlca );
Annule la requête active sur le serveur de base de données. Cette fonction
vérifie qu'une requête est active sur le serveur de base de données avant
d'envoyer la demande d'annulation. Si la fonction renvoie 1, la demande
d'annulation a été transmise ; si elle renvoie 0, aucune demande n'a été
transmise.
Une valeur renvoyée différente de 0 ne signifie pas que la requête a été
annulée. Dans les cas (peu nombreux) où la synchronisation est difficile, la
demande d'annulation et la réponse du serveur ou de la base "se croisent".
Dans ces cas, l'annulation n'a pas lieu, même si la fonction continue de
renvoyer TRUE.
Il est possible d'appeler la fonction db_cancel_request de façon asynchrone.
Cette fonction ainsi que db_is_working sont les seules fonctions de la
bibliothèque d'interface de base de données qui peuvent être appelées en
mode asynchrone à l'aide d'une zone SQLCA susceptible d'être utilisée par
une autre requête.
Si vous annulez une requête qui exécute une opération avec le curseur, la
position du curseur est indéterminée. Vous devez alors localiser le curseur en
fonction de sa position absolue ou le refermer suite à l'annulation.
void db_delete_file(
SQLCA * sqlca,
char * nom_fichier );
Vous devez être connecté sous un ID utilisateur détenant les droits DBA ou
REMOTE DBA (SQL Remote).
La fonction db_delete_file impose au serveur de base de données de
supprimer le fichier nom_fichier. Vous pouvez faire appel à cette fonction
pour supprimer l'ancien journal de transactions une fois que vous l'avez
sauvegardé et renommé (voir la fonction
DB_BACKUP_READ_RENAME_LOG, à la section "Fonction db_backup",
page 252). Vous devez être connecté sous un ID utilisateur détenant les
droits DBA.
255

Références des fonctions de bibliothèque
Fonction db_find_engine
Syntaxe
Description
Fonction db_fini
Syntaxe
Description
Voir aussi
Fonction db_get_property
Syntaxe
256
unsigned short db_find_engine(
SQLCA *sqlca,
char *nom );
Renvoie un entier court, non signé, contenant des informations d'état sur le
serveur de base de données désigné par nom. Si aucun serveur portant le nom
spécifié n'est trouvé, la valeur 0 (zéro) est renvoyée. Une valeur différente de
0 indique que le serveur est actif.
Chaque bit de la valeur renvoyée véhicule des informations. Les constantes
qui représentent les bits des différents éléments d'information sont définies
dans le fichier d'en-tête sqldef.h. Si un pointeur NULL est spécifié pour la
variable nom, des informations sur l'environnement de la base de données par
défaut sont renvoyées.
unsigned short db_fini( SQLCA *sqlca );
Cette fonction libère les ressources utilisées par l'interface de base de
données ou la DLL. Vous ne devez pas appeler d'autres bibliothèques ni
exécuter de commandes Embedded SQL après avoir appelé db_fini. Si une
erreur se produit en cours de traitement, le code d'erreur est défini dans la
zone SQLCA et la fonction renvoie 0 (zéro). En l'absence d'erreur, c'est une
valeur différente de 0 qui est renvoyée.
Vous devez appeler db_fini pour chaque zone SQLCA utilisée.
Attention
Sous NetWare, si db_fini n'est pas appelé pour chaque db_init, le serveur
de base de données et le serveur de fichiers NetWare risquent de s'arrêter.
Pour plus d’informations sur l’utilisation de la fonction db_fini dans les
applications UltraLite, reportez-vous à la section "Fonction db_fini",
page 246 du document UltraLite Guide de l’utilisateur.
unsigned int db_get_property(
SQLCA * sqlca,
a_db_property property,
char * value_buffer,
int value_buffer_size );

Description
Voir aussi
Fonction db_init
Syntaxe
Description
Chapitre 6 Programmation avec Embedded SQL
Cette fonction permet d'obtenir l'adresse du serveur auquel vous êtes
connecté. Elle est employée par l'utilitaire dbping pour imprimer l'adresse du
serveur.
Elle peut également être utilisée pour connaître la valeur des propriétés d'une
base de données. Vous pouvez obtenir les propriétés d'une base de données
sans recourir à l'interface, en exécutant une instruction SELECT ; cette
opération est définie dans la section "Propriétés des bases de données",
page 674 du document ASA Guide d’administration.
Les arguments sont les suivants :
♦ a_db_property enum avec la valeur DB_PROP_SERVER_ADDRESS.
DB_PROP_SERVER_ADDRESS permet d'obtenir, sous la forme d'une
chaîne imprimable, l'adresse réseau du serveur pour la connexion en
cours. Les protocoles de mémoire partagée et les protocoles Named
Pipes renvoient toujours une chaîne vide comme adresse. Les protocoles
TCP/IP et SPX renvoient les adresses dans une chaîne pleine.
♦ value_buffer Cet argument est renseigné avec la valeur de la propriété
sous la forme d'une chaîne terminée par une valeur NULL.
♦ value_buffer_size Longueur maximale de la chaîne value_buffer,
incluant le caractère NULL de fin.
"Propriétés des bases de données", page 674 du document ASA Guide
d’administration
unsigned short db_init( SQLCA *sqlca );
Cette fonction initialise la bibliothèque d'interface de la base de données.
Cette fonction doit être appelée avant toute autre appel de bibliothèque et
avant toute exécution d'une commande Embedded SQL. Les ressources
requises par la bibliothèque d'interface pour votre programme sont allouées
et initialisées lors de cet appel.
Utilisez db_fini pour libérer les ressources en fin d'exécution de votre
programme. En cas d'erreurs au cours du traitement, la valeur 0 (zéro) est
renvoyée dans la zone SQLCA. En l'absence d'erreurs, une valeur non nulle
est renvoyée et vous pouvez commencer à utiliser les commandes et les
fonctions Embedded SQL.
257

Références des fonctions de bibliothèque
Voir aussi
Fonction db_is_working
Syntaxe
Description
Fonction db_locate_servers
Syntaxe
Description
258
Dans la plupart des cas, cette fonction ne doit être appelée qu'une seule fois
(afin de transmettre l'adresse de la variable globale sqlca définie dans le
fichier d'en-tête sqlca.h). Si vous créez une DLL ou une application
multithread à l'aide d'Embedded SQL, appelez db_init autant de fois qu'il y a
de SQLCA.
$ Pour plus d'informations, reportez-vous à la section "Gestion de la zone
SQLCA pour le code multi-thread ou réentrant", page 208.
Attention
Sous NetWare, si db_fini n'est pas appelé pour chaque db_init, le serveur
de base de données et le serveur de fichiers NetWare risquent de s'arrêter.
Pour plus d’informations sur l’utilisation de la fonction db_init dans les
applications UltraLite, reportez-vous à la section "Fonction db_init",
page 246 du document UltraLite Guide de l’utilisateur.
unsigned db_is_working( SQLCA *sqlca );
Renvoie 1 si votre application comporte une requête de base de données en
cours qui utilise cette zone SQLCA, et 0 si aucune requête en cours n'utilise
cette zone SQLCA.
Cette fonction peut être appelée en mode asynchrone. Cette fonction ainsi
que db_cancel_request sont les seules fonctions de la bibliothèque
d'interface de base de données qui peuvent être appelées en mode asynchrone
à l'aide d'une zone SQLCA susceptible d'être utilisée par une autre requête.
unsigned int db_locate_servers(
SQLCA *sqlca,
SQL_CALLBACK_PARM adresse_callback,
void *callback_user_data );
Permet un accès par voie de programmation aux informations affichées par
l'utilitaire dblocate, avec la liste de tous les serveurs de base de données
Adaptive Server Anywhere qui, sur le réseau local, sont en réception sur
TCP/IP.
La fonction callback doit avoir la syntaxe suivante :

Chapitre 6 Programmation avec Embedded SQL
int (*)( SQLCA *sqlca,
a_server_address *adr_serveur,
void *callback_user_data);
Fonction db_register_a_callback
Syntaxe
Description
La fonction callback est appelée pour chaque serveur détecté. Si elle
renvoie 0, db_locate_servers arrête l'itération entre les serveurs.
Les paramètres sqlca et callback_user_data transmis à la fonction callback
sont ceux qui sont transmis dans db_locate_servers. Le second paramètre
est un pointeur sur une structure a_server_address. a_server_address est
définie dans sqlca.h, avec la définition suivante :
typedef struct a_server_address {
a_SQL_uint32 type_port;
a_SQL_uint32 num_port;
char *nom;
char *adresse;
} a_server_address;
♦ type_port Toujours égal à PORT_TYPE_TCP à ce moment-là (défini
à 6 dans sqlca.h).
♦ num_port Numéro de port TCP sur lequel le serveur est en réception.
♦ nom Pointe sur un buffer contenant le nom du serveur.
♦ adresse Pointe sur un buffer contenant l'adresse IP du serveur.
$ Pour plus d'informations, reportez-vous à "Utilitaire de localisation de
serveurs", page 540 du document ASA Guide d’administration.
void db_register_a_callback(
SQLCA *sqlca,
a_db_callback_index index,
( SQL_CALLBACK_PARM ) callback );
Cette fonction enregistre les fonctions de rappel (callback).
Si vous n'enregistrez aucune fonction callback DB_CALLBACK_WAIT,
vous n'avez, par défaut, aucune action à entreprendre. Votre application se
bloque en attendant la réponse de la base de données et Windows transforme
le curseur en sablier.
Pour supprimer un rappel, passez un pointeur NULL en tant que fonction
callback.
Les valeurs admises pour le paramètre index sont les suivantes :
259

Références des fonctions de bibliothèque
260
♦ DB_CALLBACK_DEBUG_MESSAGE La fonction fournie est appelée
une fois pour chaque message de débogage et elle reçoit une chaîne
terminée par une valeur NULL contenant le texte du message. La chaîne
contient en général un caractère de saut de ligne (\n) situé
immédiatement avant le caractère NULL de fin. La syntaxe de la
fonction callback est la suivante :
void SQL_CALLBACK debug_message_callback(
SQLCA *sqlca,
char * chaîne_message );
♦ DB_CALLBACK_START La syntaxe est la suivante :
void SQL_CALLBACK start_callback( SQLCA *sqlca );
La fonction est appelée immédiatement avant qu'une requête de base de
données ne soit envoyée au serveur. DB_CALLBACK_START n'est
utilisée que sous Windows 95/98, Windows NT/2000 et Windows CE.
♦ DB_CALLBACK_FINISH La syntaxe est la suivante :
void SQL_CALLBACK finish_callback( SQLCA * sqlca );
Cette fonction est appelée après que la réponse à une requête de base de
données a été reçue par la DLL d'interface. DB_CALLBACK_FINISH
n'est utilisée que sous les systèmes d'exploitation Windows.
♦ DB_CALLBACK_CONN_DROPPED La syntaxe est la suivante :
void SQL_CALLBACK conn_dropped_callback (
SQLCA *sqlca,
char *nom_connexion );
Cette fonction est appelée lorsque le serveur de base de données est sur
le point d'abandonner la connexion en raison du dépassement du délai
d'inactivité, à la suite d'une instruction DROP CONNECTION ou suite à
l'arrêt du serveur. Le nom de connexion nom_connexion est transmis
pour vous permettre de faire la différence entre les connexions. Si la
connexion n'a pas été nommée, elle a la valeur NULL.
♦ DB_CALLBACK_WAIT La syntaxe est la suivante :
void SQL_CALLBACK wait_callback( SQLCA *sqlca );
Cette fonction est appelée très souvent par la bibliothèque d'interface
pendant que le serveur de base de données ou la bibliothèque cliente
traite votre requête.
Vous pouvez enregistrer ce rappel (callback) comme suit :
db_register_a_callback( &sqlca,
DBCALLBACK_WAIT,
(SQL_CALLBACK_PARM)&db_wait_request );

Fonction db_start_database
Syntaxe
Arguments
Chapitre 6 Programmation avec Embedded SQL
♦ DB_CALLBACK_MESSAGE Cette fonction permet à l'application de
gérer les messages provenant du serveur durant le traitement d'une
requête.
La syntaxe se présente comme suit :
void SQL_CALLBACK message_callback(
SQLCA* sqlca,
unsigned short msg_type,
an_SQL_code code,
unsigned length,
char* msg
);
Le paramètre msg_type spécifie l'importance du message et les
manières dont vous souhaitez gérer les différents types de message. Les
types de message disponibles sont MESSAGE_TYPE_INFO,
MESSAGE_TYPE_WARNING, MESSAGE_TYPE_ACTION et
MESSAGE_TYPE_STATUS. Ces constantes sont définies dans
sqldef.h. Le champ code est un identificateur. Le champ length indique
la longueur du message. Le message ne se termine pas par une valeur
NULL.
Par exemple, le rappel (callback) Interactive SQL affiche les messages
STATUS et INFO dans le volet Messages, tandis que des messages de
type ACTION et WARNING sont présentés dans une boîte de dialogue.
Si une application n'enregistre pas ce rappel, il existe un rappel par
défaut qui provoque l'enregistrement de tous les messages dans le fichier
de trace du serveur (si la fonction de débogage est activée et si un fichier
de trace est spécifié). En outre, les messages de type
MESSAGE_TYPE_WARNING et MESSAGE_TYPE_ACTION sont
affichés de façon plus visible, selon les options d'affichage propres au
système d'exploitation.
unsigned int db_start_database( SQLCA * sqlca, char * parms );
sqlca Pointeur sur une structure SQLCA. Pour plus d'informations, reportezvous
à la section "Zone de communication SQL (SQLCA)", page 205.
parms Chaîne terminée par la valeur NULL contenant une liste de valeurs
de paramètres délimitées par points-virgules, chacune d'entre elles ayant la
forme KEYWORD=valeur. Par exemple :
"UID=DBA;PWD=SQL;DBF=c:\\db\\mydatabase.db"
261

Références des fonctions de bibliothèque
Description
Fonction db_start_engine
Syntaxe
Arguments
Description
262
$ Pour obtenir la liste des paramètres de connexion, reportez-vous à la
section "Paramètres de connexion", page 176 du document ASA Guide
d’administration.
Démarre une base de données sur un serveur existant si cette base n'est pas
déjà en cours d'exécution. Les étapes à suivre pour démarrer une base de
données sont décrites sous "Démarrage d'un serveur personnel", page 84 du
document ASA Guide d’administration.
La valeur TRUE est renvoyée si la base de données était déjà en cours
d'exécution ou si son démarrage a abouti. Les informations d'erreur sont
renvoyées dans la zone SQLCA.
Si un ID utilisateur et un mot de passe sont fournis dans les paramètres, ils
sont ignorés.
$ L'autorisation requise pour le démarrage et l'arrêt d'une base de données
est définie sur la ligne de commande du serveur. Pour plus d'informations,
reportez-vous à la section "Le serveur de base de données", page 128 du
document ASA Guide d’administration.
unsigned int db_start_engine( SQLCA * sqlca, char * parms );
sqlca Pointeur sur une structure SQLCA. Pour plus d'informations, reportezvous
à la section "Zone de communication SQL (SQLCA)", page 205.
parms Chaîne terminée par la valeur NULL contenant une liste de valeurs
de paramètres délimitées par points-virgules, chacune d'entre elles ayant la
forme KEYWORD=valeur. Par exemple :
"UID=DBA;PWD=SQL;DBF=c:\\db\\mydatabase.db"
$ Pour obtenir la liste des paramètres de connexion, reportez-vous à la
section "Paramètres de connexion", page 176 du document ASA Guide
d’administration.
Démarre le serveur de base de données s'il n'est pas déjà actif. Les opérations
effectuées par cette fonction sont les mêmes que celles décrites dans la
section "Démarrage d'un serveur personnel", page 84 du document ASA
Guide d’administration.
La valeur TRUE est renvoyée si le serveur est identifié ou que son démarrage
a abouti. Les informations d'erreur sont renvoyées dans la zone SQLCA.
La fonction db_start_engine ci-après démarre le serveur de base de données
qu'elle nomme asademo, mais la présence du paramètre de connexion DBF
n'entraîne pas pour autant le chargement de la base de données :

Chapitre 6 Programmation avec Embedded SQL
db_start_engine( &sqlca, "DBF=c:\\asa8\\asademo.db;
Start=dbeng8" );
Si vous souhaitez démarrer une base de données en même temps que le
serveur, vous devez inclure le nom du fichier de base de données dans le
paramètre de connexion START :
db_start_engine( &sqlca,"ENG=eng_name;START=dbeng8
c:\\asa\\asademo.db" );
Cet appel démarre le serveur, le nomme eng_name et démarre la base de
données asademo sur ce serveur.
La fonction db_start_engine tente d'établir une connexion avec un serveur
plutôt que d'en démarrer un, afin d'éviter de démarrer un serveur déjà actif.
Le paramètre de connexion FORCESTART n'est utilisé que par la fonction
db_start_engine. S'il est défini à YES, aucune connexion à un serveur n'est
tentée tant qu'il n'y a pas eu de tentative d'en démarrer un. Ceci permet aux
deux commandes suivantes de fonctionner comme prévu :
1 Démarrer un serveur de base de données nommé serveur_1 :
start dbeng8 -n serveur_1 asademo.db
2 Imposer le démarrage d'un nouveau serveur et établir la connexion :
db_start_engine( &sqlda, "START=dbeng8 -n serveur_2 asademo.db;ForceStart=YES" )
Fonction db_stop_database
Syntaxe
Arguments
Description
Si FORCESTART n'est pas employé et sans paramètre ENG, la seconde
commande tente une connexion à serveur_1. La fonction db_start_engine
ne récupère pas le nom du serveur dans l'option -n du paramètre START.
unsigned int db_stop_database( SQLCA * sqlca, char * parms );
sqlca Pointeur sur une structure SQLCA. Pour plus d'informations, reportezvous
à la section "Zone de communication SQL (SQLCA)", page 205.
parms Chaîne terminée par la valeur NULL contenant une liste de valeurs
de paramètres délimitées par points-virgules, chacune d'entre elles ayant la
forme KEYWORD=valeur. Par exemple :
"UID=DBA;PWD=SQL;DBF=c:\\db\\mydatabase.db"
$ Pour obtenir la liste des paramètres de connexion, reportez-vous à la
section "Paramètres de connexion", page 176 du document ASA Guide
d’administration.
Arrête la base de données DatabaseName sur le serveur EngineName. Si le
nom EngineName n'est pas spécifié, c'est le serveur par défaut qui est utilisé.
263

Références des fonctions de bibliothèque
Fonction db_stop_engine
Syntaxe
Arguments
Description
264
Par défaut, cette fonction n'arrête pas une base de données disposant déjà de
connexions. Toutefois, si Unconditional a la valeur yes, la base de données
est arrêtée, qu'elle ait ou non des connexions existantes.
La valeur TRUE est renvoyée si aucune erreur n'est survenue.
$ L'autorisation requise pour le démarrage et l'arrêt d'une base de données
est définie sur la ligne de commande du serveur. Pour plus d'informations,
reportez-vous à la section "Le serveur de base de données", page 128 du
document ASA Guide d’administration.
unsigned int db_stop_engine( SQLCA * sqlca, char * parms );
sqlca Pointeur sur une structure SQLCA. Pour plus d'informations, reportezvous
à la section "Zone de communication SQL (SQLCA)", page 205.
parms Chaîne terminée par la valeur NULL contenant une liste de valeurs
de paramètres délimitées par points-virgules, chacune d'entre elles ayant la
forme KEYWORD=valeur. Par exemple :
"UID=DBA;PWD=SQL;DBF=c:\\db\\mydatabase.db"
$ Pour obtenir la liste des paramètres de connexion, reportez-vous à la
section "Paramètres de connexion", page 176 du document ASA Guide
d’administration.
Arrête le serveur de base de données. Les étapes ci-dessous sont effectuées
par cette fonction :
♦ Recherche d'un serveur de base de données local dont le nom correspond
au paramètre EngineName. Si ce paramètre n'est pas spécifié, recherche
le serveur de base de données local par défaut.
♦ Si aucun serveur n'est trouvé, la fonction échoue.
♦ Envoi d'une requête au serveur lui indiquant d'effectuer un point de
reprise sur chaque base de données puis d'arrêter celles-ci.
♦ Déchargement du serveur de base de données.
Par défaut, cette fonction n'arrête pas un serveur de base de données
disposant déjà de connexions. Toutefois, si Unconditional a la valeur yes, le
serveur de base de données est arrêté, qu'il ait ou non des connexions en
cours.
Un programme en langage C peut utiliser cette fonction au lieu de générer
DBSTOP. La valeur TRUE est renvoyée si aucune erreur n'est survenue.

Fonction db_string_connect
Syntaxe
Arguments
Description
Fonction db_string_disconnect
Syntaxe
Arguments
Chapitre 6 Programmation avec Embedded SQL
L’utilisation de db_stop_ending est soumise aux autorisations définies dans
l'option de serveur -gk.
$ Pour plus d'informations, reportez-vous à la section "Option de serveur
-gk", page 151 du document ASA Guide d’administration.
unsigned int db_string_connect( SQLCA * sqlca, char * parms );
sqlca Pointeur sur une structure SQLCA. Pour plus d'informations, reportezvous
à la section "Zone de communication SQL (SQLCA)", page 205.
parms Chaîne terminée par la valeur NULL contenant une liste de valeurs
de paramètres délimitées par points-virgules, chacune d'entre elles ayant la
forme KEYWORD=valeur. Par exemple :
"UID=DBA;PWD=SQL;DBF=c:\\db\\mydatabase.db"
$ Pour obtenir la liste des paramètres de connexion, reportez-vous à la
section "Paramètres de connexion", page 176 du document ASA Guide
d’administration.
Offre des fonctionnalités supplémentaires par rapport à la commande
Embedded SQL CONNECT. Cette fonction établit une connexion en
utilisant l'algorithme décrit dans la section "Résolution des problèmes de
connexion", page 78 du document ASA Guide d’administration.
Si l'établissement de la connexion aboutit, la valeur renvoyée est TRUE
(valeur différente de 0); dans le cas contraire, la valeur de retour est FALSE
(valeur différente de 0). Les informations d'erreur relatives au démarrage du
serveur ou de la base de données, ou celles relatives à la connexion sont
renvoyées dans la zone SQLCA.
unsigned int db_string_disconnect( SQLCA * sqlca, char * parms );
sqlca Pointeur sur une structure SQLCA. Pour plus d'informations, reportezvous
à la section "Zone de communication SQL (SQLCA)", page 205.
parms Chaîne terminée par la valeur NULL contenant une liste de valeurs
de paramètres délimitées par points-virgules, chacune d'entre elles ayant la
forme KEYWORD=valeur. Par exemple :
"UID=DBA;PWD=SQL;DBF=c:\\db\\mydatabase.db"
265

Références des fonctions de bibliothèque
Description
Fonction db_string_ping_server
Syntaxe
Description
Fonction fill_s_sqlda
Syntaxe
266
$ Pour obtenir la liste des paramètres de connexion, reportez-vous à la
section "Paramètres de connexion", page 176 du document ASA Guide
d’administration.
Cette fonction met fin à la connexion identifiée par le paramètre
ConnectionName. Tous les autres paramètres sont ignorés.
Si aucun paramètre ConnectionName n'est spécifié dans la chaîne, la
connexion non nommée est interrompue. Cette fonction est l'équivalent de la
commande Embedded SQL DISCONNECT. Si une connexion est
effectivement interrompue, la valeur booléenne renvoyée est TRUE. Les
informations d'erreur sont renvoyées dans la zone SQLCA.
Cette fonction arrête la base de données si celle-ci a été démarrée avec
AutoStop=yes et qu'aucune autre connexion à cette base n'a été établie. Elle
arrête également le moteur si celui-ci a été démarré avec AutoStop=yes et
qu'aucune autre base n'est en cours d'exécution.
unsigned int db_string_ping_server(
SQLCA * sqlca,
char * chaîne_connexion,
unsigned int connexion_à_bd );
chaîne_connexion est une chaîne de connexion normale qui peut contenir ou
non des informations sur le serveur et la base de données.
Si connexion_à_bd est différent de zéro (TRUE), la fonction tente une
connexion à une base de données sur un serveur. Elle renvoie une valeur
différente de zéro (TRUE) uniquement si la chaîne de connexion suffit pour
établir la connexion à la base de données nommée sur le serveur nommé.
Si connexion_à_bd a la valeur zéro, la fonction tente uniquement de localiser
un serveur. Elle renvoie une valeur différente de zéro uniquement si la chaîne
de connexion permet de localiser un serveur. Elle ne tente pas d'établir la
connexion avec la base.
struct sqlda * fill_s_sqlda(
struct sqlda * sqlda,
unsigned int maxlen );

Description
Fonction fill_sqlda
Syntaxe
Description
Fonction free_filled_sqlda
Syntaxe
Description
Fonction free_sqlda
Syntaxe
Description
Fonction free_sqlda_noind
Syntaxe
Description
Chapitre 6 Programmation avec Embedded SQL
Semblable pour l'essentiel à fill_sqlda, mais convertit tous les types de
données de sqlda en DT_STRING. La conversion requiert l'allocation d'un
espace suffisant, l'espace maximal étant de maxlen octets. Les champs
"longueur" de la zone SQLDA (sqllen) sont modifiés en conséquence.
Renvoie sqlda en cas de succès et le pointeur NULL, si la mémoire
disponible est insuffisante.
struct sqlda * fill_sqlda( struct sqlda * sqlda );
Alloue de l'espace à chaque variable décrite dans chaque descripteur de sqlda
et affecte l'adresse de cette mémoire au champ sqldata du descripteur
correspondant. Un espace suffisant est alloué au type de base de données et à
la longueur indiqués dans ce descripteur. Renvoie sqlda en cas de succès et
le pointeur NULL, si la mémoire disponible est insuffisante.
void free_filled_sqlda( struct sqlda * sqlda );
Libère la mémoire allouée à chaque pointeur sqldata, ainsi que l'espace
alloué à la zone SQLDA. Les pointeurs NULL ne sont pas libérés.
L'appel de cette fonction provoque l'appel automatique de free_sqlda de
sorte que les descripteurs alloués par alloc_sqlda sont libérés.
void free_sqlda( struct sqlda * sqlda );
Libère l'espace alloué à cette zone sqlda, et libère l'espace de la variable
indicateur qui avait été alloué dans fill_sqlda. Ne libère pas la mémoire
référencée par chaque pointeur sqldata.
void free_sqlda_noind( struct sqlda * sqlda );
Libère l'espace alloué à cette zone sqlda. Ne libère pas la mémoire référencée
par chaque pointeur sqldata. Les pointeurs de variable indicateur sont
ignorés.
267

Références des fonctions de bibliothèque
Fonction sql_needs_quotes
Syntaxe
Description
Fonction sqlda_storage
Syntaxe
Description
Fonction sqlda_string_length
Syntaxe
Description
Fonction sqlerror_message
Syntaxe
268
"Propriétés des bases de données", page 674 du document ASA Guide
d’administration
"Utilitaire Ping", page 536 du document ASA Guide d’administration
unsigned int sql_needs_quotes( SQLCA *sqlca, char *str );
Renvoie une valeur booléenne indiquant si la chaîne doit être ou non
encadrée par des guillemets lorsqu'elle est utilisée en tant qu'identificateur
SQL. Cette fonction adresse une requête au serveur de base de données pour
déterminer si les guillemets sont nécessaires. Les informations pertinentes
sont stockées dans le champ sqlcode.
Il existe trois combinaisons de valeur/code de retour :
♦ valeur renvoyée = FALSE, sqlcode = 0 Dans ce cas, la chaîne n'a pas
besoin de guillemets.
♦ valeur renvoyée = TRUE Ici, sqlcode est toujours SQLE_WARNING et
la chaîne requiert des guillemets.
♦ valeur renvoyée = FALSE Si sqlcode n’est pas SQLE_WARNING, le
test n’est pas concluant.
unsigned long sqlda_storage( struct sqlda *sqlda, int varno );
Renvoie la quantité de mémoire requise pour enregistrer une valeur, quelle
qu'elle soit, de la variable décrite dans sqlda->sqlvar[varno].
unsigned long sqlda_string_length( SQLDA *sqlda, int varno );
Renvoie la longueur de la chaîne en langage C (de type DT_STRING)
requise pour contenir la variable sqlda->sqlvar[varno] (quel que soit son
type).
char *sqlerror_message( SQLCA *sqlca, char * buffer, int max );

Description
Chapitre 6 Programmation avec Embedded SQL
Renvoie un pointeur sur une chaîne contenant un message d'erreur. Ce
dernier contient le texte du code d'erreur de la zone SQLCA. Si aucune
erreur n'a été détectée, un pointeur NULL est renvoyé. Le message d'erreur
est placé dans le buffer fourni, tronqué (si nécessaire) à la longueur max.
269

Récapitulatif des commandes Embedded SQL
Récapitulatif des commandes Embedded SQL
270
EXEC SQL
TOUTES les instructions Embedded SQL doivent être précédées
d'EXEC SQL et se terminer par un point-virgule (;).
Il existe deux groupes de commandes Embedded SQL. Les commandes SQL
standard s'utilisent comme suit : il suffit de les placer dans un programme en
langage C, en les faisant précéder d'EXEC SQL et suivre d'un pointvirgule
(;). Les instructions CONNECT, DELETE, SELECT, SET et
UPDATE possèdent d'autres formats qui ne sont disponibles qu'avec
Embedded SQL. Ces formats appartiennent à la seconde catégorie, celle des
commandes Embedded SQL spécifiques.
$ Pour plus d'informations sur les commandes SQL standard, reportezvous
à la section "Instructions SQL", page 209 du document ASA Manuel de
référence SQL.
Plusieurs commandes SQL sont spécifiques d'Embedded SQL et peuvent
seulement être utilisées dans les programmes en langage C.
$ Pour plus d'informations sur ces commandes Embedded SQL, reportezvous
à la section "Eléments de langage SQL", page 3 du document ASA
Manuel de référence SQL.
Les instructions de manipulation et de définition de données standard
peuvent être utilisées à partir des applications Embedded SQL. En outre, les
instructions suivantes sont conçues spécifiquement pour la programmation
Embedded SQL :
♦ ALLOCATE DESCRIPTOR Alloue de la mémoire pour un descripteur.
$ Voir "Instruction ALLOCATE DESCRIPTOR [ESQL]", page 214
du document ASA Manuel de référence SQL
♦ CLOSE Ferme un curseur.
$ Voir "Instruction CLOSE [ESQL] [SP]", page 276 du document
ASA Manuel de référence SQL
♦ CONNECT Etablit une connexion à la base de données.
$ Voir "Instruction CONNECT [ESQL] [Interactive SQL]", page 283
du document ASA Manuel de référence SQL
♦ DEALLOCATE DESCRIPTOR Récupère la mémoire d'un descripteur.
$ Voir "Instruction DEALLOCATE DESCRIPTOR [ESQL]",
page 398 du document ASA Manuel de référence SQL

Chapitre 6 Programmation avec Embedded SQL
♦ DECLARATION SECTION Déclare des variables hôte pour
communiquer avec la base de données.
$ Voir "Section de déclaration [ESQL]", page 399 du document ASA
Manuel de référence SQL
♦ DECLARE CURSOR Déclare un curseur.
$ Voir "Instruction DECLARE CURSOR [ESQL] [SP]", page 401
du document ASA Manuel de référence SQL
♦ DELETE (positionné) Supprime la ligne à la position courante dans un
curseur.
$ Voir "Instruction DELETE (positionnée) [ESQL] [SP]", page 412
du document ASA Manuel de référence SQL
♦ DESCRIBE Décrit les variables hôte pour une instruction SQL donnée.
$ Voir "Instruction DESCRIBE [ESQL]", page 414 du document
ASA Manuel de référence SQL
♦ DISCONNECT Interrompt la connexion avec le serveur de base de
données.
$ Voir "Instruction DISCONNECT [ESQL] [Interactive SQL]",
page 418 du document ASA Manuel de référence SQL
♦ DROP STATEMENT Libère les ressources utilisées par une instruction
préparée.
$ Voir "Instruction DROP STATEMENT [ESQL]", page 427 du
document ASA Manuel de référence SQL
♦ EXECUTE Exécute une instruction SQL donnée.
$ Voir "Instruction EXECUTE [ESQL]", page 437 du document ASA
Manuel de référence SQL
♦ EXPLAIN Explique la stratégie d'optimisation associée à un curseur
donné.
$ Voir "Instruction EXPLAIN [ESQL]", page 444 du document ASA
Manuel de référence SQL
♦ FETCH Extrait une ligne d’un curseur.
$ Voir "Instruction FETCH [ESQL] [SP]", page 446 du document
ASA Manuel de référence SQL
♦ GET DATA Extrait les valeurs longues d’un curseur
$ Voir "Instruction GET DATA [ESQL]", page 459 du document
ASA Manuel de référence SQL
271

Récapitulatif des commandes Embedded SQL
272
♦ GET DESCRIPTOR Extrait les informations sur une variables dans une
zone SQLDA.
$ Voir "Instruction GET DESCRIPTOR [ESQL]", page 461 du
document ASA Manuel de référence SQL
♦ GET OPTION Obtient la définition d'une option de base de données
particulière.
$ Voir "Instruction GET OPTION [ESQL]", page 463 du document
ASA Manuel de référence SQL
♦ INCLUDE Inclut un fichier pour un prétraitement SQL.
$ Voir "Instruction INCLUDE [ESQL]", page 481 du document ASA
Manuel de référence SQL
♦ OPEN Ouvre un curseur.
$ Voir "Instruction OPEN [ESQL] [SP]", page 508 du document ASA
Manuel de référence SQL
♦ PREPARE Prépare une instruction SQL donnée.
$ Voir "Instruction PREPARE [ESQL]", page 518 du document ASA
Manuel de référence SQL
♦ PUT Insère une ligne dans un curseur.
$ Voir "Instruction PUT [ESQL]", page 523 du document ASA
Manuel de référence SQL
♦ SET CONNECTION Change la connexion active.
$ Voir "Instruction SET CONNECTION [Interactive SQL] [ESQL]",
page 563 du document ASA Manuel de référence SQL
♦ SET DESCRIPTOR Décrit les variables d'une zone SQLDA et place les
données dans cette zone
$ Voir "Instruction SET DESCRIPTOR [ESQL]", page 564 du
document ASA Manuel de référence SQL
♦ SET SQLCA Utilise une zone SQLCA autre que la zone globale par
défaut.
$ Voir "Instruction SET SQLCA [ESQL]", page 572 du document
ASA Manuel de référence SQL
♦ UPDATE (positionné) Met à jour la ligne à la position courante dans un
curseur.
$ Voir "Instruction UPDATE (positionnée) [ESQL] [SP]", page 609
du document ASA Manuel de référence SQL

Chapitre 6 Programmation avec Embedded SQL
♦ WHENEVER Spécifie les actions à exécuter en cas d'erreur dans des
instructions SQL.
$ Voir "Instruction WHENEVER [ESQL]", page 618 du document
ASA Manuel de référence SQL
273

Récapitulatif des commandes Embedded SQL
274

CHAPITRE 7
Programmation avec ODBC
Présentation
Sommaire
Ce chapitre présente des informations relatives au développement
d'applications faisant directement appel à l'interface de programmation
ODBC.
La documentation principale pour le développement d'applications ODBC
s'intitule Microsoft ODBC SDK documentation ; elle fait partie du SDK
Microsoft Data Access Components (MDAC). Ce chapitre fournit une
présentation et décrit des fonctions spécifiques d'Adaptive Server Anywhere,
mais n'est en aucun cas un guide exhaustif de la programmation
d'applications ODBC.
Certains outils de développement d'applications offrant déjà le support
ODBC disposent de leur propre interface de programmation qui masque
l'interface ODBC. Ce chapitre n'est pas destiné aux utilisateurs de ces types
d'outil.
Sujet Page
Présentation d'ODBC 276
Création d'applications ODBC 278
Exemples ODBC 283
Descripteurs ODBC 285
Connexion à une source de données 288
Exécution d'instructions SQL 292
Jeux de résultats 297
Appel de procédures stockées 302
Gestion des erreurs 304
275

Présentation d'ODBC
Présentation d'ODBC
Plates-formes
supportées
Conformité à ODBC
Niveaux de support
ODBC
Fonctionnalités
supportées par
Adaptive Server
Anywhere
276
L’interface ODBC (Open Database Connectivity) est une interface de
programmation d'applications définie par Microsoft Corporation comme
interface standard pour les systèmes de gestion de bases de données dans les
environnements Windows. ODBC est une interface basée sur les appels.
Pour écrire des applications ODBC pour Adaptive Server Anywhere, vous
devez disposer des éléments suivants :
♦ Adaptive Server Anywhere.
♦ Compilateur en langage C capable de créer des programmes pour votre
environnement.
♦ SDK (Kit de développement logiciel) ODBC de Microsoft. Celui-ci est
disponible sur le Microsoft Developer Network ; il fournit des éléments
de documentation et des outils complémentaires pour tester les
applications ODBC.
Adaptive Server Anywhere supporte l'API ODBC sous UNIX et
Windows CE, en plus des environnements Windows. Le support multiplateforme
ODBC facilite le développement d'applications de base de données
portables.
$ Pour plus d'informations sur l'inscription du pilote ODBC dans des
transactions distribuées, reportez-vous à la section "Transactions distribuées
et architecture à trois niveaux", page 393.
Adaptive Server Anywhere supporte ODBC 3.52.
Les fonctionnalités ODBC sont classées selon leur niveau de conformité.
Elles peuvent être basiques, de niveau 1 ou de niveau 2, ce dernier niveau
de support ODBC étant le plus complet. Ces fonctionnalités sont répertoriées
dans le document ODBC Programmer’s Reference, disponible auprès de
Microsoft Corporation dans le cadre du kit de développement logiciel
ODBC, ou sur le site Web de Microsoft à l'adresse suivante :
http://msdn.microsoft.com/library/default.asp?url=/library/enus/odbc/htm/odbcabout_this_manual.asp.
Adaptive Server Anywhere supporte la spécification ODBC 3.52.
♦ Conformité basique Adaptive Server Anywhere supporte toutes les
fonctionnalités du niveau principal.

Compatibilité
ODBC
descendante
Gestionnaire de
pilotes ODBC
Chapitre 7 Programmation avec ODBC
♦ Conformité de niveau 1 Adaptive Server Anywhere supporte toutes les
fonctionnalités du niveau 1, à l'exception de l'exécution asynchrone des
fonctions ODBC.
Adaptive Server Anywhere supporte les threads multiples partageant une
connexion unique. Les demandes issues des différents threads sont
sérialisées par Adaptive Server Anywhere.
♦ Conformité de niveau 2 Adaptive Server Anywhere supporte toutes les
fonctionnalités du niveau 2, à l'exception des suivantes :
♦ Noms en trois parties des tables et vues. Cela n'est pas applicable
pour Adaptive Server Anywhere.
♦ Exécution asynchrone de fonctions ODBC pour certaines
instructions individuelles spécifiées.
♦ Capacité de temporiser les demandes de login et les requêtes SQL.
Les applications développées avec d'anciennes versions d'ODBC
continueront de fonctionner avec Adaptive Server Anywhere et un
gestionnaire de pilotes ODBC récent. Les nouvelles fonctionnalités ODBC
ne sont pas disponibles pour les anciennes applications.
Le gestionnaire de pilotes ODBC fait partie des éléments logiciels ODBC
fournis avec Adaptive Server Anywhere. Le gestionnaire de pilotes ODBC
version 3 dispose d'une nouvelle interface de configuration des sources de
données ODBC.
277

Création d'applications ODBC
Création d'applications ODBC
278
Cette section explique comment compiler et lier des applications ODBC
simples.
Inclusion du fichier d'en-tête ODBC
Tout fichier source en langage C faisant appel à des fonctions ODBC doit
inclure un fichier d'en-tête ODBC spécifique de la plate-forme. Tous les
fichiers d'en-tête spécifiques d'une plate-forme comprennent le fichier d'entête
principal ODBC, odbc.h, qui définit toutes les fonctions, tous les types
de données et toutes les définitions de constantes nécessaires pour l'écriture
d'un programme ODBC.
v Pour inclure le fichier d'en-tête ODBC dans un fichier source en
langage C :
1 Ajoutez une ligne d'inclusion qui référence dans le fichier source le
fichier d'en-tête approprié spécifique de la plate-forme. Les lignes à
utiliser sont les suivantes :
Système d'exploitation Ligne d'inclusion
Windows #include "ntodbc.h"
UNIX #include "unixodbc.h"
Windows CE #include "ntodbc.h"
2 Ajoutez dans le chemin d'inclusion de votre compilateur le répertoire
contenant le fichier d'en-tête.
Les fichiers d'en-tête spécifiques de la plate-forme et le fichier odbc.h
sont installés dans le sous-répertoire h du répertoire SQL Anywhere.
Liaison d’applications ODBC sous Windows
Cette section ne s'applique pas à Windows CE. Pour plus d'informations,
reportez-vous à la section "Liaison d'applications ODBC sous Windows CE",
page 279.

Chapitre 7 Programmation avec ODBC
Lorsque vous liez votre application, vous devez la lier au fichier de
bibliothèque d'importation approprié afin d'avoir accès aux fonctions ODBC.
La bibliothèque d'importation définit les points d'entrée pour le gestionnaire
de pilotes ODBC odbc32.dll. A son tour, le gestionnaire de pilote charge le
pilote ODBC dbodbc8.dll d'Adaptive Server Anywhere.
Des bibliothèques d'importation séparées sont fournies pour les compilateurs
Microsoft, Watcom et Borland.
v Pour lier une application ODBC sous Windows :
♦ Ajoutez dans la liste des répertoires de bibliothèque le répertoire
contenant la bibliothèque d'importation spécifique de la plate-forme.
Les bibliothèques d'importation sont stockées dans le sous-répertoire lib
du répertoire contenant les fichiers exécutables
d'Adaptive Server Anywhere et sont nommées comme suit :
Système
d'exploitation
Compilateur Bibliothèque d'importation
Windows Microsoft odbc32.lib
Windows Watcom
C/C++
wodbc32.lib
Windows Borland bodbc32.lib
Windows CE Microsoft dbodbc8.lib
Liaison d’applications ODBC sous Windows CE
Les systèmes d'exploitation Windows CE ne comportent pas de gestionnaire
de pilotes ODBC. La bibliothèque d'importation (dbodbc8.lib) définit les
points d'entrée directement dans le pilote ODBC dbodbc8.dll
d'Adaptive Server Anywhere.
Des versions distinctes de cette DLL sont fournies pour les différentes puces
avec lesquelles Windows CE fonctionne. Ces fichiers se trouvent dans les
sous-répertoires spécifiques du système d'exploitation, situés eux-mêmes
dans le sous-répertoire ce du répertoire SQL Anywhere. Par exemple, le
pilote ODBC pour Windows CE sur la puce SH3 se trouve à l'emplacement
suivant :
C:\Program Files\Sybase\SQL Anywhere 8\ce\SH3
$ Pour obtenir la liste des versions supportées de Windows CE, reportezvous
au chapitre "Systèmes d'exploitation supportés par Adaptive Server
Anywhere", page 146 du document Présentation de SQL Anywhere Studio.
279

Création d'applications ODBC
Windows CE et
Unicode
280
v Pour lier une application ODBC sous Windows CE :
1 Ajoutez dans la liste des répertoires de bibliothèque le répertoire
contenant la bibliothèque d'importation spécifique de la plate-forme.
La bibliothèque d'importation est nommée dbodbc8.lib et se trouve dans
un sous-répertoire spécifique du système d'exploitation, se trouvant luimême
dans le sous-répertoire ce du répertoire SQL Anywhere. Par
exemple, la bibliothèque d'importation pour Windows CE sur la
puce SH3 se trouve à l'emplacement suivant :
C:\Program Files\Sybase\SQL Anywhere 8\ce\SH3\lib
2 Spécifiez le paramètre DRIVER= dans la chaîne de connexion fournie
pour la fonction SQLDriverConnect.
szConnStrIn =
"driver=chemin_se/dbodbc8.dll;dbf=c:\asademo.db"
chemin_se correspondant au chemin complet d'accès au sous-répertoire
spécifique de la puce, se trouvant lui-même dans le répertoire
SQL Anywhere sur le périphérique Windows CE. Par exemple :
\Program Files\Sybase\SQL Anywhere 8\ce\SH3\lib
Le programme exemple (odbc.c) utilise un fichier source de données
(paramètre de connexion FileDSN) appelé ASA 8.0 Sample.dsn. Vous
pouvez créer des fichiers source de données sur votre système de bureau à
partir du gestionnaire de pilotes ODBC puis les copier sur votre périphérique
Windows CE.
Adaptive Server Anywhere utilise UTF-8, qui est un système de codage des
caractères sur plusieurs octets, compatible avec Unicode.
Le pilote ODBC d'Adaptive Server Anywhere supporte des chaînes ASCII
(8 bits) ou des chaînes Unicode (caractères étendus). La macro UNICODE
contrôle si les fonctions ODBC attendent des chaînes ASCII ou Unicode. Si
votre application doit être créée avec la macro UNICODE définie mais que
vous vouliez utiliser les fonctions ODBC ASCII, la macro
SQL_NOUNICODEMAP doit également être définie.
Le fichier exemple Samples\ASA\C\odbc.c explique comment utiliser les
fonctionnalités ODBC Unicode.
Liaison d’applications ODBC sous UNIX
Aucun gestionnaire de pilotes ODBC n'est fourni avec
Adaptive Server Anywhere, mais des gestionnaires tiers sont disponibles.
Cette section explique comment créer des applications ODBC qui n'utilisent
pas un gestionnaire de pilotes ODBC.

Pilote ODBC
Informations sur
les sources de
données
Chapitre 7 Programmation avec ODBC
Le pilote ODBC est un objet partagé ou une bibliothèque partagée. Des
versions distinctes du pilote ODBC d'Adaptive Server Anywhere sont
fournies pour des applications à threads uniques ou multiples.
Les pilotes ODBC sont les fichiers suivants :
Système
d'exploitation
Modèle de thread Pilote ODBC
Solaris/Sparc Thread unique dbodbc8.so (dbodbc8.so.1)
Solaris/Sparc Threads multiples dbodbc_r.so (dbodbc_r.so.1)
Les bibliothèques sont installées en tant que liens symboliques à la
bibliothèque partagée avec un numéro de version (entre parenthèses).
v Pour lier une application ODBC sous UNIX :
1 Liez votre application directement au pilote ODBC approprié.
2 Lorsque vous déployez votre application, assurez-vous que le
pilote ODBC approprié est disponible dans le chemin de bibliothèque de
l'utilisateur.
Si Adaptive Server Anywhere ne détecte aucun gestionnaire de pilotes
ODBC, il utilise ~/.odbc.ini pour avoir des informations sur les sources de
données.
Utilisation d’un gestionnaire de pilotes ODBC sous UNIX
Il existe des gestionnaires de pilotes ODBC tiers pour UNIX. Un
gestionnaire de pilotes ODBC comprend les fichiers suivants :
Système
d'exploitation
Fichiers
Solaris/Sparc libodbc.so (libodbc.so.1)
libodbcinst.so (libodbcinst.so.1)
Solaris/Sparc libodbc.so (libodbc.so.1)
libodbcinst.so (libodbcinst.so.1)
Si vous déployez une application qui nécessite un gestionnaire de pilotes
ODBC et que vous n'utilisez pas un gestionnaire de pilotes tiers, créez des
liens symboliques entre les bibliothèques partagées libodbc et libodbcinst et le
pilote ODBC d'Adaptive Server Anywhere.
281

Création d'applications ODBC
282
S’il existe un gestionnaire de pilotes ODBC, Adaptive Server Anywhere
l'interroge plutôt que ~/.odbc.ini pour obtenir des informations sur les sources
de données.
Les applications ODBC standard ne se lient pas directement au pilote
ODBC. En fait, les appels de fonctions ODBC s'effectuent par l'intermédiaire
du gestionnaire de pilotes ODBC. Sous UNIX et Windows CE,
Adaptive Server Anywhere n'inclut pas de gestionnaire de pilotes ODBC.
Vous pouvez toujours créer des applications ODBC en les liant directement
au gestionnaire de pilotes Adaptive Server Anywhere, mais vous ne pourrez
ensuite accéder qu'aux sources de données Adaptive Server Anywhere.

Exemples ODBC
Chapitre 7 Programmation avec ODBC
Plusieurs exemples ODBC sont fournis avec Adaptive Server Anywhere.
Vous les trouverez dans le sous-répertoire Samples\ASA du répertoire
SQL Anywhere. Le chemin d'accès par défaut est :
C:\Program Files\Sybase\SQL Anywhere 8\Samples\ASA
Les exemples dans les répertoires commençant par ODBC illustrent des
tâches ODBC distinctes et simples, notamment la connexion à une base de
données et l'exécution d'instructions. Un programme exemple ODBC est
fourni dans le fichier Samples\ASA\C\odbc.c. Ce programme exécute les
mêmes actions que le programme exemple de curseur dynamique
Embedded SQL qui se trouve dans le même répertoire.
$ Pour obtenir la description du programme Embedded SQL associé,
reportez-vous à la section "Exemples de programmes Embedded SQL",
page 186.
Création du programme exemple ODBC
Le programme exemple ODBC dans Samples\ASA\C inclut un fichier batch
(script shell pour UNIX) qui permet de compiler et de lier l’exemple
d’application.
v Pour créer le programme exemple ODBC :
1 A partir de la ligne de commande, placez-vous dans le sous-répertoire
Samples\ASA\C du répertoire SQL Anywhere.
2 Exécutez le fichier batch ou script shell makeall.
Le format de cette commande est le suivant :
makeall api plate-forme compilateur
Les paramètres sont les suivants :
♦ API Spécifiez odbc pour compiler l'exemple ODBC plutôt qu'une
version Embedded SQL de l'application.
♦ Plate-forme Spécifiez WINNT pour effectuer la compilation pour
les systèmes d'exploitation Windows.
♦ Compilateur Spécifiez le compilateur à utiliser pour compiler le
programme. Les compilateurs admis sont les suivants :
♦ WC Watcom C/C++
♦ MC Microsoft Visual C++
283

Exemples ODBC
284
♦ BC Borland C++ Builder
Exécution du programme exemple ODBC
Lorsqu'il est compilé pour les versions de Windows qui supportent les
services, le programme exemple odbc.c peut être exploité en tant que service.
Les deux fichiers contenant le code exemple pour Windows sont le fichier
source ntsvc.c et le fichier d'en-tête ntsvc.h. Ce code permet de lancer le
fichier exécutable associé en tant qu'exécutable normal ou en tant que service
Windows.
v Pour exécuter l'exemple ODBC :
1 Démarrez le programme :
♦ Exécutez le fichier Samples\ASA\C\odbcwnt.exe.
2 Choisissez une table :
♦ Choisissez une des tables de la base de données exemple. Ainsi,
vous pouvez saisir Customer ou Employee.
v Pour exécuter l'exemple ODBC en tant que service Windows :
1 Démarrez Sybase Central et ouvrez le dossier Services.
2 Cliquez sur Ajouter un service. Suivez les instructions d'ajout du
programme exemple en tant que service.
3 Cliquez avec le bouton droit sur l'icône du service, puis sur Démarrer
pour le lancer.
Lorsque les programmes sont exécutés en tant que services, ils affichent
habituellement l'interface utilisateur normale. Ils écrivent également le
résultat dans le journal d'événements de l'application (Application Event
Log). S'il est impossible de démarrer l'interface utilisateur, les programmes
enregistrent une page de données dans ce journal, puis s'interrompent.

Descripteurs ODBC
Chapitre 7 Programmation avec ODBC
Les applications ODBC font appel à un petit ensemble de descripteurs pour
définir des fonctionnalités de base telles que les connexions aux bases de
données et les instructions SQL. Un descripteur est une valeur de 32 bits.
Les descripteurs suivants sont utilisés dans pratiquement toutes les
applications ODBC :
♦ Environnement Le descripteur d'environnement fournit un contexte
général pour l'accès aux données. Chaque application ODBC doit allouer
un descripteur d'environnement au démarrage et le libérer à la fin.
Le code suivant indique comment allouer un descripteur
d'environnement :
SQLHENV env;
SQLRETURN rc;
rc = SQLAllocHandle( SQL_HANDLE_ENV, SQL
_NULL_HANDLE, &env );
♦ Connexion Une connexion est spécifiée par un pilote ODBC et une
source de données. Plusieurs connexions peuvent être associées à
l'environnement d'une application. Le fait d'allouer un descripteur de
connexion n'établit pas la connexion ; le descripteur de connexion doit
être alloué dans un premier temps, puis utilisé lorsque la connexion est
établie.
Le code suivant indique comment allouer un descripteur de connexion :
SQLHDBC dbc;
SQLRETURN rc;
rc = SQLAllocHandle( SQL_HANDLE_DBC, env, &dbc );
♦ Instruction Un descripteur d'instruction permet d'accéder à une
instruction SQL et à toutes les informations qui lui sont associées,
notamment les jeux de résultats et les paramètres. Plusieurs instructions
peuvent être associées à chaque connexion. Les instructions sont
utilisées à la fois pour des opérations de curseur (extraction de données)
et pour l'exécution d'instructions individuelles (par exemple, INSERT,
UPDATE et DELETE).
Le code suivant indique comment allouer un descripteur d'instruction :
SQLHSTMT stmt;
SQLRETURN rc;
rc = SQLAllocHandle( SQL_HANDLE_STMT, dbc, &stmt );
285

Descripteurs ODBC
Allocation de descripteurs ODBC
Exemple
286
Les types de descripteur nécessaires pour les programmes ODBC sont les
suivants :
Elément Type de descripteur
Environnement SQLHENV
Connexion SQLHDBC
Instruction SQLHSTMT
Descripteur SQLHDESC
v Pour utiliser un descripteur ODBC :
1 Appelez la fonction SQLAllocHandle.
SQLAllocHandle prend trois paramètres :
♦ un identificateur pour le type d'élément alloué,
♦ le descripteur de l'élément parent,
♦ un pointeur renvoyant vers l'emplacement du descripteur à allouer.
$ Pour plus d'informations, reportez-vous à la section
SQLAllocHandle dans le document ODBC Programmer’s Reference de
Microsoft.
2 Utilisez le descripteur dans les appels de fonction ultérieurs.
3 Libérez l'objet à l'aide de SQLFreeHandle.
SQLFreeHandle prend les paramètres suivants :
♦ un identificateur pour le type d'élément libéré,
♦ le descripteur de l'élément libéré.
$ Pour plus d'informations, reportez-vous à la section
SQLFreeHandle dans le document ODBC Programmer's Reference de
Microsoft.
Le fragment de code suivant alloue et libère un descripteur d'environnement :
SQLHENV env;
SQLRETURN retcode;
retcode = SQLAllocHandle( SQL_HANDLE_ENV, SQL_NULL_HANDLE, &env );
if( retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO ) {
// succès : code d'application ici
}
SQLFreeHandle( SQL_HANDLE_ENV, env );

Premier exemple ODBC
#include
#include "ntodbc.h"
Chapitre 7 Programmation avec ODBC
$ Pour plus d’informations sur les codes de retour et la gestion des
erreurs, reportez-vous à la section "Gestion des erreurs", page 304.
Voici un exemple de programme ODBC simple qui permet de se connecter à
la base de données exemple d'Adaptive Server Anywhere et de se
déconnecter immédiatement.
$ Cet exemple se trouve dans le fichier
Samples\ASA\ODBCConnect\odbcconnect.cpp du répertoire SQL Anywhere.
int main(int argc, char* argv[])
{
SQLHENV env;
SQLHDBC dbc;
SQLRETURN retcode;
retcode = SQLAllocHandle( SQL_HANDLE_ENV, SQL_NULL_HANDLE, &env );
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
printf( "env alloué\n" );
/* Définit l'attribut d'environnement de la version d'ODBC */
retcode = SQLSetEnvAttr( env, SQL_ATTR_ODBC_VERSION, (void*)SQL_OV_ODBC3, 0);
retcode = SQLAllocHandle( SQL_HANDLE_DBC, env, &dbc );
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
printf( "dbc alloué\n" );
retcode = SQLConnect( dbc,
(SQLCHAR*) "ASA 8.0 Sample", SQL_NTS,
(SQLCHAR* ) "DBA", SQL_NTS,
(SQLCHAR*) "SQL", SQL_NTS );
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
printf( "Connexion réussie\n" );
}
SQLDisconnect( dbc );
}
SQLFreeHandle( SQL_HANDLE_DBC, dbc );
}
SQLFreeHandle( SQL_HANDLE_ENV, env );
return 0;
}
287

Connexion à une source de données
Connexion à une source de données
288
Cette section explique comment utiliser les fonctions ODBC pour établir une
connexion à une base de données Adaptive Server Anywhere.
Choix d’une fonction de connexion ODBC
ODBC offre un ensemble de fonctions de connexion. Leur utilisation dépend
de la manière dot vous souhaitez que votre application soit déployée et
utilisée :
♦ SQLConnect Fonction de connexion la plus simple.
SQLConnect prend un nom de source de données et, éventuellement, un
ID utilisateur et un mot de passe. Vous pouvez utiliser SQLConnect si
vous codez en dur un nom de source de données dans votre application.
$ Pour plus d'informations, reportez-vous à la section SQLConnect
du document ODBC Programmer’s Reference de Microsoft.
♦ SQLDriverConnect Etablit une connexion à une source de données à
l'aide d'une chaîne de connexion.
SQLDriverConnect permet à l'application d'utiliser des informations de
connexion spécifiques d'Adaptive Server Anywhere qui sont externes à
la source de données. Vous pouvez également utiliser
SQLDriverConnect pour fait en sorte que le pilote
Adaptive Server Anywhere demande des informations de connexion.
SQLDriverConnect permet également d'établir une connexion sans
indiquer de source de données.
$ Pour plus d'informations, reportez-vous à la section
SQLDriverConnect du document ODBC Programmer’s Reference de
Microsoft.
♦ SQLBrowseConnect Etablit une connexion à la source de données à
partir d'une chaîne de connexion, tout comme SQLDriverConnect.
SQLBrowseConnect permet à votre application de créer ses propres
boîtes de dialogue en vue de demander des informations de connexion et
de rechercher des sources de données utilisées par un pilote particulier
(dans le cas présent, le pilote Adaptive Server Anywhere).
$ Pour plus d'informations, reportez-vous à la section
SQLBrowseConnect du document ODBC Programmer’s Reference de
Microsoft.

Etablissement d’une connexion
Chapitre 7 Programmation avec ODBC
Les exemples de ce chapitre font principalement appel à la fonction
SQLDriverConnect.
$ Pour obtenir une liste complète des paramètres de connexion qui
peuvent être utilisés dans les chaînes de connexion, reportez-vous à la
section "Paramètres de connexion", page 176 du document ASA Guide
d’administration.
Votre application doit établir une connexion avant d'effectuer des opérations
sur une base de données.
v Pour établir une connexion ODBC :
1 Allouez un environnement ODBC.
Par exemple :
SQLHENV env;
SQLRETURN retcode;
retcode = SQLAllocHandle( SQL_HANDLE_ENV,
SQL_NULL_HANDLE, &env );
2 Déclarez la version d'ODBC.
En déclarant que l'application se base sur ODBC version 3, le
comportement à adopter par les valeurs SQLSTATE ainsi que par
d'autres fonctionnalités reposant sur la version est défini. Par exemple :
retcode = SQLSetEnvAttr( env,
SQL_ATTR_ODBC_VERSION, (void*)SQL_OV_ODBC3, 0);
3 Si nécessaire, assemblez la source de données ou la chaîne de
connexion.
En fonction de votre application, vous pouvez avoir une chaîne de
connexion ou une source de données codée en dur, ou vous pouvez
choisir de la stocker en externe pour garantir une meilleure flexibilité.
4 Allouez un élément de connexion ODBC.
Par exemple :
retcode = SQLAllocHandle( SQL_HANDLE_DBC, env, &dbc
);
5 Définissez tous les attributs de connexion qui doivent l'être avant
d'établir une connexion.
289

Connexion à une source de données
290
Certains attributs de connexion doivent être définis avant d'établir une
connexion, alors que d'autres attributs peuvent être définis soit avant,
soit après la connexion. Par exemple :
retcode = SQLSetConnectAttr( dbc, SQL_AUTOCOMMIT,
FALSE );
$ Pour plus d'informations, reportez-vous à la section "Définition des
attributs de connexion", page 290.
6 Appelez la fonction de connexion ODBC.
Par exemple :
if (retcode == SQL_SUCCESS || retcode ==
SQL_SUCCESS_WITH_INFO) {
printf( "dbc alloué\n" );
retcode = SQLConnect( dbc,
(SQLCHAR*) "ASA 8.0 Sample", SQL_NTS,
(SQLCHAR* ) "DBA", SQL_NTS,
(SQLCHAR*) "SQL", SQL_NTS );
if (retcode == SQL_SUCCESS
|| retcode == SQL_SUCCESS_WITH_INFO){
// connexion réussie.
$ Vous trouverez un exemple complet dans le fichier
Samples\ASA\ODBCConnect\odbcconnect.cpp du répertoire SQL Anywhere.
Définition des attributs de connexion
La fonction SQLSetConnectAttr permet de contrôler les détails de la
connexion. Par exemple, l'instruction suivante désactive le mode autocommit
d'ODBC.
retcode = SQLSetConnectAttr( dbc, SQL_AUTOCOMMIT, FALSE
);
$ Pour plus d'informations incluant une liste d'attributs de connexion,
reportez-vous à la section SQLSetConnectAttr du document ODBC
Programmer’s Reference de Microsoft.
De nombreux aspects de la connexion peuvent être contrôlés par
l'intermédiaire des paramètres de connexion. Pour plus d'informations,
reportez-vous à la section "Paramètres de connexion", page 75 du document
ASA Guide d’administration.

Threads et connexions dans les applications ODBC
Chapitre 7 Programmation avec ODBC
Vous pouvez développer des applications ODBC multithread pour Adaptive
Server Anywhere. Il est recommandé d'utiliser une connexion distincte par
thread.
Vous pouvez utiliser une connexion unique pour plusieurs threads. Toutefois,
le serveur de base de données n'autorise pas plus d'une requête active
simultanée par connexion. Si un thread exécute une instruction longue, tous
les autres threads doivent attendre la fin de la requête.
291

Exécution d'instructions SQL
Exécution d'instructions SQL
292
ODBC inclut plusieurs fonctions pour l'exécution d'instructions SQL :
♦ Exécution directe Adaptive Server Anywhere analyse
l’instruction SQL, prépare un plan d'accès et exécute l'instruction.
L'analyse et la préparation du plan d'accès constituent la phase de
préparation de l’instruction.
♦ Exécution préparée La préparation de l'instruction est effectuée
indépendamment de l'exécution. Pour les instructions qui doivent être
exécutées de manière répétitive, cette fonction évite de répéter la
préparation et améliore par conséquent les performances.
$ Pour plus d'informations, reportez-vous à la section "Exécution des
instructions préparées", page 295.
Exécution directe des instructions
La fonction SQLExecDirect prépare et exécute une instruction SQL.
L'instruction peut éventuellement inclure des paramètres.
Le fragment de code suivant indique comment exécuter une instruction sans
paramètres. La fonction SQLExecDirect prend un descripteur d'instruction,
une chaîne SQL, et un indicateur de longueur ou de fin, qui, dans le cas
présent, est un indicateur de chaîne terminée par la valeur NULL.
La procédure décrite dans cette section est simple mais stricte. L'application
n'accepte aucune entrée de l'utilisateur visant à modifier l'instruction. Pour
connaître une méthode plus souple de création d'instructions, reportez-vous à
la section "Exécution d'instructions avec des paramètres de liaison",
page 293.
v Pour exécuter une instruction SQL dans une application ODBC :
1 Allouez un descripteur d'instruction à l'aide de la fonction
SQLAllocHandle.
Par exemple, l'instruction suivante alloue un descripteur de type
SQL_HANDLE_STMT portant le nom stmt, sur une connexion avec le
descripteur dbc:
SQLAllocHandle( SQL_HANDLE_STMT, dbc, &stmt );
2 Appelez la fonction SQLExecDirect pour exécuter l'instruction.

Chapitre 7 Programmation avec ODBC
Par exemple, les lignes suivantes déclarent une instruction et l'exécutent.
La déclaration de deletestmt est effectuée généralement au début de
la fonction :
SQLCHAR deletestmt[ STMT_LEN ] =
"DELETE FROM department WHERE dept_id = 201";
SQLExecDirect( stmt, deletestmt, SQL_NTS) ;
$ Pour obtenir un exemple complet avec le contrôle d'erreurs, consultez le
fichier Samples\ASA\ODBCExecute\odbcexecute.cpp.
$ Pour plus d'informations sur la fonction SQLExecDirect, reportez-vous
à la section SQLExecDirect du document ODBC Programmer’s Reference de
Microsoft.
Exécution d'instructions avec des paramètres de liaison
Cette section explique comment créer et exécuter une instruction SQL en
utilisant des paramètres de liaison pour définir les valeurs des paramètres de
l'instruction lors de l'exécution.
v Pour exécuter une instruction SQL avec des paramètres de liaison
dans une application ODBC :
1 Allouez un descripteur pour l'instruction à l'aide de la fonction
SQLAllocHandle.
Par exemple, l'instruction suivante alloue un descripteur de type
SQL_HANDLE_STMT portant le nom stmt, sur une connexion avec le
descripteur dbc:
SQLAllocHandle( SQL_HANDLE_STMT, dbc, &stmt );
2 Effectuez la liaison des paramètres de l'instruction avec
SQLBindParameter.
Par exemple, les lignes suivantes déclarent des variables pour contenir
les valeurs de l'ID du service, du nom du service, de l'ID du responsable
et de la chaîne d'instruction elle-même. Ensuite, elles lient les
paramètres aux premier, deuxième et troisième paramètre d'une
instruction exécutée à l'aide du descripteur d'instruction stmt.
293

Exécution d'instructions SQL
294
#defined DEPT_NAME_LEN 20
SQLINTEGER cbDeptID = 0,
cbDeptName = SQL_NTS, cbManagerID = 0;
SQLCHAR deptname[ DEPT_NAME_LEN ];
SQLSMALLINT deptID, managerID;
SQLCHAR insertstmt[ STMT_LEN ] =
"INSERT INTO department "
"( dept_id, dept_name, dept_head_id )"
"VALUES (?, ?, ?,)";
SQLBindParameter( stmt, 1, SQL_PARAM_INPUT,
SQL_C_SSHORT, SQL_INTEGER, 0, 0,
&deptID, 0, &cbDeptID);
SQLBindParameter( stmt, 2, SQL_PARAM_INPUT,
SQL_C_CHAR, SQL_CHAR, DEPT_NAME_LEN, 0,
deptname, 0,&cbDeptName);
SQLBindParameter( stmt, 3, SQL_PARAM_INPUT,
SQL_C_SSHORT, SQL_INTEGER, 0, 0,
&managerID, 0, &cbManagerID);
3 Affectez des valeurs aux paramètres.
Par exemple, les lignes suivantes affectent des valeurs aux paramètres de
l'exemple de l'étape 2.
deptID = 201;
strcpy( (char * ) deptname, "Sales East" );
managerID = 902;
En règle générale, ces variables sont définies en réponse à l'action de
l'utilisateur.
4 Exécutez l'instruction à l'aide de la fonction SQLExecDirect.
Par exemple, la ligne suivante exécute la chaîne d'instruction contenue
dans insertstmt sur le descripteur d'instruction stmt.
SQLExecDirect( stmt, insertstmt, SQL_NTS) ;
Les paramètres de liaison sont également utilisés avec des instructions
préparées afin d'améliorer les performances des instructions exécutées à
plusieurs reprises. Pour plus d'informations, reportez-vous à la section
"Exécution des instructions préparées", page 295.
$ Les fragments de code ci-dessus n'incluent pas le contrôle d'erreurs.
Pour obtenir un exemple complet incluant le contrôle d'erreurs, consultez le
fichier Samples\ASA\ODBCExecute\odbcexecute.cpp.
$ Pour plus d'informations sur SQLExecDirect, reportez-vous à la
section SQLExecDirect dans le document ODBC Programmer’s Reference
de Microsoft.

Exécution des instructions préparées
Chapitre 7 Programmation avec ODBC
Les instructions préparées offrent des avantages en matière de performances
pour les instructions répétitives. ODBC offre tout un ensemble de fonctions
d'utilisation d'instructions préparées.
$ Pour plus d'informations sur les instructions préparées, reportez-vous à
la section "Préparation des instructions", page 12.
v Pour exécuter une instruction SQL préparée :
1 Préparez l'instruction via SQLPrepare.
Par exemple, le fragment de code ci-dessous illustre la préparation d'une
instruction INSERT.
SQLRETURN retcode;
SQLHSTMT stmt;
retcode = SQLPrepare( stmt,
"INSERT INTO department
( dept_id, dept_name, dept_head_id )
VALUES (?, ?, ?,)",
SQL_NTS);
Dans cet exemple :
♦ retcode Contient un code de retour qui doit être testé pour vérifier
la réussite ou l'échec de l'opération.
♦ stmt Fournit un descripteur à l'instruction qui servira de référence
ultérieurement.
♦ ? Les points d'interrogation sont des marques de réservation pour
les paramètres de l'instruction.
2 Définissez les valeurs des paramètres de l'instruction à l'aide de la
fonction SQLBindParameter.
Par exemple, l'appel de fonction ci-dessous définit la valeur de la
variable dept_id.
SQLBindParameter( stmt,
1,
SQL_PARAM_INPUT,
SQL_C_SSHORT,
SQL_INTEGER,
0,
0,
&sDeptID,
0,
&cbDeptID);
Dans cet exemple :
295

Exécution d'instructions SQL
296
♦ stmt Descripteur d’instruction
♦ 1 Indique que cet appel définit la valeur de la première marque de
réservation.
♦ SQL_PARAM_INPUT Indique que le paramètre est une instruction
en entrée.
♦ SQL_C_SHORT Indique le type de données en langage C utilisé
dans l'application.
♦ SQL_INTEGER Indique le type de données SQL utilisé dans la base
de données.
♦ Les deux paramètres suivants indiquent la précision de la colonne et
le nombre de chiffres après la virgule : ils sont tous deux égaux à
zéro pour les nombres entiers.
♦ &sDeptID Pointeur sur un buffer pour la valeur du paramètre.
♦ 0 Indique la longueur du buffer en octets.
♦ &cbDeptID Pointeur sur un buffer pour la longueur de la valeur du
paramètre.
3 Liez les deux autres paramètres et attribuez des valeurs à sDeptId :
4 Exécutez l'instruction.
retcode = SQLExecute( stmt);
Les étapes 2 à 4 peuvent être exécutées à plusieurs reprises.
5 Supprimez l'instruction.
En supprimant l'instruction, vous libérez les ressources qui lui sont
associées. Pour supprimer une instruction, utilisez SQLFreeHandle.
$ Pour obtenir un exemple complet incluant le contrôle d'erreurs,
consultez le fichier Samples\ASA\ODBCPrepare\odbcprepare.cpp.
$ Pour plus d'informations sur SQLPrepare, reportez-vous à la section
SQLPrepare dans le document ODBC Programmer’s Reference de
Microsoft.

Jeux de résultats
Chapitre 7 Programmation avec ODBC
Les applications ODBC utilisent des curseurs pour manipuler et mettre à jour
les jeux de résultats. Adaptive Server Anywhere offre un support complet
des différents types de curseurs et opérations sur curseur.
$ Pour plus d'informations sur les curseurs, reportez-vous à la section
"Utilisation des curseurs", page 20.
Choix des caractéristiques d'un curseur
Les fonctions ODBC qui exécutent des instructions et manipulent des jeux de
résultats utilisent des curseurs pour accomplir leurs tâches. Les applications
ouvrent un curseur de manière implicite chaque fois qu'elles exécutent une
fonction SQLExecute ou SQLExecDirect.
Pour les applications qui parcourent un jeu de résultats uniquement vers
l'avant sans le mettre à jour, le comportement des curseurs est relativement
simple. Par défaut, les applications ODBC requièrent ce comportement.
ODBC définit un curseur en lecture seule, à défilement avant uniquement et,
dans ce cas, Adaptive Server Anywhere fournit un curseur optimisé du point
de vue des performances.
$ Pour avoir un exemple simple de curseur à défilement avant
uniquement, reportez-vous à la section "Récupération de données", page 298.
Pour les applications ayant besoin de parcourir un jeu de résultats à la fois
vers l'avant et vers l'arrière (c'est notamment le cas de nombreuses
applications à interface graphique), le comportement des curseurs est plus
complexe. Que fait une application lorsqu'elle renvoie vers une ligne qui a
été mise à jour par une autre application ? ODBC définit une variété de
curseurs avec défilement afin de vous permettre de générer le
comportement qui convient à votre application. Adaptive Server Anywhere
offre un jeu complet de curseurs qui correspondent aux types de
curseur ODBC avec défilement.
La définition des caractéristiques du curseur ODBC s'effectue en appelant la
fonction SQLSetStmtAttr, qui définit les attributs de l'instruction. Vous
devez appeler la fonction SQLSetStmtAttr avant d'exécuter une instruction
qui crée un jeu de résultats.
Vous pouvez utiliser la fonction SQLSetStmtAttr pour définir les
caractéristiques de plusieurs curseurs. Les caractéristiques qui déterminent le
type de curseur fourni par Adaptive Server Anywhere sont les suivantes :
297

Jeux de résultats
Exemple
Récupération de données
298
♦ SQL_ATTR_CURSOR_SCROLLABLE Définie avec la valeur
SQL_SCROLLABLE pour un curseur avec défilement et avec la valeur
SQL_NONSCROLLABLE pour un curseur avec défilement avant
uniquement. SQL_NONSCROLLABLE est la valeur par défaut.
♦ SQL_ATTR_CONCURRENCY Définie avec l'une des valeurs suivantes :
♦ SQL_CONCUR_READ_ONLY Interdit les mises à jour.
SQL_CONCUR_READ_ONLY est la valeur par défaut.
♦ SQL_CONCUR_LOCK Utilise le niveau de verrouillage le plus bas
pour garantir que la ligne peut être mise à jour.
♦ SQL_CONCUR_ROWVER Utilise le contrôle de concurrence
optimiste en comparant des versions de ligne telles que
SQLBase ROWID ou Sybase TIMESTAMP.
♦ SQL_CONCUR_VALUES Utilise le contrôle de concurrence
optimiste en comparant les valeurs.
$ Pour plus d'informations, reportez-vous à la section SQLSetStmtAttr
dans le document ODBC Programmer’s Reference de Microsoft.
Le fragment de code suivant définit un curseur en lecture seule et avec
défilement :
SQLAllocHandle( SQL_HANDLE_STMT, dbc, &stmt );
SQLSetStmtAttr( stmt, SQL_ATTR_CURSOR_SCROLLABLE,
SQL_SCROLLABLE, 0 );
Pour récupérer des lignes d'une base de données, exécutez une instruction
SELECT à l'aide de la fonction SQLExecute ou SQLExecDirect. Cette
opération ouvre un curseur sur l'instruction. Utilisez ensuite SQLFetch ou
SQLExtendedFetch pour extraire des lignes par l'intermédiaire du curseur.
Lorsqu'une application libère l'instruction à l'aide de SQLFreeHandle, elle
ferme le curseur.
Pour extraire les valeurs d'un curseur, l'application peut utiliser SQLBindCol
ou SQLGetData. Avec SQLBindCol, les valeurs sont récupérées
automatiquement à chaque extraction. Avec SQLGetData, vous devez les
appeler pour chaque colonne après chaque extraction.
SQLGetData est utilisé pour extraire des valeurs en plusieurs morceaux
pour des colonnes de type LONG VARCHAR ou LONG BINARY. Vous
pouvez également définir l'attribut de l'instruction SQL_MAX_LENGTH sur
une valeur suffisamment grande pour contenir la valeur entière de la colonne.
La valeur par défaut de SQL_ATTR_MAX_LENGTH est 256 Ko.

Chapitre 7 Programmation avec ODBC
Le fragment de code suivant ouvre un curseur sur une requête et récupère les
données par l'intermédiaire du curseur. Le contrôle d'erreurs a été
volontairement omis afin de faciliter la lecture de cet exemple. Ce fragment
est issu d'un exemple complet, que vous trouverez dans le fichier
Samples\ASA\ODBCSelect\odbcselect.cpp.
SQLINTEGER cbDeptID = 0, cbDeptName = SQL_NTS, cbManagerID = 0;
SQLCHAR deptname[ DEPT_NAME_LEN ];
SQLSMALLINT deptID, managerID;
SQLHENV env;
SQLHDBC dbc;
SQLHSTMT stmt;
SQLRETURN retcode;
SQLAllocHandle( SQL_HANDLE_ENV, SQL_NULL_HANDLE, &env );
SQLSetEnvAttr( env, SQL_ATTR_ODBC_VERSION, (void*)SQL_OV_ODBC3, 0);
SQLAllocHandle( SQL_HANDLE_DBC, env, &dbc );
SQLConnect( dbc,
(SQLCHAR*) "ASA 8.0 Sample", SQL_NTS,
(SQLCHAR*) "DBA", SQL_NTS,
(SQLCHAR*) "SQL", SQL_NTS );
SQLAllocHandle( SQL_HANDLE_STMT, dbc, &stmt );
SQLBindCol( stmt, 1, SQL_C_SSHORT, &deptID, 0, &cbDeptID);
SQLBindCol( stmt, 2, SQL_C_CHAR, deptname, sizeof(deptname),
&cbDeptName);
SQLBindCol( stmt, 3, SQL_C_SSHORT, &managerID, 0, &cbManagerID);
SQLExecDirect( stmt, (SQLCHAR * )
"SELECT dept_id, dept_name, dept_head_id FROM DEPARTMENT "
"ORDER BY dept_id", SQL_NTS );
while( ( retcode = SQLFetch( stmt ) ) != SQL_NO_DATA ){
printf( "%d %20s %d\n", deptID, deptname, managerID );
}
SQLFreeHandle( SQL_HANDLE_STMT, stmt );
SQLDisconnect( dbc );
SQLFreeHandle( SQL_HANDLE_DBC, dbc );
SQLFreeHandle( SQL_HANDLE_ENV, env );
Le nombre de positions de ligne que vous pouvez extraire dans un curseur est
fonction de la taille d'un entier. Vous pouvez extraire des lignes numérotées
jusqu'à 2 147 483 646, ce qui correspond à la valeur que peut contenir un
entier, moins un. Lorsque vous utilisez des nombres négatifs (comptage des
lignes à partir de la fin), vous pouvez extraire un nombre de lignes égal à la
plus grande valeur négative que peut contenir un entier, plus un.
299

Jeux de résultats
Mise à jour et suppression de lignes par l'intermédiaire d'un
curseur
Utilisation de signets
300
Le document ODBC Programmer’s Reference de Microsoft recommande
d’utiliser l’instruction SELECT... FOR UPDATE pour indiquer qu’une
requête peut être mise à jour à l'aide d'opérations positionnées. Il n'est pas
nécessaire d'utiliser la clause FOR UPDATE dans
Adaptive Server Anywhere. Les instructions SELECT peuvent être mises à
jour automatiquement tant que les conditions suivantes sont respectées :
♦ La requête sous-jacente supporte ce type d'opération.
Cela signifie que tant qu'une instruction modifiant les données des
colonnes du résultat est significative, les instructions de modification de
données positionnées peuvent être exécutées sur le curseur.
L'option de base de données ANSI_UPDATE_CONSTRAINTS limite
le type de requête actualisable.
$ Pour plus d'informations, reportez-vous à la section "Option
ANSI_UPDATE_CONSTRAINTS", page 602 du document ASA Guide
d’administration.
♦ Le type de curseur supporte les mises à jour.
Si vous utilisez un curseur en lecture seule, vous ne pourrez pas mettre à
jour le jeu de résultats.
ODBC offre deux autres moyens d'exécuter les mises à jour et les
suppressions positionnées.
♦ Utilisation de la fonction SQLSetPos.
En fonction des paramètres entrés (SQL_POSITION, SQL_REFRESH,
SQL_UPDATE, SQL_DELETE), SQLSetPos définit la position du
curseur et permet à une application d'actualiser les données, ou encore
de mettre à jour ou de supprimer des données du jeu de résultats.
Il s'agit de la méthode à utiliser avec Adaptive Server Anywhere.
♦ Envoi d'instructions UPDATE et DELETE positionnées à l'aide de la
fonction SQLExecute. Cette méthode ne doit pas être utilisée avec
Adaptive Server Anywhere.
ODBC fournit des signets qui sont des valeurs utilisées pour identifier les
lignes d'un curseur. Adaptive Server Anywhere accepte des signets pour tous
les types de curseur à l'exception des curseurs dynamiques.

Chapitre 7 Programmation avec ODBC
Dans les versions antérieures à ODBC 3.0, une base de données pouvait
seulement spécifier si elle supportait ou non les signets. Il n'existait pas
d'interface pour fournir cette information sur chaque type de curseur. De
même, il n'y avait aucun moyen au niveau du serveur de base de données
d'indiquer quels types de signet de curseur étaient supportés. Pour les
applications ODBC 2, Adaptive Server Anywhere signale qu'il ne supporte
pas les signets. Il n'y a donc rien qui vous empêche de tenter d'utiliser des
signets avec des curseurs dynamiques ; mais vous devez néanmoins proscrire
cette combinaison.
301

Appel de procédures stockées
Appel de procédures stockées
Procédures et jeux
de résultats
Exemple
302
La présente section explique comment créer et appeler des procédures
stockées, et traiter des résultats à partir d'une application ODBC.
$ Pour une description complète des procédures stockées et des triggers,
reportez-vous à la section "Utilisation des procédures, des triggers et des
batchs", page 541 du document ASA Guide de l’utilisateur SQL.
Il existe deux types de procédures : celles qui renvoient des jeux de résultats
et celles qui n'en renvoient pas. Vous pouvez utiliser SQLNumResultCols
pour les distinguer. Si la procédure ne renvoie pas de jeu de résultats, le
nombre de colonnes de résultats est égal à zéro. Dans le cas contraire, vous
pouvez extraire les valeurs à l'aide de SQLFetch ou de SQLExtendedFetch
comme vous le feriez pour n'importe quel autre curseur.
Les paramètres doivent être transmis aux procédures à l'aide de marqueurs de
paramètre (points d'interrogation). Utilisez SQLBindParameter pour
attribuer une zone de stockage à chaque marqueur de paramètre, selon qu'il
s'agit d'un paramètre INPUT, OUTPUT ou INOUT.
Pour traiter des jeux de résultats multiples, ODBC doit décrire le curseur en
cours d'exécution et pas le jeu de résultat de la procédure. C'est pourquoi
ODBC ne décrit pas toujours les noms de colonnes tels qu'ils sont définis
dans la clause RESULT de la définition de la procédure stockée. Pour éviter
ce problème, vous pouvez utiliser des alias de colonnes dans votre curseur de
jeu de résultats.
L'exemple suivant crée et appelle une procédure qui ne renvoie aucun jeu de
résultats. Cette procédure prend un paramètre INOUT et incrémente sa
valeur. La valeur de variable num_col est ici zéro, car la procédure ne
renvoie pas de jeu de résultats. Le contrôle d'erreurs a été volontairement
omis afin de faciliter la lecture de cet exemple.
HDBC dbc;
HSTMT stmt;
long i;
SWORD num_col;
/* Crée une procédure */
SQLAllocStmt( dbc, &stmt );
SQLExecDirect( stmt,
"CREATE PROCEDURE Increment( INOUT a INT )" \
" BEGIN" \
" SET a = a + 1" \
" END", SQL_NTS );
/* Appelle la procédure pour incrémenter "i" */
i = 1;

Exemple
Chapitre 7 Programmation avec ODBC
SQLBindParameter( stmt, 1, SQL_C_LONG, SQL_INTEGER, 0,
0, &i, NULL );
SQLExecDirect( stmt, "CALL Increment( ? )",
SQL_NTS );
SQLNumResultCols( stmt, &num_col );
do_something( i );
L'exemple qui suit appelle une procédure qui renvoie un jeu de résultats. La
variable num_col a ici la valeur 2 car la procédure renvoie un jeu de résultats
avec deux colonnes. Le contrôle d'erreurs a été volontairement omis afin de
faciliter la lecture de cet exemple.
HDBC dbc;
HSTMT stmt;
SWORD num_col;
RETCODE retcode;
char emp_id[ 10 ];
char emp_lame[ 20 ];
/* Crée la procédure */
SQLExecDirect( stmt,
"CREATE PROCEDURE employees()" \
" RESULT( emp_id CHAR(10), emp_lname CHAR(20))"\
" BEGIN" \
" SELECT emp_id, emp_lame FROM employee" \
" END", SQL_NTS );
/* Appelle la procédure - imprime les résultats */
SQLExecDirect( stmt, "CALL employees()", SQL_NTS );
SQLNumResultCols( stmt, &num_col );
SQLBindCol( stmt, 1, SQL_C_CHAR, &emp_id,
sizeof(emp_id), NULL );
SQLBindCol( stmt, 2, SQL_C_CHAR, &emp_lname,
sizeof(emp_lname), NULL );
for( ;; ) {
retcode = SQLFetch( stmt );
if( retcode == SQL_NO_DATA_FOUND ) {
retcode = SQLMoreResults( stmt );
if( retcode == SQL_NO_DATA_FOUND ) break;
} else {
do_something( emp_id, emp_lname );
}
}
303

Gestion des erreurs
Gestion des erreurs
304
Les erreurs détectées dans ODBC sont signalées par la valeur renvoyée par
chaque appel de fonction ODBC, et soit par la fonction SQLError, soit par
la fonction SQLGetDiagRec. La fonction SQLError était utilisée dans les
versions précédentes d'ODBC, exceptée la version 3. A partir de la version 3,
la fonction SQLError, obsolète, a été remplacée par la fonction
SQLGetDiagRec.
Chaque fonction ODBC renvoie une valeur SQLRETURN, qui est l'un des
codes d'état suivants :
Code d'état Description
SQL_SUCCESS Aucune erreur.
SQL_SUCCESS_WITH_INFO La fonction s'est exécutée en totalité, mais un
appel adressé à SQLError indique un
avertissement.
Le plus souvent, cet état indique qu'une valeur
renvoyée est trop longue pour le buffer fourni par
l'application.
SQL_ERROR La fonction ne s'est pas exécutée en raison d'une
erreur. Vous pouvez appeler SQLError pour
obtenir plus d'informations.
SQL_INVALID_HANDLE Un descripteur d'environnement, de connexion ou
d'instruction incorrect a été transmis en tant que
paramètre.
Une erreur de ce type se produit souvent lorsqu'un
descripteur est utilisé après avoir été libéré ou
lorsque le descripteur est le pointeur NULL.
SQL_NO_DATA_FOUND Aucune information n'est disponible.
Cet état, qui se rencontre principalement lors de
l'extraction à partir d'un curseur, indique que le
curseur ne contient plus aucune ligne.
SQL_NEED_DATA Un paramètre requiert des données.
Il s'agit là d'une fonctionnalité avancée dont vous
trouverez la description dans la
documentation SDK ODBC sous les rubriques
SQLParamData et SQLPutData.

Exemple 1
Chapitre 7 Programmation avec ODBC
A chaque descripteur d’environnement, de connexion ou d’instruction
peuvent être associés un(e) ou plusieurs avertissements ou erreurs. Chaque
appel à SQLError ou à SQLGetDiagRec renvoie les informations
correspondant à une erreur donnée, puis supprime ces dernières. Si vous
n'appelez pas SQLError ou SQLGetDiagRec pour supprimer toutes les
erreurs, la suppression s'effectue lors de l'appel de fonction suivant
transmettant le même descripteur en tant que paramètre.
Chaque appel à SQLError transmet trois descripteurs pour un
environnement, une connexion et une instruction. Le premier appel utilise
SQL_NULL_HSTMT pour obtenir l'erreur associée à une connexion. De
même, SQL_NULL_DBC et SQL_NULL_HSTMT détectent toute erreur
associée au descripteur d'environnement.
Chaque appel à SQLGetDiagRec peut transmettre un descripteur soit pour
un environnement, soit pour une connexion, soit pour une instruction. Le
premier appel transmet un descripteur de type SQL_HANDLE_DBC pour
obtenir l'erreur associée à une connexion. Le deuxième appel transmet un
descripteur de type SQL_HANDLE_STMT pour obtenir l'erreur associée à
l'instruction qui vient d'être exécutée.
SQLError et SQLGetDiagRec renvoient SQL_SUCCESS s'il y a une
erreur à signaler (et non pas SQL_ERROR), et SQL_NO_DATA_FOUND
s'il n'y a plus d'erreurs à signaler.
Ce fragment de code utilise SQLError et des codes de retour :
/* Déclare les variables requises */
SQLHDBC dbc;
SQLHSTMT stmt;
SQLRETURN retcode;
UCHAR errmsg[100];
/* code omis ici */
retcode = SQLAllocHandle(SQL_HANDLE_STMT, dbc, &stmt );
if( retcode == SQL_ERROR ){
SQLError( env, dbc, SQL_NULL_HSTMT, NULL, NULL,
errmsg, sizeof(errmsg), NULL );
/* Suppose que print_error est défini */
print_error( "Echec de l'allocation", errmsg );
return;
}
/* Supprime des articles de la commande 2015 */
retcode = SQLExecDirect( stmt,
305

Gestion des erreurs
Exemple 2
306
"delete from sales_order_items where id=2015",
SQL_NTS );
if( retcode == SQL_ERROR ) {
SQLError( env, dbc, stmt, NULL, NULL,
errmsg, sizeof(errmsg), NULL );
/* Suppose que print_error est défini */
print_error( "Impossible de supprimer les articles",
errmsg );
return;
L’extrait de code suivant utilise SQLGetDiagRec et les codes de retour:
/* Declare les variables requises */
SQLHDBC dbc;
SQLHSTMT stmt;
SQLRETURN retcode;
SQLSMALLINT errmsglen;
SQLINTEGER errnative;
UCHAR errmsg[255];
UCHAR errstate[5];
/* code omis ici */
retcode = SQLAllocHandle(SQL_HANDLE_STMT, dbc, &stmt );
if( retcode == SQL_ERROR ){
SQLGetDiagRec(SQL_HANDLE_DBC, dbc, 1, errstate,
&errnative, errmsg, sizeof(errmsg), &errmsglen);
/* Suppose que print_error est défini */
print_error( "Echec de l'allocation", errstate,
errnative, errmsg );
return;
}
/* Supprime des articles de la commande 2015 */
retcode = SQLExecDirect( stmt,
"delete from sales_order_items where id=2015",
SQL_NTS );

Chapitre 7 Programmation avec ODBC
if( retcode == SQL_ERROR ) {
SQLGetDiagRec(SQL_HANDLE_STMT, stmt, recnum,
errstate,
&errnative, errmsg, sizeof(errmsg), &errmsglen);
/* Suppose que print_error est défini */
print_error("Impossible de supprimer les articles",
errstate,
errnative, errmsg );
return;
}
307

Gestion des erreurs
308

CHAPITRE 8
Interface Outils de base de données
Présentation
Sommaire
Ce chapitre explique comment utiliser la bibliothèque d'outils de base de
données fournie avec Adaptive Server Anywhere pour ajouter des
fonctionnalités de gestion de bases de données à des applications en
langage C ou C++.
Sujet Page
Introduction à l'interface Outils de base de données 310
Utilisation de l'interface Outils de base de données 311
Fonctions DBTools 320
Structures DBTools 332
Types d'énumération DBTools 364
309

Introduction à l'interface Outils de base de données
Introduction à l'interface Outils de base de
données
Plates-formes
supportées
Windows CE
Fichier d'en-tête
dbtools.h
310
Pour gérer les bases de données, Sybase Adaptive Server Anywhere est livré
avec Sybase Central et avec un ensemble d'utilitaires. Ces outils permettent
d'effectuer des tâches telles que la création et la sauvegarde de bases de
données, la conversion de journaux de transactions en SQL, etc.
Tous les utilitaires de gestion de bases de données exploitent une
bibliothèque partagée appelée bibliothèque d'outils de base de données. Une
version est fournie pour chacun des systèmes d'exploitation suivants :
Windows 95/98 et Windows NT. Le nom de cette bibliothèque est
dbtool8.dll.
La bibliothèque d'outils de base de données vous permet de développer vos
propres utilitaires de gestion de bases de données ou d'intégrer de telles
fonctionnalités dans vos applications. Ce chapitre décrit l'interface de la
bibliothèque d'outils de base de données. A cet effet, vous devez savoir
comment appeler des DLL à partir de votre environnement de
développement.
La bibliothèque d'outils de base de données offre des fonctions, ou points
d'entrée, pour chaque utilitaire de gestion de bases de données. Elle contient,
en outre, des fonctions supplémentaires devant être appelées avant ou après
l'utilisation d'autres fonctions d'outils de base de données.
La bibliothèque dbtool8.dll est fournie pour Windows CE, mais comprend
uniquement des points d'entrée pour DBToolsInit, DBToolsFini,
DBRemoteSQL et DBSynchronizeLog. Les autres outils ne sont pas fournis
pour Windows CE.
Le fichier d'en-tête dbtools fourni avec Adaptive Server Anywhere répertorie
les points d'entrée de la bibliothèque DBTools, ainsi que les structures
servant à échanger des informations avec la bibliothèque. Le fichier dbtools.h
est installé dans le sous-répertoire h du répertoire d'installation. Consultez le
fichier dbtools.h pour obtenir des informations récentes sur les points
d'entrée et le contenu de la structure.
Le fichier d'en-tête dbtools.h fait appel à deux autres fichiers :
♦ sqlca.h Ce fichier est inclus pour exploiter certaines macros et non la
zone de communication SQL (SQLCA) proprement dite.
♦ dllapi.h Ce fichier définit des macros de préprocesseur utilisables dans
des macros propres à un système d'exploitation ou à une langue.
Le fichier d'en-tête sqldef.h comporte des valeurs de code d'erreur.

Chapitre 8 Interface Outils de base de données
Utilisation de l’interface Outils de base de
données
Cette section explique comment développer des applications utilisant
l'interface DBTools pour gérer des bases de données.
Utilisation des bibliothèques d'importation
Plates-formes
supportées
Pour pouvoir utiliser les fonctions DBTools, vous devez relier votre
application à une bibliothèque d'importation DBTools contenant la
définition des fonctions requises.
Les bibliothèques d'importation sont spécifiques d'un compilateur et sont
fournies pour les systèmes d'exploitation Windows excepté Windows CE.
Celles de l'interface DBTools, fournies avec Adaptive Server Anywhere, se
trouvent dans le sous-répertoire lib de chaque répertoire de système
d'exploitation (lui-même dans le répertoire d'installation
d'Adaptive Server Anywhere). Les bibliothèques fournies sont les suivantes :
Compilateur Bibliothèque
Watcom win32\dbtlstw.lib
Microsoft win32\dbtlstM.lib
Borland win32\dbtlstB.lib
Démarrage et arrêt de la bibliothèque DBTools
Avant d'utiliser toute fonction DBTools, il est nécessaire d'appeler
DBToolsInit. Lorsque vous n'avez plus besoin de la bibliothèque, vous devez
appeler DBToolsFini.
Le principal objet des fonctions DBToolsInit et DBToolsFini est de
permettre à la DLL DBTools de charger la DLL de langue
d'Adaptive Server Anywhere. Cette dernière contient la version localisée de
tous les messages d'erreur et de toutes les invites utilisés en interne par
DBTools. Si vous n'appelez pas DBToolsFini, le compteur de références de
la DLL de langue n'est pas décrémenté et la DLL n'est pas déchargée. Par
conséquent, veillez à ce que chaque appel de DBToolsInit soit suivi d'un
appel de DBToolsFini.
La portion de code suivante indique comment initialiser et vider DBTools :
311

Utilisation de l'interface Outils de base de données
312
// Déclarations
a_dbtools_info info;
short ret;
Appel des fonctions DBTools
// Initialisation de la structure a_dbtools_info
memset( &info, 0, sizeof( a_dbtools_info) );
info.errorrtn = (MSG_CALLBACK)MaRoutineErreur;
// Initialisation de DBTools
ret = DBToolsInit( &info );
if( ret != EXIT_OKAY ) {
// Echec d'initialisation de la DLL
…
}
// Appel de diverses routines DBTools . . .
…
// Réinitialisation de la DLL DBTools
DBToolsFini( &info );
Pour pouvoir exécuter chaque outil, il faut d'abord renseigner une structure,
puis appeler une fonction (ou point d'entrée) de la DLL DBTools. Tous les
points d'entrée requièrent un pointeur sur une structure unique comme
argument.
L'exemple ci-dessous indique comment utiliser la fonction DBBackup sous
un système d'exploitation Windows. Il est destiné aux systèmes
d'exploitation Windows 95 ou Windows NT.
// Initialisation de la structure
a_backup_db backup_info;
memset( &backup_info, 0, sizeof( backup_info ) );
// Configuration de la structure
backup_info.version = DB_TOOLS_VERSION_NUMBER;
backup_info.output_dir = "C:\BACKUP";
backup_info.connectparms
="uid=DBA;pwd=SQL;dbf=asademo.db";
backup_info.startline = "dbeng8.EXE";
backup_info.confirmrtn = (MSG_CALLBACK) ConfirmRtn ;
backup_info.errorrtn = (MSG_CALLBACK) ErrorRtn ;
backup_info.msgrtn = (MSG_CALLBACK) MessageRtn ;
backup_info.statusrtn = (MSG_CALLBACK) StatusRtn ;
backup_info.backup_database = TRUE;
// Lancement de la sauvegarde
DBBackup( &backup_info );

Chapitre 8 Interface Outils de base de données
$ Pour plus d'informations sur les éléments des structures DBTools,
reportez-vous à la section "Structures DBTools", page 332.
Codes de retour des composants logiciels
Tous les outils de base de données sont fournis comme point d'entrée dans
une DLL. Ces points d'entrée utilisent les codes de retour suivants :
Code Explication
0 Succès
1 Panne générale
2 Format de fichier incorrect
3 Fichier introuvable, impossible d'ouvrir
4 Mémoire saturée
5 Terminé par l'utilisateur
6 Echec de la communication
7 Nom de base de données requis manquant
8 Discordance entre les protocoles client et serveur
9 Impossible de se connecter au serveur de base de données
10 Le serveur de base de données ne fonctionne pas
11 Impossible de trouver le serveur de base de données
254 Temps d'arrêt atteint
Utilisation des fonctions callback
Utilisation des
fonctions callback
255 Paramètres incorrects sur la ligne de commande
Plusieurs éléments des structures DBTools sont de type MSG_CALLBACK.
Il s'agit de pointeurs sur des fonctions callback.
Les fonctions callback permettent aux fonctions DBTools de rendre le
contrôle des opérations à l'application appelante. La bibliothèque DBTools
s'en sert dans quatre situations précises pour gérer les messages envoyés par
les fonctions DBTools à l'utilisateur :
♦ Confirmation Appelée lorsqu'une opération doit être confirmée par
l'utilisateur. Si, par exemple, le répertoire de sauvegarde n'existe pas, la
DLL des outils demande s'il doit être créé.
313

Utilisation de l'interface Outils de base de données
Affectation d’une
fonction callback à
une structure
Exemple de
fonction callback
de confirmation
Exemple de
fonction callback
d'erreur
314
♦ Message d’erreur Fonction appelée pour transmettre un message
lorsqu'une erreur se produit (par exemple, un espace disque insuffisant
lors d'une opération d'enregistrement).
♦ Message d’information Fonction appelée pour permettre aux outils
d'afficher un message destiné à l'utilisateur (tel que le nom de la table en
cours de sauvegarde).
♦ Informations d'état Fonction appelée pour permettre aux outils
d'afficher l'état d'une opération (tel que le pourcentage atteint lors du
déchargement d'une table).
Vous pouvez affecter directement une routine callback à une structure.
L'exemple suivant montre une instruction utilisant une structure de
sauvegarde :
backup_info.errorrtn = (MSG_CALLBACK) MaFonction
MSG_CALLBACK est défini dans le fichier d'en-tête dllapi.h fourni avec
Adaptive Server Anywhere. Les routines des outils peuvent renvoyer des
messages à l'application appelante pour que celle-ci les affiche dans
l'interface utilisateur adéquate (qu'il s'agisse d'un environnement interface
utilisateur, de l'affichage standard sur des systèmes en mode caractère ou de
toute autre interface utilisateur).
L'exemple de routine de confirmation suivant invite l'utilisateur à
sélectionner OUI ou NON et renvoie son choix :
extern short _callback ConfirmRtn(
char far * question )
{
int ret;
if( question != NULL ) {
ret = MessageBox( HwndParent, question,
"Confirmez", MB_ICONEXCLAMTION|MB_YESNO );
}
return( 0 );
}
Exemple de routine de gestion des messages d'erreur affichant les messages
dans une boîte de message.
extern short _callback ErrorRtn(
char far * errorstr )
{
if( errorstr != NULL ) {
ret = MessageBox( HwndParent, errorstr,
"Erreur de sauvegarde", MB_ICONSTOP|MB_OK );
}
return( 0 );
}

Exemple de
fonction callback
de message
Exemple de
fonction callback
d'état
Chapitre 8 Interface Outils de base de données
Exemple de mise en oeuvre courante d’une fonction callback affichant un
message à l'écran :
extern short _callback MessageRtn(
char far * errorstr )
{
if( messagestr != NULL ) {
OutputMessageToWindow( messagestr );
}
return( 0 );
}
Une routine callback d'état est appelée lorsque les outils doivent afficher
l'état d'une opération (tel que le pourcentage atteint lors du déchargement
d'une table). Ici encore, une mise en oeuvre courante affiche simplement le
message à l'écran :
extern short _callback StatusRtn(
char far * statusstr )
{
if( statusstr == NULL ) {
return FALSE;
}
OutputMessageToWindow( statustr );
return TRUE;
}
Numéros de version et compatibilité
Compatibilité
Chaque structure possède un élément indiquant le numéro de version. Il est
recommandé de l'employer pour indiquer la version de la bibliothèque
DBTools avec laquelle votre application a été développée. La version
actuelle de la bibliothèque est incluse sous la forme d'une constante dans le
fichier d'en-tête dbtools.h.
v Pour affecter le numéro de version courant à une structure :
♦ Avant d'appeler la fonction DBTools, affectez la constante de version à
l'élément de version de la structure. L'instruction suivante affecte la
version courante à une structure de sauvegarde :
backup_info.version = DB_TOOLS_VERSION_NUMBER;
Le numéro de version permet à votre application de continuer à fonctionner
avec des versions plus récentes de la bibliothèque DBTools. Les fonctions
DBTools utilisent le numéro fourni par l'application pour assurer la bonne
exécution de celle-ci, même si de nouveaux éléments ont été ajoutés dans la
structure DBTools.
315

Utilisation de l'interface Outils de base de données
Utilisation de champs de bits
Exemple DBTools
316
Les applications ne fonctionneront pas avec des versions antérieures de la
bibliothèque DBTools.
De nombreuses structures DBTools utilisent des champs de bits pour stocker
des informations booléennes de façon compacte. Par exemple, la structure de
sauvegarde comporte les champs de bits suivants :
a_bit_field backup_database : 1;
a_bit_field backup_logfile : 1;
a_bit_field backup_writefile: 1;
a_bit_field no_confirm : 1;
a_bit_field quiet : 1;
a_bit_field rename_log : 1;
a_bit_field truncate_log : 1;
a_bit_field rename_local_log: 1;
Dans cet exemple, chaque champ de bits a une longueur d'un seul bit, comme
l'indique le chiffre 1, à gauche du point-virgule, dans la déclaration de la
structure. Le type de données spécifique utilisé dépend de la valeur affectée à
a_bit_field, qui est définie au début du fichier dbtools.h et dépend du
système d'exploitation.
Pour transmettre des informations booléennes à la structure, il faut affecter la
valeur entière 0 ou 1 à un champ de bits.
Cet exemple, ainsi que les instructions de compilation, sont disponibles dans
le sous-répertoire Samples\ASA\DBTools du répertoire SQL Anywhere. Le
programme exemple s'intitule Samples\ASA\DBTools\main.c. Il indique
comment utiliser la bibliothèque DBTools pour effectuer une sauvegarde de
la base de données.
#define WINNT

#include
#include "windows.h"
#include "string.h"
#include "dbtools.h"
Chapitre 8 Interface Outils de base de données
extern short _callback ConfirmCallBack(char far * str){
if( MessageBox( NULL, str, "Backup",
MB_YESNO|MB_ICONQUESTION ) == IDYES ) {
return 1;
}
return 0;
}
extern short _callback MessageCallBack( char far * str){
if( str != NULL ) {
fprintf( stdout, "%s", str );
fprintf( stdout, "\n" );
fflush( stdout );
}
return 0;
}
extern short _callback StatusCallBack( char far * str ){
if( str != NULL ) {
fprintf( stdout, "%s", str );
fprintf( stdout, "\n" );
fflush( stdout );
}
return 0;
}
extern short _callback ErrorCallBack( char far * str ){
if( str != NULL ) {
fprintf( stdout, "%s", str );
fprintf( stdout, "\n" );
fflush( stdout );
}
return 0;
}
// Point d'entrée principal dans le programme.
int main( int argc, char * argv[] ){
a_backup_db backup_info;
a_dbtools_info dbtinfo;
char dir_name[ _MAX_PATH + 1];
char connect[ 256 ];
HINSTANCE hinst;
FARPROC dbbackup;
FARPROC dbtoolsinit;
FARPROC dbtoolsfini;
317

Utilisation de l'interface Outils de base de données
318
// Toujours initialiser à 0 pour que les
//nouvelles versions de la structure soient
compatibles.
memset( &backup_info, 0, sizeof( a_backup_db ) );
backup_info.version = DB_TOOLS_VERSION_8_0_00;
backup_info.quiet = 0;
backup_info.no_confirm = 0;
backup_info.confirmrtn =
(MSG_CALLBACK)ConfirmCallBack;
backup_info.errorrtn = (MSG_CALLBACK)ErrorCallBack;
backup_info.msgrtn = (MSG_CALLBACK)MessageCallBack;
backup_info.statusrtn = (MSG_CALLBACK)StatusCallBack;
if( argc > 1 ) {
strncpy( dir_name, argv[1], _MAX_PATH );
} else {
// DBTools n'accepte pas la barre
// oblique en fin de chaîne
strcpy( dir_name, "c:\\temp" );
}
backup_info.output_dir = dir_name;
if( argc > 2 ) {
strncpy( connect, argv[2], 255 );
} else {
// Suppose que le moteur s'exécute déjà.
strcpy( connect, "DSN=ASA 8.0 Sample" );
}
backup_info.connectparms = connect;
backup_info.startline = "";
backup_info.quiet = 0;
backup_info.no_confirm = 0;
backup_info.backup_database = 1;
backup_info.backup_logfile = 1;
backup_info.backup_writefile = 1;
backup_info.rename_log = 0;
backup_info.truncate_log = 0;
hinst = LoadLibrary( "dbtool8.dll" );
if( hinst == NULL ) {
// Echec
return 0;
}

}
Chapitre 8 Interface Outils de base de données
dbtinfo.errorrtn = (MSG_CALLBACK)ErrorCallBack;
dbbackup = GetProcAddress( (HMODULE)hinst,
"_DBBackup@4" );
dbtoolsinit = GetProcAddress( (HMODULE)hinst,
"_DBToolsInit@4" );
dbtoolsfini = GetProcAddress( (HMODULE)hinst,
"_DBToolsFini@4" );
(*dbtoolsinit)( &dbtinfo );
(*dbbackup)( &backup_info );
(*dbtoolsfini)( &dbtinfo );
FreeLibrary( hinst );
return 0;
319

Fonctions DBTools
Fonctions DBTools
Fonction DBBackup
Fonction
Syntaxe
Paramètres
Valeur renvoyée
Utilisation
Voir aussi
320
La présente section décrit les fonctions disponibles dans la bibliothèque
DBTools. Elles sont répertoriées dans l'ordre alphabétique.
Sauvegarde de base de données. Employée par l'utilitaire de ligne de
commande dbbackup.
short DBBackup ( const a_backup_db * bd_sauvegarde );
Paramètre Description
bd_sauvegarde Pointeur sur "Structure a_backup_db", page 332
Un code de retour, tel qu'il apparaît dans la liste "Codes de retour des
composants logiciels", page 313.
La fonction DBBackup gère toutes les tâches de sauvegarde de base de
données.
$ Pour plus d'informations sur ces tâches, reportez-vous à la section
"Utilitaire de sauvegarde d'une base de données", page 470 du document
ASA Guide d’administration.
"Structure a_backup_db", page 332
Fonction DBChangeLogName
Fonction
Syntaxe
Paramètres
Valeur renvoyée
Utilisation
Modifie le nom de fichier du journal de transactions. Employée par l'utilitaire
de ligne de commande dblog.
short DBChangeLogName ( const a_change_log * journal_transactions );
Paramètre Description
journal_transactions Pointeur sur "Structure a_change_log", page 334
Un code de retour, tel qu'il apparaît dans la liste "Codes de retour des
composants logiciels", page 313.
L'option -t de l'utilitaire de ligne de commande dblog permet de changer le
nom du journal de transactions. DBChangeLogName fournit une interface de
programmation pour cette fonction.

Voir aussi
Fonction DBChangeWriteFile
Fonction
Syntaxe
Paramètres
Valeur renvoyée
Utilisation
Voir aussi
Fonction DBCollate
Fonction
Syntaxe
Paramètres
Valeur renvoyée
Utilisation
Chapitre 8 Interface Outils de base de données
$ Pour une description de l’utilitaire dblog, reportez-vous à la section
"Utilitaire de gestion des journaux de transactions", page 550 du document
ASA Guide d’administration.
"Structure a_change_log", page 334
Modifie un fichier d'écriture pour qu'il fasse référence à un autre fichier de
base de données. Cette fonction est employée par l'utilitaire de ligne de
commande dbwrite lorsque l'option -d est appliquée.
short DBChangeWriteFile ( const a_writefile * fichier_écriture );
Paramètre Description
fichier_écriture Pointeur sur "Structure a_writefile", page 361
Un code de retour, tel qu'il apparaît dans la liste "Codes de retour des
composants logiciels", page 313.
$ Pour plus d'informations sur l'utilitaire de création de fichiers d'écriture
et sur ses fonctionnalités, reportez-vous à la section "Utilitaire de création
d'un fichier d'écriture", page 578 du document ASA Guide d’administration.
"Fonction DBCreateWriteFile", page 323
"Fonction DBStatusWriteFile", page 326
"Structure a_writefile", page 361
Extrait un ordre de classement d'une base de données.
short DBCollate ( const a_db_collation * classement_bd );
Paramètre Description
classement_bd Pointeur sur "Structure a_db_collation", page 341
Un code de retour, tel qu'il apparaît dans la liste "Codes de retour des
composants logiciels", page 313.
$ Pour plus d'informations sur l'utilitaire de classement et sur ses
fonctionnalités, reportez-vous à la section "Utilitaire de classement",
page 475 du document ASA Guide d’administration.
321

Fonctions DBTools
Voir aussi
Fonction DBCompress
Fonction
Syntaxe
Paramètres
Valeur renvoyée
Utilisation
Voir aussi
Fonction DBCreate
Fonction
Syntaxe
Paramètres
Valeur renvoyée
Utilisation
Voir aussi
322
"Structure a_db_collation", page 341
Compacte un fichier de base de données. Employée par l'utilitaire de ligne de
commande dbshrink.
short DBCompress ( const a_compress_db * bd_compactée );
Paramètre Description
bd_compactée Pointeur sur "Structure a_compress_db", page 336
Un code de retour, tel qu'il apparaît dans la liste "Codes de retour des
composants logiciels", page 313.
$ Pour plus d'informations sur l'utilitaire de compactage et sur ses
fonctionnalités, reportez-vous à la section "Utilitaire de compactage d'une
base de données", page 481 du document ASA Guide d’administration.
"Structure a_compress_db", page 336
Crée une base de données. Employée par l'utilitaire de ligne de commande
dbinit.
short DBCreate ( const a_create_db * bd_créée );
Paramètre Description
bd_créée Pointeur sur "Structure a_create_db", page 338
Un code de retour, tel qu'il apparaît dans la liste "Codes de retour des
composants logiciels", page 313.
$ Pour plus d'informations sur l'utilitaire de création, reportez-vous à la
section "Utilitaire de création d'une base de données", page 501 du document
ASA Guide d’administration.
"Structure a_create_db", page 338

Fonction DBCreateWriteFile
Fonction
Syntaxe
Paramètres
Valeur renvoyée
Utilisation
Voir aussi
Fonction DBCrypt
Fonction
Syntaxe
Paramètres
Valeur renvoyée
Utilisation
Voir aussi
Fonction DBErase
Fonction
Chapitre 8 Interface Outils de base de données
Crée un fichier d'écriture. Employée par l'utilitaire de ligne de commande
dbwrite lorsque l'option -c est appliquée.
short DBCreateWriteFile ( const a_writefile * fichier_écriture );
Paramètre Description
fichier_écriture Pointeur sur "Structure a_writefile", page 361
Un code de retour, tel qu'il apparaît dans la liste "Codes de retour des
composants logiciels", page 313.
$ Pour plus d'informations sur l'utilitaire de création de fichiers d'écriture
et sur ses fonctionnalités, reportez-vous à la section "Utilitaire de création
d'un fichier d'écriture", page 578 du document ASA Guide d’administration.
"Fonction DBChangeWriteFile", page 321
"Fonction DBStatusWriteFile", page 326
"Structure a_writefile", page 361
Crypte un fichier de base de données. Employée par l'utilitaire de ligne de
commande dbinit lorsque les options -e sont appliquées.
short DBCrypt ( const a_crypt_db * bd_cryptée );
Paramètre Description
bd_cryptée Pointeur sur "Structure a_crypt_db", page 340
Un code de retour, tel qu'il apparaît dans la liste "Codes de retour des
composants logiciels", page 313.
$ Pour plus d'informations sur le cryptage des bases de données, reportezvous
à la section "Création d'une base de données à l'aide de l'utilitaire
dbinit", page 502 du document ASA Guide d’administration
"Structure a_crypt_db", page 340
Supprime un fichier de base de données et/ou un fichier de journal de
transactions. Employée par l'utilitaire de ligne de commande dberase.
323

Fonctions DBTools
Syntaxe
Paramètres
Valeur renvoyée
Utilisation
Voir aussi
Fonction DBExpand
Fonction
Syntaxe
Paramètres
Valeur renvoyée
Utilisation
Voir aussi
Fonction DBInfo
Fonction
Syntaxe
Paramètres
324
short DBErase ( const an_erase_db * bd_supprimée );
Paramètre Description
bd_supprimée Pointeur sur "Structure an_erase_db", page 347
Un code de retour, tel qu'il apparaît dans la liste "Codes de retour des
composants logiciels", page 313.
$ Pour plus d'informations sur l'utilitaire de suppression et sur ses
fonctionnalités, reportez-vous à la section "Utilitaire de suppression d'une
base de données", page 494 du document ASA Guide d’administration.
"Structure an_erase_db", page 347
Décompacte un fichier de base de données. Employée par l'utilitaire de ligne
de commande dbexpand.
short DBExpand ( const an_expand_db * bd_décompactée );
Paramètre Description
bd_décompactée Pointeur sur "Structure an_expand_db", page 348
Un code de retour, tel qu'il apparaît dans la liste "Codes de retour des
composants logiciels", page 313.
$ Pour plus d'informations sur l'utilitaire de décompactage et sur ses
fonctionnalités, reportez-vous à la section "Utilitaire de décompactage d'une
base de données", page 555 du document ASA Guide d’administration.
"Structure an_expand_db", page 348
Renvoie des informations relatives à un fichier de base de données.
Employée par l'utilitaire de ligne de commande dbinfo.
short DBInfo ( const a_db_info * infos_bd );
Paramètre Description
infos_bd Pointeur sur "Structure a_db_info", page 343

Valeur renvoyée
Utilisation
Voir aussi
Fonction DBInfoDump
Fonction
Syntaxe
Paramètres
Valeur renvoyée
Utilisation
Voir aussi
Fonction DBInfoFree
Fonction
Syntaxe
Paramètres
Valeur renvoyée
Chapitre 8 Interface Outils de base de données
Un code de retour, tel qu'il apparaît dans la liste "Codes de retour des
composants logiciels", page 313.
$ Pour plus d'informations sur l'utilitaire d'information et sur ses
fonctionnalités, reportez-vous à la section "Utilitaire Informations", page 499
du document ASA Guide d’administration.
"Fonction DBInfoDump", page 325
"Fonction DBInfoFree", page 325
"Structure a_db_info", page 343
Renvoie des informations relatives à un fichier de base de données.
Employée par l'utilitaire de ligne de commande dbinfo lorsque l'option -u est
utilisée.
short DBInfoDump ( const a_db_info * infos_bd );
Paramètre Description
infos_bd Pointeur sur "Structure a_db_info", page 343
Un code de retour, tel qu'il apparaît dans la liste "Codes de retour des
composants logiciels", page 313.
$ Pour plus d'informations sur l'utilitaire d'information et sur ses
fonctionnalités, reportez-vous à la section "Utilitaire Informations", page 499
du document ASA Guide d’administration.
"Fonction DBInfo", page 324
"Fonction DBInfoFree", page 325
"Structure a_db_info", page 343
Libère les ressources après un appel de la fonction DBInfoDump.
short DBInfoFree ( const a_db_info * infos_bd );
Paramètre Description
infos_bd Pointeur sur "Structure a_db_info", page 343
Un code de retour, tel qu'il apparaît dans la liste "Codes de retour des
composants logiciels", page 313.
325

Fonctions DBTools
Utilisation
Voir aussi
Fonction DBLicense
Fonction
Syntaxe
Paramètres
Valeur renvoyée
Utilisation
Voir aussi
Fonction DBStatusWriteFile
Fonction
Syntaxe
Paramètres
Valeur renvoyée
Utilisation
326
$ Pour plus d’informations sur l’utilitaire d’information et sur ses
fonctionnalités, reportez-vous à la section "Utilitaire Informations", page 499
du document ASA Guide d’administration.
"Fonction DBInfo", page 324
"Fonction DBInfoDump", page 325
"Structure a_db_info", page 343
Appelée pour modifier ou afficher les informations de licence du serveur de
base de données.
short DBLicense ( const a_db_lic_info * infos_lic_bd );
Paramètre Description
infos_lic_bd Pointeur sur "Structure a_dblic_info", page 346
Un code de retour, tel qu'il apparaît dans la liste "Codes de retour des
composants logiciels", page 313.
$ Pour plus d'informations sur l'utilitaire d'information et sur ses
fonctionnalités, reportez-vous à la section "Utilitaire Informations", page 499
du document ASA Guide d’administration.
"Structure a_dblic_info", page 346
Lit l'état d'un fichier d'écriture. Employée par l'utilitaire de ligne de
commande dbwrite lorsque l'option -s est utilisée.
short DBStatusWriteFile ( const a_writefile * fichier_écriture );
Paramètre Description
fichier_écriture Pointeur sur "Structure a_writefile", page 361
Un code de retour, tel qu'il apparaît dans la liste "Codes de retour des
composants logiciels", page 313.
$ Pour plus d'informations sur l'utilitaire de création de fichiers d'écriture
et sur ses fonctionnalités, reportez-vous à la section "Utilitaire de création
d'un fichier d'écriture", page 578 du document ASA Guide d’administration.

Voir aussi
Fonction DBSynchronizeLog
Fonction
Syntaxe
Paramètres
Valeur renvoyée
Utilisation
Fonction DBToolsFini
Fonction
Syntaxe
Paramètres
Valeur renvoyée
Utilisation
Voir aussi
"Fonction DBChangeWriteFile", page 321
"Fonction DBCreateWriteFile", page 323
"Structure a_writefile", page 361
Chapitre 8 Interface Outils de base de données
Synchronise une base de données avec un serveur de synchronisation
MobiLink.
short DBSynchronizeLog( const a _sync_db * bd_sync );
Paramètre Description
bd_sync Pointeur sur "Structure a_sync_db", page 350
Un code de retour, tel qu'il apparaît dans la liste "Codes de retour des
composants logiciels", page 313.
$ Pour plus d'informations sur les fonctionnalités accessibles, reportezvous
à la section "Lancement de la synchronisation", page 150 du document
Synchronisation MobiLink Guide de l’utilisateur.
Décrémente le compteur et libère les ressources lorsqu'une application a
terminé d'utiliser la bibliothèque DBTools.
short DBToolsFini ( const a_dbtools_info * infos_dbtools );
Paramètre Description
infos_dbtools Pointeur sur "Structure a_dbtools_info", page 347
Un code de retour, tel qu'il apparaît dans la liste "Codes de retour des
composants logiciels", page 313.
La fonction DBToolsFini doit être appelée à la fin de toute application
utilisant l'interface DBTools. Dans le cas contraire, vous risquez de perdre
des ressources mémoire.
"Fonction DBToolsInit", page 328
"Structure a_dbtools_info", page 347
327

Fonctions DBTools
Fonction DBToolsInit
Fonction
Syntaxe
Paramètres
Valeur renvoyée
Utilisation
Exemple
Voir aussi
Fonction DBToolsVersion
Fonction
Syntaxe
328
Prépare l'utilisation de la bibliothèque DBTools.
short DBToolsInit t( const a_dbtools_info * infos_dbtools );
Paramètre Description
infos_dbtools Pointeur sur "Structure a_dbtools_info", page 347
Un code de retour, tel qu'il apparaît dans la liste "Codes de retour des
composants logiciels", page 313.
Le principal objet de la fonction DBToolsInit est de charger la DLL de
langue d'Adaptive Server Anywhere. Cette dernière contient la version
localisée des messages d'erreur et de toutes les invites utilisées en interne par
DBTools.
La fonction DBToolsInit doit être appelée au début de chaque application
utilisant l'interface DBTools, avant toute autre fonction DBTools.
♦ L'exemple de code suivant montre comment initialiser et vider
DBTools :
a_dbtools_info info;
short ret;
memset( &info, 0, sizeof( a_dbtools_info) );
info.errorrtn = (MSG_CALLBACK)MakeProcInstance(
(FARPROC)MyErrorRtn, hInst );
// Initialisation de DBTools
ret = DBToolsInit( &info );
if( ret != EXIT_OKAY ) {
// Echec d’initialisation de la DLL
…
}
// Appel de diverses routines DBTools . . .
…
// Réinitialisation de la DLL DBTools
DBToolsFini( &info );
"Fonction DBToolsFini", page 327
"Structure a_dbtools_info", page 347
Renvoie le numéro de version de la bibliothèque DBTools.
short DBToolsVersion ( void );

Valeur renvoyée
Utilisation
Voir aussi
Fonction DBTranslateLog
Fonction
Syntaxe
Paramètres
Valeur renvoyée
Utilisation
Voir aussi
Fonction DBTruncateLog
Fonction
Syntaxe
Paramètres
Valeur renvoyée
Utilisation
Chapitre 8 Interface Outils de base de données
Un entier court indiquant le numéro de version de la bibliothèque DBTools.
Employez la fonction DBToolsVersion pour vérifier que la bibliothèque
DBTools n'est pas plus ancienne que celle avec laquelle l'application a été
développée. Les applications ne peuvent s'exécuter qu'avec des versions de
DBTools identiques ou plus récentes.
"Numéros de version et compatibilité", page 315
Convertit un fichier de journal de transactions en SQL. Employée par
l'utilitaire de ligne de commande dbtran.
short DBTranslateLog ( const a_translate_log * journal_transactions );
Paramètre Description
journal_transactions Pointeur sur "Structure a_translate_log", page 354
Un code de retour, tel qu'il apparaît dans la liste "Codes de retour des
composants logiciels", page 313.
$ Pour plus d'informations sur l'utilitaire de conversion, reportez-vous à la
section "Utilitaire de conversion du journal de transactions", page 529 du
document ASA Guide d’administration.
"Structure a_translate_log", page 354
Tronque le journal de transactions. Employée par l'utilitaire de ligne de
commande dbbackup.
short DBTruncateLog ( const a_truncate_log * journal_tronqué );
Paramètre Description
journal_tronqué Pointeur sur "Structure a_truncate_log", page 356
Un code de retour, tel qu'il apparaît dans la liste "Codes de retour des
composants logiciels", page 313.
$ Pour plus d'informations sur l'utilitaire de sauvegarde, reportez-vous à
la section "Utilitaire de sauvegarde d'une base de données", page 470 du
document ASA Guide d’administration.
329

Fonctions DBTools
Voir aussi
Fonction DBUnload
Fonction
Syntaxe
Paramètres
Valeur renvoyée
Utilisation
Voir aussi
Fonction DBUpgrade
Fonction
Syntaxe
Paramètres
Valeur renvoyée
Utilisation
Voir aussi
330
"Structure a_truncate_log", page 356
Décharge une base de données. Employée par l'utilitaire de ligne de
commande dbunload, ainsi que par l'utilitaire dbxtract pour SQL Remote.
short DBUnload ( const an_unload_db * bd_déchargée );
Paramètre Description
bd_déchargée Pointeur sur "Structure an_unload_db", page 357
Un code de retour, tel qu'il apparaît dans la liste "Codes de retour des
composants logiciels", page 313.
$ Pour plus d'informations sur l'utilitaire de déchargement, reportez-vous
à la section "Utilitaire de déchargement d'une base de données", page 558 du
document ASA Guide d’administration.
"Structure an_unload_db", page 357
Met à niveau un fichier de base de données. Employée par l'utilitaire de ligne
de commande dbupgrade.
short DBUpgrade ( const an_upgrade_db * bd_mise_à_niveau );
Paramètre Description
bd_mise_à_niveau Pointeur sur "Structure an_upgrade_db", page 359
Un code de retour, tel qu'il apparaît dans la liste "Codes de retour des
composants logiciels", page 313.
$ Pour plus d'informations sur l'utilitaire de mise à niveau, reportez-vous
à la section "Utilitaire de mise à niveau d'une base de données", page 568 du
document ASA Guide d’administration.
"Structure an_upgrade_db", page 359

Fonction DBValidate
Fonction
Syntaxe
Paramètres
Valeur renvoyée
Utilisation
Voir aussi
Chapitre 8 Interface Outils de base de données
Valide une base de données entièrement ou partiellement. Employée par
l'utilitaire de ligne de commande dbvalid.
short DBValidate ( const a_validate_db * bd_validée );
Paramètre Description
bd_validée Pointeur sur "Structure a_validate_db", page 360
Un code de retour, tel qu'il apparaît dans la liste "Codes de retour des
composants logiciels", page 313.
$ Pour plus d'informations sur l'utilitaire de validation, reportez-vous à la
section "Utilitaire de validation d'une base de données", page 574 du
document ASA Guide d’administration.
"Structure a_validate_db", page 360
331

Structures DBTools
Structures DBTools
Structure a_backup_db
Fonction
Syntaxe
332
Cette section répertorie les structures utilisées pour échanger des
informations avec la bibliothèque DBTools. Les structures sont répertoriées
dans l'ordre alphabétique.
De nombreux éléments de structure correspondent à des options de ligne de
commande de l'utilitaire équivalent. Par exemple, plusieurs structures
comprennent un élément appelé "quiet", qui accepte les valeurs 0 ou 1. Cet
élément correspond à l'option de ligne de commande opération non
détaillée (-q), utilisée par un grand nombre d'utilitaires.
Contient les informations requises pour exécuter des tâches de sauvegarde à
l'aide de la bibliothèque DBTools.
typedef struct a_backup_db {
unsigned short version;
const char * output_dir;
const char * connectparms;
const char * startline;
MSG_CALLBACK confirmrtn;
MSG_CALLBACK errorrtn;
MSG_CALLBACK msgrtn;
MSG_CALLBACK statusrtn;
a_bit_field backup_database: 1;
a_bit_field backup_logfile : 1;
a_bit_field backup_writefile : 1;
a_bit_field no_confirm : 1;
a_bit_field quiet : 1;
a_bit_field rename_log : 1;
a_bit_field truncate_log : 1;
a_bit_field rename_local_log: 1;
const char * hotlog_filename;
char backup_interrupted;
} a_backup_db;

Paramètres
Voir aussi
Elément Description
Chapitre 8 Interface Outils de base de données
Version Numéro de version de DBTools.
output_dir Chemin d'accès du répertoire de sauvegarde. Par exemple :
"c:\backup"
connectparms Paramètres requis pour la connexion à la base de données.
Ils se présentent sous la forme de chaînes de connexion.
Exemple :
"UID=DBA;PWD=SQL;DBF=c:\asa\asademo.db"
$ Pour obtenir l'ensemble des options de chaîne de
connexion, reportez-vous à la section "Paramètres de
connexion", page 75 du document ASA Guide
d’administration.
startline Ligne de commande utilisée pour démarrer le moteur de
bases de données. Exemple :
"c:\asa\win32\dbeng8.exe"
Si cet élément est NULL, la ligne de démarrage par défaut
est utilisée.
confirmrtn Routine callback de confirmation d'une action.
errorrtn Routine callback de gestion d'un message d'erreur.
msgrtn Routine callback de gestion d'un message d'information.
statusrtn Routine callback de gestion d'un message d'état.
backup_database Sauvegarde (1) ou non (0) du fichier de base de données.
backup_logfile Sauvegarde (1) ou non (0) du journal de transactions.
backup_writefile Sauvegarde (1) ou non (0) du fichier d'écriture de la base
de données, s'il existe.
no_confirm Exécution avec (0) ou sans (1) confirmation.
quiet Fonctionnement avec (0) ou sans (1) impression de
messages.
rename_log Changement de nom du journal de transactions.
truncate_log Suppression du journal de transactions.
rename_local_log Changement de nom de la sauvegarde locale du journal de
transactions.
hotlog_filename Nom du fichier de sauvegarde à la volée.
backup_interrupted Indique que l'opération a été interrompue.
"Fonction DBBackup", page 320
333

Structures DBTools
Structure a_change_log
Fonction
Syntaxe
Paramètres
334
$ Pour plus d'informations sur les fonctions callback, reportez-vous à
"Utilisation des fonctions callback", page 313.
Contient les informations requises pour exécuter des tâches dblog à l'aide de
la bibliothèque DBTools.
typedef struct a_change_log {
unsigned short version;
const char * dbname;
const char * logname;
MSG_CALLBACK errorrtn;
MSG_CALLBACK msgrtn;
a_bit_field query_only : 1;
a_bit_field quiet : 1;
a_bit_field mirrorname_present : 1;
a_bit_field change_mirrorname : 1;
a_bit_field change_logname : 1;
a_bit_field ignore_ltm_trunc : 1;
a_bit_field ignore_remote_trunc : 1;
a_bit_field set_generation_number : 1;
a_bit_field ignore_dbsync_trunc : 1;
const char * mirrorname;
unsigned short generation_number;
const char * key_file;
char * zap_current_offset;
char * sap_starting_offset;
char * encryption_key;
} a_change_log;
Elément Description
version Numéro de version de DBTools.
dbname Nom du fichier de base de données.
logname Nom du journal de transactions. Si cet élément est
NULL, aucun journal n'est généré.
errorrtn Routine callback de gestion d'un message d'erreur.
msgrtn Routine callback de gestion d'un message
d'information.
query_only Si 1, affiche simplement le nom du journal de
transactions. Si 0, permet de changer le nom du
journal.
quiet Fonctionnement avec (0) ou sans (1) impression de
messages.

Elément Description
Chapitre 8 Interface Outils de base de données
mirrorname_present Si 1, indique que la version de DBTools est
suffisamment récente pour prendre en charge le champ
mirrorname.
change_mirrorname Si 1, permet de changer le nom du fichier miroir du
journal.
change_logname Si 1, permet de changer le nom du journal de
transactions.
ignore_ltm_trunc Lors de l'utilisation du gestionnaire de transfert de
journal (LTM), cet élément joue le même rôle que la
fonction dbcc settrunc( 'ltm', 'gen_id', n ) de
Replication Server.
$ Pour obtenir des informations sur dbcc, consultez
la documentation de Replication Server.
ignore_remote_trunc S'applique à SQL Remote. Remet à zéro l'offset
conservé pour les besoins de l'option
DELETE_OLD_LOGS, permettant ainsi la
suppression des journaux de transactions lorsqu'ils ne
sont plus nécessaires.
set_generation_number Lors de l'utilisation du LTM, cet élément est employé
pour définir le numéro de génération après chargement
d'une version de sauvegarde.
ignore_dbsync_trunc Lors de l'utilisation de dbmlsync, remet à zéro l'offset
conservé pour les besoins de l'option
DELETE_OLD_LOGS, permettant ainsi la
suppression des journaux de transactions lorsqu'ils ne
sont plus nécessaires.
mirrorname Nouveau nom du fichier miroir du journal de
transactions.
335

Structures DBTools
Voir aussi
Structure a_compress_db
Fonction
Syntaxe
336
Elément Description
generation_number Nouveau numéro de génération. Utilisé conjointement
à set_generation_number.
key_file Fichier contenant la clé de cryptage.
zap_current_offset Modifie l'offset courant en lui attribuant la valeur
spécifiée. Utilisé uniquement pour réinitialiser un
journal de transactions après un déchargement et un
rechargement afin qu'il corresponde aux paramètres de
dbremote ou dbmlsync.
zap_starting_offset Modifie l'offset de départ en lui attribuant la valeur
spécifiée. Utilisé uniquement pour réinitialiser un
journal de transactions après un déchargement et un
rechargement afin qu'il corresponde aux paramètres de
dbremote ou dbmlsync.
encryption_key Clé de cryptage du fichier de base de données.
"Fonction DBChangeLogName", page 320
$ Pour plus d'informations sur les fonctions callback, reportez-vous à
"Utilisation des fonctions callback", page 313.
Contient les informations requises pour exécuter des tâches de compactage à
l'aide de la bibliothèque DBTools.
typedef struct a_compress_db {
unsigned short version;
const char * dbname;
const char * compress_name;
MSG_CALLBACK errorrtn;
MSG_CALLBACK msgrtn;
MSG_CALLBACK statusrtn;
a_bit_field display_free_pages : 1;
a_bit_field quiet : 1;
a_bit_field record_unchanged : 1;
a_compress_stats * stats;
MSG_CALLBACK confirmrtn;
a_bit_field noconfirm : 1;
const char * encryption_key
} a_compress_db;

Paramètres
Voir aussi
Structure a_compress_stats
Fonction
Syntaxe
Elément Description
Chapitre 8 Interface Outils de base de données
version Numéro de version de DBTools.
dbname Nom du fichier de la base de données à compacter.
compress_name Nom du fichier de la base de données compacté.
errorrtn Routine callback de gestion d'un message d'erreur.
msgrtn Routine callback de gestion d'un message d'information.
statusrtn Routine callback de gestion d'un message d'état.
display_free_pages Affichage des informations sur les pages disponibles.
quiet Fonctionnement avec (0) ou sans (1) impression de
messages.
record_unchanged Si 1, indique que la structure a_compress_stats est
suffisamment récente pour comporter un élément
unchanged.
a_compress_stats Pointeur sur une structure de type a_compress_stats. Cet
élément est renseigné s'il n'est pas NULL et si
display_free_pages est différent de zéro.
confirmrtn Routine callback de confirmation d'une action.
noconfirm Exécution avec (0) ou sans (1) confirmation.
encryption_key Clé de cryptage du fichier de base de données.
"Fonction DBCompress", page 322
"Structure a_compress_stats", page 337
$ Pour plus d'informations sur les fonctions callback, reportez-vous à
"Utilisation des fonctions callback", page 313.
Contient la description des statistiques relatives au fichier de base de données
compacté.
typedef struct a_compress_stats {
a_stats_line tables;
a_stats_line indices;
a_stats_line other;
a_stats_line free;
a_stats_line total;
a_sql_int32 free_pages;
a_sql_int32 unchanged;
} a_compress_stats;
337

Structures DBTools
Paramètres
Voir aussi
Structure a_create_db
Fonction
338
Elément Description
tables Contient les informations de compactage relatives aux tables.
indices Contient les informations de compactage relatives aux index.
other Contient d’autres informations relatives au compactage.
free Contient les informations relatives à l'espace libre.
total Contient les informations globales relatives au compactage.
free_pages Contient les informations relatives aux pages libres.
unchanged Nombre de pages que l'algorithme de compactage n'est pas
parvenu à réduire.
"Fonction DBCompress", page 322
"Structure a_compress_db", page 336
Contient les informations requises pour créer une base de données à l'aide de
la bibliothèque DBTools.

Syntaxe
Paramètres
Chapitre 8 Interface Outils de base de données
typedef struct a_create_db {
unsigned short version;
const char * dbname;
const char * logname;
const char * startline;
short page_size;
const char * default_collation;
MSG_CALLBACK errorrtn;
MSG_CALLBACK msgrtn;
short database_version;
char verbose;
a_bit_field blank_pad : 2;
a_bit_field respect_case : 1;
a_bit_field encrypt : 1;
a_bit_field debug : 1;
a_bit_field dbo_avail : 1;
a_bit_field mirrorname_present : 1;
a_bit_field avoid_view_collisions : 1;
short collation_id;
const char * dbo_username;
const char * mirrorname;
const char * encryption_dllname;
a_bit_field java_classes : 1;
a_bit_field jconnect : 1;
const char * data_store_type
const char * encryption_key;
const char * encryption_algorithm;
const char * jdK_version;
} a_create_db;
Elément Description
version Numéro de version de DBTools.
dbname Nom du fichier de base de données.
logname Nouveau nom du journal de transactions.
startline Ligne de commande utilisée pour démarrer le moteur de
bases de données. Exemple :
"c:\asa\win32\dbeng8.exe"
Si cet élément est NULL, la ligne de démarrage par
défaut est utilisée.
page_size Taille des pages de la base de données.
default_collation Ordre de classement de la base de données.
errorrtn Routine callback de gestion d'un message d'erreur.
msgrtn Routine callback de gestion d'un message d'information.
database_version Numéro de version de la base de données.
339

Structures DBTools
Voir aussi
Structure a_crypt_db
Fonction
340
Elément Description
verbose Exécution en mode détaillé.
blank_pad Les blancs sont considérés comme significatifs dans les
comparaisons de chaînes et les index sont générés en
conséquence.
respect_case Les comparaisons de chaînes font la distinction
majuscules/minuscules et les index sont générés en
conséquence.
encrypt Crypte la base de données.
debug Réservée.
dbo_avail Si 1, l'utilisateur dbo est disponible dans cette base de
données.
mirrorname_present Si 1, indique que la version de DBTools est
suffisamment récente pour prendre en charge le champ
mirrorname.
avoid_view_collisions Ne génère pas les vues SYS.SYSCOLUMNS et
SYS.SYSINDEXES assurant la compatibilité avec
Watcom SQL.
collation_id Identificateur de l'ordre de classement.
dbo_username N'est plus utilisé : défini avec la valeur NULL.
mirrorname Nom du fichier miroir du journal de transactions.
encryption_dllname DLL utilisée pour crypter la base de données
java_classes Crée une base de données configurée pour Java.
jconnect Inclut les procédures système requises pour jConnect
data_store_type Réservé. Défini avec la valeur NULL.
encryption_key Clé de cryptage du fichier de base de données.
encryption_algorithm Soit AES, soit MDSR.
jdk_version Une des valeurs de l'option –jdk de dbinit.
"Fonction DBCreate", page 322
$ Pour plus d'informations sur les fonctions callback, reportez-vous à
"Utilisation des fonctions callback", page 313.
Contient les informations nécessaires pour crypter un fichier de base de
données utilisées par l'utilitaire de ligne de commande dbinit.

Syntaxe
Paramètres
Voir aussi
Structure a_db_collation
Fonction
typedef struct a_crypt_db {
const char _fd_ * dbname;
const char _fd_ * dllname;
MSG_CALLBACK errorrtn;
MSG_CALLBACK msgrtn;
MSG_CALLBACK statusrtn;
char verbose;
a_bit_field quiet : 1;
a_bit_field debug : 1;
} a_crypt_db;
Chapitre 8 Interface Outils de base de données
Elément Description
dbname Nom du fichier de base de données.
dllname Nom de la DLL utilisée pour effectuer le cryptage.
errorrtn Routine callback de gestion d'un message d'erreur.
msgrtn Routine callback de gestion d'un message d'information.
statusrtn Routine callback de gestion d'un message d'état.
verbose Fonctionnement en mode détaillé.
quiet Fonctionnement sans messages.
debug Réservée.
"Fonction DBCrypt", page 323
"Création d'une base de données à l'aide de l'utilitaire dbinit", page 502 du
document ASA Guide d’administration
Contient les informations requises pour extraire un ordre de classement d'une
base de données à l'aide de la bibliothèque DBTools.
341

Structures DBTools
Syntaxe
Paramètres
342
typedef struct a_db_collation {
unsigned short version;
const char * connectparms;
const char * startline;
const char * collation_label;
const char * filename;
MSG_CALLBACK confirmrtn;
MSG_CALLBACK errorrtn;
MSG_CALLBACK msgrtn;
a_bit_field include_empty : 1;
a_bit_field hex_for_extended : 1;
a_bit_field replace : 1;
a_bit_field quiet : 1;
const char * input_filename;
const char _fd_ * mapping_filename;
} a_db_collation;
Elément Description
version Numéro de version de DBTools.
connectparms Paramètres requis pour la connexion à la base de données.
Ils se présentent sous la forme de chaînes de connexion.
Exemple :
"UID=DBA;PWD=SQL;DBF=c:\asa\asademo.db"
$ Pour obtenir l'ensemble des options de chaîne de
connexion, reportez-vous à la section "Paramètres de
connexion", page 75 du document ASA Guide
d’administration
startline Ligne de commande utilisée pour démarrer le moteur de
bases de données. Exemple :
"c:\asa\win32\dbeng8.exe"
Si cet élément est NULL, la ligne de démarrage par défaut
est utilisée.
confirmrtn Routine callback de confirmation d'une action.
errorrtn Routine callback de gestion d'un message d'erreur.
msgrtn Routine callback de gestion d'un message d'information.
include_empty Ecriture de mappages de blancs pour des discontinuités
dans l'ordre de classement.

Voir aussi
Structure a_db_info
Fonction
Elément Description
Chapitre 8 Interface Outils de base de données
hex_for_extended Utilisation de nombres hexadécimaux sur deux chiffres
pour représenter les caractères ASCII étendus.
replace Fonctionnement sans confirmation des actions.
quiet Fonctionnement sans messages.
input_filename Entrée de la définition du classement
mapping_filename Sortie syscollationmapping.
"Fonction DBCollate", page 321
$ Pour plus d'informations sur les fonctions callback, reportez-vous à
"Utilisation des fonctions callback", page 313.
Contient les informations requises pour renvoyer des données dbinfo à l'aide
de la bibliothèque DBTools.
343

Structures DBTools
Syntaxe
Paramètres
344
typedef struct a_db_info {
unsigned short version;
MSG_CALLBACK errorrtn;
const char * dbname;
unsigned short dbbufsize;
char * dbnamebuffer;
unsigned short logbufsize;
char * lognamebuffer;
unsigned short wrtbufsize;
char * wrtnamebuffer;
a_bit_field quiet : 1;
a_bit_field mirrorname_present : 1;
a_sysinfo sysinfo;
unsigned long free_pages;
a_bit_field compressed : 1;
const char * connectparms;
const char * startline;
MSG_CALLBACK msgrtn;
MSG_CALLBACK statusrtn;
a_bit_field page_usage : 1;
a_table_info * totals;
unsigned long file_size;
unsigned long unused_pages;
unsigned long other_pages;
unsigned short mirrorbufsize;
char * mirrornamebuffer;
char * unused_field;
char * collationnamebuffer;
unsigned short collationnamebufsize;
char * classesversionbuffer;
unsigned short classesversionbufsize;
} a_db_info;
Elément Description
version Numéro de version de DBTools.
errortrn Routine callback de gestion d'un message d'erreur.
dbname Nom du fichier de base de données.
dbbufsize Longueur de l'élément dbnamebuffer.
dbnamebuffer Nom du fichier de base de données.
logbufsize Longueur de l'élément lognamebuffer.
lognamebuffer Nom du fichier de journal de transactions.
wrtbufsize Longueur de l'élément wrtnamebuffer.
wrtnamebuffer Nom du fichier d'écriture.
quiet Fonctionnement sans messages de confirmation.

Elément Description
Chapitre 8 Interface Outils de base de données
mirrorname_present Si 1, indique que la version de DBTools est suffisamment
récente pour prendre en charge le champ mirrorname.
sysinfo Pointeur sur la structure a_sysinfo.
free_pages Nombre de pages disponibles.
compressed 1 si compacté ; 0 dans le cas contraire.
connectparms Paramètres requis pour la connexion à la base de données.
Ils se présentent sous la forme de chaînes de connexion.
Exemple :
"UID=DBA;PWD=SQL;DBF=c:\Program
Files\Sybase\SQL Anywhere 8\asademo.db"
$ Pour obtenir l'ensemble des options de chaîne de
connexion, reportez-vous à la section "Paramètres de
connexion", page 75 du document ASA Guide
d’administration.
startline Ligne de commande utilisée pour démarrer le moteur de
bases de données. Exemple :
"c:\asa\win32\dbeng8.exe"
Si cet élément est NULL, la ligne de démarrage par
défaut est utilisée.
msgrtn Routine callback de gestion d'un message d'information.
statusrtn Routine callback de gestion d'un message d'état.
page_usage Si 1, affiche les statistiques d'utilisation des pages. Dans
le cas contraire, 0.
totals Pointeur sur la structure a_table_info.
file_size Taille du fichier de base de données.
unused_pages Nombre de pages non utilisées.
other_pages Nombre de pages ne correspondant ni à des tables ni à des
index.
mirrorbufsize Longueur de l'élément mirrornamebuffer.
345

Structures DBTools
Voir aussi
Structure a_dblic_info
Fonction
Syntaxe
Paramètres
346
Elément Description
mirrornamebuffer Nom du fichier miroir du journal de transactions.
collationnamebuffer Nom et libellé de classement de la base de données (taille
maximale 128+1).
collationnamebufsize Longueur de l'élément collationnamebuffer.
classesversionbuffer Version JDK des classes Java installées, comme 1.1.3,
1.1.8, 1.3, ou une chaîne vide si les classes Java ne sont
pas installées dans la base de données (la taille maximale
étant 10+1).
classesversionbufsize Longueur de l'élément classesversionbuffer
"Fonction DBInfo", page 324
$ Pour plus d'informations sur les fonctions callback, reportez-vous à
"Utilisation des fonctions callback", page 313.
Contient les informations de licence. Vous devez utiliser ces informations
conformément à votre contrat de licence.
typedef struct a_dblic_info {
unsigned short version;
char * exename;
char * username;
char * compname;
char * platform_str;
a_sql_int32 nodecount;
a_sql_int32 conncount;
a_license_type type;
MSG_CALLBACK errorrtn;
MSG_CALLBACK msgrtn;
a_bit_field quiet : 1;
a_bit_field query_only : 1;
} a_dblic_info;
Elément Description
version Numéro de version de DBTools.
exename Nom du fichier exécutable.
username Nom d'utilisateur pour la licence.
compname Nom de la société pour la licence.
platform_str Système d'exploitation : WinNT, NLM ou UNIX.
nodecount Nombre de noeuds sous licence.

Structure a_dbtools_info
Fonction
Syntaxe
Paramètres
Voir aussi
Structure an_erase_db
Fonction
Syntaxe
Elément Description
conncount Doit être 1000000L.
Chapitre 8 Interface Outils de base de données
type Voir le fichier lictype.h pour connaître les valeurs.
errorrtn Routine callback de gestion d'un message d'erreur.
msgrtn Routine callback de gestion d'un message d'information.
quiet Fonctionnement avec (0) ou sans (1) impression de messages.
query_only Si 1, affiche uniquement les informations de licence. Si 0, permet
de modifier les informations.
Contient les informations requises pour initialiser et réinitialiser la
bibliothèque DBTools.
typedef struct a_dbtools_info {
MSG_CALLBACK errorrtn;
} a_dbtools_info;
Elément Description
errorrtn Routine callback de gestion d’un message d’erreur.
"Fonction DBToolsFini", page 327
"Fonction DBToolsInit", page 328
$ Pour plus d'informations sur les fonctions callback, reportez-vous à
"Utilisation des fonctions callback", page 313.
Contient les informations requises pour supprimer une base de données à
l'aide de la bibliothèque DBTools.
typedef struct an_erase_db {
unsigned short version;
const char * dbname;
MSG_CALLBACK confirmrtn;
MSG_CALLBACK errorrtn;
MSG_CALLBACK msgrtn;
a_bit_field quiet : 1;
a_bit_field erase : 1;
const char * encryption_key;
} an_erase_db;
347

Structures DBTools
Paramètres
Voir aussi
Structure an_expand_db
Fonction
Syntaxe
Paramètres
348
Elément Description
version Numéro de version de DBTools.
dbname Nom du fichier de base de données à supprimer.
confirmrtn Routine callback de confirmation d'une action.
errorrtn Routine callback de gestion d'un message d'erreur.
msgrtn Routine callback de gestion d'un message d'information.
quiet Fonctionnement avec (0) ou sans (1) impression de messages.
erase Suppression avec (0) ou sans (1) confirmation.
encryption_key Clé de cryptage du fichier de base de données.
"Fonction DBErase", page 323
$ Pour plus d'informations sur les fonctions callback, reportez-vous à
"Utilisation des fonctions callback", page 313.
Contient les informations requises pour décompacter la base de données à
l'aide de la bibliothèque DBTools.
typedef struct an_expand_db {
unsigned short version;
const char * compress_name;
const char * dbname;
MSG_CALLBACK errorrtn;
MSG_CALLBACK msgrtn;
MSG_CALLBACK statusrtn;
a_bit_field quiet : 1;
MSG_CALLBACK confirmrtn;
a_bit_field noconfirm : 1;
const char * key_file;
const char * encryption_key;
} an_expand_db;
Elément Description
version Numéro de version de DBTools.
compress_name Nom du fichier de base de données compacté.
dbname Nom du fichier de base de données.
errorrtn Routine callback de gestion d'un message d'erreur.
msgrtn Routine callback de gestion d'un message d'information.

Voir aussi
Structure a_name
Fonction
Syntaxe
Paramètres
Voir aussi
Structure a_stats_line
Fonction
Elément Description
Chapitre 8 Interface Outils de base de données
statusrtn Routine callback de gestion d'un message d'état.
quiet Fonctionnement avec (0) ou sans (1) impression de messages.
confirmrtn Routine callback de confirmation d'une action.
noconfirm Exécution avec (0) ou sans (1) confirmation.
key_file Fichier contenant la clé de cryptage.
encryption_key Clé de cryptage du fichier de base de données.
"Fonction DBExpand", page 324
$ Pour plus d'informations sur les fonctions callback, reportez-vous à
"Utilisation des fonctions callback", page 313.
Contient une liste chaînée de noms. Employée par d'autres structures
nécessitant des listes de noms.
typedef struct a_name {
struct a_name * next;
char name[1];
} a_name, * p_name;
Elément Description
next Pointeur sur la structure a_name suivante dans la liste.
name Nom.
p_name Pointeur sur la structure a_name précédente
"Structure a_translate_log", page 354
"Structure a_validate_db", page 360
"Structure an_unload_db", page 357
Contient les informations requises pour compacter et décompacter une base
de données à l'aide de la bibliothèque DBTools.
349

Structures DBTools
Syntaxe
Paramètres
Voir aussi
Structure a_sync_db
Fonction
Syntaxe
350
typedef struct a_stats_line {
long pages;
long bytes;
long compressed_bytes;
} a_stats_line;
Elément Description
pages Nombre de pages.
bytes Nombre d'octets réservés pour la base de données
décompactée.
compressed_bytes Nombre d'octets réservés pour la base de données
compactée.
"Structure a_compress_stats", page 337
Contient les informations nécessaires à l'utilitaire dbmlsync qui utilise la
bibliothèque DBTools.
typedef struct a_sync_db {
unsigned short version;
char _fd_ * connectparms;
char _fd_ * publication;
const char _fd_ * offline_dir;
char _fd_ * extended_options;
char _fd_ * script_full_path;
const char _fd_ * include_scan_range;
const char _fd_ * raw_file;
MSG_CALLBACK confirmrtn;
MSG_CALLBACK errorrtn;
MSG_CALLBACK msgrtn;
MSG_CALLBACK logrtn;
a_SQL_uint32 debug_dump_size;
a_SQL_uint32 dl_insert_width;
a_bit_field verbose : 1;
a_bit_field debug : 1;
a_bit_field debug_dump_hex : 1;
a_bit_field debug_dump_char : 1;
a_bit_field debug_page_offsets : 1;
a_bit_field use_hex_offsets : 1;
a_bit_field use_relative_offsets : 1;
a_bit_field output_to_file : 1;
a_bit_field output_to_mobile_link : 1;
a_bit_field dl_use_put : 1;
a_bit_field dl_use_upsert : 1;

Paramètres
Chapitre 8 Interface Outils de base de données
a_bit_field kill_other_connections : 1;
a_bit_field retry_remote_behind : 1;
a_bit_field ignore_debug_interrupt : 1;
SET_WINDOW_TITLE_CALLBACK set_window_title_rtn;
char * default_window_title;
MSG_QUEUE_CALLBACK msgqueuertn;
MSG_CALLBACK progress_msg_rtn;
SET_PROGRESS_CALLBACK progress_index_rtn;
char ** argv;
char ** ce_argv;
a_bit_field connectparms_allocated : 1;
a_bit_field entered_dialog : 1;
a_bit_field used_dialog_allocation : 1;
a_bit_field ignore_scheduling : 1;
a_bit_field ignore_hook_errors : 1;
a_bit_field changing_pwd : 1;
a_bit_field prompt_again : 1;
a_bit_field retry_remote_ahead : 1;
a_bit_field rename_log : 1;
a_bit_field hide_conn_str : 1;
a_bit_field hide_ml_pwd : 1;
a_bit_field delay_ml_disconn : 1;
a_SQL_uint32 dlg_launch_focus;
char _fd_ * mlpassword;
char _fd_ * new_mlpassword;
char _fd_ * verify_mlpassword;
a_SQL_uint32 pub_name_cnt;
char ** pub_name_list;
USAGE_CALLBACK usage_rtn;
a_sql_uint32 hovering_frequency;
a_bit_short ignore_hovering : 1;
a_bit_short verbose_upload : 1;
a_bit_short verbose_upload_data : 1;
a_bit_short verbose_download : 1;
a_bit_short verbose_download_data : 1;
a_bit_short autoclose : 1;
a_bit_short ping : 1;
a_bit_short _unused : 9;
char _fd_ * encryption_key;
a_syncpub _fd_ * upload_defs;
char _fd_ * log_file_name;
char _fd_ * user_name;
} a_sync_db;
Les paramètres correspondent aux fonctionnalités accessibles depuis
l'utilitaire de ligne de commande dbmlsync.
Pour des commentaires supplémentaires, reportez-vous au fichier d'en-tête
dbtools.h.
351

Structures DBTools
Voir aussi
Structure a_syncpub
Fonction
Syntaxe
Paramètres
Structure a_sysinfo
Fonction
352
$ Pour plus d'informations, reportez-vous à la section "Client de
synchronisation MobiLink", page 436 du document Synchronisation
MobiLink Guide de l’utilisateur.
"Fonction DBSynchronizeLog", page 327
Contient les informations nécessaires à l'utilitaire dbmlsync.
typedef struct a_syncpub {
struct a_syncpub _fd_ * next;
char _fd_ * pub_name;
char _fd_ * ext_opt;
a_bit_field alloced_by_dbsync: 1;
} a_syncpub;
Elément Description
a_syncpub Pointeur sur le noeud suivant dans la liste, NULL pour
le dernier noeud
pub_name Nom(s) de publication spécifié(s) pour l'option -n. Il
s'agit de la chaîne exacte suivant -n sur la ligne de
commande.
ext_opt Options étendues spécifiées à l'aide de l'option –eu.
encryption 1 si la base de données est cryptée, 0 dans le cas
contraire.
alloced_by_dbsync FALSE, à l'exception des noeuds créés dans
dbtool8.dll.
Contient les informations requises par les utilitaires dbinfo et dbunload
employant la bibliothèque DBTools.
typedef struct a_sysinfo {
a_bit_field valid_data : 1;
a_bit_field blank_padding : 1;
a_bit_field case_sensitivity : 1;
a_bit_field encryption : 1;
char default_collation[11];
unsigned short page_size;
} a_sysinfo;

Paramètres
Voir aussi
Structure a_table_info
Fonction
Syntaxe
Paramètres
Elément Description
Chapitre 8 Interface Outils de base de données
valid_date Champ de bits indiquant si les valeurs qui suivent sont
définies.
blank_padding 1 si le remplissage avec des blancs est utilisé dans la base de
données, 0 dans le cas contraire.
case_sensitivity 1 si la base de données fait la distinction
majuscules/minuscules, 0 dans le cas contraire.
encryption 1 si la base de données est cryptée, 0 dans le cas contraire.
default_collation Ordre de classement de la base de données.
page_size Taille des pages de la base de données.
"Structure a_db_info", page 343
Contient les informations relatives à une table requise par la structure
a_db_info.
typedef struct a_table_info {
struct a_table_info * next;
unsigned short table_id;
unsigned long table_pages;
unsigned long index_pages;
unsigned long table_used;
unsigned long index_used;
char * table_name;
a_sql_uint32 table_used_pct;
a_sql_uint32 index_used_pct;
} a_table_info;
Elément Description
next Table suivante de la liste.
table_id Numéro d'ID de la table.
table_pages Nombre de pages de la table.
index_pages Nombre de pages d'index.
353

Structures DBTools
Voir aussi
Structure a_translate_log
Fonction
354
Elément Description
table_used Nombre d'octets utilisés dans les pages de la table.
index_used Nombre d'octets utilisés dans les pages d'index.
table_name Nom de la table.
table_used_pct Utilisation de l'espace de table en pourcentage.
index_used_pct Utilisation de l'espace d'index en pourcentage.
"Structure a_db_info", page 343
Contient les informations requises pour convertir un journal de transactions à
l'aide de la bibliothèque DBTools.

Syntaxe
Chapitre 8 Interface Outils de base de données
typedef struct a_translate_log {
unsigned short version;
const char * logname;
const char * sqlname;
p_name userlist;
MSG_CALLBACK confirmrtn;
MSG_CALLBACK errorrtn;
MSG_CALLBACK msgrtn;
char userlisttype;
a_bit_field remove_rollback : 1;
a_bit_field ansi_SQL : 1;
a_bit_field since_checkpoint: 1;
a_bit_field omit_comments : 1;
a_bit_field replace : 1;
a_bit_field debug : 1;
a_bit_field include_trigger_trans : 1;
a_bit_field comment_trigger_trans : 1;
unsigned long since_time;
const char _fd_ * reserved_1;
const char _fd_ * reserved_2;
a_sql_uint32 debug_dump_size;
a_bit_field debug_sql_remote : 1;
a_bit_field debug_dump_hex : 1;
a_bit_field debug_dump_char : 1;
a_bit_field debug_page_offsets : 1;
a_bit_field reserved_3 : 1;
a_bit_field use_hex_offsets : 1;
a_bit_field use_relative_offsets : 1;
a_bit_field include_audit : 1;
a_bit_field chronological_order : 1;
a_bit_field force_recovery : 1;
a_bit_field include_subsets : 1;
a_bit_field force_chaining : 1;
a_sql_uint32 recovery_ops;
a_sql_uint32 recovery_bytes;
const char _fd_ * include_source_sets;
const char _fd_ * include_destination_sets;
const char _fd_ * include_scan_range;
const char _fd_ * repserver_users;
const char _fd_ * include_tables;
const char _fd_ * include_publications;
const char _fd_ * queueparms;
a_bit_field generate_reciprocals :1;
a_bit_field match_mode :1;
const char _fd_ * match_pos;
MSG_CALLBACK statusrtn;
const char _fd_ * encryption_key;
a_bit_field show_undo :1;
const char _fd_ * logs_dir;
} a_translate_log;
355

Structures DBTools
Paramètres
Voir aussi
Structure a_truncate_log
Fonction
Syntaxe
356
Les paramètres correspondent aux fonctionnalités accessibles depuis
l'utilitaire de ligne de commande dbtran.
Pour des commentaires supplémentaires, reportez-vous au fichier d'en-tête
dbtools.h.
"Fonction DBTranslateLog", page 329
"Structure a_name", page 349
"Enumération dbtran_userlist_type", page 365
$ Pour plus d'informations sur les fonctions callback, reportez-vous à
"Utilisation des fonctions callback", page 313.
Contient les informations requises pour tronquer un journal de transactions à
l'aide de la bibliothèque DBTools.
typedef struct a_truncate_log {
unsigned short version;
const char * connectparms;
const char * startline;
MSG_CALLBACK errorrtn;
MSG_CALLBACK msgrtn;
a_bit_field quiet : 1;
char truncate_interrupted;
} a_truncate_log;

Paramètres
Voir aussi
Structure an_unload_db
Fonction
Syntaxe
Elément Description
Chapitre 8 Interface Outils de base de données
version Numéro de version de DBTools.
connectparms Paramètres requis pour la connexion à la base de données.
Ils se présentent sous la forme de chaînes de connexion.
Exemple :
"UID=DBA;PWD=SQL;DBF=c:\asa\asademo.db"
$ Pour obtenir l'ensemble des options de chaîne de
connexion, reportez-vous à la section "Paramètres de
connexion", page 75 du document ASA Guide
d’administration.
startline Ligne de commande utilisée pour démarrer le moteur de
bases de données. Exemple :
"c:\asa\win32\dbeng8.exe"
Si cet élément est NULL, la ligne de démarrage par défaut
est utilisée.
errorrtn Routine callback de gestion d'un message d'erreur.
msgrtn Routine callback de gestion d'un message d'information.
quiet Fonctionnement avec (0) ou sans (1) impression de
messages.
truncate_interrupted Indique que l'opération a été interrompue
"Fonction DBTruncateLog", page 329
$ Pour plus d'informations sur les fonctions callback, reportez-vous à
"Utilisation des fonctions callback", page 313.
Contient les informations requises pour décharger une base de données à
l'aide de la bibliothèque DBTools ou pour extraire une base de données
distante pour SQL Remote. Les champs utilisés par l'utilitaire d'extraction
SQL Remote dbxtract sont indiqués.
typedef struct an_unload_db {
unsigned short version;
const char * connectparms;
const char * startline;
const char * temp_dir;
const char * reload_filename;
MSG_CALLBACK errorrtn;
MSG_CALLBACK msgrtn;
MSG_CALLBACK statusrtn;
357

Structures DBTools
Paramètres
358
MSG_CALLBACK confirmrtn;
char unload_type;
char verbose;
a_bit_field unordered : 1;
a_bit_field no_confirm : 1;
a_bit_field use_internal_unload : 1;
a_bit_field dbo_avail : 1;
a_bit_field extract : 1;
a_bit_field table_list_provided : 1;
a_bit_field exclude_tables : 1;
a_bit_field more_flag_bits_present : 1;
a_sysinfo sysinfo;
const char * remote_dir;
const char * dbo_username;
const char * subscriber_username;
const char * publisher_address_type;
const char * publisher_address;
unsigned short isolation_level;
a_bit_field start_subscriptions : 1;
a_bit_field exclude_foreign_keys : 1;
a_bit_field exclude_procedures : 1;
a_bit_field exclude_triggers : 1;
a_bit_field exclude_views : 1;
a_bit_field isolation_set : 1;
a_bit_field include_where_subscribe : 1;
a_bit_field debug : 1;
p_name table_list;
a_bit_short escape_char_present : 1;
a_bit_short view_iterations_present : 1;
unsigned short view_iterations;
char escape_char;
char _fd_ * reload_connectparms;
char _fd_ * reload_db_filename;
a_bit_field output_connections:1;
char unload_interrupted;
a_bit_field replace_db:1;
const char _fd_ * locale;
const char _fd_ * site_name;
const char _fd_ * template_name;
a_bit_field preserve_ids:1;
a_bit_field exclude_hooks:1;
char _fd_ * reload_db_logname;
const char _fd_ * encryption_key;
const char _fd_ * encryption_algorithm;
a_bit_field syntax_version_7:1;
a_bit_field remove_java:1;
} an_unload_db;
Les paramètres correspondent aux fonctionnalités accessibles depuis les
utilitaires de ligne de commande dbunload, dbxtract et mlxtract.

Voir aussi
Structure an_upgrade_db
Fonction
Syntaxe
Paramètres
Chapitre 8 Interface Outils de base de données
Pour des commentaires supplémentaires, reportez-vous au fichier d'en-tête
dbtools.h.
"Fonction DBUnload", page 330
"Structure a_name", page 349
"Enumération dbunload_type", page 365
$ Pour plus d'informations sur les fonctions callback, reportez-vous à
"Utilisation des fonctions callback", page 313.
Contient les informations requises pour mettre à niveau une base de données
à l'aide de la bibliothèque DBTools.
typedef struct an_upgrade_db {
unsigned short version;
const char * connectparms;
const char * startline;
MSG_CALLBACK errorrtn;
MSG_CALLBACK msgrtn;
MSG_CALLBACK statusrtn;
a_bit_field quiet : 1;
a_bit_field dbo_avail : 1;
const char * dbo_username;
a_bit_field java_classes : 1;
a_bit_field jconnect : 1;
a_bit_field remove_java : 1;
a_bit_field java_switch_specified : 1;
const char * jdk_version;
} an_upgrade_db;
Elément Description
version Numéro de version de DBTools.
connectparms Paramètres requis pour la connexion à la base de données. Ils se
présentent sous la forme de chaînes de connexion. Exemple :
"UID=DBA;PWD=SQL;DBF=c:\asa\asademo.db"
$ Pour obtenir l'ensemble des options de chaîne de
connexion, reportez-vous à la section "Paramètres de
connexion", page 75 du document ASA Guide d’administration
startline Ligne de commande utilisée pour démarrer le moteur de bases
de données. Exemple :
"c:\asa\win32\dbeng8.exe"
Si cet élément est NULL, la ligne de démarrage par défaut est
utilisée.
errorrtn Routine callback de gestion d'un message d'erreur.
359

Structures DBTools
Voir aussi
Structure a_validate_db
Fonction
Syntaxe
360
Elément Description
msgrtn Routine callback de gestion d’un message d’information.
statusrtn Routine callback de gestion d'un message d'état.
quiet Fonctionnement avec (0) ou sans (1) impression de messages.
dbo_avail Si 1, indique que la version de DBTools est suffisamment
récente pour supporter le champ dbo_username.
dbo_username Nom d'utilisateur du dbo.
java_classes Met à niveau la base de données afin qu'elle soit configurée
pour Java.
jconnect Met à niveau la base de données afin qu'elle inclue les
procédures jConnect.
remove_java Met à niveau la base de données en supprimant les
fonctionnalités Java.
jdk_version Une des valeurs de l'option -jdk de dbinit.
"Fonction DBUpgrade", page 330
$ Pour plus d'informations sur les fonctions callback, reportez-vous à
"Utilisation des fonctions callback", page 313.
Contient les informations requises pour valider la base de données à l'aide de
la bibliothèque DBTools.
typedef struct a_validate_db {
unsigned short version;
const char * connectparms;
const char * startline;
p_name tables;
MSG_CALLBACK errorrtn;
MSG_CALLBACK msgrtn;
MSG_CALLBACK statusrtn;
a_bit_field quiet : 1;
a_bit_field index : 1;
a_validate_type type;
} a_validate_db;

Paramètres
Voir aussi
Structure a_writefile
Fonction
Elément Description
version Numéro de version de DBTools.
Chapitre 8 Interface Outils de base de données
connectparms Paramètres requis pour la connexion à la base de données. Ils se
présentent sous la forme de chaînes de connexion. Exemple :
"UID=DBA;PWD=SQL;DBF=c:\asa\asademo.db"
$ Pour obtenir l'ensemble des options de chaîne de connexion,
reportez-vous à la section "Paramètres de connexion", page 75 du
document ASA Guide d’administration.
startline Ligne de commande utilisée pour démarrer le moteur de bases de
données. Exemple :
"c:\Program Files\Sybase\SA\win32\dbeng8.exe"
Si cet élément est NULL, la ligne de démarrage par défaut est
utilisée.
tables Pointeur sur une liste chaînée de noms de tables.
errorrtn Routine callback de gestion d'un message d'erreur.
msgrtn Routine callback de gestion d'un message d'information.
statusrtn Routine callback de gestion d'un message d'état.
quiet Fonctionnement avec (0) ou sans (1) impression de messages.
index Validation des index
type Reportez-vous à la section "Enumération a_validate_type",
page 366.
"Fonction DBValidate", page 331
"Structure a_name", page 349
$ Pour plus d'informations sur les fonctions callback, reportez-vous à la
section "Utilisation des fonctions callback", page 313.
Contient les informations requises pour gérer les fichiers d'écriture de base
de données à l'aide de la bibliothèque DBTools.
361

Structures DBTools
Syntaxe
Paramètres
362
typedef struct a_writefile {
unsigned short version;
const char * writename;
const char * wlogname;
const char * dbname;
const char * forcename;
MSG_CALLBACK confirmrtn;
MSG_CALLBACK errorrtn;
MSG_CALLBACK msgrtn;
char action;
a_bit_field quiet : 1;
a_bit_field erase : 1;
a_bit_field force : 1;
a_bit_field mirrorname_present : 1;
const char * wlogmirrorname;
a_bit_field make_log_and_mirror_names: 1;
const char * encryption_key;
} a_writefile;
Elément Description
version Numéro de version de DBTools.
writename Nom du fichier d'écriture.
wlogname Utilisé uniquement lors de la création de fichiers
d'écriture.
dbname Utilisé lors de la création et de la modification de fichiers
d'écriture.
forcename Référence de nom de fichier forcée.
confirmrtn Routine callback de confirmation d'une action. Utilisé
uniquement lors de la création de fichiers d'écriture.
errorrtn Routine callback de gestion d'un message d'erreur.
msgrtn Routine callback de gestion d'un message d'information.
action Réservé à l'usage de Sybase.
quiet Fonctionnement avec (0) ou sans (1) impression de
messages.
erase Utilisé pour la création de fichiers d'écriture uniquement.
Suppression avec (0) ou sans (1) confirmation.

Voir aussi
Elément Description
Chapitre 8 Interface Outils de base de données
force Si 1, impose que le fichier d'écriture pointe sur un fichier
nommé.
mirrorname_present Utilisé en cas de création uniquement. Si 1, indique que la
version de DBTools est suffisamment récente pour
prendre en charge le champ mirrorname.
wlogmirrorname Nom du fichier miroir du journal de transactions.
make_log_and_mirro
r_names
Si TRUE, utilise les valeurs de wlogname et
wlogmirrorname pour déterminer les noms de fichier.
encryption_key Clé de cryptage du fichier de base de données.
"Fonction DBChangeWriteFile", page 321
"Fonction DBCreateWriteFile", page 323
"Fonction DBStatusWriteFile", page 326
$ Pour plus d'informations sur les fonctions callback, reportez-vous à
"Utilisation des fonctions callback", page 313.
363

Types d'énumération DBTools
Types d'énumération DBTools
Enumération du mode de sortie
Fonction
Syntaxe
Paramètres
Voir aussi
364
La présente section répertorie les types d'énumération utilisés par la
bibliothèque DBTools. Les énumérations sont répertoriées dans l'ordre
alphabétique.
Spécifie le mode de sortie.
enum {
VB_QUIET,
VB_NORMAL,
VB_VERBOSE
};
Valeur Description
VB_QUIET Pas de sortie.
VB_NORMAL Sortie normale.
VB_VERBOSE Sortie détaillée, utilisée à des fins de débogage.
"Structure a_create_db", page 338
"Structure an_unload_db", page 357
Enumération du remplissage avec des blancs
Fonction
Syntaxe
Paramètres
Voir aussi
Utilisée dans "Structure a_create_db", page 338 pour spécifier la valeur de
blank_pad.
enum {
NO_BLANK_PADDING,
BLANK_PADDING
};
Valeur Description
NO_BLANK_PADDING N’utilise pas le remplissage avec des blancs en
fin de chaîne.
BLANK_PADDING Utilise le remplissage avec des blancs.
"Structure a_create_db", page 338

Enumération dbtran_userlist_type
Fonction
Syntaxe
Paramètres
Voir aussi
Enumération dbunload_type
Fonction
Syntaxe
Paramètres
Voir aussi
Chapitre 8 Interface Outils de base de données
Type d'une liste d'utilisateurs, employé par "Structure a_translate_log",
page 354.
typedef enum dbtran_userlist_type {
DBTRAN_INCLUDE_ALL,
DBTRAN_INCLUDE_SOME,
DBTRAN_EXCLUDE_SOME
} dbtran_userlist_type;
Valeur Description
DBTRAN_INCLUDE_ALL Inclut les opérations de tous les utilisateurs.
DBTRAN_INCLUDE_SOME Inclut uniquement les opérations exécutées par
les utilisateurs figurant dans la liste fournie.
DBTRAN_EXCLUDE_SOME Exclut uniquement les opérations exécutées
par les utilisateurs figurant dans la liste
fournie.
"Structure a_translate_log", page 354
Type du déchargement en cours d'exécution, utilisé par "Structure
an_unload_db", page 357.
enum {
UNLOAD_ALL,
UNLOAD_DATA_ONLY,
UNLOAD_NO_DATA
};
Valeur Description
UNLOAD_ALL Décharge les données et le schéma.
UNLOAD_DATA_ONLY Décharge les données. Pas de déchargement
du schéma.
UNLOAD_NO_DATA Décharge le schéma uniquement.
"Structure an_unload_db", page 357
365

Types d'énumération DBTools
Enumération a_validate_type
Fonction
Syntaxe
Paramètres
Voir aussi
366
Type de validation en cours d'exécution, utilisé par "Structure
a_validate_db", page 360.
typedef enum {
VALIDATE_NORMAL = 0,
VALIDATE_DATA,
VALIDATE_INDEX,
VALIDATE_EXPRESS,
VALIDATE_FULL
} a_validate_type;
Valeur Description
VALIDATE_NORMAL Validation avec vérification par défaut uniquement.
VALIDATE_DATA Validation avec vérification des données en plus de la
vérification par défaut.
VALIDATE_INDEX Validation avec vérification des index en plus de la
vérification par défaut.
VALIDATE_EXPRESS Validation avec vérification express en plus de la
vérification par défaut et de la vérification des
données.
VALIDATE_FULL Validation avec vérification des données et des index
en plus de la vérification par défaut.
"Validation d'une base de données à l'aide de l'utilitaire dbvalid", page 575
du document ASA Guide d’administration
"Instruction VALIDATE TABLE", page 615 du document ASA Manuel de
référence SQL.

CHAPITRE 9
Les interfaces de programmation OLE DB
et ADO
Présentation
Sommaire
Ce chapitre explique comment utiliser l’interface OLE DB avec Adaptive
Server Anywhere.
De nombreuses applications passent par l'intermédiaire du modèle de
programmation ADO (ActiveX Data Objects) de Microsoft pour utiliser
l'interface OLE DB. Ce chapitre décrit également la programmation ADO
avec Adaptive Server Anywhere.
Sujet Page
Introduction à OLE DB 368
Programmation ADO avec Adaptive Server Anywhere 370
Interfaces OLE DB supportées 378
367

Introduction à OLE DB
Introduction à OLE DB
Plates-formes supportées
368
OLE DB est un modèle d'accès aux données proposé par Microsoft. Se
servant des interfaces COM (Component Object Model), le modèle OLE DB,
contrairement à ODBC, ne présuppose pas que la source de données utilise
un processeur de requêtes SQL.
Adaptive Server Anywhere inclut un fournisseur OLE DB appelé
ASAProv. Ce fournisseur est disponible pour les plates-formes Windows
actuelles ainsi que pour Windows CE.
Vous pouvez également accéder à Adaptive Server Anywhere à l'aide du
fournisseur OLE DB pour ODBC (MSDASQL) de Microsoft, conjugué au
pilote ODBC d'Adaptive Server Anywhere.
L'utilisation du fournisseur OLE DB d'Adaptive Server Anywhere procure
plusieurs avantages :
♦ Certaines fonctionnalités, dont la mise à jour à l'aide d'un curseur, ne
sont pas disponibles via la passerelle OLE DB/ODBC.
♦ Si vous avez recours au fournisseur OLE DB d'Adaptive Server
Anywhere, le déploiement ne nécessite pas ODBC.
♦ MSDASQL permet aux clients OLE DB de travailler avec n'importe
quel pilote ODBC, mais sans garantir que toute la gamme des
fonctionnalités de chaque pilote ODBC soit exploitée. En utilisant le
fournisseur d'Adaptive Server Anywhere, vous pouvez accéder à toutes
les fonctionnalités d'Adaptive Server Anywhere à partir des
environnements de programmation OLE DB.
Le fournisseur OLE DB d'Adaptive Server Anywhere est conçu pour
fonctionner avec OLE DB version 2.5 et ultérieure. Pour Windows CE et ses
prochaines extensions, le fournisseur OLE DB est conçu pour ADOCE
version 3.0 et ultérieure.
ADOCE, qui est l'ADO de Microsoft pour le SDK de Windows CE, apporte
une fonctionnalité de base de données aux applications développées avec les
Toolkits Windows CE pour Visual Basic 5.0 et Visual Basic 6.0.
$ Pour obtenir une liste des plates-formes supportées, reportez-vous à la
rubrique "Versions des systèmes d'exploitation", page 144 du document
Présentation de SQL Anywhere Studio.

Transactions distribuées
Chapitre 9 Les interfaces de programmation OLE DB et ADO
Il est possible d’utiliser le gestionnaire OLE DB comme gestionnaire de
ressources dans un environnement de transactions distribuées.
$ Pour plus d'informations, reportez-vous au chapitre "Transactions
distribuées et architecture à trois niveaux", page 393.
369

Programmation ADO avec Adaptive Server Anywhere
Programmation ADO avec Adaptive Server
Anywhere
370
ADO (ActiveX Data Objects) est un modèle d'accès objet aux données
présenté par le biais d'une interface Automation, qui permet aux applications
clientes de découvrir les méthodes et propriétés des objets lors de l'exécution
sans connaissance préalable de ces derniers. Automation permet aux
langages de script comme Visual Basic d'utiliser un modèle d'accès objet aux
données standard. ADO a recours à OLE DB pour fournir l'accès aux
données.
Si vous utilisez le fournisseur OLE DB d'Adaptive Server Anywhere, vous
avez un accès complet aux fonctionnalités d'Adaptive Server Anywhere à
partir d'un environnement de programmation ADO.
Cette section décrit comment exécuter les tâches élémentaires en utilisant
ADO à partir de Visual Basic. Il ne s'agit pas d'un guide complet de
programmation à l'aide d'ADO.
Les exemples de code issus de cette section se trouvent dans les fichiers
suivants :
Outil de
développement
Microsoft Visual Basic
6.0
Microsoft eMbedded
Visual Basic 3.0
Exemple
Samples\ASA\VBSampler\vbsampler.vbp
Samples\ASA\ADOCE\OLEDB_PocketPC.ebp
$ Pour plus d’informations sur la programmation avec ADO, reportezvous
à la documentation relative à votre outil de développement.
$ Pour plus de détails sur l'utilisation d'ADO et de Visual Basic pour
accéder aux données d'une base Adaptive Server Anywhere, reportez-vous
au livre blanc Accessing Data in Adaptive Server Anywhere Using ADO and
Visual Basic, disponible à l'adresse
http://www.sybase.com/detail?id=1017429.
Connexion à une base de données avec l'objet Connection
Cette section décrit une routine Visual Basic simple pour une connexion à
une base de données.

Code exemple
Remarques
Chapitre 9 Les interfaces de programmation OLE DB et ADO
Pour essayer cette routine, placez un bouton de commande intitulé
Command1 dans un formulaire et collez la routine dans son événement
Click. Lancez le programme et cliquez sur le bouton pour établir une
connexion puis effectuer une déconnexion.
Private Sub cmdTestConnection_Click()
' Déclare les variables
Dim myConn As New ADODB.Connection
Dim myCommand As New ADODB.Command
Dim cAffected As Long
On Error GoTo HandleError
' Etablit la connexion
myConn.Provider = "ASAProv"
myConn.ConnectionString = _
"Data Source=ASA 8.0 Sample"
myConn.Open
MsgBox "Réussite connexion"
myConn.Close
Exit Sub
HandleError:
MsgBox "Echec connexion"
Exit Sub
End Sub
Voici le déroulement des tâches exécutées :
♦ Les variables utilisées dans la routine sont déclarées.
♦ Une connexion à la base de données exemple est établie à l'aide du
fournisseur OLE DB d'Adaptive Server Anywhere.
♦ Un objet Command est utilisé pour exécuter une instruction simple, qui
affiche un message dans la fenêtre du serveur de base de données.
♦ La connexion est fermée.
Le fournisseur ASAProv s'enregistre automatiquement lorsqu'il est installé.
Le processus d'enregistrement consiste à créer des entrées de registre dans la
section COM du registre de sorte qu'ADO puisse localiser le fichier DLL en
cas d'appel du fournisseur ASAProv. Si vous modifiez l'emplacement de
votre fichier DLL, vous devez l'enregistrer à nouveau.
v Pour enregistrer le fournisseur OLE DB :
1 Ouvrez une fenêtre de commandes.
2 Placez-vous dans le répertoire d'installation du fournisseur OLE DB.
371

Programmation ADO avec Adaptive Server Anywhere
372
3 Entrez la commande suivante pour enregistrer le fournisseur :
regsvr32 dboledb8.dll
$ Pour plus d'informations sur la connexion à une base de données à l'aide
d'OLE DB, reportez-vous à la section "Connexion à une base de données
avec OLE DB", page 73 du document ASA Guide d’administration.
Exécution d'instructions avec l'objet Command
Code exemple
Remarques
Cette section décrit une routine simple qui envoie une instruction SQL
simple à la base de données.
Pour essayer cette routine, placez un bouton de commande intitulé
Command2 dans un formulaire et collez la routine dans son événement
Click. Lancez le programme et cliquez sur le bouton pour établir une
connexion, afficher un message dans la fenêtre du serveur de base de
données, puis effectuer une déconnexion.
Private Sub cmdUpdate_Click()
' Déclare les variables
Dim myConn As New ADODB.Connection
Dim myCommand As New ADODB.Command
Dim cAffected As Long
' Etablit la connexion
myConn.Provider = "ASAProv"
myConn.ConnectionString = _
"Data Source=ASA 8.0 Sample"
myConn.Open
'Exécute une commande
myCommand.CommandText = _
"update customer set fname='Liz' where id=102"
Set myCommand.ActiveConnection = myConn
myCommand.Execute cAffected
MsgBox CStr(cAffected) +
" lignes affectées.", vbInformation
myConn.Close
End Sub
Après avoir établi une connexion, le code exemple crée un objet Command,
définit sa propriété CommandText à une instruction de mise à jour et sa
propriété ActiveConnection à la connexion en cours. Il exécute ensuite
l'instruction de mise à jour et affiche le nombre de lignes affectées par la
mise à jour dans une boîte de message.
Dans cet exemple, la mise à jour est envoyée à la base de données puis
validée dès son exécution.

Chapitre 9 Les interfaces de programmation OLE DB et ADO
$ Pour plus d’informations sur l’utilisation des transactions au sein
d'ADO, reportez-vous à la section "Utilisation des transactions", page 377.
Vous pouvez également effectuer les mises à jour à l'aide d'un curseur.
$ Pour plus d'informations, reportez-vous à la section "Mise à jour de
données à l'aide d'un curseur", page 375.
Interrogation de la base de données avec l'objet Recordset
Code exemple
L’objet Recordset d'ADO représente le jeu de résultats d'une requête. Vous
pouvez l'utiliser pour visualiser les données d'une base de données.
Pour essayer cette routine, placez un bouton de commande intitulé
cmdQuery dans un formulaire et collez la routine dans son événement
Click. Lancez le programme et cliquez sur le bouton pour établir une
connexion, afficher un message dans la fenêtre du serveur de base de
données, exécuter une requête et afficher les premières lignes des boîtes de
message, puis effectuer une déconnexion.
373

Programmation ADO avec Adaptive Server Anywhere
Remarques
374
Private Sub cmdQuery_Click()
' Déclare les variables
Dim myConn As New ADODB.Connection
Dim myCommand As New ADODB.Command
Dim myRS As New ADODB.Recordset
On Error GoTo ErrorHandler:
' Etablit la connexion
myConn.Provider = "ASAProv"
myConn.ConnectionString = _
"Data Source=ASA 8.0 Sample"
myConn.CursorLocation = adUseServer
myConn.Mode = adModeReadWrite
myConn.IsolationLevel = adXactCursorStability
myConn.Open
'Exécute une requête
Set myRS = New Recordset
myRS.CacheSize = 50
myRS.Source = "Select * from customer"
myRS.ActiveConnection = myConn
myRS.CursorType = adOpenKeyset
myRS.LockType = adLockOptimistic
myRS.Open
'Fait défiler les premiers résultats
myRS.MoveFirst
For i = 1 To 5
MsgBox myRS.Fields("company_name"), vbInformation
myRS.MoveNext
Next
myRS.Close
myConn.Close
Exit Sub
ErrorHandler:
MsgBox Error(Err)
Exit Sub
End Sub
L’objet Recordset de cet exemple contient les résultats d'une requête portant
sur la table Customer. La boucle For fait défiler les premières lignes et
affiche la valeur company_name correspondant à chaque ligne.
Il s'agit d'un exemple simple d'utilisation d'un curseur à partir d'ADO.
$ Pour des exemples plus élaborés sur l'utilisation d'un curseur à partir
d'ADO, reportez-vous à la section "Utilisation d'un objet Recordset",
page 375.

Utilisation d’un objet Recordset
Types de curseur
Code exemple
Chapitre 9 Les interfaces de programmation OLE DB et ADO
Dans son fonctionnement avec Adaptive Server Anywhere, l’objet Recordset
d'ADO représente un curseur. Vous pouvez choisir le type de curseur en
déclarant une propriété CursorType de l'objet Recordset avant d'ouvrir ce
dernier. En fonction du type de curseur choisi, diverses actions sont possibles
sur l'objet Recordset et les performances sont différentes.
Vous trouverez une description de l'ensemble des types de curseur supportés
par Adaptive Server Anywhere à la section "Propriétés de curseur", page 25.
ADO possède ses propres conventions de dénomination des types de curseur.
Les types de curseur disponibles, les constantes correspondant à chaque type
et les types équivalents pour Adaptive Server Anywhere sont les suivants :
Type de curseur
ADO
Constante ADO Type de curseur
Adaptive Server
Anywhere
Curseur dynamique adOpenDynamic Curseur avec défilement
dynamique
Curseur keyset adOpenKeyset Curseur avec défilement
Curseur statique adOpenStatic Curseur insensible
(insensitive)
Curseur à
défilement avant
uniquement
adOpenForwardOnly Curseur sans défilement
$ Pour plus d'informations sur le choix d'un type de curseur adapté à votre
application, reportez-vous à la section "Choix d'un type de curseur", page 25.
Le code suivant définit le type de curseur pour un objet Recordset d'ADO :
Dim myRS As New ADODB.Recordset
myRS.CursorType = adOpenDynamic
Mise à jour de données à l'aide d'un curseur
Mise à jour de jeux
d'enregistrements
Le fournisseur OLE DB d'Adaptive Server Anywhere permet de mettre à
jour un jeu de résultats à l'aide d'un curseur. Cette possibilité n'est pas offerte
par le fournisseur MSDASQL.
Vous pouvez mettre à jour la base de données à l'aide d'un jeu
d'enregistrements.
375

Programmation ADO avec Adaptive Server Anywhere
Remarques
376
Private Sub Command6_Click()
Dim myConn As New ADODB.Connection
Dim myRS As New ADODB.Recordset
Dim SQLString As String
’ Connexion
myConn.Provider = "ASAProv"
myConn.ConnectionString = _
"Data Source=ASA 8.0 Sample"
myConn.Open
myConn.BeginTrans
SQLString = "Select * from customer"
myRS.Open SQLString, _
myConn, adOpenDynamic, adLockBatchOptimistic
_
If myRS.BOF And myRS.EOF Then
MsgBox "Jeu de résultat vide !", _
16, "Empty Recordset"
Else
MsgBox "Type de curseur : " + _
CStr(myRS.CursorType), vbInformation
myRS.MoveFirst
For i = 1 To 3
MsgBox "Ligne : " + CStr(myRS.Fields("id")),
vbInformation
If i = 2 Then
myRS.Update "City", "Toronto"
myRS.UpdateBatch
End If
myRS.MoveNext
Next i
' myRS.MovePrevious
myRS.Close
End If
myConn.CommitTrans
myConn.Close
End Sub
Si vous appliquez le paramètre adLockBatchOptimistic au jeu
d'enregistrements, la méthode myRS.Update n'apporte aucune modification
à la base de données elle-même : elle met à jour une copie locale de l'objet
Recordset.
La méthode myRS.UpdateBatch effectue la mise à jour du serveur de base
de données, mais ne la valide pas, car elle est interne à la transaction. Si une
méthode UpdateBatch a été appelée à l'extérieur d'une transaction, la
modification est validée.
La méthode myConn.CommitTrans valide les modifications. En effet,
comme l'objet Recordset est désormais fermé, le fait que la copie locale des
données soit modifiée ou non n'a plus d'importance.

Utilisation des transactions
Chapitre 9 Les interfaces de programmation OLE DB et ADO
Par défaut, toute modification apportée à la base de données à l'aide d'ADO
est validée dès son exécution, qu'il s'agisse de mises à jour explicites ou de la
méthode UpdateBatch appliquée à un objet Recordset. Toutefois, vous avez
vu à la section précédente comment appliquer les méthodes BeginTrans et
RollbackTrans ou CommitTrans à l'objet Connection pour utiliser des
transactions.
Le niveau d'isolement d'une transaction est défini comme une propriété de
l'objet Connection. La propriété IsolationLevel peut prendre l'une des valeurs
suivantes :
Niveau d’isolement
ADO
Constante Niveau ASA
Non spécifié adXactUnspecified Non applicable. Défini à 0
Chaos adXactChaos Non supporté. Défini à 0
Browse (survol) adXactBrowse 0
Read uncommitted
(lecture non validée)
Cursor stability
(stabilité du curseur)
Read committed
(lecture validée)
Repeatable read (lecture
répétable)
adXactReadUncommitte
d
adXactCursorStability 1
adXactReadCommitted 1
adXactRepeatableRead 2
Isolated (isolé) adXactIsolated 3
Serializable
(sérialisable)
adXactSerializable 3
$ Pour plus d'informations sur les niveaux d'isolement, reportez-vous à la
section "Niveaux d'isolement et cohérence", page 98 du document ASA
Guide de l’utilisateur SQL.
0
377

Interfaces OLE DB supportées
Interfaces OLE DB supportées
378
L’API OLE DB est constituée d'un ensemble d'interfaces. Le tableau suivant
décrit le support de chaque interface dans le gestionnaire OLE DB
d'Adaptive Server Anywhere.
Interface Fonction Restrictions
IAccessor Définit des liaisons entre la
mémoire cliente et les
valeurs des sources de
données.
IAlterIndex
IAlterTable
Modifie les tables, les index
et les colonnes.
IChapteredRowset Un jeu de lignes par chapitre
permet d'accéder par
chapitres séparés à des lignes
d'un même ensemble.
IColumnsInfo Obtient des informations
simples sur les colonnes d'un
jeu de lignes.
IColumnsRowset Obtient des informations sur
les colonnes de métadonnées
optionnelles d'un jeu de
lignes et obtient un jeu de
lignes des métadonnées
d'une colonne.
ICommand Exécute les commandes
SQL.
ICommandPersist Prolonge l'état d'un objet de
commande (mais aucun jeu
de lignes actif). Ces objets de
commande persistants
peuvent ensuite être
énumérés à l'aide du jeu de
lignes PROCEDURES ou
VIEWS.
DBACCESSOR_PASS
BYREF non supporté.
DBACCESSOR_OPTI
MIZED non supporté.
Non supportée
Non supportée.
Adaptive Server
Anywhere ne supporte
pas les jeux de lignes
par chapitre .
N'existe pas sous CE.
N'existe pas sous CE.
Appel non supporté.
IcommandProperties :
GetProperties avec
DBPROPSET_PROPE
RTIESINERROR pour
trouver les propriétés
qui n'ont pas pu être
définies.
N'existe pas sous CE.

Chapitre 9 Les interfaces de programmation OLE DB et ADO
Interface Fonction Restrictions
ICommandPrepare Prépare les commandes. N'existe pas sous CE.
ICommandProperties Définit les propriétés Rowset
pour les jeux de lignes créés
par une commande. Utilisée
le plus souvent pour spécifier
les interfaces que le jeu de
lignes doit supporter.
ICommandText Définit le texte de la
commande SQL pour
ICommand.
IcommandWithParame
ters
Définit ou obtient des
informations de paramètre
pour une commande.
Supportée
Seul le dialecte
DBGUID_DEFAULT
SQL est supporté.
Aucun support pour les
paramètres enregistrés
comme vecteurs de
valeurs scalaires.
Aucun support pour les
paramètres BLOB.
N'existe pas sous CE.
IConvertType Supportée.
Limitée sous CE.
IDBAsynchNotify Traitement asynchrone. Non supportée
IDBAsyncStatus Prévient le client des
événements pendant le
traitement asynchrone de
l'initialisation de la source de
données, du remplissage des
jeux de lignes, etc.
IDBCreateCommand Crée des commandes à partir
d'une session.
IDBCreateSession Crée une session à partir d'un
objet de source de données.
IDBDataSourceAdmin Crée/détruit/modifie des
objets de source de données,
qui sont des objets COM
utilisés par les clients. Cette
interface n'est pas utilisée
pour la gestion des sources
de données (bases de
données).
Supportée
Supportée
Non supportée
379

Interfaces OLE DB supportées
380
Interface Fonction Restrictions
IDBInfo Localise des informations
sur des mots-clés propres à
ce fournisseur (trouve des
mots-clés SQL non
standard).
En outre, trouve des
informations sur des
littéraux, caractères spéciaux
utilisés dans les requêtes de
correspondance de texte et
autres informations littérales.
IDBInitialize Initialise les objets de source
de données et les
énumérateurs.
IDBProperties Gère les propriétés d'un objet
de source de données ou d'un
énumérateur.
IDBSchemaRowset Obtient des informations sur
les tables système, dans un
format standard (jeu de
lignes).
IErrorInfo
IErrorLookup
IErrorRecords
Supporte un objet erreur
ActiveX.
IGetDataSource Renvoie un pointeur
d'interface sur l'objet de
source de données de la
session.
IIndexDefinition Crée ou supprime des index
dans la source de données.
IMultipleResults Récupère plusieurs résultats
(jeux de lignes ou décomptes
de lignes) à partir d'une
commande.
IOpenRowset Procédé non SQL pour avoir
accès à une table de base de
données par son nom.
IParentRowset Accède aux jeux de lignes
par chapitre/hiérarchisés.
N'existe pas sous CE.
N'existe pas sous CE.
N'existe pas sous CE.
N'existe pas sous CE.
N'existe pas sous CE.
Supportée
Non supportée
Supportée
Supportée.
L'ouverture d'une table
avec son nom est
supportée, mais pas
avec un GUID.
Non supportée

Chapitre 9 Les interfaces de programmation OLE DB et ADO
Interface Fonction Restrictions
IRowset Accède aux jeux de lignes. Supportée
IRowsetChange Permet la retransmission
dans la source des données
des modifications des
données de jeu de lignes.
InsertRow/SetData pas
encore mis en oeuvre pour
les objets BLOB.
IRowsetChapterMemb
er
Accède aux jeux de lignes
par chapitre/hiérarchisés.
IRowsetCurrentIndex Modifie de façon dynamique
l'index d'un jeu de lignes.
IRowsetFind Localise dans un jeu de
lignes une ligne qui
correspond à une valeur
spécifiée.
IRowsetIdentity Compare les routines de
gestion de ligne.
IRowsetIndex Accède aux index de bases
de données.
IRowsetInfo Trouve les informations sur
les propriétés d'un jeu de
lignes ou l'objet ayant créé le
jeu de lignes.
IRowsetLocate Se positionne sur des lignes
d'un jeu de lignes, à l'aide de
signets.
IRowsetNotify Fournit une interface
callback COM pour les
événements de jeu de lignes.
IRowsetRefresh Obtient la dernière valeur de
données visible pour une
transaction.
IRowsetResynch Ancienne interface
OLEDB 1.x, remplacée par
IRowsetRefresh.
IRowsetScroll Fait défiler un jeu de lignes
pour extraire les données de
ligne.
N'existe pas sous CE.
Non supportée
Non supportée
Non supportée
Non supportée
Non supportée
N'existe pas sous CE.
N'existe pas sous CE.
Supportée
Non supportée
Non supportée
Non supportée
381

Interfaces OLE DB supportées
382
Interface Fonction Restrictions
IRowsetUpdate Reporte les modifications de
données d'un jeu de lignes
jusqu'à appel d'Update.
IRowsetView Utilise les vues sur un jeu de
lignes existant.
ISequentialStream Récupère une colonne
d'objet BLOB.
ISessionProperties Obtient des informations sur
la propriété de la session.
ISourcesRowset Obtient un jeu de lignes
d'objets de source de
données et d'énumérateurs.
ISQLErrorInfo
ISupportErrorInfo
ITableDefinition
ITableDefinitionWith
Constraints
Supporte un objet erreur
ActiveX.
Crée, supprime et modifie
des tables, avec des
contraintes.
ITransaction Valide ou abandonne des
transactions.
ITransactionJoin Supporte les transactions
distribuées.
ITransactionLocal Gère les transactions pour
une session.
Les balises ne sont pas toutes
supportées.
Supportée.
N'existe pas sous CE.
Non supportée
Supportée pour la
lecture seulement.
Aucun support pour
SetData avec cette
interface.
N'existe pas sous CE.
Supportée
N'existe pas sous CE.
En option sous CE
N'existe pas sous CE.
Les balises ne sont pas
toutes supportées.
N'existe pas sous CE.
Les balises ne sont pas
toutes supportées.
N'existe pas sous CE.
N'existe pas sous CE.

Chapitre 9 Les interfaces de programmation OLE DB et ADO
Interface Fonction Restrictions
ITransactionOptions Obtient ou définit les options
d'une transaction.
IViewChapter Travaille avec les vues sur
un jeu de lignes existant,
spécifiquement pour
appliquer des filtres/un tri
post-traitement aux lignes.
IViewFilter Limite le contenu d'un jeu de
lignes aux lignes
correspondant à un ensemble
de conditions.
IViewRowset L'ouverture d'un jeu de
lignes limite le contenu du
jeu de lignes aux lignes
vérifiant un ensemble de
conditions.
IViewSort Applique un ordre de tri à
une vue.
N'existe pas sous CE.
Non supportée
Non supportée
Non supportée
Non supportée
383

Interfaces OLE DB supportées
384

CHAPITRE 10
Interface Open Client
Présentation
Sommaire
Ce chapitre décrit l'interface de programmation Open Client d'Adaptive
Server Anywhere.
La documentation principale associée au développement d'applications
Open Client est disponible auprès de Sybase. Ce chapitre décrit des fonctions
spécifiques d'Adaptive Server Anywhere, mais n'est en aucun cas un guide
exhaustif de la programmation d'applications Open Client.
Sujet Page
Préalables à la création d'applications Open Client 386
Correspondances entre les types de données 387
SQL dans les applications Open Client 389
Limites d'Adaptive Server Anywhere avec Open Client 392
385

Préalables à la création d'applications Open Client
Préalables à la création d'applications
Open Client
386
Pour exécuter les applications Open Client, vous devez installer et configurer
les composants Open Client sur la même machine que l'application utilisée.
Vous pouvez disposer de ces composants par l'installation d'autres produits
Sybase ou installer les bibliothèques avec Adaptive Server Anywhere, selon
les clauses de votre contrat de licence.
Pour utiliser les applications Open Client, il n'est pas nécessaire que les
composants Open Client se trouvent sur la même machine que le serveur de
base de données.
Pour créer des applications Open Client, vous devez vous procurer la version
de développement d'Open Client, disponible auprès de Sybase.
Par défaut, les bases de données Adaptive Server Anywhere sont créées sans
prendre en compte la distinction majuscules/minuscules, contrairement aux
bases Adaptive Server Enterprise.
$ Pour plus d'informations sur l'exécution des applications Open Client
avec Adaptive Server Anywhere, reportez-vous au chapitre "Adaptive Server
Anywhere exploité comme un Open Server", page 111 du document ASA
Guide d’administration.

Chapitre 10 Interface Open Client
Correspondances entre les types de données
Types de données
Adaptive Server
Anywhere sans
équivalent direct
dans Open Client
Open Client dispose de ses propres types de données internes, qui diffèrent
légèrement de ceux d'Adaptive Server Anywhere. C'est pourquoi Adaptive
Server Anywhere effectue une mise en correspondance interne de certains
types de données utilisés par les applications Open Client.
Pour créer des applications Open Client, vous devez vous procurer la version
de développement d'Open Client. Pour utiliser une application Open Client,
les versions d'exécution (runtime) d'Open Client doivent être installées et
configurées sur le même ordinateur que l'application.
Le serveur Adaptive Server Anywhere n'a pas besoin d'exécutable de
communication externe pour supporter les applications Open Client.
Chaque type de données Open Client est mis en correspondance avec un type
équivalent Adaptive Server Anywhere. Tous les types de données Open
Client sont supportés.
Le tableau ci-dessous dresse la liste des mises en correspondance des types
de données supportés dans Adaptive Server Anywhere, n'ayant aucun
équivalent direct dans Open Client.
Type de données ASA Type de données Open Client
unsigned short int
unsigned int bigint
unsigned bigint bigint
date smalldatetime
time smalldatetime
serialization longbinary
java longbinary
string varchar
timestamp struct datetime
Limitation d’intervalle dans la mise en correspondance des types
de données
Certains types de données présentent des intervalles différents dans Adaptive
Server Anywhere et dans Open Client. Dans ce cas, des erreurs d'overflow
peuvent survenir lors de la récupération ou de l'insertion de données.
387

Correspondances entre les types de données
Exemple
Estampilles
388
Le tableau suivant indique les types de données des applications Open Client
possédant un équivalent sous Adaptive Server Anywhere mais dont les
intervalles des valeurs admises diffèrent.
Dans la plupart des cas, les données Open Client acceptent un intervalle de
valeurs plus restreint que les données Adaptive Server Anywhere
correspondantes. Par conséquent, il n'est pas exclu qu'une valeur transmise à
Adaptive Server Anywhere soit reconnue et stockée dans une base de
données, mais qu'elle soit en dehors des intervalles admis par l'application
Open Client.
Type de données Open Client -
limite
inférieure
MONEY –922 377 203
685 477.5808
Open Client -
limite
supérieure
922 377 203
685 477.5807
ASA - limite
inférieure
ASA - limite
supérieure
–1e15 + 0.0001 1e15 – 0.0001
SMALLMONEY –214 748.3648 214 748.3647 –214 748.3648 214 748.3647
DATETIME 1 janvier 1753 31 décembre
9999
1 janvier 0001 31 décembre
9999
SMALLDATETIME 1 janvier 1900 6 juin 2079 1 mars 1600 31 décembre
7910
Les données Open Client de type MONEY et SMALLMONEY ne possèdent
pas un intervalle de valeurs numériques aussi étendu que leurs équivalents
dans Adaptive Server Anywhere. Par conséquent, il se peut que les valeurs
d'une colonne dans Adaptive Server Anywhere correspondant au type de
données MONEY Open Client, dépassent les limites imposées par ce dernier.
Lorsque le client lit des valeurs répondant à ce cas de figure via Adaptive
Server Anywhere, une erreur survient.
La mise en oeuvre dans Adaptive Server Anywhere des données de type
TIMESTAMP d'Open Client diffère de celle d'Adaptive Server Enterprise.
Dans Adaptive Server Anywhere, la valeur est convertie en type de données
DATETIME. La valeur par défaut est NULL dans
Adaptive Server Anywhere, sans garantie d'unicité. En revanche,
Adaptive Server Enterprise incrémente automatiquement sa valeur, ce qui la
rend unique.
Inversement, le type de données Adaptive Server Anywhere TIMESTAMP
contient l'année, le mois, le jour, l'heure, les minutes, les secondes et les
fractions de seconde. De plus, le type DATETIME offre un plus grand
intervalle de valeurs que les types de données Open Client mis en
correspondance par Adaptive Server Anywhere.

SQL dans les applications Open Client
Exécution d'instructions SQL
Chapitre 10 Interface Open Client
Cette section fournit un aperçu rapide de l'utilisation de SQL dans les
applications Open Client et examine plus particulièrement les questions
spécifiques d'Adaptive Server Anywhere.
$ Pour une présentation des concepts, reportez-vous au chapitre
"Utilisation de SQL dans les applications", page 9. Pour une description plus
complète, reportez-vous à la documentation d'Open Client.
Vous pouvez envoyer des instructions SQL à une base de données en les
incluant dans des appels de fonction Client Library. Par exemple, les deux
appels suivants exécutent une instruction DELETE :
ret = ct_command(cmd, CS_LANG_CMD,
"DELETE FROM employee
WHERE emp_id=105"
CS_NULLTERM,
CS_UNUSED);
ret = ct_send(cmd);
La fonction ct_command offre de nombreuses possibilités d'utilisation.
Utilisation d'instructions préparées
La fonction ct_dynamic permet de gérer les instructions préparées. Cette
fonction accepte le paramètre type, qui décrit l'opération que vous effectuez.
v Pour utiliser une instruction préparée dans Open Client :
1 Préparez l'instruction via la fonction ct_dynamic, avec le paramètre
type CS_PREPARE.
2 Définissez les paramètres de l'instruction avec ct_param.
3 Exécutez l'instruction via ct_dynamic avec le paramètre type
CS_EXECUTE.
4 Libérez les ressources associées à l'instruction via ct_dynamic avec
le paramètre type CS_DEALLOC.
$ Pour plus d'informations sur l'utilisation d'instructions préparées dans
Open Client, consultez la documentation d'Open Client.
389

SQL dans les applications Open Client
Curseurs
Types de curseurs
supportés
Etapes d'utilisation
des curseurs
390
La fonction ct_cursor permet de gérer les curseurs. Cette fonction
accepte le paramètre type, qui décrit l'opération que vous effectuez.
Certains types de curseurs supportés par Adaptive Server Anywhere ne sont
pas disponibles via l'interface Open Client. Il n'est pas possible d'utiliser des
curseurs de défilement, des curseurs de défilement dynamiques, ou encore
des curseurs insensibles (insensitive) par l'intermédiaire d'Open Client.
Les curseurs possèdent entre autres propriétés la garantie d'unicité et la
capacité de mise à jour. Les curseurs peuvent être uniques (chaque ligne
comporte des informations de clé primaire ou d'unicité, qu'elles soient
utilisées ou non par l'application) ou ne pas l'être. Les curseurs peuvent être
en lecture seule ou capables de mise à jour. Lorsqu'un curseur peut être mis à
jour mais n'est pas unique, aucune prélecture de ligne n'est possible, quelle
que soit la valeur du paramètre CS_CURSOR_ROWS, et cela risque de
diminuer les performances.
Contrairement à d'autres interfaces, telles qu'Embedded SQL, Open Client
associe un curseur aux instructions SQL sous la forme d'une chaîne.
Embedded SQL prépare tout d'abord une instruction, puis Open Client
déclare le curseur par l'intermédiaire du descripteur d'instruction.
v Pour utiliser des curseurs dans Open Client :
1 Pour déclarer un curseur dans Open Client, utilisez ct_cursor avec le
paramètre type CS_CURSOR_DECLARE.
2 Après avoir déclaré un curseur, vous pouvez déterminer le nombre de
lignes faisant l'objet d'une extraction préalable du côté client à chaque
fois qu'une ligne est extraite du serveur par l'intermédiaire de
ct_cursor avec le paramètre type CS_CURSOR_ROWS.
Le fait de stocker des lignes préalablement extraites du côté client
diminue le nombre d'appels effectués vers le serveur, améliorant ainsi le
débit global et le délai d'exécution. Les lignes ayant fait l'objet d'une
extraction préalable ne sont pas transmises immédiatement à
l'application, mais stockées dans un buffer du côté client, prêtes à être
utilisées.
L'option de base de données PREFETCH contrôle l'extraction préalable
des lignes pour d'autres interfaces. En revanche, elle est ignorée par les
connexions Open Client. Le paramètre CS_CURSOR_ROWS est ignoré
pour les curseurs non uniques pouvant être mis à jour.
3 Pour ouvrir un curseur dans Open Client, utilisez ct_cursor avec le
paramètre type CS_CURSOR_OPEN.

Modification de lignes via un curseur
Chapitre 10 Interface Open Client
4 Pour extraire chaque ligne vers l’application, utilisez ct_fetch.
5 Pour fermer un curseur, utilisez ct_cursor avec CS_CURSOR_CLOSE.
6 Dans Open Client, vous devez également libérer les ressources associées
à un curseur. Pour ce faire, utilisez ct_cursor avec
CS_CURSOR_DEALLOC. Vous pouvez aussi utiliser
CS_CURSOR_CLOSE avec le paramètre complémentaire
CS_DEALLOC pour effectuer ces opérations en une seule étape.
Avec Open Client, vous pouvez supprimer ou mettre à jour les lignes d'un
curseur tant que ce dernier est créé sur une seule table. L'utilisateur doit avoir
l'autorisation de mettre à jour la table et le curseur doit être créé en mode
mise à jour.
v Pour modifier des lignes via un curseur :
♦ Au lieu d'exécuter une extraction, vous pouvez supprimer ou mettre à
jour la ligne active du curseur en utilisant respectivement ct_cursor avec
CS_CURSOR_DELETE ou CS_CURSOR_UPDATE.
Vous ne pouvez pas insérer de lignes par l'intermédiaire d'un curseur dans les
applications Open Client.
Description des résultats de requêtes dans Open Client
Open Client gère les jeux de résultats différemment d'autres interfaces
d'Adaptive Server Anywhere.
Avec Embedded SQL et ODBC, vous devez décrire une requête ou une
procédure stockée pour définir le nombre et les types de variables corrects
attendus dans le résultat. La description est effectuée dans l'instruction ellemême.
Dans Open Client, il est inutile de décrire les instructions. En effet, chaque
ligne renvoyée par le serveur peut comporter une description de son contenu.
Si vous utilisez ct_command et ct_send pour exécuter des instructions,
vous pouvez utiliser la fonction ct_results pour gérer tous les aspects
des lignes renvoyées par les requêtes.
Si vous ne souhaitez pas utiliser cette méthode de gestion des jeux de
résultats ligne par ligne, vous pouvez utiliser ct_dynamic pour préparer
une instruction SQL et ct_describe pour décrire son jeu de résultats.
Cela correspond de manière plus proche à la description des instructions
SQL dans d'autres interfaces.
391

Limites d’Adaptive Server Anywhere avec Open Client
Limites d’Adaptive Server Anywhere avec Open
Client
392
L’interface Open Client vous permet en grande partie d’utiliser une base de
données Adaptive Server Anywhere de la même manière qu'une base de
données Adaptive Server Enterprise. Il existe toutefois des restrictions, qui
sont résumées ci-après :
♦ Service Commit Adaptive Server Anywhere ne supporte pas le service
Commit d'Adaptive Server Enterprise.
♦ Fonctions Les fonctions associées aux connexions client/serveur
déterminent les types de requête client et de réponse serveur autorisés
pour chaque connexion. Les fonctions suivantes ne sont pas supportées :
♦ CS_REG_NOTIF
♦ CS_CSR_ABS
♦ CS_CSR_FIRST
♦ CS_CSR_LAST
♦ CS_CSR_PREV
♦ CS_CSR_REL
♦ CS_DATA_BOUNDARY
♦ CS_DATA_SENSITIVITY
♦ CS_PROTO_DYNPROC
♦ CS_REQ_BCP
♦ Les options de sécurité, comme SSL et les mots de passe cryptés, ne
sont pas supportées.
♦ Les applications Open Client peuvent se connecter à
Adaptive Server Anywhere via TCP/IP, ou en utilisant le protocole
NamedPipes de la machine locale, le cas échéant.
$ Pour plus d'informations sur les fonctions, reportez-vous au
document Open Server Server-Library C Reference Manual.

CHAPITRE 11
Transactions distribuées et architecture à
trois niveaux
Présentation
Sommaire
Ce chapitre décrit l'utilisation d'Adaptive Server Anywhere dans un
environnement d'architecture à trois niveaux avec un serveur applicatif. Il
explique notamment comment inscrire Adaptive Server Anywhere dans des
transactions distribuées.
Sujet Page
Introduction 394
Architecture informatique à trois niveaux 395
Utilisation des transactions distribuées 399
Utilisation d'EAServer avec Adaptive Server Anywhere 401
393

Introduction
Introduction
394
Vous pouvez utiliser Adaptive Server Anywhere comme serveur de base de
données ou comme gestionnaire de ressources, intervenant dans des
transactions distribuées coordonnées par un serveur de transactions.
L'architecture à trois niveaux, dans laquelle un serveur applicatif joue un rôle
d'intermédiaire entre les applications clientes et un ensemble de gestionnaires
de ressources, est un environnement de transactions distribuées courant.
Sybase EAServer et certains autres serveurs d'applications sont également
des serveurs de transactions.
Sybase EAServer et Microsoft Transaction Server utilisent le service DTC
(Distributed Transaction Coordinator) de Microsoft pour coordonner les
transactions. De son côté, Adaptive Server Anywhere supporte les
transactions distribuées contrôlées par le service DTC ; vous pouvez ainsi
l'utiliser soit avec ces serveurs d'applications, soit avec tout autre produit
basé sur le modèle DTC.
Lors de l'intégration d'Adaptive Server Anywhere dans un environnement à
trois niveaux, l'essentiel du travail doit être accompli à partir du serveur
applicatif. Ce chapitre fournit une présentation générale des concepts et de
l'architecture informatique à trois niveaux ainsi que des fonctionnalités
Adaptive Server Anywhere correspondantes. Il ne décrit pas comment
configurer votre serveur applicatif pour qu'il fonctionne avec
Adaptive Server Anywhere. Pour plus d'informations, reportez-vous à la
documentation de votre serveur applicatif.

Chapitre 11 Transactions distribuées et architecture à trois niveaux
Architecture informatique à trois niveaux
Dans l'informatique à trois niveaux, la logique de l'application est conservée
sur un serveur applicatif, tel que Sybase EAServer, qui fait le lien entre le
gestionnaire de ressources et les applications clientes. Bien souvent, un seul
serveur applicatif peut accéder à plusieurs gestionnaires de ressources. Avec
Internet, les applications clientes sont basées sur un navigateur et le serveur
applicatif est généralement une extension du serveur Web.
Serveurs
d’applications
Sybase EAServer enregistre la logique de l'application sous forme de
composants, qu'elle met à la disposition des applications clientes. Il peut
s'agir de composants PowerBuilder, JavaBeans ou COM.
$ Pour plus d'informations, reportez-vous à la documentation
Sybase EAServer.
395

Architecture informatique à trois niveaux
Transactions distribuées dans une architecture à trois niveaux
Adaptive Server
Anywhere dans les
transactions
distribuées
396
Lorsque des applications clientes ou des serveurs applicatifs utilisent une
seule base de données de traitement des transactions, telle
qu'Adaptive Server Anywhere, aucune logique transactionnelle externe à la
base n'est nécessaire ; mais s'ils utilisent plusieurs gestionnaires de
ressources, le contrôle des transactions doit couvrir les ressources impliquées
dans ces transactions. Les serveurs applicatifs peuvent eux aussi fournir la
logique de transaction à leurs applications clientes, ce qui garantit que des
ensembles d'opérations sont exécutés de façon atomique sur plusieurs bases
de données.
De nombreux serveurs de transactions, notamment Sybase EAServer,
utilisent DTC (Distributed Transaction Coordinator) de Microsoft pour
fournir les services transactionnels à leurs applications clientes. DTC utilise
des transactions OLE, qui à leur tour font appel au protocole de commit à
deux phases pour coordonner les transactions mettant en oeuvre plusieurs
gestionnaires de ressources. DTC doit être installé pour utiliser les
fonctionnalités décrites dans ce chapitre.
Adaptive Server Anywhere peut intervenir dans des transactions
coordonnées par DTC ; en d'autres termes, vous pouvez utiliser des bases de
données Adaptive Server Anywhere dans des transactions distribuées en
utilisant un serveur de transactions tel que Sybase EAServer ou
Microsoft Transaction Server. Vous pouvez aussi utiliser DTC directement
dans vos applications pour coordonner des transactions entre plusieurs
gestionnaires de ressources.
Terminologie relative aux transactions distribuées
Il est supposé dans ce chapitre que vous avez une certaine connaissance des
transactions distribuées. Pour plus d'informations, reportez-vous à la
documentation de votre serveur de transactions. Cette section présente les
termes et expressions fréquemment employés.
♦ Les gestionnaires de ressources sont les services qui gèrent les données
impliquées dans la transaction.
Lorsque l'accès au serveur de base de données
Adaptive Server Anywhere s'effectue par le biais d'ODBC ou
d'OLE DB, celui-ci peut jouer le rôle de gestionnaire de ressources dans
une transaction distribuée. Le pilote ODBC et le fournisseur OLE DB se
comportent comme des proxies du gestionnaire de ressources sur la
machine cliente.

Commit à deux
phases
Chapitre 11 Transactions distribuées et architecture à trois niveaux
♦ Au lieu de communiquer directement avec le gestionnaire de ressources,
les composants applicatifs peuvent communiquer avec des distributeurs
de ressources, qui à leur tour gèrent les connexions ou les zones de
connexions aux gestionnaires de ressources.
Adaptive Server Anywhere supporte deux distributeurs de ressources : le
gestionnaire de pilotes ODBC et OLE DB.
♦ Lorsqu'un composant transactionnel demande une connexion à la base
de données (via un gestionnaire de ressources), le serveur applicatif
inscrit chaque connexion qui prend part à la transaction. DTC et le
distributeur de ressources effectuent le processus d'inscription.
Les transactions distribuées sont gérées par le biais d'un commit à deux
phases. Lorsqu'une transaction est terminée, le gestionnaire de transactions
(DTC) demande à tous les gestionnaires de ressources inscrits dans la
transaction s'ils sont prêts à la valider. Cette phase correspond à la
préparation du commit.
Si tous les gestionnaires de ressources répondent qu'ils sont prêts, DTC
envoie une demande de validation à chacun et informe son client que la
transaction est terminée. Si un ou plusieurs gestionnaires de ressources ne
répondent pas ou ne sont pas prêts, tout le travail de la transaction est annulé
au niveau de tous les gestionnaires de ressources.
Utilisation de DTC par les serveurs d’applications
Sybase EAServer et Microsoft Transaction Server sont tous deux des
serveurs de composants. La logique applicative est enregistrée sous forme de
composants et mise à la disposition des applications clientes.
Chaque composant possède un attribut de transaction qui indique la manière
dont il prend part aux transactions. Le développeur d'applications qui crée le
composant doit programmer dans ce dernier les tâches qu'exécutera la
transaction, à savoir les connexions au gestionnaire de ressources et les
opérations sur les données dont le gestionnaire de ressources a la charge.
Toutefois, il n'est pas nécessaire d'y ajouter la logique de gestion des
transactions. Une fois que l'attribut de transaction défini indique que le
composant a besoin d'une gestion de transaction, EAServer utilise DTC pour
inscrire la transaction et gérer le processus de commit à deux phases.
Architecture des transactions distribuées
Le schéma suivant illustre l'architecture de transactions distribuées. Dans ce
cas, le proxy du gestionnaire de ressources est indifféremment ODBC ou
OLE DB.
397

Architecture informatique à trois niveaux
398
Système
client
Proxy du
gestionnaire
de
ressources
DTC
Serveur
système 1
Serveur
d’applications
DTC
DTC
Serveur
système 2
Proxy du
gestionnaire
de
ressources
Dans cet exemple, un distributeur de ressources est utilisé. Le serveur
applicatif demande au service DTC de préparer une transaction. DTC et le
distributeur inscrivent chaque connexion figurant dans la transaction. Chaque
gestionnaire de ressources doit être en contact avec DTC et avec la base de
données afin d'exécuter le travail et, au moment requis, d'informer DTC du
statut de la transaction.
Pour permettre le traitement des transactions distribuées, un service DTC
doit être actif sur chaque machine. Vous contrôlez les services DTC depuis
l'icône Services dans le panneau de configuration de Windows ; le service
DTC s'appelle MSDTC.
$ Pour plus d'informations, reportez-vous à la documentation de DTC ou
d'EAServer.

Chapitre 11 Transactions distribuées et architecture à trois niveaux
Utilisation des transactions distribuées
Niveaux d’isolement DTC
Lorsque Adaptive Server Anywhere est inscrit dans une transaction
distribuée, il transmet le contrôle de la transaction au serveur de transactions
et s'assure qu'il n'effectue pas une gestion implicite de la transaction. Les
conditions suivantes sont automatiquement imposées par
Adaptive Server Anywhere lorsqu'il intervient dans des transactions
distribuées :
♦ L'autocommit est automatiquement désactivé.
♦ Les instructions de définition de données (qui ont pour effet d'exécuter
un commit) sont interdites pendant le déroulement des transactions
distribuées.
♦ Une instruction explicite COMMIT ou ROLLBACK adressée par
l'application à Adaptive Server Anywhere directement, et non par le
biais du coordinateur de transactions, génère une erreur. Toutefois, la
transaction n'est pas abandonnée.
♦ Une connexion ne peut participer qu'à une seule transaction distribuée à
la fois.
♦ Aucune opération non validée ne doit avoir lieu au moment où la
connexion est inscrite dans une transaction distribuée.
DTC possède un ensemble de niveaux d'isolement, spécifiés par le serveur
applicatif. Ces niveaux d'isolement sont mis en correspondance avec les
niveaux d'isolement d'Adaptive Server Anywhere comme suit :
Niveau d’isolement DTC Niveau d’isolement
Adaptive Server
Anywhere
ISOLATIONLEVEL_UNSPECIFIED 0
ISOLATIONLEVEL_CHAOS 0
ISOLATIONLEVEL_READUNCOMMITTED 0
ISOLATIONLEVEL_BROWSE 0
399

Utilisation des transactions distribuées
400
Niveau d’isolement DTC Niveau d’isolement
Adaptive Server
Anywhere
ISOLATIONLEVEL_CURSORSTABILITY 1
ISOLATIONLEVEL_READCOMMITTED 1
ISOLATIONLEVEL_REPEATABLEREAD 2
ISOLATIONLEVEL_SERIALIZABLE 3
ISOLATIONLEVEL_ISOLATED 3
Reprise à partir de transactions distribuées
Si le serveur de base de données tombe en panne tandis que des opérations
non validées sont en attente, il doit soit les annuler, soit les valider au
moment du démarrage, afin de préserver la nature atomique de la transaction.
Si des opérations non validées issues d'une transaction distribuée sont
détectées durant une reprise, le serveur de base de données tente de se
connecter à DTC et demande à être réinscrit dans les transactions en attente
ou pour lesquelles un doute subsiste. Une fois la réinscription terminée, DTC
ordonne au serveur de base de données d'annuler ou de valider les opérations
restantes.
Si la réinscription échoue, Adaptive Server Anywhere n'a aucun moyen de
savoir si les opérations sujettes à caution doivent être validées ou annulées, et
la reprise échoue. Toutefois, si vous tenez à effectuer une reprise de cette
base, malgré l'état incertain de ses données, vous pouvez l'imposer en
utilisant les options suivantes du serveur de base de données :
♦ -tmf Si DTC est introuvable, les opérations restantes sont annulées et la
reprise se poursuit.
$ Pour plus d'informations, reportez-vous à la section "Option de
serveur -tmf", page 164 du document ASA Guide d’administration.
♦ -tmt Si la réinscription n'est pas terminée avant le moment spécifié, les
opérations restantes sont annulées et la reprise se poursuit.
$ Pour plus d'informations, reportez-vous à la section "Option de
serveur -tmt", page 163 du document ASA Guide d’administration.

Chapitre 11 Transactions distribuées et architecture à trois niveaux
Utilisation d’EAServer avec Adaptive Server
Anywhere
Configuration d’EAServer
Cette section présente les opérations à effectuer dans EAServer version 3.0
ou ultérieures pour qu'il fonctionne avec Adaptive Server Anywhere. Pour
plus d'informations, reportez-vous à la documentation d'EAServer.
Tous les composants installés dans Sybase EAServer partagent le même
coordinateur de transactions.
EAServer 3.0 (et versions ultérieures) propose plusieurs coordinateurs de
transactions. Vous devez utiliser DTC comme coordinateur si vous incluez
Adaptive Server Anywhere dans les transactions. Cette section explique
comment configurer EAServer 3.0 pour utiliser DTC comme coordinateur de
transactions.
Le serveur de composants dans EAServer s'appelle Jaguar.
v Pour configurer un serveur EAServer en vue d'utiliser le modèle
transactionnel DTC de Microsoft :
1 Vérifiez que le serveur Jaguar est actif.
Sous Windows, le serveur Jaguar est généralement utilisé en tant que
service. Pour démarrer manuellement le serveur Jaguar installé, fourni
avec EAServer 3.0, sélectionnez
Démarrer➤Programmes➤Sybase➤EAServer➤EAServer.
2 Démarrez Jaguar Manager.
A partir du bureau Windows, sélectionnez
Démarrer➤Programmes➤Sybase➤EAServer➤Jaguar Manager.
3 Connectez-vous au serveur Jaguar à partir de Jaguar Manager.
Dans le menu Sybase Central, choisissez Outils➤Connexion➤Jaguar
Manager. Dans la boîte de dialogue de connexion, entrez jagadmin
comme nom d'utilisateur, laissez le champ Mot de passe vide et indiquez
localhost comme nom d'hôte. Cliquez sur OK pour vous connecter.
4 Définissez le modèle transactionnel pour le serveur Jaguar.
401

Utilisation d’EAServer avec Adaptive Server Anywhere
402
Dans le volet gauche, ouvrez le dossier Serveurs. Dans le volet droit,
cliquez avec le bouton droit sur le serveur que vous voulez configurer,
puis sélectionnez Propriétés serveur dans le menu contextuel. Cliquez
sur l'onglet Transactions et choisissez Microsoft DTC comme modèle.
Cliquez sur OK pour terminer.
Définition de l'attribut de transaction du composant
Dans EAServer, vous pouvez mettre en oeuvre un composant qui exécute des
opérations sur plusieurs bases de données. Vous affectez à ce composant un
attribut de transaction qui définit son mode de participation dans les
transactions. L'attribut de transaction peut prendre les valeurs suivantes :
♦ Not Supported Les méthodes du composant ne s'exécutent jamais en
tant qu'élément d'une transaction. Si le composant est activé par un autre
composant qui s'exécute dans une transaction, les tâches de la nouvelle
instance sont effectuées hors de la transaction existante. Il s'agit de la
valeur par défaut.
♦ Supports Transaction Le composant peut s'exécuter dans le contexte
d'une transaction mais aucune connexion n'est requise pour l'exécution
de ses méthodes. Si le composant est instancié directement par un client
de base, EAServer ne démarre pas de transaction. Ainsi, si le composant
A est instancié par le composant B et si B s'exécute dans une transaction,
A s'exécute dans la même transaction.
♦ Requires Transaction Le composant s'exécute toujours dans une
transaction. Lorsqu'il est instancié directement par un client de base, une
nouvelle transaction commence. Ainsi, si le composant A est activé par
le composant B et si B s'exécute dans une transaction, A s'exécutera
dans la même transaction ; si B ne s'exécute pas dans une transaction, A
s'exécutera dans une nouvelle transaction.
♦ Requires New Transaction Chaque fois que le composant est instancié,
une nouvelle transaction commence. Si le composant A est activé par le
composant B et si B s'exécute dans une transaction, A commence une
nouvelle transaction qui n'est pas touchée par les résultats de la
transaction de B ; si B ne s'exécute pas dans une transaction, A s'exécute
dans une nouvelle transaction.
Ainsi, dans l'exemple d'application Virtual University de Sybase, fourni avec
EAServer sous le nom de package SVU, la méthode enroll() du composant
SVUEnrollment exécute deux opérations distinctes (réservation d'une place
à une conférence, facturation de la conférence à l'étudiant). Ces deux
opérations doivent être traitées comme une transaction unique.

Chapitre 11 Transactions distribuées et architecture à trois niveaux
Microsoft Transaction Server propose le même ensemble de valeurs
d'attribut.
v Pour définir l'attribut de transaction d'un composant :
1 Dans Jaguar Manager, localisez le composant.
Pour localiser le composant SVUEnrollment dans l’exemple
d’application Jaguar, connectez-vous au serveur Jaguar, ouvrez le dossier
Packages, puis le package SVU. La liste des composants du package
s’affiche dans le volet droit.
2 Définissez l'attribut de transaction pour le composant choisi.
Cliquez sur le composant avec le bouton droit de la souris, puis
sélectionnez Component Properties dans le menu contextuel. Cliquez sur
l'onglet Transaction et choisissez dans la liste la valeur de l'attribut de
transaction. Cliquez sur OK pour terminer.
Le composant SVUEnrollment possède déjà l'attribut Requires
Transaction.
Une fois l'attribut de transaction du composant défini, vous pouvez effectuer
des opérations Adaptive Server Anywhere à partir de ce composant, en étant
assuré que le traitement de la transaction se déroule au niveau spécifié.
403

Utilisation d’EAServer avec Adaptive Server Anywhere
404

CHAPITRE 12
Déploiement de bases de données et
d'applications
Présentation
Sommaire
Ce chapitre explique comment déployer les composants d'Adaptive Server
Anywhere. Il identifie les fichiers requis pour le déploiement et traite des
procédures connexes, telles que le paramétrage des connexions.
Vérifiez votre contrat de licence
La redistribution des fichiers est soumise à votre contrat de licence.
Aucune instruction de ce document ne prime sur une clause quelconque
de votre contrat de licence. Veuillez consulter votre contrat de licence
avant d'envisager le déploiement d'applications.
Sujet Page
Présentation du déploiement 406
Répertoires d'installation et noms de fichiers 409
Utilisation des objets et modèles InstallShield pour le déploiement 414
Déploiement avec une installation silencieuse 416
Déploiement des applications clientes 420
Déploiement des outils d'administration 431
Déploiement des serveurs de base de données 432
Déploiement d'applications de base de données embarquées 435
405

Présentation du déploiement
Présentation du déploiement
Modèles de déploiement
406
Lorsque vous avez terminé une application de base de données, vous devez
la déployer afin qu'elle soit accessible aux utilisateurs. Selon la manière dont
votre application utilise Adaptive Server Anywhere (comme base de données
embarquée, en mode client/serveur, etc.), vous devrez peut-être déployer en
même temps certains composants du logiciel Adaptive Server Anywhere. Il
peut être également nécessaire de déployer des informations de
configuration, par exemple les noms des sources de données, qui permettront
à l'application de communiquer avec Adaptive Server Anywhere.
Vérifiez votre contrat de licence
La redistribution de fichiers est soumise à votre contrat de licence avec
Sybase. Aucune instruction de ce document ne prime sur une clause
quelconque de votre contrat de licence. Veuillez consulter votre contrat de
licence avant d'envisager le déploiement d'applications.
Voici les étapes de déploiement traitées dans ce chapitre :
♦ Détermination des fichiers requis en fonction du choix de la plate-forme
et de l'architecture des applications.
♦ Configuration des applications clientes.
Ce chapitre traite essentiellement des fichiers individuels et de leur
emplacement. Toutefois, le mode conseillé pour déployer les composants
d'Adaptive Server Anywhere est l'utilisation des objets InstallShield ou
l'installation silencieuse. Pour plus d'informations, reportez-vous aux
sections "Utilisation des objets et modèles InstallShield pour le
déploiement", page 414 et "Déploiement avec une installation silencieuse",
page 416.
Les fichiers qu'il convient de déployer dépendent du modèle de déploiement
choisi. Voici quelques modèles possibles :
♦ Déploiement client Vous pouvez ne déployer que la partie cliente
d'Adaptive Server Anywhere vers les utilisateurs finals, de sorte qu'ils
puissent se connecter à un serveur de base de données sur un réseau
central.
♦ Déploiement serveur de réseau Vous pouvez déployer les serveurs de
réseau vers des bureaux, puis déployer les clients vers chaque utilisateur
de ces bureaux.

Modes de distribution des fichiers
Chapitre 12 Déploiement de bases de données et d'applications
♦ Déploiement de base de données embarquée Vous pouvez déployer
une application exécutée via un serveur de base de données personnel.
Dans ce cas, les serveurs client et personnel doivent tous deux être
installés sur la machine de l'utilisateur final.
♦ Déploiement SQL Remote Déployer une application SQL Remote est
une extension du modèle de déploiement de base de données embarquée.
♦ Déploiement d'outils de base de données Vous pouvez déployer
Interactive SQL, Sybase Central et d'autres outils de gestion.
Pour déployer Adaptive Server Anywhere, vous avez le choix entre :
♦ Utiliser l’installation d’Adaptive Server Anywhere Vous pouvez
mettre le programme de configuration à disposition des utilisateurs
finals. En sélectionnant ensuite l'option appropriée, chaque utilisateur
final est assuré de recevoir les fichiers dont il a besoin.
Cette solution est souvent la plus simple. Si vous l'adoptez, vous devez
néanmoins fournir aux utilisateurs finals une méthode de connexion au
serveur de base de données (source de données ODBC, par exemple).
$ Pour plus d'informations, reportez-vous à la section "Déploiement
avec une installation silencieuse", page 416.
♦ Développer votre propre installation Vous pouvez, pour diverses
raisons, souhaiter développer votre propre programme d'installation qui
intègre les fichiers d'Adaptive Server Anywhere. C'est cette solution,
nettement plus complexe, qui fait l'objet essentiel de ce chapitre.
Si Adaptive Server Anywhere est déjà installé pour le type de serveur et
le système d'exploitation requis par l'architecture de l'application cliente,
les fichiers requis se trouvent dans le sous-répertoire approprié du
répertoire d'installation d'Adaptive Server Anywhere.
Par exemple, si vous avez choisi le répertoire d'installation par défaut, le
sous-répertoire win32 de ce répertoire contient les fichiers requis pour
exécuter le serveur sur les systèmes d'exploitaiton Windows.
Par ailleurs, les utilisateurs d'InstallShield Professional 5.5 et versions
supérieures peuvent utiliser SQL Anywhere Studio InstallShield
Template Projects pour déployer leur propre application. Grâce à cette
fonctionnalité, vous avez la possibilité de créer rapidement l'installation
de votre application en utilisant le projet de modèles complet ou
uniquement les éléments applicables à votre programme d'installation.
407

Présentation du déploiement
408
Quelle que soit l'option choisie, veillez à ne pas violer les termes de votre
contrat de licence.

Chapitre 12 Déploiement de bases de données et d'applications
Répertoires d'installation et noms de fichiers
Pour qu'une application déployée fonctionne correctement, le serveur de base
de données et les bibliothèques clientes doivent pouvoir localiser les fichiers
dont ils ont besoin. Les fichiers déployés doivent se trouver en relation les
uns avec les autres, de la même manière que dans votre installation Adaptive
Server Anywhere.
Dans la pratique, cela signifie que, sur un PC, la plupart des fichiers se
trouvent dans un seul répertoire. Par exemple, sous Windows, les fichiers
nécessaires pour le client et le serveur de base de données sont installés dans
un seul répertoire, qui est le sous-répertoire win32 du répertoire d'installation
d'Adaptive Server Anywhere.
$ Pour plus de précisions sur les emplacements où le logiciel recherche
les fichiers, reportez-vous à la section "Recherche de fichiers dans Adaptive
Server Anywhere", page 222 du document ASA Guide d’administration.
Remarques sur le déploiement UNIX
Les déploiements sous UNIX diffèrent quelque peu des déploiements sur
PC :
♦ Structure de répertoires Pour les installations UNIX, la structure de
répertoires est la suivante :
Directory Sommaire
/opt/sybase/SYBSsa8/bin Fichiers exécutables
/opt/sybase/SYBSsa8/lib Objets et bibliothèques partagés
/opt/sybase/SYBSsa8/res Fichiers chaîne
Sous AIX, le répertoire racine par défaut est /usr/lpp/sybase/SYBSsa8 et
non /opt/sybase/SYBSsa8.
♦ Extensions de fichiers Dans les tableaux de ce chapitre, les objets
partagés sont répertoriés avec l'extension .so. Pour HP-UX, l'extension
est .sl.
Sous le système d'exploitation AIX, les objets partagés auxquels les
applications doivent être liées sont dotés de l'extension .a.
♦ Liens symboliques Chaque objet partagé est installé comme lien
symbolique à un fichier portant le même nom avec l'extension
complémentaire .1 (un). Par exemple, libdblib8.so est un lien symbolique
au fichier libdblib8.so.1 dans le même répertoire.
409

Répertoires d'installation et noms de fichiers
410
Si l’installation d’Adaptive Server Anywhere requiert des patchs, ceux-ci
sont fournis avec l’extension .2, et le lien symbolique doit être acheminé
à nouveau.
♦ Applications utilisant ou non les threads natifs La plupart des objets
partagés sont fournis sous deux formes, l'une ayant les caractères _r
précédant l'extension de fichier. Par exemple, outre libdblib8.so, il existe
un fichier appelé libdblib8_r.so. Dans ce cas, les applications utilisant les
threads natifs doivent être liées à l'objet partagé dont le nom
comporte _r, tandis que les applications ne les utilisant pas doivent être
liées à l'objet partagé dont le nom ne comporte pas _r.
♦ Conversion des jeux de caractère Vous devez intégrer les fichiers
suivants si vous souhaitez utiliser la conversion des jeux de caractère de
serveur de base de données (l'option de serveur -ct):
♦ libunic.so
♦ charsets/ sous-arborescence du répertoire
♦ asa.cvf
$ Pour plus de précisions sur les emplacements où le logiciel recherche
les fichiers, reportez-vous à la section "Recherche de fichiers dans Adaptive
Server Anywhere", page 222 du document ASA Guide d’administration.
Conventions de dénomination des fichiers
Adaptive Server Anywhere adopte un système de dénomination cohérent de
façon à faciliter l'identification et le regroupement des composants du
système.
Ces conventions sont les suivantes :
♦ Numéro de version Le numéro de version d'Adaptive Server Anywhere
est indiqué dans le nom de fichier des composants du serveur principal
(fichiers .exe et .dll).
Par exemple, le fichier dbeng8.exe est un fichier exécutable de la
version 8.
♦ Langue La langue utilisée dans une bibliothèque de ressources de
langue est indiquée par un code de deux lettres dans son nom de fichier.
La langue de cette bibliothèque est indiquée par les deux caractères
précédant le numéro de version. Par exemple, dblgen8.dll est la
bibliothèque de ressources de langue pour l'anglais. Ces codes sont
spécifiés par la norme ISO 639.

Identification
d’autres types de
fichiers
Chapitre 12 Déploiement de bases de données et d'applications
$ Pour plus d'informations sur les libellés de langue, reportez-vous à
la section "La langue de localisation", page 280 du document ASA Guide
d’administration.
Vous pouvez transférer gratuitement depuis le site Web de Sybase un kit
international de déploiement de ressources contenant des DLL de
déploiement de ressources de langue.
v Pour transférer le kit international de déploiement de ressources
depuis le site Web de Sybase :
1 Connectez-vous à l'URL suivante à partir de votre navigateur :
http://www.sybase.com/products/anywhere/
2 Cliquez sur Downloads, situé sous l'en-tête SQL Anywhere Studio sur la
gauche de la page.
3 Cliquez sur An assortment of Emergency Bug Fixes and Updates for
SQL Anywhere Studio, sous l'en-tête Emergency Bug Fix/Updates.
4 Connectez-vous à votre compte Web Sybase.
Si vous ne disposez pas encore d'un compte Web Sybase, cliquez sur
Create a New Account pour en créer un.
5 Dans la liste des éléments disponibles, sélectionnez le kit international
de déploiement de ressources (International Resources Deployment Kit)
correspondant à la plate-forme et à la version d'Adaptive Server
Anywhere que vous utilisez.
$ Pour obtenir la liste des langues disponibles dans Adaptive Server
Anywhere, reportez-vous à la section "Classements fournis", page 286 du
document ASA Guide d’administration.
Le tableau suivant indique la plate-forme et la fonction des fichiers
d'Adaptive Server Anywhere selon leur extension de fichier. Adaptive Server
Anywhere respecte, chaque fois que possible, les conventions d'extension de
fichier standard.
411

Répertoires d'installation et noms de fichiers
Nom des fichiers
de base de
données
412
Extension de
fichier
Plate-forme Type de fichier
.nlm Novell NetWare Module chargeable
NetWare
.cnt, .ftg, .fts,
.gid, .hlp, .chm,
.chw
Windows Fichier d'aide système
.lib Dépend de l'outil de
développement
.cfg, .cpr, .dat,
.loc, .spr, .srt,
.xlt
Bibliothèques d'exécution
statiques pour la création
d'exécutables
Embedded SQL
Windows Composants de Sybase
Adaptive Server Enterprise
.cmd .bat Windows Fichiers de commandes
.res NetWare, UNIX Fichier de ressources de
langue pour les
environnements non-
Windows
.dll Windows Bibliothèque DLL
(Dynamic Link Library)
.so .sl .a UNIX Fichier d'objet partagé (Sun
Solaris et IBM AIX) ou de
bibliothèque partagée (HP-
UX). Equivalent d'un DLL
sur les plates-formes PC.
Les bases de données d'Adaptive Server Anywhere sont constituées de deux
éléments :
♦ Fichier de base de données Ce fichier contient les informations dans
un format structuré. Il est doté d'une extension .db.
♦ Fichier du journal de transactions Ce fichier enregistre toutes les
modifications des données contenues dans le fichier de base de données.
Il est doté de l'extension .log et généré par Adaptive Server Anywhere si
un tel fichier n'existe pas et qu'un fichier journal doit être utilisé. Un
journal de transactions en miroir est suivi de l'extension par défaut .mlg.
♦ Fichier d'écriture Si votre application en utilise un, il est généralement
doté de l'extension .wrt.
♦ Fichier de base de données compacté Si vous fournissez un fichier de
base de données compacté, il porte généralement l'extension .cdb.

Chapitre 12 Déploiement de bases de données et d'applications
Ces fichiers sont mis à jour, maintenus et gérés par le système de gestion de
bases de données relationnel (SGBDR) Adaptive Server Anywhere.
413

Utilisation des objets et modèles InstallShield pour le déploiement
Utilisation des objets et modèles InstallShield
pour le déploiement
414
Si vous utilisez InstallShield 6 ou une version supérieure, vous pouvez
inclure des objets InstallShield de SQL Anywhere Studio dans votre
programme d'installation. Les objets permettant de déployer des clients, des
serveurs de base de données personnels, des serveurs de réseau et des outils
d'administration se trouvent dans le sous-répertoire deployment\Object du
répertoire SQL Anywhere.
Les utilisateurs d'InstallShield Professional version 5.5 et ultérieures peuvent
utiliser les projets modèles InstallShield de SQL Anywhere Studio pour
faciliter le déploiement. Vous trouverez des modèles pour le déploiement
d'un serveur réseau, d'un serveur personnel, d'interfaces clientes et d'outils
d'administration dans le sous-répertoire SQL Anywhere
8\deployment\Templates.
Si vous disposez de la version 6 ou d'une version ultérieure d'InstallShield, il
est conseillé d'en utiliser les objets plutôt que les modèles, car ils s'intègrent
plus facilement aux autres composants d'une installation.
v Pour ajouter un projet de modèle dans votre InstallShield IDE :
1 Démarrez InstallShield IDE.
2 Choisissez Fichier➤Ouvrir.
3 Accédez à votre installation SQL Anywhere 8 et au dossier de
déploiement.
Par exemple :
C:\Program Files\Sybase\SQL Anywhere 8\deployment
4 Ouvrez le dossier de modèles correspondant au type d'objet à déployer.
Vous avez le choix entre NetworkServer, PersonalServer, Client et
JavaTools.
5 Sélectionnez le fichier ayant l'extension .ipr.
Le projet s'ouvre dans InstallShield IDE. Le volet Projects affiche une
icône pour le modèle.
Les modèles seront modifiés au moment de l'installation de sorte que les
chemins d'accès aux différents fichiers répertoriés dans les fichiers .fgl
pointent sur le programme d'installation courant d'ASA. Il suffit de
charger le modèle dans InstallShield IDE, de créer le support et le
modèle s'exécute immédiatement.

Remarques :
Chapitre 12 Déploiement de bases de données et d'applications
Lors de la création du support, des avertissements sur des groupes de
fichiers vides s'affichent. Ces groupes ont été ajoutés dans les modèles
comme marques de réservation pour les fichiers de votre application.
Pour supprimer ces avertissements, ajoutez les fichiers de votre
application dans les groupes de fichiers, ou bien supprimez ou
renommez ces groupes.
415

Déploiement avec une installation silencieuse
Déploiement avec une installation silencieuse
416
Les installations silencieuses ne nécessitent aucun intervention de l'utilisateur
et pendant qu'elles se déroulent, aucune indication n'est fournie à l'utilisateur.
Sous les systèmes d'exploitation Windows, vous pouvez appeler le
programme InstallShield d'Adaptive Server Anywhere à partir de votre
programme Setup afin que l'installation d'Anywhere se déroule en mode
silencieux. Ce type d'installation est également possible avec SMS (Systems
Management Server) de Microsoft (voir "Installation SMS", page 418).
Vous pouvez utiliser le mode d'installation silencieuse pour tous les modèles
de déploiement décrits dans la section "Modèles de déploiement", page 406.
Vous pouvez également vous en servir pour déployer des serveurs de
synchronisation MobiLink.
Création d'un programme d'installation silencieuse
Les options d'installation utilisées en mode silencieux sont fournies par un
fichier de réponse. Ce fichier est créé lors de l'exécution du programme
setup d'Adaptive Server Anywhere avec l'option de commande –r. Vous
effectuez un programme d'installation silencieuse en exécutant setup avec
l'option de ligne de commande –s.
N’utilisez pas le bouton Parcourir
Lors de la création d'un programme d'installation silencieuse, n'utilisez
pas le bouton Parcourir. En effet, l'enregistrement de ce bouton n'est pas
fiable.
v Pour créer un programme d'installation silencieuse :
1 Supprimez les installations existantes d’Adaptive Server Anywhere
(facultatif).
2 Ouvrez une fenêtre de commandes système et accédez au répertoire
contenant l'image d'installation (comprenant setup.exe, setup.ins, etc.).
3 Installez le logiciel en mode Record.
Entrez la commande suivante :
setup –s

Chapitre 12 Déploiement de bases de données et d'applications
Cette commande exécute le programme d'installation d'Adaptive Server
Anywhere et crée le fichier de réponses à partir des sélections
effectuées. Le fichier de réponses s'appelle setup.iss et il se trouve dans
votre répertoire Windows. Ce fichier contient les réponses que vous avez
fournies dans les boîtes de dialogue lors de l'installation.
En mode Enregistrement (record), le programme d'installation ne vous
invite pas à redémarrer le système, même si l'opération est nécessaire.
4 Installez Adaptive Server Anywhere avec les options et les paramètres à
utiliser pour le déploiement d'Adaptive Server Anywhere sur la machine
de l'utilisateur final, qui exécutera votre application. Vous pouvez
modifier les chemins durant l'installation silencieuse.
Exécution d'une installation silencieuse
Votre programme d’installation doit appeler celui d’installation silencieuse
d’Adaptive Server Anywhere au moyen de l’option de ligne de commande –
s. Cette section décrit comment utiliser un programme d'installation
silencieuse.
v Pour utiliser un programme d’installation silencieuse :
1 Ajoutez la commande destinée à appeler le programme d'installation
silencieuse d'Adaptive Server Anywhere pour votre procédure.
Si le fichier de réponses se trouve dans le répertoire image du
programme d'installation, vous pouvez exécuter celui-ci en tapant la
commande ci-après dans le répertoire où se trouve l'image :
setup –s
Si le fichier de réponses se trouve ailleurs, spécifiez l'emplacement
adéquat avec l'option –f1. L’option f1 et les guillemets ne doivent être
séparés par aucun espace sur la ligne de commande.
setup –s –f1"c:\winnt\setup.iss"
Pour appeler le programme d'installation à partir d'un autre script
InstallShield, vous pouvez aussi entrer la commande ci-après :
DoInstall( "chemin_image_install_ASA\SETUP.INS",
"-s", WAIT );
Des options de ligne de commande permettent de remplacer les chemins
tant pour le répertoire d'Adaptive Server Anywhere que pour le
répertoire partagé.
setup TARGET_DIR=dirname SHARED_DIR=shared_dir –s
417

Déploiement avec une installation silencieuse
Installation SMS
418
Les arguments TARGET_DIR et SHARED_DIR doivent précéder les
autres options.
2 Vérifiez si l'ordinateur destinataire doit être redémarré ou non.
Le programme d'installation crée un fichier nommé silent.log dans le
répertoire cible. Il contient une section appelée ResponseResult, qui
inclut la ligne suivante :
Reboot=valeur
Cette ligne indique si l'ordinateur destinataire doit être redémarré pour
que l'installation soit terminée ; elle prend la valeur 0 ou 1, selon le cas.
♦ Reboot=0 Redémarrage inutile
♦ Reboot=1 L'indicateur BATCH_INSTALL a été défini durant
l'installation et l'ordinateur destinataire doit être redémarré. La
procédure qui a appelé le programme d'installation silencieux doit
vérifier l'entrée Reboot et redémarrer, si nécessaire, l'ordinateur
destinataire.
3 Vérifiez que l'exécution du programme Setup s'est correctement
déroulée.
Setup crée un fichier nommé setup.log dans le répertoire contenant le
fichier de réponses. Le journal de transactions inclut un rapport sur le
programme d'installation silencieuse. La dernière section de ce fichier,
intitulée ResponseResult, comporte la ligne suivante :
ResultCode=valeur
Cette ligne indique si l'installation s'est correctement terminée. Si la
valeur de ResultCode est différente de zéro, cela signifie qu'une erreur
s'est produite. Pour obtenir une description des codes d'erreur, reportezvous
à la documentation de votre InstallShield.
SMS (System Management Server) de Microsoft utilise un programme
d'installation silencieuse qui ne redémarre pas l'ordinateur cible. Celui
d'Adaptive Server Anywhere ne redémarre pas l'ordinateur.
Votre package SMS doit contenir le fichier de réponses, l'image du
programme d'installation et le fichier de définition du package asa8.pdf (qui
se trouve sur le CD-ROM d'Adaptive Server Anywhere, dans le répertoire
\extras). La commande du Setup dans le fichier PDF contient les options
suivantes :

Chapitre 12 Déploiement de bases de données et d'applications
♦ Option –s pour une installation silencieuse
♦ Option –SMS pour indiquer l’utilisation de SMS
♦ Option –m pour générer un fichier MIF. Le fichier MIF est utilisé par
SMS pour déterminer si l'installation a réussi.
419

Déploiement des applications clientes
Déploiement des applications clientes
420
Pour déployer une application cliente exécutée sur un serveur de base de
données réseau, vous devez fournir à chaque utilisateur final :
♦ Application cliente Le logiciel de l'application est indépendant du
logiciel de base de données, aussi nous ne le décrirons pas.
♦ Fichiers de l'interface de base de données L’application cliente doit
disposer des fichiers requis par l'interface de base de données qu'elle
utilise (ODBC, JDBC, Embedded SQL ou Open Client).
♦ Informations de connexion Chaque application cliente doit disposer
des informations de connexion à la base de données.
Les fichiers d'interface et les informations de connexion requis dépendent de
l'interface utilisée par l'application. Les sections qui suivent traitent des
différentes interfaces.
Le moyen le plus simple pour déployer des applications clientes consiste à
utiliser les objets InstallShield fournis. Pour plus d'informations, reportezvous
à la section "Utilisation des objets et modèles InstallShield pour le
déploiement", page 414.
Déploiement de clients OLE DB et ADO
Le moyen le plus simple pour déployer des bibliothèques clientes OLE DB
consiste à utiliser les objets ou modèles InstallShield. Pour plus
d'informations, reportez-vous à la section "Utilisation des objets et modèles
InstallShield pour le déploiement", page 414. Si vous voulez créer votre
propre installation, cette section décrit les fichiers à déployer pour les
utilisateurs finaux.
Chaque machine cliente OLE DB doit disposer des éléments suivants :
♦ Une installation OLE DB en état de marche Les fichiers et instructions
OLE DB sont disponibles pour redistribution, auprès de Microsoft
Corporation. Ils ne sont pas décrits en détail ici.
♦ Le fournisseur OLE DB d’Adaptive Server Anywhere Le tableau
suivant répertorie les fichiers nécessaires au fonctionnement d'un
fournisseur OLE DB pour Adaptive Server Anywhere. Ces fichiers
doivent être placés dans un seul répertoire. L'installation d'Adaptive
Server Anywhere les place tous dans le sous-répertoire du système
d'exploitation du répertoire d'installation SQL Anywhere ; par exemple :
win32.

Chapitre 12 Déploiement de bases de données et d'applications
Description Windows Windows CE
Pilote OLE DB dboledb8.dll dboledb8.dll
Pilote OLE DB dboledba8.dll dboledba8.dll
Bibliothèque de ressources dblgen8.dll dblgen8.dll
de langue
Boîte de dialogue
Connexion
Déploiement de clients ODBC
dbcon8.dll sans objet
Les fournisseurs OLE DB nécessitent de nombreuses entrées dans le
registre. Vous pouvez créer ces entrées en auto-enregistrant les DLL au
moyen soit de l'utilitaire regsvr32 sous Windows, soit de l'utilitaire
regsvrce sous Windows CE.
$ Pour plus d'informations, reportez-vous aux sections "Création de
bases de données pour Windows CE", page 291 du document ASA
Guide d’administration et "Liaison d'applications ODBC sous
Windows CE", page 279.
Le moyen le plus simple pour déployer des clients ODBC consiste à utiliser
les objets ou modèles InstallShield. Pour plus d'informations, reportez-vous à
la section "Utilisation des objets et modèles InstallShield pour le
déploiement", page 414.
Chaque machine cliente ODBC doit disposer de :
♦ Une installation ODBC en état de marche Les fichiers et instructions
ODBC sont disponibles pour redistribution auprès de Microsoft
Corporation. Ils ne sont pas décrits en détail ici.
Microsoft fournit le gestionnaire de pilote ODBC pour les systèmes
d'exploitation Windows. SQL Anywhere Studio comprend un
gestionnaire de pilote ODBC pour UNIX. Il n'existe aucun gestionnaire
de pilote ODBC pour Windows CE.
Les applications ODBC peuvent s'exécuter sans gestionnaire de pilote.
Sur les plates-formes pour lesquelles il existe un gestionnaire de pilote
ODBC, l'utilisation de ce dernier est déconseillée.
421

Déploiement des applications clientes
Fichiers requis par le pilote ODBC
Remarques
422
Si nécessaire, mettez ODBC à jour
Le programme Setup de SQL Anywhere met à jour les anciennes
installations des composants d'accès aux données Microsoft
(MDAC), notamment ODBC. Si vous déployez votre propre
application, vous devez vous assurer que l'installation ODBC est
suffisante.
♦ Le pilote ODBC d’Adaptive Server Anywhere Il s'agit du fichier
dbodbc8.dll associé à quelques autres fichiers.
$ Pour plus d'informations, reportez-vous à la section "Fichiers
requis par le pilote ODBC", page 422.
♦ Les informations de connexion Les informations de connexion.
L'application cliente doit avoir accès aux informations requises pour se
connecter au serveur. Ces informations se trouvent généralement dans
une source de données ODBC.
Le tableau suivant indique les fichiers requis par un pilote ODBC d'Adaptive
Server Anywhere en cours d'exploitation. Ces fichiers doivent être placés
dans un seul répertoire. L'installation d'Adaptive Server Anywhere les place
tous dans le sous-répertoire du système d'exploitation du répertoire
d'installation SQL Anywhere ; par exemple : win32.
Description Windows Windows CE UNIX
Pilote ODBC dbodbc8.dll dbodbc8.dll libdbodbc8.so
libdbtasks8.so
Bibliothèque de
ressources de langue
dblgen8.dll dblgen8.dll dblgen8.res
Boîte de dialogue
Connexion
dbcon8.dll sans objet sans objet
♦ L'utilisateur final doit disposer d'une installation ODBC en état de
marche, avec un gestionnaire de pilote. Les instructions de déploiement
d'ODBC se trouvent dans Microsoft ODBC SDK.
♦ La boîte de dialogue Connexion est requise si les utilisateurs finaux
prévoient de créer leurs propres sources de données, s'ils doivent entrer
des ID utilisateur et des mots de passe au moment de la connexion à la
base de données ou s'ils souhaitent afficher la boîte de dialogue
Connexion pour toute autre raison.

Configuration du pilote ODBC
Windows
Chapitre 12 Déploiement de bases de données et d'applications
♦ Le traducteur ODBC n’est requis que si votre application repose sur la
conversion de jeu de caractères OEM vers ANSI.
$ Pour plus d'informations, reportez-vous aux sections "Création de
bases de données pour Windows CE", page 291 du document ASA
Guide d’administration et "Liaison d'applications ODBC sous
Windows CE", page 279.
♦ Pour les applications multithread sous UNIX, utilisez libdbodbc8_r.so et
libdbtasks8_r.so.
Le programme de configuration doit, outre copier les fichiers du pilote
ODBC sur le disque, créer un jeu d'entrées de registre pour installer
correctement le pilote ODBC.
Le programme Setup d'Adaptive Server Anywhere modifie la base de
registre pour identifier et configurer le pilote ODBC. Si vous élaborez un
programme de configuration pour les utilisateurs finals, veillez à effectuer les
mêmes paramétrages.
Vous disposez de l'utilitaire regedit pour examiner les entrées de registre.
Le pilote ODBC d'Adaptive Server Anywhere est identifié par le système au
moyen d'un ensemble de valeurs de registre dans la clé de registre suivante :
HKEY_LOCAL_MACHINE\
SOFTWARE\
ODBC\
ODBCINST.INI\
Adaptive Server Anywhere 8.0
Les valeurs sont les suivantes :
Nom de la valeur Type de valeur Données de la
valeur
Driver Chaîne chemin\dbodbc8.dll
Setup Chaîne chemin\dbodbc8.dll
Il existe également une valeur de registre dans la clé :
HKEY_LOCAL_MACHINE\
SOFTWARE\
ODBC\
ODBCINST.INI\
ODBC Drivers
La valeur se présente comme suit :
423

Déploiement des applications clientes
Pilotes ODBC de
fournisseurs tiers
424
Nom de la valeur Type de valeur Données de la
valeur
Adaptive Server Anywhere 8.0 Chaîne Installed
Si vous utilisez un pilote ODBC d'un fournisseur tiers sur un système
d'exploitation autre que Windows, consultez la documentation de ce pilote
pour le configurer.
Déploiement des informations de connexion
Types de source
de données
Les informations de connexion client ODBC sont généralement déployées
comme une source de données ODBC. Pour déployer une source de données
ODBC, vous avez le choix :
♦ Par programme Ajoutez une description de source données dans les
fichiers de registre ou d'initialisation ODBC pour l'utilisateur final.
♦ Manuellement Fournissez des instructions aux utilisateurs finals, de
sorte qu'ils puissent créer une source de données adéquate sur leur
machine propre.
Pour créer manuellement une source de données, faites appel à
l'Administrateur de source de données ODBC, à partir de l'onglet DSN
utilisateur ou de l'onglet DSN système. Le pilote ODBC d'Adaptive
Server Anywhere affiche la boîte de dialogue de configuration pour
définir les paramètres. Les paramètres de la source de données
comprennent l'emplacement du fichier de base de données, le nom du
serveur de base de données, ainsi que les éventuels paramètres de
démarrage et d'autres options.
Cette section vous donne les informations nécessaires pour l'une et l'autre
méthode.
Il existe trois types de sources de données : sources de données utilisateur,
sources de données système et source de données fichier.
Les définitions des sources de données utilisateur sont enregistrées dans la
partie du registre contenant les paramètres spécifiques de l'utilisateur
actuellement connecté au système. Les sources de données système,
toutefois, sont accessibles à tous les utilisateurs et aux services Windows, qui
sont exécutés qu'un utilisateur soit ou non connecté au système. Soit, par
exemple, une source de données système correctement configurée, appelée
MonApp : tout utilisateur peut utiliser cette connexion ODBC, s'il indique
DSN=MonApp dans la chaîne de connexion ODBC.

Entrées de registre
de source de
données
Chapitre 12 Déploiement de bases de données et d'applications
Les sources de données fichier ne se trouvent pas dans le registre, mais dans
un répertoire particulier. Une chaîne de connexion doit fournir un paramètre
de connexion FileDSN pour utiliser une source de données fichier.
Le système identifie chaque source de données utilisateur par des entrées de
registre.
Vous devez créer un ensemble de valeurs de registre dans une clé de registre
particulière. Pour les sources de données utilisateur, la clé est la suivante :
HKEY_CURRENT_USER\
SOFTWARE\
ODBC\
ODBC.INI\
nom_source_données_utilisateur
Pour les sources de données système, la clé est la suivante :
HKEY_LOCAL_MACHINE\
SOFTWARE\
ODBC\
ODBC.INI\
nom_source_données_système
La clé contient un ensemble de valeurs de registre, chacune correspondant à
un paramètre de connexion. Par exemple, la clé ASA 8.0 Sample
correspondant à la source de données ASA 8.0 Sample contient les
paramètres :
Nom de la
valeur
Type de
valeur
Autostop Chaîne Yes
Données de la valeur
DatabaseFile Chaîne Chemin\asademo.db
Description Chaîne Exemple de base de données Adaptive Server
Anywhere
Driver Chaîne Chemin\win32\dbodbc8.dll
PWD Chaîne sql
Start Chaîne Chemin\win32\dbeng8.exe -c 8m
UID Chaîne dba
Dans ces entrées, chemin est le répertoire d'installation d'Adaptive Server
Anywhere.
Vous devez en outre ajouter la source de données à la liste des sources de
données dans le registre. Pour les sources de données utilisateur, utilisez la
clé :
HKEY_CURRENT_USER\
425

Déploiement des applications clientes
Paramètres de
connexion
obligatoires et
facultatifs
426
SOFTWARE\
ODBC\
ODBC.INI\
ODBC Data Sources
Pour les sources de données système, utilisez la clé :
HKEY_LOCAL_MACHINE\
SOFTWARE\
ODBC\
ODBC.INI\
ODBC Data Sources.
La valeur associe chaque source de données à un pilote ODBC. Le nom de la
valeur est celui de la source de données et les données de la valeur sont le
nom du pilote ODBC. Par exemple, la source de données utilisateur installée
par Adaptive Server Anywhere s'appelle ASA 8.0 Sample et a la valeur
suivante :
Nom de la valeur Type de
valeur
Données de la valeur
ASA 8.0 Sample Chaîne Adaptive Server Anywhere 8.0
Avertissement : Les paramètres ODBC sont facilement visibles
Les configurations de source de données utilisateur peuvent contenir des
paramètres de base de données sensibles, tels qu'ID utilisateur et mot de
passe. Ces paramètres sont enregistrés en clair dans le registre et peuvent
être affichés par le biais des éditeurs de registre Windows regedit.exe ou
regedt32.exe, fournis par Microsoft avec le système d'exploitation. Vous
pouvez décider de chiffrer les mots de passe, ou d'obliger les utilisateurs à
les fournir lorsqu'ils se connectent.
Vous pouvez identifier le nom de la source de données dans une chaîne de
configuration ODBC :
DSN=nom_source_données_utilisateur
Lorsqu'un paramètre DSN est fourni dans la chaîne de connexion, les
définitions de la source des données utilisateur courante sont recherchées
dans le registre ; la source des données système est ensuite recherchée. Les
sources des données fichier ne sont recherchées que lorsque FileDSN est
fourni dans la chaîne de connexion ODBC.
Le tableau suivant illustre les conséquences, pour l'utilisateur et le
développeur, de l'existence d'une source de données et de son insertion dans
la chaîne de connexion de l'application en tant que paramètre DSN ou
FileDSN.

Chapitre 12 Déploiement de bases de données et d'applications
Lorsque la source de
données...
Contient le nom et
l’emplacement du pilote
ODBC, le nom du
fichier/serveur de la base
de données, les
paramètres de démarrage,
l'ID utilisateur et le mot
de passe.
Contient uniquement le
nom et l'emplacement du
pilote ODBC.
La chaîne de
connexion doit
identifier...
Aucune information
complémentaire
Le nom du fichier/serveur
de la base de données et,
éventuellement, l'ID
utilisateur et le mot de
passe.
N'existe pas. Le nom du pilote ODBC à
utiliser, selon la syntaxe :
Driver={nom_pilote
_ODBC}
Egalement, le nom de la
base de données, du
fichier de base de données
ou du serveur et,
éventuellement, d'autres
paramètres de connexion
tels que l'ID utilisateur ou
le mot de passe.
L'utilisateur doit
fournir...
Aucune information
complémentaire
L'ID utilisateur et le
mot de passe, s'ils ne
sont pas fournis dans le
DSN ou la chaîne de
connexion ODBC.
L'ID utilisateur et le
mot de passe, s'ils ne
sont pas fournis dans la
chaîne de connexion
ODBC.
$ Pour plus d’informations sur les connexions et les configurations
ODBC, reportez-vous aux sujets suivants :
♦ "Connexion à une base de données", page 39 du document ASA Guide
d’administration.
♦ Open Database Connectivity (ODBC) SDK, disponible auprès de
Microsoft.
Déploiement de clients Embedded SQL
Le moyen le plus simple pour déployer des clients Embedded SQL consiste à
utiliser les objets ou modèles InstallShield. Pour plus d'informations,
reportez-vous à la section "Utilisation des objets et modèles InstallShield
pour le déploiement", page 414.
427

Déploiement des applications clientes
428
Pour déployer des clients Embedded SQL, vous devez disposer des éléments
suivants :
♦ Fichiers installés Chaque machine cliente doit disposer des fichiers
requis pour une application cliente Embedded SQL d’Adaptive Server
Anywhere.
♦ Les informations de connexion Les informations de connexion.
L'application cliente doit avoir accès aux informations requises pour se
connecter au serveur. Ces informations peuvent se trouver dans une
source de données ODBC.
Installation des fichiers pour les clients Embedded SQL
Remarques
Le tableau suivant indique les fichiers requis pour les clients
Embedded SQL.
Description Windows UNIX
Bibliothèque d'interface dblib8.dll libdblib8.so,
libdbtasks8.so
Bibliothèque de ressources dblgen8.dll dblgen8.res
de langue
Communications réseau
IPX
Boîte de dialogue
Connexion
dbipx8.dll sans objet
dbcon8.dll sans objet
♦ Le DLL des ports réseau n'est pas requis si le client ne travaille qu'avec
le serveur de base de données personnel.
♦ Si l'application cliente utilise une source de données ODBC pour
conserver les paramètres de connexion, l'utilisateur final doit disposer
d'une installation ODBC active. Les instructions de déploiement
d'ODBC se trouvent dans Microsoft ODBC SDK.
$ Pour plus d'informations sur le déploiement ODBC, reportez-vous
à la section "Déploiement de clients ODBC", page 421.
♦ La boîte de dialogue Connexion est requise si les utilisateurs finaux
prévoient de créer leur propres sources de données, s'ils doivent entrer
des ID utilisateur et des mots de passe au moment de la connexion à la
base de données ou s'ils souhaitent afficher la boîte de dialogue
Connexion pour toute autre raison.
♦ Pour les applications multithread sous UNIX, utilisez libdblib8_r.so et
libdbtasks8_r.so.

Informations de connexion
Déploiement de clients JDBC
Chapitre 12 Déploiement de bases de données et d'applications
Pour déployer les informations de connexion Embedded SQL, vous avez le
choix :
♦ Manuelle Fournissez aux utilisateurs finals les instructions requises pour
créer une source de données adéquate sur leur machine.
♦ Fichier Distribuez un fichier contenant les informations de connexion
dans un format lisible par votre application.
♦ Source de données ODBC Vous pouvez placer les informations de
connexion dans une source de données ODBC. Pour ce faire, vous avez
besoin d'un sous-ensemble des fichiers ODBC redistribuables,
disponible auprès de Microsoft. Pour plus d'informations, reportez-vous
à la section "Déploiement de clients ODBC", page 421.
♦ Codé matériellement Vous pouvez coder matériellement les
informations de connexion dans votre application. Il s'agit d'une
méthode rigide, risquant d'être restrictive lors, par exemple, des mises à
niveau de bases de données.
Chaque client JDBC requiert, outre un environnement Java Runtime, le
pilote JDBC jConnect de Sybase ou la passerelle JDBC-ODBC.
$ Pour plus d'informations sur le déploiement de jConnect, reportez-vous
à la page http://manuals.sybase.com/onlinebooks/group-jc sur le site Web de
Sybase.
Pour déployer la passerelle JDBC-ODBC, vous devez déployer les fichiers
suivants:
♦ jodbc.jar Ce fichier doit se trouver dans le répertoire des classes de
l'application.
♦ dbjodbc8.dll Ce fichier doit se trouver dans le répertoire système. Sous
environnements UNIX et Linux, il s'agit d'un fichier de bibliothèque
partagée (dbjodbc8.so).
♦ Les fichiers pilote ODBC. Pour de plus amples informations, reportezvous
à la rubrique "Fichiers requis par le pilote ODBC", page 422.
Votre application Java doit être dotée d'une URL pour se connecter à la base
de données. Cette URL spécifie le pilote, la machine à utiliser et le port
écouté par le serveur de base de données.
$ Pour plus d'informations, reportez-vous à la section "Fourniture d'une
URL au serveur", page 149.
429

Déploiement des applications clientes
Déploiement d'une application Open Client
430
Pour déployer des applications Open Client, chaque machine cliente doit
disposer du produit Open Client de Sybase. Vous devez acquérir le logiciel
Open Client distinctement de Sybase. Il contient ses propres instructions
d'installation.
$ Les informations de connexion pour les clients Open Client se trouvent
dans le fichier d'interface. Pour des informations sur le fichier d'interface,
reportez-vous à la documentation Open Client et à la section "Configuration
d'Open Server", page 116 du document ASA Guide d’administration.

Chapitre 12 Déploiement de bases de données et d'applications
Déploiement des outils d'administration
Déploiement
Interactive SQL
Selon votre contrat de licence, vous pouvez déployer un ensemble d'outils
d'administration comprenant Interactive SQL, Sybase Central et l'utilitaire de
contrôle dbconsole.
Le moyen le plus simple pour déployer ces outils d'administration consiste à
utiliser les objets InstallShield fournis. Pour plus d'informations, reportezvous
à la section "Utilisation des objets et modèles InstallShield pour le
déploiement", page 414.
Si l'application cliente fonctionne sur des machines aux ressources limitées,
il peut être intéressant de déployer la version C d'Interactive SQL
(dbisqlc.exe) au lieu de la version standard (dbisql.exe et les classes Java
associées).
L'exécutable dbisqlc nécessite les bibliothèques clientes Embedded SQL
standard.
$ Pour plus d'informations sur les conditions système requises pour les
outils d'administration, reportez-vous à la section "Conditions système pour
les outils d'administration", page 147 du document Présentation de SQL
Anywhere Studio.
431

Déploiement des serveurs de base de données
Déploiement des serveurs de base de données
432
Vous pouvez déployer un serveur de base de données en mettant le
programme de configuration de SQL Anywhere Studio à disposition des
utilisateurs finals. En sélectionnant ensuite l'option appropriée, chaque
utilisateur final est assuré de recevoir les fichiers dont il a besoin.
Le moyen le plus simple pour déployer un serveur de base de données
personnel ou de réseau consiste à utiliser les objets InstallShield fournis.
Pour plus d'informations, reportez-vous à la section "Utilisation des objets et
modèles InstallShield pour le déploiement", page 414.
Pour exécuter un serveur de base de données, vous devez installer un
ensemble de fichiers. Les fichiers sont répertoriés dans le tableau suivant.
Toute redistribution de ces fichiers est soumise aux termes de votre contrat
de licence. Vous devez confirmer que vous détenez l'autorisation de
redistribuer les fichiers du serveur de base de données avant de procéder à la
redistribution.
Windows UNIX NetWare
dbeng8.exe dbeng8 sans objet
dbsrv8.exe dbsrv8 dbsrv8.nlm
dbserv8.dll libdbserv8.so,
libdbtasks8_r.so
sans objet
dblgen8.dll dblgen8.res dblgen8.res
dbjava8.dll (1)
libdbjava8.so (1)
dbjava8.nlm (1)
dbctrs8.dll sans objet sans objet
dbextf.dll (2)
asajdbc.zip (1,3)
asajrt12.zip (1,3)
classes.zip (1,3)
dbmem.vxd (4)
libdbextf.so (2)
asajdbc.zip (1,3)
asajrt12.zip (1,3)
classes.zip (1,3)
N/A N/A
libunic.dll libunic.so N/A
dbextf.nlm (2)
asajdbc.zip (1,3)
asajrt12.zip (1,3)
classes.zip (1,3)
asa.cvf asa.cvf asa.cvf
charsets\ directory charsets/ directory N/A
1. Requis uniquement si Java est utilisé dans la base de données. Pour les bases de données
initialisées avec JDK 1.1, distribuez asajdbc.zip. Pour celles initialisées avec JDK 1.2 ou
JDK 1.3, distribuez asajrt13.zip.
2. Requis uniquement si vous utilisez les procédures stockées et les fonctions (xp_) à l'échelle du
système.

Remarques
Chapitre 12 Déploiement de bases de données et d'applications
3. Installez de sorte que la variable d’environnement CLASSPATH puisse localiser les classes
dans ce fichier.
4. Requis sous Windows 95/98/Me si vous utilisez l'allocation de mémoire cache dynamique.
♦ Selon votre situation, choisissez de déployer le serveur de base de
données personnel (dbeng8) ou le serveur de base de données de réseau
(dbsrv8).
♦ La DLL Java (dbjava8.dll) n'est requise que si le serveur de base de
données doit utiliser la fonctionnalité Java dans la base de données.
♦ Le tableau ne mentionne pas les fichiers requis pour exécuter des
utilitaires tels que dbbackup.
$ Pour des informations sur le déploiement des utilitaires, reportezvous
à la section "Déploiement des outils d'administration", page 431.
♦ Les fichiers zip ne sont requis que pour les applications utilisant Java
dans la base de données, et doivent être installés à un emplacement
référencé par la variable d'environnement CLASSPATH de l'utilisateur.
Déploiement de bases de données
Pour déployer un fichier de base de données, installez-le sur le disque de
l'utilisateur final.
Tant que le serveur de base de données se ferme correctement, il est inutile
de déployer un journal de transactions avec le fichier de base de données.
Lorsque l'utilisateur final lance la base de données, un nouveau journal de
transactions est créé.
Pour les applications SQL Remote, la base de données doit être créée dans
un état correctement synchronisé, auquel cas un journal de transactions est
inutile. Vous pouvez utiliser l'utilitaire Extraction à cet effet.
Déploiement de bases de données sur un support en lecture seule
Vous pouvez distribuer des bases de données sur un support en lecture seule,
tel qu'un CD-ROM, dès lors que vous l'exécutez en mode lecture seule ou
que vous utilisez un fichier d'écriture.
$ Pour plus d'information sur l'exécution des bases de données en lecture
seule, reportez-vous à la section "Option de serveur -r", page 160 du
document ASA Guide d’administration.
433

Déploiement des serveurs de base de données
434
Pour que les modifications soient répercutées dans les bases de données
Adaptive Server Anywhere distribuées sur un support en lecture seule, tel
qu'un CD-ROM, vous pouvez utiliser un fichier d'écriture. Le fichier
d'écriture enregistre les modifications apportées à un fichier de base de
données en lecture seule ; il se trouve sur un support de stockage de type
lecture/écriture, par exemple un disque dur.
Dans ce cas, le fichier de base de données est placé sur le CD-ROM et le
fichier d'écriture sur le disque. La connexion est établie avec le fichier
d'écriture, lequel maintient un fichier journal de transactions sur le disque.
$ Pour plus d'informations sur les fichiers d'écriture, reportez-vous à la
section "Utilisation des fichiers d'écriture", page 239 du document ASA
Guide d’administration.

Chapitre 12 Déploiement de bases de données et d'applications
Déploiement d'applications de base de données
embarquées
Cette section traite du déploiement d'applications de bases de données
embarquées, où l'application et la base de données résident toutes deux sur la
même machine.
Une application de base de données embarquée contient :
♦ Application cliente Cela inclut les conditions du client Adaptive Server
Anywhere.
$ Pour des informations sur le déploiement des applications clientes,
reportez-vous à la section "Déploiement des applications clientes",
page 420.
♦ Serveur de base de données Serveur de base de données personnel
d'Adaptive Server Anywhere.
$ Pour des informations sur le déploiement des serveurs de base de
données, reportez-vous à la section "Déploiement des serveurs de base
de données", page 432.
♦ SQL Remote Si votre application exploite la réplication SQL Remote,
vous devez déployer l'agent de message SQL Remote.
♦ La base de données Vous devez déployer un fichier de base de
données contenant les données utilisées par l'application.
Déploiement de serveurs personnels
Lorsque vous déployez une application qui utilise le serveur personnel, vous
devez déployer à la fois les composants de l'application cliente et ceux du
serveur de base de données.
La bibliothèque de ressources de langue (dblgen8.dll) est partagée par le
client et le serveur. Vous n'avez besoin que d'une copie de ce fichier.
Il est conseillé de suivre le comportement de l'installation d'Adaptive Server
Anywhere et d'installer les fichiers clients et serveur dans le même
répertoire.
N'oubliez pas de fournir les fichiers zip Java et le DLL Java si votre
application fait appel à Java dans la base de données.
435

Déploiement d'applications de base de données embarquées
Déploiement d'utilitaires de base de données
Remarques
436
Si vous devez déployer des utilitaires de base de données (tels que
dbbackup.exe) avec votre application, vous devez disposer de l'exécutable de
l'utilitaire et des fichiers complémentaires suivants :
Description Windows UNIX
Bibliothèque d'outils de base de
données
dbtool8.dll libdbtools8.so,
libdbtasks8.so
Bibliothèque complémentaire dbwtsp8.dll libdbwtsp8.so
Bibliothèque de ressources de
langue
Boîte de dialogue Connexion
(dbisqlc uniquement)
Déploiement de SQL Remote
dblgen8.dll dblgen8.res
dbcon8.dll
♦ Les outils de base de données sont des applications Embedded SQL et
vous devez donc fournir les fichiers requis par ces applications,
répertoriés à la section "Déploiement de clients Embedded SQL",
page 427.
♦ Pour les applications multithread sous UNIX, utilisez libdbtools8_r.so et
libdbtasks8_r.so.
Si vous déployez l'agent de message SQL Remote, vous devez intégrer les
fichiers suivants :
Description Windows UNIX
agent de message dbremote.exe dbremote
Bibliothèque d'outils de base de
données
dbtool8.dll libdbtools8.so,
libdbtasks8.so
Bibliothèque complémentaire dbwtsp8.dll libdbwtsp8.so
Bibliothèque de ressources de
langue
Bibliothèque de liaison de
message VIM 1
dblgen8.dll dblgen8.res
dbvim8.dll

Chapitre 12 Déploiement de bases de données et d'applications
Description Windows UNIX
Bibliothèque de liaison de
message SMTP 1
Bibliothèque de liaison de
message FILE 1
Bibliothèque de liaison de
message FILE 1
Bibliothèque de liaison de
message MAPI 1
dbsmtp8.dll
dbfile8.dll libdbfile8.so
dbftp8.dll
dbmapi8.dll
Bibliothèque d'interface dblib8.dll
1 Déploie uniquement la bibliothèque pour la liaison de messagerie que vous utilisez.
Il est conseillé de suivre le comportement de l'installation d'Adaptive Server
Anywhere et d'installer les fichiers SQL Remote dans le même répertoire que
les fichiers d'Adaptive Server Anywhere.
Pour les applications multithread sous UNIX, utilisez libdbtools8_r.so et
libdbtasks8_r.so.
437

Déploiement d'applications de base de données embarquées
438

CHAPITRE 13
Messages d'erreur du préprocesseur SQL
Présentation
Sommaire
Ce chapitre présente une liste de tous les messages d'erreur et d'avertissement
du préprocesseur SQL.
Sujet Page
Messages d'erreur du préprocesseur SQL indexés par valeur de
message d'erreur 440
Erreurs SQLPP 444
439

Messages d'erreur du préprocesseur SQL indexés par valeur de message d'erreur
Messages d'erreur du préprocesseur SQL
indexés par valeur de message d'erreur
440
Valeur de message Message
2601 "Valeur de souscription '%1' trop élevée", page 458
2602 "Association de pointeurs et de tables non gérée
pour ces types d'hôtes", page 449
2603 "Seuls les tableaux à une seule colonne sont gérés
pour le type char", page 457
2604 "Le type VARCHAR doit contenir une longueur",
page 448
2605 "Tables de VARCHAR non gérées", page 448
2606 "Les variables du système hôte VARCHAR ne
peuvent pas être des pointeurs", page 448
2607 "Le système d'initialisation ne peut être utilisé sur
les variables du système hôte VARCHAR",
page 453
2608 "Le type FIXCHAR doit contenir une longueur",
page 445
2609 "Tableaux de FIXCHAR non gérés", page 448
2610 "Tables de ce type non gérées", page 449
2611 "Spécifiez la précision pour le type décimal",
page 457
2612 "Tableau de DECIMAL non autorisé", page 449
2613 "Type de variable du système hôte inconnu",
page 447
2614 "Entier incorrect", page 454
2615 "La variable du système hôte '%1' doit être un type
de chaîne en C", page 444
2617 "Symbole '%1' déjà défini", page 444
2618 "Type incorrect attribué à l'instruction SQL",
page 455
2619 "Le fichier à inclure, '%1', est introuvable",
page 445
2620 "Variable du système hôte '%1' inconnue",
page 451

Chapitre 13 Messages d'erreur du préprocesseur SQL
Valeur de message Message
2621 "Variable d’indicateur ’%1’ inconnue", page 453
2622 "Type incorrect pour la variable d’indicateur ’%1’",
page 455
2623 "Type de variable du système hôte incorrect sur
'%1'", page 454
2625 "La variable '%1' possède deux définitions
différentes", page 451
2626 "L'instruction '%1' n'a pas été préparée", page 457
2627 "Le curseur '%1' n'a pas été déclaré", page 450
2628 "Instruction '%1' inconnue", page 459
2629 "Variables du système hôte non autorisées pour ce
curseur", page 452
2630 "Variables du système hôte spécifiées deux fois -
avec declare et open", page 452
2631 "Vous devez spécifier une liste de variables du
système hôte dans une clause USING de %1",
page 456
2633 "Clause INTO non autorisée dans une instruction
SELECT", page 456
2634 "Syntaxe de langage SQL incorrecte - ceci est une
extension '%1'", page 453
2635 "Syntaxe Embedded SQL incorrecte - ceci est une
extension '%1'", page 452
2636 "Syntaxe Embedded SQL incorrecte", page 452
2637 "Guillemet de fin de chaîne manquant", page 455
2639 "Jeton trop grand", page 458
2640 "La variable du système hôte '%1' doit être de type
integer", page 444
2641 "Spécifiez une structure SQLDA avec
DESCRIBE", page 456
2642 "Deux structures SQLDA du même type spécifiées
(INTO ou USING)", page 447
2646 "Impossible de décrire des curseurs statiques",
page 449
2647 "Impossible de redéfinir les macros", page 447
2648 "Taille de tableau incorrecte", page 447
441

Messages d'erreur du préprocesseur SQL indexés par valeur de message d'erreur
442
Valeur de message Message
2649 "L’index de descripteur est incorrect", page 454
2650 "Champ incorrect pour SET DESCRIPTOR",
page 454
2651 "Champ utilisé plusieurs fois dans l'instruction SET
DESCRIPTOR", page 450
2652 "La valeur des données doit être une variable du
système hôte", page 450
2660 "Clause INTO sur curseur DECLARE non
autorisée - ignorée", page 446
2661 "Syntaxe SQL inconnue", page 459
2662 "Fonction SQL inconnue '%1'", page 459
2663 "Nombre de paramètres erroné pour la fonction
SQL '%1'", page 460
2664 "Les noms de déclarations statiques ne fonctionnent
pas correctement lorsqu'ils sont utilisés par deux
threads", page 458
2665 "La variable du système hôte '%1' a été redéfinie",
page 451
2666 "Extension propriétaire", page 460
2667 "Fonction SQL intermédiaire", page 453
2668 "Fonction SQL complète", page 451
2669 "Extension Transact-SQL", page 458
2680 "Pas de section de déclaration ni d'instruction
INCLUDE SQLCA", page 457
2681 "Impossible d'ouvrir le fichier temporaire",
page 459
2682 "Erreur de lecture du fichier temporaire", page 450
2683 "Erreur d'écriture du fichier de résultats", page 450
2690 "Nombre incorrect de variables du système hôte
pour ce curseur", page 446
2691 "Types de variables du système hôte incorrects
pour ce curseur", page 446
2692 "Variables d'indicateur incorrectes pour ce
curseur", page 446

Chapitre 13 Messages d'erreur du préprocesseur SQL
Valeur de message Message
2693 "Fonctionnalité non disponible avec UltraLite",
page 445
2694 "Aucune instruction OPEN pour le curseur '%1'",
page 456
2695 "Aucune instruction FETCH ou PUT pour le
curseur '%1'", page 456
2696 "La variable hôte '%1' est utilisée plusieurs fois
avec des indicateurs différents", page 445
2697 "La taille des données long binary/long varchar est
limitée à 65 535 octets pour UltraLite", page 455
443

Erreurs SQLPP
Erreurs SQLPP
444
Cette section répertorie les messages générés par le préprocesseur SQL. Il
peut s'agir de messages d'erreur et/ou d'avertissement selon les options de
ligne de commande activées.
$ Pour plus d'informations sur le préprocesseur SQL et ses options de
ligne de commande, reportez-vous à la section "Préprocesseur SQL",
page 247.
La variable du système hôte '%1' doit être un type de chaîne en C
Description
Valeur de message Type de message
2615 Erreur
Une chaîne en C était requise dans une instruction Embedded SQL (pour un
nom de curseur, un nom d'option, etc.) et la valeur fournie n'était pas une
chaîne de ce type.
La variable du système hôte '%1' doit être de type integer
Description
Symbole '%1' déjà défini
Description
Valeur de message Type de message
2640 Erreur
Vous avez utilisé une variable hôte qui n'est pas de type entier dans une
instruction où seule une variable hôte de type entier est autorisée.
Valeur de message Type de message
2617 Erreur
Vous avez défini deux fois une variable hôte.

Le fichier à inclure, '%1', est introuvable
Description
Chapitre 13 Messages d'erreur du préprocesseur SQL
Valeur de message Type de message
2619 Erreur
Impossible de trouver le fichier à inclure spécifié. Le préprocesseur utilisera
la variable d'environnement INCLUDE pour rechercher les fichiers à inclure.
Le type FIXCHAR doit contenir une longueur
Description
Valeur de message Type de message
2608 Erreur
Vous avez utilisé la macro DECL_FIXCHAR pour déclarer une variable
hôte de type FIXCHAR mais vous avez omis de spécifier une longueur.
Fonctionnalité non disponible avec UltraLite
Description
Valeur de message Type de message
2693 Drapeau (avertissement ou erreur)
Vous avez utilisé une fonctionnalité non supportée par UltraLite.
La variable hôte '%1' est utilisée plusieurs fois avec des indicateurs
différents
Description
Valeur de message Type de message
2696 Erreur
Vous avez utilisé la même variable hôte plusieurs fois avec différentes
variables d'indicateurs dans la même instruction. Cette fonctionnalité n'est
pas supportée.
445

Erreurs SQLPP
Types de variables du système hôte incorrects pour ce curseur
Description
446
Valeur de message Type de message
2691 Erreur
Vous avez utilisé une variable hôte avec une longueur ou un type différent de
la longueur ou du type utilisé précédemment avec le curseur. Les types des
variable hôte doivent être corrects pour le curseur.
Variables d’indicateur incorrectes pour ce curseur
Description
Valeur de message Type de message
2692 Erreur
Vous avez utilisé une variable d'indicateur avec le curseur, alors qu'aucune
variable de ce type n'avait été utilisée précédemment, ou inversement.
L'utilisation des variables d'indicateur doit être correcte pour le curseur.
Nombre incorrect de variables du système hôte pour ce curseur
Description
Valeur de message Type de message
2690 Erreur
Vous avez utilisé un nombre de variables hôte différent de celui utilisé
précédemment avec le curseur. Le nombre de variables hôte doit être correct
pour le curseur.
Clause INTO sur curseur DECLARE non autorisée - ignorée
Description
Valeur de message Type de message
2660 Avertissement
Vous avez utilisé une clause INTO dans une instruction DECLARE
CURSOR. La clause INTO sera ignorée.

Taille de tableau incorrecte
Description
Chapitre 13 Messages d'erreur du préprocesseur SQL
Valeur de message Type de message
2648 Erreur
La taille de tableau de la variable est négative.
Impossible de redéfinir les macros
Description
Valeur de message Type de message
2647 Erreur
Une macro du préprocesseur a été définie deux fois, peut-être dans un fichier
d'en-tête.
Deux structures SQLDA du même type spécifiées (INTO ou USING)
Description
Valeur de message Type de message
2642 Erreur
Vous avez spécifié deux clauses INTO DESCRIPTOR ou USING
DESCRIPTOR pour cette instruction.
Type de variable du système hôte inconnu
Description
Valeur de message Type de message
2613 Erreur
Vous avez déclaré une variable hôte d'un type non compris par le
préprocesseur SQL.
447

Erreurs SQLPP
Les variables du système hôte VARCHAR ne peuvent pas être des
pointeurs
Description
448
Valeur de message Type de message
2606 Erreur
Vous avez tenté de déclarer une variable hôte comme un pointeur vers une
variable VARCHAR ou BINARY. Il ne s'agit pas d'un type de variable hôte
autorisé.
Le type VARCHAR doit contenir une longueur
Description
Valeur de message Type de message
2604 Erreur
Tableaux de FIXCHAR non gérés
Description
Tables de VARCHAR non gérées
Description
Vous avez tenté de déclarer une variable hôte VARCHAR ou BINARY à
l'aide de la macro DECL_VARCHAR ou DECL_BINARY mais vous avez
omis d'indiquer une taille pour la table.
Valeur de message Type de message
2609 Erreur
Vous avez tenté de déclarer une variable hôte comme un tableau de
FIXCHAR. Il ne s'agit pas d'un type de variable hôte autorisé.
Valeur de message Type de message
2605 Erreur
Vous avez tenté de déclarer une variable hôte comme une table de
VARCHAR ou BINARY. Il ne s'agit pas d'un type de variable hôte autorisé.

Tableau de DECIMAL non autorisé
Description
Tables de ce type non gérées
Description
Chapitre 13 Messages d'erreur du préprocesseur SQL
Valeur de message Type de message
2612 Erreur
Vous avez tenté de déclarer une variable hôte comme un tableau de
DECIMAL. Il ne s'agit pas d'un type de variable hôte autorisé.
Valeur de message Type de message
2610 Erreur
Vous avez tenté de déclarer une table de variable hôte qui a un type non
supporté.
Impossible de décrire des curseurs statiques
Description
Valeur de message Type de message
2646 Erreur
Vous avez décrit un curseur statique. Lors de la description d'un curseur, son
nom doit être spécifié dans une variable hôte.
Association de pointeurs et de tables non gérée pour ces types
d'hôtes
Description
Valeur de message Type de message
2602 Erreur
Vous avez utilisé une table de pointeurs comme variable hôte. Cette
opération n'est pas autorisée.
449

Erreurs SQLPP
Le curseur '%1' n'a pas été déclaré
Description
450
Valeur de message Type de message
2627 Erreur
Un nom de curseur Embedded SQL a été utilisé (dans une instruction
FETCH, OPEN, CLOSE etc.) sans avoir été déclaré (DECLARE).
La valeur des données doit être une variable du système hôte
Description
Valeur de message Type de message
2652 Erreur
La variable utilisée dans l'instruction SET DESCRIPTOR n'a pas été
déclarée comme une variable hôte.
Erreur de lecture du fichier temporaire
Description
Valeur de message Type de message
2682 Erreur
Une erreur s'est produite lors de la lecture à partir d'un fichier temporaire.
Erreur d'écriture du fichier de résultats
Description
Valeur de message Type de message
2683 Erreur
Une erreur s'est produite lors de l'écriture dans le fichier de résultats.
Champ utilisé plusieurs fois dans l'instruction SET DESCRIPTOR
Valeur de message Type de message
2651 Erreur

Description
Fonction SQL complète
Description
Chapitre 13 Messages d'erreur du préprocesseur SQL
Le même mot-clé a été spécifié plusieurs fois dans une même instruction
SET DESCRIPTOR.
Valeur de message Type de message
2668 Drapeau (avertissement ou erreur)
Vous avez utilisé une fonctionnalité SQL/92 complète et prétraité avec
l'option de balisage -ee, -ei, -we ou -wi.
La variable du système hôte '%1' a été redéfinie
Description
Valeur de message Type de message
2665 Avertissement
Vous avez redéfini la même variable hôte avec un type d'hôte différent. En
ce qui concerne le préprocesseur, les variables hôte sont globales ; il n'est pas
possible que deux variables hôte du même nom aient des types différents.
La variable '%1' possède deux définitions différentes
Description
Valeur de message Type de message
2625 Erreur
Le même nom de variable hôte a été défini avec deux types différents au sein
d'un même module. Notez que les noms de variable hôte sont globaux pour
chaque module C.
Variable du système hôte '%1' inconnue
Valeur de message Type de message
2620 Erreur
451

Erreurs SQLPP
Description
452
Vous avez utilisé une variable hôte dans une instruction, qui n'a pas été
déclarée dans une section de déclaration.
Variables du système hôte non autorisées pour ce curseur
Description
Valeur de message Type de message
2629 Erreur
Les variables hôte ne sont pas autorisées dans l'instruction de déclaration
pour le curseur spécifié. Si le nom de curseur est fourni par le biais d'une
variable hôte, vous devez utiliser SQL dynamique et préparer l'instruction.
Une instruction préparée peut comporter des variables hôte.
Variables du système hôte spécifiées deux fois - avec declare et
open
Description
Valeur de message Type de message
2630 Erreur
Vous avez spécifié des variables hôte pour un curseur à la fois dans des
instructions declare et open. Dans le cas statique, vous devez spécifier les
variables hôte dans l'instruction declare. Dans le cas dynamique, indiquez-les
dans l'instruction open.
Syntaxe Embedded SQL incorrecte - ceci est une extension ’%1’
Valeur de message Type de message
2635 Erreur
Syntaxe Embedded SQL incorrecte
Valeur de message Type de message
2636 Erreur

Description
Chapitre 13 Messages d'erreur du préprocesseur SQL
Une instruction Embedded SQL spécifique (OPEN, DECLARE, FETCH,
etc.) comporte une erreur de syntaxe.
Syntaxe de langage SQL incorrecte - ceci est une extension ’%1’
Valeur de message Type de message
2634 Erreur
Variable d’indicateur ’%1’ inconnue
Description
Valeur de message Type de message
2621 Erreur
Vous avez utilisé une variable d'indicateur dans une instruction, qui n'a pas
été déclarée dans une section de déclaration.
Le système d'initialisation ne peut être utilisé sur les variables du
système hôte VARCHAR
Description
Fonction SQL intermédiaire
Description
Valeur de message Type de message
2607 Erreur
Vous ne pouvez pas spécifier un initialiseur de variable en C pour une
variable de système hôte de type VARCHAR ou BINARY. Vous devez
initialiser cette variable à l'aide d'un code C exécutable standard.
Valeur de message Type de message
2667 Drapeau (avertissement ou erreur)
Vous avez utilisé une fonctionnalité SQL/92 intermédiaire et prétraité avec
l'option de balisage -ee ou -we.
453

Erreurs SQLPP
L’index de descripteur est incorrect
Description
454
Valeur de message Type de message
2649 Erreur
Vous n'avez alloué aucune variable avec l'instruction ALLOCATE
DESCRIPTOR.
Champ incorrect pour SET DESCRIPTOR
Description
Valeur de message Type de message
2650 Erreur
Un mot-clé incorrect ou inconnu est présent dans une instruction SET
DESCRIPTOR. Seuls les mots-clés TYPE, PRECISION, SCALE,
LENGTH, INDICATOR, ou DATA sont acceptés.
Type de variable du système hôte incorrect sur '%1'
Description
Entier incorrect
Description
Valeur de message Type de message
2623 Erreur
Vous avez utilisé une variable hôte qui n'est pas du type chaîne à un
emplacement où le préprocesseur attendait une variable de ce type.
Valeur de message Type de message
2614 Erreur
Un entier était requis dans une instruction Embedded SQL (pour un résultat
d'extraction, un index de table de variables hôte, etc.) et le préprocesseur n'a
pas pu convertir les données fournies par l'entier.

Chapitre 13 Messages d'erreur du préprocesseur SQL
Type incorrect pour la variable d’indicateur ’%1’
Description
Valeur de message Type de message
2622 Erreur
Les variables d'indicateur doivent être de type entier court. Vous avez utilisé
une variable d'un autre type comme variable d'indicateur.
Type incorrect attribué à l'instruction SQL
Description
Valeur de message Type de message
2618 Erreur
Une variable hôte utilisée dans un identificateur d'instruction doit être du
type a_sql_statement_number. Vous avez tenté d'utiliser une variable hôte
d'un autre type comme identificateur d'instruction.
La taille des données long binary/long varchar est limitée à 65 535
octets pour UltraLite
Description
Valeur de message Type de message
2697 Erreur
Lorsque vous utilisez DECL_LONGBINARY ou DECL_LONGVARCHAR
avec UltraLite, la taille maximale de la table est de 64 ko.
Guillemet de fin de chaîne manquant
Description
Valeur de message Type de message
2637 Erreur
Vous avez spécifié une constante de chaîne dans une instruction Embedded
SQL, mais avez omis le guillemet de fin avant la fin de la ligne ou du fichier.
455

Erreurs SQLPP
Vous devez spécifier une liste de variables du système hôte dans
une clause USING de %1
Description
456
Valeur de message Type de message
2631 Erreur
L'instruction spécifiée requiert des variables hôte devant être indiquées dans
une liste de variables hôte ou à partir d'une SQLDA.
Spécifiez une structure SQLDA avec DESCRIBE
Valeur de message Type de message
2641 Erreur
Aucune instruction FETCH ou PUT pour le curseur '%1'
Description
Valeur de message Type de message
2695 Erreur
Un curseur est déclaré et ouvert, mais n'est jamais utilisé.
Clause INTO non autorisée dans une instruction SELECT
Description
Valeur de message Type de message
2633 Erreur
Vous avez spécifié une instruction Embedded SELECT statique mais vous
avez omis d'indiquer une clause INTO pour les résultats.
Aucune instruction OPEN pour le curseur ’%1’
Valeur de message Type de message
2694 Erreur

Description
Chapitre 13 Messages d'erreur du préprocesseur SQL
Un curseur est déclaré, et éventuellement utilisé, mais jamais ouvert.
Pas de section de déclaration ni d'instruction INCLUDE SQLCA
Description
Valeur de message Type de message
2680 Erreur
L’instruction EXEC SQL INCLUDE SQLCA est absente du fichier source.
Seuls les tableaux à une seule colonne sont gérés pour le type
char
Description
Valeur de message Type de message
2603 Erreur
Vous avez tenté de déclarer une variable hôte comme une table de tables de
caractères. Il ne s'agit pas d'un type de variable hôte autorisé.
Spécifiez la précision pour le type décimal
Description
Valeur de message Type de message
2611 Erreur
Vous devez indiquer la précision lorsque vous déclarez, à l'aide de la macro
DECL_DECIMAL, une variable hôte en décimal condensé. L'échelle est
facultative.
L'instruction '%1' n'a pas été préparée
Description
Valeur de message Type de message
2626 Erreur
Un nom d'instruction Embedded SQL a été utilisé (EXECUTE) sans avoir
été préparé (PREPARE).
457

Erreurs SQLPP
Les noms de déclarations statiques ne fonctionnent pas
correctement lorsqu'ils sont utilisés par deux threads
Description
458
Valeur de message Type de message
2664 Avertissement
Vous avez utilisé un nom d'instruction statique et prétraité avec l'option -r.
Les noms d'instruction statique entraînent la définition par la base de
données des variables statiques générées. Si deux threads utilisent la même
instruction, un conflit se produit sur cette variable. Utilisez une variable hôte
locale comme identificateur d'instruction à la place du nom statique.
Valeur de souscription '%1' trop élevée
Description
Jeton trop grand
Description
Extension Transact-SQL
Valeur de message Type de message
2601 Erreur
Vous avez tenté d'indexer une variable hôte qui est une table possédant une
valeur trop élevée.
Valeur de message Type de message
2639 Erreur
Le préprocesseur SQL a une longueur de jeton maximale de 2 ko. Tout jeton
supérieur à 2 ko provoque cette erreur. Pour les chaînes constantes dans les
commandes Embedded SQL (où cette erreur se produit le plus
fréquemment), utilisez la concaténation pour obtenir une chaîne plus longue.
Valeur de message Type de message
2669 Drapeau (avertissement ou erreur)

Description
Chapitre 13 Messages d'erreur du préprocesseur SQL
Vous avez utilisé une fonctionnalité Transact-SQL Sybase qui n'est pas
définie par SQL/92 et prétraité avec l'option de balisage -ee, -ei, -ef, -we, -wi
ou -wf .
Impossible d’ouvrir le fichier temporaire
Description
Fonction SQL inconnue ’%1’
Description
Instruction ’%1’ inconnue
Description
Syntaxe SQL inconnue
Valeur de message Type de message
2681 Erreur
Une erreur s'est produite lors de la tentative d'ouverture d'un fichier
temporaire.
Valeur de message Type de message
2662 Avertissement
Vous avez utilisé une fonction SQL inconnue du préprocesseur et susceptible
de provoquer une erreur lors de l'envoi de l'instruction au moteur de la base
de données.
Valeur de message Type de message
2628 Erreur
Vous avez tenté de supprimer une instruction Embedded SQL qui n'existe
pas.
Valeur de message Type de message
2661 Avertissement
459

Erreurs SQLPP
Description
Extension propriétaire
Description
460
Vous avez utilisé une instruction SQL susceptible de provoquer une erreur de
syntaxe lors de l'envoi de l'instruction au moteur de base de données.
Valeur de message Type de message
2666 Drapeau (avertissement ou erreur)
Vous avez utilisé une fonctionnalité d'Adaptive Server Anywhere qui n'est
pas définie par SQL/92 et prétraité avec l'option de balisage -ee, -ei, -ef, -we,
-wi ou -wf .
Nombre de paramètres erroné pour la fonction SQL '%1'
Description
Valeur de message Type de message
2663 Avertissement
Vous avez utilisé une fonction SQL avec un nombre erroné de paramètres.
Cette opération est susceptible de provoquer une erreur lors de l'envoi de
l'instruction au moteur de la base de données.

Index
>
>>
méthode Java dans la base de données, 75
A
a_backup_db, structure, 332
a_change_log, structure, 334
a_compress_db, structure, 336
a_compress_stats, structure, 337
a_create_db, structure, 338
a_crypt_db, structure, 340
a_db_collation, structure, 341
a_db_info, structure, 343
a_dblic_info, structure, 346
a_dbtools_info, structure, 347
a_name, structure, 349
a_stats_line, structure, 349
a_sync_db, structure, 350
a_syncpub, structure, 352
a_sysinfo, structure, 352
a_table_info, structure, 353
a_translate_log, structure, 354
a_truncate_log, structure, 356
a_validate_db, structure, 360
a_validate_type, énumération, 366
a_writefile, structure, 361
accès Java
privé, 69
protégé, 69
public, 69
ActiveX Data Objects
généralités, 370
ADO
commande, 372
connexion, 370
curseur, 26, 375
généralités, 370
introduction à la programmation, 3
mise à jour, 375
objet Command, 372
objet Connection, 370
objet Recordset, 373, 375
requête, 373, 375
type de curseur, 25
utilisation d'instructions SQL dans les
applications, 10
adresse de serveur
fonction Embedded SQL, 256
agencement
Java dans la base de données, 116
ajout
classe Java dans la base de données, 102
fichier JAR, 103
alloc_sqlda, fonction
généralités, 251
alloc_sqlda_noind, fonction
généralités, 251
461

B–B
ALTER DATABASE, instruction
Java dans la base de données, 97, 99
an_erase_db, structure, 347
an_expand_db, structure, 348
an_unload_db, structure, 357
an_upgrade_db, structure, 359
annulation de requêtes
Embedded SQL, 245
appartenance
jeu de résultats, 29
application
déploiement, 405, 420
déploiement Embedded SQL, 427
SQL, 10
application distribuée
conditions requises, 171
exemple, 173
généralités, 171
application multithread
ODBC, 276, 291
UNIX, 280
application utilisant les threads natifs
UNIX, 410
applications multi-thread
Embedded SQL, 208
architecture à trois niveaux
Distributed Transaction Coordinator, 397
distributeur de ressources, 396
EAServer, 397
généralités, 393
gestionnaire de ressources, 396
Microsoft Transaction Server, 397
transaction distribuée, 396
architecture informatique
trois niveaux, 395
architecture multithread
Java dans la base de données, 121
ARRAY, clause
instruction FETCH, 215
asademo.db, fichier
généralités, xiv
462
asajdbc.zip
classe d'exécution, 95
déploiement de serveurs de base de données, 432
ASAJDBCDRV
fichier JAR, 96
ASAJRT
fichier JAR, 96
asajrt12.zip
classe d'exécution, 95
ASAProv
fournisseur OLE DB, 368
ASASystem
fichier JAR, 96
assistant
création de classe Java, 83, 102, 159
création de fichiers JAR et ZIP, 103
mise à jour de base de données, 99
attribut
Java dans la base de données, 130
attribut de transaction
composant, 402
autocommit
contrôle, 47
mise en oeuvre, 48
ODBC, 160
transaction, 47
autocommit côté client
généralités, 48
autocommit côté serveur
généralités, 48
autorisation
JDBC, 170
B
base de données
configuration pour Java, 95, 97, 99
déploiement, 433
Java dans la base de données, 130
URL, 150
base de données embarquée
déploiement, 435

ase de données exemple
généralités, xiv
Java dans la base de données, 92
bibliothèque
Embedded SQL, 181
bibliothèque d'importation
alternatives, 183
DBTools, 311
Embedded SQL, 181
NetWare, 185
ODBC, 278
présentation, 179
Windows CE ODBC, 280
bibliothèque d'interface
chargement dynamique, 183
généralités, 178
nom de fichier, 178
BINARY, type de données
Embedded SQL, 197
BLOB
Embedded SQL, 235
envoi dans Embedded SQL, 238
récupération dans Embedded SQL, 236
bloc catch
Java, 71
bloc finally
Java, 71
bloc try
Java, 71
Borland C++
support, 180
C
cache
Java dans la base de données, 137
CALL, instruction
Embedded SQL, 241
callback
DB_CALLBACK_DEBUG_MESSAGE, 260
DB_CALLBACK_FINISH, 260
DB_CALLBACK_MESSAGE, 261
DB_CALLBACK_START, 260
DB_CALLBACK_WAIT, 260
callback, fonction
enregistrement, 259
caractère d'échappement
Java dans la base de données, 78
SQL, 78
CD-ROM
déploiement de bases de données sur, 433
chaîne
Java dans la base de données, 76
remplissage de blancs de DT_STRING, 192
type de données, 268
chaîne de caractères, 249
chaîne terminée par une valeur NULL
type de données Embedded SQL, 192
CHAINED, option
JDBC, 160
champ
classe, 65
instance, 65
Java dans la base de données, 64
privé, 69
protégé, 69
public, 69, 81
SQLDA, 227
champ de bits
utilisation, 316
champ public
question, 81
Class.forName, méthode
chargement de jConnect, 149
classe
constructeur, 64
création, 101
exécution, 73
exemple, 108
généralités, 62
importation, 173
installation, 101
instance, 68
Java, 68
mise à jour, 104
C–C
463

C–C
type de données, 106
version, 104
classe de compilation, 62
classe définie par l'utilisateur
Java dans la base de données, 74
classe d'exécution
contenu, 95
installation, 95
classe d'exécution Java dans la base de données, 73
classe d'exécution Java de Sybase
présentation, 95
classe Java
ajout, 102
installation, 102
classe Java déconseillée
généralités, 73
classe supportée, 59
classe, champ
généralités, 65
classes.zip
classe d'exécution, 95
déploiement de serveurs de base de données, 432
CLASSPATH, variable d'environnement
généralités, 80
Java dans la base de données, 80
jConnect, 147
paramètre, 157
clause
WITH HOLD, 21
clé primaire
Java dans la base de données, 117
CLOSE, instruction
généralités, 212
code de retour, 313
ODBC, 304
code octet
classe Java, 56
colonne
mise à jour, 111
type de données Java dans la base de données,
106
464
colonne calculée
création, 134
instruction INSERT, 135
instruction UPDATE, 135
Java dans la base de données, 134
recalcul, 136
restriction, 136
trigger, 135
colonne clé primaire
Java dans la base de données, 117
colonne unique
Java dans la base de données, 117
com.sybase, package
classe d'exécution, 95
Command, objet
ADO, 372
commande
objet Command d'ADO, 372
commit
transaction ODBC, 287
commit à deux phases
architecture à trois niveaux, 396, 397
Open Client, 392
commit automatique
ODBC, 287
COMMIT, instruction
curseur, 49
JDBC, 160
mode autocommit, 47
compareTo, méthode
comparaison d'objets, 117
compilateur
supporté, 180
compilateur GNU
support, 180
composant
attribut de transaction, 402
COMPUTE, clause
CREATE TABLE, 134
conception d'une base de données
Java dans la base de données, 130

condensation de structure
fichier d'en-tête, 181
configuration requise
application Open Client, 386
Connection, objet
ADO, 370
connexion
application JDBC cliente, 154
attribut ODBC, 290
exemple JDBC, 154, 158
fonction, 265
fonction ODBC, 288
jConnect, 150
JDBC, 145, 154, 158, 160
objet Connection d'ADO, 370
programmation ODBC, 289
temps d'activité, 260
URL jConnect, 149
constructeur
généralités, 64
insertion de données, 110
Java, 69
conventions
documentation, xi
conventions de dénomination
fichier, 410
conversion
type de données, 203
conversion du jeu de caractères
passerelle JDBC-ODBC, 153
coordinateur de transactions
EAServer, 401
CREATE DATABASE, instruction
Java dans la base de données, 97, 98
CREATE PROCEDURE, instruction
Embedded SQL, 241
création de classe Java, assistant
utilisation, 83, 102, 159
création de fichiers JAR et ZIP, assistant
utilisation, 103
cryptage
interface DBTools, 323
CS_CSR_ABS, 392
CS_CSR_FIRST, 392
CS_CSR_LAST, 392
CS_CSR_PREV, 392
CS_CSR_REL, 392
CS_DATA_BOUNDARY, 392
CS_DATA_SENSITIVITY, 392
CS_PROTO_DYNPROC, 392
CS_REG_NOTIF, 392
CS_REQ_BCP, 392
ct_command, fonction
Open Client, 389, 391
ct_cursor, fonction
Open Client, 390
ct_dynamic, fonction
Open Client, 389
ct_results, fonction
Open Client, 391
ct_send, fonction
Open Client, 391
C–C
curseur, 28
ADO, 26
annulation, 24, 255
appartenance, 29
choix des caractéristiques d'un curseur ODBC,
297
code exemple en C, 186
défilement, 23, 25, 39
défilement dynamique, 25, 38
demande, 26
description, 45
disponibilité, 25
DYNAMIC SCROLL, 21
dynamique, 36
Embedded SQL, 27, 212
exemple de sensibilité, 31, 33
extraction de lignes, 20, 21
extraction multiligne, 22
étape d'utilisation, 17
fat, 22
généralités, 15
insensible, 25, 35
465

D–D
instruction préparée, 19
interne, 29
jeu de résultats, 15
jeu de résultats ODBC, 298
keyset, 39
lecture seule, 25
mise à jour, 375, 391
mise à jour et suppression, 23
mise à jour ODBC, 300
modification visible, 30
niveau d'isolement, 21
ODBC, 26, 297
OLE DB, 26
Open Client, 390
ordre, 29
performances, 42, 43
plate-forme, 25
point de sauvegarde, 50
positionnement, 20
présentation, 15
procédure stockée, 242
sans défilement, 25, 35
sensibilité, 29, 30
sensibilité indéfinie, 38
sensibilité non spécifiée, 38
sensible, 36
signet ODBC, 300
statique, 35
suppression, 391
suppression ODBC, 300
table de travail, 42
tenant compte des valeurs, 39
transaction, 49
unique, 25
utilisation, 15, 20
valeur, 29
curseur à sensibilité indéfinie
exemple de mise à jour, 33
exemple de suppression, 31
généralités, 38
présentation, 30
curseur avec défilement, 23
généralités, 25, 39
curseur avec défilement dynamique
généralités, 25, 38
curseur bloc, 22
ODBC, 28
466
curseur dynamique
exemple, 189
généralités, 36
ODBC, 26
curseur en lecture seule
généralités, 25
curseur insensible
exemple de mise à jour, 33
exemple de suppression, 31
généralités, 25, 35
présentation, 30
curseur keyset
généralités, 39
ODBC, 26
curseur mixte
ODBC, 26
curseur sans défilement
généralités, 25, 35
curseur sensible
exemple de mise à jour, 33
exemple de suppression, 31
généralités, 36
présentation, 30
curseur statique
généralités, 35
ODBC, 26
curseur tenant compte des valeurs
exemple de mise à jour, 33
exemple de suppression, 31
généralités, 39
présentation, 30
curseur unique
généralités, 25
curseurs avec défilement
support JDBC, 141
D
db_backup, fonction
généralités, 245, 252
DB_BACKUP_CLOSE_FILE, paramètre, 252
DB_BACKUP_END, paramètre, 252

DB_BACKUP_OPEN_FILE, paramètre, 252
DB_BACKUP_READ_PAGE, paramètre, 252
DB_BACKUP_READ_RENAME_LOG, paramètre,
252
DB_BACKUP_START, paramètre, 252
DB_CALLBACK_CONN_DROPPED, paramètre
callback, 260
DB_CALLBACK_DEBUG_MESSAGE, paramètre
callback, 260
DB_CALLBACK_FINISH, paramètre callback, 260
DB_CALLBACK_MESSAGE, paramètre callback,
261
DB_CALLBACK_START, paramètre callback, 260
DB_CALLBACK_WAIT, paramètre callback, 260
db_cancel_request, fonction
généralités, 255
gestion des requêtes, 245
db_delete_file, fonction
généralités, 255
db_find_engine, fonction
généralités, 256
db_fini, fonction
généralités, 256
db_fini_dll
appel, 184
db_get_property, fonction
généralités, 256
db_init, fonction
généralités, 257
db_init_dll
appel, 184
db_is_working, fonction
généralités, 258
gestion des requêtes, 245
db_locate_servers, fonction
généralités, 258
db_register_a_callback, fonction
généralités, 259
gestion des requêtes, 245
D–D
db_start_database, fonction
généralités, 261
db_start_engine, fonction
généralités, 262
db_stop_database, fonction
généralités, 263
db_stop_engine, fonction
généralités, 264
db_string_connect, fonction
généralités, 265
db_string_disconnect, fonction
généralités, 265
db_string_ping_server, fonction
généralités, 266
DBBackup, fonction, 320
DBChangeLogName, fonction, 320
DBChangeWriteFile, fonction, 321
DBCollate, fonction, 321
DBCompress, fonction, 322
dbcon8.dll
déploiement de clients Embedded SQL, 428
déploiement de clients ODBC, 422
déploiement de clients OLE DB, 420
déploiement d'utilitaires de base de données, 436
dbconsole, utilitaire
déploiement, 431
DBCreate, fonction, 322
DBCreateWriteFile, fonction, 323
DBCrypt, fonction, 323
dbctrs8.dll
déploiement de serveurs de base de données, 432
dbeng8
déploiement de serveurs de base de données, 432
DBErase, fonction, 323
DBExpand, fonction, 324
dbextf.dll
déploiement de serveurs de base de données, 432
467

D–D
dbfile.dll
déploiement de SQL Remote, 436
DBInfo, fonction, 324
DBInfoDump, fonction, 325
DBInfoFree, fonction, 325
dbinit, utilitaire
Java dans la base de données, 97, 98
dbipx8.dll
déploiement de clients Embedded SQL, 428
déploiement de clients ODBC, 422
dbjava8.dll
déploiement de serveurs de base de données, 432
dblgen8.dll
déploiement de clients Embedded SQL, 428
déploiement de clients ODBC, 422
déploiement de clients OLE DB, 420
déploiement de serveurs de base de données, 432
déploiement de SQL Remote, 436
déploiement d'utilitaires de base de données, 436
dblib8.dll
bibliothèque d'interface, 178
déploiement de clients Embedded SQL, 428
DBLicense, fonction, 326
dbmapi.dll
déploiement de SQL Remote, 436
dbmlsync, utilitaire
API C, 350
création personnelle, 350
dbodbc8.dll
déploiement de clients ODBC, 422
dbodbc8.lib
bibliothèque d'importation ODBC Windows CE,
280
dbodbc8.so
pilote ODBC UNIX, 281
dboledb8.dll
déploiement de clients OLE DB, 420
dboledba8.dll
déploiement de clients OLE DB, 420
dbremote
déploiement de SQL Remote, 436
468
dbserv8.dll
déploiement de serveurs de base de données, 432
dbsmtp.dll
déploiement de SQL Remote, 436
dbsrv8
déploiement de serveurs de base de données, 432
DBStatusWriteFile, fonction, 326
DBSynchronizeLog, fonction, 327
dbtool8.dll
déploiement de SQL Remote, 436
déploiement d'utilitaires de base de données, 436
Windows CE, 310
DBTools, interface
appel des fonctions DBTools, 312
arrêt, 311
démarrage, 311
énumération, 364
fonction, 320
généralités, 309
introduction, 310
programme exemple, 316
utilisation, 311
DBToolsFini, fonction, 327
DBToolsInit, fonction, 328
DBToolsVersion, fonction, 328
dbtran_userlist_type, énumération, 365
DBTranslateLog, fonction, 329
DBTruncateLog, fonction, 329
DBUnload, fonction, 330
dbunload, utilitaire
création personnelle, 357
fichier d'en-tête, 357
dbunload_type, énumération, 365
dbupgrad, utilitaire
Java dans la base de données, 97, 99
DBUpgrade, fonction, 330
DBValidate, fonction, 331
dbvim.dll
déploiement de SQL Remote, 436

dbwtsp8.dll
déploiement de SQL Remote, 436
déploiement d'utilitaires de base de données, 436
dbxtract, utilitaire
création personnelle, 357
fichier d'en-tête, 357
dbxtract, utilitaire de ligne de commande
interface d'outils de base de données, 330
DECIMAL, type de données
Embedded SQL, 197
DECL_BINARY
macro, 197
DECL_DECIMAL
macro, 197
DECL_FIXCHAR
macro, 197
DECL_LONGBINARY
macro, 197
DECL_LONGVARCHAR
macro, 197
DECL_VARCHAR
macro, 197
déclaration
type de données Embedded SQL, 192
variable hôte, 196
DECLARE, instruction
généralités, 212
définition
valeurs au moyen de la zone SQLDA, 231
DELETE, instruction
Java dans la base de données, 112
positionnée, 23
dénomination des fichiers
conventions, 410
déploiement
application, 420
base de données, 433
base de données embarquée, 435
base de données en lecture seule, 433
base de données et application, 405
base de données sur CD-ROM, 433
client JDBC, 429
Embedded SQL, 427
emplacement des fichiers, 409
fichier d'écriture, 412
fournisseur OLE DB, 420
généralités, 405
installation silencieuse, 416
InstallShield, 414
Interactive SQL, 431
Java dans la base de données, 432
jConnect, 429
modèle, 406
ODBC, 421
Open Client, 430
outil d'administration, 431
paramètre de registre, 422, 424
paramètre ODBC, 422, 424
passerelle JDBC-ODBC, 429
pilote ODBC, 422
présentation, 406
serveur de base de données, 432
serveur de base de données personnel, 435
serveur de synchronisation MobiLink, 416
SQL Remote, 436
Sybase Central, 431
System Management Server, 418
utilitaire dbconsole, 431
DESCRIBE, instruction
champ SQLDA, 228
champ sqllen, 230
champ sqltype, 230
généralités, 224
jeux de résultats multiples, 244
descripteur, 45
allocation, 286
ODBC, 285
description
jeu de résultats, 45
destructeur
Java, 70
détection et résolution des problèmes
Java dans la base de données, 121
position du curseur, 21
DISTINCT, mot-clé
Java dans la base de données, 117
D–D
469

E–E
distinction majuscules/minuscules
Java dans la base de données et SQL, 76
type de données Java dans la base de données,
106
Distributed Transaction Coordinator
architecture à trois niveaux, 397
distributeur de ressources
architecture à trois niveaux, 396
DLL
zones SQLCA multiples, 209
DLL de langue
comment l'obtenir, 411
documentation
conventions, xi
SQL Anywhere Studio, viii
DT_BIGINT
type de données Embedded SQL, 192
DT_BINARY
type de données Embedded SQL, 193
DT_BIT
type de données Embedded SQL, 192
DT_DATE
type de données Embedded SQL, 192
DT_DECIMAL
type de données Embedded SQL, 192
DT_DOUBLE
type de données Embedded SQL, 192
DT_FIXCHAR
type de données Embedded SQL, 193
DT_FLOAT
type de données Embedded SQL, 192
DT_INT
type de données Embedded SQL, 192
DT_LONGBINARY
type de données Embedded SQL, 194
DT_LONGVARCHAR
type de données Embedded SQL, 193
DT_SMALLINT
type de données Embedded SQL, 192
DT_STRING, type de données, 268
470
DT_TIME
type de données Embedded SQL, 192
DT_TIMESTAMP
type de données Embedded SQL, 193
DT_TIMESTAMP_STRUCT
type de données Embedded SQL, 194
DT_TINYINT
type de données Embedded SQL, 192
DT_UNSINT
type de données Embedded SQL, 192
DT_UNSSMALLINT
type de données Embedded SQL, 192
DT_VARCHAR
type de données Embedded SQL, 193
DT_VARIABLE
type de données Embedded SQL, 195
DTC
architecture à trois niveaux, 397
durée
classe Java dans la base de données, 78
DYNAMIC SCROLL, curseur
détection et résolution des problèmes, 21
Embedded SQL, 27
E
EAServer
architecture à trois niveaux, 397
attribut de transaction d'un composant, 402
coordinateur de transactions, 401
transaction distribuée, 401
Embedded SQL
autorisation, 249
bibliothèque d'importation, 181
chaîne de caractères, 249
curseur, 27, 186, 212
curseur dynamique, 189
développement, 178
fichier d'en-tête, 181
fonction, 251
fonction de sauvegarde, 245
généralités, 177
instruction dynamique, 221

instruction SQL, 10
instruction statique, 221
lecture de données, 211
mode autocommit, 47
numéro de ligne, 249
présentation, 4
procédure stockée, 241
processus de compilation et de liaison, 179
programme exemple, 182
récapitulatif des commandes, 270
sauvegarde en ligne, 245
type de curseur, 25
variable hôte, 196
entité
Java dans la base de données, 130
environnement d'exécution
Java dans la base de données, 94
erreur
champ SQLCA sqlcode, 205
code, 205
SQLCODE, 205
erreur de procédure introuvable
Java dans la base de données, 121
méthode Java, 165
erreur d'overflow
conversion des types de données, 387
espace disque
Java dans la base de données, 127
espace nom
Java dans la base de données, 138
exception
Java, 70
EXEC SQL
développement Embedded SQL, 183
EXECUTE, instruction, 221
procédure stockée dans Embedded SQL, 241
executeQuery, méthode
généralités, 166
executeUpdate
méthode JDBC, 14
executeUpdate, méthode JDBC
généralités, 163
exemple
application Embedded SQL, 186
curseur statique dans Embedded SQL, 189
Embedded SQL, 187
esqldll.c, 184
ODBC, 283
programme DBTools, 316
service Windows, 284
extraction
curseur, 21
curseur avec défilement, 23
limites, 20
multiligne, 22, 215
objet, 171
ODBC, 298
SQLDA, 233
extraction étendue, 22
généralités, 215
É
égalité entre objets
Java dans la base de données, 116
énumération
interface DBTools, 364
énumération du mode de sortie, 364
énumération du remplissage avec des blancs, 364
F
fat, curseur, 22
FETCH, instruction
extraction étendue, 215
extraction multiligne, 215
généralités, 211, 212
requête dynamique, 224
fichier
conventions de dénomination, 410
emplacement de déploiement, 409
fichier de réponse
définition, 416
fichier d'écriture
déploiement, 412
É–F
471

G–I
fichier d'en-tête
Embedded SQL, 181
ODBC, 278
fill_s_sqlda, fonction
généralités, 266
fill_sqlda, fonction
généralités, 267
FIXCHAR, type de données
Embedded SQL, 197
fonction
appel des fonctions DBTools, 312
callback, 245
DBTools, 320
Embedded SQL, 251
fonction d'agrégat
Java dans la base de données, 117
fonction de bibliothèque
Embedded SQL, 251
fonctionnalité
support, 392
ForceStart [FORCESTART], paramètre de
connexion
db_start_engine, 263
format
objet Java dans la base de données, 127
forums
support technique, xv
free_filled_sqlda, fonction
généralités, 267
free_sqlda, fonction
généralités, 267
free_sqlda_noind, fonction
généralités, 267
G
gestion
erreur ODBC, 304
gestion de la sécurité Java
présentation, 126
472
gestionnaire de ressources
architecture à trois niveaux, 396
généralités, 394
getConnection, méthode
instance, 160
getObject, méthode
utilisation, 173
GRANT, instruction
JDBC, 170
GROUP BY, clause
Java dans la base de données, 117
guillemet
chaîne Java dans la base de données, 76
I
icône
utilisation dans les manuels, xii
identificateur
fonction SQL_needs_quotes, 268
guillemets nécessaires, 268
import, instruction
jConnect, 148
IMPORT, instruction
Java, 69
Java dans la base de données, 79
INCLUDE, instruction
SQLCA, 205
index
Java dans la base de données, 117, 127, 134
informations
documentation, xv
obtention, xv
INOUT, paramètre
Java dans la base de données, 124
INSENSITIVE, curseur
Embedded SQL, 27
INSERT, instruction
insertion étendue, 215
insertion multiligne, 215
Java dans la base de données, 109

JDBC, 163, 164
objet, 169
performances, 12
insertion
étendue, 215
multiligne, 215
insertion étendue, 215
insertion multiligne, 215
INSTALL, instruction
généralités, 74
utilisation, 102, 103
version de classe, 129
installation
classe Java dans une base de données, 101, 102
fichier JAR dans une base de données, 103
silencieuse, 416
InstallShield
déploiement d'Adaptive Server Anywhere, 414
installation silencieuse, 416
instance
classe Java, 68
instance, champ
généralités, 65
instanciation
définition, 68
instruction
COMMIT, 49
DELETE positionnée, 23
INSERT, 12
PUT, 23
ROLLBACK, 49
SQL, 389
UPDATE positionnée, 23
instruction préparée
curseur, 19
JDBC, 167
objet Java dans la base de données, 111
ODBC, 295
Open Client, 389
paramètre de liaison, 13
suppression, 13
utilisation, 12
Interactive SQL
déploiement, 431
interface
Java, 70
J
Jaguar
EAServer, 401
JAR, fichier
ajout, 103
installation, 101, 103
Java, 69
mise à jour, 104
suppression, 112
version, 104
Java
bloc catch, 71
bloc finally, 71
bloc try, 71
classe, 68
constructeur, 69
destructeur, 70
interface, 70
JDBC, 140
requête sur un objet, 171
traitement des erreurs, 70
Java 2
version supportée, 73
Java dans base de données
insertion, 109
présentation, 92
J–J
Java dans la base de données
API, 58, 73
caractère d'échappement, 78
champ, 64
classe de compilation, 62
classe d'exécution, 95
classe supportée, 59
colonne calculée, 134
comparaison d'objets, 116
conception d'une base de données, 130
configuration d'une base de données, 95, 97, 99
création de colonnes, 106
déchargement et rechargement d'objet, 129
déploiement, 432
didacticiel, 82
durée, 78
environnement d'exécution, 73, 94
473

J–J
espace nom, 138
FAQ, 55
fonctionnalités clés, 55
gestion de la sécurité, 125
index, 117, 127
insertion d'objet, 111
installation de classes, 101
introduction, 52, 62
machine virtuelle, 55, 56, 138
méthode, 64
méthode compareTo, 117
méthode main, 77, 120
mise à jour, 112
mise à jour de valeur, 111
NULL, 106
objet, 63
performances, 127
plate-forme supportée, 57
problème de mémoire, 137
réplication d'objet, 129
requête, 114
stockage, 127
suppression de classe, 112
suppression de ligne, 112
table exemple, 92
taille du segment de mémoire, 138
type de données, 106
utilisation de la documentation, 53
valeur par défaut, 106
version, 73
version de classe, 128
Java, package
classe d'exécution, 95
Java, procédure stockée
généralités, 122
JAVA_HEAP_SIZE, option, 138
JAVA_NAMESPACE_SIZE, option
utilisation, 138
jcatalog.sql, fichier
jConnect, 148
jConnect
base de données, 148
chargement, 149
choix d'un pilote JDBC, 141
connexion, 154, 158
déploiement de clients JDBC, 429
généralités, 147
objet système, 148
474
package, 148
URL, 149
variable d'environnement CLASSPATH, 147
version fournie, 147
JDBC
accès aux données, 162
autocommit, 160
autorisation, 170
classe d'exécution, 95
classe non standard, 142, 143
code de connexion, 154
connexion, 145, 154
connexion à une base de données, 150
connexion cliente, 154
connexion côté serveur, 158
côté client, 145
côté serveur, 145
déploiement de clients JDBC, 429
exemple, 140, 154
élément requis, 140
généralités, 140
instruction INSERT, 163, 164
instruction préparée, 167
instruction SELECT, 166
instruction SQL, 10
jConnect, 147
mode autocommit, 47
présentation, 5
présentation des applications, 141
type de curseur, 25
utilisation, 140
valeurs de connexion par défaut, 160
version, 73, 142, 143
version 2.0, 142, 143
JDBCExamples, classe
généralités, 162
JDBCExamples.java, fichier, 140
jdemo.sql
table exemple, 92
JDK
définition, 58
version, 73, 95
jeu de résultat
procédure stockée, 242
jeu de résultats
curseur, 15
extraction ODBC, 298

métadonnées, 45
méthode Java dans la base de données, 122
objet Recordset d'ADO, 373, 375
ODBC, 297, 302
Open Client, 391
procédure stockée Java dans la base de données,
122
utilisation, 20
jeux de résultats multiples
instruction DESCRIBE, 244
L
lancement, base de données
utilisation de jConnect, 150
langage de programmation C
type de données, 197
langue
nom de fichier, 410
lecture
Embedded SQL, 211
lecture de tableau
généralités, 215
lecture seule
déploiement de bases de données, 433
length, champ SQLDA
généralités, 228, 229
ligne de commande, utilitaire
déploiement, 436
logiciel
code de retour, 313
LONG BINARY, type de données
Embedded SQL, 197, 235
envoi dans Embedded SQL, 238
récupération dans Embedded SQL, 236
LONG VARCHAR, type de données
Embedded SQL, 197, 235
envoi dans Embedded SQL, 238
récupération dans Embedded SQL, 236
longueur de ligne
résultat du préprocesseur SQL, 248
M
machine virtuelle
arrêt, 138
démarrage, 138
macro
_SQL_OS_NETWARE, 184
_SQL_OS_UNIX, 184
_SQL_OS_WINNT, 184
marque de réservation
SQL dynamique, 221
MAX, fonction
Java dans la base de données, 117
mémoire
Java dans la base de données, 137
message
rappel, 261
serveur, 261
message d'erreur
fonction Embedded SQL, 268
méthode
>>, 75
classe, 65
déclaration, 66
instance, 65
Java dans la base de données, 64
opérateur point, 74
privée, 69
protégée, 69
publique, 69
statique, 65
type de renvoi void, 122
méthode de classe
généralités, 65
méthode d'instance
généralités, 65
méthode main
Java dans la base de données, 77, 120
méthode statique
généralités, 65
Microsoft Transaction Server
architecture à trois niveaux, 397
L–M
475

N–O
Microsoft Visual C++
support, 180
MIN, fonction
Java dans la base de données, 117
mise à jour
curseur, 375
mise à jour de base de données, assistant
configuration de la base de données pour Java, 99
mise à jour positionnée, 23
généralités, 21
mlxtract, utilitaire
création personnelle, 357
fichier d'en-tête, 357
mode chaîné
contrôle, 47
mise en oeuvre, 48
transaction, 47
mode commit manuel
contrôle, 47
mise en oeuvre, 48
transaction, 47
mode non chaîné
contrôle, 47
mise en oeuvre, 48
transaction, 47
modificateur d'accès
Java, 69
modification visible
curseur, 30
mot réservé
SQL et Java dans la base de données, 79
mot-clé
SQL et Java dans la base de données, 79
MSDASQL
fournisseur OLE DB, 368
multiples
jeu de résultats ODBC, 302
476
N
name, champ SQLDA
généralités, 228
NetWare
programme Embedded SQL, 185
niveau d'isolement
application, 49
curseur, 21
sensibilité du curseur, 44
NLM
programme Embedded SQL, 185
NO SCROLL, curseur
Embedded SQL, 27
nom de fichier
langue, 410
numéro de version, 410
norme
SQLJ, 52
norme SQLJ
généralités, 52
ntodbc.h, 278
NULL
Java dans la base de données, 106
SQL dynamique, 226
variable indicateur, 201
numéro de ligne
préprocesseur SQL, 249
numéro de version
nom de fichier, 410
O
objet
déchargement et rechargement, 129
extraction, 169
format de stockage, 105
insertion, 169
Java dans la base de données, 63
réplication, 129
requête, 171
type, 63
version de classe, 128

objet Recordset
ADO, 375
ODBC
application exemple, 287
application multithread, 291
bibliothèque d'importation, 278
compatibilité, 277
compatibilité descendante, 277
conformité, 276
curseur, 26, 297
déploiement, 421
déploiement du pilote, 422
descripteur, 285
descripteur de connexion, 285
descripteur d'environnement, 285
descripteur d'instruction, 285
développement UNIX, 280, 282
entrée de registre, 425
exemple de programme, 283
fichier d'en-tête, 278
instruction préparée, 295
instruction SQL, 10
introduction à la programmation, 2
jeu de résultats, 302
jeux de résultats multiples, 302
liaison, 278
mode autocommit, 47
présentation, 276
procédure stockée, 302
programmation, 275
sans gestionnaire de pilotes, 282
source de données, 425
type de curseur, 25
UNIX, 280, 281
vérification d'erreurs, 304
version supportée, 276
Windows CE, 279, 280
ODBC, paramètre
déploiement, 422, 424
odbc.h, 278
OLE DB
Adaptive Server Anywhere, 368
curseur, 26, 375
déploiement, 420
déploiement de fournisseurs, 420
généralités, 368
interface supportée, 378
introduction à la programmation, 3
mise à jour, 375
ODBC, 368
plate-forme supportée, 368
type de curseur, 25
OLE, transaction
architecture à trois niveaux, 396
Open Client
compatibilité des types de données, 387
configuration requise, 386
déploiement d'applications Open Client, 430
instruction SQL, 10
interface, 385
intervalles de types de données, 387
limites, 392
limites d'Adaptive Server Anywhere, 392
mode autocommit, 47
présentation, 6
SQL, 389
type de curseur, 25
type de données, 387
OPEN, instruction
généralités, 212
opérateur point
Java et SQL, 74, 75
option -gn
thread, 121
option QUOTED_IDENTIFIER
définition jConnect, 151
options de base de données
défintion pour jConnect, 151
ORDER BY, clause
Java dans la base de données, 117
OUT, paramètre
Java dans la base de données, 124
O–O
outil de base de données, interface
dbxtract, 330
énumération a_validate_type, 366
énumération dbtran_userlist_type, 365
énumération dbunload_type, 365
énumération du mode de sortie, 364
énumération du remplissage avec des blancs, 364
fonction DBBackup, 320
fonction DBChangeLogName, 320
fonction DBChangeWriteFile, 321
fonction DBCollate, 321
fonction DBCompress, 322
477

P–P
P
478
fonction DBCreate, 322
fonction DBCreateWriteFile, 323
fonction DBCrypt, 323
fonction DBErase, 323
fonction DBExpand, 324
fonction DBInfo, 324
fonction DBInfoDump, 325
fonction DBInfoFree, 325
fonction DBLicense, 326
fonction DBStatusWriteFile, 326
fonction DBToolsFini, 327
fonction DBToolsInit, 328
fonction DBToolsVersion, 328
fonction DBTranslateLog, 329
fonction DBTruncateLog, 329
fonction DBUnload, 330
fonction DBUpgrade, 330
fonction DBValidate, 331
généralités, 309
structure a_backup_db, 332
structure a_change_log, 334
structure a_compress_db, 336
structure a_compress_stats, 337
structure a_create_db, 338
structure a_crypt_db, 340
structure a_db_collation, 341
structure a_db_info, 343
structure a_dblic_info, 346
structure a_dbtools_info, 347
structure a_name, 349
structure a_stats_line, 349
structure a_sync_db, 350
structure a_syncpub, 352
structure a_sysinfo, 352
structure a_table_info, 353
structure a_translate_log, 354
structure a_truncate_log, 356
structure a_validate_db, 360
structure a_writefile, 361
structure an_erase_db, 347
structure an_expand_db, 348
structure an_unload_db, 357
structure an_upgrade_db, 359
package
installation, 103
Java, 69
Java dans la base de données, 79
jConnect, 148
paramètre de liaison
instruction préparée, 13
passerelle JDBC-ODBC
choix d'un pilote JDBC, 141
connexion, 152
déploiement de clients JDBC, 429
fichiers requis, 152
utilisation, 152
performance
JDBC, 167
performances
curseur, 42, 43
instruction préparée, 12, 295
pilotes JDBC, 141
valeur Java dans la base de données, 127
pilote ODBC
UNIX, 281
pilotes JDBC
choix, 141
comptabilité, 141
performances, 141
plate-forme
curseur, 25
plate-forme supportée
Java dans la base de données, 57
OLE DB, 368
point de sauvegarde
curseur, 50
point d'entrée
appel des fonctions DBTools, 312
point d'entrée de DLL, 251
portée
Java, 69
position du curseur
détection et résolution des problèmes, 21
préextraction
curseur, 43
extraction multiligne, 22
performances du curseur, 42

PREFETCH, option
curseur, 43
préparation
commit, 397
PREPARE TRANSACTION, instruction
Open Client, 392
PREPARE, instruction, 221
PreparedStatement, classe
méthode setObject, 111
PreparedStatement, interface
généralités, 167
prepareStatement, méthode, 14
préprocesseur
exécution, 180
généralités, 178
préprocesseur SQL
exécution, 180
généralités, 247
ligne de commande, 247
println, méthode
Java dans la base de données, 77
procédure
Embedded SQL, 241
jeu de résultats, 242
ODBC, 302
procédure d'environnement système sp_tsql_
définition des options pour jConnect, 151
procédure stockée
création dans Embedded SQL, 241
exécution dans Embedded SQL, 241
Java dans la base de données, 122
jeu de résultats, 242
paramètre INOUT et Java, 124
paramètre OUT et Java, 124
procédure stockée Java
exemple, 123
procédure stockée spt_mda
définition des options pour jConnect, 151
processus de compilation et de liaison, 179
programmation orientée objet
Java dans la base de données, 68
style, 81
programme d'installation
déploiement, 407
programme setup
installation silencieuse, 416
propriété
fonction db_get_property, 256
propriété de base de données
fonction db_get_property, 256
protégé
Java, 69
PUT, instruction, 23
insertion étendue, 215
insertion multiligne, 215
PUT, opération, 23
R
rappel
DB_CALLBACK_CONN_DROPPED, 260
Recordset, objet
ADO, 373
récupération
ODBC, 298
registre
déploiement, 422, 424
ODBC, 425
réinscription
transaction distribuée, 396
REMOTEPWD, paramètre, 150
remplissage de blancs
chaîne dans Embedded SQL, 192
réplication
objet Java dans la base de données, 129
reprise
transaction distribuée, 400
requête
annulation, 255
Embedded SQL, 245
Java dans la base de données, 114
JDBC, 166
R–R
479

S–S
ligne unique, 211
objet Recordset d’ADO, 373, 375
requête multiligne
curseur, 212
ROLLBACK TO SAVEPOINT, instruction, 50
curseur, 50
ROLLBACK, instruction
curseur, 49
rt.jar
classe d'exécution, 95
S
sauvegarde
exemple DBTools, 316
fonction DBTools DBBackup, 320
SCROLL, curseur
Embedded SQL, 27
section de déclaration
généralités, 196
sécurité
Java dans la base de données, 125, 126
SecurityManager, classe
généralités, 125, 126
SELECT, instruction
dynamique, 224
Java dans la base de données, 114
JDBC, 166
ligne unique, 211
objet, 169
sensibilité
curseur, 29, 30
exemple de mise à jour, 33
exemple de suppression, 31
niveau d'isolement, 44
SENSITIVE, curseur
Embedded SQL, 27
sérialisation
informatique distribuée, 173
objet, 172
objet de table, 105
objet Java dans la base de données, 127
480
serveur
localisation, 266
serveur de base de données
déploiement, 432
fonction, 265
serveur de synchronisation MobiLink
déploiement, 416
serveur personnel
déploiement, 435
service
code exemple, 191, 284
service Windows
code exemple, 191
setAutocommit, méthode
généralités, 160
setObject, méthode
utilisation, 173
signet, 28
curseur ODBC, 300
sortie standard
Java dans la base de données, 77
SQL
application, 10
application ADO, 10
application Embedded SQL, 10
application JDBC, 10
application ODBC, 10
application Open Client, 10
SQL Anywhere Studio
documentation, viii
SQL dynamique
généralités, 221
SQLDA, 226
SQL Remote
déploiement, 436
objet Java dans la base de données, 129
SQL statique
généralités, 221
SQL/92
préprocesseur SQL, 248
SQL_ATTR_MAX_LENGTH, attribut
généralités, 298

SQL_CALLBACK
déclaration de type, 259
SQL_CALLBACK_PARM
déclaration de type, 259
SQL_ERROR
code de retour ODBC, 304
SQL_INVALID_HANDLE
code de retour ODBC, 304
SQL_NEED_DATA
code de retour ODBC, 304
sql_needs_quotes, fonction
généralités, 268
SQL_NO_DATA_FOUND
code de retour ODBC, 304
SQL_SUCCESS
code de retour ODBC, 304
SQL_SUCCESS_WITH_INFO
code de retour ODBC, 304
SQL92
préprocesseur SQL, 248
SQLAllocHandle, fonction ODBC
généralités, 285, 292
paramètres de liaison, 293
utilisation, 286
SQLBindCol, fonction ODBC
généralités, 297, 298
SQLBindParameter
fonction ODBC, 14
SQLBindParameter, fonction ODBC
généralités, 293
instruction préparée, 295
procédures stockées, 302
SQLBrowseConnect, fonction ODBC
généralités, 288
SQLCA
champ, 205
généralités, 205
longueur, 205
modification, 208
threads, 208
zones multiples, 208, 209
sqlcabc, champ SQLCA
généralités, 205
sqlcaid, champ SQLCA
généralités, 205
sqlcode, champ SQLCA
généralités, 205
SQLConnect, fonction ODBC
généralités, 288
SQLCOUNT
élément de champ SQLCA, 207
sqld, champ SQLDA
généralités, 227
SQLDA
allocation, 251
chaînes, 267
champ sqllen, 229
descripteur, 46
généralités, 221, 226
libération, 266
remplissage, 267
variable hôte, 228
sqlda_storage, fonction
généralités, 268
sqlda_string_length, fonction
généralités, 268
sqldabc, champ SQLDA
généralités, 227
sqldaif, champ SQLDA
généralités, 227
sqldata, champ SQLDA
généralités, 228
sqldef.h
type de données, 192
SQLDriverConnect, fonction ODBC
généralités, 288
sqlerrd, champ SQLCA
généralités, 206
sqlerrmc, champ SQLCA
généralités, 206
sqlerrml, champ SQLCA
généralités, 206
S–S
481

S–S
sqlerror, champ SQLCA
élément, 206
SQLCOUNT, 207
SQLIOCOUNT, 206
SQLIOESTIMATE, 208
SQLError, fonction ODBC
généralités, 304
sqlerror_message, fonction
généralités, 268
sqlerrp, champ SQLCA
généralités, 206
SQLExecDirect, fonction ODBC
généralités, 292
paramètres de liaison, 293
SQLExecute
fonction ODBC, 14
SQLExtendedFetch, fonction ODBC
généralités, 298
procédures stockées, 302
SQLFetch, fonction ODBC
généralités, 298
procédures stockées, 302
SQLFreeHandle, fonction ODBC
utilisation, 286
SQLFreeStmt
fonction ODBC, 14
SQLGetData, fonction ODBC
généralités, 297, 298
sqlind, champ SQLDA
généralités, 228
SQLIOCOUNT
élément de champ SQLCA, 206
SQLIOESTIMATE
élément de champ SQLCA, 208
sqllen, champ SQLDA
description de valeurs, 230
envoi de valeurs, 231
extraction de valeurs, 233
généralités, 228, 229
instruction DESCRIBE, 230
sqlname, champ SQLDA
généralités, 228
482
SQLNumResultCols, fonction ODBC
procédures stockées, 302
SQLPP
généralités, 178
ligne de commande, 247
SQLPrepare
fonction ODBC, 14
SQLPrepare, fonction ODBC
généralités, 295
SQLRETURN
code de retour ODBC, 304
SQLSetConnectAttr, fonction ODBC
généralités, 290
SQLSetPos, fonction ODBC
généralités, 300
SQLSetStmtAttr, fonction ODBC
caractéristiques d'un curseur, 297
sqlstate, champ SQLCA
généralités, 206
SQLTransact, fonction ODBC
généralités, 287
sqltype, champ SQLDA
généralités, 228
instruction DESCRIBE, 230
sqlvar, champ SQLDA
contenu, 228
généralités, 227, 228
sqlwarn, champ SQLCA
généralités, 206
START JAVA, instruction
utilisation, 138
stockage
objet Java dans la base de données, 127
stockage d'objet
Java dans la base de données, 127
STOP JAVA, instruction
utilisation, 138
structure de répertoires
UNIX, 409
structure des programmes
Embedded SQL, 183

Sun, package
classe d'exécution, 95
support
forums, xv
support technique
forums, xv
suppression
classe Java, 112
fichier JAR, 112
suppression positionnée, 23
Sybase Central
ajout de classes Java, 102
ajout de fichiers JAR, 103
ajout de fichiers ZIP, 103
configuration de la base de données pour Java, 99
déploiement, 431
sybase.sql, package
classe d'exécution, 95
sybase.sql.ASA, package
JDBC 2.0, 143
System Management Server
déploiement, 418
système d'exploitation
nom de fichier, 410
T
table de travail
performances du curseur, 42
taille du segment de mémoire
Java dans la base de données, 138
this
méthode Java dans la base de données, 122
thread
application ODBC, 291
développement UNIX, 280
Embedded SQL, 208
Java dans la base de données, 121
ODBC, 276
TIMESTAMP, type de données
conversion, 387
traitement des erreurs
Java, 70
traitement en arrière-plan
fonctions callback, 245
transaction
curseur, 49
développement d'applications, 47
distribuée, 399
mode autocommit, 47
niveau d'isolement, 49
ODBC, 287
transaction distribuée, 394
architecture, 396, 397
architecture à trois niveaux, 396
EAServer, 401
généralités, 393, 394, 399
réinscription, 396
reprise, 400
transférabilité
définition, 137
troncature
instruction FETCH, 202
sur FETCH, 202
variable indicateur, 202
type
objet, 63
type de données
Embedded SQL, 192
intervalles, 387
Java dans la base de données, 106
langage C, 197
mappage, 387
Open Client, 387
SQL dynamique, 226
SQLDA, 228
variable hôte, 197
type de données Java
extraction, 169
insertion, 169
type de données, conversion
variable indicateur, 203
T–T
483

U–Z
U
Unicode
ODBC, 279
Windows CE, 279
UNIX
application multithread, 410
application ODBC, 282
remarque sur le déploiement, 409
structure de répertoires, 409
unixodbc.h, 278
UPDATE, instruction
Java dans la base de données, 111
méthode SET, 112
positionnée, 23
URL
base de données, 150
jConnect, 149
utilisation de Java dans la base de données, 91
utilitaire
déploiement d'utilitaires de base de données, 436
préprocesseur SQL, 247
V
valeur par défaut
Java dans la base de données, 106
VARCHAR, type de données
Embedded SQL, 197
variable de liaison
généralités, 221
variable hôte
déclaration, 196
généralités, 196
SQLDA, 228
type de données, 197
utilisation, 200
variable indicateur
conversion des types de données, 203
généralités, 201
NULL, 201
484
récapitulatif des valeurs, 203
SQLDA, 228
troncature, 202
version
classe, 128
Java dans la base de données, 73
JDBC, 73
JDK, 73
Visual C++
support, 180
VM
machine virtuelle Java, 56
void
méthode Java dans la base de données, 64, 122
W
Watcom C/C++
support, 180
Windows
service, 284
Windows CE
dbtool8.dll, 310
Java dans la base de données non supporté, 57
ODBC, 279, 280
OLE DB, 368
version supportée, 368
WITH HOLD, clause
curseur, 21
Z
zip, fichier
Java, 69
zone de communication SQL
généralités, 205