1 SQL_Services Oracle SQL/Services(TM) is a client/server system that enables client applications on PCs and workstations to access data in Oracle Rdb7(TM) databases on server systems. A simplified view of Oracle SQL/Services is shown in the following illustration. CLIENT NETWORK SERVER COMPONENT COMPONENT COMPONENT +------------+ +---+ +------+ +------+ +------------+ +---------+ | Client | |API| |Trans-|<----|Trans-| | Oracle | |Database | |Application | | | |port |---->|port | |SQL/Services| |Function | +------------+ +---+ +------+ +------+ | Server | +---------+ +------------+ Oracle SQL/Services follows the client/server model in which: o The client requests a set of services from the server through an agreed upon interface. o The server responds by accepting client requests, calling the server function to execute requests, and sending results back to the client. Message requests from the client system and response requests from the server travel over a DECnet, Transmission Control Protocol/Internet Protocol (TCP/IP), SQL*Net(R), AppleTalk, or NetWare (IPX/SPX) communications link. In its implementation of the client/server model, Oracle SQL/Services enables programmers working on any of several computing platforms (Macintosh for MPW, Macintosh for THINK C, MS Windows on MS-DOS, Windows 95, Windows NT X86, Windows NT Alpha, Solaris, Digital UNIX, OpenVMS VAX, or OpenVMS Alpha) to develop client applications that remotely access server databases stored on any operating system supported by the Oracle SQL/Services server using an available network transport. Server databases that client applications can access include either Oracle Rdb7 databases or other databases supported by Oracle Rdb7 SQL. 2 General_Information This topic provides information to help you become familiar with and use Oracle SQL/Services. 3 Writing_Applications As a programmer creating Oracle SQL/Services applications, you must be familiar with the following: o C programming language Have experience in writing programs in the C programming language. Know how to call Oracle SQL/Services client Application Programming Interface (API) routines from C programs to create Oracle SQL/Services applications. o Client system environment Know how to invoke and use a text editor on your client system to create programming source files and be able to run your system's C compiler and linker and run the resulting executable image. o Oracle Rdb7 SQL language (and the dynamic SQL interface) concepts Have a working knowledge of the SQL language. A conceptual familiarity with the dynamic SQL interface can help you understand the client API routines. o Oracle SQL/Services API Understand how to use the API routines in your C applications. 3 Documentation The following documents contain information important to your understanding of Oracle SQL/Services: o Oracle Rdb7 Guide to Using the Oracle SQL/Services Client API contains tutorial and reference information about using Oracle SQL/Services to develop client application programs that access Oracle Rdb7 databases. o Oracle Rdb7 Oracle SQL/Services Release Notes describes new features, problems, problems fixed, restrictions, and other information related to the current release of Oracle SQL/Services. o Oracle Rdb7 Oracle SQL/Services Installation Guide describes how to install Oracle SQL/Services for the OpenVMS and Digital UNIX platforms and the Oracle SQL/Services OpenVMS client API software. o Oracle Rdb7 Oracle SQL/Services Server Configuration Guide describes how to maintain and fine-tune an Oracle SQL/Services system. o Oracle Rdb7 Guide to SQL Programming describes how to combine SQL language statements with host language programs to retrieve, update, and modify data in Oracle Rdb7 databases. This programming guide focuses primarily on data manipulation (DML) statements. This guide contains information about the dynamic SQL interface that can help you understand the function of the API routines. o Oracle Rdb7 SQL Reference Manual provides reference material and a complete description of the statements; the interactive, dynamic, and module language interfaces; and the syntax for SQL. 3 Release_Notes The release notes files for Oracle SQL/Services are only available on line in a text file or as a PostScript (PS) file on OpenVMS server systems in SYS$HELP and on Digital UNIX server systems in /usr/lib/dbs/sqlsrv/v70/doc. These release notes files are also copied to the OpenVMS client system during the OpenVMS client API installation. The file names for the release notes are listed in the Oracle Rdb7 Oracle SQL/Services Installation Guide. Print the file after you have installed the Oracle SQL/Services software to become familiar with new and changed features, restrictions, errors fixed, and documentation omissions in Oracle SQL/Services for the current release. 3 Sample_Application The Oracle SQL/Services documentation, in the Oracle Rdb7 Guide to Using the Oracle SQL/Services Client API, describes a sample interactive application that accepts dynamic SQL statements and processes them using the Oracle SQL/Services client API. The sample application consists of two or three modules, depending on your client platform: o A driver module named sqsdrv.c (on all Windows-based platforms), sqsdrvu.c (on all UNIX-based platforms) or sqlsrv$driver.c (on all OpenVMS and Macintosh platforms). This module accepts dynamic SQL statements from the user and calls the dynamic SQL processing module to process the statements. It is described in the Oracle Rdb7 Guide to Using the Oracle SQL/Services Client API. o A dynamic SQL processing module named sqsdyn.c (on all Windows-based platforms), sqsdynu.c (on all UNIX-based platforms) or sqlsrv$dynamic.c (on all OpenVMS and Macintosh platforms). This module accepts dynamic SQL statements from the driver module and calls Oracle SQL/Services client API routines to process the statements. It is described in the Oracle Rdb7 Guide to Using the Oracle SQL/Services Client API. o An I/O module named winivp.c for Windows-based platforms only. This module calls Windows services to implement a basic Windows I/O interface and is not described in the Oracle Rdb7 Guide to Using the Oracle SQL/Services Client API. The sample application is able to process any dynamic SQL statement, including executable statements such as INSERT, UPDATE, DELETE, singleton-SELECT and CALL statements, as well as SELECT statements. To process a statement entered by the user, the sample application first prepares the statement. If a statement contains parameter markers, the sample application then prompts the user for parameter marker values. To process an executable statement, the sample application executes the statement, then displays any results that the statement might produce. To process a SELECT statement, the sample application declares and opens a cursor, fetches and displays rows from the result table, then closes the cursor when all rows have been fetched. Finally, the sample application releases the statement to free the resources held by the prepared statement. In some respects, the Oracle SQL/Services sample application resembles a limited, portable implementation of the Oracle Rdb7 interactive SQL application. Like interactive SQL, the driver module recognizes the semicolon (;) as an SQL statement terminator and thus accepts multiline statements. However, unlike interactive SQL, it does not parse the SQL statements entered by the user and thus cannot handle compound statements or the definition of stored procedures. Input lines beginning with an exclamation point (!) are considered comments and are not executed. Sample sources for the modules are installed during API software installation. You must build the sample application with these sources for the platforms on which you plan to develop applications. Refer to the Oracle Rdb7 Guide to Using the Oracle SQL/Services Client API for information about the build command used on each client operating system. 3 Dynamic_SQL_Interface The dynamic SQL interface allows application programs to formulate and execute SQL statements at run time. It consists of: o Dynamic SQL statements A set of SQL statements with which you can write applications using either the SQL precompiler or the SQL module processor o Data structures A set of data structures that provides a way for the dynamic SQL interface and application programs to exchange data and metadata Applications that use the dynamic SQL interface might, for example, translate interactive user input into SQL statements, or open, read, and execute files containing SQL statements. The Oracle SQL/Services executor is itself a dynamic SQL application. The Oracle SQL/Services client API routines that programmers use in client applications to access the dynamic SQL interface on the server system, map (closely) to dynamic SQL statements. An understanding of the dynamic SQL interface can help applications programmers understand the way client API routines work. For more detailed information on the dynamic SQL interface, see the Oracle Rdb7 Guide to SQL Programming and the Oracle Rdb7 SQL Reference Manual. 3 System_Management As the person responsible for managing Oracle SQL/Services at your site, you should be familiar with the information in the following chapters of the Oracle Rdb7 Oracle SQL/Services Server Configuration Guide: Chapter 1 describes the components of the Oracle SQL/Services server on an OpenVMS and Digital UNIX system. Chapter 2 describes how to manage these components using the SQLSRV_ MANAGE command line interface. Chapter 3 describes how to maintain a server configuration. Chapter 4 describes the SQLSRV_MANAGE commands. This information is also available through the help facility at the SQLSRV_MANAGE prompt on OpenVMS and Digital UNIX server systems by entering the command Help and through the Oracle SQL/Services Manager GUI on Windows platforms. As the person responsible for managing Oracle SQL/Services at your site, you should be familiar with the information in the following chapters of the Oracle Rdb7 Oracle SQL/Services Installation Guide: Chapter 4 describes multiversioning, managing a V7.0 server, and what you must do to direct clients to alternate V7.0 server network ports. Chapter 8 describes guidelines for the supported transports and where to find platform-specific error information for each transport. Refer to the Oracle Rdb7 Oracle SQL/Services Installation Guide for instructions on installing the OpenVMS VAX and OpenVMS Alpha API software. Refer to the instructions in the readme files on the Oracle Rdb7 Client CD-ROM for installing all other Oracle SQL/Services API software. 2 Client_Components Client application programs access Oracle SQL/Services on a server node using the Oracle SQL/Services client API. The Oracle SQL/Services client API is a library of callable routines that use layered communications software to communicate with the server node. o The Oracle SQL/Services client API routines provide an interface to client applications that is functionally very similar to the dynamic SQL interface. This enables client applications to execute SQL statements against data stored in a database on a server node. The SQL statements can either be defined as string constants in the source code or formulated at run time. The SQL statement syntax accepted by Oracle SQL/Services is identical to that of the dynamic SQL interface of Oracle Rdb7. o The communications software facilitates the transfer of information between the client and server systems. Using a request/response protocol that is virtually transparent to the application, the API accepts client application input, builds Oracle SQL/Services request messages, and transmits them to the server system using DECnet, AppleTalk (through an AppleTal/DECnet Gateway), Transmission Control Protocol/Internet Protocol (TCP/IP) communications protocol, NetWare (IPX/SPX), or SQL*Net. (See Network Components for descriptions of these network components.) Because the Oracle SQL/Services client API provides an interface that is functionally very similar to the dynamic SQL interface, programmers need not understand the communications software to develop Oracle SQL/Services client applications. Oracle SQL/Services currently supports an API for the Macintosh for MPW, Macintosh for THINK C, MS Windows on MS-DOS, Windows 95, Windows NT X86, Windows NT Alpha, Solaris, Digital UNIX, OpenVMS VAX, and OpenVMS operating systems. Communication between client and server systems occurs through DECnet, TCP/IP, SQL*Net, AppleTalk (through an AppleTalk/DECnet Gateway), or IPX/SPX software. See Supported Client Platforms for more information on supported client platforms. 3 Application_Programming_Interface The Application Programming Interface (API) is a library of callable routines that the client uses to access Oracle SQL/Services. The Oracle SQL/Services client API routines provide an interface to client applications that is functionally very similar to the dynamic SQL interface. This enables client applications to execute SQL statements at run time against data stored in a database on a server node. The SQL statements can either be defined as string constants in the source code or formulated at run time. The SQL statement syntax accepted by Oracle SQL/Services is identical to that of the dynamic SQL interface of Oracle Rdb7. The Oracle Rdb7 Guide to Using the Oracle SQL/Services Client API contains complete reference information about the library of callable routines that the client application uses to access Oracle SQL/Services and a sample application to show the routines in use. The routines are grouped into and described within their functional areas (association, SQL statement, result table, utility, and functional interface). 4 Association_Routines Association routines create and terminate client/server associations and control the association environment. These routines are: o sqlsrv_abort Terminates a client/server association. Disconnects from the server and releases all client resources related to the association. o sqlsrv_associate Creates a client/server association. Makes the remote connection to the server process and negotiates association characteristics and attributes. o sqlsrv_get_associate_info Gets association information. o sqlsrv_release Terminates a client/server association in an orderly fashion. Sends a message to the server requesting termination of the association, disconnects the network link, and releases all client resources related to the association. 4 SQL_Statement_Routines SQL statement routines prepare and execute SQL statements, and release prepared SQL statement resources. These routines map directly to the dynamic SQL interface. These routines are: o sqlsrv_prepare Prepares a dynamic SQL statement. It returns a statement identifier and SQLDA metadata information (fields that describe parameter markers and select list items). This routine maps to the dynamic SQL interface PREPARE and DESCRIBE statements. o sqlsrv_execute_in_out Executes a prepared SQL statement. This routine maps to the dynamic SQL interface EXECUTE statement. o sqlsrv_execute_immediate Prepares and executes an SQL statement. This routine cannot be used if the SQL statement contains parameter markers or select list items. This routine maps to the dynamic SQL interface EXECUTE IMMEDIATE statement. o sqlsrv_release_statement Releases client and server statement resources associated with a prepared statement. This routine maps to the dynamic SQL interface RELEASE statement. 4 Result_Table_Routines Result table routines allow the caller to fetch data from the server by providing calls to open a cursor, fetch from an open cursor, and close an open cursor. These routines are: o sqlsrv_declare_cursor Declares the type and mode of an extended dynamic cursor. Note that the cursor is actually declared at the server when sqlsrv_open_cursor is called the first time for a specific cursor name. If you do not call the sqlsrv_declare_cursor routine for a particular cursor name before calling sqlsrv_ open_cursor, Oracle SQL/Services implicitly declares the cursor as type table and mode update. This routine conceptually maps to the dynamic SQL interface DECLARE CURSOR statement. o sqlsrv_open_cursor Opens a cursor by associating a cursor name with a prepared statement identifier. The cursor name is used in each reference to the cursor. The sqlsrv_open_cursor routine also declares the extended dynamic cursor at the server the first time it is called for a specific cursor name. This routine conceptually maps to the dynamic SQL interface OPEN statement. o sqlsrv_fetch Fetches one row of data from an open cursor. This routine maps to the dynamic SQL interface FETCH statement. o sqlsrv_fetch_many Requests that multiple rows of data be fetched and transmitted to the client, which frequently reduces the number of network messages. This routine has no equivalent dynamic SQL interface statement. Rather, it controls the way the server sends row data back to the client after it has been retrieved by the server using the dynamic SQL interface FETCH statement. o sqlsrv_close_cursor Closes an open cursor. This routine maps to the dynamic SQL interface CLOSE statement. 4 Utility_Routines Utility routines provide miscellaneous services to the caller. These routines are: o sqlsrv_allocate_sqlda_data or sqlsrv_allocate_sqlda2_data Allocates memory for the SQLDA or SQLDA2 data buffer and indicator variable fields. o sqlsrv_free_sqlda_data or sqlsrv_free_sqlda2_data Frees memory for the SQLDA or SQLDA2 data buffer and indicator variable fields. o sqlsrv_set_option Sets the option and determines whether SQLDA or SQLDA2 mode is used. 4 Functional_Interface_Routines The functional interface routines provide access to data and metadata stored in the SQLCA, SQLDA, and SQLDA2 structures. These routines replace the need for making direct references to structure fields in client applications. These routines are: o sqlsrv_sqlca_error Returns from the SQLCA structure the error codes for the last statement executed. o sqlsrv_sqlca_error_text Returns from the SQLCA structure the error text for the last statement executed. o sqlsrv_sqlca_count Returns from the SQLCA the number of rows processed by a statement and replaces direct access to the SQLCA.SQLERRD[2] field. o sqlsrv_sqlca_sqlerrd Returns to your application the contents of the entire SQLCA.SQLERRD array which includes, for example, optimizer information for a table cursor, and number of segments, maximum segment length, and so forth for a list cursor, following a successful call to sqlsrv_open_cursor. o sqlsrv_sqlda_sqld or sqlsrv_sqlda2_sqld Returns the number of parameter markers or select list items in the SQLDA or SQLDA2 and replaces direct access to the SQLD field in an SQLDA or SQLDA2. o sqlsrv_sqlda_column_name or sqlsrv_sqlda2_column_name Copies the column name for a particular column from the SQLDA or SQLDA2 into the variable passed in this call. o sqlsrv_sqlda_column_type or sqlsrv_sqlda2_column_type Returns from the SQLDA or SQLDA2 information about the data type of a column. o sqlsrv_sqlda_bind_data or sqlsrv_sqlda2_bind_data Allows programs to allocate their own storage for data and indicator variables in an SQLDA or SQLDA2. o sqlsrv_sqlda_unbind_sqlda or sqlsrv_sqlda2_unbind_sqlda2 Releases all variables bound with the sqlsrv_sqlda_bind_data or sqlsrv_sqlda2_bind_data routine. o sqlsrv_sqlda_ref_data or sqlsrv_sqlda2_ref_data Returns from the SQLDA or SQLDA2 the type and length, and addresses of the data and indicator variables for a column. o sqlsrv_sqlda_unref_data or sqlsrv_sqlda2_unref_data Frees resources tied up by the sqlsrv_sqlda_ref_data or sqlsrv_sqlda2_ref_data routine. o sqlsrv_sqlda_get_data or sqlsrv_sqlda2_get_data Copies data and indicator values from the SQLDA or SQLDA2 to program variables and provides access to SQLDA or SQLDA2 information for languages that do not support explicit type coercion. o sqlsrv_sqlda_set_data or sqlsrv_sqlda2_set_data Copies column information into the SQLDA or SQLDA2. o sqlsrv_sqlda_set_sqllen or sqlsrv_sqlda2_set_sqllen Sets the length of a column of type SQLSRV_ASCII_STRING, SQLSRV_VARCHAR, and SQLSRV_VARBYTE by setting the SQLLEN field in an SQLDA or SQLDA2. The sqlsrv_sqlda2_set_sqllen also sets the SQLOCTET_LEN in an SQLDA2. o sqlsrv_sqlda2_char_set_info Returns the SQL character set information from the SQLDA2. 3 Communications Communications software facilitates the transfer of information between the client and server systems. Using a request/response protocol that is virtually transparent to the application, the API accepts client application input, builds Oracle SQL/Services request messages, and transmits them to the server system using DECnet, AppleTalk (through the AppleTalk/DECnet Gateway), Transmission Control Protocol/Internet Protocol (TCP/IP), SQL*Net, or NetWare (IPX/SPX) communications protocol. Because the Oracle SQL/Services client API provides an interface that is functionally very similar to the dynamic SQL interface, programmers need not understand the communications software to develop Oracle SQL/Services client applications. 2 Network_Components The appropriate client API software can communicate with the Oracle SQL/Services server using DECnet, AppleTalk, TCP/IP, SQL*Net, or IPX/SPX communications software: o DECnet software The DECnet network transport is supported by all Oracle SQL/Services server platforms and by all Oracle SQL/Services client platforms with the exception of Solaris. o AppleTalk software The Macintosh Communications Toolbox AppleTalk-DECnet Gateway tool allows a Macintosh system with an AppleTalk network connection to communicate with an Oracle SQL/Services server using DECnet via an AppleTalk DECnet Gateway node. o TCP/IP software The TCP/IP network transport is supported by all Oracle SQL/Services client and server platforms. o NetWare (IPX/SPX) software The Netware (IPX/SPX) network transport is supported on OpenVMS servers and MS Windows V3.1 clients only. o SQL*Net software The SQL*Net network transport is supported by all Oracle SQL/Services server platforms and by the MS Windows V3.1, OpenVMS, and Digital UNIX client platforms. Oracle SQL/Services uses SQL*Net as a network transport to send Oracle SQL/Services messages between Oracle SQL/Services clients and servers. The following additional features are supported with Oracle SQL/Services using SQL*Net: - Secure Network Services(R) Secure Network Services encrypts and performs security checks on data as it moves across LANs and WANs, preventing any unauthorized user from viewing or tampering with information. Specifically, Secure Network Services provides: * Network authentication * Tamper-proof data * High-speed global data encryption * Cross-protocol data security - Diagnostic tools (tracing and logging) Diagnostic tools include Oracle Trace(TM) and SQL*Net logging. Regardless of the communications software used, Oracle SQL/Services relieves application programmers of any need to understand networking to develop Oracle SQL/Services applications. See the Oracle SQL/Services Release Notes for network, transport, client, and server operating system version information. 2 Server_Components The server system accepts request messages from the client application through network transport software, processes the requests against a server system database, and sends response messages back to the waiting application on the client system. For a detailed discussion of the server and its components for the OpenVMS and Digital UNIX platforms, see the Oracle SQL/Services Server Configuration Guide. 2 Supported_Client_Platforms Oracle SQL/Services supports the following client platforms: o MS Windows V3.1, Windows 95, and Windows NT clients The Oracle SQL/Services client API is shipped as a Dynamic Link Library (DLL) on all Windows platforms. You use Microsoft C to develop client applications that you link against the platform-specific DLL to access the Oracle SQL/Services client API. The name of the DLL file for MS Windows V3.1 clients is sqsapiw.dll; the name of the DLL file for Windows 95, Windows NT X86 and Windows NT Alpha clients is sqsapi32.dll. All three Windows platforms support the use of an .ini file to customize various aspects of Oracle SQL/Services client API operations including communications, client logging, and so forth. The name of the .ini file for MS Windows V3.1 clients is sqsapiw.ini; the name of the .ini file for Windows 95, Windows NT X86 and Windows NT Alpha clients is sqsapi32.ini. The .ini file that is provided by the installation procedure has all the customizations commented out. You can tailor the operation of the Oracle SQL/Services client API to your specific requirements by reading the directions, then uncommenting and providing appropriate values for the options you need to set. The Oracle SQL/Services MS Windows V3.1, Windows 95, Windows NT X86 and Windows NT Alpha client API software supports the following network transports: - DECnet - TCP/IP - Netware (MS Windows V3.1 only) - SQL*Net (MS Windows V3.1 only) Client applications on all Windows platforms select the DECnet, TCP/IP, SQL*Net, or Netware transport using an Oracle SQL/Services client API service or using an .ini file. Specifying a transport in an .ini file overrides a selection made using the Oracle SQL/Services client API service. However, you must use the Oracle SQL/Services client API routine to select the SQL*Net network transport because Oracle SQL/Services requires different arguments for the SQL*Net transport than for other transports. If you are connecting to a server node running multiple versions of Oracle SQL/Services, then you must use an .ini file to select an alternate DECnet, TCP/IP, or Netware network port if the server you are using does not use the default network ports. If you are using the Netware transport, there are other options related to NetWare that you may need to set. See the .ini file on your platform for more information on setting Oracle SQL/Services client API options. o Macintosh clients Oracle SQL/Services client API software is available for the Macintosh Programmers Workbench (MPW) development environment from Apple Computer and the THINK C development environment from Symantec. The Oracle SQL/Services MPW client API software is shipped as an MPW object library file. The Oracle SQL/Services THINK C client API software is shipped as two THINK C library files. The Oracle SQL/Services Macintosh client API software supports the following network transports: - DECnet using the Communications Toolbox DECnet Tool - AppleTalk using the Communications Toolbox AppleTalk-DECnet Gateway Tool - TCP/IP using MACtcp Macintosh client applications select the network transport using an Oracle SQL/Services client API routine or by using the Oracle SQL/Services control panel. Selecting a transport using the Oracle SQL/Services client API overrides the transport selection in the Oracle SQL/Services control panel. If you are connecting to a server node running multiple versions of Oracle SQL/Services, then you must use the control panel to select the transport and to specify an alternate DECnet or TCP/IP network port if the server you are using does not use the default network ports. You may also use the Oracle SQL/Services control panel to select the AppleTalk-DECnet Gateway node when using AppleTalk. o Solaris client The Oracle SQL/Services Solaris client API software is shipped as an object library against which you link your client application programs. The Oracle SQL/Services Solaris client API software supports only the TCP/IP network transport. If you are connecting to a server node running multiple versions of Oracle SQL/Services, then you use the SQLSRV_TCPIP_PORT environment variable to select an alternate network port number if the server you are using does not use the default network ports. o Digital UNIX client The Oracle SQL/Services Digital UNIX client API software is shipped as an object library against which you link your client application programs. The Oracle SQL/Services Digital UNIX client API software supports the DECnet, TCP/IP and SQL*Net network transports. If you are connecting to a server node running multiple versions of Oracle SQL/Services and the server you are using does not use the default network ports, then you use the SQLSRV_DECNET_ OBJECT environment variable to select an alternate DECnet object or the SQLSRV_TCPIP_PORT environment variable to select an alternate TCP/IP network port number. o OpenVMS clients The Oracle SQL/Services OpenVMS VAX and OpenVMS Alpha client API software is shipped as shared images against which you link your client application programs. The Oracle SQL/Services OpenVMS client API software supports the DECnet, TCP/IP, and SQL*Net network transports. If you are connecting to a server node running multiple versions of Oracle SQL/Services and the server you are using does not use the default network ports, then you use the SQLSRV$DECNET_ OBJECT logical name to select an alternate DECnet object or the SQLSRV$TCPIP_PORT logical name to select an alternate TCP /IP network port number. 2 Deprecated_Features A deprecated feature is one that is supported in the current release as in previous releases of Oracle SQL/Services, however, Oracle(R) Corporation will not enhance features that are deprecated and may announce in a future version of Oracle SQL/Services that a deprecated feature is obsolete and can no longer be used. Therefore, applications that use features that are deprecated should be modified accordingly when possible. The following features have been deprecated. o MS-DOS large memory model client API The MS-DOS large memory model client API is deprecated in Oracle SQL/Services V7.0, is frozen at the V6.1 level, and will not be enhanced in future releases. The MS-DOS large memory model client API was supplied with the V6.1 kit, but is no longer supplied with the V7.0 kit. o MS-DOS medium memory model client API The MS-DOS medium memory model client API was deprecated in Oracle SQL/Services V5.1, is frozen at the V4.2 level, and will not be enhanced in future releases. The MS-DOS medium memory model client API was supplied with the V6.1 kit, but is no longer supplied with the V7.0 kit. o ULTRIX for VAX client API The ULTRIX for VAX client API was deprecated in Oracle SQL/Services V5.1, is frozen at the V4.2 level,and will not be enhanced in future releases. The ULTRIX for VAX client API was supplied with the V6.1 kit, but is no longer supplied with the V7.0 kit. o ULTRIX for RISC client API The ULTRIX for RISC client API is deprecated in Oracle SQL/Services V7.0, is frozen at the V6.1 level, and will not be enhanced in future releases. The ULTRIX for RISC client API was supplied with the V6.1 kit, but is no longer supplied with the V7.0 kit. o SunOS client API The SunOS client API is deprecated in Oracle SQL/Services V7.0, is frozen at the V6.1 level, and will not be enhanced in future releases. The SunOS client API was supplied with the V6.1 kit, but is no longer supplied with the V7.0 kit. o OS/2 client API The OS/2 client API was deprecated in Oracle SQL/Services V5.1, is frozen at the V4.2 level,and will not be enhanced in future releases. The OS/2 client API was supplied with the V6.1 kit, but is no longer supplied with the V7.0 kit. o VAX format of all API routines The VAX format for all API routines was deprecated in Oracle SQL/Services V5.0 and is documented only in the appendix of the Oracle Rdb7 Guide to Using the Oracle SQL/Services Client API. o Association routines * info_type parameter value SQLSRV_INFO_DB_CLASS of the sqlsrv_get_associate_info routine The info_type parameter value SQLSRV_INFO_DB_CLASS of the sqlsrv_get_associate_info routine is deprecated in V7.0. This parameter value will continue to work for Oracle SQL/Services V7.0. The SQLSRV_INFO_DB_CLASS parameter value describes a flag that returns true if the server is a database class server; the value is returned as a longword. This is useful to determine whether an attach is required after the association for any product layered on Oracle SQL/Services. Oracle Corporation recommends for V7.0 that you use the new info_type parameter value SQLSRV_INFO_SERVICE_ATTRS. See the Guide to Using the Oracle SQL/Services Client API for more information. * sqlsrv_set_server_class (deprecated in Oracle SQL/Services V6.1) Sets the class of executor that the dispatcher assigns to execute a client API request once an association is established. Oracle Corporation recommends that you use the CLASS_NAME field in the association structure as the method of choosing a server class because this method works for multiassociation applications. * sqlsrv_set_transport_type (deprecated in Oracle SQL/Services V6.1) Sets the transport type. Oracle Corporation recommends that you use the XPTTYP field in the association structure as the method of choosing a transport because this method works for multiassociation applications. o SQL Statement routines * sqlsrv_execute (deprecated in Oracle SQL/Services V7.0) Executes any prepared, executable SQL statement. The routine sqlsrv_execute is deprecated in Oracle SQL/Services V7.0. Oracle Corporation recommends that you code your applications using the sqlsrv_execute_in_out routine. See sqlsrv_execute_in_out for a complete description of the sqlsrv_execute_in_out routine. o Functional interface routines * sqlsrv_sqlda_map_data (deprecated in Oracle SQL/Services V5.0) Returns from the SQLDA the type, length, null value, and address of data for a column. * sqlsrv_sqlda_unmap_data (deprecated in Oracle SQL/Services V5.0) Frees any unwanted resources tied up by the sqlsrv_sqlda_ map_data routine. 2 Obsolete_(Unsupported)_Features An obsolete feature is a feature that is no longer supported that was described as a deprecated feature in a previous release. These features no longer work. The following routines are obsolete: o Association routines - sqlsrv_set_environment (was made obsolete in Oracle SQL/Services V6.1) Sets new values for environment variables on the server. Environment variables control date, time, and numeric output formats, and string-matching modes. - sqlsrv_get_environment (was made obsolete in Oracle SQL/Services V6.1) Gets current values of environment variables. o sqlsrv_set_filter (was made obsolete in Oracle SQL/Services V4.2) Associates a Boolean expression with a cursor to filter out unwanted rows from the result table before they are sent to the client. The following features are also obsolete for Oracle SQL/Services V6.1: o Local Mode Local mode was a performance optimization for applications using the Oracle SQL/Services API on the OpenVMS server nodes. The local mode flag is ignored if it is passed in the association structure. o SQLSRV_ENV_STR structure The SQLSRV_ENV_STR structure no longer exists. 2 API_Routines This section describes the documentation format of the API routines in the Oracle SQL/Services client Application Programming Interface (API). For more information on an API routine, refer to the API routine within its grouping. The API routines are grouped according to function: o Association routines - sqlsrv_abort - sqlsrv_associate - sqlsrv_get_associate_info - sqlsrv_release o SQL statement routines - sqlsrv_prepare - sqlsrv_execute_in_out - sqlsrv_execute_immediate - sqlsrv_release_statement o Result table routines - sqlsrv_declare_cursor - sqlsrv_open_cursor - sqlsrv_fetch - sqlsrv_fetch_many - sqlsrv_close_cursor o Utility routines - sqlsrv_allocate_sqlda_data or sqlsrv_allocate_sqlda2_data - sqlsrv_free_sqlda_data or sqlsrv_free_sqlda2_data - sqlsrv_set_option o Functional interface routines - sqlsrv_sqlca_error - sqlsrv_sqlca_error_text - sqlsrv_sqlca_count - sqlsrv_sqlca_sqlerrd - sqlsrv_sqlda_sqld or sqlsrv_sqlda2_sqld - sqlsrv_sqlda_column_name or sqlsrv_sqlda2_column_name - sqlsrv_sqlda_column_type or sqlsrv_sqlda2_column_type - sqlsrv_sqlda_bind_data or sqlsrv_sqlda2_bind_data - sqlsrv_sqlda_unbind_sqlda or sqlsrv_sqlda2_unbind_sqlda2 - sqlsrv_sqlda_ref_data or sqlsrv_sqlda2_ref_data - sqlsrv_sqlda_unref_data or sqlsrv_sqlda2_unref_data - sqlsrv_sqlda_get_data or sqlsrv_sqlda2_get_data - sqlsrv_sqlda_set_data or sqlsrv_sqlda2_set_data - sqlsrv_sqlda_set_sqllen or sqlsrv_sqlda2_set_sqllen - sqlsrv_sqlda2_char_set_info 3 Documentation_Format Each Oracle SQL/Services API routine is documented using a structured format called the routine template. Sections in the Routine Template lists the sections of the routine template, along with the information that is presented in each section and the format used to present the information. Some sections require no further explanation beyond what is given in Sections in the Routine Template. Those that require additional explanation are discussed in the subsections that follow the table. Table 1 Sections in the Routine Template Section Description Routine Name Appears at the top of the page, followed by the English name of the routine Overview Appears directly below the routine name and explains, usually in one or two sentences, what the routine does C Format Shows the C function prototype from the include file sqlsrv.h Parameters Provides detailed information about each parameter Notes Contains additional pieces of information related to applications programming Errors Lists the Oracle SQL/Services errors that can occur in the routine 4 Routine_Name The Oracle SQL/Services API routine names are shown in the form sqlsrv_xxx, sqlsrv_sqlca_xxx, sqlsrv_sqlda_xxx, or sqlsrv_sqlda2_ xxx, throughout the manual. 4 Return_Values The Oracle SQL/Services routine template does not include a "Returns" section. Except where explicitly noted, the Oracle SQL/Services API routines return a signed longword integer containing one of the values shown in API Return Values. Table 2 API Return Values Return Value Description n = SQL_SUCCESS The routine completed successfully. n < SQL_SUCCESS An error occurred during processing. Refer to the SQLCA.SQLCODE for the specific error. n > SQL_SUCCESS A warning was issued during processing. Refer to the SQLCA for additional information. NOTE The symbol SQL_SUCCESS is defined as 0 in the include file sqlsrv.h. 4 C_Format_Section The C Format section shows the function prototypes for the Oracle SQL/Services API routines exactly as they are declared in the include file sqlsrv.h. 3 Oracle_SQL/Services_Data_Types API Parameter Data Types lists the data types used in Oracle SQL/Services API routine calls and structures. Table 3 API Parameter Data Types Data Type Description ASSOCIATE_ID An identifier that uniquely distinguishes one association from all others ASSOCIATE_STR Structure that specifies association characteristics character string Pointer to a null-terminated character string of type char CHARPTR Pointer to a buffer or variable of type unsigned char PTRCHARPTR Pointer to a variable of type CHARPTR SHORTPTR Pointer to a variable of type short LONGPTR Pointer to a variable of type SQS_LONGWORD PTRSHORTPTR Pointer to a variable of type short * or SHORTPTR PTRLONGPTR Pointer to a variable of type LONGPTR word (signed) 16-bit signed integer word (unsigned) 16-bit unsigned integer longword (signed) 32-bit signed integer longword (signed) Array of signed 32-bit integers array longword (unsigned) 32-bit unsigned integer pointer An address whose size is platform specific SQLDA_ID An identifier (pointer or handle) used to access SQLDA data and metadata information void Arguments described with the void data type are reserved for future use SQLCA_ID An identifier (pointer or handle) used to access the data and structure SQLCA To facilitate the development of portable Oracle SQL/Services client software modules, the following two 32-bit integer data types are type defined in the sqlsrv.h file and may be used to define variables in your programs: SQS_LONGWORD 32-bit signed longword SQS_UNSIGNED_LONGWORD 32-bit unsigned longword 3 API_Association_Routines Association Routines Association routines create and terminate client/server associations and control the association environment. Association routines include the following routines: o sqlsrv_abort routine (see sqlsrv_abort) o sqlsrv_associate routine (see sqlsrv_associate) o sqlsrv_get_associate_info routine (see sqlsrv_get_associate_ info) o sqlsrv_release routine (see sqlsrv_release) 4 sqlsrv_abort 5 Overview The sqlsrv_abort routine drops the network link between the client and server, frees client association resources, and rolls back active transactions on the server. 5 C_Format extern int sqlsrv_abort( ASSOCIATE_ID associate_id); 5 Parameters 6 associate_id An identifier used to distinguish one active association from all others. 5 Errors SQLSRV_INTERR Internal error. SQLSRV_INVASC Invalid association identifier. 4 sqlsrv_associate 5 Overview The sqlsrv_associate routine creates a network link between your application and the server, using the node name, user name, and password input parameters. It creates an association identifier used in subsequent routine calls and optionally binds specific input parameters, such as the message protocol buffers and SQLCA structure, to the association. 5 C_Format extern int sqlsrv_associate( char *node_name, char *user_name, char *password, CHARPTR read_buffer, CHARPTR write_buffer, SQS_LONGWORD read_buffer_size, SQS_LONGWORD write_buffer_size, SQLCA_ID *sqlca_str, struct ASSOCIATE_STR *associate_str, ASSOCIATE_ID *associate_id); 5 Parameters 6 node_name Address of a null-terminated string containing the name of the server node. If you are using the SQL*Net transport, this parameter specifies either the SQL*Net Service Name or the SQL*Net Alias. 6 user_name_(optional) Address of a null-terminated string containing the user name that the server uses to authenticate the user and determine if the user is authorized to access the specified service. If this parameter is NULL, the DECnet transport is selected, and the client is connecting to a server on an OpenVMS node, then the server looks for an Oracle SQL/Services proxy for the client node name. If there is no proxy for the client node, or a transport other than DECnet is selected, the server checks to see if unknown users are authorized to access the specified service. If unknown users are not authorized to access the service, the association fails. See the Oracle SQL/Services Server Configuration Guide for more information on client authentication and authorization, and how Oracle SQL/Services uses the client user name. 6 password_(optional) Address of a null-terminated string containing the corresponding password to the specified user name. You must include a password when you specify a user name. 6 read_buffer_(optional) Address of a buffer of type unsigned char used by the API to receive messages from the server. If you specify a buffer address of NULL, Oracle SQL/Services allocates the buffer. Oracle Corporation recommends that you pass a NULL value. 6 write_buffer_(optional) Address of a buffer of type unsigned char used by the API to build messages to send to the server or. If you specify a buffer address of NULL, Oracle SQL/Services allocates the buffer. Oracle Corporation recommends that you pass a NULL value. 6 read_buffer_size_(optional) The size in bytes of the read_buffer. If a read_buffer is passed, the read_buffer_size must contain its size. The minimum value is 256 bytes. If no read_buffer is passed, Oracle SQL/Services allocates a buffer of size read_buffer_size if the parameter is non-zero, or of a default size if the parameter is zero. See Valid Combinations of Buffer-Related Parameters for the sqlsrv_associate Routine for valid combinations of buffer-related parameters. The values for read_buffer_size and write_buffer_size must be equal. This is true for both user-allocated buffers, or when the application requests that Oracle SQL/Services allocate buffers of a specified size. Table 4 Valid Combinations of Buffer-Related Parameters for the sqlsrv_associate Routine Buffer Oracle Transport Buffer Size SQL/Services /Platform SpecifiSpecifiedsult Comments Other NULL 0 API al- 1300 is default transports locates All platforms 1300 Other NULL 256+ API al- Client drops back to the transports locates server supported value. All platforms what V7.0 server - client user drops back to server spec- specified value; V6.1 ified or V6.0 server-client up to drops back to 5000; V5.1 32000 server-client drops back to 1300. Other Valid 256+ API Client drops back to transports user uses the server supported All platforms allo- what value. V7.0 server-client cated user drops back to server buffer spec- specified value; V6.1 ified or V6.0 server-client up to drops back to 5000; V5.1 32000 server-client drops back to 1300. IPX/SPX NULL 0 API al- 534 is the default transport locates Windows 534 enhanced mode IPX/SPX NULL 256+ API al- No error if transport locates specified value > 534 Windows up to enhanced 534 mode IPX/SPX Valid 256+ API No error if transport user- uses up specified value > 534 Windows allocated to 534 enhanced buffer of user mode buffer IPX/SPX NULL 0 API al- 470 is the default transport locates Windows 470 standard mode IPX/SPX NULL 256+ API al- No error if transport locates specified value > 470 Windows up to standard 470 mode IPX/SPX Valid 256+ API No error if transport user- uses up specified value > 470 Windows allocated to 470 standard buffer of user mode buffer 6 write_buffer_size_(optional) The size in bytes of the API buffer used to send messages. If a write_buffer is passed, the write_buffer_size must contain its size. The minimum value is 256 bytes. If no write buffer is passed, Oracle SQL/Services allocates a buffer of size write- buffer-size if the parameter is non-zero, or of a default size if the parameter is zero. See Valid Combinations of Buffer- Related Parameters for the sqlsrv_associate Routine for valid combinations of buffer-related parameters. The values for write_ buffer_size and read_buffer_size must be equal. 6 sqlca_str_(optional) Address of an SQLCA (SQL Communications Area) structure (see the SQLCA-SQL Communications Area section in Chapter 8 of the DEC Rdb Guide to SQL/Services Client APIs). If you specify a buffer address of NULL, Oracle SQL/Services allocates the SQLCA structure. Oracle Corporation recommends that you pass a NULL value. You must pass a NULL value when writing client applications on a Macintosh system. The SQLCA structure is defined in the include file sqlsrvca.h. All valid error codes are defined in sqlsrv.h. 6 associate_str Address of an ASSOCIATE_STR structure used to define optional association characteristics (see the Guide to Using the Oracle SQL/Services Client API). The ASSOCIATE_STR structure is defined in the include file sqlsrv.h. 6 associate_id A pointer to a variable of type ASSOCIATE_ID into which the API writes the association identifier. This identifier distinguishes one active association from all others. 5 Notes o Errors that are detected early in the processing of the sqlsrv_associate routine are returned only in the longword return value from sqlsrv_associate. These errors include SQLSRV_INVARG, SQLSRV_INVSQLCA, SQLSRV_NO_MEM, and SQLSRV_ INVBUFSIZ. o If the read or write buffer size is less than 256 bytes, Oracle SQL/Services returns an SQLSRV_INVARG error on sqlsrv_ associate. o If the read_buffer or write_buffer parameter values are user- allocated buffers, but the read_buffer_size or write_buffer_ size parameter values are specified as 0, Oracle SQL/Services returns an SQLSRV_INVARG error on sqlsrv_associate. o If the read_buffer and write_buffer size are not of equal size, Oracle SQL/Services returns an SQLSRV_INVBUFSIZ error on sqlsrv_associate. o When errors are detected before an associate_id is allocated for the associate session, the sqlsrv_associate routine writes NULL to the associate_id variable to indicate that no associate_id is assigned to this association. In this case, applications should not make subsequent Oracle SQL/Services API calls that require an associate_id. o When errors are detected after an associate_id is allocated for the association, the sqlsrv_associate routine writes a non-NULL value to the associate_id variable. In this case, applications can make calls to a limited subset of Oracle SQL/Services API routines, such as the sqlsrv_sqlca_ error and sqlsrv_sqlca_error_text routines, to retrieve additional information about the error. In this situation, the application should call the sqlsrv_release API routine to release the resources held by the association after retrieving the additional error information. o If a client application connects to a V7.0 server using read and write buffer sizes that are larger than the server can handle, the sqlsrv_associate routine adjusts the buffer sizes locally and immediately returns a success status to the client application. If a client application connects to a V6.1 or V6.0 server using read and write buffer sizes that are larger than the server can handle, the sqlsrv_associate routine releases the network connection, then reconnects with both read and write buffer sizes set to 5000. When the network connection is reestablished, the sqlsrv_associate routine returns a success status to the client application. In both situations, the mechanism used by the sqlsrv_associate routine to select an appropriate buffer size is transparent to the client application. Client applications can call the sqlsrv_get_associate_info routine to determine the actual buffer size being used for the association. o The Oracle SQL/Services NetWare client uses server names in place of node names. A server name is passed to Oracle SQL/Services using the sqlsrv_associate routine in place of the node_name parameter. The maximum length of the server name is 48 bytes, as specified by Novell. Oracle SQL/Services requires this server name to be the name of the InterConnections File Server, which must be installed and running on the same node as the Oracle SQL/Services server. Oracle SQL/Services NetWare clients use the InterConnections File Server as a name server. o When an association is no longer required, your application calls the sqlsrv_release routine to commit any outstanding transactions, release any prepared statements, disconnect the network link, and release any memory allocated to the association at the client and server. 5 Errors SQLSRV_CONNTIMEOUT The connection to the server could not be completed within the specified time limit. SQLSRV_DLL_ADDR_ERR Windows application GetProcAddress call error. SQLSRV_DLL_LOAD_ERR Windows application LoadLibrary call error. SQLSRV_EXEINTERR The executor has encountered an internal or other error condition. SQLSRV_GETACCINF Client authentication or authorization failed. SQLSRV_HOSTERR An attempt to access TCP/IP host files failed. SQLSRV_INTERR Internal error. SQLSRV_INV_CLS Invalid or unknown service name specified. SQLSRV_INVARG Invalid routine parameter. SQLSRV_INVASCSTR Invalid parameter in ASSOCIATE_STR. SQLSRV_INVBUFSIZ Invalid read or write buffer size. SQLSRV_INVSQLCA Invalid SQLCA structure. SQLSRV_NETERR Network transport returned an error. SQLSRV_NO_CONNREC Attempt to get a connection record from the Macintosh Communications ToolBox failed; check the node name. SQLSRV_NO_MEM API memory allocation failed. SQLSRV_NO_PRCAVL No executor processes are available" to service the connection. SQLSRV_NO_RSRC Unable to open the Macintosh Control Panel Device resource. SQLSRV_NO_SYSFLDR Unable to open the Macintosh Control Panel Device in the System Folder. SQLSRV_OPNLOGFIL Unable to open log file. SQLSRV_PWD_EXPIRED The password has expired. SQLSRV_SQLNET_ SQL*Net is unable to connect to the BADCONNECT server. SQLSRV_SQLNET_ Unable to initialize SQL*Net. BADINIT SQLSRV_SQLNET_ SQL*Net is unable to resolve the service BADSERVICE name being specified. SQLSRV_SVCNOTRUN The specified service is not running. SQLSRV_SVC_SHUTDOWN The specified service has been shut down. SQLSRV_ The maximum number of network connections TOOMANYCONNECTS has been reached at the server. SQLSRV_XPT_MISSING Valid transport selection made but code disabled. 4 sqlsrv_get_associate_info 5 Overview The sqlsrv_get_associate_info routine returns attributes of the association structure. The information is copied to a user buffer when sqlsrv_get_associate_info is called. 5 C_Format extern int sqlsrv_get_associate_info( ASSOCIATE_ID associate_id, unsigned short int info_type, unsigned short int buf_len, char *info_buf, SQS_LONGWORD *info_num); 5 Parameters 6 associate_id An identifier used to distinguish one active association from all others. 6 info_type Specifies the type of information to be returned. The values of the info_type parameter are shown in Values of the info_type Parameter. Table 5 Values of the info_type Parameter Value Description SQLSRV_INFO_SQL_VERSION Gets the version of SQL used by the server and returns it as character data. SQLSRV_INFO_ENGINE Gets the version of the Oracle Rdb database engine (if Oracle Rdb is used) used by the server and returns it as character data. SQLSRV_INFO_SRV_VERSION Gets the version of the Oracle SQL/Services server and returns it as character data. SQLSRV_INFO_PROTOCOL Gets the protocol level of the server and returns it as a longword. SQLSRV_INFO_SERVER_PID Gets the process ID (PID) of the executor and returns it as a longword. SQLSRV_INFO_TRANSPORT Gets the transport type in use and returns the information as character data. SQLSRV_INFO_BUFFER_SIZE Gets the negotiated client buffer size and returns the information as a longword. SQLSRV_INFO_SERVICE_ATTRS Gets the service attributes and returns the value as a bit mask in a 32-bit longword. The bit mask is defined in Values of the SQLSRV_ INFO_SERVICE_ATTRS Bit Masks. The values of the SQLSRV_INFO_SERVICE_ATTRS bit masks are shown in Values of the SQLSRV_INFO_SERVICE_ATTRS Bit Masks. Table 6 Values of the SQLSRV_INFO_SERVICE_ATTRS Bit Masks Numeric Value Value Description SQLSRV_INFO_SVC_DBSERVICE 1 Set if the service is a database service. SQLSRV_INFO_SVC_REUSETXN 2 Set if the service is transaction reusable. SQLSRV_INFO_SVC_TIEDEXEC 4 Set if the service is transaction reusable and the association is tied to a single executor for the life of the connection. For V7.0, this bit will always be set if the SQLSRV_INFO_ SVC_REUSETXN bit is set. 6 buf_len The size of a user-supplied buffer for information returned as character data. 6 info_buf Address of a user-supplied buffer of type char for information returned as character data. This is required for information returned as character data. 6 info_num The address of a variable of type SQS_LONGWORD to be used for information returned as a longword, or for the number of characters returned for information returned as character data. This is required for information returned as a longword, and optional for information returned as character data. 5 Notes o The sqlsrv_get_associate_info service returns one attribute per call. To get multiple attributes, your application must call sqlsrv_get_associate_info once for each attribute. o For information returned as character data, if the actual length of the string is longer than the user-supplied buffer, the returned information is truncated to the size of the buffer. 5 Errors SQLSRV_INVARG Invalid routine parameter. SQLSRV_INVASC Invalid association identifier. SQLSRV_SRVNOTSUP The server is not supported. 4 sqlsrv_release 5 Overview The sqlsrv_release routine commits active transactions on the server and requests an orderly termination of the association, which disconnects the network link and frees client association resources. 5 C_Format extern int sqlsrv_release( ASSOCIATE_ID associate_id, char *stats); 5 Parameters An identifier used to distinguish one active association from all others. 6 stats_(optional) This parameter must be 0 or NULL. 5 Notes o When an association is no longer required, your application calls the sqlsrv_release routine to commit any outstanding transactions, release any prepared statements, disconnect the network link, and release any memory allocated to the association at the client and server. 5 Errors SQLSRV_ The connection to the server could not be CONNTIMEOUT completed within the specified time limit. SQLSRV_EXEINTERR The executor has encountered an internal or other error condition. SQLSRV_INTERR Internal error. SQLSRV_INVASC Invalid association identifier. SQLSRV_MULTI_ACT A batched sqlsrv_execute_in_out or sqlsrv_ fetch_many context is active. SQLSRV_NETERR Network transport returned an error. SQLSRV_SVC_ The specified service has been shut down. SHUTDOWN 3 API_SQL_Statement_Routines SQL Statement Routines SQL statement routines prepare and execute SQL statements, and release prepared SQL statement resources. These routines map to the dynamic SQL interface. SQL statement routines include the following routines: o sqlsrv_prepare routine (see sqlsrv_prepare) o sqlsrv_execute_in_out routine (see sqlsrv_execute_in_out) o sqlsrv_execute_immediate routine (see sqlsrv_execute_ immediate) o sqlsrv_release_statement routine (see sqlsrv_release_ statement) 4 sqlsrv_prepare 5 Overview The sqlsrv_prepare routine prepares the input SQL statement and returns a value that identifies the prepared statement. It also optionally allocates and initializes SQLDA or SQLDA2 parameter markers and select list items associated with the SQL statement. 5 C_Format extern int sqlsrv_prepare( ASSOCIATE_ID associate_id, SQS_LONGWORD database_id, char *sql_statement, SQS_LONGWORD *statement_id, SQLDA_ID *parameter_marker_sqlda, SQLDA_ID *select_list_sqlda); 5 Parameters 6 associate_id An identifier used to distinguish one active association from all others. 6 database_id This parameter must be 0. Databases are referenced within the SQL statement syntax. 6 sql_statement Address of a null-terminated string containing the SQL statement to be prepared. 6 statement_id Address of a variable of type SQS_LONGWORD into which the API writes the identifier used in all subsequent references to the prepared statement. 6 parameter_marker_sqlda A pointer to a variable of type SQLDA_ID. Oracle Corporation recommends that you let the Oracle SQL/Services client API allocate memory for each parameter marker SQLDA or SQLDA2, in which case your application should store NULL in the parameter marker SQLDA_ID before calling sqlsrv_prepare. If your application provides its own memory for each parameter marker SQLDA or SQLDA2, your application must store the address of that memory in the parameter marker SQLDA_ID before calling sqlsrv_prepare. If the SQL statement is prepared successfully, Oracle SQL/Services allocates memory for the SQLDA or SQLDA2, stores the address in the SQLDA_ID, if necessary, and writes metadata information about all the parameter markers contained in the SQL statement to the parameter marker SQLDA or SQLDA2. 6 select_list_sqlda A pointer to a variable of type SQLDA_ID. Oracle Corporation recommends that you let the Oracle SQL/Services client API allocate memory for each select list SQLDA or SQLDA2, in which case your application should store NULL in the select list SQLDA_ID before calling sqlsrv_prepare. If your application provides its own memory for each select list SQLDA or SQLDA2, your application must store the address of that memory in the select list SQLDA_ID before calling sqlsrv_prepare. If the SQL statement is prepared successfully, Oracle SQL/Services allocates memory for the SQLDA or SQLDA2, stores the address in the SQLDA_ID, if necessary, and writes metadata information about all the select list items contained in the SQL statement to the select list SQLDA or SQLDA2. 5 Notes o Oracle Corporation recommends that you let the Oracle SQL/Services client API allocate memory for each parameter marker and select list SQLDA or SQLDA2. To check for the presence of parameter markers or select list items in this situation, your application tests the respective SQLDA_ID for a non-NULL value. If the SQLDA_ID does contain a non-NULL value, the number of parameter markers or select list items may be obtained from the SQLD field of the SQLDA or SQLDA2 using the sqlsrv_sqlda_sqld or sqlsrv_sqlda2_sqld routines. o If your application provides it own memory for each parameter marker and select list SQLDA or SQLDA2, it must initialize the SQLDAID field to "SQLDA" or "SQLDA2"; the SQLDABC field to the total size, in bytes, of the SQLDA; the SQLD field to zero; and the SQLN field to the total number of SQLVARs or SQLVAR2s in the SQLDA or SQLDA2. Upon successful completion of a call to sqlsrv_prepare, the presence and number of parameter markers or select list items is indicated by a non-zero value in the SQLD field of the SQLDA or SQLDA2. NOTE On the Macintosh operating system, your application cannot provide its own memory for SQLDAs or SQLDA2s, but must let the Oracle SQL/Services client API allocate the memory for SQLDAs and SQLDA2s. o To enable your application to distinguish between different types of SQL statements, Oracle Rdb stores the statement type in the SQLERRD[1] field of the SQLCA. The statement types, as defined by Oracle Rdb, are as follows: 0: statement is an executable statement other than a CALL statement 1: statement is a SELECT statement 2: statement is a CALL statement You can retrieve this value using the sqlsrv_sqlca_sqlerrd routine. o If the prepared statement is a CALL statement, the metadata for any input or input/output arguments is written to the parameter marker SQLDA or SQLDA2, while the metadata for any output or input/output arguments is written to the select list SQLDA or SQLDA2. Note that metadata for each input/output argument is written to both the parameter marker and select list SQLDAs or SQLDA2s. However, in all other respects, your application processes a CALL statement in the same manner as any other executable SQL statement. 5 Errors SQLSRV_ The connection to the server could not be CONNTIMEOUT completed within the specified time limit. SQLSRV_EXEINTERR The executor has encountered an internal or other error condition. SQLSRV_INTERR Internal error. SQLSRV_INVARG Invalid routine parameter. SQLSRV_INVASC Invalid association identifier. SQLSRV_INVSQLDA Invalid SQLDA, SQLDA2, or SQLDA_ID. SQLSRV_NETERR Network transport returned an error. SQLSRV_NO_MEM API memory allocation failed. SQLSRV_SVC_ The specified service has been shut down. SHUTDOWN 4 sqlsrv_execute_in_out 5 Overview The sqlsrv_execute_in_out routine executes any prepared, executable SQL statement. The prepared statement may accept input from a parameter marker SQLDA or SQLDA2, or return output in a select list SQLDA or SQLDA2, or both. The sqlsrv_execute_in_out routine supersedes the sqlsrv_execute routine. 5 C_Format extern int sqlsrv_execute_in_out( ASSOCIATE_ID associate_id, SQS_LONGWORD database_id, SQS_LONGWORD statement_id, short int execute_flag, SQLDA_ID parameter_marker_sqlda, SQLDA_ID select_list_sqlda); 5 Parameters 6 associate_id An identifier used to distinguish one active association from all others. 6 database_id This parameter must be 0. Databases are referenced within the SQL statement syntax. 6 statement_id The statement ID returned previously by sqlsrv_prepare when the statement was prepared. If you start batched execution for a particular statement ID using the SQLSRV_EXE_BATCH flag, you must end batched execution for that statement ID using one of the SQLSRV_EXE_W_DATA, SQLSRV_EXE_WO_DATA, or SQLSRV_EXE_ABORT flags before you can execute any other prepared statement. 6 execute_flag For a prepared statement that contains parameter markers, this parameter specifies whether the API sends single or multiple sets of parameter marker values to the server for processing (see the Batched Execution section in Chapter 4 of the DEC Rdb Guide to SQL/Services Client APIs for more information on batched execution). For all other prepared SQL statements, this value must be 0 (SQLSRV_EXE_W_DATA). The values of the execute_flag parameter are shown in Values of the execute_flag Parameter in sqlsrv_execute_in_out. Table 7 Values of the execute_flag Parameter in sqlsrv_execute_ in_out Flag Name Value Description SQLSRV_EXE_W_DATA 0 Builds an execute request message in the message buffer using the current values in the parameter marker SQLDA or SQLDA2, then sends the message to the server for execution. If batched execution is currently in effect for the statement, this parameter appends the new message to the previous messages in the message buffer, and sends all the messages to the server for execution along with any requests already queued at the server. SQLSRV_EXE_BATCH 1 Starts or continues batched execution by building an execute request message in the message buffer using the current values in the parameter marker SQLDA or SQLDA2. If batched execution is already in effect for the statement, this parameter appends the new message to the previous messages in the message buffer. Using batched execution, no messages are sent to the server until the message buffer fills up, whereupon the messages in the message buffer are sent to the server to be queued up for subsequent execution behind any previously queued requests. SQLSRV_EXE_WO_DATA 2 Ends batched execution by sending the current contents of the message buffer to the server for execution along with any previously queued requests. Note that the current values in the parameter marker SQLDA or SQLDA2 are not sent to the server when batched execution is ended using the SQLSRV_EXE_WO_ DATA flag. SQLSRV_EXE_ABORT 3 Aborts batched execution by discarding the current contents of the message buffer and sending a message to the server directing it to discard any previously queued requests. 6 parameter_marker_sqlda An SQLDA_ID that identifies the parameter marker SQLDA or SQLDA2 containing any parameter marker values or input and input/output argument values for the SQL statement to be executed. 6 select_list_sqlda An SQLDA_ID that identifies the select list SQLDA or SQLDA2 to receive any select list items or output and input/output argument values returned by the SQL statement to be executed. 5 Notes o On successful completion of a call to sqlsrv_execute_in_out, Oracle SQL/Services stores the total number of database rows inserted, updated, or deleted in the SQLERRD[2] field of the SQLCA. Because multiple rows may be updated or deleted when you execute an UPDATE or DELETE statement, this value may be higher than the number of times that you called sqlsrv_ execute_in_out for a particular batched execution. You can retrieve the row count from the SQLCA using the sqlsrv_sqlca_ count routine. Note that Oracle Rdb does not return a row count value if you use the CALL statement to invoke a stored procedure, or if you execute a compound statement. o If an error occurs executing a request queued for batched execution, then the server discards any remaining requests in the batch execution queue and returns the error to the client. Currently, there is no way to determine precisely which request caused the failure. Therefore, client applications will typically roll back the transaction in this situation. o If you use batched execution to execute an SQL statement containing both parameter markers and select list items, such as UPDATE . . . RETURNING, then only the results from the execution of the last queued request are returned to the client. The results from the execution of all previously queued requests are lost. o Once you start batched execution for a particular statement ID, you cannot call any API routines other than sqlsrv_ execute_in_out, nor can you execute any other prepared statements until you end batched execution for the current statement ID using one of the SQLSRV_EXE_W_DATA, SQLSRV_EXE_ WO_DATA, or SQLSRV_EXE_ABORT flags. o SQL describes the metadata for any items specified in the RETURNING clause of an INSERT statement into the end of the parameter marker SQLDA or SQLDA2. Note that columns, output arguments, and other values returned by a statement are normally described in the select list SQLDA or SQLDA2. The server does not normally return data values from a parameter marker SQLDA or SQLDA2 to the client; therefore, the server must explicitly check each parameter marker SQLDA or SQLDA2 to determine if an INSERT statement contains a RETURNING clause. To do so, it checks the name of the last column described in the parameter marker SQLDA or SQLDA2 for the value DBKEY. Therefore, the only value that can be returned from an INSERT statement is the DBKEY, because the server is unable to detect any other returned value. For example: INSERT INTO EMPLOYEES VALUES ( ?,?,?,?,?,?,?,? ) RETURNING DBKEY INTO ?; SQL describes the metadata for any items specified in the RETURNING clause of an UPDATE statement into the select list SQLDA or SQLDA2 as expected. 5 Errors SQLSRV_ The connection to the server could not be CONNTIMEOUT completed within the specified time limit. SQLSRV_DATA_TOO_ The Oracle SQL/Services executor determined LONG that the length of a data value in an SQLDA exceeded the maximum allowed for the value's data type. SQLSRV_EXEINTERR The executor has encountered an internal or other error condition. SQLSRV_INTERR Internal error. SQLSRV_INVARG Invalid routine parameter. SQLSRV_INVASC Invalid association identifier. SQLSRV_INVEXEFLG Invalid execute flag. SQLSRV_INVSELLST Invalid SQLDA or SQLDA2 select list. SQLSRV_INVSQLDA Invalid SQLDA, SQLDA2, or SQLDA_ID. SQLSRV_INVSTMID Invalid statement identifier. SQLSRV_MULTI_ACT A batched sqlsrv_execute_in_out or sqlsrv_ fetch_many context is active. SQLSRV_NETERR Network transport returned an error. SQLSRV_SVC_ The specified service has been shut down. SHUTDOWN 4 sqlsrv_execute_immediate 5 Overview The sqlsrv_execute_immediate routine prepares and executes an SQL statement that does not contain parameter markers or select list items. 5 C_Format extern int sqlsrv_execute_immediate( ASSOCIATE_ID associate_id, SQS_LONGWORD database_id, char *sql_statement); 5 Parameters 6 associate_id An identifier used to distinguish one active association from all others. 6 database_id This parameter must be 0. Databases are referenced within the SQL statement syntax. 6 sql_statement Address of a null-terminated string containing the SQL statement to be prepared and executed by dynamic SQL. 5 Notes o sqlsrv_execute_immediate provides an efficient mechanism, using a single request/response message pair, for executing an SQL statement that does not contain any parameter markers or select list items where the statement is to be executed only once. However, if the same SQL statement is to be executed multiple times, it is more efficient to prepare the statement and execute it as necessary, even if the statement contains no parameter markers or select list items. o On successful completion of a call to sqlsrv_execute_ immediate, Oracle SQL/Services stores the total number of database rows updated or deleted in the SQLERRD[2] field of the SQLCA. You can retrieve the row count from the SQLCA using the sqlsrv_sqlca_count routine. Note that Oracle Rdb does not return a row count value if you use the CALL statement to invoke a stored procedure, or if you execute a compound statement. 5 Errors SQLSRV_ The connection to the server could not be CONNTIMEOUT completed within the specified time limit. SQLSRV_EXEINTERR The executor has encountered an internal or other error condition. SQLSRV_INTERR Internal error. SQLSRV_INVARG Invalid routine parameter. SQLSRV_INVASC Invalid association identifier. SQLSRV_MULTI_ACT A batched sqlsrv_execute_in_out or sqlsrv_ fetch_many context is active. SQLSRV_NETERR Network transport returned an error. SQLSRV_SVC_ The specified service has been shut down. SHUTDOWN 4 sqlsrv_release_statement 5 Overview The sqlsrv_release_statement routine frees all resources associated with one or more prepared statements at both the client and server. The sqlsrv_release_statement routine implicitly invokes sqlsrv_free_sqlda_data or sqlsrv_free_sqlda2_ data to free dynamically allocated SQLDA or SQLDA2 structures. 5 C_Format extern int sqlsrv_release_statement( ASSOCIATE_ID associate_id, short int statement_id_count, SQS_LONGWORD *statement_id_array); 5 Parameters 6 associate_id An identifier used to distinguish one active association from all others. 6 statement_id_count The number of statement identifiers passed in the statement_id_ array. 6 statement_id_array An array containing the identifiers (statement_id parameters returned by the sqlsrv_prepare routine) of the statements to free. o You cannot release a statement that has an open cursor. o If you call sqlsrv_allocate_sqlda_data or sqlsrv_allocate_ sqlda2_data to allocate memory for parameter marker and select list item data and indicator variables, Oracle SQL/Services automatically frees the memory when you call sqlsrv_release_ statement. If you let sqlsrv_prepare allocate memory for the parameter marker and select list SQLDA or SQLDA2 structures, Oracle SQL/Services automatically frees the memory when you call sqlsrv_release_statement. o If Oracle SQL/Services encounters an error validating or releasing a particular statement ID, it discards any subsequent statement IDs and returns the error to the client application. Oracle SQL/Services stores the total number of statements released in the SQLERRD[2] field of the SQLCA. You can retrieve the count from the SQLCA using the sqlsrv_sqlca_ count routine. 5 Errors SQLSRV_ The connection to the server could not be CONNTIMEOUT completed within the specified time limit. SQLSRV_EXEINTERR The executor has encountered an internal or other error condition. SQLSRV_INTERR Internal error. SQLSRV_INVARG Invalid routine parameter. SQLSRV_INVASC Invalid association identifier. SQLSRV_INVSTMID Invalid statement identifier. SQLSRV_MULTI_ACT A batched sqlsrv_execute_in_out or sqlsrv_ fetch_many context is active. SQLSRV_NETERR Network transport returned an error. SQLSRV_SVC_ The specified service has been shut down. SHUTDOWN 3 API_Result_Table_Routines Result Table Routines Result table routines allow the caller to fetch data from the server by providing calls to open a cursor, fetch from an open cursor, and close an open cursor. Result table routines include the following routines: o sqlsrv_declare_cursor routine (see sqlsrv_declare_cursor) o sqlsrv_open_cursor routine (see sqlsrv_open_cursor) o sqlsrv_fetch routine (see sqlsrv_fetch) o sqlsrv_fetch_many routine (see sqlsrv_fetch_many) o sqlsrv_close_cursor routine (see sqlsrv_close_cursor) 4 sqlsrv_declare_cursor 5 Overview The sqlsrv_declare_cursor routine declares a dynamic cursor. If you do not use the sqlsrv_declare_cursor routine, Oracle SQL/Services implicitly declares all cursors as type table and mode update within the sqlsrv_open_cursor call. 5 C_Format extern int sqlsrv_declare_cursor( ASSOCIATE_ID associate_id, char *cursor_name SQS_LONGWORD statement_id short int cursor_type short int cursor_mode); 5 Parameters 6 associate_id An identifier used to distinguish one active association from all others. 6 cursor_name Address of a null-terminated string used to identify the cursor. 6 statement_id The statement ID returned previously by sqlsrv_prepare when the SELECT statement was prepared. The sqlsrv_declare_cursor routine maps the cursor_name to the prepared statement. 6 cursor_type A value indicating the type of list cursor to declare. You can declare table or list cursors: o Table Declare table cursors by specifying the SQLSRV_TABLE_CURSOR literal. o List Declare list cursors by specifying the SQLSRV_LIST_CURSOR literal. For detailed information about SQL list and table cursors, refer to the Oracle Rdb7 Guide to SQL Programming and the Oracle Rdb7 SQL Reference Manual. 6 cursor_mode A value indicating the mode of table or list cursors. Table cursors have four modes: o Update-only To declare table cursors in update-only mode, specify the literal SQLSRV_MODE_UPDATE_ONLY. o Update To declare table cursors in update mode, specify the literal SQLSRV_MODE_UPDATE. o Read-only To declare table cursors in read-only mode, specify the literal SQLSRV_MODE_READ_ONLY. o Insert-only To declare table cursors in insert-only mode, specify the literal SQLSRV_MODE_INSERT_ONLY. List cursors have three modes: o Read-only To declare list cursors in read-only mode, specify the literal SQLSRV_MODE_READ_ONLY. o Insert-only To declare list cursors in insert-only mode, specify the literal SQLSRV_MODE_INSERT_ONLY. o Scroll To declare list cursors in scroll mode, specify the literal SQLSRV_MODE_SCROLL. For detailed information about SQL cursor modes, refer to the Oracle Rdb7 Guide to SQL Programming and the Oracle Rdb7 SQL Reference Manual. 5 Notes o When designing applications, you should avoid using cursor names starting with the prefix "SQLSRV_"; this is a reserved prefix and is used by the Oracle SQL/Services product. o The cursor type and cursor mode literals are defined in the sqlsrv.h file. 5 Errors SQLSRV_DUPCRSNAM Duplicate cursor name. SQLSRV_INTERR Internal error. SQLSRV_INVARG Invalid routine parameter. SQLSRV_INVASC Invalid association identifier. SQLSRV_INVCURNAM Invalid cursor name. SQLSRV_INVSTMID Invalid statement identifier. SQLSRV_MULTI_ACT A batched sqlsrv_execute_in_out or sqlsrv_ fetch_many context is active. SQLSRV_NETERR Network transport returned an error. 4 sqlsrv_open_cursor 5 Overview The sqlsrv_open_cursor routine opens a cursor for a prepared SELECT statement. The sqlsrv_declare_cursor routine optionally determines the type and mode of the cursor. 5 C_Format extern int sqlsrv_open_cursor( ASSOCIATE_ID associate_id, char *cursor_name, SQS_LONGWORD statement_id, SQLDA_ID parameter_marker_sqlda); 5 Parameters 6 associate_id An identifier used to distinguish one active association from all others. 6 cursor_name Address of a null-terminated string identifying the cursor. All cursor operations, including positional INSERT, UPDATE, and DELETE statements, must use the cursor name to identify the cursor. 6 statement_id The statement ID returned previously by sqlsrv_prepare when the SELECT statement was prepared. The sqlsrv_open_cursor routine maps the cursor_name to the prepared statement. 6 parameter_marker_sqlda An SQLDA identifier defining the parameter marker values for the prepared SELECT statement. 5 Notes o After a successful call to sqlsrv_open_cursor to open a table cursor, Oracle Rdb stores the following information in the SQLCA: - Estimated result table cardinality in the SQLERRD[2] field. - Estimated I/Os in the SQLERRD[3] field. These values are retrieved using the sqlsrv_sqlca_sqlerrd routine. o After a successful call to sqlsrv_open_cursor to open a list cursor, Oracle Rdb stores the following information in the SQLCA: - Length of the largest actual segment in the SQLERRD[1] field. - Total number of segments in the SQLERRD[3] field. - Total length of all the segments as a quadword value in the SQLERRD[4] and SQLERRD[5] fields, which contain the low-order 32 bits and high-order 32 bits, respectively. These values are retrieved using the sqlsrv_sqlca_sqlerrd routine. 5 Errors SQLSRV_ The connection to the server could not be CONNTIMEOUT completed within the specified time limit. SQLSRV_DATA_TOO_ The Oracle SQL/Services executor determined LONG that the length of a data value in an SQLDA exceeded the maximum allowed for the value's data type. SQLSRV_EXEINTERR The executor has encountered an internal or other error condition. SQLSRV_INTERR Internal error. SQLSRV_INVARG Invalid routine parameter. SQLSRV_INVASC Invalid association identifier. SQLSRV_INVCURNAM Invalid cursor name. SQLSRV_INVSQLDA Invalid SQLDA, SQLDA2, or SQLDA_ID. SQLSRV_INVSTMID Invalid statement identifier. SQLSRV_MULTI_ACT A batched sqlsrv_execute_in_out or sqlsrv_ fetch_many context is active. SQLSRV_NETERR Network transport returned an error. SQLSRV_SVC_ The specified service has been shut down. SHUTDOWN 4 sqlsrv_fetch 5 Overview The sqlsrv_fetch routine fetches a row of data into a select list SQLDA. 5 C_Format extern int sqlsrv_fetch( ASSOCIATE_ID associate_id, char *cursor_name, short int scroll_option, SQS_LONGWORD position, SQLDA_ID select_list_sqlda); 5 Parameters 6 associate_id An identifier used to distinguish one active association from all others. 6 cursor_name Address of a null-terminated string used to identify the open cursor. 6 scroll_option The values of the scroll_option parameter are shown in Values of the scroll_option Parameter. Table 8 Values of the scroll_option Parameter Value Description SQLSRV_NO_SCROLL No scroll option. SQLSRV_SCROLL_FIRST Fetch first segment. SQLSRV_SCROLL_LAST Fetch last segment. SQLSRV_SCROLL_PRIOR Fetch prior segment. SQLSRV_SCROLL_NEXT Fetch next segment. SQLSRV_SCROLL_ABSOLUTE Fetch an absolute segment of the list cursor. SQLSRV_SCROLL_RELATIVE Fetch a relative segment relative to the current list cursor position. For table cursors, the scroll option must be 0 (SQLSRV_NO_ SCROLL). For scrollable list cursors, a value of SQLSRV_SCROLL_ ABSOLUTE indicates an absolute segment within the segmented string, while a value of SQLSRV_SCROLL_RELATIVE indicates a segment relative to the current cursor position. When a parameter value of SQLSRV_SCROLL_ABSOLUTE or SQLSRV_SCROLL_RELATIVE is specified, the value specified for the position argument indicates the position value. 6 position Indicates the position value for an absolute or relative scroll option. For an absolute scroll option, this parameter value indicates the nth absolute list segment of the list cursor. For a relative scroll option, this parameter value (positive or negative) indicates the nth list segment relative to the current list cursor position. For example, a value of -5 for the position parameter for a relative scroll option results in a fetch of the 5th segment previous to the current cursor position. The position parameter value must be 0 if the scroll_option parameter is not a relative or absolute scroll option. 6 select_list_sqlda The select list SQLDA identifier in which to store the row. 5 Notes o A return value of SQL_EOS indicates end of data, that is, the result table is empty, or no more rows remain in the result table. A call to the sqlsrv_fetch routine that returns a status code of SQL_EOS does not return any data in the SQLDA. o Although it returns only one row to the application for each call, the sqlsrv_fetch routine can request that the server send multiple rows of data from the server when called within an sqlsrv_fetch_many context. See Chapter 4 in the Guide to Using the Oracle SQL/Services Client API and sqlsrv_fetch_ many. o To scroll read-only list cursors, the scroll_option argument must specify a value as indicated in Values of the scroll_ option Parameter, and the position argument must specify the position value when an absolute or relative scroll_option value is specified. Otherwise, the position argument must be 0. o After a successful call to sqlsrv_fetch, Oracle SQL/Services stores the number of the current row within the result table in the SQLERRD[2] field of the SQLCA. This value can be retrieved using the sqlsrv_sqlca_sqlerrd routine. 5 Errors SQLSRV_ The connection to the server could not be CONNTIMEOUT completed within the specified time limit. SQLSRV_EXEINTERR The executor has encountered an internal or other error condition. SQLSRV_INTERR Internal error. SQLSRV_INVARG Invalid routine parameter. SQLSRV_INVASC Invalid association identifier. SQLSRV_INVCURNAM Invalid cursor name. SQLSRV_INVSQLDA Invalid SQLDA, SQLDA2, or SQLDA_ID. SQLSRV_MULTI_ACT A batched sqlsrv_execute_in_out or sqlsrv_ fetch_many context is active. SQLSRV_NETERR Network transport returned an error. SQLSRV_SVC_ The specified service has been shut down. SHUTDOWN 4 sqlsrv_fetch_many 5 Overview The sqlsrv_fetch_many routine directs the sqlsrv_fetch routine to transfer multiple rows of data from the server, as described in Chapter 4 in the Guide to Using the Oracle SQL/Services Client API. Frequently, this reduces the number of client/server messages required to retrieve data from the server. By default, sqlsrv_fetch retrieves one row of data at a time from the server. 5 C_Format extern int sqlsrv_fetch_many( ASSOCIATE_ID associate_id, char *cursor_name, short int increment, short int repeat_count); 5 Parameters 6 associate_id An identifier used to distinguish one active association from all others. 6 cursor_name Address of a null-terminated string used to identify the open cursor. 6 increment For a scrollable list cursor, the client API implicitly enables relative scroll mode (SQLSRV_SCROLL_RELATIVE) to fetch segments and uses the value in the increment argument to specify the relative position. Therefore, to fetch all segments in a segmented string, specify an increment value of 1. See sqlsrv_ fetch for more information on scroll modes and relative positions. This argument is ignored for cursors other than scrollable list cursors. 6 repeat_count The number of rows to fetch. A value of 0 fetches the entire result table. A value other than 0 fetches that number of rows. For example, an application might fetch enough rows to fill one screen. 5 Notes o To achieve the best performance, Oracle Corporation recommends that you specify a repeat_count of 0 to fetch all records. o When you specify a repeat_count other than 0, your application must call the sqlsrv_fetch_many routine again once the specified number of rows have been fetched. Otherwise, the API returns to the default behavior (one row for each call to the sqlsrv_fetch routine). See Chapter 4 in the Guide to Using the Oracle SQL/Services Client API for more information. o Once you initiate an sqlsrv_fetch_many operation, you must fetch the specified number of rows using sqlsrv_fetch or close the cursor using sqlsrv_close_cursor before you call other API routines. You can call sqlsrv_close_cursor at any time to close the cursor and end the sqlsrv_fetch_many operation before all the rows have been fetched. Otherwise, you must call sqlsrv_fetch the necessary number of times to fetch all the rows from the result table if you specify a repeat count of zero or the specified number of rows if you specify a non- zero repeat count before you can call any other API routine. o A call to the sqlsrv_close_cursor routine completes an sqlsrv_ fetch_many operation. o By default, the sqlsrv_fetch routine fetches only one row of data from the server. That way, your application can execute SQL statements INSERT...WHERE CURRENT OF cursor-name, UPDATE...WHERE CURRENT OF cursor-name, and DELETE...WHERE CURRENT OF cursor-name. o The sqlsrv_fetch_many routine initiates an sqlsrv_fetch_many operation; however, it does not fetch any rows. Therefore, sqlsrv_fetch_many returns a success status even if there are no rows in the result table. In this situation, sqlsrv_fetch returns a status of SQL_EOS the first time it is called to fetch a row from the result table. o The Oracle SQL/Services NetWare client does not support fetching multiple rows using sqlsrv_fetch_many. The sqlsrv_ fetch_many routine, when used with the IPX/SPX transport, always returns a success status, but does not start an sqlsrv_ fetch_many operation. Therefore, existing applications may call sqlsrv_fetch_many, but will not see the performance improvements normally associated with this call. The Oracle SQL/Services NetWare client does not batch result tuples to reduce the number of Oracle SQL/Services messages, due to SPX flow control limitations. 5 Errors SQLSRV_FTCMNYACT An sqlsrv_fetch_many context is already active for this cursor. SQLSRV_INTERR Internal error. SQLSRV_INVARG Invalid routine parameter. SQLSRV_INVASC Invalid association identifier. SQLSRV_INVCURNAM Invalid cursor name. SQLSRV_MULTI_ACT A batched sqlsrv_execute_in_out or sqlsrv_ fetch_many context is active. 4 sqlsrv_close_cursor 5 Overview The sqlsrv_close_cursor routine closes an open cursor. 5 C_Format extern int sqlsrv_close_cursor( ASSOCIATE_ID associate_id, char *cursor_name); 5 Parameters 6 associate_id An identifier used to distinguish one active association from all others. 6 cursor_name Address of a null-terminated string used to identify the open cursor. 5 Errors SQLSRV_ The connection to the server could not be CONNTIMEOUT completed within the specified time limit. SQLSRV_EXEINTERR The executor has encountered an internal or other error condition. SQLSRV_INTERR Internal error. SQLSRV_INVASC Invalid association identifier. SQLSRV_INVCURNAM Invalid cursor name. SQLSRV_NETERR Network transport returned an error. SQLSRV_SVC_ The specified service has been shut down. SHUTDOWN 3 API_Utility_Routines Utility Routines Utility routines provide local service to the caller. Utility routines include the following routines: o sqlsrv_allocate_sqlda_data or sqlsrv_allocate_sqlda2_data routine (see sqlsrv_allocate_sqlda_data or sqlsrv_allocate_ sqlda2_data) o sqlsrv_free_sqlda_data or sqlsrv_free_sqlda2_data routine (see sqlsrv_free_sqlda_data or sqlsrv_free_sqlda2_data) o sqlsrv_set_option routine (see sqlsrv_set_option) 4 sqlsrv_allocate_sqlda_data_or_sqlsrv_allocate_sqlda2_data 5 Overview The sqlsrv_allocate_sqlda_data or sqlsrv_allocate_sqlda2_data routine dynamically allocates memory for data and indicator variables. Your application passes an SQLDA_ID identifier to sqlsrv_allocate_sqlda_data or sqlsrv_allocate_sqlda2_data, which allocates buffers of the appropriate size and writes the addresses of the newly allocated buffers into the SQLDATA and SQLIND fields in the SQLVAR or SQLVAR2 array. NOTE You must not modify the SQLDATA and SQLIND fields in the SQLVAR or SQLVAR2 fields if you call sqlsrv_allocate_sqlda_ data or sqlsrv_allocate_sqlda2_data to allocate memory for data and indicator variables. The operation and results of other client API routines will be unpredictable if you modify these fields. The format, parameters, description, notes, and errors for the SQLDA or SQLDA2 routines are identical unless otherwise specified. 5 C_Format extern int sqlsrv_allocate_sqlda_data( ASSOCIATE_ID associate_id, SQLDA_ID sqlda_str); extern int sqlsrv_allocate_sqlda2_data( ASSOCIATE_ID associate_id, SQLDA_ID sqlda_str); 5 Parameters 6 associate_id An identifier used to distinguish one active association from all others. 6 sqlda_str The identifier of a parameter marker or select list SQLDA or SQLDA2 for which to allocate data and indicator variables. 5 Notes o You can free buffers allocated by the sqlsrv_allocate_sqlda_ data or sqlsrv_allocate_sqlda2_data routine explicitly by calling the sqlsrv_free_sqlda_data or sqlsrv_free_sqlda2_data routine, or implicitly by calling the sqlsrv_release_statement or sqlsrv_release routine. o The sqlsrv_allocate_sqlda_data or sqlsrv_allocate_sqlda2_data routine allocates additional memory for certain data types, as shown in Special Requirements of Data Types to Determine Extra Byte Lengths to Allocate. Table 9 Special Requirements of Data Types to Determine Extra Byte Lengths to Allocate Data Type Extra Memory to Allocate SQLSRV_ASCII_STRING +1 for null-terminating select list item values; note that parameter marker values are not treated as null-terminated strings SQLSRV_GENERALIZED_ +1 for null terminator DATE SQLSRV_INTERVAL +1 for null terminator SQLSRV_GENERALIZED_ +6 for null terminator and to allow input NUMBER in scientific notation [for example, 9999E+123] SQLSRV_VARCHAR +2 for SQLDAs or +4 for SQLDA2s for leading length field SQLSRV_VARBYTE +2 for SQLDAs or +4 for SQLDA2s for leading length field 5 Errors SQLSRV_INTERR Internal error. SQLSRV_INVARG Invalid routine parameter. SQLSRV_INVASC Invalid association identifier. SQLSRV_INVDATTYP Invalid data type. SQLSRV_INVSQLDA Invalid SQLDA, SQLDA2, or SQLDA_ID. SQLSRV_NO_MEM API memory allocation failed. SQLSRV_USRDATALL The user, not Oracle SQL/Services, has allocated data buffers. 4 sqlsrv_free_sqlda_data_or_sqlsrv_free_sqlda2_data 5 Overview The sqlsrv_free_sqlda_data or sqlsrv_free_sqlda2_data routine frees buffers that hold data and indicator variables that were dynamically allocated by the sqlsrv_allocate_sqlda_data or sqlsrv_allocate_sqlda2_data routine. Your application passes an SQLDA_ID identifier to the API, which frees the buffers and writes zeros into the SQLDATA and SQLIND fields of the SQLVAR or SQLVAR2 array. NOTE The sqlsrv_release_statement and sqlsrv_release routines implicitly call the sqlsrv_free_sqlda_data or sqlsrv_ free_sqlda2_data routine for each prepared statement's dynamically allocated SQLDA or SQLDA2 structure. The format, parameters, description, notes, and errors for the SQLDA or SQLDA2 routines are identical unless otherwise specified. 5 C_Format extern int sqlsrv_free_sqlda_data( ASSOCIATE_ID associate_id, SQLDA_ID sqlda_str); extern int sqlsrv_free_sqlda2_data( ASSOCIATE_ID associate_id, SQLDA_ID sqlda_str); 5 Parameters 6 associate_id An identifier used to distinguish one active association from all others. 6 sqlda_str The identifier of a parameter marker or select list SQLDA or SQLDA2 for which to deallocate data and indicator variables. 5 Errors SQLSRV_ACTSTM The statement id already has an active cursor. SQLSRV_INTERR Internal error. SQLSRV_INVASC Invalid association identifier. SQLSRV_INVSQLDA Invalid SQLDA, SQLDA2, or SQLDA_ID. SQLSRV_MULTI_ACT A batched sqlsrv_execute_in_out or sqlsrv_ fetch_many context is active. SQLSRV_SQLDA_ Attempt to deallocate static memory. NOTALL SQLSRV_USRDATALL The user, not Oracle SQL/Services, has allocated data buffers. 4 sqlsrv_set_option 5 Overview The sqlsrv_set_option routine sets the option that determines whether the Oracle SQL/Services client and server use the standard SQLDA or the extended SQLDA2 format for new statements that the application prepares. 5 C_Format extern int sqlsrv_set_option( ASSOCIATE_ID association, SQS_LONGWORD option, SQS_LONGWORD value, void *rsv); 5 Parameters 6 association An identifier used to distinguish one association from all others. 6 option The option to set. The option parameter takes the argument SQLSRV_OPT_SQLDA_TYPE. 6 value The value determines whether the SQLDA or SQLDA2 is set. The value parameter takes either of the arguments described in Value Parameter Arguments If the Option Parameter Argument is SQLSRV_OPT_SQLDA_TYPE when the option parameter argument SQLSRV_ OPT_SQLDA_TYPE is specified. Table 10 Value Parameter Arguments If the Option Parameter Argument is SQLSRV_OPT_SQLDA_TYPE Argument Description SQLSRV_OPT_SQLDA_SQLDA Use standard SQLDA format SQLSRV_OPT_SQLDA_SQLDA2 Use extended SQLDA2 format 6 rsv Argument reserved for future use. The value of this argument must be NULL. 5 Notes o If you do not call the sqlsrv_set_option routine to set the SQLDA format, Oracle SQL/Services uses the standard SQLDA format. To use the extended SQLDA2 format, you must call the sqlsrv_set_option routine, specifying the option as SQLSRV_ OPT_SQLDA_TYPE and the value as SQLSRV_OPT_SQLDA_SQLDA2, before you call sqlsrv_prepare to prepare an SQL statement. 5 Errors SQLSRV_INVARG Invalid routine parameter. SQLSRV_INVASC Invalid association identifier. 3 API_Functional_Interface_Routines Functional Interface Routines Functional interface routines provide access to data and metadata stored in SQLCA, SQLDA, and SQLDA2 structures. These routines replace the need for making direct references to structure fields in API applications. Functional interface routines include the following routines: o sqlsrv_sqlca_error routine (see sqlsrv_sqlca_error) o sqlsrv_sqlca_error_text routine (see sqlsrv_sqlca_error_text) o sqlsrv_sqlca_count routine (see sqlsrv_sqlca_count) o sqlsrv_sqlca_sqlerrd routine (see sqlsrv_sqlca_sqlerrd) o sqlsrv_sqlda_sqld or sqlsrv_sqlda2_sqld routine (see sqlsrv_ sqlda_sqld or sqlsrv_sqlda2_sqld) o sqlsrv_sqlda_column_name or sqlsrv_sqlda2_column_name routine (see sqlsrv_sqlda_column_name or sqlsrv_sqlda2_column_name) o sqlsrv_sqlda_column_type or sqlsrv_sqlda2_column_type routine (see sqlsrv_sqlda_column_type or sqlsrv_sqlda2_column_type) o sqlsrv_sqlda_bind_data or sqlsrv_sqlda2_bind_data routine (see sqlsrv_sqlda_bind_data or sqlsrv_sqlda2_bind_data) o sqlsrv_sqlda_unbind_sqlda or sqlsrv_sqlda2_unbind_sqlda2 routine (see sqlsrv_sqlda_unbind_sqlda or sqlsrv_sqlda2_ unbind_sqlda2) o sqlsrv_sqlda_ref_data or sqlsrv_sqlda2_ref_data routine (see sqlsrv_sqlda_ref_data or sqlsrv_sqlda2_ref_data) o sqlsrv_sqlda_unref_data or sqlsrv_sqlda2_unref_data routine (see sqlsrv_sqlda_unref_data or sqlsrv_sqlda2_unref_data) o sqlsrv_sqlda_get_data or sqlsrv_sqlda2_get_data routine (see sqlsrv_sqlda_get_data or sqlsrv_sqlda2_get_data) o sqlsrv_sqlda_set_data or sqlsrv_sqlda2_set_data routine (see sqlsrv_sqlda_set_data or sqlsrv_sqlda2_set_data) o sqlsrv_sqlda_set_sqllen or sqlsrv_sqlda2_set_sqllen routine (see sqlsrv_sqlda_set_sqllen or sqlsrv_sqlda2_set_sqllen) o sqlsrv_sqlda2_char_set_info routine (see sqlsrv_sqlda2_char_ set_info) 4 sqlsrv_sqlca_error 5 Overview The sqlsrv_sqlca_error routine returns the error codes for the last statement executed. 5 C_Format extern int sqlsrv_sqlca_error( ASSOCIATE_ID associate_id, SQS_LONGWORD *majerr, SQS_LONGWORD *suberr1, SQS_LONGWORD *suberr2); 5 Parameters 6 associate_id An identifier used to distinguish one active association from all others. 6 majerr Address of a variable of type SQS_LONGWORD into which the API writes the major error code from the SQLCODE field of the SQLCA. 6 suberr1 Address of a variable of type SQS_LONGWORD into which the API writes the minor error code from the SQLERRD[0] field of the SQLCA. 6 suberr2 Address of a variable of type SQS_LONGWORD into which the API writes the minor error code from the SQLERRD[2] field of the SQLCA. 5 Notes o After you call the Oracle SQL/Services API routine, the SQLCA structure contains the return status. 5 Errors SQLSRV_INVASC Invalid association identifier. 4 sqlsrv_sqlca_error_text 5 Overview The sqlsrv_sqlca_error_text routine returns the error text for the last statement executed. 5 C_Format extern int sqlsrv_sqlca_error_text( ASSOCIATE_ID associate_id, short int *msglen, char *msg, short int buflen); 5 Parameters 6 associate_id An identifier used to distinguish one active association from all others. 6 msglen Address of a variable of type short into which the API writes the length in bytes of the error message text written to the buffer specified by the msg parameter. 6 msg Address of a buffer of type char into which the API writes the error message text. 6 buflen Length in bytes of the buffer specified by the msg parameter. 5 Notes o The error message text is copied into the specified buffers and null-terminated. o The length of the error excluding the null-terminator is returned in msglen. 4 sqlsrv_sqlca_count 5 Overview The sqlsrv_sqlca_count routine returns the number of rows processed by a statement. 5 C_Format extern int sqlsrv_sqlca_count( ASSOCIATE_ID associate_id); 5 Parameters 6 associate_id An identifier used to distinguish one active association from all others. 5 Notes o This call replaces direct access to the SQLCA.SQLERRD[2] field. o The SQLCA.SQLERRD[2] field contains a valid row count only when a statement, or all statements in a batch execute operation, executes successfully. 5 Errors SQLSRV_INVASC Invalid association identifier. 4 sqlsrv_sqlca_sqlerrd 5 Overview The sqlsrv_sqlca_sqlerrd routine returns all values from the SQLCA.SQLERRD array. 5 C_Format extern int sqlsrv_sqlca_sqlerrd( ASSOCIATE_ID associate_id, SQS_LONGWORD *sqlerrd_array); 5 Parameters 6 associate_id An identifier used to distinguish one active association from all others. 6 sqlerrd_array Address of an array of 6 elements of type SQS_LONGWORD into which the API writes the contents of the SQLERRD array. 5 Notes o See the SQLERRD structure description in Chapter 7 of the Guide to Using the Oracle SQL/Services Client API for details of information returned in the SQLERRD array. 5 Errors SQLSRV_INVASC Invalid association identifier. 4 sqlsrv_sqlda_sqld_or_sqlsrv_sqlda2_sqld 5 Overview The sqlsrv_sqlda_sqld or sqlsrv_sqlda2_sqld routine returns the number of parameter markers or select list items in the SQLDA or SQLDA2. NOTE The format, parameters, description, notes, and errors for the SQLDA or SQLDA2 routines are identical unless otherwise specified. 5 C_Format extern int sqlsrv_sqlda_sqld( SQLDA_ID sqldaid); extern int sqlsrv_sqlda2_sqld( SQLDA_ID sqldaid); 5 Parameters 6 sqldaid The identifier of a parameter marker or select list SQLDA or SQLDA2. 5 Notes o This call corresponds to referencing the SQLD field in an SQLDA or SQLDA2. The field is set by the API after a statement is prepared. 5 Errors SQLSRV_INVSQLDA Invalid SQLDA, SQLDA2, or SQLDA_ID. 4 sqlsrv_sqlda_column_name_or_sqlsrv_sqlda2_column_name 5 Overview The sqlsrv_sqlda_column_name or sqlsrv_sqlda2_column_name routine copies the column name for a particular column from the SQLDA or SQLDA2, respectively, into a program variable. NOTE The format, parameters, description, notes, and errors for the SQLDA or SQLDA2 routines are identical unless otherwise specified. 5 C_Format extern int sqlsrv_sqlda_column_name( SQLDA_ID sqldaid, short int colnum, char *colnam, short int *colnamlen); extern int sqlsrv_sqlda2_column_name( SQLDA_ID sqldaid, short int colnum, char *colnam, short int *colnamlen); 5 Parameters 6 sqldaid The identifier of a parameter marker or select list SQLDA or SQLDA2. 6 colnum A column identified by its ordinal position in a parameter or select list. 6 colnam Address of a buffer of type char into which the API writes the column name as a null-terminated character string. For an SQLDA, the buffer must be at least 30 bytes long; for an SQLDA2, the buffer must be at least 32 bytes long. 6 colnamlen Address of a variable of type short into which the API writes the length in bytes of the column name written to the colnam parameter. 5 Notes o Oracle SQL/Services returns an error if the SQLDA or SQLDA2 is invalid or if the column number is greater than the number of parameter markers or select list items (colnum >= sqlda.SQLD). o The column name for a particular column is copied from the SQLDA into the variable passed in this call. o Oracle Rdb does not assign a value to the column name in the following situations: - If a select list item, assignment, or comparison involves an arithmetic expression or predicates other than basic predicates. - For parameter markers and select list items specified in statements contained in a compound statement. o The maximum length of a column name in an Oracle Rdb database is 31 characters. However, the maximum length of a column name stored by Oracle SQL/Services in the SQLNAME field of a client SQLDA is 29 characters. This is because the SQLNAME field is only 30 characters long and because Oracle SQL/Services null-terminates the column name in the SQLNAME field of a client SQLDA. The maximum length of a column name in the SQLNAME field of an Oracle SQL/Services client SQLDA2 is 31 characters. 5 Errors SQLSRV_INVCOLNUM Column number not within range. SQLSRV_INVSQLDA Invalid SQLDA, SQLDA2, or SQLDA_ID. 4 sqlsrv_sqlda_column_type_or_sqlsrv_sqlda2_column_type 5 Overview The sqlsrv_sqlda_column_type or sqlsrv_sqlda2_column_type routine returns information about the data type of a column. NOTE The format, parameters, description, notes, and errors for the SQLDA and SQLDA2 routines are identical unless otherwise specified. 5 C_Format extern int sqlsrv_sqlda_column_type( SQLDA_ID sqldaid, short int colnum, short int *coltyp, unsigned short int *collen, short int *colscl, void *rsv); extern int sqlsrv_sqlda2_column_type( SQLDA_ID sqldaid, short int colnum, short int *coltyp, SQS_UNSIGNED_LONGWORD *collen, short int *colscl, SQS_UNSIGNED_LONGWORD *coloctlen, void *rsv); 5 Parameters 6 sqldaid The identifier of a parameter marker or select list SQLDA or SQLDA2. 6 colnum A column identified by its ordinal position in a parameter or select list. 6 coltyp Address of a variable of type short into which the API writes the Oracle SQL/Services data type of the column. 6 collen Address of a variable into which the API writes the length of the column. For an SQLDA, the column length is expressed in an unsigned word as the number of 8-bit bytes. For an SQLDA2, the column length is expressed in an unsigned longword as the number of characters, where a single character might occupy more than one byte in a multibyte character set. 6 colscl Address of a variable of type short into which the API writes the scale factor for columns of type SQLSRV_GENERALIZED_NUMBER or the type of date or interval for columns of type SQLSRV_GENERALIZED_ DATE or SQLSRV_INTERVAL, respectively. Undefined for columns of all other data types. 6 coloctlen_(SQLDA2_only) Address of a variable of type SQS_UNSIGNED_LONGWORD into which the API writes the length of the column in octets or 8-bit bytes. 6 rsv Argument reserved for future use. The value of this argument must be NULL. 5 Notes o Oracle SQL/Services returns an error if the SQLDA or SQLDA2 is invalid or if the column number is greater than the number of parameter markers or select list items (colnum >= sqlda.SQLD). o See Chapter 8 in the Guide to Using the Oracle SQL/Services Client API for information on all Oracle SQL/Services data types. 5 Errors SQLSRV_INVCOLNUM Column number not within range. SQLSRV_INVSQLDA Invalid SQLDA, SQLDA2, or SQLDA_ID. 4 sqlsrv_sqlda_bind_data_or_sqlsrv_sqlda2_bind_data 5 Overview The sqlsrv_sqlda_bind_data or sqlsrv_sqlda2_bind_data routine allows programs to allocate their own storage for data and indicator variables for parameter markers and select list items. NOTE The format, parameters, description, notes, and errors for the SQLDA and SQLDA2 routines are identical unless otherwise specified. 5 C_Format extern int sqlsrv_sqlda_bind_data( SQLDA_ID sqldaid, short int colnum, short int coltyp, unsigned short int collen, short int colscl, CHARPTR datptr, SHORTPTR nulptr, void *rsv); extern int sqlsrv_sqlda2_bind_data( SQLDA_ID sqldaid, short int colnum, short int coltyp, SQS_UNSIGNED_LONGWORD collen, short int colscl, CHARPTR datptr, LONGPTR nulptr, SQS_UNSIGNED_LONGWORD octet_len, SQS_LONGWORD chrono_scale, SQS_LONGWORD chrono_precision, void *rsv); 5 Parameters 6 sqldaid The identifier of a parameter marker or select list SQLDA or SQLDA2. 6 colnum A column identified by its ordinal position in a parameter or select list. 6 coltyp Address of a variable of type short into which the API writes the Oracle SQL/Services data type of the column. 6 collen Address of a variable into which the API writes the length of the column. For an SQLDA, the column length is expressed in an unsigned word as the number of 8-bit bytes. For an SQLDA2, the column length is expressed in an unsigned longword as the number of characters, where a single character might occupy more than one byte in a multibyte character set. 6 colscl Address of a variable of type short into which the API writes the scale factor for columns of type SQLSRV_GENERALIZED_NUMBER or the type of date or interval for columns of type SQLSRV_ GENERALIZED_DATE or SQLSRV_INTERVAL, respectively. This parameter is undefined for columns of all other data types. 6 datptr Address of the data variable of type unsigned char for the column. 6 nulptr Address of the indicator variable for the column. For an SQLDA, the indicator variable is of type short. For an SQLDA2, the indicator variable is of type SQS_LONGWORD. See the SQLVAR and SQLVAR2 structure descriptions in Chapter 7 of the Guide to Using the Oracle SQL/Services Client API for a description of the indicator variable (SQLIND field) of an SQLDA or SQLDA2, respectively. 6 octlen_len_(SQLDA2_only) Address of a variable of type SQS_UNSIGNED_LONGWORD into which the API writes the length in octets of the column. 6 chrono_scale_(SQLDA2_only) Address of a variable of type SQS_LONGWORD into which the API writes the specific date-time data type for columns of type SQLSRV_GENERALIZED_DATE or the interval scale for columns of type SQLSRV_INTERVAL. 6 chrono_precision_(SQLDA2_only) Address of a variable of type SQS_LONGWORD into which the API writes the precision of the date-time value or interval value for columns of type SQLSRV_GENERALIZED_DATE or SQLSRV_INTERVAL, respectively. 6 rsv Argument reserved for future use. The value of this argument must be NULL. 5 Notes o Oracle SQL/Services returns an error if the SQLDA or SQLDA2 is invalid or if the column number is greater than the number of parameter markers or select list items (colnum >= sqlda.SQLD). o The sqlsrv_sqlda_bind_data and sqlsrv_sqlda2_bind_data routines provide an efficient mechanism for an application program to provide its own memory for data and indicator variables for parameter markers and select list items. After preparing a statement, the application must examine each column, allocate an appropriate amount of memory for both the data and indicator variables, then bind that memory to the column in the SQLDA or SQLDA2 using the sqlsrv_sqlda_bind_ data or sqlsrv_sqlda2_bind_data routine, respectively. Before releasing the statement, the application program must unbind the memory for the column's data and indicator variables from the SQLDA or SQLDA2 using the sqlsrv_sqlda_unbind_data or sqlsrv_sqlda2_unbind_data routine, respectively. o Applications that use the sqlsrv_sqlda_bind_data and sqlsrv_ sqlda2_bind_data routines to provide memory for data and indicator variables in an SQLDA or SQLDA2 must allocate memory for all the parameter markers and select list items in the SQLDA or SQLDA. You cannot use the sqlsrv_allocate_sqlda_data or sqlsrv_allocate_sqlda2_data routines to allocate memory for the same SQLDA or SQLDA2 for which you have bound user memory to data and indicator variables. o Calling the sqlsrv_sqlda_bind_data and sqlsrv_sqlda2_bind_data routines is equivalent to directly storing pointers and values in the SQLDATA, SQLIND, SQLLEN, and SQLOCTET_LEN fields of a column's SQLVARARY array element in an SQLDA or SQLDA2. 5 Errors SQLSRV_INCDATTYP Incompatible data type with column. SQLSRV_INVCOLNUM Column number not within range. SQLSRV_INVDATTYP Invalid data type. SQLSRV_INVSQLDA Invalid SQLDA, SQLDA2, or SQLDA_ID. SQLSRV_NO_MEM API memory allocation failed. 4 sqlsrv_sqlda_unbind_sqlda_or_sqlsrv_sqlda2_unbind_sqlda2 5 Overview The sqlsrv_sqlda_unbind_sqlda or sqlsrv_sqlda2_unbind_sqlda2 routine releases variables bound with the sqlsrv_sqlda_bind_data or sqlsrv_sqlda2_bind_data routine. NOTE The format, parameters, description, notes, and errors for the SQLDA or SQLDA2 routines are identical unless otherwise specified. 5 C_Format extern int sqlsrv_sqlda_unbind_sqlda( SQLDA_ID sqldaid); extern int sqlsrv_sqlda2_unbind_sqlda2( SQLDA_ID sqldaid); 5 Parameters 6 sqldaid The identifier of a parameter marker or select list SQLDA or SQLDA2. 5 Notes o A single call to sqlsrv_sqlda_unbind_data or sqlsrv_sqlda2_ unbind_data unbinds the memory provided for all the data and indicator variables in an SQLDA or SQLDA2 bound by one or more calls to sqlsrv_sqlda_bind_data or sqlsrv_sqlda2_bind_data. On the Macintosh platform, it also releases memory allocated to maintain the application's memory pointers. o Calling the sqlsrv_sqlda_bind_data and sqlsrv_sqlda2_bind_data routines is equivalent to directly clearing the pointers in the SQLDATA and SQLIND fields of a column's SQLVARARY array element in an SQLDA or SQLDA2. 5 Errors SQLSRV_INVSQLDA Invalid SQLDA, SQLDA2, or SQLDA_ID. 4 sqlsrv_sqlda_ref_data_or_sqlsrv_sqlda2_ref_data 5 Overview The sqlsrv_sqlda_ref_data or sqlsrv_sqlda2_ref_data routine returns the type, length, scale, or date-time type, and address of the data and indicator variables for a column in an SQLDA or SQLDA2, respectively. In the SQLDA2, the sqlsrv_sqlda2_ref_ data routine also returns the octet length, chrono-scale, and chrono-precision for a column. NOTE The format, parameters, description, notes, and errors for the SQLDA and SQLDA2 routines are identical unless otherwise specified. 5 C_Format extern int sqlsrv_sqlda_ref_data( SQLDA_ID sqldaid, short int colnum, short int *coltyp, unsigned short int *collen, short int *colscl, PTRCHARPTR val, PTRSHORTPTR nullp, void *rsv); extern int sqlsrv_sqlda2_ref_data( SQLDA_ID sqldaid, short int colnum, short int *coltyp, SQS_UNSIGNED_LONGWORD *collen, short int *colscl, PTRCHARPTR val, PTRLONGPTR nullp, SQS_UNSIGNED_LONGWORD *octet_len, SQS_LONGWORD *chrono_scale, SQS_LONGWORD *chrono_precision, void *rsv); 5 Parameters 6 sqldaid The identifier of a parameter marker or select list SQLDA or SQLDA2. 6 colnum A column identified by its ordinal position in a parameter or select list. 6 coltyp Address of a variable of type short into which the API writes the Oracle SQL/Services data type of the column. 6 collen Address of a variable into which the API writes the length of the column. For an SQLDA, the column length is expressed in an unsigned word as the number of 8-bit bytes. For an SQLDA2, the column length is expressed in an unsigned longword as the number of characters, where a single character might occupy more than one byte in a multibyte character set. 6 colscl Address of a variable of type short into which the API writes the scale factor for columns of type SQLSRV_GENERALIZED_NUMBER or the type of date or interval for columns of type SQLSRV_GENERALIZED_ DATE or SQLSRV_INTERVAL, respectively. Undefined for columns of all other data types. 6 val The address of a variable of type CHARPTR into which the API writes the address of the column's data variable. 6 nullp Address of a variable into which the API writes the address of the column's indicator variable. For an SQLDA, the indicator variable is of type short. For an SQLDA2, the indicator variable is of type SQS_LONGWORD. See the SQLVAR and SQLVAR2 structure descriptions in Chapter 7 of the Guide to Using the Oracle SQL/Services Client API for a description of the indicator variable (SQLIND field) of an SQLDA or SQLDA2, respectively. 6 octlen_len_(SQLDA2_only) Address of a variable of type SQS_UNSIGNED_LONGWORD into which the API writes the length in octets of the column. 6 chrono_scale_(SQLDA2_only) Address of a variable of type SQS_LONGWORD into which the API writes the specific date-time data type for columns of type SQLSRV_GENERALIZED_DATE or the interval scale for columns of type SQLSRV_INTERVAL. 6 chrono_precision_(SQLDA2_only) Address of a variable of type SQS_LONGWORD into which the API writes the precision of the date-time value or interval value for columns of type SQLSRV_GENERALIZED_DATE or SQLSRV_INTERVAL, respectively. 6 rsv Argument reserved for future use. The value of this argument must be NULL. 5 Notes o Oracle SQL/Services returns an error if the SQLDA or SQLDA2 is invalid or if the column number is greater than the number of parameter markers or select list items (colnum >= sqlda.SQLD). o Use the sqlsrv_sqlda_ref_data or sqlsrv_sqlda2_ref_data routine to access a column's data and indicator variables allocated by the sqlsrv_allocate_sqlda_data or sqlsrv_ allocate_sqlda2_data routine. It is equivalent to reading the SQLLEN, SQLTYPE, SQLDATA, and SQLIND fields of the SQLVAR or SQLVAR2 structure, and for SQLDA2, the SQLOCTET_LEN, SQLCHRONO_SCALE, and SQLCHRONO_PRECISION fields of the SQLVAR2 structure for the column. o Oracle SQL/Services transparently allocates memory for data and indicator variables using handles on the Macintosh platform. To provide a consistent, portable interface on the Macintosh platform with other client platforms, the sqlsrv_ sqlda_ref_data and sqlsrv_sqlda2_ref_data routines lock the memory handles, then return the pointers, rather than the handles, to the data and indicator variables. Therefore, when your application has finished accessing data and indicator variables, you must call the sqlsrv_sqlda_unref_data and sqlsrv_sqlda2_unref_data routines to unlock the memory handles. 5 Errors SQLSRV_INVCOLNUM Column number not within range. SQLSRV_INVSQLDA Invalid SQLDA, SQLDA2, or SQLDA_ID. 4 sqlsrv_sqlda_unref_data_or_sqlsrv_sqlda2_unref_data 5 Overview The sqlsrv_sqlda_unref_data or sqlsrv_sqlda2_unref_data routine frees resources tied up by the sqlsrv_sqlda_ref_data or sqlsrv_ sqlda2_ref_data routine. NOTE The format, parameters, description, notes, and errors for the SQLDA or SQLDA2 routines are identical unless otherwise specified. 5 C_Format extern int sqlsrv_sqlda_unref_data( SQLDA_ID sqldaid, short int colnum); extern int sqlsrv_sqlda2_unref_data( SQLDA_ID sqldaid, short int colnum); 5 Parameters 6 sqldaid The identifier of a parameter marker or select list SQLDA or SQLDA2. 6 colnum A column identified by its ordinal position in a parameter or select list. 5 Notes o Oracle SQL/Services returns an error if the SQLDA or SQLDA2 is invalid or if the column number is greater than the number of parameter markers or select list items (colnum >= sqlda.SQLD). o Oracle SQL/Services transparently allocates memory for data and indicator variables using handles on the Macintosh platform. To provide a consistent, portable interface on the Macintosh platform with other client platforms, the sqlsrv_ sqlda_ref_data and sqlsrv_sqlda2_ref_data routines lock the memory handles, then return the pointers, rather than the handles, to the data and indicator variables. Therefore, when your application has finished accessing data and indicator variables, you must call the sqlsrv_sqlda_unref_data and sqlsrv_sqlda2_unref_data routines to unlock the memory handles. On all other client platforms, the sqlsrv_sqlda_ unref_data and sqlsrv_sqlda2_unref_data routines have no effect. 5 Errors SQLSRV_INVCOLNUM Column number not within range. SQLSRV_INVSQLDA Invalid SQLDA, SQLDA2, or SQLDA_ID. 4 sqlsrv_sqlda_get_data_or_sqlsrv_sqlda2_get_data 5 Overview The sqlsrv_sqlda_get_data or sqlsrv_sqlda2_get_data routine copies column data and indicator variables from the SQLDA or SQLDA2, respectively, to a program. NOTE The format, parameters, description, notes, and errors for the SQLDA and SQLDA2 routines are identical unless otherwise specified. 5 C_Format extern int sqlsrv_sqlda_get_data( SQLDA_ID sqldaid, short int colnum, unsigned short int offset, CHARPTR dst, unsigned short int dstlen, SHORTPTR nullp, unsigned short int *bytcpy); extern int sqlsrv_sqlda2_get_data( SQLDA_ID sqldaid, short int colnum, SQS_UNSIGNED_LONGWORD offset, CHARPTR dst, SQS_UNSIGNED_LONGWORD dstlen, LONGPTR nullp, SQS_UNSIGNED_LONGWORD *bytcpy); 5 Parameters 6 sqldaid The identifier of a parameter marker or select list SQLDA or SQLDA2. 6 colnum A column identified by its ordinal position in a parameter or select list. 6 offset The offset within the column's data variable at which to start the copy. The most typical value for the offset parameter is zero, which means to start the copy at the beginning of the column's data variable. For an SQLDA, the offset is of type unsigned short. For an SQLDA2, the offset is of type SQS_ UNSIGNED_LONGWORD. 6 dst The address of a buffer of type unsigned char to which the data is copied. 6 dstlen The length in bytes of the buffer specified as the dst argument. For an SQLDA, the length is of type unsigned short. For an SQLDA2, the length is of type SQS_UNSIGNED_LONGWORD. 6 nullp Address of a variable into which Oracle SQL/Services writes the value of the column indicator variable. For an SQLDA, the indicator variable is of type short. For an SQLDA2, the indicator variable is of type SQS_LONGWORD. See the SQLVAR and SQLVAR2 structure descriptions in Chapter 7 of the Guide to Using the Oracle SQL/Services Client API for a description of the indicator variable (SQLIND field) of an SQLDA or SQLDA2, respectively. 6 bytcpy Address of a variable into which the API writes the number of bytes of data actually copied. For an SQLDA, the variable is of type unsigned short. For an SQLDA2, the variable is of type SQS_ UNSIGNED_LONGWORD. 5 Notes o Oracle SQL/Services returns an error if the SQLDA or SQLDA2 is invalid or if the column number is greater than the number of parameter markers or select list items (colnum >= sqlda.SQLD). o The sqlsrv_sqlda_get_data or sqlsrv_sqlda2_get_data routine provides access to SQLDA or SQLDA2 information for languages that do not support explicit type coercion. Note that the use of the sqlsrv_sqlda_get_data or sqlsrv_sqlda2_get_data routine requires the host language to support some form of type coercion. o When the sqlsrv_sqlda_get_data or sqlsrv_sqlda2_get_data routine is used, data is copied between the SQLDA or SQLDA2 and the user's buffer. o The offset field provides some flexibility to callers, allowing you to take a selected section out of the field in question. The most typical value for the offset field is zero (0), which means to start copying at the beginning of the data. The maximum allowable value for the offset field is the maximum length of the SQLDATA buffer. 5 Errors SQLSRV_INVCOLNUM Column number not within range. SQLSRV_INVSQLDA Invalid SQLDA, SQLDA2, or SQLDA_ID. 4 sqlsrv_sqlda_set_data_or_sqlsrv_sqlda2_set_data 5 Overview The sqlsrv_sqlda_set_data or sqlsrv_sqlda2_set_data routine copies column information into the SQLDA or SQLDA2, respectively. NOTE The format, parameters, description, notes, and errors for the SQLDA and SQLDA2 routines are identical unless otherwise specified. 5 C_Format extern int sqlsrv_sqlda_set_data( SQLDA_ID sqldaid, short int colnum, unsigned short int offset, CHARPTR dst, unsigned short int dstlen, short int nullp, unsigned short int *bytcpy); extern int sqlsrv_sqlda2_set_data( SQLDA_ID sqldaid, short int colnum, SQS_UNSIGNED_LONGWORD offset, CHARPTR dst, SQS_UNSIGNED_LONGWORD dstlen, SQS_LONGWORD nullp, SQS_UNSIGNED_LONGWORD *bytcpy); 5 Parameters 6 sqldaid The identifier of a parameter marker or select list SQLDA or SQLDA2. 6 colnum A column identified by its ordinal position in a parameter or select list. 6 offset The offset within the column's data variable at which to start the copy. The most typical value for the offset parameter is zero (0), which means to start the copy at the beginning of the column's data variable. For an SQLDA, the offset is of type unsigned short. For an SQLDA2, the offset is of type SQS_ UNSIGNED_LONGWORD. 6 dst The address of a buffer of type unsigned char containing the data to be copied to the SQLDATA buffer. 6 dstlen The length in bytes of the buffer specified as the dst argument. For an SQLDA, the length is of type unsigned short. For an SQLDA2, the length is of type SQS_UNSIGNED_LONGWORD. 6 nullp The value for the column's indicator variable. For an SQLDA, the indicator is of type short. For an SQLDA2, the indicator is of type SQS_LONGWORD. See the SQLVAR and SQLVAR2 structure descriptions in Chapter 7 of the Guide to Using the Oracle SQL/Services Client API for a description of the indicator variable (SQLIND field) of an SQLDA or SQLDA2, respectively. 6 bytcpy Address of a variable into which the API writes the number of bytes of data actually copied. For an SQLDA, the variable is of type unsigned short. For an SQLDA2, the variable is of type SQS_ UNSIGNED_LONGWORD. 5 Notes o Oracle SQL/Services returns an error if the SQLDA or SQLDA2 is invalid or if the column number is greater than the number of parameter markers or select list items (colnum >= sqlda.SQLD). o The sqlsrv_sqlda_set_data or sqlsrv_sqlda2_set_data routine complements the sqlsrv_sqlda_get_data or sqlsrv_sqlda2_get_ data routine. It is used to copy values into a column's data and indicator variables. o The offset field provides some flexibility to callers, allowing you to target a selected section of the field in question. The most typical value for the offset field is zero (0), which means to target the copying at the beginning of the data. The maximum allowable value for the offset field is the maximum length of the SQLDATA or SQLIND buffer. 5 Errors SQLSRV_INVCOLNUM Column number not within range. SQLSRV_INVSQLDA Invalid SQLDA, SQLDA2, or SQLDA_ID. 4 sqlsrv_sqlda_set_sqllen_or_sqlsrv_sqlda2_set_sqllen 5 Overview The sqlsrv_sqlda_set_sqllen or sqlsrv_sqlda2_set_sqllen routine sets the length of a column by setting the SQLLEN field in an SQLDA or the SQLLEN and SQLOCTET_LEN in an SQLDA2. NOTE The format, parameters, description, notes, and errors for the SQLDA and SQLDA2 routine are identical unless otherwise specified. 5 C_Format extern int sqlsrv_sqlda_set_sqllen( SQLDA_ID sqldaid, short int colnum, unsigned short int len); extern int sqlsrv_sqlda2_set_sqllen( SQLDA_ID sqldaid, short int colnum, SQS_UNSIGNED_LONGWORD len, SQS_UNSIGNED_LONGWORD octet_len); 5 Parameters 6 sqldaid The identifier of a parameter marker or select list SQLDA or SQLDA2. 6 colnum A column identified by its ordinal position in a parameter or select list. 6 len The length of the SQLLEN field in an SQLDA or SQLDA2. 6 octet_len_(SQLDA2_only) Address of a variable of type SQS_UNSIGNED_LONGWORD into which the API writes the length in octets of the column. 5 Notes o Only columns of the SQLSRV_ASCII_STRING, SQLSRV_VARCHAR, and SQLSRV_VARBYTE data types can have their length changed. o An SQLSRV_INVSETLEN error code is returned if you attempt to set the SQLLEN for a column of type SQLSRV_GENERALIZED_DATE, SQLSRV_GENERALIZED_NUMBER, SQLSRV_INTERVAL, or SQLSRV_LIST_ VARBYTE. o Use the sqlsrv_sqlda_set_sqllen or sqlsrv_sqlda2_set_sqllen routine to limit the amount of data returned in a column of a select list SQLDA. For example, if only the first few bytes of a column of type SQLSRV_ASCII_STRING, SQLSRV_VARCHAR, or SQLSRV_VARBYTE are required in certain circumstances, you can reduce the size of network messages by limiting the amount of data returned by the sqlsrv_fetch routine. When processing a call to sqlsrv_fetch or sqlsrv_execute_in_out, Oracle SQL/Services sends to the server only the lengths of those columns in a select list SQLDA or SQLDA2 that have changed since the last call. o Use the sqlsrv_sqlda_set_sqllen or sqlsrv_sqlda2_set_sqllen routine to modify the length of a column of type SQLSRV_ASCII_ STRING in a parameter marker SQLDA. In this situation, Oracle Rdb truncates or pads the value as necessary to the actual length of the column as specified in the database. Oracle SQL/Services does not need to send to the server the lengths of columns that have changed in a parameter marker SQLDA or SQLDA2, because the length of each data value is sent to the server along with the data itself. o See Chapter 8 in the Guide to Using the Oracle SQL/Services Client API for more information on how Oracle SQL/Services handles values of each supported data type. o You can increase or decrease the amount of memory Oracle SQL/Services allocates for a column by calling sqlsrv_sqlda_ set_sqllen or sqlsrv_sqlda2_set_sqllen before you call sqlsrv_ allocate_sqlda_data or sqlsrv_allocate_sqlda2_data. For example, Oracle Rdb allows you to store a segment of any length into a segmented string, regardless of the segment length specified in the database. Therefore, you may need to increase the length of a column of type SQLSRV_VARBYTE before you call sqlsrv_allocate_sqlda_data or sqlsrv_allocate_sqlda2_ data to allocate the SQLDA data memory. o For the sqlsrv_sqlda2_set_sqllen routine, the octlen parameter is compared with the len parameter to see if they are compatible. For example, the SQLLEN of a column of type SQLSRV_VARCHAR or SQLSRV_VARBYTE does not include the size of the leading 32-bit count field, whereas the SQLOCTET_LEN of a column of type SQLSRV_VARCHAR or SQLSRV_VARBYTE does include the size of the leading 32-bit count field. If they are not compatible, an SQLSRV_INVSETLEN error code is returned. When using a multibyte character set, normally the SQLLEN field represents the length in characters of a column, excluding the length of any control information, whereas the SQLOCTET_LEN represents the length in bytes of the column, including the length of any control information. However, Oracle SQL/Services does not send the SQLOCTET_LEN value to the server if it is changed; therefore, you must set the SQLLEN to the new length in bytes of the column, excluding the length of any control information. 5 Errors SQLSRV_INVCOLNUM Column number not within range. SQLSRV_INVSQLDA Invalid SQLDA, SQLDA2, or SQLDA_ID. SQLSRV_INVDATTYP Invalid data type. SQLSRV_INVSETLEN Unsupported data type or invalid SQLLEN and SQLOCTET_LEN combination. SQLSRV_INVSQLLEN The SQLLEN field in the SQLDA or SQLDA2 has been set to 0 or to a value greater than the size of the column. 4 sqlsrv_sqlda2_char_set_info 5 Overview The sqlsrv_sqlda2_char_set_info routine returns the SQL character set fields from the SQLDA2. 5 C_Format extern int sqlsrv_sqlda2_char_set_info( SQLDA_ID sqldaid, short int colnum, CHARPTR name, short int name_len, CHARPTR schema, short int schema_len, CHARPTR catalog, short int catalog_len); 5 Parameters 6 sqldaid The identifier of a parameter marker or select list SQLDA or SQLDA2. 6 colnum A column identified by its ordinal position in a parameter or select list. 6 name Address of a buffer of type unsigned char into which the API writes the character set name. 6 name_len The length of the buffer specified by the name argument into which the API writes the character set name. 6 schema Address of a buffer of type unsigned char into which the API writes the schema name. 6 schema_len The length of the buffer specified by the schema argument into which the API writes the schema name. 6 catalog Address of a buffer of type unsigned char into which the API writes the catalog name. 6 catalog_len The length of the buffer specified by the catalog argument into which the API writes the catalog name. 5 Notes o Oracle SQL/Services returns an error if the SQLDA or SQLDA2 is invalid or if the column number is greater than the number of parameter markers or select list items (colnum >= sqlda.SQLD). o The maximum length of a character set name, schema name, or catalog name is 128 bytes. If a user-supplied buffer is smaller than the actual name, the name is truncated. If a user-supplied buffer is larger than the actual name, the name is padded with spaces. 5 Errors SQLSRV_INVSQLDA Invalid SQLDA, SQLDA2, or SQLDA_ID. SQLSRV_INVCOLNUM Column number not within range. 2 Error_Message_Codes The following are SQL/Services error message codes: 3 -2000,SQLSRV_INVARG Explanation: Invalid routine parameter. User Action: Examine all routine parameters and retry with corrected value(s). 3 -2001,SQLSRV_INVBUFSIZ Explanation: Invalid read or write buffer size. User Action: Correct the value(s) for the read or write buffer size(s). 3 -2003,SQLSRV_NETERR Explanation: Network error. User Action: Find the DECnet, TCP/IP, SQL*Net, or NetWare error file (specific to your platform) and look up the error code to determine a course of action. 3 -2005,SQLSRV_INVASC Explanation: Invalid association identifier. The routine parameter for the association identifier is invalid User Action: Correct the problem and retry the routine call. 3 -2006,SQLSRV_INVSQLDA Explanation: Invalid SQLDA or SQLDA_ID. User Action: Examine the SQLDA or SQLDA_ID parameter passed to the routine and correct it. 3 -2007,SQLSRV_PRSERR Explanation: Parsing error on the protocol message. Internal error. User Action: Contact your Oracle Corporation support representative for assistance. 3 -2008,SQLSRV_INVSTMID Explanation: Invalid statement identifier. User Action: Respecify a statement identifier that references a previously prepared statement. 3 -2009,SQLSRV_INVCURNAM Explanation: Invalid cursor name. A nonexistent cursor name was specified. User Action: Specify a valid cursor name. 3 -2011,SQLSRV_INTERR Explanation: Internal error. User Action: Contact your Oracle Corporation support representative for assistance. 3 -2012,SQLSRV_OPNLOGFIL Explanation: Login was specified, but the log file could not be opened. User Action: Evaluate the platform-specific reasons as to why a log file could not be opened, such as security reasons, disk space availability, and so forth. 3 -2013,SQLSRV_NO_MEM Explanation: API memory allocation failed. User Action: Release memory on your client system before running Oracle SQL/Services. 3 -2014,SQLSRV_INVSQLCA Explanation: Invalid routine parameter. User Action: Examine all routine parameters and retry with corrected value(s). 3 -2015,SQLSRV_SQLDA_NOTALL Explanation: Attempt to deallocate static memory. User Action: Call sqlsrv_free-sqlda_data or sqlsrv_free-sqlda2_ data with an SQLDA_ID whose memory was created by sqlsrv_ allocate_sqlda_data or sqlsrv_allocate_sqlda2_data. 3 -2016,SQLSRV_MULTI_ACT Explanation: A batched sqlsrv_execute, sqlsrv_execute_in_out, or sqlsrv_fetch_many context is active. User Action: Call sqlsrv_close_cursor, sqlsrv_execute, or sqlsrv_ execute_in_out with the execute_flag = 0 or 3. 3 -2019,SQLSRV_INVEXEFLG Explanation: Invalid execute flag. User Action: Respecify the execute flag on either the sqlsrv_execute or sqlsrv_execute_in_ out call. 3 -2021,SQLSRV_INVASCSTR Explanation: Invalid parameter in ASSOCIATE_STR. User Action: Examine and fix the ASSOCIATE_STR structure. 3 -2025,SQLSRV_DUPCRSNAM Explanation: Duplicate cursor name. User Action: Respecify a correct cursor name. 3 -2026,SQLSRV_INVCOLNUM Explanation: Column number is not within range. User Action: Examine all routine parameters and retry with corrected value(s). 3 -2027,SQLSRV_INVDATTYP Explanation: Invalid data type. User Action: Specify a correct data type. 3 -2028,SQLSRV_INCDATTYP Explanation: Incompatible data type with column. User Action: Examine all routine parameters and retry with corrected value(s). 3 -2029,SQLSRV_USRDATALL Explanation: The user, not Oracle SQL/Services, has allocated data buffers. User Action: Call sqlsrv_allocate_sqlda_data or sqlsrv_allocate_ sqlda2_data or sqlsrv_free_sqlda_data or sqlsrv_free_sqlda2_data with an SQLDA_ID that does not contain user allocated data. 3 -2030,SQLSRV_ACTSTM Explanation: The statement id already has an active cursor. User Action: Close the cursor or prepare the statement again. 3 -2031,SQLSRV_APINOTSUP Explanation: API not supported. An Oracle SQL/Services client is trying to access server information that is not supported on the client. User Action: Check the version of the client software that you are using. Upgrade your client software to match the version of the server to gain support for the requested operation. 3 -2032,SQLSRV_INV_CLS Explanation: Invalid service name specified. User Action: Specify a service name in the CLASS_NAME field in the association structure that matches one of the service names in the server configuration file (check with your server system manager). 3 -2033,SQLSRV_NO_PRCAVL Explanation: No process is available. User Action: The maximum number of servers has been exceeded on the server system. Try another time, or consult with your server system manager to raise the MAX parameter(s) in the server configuration file. 3 -2034,SQLSRV_GETACCINF Explanation: The dispatcher was unable to obtain the appropriate account information to authenticate an associating client. User Action: Consult with your server system manager to examine the log files for more information. 3 -2035,SQLSRV_EXEINTERR Explanation: The executor has encountered an internal error. User Action: Examine any executor log files and correct the problem with the executor, if possible. If not, contact your Oracle support representative for assistance. 3 -2036,SQLSRV_HOSTERR Explanation: An error occurred while accessing the hosts file for the TCP/IP transport. Either a match was not found for the requested node name, or the host file does not exist, or cannot be read. User Action: Examine your platform-specific documentation for information about the location and format of the hosts file. 3 -2037,SQLSRV_XPT_MISSING Explanation: A valid transport has been selected, but the code is disabled. For example, this can occur on DOS systems when you link an application with a particular transport disabled. User Action: Examine MAKE or linking procedures to ensure that the requested transport code is enabled. 3 -2038,SQLSRV_NO_SYSFLDR Explanation: This error is valid only for Macintosh applications. An error has occurred while trying to open the Oracle SQL/Services Control Panel device in the System Folder. User Action: Examine the Macintosh environment for accessibility to the Oracle SQL/Services Control Panel device in the System Folder. 3 -2039,SQLSRV_NO_RSRC Explanation: This error is valid only for Macintosh applications. An error has occurred while trying to open the Oracle SQL/Services Control Panel device resource. User Action: Ensure that the Oracle SQL/Services Control Panel device is installed and accessible in the System Folder. 3 -2040,SQLSRV_NO_CONNREC Explanation: This error is valid only for Macintosh applications. An error has occurred while trying to get a connection record from the Communications Toolbox. This is an internal error. User Action: In some cases, rebooting the Macintosh or turning off or on the network may resolve the problem. 3 -2041,SQLSRV_PARTIAL_XFR Explanation: This error is valid only for Macintosh applications. A partial write has occurred while trying to write a message to the server. This is an internal error. User Action: In some cases, adjusting network parameters may resolve the problem. 3 -2042,SQLSRV_SRVNOTSUP Explanation: Server not supported. An Oracle SQL/Services client is requesting an operation that is not supported by the version of the server with which it is connected. User Action: Check the version of the server to which your Oracle SQL/Services client is attached. Upgrade your server software and possibly your Oracle Rdb software to gain support for the requested operation. 3 -2043,SQLSRV_INVSETLEN Explanation: 1. A length may not be specified for the following column data types: o SQLSRV_LIST_VARBYTE o SQLSRV_GENERALIZED_NUMBER o SQLSRV_GENERALIZED_DATE o SQLSRV_INTERVAL 2. The SQLOCTET_LEN value does not correspond with the SQLLEN value: o SQLSRV_ASCII_STRING The SQLOCTET_LEN value must equal SQLLEN value or be an exact multiple of the SQLLEN value if using a multi-octet character set. o SQLSRV_VARCHAR and SQLSRV_VARBYTE The SQLOCTET_LEN value must include the leading count field overhead, which is 4 octets or bytes. User Action: Specify a valid SQLLEN value or valid SQLLEN and SQLOCTET_LEN values. 3 -2044,SQLSRV_INVSQLLEN Explanation: The SQLLEN field in the SQLDA or SQLDA2 has been set to a value greater than the size of the column. User Action: Set the SQLLEN to a valid value. 3 -2045,SQLSRV_DLL_LOAD_ERR Explanation: This error is valid only for Windows applications. An error has been returned from the MS Windows LoadLibrary call. User Action: Action may vary depending on the network transport: (TCP/IP) Ensure that the TCP/IP DLL (winsock.dll, wsock32.dll) is in the search PATH. (DECnet) 32-bit applications using Windows 95 require pwsock32.dll in the search PATH. PATHWORKS for Windows 95 must be installed. (DECnet) DECnet 32-bit applications using Windows NT require DNETW.DLL in the search PATH. PATHWORKS for Windows NT must be installed. (SQL*Net) Ensure that you have all the required SQL*Net DLL files. 3 -2046,SQLSRV_DLL_ADDR_ERR Explanation: This error is valid only for Windows applications. An error has been returned from the MS Windows GetProcAddress call. (TCP/IP) The expected routines in winsock.dll or wsock32.dll are not available. (DECnet) The expected routines in pwsock32.dll or dnetw.dll are not available. (SQL*Net) The expected routines in the required SQL*Net DLL files are not available. User Action: (TCP/IP) Install a winsock compatible version of TCP/IP. (DECnet) Install PATHWORKS for Windows NT or PATHWORKS for Windows 95. (SQL*Net) Install the version of SQL*Net required by Oracle SQL/Services. 3 -2048,SQLSRV_INVSELIST Explanation: Invalid SQLDA Select list. User Action: Examine the SQLDA select list parameter passed to sqlsrv_prepare. If you are calling sqlsrv_execute, select list was detected with the statement identifier passed to sqlsrv_ execute. The sqlsrv_execute statement identifier should never contain a select list SQLDA. If you are calling sqlsrv_execute_ in_out, the statement you are executing does not have any output data, therefore it should not have a select list SQLDA. 3 -2049,SQLSRV_PWD_EXPIRED Explanation: Password Expired. User Action: Change your password. 3 -2050,SQLSRV_CONNTIMEOUT Explanation: The server created a connect context for a client, but it did not complete connect processing within the server specified interval. User Action: None 3 -2051,SQLSRV_SVCNOTRUN Explanation: The requested service is not running (i.e., this service has not been started). User Action: Start this service. 3 -2052,SQLSRV_SVC_SHUTDOWN Explanation: The service was shut down typically by system management. User Action: Ask system management why the service is shut down. 3 -2053,SQLSRV_TOOMANYCONNECTS Explanation: A connect arrived at the dispatcher when the maximum number of connects was at the maximum level. User Action: Request system management to increase the maximum number of connects. 3 -2054,SQLSRV_SQLNET_BADINIT Explanation: Unable to initialize SQL*Net. User Action: Make sure that the SQL*Net configuration files have correct parameters. On Windows systems, try exiting Windows and rerunning the application program. 3 -2055,SQLSRV_SQLNET_BADSERVICE Explanation: SQL*Net is unable to resolve the service name being specified. User Action: Verify that the service name exists in the tnsnames.ora file or in the Oracle Names Server. 3 -2056,SQLSRV_SQLNET_BADCONNECT Explanation: SQL*Net is unable to connect to the server. User Action: Verify that the server is available for accepting a connection. 3 -2057,SQLSRV_FTCMNYACT Explanation: sqlsrv_fetch_many is already active for this cursor. User Action: Call sqlsrv_fetch until the requested number of rows have been received or call sqlsrv_close_cursor to cancel fetch-many mode. 3 -2058,SQLSRV_DATA_TOO_LONG Explanation: The Oracle SQL/Services executor determined that the length of a data value in an SQLDA or SQLDA2 exceeded the maximum allowed for the value's data type. User Action: Modify the client application to supply a value of the correct length. 3 -2500,SQLSRV_MAXERR Explanation: Internal error. Top-level error reserved for Oracle. User Action: Use this error to check for a 'valid' error (an error within the range of Oracle SQL/Services errors). For error values greater than this value, you can assume that an internal error has occurred. Contact your Oracle Corporation support representative for assistance.