Library Product

Oracle Rdb7^(tm)

Guide to Using the
Oracle SQL/Services^(tm)
Client API

Release 7.0

Part No. A41981-1

Corporate Copyright Notice

Copyright 1991, 1996 Oracle Corporation.

All rights reserved.

IMPORTANT - READ CAREFULLY BEFORE VIEWING AND/OR USING THIS DOCUMENTATION IN ANY WAY. NO PART OF THIS DOCUMENTATION MAY BE REPRODUCED OR TRANSMITTED IN ANY FORM OR BY ANY MEANS, ELECTRONIC OR MECHANICAL, FOR ANY PURPOSE, WITHOUT THE EXPRESS WRITTEN PERMISSION OF ORACLE CORPORATION.

This software contains proprietary information of Oracle Corporation; it is provided under a license agreement containing restrictions on use and disclosure and is also protected by copyright law. Reverse engineering of the software is prohibited.

The information contained in this document is subject to change without notice. If you find any problems in the documentation, please report them to us in writing. Oracle Corporation does not warrant that this document is error free.

Restricted Rights Legend Programs delivered subject to the DOD FAR Supplement are 'commercial computer software' and use, duplication and disclosure of the programs shall be subject to the licensing restrictions set forth in the applicable Oracle license agreement. Otherwise, programs delivered subject to the Federal Acquisition Regulations are 'restricted computer software' and use, duplication and disclosure of the programs shall be subject to the restrictions in FAR 52.227-14, Rights in Data---General, including Alternate III (June 1987). Oracle Corporation, 500 Oracle Parkway, Redwood City, CA 94065.

The programs are not intended for use in any nuclear, aviation, mass transit, medical, or other inherently dangerous applications. It shall be the licensee's responsibility to take all appropriate fail-safe, back up, redundancy and other measures to ensure the safe use of such applications if the programs are used for such purposes, and Oracle disclaims liability for any damages caused by such use of the programs.

Oracle, Secure Network Services, and SQL*Net are registered trademarks of Oracle Corporation, Redwood City, California. Rdb7, Oracle Rdb, Oracle Trace, and Oracle SQL/Services are trademarks of Oracle Corporation, Redwood City, California.

All other company or product names are used for identification purposes only, and may be trademarks of their respective owners.

Send Us Your Comments

Oracle Corporation welcomes your comments and suggestions on the quality and usefulness of this publication. Your input is an important part of the information used for revision.

You can send comments to us in the following ways:

• Electronic mail --- nedc_doc@us.oracle.com
• FAX --- 603-897-3334 Attn:Oracle Rdb Documentation
• Postal service

  Oracle Corporation 
  Oracle Rdb Documentation 
  One Oracle Drive
  Nashua, NH  03062
  USA 
  

If you like, you can use the following questionnaire to give us feedback. (Edit the online release notes file, extract a copy of this questionnaire, and send it to us.)

• Did you find any errors?
• Is the information clearly presented?
• Do you need more information? If so, where?
• Are the examples correct? Do you need more examples?
• What features did you like most about this manual?

If you find any errors or have any other suggestions for improvement, please indicate the chapter, section, and page number (if available).

Oracle Rdb^tm is a general-purpose database management system based on the relational data model.

Oracle SQL/Services^tm, a client/server component of Oracle Rdb, enables a client application program invoked on a client computer running on a supported operating system or transport, to access Oracle Rdb databases and other databases supported by SQL on a Digital UNIX or OpenVMS server system. See the overview chapter for a complete list of supported clients.

This manual describes how to develop Oracle SQL/Services client application programs.

Intended Audience

This manual is written primarily for experienced applications programmers; however, some sections are intended for the system manager responsible for maintaining and fine-tuning . Both programmers and system managers should read Chapter 1 for a recommended approach to the material in this guide and a discussion of the pertinent sections. In addition, system managers should refer to the Oracle SQL/Services Installation Guide, which provides information important to the installation of an Oracle SQL/Services system, and to the Oracle SQL/Services Server Configuration Guide, which provides information important to the configuration and maintenance of an Oracle SQL/Services system.

Operating System Information

You can find information about the versions of the operating system and optional software that are compatible with this release of Oracle Rdb and Oracle SQL/Services in the Oracle Rdb7 Installation and Configuration Guide and the Oracle SQL/Services Installation Guide, and also in the Oracle Rdb7 Release Notes and the Oracle SQL/Services Release Notes.

Contact your Oracle® Corporation representative if you have other questions about compatibility.

Structure

This manual contains the following chapters and appendix.

Chapter 1	Introduces . Provides a reading path for programmers and system managers.
Chapter 2	Provides a condensed discussion of dynamic SQL, API routines, data structures, recommendations for API development, and API application linking.
Chapter 3	Provides guidelines for application development using the sample application.
Chapter 4	Explains how to enhance application performance.
Chapter 5	Describes execution logging and how to use it for debugging and monitoring application performance.
Chapter 6	Presents detailed reference descriptions of the API routines.
Chapter 7	Presents detailed reference descriptions of the data structures.
Chapter 8	Describes the data types used in .
Appendix A	Lists and describes the deprecated features for Oracle SQL/Services V4.1 and higher.

Related Manuals

For more information, see the other manuals in this documentation set, especially the following:

• Oracle Rdb7 Guide to SQL Programming
• Oracle Rdb7 SQL Reference Manual
• Oracle Rdb7 Release Notes
• Oracle SQL/Services Release Notes
• Oracle Rdb7 Installation and Configuration Guide
• Oracle SQL/Services Installation Guide
• Oracle SQL/Services Server Configuration Guide

The Oracle SQL/Services Release Notes and the Oracle Rdb7 Release Notes are provided only as part of the software kit. PostScript and .TXT source files for these release notes are available in SYS$HELP on OpenVMS systems and in /usr/lib/dbs/sqlsrv/v70/doc on Digital UNIX systems.

Conventions

In this manual, Oracle Rdb refers to Oracle Rdb for OpenVMS and software. Release 7.0 of Oracle Rdb software is often referred to as V7.0.

The SQL interface to Oracle Rdb is referred to as SQL. This interface is the Oracle Rdb implementation of the SQL standard ANSI X3.135-1992, ISO 9075:1992, commonly referred to as the ANSI/ISO SQL standard or SQL92.

Oracle ODBC Driver for Rdb software is referred to as the ODBC driver.

OpenVMS means both the OpenVMS Alpha and the OpenVMS VAX operating systems.

The following conventions are also used in this manual:

. . .	Vertical ellipsis points in an example mean that information not directly related to the example has been omitted.
[ ]	Brackets enclose optional clauses from which you can choose one or none.
$	The dollar sign represents the DIGITAL Command Language prompt in OpenVMS and the Bourne shell prompt in Digital UNIX.
%	The percent sign represents the Digital UNIX default user prompt.
boldface text	Boldface type in text indicates a term defined in the text.
e, f, t	Index entries in the printed manual may have a lowercase e, f, or t following the page number; the e, f, or t is a reference to the example, figure, or table, respectively, on that page.

Terminology

Some Oracle SQL/Services terminology in this manual has changed effective with release 7.0 of Oracle SQL/Services. The revised terminology reflects changes in the current server architecture compared to the original Oracle SQL/Services architecture, and makes terminology consistent on Digital UNIX and OpenVMS platforms.

• The term dispatcher replaces all instances of the phrase communications server.
• The term executor or executors replaces all instances of the phrase execute server process or execute server processes.
• The term service replaces all instances of the term class.
• The term universal replaces all instances of the term generic when referring to a service type. For example, the phrase session reusable generic service becomes session reusable universal service and generic service becomes universal service.

These terminology changes are made throughout this manual.

This section lists some of the new and changed features described in this manual since it was last revised with Version 6.1. The Oracle SQL/Services Release Notes and Oracle Rdb7 Release Notes provide information on all the new features and technical changes included in release 7.0. The major new features described in this manual include the following:

• New server on OpenVMS systems with a server system management command line interface to manage the server components from OpenVMS and Digital UNIX server systems and an Oracle SQL/Services Manager graphical user interface (GUI) to manage server components from Windows clients. See the Oracle SQL/Services Server Configuration Guide and the Oracle SQL/Services Installation Guide for more information.
• Support for SQL*Net® as a network transport type.
  To use the SQL*Net network transport, you must specify the SQLSRV_XPT_SQLNET argument in the xpttyp field in the associate structure, and you must specify the node_name parameter of the sqlsrv_associate routine as either the SQL*Net Service Name or the SQL*Net Alias.
• Oracle SQL/Services V7.0 is now truly multiversioned on OpenVMS.
  Beginning with Oracle SQL/Services V7.0 on OpenVMS, you can run multiple versions of Oracle SQL/Services server on the same node (V6.0 or V6.1 and V7.0). The Oracle SQL/Services V7.0 client API allows you to specify alternate network ports to enable you to select to which version of a server to connect.
• Support for the Windows 95 client API and the Oracle ODBC Driver for Rdb for the Windows 95 operating system.
• Support for the Solaris client API for the Solaris operating system.
• The MS--DOS large memory model client API is deprecated for Oracle SQL/Services V7.0 and is frozen at the Oracle SQL/Services V6.1 level.
• The ULTRIX for RISC client API is deprecated for Oracle SQL/Services V7.0 and is frozen at the Oracle SQL/Services V6.1 level.
• The SunOS client API is deprecated for Oracle SQL/Services V7.0 and is frozen at the Oracle SQL/Services V6.1 level.
• info_type parameter value SQLSRV_INFO_DB_CLASS of the sqlsrv_get_associate_info routine is deprecated in Oracle SQL/Services V7.0. This parameter value will continue to work for Oracle SQL/Services V7.0; however, Oracle Corporation recommends for V7.0 that you use the new info_type parameter value SQLSRV_INFO_SERVICE_ATTRS. See sqlsrv_get_associate_info for more information.
• info_type parameter value SQLSRV_INFO_SERVICE_ATTRS of the sqlsrv_get_associate_info routine is new in Oracle SQL/Services V7.0. This parameter value replaces the info_type parameter value SQLSRV_INFO_DB_CLASS that is deprecated in Oracle SQL/Services V7.0. See sqlsrv_get_associate_info for more information.
• Support for 32,000-byte buffer sizes.
  The maximum supported buffer size is 32,000 bytes for the read_buffer_size and write_buffer_size parameters in the sqlsrv_associate routine for all transports and platform combinations except NetWare on Windows. Clients negotiate with the V7.0 server for the actual supported maximum buffer size. See sqlsrv_associate for more information.
• A new value, SQLSRV_INFO_BUFFER_SIZE, of the info_type argument of the sqlsrv_get_associate_info routine.
  The value SQLSRV_INFO_BUFFER_SIZE is a new value of the info_type argument of the sqlsrv_get_associate_info routine. This value gets the negotiated buffer size and returns the information as a longword.
• Three ASSOCIATE_STR fields added in V6.1 for internal use only are now available for general use.
  The attach, declare, and appnam fields of the ASSOCIATE_STR can now be used by customers' applications. See Section 7.2 for more information.
• Two new client log field values: SQLSRV_LOG_FLUSH and SQLSRV_LOG_BINARY.
  The SQLSRV_LOG_FLUSH value, when set, flushes pending output to the log file only at the end of each complete association-level, routine-level, and protocol-level log entry and is useful if a client application is terminating abnormally while executing application code.
  The SQLSRV_LOG_BINARY value, when set, dumps memory in structured format if the data contains nonprintable characters.
  See Section 5.1 for more information.
• sqlsrv_execute routine is deprecated in V7.0.
  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.

Technical changes have been made where necessary to provide technical clarifications, to fix errors of omission, and to make corrections.

Library Product

Copyright ©1996, Oracle Corporation All rights reserved.