#EDIR DATA#
DOCTYPE='BOOK' PUBLICID='-//SYBOOKS//Default DTD//EN' SYSTEMID=''DOCTYPE='book' PUBLICID='' SYSTEMID=''Open Clientname='trade' font='symbol' code='228'  charset='fontspecific' DB-Library/C Reference Manual Open Clientname='trade' font='symbol' code='228'  charset='fontspecific' DB-Library/C Reference ManualREMAP="titleBO--Body"Open Client Release 10.0REMAP="titleBO--Body"Document ID: 32600-00-1000-04REMAP="titleBO--Body"Change Level: 2REMAP="titleBO--Body"Last Revised: May 15, 1994Principal authorship: Pegler SwiftContributing authorship: Steve Goodman, Mike AllenDocument ID: 32600-00-1000REMAP="discBO--Body"This publication pertains to Open Client Release 10.0 of the SYBASE database management software and to any subsequent release until otherwise indicated in new editions or technical notes. Information in this document is subject to change without notice. The software described herein is furnished under a license agreement, and it may be used or copied only in accordance with the terms of the agreement.Document OrdersREMAP="discBO--Body"Customers may purchase additional copies of any document or the right to make photocopies of documentation for their in-house use.REMAP="discBO--Body"To order additional documents or photocopy rights, U.S. and Canadian customers should call Customer Fulfillment at (800) 685-8225, fax (617) 229-9845.REMAP="discBO--Body"Customers in other countries with a U.S. license agreement may contact Customer Fulfillment via the fax number. All other international customers should contact their Sybase subsidiary or local distributor.REMAP="discBO--Body"Upgrades are provided only at regularly scheduled software release dates.REMAP="discBO--Body"© Copyright Sybase, Inc., 1989, 1994. All rights reserved.REMAP="discBO--Body"No part of this publication may be reproduced, transmitted, or translated in any form or by any means, electronic, mechanical, manual, optical or otherwise, without prior written permission of Sybase, Inc.REMAP="discBO--Body"Sybase TrademarksREMAP="discBO--Body"SYBASE, the SYBASE logo, SyBooks, APT-FORMS, Data Workbench, DBA Companion, Deft, GainExposure, GainInsight, GainMomentum, SA Companion, SQL Debug, SQL Solutions, SQR, Transact-SQL, and VQL are registered trademarks of Sybase, Inc. Adaptable Windowing Environment, ADA Workbench, Application Manager, Applications from Models, APT-Build, APT-Edit, APT-Execute, APT-Library, APT-Translator, APT Workbench, Build Momentum, Camelot, Client/Server Architecture for the Online Enterprise, Client/Server for the Real World, Configurator, Database Analyzer, DBA Companion Application Manager, DBA Companion Resource Manager, DB-Library, Deft Analyst, Deft Designer, Deft Educational, Deft Professional, Deft Trial, Developers Workbench, Easy SQR, Embedded SQL, Enterprise Builder, Enterprise Client/Server, Enterprise Meta Server, Enterprise Modeler, Enterprise Momentum, Gain, Insight, MAP, Maintenance Express, MethodSet, Movedb, Navigation Server, Net-Gateway, Net-Library, Object Momentum, OmniSQL Access Module, OmniSQL Gateway, OmniSQL Server, Open Client, Open Client/Server Interfaces, Open Gateway, Open Server, Open Solutions, Partnerships That Work, PC APT-Execute, PC DB-Net, PC Net Library, PostDoc, Replication Server, Replication Server Manager, Report-Execute, Report Workbench, Resource Manager, RW-Display Lib, RW-Library, Secure SQL Server, Secure SQL Toolset, SQL Code Checker, SQL Edit, SQL Edit/TPU, SQL Monitor, SQL Server, SQL Server/CFT, SQL Server/DBM, SQL Station, SQL Toolset, SQR Developers Kit, SQR Execute, SQR Toolset, SQR Workbench, SYBASE Client/Server Interfaces, SYBASE Gateways, Sybase Momentum, SYBASE SQL Lifecycle, Sybase Synergy Program, SYBASE Virtual Server Architecture, SYBASE User Workbench, System 10, Tabular Data Stream, The Enterprise Client/Server Company, and The Online Information Center are trademarks of Sybase, Inc.REMAP="discBO--Body"All other company and product names used herein may be the trademarks or registered trademarks of their respective companies.Restricted Rights LegendREMAP="discBO--Body"Use, duplication or disclosure by the Government is subject to restrictions set forth in subparagraph (c)(1)(ii) of DFARS 52.227-7013 for the DOD and as set forth in FAR 52.227-19(a)-(d) for civilian agencies.REMAP="discBO--Body"Sybase, Inc., 6475 Christie Avenue, Emeryville, CA 94608REMAP="discBO--Body"PrefaceREMAP="BO--Body"This document, the Open Client DB-Library/C Reference Manual, contains reference information for the C version of Open Client DB-Libraryname='trade' font='symbol' code='228'  charset='fontspecific'.RENDERAS="SECT1"AudienceREMAP="BO--Body"The DB-Library Reference Manual is designed to serve as a reference manual for programmers who are writing DB-Library applications. It is written for application programmers familiar with the C programming language.RENDERAS="SECT1"How to Use This BookREMAP="BO--Body"When writing a DB-Library application, use the DB-Library Reference Manual as a source of reference information.REMAP="BO--Body"LINKEND="X69705"Chapter 1,  "Introducing DB-Library,"
 contains a brief introduction to DB-Library. REMAP="BO--Body"LINKEND="X29517"Chapter 2,  "Routines,"
 contains specific information about each DB-Library routine, such as what parameters the routine takes and what it returns.REMAP="BO--Body"LINKEND="X40433"Chapter 3,  "Bulk Copy,"
 contains an introduction to bulk copy and specific information about each bulk copy routine.REMAP="BO--Body"LINKEND="X74178"Chapter 4,  "Two-Phase Commit Service,"
 contains a brief description of two-phase commit service and specific information about each two-phase commit service routine.RENDERAS="SECT1"Related DocumentsREMAP="BO--Body"The Open Client/Server Installation Guide explains how to install DB-Library. REMAP="BO--Body"The Open Client/Server Supplement contains platform-specific material for Open Client/Server products. This document includes information about:MARK="BULL" REMAP="BU--Bullet"Open Client compatibility with pre-10.0 server releasesThe interfaces fileCompiling and linking an applicationThe example programs that are included on-line with Open Client/Server productsRoutines that have platform-specific behaviorsLocalizationRENDERAS="SECT2"Other Sources of InformationREMAP="BO--Body"SYBASE® documents include a wide range of user guides and reference manuals which describe all aspects of the SYBASE relational database management system. Because application development can draw on a number of different parts of the SYBASE system, you may encounter most of the SYBASE document set at some time or another. A few manuals, however, will prove to be particularly useful: MARK="BULL" REMAP="BU--Bullet"The SQL Server Reference Manual describes the Transact-SQL® database language, which an application uses to create and manipulate SYBASE SQL Servername='trade' font='symbol' code='228'  charset='fontspecific' database objects. The Open Client Client-Library Reference Manual describes Client-Libraryname='trade' font='symbol' code='228'  charset='fontspecific'. Like DB-Library, Client-Library is a collection of routines for use in writing client applications.The Open Server Server-Library Reference Manual contains reference information for Server-Library,
 a collection of routines for use in writing Open Servername='trade' font='symbol' code='228'  charset='fontspecific' applications.The APT Workbench User's Guide documents APT-Editname='trade' font='symbol' code='228'  charset='fontspecific', used to create forms and specify their processing, and APT-SQLname='trade' font='symbol' code='228'  charset='fontspecific', a fourth-generation language for developing forms-based applications. APT Workbenchname='trade' font='symbol' code='228'  charset='fontspecific' reference manuals include:MARK="DASH" REMAP="BS--BulletSub"The APT-Edit Reference Manual, which contains detailed information about the forms editorThe APT-SQL Reference Manual, which contains detailed information on the APT-SQL languageThe APT-Library/C Reference Manual, which describes the library of C routines that give an application access to APT-Edit formsThe Data Workbench User's Guide describes Data Workbench, a set of tools that provide forms-based, interactive access to SQL Server. Since Data Workbench uses the SYBASE forms run-time system, it can serve as a valuable example of how a forms-based application looks and feels. RENDERAS="SECT1"ConventionsREMAP="BO--Body"DB-Library routine syntax is shown in a bold, monospace font:REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"   DBPROCESS    *dbopen(login,
server)    LOGINREC     *login;   char         *server;REMAP="BO--Body"Program text and computer output are shown in a monospace font:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"dbproc = dbopen(login, SERVERNAME)REMAP="BO--Body"Structure names and symbolic constants are written in small capital letters:REMAP="BO--Body"     DBPROCESS, SYBCHARREMAP="BO--Body"Routine names and Transact-SQL keywords are written in a narrow, bold font:REMAP="UN--Under"MOREINFO="NONE"dbopen, the MOREINFO="NONE"select statementRENDERAS="SECT1"If You Need HelpREMAP="BO--Body"Help is available for your SYBASE software in the form of documentation, on-line help, and a Technical Support Center.RENDERAS="SECT2"On-Line HelpREMAP="BO--Body"If you have access to a 10.0 SQL Server, you can use MOREINFO="NONE"sp_syntax, a SYBASE system procedure, to retrieve the syntax of DB-Library routines. REMAP="BO--Body"For information on how to install MOREINFO="NONE"sp_syntax, see the System Administration Guide Supplement for your platform. For information on how to run MOREINFO="NONE"sp_syntax, see its manual page in Volume 2 of the SQL Server Reference Manual.RENDERAS="SECT2"Technical SupportREMAP="BO--Body"Your company has designated someone with the authority to contact Sybase Technical Support. If you cannot resolve a problem using the information in the Sybase documentation, ask that person to contact Sybase Technical Support for you.REMAP="BO--Body"NUMBER="1" ID="X69705"Introducing DB-LibraryRENDERAS="SECT1"Client/Server ArchitectureID="IN1139921"Client/serverarchitectureREMAP="BO--Body"Client/server architecture divides the work of computing between "clients" and "servers."REMAP="BO--Body"Clients make requests of servers and process the results of those requests. For example, a client application might request data from a database server. Another client application might send a request to an environmental control server to lower the temperature in a room.REMAP="BO--Body"Servers respond to requests by returning data or other information to clients, or by taking some action. For example, a database server returns tabular data and information about that data to clients, and an electronic mail server directs incoming mail toward its final destination.FLOAT="0"FORMAT="UNKNOWN" FILEREF="fig1_1.xwd"LBL="Figure 1-1: "Client/Server architectureREMAP="BO--Body"Client/server architecture has several advantages over traditional program architectures:MARK="BULL" REMAP="BU--Bullet"Application size and complexity can be significantly reduced, because common services are handled in a single location, a server. This simplifies client applications, reduces duplicate code, and makes application maintenance easier.Client/server architecture facilitates communication between varied applications. Client applications that use dissimilar communications protocols cannot communicate directly, but can communicate through a server that "speaks" both protocols.Client/server architecture enables applications to be developed with distinct components, which can be modified or replaced without affecting other parts of the application.ID="IN179922"Clientstypes of clientsRENDERAS="SECT2"Types of ClientsREMAP="BO--Body"A client is any application that makes requests of a server. Clients include:MARK="BULL" REMAP="BU--Bullet"SQL Toolset products such as APT-Edit and Data Workbench.Stand-alone utilities provided with SQL Server, such as MOREINFO="NONE"isql and MOREINFO="NONE"bcp.Applications written using Open Client libraries.ID="IN1139833"Client/serverarchitectureApplications written using Open Client Embedded SQLname='trade' font='symbol' code='228'  charset='fontspecific'.ID="IN169834"Servertypes of serversRENDERAS="SECT2"Types of ServersREMAP="BO--Body"The SYBASE product line includes servers and tools for building servers:MARK="BULL" REMAP="BU--Bullet"SYBASE SQL Server is a database server. SQL Servers manage information stored in one or more databases.SYBASE Open Server provides the tools and interfaces needed to create a custom server, also called an "Open Server application."REMAP="BO--Body"An Open Server application can be any type of server. For example, an Open Server application can perform specialized calculations, provide access to real time data, or interface with services such as electronic mail. An Open Server application is created individually, using the building blocks provided by Open Server Server-Library.REMAP="BO--Body"SQL Server and Open Server applications are similar in some ways:MARK="BULL" REMAP="BU--Bullet"SQL Server and Open Server applications are both servers, responding to client requests.Clients communicate with both SQL Server and Open Server applications through Open Client products.REMAP="BO--Body"But they also differ:MARK="BULL" REMAP="BU--Bullet"An application programmer must create an Open Server application, using Server-Library's building blocks and supplying custom code. SQL Server is complete and does not require custom code.An Open Server application can be any kind of server, and can be written to understand any language. SQL Server is a database server, and understands only Transact-SQL.An Open Server can communicate with "foreign" applications and servers that are not based on the TDS protocol, as well as SYBASE applications and servers. SQL Server can communicate directly only with SYBASE applications and servers, although SQL Server can communicate with foreign applications and servers by using an Open Server gateway application as an intermediary.REMAP="BO--Body"The following diagram illustrates some of the different capabilities of SQL Server and Open Server:FLOAT="0"FORMAT="UNKNOWN" FILEREF="fig1_2.xwd"LBL="Figure 1-2: "SQL Server and Open Server applicationsRENDERAS="SECT1"The Open Client and Open Server ProductsREMAP="BO--Body"Sybase provides two families of products to enable customers to write client and server application programs. They are:MARK="BULL" REMAP="BU--Bullet"SYBASE Open ClientSYBASE Open ServerRENDERAS="SECT2"SYBASE Open ClientREMAP="BO--Body"SYBASE Open Client provides customer applications, third-party products, and other SYBASE products with the interfaces needed to communicate with SQL Server and Open Server. REMAP="BO--Body"Open Client can be thought of as having two components: programming interfaces and network services.REMAP="BO--Body"The programming interfaces component of Open Client is made up of libraries designed for use in writing client applications: Client-Library, DB-Library, and CS-Library. (Both Open Client and Open Server include CS-Library, which contains utility routines that are useful to both client and server applications.)REMAP="BO--Body"Open Client network services include Net-Library, which provides support for specific network protocols, such as TCP/IP or DECnet.RENDERAS="SECT2"SYBASE Open ServerREMAP="BO--Body"SYBASE Open Server provides the tools and interfaces needed to create custom server applications.REMAP="BO--Body"Like Open Client, Open Server has a programming interfaces component and a network services component.REMAP="BO--Body"The programming interfaces component of Open Server contains Server-Library and CS-Library. (Both Open Client and Open Server include CS-Library, which contains utility routines that are useful to both client and server applications.)REMAP="BO--Body"Open Server network services are generally transparent.RENDERAS="SECT2"The Open Client LibrariesREMAP="BO--Body"The libraries that make up Open Client are:ID="IN1109835"DB-LibraryMARK="BULL" REMAP="BU--Bullet"DB-Library, a collection of routines for use in writing client applications. DB-Library includes a bulk copy library and the two-phase commit special library.ID="IN1149836"Client-Librarydefinition ofClient-Library, a collection of routines for use in writing client applications. Client-Library is a new library, designed to accommodate cursors and other advanced features in the SYBASE 10.0 product line.ID="IN1109837"CS-Librarydefinition ofCS-Library, a collection of utility routines that are useful to both client and server applications. All Client-Library applications will include at least one call to CS-Library, because Client-Library routines use a structure which is allocated in CS-Library.RENDERAS="SECT2"What Is in DB-Library?REMAP="BO--Body"DB-Library/C includes C routines and macros that allow an application to interact with SYBASE SQL Server and SYBASE Open Server applications. REMAP="BO--Body"It includes routines that send commands to SQL Server and Open Server applications and others that process the results of those commands. Other routines handle error conditions, perform data conversion, and provide a variety of information about the application's interaction with a server. REMAP="BO--Body"DB-Library/C also contains several header files that define structures and values used by the routines. Versions of DB-Library have been developed for a number of languages besides C, including COBOL, FORTRAN, Ada, and Pascal. ID="IN1129838"Embedded SQLcomparing Client-Library toRENDERAS="SECT2"Comparing the Library Approach to Embedded SQLREMAP="BO--Body"Either an Open Client library application or an Embedded SQL application can be used to send SQL commands to SQL Server.REMAP="BO--Body"An Embedded SQL application includes SQL commands in-line. The host language precompiler processes the commands into calls to Open Client libraries. All SYBASE 10.0 precompilers use a run-time library composed solely of documented Client-Library and CS-Library calls.REMAP="BO--Body"In a sense, then, the precompiler transforms an Embedded SQL application into an Open Client library application.REMAP="BO--Body"An Open Client library application sends SQL commands through library routines, and does not require a precompiler.REMAP="BO--Body"Generally, an Embedded SQL application is easier to write and debug, but a library application can take fuller advantage of the flexibility and power of Open Client routines.RENDERAS="SECT2"Other SYBASE Development Tools   REMAP="BO--Body"SYBASE provides a complete development environment. In addition to control over server and database access through DB-Library/C, SYBASE offers optional tools for creating forms-based, event-driven applications. These tools are APT-Editname='trade' font='symbol' code='228'  charset='fontspecific' and the APT-Library/Cname='trade' font='symbol' code='228'  charset='fontspecific' set of routines. APT-Edit is an editor for creating forms and specifying event-driven processing. APT-Library/C is a set of C routines that support forms-based, event-driven processing. Just as DB-Library/C routines provide an application with access to servers and database objects, APT-Library/C routines provide access to a form and its objects. A forms-based application typically contains both APT-Library/C and DB-Library/C routines. For more information, see the APT Workbench User's Guide.RENDERAS="SECT1"Communicating with a Server   ID="IN1199569"DBPROCESS structure
ID="IN1694710"Servercommunicating withREMAP="BO--Body"A DB-Library/C application communicates with a server through one or more DBPROCESS structures. Through the DBPROCESS, commands are sent to the server and query results are returned to the application. One of the first routines an application typically calls is MOREINFO="NONE"dbopen, which logs the application into the server and allocates and initializes a DBPROCESS. This DBPROCESS then serves as a connection between the application and the server. Most DB-Library/C routines require a DBPROCESS as the first parameter. ID="IN11992911"DBPROCESS structuremultiple
ID="IN1792912"ServersmultipleREMAP="BO--Body"An application can have multiple open DBPROCESSes, connected to one or more servers. For instance, an application that has to perform database updates in the midst of processing the results of a query needs a separate DBPROCESS for each task. As another example, to select data from one server and update a database on another server, an application needs two DBPROCESSes-one for each server. Each DBPROCESS in an application functions independently of any other DBPROCESS. ID="IN11592913"Command buffers
ID="IN121901114"Transact-SQL commandsTransact-SQL commandsand DBPROCESSDBPROCESS
ID="IN17871415"Buffersrow. See Row buffers.
ID="IN17841716"Bufferscommand. See Command buffers.REMAP="BO--Body"The DBPROCESS structure points to a command buffer that contains language commands for transmission to the server. It also points to result rows returned from the server-either single rows or buffers of rows if buffering has been specified. In addition, it points to a message buffer that contains error and informational messages returned from the server. REMAP="BO--Body"The DBPROCESS also contains a wealth of information on various aspects of server interaction. Many of the DB-Library/C routines deal with extracting information from the DBPROCESS. Applications should access and manipulate components of the DBPROCESS structure only through DB-Library/C routines, and not directly. ID="IN118821917"LOGINREC structure
ID="IN137782318"Login record. See LOGINREC structure.REMAP="BO--Body"One other important structure is the LOGINREC. It contains typical login information, such as the username and password, which the MOREINFO="NONE"dbopen routine uses when logging into a server. DB-Library/C routines can specify the information in the LOGINRECID="IN119752619"DBPROCESS structure
ID="IN16742720"Servercommunicating with
. RENDERAS="SECT1"DB-Library/C ProgrammingREMAP="BO--Body"An application programmer writes a DB-Library program, using calls to DB-Library routines to set up DB-Library structures, connect to servers, send commands, process results, and clean up. A DB-Library program is compiled and run in the same way as any other C language program.ID="IN111732821"ProgrammingDB-Library/C
ID="IN112722922"ApplicationsDB-Library/CREMAP="BO--Body"Programming with DB-Library/C typically involves a few basic steps: NUMERATION="ARABIC" REMAP="S1--StepOne" CONTINUATION="RESTARTS" INHERITNUM="IGNORE"Logging into a server.Placing language commands into a buffer and sending them to the server.Processing the results, if any, returned from the server, one command at a time and one result row at a time. The results can be placed in program variables, where they can be manipulated by the application. Handling DB-Library/C errors and server messages. Closing the connection with the server. The example below shows the basic framework of many DB-Library/C applications. The program opens a connection to a SQL Server, sends a Transact-SQL MOREINFO="NONE"select command to the server, and processes the set of rows resulting from the MOREINFO="NONE"select. For brevity's sake, this program does not include the error or message handling routines; those routines are illustrated in the example programs included on-line with DB-Library.ID="IN112722923"ApplicationsDB-Library/C:example ofREMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"#include <sybfront.h> #include <sybdb.h> #include <syberror.h> /* Forward declarations of the error handler and message** handler. */ int      err_handler(); int      msg_handler(); main() {      DBPROCESS    *dbproc;     /* The connection with */                               /* SQL Server */      LOGINREC     *login;      /* The login information */     DBCHAR       name[40];     DBCHAR       city[20];     RETCODE      return_code;      /* Initialize DB-Library */      if (dbinit() == FAIL)           exit(ERREXIT);      /*       ** Install user-supplied error-handling and message-      ** handling routines. The code for these is omitted      ** from this example for conciseness.      */      dberrhandle(err_handler);      dbmsghandle(msg_handler);      /* Get a LOGINREC */      login = dblogin();      DBSETLPWD(login, "server_password");      DBSETLAPP(login, "example");       /* Get a DBPROCESS structure for communication */     /* with SQL Server. */      dbproc = dbopen(login, NULL);       /*      ** Retrieve some columns from the "authors" table      ** in the "pubs2" database.      */       /* First, put the command into the command buffer. */      dbcmd(dbproc, "select au_lname, city from          pubs2..authors");      dbcmd(dbproc, " where state = 'CA' ");       /*      ** Send the command to SQL Server and start execution     */      dbsqlexec(dbproc);      /* Process the command */      while ((return_code = dbresults(dbproc)) !=          NO_MORE_RESULTS)      {           if (return_code == SUCCEED)           {                /* Bind results to program variables. */                dbbind(dbproc, 1, STRINGBIND, (DBINT)0, name);                dbbind(dbproc, 2, STRINGBIND, (DBINT)0, city);                /* Retrieve and print the result rows. */                while (dbnextrow(dbproc) != NO_MORE_ROWS)                {                     printf ("%s: %s\n", name, city);                }           }      }       /* Close the connection to SQL Server */      dbexit(); } REMAP="BO--Body"The example illustrates features common to most DB-Library/C applications: MARK="BULL" REMAP="BU--Bullet"Header files. Two header files, sybfront.h and sybdb.h, are required in all source files that contain calls to DB-Library/C routines. sybfront.h must appear first in the file. It defines symbolic constants such as function return values, described in the Section 2 manual pages, and the exit values STDEXIT and ERREXITID="IN111683329"Exit values
. These exit values can be used as the argument for the C standard library function MOREINFO="NONE"exit. Since they are defined appropriately for the operating system running the program, their use provides a system-independent approach to exiting the program. sybfront.h also includes typedefs for datatypes that can be used in program variable declarations. These datatypes are described a little later. REMAP="UN--Under"sybdb.h contains additional definitions and typedefs, most of which are meant to be used only by the DB-Library/C routines and should not be directly accessed by the program. Of chief importance in sybdb.h is the typedef for the DBPROCESS structure. As discussed earlier, the DBPROCESS structure should be manipulated only through DB-Library/C routines; you should not access its components directly. To ensure compatibility with future releases of DB-Library/C, use the contents of sybdb.h only as documented in the DB-Library/C manual pages. ID="IN122663530"syberror.h header file
ID="IN121663531"Error severity valuesREMAP="UN--Under"The third header file in the example, syberror.h, contains error severity values and should be included if the program refers to those values. dbinit. This routine initializes DB-Library/C. It must be the first DB-Library/C routine in the program. Not all DB-Library/C environments currently require the MOREINFO="NONE"dbinit call. However, to ensure future compatibility and portability, you should include this call at the start of all DB-Library/C programs. dberrhandle and dbmsghandle. MOREINFO="NONE"dberrhandle installs a user-supplied error-handling routine, which gets called automatically whenever the application encounters a DB-Library/C error. Similarly, MOREINFO="NONE"dbmsghandle installs a message-handling routine, which gets called in response to informational or error messages returned from the server. The error and message handling routines are user-supplied. Sample handlers have not been supplied with this example, but are included with the on-line example programs. For more information on the example programs, see the Open Client/Server Supplement.dblogin. This routine allocates a LOGINREC structure, which DB-Library/C will use to log into the server. The two macros that follow set certain components of the LOGINREC.MOREINFO="NONE" DBSETLPWD sets the password that DB-Library/C will use when logging in.MOREINFO="NONE" DBSETLAPP sets the name of the application, which will appear in SQL Server's sysprocess table. Routines are available for setting other aspects of the LOGINREC. However, in most environments these routines are optional; the LOGINREC contains default values for each of the values they set. dbopen. The MOREINFO="NONE"dbopen routine opens a connection between the application and a server. It uses the LOGINREC supplied by MOREINFO="NONE"dblogin to log in to the server. It returns a DBPROCESS structure, which serves as the conduit for information between the application and the server. After this routine has been called, the application is connected with SQL Server and can now send Transact-SQL commands to SQL Server and process any results. dbcmd. This routine fills the command buffer with Transact-SQL commands, which can then be sent to SQL Server. Each succeeding call to MOREINFO="NONE"dbcmd simply adds the supplied text to the end of any text already in the buffer. It is the programmer's responsibility to supply necessary blanks between words, such as the blank at the beginning of the text in the second MOREINFO="NONE"dbcmd call in the example. Multiple commands can be included in the buffer. This example only shows how to send and process a single command, but DB-Library/C is designed to allow an application to send multiple commands to a server and process each command's set of results separately. dbsqlexec. This routine executes the command buffer; that is, it sends the contents of the buffer to SQL Server, which parses and executes them. dbresults. This routine gets the results of the current Transact-SQL command ready for processing.   In this case, the buffer contains a single command which returns rows, so the program is required to call MOREINFO="NONE"dbresults one time. MOREINFO="NONE"dbresults is called in a loop, however, because it is good programming practice to do so. It is recommended that MOREINFO="NONE"dbresults always be called in a loop, as it is in this example, even when it is not strictly necessary. dbbind. MOREINFO="NONE"dbbind binds result columns to program variables. In the example, the first call to MOREINFO="NONE"dbbind binds the first result column to the variable "name". In other words, when the program reads a result row by calling MOREINFO="NONE"dbnextrow, the contents of the first result column ("au_lname") will get placed in the "name" variable. The second MOREINFO="NONE"dbbind call binds the second result column to the variable "city". REMAP="UN--Under"The datatype of both bindings is "STRINGBIND," one of several binding types available for character data. The binding type must correspond to the datatype of the specified program variable. In this example the "name" variable has a DBCHAR datatype, a DB-Library/C-defined datatype that accepts a STRINGBIND result. By means of the binding type parameter, MOREINFO="NONE"dbbind supports a wide variety of type conversions, allowing the datatype of the receiving variable to differ from the datatype of the result column. dbnextrow. This routine reads a row and places the results in the program variables specified by the earlier MOREINFO="NONE"dbbind calls. Each successive call to MOREINFO="NONE"dbnextrow reads another result row, until the last row has been read and NO_MORE_ROWS is returned. Processing of the results must take place inside the MOREINFO="NONE"dbnextrow loop, because each call to MOREINFO="NONE"dbnextrow overwrites the previous values in the program variables. This example program merely prints each row's contents. dbexit. This routine closes the server connection and de-allocates the DBPROCESS. It also cleans up any structures initialized by MOREINFO="NONE"dbinit. It must be the last DB-Library/C routine in the program. Although DB-Library/C contains a great number of routines, much can be accomplished with just the few routines shown in this example. RENDERAS="SECT2"DB-Library/C Datatypes   ID="IN19663532"DatatypesDB-Library/C
ID="IN19663533"DatatypesSQL Server
ID="IN18663534"TypedefsDB-Library/CREMAP="BO--Body"DB-Library/C defines datatypes for SQL Server data. These datatypes begin with "SYB" (e.g., SYBINT4, SYBCHAR, SYBMONEY). Various routines require these datatypes as parameters. DB-Library/C and Server-Library/C also provide typedefs for use in program variable declarations. These typedefs begin with the prefix "DB" (e.g., DBINT, DBCHAR, DBMONEY, etc.) for DB-Library/C, and "SRV_" for Server-Library/C (e.g., SRV_INT4, SRV_CHAR, SRV_MONEY). By using them, you ensure that your program variables will be compatible. Section 2 includes a manual page, MOREINFO="NONE"types, that lists SQL Server datatypes and the DB-Library/C program variable types. See the Open Server-Library/C Reference Manual for a list of Server-Library datatypes. REMAP="BO--Body"The MOREINFO="NONE"dbconvert routine provides a way to convert data from one server datatype to another. It supports conversion between most datatypes. Since SQL Server and Open Server datatypes correspond directly to the DB-Library/C datatypes, you can use MOREINFO="NONE"dbconvert widely within your application. The routines that bind server result columns to program variables-MOREINFO="NONE"dbbind and MOREINFO="NONE"dbaltbindID="IN111653635"ProgrammingDB-Library/C
ID="IN112643736"ApplicationsDB-Library/C
-also provide type conversion. RENDERAS="SECT1"DB-Library/C Routines   ID="IN18633837"RoutinesREMAP="BO--Body"The DB-Library/C routines and macros handle a large variety of tasks, which are divided in this section into a number of categories: MARK="BULL" REMAP="BU--Bullet"Initialization Command Processing Results Processing Message and Error Handling Information Retrieval Browse Mode Text and Image Handling Datatype Conversion Process Control Flow Remote Procedure Call Processing Registered Procedure Call Processing Network Datetime and Money Cleanup Miscellaneous REMAP="BO--Body"The routines and macros are described in individual manual pages in Section 2. They all begin with the prefix "db". The routines are named with lowercase letters; the macros are capitalized. REMAP="BO--Body"In addition, DB-Library/C includes two special libraries: MARK="BULL" REMAP="BU--Bullet"Bulk Copy Two-Phase Commit Service REMAP="BO--Body"The routines in these libraries are described in manual pages in Section 3 and 4. The bulk copy routines begin with the prefix "bcp". The two-phase commit routines have no standard prefix. RENDERAS="SECT2"Initialization   ID="IN18633838"RoutinesinitializationREMAP="BO--Body"These routines set up and define the connection between the application program and a server. They handle such tasks as allocating and defining a LOGINREC structure, opening a connection to a server, and allocating a DBPROCESS structure. Only a few of the routines are absolutely necessary in every DB-Library/C program; in particular, an application requires MOREINFO="NONE"dbinit, MOREINFO="NONE"dblogin and MOREINFO="NONE"dbopen. The lists below specify the initialization routines in the approximate order in which a program is likely to call them. RENDERAS="SECT3"Initializing DB-Library/C   REMAP="BO--Body"MOREINFO="NONE"dbinit Initializes underlying structures used by DB-Library/C. REMAP="BO--Body"MOREINFO="NONE"dbsetversion Specifies a DB-Library version level.RENDERAS="SECT3"Setting Up the LOGINREC   REMAP="BO--Body"MOREINFO="NONE"dblogin Allocates a LOGINREC structure for subsequent use by MOREINFO="NONE"dbopen. REMAP="BO--Body"MOREINFO="NONE"DBSETLUSER Sets the server username in the LOGINREC. REMAP="BO--Body"MOREINFO="NONE"DBSETLPWD Sets the server password in the LOGINREC. REMAP="BO--Body"MOREINFO="NONE"DBSETLAPPSets the application name in the LOGINREC. REMAP="BO--Body"MOREINFO="NONE"DBSETLHOST Sets the host name in the LOGINREC. REMAP="BO--Body"MOREINFO="NONE"dbloginfree Frees a LOGINREC structure. REMAP="BO--Body"MOREINFO="NONE"DBSETLCHARSET Sets the character set in the LOGINREC. RENDERAS="SECT3"Establishing a Server Connection   REMAP="BO--Body"MOREINFO="NONE"dbsetifile Specifies the interfaces file that MOREINFO="NONE"dbopen will use to connect to a server. Note that for OS/2 and DOS platforms, no interfaces file is used. REMAP="BO--Body"MOREINFO="NONE"dbsetlogintime Sets the number of seconds DB-Library/C will wait for a server to respond to a request by MOREINFO="NONE"dbopen for a DBPROCESS connection. REMAP="BO--Body"MOREINFO="NONE"dbopen Sets up communication with the network, logs into a server using the LOGINREC, initializes any options specified in the LOGINREC, and allocates a DBPROCESS. An application can open multiple connections to a server, each connection having its own DBPROCESS. An application can also open multiple connections to multiple servers. RENDERAS="SECT3"Setting the Database   REMAP="BO--Body"MOREINFO="NONE"dbuse Sets the current database. This routine is equivalent to the Transact-SQL MOREINFO="NONE"use command and can be called repeatedly in an application. RENDERAS="SECT2"Command Processing   ID="IN18633839"Routinescommand processing
ID="IN18623940"Commandsprocessing
ID="IN115623941"Command buffers
ID="IN115623942"Command batchesREMAP="BO--Body"An application can communicate with a server through language commands. For SQL Server, the language is Transact-SQL. For Open Server, the language is whatever the Open Server has been programmed to understand. The application enters the commands into a command buffer, which the DBPROCESS points to. The application can place multiple commands in the command buffer, and the set of commands in the buffer is known as the command batch. The application then sends the command batch to the server, which executes the commands in the order entered in the buffer. RENDERAS="SECT3"Building the Command Batch   REMAP="BO--Body"These routines add commands to the buffer or clear the buffer. REMAP="BO--Body"MOREINFO="NONE"dbcmd Adds text to the command buffer. It may be called repeatedly to add multiple commands, or parts of commands. The text added with each successive call is concatenated to the previous text. REMAP="BO--Body"MOREINFO="NONE"dbfcmd Adds text to the command buffer using MOREINFO="NONE"sprintf-type formatting. This routine is the same as MOREINFO="NONE"dbcmd, except that it allows arguments to be substituted into the text. REMAP="BO--Body"MOREINFO="NONE"dbfreebuf Clears the command buffer. The command buffer is automatically cleared before a batch of commands is entered. To clear it at other times or when the DBNOAUTOFREE option has been set, use MOREINFO="NONE"dbfreebuf. RENDERAS="SECT3"Accessing the Command Batch   REMAP="BO--Body"These routines may be used to examine and copy parts of the command buffer. REMAP="BO--Body"MOREINFO="NONE"dbgetchar Returns a pointer to a particular character in the command buffer. REMAP="BO--Body"MOREINFO="NONE"dbstrlen Returns the length of the command buffer. REMAP="BO--Body"MOREINFO="NONE"dbstrcpy Copies a portion of the command buffer to a program variable. This routine is particularly valuable for debugging, because it can tell you exactly what was sent to the server. RENDERAS="SECT3"Executing the Command Batch   REMAP="BO--Body"Once language commands have been entered in the buffer, they can be sent to a server for execution. REMAP="BO--Body"MOREINFO="NONE"dbsqlsend Sends the contents of the command buffer to a server for execution. Unlike MOREINFO="NONE"dbsqlexec, this routine does not wait for a response from the server. When MOREINFO="NONE"dbsqlsend has returned SUCCEED, MOREINFO="NONE"dbsqlok must be called to verify the correctness of the command batch. REMAP="BO--Body"MOREINFO="NONE"dbsqlok Waits for results from the server and verifies the correctness of the instructions the server is responding to. This routine is used in conjunction with MOREINFO="NONE"dbsqlsend, MOREINFO="NONE"dbrpcsend, and MOREINFO="NONE"dbmoretext. After a successful MOREINFO="NONE"dbsqlok call, the application must call MOREINFO="NONE"dbresults to process the results. REMAP="BO--Body"MOREINFO="NONE"dbsqlexec Sends the contents of the command buffer to a server for execution. Once MOREINFO="NONE"dbsqlexec has returned SUCCEED, MOREINFO="NONE"dbresults must be called to process the results. Calling MOREINFO="NONE"dbsqlexec is equivalent to calling MOREINFO="NONE"dbsqlsend followed by MOREINFO="NONE"dbsqlok. RENDERAS="SECT3"Setting and Clearing Command Options   REMAP="BO--Body"The application can set a number of SQL Server and DB-Library/C command options. Among them are DBPARSEONLY, which causes SQL Server to parse but not execute the command batch, and DBBUFFER, which provides buffering of result rows. For a list of all available options and their significance, see the MOREINFO="NONE"options manual page at the end of Section 2. REMAP="BO--Body"MOREINFO="NONE"dbsetopt Sets an option. REMAP="BO--Body"MOREINFO="NONE"dbclropt Clears an option. REMAP="BO--Body"MOREINFO="NONE"dbisoptID="IN18614043"CommandsprocessingDetermines whether a particular option is set. RENDERAS="SECT2"Results Processing   ID="IN18614044"Routinesresults processing
ID="IN111604145"Result rowsprocessing
ID="IN111604146"Result rows
ID="IN111604147"Result rowsregular
ID="IN111604148"Result rowscompute
ID="IN112604149"Regular rows
ID="IN112604150"Compute rows
ID="IN111574451"Result rowscompute. See Compute rows.
ID="IN111544752"Result rowsregular. See Regular rows.
ID="IN14515053"Rowsresult. See Result rows.
ID="IN14485354"Rowsregular. See Regular rows.
ID="IN14455655"Rowscompute. See Compute rows.REMAP="BO--Body"Once a command batch has been executed in the server, indicated by MOREINFO="NONE"dbsqlexec or MOREINFO="NONE"dbsqlok returning SUCCEED, the application must process any results. Results can include: MARK="BULL" REMAP="BU--Bullet"Success or failure indications from the server; and Result rows. REMAP="BO--Body"Result rows are returned by MOREINFO="NONE"select commands and MOREINFO="NONE"executes on stored procedures that contain MOREINFO="NONE"select commands. REMAP="BO--Body"There are two types of result rows: regular rows and compute rows. Regular rows are generated from columns in a MOREINFO="NONE"select command's select-list; compute rows are generated from columns in a MOREINFO="NONE"select command's MOREINFO="NONE"compute clause. Since these two types of rows contain very different data, the application must process them separately. REMAP="BO--Body"The results for each Transact-SQL command in a batch are returned to the application separately. Within each command's set of results, the result rows are processed one at a time. REMAP="BO--Body"If a command batch contains only a single Transact-SQL command and that command returns rows, for example a MOREINFO="NONE"select command, an application must call MOREINFO="NONE"dbresults to process the results of the command. REMAP="BO--Body"If a command batch contains only a single Transact-SQL command and that command does not return rows, for example a "use database" command, an application does not have to call MOREINFO="NONE"dbresults to process the results of the command. REMAP="BO--Body"If the command batch contains more than one Transact-SQL command, an application must call MOREINFO="NONE"dbresults once for every command in the batch, whether or not the command returns rows. For this reason, it is recommended that a DB-Library/C application always call MOREINFO="NONE"dbresults in a loop after sending a command or commands to a server. REMAP="BO--Body"The following table lists Transact-SQL commands and the DB-Library/C functions required to process the results that they return: TOCENTRY="1"LBL="Table 1-1: "DB-Library/C functions required to process Transact-SQL 
commands.COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="112*"COLNAME="C2" COLWIDTH="247*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Transact-SQL 
CommandCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"Required DB-Library/C Functions VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"All Transact-SQL 
commands not listed 
elsewhere in this table. COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"dbresults. In some cases, for example MOREINFO="NONE"dbcc, the 
command's normal output is considered by DB-
Library/C to consist of errors and messages. The 
output is thus processed within a DB-Library/C 
application's error and message handlers instead of 
in the main program via MOREINFO="NONE"dbnextrow or other DB-
Library/C routines. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"executeCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A DB-Library/C application must call MOREINFO="NONE"dbresults once 
for every set of results that the stored procedure 
returns.   In addition, if the stored procedure returns 
rows, the application must call MOREINFO="NONE"dbnextrow or other DB-
Library/C result-row routines. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"selectCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"dbresults. In addition, a DB-Library/C application 
must call MOREINFO="NONE"dbnextrow or other DB-Library/C result-row 
routines. RENDERAS="SECT3"Setting Up the Results   REMAP="BO--Body"MOREINFO="NONE"dbresults Sets up the results of the next command in the batch. MOREINFO="NONE"dbresults must be called after MOREINFO="NONE"dbsqlexec or MOREINFO="NONE"dbsqlok has returned SUCCEED, but before calls to MOREINFO="NONE"dbbind or MOREINFO="NONE"dbnextrow. RENDERAS="SECT3"Getting Result Data   REMAP="BO--Body"The simplest way to get result data is to bind result columns to program variables, using MOREINFO="NONE"dbbind and MOREINFO="NONE"dbaltbind. Then, when the application calls MOREINFO="NONE"dbnextrow to read a result row (see the next section), DB-Library/C will automatically place copies of the columns' data into the program variables to which they are bound. The application must call MOREINFO="NONE"dbbind and MOREINFO="NONE"dbaltbind after a MOREINFO="NONE"dbresults call but before the first call to MOREINFO="NONE"dbnextrow. REMAP="BO--Body"You can also access a result column's data directly with MOREINFO="NONE"dbdata and MOREINFO="NONE"dbadata, which return pointers to the data. MOREINFO="NONE"dbdata and MOREINFO="NONE"dbadata have the advantage of providing access to the actual data, not a copy of the data. These routines are frequently used in conjunction with MOREINFO="NONE"dbdatlen and MOREINFO="NONE"dbadlen, which return the length of the data and are described later, in the section "Information Retrieval." When you are accessing data directly with these routines, you do not perform any preliminary binding of result columns to program variables. Simply call MOREINFO="NONE"dbdata or MOREINFO="NONE"dbadata after a MOREINFO="NONE"dbnextrow call. REMAP="BO--Body"MOREINFO="NONE"dbbind Binds a regular row result column to a program variable. REMAP="BO--Body"MOREINFO="NONE"dbbind_ps Binds a regular row result column to a program variable, with precision and scale support for numeric and decimal variables.REMAP="BO--Body"MOREINFO="NONE"dbaltbind Binds a compute row result column to a program variable. REMAP="BO--Body"MOREINFO="NONE"dbaltbind_ps Binds a compute row result column to a program variable, with precision and scale support for numeric and decimal variables.REMAP="BO--Body"MOREINFO="NONE"dbdata Returns a pointer to the data for a regular row result column. REMAP="BO--Body"MOREINFO="NONE"dbadata Returns a pointer to the data for a compute row result column. REMAP="BO--Body"MOREINFO="NONE"dbnullbind Associates an indicator variable with a regular row result column. REMAP="BO--Body"MOREINFO="NONE"dbanullbind Associates an indicator variable with a compute-row column. RENDERAS="SECT3"Reading Result Rows   REMAP="BO--Body"Once MOREINFO="NONE"dbresults has returned SUCCEED and any binding of columns to variables has been specified, the application is ready to process the results. The first step is to make the result rows available to the application. The MOREINFO="NONE"dbnextrow routine accomplishes this. Each call to MOREINFO="NONE"dbnextrow reads the next row returned from the server. The row is read directly from the network. REMAP="BO--Body"Once a row has been read in by MOREINFO="NONE"dbnextrow, the application can perform any processing desired on the data in the row. If the result columns have been bound to program variables, the data in the row will have been automatically copied into the variables. Alternatively, the data is accessible through MOREINFO="NONE"dbdata or MOREINFO="NONE"dbadata. REMAP="BO--Body"Rows read in by MOREINFO="NONE"dbnextrow may be automatically saved in a row buffer, if desired. The application accomplishes this by setting the DBBUFFER option with the MOREINFO="NONE"dbsetopt routine. Row buffering is useful for applications that need to process result rows in a non-sequential manner. Without row buffering, the application must process each row as it is read in by MOREINFO="NONE"dbnextrow, because the next call to MOREINFO="NONE"dbnextrow will overwrite the row. If the application has enabled row buffering, the rows are added to a row buffer as they are read in by MOREINFO="NONE"dbnextrow. The application can then use the MOREINFO="NONE"dbgetrow routine to skip around in the buffer and return to previously read rows. Since row buffering carries a memory and performance penalty, use it with discretion. Note that row buffering has nothing to do with network buffering and is a completely independent issue. REMAP="BO--Body"Routines are also available to print result rows in a default format. Because the format is predetermined, these routines are of limited usefulness and are appropriate primarily for debugging. REMAP="BO--Body"Note that DB-Library/C processes results one command at a time. When the application has read all the results for one command, it must call MOREINFO="NONE"dbresults again to set up the results for the next command in the command buffer. To ensure that all results are handled, is strongly recommended that MOREINFO="NONE"dbresults be called in a loop. REMAP="BO--Body"MOREINFO="NONE"dbnextrow Reads in the next row. The return value from MOREINFO="NONE"dbnextrow tells the application whether the row is a regular row or a compute row, whether the row buffer is full, and whether the last result row has been read. REMAP="BO--Body"MOREINFO="NONE"dbgetrow Reads the specified row in the row buffer. This routine provides the application with access to buffered rows that have been previously read by MOREINFO="NONE"dbnextrow. REMAP="BO--Body"MOREINFO="NONE"dbclrbuf Drops rows from the row buffer. REMAP="BO--Body"MOREINFO="NONE"dbprrow Prints all the result rows in a default format. When this routine is used, the program does not need to bind results or call MOREINFO="NONE"dbnextrow. REMAP="BO--Body"MOREINFO="NONE"dbprhead Prints default column headings for result rows. This routine is used in conjunction with MOREINFO="NONE"dbprrow. RENDERAS="SECT3"Canceling Results   REMAP="BO--Body"MOREINFO="NONE"dbcancel Cancels results from the current command batch. This routine cancels all the commands in the current batch. REMAP="BO--Body"MOREINFO="NONE"dbcanquery Cancels any rows pending from the most recently executed query. RENDERAS="SECT3"Handling Stored Procedure Results   REMAP="BO--Body"A call to a stored procedure is made through either a remote procedure call, discussed in a later section, or a Transact-SQL MOREINFO="NONE"execute command. The call can generate several types of results. First of all, a stored procedure that contains MOREINFO="NONE"select statements will return result rows in the usual fashion. Each successive call to MOREINFO="NONE"dbresults will access the set of rows from the next MOREINFO="NONE"select statement in the stored procedure. These rows can be processed, as usual, with MOREINFO="NONE"dbnextrow. REMAP="BO--Body"Second, stored procedures can contain "return parameters." Return parameters provide stored procedures with a "call-by-reference" capability. Any change that a stored procedure makes internally to the value of a return parameter is available to the calling program once it has processed all of the stored procedure's result rows, if any, by calling MOREINFO="NONE"dbresults and MOREINFO="NONE"dbnextrow. A number of routines, described below, process return parameter values. REMAP="BO--Body"Third, stored procedures can return a status number. REMAP="BO--Body"A program can access a stored procedure's return parameters and status through the following routines: REMAP="BO--Body"MOREINFO="NONE"dbretdata Returns a pointer to a return parameter value. REMAP="BO--Body"MOREINFO="NONE"dbretlen Returns the length of a return parameter value. REMAP="BO--Body"MOREINFO="NONE"dbrettype Returns the datatype of a return parameter value. REMAP="BO--Body"MOREINFO="NONE"dbretname Returns the name of the return parameter associated with a particular value. REMAP="BO--Body"MOREINFO="NONE"dbnumrets Returns the number of return parameter values generated by a stored procedure. REMAP="BO--Body"MOREINFO="NONE"dbretstatus Returns the stored procedure's status number. REMAP="BO--Body"MOREINFO="NONE"dbhasretstat Indicates whether the current command or remote procedure call generated a stored procedure status number. RENDERAS="SECT3"Miscellaneous Results Processing   REMAP="BO--Body"MOREINFO="NONE"dbsettime Sets the number of seconds that DB-Library/C will wait for a server response. REMAP="BO--Body"MOREINFO="NONE"DBGETTIMEID="IN111445756"Result rowsprocessing
 Gets the number of seconds that DB-Library/C will wait for a server response. RENDERAS="SECT2"Message and Error Handling   ID="IN114445757"Error handling
ID="IN18445758"Routineserror handling
ID="IN116445759"Message handling
ID="IN18445760"Routinesmessage handling
ID="IN17445761"Handlermessage
ID="IN17445762"HandlererrorREMAP="BO--Body"DB-Library/C applications must handle two types of messages and errors: MARK="BULL" REMAP="BU--Bullet"Server messages and errors, which range in severity from informational messages to fatal errors. Server messages and errors are known to DB-Library/C applications as "messages." To list all possible SQL Server messages, use the Transact-SQL command "MOREINFO="NONE"select * from sysmessages"; also see the System Administration Guide. See the Open Server-Library/C Reference Manual for a list of Open Server messages. DB-Library/C warnings and errors, known to DB-Library/C applications as "errors." For a list of DB-Library/C errors, see the MOREINFO="NONE"errors manual page at the end of Chapter 2 of this book. REMAP="BO--Body"Also, success or failure indications are returned by most DB-Library/C routines. REMAP="BO--Body"To handle server messages, DB-Library/C errors, and success or failure indications, a DB-Library/C application can: MARK="BULL" REMAP="BU--Bullet"Test DB-Library/C routine return codes in the main-line code, handling failures on a case-by-case basis. Centralize message and error handling by installing a message handler and an error handler, which are then automatically called by DB-Library/C when a message or error occurs. REMAP="BO--Body"It is strongly recommended that all DB-Library/C applications use centralized message and error handling in addition to main-line error testing. Centralized message and error handling has substantial benefits for large or complex applications. For example: MARK="BULL" REMAP="BU--Bullet"Centralized message and error handling reduces the need for main-line error-handling logic. This is because DB-Library/C calls an application's message and error handlers automatically whenever a message or error occurs. REMAP="UN--Under"Note, however, that even an application which uses centralized error and message handling will need some main-line error logic, depending on the nature of the application. Centralized message and error handling provides a mechanism for gracefully handling unexpected errors. An application using only main-line error-handling logic may not successfully trap errors which have not been anticipated. REMAP="BO--Body"To provide a DB-Library/C application with centralized message and error handling, the application programmer must write a message handler and an error handler and install them via MOREINFO="NONE"dbmsghandle and MOREINFO="NONE"dberrhandle. REMAP="BO--Body"The DB-Library/C routines for message and error handling are: REMAP="BO--Body"MOREINFO="NONE"dbmsghandle Installs a user function to handle server informational and error messages. REMAP="BO--Body"MOREINFO="NONE"dberrhandle Installs a user function to handle DB-Library/C error messages. REMAP="BO--Body"MOREINFO="NONE"DBDEAD Determines whether a particular DBPROCESS is dead. When a DBPROCESS is dead, the current DB-Library/C routine fails, causing the error handler to be called. RENDERAS="SECT2"Information Retrieval   ID="IN18445763"Routinesinformation retrievalREMAP="BO--Body"Information covering several areas, including regular result columns, compute result columns, row buffers, and the command state, can be retrieved from the DBPROCESS structure. As mentioned earlier, regular result columns correspond to columns in the MOREINFO="NONE"select command's select-list and compute result columns correspond to columns in the MOREINFO="NONE"select command's optional MOREINFO="NONE"compute clause. RENDERAS="SECT3"Regular Result Column Information   REMAP="BO--Body"These routines can be called after MOREINFO="NONE"dbsqlexec returns SUCCEED. REMAP="BO--Body"MOREINFO="NONE"dbnumcols Determines the number of columns in the current set of results. REMAP="BO--Body"MOREINFO="NONE"dbcolname Returns the name of a regular result column. REMAP="BO--Body"MOREINFO="NONE"dbcollen Returns the maximum length for a regular column's data. REMAP="BO--Body"MOREINFO="NONE"dbcoltype Returns the server datatype for a regular result column. REMAP="BO--Body"MOREINFO="NONE"dbdatlen Returns the actual length of a regular column's data. This routine is often used in conjunction with MOREINFO="NONE"dbdata. The value returned by MOREINFO="NONE"dbdatlen is different for each regular row read by MOREINFO="NONE"dbnextrow. REMAP="BO--Body"MOREINFO="NONE"dbvarylen Indicates whether the column's data can vary in length. RENDERAS="SECT3"Compute Result Column Information   REMAP="BO--Body"These routines can be called after MOREINFO="NONE"dbsqlexec returns SUCCEED. REMAP="BO--Body"MOREINFO="NONE"dbnumcompute Returns the number of MOREINFO="NONE"compute clauses in the current set of results. REMAP="BO--Body"MOREINFO="NONE"dbnumalts Returns the number of columns in a compute row. REMAP="BO--Body"MOREINFO="NONE"dbbylist Returns the bylist for a compute row. REMAP="BO--Body"MOREINFO="NONE"dbaltop Returns the type of aggregate operator for a compute column. REMAP="BO--Body"MOREINFO="NONE"dbalttype Returns the datatype for a compute column. REMAP="BO--Body"MOREINFO="NONE"dbaltlen Returns the maximum length for a compute column's data. REMAP="BO--Body"MOREINFO="NONE"dbaltcolid Returns the column id for a compute column. REMAP="BO--Body"MOREINFO="NONE"dbadlen Returns the actual length of a compute column's data. This routine is often used in conjunction with MOREINFO="NONE"dbadata. The value returned by MOREINFO="NONE"dbadlen is different for each compute row read by MOREINFO="NONE"dbnextrow. RENDERAS="SECT3"Row Buffer Information   REMAP="BO--Body"These macros return information that can be useful when manipulating result rows in buffers. REMAP="BO--Body"MOREINFO="NONE"DBFIRSTROW Returns the number of the first row in the buffer. REMAP="BO--Body"MOREINFO="NONE"DBLASTROW Returns the number of the last row in the buffer. RENDERAS="SECT3"Command State Information   REMAP="BO--Body"These routines return information about the current state of the command batch. Several of them return information about the "current" command-that is, the command currently being processed by MOREINFO="NONE"dbresults. REMAP="BO--Body"MOREINFO="NONE"DBCURCMD Returns the number of the current command in a batch. REMAP="BO--Body"MOREINFO="NONE"dbgetoff Checks for the existence of specified Transact-SQL constructs in the command buffer. This routine is used in conjunction with the DBOFFSET option. REMAP="BO--Body"MOREINFO="NONE"DBMORECMDS Indicates whether there are more commands in the batch. REMAP="BO--Body"MOREINFO="NONE"DBCMDROW Indicates whether the current command is one that can return rows (i.e., a MOREINFO="NONE"select or a stored procedure containing a MOREINFO="NONE"select). REMAP="BO--Body"MOREINFO="NONE"DBROWS Indicates whether the current command actually did return rows. REMAP="BO--Body"MOREINFO="NONE"DBCOUNT Returns the number of rows affected by a command. REMAP="BO--Body"MOREINFO="NONE"DBNUMORDERS Returns the number of columns specified in a MOREINFO="NONE"select command's MOREINFO="NONE"order MOREINFO="NONE"by clause. REMAP="BO--Body"MOREINFO="NONE"dbordercol Returns the id of a column appearing in a MOREINFO="NONE"select command's MOREINFO="NONE"order MOREINFO="NONE"by clause. RENDERAS="SECT3"Miscellaneous Information   REMAP="BO--Body"MOREINFO="NONE"DBCURROW Returns the number of the row currently being read. REMAP="BO--Body"MOREINFO="NONE"DBROWTYPE Indicates whether the current result row is a regular row or a compute row. REMAP="BO--Body"MOREINFO="NONE"DBISAVAIL Indicates whether a DBPROCESS is available for general use. REMAP="BO--Body"MOREINFO="NONE"dbname Returns the name of the current database. REMAP="BO--Body"MOREINFO="NONE"dbchange Indicates whether a command batch has changed the current database. REMAP="BO--Body"MOREINFO="NONE"dbgetmaxprocs Indicates the current maximum number of simultaneously open DBPROCESSes. RENDERAS="SECT2"Browse Mode   ID="IN111435864"Browse mode
ID="IN19425965"Databasesupdating
ID="IN118416066"Updating databasesREMAP="BO--Body"Browse mode provides a means for browsing through database rows and updating their values a row at a time. From the standpoint of the program, the process involves several steps, because each row must be transferred from the database into program variables before it can be browsed and updated. ID="IN19416067"Databasesmulti-user updates
ID="IN118416068"Updating databasesmulti-user situationsREMAP="BO--Body"Since a row being browsed is not the actual row residing in the database, but is instead a copy residing in program variables, the program must be able to ensure that changes to the variables' values can be reliably used to update the original database row. In particular, in multi-user situations, the program needs to ensure that updates made to the database by one user do not unwittingly overwrite updates recently made by another user. This can be a problem because the application typically selects a number of rows from the database at one time, but the application's users browse and update the database one row at a time. A timestampID="IN117416069"Timestamp columns
 column in browsable database tables provides the information necessary to regulate this type of multi-user updating. REMAP="BO--Body"Browse mode routines also allow an application to handle ad hoc queries. Several routines return information that an application can use to examine the structure of a complicated ad hoc query in order to update the underlying database tables. REMAP="BO--Body"Conceptually, browse mode involves three steps: NUMERATION="ARABIC" REMAP="S1--StepOne" CONTINUATION="RESTARTS" INHERITNUM="IGNORE"Select result rows containing columns derived from one or more database tables. Where appropriate, change values in columns of the result rows (not the actual database rows), one row at a time. Update the original database tables, one row at a time, using the new values in the result rows. REMAP="BO--Body"These steps are implemented in a program as follows: NUMERATION="ARABIC" REMAP="S1--StepOne" CONTINUATION="RESTARTS" INHERITNUM="IGNORE"Execute a MOREINFO="NONE"select command, generating result rows containing result columns. The MOREINFO="NONE"select command must include the MOREINFO="NONE"for MOREINFO="NONE"browse option. Copy the result column values into program variables, one row at a time. If appropriate, change the variables' values (possibly in response to user input). If appropriate, execute an MOREINFO="NONE"update command that updates the database row corresponding to the current result row. To handle multi-user updates, the MOREINFO="NONE"where clause of the MOREINFO="NONE"update command must reference the timestamp column. Such a MOREINFO="NONE"where clause can be obtained via the MOREINFO="NONE"dbqual function. Repeat the second, third, and fourth steps for each result row. REMAP="BO--Body"To use browse mode, the following conditions must be true: MARK="BULL" REMAP="BU--Bullet"The MOREINFO="NONE"select command must end with the key words MOREINFO="NONE"for MOREINFO="NONE"browse. The table(s) to be updated must be "browsable" (i.e., each must have a unique index and a timestamp column). Note that because a browse mode table has unique rows, the keyword MOREINFO="NONE"distinct has no effect in a MOREINFO="NONE"select against a browse-mode table. ID="IN111396270"Browse modeBrowse modeand DBPROCESSDBPROCESSThe result columns to be used in the updates must be "updatable"-they must be derived from browsable tables and cannot be the result of SQL expressions, such as "max(colname)". In other words, there must be a valid correspondence between the result column and the database column to be updated. In addition, browse mode usually requires two DBPROCESSes-one for selecting the data and another for performing updates based on the selected data. REMAP="BO--Body"For examples of browse mode programming, see the example programs included on-line.REMAP="BO--Body"The following constitute the browse mode routines: ID="IN18396271"Routinesbrowse modeREMAP="BO--Body"REMAP="BO--Body"MOREINFO="NONE"dbqual Returns a pointer to a MOREINFO="NONE"where clause suitable for use in updating the current row in a browsable table. REMAP="BO--Body"MOREINFO="NONE"dbfreequal Frees the memory allocated by MOREINFO="NONE"dbqual. REMAP="BO--Body"MOREINFO="NONE"dbtsnewval Returns the new value of the timestamp column after a browse-mode update. REMAP="BO--Body"MOREINFO="NONE"dbtsnewlen Returns the length of the new value of the timestamp column after a browse-mode update. REMAP="BO--Body"MOREINFO="NONE"dbtsput Puts the new value of the timestamp column into the given table's current row in the DBPROCESS. REMAP="BO--Body"MOREINFO="NONE"dbcolbrowse Indicates whether the source of a result column is updatable via browse mode. REMAP="BO--Body"MOREINFO="NONE"dbcolsource Returns a pointer to the name of the database column from which the specified result column was derived. REMAP="BO--Body"MOREINFO="NONE"dbtabbrowse Indicates whether a particular table is updatable via browse mode. REMAP="BO--Body"MOREINFO="NONE"dbtabcount Returns the number of tables involved in the current MOREINFO="NONE"select command. REMAP="BO--Body"MOREINFO="NONE"dbtabname Returns the name of a table based on its number. REMAP="BO--Body"MOREINFO="NONE"dbtabsourceID="IN111386372"Browse mode
ID="IN19376473"Databasesupdating
ID="IN118366574"Updating databases
 Returns the name and number of the table from which a particular result column was derived. RENDERAS="SECT2"Text and Image Handling   ID="IN18366575"Routinestext handling
ID="IN18366576"Routinesimage handlingREMAP="BO--Body"text and image are SQL Server datatypes designed to hold large text or image values. The text datatype will hold up to 2,147,483,647 bytes of printable characters. The image datatype will hold up to 2,147,483,647 bytes of binary data. REMAP="BO--Body"Because they can be so large, text and image values are not actually stored in database tables. Instead, a pointer to the text or image value is stored in the table. This pointer is called a "text pointer." REMAP="BO--Body"To ensure that competing applications do not wipe out one another's modifications to the database, a timestamp is associated with each text or image column. This timestamp is called a "text timestamp." REMAP="BO--Body"A DB-Library/C application that uses MOREINFO="NONE"dbwritetext to insert text or image data into a table must perform the following steps: NUMERATION="ARABIC" REMAP="S1--StepOne" CONTINUATION="RESTARTS" INHERITNUM="IGNORE"MOREINFO="NONE"insert all data into the row except the text or image value. MOREINFO="NONE"update the row, setting the value of the text or image column to NULL.   This step is necessary because a text or image column row that contains a null value will have a valid text pointer only if the null value was explicitly entered with the MOREINFO="NONE"update statement. MOREINFO="NONE"select the row. You must specifically MOREINFO="NONE"select the column which is to contain the text or image value. This step is necessary in order to provide the application's DBPROCESS with correct text pointer and text timestamp information. The application should throw away the data returned by this MOREINFO="NONE"select. Call MOREINFO="NONE"dbtxtptr to retrieve the text pointer from the DBPROCESS.   Call MOREINFO="NONE"dbtxtimestamp to retrieve the text timestamp from the DBPROCESS. Write the text or image value to SQL Server. An application can either: MARK="BULL" REMAP="BU--Bullet"Write the value with a single call to MOREINFO="NONE"dbwritetext; or Write the value in chunks, using MOREINFO="NONE"dbwritetext and MOREINFO="NONE"dbmoretext. If the application plans to make another update to this text or image value, it may want to save the new text timestamp which is returned by SQL Server at the conclusion of a successful MOREINFO="NONE"dbwritetext operation. The new text timestamp may be accessed via MOREINFO="NONE"dbtxtsnewval and stored for later retrieval via MOREINFO="NONE"dbtxtsput. REMAP="BO--Body"Several routines are available to facilitate the process of updating text and image columns in database tables: REMAP="BO--Body"MOREINFO="NONE"dbreadtext Reads a text or image value from SQL Server. REMAP="BO--Body"MOREINFO="NONE"dbwritetext Sends a text or image value to SQL Server. REMAP="BO--Body"MOREINFO="NONE"dbmoretext Sends part of a text or image value to SQL Server. REMAP="BO--Body"MOREINFO="NONE"dbtxptr Returns the text pointer for a column in the current results row. REMAP="BO--Body"MOREINFO="NONE"dbtxtimestamp Returns the value of the text timestamp for a column in the current results row. REMAP="BO--Body"MOREINFO="NONE"dbtxtsnewval Returns the new value of a text timestamp after a call to MOREINFO="NONE"dbwritetext. REMAP="BO--Body"MOREINFO="NONE"dbtxtsput Puts the new value of a text timestamp into the specified column of the current row in the DBPROCESS. RENDERAS="SECT2"Datatype Conversion   REMAP="BO--Body"DB-Library/C supports conversions between most server datatypes with the MOREINFO="NONE"dbconvert and MOREINFO="NONE"dbconvert_ps routines. For information on server datatypes, see the MOREINFO="NONE"types manual page at the end of Section 2. REMAP="BO--Body"The MOREINFO="NONE"dbbind, MOREINFO="NONE"dbbind_ps, MOREINFO="NONE"dbaltbind, and MOREINFO="NONE"dbaltbind_ps routines, which bind result columns to program variables, can also be used to perform type conversion. Those routines each contain a parameter that specifies the datatype of the receiving program variable. If the data being returned from the server is of a different datatype, DB-Library/C will usually convert it automatically to the type specified by the parameter. REMAP="BO--Body"MOREINFO="NONE"dbconvert Converts data from one server datatype to another. REMAP="BO--Body"MOREINFO="NONE"dbconvert_ps Converts data from one server datatype to another, with precision and scale support for numeric and decimal datatypes.REMAP="BO--Body"MOREINFO="NONE"dbwillconvert Indicates whether a specified datatype conversion is supported. RENDERAS="SECT2"Process Control Flow   ID="IN18366577"Routinesprocess controlREMAP="BO--Body"These routines allow the application to schedule its actions around its interaction with a server. REMAP="BO--Body"MOREINFO="NONE"dbsetbusy Calls a user-supplied function when DB-Library/C is reading or waiting to read results from the server. REMAP="BO--Body"MOREINFO="NONE"dbsetidle Calls a user-supplied function when DB-Library/C is finished reading from the server. REMAP="BO--Body"MOREINFO="NONE"dbsetinterrupt Calls user-supplied functions to handle interrupts while waiting on a read from the server. REMAP="BO--Body"MOREINFO="NONE"DBIORDESC UNIX and AOS/VS only. Provides access to the UNIX file descriptor used to read data coming from the server, allowing the application to respond to multiple input data streams. REMAP="BO--Body"MOREINFO="NONE"DBIOWDESC UNIX and AOS/VS only. Provides access to the UNIX file descriptor used to write data to the server, allowing the application to effectively utilize multiple input and output data streams. REMAP="BO--Body"MOREINFO="NONE"DBRBUF UNIX and AOS/VS only. Determines whether the DB-Library/C network buffer contains any unread bytes. REMAP="BO--Body"MOREINFO="NONE"dbcancel_a ID="IN127366578"Asynchronous routines (VMS)
ID="IN18366579"Routinesasynchronous (VMS)
VMS only. The asynchronous version of MOREINFO="NONE"dbcancel. REMAP="BO--Body"MOREINFO="NONE"dbnextrow_a VMS only. The asynchronous version of MOREINFO="NONE"dbnextrow. REMAP="BO--Body"MOREINFO="NONE"dbopen_a VMS only. The asynchronous version of MOREINFO="NONE"dbopen. REMAP="BO--Body"MOREINFO="NONE"dbresults_a VMS only. The asynchronous version of MOREINFO="NONE"dbresults. REMAP="BO--Body"MOREINFO="NONE"dbsqlexec_a VMS only. The asynchronous version of MOREINFO="NONE"dbsqlexec. RENDERAS="SECT2"Remote Procedure Call Processing   ID="IN122366580"Remote procedure callsprocessing
ID="IN122366581"Remote procedure calls
ID="IN117366582"Stored procedurescalling remotely
ID="IN18366583"Routinesremote procedure callREMAP="BO--Body"A remote procedure call is simply a call to a stored procedure residing on a remote server. Either an application or another server makes the call. A remote procedure call made by an application has the same effect as an MOREINFO="NONE"execute command-it executes the stored procedure, generating results accessible through MOREINFO="NONE"dbresults. However, a remote procedure call is often more efficient than an MOREINFO="NONE"execute command. Note that if the procedure being executed resides on a server other than the one to which the application is directly connected, commands executed within the procedure cannot be rolled back. REMAP="BO--Body"A server can make a remote procedure call to another server. This occurs when a stored procedure being executed on one server contains an MOREINFO="NONE"execute command for a stored procedure on another server. The MOREINFO="NONE"execute command causes the first server to log into the second server and perform a remote procedure call on the procedure. This happens without any intervention from the application, although the application can specify the remote password which the first server uses to log in. REMAP="BO--Body"MOREINFO="NONE"dbrpcinit Initializes a remote procedure call to a stored procedure. REMAP="BO--Body"MOREINFO="NONE"dbrpcparam Adds a parameter to a remote procedure call. REMAP="BO--Body"MOREINFO="NONE"dbrpcsend Signals the end of a remote procedure call, causing the server to begin executing the specified procedure. REMAP="BO--Body"MOREINFO="NONE"dbrpwset Adds a remote password to a LOGINREC structure. The server will use this password when it performs a remote procedure call on another server. REMAP="BO--Body"MOREINFO="NONE"dbrpwclr Clears all remote passwords from a LOGINREC structure. RENDERAS="SECT2"Registered Procedure Call Processing   ID="IN120356684"Registered procedureREMAP="BO--Body"A registered procedure is a procedure that is defined and installed in a running Open Server. Release 2.0 is the first Open Server release to support registered procedures. At this time, registered procedures are not supported by SQL Server. ID="IN120356685"Registered procedureuses ofREMAP="BO--Body"For DB-Library/C applications, registered procedures provide a means for inter-application communication and synchronization. This is because DB-Library/C applications connected to an Open Server can "watch" for a registered procedure to execute.   When the registered procedure executes, applications watching for it receive a notification that includes the procedure's name and the arguments it was called with. DB-Library/C applications may create only a special type of registered procedure, known as a "notification procedure." A notification procedure differs from a normal Open Server registered procedure in that it contains no executable statements. ID="IN120356686"Registered procedureexampleREMAP="BO--Body"For example, suppose that: MARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"stockprice is a real-time DB-Library/C application monitoring stock prices.   MOREINFO="NONE"price_change is a notification procedure created in Open Server by MOREINFO="NONE"stockprice, and that MOREINFO="NONE"price_change takes as parameters a stock name and a price differential. MOREINFO="NONE"sellstock, an application which puts stock up for sale, has requested to be notified when MOREINFO="NONE"price_change executes. REMAP="BO--Body"When MOREINFO="NONE"stockprice, the monitoring application, becomes aware that the price of Extravagant Auto Parts stock has risen $1.10, it executes MOREINFO="NONE"price_change with the parameters "Extravagant Auto Parts" and "+1.10".   REMAP="BO--Body"When MOREINFO="NONE"price_change executes, Open Server sends MOREINFO="NONE"sellstock a notification containing the name of the procedure (MOREINFO="NONE"price_change) and the arguments passed to it ("Extravagant Auto Parts" and "+1.10"). MOREINFO="NONE"sellstock uses the information contained in the notification to decide to put 100 shares of Extravagant Auto Parts stock up for sale. REMAP="BO--Body"MOREINFO="NONE"price_change is the means through which the MOREINFO="NONE"stockprice and MOREINFO="NONE"sellstock applications communicate.   REMAP="BO--Body"Registered procedures as a means of communication have the following advantages: MARK="BULL" REMAP="BU--Bullet"A single call to execute a registered procedure can result in many client applications being notified that the procedure has executed. The application executing the procedure does not need to know how many, or which, clients have requested notifications. The registered procedure communication mechanism is server-based. Open Server acts as a central repository for connection addresses. Because of this, client applications can communicate without having to connect directly to each other. Instead, each client simply connects to the server. REMAP="BO--Body"A DB-Library/C application can: MARK="BULL" REMAP="BU--Bullet"Create a registered procedure in Open Server. Drop a registered procedure. List all registered procedures defined in Open Server. Request to be notified when a particular registered procedure is executed. Drop a request to be notified when a particular registered procedure is executed. List all registered procedure notifications. Execute a registered procedure. Install a user-supplied handler to be called when an application receives notification that a registered procedure has executed. Poll Open Server to see if any registered procedure notifications are pending. ID="IN120356687"Registered procedureroutines
ID="IN18356688"Routinesregistered procedureREMAP="BO--Body"The registered procedure routines are: REMAP="BO--Body"MOREINFO="NONE"dbnpcreate Creates a notification procedure. REMAP="BO--Body"MOREINFO="NONE"dbnpdefine Defines a notification procedure. REMAP="BO--Body"MOREINFO="NONE"dbregdrop Drops a registered procedure. REMAP="BO--Body"MOREINFO="NONE"dbreglist Returns a list of all registered procedures currently defined in Open Server. REMAP="BO--Body"MOREINFO="NONE"dbreghandle Installs a handler routine for a registered procedure notification. REMAP="BO--Body"MOREINFO="NONE"dbreginit Initiates execution of a registered procedure. REMAP="BO--Body"MOREINFO="NONE"dbregnowatch Cancels a request to be notified when a registered procedure executes. REMAP="BO--Body"MOREINFO="NONE"dbregparam Defines a parameter for a registered procedure. REMAP="BO--Body"MOREINFO="NONE"dbregexec Executes a registered procedure. REMAP="BO--Body"MOREINFO="NONE"dbregwatch Requests to be notified when a registered procedure executes. REMAP="BO--Body"MOREINFO="NONE"dbregwatchlist Returns a list of registered procedures that a DBPROCESS is watching for. REMAP="BO--Body"MOREINFO="NONE"dbsetnotifs VMS only. Enables or disables registered procedure notifications. REMAP="BO--Body"MOREINFO="NONE"dbpoll, listed under the "Miscellaneous" category of DB-Library/C routines in this introduction, can be used to check whether any registered procedure notifications have arrived for a DBPROCESSID="IN120346789"Registered procedure
 connection. RENDERAS="SECT2"Network   ID="IN116336890"Network routines
ID="IN119336891"Tabular Data Streamroutines
ID="IN13336892"TDSroutines
ID="IN18336893"RoutinesTDSREMAP="BO--Body"These routines provide flexibility for DB-Library/C applications running in a network environment. They enable a DB-Library/C application to send and receive whole Tabular Data Streamname='trade' font='symbol' code='228'  charset='fontspecific'
 (TDS) packets and set TDS packet size. REMAP="BO--Body"TDS is an application protocol used for the transfer of requests and request results between clients and servers. DB-Library/C uses TDS automatically. It is not generally necessary for a DB-Library/C application to use TDS routines. ID="IN120336894"Gateway applicationsREMAP="BO--Body"Network routines are useful in building Open Server gateway applications. REMAP="BO--Body"MOREINFO="NONE"dbrecvpassthru Receives a TDS packet from Open Server. REMAP="BO--Body"MOREINFO="NONE"dbsendpassthru Sends a TDS packet to Open Server. REMAP="BO--Body"MOREINFO="NONE"dbsetlpacket Sets the TDS packet size for an application. REMAP="BO--Body"MOREINFO="NONE"dbgetpacketID="IN116326995"Network routines
 Returns the current TDS packet size. RENDERAS="SECT2"Datetime and Money   ID="IN117317096"Datetime routines
ID="IN114307197"Money routinesREMAP="BO--Body"These routines manipulate datetime and money datatypes. datetime and money types come in long versions, DBDATETIME and DBMONEY, and short (4-byte) versions, DBDATETIME4 and DBMONEY4. All of the DBDATETIME4 routines listed below are also available for DBDATETIME, and all DBMONEY4 routines are available for DBMONEY. For example, MOREINFO="NONE"dbmny4add, listed below, is also available as MOREINFO="NONE"dbmnyadd. REMAP="BO--Body"MOREINFO="NONE"dbdate4cmp Compares two DATETIME4 values. REMAP="BO--Body"MOREINFO="NONE"dbdate4zero Initializes a DBDATETIME4 value. REMAP="BO--Body"MOREINFO="NONE"dbmny4add Adds two DBMONEY4 values. REMAP="BO--Body"MOREINFO="NONE"dbmny4cmp Compares two DBMONEY4 values. REMAP="BO--Body"MOREINFO="NONE"dbmny4copy Copies a DBMONEY4 value. REMAP="BO--Body"MOREINFO="NONE"dbmny4divide Divides one DBMONEY4 value by another. REMAP="BO--Body"MOREINFO="NONE"dbmny4minus Negates a DBMONEY4 value. REMAP="BO--Body"MOREINFO="NONE"dbmny4mul Multiplies a DBMONEY4 value. REMAP="BO--Body"MOREINFO="NONE"dbmny4sub Subtracts a DBMONEY4 value. REMAP="BO--Body"MOREINFO="NONE"dbmny4zero Initializes a DBMONEY4 value. REMAP="BO--Body"MOREINFO="NONE"dbmnydec Decrements a DBMONEY value. REMAP="BO--Body"MOREINFO="NONE"dbmnydown Divides a DBMONEY value by a positive integer. REMAP="BO--Body"MOREINFO="NONE"dbmnyinc Increments a DBMONEY value. REMAP="BO--Body"MOREINFO="NONE"dbmnyinit Prepares a DBMONEY value for calls to MOREINFO="NONE"dbmnyndigit. REMAP="BO--Body"MOREINFO="NONE"dbmnymaxneg Returns the maximum negative DBMONEY value. REMAP="BO--Body"MOREINFO="NONE"dbmnymaxpos Returns the maximum positive DBMONEY value. REMAP="BO--Body"MOREINFO="NONE"dbmnyndigit Returns the rightmost digit of a DBMONEY value as a DBCHAR. REMAP="BO--Body"MOREINFO="NONE"dbmnyscale Multiplies a DBMONEYID="IN117297298"Datetime routines
ID="IN114287399"Money routines
 value and add a specified amount. RENDERAS="SECT2"Cleanup   REMAP="BO--Body"These routines sever the connection between the application and a server. REMAP="BO--Body"MOREINFO="NONE"dbexit Closes and de-allocates all DBPROCESS structures. This routine also cleans up any structures initialized by MOREINFO="NONE"dbinit. REMAP="BO--Body"MOREINFO="NONE"dbclose Closes and de-allocates a single DBPROCESS structure. ID="IN1172873100"Secure SQL Serverroutines forRENDERAS="SECT2"Secure SupportREMAP="BO--Body"These routines provide security for DB-Library applications running against 10.0+ SQL Server or a Secure SQL Server:REMAP="BO--Body"MOREINFO="NONE"DBSETLENCRYPT Specifies whether or not password encryption is to be used when logging into a 10.0+ SQL Server.REMAP="BO--Body"MOREINFO="NONE"DBSETLLABELED Specifies that login request labels will be sent when logging into a Secure SQL Server.REMAP="BO--Body"MOREINFO="NONE"dbsechandle Installs user functions to handle secure logins.REMAP="BO--Body"MOREINFO="NONE"dbsetsecurity Sets login request labels for use when logging into a Secure SQL Server.REMAP="BO--Body"MOREINFO="NONE"bcp_options Set bulk copy options, including BCPLABELED, the security label option.RENDERAS="SECT2"Miscellaneous Routines   REMAP="BO--Body"MOREINFO="NONE"dbpoll Checks if a server response has arrived for a DBPROCESS. REMAP="BO--Body"MOREINFO="NONE"dbsetavail Marks a DBPROCESS as being available for general use. REMAP="BO--Body"MOREINFO="NONE"dbsetmaxprocs Sets the maximum number of simultaneously open DBPROCESSes. REMAP="BO--Body"MOREINFO="NONE"dbsetuserdata Uses a DBPROCESS structure to save a pointer to user-allocated data. This routine, along with MOREINFO="NONE"dbgetuserdata, allows the application to associate user data with a particular DBPROCESS. One important use for these routines is to transfer information between a server message handler and the program code that triggered it. REMAP="BO--Body"MOREINFO="NONE"dbgetuserdata Returns a pointer to user-allocated data from a DBPROCESS structure. REMAP="BO--Body"MOREINFO="NONE"dbsetnull Defines substitution values to be used when binding null values. REMAP="BO--Body"MOREINFO="NONE"dbprtype Converts a server type token into a readable string. Tokens are returned by various routines such as MOREINFO="NONE"dbcoltype and MOREINFO="NONE"dbaltop. REMAP="BO--Body"MOREINFO="NONE"dbreadpage Reads in a page of binary data from SQL Server. REMAP="BO--Body"MOREINFO="NONE"dbwritepage Writes a page of binary data to SQL Server. RENDERAS="SECT2"Bulk Copy Special Library   ID="IN132675101"bcproutines for
ID="IN182477102"Routinesbcp
ID="IN1351982103"Bulk copy processing. See also bcp.
ID="IN141487104"Datahigh-speed loading of. See bcp.REMAP="BO--Body"The routines in this library allow an application to bulk copy data in and out of SQL Server. They provide a facility for high-speed loading of data into SQL Server from either files or program variables. They also allow you to copy data out of SQL Server into files, using a pre-defined format. The bulk copy routines are similar in function to the MOREINFO="NONE"bcp utility program, described in SYBASE SQL Server Utility Programs.REMAP="BO--Body"For more information on bulk copy, see Section 3, "Bulk Copy."REMAP="BO--Body"MOREINFO="NONE"BCP_SETL Sets the LOGINREC for bulk copy operations. REMAP="BO--Body"MOREINFO="NONE"bcp_init Initializes bulk copy. REMAP="BO--Body"MOREINFO="NONE"bcp_bind Binds data from a program variable to a SQL Server table. REMAP="BO--Body"MOREINFO="NONE"bcp_sendrow Sends a row of data from program variables to SQL Server. REMAP="BO--Body"MOREINFO="NONE"bcp_moretext Sends part of a text or image value to SQL Server. REMAP="BO--Body"MOREINFO="NONE"bcp_collen Sets the program variable data length for the current copy in. REMAP="BO--Body"MOREINFO="NONE"bcp_colptr Sets the program variable data address for the current copy in. REMAP="BO--Body"MOREINFO="NONE"bcp_batch Saves any preceding rows in SQL Server. REMAP="BO--Body"MOREINFO="NONE"bcp_done Ends a bulk copy from program variables into SQL Server. REMAP="BO--Body"MOREINFO="NONE"bcp_control Changes various control parameter default settings. REMAP="BO--Body"MOREINFO="NONE"bcp_columns Sets the total number of columns found in the host file. REMAP="BO--Body"MOREINFO="NONE"bcp_colfmt Specifies the format of a host file for bulk copy purposes. REMAP="BO--Body"MOREINFO="NONE"bcp_exec Executes a bulk copy of data between a database table and a host file. REMAP="BO--Body"MOREINFO="NONE"bcp_options Set bulk copy options.RENDERAS="SECT2"Two-Phase Commit Service Special Library   ID="IN181487105"Routinestwo-phase commit service
ID="IN1241487106"Two-phase commit serviceroutines forREMAP="BO--Body"The routines in this library allow an application to coordinate updates among two or more SQL Servers. REMAP="BO--Body"For more information on two-phase commit, see LINKEND="X74178"Chapter 4, "Two-Phase Commit Service."REMAP="BO--Body"MOREINFO="NONE"open_commit Establishes a connection with the commit service. REMAP="BO--Body"MOREINFO="NONE"start_xact Starts a distributed transaction using the commit service. REMAP="BO--Body"MOREINFO="NONE"build_xact_string Builds a name for a distributed transaction. REMAP="BO--Body"MOREINFO="NONE"commit_xact Marks a distributed transaction as being committed. REMAP="BO--Body"MOREINFO="NONE"abort_xact Marks a distributed transaction as being aborted. REMAP="BO--Body"MOREINFO="NONE"stat_xact Returns the current status of a distributed transaction. REMAP="BO--Body"MOREINFO="NONE"remove_xact Decrements the count of sites still active in the distributed transaction. REMAP="BO--Body"MOREINFO="NONE"scan_xact Prints commit service record for distributed transactions. REMAP="BO--Body"MOREINFO="NONE"close_commitID="IN181388107"Routines
 Ends a connection with the commit service. RENDERAS="SECT1"Summary of ChangesREMAP="BO--Body"This section contains information on changes to DB-Library/C since release 4.6.REMAP="BO--Body"Release 10.0 of DB-Library/C contains:MARK="BULL" REMAP="BU--Bullet"Support for the 10.0 server numeric and decimal datatypes.Routines to support SQL Server and Secure SQL Server security features.Cursor routines. For more information on cursors, see LINKEND="X76241"Appendix A, "Cursors."RENDERAS="SECT2"New DB-Library RoutinesREMAP="BO--Body"The following table lists new or newly-documented DB-Library routines:TOCENTRY="1"LBL="Table 1-2: "New DB-Library routinesCOLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="126*"COLNAME="C2" COLWIDTH="234*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Routine NameCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DescriptionVALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"bcp_optionsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Set bulk copy options.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"dbaltbind_psCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Bind a compute column to a program variable, 
with precision and scale support for numeric and 
decimal variables.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"dbbind_psCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Bind a regular result column to a program 
variable, with precision and scale support for 
numeric and decimal variables.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"dbconvert_psCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Convert data from one datatype to another, with 
precision and scale support for numeric and 
decimal types.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"dbcursorCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Inserts, updates, deletes, locks, or refreshes a 
particular row in the fetch buffer.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"dbcursorbindCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Registers the binding information on the cursor 
columns.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"dbcursorcloseCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Closes the cursor associated with the given 
handle, releasing all the data belonging to it.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"dbcursorcolinfoCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Returns column information for the specified 
column number in the open cursor.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"dbcursorfetchCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetches a block of rows into the program variables 
declared by the user in MOREINFO="NONE"dbcursorbind.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"dbcursorinfoCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Returns the number of columns and the number 
of rows in the keyset if the keyset hit the end of the 
result set.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"dbcursoropenCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Opens a cursor, specifying the scroll option, 
concurrency option, and the size of the fetch 
buffer (the number of rows retrieved with a single 
fetch).COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"dbsechandleCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Install user functions to handle secure logins.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"dbsetdefcharsetCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Sets the default character set for an application.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"dbsetdeflangCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Set the default language name for an application.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"DBSETLENCRYPTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Specify whether or not password encryption is to 
be used when logging into a 10.0+ SQL Server.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"DBSETLLABELEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Specify that login request labels will be sent when 
logging into a Secure SQL Server.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"dbsetsecurity COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Set login request labels for use when logging into 
a Secure SQL Server.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"dbsetversionCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Specify a DB-Library version level.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"dbtextsizeCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Return the number of text/image bytes that 
remain to be read for the current row.REMAP="BO--Body"NUMBER="2" ID="X29517"RoutinesREMAP="BO--Body"This chapter contains a manual page for each DB-Library routine.ID="X53831"db12hour
Determine whether the specified language uses 12-hour or 24-hour time. FORMAT="LINESPECIFIC"DBBOOL db12hour(dbproc, language)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS      *dbproc;FORMAT="LINESPECIFIC"char           *language;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. language - The name of the language of interest. ReturnsREMAP="BO--Body"TRUE if language uses 12-hour time, FALSE otherwise. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"db12hour returns TRUE if language uses 12-hour time, and FALSE if it uses 24-hour time. If language is NULL, dbproc's current language is signified. If both language and dbproc are NULL, then DB-Library's default language (for any future calls to MOREINFO="NONE"dbopen) is signified. MOREINFO="NONE"db12hour is useful when retrieving and manipulating DBDATETIME values via MOREINFO="NONE"dbsqlexec. When converting DBDATETIME values to character strings, MOREINFO="NONE"dbconvert and MOREINFO="NONE"dbbind always return the month component of the DBDATETIME value in the local language, but use the U.S. English date and time order (month-day-year, 12-hour time). MOREINFO="NONE"db12hour's return value informs the application that some further manipulation is necessary if 24-hour rather than 12-hour time is desired. The following code fragment illustrates the use of MOREINFO="NONE"db12hour: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"DBBOOL time_format; DBCHAR s_date[40];  /* ** Find out whether 12-hour or 24-hour time is** used.*/ time_format = db12hour(dbproc, "FRANCAIS");  /* Put a command into a command buffer */ dbcmd(dbproc, "select start_date from info_table");  /* Send the command to the SQL Server */ dbsqlexec(dbproc);  /* Process the command results */ dbresults(dbproc);  /* ** Bind column data (start_date) to the program  ** variable (s_date) */ dbbind(dbproc, 1, NTBSTRINGBIND, 0, s_date);  while (dbnextrow(dbproc) != NO_MORE_ROWS) {       /*       ** If we want 24-hour time, re-format       ** s_date accordingly.      */      if (time_format == TRUE)           format_24(s_date);        printf("Next start date: %s\n", s_date); } See AlsoREMAP="BO--Body"LINKEND="X53486"dbdateorder
, LINKEND="X83105"dbdayname
, LINKEND="X56030"dbmonthname
, LINKEND="X97776"dbsetopt
ID="IN438911110"db12hour
ID="IN4312881411"dbtwelvehour
 ID="IN437851712"dbadataID="X46780"dbadataID="IN4415851814"Compute columnsgetting data
ID="IN447822115"Columnscompute. See Compute columns.
ID="IN4414792416"Result columnscompute. See Compute columns.
Return a pointer to the data for a compute column. FORMAT="LINESPECIFIC"BYTE *dbadata(dbproc, computeid, column)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS         *dbproc;FORMAT="LINESPECIFIC"int               computeid;FORMAT="LINESPECIFIC"int               column;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and server. computeid - The id that identifies the particular compute row of interest. A SQL MOREINFO="NONE"select statement may have multiple MOREINFO="NONE"compute clauses, each of which returns a separate compute row. The computeid corresponding to the first MOREINFO="NONE"compute clause in a MOREINFO="NONE"select is 1. The computeid is returned by MOREINFO="NONE"dbnextrow or MOREINFO="NONE"dbgetrow. column ID="IN4415792419"Compute columnsorder returned
- The number of the column of interest.  The first column returned is number 1. Note that the order in which compute columns are returned is determined by the order of the corresponding columns in the select-list, not by the order in which the compute columns were originally specified. For example, in the following query the result of "sum(price)" is referenced by giving column a value of 1, not 2: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"select price, advance from titles     compute sum(advance), sum(price) REMAP="UN--Under"The relative order of compute columns in the select-list, rather than their absolute position, determines the value of column. For instance, given the following variation of the previous MOREINFO="NONE"select: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"select title_id, price, advance from titles     compute sum(advance), sum(price) REMAP="UN--Under"the column for "sum(price)" still has a value of 1 and not 2, because the "title_id" column in the select-list is not a compute column and therefore is ignored when determining the compute column's number. ReturnsREMAP="BO--Body"A BYTE pointer to the data for a particular column in a particular compute. Be sure to cast this pointer into the proper type. A BYTE pointer to NULL is returned if there is no such column or compute or if the data has a null value. REMAP="BO--Body"DB-Library allocates and frees the data space that the BYTE pointer points to. Do not overwrite this space. CommentsID="IN4412792422"Compute rowsgetting data for a columnMARK="BULL" REMAP="BU--Bullet"After each call to MOREINFO="NONE"dbnextrow, you can use this routine to return a pointer to the data for a particular column in a compute row.  The data is not null-terminated.  You can use MOREINFO="NONE"dbadlen to get the length of the data. ID="IN4415792423"Compute columnssumming or averagingWhen a column of integer data is summed or averaged, the server always returns a 4-byte integer, regardless of the size of the column. Therefore, be sure that the variable which is to contain the result from such a compute is declared as DBINT. Here's a short program fragment which illustrates the use of MOREINFO="NONE"dbadata: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc; int           rowinfo; DBINT         sum;  /* ** First, put the commands into the command** buffer */ dbcmd(dbproc, "select db_name(dbid), dbid, size     from sysusages"); dbcmd(dbproc, " order by dbid"); dbcmd(dbproc, " compute sum(size) by dbid");  /* ** Send the commands to SQL Server and start** execution */ dbsqlexec(dbproc); /* Process the command */ dbresults(dbproc);  /* Examine the results of the compute clause */ while((rowinfo = dbnextrow(dbproc)) !=     NO_MORE_ROWS) {      if (rowinfo == REG_ROW)           printf("regular row returned.\n");      else      {           /*           ** This row is the result of a compute          ** clause, and "rowinfo" is the computeid          ** of this compute clause.           */            sum = *(DBINT *)(dbadata(dbproc, rowinfo,               1));           printf("sum = %ld\n", sum);      } } ID="IN449713224"dbaltbinddbaltbindas alternate to dbadataalternate to dbadataThe function MOREINFO="NONE"dbaltbind automatically binds compute data to your program variables. It does a copy of the data, but is often easier to use than MOREINFO="NONE"dbadata. Furthermore, it includes a convenient type conversion capability. By means of this capability, the application can, among other things, easily add a null terminator to a result string or convert money and datetime data to printable strings. See AlsoREMAP="BO--Body"LINKEND="X76889"dbadlen
, LINKEND="X21854"dbaltbind
, LINKEND="X12040"dbaltlen
, LINKEND="X53350"dbalttype
, LINKEND="X71422"dbgetrow
, LINKEND="X10726"dbnextrow
, LINKEND="X55172"dbnumalts
ID="IN447683526"dbadata
 ID="IN447653827"dbadlenID="X76889"dbadlenID="IN4515653929"Compute columnsreturning data length of
Return the actual length of the data for a compute column. FORMAT="LINESPECIFIC"DBINT dbadlen(dbproc, computeid,
column)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS      *dbproc;FORMAT="LINESPECIFIC"int            computeid;FORMAT="LINESPECIFIC"int            column;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. computeid - The id that identifies the particular compute row of interest. A SQL MOREINFO="NONE"select statement may have multiple MOREINFO="NONE"compute clauses, each of which returns a separate compute row. The computeid corresponding to the first MOREINFO="NONE"compute clause in a MOREINFO="NONE"select is 1. The computeid is returned by MOREINFO="NONE"dbnextrow or MOREINFO="NONE"dbgetrow. column - The number of the column of interest.  The first column is number 1. ReturnsREMAP="BO--Body"The length, in bytes, of the data for a particular compute column. If there is no such column or MOREINFO="NONE"compute clause, MOREINFO="NONE"dbadlen returns -1. If the data has a null value, MOREINFO="NONE"dbadlen returns 0. CommentsMARK="BULL" REMAP="BU--Bullet"This routine returns the actual length of the data for a particular compute column. Use the MOREINFO="NONE"dbaltlen routine to determine the maximum possible length for the data. Use MOREINFO="NONE"dbadata to get a pointer to the data. Here's a program fragment that illustrates the use of MOREINFO="NONE"dbadlen: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc; char          biggest_name[MAXNAME+1]; int           namelen; int           rowinfo;  /* put the command into the command buffer */ dbcmd(dbproc, "select name from sysobjects"); dbcmd(dbproc, " order by name"); dbcmd(dbproc, " compute max(name)");  /* ** Send the command to SQL Server and start** execution.*/ dbsqlexec(dbproc);  /* process the command */ dbresults(dbproc);  /* examine each row returned by the command */ while ((rowinfo = dbnextrow(dbproc)) !=    NO_MORE_ROWS) {     if (rowinfo == REG_ROW)         printf("regular row returned.\n");     else    {         /*         ** This row is the result of a compute        ** clause, and "rowinfo" is the computeid        ** of this compute clause.         */          namelen = dbadlen(dbproc, rowinfo, 1);         strncpy(biggest_name,             (char *)dbadata(dbproc, rowinfo, 1),             namelen);          /*         ** Data pointed to by dbadata() is not         ** null-terminated.         */         biggest_name[namelen] = '\0';          printf("biggest name = %s\n",            biggest_name);     } } See AlsoREMAP="BO--Body"LINKEND="X46780"dbadata
, LINKEND="X12040"dbaltlen
, LINKEND="X53350"dbalttype
, LINKEND="X71422"dbgetrow
, LINKEND="X10726"dbnextrow
, LINKEND="X55172"dbnumalts
ID="IN457624235"dbadlen
 ID="IN459594536"dbaltbindID="X21854"dbaltbindID="IN4615594638"Compute columnsbinding to program variables
ID="IN469594639"Datatypesbinding compute columns to
Bind a compute column to a program variable. FORMAT="LINESPECIFIC"RETCODE dbaltbind(dbproc, computeid, column,
vartype,                  varlen, varaddr)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS          *dbproc;FORMAT="LINESPECIFIC"int                computeid;FORMAT="LINESPECIFIC"int                column;FORMAT="LINESPECIFIC"int                vartype;FORMAT="LINESPECIFIC"DBINT              varlen;FORMAT="LINESPECIFIC"BYTE               *varaddr;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. computeid - The id that identifies the particular compute row of interest. A MOREINFO="NONE"select statement may have multiple MOREINFO="NONE"compute clauses, each of which returns a separate compute row. The computeid corresponding to the first MOREINFO="NONE"compute clause in a MOREINFO="NONE"select is 1. column - The column number of the row data that is to be copied to a program variable.  The first column is column number 1. Note that the order in which compute columns are returned is determined by the order of the corresponding columns in the select-list, not by the order in which the compute columns were originally specified. For example, in the following query the result of "sum(price)" is referenced by giving column a value of 1, not 2: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"select price, advance from titles     compute sum(advance), sum(price) REMAP="UN--Under"The relative order of compute columns in the select-list, rather than their absolute position, determines the value of column. For instance, given the following variation of the previous MOREINFO="NONE"select: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"select title_id, price, advance from titles    compute sum(advance), sum(price) REMAP="UN--Under"the column for "sum(price)" still has a value of 1 and not 2, because the "title_id" column in the select-list is not a compute column and therefore is ignored when determining the compute column's number. vartype - This describes the datatype of the binding. It must correspond to the datatype of the program variable that will receive the copy of the data from the DBPROCESS. The table below shows the correspondence between vartypes and program variable types. ID="IN469574842"Datatypesconversions supported:by dbaltbindREMAP="UN--Under"MOREINFO="NONE"dbaltbind supports a wide range of type conversions, so the vartype can be different from the type returned by the SQL query. For instance, a SYBMONEY result may be bound to a DBFLT8 program variable via FLT8BIND, and the appropriate data conversion will happen automatically. For a list of the data conversions provided by DB-Library, see the manual page for MOREINFO="NONE"dbwillconvert. REMAP="UN--Under"For a list of the typedefs used by DB-Library, see the manual page for MOREINFO="NONE"types. REMAP="UN--Under"Here is a list of the legal vartypes recognized by MOREINFO="NONE"dbaltbind, along with the server and program variable types that each one refers to: TOCENTRY="1"LBL="Table 2-1: "Bind types (MOREINFO="NONE"dbaltbind) COLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="127*"COLNAME="C2" COLWIDTH="116*"COLNAME="C3" COLWIDTH="115*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"VartypeCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Program variable typeCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Server type VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CHARBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBCHAR COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"STRINGBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBCHAR COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NTBSTRINGBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBCHAR COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"VARYCHARBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBVARYCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBCHAR COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"BINARYBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBBINARYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBBINARY COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"VARYBINBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBVARYBINCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBBINARY COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"TINYBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBTINYINTCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBINT1COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SMALLBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBSMALLINTCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBINT2COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"INTBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBINTCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBINT4COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"FLT8BINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBFLT8COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBFLT8COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"REALBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBREALCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBREAL COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NUMERICBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBNUMERICCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBNUMERICCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DECIMALBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDECIMALCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBDECIMALCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"BITBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBBITCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBBITCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DATETIMEBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATETIMECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBDATETIMECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SMALLDATETIMEBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATETIME4COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBDATETIME4 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MONEYBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBMONEYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBMONEYCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SMALLMONEYBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBMONEY4COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBMONEY4 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"BOUNDARYBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBBOUNDARYCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SENSITIVITYBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBSENSITIVITYREMAP="UN--Under"Since SYBTEXT and SYBIMAGE data are never returned through a compute row, those datatypes are not listed above. REMAP="UN--Under"Note that the server type in the table above is listed merely for your information.  The vartype you specify does not necessarily have to correspond to a particular server type, because, as mentioned earlier, MOREINFO="NONE"dbaltbind will convert server data into the specified vartype. MOREINFO="NONE"dbaltbind does not offer precision and scale support for numeric and decimal types. When binding to numeric or decimal variables, MOREINFO="NONE"dbaltbind uses a default precision and scale of 18 and 0, respectively. To specify a different precision and scale, an application can use MOREINFO="NONE"dbaltbind_ps.REMAP="UN--Under"The table below shows that four representations for character data are available. They differ according to whether the data is blank-padded or null-terminated: TOCENTRY="1"LBL="Table 2-2: "Representations for character data.COLS="4" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="103*"COLNAME="C2" COLWIDTH="95*"COLNAME="C3" COLWIDTH="82*"COLNAME="C4" COLWIDTH="77*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"VartypeCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Program typeCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"PaddingCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Terminator VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CHARBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"blanksCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"none COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"STRINGBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"blanksCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"\0 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NTBSTRINGBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"noneCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"\0 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"VARYCHARBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBVARYCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"noneCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"none COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"BOUNDARYBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"noneCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"\0COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SENSITIVITYBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"noneCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"\0REMAP="UN--Under"Note that the "\0" in the table above is the null terminator character. REMAP="UN--Under"If overflow occurs when converting integer or float data to a character binding type, the first character of the resulting value will contain an asterisk ("*") to indicate the error. REMAP="UN--Under"Binary data may be stored in two different ways: TOCENTRY="1"LBL="Table 2-3: "Representations for binary data.COLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="136*"COLNAME="C2" COLWIDTH="141*"COLNAME="C3" COLWIDTH="82*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"VartypeCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Program typeCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Padding VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"BINARYBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBBINARYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"nullsCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"VARYBINBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBVARBINARYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"noneREMAP="UN--Under"When a column of integer data is summed or averaged, the server always returns a 4-byte integer, regardless of the size of the column. Therefore, be sure that the variable which is to contain the result from such a compute is declared as DBINT and that the vartype of the binding is INTBIND. varlen - The length of the program variable in bytes. REMAP="UN--Under"For fixed-length vartypes, such as MONEYBIND or FLT8BIND, this length is ignored. REMAP="UN--Under"For character and binary types, varlen must describe the total length of the available destination buffer space, including any space that may be required for special terminating bytes, such as a null terminator. If varlen is 0, the total number of bytes available will be copied into the program variable. (For char and binary server data, the total number of bytes available is equal to the defined length of the database column, including any blank padding. For varchar and varbinary data, the total number of bytes available is equal to the actual data contained in the column.) Therefore, if you are sure that your program variable is large enough to handle the results, you can just set varlen to 0. varaddr - The address of the program variable to which the data will be copied. ReturnsREMAP="BO--Body"SUCCEED or FAIL. MOREINFO="NONE"dbaltbind returns FAIL if the column number isn't valid, if the data conversion specified by vartype isn't legal, or if varaddr is NULL. CommentsMARK="BULL" REMAP="BU--Bullet"This routine directs DB-Library to copy compute column data returned by the server into a program variable. (A compute column results from the MOREINFO="NONE"compute clause of a Transact-SQL MOREINFO="NONE"select statement.) When each new row containing compute data is read via MOREINFO="NONE"dbnextrow or MOREINFO="NONE"dbgetrow, the data from the designated column in that compute row is copied into the program variable with the address varaddr.  There must be a separate MOREINFO="NONE"dbaltbind call for each compute column that is to be copied. It is not necessary to bind every compute column to a program variable. The server can return two types of rows: regular rows containing data from columns designated by a MOREINFO="NONE"select statement's select-list, and compute rows resulting from the MOREINFO="NONE"compute clause. MOREINFO="NONE"dbaltbind binds data from compute rows. Use MOREINFO="NONE"dbbind for binding data from regular rows. You must make the calls to MOREINFO="NONE"dbaltbind after a call to MOREINFO="NONE"dbresults and before the first call to MOREINFO="NONE"dbnextrow. The typical sequence of calls is: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"DBCHAR     name[20]; DBINT      namecount;  /* read the query into the command buffer */ dbcmd(dbproc, "select name from emp compute    count(name)");  /* send the query to SQL Server */ dbsqlexec(dbproc);  /* get ready to process the query results */ dbresults(dbproc);  /* bind the regular row data (name) */ dbbind(dbproc, 1, STRINGBIND, (DBINT) 0, name);  /* bind the compute column data (count of name) */ dbaltbind(dbproc, 1, 1, INTBIND, (DBINT) 0,     (BYTE *) &namecount);  /* now process each row */ while (dbnextrow(dbproc) != NO_MORE_ROWS) {     C-code to print or process row data } ID="IN467495645"dbadatadbadataas alternate to dbaltbindalternate to dbaltbind
MOREINFO="NONE"dbaltbind incurs a little overhead because it causes the data to be copied into a program variable. To avoid this copying, you can use the MOREINFO="NONE"dbadata routine to directly access the returned data. You can only bind a result column to a single program variable. If you bind a result column to multiple variables, only the last binding takes effect. Since the server can return null values, DB-Library provides a set of default values, one for each datatype, that it will automatically substitute when binding null values. The MOREINFO="NONE"dbsetnull function allows you to explicitly set your own null substitution values. (See the manual page for the MOREINFO="NONE"dbsetnull function for a list of the default substitution values.) See AlsoREMAP="BO--Body"LINKEND="X46780"dbadata
, LINKEND="X32323"dbaltbind_ps
, LINKEND="X63819"dbanullbind
, LINKEND="X14206"dbbind
, LINKEND="X81674"dbbind_ps
, LINKEND="X76814"dbconvert
, LINKEND="X80440"dbconvert_ps
, LINKEND="X56339"dbnullbind
, LINKEND="X70360"dbsetnull
, LINKEND="X17556"dbwillconvert
, LINKEND="X91146"types
ID="IN469465947"dbaltbind
 ID="IN4612436248"dbaltbind_psID="X32323"dbaltbind_psID="IN4715436350"Compute columnsbinding to program variables
ID="IN479436351"Datatypesbinding compute columns to
Bind a compute column to a program variable, with precision and scale support for numeric and decimal variables.FORMAT="LINESPECIFIC"RETCODE dbaltbind_ps(dbproc, computeid,
column,               vartype, varlen, varaddr,FORMAT="LINESPECIFIC"typeinfo)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS      *dbproc;FORMAT="LINESPECIFIC"int            computeid;FORMAT="LINESPECIFIC"int            column;FORMAT="LINESPECIFIC"int            vartype;FORMAT="LINESPECIFIC"DBINT          varlen;FORMAT="LINESPECIFIC"BYTE           *varaddr;FORMAT="LINESPECIFIC"DBTYPEINFO     *typeinfo;ParametersMOREINFO="NONE"dbaltbind_ps's parameters are identical to MOREINFO="NONE"dbaltbind's, except thatMOREINFO="NONE" dbaltbind_ps has the additional parameter typeinfo, which contains information about precision and scale for numeric or decimal variables.REMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. computeid - The id that identifies the particular compute row of interest. A MOREINFO="NONE"select statement may have multiple MOREINFO="NONE"compute clauses, each of which returns a separate compute row. The computeid corresponding to the first MOREINFO="NONE"compute clause in a MOREINFO="NONE"select is 1. column - The column number of the row data that is to be copied to a program variable.  The first column is column number 1. Note that the order in which compute columns are returned is determined by the order of the corresponding columns in the select-list, not by the order in which the compute columns were originally specified. For example, in the following query the result of "sum(price)" is referenced by giving column a value of 1, not 2: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"select price, advance from titles     compute sum(advance), sum(price) REMAP="UN--Under"The relative order of compute columns in the select-list, rather than their absolute position, determines the value of column. For instance, given the following variation of the previous MOREINFO="NONE"select: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"select title_id, price, advance from titles      compute sum(advance), sum(price) REMAP="UN--Under"the column for "sum(price)" still has a value of 1 and not 2, because the "title_id" column in the select-list is not a compute column and therefore is ignored when determining the compute column's number. vartype - This describes the datatype of the binding. It must correspond to the datatype of the program variable that will receive the copy of the data from the DBPROCESS. The table below shows the correspondence between vartypes and program variable types. REMAP="UN--Under"ID="IN479416554"Datatypesconversions supported:by dbaltbind_ps
MOREINFO="NONE"dbaltbind_ps supports a wide range of type conversions, so the vartype can be different from the type returned by the SQL query. For instance, a SYBMONEY result may be bound to a DBFLT8 program variable via FLT8BIND, and the appropriate data conversion will happen automatically. For a list of the data conversions provided by DB-Library, see the manual page for MOREINFO="NONE"dbwillconvert. REMAP="UN--Under"For a list of the typedefs used by DB-Library, see the manual page for MOREINFO="NONE"types. REMAP="UN--Under"Here is a list of the legal vartypes recognized by MOREINFO="NONE"dbaltbind_ps, along with the server and program variable types that each one refers to: TOCENTRY="1"LBL="Table 2-4: "Bind types (MOREINFO="NONE"dbaltbind_ps) COLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="127*"COLNAME="C2" COLWIDTH="116*"COLNAME="C3" COLWIDTH="115*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"VartypeCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Program variable typeCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Server type VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CHARBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBCHAR COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"STRINGBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBCHAR COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NTBSTRINGBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBCHAR COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"VARYCHARBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBVARYCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBCHAR COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"BINARYBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBBINARYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBBINARY COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"VARYBINBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBVARYBINCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBBINARY COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"TINYBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBTINYINTCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBINT1COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SMALLBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBSMALLINTCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBINT2COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"INTBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBINTCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBINT4COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"FLT8BINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBFLT8COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBFLT8COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"REALBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBREALCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBREAL COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NUMERICBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBNUMERICCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBNUMERICCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DECIMALBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDECIMALCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBDECIMALCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"BITBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBBITCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBBITCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DATETIMEBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATETIMECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBDATETIMECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SMALLDATETIMEBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATETIME4COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBDATETIME4 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MONEYBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBMONEYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBMONEYCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SMALLMONEYBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBMONEY4COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBMONEY4 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"BOUNDARYBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBBOUNDARYCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SENSITIVITYBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBSENSITIVITYREMAP="UN--Under"Since SYBTEXT and SYBIMAGE data are never returned through a compute row, those datatypes are not listed above. REMAP="UN--Under"Note that the server type in the table above is listed merely for your information.  The vartype you specify does not necessarily have to correspond to a particular server type, because, as mentioned earlier, MOREINFO="NONE"dbaltbind_ps will convert server data into the specified vartype. REMAP="UN--Under"The table below shows that four representations for character data are available. They differ according to whether the data is blank-padded or null-terminated: TOCENTRY="1"LBL="Table 2-5: "Representations for character dataCOLS="4" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="103*"COLNAME="C2" COLWIDTH="95*"COLNAME="C3" COLWIDTH="82*"COLNAME="C4" COLWIDTH="77*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"VartypeCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Program typeCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"PaddingCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Terminator VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CHARBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"blanksCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"none COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"STRINGBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"blanksCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"\0 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NTBSTRINGBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"noneCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"\0 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"VARYCHARBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBVARYCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"noneCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"none COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"BOUNDARYBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"noneCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"\0COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SENSITIVITYBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"noneCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"\0REMAP="UN--Under"Note that the "\0" in the table above is the null terminator character. REMAP="UN--Under"If overflow occurs when converting integer or float data to a character binding type, the first character of the resulting value will contain an asterisk ("*") to indicate the error. REMAP="UN--Under"Binary data may be stored in two different ways: TOCENTRY="1"LBL="Table 2-6: "Representations for binary data.COLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="136*"COLNAME="C2" COLWIDTH="141*"COLNAME="C3" COLWIDTH="82*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"VartypeCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Program typeCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Padding VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"BINARYBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBBINARYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"nullsCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"VARYBINBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBVARBINARYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"noneREMAP="UN--Under"When a column of integer data is summed or averaged, the server always returns a 4-byte integer, regardless of the size of the column. Therefore, be sure that the variable which is to contain the result from such a compute is declared as DBINT and that the vartype of the binding is INTBIND. varlen - The length of the program variable in bytes. REMAP="UN--Under"For fixed-length vartypes, such as MONEYBIND or FLT8BIND, this length is ignored. REMAP="UN--Under"For character and binary types, varlen must describe the total length of the available destination buffer space, including any space that may be required for special terminating bytes, such as a null terminator. If varlen is 0, the total number of bytes available will be copied into the program variable. (For char and binary server data, the total number of bytes available is equal to the defined length of the database column, including any blank padding. For varchar and varbinary data, the total number of bytes available is equal to the actual data contained in the column.) Therefore, if you are sure that your program variable is large enough to handle the results, you can just set varlen to 0. varaddr - The address of the program variable to which the data will be copied. typeinfo - A pointer to a DBTYPEINFO structure containing information about the precision and scale of decimal or numeric variables. An application sets a DBTYPEINFO structure with values for precision and scale before calling MOREINFO="NONE"dbaltbind_ps to bind columns to decimal or numeric variables.REMAP="UN--Under"If typeinfo is NULL:MARK="DASH" REMAP="BS--BulletSub"If the result column is of type numeric or decimal, MOREINFO="NONE"dbaltbind_ps picks up precision and scale values from the result column.If the result column is not numeric or decimal, MOREINFO="NONE"dbaltbind_ps uses a default precision of 18 and a default scale of 0.REMAP="UN--Under"If vartype is not DECIMALBIND or NUMERICBIND, typeinfo is ignored.REMAP="UN--Under"A DBTYPEINFO structure is defined as follows:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"typedef struct typeinfo {     DBINT   precision;     DBINT   scale;} DBTYPEINFO;REMAP="UN--Under"Legal values for precision are from 1 to 77. Legal values for scale are from 0 to 77. scale must be less than or equal to precision.ReturnsREMAP="BO--Body"SUCCEED or FAIL. MOREINFO="NONE"dbaltbind_ps returns FAIL if the column number isn't valid, if the data conversion specified by vartype isn't legal, or if varaddr is NULL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbaltbind_ps is the equivalent of MOREINFO="NONE"dbaltbind, except that MOREINFO="NONE"dbaltbind_ps provides precision and scale support for numeric and decimal datatypes, which MOREINFO="NONE"dbaltbind does not. Calling MOREINFO="NONE"dbaltbind is equivalent to calling MOREINFO="NONE"dbaltbind_ps with typeinfo as NULL.MOREINFO="NONE"dbaltbind_ps directs DB-Library to copy compute column data returned by the server into a program variable. (A compute column results from the MOREINFO="NONE"compute clause of a Transact-SQL MOREINFO="NONE"select statement.) When each new row containing compute data is read via MOREINFO="NONE"dbnextrow or MOREINFO="NONE"dbgetrow, the data from the designated column in that compute row is copied into the program variable with the address varaddr.  There must be a separate MOREINFO="NONE"dbaltbind_ps call for each compute column that is to be copied. It is not necessary to bind every compute column to a program variable. The server can return two types of rows: regular rows containing data from columns designated by a MOREINFO="NONE"select statement's select-list, and compute rows resulting from the MOREINFO="NONE"compute clause. MOREINFO="NONE"dbaltbind_ps binds data from compute rows. Use MOREINFO="NONE"dbbind_ps for binding data from regular rows. You must make the calls to MOREINFO="NONE"dbaltbind_ps after a call to MOREINFO="NONE"dbresults and before the first call to MOREINFO="NONE"dbnextrow. ID="IN477337357"dbadatadbadataas alternate to dbaltbindalternate to dbaltbind_ps
MOREINFO="NONE"dbaltbind_ps incurs a little overhead because it causes the data to be copied into a program variable. To avoid this copying, you can use the MOREINFO="NONE"dbadata routine to directly access the returned data. You can only bind a result column to a single program variable. If you bind a result column to multiple variables, only the last binding takes effect. Since the server can return null values, DB-Library provides a set of default values, one for each datatype, that it will automatically substitute when binding null values. The MOREINFO="NONE"dbsetnull function allows you to explicitly set your own null substitution values. (See the manual page for the MOREINFO="NONE"dbsetnull function for a list of the default substitution values.) See AlsoREMAP="BO--Body"LINKEND="X69467"dbdata
, LINKEND="X21854"dbaltbind
, LINKEND="X63819"dbanullbind
, LINKEND="X14206"dbbind
, LINKEND="X81674"dbbind_ps
, LINKEND="X76814"dbconvert
, LINKEND="X80440"dbconvert_ps
, LINKEND="X56339"dbnullbind
, LINKEND="X70360"dbsetnull
, LINKEND="X17556"dbwillconvert
, LINKEND="X91146"types
ID="IN4712307659"dbaltbind_ps
 ID="IN4710277960"dbaltcoliddbaltcolidID="IN4815258262"Compute columnsreturning select-list id
Return the column id for a compute column. FORMAT="LINESPECIFIC"int dbaltcolid(dbproc, computeid,
column)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS      *dbproc;FORMAT="LINESPECIFIC"int            computeid;FORMAT="LINESPECIFIC"int            column;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. computeid - The id that identifies the particular compute row of interest. A SQL MOREINFO="NONE"select statement may have multiple MOREINFO="NONE"compute clauses, each of which returns a separate compute row. The computeid corresponding to the first MOREINFO="NONE"compute clause in a MOREINFO="NONE"select is 1. The computeid is returned by MOREINFO="NONE"dbnextrow or MOREINFO="NONE"dbgetrow. column - The number of the compute column of interest.  The first column in a select-list is 1. ReturnsREMAP="BO--Body"The select-list id for the compute column. The first column in a select-list is 1.  If either the computeid or the column are invalid, MOREINFO="NONE"dbaltcolid returns -1. CommentsMARK="BULL" REMAP="BU--Bullet"This routine returns the select-list id for a compute column. For example, given the SQL statement: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"select dept, name from employee      order by dept, name      compute count(name) by dept REMAP="UN--Under"the call "dbaltcolid(dbproc, 1, 1)" will return 2, since name is the second column in the select-list. See AlsoREMAP="BO--Body"LINKEND="X46780"dbadata
, LINKEND="X76889"dbadlen
, LINKEND="X12040"dbaltlen
, LINKEND="X71422"dbgetrow
, LINKEND="X10726"dbnextrow
, LINKEND="X55172"dbnumalts
, LINKEND="X77266"dbprtype
ID="IN4810228568"dbaltcolid
 ID="IN488198869"dbaltlenID="X12040"dbaltlenID="IN4915198971"Compute columnsreturning maximum data length of
Return the maximum length of the data for a particular compute column. FORMAT="LINESPECIFIC"DBINT dbaltlen(dbproc, computeid,
column)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS       *dbproc;FORMAT="LINESPECIFIC"int             computeid;FORMAT="LINESPECIFIC"int             column;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. computeid - The id that identifies the particular compute row of interest. A SQL MOREINFO="NONE"select statement may have multiple MOREINFO="NONE"compute clauses, each of which returns a separate compute row. The computeid corresponding to the first MOREINFO="NONE"compute clause in a MOREINFO="NONE"select is 1. The computeid is returned by MOREINFO="NONE"dbnextrow or MOREINFO="NONE"dbgetrow. column - The number of the column of interest.  The first column is number 1. ReturnsREMAP="BO--Body"The maximum length, in bytes, possible for the data in a particular compute column.  -1 is returned if there is no such column or MOREINFO="NONE"compute clause. CommentsMARK="BULL" REMAP="BU--Bullet"This routine returns the maximum length for a column in a compute row. In the case of variable length data, this is not necessarily the actual length of the data, but rather the maximum length. For the actual data length, use MOREINFO="NONE"dbadlen. REMAP="UN--Under"For example, given the SQL statement: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"select dept, name from employee      order by dept, name      compute count(name) by dept REMAP="UN--Under"the call "dbaltlen(dbproc, 1, 1)" returns 4 because counts are of SYBINT4 type, which is 4 bytes long. See AlsoREMAP="BO--Body"LINKEND="X46780"dbadata
, LINKEND="X76889"dbadlen
, LINKEND="X53350"dbalttype
, LINKEND="X71422"dbgetrow
, LINKEND="X10726"dbnextrow
, LINKEND="X55172"dbnumalts
ID="IN498169277"dbaltlen
 ID="IN497139578"dbaltopID="X81910"dbaltopID="IN5015139680"Compute columnsreturning type of row aggregate
ID="IN5019139681"Aggregate operatorsreturning for a compute column
ID="IN5014139682"Row aggregatesreturning for a compute column
Return the type of aggregate operator for a particular compute column. FORMAT="LINESPECIFIC"int dbaltop(dbproc, computeid,
column)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS      *dbproc;FORMAT="LINESPECIFIC"int            computeid;FORMAT="LINESPECIFIC"int            column;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. computeid - The id that identifies the particular compute row of interest. A SQL MOREINFO="NONE"select statement may have multiple MOREINFO="NONE"compute clauses, each of which returns a separate compute row. The computeid corresponding to the first MOREINFO="NONE"compute clause in a MOREINFO="NONE"select is 1. The computeid is returned by MOREINFO="NONE"dbnextrow or MOREINFO="NONE"dbgetrow. column - The number of the column of interest.  The first column is number 1. ReturnsREMAP="BO--Body"A token value for the type of the compute column's aggregate operator. In case of error, MOREINFO="NONE"dbaltop returns -1. CommentsMARK="BULL" REMAP="BU--Bullet"This routine returns the type of aggregate operator for a particular column in a compute. For example, given the SQL statement: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"select dept, name from employee     order by dept, name     compute count(name) by dept REMAP="UN--Under"the call "dbaltop(dbproc, 1, 1)" will return the token value for MOREINFO="NONE"count since the first aggregate operator in the first compute is a MOREINFO="NONE"count. You can convert the token value to a readable token string with MOREINFO="NONE"dbprtype. See the MOREINFO="NONE"dbprtype manual page for a list of all token values and their equivalent token strings. See AlsoREMAP="BO--Body"LINKEND="X46780"dbadata
, LINKEND="X76889"dbadlen
, LINKEND="X12040"dbaltlen
, LINKEND="X10726"dbnextrow
, LINKEND="X55172"dbnumalts
, LINKEND="X77266"dbprtype
ID="IN507109988"dbaltop
 ID="IN509710289"dbalttypeID="X53350"dbalttypeID="IN5115710391"Compute columnsreturning server datatype for
ID="IN519710392"DatatypesDatatypesserver:for compute columnsserver:compute columns
ID="IN519710393"Datatypesreturning for compute columns
Return the datatype for a compute column. FORMAT="LINESPECIFIC"int dbalttype(dbproc, computeid, column)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS        *dbproc;FORMAT="LINESPECIFIC"int              computeid;FORMAT="LINESPECIFIC"int              column;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. computeid - The id that identifies the particular compute row of interest. A SQL MOREINFO="NONE"select statement may have multiple MOREINFO="NONE"compute clauses, each of which returns a separate compute row. The computeid corresponding to the first MOREINFO="NONE"compute clause in a MOREINFO="NONE"select is 1. The computeid is returned by MOREINFO="NONE"dbnextrow or MOREINFO="NONE"dbgetrow. column - The number of the column of interest.  The first column is number 1. ReturnsREMAP="BO--Body"A token value for the datatype for a particular compute column. REMAP="BO--Body"In a few cases, the token value returned by this routine may not correspond exactly with the column's server datatype: MARK="BULL" REMAP="BU--Bullet"SYBVARCHAR is returned as SYBCHAR. SYBVARBINARY is returned as SYBBINARY. SYBDATETIMN is returned as SYBDATETIME. SYBMONEYN is returned as SYBMONEY. SYBFLTN is returned as SYBFLT8. SYBINTN is returned as SYBINT1, SYBINT2, or SYBINT4, depending on the actual type of the SYBINTN. REMAP="BO--Body"MOREINFO="NONE"dbalttype returns -1 if either the computeid or the column are invalid. CommentsMARK="BULL" REMAP="BU--Bullet"This routine returns the datatype for a compute column. For a list of server datatypes, see the manual page for MOREINFO="NONE"types. MOREINFO="NONE"dbalttype actually returns an integer token value for the datatype (SYBCHAR, SYBFLT8, etc.). To convert the token value into a readable token string, use MOREINFO="NONE"dbprtype. See the MOREINFO="NONE"dbprtype manual page for a list of all token values and their equivalent token strings. For example, given the SQL statement: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"select dept, name from employee     order by dept, name     compute count(name) by dept REMAP="UN--Under"the call "dbalttype(dbproc, 1, 1)" will return the token value SYBINT4, because counts are of SYBINT4 type. MOREINFO="NONE"dbprtype will convert SYBINT4 into the readable token string "int". See AlsoREMAP="BO--Body"LINKEND="X46780"dbadata
, LINKEND="X76889"dbadlen
, LINKEND="X12040"dbaltlen
, LINKEND="X10726"dbnextrow
, LINKEND="X55172"dbnumalts
, LINKEND="X77266"dbprtype
, LINKEND="X91146"types
ID="IN519410699"dbalttype
 ID="IN51101109100"dbaltutypeID="X18128"dbaltutypeID="IN52151110102"Compute columnsreturning user-defined datatypes for
ID="IN5291110103"Datatypesreturning for compute columns
ID="IN5291110104"DatatypesDatatypesuser-defined:for compute columnsuser-defined:compute columns
ID="IN52221110105"User-defined datatypesreturning for a compute column
Return the user-defined datatype for a compute column. FORMAT="LINESPECIFIC"DBINT dbaltutype(dbproc, computeid,column)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"int          computeid;FORMAT="LINESPECIFIC"int          column;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the  information that DB-Library uses to manage communications and data between the front end and server. computeid - The id that identifies the particular compute row of interest. A SQL MOREINFO="NONE"select statement may have multiple MOREINFO="NONE"compute clauses, each of which returns a separate compute row. The computeid corresponding to the first MOREINFO="NONE"compute clause in a MOREINFO="NONE"select is 1. The computeid is returned by MOREINFO="NONE"dbnextrow or MOREINFO="NONE"dbgetrow. column - The number of the column of interest. The first column is number 1. ReturnsREMAP="BO--Body"The user-defined datatype of the specified compute column on success; a negative integer on error. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbaltutype returns the user-defined datatype for a compute column. For a description of how to add user-defined datatypes to the server databases or Server-Library programs, see the SQL Server Reference Manual or the Open Server Server-Library Reference Manual. MOREINFO="NONE"dbaltutype is defined as type DBINT, since both the DB-Library datatype DBINT and user-defined datatypes are 32 bits long. See AlsoREMAP="BO--Body"LINKEND="X53350"dbalttype
, LINKEND="X43711"dbcolutype
ID="IN5210-2113111"dbaltutype
 ID="IN5211-5116112"dbanullbindID="X63819"dbanullbindID="IN5315-5117114"Compute columnsassociating with indicator variables
Associate an indicator variable with a compute-row column. FORMAT="LINESPECIFIC"RETCODE dbanullbind(dbproc,computeid,column,                    indicator)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"int          computeid;FORMAT="LINESPECIFIC"int          column;FORMAT="LINESPECIFIC"DBINT        *indicator;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. computeid - The compute row of interest. A MOREINFO="NONE"select statement may have multiple MOREINFO="NONE"compute clauses, each of which returns a separate compute row. The computeid corresponding to the first MOREINFO="NONE"compute clause in a MOREINFO="NONE"select is 1. column - The number of the column that is to be associated with the indicator variable. indicator - A pointer to the indicator variable. indicator is just the pointer to the indicator variable. It's the variable itself which is set. ReturnsREMAP="BO--Body"SUCCEED or FAIL. MOREINFO="NONE"dbanullbind returns FAIL if computeid or column are invalid. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbanullbind associates a compute column with an indicator variable. The indicator variable indicates whether a particular compute row column has been converted and copied to a program variable successfully or unsuccessfully, or whether it is null. The indicator variable is set when compute rows are processed via MOREINFO="NONE"dbnextrow. The possible values are: -1 if the column is NULL. The full length of the column's data, in bytes if the column was bound to a program variable via MOREINFO="NONE"dbaltbind, the binding did not specify any data conversions, and the bound data was truncated because the program variable was too small to hold the column's data. 0 if the column was bound and copied to a program variable successfully. Detection of character string truncation is implemented only for CHARBIND and VARYCHARBIND. See AlsoREMAP="BO--Body"LINKEND="X46780"dbadata
, LINKEND="X76889"dbadlen
, LINKEND="X21854"dbaltbind
, LINKEND="X10726"dbnextrow
, LINKEND="X56339"dbnullbind
ID="IN5311-8120120"dbanullbind
 ID="IN536-11123121"dbbindID="X14206"dbbindID="IN5415-11124123"Regular columnsbinding to program variables
ID="IN549-11124124"Datatypesbinding regular columns to
ID="IN5438-11124125"Bind result column to program variable
ID="IN547-14127126"Columnsregular. See Regular columns.
ID="IN5414-17130127"Result columnsregular. See Regular columns.
Bind a regular result column to a program variable. FORMAT="LINESPECIFIC"MOREINFO="NONE"RETCODE dbbind(dbproc, column, vartype, varlen, varaddr)FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"int           column;FORMAT="LINESPECIFIC"int           vartype;FORMAT="LINESPECIFIC"DBINT         varlen;FORMAT="LINESPECIFIC"BYTE          *varaddr;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. column - The column number of the row data that is to be copied to a program variable.  The first column is column number 1. vartype - This describes the datatype of the binding. It must correspond to the datatype of the program variable that will receive the copy of the data from the DBPROCESS. The table below shows the correspondence between vartypes and program variable types. REMAP="UN--Under"MOREINFO="NONE"dbbind supports a wide range of type conversions, so the vartype can be different from the type returned by the SQL query. For instance, a SYBMONEY result may be bound to a DBFLT8 program variable via FLT8BIND, and the appropriate data conversion will happen automatically. For a list of the data conversions provided by DB-Library, see the manual page for MOREINFO="NONE"dbwillconvert. REMAP="UN--Under"For a list of the typedefs used by DB-Library, see the manual page for MOREINFO="NONE"types. ID="IN549-19132130"Datatypesconversions supported:by dbbindREMAP="UN--Under"Here is a list of the legal vartypes recognized by MOREINFO="NONE"dbbind, along with the server and program variable types that each one refers to: TOCENTRY="1"LBL="Table 2-7: "Bind types (MOREINFO="NONE"dbbind) COLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="126*"COLNAME="C2" COLWIDTH="99*"COLNAME="C3" COLWIDTH="135*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"VartypeCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Program 
variable typeCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Server type VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CHARBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBCHAR or SYBTEXTCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"STRINGBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBCHAR or SYBTEXTCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NTBSTRINGBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBCHAR or SYBTEXTCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"VARYCHARBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBVARYCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBCHAR or SYBTEXTCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"BINARYBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBBINARYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBBINARY or SYBIMAGECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"VARYBINBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBVARYBINCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBBINARY or SYBIMAGECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"TINYBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBTINYINTCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBINT1COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SMALLBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBSMALLINTCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBINT2COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"INTBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBINTCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBINT4COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"FLT8BINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBFLT8COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBFLT8COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"REALBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBREALCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBREAL COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NUMERICBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBNUMERICCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBNUMERICCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DECIMALBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDECIMALCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBDECIMALCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"BITBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBBITCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBBITCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DATETIMEBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATETIMECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBDATETIMECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SMALLDATETIMEBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATETIME4COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBDATETIME4 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MONEYBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBMONEYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBMONEYCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SMALLMONEYBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBMONEY4COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBMONEY4 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"BOUNDARYBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBBOUNDARYCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SENSITIVITYBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBSENSITIVITYREMAP="UN--Under"The server type in the table above is listed merely for your information.  The vartype you specify does not necessarily have to correspond to a particular server type, because, as mentioned earlier, MOREINFO="NONE"dbbind will convert server data into the specified vartype. The server types nchar and nvarchar are converted internally to char and varchar types, which correspond to the DB-Library type constant SYBCHAR. MOREINFO="NONE"dbbind does not offer precision and scale support for numeric and decimal types. When binding to numeric or decimal variables, MOREINFO="NONE"dbbind uses a default precision and scale of 18 and 0, respectively. To specify a different precision and scale, an application can use MOREINFO="NONE"dbbind_ps.REMAP="UN--Under"The table shows that four representations for character and text data are available. They differ according to whether the data is blank-padded or null-terminated.   Note that if varlen is 0, no padding takes place: TOCENTRY="1"LBL="Table 2-8: "Representations for character data.COLS="4" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="108*"COLNAME="C2" COLWIDTH="101*"COLNAME="C3" COLWIDTH="67*"COLNAME="C4" COLWIDTH="67*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"VartypeCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Program typeCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"PaddingCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Terminator VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CHARBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"blanksCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"none COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"STRINGBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"blanksCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"\0 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NTBSTRINGBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"noneCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"\0 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"VARYCHARBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBVARYCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"noneCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"none COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"BOUNDARYBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"noneCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"\0COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SENSITIVITYBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"noneCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"\0REMAP="UN--Under"Note that the "\0" in the table above is the null terminator character. REMAP="UN--Under"If overflow occurs when converting integer or float data to a character/text binding type, the first character of the resulting value will contain an asterisk ("*") to indicate the error. REMAP="UN--Under"Binary and image data may be stored in two different ways: TOCENTRY="1"LBL="Table 2-9: "Representations for binary data.COLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="130*"COLNAME="C2" COLWIDTH="141*"COLNAME="C3" COLWIDTH="60*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"VartypeCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Program typeCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Padding VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"BINARYBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBBINARYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"nulls COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"VARYBINBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBVARBINARYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"none varlen - The length of the program variable in bytes. REMAP="UN--Under"For fixed-length vartypes, such as MONEYBIND or FLT8BIND, this length is ignored. REMAP="UN--Under"For character, text, binary, and image types, varlen must describe the total length of the available destination buffer space, including any space that may be required for special terminating bytes, such as a null terminator. If varlen is 0, the total number of bytes available will be copied into the program variable. (For char and binary server data, the total number of bytes available is equal to the defined length of the database column, including any blank padding. For varchar, varbinary, text, and image data, the total number of bytes available is equal to the actual data contained in the column.) Therefore, if you are sure that your program variable is large enough to handle the results, you can just set varlen to 0. REMAP="UN--Under"Note that if varlen is 0, no padding takes place. REMAP="UN--Under"In some cases, DB-Library issues a message indicating that data conversion resulted in an overflow. This can be caused by a varlen specification that is too small for the server data.varaddr - The address of the program variable to which the data will be copied. ReturnsREMAP="BO--Body"SUCCEED or FAIL. MOREINFO="NONE"dbbind returns FAIL if the column number isn't valid, if the data conversion specified by vartype isn't legal, or if varaddr is NULL. CommentsMARK="BULL" REMAP="BU--Bullet"Data comes back from the server one row at a time. This routine directs DB-Library to copy the data for a regular column (designated in a MOREINFO="NONE"select statement's select-list) into a program variable. When each new row containing regular (not compute) data is read via MOREINFO="NONE"dbnextrow or MOREINFO="NONE"dbgetrow, the data from the designated column in that row is copied into the program variable with the address varaddr.  There must be a separate MOREINFO="NONE"dbbind call for each regular column that is to be copied. It is not necessary to bind every column to a program variable. The server can return two types of rows: regular rows and compute rows resulting from the MOREINFO="NONE"compute clause of a MOREINFO="NONE"select statement. MOREINFO="NONE"dbbind binds data from regular rows. Use MOREINFO="NONE"dbaltbind for binding data from compute rows. You must make the calls to MOREINFO="NONE"dbbind after a call to MOREINFO="NONE"dbresults and before the first call to MOREINFO="NONE"dbnextrow. The typical sequence of calls is: REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"DBINT        xvariable; DBCHAR       yvariable[10];  /* read the query into the command buffer */ dbcmd(dbproc, "select x = 100, y = 'hello'");  /* send the query to SQL Server */ dbsqlexec(dbproc);  /* get ready to process the query results */ dbresults(dbproc);  /* Bind column data to program variables */ dbbind(dbproc, 1, INTBIND, (DBINT) 0,     (BYTE *) &xvariable); dbbind(dbproc, 2, STRINGBIND, (DBINT) 0,    yvariable);  /* now process each row */ while (dbnextrow(dbproc) != NO_MORE_ROWS) {     C-code to print or process row data } ID="IN546-27140133"dbdatadbdataas alternate to dbbindalternate to dbbind
MOREINFO="NONE"dbbind incurs a little overhead, because it causes the data to be copied into a program variable. To avoid this copying, you can use the MOREINFO="NONE"dbdata routine to directly access the returned data. You can only bind a result column to a single program variable. If you bind a result column to multiple variables, only the last binding takes effect. Since the server can return null values, DB-Library provides a set of default values, one for each datatype, that it will automatically substitute when binding null values. The MOREINFO="NONE"dbsetnull function allows you to explicitly set your own null substitution values. (See the manual page for the MOREINFO="NONE"dbsetnull function for a list of the default substitution values.) See AlsoREMAP="BO--Body"LINKEND="X21854"dbaltbind
, LINKEND="X32323"dbaltbind_ps
, LINKEND="X56339"dbnullbind
, LINKEND="X81674"dbbind_ps
, LINKEND="X76814"dbconvert
, LINKEND="X80440"dbconvert_ps
, LINKEND="X69467"dbdata
, LINKEND="X56339"dbnullbind
, LINKEND="X70360"dbsetnull
, LINKEND="X17556"dbwillconvert
, LINKEND="X91146"types
ID="IN546-30143135"dbbind
 ID="IN549-33146136"dbbind_psID="X81674"dbbind_psID="IN5515-33147138"Regular columnsbinding to program variables
ID="IN559-33147139"Datatypesbinding regular columns to
ID="IN5538-33147140"Bind result column to program variable
ID="IN557-36150141"Columnsregular. See Regular columns.
ID="IN5514-39153142"Result columnsregular. See Regular columns.
Bind a regular result column to a program variable, with precision and scale support for numeric and decimal variables.FORMAT="LINESPECIFIC" RETCODE dbbind_ps(dbproc, column,
vartype,varlen,                varaddr, typeinfo)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS      *dbproc;FORMAT="LINESPECIFIC"int            column;FORMAT="LINESPECIFIC"int            vartype;FORMAT="LINESPECIFIC"DBINT          varlen;FORMAT="LINESPECIFIC"BYTE           *varaddr;FORMAT="LINESPECIFIC"DBTYPEINFO     *typeinfo;ParametersMOREINFO="NONE"dbbind_ps's parameters are identical to MOREINFO="NONE"dbbind's, except thatMOREINFO="NONE" dbbind_ps has the additional parameter typeinfo, which contains information about precision and scale for numeric or decimal variables.REMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. column - The column number of the row data that is to be copied to a program variable.  The first column is column number 1. vartype - This describes the datatype of the binding. It must correspond to the datatype of the program variable that will receive the copy of the data from the DBPROCESS. The table below shows the correspondence between vartypes and program variable types. REMAP="UN--Under"MOREINFO="NONE"dbbind_ps supports a wide range of type conversions, so the vartype can be different from the type returned by the SQL query. For instance, a SYBMONEY result may be bound to a DBFLT8 program variable via FLT8BIND, and the appropriate data conversion will happen automatically. For a list of the data conversions provided by DB-Library, see the manual page for MOREINFO="NONE"dbwillconvert. REMAP="UN--Under"For a list of the typedefs used by DB-Library, see the manual page for MOREINFO="NONE"types. ID="IN559-41155145"Datatypesconversions supported:by dbbind_psREMAP="UN--Under"Here is a list of the legal vartypes recognized by MOREINFO="NONE"dbbind_ps, along with the server and program variable types that each one refers to: TOCENTRY="1"LBL="Table 2-10: "Bind types (MOREINFO="NONE"dbbind_ps) COLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="126*"COLNAME="C2" COLWIDTH="99*"COLNAME="C3" COLWIDTH="135*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"VartypeCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Program 
variable typeCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Server type VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CHARBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBCHAR or SYBTEXTCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"STRINGBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBCHAR or SYBTEXTCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NTBSTRINGBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBCHAR or SYBTEXTCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"VARYCHARBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBVARYCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBCHAR or SYBTEXTCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"BINARYBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBBINARYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBBINARY or SYBIMAGECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"VARYBINBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBVARYBINCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBBINARY or SYBIMAGECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"TINYBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBTINYINTCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBINT1COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SMALLBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBSMALLINTCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBINT2COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"INTBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBINTCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBINT4COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"FLT8BINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBFLT8COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBFLT8COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"REALBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBREALCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBREAL COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NUMERICBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBNUMERICCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBNUMERICCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DECIMALBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDECIMALCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBDECIMALCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"BITBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBBITCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBBITCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DATETIMEBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATETIMECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBDATETIMECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SMALLDATETIMEBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATETIME4COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBDATETIME4 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MONEYBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBMONEYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBMONEYCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SMALLMONEYBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBMONEY4COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBMONEY4 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"BOUNDARYBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBBOUNDARYCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SENSITIVITYBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBSENSITIVITYREMAP="UN--Under"The server type in the table above is listed merely for your information.  The vartype you specify does not necessarily have to correspond to a particular server type, because, as mentioned earlier, MOREINFO="NONE"dbbind_ps will convert server data into the specified vartype. The server types nchar and nvarchar are converted internally to char and varchar types, which correspond to the DB-Library type constant SYBCHAR. REMAP="UN--Under"The table shows that four representations for character and text data are available. They differ according to whether the data is blank-padded or null-terminated.   Note that if varlen is 0, no padding takes place: TOCENTRY="1"LBL="Table 2-11: "Representations for character data.COLS="4" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="108*"COLNAME="C2" COLWIDTH="101*"COLNAME="C3" COLWIDTH="67*"COLNAME="C4" COLWIDTH="67*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"VartypeCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Program typeCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"PaddingCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Terminator VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CHARBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"blanksCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"none COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"STRINGBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"blanksCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"\0 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NTBSTRINGBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"noneCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"\0 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"VARYCHARBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBVARYCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"noneCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"none COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"BOUNDARYBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"noneCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"\0COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SENSITIVITYBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"noneCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"\0REMAP="UN--Under"Note that the "\0" in the table above is the null terminator character. REMAP="UN--Under"If overflow occurs when converting integer or float data to a character/text binding type, the first character of the resulting value will contain an asterisk ("*") to indicate the error. REMAP="UN--Under"Binary and image data may be stored in two different ways: TOCENTRY="1"LBL="Table 2-12: "Representations for binary data.COLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="130*"COLNAME="C2" COLWIDTH="141*"COLNAME="C3" COLWIDTH="60*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"VartypeCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Program typeCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Padding VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"BINARYBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBBINARYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"nulls COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"VARYBINBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBVARBINARYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"none varlen - The length of the program variable in bytes. REMAP="UN--Under"For fixed-length vartypes, such as MONEYBIND or FLT8BIND, this length is ignored. REMAP="UN--Under"For character, text, binary, and image types, varlen must describe the total length of the available destination buffer space, including any space that may be required for special terminating bytes, such as a null terminator. If varlen is 0, the total number of bytes available will be copied into the program variable. (For char and binary server data, the total number of bytes available is equal to the defined length of the database column, including any blank padding. For varchar, varbinary, text, and image data, the total number of bytes available is equal to the actual data contained in the column.) Therefore, if you are sure that your program variable is large enough to handle the results, you can just set varlen to 0. REMAP="UN--Under"Note that if varlen is 0, no padding takes place. varaddr - The address of the program variable to which the data will be copied. typeinfo - A pointer to a DBTYPEINFO structure containing information about the precision and scale of decimal or numeric variables. An application sets a DBTYPEINFO structure with values for precision and scale before calling MOREINFO="NONE"dbbind_ps to bind columns to decimal or numeric variables.REMAP="UN--Under"If typeinfo is NULL:MARK="DASH" REMAP="BS--BulletSub"If the result column is of type numeric or decimal, MOREINFO="NONE"dbbind_ps picks up precision and scale values from the result column.If the result column is not numeric or decimal, MOREINFO="NONE"dbbind_ps uses a default precision of 18 and a default scale of 0.REMAP="UN--Under"If vartype is not DECIMALBIND or NUMERICBIND, typeinfo is ignored.REMAP="UN--Under"A DBTYPEINFO structure is defined as follows:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"typedef struct typeinfo {     DBINTprecision;     DBINTscale;} DBTYPEINFO;REMAP="UN--Under"Legal values for precision are from 1 to 77. Legal values for scale are from 0 to 77. scale must be less than or equal to precision.ReturnsREMAP="BO--Body"SUCCEED or FAIL. MOREINFO="NONE"dbbind_ps returns FAIL if the column number isn't valid, if the data conversion specified by vartype isn't legal, or if varaddr is NULL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbbind_ps is the equivalent of MOREINFO="NONE"dbbind, except that MOREINFO="NONE"dbbind_ps provides scale and precision support for numeric and decimal datatypes, which MOREINFO="NONE"dbbind does not. Calling MOREINFO="NONE"dbbind is equivalent to calling MOREINFO="NONE"dbbind_ps with typeinfo as NULL.Data comes back from the server one row at a time. This routine directs DB-Library to copy the data for a regular column (designated in a MOREINFO="NONE"select statement's select-list) into a program variable. When each new row containing regular (not compute) data is read via MOREINFO="NONE"dbnextrow or MOREINFO="NONE"dbgetrow, the data from the designated column in that row is copied into the program variable with the address varaddr.  There must be a separate MOREINFO="NONE"dbbind orMOREINFO="NONE" dbbind_ps call for each regular column that is to be copied. It is not necessary to bind every column to a program variable. The server can return two types of rows: regular rows and compute rows resulting from the MOREINFO="NONE"compute clause of a MOREINFO="NONE"select statement. MOREINFO="NONE"dbbind_ps binds data from regular rows. Use MOREINFO="NONE"dbaltbind_ps for binding data from compute rows. You must make the calls to MOREINFO="NONE"dbbind_ps after a call to MOREINFO="NONE"dbresults and before the first call to MOREINFO="NONE"dbnextrow. ID="IN556-49163148"dbdatadbdataas alternate to dbbindalternate to dbbind_ps
MOREINFO="NONE"dbbind_ps incurs a little overhead, because it causes the data to be copied into a program variable. To avoid this copying, you can use the MOREINFO="NONE"dbdata routine to directly access the returned data. You can only bind a result column to a single program variable. If you bind a result column to multiple variables, only the last binding takes effect. Since the server can return null values, DB-Library provides a set of default values, one for each datatype, that it will automatically substitute when binding null values. The MOREINFO="NONE"dbsetnull function allows you to explicitly set your own null substitution values. See the manual page for the MOREINFO="NONE"dbsetnull function for a list of the default substitution values. See AlsoREMAP="BO--Body"LINKEND="X21854"dbaltbind
, LINKEND="X32323"dbaltbind_ps
, LINKEND="X63819"dbanullbind
, LINKEND="X14206"dbbind
, LINKEND="X76814"dbconvert
, LINKEND="X80440"dbconvert_ps
, LINKEND="X69467"dbdata
, LINKEND="X56339"dbnullbind
, LINKEND="X70360"dbsetnull
, LINKEND="X17556"dbwillconvert
, LINKEND="X91146"types
ID="IN559-52166150"dbbind_ps
 ID="IN559-55169151"dbbufsizedbbufsize
Return the size of a DBPROCESS row buffer. FORMAT="LINESPECIFIC"int dbbufsize(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS        *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and the server. ReturnsREMAP="BO--Body"An integer representing the size, in rows, of the DBPROCESS row buffer. REMAP="BO--Body"If dbproc is NULL or if row buffering is not enabled, MOREINFO="NONE"dbbufsize returns 0. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbbufsize returns the size of a DBPROCESS row buffer.   Row buffering provides a way for an application to keep a specified number of server result rows in program memory. To enable row buffering, call "dbsetopt(dbproc, DBBUFFER, "n")", where n is the number of rows to buffer. An application that is buffering result rows can  access rows non-sequentially, via MOREINFO="NONE"dbgetrow.   See the MOREINFO="NONE"dbgetrow manual page for a discussion of  the benefits and penalties of row buffering. See AlsoREMAP="BO--Body"LINKEND="X38617"dbclrbuf
, LINKEND="X71422"dbgetrow
, LINKEND="X97776"dbsetopt
, LINKEND="X60647"options
ID="IN569-58173158"dbbufsize
 ID="IN568-61176159"dbbylistdbbylistID="IN5712-61177161"Compute rowsreturning bylist for
ID="IN576-61177162"Bylistreturning
Return the bylist for a compute row. FORMAT="LINESPECIFIC"BYTE*dbbylist(dbproc,computeid,size)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"int          computeid;FORMAT="LINESPECIFIC"int          *size;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. computeid - The id that identifies the particular compute row of interest. A SQL MOREINFO="NONE"select statement may have multiple MOREINFO="NONE"compute clauses, each of which returns a separate compute row. The computeid corresponding to the first MOREINFO="NONE"compute clause in a MOREINFO="NONE"select is 1. The computeid is returned by MOREINFO="NONE"dbnextrow or MOREINFO="NONE"dbgetrow. size - A pointer to an integer, which MOREINFO="NONE"dbbylist sets to the number of elements in the bylist. ReturnsREMAP="BO--Body"A pointer to an array of bytes containing the numbers of the columns that compose the bylist for the specified compute. The array of BYTEs is part of the DBPROCESS, so you must not free it. If the computeid is out of range, NULL is returned. ID="IN579-65181166"dbcolnamedbcolnameand returning bylistreturning bylistREMAP="BO--Body"Call MOREINFO="NONE"dbcolname to derive the name of a column from its number. REMAP="BO--Body"The size of the array is returned in the size parameter. A size of 0 indicates that either there is no bylist for this particular compute or the computeid is out of range. CommentsMARK="BULL" REMAP="BU--Bullet"ID="IN576-65181168"Bylist
MOREINFO="NONE"dbbylist returns the bylist for a compute row. (A MOREINFO="NONE"select statement's MOREINFO="NONE"compute clause may contain the keyword MOREINFO="NONE"by, followed by a list of columns. This list, known as the "bylist," divides the results into subgroups, based on changing values in the specified columns. The MOREINFO="NONE"compute clause's row aggregate is applied to each subgroup, generating a compute row for each subgroup.) MOREINFO="NONE"dbresults must return SUCCEED before the application calls this routine. Assume the following command has been executed: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"select dept, name, year, sales from employee     order by dept, name, year     compute count(name) by dept,name REMAP="BO--Body"The call "dbbylist (dbproc, 1, &size)" sets size to 2, because there are two items in the bylist. It returns a pointer to an array of two BYTEs, which contain the values 1 and 2, indicating that the bylist is composed of columns 1 and 2 from the select-list. See AlsoREMAP="BO--Body"LINKEND="X46780"dbadata
, LINKEND="X76889"dbadlen
, LINKEND="X12040"dbaltlen
, LINKEND="X53350"dbalttype
, LINKEND="X83710"dbcolname
, LINKEND="X71422"dbgetrow
, LINKEND="X10726"dbnextrow
ID="IN578-68184170"dbbylist
 ID="IN578-71187171"dbcancelID="X57019"dbcancelID="IN5815-71188173"Command batchescanceling current
ID="IN587-74191174"Batchescommand. See Command batches.
Cancel the current command batch. FORMAT="LINESPECIFIC"RETCODE dbcancel(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. ReturnsREMAP="BO--Body"SUCCEED or FAIL. The most common reasons for failure are a dead DBPROCESS or a network error. MOREINFO="NONE"dbcancel will also return FAIL if the server is dead. CommentsID="IN587-74191179"Server MARK="BULL" REMAP="BU--Bullet"This routine cancels execution of the current command batch on the server and flushes any pending results. The application can call it after calling MOREINFO="NONE"dbsqlexec, MOREINFO="NONE"dbsqlsend, MOREINFO="NONE"dbsqlok, MOREINFO="NONE"dbresults, or MOREINFO="NONE"dbnextrow. MOREINFO="NONE"dbcancel sends an attention packet to the server which causes the server to cease execution of the command batch. Any pending results are read and discarded. ID="IN588-74191180"Commandscanceling entire batch
MOREINFO="NONE"dbcancel cancels all the commands in the current command batch. To cancel only the results from the current command, call MOREINFO="NONE"dbcanquery instead. If you have set your own interrupt handler using MOREINFO="NONE"dbsetinterrupt, you can't call MOREINFO="NONE"dbcancel in your interrupt handler. This would cause output from the server to DB-Library to become out of sync. If you want to cancel the current command batch from your interrupt handler, the interrupt handler should set a flag that you can check before the next call to MOREINFO="NONE"dbresults or MOREINFO="NONE"dbnextrow. An asynchronous version of MOREINFO="NONE"dbcancel, called MOREINFO="NONE"dbcancel_a, is available for VMS. See AlsoREMAP="BO--Body"LINKEND="X53272"dbcancel_a (VMS only)
, LINKEND="X15355"dbcanquery
, LINKEND="X10726"dbnextrow
, LINKEND="X35104"dbresults
, LINKEND="X21733"dbsetinterrupt
, LINKEND="X41234"dbsqlexec
, LINKEND="X21206"dbsqlok
, LINKEND="X49376"dbsqlsend
ID="IN588-77194182"dbcancel
 ID="IN5816-80197183"dbcancel_a (VMS)ID="X53272"dbcancel_a  (VMS only)ID="IN5915-80198185"Command batchescanceling current:asynchronous version (VMS)
Cancel the current command batch. FORMAT="LINESPECIFIC"RETCODE dbcancel_a(dbproc,final_result,ast_proc,>
                                            ast_param)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS       *dbproc;FORMAT="LINESPECIFIC"RETCODE         *final_result;FORMAT="LINESPECIFIC"void            (*ast_proc)();FORMAT="LINESPECIFIC"BYTE            *ast_param;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. final_result - A pointer to a RETCODE which is set to SUCCEED or FAIL if MOREINFO="NONE"dbcancel_a returns SUCCEED. *final_result will be set to SUCCEED if the current command batch was successfully canceled. ast_proc - A pointer to a user-supplied routine that will be queued when the current command batch is successfully canceled or an error occurs. *final_result will always be set before this procedure is invoked. ast_param - A generic BYTE pointer that will be passed to the user-supplied ast_proc(). ast_param allows the user to pass any parameter or structure to the ast_proc routine. ReturnsREMAP="BO--Body"SUCCEED or FAIL. CommentsID="IN5927-82200190"Asynchronous routines (VMS)dbcancel_aMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbcancel_a is the asynchronous version of MOREINFO="NONE"dbcancel. This routine cancels execution of the current command batch on the server and flushes any pending results. The application can call it after calling MOREINFO="NONE"dbsqlexec, MOREINFO="NONE"dbsqlexec_a, MOREINFO="NONE"dbsqlsend, MOREINFO="NONE"dbsqlok, MOREINFO="NONE"dbresults, MOREINFO="NONE"dbresults_a, MOREINFO="NONE"dbnextrow, or MOREINFO="NONE"dbnextrow_a. MOREINFO="NONE"dbcancel_a sends an attention packet to the server which causes the server to cease execution of the command batch. Any pending results are read and discarded. MOREINFO="NONE"dbcancel_a cancels all the commands in the current command batch. To cancel only the results from the current command, call MOREINFO="NONE"dbcanquery instead. If you have set your own interrupt handler using MOREINFO="NONE"dbsetinterrupt, you can't call MOREINFO="NONE"dbcancel_a in your interrupt handler. This would cause output from the server to DB-Library to become out of sync. If you want to cancel the current command batch from your interrupt handler, the interrupt handler should set a flag that you can check before the next call to MOREINFO="NONE"dbresults, MOREINFO="NONE"dbresults_a, MOREINFO="NONE"dbnextrow, or MOREINFO="NONE"dbnextrow_a. If MOREINFO="NONE"dbcancel_a returns FAIL, *final_result will not be set and ast_proc() will not be invoked. If MOREINFO="NONE"dbcancel_a returns SUCCEED, *final_result will be set to SUCCEED or FAIL (depending on whether the current batch was successfully canceled) and ast_proc() will be invoked by DB-Library. ID="IN5913-82200191"Input streamsutilizing multiple (VMS)
ID="IN5914-82200192"Output streamsutilizing multiple (VMS)MOREINFO="NONE"dbcancel_a is useful in VMS applications that use multi-tasking or are otherwise trying to respond to multiple input and output streams. After sending an attention packet to the server MOREINFO="NONE"dbcancel waits until all pending results are read and discarded or until the timeout period has elapsed. By substituting MOREINFO="NONE"dbcancel_a for MOREINFO="NONE"dbcancel, the time between the request for the server's attention and its response can be used to service other parts of the application. References in this manual to the MOREINFO="NONE"dbcancel routine also pertain to MOREINFO="NONE"dbcancel_a. See AlsoREMAP="BO--Body"LINKEND="X57019"dbcancel
, LINKEND="X15355"dbcanquery
, LINKEND="X54207"dbcanquery_a (VMS only)
,  LINKEND="X10726"dbnextrow
, LINKEND="X90089"dbnextrow_a (VMS only)
, LINKEND="X35104"dbresults
, LINKEND="X81070"dbresults_a (VMS only)
, LINKEND="X21733"dbsetinterrupt
, LINKEND="X41234"dbsqlexec
, LINKEND="X34208"dbsqlexec_a (VMS only)
, LINKEND="X21206"dbsqlok
, LINKEND="X70305"dbsqlok_a (VMS only)
, LINKEND="X49376"dbsqlsend
ID="IN5916-85203194"dbcancel_a (VMS)
 ID="IN5910-88206195"dbcanqueryID="X15355"dbcanqueryID="IN6011-88207197"Result rowscanceling
Cancel any rows pending from the most recently executed query. FORMAT="LINESPECIFIC"RETCODE dbcanquery(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. ReturnsREMAP="BO--Body"SUCCEED or FAIL. The most common reasons for failure are a dead DBPROCESS or a network error. CommentsMARK="BULL" REMAP="BU--Bullet"This routine is an efficient way to throw away any unread rows that result from the most recently executed SQL query. Calling MOREINFO="NONE"dbcanquery is equivalent to calling MOREINFO="NONE"dbnextrow until it returns NO_MORE_ROWS, but MOREINFO="NONE"dbcanquery is faster because it allocates no memory and executes no bindings to user data. ID="IN6014-92211202"dbsetinterruptdbsetinterruptand canceling result rowscanceling result rowsIf you have set your own interrupt handler using MOREINFO="NONE"dbsetinterrupt, you can't call MOREINFO="NONE"dbcanquery in your interrupt handler. This would cause output from the server to DB-Library to become out of sync. If you want to ignore any unread rows from the current query, the interrupt handler should set a flag that you can check before the next call to MOREINFO="NONE"dbnextrow. MOREINFO="NONE"dbresults must return SUCCEED before an application can call MOREINFO="NONE"dbcanquery. If you want to ignore all of the results from all of the commands in the current command batch, call MOREINFO="NONE"dbcancel instead. See AlsoREMAP="BO--Body"LINKEND="X57019"dbcancel
, LINKEND="X10726"dbnextrow
, LINKEND="X35104"dbresults
, LINKEND="X21733"dbsetinterrupt
, LINKEND="X41234"dbsqlexec
ID="IN6010-95214204"dbcanquery
 ID="IN6012-98217205"dbcanquery_aID="X54207"dbcanquery_a (VMS only)ID="IN6111-98218207"Result rowscanceling
Cancel any rows pending from the most recently executed query. FORMAT="LINESPECIFIC"RETCODE dbcanquery_a(dbproc, final_result, ast_proc,                ast_param)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS       *dbproc;FORMAT="LINESPECIFIC"RETCODE         *final_result;FORMAT="LINESPECIFIC"void            (*ast_proc)();FORMAT="LINESPECIFIC"BYTE            *ast_param;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. final_result - A pointer to a RETCODE which is set to SUCCEED or FAIL if MOREINFO="NONE"dbcanquery_a returns SUCCEED. *final_result will be set to SUCCEED if the current query was successfully canceled. ast_proc() - A pointer to a user-supplied routine that will be queued when the current query is successfully canceled or an error occurs. *final_result will always be set before this procedure is invoked. ast_param - A generic BYTE pointer that will be passed to the user-supplied ast_proc(). ast_param allows the user to pass any parameter or structure to the ast_proc routine. ReturnsREMAP="BO--Body"SUCCEED or FAIL. The most common reason for failure is a dead DBPROCESS. CommentsMARK="BULL" REMAP="BU--Bullet"This routine is an efficient way to throw away any unread rows that result from the most recently executed SQL query. Calling MOREINFO="NONE"dbcanquery_a is equivalent to calling MOREINFO="NONE"dbnextrow until it returns NO_MORE_ROWS, but MOREINFO="NONE"dbcanquery_a is faster because it allocates no memory and executes no bindings to user data. ID="IN6114-102222212"dbsetinterruptdbsetinterruptand canceling result rowscanceling result rowsIf you have set your own interrupt handler using MOREINFO="NONE"dbsetinterrupt, you can't call MOREINFO="NONE"dbcanquery_a in your interrupt handler. This would cause output from the server to DB-Library to become out of sync. If you want to ignore any unread rows from the current query, the interrupt handler should set a flag that you can check before the next call to MOREINFO="NONE"dbnextrow. MOREINFO="NONE"dbresults must return SUCCEED before an application can call MOREINFO="NONE"dbcanquery_a. If you want to ignore all of the results from all of the commands in the current command batch, call MOREINFO="NONE"dbcancel instead. See AlsoREMAP="BO--Body"LINKEND="X57019"dbcancel
, LINKEND="X53272"dbcancel_a (VMS only)
,  LINKEND="X10726"dbnextrow
, LINKEND="X90089"dbnextrow_a (VMS only)
, LINKEND="X35104"dbresults
, LINKEND="X81070"dbresults_a (VMS only)
, LINKEND="X21733"dbsetinterrupt
, LINKEND="X41234"dbsqlexec
, LINKEND="X34208"dbsqlexec_a (VMS only)
ID="IN6112-105225214"dbcanquery_a
 ID="IN618-108228215"dbchangeID="X22834"dbchangeID="IN629-108229217"Databasesdetermining whether changed
ID="IN6215-108229218"Command batchesCommand batchesand switching databasesswitching databases
Determine whether a command batch has changed the current database. FORMAT="LINESPECIFIC"char *dbchange(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. ReturnsREMAP="BO--Body"A pointer to the null-terminated name of the new database, if any. If the database has not changed, NULL will be returned. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbchange informs the program of a change in the current database. It does so by catching any instance of the Transact-SQL MOREINFO="NONE"use command. Although a MOREINFO="NONE"use command can appear anywhere in a command batch, the database change does not actually take effect until the end of the batch. MOREINFO="NONE"dbchange is therefore useful only in determining whether the current command batch has changed the database for subsequent command batches. The internal DBPROCESS flag that MOREINFO="NONE"dbchange monitors to determine whether the database has changed is cleared when the program executes a new command batch by calling either MOREINFO="NONE"dbsqlexec or MOREINFO="NONE"dbsqlsend. Therefore, the simplest way to keep track of database changes is to call MOREINFO="NONE"dbchange when MOREINFO="NONE"dbresults returns NO_MORE_RESULTS at the end of each command batch. Alternatively, you can always get the name of the current database by calling MOREINFO="NONE"dbname. See AlsoREMAP="BO--Body"LINKEND="X47894"dbname
, LINKEND="X35104"dbresults
, LINKEND="X41234"dbsqlexec
, LINKEND="X49376"dbsqlsend
, LINKEND="X74526"dbuse
ID="IN628-111232224"dbchange
 ID="IN6213-114235225"dbcharsetconv
ID="IN6213-114235226"Character settranslationID="X19407"dbcharsetconv
Indicate whether the server is performing character set translation. FORMAT="LINESPECIFIC"DBBOOL dbcharsetconv(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a  particular front-end/server process.   It contains all the information that  DB-Library/C uses to manage communications and data between the front end and the server. ReturnsREMAP="BO--Body"TRUE if the server is performing translation; FALSE if it is not. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbcharsetconv returns TRUE if the server is performing  character set translations, and FALSE if it is not. Note that if a client and a server are using the  same character set, the server is not performing translation. As expected in this case, MOREINFO="NONE"dbcharsetconv returns FALSE. To get the name of its own character set, a client can call  MOREINFO="NONE"dbgetcharset. To get the name of the server's character set, a client can call MOREINFO="NONE"dbservcharset. See AlsoREMAP="BO--Body"LINKEND="X28915"dbservcharset
, LINKEND="X16298"dbgetcharset
, LINKEND="X49378"DBSETLCHARSET
ID="IN6313-117239233"dbcharsetconv
 ID="IN637-120242234"dbcloseID="X87778"dbclose
Close and de-allocate a single DBPROCESSID="IN6419-122245236"DBPROCESS structureclosing a
ID="IN6419-124247237"DBPROCESS structurede-allocating a
ID="IN6419-124247238"Network connectionsclosing
 structure. FORMAT="LINESPECIFIC"void dbclose(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. ReturnsREMAP="BO--Body"None. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbclose is the inverse of MOREINFO="NONE"dbopen. It cleans up any activity associated with one DBPROCESS structure and de-allocates the space. It also closes the corresponding network connection. To close every open DBPROCESS structure, use MOREINFO="NONE"dbexit instead. MOREINFO="NONE"dbclose does not de-allocate space associated with a LOGINREC.  To de-allocate a LOGINREC, an  application can call MOREINFO="NONE"dbloginfree. Calling MOREINFO="NONE"dbclose with an argument not returned by MOREINFO="NONE"dbopen is sure to cause trouble. See AlsoREMAP="BO--Body"LINKEND="X99227"dbexit
, LINKEND="X42139"dbopen
ID="IN647-127250244"dbclose
 ID="IN648-130253245"dbclrbufID="X38617"dbclrbufID="IN6511-130254247"Row buffersclearing
ID="IN654-130254248"Rowsdropping from buffer
ID="IN6511-130254249"Result rowsdropping from buffer
Drop rows from the row buffer. FORMAT="LINESPECIFIC"void dbclrbuf(dbproc, n)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS*   dbproc;FORMAT="LINESPECIFIC"DBINT        n;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. n - The number of rows you want cleared from the row buffer. If you make n equal to or greater than the number of rows in the buffer, all but the newest row will be removed. If n is less than 1, the function call is ignored. ReturnsREMAP="BO--Body"None. CommentsMARK="BULL" REMAP="BU--Bullet"DB-Library provides a row-buffering service to application programs. You can turn row buffering on by calling "dbsetopt(dbproc, DBBUFFER, "n")" where n is the number of rows you would like DB-Library to buffer. If buffering is on, you can then randomly refer to rows that have been read from the server, using MOREINFO="NONE"dbgetrow. See the MOREINFO="NONE"dbgetrow manual page for a discussion of the benefits and penalties of row buffering. The row buffer can become full for two reasons.  Either the server has returned more than the n rows you said you wanted buffered, or sufficient space couldn't be allocated to save the row you wanted. When the row buffer is full, MOREINFO="NONE"dbnextrow returns BUF_FULL and refuses to read in the next row from the server. Once the row buffer is full, subsequent calls to MOREINFO="NONE"dbnextrow will continue to return BUF_FULL until at least one row is freed by calling MOREINFO="NONE"dbclrbuf. MOREINFO="NONE"dbclrbuf always frees the oldest rows in the buffer first. Once a result row has been cleared from the buffer, it is no longer available to the program. For an example of row buffering, see Example 4 of the on-line example programs.See AlsoREMAP="BO--Body"LINKEND="X71422"dbgetrow
, LINKEND="X10726"dbnextrow
, LINKEND="X97776"dbsetopt
, LINKEND="X60647"options
ID="IN658-133257255"dbclrbuf
 ID="IN658-136260256"dbclroptID="X69074"dbclropt
Clear an option set by MOREINFO="NONE"dbsetoptID="IN667-136261258"Optionsclearing
. FORMAT="LINESPECIFIC"RETCODE dbclropt(dbproc, option, param)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"int          option;FORMAT="LINESPECIFIC"char*        param;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. If dbproc is NULL, the option will be cleared for all active DBPROCESS structures. option - The option that is to be turned off. See the MOREINFO="NONE"options manual page for the list of options. param - Certain options take parameters.  The DBOFFSET option, for example, takes as a parameter the SQL construct for which offsets are to be returned. The MOREINFO="NONE"options manual page lists those options that take parameters. If an option does not take a parameter, param must be NULL. REMAP="UN--Under"If the option you are clearing takes a parameter but there can be only one instance of the option, MOREINFO="NONE"dbclropt ignores the param argument. For example, MOREINFO="NONE"dbclropt ignores the value of param when clearing the DBBUFFER option, because row buffering can have only one setting at a time. On the other hand, the DBOFFSET option can have several settings, each with a different parameter. It may have been set twice-to look for offsets to MOREINFO="NONE"select statements and offsets to MOREINFO="NONE"order MOREINFO="NONE"by clauses. In that case, MOREINFO="NONE"dbclropt needs the param argument to determine whether to clear the MOREINFO="NONE"select offset or the MOREINFO="NONE"order MOREINFO="NONE"by offset.  REMAP="UN--Under"If an invalid parameter is specified for one of the server options, this will be discovered the next time a command buffer is sent to the server. The MOREINFO="NONE"dbsqlexec or MOREINFO="NONE"dbsqlsend call will fail, and DB-Library will invoke the user-installed message handler. If an invalid parameter is specified for one of the DB-Library options (DBBUFFER or DBTEXTLIMIT), the MOREINFO="NONE"dbclropt call itself will fail. ReturnsREMAP="BO--Body"SUCCEED or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"This routine clears the server and DB-Library options that have been set with MOREINFO="NONE"dbsetopt. Although server options may be set and cleared directly through SQL, the application should instead use MOREINFO="NONE"dbsetopt and MOREINFO="NONE"dbclropt to set and clear options.  This provides a uniform interface for setting both server and DB-Library options. It also allows the application to use the MOREINFO="NONE"dbisopt function to check the status of an option. MOREINFO="NONE"dbclropt does not immediately clear the option. The option is cleared the next time a command buffer is sent to the server (by invoking MOREINFO="NONE"dbsqlexec or MOREINFO="NONE"dbsqlsend). For a complete list of options, see the manual page for MOREINFO="NONE"options. See AlsoREMAP="BO--Body"LINKEND="X50317"dbisopt
, LINKEND="X97776"dbsetopt
, LINKEND="X60647"options
ID="IN668-139264264"dbclropt
 ID="IN665-142267265"dbcmdID="X41151"dbcmd
Add text to the DBPROCESSID="IN6715-142268267"Command buffersadding text to
 command buffer. FORMAT="LINESPECIFIC"RETCODE dbcmd(dbproc, cmdstring)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"char         *cmdstring;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. cmdstring - A null-terminated character string that MOREINFO="NONE"dbcmd copies into the command buffer. ReturnsREMAP="BO--Body"SUCCEED or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"This routine adds text to the Transact-SQL command buffer in the DBPROCESS structure. It adds to the existing command buffer-it doesn't delete or overwrite the current contents except after the buffer has been sent to the server (see below). A single command buffer may contain multiple commands; in fact, this represents an efficient use of the command buffer. The application may call MOREINFO="NONE"dbcmd repeatedly. The command strings in sequential calls are just concatenated together. It is the application's responsibility to ensure that any necessary blanks appear between the end of one string and the beginning of the next. ID="IN6715-142268272"Command bufferssetting no clear optionAfter a call to MOREINFO="NONE"dbsqlexec or MOREINFO="NONE"dbsqlsend, the first call to either MOREINFO="NONE"dbcmd or MOREINFO="NONE"dbfcmd automatically clears the command buffer before the new text is entered. If this situation is undesirable, set the DBNOAUTOFREE option. When DBNOAUTOFREE is set, the command buffer is cleared only by an explicit call to MOREINFO="NONE"dbfreebuf. Here's a small example of using MOREINFO="NONE"dbcmd to build up a multi-line SQL command: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"DBPROCESS       *dbproc;  dbcmd(dbproc, "select name from sysobjects"); dbcmd(dbproc, " where id < 5"); dbcmd(dbproc, " and type='S'"); REMAP="BO--Body"Note the required spaces at the start of the second and third command strings. MARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbfcmd is a related function. MOREINFO="NONE"dbfcmd interprets the cmdstring as a format string that is passed to MOREINFO="NONE"sprintf along with any additional arguments. The application can intermingle calls to MOREINFO="NONE"dbcmd and MOREINFO="NONE"dbfcmd. At any time, the application can access the contents of the command buffer through calls to MOREINFO="NONE"dbgetchar, MOREINFO="NONE"dbstrlen, and MOREINFO="NONE"dbstrcpy. Available memory is the only constraint on the size of the DBPROCESS command buffer created by calls to MOREINFO="NONE"dbcmd and MOREINFO="NONE"dbfcmd. See AlsoREMAP="BO--Body"LINKEND="X29834"dbfcmd
, LINKEND="X18180"dbfreebuf
, LINKEND="X20172"dbgetchar
, LINKEND="X48259"dbstrcpy
, LINKEND="X53545"dbstrlen
, LINKEND="X60647"options
ID="IN675-145271274"dbcmd
 ID="IN678-148274275"DBCMDROWID="X17006"DBCMDROWID="IN688-148275277"Commandsdetermining whether can return rows
ID="IN684-148275278"Rowsdetermining whether returned by command
Determine whether the current command can return rows. FORMAT="LINESPECIFIC"RETCODE DBCMDROW(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. ReturnsREMAP="BO--Body"SUCCEED or FAIL, to indicate whether the command can return rows. CommentsMARK="BULL" REMAP="BU--Bullet"This macro determines whether the command currently being processed by MOREINFO="NONE"dbresults is one that can return rows, i.e., a Transact-SQL MOREINFO="NONE"select statement or an MOREINFO="NONE"execute on a stored procedure containing a MOREINFO="NONE"select. The application can call it after MOREINFO="NONE"dbresults returns SUCCEED. Even if this macro returns SUCCEED, the command does not return any rows if none have qualified. To determine whether any rows are actually being returned, use MOREINFO="NONE"DBROWS. See AlsoREMAP="BO--Body"LINKEND="X10726"dbnextrow
, LINKEND="X35104"dbresults
, LINKEND="X87634"DBROWS
, LINKEND="X42749"DBROWTYPE
ID="IN688-151278284"DBCMDROW
 ID="IN6811-154281285"dbcolbrowseID="X60561"dbcolbrowseID="IN6915-154282287"Regular columnsdetermining whether source column is updatable with browse mode
ID="IN6911-154282288"Browse modedetermining whether regular column source is updatable
Determine whether the source of a regular result column is updatable via the DB-Library browse-mode facilities. FORMAT="LINESPECIFIC"DBBOOL dbcolbrowse(dbproc, colnum)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"int          colnum;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. colnum - The number of the result column of interest. Column numbers start at 1. ReturnsREMAP="BO--Body"TRUE or FALSE. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbcolbrowse is one of the DB-Library browse mode routines. See the Introduction for a detailed discussion of browse mode. MOREINFO="NONE"dbcolbrowse provides a way to determine whether the database column that's the source of a regular (i.e., non-compute) result column in a select-list is updatable via the DB-Library browse-mode facilities. This routine is useful in examining ad hoc queries. If the query has been hardcoded into the program, MOREINFO="NONE"dbcolbrowse is obviously unnecessary. To be updatable, a column must be derived from a browsable table (i.e., the table must have a unique index and a timestamp column) and cannot be the result of a SQL expression. For example, in the following select-list: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"select title, category=type,     wholesale=(price * 0.6) ... for browse REMAP="UN--Under"result columns 1 and 2 ("title" and "category") are updatable, but column 3 ("wholesale") is not, because it is the result of an expression. The application can call MOREINFO="NONE"dbcolbrowse any time after MOREINFO="NONE"dbresults. To determine the name of the source column given the name of the result column, use MOREINFO="NONE"dbcolsource. Example 7 of the on-line example programs contains a call to MOREINFO="NONE"dbcolbrowse. See AlsoREMAP="BO--Body"LINKEND="X78078"dbcolsource
, LINKEND="X46501"dbqual
, LINKEND="X58939"dbtabbrowse
, LINKEND="X52066"dbtabcount
, LINKEND="X84917"dbtabname
, LINKEND="X67923"dbtabsource
, LINKEND="X78355"dbtsnewlen
, LINKEND="X32220"dbtsnewval
, LINKEND="X11575"dbtsput
ID="IN6911-157285294"dbcolbrowse
 ID="IN698-160288295"dbcollenID="X80379"dbcollenID="IN7015-160289297"Regular columnsreturning maximum data length of
Return the maximum length of the data in a regular result column. FORMAT="LINESPECIFIC"DBINT dbcollen(dbproc, column)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"int           column;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. column - The number of the column of interest.  The first column is number 1. ReturnsREMAP="BO--Body"The maximum length, in bytes, of the data for the particular column. If the column number is not in range, MOREINFO="NONE"dbcollen returns -1. CommentsMARK="BULL" REMAP="BU--Bullet"This routine returns the maximum length of the data in a regular (i.e., non-compute) result column.  In the case of variable length data, this is not necessarily the actual length of the data, but rather the maximum length that the data can be.  For the actual data length, use MOREINFO="NONE"dbdatlen. The value that MOREINFO="NONE"dbcollen returns is not affected by Transact-SQL string functions such as MOREINFO="NONE"rtrim and MOREINFO="NONE"ltrim. For example, if the column au_lname has  a maximum length of 20 characters, and the first row instance of au_lname is "Swift               ",  MOREINFO="NONE"dbcollen returns 20 as the length of au_lname, even though the Transact-SQL command "MOREINFO="NONE"select rtrim(au_lname) from authors" returns a string that is 5 characters long.  Here's a small program fragment that uses MOREINFO="NONE"dbcollen: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc; int           colnum; DBINT         column_length;  /* Put the command into the command buffer */ dbcmd(dbproc, "select name, id, type from    sysobjects"); /* ** Send the command to SQL Server and begin ** execution */ dbsqlexec(dbproc);  /* process the command results */ dbresults(dbproc);  /* examine the column lengths */ for (colnum = 1; colnum < 4; colnum++) {     column_length = dbcollen(dbproc, colnum);     printf("column %d, length is %ld.\n", colnum,          column_length); } See AlsoREMAP="BO--Body"LINKEND="X83710"dbcolname
, LINKEND="X35574"dbcoltype
, LINKEND="X69467"dbdata
, LINKEND="X61322"dbdatlen
, LINKEND="X66483"dbnumcols
ID="IN708-163292303"dbcollen
 ID="IN709-166295304"dbcolnameID="X83710"dbcolnameID="IN7115-166296306"Regular columnsreturning name of
Return the name of a regular result column. FORMAT="LINESPECIFIC"char *dbcolname(dbproc, column)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"int           column;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. column - The number of the column of interest.  The first column is number 1. ReturnsREMAP="BO--Body"A CHAR pointer to the null-terminated name of the particular column. If the column number is not in range, MOREINFO="NONE"dbcolname returns NULL. CommentsMARK="BULL" REMAP="BU--Bullet"This routine returns a pointer to the null-terminated name of a regular (i.e., non-compute) result column. Here's a small program fragment that uses MOREINFO="NONE"dbcolname: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"               DBPROCESS     *dbproc;                 /* Put the command into the command buffer */                dbcmd(dbproc, "select name, id, type from                      sysobjects");                 /*                ** Send the command to SQL Server and begin               ** execution                */                dbsqlexec(dbproc);                 /* Process the command results */                dbresults(dbproc);                 /* Examine the column names */                printf("first column name is %s\n",                   dbcolname(dbproc, 1));               printf("second column name is %s\n",                   dbcolname(dbproc, 2));               printf("third column name is %s\n",                   dbcolname(dbproc, 3));See AlsoREMAP="BO--Body"LINKEND="X80379"dbcollen
, LINKEND="X35574"dbcoltype
, LINKEND="X69467"dbdata
, LINKEND="X61322"dbdatlen
, LINKEND="X66483"dbnumcols
ID="IN719-169299312"dbcolname
 ID="IN7111-172302313"dbcolsourceID="X78078"dbcolsourceID="IN7215-172303315"Regular columnsreturning name of source column
Return a pointer to the name of the database column from which the specified regular result column was derived. FORMAT="LINESPECIFIC"char *dbcolsource(dbproc, colnum)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS       *dbproc;FORMAT="LINESPECIFIC"int             colnum;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. colnum - The number of the result column of interest. Column numbers start at 1. ReturnsREMAP="BO--Body"A pointer to a null-terminated column name. This pointer will be NULL if the column number is out of range or if the column is the result of a SQL expression, such as "max(colname)". CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbcolsource is one of the DB-Library browse mode routines. It is usable only with results from a browse-mode MOREINFO="NONE"select (i.e., a MOREINFO="NONE"select containing the key words MOREINFO="NONE"for MOREINFO="NONE"browse). See the Introduction for a detailed discussion of browse mode. MOREINFO="NONE"dbcolsource provides an application with information it needs to update a database column, based on an ad hoc query. MOREINFO="NONE"select statements may optionally specify header names for regular (i.e., non-compute) result columns: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"select author = au_lname from authors for browse REMAP="UN--Under"When updating a table, you must use the database column name, not the header name (in this example, "au_lname", not "author"). You can use the MOREINFO="NONE"dbcolsource routine to get the underlying database column name: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"dbcolsource(dbproc, 1) REMAP="UN--Under"This call will return a pointer to the string "au_lname". MOREINFO="NONE"dbcolsource is useful for ad hoc queries. If the query has been hardcoded into the program, this routine is obviously unnecessary. The application can call MOREINFO="NONE"dbcolsource any time after MOREINFO="NONE"dbresults. Example 7 of the on-line example programs contains a call to MOREINFO="NONE"dbcolsource. See AlsoREMAP="BO--Body"LINKEND="X60561"dbcolbrowse
, LINKEND="X46501"dbqual
, LINKEND="X58939"dbtabbrowse
, LINKEND="X52066"dbtabcount
, LINKEND="X84917"dbtabname
, LINKEND="X67923"dbtabsource
, LINKEND="X78355"dbtsnewlen
, LINKEND="X32220"dbtsnewval
, LINKEND="X11575"dbtsput
ID="IN7211-175306321"dbcolsource
 ID="IN729-178309322"dbcoltypeID="X35574"dbcoltypeID="IN7315-178310324"Regular columnsreturning datatypes for
ID="IN739-178310325"Datatypesreturning for regular column
Return the datatype for a regular result column. FORMAT="LINESPECIFIC"int dbcoltype(dbproc, column)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS      *dbproc;FORMAT="LINESPECIFIC"int            column;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. column - The number of the column of interest.  The first column is number 1. ReturnsREMAP="BO--Body"A token value for the datatype for a particular column. REMAP="BO--Body"In a few cases, the token value returned by this routine may not correspond exactly with the column's server datatype: MARK="BULL" REMAP="BU--Bullet"SYBVARCHAR is returned as SYBCHAR. SYBVARBINARY is returned as SYBBINARY. SYBDATETIMN is returned as SYBDATETIME. SYBMONEYN is returned as SYBMONEY. SYBFLTN is returned as SYBFLT8. SYBINTN is returned as SYBINT1, SYBINT2, or SYBINT4, depending on the actual type of the SYBINTN. REMAP="BO--Body"If the column number is not in range, MOREINFO="NONE"dbcoltype returns -1. CommentsMARK="BULL" REMAP="BU--Bullet"This routine returns the datatype for a regular (i.e., non-compute) result column. For a list of server datatypes, see the manual page for MOREINFO="NONE"types. MOREINFO="NONE"dbcoltype actually returns an integer token value for the datatype (SYBCHAR, SYBFLT8, etc.). To convert the token value into a readable token string, use MOREINFO="NONE"dbprtype. See the MOREINFO="NONE"dbprtype manual page for a list of all token values and their equivalent token strings. You can use MOREINFO="NONE"dbvarylen to determine whether a column's datatype is variable length. Here's a program fragment that uses MOREINFO="NONE"dbcoltype: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"DBPROCESS      *dbproc; int            colnum; int            coltype;                /* Put the command into the command buffer */               dbcmd(dbproc, "select name, id, type from                   sysobjects");                /* Send the command to SQL Server and begin              ** execution.              */               dbsqlexec(dbproc);                /* Process the command results */               dbresults(dbproc);                /* Examine the column types */               for (colnum = 1; colnum < 4; colnum++)               {                   coltype = dbcoltype(dbproc, colnum);                   printf("column %d, type is %s.\n", colnum,                    dbprtype(coltype));               } See AlsoREMAP="BO--Body"LINKEND="X80379"dbcollen
, LINKEND="X83710"dbcolname
, LINKEND="X69467"dbdata
, LINKEND="X61322"dbdatlen
, LINKEND="X66483"dbnumcols
, LINKEND="X77266"dbprtype
, LINKEND="X86715"dbvarylen
, LINKEND="X91146"types
ID="IN739-181313331"dbcoltype
   ID="IN7310-184316332"dbcolutypeID="X43711"dbcolutypeID="IN7415-184317334"Regular columnsreturning user-defined datatypes for
ID="IN749-184317335"Datatypesuser-defined:returning for regular columns
ID="IN7422-184317336"User-defined datatypesreturning for regular columns
Return the user-defined datatype for a regular result column. FORMAT="LINESPECIFIC"DBINT dbcolutype(dbproc, column)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS       *dbproc;FORMAT="LINESPECIFIC"int             column;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. column - The number of the column of interest. The first column is number 1. ReturnsREMAP="BO--Body"column's user-defined datatype on success; a negative integer on error. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbcolutype returns the user-defined datatype for a regular result column. For a description of how to add user-defined datatypes to SQL Server databases, see MOREINFO="NONE"sp_addtype in the  SQL Server Reference Manual.  For a  description of how to add user-defined datatypes to Open Server applications, see the Open Server documentation. MOREINFO="NONE"dbcolutype is defined as datatype DBINT to accommodate the size of user-defined datatypes. Both DBINT and user-defined datatypes are 32 bits long. The following code fragment illustrates the use of MOREINFO="NONE"dbcolutype: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"               DBPROCESS     *dbproc;                int           colnum;                int           numcols;                 /* Put the command into the command buffer */                dbcmd(dbproc, "select * from mytable");                 /*                ** Send the command to the SQL Server and begin               ** execution.                */                dbsqlexec(dbproc);                 /* Process the command results */                dbresults(dbproc);                 /* Examine the user-defined column types */                numcols =  dbnumcols(dbproc);                for (colnum = 1; colnum < numcols; colnum++)                {                     printf ("column %d, user-defined type is \                          %ld.\n", colnum, dbcolutype(dbproc,                         colnum));                } See AlsoREMAP="BO--Body"LINKEND="X18128"dbaltutype
, LINKEND="X35574"dbcoltype
ID="IN7410-187320342"dbcolutype
 ID="IN749-190323343"dbconvertID="X76814"dbconvertID="IN759-190324345"Datatypesconverting
Convert data from one datatype to another. FORMAT="LINESPECIFIC"DBINT dbconvert(dbproc, srctype, src, srclen,                 desttype, dest, destlen)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS      *dbproc;FORMAT="LINESPECIFIC"int            srctype;FORMAT="LINESPECIFIC"BYTE           *src;FORMAT="LINESPECIFIC"DBINT          srclen;FORMAT="LINESPECIFIC"int            desttype;FORMAT="LINESPECIFIC"BYTE           *dest;FORMAT="LINESPECIFIC"DBINT          destlen;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. In MOREINFO="NONE"dbconvert, the DBPROCESS is used only to supply any custom null values that the program may have specified via MOREINFO="NONE"dbsetnull. If dbproc is NULL, MOREINFO="NONE"dbconvert uses the default values for null value data conversions. srctype - The datatype of the data which is to be converted. This parameter can be any of the server datatypes, as listed in the first table below. src - A pointer to the data which is to be converted. If this pointer is NULL, MOREINFO="NONE"dbconvert will place an appropriate null value in the destination variable. You can use MOREINFO="NONE"dbdata to get the server data. srclen - The length, in bytes, of the data to be converted. If the srclen is 0, the source data is assumed to be null and MOREINFO="NONE"dbconvert will place an appropriate null value in the destination variable. Otherwise, this length is ignored for all datatypes except character, text, binary, and image. For SYBCHAR, SYBBOUNDARY, and SYBSENSITIVITY data, a length of -1 indicates that the string is null-terminated. You can use MOREINFO="NONE"dbdatlen to get the length of the server data. desttype - The datatype that the source data is to be converted into. This parameter can be any of the server datatypes, as listed in the first table below. dest - A pointer to the destination variable that will receive the converted data. If this pointer is NULL, MOREINFO="NONE"dbconvert will call the user-supplied error handler (if any) and return -1. destlen - The length, in bytes, of the destination variable. destlen is ignored for fixed-length datatypes. For a SYBCHAR, SYBBOUNDARY or SYBSENSITIVITY destination, the value of destlen  must be the total length of the destination buffer space. REMAP="UN--Under"The following table describes special values for destlen:TOCENTRY="1"LBL="Table 2-13: "Special values for destlen (MOREINFO="NONE"dbconvert)COLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="90*"COLNAME="C2" COLWIDTH="105*"COLNAME="C3" COLWIDTH="164*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Value of destlen:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Applicable to:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Means:VALIGN="TOP"COLNAME="C1" ALIGN="CENTER" ROTATE="0" MOREROWS="0"-1COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBCHAR, 
SYBBOUNDARY, 
SBYSENSITIVITYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"There is sufficient space available.

The string will be trimmed of 
trailing blanks and given a 
terminating null.COLNAME="C1" ALIGN="CENTER" ROTATE="0" MOREROWS="0"-2COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"There is sufficient space available.

The string will not be trimmed of 
trailing blanks, but will be given a 
terminating null.ReturnsID="IN7514-190324349"Error handlingError handlingand converting datatypesconverting datatypesREMAP="BO--Body"The length of the converted data, in bytes, if the datatype conversion succeeds.REMAP="BO--Body" If the conversion fails, MOREINFO="NONE"dbconvert returns  either -1 or FAIL,  depending on the cause of the failure. MOREINFO="NONE"dbconvert returns -1 to indicate a NULL destination pointer or an illegal datatype. MOREINFO="NONE"dbconvert returns FAIL to indicate other types of failures.REMAP="BO--Body"If MOREINFO="NONE"dbconvert fails, it will first call a user-supplied error handler (if any) and set the global DB-Library error value. REMAP="BO--Body"This routine may fail for several reasons: the requested conversion was not available; the conversion resulted in truncation, overflow, or loss of precision in the destination variable; or a syntax error occurred in converting a character string to some numeric type. CommentsMARK="BULL" REMAP="BU--Bullet"This routine allows the program to convert data from one representation to another. To determine whether a particular conversion is permitted, the program can call MOREINFO="NONE"dbwillconvert before attempting a conversion. ID="IN759-190324351"Datatypesserver
ID="IN756-190324352"ServerdatatypesMOREINFO="NONE"dbconvert can convert data stored in any of the server datatypes (although, of course, not all conversions are legal): TOCENTRY="1"LBL="Table 2-14: "Server and DB-Library datatypesCOLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="149*"COLNAME="C2" COLWIDTH="138*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Server typeCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Program variable type VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBCHARCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHAR COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBTEXTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHAR COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBBINARYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBBINARY COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBIMAGECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBBINARY COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBINT1COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBTINYINT COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBINT2COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBSMALLINT COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBINT4COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBINT COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBFLT8COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBFLT8 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBREALCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBREAL COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBNUMERICCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBNUMERICCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBDECIMALCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDECIMALCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBBITCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBBIT COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBMONEYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBMONEY COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBMONEY4COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBMONEY4 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBDATETIMECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATETIME COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBDATETIME4COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATETIME4 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBBOUNDARYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBSENSITIVITYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARID="IN759-190324353"Datatypesconversions supportedThe table below lists the datatype conversions that MOREINFO="NONE"dbconvert supports. The source datatypes are listed down the leftmost column and the destination datatypes are listed along the top row of the table. (For brevity, the prefix "SYB" has been eliminated from each datatype.) T (TRUE) indicates that the conversion is supported; F (FALSE) indicates that the conversion is not supported.FLOAT="0"FORMAT="UNKNOWN" FILEREF="fig2_1.xwd"LBL="Figure 2-1: "Supported datatype conversionsA conversion to or from the datatypes SYBBINARY and SYBIMAGE is a straight bit-copy, except when the conversion involves SYBCHAR or SYBTEXT. When converting SYBCHAR or SYBTEXT data to SYBBINARY or SYBIMAGE, DBCONVERT interprets the SYBCHAR or SYBTEXT string as hexadecimal, whether or not the string contains a leading "0x". When converting SYBBINARY or SYBIMAGE data to SYBCHAR or SYBTEXT, MOREINFO="NONE"dbconvert creates a hexadecimal string without a leading "0x". Note that SYBINT2 and SYBINT4 are signed types.  When  converting these types to character, conversion error can result if the quantity being converted is unsigned and uses the high bit. Converting a SYBMONEY, SYBCHAR, or SYBTEXT value to  SYBFLT8 may result in some loss of precision. Converting a SYBFLT8 value to SYBCHAR or SYBTEXT may also  result in some loss of precision. Converting a SYBFLT8 value to SYBMONEY can result in overflow,  because the maximum value for SYBMONEY is $922,337,203,685,477.58. If overflow occurs when converting integer or float data to  SYBCHAR or SYBTEXT, the first character of the resulting value will contain an  asterisk ("*") to indicate the error. A conversion to SYBBIT has the following effect: If the value being converted is not 0, the SYBBIT value will be set to 1; if the value is 0, the SYBBIT value will be set to 0. MOREINFO="NONE"dbconvert does not offer precision and scale support for numeric and decimal types. When converting to SYBNUMERIC or SYBDECIMAL, MOREINFO="NONE"dbconvert uses a default precision and scale of 18 and 0, respectively. To specify a different precision and scale, an application can use MOREINFO="NONE"dbconvert_ps.SYBBOUNDARY and SYBSENSITIVITY destinations are always null-terminated.ID="IN759-190324354"Datatypesconverting to sameIn certain cases, it can be useful to convert a datatype to itself. For instance, a conversion of SYBCHAR to SYBCHAR with a destlen of -1 serves as a useful way to append a null terminator to a string, as the example below illustrates. Here's a short example that illustrates how to convert server data obtained with MOREINFO="NONE"dbdata: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"DBCHAR      title[81]; DBCHAR      price[9];  /* Read the query into the command buffer */ dbcmd(dbproc, "select title, price, royalty from \     pubs2..titles");  /* Send the query to SQL Server */ dbsqlexec(dbproc);  /* Get ready to process the query results */ dbresults(dbproc);  /* Process each row */ while (dbnextrow(dbproc) != NO_MORE_ROWS) {      /*      ** The first dbconvert() adds a null     ** terminator to the string.      */      dbconvert(dbproc, SYBCHAR, (dbdata(dbproc,1)),          (dbdatlen(dbproc,1)), SYBCHAR, title,          (DBINT)-1);      /*      ** The second dbconvert() converts money to     ** string.      */      dbconvert(dbproc, SYBMONEY,          (dbdata(dbproc,2)), (DBINT)-1, SYBCHAR,          price, (DBINT)-1);       if (dbdatlen(dbproc,3) != 0)           printf ("%s\n $%s  %ld\n", title, price,            *((DBINT *)dbdata(dbproc,3))); } REMAP="UN--Under"In the MOREINFO="NONE"dbconvert calls it was not necessary to  cast the returns from MOREINFO="NONE"dbdata, because MOREINFO="NONE"dbdata returns a BYTE pointer-precisely the datatype MOREINFO="NONE"dbconvert expects in the third parameter. If you're binding data to variables with MOREINFO="NONE"dbbind  rather than accessing the data directly with MOREINFO="NONE"dbdata, MOREINFO="NONE"dbbind can perform the conversions itself,  making MOREINFO="NONE"dbconvert unnecessary. OS/2 and NetWare programmers: When MOREINFO="NONE"dbconvert is used to convert a money value to  a character type, the resulting string only contains two  decimal places.  On other platforms, money to character conversions result in a string containing four decimal places. Example 5 of the on-line example programs illustrates several more types of conversions using MOREINFO="NONE"dbconvert. For more information on server datatypes, see the  SQL Server Reference Manual and the MOREINFO="NONE"types manual page in this document. See AlsoREMAP="BO--Body"LINKEND="X21854"dbaltbind
, LINKEND="X32323"dbaltbind_ps
, LINKEND="X14206"dbbind
, LINKEND="X81674"dbbind_ps
, LINKEND="X80440"dbconvert_ps
, LINKEND="X12458"dberrhandle
, LINKEND="X70360"dbsetnull
, LINKEND="X17556"dbwillconvert
, LINKEND="X47604"errors
, LINKEND="X91146"types
ID="IN759-193327356"dbconvert
   ID="IN7512-196330357"dbconvert_psID="X80440"dbconvert_psID="IN769-196331359"Datatypesconverting
Convert data from one datatype to another, with precision and scale support for numeric and decimal types.FORMAT="LINESPECIFIC"DBINT dbconvert_ps(dbproc, srctype, src, srclen,                 desttype, dest, destlen, typeinfo)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS        *dbproc;FORMAT="LINESPECIFIC"int              srctype;FORMAT="LINESPECIFIC"BYTE             *src;FORMAT="LINESPECIFIC"DBINT            srclen;FORMAT="LINESPECIFIC"int              desttype;FORMAT="LINESPECIFIC"BYTE             *dest;FORMAT="LINESPECIFIC"DBINT            destlen;FORMAT="LINESPECIFIC"DBTYPEINFO       *typeinfo;ParametersMOREINFO="NONE"dbconvert_ps's parameters are identical to MOREINFO="NONE"dbconvert's, except thatMOREINFO="NONE" dbconvert_ps has the additional parameter typeinfo, which contains information about precision and scale for numeric or decimal variables.REMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. In MOREINFO="NONE"dbconvert_ps, the DBPROCESS is used only to supply any custom null values that the program may have specified via MOREINFO="NONE"dbsetnull. If dbproc is NULL, MOREINFO="NONE"dbconvert_ps uses the default values for null value data conversions. srctype - The datatype of the data which is to be converted. This parameter can be any of the server datatypes, as listed in the first table below. src - A pointer to the data which is to be converted. If this pointer is NULL, MOREINFO="NONE"dbconvert_ps will place an appropriate null value in the destination variable. You can use MOREINFO="NONE"dbdata to get the server data. srclen - The length, in bytes, of the data to be converted. If the srclen is 0, the source data is assumed to be null and MOREINFO="NONE"dbconvert_ps will place an appropriate null value in the destination variable. Otherwise, this length is ignored for all datatypes except character, text, binary, and image. For SYBCHAR data, a length of -1 indicates that the string is null-terminated. You can use MOREINFO="NONE"dbdatlen to get the length of the server data. desttype - The datatype that the source data is to be converted into. This parameter can be any of the server datatypes, as listed in the first table below. dest - A pointer to the destination variable that will receive the converted data. If this pointer is NULL, MOREINFO="NONE"dbconvert_ps will call the user-supplied error handler (if any) and return -1. destlen - The length, in bytes, of the destination variable. destlen is ignored for fixed-length datatypes. For a SYBCHAR, SYBBOUNDARY, or SYBSENSITIVITY destination, the value of destlen  must be the total length of the destination buffer space. REMAP="UN--Under"The following table describes special values for destlen:TOCENTRY="1"LBL="Table 2-15: "Special values for destlen (MOREINFO="NONE"dbconvert_ps)COLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="90*"COLNAME="C2" COLWIDTH="105*"COLNAME="C3" COLWIDTH="164*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Value of destlen:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Applicable to:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Means:VALIGN="TOP"COLNAME="C1" ALIGN="CENTER" ROTATE="0" MOREROWS="0"-1COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBCHAR, 
SYBBOUNDARY, 
SBYSENSITIVITYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"There is sufficient space available.

The string will be trimmed of 
trailing blanks and given a 
terminating null.COLNAME="C1" ALIGN="CENTER" ROTATE="0" MOREROWS="0"-2COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"There is sufficient space available.

The string will not be trimmed of 
trailing blanks, but will be given a 
terminating null.typeinfo - A pointer to a DBTYPEINFO structure containing information about the precision and scale of decimal or numeric destinations. An application sets a DBTYPEINFO structure with values for precision and scale before calling MOREINFO="NONE"dbconvert_ps to convert data to decimal or numeric types.REMAP="UN--Under"If typeinfo is NULL:MARK="DASH" REMAP="BS--BulletSub"If the source value is of type SYBNUMERIC or SYBDECIMAL, MOREINFO="NONE"dbconvert_ps picks up precision and scale values from the source. In effect, the source data is copied to the destination space.If the source value is not SYBNUMERIC or SYBDECIMAL, MOREINFO="NONE"dbconvert_ps uses a default precision of 18 and a default scale of 0.REMAP="UN--Under"If srctype is not SYBDECIMAL or SYBNUMERIC, typeinfo is ignored.REMAP="UN--Under"A DBTYPEINFO structure is defined as follows:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"typedef struct typeinfo {     DBINT    precision;     DBINT    scale;} DBTYPEINFO;REMAP="UN--Under"Legal values for precision are from 1 to 77. Legal values for scale are from 0 to 77. scale must be less than or equal to precision.ReturnsID="IN7614-196331363"Error handlingError handlingand converting datatypesconverting datatypesREMAP="BO--Body"The length of the converted data, in bytes, if the datatype conversion succeeds.REMAP="BO--Body" If the conversion fails, MOREINFO="NONE"dbconvert_ps returns either -1 or FAIL, depending on the cause of the failure. MOREINFO="NONE"dbconvert_ps returns -1 to indicate a NULL destination pointer or an illegal datatype. MOREINFO="NONE"dbconvert_ps returns FAIL to indicate other types of failures.REMAP="BO--Body" If MOREINFO="NONE"dbconvert_ps fails, it will first call a user-supplied error handler (if any) and set the global DB-Library error value. REMAP="BO--Body"This routine may fail for several reasons: the requested conversion was not available; the conversion resulted in truncation, overflow, or loss of precision in the destination variable; or a syntax error occurred in converting a character string to some numeric type. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbconvert_ps is the equivalent of MOREINFO="NONE"dbconvert, except that MOREINFO="NONE"dbconvert_ps provides precision and scale support for numeric and decimal datatypes, which MOREINFO="NONE"dbconvert does not. Calling MOREINFO="NONE"dbconvert is equivalent to calling MOREINFO="NONE"dbconvert_ps with typeinfo as NULL.MOREINFO="NONE"dbconvert_ps  allows a program to convert data from one representation to another. To determine whether a particular conversion is permitted, the program can call MOREINFO="NONE"dbwillconvert before attempting a conversion. ID="IN769-196331365"Datatypesserver
ID="IN766-196331366"Serverdatatypes
MOREINFO="NONE"dbconvert_ps can convert data stored in any of the server datatypes (although, of course, not all conversions are legal):TOCENTRY="1"LBL="Table 2-16: "Server and DB-Library datatypesCOLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="149*"COLNAME="C2" COLWIDTH="138*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Server typeCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Program variable type VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBCHARCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHAR COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBTEXTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHAR COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBBINARYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBBINARY COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBIMAGECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBBINARY COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBINT1COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBTINYINT COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBINT2COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBSMALLINT COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBINT4COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBINT COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBFLT8COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBFLT8 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBREALCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBREAL COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBNUMERICCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBNUMERICCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBDECIMALCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDECIMALCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBBITCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBBIT COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBMONEYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBMONEY COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBMONEY4COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBMONEY4 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBDATETIMECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATETIME COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBDATETIME4COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATETIME4 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBBOUNDARYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBSENSITIVITYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARID="IN769-196331367"Datatypesconversions supportedThe table below lists the datatype conversions that MOREINFO="NONE"dbconvert supports. The source datatypes are listed down the leftmost column and the destination datatypes are listed along the top row of the table. ID="IN769-196331368"Datatypesconversions supportedThe table below lists the datatype conversions that MOREINFO="NONE"dbconvert_ps supports. The source datatypes are listed down the leftmost column and the destination datatypes are listed along the top row of the table. (For brevity, the prefix "SYB" has been eliminated from each datatype.) T (TRUE) indicates that the conversion is supported; F (FALSE) indicates that the conversion is not supported.FLOAT="0"FORMAT="UNKNOWN" FILEREF="fig2_2.xwd"LBL="Figure 2-2: "Supported datatype conversionsA conversion to or from the datatypes SYBBINARY and SYBIMAGE is a straight bit-copy, except when the conversion involves SYBCHAR or SYBTEXT. When converting SYBCHAR or SYBTEXT data to SYBBINARY or SYBIMAGE, MOREINFO="NONE"dbconvert_ps interprets the SYBCHAR or SYBTEXT string as hexadecimal, whether or not the string contains a leading "0x". When converting SYBBINARY or SYBIMAGE data to SYBCHAR or SYBTEXT, MOREINFO="NONE"dbconvert_ps creates a hexadecimal string without a leading "0x". Note that SYBINT2 and SYBINT4 are signed types.  When  converting these types to character, conversion error can result if the quantity being converted is unsigned and uses the high bit. Converting a SYBMONEY, SYBCHAR, or SYBTEXT value to  SYBFLT8 may result in some loss of precision. Converting a SYBFLT8 value to SYBCHAR or SYBTEXT may also  result in some loss of precision. Converting a SYBFLT8 value to SYBMONEY can result in overflow,  because the maximum value for SYBMONEY is $922,337,203,685,477.58. If overflow occurs when converting integer or float data to  SYBCHAR or SYBTEXT, the first character of the resulting value will contain an  asterisk ("*") to indicate the error. A conversion to SYBBIT has the following effect: If the value being converted is not 0, the SYBBIT value will be set to 1; if the value is 0, the SYBBIT value will be set to 0. SYBBOUNDARY and SYBSENSITIVITY destinations are always null-terminated.ID="IN769-196331369"Datatypesconverting to sameIn certain cases, it can be useful to convert a datatype to itself. For instance, a conversion of SYBCHAR to SYBCHAR with a destlen of -1 serves as a useful way to append a null terminator to a string.If you're binding data to variables with MOREINFO="NONE"dbbind or MOREINFO="NONE"dbbind_ps rather than accessing the data directly with MOREINFO="NONE"dbdata, MOREINFO="NONE"dbbind can perform the conversions itself,  making MOREINFO="NONE"dbconvert_ps unnecessary. OS/2 and NetWare programmers: When MOREINFO="NONE"dbconvert_ps is used to convert a money value to  a character type, the resulting string only contains two  decimal places.  On other platforms, money to character conversions result in a string containing four decimal places. Example 5 of the on-line example programs illustrates several more types of conversions using MOREINFO="NONE"dbconvert_ps. For more information on server datatypes, see the SQL Server Reference Manual and the MOREINFO="NONE"types manual page in this document. See AlsoREMAP="BO--Body"LINKEND="X21854"dbaltbind
, LINKEND="X32323"dbaltbind_ps
, LINKEND="X14206"dbbind
, LINKEND="X81674"dbbind_ps
, LINKEND="X76814"dbconvert
, LINKEND="X12458"dberrhandle
, LINKEND="X70360"dbsetnull
, LINKEND="X17556"dbwillconvert
, LINKEND="X47604"errors
, LINKEND="X91146"types
ID="IN7612-199334371"dbconvert_ps
 ID="IN767-202337372"DBCOUNTDBCOUNTID="IN774-202338374"Rowsreturning number affected by a command
ID="IN778-202338375"Commandsreturning number of rows affected by
Return the number of rows affected by a Transact-SQL command. FORMAT="LINESPECIFIC"DBINT DBCOUNT(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS      *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. ReturnsID="IN7716-208344379"DBNOCOUNT optionDBNOCOUNT optionand DBCOUNTDBCOUNTREMAP="BO--Body"The number of rows affected by the command, or -1. DBCOUNT will return -1 if any of the following are true: MARK="BULL" REMAP="BU--Bullet"The Transact-SQL command fails for any reason, such as a syntax error. The command is one that never affects rows, such as a MOREINFO="NONE"print command. The command executes a stored procedure that does not execute any MOREINFO="NONE"select statements. The DBNOCOUNT option is on. CommentsMARK="BULL" REMAP="BU--Bullet"Once the results of a command have been processed, you can call MOREINFO="NONE"DBCOUNT to find out how many rows were affected by the command. For example, if a MOREINFO="NONE"select command was sent to the server and you have read all the rows by calling MOREINFO="NONE"dbnextrow until it returned NO_MORE_ROWS, you can call this macro to find out how many rows were retrieved. If the current command is one that doesn't return rows, (for example, a MOREINFO="NONE"delete), you can call DBCOUNT immediately after MOREINFO="NONE"dbresults. If the command is one that executes a stored procedure, for example an MOREINFO="NONE"exec or remote procedure call,  DBCOUNT returns the number of rows  returned by the latest MOREINFO="NONE"select statement executed by the stored procedure, or -1  if the stored procedure does not execute any MOREINFO="NONE"select statements. Note that a stored procedure which contains no MOREINFO="NONE"select statements may execute a MOREINFO="NONE"select by calling another stored procedure which contains a MOREINFO="NONE"select. See AlsoREMAP="BO--Body"LINKEND="X10726"dbnextrow
, LINKEND="X35104"dbresults
, LINKEND="X60647"options
ID="IN777-211347382"DBCOUNT
 ID="IN778-214350383"DBCURCMDDBCURCMDID="IN788-214351385"Commandsreturning number of current
Return the number of the current command. FORMAT="LINESPECIFIC"int DBCURCMD(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. ReturnsREMAP="BO--Body"The number of the current command. CommentsMARK="BULL" REMAP="BU--Bullet"This macro returns the number of the command whose results are currently being processed. The first command in a batch is number 1.  The command number is incremented every time MOREINFO="NONE"dbresults returns SUCCEED or FAIL. (Unsuccessful commands are counted.) The command number is reset by each call to MOREINFO="NONE"dbsqlexec or MOREINFO="NONE"dbsqlsend. See AlsoREMAP="BO--Body"LINKEND="X17006"DBCMDROW
, LINKEND="X78556"DBMORECMDS
, LINKEND="X87634"DBROWS
ID="IN788-217354391"DBCURCMD
 ID="IN788-220357392"DBCURROWID="X17373"DBCURROWID="IN794-220358394"Rowsreturning number of current
Return the number of the row currently being read. FORMAT="LINESPECIFIC"DBINT DBCURROW(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS      *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. ReturnsREMAP="BO--Body"The number of the current row. This routine returns 0 if no rows have been processed yet. CommentsMARK="BULL" REMAP="BU--Bullet"This macro returns the number of the row currently being read. Rows are counted from the first row returned from the server, whose number is 1, and not from the top of the row buffer, if any. The row number changes every time MOREINFO="NONE"dbnextrow or MOREINFO="NONE"dbgetrow returns SUCCEED. The row number is reset to 0 by each new call to MOREINFO="NONE"dbresults. See AlsoREMAP="BO--Body"LINKEND="X38617"dbclrbuf
, LINKEND="X66598"DBFIRSTROW
, LINKEND="X71422"dbgetrow
, LINKEND="X20854"DBLASTROW
, LINKEND="X10726"dbnextrow
, LINKEND="X97776"dbsetopt
, LINKEND="X60647"options
ID="IN798-223361400"DBCURROW
 ID="X99424"ID="IN808-226365401"dbcursor
dbcursorID="IN806-226365402"Cursorupdating
Inserts, updates, deletes, locks, or refreshes a particular row in the fetch buffer.FORMAT="LINESPECIFIC"RETCODE dbcursor(hc, optype, bufno, table, values)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBCURSOR      *hc;FORMAT="LINESPECIFIC"SHORT         optype;FORMAT="LINESPECIFIC"SHORT         bufno;FORMAT="LINESPECIFIC"BYTE          *table;FORMAT="LINESPECIFIC"BYTE          *valuesParametersREMAP="RI--RefIndent"hc - Cursor handle previously returned by MOREINFO="NONE"dbcursoropen.optype - Type of operation to perform:TOCENTRY="1"LBL="Table 2-17: "Values for optype (MOREINFO="NONE"dbcursor)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="126*"COLNAME="C2" COLWIDTH="234*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Symbolic ValueCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"OperationVALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CRS_UPDATECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Updates data.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CRS_DELETECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Deletes data.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CRS_INSERTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Inserts data.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CRS_REFRESHCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetches another row in the buffer.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CRS_LOCKCCCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetches another row and locks it. The row is 
actually locked only if inside a transaction block. 
The lock is released when the application commits 
or ends the transaction.bufno - Row number in the fetch buffer to which the operation applies. The specified buffer must contain a valid row. If the value of bufno is 0, a CRS_REFRESH operation applies to all rows in the buffer. In an MOREINFO="NONE"insert or MOREINFO="NONE"update operation where no values parameter is given, the values are read from the bound variables array in the corresponding bufno value. The number of the first row in the buffer is 1.table - The table to be inserted, updated, deleted, or locked if the cursor declaration contains more than one table. If there is only one table, this parameter is not required.values - String values to be updated and/or inserted. Use this parameter only with MOREINFO="NONE"update and MOREINFO="NONE"insert to specify the new column values (that is, Quantity = Quantity + 1). In most cases, you can set this parameter to NULL and the new values for each column are taken from the fetch buffer (the program variable specified by MOREINFO="NONE"dbcursorbind). If the MOREINFO="NONE"select statement includes a computation (that is, MOREINFO="NONE"select 5*5...) and a function (for example, MOREINFO="NONE"select MOREINFO="NONE"getdate(), MOREINFO="NONE"convert(), and so on), then updating through the buffer array will surely not work.REMAP="UN--Under"There are four possible formats for this parameter: two for updating and two for inserting. The chosen format must match the optype (MOREINFO="NONE"update or MOREINFO="NONE"insert). Both contain a full and an abbreviated format. The full format is a complete SQL statement (MOREINFO="NONE"update or MOREINFO="NONE"insert) without a MOREINFO="NONE"where clause. The abbreviated format is just the MOREINFO="NONE"set clause (MOREINFO="NONE"update) or just the MOREINFO="NONE"values clause (MOREINFO="NONE"insert). When the full format is used, the value specified for tablename overrides the table parameter of MOREINFO="NONE"dbcursor. Because a MOREINFO="NONE"where clause is added automatically, do not include one.ReturnsREMAP="BO--Body"SUCCEED or FAIL. This function can fail for the following reasons:MARK="BULL" REMAP="BU--Bullet"Cursor is opened as read only, no updates allowed.Server or connection failure or timeout.No permission to update or change the database.A trigger in the database caused the MOREINFO="NONE"lock or MOREINFO="NONE"update/insert operation to fail.Optimistic concurrency control.CommentsMARK="BULL" REMAP="BU--Bullet"If a column used as a unique index column is updated or changed, the corresponding row appears to be missing the next time it is fetched.For more information on cursors, see LINKEND="X76241"Appendix A, "Cursors."See AlsoREMAP="BO--Body"LINKEND="X96617"dbcursorbind
, LINKEND="X25653"dbcursorclose
, LINKEND="X15626"dbcursorcolinfo
, LINKEND="X10062"dbcursorfetch
, LINKEND="X67036"dbcursorinfo
, LINKEND="X51048"dbcursoropenID="X96617"ID="IN8112-229369409"dbcursorbind
dbcursorbindID="IN816-229369410"Cursorbinding
Registers the binding information on the cursor columns.FORMAT="LINESPECIFIC"RETCODE dbcursorbind(hc, col, vartype, varlen,              poutlen, pvaraddr)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBCURSOR      hc;FORMAT="LINESPECIFIC"int           col;FORMAT="LINESPECIFIC"int           vartype;FORMAT="LINESPECIFIC"DBINT         varlen;FORMAT="LINESPECIFIC"DBINT         *poutlen;FORMAT="LINESPECIFIC"BYTE          *pvaraddr;ParametersREMAP="RI--RefIndent"hc - Cursor handle created by MOREINFO="NONE"dbcursoropen.col - Number of the column to be bound to a program variable.vartype - Binding type, which uses the same datatypes as the vartype parameter for MOREINFO="NONE"dbbind and is bound by the same conversion rules. If this value is set to NOBIND for any column, the data is not bound. Instead, a pointer to the data is returned to the address in the corresponding pvaraddr entry for every row, and the length of the data is returned to the corresponding varlen array entry. This feature lets the application access the cursor data as it does with MOREINFO="NONE"dbdata and MOREINFO="NONE"dbdatalen.varlen - Maximum length of variable-length datatype, such as CHARBIND, VARYCHARBIND, BINARYBIND, STRINGBIND, NTBSTRINGBIND, and VARYBINBIND. This parameter is ignored for fixed-length datatypes, such as INTBIND, FLT8BIND, MONEYBIND, BITBIND, SMALLBIND, and so on. It is also ignored if the vartype is NOBIND.poutlen - Pointer to an array of long integers where the actual length of the column's data is returned for each row. If poutlen is set to NULL, the lengths are not returned. The array size must be large enough to hold one DBINT variable for every row to be fetched at a time (as indicated by the nrows parameter in MOREINFO="NONE"dbcursoropen).REMAP="UN--Under"When using MOREINFO="NONE"dbcursor to update or insert with values from bound program variables, you can specify a null value by setting the corresponding poutlen to zero before calling MOREINFO="NONE"dbcursor. Nonzero values are ignored except when NOBIND or one of the variable-length datatypes such as VARYCHARBIND or VARYBINBIND has been specified. In that case poutlen must contain the actual item length. If STRINGBIND or NTBSTRINGBIND has been specified, any nonzero value for poutlen is ignored, and the length of the string is determined by scanning for the null terminator.pvaraddr - Pointer to the program variable to which the data is copied. If vartype is NOBIND, pvaraddr is assumed to point to an array of pointers - to the address of the actual data fetched by MOREINFO="NONE"dbcursorfetch. This array's length must equal the value of nrows in MOREINFO="NONE"dbcursoropen. If the cursor was opened with nrows > 1, pvaraddr is assumed to point to an array of nrows elements. Calling MOREINFO="NONE"dbcursorbind with pvaraddr set to NULL breaks the existing binding.ReturnsREMAP="BO--Body"SUCCEED or FAIL.CommentsMARK="BULL" REMAP="BU--Bullet"If MOREINFO="NONE"dbcursorbind is called more than once for any column, only the last call is effective.This function works almost the same as MOREINFO="NONE"dbbind without cursors.For more information on cursors, see LINKEND="X76241"Appendix A, "Cursors"
.See AlsoREMAP="BO--Body"LINKEND="X99424"dbcursor
, LINKEND="X25653"dbcursorclose
, LINKEND="X15626"dbcursorcolinfo
, LINKEND="X10062"dbcursorfetch
, LINKEND="X67036"dbcursorinfo
, LINKEND="X51048"dbcursoropenID="X25653"ID="IN8213-232373417"dbcursorclose
dbcursorcloseID="IN826-232373418"Cursorclosing
Closes the cursor associated with the given handle, releasing all the data belonging to it.FORMAT="LINESPECIFIC"void dbcursorclose(hc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBCURSOR     *hc;ParametersREMAP="BO--Body"hc - Cursor handle created by MOREINFO="NONE"dbcursoropen.ReturnsREMAP="BO--Body"None.CommentsMARK="BULL" REMAP="BU--Bullet"Closing a DBPROCESS connection with MOREINFO="NONE"dbcursorclose automatically closes all the cursors associated with it. After issuing MOREINFO="NONE"dbcursorclose, the cursor handle should not be used.For more information on cursors, see LINKEND="X76241"Appendix A, "Cursors"
.See AlsoREMAP="BO--Body"LINKEND="X99424"dbcursor
, LINKEND="X96617"dbcursorbind
, LINKEND="X15626"dbcursorcolinfo
, LINKEND="X10062"dbcursorfetch
, LINKEND="X67036"dbcursorinfo
, LINKEND="X51048"dbcursoropenID="X15626"ID="IN8315-235377425"dbcursorcolinfo
dbcursorcolinfoID="IN836-235377426"Cursorretrieving column information for
Returns column information for the specified column number in the open cursor.FORMAT="LINESPECIFIC"RETCODE dbcursorcolinfo(hcursor, column,
colname,              coltype, collen, usertype)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBCURSOR      *hcursorFORMAT="LINESPECIFIC"int           column;FORMAT="LINESPECIFIC"char          *colname;FORMAT="LINESPECIFIC"int           *coltype;FORMAT="LINESPECIFIC"DBINT         *collen;FORMAT="LINESPECIFIC"int           *usertype;ParametersREMAP="RI--RefIndent"hcursor - Cursor handle created by MOREINFO="NONE"dbcursoropen.column - Column number for which information is to be returned.colname - Location where to return the name of the column. The user should allocate space large enough to accommodate the column name.coltype - Location where to return the column's datatype.collen - Location where to return the column's maximum length.usertype - Location where to return the column's user-defined datatype.ReturnsREMAP="BO--Body"SUCCEED or FAIL.CommentsMARK="BULL" REMAP="BU--Bullet"Any of the parameters colname, coltype, collen, or usertype can be set to NULL, in which case the information for that variable is not returned.For more information on cursors, see LINKEND="X76241"Appendix A, "Cursors".See AlsoREMAP="BO--Body"LINKEND="X99424"dbcursor
, LINKEND="X96617"dbcursorbind
, LINKEND="X25653"dbcursorclose
, LINKEND="X10062"dbcursorfetch
, LINKEND="X67036"dbcursorinfo
, LINKEND="X51048"dbcursoropenID="X10062"ID="IN8413-238381433"dbcursorfetch
dbcursorfetchID="IN846-238381434"Cursorfetching against
Fetches a block of rows into the program variables declared by the user in MOREINFO="NONE"dbcursorbind.FORMAT="LINESPECIFIC"RETCODE dbcursorfetch(hc, fetchtype, rownum)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBCURSOR     *hc;FORMAT="LINESPECIFIC"SHORT        fetchtype;FORMAT="LINESPECIFIC"SHORT        rownum;ParametersREMAP="RI--RefIndent"hc - Cursor handle created by MOREINFO="NONE"dbcursoropen.fetchtype - Type of fetch chosen. The scroll option in MOREINFO="NONE"dbcursoropen determines which of these values are legal:TOCENTRY="1"LBL="Table 2-18: "Values for fetchtype (MOREINFO="NONE"dbcursorfetch)COLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="99*"COLNAME="C2" COLWIDTH="81*"COLNAME="C3" COLWIDTH="180*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Symbolic ValueCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MeaningCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CommentVALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"FETCH_FIRSTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetch the first 
block of rows.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Although available for all cursor 
types, this option is especially useful 
for returning to the beginning of a 
keyset when you've selected a 
forward-only scrolling cursor.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"FETCH_NEXTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetch the next 
block of rows.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"If the result set exceeds the specified 
keyset size and if FETCH_RANDOM 
and/or FETCH_RELATIVE have 
been issued, a FETCH_NEXT can 
span a keyset boundary. In this case, 
the fetch that spans a keyset 
boundary returns a partial buffer, and 
the next fetch shifts down the keyset 
and returns the next full set of rows.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"FETCH_PREVCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetch the 
previous block 
of rows.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"This option is unavailable with 
forward-only scrolling cursors. If 
rownum falls within the keyset, the 
range of rows must stay within the 
keyset because only the rows within 
the keyset are returned. This option 
does not change the keyset to the 
previous rownum rows in the result 
set.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"FETCH_RANDOMCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetch a block of 
rows, starting 
from the 
specified row 
number within 
the keyset.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"This option is valid only within the 
keyset. The buffer is only partially 
filled when the range spans the keyset 
boundary.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"FETCH_RELATIVECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetch a block of 
rows, relative 
to the number 
of rows 
indicated in the 
last fetch.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"This option jumps rownum rows from 
the first row of the last fetch and starts 
fetching from there. The rows must 
remain within the keyset. The buffer 
is only partially filled when the range 
spans the keyset boundary.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"FETCH_LASTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetch the last 
block of rows.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"This value is available only with 
totally keyset-driven cursors.rownum - The specified row for the buffer to start filling. Use this parameter only with a fetchtype of FETCH_RANDOM or FETCH_RELATIVE.ReturnsREMAP="BO--Body"SUCCEED or FAIL. If the status array contains a status row for every row fetched, SUCCEED is returned. FAIL is returned if at least one of the following is true.MARK="BULL" REMAP="BU--Bullet"FETCH_RANDOM and FETCH_RELATIVE require a keyset driven cursor.Forward-only scrolling can use only FETCH_FIRST and FETCH_NEXT.The server or a connection fails or takes a timeout.The server is out of memory.The FETCH_LAST option requires a fully keyset-driven cursor.CommentsMARK="BULL" REMAP="BU--Bullet"Specify the size of the fetch buffer in MOREINFO="NONE"dbcursoropen.Program variables must first be registered, using MOREINFO="NONE"dbcursorbind. Then the data can be transferred into the DB-Library buffers. The bound variables must, therefore, be arrays large enough to hold the specified number of rows. The status array contains status code for every row and contains flags for missing rows.When the range of rows specified by FETCH_NEXT, FETCH_RANDOM, or FETCH_RELATIVE spans a keyset boundary, only the rows remaining in the keyset are returned. In this case, the buffer is only partially filled, and the FETCH_ENDOFKEYSET flag is set as the status of the last row. The following FETCH_NEXT shifts the keyset down.For more information on cursors, see LINKEND="X76241"Appendix, "Cursors"
.See AlsoREMAP="BO--Body"LINKEND="X99424"dbcursor
, LINKEND="X96617"dbcursorbind
, LINKEND="X25653"dbcursorclose
, LINKEND="X15626"dbcursorcolinfo
, LINKEND="X67036"dbcursorinfo
, LINKEND="X51048"dbcursoropen
ID="IN8413-241384441"dbcursorfetch
 ID="X67036"ID="IN8512-244388442"dbcursorinfo
dbcursorinfo
ID="IN856-244388444"Cursorretrieving information about
Returns the number of columns and the number of rows in the keyset if the keyset hit the end of the result set.FORMAT="LINESPECIFIC"RETCODE dbcursorinfo(hcursor, ncols, nrows);FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBCURSOR      *hcursor;FORMAT="LINESPECIFIC"int           *ncolsFORMAT="LINESPECIFIC"DBINT         *nrows;ParametersREMAP="RI--RefIndent"hcursor - Cursor handle created by MOREINFO="NONE"dbcursoropen.ncols - Location where to return the number of columns in the cursor.nrows - Location where to return the number of rows in the keyset.ReturnsREMAP="BO--Body"SUCCEED or FAIL.CommentsMARK="BULL" REMAP="BU--Bullet"For fully keyset-driven cursors, the nrows parameter contains the number of rows in the keyset. For mixed or dynamic cursors, nrows is always set to -1, unless the keyset is the last one in the result set. In that case, the number of rows in the keyset is returned. This helps the programmer find out when the keyset has hit the end of the result set.For more information on cursors, see LINKEND="X76241"Appendix A,  "Cursors."See AlsoREMAP="BO--Body"LINKEND="X99424"dbcursor
, LINKEND="X96617"dbcursorbind
, LINKEND="X25653"dbcursorclose
, LINKEND="X15626"dbcursorcolinfo
, LINKEND="X10062"dbcursorfetch
, LINKEND="X51048"dbcursoropenID="X51048"ID="IN8612-247392451"dbcursoropen
dbcursoropenID="IN866-247392452"Cursoropening
Opens a cursor, specifying the scroll option, concurrency option, and the size of the fetch buffer (the number of rows retrieved with a single fetch).FORMAT="LINESPECIFIC"hc=dbcursoropen(dbproc, stmt, scrollopt, concuropt,             nrows, pstatus)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"BYTE         *stmt;FORMAT="LINESPECIFIC"SHORT        scrollopt;FORMAT="LINESPECIFIC"SHORT        concuropt;FORMAT="LINESPECIFIC"USHORT       nrows;FORMAT="LINESPECIFIC"DBINT        *pstatusParametersREMAP="RI--RefIndent"hc - Cursor used by subsequent functions that operate on this cursor.dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. stmt - The MOREINFO="NONE"select statement that defines a cursor.scrollopt - Indicator of the desired scrolling technique.REMAP="UN--Under"Keyset driven fixes membership in the result set and order at cursor open time.REMAP="UN--Under"Dynamic determines membership in the result set and order at fetch time. REMAP="UN--Under"Possible values for scrollopt are as follows:TOCENTRY="1"LBL="Table 2-19: "Values  for scrollopt (MOREINFO="NONE"dbcursoropen)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="90*"COLNAME="C2" COLWIDTH="270*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Symbolic ValueCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MeaningVALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CUR_FORWARDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Forward scrolling only.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CUR_KEYSETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Keyset driven.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CUR_DYNAMICCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fully dynamic.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"int nCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Keyset-driven cursor within (n*nrows) blocks, but fully 
dynamic outside the keyset.concuropt - Definition of concurrency control:TOCENTRY="1"LBL="Table 2-20: "Values  for concuropt (MOREINFO="NONE"dbcursoropen)COLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="99*"COLNAME="C2" COLWIDTH="126*"COLNAME="C3" COLWIDTH="135*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Symbolic ValueCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MeaningCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ExplanationVALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CUR_READONLYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Read-only cursor.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The data cannot be 
modified.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CUR_LOCKCCCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Intent to update locking.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"All data, if inside a 
transaction block, is locked 
out as it is fetched through 
MOREINFO="NONE"dbcursorfetch.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CUR_OPTCCCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Optimistic concurrency 
control, based on 
timestamp values.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"In a given row, 
modifications to the data 
succeed only if the row 
hasn't been updated since 
the last fetch. Changes are 
detected through 
timestamps or by 
comparing all non-text, 
non-image values in a 
selected table row.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CUR_OPTCCVALCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Optimistic concurrency 
based on values.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Same as CUR_OPTCC 
except changes are detected 
by comparing the values in 
all selected columns.nrows - Number of rows in the fetch buffer (the width of the cursor). For mixed cursors the keyset capacity in rows is determined by this number multiplied by the value of the scrollopt parameter.pstatus - Pointer to the array of row status indicators. The status of every row copied into the fetch buffer is returned to this array. The array must be large enough to hold one long integer for every row in the buffer to be fetched. During the MOREINFO="NONE"dbcursorfetch call, as the rows are filled into the bound variable, the corresponding status is filled with status information. The following table shows status flags stored during the call to MOREINFO="NONE"dbcursorfetch:TOCENTRY="1"LBL="Table 2-21: "Values  for pstatus (MOREINFO="NONE"dbcursoropen)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="117*"COLNAME="C2" COLWIDTH="214*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Symbolic ValueCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MeaningVALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"FTC_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The row was successfully copied. If this flag is 
not set, the row was not fetched.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"FTC_MISSINGCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The row is missing.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"FTC_ENDOFKEYSETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The end of the keyset. The remaining rows in 
the bind arrays are not used.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"FTC_ENDOFRESULTSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The end of the result set. The remaining rows 
are not used.ReturnsREMAP="BO--Body"If the cursor succeeds, a handle to the cursor is returned. If it fails, NULL is returned. Several errors, such as the following, can cause the cursor to fail:MARK="BULL" REMAP="BU--Bullet"Not enough memory in the system. Reduce the number of rows in the keyset, use dynamic scrolling, or reduce the number of rows to be fetched at a time.A unique row identifier could not be found.A syntax error occurred or the MOREINFO="NONE"select statement failed.CommentsMARK="BULL" REMAP="BU--Bullet"This function prepares for the MOREINFO="NONE"select statement, but doesn't execute it until the fetch. The cursor definition cannot contain stored procedures or multiple Transact-SQL statements.For MOREINFO="NONE"dbcursor to succeed, every table in the MOREINFO="NONE"select statement must have a unique index. The transact-SQL phrases MOREINFO="NONE"for MOREINFO="NONE"browse, MOREINFO="NONE"select MOREINFO="NONE"into, MOREINFO="NONE"compute, MOREINFO="NONE"union, or MOREINFO="NONE"compute MOREINFO="NONE"by are not allowed in the cursor statement. Only fully keyset-driven cursors can have MOREINFO="NONE"order, MOREINFO="NONE"having, or MOREINFO="NONE"group by phrases.When opening a cursor through views, only one view name can be specified, and a view cannot be joined with another table or view. But the view can be a join of multiple tables, allowing updates subject to the same restrictions as in updating joins. Opening the cursor succeeds only if all the tables involved in the view have unique indexes, and all the columns making up the unique indexes are in the view.Multiple cursors (as many as the systems memory allows) can be opened within the same dbproc connection. There should be no commands waiting to be executed or results pending in the DBPROCESS connection when cursor functions are called.For more information on cursors, see LINKEND="X76241"Appendix A,  "Cursors."See AlsoREMAP="BO--Body"LINKEND="X99424"dbcursor
, LINKEND="X96617"dbcursorbind
, LINKEND="X25653"dbcursorclose
, LINKEND="X15626"dbcursorcolinfo
, LINKEND="X10062"dbcursorfetch
, LINKEND="X67036"dbcursorinfo
, LINKEND="X51048"dbcursoropenREMAP="BO--Body"ID="X69467"dbdataID="INA43159753"Regular columnsgetting data
Return a pointer to the data in a regular result column. FORMAT="LINESPECIFIC"BYTE *dbdata(dbproc, column)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"int          column;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. column - The number of the column of interest.  The first column is number 1. ReturnsREMAP="BO--Body"A BYTE pointer to the data for the particular column of interest. Be sure to cast this pointer into the proper type. A NULL BYTE pointer is returned if there is no such column or if the data has a null value. To make sure that the data is really a null value, you should always check for a return of 0 from MOREINFO="NONE"dbdatlen. CommentsMARK="BULL" REMAP="BU--Bullet"This routine returns a pointer to the data in a regular (i.e., non-compute) result column. The data is not null-terminated.  You can use MOREINFO="NONE"dbdatlen to get the length of the data. Here's a small program fragment that uses MOREINFO="NONE"dbdata: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc; DBINT        row_number = 0; DBINT        object_id; REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* Put the command into the command buffer */ dbcmd(dbproc, "select id from sysobjects"); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* ** Send the command to SQL Server and begin** execution */ dbsqlexec(dbproc); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* Process the command results */ dbresults(dbproc); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* Examine the data in each row */ while (dbnextrow(dbproc) != NO_MORE_ROWS) {     row_number++;     object_id = *((DBINT *)dbdata(dbproc, 1));     printf("row %ld, object id is %ld.\n",        row_number, object_id); } Do not add a null terminator to string data until you've copied it from the DBPROCESS with a routine such as MOREINFO="NONE"strncpy. For example: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"char    objname[40];      ... strncpy(objname, (char *)dbdata(dbproc,2),     (int)dbdatlen(dbproc,2)); objname[dbdatlen(dbproc,2] = '\0'; ID="IN43689138"dbbinddbbindas alternate to dbdataalternate to dbdataThe function MOREINFO="NONE"dbbind will automatically bind result data to your program variables.  It does a copy of the data, but is often easier to use than MOREINFO="NONE"dbdata. Furthermore, it includes a convenient type conversion capability. By means of this capability, the application can, among other things, easily add a null terminator to a result string or convert money and datetime data to printable strings. See AlsoREMAP="BO--Body"LINKEND="X14206"dbbind
, LINKEND="X80379"dbcollen
, LINKEND="X83710"dbcolname
, LINKEND="X35574"dbcoltype
, LINKEND="X61322"dbdatlen
, LINKEND="X66483"dbnumcols
ID="IN436861610"dbdata
 ID="IN4310831911"dbdate4cmp
ID="IN4315831912"Datetime valuescomparing
ID="IN439831913"Comparingdatetime valuesID="X19947"dbdate4cmp
Compare two DBDATETIME4 values. FORMAT="LINESPECIFIC"int dbdate4cmp(dbproc, d1, d2) FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"DBDATETIME4   *d1;FORMAT="LINESPECIFIC"DBDATETIME4   *d2;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and the server.   REMAP="UN--Under"This parameter may be NULL. d1 - A pointer to a DBDATETIME4 value. d2 - A pointer to a DBDATETIME4 value. ReturnsREMAP="BO--Body"If d1 = d2, MOREINFO="NONE"dbdate4cmp returns 0. REMAP="BO--Body"If d1 < d2, MOREINFO="NONE"dbdate4cmp returns -1. REMAP="BO--Body"If d1 > d2, MOREINFO="NONE"dbdate4cmp returns 1. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbdate4cmp compares two DBDATETIME4 values. The range of legal DBDATETIME4 values is from January 1, 1900 to June 6, 2079. DBDATETIME4 values have a precision of one minute. See AlsoREMAP="BO--Body"LINKEND="X94368"dbdatecmp
, LINKEND="X81878"dbmnycmp
, LINKEND="X44051"dbmny4cmp
ID="IN4410802320"dbdate4cmp
 ID="IN4411772621"dbdate4zeroID="X37032"dbdate4zero
Initialize a DBDATETIME4 variable to Jan 1, 1900 12:00AM. FORMAT="LINESPECIFIC"RETCODE dbdate4zero(dbproc, dateptr)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"DBDATETIME4  *dateptr;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and the server.   REMAP="UN--Under"This parameter may be NULL. dateptr - A pointer to the DBDATETIME4 variable to initialize. ReturnsREMAP="BO--Body"SUCCEED or FAIL. REMAP="BO--Body"MOREINFO="NONE"dbdate4zero returns FAIL if dateptr is NULL CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbdate4zero initializes a DBDATETIME4 variable to Jan 1, 1900 12:00AM. The range of legal DBDATETIME4 values is from January 1, 1900  to June 6, 2079. DBDATETIME4 values have a precision of one minute. See AlsoREMAP="BO--Body"LINKEND="X87330"dbdatezero
ID="IN4511743028"dbdate4zero
 ID="IN4510713329"dbdatecharID="X23221"dbdatechar
Convert an integer component of a DBDATETIMEID="IN465713431"Datesconverting to character format
ID="IN4620693632"DBDATETIME structureconverting integer component to character format
 value into character format. FORMAT="LINESPECIFIC"RETCODE dbdatechar(dbproc, charbuf, datepart, value)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"char         *charbuf;FORMAT="LINESPECIFIC"int          datepart;FORMAT="LINESPECIFIC"int          value;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. charbuf - A pointer to the character buffer that will contain the null-terminated character representation of value. datepart - valueID="IN465693635"Datesparts of
ID="IN465693636"Datessymbols recognized by DB-Library
's type. The following table lists the date parts, the date part symbols recognized by DB-Library, and the expected values. Note that the names of the months and the days in this table are those for English. TOCENTRY="1"LBL="Table 2-22: "Date parts and their character representation.COLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="90*"COLNAME="C2" COLWIDTH="99*"COLNAME="C3" COLWIDTH="135*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Date Part COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SymbolCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Character Representation 
of Value VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"yearCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATE_YYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"1753 - 9999 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"quarterCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATE_QQCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"1 - 4 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"monthCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATE_MMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"January - December COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"dayofyearCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATE_DYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"1 - 366 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"dayCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATE_DDCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"1 - 31 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"weekCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATE_WKCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"1 - 54 (for leap years) COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"weekdayCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATE_DWCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Monday - Sunday COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"hourCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATE_HHCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"0 - 23 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"minuteCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATE_MICOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"0 - 59 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"secondCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATE_SSCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"0 - 59 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"millisecondCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATE_MSCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"0 - 999 value - The numeric value to be converted. ReturnsREMAP="BO--Body"SUCCEED or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbdatechar converts integer datetime components to character format. For example, MOREINFO="NONE"dbdatechar associates the month component "3" with its associated character string: "March" if English is used, "mars" if French is used, and so on. The language of the associated character string is determined by the dbproc. MOREINFO="NONE"dbdatechar is often useful in conjunction with MOREINFO="NONE"dbdatecrack. See AlsoREMAP="BO--Body"LINKEND="X76814"dbconvert
, LINKEND="X69467"dbdata
, LINKEND="X58577"dbdatename
, LINKEND="X76106"dbdatecrack
ID="IN4610663940"dbdatechar
 ID="IN469634241"dbdatecmpID="X94368"dbdatecmp
Compare two DBDATETIME values. FORMAT="LINESPECIFIC"int dbdatecmp(dbproc, d1, d2)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"DBDATETIME   *d1;FORMAT="LINESPECIFIC"DBDATETIME   *d2;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and the server.   REMAP="UN--Under"This parameter may be NULL. d1 - A pointer to a DBDATETIME value. d2 - A pointer to a DBDATETIME value. ReturnsREMAP="BO--Body"If d1 = d2, MOREINFO="NONE"dbdatecmp returns 0. REMAP="BO--Body"If d1 < d2, MOREINFO="NONE"dbdatecmp returns -1. REMAP="BO--Body"If d1 > d2, MOREINFO="NONE"dbdatecmp returns 1. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbdatecmp compares two DBDATETIME values.   The range of legal DBDATETIME values is from  January 1, 1753 to December 31, 9999. DBDATETIME values have a precision of 1/300th of a second  (3.33 milliseconds). See AlsoREMAP="BO--Body"LINKEND="X19947"dbdate4cmp
, LINKEND="X81878"dbmnycmp
, LINKEND="X44051"dbmny4cmp
ID="IN479604648"dbdatecmp
 ID="IN4711574949"dbdatecrackID="X76106"dbdatecrack
Convert a machine-readable DBDATETIMEID="IN4820555251"DBDATETIME structureconverting values into usable format
ID="IN485555252"Datesconverting values into usable format
 value into user-accessible format. FORMAT="LINESPECIFIC"RETCODE dbdatecrack(dbproc, dateinfo, datetime)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"DBDATEREC    *dateinfo;FORMAT="LINESPECIFIC"DBDATETIME   *datetime;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. dateinfo ID="IN4819535455"DBDATEREC structure
- A pointer to a DBDATEREC structure to contain the parts of datetime. DBDATEREC is defined as follows: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"typedef struct dbdaterec {     long    dateyear;    /* 1900 to the future */     long    datemonth;   /* 0 - 11 */     long    datedmonth;  /* 1 - 31 */     long    datedyear;   /* 1 - 366 */     long    datedweek;   /* 0 - 6 (Sun. - Sat.) */     long    datehour;    /* 0 - 23 */     long    dateminute;  /* 0 - 59 */     long    datesecond;  /* 0 - 59 */     long    datemsecond; /* 0 - 997 */     long    datetzone;   /* 0 - 127 */ } DBDATEREC; datetime - A pointer to the DBDATETIME value of interest. ReturnsREMAP="BO--Body"SUCCEED or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbdatecrack converts a DBDATETIME value into its integer components and places those components into a DBDATEREC structure. ID="IN4820515658"DBDATETIME structureDBDATETIME structures store date and time values in an internal format. For example, a time value is stored as the number of 300th's of a second since midnight, and a date value is stored as the number of days since January 1, 1900. MOREINFO="NONE"dbdatecrack converts the internal value to something more usable by an application program. The integer date parts placed in the DBDATEREC structure may be converted to character strings via MOREINFO="NONE"dbdatechar. Calling MOREINFO="NONE"dbdatecrack to convert an internal format datetime value is equivalent to calling MOREINFO="NONE"dbdatepart many times. The following code fragment illustrates the use of MOREINFO="NONE"dbdatecrack: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"dbcmd(dbproc, "select name, crdate from \     master..sysdatabases"); dbsqlexec(dbproc); dbresults(dbproc); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"while (dbnextrow(dbproc) != NO_MORE_ROWS) {     /*     ** Print the database name and its date info    */     dbconvert(dbproc, dbcoltype(dbproc, 2),        dbdata(dbproc, 2), dbdatlen(dbproc, 2),        SYBCHAR, datestring, -1);     printf("%s: %s\n", (char *)        (dbdata(dbproc, 1)), datestring); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /*     ** Break up the creation date into its    ** constituent parts.     */     dbdatecrack(dbproc, &dateinfo,          (DBDATETIME *)(dbdata(dbproc, 2))); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /* Print the parts of the creation date */     printf("\tYear = &d.\n", dateinfo.dateyear);    printf("\tMonth = &d.\n",dateinfo.datemonth);    printf("\tDay of month = &d.\n",        dateinfo.datedmonth);     printf("\tDay of year = &d.\n",        dateinfo.datedyear);     printf("\tDay of week = &d.\n",        dateinfo.datedweek);     printf("\tHour = &d.\n", dateinfo.datehour);     printf("\tMinute = &d.\n",        dateinfo.dateminute);     printf("\tSecond = &d.\n",        dateinfo.datesecond);     printf("\tMillisecond = &d.\n",        dateinfo.datemsecond); } See AlsoREMAP="BO--Body"LINKEND="X76814"dbconvert
, LINKEND="X69467"dbdata
, LINKEND="X23221"dbdatechar
, LINKEND="X58577"dbdatename
, LINKEND="X65989"dbdatepart
ID="IN4811485960"dbdatecrack
 ID="IN4810456261"dbdatenameID="X58577"dbdatename
Convert the specified component of a DBDATETIMEID="IN4920436563"DBDATETIME structureconverting date parts to character strings
ID="IN495436564"Datesconverting parts to character strings
 structure into its corresponding character string. FORMAT="LINESPECIFIC"int dbdatename(dbproc, charbuf, datepart, datetime)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"char          *charbuf;FORMAT="LINESPECIFIC"int           datepart;FORMAT="LINESPECIFIC"DBDATETIME    *datetime;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. charbuf - A pointer to a character buffer that will contain the NULL-terminated character representation of the datetime component of interest. If datetime is NULL, charbuf will contain a zero-length string. datepart - The date component of interest.  The following table lists the date parts, the date part symbols recognized by DB-Library and the expected values. Note that the names of the months and the days in this table are those for English. TOCENTRY="1"LBL="Table 2-23: "Date parts and their character representations.COLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="72*"COLNAME="C2" COLWIDTH="108*"COLNAME="C3" COLWIDTH="135*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Date PartCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SymbolCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Character Representation 
of Value VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"yearCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATE_YYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"1753 - 9999 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"quarterCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATE_QQCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"1 - 4 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"monthCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATE_MMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"January - December COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"dayofyearCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATE_DYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"1 - 366 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"dayCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATE_DDCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"1 - 31 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"weekCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATE_WKCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"1 - 54 (for leap years) COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"weekdayCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATE_DWCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Monday - Sunday COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"hourCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATE_HHCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"0 - 23 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"minuteCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATE_MICOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"0 - 59 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"secondCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATE_SSCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"0 - 59 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"millisecondCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATE_MSCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"0 - 999 datetime - A pointer to the DBDATETIME value of interest. ReturnsREMAP="BO--Body"The number of bytes placed into *charbuf. REMAP="BO--Body"In case of error, MOREINFO="NONE"dbdatename returns -1. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbdatename converts the specified component of a DBDATETIME structure into a character string. The names of the months and weekdays are in the language of the specified DBPROCESS. If dbproc is NULL, these names will be in DB-Library's default language. This function is very similar to the Transact-SQL MOREINFO="NONE"datename function. The following code fragment illustrates the use of MOREINFO="NONE"dbdatename: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"dbcmd(dbproc, "select name, crdate from \     master..sysdatabases"); dbsqlexec(dbproc); dbresults(dbproc); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"while (dbnextrow(dbproc) != NO_MORE_ROWS) {     /*    ** Print the database name and its date info    */     dbconvert(dbproc, dbcoltype(dbproc, 2),         dbdata(dbproc, 2), dbdatlen(dbproc, 2),         SYBCHAR, datestring, -1);                     printf("%s: %s\n", (char *) (dbdata                         (dbproc, 1)), datestring);                      /* Print the parts of the creation date */                     dbdatename(dbproc, datestring, DBDATE_YY,                           (DBDATETIME *) (dbdata(dbproc, 2)));                     printf("\ Year = %s.\n", datestring);                      dbdatename(dbproc, datestring, DBDATE_QQ,                           (DBDATETIME *) (dbdata(dbproc, 2)));                     printf("\ Quarter = %s.\n", datestring);                      dbdatename(dbproc, datestring, DBDATE_MM,                           (DBDATETIME *) (dbdata(dbproc, 2)));                     printf("\ Month = %s.\n", datestring);                      dbdatename(dbproc, datestring, DBDATE_DW,                           (DBDATETIME *) (dbdata(dbproc, 2)));                     printf("\ Day of week = %s.\n", datestring);                      dbdatename(dbproc, datestring, DBDATE_DD,                           (DBDATETIME *) (dbdata(dbproc, 2)));                     printf("\ Day of month = %s.\n", datestring);                      dbdatename(dbproc, datestring, DBDATE_DY,                            (DBDATETIME *) (dbdata(dbproc, 2)));                     printf("\ Day of year = %s.\n", datestring);                      dbdatename(dbproc, datestring, DBDATE_HH,                           (DBDATETIME *) (dbdata(dbproc, 2)));                     printf("\ Hour = %s.\n", datestring);                      dbdatename(dbproc, datestring, DBDATE_MI,                           (DBDATETIME *) (dbdata(dbproc, 2)));                     printf("\ Minute = %s.\n", datestring);                      dbdatename(dbproc, datestring, DBDATE_SS,                           (DBDATETIME *) (dbdata(dbproc, 2)));                     printf("\ Second = %s.\n", datestring);                      dbdatename(dbproc, datestring, DBDATE_MS,                           (DBDATETIME *) (dbdata(dbproc, 2)));                     printf("\ Millisecond = %s.\n", datestring);                      dbdatename(dbproc, datestring, DBDATE_WK,                           (DBDATETIME *) (dbdata(dbproc, 2)));                     printf("\ Week = %s.\n", datestring); See AlsoREMAP="BO--Body"LINKEND="X76814"dbconvert
, LINKEND="X69467"dbdata
, LINKEND="X23221"dbdatechar
, LINKEND="X76106"dbdatecrack
ID="IN4910406870"dbdatename
 ID="IN4911377171"dbdateorderID="X53486"dbdateorderID="IN505377273"Datesreturning order for specified language
Return the date component order for a given language. FORMAT="LINESPECIFIC"char *dbdateorder(dbproc, language)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"char         *language;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. language - The name of the language of interest. ReturnsREMAP="BO--Body"A pointer to a NULL-terminated 3-character string containing the characters "m", "d", and "y", representing the month, day, and year date components, respectively. The order of the characters in the MOREINFO="NONE"dbdateorder string corresponds to their order in language's default datetime format. REMAP="BO--Body"MOREINFO="NONE"dbdateorder returns a NULL pointer on failure. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbdateorder returns a character string that describes the order in which the month, day, and year date components appear in the specified language. If language is NULL, the current language of the specified DBPROCESS is used. If both language and dbproc are NULL, DB-Library's default language is used. The date order string returned by MOREINFO="NONE"dbdateorder is a pointer to DB-Library's internal data structures. Application programs should neither modify this string, nor free it. REMAP="BO--Body"MARK="BULL" REMAP="BU--Bullet"The following code fragment illustrates the use of MOREINFO="NONE"dbdateorder: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"/* Retrieve the date order from SQL Server */ printf("date-order: %s\n",     (dbdateorder(DBPROCESS *)NULL, (char *)NULL)); See AlsoREMAP="BO--Body"LINKEND="X76814"dbconvert
, LINKEND="X69467"dbdata
, LINKEND="X23221"dbdatechar
, LINKEND="X76106"dbdatecrack
ID="IN5011347579"dbdateorder
 ID="IN5010317880"dbdatepartID="X65989"dbdatepart
Return the specified part of a DBDATETIMEID="IN5120298182"DBDATETIME structurereturning parts as numeric values
ID="IN515298183"Datesreturning parts as numeric values
 value as a numeric value. FORMAT="LINESPECIFIC"DBINT dbdatepart(dbproc, datepart, datetime)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"int           datepart;FORMAT="LINESPECIFIC"DBDATETIME    *datetime;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. datepart - The date component of interest.  The following table lists the date parts, the date part symbols recognized by DB-Library and the expected values. Note that the names of the months and the days in this table are those for English. TOCENTRY="1"LBL="Table 2-24: "Date parts and their character representationsCOLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="99*"COLNAME="C2" COLWIDTH="116*"COLNAME="C3" COLWIDTH="115*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Date PartCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SymbolCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Character 
Representation of Value VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"yearCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATE_YYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"1753 - 9999 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"quarterCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATE_QQCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"1 - 4 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"monthCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATE_MMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"January - December COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"dayofyearCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATE_DYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"1 - 366 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"dayCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATE_DDCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"1 - 31 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"weekCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATE_WKCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"1 - 54 (for leap years) COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"weekdayCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATE_DWCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Monday - Sunday COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"hourCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATE_HHCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"0 - 23 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"minuteCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATE_MICOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"0 - 59 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"secondCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATE_SSCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"0 - 59 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"millisecondCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATE_MSCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"0 - 999 datetime - A pointer to the DBDATETIME value of interest. ReturnsREMAP="BO--Body"The value of the specified date part. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbdatepart returns the specified part of a DBDATETIME value as a numeric value. MOREINFO="NONE"dbdatepart is similar to the Transact-SQL MOREINFO="NONE"datepart function. See AlsoREMAP="BO--Body"LINKEND="X76814"dbconvert
, LINKEND="X69467"dbdata
, LINKEND="X23221"dbdatechar
, LINKEND="X76106"dbdatecrack
, LINKEND="X58577"dbdatename
ID="IN5110268489"dbdatepart
 ID="IN5110238790"dbdatezeroID="X87330"dbdatezero
Initialize a DBDATETIME value to Jan 1, 1900 12:00:00:000AM. FORMAT="LINESPECIFIC"RETCODE dbdatezero(dbproc, dateptr)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"DBDATETIME    *dateptr;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and the server.   REMAP="UN--Under"This parameter may be NULL. dateptr - A pointer to the DBDATETIME variable to initialize. ReturnsREMAP="BO--Body"SUCCEED or FAIL. REMAP="BO--Body"MOREINFO="NONE"dbdatezero returns FAIL if dateptr is NULL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbdatezero initializes a DBDATETIME value to Jan 1, 1900 12:00:00:000AM. The range of legal DBDATETIME values is from January 1, 1753  to December 31, 9999. DBDATETIME values have a precision of 1/300th of a second (3.33 milliseconds). See AlsoREMAP="BO--Body"LINKEND="X37032"dbdate4zero
ID="IN5210209197"dbdatezero
 ID="IN528179498"dbdatlenID="X61322"dbdatlenID="IN53151795100"Regular columnsreturning data length of
Return the length of the data in a regular result column. FORMAT="LINESPECIFIC"DBINT dbdatlen(dbproc, column)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"int          column;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. column - The number of the column of interest.  The first column is number 1. ReturnsREMAP="BO--Body"The length, in bytes, of the data that would be returned for the particular column. If the data has a null value, MOREINFO="NONE"dbdatlen returns 0. If the column number is not in range, MOREINFO="NONE"dbdatlen returns -1. CommentsMARK="BULL" REMAP="BU--Bullet"This routine returns the length, in bytes, of data that would be returned by a MOREINFO="NONE"select against a regular (i.e., non-compute)  result column.  In most cases, this is the actual length of  data for the column.  For text and image columns, however, the integer returned by MOREINFO="NONE"dbdatlen can be less than the actual length of data for the column.  This is because the  server global variable @@textsize limits the amount of text or image data returned by a MOREINFO="NONE"select. Use the MOREINFO="NONE"dbcollen routine to determine the maximum  possible length for the data. Use MOREINFO="NONE"dbdata to get a pointer to the data itself. Here's a small program fragment that uses MOREINFO="NONE"dbdatlen: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"               DBPROCESS    *dbproc;                DBINT        row_number = 0;                DBINT        data_length; REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"               /* Put the command into the command buffer */                dbcmd(dbproc, "select name from sysobjects");                /*                ** Send the command to SQL Server and begin               ** execution                */                dbsqlexec(dbproc);                 /* Process the command results */                dbresults(dbproc);                 /* Examine the data lengths of each row */                while (dbnextrow(dbproc) != NO_MORE_ROWS)                {                     row_number++;                     data_length = dbdatlen(dbproc, 1);                     printf("row %ld, data length is %ld.\n",                         row_number, data_length);                } See AlsoREMAP="BO--Body"LINKEND="X80379"dbcollen
, LINKEND="X83710"dbcolname
, LINKEND="X35574"dbcoltype
, LINKEND="X69467"dbdata
, LINKEND="X66483"dbnumcols
ID="IN5381498106"dbdatlen
 ID="IN53911101107"dbdaynameID="X83105"dbdaynameID="IN54511102109"Datesreturning name of day in specified language
ID="IN54411102110"Daysreturning name of in specified language
Determine the name of a specified weekday in a specified language. FORMAT="LINESPECIFIC"char *dbdayname(dbproc, language, daynum)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"char         *language;FORMAT="LINESPECIFIC"int          daynum;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. language - The name of the desired language. daynum - The number of the desired day. Day numbers range from 1 (Monday) to 7 (Sunday). ReturnsREMAP="BO--Body"The name of the specified day on success; a NULL pointer on error. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbdayname returns the name of the specified day in the specified language. If language is NULL, dbproc's current language is used. If both language and dbproc are NULL, then U.S. English is used. The following code fragment illustrates the use of MOREINFO="NONE"dbdayname: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"               /*                ** Retrieve the name of each day of the week in               ** U.S. English.                */                for (daynum = 1; daynum <= 7; daynum++)                     printf("Day %d: %s\n", daynum,                     dbdayname((DBPROCESS *)NULL, (char *)NULL,                    daynum)); See AlsoREMAP="BO--Body"LINKEND="X53831"db12hour
, LINKEND="X53486"dbdateorder
, LINKEND="X56030"dbmonthname
, LINKEND="X52068"DBSETLNATLANG
ID="IN5498105116"dbdayname
 ID="X39971"DBDEADID="IN5565109117"DBDEAD
Determine whether a particular DBPROCESSID="IN55193111119"DBPROCESS structuredetermining whether dead
 is dead. FORMAT="LINESPECIFIC"DBBOOL DBDEAD(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. ReturnsREMAP="BO--Body"TRUE or FALSE. CommentsID="IN5514-1115124"Error handlingError handlingand DBDEADDBDEADMARK="BULL" REMAP="BU--Bullet"This macro indicates whether or not the specified DBPROCESS has been marked dead. It is particularly useful in user-supplied error handlers. If a DBPROCESS is dead, then almost every DB-Library routine which receives it as a parameter will immediately fail, calling the user-supplied error handler. Note:  If there is no user-supplied error handler, a dead DBPROCESS will cause the affected DB-Library routines not to fail, but to abort the program. Note that MOREINFO="NONE"DBDEAD does not communicate with the server, but only checks the current status of a DBPROCESS. If a previously-called DB-Library routine has not marked a DBPROCESS as dead, MOREINFO="NONE"DBDEAD reports the DBPROCESS as healthy.See AlsoREMAP="BO--Body"LINKEND="X12458"dberrhandle
, LINKEND="X47604"errors
ID="IN556-4118126"DBDEAD
 ID="IN5511-7121127"dberrhandleID="X12458"dberrhandleID="IN5614-8123129"Error handlinginstalling a user-function
Install a user function to handle DB-Library errors. FORMAT="LINESPECIFIC"int (*dberrhandle(handler))()FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"int          (*handler)();ParametersREMAP="RI--RefIndent"handler - A pointer to the user function that will be called whenever DB-Library determines that an error has occurred. DB-Library calls this function with six parameters: TOCENTRY="1"LBL="Table 2-25: "Error handler parametersCOLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="63*"COLNAME="C2" COLWIDTH="279*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ParameterCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MeaningVALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"dbprocCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The affected DBPROCESS. If there is no DBPROCESS 
associated with this error, this parameter will be NULL. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"severityCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The severity of the error (datatype int). Error severities are 
defined in syberror.h. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"dberrCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The identifying number of the error (datatype int). Error 
numbers are defined in sybdb.h. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"oserrCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The operating-system-specific error number that describes 
the cause of the error (datatype int). If there is no relevant 
operating-system error, the value of this parameter will be 
DBNOERR. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"dberrstrCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A printable description of dberr (datatype char *). COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"oserrstrCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A printable description of oserr(datatype char *). REMAP="UN--Under"The error handler must return one of the following four values, directing DB-Library to perform particular actions: TOCENTRY="1"LBL="Table 2-26: "Error handler returnsCOLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="99*"COLNAME="C2" COLWIDTH="243*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ReturnCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ActionVALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"INT_EXITCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Print an error message and abort the program. DB-
Library will also return an error indication to the 
operating system. (Note to UNIX programmers: DB-
Library will not leave a core file.) COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"INT_CANCELCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Return FAIL from the DB-Library routine that 
caused the error. Returning INT_CANCEL on 
timeout errors will kill the dbproc. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"INT_TIMEOUTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Cancel the operation that caused the error but leave 
the dbproc in working condition. This return value 
is meaningful only for timeout errors (SYBETIME). 
In any other case, this value will be considered an 
error, and will be treated as an INT_EXIT. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"INT_CONTINUECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Continue to wait for one additional timeout period. 
At the end of that period, call the error handler 
again. This return value is meaningful only for 
timeout errors (SYBETIME). In any other case, this 
value will be considered an error, and will be treated 
as an INT_EXIT. REMAP="UN--Under"If the error handler returns any value besides these four, the program will abort. REMAP="UN--Under"The following example shows a typical error handler routine: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"#include <sybfront.h> #include <sybdb.h> #include <syberror.h> REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"int err_handler(dbproc, severity, dberr, oserr,     dberrstr, oserrstr) REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc; int          severity; int          dberr; int          oserr; char         *dberrstr; char         *oserrstr; REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"{      if ((dbproc == NULL) || (DBDEAD(dbproc)))           return(INT_EXIT);      else       {          printf("DB-Library error:\n\t%s\n",               dberrstr);           if (oserr != DBNOERR)                printf("Operating-system \                    error:\n\t%s\n", oserrstr);           return(INT_CANCEL);      } } ReturnsREMAP="BO--Body"A pointer to the previously-installed error handler. This may be NULL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dberrhandle installs an error-handler function that you supply. When a DB-Library error occurs, DB-Library will call this error handler immediately. You must install an error handler in order to handle DB-Library errors properly. If an application does not call MOREINFO="NONE"dberrhandle to install an error-handler function, DB-Library ignores error messages. The messages are not printed.The user-supplied error handler will completely determine the response of DB-Library to any error that occurs. It must tell DB-Library whether to: MARK="DASH" REMAP="BS--BulletSub"abort the program, return an error code and kill the dbproc,  cancel the operation that caused the error, or keep trying (in the case of a timeout error). If the user does not supply an error handler (or passes a NULL pointer to MOREINFO="NONE"dberrhandle), DB-Library will exhibit its default error-handling behavior:  It will abort the program if the error has made the affected DBPROCESS unusable (the user can call MOREINFO="NONE"DBDEAD to determine whether or not a DBPROCESS has become unusable). If the error has not made the DBPROCESS unusable, DB-Library will simply return an error code to its caller. ID="IN5614-8123134"Error handlingde-installing handlerYou can de-install an existing error handler by calling MOREINFO="NONE"dberrhandle with a NULL parameter. You can also, at any time, install a new error handler. The new handler will automatically replace any existing handler. ID="IN5622-10125135"syberror.h header fileIf the program refers to error severity values, its source file must include the header file syberror.h. See the MOREINFO="NONE"errors manual page for a list of DB-Library errors. ID="IN5611-18133136"dbmsghandledbmsghandleand dberrhandledberrhandle
ID="IN5616-22137137"Message handlingMessage handlingand dberrhandledberrhandleAnother routine, MOREINFO="NONE"dbmsghandle, installs a message handler that DB-Library calls in response to the server error messages. ID="IN568-24139138"SYBESMSGSYBESMSGand error handlingerror handlingIf the application provokes messages from DB-Library and the server simultaneously, DB-Library calls the server message handler before it calls the DB-Library error handler. The DB-Library/C error value SYBESMSG is generated in response to a server error message, but not in response to a server informational message.  This means that when a server error occurs, both the server message handler and the DB-Library/C error handler are called, but when the server generates an informational message, only the server message handler is called. REMAP="UN--Under"If you have installed a server message handler, you may want to write your DB-Library error handler so as to suppress the printing of any SYBESMSG error, to avoid notifying the user about the same error twice. The following chart provides information on when DB-Library/C calls an application's message and error handlers: TOCENTRY="1"LBL="Table 2-27: "Common errorsCOLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="153*"COLNAME="C2" COLWIDTH="88*"COLNAME="C3" COLWIDTH="115*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Error or MessageCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Message Handler 
Called?COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Error Handler Called?COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SQL syntax errorCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"YesCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Yes (SYBESMSG)aCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SQL MOREINFO="NONE"print statementCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"YesCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NoCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SQL MOREINFO="NONE"raiserrorCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"YesCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Server diesCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NoCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Yes (SYBESEOF) bCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Timeout from the serverCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NoCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Yes (SYBETIME)cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Deadlock on queryCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"YesdCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Timeout on loginCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NoCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Yes (SYBEFCON, 
SYBECONN)cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Login fails (MOREINFO="NONE"dbopen) COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"YesCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Yes (SYBEPWD)bCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Use database messageCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"YesaCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Incorrect use of DB-Library/C 
calls, such as not calling 
MOREINFO="NONE"dbresults when requiredCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NoCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Yes (SYBERPND, ...) COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fatal Server error (severity 
greater than 16) COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Yes bCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Yes (SYBESMSG) ID="IPTF5A" VALIGN="TOP"aCode your handler to ignore the message.bCode your handler to exit the application.cTo waIt for another timeout period, code your handler to return INT_CONTINUE.dCode your handler to test for deadlock.See AlsoREMAP="BO--Body"LINKEND="X39971"DBDEAD
, LINKEND="X78343"dbmsghandle
, LINKEND="X47604"errors
ID="IN5611-27142140"dberrhandle
ID="IN5614-28143141"Error handlinginstalling a user-function
 ID="IN566-31146142"dbexitID="X99227"dbexit
Close and de-allocate all DBPROCESS structures, and clean up any structures initialized by MOREINFO="NONE"dbinitID="IN5719-33149144"DBPROCESS structureclosing all
ID="IN5719-35151145"DBPROCESS structurede-allocating all
. FORMAT="LINESPECIFIC"void dbexit()ParametersREMAP="BO--Body"None. ReturnsREMAP="BO--Body"None. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbexit calls MOREINFO="NONE"dbclose repeatedly for all allocated DBPROCESS structures. MOREINFO="NONE"dbclose cleans up any activity associated with a single DBPROCESS structure and de-allocates the space. You can use MOREINFO="NONE"dbclose directly to close just a single DBPROCESS structure. ID="IN576-43159150"dbinitdbinitand dbexitdbexitMOREINFO="NONE"dbexit also cleans up any structures initialized by MOREINFO="NONE"dbinit, releasing the memory associated with those structures. It must be the last DB-Library call in any application that callsMOREINFO="NONE" dbinit. To ensure future compatibility and portability, it is strongly recommended that all applications call MOREINFO="NONE"dbinit and MOREINFO="NONE"dbexit, no matter what their environmentREMAP="UN--Under"For environments requiring MOREINFO="NONE"dbinit, the application must not make any other DB-Library call after calling MOREINFO="NONE"dbexit. See AlsoREMAP="BO--Body"LINKEND="X87778"dbclose
, LINKEND="X24387"dbinit
, LINKEND="X42139"dbopen
ID="IN576-46162152"dbexit
 REMAP="BO--Body"ID="X29834"dbfcmd
Add text to the DBPROCESS command buffer using C run-time library MOREINFO="NONE"sprintfID="INB43159753"Command buffersadding text to
ID="IN43169574"sprintf function
-type formatting. FORMAT="LINESPECIFIC"RETCODE dbfcmd(dbproc, cmdstring, args...)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"char          *cmdstring;FORMAT="LINESPECIFIC"long          args...;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and server. cmdstring - A format string of the form used by the MOREINFO="NONE"sprintf routine. args... - There is an optional and variable number of arguments to MOREINFO="NONE"dbfcmd. The number of arguments required depends on the number indicated in the cmdstring argument. The arguments are passed directly to the MOREINFO="NONE"sprintf function. ReturnsREMAP="BO--Body"SUCCEED or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"This routine adds text to the Transact-SQL command buffer in the DBPROCESS structure. MOREINFO="NONE"dbfcmd works just like the C language Standard I/O library MOREINFO="NONE"sprintf function, using % conversion specifications. If you don't need any of the formatting capability of MOREINFO="NONE"sprintf, you can use MOREINFO="NONE"dbcmd instead. The following table lists the conversions supported by MOREINFO="NONE"dbfcmd: TOCENTRY="1"LBL="Table 2-28: "MOREINFO="NONE"dbfcmd conversionsCOLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="117*"COLNAME="C2" COLWIDTH="107*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ConversionCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Program variable type VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"%sCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"char  COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"%dCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"int  COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"%fCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"double COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"%gCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"double COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"%eCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"double COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"%%COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"none REMAP="UN--Under"The data type SYBDATETIME must be converted to a character string and passed using %s. The data type SYBMONEY may be converted to a character string and passed using %s, or converted to float and passed using %f. Currently, only eight arguments may be handled in each call to MOREINFO="NONE"dbfcmd. To format commands that require more than eight arguments, call MOREINFO="NONE"dbfcmd repeatedly. Since MOREINFO="NONE"dbfcmd calls MOREINFO="NONE"sprintf, you must remember that % has a special meaning as the beginning of a format command. If you want to include % in the command string, you must precede it with another %. Don't use arguments containing strings with apostrophes or single quotes, and don't use NULL arguments. Apostrophes, single quotes, and NULL arguments can result in SQL Server syntax errors, because SQL Server interprets them as indicating string termination.MOREINFO="NONE"dbfcmd manages the space allocation for the command buffer. It adds to the existing command buffer-it doesn't delete or overwrite the current contents except after the buffer has been sent to the server (see below). A single command buffer may contain multiple commands; in fact, this represents an efficient use of the command buffer. The application may call MOREINFO="NONE"dbfcmd repeatedly. The command strings in sequential calls are just concatenated together. It is the program's responsibility to ensure that any necessary blanks appear between the end of one string and the beginning of the next. ID="IN431989139"DBNOAUTOFREE optionDBNOAUTOFREE optionand dbfcmddbfcmdAfter a call to MOREINFO="NONE"dbsqlexec or MOREINFO="NONE"dbsqlsend, the first call to either MOREINFO="NONE"dbcmd or MOREINFO="NONE"dbfcmd automatically clears the command buffer before the new text is entered. If this situation is undesirable, set the DBNOAUTOFREE option. When DBNOAUTOFREE is set, the command buffer is cleared only by an explicit call to MOREINFO="NONE"dbfreebuf. Here's a small program fragment that uses MOREINFO="NONE"dbfcmd to build up a multi-line SQL command: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"char         *column_name; DBPROCESS    *dbproc; int          low_id; char         *object_type; char         *tablename; REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"dbfcmd(dbproc, "select %s from %s", column_name, tablename); dbfcmd(dbproc, " where id > %d", low_id); dbfcmd(dbproc, " and type='%s'", object_type); REMAP="UN--Under"Note the required spaces at the start of the second and third command strings. Be sure to guard against passing a null pointer contained in a variable to MOREINFO="NONE"dbfcmd. If a null value is a possibility, you should check for it before using the variable with a MOREINFO="NONE"dbfcmd call. The application can intermingle calls to MOREINFO="NONE"dbcmd and MOREINFO="NONE"dbfcmd. At any time, the application can access the contents of the command buffer through calls to MOREINFO="NONE"dbgetchar, MOREINFO="NONE"dbstrlen, and MOREINFO="NONE"dbstrcpy. Available memory is the only constraint on the size of the DBPROCESS command buffer created by calls to MOREINFO="NONE"dbcmd and MOREINFO="NONE"dbfcmd. LimitationsREMAP="BO--Body"Currently, only eight args may be handled in each call to MOREINFO="NONE"dbfcmd. To format commands that require more than eight args, call MOREINFO="NONE"dbfcmd repeatedly. REMAP="BO--Body"Because it makes text substitutions, MOREINFO="NONE"dbfcmd uses a working buffer in addition to the DBPROCESS command buffer. MOREINFO="NONE"dbfcmd allocates this working buffer dynamically. The size of the space it allocates is equal to the maximum of a defined constant (1024) and the string length of cmdstring * 2. For example, if the length of cmdstring is 600 bytes, MOREINFO="NONE"dbfcmd allocates a working buffer 1200 bytes long. If the length of cmdstring is 34 bytes, MOREINFO="NONE"dbfcmd allocates a working buffer 1024 bytes long. REMAP="BO--Body"If the args are very big in comparison to the size of cmdstring, the working buffer may not be large enough to hold the string after substitutions are made. In this situation, break cmdstring up and use multiple calls to MOREINFO="NONE"dbfcmd. REMAP="BO--Body"Note that the working buffer is not the same as the DBPROCESS command buffer. The working buffer is a temporary buffer used only by MOREINFO="NONE"dbfcmd when making text substitutions. The DBPROCESS command buffer holds the text after substitutions have been made. There is no constraint, other than available memory, on the size of the DBPROCESS command buffer. See AlsoREMAP="BO--Body"LINKEND="X41151"dbcmd
, LINKEND="X18180"dbfreebuf
, LINKEND="X20172"dbgetchar
, LINKEND="X48259"dbstrcpy
, LINKEND="X53545"dbstrlen
, LINKEND="X60647"options
ID="IN436861612"dbfcmd
 ID="X66598"DBFIRSTROWID="IN4410832013"DBFIRSTROW
ID="IN4411832015"Row buffersreturning number of first row
ID="IN444832016"Rowsreturning number of first in buffer
Return the number of the first row in the row buffer. FORMAT="LINESPECIFIC"DBINT DBFIRSTROW(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and server. ReturnsREMAP="BO--Body"The number of the first row in the row buffer. Rows are counted from the first row returned from the server, whose number is 1. This routine returns 0 if there's an error. CommentsMARK="BULL" REMAP="BU--Bullet"This macro returns the number of the first row in the row buffer. ID="IN4415772621"DBBUFFER optionDBBUFFER optionand DBFIRSTROWDBFIRSTROWIf you aren't buffering rows, DBFIRSTROW, DBCURROW, and DBLASTROW always have the same value. If you have enabled buffering by setting the DBBUFFER option, DBFIRSTROW returns the number of the first row in the row buffer. Note that the first row returned from the server (whose value is 1) is not necessarily the first row in the row buffer. The rows in the row buffer are dependent on manipulation by the application program. See the MOREINFO="NONE"dbclrbuf manual page for details. See AlsoREMAP="BO--Body"LINKEND="X38617"dbclrbuf
, LINKEND="X17373"DBCURROW
, LINKEND="X71422"dbgetrow
, LINKEND="X20854"DBLASTROW
, LINKEND="X10726"dbnextrow
, LINKEND="X97776"dbsetopt
, LINKEND="X60647"options
ID="IN4410742923"DBFIRSTROW
 ID="IN4412713224"dbfree_xlateID="X43669"dbfree_xlateID="IN4526713326"Character set translationsfreeing tables
ID="IN4518713327"Translation tablesfreeing
Free a pair of character set translation tables. FORMAT="LINESPECIFIC"RETCODE *dbfree_xlate(dbproc, xlt_tosrv, xlt_todisp)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"DBXLATE      *xlt_tosrv;FORMAT="LINESPECIFIC"DBXLATE      *xlt_todisp;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and server. xlt_tosrv - A pointer to a translation table used to translate display-specific character strings to the server character strings. The translation table is allocated via MOREINFO="NONE"dbload_xlate. xlt_todisp - A pointer to a translation table used to translate server character strings to display-specific character strings. The translation table is allocated via MOREINFO="NONE"dbload_xlate. ReturnsREMAP="BO--Body"SUCCEED or FAIL. CommentsID="IN4512673732"dbload_xlatedbload_xlateand freeing translation tablesfreeing translation tables
ID="IN4526673733"Character set translationstablesMARK="BULL" REMAP="BU--Bullet"This routine frees a pair of character set translation tables allocated by MOREINFO="NONE"dbload_xlate. Character set translation tables translate characters between the server's standard character set and the display device's character set. The following code fragment illustrates the use of MOREINFO="NONE"dbfree_xlate: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"char        destbuf[128]; int         srcbytes_used; DBXLATE     *xlt_todisp; DBXLATE     *xlt_tosrv; REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"dbload_xlate((DBPROCESS *)NULL, "iso_1",    "trans.xlt", &xlt_tosrv, &xlt_todisp); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"printf("Original string: \n\t%s\n\n",    TEST_STRING); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"dbxlate((DBPROCESS *)NULL, TEST_STRING,    strlen(TEST_STRING), destbuf, -1, xlt_todisp,                     &srcbytes_used); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"printf("Translated to display character set: \     \n\t%s\n\n", destbuf); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"dbfree_xlate((DBPROCESS *)NULL, xlt_tosrv,    xlt_todisp); See AlsoREMAP="BO--Body"LINKEND="X57212"dbload_xlate
, LINKEND="X19114"dbxlate
ID="IN4512644035"dbfree_xlate
 ID="IN459614336"dbfreebufID="X18180"dbfreebufID="IN4615614438"Command buffersclearing
Clear the command buffer. FORMAT="LINESPECIFIC"void dbfreebuf(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and server. ReturnsREMAP="BO--Body"None. CommentsMARK="BULL" REMAP="BU--Bullet"This routine clears a DBPROCESS command buffer by freeing any space allocated to it. It then sets the command buffer to NULL. Commands are added to the command buffer with the MOREINFO="NONE"dbcmd or MOREINFO="NONE"dbfcmd routine. ID="IN4619555043"DBNOAUTOFREE optionDBNOAUTOFREE optionand dbfreebufdbfreebufAfter a call to MOREINFO="NONE"dbsqlexec or MOREINFO="NONE"dbsqlsend, the first call to either MOREINFO="NONE"dbcmd or MOREINFO="NONE"dbfcmd automatically calls MOREINFO="NONE"dbfreebuf to clear the command buffer before the new text is entered. If this situation is undesirable, set the DBNOAUTOFREE option. When DBNOAUTOFREE is set, the command buffer is cleared only by an explicit call to MOREINFO="NONE"dbfreebuf. At any time, the application can access the contents of the command buffer through calls to MOREINFO="NONE"dbgetchar, MOREINFO="NONE"dbstrlen, and MOREINFO="NONE"dbstrcpy. See AlsoREMAP="BO--Body"LINKEND="X41151"dbcmd
, LINKEND="X29834"dbfcmd
, LINKEND="X20172"dbgetchar
, LINKEND="X41234"dbsqlexec
, LINKEND="X49376"dbsqlsend
, LINKEND="X48259"dbstrcpy
, LINKEND="X53545"dbstrlen
, LINKEND="X60647"options
ID="IN469525345"dbfreebuf
 ID="IN4610495646"dbfreequalID="X23352"dbfreequal
Free the memory allocated by MOREINFO="NONE"dbqualID="IN476475948"dbqualfreeing allocated memory
. FORMAT="LINESPECIFIC"void dbfreequal(qualptr)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"char         *qualptr;ParametersREMAP="RI--RefIndent"qualptr - A pointer to the memory allocated by MOREINFO="NONE"dbqual. ReturnsREMAP="BO--Body"None. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbfreequal is one of the DB-Library browse mode routines. See the Introduction for a detailed discussion of browse mode. MOREINFO="NONE"dbqual provides a MOREINFO="NONE"where clause that the application can use to update a single row in a browsable table. In doing so, it dynamically allocates a buffer to contain the MOREINFO="NONE"where clause. When the MOREINFO="NONE"where clause is no longer needed, the application can use MOREINFO="NONE"dbfreequal to de-allocate the buffer. See AlsoREMAP="BO--Body"LINKEND="X46501"dbqual
ID="IN4710446254"dbfreequal
 ID="IN4710416555"dbfreesortID="X50825"dbfreesort
Free a sort order structure allocated by MOREINFO="NONE"dbloadsortID="IN4811416657"Sort ordersfreeing
. FORMAT="LINESPECIFIC"RETCODE dbfreesort(dbproc, sortorder)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS      *dbproc;FORMAT="LINESPECIFIC"DBSORTORDER    *sortorder;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and server. sortorder - A pointer to a DBSORTORDER structure allocated via MOREINFO="NONE"dbloadsort. ReturnsREMAP="BO--Body"SUCCEED or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbfreesort frees a sort order structure which was allocated via MOREINFO="NONE"dbloadsort. DB-Library routines such as MOREINFO="NONE"dbstrcmp and MOREINFO="NONE"dbstrsort use sort orders to determine how character data must be sorted. ID="IN4811416662"Sort ordersWhen an application program does sorting or comparing, it automatically sorts character data the same way the server does. If no sort order has been loaded, routines such as MOREINFO="NONE"dbstrcmp and MOREINFO="NONE"dbstrsort sort characters by their binary values. Application programs must not attempt to use operating-system facilities to free the sortorder structure directly, as it may have been allocated using some mechanism other than MOREINFO="NONE"malloc (on operating systems where MOREINFO="NONE"malloc is not supported), and it may consist of multiple parts, some of which must be freed separately. The following code fragment illustrates the use of MOREINFO="NONE"dbfreesort: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"sortorder = dbloadsort(dbproc);  retval = dbstrcmp(dbproc, "ABC", 3, "abc", 3,sortorder); printf("ABC dbstrcmp'ed with abc yields %d.\n",    retval);  retval = dbstrcmp(dbproc, "abc", 3, "ABC", 3,    sortorder); printf("abc dbstrcmp'ed with ABC yields %d.\n",    retval);  dbfreesort(dbproc, sortorder); See AlsoREMAP="BO--Body"LINKEND="X42259"dbloadsort
, LINKEND="X38801"dbstrcmp
, LINKEND="X41485"dbstrsort
ID="IN4810386964"dbfreesort
 ID="IN489357265"dbgetcharID="X20172"dbgetcharID="IN4915357367"Command buffersgetting characters
ID="IN4910357368"Charactersgetting from command buffer
Return a pointer to a character in the command buffer. FORMAT="LINESPECIFIC"char *dbgetchar(dbproc, n)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"int           n;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and server. n - The character to find in the command buffer. The first character is the 0'th character. ReturnsREMAP="BO--Body"MOREINFO="NONE"dbgetchar returns a pointer to the n'th character in the command buffer. If n is not in range, MOREINFO="NONE"dbgetchar returns NULL. CommentsMARK="BULL" REMAP="BU--Bullet"You can use MOREINFO="NONE"dbgetchar to find a particular character in the command buffer. It returns a pointer to the n'th character in the command buffer. Internally, the command buffer is a linked list of non-null-terminated text strings. MOREINFO="NONE"dbgetchar, MOREINFO="NONE"dbstrcpy, and MOREINFO="NONE"dbstrlen together provide a way to locate and copy parts of the command buffer. Since the command buffer is not just one large text string, but rather a linked list of text strings, you must use MOREINFO="NONE"dbgetchar to index through the buffer. If you just get a pointer using MOREINFO="NONE"dbgetchar and then increment it yourself, it will probably fall off the end of a string and cause a segmentation fault. See AlsoREMAP="BO--Body"LINKEND="X41151"dbcmd
, LINKEND="X29834"dbfcmd
, LINKEND="X18180"dbfreebuf
, LINKEND="X48259"dbstrcpy
, LINKEND="X53545"dbstrlen
ID="IN499327674"dbgetchar
 ID="IN4912297975"dbgetcharset
ID="IN4913297976"Character setreturning client
ID="IN4934297977"Returning the client character set
ID="IN4932297978"Getting the client character set
ID="IN4919278179"DBPROCESS structuregetting client character set fromID="X16298"dbgetcharset
Get the name of the client character set from the DBPROCESS structure. FORMAT="LINESPECIFIC"char *dbgetcharset(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library/C uses to manage communications and data between the front end and server. ReturnsREMAP="BO--Body"A pointer to the null-terminated name of the client character set, or NULL in case of error. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbgetcharset returns the name of the client's character set. DB-Library/C clients can use a different character set than the server or servers to which they are connected. If a client and server are using different character sets, and the server supports character translation for the client's character set, it will perform all conversions to and from its own character set when communicating with the client. An application can inform the server what character set it is using via DBSETLCHARSET. To determine if the server is performing character set translations, an application can call MOREINFO="NONE"dbcharsetconv. To get the name of the server character set, an application can call MOREINFO="NONE"dbservcharset. See AlsoREMAP="BO--Body"LINKEND="X19407"dbcharsetconv
, LINKEND="X88162"dblogin
, LINKEND="X42139"dbopen
, LINKEND="X28915"dbservcharset
, LINKEND="X49378"DBSETLCHARSET
ID="IN5012248586"dbgetcharset
 ID="IN5012218887"dbgetloginfoID="X36015"dbgetloginfo
Transfer TDS login response information from a DBPROCESS structure to a newly-allocated DBLOGINFO structure. FORMAT="LINESPECIFIC"RETCODE dbgetloginfo(dbproc, loginfo)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"DBLOGINFO    **loginfo;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library/C uses to manage communications and data between the front end and the server. loginfo - A pointer to a DBLOGINFO pointer. MOREINFO="NONE"dbgetloginfo sets the DBLOGINFO pointer to the address of a newly-allocated DBLOGINFO structure. ReturnsREMAP="BO--Body"SUCCEED or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbgetloginfo transfers TDS login response information from a DBPROCESS structure to a newly-allocated DBLOGINFO structure. An application needs to call MOREINFO="NONE"dbgetloginfo only if 1) it is an Open Server gateway application and 2) it is using TDS passthrough. TDS (Tabular Data Stream) is an application protocol used for the transfer of requests and request results between clients and servers. When a client connects directly to a server, the two programs negotiate the TDS format they will use to send and receive data. When a gateway application uses TDS passthrough, the application forwards TDS packets between the client and a remote server without examining or processing them. For this reason, the remote server and the client must agree on a TDS format to use. MOREINFO="NONE"dbgetloginfo is the second of four calls, two of them Server Library calls, that allow a client and remote server to negotiate a TDS format. The calls, which can only be made in a SRV_CONNECT event handler, are: MARK="DASH" REMAP="BS--BulletSub"MOREINFO="NONE"   srv_getloginfo - Allocate a DBLOGINFO structure and fill it with TDS information from a client SRV_PROC. MOREINFO="NONE"   dbsetloginfo - Transfer the TDS information retrieved in step 1 from the DBLOGINFO structure to a DB-Library/C LOGINREC structure, and then free the DBLOGINFO structure. After the information is transferred, the application can use this LOGINREC structure in the MOREINFO="NONE"dbopen call which establishes its connection with the remote server. MOREINFO="NONE"   dbgetloginfo - Transfer the remote server's response to the client's TDS information from a DBPROCESS structure into a newly-allocated DBLOGINFO structure. MOREINFO="NONE"   srv_setloginfo - Send the remote server's response, retrieved in step 3, to the client, and then free the DBLOGINFO structure. This is an example of a SRV_CONNECT handler preparing a remote connection for TDS passthrough: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"  RETCODE connect_handler(srvproc) SRVPROC         *srvproc; { DBLOGINFO    *loginfo; LOGINREC     *loginrec; DBPROCESS    *dbproc; REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"  /* ** Get the TDS login information from the client ** SRV_PROC. */ srv_getloginfo(srvproc, &loginfo); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"  /* Get a LOGINREC structure */ loginrec = dblogin(); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"  /* ** Initialize the LOGINREC with the login info** from the SRV_PROC. */ dbsetloginfo(loginrec, loginfo); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"  /* Connect to the remote server */dbproc = dbopen(loginrec, REMOTE_SERVER_NAME); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"  /* ** Get the TDS login response information from  ** the remote connection. */ dbgetloginfo(dbproc, &loginfo); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"  /* ** Return the login response information to the  ** SRV_PROC. */ srv_setloginfo(srvproc, loginfo); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"  /* Accept the connection and return */ srv_senddone(srvproc, 0, 0, 0); return(SRV_CONTINUE); } See AlsoREMAP="BO--Body"LINKEND="X16128"dbrecvpassthru
, LINKEND="X47536"dbsendpassthru
, LINKEND="X47652"dbsetloginfo
ID="IN5112189294"dbgetloginfo
 ID="IN5114159595"dbgetlusernamedbgetlusername
Return the user name from a LOGINREC structure. FORMAT="LINESPECIFIC"int dbgetlusername(login, name_buffer, buffer_len)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"LOGINREC       *login;FORMAT="LINESPECIFIC"BYTE           *name_buffer;FORMAT="LINESPECIFIC"int            buffer_len;ParametersREMAP="RI--RefIndent"loginrec - A pointer to a LOGINREC structure, which can be passed as an argument to MOREINFO="NONE"dbopen. You can get a LOGINREC structure by calling MOREINFO="NONE"dblogin. name_buffer - A pointer to a buffer. The user name will be copied from the LOGINREC structure to this buffer. buffer_len - The length, in bytes, of the destination buffer. ReturnsREMAP="BO--Body"The number of bytes copied into the destination buffer, not including the null-terminator. REMAP="BO--Body"If the user name is more than buffer_len - 1 bytes long, MOREINFO="NONE"dbgetlusername copies buffer_len - 1 bytes into the destination buffer and returns DBTRUNCATED. REMAP="BO--Body"MOREINFO="NONE"dbgetlusername returns FAIL if loginrec is NULL, name_buffer is NULL, or buffer_len is less than 0. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbgetlusername copies the user name from LOGINREC structure into the name_buffer buffer. To set the user name in a LOGINREC structure, use DBSETLUSER. MOREINFO="NONE"dbgetlusername copies a maximum of buffer_len - 1 bytes, and null-terminates the user name string. Since the longest user name in a LOGINREC structure is DBMAXNAME bytes, an application will never need a destination buffer longer than DBMAXNAME + 1 bytes. If the user name is in the LOGINREC is longer than buffer_len - 1 bytes, MOREINFO="NONE"dbgetlusername truncates the name and returns DBTRUNCATED. See AlsoREMAP="BO--Body"LINKEND="X88162"dblogin
, LINKEND="X77719"DBSETLUSER
ID="IN52141299102"dbgetlusername
 ID="IN52139102103"dbgetmaxprocsID="X85672"dbgetmaxprocs
Determine the current maximum number of simultaneously open DBPROCESSID="IN53197105105"DBPROCESS structuredetermining current limit available
es. FORMAT="LINESPECIFIC"int dbgetmaxprocs()ParametersREMAP="BO--Body"None. ReturnsREMAP="BO--Body"An integer representing the current limit on the number of simultaneously open DBPROCESSes. CommentsMARK="BULL" REMAP="BU--Bullet"A DB-Library program has a maximum number of simultaneously open DBPROCESSes. By default, this number is 25. The application program may change this limit by calling MOREINFO="NONE"dbsetmaxprocs. See AlsoREMAP="BO--Body"LINKEND="X42139"dbopen
, LINKEND="X47066"dbsetmaxprocs
ID="IN53134108111"dbgetmaxprocs
 ID="IN53121111112"dbgetnatlang
ID="IN539-1113113"Languagesgetting name from DBPROCESS
ID="IN5331-1113114"Returning the national language
ID="IN5329-1113115"Getting the national language
ID="IN5319-3115116"DBPROCESS structuregetting national language fromdbgetnatlang
Get the national language from the DBPROCESS structure. FORMAT="LINESPECIFIC"char* dbgetnatlang(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library/C uses to manage communications and data between the front end and server. ReturnsREMAP="BO--Body"A pointer to a character string representing the national language that the client DBPROCESS is using. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbgetnatlang returns a pointer to the name of the national language that a client is using. DB-Library/C clients may use a different national language than the server or servers to which they are connected. An application can inform the server what national language it wishes to use via DBSETLNATLANG. See AlsoREMAP="BO--Body"LINKEND="X88162"dblogin
, LINKEND="X42139"dbopen
, LINKEND="X52068"DBSETLNATLANG
ID="IN5412-6119123"dbgetnatlang
 ID="IN548-9122124"dbgetoffdbgetoffID="IN5515-9123126"Command bufferschecking for Transact-SQL constructs
Check for the existence of Transact-SQL constructs in the command buffer. FORMAT="LINESPECIFIC"int dbgetoff(dbproc, offtype, startfrom)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"DBUSMALLINT  offtype;FORMAT="LINESPECIFIC"int          startfrom;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and server. offtype ID="IN557-9123129"Offsetstypes of
ID="IN5519-11125130"sybdb.h header file
- The type of offset you want to find. The types are defined in the header file sybdb.h and are: REMAP="UN--Under"OFF_SELECT OFF_FROM OFF_ORDER OFF_COMPUTE OFF_TABLE OFF_PROCEDURE OFF_STATEMENT OFF_PARAM OFF_EXEC REMAP="UN--Under"See the MOREINFO="NONE"options manual page for details. startfrom - The point in the buffer to start looking. The command buffer begins at 0. ReturnsREMAP="BO--Body"The character offset into the command buffer for the specified offset. If the offset is not found, -1 is returned. CommentsID="IN5515-17131133"DBOFFSET optionDBOFFSET optionand dbgetoffdbgetoffMARK="BULL" REMAP="BU--Bullet"If the DBOFFSET option has been set (see the MOREINFO="NONE"options manual page), this routine can check for the location of certain Transact-SQL constructs in the command buffer. As a simple example, assume the program doesn't know the contents of the command buffer but needs to know where the SQL keyword MOREINFO="NONE"select appears: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"int     select_offset[10]; int     last_offset; int     i; REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* Set the offset option */ dbsetopt(dbproc, DBOFFSET, "select"); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* ** Assume the command buffer contains the** following selects.*/ dbcmd(dbproc, "select x = 100 select y = 5"); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* Send the query to SQL Server */ dbsqlexec(dbproc); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* Get all the offsets to the select keyword */ for (i = 0, last_offset = 0; last_offset != -1;    i++)     if ((last_offset = dbgetoff(dbproc,        OFF_SELECT, last_offset) != -1)     select_offset[i] = last_offset++; REMAP="UN--Under"In this example, select_offset[0] = 0 and select_offset[1] = 15. MOREINFO="NONE"dbgetoff does not recognize MOREINFO="NONE"select statements in a subquery. Thus, if the command buffer contained: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"select pub_name from publishers where pub_id not in    (select pub_id     from titles     where type = "business") REMAP="UN--Under"the second "select" would not be recognized. See AlsoREMAP="BO--Body"LINKEND="X41151"dbcmd
, LINKEND="X20172"dbgetchar
, LINKEND="X97776"dbsetopt
, LINKEND="X48259"dbstrcpy
, LINKEND="X53545"dbstrlen
, LINKEND="X60647"options
ID="IN558-20134135"dbgetoff
 ID="IN5511-23137136"dbgetpacket
ID="IN553-23137137"TDSpacket size:returning
ID="IN5525-23137138"Returning TDS packet size
ID="IN5511-23137139"Packet sizeTDS
ID="IN5518-25139140"LOGINREC structurepacket size field
ID="IN5519-25139141"Text and image data
ID="IN5519-25139142"Tabular Data StreamroutinesID="X32032"dbgetpacket
Return the TDS packet size currently in use. FORMAT="LINESPECIFIC"int dbgetpacket(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library/C uses to manage communications and data between the front end and the server. ReturnsREMAP="BO--Body"The TDS packet size currently in use. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbgetpacket returns the TDS packet size currently in use. TDS (Tabular Data Stream) is an application protocol used for the transfer of requests and request results between clients and servers. TDS data is sent in fixed-size chunks, called "packets". TDS packets have a default size of 512 bytes. An application may change the TDS packet size via MOREINFO="NONE"DBSETLPACKET, which sets the packet size field in the LOGINREC structure. When the application logs in to the server or Open Server, the server sets the TDS packet size for the created DBPROCESS connection to be equal to or less than the value of this field. The packet size is set to a value less than the value of the field if the server is experiencing space constraints. Otherwise, the packet size will be equal to the value of the field. If an application sends or receives large amounts of text or image data, a packet size larger than the default 512 bytes may improve efficiency, since it results in fewer network reads and writes. See AlsoREMAP="BO--Body"LINKEND="X60486"DBSETLPACKET
ID="IN5611-28143149"dbgetpacket
 ID="IN568-31146150"dbgetrowID="X71422"dbgetrowID="IN5711-31147152"Row buffersreading specified rows
ID="IN574-31147153"Rowsreading specified in buffer
Read the specified row in the row buffer. FORMAT="LINESPECIFIC"STATUS dbgetrow(dbproc, row)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"DBINT         row;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and server. row - The number of the row to read. Rows are counted from the first row returned from the server, whose number is 1. Note that the first row in the row buffer is not necessarily the first row returned from the server. ReturnsREMAP="BO--Body"MOREINFO="NONE"dbgetrow can return four different types of values: MARK="BULL" REMAP="BU--Bullet"If the current row is a regular row, REG_ROW is returned. If the current row is a compute row, the computeid of the row is returned. (See MOREINFO="NONE"dbaltbind for information on the computeid.) If the row is not in the row buffer, NO_MORE_ROWS is returned and the current row is left unchanged. If the routine was unsuccessful, FAIL is returned. CommentsMARK="BULL" REMAP="BU--Bullet"ID="IN5715-37153158"DBBUFFER optionDBBUFFER optionand dbgetrowdbgetrow
MOREINFO="NONE"dbgetrow sets the current row in the row buffer to a specific row and reads it. This routine only works if the DBBUFFER option is on, enabling row buffering. When MOREINFO="NONE"dbgetrow is called, any binding of row data to program variables (as specified with MOREINFO="NONE"dbbind or MOREINFO="NONE"dbaltbind) takes effect. ID="IN5711-37153159"Row buffersRow buffering provides a way to keep a specified number of server result rows in program memory. Without row buffering, the result row generated by each new MOREINFO="NONE"dbnextrow call overwrites the contents of the previous result row. Row buffering is therefore useful for programs that need to look at result rows in a non-sequential manner. It does, however, carry a memory and performance penalty because each row in the buffer must be allocated and freed individually. Therefore, use it only if you need to. Specifically, the application should only turn the DBBUFFER option on if it calls MOREINFO="NONE"dbgetrow or MOREINFO="NONE"dbsetrow. Note that row buffering has nothing to do with network buffering and is a completely independent issue. When row buffering is not enabled, the application processes each row as it is read from the server, by calling MOREINFO="NONE"dbnextrow repeatedly until it returns NO_MORE_ROWS. When row buffering is enabled, the application can use MOREINFO="NONE"dbgetrow to jump to any row that has already been read from the server with MOREINFO="NONE"dbnextrow. Subsequent calls to MOREINFO="NONE"dbnextrow cause the application to read successive rows in the buffer. When MOREINFO="NONE"dbnextrow reaches the last row in the buffer, it reads rows from the server again, if there are any. Once the buffer is full, MOREINFO="NONE"dbnextrow does not read any more rows from the server until some of the rows have been cleared from the buffer with MOREINFO="NONE"dbclrbuf. ID="IN5710-45161160"DBFIRSTROWDBFIRSTROWand dbgetrowdbgetrowThe macros DBFIRSTROW, DBLASTROW, and DBCURROW are useful in conjunction with MOREINFO="NONE"dbgetrow calls. DBFIRSTROW, for instance, gets the number of the first row in the buffer. Thus, the call: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"dbgetrow(dbproc, DBFIRSTROW(dbproc)) REMAP="UN--Under"sets the current row to the first row in the buffer. The routine MOREINFO="NONE"dbsetrow sets a buffered row to "current" but does not read the row. For an example of row buffering, see Example 4 of the on-line example programs.See AlsoREMAP="BO--Body"LINKEND="X21854"dbaltbind
, LINKEND="X14206"dbbind
, LINKEND="X38617"dbclrbuf
, LINKEND="X17373"DBCURROW
, LINKEND="X66598"DBFIRSTROW
, LINKEND="X20854"DBLASTROW
, LINKEND="X10726"dbnextrow
, LINKEND="X55181"dbsetrow
, LINKEND="X60647"options
ID="IN578-48164162"dbgetrow
 ID="X80614"DBGETTIMEID="IN589-51168163"DBGETTIME
ID="IN584-51168165"Timeamount DB-Library waits for a server response
ID="IN587-51168166"Server 
Return the number of seconds that DB-Library will wait for a server response to a SQL command. FORMAT="LINESPECIFIC"int DBGETTIME()ParametersREMAP="BO--Body"None. ReturnsREMAP="BO--Body"The timeout value-the number of seconds that DB-Library waits for a server response before timing out. A timeout value of 0 represents an infinite timeout period. CommentsMARK="BULL" REMAP="BU--Bullet"This routine returns the length of time in seconds that DB-Library will wait for a server response during calls to MOREINFO="NONE"dbsqlexec, MOREINFO="NONE"dbsqlok, MOREINFO="NONE"dbresults, and MOREINFO="NONE"dbnextrow. The default timeout value is 0, which represents an infinite timeout period. The program can call MOREINFO="NONE"dbsettime to change the timeout value. See AlsoREMAP="BO--Body"LINKEND="X68770"dbsettime
ID="IN589-54171172"DBGETTIME
 ID="IN5813-57174173"dbgetuserdataID="X34885"dbgetuserdata
Return a pointer to user-allocated data from a DBPROCESSID="IN5913-59177175"User-supplieddata:associating with a DBPROCESS
ID="IN5919-61179176"DBPROCESS structuregetting user-allocated data
ID="IN594-61179177"Datagetting user-allocated
 structure. FORMAT="LINESPECIFIC"BYTE *dbgetuserdata(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and server. ReturnsREMAP="BO--Body"A generic BYTE pointer to the user's private data space. This pointer must have been previously saved with the MOREINFO="NONE"dbsetuserdata routine. CommentsMARK="BULL" REMAP="BU--Bullet"This routine returns, from a DBPROCESS structure, a pointer to user-allocated data. The application must have previously saved this pointer with the MOREINFO="NONE"dbsetuserdata routine. MOREINFO="NONE"dbgetuserdata and MOREINFO="NONE"dbsetuserdata allow the application to associate user data with a particular DBPROCESS. This avoids the necessity of using global variables for this purpose. One use for these routines is to handle deadlock, as shown in the example on the MOREINFO="NONE"dbsetuserdataID="IN598-61179182"Deadlockhandling
 manual page. That example reruns the transaction when the application's message handler detects deadlock. This routine is particularly useful when the application has multiple DBPROCESSes. See AlsoREMAP="BO--Body"LINKEND="X15711"dbsetuserdata
ID="IN5913-64182184"dbgetuserdata
 REMAP="BO--Body"ID="X23034"dbhasretstatID="IN43229753"Remote procedure callsdetermining whether status number was generated
Determine whether the current command or remote procedure call generated a return status number. FORMAT="LINESPECIFIC"DBBOOL dbhasretstat(dbprWoc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and server. ReturnsREMAP="BO--Body"TRUE or FALSE. CommentsID="IN43179758"Stored proceduresStored proceduresand status numbersstatus numbers
ID="IN43149759"Status numbersdetermining whether generatedMARK="BULL" REMAP="BU--Bullet"This routine determines whether the current Transact-SQL command or remote procedure call generated a return status number. Status numbers are returned by all stored procedures running on a server whose version is 4.0 or above. Since status numbers are a feature of stored procedures, only a remote procedure call or an MOREINFO="NONE"execute command can generate a status number. The MOREINFO="NONE"dbretstatus routine actually gets the status number. Stored procedures that complete normally return a status number of 0. For a list of return status numbers, see the  SQL Server Reference Manual. When executing a stored procedure, the server returns the status number immediately after returning all other results. Therefore, the application can call MOREINFO="NONE"dbhasretstat only after processing the stored procedure's results by calling MOREINFO="NONE"dbresults, as well as MOREINFO="NONE"dbnextrow if appropriate. (Note that a stored procedure can generate several sets of results-one for each MOREINFO="NONE"select it contains. Before the application can call MOREINFO="NONE"dbhasretstat or MOREINFO="NONE"dbretstatus, it must call MOREINFO="NONE"dbresults and MOREINFO="NONE"dbnextrow as many times as necessary to process all the results.) The order in which the application processes the status number and any return parameter values is unimportant. For an example of this routine, see Example 8 of the on-line example programs.See AlsoREMAP="BO--Body"LINKEND="X10726"dbnextrow
, LINKEND="X35104"dbresults
, LINKEND="X29147"dbretdata
, LINKEND="X95390"dbretstatus
, LINKEND="X47823"dbrpcinit
, LINKEND="X50365"dbrpcparam
, LINKEND="X71145"dbrpcsend
ID="IN431294811"dbhasretstat
 ID="IN436911112"dbinitID="X24387"dbinitID="IN4410911214"DB-Libraryinitializing
Initialize DB-Library. FORMAT="LINESPECIFIC"RETCODE  dbinit()ParametersREMAP="BO--Body" None. ReturnsREMAP="BO--Body"SUCCEED or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"This routine initializes certain private DB-Library structures. For environments that require it, the application must call MOREINFO="NONE"dbinit before calling any other DB-Library routine. Most DB-Library routines will cause the application to exit if they are called before MOREINFO="NONE"dbinit. To ensure future compatibility and portability, it is strongly recommended that all applications call MOREINFO="NONE"dbinit, no matter what their operating environment. See AlsoREMAP="BO--Body"LINKEND="X99227"dbexit
ID="IN446881520"dbinit
 ID="IN4429812221"DBIORDESC (UNIX and AOS/VS)  ID="X41944"DBIORDESC (UNIX and AOS/VS only)

Provide program access to the UNIX or AOS/VS file descriptor used by a DBPROCESSID="IN456772723"Serverreading data from (UNIX and AOS/VS)
ID="IN4535733124"File descriptors (UNIX and AOS/VS) access to
ID="IN454693525"Datareading server (UNIX and AOS/VS) 
 to read data coming from the server. FORMAT="LINESPECIFIC"int DBIORDESC(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and server. ReturnsREMAP="BO--Body"An integer file descriptor used by the specified DBPROCESS to read data coming from the server. CommentsID="IN4513653930"Input streamsresponding to multiple (UNIX and AOS/VS)MARK="BULL" REMAP="BU--Bullet"This routine provides a way for an application to respond effectively to multiple input streams. Depending on the nature of your application, the time between a request for information from the server (usually made via a call to MOREINFO="NONE"dbsqlsend) and the server's response (read by calling MOREINFO="NONE"dbsqlok, MOREINFO="NONE"dbresults, or MOREINFO="NONE"dbnextrow) may be significant. You may use this time to service other parts of your application. The DBIORDESC routine provides a way to obtain the I/O descriptor which a DBPROCESS uses to read the data stream from the server. This information may then be used with various operating system facilities (such as the UNIX MOREINFO="NONE"select call) to allow the application to respond effectively to multiple input streams. MOREINFO="NONE"dbpoll checks if a server response has arrived for any of an application's DBPROCESSes. The use of MOREINFO="NONE"dbpoll is generally simpler than the use of DBIORDESC. For this reason, and because DBIORDESC is non-portable, it is generally preferable to use MOREINFO="NONE"dbpoll. The file descriptor returned by DBIORDESC may only be used with operating system facilities that do not read data from the incoming data stream. If data is read from this stream by any means other than through a DB-Library routine, communications between the front-end and the server will become hopelessly scrambled. An application can use the DB-Library DBRBUF routine, in addition to the UNIX MOREINFO="NONE"select function or AOS/VS equivalent, to help determine whether any more data from the server is available for reading. A companion routine, DBIOWDESC, provides access to the file descriptor used to write data to the server. See AlsoREMAP="BO--Body"LINKEND="X41151"dbcmd
, LINKEND="X19954"DBIOWDESC
, LINKEND="X10726"dbnextrow
, LINKEND="X45215"dbpoll
, LINKEND="X55434"DBRBUF
, LINKEND="X35104"dbresults
, LINKEND="X21206"dbsqlok
, LINKEND="X49376"dbsqlsend
ID="IN4529584632"DBIORDESC (UNIX and AOS/VS)  
 ID="IN4529515333"DBIOWDESC (UNIX and AOS/VS)  ID="X19954"DBIOWDESC (UNIX and AOS/VS only)
Provide program access to the UNIX or AOS/VS file descriptor used by a DBPROCESSID="IN4635475835"File descriptors (UNIX and AOS/VS) access to
ID="IN464436236"Datawriting to the server (UNIX and AOS/VS) 
ID="IN466396637"Serverwriting data to (UNIX and AOS/VS)
 to write data to the server. FORMAT="LINESPECIFIC"int DBIOWDESC(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and server. ReturnsREMAP="BO--Body"An integer file descriptor used by the specified DBPROCESS to write data to the server. CommentsID="IN4613357042"Input streamsutilizing multiple (UNIX and AOS/VS)
ID="IN4614317443"Output streamsutilizing multiple (UNIX and AOS/VS) MARK="BULL" REMAP="BU--Bullet"This routine provides a way for an application to effectively utilize multiple input and output streams. Depending on the nature of your application, the time interval between the initiation of an attempt to write information to the server (usually made via a call to MOREINFO="NONE"dbsqlsend) and the completion of that attempt may be significant. You may use this time to service other parts of your application. The DBIOWDESC routine provides a way to obtain the I/O descriptor which a DBPROCESS uses to write the data stream to the server. This information may then be used with various operating system facilities (such as the UNIX MOREINFO="NONE"select function) to allow the application to effectively utilize multiple input and output streams. The file descriptor returned by this routine may only be used with operating system facilities that do not write data to the outgoing data stream. If data is written to this stream by any means other than through a DB-Library routine, communications between the front-end and the server will become hopelessly scrambled. A companion routine, DBIORDESC, provides access to the file descriptor used to read data coming from the server. For some applications, another routine, MOREINFO="NONE"dbpoll may be preferable to DBIORDESC. See AlsoREMAP="BO--Body"LINKEND="X41151"dbcmd
, LINKEND="X41944"DBIORDESC
, LINKEND="X10726"dbnextrow
, LINKEND="X45215"dbpoll
, LINKEND="X35104"dbresults
, LINKEND="X21206"dbsqlok
, LINKEND="X49376"dbsqlsend
ID="IN4629248145"DBIOWDESC (UNIX and AOS/VS)  
 ID="IN469218446"DBISAVAILID="X27527"DBISAVAIL
Determine whether a DBPROCESSID="IN4719198748"DBPROCESS structuredetermining whether available
 is available for general use. FORMAT="LINESPECIFIC"DBBOOL DBISAVAIL(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and server. ReturnsREMAP="BO--Body"TRUE if the DBPROCESS is available for general use, otherwise FALSE. CommentsMARK="BULL" REMAP="BU--Bullet"This routine indicates whether the specified DBPROCESS is available for general use. When a DBPROCESS is first opened, it is marked as being available, until some use is made of it. Many DB-Library routines will automatically set the DBPROCESS to "not available," but only MOREINFO="NONE"dbsetavail will reset it to "available." This facility is useful when several parts of a program are attempting to share a single DBPROCESSID="IN4719178953"DBPROCESS structuresharing single
. See AlsoREMAP="BO--Body"LINKEND="X60441"dbsetavail
ID="IN479149255"DBISAVAIL
 ID="IN477119556"dbisoptID="X50317"dbisoptID="IN487119658"Optionschecking status of
Check the status of a server or DB-Library option. FORMAT="LINESPECIFIC"DBBOOL dbisopt(dbproc, option, param)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"int          option;FORMAT="LINESPECIFIC"char         *param;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and server. Unlike the functions MOREINFO="NONE"dbsetopt and MOREINFO="NONE"dbclropt, dbproc cannot be NULL here. option - The option to be checked. See the MOREINFO="NONE"options manual page for the list of options. param - Certain options take parameters. The DBOFFSET option, for example, takes as a parameter the SQL construct for which offsets are to be returned. The MOREINFO="NONE"options manual page lists those options that take parameters. If an option does not take a parameter, param must be NULL. REMAP="UN--Under"If the option you are checking takes a parameter but there can be only one instance of the option, MOREINFO="NONE"dbisopt ignores the param argument. For example, MOREINFO="NONE"dbisopt ignores the value of param when checking the DBBUFFER option, because row buffering can have only one setting at a time. On the other hand, the DBOFFSET option can have several settings, each with a different parameter. It may have been set twice-to look for offsets to MOREINFO="NONE"select statements and offsets to MOREINFO="NONE"order MOREINFO="NONE"by clauses. In that case, MOREINFO="NONE"dbisopt needs the param argument to determine whether to check the MOREINFO="NONE"select offset or the MOREINFO="NONE"order MOREINFO="NONE"by offset. ReturnsREMAP="BO--Body"TRUE or FALSE. CommentsMARK="BULL" REMAP="BU--Bullet"This routine checks the status of the server and DB-Library options. Although server options may be set and cleared directly through SQL, the application should instead use MOREINFO="NONE"dbsetopt and MOREINFO="NONE"dbclropt to set and clear options. This provides a uniform interface for setting both server and DB-Library options. It also allows the application to use the MOREINFO="NONE"dbisopt function to check the status of an option. For a list of each option and its default status, see the manual page for MOREINFO="NONE"options. See AlsoREMAP="BO--Body"LINKEND="X69074"dbclropt
, LINKEND="X97776"dbsetopt
, LINKEND="X60647"options
ID="IN48789964"dbisopt
 ID="IN489510265"DBLASTROWID="X20854"DBLASTROWID="IN4911510367"Row buffersreturning number of last row
ID="IN494510368"Rowsreturning number of last in buffer
Return the number of the last row in the row buffer. FORMAT="LINESPECIFIC"DBINT DBLASTROW(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and server. ReturnsREMAP="BO--Body"The number of the last row in the row buffer. This routine returns 0 if there's an error. CommentsMARK="BULL" REMAP="BU--Bullet"This macro returns the number of the last row in the row buffer. Rows are counted from the first row returned from the server, whose number is 1, and not from the top of the row buffer. ID="IN4915-110973"DBBUFFER optionDBBUFFER optionand DBLASTROWDBLASTROWIf you aren't buffering rows, DBFIRSTROW, DBCURROW, and DBLASTROW will always have the same value. If you have enabled buffering by setting the DBBUFFER option, DBLASTROW will return the number of the row that is the last row in the row buffer. See AlsoREMAP="BO--Body"LINKEND="X38617"dbclrbuf
, LINKEND="X17373"DBCURROW
, LINKEND="X66598"DBFIRSTROW
, LINKEND="X71422"dbgetrow
, LINKEND="X10726"dbnextrow
, LINKEND="X97776"dbsetopt
, LINKEND="X60647"options
ID="IN499-411275"DBLASTROW
 ID="IN4912-711576"dbload_xlateID="X57212"dbload_xlateID="IN5026-711678"Character set translationsloading tables
ID="IN5018-711679"Translation tablesloading
Load a pair of character set translation tables. FORMAT="LINESPECIFIC"RETCODE dbload_xlate(dbproc, srv_charset, xlate_name,                     xlt_tosrv, xlt_todisp)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"char          *srv_charset;FORMAT="LINESPECIFIC"char          *xlt_name;FORMAT="LINESPECIFIC"DBXLATE       **xlt_tosrv;FORMAT="LINESPECIFIC"DBXLATE       **xlt_todisp;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and server. srv_charset - A pointer to the name of the server's character set. MOREINFO="NONE"dbload_xlate looks for a directory of this name in the SYBASE charsets directory. For example, if the server is using the iso_1 character set, MOREINFO="NONE"dbload_xlate looks for $SYBASE/charsets/iso_1 on UNIX systems, or SYBASE:[CHARSETS.ISO_1] on VMS systems. xlt_name - A pointer to the name of the file containing the display-specific character set. MOREINFO="NONE"dbload_xlate looks for this file in the server character set directory. xlt_tosrv - A pointer to a pointer to a character set translation table used to translate display-specific character strings to the server character strings. The translation table is allocated via MOREINFO="NONE"dbload_xlate. xlt_todisp - A pointer to a pointer to a character set translation table used to translate server character strings to display-specific character strings. The translation table is allocated via MOREINFO="NONE"dbload_xlate. ReturnsREMAP="BO--Body"SUCCEED or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbload_xlate reads a display-specific localization file and allocates two character set translation tables: one for translations from the server's character set to the display-specific character set, and another for translations from the display-specific character set to the server's character set. The following code fragment illustrates the use of MOREINFO="NONE"dbload_xlate: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"char        destbuf[128]; int         srcbytes_used; DBXLATE*    xlt_todisp; DBXLATE     *xlt_tosrv; REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"dbload_xlate((DBPROCESS *)NULL, "iso_1",    "trans.xlt", &xlt_tosrv, &xlt_todisp); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"printf("Original string: \n\ %s\n\n",    TEST_STRING); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"dbxlate((DBPROCESS *)NULL, TEST_STRING,    strlen(TEST_STRING), destbuf, -1, xlt_todisp,     &srcbytes_used); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"printf("Translated to display character set: \ \n\t%s\n\n", destbuf); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"dbfree_xlate((DBPROCESS *)NULL, xlt_tosrv,    xlt_todisp); See AlsoREMAP="BO--Body"LINKEND="X43669"dbfree_xlate
, LINKEND="X19114"dbxlate
ID="IN5012-1011985"dbload_xlate
 ID="IN5010-1312286"dbloadsortID="X42259"dbloadsortID="IN5111-1312388"Sort ordersloading
Load a server sort order. FORMAT="LINESPECIFIC"DBSORTORDER *dbloadsort(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and server. ReturnsREMAP="BO--Body"A pointer to a DBSORTORDER structure on success, NULL on error. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbloadsort provides information about the sort order of the server's character set. This information can be used by MOREINFO="NONE"dbstrcmp or MOREINFO="NONE"dbstrsort to compare two character strings. MOREINFO="NONE"dbloadsort allocates a DBSORTORDER structure to contain the server character set sort order information. The structure is freed via MOREINFO="NONE"dbfreesort. The following code fragment illustrates the use of MOREINFO="NONE"dbloadsort: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"sortorder = dbloadsort(dbproc); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"retval = dbstrcmp(dbproc, "ABC", 3, "abc", 3,    sortorder); printf("ABC dbstrcmp'ed with abc yields %d.\n",    retval); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"retval = dbstrcmp(dbproc, "abc", 3, "ABC", 3,    sortorder); printf("abc dbstrcmp'ed with ABC yields %d.\n",    retval); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"dbfreesort(dbproc, sortorder);See AlsoREMAP="BO--Body"LINKEND="X50825"dbfreesort
, LINKEND="X38801"dbstrcmp
, LINKEND="X41485"dbstrsort
ID="IN5110-1612694"dbloadsort
 ID="IN517-1912995"dbloginID="X88162"dblogin
Allocate a login record for use in MOREINFO="NONE"dbopenID="IN5218-2113297"LOGINREC structureallocating
. FORMAT="LINESPECIFIC"LOGINREC *dblogin()ParametersREMAP="BO--Body"None.ReturnsREMAP="BO--Body"A pointer to a LOGINREC structure. MOREINFO="NONE"dblogin returns NULL if the structure could not be allocated. CommentsID="IN526-25136102"dbopengetting a LOGINRECMARK="BULL" REMAP="BU--Bullet"This routine allocates a LOGINREC structure for use with MOREINFO="NONE"dbopen. There are various routines available to supply components of the LOGINREC. The program may supply the host name, user name, user password, and application name-via MOREINFO="NONE"DBSETLHOST, MOREINFO="NONE"DBSETLUSER, MOREINFO="NONE"DBSETLPWD, and MOREINFO="NONE"DBSETAPP, respectively.  It is generally only necessary for the program to supply the user password (and even this can be eliminated if the password is a null value). The other variables in the LOGINREC structure will be set to default values. Other components of the LOGINREC may also be changed: MARK="DASH" REMAP="BS--BulletSub"The national language name can be set in a LOGINREC structure via MOREINFO="NONE"DBSETLNATLANG. Call MOREINFO="NONE"DBSETLNATLANG only if you do not wish to use the server's default national language. The TDS packet size can be set in a LOGINREC via MOREINFO="NONE"DBSETLPACKET. If not explicitly set, the TDS packet size defaults to 512 bytes. TDS is an application protocol used for the exchange of information between clients and servers. The character set can be set in a LOGINREC via MOREINFO="NONE"DBSETLCHARSET. An application needs to call MOREINFO="NONE"DBSETLCHARSET only if it is not using ISO-8859-1 (known to the server as "iso_1"). When a connection attempt is made between a client and a server, there are two ways in which the connection can fail (assuming that the system is correctly configured): MARK="DASH" REMAP="BS--BulletSub"The machine that the server is supposed to be on is running correctly and the network is running correctly. In this case, if there is no server listening on the specified port, the machine the server is supposed to be on will signal the client, via a network error, that the connection can't be formed. Regardless of MOREINFO="NONE"dbsetlogintime, the connection will fail. The machine that the server is on is down. In this case, the machine that the server is supposed to be on will not respond. Because "no response" is not considered to be an error, the network will not signal the client that an error has occurred. However, if MOREINFO="NONE"dbsetlogintime has been called to set a timeout period, a timeout error will occur when the client fails to receive a response within the set period. Here's a program fragment that uses MOREINFO="NONE"dblogin: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc; LOGINREC     *loginrec; REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"loginrec = dblogin(); DBSETLPWD(loginrec, "server_password"); DBSETLAPP(loginrec, "my_program"); dbproc = dbopen(loginrec, "my_server"); Once the application has made all its MOREINFO="NONE"dbopen calls, the LOGINREC structure is no longer necessary. The program can then call MOREINFO="NONE"dbloginfree to free the LOGINREC structure. See AlsoREMAP="BO--Body"LINKEND="X96175"dbloginfree
, LINKEND="X42139"dbopen
, LINKEND="X56457"dbrpwclr
, LINKEND="X58569"dbrpwset
, LINKEND="X75775"DBSETLAPP
, LINKEND="X49378"DBSETLCHARSET
, LINKEND="X47887"DBSETLHOST
, LINKEND="X52068"DBSETLNATLANG
, LINKEND="X60486"DBSETLPACKET
, LINKEND="X60994"DBSETLPWD
, LINKEND="X77719"DBSETLUSER
ID="IN527-28139104"dblogin
 ID="IN5211-31142105"dbloginfreeID="X96175"dbloginfreeID="IN5318-33145107"LOGINREC structurefreeing
Free a login record. FORMAT="LINESPECIFIC"void dbloginfree(loginptr)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"LOGINREC      *loginptr;ParametersREMAP="RI--RefIndent"loginptr - A pointer to a LOGINREC structure. ReturnsREMAP="BO--Body"None. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dblogin provides a LOGINREC structure for use with MOREINFO="NONE"dbopen. Once the application has made all its MOREINFO="NONE"dbopen calls, the LOGINREC structure is no longer necessary. MOREINFO="NONE"dbloginfree frees the memory associated with the specified LOGINREC structure. See AlsoREMAP="BO--Body"LINKEND="X88162"dblogin
, LINKEND="X42139"dbopen
ID="IN5311-36148113"dbloginfree
 REMAP="BO--Body"ID="X74520"dbmny4add
Add two DBMONEY4 values. FORMAT="LINESPECIFIC"RETCODE dbmny4add(dbproc, m1, m2, sum)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"DBMONEY4     *m1;FORMAT="LINESPECIFIC"DBMONEY4     *m2;FORMAT="LINESPECIFIC"DBMONEY4     *sum;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and the server.   REMAP="UN--Under"This parameter may be NULL. The DBPROCESS is used as a parameter to an application's error handler.   It also contains information on what language to print error messages in.  If a DBPROCESS is not supplied, the  default national language is used. m1 - A pointer to a DBMONEY4 value. m2 - A pointer to a DBMONEY4 value. sum - A pointer to a DBMONEY4 variable to hold the result of the addition. ReturnsREMAP="BO--Body"SUCCEED or FAIL. REMAP="BO--Body"MOREINFO="NONE"dbmny4add returns FAIL in case of overflow, or if m1, m2, or sum is NULL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbmny4add adds the m1 and m2 DBMONEY4 values and places the result in *sum. In case of overflow, MOREINFO="NONE"dbmny4add returns FAIL and sets *sum to $0.00. The range of legal DBMONEY4 values is from -$214,748.3648  to $214,748.3647. DBMONEY4 values have a precision of one ten-thousandth of a dollar. See AlsoREMAP="BO--Body"LINKEND="X27673"dbmny4sub
, LINKEND="X56924"dbmny4mul
, LINKEND="X63873"dbmny4divide
, LINKEND="X28528"dbmny4minus
, LINKEND="X74520"dbmny4add
, LINKEND="X27673"dbmny4sub
, LINKEND="X77367"dbmnymul
, LINKEND="X40627"dbmnydivide
, LINKEND="X23898"dbmnyminus
ID="IN4399488"dbmny4add
 ID="IN43991119"dbmny4cmpID="X44051"dbmny4cmp
Compare two DBMONEY4 values. FORMAT="LINESPECIFIC"int dbmny4cmp(dbproc, m1, m2)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"DBMONEY4     *m1;FORMAT="LINESPECIFIC"DBMONEY4     *m2;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and the server.   REMAP="UN--Under"This parameter may be NULL. The DBPROCESS is used as a parameter to an application's error handler.   It also contains information on what language to print error messages in.  If a DBPROCESS is not supplied, the  default national language is used. m1 - A pointer to a DBMONEY4 value. m2 - A pointer to a DBMONEY4 value. ReturnsREMAP="BO--Body"If m1 = m2, MOREINFO="NONE"dbmny4cmp returns 0.  REMAP="BO--Body"If m1 < m2, MOREINFO="NONE"dbmny4cmp returns -1.  REMAP="BO--Body"If m1 > m2, MOREINFO="NONE"dbmny4cmp returns 1. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbmny4cmp compares two DBMONEY4 values. The range of legal DBMONEY4 values is from -$214,748.3648 to $214,748.3647. DBMONEY4 values have a precision of one ten-thousandth of a dollar. See AlsoREMAP="BO--Body"LINKEND="X81878"dbmnycmp
ID="IN449881516"dbmny4cmp
 ID="IN4410851817"dbmny4copyID="X81375"dbmny4copy
Copy a DBMONEY4 value. FORMAT="LINESPECIFIC"RETCODE dbmny4copy(dbproc, src, dest)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"DBMONEY4      *src;FORMAT="LINESPECIFIC"DBMONEY4      *dest;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and the server.   REMAP="UN--Under"This parameter may be NULL. The DBPROCESS is used as a parameter to an application's error handler.   It also contains information on what language to print error messages in.  If a DBPROCESS is not supplied, the  default national language is used. src - A pointer to the source DBMONEY4 value. dest - A pointer to the destination DBMONEY4 variable. ReturnsREMAP="BO--Body"SUCCEED or FAIL. REMAP="BO--Body"MOREINFO="NONE"dbmny4copy returns FAIL if either src or dest is NULL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbmny4copy copies the src DBMONEY4 value  to the dest DBMONEY4 variable. The range of legal DBMONEY4 values is from -$214,748.3648  to $214,748.3647. DBMONEY4 values have a precision of one ten-thousandth of a dollar. See AlsoREMAP="BO--Body"LINKEND="X59968"dbmnycopy
, LINKEND="X23898"dbmnyminus
, LINKEND="X28528"dbmny4minus
ID="IN4510822224"dbmny4copy
 ID="IN4512792525"dbmny4divideID="X63873"dbmny4divide
Divide one DBMONEY4 value by another. FORMAT="LINESPECIFIC"RETCODE dbmny4divide(dbproc, m1, m2, quotient)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"DBMONEY4      *m1;FORMAT="LINESPECIFIC"DBMONEY4      *m2;FORMAT="LINESPECIFIC"DBMONEY4      *quotient;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and the server.   REMAP="UN--Under"This parameter may be NULL. The DBPROCESS is used as a parameter to an application's error handler.   It also contains information on what language to print error messages in.  If a DBPROCESS is not supplied, the  default national language is used. m1 - A pointer to the DBMONEY4 value serving as dividend. m2 - A pointer to the DBMONEY4 value serving as divisor. quotient - A pointer to a DBMONEY4 variable  to hold the result of the division. ReturnsREMAP="BO--Body"SUCCEED or FAIL. REMAP="BO--Body"MOREINFO="NONE"dbmny4divide returns FAIL in case of overflow or division by zero, or if m1, m2, or quotient is NULL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbmny4divide divides the m1 DBMONEY4 value  by the m2 DBMONEY4 value and places the result in *quotient. In case of overflow or division by zero, MOREINFO="NONE"dbmny4divide returns FAIL and sets *quotient to $0.0000. The range of legal DBMONEY4 values is from -$214,748.3648  to $214,748.3647. DBMONEY4 values have a precision of  one ten-thousandth of a dollar. See AlsoREMAP="BO--Body"LINKEND="X74520"dbmny4add
, LINKEND="X27673"dbmny4sub
, LINKEND="X56924"dbmny4mul
, LINKEND="X28528"dbmny4minus
, LINKEND="X93356"dbmnyadd
, LINKEND="X18692"dbmnysub
, LINKEND="X77367"dbmnymul
, LINKEND="X40627"dbmnydivide
, LINKEND="X23898"dbmnyminus
ID="IN4612762932"dbmny4divide
 ID="IN4611733233"dbmny4minusID="X28528"dbmny4minus
Negate a DBMONEY4 value. FORMAT="LINESPECIFIC"RETCODE dbmny4minus(dbproc, src, dest)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"DBMONEY4     *src;FORMAT="LINESPECIFIC"DBMONEY4     *dest;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and the server.   REMAP="UN--Under"This parameter may be NULL. The DBPROCESS is used as a parameter to an application's error handler.   It also contains information on what language to print error messages in.  If a DBPROCESS is not supplied, the  default national language is used. src - A pointer to a DBMONEY4 value. dest - A pointer to a DBMONEY4 variable to hold the result of the negation. ReturnsREMAP="BO--Body"SUCCEED or FAIL. REMAP="BO--Body"MOREINFO="NONE"dbmny4minus returns FAIL in case of overflow, or if src or dest is NULL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbmny4minus negates the src DBMONEY4 value  and places the result into *dest. In case of overflow, MOREINFO="NONE"dbmny4minus returns FAIL. *dest is undefined in this case. An attempt to negate the maximum negative DBMONEY4  value will result in overflow. The range of legal DBMONEY4 values is from -$214,748.3648  to $214,748.3647. DBMONEY4 values have a precision of  one ten-thousandth of a dollar. See AlsoREMAP="BO--Body"LINKEND="X23898"dbmnyminus
, LINKEND="X59968"dbmnycopy
, LINKEND="X81375"dbmny4copy
ID="IN4711703640"dbmny4minus
 ID="IN479673941"dbmny4mulID="X56924"dbmny4mul
Multiply two DBMONEY4 values. FORMAT="LINESPECIFIC"RETCODE dbmny4mul(dbproc, m1, m2, product)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"DBMONEY4     *m1;FORMAT="LINESPECIFIC"DBMONEY4     *m2;FORMAT="LINESPECIFIC"DBMONEY4     *product;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and the server.   REMAP="UN--Under"This parameter may be NULL. The DBPROCESS is used as a parameter to an application's error handler.   It also contains information on what language to print error messages in.  If a DBPROCESS is not supplied, the  default national language is used. m1 - A pointer to a DBMONEY4 value. m2 - A pointer to a DBMONEY4 value. product - A pointer to a DBMONEY4 variable to hold the result of the multiplication. ReturnsREMAP="BO--Body"SUCCEED or FAIL. REMAP="BO--Body"MOREINFO="NONE"dbmny4mul returns FAIL in case of overflow, or if m1, m2, or product is NULL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbmny4mul multiplies the m1 DBMONEY4 value by the m2 DBMONEY4 value and places the result in *product. In case of overflow, MOREINFO="NONE"dbmny4mul returns FAIL and sets *product to $0.0000. The range of legal DBMONEY4 values is from -$214,748.3648  to $214,748.3647. DBMONEY4 values have a precision of  one ten-thousandth of a dollar. See AlsoREMAP="BO--Body"LINKEND="X74520"dbmny4add
, LINKEND="X27673"dbmny4sub
, LINKEND="X63873"dbmny4divide
, LINKEND="X28528"dbmny4minus
, LINKEND="X93356"dbmnyadd
, LINKEND="X18692"dbmnysub
, LINKEND="X77367"dbmnymul
, LINKEND="X40627"dbmnydivide
, LINKEND="X23898"dbmnyminus
ID="IN489644348"dbmny4mul
 ID="IN489614649"dbmny4subID="X27673"dbmny4sub
Subtract one DBMONEY4 value from another. FORMAT="LINESPECIFIC"RETCODE dbmny4sub(dbproc, m1, m2, difference)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"DBMONEY4     *m1;FORMAT="LINESPECIFIC"DBMONEY4     *m2;FORMAT="LINESPECIFIC"DBMONEY4     *difference;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and the server.   REMAP="UN--Under"This parameter may be NULL. The DBPROCESS is used as a parameter to an application's error handler.   It also contains information on what language to print error messages in.  If a DBPROCESS is not supplied, the  default national language is used. m1 - A pointer to the DBMONEY4 to be subtracted from. m2 - A pointer to the DBMONEY4 value to subtract. difference - A pointer to a DBMONEY4 variable to hold the result of the subtraction. ReturnsREMAP="BO--Body"SUCCEED or FAIL. REMAP="BO--Body"MOREINFO="NONE"dbmny4sub returns FAIL in case of overflow, or if m1, m2, or difference is NULL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbmny4sub subtracts the m2 DBMONEY4 value from the m1 DBMONEY4 value and  places the result in *difference. In case of overflow, MOREINFO="NONE"dbmny4sub returns FAIL and sets *difference to $0.0000. The range of legal DBMONEY4 values is from -$214,748.3648  to $214,748.3647. DBMONEY4 values have a precision of  one ten-thousandth of a dollar. See AlsoREMAP="BO--Body"LINKEND="X27673"dbmny4sub
, LINKEND="X56924"dbmny4mul
, LINKEND="X63873"dbmny4divide
, LINKEND="X28528"dbmny4minus
, LINKEND="X74520"dbmny4add
, LINKEND="X18692"dbmnysub
, LINKEND="X77367"dbmnymul
, LINKEND="X40627"dbmnydivide
, LINKEND="X23898"dbmnyminus
ID="IN499585056"dbmny4sub
 ID="IN4910555357"dbmny4zeroID="X33621"dbmny4zero
Initialize a DBMONEY4 variable to $0.0000. FORMAT="LINESPECIFIC"RETCODE dbmny4zero(dbproc, mny4ptr)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"DBMONEY4     *mny4ptr;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and the server.   REMAP="UN--Under"This parameter may be NULL. The DBPROCESS is used as a parameter to an application's error handler.   It also contains information on what language to print error messages in.  If a DBPROCESS is not supplied, the  default national language is used. mny4ptr - A pointer to the DBMONEY4 value to initialize. ReturnsREMAP="BO--Body"SUCCEED or FAIL. REMAP="BO--Body"MOREINFO="NONE"dbmny4zero returns FAIL if mny4ptr is NULL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbmny4zero initializes a DBMONEY4 value to $0.0000. The range of legal DBMONEY4 values is from -$214,748.3648  to $214,748.3647. DBMONEY4 values have a precision of  one ten-thousandth of a dollar. See AlsoREMAP="BO--Body"LINKEND="X12037"dbmnyzero
ID="IN5010525764"dbmny4zero
 ID="IN508496065"dbmnyaddID="X93356"dbmnyadd
Add two DBMONEY values. FORMAT="LINESPECIFIC"RETCODE dbmnyadd(dbproc, m1, m2, sum)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"DBMONEY      *m1;FORMAT="LINESPECIFIC"DBMONEY      *m2;FORMAT="LINESPECIFIC"DBMONEY      *sum;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and the server.   REMAP="UN--Under"This parameter may be NULL. The DBPROCESS is used as a parameter to an application's error handler.   It also contains information on what language to print error messages in.  If a DBPROCESS is not supplied, the  default national language is used. m1 - A pointer to a DBMONEY value. m2 - A pointer to a DBMONEY value. sum - A pointer to a DBMONEY variable to hold the result of the addition. ReturnsREMAP="BO--Body"SUCCEED or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbmnyadd adds the m1 and m2 DBMONEY values  and places the result in *sum. In case of overflow, MOREINFO="NONE"dbmnyadd returns FAIL and sets *sum to $0.0000. The range of legal DBMONEY values is between  +/-$922,337,203,685,477.5807. DBMONEY values have a precision of one ten-thousandth of  a dollar. REMAP="BO--Body"MOREINFO="NONE"dbmnyadd returns FAIL in case of overflow, or if m1, m2, or sum is NULL. See AlsoREMAP="BO--Body"LINKEND="X18692"dbmnysub
, LINKEND="X77367"dbmnymul
, LINKEND="X40627"dbmnydivide
, LINKEND="X23898"dbmnyminus
, LINKEND="X74520"dbmny4add
, LINKEND="X27673"dbmny4sub
, LINKEND="X56924"dbmny4mul
, LINKEND="X63873"dbmny4divide
, LINKEND="X28528"dbmny4minus
ID="IN518466472"dbmnyadd
 ID="IN518436773"dbmnycmpID="X81878"dbmnycmp
Compare two DBMONEY values. FORMAT="LINESPECIFIC"int dbmnycmp(dbproc, m1, m2)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"DBMONEY      *m1;FORMAT="LINESPECIFIC"DBMONEY      *m2;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and the server.   REMAP="UN--Under"This parameter may be NULL. The DBPROCESS is used as a parameter to an application's error handler.   It also contains information on what language to print error messages in.  If a DBPROCESS is not supplied, the  default national language is used. m1 - A pointer to a DBMONEY value. m2 - A pointer to a DBMONEY value. ReturnsREMAP="BO--Body"If m1 = m2 MOREINFO="NONE"dbmnycmp returns 0. REMAP="BO--Body"If m1 < m2 MOREINFO="NONE"dbmnycmp returns -1. REMAP="BO--Body"If m1 > m2 MOREINFO="NONE"dbmnycmp returns 1. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbmnycmp compares two DBMONEY values. The range of legal DBMONEY values is between  +/-$922,337,203,685,477.5807. DBMONEY values have a precision of one ten-thousandth of  a dollar. See AlsoREMAP="BO--Body"LINKEND="X44051"dbmny4cmp
ID="IN528407180"dbmnycmp
 ID="IN529377481"dbmnycopyID="X59968"dbmnycopy
Copy a DBMONEY value. FORMAT="LINESPECIFIC"RETCODE dbmnycopy(dbproc, src, dest)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"DBMONEY      *src;FORMAT="LINESPECIFIC"DBMONEY      *dest;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and the server.   REMAP="UN--Under"This parameter may be NULL. The DBPROCESS is used as a parameter to an application's error handler.   It also contains information on what language to print error messages in.  If a DBPROCESS is not supplied, the  default national language is used. src - A pointer to the source DBMONEY value. dest - A pointer to the destination DBMONEY variable. ReturnsREMAP="BO--Body"SUCCEED or FAIL. REMAP="BO--Body"MOREINFO="NONE"dbmnycopy returns FAIL if either src or dest  is NULL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbmnycopy copies the src DBMONEY value to the dest DBMONEY value. The range of legal DBMONEY values is between  +/-$922,337,203,685,477.5807. DBMONEY values have a precision of one ten-thousandth of  a dollar. See AlsoREMAP="BO--Body"LINKEND="X59968"dbmnycopy
, LINKEND="X23898"dbmnyminus
, LINKEND="X28528"dbmny4minus
ID="IN539347888"dbmnycopy
 ID="IN538318189"dbmnydecID="X43308"dbmnydec
Decrement a DBMONEY value by one ten-thousandth of a dollar. FORMAT="LINESPECIFIC"RETCODE dbmnydec(dbproc, mnyptr)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"DBMONEY      *mnyptr;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and the server.   REMAP="UN--Under"This parameter may be NULL. The DBPROCESS is used as a parameter to an application's error handler.   It also contains information on what language to print error messages in.  If a DBPROCESS is not supplied, the  default national language is used. mnyptr - A pointer to the DBMONEY value to decrement. ReturnsREMAP="BO--Body"SUCCEED or FAIL. REMAP="BO--Body"MOREINFO="NONE"dbmnydec returns FAIL in case of overflow or  if mnyptr is NULL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbmnydec decrements a DBMONEY value by  one ten-thousandth of a dollar. An attempt to decrement the maximum negative DBMONEY value  will result in overflow.   In case of overflow, MOREINFO="NONE"dbmnydec returns FAIL.  *mnyptr is undefined in this case. The range of legal DBMONEY values is between  +/-$922,337,203,685,477.5807. DBMONEY values have a precision of one ten-thousandth of  a dollar. See AlsoREMAP="BO--Body"LINKEND="X23322"dbmnyinc
, LINKEND="X97573"dbmnymaxneg
ID="IN548288596"dbmnydec
 ID="IN5411258897"dbmnydivideID="X40627"dbmnydivide
Divide one DBMONEY value by another. FORMAT="LINESPECIFIC"RETCODE dbmnydivide(dbproc, m1, m2, quotient)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"DBMONEY      *m1;FORMAT="LINESPECIFIC"DBMONEY      *m2;FORMAT="LINESPECIFIC"DBMONEY      *quotient;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and the server.   REMAP="UN--Under"This parameter may be NULL. The DBPROCESS is used as a parameter to an application's error handler.   It also contains information on what language to print error messages in.  If a DBPROCESS is not supplied, the  default national language is used. m1 - A pointer to the DBMONEY value serving as dividend. m2 - A pointer to the DBMONEY value serving as divisor. quotient - A pointer to a DBMONEY variable to hold the result of the division. ReturnsREMAP="BO--Body"SUCCEED or FAIL. REMAP="BO--Body"MOREINFO="NONE"dbmnydivide returns FAIL in case of overflow or division by zero, or if m1, m2, or quotient is NULL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbmnydivide divides the m1 DBMONEY value by the m2 DBMONEY value and places the result in *quotient. In case of overflow or division by zero, MOREINFO="NONE"dbmnydivide returns FAIL and sets *quotient to $0.0000. The range of legal DBMONEY values is between  +/-$922,337,203,685,477.5807. DBMONEY values have a precision of one ten-thousandth of  a dollar. See AlsoREMAP="BO--Body"LINKEND="X93356"dbmnyadd
, LINKEND="X18692"dbmnysub
, LINKEND="X77367"dbmnymul
, LINKEND="X23898"dbmnyminus
, LINKEND="X74520"dbmny4add
, LINKEND="X27673"dbmny4sub
, LINKEND="X56924"dbmny4mul
, LINKEND="X63873"dbmny4divide
, LINKEND="X28528"dbmny4minus
ID="IN55112292104"dbmnydivide
 ID="IN5591995105"dbmnydownID="X73831"dbmnydown
Divide a DBMONEY value by a positive integer. FORMAT="LINESPECIFIC"RETCODE dbmnydown(dbproc, mnyptr, divisor, remainder)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"DBMONEY      *mnyptr;FORMAT="LINESPECIFIC"int          divisor;FORMAT="LINESPECIFIC"int          *remainder;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and the server.   REMAP="UN--Under"This parameter may be NULL. The DBPROCESS is used as a parameter to an application's error handler.   It also contains information on what language to print error messages in.  If a DBPROCESS is not supplied, the  default national language is used. mnyptr - A pointer to the DBMONEY value to divide. *mnyptr will also contain the result of the division. divisor - The integer by which *mnyptr will be divided.  divisor must be positive, and must be less than or  equal to 65535. remainder - A pointer to an integer variable to hold the remainder from the division, in ten-thousandths of a dollar. If remainder is passed as NULL, no remainder is returned. ReturnsREMAP="BO--Body"SUCCEED or FAIL. REMAP="BO--Body"MOREINFO="NONE"dbmnydown returns FAIL if mnyptr is NULL, or if divisor is not between 1 and 65535. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbmnydown divides a DBMONEY value by a short integer and places the result back in the original DBMONEY variable. MOREINFO="NONE"dbmnydown places the remainder of the division into *remainder.  *remainder is an integer representing the number of ten-thousandths of a dollar left after the division. divisor must be greater than or equal to one and less than or equal to 65535. The range of legal DBMONEY values is between  +/-$922,337,203,685,477.5807. DBMONEY values have a precision of one ten-thousandth of  a dollar. See AlsoREMAP="BO--Body"LINKEND="X36067"dbmnyscale
, LINKEND="X40627"dbmnydivide
, LINKEND="X63873"dbmny4divide
ID="IN5691699112"dbmnydown
 ID="IN56813102113"dbmnyincID="X23322"dbmnyinc
Increment a DBMONEY value by one ten-thousandth of a dollar. FORMAT="LINESPECIFIC"RETCODE dbmnyinc(dbproc, mnyptr)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"DBMONEY      *mnyptr;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and the server.   REMAP="UN--Under"This parameter may be NULL. The DBPROCESS is used as a parameter to an application's error handler.   It also contains information on what language to print error messages in.  If a DBPROCESS is not supplied, the  default national language is used. mnyptr - A pointer to the DBMONEY value to increment. ReturnsREMAP="BO--Body"SUCCEED or FAIL. REMAP="BO--Body"MOREINFO="NONE"dbmnyinc returns FAIL in case of overflow  or if mnyptr is NULL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbmnyinc increments a DBMONEY value by one  ten-thousandth of a dollar. An attempt to increment the maximum positive  DBMONEY value will result in overflow.   In case of overflow MOREINFO="NONE"dbmnyinc returns FAIL. *mnyptr is undefined in this case. The range of legal DBMONEY values is between  +/-$922,337,203,685,477.5807. DBMONEY values have a precision of one ten-thousandth of  a dollar. See AlsoREMAP="BO--Body"LINKEND="X43308"dbmnydec
, LINKEND="X90636"dbmnymaxpos
ID="IN57810106120"dbmnyinc
 ID="IN5797109121"dbmnyinitID="X86423"dbmnyinit
Prepare a DBMONEY value for calls to MOREINFO="NONE"dbmnyndigit. FORMAT="LINESPECIFIC"RETCODE dbmnyinit(dbproc, mnyptr, trim, negative)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"DBMONEY      *mnyptr;FORMAT="LINESPECIFIC"int          trim;FORMAT="LINESPECIFIC"DBBOOL       *negative;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and the server.   REMAP="UN--Under"This parameter may be NULL. The DBPROCESS is used as a parameter to an application's error handler.   It also contains information on what language to print error messages in.  If a DBPROCESS is not supplied, the  default national language is used. mnyptr - A pointer to the DBMONEY value to be initialized.  MOREINFO="NONE"dbmnyinit changes the value of *mnyptr. trim - The number of digits to trim from *mnyptr. MOREINFO="NONE"dbmnyinit removes digits from *mnyptr by dividing it by a power of ten.  The value of trim determines what power of ten is used.  trim cannot be less than 0. negative - A pointer to a DBBOOL variable.  If *mnyptr is negative, MOREINFO="NONE"dbmnyinit makes it positive and sets *negative to TRUE. ReturnsREMAP="BO--Body"SUCCEED or FAIL. REMAP="BO--Body"MOREINFO="NONE"dbmnyinit returns FAIL if mnyptr is NULL, negative is NULL, or trim is less than 0. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbmnyinit initializes a DBMONEY value for conversion to character.  It eliminates unwanted precision and converts negative values to positive. MOREINFO="NONE"dbmnyinit eliminates digits from a DBMONEY value  by dividing by a power of 10. The integer trim determines what power of 10 is used.   MOREINFO="NONE"dbmnyinit modifies *mnyptr, replacing the original value with the trimmed value. If *mnyptr is negative, MOREINFO="NONE"dbmnyinit makes it positive and sets *negative to TRUE. MOREINFO="NONE"dbmnyinit and MOREINFO="NONE"dbmnyndigit are useful  for writing a custom DBMONEY-to-DBCHAR conversion routine.   Such a custom routine might be useful if the accuracy provided by MOREINFO="NONE"dbconvert's DBMONEY-to-DBCHAR conversion (hundredths of a dollar) is not adequate. Also, MOREINFO="NONE"dbconvert does not build a character string  containing commas. MOREINFO="NONE"dbmnyndigit returns the rightmost digit of a DBMONEY value as a DBCHAR.   To get all the digits of a DBMONEY value, call MOREINFO="NONE"dbmnyndigit repeatedly. See the MOREINFO="NONE"dbmnyndigit manual page for more details. MOREINFO="NONE"dbmnyinit is almost always used in conjunction with  MOREINFO="NONE"dbmnyndigit.  Used alone, MOREINFO="NONE"dbmnyinit can force negative DBMONEY values positive and divide DBMONEY values by a power of ten, but the real purpose of MOREINFO="NONE"dbmnyinit is to prepare a DBMONEY value for calls to MOREINFO="NONE"dbmnyndigit. The range of legal DBMONEY values is between  +/-$922,337,203,685,477.5807. DBMONEY values have a precision of one ten-thousandth of  a dollar. The MOREINFO="NONE"dbmnyndigit manual page contains an example which demonstrates the use of MOREINFO="NONE"dbmnyinit. See AlsoREMAP="BO--Body"LINKEND="X95988"dbmnyndigit
, LINKEND="X76814"dbconvert
ID="IN5894113128"dbmnyinit
 ID="IN58111116129"dbmnymaxnegID="X97573"dbmnymaxneg
Return the maximum negative DBMONEY value supported. FORMAT="LINESPECIFIC"RETCODE dbmnymaxneg(dbproc,dest)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"DBMONEY      *dest;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and the server.   REMAP="UN--Under"This parameter may be NULL. The DBPROCESS is used as a parameter to an application's error handler.   It also contains information on what language to print error messages in.  If a DBPROCESS is not supplied, the  default national language is used. dest - A pointer to a DBMONEY variable. ReturnsREMAP="BO--Body"SUCCEED or FAIL. REMAP="BO--Body"MOREINFO="NONE"dbmnymaxneg returns FAIL if dest is NULL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbmnymaxneg fills *dest with the maximum negative DBMONEY value supported. The range of legal DBMONEY values is between  +/-$922,337,203,685,477.5807. DBMONEY values have a precision of one ten-thousandth of  a dollar. See AlsoREMAP="BO--Body"LINKEND="X90636"dbmnymaxpos
ID="IN5911-2120136"dbmnymaxneg
 ID="IN5911-5123137"dbmnymaxposID="X90636"dbmnymaxpos
Returns the maximum positive DBMONEY value supported. FORMAT="LINESPECIFIC"RETCODE dbmnymaxpos(dbproc, dest)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"DBMONEY      *dest;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and the server.   REMAP="UN--Under"This parameter may be NULL. The DBPROCESS is used as a parameter to an application's error handler.   It also contains information on what language to print error messages in.  If a DBPROCESS is not supplied, the  default national language is used. dest - A pointer to a DBMONEY variable. ReturnsREMAP="BO--Body"SUCCEED or FAIL. REMAP="BO--Body"MOREINFO="NONE"dbmnymaxpos returns FAIL if dest is NULL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbmnymaxpos fills *dest with the maximum positive DBMONEY value supported. The range of legal DBMONEY values is between  +/-$922,337,203,685,477.5807. DBMONEY values have a precision of one ten-thousandth of  a dollar. See AlsoREMAP="BO--Body"LINKEND="X97573"dbmnymaxneg
ID="IN6011-8127144"dbmnymaxpos
 ID="IN6010-11130145"dbmnyminusID="X23898"dbmnyminus
Negate a DBMONEY value. FORMAT="LINESPECIFIC"RETCODE dbmnyminus(dbproc, src, dest)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"DBMONEY      *src;FORMAT="LINESPECIFIC"DBMONEY      *dest;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and the server.   REMAP="UN--Under"This parameter may be NULL. The DBPROCESS is used as a parameter to an application's error handler.   It also contains information on what language to print error messages in.  If a DBPROCESS is not supplied, the  default national language is used. src - A pointer to a DBMONEY value. dest - A pointer to a DBMONEY variable to hold the result of the negation. ReturnsREMAP="BO--Body"SUCCEED or FAIL. REMAP="BO--Body"MOREINFO="NONE"dbmnyminus returns FAIL in case of overflow, or if src or dest is NULL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbmnyminus negates the src DBMONEY value  and places the result into *dest. In case of overflow, MOREINFO="NONE"dbmnyminus returns FAIL.  *dest is undefined in this case.  An attempt to negate the maximum negative DBMONEY value will result in overflow. The range of legal DBMONEY values is between  +/-$922,337,203,685,477.5807. DBMONEY values have a precision of one ten-thousandth of  a dollar. See AlsoREMAP="BO--Body"LINKEND="X28528"dbmny4minus
, LINKEND="X59968"dbmnycopy
, LINKEND="X81375"dbmny4copy
ID="IN6110-14134152"dbmnyminus
 ID="IN618-17137153"dbmnymulID="X77367"dbmnymul
Multiply two DBMONEY values. FORMAT="LINESPECIFIC"RETCODE dbmnymul(dbproc, m1, m2, product)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"DBMONEY      *m1;FORMAT="LINESPECIFIC"DBMONEY      *m2;FORMAT="LINESPECIFIC"DBMONEY      *product;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and the server.   REMAP="UN--Under"This parameter may be NULL. The DBPROCESS is used as a parameter to an application's error handler.   It also contains information on what language to print error messages in.  If a DBPROCESS is not supplied, the  default national language is used. m1 - A pointer to a DBMONEY value. m2 - A pointer to a DBMONEY value. product - A pointer to a DBMONEY variable to hold the result of the multiplication. ReturnsREMAP="BO--Body"SUCCEED or FAIL. REMAP="BO--Body"MOREINFO="NONE"dbmnymul returns FAIL in case of overflow, or if m1, m2, or product is NULL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbmnymul multiplies the m1 DBMONEY value by the m2 DBMONEY value and places the result in *product. In case of overflow, MOREINFO="NONE"dbmnymul returns FAIL and sets *product to $0.0000. The range of legal DBMONEY values is between  +/-$922,337,203,685,477.5807. DBMONEY values have a precision of one ten-thousandth of  a dollar. See AlsoREMAP="BO--Body"LINKEND="X93356"dbmnyadd
, LINKEND="X18692"dbmnysub
, LINKEND="X40627"dbmnydivide
, LINKEND="X23898"dbmnyminus
, LINKEND="X74520"dbmny4add
, LINKEND="X27673"dbmny4sub
, LINKEND="X56924"dbmny4mul
, LINKEND="X63873"dbmny4divide
, LINKEND="X28528"dbmny4minus
ID="IN628-20141160"dbmnymul
 ID="IN6211-23144161"dbmnyndigitID="X95988"dbmnyndigit
Return the rightmost digit of a DBMONEY value as a DBCHAR. FORMAT="LINESPECIFIC"RETCODE dbmnyndigit(dbproc, mnyptr, value, zero)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"DBMONEY      *mnyptr;FORMAT="LINESPECIFIC"DBCHAR       *value;FORMAT="LINESPECIFIC"DBBOOL       *zero;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and the server.   REMAP="UN--Under"This parameter may be NULL. The DBPROCESS is used as a parameter to an application's error handler.   It also contains information on what language to print error messages in.  If a DBPROCESS is not supplied, the  default national language is used. mnyptr - A pointer to a DBMONEY value.  Each call to MOREINFO="NONE"dbmnyndigit divides this value by 10 and places the result back into *mnyptr. value - A pointer to a DBCHAR variable  to fill with the character representation of the  rightmost digit of the DBMONEY value. zero - A pointer to a DBBOOL variable.   Each call to MOREINFO="NONE"dbmnyndigit divides *mnyptr by 10 and puts the character representation of the remainder of the division in *value. If the result of the division is  $0.0000, MOREINFO="NONE"dbmnyndigit sets *zero to TRUE. Otherwise, *zero is set to FALSE.   If zero is passed as NULL, this information is  not returned. ReturnsREMAP="BO--Body"SUCCEED or FAIL. REMAP="BO--Body"MOREINFO="NONE"dbmnyndigit returns FAIL if mnyptr or value is NULL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbmnyndigit returns the rightmost digit of a DBMONEY value as a DBCHAR. MOREINFO="NONE"dbmnyndigit divides a DBMONEY value by 10.  It places the character representation of the remainder of the division in *value, and replaces *mnyptr with the result of the division.  If the result of the division is $0.0000, MOREINFO="NONE"dbmnyndigit sets *zero to true. To get all the digits of a DBMONEY value, call MOREINFO="NONE"dbmnydigit repeatedly, until *zero is TRUE. MOREINFO="NONE"dbmnyinit and MOREINFO="NONE"dbmnyndigit are useful  for writing a custom DBMONEY-to-DBCHAR conversion routine.   Such a custom routine might be useful if the accuracy provided by MOREINFO="NONE"dbconvert's DBMONEY-to-DBCHAR conversion (hundredths of a dollar) is not adequate.   Also MOREINFO="NONE"dbconvert does not build a character string containing commas. MOREINFO="NONE"dbmnyinit initializes a DBMONEY value for conversion to  character.  It eliminates unwanted precision and converts negative values to positive.  For more information, see the MOREINFO="NONE"dbmnyinit manual page. The range of legal DBMONEY values is between  +/-$922,337,203,685,477.5807. DBMONEY values have a precision of one ten-thousandth of  a dollar. This code fragment demonstrates the use of MOREINFO="NONE"dbmnyndigit and MOREINFO="NONE"dbmnyinit: REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"/* ** This example demonstrates dbmnyinit() and** dbmnyndigit().  It is a conversion routine which** converts a DBMONEY value  to a character string.** The conversion provided by this routine is unlike** the conversion provided by dbconvert() in that the** resulting character string includes commas. This** conversion provides precision of two digits after** the decimal point. ** ** For simplicity, the example assumes that all** routines succeed and all parameters passed to it ** are valid. */ 
 #define PRECISION       2  RETCODE     new_mnytochar(mnyptr, buf_ptr) DBMONEY     *mnyptr; char        *buf_ptr; {      DBMONEY    local_mny;      DBBOOL     negative;      int        bytes_written;      DBCHAR     value;      DBBOOL     zero;      int        ret;      char       temp_buf[32]; 
      /*      ** Since dbmnyinit() and dbmnyndigit() modify the     ** DBMONEY value passed to it, and since we do      ** not want to modify the DBMONEY value passed      ** to us by the user we need to make a local copy.     */      ret = dbmnycopy((DBPROCESS *)NULL, mnyptr,          &local_mny);      /* The value of 'ret' should be checked */ 
      /*      ** Next we need to call dbmnyinit().     **     ** dbmnyinit() eliminates any unwanted precision      ** from the DBMONEY value.  DBMONEY values are      ** stored with accuracy to four digits after the      ** decimal point. For this conversion routine we      ** only want accuracy to two digits after the     ** decimal.     **      ** Passing a value of 2 for the second parameter     ** eliminates those two digits of precision we do      ** not care about.      **      ** dbmnyinit() also turns negative DBMONEY values      ** into positive DBMONEY values. The value of      ** negative is set to TRUE if dbmnyinit() turns a      ** negative DBMONEY value into a positive DBMONEY     ** value.      **      ** NOTE: dbmnyinit() eliminates unwanted by     ** precision by dividing DBMONEY values by a      ** power of ten. In this conversion routine it     ** divides by 100.  If we pass dbmnyinit() a     ** DBMONEY value of $1534.1277 the resulting     ** DBMONEY value is $15.3413.        */      negative = FALSE;      ret = dbmnyinit((DBPROCESS *)NULL, &local_mny,          4 - PRECISION, &negative);      /* The value of 'ret' should be checked */ 
      /*      ** dbmnyndigit() extracts the rightmost digit out      ** of the DBMONEY value, converts it to a      ** character, places the character into the      ** variable "value", and then divides the DBMONEY     ** value by 10. dbmnyndigit() sets 'zero' to TRUE     ** if the result of the division is $0.0000.     **     ** By calling dbmnyndigit() until 'zero' is set to      ** TRUE we will be returned all the digits (from      ** right to left) of the DBMONEY value.      */      zero = FALSE;      bytes_written = 0;      while( zero == FALSE )      {          ret = dbmnyndigit((DBPROCESS *)NULL,              &local_mny, &value, &zero);          /* The value of 'ret' should be checked. */ 
          /*          ** As we are getting the digits, we want to          ** place the decimal point and commas in the          ** proper positions ...          */          temp_buf[bytes_written++] = value; 
          /*          ** If zero == TRUE we got all the digits. We          ** do not want to call         ** check_comma_and_decimal() since we might          ** put a comma before the leftmost digit.          */           if( zero == FALSE )          {               /*               ** As we are getting the digits, we want               ** to place the decimal point and commas               ** in the proper positions ...               */               check_comma_and_decimal(temp_buf,                   &bytes_written);          }      } 
      /*      ** If we haven't written PRECISION bytes into the      ** buffer yet, pad with zeros, write the decimal      ** point to the buffer, and write a zero after      ** the decimal point.      */      pad_with_zeros(temp_buf, &bytes_written);
      /*      ** We've written the money value into the buffer      ** backwards. Now we have to write it the right     ** way.      */      reverse_money(buf_ptr, temp_buf, bytes_written,          negative); 
      return(SUCCEED);  }  void     check_comma_and_decimal(temp_buf,              bytes_written) char     *temp_buf; int      *bytes_written; {
      static     int     comma = 0;      static     DBBOOL  after_decimal = FALSE;       if( after_decimal )      {          /*          ** When comma is 3 it is time to write a          ** comma. We do not care about commas until          ** after we've written the decimal point.          */          comma++;      } 
      /*      ** After we've written PRECISION bytes into the      ** buffer, it's time to write the decimal point.      */      if( *bytes_written == PRECISION )      {          temp_buf[(*bytes_written)++] = '.';          after_decimal = TRUE;      }       /*      ** When (comma == 3) that means we've written three      ** digits and it's time to put a comma into the     ** buffer.      */      if( comma == 3 )      {           temp_buf[(*bytes_written)++] = ',';            comma = 0;       /* clear comma */      } }
 void    pad_with_zeros(temp_buf, bytes_written) char    *temp_buf; int     *bytes_written; {       /* If we haven't written PRECISION bytes into the      ** buffer yet, pad with zeros, write the decimal     ** point to the buffer, and write a zero after the      ** decimal point.      */      while( *bytes_written < PRECISION )      {          temp_buf[(*bytes_written)++] = '0';      }       if( *bytes_written == PRECISION )      {          temp_buf[(*bytes_written)++] = '.';          temp_buf[(*bytes_written)++] = '0';      } } void     reverse_money(char_buf, temp_buf,              bytes_written, negative) char     *char_buf; char     *temp_buf; int      bytes_written; DBBOOL   negative; {      int       i;      /*      ** We've written the money value into the buffer      ** backwards. Now we have to write it the right      ** way. First check to see if we need to write a      ** negative sign, then write the dollar sign,      ** finally write the money value.      */      i = 0;      if( negative == TRUE )      {          char_buf[i++] = '-';      } REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"     char_buf[i++] = '$';      while( bytes_written-- )      {          char_buf[i++] = temp_buf[bytes_written];      }      /* Append null-terminator: */      char_buf[i] = '\0'; } See AlsoREMAP="BO--Body"LINKEND="X86423"dbmnyinit
, LINKEND="X76814"dbconvert
ID="IN6311-26148168"dbmnyndigit
 ID="IN6310-29151169"dbmnyscaleID="X36067"dbmnyscale
Multiply a DBMONEY value by a positive integer and add a specified amount. FORMAT="LINESPECIFIC"RETCODE dbmnyscale(dbproc, mnyptr, multiplier, addend)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS   *dbproc;FORMAT="LINESPECIFIC"DBMONEY     *mnyptr;FORMAT="LINESPECIFIC"int         multiplier;FORMAT="LINESPECIFIC"int         addend;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and the server.   REMAP="UN--Under"This parameter may be NULL. The DBPROCESS is used as a parameter to an application's error handler.   It also contains information on what language to print error messages in.  If a DBPROCESS is not supplied, the  default national language is used. mnyptr - A pointer to the DBMONEY value to multiply.   *mnyptr will also contain the result of the MOREINFO="NONE"dbmnyscale operation. multiplier - The integer by which *mnyptr will be multiplied. multiplier must be positive, and must be less than or  equal to 65535. addend - An integer representing the number of ten-thousandths of a dollar to add to *mnyptr after the multiplication. ReturnsREMAP="BO--Body"SUCCEED or FAIL. REMAP="BO--Body"MOREINFO="NONE"dbmnyscale returns FAIL if mnyptr is NULL, if overflow occurs, or if multiplier is not between 1 and 65535. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbmnyscale multiplies a DBMONEY value by a short integer, adds addend ten-thousandths of a dollar, and places the  result back in the original DBMONEY variable. multiplier must be greater than or equal to one and less than or equal to 65535. In case of overflow, MOREINFO="NONE"dbmnyscale returns FAIL. *mnyptr is undefined in this case. The range of legal DBMONEY values is between  +/-$922,337,203,685,477.5807. DBMONEY values have a precision of one ten-thousandth of  a dollar. See AlsoREMAP="BO--Body"LINKEND="X73831"dbmnydown
, LINKEND="X77367"dbmnymul
, LINKEND="X56924"dbmny4mul
ID="IN6410-32155176"dbmnyscale
 ID="IN648-35158177"dbmnysubID="X18692"dbmnysub
Subtract one DBMONEY value from another. FORMAT="LINESPECIFIC"RETCODE dbmnysub(dbproc, m1, m2, difference)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"DBMONEY       *m1;FORMAT="LINESPECIFIC"DBMONEY       *m2;FORMAT="LINESPECIFIC"DBMONEY       *difference;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and the server.   REMAP="UN--Under"This parameter may be NULL. The DBPROCESS is used as a parameter to an application's error handler.   It also contains information on what language to print error messages in.  If a DBPROCESS is not supplied, the  default national language is used. m1 - A pointer to the DBMONEY value to be subtracted from. m2 - A pointer to the DBMONEY value to subtract. difference - A pointer to a DBMONEY variable to hold the result of the subtraction. ReturnsREMAP="BO--Body"SUCCEED or FAIL. REMAP="BO--Body"MOREINFO="NONE"dbmnysub returns FAIL in case of overflow, or if m1, m2, or difference is NULL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbmnysub subtracts the m2 DBMONEY value from the m1 DBMONEY value and places the result in *difference. In case of overflow, MOREINFO="NONE"dbmnysub returns FAIL and sets difference to $0.0000. The range of legal DBMONEY values is between  +/-$922,337,203,685,477.5807. DBMONEY values have a precision of one ten-thousandth of  a dollar. See AlsoREMAP="BO--Body"LINKEND="X93356"dbmnyadd
, LINKEND="X77367"dbmnymul
, LINKEND="X40627"dbmnydivide
, LINKEND="X23898"dbmnyminus
, LINKEND="X74520"dbmny4add
, LINKEND="X27673"dbmny4sub
, LINKEND="X56924"dbmny4mul
, LINKEND="X63873"dbmny4divide
, LINKEND="X28528"dbmny4minus
ID="IN658-38162184"dbmnysub
 ID="IN659-41165185"dbmnyzeroID="X12037"dbmnyzero
Initialize a DBMONEY value to $0.0000. FORMAT="LINESPECIFIC"RETCODE dbmnyzero(dbproc, mnyptr)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS  *dbproc;FORMAT="LINESPECIFIC"DBMONEY    *mnyptr;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and the server.   REMAP="UN--Under"This parameter may be NULL. The DBPROCESS is used as a parameter to an application's error handler.   It also contains information on what language to print error messages in.  If a DBPROCESS is not supplied, the  default national language is used. mnyptr - A pointer to the DBMONEY value to initialize. ReturnsREMAP="BO--Body"SUCCEED or FAIL. REMAP="BO--Body"MOREINFO="NONE"dbmnyzero returns FAIL if mnyptr is NULL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbmnyzero initializes a DBMONEY value to $0.0000. The range of legal DBMONEY values is between  +/-$922,337,203,685,477.5807. DBMONEY values have a precision of one ten-thousandth of  a dollar. See AlsoREMAP="BO--Body"LINKEND="X33621"dbmny4zero
ID="IN669-44169192"dbmnyzero
 ID="IN6611-47172193"dbmonthnameID="X56030"dbmonthnameID="IN675-47173195"Datesdetermining month name in specified language
ID="IN676-47173196"Monthsdetermining name in specified language
Determine the name of a specified month in a specified language. FORMAT="LINESPECIFIC"char *dbmonthname(dbproc, language, monthnum,                  shortform)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"char          *language;FORMAT="LINESPECIFIC"int           monthnum;FORMAT="LINESPECIFIC"DBBOOL        shortform;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. language - The name of the desired language. monthnum - The number of the desired month. Month numbers range from 1 (January) to 12 (December). shortform - A Boolean value indicating whether the long or short form of the month name is desired. If shortform is TRUE, MOREINFO="NONE"dbmonthname returns the short form of the month name; if shortform is FALSE, MOREINFO="NONE"dbmonthname returns the full month name. For example, if the month name desired is the U.S. English short form for January, "Jan" is returned. REMAP="UN--Under"Short forms of month names are defined in localization files on a per-localization-file basis. ReturnsREMAP="BO--Body"The name of the specified month on success; a NULL pointer on error. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbmonthname returns the name of the specified month in the specified language. If no language is specified (language is NULL), dbproc's current language is used. If both language and dbproc are NULL, DB-Library's default language (if any) is used. The following code fragment illustrates the use of MOREINFO="NONE"dbmonthname: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"for (monthnum = 1; monthnum <= 12; monthnum++)    printf("Month %d: %s\n", monthnum,        dbmonthname((DBPROCESS *)NULL,             (char *)NULL,          monthnum, TRUE),         dbmonthname((DBPROCESS *)NULL,             (char *)NULL,          monthnum, FALSE)); See AlsoREMAP="BO--Body"LINKEND="X53831"db12hour
, LINKEND="X53486"dbdateorder
, LINKEND="X83105"dbdayname
, LINKEND="X52068"DBSETLNATLANG
, LINKEND="X97776"dbsetopt
ID="IN6711-50176202"dbmonthname
 ID="X78556"DBMORECMDSID="IN6810-53180203"DBMORECMDS
ID="IN688-53180205"Commandsdetermining whether more to process
ID="IN6815-53180206"Command batchesdetermining whether more results to process
Indicate whether there are more commands to be processed. FORMAT="LINESPECIFIC"RETCODE DBMORECMDS(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. ReturnsREMAP="BO--Body"SUCCEED or FAIL, indicating whether there are more results from the command batch. CommentsMARK="BULL" REMAP="BU--Bullet"The application can use this macro to determine whether there are more results to process. MOREINFO="NONE"DBMORECMDS can be called after MOREINFO="NONE"dbnextrow returns NO_MORE_ROWS. If you know that the current command is returning no rows, you can call MOREINFO="NONE"DBMORECMDS immediately after MOREINFO="NONE"dbresults. Applications rarely need this routine, because they can simply call MOREINFO="NONE"dbresults until it returns NO_MORE_RESULTS. See AlsoREMAP="BO--Body"LINKEND="X17006"DBCMDROW
, LINKEND="X35104"dbresults
, LINKEND="X87634"DBROWS
, LINKEND="X42749"DBROWTYPE
ID="IN6810-56183212"DBMORECMDS
 ID="IN6810-59186213"dbmoretextID="X96538"dbmoretextID="IN6911-59187215"Text valuesupdating
ID="IN6912-59187216"Image valuesupdating
ID="IN696-59187217"Serversending text/image values to
Send part of a text or image value to the server. FORMAT="LINESPECIFIC"RETCODE dbmoretext(dbproc, size, text)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"DBINT        size;FORMAT="LINESPECIFIC"BYTE         *text;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. size - The size, in bytes, of this particular part of the text or image value being sent to the server. It is an error to send more text or image bytes to the server than were specified in the call to MOREINFO="NONE"dbwritetext. text - A pointer to the text or image portion to be written. ReturnsREMAP="BO--Body"SUCCEED or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"This routine is used in conjunction with MOREINFO="NONE"dbwritetext to send a large SYBTEXT or SYBIMAGE value to the server in the form of a number of smaller chunks. This is particularly useful with operating systems unable to allocate extremely long data buffers. ID="IN6918-59187222"Updating databasesUpdating databasesand text/image datatext/image data
ID="IN699-59187223"DatabasesDatabasesupdating:and text/image dataupdating:text/image dataMOREINFO="NONE"dbmoretext and MOREINFO="NONE"dbwritetext are used in updates only, and serve to replace the Transact-SQL MOREINFO="NONE"update statement. MOREINFO="NONE"dbsqlok and MOREINFO="NONE"dbresults must be called before the first call to MOREINFO="NONE"dbmoretext and after the last call to MOREINFO="NONE"dbmoretext. See the MOREINFO="NONE"dbwritetext manual page for more information, including an example that uses MOREINFO="NONE"dbmoretext. The DB-Library/C option DBTEXTSIZE affects the value of the server @@textsize global variable, which restricts the size of text or image values that the server returns. @@textsize has a default value of 32,768 bytes. An application that retrieves text or image values larger than 32,768 bytes will need to call MOREINFO="NONE"dbsetopt to make @@textsize larger. REMAP="UN--Under"The DB-Library/C option DBTEXTLIMIT limits the size of text or  image values that DB-Library/C will read. See AlsoREMAP="BO--Body"LINKEND="X49629"dbtxptr
, LINKEND="X23507"dbtxtimestamp
, LINKEND="X38408"dbwritetext
ID="IN6910-62190225"dbmoretext
 ID="IN6911-65193226"dbmsghandleID="X78343"dbmsghandleID="IN7016-66195228"Message handlinginstalling a user function
Install a user function to handle server messages. FORMAT="LINESPECIFIC"int (*dbmsghandle(handler))()FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"int              (*handler)();ParametersREMAP="RI--RefIndent"handler - A pointer to the user function that will be called whenever DB-Library receives an error or informational message from the server. DB-Library calls this function with eight parameters: TOCENTRY="1"LBL="Table 2-29: "Message handler parametersCOLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="72*"COLNAME="C2" COLWIDTH="270*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ParameterCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MeaningVALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"dbprocCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The affected DBPROCESS. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"msgnoCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The current message's number (datatype DBINT). These 
numbers are documented in the  sysmessages table.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"msgstateCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The current message's error state number (datatype int). 
These numbers provide Sybase Technical Support with 
information about the context of the error. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"severityCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The current message's information class or error severity 
(datatype int). These numbers are documented in the 
System Administration Guide. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"msgtextCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The null-terminated text of the current message (datatype 
char *). COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"srvnameCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The null-terminated name of the server that generated the 
message (datatype char *). A server's name is stored in the 
srvname column of its sysservers system table. It is used in 
server-to-server communication; in particular, it's used 
when one server logs into another server to perform a 
remote procedure call. If the server has no name, srvname 
will be of length 0. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"procnameCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The null-terminated name of the stored procedure that 
generated the message (datatype char *). If the message 
was not generated by a stored procedure, procname will be 
of length 0. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"lineCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The number of the command batch or stored procedure 
line that generated the message (datatype 
DBUSMALLINT). Line numbers start at 1. The line 
number pertains to the nesting level at which the message 
was generated. For instance, if a command batch executes 
stored procedure A, which then calls stored procedure B, 
and a message is generated at line 3 of B, then line will be 
3. 

line will be 0 if there is no line number associated with the 
message. Circumstances that could generate messages 
without line numbers include a login error or a remote 
procedure call (performed via MOREINFO="NONE"dbrpcsend) to a stored 
procedure that doesn't exist. REMAP="UN--Under"The message handler must return a value of 0 to DB-Library. REMAP="UN--Under"The following example shows a typical message handler routine:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"#include <sybfront.h> #include <sybdb.h>  int msg_handler(dbproc, msgno, msgstate,    severity, msgtext, srvname, procname, line)  DBPROCESS         *dbproc; DBINT             msgno; int               msgstate; int               severity; char              *msgtext; char              *srvname; char              *procname; DBUSMALLINT       line;  {      printf ("Msg %ld, Level %d, State %d\n",           msgno, severity, msgstate);       if (strlen(srvname) > 0)           printf ("Server '%s', ", srvname);       if (strlen(procname) > 0)           printf ("Procedure '%s', ", procname);       if (line > 0)           printf ("Line %d", line);        printf("\n\ %s\n", msgtext);        return(0); } ReturnsREMAP="BO--Body"A pointer to the previously-installed message handler. This may be NULL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbmsghandle installs a message-handler function that you supply. When DB-Library receives a server error or informational message, it will call this message handler immediately. You must install a message handler in order to handle server messages properly. If an application does not call MOREINFO="NONE"dbmsghandle to install a message-handler function, DB-Library ignores server messages. The messages are not printed.ID="IN7015-66195233"Command buffersCommand buffersand message handlingmessage handlingIf the command buffer contains just a single command and that  command provokes a server message, DB-Library will call the message  handler during MOREINFO="NONE"dbsqlexec. If the command buffer contains multiple commands and one of the commands provokes a server message, DB-Library will call the message handler when MOREINFO="NONE"dbresults is called for the particular command. ID="IN7016-66195234"Message handlingde-installing handlerYou can de-install an existing message handler by calling MOREINFO="NONE"dbmsghandle with a NULL parameter. You can also, at any time, install a new message handler. The new handler will automatically replace any existing handler. See the sysmessages table for a list of server messages. In addition, the Transact-SQL MOREINFO="NONE"print and MOREINFO="NONE"raiserror commands generate server messages that MOREINFO="NONE"dbmsghandle will catch. The routines MOREINFO="NONE"dbsetuserdata and MOREINFO="NONE"dbgetuserdata can be particularly useful when you need to transfer information between the message handler and the program code that triggered it. See the MOREINFO="NONE"dbsetuserdata manual page for an example of how to handle deadlock in this way. Another routine, MOREINFO="NONE"dberrhandle, installs an error handler  that DB-Library calls in response to DB-Library errors. If the application provokes messages from DB-Library and the server simultaneously, DB-Library calls the server message handler before it calls the DB-Library error handler. The DB-Library/C error value SYBESMSG is generated in response to a server error message, but not in response to a server informational message.  This means that when a server error occurs, both the server message handler and the DB-Library/C error handler are called, but when the server generates an informational message, only the server message handler is called. REMAP="UN--Under"If you have installed a server message handler, you may want to write your DB-Library error handler so as to suppress the printing of any SYBESMSG error, to avoid notifying the user about the same error twice. The following chart provides information on when DB-Library/C calls an application's message and error handlersTOCENTRY="1"LBL="Table 2-30: "Interaction of message and error handlersCOLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="153*"COLNAME="C2" COLWIDTH="88*"COLNAME="C3" COLWIDTH="115*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Error or MessageCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Message Handle 
Called?COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Error Handler Called?VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SQL syntax errorCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"YesCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Yes (SYBESMSG)aCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SQL print statementCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"YesCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NoCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SQL raiserrorCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"YesCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Server diesCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NoCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Yes (SYBESEOF) bCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Timeout from the serverCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NoCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Yes (SYBETIME)cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Deadlock on querydCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"YesCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Timeout on loginCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NoCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Yes (SYBEFCON)COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Login fails (MOREINFO="NONE"dbopen) COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"YesCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Yes (SYBEPWD)bCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Use database messageCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"YesaCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Incorrect use of DB-Library/C 
calls, such as not calling 
MOREINFO="NONE"dbresults when requiredCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NoCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Yes (SYBERPND, ...) COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fatal Server error (severity 
greater than 16) COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Yes bCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Yes (SYBESMSG) VALIGN="TOP"aCode your handler to ignore the message.bCode your handler to exit the application.cTo wait   for another timeout period, code your handler to return 
INT_CONTINUE.dCode your handler to test for deadlock.See AlsoREMAP="BO--Body"LINKEND="X12458"dberrhandle
, LINKEND="X34885"dbgetuserdata
, LINKEND="X15711"dbsetuserdata
ID="IN7011-69198236"dbmsghandle
ID="IN7016-70199237"Message handlinginstalling a user function
 REMAP="BO--Body"ID="X47894"dbnameID="IN4399753"Databasesreturning name of current
Return the name of the current database. FORMAT="LINESPECIFIC"char *dbname(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. ReturnsREMAP="BO--Body"A pointer to the null-terminated name of the current database. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbname returns the name of the current database. If you need to keep track of when the database changes, use MOREINFO="NONE"dbchange. See AlsoREMAP="BO--Body"LINKEND="X22834"dbchange
, LINKEND="X74526"dbuse
ID="IN4369489"dbname
 ID="IN439911110"dbnextrowID="X10726"dbnextrowID="IN444911212"Rowsreading next
ID="IN4411911213"Result rowsreading next
ID="IN4412911214"Regular rowsreading next
ID="IN4412911215"Compute rowsreading next
Read the next result row. FORMAT="LINESPECIFIC"STATUS dbnextrow(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. ReturnsID="IN444911219"Rowsdetermining typeREMAP="BO--Body"MOREINFO="NONE"dbnextrow can return five different types of values: ID="IN4412911220"Regular rowsdeterminingMARK="BULL" REMAP="BU--Bullet"If a regular row is read, REG_ROW is returned. ID="IN4412911221"Compute rowsdeterminingIf a compute row is read, the computeid of the row is returned. (See MOREINFO="NONE"dbaltbind for information on the computeid.) If there are no more rows to be read or the command didn't return any rows, NO_MORE_ROWS is returned. If buffering is turned on and reading the next row would cause the buffer to be exceeded, BUF_FULL is returned. In this case, no row will have been read. To read any more rows, at least one row must first be pruned from the top of the row buffer by calling MOREINFO="NONE"dbclrbuf. If the routine was unsuccessful, FAIL is returned. CommentsMARK="BULL" REMAP="BU--Bullet"ID="IN4415891423"DBBUFFER optionDBBUFFER optionand reading result rowsreading result rows
MOREINFO="NONE"dbnextrow reads the next row of result data, starting with the first row returned from the server. Ordinarily, the next result row is read directly from the server. If the DBBUFFER option is turned on and rows have been read out of order by calling MOREINFO="NONE"dbgetrow, the next row is read instead from a linked list of buffered rows. When MOREINFO="NONE"dbnextrow is called, any binding of row data to program variables (as specified with MOREINFO="NONE"dbbind or MOREINFO="NONE"dbaltbind) takes effect. MOREINFO="NONE"dbresults must return SUCCEED before an application can call MOREINFO="NONE"dbnextrow.  To determine whether a particular  command is one that returns rows and needs results processing with MOREINFO="NONE"dbnextrow,  call MOREINFO="NONE"DBROWS after MOREINFO="NONE"dbresults. After calling MOREINFO="NONE"dbresults, an application can either call MOREINFO="NONE"dbcanquery or MOREINFO="NONE"dbcancel to cancel the current set of results, or MOREINFO="NONE"dbnextrow to process the results.   If it chooses to process the results, an application can either:MARK="DASH" REMAP="BS--BulletSub"Process all result rows by calling MOREINFO="NONE"dbnextrow  in a loop until it returns NO_MORE_ROWS. After NO_MORE_ROWS is returned, the application can call MOREINFO="NONE"dbresults again, to set up the next result set (if any) for processing.Process some result rows by calling MOREINFO="NONE"dbnextrow, and then cancel the remaining result rows by calling MOREINFO="NONE"dbcancel or MOREINFO="NONE"dbcanquery.REMAP="UN--Under"An application must either cancel or process all result rows.The typical sequence of calls is: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"DBINT     xvariable; DBCHAR    yvariable[10];  /* Read the query into the command buffer */ dbcmd(dbproc, "select x = 100, y = 'hello'"); /* Send the query to SQL Server */ dbsqlexec(dbproc);  /* Get ready to process the query results */ dbresults(dbproc);  /* Bind column data to program variables */ dbbind(dbproc, 1, INTBIND, (DBINT) 0,     (BYTE *) &xvariable); dbbind(dbproc, 2, STRINGBIND, (DBINT) 0,    yvariable);  /* Now process each row */ while (dbnextrow(dbproc) != NO_MORE_ROWS) {     C-code to print or process row data } The server can return two types of rows: regular rows containing data from columns designated by a MOREINFO="NONE"select statement's select-list, and compute rows resulting from the MOREINFO="NONE"compute clause. To facilitate the processing of result rows from the server, MOREINFO="NONE"dbnextrow returns different values according to the type of row. See the section MOREINFO="NONE"Returns for details. To display server result data on the default output device, you can use MOREINFO="NONE"dbprrow instead of MOREINFO="NONE"dbnextrow. An asynchronous version of MOREINFO="NONE"dbnextrow, called MOREINFO="NONE"dbnextrow_a, is available for VMS. See AlsoREMAP="BO--Body"LINKEND="X21854"dbaltbind
, LINKEND="X14206"dbbind
, LINKEND="X15355"dbcanquery
, LINKEND="X38617"dbclrbuf
, LINKEND="X71422"dbgetrow
, LINKEND="X90089"dbnextrow_a (VMS only)
, LINKEND="X66379"dbprrow
, LINKEND="X55181"dbsetrow
, LINKEND="X60647"options
ID="IN449861725"dbnextrow
 ID="X90089"dbnextrow_a  (VMSID="IN4517832126"dbnextrow_a (VMS)
 only)ID="IN454832128"Rowsreading next:asynchronous version (VMS)
ID="IN4511832129"Result rowsreading next:asynchronous version (VMS)
ID="IN4512832130"Regular rowsreading next:asynchronous version (VMS)
ID="IN4512832131"Compute rowsreading next:asynchronous version (VMS)
Read the next result row. FORMAT="LINESPECIFIC"STATUS dbnextrow_a(dbproc, final_result, ast_proc,                    ast_param)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS   *dbproc;FORMAT="LINESPECIFIC"RETCODE     *final_result;FORMAT="LINESPECIFIC"void        (*ast_proc)();FORMAT="LINESPECIFIC"BYTE        *ast_param;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. final_result - A pointer to a RETCODE which is set to (1) REG_ROW if a regular row was read, (2) the row's computeid if a compute row was read, (3) NO_MORE_ROWS if there are no more rows to be read or if the command didn't return any rows, or (4) FAIL if a server communications error occurred. final_result will be set only if MOREINFO="NONE"dbnextrow_a returns SUCCEED. For information on compute rows and the computeid, see the manual page on MOREINFO="NONE"dbaltbind. ast_proc - A pointer to a user-supplied routine that will be queued when the correctness of the command batch is finally determined by the server.  *final_result will always be set before this procedure is invoked. ast_param - A generic BYTE pointer that will be passed to the user-supplied ast_proc(). ast_param allows the user to pass any parameter or structure to the ast_proc routine. ReturnsREMAP="BO--Body"MOREINFO="NONE"dbnextrow_a can return three different values: MARK="BULL" REMAP="BU--Bullet"If the routine succeeded, SUCCEED is returned. If buffering is turned on and reading the next row would cause the buffer to be exceeded, BUF_FULL is returned. In this case, no row will have been read. To read any more rows, at least one row must first be pruned from the top of the row buffer by calling MOREINFO="NONE"dbclrbuf. If the routine was otherwise unsuccessful, FAIL is returned. CommentsID="IN4527812336"Asynchronous routines (VMS)dbnextrow_aMARK="BULL" REMAP="BU--Bullet"This routine is the asynchronous version of MOREINFO="NONE"dbnextrow. MOREINFO="NONE"dbnextrow_a causes the next row of result data to be read, starting with the first row returned from the server. Ordinarily, the next result row is taken directly from the server. If the DBBUFFER option is turned on and rows have been read out of order by calling MOREINFO="NONE"dbgetrow, the next data row is read instead from a linked list of buffered rows. When MOREINFO="NONE"dbnextrow_a is called, any binding of row data to program variables (as specified with MOREINFO="NONE"dbbind or MOREINFO="NONE"dbaltbind) takes effect. The application must call MOREINFO="NONE"dbresults or MOREINFO="NONE"dbresults_a with a final result of SUCCEED before it can make any calls to MOREINFO="NONE"dbnextrow_a. To determine whether a particular command is one that returns rows and needs results processing with MOREINFO="NONE"dbnextrow_a, call MOREINFO="NONE"DBROWS after MOREINFO="NONE"dbresults or MOREINFO="NONE"dbresults_a. Normally, each row is processed in turn by repeatedly calling MOREINFO="NONE"dbnextrow_a until final_result has been set to NO_MORE_ROWS. To cancel the current set of results instead, call MOREINFO="NONE"dbcanquery. After a call to MOREINFO="NONE"dbcanquery, it is safe to call MOREINFO="NONE"dbresults or MOREINFO="NONE"dbresults_a again. The server can return two types of rows: regular rows containing data from columns designated by a MOREINFO="NONE"select statement's select-list, and compute rows resulting from the MOREINFO="NONE"compute clause. To facilitate the processing of rows from the server, MOREINFO="NONE"dbnextrow_a returns different final results according to the type of row. See below for details. The following three events must occur before row data can be examined: MARK="DASH" REMAP="BS--BulletSub"MOREINFO="NONE"dbnextrow_a must return SUCCEED. *final_result must be set to SUCCEED by DB-Library. ast_proc() must be invoked by DB-Library. REMAP="UN--Under"If MOREINFO="NONE"dbnextrow_a returns FAIL or BUF_FULL, *final_result will not be set and ast_proc() will not be invoked. If MOREINFO="NONE"dbnextrow_a returns SUCCEED, *final_result will be set (see the description of final_result below), and ast_proc() will be invoked by DB-Library. ID="IN4513812337"Input streamsutilizing multiple (VMS)
ID="IN4514812338"Output streamsutilizing multiple (VMS)MOREINFO="NONE"dbnextrow_a is useful in VMS applications that use multi-tasking or are otherwise trying to respond to multiple input and output streams. MOREINFO="NONE"dbnextrow waits until a row is received or until the timeout period has elapsed. By substituting MOREINFO="NONE"dbnextrow_a for MOREINFO="NONE"dbnextrow, the time between the request for server information and the server's      response can be used to service other parts of the application. References in this manual to the MOREINFO="NONE"dbnextrow routine also pertain to MOREINFO="NONE"dbnextrow_a. For an example that illustrates the use of MOREINFO="NONE"dbnextrow_a, see the on-line example programs. See AlsoREMAP="BO--Body"LINKEND="X21854"dbaltbind
, LINKEND="X14206"dbbind
, LINKEND="X15355"dbcanquery
, LINKEND="X54207"dbcanquery_a (VMS only)
, LINKEND="X38617"dbclrbuf
, LINKEND="X71422"dbgetrow
, LINKEND="X10726"dbnextrow
, LINKEND="X66379"dbprrow
, LINKEND="X60647"options
ID="IN4517782640"dbnextrow_a (VMS)
 ID="IN4510752941"dbnpcreate
ID="IN4520752942"Registered procedurecreating
ID="IN4531752943"Creating a registered procedure
ID="IN4522752944"Notification procedurecreating
ID="IN4533752945"Creating a notification procedureID="X44215"dbnpcreate
Create a notification procedure. FORMAT="LINESPECIFIC"RETCODE dbnpcreate(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a  particular front-end/server process.   It contains all the information that  DB-Library/C uses to manage communications and data between the front end and the server. ReturnsREMAP="BO--Body"SUCCEED or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbnpcreate creates a notification procedure. A notification procedure is a special type of Open Server registered procedure.  A notification procedure differs from a normal Open Server registered procedure in that it contains no executable statements. Notification procedures are the only type of Open Server registered  procedure that a DB-Library/C application can create. The procedure name and its parameters must have been previously defined via MOREINFO="NONE"dbnpdefine and MOREINFO="NONE"dbregparam. To create a notification procedure, a DB-Library/C application must: MARK="DASH" REMAP="BS--BulletSub"Define the procedure via MOREINFO="NONE"dbnpdefine. Describe the procedure's parameters, if any, via MOREINFO="NONE"dbregparam. Create the procedure via MOREINFO="NONE"dbnpcreate. All DB-Library/C routines that apply to registered procedures apply to notification procedures as well. For example, MOREINFO="NONE"dbregexec executes a registered procedure, which may or may not be a notification procedure.  Likewise, MOREINFO="NONE"dbreglist lists all registered procedures currently defined in Open Server, some of which may be notification procedures. Like other registered procedures, notification procedures are  useful for inter-application communication and synchronization, because applications can request to be advised  when a notification procedure executes. Notification procedures may be created only in Open Server.  At this time, SQL Server does not support notification procedures. A DB-Library/C application requests to be notified of a registered  procedure's execution via MOREINFO="NONE"dbregwatch.   The application may request to be  notified either synchronously or asynchronously. This is an example of creating a notification procedure: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"DBPROCESS   *dbproc; DBINT       status;  /* ** Let's create a notification procedure called ** "message" which has two parameters: **      msg     varchar(255) **      user    idint */  /*  ** Define the name of the notification procedure** "message" */ dbnpdefine (dbproc, "message", DBNULLTERM);  /*  ** The notification procedure has two parameters: **       msg    varchar(255) **       user   idint ** So, define these parameters.  Note that ** neither of the parameters is defined with a** default value. */ dbregparam (dbproc, "msg", SYBVARCHAR,    DBNODEFAULT, NULL); dbregparam (dbproc, "userid", SYBINT4,    DBNODEFAULT, 4);  /*  Create the notification procedure: */ status = dbnpcreate (dbproc); if (status == FAIL) {     fprintf(stderr, "ERROR:  Failed to create \         message!\n"); } else {     fprintf(stdout, "Success in creating \         message!\n"); } See AlsoREMAP="BO--Body"LINKEND="X53834"dbreginit
,  LINKEND="X63607"dbregparam
,  LINKEND="X44024"dbregwatch
,  LINKEND="X95291"dbregnowatch
ID="IN4610723352"dbnpcreate
 ID="IN4610693653"dbnpdefine
ID="IN4620693654"Registered procedurecreating
ID="IN4620693655"Registered proceduredefining
ID="IN4631693656"Creating a registered procedure
ID="IN4631693657"Defining a registered procedure
ID="IN4622693658"Notification procedurecreating
ID="IN4622693659"Notification proceduredefining
ID="IN4633693660"Creating a notification procedure
ID="IN4633693661"Defining a notification procedureID="X65953"dbnpdefine
Define a notification procedure. FORMAT="LINESPECIFIC"RETCODE dbnpdefine(dbproc, procedure_name, namelen)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"DBCHAR        *procedure_name;FORMAT="LINESPECIFIC"DBSMALLINT    namelen;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a  particular front-end/server process.   It contains all the information that DB-Library/C uses to manage communications and data between the front end and the server. procedure_name - A pointer to the name of the notification procedure being defined. namelen - The length of procedure_name, in bytes. If procedure_name is null-terminated, pass namelen as DBNULLTERM. ReturnsREMAP="BO--Body"SUCCEED or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbnpdefine defines a notification procedure.  Defining a  notification procedure is the first step in creating it. A notification procedure is a special type of Open Server registered procedure.  A notification procedure differs from a normal Open Server registered procedure in that it contains no executable statements. Notification procedures are the only type of Open Server registered  procedure that a DB-Library/C application can create. To create a notification procedure, a DB-Library/C application must: MARK="DASH" REMAP="BS--BulletSub"Define the procedure via MOREINFO="NONE"dbnpdefine. Describe the procedure's parameters, if any, via MOREINFO="NONE"dbregparam. Create the procedure via MOREINFO="NONE"dbnpcreate. All DB-Library/C routines that apply to registered procedures apply to notification procedures as well. For example, MOREINFO="NONE"dbregexec executes a registered procedure, which may or may not be a notification procedure.  Likewise, MOREINFO="NONE"dbreglist lists all registered procedures currently defined in Open Server, some of which may be notification procedures. This is an example of defining a notification procedure: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc; DBINT        status;  /* ** Let's create a notification procedure called** "message" which has two parameters:**      msg     varchar(255) **      userid  int */  /*  ** Define the name of the notification procedure** "message" */ dbnpdefine (dbproc, "message", DBNULLTERM);  /* The notification procedure has two parameters: **      msg    varchar(255) **      userid int ** So, define these parameters.  Note that** neither of the parameters is defined with a** default value. */ dbregparam (dbproc, "msg", SYBVARCHAR,    DBNODEFAULT, NULL); dbregparam (dbproc, "userid", SYBINT4,    DBNODEFAULT, 4); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/*  Create the notification procedure: */ status = dbnpcreate (dbproc); if (status == FAIL) {     fprintf(stderr, "ERROR:  Failed to create \         message!\n"); } else {     fprintf(stdout, "Success in creating \        message!\n"); }                See AlsoREMAP="BO--Body"LINKEND="X63607"dbregparam
,  LINKEND="X44215"dbnpcreate
,  LINKEND="X77038"dbreglist
ID="IN4710664068"dbnpdefine
 ID="IN4710634369"dbnullbindID="X56339"dbnullbindID="IN4815634471"Regular columnsassociating indicator variables with
Associate an indicator variable with a regular result row column. FORMAT="LINESPECIFIC"RETCODE dbnullbind(dbproc, column, indicator)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS   *dbproc;FORMAT="LINESPECIFIC"int         column;FORMAT="LINESPECIFIC"DBINT       *indicator;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. column - The number of the column that is to be associated with the indicator variable. indicator - A pointer to the indicator variable. ReturnsREMAP="BO--Body"SUCCEED or FAIL. MOREINFO="NONE"dbnullbind returns FAIL if column is invalid. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbnullbind associates a regular result row column with an indicator variable. The indicator variable indicates whether a particular regular result row's column has been converted and copied to a program variable successfully or unsuccessfully, or whether it is null. The indicator variable is set when regular result rows are processed via MOREINFO="NONE"dbnextrow. The possible values are: MARK="DASH" REMAP="BS--BulletSub"-1 if the column is NULL. The full length of column's data, in bytes if column was bound to a program variable via MOREINFO="NONE"dbbind, the binding did not specify any data conversions, and the bound data was truncated because the program variable was too small to hold column's data. 0 if column was bound and copied to a program variable successfully. Detection of character string truncation is implemented only for CHARBIND and VARYCHARBIND. See AlsoREMAP="BO--Body"LINKEND="X63819"dbanullbind
, LINKEND="X14206"dbbind
, LINKEND="X69467"dbdata
, LINKEND="X61322"dbdatlen
, LINKEND="X10726"dbnextrow
ID="IN4810604777"dbnullbind
 ID="IN489575078"dbnumaltsID="X55172"dbnumaltsID="IN4912575180"Compute rowsreturning number of columns
ID="IN4915575181"Compute columnsreturning number in row
Return the number of columns in a compute row. FORMAT="LINESPECIFIC"int dbnumalts(dbproc, computeid)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS   *dbproc;FORMAT="LINESPECIFIC"int         computeid;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. computeid - The id that identifies the particular compute row of interest. A SQL MOREINFO="NONE"select statement may have multiple MOREINFO="NONE"compute clauses, each of which returns a separate compute row. The computeid corresponding to the first MOREINFO="NONE"compute clause in a MOREINFO="NONE"select is 1. The computeid is returned by MOREINFO="NONE"dbnextrow or MOREINFO="NONE"dbgetrow. ReturnsREMAP="BO--Body"The number of columns for the particular computeid.MOREINFO="NONE"dbnumalts returns -1 if computeid is invalid. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbnumalts returns the number of columns in a compute row. The application can call this routine after MOREINFO="NONE"dbresults returns SUCCEED. For example, given the SQL statement: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"select dept, year, sales from employee     order by dept, year     compute avg(sales), min(sales),     max(sales) by dept REMAP="UN--Under"the call "dbnumalts(dbproc, 1)" will return 3. See AlsoREMAP="BO--Body"LINKEND="X46780"dbadata
, LINKEND="X76889"dbadlen
, LINKEND="X12040"dbaltlen
, LINKEND="X53350"dbalttype
, LINKEND="X71422"dbgetrow
, LINKEND="X10726"dbnextrow
, LINKEND="X66483"dbnumcols
ID="IN499545487"dbnumalts
 ID="IN499515788"dbnumcolsID="X66483"dbnumcolsID="IN5015515890"Regular columnsdetermining number of in results
Determine the number of regular columns for the current set of results. FORMAT="LINESPECIFIC"int dbnumcols(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS   *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. ReturnsREMAP="BO--Body"The number of columns in the current set of results.  If there are no columns, MOREINFO="NONE"dbnumcols returns 0. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbnumcols returns the number of regular (i.e., non-compute) columns in the current set of results. Here's a program fragment that illustrates the use of MOREINFO="NONE"dbnumcols: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"int        column_count; DBPROCESS  *dbproc;  /* Put the commands into the command buffer */ dbcmd(dbproc, "select name, id, type from \     sysobjects"); dbcmd(dbproc, " select name from sysobjects");  /* ** Send the commands to SQL Server and start** execution */ dbsqlexec(dbproc);  /* Process each command until there are no more */ while (dbresults(dbproc) != NO_MORE_RESULTS) {     column_count = dbnumcols(dbproc);     printf("%d columns in this SQL Server \         result.\n", column_count);     while (dbnextrow(dbproc) != NO_MORE_ROWS)         printf("row received.\n"); } See AlsoREMAP="BO--Body"LINKEND="X80379"dbcollen
, LINKEND="X83710"dbcolname
, LINKEND="X55172"dbnumalts
ID="IN509486196"dbnumcols
 ID="IN5012456497"dbnumcomputedbnumcompute
Return the number of MOREINFO="NONE"computeID="IN5115436799"compute clausesreturning number in results
 clauses in the current set of results. FORMAT="LINESPECIFIC"int dbnumcompute(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS   *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. ReturnsREMAP="BO--Body"The number of MOREINFO="NONE"compute clauses in the current set of results. CommentsMARK="BULL" REMAP="BU--Bullet"This routine returns the number of MOREINFO="NONE"compute clauses in the current set of results. The application can call it after MOREINFO="NONE"dbresults returns SUCCEED. For example, given the SQL statement: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"select dept, name from employee     order by dept, name     compute count(name) by dept     compute count(name) REMAP="UN--Under"the call "dbnumcompute(dbproc)" will return 2 since there are two MOREINFO="NONE"compute clauses in the MOREINFO="NONE"select statement. See AlsoREMAP="BO--Body"LINKEND="X55172"dbnumalts
, LINKEND="X35104"dbresults
ID="IN51124070105"dbnumcompute
 ID="IN51113773106"DBNUMORDERSID="X81410"DBNUMORDERS
Return the number of columns specified in a Transact-SQL MOREINFO="NONE"select statement's MOREINFO="NONE"order MOREINFO="NONE"byID="IN52163576108"order by clausesreturning number of columns in
ID="IN5273378109"Columnsreturning number in order by clause
 clause. FORMAT="LINESPECIFIC"int DBNUMORDERS(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS   *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. ReturnsREMAP="BO--Body"The number of MOREINFO="NONE"order MOREINFO="NONE"by columns. If there's no MOREINFO="NONE"order MOREINFO="NONE"by clause, this routine returns 0. If there's an error, it returns -1. CommentsMARK="BULL" REMAP="BU--Bullet"Once a MOREINFO="NONE"select statement has been executed and MOREINFO="NONE"dbresults has been called to process it, the application can call DBNUMORDERS to find out how many columns were specified in the statement's MOREINFO="NONE"order MOREINFO="NONE"by clause. See AlsoREMAP="BO--Body"LINKEND="X48294"dbordercol
ID="IN52113081115"DBNUMORDERS
 ID="IN5292784116"dbnumretsID="X32989"dbnumretsID="IN53172785118"Stored proceduresreturn parameter values:determining number of
ID="IN53232785119"Return parameter valuesdetermining number of
Determine the number of return parameter values generated by a stored procedure. FORMAT="LINESPECIFIC"int dbnumrets(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. ReturnsREMAP="BO--Body"The number of return parameter values associated with the most recently-executed stored procedure. CommentsID="IN53222785124"Remote procedure callsdetermining number of return parameter valuesMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbnumrets provides the number of return parameter values returned by the most recent MOREINFO="NONE"execute statement or remote procedure call on a stored procedure. ID="IN53232785125"Return parameter valuesTransact-SQL stored procedures can return values for specified "return parameters." Changes made to the value of a return parameter inside the stored procedure are then available to the program that called the procedure. This is analogous to the "pass by reference" facility available in some programming languages. ID="IN53102389126"dbrpcparamdbrpcparamand return parameter valuesreturn parameter valuesFor a parameter to function as a return parameter, it must be declared as such within the stored procedure. The MOREINFO="NONE"execute statement or remote procedure call that calls the stored procedure must also indicate that the parameter should function as a return parameter. In the case of a remote procedure call, it is the MOREINFO="NONE"dbrpcparam routine that specifies whether a parameter is a return parameter. When executing a stored procedure, the server returns any parameter values immediately after returning all other results. Therefore, the application can call MOREINFO="NONE"dbnumrets only after processing the stored procedure's results by calling MOREINFO="NONE"dbresults, as well as MOREINFO="NONE"dbnextrow if appropriate. (Note that a stored procedure can generate several sets of results-one for each MOREINFO="NONE"select it contains. Before the application can call MOREINFO="NONE"dbnumrets or any other routines that process return parameters, it must call MOREINFO="NONE"dbresults and MOREINFO="NONE"dbnextrow as many times as necessary to process all the results.) If the stored procedure is invoked with a remote procedure call, the return parameter values are automatically available to the application. If, on the other hand, the stored procedure is invoked with an MOREINFO="NONE"execute statement, the return parameter values are available only if the command batch containing the MOREINFO="NONE"execute statement uses local variables, not constants, for the return parameters. Other routines return additional information about return parameter values: MARK="DASH" REMAP="BS--BulletSub"MOREINFO="NONE"dbretdata returns a pointer to a parameter value. MOREINFO="NONE"dbretlen returns the length of a parameter value. MOREINFO="NONE"dbretname returns the name of a parameter value. MOREINFO="NONE"dbrettype returns the datatype of a parameter value. For an example of this routine, see the on-line example programs.See AlsoREMAP="BO--Body"LINKEND="X10726"dbnextrow
, LINKEND="X35104"dbresults
, LINKEND="X29147"dbretdata
, LINKEND="X78900"dbretlen
, LINKEND="X24047"dbretname
, LINKEND="X70606"dbrettype
, LINKEND="X47823"dbrpcinit
, LINKEND="X50365"dbrpcparam
ID="IN5392092128"dbnumrets
 ID="IN5361795129"dbopenID="X42139"dbopen
Create and initialize a DBPROCESSID="IN54191598131"DBPROCESS structureallocating
ID="IN541913100132"DBPROCESS structureinitializing
ID="IN54613100133"Serverlogging into
ID="IN542313100134"Logging into the server
 structure. FORMAT="LINESPECIFIC"DBPROCESS *dbopen(login, server)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"LOGINREC      *login;FORMAT="LINESPECIFIC"char          *server;ParametersREMAP="RI--RefIndent"login - A pointer to a LOGINREC structure.  This pointer will be passed as an argument to MOREINFO="NONE"dbopen. You can get one by calling MOREINFO="NONE"dblogin. REMAP="UN--Under"Once the application has made all its MOREINFO="NONE"dbopen calls, the LOGINREC structure is no longer necessary. The program can then call MOREINFO="NONE"dbloginfree to free the LOGINREC structure. server ID="IN54155108137"interfaces fileinterfaces fileand dbopendbopen
- The server that you want to connect to. server is the alias given to the server in the interfaces file. MOREINFO="NONE"dbopen looks up server in the interfaces file to get information for connecting to a server. REMAP="UN--Under"If server is NULL MOREINFO="NONE"dbopen looks up the interfaces entry that corresponds to the value of the DSQUERY environment variable or logical name. If DSQUERY has not been explicitly set, it has a value of "SYBASE". (For information on designating an interfaces file, see the manual page for MOREINFO="NONE"dbsetifile. For more information on the interfaces file itself, see the Open Client/Server Supplement.) For the OS/2 platform, client applications do not use an interfaces file and "SYBASE" is not the default name for SQL Server.  Consult your Installation Guide for Open Client Net-Library for information on how the server parameter is used by MOREINFO="NONE"dbopen on this platforms. ReturnsREMAP="BO--Body"A DBPROCESS pointer if everything went well. Ordinarily, MOREINFO="NONE"dbopen returns NULL if a DBPROCESS structure couldn't be created or initialized, or if your login to the server failed. When MOREINFO="NONE"dbopen returns NULL, it generates a DB-Library error number that indicates the error. The application can access this error number through an error handler. However, if there's an unexpected communications failure during the server login process and an error handler has not been installed, the program will be aborted. CommentsREMAP="UN--Under"This routine allocates and initializes a DBPROCESS structure. This structure is the basic data structure that DB-Library uses to communicate with a server. It is the first argument in almost every DB-Library call. Besides allocating the DBPROCESS structure, this routine sets up communication with the network, logs into the server, and initializes any default options. MARK="BULL" REMAP="BU--Bullet"Here's a program fragment that uses MOREINFO="NONE"dbopen: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"DBPROCESS       *dbproc; LOGINREC        *loginrec;  loginrec = dblogin(); DBSETLPWD(loginrec, "server_password"); DBSETLAPP(loginrec, "my_program"); dbproc = dbopen(loginrec, "my_server"); Multiple QUERY entries in an interfaces file: It is possible to set up an interfaces file so that if MOREINFO="NONE"dbopen fails to establish a connection with a server, it attempts to establish a connection with an alternate server. REMAP="UN--Under"An application can use the MOREINFO="NONE"dbopen call REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"dbopen(loginrec, MARS); REMAP="UN--Under"to connect to the server MARS.  An interfaces file containing an entry for MARS might look like this: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"# MARS     query tcp hp-ether violet 1025     master tcp hp-ether violet 1025     console tcp hp-ether violet 1026 # VENUS     query tcp hp-ether plum 1050     master tcp hp-ether plum 1050     console tcp hp-ether plum 1051 # NEPTUNE     query tcp hp-ether mauve 1060     master tcp hp-ether mauve 1060     console tcp hp-ether mauve 1061 REMAP="BO--Body"The application is directed to port number 1025  on the machine violet. If MARS is not available, the MOREINFO="NONE"dbopen call fails. If the interfaces file has multiple query entries in it for MARS, however, then when the first connection attempt fails, MOREINFO="NONE"dbopen will automatically attempt to connect to the next server listed. Such an interfaces file might look like this: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"# MARS     query tcp hp-ether violet 1025     query tcp hp-ether plum 1050     query tcp hp-ether mauve 1060     master tcp hp-ether violet 1025     console tcp hp-ether violet 1026 # VENUS     query tcp hp-ether plum 1050     master tcp hp-ether plum 1050     console tcp hp-ether plum 1051 # NEPTUNE     query tcp hp-ether mauve 1060     master tcp hp-ether mauve 1060     console tcp hp-ether mauve 1061 REMAP="BO--Body"Note that the second query entry under MARS is identical to the query entry under VENUS, and that the third query entry is identical to the query entry under NEPTUNE. If this interfaces file is used, then if  the application fails to connect with MARS it will automatically attempt to connect with VENUS. If it fails to connect with VENUS, it will automatically attempt to connect with NEPTUNE. There is no limit on the number of alternate servers that may be listed under a server's interfaces file entry, but each alternate server must be listed in the same  interfaces file. Two numbers may be added after the server's name in the interfaces file: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"# MARS retries seconds     query tcp hp-ether violet 1025     query tcp hp-ether plum 1050     query tcp hp-ether mauve 1060     master tcp hp-ether violet 1025     console tcp hp-ether violet 1026 REMAP="BO--Body"retries represents the number of additional times to loop through the list of query entries if no connection is achieved during the first pass. seconds represents the amount of time, in seconds, that MOREINFO="NONE"dbopen will wait at the top of the loop before going through the list again.  These numbers are optional. If they are not included, MOREINFO="NONE"dbopen will try to  connect to each query entry only once.  Looping through the list and pausing between loops is useful in case any of the candidate servers is in the process of booting. Multiple query lines can be particularly useful when alternate servers contain mirrored copies of the  primary server's databases. MARK="BULL" REMAP="BU--Bullet"Once the application has logged into a server, it can change databases by calling the MOREINFO="NONE"dbuse routine. An asynchronous version of MOREINFO="NONE"dbopen, called MOREINFO="NONE"dbopen_a, is available for VMS. ErrorsREMAP="BO--Body"MOREINFO="NONE"dbopen will return NULL if any of the following are true: REMAP="BO--Body"SYBEMEM       Unable to allocate sufficient memory. SYBEDBPS       Maximum number of DBPROCESSes already allocated.                              Note that an application can set or retrieve the                              maximum number of DBPROCESSes via MOREINFO="NONE"dbsetmaxprocs                              and MOREINFO="NONE"dbgetmaxprocs SYBESOCK      Unable to open socket. SYBEINTF       Server name not found in interfaces file. SYBEUHST     Unknown host machine name. SYBECONN    Unable to connect: SQL Server is unavailable or does                                not exist. SYBEPWD       Login incorrect. SYBEOPIN       Could not open interfaces file. See AlsoREMAP="BO--Body"LINKEND="X87778"dbclose
, LINKEND="X99227"dbexit
, LINKEND="X24387"dbinit
, LINKEND="X88162"dblogin
, LINKEND="X96175"dbloginfree
, LINKEND="X10573"dbopen_a (VMS only)
, LINKEND="X25800"dbsetifile
, LINKEND="X74526"dbuse
ID="IN5462111142"dbopen
 ID="X10573"dbopen_a  (VMSID="IN5514-1115143"dbopen_a (VMS)
 only)
Create and initialize a DBPROCESSID="IN5519-3117145"DBPROCESS structureallocating:asynchronous version (VMS)
ID="IN556-3117146"Serverlogging into:asynchronous (VMS)
ID="IN5523-3117147"Logging into the serverasynchronous (VMS)
 structure. FORMAT="LINESPECIFIC"RETCODE dbopen_a(login, server, dbproc, final_result,                 ast_proc, ast_param)FORMAT="LINESPECIFIC"LOGINREC      *login;FORMAT="LINESPECIFIC"char          *server;FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"RETCODE       *final_result;FORMAT="LINESPECIFIC"void          (*ast_proc)();FORMAT="LINESPECIFIC"BYTE          *ast_param;ParametersREMAP="RI--RefIndent"login - A pointer to a LOGINREC structure.  This pointer will be passed as an argument to MOREINFO="NONE"dbopen_a. You can get one by calling MOREINFO="NONE"dblogin. REMAP="UN--Under"Once the application has made all its MOREINFO="NONE"dbopen_a calls, the LOGINREC structure is no longer necessary. The program can then call MOREINFO="NONE"dbloginfree to free the LOGINREC structure. server - The server that you want to connect to. server is the alias given to the server in the interfaces file. MOREINFO="NONE"dbopen_a looks up server in the interfaces file to get information for connecting to a server. REMAP="UN--Under"If server is NULL MOREINFO="NONE"dbopen_a looks up the interfaces entry that corresponds to the value of the DSQUERY environment variable or logical name. If DSQUERY has not been explicitly set, it has a value of "SYBASE". (For information on designating an interfaces file, see the manual page for MOREINFO="NONE"dbsetifile. For more information on the interfaces file itself, see the Open Client/Server Supplement.) dbproc - A pointer which will point to a newly-allocated DBPROCESS structure if MOREINFO="NONE"dbopen_a returns SUCCEED and *final_result is set to SUCCEED. Otherwise, dbproc will be invalid. final_result - A pointer to a RETCODE which is set to SUCCEED or FAIL if MOREINFO="NONE"dbopen_a returns SUCCEED. *final_result is set to SUCCEED if a successful connection to a server has been made. The most common reason that *final_result gets set to FAIL is because the login to the server failed. REMAP="UN--Under"When *final_result is set to FAIL, a DB-Library error number that indicates the error may be accessed through an error handler. However, if there's an unexpected communications failure during the server login process and an error handler has not been installed, the program will be aborted. ast_proc - A pointer to a user-supplied routine that will be queued when the success of the current command is finally determined by the server.  *final_result will always be set before this procedure is invoked. ast_param - A generic BYTE pointer that will be passed to the user-supplied ast_proc(). ast_param allows the user to pass any parameter or structure to the ast_proc() routine. ReturnsREMAP="UN--Under"SUCCEED or FAIL. MOREINFO="NONE"dbopen_a will return FAIL if either of the following conditions are true: MARK="BULL" REMAP="BU--Bullet"The maximum number of DBPROCESS structures has been exceeded. This number can be set with the DB-Library routine MOREINFO="NONE"dbsetmaxprocs. There's not enough memory to allocate another DBPROCESS structure. CommentsID="IN5527-5119152"Asynchronous routines (VMS)dbopen_aMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbopen_a is the asynchronous version of MOREINFO="NONE"dbopen. This routine allocates and initializes a DBPROCESS structure. This structure is the basic data structure that DB-Library uses to communicate with a server. It is the first argument in almost every DB-Library call. Besides allocating the DBPROCESS structure, this routine sets up communication with the network, logs into the server, and initializes any default options. The following three events must occur before any other DB-Library routines can be called: MARK="DASH" REMAP="BS--BulletSub"MOREINFO="NONE"dbopen_a must return SUCCEED. *final_result must be set to SUCCEED by DB-Library. ast_proc() must be invoked by DB-Library. REMAP="UN--Under"If MOREINFO="NONE"dbopen_a returns FAIL, *final_result will not be set and ast_proc() will not be invoked. If MOREINFO="NONE"dbopen_a returns SUCCEED, *final_result will be set to SUCCEED or FAIL and ast_proc() will be invoked by DB-Library. ID="IN5513-5119153"Input streamsutilizing multiple (VMS)
ID="IN5514-5119154"Output streamsutilizing multiple (VMS)MOREINFO="NONE"dbopen_a is useful in VMS applications that use multi-tasking or are otherwise trying to respond to multiple input and output streams. MOREINFO="NONE"dbopen waits until a connection to the server has been made or until all retries have been exhausted. By substituting MOREINFO="NONE"dbopen_a for MOREINFO="NONE"dbopen, the time it takes to obtain a server can be used to service other parts of the application. Once the application has logged into a server, it can change databases by calling the MOREINFO="NONE"dbuse routine. References in this manual to the MOREINFO="NONE"dbopen routine also pertain to MOREINFO="NONE"dbopen_a. For an example that illustrates the use of MOREINFO="NONE"dbopen_a, see the on-line example programs.See AlsoREMAP="BO--Body"LINKEND="X87778"dbclose
, LINKEND="X99227"dbexit
, LINKEND="X24387"dbinit
, LINKEND="X88162"dblogin
, LINKEND="X96175"dbloginfree
, LINKEND="X42139"dbopen
, LINKEND="X25800"dbsetifile
, LINKEND="X74526"dbuse
ID="IN5514-8122156"dbopen_a (VMS)
 ID="IN5510-11125157"dbordercolID="X48294"dbordercol
Return the id of a column appearing in the most recently executed query's MOREINFO="NONE"order MOREINFO="NONE"byID="IN5616-13128159"order by clausesreturning column id in
ID="IN567-15130160"Columnsreturning id of in order by clause
 clause. FORMAT="LINESPECIFIC"int dbordercol(dbproc, order)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"int           order;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. order - The id that identifies the particular MOREINFO="NONE"order MOREINFO="NONE"by column of interest. The first column named within the MOREINFO="NONE"order MOREINFO="NONE"by clause is number 1. ReturnsREMAP="BO--Body"The column id (based on the column's position in the select-list) for the column in the specified place in the MOREINFO="NONE"order MOREINFO="NONE"by clause. If the order is invalid, MOREINFO="NONE"dbordercol returns -1. CommentsMARK="BULL" REMAP="BU--Bullet"This routine returns the id of the column that appears in a specified location within the MOREINFO="NONE"order MOREINFO="NONE"by clause of a SQL MOREINFO="NONE"select command. REMAP="UN--Under"For example, given the SQL statement: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"select dept, name, salary from employee     order by salary, name REMAP="UN--Under"the call "dbordercol(dbproc, 1)" will return 3 since the first column named in the MOREINFO="NONE"order MOREINFO="NONE"by clause refers to the third column in the query's select-list. See AlsoREMAP="BO--Body"LINKEND="X81410"DBNUMORDERS
ID="IN566-18133166"dbpoll
ID="IN5620-18133167"Registered procedurenotifications
ID="IN5626-18133168"Polling the network buffer
ID="IN5614-18133169"Network bufferpolling
ID="IN5610-18133170"TDS bufferpolling
ID="IN5622-18133171"Multiple input streamsID="X45215"dbpoll
Check if a server response has arrived for a DBPROCESS. FORMAT="LINESPECIFIC"RETCODE dbpoll(dbproc, milliseconds,
ready_dbproc,              return_reason)FORMAT="LINESPECIFIC"FORMAT="LINESPECIFIC"DBPROCESS       *dbproc;FORMAT="LINESPECIFIC"long            milliseconds;FORMAT="LINESPECIFIC"DBPROCESS       **ready_dbproc;FORMAT="LINESPECIFIC"int             *return_reason;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a  particular front-end/server process.   It contains all the information that DB-Library/C  uses to manage communications and data between the front end and  server. REMAP="UN--Under"dbproc represents the DBPROCESS connection that MOREINFO="NONE"dbpoll will check. REMAP="UN--Under"If dbproc is passed as NULL, MOREINFO="NONE"dbpoll will check all open DBPROCESS connections to see if a response has  arrived for any of them. milliseconds - The maximum number of milliseconds that MOREINFO="NONE"dbpoll  should wait for a response before returning.  REMAP="UN--Under"If milliseconds is passed as 0, MOREINFO="NONE"dbpoll  returns immediately.  REMAP="UN--Under"If milliseconds is passed as -1, MOREINFO="NONE"dbpoll will not return until either a server response arrives or a system  interrupt occurs. ready_dbproc - A pointer to a pointer to a DBPROCESS structure.  MOREINFO="NONE"dbpoll sets *ready_dbproc to point to the DBPROCESS for which the server response has arrived. If no response has arrived, MOREINFO="NONE"dbpoll sets *ready_dbproc to NULL. return_reason - A pointer to an integer representing the reason MOREINFO="NONE"dbpoll has returned. The integer will be one of the following symbolic values: REMAP="UN--Under"DBRESULTREMAP="UN--Under"A response to a server command has arrived.  The application may call MOREINFO="NONE"dbsqlok (assuming that  MOREINFO="NONE"dbsqlsend has been called) to examine the server's response. REMAP="UN--Under"DBNOTIFICATIONREMAP="UN--Under"A registered procedure notification has arrived.  If a handler for this registered procedure has been installed via MOREINFO="NONE"dbreghandle, MOREINFO="NONE"dbpoll invokes this handler before it returns.  If a handler for the  registered procedure has not been installed and there is no default handler for this DBPROCESS installed, DB-Library/C raises an error when it reads the notification. REMAP="UN--Under"DBTIMEOUTREMAP="UN--Under"The time indicated by the milliseconds parameter  elapsed before any server response arrived. REMAP="UN--Under"DBINTERRUPTREMAP="UN--Under"An operating-system interrupt occurred before any  server response arrived and before the timeout period elapsed. This list may expand in the future, as more kinds of  server responses are recognized by DB-Library/C.  It is recommended that application programs be coded to handle unexpected values in return_reason without error. ReturnsREMAP="BO--Body"SUCCEED or FAIL.  REMAP="BO--Body"MOREINFO="NONE"dbpoll returns FAIL if any of the server connections it checks has died. If MOREINFO="NONE"dbpoll returns FAIL, ready_dbproc  and return_reason are undefined. VMS programmers:  MOREINFO="NONE"dbpoll returns FAIL if registered procedure notifications are disabled. Use MOREINFO="NONE"dbsetnotifs to enable and disable registered procedure notifications. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbpoll checks the TDS (Tabular Data Stream) buffer to see if it contains any server response not yet  read by an application. dbproc represents the DBPROCESS connection that MOREINFO="NONE"dbpoll will check.  If dbproc is passed as NULL, MOREINFO="NONE"dbpoll examines all open connections and returns as soon as it finds one that has an unread server response. If there is an unread response, MOREINFO="NONE"dbpoll sets ready_dbproc  and return_reason to reflect which DBPROCESS connection the response is for and what the response is. MOREINFO="NONE"dbpoll can be used for two purposes: MARK="DASH" REMAP="BS--BulletSub"To check if a registered procedure notification has arrived for a DBPROCESS. To enable an application to implement non-blocking reads from the server.  Concerning registered procedure notifications and MOREINFO="NONE"dbpoll: MARK="DASH" REMAP="BS--BulletSub"An application may have one  or more DBPROCESS connections waiting for registered procedure  notifications. A DBPROCESS connection will not be aware that an  registered procedure notification has arrived unless it  reads results from the server.  If a connection is  not reading results, it can use MOREINFO="NONE"dbpoll  to check if a registered procedure notification has arrived.   If so, MOREINFO="NONE"dbpoll reads the registered procedure notification  stream and calls the handler for that registered procedure. Concerning non-blocking reads and MOREINFO="NONE"dbpoll: MARK="DASH" REMAP="BS--BulletSub"Depending on the nature  of an application, the time between a request for information from the server (usually made via MOREINFO="NONE"dbsqlsend) and the server's response (read via MOREINFO="NONE"dbsqlok, MOREINFO="NONE"dbresults, or MOREINFO="NONE"dbnextrow) may be significant. An application may use this time to perform other duties.  When ready, the application can check to see if a server response has arrived while it was busy elsewhere. To check for a server response, an application can either use MOREINFO="NONE"dbpoll, or MOREINFO="NONE"DBRBUF and MOREINFO="NONE"DBIORDESC. MOREINFO="NONE"DBRBUF is a UNIX and AOS/VS-specific routine.  It checks an internal DB-Library network buffer to see if a server response has already been read.    MOREINFO="NONE"dbpoll checks one or all connections used by an application's DBPROCESSes, to see if a response is ready to be read. MOREINFO="NONE"DBIORDESC, another UNIX and AOS/VS-specific routine, is similar in function to MOREINFO="NONE"dbpoll, but can check only single socket and  must be used with the UNIX select or AOS/VS equivalent. Since the UNIX and AOS/VS-specific routines MOREINFO="NONE"DBRBUF and MOREINFO="NONE"DBIORDESC are non-portable, their use should be avoided whenever possible.  They do, however, provide a way for application programs  to integrate handling of DB-Library/C sockets with other sockets  being used by an application.  Note that ready_dbproc, the third parameter required by  MOREINFO="NONE"dbpoll, is not a pointer to a DBPROCESS structure. It is a pointer to the address of a DBPROCESS.  MOREINFO="NONE"dbpoll sets *ready_dbproc to point to the DBPROCESS for which the server response has arrived.  If no server response has arrived, MOREINFO="NONE"dbpoll sets *ready_dbproc to NULL. This is a code fragment that uses MOREINFO="NONE"dbpoll: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* ** This code fragment illustrates the use of ** dbpoll() to processan event notification. ** ** The code fragment will ask the Server to ** notify the Client when the event "shutdown" ** occurs. When the event notification is** received from the Server, DB-Library will call ** the handler installed for that event. This** event handler routine can then access the ** event's parameters, and take any appropriate  ** action. */ REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"DBINT   handlerfunc(); DBINT   ret; REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* First install the handler for this event */ dbreghandle(dbproc, "shutdown", handlerfunc); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* ** Now make the asynchronous notification** request. */ ret = dbregwatch(dbproc, "shutdown", DBNULLTERM,    DBNOWAITONE); if (ret == FAIL) {     fprintf(stderr, "ERROR: dbregwatch() \         failed!!\n"); } else if (ret == DBNOPROC) {     fprintf(stderr, "ERROR: procedure shutdown \         not defined!\n"); } REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* ** Since we are making use of the asynchronous ** event notification mechanism, the application** can continue doing other work. All we have to ** do is call dbpoll() once in a while, to deal ** with the event notification when it arrives. */ while (1) {     /* Have dbpoll() block for one second */     dbpoll(NULL, 1000, NULL, &ret);REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /*     ** If we got the event, then get out of this    ** loop.     */     if (ret == DBNOTIFICATION)     {         break;     }      REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /* Deal with our other tasks here */ } See AlsoREMAP="BO--Body"LINKEND="X41944"DBIORDESC
, LINKEND="X55434"DBFUF
, LINKEND="X35104"dbresults
, LINKEND="X25775"dbreghandle
, LINKEND="X21206"dbsqlok
ID="IN576-21137178"dbpoll
 ID="X41324"dbpoll_a (VMS only)
Check if a server response has arrived for a DBPROCESS. FORMAT="LINESPECIFIC"RETCODE dbpoll(dbproc, milliseconds, ready_dbproc,           return_reason,final_result,ast_proc,           ast_param)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"long         milliseconds;FORMAT="LINESPECIFIC"DBPROCESS    **ready_dbproc;FORMAT="LINESPECIFIC"int          *return_reason;FORMAT="LINESPECIFIC"RETCODE      *final_result;FORMAT="LINESPECIFIC"void         (*ast_proc)();FORMAT="LINESPECIFIC"BYTE         *ast_param;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a  particular front-end/server process.   It contains all the information that DB-Library/C  uses to manage communications and data between the front end and  server. REMAP="UN--Under"dbproc represents the DBPROCESS connection that MOREINFO="NONE"dbpoll_a will check. REMAP="UN--Under"If dbproc is passed as NULL, MOREINFO="NONE"dbpoll_a will check all open DBPROCESS connections to see if a response has  arrived for any of them. milliseconds - The maximum number of milliseconds that MOREINFO="NONE"dbpoll_a  should wait for a response before returning.  REMAP="UN--Under"If milliseconds is passed as 0, MOREINFO="NONE"dbpoll_a  returns immediately.  REMAP="UN--Under"If milliseconds is passed as -1, MOREINFO="NONE"dbpoll_a will not return until either a server response arrives or a system  interrupt occurs. ready_dbproc - A pointer to a pointer to a DBPROCESS structure.  MOREINFO="NONE"dbpoll_a sets *ready_dbproc to point to the DBPROCESS for which the server response has arrived. If no response has arrived, MOREINFO="NONE"dbpoll_a sets *ready_dbproc to NULL. return_reason - A pointer to an integer representing the reason MOREINFO="NONE"dbpoll_a has returned. The integer will be one of the following symbolic values: REMAP="UN--Under"DBRESULTREMAP="UN--Under"A response to a server command has arrived.  The application may call MOREINFO="NONE"dbsqlok (assuming that  MOREINFO="NONE"dbsqlsend has been called) to examine the server's response. REMAP="UN--Under"DBNOTIFICATIONREMAP="UN--Under"A registered procedure notification has arrived.  If a handler for this registered procedure has been installed via MOREINFO="NONE"dbreghandle, MOREINFO="NONE"dbpoll_a invokes this handler before it returns.  If a handler for the  registered procedure has not been installed and there is no default handler for this DBPROCESS installed, DB-Library/C raises an error when it reads the notification. REMAP="UN--Under"DBTIMEOUTREMAP="UN--Under"The time indicated by the milliseconds parameter  elapsed before any server response arrived. REMAP="UN--Under"DBINTERRUPTREMAP="UN--Under"An operating-system interrupt occurred before any  server response arrived and before the timeout period elapsed. This list may expand in the future, as more kinds of  server responses are recognized by DB-Library/C.  It is recommended that application programs be coded to handle unexpected values in return_reason without error. final_result - A pointer to a RETCODE which is set to SUCCEED or FAIL. ast_proc - A pointer to a user-supplied routine that will be queued when either something has arrived from the server, the timeout period has expired, or an error has occurred. *final_result will always be set before this procedure is invoked. ast_param - A generic BYTE pointer that will be passed to the user-supplied ast_proc(). ast_param allows the user to pass any parameter or structure to the ast_proc routine. ReturnsREMAP="BO--Body"SUCCEED or FAIL. It will also set final_result and invoke ast_proc() when the operation has fully completed. REMAP="BO--Body"MOREINFO="NONE"dbpoll_a returns FAIL if any of the server connections it checks has died. If MOREINFO="NONE"dbpoll_a returns FAIL, ready_dbproc  and return_reason are undefined. VMS programmers:  MOREINFO="NONE"dbpoll_a returns FAIL if registered procedure notifications are disabled. Use MOREINFO="NONE"dbsetnotifs to enable and disable registered procedure notifications. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbpoll_a checks the TDS (Tabular Data Stream) buffer to see if it contains any server response not yet  read by an application. dbproc represents the DBPROCESS connection that MOREINFO="NONE"dbpoll_a will check.  If dbproc is passed as NULL, MOREINFO="NONE"dbpoll_a examines all open connections and invokes the ast_proc as soon as it finds one that has an unread server response. If there is an unread response, dbpoll_a sets ready_dbproc  and return_reason to reflect which DBPROCESS connection the response is for and what the response is. MOREINFO="NONE"dbpoll_a can be used for two purposes: MARK="DASH" REMAP="BS--BulletSub"To check if a registered procedure notification has arrived for a DBPROCESS. To enable an application to implement non-blocking reads from the server.  Concerning registered procedure notifications and MOREINFO="NONE"dbpoll_a: MARK="DASH" REMAP="BS--BulletSub"An application may have one  or more DBPROCESS connections waiting for registered procedure  notifications. A DBPROCESS connection will not be aware that an  registered procedure notification has arrived unless it  reads results from the server.  If a connection is  not reading results, it can use MOREINFO="NONE"dbpoll_a  to check if a registered procedure notification has arrived.   If so, MOREINFO="NONE"dbpoll_a reads the registered procedure notification  stream and calls the handler for that registered procedure. Concerning non-blocking reads and MOREINFO="NONE"dbpoll_a: MARK="DASH" REMAP="BS--BulletSub"Depending on the nature  of an application, the time between a request for information from the server (usually made via MOREINFO="NONE"dbsqlsend) and the server's response (read via MOREINFO="NONE"dbresults or MOREINFO="NONE"dbnextrow) may be significant. An application can use this time to perform other duties.  When ready, the application can check to see if a server response has arrived while it was busy elsewhere.Do not use dbsqlok to read the server's response. If the server has already returned results to the client, dbsqlok will wait for the next reponse. Unless event notification is enabled, dbsqlok will wait forever.Note that ready_dbproc, the third parameter required by  MOREINFO="NONE"dbpoll_a, is not a pointer to a DBPROCESS structure. It is a pointer to the address of a DBPROCESS.  MOREINFO="NONE"dbpoll_a sets *ready_dbproc to point to the DBPROCESS for which the server response has arrived.  If no server response has arrived, MOREINFO="NONE"dbpoll_a sets *ready_dbproc to NULL. See AlsoREMAP="BO--Body"LINKEND="X35104"dbresults
, LINKEND="X25775"dbreghandle
, LINKEND="X21206"dbsqlok
, LINKEND="X45215"dbpoll
ID="IN588-27144191"dbpoll_a
 ID="IN588-30147192"dbprheadID="X13029"dbprheadID="IN5911-30148194"Result rowsprinting column headings of
ID="IN594-30148195"Rowsprinting column headings of
ID="IN599-34152196"DebuggingDebuggingand dbprheaddbprhead
Print the column headings for rows returned from the server. FORMAT="LINESPECIFIC"void dbprhead(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. ReturnsREMAP="BO--Body"None. CommentsMARK="BULL" REMAP="BU--Bullet"This routine displays, on the default output device and in a default format, the column headings for a set of query results. The format is compatible with the format used by MOREINFO="NONE"dbprrow. The application can call MOREINFO="NONE"dbprhead once MOREINFO="NONE"dbresults returns SUCCEED. You can specify the maximum number of characters to be placed on one line via the DB-Library option DBPRLINELEN. This routine is useful for debugging. See AlsoREMAP="BO--Body"LINKEND="X14206"dbbind
, LINKEND="X10726"dbnextrow
, LINKEND="X66379"dbprrow
, LINKEND="X35104"dbresults
ID="IN598-37155202"dbprhead
 ID="IN597-40158203"dbprrowID="X66379"dbprrowID="IN6011-40159205"Result rowsprinting
ID="IN604-40159206"Rowsprinting
ID="IN609-44163207"DebuggingDebuggingand dbprrowdbprrow
Print all the rows returned from the server. FORMAT="LINESPECIFIC"RETCODE dbprrow(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. ReturnsREMAP="BO--Body"SUCCEED or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"This routine displays, on the default output device and in a default format, the rows for a set of query results. This routine reads and prints all the rows. It saves the trouble of calling routines such as MOREINFO="NONE"dbbind and MOREINFO="NONE"dbnextrow, but it prints only in a single, predetermined format. The application can call MOREINFO="NONE"dbprrow once MOREINFO="NONE"dbresults returns SUCCEED. When using this routine, you do not need to call MOREINFO="NONE"dbnextrow to loop through the rows. You can specify the maximum number of characters to be placed on one line via the DB-Library option DBPRLINELEN. MOREINFO="NONE"dbprrow is useful primarily for debugging. If row buffering is turned on, MOREINFO="NONE"dbprrow buffers rows in addition to printing them out. If the buffer is full, the oldest rows are removed as necessary. See AlsoREMAP="BO--Body"LINKEND="X14206"dbbind
, LINKEND="X10726"dbnextrow
, LINKEND="X13029"dbprhead
, LINKEND="X35104"dbresults
ID="IN607-47166213"dbprrow
 ID="IN608-50169214"dbprtypeID="X77266"dbprtypeID="IN6112-50170216"Token valuesconverting to readable strings
ID="IN616-50170217"Servertoken values:converting
Convert a token value to a readable string. FORMAT="LINESPECIFIC"char *dbprtype(token)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"int          token;ParametersREMAP="RI--RefIndent"token - The server token value (SYBCHAR, SYBFLT8, etc.) returned by MOREINFO="NONE"dbcoltype, MOREINFO="NONE"dbalttype, MOREINFO="NONE"dbrettype, or MOREINFO="NONE"dbaltop. ReturnsREMAP="BO--Body"A pointer to a null-terminated string that is the readable translation of the token value. The pointer points to space that is never overwritten, so it is safe to call this routine more than once in the same statement. If the token value is unknown, the routine returns a pointer to an empty string. CommentsMARK="BULL" REMAP="BU--Bullet"Certain routines-MOREINFO="NONE"dbcoltype, MOREINFO="NONE"dbalttype, MOREINFO="NONE"dbrettype, and MOREINFO="NONE"dbaltop-return token values representing server datatypes or aggregate operators. MOREINFO="NONE"dbprtype provides a readable string version of a token value. For example, MOREINFO="NONE"dbprtype will take a MOREINFO="NONE"dbcoltype token value representing the server binary datatype (SYBBINARY) and return the string "binary". Here's a list of the token strings that MOREINFO="NONE"dbprtype can return and their token value equivalents: TOCENTRY="1"LBL="Table 2-31: "Token values and their string equivalents.COLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="90*"COLNAME="C2" COLWIDTH="99*"COLNAME="C3" COLWIDTH="162*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Token StringCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Token ValueCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Description VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"charCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBCHARCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"char datatype COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"textCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBTEXTCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"text datatype COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"binaryCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBBINARYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"binary datatype COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"imageCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBIMAGECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"image datatype COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"tinyintCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBINT1COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"1-byte integer datatype COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"smallintCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBINT2COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"2-byte integer datatype COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"intCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBINT4COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"4-byte integer datatype COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"floatCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBFLT8COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"8-byte float datatype COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"realCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBREALCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"4-byte float datatype COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"numericCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBNUMERICCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"numeric typeCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"decimalCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBDECIMALCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"decimal typeCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"bitCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBBITCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"bit datatype COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"moneyCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBMONEYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"money datatype COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"smallmoneyCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBMONEY4COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"4-byte money datatype COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"datetimeCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBDATETIMECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"datetime datatype COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"smalldatetimeCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBDATETIME4COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"4-byte datetime datatype COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"boundaryCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBBOUNDARYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"boundary typeCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"sensitivityCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBSENSITIVITYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"sensitivity typeCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"sumCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBAOPSUMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"sum aggregate operator COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"avgCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBAOPAVGCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"average aggregate operator COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"countCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBAOPCNTCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"count aggregate operator COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"minCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBAOPMINCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"minimum aggregate operator COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"maxCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBAOPMAXCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"maximum aggregate operator See AlsoREMAP="BO--Body"LINKEND="X81910"dbaltop
, LINKEND="X53350"dbalttype
, LINKEND="X35574"dbcoltype
, LINKEND="X70606"dbrettype
, LINKEND="X91146"types
ID="IN618-53173223"dbprtype
 REMAP="BO--Body"ID="X46501"dbqual
Return a pointer to a MOREINFO="NONE"whereID="IN4349753"Rowsupdating current in browsable table
ID="IN43139574"where clausesWHERE clausesfor use in updating a browsable tableuse in updating a browsable table
 clause suitable for use in updating the current row in a browsable table. FORMAT="LINESPECIFIC"char *dbqual(dbproc, tabnum, tabname)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"int           tabnum;FORMAT="LINESPECIFIC"char          *tabname;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and server. tabnum - The number of the table of interest, as specified in the MOREINFO="NONE"select statement's MOREINFO="NONE"from clause. Table numbers start at 1. If tabnum is -1, the tabname parameter will be used to identify the table. tabname - A pointer to the null-terminated name of a table specified in the MOREINFO="NONE"select statement's MOREINFO="NONE"from clause. tabname is ignored unless tabnum is passed as -1. ReturnsREMAP="BO--Body"A pointer to a null-terminated MOREINFO="NONE"where clause for the current row in the specified table. This buffer is dynamically allocated, and it is the application's responsibility to free it via MOREINFO="NONE"dbfreequal. REMAP="BO--Body"MOREINFO="NONE"dbqual will return a NULL pointer if the specified table is not browsable. For a table to be "browsable," it must have a unique index and a timestamp column. REMAP="BO--Body"MOREINFO="NONE"dbqual will also return a NULL pointer if the preceding MOREINFO="NONE"select did not include the MOREINFO="NONE"for MOREINFO="NONE"browse option. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbqual is one of the DB-Library browse mode routines. See the Introduction for a detailed discussion of browse mode. MOREINFO="NONE"dbqual provides a MOREINFO="NONE"where clause that the application can use to update a single row in a browsable table. Columns from this row must have previously been retrieved into the application through a browse-mode MOREINFO="NONE"select query (i.e., a MOREINFO="NONE"select that ends with the key words MOREINFO="NONE"for MOREINFO="NONE"browse). REMAP="UN--Under"The MOREINFO="NONE"where clause produced by MOREINFO="NONE"dbqual begins with the keyword MOREINFO="NONE"where and contains references to the row's unique index and timestamp column. The application simply appends the MOREINFO="NONE"where clause to an MOREINFO="NONE"update or MOREINFO="NONE"delete statement; it does not need to examine it or manipulate it in any way. ID="IN43179579"Timestamp columnsTimestamp columnsand updating rowsupdating rowsREMAP="UN--Under"The timestamp column indicates the time that the particular row was last updated. An update on a browsable table will fail if the timestamp column in the MOREINFO="NONE"dbqual-generated MOREINFO="NONE"where clause is different from the timestamp column in the table. Such a condition, which provokes SQL Server error message 532, indicates that another user updated the row between the time this application selected it for browsing and the time it tried to update it. The application itself must provide the logic for handling the update failure. The following program fragment illustrates one approach: REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"/* This code fragment illustrates a technique for ** handling the case where a browse-mode update fails ** because the row has already been updated ** by another user. In this example, we simply retrieve ** the entire row again, allow the user to examine and ** modify it, and try the update again. ** ** Note that "q_dbproc" is the DBPROCESS used to query ** the database, and "u_dbproc" is the DBPROCESS used ** to update the database. */REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"/* First, find out which employee record the user ** wants to update. */ employee_id = which_employee(); REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"while (1) {     /* Retrieve that employee record from the database.     ** We'll assume that "empid" is a unique index,     ** so this query will return only one row.     */     dbfcmd (q_dbproc, "select * from employees where \         empid = %d for browse", employee_id);     dbsqlexec(q_dbproc);     dbresults(q_dbproc);     dbnextrow(q_dbproc); REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"    /* Now, let the user examine or edit the employee's     ** data, first placing the data into program    ** variables.     */     extract_employee_data(q_dbproc, employee_struct);     examine_and_edit(employee_struct, &edit_flag); REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"    if (edit_flag == FALSE)     {         /* The user didn't edit this record,         ** so we're done.         */         break;     }     else     {         /* The user edited this record, so we'll use         ** the edited data to update the        ** corresponding row in the database.        */         qualptr = dbqual(q_dbproc, -1, "employees");         dbcmd(u_dbproc, "update employees");         dbfcmd (u_dbproc, " set address = '%s', \             salary = %d %s",             employee_struct->address,             employee_struct->salary, qualptr);         dbfreequal(qualptr);         if ((dbsqlexec(u_dbproc) == FAIL) ||            (dbresults(u_dbproc) == FAIL))         {             /* Our update failed. In a real program,             ** it would be necessary to examine the             ** messages returned from the SQL Server             ** to determine why it failed.  In this             ** example, we'll assume that the update             ** failed because someone else has already            ** updated this row, thereby changing            ** the timestamp.             **             ** To cope with this situation, we'll just             ** repeat the loop, retrieving the changed             ** row for our user to examine and edit.             ** This will give our user the opportunity             ** to decide whether to overwrite the             ** change made by the other user.             */             continue;         }         else         {             /* The update succeeded, so we're done. */             break;         }     } } MOREINFO="NONE"dbqual can only construct MOREINFO="NONE"where clauses for browsable tables. You can use MOREINFO="NONE"dbtabbrowse to determine whether a table is browsable. MOREINFO="NONE"dbqual is usually called after MOREINFO="NONE"dbnextrow. For a complete example that uses MOREINFO="NONE"dbqual to perform a browse mode update, see the on-line example programs.See AlsoREMAP="BO--Body"LINKEND="X60561"dbcolbrowse
, LINKEND="X78078"dbcolsource
, LINKEND="X23352"dbfreequal
, LINKEND="X58939"dbtabbrowse
, LINKEND="X52066"dbtabcount
, LINKEND="X84917"dbtabname
, LINKEND="X67923"dbtabsource
, LINKEND="X78355"dbtsnewlen
, LINKEND="X32220"dbtsnewval
, LINKEND="X11575"dbtsput
ID="IN436921011"dbqual
 ID="IN4326851712"DBRBUF (UNIX and AOS/VS)  ID="X55434"DBRBUF (UNIX and AOS/VS only)ID="IN4415812214"Network buffersdetermining whether unread bytes (UNIX and AOS/VS) 
Determine whether the DB-Library network buffer contains any unread bytes. FORMAT="LINESPECIFIC"DBBOOL DBRBUF(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and server. ReturnsREMAP="BO--Body"TRUE (bytes remain in buffer) or FALSE (no bytes in buffer). REMAP="BO--Body"Note that MOREINFO="NONE"DBRBUF actually returns TRUE both when there are bytes available in the read buffer, and when no more results are available to be processed. REMAP="BO--Body"This is because the purpose of MOREINFO="NONE"DBRBUF is to tell an application when it can read and be assured that it will not hang. If MOREINFO="NONE"DBRBUF didn't return TRUE in the case of no more results, then applications that loop while MOREINFO="NONE"DBRBUF returns FALSE could loop indefinitely, if all results had already been processed. CommentsMARK="BULL" REMAP="BU--Bullet"This routine lets the application know if the DB-Library network buffer contains any bytes yet unread. ID="IN4413772619"Input streamsand checking for unread bytes in network buffer (UNIX and AOS/VS) [Input streams:checking for unread bytes in network buffer (UNIX and AOS/VS)
MOREINFO="NONE"DBRBUF is ordinarily used in conjunction with MOREINFO="NONE"dbsqlok and MOREINFO="NONE"DBIORDESC. MOREINFO="NONE"dbpoll, a DB-Library/C routine which checks if a server response has arrived for any DBPROCESS, may replace MOREINFO="NONE"DBRBUF. Since the UNIX-specific routines MOREINFO="NONE"DBRBUF and MOREINFO="NONE"DBIORDESC are non-portable, their use should be avoided whenever possible. They do, however, provide a way for application programs to integrate handling of DB-Library/C sockets with other sockets being used by an application. An application uses these routines to manage multiple input data streams. To manage these streams efficiently, an application that uses MOREINFO="NONE"dbsqlok should check whether any bytes remain either in the network buffer or in the network itself before calling MOREINFO="NONE"dbresults. To test whether bytes remain in the network buffer, the application can call MOREINFO="NONE"DBRBUF. To test whether bytes remain in the network itself, the application can either call the UNIX MOREINFO="NONE"select or AOS/VS equivalent and MOREINFO="NONE"DBIORDESC, or call MOREINFO="NONE"dbpoll. See AlsoREMAP="BO--Body"LINKEND="X41944"DBIORDESC
, LINKEND="X45215"dbpoll
, LINKEND="X21206"dbsqlok
, LINKEND="X35104"dbresults
ID="IN4426703321"DBRBUF (UNIX and AOS/VS)  
 ID="IN4410673622"dbreadpageID="X38277"dbreadpageID="IN4511673724"Binary datareading page of
ID="IN454673725"Databinary:reading a page of
ID="IN459673726"Databasesreading pages
Read a page of binary data from the server. FORMAT="LINESPECIFIC"DBINT dbreadpage(dbproc, dbname, pageno, buf)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"char          *dbname;FORMAT="LINESPECIFIC"DBINT         pageno;FORMAT="LINESPECIFIC"BYTE          buf[];ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and server. dbname - The name of the database of interest. pageno - The number of the database page to be read. buf - A pointer to a buffer to hold the received page data. SQL Server pages are currently 2048 bytes long. ReturnsREMAP="BO--Body"The number of bytes read from the server. If the operation was unsuccessful, MOREINFO="NONE"dbreadpage returns -1. CommentsMARK="BULL" REMAP="BU--Bullet"ID="IN4516634131"Message handlingMessage handlingand dbreadpagedbreadpage
MOREINFO="NONE"dbreadpage reads a page of binary data from the server. This routine is primarily useful for examining and repairing damaged database pages. After calling MOREINFO="NONE"dbreadpage, the DBPROCESS may contain some error or informational messages from the server. These messages may be accessed through a user-supplied message handler. Use this routine only if you are absolutely sure you know what you are doing! LimitationsREMAP="BO--Body"Alters the contents of the DBPROCESS command buffer. See AlsoREMAP="BO--Body"LINKEND="X78343"dbmsghandle
, LINKEND="X48593"dbwritepage
ID="IN4510604434"dbreadpage
 ID="IN4510574735"dbreadtextID="X51086"dbreadtextID="IN4611574837"Text valuesreading parts of
ID="IN4612574838"Image valuesreading parts of
Read part of a text or image value from the server. FORMAT="LINESPECIFIC"STATUS dbreadtext(dbproc, buf, bufsize)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"void          *buf;FORMAT="LINESPECIFIC"DBINT         bufsize;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and server. buf - A pointer to a caller-allocated buffer that will contain the chunk of text or image data. bufsize - The size of the caller's buffer, in bytes. ReturnsREMAP="BO--Body"The following table lists the return values for MOREINFO="NONE"dbreadtext: TOCENTRY="1"LBL="Table 2-32: "Return values for MOREINFO="NONE"dbreadtext.COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="112*"COLNAME="C2" COLWIDTH="247*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Return ValueCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"IndicatingVALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"> 0COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The number of bytes placed into the caller's buffer. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"  0COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The end of a row. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0" -1COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An error occurred, such as a network or out of 
memory error. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NO_MORE_ROWSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"All rows read. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbreadtext reads a large SYBTEXT or SYBIMAGE value from the server in the form of a number of smaller chunks. This is particularly useful with operating systems that are unable to allocate extremely long data buffers. To read successive chunks of the same SYBTEXT or SYBIMAGE value, call MOREINFO="NONE"dbreadtext until it returns 0 (end of row). Use MOREINFO="NONE"dbreadtext in place of MOREINFO="NONE"dbnextrow to read SYBTEXT and SYBIMAGE values. MOREINFO="NONE"dbreadtext can process the results of Transact-SQL queries if those queries return only one column and that column contains either text or image data. The Transact-SQL MOREINFO="NONE"readtext command returns results of this type. The DB-Library/C option DBTEXTSIZE affects the value of the server @@textsize global variable, which restricts the size of text or image values that the server returns. @@textsize has a default value of 32,768 bytes. An application that retrieves text or image values larger than 32,768 bytes will need to call MOREINFO="NONE"dbsetopt to make @@textsize larger. REMAP="UN--Under"The DB-Library/C option DBTEXTLIMIT limits the size of text or image values that DB-Library/C will read. DB-Library/C will throw away any text that exceeds the limit. This code fragment demonstrates the use of MOREINFO="NONE"dbreadtext: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"DBPROCESS   *dbproc; long        bytes; RETCODE     ret; char        buf[BUFSIZE + 1]; REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* ** Install message and error handlers... ** Log into server... ** Send a "use database" command... */ REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* Select a text column: */ dbfcmd(dbproc, "select textcolumn from bigtable"); dbsqlexec(dbproc); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* Process the results: */ while( (ret = dbresults(dbproc)) !=    NO_MORE_RESULTS ) {     if( ret == FAIL )     {         /* dbresults() failed */     } REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    while( (bytes = dbreadtext(dbproc,         (void *)buf, BUFSIZE)) != NO_MORE_ROWS )     {         if( bytes == -1 )         {             /* dbreadtext() failed */         }         else if( bytes == 0 )         {             /* We've reached the end of a row*/             printf("End of Row!\n\n");         }         else         {             /*             ** 'bytes' bytes have been placed            ** into our buffer.             ** Print them:             */             buf[bytes] = '\0';             printf("%s\n", buf);         }     } } See AlsoREMAP="BO--Body"LINKEND="X96538"dbmoretext
, LINKEND="X10726"dbnextrow
, LINKEND="X38408"dbwritetext
ID="IN4610545144"dbreadtext
 ID="IN469515445"dbrecftosdbrecftosID="IN478515547"SQL textrecording
ID="IN476515548"Serverrecording SQL text sent to
ID="IN479515549"Debuggingrecording SQL text sent to the server
Record all SQL sent from the application to the server. FORMAT="LINESPECIFIC"void dbrecftos(filename)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"char         *filename;ParametersREMAP="RI--RefIndent"filename - A pointer to a NULL-terminated character string to be used as the basis for naming SQL session files. ReturnsREMAP="BO--Body"None. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbrecftos causes all SQL sent from the front-end application program to the server to be recorded in a human-readable file. This SQL session information is useful for debugging purposes. DB-Library creates one SQL session file for each call to MOREINFO="NONE"dbopen that occurs after MOREINFO="NONE"dbrecftos is called. Files are named filename.n, where filename is the name specified in the call to MOREINFO="NONE"dbrecftos and n is an integer, starting with 0. REMAP="UN--Under"For example, if filename is "foo", the first file created is named "foo.0", the next "foo.1", and so forth. See AlsoREMAP="BO--Body"LINKEND="X42139"dbopen
ID="IN479485855"dbrecftos
 ID="IN4714456156"dbrecvpassthru
ID="IN473456157"TDSpassthrough operation
ID="IN4710456158"TDS packetreceiving
ID="IN4720456159"Gateway applications
ID="IN4712456160"Applicationsgateway
ID="IN4719456161"Tabular Data Streamroutines
ID="IN4721456162"Passthrough operationID="X16128"dbrecvpassthru
Receive a TDS packet from a server. FORMAT="LINESPECIFIC"RETCODE dbrecvpassthru(dbproc, recv_bufp)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"DBVOIDPTR     *recv_bufp;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library/C uses to manage communications and data between the front end and the server. recv_bufp - A pointer to a variable which MOREINFO="NONE"dbrecvpassthru fills with the address of a buffer containing the TDS packet most recently received by this DBPROCESS connection. The application is not responsible for allocating this buffer. ReturnsREMAP="BO--Body"DB_PASSTHRU_MORE, DB_PASSTHRU_EOM, or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbrecvpassthru receives a TDS (Tabular Data Stream) packet from a server. TDS is an application protocol used for the transfer of requests and request results between clients and servers. Under ordinary circumstances, a DB-Library/C application does not have to deal directly with TDS, because DB-Library/C manages the data stream. MOREINFO="NONE"dbrecvpassthru and MOREINFO="NONE"dbsendpassthru are useful in gateway applications. When an application serves as the intermediary between two servers, it can use these routines to pass the TDS stream from one server to the other, eliminating the process of interpreting the information and re-encoding it. MOREINFO="NONE"dbrecvpassthru reads a packet of bytes from the server connection identified by dbproc and sets *recv_bufp to point to the buffer containing the bytes. A packet has a default size of 512 bytes. An application can change its packet size via MOREINFO="NONE"DBSETLPACKET. For more information on packet sizes, see the MOREINFO="NONE"DBGETPACKET and MOREINFO="NONE"DBSETLPACKET manual pages. MOREINFO="NONE"dbrecvpassthru returns DB_PASSTHRU_EOM if the TDS packet has been marked by the server as EOM (End Of Message). If the TDS packet is not the last in the stream, MOREINFO="NONE"dbrecvpassthru returns DB_PASSTHRU_MORE. A DBPROCESS connection which is used for a MOREINFO="NONE"dbrecvpassthru operation cannot be used for any other DB-Library/C function until DB_PASSTHRU_EOM has been received. This is a code fragment using MOREINFO="NONE"dbrecvpassthru: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* ** The following code fragment illustrates the ** use of dbrecvpassthru() in an Open Server ** gateway application. It will continually get** packets from a remote server, and pass them** through to the client. **  ** The routine srv_sendpassthru() is the Open ** Server counterpart required to complete** this passthru operation. */ REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"DBPROCESS   *dbproc; SRV_PROC    *srvproc; int         ret; BYTE        *packet; REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"while(1)  {     /* Get a TDS packet from the remote server */     ret = dbrecvpassthru(dbproc, &packet); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    if( ret == FAIL )     {         fprintf(stderr, "ERROR - dbrecvpassthru\             failed in handle_results.\n");         exit();     } REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /* Now send the packet to the client */    if( srv_sendpassthru(srvproc, packet,         (int *)NULL) == FAIL )     {         fprintf(stderr, "ERROR - srv_sendpassthru \             failed in handle_results.\n");         exit();     } REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /*     ** We've sent the packet, so let's see if     ** there's any more.     */     if( ret == DB_PASSTHRU_MORE )         continue;     else         break; } See AlsoREMAP="BO--Body"LINKEND="X47536"dbsendpassthru
ID="IN4814426569"dbrecvpassthru
 ID="IN489396870"dbregdrop
ID="IN4820396871"Registered proceduredropping
ID="IN4831396872"Dropping a registered proceduredbregdrop
Drop a registered procedure. FORMAT="LINESPECIFIC"RETCODE dbregdrop(dbproc, procedure_name, namelen)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS      *dbproc;FORMAT="LINESPECIFIC"DBCHAR         *procedure_name;FORMAT="LINESPECIFIC"DBSMALLINT     namelen;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library/C uses to manage communications and data between the front end and the server. procedure_name - A pointer to the name of the registered procedure that the DBPROCESS connection wishes to drop. namelen - The length of procedure_name, in bytes. If procedure_name is null-terminated, pass namelen as DBNULLTERM. ReturnsREMAP="BO--Body"SUCCEED, DBNOPROC, or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbregdrop drops a registered procedure from Open Server. Because a notification procedure is simply a special type of registered procedure, a notification procedure may also be dropped via MOREINFO="NONE"dbregdrop. A DBPROCESS connection can drop any registered procedure defined in Open Server, including procedures created by other DBPROCESS connections and procedures created by other applications. Any mechanism to protect registered procedures must be embodied in the server application. If the procedure referenced by procedure_name is not defined in Open Server, MOREINFO="NONE"dbregdrop returns DBNOPROC. An application can use MOREINFO="NONE"dbreglist to obtain a list of registered procedures currently defined in Open Server. This is a code fragment that uses MOREINFO="NONE"dbregdrop: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* ** The following code fragment illustrates ** dropping a registered procedure. */ REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"DBPROCESS   *dbproc; RETCODE     ret; char        *procname; REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"procname = "some_event"; REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"ret = dbregdrop(dbproc, procname, DBNULLTERM); if (ret == FAIL) {     fprintf(stderr, "ERROR: dbregdrop() \         failed!!\n"); } else if (ret == DBNOPROC) {     fprintf(stderr, "ERROR: procedure %s was not\         registered!\n", procname); } See AlsoREMAP="BO--Body"LINKEND="X44215"dbnpcreate
, LINKEND="X77038"dbreglist
ID="IN499367279"dbregdrop
 ID="IN499337580"dbregexec
ID="IN4920337581"Registered procedureexecuting
ID="IN4932337582"Executing a registered procedure
ID="IN4920337583"Registered procedurenotificationsID="X61111"dbregexec
Execute a registered procedure. FORMAT="LINESPECIFIC"RETCODE dbregexec(dbproc, options)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS      *dbproc;FORMAT="LINESPECIFIC"DBUSMALLINT    options;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library/C uses to manage communications and data between the front end and the server. options - A two-byte bitmask, either DBNOTIFYALL or DBNOTIFYNEXT. REMAP="UN--Under"If MOREINFO="NONE"options is DBNOTIFYALL, Open Server will notify all DBPROCESSes watching for the execution of this registered procedure. REMAP="UN--Under"If MOREINFO="NONE"options is DBNOTIFYNEXT, Open Server will notify only the DBPROCESS that has been watching the longest. ReturnsREMAP="BO--Body"SUCCEED or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbregexec completes the process of executing a registered procedure. Because a notification procedure is simply a special type of registered procedure, a notification procedure may also be executed via MOREINFO="NONE"dbregexec. The procedure name and its parameters must have been previously defined via MOREINFO="NONE"dbreginit and MOREINFO="NONE"dbregparam. To execute a registered procedure, a DB-Library/C application must: MARK="DASH" REMAP="BS--BulletSub"Initiate the call via MOREINFO="NONE"dbreginit. Describe the procedure's parameters, if any, via MOREINFO="NONE"dbregparam. Execute the procedure via MOREINFO="NONE"dbregexec. An application cannot execute a registered procedure that is not defined in Open Server. MOREINFO="NONE"dbreglist returns a list of registered procedures that are currently defined. Registered procedures are useful for inter-application communication and synchronization, because applications can request to be advised when a registered procedure executes. Registered procedures may be created only in Open Server. At this time, SQL Server does not support registered procedures. An application can use MOREINFO="NONE"dbnpcreate, MOREINFO="NONE"dbregparam, and MOREINFO="NONE"dbnpcreate to create a registered procedure. A DB-Library/C application requests to be notified of a registered procedure's execution via MOREINFO="NONE"dbregwatch. The application may request to be notified either synchronously or asynchronously. This is an example of executing a registered procedure: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"DBPROCESS   *dbproc; DBINT       newprice = 55; DBINT       status; REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* ** Initiate execution of the registered procedure** "price_change" */ dbreginit (dbproc, "price_change", DBNULLTERM); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* ** The registered procedure has two parameters: **      name        varchar(255) **      newprice    int ** So pass these parameters to the registered** procedure. */ REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"dbregparam (dbproc, "name", SYBVARCHAR, NULL,    "sybase"); dbregparam (dbproc, "newprice", SYBINT4, 4,    &newprice); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/*  Execute the registered procedure: */ status = dbregexec (dbproc, DBNOTIFYALL); if (status == FAIL) {     fprintf(stderr, "ERROR:  Failed to execute \         price_change!\n"); }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"else if (status == DBNOPROC) {     fprintf(stderr, "ERROR:  Price_change does \         not exist!\n"); } else {     fprintf(stdout, "Success in executing \         price_change!\n"); } See AlsoREMAP="BO--Body"LINKEND="X53834"dbreginit
, LINKEND="X63607"dbregparam
, LINKEND="X44024"dbregwatch
, LINKEND="X95291"dbregnowatch
ID="IN509307990"dbregexec
 ID="IN5011278291"dbreghandle
ID="IN5020278292"Registered procedurehandler routine
ID="IN5020278293"Registered procedurenotifications
ID="IN5013278294"Notificationsregistered procedure
ID="IN507278295"Handlernotification
ID="IN5020278296"Notification handlerID="X25775"dbreghandle
Install a handler routine for a registered procedure notification. FORMAT="LINESPECIFIC"RETCODE dbreghandle(dbproc, procedure_name, namelen,                     handler)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"DBCHAR        *procedure_name;FORMAT="LINESPECIFIC"DBSMALLINT    namelen;FORMAT="LINESPECIFIC"INTFUNCPTR    handler;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library/C uses to manage communications and data between the front end and the server. procedure_name - A pointer to the name of the registered procedure for which the handler is being installed. REMAP="UN--Under"If procedure_name is passed as NULL, the handler is installed as a default handler. The default handler will be called for all registered procedure notifications read by this DBPROCESS connection for which no other handler has been installed. namelen - The length of procedure_name, in bytes. If procedure_name is null-terminated, pass namelen as DBNULLTERM. handler - A pointer to the function to be called by DB-Library/C when the registered procedure notification is read. REMAP="UN--Under"If handler is passed as NULL, any handler previously installed for the registered procedure is de-installed. ReturnsREMAP="BO--Body"SUCCEED or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbreghandle installs a user-supplied handler routine to be called by DB-Library/C when a DBPROCESS connection reads an asynchronous notification that a registered procedure has been executed. REMAP="UN--Under"Because a notification procedure is simply a special type of registered procedure, a handler for a notification procedure may also be installed via MOREINFO="NONE"dbreghandle. An application receives an asynchronous notification only if it has previously called MOREINFO="NONE"dbregwatch with options passed as DBNOWAITONE or DBNOWAITALL. This call tells Open Server that the application is interested in the execution of the registered procedure, that it will receive the notification asynchronously, and that it will read the notification through a particular DBPROCESS connection. If no handler is installed for a notification, DB-Library/C will raise an error when the DBPROCESS connection reads the notification. Either procedure_name or handler may be NULL: MARK="DASH" REMAP="BS--BulletSub"If both procedure_name and handler are supplied, MOREINFO="NONE"dbreghandle installs the handler specified by handler for the registered procedure specified by procedure_name. If procedure_name is NULL and handler is NULL, MOREINFO="NONE"dbreghandle de-installs all handlers for this DBPROCESS connection. If procedure_name is NULL but handler is supplied, MOREINFO="NONE"dbreghandle installs the handler specified by handler as a "default" handler for this DBPROCESS connection. This default handler will be called whenever the DBPROCESS connection reads a registered procedure notification for which no other handler has been installed. If procedure_name is supplied but handler is NULL, MOREINFO="NONE"dbreghandle de-installs any handler previously installed for this registered procedure. If a default handler has been installed for this DBPROCESS connection, it remains in effect and will be called if a procedure_name notification is read. The same handler may be used by several DBPROCESS connections, but it must be installed for each one by a separate call to MOREINFO="NONE"dbreghandle. Because of the possibility of a single notification handler being called when different DBPROCESSes read notifications, all handlers should be written to be re-entrant. A single DBPROCESS connection may be watching for several registered procedures to execute. This connection may have different handlers installed to process the various notifications it may read. Each handler must be installed by a separate call to MOREINFO="NONE"dbreghandle. A DBPROCESS connection may be idle, sending commands, reading results, or idle with results pending when a registered procedure notification arrives. MARK="DASH" REMAP="BS--BulletSub"If the DBPROCESS connection is idle, it is necessary for the application to call MOREINFO="NONE"dbpoll to enable the connection to read the notification. If a handler for the notification has been installed, it will be called before MOREINFO="NONE"dbpoll returns. If the DBPROCESS connection is sending commands, the notification is read and the notification handler called during MOREINFO="NONE"dbsqlexec or MOREINFO="NONE"dbsqlok. After the notification handler returns, flow of control continues normally. If the DBPROCESS connection is reading results, the notification is read and the notification handler called either in MOREINFO="NONE"dbresults or MOREINFO="NONE"dbnextrow. After the notification handler returns, flow of control continues normally. If the DBPROCESS connection is idle with results pending, the notification is not read until all results in the stream up to the notification have been read and processed by the connection. Because a notification may be read while a DBPROCESS connection is in any of several different states, the actions that a notification handler may take are restricted. A notification handler may not use an existing DBPROCESS to send a query to the server, process the results of a query, or call MOREINFO="NONE"dbcancel or MOREINFO="NONE"dbcanquery. A notification handler may, however, open a new DBPROCESS and use this new DBPROCESS to send queries and process results within the handler. A notification handler can read the arguments passed to the registered procedure upon execution. To do this, the handler can use the DB-Library/C routines MOREINFO="NONE"dbnumrets, MOREINFO="NONE"dbrettype, MOREINFO="NONE"dbretlen, MOREINFO="NONE"dbretname, and MOREINFO="NONE"dbretdata. All notification handlers are called by DB-Library/C with the following parameters: MARK="DASH" REMAP="BS--BulletSub"dbproc, a pointer to the DBPROCESS connection that has been watching for the notification; procedure_name, a pointer to the name of the registered procedure that has been executed; reserved1, a DBUSMALLINT parameter reserved for future use; reserved2, a DBUSMALLINT parameter reserved for future use. A notification handler must return INT_CONTINUE to indicate normal completion, or INT_EXIT to instruct DB-Library/C to abort the application and return control to the operating system. This is an example of a notification handler: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"DBINT    my_procedure_handler(dbproc,            procedure_name, reserved1, reserved2) REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* The client connection */DBPROCESS       *dbproc;/* A null-terminated string */DBCHAR          *procedure_name;/* Reserved for future use */DBUSMALLINT     reserved1;/* Reserved for future use */DBUSMALLINT     reserved2;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"{     int     i, type;     DBINT   len;     char    *name;     BYTE    *data;     int     params; REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /*     ** Find out how many parameters this    ** procedure received.    */     params = dbnumrets(dbproc); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    i = 0;    /* Initialize counter */  REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /* Now process each parameter in turn */     while(i++ < params)     {         /* Get the parameter's datatype */         type = dbrettype(dbproc, i); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"        /* Get the parameter's length */         len = dbretlen(dbproc, i); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"        /* Get the parameter's name */         name = dbretname(dbproc, i);REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"        /* Get a pointer to the parameter */         data = dbretdata(dbproc, i); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"        /* Process the parameter here */     }     return(INT_CONTINUE); } See AlsoREMAP="BO--Body"LINKEND="X44024"dbregwatch
, LINKEND="X95291"dbregnowatch
, LINKEND="X63607"dbregparam
, LINKEND="X61111"dbregexec
ID="IN51112486103"dbreghandle
 ID="IN5192189104"dbreginit
ID="IN51202189105"Registered procedureexecuting
ID="IN51322189106"Executing a registered procedureID="X53834"dbreginit
Initiate execution of a registered procedure. FORMAT="LINESPECIFIC"RETCODE dbreginit(dbproc, procedure_name, namelen)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"DBCHAR        *procedure_name;FORMAT="LINESPECIFIC"DBSMALLINT    namelen;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library/C uses to manage communications and data between the front end and server. procedure_name - A pointer to the name of the registered procedure being executed. namelen - The length of procedure_name, in bytes. If procedure_name is null-terminated, pass namelen as DBNULLTERM. ReturnsREMAP="BO--Body"SUCCEED or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbreginit initiates the execution of a registered procedure. Because a notification procedure is simply a special type of registered procedure, execution of a notification procedure may also be initiated via MOREINFO="NONE"dbreginit. To execute a registered procedure, a DB-Library/C application must: MARK="DASH" REMAP="BS--BulletSub"Initiate the call via MOREINFO="NONE"dbreginit. Pass the procedure's parameters, if any, via MOREINFO="NONE"dbregparam. Execute the procedure via MOREINFO="NONE"dbregexec. This is an example of executing a registered procedure: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"DBPROCESS   *dbproc; DBINT       newprice = 55; DBINT       status; REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/*  ** Initiate execution of the registered procedure** "price_change".*/ dbreginit (dbproc, "price_change", DBNULLTERM); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/*  ** The registered procedure has two parameters: **      name        varchar(255) **      newprice    int ** So pass these parameters to the registered** procedure. */ REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"dbregparam (dbproc, "name", SYBVARCHAR, NULL,    "sybase"); dbregparam (dbproc, "newprice", SYBINT4, 4, 4,    &newprice); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/*  Execute the registered procedure: */ status = dbregexec (dbproc, DBNOTIFYALL); if (status == FAIL) {     fprintf(stderr, "ERROR:  Failed to execute \         price_change!\n"); } else if (status == DBNOPROC) {     fprintf(stderr, "ERROR:  Price_change does \         not exist!\n"); } else {     fprintf(stdout, "Success in executing \         price_change!\n"); } See AlsoREMAP="BO--Body"LINKEND="X63607"dbregparam
, LINKEND="X61111"dbregexec
, LINKEND="X44024"dbregwatch
, LINKEND="X77038"dbreglist
, LINKEND="X71568"dbregwatchlist
ID="IN5291893113"dbreginit
 ID="IN5291596114"dbreglist
ID="IN52201596115"Registered procedurelisting currently defined
ID="IN52291596116"Listing registered proceduresID="X77038"dbreglist
Return a list of registered procedures currently defined in Open Server. FORMAT="LINESPECIFIC"RETCODE dbreglist(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library/C uses to manage communications and data between the front end and the server. ReturnsREMAP="BO--Body"SUCCEED or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbreglist returns a list of registered procedures currently defined in Open Server. Because a notification procedure is simply a special type of registered procedure, notification procedures will be included in the list of registered procedures. The list of registered procedures is returned as rows which an application must explicitly process after calling MOREINFO="NONE"dbreglist. Each row represents the name of a single registered procedure defined in Open Server. A row contains a single column of type SYBVARCHAR. The following code fragment illustrates how MOREINFO="NONE"dbreglist might be used in an application: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc; DBCHAR       *procedurename; DBINT        ret; REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* request the list of procedures */ if( (ret = dbreglist(dbproc)) == FAIL) {     /* Handle failure here */ } dbresults(dbproc); while( dbnextrow(dbproc) != NO_MORE_ROWS ) {     procedurename = (DBCHAR *)dbdata(dbproc, 1);     procedurename[dbdatlen(dbproc, 1)] = '\0'; REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    fprintf(stdout, "The procedure '%s' is \         defined.\n", procedurename); } /* All done */ See AlsoREMAP="BO--Body"LINKEND="X71568"dbregwatchlist
, LINKEND="X44024"dbregwatch
ID="IN53912100123"dbreglist
 ID="IN53129103124"dbregnowatch
ID="IN53209103125"Registered procedurecanceling notification request
ID="IN53209103126"Notification requestcancelingID="X95291"dbregnowatch
Cancel a request to be notified when a registered procedure executes. FORMAT="LINESPECIFIC"RETCODE dbregnowatch(dbproc, procedure_name,                      namelen)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"DBCHAR        *procedure_name;FORMAT="LINESPECIFIC"DBSMALLINT    namelen;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library/C uses to manage communications and data between the front end and the server. procedure_name - A pointer to the name of the registered procedure that the DBPROCESS connection is no longer interested in. namelen - The length of procedure_name, in bytes. If procedure_name is null-terminated, pass namelen as DBNULLTERM. ReturnsREMAP="BO--Body"SUCCEED, DBNOPROC, or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbregnowatch cancels a DBPROCESS connection's request to be notified when a registered procedure executes. Because a notification procedure is simply a special type of registered procedure, MOREINFO="NONE"dbregnowatch also cancels a DBPROCESS connection's request to be notified when a notification procedure executes. It is meaningful to call MOREINFO="NONE"dbregnowatch only if the DBPROCESS connection has previously requested an asynchronous notification via MOREINFO="NONE"dbregwatch. If the procedure referenced by procedure_name is not defined in Open Server, MOREINFO="NONE"dbregnowatch returns DBNOPROC. An application can obtain a list of procedures currently registered in Open Server via MOREINFO="NONE"dbreglist. An application can obtain a list of registered procedures it is watching for via MOREINFO="NONE"dbregwatchlist. This is an example of canceling a request to be notified: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"DBPROCESS   *dbproc; DBINT       ret; REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* ** Inform the server that we no longer wish to ** be notified when "price_change" executes: */ ret = dbregnowatch (dbproc, "price_change",    DBNULLTERM); if (ret == DBNOPROC) {     /* The registered procedure must not exist */     fprintf(stderr, "ERROR:  price_change \         doesn't exist!\n"); } See AlsoREMAP="BO--Body"LINKEND="X44024"dbregwatch
, LINKEND="X71568"dbregwatchlist
, LINKEND="X25775"dbreghandle
, LINKEND="X61111"dbregexec
ID="IN54126107133"dbregnowatch
 ID="IN54103110134"dbregparam
ID="IN54203110135"Registered procedureparameters
ID="IN54103110136"Parametersregistered procedureID="X63607"dbregparam
Define or describe a registered procedure parameter. FORMAT="LINESPECIFIC"RETCODE dbregparam(dbproc,param_name, type, datalen,                    data)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"char         *param_name;FORMAT="LINESPECIFIC"int          type;FORMAT="LINESPECIFIC"DBINT        datalen;FORMAT="LINESPECIFIC"BYTE         *data;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library/C uses to manage communications and data between the front end and the server. param_name - A pointer to the parameter name. REMAP="UN--Under"When creating a registered procedure, param_name is required. REMAP="UN--Under"When executing a registered procedure, param_name may be NULL. In this case, the registered procedure will expect to receive its parameters in the order in which they were originally defined. type - The data type of the parameter. Legal data types are: SYBINT1, SYBINT2, SYBINT4, SYBREAL, SYBFLT8, SYBCHAR, SYBBINARY, SYBVARCHAR, SYBDATETIME4, SYBDATETIME, SYBMONEY4, and SYBMONEY. REMAP="UN--Under"Note that SYBTEXT and SYBIMAGE are not legal data types. datalen - The length of the parameter. REMAP="UN--Under"When creating a registered procedure: MARK="DASH" REMAP="BS--BulletSub"datalen can be used to indicate that no default value is being supplied for this parameter. To do this, pass datalen as DBNODEFAULT. datalen can be used to indicate that the default value for a parameter is NULL. This is different from having no default. To do this, pass datalen as 0. REMAP="UN--Under"When executing a registered procedure: MARK="DASH" REMAP="BS--BulletSub"datalen may be 0. In this case, data is ignored and NULL is passed to the registered procedure for this parameter. data - A pointer to the parameter. REMAP="UN--Under"When creating a registered procedure, data can be used to provide a default value for the parameter. Pass data as pointing to the default value. If no default value is desired, pass datalen as DBNODEFAULT. REMAP="UN--Under"When executing a registered procedure, data may be passed as NULL. ReturnsREMAP="BO--Body"SUCCEED or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbregparam defines a registered procedure parameter. Because a notification procedure is simply a special type of registered procedure, MOREINFO="NONE"dbregparam also defines a notification procedure parameter. MOREINFO="NONE"dbregparam is called to define registered procedure parameters when a registered procedure is created and to describe the parameters when a registered procedure is executed. DB-Library/C applications can create only a special type of registered procedure, known as a notification procedure. A notification procedure differs from a normal Open Server registered procedure in that it contains no executable statements. For more information on notification procedures, see the MOREINFO="NONE"dbnpdefine and MOREINFO="NONE"dbnpcreate manual pages. Either MOREINFO="NONE"dbnpdefine, which initiates the process of creating a notification procedure, or MOREINFO="NONE"dbreginit, which initiates the process of executing a registered procedure, must be called before an application calls MOREINFO="NONE"dbregparam. When creating a registered procedure: MARK="DASH" REMAP="BS--BulletSub"To indicate that no default value is being supplied, pass datalen as DBNODEFAULT. data is ignored in this case. To supply a default value of NULL, pass datalen as 0. data is ignored in this case. To supply a default value that is not NULL pass datalen as the length of the value (or -1 if it is a fixed-length type), and data as pointing to the value. When executing a registered procedure: MARK="DASH" REMAP="BS--BulletSub"To pass NULL as the value of the parameter, pass datalen as 0. In this case, data is ignored. To pass a value for this parameter, pass datalen as the length of the value (or -1 if it is a fixed-length type), and data as pointing to the value. To create a notification procedure, a DB-Library/C application must: MARK="DASH" REMAP="BS--BulletSub"Define the procedure via MOREINFO="NONE"dbnpdefine. Describe the procedure's parameters, if any, via MOREINFO="NONE"dbregparam. Create the procedure via MOREINFO="NONE"dbnpcreate. This is an example of creating a notification procedure: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"DBPROCESS   *dbproc; DBINT       status; REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* ** Let's create a notification procedure called ** "message" which has two parameters: **      msg     varchar(255) **      userid  int */ REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/*  ** Define the name of the notification procedure** "message" */ dbnpdefine (dbproc, "message", DBNULLTERM); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* The notification procedure has two parameters: **      msg     varchar(255) **      userid  int ** So, define these parameters.  Note that both ** of these parameters are defined with a default** value of NULL. Passing datalen as 0 ** accomplishes this. */ REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"dbregparam (dbproc, "msg", SYBVARCHAR, 0, NULL); dbregparam (dbproc, "userid", SYBINT4, 0, NULL); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/*  Create the notification procedure: */ status = dbnpcreate (dbproc); if (status == FAIL) {     fprintf(stderr, "ERROR:  Failed to create \        message!\n"); } else {     fprintf(stdout, "Success in creating \         message!\n"); } To execute a registered procedure, a DB-Library/C application must: MARK="DASH" REMAP="BS--BulletSub"Initiate the call via MOREINFO="NONE"dbreginit. Pass the procedure's parameters, if any, via MOREINFO="NONE"dbregparam. Execute the procedure via MOREINFO="NONE"dbregexec. This is an example of executing a registered procedure: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"DBPROCESS   *dbproc; DBINT       newprice = 55; DBINT       status; REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* ** Initiate execution of the registered procedure** "price_change".*/ dbreginit (dbproc, "price_change", DBNULLTERM); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* ** The registered procedure has two parameters: **      name        varchar(255) **      newprice    int ** So pass these parameters to the registered** procedure. */ dbregparam (dbproc, "name", SYBVARCHAR, 6,"sybase"); dbregparam (dbproc, "newprice", SYBINT4, -1,&newprice); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/*  Execute the registered procedure: */ status = dbregexec (dbproc, DBNOTIFYALL); if (status == FAIL) {     fprintf(stderr, "ERROR:  Failed to execute \         price_change!\n"); } else if (status == DBNOPROC) {     fprintf(stderr, "ERROR:  Price_change does \         not exist!\n"); } else {     fprintf(stdout, "Success in executing \         price_change!\n"); } See AlsoREMAP="BO--Body"LINKEND="X53834"dbreginit
, LINKEND="X61111"dbregexec
, LINKEND="X65953"dbnpdefine
, LINKEND="X44215"dbnpcreate
, LINKEND="X44024"dbregwatch
ID="IN55100114143"dbregparam
 ID="IN5510-3117144"dbregwatch
ID="IN5520-3117145"Registered procedurenotifications:requesting
ID="IN5546-3117146"Requesting a registered procedure notificationID="X44024"dbregwatch
Request to be notified when a registered procedure executes. FORMAT="LINESPECIFIC"RETCODE dbregwatch(dbproc, procedure_name,namelen,                   options)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"DBCHAR        *procedure_name;FORMAT="LINESPECIFIC"DBSMALLINT    namelen;FORMAT="LINESPECIFIC"DBUSMALLINT   options;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library/C uses to manage communications and data between the front end and the server. procedure_name - A pointer to the name of a registered procedure. The registered procedure must be defined in Open Server. namelen - The length of procedure_name, in bytes. If procedure_name is null-terminated, pass namelen as DBNULLTERM. options - A two-byte bitmask: DBWAIT, DBNOWAITONE, or DBNOWAITALL. REMAP="UN--Under"If MOREINFO="NONE"options is passed as DBWAIT, MOREINFO="NONE"dbregwatch will not return until the DBPROCESS connection reads a synchronous notification that the registered procedure has executed. REMAP="UN--Under"If MOREINFO="NONE"options is passed as DBNOWAITONE, MOREINFO="NONE"dbregwatch returns immediately. The DBPROCESS connection will receive an asynchronous notification when the registered procedure executes. The connection will receive only a single notification, even if the registered procedure executes multiple times. REMAP="UN--Under"If MOREINFO="NONE"options is passed as DBNOWAITALL, MOREINFO="NONE"dbregwatch returns immediately. The DBPROCESS connection will receive an asynchronous notification when the registered procedure executes. The connection will continue to receive notifications, one for each execution of the registered procedure, until it informs Open Server that it no longer wishes to receive them. ReturnsREMAP="BO--Body"SUCCEED, DBNOPROC, or FAIL. REMAP="BO--Body"MOREINFO="NONE"dbregwatch returns FAIL if no handler is installed for the registered procedure. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbregwatch informs Open Server that a DBPROCESS connection should be notified when a particular registered procedure executes. Because a notification procedure is simply a special type of registered procedure, MOREINFO="NONE"dbregwatch also informs Open Server that a DBPROCESS connection should be notified when a particular notification procedure executes. The connection can request to be notified synchronously or asynchronously: MARK="DASH" REMAP="BS--BulletSub"To request synchronous notification, an application passes options as DBWAIT in its call to MOREINFO="NONE"dbregwatch. In this case, MOREINFO="NONE"dbregwatch will not return until the DBPROCESS connection reads the notification that the registered procedure has executed. Open Server will send only a single notification as the result of a synchronous notification request. If the registered procedure executes a second time, after the synchronous request has been satisfied, the client will not receive a second notification, unless another notification request is made. To request asynchronous notification, an application passes options as DBNOWAITONE or DBNOWAITALL in its call to MOREINFO="NONE"dbregwatch. In this case, MOREINFO="NONE"dbregwatch returns immediately. A return code of SUCCEED indicates that Open Server has accepted the request. If options is DBNOWAITONE, Open Server will send only a single notification, even if the registered procedure executes multiple times. If options is DBNOWAITALL, Open Server will continue to send a notification every time the registered procedure executes, until it is informed, via MOREINFO="NONE"dbregnowatch, that the client no longer wishes to receive them. A DBPROCESS connection may be idle, sending commands, reading results, or idle with results pending when an asynchronous registered procedure notification arrives. MARK="DASH" REMAP="BS--BulletSub"If the DBPROCESS connection is idle, it is necessary for the application to call MOREINFO="NONE"dbpoll to enable the connection to read the notification. If a handler for the notification has been installed, it will be called before MOREINFO="NONE"dbpoll returns. If the DBPROCESS connection is sending commands, the notification is read and the notification handler called during MOREINFO="NONE"dbsqlexec or MOREINFO="NONE"dbsqlok. After the notification handler returns, flow of control continues normally. If the DBPROCESS connection is reading results, the notification is read and the notification handler called either in MOREINFO="NONE"dbresults or MOREINFO="NONE"dbnextrow. After the notification handler returns, flow of control continues normally. If the DBPROCESS connection is idle with results pending, the notification is not read until all results in the stream up to the notification have been read and processed by the connection. An application must install a handler to process the registered procedure notification before calling MOREINFO="NONE"dbregwatch. If no handler is installed, MOREINFO="NONE"dbregwatch returns FAIL. An application can install a notification handler via MOREINFO="NONE"dbreghandle. REMAP="UN--Under"If the handler is de-installed after the application calls MOREINFO="NONE"dbregwatch but before the registered procedure notification is received, DB-Library/C raises an error when the notification is received. If the procedure referenced by procedure_name is not defined in Open Server, MOREINFO="NONE"dbregwatch returns DBNOPROC. An application can obtain a list of procedures currently registered in Open Server via MOREINFO="NONE"dbreglist. An application can obtain a list of registered procedures it is watching for via MOREINFO="NONE"dbregwatchlist. This is an example of making a synchronous notification request: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"DBPROCESS   *dbproc; DBINT       handlerfunc; DBINT       ret; REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* ** The registered procedure is defined in Open** Server as: **      shutdown   msg_param   varchar(255) */ REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* ** First install the handler for this registered** procedure: */ dbreghandle(dbproc, "shutdown", DBNULLTERM,    handlerfunc); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* Make the notification request and wait: */ ret = dbregwatch(dbproc, "shutdown", DBNULLTERM,    DBWAIT); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"if (ret == FAIL) {     fprintf (stderr, "ERROR:  dbregwatch() \         failed!\n"); } else if (ret == DBNOPROC) {     fprintf (stderr, "ERROR: procedure shutdown \         not defined.\n"); } else {     /*     ** The registered procedure notification has     ** been returned, and our registered     ** procedure handler has already been called.     */ } This is an example of making an asynchronous notification request: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"DBPROCESS   *dbproc; DBINT       handlerfunc; DBINT       ret; REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* ** The registered procedure is defined in Open** Server as: **     shutdown   msg_param   varchar(255) */ REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* ** First install the handler for this registered** procedure: */ dbreghandle(dbproc, "shutdown", DBNULLTERM,    handlerfunc); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* Make the asynchronous notification request: */ ret = dbregwatch(dbproc, "shutdown", DBNULLTERM,    DBNOWAITALL); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"if (ret == FAIL) {     fprintf (stderr, "ERROR:  dbregwatch() \         failed!\n"); } else if (ret == DBNOPROC) {     fprintf (stderr, "ERROR: procedure shutdown \         not defined.\n"); } REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/*  ** Since we are making use of the asychronous ** registered procedure notification mechanism, ** the application can continue doing other work ** while waiting for the notification.  All we ** have to do is call dbpoll() once in a while to** read the registered procedure notification ** when it arrives. */ REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"while (1) {     /* Have dbpoll() block for one second */     dbpoll (NULL, 1000, NULL, &ret); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /*     ** If we got the notification, then exit     ** the loop     */     if (ret == DBNOTIFICATION)         break; REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /*  Handle other program tasks here */ } See AlsoREMAP="BO--Body"LINKEND="X61111"dbregexec
, LINKEND="X63607"dbregparam
, LINKEND="X77038"dbreglist
, LINKEND="X71568"dbregwatchlist
, LINKEND="X95291"dbregnowatch
, LINKEND="X45215"dbpoll
ID="IN5610-6121153"dbregwatch
 ID="IN5614-9124154"dbregwatchlist
ID="IN5620-9124155"Registered procedurelisting requested notifications
ID="IN5652-9124156"Listing requested registered procedure notifications
ID="IN5613-9124157"Notificationsregistered procedure:listing
ID="IN5620-9124158"Notification requestlistingID="X71568"dbregwatchlist
Return a list of registered procedures that a DBPROCESS is watching for. FORMAT="LINESPECIFIC"RETCODE dbregwatchlist(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and server. ReturnsREMAP="BO--Body"SUCCEED or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbregwatchlist returns a list of registered procedures that a DBPROCESS connection is watching for. Because a notification procedure is simply a special type of registered procedure, the list returned by MOREINFO="NONE"dbregwatchlist will include notification procedures. The list of registered procedures is returned as rows which an application must explicitly process after calling MOREINFO="NONE"dbregwatchlist. Each row represents the name of a single registered procedure for which the DBPROCESS has requested notification. A row contains a single column of type SYBVARCHAR. The following code fragment illustrates how MOREINFO="NONE"dbregwatchlist might be used in an application: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc; DBCHAR       *procedurename; DBINT        ret; REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* Request the list of procedures */ if( (ret = dbregwatchlist(dbproc)) == FAIL) {     /* Handle failure here */ } dbresults(dbproc); while( dbnextrow(dbproc) != NO_MORE_ROWS ) {     procedurename = (DBCHAR *)dbdata(dbproc, 1);     procedurename[dbdatlen(dbproc, 1)] = '\0'; REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    fprintf(stdout, "we're waiting for \         procedure '%s'.\n", procedurename); } /* All done */ See AlsoREMAP="BO--Body"LINKEND="X44024"dbregwatch
, LINKEND="X35104"dbresults
, LINKEND="X10726"dbnextrow
ID="IN5714-12128165"dbregwatchlist
 ID="IN579-15131166"dbresultsID="X35104"dbresultsID="IN587-15132168"Resultssetting up for next query
ID="IN588-15132169"Commandssetting up results for next
ID="IN5815-15132170"Command batchessetting results for next command
Set up the results of the next query. FORMAT="LINESPECIFIC"RETCODE dbresults(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and server. ReturnsREMAP="BO--Body"SUCCEED, FAIL or NO_MORE_RESULTS. MOREINFO="NONE"dbresults returns NO_MORE_RESULTS if all commands in the buffer have already been processed. The most common reason for failing is a run-time error, such as a database permission violation. REMAP="BO--Body"The number of commands in the command buffer determines whether MOREINFO="NONE"dbsqlexec or MOREINFO="NONE"dbresults traps a run-time error. If the buffer contains only a single command, a run-time error will cause MOREINFO="NONE"dbsqlexec to fail. If the command buffer contains multiple commands, a run-time error will not cause MOREINFO="NONE"dbsqlexec to fail. Instead, the MOREINFO="NONE"dbresults call that processes the command causing the run-time error will fail. REMAP="BO--Body"The situation is a bit more complicated for run-time errors and stored procedures. A run-time error on an MOREINFO="NONE"execute command may cause MOREINFO="NONE"dbresults to fail, in accordance with the rule given in the previous paragraph. A run-time error on a statement inside a stored procedure will not cause MOREINFO="NONE"dbresults to fail, however. For example, if the stored procedure contains an MOREINFO="NONE"insert statement and the user does not have insert permission on the database table, the MOREINFO="NONE"insert statement will fail, but MOREINFO="NONE"dbresults will still return SUCCEED. To check for run-time errors inside stored procedures, use the MOREINFO="NONE"dbretstatus routine to look at the procedure's return status, and trap relevant server messages inside your message handler. CommentsMARK="BULL" REMAP="BU--Bullet"This routine sets up the next command in the command batch for processing. The application program calls it after MOREINFO="NONE"dbsqlexec or MOREINFO="NONE"dbsqlok returns SUCCEED. The first call to MOREINFO="NONE"dbresults will always return either SUCCEED or NO_MORE_RESULTS if the call to MOREINFO="NONE"dbsqlexec or MOREINFO="NONE"dbsqlok has returned SUCCEED. Once MOREINFO="NONE"dbresults returns SUCCEED, the application typically processes any result rows with MOREINFO="NONE"dbnextrow. If a command batch contains only a single command, and that command does not return rows, for example a "use database" command, a DB-Library/C application does not have to call MOREINFO="NONE"dbresults to process the results of the command. However, if the command batch contains more than one command, a DB-Library/C application must call MOREINFO="NONE"dbresults once for every command in the batch, whether or not the command returns rows. REMAP="UN--Under"MOREINFO="NONE"dbresults must also be called at least once for any stored procedure executed in a command batch, whether or not the stored procedure returns rows. If the stored procedure contains more than one Transact-SQL MOREINFO="NONE"select, then MOREINFO="NONE"dbresults must be called once for each MOREINFO="NONE"select. REMAP="UN--Under"To ensure that MOREINFO="NONE"dbresults is called the correct number of times, it is strongly recommended that MOREINFO="NONE"dbresults always be called in a loop that terminates when MOREINFO="NONE"dbresults returns NO_MORE_RESULTS. All Transact-SQL commands are considered commands by MOREINFO="NONE"dbresults. For a list of Transact-SQL commands, see the  SQL Server Reference Manual. To cancel the remaining results from the command batch (and eliminate the need to continue calling MOREINFO="NONE"dbresults until it returns NO_MORE_RESULTS), call MOREINFO="NONE"dbcancel. To determine whether a particular command is one that returns rows and needs results processing with MOREINFO="NONE"dbnextrow, call MOREINFO="NONE"DBROWS after the MOREINFO="NONE"dbresults call. The typical sequence of calls for using MOREINFO="NONE"dbresults with MOREINFO="NONE"dbsqlexec is: REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"DBINT         xvariable; DBCHAR        yvariable[10]; RETCODE       return_code; REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"/* Read the query into the command buffer */ dbcmd(dbproc, "select x = 100, y = 'hello'"); REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"/* Send the query to SQL Server */ dbsqlexec(dbproc); REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"/* ** Get ready to process the results of the query. ** Note that dbresults is called in a loop even through** only a single set of results is expected.  This is ** simply because it is good programming practice to  ** always code dbresults in a loop. */ REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"while ((return_code =dbresults(dbproc)!=     NO_MORE_RESULTS){     if ((return_code == SUCCEED) && (DBROWS(dbproc)        == SUCCEED))     {         /* Bind column data to program variables */         dbbind(dbproc, 1, INTBIND, (DBINT) 0,             (BYTE *) &xvariable);         dbbind(dbproc, 2, STRINGBIND, (DBINT) 0,            yvariable); REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"        /* Now process each row */         while (dbnextrow(dbproc) != NO_MORE_ROWS)         {             C-code to print or process row data         }     } } REMAP="UN--Under"Example 1 of the on-line example programs shows how to use MOREINFO="NONE"dbresults to process a multi-query command batch. To manage multiple input data streams efficiently, an application can confirm that unread bytes are available, either in the DB-Library network buffer or in the network itself. The application can either: MARK="DASH" REMAP="BS--BulletSub"(For UNIX or AOS/VS only.) Call MOREINFO="NONE"DBRBUF to test whether bytes remain in the network buffer, and call MOREINFO="NONE"DBIORDESC and the UNIX MOREINFO="NONE"select or AOS/VS equivalent to test whether bytes remain in the network itself; or (For all systems.) Call MOREINFO="NONE"dbpoll. ID="IN5822-15132175"Remote procedure callsprocessingAnother use for MOREINFO="NONE"dbresults is to process the results of a remote procedure call made with MOREINFO="NONE"dbrpcsend. See the MOREINFO="NONE"dbrpcsend manual page for details. An asynchronous version of MOREINFO="NONE"dbresults, called MOREINFO="NONE"dbresults_a, is available for VMS. See AlsoREMAP="BO--Body"LINKEND="X14206"dbbind
, LINKEND="X57019"dbcancel
, LINKEND="X10726"dbnextrow
, LINKEND="X45215"dbpoll
, LINKEND="X55434"DBRBUF (UNIX and AOS/VS only)
, LINKEND="X81070"dbresults_a (VMS only)
, LINKEND="X95390"dbretstatus
, LINKEND="X87634"DBROWS
, LINKEND="X71145"dbrpcsend
, LINKEND="X41234"dbsqlexec
, LINKEND="X21206"dbsqlok
ID="IN589-18135177"dbresults
 ID="IN5817-21138178"dbresults_a (VMS)ID="X81070"dbresults_a  (VMS only)ID="IN597-21139180"Resultssetting up for next query:asynchronous (VMS)
ID="IN598-21139181"Commandssetting up results for next:asynchronous (VMS)
ID="IN5915-21139182"Command batchessetting results for next command:asynchronous (VMS)
Set up the results of the next query. FORMAT="LINESPECIFIC"RETCODE dbresults_a(dbproc, final_result, ast_proc,                     ast_param)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"RETCODE       *final_result;FORMAT="LINESPECIFIC"void          (*ast_proc)();FORMAT="LINESPECIFIC"BYTE          *ast_param;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and server. final_result - A pointer to a RETCODE which is set to SUCCEED or FAIL if MOREINFO="NONE"dbresults_a returns SUCCEED. *final_result will be set to SUCCEED if the server determines that the current command is successful. The most common reason that *final_result gets set to FAIL is a run-time error, such as a database permission violation. REMAP="UN--Under"The number of commands in the command buffer determines whether MOREINFO="NONE"dbsqlexec or MOREINFO="NONE"dbresults_a traps a run-time error. If the buffer contains only a single command, a run-time error will cause MOREINFO="NONE"dbsqlexec to fail. If the command buffer contains multiple commands, a run-time error will not cause MOREINFO="NONE"dbsqlexec to fail. Instead, DB-Library will return FAIL in the *final_result of the MOREINFO="NONE"dbresults_a call that processes the command causing the run-time error. REMAP="UN--Under"The situation is a bit more complicated for run-time errors and stored procedures. A run-time error on an MOREINFO="NONE"execute command may set *final_result to FAIL, in accordance with the rule given in the previous paragraph. A run-time error on a statement inside a stored procedure will not set *final_result to FAIL, however. For example, if the stored procedure contains an MOREINFO="NONE"insert statement and the user does not have insert permission on the database table, the MOREINFO="NONE"insert statement will fail, but *final_result will still be set to SUCCEED. To check for run-time errors inside stored procedures, use the MOREINFO="NONE"dbretstatus routine to look at the procedure's return status, and trap relevant server messages inside your message handler. ast_proc - A pointer to a user-supplied routine that will be queued when the success of the current command is finally determined by the server. *final_result will always be set before this procedure is invoked. ast_param - A generic BYTE pointer that will be passed to the user-supplied ast_proc(). ast_param allows the user to pass any parameter or structure to the ast_proc routine. CommentsID="IN5927-23141186"Asynchronous routines (VMS)dbresults_aMARK="BULL" REMAP="BU--Bullet"This routine is the asynchronous version of MOREINFO="NONE"dbresults. This routine sets up the next command in the command batch for processing. The application program calls it after MOREINFO="NONE"dbsqlexec or MOREINFO="NONE"dbsqlexec_a returns SUCCEED. The first call to MOREINFO="NONE"dbresults_a will always return either SUCCEED or NO_MORE_RESULTS if the call to MOREINFO="NONE"dbsqlexec or MOREINFO="NONE"dbsqlexec_a has returned SUCCEED. The following three events must occur before MOREINFO="NONE"dbnextrow or MOREINFO="NONE"dbnextrow_a can be called to process any result rows: MARK="DASH" REMAP="BS--BulletSub"MOREINFO="NONE"dbresults_a must return SUCCEED. *final_result must be set to SUCCEED by DB-Library.  ast_proc() must be invoked by DB-Library. REMAP="UN--Under"If MOREINFO="NONE"dbresults_a returns FAIL or NO_MORE_RESULTS, *final_result will not be set and ast_proc() will not be invoked. If MOREINFO="NONE"dbresults_a returns SUCCEED, *final_result will be set to SUCCEED or FAIL and ast_proc() will be invoked by DB-Library. ID="IN5914-23141187"Output streamsutilizing multiple (VMS)
ID="IN5913-23141188"Input streamsutilizing multiple (VMS)MOREINFO="NONE"dbresults_a is useful in VMS applications that use multi-tasking or are otherwise trying to respond to multiple input and output streams. MOREINFO="NONE"dbresults waits until a server response is received or until the timeout period has elapsed. By substituting MOREINFO="NONE"dbresults_a for MOREINFO="NONE"dbresults, the time it takes to receive results from the server can be used to service other parts of the application. MOREINFO="NONE"dbresults_a must be called for each command in the command batch, whether or not the command returns any rows. If the application code doesn't know how many commands are in the batch (for example, if the application is designed to process ad hoc queries), it can call MOREINFO="NONE"dbresults_a until it returns NO_MORE_RESULTS. REMAP="UN--Under"MOREINFO="NONE"dbresults_a must also be called at least once for any stored procedure executed in a command batch, whether or not the stored procedure returns rows. If the stored procedure contains more than one SQL MOREINFO="NONE"select statement, then MOREINFO="NONE"dbresults_a must be called once for each MOREINFO="NONE"select. Again, the easiest way to do this is to continue to call MOREINFO="NONE"dbresults_a until it returns NO_MORE_RESULTS. To cancel the remaining results from the command batch (and eliminate the need to continue calling MOREINFO="NONE"dbresults_a until it returns NO_MORE_RESULTS), call MOREINFO="NONE"dbcancel or MOREINFO="NONE"dbcancel_a. To determine whether a particular command is one that returns rows and needs results processing with MOREINFO="NONE"dbnextrow or MOREINFO="NONE"dbnextrow_a, call MOREINFO="NONE"DBROWS after the MOREINFO="NONE"dbresults_a call. Another use for MOREINFO="NONE"dbresults_a is to process the results of a remote procedure call made with MOREINFO="NONE"dbrpcsend. See the MOREINFO="NONE"dbrpcsend manual page for details. References in this manual to the MOREINFO="NONE"dbresults routine also pertain to MOREINFO="NONE"dbresults_a. For an example that illustrates the use of MOREINFO="NONE"dbresults_a, see the on-line example programs.ReturnsREMAP="BO--Body"SUCCEED, FAIL or NO_MORE_RESULTS. MOREINFO="NONE"dbresults_a returns NO_MORE_RESULTS if all commands in the buffer have already been processed. MOREINFO="NONE"dbresults_a will return FAIL if there are still rows pending from a previous query. See AlsoREMAP="BO--Body"LINKEND="X14206"dbbind
, LINKEND="X57019"dbcancel
, LINKEND="X10726"dbnextrow
, LINKEND="X90089"dbnextrow_a (VMS only), LINKEND="X35104"dbresults
, LINKEND="X95390"dbretstatus
, LINKEND="X87634"DBROWS
, LINKEND="X41234"dbsqlexec
, LINKEND="X34208"dbsqlexec_a (VMS only)
, LINKEND="X21206"dbsqlok
, LINKEND="X70305"dbsqlok_a (VMS only)
ID="IN5917-26144191"dbresults_a (VMS)
 ID="IN599-29147192"dbretdataID="X29147"dbretdataID="IN6017-29148194"Stored proceduresreturn parameter values:getting
ID="IN6023-29148195"Return parameter valuesgetting
ID="IN6022-29148196"Remote procedure callsgetting return parameter values
Return a pointer to a return parameter value generated by a stored procedure. FORMAT="LINESPECIFIC"BYTE *dbretdata(dbproc, retnum)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"int          retnum;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and server. retnum - The number of the return parameter value of interest. The first return value is 1. Values are returned in the same order as the parameters were originally specified in the stored procedure's MOREINFO="NONE"create MOREINFO="NONE"procedure statement. (Note that this is not necessarily the same order as specified in the remote procedure call.) When specifying retnum, non-return parameters do not count. For example, if the second parameter in a stored procedure is the only return parameter, its retnum is 1, not 2. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbretdata returns a pointer to a return parameter value generated by a stored procedure. It is useful in conjunction with remote procedure calls and MOREINFO="NONE"execute statements on stored procedures. Transact-SQL stored procedures can return values for specified "return parameters." Changes made to the value of a return parameter inside the stored procedure are then available to the program that called the procedure. This is analogous to the "pass by reference" facility available in some programming languages. REMAP="UN--Under"For a parameter to function as a return parameter, it must be declared as such within the stored procedure. The MOREINFO="NONE"execute statement or remote procedure call that calls the stored procedure must also indicate that the parameter should function as a return parameter. In the case of a remote procedure call, it is the MOREINFO="NONE"dbrpcparam routine that specifies whether a parameter is a return parameter. When executing a stored procedure, the server returns any parameter values immediately after returning all other results. Therefore, the application can call MOREINFO="NONE"dbretdata only after processing the stored procedure's results by calling MOREINFO="NONE"dbresults, as well as MOREINFO="NONE"dbnextrow if appropriate. (Note that a stored procedure can generate several sets of results-one for each MOREINFO="NONE"select it contains. Before the application can call MOREINFO="NONE"dbretdata or any other routines that process return parameters, it must call MOREINFO="NONE"dbresults and MOREINFO="NONE"dbnextrow as many times as necessary to process all the results.) If the stored procedure is invoked with a remote procedure call, the return parameter values are automatically available to the application. If, on the other hand, the stored procedure is invoked with an MOREINFO="NONE"execute statement, the return parameter values are available only if the command batch containing the MOREINFO="NONE"execute statement uses local variables, not constants, for the return parameters. Other routines return additional information about return parameter values: MARK="DASH" REMAP="BS--BulletSub"MOREINFO="NONE"dbnumrets returns the total number of return parameter values. MOREINFO="NONE"dbretlen returns the length of a parameter value. MOREINFO="NONE"dbretname returns the name of a parameter value. MOREINFO="NONE"dbrettype returns the datatype of a parameter value. For an example of this routine, see the on-line example programs.ReturnsREMAP="BO--Body"A pointer to the specified return value. If retnum is out of range, MOREINFO="NONE"dbretdata returns NULL. To determine whether the data really has a null value (and retnum is not merely out of range), check for a return of 0 from MOREINFO="NONE"dbretlen. See AlsoREMAP="BO--Body"LINKEND="X10726"dbnextrow
, LINKEND="X32989"dbnumrets
, LINKEND="X35104"dbresults
, LINKEND="X78900"dbretlen
, LINKEND="X24047"dbretname
, LINKEND="X70606"dbrettype
, LINKEND="X47823"dbrpcinit
, LINKEND="X50365"dbrpcparam
ID="IN609-32151202"dbretdata
 ID="IN608-35154203"dbretlenID="X78900"dbretlenID="IN6117-35155205"Stored proceduresreturn parameter values:getting length of
ID="IN6123-35155206"Return parameter valuesgetting length of
ID="IN6122-35155207"Remote procedure callsgetting length of return parameter value
Determine the length of a return parameter value generated by a stored procedure. FORMAT="LINESPECIFIC"DBINT dbretlen(dbproc, retnum)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"int          retnum;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and server. retnum - The number of the return parameter value of interest. The first return value is 1. Values are returned in the same order as the parameters were originally specified in the stored procedure's MOREINFO="NONE"create MOREINFO="NONE"procedure statement. (Note that this is not necessarily the same order as specified in the remote procedure call.) When specifying retnum, non-return parameters do not count. For example, if the second parameter in a stored procedure is the only return parameter, its retnum is 1, not 2. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbretlen returns the length of a particular return parameter value generated by a stored procedure. It is useful in conjunction with remote procedure calls and MOREINFO="NONE"execute statements on stored procedures. Transact-SQL stored procedures can return values for specified "return parameters." Changes made to the value of a return parameter inside the stored procedure are then available to the program that called the procedure. This is analogous to the "pass by reference" facility available in some programming languages. REMAP="UN--Under"For a parameter to function as a return parameter, it must be declared as such within the stored procedure. The MOREINFO="NONE"execute statement or remote procedure call that calls the stored procedure must also indicate that the parameter should function as a return parameter. In the case of a remote procedure call, it is the MOREINFO="NONE"dbrpcparam routine that specifies whether a parameter is a return parameter. When executing a stored procedure, the server returns any parameter values immediately after returning all other results. Therefore, the application can call MOREINFO="NONE"dbretlen only after processing the stored procedure's results by calling MOREINFO="NONE"dbresults, as well as MOREINFO="NONE"dbnextrow if appropriate. (Note that a stored procedure can generate several sets of results-one for each MOREINFO="NONE"select it contains. Before the application can call MOREINFO="NONE"dbretlen or any other routines that process return parameters, it must call MOREINFO="NONE"dbresults and MOREINFO="NONE"dbnextrow as many times as necessary to process all the results.) If the stored procedure is invoked with a remote procedure call, the return parameter values are automatically available to the application. If, on the other hand, the stored procedure is invoked with an MOREINFO="NONE"execute statement, the return parameter values are available only if the command batch containing the MOREINFO="NONE"execute statement uses local variables, not constants, for the return parameters. Other routines return additional information about return parameter values: MARK="DASH" REMAP="BS--BulletSub"MOREINFO="NONE"dbnumrets returns the total number of return parameter values. MOREINFO="NONE"dbretdata returns a pointer to a parameter value. MOREINFO="NONE"dbretname returns the name of a parameter value. MOREINFO="NONE"dbrettype returns the datatype of a parameter value. For an example of this routine, see Example 8  of the on-line example programs.ReturnsREMAP="BO--Body"The length of the specified return parameter value. If retnum is out of range, MOREINFO="NONE"dbretlen returns -1. If the return value is null, MOREINFO="NONE"dbretlen returns 0. See AlsoREMAP="BO--Body"LINKEND="X10726"dbnextrow
, LINKEND="X32989"dbnumrets
, LINKEND="X35104"dbresults
, LINKEND="X29147"dbretdata
, LINKEND="X24047"dbretname
, LINKEND="X70606"dbrettype
, LINKEND="X47823"dbrpcinit
, LINKEND="X50365"dbrpcparam
ID="IN618-38158213"dbretlen
 ID="IN619-41161214"dbretnameID="X24047"dbretnameID="IN6217-41162216"Stored proceduresreturn parameter values:getting parameter name
ID="IN6223-41162217"Return parameter valuesgetting parameter name
ID="IN6222-41162218"Remote procedure callsgetting name of return parameter value
Determine the name of the stored procedure parameter associated with a particular return parameter value. FORMAT="LINESPECIFIC"char *dbretname(dbproc, retnum)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"int           retnum;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and server. retnum - The number of the return parameter value of interest. The first return value is 1. Values are returned in the same order as the parameters were originally specified in the stored procedure's MOREINFO="NONE"create MOREINFO="NONE"procedure statement. (Note that this is not necessarily the same order as specified in the remote procedure call.) When specifying retnum, non-return parameters do not count. For example, if the second parameter in a stored procedure is the only return parameter, its retnum is 1, not 2. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbretname returns a pointer to the null-terminated parameter name associated with a return parameter value from a stored procedure. It is useful in conjunction with remote procedure calls and MOREINFO="NONE"execute statements on stored procedures. Transact-SQL stored procedures can return values for specified "return parameters." Changes made to the value of a return parameter inside the stored procedure are then available to the program that called the procedure. This is analogous to the "pass by reference" facility available in some programming languages. REMAP="UN--Under"For a parameter to function as a return parameter, it must be declared as such within the stored procedure. The MOREINFO="NONE"execute statement or remote procedure call that calls the stored procedure must also indicate that the parameter should function as a return parameter. In the case of a remote procedure call, it is the MOREINFO="NONE"dbrpcparam routine that specifies whether a parameter is a return parameter. When executing a stored procedure, the server returns any parameter values immediately after returning all other results. Therefore, the application can call MOREINFO="NONE"dbretname only after processing the stored procedure's results by calling MOREINFO="NONE"dbresults, as well as MOREINFO="NONE"dbnextrow if appropriate. (Note that a stored procedure can generate several sets of results-one for each MOREINFO="NONE"select it contains. Before the application can call MOREINFO="NONE"dbretname or any other routines that process return parameters, it must call MOREINFO="NONE"dbresults and MOREINFO="NONE"dbnextrow as many times as necessary to process all the results.) If the stored procedure is invoked with a remote procedure call, the return parameter values are automatically available to the application. If, on the other hand, the stored procedure is invoked with an MOREINFO="NONE"execute statement, the return parameter values are available only if the command batch containing the MOREINFO="NONE"execute statement uses local variables, not constants, for the return parameters. Other routines return additional information about return parameter values: MARK="DASH" REMAP="BS--BulletSub"MOREINFO="NONE"dbnumrets returns the total number of return parameter values. MOREINFO="NONE"dbretdata returns a pointer to a parameter value. MOREINFO="NONE"dbretlen returns the length of a parameter value. MOREINFO="NONE"dbrettype returns the datatype of a parameter value. For an example of this routine, see Example 8  of the on-line example programs.ReturnsREMAP="BO--Body"A pointer to the null-terminated parameter name for the specified return value. If retnum is out of range, MOREINFO="NONE"dbretname returns NULL. See AlsoREMAP="BO--Body"LINKEND="X10726"dbnextrow
, LINKEND="X32989"dbnumrets
, LINKEND="X35104"dbresults
, LINKEND="X29147"dbretdata
, LINKEND="X78900"dbretlen
, LINKEND="X70606"dbrettype
, LINKEND="X47823"dbrpcinit
, LINKEND="X50365"dbrpcparam
ID="IN629-44165224"dbretname
 ID="IN6211-47168225"dbretstatusID="X95390"dbretstatusID="IN6317-47169227"Stored proceduresreturning status number
ID="IN6314-47169228"Status numbersStatus numbersfor current commandcurrent command
ID="IN6322-47169229"Remote procedure callsgetting status number
ID="IN638-47169230"Commandsgetting stored procedures status number
Determine the stored procedure status number returned by the current command or remote procedure call. FORMAT="LINESPECIFIC"DBINT dbretstatus(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and server. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbretstatus fetches a stored procedure's status number. All stored procedures that are run on a server version 4.0 or above return a status number. Stored procedures that complete normally return a status number of 0. For a list of return status numbers, see the  SQL Server Reference Manual. The MOREINFO="NONE"dbhasretstat routine determines whether the current Transact-SQL command or remote procedure call actually generated a return status number. Since status numbers are a feature of stored procedures, only a remote procedure call or an MOREINFO="NONE"execute command can generate a status number. When executing a stored procedure, the server returns the status number immediately after returning all other results. Therefore, the application can call MOREINFO="NONE"dbretstatus only after processing the stored procedure's results by calling MOREINFO="NONE"dbresults, as well as MOREINFO="NONE"dbnextrow if appropriate. (Note that a stored procedure can generate several sets of results-one for each MOREINFO="NONE"select it contains. Before the application can call MOREINFO="NONE"dbretstatus or MOREINFO="NONE"dbhasretstat, it must call MOREINFO="NONE"dbresults and MOREINFO="NONE"dbnextrow as many times as necessary to process all the results.) The order in which the application processes the status number and any return parameter values is unimportant. For an example of this routine, see Example 8  of the on-line example programs.ReturnsREMAP="BO--Body"The return status number for the current command. See AlsoREMAP="BO--Body"LINKEND="X23034"dbhasretstat
, LINKEND="X10726"dbnextrow
, LINKEND="X35104"dbresults
, LINKEND="X29147"dbretdata
, LINKEND="X47823"dbrpcinit
, LINKEND="X50365"dbrpcparam
, LINKEND="X71145"dbrpcsend
ID="IN6311-50172236"dbretstatus
 ID="IN639-53175237"dbrettypeID="X70606"dbrettypeID="IN6417-53176239"Stored proceduresreturn parameter values:getting datatype of
ID="IN6423-53176240"Return parameter valuesgetting datatype of
ID="IN6422-53176241"Remote procedure callsgetting return parameter value datatype
Determine the datatype of a return parameter value generated by a stored procedure. FORMAT="LINESPECIFIC"int dbrettype(dbproc, retnum)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"int          retnum;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and server. retnum - The number of the return parameter value of interest. The first return value is 1. Values are returned in the same order as the parameters were originally specified in the stored procedure's MOREINFO="NONE"create MOREINFO="NONE"procedure statement. (Note that this is not necessarily the same order as specified in the remote procedure call.) When specifying retnum, non-return parameters do not count. For example, if the second parameter in a stored procedure is the only return parameter, its retnum is 1, not 2. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbrettype returns the datatype of a return parameter value generated by a stored procedure. It is useful in conjunction with remote procedure calls and MOREINFO="NONE"execute statements on stored procedures. Transact-SQL stored procedures can return values for specified "return parameters." Changes made to the value of a return parameter inside the stored procedure are then available to the program that called the procedure. This is analogous to the "pass by reference" facility available in some programming languages. REMAP="UN--Under"For a parameter to function as a return parameter, it must be declared as such within the stored procedure. The MOREINFO="NONE"execute statement or remote procedure call that calls the stored procedure must also indicate that the parameter should function as a return parameter. In the case of a remote procedure call, it is the MOREINFO="NONE"dbrpcparam routine that specifies whether a parameter is a return parameter. When executing a stored procedure, the server returns any parameter values immediately after returning all other results. Therefore, the application can call MOREINFO="NONE"dbrettype only after processing the stored procedure's results by calling MOREINFO="NONE"dbresults, as well as MOREINFO="NONE"dbnextrow if appropriate. (Note that a stored procedure can generate several sets of results-one for each MOREINFO="NONE"select it contains. Before the application can call MOREINFO="NONE"dbrettype or any other routines that process return parameters, it must call MOREINFO="NONE"dbresults and MOREINFO="NONE"dbnextrow as many times as necessary to process all the results.) If the stored procedure is invoked with a remote procedure call, the return parameter values are automatically available to the application. If, on the other hand, the stored procedure is invoked with an MOREINFO="NONE"execute statement, the return parameter values are available only if the command batch containing the MOREINFO="NONE"execute statement uses local variables, not constants, for the return parameters. MOREINFO="NONE"dbrettype actually returns an integer token value for the datatype (SYBCHAR, SYBFLT8, etc.). To convert the token value into a readable token string, use MOREINFO="NONE"dbprtype. See the MOREINFO="NONE"dbprtype manual page for a list of all token values and their equivalent token strings. For a list of server datatypes, see the manual page for MOREINFO="NONE"types. Other routines return additional information about return parameter values: MARK="DASH" REMAP="BS--BulletSub"MOREINFO="NONE"dbnumrets returns the total number of return parameter values. MOREINFO="NONE"dbretdata returns a pointer to a parameter value. MOREINFO="NONE"dbretlen returns the length of a parameter value. MOREINFO="NONE"dbretname returns the name of a parameter value. For an example of this routine, see Example 8  of the on-line example programs.ReturnsREMAP="BO--Body"A token value for the datatype of the specified return value. REMAP="BO--Body"In a few cases, the token value returned by this routine may not correspond exactly with the column's server datatype: MARK="BULL" REMAP="BU--Bullet"SYBVARCHAR is returned as SYBCHAR. SYBVARBINARY is returned as SYBBINARY. SYBDATETIMN is returned as SYBDATETIME. SYBMONEYN is returned as SYBMONEY. SYBFLTN is returned as SYBFLT8. SYBINTN is returned as SYBINT1, SYBINT2, or SYBINT4, depending on the actual type of the SYBINTN. REMAP="BO--Body"If retnum is out of range, -1 is returned. See AlsoREMAP="BO--Body"LINKEND="X10726"dbnextrow
, LINKEND="X32989"dbnumrets
, LINKEND="X77266"dbprtype
, LINKEND="X35104"dbresults
, LINKEND="X29147"dbretdata
, LINKEND="X78900"dbretlen
, LINKEND="X24047"dbretname
, LINKEND="X47823"dbrpcinit
, LINKEND="X50365"dbrpcparam
ID="IN649-56179247"dbrettype
 ID="IN646-59182248"DBROWSID="X87634"DBROWSID="IN658-59183250"Commandsdetermining whether it returned rows
ID="IN654-59183251"Rowsdetermining whether returned
Indicate whether the current command actually returned rows. FORMAT="LINESPECIFIC"RETCODE DBROWS(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and server. CommentsMARK="BULL" REMAP="BU--Bullet"This macro determines whether the command currently being processed by MOREINFO="NONE"dbresults returned any rows. The application can call it after MOREINFO="NONE"dbresults returns SUCCEED. The application must not call DBROWS after MOREINFO="NONE"dbnextrow. The macro may return the wrong result at that time. ID="IN659-67191255"dbnextrowdbnextrowand DBROWSDBROWSThe application can use DBROWS to determine whether it needs to call MOREINFO="NONE"dbnextrow to process result rows. If DBROWS returns FAIL, the application can skip the MOREINFO="NONE"dbnextrow calls. The MOREINFO="NONE"DBCMDROW macro determines whether the current command is one that can return rows (i.e., a Transact-SQL MOREINFO="NONE"select statement or an MOREINFO="NONE"execute on a stored procedure containing a MOREINFO="NONE"select). ReturnsREMAP="BO--Body"SUCCEED or FAIL, indicating whether the current command returned rows. See AlsoREMAP="BO--Body"LINKEND="X17006"DBCMDROW
, LINKEND="X10726"dbnextrow
, LINKEND="X35104"dbresults
, LINKEND="X42749"DBROWTYPE
ID="IN656-70194258"DBROWS
 ID="IN659-73197259"DBROWTYPEID="X42749"DBROWTYPEID="IN664-73198261"Rowsreturning type of
ID="IN669-81206262"dbnextrowdbnextrowand DBROWTYPEDBROWTYPE
Return the type of the current row. FORMAT="LINESPECIFIC"STATUS DBROWTYPE(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and server. CommentsMARK="BULL" REMAP="BU--Bullet"This macro tells you the type (regular or compute) of the current row. Usually you already know this, since MOREINFO="NONE"dbnextrow also returns the row type. ReturnsREMAP="BO--Body"Three different types of values can be returned: MARK="BULL" REMAP="BU--Bullet"If the current row is a regular row, REG_ROW is returned. If the current row is a compute row, the computeid of the row is returned. (See MOREINFO="NONE"dbaltbind for information on the computeid.) If no rows have been read, or if the routine failed for any reason, NO_MORE_ROWS is returned. See AlsoREMAP="BO--Body"LINKEND="X10726"dbnextrow
 ID="IN669-84209268"DBROWTYPE
ID="IN669-87212269"dbrpcinitID="X47823"dbrpcinitID="IN6722-87213271"Remote procedure callsinitializing
Initialize a remote procedure call. FORMAT="LINESPECIFIC"RETCODE dbrpcinit(dbproc, rpcname, options)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"char         *rpcname;FORMAT="LINESPECIFIC"DBSMALLINT   options;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and the server. rpcname - A pointer to the name of the stored procedure to be invoked. options - A two-byte bitmask of RPC options. So far, the only option available is DBRPCRECOMPILE, which causes the stored procedure to be recompiled before it is executed. CommentsMARK="BULL" REMAP="BU--Bullet"An application can call a stored procedure in two ways: by executing a command buffer containing a Transact-SQL MOREINFO="NONE"execute statement or by making a remote procedure call ("RPC"). ID="IN6722-87213275"Remote procedure callsadvantages ofRemote procedure calls have a few advantages over MOREINFO="NONE"execute statements: MARK="DASH" REMAP="BS--BulletSub"An RPC passes the stored procedure's parameters in their native datatypes, in contrast to the MOREINFO="NONE"execute statement, which passes parameters as ASCII characters. Therefore, the RPC method is faster and usually more compact than the MOREINFO="NONE"execute statement, because it does not require either the application program or the server to convert between native datatypes and their ASCII equivalents. It is simpler and faster to accommodate stored procedure return parameters with an RPC, instead of an MOREINFO="NONE"execute statement. With an RPC, the return parameters are automatically available to the application. (Note, however, that a return parameter must be specified as such when it's originally added to the RPC via the MOREINFO="NONE"dbrpcparam routine.) If, on the other hand, a stored procedure is called with an MOREINFO="NONE"execute statement, the return parameter values are available only if the command batch containing the MOREINFO="NONE"execute statement uses local variables, not constants, as the return parameters. This involves additional parsing each time the command batch is executed. ID="IN6722-87213276"Remote procedure callsTo make a remote procedure call, first call MOREINFO="NONE"dbrpcinit to specify the stored procedure that's to be invoked. Then call MOREINFO="NONE"dbrpcparam once for each of the stored procedure's parameters. Finally, call MOREINFO="NONE"dbrpcsend to signify the end of the parameter list. This causes the server to begin executing the specified procedure. You can then call MOREINFO="NONE"dbsqlok, MOREINFO="NONE"dbresults, and MOREINFO="NONE"dbnextrow to process the stored procedure's results. (Note that you will need to call MOREINFO="NONE"dbresults multiple times if the stored procedure contains more than one MOREINFO="NONE"select statement.) After all of the stored procedure's results have been processed, you can call the routines that process return parameters and status numbers, such as MOREINFO="NONE"dbretdata and MOREINFO="NONE"dbretstatus. If the procedure being executed resides on a server other than the one to which the application is directly connected, commands executed within the procedure cannot be rolled back. For an example of a remote procedure call, see Example 8 in the on-line example programs.ReturnsREMAP="BO--Body"SUCCEED or FAIL. See AlsoREMAP="BO--Body"LINKEND="X10726"dbnextrow
, LINKEND="X35104"dbresults
, LINKEND="X29147"dbretdata
, LINKEND="X95390"dbretstatus
, LINKEND="X50365"dbrpcparam
, LINKEND="X71145"dbrpcsend
, LINKEND="X21206"dbsqlok
ID="IN679-90216279"dbrpcinit
 ID="IN6710-93219280"dbrpcparamID="X50365"dbrpcparamID="IN6822-93220282"Remote procedure callsadding parameters to
Add a parameter to a remote procedure call. FORMAT="LINESPECIFIC"RETCODE dbrpcparam(dbproc, paramname, status, type,                   maxlen, datalen, value)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;FORMAT="LINESPECIFIC"char         *paramname;FORMAT="LINESPECIFIC"BYTE         status;FORMAT="LINESPECIFIC"int          type;FORMAT="LINESPECIFIC"DBINT        maxlen;FORMAT="LINESPECIFIC"DBINT        datalen;FORMAT="LINESPECIFIC"BYTE         *value;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and the server. paramname - A pointer to the name of the parameter to be invoked. This name must begin with the "@" symbol, which prefixes all stored procedure parameter names. As in the Transact-SQL MOREINFO="NONE"execute statement, the name is optional. If it is not used, it should be specified as NULL. In that case, the order of the MOREINFO="NONE"dbrpcparam calls determines the parameter to which each refers. status - A one-byte bitmask of RPC-parameter options. So far, the only option available is DBRPCRETURN, which signifies that the application program would like this parameter used as a return parameter. type - The datatype of the parameter (e.g., SYBINT1, SYBCHAR, etc.). maxlen - For return parameters, this is the maximum desired byte length for the RPC parameter value returned from the stored procedure. maxlen is relevant only for values whose datatypes are not fixed in length-that is, character, text, binary, and image values. If this parameter doesn't apply (i.e., if the type is a fixed length datatype such as SYBINT2) or if you don't care about restricting the lengths of return parameters, set maxlen to -1. maxlen should also be set to -1 for parameters not designated as return parameters. datalen - The length, in bytes, of the RPC parameter to pass to the stored procedure. This length should not count any null terminator. REMAP="UN--Under"If type is SYBCHAR, SYBVARCHAR, SYBBINARY, SYBVARBINARY, SYBBOUNDARY, or SYBSENSITIVITY, datalen must be specified. Passing datalen as -1 for any of these datatypes results in the DBPROCESS referenced by dbproc being marked as dead. REMAP="UN--Under"If type is a fixed length datatype, for example, SYBINT2, pass datalen as -1.  REMAP="UN--Under"If the value of the RPC parameter is NULL, pass datalen as 0, even if type is a fixed length datatype. value - A pointer to the RPC parameter itself. If datalen is 0, this pointer will be ignored and treated as NULL. Note that DB-Library does not copy *value into its internal buffer space until the application calls MOREINFO="NONE"dbrpcsend. An application must not write over *value until after it has called MOREINFO="NONE"dbrpcsend.An application must not write over *value until after it has called MOREINFO="NONE"dbrpcsend to send the remote procedure call to the server. This is a functional change from previous versions of DB-Library.CommentsMARK="BULL" REMAP="BU--Bullet"An application can call a stored procedure in two ways: by executing a command buffer containing a Transact-SQL MOREINFO="NONE"execute statement or by making a remote procedure call ("RPC"). See the manual page for MOREINFO="NONE"dbrpcinit for a discussion of the differences between these techniques. To make a remote procedure call, first call MOREINFO="NONE"dbrpcinit to specify the stored procedure that's to be invoked. Then call MOREINFO="NONE"dbrpcparam once for each of the stored procedure's parameters. Finally, call MOREINFO="NONE"dbrpcsend to signify the end of the parameter list. This causes the server to begin executing the specified procedure. You can then call MOREINFO="NONE"dbsqlok, MOREINFO="NONE"dbresults, and MOREINFO="NONE"dbnextrow to process the stored procedure's results. (Note that you will need to call MOREINFO="NONE"dbresults multiple times if the stored procedure contains more than one MOREINFO="NONE"select statement.) After all of the stored procedure's results have been processed, you can call the routines that process return parameters and status numbers, such as MOREINFO="NONE"dbretdata and MOREINFO="NONE"dbretstatus. For parameters of type SYBCHAR, SYBVARCHAR, SYBBINARY, SYBVARBINARY, SYBBOUNDARY, and SYBSENSITIVITY, datalen must be specified. Passing datalen as -1 for any of these datatypes results in the DBPROCESS referenced by dbproc being marked as dead. If the procedure being executed resides on a server other than the one to which the application is directly connected, commands executed within the procedure cannot be rolled back. For an example of a remote procedure call, see Example 8 in the on-line example programs.ReturnsREMAP="BO--Body"SUCCEED or FAIL. See AlsoREMAP="BO--Body"LINKEND="X10726"dbnextrow
, LINKEND="X35104"dbresults
, LINKEND="X29147"dbretdata
, LINKEND="X95390"dbretstatus
, LINKEND="X47823"dbrpcinit
, LINKEND="X71145"dbrpcsend
, LINKEND="X21206"dbsqlok
ID="IN6810-96223288"dbrpcparam
 ID="IN689-99226289"dbrpcsendID="X71145"dbrpcsendID="IN6922-99227291"Remote procedure callssignaling end of
Signal the end of a remote procedure call. FORMAT="LINESPECIFIC"RETCODE dbrpcsend(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and the server. ReturnsREMAP="BO--Body"SUCCEED or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"An application can call a stored procedure in two ways: by executing a command buffer containing a Transact-SQL MOREINFO="NONE"execute statement or by making a remote procedure call ("RPC"). See the manual page for MOREINFO="NONE"dbrpcinit for a discussion of the differences between these techniques. To make a remote procedure call, first call MOREINFO="NONE"dbrpcinit to specify the stored procedure that's to be invoked. Then call MOREINFO="NONE"dbrpcparam once for each of the stored procedure's parameters. Finally, call MOREINFO="NONE"dbrpcsend to signify the end of the parameter list. This causes the server to begin executing the specified procedure. You can then call MOREINFO="NONE"dbsqlok, MOREINFO="NONE"dbresults, and MOREINFO="NONE"dbnextrow to process the stored procedure's results. (Note that you will need to call MOREINFO="NONE"dbresults multiple times if the stored procedure contains more than one MOREINFO="NONE"select statement.) After all of the stored procedure's results have been processed you can call the routines that process return parameters and status numbers, such as MOREINFO="NONE"dbretdata and MOREINFO="NONE"dbretstatus. If the procedure being executed resides on a server other than the one to which the application is directly connected, commands executed within the procedure cannot be rolled back. For an example of a remote procedure call, see Example 8 in the on-line example programs.See AlsoREMAP="BO--Body"LINKEND="X10726"dbnextrow
, LINKEND="X35104"dbresults
, LINKEND="X29147"dbretdata
, LINKEND="X95390"dbretstatus
, LINKEND="X47823"dbrpcinit
, LINKEND="X50365"dbrpcparam
, LINKEND="X21206"dbsqlok
ID="IN699-102230297"dbrpcsend
 ID="IN698-105233298"dbrpwclrID="X56457"dbrpwclr
Clear all remote passwords from the LOGINRECID="IN7022-105234300"Remote procedure callsclearing passwords
ID="IN709-105234301"Passwordsremote:clearing
ID="IN7018-107236302"LOGINREC structureclearing all remote passwords
 structure. FORMAT="LINESPECIFIC"void dbrpwclr(loginrec)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"LOGINREC     *loginrec;ParametersREMAP="RI--RefIndent"loginrec - A pointer to a LOGINREC structure. This pointer will serve as an argument to MOREINFO="NONE"dbopen. You can get one by calling MOREINFO="NONE"dblogin. ReturnsREMAP="BO--Body"None. CommentsMARK="BULL" REMAP="BU--Bullet"A Transact-SQL command batch or stored procedure running on one server may call a stored procedure located on another server. To accomplish this server-to-server communication, the first server, connected to the application through MOREINFO="NONE"dbopen, actually logs into the second, remote server. REMAP="UN--Under"MOREINFO="NONE"dbrpwset allows the application to specify the password to be used when the first server attempts to call the stored procedure on the remote server. Multiple passwords may be specified, one for each server, that the first server might need to log into. A single LOGINREC can be used repeatedly, in successive MOREINFO="NONE"dbopen calls to different servers. MOREINFO="NONE"dbrpwclr allows the application to remove any remote password information currently in the LOGINREC, so that successive calls to MOREINFO="NONE"dbopen can contain different remote password information (specified with MOREINFO="NONE"dbrpwset). See AlsoREMAP="BO--Body"LINKEND="X88162"dblogin
, LINKEND="X42139"dbopen
, LINKEND="X58569"dbrpwset
, LINKEND="X75775"DBSETLAPP
, LINKEND="X47887"DBSETLHOST
, LINKEND="X60994"DBSETLPWD
, LINKEND="X77719"DBSETLUSER
ID="IN708-110239308"dbrpwclr
 ID="IN708-113242309"dbrpwsetID="X58569"dbrpwset
Add a remote password to the LOGINRECID="IN7122-113243311"Remote procedure callsadding passwords for
ID="IN719-113243312"Passwordsremote:adding
ID="IN7118-115245313"LOGINREC structureadding remote passwords
 structure. FORMAT="LINESPECIFIC"RETCODE dbrpwset(loginrec, srvname, password, pwlen)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"LOGINREC     *loginrec;FORMAT="LINESPECIFIC"char         *srvname;FORMAT="LINESPECIFIC"char         *password;FORMAT="LINESPECIFIC"int          pwlen;ParametersREMAP="RI--RefIndent"loginrec - A pointer to a LOGINREC structure. This pointer will serve as an argument to MOREINFO="NONE"dbopen. You can get one by calling MOREINFO="NONE"dblogin. srvname - The name of a server. A server's name is stored in the srvname column of its sysservers system table. When the first server calls a stored procedure located on the server designated by srvname, it will use the specified password to log in. If srvname is NULL, the specified password will be considered a "universal" password, to be used with any server that does not have a password explicitly specified for it. password - The password which the first server will use to log into the specified server. pwlen - The length of the password in bytes. ReturnsREMAP="BO--Body"SUCCEED or FAIL. This routine may fail if the addition of the specified password would overflow the LOGINREC's remote password buffer. (The remote password buffer is 255 bytes long. Each password's entry in the buffer consists of the password itself, the associated server name, and two extra bytes.) CommentsMARK="BULL" REMAP="BU--Bullet"A Transact-SQL command batch or stored procedure running on one server may call a stored procedure located on another server. To accomplish this server-to-server communication, the first server, connected to the application through MOREINFO="NONE"dbopen, actually logs into the second, remote server and performs a remote procedure call. REMAP="UN--Under"MOREINFO="NONE"dbrpwset allows the application to specify the password to be used when the first server attempts to call the stored procedure on the remote server. Multiple passwords may be specified, one for each server that the first server might need to log into. If the application has not specified a remote password for a particular server the password defaults to the one set with MOREINFO="NONE"DBSETLPWD (or a null value, if MOREINFO="NONE"DBSETLPWD has not been called). This behavior may be fine if the application's user has the same password on multiple server MOREINFO="NONE"dbrpwclr clears all remote passwords from the LOGINREC. See AlsoREMAP="BO--Body"LINKEND="X88162"dblogin
, LINKEND="X42139"dbopen
, LINKEND="X56457"dbrpwclr
, LINKEND="X75775"DBSETLAPP
, LINKEND="X47887"DBSETLHOST
, LINKEND="X60994"DBSETLPWD
, LINKEND="X77719"DBSETLUSER
ID="IN718-118248319"dbrpwset
 REMAP="BO--Body"dbsafestrID="IN43159753"Quotation marksQuotation marksand character stringscharacter strings
ID="IN43179754"Character stringsCharacter stringsand quotation marksquotation marks
Double the quotes in a character string. FORMAT="LINESPECIFIC"RETCODE dbsafestr(dbproc, src, srclen, dest,                 destlen, quotetype)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS      *dbproc;FORMAT="LINESPECIFIC"char           *src;FORMAT="LINESPECIFIC"DBINT          srclen;FORMAT="LINESPECIFIC"char           *dest;FORMAT="LINESPECIFIC"DBINT          destlen;FORMAT="LINESPECIFIC"int            quotetype;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. src - A pointer to the original string. srclen - The length of src, in bytes. If srclen is -1, src is assumed to be null terminated. dest - A pointer to a programmer-supplied buffer to contain the resulting string. dest must be large enough for the resulting string plus a null terminator. destlen - The length of the programmer-supplied buffer to contain the resulting string. If destlen is -1, dest is assumed to be large enough to hold the resulting string. quotetype - The type of quotes to double. The following table lists the possible values for quotetype: TOCENTRY="1"LBL="Table 2-33: "Values for quotetypeCOLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="90*"COLNAME="C2" COLWIDTH="243*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Value of 
quotetype:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"dbsafestr:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBSINGLECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Doubles all single quotes (') in src. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDOUBLECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Doubles all double quotes (") in src. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBBOTHCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Doubles all single and double quotes in src. ReturnsREMAP="BO--Body"SUCCEED or FAIL. MOREINFO="NONE"dbsafestr fails if the resulting string is too large for dest, or if an invalid quotetype is specified. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbsafestr doubles the single and/or double quotes found in a character string. This is useful when specifying literal quotes within a character string. See AlsoREMAP="BO--Body"LINKEND="X41151"dbcmd
, LINKEND="X29834"dbfcmd
ID="IN43994810"dbsafestr
 ID="X13587"dbsechandleID="IN4411911211"dbsechandle
ID="IN4414911213"Logins, secure
ID="IN4413911214"Secure loginsinstalling user function for
Install user functions to handle secure logins.FORMAT="LINESPECIFIC"RETCODE *dbsechandle(type, handler)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBINT         type;FORMAT="LINESPECIFIC"INTFUNCPTR    (*handler)();ParametersREMAP="RI--RefIndent"type - An integer variable which has been set to one of the following symbolic values:TOCENTRY="1"LBL="Table 2-34: "Values for type (MOREINFO="NONE"dbsechandle)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="120*"COLNAME="C2" COLWIDTH="239*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Value of type:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"dbsechandle:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBENCRYPTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Installs a function to handle password encryption.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBLABELSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Installs a function to handle login security labels.handler - A pointer to the user function that DB-Library will call whenever the corresponding type of secure login needs to be handled. REMAP="UN--Under"If handler is NULL and type is DBENCRYPT, DB-Library will use its default encryption handler.REMAP="UN--Under"If handler is NULL and type is DBLABELS, MOREINFO="NONE"dbsechandle de-installs any currently-installed label handler.ReturnsREMAP="BO--Body"SUCCEED or FAIL.CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbsechandle installs user functions to handle secure logins.An application can use MOREINFO="NONE"dbsechandle to install functions to handle two types of secure logins:MARK="DASH" REMAP="BS--BulletSub"Encrypted password secure loginsIn this type of secure login, the server provides the client with a key. The client uses the key to encrypt a password, which it then returns to the server.Security label secure loginsIn this type of secure login, the server asks the client for identifying security labels, which the client then provides.ID="IN4418911219"Encryption handler installingEncrypted Password Secure LoginsMARK="BULL" REMAP="BU--Bullet"If type is DBENCRYPT, MOREINFO="NONE"dbsechandle installs the function that DB-Library will call when encrypting user passwords. DB-Library will perform password encryption only if MOREINFO="NONE"DBSETLENCRYPT has been called prior to calling MOREINFO="NONE"dbopen.DB-Library will call its default encryption handler if a user function has not been installedTypically, a user function does not need to be installed for password encryption. This is because DB-Library's default encryption handler allows an application perform password encryption when connecting to a SQL Server.A user-defined encryption handler should be installed by applications which are gateways. The encryption handler will be responsible for taking the encryption key returned by the remote server, passing it back to the client, reading the encrypted password from the client, and returning the encrypted password to DB-Library so that DB-Library can pass it on to the remote server.An encryption handler should be defined as:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"RETCODE encryption_handler(dbproc, pwd, pwdlen,    enc_key, keylen, outbuf, buflen, outlen)DBPROCESS   *dbproc;BYTE        *pwd;DBINT       pwdlen;BYTE        *enc_key;DBINT       keylen;BYTE        *outbuf;DBINT       buflen;DBINT       *outlen;REMAP="UN--Under"where:dbproc is the DBPROCESS.pwd is the user password to be encrypted.pwdlen is the length of the user's password.enc_key is the key to be used during encryption.keylen is the length of the encryption key.outbuf is a buffer in which the callback can place the encrypted password. This buffer will be allocated and freed by DB-Library.buflen is the length of the output buffer.outlen is a pointer to a DBINT. The encryption handler should set *outlen to the length of the encrypted password.An encryption handler should return SUCCEED to indicate that the password was encrypted successfully. If the encryption handler returns a value other than SUCCEED DB-Library will abort the connection attempt.ID="IN4422911220"Security label handlerinstallingSecurity Label Secure LoginsMARK="BULL" REMAP="BU--Bullet"If type is DBLABELS, MOREINFO="NONE"dbsechandle installs a function that DB-Library will call to get login security labels.DB-Library will send login security labels only if MOREINFO="NONE"DBSETLABELLED has been called prior to calling MOREINFO="NONE"dbopen.There are two ways for an application to define security labels:MARK="DASH" REMAP="BS--BulletSub"The application can call MOREINFO="NONE"dbsetsecurity one time for each label it wants to define. Most applications will use this method.The application can call MOREINFO="NONE"dbsechandle to install a user-supplied function to generate security labels. Typically, only gateway applications will use this method.REMAP="UN--Under"If an application uses both methods, the labels defined via MOREINFO="NONE"dbsetsecurity and the labels generated by the user-supplied function are sent to the server at the same time.DB-Library calls an application's label handler during the connection process, in response to a server request for login security labels. Each time it is called, the label handler returns a single label. DB-Library sends these labels, together with any labels previously defined via MOREINFO="NONE"dbsetsecurity, to the server.DB-Library does not have a default label handler. A user-defined label handler should be installed by applications which are gateways. The label handler will be responsible for reading the client's login security labels and passing them on to DB-Library so that DB-Library can pass them on to the remote server.A label handler should be defined as:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"RETCODE label_handler(dbproc, namebuf, nbuflen,    valuebuf, vbuflen, namelen, valuelen)DBPROCESS   *dbproc;DBCHAR      *namebuf;DBINT       nbuflen;DBCHAR      *valuebuf;DBINT       vbuflen;DBINT       *namelen;DBINT       *valuelen;REMAP="UN--Under"where: dbproc is the DBPROCESS. namebuf is a buffer in which the handler can place the name of the login security label. This buffer is allocated and freed by DB-Library. nbuflen is the length of the namebuf buffer. valuebuf is a buffer in which the handler can place the value of the login security label. This buffer is allocated and freed by DB-Library. vbuflen is the length of the valuebuf buffer. namelen is a pointer to a DBINT. The label handler should set *namelen to the length of the label name placed in namebuf. valuelen is a pointer to a DBINT. The label handler should set *valuelen to the length of the label value placed in valuebuf.The following table lists the return values that are legal for a security label handler. A security label handler must return one of these values:TOCENTRY="1"LBL="Table 2-35: "Return values for security label handlersCOLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="106*"COLNAME="C2" COLWIDTH="253*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Label Handler 
Return Value:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Indicates:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBMORELABELCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The label handler has set the name and value of a login 
security label. 
DB-Library should call the label handler again to get 
an additional label.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBENDLABELCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The label handler has set the name and value of a login 
security label. 

DB-Library should not call the label handler again.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBERRLABELCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A label handler error has occurred. DB-Library should 
abort the connection attempt.See AlsoREMAP="BO--Body"LINKEND="X50371"DBSETLENCRYPT
, LINKEND="X37857"DBSETLLABELED
, LINKEND="X42139"dbopen
, LINKEND="X89093"dbsetsecurity
ID="IN4414881522"dbsendpassthru
ID="IN443881523"TDSpassthrough operation
ID="IN4410881524"TDS packetsending
ID="IN4420881525"Gateway applications
ID="IN4412881526"Applicationsgateway
ID="IN4419881527"Tabular Data Streamroutines
ID="IN4421881528"Passthrough operationID="X47536"dbsendpassthru
Send a TDS packet to a server. FORMAT="LINESPECIFIC"RETCODE dbsendpassthru(dbproc, send_bufp)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"DBVOIDPTR     send_bufp;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a  particular front-end/server process.   It contains all the information that  DB-Library/C uses to manage communications and data between the  front end and the server. send_bufp - A pointer to a buffer containing the TDS packet to be sent to the server.  A packet has a default size of 512 bytes. This size may be changed via MOREINFO="NONE"DBSETLPACKET.   ReturnsREMAP="BO--Body"DB_PASSTHRU_MORE, DB_PASSTHRU_EOM, or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbsendpassthru sends a TDS (Tabular Data Stream) packet to a server. TDS is an application protocol used for the transfer of requests and request results between clients and servers. Under ordinary circumstances, a DB-Library/C application does not have to deal directly with TDS, because DB-Library/C manages the data stream. MOREINFO="NONE"dbrecvpassthru and MOREINFO="NONE"dbsendpassthru are useful in gateway applications.  When an application serves as the intermediary between two servers, it can use these routines to pass the TDS stream from one server to the other, eliminating the process of interpreting the information and re-encoding it. MOREINFO="NONE"dbsendpassthru sends a packet of bytes from the buffer to which send_bufp points.   Most commonly, send_bufp will be *recv_bufp as returned by MOREINFO="NONE"dbrecvpassthru. send_bufp may also be the address of a user-allocated buffer containing the packet to be sent. A packet has a default size of 512 bytes.  An application can change its packet size via  MOREINFO="NONE"DBSETLPACKET.  For more information  on packet sizes, see the MOREINFO="NONE"DBGETPACKET and MOREINFO="NONE"DBSETLPACKET  manual pages. MOREINFO="NONE"dbsendpassthru returns DB_PASSTHRU_EOM if the TDS packet  in the buffer is marked as EOM (End Of Message). If the TDS packet is not the last in the stream, MOREINFO="NONE"dbsendpassthru  returns DB_PASSTHRU_MORE. A DBPROCESS connection  which is used for a MOREINFO="NONE"dbsendpassthru operation cannot be used for any other DB-Library/C function until DB_PASSTHRU_EOM is received. This is a code fragment using MOREINFO="NONE"dbsendpassthru: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* ** The following code fragment illustrates the ** use of dbsendpassthru() in an Open Server ** gateway application. It will continually get ** packets from a client, and pass them through** to the remote server. ** ** The routine srv_recvpassthru() is the Open ** Server counterpart required to complete this** passthru operation. */ REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc; SRV_PROC     *srvproc; int          ret; BYTE         *packet; REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"while(1) {     ret = srv_recvpassthru(srvproc, &packet,         (int *)NULL); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    if( ret == SRV_S_PASSTHRU_FAIL )     {         fprintf(stderr, "ERROR - \             srv_recvpassthru failed in \             lang_execute.\n");         exit();     } REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /*     ** Now send the packet to the remote server     */     if( dbsendpassthru(dbproc, packet) == FAIL )     {         fprintf(stderr, "ERROR - dbsendpassthru\             failed in lang_execute.\n");         exit();     } REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /*     ** We've sent the packet, so let's see if     ** there's any more.     */     if( ret == SRV_S_PASSTHRU_MORE )         continue;     else         break; } See AlsoREMAP="BO--Body"LINKEND="X16128"dbrecvpassthru
ID="IN4514851935"dbsendpassthru
 ID="IN4513822236"dbservcharset
ID="IN4513822237"Character setreturning server
ID="IN4534822238"Returning the server character set
ID="IN4532822239"Getting the server character setID="X28915"dbservcharset
Get the name of the server character set.  FORMAT="LINESPECIFIC"char *dbservcharset(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a  particular front-end/server process.   It contains all the information that  DB-Library/C uses to manage communications and data between the front end and the server. ReturnsREMAP="BO--Body"A pointer to the null-terminated name of the  server's character set, or NULL in case of error. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbservcharset returns the name of the server's character set. DB-Library/C clients can use a different character set than the server or servers to which they are connected.  If a client and server are using different character sets, and the server supports character  translation for the client's character set, it will perform all  conversions to and from its own character set when communicating  with the client. An application can inform the server what character set it is using via MOREINFO="NONE"DBSETLCHARSET. To determine if the server is performing character set translations, an application can call MOREINFO="NONE"dbcharsetconv.  To get the name of the client character set, an application can call MOREINFO="NONE"dbgetcharset. See AlsoREMAP="BO--Body"LINKEND="X19407"dbcharsetconv
, LINKEND="X16298"dbgetcharset
, LINKEND="X49378"DBSETLCHARSET
ID="IN4613792647"dbservcharset
 ID="IN4610762948"dbsetavailID="X60441"dbsetavail
Mark a DBPROCESSID="IN4719743250"DBPROCESS structuremarking available
 as being available for general use. FORMAT="LINESPECIFIC"void dbsetavail(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. ReturnsREMAP="BO--Body"None. CommentsMARK="BULL" REMAP="BU--Bullet"This routine marks the DBPROCESS as being available for general use. Any subsequent calls to MOREINFO="NONE"DBISAVAIL will return TRUE, until some use is made of the DBPROCESS. Many DB-Library routines automatically set the DBPROCESS to "not available." This is useful when many different parts of a program are attempting to share a single DBPROCESS. See AlsoREMAP="BO--Body"LINKEND="X27527"DBISAVAIL
ID="IN4710713556"dbsetavail
 ID="IN479683857"dbsetbusyID="X90843"dbsetbusyID="IN489683959"Functionsuser-supplied:indicating server access
ID="IN4813683960"User-suppliedfunctions:indicating server access
Call a user-supplied function when DB-Library is reading from the server. FORMAT="LINESPECIFIC"void dbsetbusy(dbproc, busyfunc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"int           (*(*busyfunc)())();ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. busyfunc - The user-supplied function that DB-Library will call whenever it accesses the server. DB-Library calls busyfunc() with a single parameter-a pointer to the DBPROCESS from the MOREINFO="NONE"dbsetbusy call. REMAP="UN--Under"busyfunc() returns a pointer to a function that returns an integer. ReturnsREMAP="BO--Body"None. CommentsMARK="BULL" REMAP="BU--Bullet"This routine associates a user-supplied function with the specified dbproc. The user-supplied function will automatically be called whenever DB-Library is reading or waiting to read output from the server. For example, an application may want to print a message whenever the server is accessed. MOREINFO="NONE"dbsetbusy will cause the user-supplied function busyfunc() to be called in this case. Similarly, MOREINFO="NONE"dbsetidle may also be used to associate a user-supplied function, idlefunc(), with a dbproc.  idlefunc() will automatically be called whenever DB-Library has finished reading output from the server. The server sends result data to the application in packets of 512 bytes. (The final packet in a set of results may be less than 512 bytes.) DB-Library calls busyfunc() at the beginning of each packet and  idlefunc() at the end of each packet. If the output from the server spans multiple packets, busyfunc() and  idlefunc() will be called multiple times. Here's an example of installing and defining busyfunc() and  idlefunc(): REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"/*** busyfunc returns a pointer to a function that ** returns an integer.*/int      (*busyfunc())();void     idlefunc(); REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"int      counterfunc(); ... REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"main() {     DBPROCESS      *dbproc;     ... REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"    dbproc = dbopen(login, NULL); REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"    /*     ** Now that we have a DBPROCESS, install the     ** busy-function and the idle-function.    */     dbsetbusy(dbproc, busyfunc);     dbsetidle(dbproc, idlefunc); REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"    dbcmd(dbproc, "select * from sysdatabases");     dbcmd(dbproc, " select * from sysobjects");     dbsqlexec(dbproc); REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"    /*     ** DB-Library calls busyfunc() for the first time    ** during dbsqlexec(). Depending on the size of the    ** results, it may call busyfunc() again during     ** processing of the results.     */ REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"    while (dbresults(dbproc) != NO_MORE_RESULTS)         dbprrow(dbproc); REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"    /*    ** DB-Library calls idlefunc() each time a packet    ** of results has been received. Depending on the    ** size of the results, it may call idlefunc()    ** multiple times during processing of the results.     */     ... } REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"int (*busyfunc(dbproc))() DBPROCESS  dbproc; {     printf("Waiting for data...\n");REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"    return(counterfunc); } REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"void idlefunc(procptr, dbproc) REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"/*** idlefunc's first parameter is a pointer to a ** routine that returns an integer. This is the same** pointer that busyfunc returns.*/int           (*procptr)();REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"DBPROCESS      *dbproc; {     int       count; REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"    printf("Data is ready.\n");     count = (*procptr)(); REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"    printf ("Counterfunc has been called %d %s.\n",         count, (count == 1 ? "time" : "times")); REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"} REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"int counterfunc() {     static     int     counter = 0; REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"    return(++counter); } See AlsoREMAP="BO--Body"LINKEND="X36795"dbsetidle
ID="IN489654266"dbsetbusy
 ID="IN4815624567"dbsetdefcharset
ID="IN4813624568"Character set setting default
ID="IN4821624569"Default character setsetting for an applicationID="X46791"dbsetdefcharset
Set the default character set for an application. FORMAT="LINESPECIFIC"RETCODE dbsetdefcharset(charset)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"char         *charset;ParametersREMAP="RI--RefIndent"charset- The name of the character set to use. charset must be a NULL-terminated character string. ReturnsREMAP="BO--Body"SUCCEED or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbsetdefcharset sets an application's default character set.DB-Library uses a default character set when no DBPROCESS is available or when localization information for a DBPROCESS' character set can't be found.If an application doesn't call MOREINFO="NONE"dbsetdefcharset, its default character set is the character set of the first DBPROCESS connection opened, or iso_1 if no DBPROCESS is open.If an application plans to call both MOREINFO="NONE"dbsetdefcharset and MOREINFO="NONE"dbsetdeflang, it must call MOREINFO="NONE"dbsetdefcharset first.See AlsoREMAP="BO--Body"LINKEND="X87123"dbsetdeflang
, LINKEND="X46791"dbsetdefcharset
, LINKEND="X88162"dblogin
, LINKEND="X42139"dbopen
ID="IN4912594976"dbsetdeflang
ID="IN499594977"Languages setting defaultID="X87123"dbsetdeflangID="IN5016595079"Default languagesetting for an application
Set the default language name for an application.FORMAT="LINESPECIFIC"RETCODE dbsetdeflang(language)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"char         *language;ParametersREMAP="RI--RefIndent"language -  The name of the national language to use. language must be a NULL-terminated character string.ReturnsREMAP="BO--Body"SUCCEED or FAIL.CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbsetdeflang sets an application's default national language.DB-Library uses a default language when no DBPROCESS is available or when localization information for a DBPROCESS' language can't be found.If an application doesn't call MOREINFO="NONE"dbsetdeflang, its default language is the language of the first DBPROCESS connection opened, or us_english if no DBPROCESS is open.See AlsoREMAP="BO--Body"LINKEND="X52068"DBSETLNATLANG
ID="IN5012565385"dbsetdeflang
 ID="IN509535686"dbsetidleID="X36795"dbsetidleID="IN519535788"Functionsuser-supplied:indicating DB-Library is finished reading from the server
ID="IN5113535789"User-suppliedfunctions:indicating DB-Library is finished reading from the server
Call a user-supplied function when DB-Library is finished reading from the server. FORMAT="LINESPECIFIC"void dbsetidle(dbproc, idlefunc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"void          (*idlefunc)();ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. idlefunc - The user-supplied function that will be called by DB-Library whenever the server has finished sending data to the host. DB-Library calls  idlefunc() with two parameters-the return value from busyfunc() (a pointer to a function that returns an integer) and a pointer to the DBPROCESS from the MOREINFO="NONE"dbsetidle call. REMAP="UN--Under" idlefunc() returns void. ReturnsREMAP="BO--Body"None. CommentsMARK="BULL" REMAP="BU--Bullet"This routine associates a user-supplied function with the specified dbproc. The user-supplied function will automatically be called when DB-Library is finished reading or waiting to read a packet of output from the server. For example, an application may want to print a message whenever the server has finished sending data to the host. MOREINFO="NONE"dbsetidle will cause the user-supplied function  idlefunc() to be called in this case. Similarly, MOREINFO="NONE"dbsetbusy may also be used to associate a user-supplied function, busyfunc(), with a dbproc. busyfunc() will automatically be called whenever DB-Library is reading or waiting to read a packet of output from the server. The server sends result data to the application in packets of 512 bytes. (The final packet in a set of results may be less than 512 bytes.) DB-Library calls busyfunc() at the beginning of each packet and  idlefunc() at the end of each packet. If the output from the server spans multiple packets, busyfunc() and  idlefunc() will be called multiple times. See the MOREINFO="NONE"dbsetbusy manual page for an example of installing and defining busyfunc() and  idlefunc(). See AlsoREMAP="BO--Body"LINKEND="X90843"dbsetbusy
ID="IN519506095"dbsetidle
 ID="IN5110476396"dbsetifileID="X25800"dbsetifile
Specify the name and location of the SYBASEID="IN5215456698"interfaces filespecifying name and location
ID="IN5219436899"Network connectionsspecifying interfaces file
 interfaces file. FORMAT="LINESPECIFIC"void dbsetifile(filename)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"char         *filename;ParametersREMAP="RI--RefIndent"filename - The name of the interfaces file that gets searched during every subsequent call to MOREINFO="NONE"dbopen. If this parameter is NULL, DB-Library will revert to its default interfaces filename. ReturnsREMAP="BO--Body"None. CommentsID="IN52154170104"interfaces fileMARK="BULL" REMAP="BU--Bullet"This routine lets the application specify the name and location of the interfaces file that will be searched during every subsequent call to MOREINFO="NONE"dbopen. The interfaces file contains the name and network address of every server available on the network. If MOREINFO="NONE"dbsetifile has not been called, a call to MOREINFO="NONE"dbopen will initiate the following default behavior:  DB-Library will first attempt to use a file named "interfaces" in the directory named by the SYBASE environment variable or logical name. If SYBASE has not been set, DB-Library will attempt to use a file called "interfaces" in the home directory of the user named "sybase". For more information on the interfaces file, see the Open Client/Server Installation Guide. MOREINFO="NONE"dbsetifile, which was supported in Release 3.4 of DB-Library/C for OS/2 and MS-DOS, is no longer supported for these platforms. In MPE/XL, the interfaces file is named interfac. It is located in the pub group of the SYBASE account. See AlsoREMAP="BO--Body"LINKEND="X42139"dbopen
ID="IN52103873106"dbsetifile
 ID="IN52143576107"dbsetinterruptID="X21733"dbsetinterruptID="IN5393577109"Functionsuser-supplied:calling to handle interrupts
ID="IN53133577110"User-suppliedfunctions:calling to handle interrupts
ID="IN53183577111"Interrupt handling
Call user-supplied functions to handle interrupts while waiting on a read from the server. FORMAT="LINESPECIFIC"void dbsetinterrupt(dbproc, chkintr, hndlintr)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"int           (*chkintr)();FORMAT="LINESPECIFIC"int           (*hndlintr)();ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. chkintr - A pointer to the user function that DB-Library will call to check whether an interrupt is pending.  DB-Library calls it periodically while waiting on a read from the server. DB-Library calls chkintr() with a single parameter-a pointer to the DBPROCESS from the MOREINFO="NONE"dbsetinterrupt call. REMAP="UN--Under"chkintr() must return TRUE or FALSE. hndlintr - A pointer to the user function that DB-Library will call if an interrupt is returned. DB-Library calls hndlintr() with a single parameter-a pointer to the DBPROCESS from the MOREINFO="NONE"dbsetinterrupt call. REMAP="UN--Under"The following table lists hndlintr()'s legal return values: TOCENTRY="1"LBL="Table 2-36: "Return values for hndlintr()COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="98*"COLNAME="C2" COLWIDTH="234*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Return ValueCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To IndicateVALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"INT_EXITCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Abort the program. (Note to UNIX programmers: 
DB-Library will not leave a core file.) COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"INT_CANCELCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Cancel the current command batch. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"INT_CONTINUECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Continue to wait for the server response. ReturnsREMAP="BO--Body"None. CommentsMARK="BULL" REMAP="BU--Bullet"DB-Library does non-blocking reads from the server.  While waiting for a read from the server, it will call the chkintr() function to see if an interrupt is pending.  If there is an interrupt, hndlintr() will be called. MOREINFO="NONE"dbsetinterrupt is provided so that the programmer can substitute alternative interrupt handling for the time that the host program is waiting on reads from the server. ID="IN53223181116"sybfront.h header filesybfront.h header fileand interrupt handlinginterrupt handling
hndlintr() must return one of the interrupt returns defined in the header file sybfront.h: INT_EXIT, INT_CONTINUE, or INT_CANCEL. chkintr() must return TRUE or FALSE. You can use MOREINFO="NONE"dbcancel to cancel the current command batch. If you have set your own interrupt handler using MOREINFO="NONE"dbsetinterrupt, however, you cannot call MOREINFO="NONE"dbcancel in your interrupt handler, because this will cause output from the server to DB-Library to become out of sync. If you want to cancel the current command batch from your interrupt handler, the interrupt handler should set a flag that you can check before the next call to MOREINFO="NONE"dbresults or MOREINFO="NONE"dbnextrow. Here are example chkintr() and hndlintr() routines: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"int         chkintr(dbproc) DBPROCESS   *dbproc; {     /*     ** This routine assumes that the application     ** sets the global variable    ** "OS_interrupt_happened" upon catching     ** an interrupt via some operating system    ** facility.     */     if (OS_interrupt_happened)     {         /*         ** Clear the interrupt flag, for         ** future use.         */         OS_interrupt_happened = FALSE; REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"        return(TRUE);     }     else         return(FALSE); } REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"int         hndlintr(dbproc) DBPROCESS   *dbproc; {     char    response[10]; REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    printf("\nAn interrupt has occurred. Do you \        want to:\n\n");     printf("\t1) Abort the program\n");     printf("\t2) Cancel the curreyquery\n");     printf("\t3) Continue processing the current\        query's results\n\n");     printf("Press 1, 2, or 3, followed by the \         return key: ");     gets(response); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    switch(response[0])     {     case '1':         return(INT_EXIT);         break;     case '2':         return(INT_CANCEL);         break;     case '3':         return(INT_CONTINUE);         break;     default:         printf("Response not understood. \             Aborting program.\n");         return(INT_EXIT);         break;     } }See AlsoREMAP="BO--Body"LINKEND="X57019"dbcancel
, LINKEND="X90843"dbsetbusy
, LINKEND="X36795"dbsetidle
ID="IN53142884118"dbsetinterrupt
 ID="IN5392587119"DBSETLAPPID="X75775"DBSETLAPP
Set the application name in the LOGINRECID="IN54182390121"LOGINREC structuresetting application name in
ID="IN54172192122"Application namessetting in LOGINREC
 structure. FORMAT="LINESPECIFIC"RETCODE DBSETLAPP(loginrec, application)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"LOGINREC      *loginrec;FORMAT="LINESPECIFIC"char          *application;ParametersREMAP="RI--RefIndent"loginrec - A pointer to a LOGINREC structure, which will be passed as an argument to MOREINFO="NONE"dbopen. You can get one by calling MOREINFO="NONE"dblogin. application - The application name that will be sent to the server. It must be a null-terminated character string. The maximum length of the string, not including the null terminator, is 30 characters. ReturnsREMAP="BO--Body"SUCCEED or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"This macro sets the application field in the LOGINREC structure. For it to have any effect, it must be called before MOREINFO="NONE"dbopen. It is not necessary to call this routine. By default, the application name will be a null value.The server uses the application name in its sysprocesses table to help identify your process. If you set the application name, you will see it if you query the sysprocesses table in the master database. See AlsoREMAP="BO--Body"LINKEND="X88162"dblogin
, LINKEND="X42139"dbopen
, LINKEND="X47887"DBSETLHOST
, LINKEND="X60994"DBSETLPWD
, LINKEND="X77719"DBSETLUSER
ID="IN5491895128"DBSETLAPP
 ID="IN54131598129"DBSETLCHARSET
ID="IN54131598130"Character setsetting
ID="IN54321598131"Setting the client character set
ID="IN541813100132"LOGINREC structuresetting client character set inID="X49378"DBSETLCHARSET
Set the character set in the LOGINREC structure. FORMAT="LINESPECIFIC"RETCODE DBSETLCHARSET(loginrec, char_set)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"LOGINREC      *loginrec;FORMAT="LINESPECIFIC"DBCHAR        *char_set;ParametersREMAP="RI--RefIndent"loginrec - A pointer to a LOGINREC structure to be passed as an argument to MOREINFO="NONE"dbopen. LOGINREC structures are obtained via MOREINFO="NONE"dblogin. char_set - The name of the character set the client will use. char_set must be a null-terminated string. Default values for char_set include "iso_1" for ISO-8859-1 (most platforms), "cp850" for Code Page 850 (IBM RS6000), and "roman8" for the Roman8 character set (HP platforms). REMAP="UN--Under"To indicate that no character set conversion is desired, pass char_set as NULL. ReturnsREMAP="BO--Body"SUCCEED or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"DBSETLCHARSET sets the client character set in a LOGINREC structure.   DB-Library/C clients may use a different character set than the server or servers to which they are connected.  MOREINFO="NONE"DBSETLCHARSET is used to inform the server what character set a client is using. Because the LOGINREC is passed as a parameter in the MOREINFO="NONE"dbopen call which establishes the client's connection with a server, MOREINFO="NONE"DBSETLCHARSET must be called before MOREINFO="NONE"dbopen in order to have any effect.  The server will perform all conversions to and from its own character set when communicating with a client using a  different character set. If no conversion is desired, call MOREINFO="NONE"DBSETLCHARSET with char_set as NULL. See AlsoREMAP="BO--Body"LINKEND="X16298"dbgetcharset
, LINKEND="X88162"dblogin
, LINKEND="X42139"dbopen
ID="IN551310104139"DBSETLCHARSET
 ID="IN55137107140"DBSETLENCRYPTID="X50371"DBSETLENCRYPTID="IN56197108142"Encrypted passwords
Specify whether or not network password encryption is to be used when logging into a 10.0+ SQL Server.FORMAT="LINESPECIFIC"RETCODE DBSETLENCRYPT(loginrec, enable)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"LOGINREC      *loginrec;FORMAT="LINESPECIFIC"DBBOOL        enable;ParametersREMAP="RI--RefIndent"loginrec - A pointer to a LOGINREC structure, which will be passed as an argument to MOREINFO="NONE"dbopen. You can get one by calling MOREINFO="NONE"dblogin. enable -  A boolean value (TRUE or FALSE) specifying whether or not the server should request an encrypted password at login time.ReturnsREMAP="BO--Body"SUCCEED or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"DBSETLENCRYPT specifies whether or not network password encryption is to be used when logging into a 10.0+ SQL Server. If an application does not call MOREINFO="NONE"DBSETLENCRYPT, password encryption is not used.Network password encryption provides a protected mechanism for authenticating a user's identity. If an application specifies that network password encryption is to be used, then when the application attempts to open a connection:MARK="DASH" REMAP="BS--BulletSub"No password is sent with the initial connection request. At this time, the client indicates to the server that encryption is desired.The server replies to the connection request with an encryption key.DB-Library uses the key to encrypt the user's password and remote passwords, if any, and sends the encrypted passwords back to the server.The server uses the key to decrypt the encrypted passwords and either accepts or rejects the login attempt.If password encryption is not specified, then when an application attempts to open a connection:MARK="DASH" REMAP="BS--BulletSub"A password is included with the connection request.The server either accepts or rejects the login attempt.See AlsoREMAP="BO--Body"LINKEND="X13587"dbsechandle
ID="IN56134111148"DBSETLENCRYPT
 ID="IN56101114149"DBSETLHOSTID="X47887"DBSETLHOST
Set the host name in the LOGINRECID="IN5718-1117151"LOGINREC structuresetting host name in
ID="IN5710-3119152"Host namessetting in LOGINREC
 structure. FORMAT="LINESPECIFIC"RETCODE DBSETLHOST(loginrec, hostname)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"LOGINREC      *loginrec;FORMAT="LINESPECIFIC"char          *hostname;ParametersREMAP="RI--RefIndent"loginrec - A pointer to a LOGINREC structure, which will be passed as an argument to MOREINFO="NONE"dbopen. You can get one by calling MOREINFO="NONE"dblogin. hostname - The host name that will be sent to the server. It must be a null-terminated character string. The maximum length of the string, not including the null terminator, is 30 characters. ReturnsREMAP="BO--Body"SUCCEED or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"This macro sets the host name in the LOGINREC structure. For it to have any effect, it must be called before MOREINFO="NONE"dbopen. The host name will show up in the sysprocesses table in the master database. It is not necessary to call this routine. If it is not called, DB-Library will set the default value for the host name. This default value will generally be a version of the host machine's name provided by the operating system. See AlsoREMAP="BO--Body"LINKEND="X88162"dblogin
, LINKEND="X42139"dbopen
, LINKEND="X75775"DBSETLAPP
, LINKEND="X60994"DBSETLPWD
, LINKEND="X77719"DBSETLUSER
ID="IN5710-6122158"DBSETLHOST
 ID="IN5713-9125159"DBSETLLABELED
ID="IN5720-9125160"Login request labelssetting
ID="IN5715-9125161"Security labelssettingID="X37857"DBSETLLABELED
Set a bit to inform Secure SQL Server that login security labels will be sent at login time.FORMAT="LINESPECIFIC"RETCODE DBSETLLABELED(loginrec, enable)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"LOGINREC      *loginrec;FORMAT="LINESPECIFIC"DBBOOL        enable;ParametersREMAP="RI--RefIndent"loginrec - a pointer to a LOGINREC structure, which will be passed as an argument to MOREINFO="NONE"dbopen. You can get one by calling MOREINFO="NONE"dblogin.enable - a boolean value (TRUE or FALSE) specifying whether or not the client will send login security labels at login time.ReturnsREMAP="BO--Body"SUCCEED or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"DBSETLLABELED specifies whether login security labels will be used when logging into a Secure SQL Server. If an application does not call MOREINFO="NONE"DBSETLLABELED, no login security labels are sent to the server.There are two ways for an application to define the security labels that it will send. An application can use either, or both, of these methods:MARK="DASH" REMAP="BS--BulletSub"The application can call MOREINFO="NONE"dbsetsecurity one time for each label it wants to define.The application can call MOREINFO="NONE"dbsechandle to install a user-supplied function to generate security labels. At connection time, MOREINFO="NONE"dbopen will call the function in response to a request for security labels.REMAP="UN--Under"If an application uses both methods, the labels defined via MOREINFO="NONE"dbsetsecurity and the labels generated by the user-supplied function are sent to the server at the same time.The DB-Library version must be set to 10.0 before you can call MOREINFO="NONE"dbsetsecurity. (Set it with MOREINFO="NONE"dbsetversion.)See AlsoREMAP="BO--Body"LINKEND="X13587"dbsechandle
, LINKEND="X89093"dbsetsecurity
, LINKEND="X32027"dbsetversion
ID="IN5813-12129168"DBSETLNATLANGID="X52068"DBSETLNATLANG
Set the national language name in the LOGINRECID="IN599-14132170"Languagessetting name in LOGINREC
ID="IN5918-16134171"LOGINREC structuresetting user language name in
 structure. FORMAT="LINESPECIFIC"RETCODE DBSETLNATLANG(loginrec, language)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"LOGINREC      *loginrec;FORMAT="LINESPECIFIC"char          *language;ParametersREMAP="RI--RefIndent"loginrec - A pointer to a LOGINREC structure to be passed as an argument to MOREINFO="NONE"dbopen. LOGINREC structures are obtained via MOREINFO="NONE"dblogin. language - The name of the national language to use. language must be a NULL-terminated character string. ReturnsREMAP="BO--Body"SUCCEED or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"This macro sets the user language in the LOGINREC structure. If you wish to set a particular user language, call MOREINFO="NONE"DBSETLNATLANG before MOREINFO="NONE"dbopen. Call MOREINFO="NONE"DBSETLNATLANG only if you do not wish to use the server's default national language. See AlsoREMAP="BO--Body"LINKEND="X88162"dblogin
, LINKEND="X42139"dbopen
, LINKEND="X87123"dbsetdeflang
ID="IN5912-19137177"dbsetloginfoID="X47652"dbsetloginfo
Transfer TDS login information from a DBLOGINFO structure to a LOGINREC structure. FORMAT="LINESPECIFIC"RETCODE dbsetloginfo(loginrec, loginfo)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"LOGINREC      *login;FORMAT="LINESPECIFIC"DBLOGINFO     *loginfo;ParametersREMAP="RI--RefIndent"login - A pointer to a LOGINREC structure.  This pointer will be passed as an argument to MOREINFO="NONE"dbopen. You can get one by calling MOREINFO="NONE"dblogin. loginfo - A pointer to a DBLOGINFO structure that contains login parameter information. ReturnsREMAP="BO--Body"SUCCEED or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbsetloginfo transfers TDS login information from a DBLOGINFO structure to a LOGINREC structure.   After the information is transferred, MOREINFO="NONE"dbsetloginfo frees the DBLOGINFO structure. An application needs to call MOREINFO="NONE"dbsetloginfo only if 1) it is an Open Server gateway application and 2) it is using TDS passthrough. TDS (Tabular Data Stream) is an application protocol used for the transfer of requests and request results between clients and servers. When a client connects directly to a server, the two  programs negotiate the  TDS format they will use to send and receive data.  When a gateway application uses TDS passthrough,  the application forwards TDS packets between  the client and a remote server without examining or processing them. For this reason, the remote server and the client must agree on a TDS format to use. MOREINFO="NONE"dbsetloginfo is the third of four calls, two of them Server Library calls, that allow a client and remote server to negotiate a TDS format.  The calls, which can only be made in a SRV_CONNECT event handler, are: NUMERATION="ARABIC" REMAP="S1--StepOne" CONTINUATION="RESTARTS" INHERITNUM="IGNORE"MOREINFO="NONE"srv_getloginfo - Allocate a DBLOGINFO structure  and fill it with TDS information from a client SRV_PROC. MOREINFO="NONE"dbsetloginfo - Transfer the TDS information retrieved in step 1 from the DBLOGINFO structure  to a DB-Library/C LOGINREC structure, and then free the DBLOGINFO structure.  After the information is transferred, the application can use this LOGINREC structure in the MOREINFO="NONE"dbopen call which establishes its connection with the remote server. MOREINFO="NONE"dbgetloginfo - Transfer the remote server's response  to the client's TDS information from a DBPROCESS structure into a newly-allocated DBLOGINFO structure. MOREINFO="NONE"srv_setloginfo - Send the remote server's response,  retrieved in step 3, to the client, and then free the DBLOGINFO structure.  MARK="BULL" REMAP="BU--Bullet"This is an example of  a SRV_CONNECT handler preparing a  remote connection for TDS passthrough: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"RETCODE      connect_handler(srvproc) SRVPROC      *srvproc; {     SYBLOGINFO   *loginfo;     LOGINREC     *loginrec;     DBPROCESS    *dbproc; REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /*     ** Get the TDS login information from the     ** client SRV_PROC.     */     srv_getloginfo(srvproc, &loginfo); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /* Get a LOGINREC structure */     loginrec = dblogin(); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /*     ** Initialize the LOGINREC with the logininfo     ** from the SRV_PROC.     */     dbsetloginfo(loginrec, loginfo); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /* Connect to the remote server */     dbproc = dbopen(loginrec, REMOTE_SERVER_NAME)REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /*     ** Get the TDS login response informationfrom      ** the remote connection.     */     dbgetloginfo(dbproc, &loginfo); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /*     ** Return the login response information to     ** the SRV_PROC.     */     srv_setloginfo(srvproc, loginfo); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /* Accept the connection and return */     srv_senddone(srvproc, 0, 0, 0);     return(SRV_CONTINUE); } See AlsoREMAP="BO--Body"LINKEND="X36015"dbgetloginfo
, LINKEND="X16128"dbrecvpassthru
,  LINKEND="X47536"dbsendpassthru
ID="IN6012-22141184"dbsetloginfo
 ID="IN6014-25144185"dbsetlogintimeID="X64830"dbsetlogintime
Set the number of seconds that DB-Library waits for a server response to a request for a DBPROCESSID="IN614-25145187"Timesetting server login response
ID="IN616-25145188"Serversetting response time
ID="IN616-27147189"dbopensetting login response time
 connection. FORMAT="LINESPECIFIC"RETCODE dbsetlogintime(seconds)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"int           seconds;ParametersREMAP="RI--RefIndent"seconds - The timeout value-the number of seconds that DB-Library waits for a login response before timing out. A timeout value of 0 represents an infinite timeout period. ReturnsREMAP="BO--Body"SUCCEED or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"This routine sets the length of time in seconds that DB-Library will wait for a login response after calling MOREINFO="NONE"dbopen. The default timeout value is 60 seconds. When a connection attempt is made between a client and a server, there are two ways in which the connection can fail (assuming that the system is correctly configured): MARK="DASH" REMAP="BS--BulletSub"The machine that the server is supposed to be on is running correctly and the network is running correctly. In this case, if there is no server listening on the specified port, the machine the server is supposed to be on will signal the client, via a network error, that the connection can't be formed.  Regardless of MOREINFO="NONE"dbsetlogintime, the connection will fail. The machine that the server is on is down. In this case, the machine that the server is supposed to be on will not respond.  Because "no response" is not considered to be an error, the network will not signal the client that an error has occurred. However, if MOREINFO="NONE"dbsetlogintime has been called to set a timeout period, a timeout error will occur when the client fails to receive a response within the set period. See AlsoREMAP="BO--Body"LINKEND="X12458"dberrhandle
, LINKEND="X68770"dbsettime
ID="IN6114-30150195"dbsetlogintime
 ID="IN6112-33153196"DBSETLPACKET
ID="IN613-33153197"TDSpacket size:setting
ID="IN6123-33153198"Setting TDS packet size
ID="IN6111-33153199"Packet sizeTDS
ID="IN6118-35155200"LOGINREC structurepacket size field
ID="IN6119-35155201"Text and image data
ID="IN6119-35155202"Tabular Data StreamroutinesID="X60486"DBSETLPACKET
Set the TDS packet size in an application's LOGINREC structure. FORMAT="LINESPECIFIC"RETCODE DBSETLPACKET(login, packet_size)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"LOGINREC      *login;FORMAT="LINESPECIFIC">short         packet_size;ParametersREMAP="RI--RefIndent"loginrec - A pointer to the LOGINREC structure to be passed as an argument  to MOREINFO="NONE"dbopen when logging in to the server. An application can obtain a LOGINREC structure via MOREINFO="NONE"dblogin. packet_size - The packet size being requested, in bytes.  The server will set the actual  packet size to a value less than or equal to this requested size. ReturnsREMAP="BO--Body"SUCCEED or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"DBSETLPACKET sets the packet size field in an application's  LOGINREC structure.  When the application logs in to the server, the server sets the TDS packet size for that DBPROCESS connection to be equal to or less than the value of this field.  The packet size is set to a value less than the value of the packet size field if the server is experiencing space constraints.  Otherwise, the packet size will be equal to the value of the field. If an application sends or receives large amounts of text or  image data, a packet size larger than the default 512 bytes may improve efficiency, since it results in fewer network reads and writes. To determine the packet size that the server has set,  an application can call MOREINFO="NONE"dbgetpacket. TDS (Tabular Data Stream) is an application protocol used for the  transfer of requests and request results between clients and servers. TDS data is sent in fixed-size chunks, called packets.  TDS packets have a default size of 512 bytes. The only way an application can change the TDS packet size is via MOREINFO="NONE"DBSETLPACKET.  If MOREINFO="NONE"DBSETLPACKET is not called, all DBPROCESS connections in an application will use the default size. Different DBPROCESS connections in an application may use different packet sizes.  To set different packet sizes for DBPROCESS connections, an application can either: MARK="DASH" REMAP="BS--BulletSub"Change the packet size in a single LOGINREC between the  MOREINFO="NONE"dbopen calls which create the DBPROCESS connections; or Set different packet sizes in multiple LOGINRECs, and use these different LOGINRECs when creating the DBPROCESS connections. Because the actual packet size for a DBPROCESS connection is set when the DBPROCESS is created, calls to MOREINFO="NONE"DBSETLPACKET will have no effect on the packet sizes of DBPROCESSes already allocated via MOREINFO="NONE"dbopen. See AlsoREMAP="BO--Body"LINKEND="X88162"dblogin
,  LINKEND="X42139"dbopen
,  LINKEND="X32032"dbgetpacket
ID="IN6212-38159209"DBSETLPACKET
 ID="IN629-41162210"DBSETLPWDID="X60994"DBSETLPWD
Set the user server password in the LOGINRECID="IN6318-43165212"LOGINREC structuresetting password in
ID="IN639-43165213"Passwordssetting server
ID="IN636-43165214"Serversetting user passwords
 structure. FORMAT="LINESPECIFIC"RETCODE DBSETLPWD(loginrec, password)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"LOGINREC      *loginrec;FORMAT="LINESPECIFIC"char          *password;ParametersREMAP="RI--RefIndent"loginrec - A pointer to a LOGINREC structure, which will be passed as an argument to MOREINFO="NONE"dbopen. You can get one by calling MOREINFO="NONE"dblogin. password - The password that will be sent to the server. It must be a null-terminated character string. The maximum length of the string, not including the null terminator, is 30 characters. ReturnsREMAP="BO--Body"SUCCEED or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"This macro sets the user server password in the LOGINREC structure. For it to have any effect, it must be called before MOREINFO="NONE"dbopen. By default, the password field of the LOGINREC has a null value. Therefore, you do not need to call this routine if the password is a null value. DB-Library does not automatically blank out the password in loginrec after a call to MOREINFO="NONE"dbopen. Therefore, if you want to minimize the risk of having a readable password in your DB-Library program, you should set password to something else after you call MOREINFO="NONE"dblogin. See AlsoREMAP="BO--Body"LINKEND="X88162"dblogin
, LINKEND="X42139"dbopen
, LINKEND="X75775"DBSETLAPP
, LINKEND="X47887"DBSETLHOST
, LINKEND="X77719"DBSETLUSER
ID="IN639-46168220"DBSETLPWD
 ID="IN6310-49171221"DBSETLUSERID="X77719"DBSETLUSER
Set the username in the LOGINRECID="IN6418-51174223"LOGINREC structuresetting username in
ID="IN649-51174224"Usernamessetting
 structure. FORMAT="LINESPECIFIC"RETCODE DBSETLUSER(loginrec, username)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"LOGINREC       *loginrec;FORMAT="LINESPECIFIC"char           *username;ParametersREMAP="RI--RefIndent"loginrec - A pointer to a LOGINREC structure, which will be passed as an argument to MOREINFO="NONE"dbopen. You can get one by calling MOREINFO="NONE"dblogin. username - The username that will be sent to the server. It must be a null-terminated character string. The maximum length of the string, not including the null terminator, is 30 characters. The server will use username to determine who is attempting the connection. The server usernames are defined in the syslogins table in the master database. ReturnsREMAP="BO--Body"SUCCEED or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"This macro sets the username in the LOGINREC structure. For it to have any effect, it must be called before MOREINFO="NONE"dbopen. In most environments, this macro is optional. If it is not called, DB-Library will generally set the default value for the username. On MOREINFO="NONE"VMS: the username defaults to the USER logical name. On MOREINFO="NONE"UNIX: the username defaults to the UNIX login name. On OS/2 and NetWare: The username defaults to the SYBUSER environment variable, if any. If the application does not call MOREINFO="NONE"DBSETLUSER, the SYBUSER environment variable must be set. Otherwise, MOREINFO="NONE"dbopen will fail when it tries to log into the server. On MPE/XL:  The username defaults to the value of the system environment variable HPUSER. See AlsoREMAP="BO--Body"LINKEND="X88162"dblogin
, LINKEND="X42139"dbopen
, LINKEND="X47887"DBSETLHOST
, LINKEND="X60994"DBSETLPWD
, LINKEND="X75775"DBSETLAPP
ID="IN6410-54177230"DBSETLUSER
 ID="IN6413-57180231"dbsetmaxprocsID="X47066"dbsetmaxprocs
Set the maximum number of simultaneously open DBPROCESSID="IN6519-59183233"DBPROCESS structuresetting maximum number available
es. FORMAT="LINESPECIFIC"RETCODE dbsetmaxprocs(maxprocs)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"int           maxprocs;ParametersREMAP="RI--RefIndent"maxprocs - The new limit on simultaneously open DBPROCESSes for this particular program. ReturnsREMAP="BO--Body"SUCCEED or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"A DB-Library program has a maximum number of simultaneously open DBPROCESSes. By default, this number is 25. The program may change this limit by calling MOREINFO="NONE"dbsetmaxprocs. The program may find out what the current limit is by calling MOREINFO="NONE"dbgetmaxprocs. See AlsoREMAP="BO--Body"LINKEND="X85672"dbgetmaxprocs
, LINKEND="X42139"dbopen
ID="IN6513-62186239"dbsetmaxprocs
 dbsetnotifs (VMSID="IN6611-65190240"dbsetnotifs
ID="IN6631-65190241"Disabling registered procedures
ID="IN668-65190242"VMS only
 only)
Enable or disable registered procedure notifications. FORMAT="LINESPECIFIC"RETCODE dbsetnotifs(notif_state)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBBOOL       notif_state;ParametersREMAP="RI--RefIndent"notif_state - A BOOLEAN set to TRUE to enable registered procedure notifications and FALSE to disable. ReturnsREMAP="BO--Body"SUCCEED or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbsetnotif may only be invoked before MOREINFO="NONE"dbopen has been used to establish a connection with the server or after all connections are closed. MOREINFO="NONE"dbsetnotifs returns FAIL if any connections are open when it is called. If registered procedure notifications are enabled, programs may not use synchronous functions at AST level. Performing synchronous functions at AST level with registered procedure notifications enabled will cause I/O operations to hang. Registered procedure notifications are enabled by default. This call affects all connections subsequently opened. See AlsoREMAP="BO--Body"LINKEND="X45215"dbpoll
ID="IN6611-68193249"dbsetnotifs
 ID="IN669-71196250"dbsetnullID="X70360"dbsetnullID="IN6711-71197252"Null valuesdefining
ID="IN6711-71197253"Null valuesbinding
Define substitution values to be used when binding null values. FORMAT="LINESPECIFIC"RETCODE dbsetnull(dbproc, bindtype, bindlen, bindval)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"int           bindtype;FORMAT="LINESPECIFIC"int           bindlen;FORMAT="LINESPECIFIC"BYTE          *bindval;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. bindtype - The type of variable binding to which the substitute value will apply. (See the manual page for MOREINFO="NONE"dbbind for more information about the different bindtypes.) bindlen - The length in bytes of the substitute value you are supplying.  DB-Library ignores it in all cases except CHARBIND and BINARYBIND. All the other types are either fixed length or have a special terminator or embedded byte-count that provides the length of the data. bindval - A generic BYTE pointer to the value you want to use as a null substitution value. MOREINFO="NONE"dbsetnull makes a copy of the value, so you can free this pointer at any time after this call. ReturnsREMAP="BO--Body"SUCCEED or FAIL. MOREINFO="NONE"dbsetnull returns FAIL if you give it an unknown bindtype. It will also fail if the specified DBPROCESS is dead. CommentsMARK="BULL" REMAP="BU--Bullet"The MOREINFO="NONE"dbbind and MOREINFO="NONE"dbaltbind routines bind result column values to program variables. After the application calls them, calls to MOREINFO="NONE"dbnextrow and MOREINFO="NONE"dbgetrow automatically copy result values into the variables to which they are bound. If the server returns a null value for one of the result columns, DB-Library automatically places a substitute value into the result variable. Each DBPROCESSID="IN6711-71197258"Null valuesdefault
 has a list of substitute values for each of the binding types. The following table lists the default substitution values: TOCENTRY="1"LBL="Table 2-37: "Default null substitution valuesCOLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="126*"COLNAME="C2" COLWIDTH="207*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Binding Type:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Null Substitution Value:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"TINYBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"0 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SMALLBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"0 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"INTBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"0COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CHARBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"empty string (padded with blanks) COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"STRINGBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"empty string (padded with blanks, null-
terminated) COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NTBSTRINGBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"empty string (null-terminated) COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"VARYCHARBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"empty string COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"BINARYBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"empty array (padded with zeros) COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"VARYBINBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"empty array COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DATETIMEBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"8 bytes of zeros COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SMALLDATETIMEBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"8 bytes of zeros COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MONEYBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"$0.00 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SMALLMONEYBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"$0.00 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"FLT8BINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"0.0 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"REALBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"0.0 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DECIMALBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"0.0 (with default scale and precision)COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NUMERICBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"0.0 (with default scale and precision)COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"BOUNDARYBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"empty string (null-terminated)COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SENSITIVITYBINDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"empty string (null-terminated)MOREINFO="NONE"dbsetnull lets you provide your own null substitution values. When you call MOREINFO="NONE"dbsetnull to change a particular null substitution value, the new value will remain in force for the specified DBPROCESS until you change it with another call to MOREINFO="NONE"dbsetnull. The MOREINFO="NONE"dbconvert routine also uses the current null substitution values when it needs to set a destination variable to null. See AlsoREMAP="BO--Body"LINKEND="X21854"dbaltbind
, LINKEND="X14206"dbbind
, LINKEND="X76814"dbconvert
, LINKEND="X91146"types
ID="IN679-74200260"dbsetnull
 ID="IN678-77203261"dbsetoptID="X97776"dbsetoptID="IN687-77204263"Optionssetting
Set a server or DB-Library option. FORMAT="LINESPECIFIC"RETCODE dbsetopt(dbproc, option, char_param,int_param)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"int           option;FORMAT="LINESPECIFIC"char          *char_param;FORMAT="LINESPECIFIC"int           int_param;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. If dbproc is NULL, the option will be set for all active DBPROCESS structures. option - The option that is to be turned on. See the MOREINFO="NONE"options manual page for the list of options. char_param - Certain options take parameters. For example, the DBOFFSET option takes as its parameter the construct for which offsets are to be returned: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"dbsetopt(dbproc, DBOFFSET, "compute", -1REMAP="UN--Under"The DBBUFFER option takes as its parameter the number of rows to be buffered: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"dbsetopt(dbproc, DBBUFFER, "500", -1)REMAP="UN--Under"char_param must always be a character string enclosed in quotes, even in the case of a numeric value, as in the DBBUFFER example. If an invalid parameter is specified for one of the server options, this will be discovered the next time a command buffer is sent to the server. The MOREINFO="NONE"dbsqlexec or MOREINFO="NONE"dbsqlsend call will fail, and DB-Library will invoke the user-installed message handler. If an invalid parameter is specified for one of the DB-Library options (DBBUFFER or DBTEXTLIMIT), the MOREINFO="NONE"dbsetopt call itself will fail. REMAP="UN--Under"If the option takes no parameters, char_param must be NULL. int_param - Some options require an additional parameter, int_param, which is the length of the character string passed as char_param. Currently, only  DBPRCOLSEP, DBPRLINESEP, and DBPRPAD require this parameter. REMAP="UN--Under"If int_param is not required, pass it as -1.ReturnsREMAP="BO--Body"SUCCEED or FAIL. REMAP="BO--Body"MOREINFO="NONE"dbsetopt will fail if char_param is invalid for one of the DB-Library options. However, an invalid char_param for a server option will not cause MOREINFO="NONE"dbsetopt to fail, because such a parameter does not get validated until the command buffer is sent to the server. CommentsMARK="BULL" REMAP="BU--Bullet"This routine sets server and DB-Library options. Although server options may be set and cleared directly through SQL, the application should instead use MOREINFO="NONE"dbsetopt and MOREINFO="NONE"dbclropt to set and clear options.  This provides a uniform interface for setting both server and DB-Library options. It also allows the application to use the MOREINFO="NONE"dbisopt function to check the status of an option. MOREINFO="NONE"dbsetopt does not immediately set the option. The option is set the next time a command buffer is sent to the server (by invoking MOREINFO="NONE"dbsqlexec or MOREINFO="NONE"dbsqlsend). For a list of each option and its default status, see the manual page for MOREINFO="NONE"options. See AlsoREMAP="BO--Body"LINKEND="X69074"dbclropt
, LINKEND="X50317"dbisopt
, LINKEND="X60647"options
ID="IN688-80207269"dbsetopt
 ID="IN688-83210270"dbsetrowID="X55181"dbsetrow
Set a buffered row to "current."  FORMAT="LINESPECIFIC"STATUS dbsetrow(dbproc, row)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"DBINT         row;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and the server. row - An integer representing the row number of the row to make current. Row number 1 is the first row returned from the server. This is not necessarily the first row in the row buffer. ReturnsREMAP="BO--Body"MORE_ROWS, NO_MORE_ROWS, or FAIL. REMAP="BO--Body"MOREINFO="NONE"dbsetrow returns: MARK="BULL" REMAP="BU--Bullet"MORE_ROWS if it found row in the row buffer; NO_MORE_ROWS if it did not find row in the row buffer, or if row buffering is not enabled; FAIL if the dbproc DBPROCESS is dead or not enabled. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbsetrow sets a buffered row to "current". After MOREINFO="NONE"dbsetrow is called, the application's next call to MOREINFO="NONE"dbnextrow will read this row.   MOREINFO="NONE"dbgetrow, another DB-Library/C routine, also sets a specific row in the row buffer to "current." However, unlike MOREINFO="NONE"dbsetrow, MOREINFO="NONE"dbgetrow reads the row. Any binding of row data to program variables (as specified with MOREINFO="NONE"dbbind and MOREINFO="NONE"dbaltbind) takes effect. MOREINFO="NONE"dbsetrow has no effect unless the DB-Library/C option DBBUFFERID="IN6911-83211276"Row buffers
 is on. Row buffering provides a way to keep a specified number of server result rows in program memory. Without row buffering, the result row generated by each new MOREINFO="NONE"dbnextrow call overwrites the contents of the previous result row. Row buffering is therefore useful for programs that need to look at result rows in a non-sequential manner. It does, however, carry a memory and performance penalty  because each row in the buffer must be allocated and freed individually. Therefore, use it only if you need to. Specifically, the application should only turn the DBBUFFER option on if it calls MOREINFO="NONE"dbgetrow or MOREINFO="NONE"dbsetrow. Note that row buffering has nothing to do with network buffering and is a completely independent issue. When row buffering is not enabled, the application processes each row as it reads it from the server, by calling MOREINFO="NONE"dbnextrow repeatedly until it returns NO_MORE_ROWS.  When row buffering is enabled, the application can use MOREINFO="NONE"dbsetrow to jump to any row that has already been read from the server with MOREINFO="NONE"dbnextrow.  Subsequent calls to MOREINFO="NONE"dbnextrow will cause the application to read successive rows in the buffer, starting with the row specified by the row parameter. When MOREINFO="NONE"dbnextrow reaches the last row in the buffer, it reads rows from the server again, if there are any.  Once the buffer is full, MOREINFO="NONE"dbnextrow does not read any more rows from the server until some of the rows have been cleared from the buffer with MOREINFO="NONE"dbclrbuf. The macro MOREINFO="NONE"DBFIRSTROW, which returns the number of the first row in the row buffer, is useful in conjunction with  MOREINFO="NONE"dbsetrow.  Thus, the call: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"dbsetrow(dbproc, DBFIRSTROW(dbproc)) REMAP="UN--Under"sets the current row so that the next call to MOREINFO="NONE"dbnextrow  will read the first row in the buffer. See AlsoREMAP="BO--Body"LINKEND="X38617"dbclrbuf
, LINKEND="X17373"DBCURROW
, LINKEND="X66598"DBFIRSTROW
, LINKEND="X71422"dbgetrow
, LINKEND="X20854"DBLASTROW
, LINKEND="X10726"dbnextrow
, LINKEND="X60647"options
ID="IN698-86214278"dbsetrow
 ID="IN6913-89217279"dbsetsecurity
ID="IN6920-89217280"Login request labelssettingID="X89093"dbsetsecurityID="IN7015-89218282"Security labelssetting
Set login security labels for use when logging into a Secure SQL Server.FORMAT="LINESPECIFIC"RETCODE dbsetsecurity(loginrec, labelname, labelvalue)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"LOGINREC      *loginrec;FORMAT="LINESPECIFIC"CHAR          *labelname;FORMAT="LINESPECIFIC"CHAR          *labelvalue;ParametersREMAP="RI--RefIndent"loginrec - A pointer to a LOGINREC structure, which will be passed as an argument to MOREINFO="NONE"dbopen. You can get one by calling MOREINFO="NONE"dblogin. labelname -  A pointer to one of the following session label names:MARK="DASH" REMAP="BS--BulletSub""curread" (current read level) is the initial level of data that you can read during this session. curread must dominate curwrite."curwrite" (current write level) is the initial sensitivity level that will be applied to any data that you write during this session."maxread "(maximum read level) is the maximum level at which you can read data. This is the upper bound to which you as a multi-level user can set your curread during the session. maxread must dominate maxwrite."maxwrite" (maximum write level) is the maximum level at which you can write data. This is the upper bound to which you as a multi-level user can set your curwrite during a session. maxwrite must dominate minwrite and curwrite."minwrite" (minimum write level) is the minimum level at which you can write data. This is the lower bound to which you as a multi-level user can set curwrite during a session. minwrite must be dominated by maxwrite and curwrite.labelvalue -  A pointer to a 255-byte, human-readable security label in your system.ReturnsREMAP="BO--Body"SUCCEED or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbsetsecurity defines login security labels for use when logging into a Secure SQL Server.There are two ways for an application to define security labels:MARK="DASH" REMAP="BS--BulletSub"The application can call MOREINFO="NONE"dbsetsecurity one time for each label it wants to define. Most applications will use this method.The application can call MOREINFO="NONE"dbsechandle to install a user-supplied function to generate security labels. Typically, only gateway applications will use this method.REMAP="UN--Under"If an application uses both methods, the labels defined via MOREINFO="NONE"dbsetsecurity and the labels generated by the user-supplied function are sent to the server at the same time.An application calls MOREINFO="NONE"dbsetsecurity to define login security labels before calling MOREINFO="NONE"dbopen to open a connection. The labels are sent to the server as a part of opening the connection.A separate call to MOREINFO="NONE"dbsetsecurity must be made for each label that you wish to set.Before calling MOREINFO="NONE"dbsetsecurity the application must call MOREINFO="NONE"DBSETLLABELED to inform the server that it will send login security labels.The DB-Library version must be set to 10.0 before you can call MOREINFO="NONE"dbsetsecurity. (Set it with MOREINFO="NONE"dbsetversion.)See AlsoREMAP="BO--Body"LINKEND="X37857"DBSETLLABELED
, LINKEND="X13587"dbsechandle
, LINKEND="X32027"dbsetversion
ID="IN7013-92221288"dbsetsecurity
 ID="IN709-95224289"dbsettimeID="X68770"dbsettimeID="IN714-95225291"Timesetting length DB-Library waits for server response
Set the number of seconds that DB-Library will wait for a server response to a SQL command. FORMAT="LINESPECIFIC"RETCODE dbsettime(seconds)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"int           seconds;ParametersREMAP="RI--RefIndent"seconds - The timeout value-the number of seconds that DB-Library waits for a server response before timing out. A timeout value of 0 represents an infinite timeout period. ReturnsREMAP="BO--Body"SUCCEED or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"This routine sets the length of time in seconds that DB-Library will wait for a server response during calls to MOREINFO="NONE"dbsqlexec, MOREINFO="NONE"dbsqlok, MOREINFO="NONE"dbresults, and MOREINFO="NONE"dbnextrow. The default timeout value is 0, which represents an infinite timeout period. MOREINFO="NONE"dbsettime can be called at any time during the application-before or after a call to MOREINFO="NONE"dbopen. It takes effect immediately upon being called. To set a timeout value for calls to MOREINFO="NONE"dbopen, use MOREINFO="NONE"dbsetlogintime. Note that, after sending a query to the server, MOREINFO="NONE"dbsqlexec waits until a response is received or until the timeout period has elapsed. To minimize the time spent in DB-Library waiting for a response from the server, an application can instead call MOREINFO="NONE"dbsqlsend followed by MOREINFO="NONE"dbsqlok. The program can call MOREINFO="NONE"DBGETTIME to learn the current timeout value. A timeout generates the DB-Library error "SYBETIME." See AlsoREMAP="BO--Body"LINKEND="X12458"dberrhandle
, LINKEND="X80614"DBGETTIME
, LINKEND="X64830"dbsetlogintime
, LINKEND="X41234"dbsqlexec
, LINKEND="X21206"dbsqlok
, LINKEND="X49376"dbsqlsend
ID="IN719-98228297"dbsettime
 ID="IN7113-101231298"dbsetuserdataID="X15711"dbsetuserdata
Use a DBPROCESSID="IN7213-103234300"User-supplieddata:saving in a DBPROCESS
ID="IN7213-103234301"User-supplieddata:saving
ID="IN724-103234302"Datasaving user-allocated
ID="IN7219-105236303"DBPROCESS structuresaving user-allocated data
 structure to save a pointer to user-allocated data. FORMAT="LINESPECIFIC"void dbsetuserdata(dbproc, ptr)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"BYTE          *ptr;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. ptr - A generic BYTE pointer to the user's private data space. ReturnsREMAP="BO--Body"None. CommentsMARK="BULL" REMAP="BU--Bullet"This routine saves, in a DBPROCESS structure, a pointer to user-allocated data. The application can access the data later with the MOREINFO="NONE"dbgetuserdata routine. ID="IN728-105236308"DeadlockhandlingMOREINFO="NONE"dbsetuserdata allows the application to associate user data with a particular DBPROCESS. This avoids the necessity of using global variables for this purpose. One use for this routine is to handle deadlock, as shown in the example below. This routine is particularly useful when the application has multiple DBPROCESSes. The application must allocate the data that ptr points to. DB-Library never manipulates this data; it merely saves the pointer to it for later use by the application. Here's an example of using this routine to handle deadlock, a situation which occurs occasionally in high-volume applications. See the System Administration GuideID="IN7216-105236309"Message handlingMessage handlingand deadlockdeadlock
 for more information on deadlock. This program fragment sends updates to the server. It reruns the transaction when its message handler detects deadlock. REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"... REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"/* ** Deadlock detection: **  In the DBPROCESS structure, we save a pointer to **  a DBBOOL variable. The message handler sets the **  variable when deadlock occurs. The result**  processing logic checks the variable and resends **  the transaction in case of deadlock. */ REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"    /*     ** Allocate the space for the DBBOOL variable    ** and save it in the DBPROCESS structure.     */     dbsetuserdata(dbproc, malloc(sizeof(DBBOOL))); REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"    /* Initialize the variable to FALSE */     *((DBBOOL *) dbgetuserdata(dbproc)) = FALSE; REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"... REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"    /* Run queries and check for deadlock */ deadlock:     /*     ** Did we get here via deadlock?     ** If so, the server has already aborted the     ** transaction. We'll just start it again.  In a     ** real application, the deadlock handling may need     ** to be somewhat more sophisticated.  For     ** instance, you may want to keep a counter and    ** retry the transaction just a fixed number     ** of times.     */ REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"    if (*((DBBOOL *) dbgetuserdata(dbproc)) == TRUE)     {         /* Reset the variable to FALSE */         *((DBBOOL *) dbgetuserdata(dbproc)) = FALSE;     } REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"    /* Start the transaction */     dbcmd(dbproc, "begin transaction "); REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"    /* Run the first update command */     dbcmd(dbproc, "update ......");     dbsqlexec(dbproc);     while (dbresults(dbproc) != NO_MORE_RESULTS)     {         /* application code */     } REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"    /*  Did we deadlock? */     if (*((DBBOOL *) dbgetuserdata(dbproc)) == TRUE)         goto deadlock; REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"    /*  Run the second update command.  */     dbcmd(dbproc, "update ......");     dbsqlexec(dbproc);     while (dbresults(dbproc) != NO_MORE_RESULTS)     {         /* application code */     } REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"    /*  Did we deadlock? */     if (*((DBBOOL *) dbgetuserdata(dbproc)) == TRUE)         goto deadlock; REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"    /*  No deadlock -- Commit the transaction */     dbcmd(dbproc, "commit transaction");     dbsqlexec(dbproc);     dbresults(dbproc); REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"... REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"/* ** SERVERMSGS ** This is the server message handler.  Assume that ** the dbmsghandle() routine installed it earlier in** the program. */ servermsgs(dbproc, msgno, msgstate, severity, msgtext,    srvname, procname, line) DBPROCESS    *dbproc; DBINT        msgno; int          msgstate; int          severity; char         *msgtext; char         *srvname; char         *procname; DBUSMALLINT  line; { REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"    /*  Is this a deadlock message? */     if (msgno == 1205)     {         /* Set the deadlock indicator */         *((DBBOOL *) dbgetuserdata(dbproc)) = TRUE;         return (0);     } REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"    /*  Normal message handling code here */ } See AlsoREMAP="BO--Body"LINKEND="X34885"dbgetuserdata
ID="IN7213-108239311"dbsetuserdata
 ID="IN7212-111242312"dbsetversionID="X32027"dbsetversion
Specify a DB-Library version level.FORMAT="LINESPECIFIC"RETCODE dbsetversion(version)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBINT        version;ParametersREMAP="RI--RefIndent"version - The version of DB-Library behavior that the application expects. The following table lists the symbolic values that are legal for version:TOCENTRY="1"LBL="Table 2-38: "Values for version (MOREINFO="NONE"dbsetversion)COLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="99*"COLNAME="C2" COLWIDTH="88*"COLNAME="C3" COLWIDTH="172*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Value of version:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Features Supported:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBVERSION_46COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"4.6 behaviorCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"RPCs, registered procedures, 
remote procedure calls, text and 
image datatypes.

This is the default version of DB-
Library.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBVERSION_100COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"10.0 behaviorCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Numeric and decimal datatypes.ReturnsREMAP="BO--Body"SUCCEED or FAIL.CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbversion sets the version of DB-Library behavior that an application expects. DB-Library will provide the behavior requested, regardless of the actual version of DB-Library in use.An application is not required to call MOREINFO="NONE"dbsetversion. However, if MOREINFO="NONE"dbsetversion is not called, DB-Library provides 4.6-level behavior.If an application calls MOREINFO="NONE"dbsetversion, it must do so before calling any other DB-Library routine, with the exception of MOREINFO="NONE"dbinit.It is an error to call MOREINFO="NONE"dbsetversion more than once.See AlsoREMAP="BO--Body"LINKEND="X24387"dbinit
ID="IN7312-114246319"dbsetversion
ID="IN736-117249320"dbspiddbspid
Get the server process id for the specified DBPROCESSID="IN7419-119252322"DBPROCESS structuregetting server process id
ID="IN7410-119252323"Process idgetting
. FORMAT="LINESPECIFIC"int dbspid(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. ReturnsREMAP="BO--Body"dbproc's server process id. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbspid yields the server process id of the specified DBPROCESS. The process id appears in the server's sysprocesses table. You can use the server process id to make queries against the sysprocesses table. See AlsoREMAP="BO--Body"LINKEND="X42139"dbopen
ID="IN746-122255329"dbspid
 ID="IN749-125258330"dbspr1rowID="X27359"dbspr1rowID="IN7511-125259332"Result rowsputting one in buffer
Place one row of server query results into a buffer. FORMAT="LINESPECIFIC"RETCODE dbspr1row(dbproc, buffer, buf_len)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS      *dbproc;FORMAT="LINESPECIFIC"char           *buffer;FORMAT="LINESPECIFIC"DBINT          buf_len;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. buffer - A pointer to a character buffer to contain the MOREINFO="NONE"dbspr1row results. buf_len - The length of buffer, including its NULL terminator. ReturnsREMAP="BO--Body"SUCCEED or FAIL. If an error occurs, the contents of *buffer are undefined. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbspr1row fills a programmer-supplied buffer with a NULL-terminated character string containing one server query results row. ID="IN759-129263337"DebuggingDebuggingand dbspr1rowdbspr1rowMOREINFO="NONE"dbspr1row is useful when displaying data for debugging and writing applications that scroll data displays. MOREINFO="NONE"dbspr1row gives programmers greater control over data display than MOREINFO="NONE"dbprrow. MOREINFO="NONE"dbprrow always writes its output to the display device, while MOREINFO="NONE"dbspr1row writes its output to a buffer, which the programmer may then display at whatever time or location is desired. To pad results data to its maximum converted length, specify a pad character via the DB-Library option DBPRPAD. The pad character will be appended to each column's data. The maximum converted column length is equal to the longest possible string which could be the column's displayable data, or the length of the column's name, whichever is greater. See the MOREINFO="NONE"options man page for more details on the DBPRPAD option. You can specify the column separator string via the DB-Library option DBPRCOLSEP.  The column separator will be added to the end of each converted column's data except the last.  The default separator is an ASCII 0x20 (space). See the MOREINFO="NONE"options man page for more details on the DBPRCOLSEP option. You can specify the maximum number of characters to be placed on one line via the DB-Library option DBPRLINELEN. You can specify the line separator string via the DB-Library option DBPRLINESEP. The default line separator is a newline (ASCII 0x0a or 0x0d, depending on the host system). See the MOREINFO="NONE"options man page for more details on the DBPRLINELEN and DBPRLINESEP options. The length of the buffer required by MOREINFO="NONE"dbspr1row can be determined by calling MOREINFO="NONE"dbspr1rowlen. The format of results rows returned by MOREINFO="NONE"dbspr1row is determined by the SQL query. MOREINFO="NONE"dbspr1row makes no attempt to format the data beyond converting it to printable characters, padding the columns as necessary, and adding the column and line separators. To make the best use of MOREINFO="NONE"dbspr1row, application programs should call it once for every successful call to MOREINFO="NONE"dbnextrow. The following code fragment illustrates the use of MOREINFO="NONE"dbspr1row: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"char     mybuffer[2000];  while (dbnextrow(dbproc) != NO_MORE_ROWS) {     dbspr1row(dbproc, mybuffer,sizeof(mybuffer));     fprintf( stdout, "\n%s", mybuffer); } The following code fragment shows the use of the DBPRPAD and DBPRCOLSEP options: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"char     mybuffer[2000];  /* ** Specify the pad and column separator** characters */  /* Pad = 0x2A */dbsetopt(dbproc, DBPRPAD, "*", DBPADON);/* Col. sep. = 0x2C20 */dbsetopt(dbproc, DBPRCOLSEP, ", ", 2); while (dbnextrow(dbproc) != NO_MORE_ROWS) {     dbspr1row(dbproc, mybuffer,         sizeof(mybuffer) );     fprintf( stdout, "\n%s", mybuffer); }  /* Turn padding off */dbsetopt(dbproc, DBPRPAD, SS, DBPADOFF );/* Revert to default */dbsetopt(dbproc, DBPRCOLSEP, RS, -1 );See AlsoREMAP="BO--Body"LINKEND="X69074"dbclropt
, LINKEND="X50317"dbisopt
, LINKEND="X13029"dbprhead
, LINKEND="X66379"dbprrow
, LINKEND="X59954"dbspr1rowlen
, LINKEND="X48660"dbsprhead
, LINKEND="X50336"dbsprline
, LINKEND="X60647"options
ID="IN759-144278341"dbspr1row
  ID="IN7512-147281342"dbspr1rowlenID="X59954"dbspr1rowlen
Determine how large a buffer to allocate to hold the results returned by MOREINFO="NONE"dbsprhead, dbsprline, and MOREINFO="NONE"dbspr1rowID="IN767-147282344"Buffersdetermining size for results
. FORMAT="LINESPECIFIC"DBINT dbspr1rowlen(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. ReturnsREMAP="BO--Body"The size of the buffer, in bytes, required by MOREINFO="NONE"dbsprhead, dbsprline, and MOREINFO="NONE"dbspr1row on success; a negative integer on error. CommentsID="IN769-155290349"dbsprheaddbsprheadand dbspr1rowlendbspr1rowlen
ID="IN769-163298350"dbsprlinedbsprlineand dbspr1rowlendbspr1rowlen
ID="IN769-171306351"dbspr1rowdbspr1rowand dbspr1rowlendbspr1rowlenMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbspr1rowlen determines the size of the buffer (in bytes) required by MOREINFO="NONE"dbsprhead, dbsprline, and MOREINFO="NONE"dbspr1row, including the NULL terminator. ID="IN769-175310352"DebuggingDebuggingand dbspr1rowlendbspr1rowlenMOREINFO="NONE"dbspr1rowlen is useful when printing data for debugging, and when scrolling data displays. To make the best use of MOREINFO="NONE"dbspr1rowlen, application programs should call it once for every successful call to MOREINFO="NONE"dbresults. The following code fragment illustrates the use of MOREINFO="NONE"dbspr1rowlen: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"dbcmd(dbproc, "select * from sysdatabases"); dbcmd(dbproc, " order by name"); dbcmd(dbproc, " compute max(crdate) by name"); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"dbsqlexec(dbproc); dbresults(dbproc); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"printf("Maximum row length will be %ld \     characters.\n", dbspr1rowlen(dbproc)); See AlsoREMAP="BO--Body"LINKEND="X69074"dbclropt
, LINKEND="X50317"dbisopt
, LINKEND="X13029"dbprhead
, LINKEND="X66379"dbprrow
, LINKEND="X27359"dbspr1row
, LINKEND="X48660"dbsprhead
, LINKEND="X50336"dbsprline
, LINKEND="X60647"options
ID="IN7612-178313354"dbspr1rowlen
 ID="IN769-181316355"dbsprheadID="X48660"dbsprheadID="IN7711-181317357"Result rowsplacing header in buffer
ID="IN777-181317358"Buffersplacing query results header in
Place the server query results header into a buffer. FORMAT="LINESPECIFIC"RETCODE dbsprhead(dbproc, buffer, buf_len)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"char          *buffer;FORMAT="LINESPECIFIC"DBINT         buf_len;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. buffer - A pointer to a character buffer to contain the query results header. buf_len - The length of buffer, including its NULL terminator. ReturnsREMAP="BO--Body"SUCCEED or FAIL. If an error occurs, the contents of *buffer are undefined. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbsprhead fills a programmer-supplied buffer with a NULL-terminated character string containing the header for the current set of query results. The header consists of the column names. The sequence of the column names matches that of the output of MOREINFO="NONE"dbspr1row. ID="IN779-185321363"DebuggingDebuggingand dbsprheaddbsprheadMOREINFO="NONE"dbsprhead is useful when printing data for debugging, and when scrolling data displays. To pad each column name to its maximum converted length, specify a pad character via the DB-Library option DBPRPAD. The pad character will be appended to each column's name. The maximum converted column length is equal to the longest possible string which could be the column's displayable data, or the length of the column's name, whichever is greater. See the MOREINFO="NONE"options man page for more details on the DBPRPAD option. You can specify the column separator string via the DB-Library option DBPRCOLSEP.  The column separator will be added to the end of each column name except the last.  The default separator is an ASCII 0x20 (space). See the MOREINFO="NONE"options man page for more details on the DBPRCOLSEP option. You can specify the maximum number of characters to be placed on one line via the DB-Library option DBPRLINELEN. REMAP="UN--Under"You can specify the line separator string via the DB-Library option DBPRLINESEP. The default line separator is a newline (ASCII 0x0a or 0x0d, depending on the host system). See the MOREINFO="NONE"options man page for more details on the DBPRLINELEN and DBPRLINESEP options. The length of the buffer required by MOREINFO="NONE"dbsprhead can be determined by calling MOREINFO="NONE"dbspr1rowlen. To make the best use of MOREINFO="NONE"dbsprhead, application programs should call it once for every successful call to MOREINFO="NONE"dbresults. The following code fragment illustrates the use of MOREINFO="NONE"dbsprhead: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"dbcmd(dbproc, "select * from sysdatabases"); dbcmd(dbproc, " order by name"); dbcmd(dbproc, " compute max(crdate) by name"); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"dbsqlexec(dbproc); dbresults(dbproc); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"dbsprhead(dbproc, buffer, sizeof(buffer)); printf("%s\n", buffer); See AlsoREMAP="BO--Body"LINKEND="X69074"dbclropt
, LINKEND="X50317"dbisopt
, LINKEND="X13029"dbprhead
, LINKEND="X66379"dbprrow
, LINKEND="X97776"dbsetopt
, LINKEND="X27359"dbspr1row
, LINKEND="X59954"dbspr1rowlen
, LINKEND="X50336"dbsprline
, LINKEND="X60647"options
ID="IN779-188324365"dbsprhead
 ID="IN779-191327366"dbsprlineID="X50336"dbsprline
Choose the character with which to underline the column names produced by MOREINFO="NONE"dbsprheadID="IN789-199336368"dbsprheaddbsprheadand dbsprlinedbsprline
. FORMAT="LINESPECIFIC"RETCODE dbsprline(dbproc, buffer, buf_len, linechar)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"char          *buffer;FORMAT="LINESPECIFIC"DBINT         buf_len;FORMAT="LINESPECIFIC"DBCHAR        linechar;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. buffer - A pointer to a character buffer to contain the MOREINFO="NONE"dbsprline results. buf_len - The length of buffer, including its NULL terminator. linechar - The character with which to "underline" column names produced by MOREINFO="NONE"dbsprhead. ReturnsREMAP="BO--Body"SUCCEED or FAIL. If an error occurs, the contents of *buffer are undefined. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbsprline is used to "underline" the column names produced by MOREINFO="NONE"dbsprhead. MOREINFO="NONE"dbsprline fills a programmer-supplied buffer with a NULL-terminated character string containing one group of the character specified by linechar for each column in the current set of query results. The format of this line matches the format of the output of MOREINFO="NONE"dbsprhead. You can determine the length of the buffer required by MOREINFO="NONE"dbsprline via MOREINFO="NONE"dbspr1rowlen. To make the best use of MOREINFO="NONE"dbsprhead, application programs should call it once for every successful call to MOREINFO="NONE"dbresults. ID="IN789-203340373"DebuggingDebuggingand dbsprlinedbsprlineMOREINFO="NONE"dbsprline is useful when printing data for debugging, and when scrolling data displays. The following code fragment illustrates the use of MOREINFO="NONE"dbsprline: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"dbcmd(dbproc, "select * from sysdatabases"); dbcmd(dbproc, " order by name"); dbcmd(dbproc, " compute max(crdate) by name"); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"dbsqlexec(dbproc); dbresults(dbproc); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* ** Display the column headings, underline them ** with "*" */ dbsprhead(dbproc, buffer, sizeof(buffer)); printf("%s\n", buffer); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"dbsprline(dbproc, buffer, sizeof(buffer), '*'); printf("%s\n", buffer); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* Process returned rows as usual */ See AlsoREMAP="BO--Body"LINKEND="X69074"dbclropt
, LINKEND="X50317"dbisopt
, LINKEND="X13029"dbprhead
, LINKEND="X66379"dbprrow
, LINKEND="X97776"dbsetopt
, LINKEND="X27359"dbspr1row
, LINKEND="X59954"dbspr1rowlen
, LINKEND="X48660"dbsprhead
, LINKEND="X60647"options
ID="IN789-206343375"dbsprline
 ID="IN789-209346376"dbsqlexecID="X41234"dbsqlexecID="IN7915-209347378"Command batchessending to the server
Send a command batch to the server. FORMAT="LINESPECIFIC"RETCODE dbsqlexec(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. ReturnsREMAP="BO--Body"SUCCEED or FAIL. The most common reason for failing is a SQL syntax error. MOREINFO="NONE"dbsqlexec will also fail if there are semantic errors, such as incorrect column or table names. Failure occurs if any of the commands in the batch contains a semantic or syntax error. MOREINFO="NONE"dbsqlexec also fails if previous results had not been processed, or if the command buffer was empty. REMAP="BO--Body"In addition, a run-time error, such as a database protection violation, can cause MOREINFO="NONE"dbsqlexec to fail. A run-time error will cause MOREINFO="NONE"dbsqlexec to fail:MARK="BULL" REMAP="BU--Bullet"If the command causing the error is the only command in the command buffer.If the command causing the error is the first command in a multiple-command buffer.REMAP="BO--Body"If the command buffer contains multiple commands (and the first command in the buffer is ok), a run-time error will not cause MOREINFO="NONE"dbsqlexec to fail. Instead, failure will occur with the MOREINFO="NONE"dbresults call that processes the command causing the run-time error. REMAP="BO--Body"The situation is a bit more complicated for run-time errors and stored procedures. A run-time error on an MOREINFO="NONE"execute command may cause MOREINFO="NONE"dbsqlexec to fail, in accordance with the rule given in the previous paragraphs. A run-time error on a statement inside a stored procedure will not cause MOREINFO="NONE"dbsqlexec to fail, however. For example, if the stored procedure contains an MOREINFO="NONE"insert statement and the user does not have insert permission on the database table, the MOREINFO="NONE"insert statement will fail, but MOREINFO="NONE"dbsqlexec will still return SUCCEED. To check for run-time errors inside stored procedures, use the MOREINFO="NONE"dbretstatus routine to look at the procedure's return status, and trap relevant server messages inside your message handler. CommentsMARK="BULL" REMAP="BU--Bullet"This routine sends SQL commands, stored in the command buffer of the DBPROCESS, to the server. Commands may be added to the DBPROCESS structure by calling MOREINFO="NONE"dbcmd or MOREINFO="NONE"dbfcmd. Once MOREINFO="NONE"dbsqlexec returns SUCCEED, the application must call MOREINFO="NONE"dbresults to process the results. The typical sequence of calls is: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"DBINT       xvariable; DBCHAR      yvariable[10]; REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* Read the query into the command buffer */ dbcmd(dbproc, "select x = 100, y = 'hello'"); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* Send the query to SQL Server */ dbsqlexec(dbproc); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* Get ready to process the query results */ dbresults(dbproc); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* Bind column data to program variables */ dbbind(dbproc, 1, INTBIND, (DBINT) 0,     (BYTE *) &xvariable); dbbind(dbproc, 2, STRINGBIND, (DBINT) 0,    yvariable); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* Now process each row */ while (dbnextrow(dbproc) != NO_MORE_ROWS) {     C-code to print or process row data } MOREINFO="NONE"dbsqlexec is equivalent to MOREINFO="NONE"dbsqlsend followed by MOREINFO="NONE"dbsqlok. However, after sending a query to the server, MOREINFO="NONE"dbsqlexec waits until a response is received or until the timeout period has elapsed. By substituting MOREINFO="NONE"dbsqlsend and MOREINFO="NONE"dbsqlok for MOREINFO="NONE"dbsqlexec, you can sometimes provide a way for the application to respond more effectively to multiple input and output streams. See the manual pages for those two routines for more information. Multiple commands may exist in the command buffer when an application calls MOREINFO="NONE"dbsqlexec.  These commands are sent to the server as a unit and are considered to be a single command batch. An asynchronous version of MOREINFO="NONE"dbsqlexec, called MOREINFO="NONE"dbsqlexec_a, is available for VMS. See AlsoREMAP="BO--Body"LINKEND="X41151"dbcmd
, LINKEND="X29834"dbfcmd
, LINKEND="X10726"dbnextrow
, LINKEND="X35104"dbresults
, LINKEND="X95390"dbretstatus
, LINKEND="X68770"dbsettime
, LINKEND="X34208"dbsqlexec_a (VMS only)
, LINKEND="X21206"dbsqlok
, LINKEND="X49376"dbsqlsend
ID="IN799-212350384"dbsqlexec
 ID="IN7917-215353385"dbsqlexec_a (VMS)ID="X34208"dbsqlexec_a  (VMS only)ID="IN8015-215354387"Command batchessending to the server:asynchronous (VMS)
Send a command batch to the server and verify its correctness asynchronously. FORMAT="LINESPECIFIC"RETCODE dbsqlexec_a(dbproc, final_result, ast_proc,                     ast_param)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"RETCODE       *final_result;FORMAT="LINESPECIFIC"void          (*ast_proc)();FORMAT="LINESPECIFIC"BYTE          *ast_param;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. final_result - A pointer to a RETCODE which is set to SUCCEED or FAIL if MOREINFO="NONE"dbsqlexec_a returns SUCCEED. *final_result will be set to SUCCEED if the server determines that the command batch is correct. The most common reason that *final_result gets set to FAIL is a SQL syntax error. *final_result also gets set to FAIL if there are semantic errors, such as incorrect column or table names. Failure occurs if any of the commands in the batch contains a semantic or syntax error. REMAP="UN--Under"In addition, a run-time error, such as a database protection violation, will set *final_result to FAIL if the command buffer contains only a single command. If the command buffer contains multiple commands, a run-time error will not set *final_result to FAIL. Instead, failure will occur with the MOREINFO="NONE"dbresults or MOREINFO="NONE"dbresults_a call that processes the command causing the run-time error. REMAP="UN--Under"The situation is a bit more complicated for run-time errors and stored procedures. A run-time error on an MOREINFO="NONE"execute command may set *final_result to FAIL, in accordance with the rule given in the previous paragraph. A run-time error on a statement inside a stored procedure will not set *final_result to FAIL, however. For example, if the stored procedure contains an MOREINFO="NONE"insert statement and the user does not have insert permission on the database table, the MOREINFO="NONE"insert statement will fail, but *final_result will still be set to SUCCEED. To check for run-time errors inside stored procedures, use the MOREINFO="NONE"dbretstatus routine to look at the procedure's return status, and trap relevant server messages inside your message handler. ast_proc - A pointer to a user-supplied routine that will be queued when the correctness of the command batch is finally determined by the server.  *final_result will always be set before this procedure is invoked. ast_param - A generic BYTE pointer that will be passed to the user-supplied ast_proc(). ast_param allows the user to pass any parameter or structure to the ast_proc routine. ReturnsREMAP="BO--Body"SUCCEED or FAIL. MOREINFO="NONE"dbsqlexec_a will return FAIL if any of the following conditions are true:  previous results were not processed, the command buffer was empty, or there was an error in sending the command batch to the server. CommentsID="IN8027-217356392"Asynchronous routines (VMS)dbsqlexec_aMARK="BULL" REMAP="BU--Bullet"This routine is the asynchronous version of MOREINFO="NONE"dbsqlexec. This routine sends SQL commands, stored in the command buffer of the DBPROCESS, to the server. Commands may be added to the DBPROCESS structure by calling MOREINFO="NONE"dbcmd or MOREINFO="NONE"dbfcmd. The following three events must occur before MOREINFO="NONE"dbresults or MOREINFO="NONE"dbresults_a can be called to process the query results: MARK="DASH" REMAP="BS--BulletSub"MOREINFO="NONE"dbsqlexec_a must return SUCCEED. *final_result must be set to SUCCEED by DB-Library. ast_proc() must be invoked by DB-Library. REMAP="UN--Under"If MOREINFO="NONE"dbsqlexec_a returns FAIL, *final_result will not be set and ast_proc() will not be invoked. If MOREINFO="NONE"dbsqlexec_a returns SUCCEED, *final_result will be set to SUCCEED or FAIL (depending on whether the server verifies the command batch as correct) and ast_proc() will be invoked by DB-Library. ID="IN8014-217356393"Output streamsutilizing multiple (VMS)
ID="IN8013-217356394"Input streamsutilizing multiple (VMS)MOREINFO="NONE"dbsqlexec_a is useful in VMS applications that use multi-tasking or are otherwise trying to respond to multiple input and output streams. After sending a query to the server, MOREINFO="NONE"dbsqlexec waits until a response is received or until the timeout period has elapsed. By substituting MOREINFO="NONE"dbsqlexec_a for MOREINFO="NONE"dbsqlexec, the time between the request for server information and the server's      response can be used to service other parts of the application. References in this manual to the MOREINFO="NONE"dbsqlexec routine also pertain to MOREINFO="NONE"dbsqlexec_a. For an example that illustrates the use of MOREINFO="NONE"dbsqlexec_a, see the on-line example programs.See AlsoREMAP="BO--Body"LINKEND="X57019"dbcancel
, LINKEND="X53272"dbcancel_a (VMS only)
, LINKEND="X41151"dbcmd
, LINKEND="X29834"dbfcmd
, LINKEND="X10726"dbnextrow
, LINKEND="X90089"dbnextrow_a (VMS only)
, LINKEND="X35104"dbresults
, LINKEND="X81070"dbresults_a (VMS only)
, LINKEND="X95390"dbretstatus
, LINKEND="X41234"dbsqlexec
, LINKEND="X21206"dbsqlok
, LINKEND="X70305"dbsqlok_a (VMS only)
, LINKEND="X49376"dbsqlsend
ID="IN8017-220359396"dbsqlexec_a (VMS)
 ID="IN807-223362397"dbsqlokID="X21206"dbsqlokID="IN8115-223363399"Command batchesverifying correctness of
Wait for results from the server and verify the correctness of the instructions the server is responding to. FORMAT="LINESPECIFIC"RETCODE dbsqlok(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. ReturnsREMAP="BO--Body"SUCCEED or FAIL. The most common reason for failing is a SQL syntax error. MOREINFO="NONE"dbsqlok will also fail if there are semantic errors, such as incorrect column or table names. Failure occurs if any of the commands in the batch contains a semantic or syntax error. REMAP="BO--Body"In addition, a run-time error, such as a database protection violation, will cause MOREINFO="NONE"dbsqlok to fail if the command buffer contains only a single command. If the command buffer contains multiple commands, a run-time error will not cause MOREINFO="NONE"dbsqlok to fail. Instead, failure will occur with the MOREINFO="NONE"dbresults call that processes the command causing the run-time error. REMAP="BO--Body"The situation is a bit more complicated for run-time errors and stored procedures. A run-time error on an MOREINFO="NONE"execute command may cause MOREINFO="NONE"dbsqlok to fail, in accordance with the rule given in the previous paragraph. A run-time error on a statement inside a stored procedure will not cause MOREINFO="NONE"dbsqlok to fail, however. For example, if the stored procedure contains an MOREINFO="NONE"insert statement and the user does not have insert permission on the database table, the MOREINFO="NONE"insert statement will fail, but MOREINFO="NONE"dbsqlok will still return SUCCEED. To check for run-time errors inside stored procedures, use the MOREINFO="NONE"dbretstatus routine to look at the procedure's return status, and trap relevant server messages inside your message handler. CommentsMARK="BULL" REMAP="BU--Bullet"This routine waits for results from the server and verifies the correctness of the instructions that the server is responding to. REMAP="UN--Under"The "instructions that the server is responding to" can be any of the following: A command batch (when MOREINFO="NONE"dbsqlok is used with MOREINFO="NONE"dbsqlsend). ID="IN8111-223363404"Text valuesverifying correctness of
ID="IN8112-223363405"Image valuesverifying correctness ofMARK="DASH" REMAP="BS--BulletSub"Processing information for handling chunks of text or image data (when MOREINFO="NONE"dbsqlok is used with MOREINFO="NONE"dbmoretext). ID="IN8122-223363406"Remote procedure callsverifying correctness ofA remote procedure call (when MOREINFO="NONE"dbsqlok is used with MOREINFO="NONE"dbrpcsend). ID="IN819-231371407"dbsqlsenddbsqlsendand dbsqlokdbsqlok
ID="IN819-239379408"dbrpcsenddbrpcsendand dbsqlokdbsqlok
ID="IN8110-247387409"dbmoretextdbmoretextand dbsqlokdbsqlokThe application must call MOREINFO="NONE"dbsqlok after a call to MOREINFO="NONE"dbsqlsend or MOREINFO="NONE"dbrpcsend, and before and after a set of MOREINFO="NONE"dbmoretext calls. A successful MOREINFO="NONE"dbsqlok call must always be followed by a call to MOREINFO="NONE"dbresults to process the results. MOREINFO="NONE"dbsqlexec is equivalent to MOREINFO="NONE"dbsqlsend followed by MOREINFO="NONE"dbsqlok. ID="IN8114-251391410"Output streamsutilizing multiple (UNIX and AOS/VS) 
ID="IN8113-255395411"Input streamsutilizing multiple (UNIX and AOS/VS) The use of MOREINFO="NONE"dbsqlsend with MOREINFO="NONE"dbsqlok  is of particular value in UNIX and AOS/VS applications. After sending a query to the server, MOREINFO="NONE"dbsqlexec waits until a response is received or until the timeout period has elapsed. By substituting MOREINFO="NONE"dbsqlsend and MOREINFO="NONE"dbsqlok  for MOREINFO="NONE"dbsqlexec, you can sometimes provide a way for a UNIX or AOS/VS application to respond more effectively to multiple input and output streams. The time between the request for information from the server (made via a call to MOREINFO="NONE"dbsqlsend) and the server's response (read by calling MOREINFO="NONE"dbsqlok) can be used, in conjunction  with MOREINFO="NONE"DBIORDESC, MOREINFO="NONE"dbpoll, or MOREINFO="NONE"DBIOWDESC, to service other parts of the application. MOREINFO="NONE"DBIORDESC and MOREINFO="NONE"DBIOWDESC are available for UNIX  and AOS/VS only. See the manual pages for those two routines for more information. To manage these streams efficiently, an application  that uses MOREINFO="NONE"dbsqlok should confirm that unread bytes are available either in the network buffer or in the network itself before calling  MOREINFO="NONE"dbsqlok or MOREINFO="NONE"dbresults. The application can either: MARK="DASH" REMAP="BS--BulletSub"Call MOREINFO="NONE"DBRBUF (UNIX and AOS/VS only) to  test whether bytes remain in the network buffer, and call MOREINFO="NONE"DBIORDESC and the UNIX MOREINFO="NONE"select or AOS/VS equivalent to test whether bytes remain in the network itself; or Call MOREINFO="NONE"dbpoll.  On occasion the operating system may inform the application that data is ready for MOREINFO="NONE"dbsqlok to read when only the first part of the server response is present. When this occurs, MOREINFO="NONE"dbsqlok waits for the rest of the response or until the timeout period has elapsed, just like MOREINFO="NONE"dbsqlexec. In practice, however, the entire response is usually available at one time. MOREINFO="NONE"dbsqlok is also useful in text update operations. When chunks of text are sent to the server via MOREINFO="NONE"dbwritetext and MOREINFO="NONE"dbmoretext, MOREINFO="NONE"dbsqlok must be called before the first call to MOREINFO="NONE"dbmoretext and after the last call to MOREINFO="NONE"dbmoretext. For an example of its use in this context, see the manual page for MOREINFO="NONE"dbwritetext. MOREINFO="NONE"dbsqlok is also necessary when making remote procedure calls. The application must call it after MOREINFO="NONE"dbrpcsend and before MOREINFO="NONE"dbresults. See AlsoREMAP="BO--Body"LINKEND="X41151"dbcmd
, LINKEND="X29834"dbfcmd
, LINKEND="X41944"DBIORDESC (UNIX and AOS/VS)
, LINKEND="X19954"DBIOWDESC (UNIX and AOS/VS)
, LINKEND="X96538"dbmoretext
, LINKEND="X10726"dbnextrow
, LINKEND="X45215"dbpoll
, LINKEND="X55434"DBRBUF (UNIX and AOS/VS)
, LINKEND="X35104"dbresults
, LINKEND="X95390"dbretstatus
, LINKEND="X71145"dbrpcsend
, LINKEND="X68770"dbsettime
, LINKEND="X41234"dbsqlexec
, LINKEND="X49376"dbsqlsend
, LINKEND="X38408"dbwritetext
ID="IN817-258398413"dbsqlok
 ID="IN8115-261401414"dbsqlok_a (VMS)ID="X70305"dbsqlok_a  (VMS only)ID="IN8215-261402416"Command batchesverifying correctness of
Wait for results from the server and verify the correctness of the instructions asynchronously. FORMAT="LINESPECIFIC"RETCODE dbsqlok_a(dbproc, final_result, ast_proc,                   ast_param)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"RETCODE       *final_result;FORMAT="LINESPECIFIC"void          (*ast_proc)();FORMAT="LINESPECIFIC"BYTE          *ast_param;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. final_result - A pointer to a RETCODE which is set to SUCCEED or FAIL if MOREINFO="NONE"dbsqlok_a returns SUCCEED. *final_result will be set to SUCCEED if the server determines that the command batch is correct. The most common reason that *final_result gets set to FAIL is a SQL syntax error. *final_result also gets set to FAIL if there are semantic errors, such as incorrect column or table names. Failure occurs if any of the commands in the batch contains a semantic or syntax error. REMAP="UN--Under"In addition, a run-time error, such as a database protection violation, will set *final_result to FAIL if the command buffer contains only a single command. If the command buffer contains multiple commands, a run-time error will not set *final_result to FAIL. Instead, failure will occur with the MOREINFO="NONE"dbresults or MOREINFO="NONE"dbresults_a call that processes the command causing the run-time error. REMAP="UN--Under"The situation is a bit more complicated for run-time errors and stored procedures. A run-time error on an MOREINFO="NONE"execute command may set *final_result to FAIL, in accordance with the rule given in the previous paragraph. A run-time error on a statement inside a stored procedure will not set *final_result to FAIL, however. For example, if the stored procedure contains an MOREINFO="NONE"insert statement and the user does not have insert permission on the database table, the MOREINFO="NONE"insert statement will fail, but *final_result will still be set to SUCCEED. To check for run-time errors inside stored procedures, use the MOREINFO="NONE"dbretstatus routine to look at the procedure's return status, and trap relevant server messages inside your message handler. ast_proc - A pointer to a user-supplied routine that will be queued when the correctness of the command batch is finally determined by the server.  *final_result will always be set before this procedure is invoked. ast_param - A generic BYTE pointer that will be passed to the user-supplied ast_proc(). ast_param allows the user to pass any parameter or structure to the ast_proc routine. ReturnsREMAP="BO--Body"SUCCEED or FAIL. The most common reason for failing is that DB-Library/C is not in a state where it expects data from the server. CommentsMARK="BULL" REMAP="BU--Bullet"This routine is the asynchronous version of MOREINFO="NONE"dbsqlok. It asynchronously verifies the correctness of the instructions that the server is responding to. REMAP="UN--Under"The "instructions that the server is responding to" can be any of the following: MARK="DASH" REMAP="BS--BulletSub"A command batch (when MOREINFO="NONE"dbsqlok_a is used with MOREINFO="NONE"dbsqlsend). ID="IN8211-261402421"Text valuesverifying correctness of
ID="IN8212-261402422"Image valuesverifying correctness ofProcessing information for handling chunks of text or image data (when MOREINFO="NONE"dbsqlok_a is used with MOREINFO="NONE"dbmoretext). ID="IN8222-261402423"Remote procedure callsverifying correctness ofA remote procedure call (when MOREINFO="NONE"dbsqlok_a is used with MOREINFO="NONE"dbrpcsend). ID="IN829-269410424"dbsqlsenddbsqlsendand dbsqlok_adbsqlok_a
ID="IN829-277418425"dbrpcsenddbrpcsendand dbsqlok_adbsqlok_a
ID="IN8210-285426426"dbmoretextdbmoretextand dbsqlok_adbsqlok_aThe application must call MOREINFO="NONE"dbsqlok_a after a call to MOREINFO="NONE"dbsqlsend or MOREINFO="NONE"dbrpcsend, and before and after a set of MOREINFO="NONE"dbmoretext calls. A successful MOREINFO="NONE"dbsqlok_a call must always be followed by a call to MOREINFO="NONE"dbresults or MOREINFO="NONE"dbresults_a to process the results. MOREINFO="NONE"dbsqlexec_a is equivalent to MOREINFO="NONE"dbsqlsend followed by MOREINFO="NONE"dbsqlok_aID="IN8214-289430427"Output streamsutilizing multiple (UNIX and AOS/VS) 
ID="IN8213-293434428"Input streamsutilizing multiple (UNIX and AOS/VS)
. On occasion the operating system may inform the application that data is ready for MOREINFO="NONE"dbsqlok_a to read when only the first part of the server response is present. When this occurs, MOREINFO="NONE"dbsqlok_a waits for the rest of the response or until the timeout period has elapsed, just like MOREINFO="NONE"dbsqlexec. In practice, however, the entire response is usually available at one time. MOREINFO="NONE"dbsqlok_a is also useful in text update operations. When chunks of text are sent to the server via MOREINFO="NONE"dbwritetext and MOREINFO="NONE"dbmoretext, MOREINFO="NONE"dbsqlok_a must be called before the first call to MOREINFO="NONE"dbmoretext and after the last call to MOREINFO="NONE"dbmoretext. MOREINFO="NONE"dbsqlok_a is also useful when making remote procedure calls. The application can call it after MOREINFO="NONE"dbrpcsend and before MOREINFO="NONE"dbresults or MOREINFO="NONE"dbresults_a. See AlsoREMAP="BO--Body"LINKEND="X41151"dbcmd
, LINKEND="X29834"dbfcmd
, LINKEND="X41944"DBIORDESC (UNIX and AOS/VS)
, LINKEND="X19954"DBIOWDESC (UNIX and AOS/VS)
, LINKEND="X96538"dbmoretext
, LINKEND="X10726"dbnextrow
, LINKEND="X90089"dbnextrow_a (VMS only)
, LINKEND="X45215"dbpoll
, LINKEND="X41324"dbpoll_a (VMS only)
, LINKEND="X55434"DBRBUF (UNIX and AOS/VS)
, LINKEND="X35104"dbresults
, LINKEND="X81070"dbresults_a (VMS only)
, LINKEND="X95390"dbretstatus
, LINKEND="X71145"dbrpcsend
, LINKEND="X68770"dbsettime
, LINKEND="X41234"dbsqlexec
, LINKEND="X34208"dbsqlexec_a (VMS only)
, LINKEND="X49376"dbsqlsend
, LINKEND="X38408"dbwritetext
ID="IN8215-296437430"dbsqlok_a (VMS)
 ID="IN829-299440431"dbsqlsendID="X49376"dbsqlsendID="IN8315-299441433"Command batchessending to the server
Send a command batch to the server and do not wait for a response. FORMAT="LINESPECIFIC"RETCODE dbsqlsend(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS      *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. ReturnsREMAP="BO--Body"SUCCEED or FAIL. MOREINFO="NONE"dbsqlsend may fail if previous results had not been processed, or if the command buffer was empty. CommentsMARK="BULL" REMAP="BU--Bullet"This routine sends SQL commands, stored in the command buffer, to the server. The application can add commands to the command buffer by calling MOREINFO="NONE"dbcmd or MOREINFO="NONE"dbfcmd. Once MOREINFO="NONE"dbsqlsend returns SUCCEED, the application must call MOREINFO="NONE"dbsqlok to verify the accuracy of the command batch. The application can then call MOREINFO="NONE"dbresults to process the results. MOREINFO="NONE"dbsqlexec is equivalent to MOREINFO="NONE"dbsqlsend followed by MOREINFO="NONE"dbsqlok. ID="IN8314-303445438"Output streamsutilizing multiple (UNIX and AOS/VS) 
ID="IN8313-307449439"Input streamsutilizing multiple (UNIX and AOS/VS)The use of MOREINFO="NONE"dbsqlsend with MOREINFO="NONE"dbsqlok is of particular value in UNIX and AOS/VS applications. After sending a query to the server, MOREINFO="NONE"dbsqlexec waits until a response is received or until the timeout period has elapsed. By substituting MOREINFO="NONE"dbsqlsend and MOREINFO="NONE"dbsqlok for MOREINFO="NONE"dbsqlexec, you can sometimes provide a way for a UNIX or AOS/VS application to respond more effectively to multiple input and output streams. The time between the request for information from the server (made via a call to MOREINFO="NONE"dbsqlsend) and the server's response (read by calling MOREINFO="NONE"dbsqlok) can be used, in conjunction with MOREINFO="NONE"DBIORDESC or MOREINFO="NONE"DBIOWDESC, to service other parts of the application. MOREINFO="NONE"DBIORDESC and MOREINFO="NONE"DBIOWDESC are available for UNIX  and AOS/VS only. See the manual pages for those two routines for more information. See AlsoREMAP="BO--Body"LINKEND="X41151"dbcmd
, LINKEND="X29834"dbfcmd
, LINKEND="X41944"DBIORDESC (UNIX and AOS/VS)
, LINKEND="X19954"DBIOWDESC (UNIX and AOS/VS)
, LINKEND="X10726"dbnextrow
, LINKEND="X35104"dbresults
, LINKEND="X68770"dbsettime
, LINKEND="X41234"dbsqlexec
, LINKEND="X21206"dbsqlok
ID="IN839-310452441"dbsqlsend
 ID="IN8310-313455442"dbstrbuilddbstrbuildID="IN8414-313456444"Error handlingtranslating messages from one language to another
Build a printable string from text containing placeholders for variables. FORMAT="LINESPECIFIC"int dbstrbuild(dbproc, charbuf, bufsize,               text [, formats [, arg] ... ])FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"char          *charbuf;FORMAT="LINESPECIFIC"int           bufsize;FORMAT="LINESPECIFIC"char          *text;FORMAT="LINESPECIFIC"char          *formats;FORMAT="LINESPECIFIC"???           args???;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and the server. MOREINFO="NONE"dbstrbuild uses it only as a parameter to the programmer-installed error handler (if one exists) when an error occurs. charbuf - A pointer to the destination buffer that will contain the message built by MOREINFO="NONE"dbstrbuild. bufsize - The size of the destination buffer, in bytes. This size must include a single byte for the results string's NULL terminator. text - A pointer to a NULL-terminated character string that contains message text and place holders for variables. Place holders consist of a percent sign, an integer, and an exclamation point. The integer indicates which argument to substitute for a particular place holder. Arguments and format strings are numbered from left to right. Argument 1 is substituted for place holder "%1!", and so on. formats - A pointer to a NULL-terminated string containing one MOREINFO="NONE"sprintf-style format specifier for each place holder in the text string. args - The values which will be converted according to the contents of the formats string. There must be one arg for each format in the formats string. The first value will correspond to the "%1!" parameter, the second the "%2!", and so forth. The results are undefined if there are insufficient args for the format. If the format  is  exhausted while args remain, the excess args are simply ignored. ReturnsREMAP="BO--Body"The length of the resulting message string, not including the NULL terminator, on success; a negative integer on failure. CommentsMARK="BULL" REMAP="BU--Bullet"Parameters in error messages may occur in different orders in different languages. MOREINFO="NONE"dbstrbuild allows construction of error messages in an MOREINFO="NONE"sprintf-like fashion to insure easy translation of error messages from one language to another. MOREINFO="NONE"dbstrbuild builds a printable string from an error text that contains place holders for variables, a format string containing information about the types and appearances of those variables, and a variable number of arguments which provide actual values for those variables. Place holders for variables consist of a percent sign, an integer, and an exclamation point. The integer indicates which argument to substitute for a particular place holder. Arguments and format strings are numbered from left to right. Argument 1 is substituted for place holder "%1!", and so on. REMAP="UN--Under"For example, consider an error message which complains about a misused keyword in a stored procedure. The message requires three arguments: the misused keyword, the line in which the keyword occurs, and the name of the stored procedure in which the misuse occurs. In the English localization file, the message text might appear as: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"The keyword '%1!' is misused in line %2! of stored procedure '%3!' . REMAP="UN--Under"In the Yoda-speak localization file, the same message might appear as: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"In line '%2!' of stored procedure '%3!', the keyword '%1!' misused is. REMAP="UN--Under"The MOREINFO="NONE"dbstrbuild line for either of the above messages would be: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"dbstrbuild(dbproc, charbuf, BUFSIZE, <get the    message somehow>, "%s %d %s", keyword,    linenum, sp_name) REMAP="UN--Under"keyword is substituted for place holder "%1!", linenum is substituted for place holder "%2!", and sp_name is substituted for place holder "%3!". The following code fragment illustrates the use of MOREINFO="NONE"dbstrbuild to build messages. For simplicity, the text of the message is hard-coded. In practice, MOREINFO="NONE"dbstrbuild message texts come from a localization file. REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"char    charbuf[BUFSIZE]; int     linenum = 15; char    *filename = "myfile"; char    *dirname = "mydir"; REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"dbstrbuild (dbproc, charbuf, BUFSIZE,     "Unable to read line %1! of file %2! in \     directory %3!.", "%d %s %s", linenum,    filename, dirname); REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"printf(charbuf); MOREINFO="NONE"dbstrbuild format specifiers may be separated by any other characters, or they may be adjacent to each other. This allows pre-existing English-language message strings to be used as MOREINFO="NONE"dbstrbuild format parameters. The first format specifier describes the "%1!" parameter, the second the "%2!" parameter, and so forth. See AlsoREMAP="BO--Body"LINKEND="X76814"dbconvert
, LINKEND="X58577"dbdatename
, LINKEND="X65989"dbdatepart
ID="IN8410-316459450"dbstrbuild
 ID="IN848-319462451"dbstrcmpID="X38801"dbstrcmpID="IN8511-319463453"Sort orderscomparing two character strings
Compare two character strings using a specified sort order. FORMAT="LINESPECIFIC"int dbstrcmp(dbproc, str1, len1, str2, len2, sortorder)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"char          *str1;FORMAT="LINESPECIFIC"int           len1;FORMAT="LINESPECIFIC"char          *str2;FORMAT="LINESPECIFIC"int           len2;FORMAT="LINESPECIFIC"DBSORTORDER   *sortorder;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. str1 - A pointer to the first character string to compare. str1 may be NULL. len1 - The length, in bytes, of str1. If len1 is -1, str1 is assumed to be NULL-terminated. str2 - A pointer to the second character string to compare. str2 may be NULL. len2 - The length, in bytes, of str2. If len2 is -1, str2 is assumed to be NULL-terminated. sortorder - A pointer to a DBSORTORDER structure allocated via MOREINFO="NONE"dbloadsort. If sortorder is NULL, MOREINFO="NONE"dbstrcmp compares str1 and str2 using their binary values, just as MOREINFO="NONE"strcmp does. ReturnsREMAP="BO--Body"1 if str1 is lexicographically greater than str2. 0 if str1 is lexicographically equal to str2. -1 if str1 is lexicographically less than str2. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbstrcmp compares str1 and str2 and returns an integer greater than, equal to, or less than 0, according to whether str1 is lexicographically greater than, equal to, or less than str2. MOREINFO="NONE"dbstrcmp uses a sort order that was retrieved from the server via MOREINFO="NONE"dbloadsort. This allows DB-Library application programs to compare strings using the same sort order as the server. Note that some languages contain strings which are lexicographically equal according to some specified sort-order, but contain different characters. Even though they are "equal," there is a standard order that should be used when placing them into an ordered list. When given two strings like this to compare, MOREINFO="NONE"dbstrcmp returns 0 (indicating the two strings are equal), but MOREINFO="NONE"dbstrsort returns some non-zero value indicating that one of these strings should appear before the other in a sorted list. REMAP="UN--Under"Below is an example of this behavior. The two English-language character strings are used with a case-insensitive sort order which specifies that upper case characters should appear before lower case: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"/* This call returns 0: */ dbstrcmp(dbproc, "ABC", 3, "abc", 3, mysort);  /* This call returns a negative value: */ dbstrsort(dbproc, "ABC", 3, "abc", 3, mysort); See AlsoREMAP="BO--Body"LINKEND="X50825"dbfreesort
, LINKEND="X42259"dbloadsort
, LINKEND="X41485"dbstrsort
ID="IN858-322466459"dbstrcmp
 ID="IN858-325469460"dbstrcpyID="X48259"dbstrcpyID="IN8615-325470462"Command bufferscopying portions of
Copy a portion of the command buffer. FORMAT="LINESPECIFIC"RETCODE dbstrcpy(dbproc, start, numbytes, dest)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"int           start;FORMAT="LINESPECIFIC"int           numbytes;FORMAT="LINESPECIFIC"char          *dest;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. start - Indicates which character in the command buffer to start copying from. The first character is the 0'th character. If start is greater than the length of the command buffer, MOREINFO="NONE"dbstrcpy inserts a null terminator at dest[0]. numbytes - The number of characters to copy.  If numbytes is -1, MOREINFO="NONE"dbstrcpy will copy the entire command buffer, whether or not dest points to adequate space. It is legal to copy 0 bytes, in which case MOREINFO="NONE"dbstrcpy inserts a null terminator at dest[0].  If there are not numbytes available to copy, MOREINFO="NONE"dbstrcpy copies the number of bytes available and returns SUCCEED. dest - A pointer to the data space to copy the source string into. ReturnsREMAP="BO--Body"SUCCEED or FAIL. MOREINFO="NONE"dbstrcpy returns FAIL if start is negative. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbstrcpy copies a portion of the command buffer to a program variable. The copy is null-terminated. Internally, the command buffer is a linked list of non-null-terminated text strings. MOREINFO="NONE"dbgetchar, MOREINFO="NONE"dbstrcpy, and MOREINFO="NONE"dbstrlen together provide a way to locate and copy parts of the command buffer. MOREINFO="NONE"dbstrcpy assumes that the destination is large enough to receive the source string.  If not, a segmentation fault is likely. When numbytes is passed as -1, dbstrcpy copies the entire command buffer.  Do not pass numbytes as -1 unless you are certain that dest points to adequate space for this string.  See AlsoREMAP="BO--Body"LINKEND="X41151"dbcmd
, LINKEND="X29834"dbfcmd
, LINKEND="X18180"dbfreebuf
, LINKEND="X20172"dbgetchar
, LINKEND="X53545"dbstrlen
ID="IN868-328473468"dbstrcpy
 ID="IN868-331476469"dbstrlenID="X53545"dbstrlenID="IN8715-331477471"Command buffersreturning character length of
Return the length, in characters, of the command buffer. FORMAT="LINESPECIFIC"int dbstrlen(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. ReturnsREMAP="BO--Body"The length, in characters, of the command buffer. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbstrlen finds the length, in characters, of the command buffer. Internally, the command buffer is a linked list of non-null-terminated text strings. MOREINFO="NONE"dbgetchar, MOREINFO="NONE"dbstrcpy, and MOREINFO="NONE"dbstrlen together provide a way to locate and copy parts of the command buffer. See AlsoREMAP="BO--Body"LINKEND="X41151"dbcmd
, LINKEND="X29834"dbfcmd
, LINKEND="X18180"dbfreebuf
, LINKEND="X20172"dbgetchar
, LINKEND="X48259"dbstrcpy
ID="IN878-334480477"dbstrlen
 ID="IN879-337483478"dbstrsortID="X41485"dbstrsortID="IN8811-337484480"Sort ordersdetermining order of two character strings
Determine which of two character strings should appear first in a sorted list. FORMAT="LINESPECIFIC"int dbstrsort(dbproc, str1, len1, str2, len2, sortorder)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"char          *str1;FORMAT="LINESPECIFIC"int           len1;FORMAT="LINESPECIFIC"char          *str2;FORMAT="LINESPECIFIC"int           len2;FORMAT="LINESPECIFIC"DBSORTORDER   *sortorder;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. str1 - A pointer to the first character string to compare. str1 may be NULL. len1 - The length, in bytes, of str1. If len1 is -1, str1 is assumed to be NULL-terminated. str2 - A pointer to the second character string to compare. str2 may be NULL. len2 - The length, in bytes, of str2. If len2 is -1, str2 is assumed to be NULL-terminated. sortorder - A pointer to a DBSORTORDER structure allocated via MOREINFO="NONE"dbloadsort. If sortorder is NULL, MOREINFO="NONE"dbstrsort compares str1 and str2 using their binary values, just as MOREINFO="NONE"strcmp does. ReturnsREMAP="BO--Body"1 if str1 should appear after str2. 0 if str1 is identical to str2. -1 if str1 should appear before str2. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbstrsort compares str1 and str2 and returns an integer greater than, equal to, or less than 0, according to whether str1 should appear after, at the same place (the strings are identical), or before str2 in a sorted list. MOREINFO="NONE"dbstrsort uses a sort order that was retrieved from the server via MOREINFO="NONE"dbloadsort. This allows DB-Library application programs to compare strings using the same sort order as the server. Note that some languages contain strings which are lexicographically equal according to some specified sort-order, but contain different characters. Even though they are "equal," there is a standard order that should be used when placing them into an ordered list. When given two strings like this to compare, MOREINFO="NONE"dbstrcmp returns 0 (indicating the two strings are equal), but MOREINFO="NONE"dbstrsort returns some non-zero value indicating that one of these strings should appear before the other in a sorted list. REMAP="UN--Under"Below is an example of this behavior. The two English-language character strings are used with a case-insensitive sort order specifies that upper case characters should appear before lower case: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"/* This call returns 0: */ dbstrcmp(dbproc, "ABC", 3, "abc", 3, mysort);  /* This call returns a negative value: */ dbstrsort(dbproc, "ABC", 3, "abc", 3, mysort); ID="IN888-345492485"dbstrcmpdbstrcmpand dbstrsortdbstrsortMOREINFO="NONE"dbstrsort can only be used to examine two character strings which have already been identified as equal via MOREINFO="NONE"dbstrcmp. If MOREINFO="NONE"dbstrcmp has not identified these strings as being equal to each other, MOREINFO="NONE"dbstrsort's behavior is undefined. See AlsoREMAP="BO--Body"LINKEND="X50825"dbfreesort
, LINKEND="X42259"dbloadsort
, LINKEND="X38801"dbstrcmp
ID="IN889-348495487"dbstrsort
 REMAP="BO--Body"ID="X58939"dbtabbrowseID="IN4369753"Tablesidentifying browsable
ID="IN43119754"Browse modeidentifying browsable tables
Determine whether the specified table is updatable via the DB-Library browse-mode facilities. FORMAT="LINESPECIFIC"DBBOOL dbtabbrowse(dbproc, tabnum)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"int           tabnum;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. tabnum - The number of the table of interest, as specified in the MOREINFO="NONE"select statement's MOREINFO="NONE"from clause. Table numbers start at 1. ReturnsREMAP="BO--Body"TRUE or FALSE. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbtabbrowse is one of the DB-Library browse mode routines. See the Introduction for a detailed discussion of browse mode. MOREINFO="NONE"dbtabbrowse provides a way to identify browsable tables. It is useful when examining ad hoc queries prior to performing browse mode updates based on them. If the query has been hardcoded into the program, this routine is obviously unnecessary. For a table to be considered "browsable," it must have a unique index and a timestamp column. The application can call MOREINFO="NONE"dbtabbrowse any time after MOREINFO="NONE"dbresults. Example 7 of the on-line example programs contains a call to MOREINFO="NONE"dbtabbrowse. See AlsoREMAP="BO--Body"LINKEND="X60561"dbcolbrowse
, LINKEND="X78078"dbcolsource
, LINKEND="X46501"dbqual
, LINKEND="X52066"dbtabcount
, LINKEND="X84917"dbtabname
, LINKEND="X67923"dbtabsource
, LINKEND="X78355"dbtsnewlen
, LINKEND="X32220"dbtsnewval
, LINKEND="X11575"dbtsput
ID="IN431194810"dbtabbrowse
 ID="IN4310911111"dbtabcountID="X52066"dbtabcount
Return the number of tables involved in the current MOREINFO="NONE"selectID="IN446891413"Tablesreturning number involved in a select query
 query. FORMAT="LINESPECIFIC"int dbtabcount(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. ReturnsREMAP="BO--Body"The number of tables, including server work tables, involved in the current set of row results. REMAP="BO--Body"MOREINFO="NONE"dbtabcount will return -1 in case of error. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbtabcount is one of the DB-Library browse mode routines. It is usable only with results from a browse-mode MOREINFO="NONE"select (i.e., a MOREINFO="NONE"select containing the key words MOREINFO="NONE"for MOREINFO="NONE"browse). See the Introduction for a detailed discussion of browse mode. ID="IN4411891418"Browse modedetermining number of tables involvedA MOREINFO="NONE"select query can generate a set of result rows whose columns are derived from several database tables. To perform browse-mode updates of columns in a query's select-list, the application must know how many tables were involved in the query, because each table requires a separate MOREINFO="NONE"update statement. MOREINFO="NONE"dbtabcount can provide this information for ad hoc queries. If the query has been hardcoded into the program, this routine is obviously unnecessary. ID="IN446891419"Tablesserver work
ID="IN449812220"dbtabnamedbtabnameand dbtabcountdbtabcountThe count returned by this routine includes any server "work tables" used in processing the query. The server sometimes creates temporary, internal work tables to process a query. It deletes these work tables by the time it finishes processing the statement. Work tables are not updatable and are not available to the application. Therefore, before using a table number, the application must make sure that it does not belong to a work table. MOREINFO="NONE"dbtabname can be used to determine whether a particular table number refers to a work table. The application can call MOREINFO="NONE"dbtabcount any time after MOREINFO="NONE"dbresults. Example 7 of the on-line example programs contains a call to MOREINFO="NONE"dbtabcount. See AlsoREMAP="BO--Body"LINKEND="X60561"dbcolbrowse
, LINKEND="X78078"dbcolsource
, LINKEND="X46501"dbqual
, LINKEND="X58939"dbtabbrowse
, LINKEND="X84917"dbtabname
, LINKEND="X67923"dbtabsource
, LINKEND="X78355"dbtsnewlen
, LINKEND="X32220"dbtsnewval
, LINKEND="X11575"dbtsput
ID="IN4410782522"dbtabcount
 ID="IN449752823"dbtabnameID="X84917"dbtabnameID="IN456752925"Tablesreturning name of
ID="IN456752926"Tablesserver work:determining
Return the name of a table based on its number. FORMAT="LINESPECIFIC"char *dbtabname(dbproc, tabnum)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"int           tabnum;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. tabnum - The number of the table of interest. Table numbers start with 1. Use MOREINFO="NONE"dbtabcount to find out the total number of tables involved in a particular query. ReturnsREMAP="BO--Body"A pointer to the null-terminated name of the specified table. This pointer will be NULL if the table number is out of range or if the specified table is a server work table. See the MOREINFO="NONE"dbtabcount manual page for a description of work tables. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbtabname is one of the DB-Library browse mode routines. It is usable only with results from a browse-mode MOREINFO="NONE"select (i.e., a MOREINFO="NONE"select containing the key words MOREINFO="NONE"for MOREINFO="NONE"browse). See the Introduction for a detailed discussion of browse mode. A MOREINFO="NONE"select query can generate a set of result rows whose columns are derived from several database tables. MOREINFO="NONE"dbtabname provides a way for an application to determine the name of each table involved in an ad hoc query. If the query has been hardcoded into the program, this routine is obviously unnecessary. The application can call MOREINFO="NONE"dbtabname any time after MOREINFO="NONE"dbresults. Example 7 of the on-line example programs contains a call to MOREINFO="NONE"dbtabname. See AlsoREMAP="BO--Body"LINKEND="X60561"dbcolbrowse
, LINKEND="X78078"dbcolsource
, LINKEND="X46501"dbqual
, LINKEND="X58939"dbtabbrowse
, LINKEND="X52066"dbtabcount
, LINKEND="X67923"dbtabsource
, LINKEND="X78355"dbtsnewlen
, LINKEND="X32220"dbtsnewval
, LINKEND="X11575"dbtsput
ID="IN459723232"dbtabname
 ID="IN4511693533"dbtabsourceID="X67923"dbtabsourceID="IN4614693635"Result columnsreturning name and number of source table
ID="IN466693636"Tablesreturning name and number associated with result columns
Return the name and number of the table from which a particular result column was derived. FORMAT="LINESPECIFIC"char *dbtabsource(dbproc, colnum, tabnum)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS      *dbproc;FORMAT="LINESPECIFIC"int            colnum;FORMAT="LINESPECIFIC"int            *tabnum;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. colnum - The number of the result column of interest. Column numbers start at 1. tabnum - A pointer to an integer, which will be filled in with the table's number.  Many DB-Library routines that deal with browse mode accept either a table name or a table number. If MOREINFO="NONE"dbtabsource returns NULL (see below), *tabnum will be set to -1. ReturnsREMAP="BO--Body"A pointer to the name of the table from which this result column was derived. A NULL return value can mean a few different things: MARK="BULL" REMAP="BU--Bullet"The DBPROCESS is dead or not enabled. This is an error that will cause an application's error handler to be invoked. The column number is out of range. The column is the result of an expression, such as "max(colname)". CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbtabsource is one of the DB-Library browse mode routines. It is usable only with results from a browse-mode MOREINFO="NONE"select (i.e., a MOREINFO="NONE"select containing the key words MOREINFO="NONE"for MOREINFO="NONE"browse). See the Introduction for a detailed discussion of browse mode. MOREINFO="NONE"dbtabsource allows an application to determine which tables provided the columns in the current set of result rows. This information is valuable when using MOREINFO="NONE"dbqual to construct MOREINFO="NONE"where clauses for MOREINFO="NONE"update and MOREINFO="NONE"delete statements based on ad hoc queries. If the query has been hardcoded into the program, this routine is obviously unnecessary. The application can call MOREINFO="NONE"dbtabsource any time after MOREINFO="NONE"dbresults. Example 7 of the on-line example programs contains a call to MOREINFO="NONE"dbtabsource. See AlsoREMAP="BO--Body"LINKEND="X60561"dbcolbrowse
, LINKEND="X78078"dbcolsource
, LINKEND="X46501"dbqual
, LINKEND="X58939"dbtabbrowse
, LINKEND="X52066"dbtabcount
, LINKEND="X84917"dbtabname
, LINKEND="X78355"dbtsnewlen
, LINKEND="X32220"dbtsnewval
ID="IN4611663942"dbtabsource
 ID="IN465644143"DBTDSID="X51451"DBTDSID="IN4728644245"Tabular Data Stream protocoldetermining version being used
Determine which version of TDS (the Tabular Data Stream protocol) is being used. FORMAT="LINESPECIFIC"int DBTDS(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. ReturnsREMAP="BO--Body"The version of TDS used by dbproc to communicate with the server. Currently, the possible versions are: MARK="DASH" REMAP="BS--BulletSub"DBTDS_2_0 DBTDS_3_4 DBTDS_4_0 DBTDS_4_2 REMAP="BO--Body"DBTDS returns a negative integer on error. CommentsID="IN4728644250"Tabular Data Stream protocolversions availableMARK="BULL" REMAP="BU--Bullet"DBTDS returns the version of TDS (Tabular Data Stream protocol) being used by dbproc to communicate with the server. See AlsoREMAP="BO--Body"LINKEND="X29357"dbversion
ID="IN4710614552"dbtextsizedbtextsizeID="IN4811614654"Text valuesbytes left of
ID="IN4812614655"Image valuesbytes left of
Return the number of text/image bytes that remain to be read for the current row.FORMAT="LINESPECIFIC"DBINT dbtextsize(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and server. ReturnsREMAP="BO--Body"The following table lists the return values for MOREINFO="NONE"dbtextsize: TOCENTRY="1"LBL="Table 2-39: "Return values (MOREINFO="NONE"dbtextsize)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="112*"COLNAME="C2" COLWIDTH="247*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="CENTER" ROTATE="0" MOREROWS="0"Return ValueCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="CENTER" ROTATE="0" MOREROWS="0">= 0COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The number of bytes that remain to be read. Zero 
indicates NO_MORE_ROWS.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C1" ALIGN="CENTER" ROTATE="0" MOREROWS="0"-1COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An error has occurred.COLNAME="C1" ALIGN="CENTER" ROTATE="0" MOREROWS="0"-2COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"dbtextsize has been called for RPC data.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbtextsize assumes that there is only one column and that this column is of type text or image.MOREINFO="NONE"dbtextsize is useful when an application does not know how large a text or image value is.MOREINFO="NONE"dbtextsize does not work with RPC text data.See AlsoREMAP="BO--Body"LINKEND="X51086"dbreadtext
ID="IN4810584961"dbtsnewlenID="X78355"dbtsnewlenID="IN4917585063"Timestamp columnsreturning length of after update
Return the length of the new value of the timestamp column after a browse-mode update. FORMAT="LINESPECIFIC"int dbtsnewlen(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. ReturnsREMAP="BO--Body"The length (in bytes) of the updated row's new timestamp value. If no timestamp was returned to the application (possibly because the update was unsuccessful, or because the MOREINFO="NONE"update statement did not contain the MOREINFO="NONE"tsequal built-in function), MOREINFO="NONE"dbtsnewlen will return -1. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbtsnewlen is one of the DB-Library browse mode routines. See the Introduction for a detailed discussion of browse mode. MOREINFO="NONE"dbtsnewlen provides information about the timestamp column. The MOREINFO="NONE"where clause returned by MOREINFO="NONE"dbqual contains a call to the MOREINFO="NONE"tsequal built-in function. When such a MOREINFO="NONE"where clause is used in an MOREINFO="NONE"update statement, the MOREINFO="NONE"tsequal function places a new value in the updated row's timestamp column and returns the new timestamp value to the application (if the update is successful). The MOREINFO="NONE"dbtsnewlen function allows the application to save the length of the new timestamp value, possibly for use with MOREINFO="NONE"dbtsput. See AlsoREMAP="BO--Body"LINKEND="X60561"dbcolbrowse
, LINKEND="X78078"dbcolsource
, LINKEND="X46501"dbqual
, LINKEND="X58939"dbtabbrowse
, LINKEND="X52066"dbtabcount
, LINKEND="X84917"dbtabname
, LINKEND="X67923"dbtabsource
, LINKEND="X32220"dbtsnewval
, LINKEND="X11575"dbtsput
ID="IN4910555369"dbtsnewlen
 ID="IN4910525670"dbtsnewvalID="X32220"dbtsnewvalID="IN5017525772"Timestamp columnsreturning value of after update
Return the new value of the timestamp column after a browse-mode update. FORMAT="LINESPECIFIC"DBBINARY *dbtsnewval(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. ReturnsREMAP="BO--Body"A pointer to the updated row's new timestamp value. If no timestamp was returned to the application (possibly because the update was unsuccessful, or because the MOREINFO="NONE"update statement did not contain the MOREINFO="NONE"tsequal built-in function), the pointer will be NULL. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbtsnewval is one of the DB-Library browse mode routines. See the Introduction for a detailed discussion of browse mode. MOREINFO="NONE"dbtsnewval provides information about the timestamp column. The MOREINFO="NONE"where clause returned by MOREINFO="NONE"dbqual contains a call to the MOREINFO="NONE"tsequal built-in function. When such a MOREINFO="NONE"where clause is used in an MOREINFO="NONE"update statement, the MOREINFO="NONE"tsequal function places a new value in the updated row's timestamp column and returns the new timestamp value to the application (if the update is successful). This routine allows the application to save the new timestamp value, possibly for use with MOREINFO="NONE"dbtsput. See AlsoREMAP="BO--Body"LINKEND="X58939"dbtabbrowse
, LINKEND="X67923"dbtabsource
, LINKEND="X46501"dbqual
, LINKEND="X58939"dbtabbrowse
, LINKEND="X52066"dbtabcount
, LINKEND="X84917"dbtabname
, LINKEND="X67923"dbtabsource
, LINKEND="X78355"dbtsnewlen
, LINKEND="X11575"dbtsput
ID="IN5010496078"dbtsnewval
 ID="IN507466379"dbtsputID="X11575"dbtsput
Put the new value of the timestamp column into the given table's current row in the DBPROCESSID="IN5117446681"Timestamp columnsputting new value in DBPROCESS
. FORMAT="LINESPECIFIC"RETCODE dbtsput(dbproc, newts, newtslen, tabnum,                tabname)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"DBBINARY      *newts;FORMAT="LINESPECIFIC"int           newtslen;FORMAT="LINESPECIFIC"int           tabnum;FORMAT="LINESPECIFIC"char          *tabname;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. REMAP="UN--Under"This must be the DBPROCESS used to perform the original MOREINFO="NONE"select query. newts - A pointer to the new timestamp value. It is returned by MOREINFO="NONE"dbtsnewval. newtslen - The length of the new timestamp value. It is returned by MOREINFO="NONE"dbtsnewlen. tabnum - The number of the updated table. Table numbers start at 1. tabnum must refer to a browsable table. Use MOREINFO="NONE"dbtabbrowse to determine whether a table is browsable. REMAP="UN--Under"If this value is -1, the tabname parameter will be used to identify the table. tabname - A pointer to a null-terminated table name. tabname must refer to a browsable table. If this pointer is NULL, the tabnum parameter will be used to identify the table. ReturnsREMAP="BO--Body"SUCCEED or FAIL. The following situations will cause this routine to return FAIL: MARK="BULL" REMAP="BU--Bullet"The application tries to update the timestamp of a non-existent row. The application tries to update the timestamp using NULL as the timestamp value (newts). The specified table is non-browsable. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbtsput is one of the DB-Library browse mode routines. See the Introduction for a detailed discussion of browse mode. MOREINFO="NONE"dbtsput manipulates the timestamp column. The MOREINFO="NONE"where clause returned by MOREINFO="NONE"dbqual contains a call to the MOREINFO="NONE"tsequal built-in function. When such a MOREINFO="NONE"where clause is used in an MOREINFO="NONE"update statement, the MOREINFO="NONE"tsequal function places a new value in the updated row's timestamp column and returns the new timestamp value to the application (if the update is successful). If the same row is updated a second time, the MOREINFO="NONE"update statement's MOREINFO="NONE"where clause must use the latest timestamp value. REMAP="UN--Under"This routine updates the timestamp in the DBPROCESS for the row currently being browsed. Then, if the application needs to update the row a second time, it can call MOREINFO="NONE"dbqual to formulate a new MOREINFO="NONE"where clause that uses the new timestamp. See AlsoREMAP="BO--Body"LINKEND="X60561"dbcolbrowse
, LINKEND="X78078"dbcolsource
, LINKEND="X46501"dbqual
, LINKEND="X58939"dbtabbrowse
, LINKEND="X52066"dbtabcount
, LINKEND="X84917"dbtabname
, LINKEND="X67923"dbtabsource
, LINKEND="X78355"dbtsnewlen
, LINKEND="X32220"dbtsnewval
ID="IN517416987"dbtsput
 ID="IN517387288"dbtxptrID="X49629"dbtxptrID="IN5213387390"Text pointersreturning value of
Return the value of the text pointer for a column in the current row. FORMAT="LINESPECIFIC"DBBINARY *dbtxptr(dbproc, column)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"int           column; ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. column - The number of the select-list column of interest. Column numbers start at 1. ReturnsREMAP="BO--Body"A DBBINARY pointer to the text pointer for the column of interest. This pointer may be NULL. CommentsID="IN5211387395"Text valuesText valuesand text pointerstext pointers
ID="IN5212387396"Image valuesImage valuesand text pointerstext pointers
ID="IN5213387397"Text pointersMARK="BULL" REMAP="BU--Bullet"Every database column row of type SYBTEXT or SYBIMAGE has an associated text pointer, which uniquely identifies the text or image value. This text pointer is used by the MOREINFO="NONE"dbwritetext function to update text and image values. It's important that all the rows of the specified text or image column have valid text pointers. A text or image column row will have a valid text pointer if it contains data. However, if the text or image column row contains a null value, its text pointer will be valid only if the null value was explicitly entered with the MOREINFO="NONE"update statement. REMAP="UN--Under"Assume a table textnull with columns key and x, where x is a text column that permits nulls. The following statement assigns valid text pointers to the text column's rows: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"update textnull set x = null REMAP="UN--Under"On the other hand, the MOREINFO="NONE"insert of a null value into a text column does not provide a valid text pointer. This is true for an MOREINFO="NONE"insert of an explicit null or an MOREINFO="NONE"insert of an implicit null, such as the following: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"insert textnull (key) values (2) REMAP="UN--Under"When dealing with a null text or image value, be sure to use MOREINFO="NONE"update to get a valid text pointer. An application must MOREINFO="NONE"select a row containing a text or image value before calling MOREINFO="NONE"dbtxptr to return the associated text pointer. The MOREINFO="NONE"select causes a copy of the text pointer to be placed in the application's DBPROCESS.  The application can then retrieve this text pointer from the DBPROCESS via MOREINFO="NONE"dbtxptr. REMAP="UN--Under"If no MOREINFO="NONE"select is performed prior to the call to MOREINFO="NONE"dbtxptr, the call will result in a DB-Library error message. For an example that uses MOREINFO="NONE"dbtxptr, see the MOREINFO="NONE"dbwritetext manual page. See AlsoREMAP="BO--Body"LINKEND="X23507"dbtxtimestamp
, LINKEND="X38408"dbwritetext
ID="IN527357699"dbtxptr
 ID="IN52133279100"dbtxtimestampID="X23507"dbtxtimestampID="IN53153280102"Text timestampsreturning value of
ID="IN53113280103"Text valuesText valuesand text timestampstext timestamps
ID="IN53123280104"Image valuesImage valuesand text timestampstext timestamps
Return the value of the text timestamp for a column in the current row. FORMAT="LINESPECIFIC"DBBINARY *dbtxtimestamp(dbproc, column)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"int           column;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. column - The number of the select-list column of interest. Column numbers start at 1. ReturnsREMAP="BO--Body"A DBBINARY pointer to the text timestamp for the column of interest. This pointer may be NULL. CommentsID="IN53153280109"Text timestampsMARK="BULL" REMAP="BU--Bullet"Every database column of type SYBTEXT or SYBIMAGE has an associated text timestamp, which marks the time of the column's last modification. The text timestamp is useful in conjunction with the MOREINFO="NONE"dbwritetext function, to ensure that two competing application users do not inadvertently wipe out each other's modifications to the same value in the database. It is returned to the DBPROCESS when a Transact-SQL MOREINFO="NONE"select is performed on a SYBTEXT or SYBIMAGE column. The length of a non-NULL text timestamp is always DBTXTSLEN (currently defined as eight bytes). An application must MOREINFO="NONE"select a row containing a text or image value before calling MOREINFO="NONE"dbtxtimestamp to return the associated text  timestamp. The MOREINFO="NONE"select causes a copy of the text timestamp to be placed in the application's DBPROCESS.  The application can then retrieve this text timestamp from the DBPROCESS via MOREINFO="NONE"dbtxtimestamp. REMAP="UN--Under"If no MOREINFO="NONE"select is performed prior to the call to MOREINFO="NONE"dbtxtimestamp, the call will result in a DB-Library error message. For an example that uses MOREINFO="NONE"dbtxtimestamp, see the MOREINFO="NONE"dbwritetext manual page. See AlsoREMAP="BO--Body"LINKEND="X49629"dbtxptr
, LINKEND="X38408"dbwritetext
ID="IN53132983111"dbtxtimestamp
 ID="IN53122686112"dbtxtsnewvalID="X54400"dbtxtsnewval
Return the new value of a text timestamp after a call to MOREINFO="NONE"dbwritetextID="IN54152687114"Text timestampsreturning value of after update
. FORMAT="LINESPECIFIC"DBBINARY *dbtxtsnewval(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. ReturnsREMAP="BO--Body"A pointer to the new text timestamp value for the SYBTEXT or SYBIMAGE value modified by a MOREINFO="NONE"dbwritetext operation. This pointer may be NULL. CommentsMARK="BULL" REMAP="BU--Bullet"Every database column of type SYBTEXT or SYBIMAGE has an associated text timestamp, which is updated whenever the column's value is changed. The text timestamp is useful in conjunction with the MOREINFO="NONE"dbwritetext function, to ensure that two competing application users do not inadvertently wipe out each other's modifications to the same value in the database. It is returned to the DBPROCESS when a Transact-SQL MOREINFO="NONE"select is performed on a SYBTEXT or SYBIMAGE column and may be examined by calling MOREINFO="NONE"dbtxtimestamp. After each successful MOREINFO="NONE"dbwritetext operation (which may include a number of calls to MOREINFO="NONE"dbmoretext), the server will send the updated text timestamp value back to DB-Library. MOREINFO="NONE"dbtxtsnewval provides a way for the application to get this new timestamp value. The application can use MOREINFO="NONE"dbtxtsnewval in two ways. First, the return from MOREINFO="NONE"dbtxtsnewval can be used as the timestamp parameter of a MOREINFO="NONE"dbwritetext call. Second, MOREINFO="NONE"dbtxtsnewval and MOREINFO="NONE"dbtxtsput can be used together to put the new timestamp value into the DBPROCESS row buffer, for future access via MOREINFO="NONE"dbtxtimestamp. This is particularly useful when the application is buffering result rows and does not need the new timestamp immediately. See AlsoREMAP="BO--Body"LINKEND="X96538"dbmoretext
, LINKEND="X23507"dbtxtimestamp
, LINKEND="X86799"dbtxtsput
, LINKEND="X38408"dbwritetext
ID="IN54122390120"dbtxtsnewval
 ID="IN5492093121"dbtxtsputID="X86799"dbtxtsput
Put the new value of a text timestamp into the specified column of the current row in the DBPROCESSID="IN55151896123"Text timestampsputting new value into DBPROCESS
. FORMAT="LINESPECIFIC"RETCODE dbtxtsput(dbproc, newtxts, colnum)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"DBBINARY      *newtxts;FORMAT="LINESPECIFIC"int           colnum;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. newtxts - A pointer to the new text timestamp value. It is returned by MOREINFO="NONE"dbtxtsnewval. colnum - The number of the select-list column of interest.  Column numbers start at 1. ReturnsREMAP="BO--Body"SUCCEED or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"Every database column of type SYBTEXT or SYBIMAGE has an associated text timestamp, which is updated whenever the column's value is changed. The text timestamp is useful in conjunction with the MOREINFO="NONE"dbwritetext function, to ensure that two competing application users do not inadvertently wipe out each other's modifications to the same value in the database. It is returned to the DBPROCESS when a Transact-SQL MOREINFO="NONE"select is performed on a SYBTEXT or SYBIMAGE column and may be examined by calling MOREINFO="NONE"dbtxtimestamp. After each successful MOREINFO="NONE"dbwritetext operation (which may include a number of calls to MOREINFO="NONE"dbmoretext), the server will send the updated text timestamp value back to DB-Library. MOREINFO="NONE"dbtxtsnewval allows the application to get this new timestamp value. The application can then use MOREINFO="NONE"dbtxtsput to put the new timestamp value into the DBPROCESS row buffer, for future access via MOREINFO="NONE"dbtxtimestamp. This is particularly useful when the application is buffering result rows and does not need the new timestamp immediately. See AlsoREMAP="BO--Body"LINKEND="X96538"dbmoretext
, LINKEND="X23507"dbtxtimestamp
, LINKEND="X54400"dbtxtsnewval
, LINKEND="X38408"dbwritetext
ID="IN5591599129"dbtxtsput
ID="IN551113101130"Text valuesText valuesand text timestamps. See Text timestamps.text timestamps
ID="IN551211103131"Image valuesImage valuesand text timestamps. See Text timestamps.text timestamps
 ID="IN5558106132"dbuseID="X74526"dbuseID="IN5698107134"Databasesusing specified
Use a particular database. FORMAT="LINESPECIFIC"RETCODE dbuse(dbproc, dbname)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"char          *dbname;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. dbname - The name of the database to use. ReturnsREMAP="BO--Body"SUCCEED or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"This routine issues a Transact-SQL MOREINFO="NONE"use command for the specified database for a particular DBPROCESS. It sets up the command and calls MOREINFO="NONE"dbsqlexec and MOREINFO="NONE"dbresults. If the MOREINFO="NONE"use command fails because the requested database has not yet completed a recovery process, MOREINFO="NONE"dbuse will continue to send MOREINFO="NONE"use commands at one second intervals until it either succeeds or encounters some other error. The routine uses the dbproc provided by the caller.  It also uses the command buffer of that dbproc. MOREINFO="NONE"dbuse overwrites any existing commands in the buffer and clears the buffer when it is finished. See AlsoREMAP="BO--Body"LINKEND="X22834"dbchange
, LINKEND="X47894"dbname
ID="IN5655110140"dbuse
 ID="IN5692113141"dbvarylenID="X86715"dbvarylenID="IN57152114143"Regular columnsdetermining whether data length can vary
Determine whether the specified regular result column's data can vary in length. FORMAT="LINESPECIFIC"DBBOOL dbvarylen(dbproc, column)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"int           column;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. column - The number of the regular result column of interest. The first column is number 1. ReturnsREMAP="BO--Body"TRUE or FALSE, indicating whether or not the column's data can vary in length. MOREINFO="NONE"dbvarylen also returns FALSE if the column number is out of range. CommentsMARK="BULL" REMAP="BU--Bullet"This routine indicates whether a particular regular (i.e., non-compute) result column's data can vary in length. It will return TRUE if the result column is derived from a database column of type varchar, varbinary, text, image, boundary, or sensitivity. It will also return TRUE if the source database column is defined as NULL, meaning that it may contain a null value. This routine is useful with programs that handle ad hoc queries, if the program needs to be alerted to the possibility of null or variable length data. You can use MOREINFO="NONE"dbcoltype to get a column's datatype. See AlsoREMAP="BO--Body"LINKEND="X80379"dbcollen
, LINKEND="X83710"dbcolname
, LINKEND="X35574"dbcoltype
, LINKEND="X69467"dbdata
, LINKEND="X61322"dbdatlen
, LINKEND="X66483"dbnumcols
, LINKEND="X77266"dbprtype
, LINKEND="X91146"types
ID="IN579-1117149"dbvarylen
 ID="IN579-4120150"dbversionID="X29357"dbversionID="IN588-4121152"VersionsDB-Library:determining which
ID="IN5810-4121153"DB-Librarydetermining version in use
Determine which version of DB-Library is in use. FORMAT="LINESPECIFIC"char *dbversion()ParametersREMAP="BO--Body"None. ReturnsREMAP="BO--Body"A pointer to a character string containing which version of DB-Library is in use. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbversion returns a pointer to a character string that contains the version number for the DB-Library that is currently in use. See AlsoREMAP="BO--Body"LINKEND="X51451"DBTDS
ID="IN589-7124159"dbversion
 ID="IN5813-10127160"dbwillconvertID="X17556"dbwillconvertID="IN599-10128162"Datatypesdetermining supported conversions
Determine whether a specific datatype conversion is available within DB-Library. FORMAT="LINESPECIFIC"DBBOOL dbwillconvert(srctype, desttype)FORMAT="LINESPECIFIC"int     srctype;FORMAT="LINESPECIFIC"int     desttype;ParametersREMAP="RI--RefIndent"srctype - The datatype of the data which is to be converted. This parameter can be any of the server datatypes, as listed in the table below. desttype - The datatype that the source data is to be converted into. This parameter can be any of the server datatypes, as listed in the table below. ReturnsREMAP="BO--Body"TRUE if the datatype conversion is supported; FALSE if the conversion is not supported. CommentsMARK="BULL" REMAP="BU--Bullet"This routine allows the program to determine whether MOREINFO="NONE"dbconvert is capable of performing a specific datatype conversion. When MOREINFO="NONE"dbconvert is asked to perform a conversion that it doesn't support, it calls a user-supplied error handler (if any), sets a global error number, and returns FAIL. MOREINFO="NONE"dbconvert can convert data stored in any of the server datatypes (although, of course, not all conversions are legal): TOCENTRY="1"LBL="Table 2-40: "Server and DB-Library datatypes.COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="108*"COLNAME="C2" COLWIDTH="138*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Server typeCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Program variable type VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBCHARCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHAR COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBTEXTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHAR COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBBINARYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBBINARY COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBIMAGECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBBINARY COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBINT1COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBTINYINT COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBINT2COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBSMALLINT COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBINT4COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBINT COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBFLT8COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBFLT8 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBREALCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBREAL COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBNUMERICCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBNUMERICCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBDECIMALCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDECIMALCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBBITCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBBIT COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBMONEYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBMONEY COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBMONEY4COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBMONEY4 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBDATETIMECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATETIME COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBDATETIME4COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBDATETIME4 COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBBOUNDARYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBSENSITIVITYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBCHARThe table below lists the datatype conversions that MOREINFO="NONE"dbconvert and MOREINFO="NONE"dbconvert_ps support. The source datatypes are listed down the leftmost column and the destination datatypes are listed along the top row of the table. (For brevity, the prefix "SYB" has been eliminated from each datatype.) IfMOREINFO="NONE" dbwillconvert returns TRUE (T), the conversion is supported; if it returns FALSE (F), the conversion is not supported.FLOAT="0"FORMAT="UNKNOWN" FILEREF="fig2_3.xwd"LBL="Figure 2-3: "Supported datatype conversionsSee the manual pages for MOREINFO="NONE"dbconvert or MOREINFO="NONE"dbconvert_ps for more information on datatype conversions. See AlsoREMAP="BO--Body"LINKEND="X21854"dbaltbind
, LINKEND="X14206"dbbind
, LINKEND="X76814"dbconvert
, LINKEND="X80440"dbconvert_ps
, LINKEND="X91146"types
ID="IN5913-13131168"dbwillconvert
 ID="IN5911-16134169"dbwritepageID="X48593"dbwritepageID="IN6011-16135171"Binary datawriting page of to the server
ID="IN604-16135172"Databinary:writing page of to the server
Write a page of binary data to the server. FORMAT="LINESPECIFIC"RETCODE dbwritepage(dbproc, dbname, pageno, size, buf)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"char          *dbname;FORMAT="LINESPECIFIC"DBINT         pageno;FORMAT="LINESPECIFIC"DBINT         size;FORMAT="LINESPECIFIC"BYTE          buf[];ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. dbname - The name of the database of interest. pageno - The number of the database page to be written. size - The number of bytes to be written to the server. Currently, SQL Server database pages are 2048 bytes long. buf - A pointer to a buffer which holds the data to be written. ReturnsREMAP="BO--Body"SUCCEED or FAIL. CommentsMARK="BULL" REMAP="BU--Bullet"ID="IN609-16135177"Debuggingrepairing damaged database pages
MOREINFO="NONE"dbwritepage writes a page of binary data to the server. This routine is primarily useful for examining and repairing damaged database pages. After calling MOREINFO="NONE"dbwritepage, the DBPROCESS may contain some error or informational messages from the server. These messages may be accessed through a user-supplied message handler. Use this routine only if you are absolutely sure you know what you are doing! See AlsoREMAP="BO--Body"LINKEND="X78343"dbmsghandle
, LINKEND="X38277"dbreadpage
ID="IN6011-19138179"dbwritepage
 ID="IN6011-22141180"dbwritetextID="X38408"dbwritetextID="IN6111-22142182"Text valuesupdating
ID="IN6112-22142183"Image valuesupdating
Send a text or image value to the server. FORMAT="LINESPECIFIC"RETCODE dbwritetext(dbproc, objname, textptr,                     textptrlen, timestamp, log,                     size, text)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"char          *objname;FORMAT="LINESPECIFIC"DBBINARY      *textptr;FORMAT="LINESPECIFIC"DBTINYINT     textptrlen;FORMAT="LINESPECIFIC"DBBINARY      *timestamp;FORMAT="LINESPECIFIC"DBBOOL        log;FORMAT="LINESPECIFIC"DBINT         size;FORMAT="LINESPECIFIC"BYTE          *text;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and server. objname - The database table and column name of interest. The table and the column should be separated by a period ("."). textptr - A pointer to the text pointer of the text or image value to be modified. This can be obtained by calling MOREINFO="NONE"dbtxptr. The text pointer must be a valid one, as described on the MOREINFO="NONE"dbtxptr manual page. textptrlen - This parameter is included for future compatibility. For now, its value must be the defined constant DBTXPLEN. timestamp - A pointer to the text timestamp of the text or image value to be modified. This can be obtained via MOREINFO="NONE"dbtxtimestamp or MOREINFO="NONE"dbtxtsnewval. This value changes whenever the text or image value itself is changed. This parameter is optional and may be passed as NULL. log - A Boolean value, specifying whether this MOREINFO="NONE"dbwritetext operation should be recorded in the transaction log. size - The total size, in bytes, of the text or image value to be written. Since MOREINFO="NONE"dbwritetext uses this parameter as its only guide to determining how many bytes to send, size must not exceed the actual size of the value. text - A pointer to the text or image to be written. If this pointer is NULL, DB-Library will expect the application to call MOREINFO="NONE"dbmoretext one or more times, until all size bytes of data have been sent to the server. ReturnsREMAP="BO--Body"SUCCEED or FAIL. REMAP="BO--Body"A common cause for failure is an invalid timestamp parameter. This will occur if, between the time the application retrieves the text column and the time the application calls MOREINFO="NONE"dbwritetext to update it, a second application intervenes with its own update. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbwritetext updates SYBTEXT and SYBIMAGE values. It allows the application to send long values to the server without having to copy them into a Transact-SQL MOREINFO="NONE"update statement. In addition, MOREINFO="NONE"dbwritetext gives applications access to the text timestamp mechanism, which can be used to ensure that two competing application users do not inadvertently wipe out each other's modifications to the same value in the database. The timestamp parameter is optional. REMAP="UN--Under"If the timestamp parameter is supplied, MOREINFO="NONE"dbwritetext will succeed only if the value of the timestamp parameter matches the text column's timestamp in the database.  If a match occurs, MOREINFO="NONE"dbwritetext updates the text column, and at the same time updates the column's timestamp with the current time. This has the effect of governing updates by competing applications-an application's MOREINFO="NONE"dbwritetext call will fail if a second application updated the text column between the time the first application retrieved the column and the time it made its MOREINFO="NONE"dbwritetext call. REMAP="UN--Under"If the timestamp parameter is not supplied, MOREINFO="NONE"dbwritetext updates the text column regardless of the value of the column's timestamp. The value to use as the timestamp parameter is placed in an application's DBPROCESS when the application performs a MOREINFO="NONE"select on a text or image value.  It can be retrieved from the DBPROCESS via MOREINFO="NONE"dbtxtimestamp.   REMAP="UN--Under"In addition, after each successful MOREINFO="NONE"dbwritetext operation, which may include a number of calls to MOREINFO="NONE"dbmoretext, SQL Server sends a new text timestamp value back to DB-Library. MOREINFO="NONE"dbtxtsnewval provides a way for an application to retrieve this new value. MOREINFO="NONE"dbwritetext is similar in function to the Transact-SQL MOREINFO="NONE"writetext command. It is usually more efficient to call MOREINFO="NONE"dbwritetext than to send a MOREINFO="NONE"writetext command through the command buffer. In addition, MOREINFO="NONE"dbwritetext can handle columns up to 2 gigabytes in length, while MOREINFO="NONE"writetext data is limited to approximately 120K bytes. For more information on MOREINFO="NONE"writetext, see the  SQL Server Reference Manual. MOREINFO="NONE"dbwritetext can be invoked with or without logging, according to the value of the log parameter. REMAP="UN--Under"While logging aids media recovery, logging text data quickly increases the size of the transaction log. If you're logging MOREINFO="NONE"dbwritetext operations, make sure that the transaction log resides on a separate database device. See the System Administration Guide, MOREINFO="NONE"create MOREINFO="NONE"database in the  SQL Server Reference Manual, andMOREINFO="NONE" sp_logdevice in the  SQL Server Reference Manual for details. REMAP="UN--Under"To use MOREINFO="NONE"dbwritetext with logging turned off, the database option MOREINFO="NONE"select into/bulkcopy must be set to "true". The following SQL command will do this: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"sp_dboption 'mydb', 'select into/bulkcopy', 'true' REMAP="UN--Under"See the SQL Server Reference Manual for further details on MOREINFO="NONE"sp_dboption. The application can send a text or image value to the server all at once or a chunk at a time. MOREINFO="NONE"dbwritetext by itself handles sending an entire text or image value. The use of MOREINFO="NONE"dbwritetext with MOREINFO="NONE"dbmoretext allows the application to send a large text or image value to the server in the form of a number of smaller chunks. This is particularly useful with operating systems unable to allocate extremely long data buffers. To send an entire text or image value requires a non-NULL text parameter. Then, MOREINFO="NONE"dbwritetext will execute the data transfer from start to finish, including any necessary calls to MOREINFO="NONE"dbsqlok and MOREINFO="NONE"dbresults. Here's a code fragment that illustrates this use of MOREINFO="NONE"dbwritetext: REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"LOGINREC     *login; DBPROCESS    *q_dbproc; DBPROCESS    *u_dbproc; DBCHAR       abstract_var[512]; REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"/* Initialize DB-Library. */ if (dbinit() == FAIL)     exit(ERREXIT); REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"/* ** Open separate DBPROCESSes for querying and updating. ** This is not strictly necessary in this example, ** which retrieves only one row.  However, this ** approach becomes essential when performing updates ** on multiple rows of retrieved data. */ login = dblogin(); q_dbproc = dbopen(login, NULL); u_dbproc = dbopen(login, NULL); REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"/* The database column "abstract" is a text column. ** Retrieve the value of one of its rows. */ dbcmd(q_dbproc, "select abstract from articles where \     article_id = 10"); dbsqlexec(q_dbproc); dbresults(q_dbproc); dbbind(q_dbproc, 1, STRINGBIND, (DBINT) 0,    abstract_var); REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"/* ** For simplicity, we'll assume that just one row is** returned. */ dbnextrow(q_dbproc); REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"/* Here we can change the value of "abstract_var" */ /* For instance ... */ strcpy(abstract_var, "A brand new value."); REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"/* Update the text column */ dbwritetext (u_dbproc, "articles.abstract",    dbtxptr(q_dbproc, 1), DBTXPLEN,     dbtxtimestamp(q_dbproc, 1), TRUE,      (DBINT)strlen(abstract_var), abstract_var); REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"/* We're all done */ dbexit(); To send chunks of text or image, rather than the whole value at once, set the text parameter to NULL. Then, MOREINFO="NONE"dbwritetext will return control to the application immediately after notifying the server that a text transfer is about to begin. The actual text will be sent to the server with MOREINFO="NONE"dbmoretext, which can be called multiple times, once for each chunk. Here's a code fragment that illustrates the use of MOREINFO="NONE"dbwritetext with MOREINFO="NONE"dbmoretext: REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"LOGINREC     *login; DBPROCESS    *q_dbproc; DBPROCESS    *u_dbproc; DBCHAR       part1[512]; static DBCHAR   part2[512] = " This adds another \     sentence to the text."; REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"if (dbinit() == FAIL)     exit(ERREXIT); REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"login = dblogin(); q_dbproc = dbopen(login, NULL); u_dbproc = dbopen(login, NULL); REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"dbcmd(q_dbproc, "select abstract from articles where \     article_id = 10"); dbsqlexec(q_dbproc); dbresults(q_dbproc); dbbind(q_dbproc, 1, STRINGBIND, (DBINT) 0, part1); REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"/* ** For simplicity, we'll assume that just one row is** returned. */ dbnextrow(q_dbproc); REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"/* ** Here we can change the value of part of the text ** column. In this example, we will merely add a ** sentence to the end of the existing text. */ REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"/* Update the text column */ dbwritetext (u_dbproc, "articles.abstract",    dbtxptr(q_dbproc, 1), DBTXPLEN,     dbtxtimestamp(q_dbproc, 1), TRUE,     (DBINT)(strlen(part1) + strlen(part2)), NULL); REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"dbsqlok(u_dbproc); dbresults(u_dbproc); REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"/* Send the update value in chunks */ dbmoretext(u_dbproc, (DBINT)strlen(part1), part1); dbmoretext(u_dbproc, (DBINT)strlen(part2), part2); REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"dbsqlok(u_dbproc); dbresults(u_dbproc); REMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"dbexit(); REMAP="UN--Under"Note the required calls to MOREINFO="NONE"dbsqlok and MOREINFO="NONE"dbresults between the call to MOREINFO="NONE"dbwritetext and the first call to MOREINFO="NONE"dbmoretext, and after the final call to MOREINFO="NONE"dbmoretext. When MOREINFO="NONE"dbwritetext is used with MOREINFO="NONE"dbmoretext, it locks the specified database text column. The lock is not released until the final MOREINFO="NONE"dbmoretext has sent its data. This ensures that a second application does not read or update the text column in the midst of the first application's update. You cannot use MOREINFO="NONE"dbwritetext on text or image columns in views. The DB-Library/C option DBTEXTSIZE affects the value of the server @@textsize global variable, which restricts the size of text or image values that SQL Server returns. @@textsize has a default value of 32,768 bytes. An application that retrieves text or image values larger than 32,768 bytes will need to call MOREINFO="NONE"dbsetopt to make @@textsize larger. REMAP="UN--Under"The DB-Library/C option DBTEXTLIMIT limits the size of text or  image values that DB-Library/C will read. See AlsoREMAP="BO--Body"LINKEND="X96538"dbmoretext
, LINKEND="X49629"dbtxptr
, LINKEND="X23507"dbtxtimestamp
, LINKEND="X38408"dbwritetext
, LINKEND="X86799"dbtxtsput
ID="IN6111-25145189"dbwritetext
 ID="IN617-28148190"dbxlateID="X19114"dbxlateID="IN6217-28149192"Character stringstranslating from one character set to another
ID="IN6226-28149193"Character set translationsCharacter set translationsfor stringsstrings
Translate a character string from one character set to another. FORMAT="LINESPECIFIC"int dbxlate(dbproc, src, srclen, dest, destlen, xlt,            srcbytes_used, srcend, status)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     dbproc;FORMAT="LINESPECIFIC"char          *src;FORMAT="LINESPECIFIC"int           srclen;FORMAT="LINESPECIFIC"char          *dest;FORMAT="LINESPECIFIC"int           destlen;FORMAT="LINESPECIFIC"DBXLATE       *xlt;FORMAT="LINESPECIFIC"int           *srcbytes_used;FORMAT="LINESPECIFIC"DBBOOL        srcend;FORMAT="LINESPECIFIC"int           *status;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and the server. src - A pointer to the string to be translated. srclen - The length, in bytes, of src. If srclen is -1, src is assumed to be NULL-terminated. dest - A pointer to the buffer to contain the translated string, including a null terminator. destlen - The size, in bytes, of the buffer to contain the translated string. If destlen is -1, dest is assumed to be large enough to hold the translated string and its null terminator. xlt - A pointer to a translation structure used to translate character strings from one character set to another. The translation structure is allocated via MOREINFO="NONE"dbload_xlate. srcbytes_used - The number of bytes actually translated. If the fully translated string would overflow dest, MOREINFO="NONE"dbxlate translates only as much of src as will fit. If destlen is -1, srcbytes_used is srclen. srcend - A BOOLEAN value indicating whether or not more data is arriving. If srcend is TRUE, no more data is arriving. If srcend is FALSE, src is part of a larger string of data to be translated, and it is not the end of the string. status - A pointer to a code indicating the status of the translated character string. The following table lists the possible values for status: TOCENTRY="1"LBL="Table 2-41: "Values for status.COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="99*"COLNAME="C2" COLWIDTH="261*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Value of status:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBXLATE_XOFCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The translated string overflowed dest. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBXLATE_XOKCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The translation succeeded. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBXLATE_XPATCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The last bytes of src are the beginning of a pattern for 
which there is a translation. These bytes were not  
translated. ReturnsREMAP="BO--Body"The number of bytes actually placed in dest on success; a negative integer on error. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbxlate translates a character string from one character set to another. It is useful when the server character set differs from the display device's character set. The following code fragment illustrates the use of MOREINFO="NONE"dbxlate: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"char        destbuf[128]; int         srcbytes_used; DBXLATE     *xlt_todisp; DBXLATE     *xlt_tosrv; REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"dbload_xlate((DBPROCESS *)NULL, "iso_1",    "trans.xlt", &xlt_tosrv, &xlt_todisp); printf("Original string: \n\ %s\n\n",    TEST_STRING); dbxlate((DBPROCESS *)NULL, TEST_STRING,    strlen(TEST_STRING), destbuf, -1, xlt_todisp,     &srcbytes_used); printf("Translated to display character set: \     \n\t%s\n\n", destbuf); dbfree_xlate((DBPROCESS *)NULL, xlt_tosrv,    xlt_todisp); See AlsoREMAP="BO--Body"LINKEND="X57212"dbload_xlate
, LINKEND="X43669"dbfree_xlate
ID="IN627-31152199"dbxlate
 REMAP="BO--Body"ID="X47604"errorsID="IN4369933"ErrorsDB-Library
ID="IN43149934"Error handlinglist of errors
The complete collection of DB-Library errors and error severities. FORMAT="LINESPECIFIC"#include <sybfront.h> FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"#include <sybdb.h> FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"#include <syberror.h> CommentsMARK="BULL" REMAP="BU--Bullet"This is the complete range of possible DB-Library errors and error severities. The error values are listed alphabetically in LINKEND="X49063"Table 2-42: Errors
 below. The second column of this table gives the error severity for each error as a symbolic value. The third column contains the text associated with the error.LINKEND="X89012"Table 2-43: Error severities
 provides a list of all possible error severities, with their numerical equivalents and an explanation of the type of error. When an error or informational event occurs, these numbers are passed to the currently-installed user-supplied error handler. ID="IN43199577"sybdb.h header filesybdb.h header fileand error handlingerror handling
ID="IN432291118"syberror.h header filesyberror.h header fileand error severitieserror severitiesError values are defined in the header file sybdb.h. Error severity values are defined in the header file syberror.h. Your program need include syberror.h only if it refers to the symbolic error severities. ErrorsTOCENTRY="1"ID="X49063" LBL="Table 2-42: "ErrorsCOLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="108*"COLNAME="C2" COLWIDTH="113*"COLNAME="C3" COLWIDTH="243*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Error Name COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Error SeverityCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Error TextVALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEAAMTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0" EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"User attempted a MOREINFO="NONE"dbaltbind with mismatched column 
and variable types.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEABMTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0" EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"User attempted a MOREINFO="NONE"dbbind with mismatched column 
and variable types.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEABNCCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Attempt to bind to a non-existent column.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEABNPCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Attempt to bind using NULL pointers.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEABNVCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Attempt to bind to a NULL program variable.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEACNVCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCONVERSIONCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Attempt to do data-conversion with NULL 
destination variable.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEADSTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCONSISTENCYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"International Release: Error in attempting to 
determine the size of a pair of translation tables.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEAICFCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCONSISTENCYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"International Release: Error in attempting to install 
custom format.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEALTTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCONSISTENCYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"International Release: Error in attempting to load a 
pair of translation tables.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEAOLFCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXRESOURCECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"International Release: Error in attempting to open a 
localization file.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEAPCTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCONSISTENCYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"International Release: Error in attempting to 
perform a character set translation.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEAPUTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Attempt to print unknown token.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEARDICOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXRESOURCECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"International Release: Error in attempting to read 
datetime information from a localization file. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEARDLCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXRESOURCECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"International Release: Error in attempting to read 
the dblib.loc localization file.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEASECCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Attempt to send an empty command buffer to the 
server.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEASNLCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Attempt to set fields in a null LOGINREC.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEASTFCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCOMMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"VMS: Unable to setmode for control_cast.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEASTLCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Synchronous I/O attempted at AST level. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEASULCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Attempt to set unknown LOGINREC field.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEAUTNCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Attempt to update the timestamp of a table which 
has no timestamp column.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBADPKCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXINFOCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Packet size of %1 not supported-size of %2 used 
instead!COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBBCICOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXINFOCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Batch successfully bulk copied to the server.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBBLCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Bad bindlen parameter passed to MOREINFO="NONE"dbsetnull.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBCBCCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"bcp_columns must be called before MOREINFO="NONE"bcp_colfmt and 
MOREINFO="NONE"bcp_colfmt_ps.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBCBNPRCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"bcp_bind: if varaddr is NULL, prefixlen must be 0 
and no terminator should be specified.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBCBNTYPCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"bcp_bind: if varaddr is NULL and varlen greater than 
0, the table column type must be SYBTEXT or 
SYBIMAGE and the program variable type must be 
SYBTEXT, SYBCHAR, SYBIMAGE or SYBBINARY.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBCBPREFCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Illegal prefix length. Legal values are 0, 1, 2 or 4.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBCFOCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXUSERCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"bcp host files must contain at least one column.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBCHLENCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"host_collen should be greater than or equal to -1.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBCISCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCONSISTENCYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Attempt to bulk copy an illegally-sized column 
value to the server.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBCITCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"It's illegal to use BCP terminators with program 
variables other than SYBCHAR, SYBBINARY, 
SYBTEXT, or SYBIMAGE.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBCITBLENCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"bcp_init: tblname parameter is too long.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBCITBNMCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"bcp_init: tblname parameter cannot be NULL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBCMTXTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"bcp_moretext may be used only when there is at least 
one text or image column in the server table.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBCNLCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXNONFATALCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Negative length-prefix found in BCP data-file.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBCNNCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXUSERCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Attempt to bulk copy a NULL value into a Server 
column which does not accept null values.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBCNTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXUSERCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Attempt to use Bulk Copy with a non-existent 
Server table. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBCORCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCONSISTENCYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Attempt to bulk copy an oversized row to the server.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBCPBCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"bcp_bind, bcp_moretext and MOREINFO="NONE"bcp_sendrow may not be 
used afterMOREINFO="NONE" bcp_init has been passed a non-NULL 
input file name.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBCPCTYPCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"bcp_colfmt: If table_colnum is 0, host_type cannot be 
0.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBCPICOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"bcp_init must be called before any other MOREINFO="NONE"bcp routines.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBCPNCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"bcp_bind, bcp_collen, bcp_colptr, bcp_moretext and 
bcp_sendrow may be used only after bcp_init has 
been called with the copy direction set to DB_IN.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBCPRECCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXNONFATALCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Column %1!: Illegal precision value encountered.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBCPREFCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Illegal prefix length. Legal values are -1, 0, 1, 2 or 4.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBCRECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXNONFATALCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"I/O error while reading MOREINFO="NONE"bcp datafile.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBCROCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXINFOCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The BCP hostfile `%1!' contains only %2! rows. It 
was impossible to read the requested %3! rows.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBCSACOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXUSERCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The BCP hostfile `%1!' contains only %2! rows. 
Skipping all of these rows is not allowed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBCSETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCONSISTENCYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Unknown character-set encountered.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBCSICOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Host-file columns may be skipped only when 
copying into the Server.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBCSNDROWCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"bcp_sendrow may NOT be called unless all text data 
for the previous row has been sent using 
bcp_moretext.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBCSNTYPCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"column number %1!: if varaddr is NULL and varlen 
greater than 0, the table column type must be 
SYBTEXT or SYBIMAGE and the program variable 
type must be SYBTEXT, SYBCHAR, SYBIMAGE or 
SYBBINARY.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBCUCCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXRESOURCECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"bcp: Unable to close host datafile.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBCUOCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXRESOURCECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"bcp: Unable to open host datafile.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBCVHCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"bcp_exec may be called only after MOREINFO="NONE"bcp_init has been 
passed a valid host file.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBCVLENCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"varlen should be greater than or equal to -1.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBCWECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXNONFATALCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"I/O error while writing bcp datafile.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBDIOCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Bad bulk copy direction. Must be either IN or OUT.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBEOFCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXNONFATALCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Unexpected EOF encountered in bcp datafile. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBIHCCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Incorrect host-column number found in bcp format 
file.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBIVICOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"bcp_columns, bcp_colfmt and MOREINFO="NONE"bcp_colfmt_ps may be 
used only after MOREINFO="NONE"bcp_init has been passed a valid input 
file.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBNCRCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Attempt to bind user variable to a non-existent 
compute row.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBNUMCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Bad numbytes parameter passed to MOREINFO="NONE"dbstrcpy.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBPKSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"In MOREINFO="NONE"DBSETLPACKET, the packet size parameter must be 
between 0 and 999999.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBPRECCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Illegal precision specified.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBPROBADDEFCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCONSISTENCYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"bcp protocol error: illegal default column id 
received.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBPROCOLCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCONSISTENCYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"bcp protocol error: returned column count differs 
from the actual number of columns received.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBPRODEFCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCONSISTENCYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"bcp protocol error: expected default information and 
got none.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBPRODEFIDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCONSISTENCYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"bcp protocol error: default column id and actual 
column id are not sameCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBPRODEFTYPCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCONSISTENCYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"bcp protocol error: default value datatype differs 
from column datatype.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBPROEXTDEFCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCONSISTENCYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"bcp protocol error: more than one row of default 
information received.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBPROEXTRESCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCONSISTENCYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"bcp protocol error: unexpected set of results 
received.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBPRONODEFCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCONSISTENCYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"bcp protocol error: default value received for column 
that does not have default.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBPRONUMDEFCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCONSISTENCYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"bcp protocol error: expected number of defaults 
differs from the actual number of defaults received.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBRFFCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXRESOURCECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"I/O error while reading MOREINFO="NONE"bcp format file.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBSCALECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Illegal scale specified.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBTMTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Attempt to send too much text data via the 
MOREINFO="NONE"bcp_moretext call.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBTOKCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCOMMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Bad token from the server: Datastream processing 
out of sync.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBTYPCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Unknown bind type passed to DB-Library function.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBTYPSRVCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Datatype is not supported by the server.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBUCECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXRESOURCECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"bcp: Unable to close error file.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBUCFCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"bcp: Unable to close format file.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBUDFCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"bcp: Unrecognized datatype found in format file.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBUFFCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"bcp: Unable to create format file.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBUFLCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCONSISTENCYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DB-Library internal error-send buffer length 
corrupted. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBUOECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXRESOURCECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"bcp: Unable to open error file.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBUOFCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"bcp: Unable to open format file.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBWEFCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXNONFATALCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"I/O error while writing bcp error file.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEBWFFCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXRESOURCECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"I/O error while writing bcp format file.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBECAPCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCOMMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DB-Library capabilities not accepted by the Server.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBECAPTYPCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCOMMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Unexpected capability type in CAPABILITY 
datastream.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBECDNSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCONSISTENCYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Datastream indicates that a compute column is 
derived from a non-existent select-list member.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBECDOMAINCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCONVERSIONCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Source field value is not within the domain of legal 
values.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBECINTERNALCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCONVERSIONCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Internal Conversion error.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBECLOSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCOMMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Error in closing network connection.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBECLPRCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCONVERSIONCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Data conversion resulted in loss of precision.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBECNORCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Column number out of range.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBECNOVCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCONVERSIONCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Attempt to set variable to NULL resulted in 
overflow.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBECOFLCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCONVERSIONCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Data conversion resulted in overflow.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBECONNCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCOMMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Unable to connect: SQL Server is unavailable or 
does not exist. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBECRNCCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The current row is not a result of compute clause 
%1!, so it is illegal to attempt to extract that data 
from this row.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBECSYNCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCONVERSIONCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Attempt to convert data stopped by syntax error in 
source field.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBECUFLCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCONVERSIONCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Data conversion resulted in underflow.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEDBPSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXRESOURCECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Maximum number of DBPROCESSes already 
allocated.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEDDNECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXINFOCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBPROCESS is dead or not enabled.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEDIVZCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXUSERCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Attempt to divide by $0.00 in function %1!.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEDNTICOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Attempt to use dbtxtsput to put a new text 
timestamp into a column whose datatype is neither 
SYBTEXT nor SYBIMAGE.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEDPORCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Out-of-range datepart constant.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEDVORCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Day values must be between 1 and 7.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEECANCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXINFOCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Attempted to cancel unrequested event notification.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEEINICOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXINFOCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Must call MOREINFO="NONE"dbreginit before MOREINFO="NONE"dbregexec.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEEQVACOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCOMMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Error in queuing VMS AST routine.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEETDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Failure to send the expected amount of TEXT or 
IMAGE data via MOREINFO="NONE"dbmoretext.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEEUNRCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCOMMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Unsolicited event notification received.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEEVOPCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXINFOCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Called MOREINFO="NONE"dbregwatch with a bad options parameter.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEEVSTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXINFOCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Must initiate a transaction before calling MOREINFO="NONE"dbregparam.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEFCONCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCOMMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SQL Server connection failed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEFRESCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXFATALCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Challenge-Response function failed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEFSHDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXRESOURCECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Error in attempting to find the SYBASE home 
directory.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEFUNCCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Functionality not supported at the specified version 
level.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEICNCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Invalid computeid or compute column number.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEIDCLCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCONSISTENCYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Illegal datetime column length returned by SQL 
Server. Legal datetime lengths are 4 and 8 bytes. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEIDECCLCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCONSISTENCYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Invalid decimal column length returned by the 
server.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEIFCLCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCONSISTENCYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Illegal floating-point column length returned by 
SQL Server. Legal floating-point lengths are 4 and 8 
bytes.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEIFNBCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Illegal field number passed to MOREINFO="NONE"bcp_control.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEIICLCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCONSISTENCYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Illegal integer column length returned by SQL 
Server. Legal integer lengths are 1, 2, and 4 bytes.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEIMCLCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCONSISTENCYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Illegal money column length returned by SQL 
Server. Legal money lengths are 4 and bytes.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEINLNCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXUSERCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Interface file: unexpected end-of-line.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEINTFCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXUSERCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Server name not found in interface file.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEINUMCLCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCONSISTENCYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Invalid numeric column length returned by the 
server.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEIPVCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXINFOCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"%1! is an illegal value for the %2! parameter of %3!.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEISOICOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCONSISTENCYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"International Release: Invalid sort-order information 
found.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEISRVPRECCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCONSISTENCYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Illegal precision value returned by the server.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEISRVSCLCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCONSISTENCYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Illegal scale value returned by the server.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEITIMCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Illegal timeout value specified.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEIVERSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Illegal version level specified.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEKBCICOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXINFOCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"1000 rows sent to the server.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEKBCOCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXINFOCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"1000 rows successfully bulk copied to host file.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEMEMCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXRESOURCECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Unable to allocate sufficient memory. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEMOVCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXUSERCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Money arithmetic resulted in overflow in function 
%1!.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEMPLLCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXUSERCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Attempt to set maximum number of DBPROCESSes 
lower than 1.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEMVORCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Month values must be between 1 and 12.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBENBUFCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXINFOCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Called MOREINFO="NONE"dbsendpassthru with a NULL buf parameter.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBENBVPCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Cannot pass MOREINFO="NONE"dbsetnull a NULL bindval pointer.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBENDCCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Cannot have negative component in date in numeric 
form.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBENDTPCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Called MOREINFO="NONE"dbdatecrack with NULL datetime parameter.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBENEGCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCOMMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Negotiated login attempt failed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBENHANCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXINFOCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Called MOREINFO="NONE"dbrecvpassthru with a NULL handle 
parameter.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBENMOBCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No such member of order by clause.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBENOEVCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXINFOCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBPOLL can not be called when registered 
procedure notifications have been disabled.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBENPRMCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULL parameter not allowed for this MOREINFO="NONE"dboption.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBENSIPCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Negative starting index passed to MOREINFO="NONE"dbstrcpy.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBENTLLCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXUSERCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Name too long for LOGINREC field.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBENTSTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXUSERCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"VMS: The file being opened must be a stream_lf.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBENTTNCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Attempt to use dbtxtsput to put a new text 
timestamp into a non-existent data row.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBENULLCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXINFOCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULL DBPROCESS pointer passed to DB-Library.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBENULPCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Called %s with a NULL %s parameter.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBENXIDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXNONFATALCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The Server did not grant us a distributed-transaction 
ID.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEONCECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Function can be called only once.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEOOBCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCOMMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Error in sending out-of-band data to the server.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEOPINCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXNONFATALCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Could not open interface file. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEOPNACOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXNONFATALCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Option is not available with current server.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEORENCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXINFOCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"International Release: Warning: an out-of-range 
error-number was encountered in dblib.loc. The 
maximum permissible error-number is defined as 
DBERRCOUNT in sybdb.h.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEORPFCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXUSERCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Attempt to set remote password would overflow the 
login record's remote password field.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEPOLLCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXINFOCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"There is already an active MOREINFO="NONE"dbpoll.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEPRTFCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXINFOCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"dbtracestring may only be called from a printfunc.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEPWDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXUSERCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Login incorrect.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBERDCNCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCONVERSIONCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Requested data conversion does not exist.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBERDNRCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Attempt to retrieve data from a non-existent row.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEREADCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCOMMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Read from the server failed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBERESPCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Response function address passed to MOREINFO="NONE"dbresponse 
must be non-NULL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBERPCSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXINFOCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Must call MOREINFO="NONE"dbrpcinit before MOREINFO="NONE"dbrpcparam or MOREINFO="NONE"dbrpcsend.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBERPILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"It is illegal to pass -1 to MOREINFO="NONE"dbrpcparam for the datalen of 
parameters which are of type SYBCHAR, 
SYBVARCHAR, SYBBINARY, or SYBVARBINARY.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBERPNACOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXNONFATALCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The RPC facility is available only when using a 
server whose version number is 4.0 or greater.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBERPNDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Attempt to initiate a new SQL Server operation with 
results pending.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBERPNULLCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"value parameter for MOREINFO="NONE"dbprcparam can be NULL, only if 
the datalen parameter is 0.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBERPTXTIMCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"RPC parameters cannot be of type Text/Image.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBERPULCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"When passing a SYBINTN, SYBDATETIMN, 
SYBMONEYN, or SYBFLTN parameter via 
MOREINFO="NONE"dbrpcparam, it's necessary to specify the parameter's 
maximum or actual length, so that DB-Library can 
recognize it as a SYINT1, SYBINT2, SYBINT4, 
SYBMONEY, SYBMONEY4, etc.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBERTCCCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"dbreadtext may not be used to receive the results of a 
query which contains a COMPUTE clause.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBERTSCCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"dbreadtext may only be used to receive the results of 
a query which contains a single result column.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBERXIDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXNONFATALCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The Server did not recognize our distributed-
transaction ID.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBESECURECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Secure Server function not supported in this version.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBESEFACOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBSETNOTIFS cannot be called if connections are 
present.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBESEOFCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCOMMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Unexpected EOF from the server. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBESFOVCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"International Release: dbsafestr overflowed its 
destination buffer.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBESMSGCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXSERVERCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"General SQL Server error: Check messages from the 
server.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBESOCKCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCOMMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Unable to open socket.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBESPIDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Called MOREINFO="NONE"dbspid with a NULL dbproc.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBESYNCCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCOMMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Read attempted while out of synchronization with 
SQL Server.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBETEXSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXINFOCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Called MOREINFO="NONE"dbmoretext with a bad size parameter.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBETIMECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXTIMECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SQL Server connection timed out.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBETMCFCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Attempt to install too many custom formats via 
MOREINFO="NONE"dbfmtinstall.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBETMTDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Attempt to send too much TEXT data via the 
MOREINFO="NONE"dbmoretext call.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBETPARCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No SYBTEXT or SYBIMAGE parameters were 
defined.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBETPTNCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXUSERCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Syntax error: only two periods are permitted in table 
names.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBETRACCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXINFOCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Attempted to turn off a trace flag that was not on.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBETRANCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXINFOCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBPROCESS is being used for another transaction.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBETRASCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXINFOCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DB-Library internal error - trace structure not found.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBETRSNCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXINFOCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Bad numbytes parameter passed to MOREINFO="NONE"dbtracestring.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBETSITCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXINFOCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Attempt to call MOREINFO="NONE"dbtsput with an invalid timestamp.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBETTSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXUSERCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The table which bulk copy is attempting to copy to a 
host file is shorter than the number of rows which 
bulk copy was instructed to skip.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBETYPECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXINFOCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Invalid argument type given to Hyper/DB-Library.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEUACSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXRESOURCECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"VMS: Unable to assign channel to sys$command.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEUAVECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXRESOURCECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Unable to allocate VMS event flag. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEUCPTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXUSERCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Unrecognized custom-format parameter-type 
encountered in MOREINFO="NONE"dbstrbuild.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEUCRRCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCONSISTENCYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Internal software error: Unknown connection result 
reported by dbpasswd.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEUDTYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCONSISTENCYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Unknown datatype encountered.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEUFDSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXUSERCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Unrecognized format encountered in MOREINFO="NONE"dbstrbuild.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEUFDTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCONSISTENCYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Unknown fixed-length datatype encountered.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEUHSTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXUSERCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Unknown host machine name.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEUMSGCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCOMMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Unknown message-id in MSG datastream.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEUNAMCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXFATALCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Unable to get current username from operating 
system.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEUNOPCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXNONFATALCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Unknown option passed to MOREINFO="NONE"dbsetopt.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEUNTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXUSERCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Unknown network type found in interface file.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEURCICOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXRESOURCECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"International Release: Unable to read copyright 
information from the DB-Library localization file.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEUREICOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXRESOURCECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"International Release: Unable to read error 
information from the DB-Library localization file.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEUREMCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXRESOURCECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"International Release: Unable to read error 
mnemonic from the DB-Library localization file.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEURESCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXRESOURCECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"International Release: Unable to read error string 
from the DB-Library localization file.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEURMICOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXRESOURCECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"International Release: Unable to read money-format 
information from the DB-Library localization file. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEUSCTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCOMMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Unable to set communications timer.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEUTDSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCOMMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Unrecognized TDS version received from the server.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEUVBFCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Attempt to read an unknown version of MOREINFO="NONE"bcp format 
file.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEUVDTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCONSISTENCYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Unknown variable-length datatype encountered.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEVDPTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXUSERCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"For bulk copy, all variable-length data must have 
either a length-prefix or a terminator specified.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEVMSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXRESOURCECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Sendflush: VMS I/O error.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEWAIDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCONSISTENCYCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DB-Library internal error: ALTFMT following 
ALTNAME has wrong id.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEWRITCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCOMMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Write to the server failed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEXOCICOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXNONFATALCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"International Release: A character-set translation 
overflowed its destination buffer while using bcp to 
copy data from a host-file to the server.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEXTDNCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Warning: the MOREINFO="NONE"xlt_todisp parameter to MOREINFO="NONE"dbfree_xlate was 
NULL. The space associated with the MOREINFO="NONE"xlt_tosrv 
parameter has been freed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEXTNCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The MOREINFO="NONE"xlt_tosrv and MOREINFO="NONE"xlt_todisp parameters to MOREINFO="NONE"dbfree_xlate 
were NULL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEXTSNCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Warning: the MOREINFO="NONE"xlt_tosrv parameter to MOREINFO="NONE"dbfree_xlate was 
NULL. The space associated with the MOREINFO="NONE"xlt_todisp 
parameter has been freed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SYBEZTXTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXINFOCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Attempt to send zero length TEXT or IMAGE to 
dataserver via MOREINFO="NONE"dbwritetext.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"UNUSEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXINFOCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"This error number is unused. Error Severities       TOCENTRY="1"LBL="Table 2-43: " ID="X89012"Error severitiesCOLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="97*"COLNAME="C2" COLWIDTH="63*"COLNAME="C3" COLWIDTH="297*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Error SeverityCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Numerical 
EquivalentCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ExplanationVALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXINFOCOLNAME="C2" ALIGN="CENTER" ROTATE="0" MOREROWS="0"1COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Informational, non-error. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXUSERCOLNAME="C2" ALIGN="CENTER" ROTATE="0" MOREROWS="0"2COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"User error. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXNONFATALCOLNAME="C2" ALIGN="CENTER" ROTATE="0" MOREROWS="0"3COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Non-fatal error. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCONVERSIONCOLNAME="C2" ALIGN="CENTER" ROTATE="0" MOREROWS="0"4COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Error in DB-Library data conversion. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXSERVERCOLNAME="C2" ALIGN="CENTER" ROTATE="0" MOREROWS="0"5COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The Server has returned an error flag. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXTIMECOLNAME="C2" ALIGN="CENTER" ROTATE="0" MOREROWS="0"6COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"We have exceeded our timeout period while waiting for a 
response from the Server-the DBPROCESS is still alive. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXPROGRAMCOLNAME="C2" ALIGN="CENTER" ROTATE="0" MOREROWS="0"7COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Coding error in user program. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXRESOURCECOLNAME="C2" ALIGN="CENTER" ROTATE="0" MOREROWS="0"8COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Running out of resources-the DBPROCESS may be dead. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCOMMCOLNAME="C2" ALIGN="CENTER" ROTATE="0" MOREROWS="0"9COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Failure in communication with Server-the DBPROCESS is dead.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXFATALCOLNAME="C2" ALIGN="CENTER" ROTATE="0" MOREROWS="0"10COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fatal error-the DBPROCESS is dead. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EXCONSISTENCYCOLNAME="C2" ALIGN="CENTER" ROTATE="0" MOREROWS="0"11COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Internal software error-notify Sybase Technical Support. See AlsoREMAP="BO--Body"LINKEND="X39971"DBDEAD
, LINKEND="X12458"dberrhandle
ID="IN436901212"Errors
 ID="IN437891313"OptionsID="X60647"optionsID="IN447891415"OptionsDB-Library
The complete list of DB-Library options. FORMAT="LINESPECIFIC"#include <sybfront.h> FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"#include <sybdb.h> CommentsID="IN4419851818"sybdb.h header filesybdb.h header fileand DB-Library optionsDB-Library optionsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbsetopt and MOREINFO="NONE"dbclropt use the following constants, defined in sybdb.hID="IN4416832019"DATEFIRST option
, for setting and clearing options. All options are off by default. These options are available: REMAP="RI--RefIndent"DBARITHABORT ID="IN447832020"Queriesaborting during arithmetic exceptions
ID="IN4421832021"Arithmetic exceptions
ID="IN4419812222"DBARITHABORT option
- If this option is set, the server will abort a query when an arithmetic exception occurs during its execution. DBARITHIGNORE ID="IN447812223"Queriesignoring arithmetic exceptions
ID="IN4421812224"Arithmetic exceptions
ID="IN4420792425"DBARITHIGNORE option
- If this option is set, the server will substitute null values for selected or updated values when an arithmetic exception occurs during query execution. The SQL Server will not return a warning message. If neither DBARITHABORT nor DBARITHIGNORE is set, SQL Server will substitute null values and print a warning message after the query has been executed. DBAUTH ID="IN4413772626"DBAUTH option
- This option sets system administration authorization levels. Possible levels are: "sa", "sso", "oper", and "dbcc_edit". For information on these levels, see the SQL Server Reference Manual.DBBUFFER ID="IN4415752827"DBBUFFER option
ID="IN4411752828"Result rowsbuffering
ID="IN444752829"Rowsbuffering
ID="IN444723130"Rowsbuffering. See Row buffers.
- This option allows the application to buffer result rows, so that it can access them non-sequentially via the MOREINFO="NONE"dbgetrow function. This option is handled locally by DB-Library and is not a server option. When the option is set, you supply a parameter which is the number of rows you want buffered. If you use 0 as the number of rows to buffer, the buffer will be set to a default size (currently 1000 rows). REMAP="UN--Under"When an application calls MOREINFO="NONE"dbclropt to clear the DBBUFFER option, DB-Library frees the memory associated with the row buffer.DBCHAINXACTSID="IN4422723131"Unchained transactions
ID="IN4419703332"DBCHAINXACTS option
ID="IN4420703333"Chained transactions
 - This option is used to select chained or unchained transaction behavior. Chained behavior means that each server command is considered to be a distinct transaction. Unchained behavior requires an explicit commit transaction statement to define a transaction. This option is off (indicating unchained behavior) by default.DBDATEFIRST ID="IN4432663734"DATEFORMAT option of set command
ID="IN4412663735"Date formatsinput
- sets the first weekday to a number from one through seven. The us_english default is 1 (Sunday). DBDATEFORMAT - sets the order of the date parts month/day/year for entering datetime or smalldatetime data. Valid arguments are "mdy", "dmy", "ymd", "ydm", "myd", or "dym". The us_english default is "mdy". REMAP="UN--Under"Row buffering provides a way to keep a specified number of server result rows in program memory. Without row buffering, the result row generated by each new MOREINFO="NONE"dbnextrow call overwrites the contents of the previous result row. Row buffering is therefore useful for programs that need to look at result rows in a non-sequential manner. It does, however, carry a memory and performance penalty because each row in the buffer must be allocated and freed individually. Therefore, use it only if you need to. Specifically, the application should only turn the DBBUFFER option on if it calls MOREINFO="NONE"dbgetrow or MOREINFO="NONE"dbsetrow. Note that row buffering has nothing to do with network buffering and is a completely independent issue. (See MOREINFO="NONE"dbgetrow, dbnextrow, and MOREINFO="NONE"dbclrbuf for more information about row buffering.) DBFIPSFLAG ID="IN4417643936"DBFIPSFLAG option
- Setting this option causes the server to flag non-standard SQL commands. This option is off by default.DBISOLATION ID="IN4418624137"DBISOLATION option
- This option is used to specify the transaction isolation level. Possible levels are "1" and "3". The default level is "1". Setting the level to "3" causes all pages of tables specified in a MOREINFO="NONE"select query inside a transaction to be locked for the duration of the transaction.DBNATLANG ID="IN4416604338"DBNATLANG option
ID="IN449604339"Languagessetting national
- This is a DB-Library Internationalization option. Associate the specified DBPROCESS (or all open DBPROCESSes, if a DBPROCESS is not specified) with a national language. If the national language is not set for a particular DBPROCESS, U.S. English is used by default. REMAP="UN--Under"In programs that allow application users to make ad hoc queries, the user may override DBNATLANG with the Transact-SQL MOREINFO="NONE"set MOREINFO="NONE"language command. All DBPROCESSes opened using a particular LOGINREC will also use that LOGINREC's associated national language. Use the DBSETLNATLANG macro to associate a national language with a LOGINREC. DBNOAUTOFREE ID="IN4419584540"DBNOAUTOFREE option
ID="IN4415584541"Command bufferslimiting clearing
- This option causes the command buffer to be cleared only by an explicit call to MOREINFO="NONE"dbfreebuf. When DBNOAUTOFREE is not set, after a call to MOREINFO="NONE"dbsqlexec or MOREINFO="NONE"dbsqlsend the first call to either MOREINFO="NONE"dbcmd or MOREINFO="NONE"dbfcmd automatically clears the command buffer before the new text is entered. DBNOCOUNT ID="IN4416564742"DBNOCOUNT option
ID="IN444564743"Rowsturning counting off
- This option causes the server to stop sending back information about the number of rows affected by each SQL statement. The application can otherwise obtain this information by calling DBCOUNTMOREINFO="NONE". DBNOEXEC ID="IN447564744"Queriesnot executing
ID="IN4415544945"DBNOEXEC option
- If this option is set, the server will process the query through the compile step but the query will not be executed. This can be used in conjunction with DBSHOWPLAN. DBOFFSET ID="IN4415525146"DBOFFSET option
ID="IN447525147"Offsetssetting where to return
- This option indicates that the server should return offsets for certain constructs in the query. DBOFFSET takes a parameter that specifies the particular construct. The valid parameters for this option are "select", "from", "table", "order", "compute", "statement", "procedure", "execute", or "param". (Note that "param" refers to parameters of stored procedures.) Calls to routines such as MOREINFO="NONE"dbsetopt can specify these option parameters in either lower or upper case. Offsets are returned only if the batch contains no syntax errors. DBPARSEONLY ID="IN4418505348"DBPARSEONLY option
ID="IN446505349"Syntaxchecking
- If this option is set, the server only checks the syntax of the query and returns error messages to the host. Offsets are returned if the DBOFFSET option is set and there are no errors. DBPRCOLSEP ID="IN4417485550"DBPRCOLSEP option
ID="IN447485551"Columnsspecifying separator characters
ID="IN4420485552"Separator charactersspecifying for columns
- Specify the column separator character(s). Query results rows formatted via MOREINFO="NONE"dbprhead, dbprrow, dbsprhead, dbsprline, and MOREINFO="NONE"dbspr1row will have columns separated by the specified string. The default separator is an ASCII 0x20 (space). The third parameter, a string, is not necessarily NULL-terminated. The length of the string used is given as the fourth parameter in the call to MOREINFO="NONE"dbsetopt. To revert to using the default separator, specify a length of -1. In this case, the third parameter is ignored. DBPRLINELEN ID="IN4418465753"DBPRLINELEN option
ID="IN4411465754"Line lengthspecifying for rows
ID="IN444465755"Rowsspecifying line length
- Specify the maximum number of characters to be placed on one line. This value is used by MOREINFO="NONE"dbprhead, dbprrow, dbsprhead, dbsprline, and MOREINFO="NONE"dbspr1row. The default line length is 80 characters. DBPRLINESEP ID="IN4418445956"DBPRLINESEP option
ID="IN4420445957"Separator charactersspecifying for rows
ID="IN444445958"Rowsspecifying separator characters
- Specify the row separator character to be used by MOREINFO="NONE"dbprhead, dbprrow, dbsprhead, dbsprline, and MOREINFO="NONE"dbspr1row. The default separator is a newline (0x0D or 0x0A, depending on the host system). The third parameter, a string, is not necessarily null-terminated. The length of the string is given as the fourth parameter in the call to MOREINFO="NONE"dbsetopt. To revert to the default terminator, specify a length of -1; in this case, the third parameter is ignored. DBPRPAD ID="IN4414426159"DBPRPAD option
ID="IN447426160"Paddingspecifying characters to use
- Specify the pad character used when printing results via MOREINFO="NONE"dbprhead, dbprrow, dbsprhead, dbsprline, and MOREINFO="NONE"dbspr1row. To activate padding, specify DBPADON as the fourth parameter in the MOREINFO="NONE"dbsetopt call. The pad character may be specified as the third parameter in the MOREINFO="NONE"dbsetopt call. If the character is not specified, the ASCII character 0x20 (SPACE) is used. To turn off padding, call MOREINFO="NONE"dbsetopt with DBPADOFF as the fourth parameter; the third parameter is ignored when turning padding off. DBROWCOUNT ID="IN4417406361"DBROWCOUNT option
ID="IN4412406362"Regular rowslimiting number to return
ID="IN444406363"Rowslimiting number to return
- If this option is set, the server will return only a maximum specified number of regular rows for MOREINFO="NONE"select statements. This option does not limit the number of compute rows returned. REMAP="UN--Under"DBROWCOUNT works somewhat differently from most options. It is always set on, never off. Setting DBROWCOUNT to 0 sets it back to the default-that is, to return all the rows generated by a MOREINFO="NONE"select statement. Therefore, the way to turn DBROWCOUNT off is to set it on with a count of 0. DBSHOWPLAN ID="IN4417386564"DBSHOWPLAN option
ID="IN4415386565"Processing plangenerating description of
- If this option is set, the server will generate a description of the processing plan after compilation and continue executing the query. DBSTAT ID="IN4413366766"DBSTAT option
ID="IN4410366767"Statisticsperformance:determining when returned
ID="IN444366768"Timedetermining when to return status
- This option determines when performance statistics (CPU time, elapsed time, I/O, etc.) will be returned to the host after each query. DBSTAT takes one of two parameters: "io", for statistics about SQL Server internal I/O; and "time", for information about SQL Server's parsing, compilation, and execution times. These statistics are received by DB-Library in the form of informational messages, and application programs can access them through the user-supplied message handler. DBSTORPROCID ID="IN4419337069"DBSTORPROCID option
ID="IN4417337070"Stored proceduressending ids of
- If this option is set, the server will send the stored procedure id to the host before sending rows generated by the stored procedure. DBTEXTLIMIT ID="IN4418297471"DBTEXTLIMIT option
ID="IN4411297472"Text valueslimiting size of
ID="IN4412297473"Image valueslimiting size of
- This option causes DB-Library to limit the size of returned text or image values. When setting this option, you supply a parameter which is the length, in bytes, of the longest text or image value that your program can handle. DB-Library will read but ignore any part of a text or image value that goes over this limit. DB-Library's default behavior is to read and return all the data sent by the Server. To restore this default behavior, set DBTEXTLIMIT to a value less than 1. In the case of huge text values, it may take some time for the entire text value to be returned over the network. To keep the server from sending this extra text in the first place, use the DBTEXTSIZE option instead. DBTEXTSIZE ID="IN4417277674"DBTEXTSIZE option
ID="IN4411277675"Text valueslimiting size of
ID="IN4412277676"Image valueslimiting size of
- This option changes the value of the server global variable @@textsize, which limits the size of text or image values that the server returns. When setting this option, you supply a parameter which is the length, in bytes, of the longest text or image value that the server should return. @@textsize has a default value of 32,768 bytes. Note that, in programs that allow application users to make ad hoc queries, the user may override this option with the Transact-SQL MOREINFO="NONE"set MOREINFO="NONE"textsize command. To set a text limit that the user cannot override, use the DBTEXTLIMIT option instead. DBBUFFER, DBNOAUTOFREE, and DBTEXTLIMIT are DB-Library options. That is, they affect DB-Library but are not sent to the server. The other options are SQL Server options-they get sent to the server. SQL Server options are also settable through Transact-SQL. ID="IN447277677"Optionsparameter values ofAs mentioned in the preceding descriptions, certain options take parameters: TOCENTRY="1"LBL="Table 2-44: "Parameter values for optionsCOLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="93*"COLNAME="C2" COLWIDTH="239*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"OptionCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Possible parameter values VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBTEXTSIZECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0""0" to "2,147,483,647" COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBOFFSETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0""select", "from", "table", "order", "compute", 
"statement", "procedure", "execute", or "param" COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBSTATCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0""io" or "time" COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBROWCOUNTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0""0" to "2,147,483,647" COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBBUFFERCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0""0" to either "32,767" or "2,147,483,647", 
depending on whether your int datatype is 2 or 4 
bytes long COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DBTEXTLIMITCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0""0" to "2,147,483,647" REMAP="BO--Body"MOREINFO="NONE"dbsetopt requires that an option parameter be specified when setting any option on the preceding list. MOREINFO="NONE"dbclropt and MOREINFO="NONE"dbisopt require that the parameter be specified only for DBOFFSET and DBSTAT. This is because DBOFFSET and DBSTAT are the only options that can have multiple settings at a time, and thus they require further definition before being cleared or checked. REMAP="BO--Body"Note that parameters specified in calls to MOREINFO="NONE"dbsetopt, MOREINFO="NONE"dbclropt, and MOREINFO="NONE"dbisopt are always passed as character strings and must be quoted, even if they are numeric values. See the MOREINFO="NONE"dbsetopt manual page for more information. See AlsoREMAP="BO--Body"LINKEND="X69074"dbclropt
, LINKEND="X50317"dbisopt
, LINKEND="X97776"dbsetopt
ID="IN447267779"Options
 ID="IN449257880"DatatypesDB-LibraryID="X91146"typesID="IN459257982"DatatypesServer:list of
List of data typedefs and defines used by DB-Library. FORMAT="LINESPECIFIC"#include <sybfront.h> FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"#include <sybdb.h> CommentsMARK="BULL" REMAP="BU--Bullet"Here is a list of server datatypes. MOREINFO="NONE"dbconvert and MOREINFO="NONE"dbwillconvert use these types. In addition, the routines MOREINFO="NONE"dbcoltype, MOREINFO="NONE"dbalttype, and MOREINFO="NONE"dbrettype will return one of these types. REMAP="UN--Under"SYBBINARY                binary type SYBBIT                          bit type SYBCHAR                    char type SYBTEXT                      text type SYBIMAGE                   image type SYBINT1                       1-byte integer SYBINT2                       2-byte integer SYBINT4                       4-byte integer SYBREAL                      4-byte float type SYBNUMERIC             numeric typeSYBDECIMAL              decimal typeSYBFLT8                        8-byte float type SYBMONEY                  money type SYBMONEY4                4-byte money type SYBDATETIME            datetime type SYBDATETIME4          4-byte datetime typeSYBBOUNDARY         security sensitivity_boundary typeSYBSENSITIVITY       security sensitivity typeREMAP="UN--Under"For more information on server datatypes, see the Transact-SQL Reference Manual. ID="IN458257985"TypedefsDB-Library:list ofHere is a list of typedefs used by DB-Library functions. These typedefs are useful for defining program variables, particularly variables used with MOREINFO="NONE"dbbind, MOREINFO="NONE"dbaltbind, MOREINFO="NONE"dbconvert, and MOREINFO="NONE"dbdatecrack. REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* char, text, boundary, and sensitivity types */typedef char             DBCHAR;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* binary and image type */typedef unsigned char    DBBINARY;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* 1-byte integer */typedef unsigned char   DBTINYINT; /* 2-byte integer */typedef short           DBSMALLINT; / unsigned 2-byte integer */typedef unsigned short  DBUSMALLINT; /* 4-byte integer */typedef long            DBINT; /* 4-byte float type */typedef float           DBREAL; typedef struct          dbnumeric{    char               precision;    char               scale;    unsigned char      val[MAXNUMLEN];} DBNUMERIC; typedef DBNUMERIC       DBDECIMAL; /* 8-byte float type */typedef double          DBFLT8; /* bit type */typedef unsigned char   DBBIT; /* SUCCEED or FAIL */typedef int             RETCODE;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* datetime type */typedef struct          datetime{     /* number of days since 1/1/1900 */    long            dtdays;    /* 300ths of a second since midnight */    unsigned long   dttime;} DBDATETIME;  /* 4-byte datetime type */typedef struct            datetime4{     /* number of days since 1/1/1900 */    unsigned short      numdays;    /* number of minutes since midnight */    unsigned short  nummins;} DBDATETIME4;  typedef struct            dbdaterec {     /* 1900 to the future */    long    dateyear;    /* 0 - 11 */    long    datemonth;    /* 1 - 31 */    long    datedmonth;    /* 1 - 366 */    long    datedyear;    /* 0 - 6 (Mon. - Sun.) */    long    datedweek;    /* 0 - 23 */    long    datehour;    /* 0 - 59 */    long    dateminute;    /* 0 - 59 */    long    datesecond;    /* 0 - 997 */    long    datemsecond;    /* 0 - 127 */    long    datetzone;} DBDATEREC;  /* money type */typedef struct           money{     long            mnyhigh;     unsigned long   mnylow; } DBMONEY;  /* 4-byte money type */typedef signed long      DBMONEY4; /* Pascal-type string */typedef struct           dbvarychar{     /* character count */    DBSMALLINT       len;    /* non-terminated string */    DBCHAR           str[DBMAXCHAR];} DBVARYCHAR;  /* Pascal-type binary array */typedef struct           dbvarybin{     /* byte count */    DBSMALLINT        len;    /* non-terminated array */    BYTE              array[DBMAXCHAR];} DBVARYBIN;  /* Used by DB-Library for indicator variables */typedef      DBSMALLINT     DBINDICATOR;The SYBBOUNDARY and SYBSENSITIVITY types correspond to the program variable type DBCHAR.See AlsoREMAP="BO--Body"LINKEND="X21854"dbaltbind
, LINKEND="X53350"dbalttype
, LINKEND="X14206"dbbind
, LINKEND="X35574"dbcoltype
, LINKEND="X76814"dbconvert
, LINKEND="X77266"dbprtype
, LINKEND="X70606"dbrettype
, LINKEND="X17556"dbwillconvert
, LINKEND="X60647"options
ID="IN459248087"DatatypesDB-Library
 REMAP="BO--Body"NUMBER="3" ID="X40433"Bulk CopyRENDERAS="SECT1"Introduction to Bulk Copy   ID="IN399921"Bulk copyREMAP="BO--Body"Bulk copy is a tool for high-speed transfer of data between a database table and program variables or a host  file.  It provides an alternative to SQL MOREINFO="NONE"insert and MOREINFO="NONE"select commands.REMAP="BO--Body"The DB-Library/C bulk copy special library is a collection of routines that provide bulk copy functionality to a DB-Library/C application. A DB-Library/C application may find bulk copy useful if it needs to exchange data with a non-database application, load data into a new database, or move data from one database to another. RENDERAS="SECT2"Transferring Data Into the Database   REMAP="BO--Body"Data can be copied into a database from program variables or from a host file. REMAP="BO--Body"When copying data into a database table, the chief advantage of bulk copy over the alternative MOREINFO="NONE"insert is speed.  Also, SQL MOREINFO="NONE"insert requires that the data be in character string format, while bulk copy can transfer native datatypes. REMAP="BO--Body"When copying data into a non-indexed table, the "high speed" version of bulk copy is used. High-speed means that no data logging is  performed during the transfer.  If the system fails before the transfer is complete, no new data will remain in the database.  Because high-speed transfer affects the recoverability of the database, it is only enabled if the SQL Server option "select into/bulkcopy" has been turned on.  If the option is not set on, and a user tries to copy data into a table that has no  indexes, SQL Server generates an error message. REMAP="BO--Body"After the bulk copy is complete, the system  administrator should dump the database to ensure its future recoverability. REMAP="BO--Body"When you copy data into an indexed table, a slower version of MOREINFO="NONE"bcp is automatically used, and row inserts are logged. REMAP="BO--Body"In order to copy data into a database, a DB-Library/C application must perform the following introductory steps: MARK="BULL" REMAP="BU--Bullet"Call MOREINFO="NONE"dblogin to acquire a LOGINREC structure for later use with MOREINFO="NONE"dbopen. Call MOREINFO="NONE"bcp_setl to set up the LOGINREC for bulk copy operations into the database. Call MOREINFO="NONE"dbopen to  establish a connection with  SQL Server. Call MOREINFO="NONE"bcp_init to initialize the bulk copy operation and inform SQL Server whether the copy will be performed from  program variables or a host file. To copy data into the database, MOREINFO="NONE"bcp_init's parameter direction must be passed as DB_IN. REMAP="BO--Body"At this point,  an application copying data from program variables will need to perform different steps than an application copying data from a host file. REMAP="BO--Body"To copy data from program variables, a DB-Library/C application must perform the following steps in addition to the  introductory ones listed previously: MARK="BULL" REMAP="BU--Bullet"Call MOREINFO="NONE"bcp_bind once for each program variable that is to be bound to a database column. Transfer a batch of data in a loop: MARK="DASH" REMAP="BS--BulletSub"Assign program variables the data values to transfer. Call MOREINFO="NONE"bcp_sendrow to send the row of data. After a batch of rows has been sent, call MOREINFO="NONE"bcp_batch to save the rows in SQL Server. After all the data has been sent, call MOREINFO="NONE"bcp_done to end the bulk copy operation. REMAP="BO--Body"To copy data from a host file, a DB-Library/C application needs to perform the following steps in addition to the introductory ones listed previously: MARK="BULL" REMAP="BU--Bullet"Call MOREINFO="NONE"bcp_control to set the batch size and change control parameter default settings. Call MOREINFO="NONE"bcp_columns to set the total number of columns found in the host file. Call MOREINFO="NONE"bcp_colfmt once for each column in the host file. If the host file matches the database table exactly, an  application does not have to call MOREINFO="NONE"bcp_colfmt. Call MOREINFO="NONE"bcp_exec to start the copy in. RENDERAS="SECT2"Transferring Data Out From the Database   REMAP="BO--Body"Data can be copied out from a database only into an operating system file.  Bulk copy does not allow the transfer of data from a database into program variables. REMAP="BO--Body"When transferring data out to a host file from a database table, the chief advantage of bulk copy over SQL MOREINFO="NONE"select is that it allows very specific output  file formats to be specified.  Bulk copy is not significantly faster than SQL MOREINFO="NONE"select. REMAP="BO--Body"In order to copy data out from a database, a DB-Library/C application must perform the following steps: MARK="BULL" REMAP="BU--Bullet"Call MOREINFO="NONE"dblogin to acquire a LOGINREC structure for later use with MOREINFO="NONE"dbopen. Call MOREINFO="NONE"dbopen to  establish a connection with  SQL Server. Call MOREINFO="NONE"bcp_init to initialize the bulk copy operation. To copy data out from the database, direction  must be passed as DB_OUT. Call MOREINFO="NONE"bcp_control to set the batch size and change control parameter default settings. Call MOREINFO="NONE"bcp_columns to set the total number of columns found in the host file. Call MOREINFO="NONE"bcp_colfmt once for each column in the host file. If the host file matches the database table exactly, an  application does not have to call MOREINFO="NONE"bcp_colfmt. Call MOREINFO="NONE"bcp_execID="IN399832"Bulk copy
 to start the copy out. REMAP="BO--Body"ID="X40028"bcp_batchID="IN4339573"bcpsaving preceding rows in SQL Server
Save any preceding rows in SQL Server. FORMAT="LINESPECIFIC"DBINT bcp_batch(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS    *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/SQL Server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and SQL Server. CommentsMARK="BULL" REMAP="BU--Bullet"When an application uses MOREINFO="NONE"bcp_bind and MOREINFO="NONE"bcp_sendrow to bulk-copy rows from program variables to SQL Server tables, the rows are permanently saved in SQL Server only when the program calls MOREINFO="NONE"bcp_batch or MOREINFO="NONE"bcp_done. You may call MOREINFO="NONE"bcp_batch once every n rows or when there is a lull between periods of incoming data (as in a telemetry application). Of course, you may choose some other criteria, or may decide not to call MOREINFO="NONE"bcp_batch at all. If MOREINFO="NONE"bcp_batch is not called, the rows are permanently saved in SQL Server when MOREINFO="NONE"bcp_done is called. By default, SQL Server copies all the rows specified in one batch. SQL Server considers each batch to be a separate MOREINFO="NONE"bcp operation. Each batch is copied in a single MOREINFO="NONE"insert transaction, and if any row in the batch is rejected, the entire MOREINFO="NONE"insert is rolled back. MOREINFO="NONE"bcp then continues to the next batch. You can use MOREINFO="NONE"bcp_batch to break large input files into  smaller units of recoverability. For example, if 300,000 rows are bulk copied and MOREINFO="NONE"bcp_batch is called every 100,000 rows, if there is a fatal error after row 200,000, the first two batches-200,000 rows-will have been successfully copied into SQL Server.  MOREINFO="NONE"bcp_batch actually sends two commands to the server. The first command tells the server to permanently save the rows. The second tells the server to begin a new transaction.  It is possible that the command to save the rows completes  successfully but the command to start a new transaction does not.  In this case, MOREINFO="NONE"bcp_batch's error return of -1 does not indicate that the rows have not been successfully saved. To find out whether this has happened, an application can refer to the messages generated by SQL Server or DB-Library/C. For information on the MOREINFO="NONE"bcp utility program, see its manual page in the Open Client/Server Supplement. ReturnsREMAP="BO--Body"The number of rows saved since the last call to MOREINFO="NONE"bcp_batch, or -1 in case of error. See AlsoREMAP="BO--Body"LINKEND="X98985"bcp_bind
,  LINKEND="X90675"bcp_done
,  LINKEND="X88050"bcp_sendrow
ID="IN43992109"bcp_batch
 ID="IN438891310"bcp_bindID="X98985"bcp_bindID="IN443871612"bcpbinding data
Bind data from a program variable to a SQL Server table. FORMAT="LINESPECIFIC"RETCODE bcp_bind (dbproc, varaddr, prefixlen, varlen,              terminator, termlen, type, table_column)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"BYTE          *varaddr;FORMAT="LINESPECIFIC"int           prefixlen;FORMAT="LINESPECIFIC"DBINT         varlen;FORMAT="LINESPECIFIC"BYTE          *terminator;FORMAT="LINESPECIFIC"int           termlen;FORMAT="LINESPECIFIC"int           type;FORMAT="LINESPECIFIC"int           table_column;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/SQL Server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and SQL Server. varaddr - The address of the program variable from which the data will be copied. If type is SYBTEXT or SYBIMAGE, varaddr can be NULL. A NULL varaddr indicates  that text and image values will be sent to SQL Server in chunks by MOREINFO="NONE"bcp_moretext, rather than all at once by MOREINFO="NONE"bcp_sendrow. prefixlen - The length, in bytes, of any length prefix this column may have.  For example, strings in some non-C programming languages are made up of a one-byte length prefix, followed by the string data itself. If the data does not have a length prefix, set prefixlen to 0. varlen - The length of the data in the program variable, not including the length of any length prefix and/or terminator.  Setting varlen to 0 signifies that the data is null. Setting varlen to -1 indicates that the system should ignore this parameter. REMAP="UN--Under"For fixed-length datatypes, such as integers, the datatype itself indicates to the system the length of the data. Therefore, for fixed-length datatypes, varlen must always be -1, except when the data is null, in which case varlen must be 0. REMAP="UN--Under"For character, text, binary, and image data, varlen can be -1, 0, or some positive value. If varlen is -1, the system will use either a length prefix or a terminator sequence to determine the length. (If both are supplied, the system will use the one that results in  the shortest amount of data being copied.) If varlen is -1 and neither a prefix length nor a  terminator sequence is specified, the system will return an error message. If varlen is 0, the system assumes the data is null. If varlen is some positive value, the system uses varlen as the data length. However, if, in addition to a positive varlen, a prefix length and/or terminator sequence is provided, the system determines the data length by using the method  that results in the shortest amount of data being copied. terminator - A pointer to the byte pattern, if any, that marks the end of this program variable. For example, C strings usually have a one-byte terminator, whose value is 0. If there is no terminator for the variable, set terminator to NULL. REMAP="UN--Under"If you want to designate the C null terminator as the program variable terminator, the simplest way is to use an empty string ("") as terminator and set termlen to 1, since the null terminator constitutes a single byte. For instance, the second MOREINFO="NONE"bcp_bind call in the previous example uses two tabs as the program variable terminator. It could be rewritten to use a C null terminator instead, as follows: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"(bcp_bind (dbproc, co_name, 0, -1, "", 1, 0, 2) termlen - The length of this program variable's terminator, if any. If there is no terminator for the variable, set termlen to 0. type - The datatype of your program variable, expressed as a SQL Server datatype.  The data in the program variable will be automatically converted to the type of the database column.  If this parameter is 0, no conversion will be performed.  See the MOREINFO="NONE"dbconvert manual page for a list of supported conversions.  That manual page also contains a list of SQL Server datatypes. table_column - The column in the database table to which the data will be copied. Column numbers start at 1. CommentsMARK="BULL" REMAP="BU--Bullet"There may be times when you want to copy data directly from a program variable into a table in SQL Server, without having to first place the data in a host file or use the SQL MOREINFO="NONE"insert command. The MOREINFO="NONE"bcp_bind function is a fast and efficient way to do this. You must call MOREINFO="NONE"bcp_init before calling this or any other bulk copy functions. There must be a separate MOREINFO="NONE"bcp_bind call for every column in the SQL Server table into which you want to copy. After the necessary MOREINFO="NONE"bcp_bind calls have been made, you then call MOREINFO="NONE"bcp_sendrow to send a row of data from your program variables to SQL Server. The table to be copied into is set by calling MOREINFO="NONE"bcp_init. Whenever you want SQL Server to checkpoint the rows already received, call MOREINFO="NONE"bcp_batch. For example, you may want to call MOREINFO="NONE"bcp_batch once for every 1000 rows inserted, or at any other interval. ID="IN448792416"bcp_donebcp_doneand bcp_bindbcp_bindWhen there are no more rows to be inserted, call MOREINFO="NONE"bcp_done. Failure to do so will result in an error. When using MOREINFO="NONE"bcp_bind, the host filename parameter used in the call to MOREINFO="NONE"bcp_init, hfile, must be set to NULL, and  the direction parameter, direction, must be set to DB_IN.  Prefix lengths should not be used with fixed-length datatypes, such as integers or floats.  For fixed-length datatypes, since bulk copy can figure out the length of the data from the datatype, pass prefixlen as 0 and  varlen as -1, except when the data is null,  in which case varlen must be 0. Control parameter settings, specified with MOREINFO="NONE"bcp_control, have no effect on MOREINFO="NONE"bcp_bind row transfers. It is an error to call MOREINFO="NONE"bcp_columns when using MOREINFO="NONE"bcp_bind. ID="IN4411713217"bcp_columnsbcp_columnsand bcp_bindbcp_bindThe following program fragment illustrates MOREINFO="NONE"bcp_bind: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"LOGINREC           *login; DBPROCESS          *dbproc; char               co_name[MAXNAME]; DBINT              co_id; DBINT              rows_sent; DBBOOL             more_data; char               *terminator = "\ \ ";  /* Initialize DB-Library. */ if (dbinit() == FAIL)      exit(ERREXIT);  /* Install error-handler and message-handler. */ dberrhandle(err_handler); dbmsghandle(msg_handler);  /* Open a DBPROCESS. */ login = dblogin(); BCP_SETL(login, TRUE); dbproc = dbopen(login, NULL);  /* Initialize bcp. */ if (bcp_init(dbproc, "comdb..accounts_info",       NULL, NULL, DB_IN) == FAIL)      exit(ERREXIT);  /* Bind program variables to table columns. */ if (bcp_bind(dbproc, &co_id, 0, -1,       (BYTE *)NULL, 0, 0, 1) == FAIL) {      fprintf(stderr, "bcp_bind, column 1, failed.\n");      exit(ERREXIT); }  if (bcp_bind      (dbproc, co_name, 0, -1, (BYTE *)terminator,       strlen(terminator), 0, 2)           == FAIL) {      fprintf(stderr, "bcp_bind, column 2, failed.\n");      exit(ERREXIT); }  while (TRUE) {      /* Process/retrieve program data. */      more_data = getdata(&co_id, co_name);              if (more_data == FALSE)            break;        /* Send the data. */       if (bcp_sendrow(dbproc) == FAIL)          exit(ERREXIT); }  /* Terminate the bulk copy operation. */ if ((rows_sent = bcp_done(dbproc)) == -1)      printf("Bulk-copy unsuccessful.\n"); else      printf("%ld rows copied.\n", rows_sent); For information on the MOREINFO="NONE"bcp utility program, see its manual page in the Open Client/Server Supplement. ReturnsREMAP="BO--Body"SUCCEED or FAIL. See AlsoREMAP="BO--Body"LINKEND="X40028"bcp_batch
, LINKEND="X63011"bcp_colfmt
, LINKEND="X12457"bcp_collen
, LINKEND="X88930"bcp_colptr
, LINKEND="X96868"bcp_columns
, LINKEND="X46887"bcp_control
, LINKEND="X90675"bcp_done
, LINKEND="X97799"bcp_exec
, LINKEND="X40041"bcp_init
, LINKEND="X18177"bcp_moretext
, LINKEND="X88050"bcp_sendrow
ID="IN448683520"bcp_bind
 ID="IN4410653821"bcp_colfmtID="X63011"bcp_colfmtID="IN453634123"bcphost file format
ID="IN453614324"bcpspecifying host file format
ID="IN453594525"bcpoverriding default data formats
Specify the format of a host file for bulk copy purposes. FORMAT="LINESPECIFIC"RETCODE bcp_colfmt (dbproc, host_colnum, host_type,                host_prefixlen, host_collen, host_term,                host_termlen, table_colnum)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"int           host_colnum;FORMAT="LINESPECIFIC"int           host_type;FORMAT="LINESPECIFIC"int           host_prefixlen;FORMAT="LINESPECIFIC"DBINT         host_collen;FORMAT="LINESPECIFIC"BYTE          *host_term;FORMAT="LINESPECIFIC"int           host_termlen;FORMAT="LINESPECIFIC"int           table_colnum;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/SQL Server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and SQL Server. host_colnum - The column in the host file whose format is being specified. The first column is number 1. host_type - The datatype of this column in the host file, expressed as a SQL Server datatype.  If it is different from the datatype of the corresponding column in the database table (table_colnum), the conversion will be performed automatically.  See the MOREINFO="NONE"dbconvert manual page for a table of allowable data conversions. That manual page also contains a list of SQL Server datatypes. REMAP="UN--Under"If you want to specify the same datatype as in the corresponding column of the database table (table_colnum), this parameter should be set to 0. MOREINFO="NONE"bcp_colfmt does not offer precision and scale support for numeric and decimal types. When setting the format of a numeric or decimal host column, MOREINFO="NONE"bcp_colfmt uses a default precision and scale of 18 and 0, respectively. To specify a different precision and scale, an application can call MOREINFO="NONE"bcp_colfmt_ps.host_prefixlen - The length of the length prefix for this column in the host file.  Legal prefix lengths are 1, 2, and 4 bytes. To avoid using a length prefix, this parameter should be set to 0. To let MOREINFO="NONE"bcp decide whether  to use a length prefix, this parameter should be set to -1. In such a case, MOREINFO="NONE"bcp will use a length prefix (of whatever length is necessary) if the database column length is variable. REMAP="UN--Under"If more than one means of specifying a host file column length is used (such as a length prefix and a maximum column length, or a length prefix and a terminator sequence), MOREINFO="NONE"bcp will look at all of them and use the one that results in the shortest amount of data being copied. REMAP="UN--Under"One valuable use for length prefixes is to simplify the specifying of null data values in a host file.  For instance, assume you have a 1-byte length prefix for a 4-byte integer column. Ordinarily, the length prefix will contain a value of 4, to indicate that a 4-byte value follows. However, if the value of the column is null, the length prefix can be set to 0, to indicate that 0 bytes follow for the column. host_collen - The maximum length of this column's data in the host file, not including the length of any length prefix and/or terminator.  Setting host_collen to 0 signifies that the data is null. Setting host_collen to -1 indicates that the system should ignore this parameter (i.e., there is no default maximum length). REMAP="UN--Under"For fixed-length datatypes, such as integers, the length of the data is constant, except for the special case of null values. Therefore, for fixed-length datatypes, host_collen must always be -1, except when the data is null, in which case host_collen must be 0. REMAP="UN--Under"For character, text, binary, and image data, host_collen can be -1, 0, or some positive value. If host_collen is -1, the system will use either a length prefix or a terminator sequence to determine the length of the data. (If both are supplied, the system will use the one that results in  the shortest amount of data being copied.) If host_collen is -1 and neither a prefix length nor a  terminator sequence is specified, the system will return an error message. If host_collen is 0, the system assumes the data is null. If host_collen is some positive value, the system uses host_collen as the maximum data length. However, if, in addition to a positive host_collen, a prefix length and/or terminator sequence is provided, the system determines the data length by using the method  that results in the shortest amount of data being copied. host_term - The terminator sequence to be used for this column.  This parameter is mainly useful for character, text, binary, and image data types, because all other types are of fixed length.  To avoid using a terminator, set this parameter to NULL. To set the terminator to the NULL character, set host_term to "\0". To make the tab character the terminator, set host_term to "\ ". To make the newline character the terminator, set host_term to "\n". REMAP="UN--Under"If more than one means of specifying a host file column length is used (such as a terminator and a length prefix, or a terminator and a maximum column length), MOREINFO="NONE"bcp will look at all of them and use the one that results in the shortest amount of data being copied. host_termlen - The length, in bytes, of the terminator sequence to be used for this column. To avoid using a terminator, set this value to -1. table_colnum - The corresponding column in the database table. If this value is 0, this column will not be copied. The first column is column 1. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"bcp_colfmt allows you to specify the host file format for bulk copies. For bulk copy purposes, a format contains the following parts: MARK="DASH" REMAP="BS--BulletSub"A mapping from host file columns to database columns. The datatype of each host file column. The length of the optional length prefix of each column. The maximum length of the host file column's data. The optional terminating byte sequence for each column. The length of this optional terminating byte sequence. Each call to MOREINFO="NONE"bcp_colfmt specifies the format for one host file column. For example, if you have a table with five columns, and want to change the default settings for three of those columns, you should first call "bcp_columns(dbproc, 5)", and then call MOREINFO="NONE"bcp_colfmt five times, with three of those calls setting your custom format. The remaining two calls should have their host_type set to 0, and their  host_prefixlen, host_collen, and host_termlen parameters set to -1.  The result of this would be to copy all five columns-three with your customized format and two with the default format. MOREINFO="NONE"bcp_columns must be called before any calls to MOREINFO="NONE"bcp_colfmt. You must call MOREINFO="NONE"bcp_colfmt for every column in the host file, regardless of whether some of those columns use the default format or are skipped. To skip a column, set the table_column parameter to 0. For information on the MOREINFO="NONE"bcp utility program, see its manual page in the Open Client/Server Supplement. ReturnsREMAP="BO--Body"SUCCEED or FAIL. See AlsoREMAP="BO--Body"LINKEND="X40028"bcp_batch
, LINKEND="X98985"bcp_bind
, LINKEND="X70318"bcp_colfmt_ps
, LINKEND="X12457"bcp_collen
, LINKEND="X88930"bcp_colptr
, LINKEND="X96868"bcp_columns
, LINKEND="X46887"bcp_control
, LINKEND="X90675"bcp_done
, LINKEND="X97799"bcp_exec
, LINKEND="X40041"bcp_init
, LINKEND="X88050"bcp_sendrow
ID="IN4510564831"bcp_colfmt
 ID="IN4513535132"bcp_colfmt_psID="X70318"bcp_colfmt_psID="IN463515434"bcphost file format
ID="IN463495635"bcpspecifying host file format
ID="IN463475836"bcpoverriding default data formats
Specify the format of a host file for bulk copy purposes, with precision and scale support for numeric and decimal columns.FORMAT="LINESPECIFIC"RETCODE bcp_colfmt_ps (dbproc, host_colnum, host_type,                host_prefixlen, host_collen, host_term,                host_termlen, table_colnum, typeinfo)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"int           host_colnum;FORMAT="LINESPECIFIC"int           host_type;FORMAT="LINESPECIFIC"int           host_prefixlen;FORMAT="LINESPECIFIC"DBINT         host_collen;FORMAT="LINESPECIFIC"BYTE          *host_term;FORMAT="LINESPECIFIC"int           host_termlen;FORMAT="LINESPECIFIC"int           table_colnum;FORMAT="LINESPECIFIC"DBTYPEINFO    *typeinfo;ParametersMOREINFO="NONE"bcp_colfmt_ps's parameters are identical to MOREINFO="NONE"bcp_colfmt's, except that MOREINFO="NONE"bcp_colfmt_ps has the additional parameter typeinfo, which contains information about precision and scale for numeric or decimal columns.REMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/SQL Server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and SQL Server. host_colnum - The column in the host file whose format is being specified. The first column is number 1. host_type - The datatype of this column in the host file, expressed as a SQL Server datatype.  If it is different from the datatype of the corresponding column in the database table (table_colnum), the conversion will be performed automatically.  See the MOREINFO="NONE"dbconvert manual page for a table of allowable data conversions. That manual page also contains a list of SQL Server datatypes. REMAP="UN--Under"If you want to specify the same datatype as in the corresponding column of the database table (table_colnum), this parameter should be set to 0. host_prefixlen - The length of the length prefix for this column in the host file.  Legal prefix lengths are 1, 2, and 4 bytes. To avoid using a length prefix, this parameter should be set to 0. To let MOREINFO="NONE"bcp decide whether  to use a length prefix, this parameter should be set to -1. In such a case, MOREINFO="NONE"bcp will use a length prefix (of whatever length is necessary) if the database column length is variable. REMAP="UN--Under"If more than one means of specifying a host file column length is used (such as a length prefix and a maximum column length, or a length prefix and a terminator sequence), MOREINFO="NONE"bcp will look at all of them and use the one that results in the shortest amount of data being copied. REMAP="UN--Under"One valuable use for length prefixes is to simplify the specifying of null data values in a host file.  For instance, assume you have a 1-byte length prefix for a 4-byte integer column. Ordinarily, the length prefix will contain a value of 4, to indicate that a 4-byte value follows. However, if the value of the column is null, the length prefix can be set to 0, to indicate that 0 bytes follow for the column. host_collen - The maximum length of this column's data in the host file, not including the length of any length prefix and/or terminator.  Setting host_collen to 0 signifies that the data is null. Setting host_collen to -1 indicates that the system should ignore this parameter (i.e., there is no default maximum length). REMAP="UN--Under"For fixed-length datatypes, such as integers, the length of the data is constant, except for the special case of null values. Therefore, for fixed-length datatypes, host_collen must always be -1, except when the data is null, in which case host_collen must be 0. REMAP="UN--Under"For character, text, binary, and image data, host_collen can be -1, 0, or some positive value. If host_collen is -1, the system will use either a length prefix or a terminator sequence to determine the length of the data. (If both are supplied, the system will use the one that results in  the shortest amount of data being copied.) If host_collen is -1 and neither a prefix length nor a  terminator sequence is specified, the system will return an error message. If host_collen is 0, the system assumes the data is null. If host_collen is some positive value, the system uses host_collen as the maximum data length. However, if, in addition to a positive host_collen, a prefix length and/or terminator sequence is provided, the system determines the data length by using the method  that results in the shortest amount of data being copied. host_term - The terminator sequence to be used for this column.  This parameter is mainly useful for character, text, binary, and image data types, because all other types are of fixed length.  To avoid using a terminator, set this parameter to NULL. To set the terminator to the NULL character, set host_term to "\0". To make the tab character the terminator, set host_term to "\ ". To make the newline character the terminator, set host_term to "\n". REMAP="UN--Under"If more than one means of specifying a host file column length is used (such as a terminator and a length prefix, or a terminator and a maximum column length), MOREINFO="NONE"bcp will look at all of them and use the one that results in the shortest amount of data being copied. host_termlen - The length, in bytes, of the terminator sequence to be used for this column. To avoid using a terminator, set this value to -1. table_colnum - The corresponding column in the database table. If this value is 0, this column will not be copied. The first column is column 1. typeinfo - A pointer to a DBTYPEINFO structure containing information about the precision and scale of decimal or numeric host file columns. An application sets a DBTYPEINFO structure with values for precision and scale before calling MOREINFO="NONE"bcp_colfmt_ps to specify the host file format of decimal or numeric columns.REMAP="UN--Under"If typeinfo is NULL, MOREINFO="NONE"bcp_colfmt_ps is the equivalent of MOREINFO="NONE"bcp_colfmt. That is:MARK="DASH" REMAP="BS--BulletSub" If the server column is of type numeric or decimal, MOREINFO="NONE"bcp_colfmt_ps picks up precision and scale values from the column.If the server column is not numeric or decimal, MOREINFO="NONE"bcp_colfmt_ps uses a default precision of 18 and a default scale of 0.REMAP="UN--Under"If host_type is not 0, SYBDECIMAL or SYBNUMERIC, typeinfo is ignored.REMAP="UN--Under"If host_type is 0 and the corresponding server column is not numeric or decimal, typeinfo is ignored.REMAP="UN--Under"A DBTYPEINFO structure is defined as follows:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"typedef struct typeinfo {    DBINT   precision;    DBINT   scale;} DBTYPEINFO;REMAP="UN--Under"Legal values for precision are from 1 to 77. Legal values for scale are from 0 to 77. scale must be less than or equal to precision.CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"bcp_colfmt_ps is the equivalent of MOREINFO="NONE"bcp_colfmt, except that MOREINFO="NONE"bcp_colfmt_ps provides precision and scale support for numeric and decimal datatypes, which MOREINFO="NONE"bcp_colfmt does not. Calling MOREINFO="NONE"bcp_colfmt is equivalent to calling MOREINFO="NONE"bcp_colfmt_ps with typeinfo as NULL.MOREINFO="NONE"bcp_colfmt_ps allows you to specify the host file format for bulk copies. For bulk copy purposes, a format contains the following parts: MARK="DASH" REMAP="BS--BulletSub"A mapping from host file columns to database columns. The datatype of each host file column. The length of the optional length prefix of each column. The maximum length of the host file column's data. The optional terminating byte sequence for each column. The length of this optional terminating byte sequence. Each call to MOREINFO="NONE"bcp_colfmt_ps specifies the format for one host file column. For example, if you have a table with five columns, and want to change the default settings for three of those columns, you should first call "bcp_columns(dbproc, 5)", and then call MOREINFO="NONE"bcp_colfmt_ps five times, with three of those calls setting your custom format. The remaining two calls should have their host_type set to 0, and their  host_prefixlen, host_collen, and host_termlen parameters set to -1.  The result of this would be to copy all five columns-three with your customized format and two with the default format. MOREINFO="NONE"bcp_columns must be called before any calls to MOREINFO="NONE"bcp_colfmt_ps. You must call MOREINFO="NONE"bcp_colfmt_ps for every column in the host file, regardless of whether some of those columns use the default format or are skipped. To skip a column, set the table_column parameter to 0. For information on the MOREINFO="NONE"bcp utility program, see its manual page in the Open Client/Server Supplement. ReturnsREMAP="BO--Body"SUCCEED or FAIL. See AlsoREMAP="BO--Body"LINKEND="X40028"bcp_batch
, LINKEND="X98985"bcp_bind
, LINKEND="X63011"bcp_colfmt
, LINKEND="X12457"bcp_collen
, LINKEND="X88930"bcp_colptr
, LINKEND="X96868"bcp_columns
, LINKEND="X46887"bcp_control
, LINKEND="X90675"bcp_done
, LINKEND="X97799"bcp_exec
, LINKEND="X40041"bcp_init
, LINKEND="X88050"bcp_sendrow
ID="IN4613446142"bcp_colfmt_ps
 ID="IN4610416443"bcp_collenID="X12457"bcp_collen
Set the program variable data length for the current copy MOREINFO="NONE"inID="IN473396745"bcpchanging program variable data length
. FORMAT="LINESPECIFIC"RETCODE bcp_collen(dbproc, varlen, table_column)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS      *dbproc;FORMAT="LINESPECIFIC"DBINT          varlen;FORMAT="LINESPECIFIC"int            table_column;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/SQL Server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and SQL Server. varlen - The length of the program variable, which does not include the length of the length prefix or terminator. Setting varlen to 0 signifies that the data is NULL. Setting it to -1 signifies that the data is variable-length and that the length will be determined by the length prefix or terminator. If  both a length prefix and a terminator exist, MOREINFO="NONE"bcp will use the one that results in the shortest amount of data being copied. table_column - The column in the SQL Server table to which the data will be copied. Column numbers start at 1. CommentsMARK="BULL" REMAP="BU--Bullet"The MOREINFO="NONE"bcp_collen function allows you to change the program variable data length for a particular column while running a copy MOREINFO="NONE"in via calls to MOREINFO="NONE"bcp_bind. Initially, the program variable data length is determined when MOREINFO="NONE"bcp_bind is called. If the program variable data length changes between calls to MOREINFO="NONE"bcp_sendrow, and no length prefix or terminator is being used, you may call MOREINFO="NONE"bcp_collen to reset the length. The next call to MOREINFO="NONE"bcp_sendrow will use the length you just set. There must be a separate MOREINFO="NONE"bcp_collen call for every column in the table whose data length you want to modify. For information on the MOREINFO="NONE"bcp utility program, see its manual page in the Open Client/Server Supplement. ReturnsREMAP="BO--Body"SUCCEED or FAIL. See AlsoREMAP="BO--Body"LINKEND="X98985"bcp_bind
,  LINKEND="X88930"bcp_colptr
,  LINKEND="X88050"bcp_sendrow
ID="IN4710367051"bcp_collen
 ID="IN4710337352"bcp_colptrID="X88930"bcp_colptr
Set the program variable data address for the current copy MOREINFO="NONE"inID="IN483317654"bcpchanging program variable data address
. FORMAT="LINESPECIFIC"RETCODE bcp_colptr(dbproc, colptr, table_column)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"BYTE          *colptr;FORMAT="LINESPECIFIC"int           table_column;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/SQL Server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and SQL Server. colptr - The address of the program variable. table_column - The column in the SQL Server table to which the data will be copied. Column numbers start at 1. CommentsMARK="BULL" REMAP="BU--Bullet"The MOREINFO="NONE"bcp_colptr function allows you to change the program variable data address for a particular column while running a copy MOREINFO="NONE"in via calls to MOREINFO="NONE"bcp_bind. Initially, the program variable data address is determined when MOREINFO="NONE"bcp_bind is called. If the program variable data address changes between calls to MOREINFO="NONE"bcp_sendrow, you may call MOREINFO="NONE"bcp_colptr to reset the address of the data.  The next call to MOREINFO="NONE"bcp_sendrow will use the data at the address you just set. There must be a separate MOREINFO="NONE"bcp_colptr call for every column in the table whose data address you want to modify. For information on the MOREINFO="NONE"bcp utility program, see its manual page in the Open Client/Server Supplement. ReturnsREMAP="BO--Body"SUCCEED or FAIL. See AlsoREMAP="BO--Body"LINKEND="X98985"bcp_bind
,  LINKEND="X12457"bcp_collen
,  LINKEND="X88050"bcp_sendrow
ID="IN4810287960"bcp_colptr
 ID="IN4811258261"bcp_columnsID="X96868"bcp_columnsID="IN493238563"bcpsetting number of columns in host file
ID="IN493218764"bcpoverriding default data formats
Set the total number of columns found in the host file. FORMAT="LINESPECIFIC"RETCODE bcp_columns(dbproc, host_colcount)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"int           host_colcount;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/SQL Server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and SQL Server. host_colcount - The total number of columns in the host file. Even if you are preparing to bulk copy data from the host file to a SQL Server table and do not intend to copy all columns in the host file, you must still set host_colcount to the total number of host file columns. CommentsMARK="BULL" REMAP="BU--Bullet"This function sets the total number of columns found in a host file for use with bulk copy. This routine may be called only after MOREINFO="NONE"bcp_init has been called with a valid file name. You should call this routine only if you intend to use a host file format that differs from the default. The default host file format is described on the MOREINFO="NONE"bcp_init manual page. After calling MOREINFO="NONE"bcp_columns, you must call MOREINFO="NONE"bcp_colfmt host_colcount times, because you are defining a completely custom file format. For information on the MOREINFO="NONE"bcp utility program, see its manual page in the Open Client/Server Supplement. ReturnsREMAP="BO--Body"SUCCEED or FAIL. See AlsoREMAP="BO--Body"LINKEND="X63011"bcp_colfmt
, LINKEND="X40041"bcp_init
ID="IN4911189070"bcp_columns
 ID="IN4911159371"bcp_controlID="X46887"bcp_controlID="IN503139673"bcpchanging default data formats
Change various control parameter default settings. FORMAT="LINESPECIFIC"RETCODE bcp_control(dbproc, field, value)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"int           field;FORMAT="LINESPECIFIC"DBINT         value;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/SQL Server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and SQL Server. field - The field can be one of the following: TOCENTRY="1"LBL="Table 3-1: "Values for field (MOREINFO="NONE"bcp_control)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="99*"COLNAME="C2" COLWIDTH="261*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"FieldCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Description VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"BCPMAXERRSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The number of errors allowed before giving up.   The 
default is 10. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"BCPFIRSTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The first row to copy. The default is 1.  A  value of less 
than 1 resets this field to its default  value of 1. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"BCPLASTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The last row to copy. The default is to copy all  rows. A 
value less than 1 resets this field to its  default value. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"BCPBATCHCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The number of rows per batch. The default is 0,  which 
means that the entire bulk copy will be done  in one 
batch.  This field is only meaningful when  copying from 
a host file into SQL Server. value - The value for the specified field. CommentsMARK="BULL" REMAP="BU--Bullet"This function sets various control parameters for bulk copy operations, including the number of errors allowed before aborting a bulk copy, the numbers of the first and last rows to copy, and the batch size. These control parameters are only meaningful when copying between a host file and a SQL Server table. Control parameter settings have no effect on MOREINFO="NONE"bcp_bind row transfers. By default, SQL Server copies all the rows specified in one batch. SQL Server considers each batch to be a separate MOREINFO="NONE"bcp operation. Each batch is copied in a single MOREINFO="NONE"insert transaction, and if any row in the batch is rejected, the entire MOREINFO="NONE"insert is rolled back. MOREINFO="NONE"bcp then continues to the next batch. You can use MOREINFO="NONE"bcp_batch to break large input files into  smaller units of recoverability. For example, if 300,000 rows are bulk copied in with a batch size of 100,000 rows, and there is a fatal error after row 200,000, the first two batches-200,000 rows-will have been successfully copied into SQL Server. If batching had not been used, no rows would have been copied into SQL Server. The following program fragment illustrates MOREINFO="NONE"bcp_control: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"LOGINREC        *login; DBPROCESS       *dbproc; DBINT           rowsread;  /* Initialize DB-Library. */ if (dbinit() == FAIL)      exit(ERREXIT);  /* Install error-handler and message-handler. */ dberrhandle(err_handler); dbmsghandle(msg_handler);  /* Open a DBPROCESS. */ login = dblogin(); bcp_setl(login, TRUE); dbproc = dbopen(login, NULL);  /* Initialize bcp. */ if (bcp_init(dbproc, "comdb..address", "address.add",       "addr.error", DB_IN) == FAIL)      exit(ERREXIT);  /* Set the number of rows per batch. */ if (bcp_control(dbproc, BCPBATCH, 1000) == FAIL) {      printf("bcp_control failed to set batching behavior.\n");      exit(ERREXIT); }  /* Set host column count. */ if (bcp_columns(dbproc, 1) == FAIL) {      printf("bcp_columns failed.\n");      exit(ERREXIT); }  /* Set the host-file format. */ if (bcp_colfmt(dbproc, 1, 0, 0, -1, (BYTE *)("\n"), 1, 1) == FAIL) {      printf("bcp_colformat failed.\n");      exit(ERREXIT); }  /* Now, execute the bulk copy. */ if (bcp_exec(dbproc, &rowsread) == FAIL) {      printf("Incomplete bulk copy.  Only %ld row%c copied.\n",              rowsread, (rowsread == 1) ? ' ': 's');            exit(ERREXIT); } For information on the MOREINFO="NONE"bcp utility program, see its manual page in the Open Client/Server Supplement. ReturnsREMAP="BO--Body"SUCCEED or FAIL. See AlsoREMAP="BO--Body"LINKEND="X40028"bcp_batch
, LINKEND="X98985"bcp_bind
, LINKEND="X63011"bcp_colfmt
, LINKEND="X12457"bcp_collen
, LINKEND="X88930"bcp_colptr
, LINKEND="X96868"bcp_columns
, LINKEND="X90675"bcp_done
, LINKEND="X97799"bcp_exec
, LINKEND="X40041"bcp_init
ID="IN5011109979"bcp_control
 ID="IN508710280"bcp_doneID="X90675"bcp_doneID="IN513510582"bcpending bulk copy from program variables
End a bulk copy from program variables into SQL Server. FORMAT="LINESPECIFIC"DBINT bcp_done(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/SQL Server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and SQL Server. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"bcp_done ends a bulk copy performed with MOREINFO="NONE"bcp_bind and MOREINFO="NONE"bcp_sendrow. It should be called after the last call to MOREINFO="NONE"bcp_sendrow or MOREINFO="NONE"bcp_moretext. Failure to call MOREINFO="NONE"bcp_done after you have completed copying in all your data will result in unpredictable errors. For information on the MOREINFO="NONE"bcp utility program, see its manual page in the Open Client/Server Supplement. ReturnsREMAP="BO--Body"The number of rows permanently saved since the last call to MOREINFO="NONE"bcp_batch, or -1 in case of error. See AlsoREMAP="BO--Body"LINKEND="X40028"bcp_batch
,  LINKEND="X98985"bcp_bind
,  LINKEND="X18177"bcp_moretext
, LINKEND="X88050"bcp_sendrow
ID="IN518210888"bcp_done
 ID="IN518-111189"bcp_execID="X97799"bcp_execID="IN523-311491"bcpexecuting
Execute a bulk copy of data between a database table and a host file. FORMAT="LINESPECIFIC"RETCODE bcp_exec(dbproc, rows_copied)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"DBINT         *rows_copied;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/SQL Server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and SQL Server. rows_copied - A pointer to a DBINT. MOREINFO="NONE"bcp_exec will fill this DBINT with the number of rows successfully copied. If set to NULL, this parameter will not be filled in by MOREINFO="NONE"bcp_exec. CommentsMARK="BULL" REMAP="BU--Bullet"This routine copies data from a host file to a database table or vice-versa, depending on the value of the direction parameter in MOREINFO="NONE"bcp_init. Before calling this function you must call MOREINFO="NONE"bcp_init with a valid host filename. Failure to do so will result in an error. The following program fragment illustrates MOREINFO="NONE"bcp_exec: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"LOGINREC        *login; DBPROCESS       *dbproc; DBINT           rowsread;  /* Initialize DB-Library. */ if (dbinit() == FAIL)       exit(ERREXIT);  /* Install error-handler and message-handler. */ dberrhandle(err_handler); dbmsghandle(msg_handler);  /* Open a DBPROCESS. */ login = dblogin(); bcp_setl(login, TRUE); dbproc = dbopen(login, NULL);  /* Initialize bcp. */ if (bcp_init(dbproc, "pubs2..authors", "authors.save",       (BYTE *)NULL, DB_OUT) == FAIL)      exit(ERREXIT);  /* Now, execute the bulk copy. */ if (bcp_exec(dbproc, &rowsread) == FAIL)      printf("Incomplete bulk copy.  Only %ld row%c copied.\n",              rowsread, (rowsread == 1) ? ' ': 's'); For information on the MOREINFO="NONE"bcp utility program, see its manual page in the Open Client/Server Supplement. ReturnsREMAP="BO--Body"SUCCEED or FAIL. MOREINFO="NONE"bcp_exec returns SUCCEED if all rows are copied. If a partial or complete failure occurs, MOREINFO="NONE"bcp_exec returns FAIL. Check the rows_copied parameter for the number of rows successfully copied. See AlsoREMAP="BO--Body"LINKEND="X40028"bcp_batch
, LINKEND="X98985"bcp_bind
, LINKEND="X63011"bcp_colfmt
, LINKEND="X12457"bcp_collen
, LINKEND="X88930"bcp_colptr
, LINKEND="X96868"bcp_columns
, LINKEND="X46887"bcp_control
, LINKEND="X90675"bcp_done
, LINKEND="X40041"bcp_init
, LINKEND="X88050"bcp_sendrow
ID="IN528-611797"bcp_exec
 ID="IN528-912098"bcp_getlbcp_getl
Determine if the LOGINREC has been set for bulk copy operations. FORMAT="LINESPECIFIC"DBBOOL bcp_getl(loginrec) FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"LOGINREC        *loginrec; ParametersREMAP="RI--RefIndent"loginrec - A pointer to a LOGINREC structure, which will be passed as an argument to MOREINFO="NONE"dbopen.  You can get a LOGINREC structure by calling MOREINFO="NONE"dblogin. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"bcp_getl returns TRUE if *loginrec is enabled for bulk copy operations, and FALSE if  it is not. A DBPROCESS connection cannot be used for bulk copy MOREINFO="NONE"in operations unless the LOGINREC used to open the connection  has been set to enable bulk copy.   The macro MOREINFO="NONE"bcp_setl sets a LOGINREC to enable bulk copy. By default, DBPROCESSes are not enabled for bulk copy operations. Applications that allow users to make ad hoc queries may  want to avoid calling MOREINFO="NONE"bcp_setl in order to keep users  from initiating a bulk copy sequence via SQL commands.   Once a bulk copy sequence has begun, it cannot be stopped via an ordinary SQL command. If LOGINREC is NULL, MOREINFO="NONE"bcp_getl returns FALSE. ReturnsREMAP="BO--Body"TRUE or FALSE. See AlsoREMAP="BO--Body"LINKEND="X40041"bcp_init
, LINKEND="X54146"bcp_setl
, LINKEND="X88162"dblogin
, LINKEND="X42139"dbopen
ID="IN538-12124105"bcp_getl
  ID="IN538-15127106"bcp_initID="X40041"bcp_initID="IN543-17130108"bcpinitializing
Initialize bulk copy. FORMAT="LINESPECIFIC"RETCODE bcp_init(dbproc, tblname, hfile, errfile,                 direction)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"char          *tblname;FORMAT="LINESPECIFIC"char          *hfile;FORMAT="LINESPECIFIC"char          *errfile;FORMAT="LINESPECIFIC"int           direction;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/SQL Server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and SQL Server. tblname - The name of the database table to be copied in or out. This name may also include the database name or the owner name. For example, "pubs2.gracie.titles", "pubs2..titles", "gracie.titles", and "titles" are all legal table names. hfile - The name of the host file to be copied in or out. If no host file is involved (the situation when data is being copied directly from variables), hfile should be NULL. errfile - The name of the error file to be used. This error file will be filled with progress messages, error messages, and copies of any rows which, for any reason, could not be copied from a host file to a SQL Server table.REMAP="UN--Under"If errfile is NULL, no error file is used. REMAP="UN--Under"If hfile is NULL, errfile is ignored. This is because an error file is not necessary when bulk-copying from program variables.direction - The direction of the copy. It must be one of two  values-DB_IN or DB_OUT. DB_IN indicates a copy from the host into the database table, while DB_OUT indicates a copy from the database table into the host file. REMAP="UN--Under"It is illegal to request a bulk copy from the  database table (DB_OUT) without supplying a host file name. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"bcp_init performs the necessary initializations for a bulk copy of data between the front-end and a SQL Server. It sets the default host file data formats and examines the structure of the database table. MOREINFO="NONE"bcp_init must be called before any other bulk copy functions. Failure to do so will result in an error. If a host file is being used (see the description of the hfileID="IN543-19132112"bcpdefault data formats
 parameter, below), the default data formats are as follows: MARK="DASH" REMAP="BS--BulletSub"The order, type, length and number of the columns in the host file are assumed to be identical to the order, type and number of the columns in the database table. If a given database column's data is fixed-length, then the host file's data column will also be fixed-length. If a given database column's data is variable-length or may contain NULL values, the host file's data column will be prefixed by a 4-byte length value for SYBTEXT and SYBIMAGE data types, and a 1-byte length value for all other types. There are no terminators of any kind between host file columns. REMAP="UN--Under"Any of these defaults can be overridden by calling MOREINFO="NONE"bcp_columns and MOREINFO="NONE"bcp_colfmt. To use the bulk copy routines to copy data to a database table requires the following: MARK="DASH" REMAP="BS--BulletSub"The DBPROCESS structure must be usable for bulk copy purposes. This is accomplished by calling MOREINFO="NONE"bcp_setl: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"login = dblogin(); bcp_setl(login, TRUE); If the table has no indexes,  the database optionMOREINFO="NONE" select into/bulkcopy must be set to "true". The following SQL command will do this: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"sp_dboption 'mydb', 'select into/bulkcopy', 'true' REMAP="UN--Under"See the SQL Server Reference Manual for further details on MOREINFO="NONE"sp_dboption. If no host file is being used, it's necessary to call MOREINFO="NONE"bcp_bind to specify the format and location in memory of each column's data value. If no host file is being used, errfile is ignored. An error file is not necessary when bulk-copying from program variables because MOREINFO="NONE"bcp_sendrow returns FAIL if an error occurs. In this case, the application can examine the bulk copy program variables to determine which row values caused the error.For information on the MOREINFO="NONE"bcp utility program, see its manual page in the Open Client/Server Supplement. ReturnsREMAP="BO--Body"SUCCEED or FAIL. See AlsoREMAP="BO--Body"LINKEND="X40028"bcp_batch
, LINKEND="X98985"bcp_bind
, LINKEND="X63011"bcp_colfmt
, LINKEND="X12457"bcp_collen
, LINKEND="X88930"bcp_colptr
, LINKEND="X96868"bcp_columns
, LINKEND="X46887"bcp_control
, LINKEND="X90675"bcp_done
, LINKEND="X97799"bcp_exec
, LINKEND="X88050"bcp_sendrow
ID="IN548-22135115"bcp_init
 ID="IN5412-25138116"bcp_moretextID="X18177"bcp_moretextID="IN553-27141118"bcpsending text/image values
ID="IN5511-27141119"Text valuesbulk copying parts
ID="IN5512-27141120"Image valuesbulk copying parts
Send part of a text or image value to SQL Server. FORMAT="LINESPECIFIC"RETCODE bcp_moretext(dbproc, size, text)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"DBINT         size;FORMAT="LINESPECIFIC"BYTE          *text;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/SQL Server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and SQL Server. size - The size of this particular part of the text or image value being sent to SQL Server. It is an error to send more text or image bytes to SQL Server than were specified in the call to MOREINFO="NONE"bcp_bind or MOREINFO="NONE"bcp_collen. text - A pointer to the text or image portion to be written. CommentsMARK="BULL" REMAP="BU--Bullet"This routine is used in conjunction with MOREINFO="NONE"bcp_bind and MOREINFO="NONE"bcp_sendrow to send a large SYBTEXT or SYBIMAGE value to SQL Server in the form of a number of smaller chunks. This is particularly useful with operating systems  unable to allocate extremely long data buffers. If MOREINFO="NONE"bcp_bind is called with a type parameter of SYBTEXT or SYBIMAGE and a non-NULL varaddr parameter, MOREINFO="NONE"bcp_sendrow will send the entire text or image data value, just as it does for all other datatypes. If, however, MOREINFO="NONE"bcp_bind has a NULL varaddr parameter, MOREINFO="NONE"bcp_sendrow will return control to the application immediately after all non-text or image columns are sent to SQL Server. The application can then call MOREINFO="NONE"bcp_moretext repeatedly to send the text and image columns to SQL Server, a chunk at a time. Here's an example that illustrates how to use MOREINFO="NONE"bcp_moretext with MOREINFO="NONE"bcp_bind and MOREINFO="NONE"bcp_sendrow: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"LOGINREC        *login; DBPROCESS       *dbproc;  DBINT           id = 5; char            *part1 = "This text value isn't very long,"; char            *part2 = " but it's broken up into three parts"; char            *part3 = " anyhow.";  /* Initialize DB-Library. */ if (dbinit() == FAIL)       exit(ERREXIT);        /* Install error handler and message handler. */ dberrhandle(err_handler); dbmsghandle(msg_handler);        /* Open a DBPROCESS */ login = dblogin(); bcp_setl(login, TRUE); dbproc = dbopen(login, NULL);  /* Initialize bcp. */ if (bcp_init(dbproc, "comdb..articles", (BYTE *)NULL,       (BYTE *)NULL, DB_IN) == FAIL)      exit(ERREXIT);  /* Bind program variables to table columns. */ if (bcp_bind(dbproc, (BYTE *)&id, 0, (DBINT)-1,       (BYTE *)NULL, 0, SYBINT4, 1) == FAIL) {      fprintf(stderr, "bcp_bind, column 1, failed.\n");      exit(ERREXIT); }  if (bcp_bind       (dbproc, (BYTE *)NULL, 0,        (DBINT) (strlen(part1) + strlen(part2) + strlen(part3)),       (BYTE *)NULL, 0, SYBTEXT, 2)       == FAIL) {       fprintf(stderr, "bcp_bind, column 2, failed.\n");       exit(ERREXIT); }  /* ** Now send this row, with the text value broken into  ** three chunks.  */ if (bcp_sendrow(dbproc) == FAIL)      exit(ERREXIT); if (bcp_moretext(dbproc, (DBINT)strlen(part1), part1) == FAIL)      exit(ERREXIT); if (bcp_moretext(dbproc, (DBINT)strlen(part2), part2) == FAIL)      exit(ERREXIT); if (bcp_moretext(dbproc, (DBINT)strlen(part3), part3) == FAIL)      exit(ERREXIT);  /* We're all done. */ bcp_done(dbproc); dbclose(dbproc); If you use MOREINFO="NONE"bcp_moretext to send one text or image column in the row, you must also use it to send all other text and image columns in the row. If the row contains more than one text or image column, MOREINFO="NONE"bcp_moretext will first send its data to the lowest-numbered (i.e., leftmost) text or image column, followed by the next lowest-numbered column, and so on. An application will normally call MOREINFO="NONE"bcp_sendrow and MOREINFO="NONE"bcp_moretext within loops, in order to send a number of rows of data. Here's an outline of how to do this for a table containing two text columns: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"while (there are still rows to send) {     bcp_sendrow(...);      for (all the data in the first text column)         bcp_moretext(...);      for (all the data in the second text column)         bcp_moretext(...); } For information on the MOREINFO="NONE"bcp utility program, see its manual page in the Open Client/Server Supplement. ReturnsREMAP="BO--Body"SUCCEED or FAIL. See AlsoREMAP="BO--Body"LINKEND="X98985"bcp_bind
, LINKEND="X88050"bcp_sendrow
, LINKEND="X96538"dbmoretext
, LINKEND="X38408"dbwritetext
ID="IN5512-30144126"bcp_moretext
 ID="IN5511-33147127"bcp_options
ID="IN5517-33147128"Secure SQL Serverand bcpbcp_optionsID="IN563-35150130"bcpsetting options for
ID="IN563-37152131"bcpand Secure SQL Server
ID="IN563-39154132"bcpBCPLABELED option
Set bulk copy options.FORMAT="LINESPECIFIC"RETCODE bcp_options (dbproc, option, value, valuelen)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"int           option;FORMAT="LINESPECIFIC"BYTE          *value;FORMAT="LINESPECIFIC"int           valuelen;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/SQL Server process. It contains all the information that DB-Library uses to manage communications and data between the front end and SQL Server. option - The bulk library option being set. The following values are legal for option:TOCENTRY="1"LBL="Table 3-2: "Values for option (MOREINFO="NONE"bcp_options)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="120*"COLNAME="C2" COLWIDTH="239*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Value of option:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The option determines:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"BCPLABELEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether or not data for the sensitivity column is 
included in a bulk copy operation. By default,  
sensitivity column data is not included.

This option pertains to Secure SQL Server copies 
only.value - A generic BYTE pointer to the value of the specified option. As the following table describes, what value should point to depends on option:TOCENTRY="1"LBL="Table 3-3: "Values for value (MOREINFO="NONE"bcp_options)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="120*"COLNAME="C2" COLWIDTH="239*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"option is:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"valueVALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"BCPLABELEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A DBBOOL value. Set *value to TRUE to enable a 
bulk copy with sensitivity labels. Set *value to 
FALSE for a normal bulk copy operation.valuelen - The length of the data to which value points. If value points to a fixed-length item (e.g. a DBBOOL, DBINT, etc.), pass valuelen as -1.CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"bcp_options sets bulk copy options.Currently the only bulk copy option available is BCPLABELED.MOREINFO="NONE"BCPLABELEDMARK="BULL" REMAP="BU--Bullet"BCPLABELLED determines whether or not data for the sensitivity column is included in a bulk copy operation. By default, sensitivity column data is not included.BCPLABELLED pertains to Secure SQL Server copies only.BCPLABELLED affects both bulk copy in and bulk copy out operations:MARK="DASH" REMAP="BS--BulletSub"If BCPLABELLED is CS_TRUE, the application must supply data for the sensitivity column on bulk copy in operations andwill receive data from the sensitivity column on bulk copy out operations.If BCPLABELLED is CS_FALSE, the application does not need to supply data for the sensitivity column on bulk copy in operations and will not receive data from the sensitivity column on bulk copy out operations.BCPLABELLED is applicable to Secure SQL Server copies only. MOREINFO="NONE"bcp_init fails if BCPLABELLED is TRUE and a bulk copy operation is attempted against a standard SQL Server.Users copying into the sensitivity column must have the MOREINFO="NONE"bcpin_labels_role role activated on Secure SQL Server. MOREINFO="NONE"bcp_init fails if the user does not have the MOREINFO="NONE"bcpin_labels_role.For information on the MOREINFO="NONE"bcp utility program, see its manual page in the Open Client/Server Supplement. For information on Secure SQL Server, see your Secure SQL Server documentation.ReturnsREMAP="BO--Body"SUCCEED or FAIL. See AlsoREMAP="BO--Body"LINKEND="X40041"bcp_init
, LINKEND="X46887"bcp_control
ID="IN5611-42157138"bcp_readfmtID="X63672"bcp_readfmtID="IN573-44160140"bcpcopying multiple files
ID="IN573-46162141"bcpreading format definitions
Read a datafile format definition from a host file. FORMAT="LINESPECIFIC"RETCODE bcp_readfmt(dbproc, filename)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"char          *filename;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a  particular front end/SQL Server process. It contains all the information that DB-Library uses to manage communications and data between the front end and SQL Server. filename - The full directory specification of the file containing the format definitions. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"bcp_readfmt reads a datafile format definition from a host file, then makes the appropriate calls to MOREINFO="NONE"bcp_columns and MOREINFO="NONE"bcp_colfmt. This automates the bulk copy of multiple files which share a common data format. MOREINFO="NONE"bcp, the bulk copy utility, copies a database table to or from a host file in a user-specified format. User-specified formats may be saved via MOREINFO="NONE"bcp in datafile format definition files, which can later be used to automate the bulk copy of files that share a common format. See the Open Client/Server Supplement for more information on the MOREINFO="NONE"bcp utility and datafile format definition files. Application programs can call MOREINFO="NONE"bcp_writefmt to create files with datafile format definitions. The following code fragment illustrates the use of MOREINFO="NONE"bcp_readfmt: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"bcp_init(dbproc, "mytable", "bcpdata", "bcperrs", DB_IN); bcp_readfmt(dbproc, "my_fmtfile"); bcp_exec(dbproc, &rows_copied); ReturnsREMAP="BO--Body"SUCCEED or FAIL. See AlsoREMAP="BO--Body"LINKEND="X63011"bcp_colfmt
, LINKEND="X96868"bcp_columns
, LINKEND="X66287"bcp_writefmt
ID="IN5711-49165147"bcp_readfmt
 ID="IN5711-52168148"bcp_sendrowID="X88050"bcp_sendrowID="IN583-54171150"bcpsending data from program variables
Send a row of data from program variables to SQL Server. FORMAT="LINESPECIFIC"RETCODE bcp_sendrow(dbproc)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a particular front-end/SQL Server process.  It contains all the information that DB-Library uses to manage communications and data between the front end and SQL Server. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"bcp_sendrow builds a row from program variables and sends it to SQL Server. Before calling MOREINFO="NONE"bcp_sendrow, you must make calls to MOREINFO="NONE"bcp_bind to specify the program variables to be used. If MOREINFO="NONE"bcp_bind is called with a type parameter of SYBTEXT or SYBIMAGE and a non-NULL varaddr parameter, MOREINFO="NONE"bcp_sendrow will send the entire text or image data value, just as it does for all other datatypes. If, however, MOREINFO="NONE"bcp_bind has a NULL varaddr parameter, MOREINFO="NONE"bcp_sendrow will return control to the application immediately after all non-text or image columns are sent to SQL Server. The application can then call MOREINFO="NONE"bcp_moretext repeatedly to send the text and image columns to SQL Server, a chunk at a time. For an example, see the MOREINFO="NONE"bcp_moretext manual page. After the last call to MOREINFO="NONE"bcp_sendrow, you must call MOREINFO="NONE"bcp_done to ensure proper internal cleanup. When MOREINFO="NONE"bcp_sendrow is used to bulk copy rows from program variables into SQL Server tables, rows are permanently saved in SQL Server only when the user calls MOREINFO="NONE"bcp_batch or MOREINFO="NONE"bcp_done. REMAP="UN--Under"The user may choose to call MOREINFO="NONE"bcp_batch once every n rows, or when there is a lull between periods of incoming data (as in a telemetry application). Of course, the user may choose some other criteria or may decide not to call MOREINFO="NONE"bcp_batch at all. If MOREINFO="NONE"bcp_batch is never called, the rows are permanently saved in SQL Server when MOREINFO="NONE"bcp_done is called. For information on the MOREINFO="NONE"bcp utility program, see its manual page in the Open Client/Server Supplement. ReturnsREMAP="BO--Body"SUCCEED or FAIL. See AlsoREMAP="BO--Body" LINKEND="X40028"bcp_batch
, LINKEND="X98985"bcp_bind
, LINKEND="X63011"bcp_colfmt
, LINKEND="X12457"bcp_collen
, LINKEND="X88930"bcp_colptr
, LINKEND="X96868"bcp_columns
, LINKEND="X46887"bcp_control
, LINKEND="X90675"bcp_done
, LINKEND="X97799"bcp_exec
, LINKEND="X40041"bcp_init
, LINKEND="X18177"bcp_moretext
 ID="IN588-57174156"BCP_SETLID="X54146"bcp_setl
Set the LOGINRECID="IN593-61179158"bcpsetting LOGINREC for
ID="IN5918-65183159"LOGINREC structuresetting for bcp
ID="IN593-67185160"bcpenabling
 for bulk copy "copy in" operations. FORMAT="LINESPECIFIC"RETCODE bcp_setl(loginrec, enable)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"LOGINREC     *loginrec;FORMAT="LINESPECIFIC"DBBOOL       enable;ParametersREMAP="RI--RefIndent"loginrec - This is a pointer to a LOGINREC structure, which will  be passed as an argument to MOREINFO="NONE"dbopen. You can get one by calling MOREINFO="NONE"dblogin. enable - This is a Boolean value (TRUE or FALSE), which specifies whether or not to enable bulk copy operations for the resulting DBPROCESS. By default, DBPROCESSes are not enabled for bulk copy operations. CommentsMARK="BULL" REMAP="BU--Bullet"This macro sets a field in the LOGINREC structure that tells SQL Server that the DBPROCESS connection may be used for bulk copy operations. To have any effect, it must be called before MOREINFO="NONE"dbopen, the routine that actually allocates the DBPROCESS structure. Applications that allow users to make ad hoc queries may want to avoid calling this macro, or call it with the enable parameter FALSE, to keep users from initiating a bulk copy sequence via SQL commands. Once a bulk copy sequence has begun, it cannot be stopped via an ordinary SQL command. For information on the MOREINFO="NONE"bcp utility program, see its manual page in the Open Client/Server Supplement. MOREINFO="NONE"bcp_setl applies to "copy in" operations only. ReturnsREMAP="BO--Body"SUCCEED or FAIL. See AlsoREMAP="BO--Body"LINKEND="X40041"bcp_init
,  LINKEND="X88162"dblogin
,  LINKEND="X42139"dbopen
, LINKEND="X75775"DBSETLAPP
,  LINKEND="X47887"DBSETLHOST
,  LINKEND="X60994"DBSETLPWD
,  LINKEND="X77719"DBSETLUSER
ID="IN598-70188166"BCP_SETL
 ID="IN5912-73191167"bcp_setxlatebcp_setxlateID="IN603-75194169"bcpcharacter set translations for
ID="IN6026-77196170"Character set translationsspecifying for bcp
Specify the character set translations to use when retrieving data from or inserting data into a SQL Server. FORMAT="LINESPECIFIC"RETCODE bcp_setxlate(dbproc, xlt_tosrv, xlt_todisp)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"DBXLATE       *xlt_tosrv;FORMAT="LINESPECIFIC"DBXLATE       *xlt_todisp;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a  particular front end/SQL Server process.  It contains all the information that  DB-Library uses to manage communications and data between the front end  and SQL Server. xlt_tosrv - A pointer to a translation structure. The translation structure is allocated via MOREINFO="NONE"dbload_xlate. xlt_tosrv indicates the character set translation to use when moving data from the application program to the SQL Server (the "copy in", or DB_IN, direction). xlt_todisp - A pointer to a translation structure. The translation structure is allocated via MOREINFO="NONE"dbload_xlate. xlt_todisp indicates the character set translation to use when moving data from SQL Server to the application program (the "copy out", or DB_OUT, direction). CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"bcp_setxlate specifies the character set translations to use when transferring character data between the SQL Server and a front-end application program via MOREINFO="NONE"bcp. The specified character set translations need not be the same as those being used to display or input data on the user's terminal. The translations may be used to read or write a data file in a completely different character set that is not intended for immediate display. The following code fragment illustrates the use of MOREINFO="NONE"bcp_setxlate: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"bcp_init(dbproc, "mytable", "bcpdata", "bcperrs", DB_OUT); bcp_setxlate(dbproc, xlt_tosrv, xlt_todisp); bcp_columns(dbproc, 3); bcp_colfmt(dbproc, 1, SYBCHAR, 0, -1, "\ ", 1, 1); bcp_colfmt(dbproc, 2, SYBCHAR, 0, -1, "\ ", 1, 2); bcp_colfmt(dbproc, 3, SYBCHAR, 0, -1, "\n", 1, 3); bcp_exec(dbproc); ReturnsREMAP="BO--Body"SUCCEED or FAIL. See AlsoREMAP="BO--Body"LINKEND="X43669"dbfree_xlate
, LINKEND="X57212"dbload_xlate
, LINKEND="X19114"dbxlate
ID="IN6012-80199176"bcp_setxlate
 ID="IN6012-83202177"bcp_writefmtID="X66287"bcp_writefmtID="IN613-85205179"bcpwriting format definitions to a file
ID="IN613-87207180"bcpcopying multiple files
Write a datafile format definition to a host file. FORMAT="LINESPECIFIC"RETCODE bcp_writefmt(dbproc, filename)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *dbproc;FORMAT="LINESPECIFIC"char          *filename;ParametersREMAP="RI--RefIndent"dbproc - A pointer to the DBPROCESS structure that provides the connection for a  particular front-end/SQL Server process.  It contains all the information that  DB-Library uses to manage communications and data between the front end  and SQL Server. filename - The full directory specification of the file which contains the format definitions. CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"bcp_writefmt writes a datafile format definition to a host file. The format reflects previous calls to MOREINFO="NONE"bcp_columns and MOREINFO="NONE"bcp_colfmt. MOREINFO="NONE"bcp, the bulk copy utility, copies a database table to or from a host file in a user-specified format. User-specified formats may be saved via MOREINFO="NONE"bcp in "datafile format definition files," which can later be used to automate the bulk copy of files which share a common format. See the Open Client/Server Supplement for more information on the MOREINFO="NONE"bcp utility and datafile format definition files. Format definition files are read via MOREINFO="NONE"bcp_readfmt. The following code fragment illustrates the use of MOREINFO="NONE"bcp_writefmt: REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"bcp_init(dbproc, "mytable", "bcpdata", "bcperrs", DB_OUT);  bcp_columns(dbproc, 3); bcp_colfmt(dbproc, 1, SYBCHAR, 0, -1, "\ ", 1, 1); bcp_colfmt(dbproc, 2, SYBCHAR, 0, -1, "\ ", 1, 2); bcp_colfmt(dbproc, 3, SYBCHAR, 0, -1, "\n", 1, 3);  bcp_writefmt(dbproc, "my_fmtfile"); bcp_exec(dbproc, &rows_copied); ReturnsREMAP="BO--Body"SUCCEED or FAIL. See AlsoREMAP="BO--Body"bcp, LINKEND="X63011"bcp_colfmt
, LINKEND="X96868"bcp_columns
, LINKEND="X63672"bcp_readfmt
ID="IN6112-90210186"bcp_writefmt
 REMAP="BO--Body"NUMBER="4" ID="X74178"Two-Phase Commit ServiceRENDERAS="SECT1"Programming Distributed Transactions   ID="IN41010011"SQL Serverupdating among multiple
ID="IN4559832"Distributed transactions. See Two-phase commit service.
ID="IN4129563"Transactionsdistributed. See Two-phase commit service.
ID="IN4249474"Two-phase commit service
ID="IN4189475"Updating databasesUpdating databaseson multiple serversmultiple servers
ID="IN499476"DatabasesDatabasesupdating:on multiple serversupdating:multiple serversREMAP="BO--Body"The two-phase commit service allows an application to coordinate updates among two or more SQL Servers. This initial implementation of distributed transactions treats separate transactions (which may be on separate SQL Servers) as if they were a single transaction. The commit service uses one SQL Server, the "commit server," as a central record-keeper that helps the application determine whether  to commit, or whether to roll back transactions in case of failure. Thus, the two-phase commit guarantees  that either all the databases on the participating servers are updated or that none of them are.REMAP="BO--Body"A distributed transaction is performed by submitting  Transact-SQL statements to the SQL Servers via DB-Library routines. An application program opens a session with each server, issues the update commands, and then prepares to commit the transaction. Through DB-Library, the application issues to each participating server: MARK="BULL" REMAP="BU--Bullet"A MOREINFO="NONE"begin MOREINFO="NONE"transaction with identifying information on the application, the transaction, and the commit server. The Transact-SQL update statements. A MOREINFO="NONE"prepare MOREINFO="NONE"transaction statement that  indicates that the updates have been performed and that the server is prepared to commit. REMAP="BO--Body"After the updates have been performed on all the servers participating in the distributed transaction, the two-phase commit begins. In the first phase, all servers agree that they are ready to commit. In the second phase,  the application informs the commit service that the transaction is complete (i.e., that the commit will take place), and a MOREINFO="NONE"commit MOREINFO="NONE"transaction is then issued to all of the servers, causing them to commit. REMAP="BO--Body"If an error occurs between phase one and phase two, all servers coordinate with the commit service to determine whether the transaction should be committed or aborted. If certain types of errors occur during a two-phase transaction, SQL Server may need to mark a two-phase process as infected.  Marking the process as infected rather than killing it aids in later error recovery. To ensure that SQL Server is able to mark processes as infected, boot SQL Server with the flag "-T3620" passed on the command line. RENDERAS="SECT1"The Commit Service and the Application Program   REMAP="BO--Body"The role of the commit service is to be a single place of record that helps the application decide whether  the transaction should be committed or aborted. REMAP="BO--Body"If the SQL Servers are all prepared to commit, the application notifies the commit service to mark the transaction as committed. Once this happens, the transaction is committed despite any failures that might subsequently happen. REMAP="BO--Body"If any SQL Server or the application program  fails before the MOREINFO="NONE"prepare MOREINFO="NONE"transaction statement, the SQL Server will MOREINFO="NONE"rollback the transaction. REMAP="BO--Body"If any SQL Server or the application program fails after  the MOREINFO="NONE"prepare but before the MOREINFO="NONE"commit, the SQL Server will communicate with the server  functioning as the commit service and ask it whether to MOREINFO="NONE"rollback or MOREINFO="NONE"commit. REMAP="BO--Body"If the SQL Server cannot communicate with the server functioning as the commit service, it will mark the user task process as infected in SQL Server. At this point, the system administrator can either kill the infected process immediately, or wait until communication to the commit service is restored to kill the infected process. MARK="BULL" REMAP="BU--Bullet"If the system administrator kills the infected process  immediately, two-phase commit protocol is violated and the integrity of the two-phase transaction is not guaranteed. Servers participating in the transaction may be in inconsistent states. If the system administrator kills the infected process after communication with the commit service has been restored, the SQL Server will communicate with the commit service to determine whether or not to commit the transaction locally.  The  integrity of the two-phase transaction is guaranteed. REMAP="BO--Body"To decide whether or not to kill the infected process immediately, the system administrator must consider the estimated downtime of the commit service, the number and importance of locks held by the infected process, and the complexity of the transaction in progress. REMAP="BO--Body"The role of the application program is to deliver the Transact-SQL statements to the SQL Servers in the proper order, using the proper DB-Library routines. The role of the commit service is to provide a single place where the commit/rollback status is maintained. The SQL Servers communicate with the commit service only if a failure happens during the two-phase commit. ID="IN4199297"DBPROCESS structureDBPROCESS structureand two-phase commit servicetwo-phase commit service
ID="IN42490118"Two-phase commit serviceTwo-phase commit serviceand DBPROCESSDBPROCESSREMAP="BO--Body"The commit service needs its own DBPROCESS, separate from the DBPROCESSes used for the distributed transaction, to perform its record-keeping. Note, however, that the server handling the commit service can also be  one of the servers participating in the transaction, as long as the  commit service has its own DBPROCESS. In fact, all the servers involved in the transaction can be one and the same. RENDERAS="SECT1"The Probe Process   REMAP="BO--Body"If any server must recover the transaction, it initiates a process, MOREINFO="NONE"probe, that determines the last known status of the transaction. After it returns the status of that transaction to the commit service, the MOREINFO="NONE"probe process dies. The MOREINFO="NONE"probe process makes use of MOREINFO="NONE"stat_xact,  the same status-checking routine that the commit service uses to check on the progress of a distributed transaction. RENDERAS="SECT1"The Two-Phase Commit Routines   REMAP="BO--Body"The routines that make up the two-phase commit service are: MARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"open_commit - opens a connection with the commit service. The routine is given the login ID of the user initiating the session and the name of the commit service. It returns a pointer to a DBPROCESS structure used in subsequent commit service calls. MOREINFO="NONE"start_xact - records the start of a distributed transaction, and stores initial information about the transaction (DBPROCESS id, application name, transaction name, and number of sites participating) in a lookup table on the commit server. It returns the commid identifying number for the transaction. MOREINFO="NONE"build_xact_string - builds a name string for use by each participating SQL Server for its MOREINFO="NONE"begin MOREINFO="NONE"transaction and MOREINFO="NONE"prepare MOREINFO="NONE"transaction statements. This string encodes the application's transaction name, the commit service name, and the commid. MOREINFO="NONE"commit_xact - tells the commit service to commit the transaction. MOREINFO="NONE"abort_xact - tells the commit service to abort the transaction. MOREINFO="NONE"remove_xact - decrements the count of servers still participating in the transaction. MOREINFO="NONE"close_commit - closes the connection with the commit service. REMAP="BO--Body"Two additional routines are used for ongoing status reports: MARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"scan_xact - returns the status of a single or all distributed transactions. MOREINFO="NONE"stat_xact - returns the completion status of a distributed transaction. REMAP="BO--Body"During the course of a session, the diagnostic routines MOREINFO="NONE"scan_xact and  MOREINFO="NONE"stat_xact are used to check that the commit service carried out the request. REMAP="BO--Body"The MOREINFO="NONE"scan_xact routine uses the commit service lookup table, MOREINFO="NONE"spt_committab, which holds the values of: MARK="BULL" REMAP="BU--Bullet"The transaction IDThe time the transaction started The last time the row was updated The number of servers initially involved in the transaction The number of servers that still have not completed The status (`a'-abort, `c'-commit, `b'-begin) The application name The transaction name REMAP="BO--Body"The two-phase commit routines call internal stored procedures (e.g., MOREINFO="NONE"sp_start_xact) that are created in each server's master database. The MOREINFO="NONE"installmaster script creates the commit service lookup table and stored procedures in each server's master database, for use whenever that server becomes a commit server. RENDERAS="SECT1"Specifying the Commit Server   ID="IN42486159"Two-phase commit serviceTwo-phase commit serviceand interfaces fileinterfaces fileREMAP="BO--Body"The commit server must have an entry in the interfaces file on each machine participating in the distributed transaction. On the machine on which the commit server is actually running, the commit server entry must specify the usual ports described in the Open Client/Server Supplement,  including a query port. For example: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"SERVICE     console tcp sun-ether rose 2002      master tcp sun-ether rose 2001      debug tcp sun-ether rose 2003      query tcp sun-ether rose 2001  REMAP="BO--Body"On any additional machines containing other servers participating in the distributed transaction, the commit server entry need specify only the query port: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"SERVICE     query tcp sun-ether rose 2001  SITEA     console tcp sun-ether gaia 2012      debug tcp sun-ether gaia 2013      master tcp sun-ether gaia 2011      query tcp sun-ether gaia 2011  REMAP="BO--Body"The name of the commit server (in these examples, "SERVICE") is used as a parameter in calls to the MOREINFO="NONE"open_commit and MOREINFO="NONE"build_xact_string routines. The commit server name must be the same on all machines participating in the transaction. The name cannot contain a period (".") or a colon (":"). RENDERAS="SECT1"Two-Phase Commit Example Program   REMAP="BO--Body"An example program illustrating the two-phase commit service is included with DB-Library's on-line example programs. This same example is duplicated below, but with comments added to document how recovery occurs for different types of failure that may occur at various points in the transaction. REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/*     **    twophase.c ** **    Demo of Two-Phase Commit Service ** **    This example uses the two-phase commit service **    to perform a simultaneous update on two servers. **    In this example, one of the servers participating  **    in the distributed transaction also functions as  **    the commit service. ** **    In this particular example, the same update is  **    performed on both servers. You can, however, use  **    the commit server to perform completely different  **    updates on each server. ** */  #include <stdio.h> #include <sybfront.h> #include <sybdb.h> #include "sybdbex.h"  int err_handler(); int msg_handler();  char     cmdbuf[256]; char     xact_string[128];  main() {       DBPROCESS     *dbproc_server1;       DBPROCESS     *dbproc_server2;      DBPROCESS     *dbproc_commit;      LOGINREC      *login;      int           commid;       RETCODE       ret_server1;      RETCODE       ret_server2;       /* Initialize DB-Library. */      if (dbinit() == FAIL)      exit(ERREXIT);       dberrhandle(err_handler);      dbmsghandle(msg_handler);       printf("Demo of Two Phase Commit\n");       /* Open connections with the servers and the      ** commit service. */      login = dblogin();      DBSETLPWD(login, "server_password");      DBSETLAPP(login, "twophase");       dbproc_server1 = dbopen (login, "SERVICE");      dbproc_server2 = dbopen (login, "PRACTICE");      dbproc_commit = open_commit (login, "SERVICE");       if (dbproc_server1 == NULL ||           dbproc_server2 == NULL ||           dbproc_commit  == NULL)      {           printf (" Connections failed!\n");           exit (ERREXIT);      }       /* Use the "pubs2" database. */      sprintf(cmdbuf, "use pubs2");      dbcmd(dbproc_server1, cmdbuf);      dbsqlexec(dbproc_server1);      dbcmd(dbproc_server2, cmdbuf);      dbsqlexec(dbproc_server2);       /*      ** Start the distributed transaction on the     ** commit service.      */      commid = start_xact(dbproc_commit, "demo", "test", 2); The application is now in the begin phase of the two-phase commit transaction.  REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /* Build the transaction name. */      build_xact_string ("test", "SERVICE", commid, xact_string);       /* Build the first command buffer. */      sprintf(cmdbuf, "begin transaction %s", xact_string);       /* Begin the transactions on the different servers. */      dbcmd(dbproc_server1, cmdbuf);      dbsqlexec(dbproc_server1);      dbcmd(dbproc_server2, cmdbuf);      dbsqlexec(dbproc_server2);       /* Do various updates. */      sprintf(cmdbuf, " update titles set price = $1.50 where");      strcat(cmdbuf, " title_id = 'BU1032'");      dbcmd(dbproc_server1, cmdbuf);      ret_server1 = dbsqlexec(dbproc_server1);      dbcmd(dbproc_server2, cmdbuf);      ret_server2 =dbsqlexec(dbproc_server2); See Program Note 1, following this example.REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     if (ret_server1 == FAIL || ret_server2 == FAIL)      {           /* Some part of the transaction failed. */           printf(" Transaction aborted -- dbsqlexec failed\n");           abortall(dbproc_server1, dbproc_server2,                   dbproc_commit, commid);      }       /* Find out if all servers can commit the transaction. */      sprintf(cmdbuf, "prepare transaction");      dbcmd(dbproc_server1, cmdbuf);      dbcmd(dbproc_server2, cmdbuf);      ret_server1 = dbsqlexec(dbproc_server1); See Program Note 2, following this example.REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     ret_server2 = dbsqlexec(dbproc_server2); See Program Note 3, following this example.REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     if (ret_server1 == FAIL || ret_server2 == FAIL)      {           /* One or both of the servers failed to prepare. */           printf(" Transaction aborted -- prepare failed\n");           abortall(dbproc_server1, dbproc_server2,                   dbproc_commit, commid);      } See Program Note 4, following this example.REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /* Commit the transaction. */      if (commit_xact(dbproc_commit, commid) == FAIL)      {           /* The commit server failed to record the commit. */           printf( " Transaction aborted -- commit_xact failed\n");           abortall(dbproc_server1, dbproc_server2,                   dbproc_commit, commid);           exit(ERREXIT);      } See Program Note 5, following this example.REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /* The transaction has successfully committed.       ** Inform the servers.      */      sprintf(cmdbuf, "commit transaction");      dbcmd(dbproc_server1, cmdbuf);      if (dbsqlexec(dbproc_server1) != FAIL)           remove_xact(dbproc_commit, commid, 1); See Program Note 6, following this example.REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     dbcmd(dbproc_server2, cmdbuf);      if (dbsqlexec(dbproc_server2) != FAIL)      remove_xact(dbproc_commit, commid, 1); See Program Note 7, following this example.REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /* Close the connection to the commit server. */      close_commit(dbproc_commit); See Program Note 8, following this example.REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     printf( "We made it!\n");      dbexit();      exit(STDEXIT); }  /* Function to abort the distributed transaction. */  abortall( dbproc_server1, dbproc_server2, dbproc_commit, commid ) DBPROCESS      *dbproc_server1;  DBPROCESS      *dbproc_server2; DBPROCESS      *dbproc_commit; int            commid; {      /* Some part of the transaction failed. */       /* Inform the commit server of the failure. */      abort_xact(dbproc_commit, commid);       /* Roll back the transactions on the different servers. */      sprintf(cmdbuf, "rollback transaction");      dbcmd(dbproc_server1, cmdbuf);      if (dbsqlexec(dbproc_server1) != FAIL)           remove_xact(dbproc_commit, commid, 1);      dbcmd(dbproc_server2, cmdbuf);      if (dbsqlexec(dbproc_server2) != FAIL)           remove_xact(dbproc_commit, commid, 1);       dbexit();      exit(ERREXIT); }  /* Message and error handling functions. */  int msg_handler(dbproc, msgno, msgstate, severity, msgtext,                  servername, procname, line)  DBPROCESS       *dbproc; DBINT           msgno; int             msgstate; int             severity; char            *msgtext; char            *servername; char            *procname; DBUSMALLINT     line;  {      /*   Msg 5701 is just a use database message, so skip it. */      if (msgno == 5701)           return (0);       /* Print any severity 0 message as is, without extra stuff. */     if (severity == 0)      {           (void) fprintf (ERR_CH, "%s\n",msgtext);           return (0);      }       (void) fprintf (ERR_CH, "Msg %ld, Level %d, State %d\n",               msgno, severity, msgstate);       if (strlen(servername) > 0)           (void) fprintf (ERR_CH, "Server '%s', ", servername);      if (strlen(procname) > 0)           (void) fprintf (ERR_CH, "Procedure '%s', ", procname);      if (line > 0)           (void) fprintf (ERR_CH, "Line %d", line);       (void) fprintf (ERR_CH, "\n\ %s\n", msgtext);       if (severity >= 16)      {           (void) fprintf (ERR_CH, "Program Terminated! Fatal\                          SQL Server error.\n");           exit(ERREXIT);      }       return (0);    }  int err_handler(dbproc, severity, dberr, oserr, dberrstr, oserrstr) DBPROCESS    *dbproc; int          severity; int          dberr; int          oserr; char         *dberrstr; char         *oserrstr; {      if ((dbproc == NULL) || (DBDEAD(dbproc)))           return (INT_EXIT);      else      {           (void) fprintf (ERR_CH, "DB-Library error: \                          \n\  %s\n", dberrstr);           if (oserr != DBNOERR)                (void) fprintf (ERR_CH, "Operating system error:\                                \n\ %s\n", oserrstr);      }       return (INT_CANCEL); } RENDERAS="SECT2"Program NotesNUMERATION="ARABIC" REMAP="S1--StepOne" CONTINUATION="RESTARTS" INHERITNUM="IGNORE"If any type of failure occurs at this point, it is the application's responsibility to roll back the transactions, using MOREINFO="NONE"abort_xact. The application has entered the prepare stage of the two-phase commit transaction.  As far as the commit server is aware, though, the application is still in the begin phase. If any type of failure occurs at this point, it is the application's responsibility to roll back the transactions, using MOREINFO="NONE"abort_xact. At this point, the following failures are possible:  MARK="BULL" REMAP="BU--Bullet"Either the application's link to the commit server, or the commit server itself, may go down. REMAP="UN--Under"In this case, the following call to MOREINFO="NONE"commit_xact will fail, and the application must roll back the transactions via MOREINFO="NONE"abort_xact. The application's link to a participating server may go down. REMAP="UN--Under"In this case, the following call to MOREINFO="NONE"commit_xact will succeed, but the application's  MOREINFO="NONE"commit MOREINFO="NONE"transaction command to the participating server will not. However, the server will be aware that its connection with the application has died.  It will communicate with the commit server, using MOREINFO="NONE"probe, to determine  whether to commit the transaction locally. A participating server may go down. REMAP="UN--Under"In this case, the following call to MOREINFO="NONE"commit_xact will succeed, but the application's MOREINFO="NONE"commit MOREINFO="NONE"transaction to the participating server will not.  When the participating server comes back up, it will use MOREINFO="NONE"probe to determine whether to commit the transaction locally. Both the application's link to the commit server and the application's link to the participating server may go down.  REMAP="UN--Under"In this case, the following call to MOREINFO="NONE"commit_xact will fail. The application must roll back the transactions viaMOREINFO="NONE" abort_xact, but will not be able to communicate with the participating server. The participating server will use MOREINFO="NONE"probe to communicate with the commit server.  It will learn that the transaction has not been committed in the commit service, and will roll back the transaction locally. Both the application's link to the participating server, and the participating server's link to the commit server may go down. REMAP="UN--Under"In this case, the following call to MOREINFO="NONE"commit_xact will succeed, but the application will not be able to communicate this to the participating server.  When its connection to the  application dies, the participating server will attempt to  communicate with the commit server via MOREINFO="NONE"probe to determine whether or not to commit the transaction locally. Because its link to the commit server is down, however, it will not be able to. REMAP="UN--Under"Because it cannot resolve the transaction,  the participating server marks the user task process as infected.   REMAP="UN--Under"If the system administrator kills the infected process while the commit server is still down, two-phase commit protocol is violated and the integrity of the transaction is not guaranteed.   REMAP="UN--Under"If the system administrator waits until commit server is back up to kill the infected process, MOREINFO="NONE"probe is automatically fired when the system administrator attempts to kill the process. MOREINFO="NONE"probe communicates with the commit server and determines whether the participating server should commit the transaction locally.  The integrity of the transaction is guaranteed. The application has entered the committed phase of the two-phase commit transaction.  This means that any MOREINFO="NONE"probe process querying the commit server will be told to commit the transaction locally.  After this point, the application does  not need to concern itself with aborting the transaction. If the above MOREINFO="NONE"dbsqlexec to server1 returns fail because the  application's link to the server has gone down, server1 will  use MOREINFO="NONE"probe to communicate with the commit server.   MOREINFO="NONE"probe will find that the transaction is committed  in the commit server, and will tell server1 to commit locally. REMAP="UN--Under"If MOREINFO="NONE"probe cannot communicate with the commit server, server1 will infect the user task process in SQL Server.   If the system administrator kills the infected process before communication with the commit server is re-established, the transaction will be rolled back, thus violating two-phase protocol and leaving the database in an inconsistent state.  If possible, the system administrator should always wait until  communication with the commit server is re-established before killing the infected process. MARK="BULLET"If the MOREINFO="NONE"dbsqlexec to server1 returns fail because server1  has gone down, the local transaction will remain in limbo until  server 1 is restored.  As part of the recovery process, server1 will use MOREINFO="NONE"probe to communicate with the commit server. MOREINFO="NONE"probe will find that the transaction is committed in the commit server, and will tell server1 to commit locally. REMAP="UN--Under"If MOREINFO="NONE"probe cannot communicate with the commit server, server1 will mark the database as suspect.  After communication with the commit sever is re-established,  the suspect database should be re-recovered. If the above MOREINFO="NONE"dbsqlexec to server2 returns fail because the  application's link to the server has gone down, server2 will  use MOREINFO="NONE"probe to communicate with the commit server.   MOREINFO="NONE"probe will find that the transaction is committed  in the commit server, and will tell server2 to commit locally. REMAP="UN--Under"If MOREINFO="NONE"probe cannot communicate with the commit server, server2 will infect the user task process in SQL Server.   If the system administrator kills the infected process before communication with the commit server is re-established, the transaction will be rolled back, thus violating two-phase protocol and leaving the database in an inconsistent state.  If possible, the system administrator should always wait until  communication with the commit server is re-established before killing the infected process. MARK="BULL" REMAP="BU--Bullet"If the MOREINFO="NONE"dbsqlexec to server2 returns fail because server2 has gone down, the local transaction will remain in limbo until  server 2 is restored.  As part of the recovery process, server2 will use MOREINFO="NONE"probe to communicate with the commit server. MOREINFO="NONE"probe will find that the transaction is committed in the commit server, and will tell server2 to commit locally. REMAP="UN--Under"If MOREINFO="NONE"probe cannot communicate with the commit server, server2 will mark the database as suspect.  After communication with the commit sever is re-established,  the suspect database should be re-recovered. MOREINFO="NONE"close_commit marks the transaction as complete in the MOREINFO="NONE"spt_committab table on the commit server.  If MOREINFO="NONE"close_commit fails, the transaction is not marked as  complete.  No actual harm is done by this, but the system administrator may choose to manually update MOREINFO="NONE"spt_committabID="IN424851610"Two-phase commit service
 in this case. ID="X19670"abort_xactID="IN43249753"Two-phase commit servicemarking transactions as aborted
Mark a distributed transaction as being aborted. FORMAT="LINESPECIFIC"RETCODE abort_xact(connect, commid)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *connect;FORMAT="LINESPECIFIC"DBINT         commid;ParametersREMAP="RI--RefIndent"connect - A pointer to the DBPROCESS used to communicate with the commit service. commid - The commid used to identify the transaction to the commit service. CommentsMARK="BULL" REMAP="BU--Bullet"This routine informs the commit service that the status of a  distributed transaction should be changed from "begin" to "abort." ReturnsREMAP="BO--Body"SUCCEED or FAIL. See AlsoREMAP="BO--Body"LINKEND="X38483"commit_xact
, LINKEND="X19834"remove_xact
, LINKEND="X54465"scan_xact
, LINKEND="X29964"start_xact
, LINKEND="X27839"stat_xact
ID="IN43109489"abort_xact
 ID="IN4317911110"build_xact_stringID="X16980"build_xact_stringID="IN4424911212"Two-phase commit servicebuilding names for recovery purposes
Build a name for a distributed transaction. FORMAT="LINESPECIFIC"void build_xact_string(xact_name, service_name,                      commid, result)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"char      *xact_name;FORMAT="LINESPECIFIC"char      *service_name;FORMAT="LINESPECIFIC"DBINT     commid;FORMAT="LINESPECIFIC"char      *result;ParametersREMAP="RI--RefIndent"xact_name ID="IN449911215"DebuggingDebuggingfor two-phase commit servicetwo-phase commit service
ID="IN4424911216"Two-phase commit servicedebugging
- The application or user name for the transaction. This name gets encoded in the name string but is not used by the commit service or SQL Server. It serves to identify the transaction for debugging purposes. service_name - The name that will be used by SQL Server to contact the commit service, should it be necessary to recover the transaction. If service_name is NULL, the name DSCOMMIT is used. REMAP="UN--Under"service_name must correspond to name of the interfaces file entry for the commit service. If service_name is NULL, the interfaces file must contain an entry for DSCOMMIT.commid - The number used by the commit service to identify the transaction. commid is the number returned by the call to MOREINFO="NONE"start_xact. result - Address of buffer where the string should be built. The space must be allocated by the caller. CommentsMARK="BULL" REMAP="BU--Bullet"This routine builds a name string for use  in the SQL MOREINFO="NONE"begin MOREINFO="NONE"transaction and MOREINFO="NONE"prepare MOREINFO="NONE"transaction  of a SQL Server transaction.  If SQL Server has to recover the transaction, it uses information encoded in the name to determine which commit service to contact  and which transaction in that service to inquire about. The application should issue a SQL MOREINFO="NONE"begin MOREINFO="NONE"transaction using the string built by MOREINFO="NONE"build_xact_string. The string built by MOREINFO="NONE"build_xact_string must be large enough to hold the ASCII representation of commid, the xact_name, the service_name, two additional characters, and a NULL terminator. ReturnsREMAP="BO--Body"None. See AlsoREMAP="BO--Body"LINKEND="X38483"commit_xact
, LINKEND="X29964"start_xact
ID="IN4417881520"build_xact_string
 ID="IN4412851821"close_commitclose_commitID="IN4524851923"Two-phase commit serviceclosing connections
End a connection with the commit service. FORMAT="LINESPECIFIC"void close_commit(connect)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *connect;ParametersREMAP="RI--RefIndent"connect - A pointer to the DBPROCESS structure that was originally returned  by MOREINFO="NONE"open_commit. CommentsMARK="BULL" REMAP="BU--Bullet"This routine calls MOREINFO="NONE"dbclose to end a connection  with the commit service.  A call to MOREINFO="NONE"close_commit should be made when the application is through with the commit service, in order to free resources.  ReturnsREMAP="BO--Body"None. See AlsoREMAP="BO--Body"LINKEND="X87778"dbclose
ID="IN4512822229"close_commit
 ID="IN4511792530"commit_xactID="X38483"commit_xactID="IN4624792632"Two-phase commit servicemarking transactions as committed
Mark a distributed transaction as being committed. FORMAT="LINESPECIFIC"RETCODE commit_xact(connect, commid)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *connect;FORMAT="LINESPECIFIC"DBINT         commid;ParametersREMAP="RI--RefIndent"connect - A pointer to the DBPROCESS used to communicate with the commit service. commid - The commid used to identify the transaction to the commit service. CommentsMARK="BULL" REMAP="BU--Bullet"This routine informs the commit service that the status of a distributed  transaction should be changed from "begin" to "commit." ReturnsREMAP="BO--Body"SUCCEED or FAIL. If MOREINFO="NONE"commit_xact fails, you must roll back the transaction. See AlsoREMAP="BO--Body"LINKEND="X19670"abort_xact
, LINKEND="X19834"remove_xact
, LINKEND="X54465"scan_xact
, LINKEND="X29964"start_xact
, LINKEND="X27839"stat_xact
ID="IN4611762938"commit_xact
 ID="IN4611733239"open_commitopen_commitID="IN4724733341"Two-phase commit serviceopening connections
Establish a connection with the commit service. FORMAT="LINESPECIFIC"DBPROCESS *open_commit(login, servername)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"LOGINREC     *login;FORMAT="LINESPECIFIC"char         *servername;ParametersREMAP="RI--RefIndent"login - This is a LOGINREC containing information about the user  initiating the session, such as login name, password, options desired. The LOGINREC must have been obtained from a prior call  to the DB-Library routine MOREINFO="NONE"dblogin. The caller may wish to initialize fields in the LOGINREC. See the manual page for MOREINFO="NONE"dblogin for more details. servername - The name of the commit service; for example, DSCOMMIT_SALESNET. If servername is NULL, the name DSCOMMIT is used.  The name cannot contain a period (".") or a colon (":"). CommentsMARK="BULL" REMAP="BU--Bullet"This routine calls MOREINFO="NONE"dbopen to establish a connection  with the commit service.  A call to MOREINFO="NONE"open_commit must precede any calls to other commit service routines, such as MOREINFO="NONE"start_xact, MOREINFO="NONE"commit_xact,  MOREINFO="NONE"abort_xact, MOREINFO="NONE"remove_xact, and MOREINFO="NONE"scan_xact. A session with the commit service is closed by calling MOREINFO="NONE"close_commit. This routine returns a DBPROCESS structure, which is used to communicate with the commit service. The DBPROCESS must be dedicated to its role with the commit service and should not be used otherwise in the distributed transaction. ReturnsREMAP="BO--Body"A pointer to a DBPROCESS structure to be used in subsequent commit service calls, or NULL if the open failed. See AlsoREMAP="BO--Body"LINKEND="X88162"dblogin
, LINKEND="X42139"dbopen
ID="IN4711703647"open_commit
 ID="X19834"remove_xactID="IN4811674048"remove_xact
ID="IN4824674050"Two-phase commit servicedecrementing site count
Decrement the count of sites still active in the distributed transaction.FORMAT="LINESPECIFIC"RETCODE remove_xact(connect, commid, n)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *connect;FORMAT="LINESPECIFIC"DBINT         commid;FORMAT="LINESPECIFIC"int           n;ParametersREMAP="RI--RefIndent"connect - A pointer to the DBPROCESS used to communicate with the commit service. commid - The commid used to identify the transaction to the commit service.n - The number of sites to remove from the transaction.CommentsMARK="BULL" REMAP="BU--Bullet"The commit service keeps a count of the number of sites participating in a distributed transaction. This routine informs the commit service that one or more sites has done a local commit or abort on the transaction and is hence no longer participating. The commit service removes the sites from the transaction by decrementing the count of sites. The transaction record is deleted entirely if the count drops to zero.ReturnsREMAP="BO--Body"SUCCEED or FAIL. See AlsoREMAP="BO--Body"LINKEND="X19670"abort_xact
, LINKEND="X38483"commit_xact
, LINKEND="X54465"scan_xact
, LINKEND="X29964"start_xact
, LINKEND="X27839"stat_xact
ID="IN4811644356"remove_xact
 ID="IN489614657"scan_xactID="X54465"scan_xactID="IN4924614759"Two-phase commit serviceprinting record of distributed transactions
ID="IN4924614760"Two-phase commit servicediagnostic routines
Print commit service record for distributed transactions. FORMAT="LINESPECIFIC"RETCODE scan_xact(connect, commid)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *connect;FORMAT="LINESPECIFIC"DBINT         commid;ParametersREMAP="RI--RefIndent"connect - A pointer to the DBPROCESS used to communicate with the commit service. commid - The commid used to identify the transaction to the commit service. If commid is -1, all commit service records are displayed. CommentsMARK="BULL" REMAP="BU--Bullet"This routine displays the commit service record for a specific distributed transaction, or for all distributed transactions known to the commit service. ReturnsREMAP="BO--Body"SUCCEED or FAIL. See AlsoREMAP="BO--Body"LINKEND="X19670"abort_xact
, LINKEND="X38483"commit_xact
, LINKEND="X19834"remove_xact
, LINKEND="X29964"start_xact
, LINKEND="X27839"stat_xact
ID="IN499585066"scan_xact
 ID="IN4910555367"start_xactID="X29964"start_xactID="IN5024555469"Two-phase commit servicestarting a distributed transaction
Start a distributed transaction using the commit service. FORMAT="LINESPECIFIC"DBINT start_xact(connect, application_name, xact_name,                 site_count)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *connect;FORMAT="LINESPECIFIC"char          *application_name;FORMAT="LINESPECIFIC"char          *xact_name;FORMAT="LINESPECIFIC"int           site_count;ParametersREMAP="RI--RefIndent"connect - A pointer to the DBPROCESS used to communicate with the commit service. application_name - The name of the application. This name can be anything the application chooses. It will appear in the table maintained by the commit service but is not used by the commit service or the SQL Server recovery system. xact_name - The name of the transaction.  This name will appear in the table maintained by the commit service and must be supplied as part of the transaction name string built by  MOREINFO="NONE"build_xact_string. The name cannot contain a period (".") or a colon (":"). site_count - The number of sites participating in the transaction. CommentsMARK="BULL" REMAP="BU--Bullet"This routine records the start of a distributed transaction with the commit service. A record is placed in the commit service containing the commid, which is a number that caller subsequently uses to identify the transaction to the commit service. ReturnsREMAP="BO--Body"An integer called the commid. This number is used to identify the transaction in subsequent calls to the commit service. In case of error, this routine will return 0. See AlsoREMAP="BO--Body"LINKEND="X19670"abort_xact
, LINKEND="X16980"build_xact_string
, LINKEND="X38483"commit_xact
, LINKEND="X19834"remove_xact
, LINKEND="X54465"scan_xact
, LINKEND="X27839"stat_xact
ID="IN5010525775"start_xact
 ID="IN509496076"stat_xactID="X27839"stat_xactID="IN5124496178"Two-phase commit servicediagnostic routines
ID="IN5124496179"Two-phase commit servicereturning status of a distributed transaction
Return the current status of a distributed transaction. FORMAT="LINESPECIFIC"int stat_xact(connect, commid)FORMAT="LINESPECIFIC" FORMAT="LINESPECIFIC"DBPROCESS     *connect;FORMAT="LINESPECIFIC"DBINT         commid;ParametersREMAP="RI--RefIndent"connect - A pointer to the DBPROCESS used to communicate with the commit service. commid - The commid used to identify the transaction to the commit service. If commid is -1, all commit service records are displayed. CommentsMARK="BULL" REMAP="BU--Bullet"This routine returns the transaction status for the specified  distributed transaction. ReturnsREMAP="BO--Body"A character code: `a' (abort), `b' (begin), `c' (commit), `u' (unknown), or -1 (request failed). See AlsoREMAP="BO--Body"LINKEND="X19670"abort_xact
, LINKEND="X38483"commit_xact
, LINKEND="X19834"remove_xact
, LINKEND="X54465"scan_xact
, LINKEND="X29964"start_xact
ID="IN519466485"stat_xact
 REMAP="BO--Body"NUMBER="A" ID="X76241"CursorsREMAP="BO--Body"This appendix introduces DB-Library's new cursor routines. The appendix:MARK="BULL" REMAP="BU--Bullet"Defines cursors.Describes what DB-Library's new cursor routines can do.Describes the differences between DB-Library cursors and Browse Mode, and between DB-Library and Client-Library cursors.Identifies differences in the sensitivity of cursors to change.Describes the options for controlling sensitivity and for limiting interference from changes made by other users.Lists the new cursor routines.Outlines how to control the duration of locks acquired during cursor operations. ID="X21209" RENDERAS="SECT1"What are Cursors?REMAP="BO--Body"Because relational databases are oriented toward sets, no concept of next row exists, meaning you can't operate on an individual row in a set. Cursor functionality solves this problem by letting a result set be processed one row at a time, similar to the way you read and update a file on a disk. A DB-Library cursor indicates the current position in a result set, just as the cursor on your screen indicates the current position in a block of text.REMAP="BO--Body"DB-Library cursors are client-side cursors. This means that they do not correspond to a SQL Server cursor, but emulate a cursor which appears to the user to be in the server. The DB-Library cursor transparently does keyset management, row positioning, and concurrency control entirely on the client side.RENDERAS="SECT2"What Are DB-Library Cursors Good For?REMAP="BO--Body"The DB-Library cursor routines offer the following capabilities, with certain limitations:MARK="BULL" REMAP="BU--Bullet"Forward and backward scrolling (depending on how the keyset is defined during MOREINFO="NONE"dbcursoropen)Direct access by position in the result setPositioned updates (even if the result set was defined with MOREINFO="NONE"order by)Sensitivity adjustments to changes made by other usersConcurrency control through several optionsRENDERAS="SECT2"Differences Between DB-Library Cursors and Browse ModeREMAP="BO--Body"Cursors let the user scroll through and update a result set with fewer restrictions than browse mode. Although cursors require a unique index, they do not require a timestamp nor a second connection to a database for updates. They also don't create a copy of the entire result set. The following table summarizes these differences:TOCENTRY="1"LBL="Table A-1: "Cursors and browse modeCOLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="126*"COLNAME="C2" COLWIDTH="117*"COLNAME="C3" COLWIDTH="117*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"What About?COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CursorsCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Browse ModeVALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"TimestampsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Not requiredCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"RequiredCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Multiple connections for 
updatesCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"UnnecessaryCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NecessaryCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"TablesCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Use original tablesCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Uses a copy of tablesRENDERAS="SECT2"Differences Between DB-Library and Client-Library CursorsREMAP="BO--Body"A DB-Library cursor does not correspond to an actual SQL Server cursor. Instead, at the time the cursor is declared with MOREINFO="NONE"dbcursoropen, DB-Library fetches keysets from SQL Server "under the covers." It then builds qualifiers based on the keys for the current row and sends them to SQL Server. The server parses the query and returns a result set. When MOREINFO="NONE"dbcursorfetch is called to retrieve more data, the DB-Library cursor may have to do additional selects. In addition, SQL Server may have to parse the query each time MOREINFO="NONE"dbcursorfetch is called.REMAP="BO--Body"A Client-Library cursor corresponds to an actual cursor in SQL Server. It is sometimes referred to, therefore, as a native cursor. A new TDS protocol allows Client-Library to interact with the server to manage the cursor. REMAP="BO--Body"A Client-Library cursor is faster than a DB-Library cursor because it doesn't have to send SQL to the server causing a re-parse of the query multiple times. But because the result set remains on the server side, it cannot offer the same options for concurrency control as a DB-Library cursor.REMAP="BO--Body"The following table summarizes these and additional differences between the two cursors:TOCENTRY="1"LBL="Table A-2: "Differences between DB-Library cursors and Client-Library cursorsCOLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="187*"COLNAME="C2" COLWIDTH="172*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DB-Library cursors:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Client-Library cursor:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Cursor row position is defined by the 
client.COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Cursor row position is defined by 
the server.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Can define optimistic concurrency 
control (allows dirty reads).COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Cannot define optimistic 
concurrency control (does not allow 
dirty reads).COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Can fetch backward (if cur_keyset or 
cur_dynamic is specified for scrollopt 
during MOREINFO="NONE"dbcursoropen).COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Can only fetch forward.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"More memory may be required if you 
query very large row sizes, unless you 
specify a smaller number of rows in the 
fetch buffer during MOREINFO="NONE"dbcursoropen.COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"More memory is not required no 
matter how large the row sizes are.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"You cannot access an Open Server 
application, unless the application 
installs the required DB-Library stored 
procedures.COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"You can access a System 10 Open 
Server application that is coded to 
support cursors.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Slower performance.COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Faster performance.RENDERAS="SECT1"Sensitivity to ChangeREMAP="BO--Body"Three broad categories identify cursors according to their sensitivity to change:RENDERAS="SECT2"RENDERAS="SECT3"StaticREMAP="BO--Body"Values, order, and membership in the result set do not change while the cursor is open.RENDERAS="SECT3"Keyset-DrivenREMAP="BO--Body"Values can change, but order and membership in the result set remain fixed at open time (the moment the cursor is opened).RENDERAS="SECT3"DynamicREMAP="BO--Body"Values, order, and membership in the result set can all change.RENDERAS="SECT2"Static CursorREMAP="BO--Body"In a static cursor, neither the cursor owner nor any other user can change the result set while the cursor is open. Values, membership, and order remain fixed until the cursor is closed. You can either take a snapshot of the result set (which begins to diverge from the snapshot as updates are made), or you can lock the entire result set to prevent updates.REMAP="BO--Body"It is not necessary for cursor routines to support static cursors directly. You can achieve static behavior through one of the following methods:MARK="BULL" REMAP="BU--Bullet"Take a snapshot copy of the result set (with MOREINFO="NONE"select...into) and then call MOREINFO="NONE"dbcursoropen against the snapshot (temporary table).Lock the result set by calling MOREINFO="NONE"dbcursoropen with the MOREINFO="NONE"holdlock keyword in a MOREINFO="NONE"select statement. This method, however, significantly reduces concurrency.RENDERAS="SECT2"Keyset-Driven CursorREMAP="BO--Body"In a keyset-driven cursor the order and the membership of rows in the result set are fixed at open time, but changes to values may be made by the cursor owner. Committed changes made by other users are visible. If a change affects a row's order, or results in a row no longer qualifying for membership, the row does not disappear or move unless the cursor is closed and reopened. If the cursor remains open, deleted rows, when accessed, return a special error code that says they are missing. Updating the key also causes the rows to be "missing."REMAP="BO--Body"Inserted data does not appear, but changes to existing data do appear when the buffer is refreshed. With or without MOREINFO="NONE"order by, the user can access rows by either relative or absolute position.REMAP="BO--Body"To access a row by relative position, move the cursor relative to its current position. For example, if the cursor is on row three and you want to access row eight, tell the cursor to jump five rows relative to its current position. The cursor jumps five rows to row eight.REMAP="BO--Body"To access a row by absolute position, tell the cursor the number of the row you want to access. For example, if the cursor is on row three and you want to access row eight, tell the cursor to jump to row eight.RENDERAS="SECT2"Dynamic CursorREMAP="BO--Body"In a dynamic cursor, uncommitted changes made by the cursor owner and committed changes made by anyone become visible the next time the user scrolls. Changes include inserts and deletes as well as changes in order and membership. (Deleted rows do not leave holes.) The user can access rows by relative (but not absolute) position in the result set. Dynamic cursors cannot use an MOREINFO="NONE"order by clause.ID="X37712" RENDERAS="SECT2"Concurrency ControlREMAP="BO--Body"Cursors control, through several options, concurrent access. Concurrent acces is when more than one user accesses and updates the same data at the same time. With concurrent access, data can become unreliable without some kind of control. To activate the particular concurrency control desired, specify one of the following options when you open a cursor:TOCENTRY="1"LBL="Table A-3: "Concurrency control optionsCOLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="99*"COLNAME="C2" COLWIDTH="261*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"OptionCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ResultVALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CUR_READONLYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Updates are not permitted.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CUR_LOCKCCCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The set of rows currently in the client buffer is locked 
when they are fetched inside a user-initiated transaction. 
No other user can update or read these rows. Updates 
issued by the cursor owner are guaranteed to succeed.

No locks are held unless the application first issues MOREINFO="NONE"begin 
transaction. Locks are held until the application issues a 
MOREINFO="NONE"commit transaction. Locks are not automatically released 
when the next fetch is executed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CUR_OPTCC and 
CUR_OPTCCVALCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Rows currently in the buffer are not locked, and other 
users can update or read them freely.REMAP="BO--Body"To detect collisions between updates issued by the cursor owner and those issued by other users, cursors save and compare timestamps or column values. Therefore, if you specify either of the optimistic concurrency control options (CUR_OPTCC or CUR_OPTCCVAL) your updates may fail because of collisions with other updates. You may want to design the application to refresh the buffer and then retry updates that fail.REMAP="BO--Body"The two optimistic concurrency control options differ in the way they detect collisions:TOCENTRY="1"LBL="Table A-4: "Detecting concurrency collisions COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="99*"COLNAME="C2" COLWIDTH="261*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"OptionCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Method of detectionVALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CUR_OPTCCCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Optimistic concurrency control based on timestamp 
values. Compares timestamps if available; otherwise, 
saves and compares the value of all non-text, non-image 
columns in the table with their previous values.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CUR_OPTCCVALCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Optimistic concurrency control based on values. 
Compares selected values whether or not a timestamp is 
available.RENDERAS="SECT1"New Cursor FunctionsREMAP="BO--Body"The following list summarizes the new routines that support cursors:MARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"dbcursoropen declares and opens the cursor, specifies the size of the fetch buffer and defines the keyset, and sets the concurrency control option.MOREINFO="NONE"dbcursorinfo returns the number of columns and the number of rows in the open cursor.MOREINFO="NONE"dbcursorcolinfo returns column information for the specified column number in the open cursor.MOREINFO="NONE"dbcursorbind associates program variables with columns.MOREINFO="NONE"dbcursorfetch scrolls the fetch buffer.MOREINFO="NONE"dbcursor updates, deletes, inserts, and refreshes the rows in the fetch buffer.MOREINFO="NONE"dbcursorclose closes the cursor.REMAP="BO--Body"For details about each function, see Section 2 of this manual.RENDERAS="SECT1"Holding LocksREMAP="BO--Body"To retain the flexibility of the SQL Server transaction model, cursors do not automatically issue MOREINFO="NONE"begin transaction or MOREINFO="NONE"commit transaction. The duration of locks acquired during cursor operations is entirely under the control of the application. In other words, an application that uses CUR_LOCKCC on either the MOREINFO="NONE"dbopencursor or MOREINFO="NONE"dbcursor routine must also issue MOREINFO="NONE"begin MOREINFO="NONE"transaction for the locking to have any effect.REMAP="BO--Body"To hold the lock on the currently buffered rows when CUR_LOCKCC is used onMOREINFO="NONE" dbcursoropen, the application must issue MOREINFO="NONE"commit MOREINFO="NONE"transaction and MOREINFO="NONE"begin MOREINFO="NONE"transaction before each MOREINFO="NONE"dbcursorfetch that scrolls the local buffer (except for the very first MOREINFO="NONE"dbcursorfetch, which should be preceded only by MOREINFO="NONE"begin MOREINFO="NONE"transaction).REMAP="BO--Body"To use the short-duration locking feature, issue MOREINFO="NONE"begin MOREINFO="NONE"transaction before locking the row to be updated with the CUR_LOCKCC option of MOREINFO="NONE"dbcursor. If each update is independent, issue MOREINFO="NONE"commit MOREINFO="NONE"transaction after each update. If multiple updates to the same screenful of data depend on each other, issue MOREINFO="NONE"commit MOREINFO="NONE"transaction when the screen is scrolled.REMAP="BO--Body"For repeatable-read consistency, specify MOREINFO="NONE"holdlock in the MOREINFO="NONE"select statement in MOREINFO="NONE"dbcursoropen, and issue MOREINFO="NONE"begin MOREINFO="NONE"transaction before the first MOREINFO="NONE"dbcursorfetch. Locks are obtained as the data is fetched and are retained until the application issues MOREINFO="NONE"commit MOREINFO="NONE"transaction or MOREINFO="NONE"rollback MOREINFO="NONE"transaction.REMAP="BO--Body"Although you can close and reopen a repeatable-read cursor, you can get the same effect with FETCH_FIRST.REMAP="BO--Body"Other combinations are possible as well. The important thing to remember is that locks are not held unless MOREINFO="NONE"begin MOREINFO="NONE"transaction is in effect. Locks acquired while MOREINFO="NONE"begin MOREINFO="NONE"transaction is in effect are held until a MOREINFO="NONE"commit MOREINFO="NONE"transaction or MOREINFO="NONE"rollback MOREINFO="NONE"transaction is issued.RENDERAS="SECT1"Cursors and Stored ProceduresREMAP="BO--Body"Cursors use the catalog stored procedures:MARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"sp_tables MOREINFO="NONE"sp_indexes MOREINFO="NONE"sp_special_columns REMAP="BO--Body"For more information about these stored procedures, see the SQL Server Reference Manual.REMAP="BO--Body"