ISO/IEC 9075-3:1995

Information technology - Database languages - SQL - Part 3: Call-Level Interface (SQL/CLI)

Technologies de l'information — Langages de base de données — SQL — Partie 3: Interface de niveau d'appel (SQL/CLI)

General Information

• Status: Withdrawn
• Publication Date: 26-Dec-1995
• Withdrawal Date: 26-Dec-1995
• ICS: 35.060 - Languages used in information technology
• Technical Committee: ISO/IEC JTC 1/SC 32 - Data management and interchange
• Drafting Committee: ISO/IEC JTC 1/SC 32 - Data management and interchange
• Current Stage: 9599 - Withdrawal of International Standard
• Start Date: 16-Dec-1999
• Completion Date: 30-Oct-2025

Relations

• Revised: ISO/IEC 9075-3:1999 - Information technology - Database languages - SQL - Part 3: Call-Level Interface (SQL/CLI)
• Effective Date: 15-Apr-2008

Standards Content (Sample)

INTERNATIONAL
ISOJIEC
STANDARD 9075-3
First edition
1995-I 2-l 5
Information technology - Database
languages - SQL -
Part 3:
Call-Level Interface (SQL/CLl)
Technologies de /‘information - Langages de base de don&es - SQL -
Pat-tie 3: Interface de niveau d ‘appel (SQL/CL/)
Reference number
ISO/I EC 9075-3: 1995(E)
Page
Contents
1 Scope .~.,. 1
Norrmativereferences. 3
.....................................
3 Definitions, notations, and conventions
. Definitions .
Notations .
32 .
..........................................................
33 Conventions.
...........................................
313.1 Specification of routine definitions
Subclausenaming .
3.32
Concepts.~ .
41 Introduction.” .
Returncodes .
4:2
........................................................ 10
43 . Diagnostics areas
............................................... 12
44 Miscellaneous characteristics
..12
414.1 Handles .
................................................... 12
4.4.2 Null terminated strings
........................................................... 12
4.4.3 Null pointers
................................................... 13
4.4.4 Environment attributes
..................................................... 13
4.4.5 Connection attributes
..................................................... 13
4.4.6 Statement attributes
..................................................... 14
4.4.7 CL1 descriptor areas
..........................................
5 Call-Level Interface specifications
51 . .
..................................................
52 . invocation
................................................
53 SQL/CL1 common elements
....................................................
513.1 Implicit set connection
.......................................................... 26
5.3.2 Implicit cursor
.....................................................
5.3.3 Implicit using clause
................................................. 34
5.3.4 Character string retrieval
................................................. 35
5.3.5 Deferred parameter check
................................................... 35
5.3.6 Client-server operation.
.................................................. 35
5.3.7 CLI-specific status codes
......................................
5.3.8 Description of CL1 item descriptor areas
............................................
5.3.9 Other tables associated with CL1
................................................ 58
54 . Data type correspondences.
0 ISO/IEC 1995
All rights reserved. Unless otherwise specified, no part of this publication may be repro-
duced or utilized in any form or by any means, electronic or mechanical, including photo-
copying and microfilm, without permission in writing from the publisher.
ISO/IEC Copyright Office l Case postale 56 l CH-1211 Geneve 20 l Switzerland
Printed in Switzerland
ii Call-Level Interface (SQLKLI)

OISO/IEC
6 SQLJCLIroutines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
...........................................................
61 . AIlocConnect
62 . AllocEnv.6 6
..~.....................................6 7
AIlocHandle
63 .
....................
..............................................................
64 . AIlocStmt
..7 1
65 . Bind&l .
.............................................................
66 BindParam
................................................................
6:7 Cancel
............................................................
68 . CloseCursor
ColAttribute .
Connect .
6'10
Copy&x. .
6'11
DataSources.8 7
6'12
DescribeCol .
6‘13
..9 1
6'14 Disconnect .
6'15 EndTran.g 3
.................................................................
6'16 Error
..9 8
6'17 ExecDirect .
..10 1
Execute
6'18 .
..lO 3
Fetch
6’19 .
6:20 FetchScroll.lO 5
FreeConnect.lO 8
6.21
FreeEnv.lO 9
6.22
..llO
FreeHandle
6.23 .
..113
FreeStmt
6.24 .
..114
GetConnectAttr
6.25 .
......................................................... 115
GetCursorName
6.26
6.27 GetData. .*.*.116
...
..l2 l
6.28 GetDescField .
6.29 GetDescRec .".12 3
..
..12 5
6.30 GetDiagField .
..13 1
6.31 GetDiagRec .
..13 3
6.32 GetEnvAttr .
..13 4
6.33 GetFunctions .
6.34 GetInfo.l3 5
6.35 GetStmtAttr.~.l4 3
..14 5
6.36 GetTypeInfo
..........................................................
..14 9
6.37 NumResuItCols .
6.38 ParamData.l5 0
6.39 Prepare ~.15 5
6.40 PutData.l5 7
..15 9
6e41 RowCount .
..16 0
6.42 SetConnectAttr .
......................................................... 161
6.43 SetCursorName
..16 3
6.44 SetDescField .
Table of Contents iii
OISO/IEC
6.45 SetDescRec.16 6
6.46 SetEnvAttr.16 8
..16 9
6.47 SetStmtAttr .
7 Conformance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .173
71 . Introduction.173
72 . Claims of conformance . . . . . . . . . . . . . . . . . * . * . e . . . . . . . . . . . . . . . . . . . . . . e . . . . . . . 173
73 . Extensions and options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
..17 5
Annex A Typicalheaderfiles .
C Header File SQLCL1.H. . 175
A.1
.............................................. 185
A.2 COBOL Library Item SQLCLI
............................................... 193
Annex B Sample C programs
................................................. 193
B.l Create table, insert, select
....................................................... 196
B.2 Interactive Query.
............................ 199
B3 . Providing long dynamic arguments at Execute( ) time
Annex C Implementation-defined elements 0 . . + . . . 6 a . . . . . . e . + . - . . . . - . . . - . e . . o .203
Implementation-dependent elements . . . . y * . D . * . e 0 . o . e * . o . o . . . . . e . . . .211
Annex D
Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .215
iv Call-Level Interface (SQLKLI)

ISO/IEC 90’75-3=1995 (E)
OISO/IEC
TABLES
Page
Table
.............................................
1 Fields in CL1 diagnostics areas
........................
2 Supported calling conventions of CL1 routines by language
.............................................
3 Abbreviated CL1 generic names
................... 35
4 SQLSTATE class and subclass values for CLI-specific conditions
..........................................
5 Fields in CL1 item descriptor areas
...............................
6 Codes used for implementation data types in CL1
...................................
7 Codes used for application data types in CL1
...........................
8 Codes associated with datetime data types in SQL/CL1
...........................
9 Codes associated with in SQL/CL1
........................ 42
10 SQL-statement integer codes for use in a diagnostics area
...................... 44
11 SQL-statement character codes for use in a diagnostics area.
.............................................
12 Codes used for diagnostic fields
...............................................
13 Codes used for handle types.
.......................................
14 Codes used for transaction termination
.......................................
15 Codes used for environment attributes
.........................................
16 Codes used for connection attributes
.........................................
17 Codes used for statement attributes
............................................
18 Codes used for FreeStmt options
...................................................
19 Data types of attributes
.............................................
20 Codes used for descriptor fields
............................................
21 Codes used for fetch orientation.
............................................
22 Miscellaneous codes used in CL1
..........................................
23 Codes used for GetData data types
......................................
24 Codes used to identify SQL/CL1 routines
...........................
25 Codes and data types for implementation information.
.......................................
26 Values for ALTER TABLE with GetInfo
.......................... 52
27 Values for CURSOR COMMIT BEHAVIOR with GetInfo
..................................
28 Values for FETCH DIRECTION with GetInfo
..............................
29 Values for GETDATA EXTENSIONS with GetInfo
...................................
Values for IDENTIFIER CASE with GetInfo
...........................
31 Values for OUTER JOIN CAPABILITIES with GetInfo
.............................
32 Values for SCROLL CONCURRENCY with GetInfo
.............................
33 Values for TRANSACTION CAPABLE with GetInfo
....................
34 Values for TRANSACTION ISOLATION OPTION with GetInfo
...................................
35 Values for NULL COLLATION with GetInfo
...........................................
36 Codes used for concise data types
......................... 56
37 Codes used with concise datetime data types in SQL/CL1
..........................
Codes used with concise interval data types in SQL/CL1
Table of Contents v
OISO/IEC
Concise codes used with datetime data types in SQL/CL1 . 57
40 Concise codes used with interval data types in SQL/CL1 .
Data type correspondences for Ada . 58
42 Data type correspondences for C .
43 Data type correspondences for COBOL . 60
44 Data type correspondences for Fortran .
45 Data type correspondences for MUMPS . 62
46 Data type correspondences for Pascal .
47 Data type correspondences for PL/I .
vi Call-Level Interface (SQIKLI)

OISOLCEC ISO/IEC 907593:1995 (E)
Foreword
IS0 (the International Organization for Standardization) and IEC (the International Electrotechnical
Commission) form the specialized system for worldwide standardization. National bodies that are
members of IS0 or IEC participate in the development of International Standards through technical
committees established by the respective organization to deal with particular fields of technical
activity. IS0 and IEC technical committees collaborate in fields of mutual interest. Other inter-
national organizations, governmental and non-governmental, in liaison with IS0 and IEC, also take
part in the work.
In the field of information technology, IS0 and IEC have established a joint technical committee,
ISO/IEC JTC 1. Draft International Standards adopted by the joint technical committee are circu-
lated to national bodies for voting. Publication as an International Standard requires approval by
at least 75 % of the national bodies casting a vote.
International Standard ISO/IEC 9075-3 was prepared by Joint Technical Committee ISO/IEC JTC 1,
Information technology, Subcommittee SC 21, Open systems interconnection, data management and
open distributed processing.
ISO/IEC 9075 consists of the following parts, under the general title Information technozogy -
Database languages - SQL:
- Part 3: Call-Level Interface (SQLICLI)
- Part 4: Persistent Stored Modules (SQLIPSM)
Parts 1 and 2 are currently published as ISO/IEC 9075:1992.
Annexes A to D of this part of ISO/IEC 9075 are for information only.
Foreword vii
ISO/IEC 90763tl995 (E) 01s0/rEc
Introduction
The organization of this part of ISO/IEC 9075 is as follows:
1) Clause 1, “Scope”, specifies the scope of this part of ISO/IEC 9075
identifies additional standards that, through reference in this
2) Clause 2, “Normative references”,
part of ISO/IEC 9075, constitute provisions of this part of ISO/IEC 9075.
defines the notations and conventions used
3) Clause 3, “Definitions, notations, and conventions”,
in this part of ISO/IEC 9075.
4) Clause 4, “Concepts”, presents concepts used in the definition of the Call-Level Interface.
defines facilities for using SQL through a Call-
5) Clause 5, “Call-Level Interface specifications”,
Level Interface.
6) Clause 6, “SQL/CL1 routines”, defines each of the routines that comprise the Call-Level
Interface.
defines the criteria for conformance to this part of ISO/IEC 9075.
7) Clause 7, “Conformance”,
8) Annex A, “Typical header files”, is an informative Annex. It provides examples of typical header
files for application programs using the SQL Call-Level Interface.
Annex B, “Sample C programs” is an informative Annex. It provides a sample of using the SQL
9)
Call-Level Interface from the C programming language.
is an informative Annex. It lists those features
10) Annex C, “Implementation-defined elements”,
for which the body of this part of the standard states that the syntax or meaning or effect on
the database is partly or wholly implementation-defined, and describes the defining information
that an implementor shall provide in each case.
11) Annex D, “Implementation-dependent elements”, is an informative Annex. It lists those features
for which the body of this part of the standard states that the syntax or meaning or effect on
the database is partly or wholly implementation-dependent.
In the text of this part of ISO/IEC 9075, Clauses begin a new odd-numbered page, and in Clause 5,
“Call-Level Interface specifications”, through Clause 7, “Conformance”, Subclauses begin a new
page. Any resulting blank space is not significant.
viii Introduction
INTERNATIONAL STANDARD OISO/IEC
Information technology - Database languages - SQL -
Part 3:
Call-Level Interface (SQWCLI)
1 Scope
This part of ISO/IEC 9075 defines the structures and procedures that may be used to execute state-
ments of the database language SQL from within an application written in a standard programming
language in such a way that procedures used are independent of the SQL statements to be executed.
Scope 1
ISO/IEC 9075~3r1995 (E) 01s0/IEc
2 Call-Level Interface (SQLKLI)

01s0/IEc
2 Normative references
The following standards contain provisions that, through reference in this text, constitute provisions
of this part of this International Standard. At the time of publication, the editions indicated were
valid. All standards are subject to revision, and parties to agreements based on this International
Standard are encouraged to investigate the possibility of applying the most recent editions of
the standards indicated below. Members of IEC and IS0 maintain registers of currently valid
International Standards.
ISOIIEC 1539:1991, Information technology - Programming languages - FORTRAN.
IS0 1989:1985, Programming languages - COBOL.
IS0 6160:1979, Programming languages - PLII.
IS0 71851990, Information technology - Programming languages - Pascal.
ISOIIEC 8652: 1995, Information technology - Programming languages - Ada.
NOTE - IS0 86521987 has been superseded by a new edition (ISOLIEC 86521995). However, when this part
of ISO/IEC 9075 was under development, the previous edition was valid and this part of ISO/IEC 9075 is therefore
based on that edition, which is listed below.
IS0 8652: 1987, Programming languages - Ada.
ISO/IEC 9075:1992, Information technology - Database languages - SQL.
ISO/IEC 9899:1990, Programming languages - C.
ISO/IEC 10206:1991, Information technology - Programming languages - Extended Pascal.
ISOIIEC 11756: 1992, Information technology-Programming languages-MUMPS.
Normative references
ISO/IEC 907593t1995 (E)
OISO/IEC
4 Call-Level Interface (SQLKLI)

01s0/IEc
3 Definitions, notations, and conventions
3.1 Definitions
For the purposes of this part of ISO/IEC 9075, the definitions given in ISO/IEC 9075:1992 and the
following definitions apply.
a) handle: An opaque data value returned by an SQL/CL1 implementation when a CL1 resource
is allocated and used by an SQL/CL1 application to reference that CL1 resource.
b) inner table: The second operand of a left outer join or the first operand of a right outer join.
3.2 Notations
The syntax notation used in this part of ISO/IEC 9075 is an extended version of BNF (“Backus
Normal Form” or “Backus Naur Form”).
This version of BNF is fully described in Subclause 3.2, “Notation”, of ISO/IEC 9075:1992.
3.3 Conventions
The conventions used in this part of ISO/IEC 9075 are identical to those described in Subclause 3.3,
“Conventions”, of ISO/IEC 9075:1992.
The contents of this part of ISO/IEC 9075 depend wholly on ISO/IEC 9075:1992. For example,
the Syntax found in the Format portions of this part of ISO/IEC 9075 often uses symbols that are
defined in ISOAEC 9075:1992.
3.3.1 Specification of routine definitions
The routines in this part of ISO/IEC 9075 are specified in terms of
Function: A short statement of the purpose of the routine.
- Definition: The name of the routine and the names, modes, and data types of its parameters.
- General Rules: A specification of the run-time effect of the routine. Where more than one
General Rule is used to specify the effect of a routine, the required effect is that which would
be obtained by beginning with the first General Rule and applying the Rules in numerical
sequence until a Rule is applied that specifies or implies a change in sequence or termination
of the application of the Rules. Unless otherwise specified or implied by a specific Rule that
is applied, application of General Rules terminates when the last in the sequence has been
applied.
Definitions, notations, and conventions 5

OISO/IEC
3.3 Conventions
3.3.2 Subclause naming
Clauses and Subclauses in this part of ISOAEC 9075 that have names identical to Clauses or
Subclauses in ISOLIEC 9075:1992 supplement the Clause or Subclause, respectively, in ISO/IEC
9075:1992, typically by replacing Format items or Rules or by providing new Format items or Rules.
Clauses and Subclauses in this part of ISO/IEC 9075 that have names that are not identical to
Clauses or Subclauses in ISO/IEC 9075:1992 provide language specification particular to this part
of ISO/IEC 9075.
6 Call-Level Interface (SQLKLI)

OISO/IEC
4 Concepts
4.1 Introduction
The Call-Level Interface (SQUCLI) is an alternative binding style for executing SQL statements
comprising routines that:
- Allocate and deallocate resources,
- Control connections to SQL-servers,
- Execute SQL statements using mechanisms similar to dynamic SQL,
- Obtain diagnostic information,
Control transaction termination, and
- Obtain information about the implementation.
The AllocHandle routine allocates the resources to manage an SQL-environment, an SQL-
connection, a CL1 descriptor area, or SQL-statement processing. An SQL-connection is allocated
in the context of an allocated SQL-environment. A CL1 descriptor area and an SQL-statement
are allocated in the context of an allocated SQL-connection. The FreeHandle routine deallocates
The AllocConnect, AllocEnv, and AllocStmt routines can be used to allocate
a specified resource.
the resources to manage an SQL-connection, an SQL-environment, and SQL-statement processing,
The FreeConnect, FreeEnv, and FreeStmt
respectively, instead of using the AllocHandle routine.
routines can be used to deallocate the specific resource instead of using FreeHandle.
Each allocated SQL-environment has an attribute that determines whether output character strings
are null terminated by the implementation. The application can set the value of this attribute
by using the routine SetEnvAttr and can retrieve the current value of the attribute by using the
routine GetEnvAttr.
The Connect routine establishes an SQL-connection. The Disconnect routine terminates an es-
tablished SQL-connection. Switching between established SQL-connections occurs automatically
whenever the application switches processing to a dormant SQL-connection.
The ExecDirect routine is used for a one-time execution of an SQL-statement. The Prepare routine
is used to prepare an SQL-statement for subsequent execution using the Execute routine. In each
case, the executed SQL-statement can contain dynamic parameters.
The interface for a description of dynamic parameters, dynamic parameter values, the resultant
columns of a or , and the tar-
get specifications for the resultant columns is a CL1 descriptor area. A CL1 descriptor area for
each type of interface is automatically allocated when an SQL-statement is allocated. The applica-
tion may allocate additional CL1 descriptor areas and nominate them for use as the interface for
the description of dynamic parameter values or the description of target specifications by using the
routine SetStmtAttr. The application can determine the handle value of the CL1 descriptor area cur-
rently being used for a specific interface by using the routine GetStmtAttr. The GetDescField and
Concepts 7
OISO/IEC
4.1 Introduction
GetDescRec routines enable information to be retrieved from a CL1 descriptor area. The CopyDesc
routine enables the contents of a CL1 descriptor area to be copied to another CL1 descriptor area.
When a or is prepared or exe-
cuted immediately, a description of the resultant columns is automatically provided in the applicable
CL1 descriptor area. In this case, the application may additionally retrieve information by using
the DescribeCol and/or the ColAttribute routine to obtain a description of a single resultant column
and by using the NumResultCols routine to obtain a count of the number of resultant columns. The
application sets values in the CLI descriptor area for the description of the corresponding target
specifications either explicitly using the routines SetDescField and SetDescRec or implicitly using
the routine BindCol.
When an SQL-statement is prepared or executed immediately, a description of the dynamic param-
eters is automatically provided in the applicable CLI descriptor area if this facility is supported
by the current SQL-connection. An attribute associated with the allocated SQL-connection indi-
cates whether this facility is supported. The value of the attribute may be retrieved using the
routine GetConnectAttr. The application sets values in the CL1 descriptor area for the description
of dynamic parameter values and, regardless of whether automatic population is supported, in the
CL1 descriptor area for the description of dynamic parameters either explicitly using the routines
SetDescField and SetDescRec or implicitly using the routine BindParam. The value of a dynamic
parameter may be established before SQL-statement execution (immediate parameter value) or may
be provided during SQL-statement execution (deferred parameter value). Its description in the CL1
descriptor area determines which method is in use. The ParamData routine is used to cycle through
and process deferred parameter values. The PutData routine is used to provide the deferred values.
The PutData routine also enables the values of character string parameters to be provided in pieces.
When a or is executed, a
cursor is implicitly declared and opened. The cursor name can be supplied by the application
by using the routine SetCursorName. If a cursor name is not supplied by the application, an
implementation-dependent cursor name is generated. The cursor name can be retrieved by using
the GetCursorName routine.
The Fetch and FetchScroll routines are used to position an open cursor on a row and to retrieve
the values of bound columns for that row. A bound column is one whose target specification in
the specified CL1 descriptor area defines a location for the target value. The Fetch routine always
positions the open cursor on the next row, whereas the FetchScroll routine may be used to position
the open cursor on any of its rows. The value of the CURSOR SCROLLABLE statement attribute
must be SCROLLABLE at the time that the cursor is implicitly declared in order to use FetchScroll
with a FetchOrientation other than NEXT. The application can set the value of this attribute by
using the SetStmtAttr routine and can retrieve the current value of the attribute by using the
GetStmtAttr routine.
Values for unbound columns can be individually retrieved by using the GetData routine. The
GetData routine also enables the values of character string columns to be retrieved piece by piece.
The current row of a cursor can be deleted or updated by executing a statement: positioned> or a , respectively,
for that cursor under a different allocated SQL-statement to the one under which the cursor was
opened. The CloseCursor routine enables a cursor to be closed.
The Error, GetDiagField, and GetDiagRec routines obtain diagnostic information about the most
recent routine operating on a particular resource. The Error routine always retrieves information
from the next status record, whereas the GetDiagField and GetDiagRec routines may be used to
retrieve information from any status record.
Information on the number of rows affected by the last executed SQL-statement can be obtained by
using the RowCount or GetDiagField routine.
8 Call-Level Interface (SQLKLI)

01s0/IEc
4.1 Introduction
An SQL-transaction is terminated by using the EndTran routine.
NOTE l- Neither a nor a may be executed using the ExecDirect
or Execute routines.
The Cancel routine is used to cancel the execution of a concurrently executing SQL/CL1 routine
or to terminate the processing of deferred parameter values and the execution of the associated
SQL-statement.
The GetFunctions, GetInfo, and GetTypeInfo routines are used to obtain information about the
implementation. The DataSources routine returns a list of names that identify SQL-servers to
which the application may be able to connect and returns a description of each such SQL-server.
4.2 Return codes
The execution of a CL1 routine causes one or more conditions to be raised. The status of the
execution is indicated by a code that is returned either as the result of a CLI routine that is a CL1
function or as the value of the ReturnCode argument of a CL1 routine that is a CL1 procedure.
The values and meanings of the return codes are as follows. If more than one return code is
possible, then the one appearing later in the list is the one returned.
A value of zero indicates Success . The CL1 routine executed successfully.
- A value of P indicates Success with information . The CL1 routine executed successfully but a
completion condition was raised: warning.
The CL1 routine executed successfully but a comple-
- A value of 100 indicates No data found .
---
tion condition was raised: no data.
- A value of 99 indicates Data needed . The CL1 routine did not complete its execution because
--
additional data is needed. An exception condition was raised: CLI-specific condition - dynamic
parameter value needed.
The CL1 routine did not execute successfully. An exception con-
- A value of -1 indicates Error .
invalid handle or CLI-specific condition - dynamic
dition other than CLI-specific condition -
parameter value needed was raised.
- A value of -2 indicates Invalid handle . The CL1 routine did not execute successfully because
an exception condition was raised: CLI-specific condition - invalid handle.
If the CL1 routine did not execute successfully, then the values of all output arguments are
implementation-dependent unless explicitly defined by this part of ISO/IEC 9075.
In addition to providing the return code, for all CL1 routines other than GetDiagField and
GetDiagRec, the implementation records information about completion conditions and about excep-
tion conditions other than CLI-specific condition- invalid handle in the diagnostics area associated
with the resource being utilized.
The resource being utilized by a routine is the resource identified by its input handle. In the case
of CopyDesc, which has two input handles, the resource being utilized is deemed to be the one
identified by TargetDescHandle.
Concepts 9
OISO/IEC
4.3 Diagnostics areas
4.3 Diagnostics areas
Each diagnostics area comprises header fields that contain general information relating to the
routine that was executed and zero or more status records containing information about individual
conditions that occurred during the execution of the CL1 routine. A condition that causes a status
record to be generated is referred to as a status condition.
At the beginning of the execution of any CL1 routine other than Error, GetDiagField, and
GetDiagRec, the diagnostics area for the resource being utilized is emptied. If the execution of
such a routine does not result in the exception condition CLI-specific condition-invalid handle or
the exception condition CL&specific ConditionAynamic parameter value needed, then:
Header information is generated in the diagnostics area.
then no status records are generated.
- If the routine’s return code indicates Success ,
- If the routine’s return code indicates Success with information or Error , then one or more
status records are generated.
then no status record is generated corre-
- If the routine’s return code indicates No data found ,
---
sponding to SQLSTATE value '02000' but there may be status records generated corresponding
to SQLSTATE value '02nnn', where 'nnn' is an implementation-defined subclass value.
If multiple status records are generated, then the order in which status records are placed in a
diagnostics area is implementation-dependent except that:
For the purpose of choosing the first status record, status records corresponding to transaction
roLlback have precedence over status records corresponding to other exceptions, which in turn
have precedence over status records corresponding to the completion condition no data, which in
turn have precedence over status records corresponding to the completion condition warning.
Apart from any status records corresponding to an implementation-specified no data, any status
record corresponding to an implementation-specified condition that duplicates, in whole or in
part, a condition defined in this part of ISO/IEC 9075 shall not be the first status record.
The routines GetDiagField and GetDiagRec retrieve information from a diagnostics area. The
application identifies which diagnostics area is to be accessed by providing the handle of the
relevant resource as an input argument. The routines return a result code but do not modify
the identified diagnostics area.
The Error routine also retrieves information from a diagnostics area. The Error routine retrieves
the status records in the identified diagnostics area one at a time but does not permit already
processed status records to be retrieved. Error returns a result code but does not modify the
identified diagnostics area.
The RowCount routine retrieves the ROW COUNT field from the diagnostics area for the spec-
-
ified statement handle. RowCount returns a result code and may
cause exception or completion
cond itions to be raised which cause status records to be generated.
A CL1 diagnostics area comprises the fields specified in Table 1, “Fields in CLI diagnostics areas”.
10 Call-Level Interface (SQLKLI)

OISO/IEC
4.3 Diagnostics areas
Table l-Fields in CM diagnostics areas
Field Data type
Header fields
DYNAMIC FUNCTION CHARACTER VARYING (Ll)
-
DYNAMIC FUNCTION CODE INTEGER .
- -
MORE INTEGER
NUMBER INTEGER
SMALLINT
RETURNCODE
INTEGER
ROW COUNT
-
Fields in status records
CHARACTER VARYING (L)
CATALOG - NAME
CHARACTER VARYING (Ll)
CLASS ORIGIN
-
CHARACTER VARYING (L)
COLUMN NAME
-
CONDITION NUMBER INTEGER
-
CONNECTION NAME CHARACTER VARYING (L)
-
CONSTRAINT CATALOG CHARACTER VARYING (L)
-
CONSTRAINT NAME CHARACTER VARYING (L)
-
CONSTRoAINT SCHEMA CHARACTER VARYING (L)
-
CURSOR NAME CHARACTER VARYING (L)
-
MESSAGE LENGTH INTEGER
-
MESSAGE OCTET LENGTH INTEGER
- -
MESSAGE TEXT CHARACTER VARYING (Ll)
-
NATIVE CODE INTEGER
-
CHARACTER VARYING (L)
SCHEMA NAME
-
CHARACTER VARYING (L)
SERVER NAME
-
SQLSTATE CHARACTER (5)
CHARACTER VARYING (Ll)
SUBCLASS ORIGIN
-
TABLE NAME CHARACTER VARYING (L)
-
Where L is an implementation-defined integer not less than 128 and Ll is an implementation-defined integer not less
than 254.
All diagnostics area fields specified in ISO/IEC 9075:1992 that are not included in this table are not
applicable to SQLKLI.
Concepts 11
4.4 Miscellaneous characteristics
4.4 Miscellaneous characteristics
4.4.1 Handles
The AllocHandle routine returns an identifier, known as a handle, that uniquely identifies the
allocated resource. Although the CL1 parameter data type for a handle parameter is INTEGER, its
value has no meaning in any other context and should not be used as a numeric operand or modified
in any way.
In general, if the related resource cannot be allocated, then a handle value of zero is returned.
However, even if a resource has been successfully allocated, processing of that resource can subse-
quently fail due to memory constraints as follows:
- If additional memory is required but is not available, then an exception condition is raised:
CL&specific condition - memory allocation error.
- If previously allocated memory cannot be accessed, then an exception condition is raised: CLI-
memory management error.
specific condition -
NOTE 2 - No diagnostic information is generated in this case.
The validity of a handle in a compilation unit other than the one in which the identified resource
was allocated is implementation-defined.
NOTE 3 - Specifying (the address of) a valid handle as the output handle of AllocHandle does not have the
effect of reinitializing the identified resource. Instead, a new resource is allocated and a new handle value
overwrites the old one.
4.4.2 Null terminated strings
An input character string provided by the application may be terminated by the implementation-
defined null character that terminates C character strings. If this technique is used, the application
may set the associated length argument to either the length of the string excluding the null termi-
nator or to -3, indicating NULL TERMINATED.
If the NULL TERMINATION attribute for the SQL-environment is true , then all output character
strings returned by the implementation are terminated by the implementation-defined null char-
acter that terminates C character strings. If the NULL TERMINATION attribute is false , then
output character strings are not null terminated.
4.4.3 Null pointers
If the standard programming language of the invoking host program supports pointers, then the
application may provide a zero-valued pointer, referred to as a null pointer, in the following circum-
stances:
- In lieu of an output argument that is to receive length of
the a returned character string. This
indicates that the application wishes to prohibit the return
of this information.
- In lieu of other output arguments where specifically allowed by ISO/IEC 9075. This indicates
that the application wishes to prohibit the return of this information.
- In lieu of input arguments where specifically allowed by ISO/IEC 9075. The semantics of such a
specification depend on the context.
12 Call-Level Interface (SQIJCLI)

ISO/IEC 907593:1995 (E)
01s0/IEc
4.4 Miscellaneous characteristics
If the application provides a null pointer in any other circumstances, then an exception condition is
raised: CLI-specific condition - invalid use of null pointer.
If the NULL TERMINATION attribute for the SQL-environment is fake , then specifying a zero
buffer size for an output argument is equivalent to specifying a null pointer for that output argu-
ment.
4.4.4 Environment attributes
Environment attributes are associated with each allocated SQL-environment and affect the behavior
of CL1 functions in that SQL-environment.
The GetEnvAttr routine enables the application to determine the current value of a specific at-
tribute. For attributes that may be set by the user, the SetEnvAttr routine enables the application
to set the value of a specific attribute. Attribute values may be set by the application whenever
there are no SQL-connections allocated within the SQL-environment.
and Table 19, “Data types of attributes”, in
Table 15, “Codes used for environment attributes”,
Subclause 5.39, “Other tables associated with CLI”, indicate for each attribute its name, code value,
data type, possible values, and whether the attribute may be set using SetEnvAttr.
The NULL TERMINATION attribute determines whether output character strings are null termi-
The attribute is set to true when an SQL-environment is allocated.
nated by the implementation.
4.4.5 Connection attributes
of
Connection attributes are associated with each allocated SQL-connection and affect the behavior
CL1 functions operating in the context of that allocated SQL-connection.
The GetConnectAttr routine enables the application to determine the current value of a specific
attribute. For attributes that may be set by the user, the SetConnectAttr routine enables the
application to set the value of a specific attribute.
and Table 19, “Data types of attributes”, in
Table 16, “Codes used for connection attributes”,
Subclause 53.9, “Other tables associated with CLI”, indicate for each attribute its name, code
value, data type, possible values and whether the attribute may be set using SetConnectAttr.
The POPULATE IPD attribute determines whether the implementation will populate the implemen-
tation parameter descriptor with a descriptor for the s when an
SQL-statement is prepared or executed immediately. The attribute is automatically set each time
an SQL-connection is established for the allocated SQL-connection.
4.4.6 Statement attributes
Statement attributes a re as sociated with each allocated SQL-statement and affect the processing
of
SQL-statements under that allocated SQL-statement.
The GetStmtAttr routine enables the application to determine the current value of a specific at-
tribute. For attributes that may be set by the user, the SetStmtAttr routine enables the application
to set the value of a specific attribute.
Table 17, “Codes used for statement attributes”, and Table 19, “Data types of attributes”, in
Subclause 5.3.9, “Other tables associated with CLI”, indicate for each attribute its name, code
value, data type, possible values, and whether the attribute may be set by using SetStmtAttr.
Concepts 13
OISO/IEC
ISO/IEC 907593:1995 (E)
4.4 Miscellaneous characteristics
The APD HANDLE attribute is the value of the handle of the current application parameter de-
scriptor for the allocated SQL-statement. The attribute is set to the value of the handle of the
automatically allocated application parameter descriptor when the SQL-statement is allocated.
The ARD HANDLE attribute is the value of the handle of the current application row descriptor for
the allocated SQL-statement. The attribute is set to the value of the handle of the automatically
allocated application row descriptor when the SQL-statement is allocated.
The IPD HANDLE attribute is the value of the handle of the implementation parameter descriptor
associated with the allocated SQL-statement. The attribute is set when the SQL-statement is
allocated.
The IRD HANDLE attribute is the value of the handle of the implementation row descriptor associ-
ated with the allocated SQL-statement. The attribute is
...