API Guide

368 Pages·2011·2.01 MB·English

by  Borland Software Corp.

API Guide
InterBase XE
April, 2011
Copyright © 1994-2011 Embarcadero Technologies, Inc.
Embarcadero Technologies, Inc.
100 California Street, 12th Floor
San Francisco, CA 94111 U.S.A.
All rights reserved.
All brands and product names are trademarks or registered trademarks of their respective owners.
This software/documentation contains proprietary information of Embarcadero Technologies, Inc.;
it is provided under a license agreement containing restrictions on use and disclosure and is also
protected by copyright law. Reverse engineering of the software is prohibited.
If this software/documentation is delivered to a U.S. Government Agency of the Department of
Defense, then it is delivered with Restricted Rights and the following legend is applicable:
Restricted Rights Legend Use, duplication, or disclosure by the Government is subject to restrictions
as set forth in subparagraph (c)(1)(ii) of DFARS 252.227-7013, Rights in Technical Data and Computer
Software (October 1988).
If this software/documentation is delivered to a U.S. Government Agency not within the Department
of Defense, then it is delivered with Restricted Rights, as defined in FAR 552.227-14, Rights in
Data-General, including Alternate III (June 1987).
Information in this document is subject to change without notice. Revisions may be issued to advise
of such changes and additions. Embarcadero Technologies, Inc. does not warrant that this
documentation is error-free.
Contents
Tables . . . . . . . . . . . . . . . . . . . . . . . . . ix Using C/C++ Builder . . . . . . . . . . . . . . .3-7
Setting up the Integrated Development Environment
Chapter 1
(IDE). . . . . . . . . . . . . . . . . . . . . . .3-8
Using the API Guide IDE default. . . . . . . . . . . . . . . . . . .3-8
Who should use this guide. . . . . . . . . . . . . . 1-1 IDE Project Options dialog box . . . . . . . .3-8
Topics covered in this guide. . . . . . . . . . . . . 1-1 Directories . . . . . . . . . . . . . . . . .3-8
Sample database and applications . . . . . . . . . . 1-3 Compiler . . . . . . . . . . . . . . . . . .3-8
Linker . . . . . . . . . . . . . . . . . . .3-8
Chapter 2 The module definition file. . . . . . . . . . . . .3-8
Using dynamic link libraries (DLLs) . . . . . . .3-9
Application Requirements
Example programs . . . . . . . . . . . . . . . .3-9
Requirements for all applications . . . . . . . . . . 2-1
Including ibase.h . . . . . . . . . . . . . . . . . 2-2 Chapter 4
Database requirements . . . . . . . . . . . . . . 2-2
Working with Databases
Declaring database handles. . . . . . . . . . 2-2
Connecting to databases . . . . . . . . . . . . . . .4-1
Setting up a DPB . . . . . . . . . . . . . . . 2-2
Creating database handles. . . . . . . . . . . . .4-2
Transaction requirements. . . . . . . . . . . . . 2-3
Declaring database handles . . . . . . . . . .4-2
Declaring transaction handles . . . . . . . . 2-3
Initializing database handles. . . . . . . . . .4-2
Setting up a TPB . . . . . . . . . . . . . . . 2-3
Creating and populating a DPB. . . . . . . . . .4-3
Additional requirements. . . . . . . . . . . . . . . 2-3
DPB parameters. . . . . . . . . . . . . . . . . .4-4
Microsoft Windows requirements . . . . . . . . 2-3
Adding parameters to a DPB . . . . . . . . . . .4-7
DSQL requirements . . . . . . . . . . . . . . . 2-4
Attaching to a database . . . . . . . . . . . . . .4-8
Blob requirements . . . . . . . . . . . . . . . . 2-4
Requesting information about an attachment. . . . 4-10
Array requirements. . . . . . . . . . . . . . . . 2-5
The request buffer. . . . . . . . . . . . . . . . 4-10
Event requirements. . . . . . . . . . . . . . . . 2-5
The result buffer. . . . . . . . . . . . . . . . . 4-10
Error-handling requirements . . . . . . . . . . . 2-6
Status information. . . . . . . . . . . . . . . . 4-11
Services requirements . . . . . . . . . . . . . . 2-6
Request buffer items and result buffer values. . 4-11
Compiling and linking. . . . . . . . . . . . . . . . 2-6
Database characteristics . . . . . . . . . . . 4-11
Chapter 3 Environmental characteristics . . . . . . . . 4-12
Performance statistics . . . . . . . . . . . . 4-13
Programming with
Database operation counts. . . . . . . . . . 4-14
the InterBase API
isc_database_info() call example . . . . . . . . 4-15
Basic procedure for application development. . . . 3-1 Disconnecting from databases . . . . . . . . . . . 4-15
Supported development environments. . . . . . . . 3-1 Deleting a database . . . . . . . . . . . . . . . . . 4-16
User name and password requirements . . . . . . . 3-2
Chapter 5
Specifying user name and password. . . . . . . . . 3-2
Using environment variables . . . . . . . . . . . . 3-3 Working with Transactions
Setting a default database directory . . . . . . . 3-4
Starting transactions . . . . . . . . . . . . . . . . .5-2
Setting a user name and password . . . . . . . . 3-4
Creating transaction handles . . . . . . . . . . .5-2
Datatypes . . . . . . . . . . . . . . . . . . . . . . 3-4
Declaring transaction handles . . . . . . . . .5-3
Calling conventions . . . . . . . . . . . . . . . . . 3-4
Initializing transaction handles . . . . . . . .5-3
Building applications . . . . . . . . . . . . . . . . 3-5
Creating a transaction parameter buffer. . . . . .5-3
Compilers . . . . . . . . . . . . . . . . . . . . 3-5
Specifying the transaction version number . .5-6
Linking. . . . . . . . . . . . . . . . . . . . . . 3-5
Specifying access mode . . . . . . . . . . . .5-6
Include files . . . . . . . . . . . . . . . . . . . 3-6
Specifying isolation level . . . . . . . . . . .5-6
Using Microsoft C++. . . . . . . . . . . . . . . 3-6
isc_tpb_concurrency . . . . . . . . . . . .5-6
iii
isc_tpb_read_committed . . . . . . . . . 5-7 Setting a NULL indicator. . . . . . . . . . . 6-15
isc_tpb_consistency. . . . . . . . . . . . 5-7 Aligning numerical data. . . . . . . . . . . . . 6-15
Isolation level interactions . . . . . . . . 5-7 DSQL programming methods . . . . . . . . . . . 6-16
Specifying lock resolution . . . . . . . . . . 5-8 Method 1: Non-query statements without parameters
Specifying conflict resolution . . . . . . . . 5-9 6-16
Specifying table reservation . . . . . . . . . 5-9 Using isc_dsql_execute_immediate() . . . . 6-16
Using the default TPB . . . . . . . . . . . .5-10 Using isc_dsql_prepare() and isc_dsql_execute().
Calling isc_start_transaction(). . . . . . . . . .5-11 6-17
Calling isc_start_multiple() . . . . . . . . . . .5-11 Method 2: Non-query statements with parameters . .
Use of Commit/Rollback with Multidatabase 6-17
Transactions . . . . . . . . . . . . . . . . . .5-13 Creating the input XSQLDA . . . . . . . . . 6-17
Ending transactions . . . . . . . . . . . . . . . . .5-13 Preparing and executing a statement string with
Using isc_commit_transaction(). . . . . . . . .5-14 parameters . . . . . . . . . . . . . . . . . 6-18
Using isc_commit_retaining() . . . . . . . . . .5-14 Re-executing the statement string . . . . . . 6-20
Working with savepoints. . . . . . . . . . . . .5-15 Method 3: Query statements without parameters6-20
A SAVEPOINT example . . . . . . . . .5-15 Preparing the output XSQLDA. . . . . . . . 6-20
Using isc_prepare_transaction() . . . . . . . . .5-16 Preparing a query statement string without
Using isc_prepare_transaction2() . . . . . . . .5-17 parameters . . . . . . . . . . . . . . . . . 6-21
Using isc_rollback_transaction() . . . . . . . .5-17 Executing a statement string within the context of
Using isc_rollback_retaining(). . . . . . . . . .5-17 a cursor. . . . . . . . . . . . . . . . . . . 6-22
Re-executing a query statement string without
Chapter 6 parameters . . . . . . . . . . . . . . . . . 6-23
Working with Dynamic SQL Method 4: Query statements with parameters. . 6-23
Preparing the input XSQLDA . . . . . . . . 6-24
Overview of the DSQL programming process . . . 6-1
Preparing the output XSQLDA. . . . . . . . 6-24
DSQL API limitations. . . . . . . . . . . . . . . . 6-1
Preparing a query statement string
Accessing databases . . . . . . . . . . . . . . . 6-2
withparameters . . . . . . . . . . . . . . 6-25
Handling transactions . . . . . . . . . . . . . . 6-3
Executing a query statement string within the
Creating a database. . . . . . . . . . . . . . . . 6-3
context of a cursor . . . . . . . . . . . . . 6-27
Processing Blob data. . . . . . . . . . . . . . . 6-4
Re-executing a query statement string
Processing array data. . . . . . . . . . . . . . . 6-4
withparameters . . . . . . . . . . . . . . 6-28
Writing an API application to process SQL statements .
Determining an unknown statement type at runtime6-29
6-4
Determining if API calls can process a SQL
Chapter 7
statement . . . . . . . . . . . . . . . . . . . . 6-5
Working with Blob Data
Representing a SQL statement as a character string.
6-5 What is a Blob?. . . . . . . . . . . . . . . . . . . .7-2
Specifying parameters in SQL statement strings. 6-5 How is Blob data stored? . . . . . . . . . . . . .7-2
Understanding the XSQLDA. . . . . . . . . . . . . 6-6 Blob subtypes . . . . . . . . . . . . . . . . . . .7-3
XSQLDA field descriptions. . . . . . . . . . . . 6-8 Blob database storage . . . . . . . . . . . . . . .7-3
XSQLVAR field descriptions . . . . . . . . . . . 6-9 Blob descriptors. . . . . . . . . . . . . . . . . . . .7-3
Input descriptors . . . . . . . . . . . . . . . . .6-10 Populating a Blob descriptor . . . . . . . . . . . . .7-4
Output descriptors . . . . . . . . . . . . . . . .6-10 Blob data operations . . . . . . . . . . . . . . . . .7-5
Using the XSQLDA_LENGTH macro . . . . . .6-11 Reading data from a Blob. . . . . . . . . . . . .7-5
SQL datatype macro constants. . . . . . . . . .6-11 Creating the SELECT statement . . . . . . . .7-6
Handling varying string datatypes . . . . . . . .6-13 Preparing the output XSQLDA. . . . . . . . .7-6
Handling NUMERIC and DECIMAL datatypes . .6-14 Preparing the SELECT statement for execution7-6
Coercing datatypes. . . . . . . . . . . . . . . .6-14 Executing the statement . . . . . . . . . . . .7-8
Coercing character datatypes. . . . . . . . .6-14 Fetching selected rows. . . . . . . . . . . . .7-8
Coercing numeric datatypes . . . . . . . . .6-15 Reading and processing the Blob data. . . . .7-8
iv
Writing data to a Blob . . . . . . . . . . . . . . 7-9 Deleting an array . . . . . . . . . . . . . . . . 8-14
Preparing the UPDATE or INSERT statement .7-10
Creating a new Blob and storing data . . . .7-11 Chapter 9
Associating the new Blob with the Blob column. Working with Conversions
7-12
Converting date and times from InterBase to C format .
Deleting a Blob. . . . . . . . . . . . . . . . . .7-12
9-2
Requesting information about an open Blob . . . .7-13
Converting dates from C to InterBase format . . . .9-3
The item-list buffer. . . . . . . . . . . . . . . .7-13
Reversing the byte order of numbers. . . . . . . . .9-3
The result buffer . . . . . . . . . . . . . . . . .7-13
Blob buffer items. . . . . . . . . . . . . . . . .7-14 Chapter 10
Status messages . . . . . . . . . . . . . . . . .7-14
Handling Error Conditions
isc_blob_info() call example. . . . . . . . . . .7-15
Filtering Blob data. . . . . . . . . . . . . . . . . .7-16 Setting up an error status vector . . . . . . . . . . 10-1
Using your own filters . . . . . . . . . . . . . .7-16 Using information in the status vector . . . . . . . 10-2
Declaring an external Blob filter to the database 7-16 Checking the status vector for errors . . . . . . 10-2
Writing an external Blob filter . . . . . . . . . .7-17 Displaying InterBase error messages . . . . . . 10-3
Defining the filter function . . . . . . . . . .7-17 Capturing InterBase error messages . . . . . . 10-3
Defining the Blob control structure. . . . . .7-18 Setting a SQLCODE value on error . . . . . . . . . 10-4
Programming filter function actions . . . . .7-20 Displaying SQL error messages. . . . . . . . . 10-5
Writing an application that requests filtering . .7-21 Capturing SQL error messages . . . . . . . . . 10-5
Understanding the Blob parameter buffer . .7-21 Parsing the status vector . . . . . . . . . . . . . . 10-6
Generating a Blob parameter buffer using API How the status vector is parsed . . . . . . . . . 10-6
calls . . . . . . . . . . . . . . . . . . . . .7-22 Meaning of the first long in a cluster . . . . . . 10-7
Generating a Blob parameter buffer directly .7-23 Meaning of the second long in a cluster . . . . 10-8
Requesting filter usage . . . . . . . . . . . .7-24 InterBase error codes . . . . . . . . . . . . 10-8
String addresses . . . . . . . . . . . . . . . 10-9
Chapter 8 String length indicators . . . . . . . . . 10-9
Working with Array Data Numeric values. . . . . . . . . . . . . . 10-9
Operating system error codes . . . . . . 10-9
Introduction to arrays . . . . . . . . . . . . . . . . 8-1
Meaning of the third long in a cluster. . . . . 10-10
Array database storage. . . . . . . . . . . . . . 8-2
Status vector parsing example. . . . . . . . . 10-10
Array descriptors. . . . . . . . . . . . . . . . . 8-2
Populating an array descriptor . . . . . . . . . . 8-4 Chapter 11
Accessing array data. . . . . . . . . . . . . . . . . 8-5
Working with Events
Reading data from an array . . . . . . . . . . . 8-5
Creating the SELECT statement. . . . . . . . 8-6 Understanding the event mechanism . . . . . . . . 11-1
Preparing the output XSQLDA . . . . . . . . 8-6 Event parameter buffers. . . . . . . . . . . . . 11-2
Preparing the SELECT statement for execution8-6 Synchronous event notification . . . . . . . . . 11-2
Executing the statement . . . . . . . . . . . 8-8 Asynchronous event notification . . . . . . . . 11-2
Populating the array descriptor. . . . . . . . 8-8 Transaction control of events . . . . . . . . . . 11-3
Fetching selected rows . . . . . . . . . . . . 8-9 Creating EPBs with isc_event_block(). . . . . . . 11-3
Reading and processing the array data . . . . 8-9 Waiting on events with isc_wait_for_event(). . . . 11-4
Writing data to an array . . . . . . . . . . . . .8-10 Continuous processing with isc_que_events() . . . 11-5
Preparing the array descriptor . . . . . . . .8-10 Creating an AST. . . . . . . . . . . . . . . . . 11-5
Preparing the array buffer with data . . . . .8-11 A complete isc_que_events() example . . . . . 11-6
Preparing the UPDATE or INSERT statement .8-12 Determining which events occurred with
Calling isc_array_put_slice2() . . . . . . . .8-13 isc_event_counts() . . . . . . . . . . . . . . . . 11-7
Associating the new array with the array column Canceling interest with isc_cancel_events() . . . . 11-8
8-14
v
Chapter 12 Chapter 13
Working with Services Using the Install and
Overview of the Services API. . . . . . . . . . . .12-1 Licensing APIs
General information . . . . . . . . . . . . . . .12-1
About the InterBase Install API . . . . . . . . . . 13-2
Using services parameter buffers . . . . . . . .12-2
Files in the Install API . . . . . . . . . . . . . 13-2
Attaching to the Services Manager with
What the Install API does. . . . . . . . . . . . 13-3
isc_service_attach() . . . . . . . . . . . . . .12-3
What the Install API does not do . . . . . . 13-3
Detaching from a Services Manager with
The Install API functions . . . . . . . . . . . . 13-3
isc_service_detach(). . . . . . . . . . . . . .12-4
The install handle . . . . . . . . . . . . . . . . 13-4
Invoking service tasks with isc_service_start(). . .12-4
Error handling. . . . . . . . . . . . . . . . . . 13-5
Using request buffers. . . . . . . . . . . . . . .12-4
Callback functions. . . . . . . . . . . . . . . . 13-5
Overview of task identifiers . . . . . . . . . . .12-5
fp_status() . . . . . . . . . . . . . . . . . . 13-5
Generic Services API Parameters . . . . . . . .12-5
fp_error() . . . . . . . . . . . . . . . . . . 13-6
Backing up and restoring databases . . . . . . .12-6
Datatypes defined for the Install API . . . . . . 13-7
Setting database properties. . . . . . . . . . . 12-11
Writing an InterBase install. . . . . . . . . . . . . 13-7
Invoking database maintenance . . . . . . . . 12-13
Overview of the process. . . . . . . . . . . . . 13-7
Invoking a database validation . . . . . . . 12-13
Using the License API . . . . . . . . . . . . . . . 13-9
Invoking a database sweep . . . . . . . . . 12-14
Loading the License API . . . . . . . . . . . . 13-9
Resolving limbo transactions. . . . . . . . 12-15
Preparing the ib_license.dat file. . . . . . . . . 13-9
Requesting database and server status reports . 12-16
Adding server functionality. . . . . . . . . . 13-10
Requesting database statistics . . . . . . . 12-16
Pseudocode for a typical install. . . . . . . . . . 13-10
Requesting the server log. . . . . . . . . . 12-16
Configuring users . . . . . . . . . . . . . . . 12-17 Chapter 14
Listing valid users in the security database. 12-17
Exporting XML
Adding a user to the security database . . . 12-17
Removing a user from the security database12-18 Using the InterBase API to generate XML. . . . . 14-1
Modifying a user in the security database . 12-18 The IB_XMLDA structure . . . . . . . . . . . 14-2
Deprecated use of older user functions. . . 12-19 Required elements of the IB_XMLDA structure .
Administering software activation certificates. 12-19 14-3
Listing software activation certificates. . . 12-19 Optional elements of the IB_XMLDA structure .
Adding a software activation certificate . . 12-19 14-3
Removing a software activation certificate. 12-19 Defines. . . . . . . . . . . . . . . . . . . . 14-4
Enabling changes to certificates . . . . . . 12-19 Using the xmlda_flags . . . . . . . . . . . . . 14-4
Querying the Services Manager . . . . . . . . . . 12-20 XMLDA_ATTRIBUTE_FLAG. . . . . . . 14-4
Blocking and specifying timeout. . . . . . . . 12-20 XMLDA_NO_HEADER . . . . . . . . . . 14-5
Services API query example. . . . . . . . . . 12-21 A complete example . . . . . . . . . . . . . . . . 14-5
Using result buffers . . . . . . . . . . . . . . 12-21 XML output structure . . . . . . . . . . . . . . 14-5
Querying server configuration . . . . . . . . . 12-22 The C program . . . . . . . . . . . . . . . . . 14-6
Additional data for server configuration . . 12-25 The XML output. . . . . . . . . . . . . . . 14-8
Software activation certificates . . . . . 12-25
Chapter 15
Server configuration properties. . . . . 12-26
Querying security configuration . . . . . . . . 12-28 API Function Reference
Additional data for security information . . 12-29 Function categories . . . . . . . . . . . . . . . . . 15-1
Querying service tasks . . . . . . . . . . . . . 12-32 Array functions . . . . . . . . . . . . . . . . . 15-2
Additional data for task results. . . . . . . 12-33 Blob functions. . . . . . . . . . . . . . . . . . 15-2
Using the Services API with Delphi and C++Builder. . Database functions . . . . . . . . . . . . . . . 15-3
12-34 Conversion functions . . . . . . . . . . . . . . 15-3
DSQL functions. . . . . . . . . . . . . . . . . 15-4
vi
Error-handling functions . . . . . . . . . . . . .15-5 isc_dsql_describe_bind() . . . . . . . . . . . . . 15-61
Event functions. . . . . . . . . . . . . . . . . .15-5 isc_dsql_execute() . . . . . . . . . . . . . . . . 15-63
Information functions . . . . . . . . . . . . . .15-6 isc_dsql_execute2(). . . . . . . . . . . . . . . . 15-66
Install functions . . . . . . . . . . . . . . . . .15-6 isc_dsql_execute_immediate() . . . . . . . . . . 15-69
Licensing functions . . . . . . . . . . . . . . .15-7 isc_dsql_exec_immed2() . . . . . . . . . . . . . 15-72
Services functions . . . . . . . . . . . . . . . .15-7 isc_dsql_fetch(). . . . . . . . . . . . . . . . . . 15-73
Transaction control functions . . . . . . . . . .15-8 isc_dsql_free_statement(). . . . . . . . . . . . . 15-76
Using function definitions. . . . . . . . . . . . . .15-9 isc_dsql_prepare() . . . . . . . . . . . . . . . . 15-78
isc_add_user() . . . . . . . . . . . . . . . . . . . .15-9 isc_dsql_set_cursor_name() . . . . . . . . . . . 15-80
isc_array_get_slice(). . . . . . . . . . . . . . . . 15-11 isc_dsql_sql_info() . . . . . . . . . . . . . . . . 15-82
isc_array_get_slice2() . . . . . . . . . . . . . . . 15-12 isc_dsql_xml_buffer_fetch() . . . . . . . . . . . 15-83
isc_array_lookup_bounds() . . . . . . . . . . . . 15-15 isc_dsql_xml_fetch() . . . . . . . . . . . . . . . 15-85
isc_array_lookup_bounds2() . . . . . . . . . . . 15-15 isc_dsql_xml_fetch_all() . . . . . . . . . . . . . 15-86
isc_array_lookup_desc(). . . . . . . . . . . . . . 15-17 isc_encode_sql_date() . . . . . . . . . . . . . . 15-87
isc_array_lookup_desc2() . . . . . . . . . . . . . 15-17 isc_encode_sql_time() . . . . . . . . . . . . . . 15-88
isc_array_put_slice(). . . . . . . . . . . . . . . . 15-20 isc_encode_timestamp() . . . . . . . . . . . . . 15-89
isc_array_put_slice2() . . . . . . . . . . . . . . . 15-20 isc_event_block(). . . . . . . . . . . . . . . . . 15-90
isc_array_set_desc() . . . . . . . . . . . . . . . . 15-25 isc_event_counts() . . . . . . . . . . . . . . . . 15-91
isc_array_set_desc2() . . . . . . . . . . . . . . . 15-25 isc_expand_dpb(). . . . . . . . . . . . . . . . . 15-92
isc_attach_database() . . . . . . . . . . . . . . . 15-27 isc_get_client_version() . . . . . . . . . . . . . 15-93
isc_blob_default_desc() . . . . . . . . . . . . . . 15-29 isc_get_client_major_version(). . . . . . . . . . 15-94
isc_blob_default_desc2() . . . . . . . . . . . . . 15-29 isc_get_client_minor_version(). . . . . . . . . . 15-94
isc_blob_gen_bpb() . . . . . . . . . . . . . . . . 15-31 isc_get_segment(). . . . . . . . . . . . . . . . . 15-94
isc_blob_gen_bpb2() . . . . . . . . . . . . . . . 15-31 isc_install_clear_options() . . . . . . . . . . . . 15-96
isc_blob_info(). . . . . . . . . . . . . . . . . . . 15-32 isc_install_execute() . . . . . . . . . . . . . . . 15-97
isc_blob_lookup_desc() . . . . . . . . . . . . . . 15-33 isc_install_get_info() . . . . . . . . . . . . . . . 15-98
isc_blob_lookup_desc2() . . . . . . . . . . . . . 15-34 isc_install_get_message(). . . . . . . . . . . . .15-100
isc_blob_set_desc() . . . . . . . . . . . . . . . . 15-35 isc_install_load_external_text() . . . . . . . . .15-100
isc_blob_set_desc2(). . . . . . . . . . . . . . . . 15-36 isc_install_precheck(). . . . . . . . . . . . . . .15-100
isc_cancel_blob() . . . . . . . . . . . . . . . . . 15-37 isc_install_set_option(). . . . . . . . . . . . . .15-102
isc_cancel_events() . . . . . . . . . . . . . . . . 15-38 isc_install_unset_option() . . . . . . . . . . . .15-104
isc_close_blob() . . . . . . . . . . . . . . . . . . 15-39 isc_interprete() . . . . . . . . . . . . . . . . . .15-104
isc_commit_retaining() . . . . . . . . . . . . . . 15-40 isc_license_add() . . . . . . . . . . . . . . . . .15-105
isc_commit_transaction() . . . . . . . . . . . . . 15-41 isc_license_check(). . . . . . . . . . . . . . . .15-106
isc_create_blob2() . . . . . . . . . . . . . . . . . 15-42 isc_license_remove() . . . . . . . . . . . . . . .15-107
isc_create_database() . . . . . . . . . . . . . . . 15-44 isc_license_display() . . . . . . . . . . . . . . .15-108
isc_database_info() . . . . . . . . . . . . . . . . 15-44 isc_license_get_msg() . . . . . . . . . . . . . .15-108
isc_decode_sql_date() . . . . . . . . . . . . . . . 15-46 isc_modify_user(). . . . . . . . . . . . . . . . .15-109
isc_decode_sql_time(). . . . . . . . . . . . . . . 15-47 isc_open_blob2() . . . . . . . . . . . . . . . . . 15-111
isc_decode_timestamp(). . . . . . . . . . . . . . 15-47 isc_portable_integer(). . . . . . . . . . . . . . . 15-113
isc_delete_user(). . . . . . . . . . . . . . . . . . 15-48 isc_prepare_transaction(). . . . . . . . . . . . . 15-113
isc_detach_database() . . . . . . . . . . . . . . . 15-51 isc_prepare_transaction2() . . . . . . . . . . . . 15-115
isc_drop_database() . . . . . . . . . . . . . . . . 15-52 isc_print_sqlerror() . . . . . . . . . . . . . . . . 15-116
isc_dsql_allocate_statement() . . . . . . . . . . . 15-52 isc_print_status() . . . . . . . . . . . . . . . . . 15-117
isc_dsql_alloc_statement2() . . . . . . . . . . . . 15-54 isc_put_segment() . . . . . . . . . . . . . . . . 15-117
isc_dsql_batch_execute . . . . . . . . . . . . . . 15-55 isc_que_events() . . . . . . . . . . . . . . . . . 15-119
isc_dsql_batch_execute_immed. . . . . . . . . . 15-58 isc_rollback_retaining(). . . . . . . . . . . . . .15-122
New Error Conditions. . . . . . . . . . 15-59 isc_rollback_transaction() . . . . . . . . . . . .15-123
isc_dsql_describe() . . . . . . . . . . . . . . . . 15-60 isc_service_attach(). . . . . . . . . . . . . . . .15-124
vii
isc_service_detach() . . . . . . . . . . . . . . . 15-125 isc_uninstall_execute() . . . . . . . . . . . . . .15-136
isc_service_query() . . . . . . . . . . . . . . . 15-126 isc_uninstall_precheck() . . . . . . . . . . . . .15-137
isc_service_start() . . . . . . . . . . . . . . . . 15-127 isc_vax_integer() . . . . . . . . . . . . . . . . .15-137
isc_sqlcode(). . . . . . . . . . . . . . . . . . . 15-128 isc_version() . . . . . . . . . . . . . . . . . . .15-138
isc_sql_interprete() . . . . . . . . . . . . . . . 15-128 isc_wait_for_event() . . . . . . . . . . . . . . .15-140
isc_start_multiple() . . . . . . . . . . . . . . . 15-129
Index . . . . . . . . . . . . . . . . . . . . . . . .I-143
isc_start_transaction() . . . . . . . . . . . . . . 15-132
isc_transaction_info() . . . . . . . . . . . . . . 15-134
viii
Tables
1.1 API Guide chapters. . . . . . . . . . . . . . 1-2 12.1 Syntax of Services Manager connect string, by
3.1 Environment variables used by InterBase . . 3-3 protocol . . . . . . . . . . . . . . . . . . . 12-3
3.2 InterBase library file names . . . . . . . . . 3-6 12.2 Services API tasks. . . . . . . . . . . . . . 12-5
3.3 Microsoft C compiler options . . . . . . . . 3-6 12.3 Generic Services API Parameters . . . . . . 12-6
3.4 C++ Builder compiler options . . . . . . . . 3-7 12.4 Services API database backup arguments. . 12-7
4.1 API database functions . . . . . . . . . . . . 4-1 12.5 Services API database restore arguments . . 12-9
4.2 DPB parametersgrouped by purpose. . . . . 4-4 12.6 Services API database properties arguments12-11
4.3 Alphabetical list of DPB parameters . . . . . 4-5 12.7 Services API database validation arguments12-14
4.4 DPB parameters recognized by 12.8 Services API database sweep arguments . 12-15
isc_expand_dpb() . . . . . . . . . . . . . . 4-7 12.9 Services API limbo transaction arguments 12-15
4.5 isc_expand_dbp() parameters. . . . . . . . . 4-8 12.10 Services API status report arguments . . . 12-16
4.6 Status message return items . . . . . . . . .4-11 12.11 Services API display users arguments. . . 12-17
4.7 Database information items for database 12.12 Services API arguments for
characteristics. . . . . . . . . . . . . . . . .4-12 isc_action_svc_add_user . . . . . . . . . 12-17
4.8 Database information items for environmental 12.13 Services API remove user arguments . . . 12-18
characteristics. . . . . . . . . . . . . . . . .4-13 12.14 Services API software activation certificate
4.9 Database information items for performance arguments . . . . . . . . . . . . . . . . . 12-19
statistics. . . . . . . . . . . . . . . . . . . .4-13 12.15 Services API server configuration query items . .
4.10 Database information items for operation counts 12-23
4-14 12.16 Services API software activation certificate
5.1 API transaction functions. . . . . . . . . . . 5-1 arguments . . . . . . . . . . . . . . . . . 12-26
5.2 Additional API transaction functions. . . . . 5-2 12.17 Services API security configuration query items .
5.3 TPB constants. . . . . . . . . . . . . . . . . 5-4 12-28
5.4 Isolation level interaction with read and write 12.18 Services API user information arguments. 12-29
operations. . . . . . . . . . . . . . . . . . . 5-8 12.19 Services API database connection information
6.1 XSQLDA field descriptions . . . . . . . . . . 6-8 arguments . . . . . . . . . . . . . . . . . 12-31
6.2 XSQLVAR field descriptions . . . . . . . . . 6-9 12.20 Services API task query items. . . . . . . 12-32
6.3 SQL data types, macro expressions, and C data 12.21 Services API limbo transaction arguments 12-33
types . . . . . . . . . . . . . . . . . . . . .6-11 13.1 Install API files required for writing an InterBase
6.4 SQL statement strings and recommended install. . . . . . . . . . . . . . . . . . . . . 13-2
processing methods. . . . . . . . . . . . . .6-16 13.2 Entry points in ibinstall.dll . . . . . . . . . 13-4
6.5 Statement types. . . . . . . . . . . . . . . .6-29 13.3 Datatypes defined for the InterBase Install API. .
7.1 API Blob functions . . . . . . . . . . . . . . 7-1 13-7
7.2 Blob request and return items . . . . . . . .7-14 13.4 Error codes from isc_license_add() . . . . 13-10
7.3 Status message return items . . . . . . . . .7-14 15.1 Array functions . . . . . . . . . . . . . . . 15-2
7.4 isc_blob_ctl structure field descriptions . . .7-19 15.2 Blob functions . . . . . . . . . . . . . . . . 15-2
7.5 Action constants . . . . . . . . . . . . . . .7-21 15.3 Database functions. . . . . . . . . . . . . . 15-3
7.6 Blob parameter buffer parameter types. . . .7-24 15.4 Date and conversion functions. . . . . . . . 15-3
8.1 API array access functions . . . . . . . . . . 8-1 15.5 DSQL functions . . . . . . . . . . . . . . . 15-4
8.2 Array descriptor fields . . . . . . . . . . . . 8-2 15.6 Error-handling functions. . . . . . . . . . . 15-5
8.3 Data types for array descriptors . . . . . . . 8-3 15.7 Event functions . . . . . . . . . . . . . . . 15-5
10.1 Error-handling functions . . . . . . . . . . .10-1 15.8 Information functions . . . . . . . . . . . . 15-6
10.2 Interpretation of the first long in status vector 15.9 Install functions . . . . . . . . . . . . . . . 15-6
clusters . . . . . . . . . . . . . . . . . . . .10-7 15.10 Licensing functions . . . . . . . . . . . . . 15-7
10.3 #defines for status vector numeric descriptors10-8 15.11 Service functions . . . . . . . . . . . . . . 15-7
11.1 API event functions. . . . . . . . . . . . . .11-1 15.12 Transaction control functions . . . . . . . . 15-8
15.13 Function description format . . . . . . . . . 15-9
ix
15.14 Error messages for isc_adduser(). . . . . . 15-10 15.23 isc_dsql_batch_execute_immed Parameters15-58
15.15 Data types for array descriptor fields. . . . 15-16 15.24 Batch Update Error Codes. . . . . . . . . 15-59
15.16 Data types for array descriptor fields. . . . 15-19 15.25 Error codes from isc_license_add() . . . .15-106
15.17 Data types for array descriptor fields. . . . 15-26 15.26 Error codes from isc_license_check() . . .15-107
15.18 Blob descriptor fields. . . . . . . . . . . . 15-30 15.27 Returns codes from isc_license_remove().15-107
15.19 Blob descriptor fields. . . . . . . . . . . . 15-35 15.28 Error messages for isc_modifyuser() . . . 15-110
15.20 Error messages for isc_deleteuser() . . . . 15-50 15.29 Transaction information request item . . .15-134
15.21 isc_dsql_batch_execute Parameters . . . . 15-55 15.30 Status message return items . . . . . . . .15-135
15.22 XSQLVAR_LENTGH Macro Parameters . 15-56
x