#EDIR DATA#
DOCTYPE='BOOK' PUBLICID='-//SYBOOKS//Default DTD//EN' SYSTEMID=''DOCTYPE='book' PUBLICID='' SYSTEMID=''Open Client Client-Library/C Reference ManualOpen ClientClient-Library/C Reference Manual REMAP="titleBO--Body"Open Client Release 10.0REMAP="titleBO--Body"Document ID: 32840-00-1000-04REMAP="titleBO--Body"Change Level: 2REMAP="titleBO--Body"Last Revised: May 15, 1994Principal authorship: Pegler SwiftContributing authorship: Mike Allen, Otto LindDocument ID: 32840-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.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 94608PrefaceREMAP="BO--Body"This document, the Open Client Client-Library/C Reference Manual, contains reference information for the C version of Open Client Client-Libraryname='trade' font='symbol' code='228'  charset='fontspecific'.RENDERAS="SECT1"AudienceREMAP="BO--Body"The Client-Library Reference Manual is designed to serve as a reference manual for programmers who are writing Client-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 Client-Library application, use the Client-Library Reference Manual as a source of reference information.REMAP="BO--Body"LINKEND="X72623"Chapter 1,  "Introducing Client-Library,"
 contains a brief introduction to Client-Library. REMAP="BO--Body"LINKEND="X34826"Chapter 2,  "Topics,"
 contains information on how to accomplish specific programming tasks, such as using Client-Library routines to read a text or image value from the server. This chapter also contains information on Client-Library structures, options, error messages, and conventions.REMAP="BO--Body"LINKEND="X47797"Chapter 3,  "Routines,"
 contains specific information about each Client-Library routine, such as what parameters the routine takes and what it returns.REMAP="BO--Body"Although there is some introductory material about application development in this manual, it is highly recommended that applications programmers read the Client-Library Programmer's Guide before designing a Client-Library application.RENDERAS="SECT1"Related DocumentsREMAP="BO--Body"The Open Client/Server Installation Guide explains how to install Client-Library. REMAP="BO--Body"The Client-Library Programmer's Guide contains information on how to design and implement Client-Library programs.REMAP="BO--Body"The Open Client and Open Server Common Libraries Reference Manual contains reference information for:MARK="BULL" REMAP="BU--Bullet"CS-Libraryname='trade' font='symbol' code='228'  charset='fontspecific'Client-Library and Server-Libraryname='trade' font='symbol' code='228'  charset='fontspecific' bulk copy routinesREMAP="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 DB-Library Reference Manual describes DB-Libraryname='trade' font='symbol' code='228'  charset='fontspecific'. Like Client-Library, DB-Library is a collection of routines for use in writing client applications.The Open Server Server-Library Reference Manual contains reference information for Open Server 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"Client-Library routine syntax is shown in a bold, monospace font:REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_init(context, version)REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_CONTEXT     *context;CS_INT         version;REMAP="BO--Body"Program text and computer output are shown in a monospace font:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"ct_init(mycontext, CS_VERSION_100);REMAP="BO--Body"Structure names and symbolic constants are shown in small capital letters:REMAP="BO--Body"      CS_CONTEXT, CS_SYNC_IOREMAP="BO--Body"Routine names and Transact-SQL keywords are written in a narrow, bold font:REMAP="UN--Under"     MOREINFO="NONE"ct_init, the MOREINFO="NONE"select statementRENDERAS="SECT1"Code FragmentsREMAP="BO--Body"Code fragments in this book are taken from the on-line example programs that are included with Client-Library.REMAP="BO--Body"The example programs, and consequently the code fragments in this book, use MOREINFO="NONE"EX_*, MOREINFO="NONE"Ex_*, and MOREINFO="NONE"ex_* #defines, variables, and routines. REMAP="BO--Body"These #defines, variables, and routines are part of the example programs but not a part of Client-Library.RENDERAS="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 Client-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="X72623"Introducing Client-LibraryRENDERAS="SECT1"Client/Server ArchitectureID="IN1139921"Client/serverarchitectureREMAP="BO--Body"Client/server architecture divides the work of computing between "clients" and "servers."ID="IN179922"Clientswhat they doREMAP="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.ID="IN179923"Serverswhat they do
ID="IN1139924"Client/serverdiagram of interactionREMAP="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 architectureID="IN1139925"Client/serverarchitecture:advantagesREMAP="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="IN179926"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 WorkbenchStand-alone utilities provided with SQL Server, such as MOREINFO="NONE"isql and MOREINFO="NONE"bcpApplications written using Open Client librariesApplications written using SYBASE Embedded SQLname='trade' font='symbol' code='228'  charset='fontspecific'ID="IN179927"Serverstypes 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.
ID="IN1109928"SQL Serversimilarities to Open Server
ID="IN1119929"Open Serversimilarities to SQL ServerREMAP="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.ID="IN11099210"SQL Serverdifferences from Open Server
ID="IN11199211"Open Serverdifferences from SQL ServerREMAP="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 application can communicate with "foreign" applications and servers that are not based on SYBASE protocols, 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.ID="IN11099212"SQL Servercapabilities diagrammed;Open Server:capabilities diagrammedREMAP="BO--Body"The following diagram illustrates some of the different capabilities of SQL Server and Open Server applications:FLOAT="0"FORMAT="UNKNOWN" FILEREF="fig1_2.xwd"LBL="Figure 1-2: "SQL Server and Open Server applicationsID="IN11398313"Client/serverarchitectureREMAP="BO--Body"RENDERAS="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 ServerID="IN11898314"SYBASE Open Clientdescription of
ID="IN11198315"Open Clientdescription of productRENDERAS="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. ID="IN11198316"Open Clientprogramming interfaces
ID="IN11198317"Open Clientnetwork servicesREMAP="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.)ID="IN11198318"Net-LibraryREMAP="BO--Body"Open Client network services include Net-Libraryname='trade' font='symbol' code='228'  charset='fontspecific', which provides support for specific network protocols, such as TCP/IP or DECnet.ID="IN11898319"SYBASE Open Serverdescription of
ID="IN11198320"Open Serverdescription ofRENDERAS="SECT2"SYBASE Open ServerREMAP="BO--Body"SYBASE Open Server provides the tools and interfaces needed to create custom servers.REMAP="BO--Body"Like Open Client, Open Server has a programming interfaces component and a network services component.ID="IN11198321"Open Serverprogramming interfacesREMAP="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.)ID="IN11198322"Open Servernetwork servicesREMAP="BO--Body"Open Server network services are transparent.RENDERAS="SECT2"Application Calls to LibrariesID="IN11198323"Open Clientlibrary calls diagrammed
ID="IN11198324"Open Serverlibrary calls diagrammedREMAP="BO--Body"The following diagram illustrates the Open Client and Open Server library calls that different types of applications might make. For example, a client application might include calls to Client-Library and CS-Library, while an application that acts as both client and server (for example, a gateway application) might include calls to Client-Library, CS-Library, and Server-Library:FLOAT="0"FORMAT="UNKNOWN" FILEREF="fig1_3.xwd"LBL="Figure 1-3: "Application calls to librariesID="IN11198325"Open Clientlibraries included inRENDERAS="SECT2"The Open Client LibrariesREMAP="BO--Body"The libraries that make up Open Client programming interfaces are:ID="IN11098326"DB-Librarydefinition ofMARK="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="IN11498327"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="IN11098328"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.ID="IN11498329"Client-Librarydescription of contentsRENDERAS="SECT2"What Is in Client-Library?REMAP="BO--Body"Client-Library includes routines that send commands to a server and routines that process the results of those commands. Other routines set application properties, handle error conditions, and provide a variety of information about an application's interaction with a server.REMAP="BO--Body"Client-Library also contains a header file, ID="IN12294730"ctpublic.h header filectpublic.h
ctpublic.h, that defines structures, types, and values used by Client-Library routines.ID="IN11494731"Client-Librarygeneric interfaceRENDERAS="SECT3"Client-Library is a Generic InterfaceREMAP="BO--Body"Client-Library is a generic interface. Through Open Server and gateway applications, Client-Library applications can run against foreign applications and servers as well as SQL Server. REMAP="BO--Body"Because it is generic, Client-Library does not enforce or reflect any particular server's restrictions. For example, Client-Library allows text and image stored procedure parameters, but SQL Server does not.REMAP="BO--Body"When writing a Client-Library application, keep the application's ultimate target server in mind. If you are unsure about what is legal on a server and what is not, consult your server documentation. REMAP="BO--Body"An application can call MOREINFO="NONE"ct_capability to find out what capabilities a particular client/server connection supports.ID="IN11294732"Embedded SQLcomparing to Client-Library
ID="IN11494733"Client-Librarycomparing to Embedded SQLRENDERAS="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="SECT1"Using Client-LibraryREMAP="BO--Body"An application programmer writes a Client-Library program, using calls to Client-Library and CS-Library routines to set up structures, connect to servers, send commands, process results, and clean up. A Client-Library program is compiled and run in the same way as any other C language program.ID="IN11094734"Structurescontrol:discussion of
ID="IN118911035"Control structuresSee Structures, controlID="X43145" RENDERAS="SECT2"Basic Control StructuresREMAP="BO--Body"In order to send commands to a server, a Client-Library application must allocate three types of structures:ID="IN110911036"Structurescontext structure
ID="IN110891237"StructuresCS_CONTEXT structureMARK="BULL" REMAP="BU--Bullet"A ID="IN120871438"CS_CONTEXT structure
CS_CONTEXT structure, which defines a particular application "context", or operating environmentID="IN110871439"Structuresconnection structure
ID="IN110851640"StructuresCS_CONNECTION structureA ID="IN123831841"CS_CONNECTION structure
CS_CONNECTION structure, which defines a particular client/server connectionID="IN110831842"Structurescommand structure
ID="IN110812043"StructuresCS_COMMAND structureA ID="IN120792244"CS_COMMAND structure
CS_COMMAND structure, which defines a "command space" in which commands are sent to a serverID="IN110772445"AllocatingAllocatinga CS_CONTEXT structureCS_CONTEXTREMAP="BO--Body"An application allocates these structures by calling the CS-Library and Client-Library routines MOREINFO="NONE"cs_ctx_alloc, MOREINFO="NONE"ct_con_alloc, and MOREINFO="NONE"ct_cmd_alloc. ID="IN110772446"Structuresrelationship of control structures diagrammedREMAP="BO--Body"The general relationship between the three basic control structures is illustrated by the following diagram :     FLOAT="0"FORMAT="UNKNOWN" FILEREF="fig1_4.xwd"LBL="Figure 1-4: "Relationship of control structuresREMAP="BO--Body"Through these structures, an application sets up its environment, connects to servers, sends commands, and processes results.REMAP="BO--Body"For more information about these control structures, see LINKEND="X17322""Structures"
in Chapter 2, "Topics," or the Client-Library Programmer's Guide.ID="IN123772447"Steps in an application
ID="IN112772448"Applicationssteps in a simple programRENDERAS="SECT2"Steps in a Simple ProgramREMAP="BO--Body"On most platforms, a simple Client-Library program involves the following steps:Set up the Client-Library programming environment.Define error handling. Most applications will use callback routines to handle Client-Library and server error and informational messages. Some applications, however, will handle messages in-line. For a discussion of error and message handling, see LINKEND="X46924""Error and Message Handling"
in Chapter 2, "Topics."Connect to a server.Send a command to the server.Process the results of the command. Finish up.REMAP="BO--Body"The example program in the following section demonstrates these steps.ID="IN116772449"Example programsChapter1 exampleRENDERAS="SECT1"A Simple Example ProgramREMAP="BO--Body"The following example demonstrates the basic framework of a Client-Library application. The program follows the steps outlined in the previous section, sending a language command to a SQL Server and processing the results of the command. In this case, the language command is a Transact-SQL MOREINFO="NONE"select command.REMAP="BO--Body"For brevity's sake, this program does not include code for the message callback routines that handle Client-Library and server messages. However, message callback routines are included with the on-line example programs.REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/*** Language Query Example Program.*/ #include <stdio.h>#include <ctpublic.h> /*** Define a global context structure to use*/CS_CONTEXT *context; #define ERROR_EXIT   (-1)#define        MAXCOLUMNS   2#define        MAXSTRING    40 extern int print_data(); /* Client message and server message callback routines: */CS_RETCODE  clientmsg_callback();CS_RETCODE  servermsg_callback();void error(); /*** Main entry point for the program.*/main(argc, argv)int     argc; char    **argv;{    CS_CONNECTION    *connection;   /* Connection structure. */    CS_COMMAND       *cmd;          /* Command structure.    */     /* Data format structures for column descriptions: */    CS_DATAFMT                columns[MAXCOLUMNS];         CS_INT            datalength[MAXCOLUMNS];    CS_SMALLINT       indicator[MAXCOLUMNS];    CS_INT            count;    CS_RETCODE        ret, res_type;    CS_CHAR           name[MAXSTRING];    CS_CHAR           city[MAXSTRING];     /*    ** Get a context structure to use.    */    cs_ctx_alloc(CS_VERSION_100, &context)     /*    ** Initialize Open Client.    */    ct_init(context, CS_VERSION_100);        /*    ** Install message callback routines.    */    ct_callback(context, NULL, CS_SET, CS_CLIENTMSG_CB,            clientmsg_callback);     ct_callback(context, NULL, CS_SET, CS_SERVERMSG_CB,            servermsg_callback);     /*    ** Connect to the server:    **     Allocate a connection structure.    **     Set user name and password.    **     Create the connection.    */    ct_con_alloc(context, &connection);    ct_con_props(connection, CS_SET, CS_USERNAME, "username",            CS_NULLTERM, NULL);    ct_con_props(connection, CS_SET, CS_PASSWORD, "password",            CS_NULLTERM, NULL);     /*    ** This call actually creates the connection:    */    ct_connect(connection, "servername", CS_NULLTERM);     /*    ** Allocate a command structure.    */    ct_cmd_alloc(connection, &cmd);     /*    ** Initiate a language command.    */    ct_command(cmd, CS_LANG_CMD,            "use pubs2 \             select au_lname, city from pubs2..authors \                where state = 'CA'",            CS_NULLTERM, CS_UNUSED);      /*    ** Send the command.    */    ct_send(cmd);     /*    ** Process the results of the command.    */    while((ret = ct_results(cmd, &res_type))== CS_SUCCEED)    {        switch (res_type)        {        case CS_ROW_RESULT:            /*            ** We're expecting exactly two columns.            ** For each column, fill in the relevant            ** fields in a data format structure, and            ** bind the column.            */            columns[0].datatype = CS_CHAR_TYPE;            columns[0].format = CS_FMT_NULLTERM;            columns[0].maxlength = MAXSTRING;            columns[0].count = 1;            columns[0].locale = NULL;            ct_bind(cmd, 1, &columns[0], name, &datalength[0],                    &indicator[0]);             columns[1].datatype = CS_CHAR_TYPE;            columns[1].format = CS_FMT_NULLTERM;            columns[1].maxlength = MAXSTRING;            columns[1].count = 1;            columns[1].locale = NULL;            ct_bind(cmd, 2, &columns[1], city, &datalength[1],                    &indicator[1]);             /*            ** Now fetch and print the rows.            */            while(((ret = ct_fetch(cmd, CS_UNUSED, CS_UNUSED,                CS_UNUSED, &count))                == CS_SUCCEED) || (ret == CS_ROW_FAIL))            {                /*                ** Check if we hit a recoverable error.                */                if( ret == CS_ROW_FAIL )                {                    fprintf(stderr,                    "Error on row %d in this fetch batch.",                    count+1);                }                            /*                ** We have a row, let's print it.                */                fprintf(stdout, "%s: %s\n", name, city);            }             /*            ** We're finished processing rows, so check             ** ct_fetch's final return value.            */            if( ret == CS_END_DATA )            {                fprintf(stdout,                "All done processing rows.");            }            else /* Failure occurred. */            {                error("ct_fetch failed");            }             /*            ** All done with this result set.            */            break;         case CS_CMD_SUCCEED:            /*            ** Executed a command that never returns rows.            */            fprintf(stderr, "No rows returned.\n");            break;          case CS_CMD_FAIL:            /*            ** The server encountered an error while            ** processing our command.            */            break;         case CS_CMD_DONE;            /*            ** The logical command has been completely            ** processed.            */            break;         default:            /*            ** We got something unexpected.            */            error("ct_result returned unexpected result                type");            break;        }    }     /*    ** We've finished processing results. Let's check     ** the return value of ct_results() to see if    ** everything went ok.    */    switch(ret)    {        case CS_END_RESULTS:            /*            ** Everything went fine.            */            break;         case CS_FAIL:            /*            ** Something terrible happened.            */            error("ct_results() returned FAIL.");            break;         default:            /*            ** We got an unexpected return value.            */        error("ct_result returned unexpected return                code");                break;    }     ** All done.    */    ct_cmd_drop(cmd);    ct_close(connection, CS_UNUSED);     ct_con_drop(connection);    ct_exit(context, CS_UNUSED);    cs_ctx_drop(context);    return 0;} /*** Error occurred, cleanup and exit.*/void error(msg)char *msg;{    fprintf(stderr, "FATAL ERROR: %s\n", msg);    exit(ERROR_EXIT);}RENDERAS="SECT1"Notes on the Example ProgramREMAP="BO--Body"The header file MOREINFO="NONE"ctpublic.h is required in all source files that contain calls to Client-Library/C. It defines symbolic constants used by Client-Library routines and contains typedefs for Client-Library datatypes.ID="IN119772450"Program environmentsetting upRENDERAS="SECT2"Setting Up the Client-Library Programming EnvironmentREMAP="BO--Body"The CS-Library routineMOREINFO="NONE" cs_ctx_alloc allocates a context structure. A context structure is used to store configuration parameters that describe a particular "context," or operating environment, for a set of server connections. On most platforms, an application can have multiple contexts, although a typical application will need just one.REMAP="BO--Body"Application properties that can be defined at the context level include the name and location of the interfaces file, the login timeout value, and the maximum number of connections allowed within the context.REMAP="BO--Body"MOREINFO="NONE"ct_init initializes Client-Library. An application calls MOREINFO="NONE"ct_init after calling MOREINFO="NONE"cs_ctx_alloc and before calling any other Client-Library routine.RENDERAS="SECT2"Installing Message Callback RoutinesREMAP="BO--Body"MOREINFO="NONE"ct_callback installs a Client-Library callback routine. Callbacks are custom routines which are called automatically by Client-Library when a triggering event of the appropriate type occurs. For example, a client message callback is called automatically whenever OC-Library generates an error or informational message.REMAP="BO--Body"There are several types of callbacks, but the example program installs only two: a client message callback, to handle Client-Library error and informational messages, and a server message callback, to handle server error and informational messages. Code for the callbacks is not supplied with this example.ID="IN19772451"Callbacksnot supported by all languages/platformsCallback routines are not supported for all programming language/ platform combinations.If callbacks are not supported for a programming language/platform version of Client-Library, the Open Client/Server Supplement for that language and platform will indicate the lack of support.RENDERAS="SECT2"Connecting to a ServerREMAP="BO--Body"MOREINFO="NONE"ct_con_alloc allocates a connection structure. A connection structure contains information about a particular client/server connection.REMAP="BO--Body"MOREINFO="NONE"ct_con_props sets and retrieves the values of a connection's properties. Connection properties include user name and password, which are used in logging into a server; application name, which appears in SQL Server's sysprocess table, and packet size, which determines the size of network packets that an application will send and receive. For a complete list of connection properties, see the MOREINFO="NONE"Properties topics page.REMAP="BO--Body"The example program sets only the user name and password properties.REMAP="BO--Body"MOREINFO="NONE"ct_connect opens a connection to a server, logging into the server with the connection information specified via MOREINFO="NONE"ct_con_props.RENDERAS="SECT2"Sending a Command to the ServerREMAP="BO--Body"MOREINFO="NONE"ct_cmd_alloc allocates a command structure. A command structure is used to send commands to a server and to process the results of those commands.REMAP="BO--Body"MOREINFO="NONE"ct_command initiates the process of sending a non-cursor command. In this case, the example program initiates a language command.REMAP="BO--Body"MOREINFO="NONE"ct_send sends a command to the server.RENDERAS="SECT2"Processing the Results of the CommandREMAP="BO--Body"Almost all Client-Library programs will process results by using a loop controlled by MOREINFO="NONE"ct_results. Inside the loop, a switch takes place on the current type of result. Different types of results require different types of processing.REMAP="BO--Body"For row results, typically the number of columns in the result set is determined and then used to control a loop in which result items are bound to program variables. An application can call MOREINFO="NONE"ct_res_info to get the number of result columns, but in the example this is not necessary, because exactly two columns were selected. After the result items are bound, MOREINFO="NONE"ct_fetch is called to fetch data rows until end-of-data.REMAP="BO--Body"The results processing model used in the example looks like this:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"while ct_results returns CS_SUCCEED        switch on result_type            case row results                for each column:                    ct_bind                end for                while ct_fetch is returning rows                    process each row                end while                check ct_fetch's final return code            end case row results            case other result type....            case other result type....            ....        end switchend whilecheck ct_results' final return codeREMAP="BO--Body"MOREINFO="NONE"ct_results sets up results for processing. MOREINFO="NONE"ct_results' return parameter MOREINFO="NONE"result_type indicates the type of result data that is available for processing. Because the example program expects only a single result set of type CS_ROW_RESULT, most result types are not included as cases in the switch on MOREINFO="NONE"result_type.REMAP="BO--Body"Note that the example program calls MOREINFO="NONE"ct_results in a loop that continues as long as MOREINFO="NONE"ct_results returns CS_SUCCEED, indicating that result sets are available for processing. Although this type of program structure is not strictly necessary in the case of a simple language command, it is highly recommended. In more complex programs, it is not possible to predict the number and type of result sets than an application will receive in response to a command.REMAP="BO--Body"MOREINFO="NONE"ct_bind binds a result item to a program variable. Binding creates an association between a result item and a program data space.REMAP="BO--Body"MOREINFO="NONE"ct_fetch fetches result data. In the example, since binding has been specified and the count field in the CS_DATAFMT structure for each column is set to 1, each MOREINFO="NONE"ct_fetch call copies one row of data into program data space. As each row is fetched, the example program prints it.REMAP="BO--Body"After the MOREINFO="NONE"ct_fetch loop terminates, the example program checks its final return code to find out whether we dropped out because of end-of-data, or because of failure.RENDERAS="SECT2"Finishing UpREMAP="BO--Body"MOREINFO="NONE"ct_cmd_drop de-allocates a command structure.REMAP="BO--Body"MOREINFO="NONE"ct_close closes a server connection.REMAP="BO--Body"MOREINFO="NONE"ct_con_drop de-allocates a connection structure.REMAP="BO--Body"MOREINFO="NONE"ct_exit terminates Client-Library.REMAP="BO--Body"The CS-Library routineMOREINFO="NONE" cs_ctx_drop de-allocates a context structure.RENDERAS="SECT1"More Advanced ProgramsID="IN114772452"Client-Libraryadvanced featuresREMAP="BO--Body"Although some Client-Library applications will be as simple as the example program in this chapter, most will be more complex. Client-Library is a rich programming interface that supports a variety of advanced features.ID="IN18772453"Featureslist of advanced features
ID="IN117772454"Advanced featureslist of Client-Library featuresREMAP="BO--Body"Some of these features are:MARK="BULL" REMAP="BU--Bullet"Asynchronous network I/O support. When asynchronous network I/O is enabled, a Client-Library routine that reads from or writes to the network does not block, but instead returns immediately. Registered Procedures. For clients connected to a release 2.0 or greater Open Server, registered procedures provide a means of inter-application communication and synchronization. An application can create, wait for, and execute registered procedures. Cursor support. Client-Library contains routines to declare, open, and manipulate cursors as supported in 10.0 SQL Server and Open Server.International support. Client-Library allows an application to choose a language for Client-Library and SQL Server messages, process datetime, money, and numeric values in local formats, and specify character sets and collating sequences. A Client-Library application can specify localization information for a context, connection, or individual data element. Gateway support. A gateway is an application that acts as a "translator" for clients and server that cannot communicate directly. A gateway application passes requests from a client to a server, acting as both client and server itself. Client-Library provides routines specifically for use in building gateway applications.Remote procedure calls. A Client-Library application can send remote procedure calls to SQL Servers or Open Server applications. Text and image datatype support. Client-Library provides routines to transfer large text or image values to or from a server.REMAP="BO--Body"For more information on these and other advanced features, see LINKEND="X34826"Chapter 2,  "Topics"
.REMAP="BO--Body"NUMBER="2" ID="X34826"TopicsREMAP="BO--Body"This chapter contains information on:MARK="BULL" REMAP="BU--Bullet"Client-Library programming topics, such as asynchronous programming, browse mode, and text and image support.How to use routines to accomplish specific programming tasks, such as declaring and opening a cursor.Client-Library properties, datatypes, options, parameter conventions, and structures.RENDERAS="SECT1"List of TopicsREMAP="BO--Body"The following topics are included in this section:REMAP="UN--Under"MOREINFO="NONE"Asynchronous ProgrammingREMAP="UN--Under"MOREINFO="NONE"Browse ModeREMAP="UN--Under"MOREINFO="NONE"CallbacksREMAP="UN--Under"MOREINFO="NONE"CapabilitiesREMAP="UN--Under"MOREINFO="NONE"Client-Library MessagesREMAP="UN--Under"MOREINFO="NONE"CS_BROWSEDESC StructureREMAP="UN--Under"MOREINFO="NONE"CS_CLIENTMSG StructureREMAP="UN--Under"MOREINFO="NONE"CS_DATAFMT StructureREMAP="UN--Under"MOREINFO="NONE"CS_IODESC StructureREMAP="UN--Under"MOREINFO="NONE"CS_SERVERMSG StructureREMAP="UN--Under"MOREINFO="NONE"CursorsREMAP="UN--Under"MOREINFO="NONE"Dynamic SQLREMAP="UN--Under"MOREINFO="NONE"Error and Message HandlingREMAP="UN--Under"MOREINFO="NONE"Header FilesREMAP="UN--Under"MOREINFO="NONE"International SupportREMAP="UN--Under"MOREINFO="NONE"Message Commands and ResultsREMAP="UN--Under"MOREINFO="NONE"OptionsREMAP="UN--Under"MOREINFO="NONE"Parameter ConventionsREMAP="UN--Under"MOREINFO="NONE"PropertiesREMAP="UN--Under"MOREINFO="NONE"Registered ProceduresREMAP="UN--Under"MOREINFO="NONE"Remote Procedure CallsREMAP="UN--Under"MOREINFO="NONE"ResultsREMAP="UN--Under"MOREINFO="NONE"Security FeaturesREMAP="UN--Under"MOREINFO="NONE"SQLCA StructureREMAP="UN--Under"MOREINFO="NONE"SQLCODE StructureREMAP="UN--Under"MOREINFO="NONE"SQLSTATE StructureREMAP="UN--Under"MOREINFO="NONE"StructuresREMAP="UN--Under"MOREINFO="NONE"Text and ImageREMAP="UN--Under"MOREINFO="NONE"TypesREMAP="BO--Body"ID="X80066" RENDERAS="SECT1"Asynchronous ProgrammingREMAP="BO--Body"Asynchronous applications are designed to make constructive use of time that would otherwise be spent waiting for certain types of operations to complete. Typically, reading from and writing to a network or external device is much slower than straightforward program execution.ID="IN42219383"Asynchronous behaviorenabling using CS_NETIO propertyREMAP="BO--Body"When writing an asynchronous application, the application programmer must enable asynchronous Client-Library behavior at the context or connection level by setting the Client-Library property CS_NETIO to ID="IN422089124"CS_ASYNC_IO constantCS_ASYNC_IO
CS_ASYNC_IOID="IN422189125"Asynchronous behaviorAsynchronous behaviorof Client-Library routinesClient-Library routines
. When asynchronous behavior is enabled, all Client-Library routines that read from or write to the network either:MARK="BULL" REMAP="BU--Bullet"Initiate the requested operation and return ID="INA421787146"CS_PENDING return
CS_PENDING immediatelyReturn ID="IN421683187"CS_BUSY constantCS_BUSY
CS_BUSY to indicate that an asynchronous operation is already pending for this connectionREMAP="BO--Body"Non-asynchronous routines can also return CS_BUSY if called when an asynchronous operation is pending for a connection.ID="IN422483188"Asynchronous programminglearning of asynchronous routine completionRENDERAS="SECT2"Learning about CompletionsID="IN421083189"CompletionCompletionof asynchronous routineasynchronous routineREMAP="BO--Body"An application can learn of an asynchronous routine completion in one of two ways:ID="IN429831810"CallbacksCallbacksand asynchronous programmingasynchronous programming
ID="IN4219831811"Completion callback
ID="IN429831812"Callbackstriggered on asynchronous routine completionMARK="BULL" REMAP="BU--Bullet"On platforms that support interrupt-driven I/O, Client-Library automatically calls the application's completion callback routine when an asynchronous operation completes.ID="IN427812013"ct_pollusing to check for asynchronous completionsOn platforms that do not support interrupt-driven I/O, an application can use MOREINFO="NONE"ct_poll to find out if any asynchronous operations have completed. If it finds a completed operation, Client-Library will call an application's completion callback routine from within MOREINFO="NONE"ct_poll.RENDERAS="SECT2"Asynchronous RoutinesID="IN4224812014"Asynchronous programminglist of asynchronous routinesREMAP="BO--Body"The following Client-Library routines can behave asynchronously:MARK="BULL" REMAP="BU--Bullet"ID="IN429792215"ct_cancelasynchronous behavior
MOREINFO="NONE"ct_cancel ID="IN428772416"ct_closeasynchronous behavior
MOREINFO="NONE"ct_closeMOREINFO="NONE" ID="IN4210752617"ct_connectasynchronous behavior
MOREINFO="NONE"ct_connect ID="IN428732818"ct_fetchasynchronous behavior
MOREINFO="NONE"ct_fetch ID="IN4211713019"ct_get_dataasynchronous behavior
MOREINFO="NONE"ct_get_data ID="IN4210693220"ct_optionsasynchronous behavior
MOREINFO="NONE"ct_options ID="IN4215673421"ct_recvpassthruasynchronous behavior
MOREINFO="NONE"ct_recvpassthru ID="IN4210653622"ct_resultsasynchronous behavior
MOREINFO="NONE"ct_results ID="IN427633823"ct_sendasynchronous behavior
MOREINFO="NONE"ct_send ID="IN4212614024"ct_send_dataasynchronous behavior
MOREINFO="NONE"ct_send_data ID="IN4215594225"ct_sendpassthruasynchronous behavior
MOREINFO="NONE"ct_sendpassthru ID="IN4221574426"Asynchronous behaviorCS_BUSY returnREMAP="BO--Body"Any Client-Library routine that takes a command or connection structure as a parameter can return CS_BUSYID="IN4216554627"CS_BUSY constantmeaning of
. CS_BUSY indicates that a routine is unable to perform because the relevant connection is currently busy, waiting for an asynchronous operation to complete.ID="IN4224554628"Asynchronous programmingroutines callable when operation pendingREMAP="BO--Body"An application can call the following routines while an asynchronous operation is pending:MARK="BULL" REMAP="BU--Bullet"Any routine that takes a CS_CONTEXT structure as a parameter. If the CS_CONTEXT structure is an optional parameter, it must be non-NULL.ID="IN429534829"ct_cancelcallable when asynchronous operation pending
MOREINFO="NONE"ct_cancel(CS_CANCEL_ATTN)ID="IN4212515030"ct_cmd_propscallable when asynchronous operation pending
MOREINFO="NONE"ct_cmd_props(CS_USERDATA)ID="IN4212495231"ct_con_propscallable when asynchronous operation pending
MOREINFO="NONE"ct_con_props(CS_USERDATA)ID="IN427475432"ct_pollcallable when asynchronous operation pending
MOREINFO="NONE"ct_pollMOREINFO="NONE" RENDERAS="SECT2"ID="IN4224475433"Asynchronous programmingmemory requirements
Client-Library's Interrupt-Level Memory RequirementsID="IN4219475434"Memory requirementsfor asynchronous programming[Memory requirements:asynchronous programmingÕ REMAP="BO--Body"Ordinarily, Client-Library routines satisfy their memory requirements by calling MOREINFO="NONE"mallocID="IN426455635"mallocnot safe at interrupt level
. However, because not all implementations of MOREINFO="NONE"mallocID="IN4215455636"Interrupt levelmemory requirements
are re-entrant, it is not safe for Client-Library routines that are called at the interrupt level to use MOREINFO="NONE"malloc. For this reason, asynchronous applications are required to provide an alternate way for Client-Library to satisfy its memory requirements.REMAP="BO--Body"Client-Library provides two mechanisms by which an asynchronous application can satisfy Client-Library's memory requirements:ID="IN4224455637"Asynchronous programmingAsynchronous programmingand memory pool propertymemory pool propertyMARK="BULL" REMAP="BU--Bullet"The application can use the CS_MEM_POOL property to provide Client-Library with a memory pool.ID="IN4224455638"Asynchronous programmingAsynchronous programmingand user allocation function propertiesuser allocation function propertiesThe application can use the CS_USER_ALLOC and CS_USER_FREE ID="IN4217455639"Memory allocationinstalling custom memory allocation routines
properties to install memory allocation routines that Client-Library can safely call at the interrupt level.REMAP="BO--Body"If an asynchronous application fails to provide Client-Library with a safe way to satisfy memory requirements, Client-Library's behavior is undefined.ID="IN4219455640"Memory requirementshow Client-Library satisfiesREMAP="BO--Body"Client-Library attempts to satisfy memory requirements from the following sources in the following order:REMAP="UN--Under"1. Memory poolREMAP="UN--Under"2. User-supplied allocation and free routinesREMAP="UN--Under"3. System routinesID="IN4224455641"Asynchronous programminglayered applications;Layered applications:asynchronous programming;Applications:layeredID="X56944" RENDERAS="SECT2"Layered Applications REMAP="BO--Body"Asynchronous applications are often layered. In these types of applications, the lower layer serves to protect the higher layer from low-level asynchronous detail.RENDERAS="SECT3"What's In the Layers?REMAP="BO--Body"The higher-level layer typically consists of:MARK="BULL" REMAP="BU--Bullet"Main-line codeRoutines that asynchronously perform "larger" operations.REMAP="UN--Under"In this discussion, a "larger" operation is a task that requires several Client-Library calls to complete. For example, updating a database table is a larger operation because an application needs to call MOREINFO="NONE"ct_command, MOREINFO="NONE"ct_send, and MOREINFO="NONE"ct_results in order to perform the update.REMAP="BO--Body"The lower-level layer typically consists of:MARK="BULL" REMAP="BU--Bullet"The Client-Library routines required to perform a larger operationCode to handle low-level asynchronous operation completionsID="IN429435842"ct_wakeupct_wakeupand layered asynchronous applicationslayered asynchronous applicationsRENDERAS="SECT3"Using MOREINFO="NONE"ct_wakeupID="IN4224416043"CS_DISABLE_POLL propertyCS_DISABLE_POLL propertyand layered asynchronous applicationslayered asynchronous applications
and CS_DISABLE_POLLREMAP="BO--Body"ID="IN4224396244"Asynchronous programminglayered applications:and ct_wakeup
MOREINFO="NONE"ct_wakeup ID="IN4224396245"Asynchronous programminglayered applications:preventing reporting of asynchronous routine completions
and the CS_DISABLE_POLLID="IN4220376446"Layered applicationsasynchronous programming:and ct_wakeup
ID="IN4220376447"Layered applicationsasynchronous programming:preventing report of routine completions
property are useful in layered asynchronous applications:MARK="BULL" REMAP="BU--Bullet"A layered application can use CS_DISABLE_POLLID="IN427356648"ct_pollpreventing report of routine completions
to prevent MOREINFO="NONE"ct_poll from reporting asynchronous Client-Library routine completions.A layered application can use MOREINFO="NONE"ct_wakeup to let the higher layer know when a "larger" asynchronous operation is complete.REMAP="BO--Body"A layered application that is using a routine to perform a "larger" operation typically uses MOREINFO="NONE"ct_wakeup and CS_DISABLE_POLL in the following manner:NUMERATION="ARABIC" REMAP="S1--StepOne" CONTINUATION="RESTARTS" INHERITNUM="IGNORE"The application performs any necessary initialization, installs callback routines, opens connections, etc.The application calls the routine performing the larger operation.ID="IN427336849"ct_pollct_polland layered applicationslayered applicationsIf the application uses MOREINFO="NONE"ct_pollID="IN4224317050"Asynchronous programminglayered applications:and ct_poll
ID="IN4220297251"Layered applicationsasynchronous programming:and ct_poll
to check for asynchronous completions, then the routine must disable polling. This prevents MOREINFO="NONE"ct_poll from reporting lower-level asynchronous completions to the higher-level layer. To disable polling, the routine sets CS_DISABLE_POLL to CS_TRUE.REMAP="UN--Under"If the application does not call MOREINFO="NONE"ct_poll, the routine does not need to disable polling.ID="IN4211277452"ct_callbackct_callbackand layered applicationslayered applicationsThe routine calls MOREINFO="NONE"ct_callbackID="IN4220257653"Layered applicationsasynchronous programming:and ct_callback
ID="IN4224237854"Asynchronous programminglayered applications:and ct_callback
to replace the higher-level layer's completion callback with its own completion callback.The routine performs its work.The routine re-installs the higher-level layer's completion callback.If polling has been disabled, the routine enables it again by setting the CS_DISABLE_POLL property to CS_FALSE.The routine calls MOREINFO="NONE"ct_wakeup to trigger the higher-level layer's completion callback routine.ID="IN4224237855"Asynchronous programminglayered applications:example;Layered applications:asynchronous programming:exampleRENDERAS="SECT3"A Brief ExampleREMAP="BO--Body"An application that performs asynchronous database updates might include the routine MOREINFO="NONE"do_update, where MOREINFO="NONE"do_update calls all of the Client-Library routines necessary to perform a database update. REMAP="BO--Body"The main application can call MOREINFO="NONE"do_update asynchronously and go on with its other work.REMAP="BO--Body"When called,MOREINFO="NONE" do_update replaces the main application's completion callback with its own (so that the main application's callback is not triggered by low-level asynchronous completions), and proceeds with the work of the update. In order to perform the update, MOREINFO="NONE"do_update needs to call several Client-Library routines, including MOREINFO="NONE"ct_send and MOREINFO="NONE"ct_results, which behave asynchronously. When each asynchronous routine completes, it triggers MOREINFO="NONE"do_update's completion callback.REMAP="BO--Body"When MOREINFO="NONE"do_update has finished the update operation, it re-installs the main application's completion callback and calls MOREINFO="NONE"ct_wakeup with function as its own function id. This triggers the main application's completion callback, letting the main application know that MOREINFO="NONE"do_updateID="IN4211227956"Programmingasynchronous
has completed.ID="IN4224218057"Asynchronous programmingREMAP="BO--Body"ID="IN4214218058"Scrolling rowsbrowse mode method
ID="IN4211208159"Browse modeID="X24200" RENDERAS="SECT1"Browse ModeBrowse mode is included in 10.0 Client-Library in order to provide compatibility with Open Server applications and older Open Client libraries. Its use in new Open Client Client-Library applications is discouraged, because cursors provide the same functionality in a more portable and flexible manner. Further, browse mode is SYBASE-specific and is not suited for use in a heterogeneous environment.ID="IN4211208160"Browse modepurposeREMAP="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 an application 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="IN4216208161"Timestamp columnused for browse modeREMAP="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 an application typically selects a number of rows from a database at one time, but the application's users browse and update the database one row at a time. A timestamp column in browsable tables provides the information necessary to regulate this type of multi-user updating.ID="IN4211188362"Browse modead-hoc queries and ct_br_tableREMAP="BO--Body"Because some applications permit users to enter ad-hoc browse mode queries, Client-Library provides two routines, MOREINFO="NONE"ct_br_tableID="IN4211168563"Browse modead-hoc queries and ct_br_column
and MOREINFO="NONE"ct_br_column, that allow an application to retrieve information about the tables and columns underlying a browse-mode result set. This information is useful when an application is constructing commands to perform browse-mode updates.ID="IN4211168564"Browse modeconnection requirementsREMAP="BO--Body"A browse-mode application requires two connections, one for selecting the data and a second for performing the updates.REMAP="BO--Body"For more information on browse mode, see the SQL Server Reference Manual.ID="IN4211168565"Browse modesteps to implementRENDERAS="SECT2"Implementing Browse ModeREMAP="BO--Body"Conceptually, browse mode involves two steps:NUMERATION="ARABIC" REMAP="S1--StepOne" CONTINUATION="RESTARTS" INHERITNUM="IGNORE"Select 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, and use the new values to update the original database tables.REMAP="BO--Body"These steps are implemented in a program as follows:ID="IN4223148766"CS_HIDDEN_KEYS propertyCS_HIDDEN_KEYS propertyand browse modebrowse mode
ID="IN4211128967"Browse modeBrowse modeand CS_HIDDEN_KEYS propertyCS_HIDDEN_KEYS propertyNUMERATION="ARABIC" REMAP="S1--StepOne" CONTINUATION="RESTARTS" INHERITNUM="IGNORE"Set a connection's CS_HIDDEN_KEYS property to CS_TRUE. This ensures that Client-Library returns a table's timestamp column as part of a result set. In browse-mode updates, the timestampID="IN4218128968"Multi-user updatesregulating in browse mode
column is used to regulate multi-user updates.ID="IN4227109169"select...for browse command
ID="IN421189370"Browse modeselect...for browse commandExecute a MOREINFO="NONE"select...for browse language command. This command generates a regular row result set. This result set contains hidden key columns (one of which is the timestamp column) in addition to explicitly selected columns.After MOREINFO="NONE"ct_results indicates regular row results, call MOREINFO="NONE"ct_describe to get CS_DATAFMT descriptions of the result columnsMOREINFO="NONE":MARK="DASH" REMAP="BS--BulletSub"To indicate the timestamp column, MOREINFO="NONE"ct_describe sets the ID="IN421649771"CS_TIMESTAMP bitCS_TIMESTAMP
CS_TIMESTAMP and ID="IN4213010172"CS_HIDDEN bitCS_HIDDEN
CS_HIDDEN bits in the *datafmtname='rArrow' font='symbol' code='174'  charset='fontspecific'status field.To indicate an ordinary hidden key column, MOREINFO="NONE"ct_describe sets the CS_HIDDEN bit in the *datafmtname='rArrow' font='symbol' code='174'  charset='fontspecific'status field. If the CS_HIDDEN bit is not set, the column is an explicitly-selected column.Call MOREINFO="NONE"ct_bind to bind the result columns of interest. An application must bind all hidden columns because it will need the values of these columns to build a qualifier at update time. ID="IN4211-210373"ct_br_tablewhen to callCall MOREINFO="NONE"ct_br_tableID="IN4212-410574"ct_br_columnwhen to call
, if necessary, to retrieve information about the database tables that underlie the result set. Call MOREINFO="NONE"ct_br_column, if necessary, to retrieve information about a specific result set column. Both of these types of information can be useful when building a language command to update the database.Call MOREINFO="NONE"ct_fetch in a loop to fetch rows. When a row is fetched that contains values that need to be changed, update the database table(s) with the new values. To do this:MARK="DASH" REMAP="BS--BulletSub"Construct a language command containing a Transact-SQL MOREINFO="NONE"update statement with a where-clause qualifier that uses the row's hidden columns (including the timestamp column).Send the language command to the server and process the results of the command. A language command containing a browse-mode MOREINFO="NONE"update statement generates a result set of type ID="IN4227-810975"CS_PARAM_RESULT result typeCS_PARAM_RESULT
CS_PARAM_RESULT. This result set contains a single result item, the new timestamp for the row. If the application plans to update this same row again, it must save the new timestamp for later use.REMAP="UN--Under"After one browse-mode row has been updated, the application can fetch and process the next row.ID="IN4211-810976"Browse modeconditions for usingRENDERAS="SECT2"Browse-mode ConditionsREMAP="BO--Body"To use browse mode, the following conditions must be true:MARK="BULL" REMAP="BU--Bullet"The MOREINFO="NONE"select command that generated the result set must end with the key words MOREINFO="NONE"for browse.The table(s) to be updated must be "browsable" (i.e., each must have a unique index and a timestamp column).The result columns to be updated cannot be the result of SQL expressions, such asMOREINFO="NONE" max(colname)ID="IN4211-911077"Browse mode
.ID="IN429-1011178"CallbacksID="X40634" RENDERAS="SECT1"CallbacksRENDERAS="SECT2"What Are Callbacks?REMAP="BO--Body"Callbacks are user-supplied routines that are automatically called by Client-Library whenever certain triggering events, knownID="IN426-1311479"Eventscallback:See Callback events
as ID="IN4215-1311480"Callback events
callback events, occur.REMAP="BO--Body"Some callback events are the result of a server response arriving for an application. For example, a notification callback event occurs when a registered procedure notification arrives from an Open Server. REMAP="BO--Body"Other callback events occur at the internal Client-Library level. For example, a client message callback event occurs when Client-Library generates an error message. ID="IN429-1311481"Callbacksdescription of when calledRENDERAS="SECT2"When Are Callbacks Called?REMAP="BO--Body"When Client-Library recognizes a callback event, it automatically calls the appropriate callback routine.ID="IN4215-1311482"Callback eventsrecognizingREMAP="BO--Body"In order for Client-Library to recognize some callback events, it must be actively engaged in reading from the network. Most callback events of this type occur when Client-Library is naturally reading from the network, and are handled automatically.ID="IN4215-1311483"Callback eventswhen not reading from networkREMAP="BO--Body"Two types of callback events, however, can occur when Client-Library is not reading from the network. These are: ID="IN4225-1311484"Completion callback eventwhen it occursMARK="BULL" REMAP="BU--Bullet"The completion callback event, which occurs when an asynchronous Client-Library routine completes.ID="IN4227-1311485"Notification callback eventwhen it occursThe notification callback event, which occurs when an Open Server notification arrives for an application.ID="IN429-1311486"Callbackswhen called at interrupt level
ID="IN4215-1311487"Interrupt levelwhen callbacks are called atREMAP="BO--Body"If a platform supports interrupt-driven I/O, completion and notification callbacks are called at the interrupt level when a completion or notification callback event occurs. If a platform does not support interrupt-driven I/O, however, an application will need to call MOREINFO="NONE"ct_poll to check for these events if it is not otherwise reading from the network.ID="IN429-1511688"CallbacksCallbacksand ct_pollct_pollREMAP="BO--Body"If MOREINFO="NONE"ct_poll finds an asynchronous routine completion or an Open Server notification, it automatically calls the appropriate callback routine before returning.Because some types of callback routines can be executed at interrupt time, a callback routine must take care in accessing data structures that are also used by the application's main-line code.ID="IN429-1511689"Callbackstypes ofRENDERAS="SECT2"Types of CallbacksID="IN429-1511690"Callbackswhen calledREMAP="BO--Body"The following table lists the types of callbacks, when they are called, and whether an application needs to use MOREINFO="NONE"ct_pollID="IN429-1511691"Callbackshow triggered
ID="IN4220-1511692"Triggering callbacks
to trigger them:TOCENTRY="1"LBL="Table 2-1: "Types of callbacksCOLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="87*"COLNAME="C2" COLWIDTH="149*"COLNAME="C3" COLWIDTH="236*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Type of Callback:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"When Is it Called?COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"How Is it Called?VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Client MessageCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"In response to a Client-Library 
error or informational 
message.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"When Client-Library generates an error or 
informational message, Client-Library 
automatically triggers the client message callback.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CompletionCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"When an asynchronous Client-
Library routine completes.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An asynchronous routine completion can occur at 
any time. 

On platforms that support interrupt-driven I/O, 
the completion callback is called automatically, at 
the interrupt level, when the completion occurs.

On platforms that do not support interrupt-driven 
I/O, an application can use MOREINFO="NONE"ct_poll to find out if any 
routines have completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"EncryptionCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"During the connection process, 
in response to a server request 
for an encrypted password.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"If a connection's CS_SEC_ENCRYPTION property 
is set to CS_TRUE, then Client-Library 
automatically triggers the encryption callback 
when a server requests an encrypted password 
during a connection attempt.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NegotiationCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"During the connection process:
- In response to a server request for login security labels.
- In response to a server 
challenge.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"If a connection's CS_SEC_NEGOTIATE property is 
CS_TRUE, then Client-Library automatically 
triggers the negotiation callback when a server 
requests login security labels during a connection 
attempt.

If a connection's CS_SEC_CHALLENGE property 
is CS_TRUE, then Client-Library automatically 
triggers the negotiation callback when a server 
issues a challenge during a connection attempt.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NotificationCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"When an Open Server 
notification arrives.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An Open Server notification can arrive at any time.

On platforms that support interrupt-driven I/O, 
the notification callback is called at the interrupt 
level when the completion occurs.

On platforms that do not support interrupt-driven 
I/O, an application must be actively reading from 
the network in order for Client-Library to 
recognize a notification. If an application is not 
actively reading from the network, it can use 
MOREINFO="NONE"ct_poll to find out if a notification has arrived.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Server MessageCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"In response to a server error or 
informational message.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Server messages occur as the result of specific 
commands. When an application processes the 
results of a command, Client-Library reads any 
error or informational messages related to the 
command, automatically triggering the server 
message callback.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SignalCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"In response to an operating-
system signal.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"When a signal arrives, Client-Library's own signal 
handler automatically calls the signal callback that 
an application has installed.ID="IN429-1511693"Callbacksnot universally implementedRENDERAS="SECT2"Callbacks Are Not Universally ImplementedREMAP="BO--Body"Callbacks may not be implemented for programming language/ platform combinations that do not support function calls by pointer reference. If this is the case, an application:MARK="BULL" REMAP="BU--Bullet"Must handle Client-Library and server messages in-line, using MOREINFO="NONE"ct_diag. Can still use MOREINFO="NONE"ct_poll to check for a completion or notification callback event, but will have to call any routine handling the event directly. REMAP="BO--Body"If callbacks are not supported for a programming language/platform version of Client-Library, the Open Client/Server Supplement for that language and platform will indicate the lack of support.ID="IN429-1511694"CallbacksinstallingRENDERAS="SECT2"Installing a Callback RoutineREMAP="BO--Body"An application installs a callback routine by calling MOREINFO="NONE"ct_callback, passing a pointer to the callback routine and indicating its type via the type parameter.ID="IN4211-1511695"Connectionsinheriting parent contextÕ s callbacksREMAP="BO--Body"A callback of a particular type can be installed at the context or connection level. When a connection is allocated, it picks up default callbacks from its parent context. An application can override these default callbacks by calling MOREINFO="NONE"ct_callback to install new callbacks at the connection level.RENDERAS="SECT2"When a Callback Event OccursREMAP="BO--Body"For most types of callbacks, when a callback event occurs:MARK="BULL" REMAP="BU--Bullet"If a callback of the proper type exists at the proper level, it is called.ID="IN4215-1511696"Callback eventsinformation can be discardedIf a callback of the proper type does not exist at the proper level then the callback event information is discarded.ID="IN4223-1511697"Client message callbackexceptional behaviorREMAP="BO--Body"The client message callback is an exception to this rule. When an error or informational message is generated for a connection that has no client message callback installed, Client-Library calls the connection's parent context's client message callback (if any) rather than discarding the message. If the context has no client message callback installed, then the message is discarded.RENDERAS="SECT2"Retrieving and Replacing Callback RoutinesID="IN429-1511698"Callbacksretrieving a pointer toREMAP="BO--Body"To retrieve a pointer to a currently-installed callback, call MOREINFO="NONE"ct_callback with the parameter action as CS_GET. MOREINFO="NONE"ct_callback sets *func to the address of the current callback. An application can save this address for re-use at a later time.ID="IN429-1511699"Callbacksde-installing;De-installing:callback routinesREMAP="BO--Body"To de-install a callback, call MOREINFO="NONE"ct_callback with the parameter action as CS_SET and func as NULL.ID="IN429-15116100"Callbacksreplacing callback routinesREMAP="BO--Body"To replace an existing callback routine with a new one, call MOREINFO="NONE"ct_callback to install the new routine. MOREINFO="NONE"ct_callback will replace the existing callback with the new callback.ID="IN429-15116101"Callbacksdefining callback routinesRENDERAS="SECT2"Defining Callback RoutinesID="IN429-15116102"CallbacksClient-Library routines they can callREMAP="BO--Body"All callback routines are limited as to which Client-Library routines they can call. The following table lists types of callback routines and the Client-Library routines that they can call:TOCENTRY="1"LBL="Table 2-2: "Callbacks can call these Client-Library routinesCOLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="90*"COLNAME="C2" COLWIDTH="167*"COLNAME="C3" COLWIDTH="208*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Type of Callback COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Can CallCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Under What Circumstances?VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"All Callback 
RoutinesCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_configMOREINFO="NONE" COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To retrieve information only.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_con_propsMOREINFO="NONE" COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To retrieve information or to set the 
CS_USERDATA property only.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cmd_propsMOREINFO="NONE" COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To retrieve information or to set the 
CS_USERDATA property only.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_ATTN)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Server MessageCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_bind, ct_describe, ct_fetch, 
ct_get_data, ct_res_infoCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routines must be called with the 
command structure returned by the 
callbacks's MOREINFO="NONE"ct_con_props(CS_EED_CMD) 
call.

For more information, see "Extended Error 
Data".COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NotificationCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_bind, ct_describe, ct_fetch, 
ct_get_data, 
ct_res_info(CS_NUMDATA)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routines must be called with the 
command structure returned by the 
callbacks's MOREINFO="NONE"ct_con_props(CS_NOTIF_CMD) 
call.

For more information, see "Registered 
Procedures".COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Completion COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Any Client-Library or CS-Library 
routine except MOREINFO="NONE"cs_objects 
(CS_SET), MOREINFO="NONE"ct_init, ct_exit, 
ct_setloginfo, and MOREINFO="NONE"ct_getloginfo. 

MOREINFO="NONE"cs_objects(CS_SET) is not 
asynchronous-safe, and MOREINFO="NONE"ct_init, 
MOREINFO="NONE"ct_exit, ct_setloginfo, and 
MOREINFO="NONE"ct_getloginfo perform system-level 
memory allocation or free.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"REMAP="BO--Body"The following sections contain information on how to define each type of callback routine:ID="IN4226-15116103"Error and message handlinghandling Client-Library errors with a client message callback
ID="IN429-15116104"Callbacksclient message callback
ID="IN4223-15116105"Client message callback
ID="IN429-15116106"Callbacksclient message callbackRENDERAS="SECT2"Client Message CallbacksREMAP="BO--Body"An application can handle Client-Library error and informational messages in-line, or through a client message callback routine.REMAP="BO--Body"When a connection is allocated, it picks up a default client message callback from its parent context. If the parent context has no client message callback installed, then the connection is created without a default client message callback.REMAP="BO--Body"After allocating a connection, an application can:MARK="BULL" REMAP="BU--Bullet"Install a different client message callback for the connection.ID="IN427-17118107"ct_diagde-installs message callbacksCall MOREINFO="NONE"ct_diag to initialize in-line message handling for the connection. Note that MOREINFO="NONE"ct_diag automatically de-installs all message callbacks for the connection.REMAP="BO--Body"If a client message callback is not installed for a connection or its parent context and in-line message handling is not enabled, Client-Library discards message information.REMAP="BO--Body"If callbacks are not implemented for a particular programming language/platform version of Client-Library, an application must handle Client-Library messages in-line, using MOREINFO="NONE"ct_diag.REMAP="BO--Body"If a connection is handling Client-Library messages through a client message callback, then the callback is called whenever Client-Library generates an error or informational messageThe exception to this rule is that Client-Library does not call the client message callback when a message is generated from within most types of callback routines. Client-Library does call the client message callback when a message is generated within a completion callback.  That is, if a Client-Library routine fails within a callback routine other than the completion callback, the routine returns ID="IN4216-21122108"CS_FAIL constantCS_FAIL
CS_FAIL but does not trigger the client message callback.ID="IN4223-21122109"Client message callbackdefiningRENDERAS="SECT3"Defining a Client Message CallbackREMAP="BO--Body"A client message callback is defined as follows:REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE clientmsg_cb(context, connection, message)REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_CONTEXT      *context;CS_CONNECTION   *connection;CS_CLIENTMSG    *message;REMAP="BO--Body"where:REMAP="RI--RefIndent"context is a pointer to the CS_CONTEXT structure for which the message occurred.connection is a pointer to the CS_CONNECTION structure for which the message occurred, if any. connection can be NULL.message is a pointer to a CS_CLIENTMSG structure containing Client-Library message information. For information on the CS_CLIENTMSG structure, see the MOREINFO="NONE"CS_CLIENTMSG topics page.REMAP="UN--Under"Note that message can have a new value each time the client message callback is called.ID="IN4223-21122110"Client message callbackvalid return valuesA client message callback must return either:MARK="BULL" REMAP="BU--Bullet"CS_SUCCEED, to instruct Client-Library to continue any processing that is currently occurring on this connection.REMAP="UN--Under"If a timeout error occurs, CS_SUCCEED causes Client-Library to wait for the duration of a full timeout period before calling the client message callback again. It continues this behavior until either the command succeeds without timing out or until the server cancels the current command in response to a MOREINFO="NONE"ct_cancel(CS_CANCEL_ATTN) call from the client message callback.It is possible, in some cases, that a server will be unable to respond to a client's cancel command. Such a situation could occur, for example, if the server is processing a very complex query and is not in an interruptable state.CS_FAIL, to instruct Client-Library to terminate any processing that is currently occurring on this connection. A return of CS_FAIL results in the connection being marked as dead. In order to continue using the connection, the application must close the connection and reopen it.ID="IN4223-21122111"Client message callbackClient-Library routines it can callREMAP="BO--Body"The following table lists the Client-Library routines that a client message callback can call:TOCENTRY="1"LBL="Table 2-3: "Routines that a Client Message callback can call COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="171*"COLNAME="C2" COLWIDTH="189*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A Client Message Callback Can Call:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Under What Circumstances?VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_configMOREINFO="NONE" COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To retrieve information only.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_con_propsMOREINFO="NONE" COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To retrieve information or to set the 
CS_USERDATA property only.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cmd_propsMOREINFO="NONE" COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To retrieve information or to set the 
CS_USERDATA property only.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_ATTN)COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Any.ID="IN4223-21122112"Client message callbackexampleID="X45622" RENDERAS="SECT3"Client Message Callback ExampleREMAP="BO--Body"This is an example of a client message callback:REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/*** ex_clientmsg_cb()**** Type of function:**      Example program client message handler**** Purpose:**      Installed as a callback into Open Client.**** Returns:**      CS_SUCCEED**** Side Effects:**      None*/REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"CS_RETCODE CS_PUBLICex_clientmsg_cb(context, connection, errmsg)CS_CONTEXT        *contextCS_CONNECTION     *connection;CS_CLIENTMSG      *errmsg;{    fprintf(EX_ERROR_OUT, "\nOpen Client Message:\n");    fprintf(EX_ERROR_OUT, "Message number:           LAYER = (%ld) ORIGIN = (%ld) ",          CS_LAYER(errmsg->msgnumber),          CS_ORIGIN(errmsg->msgnumber));   fprintf(EX_ERROR_OUT, "SEVERITY = (%ld)           NUMBER = (%ld)\n",          CS_SEVERITY(errmsg->msgnumber),           CS_NUMBER(errmsg->msgnumber));     fprintf(EX_ERROR_OUT, "Message String: %s\n",          errmsg->msgstring);    if (errmsg->osstringlen > 0)    {        fprintf(EX_ERROR_OUT, "Operating System \              Error: %s\n", errmsg->osstring);    }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    return CS_SUCCEED;}ID="IN4219-21122113"Completion callback
ID="IN429-21122114"Callbackscompletion callback
ID="IN4224-21122115"Asynchronous programmingdefining a completion callbackRENDERAS="SECT2"Completion CallbacksREMAP="BO--Body"A completion callback is called whenever an application receives notice that an asynchronous routine has completed.REMAP="BO--Body"A context or a connection can be defined to be asynchronous. If a context is asynchronous, then all connections within that context are asynchronous, unless defined otherwise.REMAP="BO--Body"When a connection is asynchronous, Client-Library routines that perform network I/O do not block, but instead return ID="IN4217-23124116"CS_PENDING return
CS_PENDING immediately. When a routine completes, Client-Library automatically calls the completion callback.ID="IN4219-23124117"Completion callbackpurposeREMAP="BO--Body"A completion callback is typically coded to notify the main-line code of the asynchronous routine's completion.ID="IN4219-23124118"Completion callbackdefiningRENDERAS="SECT3"Defining a Completion CallbackREMAP="BO--Body"A completion callback is defined as follows:REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE completion_cb(connection, cmd, function,                status)REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_CONNECTION   *connection;CS_COMMAND      *cmd;CS_INT          function;CS_RETCODE      status;REMAP="BO--Body"where:REMAP="RI--RefIndent"connection is a pointer to the CS_CONNECTION structure representing the connection that performed the I/O for the routine.cmd is a pointer to the CS_COMMAND structure for the routine, if any. cmd can be NULL.function indicates which routine has completed. The following table lists the symbolic values possible for function:TOCENTRY="1"LBL="Table 2-4: "Values for function (Completion Callback)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 MOREINFO="NONE"function:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Indicating:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"BLK_ROWXFERCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"blk_rowxfer has completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"BLK_SENDROWCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"blk_sendrow has completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"BLK_SENDTEXTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"blk_sendtext has completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"BLK_TEXTXFERCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"blk_textxfer has completedCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CT_CANCELCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel has completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CT_CLOSECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_close has completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CT_CONNECTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_connect has completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CT_FETCHCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_fetch has completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CT_GET_DATACOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_get_data has completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CT_OPTIONSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_options has completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CT_RECVPASSTHRUCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_recvpassthru has completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CT_RESULTSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_results has completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CT_SENDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_send has completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CT_SEND_DATACOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_send_data has completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CT_SENDPASSTHRUCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_sendpassthru has completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A user-defined value. 
This value must be 
greater than or equal to 
CT_USER_FUNC.COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A user-defined function has completed.status is the return status of the completed routine. To find out what values status can have, see MOREINFO="NONE"Returns on the manual page for the routine.ID="IN4219-23124119"Completion callbackClient-Library routines that it can callREMAP="BO--Body"Because it is regarded as an extension of main-line code, a completion callback can call any Client-Library routine.ID="IN4219-23124120"Completion callbackvalid return valueREMAP="BO--Body"If a completion callback calls an asynchronous Client-Library routine, it should return the value returned by the routine itself. Otherwise, there are no restrictions on what a completion callback can return. It is recommended, however, that the completion callback return either CS_SUCCEED if the completion callback succeeded or CS_FAIL if an error occurred.ID="IN4219-23124121"Completion callbackexampleRENDERAS="SECT3"Completion Callback ExampleREMAP="BO--Body"The following is an example of a completion callback:REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/*** ex_acompletion_cb()**** Type of function:**      Internal example async lib**** Purpose:**       Installed as a callback into Open Client. It **       will dispatch to the appropriate completion**       processing routine based on async state.** **       Another approach to callback processing is to **       have each completion routine install the **       completion callback for the next step in **       processing. We use one dispatch point to aid **       in debugging the async processing (only need**       to set one breakpoint).**** Returns:**       Return of completion processing routine.**** Side Effects:**      None*/REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"CS_STATIC CS_RETCODE CS_INTERNALex_acompletion_cb(connection, cmd, function, status)CS_CONNECTION    *connection;CS_COMMAND       *cmd;CS_INT           function;CS_RETCODE       status;{CS_RETCODE       retstat;      ExAsync     *ex_async;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /*      ** Extract the user area out of the command      ** handle.      */      retstat = ct_cmd_props(cmd, CS_GET, CS_USERDATA,           &ex_async, CS_SIZEOF(ex_async), NULL);      if (retstat != CS_SUCCEED)      {          return retstat;      }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"      fprintf(stdout, "\nex_acompletion_cb: function \          %ld Completed", function);REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"      /* Based on async state, do the right thing */    switch ((int)ex_async->state)    {         case EX_ASEND:         case EX_ACANCEL_CURRENT:         retstat = ex_asend_comp(ex_async, connection,              cmd, function, status);         break;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"         case EX_ARESULTS:         retstat = ex_aresults_comp(ex_async,            connection, cmd, function, status);         break;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"         case EX_AFETCH:         retstat = ex_afetch_comp(ex_async,               connection, cmd, function, status);         break;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"         case EX_ACANCEL_ALL:         retstat = ex_adone_comp(ex_async, connection,              cmd, function, status);         break;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"         default:         ex_apanic("ex_acompletion_cb: unexpected \               async state");         break;     }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     return retstat;}ID="IN4220-23124122"Gateway applicationshandling encrypted passwords
ID="IN4219-23124123"Encryption callback
ID="IN429-23124124"Callbacksencryption callback
ID="IN4219-23124125"Encrypted passwordsRENDERAS="SECT2"Encryption CallbacksID="IN4210-23124126"Handshakesencrypted password securityREMAP="BO--Body"SQL Server uses encrypted password handshakes. Most applications are not aware of this because Client-Library automatically handles it.REMAP="BO--Body"Client-Library applications that are acting as gateways, however, need to handle password encryption explicitly, using an encryption callback routine to pass the server's encryption key to the client and to return the encrypted password back to the server.REMAP="BO--Body"In order to use an encryption callback, a connection must have its CS_SEC_ENCRYPTION property set to CS_TRUE.REMAP="BO--Body"For more information on handling encrypted password security handshakes, see LINKEND="X70164""Encrypted Password Security Handshakes" 
.ID="IN4219-23124127"Encryption callbackdefiningRENDERAS="SECT3"Defining an Encryption CallbackREMAP="BO--Body"An encryption callback is defined as follows:REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE encrypt_cb(connection, pwd, pwdlen,                 key, keylen, buf, buflen, outlen)REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_CONNECTION    *connection;CS_BYTE          *pwd;CS_INT           pwdlen;CS_BYTE          *key;CS_INT           keylen;CS_BYTE          *buffer;CS_INT           buflen;CS_INT           *outlen;REMAP="BO--Body"where:REMAP="RI--RefIndent"connection is a pointer to the CS_CONNECTION structure representing the connection that is logging into the server.pwd is the user password to be encryptedpwdlen is the length of the passwordkey is the key to use to encrypt the password.keylen is the length of the encryption keybuffer is a pointer to a buffer. The encryption callback should place the encrypted password in this buffer. This buffer is allocated and freed by Client-Library. Its length is described by buflen.buflen is the length, in bytes, of the *buffer data space.outlen is a pointer to a CS_INT. The encryption callback must set *outlen to the length of the encrypted password placed in *buffer.ID="IN4219-23124128"Encryption callbackvalid return valuesREMAP="BO--Body"An encryption callback should return CS_SUCCEED to indicate that the password was successfully encrypted. If the encryption callback returns a value other than CS_SUCCEED, Client-Library aborts the connection attempt, causing MOREINFO="NONE"ct_connect to return CS_FAIL.ID="IN4217-23124129"Secure SQL Serverhandling security labels
ID="IN4220-23124130"Negotiation callback
ID="IN429-23124131"Callbacksnegotiation callback
ID="IN4217-23124132"Secure SQL Serverhandling challengesRENDERAS="SECT2"Negotiation CallbacksID="IN4220-23124133"Negotiation callbacktrusted-user security handshakes
ID="IN4220-23124134"Negotiation callbackchallenge/response security handshakesREMAP="BO--Body"Client-Library uses the negotiation callback to handle both trusted-user security handshakes and challenge/response security handshakes.REMAP="BO--Body"For more information on these types of handshakes, see LINKEND="X23734""Security Features" 
.ID="IN4210-23124135"Handshakestrusted-user securityRENDERAS="SECT3"Trusted-User Security HandshakesREMAP="BO--Body"When logging into a server, a trusted-user security handshake occurs when the server asks the client for identifying security labels, which the client then provides.ID="IN4232-23124136"Trusted-user security handshakesnegotiation callbackREMAP="BO--Body"A connection can use a negotiation callback to provide these security labels. To do this, the connection installs a negotiation callback routine. At connection time, when Client-Library receives the server request for login security labels, it triggers the negotiation callback.REMAP="BO--Body"A connection can also use MOREINFO="NONE"ct_labels to define security labels. For more information, see the manual page for MOREINFO="NONE"ct_labels.REMAP="BO--Body"A connection that will be participating in trusted-user security handshakes must set its CS_SEC_NEGOTIATE property to CS_TRUE. ID="IN4210-23124137"Handshakeschallenge/response securityRENDERAS="SECT3"Challenge/Response Security HandshakesREMAP="BO--Body"When logging into a server, a challenge/response security handshake occurs when the server issues a challenge, to which the client must respond.ID="IN4238-23124138"Challenge/response security handshakesnegotiation callbacksREMAP="BO--Body"A connection can use a negotiation callback to provide its response to the challenge. To do this, the connection installs a negotiation callback routine. At connection time, when Client-Library receives the server challenge, it triggers the negotiation callback.REMAP="BO--Body"A connection that will be participating in challenge/response security handshakes must set either its CS_SEC_CHALLENGE property or its CS_SEC_APPDEFINED property to CS_TRUE. ID="IN4220-23124139"Negotiation callbackdefiningRENDERAS="SECT3"Defining a Negotiation CallbackREMAP="BO--Body"A negotiation callback is defined as follows:REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE negotiation_cb(connection, inmsgid,                outmsgid, inbuffmt, inbuf, outbuffmt,                outbuf, outbufoutlen) CS_CONNECTION   *connection;CS_INT          inmsgid;CS_INT          *outmsgid;CS_DATAFMT      *inbuffmt;CS_BYTE         *inbuf;CS_DATAFMT      *outbuffmt;CS_BYTE         *outbuf;CS_INT          *outbufoutlen;REMAP="BO--Body"where:REMAP="RI--RefIndent"connection is a pointer to the CS_CONNECTION structure representing the connection that is logging into the server.inmsgid is the type of information that the server is requesting. The following table lists the values that are legal for inmsgid:TOCENTRY="1"LBL="Table 2-5: "Values for inmsgid (Negotiation Callback)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="153*"COLNAME="C2" COLWIDTH="207*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Value of inmsgid:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_MSG_GETLABELSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The server is requesting security labels.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A user-defined value < 
CS_USER_MSGIDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The server is requesting a Sybase-defined 
value. It is the negotiation callback's 
responsibility to understand the meaning of 
inmsgid.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A user-defined value >= 
CS_USER_MSGID and <= 
CS_USER_MAX_MSGIDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The Open Server application is requesting 
an application-defined value. It is the 
negotiation callback's responsibility to 
understand the meaning of inmsgid.outmsgid is the type of information that the negotiation callback is returning. The following table lists the values that are legal for outmsgid:TOCENTRY="1"LBL="Table 2-6: "Values for outmsgid (Negotiation Callback)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="153*"COLNAME="C2" COLWIDTH="207*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Value of outmsgid:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_MSG_LABELSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The negotiation callback is returning 
security labels.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A user-defined value < 
CS_USER_MSGIDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The callback is returning a Sybase-defined 
value.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A user-defined value >= 
CS_USER_MSGID and <= 
CS_USER_MAX_MSGIDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The callback is returning an application-
defined value.inbuffmt is a pointer to a CS_DATAFMT structure. If the negotiation callback is handling a trusted-user handshake, inbuffmt is NULL. If the negotiation callback is handling a challenge/response handshake, *inbuffmt describes the inbuf challenge key.inbuf is a pointer to data space. If the negotiation callback is handling a trusted-user handshake, inbuf is NULL. If the negotiation callback is handling a challenge/response handshake, inbuf points to the challenge key.outbuffmt is a pointer to a CS_DATAFMT structure. The negotiation callback should fill this CS_DATAFMT with a description of the security label or response that it is returning.REMAP="UN--Under"Client-Library does not define which fields in the CS_DATAFMT need to be set; however, Secure SQL Server requires values for the name, namelen, and datatype fields.outbuf is a pointer to a buffer. The negotiation callback should place the security label or response in this buffer. This buffer is allocated and freed by Client-Library. Its length is described by outbuffmtname='rArrow' font='symbol' code='174'  charset='fontspecific'maxlength.outbufoutlen is the length, in bytes, of the data placed in *outbuf.ID="IN4220-23124140"Negotiation callbackvalid return valuesREMAP="BO--Body"A negotiation callback must return CS_SUCCEED, CS_FAIL, or CS_CONTINUE:MARK="BULL" REMAP="BU--Bullet"If the callback returns CS_CONTINUE, Client-Library calls the negotiation callback again to generate an additional security label or response.If the callback returns CS_SUCCEED, Client-Library sends the security label(s) or response(s) to the server.If the callback returns CS_FAIL, Client-Library aborts the connection process, causing MOREINFO="NONE"ct_connect to return CS_FAIL.ID="IN4221-23124141"Registered procedureshandling notifications
ID="IN4221-23124142"Registered proceduresnotification callbacks
ID="IN4221-23124143"Notification callback
ID="IN429-23124144"Callbacksnotification callbackRENDERAS="SECT2"Notification CallbacksREMAP="BO--Body"A registered procedure is a type of procedure that is defined and installed in a running Open Server. A Client-Library application can use a remote procedure call command to execute a registered procedure, and can "watch" for a registered procedure to execute.REMAP="BO--Body"When a registered procedure executes, applications watching for it receive a notification that includes the procedure's name and the arguments it was called with.REMAP="BO--Body"When Client-Library receives a notification, it calls an application's notification callback routine. REMAP="BO--Body"The registered procedure's name is available as the second parameter to the notification callback routine.ID="IN4221-23124145"Registered proceduresretrieving argumentsREMAP="BO--Body"The arguments with which the registered procedure was called are available inside the notification callback, as a parameter result set. To retrieve these arguments, an application:MARK="BULL" REMAP="BU--Bullet"Calls MOREINFO="NONE"ct_con_props(CS_NOTIF_CMD) to retrieve a pointer to the command structure containing the parameter result set.Calls MOREINFO="NONE"ct_res_info(CS_NUMDATA), MOREINFO="NONE"ct_describe, MOREINFO="NONE"ct_bind, MOREINFO="NONE"ct_fetch, and MOREINFO="NONE"ct_get_data to describe, bind, and fetch the parameters.REMAP="BO--Body"For more information on registered procedures, see the LINKEND="X72967""Registered Procedures"
topics page.ID="IN4221-23124146"Notification callbackdefiningRENDERAS="SECT3"Defining a Notification CallbackREMAP="BO--Body"A notification callback is defined as follows:REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE notification_cb(conn, proc_name, pnamelen) CS_CONNECTION    *conn;CS_CHAR          *proc_name;CS_INT           pnamelen;REMAP="BO--Body"where:REMAP="RI--RefIndent"connection is a pointer to the CS_CONNECTION structure receiving the notification. This CS_CONNECTION is the parent connection of the CS_COMMAND that sent the request to be notified.proc_name is a pointer to the name of the registered procedure that has been executed.pnamelen is the length, in bytes, of *proc_name.ID="IN4221-23124147"Notification callbackvalid return valueREMAP="BO--Body"A notification callback must return CS_SUCCEED.ID="IN4221-23124148"Notification callbackClient-Library routines it can callREMAP="BO--Body"The following table lists the Client-Library routines that a notification callback can call:TOCENTRY="1"LBL="Table 2-7: "Routines that a Client Message callback can call COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="153*"COLNAME="C2" COLWIDTH="207*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A Notification Callback Can Call:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Under What Circumstances?VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_configMOREINFO="NONE" COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To retrieve information only.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_con_propsMOREINFO="NONE" COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To retrieve information or to set the 
CS_USERDATA property only.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cmd_propsMOREINFO="NONE" COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To retrieve information or to set the 
CS_USERDATA property only.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_ATTN)COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"AnyCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_bind, ct_describe, ct_fetch, 
ct_get_data, 
ct_res_info(CS_NUMDATA)COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routines must be called with the 
command structure returned by the 
callbacks's MOREINFO="NONE"ct_con_props(CS_NOTIF_CMD) 
call.

For more information, see "Registered 
Procedures".ID="IN4226-23124149"Error and message handlinghandling server errors with a server message callback
ID="IN429-23124150"Callbacksserver message callback
ID="IN4223-23124151"Server message callbackRENDERAS="SECT2"Server Message CallbacksREMAP="BO--Body"An application can handle server error and informational messages in-line, or through a server message callback routine.REMAP="BO--Body" When a connection is allocated, it picks up a default server message callback from its parent context. If the parent context has no server message callback installed, then the connection is created without a default server message callback.REMAP="BO--Body"After allocating a connection, an application can:MARK="BULL" REMAP="BU--Bullet"Install a different server message callback for the connection.Call MOREINFO="NONE"ct_diag to initialize in-line message handling for the connection. Note that MOREINFO="NONE"ct_diag automatically de-installs all message callbacks for the connection.ID="IN4226-23124152"Error and message handlingserver message information can be discardedREMAP="BO--Body"If a server message callback is not installed and in-line message handling is not enabled, Client-Library discards server message information.REMAP="BO--Body"If callbacks are not implemented for a particular programming language/platform version of Client-Library, an application must handle server messages in-line, using MOREINFO="NONE"ct_diag.REMAP="BO--Body"If a connection is handling server messages through a server message callback, then the callback is called whenever a server message arrives.ID="IN4223-23124153"Server message callbackdefiningRENDERAS="SECT3"Defining a Server Message CallbackREMAP="BO--Body"A server message callback is defined as follows:REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE servermsg_cb(context, connection, message) CS_CONTEXT       *context;CS_CONNECTION    *connection;CS_SERVERMSG     *message;REMAP="BO--Body"where:REMAP="RI--RefIndent"context is a pointer to the CS_CONTEXT structure for which the message occurred.connection is a pointer to the CS_CONNECTION structure for which the message occurred.message is a pointer to a CS_SERVERMSG structure containing server message information. For information on the CS_SERVERMSG data structure, see the MOREINFO="NONE"CS_SERVERMSG topics page.REMAP="UN--Under"Note that message can have a new value each time the server message callback is called.ID="IN4223-23124154"Server message callbackvalid return valueA server message callback must return CS_SUCCEED.ID="IN4223-23124155"Server message callbackClient-Library routines it can callREMAP="BO--Body"The following table lists the Client-Library routines that a server message callback can call:TOCENTRY="1"LBL="Table 2-8: "Routines that a server message callback can call COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="153*"COLNAME="C2" COLWIDTH="207*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A Server Message 
Callback Can Call:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Under What Circumstances?VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_configMOREINFO="NONE" COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To retrieve information only.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_con_propsMOREINFO="NONE" COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To retrieve information or to set the 
CS_USERDATA property only.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cmd_propsMOREINFO="NONE" COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To retrieve information or to set the 
CS_USERDATA property only.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_ATTN)COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Any.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_bind, ct_describe, ct_fetch, 
ct_get_data, ct_res_infoCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routines must be called with the 
command structure returned by the 
callbacks's MOREINFO="NONE"ct_con_props(CS_EED_CMD) 
call.

A server message callback can call these 
routines only while extended error data is 
available; that is, until MOREINFO="NONE"ct_fetch returns 
CS_END_DATA.

For more information, see "Extended Error 
Data".ID="IN4223-23124156"Server message callbackexampleRENDERAS="SECT3"Server Message Callback ExampleREMAP="BO--Body"This is an example of a server message callback:REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/*** ex_servermsg_cb()**** Type of function:**      Example program server message handler**** Purpose:**      Installed as a callback into Open Client.** ** Returns:**      CS_SUCCEED**** Side Effects:**      None*/CS_RETCODE CS_PUBLICex_servermsg_cb(connection, cmd, srvmsg)CS_CONNECTION*    connection;CS_COMMAND        *cmd;CS_SERVERMSG      *srvmsg;{      fprintf(EX_ERROR_OUT, "\nServer message:\n");      fprintf(EX_ERROR_OUT, "Message number: %ld, \           Severity %ld, ", srvmsg->msgnumber,            srvmsg->severity);      fprintf(EX_ERROR_OUT, "State %ld, Line %ld",           srvmsg->state, srvmsg->line);REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"      if (srvmsg->svrnlen > 0)      {          fprintf(EX_ERROR_OUT, "\nServer '%s'",                 srvmsg->svrname);       }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"      if (srvmsg->proclen > 0)      {          fprintf(EX_ERROR_OUT, " Procedure '%s'",               srvmsg->proc);      }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"      fprintf(EX_ERROR_OUT, "\nMessage String: %s",          srvmsg->text);REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"      return CS_SUCCEED;}ID="IN4224-23124157"Operating-system signalshandling with a signal callback
ID="IN4215-23124158"Signal callback
ID="IN429-23124159"Callbackssignal callbackRENDERAS="SECT2"Signal CallbacksREMAP="BO--Body"A signal callback is called whenever a process receives a signal on a UNIX platform.REMAP="BO--Body"An application that needs to handle signals for its own purposes must do so by calling MOREINFO="NONE"ct_callback to install signal callbacks, rather than by making a signal system call to install a signal handler. This is because a signal system call will de-install Client-Library's signal handler. If this occurs, Client-Library's behavior is undefined.REMAP="BO--Body"When Client-Library receives a signal, Client-Library's signal handler:MARK="BULL" REMAP="BU--Bullet"Performs any internal Client-Library processing that is required. Calls the appropriate user-defined signal callback, if any.REMAP="BO--Body"An application that plans to install a signal callback must include the header file sys/signal.h.ID="IN4215-23124160"Signal callbackdefiningRENDERAS="SECT3"Defining a Signal CallbackREMAP="BO--Body"A signal callback must be defined according to operating system specifications.ID="IN4215-23124161"Signal callbackinstallingRENDERAS="SECT3"Installing a Signal CallbackREMAP="BO--Body"A signal callback can be installed only at the context level.REMAP="BO--Body"Signal callbacks are identified by adding the signal number on to the manifest constant ID="IN4226-25126162"CS_SIGNAL_CB callback type
CS_SIGNAL_CB. REMAP="BO--Body"The following routine demonstrates how to install a signal callback:REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/*** INSTALLSIGNALCB**** This routine installs a signal callback for the** specified signal**** Parameters:**      cp   Context handle**      signo   Signal number**      signalhandler   Signal handler to install**** Returns:**      CS_SUCCEED   Signal handler was installed**                   successfully**      CS_FAIL      An error was detected while**                   installing the signal handler*/CS_RETCODE  installsignalcb(cp, signo, signalhandler)CS_CONTEXT  *cp;CS_INT  signo;CS_VOID *signalhandler;{     CS_INT       adjustedsigno;     CS_RETCODE   ret;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"      /*      ** Add the signal number to the CS_SIGNAL_CB       ** define to indicate the signal number that this      ** handler is being installed for.      */      adjustedsigno = CS_SIGNAL_CB + signo;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"      ret = ct_callback(cp, (CS_CONNECTION *)NULL,           CS_SET, adjustedsigno, signalhandler);ID="IN429-26127163"CallbacksREMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"      return(ret);}RENDERAS="SECT1"ID="X17423"ID="IN4212-27128164"Capabilities
CapabilitiesREMAP="BO--Body"Capabilities describe features that a client/server connection supports.REMAP="BO--Body"For a list of capabilities, see LINKEND="X94203""ct_capability"
.ID="IN4212-27128165"Capabilitiesuses ofRENDERAS="SECT2"What are Capabilities Good For?REMAP="BO--Body"An application can use capabilities to find out what features are supported by a connection's actual TDS version.REMAP="BO--Body"In particular, an application can:ID="IN428-27128166"Requestsdetermining supported request typesMARK="BULL" REMAP="BU--Bullet"Find out whether a server connection supports a particular type of request.ID="IN429-27128167"Responsespreventing server responsesTell a server not to send a particular type of response on a connection.ID="IN4212-27128168"Capabilitiestypes ofRENDERAS="SECT2"Types of CapabilitiesREMAP="BO--Body"There are two types of capabilities:MARK="BULL" REMAP="BU--Bullet"ID="IN4227-29130169"CS_CAP_REQUEST capabilitiesmeaning of
CS_CAP_REQUEST capabilities, or "request capabilities," which describe the types of client requests that can be sent on a server connection.ID="IN4228-31132170"CS_CAP_RESPONSE capabilitiesmeaning of
CS_CAP_RESPONSE capabilities, or "response capabilities," which describe the types of server responses that a connection does not wish to receive.ID="IN4210-31132171"Retrievingcapabilities
ID="IN427-31132172"Settingcapabilities
ID="IN4212-31132173"Capabilitiessetting and retrievingRENDERAS="SECT2"Setting and Retrieving CapabilitiesREMAP="BO--Body"Before calling MOREINFO="NONE"ct_connect to open a connection, an application can:ID="IN423-31132174"TDSconnectionÕ s default version level
ID="IN4211-31132175"Connectionsdefault TDS version levelMARK="BULL" REMAP="BU--Bullet"Retrieve request or response capabilities, to determine what request and response features are normally supported at the connection's current TDS version level. A connection's TDS level defaults to the version level that the application requested in its call to MOREINFO="NONE"ct_initID="IN4211-31132176"Connectionschanging TDS version level
ID="IN423-31132177"TDSchanging a connectionÕ s TDS version level
. An application can change a connection's TDS level by calling MOREINFO="NONE"ct_con_props with property as CS_TDS_VERSION.Set response capabilities, to indicate that a connection does not wish to receive particular types of responses. For example, an application can set a connection's TDS_RES_NOEED capability to CS_TRUE to indicate that the connection does not wish to receive extended error data.ID="IN4211-31132178"Connectionsnegotiating the TDS version level
ID="IN423-31132179"TDSnegotiating the version levelREMAP="BO--Body"During the connection process, the client and server negotiate a TDS version level for the connection. The TDS version level determines which capabilities the connection will support.REMAP="BO--Body"After a connection is open, an application can:MARK="BULL" REMAP="BU--Bullet"Retrieve request capabilities to find out what types of requests the connection will support.Retrieve response capabilities to find out whether the server has agreed to withhold the previously-indicated response types from the connection.ID="X75264" RENDERAS="SECT3"Setting and Retrieving Multiple CapabilitiesREMAP="BO--Body"Gateway applications often need to set or retrieve all capabilities of a type category with a single call to MOREINFO="NONE"ct_capability. To do this, an application calls MOREINFO="NONE"ct_capability with:MARK="BULL" REMAP="BU--Bullet"type as the type category of interestcapability as ID="IN4220-35136180"CS_ALL_CAPS constantCS_ALL_CAPS
CS_ALL_CAPSvalue as a CS_CAP_TYPE structureREMAP="BO--Body"Client-Library provides the following macros to enable an application to set, clear, and test bits in a CS_CAP_TYPE structure:MARK="BULL" REMAP="BU--Bullet"ID="IN4220-39140181"CS_SET_CAPMASK macroCS_SET_CAPMASK
MOREINFO="NONE"CS_SET_CAPMASK(mask, capability)ID="IN4220-43144182"CS_CLR_CAPMASK macroCS_CLR_CAPMASK
MOREINFO="NONE"CS_CLR_CAPMASK(mask, capability)ID="IN4220-47148183"CS_TST_CAPMASK macroCS_TST_CAPMASK
MOREINFO="NONE"CS_TST_CAPMASK(mask, capability)REMAP="BO--Body"where mask is a pointer to a CS_CAP_TYPE structure and capability is the capability of interest.ID="IN4212-48149184"CapabilitiesREMAP="BO--Body"REMAP="BO--Body"RENDERAS="SECT1"ID="X26600"Client-Library MessagesID="IN42239921"Client-Library messagesREMAP="BO--Body"Client-Library message numbers are four bytes long. Each byte contains da separate piece of information.ID="IN42239922"Client-Library messagesinterpretingRENDERAS="SECT2"What the Bytes RepresentREMAP="BO--Body"The first (high-order) byte represents the Client-Library layer that is reporting the message. A typical application will not examine this byte except to provide information for SYBASE Technical Support.REMAP="BO--Body"The second byte represents the message's origin. A typical application will not examine this byte except to provide information for SYBASE Technical support.REMAP="BO--Body"The third byte represents the message's severity. For a list of possible severities, see LINKEND="X23180"Table 2-9: Client-Library message severities
.REMAP="BO--Body"The fourth (low-order) byte represents a layer-specific message number. RENDERAS="SECT2"Decoding a Message NumberID="IN42239923"Client-Library messagesmacros to decode message numbersREMAP="BO--Body"Client-Library provides the following macros to help an application decode a message number:MARK="BULL" REMAP="BU--Bullet"ID="IN42149564"CS_LAYER macroCS_LAYER
MOREINFO="NONE"CS_LAYER ID="IN421591105"CS_ORIGIN macroCS_ORIGIN
MOREINFO="NONE"CS_ORIGIN ID="IN421787146"CS_SEVERITY macroCS_SEVERITY
MOREINFO="NONE"CS_SEVERITY ID="IN421583187"CS_NUMBER macroCS_NUMBER
MOREINFO="NONE"CS_NUMBER REMAP="BO--Body"These macros are defined in the header file ID="IN422179228"cstypes.h header filecstypes.h
cstypes.h.REMAP="BO--Body"A typical application uses these macros to split a message number into four parts, which it then displays separately.REMAP="BO--Body"The client message callback example  demonstrates the use of these macros.ID="IN422379229"Client-Library messagesexplanation of severitiesRENDERAS="SECT2"Message SeveritiesREMAP="BO--Body"The following table lists Client-Library message severities:TOCENTRY="1"LBL="Table 2-9: " ID="X23180"Client-Library message severitiesCOLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="128*"COLNAME="C2" COLWIDTH="135*"COLNAME="C3" COLWIDTH="206*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Severity:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Explanation:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"User Action:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SV_INFORMCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No error has occurred. The 
message is informational.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No action is required. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SV_CONFIG_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A SYBASE configuration 
error has been detected. 
Configuration errors 
include missing localization 
files, a missing interfaces 
file, and an unknown server 
name in the interfaces file.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Raise an error so that the application's end-
user can correct the problem.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SV_RETRY_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An operation has failed, but 
the operation can be retried.
An example of this type of 
operation is a network read 
that times out.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The return value from an application's 
client message callback determines whether 
or not Client-Library retries the operation.

If the client message callback returns 
CS_SUCCEED, Client-Library retries the 
operation.

If the client message callback returns 
CS_FAIL, Client-Library does not retry the 
operation and marks the connection as 
dead. In this case, call 
MOREINFO="NONE"ct_close(CS_FORCE_CLOSE) to close the 
connection and then re-open it, if desired, 
by calling MOREINFO="NONE"ct_connect.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SV_API_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A Client-Library routine 
generated an error. This 
error is typically caused by 
a bad parameter or calling 
sequence. The server 
connection is probably 
salvageable.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Call MOREINFO="NONE"ct_cancel(CS_CANCEL_ALL) to clean 
up the connection. If 
MOREINFO="NONE"ct_cancel(CS_CANCEL_ALL) returns 
CS_SUCCEED, the server connection is 
unharmed. Note that it is illegal to perform 
this type of cancel from within a client 
message callback routine.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SV_RESOURCE_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A resource error has 
occurred. This error is 
typically caused by a malloc 
failure or lack of file 
descriptors. The server 
connection is probably not 
salvageable.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Call MOREINFO="NONE"ct_close(CS_FORCE_CLOSE) to close 
the server connection and then re-open it, if 
desired, by calling MOREINFO="NONE"ct_connect. Note that it is 
illegal to make these calls from within a 
client message callback routine.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SV_COMM_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An unrecoverable error in the server communication channel has occurred.
The server connection is not 
salvageable.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Call MOREINFO="NONE"ct_close(CS_FORCE_CLOSE) to close 
the server connection and then re-open it, if 
desired, by calling MOREINFO="NONE"ct_connect. Note that it is 
illegal to make these calls from within a 
client message callback routine.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SV_INTERNAL_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An internal Client-Library 
error has occurred.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Call MOREINFO="NONE"ct_exit(CS_FORCE_EXIT) to exit Client-
Library, and then exit the application. Note 
that it is illegal to call MOREINFO="NONE"ct_exit from within a 
client message callback routine.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SV_FATALCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A serious error has 
occurred. All server 
connections are unusable.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Call MOREINFO="NONE"ct_exit(CS_FORCE_EXIT) to exit Client-
Library, and then exit the application. Note 
that it is illegal to call MOREINFO="NONE"ct_exit from within a 
client message callback routine.ID="IN4223782310"Client-Library messagesREMAP="BO--Body"RENDERAS="SECT1"CommandsREMAP="BO--Body"In the client/server model, a server accepts commands from multiple clients and responds by returning data and other information to the clients. SYBASE Open Client applications use Client-Library routines to communicate commands to servers. For example, an application might send a cursor open command to a server, directing it to execute a SQL MOREINFO="NONE"select statement.ID="IN428782311"CommandsClient-Library routines that initiate commands
ID="IN4214782312"Client-Libraryroutines that initiate commands
ID="IN428782313"Commandstypes ofREMAP="BO--Body"The following table lists Client-Library routines that initiate commands, together with the types of commands that each routine initiates:TOCENTRY="1"LBL="Table 2-10: "Client-Library routines that initiate commandsCOLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="116*"COLNAME="C2" COLWIDTH="245*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Client-Library routine:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Initiates:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_commandMOREINFO="NONE" COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Miscellaneous commands, including language, 
message, package, remote procedure call (RPC), and 
send-data commands.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cursorMOREINFO="NONE" COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Cursor commands, including cursor declare, cursor 
options, cursor rows, cursor open, cursor update, 
cursor delete, cursor close, and cursor de-allocate.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_dynamic COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Dynamic commands, including cursor declare, 
prepare, describe input, execute, describe output, 
and de-allocate.ID="IN428782314"Commandssending to a serverRENDERAS="SECT2"Sending a Command to a ServerREMAP="BO--Body"In general, sending a command to a server is a four step process. To send a command to a server, an application must:NUMERATION="ARABIC" REMAP="S1--StepOne" CONTINUATION="RESTARTS" INHERITNUM="IGNORE"Initiate the command by calling MOREINFO="NONE"ct_command, MOREINFO="NONE"ct_cursor, or MOREINFO="NONE"ct_dynamic. These routines set up internal structures that are used in building a command stream to send to the server.Pass parameters for the command (if required). Most applications pass parameters by calling MOREINFO="NONE"ct_param once for each parameter that the command requires, but it is also possible to pass parameters for a command by using MOREINFO="NONE"ct_dyndesc.REMAP="UN--Under"Not all commands require parameters. For example, an RPC command may or may not require parameters, depending on the stored procedure being called. For information about which commands require parameters, see the MOREINFO="NONE"ct_param and MOREINFO="NONE"ct_dyndesc manual pages.Send the command to the server by calling MOREINFO="NONE"ct_send.Verify the success of the command by calling MOREINFO="NONE"ct_results.Step 4 does not imply that an application need only call MOREINFO="NONE"ct_results once. If the value of MOREINFO="NONE"ct_results' result_type parameter indicates that there are fetchable results, the application will most likely process the results using a loop controlled by MOREINFO="NONE"ct_results. See the Open Client Client-Library/C Programmer's Guide for a discussion of processing results.RENDERAS="SECT2"Deciding Which Type of Command to UseREMAP="BO--Body"In some cases, different Client-Library commands actually do the same thing. For example, an application might send an RPC command to a server to direct it to execute a stored procedure, or it might send a cursor command.ID="IN428782315"Commandsdifferent routines for similar tasksREMAP="BO--Body"The following table lists common tasks as well as various Client-Library routines that an application can use to accomplish them.TOCENTRY="1"LBL="Table 2-11: "Different Client-Library commands that accomplish the same tasksCOLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="126*"COLNAME="C2" COLWIDTH="180*"COLNAME="C3" COLWIDTH="162*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Task:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Routines:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NotesVALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Execute a statement(with no variables)COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_command(CS_LANG_CMD)MOREINFO="NONE"ct_sendCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_dynamic(CS_EXEC_IMMEDIATE)MOREINFO="NONE"ct_sendCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A MOREINFO="NONE"select statement is not allowed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Execute a statement(with variables)COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_command(CS_LANG_CMD)MOREINFO="NONE"ct_paramct_sendCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_command(CS_RPC_CMD)MOREINFO="NONE"ct_paramct_sendCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cursor(CS_CURSOR_DECLARE)MOREINFO="NONE"ct_paramct_cursor(CS_CURSOR_OPEN)MOREINFO="NONE"ct_paramct_sendCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_dynamic(CS_PREPARE)MOREINFO="NONE"ct_dynamic(CS_EXECUTE)MOREINFO="NONE"ct_paramct_sendCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Execute a SQL Server 
stored procedureCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_command(CS_RPC_CMD)MOREINFO="NONE"ct_sendCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"*buffer is the name of the stored 
procedure.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_command(CS_LANG_CMD)MOREINFO="NONE"ct_sendCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"*buffer is an "MOREINFO="NONE"execute 
st_proc_name" statement.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Declare a cursorCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_command(CS_LANG_CMD)MOREINFO="NONE"ct_sendCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Declares a (language based) 
cursor on a SQL statement.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cursor(CS_CURSOR_DECLARE)MOREINFO="NONE"ct_sendCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Declares a (Client-Library based) 
cursor on a SQL statement.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_dynamic(CS_PREPARE)MOREINFO="NONE"ct_dynamic(CS_CURSOR_DECLARE)MOREINFO="NONE"ct_sendCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Declares a (language based)
cursor on a prepared statement.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_dynamic(CS_PREPARE)MOREINFO="NONE"ct_dynamic(CS_CURSOR_DECLARE)MOREINFO="NONE"ct_cursor(CS_CURSOR_OPTION)MOREINFO="NONE"ct_sendCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Declares a (Client-Library based) 
cursor on a prepared statement.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cursor(CS_CURSOR_DECLARE)MOREINFO="NONE"ct_sendCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Declares a (Client-Library) cursor 
on a SQL Server stored 
procedure.

*text is an "MOREINFO="NONE"execute 
st_proc_name" statement.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_dynamic(CS_CURSOR_DECLARE)MOREINFO="NONE"ct_sendCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Declares a (language based) 
cursor on a SQL Server stored 
procedure.

*id is the identifier for the 
"MOREINFO="NONE"execute st_proc_name" 
statement that was previously 
prepared by a call to 
MOREINFO="NONE"ct_dynamic(CS_PREPARE). REMAP="BO--Body"Because an application can use different Client-Library commands to accomplish the same task, it is not always easy to choose which command type to use in an application.REMAP="BO--Body"The following sections contain information about each of the Client-Library routines that initiate commands.ID="IN4210762516"ct_commandRENDERAS="SECT2"ct_commandREMAP="BO--Body"This routine is unique for a number of reasons:MARK="BULL" REMAP="BU--Bullet"It is the only one of the three command initiation routines that initiates more than one kind of command.It is the only command initiation routine that accepts multiple language statements at one time.It has the ability to send a command to execute a SQL Server stored procedure either as a language command or as an RPC command.It provides the only means of inserting text and image data.REMAP="BO--Body"For information about RPC commands, see LINKEND="X68029""Remote Procedure Calls" 
and ``RPC (remote procedure call) Commands''.REMAP="BO--Body"For information about text and image data, see LINKEND="X51184""Text and Image" 
and LINKEND="X81429""Send-Data Commands" 
.ID="IN429742717"ct_cursorRENDERAS="SECT2"ct_cursorID="IN4222742718"Client-Library cursorsREMAP="BO--Body"This routine allows you to create and use Client-Library-based cursors. These are different from language-based cursors in that a single server connection can support multiple open cursors, each simultaneously processing its own result set.REMAP="BO--Body"In addition, an application can send commands to update or delete rows in the underlying table(s) while actively fetching rows of a cursor result set.REMAP="BO--Body"For information about Client-Library-based cursors, see LINKEND="X50078""Cursors"
.REMAP="BO--Body"For information on using Client-Library to update previously-fetched cursor rows, see the MOREINFO="NONE"ct_keydata manual page.ID="IN4210722919"ct_dynamicRENDERAS="SECT2"ct_dynamicREMAP="BO--Body"This routine was designed for precompiler use, but it can offer a Client-Library application the following advantages:MARK="BULL" REMAP="BU--Bullet"The ability to send a command to execute a prepared statement and reference the statement with a unique identifier.ID="IN4219722920"Prepared statementsdefinitionREMAP="UN--Under"A prepared statement is a statement that has been compiled and stored with an identifier as a result of a MOREINFO="NONE"ct_dynamic(CS_PREPARE) call and a MOREINFO="NONE"ct_send call.ID="IN4219722921"Prepared statementswhy prepare a statement?REMAP="UN--Under"An application typically prepares a statement if it plans to execute the statement multiple times. Variables are particularly useful in dynamic commands because they allow an application to compile a statement once and change the values of the statement's variables each time it executes the statement.ID="IN4236722922"Describing prepared statement outputThe ability to describe (with CS_DESCRIBE_OUTPUT) prepared statement output before sending a command to execute the statement.Less overhead and faster performance than MOREINFO="NONE"ct_command, if the statement is executed more than once. This benefit is specific to the execution of SQL statements on a SQL Server.REMAP="BO--Body"All of the above advantages can also be realized using a stored procedure and either language or RPC commands. Because of the limitations of dynamic SQL, its use is discouraged. For a discussion of the limitations of dynamic SQL functionality, see LINKEND="X39013""Dynamic SQL"
.REMAP="BO--Body"REMAP="BO--Body"RENDERAS="SECT1"CS_BROWSEDESC StructureREMAP="BO--Body"ID="IN42119473"Browse modeBrowse mode and CS_BROWSEDESC structureCS_BROWSEDESC
MOREINFO="NONE"ct_br_column uses a CS_BROWSEDESC structure to return information about a column returned as the result of a browse-mode MOREINFO="NONE"select. This information is useful when an application needs to construct a language command to update browse-mode tables.REMAP="BO--Body"A CS_BROWSEDESC structure is defined as follows:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"/*** CS_BROWSEDESC** The Client-Library browse column description** structure.*/typedef struct _cs_browsedesc{    CS_INT      status;    CS_BOOL     isbrowse;    CS_CHAR     origname[CS_MAX_NAME];    CS_INT      orignlen;    CS_INT      tablenum;    CS_CHAR     tablename[CS_OBJ_NAME];    CS_INT      tabnlen;} CS_BROWSEDESC;REMAP="BO--Body"where:REMAP="RI--RefIndent"status is a bit mask of the following symbols, or-ed together:REMAP="UN--Under"CS_EXPRESSION to indicate the column is the result of an expression, for example, "sum*2" in the query "select sum*2 from areas".REMAP="UN--Under"CS_HIDDEN to indicate that the column is a "hidden" column that has been exposed. For more information, see CS_HIDDEN_KEYS on the MOREINFO="NONE"Properties topics page.REMAP="UN--Under"CS_KEY to indicate that the column is a key column. For more information, see the MOREINFO="NONE"ct_keydata manual page.REMAP="UN--Under"CS_RENAMED to indicate that the column's heading is not the original name of the column. Columns will have a different heading from the column name in the data base if they are the result of a query of the form "select Author = au_lname from authors".isbrowse indicates whether or not the column can be browse-mode updated.REMAP="UN--Under"A column can be updated if it is not the result of an expression and if it belongs to a browsable table. A table is browsable if it has a unique index and a timestamp column.REMAP="UN--Under"isbrowse is set to CS_TRUE if the column can be updated and CS_FALSE if it cannot.origname is the original name of the column in the database. origname is a null-terminated string.REMAP="UN--Under"Any updates to a column must refer to it by its original name, not the heading that may have been given the column in a MOREINFO="NONE"select statement.orignlen is the length, in bytes, of origname.tablenum is the number of the table to which the column belongs. The first table in a select statement's from-list is table number 1, the second number 2, and so forth.tablename is the name of the table to which the column belongs. tablename is a null-terminated string.tabnlen is the length, in bytes, of tablename.ID="IN42109294"StructuresCS_CLIENTMSG structure
ID="IN422290115"CS_CLIENTMSG structureID="X35643" RENDERAS="SECT1"CS_CLIENTMSG Structure ID="IN422688136"Error and message handlingError and message handling and CS_CLIENTMSG structureCS_CLIENTMSGREMAP="BO--Body"A CS_CLIENTMSG structure contains information about a Client-Library error or informational message.REMAP="BO--Body"Client-Library uses a CS_CLIENTMSG structure in two ways:MARK="BULL" REMAP="BU--Bullet"For connections using the callback method to handle messages, a CS_CLIENTMSG is the third parameter that Client-Library passes to an application's client message callback routine.For connections handling messages in-line, MOREINFO="NONE"ct_diag can return information in a CS_CLIENTMSG.REMAP="BO--Body"For information on error and message handling, see LINKEND="X46924""Error and Message Handling" 
.REMAP="BO--Body"For information on Client-Library messages, see LINKEND="X26600""Client-Library Messages" 
.REMAP="BO--Body"A CS_CLIENTMSG structure is defined as follows:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"/*** CS_CLIENTMSG** The Client-Library client message structure.*/ typedef struct _cs_clientmsg{    CS_INT      severity;    CS_MSGNUM   msgnumber;    CS_CHAR     msgstring[CS_MAX_MSG];    CS_INT      msgstringlen;     /*    ** If the error involved the operating    ** system, the following fields contain     ** operating-system-specific information:    */    CS_INT      osnumber;    CS_CHAR     osstring[CS_MAX_MSG];    CS_INT      osstringlen;     /*    ** Other information:    */    CS_INT      status;    CS_BYTE     sqlstate[CS_SQLSTATE_SIZE];    CS_INT      sqlstatelen;  } CS_CLIENTMSG;REMAP="BO--Body"where:REMAP="RI--RefIndent"severity is a symbolic value representing the severity of the message. The following table lists the legal values for severity:TOCENTRY="1"LBL="Table 2-12: "Values for severity (CS_CLIENTMSG)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="128*"COLNAME="C2" COLWIDTH="237*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Severity:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Explanation:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SV_INFORMCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No error has occurred. The message is 
informational.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SV_CONFIG_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A SYBASE configuration error has been detected. 
Configuration errors include missing localization 
files, a missing interfaces file, and an unknown 
server name in the interfaces file.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SV_RETRY_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An operation has failed, but the operation can be 
retried.

An example of this type of operation is a network 
read that times out.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SV_API_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A Client-Library routine generated an error. This 
error is typically caused by a bad parameter or 
calling sequence. The server connection is 
probably salvageable.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SV_RESOURCE_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A resource error has occurred. This error is 
typically caused by a malloc failure or lack of file 
descriptors. The server connection is probably not 
salvageable.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SV_COMM_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An unrecoverable error in the server communication channel has occured
The server connection is not salvageable.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SV_INTERNAL_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An internal Client-Library error has occurred.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SV_FATALCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A serious error has occurred. All server 
connections are unusable.msgnumber is the Client-Library message number. For information on how to interpret this number, see the LINKEND="X26600""Client-Library Messages"
topics.msgstring is the null-terminated Client-Library message string.msgstring is the Client-Library message string. REMAP="UN--Under"If an application is not sequencing messages, msgstring is guaranteed to be null-terminated, even if it has been truncated.REMAP="UN--Under"If an application is sequencing messages, msgstring is null-terminated only if it is the last chunk of a sequenced message.REMAP="UN--Under"For more information on sequenced messages, see LINKEND="X74900""Sequencing Long Messages" 
.msgstringlen is the length, in bytes, of msgstring. This is always the actual length, never the symbolic value CS_NULLTERM.osnumber is the operating system error number, if any. Client-Library sets osnumber to 0 if no operating system error has occurred.osstring is the null-terminated operating system error string, if any.osstringlen is the length of osstring. This is always the actual length, never the symbolic value CS_NULLTERM.status is a bitmask used to indicate various types of information, such as whether or not this is the first, a middle, or the last chunk of an error message. The following table lists the values that can be present in status:TOCENTRY="1"LBL="Table 2-13: "Values for status (CS_CLIENTMSG) COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="127*"COLNAME="C2" COLWIDTH="232*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Symbolic Value:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FIRST_CHUNKCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The message text contained in msgstring is the first 
chunk of the message.

If CS_FIRST_CHUNK and CS_LAST_CHUNK are 
both on, then msgstring contains the entire 
message.

If neither CS_FIRST_CHUNK nor 
CS_LAST_CHUNK is on, then msgstring contains 
a middle chunk of the message.

For more information on sequenced messages, see 
"Sequencing Long Messages" .COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_LAST_CHUNKCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The message text contained in msgstring is the last 
chunk of the message.

If CS_FIRST_CHUNK and CS_LAST_CHUNK are 
both on, then msgstring contains the entire 
message.

If neither CS_FIRST_CHUNK nor 
CS_LAST_CHUNK is on, then msgstring contains 
a middle chunk of the message.

For more information on sequenced messages, see 
"Sequencing Long Messages" .sqlstate is a byte string describing the error. REMAP="UN--Under"Not all client messages have SQL state values associated with them. If no SQL state value is associated with a message, sqlstate has the value "ZZZZZ".sqlstatelen is the length, in bytes, of the sqlstate string.ID="IN421086157"StructuresCS_DATAFMT structure
ID="IN422084178"CS_DATAFMT structureID="X19225" RENDERAS="SECT1"CS_DATAFMT StructureID="IN42784179"Formatsdescribing data formats
ID="IN429841710"Datatypesstructure for describing
ID="IN4221841711"Data format structureREMAP="BO--Body"A CS_DATAFMT structure is used to describe data values and program variables. For example:MARK="BULL" REMAP="BU--Bullet" MOREINFO="NONE"ct_bind requires a CS_DATAFMT structure to describe a destination variable.MOREINFO="NONE"ct_describe returns a CS_DATAFMT structure to describe a result data item.MOREINFO="NONE"ct_param requires a CS_DATAFMT to describe an input parameter.MOREINFO="NONE"cs_convert requires CS_DATAFMT structures to describe source and destination data.REMAP="BO--Body"Most routines use only a subset of the fields in a CS_DATAFMT. For example, MOREINFO="NONE"ct_bind does not use the name, status, and usertype fields, and MOREINFO="NONE"ct_describe does not use the format field. For information on which fields in the CS_DATAFMT a routine uses, see the manual page for the routine.REMAP="BO--Body"A CS_DATAFMT structure is defined as follows:REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"typedef struct _cs_datafmt{    CS_CHAR name[CS_MAX_NAME];  /* Name of data */    CS_INT  namelen;            /* Length of name */    CS_INT  datatype;           /* Data's datatype */    CS_INT  format;             /* Format symbols */    CS_INT  maxlength;          /* Data max length */    CS_INT  scale;              /* Scale of data */    CS_INT  precision;          /* Data precision */    CS_INT  status;             /* Status symbols */REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /*     ** The following field indicates the number of      ** rows to copy, per ct_fetch call, to a bound      ** program variable. ct_describe sets this field      ** to a default value of 1. ct_bind is the only     ** routine that reads this field.     */     CS_INT  count;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /*     ** These fields are used to support SQL Server      ** user-defined datatypes and international     ** datatypes:     */     CS_INT       usertype;           /* Svr user-def'd type */     CS_LOCALE   *locale;    /* Locale information */REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"} CS_DATAFMT;REMAP="BO--Body"where:REMAP="RI--RefIndent"name is the name of the data. name is often a column or parameter name.namelen is the length, in bytes, of name. Set namelen to ID="IN4220802112"CS_NULLTERM constantCS_NULLTERM
CS_NULLTERM to indicate a null-terminated name. Set namelen to 0 to if name is NULL.datatype is a type constant representing the datatype of the data. This is either one of the Open Client datatypes listed on the MOREINFO="NONE"Types topics page, or an Open Client user-defined datatype. For information on user-defined datatypes, see the MOREINFO="NONE"Types topics page. REMAP="UN--Under"Do not confuse the datatype field with the usertype field. datatype is always used to describe the Open Client datatype of the data. usertype is only used if the data has a SQL Server user-defined datatype in addition to an Open Client datatype.REMAP="UN--Under"For example, the following SQL Server command creates the SQL Server user-defined type birthday:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"sp_addtype birthday, datetimeREMAP="UN--Under"and this command creates a table containing a column of the new type:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"create table birthdays(    name        varchar(30),    happyday    birthday)REMAP="UN--Under"If a Client-Library application executes a select against this table and calls MOREINFO="NONE"ct_describe to get a description of the birthday column in the result set, the datatype and usertype fields in the CS_DATAFMT structure are set as follows:REMAP="UN--Under"datatype is set to CS_DATETIME_TYPE.usertype is set to the SQL Server id for the type birthday.format describes the destination format of character or binary data. format is a bit mask of the following symbols, or'ed together:TOCENTRY="1"LBL="Table 2-14: "Values for format (CS_DATAFMT)COLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="114*"COLNAME="C2" COLWIDTH="166*"COLNAME="C3" COLWIDTH="79*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Symbol:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Notes:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FMT_NULLTERMCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The data should be null-
terminated.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"For character 
or text data.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FMT_PADBLANKCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The data should be padded with 
blanks to the full length of the 
destination variable.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"For character 
or text data.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FMT_PADNULLCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The data should be padded with 
NULLs to the full length of the 
destination variable.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"For character, 
text, binary or 
image data.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FMT_UNUSEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No format information is being 
provided.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"For all data 
types.maxlength can represent various lengths, depending on which Open Client routine is using the CS_DATAFMT. The following table lists the meanings of maxlength:TOCENTRY="1"LBL="Table 2-15: "Meaning of maxlength (CS_DATAFMT)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="101*"COLNAME="C2" COLWIDTH="259*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Open Client routine:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"maxlength is:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_bindMOREINFO="NONE" COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The length of the bind variable.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_describeMOREINFO="NONE" COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The maximum possible length of the column or 
parameter being described. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_paramMOREINFO="NONE" COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The maximum desired length of return parameter data.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"cs_convertMOREINFO="NONE" COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The length of the source data and the length of the 
destination buffer space.scale is the scale of the data. scale is used only with decimal or numeric datatypes.REMAP="UN--Under"At the current time, legal values for scale are from 0 to 77. The default scale is 0.ID="IN4221762513"CS_MIN_SCALE constantCS_MIN_SCALE
CS_MIN_SCALE, ID="IN4221722914"CS_MAX_SCALE constantCS_MAX_SCALE
CS_MAX_SCALE, and ID="IN4220683315"CS_DEF_PREC constantCS_DEF_PREC
CS_DEF_PREC define the minimum, maximum, and default scale values, respectively.REMAP="UN--Under"To indicate that destination data should use the same scale as the source data, set scale to ID="IN4221643716"CS_SRC_VALUE constantCS_SRC_VALUE
CS_SRC_VALUE.REMAP="UN--Under"scale must be less than or equal to precision.precision is the precision of the data. precision is used only with decimal or numeric datatypes. REMAP="UN--Under"At the current time, legal values for precision are from 1 to 77. The default precision is 18. ID="IN4220604117"CS_MIN_PREC constantCS_MIN_PREC
CS_MIN_PREC, ID="IN4220564518"CS_MAX_PREC constantCS_MAX_PREC
CS_MAX_PREC, ID="IN4220524919"CS_DEF_PREC constantCS_DEF_PREC
and CS_DEF_PREC define the minimum, maximum, and default precision values, respectively.REMAP="UN--Under"To indicate that destination data should use the same precision as the source data, set precision to ID="IN4221485320"CS_SRC_VALUE constantCS_SRC_VALUE
CS_SRC_VALUE.REMAP="UN--Under"precision must be greater than or equal to scale.status is a bit mask used to indicate various types of information. The following table lists the values that can make up status:TOCENTRY="1"LBL="Table 2-16: "Values for status (CS_DATAFMT)COLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="120*"COLNAME="C2" COLWIDTH="150*"COLNAME="C3" COLWIDTH="89*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Symbolic Value:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Value is Legal 
For:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CANBENULLCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The column can contain NULL 
values.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_describe, 
MOREINFO="NONE"ct_dyndescCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_HIDDENCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The column is a "hidden" 
column that has been exposed.

For more information, see the 
CS_HIDDEN_KEYS on the MOREINFO="NONE"Properties topics page.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_describeMOREINFO="NONE", 
MOREINFO="NONE"ct_dyndescCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_IDENTITYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The column is an identity 
column.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_describe, 
MOREINFO="NONE"ct_dyndescCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_KEYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The column is a key column.

For more information, see the 
manual page for MOREINFO="NONE"ct_keydata.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_describeMOREINFO="NONE", 
MOREINFO="NONE"ct_dyndescCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_UPDATABLECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The column is an updatable 
cursor column.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_describe,
MOREINFO="NONE"ct_dyndescCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_VERSION_KEYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The column is part of the 
version key for the row.
 SQL Server uses version keys 
for positioning cursors.
For more information, see the 
manual page for MOREINFO="NONE"ct_keydata.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_describeMOREINFO="NONE", 
MOREINFO="NONE"ct_dyndescCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TIMESTAMPCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The column is a timestamp 
column. An application uses 
timestamp columns when 
performing browse-mode 
updates.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_describeMOREINFO="NONE" COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_UPDATECOLCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The parameter is the name of a 
column in the update clause of 
a cursor declare command.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_param,
MOREINFO="NONE"ct_dyndescCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_INPUTVALUECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The parameter is an input 
parameter value for a Client-
Library command.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_paramMOREINFO="NONE", 
MOREINFO="NONE"ct_dyndescCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_RETURNCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The parameter is a return 
parameter to an RPC 
command.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_param,
MOREINFO="NONE"ct_dyndesccount is the number of rows to copy to program variables per MOREINFO="NONE"ct_fetch call. count is used only by MOREINFO="NONE"ct_bind.usertype is the server user-defined datatype, if any, of data returned by the server. usertype is used only for server user-defined types, not for Client-Library user-defined types. For a discussion of Client-Library user-defined types, see the MOREINFO="NONE"Types topics page.locale is a pointer to a CS_LOCALE structure containing localization information. Set locale to NULL if localization information is not required.REMAP="UN--Under"Before using a CS_DATAFMT structure, make sure that locale is valid either by setting it to NULL or to the address of a valid CS_LOCALE structure.ID="IN4210465521"StructuresCS_IODESC structure
ID="IN4219445722"CS_IODESC structureID="X66404" RENDERAS="SECT1"CS_IODESC StructureID="IN429445723"Bulk copydescribing bulk copy data
ID="IN4214445724"Text and imagedescribing text and image data
ID="IN4214425925"Text and imageText and imageand CS_IODESC structureCS_IODESC
ID="IN429406126"Bulk copyBulk copyand CS_IODESC structureCS_IODESC
ID="IN4224406127"I/O descriptor structureREMAP="BO--Body"A CS_IODESC, also called an "I/O descriptor structure," describes text or image data. REMAP="BO--Body"An application calls MOREINFO="NONE"ct_data_info to retrieve a CS_IODESC structure after retrieving a text or image value that it plans to update at a later time. REMAP="BO--Body"Once it has a valid CS_IODESC, a typical application will change only the values of the locale, total_txtlen, and log_on_update fields before using the CS_IODESC to update the text or image value.REMAP="BO--Body"An application calls MOREINFO="NONE"ct_data_info to define a CS_IODESC structure after calling MOREINFO="NONE"ct_command to initiate a send-data operation to update a text or image value.REMAP="BO--Body"A CS_IODESC is defined as follows:REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"typedef struct _cs_iodesc{    CS_INT        iotype;             /* CS_IODATA           */    CS_INT        datatype;           /* Text or image.      */    CS_LOCALE     *locale;            /* Locale information. */    CS_INT        usertype;           /* User-defined type.  */    CS_INT        total_txtlen;       /* Total data length.  */    CS_INT        offset;             /* Reserved.           */    CS_BOOL       log_on_update       /* Log the insert?     */    CS_CHAR       name[CS_OBJ_NAME];  /* Name of data object.*/    CS_INT        namelen            /* Length of name.     */    CS_BYTE       timestamp[CS_TS_SIZE];  /* SQL Server id.  */    CS_INT        timestamplen; /* Length of timestamp.*/    CS_BYTE       textptr[CS_TP_SIZE];    /* SQL Server ptr. */    CS_INT        textptrlen;         /* Length of textptr.  */} CS_IODESC;REMAP="BO--Body"where:REMAP="RI--RefIndent"iotype indicates the type of I/O to perform. For text and image operations, iotype always has the value CS_IODATA.datatype is the datatype of the data object. The only legal values for datatype are CS_TEXT_TYPE and CS_IMAGE_TYPE.locale is a pointer to a CS_LOCALE structure containing localization information for the text or image value. Set locale to NULL if localization information is not required.REMAP="UN--Under"Before using a CS_IODESC structure, make sure that locale is valid either by setting it to NULL or to the address of a valid CS_LOCALE structure.usertype is the SQL Server user-defined datatype of the data object, if any. On send-data operations, usertype is ignored. On get-data operations, Client-Library sets usertype in addition to (not instead of) datatype.total_textlen is the total length, in bytes, of the text or image value.offset is reserved for future use.log_on_update describes whether the server should log the update to this text or image value.name is the name of the text or image column. name is a null-terminated string of the form table.column.namelen is the length, in bytes, of name (not including the null terminator). When filling in a CS_IODESC, an application can set namelen to CS_NULLTERM to indicate a null-terminated name.timestamp is the text timestamp of the column. A text timestamp marks the time of a text or image column's last modification.timestamplen is the length, in bytes, of timestamp.textptr is the text pointer for the column. A text pointer is an internal server pointer that points to the data for a text or image column. textptr identifies the target column in a send-data operation.textptrlen is the length, in bytes, of textptr.ID="IN4210386328"StructuresCS_SERVERMSG structure
ID="IN4222366529"CS_SERVERMSG structureID="X49789" RENDERAS="SECT1"CS_SERVERMSG StructureID="IN4226346730"Error and message handlingError and message handlingand CS_SERVERMSG structureCS_SERVERMSGREMAP="BO--Body"A CS_SERVERMSG structure contains information about a server error or informational message.REMAP="BO--Body"Client-Library uses a CS_SERVERMSG structure in two ways:MARK="BULL" REMAP="BU--Bullet"For connections using the callback method to handle messages, a CS_SERVERMSG is the third parameter that Client-Library passes to the connection's server message callback.For connections handling messages in-line, MOREINFO="NONE"ct_diag can return information in a CS_SERVERMSG.REMAP="BO--Body"For information on error and message handling, see LINKEND="X46924""Error and Message Handling" 
.REMAP="BO--Body"A CS_SERVERMSG structure is defined as follows:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"/*** CS_SERVERMSG** The Client-Library server message structure.*/REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"typedef struct _cs_servermsg{    CS_MSGNUM   msgnumber;    CS_INT      state;    CS_INT      severity;    CS_CHAR     text[CS_MAX_MSG];    CS_INT      textlen;    CS_CHAR     svrname[CS_MAX_NAME];    CS_INT      svrnlen;REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"    /*    ** If the error involved a stored procedure,    ** the following fields contain information    ** about the procedure:    */    CS_CHAR     proc[CS_MAX_NAME];    CS_INT      proclen;    CS_INT      line;REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"    /*    ** Other information.    */    CS_INT      status;    CS_BYTE     sqlstate[CS_SQLSTATE_SIZE];    CS_INT      sqlstatelen;REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"} CS_SERVERMSG;REMAP="BO--Body"where:REMAP="RI--RefIndent"msgnumber is the server message number. For a list of SQL Server messages, execute the Transact-SQL command:REMAP="UI--UserInput" FORMAT="LINESPECIFIC"select * from sysmessagesstate is the server error state. severity is the severity of the message. For a list of SQL Server message severities, execute the Transact-SQL command:REMAP="UI--UserInput" FORMAT="LINESPECIFIC"select distinct severity from sysmessagestext is the text of the server message. REMAP="UN--Under"If an application is not sequencing messages, text is guaranteed to be null-terminated, even if it has been truncated.REMAP="UN--Under"If an application is sequencing messages, text is null-terminated only if it is the last chunk of a sequenced message.REMAP="UN--Under"For more information on sequenced messages, see LINKEND="X74900""Sequencing Long Messages" 
.textlen is the length, in bytes, of text. This is always the actual length, never the symbolic value CS_NULLTERM.svrname is the name of the server that generated the message. This is the name of the server as it appears in the interfaces file. svrname is a null-terminated string.svrnlen is the length, in bytes, of svrname.proc is the name of the stored procedure which caused the message, if any. proc is a null-terminated string.proclen is the length, in bytes, of proc.line is the line number, if any, of the line that caused the message. line can be a line number in a stored procedure or a line number in a command batch.status is a bitmask used to indicate various types of information, such as whether or not extended error data is included with the message. The following table lists the values that can be present in status:TOCENTRY="1"LBL="Table 2-17: "Values for status (CS_SERVERMSG) COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="127*"COLNAME="C2" COLWIDTH="232*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Symbolic Value:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_HASEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Extended error data is included with the message.

For more information on extended error data, see 
"Extended Error Data" .COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FIRST_CHUNKCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The message text contained in text is the first 
chunk of the message.

If CS_FIRST_CHUNK and CS_LAST_CHUNK are 
both on, then text contains the entire message.

If neither CS_FIRST_CHUNK nor 
CS_LAST_CHUNK is on, then text contains a 
middle chunk of the message.

For more information on sequenced messages, see 
"Sequencing Long Messages" .COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_LAST_CHUNKCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The message text contained in text is the last 
chunk of the message.

If CS_FIRST_CHUNK and CS_LAST_CHUNK are 
both on, then text contains the entire message.

If neither CS_FIRST_CHUNK nor 
CS_LAST_CHUNK is on, then text contains a 
middle chunk of the message.

For more information on sequenced messages, see 
"Sequencing Long Messages" .sqlstate is a byte string describing the error. REMAP="UN--Under"Not all server messages have SQL state values associated with them. If no SQL state value is associated with a message, sqlstate has the value "ZZZZZ".sqlstatelen is the length, in bytes, of the sqlstate string.ID="IN427336831"CursorsID="X50078" RENDERAS="SECT1"CursorsID="IN427336832"Cursorsdescription ofREMAP="BO--Body"A cursor is a symbolic name that is associated with one of the following SQL statements:MARK="BULL" REMAP="BU--Bullet"A SQL MOREINFO="NONE"select statementA Transact-SQL MOREINFO="NONE"execute statementREMAP="UN--Under"The stored procedure being executed can contain only a single SQL MOREINFO="NONE"select statement.A dynamic SQL prepared statement where the statement can be either:MARK="DASH" REMAP="BS--BulletSub"A SQL MOREINFO="NONE"select statementA Transact-SQL MOREINFO="NONE"execute statementREMAP="UN--Under"The stored procedure being executed can contain only a single SQL MOREINFO="NONE"select statement.REMAP="BO--Body"The SQL statement associated with a cursor is called the body of the cursor.ID="IN427336833"Cursorslanguage cursor
ID="IN4216307134"Language cursorsSee Also CursorsREMAP="BO--Body"Client-Library allows an application to declare and manipulate a cursor as either a language cursor (using MOREINFO="NONE"ct_commandID="IN427307135"CursorsClient-Library cursor
ID="IN4222277436"Client-Library cursorsSee Cursors
) or a Client-Library cursor (using MOREINFO="NONE"ct_cursor). REMAP="BO--Body"Both language cursors and Client-Library cursors can be used to send commands to SYBASE SQL Servers and Open Server applications.REMAP="BO--Body"A language cursor cannot be manipulated using MOREINFO="NONE"ct_cursor; likewise, a Client-Library cursor cannot be manipulated using MOREINFO="NONE"ct_command.ID="X92621" RENDERAS="SECT2"Language CursorsID="IN427277437"Cursorsdeclaring language cursorsRENDERAS="SECT3"Declaring Language CursorsID="IN4210257638"ct_commandct_commandand language cursorslanguage cursorsREMAP="BO--Body"An application creates a language cursor by initiating a call to ID="IN427237839"CursorsCursorsand ct_commandct_command
MOREINFO="NONE"ct_command(CS_LANG_CMD) and specifying a cursor declare statement. For an application accessing SQL Server, the cursor declare statement would be a MOREINFO="NONE"declare cursor command.ID="IN427237840"Cursorslanguage cursorsÕ  use of command structuresREMAP="BO--Body"An application can declare one or more language cursors using the same or different command structures. The association between a language cursor and a command structure is short-lived: from the time at which a command is initiated (MOREINFO="NONE"ct_command(CS_LANG_CMD)) until the command results are fully processed.REMAP="BO--Body"The following commands use Transact-SQL to declare two language cursors, specify their cursor rows settings, and open them, all in the same command structure space.REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"strcpy(buf, "declare A cursor for select * from \                A_Table \            set cursor rows 10 for A \            declare B cursor for select * from \                B_Table \            set cursor rows 5 for B \            open A \            open B");REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"ct_command(cmd, CS_LANG_CMD, buf, CS_NULLTERM,    CS_UNUSED);REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"ct_send(cmd);REMAP="BO--Body"For detailed information about MOREINFO="NONE"ct_command, see the MOREINFO="NONE"ct_command manual page.RENDERAS="SECT3"Regular Row Result SetsID="IN427237841"Cursorslanguage cursors and regular row result setsREMAP="BO--Body"Language cursors generate regular row result sets when an application fetches against them:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"strcpy(buf2, "fetch A \             fetch B");REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"ct_command(cmd, CS_LANG_CMD, buf2, CS_NULLTERM,    CS_UNUSED);REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"ct_send(cmd);REMAP="BO--Body"The number of rows returned to Client-Library per MOREINFO="NONE"fetchID="IN427237842"Cursorscursor rows setting
command is equal to the current "cursor rows" setting for the cursor: 10 for cursor A and 5 for cursor B, in this case. It is useful to refer to this portion of the result set as a buffer's worth of rows. The application fetches the rows from Client-Library by making calls to MOREINFO="NONE"ct_fetch.ID="IN4219237843"Regular row resultsfetchingRENDERAS="SECT3"Fetching From Regular Row Result SetsID="IN4219237844"Regular row resultssimultaneous fetching from multiple result setsREMAP="BO--Body"An application can simultaneously fetch from multiple regular row result sets. It must, however, completely process the buffer's worth of rows returned by a cursor's MOREINFO="NONE"fetch command before it attempts to fetch rows from another cursor's result set. A buffer's worth of rows has been completely processed when the value returned from MOREINFO="NONE"ct_fetch is CS_END_DATA.ID="IN427237845"Cursorslanguage cursors and data modificationREMAP="BO--Body"An application can update or delete the most recently fetched row while fetching from a regular row result set. The modification is propagated back to the underlying database table.RENDERAS="SECT2"Client-Library CursorsID="IN427237846"Cursorsdeclaring Client-Library cursorsRENDERAS="SECT3"Declaring Client-Library CursorsID="IN429218047"ct_cursorct_cursorand Client-Library cursorsClient-Library cursorsREMAP="BO--Body"An application creates a Client-Library cursor by initiating a call to ID="IN427198248"CursorsCursorsand ct_cursorct_cursor
MOREINFO="NONE"ct_cursor(CS_CURSOR_DECLARE).ID="IN427198249"CursorsClient-Library cursorsÕ  use of command structuresREMAP="BO--Body"Unlike language cursors, each Client-Library cursor must be declared using a different command structure. All operations on the same Client-Library cursor, from its declaration to its de-allocation, must reference the same unique command structure.REMAP="BO--Body"The following commands use Transact-SQL to declare two Client-Library cursors and specify their cursor rows settings. The commands for each cursor use different command structures.REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"ct_cursor(cmd, CS_CURSOR_DECLARE, A, CS_NULLTERM,     cursor_body, CS_NULLTERM, CS_FOR_UPDATE);REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"ct_cursor(cmd, CS_CURSOR_ROWS, NULL, CS_UNUSED,     NULL, CS_UNUSED, 5);REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"ct_send(cmd);REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"ct_cursor(cmd2, CS_CURSOR_DECLARE, B, CS_NULLTERM,    cursor_body2, CS_NULLTERM, CS_FOR_UPDATE);REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"ct_cursor(cmd2, CS_CURSOR_ROWS, NULL, CS_UNUSED,     NULL, CS_UNUSED, 10);REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"ct_send(cmd2);REMAP="BO--Body"For detailed information about MOREINFO="NONE"ct_cursor, see the LINKEND="X36007""ct_cursor"
manual page.RENDERAS="SECT3"Cursor Result SetsID="IN427198250"CursorsClient-Library cursors and cursor result setsREMAP="BO--Body"Client-Library cursors generate cursor result sets when an application makes calls to MOREINFO="NONE"ct_cursor(CS_CURSOR_OPEN) to initiate commands to open the cursors.REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"ct_cursor(cmd, CS_CURSOR_OPEN, NULL, CS_UNUSED,    NULL, CS_UNUSED, CS_UNUSED);REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"ct_send(cmd);REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"ct_cursor(cmd2, CS_CURSOR_OPEN, NULL, CS_UNUSED,    NULL, CS_UNUSED, CS_UNUSED);REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"ct_send(cmd2);ID="IN427198251"Cursorscursor rows settingREMAP="BO--Body"The number of rows returned to Client-Library per internal fetch command is equal to the current "cursor rows" setting for the cursor: 10 for cursor A and 5 for cursor B, in this case. The application fetches the rows from Client-Library by making calls to MOREINFO="NONE"ct_fetch.ID="IN4218198252"Cursor result setsfetchingRENDERAS="SECT3"Fetching From Cursor Result SetsID="IN4218198253"Cursor result setssimultaneous fetching fromREMAP="BO--Body"An application can simultaneously fetch from multiple cursor result sets. Unlike language cursors, an application does not need to completely process the buffer's worth of rows returned on a Client-Library cursor before it fetches rows from another cursor's result set.ID="IN427198254"CursorsClient-Library cursors and data modificationREMAP="BO--Body"Also, while a language cursor can only be used to delete or update the most recently fetched row, a Client-Library cursor can be used to modify any previously fetched row. This modification is propagated back to the underlying database table.REMAP="BO--Body"For information about using Client-Library to modify previously fetched cursor rows, see the MOREINFO="NONE"ct_keydata manual page. ID="IN427198255"Cursorsinteraction between language cursors and Client-Library cursorsRENDERAS="SECT2"Language Cursor and Client-Library Cursor InteractionREMAP="BO--Body"Language cursors and Client-Library cursors can share the same connection structure. The implication of this is that whenever a language cursor sends a MOREINFO="NONE"fetch command, all other cursors (including the Client-Library cursors) sharing the same connection are blocked until the application processes the buffer's worth of regular rows returned.RENDERAS="SECT2"Where to Go for More InformationREMAP="BO--Body"For detailed information on the routines that initiate language and Client-Library cursor commands, see the manual pages for MOREINFO="NONE"ct_command and MOREINFO="NONE"ct_cursor.REMAP="BO--Body"For information on how to declare and manipulate Client-Library cursors , see the Open Client Client-Library/C Programmer's Guide.REMAP="BO--Body"For information on how cursors are implemented in 10.0 SQL Server, see the SQL Server Reference Manual.REMAP="BO--Body"For information on how cursors are supported by 10.0 Open Server, see the Open Server Server-Library Reference ManualID="IN427188356"Cursors
.REMAP="BO--Body"ID="X39013" RENDERAS="SECT1"Dynamic SQLID="IN42119923"Dynamic SQLpurposeREMAP="BO--Body"Dynamic SQL is primarily useful for precompiler support, but it can also be used by interactive applications that do either of the following:MARK="BULL" REMAP="BU--Bullet"Generate SQL statements based on information provided by an end-userAllow end-users to create whole or partial SQL statementsRENDERAS="SECT2"What is Dynamic SQL?REMAP="BO--Body"Dynamic SQL is the process of generating, preparing, and executing SQL statements at run-time.ID="IN42119924"Dynamic SQLadvantagesREMAP="BO--Body"Dynamic SQL addresses a number of issues, namely:MARK="BULL" REMAP="BU--Bullet"The need to execute SQL statements whose text is not known prior to run-time.REMAP="UN--Under"It would be difficult to anticipate all of the SQL statements that an end user might want to execute. An application can benefit from dynamically constructing SQL statements, binding variable values, and executing the statements, all at run-time.The efficiency of preparing a `generic' SQL statement once and executing it multiple times, each time changing the values of its host variables.REMAP="UN--Under"Preparing a SQL statement is analogous to compiling an application; the syntax of the SQL statement is checked and the DBMS has an opportunity to optimize the SQL statements, deciding on query plans and storing those plans in anticipation of later application execution.The advantage of referencing a prepared SQL statement with an identifier.The need to create one or more cursors at run-time to handle multiple-row access.ID="IN42119925"Dynamic SQLlimitations
ID="IN42119926"Dynamic SQLrestrictionsRENDERAS="SECT2"Limitations of Dynamic SQLREMAP="BO--Body"Dynamic SQL has some significant limitations.ID="IN42119927"Dynamic SQLlimitations:performanceRENDERAS="SECT3"PerformanceID="IN42109928"Static SQL
ID="IN4239929"SQLstatic SQLREMAP="BO--Body"Dynamic SQL generally performs poorer than static SQL, the term for SQL when it is embedded into an application. When you compile an embedded SQL application, SQL statement preparation and optimization is performed as well. The overhead incurred by these impacts the application developer, not the end-user.REMAP="BO--Body"A dynamic SQL application, on the other hand, incurs the overhead of SQL statement preparation and optimization at run-time, which affects the end-user.ID="IN421199210"Dynamic SQLlimitations:ANSI cursor restriction
ID="IN42799211"CursorsANSI restriction
ID="IN422399212"ANSI cursor restrictionRENDERAS="SECT3"ANSI Cursor RestrictionREMAP="BO--Body"A dynamic SQL application using Transact-SQL cursors or Client-Library cursors (as opposed to language cursors) is subject to the following restriction.REMAP="BO--Body"By ANSI definition, a cursor is associated with a single result set, and thus, a single SQL statement. This means that a dynamic SQL prepared statement can only be either:MARK="BULL" REMAP="BU--Bullet"A SQL MOREINFO="NONE"select statementREMAP="BO--Body"or a:MARK="BULL" REMAP="BU--Bullet"A Transact-SQL MOREINFO="NONE"execute statementREMAP="UN--Under"The stored procedure being executed can contain only a single SQL MOREINFO="NONE"select statement.ID="IN421199213"Dynamic SQLlimitations:SQL Server restrictionsRENDERAS="SECT3"SQL Server RestrictionsID="IN421199214"Dynamic SQLhow SQL Server implements it
ID="IN421099215"SQL Serverimplementation of dynamic SQLREMAP="BO--Body"SQL Server implements dynamic SQL using temporary stored procedures. A temporary stored procedure is created when a SQL statement is prepared, and destroyed when that prepared statement is de-allocated. De-allocation can occur either explicitly with a MOREINFO="NONE"ct_dynamic(CS_DEALLOC) call or implicitly when a connection is closed.REMAP="BO--Body"As a consequence of this implementation, an application accessing SQL Server and using dynamic SQL is subject to the restrictions of SQL Server stored procedures. Some of the implications of this are:MARK="BULL" REMAP="BU--Bullet"Temporary tables are destroyed when the prepared statement is de-allocated.Parameters of text and image datatypes are not supported.The maximum number of parameters supported is 255.REMAP="BO--Body"See the Transact-SQL User's Guide for a complete discussion of stored procedures.RENDERAS="SECT2"Dynamic SQL ImplementationID="IN422799216"Execute immediate operation
ID="IN421799217"Prepare operation
ID="IN421799218"Execute operationREMAP="BO--Body"There are two ways to dynamically execute SQL statements. One is to perform the prepare and execute operations in one step, and the other is to perform the prepare and execute operations separately.REMAP="BO--Body"Preparing a SQL statement consists of:MARK="BULL" REMAP="BU--Bullet"Parsing - checking the statement's syntax and verifying the names of the specified columns and tables against the system catalogOptimizing - determining the data access path (execution plan), if possibleGenerating execution codeREMAP="BO--Body"Executing a SQL statement is what actually makes things happen: rows are added by an MOREINFO="NONE"insert statement, removed by a MOREINFO="NONE"delete statement, changed by an MOREINFO="NONE"update statement, or retrieved by a MOREINFO="NONE"select statement.REMAP="BO--Body"The following sections discuss the two methods, and the circumstances in which an application would choose one method over the other.RENDERAS="SECT3"Execute ImmediateID="IN422799219"Execute immediate operationcriteriaREMAP="BO--Body"The execute immediate method performs the prepare and execute operations in one step. A dynamic SQL statement can be executed immediately if it meets the following criteria:MARK="BULL" REMAP="BU--Bullet"It does not return data (it is not a MOREINFO="NONE"select statement).It does not contain dynamic parameter markers (?'s).REMAP="UN--Under"Dynamic parameter markers act as placeholders that allow users to specify actual data to be substituted into a SQL statement at run-time.The application will execute it only once.REMAP="UN--Under"Using the execute immediate method, an application can execute a literal SQL statement more than once, but this is discouraged since it incurs the overhead associated with statement preparation each time it executes the statement.ID="IN423099220"Prepare and execute operationsRENDERAS="SECT3"Prepare and ExecuteREMAP="BO--Body"The execute and prepare method performs the prepare and execute operations separately. An application mustID="IN423099221"Prepare and execute operationscriteria
use this method if the dynamic SQL statement meets any of the following criteria:MARK="BULL" REMAP="BU--Bullet"It returns data.It contains dynamic parameter markers (?'s).REMAP="BO--Body"and it should use this method if:MARK="BULL" REMAP="BU--Bullet"The application will execute it multiple times.REMAP="UN--Under"Using the prepare and execute method, an application incurs the overhead associated with statement preparation only once: when it prepares the statement. Each execution of the statement thereafter costs nothing in terms of overhead.ID="IN423099222"Prepare and execute operationsadvantagesREMAP="BO--Body"Separating the prepare and execute operations offers an application the following advantages over the execute immediate method:MARK="BULL" REMAP="BU--Bullet"It allows MOREINFO="NONE"select statements to be executed.It increases the performance of statements which are executed more than once.It provides the application with an opportunity to describe prepared statement input values.ID="IN422799223"Execute immediate operationsteps to performRENDERAS="SECT2"Execute ImmediateREMAP="BO--Body"To execute a literal, non-query, dynamic SQL statement:NUMERATION="ARABIC" REMAP="S1--StepOne" CONTINUATION="RESTARTS" INHERITNUM="IGNORE"Store the text of the dynamic SQL statement in a character string host variable.Call MOREINFO="NONE"ct_dynamic with type as CS_EXEC_IMMEDIATE to initiate a command to execute the statement.Call MOREINFO="NONE"ct_send to send the command to the server.Call MOREINFO="NONE"ct_results and examine the value of the *result_type parameter to determine whether the command succeeded (CS_CMD_SUCCEED) or failed (CS_CMD_FAIL).ID="IN422999224"Prepare and execute operationsteps to performRENDERAS="SECT2"Prepare and ExecuteREMAP="BO--Body"Preparing and executing a dynamic SQL statement is more complex than performing an execute immediate operation. The steps are:MARK="BULL" REMAP="BU--Bullet"Prepare the dynamic SQL statement.Get a description of prepared statement input, if necessary.Get a description of prepared statement output, if necessary.Execute the prepared statement or declare and open a cursor on the prepared statement.Process results, if necessary.De-allocate the prepared statement.ID="IN421999225"Prepared statementspreparing a statement
ID="IN421199226"Dynamic SQLpreparing a statementRENDERAS="SECT3"Preparing a StatementREMAP="BO--Body"When an application prepares a dynamic SQL statement separately from executing it, these additional tasks are performed during the prepare operation:MARK="BULL" REMAP="BU--Bullet"The statement is associated with an identifier for easy access.The compiled statement is stored on the server for later execution.REMAP="BO--Body"To prepare a dynamic SQL statement:NUMERATION="ARABIC" REMAP="S1--StepOne" CONTINUATION="RESTARTS" INHERITNUM="IGNORE"Store the text of the statement in a character string host variable, for example:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"char     *query = "select type, title, price                    from titles                    where title_id = ?"REMAP="UN--Under"The SQL statement may include one or more dynamic parameter markers that act as placeholders. A placeholder is represented by a "?" character. Placeholders can be specified:MARK="DASH" REMAP="BS--BulletSub"For one or more columns in a MOREINFO="NONE"select listFor one or more values in an MOREINFO="NONE"insert statementIn the MOREINFO="NONE"set clause of an MOREINFO="NONE"update statementIn a MOREINFO="NONE"where clause of a MOREINFO="NONE"select or MOREINFO="NONE"update statementREMAP="UN--Under"At execution time, the application must substitute a value for each dynamic parameter marker.Call MOREINFO="NONE"ct_dynamic with type as CS_PREPARE to initiate a command to prepare the statement.REMAP="UN--Under"To initiate a command to prepare the above SQL statement:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"ct_dynamic(cmd, CS_PREPARE, "myid", CS_NULLTERM,    query, CS_NULLTERM);REMAP="UN--Under"To initiate a command to prepare a statement that executes a stored procedure, specify "MOREINFO="NONE"exec sp_name" as the SQL text, where MOREINFO="NONE"sp_name is the actual name of the stored procedure to be executed:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"ct_dynamic(cmd, CS_PREPARE, "myid", CS_NULLTERM,    "exec sp_2", CS_NULLTERM);Call MOREINFO="NONE"ct_send to send the command to the server.Call MOREINFO="NONE"ct_results as necessary to process the results of the command. A successful CS_PREPARE command will generate a CS_CMD_SUCCEED result.ID="IN421999227"Prepared statementsgetting a description of input parameters
ID="IN421199228"Dynamic SQLgetting a description of input parametersRENDERAS="SECT3"Getting a Description of Prepared Statement InputREMAP="BO--Body"If a SQL statement contains any dynamic parameter markers, it is often useful for an application to get a description from the server of the values to be input. This description includes the number of input values, as well as their data types, lengths, and so on. The application can then use this information to prompt the end user for input values. After prompting for input values, it can pass those values to the prepared statement just prior to executing the statement.REMAP="BO--Body"To get a description of prepared statement input:NUMERATION="ARABIC" REMAP="S1--StepOne" CONTINUATION="RESTARTS" INHERITNUM="IGNORE"Call MOREINFO="NONE"ct_dynamic with type as CS_DESCRIBE_INPUT to initiate a command to get the description.Call MOREINFO="NONE"ct_send to send the command to the server.Call MOREINFO="NONE"ct_results as necessary to process the results of the command. A CS_DESCRIBE_INPUT command generates a result set of type CS_DESCRIBE_RESULT. This result set contains no fetchable data but does contain descriptive information for each of the input values.Call MOREINFO="NONE"ct_res_info to get the number of input values. This assumes that CS_DESCRIBE_RESULT was returned, as does the following step.For each input value, call MOREINFO="NONE"ct_describe. Increment the value of the item parameter by 1 with each call.REMAP="BO--Body"Alternately, an application can use a dynamic SQL descriptor area to hold the description of the prepared statement input. If this is the case, the following steps replace those specified above: NUMERATION="ARABIC" REMAP="S1--StepOne" CONTINUATION="RESTARTS" INHERITNUM="IGNORE"Call MOREINFO="NONE"ct_dyndesc with operation as CS_ALLOC to allocate a descriptor area.Call MOREINFO="NONE"ct_dynamic with type as CS_DESCRIBE_INPUT to initiate the command to get the description.Call MOREINFO="NONE"ct_send to send the command to the server.Call MOREINFO="NONE"ct_results as necessary to process the results of the command. A CS_DESCRIBE_INPUT command generates a result set of type CS_DESCRIBE_RESULT. This result set contains no fetchable data but does contain descriptive information for each of the input values.Call MOREINFO="NONE"ct_dyndesc with operation as CS_USE_DESC to associate the prepared statement with the descriptor area allocated in step 1. This assumes that CS_DESCRIBE_RESULT was returned, as do the following two steps.Call MOREINFO="NONE"ct_dyndesc with operation as CS_GETCNT to get the number of input values.For each input value, call MOREINFO="NONE"ct_dyndesc with operation as CS_GETATT to get the value's description.REMAP="BO--Body"The first method (not using a dynamic SQL descriptor area) is recommended since performance is better and it is consistent with the way in which results are processed for non-dynamic SQL statements as well.ID="IN421999229"Prepared statementsgetting a description of output from
ID="IN421199230"Dynamic SQLgetting a description of prepared statement outputRENDERAS="SECT3"Getting a Description of Prepared Statement OutputREMAP="BO--Body"If the dynamic SQL statement is a MOREINFO="NONE"select statement and the MOREINFO="NONE"select list was not known prior to run-time, the application must get a description of the prepared statement output before processing the results.REMAP="BO--Body"For example, a forms-based application that processes interactive SQL queries needs to determine result column types and lengths in order to display output.REMAP="BO--Body"To get a description of prepared statement output columns:NUMERATION="ARABIC" REMAP="S1--StepOne" CONTINUATION="RESTARTS" INHERITNUM="IGNORE"Call MOREINFO="NONE"ct_dynamic with type as CS_DESCRIBE_OUTPUT to initiate a command to get the description.Call MOREINFO="NONE"ct_send to send the command to the server.Call MOREINFO="NONE"ct_results as necessary to process the results of the command. A MOREINFO="NONE"ct_dynamic(CS_DESCRIBE_OUTPUT) command generates a result set of type CS_DESCRIBE_RESULT. This result set contains no fetchable data but does contain descriptive information for each of the output columns.Call MOREINFO="NONE"ct_res_info to get the number of output columns. This assumes that CS_DESCRIBE_RESULT was returned, as does the following step.For each output column, call MOREINFO="NONE"ct_describe. Increment the value of the item parameter by 1 with each call.REMAP="BO--Body"Alternately, an application can use a dynamic SQL descriptor area to hold the prepared statement output. If this is the case, the following steps replace those specified above: NUMERATION="ARABIC" REMAP="S1--StepOne" CONTINUATION="RESTARTS" INHERITNUM="IGNORE"Call MOREINFO="NONE"ct_dyndesc with operation as CS_ALLOC to allocate a descriptor area.Call MOREINFO="NONE"ct_dynamic with type as CS_DESCRIBE_OUTPUT to initiate the command to get the description.Call MOREINFO="NONE"ct_send to send the command to the server.Call MOREINFO="NONE"ct_results as necessary to process the results of the command. A CS_DESCRIBE_OUTPUT command generates a result set of type CS_DESCRIBE_RESULT. This result set contains no fetchable data but does contain descriptive information for each of the output columns.Call MOREINFO="NONE"ct_dyndesc with operation as CS_USE_DESC to associate the results with the descriptor area allocated in step 1. This assumes that CS_DESCRIBE_RESULT was returned, as do the following two steps.Call MOREINFO="NONE"ct_dyndesc with operation as CS_GETCNT to get the number of output columns.For each output column, call MOREINFO="NONE"ct_dyndesc with operation as CS_GETATT to get the value's description.ID="IN421999231"Prepared statementsexecuting a prepared statement
ID="IN421199232"Dynamic SQLexecuting a prepared statementRENDERAS="SECT3"Executing a Prepared StatementREMAP="BO--Body"To execute a previously-prepared statement:NUMERATION="ARABIC" REMAP="S1--StepOne" CONTINUATION="RESTARTS" INHERITNUM="IGNORE"Call MOREINFO="NONE"ct_dynamic with type as CS_EXECUTE to initiate a command to execute the statement.Define the input values to the SQL statement by performing the following steps for each input value:MARK="DASH" REMAP="BS--BulletSub"Prompt the end-user for an input value.Call MOREINFO="NONE"ct_param to pass the input value to the SQL statement.REMAP="UN--Under"Alternately, if the application is using a dynamic SQL descriptor area, perform these steps for each input value:MARK="DASH" REMAP="BS--BulletSub"Prompt the end-user for an input value.Call MOREINFO="NONE"ct_dyndesc with operation as CS_SETATT to put the value into the descriptor area.REMAP="UN--Under"If the application is using a dynamic SQL descriptor area, then after all the input values have been defined, associate the dynamic SQL descriptor area with the prepared statement:MARK="DASH" REMAP="BS--BulletSub"Call MOREINFO="NONE"ct_dyndesc with operation as CS_USE_DESC.REMAP="UN--Under"The input values are substituted for the dynamic parameter markers.Call MOREINFO="NONE"ct_send to send the command to the server.Call MOREINFO="NONE"ct_results as necessary to process the results of the command.ID="IN421999233"Prepared statementsdeclaring a cursor on
ID="IN421199234"Dynamic SQLdeclaring a cursor on a prepared statement
ID="IN42799235"Cursorsdeclaring a Client-Library cursor on a prepared statementRENDERAS="SECT3"Declaring and Opening a Cursor on a Prepared Statement REMAP="BO--Body"Instead of executing a prepared statement, an application can declare and open a cursor on it. The prepared statement serves as the body of the cursor. When the application opens the cursor, the prepared statement is executed. Any results generated are available to the application as a cursor row result set.REMAP="BO--Body"To declare and open a cursor on a prepared statement:NUMERATION="ARABIC" REMAP="S1--StepOne" CONTINUATION="RESTARTS" INHERITNUM="IGNORE"Call MOREINFO="NONE"ct_dynamic with type as CS_CURSOR_DECLARE to initiate a command to declare a cursor.REMAP="UN--Under"Note that MOREINFO="NONE"ct_dynamic, not MOREINFO="NONE"ct_cursor, is used to declare a cursor on a prepared statement.Call MOREINFO="NONE"ct_cursor with type as CS_CURSOR_OPTION to set options for the cursor.Call MOREINFO="NONE"ct_send to send the command to the server.Call MOREINFO="NONE"ct_results as necessary to process the results of the command. Call MOREINFO="NONE"ct_cursor with type as CS_CURSOR_OPEN to initiate a command to open the cursor.Define the input values to the SQL statement by performing the following two steps for each input value:MARK="DASH" REMAP="BS--BulletSub"Prompt the end-user for an input value.Call MOREINFO="NONE"ct_param to pass the input value to the SQL statement.REMAP="UN--Under"Alternately, if the application is using a dynamic SQL descriptor area, perform the following two steps for each input value:MARK="DASH" REMAP="BS--BulletSub"Prompt the end-user for an input value.Call MOREINFO="NONE"ct_dyndesc with operation as CS_SETATT to put the value into the descriptor area.REMAP="UN--Under"To then associate the dynamic SQL descriptor area with the prepared statement:MARK="DASH" REMAP="BS--BulletSub"Call MOREINFO="NONE"ct_dyndesc with operation as CS_USE_DESC.REMAP="UN--Under"The input values are substituted for the dynamic parameter markers.Call MOREINFO="NONE"ct_send to send the command to the server.Call MOREINFO="NONE"ct_results as necessary to process the results of the command. REMAP="BO--Body"If desired, an application can batch together the commands to declare and open the cursor by eliminating the MOREINFO="NONE"ct_send and MOREINFO="NONE"ct_results calls that follow the MOREINFO="NONE"ct_cursor(CS_CURSOR_OPTION) call.RENDERAS="SECT3"Processing ResultsREMAP="BO--Body"Processing the results of a dynamic SQL statement is the same as processing the results of any other SQL statement.REMAP="BO--Body"See the MOREINFO="NONE"Results topics page, the MOREINFO="NONE"ct_results manual page, and the "Step 5: Processing Results" section of the Open Client Client-Library/C Programmer's Guide for detailed information about processing results.ID="IN421999236"Prepared statementsde-allocating
ID="IN421199237"Dynamic SQLde-allocating a prepared statementRENDERAS="SECT3"De-allocating a Prepared StatementREMAP="BO--Body"When an application is done with a prepared statement, it can de-allocate the statement and free any resources associated with it.REMAP="BO--Body"To de-allocate a prepared statement:NUMERATION="ARABIC" REMAP="S1--StepOne" CONTINUATION="RESTARTS" INHERITNUM="IGNORE"If the application used descriptor areas for the prepared statement input and output, de-allocate the descriptor areas by calling MOREINFO="NONE"dt_dyndesc with operation as CS_DEALLOC once for each descriptor area.Call MOREINFO="NONE"ct_dynamic with type as CS_DEALLOC to initiate a command to de-allocate the prepared statement.If the application declared and opened a cursor on the prepared statement, call MOREINFO="NONE"ct_cursor with type as CS_CURSOR_CLOSE and option as CS_DEALLOC to initiate a command both to close and de-allocate the cursor. Call MOREINFO="NONE"ct_send to send the command to de-allocate the statement.Call MOREINFO="NONE"ct_results as necessary to process the results of the command.ID="IN421199238"Dynamic SQLstored procedures as alternatives
ID="IN421199239"Dynamic SQLalternative toRENDERAS="SECT2"Alternatives to Dynamic SQLREMAP="BO--Body"Because of the numerous restrictions of dynamic SQL, we recommend that applications use stored procedures to accomplish the same tasks. Stored procedures offer identical functionality to dynamic SQL except for the ability to get a description of prepared statement input: creating a stored procedure is analogous to preparing a SQL statement, a stored procedure's input parameters serve the same purpose as do dynamic parameter markers, and executing a stored procedure is equivalent to executing a prepared statement.ID="IN421198340"Dynamic SQLREMAP="BO--Body"ID="IN42895641"MessagesSee Also Error and message handling
ID="IN421095642"SQL Serverhandling server messages
ID="IN421495643"Client-Libraryhandling Client-Library errors
ID="IN422694744"Error and message handlingID="X46924" RENDERAS="SECT1"Error and Message HandlingREMAP="BO--Body"All Client-Library routines return success or failure indications. It is highly recommended that applications check these return codes.REMAP="BO--Body"In addition, Client-Library applications must handle two types of error and informational messages:ID="IN421594745"Client messagesMARK="BULL" REMAP="BU--Bullet"Client-Library messages, also known as "client messages", are generated by Client-Library. They range in severity from informational messages to fatal errors.ID="IN421594746"Server messages
ID="IN421094747"SQL Serverlisting messagesServer messages are generated by the server. Server messages also range in severity from informational messages to fatal errors. SQL Server messages can be listed by executing the Transact-SQL command "select * from sysmessages". See the Open Server Server-Library Reference Manual for a list of Open Server messages.Don't confuse Client-Library and server messages with a result set of type CS_MSG_RESULT. Client-Library and server messages are the means through which Client-Library and the server communicate error and informational conditions to an application. An application accesses Client-Library and server messages either through message callback routines, or in-line, using MOREINFO="NONE"ct_diag. A message result set, on the other hand, is one of several types of result sets a server can return to an application. An application processes a result set of type CS_MSG_RESULT by calling MOREINFO="NONE"ct_res_info to get the message's id.ID="IN422694748"Error and message handlingdiscussion of callbacks versus in-line methodRENDERAS="SECT2"Two Methods of Handling MessagesREMAP="BO--Body"An application can handle Client-Library and server messages in one of two ways:MARK="BULL" REMAP="BU--Bullet"By installing callback routines to handle messagesIn-line, using the Client-Library routine MOREINFO="NONE"ct_diagID="IN42994749"Callbacksadvantages over in-line message handlingREMAP="BO--Body"The callback method has the advantages of:MARK="BULL" REMAP="BU--Bullet"Centralizing message handling code.Providing a method to gracefully handle unexpected errors. Client-Library automatically calls the appropriate message callback whenever a message is generated, so an application will not fail to trap unexpected errors. An application using only main-line error-handling logic may not successfully trap errors that have not been anticipated.ID="IN422494750"In-line message handlingadvantages over callback routinesREMAP="BO--Body"In-line message handling has the advantage of allowing an application to check for messages at particular times. For example, an application that is creating a connection might choose to wait until all connection-related commands are issued before checking for messages.REMAP="BO--Body"Most applications will use the callback method to handle messages. However, an application that is running on a platform/language combination that does not support callbacks must use the in-line method.REMAP="BO--Body"An application indicates which method it will use by calling MOREINFO="NONE"ct_callback to install message callbacks or by calling MOREINFO="NONE"ct_diag to initialize in-line message handling.ID="IN422694751"Error and message handlingon different connectionsREMAP="BO--Body"An application can use different methods on different connections. For example, an application can install message callbacks at the context level, allocate two connections, and then call MOREINFO="NONE"ct_diag to initialize in-line message handling for one of the connections. The other connection will use the default message callbacks that it picked up from its parent context. ID="IN422694752"Error and message handlingswitching between callback and in-line methodsREMAP="BO--Body"An application can switch back and forth between the in-line and the callback methods:MARK="BULL" REMAP="BU--Bullet"Installing either a client message callback or a server message callback turns off in-line message handling. Any saved messages are discarded.Likewise, calling MOREINFO="NONE"ct_diag to initialize in-line message handling de-installs a connection's message callbacks. If this occurs, the connection's first CS_GET call to MOREINFO="NONE"ct_diag will retrieve a warning message to this effect.ID="IN422694753"Error and message handlingwhen Client-Library discards message informationREMAP="BO--Body"If a callback of the proper type is not installed and in-line message handling is not enabled, Client-Library discards message information.ID="IN422694754"Error and message handlingusing callbacks to handle messagesRENDERAS="SECT2"Using Callbacks to Handle MessagesREMAP="BO--Body"An application calls MOREINFO="NONE"ct_callback to install message callbacks.REMAP="BO--Body"Client-Library stores callbacks in the CS_CONNECTION and CS_CONTEXT structures. Because of this, when a Client-Library error occurs that makes a CS_CONNECTION or CS_CONTEXTID="IN422694755"Error and message handlingwhen Client-Library can't call the client message callback
ID="IN422394756"Client message callbackwhen Client-Library fails to call it
structure unusable, Client-Library cannot call the client message callback. However, the routine that caused the error still returns CS_FAIL.REMAP="BO--Body"For more information on using callbacks to handle Client-Library and server messages, see LINKEND="X40634""Callbacks" 
and the manual page for LINKEND="X39627""ct_callback" 
. ID="IN422692957"Error and message handlingusing ct_diag to handle messages in-lineRENDERAS="SECT2"In-Line Message HandlingREMAP="BO--Body"An application calls MOREINFO="NONE"ct_diag to initialize in-line message handling for a connectionMOREINFO="NONE". A typical application calls MOREINFO="NONE"ct_diag immediately after calling MOREINFO="NONE"ct_con_alloc to allocate the connection structure.REMAP="BO--Body"An application cannot use MOREINFO="NONE"ct_diagID="IN427901158"ct_diagnot for use at the context level
at the context level. That is, an application cannot use MOREINFO="NONE"ct_diag to retrieve messages generated by routines that take a CS_CONTEXT (and no CS_CONNECTION) as a parameter. These messages are unavailable to an application that is using in-line error handling.REMAP="BO--Body"An application that is retrieving messages into a SQLCA, SQLCODE, or SQLSTATE should set the Client-Library property ID="IN4221881359"CS_EXTRA_INF propertyCS_EXTRA_INF propertyand in-line message handlingin-line message handling
CS_EXTRA_INF to CS_TRUE. See "The CS_EXTRA_INF Property," below, for more information.REMAP="BO--Body"The ID="IN4224861560"CS_DIAG_TIMEOUT propertyCS_DIAG_TIMEOUT propertyand in-line message handlingin-line message handling
CS_DIAG_TIMEOUT property controls whether Client-Library fails or retries when a Client-Library routine generates a timeout error. REMAP="BO--Body"If a Client-Library error occurs that makes a CS_CONNECTION structure unusable, MOREINFO="NONE"ct_diag returns CS_FAIL when called to retrieve information about the original error.REMAP="BO--Body"For more information on the in-line method of handling Client-Library and server messages, see the manual page for MOREINFO="NONE"ct_diag.RENDERAS="SECT2"Client-Library's Message StructuresID="IN4226861561"Error and message handlingmessage structuresREMAP="BO--Body"Client-Library uses the following structures to return message information:MARK="BULL" REMAP="BU--Bullet"The CS_CLIENTMSG structureThe CS_SERVERMSG structureThe SQLCA structureThe SQLCODE structureThe SQLSTATE structureID="IN4221841762"CS_EXTRA_INF propertyCS_EXTRA_INF propertyand in-line message handlingin-line message handlingRENDERAS="SECT2"The CS_EXTRA_INF PropertyREMAP="BO--Body"The CS_EXTRA_INF property determines whether or not Client-Library returns certain kinds of informational messages.ID="IN4215802163"SQLCA structureand CS_EXTRA_INF propertyREMAP="BO--Body"An application that is retrieving messages into a ID="IN4217762564"SQLCODE structureand CS_EXTRA_INF property
SQLCA, SQLCODEID="IN4218722965"SQLSTATE structureand CS_EXTRA_INF property
, or SQLSTATE should set the Client-Library property CS_EXTRA_INF to CS_TRUE. This is because the SQL structures require information that Client-Library does not customarily return. If CS_EXTRA_INF is not set, a loss of information will occur.REMAP="BO--Body"An application that is not using the SQL structures can also set CS_EXTRA_INF to CS_TRUE. In this case, the extra information is returned as standard Client-Library messages.REMAP="BO--Body"The additional information returned includes the number of rows affected by the most recent command.ID="IN4226722966"Error and message handlingpreventing message truncation
ID="IN4226722967"Error and message handlingsequenced messages
ID="IN4216722968"Chunked messages
ID="IN4218722969"Sequenced messages
ID="IN4223703170"CS_NO_TRUNCATE propertyand sequenced messages
ID="IN428703171"Messageschunked
ID="IN428703172"MessagessequencedID="X74900" RENDERAS="SECT2"Sequencing Long Messages REMAP="BO--Body"Message callback routines and MOREINFO="NONE"ct_diag return Client-Library and server messages in CS_CLIENTMSG and CS_SERVERMSG structures. In the CS_CLIENTMSG structure, the message text is stored in the msgstring field. In the CS_SERVERMSG structure, the message text is stored in the text field. Both msgstring and text are ID="IN4219663573"CS_MAX_MSG constantCS_MAX_MSG
CS_MAX_MSG bytes long.REMAP="BO--Body"If a message longer than CS_MAX_MSG - 1 bytes is generated, Client-Library's default behavior is to truncate the message. However, an application can use the CS_NO_TRUNCATE property to tell Client-Library to "sequence" long messages instead of truncating them. REMAP="BO--Body"When Client-Library is sequencing long messages, it uses as many CS_CLIENTMSG or CS_SERVERMSG structures as necessary to return the full text of a message. The message's first CS_MAX_MSG bytes are returned in one structure, its second CS_MAX_MSG bytes in a second structure, and so forth.REMAP="BO--Body"Client-Library null terminates only the last chunk of a message. If a message is exactly CS_MAX_MSG bytes long, the message is returned in two chunks: the first containing CS_MAX_MSG bytes of the message and the second containing a null terminator.REMAP="BO--Body"If an application is using callback routines to handle messages, Client-Library calls the callback routine once for each message chunk.REMAP="BO--Body"If an application is using MOREINFO="NONE"ct_diag to handle messages, it must call MOREINFO="NONE"ct_diag once for each message chunk.The ID="IN4215643774"SQLCA structureno support for sequenced messages
SQLCA, ID="IN4217623975"SQLCODE structureno support for sequenced messages
SQLCODE, and ID="IN4218604176"SQLSTATE structureno support for sequenced messages
SQLSTATE structures do not support sequenced messages. An application cannot use these structures to retrieve sequenced messages. Messages that are too long for these structures are truncated.Operating system messages, if any, are reported via the osstring field of the CS_CLIENTMSGID="IN4225604177"Operating system messagesnot sequenced
ID="IN4226604178"Error and message handlingoperating system messages
structure. Client-Library does not sequence operating system messages.ID="IN4218604179"Sequenced messagesmessage structure fieldsRENDERAS="SECT3"Message Structure Fields for Sequenced MessagesMARK="BULL" REMAP="BU--Bullet"The status field in the CS_CLIENTMSG and CS_SERVERMSG structures indicates whether the structure contains a whole message or a chunk of a message. REMAP="UN--Under"The following table lists status values that are related to sequenced messages:TOCENTRY="1"LBL="Table 2-18: "status values for sequenced messagesCOLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="127*"COLNAME="C2" COLWIDTH="232*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Symbolic Value:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FIRST_CHUNKCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The message text is the first chunk of the message.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_LAST_CHUNKCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The message text is the last chunk of the message.MARK="DASH" REMAP="BS--BulletSub"If CS_FIRST_CHUNK and CS_LAST_CHUNK are both on, then the message text in the structure is the entire message.If neither CS_FIRST_CHUNK nor CS_LAST_CHUNK is on, then the message text in the structure is a middle chunk.The msgstringlen field in the CS_CLIENTMSG structure and the textlen field in the CS_SERVERMSG structure always reflect the length of the current message chunk. All other fields in the CS_CLIENTMSG and CS_SERVERMSG are repeated with each message chunk.ID="IN4219604180"Extended error datasequenced messages
ID="IN4218604181"Sequenced messagesextended error dataRENDERAS="SECT3"Sequenced Messages and Extended Error DataREMAP="BO--Body"If a sequenced server message has extended error data associated with it, an application can retrieve the extended error data while processing any single chunk of the sequenced message. Once the application has retrieved the extended error data, however, it is no longer available.REMAP="BO--Body"For more information on extended error data, see LINKEND="X78290""Extended Error Data" 
.ID="IN427584382"ct_diagsequenced messages
ID="IN4218564583"Sequenced messagesSequenced messagesand ct_diagct_diagRENDERAS="SECT3"Sequenced Messages and ct_diagREMAP="BO--Body"If an application is using sequenced error messages, MOREINFO="NONE"ct_diag acts on message chunks instead of messages. This has the following effects:MARK="BULL" REMAP="BU--Bullet"AMOREINFO="NONE" ct_diag(CS_GET) call with index i returns the i'th message chunk, not the i'th message.A MOREINFO="NONE"ct_diag(CS_MSGLIMIT) call limits the number of chunks, not the number of messages, that Client-Library will store.A MOREINFO="NONE"ct_diag(CS_STATUS) call returns the number of currently-stored chunks, not the number of currently-stored messages.ID="IN4215564584"Server messagesextended error data
ID="IN4219564585"Extended error dataID="X78290" RENDERAS="SECT2"Extended Error DataREMAP="BO--Body"Some server messages have "extended error data" associated with them. Extended error data is simply additional information about the error.ID="IN4210564586"SQL Serverextended error dataREMAP="BO--Body"For SQL Server messages, the additional information is most typically which column or columns provoked the error. REMAP="BO--Body"Client-Library makes extended error data available to an application in the form of a parameter result set, where each result item is a piece of extended error data. A piece of extended error data can be named, and can be of any datatype.REMAP="BO--Body"An application can retrieve extended error data but is not required to do so.ID="IN4219564587"Extended error databenefits ofRENDERAS="SECT3"What's Extended Error Data Good For?REMAP="BO--Body"Applications that allow end-users to enter or edit data often need to report errors to their users at the column level. The standard server message mechanism, however, makes column-level information available only within the text of the server message. Extended error data provides a means for applications to conveniently access column-level information.REMAP="BO--Body"For example, imagine an application that allows end-users to enter and edit data in the titleauthor table in the pubs2 database. titleauthor uses a key composed of two columns, au_id and title_id. Any attempt to enter a row with an au_id and title_id that match an existing row will cause a "duplicate key" message to be sent to the application. REMAP="BO--Body"On receiving this message, the application needs to identify the problem column or columns to the end-user, so that the user can correct them. This information is not available in the duplicate key message, except in the message text. The information is available, however, as extended error data.ID="IN4219564588"Extended error datahow to tell if availableRENDERAS="SECT3"How Can an Application Tell if Extended Error Data is Available?REMAP="BO--Body"When Client-Library returns standard server message information to an application in a CS_SERVERMSG structure, it sets the CS_HASEED bit of the status field of the CS_SERVERMSG structure if extended error data is available for the message.REMAP="BO--Body"Extended error data is returned to an application in the form of a parameter result set that is available on a special CS_COMMAND structure that Client-Library provides.REMAP="BO--Body"To retrieve extended error data, an application processes the parameter result set.ID="IN4219564589"Extended error dataExtended error dataand server message callbacksserver message callbacks
ID="IN4223564590"Server message callbackextended error dataRENDERAS="SECT3"Server Message Callbacks and Extended Error DataREMAP="BO--Body"Within a server message callback routine, an application retrieves the CS_COMMAND with the extended error data by calling MOREINFO="NONE"ct_con_props with property as CS_EED_CMD:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"CS_RETCODE      ret;CS_COMMAND      *eed_cmd;CS_INT          outlen;REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"ret = ct_con_props(connection, CS_GET, CS_EED_CMD,    &eed_cmd, CS_UNUSED, &outlen);REMAP="BO--Body"MOREINFO="NONE"ct_con_props sets eed_cmd to point to the CS_COMMAND on which the extended error data is available.REMAP="BO--Body"Once it has the CS_COMMAND, the callback routine processes the extended error data as a normal parameter result set, calling MOREINFO="NONE"ct_res_info,MOREINFO="NONE" ct_describe, MOREINFO="NONE"ct_bind, MOREINFO="NONE"ct_fetch, and MOREINFO="NONE"ct_get_data to describe, bind, and fetch the parameters. It is not necessary for the callback routine to callMOREINFO="NONE" ct_results.ID="IN4219564591"Extended error datain-line error handling
ID="IN4224564592"In-line message handlingextended error dataRENDERAS="SECT3"In-Line Error Handling and Extended Error DataID="IN4226564593"Error and message handlingextended error dataREMAP="BO--Body"An application that is handling server messages in-line retrieves the CS_COMMAND with the extended error data by calling MOREINFO="NONE"ct_diag with operation as CS_EED_CMD:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"CS_RETCODE      ret;CS_COMMAND      *eed_cmd;CS_INT          index;REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"ret = ct_diag (connection, CS_EED_CMD,    CS_SERVERMSG_TYPE, index, &eed_cmd);REMAP="BO--Body"In this call, type must be CS_SERVERMSG_TYPE and index must be the index of the message for which extended error data is available. MOREINFO="NONE"ct_diag sets eed_cmd to point to the CS_COMMAND on which the extended error data is available.REMAP="BO--Body"Once it has the CS_COMMAND, the application processes the extended error data as a normal parameter result set, calling MOREINFO="NONE"ct_res_info,MOREINFO="NONE" ct_describe, MOREINFO="NONE"ct_bind, MOREINFO="NONE"ct_fetch, and MOREINFO="NONE"ct_get_data to describe, bind, and fetch the parameters. It is not necessary for the application to call MOREINFO="NONE"ct_results.ID="IN427564594"Serverstransaction states
ID="IN4210564595"SQL Servertransaction states
ID="IN4218564596"Transaction statesID="X41110" RENDERAS="SECT2"Server Transaction StatesREMAP="BO--Body"Server transaction state information is useful when an application needs to determine the outcome of a transaction.REMAP="BO--Body"The following table lists the symbolic values that represent transaction states:TOCENTRY="1"LBL="Table 2-19: " ID="X76523"Transaction statesCOLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="135*"COLNAME="C2" COLWIDTH="225*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Symbolic Value:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRAN_IN_PROGRESSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A transaction is in progress.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRAN_COMPLETEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The most recent transaction completed 
successfully.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRAN_STMT_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The most-recently-executed statement in the 
current transaction failed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRAN_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The most recent transaction failed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRAN_UNDEFINEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A transaction state is not currently defined.ID="IN4218564597"Transaction statesretrieving in main-line code
ID="IN4210564598"Retrievingtransaction states:in main-line code
ID="IN4214564599"Main-line coderetrieving transaction statesRENDERAS="SECT3"Retrieving Transaction States in Main-Line CodeREMAP="BO--Body"In main-line code, an application retrieves a transaction state by calling MOREINFO="NONE"ct_res_info with type as CS_TRANS_STATE:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"CS_RETCODE      ret;CS_INT          outlen;CS_INT          trans_state;REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"ret = ct_res_info (cmd, CS_TRANS_STATE,    &trans_state, CS_UNUSED, outlen)REMAP="BO--Body"MOREINFO="NONE"ct_res_info sets trans_state to one of the symbolic values listed in LINKEND="X76523"Table 2-19: Transaction states
.ID="IN42185645100"Transaction stateswhen information is availableREMAP="BO--Body"Transaction state information is available only for CS_COMMAND structures with pending results or an open cursor. That is, transaction state information is available if an application's last call to MOREINFO="NONE"ct_results returned CS_SUCCEED.REMAP="BO--Body"Transaction state information is guaranteed to be correct only after MOREINFO="NONE"ct_results sets *result_type to CS_CMD_DONE, CS_CMD_SUCCEED, or CS_CMD_FAIL.ID="IN42185645101"Transaction statesretrieving in a server message callback
ID="IN42105645102"Retrievingtransaction states:in a server message callback
ID="IN42235645103"Server message callbackretrieving transaction statesRENDERAS="SECT3"Retrieving Transaction States in a Server Message CallbackREMAP="BO--Body"An application can retrieve transaction states inside a server message callback only if extended error data is available.REMAP="BO--Body"Within a server message callback, Client-Library indicates that extended error data is available by setting the CS_HASEED bit of the status field of the CS_SERVERMSG structure describing the message.REMAP="BO--Body"If extended error data is available, the application can retrieve the current transaction state by:NUMERATION="ARABIC" REMAP="S1--StepOne" CONTINUATION="RESTARTS" INHERITNUM="IGNORE"Retrieving the CS_COMMAND with the extended error data by calling MOREINFO="NONE"ct_con_props with property as CS_EED_CMD.Calling MOREINFO="NONE"ct_res_info with type as CS_TRANS_STATE. MOREINFO="NONE"ct_res_info sets its *buffer parameter to one of the symbolic values listed in LINKEND="X76523"Table 2-19: Transaction states
. ID="IN42265546104"Error and message handlingREMAP="BO--Body"ID="IN42165546105"Example programs
ID="IN4285546106"ProgramsexampleRENDERAS="SECT1"Example ProgramsID="IN42145546107"Client-Libraryexample programsREMAP="BO--Body"The following example programs and header files are installed with Client-Library. Each file contains a header describing the file's contents and purpose. COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="81*"COLNAME="C2" COLWIDTH="360*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Example 
ProgramCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DescriptionVALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"blktxt.cCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Uses the bulk copy routines to copy static data to a table.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"compute.cCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Shows how to process compute results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"csr_disp.cCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Demonstrates the use of a read-only cursor.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ex_alib.cex_amain.cCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A collection of routines which form an example of how to 
write an asynchronous layer on top of Client-Library.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"example.hCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A header file for the Client-Library example programs.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"exasync.hCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A header file for the constants and data structures in ex_alib.c 
and ex_amain.c.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"exutils.cCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Contains utility routines used by all of the other sample 
programs, and demonstrates how an application can hide 
some of the implementation details of Client-Library from 
higher-level programs.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"exutils.hCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A header file for the utility functions in exutils.c.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"getsend.cCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Shows how to retrieve and update text data.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"i18n.cCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Demonstrates some of the international features available in 
Client-Library.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"rpc.cCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Illustrates sending an RPC command to a server and then 
processing the row, parameter, and status results returned 
from the remote procedure.REMAP="BO--Body"Before running an example program:MARK="BULL" REMAP="BU--Bullet"Set the $SYBASE environment variable, or the SYBASE logical for the VMS platform, to indicate the sybase directorySet the $SYBPLATFORM environment variable to indicate the platform on which the example will run (for example, sun4, sun_svr4, hp800, rs6000, ncr, axposf)Set the DSQUERY environment variable to indicate the server to which the program will connect.Assign valid username and password values in the example.h header file for all but the asynchronous example programs.Install the pubs2 database on the server, for those example programs which require access to pubs2 objects.REMAP="UN--Under"Refer to the appropriate example program's header to find out which database and table(s) the program will be accessing.RENDERAS="SECT2"Client-Library Routines in Example ProgramsREMAP="BO--Body"The table below lists Client-Library and CS-Library routines along with example programs that demonstrate their use:COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="99*"COLNAME="C2" COLWIDTH="360*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"RoutineCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Example Program(s)VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"blk_allocCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"blktxt.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"blk_bindCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"blktxt.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"blk_doneCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"blktxt.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"blk_dropCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"blktxt.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"blk_initCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"blktxt.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"blk_rowxferCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"blktxt.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"blk_textxferCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"blktxt.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"cs_configCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"i18n.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"cs_convertCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"exutils.c, i18n.c, rpc.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"cs_ctx_allocCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ex_amain.c, exutils.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"cs_ctx_dropCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ex_amain.c, exutils.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"cs_loc_allocCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"i18n.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"cs_loc_dropCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"i18n.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"cs_localeCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"i18n.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"cs_set_convertCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"i18n.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"cs_setnullCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"i18n.c, rpc.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"cs_will_convertCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"exutils.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_bindCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"compute.c, ex_alib.c, exutils.c, getsend.c, i18n.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_callbackCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ex_alib.c, ex_amain.c, exutils.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancelCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ex_alib.c, ex_amain.c, exutils.c, getsend.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_closeCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ex_amain.c, exutils.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cmd_allocCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"compute.c, csr_disp.c, ex_alib.c, exutils.c, getsend.c, i18n.c, 
rpc.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cmd_dropCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"compute.c, csr_disp.c, ex_alib.c, exutils.c, i18n.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cmd_propsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ex_alib.c, rpc.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_commandCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"compute.c, ex_alib.c, exutils.c, getsend.c, i18n.c, rpc.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_compute_infoCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"compute.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_con_allocCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"blktxt.c, ex_amain.c, exutils.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_con_dropCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"blktxt.c, ex_amain.c, exutils.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_con_propsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"blktxt.c, ex_alib.c, ex_amain.c, exutils.c, rpc.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_configCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"exutils.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_connectCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"blktxt.c, ex_amain.c, exutils.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cursorCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"csr_disp.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_debugCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ex_alib.c, ex_amain.c, exutils.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_describeCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"compute.c, ex_alib.c, exutils.c, getsend.c, i18n.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_exitCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ex_amain.c, exutils.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_fetchCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"compute.c, ex_alib.c, exutils.c, getsend.c, i18n.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_get_dataCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"getsend.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_initCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ex_amain.c, exutils.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_paramCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"rpc.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_pollCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ex_amain.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_res_infoCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"compute.c, ex_alib.c, exutils.c, i18n.c, rpc.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_resultsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"compute.c, csr_disp.c, ex_alib.c, exutils.c, getsend.c, i18n.c, 
rpc.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_sendCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"compute.c, csr_disp.c, ex_alib.c, exutils.c, getsend.c, i18n.c, 
rpc.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_send_dataCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"getsend.cCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_wakeupCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ex_alib.cID="IN42125546108"Header filesRENDERAS="SECT1"Header FilesID="IN42125348109"Header filesctpublic.hREMAP="BO--Body"The header file ctpublic.h is required in all application source files that contain calls to Client-Library.REMAP="BO--Body"ID="IN42225150110"ctpublic.h header file
ctpublic.h includes:MARK="BULL" REMAP="BU--Bullet"Definitions of symbolic constants used by Client-Library routines.Declarations for Client-Library routines.ID="IN42124952111"Header filescspublic.h
cspublic.hID="IN42224754112"cspublic.h header file
, the CS-Library header file. cspublic.h includes:MARK="DASH" REMAP="BS--BulletSub"Definitions of common client/server symbolic constants.Typedefs for common client/server structures.Declarations for CS-Library routines.cstypes.h, which contains typedefs for Client-Library datatypes.ID="IN42124556113"Header filescstypes.hID="IN42214358114"cstypes.h header filesqlca.h, which contains a typedef for the SQLCA structure.ID="IN42124160115"Header filessqlca.hID="IN42193962116"sqlca.h header filecsconfig.h, which contains platform-dependent datatypes and definitions.ID="IN42213467119"International supportID="IN42123764117"Header filescsconfig.hID="IN42223566118"csconfig.h header fileID="X79509" RENDERAS="SECT1"International SupportID="IN42183467120"Locale informationREMAP="BO--Body"Client-Library provides support for international applications by allowing them to localize.
An application that is localized typically:ID="IN42253467121"National language supportID="IN4293467122"Languagessetting nationalID="IN42193467123"Collating sequencesspecifyingID="IN42143467124"Character setsspecifyingID="IN4273467125"Formatsusing national formats for datetime, money, and numeric valuesID="IN42123467126"ApplicationslocalizedMARK="BULL" REMAP="BU--Bullet"Uses a local language for Client-Library and SQL Server messagesUses local datetime formatsUses a specific character set and collating sequence (also called "sort order") when converting or comparing stringsID="IN42123467127"Localizationdefault valuesREMAP="BO--Body"On most platforms, Client-Library uses environment variables to determine the default localization values than an application will use. If these default values meet an application's needs, it does not have to localize further.ID="IN42123269128"LocalizationCS_LOCALE structureREMAP="BO--Body"If the default values don't meet an application's needs, it can use a CS_LOCALEID="IN42123269129"Localizationsetting custom values
structure to set custom localization values at the context, connection, or data element levels. For information on how to use a CS_LOCALE structure, see LINKEND="X24363""Using a CS_LOCALE Structure" 
.Platform-specific localization issues are discussed in the International Support chapter of the Open Client/Server Supplement. You must read this chapter in order to understand Client-Library's localization mechanism and how environment variables affect localization. ID="IN42193071130"CS_LOCALE structurewhen to useRENDERAS="SECT2"When Does an Application Need to Use a CS_LOCALE?REMAP="BO--Body"An application needs to use a CS_LOCALE structure if Client-Library's default localization values don't meet its needs. For information on how Client-Library sets up default localization values, see the Open Client/Server Supplement for your platform.REMAP="BO--Body"Typically, an application needs to use a CS_LOCALE if it will be working in a language or character set that differs from the predominant local language and character set.REMAP="BO--Body"For example:MARK="BULL" REMAP="BU--Bullet"An application running in a German environment might need to use a CS_LOCALE in order to receive Client-Library error messages in French.An English gateway application that supports Danish clients might need to use a CS_LOCALE.ID="X24363" RENDERAS="SECT2"Using a CS_LOCALE StructureREMAP="BO--Body"A CS_LOCALE structure defines localization values. An application can use a CS_LOCALE structure to define custom localization values at the context, connection, and data element levels.REMAP="BO--Body"To do this, an application:NUMERATION="ARABIC" REMAP="S1--StepOne" CONTINUATION="RESTARTS" INHERITNUM="IGNORE"Calls MOREINFO="NONE"cs_loc_alloc to allocate a CS_LOCALE structure. Calls MOREINFO="NONE"cs_locale to load the CS_LOCALE with custom localization values. Depending on what parameters it is called with, MOREINFO="NONE"cs_locale may search for the LC_ALL, LC_CTYPE, LC_COLLATE, LC_MESSAGE, LC_TIME or LANG environment variables.Uses the CS_LOCALE. An application can:MARK="DASH" REMAP="BS--BulletSub"Call MOREINFO="NONE"cs_config with property as CS_LOC_PROP to copy the custom localization values into a context structure.Call MOREINFO="NONE"ct_con_props with property as CS_LOC_PROP to copy the custom localization values into a connection structure. Note that because CS_LOC_PROP is a login property, an application cannot change its value after a connection is open.Supply the CS_LOCALE as a parameter to a routine that accepts custom localization values (MOREINFO="NONE"cs_strcmp, MOREINFO="NONE"cs_time).Include the CS_LOCALE in a CS_DATAFMT structure describing a destination program variable (MOREINFO="NONE"cs_convert, MOREINFO="NONE"ct_bind).Calls MOREINFO="NONE"cs_loc_drop to de-allocate the CS_LOCALE.ID="IN42123071131"LocalizationLocalizationat the context levelcontext levelRENDERAS="SECT3"Context-Level LocalizationREMAP="BO--Body"Context-level localization values define the localization for an Open Client context.REMAP="BO--Body"When an application allocates a CS_CONTEXT structure, CS-Library assigns default localization values to the new context. On most platforms, environment variables determine the default values. For specific information on how default localization values are assigned on your platform, see the Open Client/Server Supplement.REMAP="BO--Body"Because default localization values are always defined, an application only needs to define new context-level localization values if the default values are not acceptable.ID="IN42123071132"LocalizationLocalizationat the connection levelconnection levelRENDERAS="SECT3"Connection-Level LocalizationREMAP="BO--Body"Connection-level localization values define the localization for a specific client-server connection.ID="IN42123071133"Localizationinheriting values from the parent contextREMAP="BO--Body"A new connection inherits default localization values from its parent context, so an application needs to define new localization values for a connection only if the parent context's values are not acceptable.REMAP="BO--Body"When an application calls MOREINFO="NONE"ct_connect to open a connection, the server determines whether or not it can support the connection's language and character set. If it cannot, the connection attempt fails.This functionality is very different from that of DB-Library, where a connection uses SQL Server's default national language unless the application calls DBSETLNATLANG to set the national language name.ID="IN42123071134"LocalizationLocalizationat the data element leveldata element levelRENDERAS="SECT3"Data-Element-Level LocalizationREMAP="BO--Body"A data-element-level CS_LOCALE defines localization values for a specific data element, for example, a routine parameter or bind variable.REMAP="BO--Body"An application needs to define localization values at the data element level only if the existing connection's values are not acceptable.REMAP="BO--Body"For example, suppose a connection is using an English locale (us_english language, iso_1 character set, and appropriate datetime formats), but the connection needs to display a datetime result column using French day and month names.REMAP="BO--Body"The application can:MARK="BULL" REMAP="BU--Bullet"Load a CS_LOCALE with French datetime formats.Call MOREINFO="NONE"ct_bind to bind the result column to a character variable. The CS_DATAFMT structure that describes the bind variable must reference the French CS_LOCALE. REMAP="BO--Body"When the application calls MOREINFO="NONE"ct_fetch, the datetime value in the result column is automatically converted to a character string containing French day and month names and copied into the bound variable.ID="IN42213071135"International supportdefault behavior
ID="IN42123071136"Localizationwhere does Client-Library look for values?RENDERAS="SECT2"Where Does Client-Library Look for Localization Information?REMAP="BO--Body"When determining which localization values to use, Client-Library starts at the data element level and proceeds up. The order of precedence is:NUMERATION="ARABIC" REMAP="S1--StepOne" CONTINUATION="RESTARTS" INHERITNUM="IGNORE"Data element localization values:MARK="DASH" REMAP="BS--BulletSub"The CS_LOCALE associated with the CS_DATAFMT structure that describes a data element, or The CS_LOCALE passed to a routine as a parameter.Connection structure localization values.Context structure localization values.REMAP="BO--Body"Context-level localization values are always defined, because when an application allocates a context structure, CS-Library provides the new context with default localization values.REMAP="BO--Body"(After allocating a context, an application can change its localization values by calling MOREINFO="NONE"cs_loc_alloc, MOREINFO="NONE"cs_locale, and MOREINFO="NONE"cs_config.)ID="X78928" RENDERAS="SECT2"The Locales FileREMAP="BO--Body"The SYBASEID="IN42123071137"Locales filewhat it does
locales file associates locale names with languages, character sets, and sort orders. Open Client/Server products use the locales file when loading localization information. REMAP="BO--Body"The locales file directs Open Client/Server products to language, character set, and sort order names, but does not contain actual localized messages or character set information. REMAP="BO--Body"For more information on the locales file, see the Open Client/Server Supplement.ID="IN42123071138"Locales fileentriesRENDERAS="SECT3"Locales File EntriesREMAP="BO--Body"The locales file has platform-specific sections, each of which contains entries of the form:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"locale = locale_name, language, charset, sortorderREMAP="BO--Body"sortorder is an optional field. If not specified, the sort order for the specified locale defaults to binary.REMAP="BO--Body"Each entry defines a locale name by associating it with a language, character set, and sort order. REMAP="BO--Body"For example, a section of the locales file might contain the following entries:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"locale = default, us_english, iso_1, dictionarylocale = fr, french, iso_1, noaccentslocale = C.japanese, us_english, eucjisREMAP="BO--Body"These entries indicate that:MARK="BULL" REMAP="BU--Bullet"When a locale name of "default" is specified, a language of "us_english", a character set of "iso_1", and a sort order of "dictionary" should be used.When a locale name of "fr" is specified, a language of "french", a character set of "iso_1", and a sort order of "noaccents" should be used. When a locale name of "C.japanese" is specified, a language of "us_english", a character set of "eucjis", and a sort order of "binary" (the default sort order) should be used.ID="IN42113071139"Locale namepredefinedRENDERAS="SECT3"Predefined Locale NamesREMAP="BO--Body"SYBASE pre-defines some locale names by including entries for them in the locales file. If these entries don't meet your needs, you can either modify them or add additional entries that define new locale names.ID="IN42123071140"Locales filepredefined locale namesRENDERAS="SECT3"MOREINFO="NONE"cs_locale and the Locales FileREMAP="BO--Body"Before using a CS_LOCALEID="IN42122873141"LocalizationLocalizationand cs_localecs_locale
structure to set custom localization values for a context, connection, or data element, a Client-Library application must call MOREINFO="NONE"cs_locale to load the CS_LOCALE with the desired localization values.REMAP="BO--Body"In loading the CS_LOCALE, MOREINFO="NONE"cs_locale:NUMERATION="ARABIC" REMAP="S1--StepOne" CONTINUATION="RESTARTS" INHERITNUM="IGNORE"Determines what to use as a locale name:MARK="DASH" REMAP="BS--BulletSub"If MOREINFO="NONE"cs_locale's buffer parameter is supplied, this is the locale name.If MOREINFO="NONE"cs_locale's buffer parameter is NULL, MOREINFO="NONE"cs_locale performs a platform-specific operating system search for a locale name. For information on this search, see the Open Client/Server Supplement for your platform.Looks the locale name up in the locales file to determine which language, character set, and sort order are associated with it.Loads the type of information specified by the type parameter into the CS_LOCALE. For example, if type is CS_LC_CTYPE, MOREINFO="NONE"cs_locale loads character set information. If type is CS_LC_MESSAGE, MOREINFO="NONE"cs_locale loads message information.ID="IN42212774142"International supportREMAP="UN--Under"RENDERAS="SECT1"Logical Sequence of CallsREMAP="BO--Body"Client-Library uses state machines to define and enforce the order in which applications call Client-Library routines. This defined order is known as `a logical sequence'. For example, an application must send a SQL query statement to a server before it can execute the statement, and it must execute a statement before it can fetch rows from the statement's result set.RENDERAS="SECT2"Client-Library State MachinesREMAP="BO--Body"The application programming interface (API) layer of Client-Library consists of three state machines, each corresponding to one of the three basic control structures: CS_CONTEXT, CS_CONNECTION, or CS_COMMAND. See chapter 3 of the Open Client Client-Library/C Programmer's Guide for a discussion of the basic control structures.REMAP="BO--Body"At the context level, an application sets up its environment: allocating one or more context structures, setting CS-Library properties for the contexts, initializing Client-Library, and setting Client-Library properties for the contexts.REMAP="BO--Body"At the connection level, an application connects to a server: allocating one or more connection structures, setting properties for the connections, opening the connections, and setting any server options for the connections. An application can allocate a connection structure only after a context structure has been allocated.REMAP="BO--Body"At the command level, an application allocates one or more command structures, sends commands, and processes results. An application can allocate a command structure only after a connection structure has been allocated.RENDERAS="SECT2"Command Level Sequence of CallsREMAP="BO--Body"It is at the command level that the logical sequence of calls becomes complex. This is due to the number of routines that are managed at the command level, compared to the number managed at the context and connection levels.REMAP="BO--Body"Client-Library's command state machine gets help from two other state tables when it attempts to verify that a call to a particular routine is permitted. These are the initiated commands state table and the result types state table.RENDERAS="SECT3"Commands State TableREMAP="BO--Body"The commands table defines `states' in which an application can be. For example, it defines a Command Sent state which indicates that the last thing an application did was send a command to a server (via MOREINFO="NONE"ct_send).REMAP="BO--Body"The commands table also maps each state to valid Client-Library routines that an application can call while in that state. For example, in the Command Sent state, an application can cancel the command or the result set, get or set command structure properties, perform operations on a dynamic SQL descriptor area, receive a TDS packet from the server, or set up results for processing.REMAP="BO--Body"See LINKEND="X78115""Command States" 
for a detailed description of each of the command states. See LINKEND="X59016""Callable Routines in Each Command State" 
for a mapping of command states with Client-Library routines.RENDERAS="SECT3"Initiated Commands State TableREMAP="BO--Body"The initiated commands table focuses on routines that initiate and set up commands to be sent to a server (MOREINFO="NONE"ct_command, MOREINFO="NONE"ct_cursor, MOREINFO="NONE"ct_dynamic, MOREINFO="NONE"ct_param, and so on). It provides a finer level of enforcement than is possible with the commands table.REMAP="BO--Body"For example, the command state machine ensures that MOREINFO="NONE"ct_param is called only after a command has been initiated. However, it cannot prevent an application from calling MOREINFO="NONE"ct_param when the initiated command does not take parameters (as in the case of a MOREINFO="NONE"ct_cursor(CS_CURSOR_CLOSE)). It is in cases like these that the initiated commands table enforces the logical sequence of calls.REMAP="BO--Body"As another example, assume that a Client-Library cursor is declared using the cmd1 CS_COMMAND structure. After the cursor declare command is sent to the server and the results processed, the state machine is back in an Idle state:FLOAT="0"FORMAT="UNKNOWN" FILEREF="fig1_1aa.xwd"REMAP="BO--Body"From an Idle state, the command state machine permits an application to initiate a new command. This means that it cannot prevent an application from declaring a second cursor using the same CS_COMMAND structure that it used to declare the first cursor (cmd1).REMAP="BO--Body"The initiated commands table, however, keeps track of the state of a cursor on a command handle. It recognizes that if a cursor has been previously declared using a particular CS_COMMAND structure, a second attempt to declare a cursor using the same CS_COMMAND structure is illegal.REMAP="BO--Body"See LINKEND="X74631""Initiated Commands" 
for a detailed description of each of the initiated command states. See LINKEND="X28854""Callable Routines for Initiated Commands" 
for a mapping of initiated command states with Client-Library routines.RENDERAS="SECT3"Result Types State TableREMAP="BO--Body"The result types table focuses on routines that return information about result sets. The command state machine defines states (like Fetchable Results and Fetchable Cursor Results) which indicate that results are available. The result types table goes a step farther by indicating the type of available results.REMAP="BO--Body"This information is important because certain routines only make sense for certain result types. For example, calling MOREINFO="NONE"ct_compute_info is only logical when compute results are available, and calling MOREINFO="NONE"ct_br_column is only logical when regular row results are available. It is in cases like these that the result types table enforces the logical sequence of calls.REMAP="BO--Body"See LINKEND="X98861""Result Types" 
for a detailed description of each of the result type states. See LINKEND="X97530""Callable Routines for Each Result Type" 
for a mapping of result type states with Client-Library routines.RENDERAS="SECT3"SummaryREMAP="BO--Body"This diagram shows how the state tables work together:FLOAT="0"FORMAT="UNKNOWN" FILEREF="fig2_1.xwd"REMAP="BO--Body"Be aware that if there are multiple command structures sharing the same connection, REMAP="BO--Body"The information that follows is intended to serve as a reference for valid Client-Library application behavior. Use it when you want to verify that a particular sequence of routine calls is valid or when you need to know `where to go from here.' The important point to remember is that Client-Library enforces the logical sequence of calls for you. It returns descriptive error messages at run-time if an application has not called routines in a logical sequence.ID="X78115" RENDERAS="SECT2"Command StatesREMAP="BO--Body"Client-Library keeps track of a command's current state. A command can be in any one of the following states.TOCENTRY="1"LBL="Table 2-20: "Command states COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="108*"COLNAME="C2" COLWIDTH="252*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Command State:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"What it Indicates:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"IdleCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The application either: 1) hasn't yet initiated a 
command, 2) has completely processed the results of 
the last command, 3) has fetched all cursor rows but 
has not closed the Client-Library cursor, or 4) has 
closed a Client-Library cursor that is still associated 
with unprocessed results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Command 
initiatedCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The application called MOREINFO="NONE"ct_command, MOREINFO="NONE"ct_cursor, or 
MOREINFO="NONE"ct_dynamic to initiate a command, but it hasn't yet sent 
it to the server.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Command 
sentCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The application called MOREINFO="NONE"ct_send to send a command to 
the server, but it hasn't yet called MOREINFO="NONE"ct_results to set up 
result data for processing.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Non-fetchable
results availableCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The application called MOREINFO="NONE"ct_results and the result set 
contains no actual result data. Additional calls to 
MOREINFO="NONE"ct_results are necessary.
or:
The application called MOREINFO="NONE"ct_fetch which returned 
CS_END_DATA.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ANSI-style cursor 
end-dataCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The application called MOREINFO="NONE"ct_fetch which returned 
CS_END_DATA and the CS_ANSI_BINDS property is 
set.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetchable 
resultsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The application called MOREINFO="NONE"ct_results and the result set 
contains fetchable results (compute results, return 
parameter results, regular row results, and stored 
procedure return status results). MOREINFO="NONE"ct_fetch has not been 
called yet.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetchable 
cursor resultsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The application called MOREINFO="NONE"ct_results and the result set 
contains fetchable cursor results. MOREINFO="NONE"ct_fetch has not been 
called yet.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetchable 
nested 
commandCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The application initiated a cursor close command 
(MOREINFO="NONE"ct_cursor(CS_CURSOR_CLOSE)) before fetching 
from a result set that contains fetchable cursor results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Sent fetchable 
nested commandCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The application called MOREINFO="NONE"ct_send to send the cursor close 
command to the server before fetching from a result 
set that contains fetchable cursor results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Processing 
fetchable nested 
commandCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The application called MOREINFO="NONE"ct_results to process the results 
of the cursor close command before fetching from a 
result set that contains fetchable cursor results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetching 
resultsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The application called MOREINFO="NONE"ct_fetch at least once and is 
currently in the process of fetching results (compute 
results, return parameter results, regular row results, 
and stored procedure return status results).COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetching cursor 
resultsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The application called MOREINFO="NONE"ct_fetch at least once and is 
currently in the process of fetching cursor row results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetching nested 
commandCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The application initiated a cursor close 
(MOREINFO="NONE"ct_cursor(CS_CURSOR_CLOSE)), cursor update 
(MOREINFO="NONE"ct_cursor(CS_CURSOR_UPDATE)), or cursor delete 
(MOREINFO="NONE"ct_cursor(CS_CURSOR_DELETE)) command while 
fetching from a result set that contains cursor results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Sent fetching 
nested 
commandCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The application called MOREINFO="NONE"ct_send to send the cursor close, 
cursor update, or cursor delete command to the server 
while fetching from a result set that contains cursor 
results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Processing 
fetching nested 
commandCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The application called MOREINFO="NONE"ct_results to process the results 
of the cursor close, cursor update, or cursor delete 
command while fetching from a result set that 
contains cursor results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Result set 
canceledCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The application canceled the current command 
(MOREINFO="NONE"ct_cancel(CS_CANCEL_ALL)). An application can 
call MOREINFO="NONE"ct_results once more to return the command to an 
Idle state.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"UndefinedCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The command structure is in an undefined state. Call 
MOREINFO="NONE"ct_cancel(CS_CANCEL_ALL).COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"In receive 
passthroughCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The application called MOREINFO="NONE"ct_recvpassthru and 
CS_PASSTHRU_MORE was returned.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"In send 
passthroughCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The application called MOREINFO="NONE"ct_sendpassthru and 
CS_PASSTHRU_MORE was returned.REMAP="BO--Body"This diagram shows a command transitioning through several command states.FLOAT="0"FORMAT="UNKNOWN" FILEREF="fig1_1a.xwd"RENDERAS="SECT3"Command-level RoutinesREMAP="BO--Body"These Client-Library routines are managed at the command level:COLS="4" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="124*"COLNAME="C2" COLWIDTH="124*"COLNAME="C3" COLWIDTH="124*"COLNAME="C4" COLWIDTH="124*"VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_bindMOREINFO="NONE"ct_br_columnMOREINFO="NONE"ct_br_tableMOREINFO="NONE"ct_cancelMOREINFO="NONE"ct_cmd_dropMOREINFO="NONE"ct_cmd_propsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_commandMOREINFO="NONE"ct_compute_infoMOREINFO="NONE"ct_cursorMOREINFO="NONE"ct_data_infoMOREINFO="NONE"ct_describeMOREINFO="NONE"ct_dynamicCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_dyndescMOREINFO="NONE"ct_fetchMOREINFO="NONE"ct_get_dataMOREINFO="NONE"ct_getformatMOREINFO="NONE"ct_keydataMOREINFO="NONE"ct_paramCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_res_infoMOREINFO="NONE"ct_resultsMOREINFO="NONE"ct_sendMOREINFO="NONE"ct_send_dataMOREINFO="NONE"ct_recvpassthruMOREINFO="NONE"ct_sendpassthruID="X59016" RENDERAS="SECT3"Callable Routines in Each Command StateREMAP="BO--Body"This table maps each command state to the Client-Library routines that an application can legally call while in that state. It also identifies the state of the command after the routine completes.TOCENTRY="1"LBL="Table 2-21: "Callable routines at each command stateCOLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="79*"COLNAME="C2" COLWIDTH="180*"COLNAME="C3" COLWIDTH="198*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Beginning
State:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Callable Routines:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Resulting
Command State:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"IdleCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_ALL)MOREINFO="NONE"ct_cancel(CS_CANCEL_ATTN)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Idle, if CS_SUCCEED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cmd_dropCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Idle.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cmd_propsCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Idle.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_commandCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Command initiated, if CS_SUCCEED.
Idle, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cursorCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Command initiated, if CS_SUCCEED.
Idle, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_dynamicCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Command initiated, if CS_SUCCEED.
Idle, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_dyndescCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Idle.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_sendpassthruCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"In send passthrough, if 
CS_PASSTHRU_MORE.Command sent, if CS_PASSTHRU_EOM.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Command 
initiatedCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_ALL)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Idle, if CS_SUCCEED.Command initiated, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_ATTN)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Command initiated.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cmd_propsCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Command initiated.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cursorCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Command initiated.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_data_info(CS_SET)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Command initiated.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_dyndescCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Command initiated.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_paramCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Command initiated.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_sendCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Command sent, if CS_SUCCEED.Idle, if CS_CANCELED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_send_dataCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Command initiated, if CS_SUCCEED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Command 
sentCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_ALL)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Result set canceled, if CS_SUCCEED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_ATTN)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Command sent, if CS_SUCCEED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cmd_propsCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Command sentCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_dyndescCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Command sentCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_recvpassthruCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"In receive passthrough, if 
CS_PASSTHRU_MORE.
Idle, if CS_PASSTHRU_EOM, 
CS_CANCELED.
Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_resultsCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Non-fetchable results available, if 
CS_SUCCEED and *result_type equals 
CS_MSG_RESULT, CS_CMD_SUCCEED, 
CS_CMD_FAIL, CS_CMD_DONE, 
CS_ROWFMT_RESULT, 
CS_COMPUTEFMT_RESULT, or 
CS_DESCRIBE_RESULT.
Fetchable results, if CS_SUCCEED and 
*result_type equals CS_ROW_RESULT, 
CS_COMPUTE_RESULT, 
CS_PARAM_RESULT, or 
CS_STATUS_RESULT.
Fetchable cursor results, if CS_SUCCEED 
and *result_type equals 
CS_CURSOR_RESULT.
Idle, if CS_CANCELED or 
CS_END_RESULTS.Undefined, if CS_SUCCEED and 
*result_type equals CS_CMD_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Non-fetchable
results 
availableCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_br_columnCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Non-fetchable results available.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_br_tableCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Non-fetchable results available.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_ALL)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Result set canceled, if CS_SUCCEED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_ATTN)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Non-fetchable results available, if 
CS_SUCCEED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_CURRENT)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Non-fetchable results available, if 
CS_SUCCEED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cmd_propsCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Non-fetchable results available.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_compute_infoCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Non-fetchable results available.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_describeCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Non-fetchable results available.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_dyndescCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Non-fetchable results available.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_getformatCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Non-fetchable results available.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_res_infoCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Non-fetchable results available.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_resultsCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetchable results, if CS_SUCCEED and 
*result_type equals CS_ROW_RESULT, 
CS_COMPUTE_RESULT, 
CS_PARAM_RESULT, or 
CS_STATUS_RESULT.
Fetchable cursor results, if CS_SUCCEED 
and *result_type equals 
CS_CURSOR_RESULT.
Idle, if CS_CANCELED or 
CS_END_RESULTS.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ANSI-style 
cursor 
end-dataCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_bindCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ANSI-style cursor end-data.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_br_columnCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ANSI-style cursor end-data.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_br_tableCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ANSI-style cursor end-data.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_ALL)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Result set canceled, if CS_SUCCEED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ct_cancel(CS_CANCEL_ATTN)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ANSI-style cursor end-data if 
CS_SUCCEED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_CURRENT)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ANSI-style cursor end-data.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cmd_propsCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ANSI-style cursor end-data.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_compute_infoCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ANSI-style cursor end-data.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_describeCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ANSI-style cursor end-data.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_dyndescCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ANSI-style cursor end-data.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_fetchCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ANSI-style cursor end-data, if 
CS_END_DATA.
Idle, if CS_CANCELED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_getformatCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ANSI-style cursor end-data.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_res_infoCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ANSI-style cursor end-data.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_resultsCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Non-fetchable results available, if 
CS_SUCCEED and *result_type equals 
CS_MSG_RESULT or CS_CMD_DONE.
Idle, if CS_CANCELED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetchable 
resultsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_bindCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetchable results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_br_columnCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetchable results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_br_tableCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetchable results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_ALL)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Result set canceled, if CS_SUCCEED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ct_cancel(CS_CANCEL_ATTN)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetchable results, if CS_SUCCEED.
Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ct_cancel(CS_CANCEL_CURRENT)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Non-fetchable results available, if 
CS_SUCCEED.Idle, if CS_CANCELED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cmd_propsCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetchable results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_compute_infoCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetchable results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_describeCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetchable results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_dyndescCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetchable results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_fetchCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetching results, if CS_SUCCEED or 
CS_ROW_FAIL.Non-fetchable results available, if 
CS_END_DATA.Idle, if CS_CANCELED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_getformatCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetchable results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_res_infoCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetchable results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetchable 
cursor resultsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_bindCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetchable cursor results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_ALL)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Result set canceled, if CS_SUCCEED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_ATTN)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetchable cursor results, if CS_SUCCEED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_CURRENT)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Non-fetchable results available, if 
CS_SUCCEED.Idle, if CS_CANCELED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cmd_propsCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetchable cursor results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cursorCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetchable nested command, if 
CS_SUCCEED.Fetchable cursor results, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_describeCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetchable cursor results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_dyndescCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetchable cursor results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_fetchCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetching cursor results, if CS_SUCCEED or 
CS_ROW_FAIL.Idle, if CS_CANCELED.Non-fetchable results available, if 
CS_END_DATA.Ansi-style cursor end-data, if 
CS_END_DATA and CS_ANSI_BINDS 
property is set.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_getformatCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetchable cursor results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_res_infoCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetchable cursor results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetchable nestedcommandCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_ALL)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetchable cursor results, if CS_SUCCEED.Fetchable nested command, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_ATTN)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetchable nested command, if 
CS_SUCCEED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cmd_propsCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetchable nested command.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_dyndescCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetchable nested command.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_paramCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetchable nested command.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_sendCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Sent fetchable nested, if CS_SUCCEED.Idle, if CS_CANCELED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Sent fetchable 
nestedCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_ALL)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Result set canceled, if CS_SUCCEED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_ATTN)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Sent fetchable nested, if CS_SUCCEED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cmd_propsCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Sent fetchable nested.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_resultsCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Processing fetchable nested command, if 
CS_CMD_SUCCEED or CS_CMD_FAIL.Idle, if CS_CANCELED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Processing 
fetchable 
nested 
commandCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_ALL)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Result set canceled, if CS_SUCCEED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_ATTN)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Processing fetchable nested command, if 
CS_SUCCEED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_CURRENT)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Processing fetchable nested command, if 
CS_SUCCEED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cmd_propsCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Processing fetchable nested command.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_dyndescCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Processing fetchable nested command.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_res_infoCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Processing fetchable nested command.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_resultsCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetchable cursor results, if 
CS_END_RESULTS.Idle, if CS_CANCELED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetching 
resultsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_bindCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetching results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_br_columnCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetching results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_br_tableCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetching results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_ALL)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Result set canceled, if CS_SUCCEED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_ATTN)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetching results, if CS_SUCCEED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_CURRENT)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Non-fetchable results available, if 
CS_SUCCEED.Idle, if CS_CANCELED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cmd_propsCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetching results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_compute_infoCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetching results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_data_info(CS_GET)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetching results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_describeCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetching results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_dyndescCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetching results, if CS_SUCCEED.Idle, if CS_CANCELED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_fetchCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetching results, if CS_SUCCEED.
Non-fetchable results available, if 
CS_END_DATA.Idle, if CS_CANCELED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_get_dataCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetching results, if CS_SUCCEED.Idle, if CS_CANCELED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_getformatCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetching results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_res_infoCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetching results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetching 
cursor 
resultsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_bindCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetching cursor results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_ALL)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Result set canceled, if CS_SUCCEED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ct_cancel(CS_CANCEL_ATTN)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetching cursor results, if CS_SUCCEED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ct_cancel(CS_CANCEL_CURRENT)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Non-fetchable results available, if 
CS_SUCCEED.Idle, if CS_CANCELED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cmd_propsCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetching cursor results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cursorCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetching nested command, if 
CS_SUCCEED.Fetching cursor results, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_describeCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetching cursor results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_dyndescCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetching cursor results, if CS_SUCCEED.Idle, if CS_CANCELED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_fetchCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetching cursor results, if CS_SUCCEED.Non-fetchable results available, if CS_END_DATA.Ansi-style cursor end-data, if 
CS_END_DATA and CS_ANSI_BINDS 
property is set.Idle, if CS_CANCELED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_get_dataCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetching cursor results, if CS_SUCCEED.Idle, if CS_CANCELED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_getformatCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetching cursor results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_keydataCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetching cursor results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_res_infoCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetching cursor results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetching 
nested 
commandCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_ALL)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetching cursor results, if CS_SUCCEED.Fetching nested command, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_ATTN)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetching nested command, if 
CS_SUCCEED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cmd_propsCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetching nested command.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_dyndescCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetching nested command.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_paramCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetching nested command.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_sendCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Sent fetching nested command, if 
CS_SUCCEED.Idle, if CS_CANCELED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Sent fetching nested commandCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_ALL)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Result set canceled, if CS_SUCCEED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_ATTN)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Sent fetching nested command, if 
CS_SUCCEED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cmd_propsCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Sent fetching nested command.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_resultsCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Processing fetching nested command, if 
CS_CMD_SUCCEED or CS_CMD_FAIL.Idle, if CS_CANCELED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Processing fetching nested commandCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_ALL)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Result set canceled, if CS_SUCCEED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_ATTN)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Processing fetching nested command, if 
CS_SUCCEED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_CURRENT)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Processing fetching nested command, if 
CS_SUCCEED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cmd_propsCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Processing fetching nested command.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_dyndescCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Processing fetching nested command.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_keydataCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Processing fetching nested command.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_res_infoCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Processing fetching nested command.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_resultsCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Processing fetching nested command, if 
CS_SUCCEED.
Fetching cursor results, if 
CS_END_RESULTS.Idle, if CS_CANCELED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Result set 
canceledCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_ALL)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Idle, if CS_SUCCEED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_ATTN)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Idle, if CS_SUCCEED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cmd_dropCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Idle.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cmd_propsCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Idle.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_commandCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Command initiated, if CS_SUCCEED.
Idle, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cursorCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Command initiated, if CS_SUCCEED.
Idle, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_dynamicCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Command initiated, if CS_SUCCEED.
Idle, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_dyndescCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Idle, if CS_SUCCEED, CS_ROW_FAIL, or 
CS_CANCELED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_resultsCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Result set canceled, if CS_SUCCEED or 
CS_FAIL.
Idle, if CS_CANCELED.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_sendpassthruCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Result set canceled.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"UndefinedCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_ALL)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Idle, if CS_SUCCEED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_ATTN)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Undefined.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cmd_propsCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Undefined.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_dyndescCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Undefined.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"In receive 
passthroughCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_ALL)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Idle, if CS_SUCCEED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_ATTN)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"In receive passthrough, if CS_SUCCEED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cmd_propsCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"In receive passthrough.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_recvpassthruCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Idle, if CS_PASSTHRU_EOM or 
CS_CANCELED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"In send 
passthroughCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_ALL)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Idle, if CS_SUCCEED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel(CS_CANCEL_ATTN)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"In send passthrough, if CS_SUCCEED.Undefined, if CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cmd_propsCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"In send passthrough.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_sendpassthruCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Command sent, if CS_PASSTHRU_EOM.Idle, if CS_CANCELED.Undefined, if CS_FAIL.ID="X74631" RENDERAS="SECT2"Initiated CommandsREMAP="BO--Body"In addition to command states, Client-Library keeps track of initiated commands. An initiated command can be in any one of the following states.TOCENTRY="1"LBL="Table 2-22: "Initialized commandsCOLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="126*"COLNAME="C2" COLWIDTH="234*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Initiated Command:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"What it Indicates:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"IdleCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The application either hasn't yet initiated a 
command or has completely processed the results 
of the last command.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Idle, with 
declared cursorCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The application initiated a cursor declare 
command (MOREINFO="NONE"ct_cursor(CS_CURSOR_DECLARE)), 
sent the command to the server, and completely 
processed the results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Idle, with 
opened cursorCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The application initiated a cursor open command 
(MOREINFO="NONE"ct_cursor(CS_CURSOR_OPEN)) and fetched all the 
results (MOREINFO="NONE"ct_results returned CS_END_RESULTS), but 
has not yet closed the cursor.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Opened cursor, 
no rows fetchedCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The application called MOREINFO="NONE"ct_results, but hasn't yet 
processed any of the results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Opened cursor, 
fetching rowsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The application called MOREINFO="NONE"ct_fetch at least once and is 
currently in the process of fetching results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Command
initiatedCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The application initiated a language, message, 
package, or RPC command via MOREINFO="NONE"ct_command.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Sent dataCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The application initiated a send-data or send-
bulk-data command via MOREINFO="NONE"ct_command.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Declared cursorCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The application initiated a cursor declare 
command (MOREINFO="NONE"ct_cursor(CS_CURSOR_DECLARE)), 
but hasn't yet sent it to a server via MOREINFO="NONE"ct_send.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Set cursor rowsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The application initiated a cursor rows command 
via MOREINFO="NONE"ct_cursor(CS_CURSOR_ROWS).COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Opened cursorCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The application initiated a cursor open command 
(MOREINFO="NONE"ct_cursor(CS_CURSOR_OPEN)), but hasn't yet sent 
it to a server.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Closed cursorCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The application initiated a cursor close command 
(MOREINFO="NONE"ct_cursor(CS_CURSOR_CLOSE)) but hasn't yet 
sent it to a server.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"De-allocated 
cursorCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The application initiated a cursor de-allocate 
command (MOREINFO="NONE"ct_cursor(CS_CURSOR_DEALLOC)) but 
hasn't yet sent it to a server.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Updated cursor 
rowCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The application initiated a cursor update 
command (MOREINFO="NONE"ct_cursor(CS_CURSOR_UPDATE)) but 
hasn't yet sent it to a server.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Deleted cursor 
rowCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The application initiated a cursor delete command 
(MOREINFO="NONE"ct_cursor(CS_CURSOR_DELETE)) but hasn't yet 
sent it to a server.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Dynamic cursor 
declaredCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The application initiated a cursor declare 
command on a dynamically prepared SQL 
statement (MOREINFO="NONE"ct_dynamic(CS_CURSOR_DECLARE)) 
but hasn't yet sent it to a server.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Dynamic 
de-allocatedCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The application initiated a command to de-
allocate a prepared SQL statement 
(MOREINFO="NONE"ct_dynamic(CS_DEALLOC)) but hasn't yet sent it 
to a server.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Dynamic 
describedCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The application initiated a command to retrieve 
input parameter information 
(MOREINFO="NONE"ct_dynamic(CS_DESCRIBE_INPUT)) or column list 
information (MOREINFO="NONE"ct_dynamic(CS_DESCRIBE_OUTPUT)) 
but hasn't yet sent it to a server.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Dynamic executedCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The application initiated a command to execute a 
prepared SQL statement 
(MOREINFO="NONE"ct_dynamic(CS_EXECUTE)) but hasn't yet sent it to 
a server.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Dynamic execute 
immediateCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The application initiated a command to execute a 
literal SQL statement 
(MOREINFO="NONE"ct_dynamic(CS_EXEC_IMMEDIATE)) but hasn't 
yet sent it to a server.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Dynamic prepareCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The application initiated a command to prepare a 
SQL statement (MOREINFO="NONE"ct_dynamic(CS_PREPARE)) but 
hasn't yet sent it to a server.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_send_data succeededCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The application successfully called MOREINFO="NONE"ct_send_data at 
least once.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Bulk copyCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The application initiated a send-bulk-data 
command (MOREINFO="NONE"ct_command(CS_SEND_BULK_CMD)) 
but hasn't yet sent it to a server.RENDERAS="SECT3"Initiated Command RoutinesREMAP="BO--Body"The following Client-Library routines are useful for processing initiated commands:COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="207*"COLNAME="C2" COLWIDTH="207*"VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cmd_dropMOREINFO="NONE"ct_commandMOREINFO="NONE"ct_cursorMOREINFO="NONE"ct_data_infoMOREINFO="NONE"ct_dynamicCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_dyndescMOREINFO="NONE"ct_paramMOREINFO="NONE"ct_send_dataMOREINFO="NONE"ct_sendpassthruID="X28854" RENDERAS="SECT3"Callable Routines for Initiated CommandsREMAP="BO--Body"This table maps each initiated command state to the Client-Library routines that an application can legally call while in that state.REMAP="BO--Body"Where (none) is specified, it indicates that an application can call none of the routines listed above. From within those states that map to a (none) value in the Callable Routines column, an application's only options are to either send (MOREINFO="NONE"ct_send) or cancel (MOREINFO="NONE"ct_cancel) the initiated command.TOCENTRY="1"LBL="Table 2-23: "Callable routines for initiated commands COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="153*"COLNAME="C2" COLWIDTH="207*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Initiated Command:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Callable Routines:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"IdleCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cmd_dropct_command(CS_LANG_CMD)MOREINFO="NONE"ct_command(CS_MSG_CMD)MOREINFO="NONE"ct_command(CS_PACKAGE_CMD)MOREINFO="NONE"ct_command(CS_RPC_CMD)MOREINFO="NONE"ct_command(CS_SEND_BULK_CMD)MOREINFO="NONE"ct_command(CS_SEND_DATA_CMD)MOREINFO="NONE"ct_cursor(CS_CURSOR_DECLARE)MOREINFO="NONE"ct_dynamic(CS_CURSOR_DECLARE)MOREINFO="NONE"ct_dynamic(CS_DEALLOC)MOREINFO="NONE"ct_dynamic(CS_DESCRIBE_INPUT)MOREINFO="NONE"ct_dynamic(CS_DESCRIBE_OUTPUT)MOREINFO="NONE"ct_dynamic(CS_EXECUTE)MOREINFO="NONE"ct_dynamic(CS_EXEC_IMMEDIATE)MOREINFO="NONE"ct_dynamic(CS_PREPARE)MOREINFO="NONE"ct_sendpassthruCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Idle, with declared cursorCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cursor(CS_CURSOR_ROWS)MOREINFO="NONE"ct_cursor(CS_CURSOR_OPEN)MOREINFO="NONE"ct_cursor(CS_CURSOR_CLOSE, 
CS_DEALLOC)MOREINFO="NONE"ct_cursor(CS_CURSOR_DEALLOC)MOREINFO="NONE"ct_dynamic(CS_DEALLOC)COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Idle, with opened cursorCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cursor(CS_CURSOR_CLOSE)MOREINFO="NONE"ct_cursor(CS_CURSOR_CLOSE, 
CS_DEALLOC)MOREINFO="NONE"ct_dynamic(CS_DEALLOC)COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Opened cursor,no rows fetchedCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cursor(CS_CURSOR_CLOSE)MOREINFO="NONE"ct_cursor(CS_CURSOR_CLOSE, CS_DEALLOC)COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Opened cursor, fetching rowsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cursor(CS_CURSOR_CLOSE)MOREINFO="NONE"ct_cursor(CS_CURSOR_CLOSE, 
CS_DEALLOC)MOREINFO="NONE"ct_cursor(CS_CURSOR_UPDATE)MOREINFO="NONE"ct_cursor(CS_CURSOR_DELETE)COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Command initializedCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_dyndesc(CS_USE_DESC)MOREINFO="NONE"ct_paramCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Sent dataCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_data_info(CS_SET)MOREINFO="NONE"ct_send_dataCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Declared cursorCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cursor(CS_CURSOR_ROWS)MOREINFO="NONE"ct_cursor(CS_CURSOR_OPEN)MOREINFO="NONE"ct_cursor(CS_CURSOR_OPTION)MOREINFO="NONE"ct_dyndesc(CS_USE_DESC)MOREINFO="NONE"ct_param COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Set cursor rowsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cursor(CS_CURSOR_OPEN)COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Opened cursorCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_dyndesc(CS_USE_DESC)MOREINFO="NONE"ct_paramCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Closed cursorCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"(None)COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"De-allocated cursorCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"(None)COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Updated cursor rowCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_dyndesc(CS_USE_DESC)MOREINFO="NONE"ct_paramCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Deleted cursor rowCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"(None)COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Dynamic declaredCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"(None)COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Dynamic de-allocatedCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"(None)COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Dynamic describedCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"(None)COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Dynamic executedCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_dyndesc(CS_USE_DESC)MOREINFO="NONE"ct_paramCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Dynamic execute immediateCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"(None)COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Dynamic prepareCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_dyndesc(CS_USE_DESC)MOREINFO="NONE"ct_paramCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_send_data succeededCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_send_dataCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Bulk copyCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_send_dataID="X98861" RENDERAS="SECT2"Result TypesREMAP="BO--Body"If a command is in one of the following states:REMAP="UN--Under"Results availableFetchable resultsFetchable cursor resultsFetchable nested commandSent fetchable nested commandProcessing fetchable nested commandFetching resultsFetching cursor resultsREMAP="UN--Under"Fetching nested commandSent fetching nested commandProcessing fetching nested commandREMAP="BO--Body"Client-Library pre-defines which routines can be called, based on the result type. REMAP="BO--Body"The following table briefly describes the different result types:TOCENTRY="1"LBL="Table 2-24: "Result typesCOLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="117*"COLNAME="C2" COLWIDTH="243*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Result Type:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Description:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Regular row 
resultsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Zero or more rows of tabular data generated by the 
execution of a Transact-SQL MOREINFO="NONE"select statement.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Cursor row 
resultsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Zero or more rows of tabular data generated when 
an application executes a Client-Library cursor open 
command.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Parameter 
resultsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A single row of message parameters or stored 
procedure return parameters.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Stored procedure 
return status 
resultsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A single row containing a single value (a return 
status).COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Message resultsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No data is available, but an application can call 
MOREINFO="NONE"ct_res_info to get the message's id.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Compute row 
resultsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A single row of tabular data with a number of 
columns equal to the number of columns listed in 
the compute clause that generated the compute row.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CMD_DONECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The results of a command have been completely 
processed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CMD_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A command that returns no data (such as a 
language command containing a Transact-SQL 
MOREINFO="NONE"insert statement) was successful.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CMD_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The server encountered an error while executing a 
command.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Regular row 
format resultsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Format information for an associated regular row 
result set.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Compute row 
format resultsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Format information for an associated compute row 
result set.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Describe resultsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Descriptive information returned as the result of a 
dynamic SQL describe input or output command.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Extended error 
data resultsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A single row of extended error data.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Notification 
resultsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A single row of arguments with which a registered 
procedure was called.REMAP="BO--Body"See the MOREINFO="NONE"Results topics page for detailed information about the various types of results.RENDERAS="SECT3"Result Type Processing RoutinesREMAP="BO--Body"The following Client-Library routines are useful for processing various types of results:COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="207*"COLNAME="C2" COLWIDTH="207*"VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_bindMOREINFO="NONE"ct_br_columnMOREINFO="NONE"ct_br_tableMOREINFO="NONE"ct_compute_infoMOREINFO="NONE"ct_data_infoCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_describeMOREINFO="NONE"ct_dyndescMOREINFO="NONE"ct_getformatMOREINFO="NONE"ct_keydataMOREINFO="NONE"ct_res_infoID="X97530" RENDERAS="SECT3"Callable Routines for Each Result TypeREMAP="BO--Body"When an application calls MOREINFO="NONE"ct_results to find out what kind of results are available, Client-Library defines which routines are callable based on the value of MOREINFO="NONE"ct_results' *result_type parameter.REMAP="BO--Body"This table maps each result type to the Client-Library routines that an application can legally call to process that result type.TOCENTRY="1"LBL="Table 2-25: "Callable routines for each result type COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="162*"COLNAME="C2" COLWIDTH="198*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Result Type:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Callable Routines:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Regular row resultsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_bindct_br_columnct_br_tablect_data_info(CS_GET)MOREINFO="NONE"ct_describect_getformatct_res_info(CS_BROWSE_INFO)MOREINFO="NONE"ct_res_info(CS_CMD_NUMBER)MOREINFO="NONE"ct_res_info(CS_NUMDATA)MOREINFO="NONE"ct_res_info(CS_NUMORDERCOLS)MOREINFO="NONE"ct_res_info(CS_ORDERBY_COLS)MOREINFO="NONE"ct_res_info(CS_TRANS_STATE)MOREINFO="NONE"ct_dyndesc(CS_USE_DESC)COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Cursor row resultsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_bindct_describect_getformatct_keydatact_res_info(CS_CMD_NUMBER)MOREINFO="NONE"ct_res_info(CS_CMD_NUMDATA)MOREINFO="NONE"ct_res_info(CS_TRANS_STATE)MOREINFO="NONE""ct_dyndesc(CS_USE_DESC)COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Parameter resultsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_bindct_describect_res_info(CS_CMD_NUMBER)MOREINFO="NONE"ct_res_info(CS_NUMDATA)MOREINFO="NONE"ct_res_info(CS_TRANS_STATE)MOREINFO="NONE"ct_dyndesc(CS_USE_DESC)COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Stored procedure return status resultsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_bindct_describect_res_info(CS_CMD_NUMBER)MOREINFO="NONE"ct_res_info(CS_CMD_NUMDATA)MOREINFO="NONE"ct_res_info(CS_TRANS_STATE)MOREINFO="NONE"ct_dyndesc(CS_USE_DESC)COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Message resultsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_res_info(CS_CMD_NUMBER)MOREINFO="NONE"ct_res_info(CS_MSGTYPE)MOREINFO="NONE"ct_res_info(CS_TRANS_STATE)COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Compute row resultsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_bindct_compute_infoct_describect_res_info(CS_CMD_NUMBER)MOREINFO="NONE"ct_res_info(CS_NUM_COMPUTES)MOREINFO="NONE"ct_res_info(CS_NUMDATA)MOREINFO="NONE"ct_res_info(CS_TRANS_STATE)MOREINFO="NONE"ct_dyndesc(CS_USE_DESC)COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CMD_DONECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_res_info(CS_CMD_NUMBER)MOREINFO="NONE"ct_res_info(CS_ROW_COUNT)MOREINFO="NONE"ct_res_info(CS_TRANS_STATE)COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CMD_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_res_info(CS_CMD_NUMBER)MOREINFO="NONE"ct_res_info(CS_ROW_COUNT)MOREINFO="NONE"ct_res_info(CS_TRANS_STATE)COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CMD_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_res_info(CS_CMD_NUMBER)MOREINFO="NONE"ct_res_info(CS_ROW_COUNT)MOREINFO="NONE"ct_res_info(CS_TRANS_STATE)COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Regular row format
resultsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_describect_res_info(CS_CMD_NUMBER)MOREINFO="NONE"ct_res_info(CS_CMD_NUMDATA)MOREINFO="NONE"ct_res_info(CS_TRANS_STATE)MOREINFO="NONE"ct_dyndesc(CS_USE_DESC)COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Compute row formatresultsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_compute_infoct_describe>ct_res_info(CS_CMD_NUMBER)MOREINFO="NONE"ct_res_info(CS_NUM_COMPUTES)MOREINFO="NONE"ct_res_info(CS_NUMDATA)MOREINFO="NONE"ct_res_info(CS_TRANS_STATE)MOREINFO="NONE"ct_dyndesc(CS_USE_DESC)COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Describe resultsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_describect_res_info(CS_CMD_NUMBER)MOREINFO="NONE"ct_res_info(CS_NUMDATA)MOREINFO="NONE"ct_res_info(CS_TRANS_STATE)MOREINFO="NONE"ct_dyndesc(CS_USE_DESC)COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Extended error data resultsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_bindct_describect_res_info(CS_NUMDATA)MOREINFO="NONE"ct_res_info(CS_TRANS_STATE)COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Notification resultsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_bindct_describect_res_info(CS_NUMDATA)MOREINFO="NONE"ct_res_info(CS_TRANS_STATE)RENDERAS="SECT3"Pending ResultsREMAP="BO--Body"Multiple command structures sharing the same connection can block one another when results are pending on the connection. `Pending results' is a term that indicates that the results of a command have not yet been completely processed. For example, assume two CS_COMMAND structures (A and B) sharing the same CS_CONNECTION structure. If A is in the Results Available state, B is blocked from sending a command to the server because there are results pending on the connection. B will remain blocked until A processes all the results of the current command and transitions into a state that indicates that no results are pending.REMAP="BO--Body"States that indicate pending results are:REMAP="UN--Under"Command sentResults availableANSI-style cursor end-dataFetchable resultsSent fetchable nested commandProcessing fetchable nested commandFetching resultsSent fetching nested commandUndefinedIn receive passthroughIn send passthroughREMAP="BO--Body"States that do not indicate pending results are:REMAP="UN--Under"IdleCommand initiatedFetchable cursor resultsFetchable nested commandFetching cursor resultsFetching nested commandProcessing fetching nested commandResult set canceledREMAP="BO--Body"ID="X12709" RENDERAS="SECT1"Message Commands and ResultsID="IN42162774143"Message commands
ID="IN42152774144"Message results
ID="IN42132774145"Client/servercommunicationREMAP="BO--Body"Message commands and results provide a way for clients and servers to communicate specialized information to one another.REMAP="BO--Body"For example, if the ID="IN42212378146"CS_OPT_GETDATA optionCS_OPT_GETDATA
CS_OPT_GETDATA option is enabled, then on every MOREINFO="NONE"insert, MOREINFO="NONE"delete, or MOREINFO="NONE"update SQL Server returns a message with parameters that allows a client application to construct the name of the temporary table that SQL Server is using for the operation.RENDERAS="SECT2"Message CommandsID="IN42162378147"Message commandssendingREMAP="BO--Body"To send a message command:NUMERATION="ARABIC" REMAP="S1--StepOne" CONTINUATION="RESTARTS" INHERITNUM="IGNORE"Call MOREINFO="NONE"ct_command to initiate the command.Call MOREINFO="NONE"ct_param once for each parameter that the message requires.Call MOREINFO="NONE"ct_send to send the message command.RENDERAS="SECT2"Message ResultsREMAP="BO--Body"MOREINFO="NONE"ct_results sets its *result_type parameter to CS_MSG_RESULT to indicate a message result set.REMAP="BO--Body"A message result set contains no fetchable data. Rather, a message has an "id," which an application can retrieve by calling MOREINFO="NONE"ct_res_info.REMAP="BO--Body"Any parameters associated with a message are returned in the form of a parameter result set following the message result set.ID="IN4282378148"Messageslegal IDs for user-defined messagesRENDERAS="SECT2"Legal Message IdsID="IN42212378149"User-defined messageslegal message IDsREMAP="BO--Body"Ids for user-defined messages must be greater than or equal to CS_USER_MSGID and less than or equal to CS_USER_MAX_MSGID.ID="IN42112378150"Open Clientmacros
ID="IN4262378151"MacrosOpen Client macrosRENDERAS="SECT1"Open Client MacrosID="IN4262378152"Macrosdefinition ofREMAP="BO--Body"Macros are C language definitions that typically take one or more arguments and expand into inline C code when the source file is pre-processed. The following sections introduce you to the Open Client macros by presenting them in their functional contexts.ID="IN42142378153"Message numberdecoding
ID="IN42252378154"Decoding a message numberRENDERAS="SECT2"Decoding a Message NumberREMAP="BO--Body"Client-Library and CS-Library message numbers consist of four components: layer, origin, severity, and number.REMAP="BO--Body"Open Client provides the following macros to help an application decode a Client-Library or CS-Library message number and break it into its four parts so that each component can be displayed separately:MARK="BULL" REMAP="BU--Bullet"ID="IN42142180155"CS_LAYER macro
MOREINFO="NONE"CS_LAYER(msg_number) - identifies the layer reporting the error.ID="IN42151982156"CS_ORIGIN macro
MOREINFO="NONE"CS_ORIGIN(msg_number) - indicates where the error manifested itself.ID="IN42171784157"CS_SEVERITY macro
MOREINFO="NONE"CS_SEVERITY(msg_number) - indicates the severity of the error.ID="IN42151586158"CS_NUMBER macro
MOREINFO="NONE"CS_NUMBER(msg_number) - identifies the actual layer-specific error                                               number being reported.REMAP="BO--Body"These macros are defined in the header file 
cstypes.h.ID="IN42211388159"cstypes.h header fileID="IN42121190160"Header filescstypes.hREMAP="BO--Body"See the LINKEND="X26600""Client-Library Messages"
topics page for more information about Client-Library message numbers.REMAP="BO--Body"For information on CS-Library error handling, see the Open Client and Open Server Common Libraries Reference Manual.ID="IN4221992161"CS_CAP_TYPE structuremanipulating bits
ID="IN4210794162"StructuresCS_CAP_TYPE structure:manipulating bitsRENDERAS="SECT2"Manipulating Bits in a CS_CAP_TYPE StructureID="IN4212794163"Capabilitiesstoring connection informationREMAP="BO--Body"Capabilities describe features that a client/server connection supports. Each connection's capability information is stored in a CS_CAP_TYPE structure.REMAP="BO--Body"Client-Library provides the following macros to enable an application to clear, set, and test bits in a CS_CAP_TYPE structure:MARK="BULL" REMAP="BU--Bullet"ID="IN4220596164"CS_CLR_CAPMASK macro
MOREINFO="NONE"CS_CLR_CAPMASK(mask, capability) - clears bits in a CS_CAP_TYPE structure.ID="IN4220398165"CS_SET_CAPMASK macro
MOREINFO="NONE"CS_SET_CAPMASK(mask, capability) - sets bits in a CS_CAP_TYPEstructure.ID="IN42201100166"CS_TST_CAPMASK macro
MOREINFO="NONE"CS_TST_CAPMASK(mask, capability) - tests bits in a CS_CAP_TYPEstructure.REMAP="BO--Body"where mask is a pointer to a CS_CAP_TYPE structure and capability is the capability of interest.REMAP="BO--Body"These macros are defined in the header file ID="IN4222-1102167"cspublic.h header file
ID="IN4212-3104168"Header filescspublic.h
cspublic.h.REMAP="BO--Body"See the LINKEND="X17423""Capabilities"
topic page for more information about capabilities.RENDERAS="SECT2"Using the sizeof OperatorID="IN4215-7108169"sizeof operatorsizeofREMAP="BO--Body"The C MOREINFO="NONE"sizeof operator returns the size of a specified item in bytes. Because the datatype of its return value varies from platform to platform, using sizeof can be problematic for Client-Library applications. In particular, specifying sizeof as an argument to a Client-Library routine may result in a compiler error or warning if the type returned is not a CS_INT.REMAP="BO--Body"Client-Library provides the following macro to enable an application to use the sizeof function with Client-Library:MARK="BULL" REMAP="BU--Bullet"ID="IN4215-9110170"CS_SIZEOF macro
MOREINFO="NONE"CS_SIZEOF - casts a value to a CS_INT.REMAP="BO--Body"This macro is defined in the header file cstypes.h.
ID="IN4221-11112171"cstypes.h header file
ID="IN4212-13114172"Header filescstypes.h
ID="IN427-13114173"OptionsSQL ServerID="X98856" RENDERAS="SECT1"OptionsID="IN4210-13114174"SQL Serveroptions:two ways to setREMAP="BO--Body"A Client-Library application can set and clear SQL Server query-processing options in one of two ways:MARK="BULL" REMAP="BU--Bullet"Through a Transact-SQL language command (MOREINFO="NONE"set)By calling MOREINFO="NONE"ct_optionsREMAP="BO--Body"An application must use only one of these methods, because otherwise Client-Library/server communications can become confused.REMAP="BO--Body"The MOREINFO="NONE"ct_options method is recommended, because it has the advantage of allowing an application to check the status of an option, which cannot be done through the Transact-SQL MOREINFO="NONE"set command.REMAP="BO--Body"For more information on SQL Server query-processing options, see theMOREINFO="NONE" set command in the SQL Server Reference Manual.ID="IN426-13114175"Serveroptions:list of
ID="IN4210-13114176"SQL Serveroptions:list ofRENDERAS="SECT2"Symbolic Constants for Server OptionsREMAP="BO--Body"The following table lists the symbolic constants that are used with MOREINFO="NONE"ct_options:TOCENTRY="1"LBL="Table 2-26: "Symbolic constants for server optionsCOLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="166*"COLNAME="C2" COLWIDTH="202*"COLNAME="C3" COLWIDTH="102*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Symbolic Constant:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"What the Option Does:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Default Value:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_ANSINULLCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Determines whether or not evaluation of 
NULL-valued operands in SQL equality 
(=) or inequality (!=) comparisons is ANSI-
compliant.
If CS_TRUE, SQL Server enforces the ANSI 
behavior that "= NULL" and "is NULL" 
are not equivalent. In standard Transact 
SQL, "= NULL" and "is NULL" are 
considered to be equivalent.
This option affects "<> NULL" and "is not 
NULL" behavior in a similar fashion.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_ANSIPERMCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Determines whether or not SQL Server is 
ANSI-compliant with respect to 
permissions checks on MOREINFO="NONE"update and MOREINFO="NONE"delete 
statements.

If CS_TRUE, SQL Server is ANSI-
compliant.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_ARITHABORTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Determines how SQL Server behaves when 
an arithmetic error occurs.

** If CS_TRUE, both the MOREINFO="NONE"arith_overflow and 
MOREINFO="NONE"numeric_truncation options are set on. An 
entire transaction or batch in which an 
error occurred is rolled back when a 
divide-by-zero error or a loss of precision 
occurs during either an explicit or implicit 
datatype conversion. If a loss of scale by an 
exact numeric type during an implicit 
datatype conversion occurs, the statement 
that caused the error is aborted, but the 
other statements in the transaction or batch 
continue to be processed.

** If CS_FALSE, both the MOREINFO="NONE"arith_overflow and 
MOREINFO="NONE"numeric_truncation options are set off. The 
statement that caused a divide-by-zero 
error or a loss of precision during either an 
explicit or implicit datatype conversion is 
aborted, but the other statements in the 
transaction or batch continue to be 
processed. If a loss of scale by an exact 
numeric type during an implicit datatype 
conversion occurs, the query results are 
truncated and other statements in the 
transaction or batch continue to be 
processed.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_ARITHIGNORECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Determines whether SQL Server displays a 
message after a divide-by-zero error or a 
loss of precision. 

If CS_TRUE, warning message are 
suppressed after these errors.

If CS_FALSE, warning messages are 
displayed after these errors.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_AUTHOFFCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Turns the specified authorization level off 
for the current server session. When a user 
logs in, all authorizations granted to that 
user are automatically turned off.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Not applicableCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_AUTHONCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Turns the specified authorization level on 
for the current server session. When a user 
logs in, all authorizations granted to that 
user are automatically turned on.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Not applicableCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_CHAINXACTSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"If CS_TRUE, SQL Server uses chained 
transaction behavior. Chained transaction 
behavior means that each server command 
is considered to be a distinct transaction. 
SQL Server implicitly executes a MOREINFO="NONE"begin 
transaction before any of the following 
statements: MOREINFO="NONE"delete, MOREINFO="NONE"fetch, MOREINFO="NONE"insert, MOREINFO="NONE"open, MOREINFO="NONE"select, 
and MOREINFO="NONE"update.
If CS_FALSE, an application must specify 
an explicit MOREINFO="NONE"commit transaction statement to 
end a transaction and begin a new one.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_CURCLOSEONXACTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"If CS_TRUE, all cursors opened within a 
transaction are closed when the transaction 
completes.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_CURREADCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Sets a security label specifying the current 
read level.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_CURWRITECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Sets a security label specifying the current 
write level.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_DATEFIRSTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Sets the "first" day of the week.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"For us_english, the 
default is 
CS_OPT_SUNDAY.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_DATEFORMATCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Sets the order of the date parts 
month/day/year for entering datetime or 
smalldatetime data. COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"For us_english, the 
default is 
CS_OPT_FMTMDY.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_FIPSFLAGCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Determines whether SQL Server displayss 
a warning message when SQL extensions 
are used.

If CS_TRUE, SQL Server flags any non-
standard SQL commands that are sent.

If CS_FALSE, SQL Server does not flag 
non-ANSI SQL.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_FORCEPLANCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"If CS_TRUE, SQL Server joins tables in the 
order in which the tables are listed in the 
MOREINFO="NONE"from clause of the query.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_FORMATONLYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"If CS_TRUE, SQL Server sends back a 
description of the data, rather than the data 
itself, in response to a MOREINFO="NONE"select query.

If CS_FALSE, SQL Server sends back data 
in response to a MOREINFO="NONE"select query.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_GETDATACOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"If CS_TRUE, on every MOREINFO="NONE"insert, MOREINFO="NONE"delete, or 
MOREINFO="NONE"update statement, SQL Server returns 
information (in the form of a message 
result set and parameters) that an 
application can use to construct the name 
of the temporary table that will contain the 
rows to be inserted and/or deleted.

Note that an update consists of insertions 
and deletions.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_IDENTITYOFFCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Disables inserts into a table's IDENTITY 
column.

For more information, see the MOREINFO="NONE"set command (MOREINFO="NONE"identity_insert option) in the 
SQL Server documentation.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Not applicableCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_IDENTITYONCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Enables inserts into a table's IDENTITY 
column.

For more information, see the MOREINFO="NONE"set 
command (MOREINFO="NONE"identity_insert option) in the 
SQL Server documentation.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Not applicableCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_ISOLATIONCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Specifies a transaction isolation level. 
Possible levels are CS_OPT_LEVEL1 and 
CS_OPT_LEVEL3.

If CS_OPT_LEVEL1, shared locks are 
placed on all accessed pages of tables 
specified in a MOREINFO="NONE"select query's MOREINFO="NONE"from clause. 
The locks are held for the duration of a 
transaction.

If CS_OPT_LEVEL3, hold locks are placed 
on all accessed pages of tables specified in 
a MOREINFO="NONE"select query's MOREINFO="NONE"from clause. The locks are 
held for the duration of the transaction.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_LEVEL1COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_NOCOUNTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Turns off the display of the number of rows 
affected by each SQL statement. An 
application can ordinarily obtain this 
information by calling MOREINFO="NONE"ct_res_info.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_NOEXECCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"If CS_TRUE, SQL Server compiles each 
query but does not execute it. 

Use this option in conjunction with 
CS_OPT_SHOWPLAN.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_PARSEONLYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"If CS_TRUE, SQL Server checks the syntax 
of each query and returns any error 
messages as necessary, but does not 
execute the query.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_QUOTED_IDENTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"If CS_TRUE, SQL Server treats all strings 
enclosed in double quotes (") as identifiers.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_RESTREESCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"If CS_TRUE, SQL Server checks the syntax 
of each query and returns parse resolution 
trees (in the form of image columns in a 
regular row result set) and error messages 
as necessary, but does not execute the 
query.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_ROWCOUNTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"If set to 0, all rows generated by a MOREINFO="NONE"select 
statement are returned.

If set to a value greater than 0, SQL Server 
returns up to the specified number of 
regular rows for each MOREINFO="NONE"select statement.

This option is always on, never off.
This option does not limit the number of 
compute rows returned.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"0.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_SHOWPLANCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Detemines whether a description of each 
query's processing plan is returned 
between its compilation and execution.
If CS_TRUE, SQL Server compiles a query, 
generates a description of its processing 
plan, and then executes the query.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_STATS_IOCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Determines whether SQL Server internal 
I/O statistics (the number of scans, logical 
reads, physical reads, and pages written) 
are returned for each query.

If CS_TRUE, statistics are returned.
These statistics are returned to Client-
Library in the form of informational server 
messages. Application programs can 
access them through the user-supplied 
server message handler.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_STATS_TIMECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Determines whether SQL Server parsing, 
compilation, and execution time statistics 
are returned for each query.

If CS_TRUE, statistics are returned.
These statistics are returned to Client-
Library in the form of informational server 
messages. Application programs can 
access them through the user-supplied 
server message handler.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_STR_RTRUNCCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"If CS_TRUE, SQL Server is ANSI-
compliant with respect to right truncation 
of character data.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_TEXTSIZECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Specifies the value of the SQL Server global 
variable @@textsize, which limits the size of 
text or image values that SQL Server 
returns.
When setting this option, supply a 
parameter which is the length, in bytes, of 
the longest text or image value that SQL 
Server should return.
In programs that allow application users to 
run ad hoc queries, the user may override 
this option with the Transact-SQLMOREINFO="NONE" set 
MOREINFO="NONE"textsize command. To set a text limit that 
the user cannot override, use the Client-
Library CS_TEXTLIMIT property instead.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"32,768 bytesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_TRUNCIGNORECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"If CS_TRUE, SQL Server ignores 
truncation errors. This is standard ANSI 
behavior.

If CS_FALSE, SQL Server raises an error 
when conversion results in truncation.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSEID="IN4221-14115177"Parameter conventionsRENDERAS="SECT1"Parameter ConventionsREMAP="BO--Body"This topics page contains information on Client-Library parameter conventions. REMAP="BO--Body"Exceptions to these conventions are documented on the manual pages for the routines for which the exceptions occur.ID="IN4210-14115178"Parametersunused parameters
ID="IN4210-16117179"ParametersNULL parameters
ID="IN4217-16117180"Unused parameters
ID="IN4215-18119181"NULL parametersRENDERAS="SECT2"NULL and Unused ParametersREMAP="BO--Body"This section contains information on NULL and unused parameters.ID="IN4210-18119182"Parameterspointer parametersRENDERAS="SECT3"Pointer ParametersREMAP="BO--Body"A pointer parameter can:MARK="BULL" REMAP="BU--Bullet"Have a non-NULL valueHave a value of NULLBe unusedREMAP="BO--Body"Pass NULL and unused pointer parameters as NULL. REMAP="BO--Body"If the parameter has a NULL value, the length variable associated with the parameter, if any, must be 0 or CS_UNUSED.REMAP="BO--Body"If the parameter is unused, the length variable associated with the parameter, if any, must be CS_UNUSED.REMAP="BO--Body"Client-Library uses current programming context information to determine whether to interpret the parameter as NULL or unused.ID="IN4210-18119183"Parametersnon-pointer parametersRENDERAS="SECT3"Non-Pointer ParametersREMAP="BO--Body"Pass non-pointer unused parameters as CS_UNUSED. ID="IN4210-18119184"Parametersinput parameter stringsRENDERAS="SECT2"Input Parameter StringsREMAP="BO--Body"Most string parameters are associated with a parameter that indicates the length of the string.ID="IN4210-18119185"Parameterspassing a null-terminated stringREMAP="BO--Body"When passing a null-terminated string, an application can pass the length parameter as CS_NULLTERM. ID="IN4210-18119186"Parameterspassing a non null-terminated stringREMAP="BO--Body"When passing a string that is not null-terminated, an application must set the associated length parameter to the length, in bytes, of the string.REMAP="BO--Body"If a string parameter is NULL the associated length parameter must be 0 or CS_UNUSED.ID="IN4210-18119187"Parametersoutput parameter stringsRENDERAS="SECT2"Output Parameter StringsREMAP="BO--Body"An application indicates the length of a string buffer by setting an associated length parameter.REMAP="BO--Body"If the length parameter indicates that the buffer is not large enough to hold a null-terminated output string, Client-Library routines return CS_FAIL.ID="IN4210-18119188"Structurespointers to structuresRENDERAS="SECT2"Pointers to Basic StructuresREMAP="BO--Body"All Client-Library routines take a pointer to a CS_CONTEXT structure, a CS_CONNECTION structure, or a CS_COMMAND structure as a parameter. REMAP="BO--Body"An application must allocate these structures (via MOREINFO="NONE"cs_ctx_alloc, MOREINFO="NONE"ct_con_alloc, or MOREINFO="NONE"ct_cmd_alloc) before using them as parameters.ID="IN4210-18119189"Parameterspassing an invalid structure pointerREMAP="BO--Body"If an application passes an invalid structure pointer to a Client-Library routine, the routine returns CS_FAIL but Client-Library does not call the application`s client message callback routine. This is because Client-Library stores the location of the client message callback in the CS_CONTEXT, CS_CONNECTION, and CS_COMMAND structures.ID="IN4210-18119190"Parametersitem numbers as parametersRENDERAS="SECT2"Item NumbersID="IN4212-18119191"Item numbersas parametersREMAP="BO--Body"Many Client-Library routines that process results or return information about results take an "item number" as a parameter. An item number identifies a result item in a result set, and can be a column number, a compute column number, a parameter number, or a return status number. ID="IN4212-20121192"Item numbersand ct_res_infoREMAP="BO--Body"Item numbers start at 1 and never exceed the number of items in the current result set. An application can call MOREINFO="NONE"ct_res_info with type as CS_NUMDATA to get the number of items in the current result set.REMAP="BO--Body"When the result set contains columns, item is a column number. Columns are returned to an application in select-list order.REMAP="BO--Body"When the result set contains compute columns, item is the column number of a compute column. Compute columns are returned in the order in which they are listed in the compute clause. REMAP="BO--Body"When the result set contains parameters, item is a parameter number. Stored procedure return parameters are returned in the same order as the parameters were originally specified in the stored procedure's MOREINFO="NONE"create procedure statement. This is not necessarily the same order as specified in the RPC command that invoked the stored procedure. In determining what number to pass as item do not count non-return parameters. For example, if the second parameter in a stored procedure is the only return parameter, pass item as 1. REMAP="BO--Body"When the result set contains a return status, item is always 1, as there can be only a single status in a return status result set.ID="X49197" RENDERAS="SECT2"ID="IN4216-28129193"action parameter
action, buffer, buflen, and outlenREMAP="BO--Body"Many Client-Library routines use some combination of the parameters action, buffer, buflen, and outlen. REMAP="RI--RefIndent"ID="IN4210-30131194"Parametersaction parameter
action describes whether to set or retrieve information. For most routines, action can take the symbolic values CS_GET, CS_SET, and CS_CLEAR.REMAP="UN--Under"If action is CS_CLEAR, buffer must be NULL and buflen must be CS_UNUSED.ID="IN4210-32133195"Parametersbuffer parameter
buffer is typically a pointer to program data space.REMAP="UN--Under"If information is being set, buffer points to the value to use in setting the information.REMAP="UN--Under"If information is being retrieved, buffer points to the space in which the Client-Library routine will place the requested information.REMAP="UN--Under"If information is being cleared, buffer must be NULL.REMAP="UN--Under"If the Client-Library routine returns CS_FAIL, *buffer remains unchanged.ID="IN4210-34135196"Parametersbuflen parameter
buflen is the length, in bytes, of the buffer data space. REMAP="UN--Under"If information is being set and the value in *buffer is null-terminated, pass buflen as CS_NULLTERM.REMAP="UN--Under"If *buffer is a fixed-length value, a symbolic value, or a function, buflen must be CS_UNUSED.REMAP="UN--Under"If buffer is NULL, buflen must be 0 or CS_UNUSED.ID="IN4210-36137197"Parametersoutlen parameter
outlen is a pointer to an integer variable. REMAP="UN--Under"outlen must be NULL if information is being set.REMAP="UN--Under"When information is being retrieved, outlen is an optional parameter. If supplied, Client-Library sets the variable to the length, in bytes, of the requested information (including a null terminator, if applicable).REMAP="UN--Under"If the information is longer than buflen bytes, an application can use the value of *outlen to determine how many bytes are needed to hold the information. ID="IN4210-38139198"Parametersinteraction between action, buffer, buflen, outlen parametersREMAP="UN--Under"The following table summarizes the interaction between action, buffer, buflen, and outlen:TOCENTRY="1"LBL="Table 2-27: "Interaction between action, buffer, buflen, and outlenCOLS="5" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="65*"COLNAME="C2" COLWIDTH="93*"COLNAME="C3" COLWIDTH="92*"COLNAME="C4" COLWIDTH="62*"COLNAME="C5" COLWIDTH="155*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"action:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"buffer:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"buflen:COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"outlen:COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"What HappensVALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CLEARCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_UNUSEDCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The Client-Library information 
is cleared by resetting it to its 
default value.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to a 
null-terminated 
character string.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_NULLTERM 
or the length of 
the string, not 
including the 
null terminator.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The Client-Library information 
is set to the value of the *buffer 
character string.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to a 
character string 
that is not null-
terminated.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The length of the 
string.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The Client-Library information 
is set to the value of the *buffer 
character string.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to a 
variable-length, 
non-character 
value. (For 
example, binary 
data.)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The length of the 
data.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The Client-Library information 
is set to the value of the *buffer 
data.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to a 
fixed-length or 
symbolic value.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_UNUSEDCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The Client-Library information 
is set to the value of the integer 
or symbolic value.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"0 or CS_UNUSEDCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The Client-Library information 
is set to NULL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_GETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to 
space large 
enough for the 
return character 
string plus a null 
terminator.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The length of 
*buffer.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Supplied 
or NULLCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The return value is copied to 
*buffer.

A null-terminator is appended.
If supplied, *outlen is set to the 
length of the return value, 
including the null terminator.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_GETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to 
space that is not 
large enough for 
the return 
character string 
plus a null 
terminator.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The length of 
*buffer.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Supplied 
or NULLCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No data is copied to *buffer.

If supplied, *outlen is set to the 
length of the return value, 
including the null terminator.

The routine returns CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_GETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to 
space that is large 
enough for the 
return variable-
length, non-
character data.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The length of 
*buffer.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Supplied 
or NULLCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The return value is copied to 
*buffer.
If supplied, *outlen is set to the 
length of the return value.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_GETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to 
space that is not 
large enough for 
the return 
variable-length, 
non-character 
data.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The length of 
*buffer.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Supplied 
or NULLCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No data is copied to *buffer.

If supplied, *outlen is set to the 
length of the return value.

The routine returns CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_GETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to 
space that is 
assumed to be 
large enough for 
a fixed-length or 
symbolic value.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_UNUSEDCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Supplied 
or NULLCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The return value is copied to 
*buffer.
If supplied, *outlen is set to the 
length of the return value.REMAP="BO--Body"ID="X81031" RENDERAS="SECT1"PropertiesREMAP="BO--Body"Properties define aspects of Client-Library behavior. For example, the CS_NETIO property determines whether a connection is synchronous or asynchronous, and the CS_HIDDEN_KEYS property determines whether or not hidden keys returned as part of a result set are exposed.REMAP="BO--Body"Login properties are used when logging into a server. Login properties include CS_USERNAME, CS_PASSWORD, and CS_PACKETSIZE.ID="IN42109925"Propertiesnegotiated properties
ID="IN42109923"Propertieslogin properties
ID="IN42169924"Login properties
ID="IN42219926"Negotiated propertiesREMAP="BO--Body"A server can change the values of some login properties during the log-in process. For example, if an application sets CS_PACKETSIZE to 2048 bytes and then logs into a server that cannot support this packet size, the server will overwrite 2048 with a packet size it can support. These types of properties are called negotiated properties.ID="IN42109927"Propertiessetting and retrieving propertiesRENDERAS="SECT2"Setting and Retrieving PropertiesID="IN42109748"PropertiesPropertiesand ct_configct_configREMAP="BO--Body"An application calls MOREINFO="NONE"ct_configID="IN42109569"PropertiesPropertiesand ct_con_propsct_con_props
, MOREINFO="NONE"ct_con_propsID="IN421093810"PropertiesPropertiesand ct_cmd_propsct_cmd_props
, and MOREINFO="NONE"ct_cmd_propsID="IN4210911011"PropertiesPropertiesand cs_configcs_config
to set and retrieve Client-Library properties at the context, connection, and command structure levels, respectively. An application calls MOREINFO="NONE"cs_config to set and retrieve CS-Library context properties.ID="IN4210911012"Propertiesdefault valuesREMAP="BO--Body"When a connection structure is allocated, it picks up default property values from its parent context. For example, if CS_TEXTLIMIT is set to 16,000 at the context level, then any connection created within this context will have a default text limit value of 16,000. Likewise, when a command structure is allocated, it picks up default property values from its parent connection.REMAP="BO--Body"An application can override a default property value by calling MOREINFO="NONE"cs_config, MOREINFO="NONE"ct_config, MOREINFO="NONE"ct_con_props, or MOREINFO="NONE"ct_cmd_props to change the value of the property.REMAP="BO--Body"Most properties' values can be either set or retrieved by an application, but some properties are "retrieve only."ID="IN4210911013"Propertiestypes of context propertiesRENDERAS="SECT2"Three Kinds of Context PropertiesREMAP="BO--Body"There are actually three kinds of context properties:MARK="BULL" REMAP="BU--Bullet"Context properties specific to CS-LibraryContext properties specific to Client-LibraryContext properties specific to Server-LibraryREMAP="BO--Body"ID="IN4218891214"Context propertiesContext propertiesand cs_configcs_config
MOREINFO="NONE"cs_config sets and retrieves the values of CS-Library-specific context properties. With the exception of CS_LOC_PROP, properties set via MOREINFO="NONE"cs_config affect only CS-Library. CS-Library-specific context properties are listed on the manual page for MOREINFO="NONE"cs_config in the Common Libraries Reference Manual.REMAP="BO--Body"ID="IN4218871415"Context propertiesContext propertiesand ct_configct_config
MOREINFO="NONE"ct_config sets and retrieves the values of Client-Library-specific context properties. Properties set via MOREINFO="NONE"ct_config affect only Client-Library. Client-Library-specific context properties are listed in LINKEND="X21885"Table 2-28: Client-Library properties
.REMAP="BO--Body"ID="IN4218851616"Context propertiesContext propertiesand srv_propssrv_props
MOREINFO="NONE"srv_props sets and retrieves the values of Server-Library-specific context properties. Properties set via MOREINFO="NONE"srv_props affect only Server-Library.ID="IN4210851617"Propertiescopying login properties
ID="IN4216851618"Login propertiescopying to new connectionRENDERAS="SECT2"Copying Login PropertiesREMAP="BO--Body"An application can copy login properties from an established connection to a new connection structure. To do this, an application:NUMERATION="ARABIC" REMAP="S1--StepOne" CONTINUATION="RESTARTS" INHERITNUM="IGNORE"Allocates a connection structure (MOREINFO="NONE"ct_con_alloc).Customizes the connection (MOREINFO="NONE"ct_con_props).Opens the connection (MOREINFO="NONE"ct_connect).Calls MOREINFO="NONE"ct_getloginfo to allocate a CS_LOGINFO structure and copy the connection`s login properties into it.Allocates a second connection structure (MOREINFO="NONE"ct_con_alloc).Calls MOREINFO="NONE"ct_setloginfo to copy login properties from the CS_LOGINFO structure to the second connection structure. After copying the properties, MOREINFO="NONE"ct_setloginfo de-allocates the CS_LOGINFO structure.Customizes any non-login properties in the second connection (MOREINFO="NONE"ct_con_props).Opens the second connection (MOREINFO="NONE"ct_connect).ID="IN4210831819"PropertiesSummary of Properties tableRENDERAS="SECT2"Summary of PropertiesREMAP="BO--Body"The following table lists Client-Library properties. The context properties in this table are set via MOREINFO="NONE"ct_config. For a list of context properties set via MOREINFO="NONE"cs_config, see the manual page for MOREINFO="NONE"cs_config in the Open Client and Open Server Common Libraries Reference Manual.TOCENTRY="1"LBL="Table 2-28: " ID="X21885"Client-Library properties COLS="5" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="105*"COLNAME="C2" COLWIDTH="116*"COLNAME="C3" COLWIDTH="101*"COLNAME="C4" COLWIDTH="65*"COLNAME="C5" COLWIDTH="88*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Property name:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"What it is:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Possible values:COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Applicable 
at what 
level?COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NotesVALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_ANSI_BINDSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether or not to use 
ANSI-style binds.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE or 
CS_FALSE.

The default is 
CS_FALSE.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context,
connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_APPNAMECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The application name 
used when logging into 
the server.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A character string.

The default is 
NULL.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Login property.
Cannot be set 
after connection 
is established.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_ASYNC_
NOTIFSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether a connection 
will receive registered 
procedure 
notifications 
asynchronously.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE or 
CS_FALSE.

The default is 
CS_FALSE.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BULK_LOGINCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether or not a 
connection is enabled 
to perform bulk copy 
"in" operations. COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE or 
CS_FALSE.

The default is 
CS_FALSE.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Login property.
Cannot be set 
after connection 
is established.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CHARSETCNVCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether or not 
character set 
conversion is taking 
place.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE or 
CS_FALSE.

A default is not 
applicable.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieve only, 
after connection 
is established.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_COMMBLOCKCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to a 
communication 
sessions block.

This property is 
specific to IBM-370 
systems and is ignored 
by all other platforms.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer value.

The default is 
NULL.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Cannot be set 
after connection 
is established.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CON_STATUSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The connection's 
status.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A CS_INT-sized bit-
mask.
For a list of possible 
values, see 
"Connection 
Status" .COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieve only. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CUR_IDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The cursor's 
identification number.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An integer value.

A default is not 
applicable.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Command.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieve only, 
after CS_CUR_
STATUS 
indicates an 
existing cursor.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CUR_NAMECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The cursor's name, as 
defined in an 
application's 
MOREINFO="NONE"ct_cursor(CS_CURSOR
_DECLARE) call.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A character string.

A default is not 
applicable.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Command.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieve only, 
after MOREINFO="NONE"ct_cursor(CS_CURSOR_
DECLARE) 
returns 
CS_SUCCEED.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CUR_ROW
COUNTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The current value of 
cursor rows. Cursor 
rows is the number of 
rows returned to 
Client-Library per 
internal fetch request.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An integer value.

A default is not 
applicable.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Command.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieve only, 
after CS_CUR_
STATUS 
indicates an 
existing cursor.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CUR_STATUSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The cursor's status.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A CS_INT-sized bit-
mask.
For a list of possible 
values, see "Cursor 
Status" .COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Command.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieve only. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DIAG_
TIMEOUTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"When in-line error 
handling is in effect, 
whether Client-
Library should fail or 
retry on timeout errors.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE or 
CS_FALSE.

The default is 
CS_FALSE, which 
means Client-
Library should 
retry.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DISABLE_
POLLCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether or not to 
disable polling. If 
polling is disabled, 
MOREINFO="NONE"ct_poll does not report 
asynchronous 
operation completions.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE or 
CS_FALSE.

The default is 
CS_FALSE, which 
means that polling 
is not disabled.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context, 
connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Useful in 
layered 
asynchronous 
applications.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_EED_CMDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to a 
command structure 
containing extended 
error data.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer value.

A default is not 
applicable.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieve only.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_ENDPOINTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The file descriptor for a 
connection.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An integer value.

A default is not 
applicable.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieve only, 
after connection 
is established.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_EXPOSE_FMTSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether or not to 
expose results of type 
CS_ROWFMT_
RESULT and CS_COM
PUTEFMT_RESULT.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE or 
CS_FALSE.

The default is 
CS_FALSE.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context,
connectionCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Cannot be set 
after connection 
is established.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_EXTRA_INFCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether or not to 
return the extra 
information that's 
required when 
processing Client-
Library messages in-
line using a SQLCA, 
SQLCODE, or 
SQLSTATE.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE or 
CS_FALSE.

The default is 
CS_FALSE.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context,
connectionCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_HIDDEN_KEYSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether or not to 
expose hidden keys.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE or 
CS_FALSE.

The default is 
CS_FALSE.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context,
connection, 
command.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Cannot be set at 
the command 
level if results are 
pending or a 
cursor is open.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_HOSTNAMECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The host machine 
name.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A character string.

The default is 
NULL.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Login property.
Cannot be set 
after connection 
is established.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_IFILECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The path and name of 
the interfaces file.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A character string.
The default varies by 
platform. On UNIX 
platforms, the default 
is 
$SYBASE/interfaces.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_LOC_PROPCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A CS_LOCALE 
structure that defines 
localization 
information.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A CS_LOCALE 
structure.

A connection picks 
up default 
localization 
information from its 
parent context.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.

To set 
CS_LOC_
PROP at the 
context 
level, call 
MOREINFO="NONE"cs_config.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Login property.
Cannot be set 
after connection 
is established.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_LOGIN_
STATUSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether or not the 
connection is open.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE or 
CS_FALSE.

A default is not 
applicable.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieve only.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_LOGIN_
TIMEOUTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The login timeout 
value.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An integer value.

The default is 60 
seconds. A value of 
CS_NO_LIMIT 
represents an 
infinite timeout 
period.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_MAX_
CONNECTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The maximum number 
of connections for this 
context.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An integer value.
The default varies 
by platform. On 
UNIX platforms, 
the default is 25.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_MEM_POOLCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A memory pool that 
Client-Library will use 
to satisfy interrupt-
level memory 
requirements.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer value.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Useful in 
asynchronous 
applications.
Cannot be set or 
cleared when 
context has 
connections.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_NETIOCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether network I/O 
is synchronous, fully 
asynchronous, or 
deferred asynchronous.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SYNC_IO, 
CS_ASYNC_IO, or 
CS_DEFER_IO.

The default is 
CS_SYNC_IO.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context,
connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Cannot be set for 
a context with 
open 
connections.

CS_DEFER_IO 
is legal only at 
the context level.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_NO_TRUNCATECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether Client-Library 
should truncate or 
sequence messages that 
are longer than 
CS_MAX_MSG.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE or 
CS_FALSE.

The default is 
CS_FALSE, which 
means that Client-
Library truncates 
long messages.
COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_NOINTERRUPTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether or not the 
application can be 
interrupted.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE or 
CS_FALSE.

The default is 
CS_FALSE, which 
means the 
application can be 
interrupted.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_NOTIF_CMDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to a 
command structure 
containing registered 
procedure notification 
parameters.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer value.

A default is not 
applicable.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieve only.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_PACKETSIZECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The TDS packet size.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An integer value.
The default varies 
by platform. On 
most platforms, the 
default is 512 bytes.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Negotiated login 
property.
Cannot be set 
after connection 
is established.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_PARENT_
HANDLECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The address of a 
command or 
connection structure's 
parent structure.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer value.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection,
command.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieve only.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_PASSWORDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The password used to 
log into the server.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A character string.
The default is 
NULL.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Login property.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SEC_
APPDEFINEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether or not the 
connection will use 
application-defined 
challenge/response 
security handshaking.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE or 
CS_FALSE.

The default is 
CS_FALSE.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Cannot be set 
after connection 
is established.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SEC_
CHALLENGECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether or not the 
connection will use 
Sybase-defined 
challenge/response 
security handshaking.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE or 
CS_FALSE.

The default is 
CS_FALSE.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Cannot be set 
after connection 
is established.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SEC_
ENCRYPTIONCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether or not the 
connection will use 
encrypted password 
security handshaking.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE or 
CS_FALSE.

The default is 
CS_FALSE.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Cannot be set 
after connection 
is established.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SEC_
NEGOTIATECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether or not the 
connection will use 
trusted-user security 
handshaking.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE or 
CS_FALSE.

The default is 
CS_FALSE.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Cannot be set 
after connection 
is established.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SERVERNAMECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The name of the server 
to which a connection 
is connected.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A string value.

A default is not 
applicable.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieve only, 
after connection 
is established.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TDS_VERSIONCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The version of the TDS 
protocol that the 
connection is using.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A symbolic version 
level.
CS_TDS_VERSION 
defaults to a value 
based on 
CS_VERSION.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Negotiated login 
property.
Cannot be set after connection 
is established.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TEXTLIMITCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The largest text or 
image value to be 
returned on this 
connection.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An integer value.

The default is 
CS_NO_LIMIT.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context,
connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TIMEOUTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The timeout value.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An integer value.

The default is 
CS_NO_LIMIT.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRANS
ACTION_NAMECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A transaction name.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A string value.

The default is 
NULL.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_USER_ALLOCCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A user-defined 
memory allocation 
routine.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A user-defined 
function.

A default is not 
applicable.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Useful in 
asynchronous 
application.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_USER_FREECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A user-defined 
memory free routine.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A user-defined 
function.

A default is not 
applicable.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Useful in 
asynchronous 
application.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_USERDATACOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"User-allocated data.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"User-allocated data.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection,
command.
To set 
CS_USERDATA at 
the context 
level, call 
MOREINFO="NONE"cs_config.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_USERNAMECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The name used to log 
into the server.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A character string.

The default is 
NULL.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Login property.
Cannot be set 
after connection 
is established.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_VER_STRINGCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Client-Library's true 
version string.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A character string

A default is not 
applicable.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieve only.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_VERSIONCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The version of Client-
Library in use by this 
context.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A symbolic version 
level.

CS_VERSION gets 
its value from a 
context's MOREINFO="NONE"ct_init call.

Currently, the only 
possible value is 
CS_VERSION_100.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieve only.RENDERAS="SECT2"About the PropertiesID="IN4222812020"CS_ANSI_BINDS propertydetailed description of
ID="IN427812021"Bindingdefining a bind styleID="X18387" RENDERAS="SECT3"ANSI-Style BindsMARK="BULL" REMAP="BU--Bullet"CS_ANSI_BINDSID="IN4216812022"ANSI-style binds
defines whether or not Client-Library will use ANSI-style binds.When ANSI-style binds are in effect:MARK="DASH" REMAP="BS--BulletSub"It is considered an error to bind some, but not all, items in a result set. An application must either bind none of the items or bind all of the items. MOREINFO="NONE"ct_fetch raises an error when copying a NULL or truncated character string value into a variable with which no indicator is associated. REMAP="UN--Under"In both of these cases, MOREINFO="NONE"ct_fetch returns CS_ROW_FAIL.ID="IN4219792223"CS_APPNAME propertydetailed description of
ID="IN4212792224"Applicationsapplication name propertyRENDERAS="SECT3"Application NameMARK="BULL" REMAP="BU--Bullet"CS_APPNAME defines the application name that a connection will use when connecting to a server.SQL Server uses application names to identify connection processes in the sysprocesses table of the master database.ID="IN4224772425"CS_ASYNC_NOTIFS propertydetailed description of
ID="IN4221772426"Registered proceduresasynchronous notifications propertyRENDERAS="SECT3"Asynchronous NotificationsMARK="BULL" REMAP="BU--Bullet"CS_ASYNC_NOTIFS determines whether a connection will receive registered procedure notifications asynchronously.If CS_ASYNC_NOTIFS is set to CS_TRUE, then Client-Library interrupts the application to report an arriving registered procedure notification. When Client-Library reports the notification, the application's notification callback is automatically triggered.If CS_ASYNC_NOTIFS is CS_FALSE, then the application must be reading from the network in order for Client-Library to report a registered procedure notification. When Client-Library reports the notification, the application's notification callback is automatically called.REMAP="UN--Under"Likewise, if CS_ASYNC_NOTIFS is CS_FALSE, MOREINFO="NONE"ct_poll will not read from the network. This means that an application must be reading results in order for MOREINFO="NONE"ct_poll to report a registered procedure notification. When MOREINFO="NONE"ct_poll reports the notification, the application's notification callback is automatically called.Setting CS_ASYNC_NOTIFS to CS_FALSE does not immediately turn asynchronous notifications off. In order to truly turn asynchronous notifications off, an application must send a command to the server after setting CS_ASYNC_NOTIFS to CS_FALSE.CS_ASYNC_NOTIFS is the only property that determines whether notifications are received asynchronously:MARK="DASH" REMAP="BS--BulletSub"An otherwise synchronous connection can receive asynchronous notifications.An asynchronous connection will not receive notifications asynchronously unless it sets CS_ASYNC_NOTIFS to CS_TRUE.For information on registered procedures, see the LINKEND="X72967""Registered Procedures"
topics page.ID="IN4222752627"CS_BULK_LOGIN propertydetailed description of
ID="IN429752628"Bulk copybulk copy operations propertyRENDERAS="SECT3"Bulk Copy OperationsMARK="BULL" REMAP="BU--Bullet"CS_BULK_LOGIN describes whether or not a connection can perform bulk copy operations into a database.Applications that allow users to make ad hoc queries may want to avoid setting this property to CS_TRUE, to keep users from initiating a bulk copy sequence via SQL commands. Once a bulk copy sequence is begun, it cannot be stopped with an ordinary SQL command.For information on Bulk Copy, see the Common Libraries Reference Manual.ID="IN4222732829"CS_CHARSETCNV propertydetailed description of
ID="IN4214732830"Character setscharacter set conversion property
ID="IN4210732831"Conversionbetween client and server character setsRENDERAS="SECT3"Character Set ConversionMARK="BULL" REMAP="BU--Bullet"CS_CHARSETCNV describes whether or not the server is converting between the client and server character sets. This property is retrieve-only, after a connection is established.A value of CS_TRUE indicates that the server is converting between the client and server character sets; CS_FALSE indicates that no conversion is taking place.ID="IN4221713032"CS_COMMBLOCK propertydetailed description of
ID="IN4238713033"Communications sessions block propertyRENDERAS="SECT3"Communications Session BlockMARK="BULL" REMAP="BU--Bullet"The CS_COMMBLOCK property defines a pointer to a communications block. This property is specific to IBM-370 systems and is ignored by all other platforms.ID="IN4211713034"Connectionsdetermining if dead
ID="IN4211713035"Connectionsdetermining status of
ID="IN4226713036"Connection status property
ID="IN4222693237"CS_CON_STATUS propertydetailed description ofID="X64583" RENDERAS="SECT3"Connection StatusMARK="BULL" REMAP="BU--Bullet"CS_CON_STATUS is a CS_INT-sized bit-mask that reflects a connection's current status.The following table lists the symbolic values that can make up CS_CON_STATUS:TOCENTRY="1"LBL="Table 2-29: "Bit values for the CS_CON_STATUS propertyCOLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="153*"COLNAME="C2" COLWIDTH="207*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Symbolic Value:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CONSTAT_CONNECTEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The connection is open.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CONSTAT_DEADCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The connection has been marked as "dead."

Client-Library marks a connection as dead if 
errors have made it unusable or if an 
application's client message callback 
routine returns CS_FAIL.

An application must call MOREINFO="NONE"ct_close and 
MOREINFO="NONE"ct_con_drop to close and drop connections 
that have been marked as dead.

An exception to this rule occurs for certain 
types of results-processing errors. If a 
connection is marked dead while processing 
results, the application can try calling 
MOREINFO="NONE"ct_cancel(CS_CANCEL_ALL or 
CS_CANCEL_ATTN) to "revive" the 
connection. If this fails, the application must 
close and drop the connection.ID="IN4218693238"Cursor ID property
ID="IN4218673439"CS_CUR_ID propertydetailed description ofID="X34825" RENDERAS="SECT3"Cursor IDMARK="BULL" REMAP="BU--Bullet"CS_CUR_ID is the server identification number assigned to a cursor. An application can retrieve a cursor's identification number after calling MOREINFO="NONE"ct_cmd_props(CS_CUR_STATUS) to confirm that a cursor exists in the command space of interest.CS_CUR_ID is a command structure property and cannot be retrieved at the connection or context levels. Cursor properties are useful to gateway applications that send cursor information to clients.ID="IN4220673440"Cursor name property
ID="IN4220653641"CS_CUR_NAME propertydetailed description ofID="X80859" RENDERAS="SECT3"Cursor NameMARK="BULL" REMAP="BU--Bullet"CS_CUR_NAME is the name with which a cursor was declared. An application declares a cursor by calling MOREINFO="NONE"ct_cursor(CS_CURSOR_DECLARE).An application can retrieve a cursor's name any time after its MOREINFO="NONE"ct_cursor(CS_CURSOR_DECLARE) call returns CS_SUCCEED.CS_CUR_NAME is a command structure property and cannot be retrieved at the connection or context levels. Cursor properties are useful to gateway applications that send cursor information to clients.ID="IN4224653642"Cursor rowcount property
ID="IN4224633843"CS_CUR_ROWCOUNT propertydetailed description ofID="X32319" RENDERAS="SECT3"Cursor RowcountMARK="BULL" REMAP="BU--Bullet"CS_CUR_ROWCOUNT is the current value of cursor rows for a cursor.Cursor rows is the number of rows returned to Client-Library per internal fetch request. Note that this is not the number of rows returned to an application per MOREINFO="NONE"ct_fetch call. For more information on cursor rows, see LINKEND="X11788""Dynamic SQL Cursor Option" 
.An application can retrieve CS_CUR_ROWCOUNT after calling MOREINFO="NONE"ct_cmd_props(CS_CUR_STATUS) to confirm that a cursor exists in the command space of interest.CS_CUR_ROWCOUNT is a command structure property and cannot be retrieved at the connection or context levels. Cursor properties are useful to gateway applications that send cursor information to clients.ID="IN4222633844"Cursor status property
ID="IN4222614045"CS_CUR_STATUS propertydetailed description ofID="X18759" RENDERAS="SECT3"Cursor StatusMARK="BULL" REMAP="BU--Bullet"CS_CUR_STATUS is a CS_INT-sized bit-mask that reflects a cursor's current status.The following table lists the symbolic values that can make up CS_CUR_STATUS:TOCENTRY="1"LBL="Table 2-30: "Bit values for the CS_CUR_STATUS propertyCOLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="144*"COLNAME="C2" COLWIDTH="216*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Symbolic Value:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CURSTAT_CLOSEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A closed cursor exists in the command space. 
An application can re-open a closed cursor.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CURSTAT_DECLAREDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A cursor is currently declared in this 
command space.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CURSTAT_NONECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No cursor is declared in this command space.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CURSTAT_OPENCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An open cursor exists in the command space.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CURSTAT_RDONLYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The cursor is read-only and cannot be used to 
perform updates.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CURSTAT_UPDATABLECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The cursor can be used to perform updates.ID="IN4213614046"Cursor statusguaranteed accuracyCursor status is guaranteed to be accurate:MARK="DASH" REMAP="BS--BulletSub"After MOREINFO="NONE"ct_results returns CS_SUCCEED with a *result_type parameter of CS_CMD_SUCCEED, CS_CMD_FAIL, or CS_CURSOR_RESULTAfter MOREINFO="NONE"ct_cancel(MOREINFO="NONE"CS_CANCEL_ALL) returns CS_SUCCEEDAfter any Client-Library or CS-Library routine returns CS_CANCELEDCalling MOREINFO="NONE"ct_cancel can cause a connection's cursors to enter an undefined state. An application can use the cursor status property to determine how a cancel operation has affected a cursor.CS_CUR_STATUS is a command structure property and cannot be retrieved at the connection or context levels. ID="IN4220614047"Gateway applicationsGateway applicationsand cursor informationcursor informationCursor properties are useful to gateway applications that send cursor information to clients.ID="IN4224594248"CS_DIAG_TIMEOUT propertydetailed description ofRENDERAS="SECT3"Diagnostic Timeout FailID="IN4224594249"In-line message handlingClient-Library timeout errorsMARK="BULL" REMAP="BU--Bullet"When in-line error handling is in effect, the CS_DIAG_TIMEOUT property determines whether Client-Library fails or retries on Client-Library timeout errors.If CS_DIAG_TIMEOUT is CS_TRUE, Client-Library marks a connection as dead when a Client-Library routine generates a timeout error.If CS_DIAG_TIMEOUT is CS_FALSE, Client-Library retries indefinitely when a Client-Library routine generates a timeout error. ID="IN427594250"Pollingdisabling
ID="IN4224594251"Asynchronous programmingdisabling polling
ID="IN4224574452"CS_DISABLE_POLL propertydetailed description ofRENDERAS="SECT3"Disable PollMARK="BULL" REMAP="BU--Bullet"The CS_DISABLE_POLL property determines whether or not MOREINFO="NONE"ct_poll reports asynchronous operation completions.ID="IN4220574453"Layered applicationsasynchronous programming:preventing report of routine completionsLayered asynchronous applications can use CS_DISABLE_POLL to prevent MOREINFO="NONE"ct_poll from reporting low-level asynchronous completions.An application cannot call MOREINFO="NONE"ct_wakeup if the CS_DISABLE_POLL property is set to CS_TRUE.For more information on CS_DISABLE_POLL, see LINKEND="X56944""Layered Applications" 
.ID="IN4219554654"CS_EED_CMD propertydetailed description of
ID="IN4228554655"Extended error data propertyRENDERAS="SECT3"Extended Error Data Command StructureMARK="BULL" REMAP="BU--Bullet"The CS_EED_CMD property defines a pointer to a CS_COMMAND structure containing extended error data.ID="IN4223554656"Server message callbackextended error dataWithin a server message callback, Client-Library indicates that extended error data is available by setting the CS_HASEED bit of the status field of the CS_SERVERMSG structure describing the message.It is an error to retrieve CS_EED_CMD if no extended error data is available.For more information on extended error data, see LINKEND="X78290""Extended Error Data" 
.RENDERAS="SECT3"Endpoint PollingMARK="BULL" REMAP="BU--Bullet"CS_ENDPOINT allows an application to get a file descriptor, the number associated with a connection to a remote server. This can be useful to a gateway application that contains both Client-Library and Server-Library calls: after establishing a connection to a remote server with Client-Library, the file descriptor associated with that connection can be used by the MOREINFO="NONE"srv_poll Server-Library routine. A call to MOREINFO="NONE"srv_poll causes the current thread to be rescheduled until there are results available on the connection.Use of the CS_ENDPOINT property is discouraged, since it is currently specific only to UNIX platforms.ID="IN4223534857"CS_EXPOSE_FMTS propertydetailed description of
ID="IN4223534858"Expose formats property
ID="IN427534859"Formatsexpose formats propertyRENDERAS="SECT3"Expose FormatsMARK="BULL" REMAP="BU--Bullet"CS_EXPOSE_FMTS determines whether or not Client-Library exposes format result sets.ID="IN4217534860"Format result setdescription ofA format result set contains format information for the result set with which it is associated. Format information includes the number of items in the result set and a description of each item. There are two types of format result sets:MARK="DASH" REMAP="BS--BulletSub" ID="IN4228515061"CS_ROWFMT_RESULT result type
CS_ROWFMT_RESULT. This type of format result set contains format information for a regular row result set.ID="IN4238495262"CS_COMPUTEFMT_RESULT format result set
CS_COMPUTEFMT_RESULT. This type of format result set contains format information for a compute row result set.All format result sets generated by a command precede the regular row and compute row result sets generated by the command.If format result sets are not exposed, an application can only retrieve format information while it is processing a result set. For example, after MOREINFO="NONE"ct_results returns CS_ROW_RESULT the application can call MOREINFO="NONE"ct_res_info to determine the number of columns in the result set, MOREINFO="NONE"ct_describe to get a description of each column, etc.REMAP="UN--Under"Exposing format result sets allows an application to retrieve format information before processing a result set. ID="IN4220495263"Gateway applicationsrepackaging SQL Server resultsExposing format result sets is useful in gateway applications that need to repackage SQL Server results before sending them on to a foreign client.An application can expose format result sets by setting the CS_EXPOSE_FMTS property to CS_TRUE.For more information on format results, see LINKEND="X17247""Format Results" 
.ID="IN4221475464"CS_EXTRA_INF propertydetailed description of
ID="IN4226475465"Extra information propertyRENDERAS="SECT3"Extra InformationMARK="BULL" REMAP="BU--Bullet"CS_EXTRA_INF determines whether or not Client-Library returns the extra information that MOREINFO="NONE"ct_diag requires to fill in a SQLCA, SQLCODE, or SQLSTATE structure.ID="IN424475466"Rowsnumber of rows affected by most recent commandThis extra information includes the number of rows affected by the most recent command.If an application is not retrieving messages into a SQLCA, SQLCODE, or SQLSTATE, the extra information is returned as ordinary Client-Library messages.ID="IN4223455667"CS_HIDDEN_KEYS propertydetailed description of
ID="IN4220455668"Hidden keys property
ID="IN4211455669"Key columnsexposing hidden keys
ID="IN4220455670"Exposing hidden keysRENDERAS="SECT3"Hidden KeysMARK="BULL" REMAP="BU--Bullet"CS_HIDDEN_KEYSID="IN4211455671"Hidden keysdefinition of
determines whether or not Client-Library exposes any "hidden keys" that are part of a result set. Hidden keys are columns that are not explicitly selected in a query, but which are returned to a client because they make up part or all of a table's key.REMAP="UN--Under"Ordinarily, the presence of these columns is suppressed. The client is not aware that they are a part of the result set.A client can expose hidden keys by setting the CS_HIDDEN_KEYS property to CS_TRUE. ID="IN4211435872"Hidden keysHidden keysand ct_res_infoct_res_infoOnce hidden keys are exposed, they are returned as ordinary columns. If an application calls MOREINFO="NONE"ct_res_info to retrieve the number of columns in a result set, for example, the number will include exposed columns. An application can bind and fetch the row values of exposed columns.ID="IN4211416073"Hidden keysHidden keysand ct_describect_describeIf a column is an exposed hidden key, MOREINFO="NONE"ct_describe includes CS_HIDDEN in the status field bit mask describing the column.An application can use MOREINFO="NONE"ct_keydata with a table's keys to change a cursor's position. For information on how to do this, see the MOREINFO="NONE"ct_keydata manual page.ID="IN4223396274"CS_HIDDEN_KEYS propertywhen not settableAn application cannot set the CS_HIDDEN_KEYS property at the command level if results are pending or a cursor is open.ID="IN4220376475"CS_HOSTNAME propertydetailed description of
ID="IN4218376476"Host name propertyRENDERAS="SECT3"Host NameMARK="BULL" REMAP="BU--Bullet"CS_HOSTNAME is the name of the host machine, used when logging in to a server.ID="IN4210376477"SQL Serverwhere a processÕ s host name is listedSQL Server lists a process' host name in the sysprocesses table of the master database.ID="IN4220356678"CS_LOC_PROP propertydetailed description of
ID="IN4227356679"Locale information propertyRENDERAS="SECT3"Locale InformationMARK="BULL" REMAP="BU--Bullet"CS_LOC_PROP defines a CS_LOCALE structure that contains localization values. Localization values include a language, a character set, datetime formats, and a collating sequence.ID="IN4212336880"LocalizationLocalizationand ct_con_propsct_con_propsAn application can call MOREINFO="NONE"ct_con_props to set or retrieve CS_LOC_PROP at the connection level.MARK="DASH" REMAP="BS--BulletSub"When setting CS_LOC_PROP, an application passes MOREINFO="NONE"ct_con_props a CS_LOCALE structure. MOREINFO="NONE"ct_con_props copies information from the CS_LOCALE and stores it internally. After calling MOREINFO="NONE"ct_con_props, the application can de-allocate the CS_LOCALE.When retrieving CS_LOC_PROP, an application passes MOREINFO="NONE"ct_con_props a CS_LOCALE structure. MOREINFO="NONE"ct_con_props copies current localization information into this CS_LOCALE. A connection picks up default localization information from its parent context.An application can call MOREINFO="NONE"cs_loc_alloc to allocate a CS_LOCALE structure.ID="IN4212317081"LocalizationLocalizationand cs_configcs_configAn application can call MOREINFO="NONE"cs_config to set or retrieve CS_LOC_PROP at the context level.If an application does not call MOREINFO="NONE"cs_config to define localization information for a context, the context uses default localization values that are assigned at allocation time. On most platforms, environment variables determine the default values. For specific information on how default localization values are assigned on your platform, see the Open Client/Server Supplement.ID="IN4217297282"CS_IFILE propertydetailed description of
ID="IN4215297283"Interfaces fileinterfaces file property
ID="IN427297284"Serversinterfaces file
ID="IN4210297285"SQL Serverspecifying a server to connect toRENDERAS="SECT3"Location of the Interfaces FileMARK="BULL" REMAP="BU--Bullet"CS_IFILE defines the name and location of the interfaces file.ID="IN4215297286"Interfaces filedetailed description of
ID="IN4215277487"Interfaces fileInterfaces fileand ct_connectct_connectThe interfaces file contains the name and network address of every server available on the network. It establishes communication between clients and servers. For every server to which a client might connect, the interfaces file contains an entry which includes the server name, the machine name, and the address of that server. For Client-Library applications, the interfaces file is searched during every call to MOREINFO="NONE"ct_connect. On most platforms, if a particular interfaces file has not been specified via MOREINFO="NONE"ct_config, MOREINFO="NONE"ct_connect attempts to use a file named interfaces in the directory named by the SYBASE environment variable or logical name. If SYBASE has not been set, MOREINFO="NONE"ct_connect attempts to use a file named interfaces in the home directory of the user named "sybase"For more information on the interfaces file, see the SYBASE Installation Guide. Not all platforms use an interfaces file. If you do not know whether your platform uses an interfaces file, consult your SYBASE System Administrator or see the SYBASE SQL Server Installation Guide for your platform.ID="IN4224257688"CS_LOGIN_STATUS propertydetailed description ofID="IN4221257689"Login status propertyRENDERAS="SECT3"Login StatusMARK="BULL" REMAP="BU--Bullet"CS_LOGIN_STATUS is CS_TRUE if a connection is open, CS_FALSE if it is not. This property can only be retrieved.MOREINFO="NONE"ct_connect is used to open a connection.ID="IN428257690"Timeoutslogin timeout property
ID="IN4225237891"CS_LOGIN_TIMEOUT propertydetailed description of
ID="IN4222237892"Login timeout propertyRENDERAS="SECT3"Login TimeoutMARK="BULL" REMAP="BU--Bullet"CS_LOGIN_TIMEOUT defines the length of time, in seconds, that Client-Library waits for a login response when making a connection attempt. A Client-Library application makes a connection attempt by calling MOREINFO="NONE"ct_connect. The default timeout value is 60 seconds. A timeout value of ID="IN4225218093"CS_NO_LIMIT timeout value
CS_NO_LIMIT represents an infinite timeout period.ID="IN428198294"TimeoutsCS_NO_LIMIT timeout valueREMAP="UN--Under"Note that a timeout value of CS_NO_LIMIT does not apply to asynchronous connections. MOREINFO="NONE"ct_connect calls on asynchronous connections return immediately.ID="IN4223178495"CS_MAX_CONNECT propertydetailed description of
ID="IN4238178496"Maximum number of connections property
ID="IN4211178497"Connectionssetting maximum number of RENDERAS="SECT3"Maximum Number of ConnectionsMARK="BULL" REMAP="BU--Bullet"CS_MAX_CONNECT defines the maximum number of simultaneously open connections that a context can have. ID="IN4223158698"CS_MAX_CONNECT propertydefault value
CS_MAX_CONNECT has a default value of 25. Negative and zero values are not allowed for CS_MAX_CONNECT.If MOREINFO="NONE"ct_config is called to set a value for CS_MAX_CONNECT which is less than the number of currently open connections, MOREINFO="NONE"ct_config raises a Client-Library error and returns CS_FAIL without altering the value of CS_MAX_CONNECT.ID="IN4224158699"Asynchronous programming memory requirements
ID="IN42201586100"Memory pool property
ID="IN42201388101"CS_MEM_POOL propertydetailed description ofRENDERAS="SECT3"Memory PoolMARK="BULL" REMAP="BU--Bullet"CS_MEM_POOL identifies a pool of memory that Client-Library can use to satisfy its memory requirements.Ordinarily, Client-Library routines satisfy their memory requirements by calling MOREINFO="NONE"malloc. However, because not all implementations of MOREINFO="NONE"malloc are re-entrant, it is not safe for Client-Library routines that are called at the interrupt level to use MOREINFO="NONE"malloc. For this reason, asynchronous applications are required to provide an alternate way for Client-Library to satisfy its memory requirements.REMAP="UN--Under"Client-Library provides two mechanisms by which an asynchronous application can satisfy Client-Library's memory requirements:MARK="DASH" REMAP="BS--BulletSub"The application can use the CS_MEM_POOL property to provide Client-Library with a memory pool.The application can use the CS_USER_ALLOC and CS_USER_FREE properties to install memory allocation routines that Client-Library can safely call at the interrupt level.REMAP="UN--Under"If an asynchronous application fails to provide Client-Library with a safe way to satisfy memory requirements, Client-Library's behavior is undefined.MOREINFO="NONE"ct_config returns CS_FAIL if an application attempts to set a memory pool that does not meet Client-Library's minimum pool size requirements. ID="IN42191388102"Memory requirementson UNIX systemsOn UNIX systems, a memory pool should include approximately 6K bytes for each connection. Client-Library attempts to satisfy memory requirements from the following sources in the following order:REMAP="UN--Under"1.  Memory pool.REMAP="UN--Under"2.  User-supplied allocation and free routines.REMAP="UN--Under"3.  System routines.If a connection cannot get the memory it needs, Client-Library marks the connection dead.An application is responsible for allocating and freeing the memory identified by CS_MEM_POOL.ID="IN42111190103"Memory poolreplacing with ct_configAn application can replace a memory pool by calling MOREINFO="NONE"ct_config with action as CS_SET and buffer as the address of the new pool.ID="IN4211992104"Memory poolclearing with ct_configAn application can clear a memory pool in two ways:MARK="DASH" REMAP="BS--BulletSub"By calling MOREINFO="NONE"ct_config with action as CS_SET and buffer as NULLBy calling MOREINFO="NONE"ct_config with action as CS_CLEARAn application cannot set or clear a memory pool for a context in which CS_CONNECTION structures currently exist. A context must drop all CS_CONNECTION structures before clearing a memory pool.ID="IN4217794105"CS_NETIO propertydetailed description of
ID="IN4220794106"Network I/O propertyRENDERAS="SECT3"Network I/OMARK="BULL" REMAP="BU--Bullet"CS_NETIO determines whether a connection is synchronous, fully asynchronous, or deferred asynchronous:MARK="DASH" REMAP="BS--BulletSub"On a synchronous connection, a routine that requires a server response blocks until the response is received.On a fully asynchronous connection, a routine that requires a server response returns CS_PENDING immediately. When the response arrives and the routine completes its work, Client-Library calls the connection's completion callback automatically, at the interrupt level.On a deferred asynchronous connection, a routine that requires a server response returns CS_PENDING immediately. The connection must call MOREINFO="NONE"ct_poll in order to find out if the routine has completed.ID="IN4224794107"Asynchronous programmingsetting up deferred asynchronous connectionsAn application can set up deferred asynchronous connections only at the context level, by calling MOREINFO="NONE"ct_config with *buffer as CS_DEFER_IO. CS_DEFER_IO is not a legal value at the connection level. Asynchronous connections use the type of asynchronous I/O that matches their parent context. For example, suppose an application sets up deferred asynchronous connections at the context level and then creates a synchronous connection within the context. If the application later calls MOREINFO="NONE"ct_con_props with *buffer as CS_ASYNC_IO to make this connection asynchronous, the connection will be deferred asynchronous, not fully asynchronous.A context can include both synchronous and asynchronous connections, but all asynchronous connections within a context must be either fully asynchronous or deferred asynchronous. The following restrictions apply to an application's use of ID="IN4217596108"CS_NETIO propertyrestrictions;Network I/O property:restrictions
CS_NETIO:MARK="DASH" REMAP="BS--BulletSub"An application cannot set CS_NETIO for a context if the context has open connections. An application cannot set CS_NETIO for a connection if the connection has any active commands or pending results.For more information on asynchronous Client-Library programming, see the LINKEND="X80066""Asynchronous Programming"
topics page.ID="IN4223398109"CS_NO_TRUNCATE propertydetailed description of
ID="IN42261100110"Error and message handlingpreventing message truncation:with  CS_NO_TRUNCATE propertyRENDERAS="SECT3"No TruncateMARK="BULL" REMAP="BU--Bullet"CS_NO_TRUNCATE determines whether Client-Library truncates or sequences Client-Library and server messages that are longer than CS_MAX_MSG - 1 bytes.Client-Library's default behavior is to truncate messages that are longer than CS_MAX_MSG - 1 bytes. When Client-Library is sequencing messages, however, it uses as many CS_CLIENTMSG or CS_SERVERMSG structures as necessary to return the full text of a message. The message's first CS_MAX_MSG bytes are returned in one structure, its second CS_MAX_MSG bytes in a second structure, and so forth.Client-Library null terminates only the last chunk of a message. If a message is exactly CS_MAX_MSG bytes long, the message is returned in two chunks: the first containing CS_MAX_MSG bytes of the message and the second containing a null terminator.For more information on sequenced messages, see LINKEND="X74900""Sequencing Long Messages" 
.ID="IN4210-1102111"Interruptspreventing with CS_NOINTERRUPT property
ID="IN4213-3104112"Critical code
ID="IN4223-5106113"CS_NOINTERRUPT propertydetailed description of
ID="IN4221-5106114"No interrupt propertyRENDERAS="SECT3"No InterruptMARK="BULL" REMAP="BU--Bullet"CS_NOINTERRUPT determines whether an application can be interrupted by Client-Library. ID="IN4210-5106115"Interruptsexamples of interrupt situationsExamples of interrupt situations include:MARK="DASH" REMAP="BS--BulletSub"A Client-Library routine running on an asynchronous connection completes, generating an interrupt.A registered procedure notification arrives for an application, generating an interrupt.When CS_NOINTERRUPT is CS_TRUE, interruptions are deferred until CS_NOINTERRUPT is reset to CS_FALSE.An application can use the CS_NOINTERRUPT property to protect critical sections of code.ID="IN4221-5106116"Registered proceduresprocessing notification parameters
ID="IN4221-7108117"CS_NOTIF_CMD propertydetailed description of
ID="IN4231-7108118"Notification parameter propertyRENDERAS="SECT3"Notification ParametersMARK="BULL" REMAP="BU--Bullet"The CS_NOTIF_CMD property defines a pointer to a CS_COMMAND structure containing registered procedure notification parameters.For more information on registered procedures, see the LINKEND="X72967""Registered Procedures"
topics page.ID="IN4222-9110119"CS_PACKETSIZE propertydetailed description of
ID="IN427-9110120"Packetspacket size propertyRENDERAS="SECT3"Packet SizeMARK="BULL" REMAP="BU--Bullet"CS_PACKETSIZEID="IN423-9110121"TDSpacket size property
determines the packet size that Client-Library uses when sending Tabular Data Stream (TDS) packets.If an application needs to send or receive large amounts of text, image, or bulk data, a larger packet size can improve efficiency.ID="IN4225-11112122"CS_PARENT_HANDLE propertydetailed description of
ID="IN4210-11112123"Structuresparent structure propertyRENDERAS="SECT3"Parent StructureMARK="BULL" REMAP="BU--Bullet"CS_PARENT_HANDLE defines a pointer to a command or connection structure's parent structure.If retrieved at the command structure level, CS_PARENT_HANDLE is a pointer to the command structure's parent connection structure.If retrieved at the connection structure level, CS_PARENT_HANDLE is a pointer to the connection structure's parent context structure.ID="IN4220-13114124"CS_PASSWORD propertydetailed description of
ID="IN429-13114125"Passwordspassword propertyRENDERAS="SECT3"PasswordMARK="BULL" REMAP="BU--Bullet"CS_PASSWORD defines the password that a connection uses when logging in to a server.ID="IN4226-15116126"CS_SEC_APPDEFINED propertydetailed description of
ID="IN4211-15116127"Open Serverchallenge/response handshakingRENDERAS="SECT3"Security Application-DefinedMARK="BULL" REMAP="BU--Bullet"CS_SEC_APPDEFINEDID="IN4210-15116128"Handshakeschallenge/response security:application-defined
determines whether or not a connection will use Open Server application-defined challenge/response security handshaking.If a connection is using challenge/response security handshaking, then Client-Library calls the connection's negotiation callback routine when it receives a server challenge.For more information on server challenges, see LINKEND="X40605""Challenge/Response Security Handshakes" 
.ID="IN4225-17118129"CS_SEC_CHALLENGE propertydetailed description of
ID="IN4217-17118130"Secure SQL Serverchallenge/response security handshakesRENDERAS="SECT3"Security ChallengeMARK="BULL" REMAP="BU--Bullet"CS_SEC_CHALLENGEID="IN4210-17118131"Handshakeschallenge/response security:Sybase-defined
determines whether or not a connection will use Sybase-defined challenge/response security handshaking.If a connection is using challenge/response security handshaking, then Client-Library calls the connection's negotiation callback routine when it receives a server challenge.For more information on server challenges, see LINKEND="X40605""Challenge/Response Security Handshakes" 
.ID="IN4226-19120132"CS_SEC_ENCRYPTION propertydetailed description ofRENDERAS="SECT3"Security EncryptionMARK="BULL" REMAP="BU--Bullet"CS_SEC_ENCRYPTIONID="IN4238-19120133"Encrypted password security handshakes
ID="IN4210-19120134"Handshakesencrypted password security
determines whether or not a connection will use encrypted password security handshaking.If a connection is using encrypted password security handshaking, then Client-Library calls the connection's encryption callback routine when it receives a request for an encrypted password.Typical applications do not need to set CS_SEC_ENCRYPTION, which is provided for gateway support.For more information on encrypted passwords, see LINKEND="X70164""Encrypted Password Security Handshakes" 
.ID="IN4225-21122135"CS_SEC_NEGOTIATE propertydetailed description of
ID="IN4217-21122136"Secure SQL Servertrusted-user security handshakesRENDERAS="SECT3"Security NegotiationMARK="BULL" REMAP="BU--Bullet"CS_SEC_NEGOTIATEID="IN4210-21122137"Handshakestrusted-user security
ID="IN4232-21122138"Trusted-user security handshakes
determines whether or not a connection will use trusted-user security handshaking.Trusted-user security handshaking requires a client application to provide identifying security labels to pass to the server during the connection process.ID="IN4215-21122139"Security labelstwo methods of definingThere are two ways for an application to define security labels. An application can use either, or both, of these methods: MARK="DASH" REMAP="BS--BulletSub"The application can call MOREINFO="NONE"ct_labels one time for each label it wants to define.The application can call MOREINFO="NONE"ct_callback to install a user-supplied negotiation callback to generate security labels. At connection time, Client-Library automatically triggers the callback in response to a request for security labels.For more information on login security labels, see LINKEND="X29540""Trusted-User Security Handshakes" 
.ID="IN4223-23124140"CS_TDS_VERSION propertydetailed description of
ID="IN423-23124141"TDSTDS version propertyRENDERAS="SECT3"TDS VersionMARK="BULL" REMAP="BU--Bullet"CS_TDS_VERSION defines the version of the Tabular Data Stream (TDS) protocol that the connection is using.Because CS_TDS_VERSION is a negotiated login property, its value can change during the login process. An application can set CS_TDS_VERSION to request a TDS level before calling MOREINFO="NONE"ct_connect. When MOREINFO="NONE"ct_connect creates the connection, if the server cannot provide the requested TDS version, a new (lower) TDS version is negotiated. An application can retrieve the value of CS_TDS_VERSION after a connection is established to determine the actual version of TDS in use.The following table lists the symbolic values that CS_TDS_VERSION can have:TOCENTRY="1"LBL="Table 2-31: "Values for CS_TDS_VERSIONCOLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="104*"COLNAME="C2" COLWIDTH="96*"COLNAME="C3" COLWIDTH="158*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Symbolic Value: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"CS_TDS_40COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"4.0 TDSCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Browse mode, text and image 
handling, remote procedure 
calls, bulk copy.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TDS_42COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"4.2 TDSCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Internationalization.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TDS_46COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"4.6 TDSCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Registered procedures, TDS 
passthrough, negotiable TDS 
packet size, multi-byte character 
sets.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TDS_50COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"5.0 TDSCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Cursors.If not otherwise set, CS_TDS_VERSION defaults to a value based on the CS_VERSION level that an application requested via MOREINFO="NONE"ct_init.A connection's CS_TDS_VERSION level will never be higher than the default TDS level associated with its parent context's CS_VERSION level. REMAP="UN--Under"For example, 5.0 is the default TDS level associated with a version level of CS_VERSION_100. If an application calls MOREINFO="NONE"ct_init with version as CS_VERSION_100 for a context, all connections created within that context are restricted to CS_TDS_VERSION levels of 5.0 or lower.If an application sets the CS_TDS_VERSION property, Client-Library overwrites existing capability values with default capability values corresponding to the new TDS version. For this reason, an application should set CS_TDS_VERSION before setting any capabilities for a connection.ID="IN4221-25126142"CS_TEXTLIMIT propertydetailed description of
ID="IN4214-25126143"Text and imagetext and image limit property
ID="IN4214-25126144"Text and imagelimiting text and image valuesRENDERAS="SECT3"Text and Image LimitMARK="BULL" REMAP="BU--Bullet"CS_TEXTLIMIT indicates the length, in bytes, of the longest text or image value that an application wants to receive. Client-Library will read but ignore any part of a text or image value that goes over this limit.ID="IN4221-27128145"CS_TEXTLIMIT propertydefault valueThe default value of CS_TEXTLIMIT is CS_NO_LIMIT. This means that Client-Library reads and returns all data sent by the server.In case of huge text values, it can take some time for an entire text value to be returned over the network. To keep a SQL Server from sending this extra text in the first place, use the MOREINFO="NONE"ct_optionsID="IN4214-29130146"Text and imageand CS_TEXTSIZE_OPT option
CS_TEXTSIZE_OPT option to set the server global variable @@textsize.ID="IN4219-31132147"CS_TIMEOUT propertydetailed description of
ID="IN428-31132148"Timeoutstimeout propertyRENDERAS="SECT3"TimeoutMARK="BULL" REMAP="BU--Bullet"CS_TIMEOUT controls the length of time, in seconds, that Client-Library waits for a server response when making a request. ID="IN428-31132149"Timeoutsdefault valueThe default timeout value is CS_NO_LIMIT, which represents an infinite timeout period. Negative and zero values are not allowed for CS_TIMEOUT.MOREINFO="NONE"ct_config can be called to set the timeout value at any time during an application - before or after a call to MOREINFO="NONE"ct_connect creates an open connection. It takes effect for all open connections immediately upon being called.ID="IN4228-33134150"CS_TRANSACTION_NAME propertydetailed description of
ID="IN4225-33134151"Transaction name propertyRENDERAS="SECT3"Transaction NameMARK="BULL" REMAP="BU--Bullet"CS_TRANSACTION_NAME defines a transaction name.SYBASE Open Server for CICS uses transaction names to identify executables running under CICS. For more information on SYBASE Open Server for CICS, see the Open Server for CICS documentation.All Client-Library applications can set CS_TRANSACTION_NAME. If a transaction name is not required, CS_TRANSACTION_NAME is ignored.ID="IN4233-33134152"User allocation function property
ID="IN4224-33134153"Asynchronous programming memory requirements
ID="IN4226-33134154"Memory allocation property
ID="IN4222-35136155"CS_USER_ALLOC propertydetailed description ofID="X37677" RENDERAS="SECT3"User Allocation FunctionMARK="BULL" REMAP="BU--Bullet"CS_USER_ALLOC identifies a user-supplied memory allocation routine that Client-Library will use for memory management.Together, CS_USER_ALLOC and CS_USER_FREE allow an asynchronous application to perform its own memory management.A user-supplied memory allocation routine must be defined as:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"void     *user_alloc(size)size_t   size;Ordinarily, Client-Library routines satisfy their memory requirements by calling MOREINFO="NONE"malloc. However, because not all implementations of MOREINFO="NONE"malloc are re-entrant, it is not safe for Client-Library routines that are called at the interrupt level to use MOREINFO="NONE"malloc. For this reason, asynchronous applications are required to provide an alternate way for Client-Library to satisfy its memory requirements.REMAP="UN--Under"Client-Library provides two mechanisms by which an asynchronous application can satisfy Client-Library's memory requirements:MARK="DASH" REMAP="BS--BulletSub"The application can use the CS_MEM_POOL property to provide Client-Library with a memory pool.The application can use the CS_USER_ALLOC and CS_USER_FREE properties to install memory allocation and free routines that Client-Library can safely call at the interrupt level.REMAP="UN--Under"If an asynchronous application fails to provide Client-Library with a safe way to satisfy memory requirements, Client-Library's behavior is undefined.Client-Library attempts to satisfy memory requirements from the following sources in the following order:REMAP="UN--Under"1.  Memory pool.REMAP="UN--Under"2.  User-supplied allocation and free routines.REMAP="UN--Under"3.   System routines.If a connection cannot get the memory it needs, Client-Library marks the connection dead.ID="IN4227-37138156"User-defined memory routinereplacing with ct_configAn application can replace a user-defined memory routine by calling MOREINFO="NONE"ct_config with action as CS_SET and buffer as the address of the new routine.ID="IN4227-37138157"User-defined memory routineclearingAn application can clear a memory routine in two ways:MARK="DASH" REMAP="BS--BulletSub"By calling MOREINFO="NONE"ct_config with action as CS_SET and buffer as NULL.By calling MOREINFO="NONE"ct_config with action as CS_CLEAR.ID="IN4227-37138158"User free function property
ID="IN4224-37138159"Asynchronous programming memory requirements
ID="IN4220-37138160"Memory free property
ID="IN4221-39140161"CS_USER_FREE propertydetailed description ofRENDERAS="SECT3"User Free FunctionMARK="BULL" REMAP="BU--Bullet"CS_USER_FREEID="IN4233-39140162"User-supplied memory free routineidentifying
identifies a user-supplied memory free routine that Client-Library will use for interrupt-level memory management.Together, CS_USER_ALLOC and CS_USER_FREE allow an asynchronous application to perform its own interrupt-level memory management.A user-supplied memory free routine must be defined as:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"void     user_free(ptr)void     *ptr;For more information, see LINKEND="X37677""User Allocation Function" 
.ID="IN4220-41142163"CS_USERDATA propertydetailed description of
ID="IN4218-41142164"User data propertyRENDERAS="SECT3"User DataMARK="BULL" REMAP="BU--Bullet"The CS_USERDATAID="IN4219-41142165"User-allocated datadefining
ID="IN424-41142166"Datadefining user-allocated data
property defines user-allocated data. This property allows an application to associate user data with a particular connection or command structure.CS_USERDATAID="IN429-41142167"Callbackssharing information with main-line application
ID="IN4221-41142168"Main-line applicationsharing information with callback routine
is useful when a callback routine and the main-line application need to share information without using global variables.When an application uses CS_USERDATA to store data, Client-Library copies the actual data, not a pointer to the data, into internal data space.ID="IN4219-43144169"User-allocated dataUser-allocated dataand cs_configcs_configTo associate user data with a context structure, an application can call MOREINFO="NONE"cs_config.The following code fragment demonstrates the CS_USERDATA property:REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"CS_CHAR         set_charbuf[32];CS_CHAR         get_charbuf[32];CS_CONNECTION   *con;CS_RETCODE      ret;CS_INT          outlen;CS_COMMAND      *set_cmd;CS_COMMAND      *get_cmd;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/*** Store a character string in the userdata field. ** Set the length field to one greater than the length ** of the string so that the null terminator will be ** stored as part of the user data. If the null ** terminator is not explicitly stored as part of the ** userdata then the string will not be null-** terminated when it is retrieved.*/strcpy(set_charbuf, "some userdata");ret = ct_con_props(con, CS_SET, CS_USERDATA,     set_charbuf, strlen(set_charbuf) + 1, NULL);if (ret != CS_SUCCEED){    error("ct_con_props() failed");}REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"ret = ct_con_props(con, CS_GET, CS_USERDATA,     get_charbuf, sizeof(get_charbuf), &outlen);if (ret != CS_SUCCEED){   error("ct_con_props() failed");}REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/*** The next example stores a pointer to a CS_COMMAND ** structure in the connection's user data field.*/ret = ct_con_props(con, CS_SET, CS_USERDATA,     &set_cmd, sizeof(set_cmd), NULL);if (ret != CS_SUCCEED){    error("ct_con_props() failed");}REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"ret = ct_con_props(con, CS_GET, CS_USERDATA,     &get_cmd, sizeof(get_cmd), &outlen);if (ret != CS_SUCCEED){    error("ct_con_props() failed");}ID="IN4220-45146170"CS_USERNAME propertydetailed description of
ID="IN4218-45146171"User name propertyRENDERAS="SECT3"User NameMARK="BULL" REMAP="BU--Bullet"CS_USERNAMEID="IN4210-45146172"Login namedefining
defines the user login name that the connection will use to log into a server.ID="IN427-45146173"VersionClient-Library:version string property
ID="IN4214-45146174"Client-Libraryversion string property
ID="IN4222-47148175"CS_VER_STRING propertydetailed description ofRENDERAS="SECT3"Version String for Client-LibraryMARK="BULL" REMAP="BU--Bullet"CS_VER_STRING defines a character string that represents the true version of Client-Library that an application is using. This property can only be retrieved.ID="IN4222-51152176"CS_VER_STRING propertyCS_VER_STRING
CS_VER_STRING and ID="IN4219-55156177"CS_VERSION propertyCS_VERSION
CS_VERSION can indicate different version levels because higher-level versions of Client-Library can emulate the behavior of lower-level versions. REMAP="UN--Under"CS_VER_STRING represents the actual version of Client-Library that is in use. CS_VERSION represents the version of Client-Library behavior than an application has requested.ID="IN4219-57158178"CS_VERSION propertydetailed description of
ID="IN4214-57158179"Client-Libraryversion property
ID="IN427-57158180"VersionClient-Library:version propertyRENDERAS="SECT3"Version of Client-LibraryMARK="BULL" REMAP="BU--Bullet"The CS_VERSION property represents the version of Client-Library behavior than an application has requested via MOREINFO="NONE"ct_init. The value of this property can only be retrieved.ID="IN4219-59160181"CS_VERSION propertylegal valueCurrently, the only value that is legal for CS_VERSION is CS_VERSION_100.Connections allocated within a context use default CS_TDS_VERSION values that are based on their parent context's CS_VERSION level.Both Client-Library and CS-Library have CS_VERSION properties. MOREINFO="NONE"ct_config returns the value of the Client-Library CS_VERSION. MOREINFO="NONE"cs_config returns the value of the CS-Library CS_VERSION.ID="IN4210-60161182"PropertiesREMAP="BO--Body"REMAP="BO--Body"ID="X72967" RENDERAS="SECT1"Registered ProceduresREMAP="BO--Body"A registered procedure is a procedure that is defined and installed in a running Open Server application. Release 2.0 is the first Open Server release to support registered procedures. At this time, registered procedures are not supported by SQL Server.REMAP="BO--Body"For Client-Library applications, registered procedures provide a means for inter-application communication and synchronization. This is because Client-Library 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.REMAP="BO--Body"For example, suppose that:MARK="BULL" REMAP="BU--Bullet"stockprice is a real-time Client-Library application monitoring stock prices.price_change is a registered procedure created in Open Server by stockprice, and that price_change takes as parameters a stock name and a price differential.sellstock, an application which puts stock up for sale, has requested to be notified when price_change executes.REMAP="BO--Body"When stockprice, the monitoring application, becomes aware that the price of Extravagant Auto Parts stock has risen $1.10, it executes price_change with the parameters "Extravagant Auto Parts" and "+1.10".REMAP="BO--Body"When price_change executes, Open Server sends sellstock a notification containing the name of the procedure (price_change) and the arguments passed to it ("Extravagant Auto Parts" and "+1.10"). sellstock uses the information contained in the notification to decide whether or not to sell Extravagant Auto Parts stock.REMAP="BO--Body"price_change is the means through which the stockprice and sellstock applications communicate.ID="IN42219923"Registered proceduresadvantages ofREMAP="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 information.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 Open Server.REMAP="BO--Body"A Client-Library application makes remote procedure calls to Open Server system registered procedures in order to:MARK="BULL" REMAP="BU--Bullet"Create a registered procedure in Open Server.REMAP="UN--Under"(Note that a Client--Library application can only create registered procedures that contain no executable statements. These "bodiless" procedures are primarily useful for communication and synchronization purposes.)Drop a registered procedure.List all registered procedures defined in Open Server.Request to be notified when a particular registered procedure is executed.List all registered procedure notifications.Execute a registered procedure.REMAP="BO--Body"For more information on Open Server system registered procedures, see the Open Server Server-Library Reference Manual.REMAP="BO--Body"An application calls Client-Library routines in order to:MARK="BULL" REMAP="BU--Bullet"Install a user-supplied callback routine to be called when the application receives notification that a registered procedure has executedPoll the network (if necessary) to see if any registered procedure notifications are waitingRENDERAS="SECT2"When Client-Library Receives a NotificationID="IN42219924"Registered procedureswhat happens when notification is receivedREMAP="BO--Body"When Client-Library receives a registered procedure notification, it calls an application's notification callback routine. REMAP="BO--Body"The registered procedure's name is available as the second parameter to the notification callback routine.REMAP="BO--Body"The arguments with which the registered procedure was called are available inside the notification callback, as a parameter result set. To retrieve these arguments, an application:MARK="BULL" REMAP="BU--Bullet"Calls MOREINFO="NONE"ct_con_props(CS_NOTIF_CMD) to retrieve a pointer to the command structure containing the parameter result setCalls MOREINFO="NONE"ct_res_info(CS_NUMDATA), MOREINFO="NONE"ct_describe, MOREINFO="NONE"ct_bind, MOREINFO="NONE"ct_fetch, and MOREINFO="NONE"ct_get_data to describe, bind, and fetch the parametersREMAP="BO--Body"For more information on callback routines, see the MOREINFO="NONE"Callbacks topics page.RENDERAS="SECT2"Receiving Notifications AsynchronouslyREMAP="BO--Body"The ID="IN42219745"Registered proceduresRegistered proceduresand CS_ASYNC_NOTIFS propertyCS_ASYNC_NOTIFS property
CS_ASYNC_NOTIFS property determines whether a connection receives notifications asynchronously:MARK="DASH" REMAP="BS--BulletSub"An otherwise synchronous connection can receive asynchronous notifications by setting CS_ASYNC_NOTIFS to CS_TRUE.An asynchronous connection will not receive notifications asynchronously unless it sets CS_ASYNC_NOTIFS to CS_TRUE.REMAP="BO--Body"CS_ASYNC_NOTIFS defaults to CS_FALSEID="IN42219656"Registered procedures
, which means that the application must be reading from the network in order to receive a registered procedure notification.ID="IN42229567"Remote procedure callsID="X68029" RENDERAS="SECT1"Remote Procedure CallsID="IN42179568"Stored procedurestwo ways to executeREMAP="BO--Body"A Client-Library application can call a SQL Server stored procedure in two ways: by executing a Transact-SQL language command ("execute myproc") or by executing an RPC (remote procedure call) command.REMAP="BO--Body"A Client-Library application can call an Open Server registered procedure by executing an RPC command.ID="IN42229389"Remote procedure callscomparing RPCs and execute statementsRENDERAS="SECT2"Comparing RPCs and Execute StatementsID="IN422293810"Remote procedure callsadvantagesREMAP="BO--Body"Remote procedure calls have a few advantages over MOREINFO="NONE"execute statements:MARK="BULL" REMAP="BU--Bullet"An RPC command can be used to execute a SQL Server stored procedure or an Open Server registered procedure.REMAP="UN--Under"A Transact-SQL language command can be used only to execute a SQL Server stored procedure (unless the Open Server application understands Transact-SQL).An RPC command passes the stored procedure's parameters in their native datatypes, in contrast to the MOREINFO="NONE"execute statement, which passes parameters as ASCII characters. This difference means that the RPC method is faster and more efficient than the MOREINFO="NONE"execute method, 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 if the procedure is invoked with an RPC command instead of a language command. REMAP="UN--Under"With an RPC command, the return parameter values automatically become available to the application as a parameter result set. (Note, however, that a return parameter must be specified as such when it is originally added to the RPC command stream with MOREINFO="NONE"ct_param.) REMAP="UN--Under"With an MOREINFO="NONE"execute statement, on the other hand, the return parameter values are available only if the language command declares local variables and passes these variables (not constants) for the return parameters. Because the language command contains more than one SQL statement, this technique involves additional parsing each time the language command is executed. Further, the language command must explicitly select the local variables after the RPC is executed. Their values are then returned to the application as a regular row result set.ID="IN422193811"Server-to-server RPCsRENDERAS="SECT2"Servers Can Execute Remote ProceduresREMAP="BO--Body"A server can execute a procedure residing on another server. For example, this might occur when a stored procedure being executed on one server contains an MOREINFO="NONE"execute statement for a stored procedure on another server. The MOREINFO="NONE"execute command causes the first server to log into the second server and execute the remote procedure. This is called a "server-to-server remote procedure call," and happens without any intervention from the application, although the application can specify the remote password which the first server uses to log in to the second.REMAP="BO--Body"A server-to-server remote procedure call also occurs when an application sends a request to execute a procedure that does not reside on the server to which it is directly connected. For example, if an application is connected to server1, the following language command results in a server-to-server remote procedure call:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"ct_command(cmd, CS_LANG_CMD,    "execute server2...procedure1",    CS_NULLTERM, CS_UNUSED);ID="IN422293812"Remote procedure callsTransact-SQL command restrictionREMAP="BO--Body"Transact-SQL commands contained in a stored procedure that is executed as the result of a server-to-server remote procedure call cannot be rolled back.ID="IN422293813"Remote procedure callsrelated routinesRENDERAS="SECT2"Remote Procedure Call RoutinesREMAP="BO--Body"The following Client-Library routines are related to remote procedure calls:MARK="BULL" REMAP="BU--Bullet"ID="IN4223911014"Remote procedures callsRemote procedure callsand ct_remote_pwdct_remote_pwd
MOREINFO="NONE"ct_remote_pwd sets and clears the passwords that are used when logging into a remote server.ID="IN4222891215"Remote procedure callsRemote procedure callsand ct_commandct_command
MOREINFO="NONE"ct_command initiates an RPC command.ID="IN4222871416"Remote procedure callsRemote procedure callsand ct_paramct_param
MOREINFO="NONE"ct_param defines parameters for an RPC command.ID="IN4222851617"Remote procedure callsRemote procedure callsand ct_sendct_send
MOREINFO="NONE"ct_send sends an RPC command.ID="IN4222831818"Remote procedure callsRemote procedure callsand ct_resultsct_results
MOREINFO="NONE"ct_results, MOREINFO="NONE"ct_bind, and MOREINFO="NONE"ct_fetch are used to process remote procedure results.ID="IN4222831819"Remote procedure callsresults fromRENDERAS="SECT2"Remote Procedure Call ResultsREMAP="BO--Body"In addition to results generated by the Transact-SQL statements they contain, SQL Server stored procedures that are executed via an RPC command can generate return parameter and return status results.REMAP="BO--Body"Open Server procedures can generate row, cursor, return parameter and return status results.REMAP="BO--Body"All of these types of results can be processed using MOREINFO="NONE"ct_results, MOREINFO="NONE"ct_bind, and MOREINFO="NONE"ct_fetch.ID="IN4217831820"Stored proceduresresults:return parameterRENDERAS="SECT2"Return ParametersID="IN4217831821"Stored proceduresparameter values passed by referenceREMAP="BO--Body"SQL Server and Open Server 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="BO--Body"In order for a parameter to function as a return parameter, it must be declared as such within the stored procedure. The MOREINFO="NONE"executeID="IN4217831822"Return parametersspecifying a parameter as a return parameter
statement or RPC command that invokes the stored procedure must also indicate that the parameter is a return parameter. In the case of an RPC command, it is the MOREINFO="NONE"ct_param routine that specifies whether a parameter is a return parameter. ID="IN4217831823"Return parametersprocessingRENDERAS="SECT3"Processing Return ParametersREMAP="BO--Body"As mentioned in the preceding section, "Comparing RPCs and Execute Statements," return parameter values are available to an application as a parameter result set only if the application invoked the stored procedure using an RPC command.REMAP="BO--Body"MOREINFO="NONE"ct_results sets its *result_type parameter to ID="IN4227812024"CS_PARAM_RESULT result typeprocessing
CS_PARAM_RESULT if a parameter result set is available to be processed.REMAP="BO--Body"An application processes a CS_PARAM_RESULT result set in the same way as it would processes a regular row result set; that is, by binding result items and fetching rows of data. Because stored procedure parameters are returned to an application as a single row, one call to MOREINFO="NONE"ct_fetch will copy all of a procedure's return parameters into the program variables designated via MOREINFO="NONE"ct_bind. However, an application must still call MOREINFO="NONE"ct_fetch in a loop until it returns CS_END_DATA.ID="IN4217812025"Stored proceduresresults:return statusRENDERAS="SECT2"Return StatusREMAP="BO--Body"Stored procedures can return a status number.REMAP="BO--Body"All stored procedures that run on a SQL Server version 4.0 or greater return a status number. Stored procedures usually return 0 to indicate normal completion. For a list of SQL Server default return status numbers, see MOREINFO="NONE"return in the SQL Server Reference Manual.REMAP="BO--Body"Because return status numbers are a feature of stored procedures, only an RPC command or a language command containing an MOREINFO="NONE"execute statement can generate a return status.RENDERAS="SECT3"Processing an RPC Command Return StatusREMAP="BO--Body"MOREINFO="NONE"ct_results sets its *result_type parameter to ID="IN4228792226"CS_STATUS_RESULT result typeprocessing
CS_STATUS_RESULT if a return status result set is available to be processed. REMAP="BO--Body"Because a return status result set contains only a single value, one call to MOREINFO="NONE"ct_fetch will copy the status into the program variable designated via MOREINFO="NONE"ct_bind. However, an application should always call MOREINFO="NONE"ct_fetch in a loop until it returns CS_END_DATA.ID="IN4222782327"Remote procedure callsREMAP="BO--Body"ID="IN427772428"ResultsID="X51426" RENDERAS="SECT1"ResultsID="IN427772429"Resultslist of result typesREMAP="BO--Body"When a Client-Library command executes on a server, it can generate various types of results which are returned to the application that sent the command:REMAP="BO--Body"They are:MARK="DASH" REMAP="BS--BulletSub"Regular row resultsCursor row resultsParameter resultsStored procedure return status resultsCompute row resultsMessage resultsDescribe resultsFormat resultsID="IN427772430"Resultsdefinition ofREMAP="BO--Body"Results are returned to an application in the form of "result sets." A result set contains only a single type of result data. Regular row and cursor row result sets can contain multiple rows of data, but other types of result sets contain at most a single row of data.ID="IN427772431"ResultsprocessingREMAP="BO--Body"An application processes results by calling MOREINFO="NONE"ct_results, which indicates the type of result available by setting *result_type. REMAP="BO--Body"MOREINFO="NONE"ct_results sets *result_type to CS_CMD_DONE to indicate that the results of a "logical command" have been completely processed. A logical command is generally considered to be any Open Client command defined via MOREINFO="NONE"ct_command, MOREINFO="NONE"ct_dynamic, or MOREINFO="NONE"ct_cursor. Exceptions to this rule are documented in LINKEND="X17772""When are the Results of a Command Completely Processed?" 
.ID="IN427772432"Resultsnot generated by all commandsREMAP="BO--Body"Some commands, for example a language command containing a Transact-SQL MOREINFO="NONE"update statement, do not generate results. MOREINFO="NONE"ct_results sets *result_type to CS_CMD_SUCCEED or CS_CMD_FAIL to indicate the status of a command that does not return results.ID="IN427772433"Resultstypes ofRENDERAS="SECT2"Types of ResultsID="IN4211772434"Row results
ID="IN4219772435"Regular row results
ID="IN427772436"Resultsregular row results
ID="IN427772437"Resultsrow resultsRENDERAS="SECT3"Regular Row ResultsREMAP="BO--Body"A regular row result set is generated by the execution of a Transact-SQL MOREINFO="NONE"select statement on a server. REMAP="BO--Body"A regular row result set contains zero or more rows of tabular data. ID="IN4218772438"Cursor row results
ID="IN427772439"Resultscursor row resultsRENDERAS="SECT3"Cursor Row ResultsREMAP="BO--Body"A cursor row result set is generated when an application executes a Client-Library cursor open command.A cursor row result set is not generated when an application executes language command containing a Transact-SQL MOREINFO="NONE"open statement. For more information, see LINKEND="X92621""Language Cursors" 
.REMAP="BO--Body"A cursor row result set contains zero or more rows of tabular data.REMAP="BO--Body"A cursor row result set differs from a regular row result set in that an application can use MOREINFO="NONE"ct_cursor to update underlying tables while fetching cursor rows. This is not possible with regular rows.ID="IN4217772440"Stored proceduresresults:return parameter
ID="IN4218772441"Message parameters
ID="IN427772442"Resultsparameter results
ID="IN4217772443"Parameter resultsRENDERAS="SECT3"Parameter ResultsREMAP="BO--Body"A parameter result set contains a single "row" of parameters. Several types of data can be returned as a parameter result set, including:MARK="BULL" REMAP="BU--Bullet"Message parameters. For more information, see the LINKEND="X12709""Message Commands and Results"
topics page.Stored procedure return parameters. For more information, see the LINKEND="X68029""Remote Procedure Calls"
topics page.REMAP="BO--Body"Extended error data and registered procedure notification parameters are also returned as parameter result sets, but since an application does not call MOREINFO="NONE"ct_results to process these types of data, the application never sees a result type of CS_PARAM_RESULT. Instead, the row of parameters is simply available to be fetched after the application retrieves the CS_COMMAND structure containing the data.REMAP="BO--Body"For information on extended error data, see the LINKEND="X46924""Error and Message Handling"
topics page. For information on registered procedure notification parameters, see the LINKEND="X72967""Registered Procedures"
topics page.ID="IN4217772444"Stored proceduresresults:return status
ID="IN427772445"Resultsstatus results
ID="IN4213772446"Status resultRENDERAS="SECT3"Stored Procedure Return Status ResultsREMAP="BO--Body"A status result set consists of a single row which contains a single value, a return status. For more information on a stored procedure return status, see the LINKEND="X68029""Remote Procedure Calls"
topics page.ID="IN427772447"Resultscompute row results
ID="IN4215772448"Compute resultsRENDERAS="SECT3"Compute Row ResultsREMAP="BO--Body"A compute row result set contains a single row of tabular data with a number of columns equal to the number of columns listed in the compute clause that generated the compute row.REMAP="BO--Body"For more information on compute rows, see MOREINFO="NONE"compute clause in the SQL Server Reference Manual.ID="IN427772449"Resultsmessage results
ID="IN4215772450"Message resultsRENDERAS="SECT3"Message ResultsREMAP="BO--Body"A message result set does not actually contain any data. Instead, a message has an "id." To get a message's id, an application can call MOREINFO="NONE"ct_res_info after MOREINFO="NONE"ct_results returns CS_MSG_RESULT.REMAP="BO--Body"If parameters are associated with a message, they are returned as a separate parameter result set, immediately following the message result set.REMAP="BO--Body"For more information on message results, see the LINKEND="X12709""Message Commands and Results"
topics page.ID="IN4216772451"Describe results
ID="IN427772452"Resultsdescribe resultsRENDERAS="SECT3"Describe ResultsREMAP="BO--Body"A describe result set does not contain fetchable data, but rather indicates the existence of descriptive information returned as the result of a dynamic SQL describe input or describe output command.REMAP="BO--Body"An application can retrieve this descriptive information by calling MOREINFO="NONE"ct_describe or MOREINFO="NONE"ct_dyndesc.REMAP="BO--Body"For more information on dynamic SQL, see the LINKEND="X39013""Dynamic SQL"
topics page.ID="IN427772453"Resultsformat results
ID="IN4214772454"Format resultsID="X17247" RENDERAS="SECT3"Format ResultsREMAP="BO--Body"There are two types of format results: regular row format results and compute row format results.REMAP="BO--Body"Format result sets do not contain fetchable data, but rather indicate the availability of format information for the regular row and compute row result sets with which they are associated.REMAP="BO--Body"All format information for a command is returned before any data. That is, the row format and compute format result sets for a command precede the regular row and compute row result sets that the command generates.REMAP="BO--Body"Format information is primarily of use in gateway applications, which need to repackage SQL Server results before sending them on to a foreign client.REMAP="BO--Body"A gateway application typically processes a format result set one column at a time, retrieving format information for the column by calling MOREINFO="NONE"ct_describe and MOREINFO="NONE"ct_compute_info and sending the format information on via Server-Library routines.REMAP="BO--Body"A connection receives format results only if its CS_EXPOSE_FMTS property is set to CS_TRUE.ID="IN427772455"Resultscode fragment demonstrating how to processRENDERAS="SECT2"Program Structure for Processing ResultsREMAP="BO--Body"The following pseudo-code fragment demonstrates how a typical application might process the various types of result data:REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"while ct_results returns CS_SUCCEED      case CS_ROW_RESULT         ct_res_info to get the number of columns         for each column:            ct_describe to get a description of the                 column            ct_bind to bind the column to a program                  variable         end for         while ct_fetch returns CS_SUCCEED or             CS_ROW_FAIL             if CS_SUCCEED                 process the row             else if CS_ROW_FAIL                handle the row failure;             end if         end while        switch on ct_fetch's final return code             case CS_END_DATA...             case CS_CANCELED...             case CS_FAIL...        end switch     end case     case CS_CURSOR_RESULT         ct_res_info to get the number of columns         for each column:             ct_describe to get a description of the                  column             ct_bind to bind the column to a program                 variable         end for         while ct_fetch returns CS_SUCCEED or              CS_ROW_FAIL              if CS_SUCCEED                 process the row              else if CS_ROW_FAIL                 handle the row failure              end if              /* For update or delete only: */             if target row is not the row just fetched                 ct_keydata to specify the target row                  key             end if             /* End for update or delete only */REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"                    /* To send another cursor command: */                    ct_cursor to initiate the cursor command                    ct_param if command is update of some                        columns only                    ct_send to send the command                    while ct_results returns CS_SUCCEED                        (...process results...)                    end while                    /* End to send another cursor command */                end while                switch on ct_fetch's final return code                    case CS_END_DATA...                    case CS_CANCELED...                    case CS_FAIL...                end switch            end case            case CS_PARAM_RESULT                ct_res_info to get the number of parameters                for each parameter:                    ct_describe to get a description of the                        parameter                    ct_bind to bind the parameter to a                        variable                end for                while ct_fetch returns CS_SUCCEED or                    CS_ROW_FAIL                    if CS_SUCCEED                        process the row of parameters                    else if CS_ROW_FAIL                        handle the failure                    end if                end while                switch on ct_fetch's final return code                    case CS_END_DATA...                    case CS_CANCELED...                    case CS_FAIL...                end switch            end case            case CS_STATUS_RESULT                ct_bind to bind the status to a program                    variable                while ct_fetch returns CS_SUCCEED or                    CS_ROW_FAIL                    if CS_SUCCEED                        process the return status                    else if CS_ROW_FAIL                        handle the failure                    end if                end while                switch on ct_fetch's final return code                    case CS_END_DATA...                    case CS_CANCELED...                    case CS_FAIL...                end switch            end case            case CS_COMPUTE_RESULT                (optional:  ct_compute_info to get bylist                    length, bylist, or compute row id)                ct_res_info to get the number of columns                for each column:                    ct_describe to get a description of the                        column                    ct_bind to bind the column to a program                        variable                    (optional: ct_compute_info to get the                        compute column id or the aggregate                        operator for the compute column)                end for                while ct_fetch returns CS_SUCCEED or                    CS_ROW_FAIL                    if CS_SUCCEED                        process the compute row                    else if CS_ROW_FAIL                        handle the failure                    end if                end while                switch on ct_fetch's final return code                    case CS_END_DATA...                    case CS_CANCELED...                    case CS_FAIL...                end switch            end case            case CS_MSG_RESULT                ct_res_info to get the message id                code to handle the message            end case            case CS_DESCRIBE_RESULT                ct_res_info to get the number of columns                for each column:                    ct_describe or ct_dyndesc to get a                        description                end for            end case            case CS_ROWFMT_RESULT                ct_res_info to get the number of columns                for each column:                    ct_describe to get a column description                    send the information on to the gateway                        client                end for            end case            case CS_COMPUTEFMT_RESULT                ct_res_info to get the number of columns                for each column:                    ct_describe to get a column description                    (if required:                         ct_compute_info for compute                            information                    end if required)                    send the information on to the gateway                        client                end for            end case            case CS_CMD_DONE                indicates a command's results are completely                    processed            end case            case CS_CMD_SUCCEED                indicates the success of a command that                    returns no results            end case            case CS_CMD_FAIL                indicates a command failed            end case        end while        switch on ct_results' final return code            case CS_END_RESULTS                indicates no more results            end case            case CS_CANCELED                indicates results were canceled            end case            case CS_FAIL                indicates ct_results failed            end case        end switchID="IN4211772456"Result itemthree ways to retrieve its valueRENDERAS="SECT2"Retrieving an Item's ValueREMAP="BO--Body"When processing a result set, there are three ways for an application to retrieve a result item's value:MARK="BULL" REMAP="BU--Bullet"It can call MOREINFO="NONE"ct_bind to associate a result item with a program variable. When the program calls MOREINFO="NONE"ct_fetch to fetch a result row, the item's value is automatically copied into the associated program variable. Most applications will use this method for all result items except large text or image values.It can call MOREINFO="NONE"ct_get_data to retrieve a result item's value in chunks. After calling MOREINFO="NONE"ct_fetch to fetch the row, the application calls MOREINFO="NONE"ct_get_data in a loop. Each MOREINFO="NONE"ct_get_data call retrieves a chunk of the result item's value. Most application will use MOREINFO="NONE"ct_get_data only to retrieve large text or image values.It can call MOREINFO="NONE"ct_dyndesc to retrieve result item descriptions and values. An application calls MOREINFO="NONE"ct_dyndesc once for each result item, after calling MOREINFO="NONE"ct_fetch to fetch the row. Typical applications will not use MOREINFO="NONE"ct_dyndesc, which is intended for precompiler support.ID="IN427762557"ResultsREMAP="BO--Body"REMAP="BO--Body"ID="X23734" RENDERAS="SECT1"Security FeaturesREMAP="BO--Body"Client-Library's security-related features include:MARK="BULL" REMAP="BU--Bullet"Support for various types of security handshakesSupport for Secure SQL Server's sensitivity and sensitivity_boundary datatypes.Support for bulk copies in to and out from Secure SQL Servers.ID="IN42810012"Securityhandshakes;Handshakes:types of security handshakesRENDERAS="SECT2"Security HandshakesREMAP="BO--Body"Client-Library supports three types of security handshakes:MARK="BULL" REMAP="BU--Bullet"Trusted-user security handshakesREMAP="UN--Under"In this type of handshake, the server asks the client for identifying security labels, which the client then provides.REMAP="UN--Under"Secure SQL Server uses trusted-user security handshaking. On Secure SQL Server, security labels are known as "sensitivity labels."Challenge/response security handshakesREMAP="UN--Under"In this type of handshake, the server issues a challenge to which the client must correctly respond.Encrypted password security handshakesREMAP="UN--Under"In this type of handshake, the server provides the client with a key. The client uses the key to encrypt a password, which it then returns to the server.ID="IN423210013"Trusted-user security handshakestrusted-user security
ID="IN421710014"Secure SQL Servertrusted-user security handshakesID="X29540" RENDERAS="SECT3"Trusted-User Security HandshakesID="IN423210015"Trusted-user security handshakestrusted-user securityREMAP="BO--Body"To provide the response that a trusted-user security handshake requires, an application must:MARK="BULL" REMAP="BU--Bullet"Call MOREINFO="NONE"ct_con_props to set the CS_SEC_NEGOTIATE property to CS_TRUE.Define security labels to pass to the server at connection time.REMAP="UN--Under"There are two ways for an application to define security labels. An application can use either, or both, of these methods:MARK="DASH" REMAP="BS--BulletSub"The application can call MOREINFO="NONE"ct_labels one time for each label it wants to define.The application can call MOREINFO="NONE"ct_callback to install a user-supplied negotiation callback to generate security labels. At connection time, Client-Library automatically triggers the callback in response to a request for security labels.REMAP="UN--Under"If an application uses both methods, the labels defined via MOREINFO="NONE"ct_labels and the labels generated by the negotiation callback are sent to the server at the same time.REMAP="BO--Body"When the application calls MOREINFO="NONE"ct_connect to connect to the server, the server responds with a request for security labels. In response, Client-Library generates a list of labels and sends it to the server:MARK="BULL" REMAP="BU--Bullet"If the application has called MOREINFO="NONE"ct_labels to define labels, Client-Library includes these labels in the list.If the application has installed a negotiation callback to generate security labels, Client-Library triggers the callback and includes the labels that it generates in the list.REMAP="UN--Under"When it is called, the negotiation callback generates a single security label and returns either CS_CONTINUE, CS_SUCCEED, or CS_FAIL.REMAP="UN--Under"If the callback returns CS_CONTINUE, Client-Library calls the negotiation callback again, to get an additional security label.REMAP="UN--Under"If the callback returns CS_SUCCEED, Client-Library sends the list of security labels to the server.REMAP="UN--Under"If the callback returns CS_FAIL, Client-Library aborts the connection process, causing MOREINFO="NONE"ct_connect to return CS_FAIL.ID="IN423810016"Challenge/response security handshakes
ID="IN421710017"Secure SQL Serverchallenge/response security handshakesID="X40605" RENDERAS="SECT3"Challenge/Response Security HandshakesREMAP="BO--Body"Servers can use challenge/response security handshakes to provide an additional level of login security checking.ID="IN423810018"Challenge/response security handshakeschallenge/response securityREMAP="BO--Body"To provide the response that this handshake method requires, an application must:MARK="DASH" REMAP="BS--BulletSub"Call MOREINFO="NONE"ct_con_props to set the CS_SEC_CHALLENGE or CS_SEC_APPDEFINED property to CS_TRUE. CS_SEC_CHALLENGE turns on Sybase-defined challenge/response security handshaking; CS_SEC_APPDEFINED turns on Open Server application-defined challenge/response security handshaking.Write a negotiation callback that will return the required response.Call MOREINFO="NONE"ct_callback to install the callback either at the context level or for a specific connection.REMAP="BO--Body"When the application calls MOREINFO="NONE"ct_connect to connect to the server:MARK="DASH" REMAP="BS--BulletSub"If the server replies with a challenge, then Client-Library calls the connection's negotiation callback.The negotiation callback generates the response and returns either CS_CONTINUE, CS_SUCCEED, or CS_FAIL.If the callback returns CS_CONTINUE, Client-Library calls the negotiation callback again, to get an additional response.If the callback returns CS_SUCCEED, Client-Library sends the response(s) to the server.If the callback returns CS_FAIL, Client-Library aborts the connection process, causing MOREINFO="NONE"ct_connect to return CS_FAIL.ID="IN422010019"Gateway applicationshandling encrypted passwords
ID="IN4238100110"Encrypted password security handshakesencrypted password securityID="X70164" RENDERAS="SECT3"Encrypted Password Security HandshakesREMAP="BO--Body"SQL Server uses encrypted password handshakes.REMAP="BO--Body"Most applications are not aware of SQL Server's password encryption because Client-Library automatically handles it.REMAP="BO--Body"Client-Library applications that are acting as gateways, however, need to handle password encryption explicitly, passing the server's encryption key on to the client and then returning the encrypted password back to the server.ID="IN4238100111"Encrypted password security handshakesencrypted password securityREMAP="BO--Body"To do this, a gateway application must:MARK="DASH" REMAP="BS--BulletSub"Call MOREINFO="NONE"ct_con_props to set the CS_SEC_ENCRYPTION property to CS_TRUE.Write an encryption callback routine.Call MOREINFO="NONE"ct_callback to install the callback either at the context level or for a specific connection.REMAP="BO--Body"When the gateway calls MOREINFO="NONE"ct_connect to connect to the server:MARK="DASH" REMAP="BS--BulletSub"The server responds with an encryption key, causing Client-Library to trigger the encryption callback.The encryption callback passes the key on to the gateway's client.The gateway's client encrypts the password and returns it to the encryption callback.If the callback returns CS_SUCCEED, Client-Library sends the encrypted password to the server.If the callback returns CS_FAIL, Client-Library aborts the connection process, causing MOREINFO="NONE"ct_connect to return CS_FAIL.RENDERAS="SECT2"ID="IN429100112"Datatypessecurity
ID="IN428100113"Securitydatatypes
Security DatatypesID="IN4218100114"Sensitivity labelssensitivityREMAP="BO--Body"Secure SQL Server uses sensitivity labels, of datatype sensitivity, to control access to data. Each row in a Secure SQL Server table has a sensitivity label.ID="IN4215100115"Boundary labelsboundaryREMAP="BO--Body"Secure SQL Server uses boundary labels, of datatype sensitivity_boundary, to specify either an upper or lower bound for the sensitivity labels that a process can use or access. Secure SQL Server uses boundary labels internally, in system tables.REMAP="BO--Body"Client-Library supports these two datatypes by providing the type constants ID="IN422896516"CS_SENSITIVITY_TYPE datatypeCS_SENSITIVITY_TYPE
CS_SENSITIVITY_TYPE and ID="IN422592917"CS_BOUNDARY_TYPE datatypeCS_BOUNDARY_TYPE
CS_BOUNDARY_TYPE.REMAP="BO--Body"These type constants differ from other Open Client type constants in that they do not correspond to similarly-named typedefs. Instead, they correspond to CS_CHAR.REMAP="BO--Body"This means that although Open Client routines accept and return CS_BOUNDARY_TYPE and CS_SENSITIVITY_TYPE to describe a column or variable's datatype, any corresponding program variable must be of type CS_CHAR.REMAP="BO--Body"For example, if an application calls MOREINFO="NONE"ct_bind with the datatype field of the CS_DATAFMT structure set to CS_SENSITIVITY_TYPE, the program variable to which the data is being bound must be of type CS_CHAR.ID="IN42992918"Bulk copy copies into Secure SQL Server
ID="IN42892919"Securitybulk copies into Secure SQL ServerRENDERAS="SECT2"Secure Bulk CopiesREMAP="BO--Body"For information on how to bulk copy in to or out from a Secure SQL Server, see:MARK="BULL" REMAP="BU--Bullet"Chapter 3, "Introducing Bulk Copy," in the Open Client and Open Server Common Libraries Reference ManualSecure SQL Server Utility Programs ID="IN42692920"Serverrestrictions
ID="IN421292921"RestrictionsserverRENDERAS="SECT1"Server RestrictionsID="IN421192922"Open Clientgeneric programming interface
ID="IN421192923"Open Clientservers it accessesREMAP="BO--Body"SYBASE Open Client is a generic programming interface. This means that it is functionally independent of the servers to which it interfaces. Such independence allows Open Client applications to communicate with not only SYBASE SQL Server and SYBASE Open Server applications, but if the Open Server application is a gateway, with non-Sybase servers as well.ID="IN421192924"Open Clientindependent of server behavior
ID="IN42692925"ServerbehaviorREMAP="BO--Body"Being functionally independent means that Open Client has no knowledge of the way in which a server may choose to implement certain functionality. It is possible that the same feature, implemented by multiple servers, will exhibit various different behaviors. The behavior of a server feature is specific to the server currently being accessed.ID="IN421192926"Open Clientapplication developer responsibilities
ID="IN421292927"Applicationsapplication developer responsibilitiesREMAP="BO--Body"As an Open Client application developer, you should have a thorough understanding of the behavior of the server(s) for which you are writing an application. This includes knowing what functionality is supported and what restrictions are enforced.ID="IN421292928"RestrictionsOpen Server
ID="IN421192929"Open ServerrestrictionsRENDERAS="SECT2"Open Server RestrictionsREMAP="BO--Body"Open Client and Open Server do not inherit SQL Server restrictions. This means that communication between Open Client applications and Open Server applications is not constrained by rules that govern SQL Server's behavior.REMAP="BO--Body"Communication is constrained, however, by any restrictions built into an Open Server application. For example, an Open Server application may decide not to support remote procedure calls (RPCs) by not installing the SRV_RPC event handler. This is a constraint of which an Open Client application must be aware.REMAP="BO--Body"An important point to note is that Open Client and Open Server are mirror images of each other. Open Server is capable of receiving anything that Open Client is capable of sending, and vice versa. Restrictions arise not only when implementation-specific limitations are imposed on an Open Server application, but when functionality available in Open Server is not enabled.ID="IN421092930"SQL Serverrestrictions
ID="IN421292931"RestrictionsSQL ServerRENDERAS="SECT2"SQL Server RestrictionsREMAP="BO--Body"It is only when an Open Client application accesses SQL Server that the application must be aware of SQL Server restrictions. For example, SQL Server has login name requirements: the login name must follow the rules for SQL Server identifiers and it must be unique. When an Open Client application accesses a SQL Server, it must adhere to such requirements.REMAP="BO--Body"What follows are some important SQL Server restrictions:MARK="BULL" REMAP="BU--Bullet"Dynamic SQL is implemented using temporary stored procedures and therefore, inherits the restrictions of stored procedures.The long variable-length binary datatypes, as well as the long variable-length character datatypes, are not supported.By definition, a cursor is associated with only one MOREINFO="NONE"select statement. This means that a stored procedure on which a Client-Library cursor is declared can contain only a single statement: a MOREINFO="NONE"select statement.Stored procedures do not support text and image parameters.Event notifications are not supported.Message commands are not supported.The POSIX locale method of localization is not supported.RENDERAS="SECT2"What Client/Server Features are Supported?ID="IN4213901132"ct_capabilityREMAP="BO--Body"To ascertain some of the client and server features supported by a particular connection, an application can call MOREINFO="NONE"ct_capability. MOREINFO="NONE"ct_capability's value parameter returns information about whether the capability is enabled or not.REMAP="BO--Body"An application can find out, among other things:MARK="BULL" REMAP="BU--Bullet"What datatypes are supportedWhat types of requests are validREMAP="BO--Body"For more information about getting (and setting) client and server features, see the MOREINFO="NONE"ct_capability manual page.ID="IN4215881333"SQLCA structure
ID="IN4210861534"StructuresSQLCA structureID="X63522" RENDERAS="SECT1"SQLCA StructureREMAP="BO--Body"A SQLCA structure can be used in conjunction with MOREINFO="NONE"ct_diag to retrieve Client-Library and server error and informational messages.REMAP="BO--Body"A SQLCA structure is defined as follows:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"/*** SQLCA** The SQL Communications Area structure. */ typedef struct _sqlca{    char    sqlcaid[8];    long    sqlcabc;    long    sqlcode;     struct    }        long    sqlerrml;        char    sqlerrmc[256];    } sqlerrm;     char    sqlerrp[8];    long    sqlerrd[6];    char    sqlwarn[8];    char    sqlext[8]; } SQLCA;REMAP="BO--Body"where:REMAP="RI--RefIndent"sqlcaid is "SQLCA".sqlcabc is ignored.sqlcode is the server or Client-Library message number. For information on how Client-Library maps message numbers to sqlcode, see LINKEND="X57132""SQLCODE Structure" 
.sqlerrml is the length of the actual message text (not the length of the text placed in sqlerrmc).sqlerrmc is the null-terminated text of the message. If the message is too long for the array, Client-Library truncates it before appending the null terminator.sqlerrp is the null-terminated name of the stored procedure, if any, being executed at the time of the error. If the name is too long for the array, Client-Library truncates it before appending the null terminator.sqlerrd[2] is the number of rows affected by the current command. This field is set only if the current message is a "number of rows affected" message. Otherwise, sqlerrd[2] has a value of CS_NO_COUNT.sqlwarn is an array of warnings:MARK="BULL" REMAP="BU--Bullet"If sqlwarn[0] is blank, then all other sqlwarn variables are blank. If sqlwarn[0] is not blank, then at least one other sqlwarn variable is set to "W".If sqlwarn[1] is "W", then Client-Library truncated at least one column's value when copying it into a host variable.If sqlwarn[2] is "W", then at least one null value was eliminated from the argument set of a function.If sqlwarn[3] is "W", then some but not all items in a result set have been bound. This field is set only if the CS_ANSI_BINDS property is set to CS_TRUE.If sqlwarn[4] is "W", then a dynamic SQL MOREINFO="NONE"update or MOREINFO="NONE"delete statement did not include a MOREINFO="NONE"where clause.If sqlwarn[5] is "W", then a server conversion or truncation error has occurred.REMAP="BO--Body"sqlext is ignored.ID="IN4217841735"SQLCODE structure
ID="IN4210821936"StructuresSQLCODE structureID="X57132" RENDERAS="SECT1"SQLCODE StructureREMAP="BO--Body"A SQLCODE structure can be used in conjunction with MOREINFO="NONE"ct_diag to retrieve Client-Library and server error and informational message codes.REMAP="BO--Body"An application must declare a SQLCODE structure as a long integer.REMAP="BO--Body"Client-Library always sets SQLCODE and the sqlcode field of the SQLCA structure identically.ID="IN4217802137"SQLCODE structuremapping server messages to
ID="IN4215782338"Server messagesmapping to SQLCODE structureRENDERAS="SECT2"Mapping Server Messages to SQLCODEREMAP="BO--Body"A server message number is mapped to a SQLCODE of 0 if it has a severity of 0.REMAP="BO--Body"Other server messages may be mapped to a SQLCODE of 0 as well.REMAP="BO--Body"Server message numbers are inverted before being placed into SQLCODE. This ensures that SQLCODE is negative if an error has occurred.REMAP="BO--Body"For a list of server messages, execute the Transact-SQL command:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"select * from sysmessagesID="IN4217762539"SQLCODE structuremapping Client-Library messages to
ID="IN4223742740"Client-Library messagesmapping to SQLCODE structureRENDERAS="SECT2"Mapping Client-Library Messages to SQLCODEREMAP="BO--Body"The Client-Library message "No rows affected" is mapped to a SQLCODE of 100.REMAP="BO--Body"Client-Library messages with CS_SV_INFORM severities are mapped to a SQLCODE of 0.REMAP="BO--Body"Other Client-Library messages may be mapped to a SQLCODE of 0 as well.REMAP="BO--Body"Client-Library message numbers are inverted before being placed into SQLCODE. This ensures that SQLCODE is negative if an error has occurred.REMAP="BO--Body"For a list of Client-Library messages, see the LINKEND="X26600""Client-Library Messages"
topics page. ID="IN4218722941"SQLSTATE structure
ID="IN4210703142"StructuresSQLSTATE structureID="X24839" RENDERAS="SECT1"SQLSTATE StructureREMAP="BO--Body"A SQLSTATE structure can be used in conjunction with MOREINFO="NONE"ct_diag to retrieve SQL state information, if any, associated with a Client-Library or server message.REMAP="BO--Body"An application must declare a SQLSTATE structure as an array of bytes.REMAP="BO--Body"Client-Library always sets SQLSTATE and the sqlstate field of the CS_CLIENTMSG and CS_SERVERMSG structure identically.ID="IN4210693243"StructuresID="X17322" RENDERAS="SECT1"StructuresID="IN4210693244"StructuresÔ Ô hiddenÕ Õ  and Ô Ô exposedÕ Õ REMAP="BO--Body"Client-Library structures fall into two categories: "hidden" structures, whose internals are not documented, and "exposed" structures, whose internals are documented.ID="IN4217693245"Hidden structureslist ofRENDERAS="SECT2"Hidden StructuresREMAP="BO--Body"Client-Library uses hidden structures to manage a variety of internal tasks.REMAP="BO--Body"A Client-Library application cannot directly access hidden structure internals. Instead, the application must call Client-Library routines to allocate, manipulate, and de-allocate hidden structures.REMAP="BO--Body"Hidden structures include:MARK="BULL" REMAP="BU--Bullet"ID="IN4217673446"Hidden structuresCS_BLKDESC structure
ID="IN4220653647"CS_BLKDESC structure
CS_BLKDESC, a control structure used by Client-Library's and Server-Library's bulk copy routines.ID="IN4217633848"Hidden structuresCS_CAP_TYPE structure
ID="IN4221614049"CS_CAP_TYPE structure
CS_CAP_TYPE, which is used to store capability information.ID="IN4217594250"Hidden structuresCS_COMMAND structure
CS_COMMANDID="IN4220574451"CS_COMMAND structure
, which is used to send commands and process results.ID="IN4217554652"Hidden structuresCS_CONNECTION structure
CS_CONNECTIONID="IN4223534853"CS_CONNECTION structure
, which defines an individual client/server connection.ID="IN4217515054"Hidden structuresCS_CONTEXT structure
CS_CONTEXTID="IN4220495255"CS_CONTEXT structure
, which defines a Client-Library programming context.ID="IN4217475456"Hidden structuresCS_LOCALE structure 
CS_LOCALEID="IN4219455657"CS_LOCALE structure
, which is used to store localization information.ID="IN4217435858"Hidden structuresCS_LOGINFO structure
CS_LOGINFOID="IN4220416059"CS_LOGINFO structure
, the server login information structure. This structure, which is associated with a CS_CONNECTION, contains server login information such as user name and password.ID="IN4217416060"Hidden structuresrelated routinesREMAP="BO--Body"The following table lists the routines and macros that allocate, manipulate, and de-allocate hidden structures:TOCENTRY="1"LBL="Table 2-32: " ID="X61933"Routines that manipulate hidden structuresCOLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="112*"COLNAME="C2" COLWIDTH="103*"COLNAME="C3" COLWIDTH="144*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Structure:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Routines:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"For More Information, See:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BLKDESCCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"blk_alloc, MOREINFO="NONE"blk_dropCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The Open Client and Open 
Server Common Libraries 
Reference Manual.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CAP_TYPECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"CS_CLR_CAPMASKMOREINFO="NONE",
MOREINFO="NONE" 
CS_SET_CAPMASKMOREINFO="NONE",MOREINFO="NONE" 
CS_TST_CAPMASKCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0""Setting and Retrieving 
Multiple Capabilities" COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_COMMANDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cmd_allocMOREINFO="NONE", 
MOREINFO="NONE"ct_cmd_propsMOREINFO="NONE", 
MOREINFO="NONE"ct_cmd_dropCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0""Basic Control Structures" COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CONNECTIONCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_con_allocMOREINFO="NONE", 
MOREINFO="NONE"ct_con_propsMOREINFO="NONE", 
MOREINFO="NONE"ct_con_dropCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0""Basic Control Structures" COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CONTEXTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"cs_ctx_allocMOREINFO="NONE", 
MOREINFO="NONE"ct_configMOREINFO="NONE", MOREINFO="NONE"cs_configMOREINFO="NONE", 
MOREINFO="NONE"cs_ctx_dropCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0""Basic Control Structures" COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_LOCALECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"cs_loc_allocMOREINFO="NONE", 
MOREINFO="NONE"cs_localeMOREINFO="NONE", 
MOREINFO="NONE"cs_loc_dropCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0""International Support"   of 
this manual.

The Open Client and Open 
Server Common Libraries 
Reference Manual.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_LOGINFOCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_getloginfoMOREINFO="NONE", 
MOREINFO="NONE"ct_setloginfoCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The manual pages for 
MOREINFO="NONE"ct_getloginfo and MOREINFO="NONE"ct_setloginfo 
in Chapter 3 of this manual.ID="IN4218416061"Exposed structuresRENDERAS="SECT2"Exposed StructuresREMAP="BO--Body"Exposed structures provide a way for Client-Library to exchange information with an application. Typically, applications set fields in an exposed structure before passing the structure as a parameter to a Client-Library routine, and retrieve the values of fields in an exposed structure after calling a Client-Library routine.REMAP="BO--Body"Exposed structures include:MARK="BULL" REMAP="BU--Bullet"ID="IN4218396262"Exposed structuresCS_BROWSEDESC structure
CS_BROWSEDESCID="IN4223376463"CS_BROWSEDESC structure
, the browse descriptor structureID="IN4218356664"Exposed structuresCS_CLIENTMSG structure
CS_CLIENTMSGID="IN4222336865"CS_CLIENTMSG structure
, the Client-Library message structureID="IN4218317066"Exposed structuresCS_DATAFMT structure
CS_DATAFMTID="IN4220297267"CS_DATAFMT structure
, the data format structureID="IN4218277468"Exposed structuresCS_IODESC structure
CS_IODESCID="IN4219257669"CS_IODESC structure
, the I/O descriptor structureID="IN4218237870"Exposed structuresCS_SERVERMSG structure
CS_SERVERMSGID="IN4222218071"CS_SERVERMSG structure
, the server message structureID="IN4218198272"Exposed structuresSQLCA structure
SQLCAID="IN4215178473"SQLCA structure
, the SQL Communications Area structureID="IN4218158674"Exposed structuresSQLCODE structure
SQLCODEID="IN4217138875"SQLCODE structure
, the SQL Code structureID="IN4218119076"Exposed structuresSQLSTATE structure
SQLSTATEID="IN421899277"SQLSTATE structure
, the SQL State structureID="IN421089378"StructuresREMAP="BO--Body"These exposed structures are documented on topics pages.ID="IN421479479"Text and imageID="X51184" RENDERAS="SECT1"Text and ImageREMAP="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.ID="IN421479480"Text and imagestoring text and image dataREMAP="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."ID="IN421479481"Text and imagetext timestamp;Text timestampREMAP="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"Client-Library stores the text pointer and text timestamp for a text or image column in an I/O descriptor structure, the CS_IODESC. The I/O descriptor for a column also contains other information about the column, including its name and datatype.REMAP="BO--Body"For detailed information on the CS_IODESC structure, see the MOREINFO="NONE"CS_IODESC topics page.ID="IN421479482"Text and imageretrieving a text or image columnRENDERAS="SECT2"Retrieving a Text or Image ColumnREMAP="BO--Body"An application can retrieve text or image columns in two ways:MARK="BULL" REMAP="BU--Bullet"It can select the columns, bind the columns, and fetch rows. In other words, an application can retrieve and process text and image columns in the same way it retrieves and processes any other type of column.It can select the columns, use MOREINFO="NONE"ct_fetch to loop through result rows, and useMOREINFO="NONE" ct_get_data to retrieve data in the text and image columns. An application will typically use this method when processing text or image values that are too large for convenient binding.ID="IN421159683"ct_get_datafetching text or image values
ID="IN421439884"Text and imageusing ct_get_data to fetch text or image valuesID="X53057" RENDERAS="SECT3"Using MOREINFO="NONE"ct_get_data to Fetch Text and Image ValuesREMAP="BO--Body"Only columns that follow the last column bound with MOREINFO="NONE"ct_bind are available for use with MOREINFO="NONE"ct_get_data.REMAP="BO--Body"For example, if an application selects four columns, all of which are text, and binds the first and third columns to program variables, then the application cannot use MOREINFO="NONE"ct_get_data to retrieve the text contained in the second column. It can still, however, use MOREINFO="NONE"ct_get_data to retrieve the text in the fourth column.REMAP="BO--Body"To retrieve a text or image value using MOREINFO="NONE"ct_get_data, an application follows these steps:NUMERATION="ARABIC" REMAP="S1--StepOne" CONTINUATION="RESTARTS" INHERITNUM="IGNORE"Execute a command that generates a result set that contains text or image columns.REMAP="UN--Under"An application can use a language command, RPC command, or dynamic SQL command to generate a result set containing text or image columns. REMAP="UN--Under"For example, the pic column in the au_pix table of the pubs2 database contains authors' pictures. To retrieve MOREINFO="NONE"them, an application might execute the following language command:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"ct_command(cmd, CS_LANG_CMD,         "select pic from au_pix",        CS_NULLTERM, CS_UNUSED);ct_send(cmd);Process the result set containing the text or image column.REMAP="UN--Under"An application uses MOREINFO="NONE"ct_fetch to loop through the rows contained in the result set. Inside the loop, for each unbound text or image column:MARK="DASH" REMAP="BS--BulletSub"The application can call MOREINFO="NONE"ct_get_data in a loop to retrieve the text or image data for the column.The application can call MOREINFO="NONE"ct_data_info to get an I/O descriptor that can be used to update the column at a later time.REMAP="UN--Under"Most applications will use a program structure similar to the following:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"while ct_fetch is returning rows    process any bound columns    for each unbound text or image column        while ct_get_data is returning data            process the data        end while        ct_data_info to get the column's CS_IODESC    end forend whileREMAP="UN--Under"Alternatively, for each unbound text or image column, an application can:MARK="DASH" REMAP="BS--BulletSub"Call MOREINFO="NONE"ct_get_data with the parameter buflen as 0, so that it returns no data but does refresh the I/O descriptor for the column.Call MOREINFO="NONE"ct_data_info to get the I/O descriptor for the column. The total_txtlen field in this structure represents the total length of the text or image value.Call MOREINFO="NONE"ct_get_data as many times as necessary to retrieve the value.REMAP="UN--Under"This method has the advantage of allowing an application to determine the total length of a text or image value before retrieving it.ID="IN42839885"Updatingtext or image columns
ID="IN421439886"Text and imageupdating a text or image columnID="X31032" RENDERAS="SECT2"Updating a Text or Image ColumnREMAP="BO--Body"An application can only update a value in a text or image column if it has a current I/O descriptor for the column value that it needs to update.REMAP="BO--Body"To retrieve the current I/O descriptor for a column value, an application must:NUMERATION="ARABIC" REMAP="S1--StepOne" CONTINUATION="RESTARTS" INHERITNUM="IGNORE"Call MOREINFO="NONE"ct_fetch to fetch the row of interest.Call MOREINFO="NONE"ct_get_data to retrieve the column's value and refresh the I/O descriptor for the column. To refresh the I/O descriptor without retrieving any data for the column, call MOREINFO="NONE"ct_get_data with buflen as 0.Call MOREINFO="NONE"ct_data_info to retrieve the I/O descriptor.REMAP="BO--Body"Once it has the current I/O descriptor for a column value, the application can perform the update:NUMERATION="ARABIC" REMAP="S1--StepOne" CONTINUATION="RESTARTS" INHERITNUM="IGNORE"Call MOREINFO="NONE"ct_command to initiate a send-data command.Modify the I/O descriptor, if necessary. Most applications will change only the values of the locale, total_txtlen, or log_on_update fields. Call MOREINFO="NONE"ct_data_info to set the I/O descriptor for the column value. The textptr field of the I/O descriptor structure identifies the target column of the send-data operation.Call MOREINFO="NONE"ct_send_data in a loop to write the entire text or image value. Each call to MOREINFO="NONE"ct_send_data writes a portion of the text or image value.Call MOREINFO="NONE"ct_send to send the command.Call MOREINFO="NONE"ct_results to process the results of the command. An update of a text or image value generates a a parameter result set containing a single parameter, the new text timestamp for the value. If the application plans to update this column value again, it must save the new timestamp and copy it into the CS_IODESC for the column value before calling MOREINFO="NONE"ct_data_info (step 3, above) to set the I/O descriptor for the new update.REMAP="BO--Body"Most applications will use a program structure similar to the following to update text or image columns:FLOAT="0"FORMAT="UNKNOWN" FILEREF="fig2_2.xwd"LBL="Figure 2-1: "Updating text or image columnsID="IN421439887"Text and imageinserting text and image valuesRENDERAS="SECT2"Populating a Table Containing Text or Image ColumnsREMAP="BO--Body"An application's method of populating a table containing text or image columns will depend on the size of the data values to be inserted.RENDERAS="SECT3"Smaller Text and Image ValuesREMAP="BO--Body"Most applications can embed text or image values of less than about 100K in an MOREINFO="NONE"insert statement:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"insert blurbs values ("486-29-1786", "If Chastity    Locksley didn't exist, this troubled...")REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"insert au_pix values ("486-29-1786", 0x67f44c...,    "ICT", "30220", "626", "635")Be aware that MS Windows applications are limited by the amount of memory available in the data segment.RENDERAS="SECT3"Larger Text and Image ValuesREMAP="BO--Body"Because it results in improved performance, the following method is recommended when populating a SQL Server table with text or image values larger than 100K:NUMERATION="ARABIC" REMAP="S1--StepOne" CONTINUATION="RESTARTS" INHERITNUM="IGNORE"MOREINFO="NONE"insert all data into the row except the text or image values.MOREINFO="NONE"update the row, setting the value of the text or image columns 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 text or image columns. This step is necessary in order to provide Client-Library with current I/O descriptor information.Call MOREINFO="NONE"ct_results and MOREINFO="NONE"ct_fetch to process the results of the MOREINFO="NONE"select. Although the actual data returned by this MOREINFO="NONE"select can be thrown away, the application must retrieve the I/O descriptor for each text or image column in the row. REMAP="UN--Under"For information on retrieving an I/O descriptor, see LINKEND="X31032""Updating a Text or Image Column" 
.Update the columns as described in LINKEND="X31032""Updating a Text or Image Column" 
.ID="IN421429988"Text and imageREMAP="BO--Body"ID="IN425-110289"TypesSee Also Datatypes
ID="IN4214-110290"Client-Librarydatatypes
ID="IN425-210391"TypesID="X22337" RENDERAS="SECT1"TypesREMAP="BO--Body"Open Client Client-Library supports a wide range of datatypes. These datatypes are shared with Open Client CS-Library and Open Server Server-Library. In most cases, they correspond directly to SQL Server datatypes.REMAP="BO--Body"The "Datatype Summary" chart, below, lists Open Client/Server type constants, their corresponding typedefs, and their corresponding SQL Server or Secure SQL Server datatypes, if any.REMAP="BO--Body"A list of Open Client routines that are useful in manipulating datatypes follows the summary chart, together with more detailed information on each datatype.REMAP="BO--Body"For additional information on datatypes, see Chapter 3, "Structures, Datatypes, Constants, and Conventions" in the Client-Library Programmer's Guide.ID="IN429-210392"Datatypeslist ofRENDERAS="SECT2"Datatype SummaryREMAP="BO--Body"The following table lists Open Client/Server type constants, their corresponding typedefs, and their corresponding SQL Server or Secure SQL Server datatypes, if any:TOCENTRY="1"LBL="Table 2-33: "Datatype summaryCOLS="5" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="55*"COLNAME="C2" COLWIDTH="128*"COLNAME="C3" COLWIDTH="105*"COLNAME="C4" COLWIDTH="104*"COLNAME="C5" COLWIDTH="76*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Open Client/Server 
Type ConstantCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DescriptionCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Corresponding Open 
Client/Server TypedefCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Corresponding
Server 
DatatypeVALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Binary 
typesCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BINARY_TYPECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Binary typeCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BINARYCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"binary,
varbinaryCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_LONGBINARY_TYPECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Long binary typeCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_LONGBINARYCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NONECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_VARBINARY_TYPECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Variable-length 
binary typeCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_VARBINARYCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NONECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Bit typesCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BIT_TYPECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Bit typeCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BITCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"boolean COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Character
typesCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CHAR_TYPECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Character typeCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CHARCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"char,
varcharCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_LONGCHAR_TYPECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Long character typeCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_LONGCHARCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NONECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_VARCHAR_TYPECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Variable-length 
character typeCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_VARCHARCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NONECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Datetime 
typesCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATETIME_TYPECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"8-byte datetime typeCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATETIMECOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"datetime COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATETIME4_TYPECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"4-byte datetime typeCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATETIME4COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"smalldatetime COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Numeric 
typesCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TINYINT_TYPECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"1-byte integer typeCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TINYINTCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"tinyint COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SMALLINT_TYPECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"2-byte integer typeCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SMALLINTCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"smallint COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_INT_TYPECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"4-byte integer typeCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_INTCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"int COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DECIMAL_TYPECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Decimal typeCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DECIMALCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"decimal COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_NUMERIC_TYPECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Numeric typeCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_NUMERICCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"numeric COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FLOAT_TYPECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"8-byte float typeCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FLOATCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"float COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_REAL_TYPECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"4-byte float typeCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_REALCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"real COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Money 
typesCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_MONEY_TYPECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"8-byte money typeCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_MONEYCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"money COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_MONEY4_TYPECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"4-byte money typeCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_MONEY4COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"smallmoney COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Security 
typesCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BOUNDARY_TYPECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Secure SQL Server 
boundary typeCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CHARCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"sensitivity_
boundary COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SENSITIVITY_TYPECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Secure SQL Server 
sensitivity typeCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CHARCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"sensitivity COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Text and 
image 
typesCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TEXT_TYPECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Text typeCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TEXTCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"text COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_IMAGE_TYPECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Image typeCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_IMAGECOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"imageID="IN429-210393"Datatypesroutines that manipulate datatypesRENDERAS="SECT2"Routines That Manipulate DatatypesREMAP="BO--Body"Open Client CS-Library provides several routines that are useful for manipulating datatypes. They include:MARK="BULL" REMAP="BU--Bullet"ID="IN429-410594"DatatypesDatatypesand cs_calccs_calc
MOREINFO="NONE"cs_calc, which performs arithmetic operations on decimal, money, and numeric datatypesID="IN429-610795"DatatypesDatatypesand cs_cmpcs_cmp
MOREINFO="NONE"cs_cmp, which compares datetime, decimal, money, and numeric datatypesID="IN429-810996"DatatypesDatatypesand cs_convertcs_convert
MOREINFO="NONE"cs_convert, which converts a data value from one datatype to anotherID="IN429-1011197"DatatypesDatatypesand cs_dt_crackcs_dt_crack
MOREINFO="NONE"cs_dt_crack, which converts a machine readable datetime value into a user-accessible formatID="IN429-1211398"DatatypesDatatypesand cs_dt_infocs_dt_info
MOREINFO="NONE"cs_dt_info, which sets or retrieves language-specific datetime informationID="IN429-1411599"DatatypesDatatypesand cs_strcmpcs_strcmp
MOREINFO="NONE"cs_strcmp, which compares two stringsREMAP="BO--Body"These routines are documented in the Open Client and Open Server Common Libraries Reference Manual.ID="IN428-14115100"TypedefsOpen Client
ID="IN4214-14115101"Client-LibrarytypedefsRENDERAS="SECT2"Open Client DatatypesID="IN4216-14115102"Binary datatypes
ID="IN429-14115103"DatatypesbinaryRENDERAS="SECT3"Binary TypesREMAP="BO--Body"Open Client has three binary types, ID="IN4218-18119104"CS_BINARY datatypebinary:CS_BINARY
CS_BINARY, ID="IN4222-22123105"CS_LONGBINARY datatypebinary:CS_LONGBINARY
CS_LONGBINARY, and ID="IN4221-26127106"CS_VARBINARY datatypebinary:CS_VARBINARY
CS_VARBINARY. REMAP="BO--Body"CS_BINARY corresponds to the SQL Server types binary and varbinary. That is, Client-Library interprets both the server binary and varbinary types as CS_BINARY. For example, MOREINFO="NONE"ct_describe returns CS_BINARY_TYPE when describing a result column that has the server datatype varbinary.REMAP="BO--Body"CS_BINARY is defined as:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"typedef unsigned char    CS_BINARY;    CS_LONGBINARY and CS_VARBINARY do not correspond to any SQL Server datatypes. Specifically, CS_VARBINARY does not correspond to the SQL Server datatype varbinary.REMAP="BO--Body"CS_LONGBINARY does not correspond to any SQL Server type, but some Open Server applications may support CS_LONGBINARY. An application can use the CS_DATA_LBIN capability to determine whether an Open Server connection supports CS_LONGBINARY. If it does, then MOREINFO="NONE"ct_describe can return CS_LONGBINARY when describing a result data item.REMAP="BO--Body"A CS_LONGBINARY value has a maximum length of 2,147,483,647 bytes. CS_LONGBINARY is defined as:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"typedef unsigned char    CS_LONGBINARY;REMAP="BO--Body"CS_VARBINARY does not correspond to any SQL Server type. For this reason, Open Client routines do not return CS_VARBINARY_TYPE. CS_VARBINARY is provided to enable non-C programming language veneers to be written for Open Client. Typical client applications will not use CS_VARBINARY.REMAP="BO--Body"CS_VARBINARY is defined as:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"typedef struct _cs_varybin{    CS_SMALLINT      len;    CS_BYTE          array[CS_MAX_CHAR];} CS_VARBINARY;REMAP="UN--Under"where:REMAP="UN--Under"len is the length of the binary array.REMAP="UN--Under"array is the array itself.REMAP="BO--Body"Although CS_VARBINARY variables are used to store variable-length values, CS_VARBINARY is considered to be a fixed-length type. This means that an application does not typically need to provide Client-Library with the length of a CS_VARBINARY variable. For example, MOREINFO="NONE"ct_bind ignores the value of datafmtname='rArrow' font='symbol' code='174'  charset='fontspecific'maxlength when binding to a CS_VARBINARY variable.ID="IN4212-26127107"Bit datatype
ID="IN429-26127108"DatatypesbitRENDERAS="SECT3"Bit TypesREMAP="BO--Body"Open Client supports a single bit type, ID="IN4215-30131109"CS_BIT datatypebit:CS_BIT
CS_BIT. This type is intended to hold server bit (or boolean) values of 0 or 1. When converting other types to bit, all non-zero values are converted to 1:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"typedef unsigned char    CS_BIT;    ID="IN429-30131110"Datatypescharacter
ID="IN4219-30131111"Character datatypesRENDERAS="SECT3"Character TypesREMAP="BO--Body"Open Client has three character types, ID="IN4216-34135112"CS_CHAR datatypecharacter:CS_CHAR
CS_CHAR, ID="IN4220-38139113"CS_LONGCHAR datatypecharacter:CS_LONGCHAR
CS_LONGCHAR, and ID="IN4219-42143114"CS_VARCHAR datatypecharacter:CS_VARCHAR
CS_VARCHAR:REMAP="BO--Body"CS_CHAR corresponds to the SQL Server types char and varchar. That is, Client-Library interprets both the server char and varchar types as CS_CHAR. For example, MOREINFO="NONE"ct_describe returns CS_CHAR_TYPE when describing a result column that has the server datatype varchar.REMAP="BO--Body"CS_CHAR is defined as:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"typedef char    CS_CHAR;CS_LONGCHAR and CS_VARCHAR do not correspond to any SQL Server datatypes. Specifically, CS_VARCHAR does not correspond to the SQL Server datatype varchar.REMAP="BO--Body"CS_LONGCHAR does not correspond to any SQL Server type, but some Open Server applications may support CS_LONGCHAR. An application can use the CS_DATA_LCHAR capability to determine whether an Open Server connection supports CS_LONGCHAR. If it does, then MOREINFO="NONE"ct_describe can return CS_LONGCHAR when describing a result data item.REMAP="BO--Body"A CS_LONGCHAR value has a maximum length of 2,147,483,647 bytes. CS_LONGCHAR is defined as:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"typedef unsigned char    CS_LONGCHAR;REMAP="BO--Body"CS_VARCHAR does not correspond to any SQL Server type. For this reason, Open Client routines do not return CS_VARCHAR_TYPE. CS_VARCHAR is provided to enable non-C programming language veneers to be written for Open Client. Typical client applications will not use CS_VARCHAR.REMAP="BO--Body"CS_VARCHAR is defined as:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"typedef struct _cs_varchar{    CS_SMALLINT      len;    CS_CHAR          str[CS_MAX_CHAR];} CS_VARCHAR;REMAP="UN--Under"where:REMAP="UN--Under"len is the length of the string.REMAP="UN--Under"str is the string itself. Note that str is not a null-terminated string.REMAP="BO--Body"Although CS_VARCHAR variables are used to store variable-length values, CS_VARCHAR is considered to be a fixed-length type. This means that an application does not typically need to provide Client-Library with the length of a CS_VARCHAR variable. For example, MOREINFO="NONE"ct_bind ignores the value of datafmtname='rArrow' font='symbol' code='174'  charset='fontspecific'maxlength when binding to a CS_VARCHAR variable.ID="IN429-42143115"Datatypesdatetime
ID="IN4218-42143116"Datetime datatypesRENDERAS="SECT3"Datetime TypesREMAP="BO--Body"Open Client supports two datetime types, ID="IN4220-46147117"CS_DATETIME datatypedatetime:CS_DATETIME
CS_DATETIME and ID="IN4221-50151118"CS_DATETIME4 datatypedatetime:CS_DATETIME4
CS_DATETIME4. These datatypes are intended to hold 8-byte and 4-byte datetime values, respectively. REMAP="BO--Body"An Open Client application can use the CS-Library Routine MOREINFO="NONE"cs_dt_crack to extract date parts (year, month, day, etc.) from a datetime structure.REMAP="BO--Body"CS_DATETIME corresponds to the SQL Server datetime datatype. The range of legal CS_DATETIME values is from January 1, 1753 to December 31, 9999, with a precision of 1/300th of a second (3.33 milliseconds):REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"typedef struct _cs_datetime{    CS_INT    dtdays;    CS_INT    dttime;} CS_DATETIME;REMAP="UN--Under"where:REMAP="UN--Under"dtdays is the number of days since 1/1/1900.REMAP="UN--Under"dttime is the number of 300ths of a second since midnight.REMAP="BO--Body"MOREINFO="NONE"CS_DATETIME4 corresponds to the SQL Server smalldatetime 
datatype. The range of legal CS_DATETIME4 values is from January 1, 1900 to June 6, 2079, with a precision of 1 minute:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"typedef struct _cs_datetime4{    CS_USHORT    days;    CS_USHORT    minutes;} CS_DATETIME4;            REMAP="UN--Under"where:REMAP="UN--Under"days is the number of days since 1/1/1900.REMAP="UN--Under"minutes is the number of minutes since midnight.ID="IN4217-50151119"Integer datatypes
ID="IN429-50151120"Datatypesinteger
ID="IN4216-50151121"Decimal datatype
ID="IN4216-50151122"Numeric datatype
ID="IN4214-50151123"Float datatype
ID="IN4213-50151124"Real datatypeRENDERAS="SECT3"Numeric TypesREMAP="BO--Body"Open Client supports a wide range of numeric types.REMAP="BO--Body"Integer types include ID="IN4219-54155125"CS_TINYINT datatypeinteger:CS_TINYINT
CS_TINYINT, a 1-byte integer; ID="IN4220-58159126"CS_SMALLINT datatypeinteger:CS_SMALLINT
CS_SMALLINT, a 2-byte integer, and ID="IN4215-62163127"CS_INT datatypeinteger:CS_INT
CS_INT, a 4-byte integer:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"typedef unsigned char    CS_TINYINT;REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"typedef short            CS_SMALLINT;REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"typedef long             CS_INT;REMAP="BO--Body"ID="IN4216-66167128"CS_REAL datatypereal:CS_REAL
CS_REAL corresponds to the SQL Server datatype real. It is implemented as a C-language float type:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"typedef float    CS_REAL;REMAP="BO--Body"ID="IN4217-70171129"CS_FLOAT datatypefloat:CS_FLOAT
CS_FLOAT corresponds to the SQL Server datatype float. It is implemented as a C-language double type:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"typedef double   CS_FLOAT;REMAP="BO--Body"ID="IN4219-74175130"CS_NUMERIC datatypenumeric:CS_NUMERIC
CS_NUMERIC and ID="IN4219-78179131"CS_DECIMAL datatypedecimal:CS_DECIMAL
CS_DECIMAL correspond to the SQL Server datatypes numeric and decimal. These types provide platform-independent support for numbers with precision and scale.REMAP="BO--Body"The SQL Server datatypes numeric and decimal are equivalent; and CS_DECIMAL is defined as CS_NUMERIC:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"typedef struct_cs_numeric{    CS_BYTE         precision;    CS_BYTE         scale;    CS_BYTE         array[CS_MAX_NUMLEN];} CS_NUMERIC;REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"typedef CS_NUMERIC   CS_DECIMAL;REMAP="UN--Under"where:REMAP="UN--Under"precision is the precision of the numeric value. At the current time, legal values for precision are from 1 to 77. The default precision is 18. CS_MIN_PREC, CS_MAX_PREC, and CS_DEF_PREC define the minimum, maximum, and default precision values, respectively.REMAP="UN--Under"scale is the scale of the numeric value. At the current time, legal values for scale are from 0 to 77. The default scale is 0. CS_MIN_SCALE, CS_MAX_SCALE, and CS_DEF_PREC define the minimum, maximum, and default scale values, respectively.REMAP="UN--Under"scale must be less than or equal to precision.REMAP="BO--Body"CS_DECIMAL types use the same default values for precision and scale as CS_NUMERIC types.    ID="IN4215-78179132"Money datatypes
ID="IN429-78179133"DatatypesmoneyRENDERAS="SECT3"Money TypesREMAP="BO--Body"Open Client supports two money types, ID="IN4217-82183134"CS_MONEY datatypemoney:CS_MONEY
CS_MONEY and ID="IN4218-86187135"CS_MONEY4 datatypemoney:CS_MONEY4
CS_MONEY4. These datatypes are intended to hold 8-byte and 4-byte money values, respectively.REMAP="BO--Body"CS_MONEY corresponds to the SQL Server money datatype. The range of legal CS_MONEY values is between +/- $922,337,203,685,477.5807:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"typedef struct _cs_money{    CS_INT      mnyhigh;    CS_UINT     mnylow;} CS_MONEY;REMAP="BO--Body"CS_MONEY4 corresponds to the SQL Server smallmoney datatype. The range of legal CS_MONEY4 values is between -$214,748.3648 and +$214,748.3647:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"typedef struct _cs_money4{    CS_INT    mny4;} CS_MONEY4;ID="IN429-86187136"Datatypessecurity
ID="IN428-86187137"SecuritydatatypesRENDERAS="SECT3"Security TypesREMAP="BO--Body"Open Client supports Secure SQL Server's sensitivity_boundary and sensitivity types by defining the type constants ID="IN4225-90191138"CS_BOUNDARY_TYPE datatypesecurity:CS_BOUNDARY_TYPE
CS_BOUNDARY_TYPE and ID="IN4228-94195139"CS_SENSITIVITY_TYPE datatypesecurity:CS_SENSITIVITY_TYPE
CS_SENSITIVITY_TYPE. REMAP="BO--Body"These type constants differ from other Open Client type constants in that they do not correspond to similarly-named typedefs. Instead, they correspond to CS_CHAR.REMAP="BO--Body"This means that although Open Client routines accept and return CS_BOUNDARY_TYPE and CS_SENSITIVITY_TYPE to describe a column or variable's datatype, any corresponding program variable must be of type CS_CHAR.REMAP="BO--Body"For example, if an application calls MOREINFO="NONE"ct_bind with the datatype field of the CS_DATAFMT structure set to CS_SENSITIVITY_TYPE, the program variable to which the data is being bound must be of type CS_CHAR.ID="IN429-94195140"Datatypestext and image
ID="IN4214-94195141"Text and imagedatatypesRENDERAS="SECT3"Text and Image TypesREMAP="BO--Body"Open Client supports a text datatype, ID="IN4216-98199142"CS_TEXT datatypetext and image:CS_TEXT
CS_TEXT, and an image datatype, ID="IN4217-102203143"CS_IMAGE datatypetext and image:CS_IMAGE
CS_IMAGE.REMAP="BO--Body"CS_TEXT corresponds to the server datatype text, which describes a variable-length column containing up to 2,147,483,647 bytes of printable character data. CS_TEXT is defined as unsigned character:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"typedef unsigned char    CS_TEXT;REMAP="BO--Body"CS_IMAGE corresponds to the server datatype image, which describes a variable-length column containing up to 2,147,483,647 bytes of binary data. CS_IMAGE is defined as unsigned character:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"typedef unsigned char    CS_IMAGE;ID="IN4222-102203144"User-defined datatypes
ID="IN4214-102203145"Client-Libraryuser-defined datatypes
ID="IN429-102203146"Datatypesuser-defined typesID="X38742" RENDERAS="SECT2"Open Client User-Defined DatatypesREMAP="BO--Body"An application that needs to use a datatype that is not included in the standard Open Client type set can create a user-defined datatype.REMAP="BO--Body"An Client-Library application creates a user-defined type by declaring it: REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"typedef char    CODE_NAME;REMAP="BO--Body"Because the Open Client routines MOREINFO="NONE"ct_bind and MOREINFO="NONE"cs_set_convert use integer symbolic constants to identify datatypes, it is often convenient for an application to declare a type constant for a user-defined type. User-defined types must be defined as greater than or equal to CS_USERTYPE:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"#define CODE_NAME_TYPE    CS_USERTYPE + 2;REMAP="BO--Body"Once a user-defined type has been created, an application can:MARK="BULL" REMAP="BU--Bullet"Call MOREINFO="NONE"cs_set_convert to install custom conversion routines to convert between standard Open Client types and the user-defined typeCall MOREINFO="NONE"cs_setnull to define a null substitution value for the user-defined type.REMAP="BO--Body"After conversion routines are installed, an application can bind server results to a user-defined type:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"mydatafmt.datatype = CODE_NAME_TYPE;ct_bind(cmd, 1, &mydatafmt, mycodename, NULL,    NULL);REMAP="BO--Body"Custom conversion routines are called transparently, whenever required, by MOREINFO="NONE"ct_bind and MOREINFO="NONE"cs_convert. Do not confuse Open Client user-defined types with SQL Server user-defined types. Open Client user-defined types are C-language types, declared within an application. SQL Server user-defined types are database column datatypes, created using the system stored procedure MOREINFO="NONE"sp_addtype.ID="IN425-103204147"TypesREMAP="BO--Body"REMAP="BO--Body"NUMBER="3" ID="X47797"RoutinesREMAP="BO--Body"This chapter contains a manual page for each Client-Library routine.ID="X29013"ct_bindID="IN4379753"Bindingbinding results to program variables
ID="INA4379754"Resultsbinding results to program variables
ID="IN4399755"Variablesbinding results to program variables
Bind server results to program variables. REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_bind(cmd, item, datafmt, buffer,                copied, indicator) CS_COMMAND      *cmd;CS_INT          item;CS_DATAFMT      *datafmt;CS_VOID         *buffer;CS_INT          *copied;CS_SMALLINT     *indicator;ParametersREMAP="RI--RefIndent"cmd - A pointer to the CS_COMMAND structure managing a client/ server operation. item - An integer representing the number of the column, parameter, or status to bind. REMAP="UN--Under"When binding a column, item is the column's column number. The first column in a MOREINFO="NONE"select statement's select-list is column number 1, the second number 2, and so forth. ID="IN4379758"Columnsbinding to program variablesREMAP="UN--Under"When binding a compute column, item is the column number of the compute column. Compute columns are returned in the order in which they are listed in the compute clause. The first column returned is number 1. ID="IN43159759"Compute columnsbinding to program variablesREMAP="UN--Under"When binding a return parameter, item is the parameter number of the parameter. The first parameter returned by a stored procedure is number 1. Stored procedure return parameters are returned in the same order as the parameters were originally specified in the stored procedure's MOREINFO="NONE"create procedure statement. This is not necessarily the same order as specified in the RPC command that invoked the stored procedure. In determining what number to pass as item do not count non-return parameters. For example, if the second parameter in a stored procedure is the only return parameter, pass item as 1. ID="IN431797510"Parameter resultsbinding to program variablesREMAP="UN--Under"When binding a stored procedure return status, item must be 1, as there can be only a single status in a return status result set.ID="IN431397511"Return statusbinding to a program variableREMAP="UN--Under"To clear all bindings, pass item as CS_UNUSED, with datafmt, buffer, copied, and indicator as NULL.ID="IN43797512"Bindingclearing bindingsdatafmt ID="IN432093913"CS_DATAFMT structureCS_DATAFMT structureand ct_bindct_bind
- A pointer to the CS_DATAFMT structure that describes the destination variable(s).REMAP="UN--Under"The chart below lists the fields in *datafmtID="IN437891314"ct_bindct_bindand CS_DATAFMT structureCS_DATAFMT structure
that are used by MOREINFO="NONE"ct_bind, and contains general information about the fields. MOREINFO="NONE"ct_bind ignores fields that it does not use:TOCENTRY="1"LBL="Table 3-1: "Fields in the CS_DATAFMT structure (MOREINFO="NONE"ct_bind)COLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="59*"COLNAME="C2" COLWIDTH="108*"COLNAME="C3" COLWIDTH="304*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Field 
name:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"When is the field 
used?COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Set the field to:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"name COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Not used.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Not applicable.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"namelen COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Not used.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Not applicable.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"datatype COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"When binding all 
types of results.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A type constant (CS_xxx_TYPE) representing the datatype of the 
destination variable.

All type constants listed on the MOREINFO="NONE"Types topics page are valid. Open 
Client user-defined types are also valid, provided that user-
supplied conversion routines have been installed via 
MOREINFO="NONE"cs_set_convert. If datatype is an Open Client user-defined type, 
MOREINFO="NONE"ct_bind does not validate any CS_DATAFMT fields except count.
MOREINFO="NONE"
ct_bind supports a wide range of type conversions, so datatype can 
be different from the type returned by the server. For instance, by 
specifying a destination type of CS_FLOAT_TYPE, a CS_MONEY 
result can be bound to a CS_FLOAT program variable. The 
appropriate data conversion happens automatically. For a list of 
the data conversions provided by Client-Library, see the manual 
page for MOREINFO="NONE"cs_willconvert.

If datatype is CS_BOUNDARY_TYPE or CS_SENSITIVITY_TYPE, 
the *buffer program variable must be of type CS_CHAR.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"format COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"When binding 
results to character- 
or binary-type 
destination 
variables; otherwise 
CS_FMT_UNUSED.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A bit-mask of the following symbols:

For character and text destinations only:
CS_FMT_NULLTERM to null-terminate the data, or 
CS_FMT_PADBLANK to pad to the full length of the variable with 
spaces.

For character, binary, text, and image destinations:
CS_FMT_PADNULL to pad to the full length of the variable with 
nulls.

For any type of destination:
CS_FMT_UNUSED if no format information is being provided.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"maxlength COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"When binding all 
types of results to non-fixed-length types.

When binding to 
fixed-length types, 
maxlength is ignored.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The length of the *buffer destination variable. If buffer points to an 
array, set maxlength to the length of a single element of the array.

When binding to character or binary destinations, maxlength must 
describe the total length of the destination variable, including any 
space required for special terminating bytes, such as a null 
terminator.

If maxlength indicates that *buffer is not large enough to hold a 
result data item, then at fetch time MOREINFO="NONE"ct_fetch discards the result item 
that is too large, fetches any remaining items in the row, and 
returns CS_ROW_FAIL. If this occurs the contents of *buffer are 
undefined.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"scale COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Only when binding 
to numeric or 
decimal destinations.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The scale to be used for the destination variable.

If the source data is the same type as the destination, then scale can 
be set to CS_SRC_VALUE to indicate that the destination should 
pick up its value for scale from the source data.

scale must be less than or equal to precision.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"precision COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Only when binding 
to numeric or 
decimal destinations.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The precision to be used for the destination variable.

If the source data is the same type as the destination, then precision 
can be set to CS_SRC_VALUE to indicate that the destination 
should pick up its value for precision from the source data.

precision must be greater than or equal to scale.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"status COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Not used.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Not applicable.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"count COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"When binding all 
types of results.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"count is the number of result rows to be copied to program 
variables per MOREINFO="NONE"ct_fetch call. 

If count is larger than the number of available rows, only the 
available rows are copied. (Note that only regular row and cursor 
row result sets will ever contain multiple rows.)

count must have the same value for all columns in a result set, with 
one exception: an application can intermix counts of 0 and 1.

If count is 0, 1 row is fetched.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"usertype COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Not used.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Not applicable.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"locale COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"When binding all 
types of results.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to a CS_LOCALE structure containing locale 
information for the *buffer destination variable.

If custom locale information is not required for the variable, pass 
locale as NULL.buffer - The address of an array of datafmtname='rArrow' font='symbol' code='174'  charset='fontspecific'
count variables, each of which is of size datafmtname='rArrow' font='symbol' code='174'  charset='fontspecific'
maxlength.REMAP="UN--Under" *buffer is the program variable or variables to which MOREINFO="NONE"ct_bind binds the server results. When the application calls MOREINFO="NONE"ct_fetch to fetch the result data, it is copied into this space.REMAP="UN--Under"If buffer is NULL, MOREINFO="NONE"ct_bind clears the binding for this result item. Note that if buffer is NULL, datafmt, copied, and indicator must also be NULL.copied - The address of an array of datafmtname='rArrow' font='symbol' code='174'  charset='fontspecific'
count integer variables. At fetch timeMOREINFO="NONE", ct_fetch fills this array with the lengths of the copied data. copied is an optional parameter and can be passed as NULL.indicator - The address of an array of datafmtname='rArrow' font='symbol' code='174'  charset='fontspecific'
count CS_SMALLINT variables. At fetch time, each variable is used to indicate certain conditions about the fetched data. indicator is an optional parameter and can be passed as NULL.REMAP="UN--Under"The following table lists the values that an indicator variable can have: TOCENTRY="1"LBL="Table 3-2: "Values for indicator (MOREINFO="NONE"ct_bind)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"Value of indicator 
variable:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Indicates: VALIGN="TOP"COLNAME="C1" ALIGN="CENTER" ROTATE="0" MOREROWS="0"-1COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The fetched data was NULL. In this case, no data 
is copied to *buffer.COLNAME="C1" ALIGN="CENTER" ROTATE="0" MOREROWS="0"0COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The fetch was successful. COLNAME="C1" ALIGN="CENTER" ROTATE="0" MOREROWS="0"integer valueCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The actual length of the server data, if the fetch 
resulted in truncation. ReturnsREMAP="BO--Body"TOCENTRY="1"LBL="Table 3-3: "Return values (MOREINFO="NONE"ct_bind)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="106*"COLNAME="C2" COLWIDTH="253*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine completed successfully.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BUSYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An asynchronous operation is already pending for this 
connection. For more information, see the 
MOREINFO="NONE"Asynchronous Programming topics page.ID="IN437871516"ct_bindcommon reasons for failureREMAP="BO--Body"Common reasons for a MOREINFO="NONE"ct_bind failure include:MARK="BULL" REMAP="BU--Bullet"An illegal datatype specified via datafmtname='rArrow' font='symbol' code='174'  charset='fontspecific'datatype.A bad datafmtname='rArrow' font='symbol' code='174'  charset='fontspecific'locale pointer. Initialize datafmtname='rArrow' font='symbol' code='174'  charset='fontspecific'locale to NULL if it is not used.Requested conversion is not available.CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"ct_bind can be used to bind a regular or cursor result column, a compute column, a return parameter, or a stored procedure status number.   When binding a regular or cursor column, multiple rows of the column can be bound with a single call to MOREINFO="NONE"ct_bind.Message, describe, row format, and compute format results are not bound. This is because result sets of type CS_MSG_RESULT, CS_DESCRIBE_RESULT, CS_ROWFMT_RESULT, and CS_COMPUTEFMT_RESULT contain no fetchable data. Instead, these result sets indicate that certain types of information are available. An application can retrieve the information by calling other Client-Library routines, such as MOREINFO="NONE"ct_res_info. For more information on how to process these types of results, see the LINKEND="X51426""Results"
topics page.ID="IN437871518"BindingpurposeBinding associates a result data item with a program variable. At fetch time, each MOREINFO="NONE"ct_fetch call copies a row-instance of the data item into the variable with which the item is associated.ID="IN437871519"Bindingbinding large values
ID="IN437851720"Bindingusing ct_get_data insteadREMAP="UN--Under"If a result data item is very large (for example, a large text or image column), it is often more convenient for an application to use ID="IN4311812121"ct_get_dataalternative to ct_bind
MOREINFO="NONE"ct_get_data to retrieve the data item's value in chunks, rather than copying the entire value to a bound variable. For more information on MOREINFO="NONE"ct_get_data, see the MOREINFO="NONE"ct_get_data manual page, and the MOREINFO="NONE"Text and Image topics page.MOREINFO="NONE"ct_bind binds only the current result type. MOREINFO="NONE"ct_results indicates the current result type via its result_type parameter. For example, if MOREINFO="NONE"ct_results sets *result_type to CS_STATUS_RESULT, a return status is available for binding.ID="IN437792322"BindingBindingand ct_res_infoct_res_infoAn application can call MOREINFO="NONE"ct_res_infoID="IN437772523"BindingBindingand ct_describect_describe
to determine the number of items in the current result set, and can call MOREINFO="NONE"ct_describe to get a description of each item. ID="IN437772524"Bindingbinding to multiple variables not allowedAn application can only bind a result item to a single program variable. If an application binds a result item to multiple variables, only the last binding has any effect.ID="IN437772525"Bindingre-bindingAn application can re-bind while actively fetching rows. That is, an application can call MOREINFO="NONE"ct_bind inside a MOREINFO="NONE"ct_fetch loop if it needs to change a result item's binding. ID="IN437772526"Bindinghow long it remains in effectIf not changed, binding for a particular type of result remains in effect until MOREINFO="NONE"ct_results returns CS_CMD_DONE to indicate that the results of a logical command are completely processed. This saves an application the trouble of re-binding interspersed regular row results and compute row results that are generated by the same command.REMAP="UN--Under"For example, a language command containing a MOREINFO="NONE"select statement with MOREINFO="NONE"compute and MOREINFO="NONE"order by clauses can generate multiple buffers full of regular row results intermixed with compute row results. Because they are generated by the same command, each buffer of regular row results and each buffer of compute row results will contain identical columns. An application need only bind the first buffer of regular row results and the first buffer of compute results. These bindings will remain in effect until both result sets are completely processed.An application can use MOREINFO="NONE"ct_bind to bind to Open Client user-defined datatypes for which conversion routines have been installed. To install a conversion routine for a user-defined datatype, an application calls MOREINFO="NONE"cs_set_convert. For more information on Open Client user-defined types, see LINKEND="X38742""Open Client User-Defined Datatypes" 
.ID="IN437772527"Bindingclearing bindingsClearing BindingsMARK="BULL" REMAP="BU--Bullet"To clear the binding for a result item, call MOREINFO="NONE"ct_bind with buffer, datafmt, copied, and indicator as NULL. To clear all bindings, call MOREINFO="NONE"ct_bind with item as CS_UNUSED and buffer, datafmt, copied, and indicator as NULL.It is not an error to clear a non-existent binding. Array Binding MARK="BULL" REMAP="BU--Bullet"Array binding is the process of binding a result column to an array of program variables. At fetch time, multiple rows' worth of a column are copied to an array of variables with a single MOREINFO="NONE"ct_fetch call. An application indicates array binding by setting datafmtname='rArrow' font='symbol' code='174'  charset='fontspecific'count to a value greater than 1.ID="IN437772528"Bindingarray binding
ID="IN4313772529"Array bindingArray binding is only practical for regular row and cursor results. This is because other types of results are considered to be the equivalent of a single row.ID="IN437772530"Bindingbinding columns to arraysWhen binding columns to arrays, all MOREINFO="NONE"ct_bind calls in the sequence of calls binding the columns must use the same value for datafmtname='rArrow' font='symbol' code='174'  charset='fontspecific'
count. For example, when binding three columns to arrays, it is an error to use a count of five in the first two MOREINFO="NONE"ct_bind calls and a count of three in the last.REMAP="UN--Under"However, an application can intermix counts of 0 and 1. counts of 0 and 1 are considered to be equivalent because they both cause MOREINFO="NONE"ct_fetch to fetch a single row.ID="IN437752731"ct_bindcode exampleExampleREMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"CS_RETCODE      retcode;CS_INT          num_cols;CS_INT          i;CS_INT          j;CS_INT          row_count = 0;CS_INT          rows_read;CS_INT          disp_len;CS_DATAFMT      *datafmt;EX_COLUMN_DATA  *coldata;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* Determine the number of columns in this result set */....CODE DELETED.....REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/*        ** Our program variable, called 'coldata', is an array of ** EX_COLUMN_DATA structures. Each array element represents** one column.  Each array element will be re-used for each** row.**** First, allocate memory for the data element to process.*/coldata = (EX_COLUMN_DATA *)malloc(num_cols *     sizeof (EX_COLUMN_DATA));REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"if (coldata == NULL){    ex_error("ex_fetch_data: malloc() failed");    return CS_MEM_ERROR;}datafmt = (CS_DATAFMT *)malloc(num_cols *     sizeof (CS_DATAFMT));if (datafmt == NULL){    ex_error("ex_fetch_data: malloc() failed");   free(coldata);   return CS_MEM_ERROR;}REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/*** Loop through the columns, getting a description of each** one and binding each one to a program variable.**** We're going to bind each column to a character string; ** this will show how conversions from server native** datatypes to strings can occur via bind.**** We're going to use the same datafmt structure for both** the describe and the subsequent bind.**** If an error occurs within the for loop, a break is used** to get out of the loop and the data that was allocated** is freed before returning.*/for (i = 0; i < num_cols; i++){    /*    ** Get the column description.  ct_describe() fills    ** the datafmt parameter with a description of the   ** column.    */    retcode = ct_describe(cmd, (i + 1), &datafmt[i]);    if (retcode != CS_SUCCEED)    {        ex_error("ex_fetch_data: ct_describe() failed");        break;    }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /*    ** Update the datafmt structure to indicate that we    ** want the results in a null terminated character    ** string.   **    ** First, update datafmt.maxlength to contain the    ** maximum possible length of the column. To do this,    ** call ex_display_len() to determine the number of    ** bytes needed for the character string    ** representation, given the datatype described    ** above. Add one for the null termination character.   */    datafmt[i].maxlength = ex_display_dlen(&datafmt[i])           + 1;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /*    ** Set datatype and format to tell bind we want things    ** converted to null terminated strings.    */    datafmt[i].datatype = CS_CHAR_TYPE;    datafmt[i].format = CS_FMT_NULLTERM;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /*    ** Allocate memory for the column string     */    coldata[i].value = (CS_CHAR *)malloc         (datafmt[i].maxlength);    if (coldata[i].value == NULL)    {         ex_error("ex_fetch_data: malloc() failed");         retcode = CS_MEM_ERROR;        break;   }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /* Now bind. */   retcode = ct_bind(cmd, (i + 1), &datafmt[i],         coldata[i].value, &coldata[i].valuelen,        &coldata[i].indicator);    if (retcode != CS_SUCCEED)   {   ex_error("ex_fetch_data: ct_bind() failed");         break;    }}REMAP="BO--Body"This code excerpt is from the exutils.c example program.For further examples of using MOREINFO="NONE"ct_bind, see the compute.c, ex_alib.c, getsend.c, and i18n.c example programs.See AlsoREMAP="BO--Body"LINKEND="X64204"ct_describe
MOREINFO="NONE", LINKEND="X65123"ct_fetch
MOREINFO="NONE", LINKEND="X70623"ct_res_info
MOREINFO="NONE", LINKEND="X57817"ct_results
MOREINFO="NONE", LINKEND="X22337"Types
ID="IN437723034"ct_bind
MOREINFO="NONE"  ID="IN4312693335"ct_br_columnID="X48187"ct_br_columnID="IN4411693437"Browse moderetrieving information about a browse mode column
ID="IN447693438"Columnsretrieving information about a browse mode column
Retrieve information about a column generated by a browse-mode MOREINFO="NONE"select.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_br_column(cmd, colnum, browsedesc) CS_COMMAND        *cmd;CS_INT            colnum;CS_BROWSEDESC     *browsedesc;ParametersREMAP="RI--RefIndent"cmd - A pointer to the CS_COMMAND structure managing a client/ server operation. colnum - The number of the column to describe. The first column in a MOREINFO="NONE"select statement's select-list is column number 1, the second is number 2, and so forth.browsedesc - A pointer to a CS_BROWSEDESC structure. MOREINFO="NONE"ct_br_column fills this structure with information about the column specified by colnum.REMAP="UN--Under"For information on the CS_BROWSEDESC structure, see the MOREINFO="NONE"CS_BROWSEDESC topics page.ReturnsREMAP="BO--Body"TOCENTRY="1"LBL="Table 3-4: "Return values (MOREINFO="NONE"ct_br_column)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="106*"COLNAME="C2" COLWIDTH="253*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine completed successfully.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_br_column returns CS_FAIL if the current result set 
was not generated by a MOREINFO="NONE"select...for browse.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BUSYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An asynchronous operation is already pending for this 
connection. For more information, see the 
MOREINFO="NONE"Asynchronous Programming topics page.CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"ct_br_column fills *browsedesc with information about the column specified by colnum.ID="INA4411693443"Browse modeconditions for updating a columnA column can be updated through browse mode only if it meets three conditions:MARK="DASH" REMAP="BS--BulletSub"It belongs to a browsable table.It is the result of a MOREINFO="NONE"select...for browse.It is not the result of a SQL expression, such as MOREINFO="NONE"max(colname).It is an error to call MOREINFO="NONE"ct_br_columnID="IN4411693444"Browse modewhen browse mode information is available
if browse-mode information is not available. Generally, browse mode information is available if the current result set is a CS_ROW_RESULT result set that was generated by a MOREINFO="NONE"select...for browse.REMAP="UN--Under"Before calling MOREINFO="NONE"ct_br_column, an application can call MOREINFO="NONE"ct_res_info with type as CS_BROWSE_INFO to check whether browse mode information is available.See the MOREINFO="NONE"Browse Mode topics page for more information on browse mode.See AlsoREMAP="BO--Body"LINKEND="X24200"Browse Mode
MOREINFO="NONE", LINKEND="X35876"ct_br_table
ID="IN4412663746"ct_br_column
MOREINFO="NONE"  ID="IN4411634047"ct_br_tableID="X35876"ct_br_tableID="IN4511634149"Browse moderetrieving information about browse mode tables
Return information about browse mode tables.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_br_table(cmd, tabnum, type,                buffer, buflen, outlen) CS_COMMAND      *cmd;CS_INT          tabnum;CS_INT          type;CS_VOID         *buffer;CS_INT          buflen;CS_INT          *outlen;Parameters REMAP="RI--RefIndent"cmd - A pointer to the CS_COMMAND structure managing a client/ server operation.tabnum - The number of the table of interest. The first table in a MOREINFO="NONE"select statement's MOREINFO="NONE"from-list is table number 1, the second number 2, and so forth.type - The type of information to return. The following table lists the symbolic values that are legal for type:TOCENTRY="1"LBL="Table 3-5: "Values for type (MOREINFO="NONE"ct_br_table)COLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="99*"COLNAME="C2" COLWIDTH="159*"COLNAME="C3" COLWIDTH="101*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Value of type:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_br_table returns:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"*buffer set to:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_ISBROWSECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether or not the table is 
browsable. A table is browsable 
if it has a unique index and a 
timestamp column.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE or 
CS_FALSE.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TABNAMECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The name of the table whose 
number is MOREINFO="NONE"tabnum.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A string value.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TABNUMCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The number of tables named in
the browse-mode MOREINFO="NONE"select.
If type is CS_TABNUM, pass
tabnum as CS_UNUSED.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An integer value.buffer - A pointer to the space in which MOREINFO="NONE"ct_br_table will place the requested information. buflen - The length, in bytes, of the *buffer data space. REMAP="UN--Under"If type is CS_ISBROWSE or CS_TABNUM, pass buflen as CS_UNUSED.outlen - A pointer to an integer variable. REMAP="UN--Under"If supplied,MOREINFO="NONE" ct_br_table sets *outlen to the length, in bytes, of the requested information. REMAP="UN--Under"If the requested information is larger than buflen bytes, an application can use the value of *outlen to determine how many bytes are needed to hold the information. ReturnsTOCENTRY="1"LBL="Table 3-6: "Return values (MOREINFO="NONE"ct_br_table)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="106*"COLNAME="C2" COLWIDTH="253*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine completed successfully.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_br_table returns CS_FAIL if the current result set 
was not generated by a MOREINFO="NONE"select...for browse.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BUSYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An asynchronous operation is already pending for this 
connection. For more information, see the 
MOREINFO="NONE"Asynchronous Programming topics page.CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"ct_br_table returns either the number of tables named in the MOREINFO="NONE"select statement or information about a particular table.ID="IN4511634154"Browse modebrowsable table attributesA table is browsable if it has a unique index and a timestamp column.It is an error to call MOREINFO="NONE"ct_br_table if browse-mode information is not available. Generally, browse mode information is available if the current result set is a CS_ROW_RESULT result set that was generated by a MOREINFO="NONE"select...for browse.Before calling MOREINFO="NONE"ct_br_table, an application can call MOREINFO="NONE"ct_res_info with type as CS_BROWSE_INFO to check whether browse mode information is available.For more information on browse mode, see the MOREINFO="NONE"Browse Mode topics page.See AlsoREMAP="BO--Body"LINKEND="X24200"Browse Mode
, LINKEND="X48187"ct_br_column
ID="IN4511604456"ct_br_tableID="X39627"ct_callbackID="INA4399753"Callbacksinstalling
ID="IN4399754"Callbacksretrieving
Install or retrieve a Client-Library callback routine. REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_callback(context, connection,            action, type, func) CS_CONTEXT      *context;CS_CONNECTION   *connection;CS_INT          action;CS_INT          type;CS_VOID         *func;ParametersREMAP="RI--RefIndent"context - A pointer to a CS_CONTEXT structure.   A CS_CONTEXT structure defines a Client-Library application context. REMAP="UN--Under"Either context or connection must be NULL:MARK="DASH" REMAP="BS--BulletSub"If context is supplied, the callback is installed as a "default" callback for the specified context. Once installed, a default callback is inherited by all connections subsequently allocated within the context.If context is NULL, the callback is installed for the individual connection specified by connection. connection - A pointer to a CS_CONNECTION structure. A CS_CONNECTION structure contains information about a particular client/ server connection. REMAP="UN--Under"Either context or connection must be NULL:MARK="DASH" REMAP="BS--BulletSub"If connection is supplied, the callback is installed for the specified connection.If connection is NULL, the callback is installed for the application context specified by context.   action - One of the following symbolic values:TOCENTRY="1"LBL="Table 3-7: "Values for action (MOREINFO="NONE"ct_callback)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"Value of MOREINFO="NONE"action:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ct_callback:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Installs a callback.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_GETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieves the currently-installed callback of this 
type.ID="IN4399757"Callbackstypes of
type - The type of callback routine of interest.   The following table lists the symbolic values that are legal for type:TOCENTRY="1"LBL="Table 3-8: "Values for type (MOREINFO="NONE"ct_callback)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="135*"COLNAME="C2" COLWIDTH="223*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Value of MOREINFO="NONE"type:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_callback installs:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CLIENTMSG_CBCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A client message callback.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_COMPLETION_CBCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A completion callback. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_ENCRYPT_CBCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An encryption callback.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_MESSAGE_CBCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A message callback.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CHALLENGE_CBCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A negotiation callback.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SERVERMSG_CBCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A server message callback.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_NOTIF_CBCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A registered procedure notification callback.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SIGNAL_CB + 
signal_numberCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A signal callback. COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Signal callbacks are identified by adding the 
signal number of interest to the manifest 
constant CS_SIGNAL_CB. For example, to 
install a signal callback for a SIGALRM signal,
pass type as CS_SIGNAL_CB + SIGALRM.func - A pointer variable.REMAP="UN--Under"If a callback routine is being installed, func is the address of the callback routine to install.REMAP="UN--Under"If a callback routine is being retrieved, MOREINFO="NONE"ct_callback sets *func to the address of the currently-installed callback routine.ReturnsTOCENTRY="1"LBL="Table 3-9: "Return values (MOREINFO="NONE"ct_callback)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="106*"COLNAME="C2" COLWIDTH="260*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine completed successfully.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BUSYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An asynchronous operation is already pending for this 
connection. For more information, see the MOREINFO="NONE"Asynchronous 
Programming topics page.CommentsMARK="BULL" REMAP="BU--Bullet"A typical application will use MOREINFO="NONE"ct_callback only to install callback routines. However, some applications may need to retrieve previously-installed callbacks.To install a callback routine, an application calls MOREINFO="NONE"ct_callback with action as CS_SET and func as the address of the callback to install.To retrieve the address of a previously-installed callback, an application calls MOREINFO="NONE"ct_callback with action as CS_GET and func as a pointer to a pointer. In this case, MOREINFO="NONE"ct_callback sets *func to the address of the current callback of the specified type. An application can save this address for re-use at a later time. Note that retrieving the address of a callback does not de-install it.MOREINFO="NONE"ct_callbackID="IN43997510"Callbacksinstalling
can be used to install a callback routine either for a context or for a particular connection. To install a callback for a context, pass connection as NULL. To install a callback for a connection, pass context as NULL.When a context is allocated, it has no callback routines installed. An application must specifically install any callbacks that are required.ID="IN43997511"Callbacksinheriting callback routines from the parent contextWhen a connection is allocated, it picks up default callback routines from its parent context. An application can override these default callbacks by calling MOREINFO="NONE"ct_callback to install new callbacks at the connection level.ID="IN43997512"Callbacksde-installingTo de-install an existing callback routine, an application can call MOREINFO="NONE"ct_callback with func as NULL. An application can also install a new callback routine at any time. The new callback will automatically replace any existing callback.ID="IN43997513"Callbacksinformation can be discardedFor most types of callbacks, if no callback of a particular type is installed for a connection, Client-Library discards callback information of that type. ID="IN432397514"Client message callbackexceptional behaviorREMAP="UN--Under"The client message callback is an exception to this rule. When an error or informational message is generated for a connection that has no client message callback installed, Client-Library calls the connection's parent context's client message callback (if any) rather than discarding the message. If the context has no client message callback installed, then the message is discarded.ID="IN43997515"Callbacksimplications of inheritanceA connection picks up its parent context's callback routines only once, when it is allocated. This has two important implications:MARK="DASH" REMAP="BS--BulletSub"Existing connections are not affected by changes to their parent context's callback routines.If a callback routine of a particular type is de-installed for a connection, the connection does not pick up its parent context's callback routine. Instead, the connection is considered to have no callback routine of this type installed.An application can useID="IN43995716"Callbacksusing CS_USERDATA to transfer information
the CS_USERDATAID="IN432093917"CS_USERDATA propertyusing with callbacks
property to transfer information between a callback routine and the program code that triggered it.   The CS_USERDATA property allows an application to save user data in internal Client-Library space and retrieve it later. For information on how to declare specific types of callback routines, see the MOREINFO="NONE"Callbacks topics page.ID="IN4311911118"ct_callbackcode exampleExampleREMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/*** Install message and completion handlers.*/retstat = ct_callback(Ex_context, NULL, CS_SET,     CS_CLIENTMSG_CB,(CS_VOID *)ex_clientmsg_cb);if (retstat != CS_SUCCEED){     ex_panic("ct_callback failed");}retstat = ct_callback(Ex_context, NULL, CS_SET,     CS_SERVERMSG_CB,(CS_VOID *)ex_servermsg_cb);if (retstat != CS_SUCCEED){     ex_panic("ct_callback failed");}REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"retstat = ct_callback(Ex_context, NULL, CS_SET,    CS_COMPLETION_CB,(CS_VOID *)CompletionCB);if (retstat != CS_SUCCEED){     ex_panic("ct_callback failed");}REMAP="BO--Body"This code excerpt is from the ex_amain.c example program. For further examples of using MOREINFO="NONE"ct_callback, see the ex_alib.c and exutils.c example programs.See AlsoREMAP="BO--Body"LINKEND="X40634"Callbacks
MOREINFO="NONE", LINKEND="X94203"ct_capability
MOREINFO="NONE", LINKEND="X62055"ct_config
MOREINFO="NONE", LINKEND="X57953"ct_con_props
MOREINFO="NONE", LINKEND="X31502"ct_connect
ID="IN4311881421"ct_callback
MOREINFO="NONE"   ID="IN439851722"ct_cancelct_cancelID="IN449851824"Cancelingcommands
ID="IN449851825"Cancelingresults
ID="IN448851826"Commandscanceling
ID="IN447851827"Resultscanceling results
Cancel a command or the results of a command.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_cancel(connection, cmd, type) CS_CONNECTION     *connection;CS_COMMAND        *cmd;CS_INT            type;ParametersREMAP="RI--RefIndent"connection - A pointer to a CS_CONNECTION structure. A CS_CONNECTION structure contains information about a particular client/ server connection.REMAP="UN--Under"For CS_CANCEL_CURRENT cancels, connection must be NULL.REMAP="UN--Under"For CS_CANCEL_ATTN and CS_CANCEL_ALL cancels, one of connection or cmd must be NULL. If connection is supplied and cmd is NULL, the cancel operation applies to all commands pending for this connection.cmd - A pointer to the CS_COMMAND structure managing a client/ server operation. REMAP="UN--Under"For CS_CANCEL_CURRENT cancels, cmd must be supplied. The cancel operation applies only to the results pending for this command structure.REMAP="UN--Under"For CS_CANCEL_ATTN and CS_CANCEL_ALL cancels, if cmd is supplied and connection is NULL, the cancel operation applies only to the command pending for this command structure. If cmd is NULL and connection is supplied, the cancel operation applies to all commands pending for this connection.type - The type of cancel. The following table lists the symbolic values that are legal for typeTOCENTRY="1"LBL="Table 3-10: "Values for type (MOREINFO="NONE"ct_cancel)COLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="125*"COLNAME="C2" COLWIDTH="200*"COLNAME="C3" COLWIDTH="142*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Value of MOREINFO="NONE"type:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Behavior of MOREINFO="NONE"ct_cancel: COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Notes:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CANCEL_ALLCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel sends an attention to the server, 
instructing it to cancel the current command.

Client-Library immediately discards all 
results generated by the command.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Causes this connection's 
cursors to enter an undefined state.

To determine the state of a 
cursor, an application can call 
MOREINFO="NONE"ct_cmd_props with property 
as CS_CUR_STATUS.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CANCEL_ATTNCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel sends an attention to the server, 
instructing it to cancel the current 
command.

The next time the application reads from 
the server, Client-Library discards all 
results generated by the canceled 
command.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Causes this connection's 
cursors to enter an undefined 
state.

To determine the state of a 
cursor, an application can call 
MOREINFO="NONE"ct_cmd_props with property 
as CS_CUR_STATUS.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CANCEL_CURRENTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel discards the current result set.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Safe to use on connections 
with open cursors.ReturnsREMAP="BO--Body"TOCENTRY="1"LBL="Table 3-11: "Return values (MOREINFO="NONE"ct_cancel)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="106*"COLNAME="C2" COLWIDTH="253*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine completed successfully.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_PENDINGCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Asynchronous network I/O is in effect. For more 
information, see the MOREINFO="NONE"Asynchronous Programming topics 
page.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CANCELEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The cancel operation was canceled. Only a 
CS_CANCEL_CURRENT type of cancel can be 
canceled.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BUSYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An asynchronous operation is already pending for this 
connection. For more information, see the 
MOREINFO="NONE"Asynchronous Programming topics page.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRYINGCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A cancel operation is already pending for this 
connection.CommentsMARK="BULL" REMAP="BU--Bullet"Canceling a command is equivalent to sending an attention to the server, instructing it to halt execution of the current command. When a command is canceled, any results generated by it are no longer available to an application.ID="IN4418851832"Discarding results
ID="IN447851833"ResultsdiscardingCanceling results is equivalent to discarding a buffer's worth of results. Once results are canceled, they are no longer available to an application. If the result set has not been completely processed, subsequent results remain available.Canceling a CommandMARK="BULL" REMAP="BU--Bullet"To cancel the current command and all results generated by it, an application calls MOREINFO="NONE"ct_cancel with type as CS_CANCEL_ATTN or CS_CANCEL_ALL. Both of these calls tell Client-Library to:MARK="DASH" REMAP="BS--BulletSub"Send an attention to the server, instructing it to halt execution of the current command.Discard any results already generated by the command.Both types of cancels return CS_SUCCEED immediately, without sending an attention to the server, if no command is in progress. If an application has not yet called MOREINFO="NONE"ct_send to send an initiated command or command batch:MARK="DASH" REMAP="BS--BulletSub"A CS_CANCEL_ALL cancel discards the initiated command or command batch without sending an attention to the server. A CS_CANCEL_ATTN cancel has no effect.A connection can become unusable due to error. If this occurs, Client-Library marks the connection as "dead." An application can use the CS_CON_STATUSID="IN4411851834"Connectionsdetermining if dead
property to determine if a connection has been marked dead.ID="IN4411832035"Connectionsusing ct_cancel to revive a dead connectionREMAP="UN--Under"If a connection has been marked dead because of a results-processing error, an application can try calling MOREINFO="NONE"ct_cancel(CS_CANCEL_ALL or CS_CANCEL_ATTN) to "revive" the connection. If this fails, the application must close the connection and drop its CS_CONNECTION structure.ID="IN4425792436"CS_CANCEL_ALL cancel typedifference from  CS_CANCEL_ATTNThe difference between CS_CANCEL_ALLID="IN4426752837"CS_CANCEL_ATTN cancel typedifference from CS_CANCEL_ALL
and CS_CANCEL_ATTN is:MARK="DASH" REMAP="BS--BulletSub"CS_CANCEL_ALL causes Client-Library to immediately discard the canceled command's results (if any).CS_CANCEL_ATTN causes Client-Library to wait until the application attempts to read from the server before discarding the results.ID="IN447752838"Resultsdiscarding:dangers of discarding results
ID="IN4418752839"Discarding resultsdanger of discarding results
ID="IN449752840"Cancelingresults:danger of discarding resultsREMAP="UN--Under"This difference is important because Client-Library must read from the result stream in order to discard results, and it is not always safe to read from the result stream.REMAP="UN--Under"It is not safe to read from the result stream from within callbacks or interrupt handlers, or when an asynchronous routine is pending. It is safe to read from the result stream anytime an application is running in its main-line code, except when an asynchronous operation is pending.ID="IN4426733041"CS_CANCEL_ATTN cancel typewhen to useREMAP="UN--Under"Use CS_CANCEL_ATTN from within callbacks or interrupt handlers, or when an asynchronous operation is pending.ID="IN4425713242"CS_CANCEL_ALL cancel typewhen to useREMAP="UN--Under"Use CS_CANCEL_ALL in main-line code, except when an asynchronous operation is pending.CS_CANCEL_ALLID="IN4426693443"CS_CANCEL_ATTN cancel typereusing a command structure
leaves the command structure in a "clean" state, available for use in another operation. When a command is canceled with CS_CANCEL_ATTN, however, the command structure cannot be reused until a Client-Library routine returns CS_CANCELED.REMAP="UN--Under"The Client-Library routines that can return CS_CANCELED areMOREINFO="NONE":MARK="DASH" REMAP="BS--BulletSub"MOREINFO="NONE"ct_cancel(CS_CANCEL_CURRENT) MOREINFO="NONE"ct_fetchMOREINFO="NONE" MOREINFO="NONE"ct_get_data MOREINFO="NONE"ct_optionsMOREINFO="NONE" MOREINFO="NONE"ct_recvpassthruMOREINFO="NONE" MOREINFO="NONE"ct_resultsMOREINFO="NONE" MOREINFO="NONE"ct_sendMOREINFO="NONE" MOREINFO="NONE"ct_sendpassthru CS_CANCEL_ATTN has two primary uses:MARK="DASH" REMAP="BS--BulletSub"To cancel commands from within an application's interrupt handlers or callback routines.In asynchronous applications, to cancel pending calls to the result-processing routines MOREINFO="NONE"ct_results and MOREINFO="NONE"ct_fetch.ID="IN4425673644"CS_CANCEL_ALL cancel typewhen not to useCanceling commands on a connection that has an open cursor may affect the state of the cursor in unexpected ways. For this reason, it is recommended that the CS_CANCEL_ALLID="IN4426653845"CS_CANCEL_ATTN cancel typewhen not to use
and CS_CANCEL_ATTN types of cancels not be used on connections with open cursors. Instead of canceling a cursor command, an application can simply close the cursor.Canceling Current ResultsMARK="BULL" REMAP="BU--Bullet"To cancel current results, an application calls MOREINFO="NONE"ct_cancel with typeID="IN4429634046"CS_CANCEL_CURRENT cancel typewhen to use
as CS_CANCEL_CURRENT. This tells Client-Library to discard the current results; it is equivalent to calling MOREINFO="NONE"ct_fetch until it returns CS_END_DATA.The next buffer's worth of results, if any, remains available to the application, and the current command is not affected.ID="IN449634047"Cancelingaffect on bindingCanceling results clears the bindings between the result items and program variables.A CS_CANCEL_CURRENT type of cancel is legal for all types of result sets, even those that contain no fetchable results. If a result set contains no fetchable results, a cancel has no effect.ID="IN449614248"ct_cancelcode exampleExampleREMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"if (query_code == CS_FAIL){    /*    ** Terminate results processing and break out of     ** the results loop.    */    retcode = ct_cancel(NULL, cmd, CS_CANCEL_ALL);    if (retcode != CS_SUCCEED)    {       ex_error("ex_execute_cmd: ct_cancel() failed");    }break;}REMAP="BO--Body"This code excerpt is from the exutils.c example program. For further examples of using MOREINFO="NONE"ct_cancel, see the ex_alib.c, ex_amain.c, and getsend.c example programs.See AlsoREMAP="BO--Body"LINKEND="X65123"ct_fetch
MOREINFO="NONE", LINKEND="X57817"ct_results
ID="IN449584551"ct_cancelID="X94203"ct_capabilityID="IN43129753"Capabilitiessetting and retrieving
Set or retrieve a client/server capability.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_capability(connection, action, type,                capability, value) CS_CONNECTION    *connection;CS_INT           action;CS_INT           type;CS_INT           capability;CS_VOID          *value;ParametersREMAP="RI--RefIndent"connection - A pointer to a CS_CONNECTION structure. A CS_CONNECTION structure contains information about a particular client/ server connection. action - One of the following symbolic values:TOCENTRY="1"LBL="Table 3-12: " ID="X54640"Values for action (MOREINFO="NONE"ct_capability)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"Value of MOREINFO="NONE"action:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ct_capability:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Sets a capability.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_GETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieves a capability.ID="IN43129756"Capabilitiestypes of
type - The type category of the capability. The following table lists the symbolic values that are legal for type: TOCENTRY="1"LBL="Table 3-13: "Values for type (MOREINFO="NONE"ct_capability)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"Value of MOREINFO="NONE"type:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"What it means:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CAP_REQUESTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Request capabilities. COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"These capabilities describe the types of requests 
that a connection can support.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Request capabilities are retrieve-only.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CAP_RESPONSECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Response capabilities.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"These capabilities describe the types of responses 
that a server can send to a connection.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An application can set response capabilities before 
a connection is open and can retrieve response 
capabilities at any time.capability - The capability of interest. The following two tables list the symbolic values that are legal for capability:In addition to the values listed in the tables, capability can have the special value ID="IN43209577"CS_ALL_CAPS constant
CS_ALL_CAPS, to indicate that an application is setting or retrieving all response or request capabilities simultaneously. CS_ALL_CAPS is primarily of use in gateway applications. A typical Client-Library application will only need to set or retrieve a small number of capabilities.CS_CAP_REQUEST CapabilitiesTOCENTRY="1"LBL="Table 3-14: "Request capabilitiesCOLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="184*"COLNAME="C2" COLWIDTH="191*"COLNAME="C3" COLWIDTH="91*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CAP_REQUEST Capability:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Meaning:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Capability
relates to:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CON_INBANDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"In-band (non-expedited) attentions.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ConnectionsCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CON_OOBCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Out-of-band (expedited) attentions.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ConnectionsCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CSR_ABSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetch of specified absolute cursor row.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CursorsCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CSR_FIRSTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetch of first cursor row.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CursorsCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CSR_LASTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetch of last cursor row.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CursorsCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CSR_MULTICOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Multi-row cursor fetch.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CursorsCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CSR_PREVCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetch previous cursor row.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CursorsCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CSR_RELCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Fetch specified relative cursor row.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CursorsCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_BINCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Binary datatype.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_VBINCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Variable-length binary type.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_LBINCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Long binary datatype.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_BITCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Bit datatype.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_BITNCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Nullable bit values.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_BOUNDARYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Secure Server boundary datatypes.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_CHARCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Character datatype.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_VCHARCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Variable-length character datatype.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_LCHARCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Long character datatype.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_DATE4COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Short datetime datatype.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_DATE8COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Datetime datatype.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_DATETIMENCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULL datetime values.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_DECCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Decimal datatype.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_FLT4COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"4-byte float datatype.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_FLT8COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"8-byte float datatype.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_FLTNCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Nullable float values.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_IMAGECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Image datatype.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_INT1COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Tiny integer datatype.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_INT2COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Small integer datatype.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_INT4COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Integer datatype.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_INTNCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULL integers.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_MNY4COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Short money datatype.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_MNY8COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Money datatype.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_MONEYNCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULL money values.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_NUMCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Numeric datatype.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_SENSITIVITYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Secure Server sensitivity datatypes.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_TEXTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Text datatype.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPTION_GETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether the client can get current 
option values from the server.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"OptionsCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_PROTO_BULKCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Tokenized bulk copy.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Bulk copyCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_PROTO_DYNAMICCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Descriptions for prepared statements 
come back at prepare time.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Dynamic SQLCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_PROTO_DYNPROCCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Client-Library prepends SQL to a 
Dynamic SQL prepare statement.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Dynamic SQLCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_REQ_BCPCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Bulk copy requests.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CommandsCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_REQ_CURSORCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Cursor requests.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CommandsCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_REQ_DYNCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Dynamic SQL requests.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CommandsCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_REQ_LANGCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Language requests.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CommandsCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_REQ_MSGCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Message commands.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CommandsCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_REQ_MSTMTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Multiple server commands per Client-
Library language command.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CommandsCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_REQ_NOTIFCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Registered procedure notifications.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CommandsCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_REQ_PARAMCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Use PARAM/PARAMFMT TDS 
streams for requests.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CommandsCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_REQ_URGNOTIFCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Send notifications with the "urgent" bit 
set in the TDS packet header.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Registered 
proceduresCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_REQ_RPCCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Remote procedure requests.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CommandsCS_CAP_RESPONSE CapabilitiesTOCENTRY="1"LBL="Table 3-15: "Response capabilitiesCOLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="184*"COLNAME="C2" COLWIDTH="191*"COLNAME="C3" COLWIDTH="91*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CAP_RESPONSE Capability:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Meaning:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Capability
relates to:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CON_NOINBANDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No in-band (non-expedited) attentions.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ConnectionsCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CON_NOOOBCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No out-of-band (expedited) attentions.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ConnectionsCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_NOBINCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No binary datatype.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_NOVBINCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No variable-length binary type.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_NOLBINCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No long binary datatype.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_NOBITCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No bit datatype.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_NOBOUNDARYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No Secure Server boundary datatypes.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_NOCHARCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No character datatype.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_NOVCHARCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No variable-length character datatype.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_NOLCHARCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No long character datatype.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_NODATE4COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No short datetime datatype.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_NODATE8COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No datetime datatype.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_NODATETIMENCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No NULL datetime values.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_NODECCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No decimal datatype.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_NOFLT4COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No 4-byte float datatype.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_NOFLT8COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No 8-byte float datatype.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_NOIMAGECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No image datatype.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_NOINT1COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No tiny integer datatype.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_NOINT2COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No small integer datatype.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_NOINT4COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No integer datatype.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_NOINT8COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No 8-byte integer datatype.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_NOINTNCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No NULL integers.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_NOMNY4COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No short money datatype.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_NOMNY8COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No money datatype.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_NOMONEYNCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No NULL money values.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_NONUMCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No numeric datatype.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_NOSENSITIVITYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No Secure Server sensitivity datatypes.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATA_NOTEXTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No text datatype.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DatatypesCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_RES_NOEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No extended error results.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ResultsCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_RES_NOMSGCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No message results.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ResultsCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_RES_NOPARAMCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Don't use PARAM/PARAMFMT TDS 
streams for RPC results.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ResultsCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_RES_NOSTRIPBLANKSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The server shouldn't strip blanks when 
returning data from nullable fixed-
length character columns.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ResultsCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_RES_NOTDSDEBUGCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No TDS debug token in response to 
certain MOREINFO="NONE"dbcc commands.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ResultsREMAP="RI--RefIndent"value - If a capability is being set, value points to a CS_BOOL variable that has the value CS_TRUE or CS_FALSE. REMAP="UN--Under"If a capability is being retrieved, value points to a CS_BOOL-sized variable which MOREINFO="NONE"ct_capability sets to CS_TRUE or CS_FALSE.REMAP="UN--Under"CS_TRUE indicates that a capability is enabled. For example, if the CS_RES_NOEED capability is set to CS_TRUE, no extended error data will be returned on the connection.If capability is CS_ALL_CAPS, value must point to a CS_CAP_TYPE structure.ReturnsTOCENTRY="1"LBL="Table 3-16: "Return values (MOREINFO="NONE"ct_capability)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="106*"COLNAME="C2" COLWIDTH="253*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine completed successfully.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BUSYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An asynchronous operation is already pending for this 
connection. For more information, see the 
MOREINFO="NONE"Asynchronous Programming topics page.CommentsMARK="BULL" REMAP="BU--Bullet"Capabilities describe client/server features that a connection supports. There are two types of capabilities: CS_CAP_RESPONSE capabilities, also called "response capabilities," and CS_CAP_REQUEST capabilities, also called "request capabilities."ID="IN431295710"Capabilitiesuses ofMARK="DASH" REMAP="BS--BulletSub"An application uses request capabilities to determine what kinds of requests a server connection supports. For example, an application can retrieve the CS_REQ_CURSOR capability to find out whether a connection supports cursor requests.An application uses response capabilities to prevent the server from sending a type of response that the application cannot process. For example, an application can prevent a server from sending NULL money values by setting the CS_DATA_NOMONEYN response capability to CS_TRUE.ID="IN431295711"Capabilitiesbefore and after opening a connection
ID="IN431295712"CapabilitiesCapabilitiesand connectionsconnections
ID="IN431195713"ConnectionsConnectionsand capabilitiescapabilitiesBefore a connection is open, an application can:MARK="DASH" REMAP="BS--BulletSub"Retrieve request or response capabilities, to determine what request and response features are normally supported at the application's current TDS (Tabular Data Stream) version level. An application's TDS level defaults to a value based on the CS_VERSION level that the application requested in its call to MOREINFO="NONE"ct_init.Set response capabilities, to indicate that a connection does not wish to receive particular types of server responses. Note that an application cannot set request capabilities, which are retrieve-only.After a connection is open, an application can:MARK="DASH" REMAP="BS--BulletSub"Retrieve request capabilities to find out what types of requests the connection will support.Retrieve response capabilities to find out whether the server has agreed to withhold the previously-indicated response types from the connection.ID="IN431295714"Capabilitieshow capabilities are determined
ID="IN431295715"CapabilitiesTDS version level
ID="IN43395716"TDSdetermining capabilitiesCapabilities are determined by a connection's TDS version level. Not all TDS versions support the same capabilities. For example, 4.0 TDS does not support registered procedure notifications or cursor requests. 4.0 TDS does, however, support bulk copy requests, remote procedure call requests, row results, and compute row results. A connection's TDS version level is negotiated during the connection process.If an application sets the CS_TDS_VERSION property, Client-Library overwrites existing capability values with default capability values corresponding to the new TDS version. For this reason, an application should set ID="IN432393917"CS_TDS_VERSION propertyCS_TDS_VERSION propertyand capabilitiescapabilities
CS_TDS_VERSION before setting any capabilities for a connection.REMAP="UN--Under"Because ID="IN4312911118"CapabilitiesCS_TDS_VERSION property
CS_TDS_VERSION is a negotiated login property, the server can change its value at connection time. If this occurs, Client-Library will overwrite existing capability values with default capability values corresponding to the new TDS version.Because capability values can change at connection time, an application must call ID="IN4312891319"CapabilitiesCapabilitiesand ct_capabilityct_capability
MOREINFO="NONE"ct_capability after a connection is open in order to determine what capability values are in effect for the connection.When a connection is closed, Client-Library resets its capability values to values corresponding to the application's default TDS version.ID="IN4312891320"Capabilitiessetting and retrieving multiple capabilitiesSetting and Retrieving Multiple CapabilitiesMARK="BULL" REMAP="BU--Bullet"Gateway applications often need to set or retrieve all capabilities of a type category with a single call to MOREINFO="NONE"ct_capability. To do this, an application calls MOREINFO="NONE"ct_capability with:MARK="DASH" REMAP="BS--BulletSub"type as the type category of interestcapability as CS_ALL_CAPSvalue as a CS_CAP_TYPE structureClient-Library provides the following macros to enable an application to set, clear, and test bits in a CS_CAP_TYPE structure:MARK="DASH" REMAP="BS--BulletSub"ID="IN4312871521"CapabilitiesCS_SET_CAPMASK macro
ID="IN4320851722"CS_SET_CAPMASK macro
MOREINFO="NONE"CS_SET_CAPMASK(mask, capability)ID="IN4312831923"CapabilitiesCS_CLR_CAPMASK macro
ID="IN4320812124"CS_CLR_CAPMASK macro
MOREINFO="NONE"CS_CLR_CAPMASK(mask, capability)ID="IN4312792325"CapabilitiesCS_TST_CAPMASK macro
ID="IN4320772526"CS_TST_CAPMASK macro
MOREINFO="NONE"CS_TST_CAPMASK(mask, capability)REMAP="UN--Under"where mask is a pointer to a CS_CAP_TYPE structure and capability is the capability of interest.See AlsoREMAP="BO--Body"LINKEND="X17423"Capabilities
, LINKEND="X57953"ct_con_props
, LINKEND="X31502"ct_connect
, LINKEND="X61859"ct_options
, LINKEND="X81031"Properties
ID="IN4313742828"ct_capability
ID="IN438713129"ct_closeID="X98839"ct_closeID="IN4427713231"Closing a server connection
ID="IN447713232"Serversclosing a server connection
ID="IN4411713233"Connectionsclosing
Close a server connection.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_close(connection, option) CS_CONNECTION    *connection;CS_INT           option;ParametersREMAP="RI--RefIndent"connection - A pointer to a CS_CONNECTION structure. A CS_CONNECTION structure contains information about a particular client/ server connection. option - The option, if any, to use for the close. The following table lists the symbolic values that are legal for option:TOCENTRY="1"LBL="Table 3-17: "Values for option (MOREINFO="NONE"ct_close)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="106*"COLNAME="C2" COLWIDTH="253*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Value of MOREINFO="NONE"option:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"What it means:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_UNUSEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"(10.0+ servers only)COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Default behavior.
MOREINFO="NONE"
ct_close sends a logout message to the server and 
reads the response to this message before closing the 
connection.

If the connection has results pending, MOREINFO="NONE"ct_close returns 
CS_FAIL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FORCE_CLOSECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The connection is closed whether or not results are 
pending, and without notifying the server.

This option is primarily for use when an application is 
hung waiting for a server response. It is also useful if 
MOREINFO="NONE"ct_results, MOREINFO="NONE"ct_fetch, or MOREINFO="NONE"ct_cancel returns CS_FAIL.ReturnsTOCENTRY="1"LBL="Table 3-18: "Return values (MOREINFO="NONE"ct_close)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="108*"COLNAME="C2" COLWIDTH="252*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine completed successfully.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_PENDINGCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Asynchronous network I/O is in effect. For more 
information, see the MOREINFO="NONE"Asynchronous Programming topics 
page.

If asynchronous network I/O is in effect and MOREINFO="NONE"ct_close 
is called with option as CS_FORCE_CLOSE, it returns 
CS_SUCCEED or CS_FAIL immediately to indicate 
the network response. In this case, no completion 
callback event occurs.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BUSYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An asynchronous operation is already pending for this 
connection. For more information, see the 
MOREINFO="NONE"Asynchronous Programming topics page.

Note that MOREINFO="NONE"ct_close does not return CS_BUSY when 
called with option as CS_FORCE_CLOSE.ID="IN448693437"ct_closecommon reason for failureREMAP="BO--Body"The most common reason for a MOREINFO="NONE"ct_close(CS_UNUSED) failure is pending results on the connection.CommentsID="IN4411693439"Connectionsde-allocating a connectionMARK="BULL" REMAP="BU--Bullet"To de-allocate a CS_CONNECTION, an application can call MOREINFO="NONE"ct_con_drop after the connection has been successfully closed. A connection can become unusable due to error. If this occurs, Client-Library marks the connection as "dead." An application can use the CS_CON_STATUSID="IN4411693440"Connectionsdetermining if dead
property to determine if a connection has been marked dead. ID="IN4411693441"Connectionsforcing a closeREMAP="UN--Under"If a connection has been marked dead, an application must call MOREINFO="NONE"ct_close(CS_FORCE_CLOSEID="IN4411693442"Connectionsclosing
) to close the connection and MOREINFO="NONE"ct_con_drop to drop its CS_CONNECTION structure.REMAP="UN--Under"An exception to this rule occurs for certain types of results-processing errors. If a connection is marked dead while processing results, the application can try calling MOREINFO="NONE"ct_cancel(CS_CANCEL_ALL or CS_CANCEL_ATTNID="IN4411693443"Connectionsreviving a dead connection
) to "revive" the connection. If this fails, the application must close the connection and drop its CS_CONNECTION structure.When a connection is closed, all open cursors on that connection are automatically closed.ID="INB4411693444"Connectionsusing asynchronous network I/OIf the connection is using asynchronous network I/O, MOREINFO="NONE"ct_close returns CS_PENDING. When the server response arrives, Client-Library closes the connection and then calls the completion callback installed for the connection, if any.The behavior of MOREINFO="NONE"ct_close depends on the value of option, which determines the type of close. Each section below contains information on a type of close.ID="IN4411693445"Connectionsdefault close behaviorDefault Close BehaviorMARK="BULL" REMAP="BU--Bullet"If the connection has any pending results, MOREINFO="NONE"ct_close returns CS_FAIL. If the connection has an open cursor, the server closes the cursor when Client-Library closes the connection.When connected to a 10.0+ server, MOREINFO="NONE"ct_close sends a logout message to the server and reads the response to this message before terminating the connection. The contents of this message do not affect MOREINFO="NONE"ct_close's behavior.An application cannot call MOREINFO="NONE"ct_close(CS_UNUSED) when an asynchronous operation is pending.ID="IN4411673646"ConnectionsCS_FORCE_CLOSE behaviorCS_FORCE_CLOSE BehaviorMARK="BULL" REMAP="BU--Bullet"The connection is closed whether or not it has an open cursor or pending results.MOREINFO="NONE"ct_close does not behave asynchronously when called with the CS_FORCE_CLOSE option. When MOREINFO="NONE"ct_close(CS_FORCE_CLOSE) is called to close an asynchronous connection, it returns CS_SUCCEED or CS_FAIL immediately, to indicate the network response. In this case, no completion callback event occurs. ID="IN4421653847"CS_FORCE_CLOSE optionwhen to use
CS_FORCE_CLOSE is useful when:MARK="DASH" REMAP="BS--BulletSub"A connection has been marked as dead.An application is hung, waiting for a server response. An application cannot call MOREINFO="NONE"ct_close(CS_UNUSED) because results are pending. Because no logout message is sent to the server, the server cannot tell whether the close is intentional or whether it is the result of a lost connection or crashed client.An application can call MOREINFO="NONE"ct_close(CS_FORCE_CLOSE) when an asynchronous operation is pending.ID="IN448634048"ct_closecode exampleExampleREMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"CS_RETCODE   retcode;CS_INT       close_option;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"close_option = (status != CS_SUCCEED)? CS_FORCE_CLOSE :    CS_UNUSED;retcode = ct_close(connection, close_option);if (retcode != CS_SUCCEED){    ex_error("ex_con_cleanup: ct_close() failed");    return retcode;}REMAP="BO--Body"This code excerpt is from the exutils.c example program. For another example of using MOREINFO="NONE"ct_close, see the ex_amain.c example program.See AlsoREMAP="BO--Body"LINKEND="X39627"ct_callback
, LINKEND="X21849"ct_con_drop
, LINKEND="X31502"ct_connect
, LINKEND="X57953"ct_con_props
ID="IN448604351"ct_closeID="X88589"ct_cmd_allocID="IN43109573"AllocatingAllocatinga CS_COMMAND structureCS_COMMAND
ID="IN43209394"CS_COMMAND structureallocating
Allocate a CS_COMMANDID="IN43179395"Command structureallocating
structure. REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_cmd_alloc(connection, cmd_pointer) CS_CONNECTION     *connection;CS_COMMAND        **cmd_pointer;ParametersREMAP="RI--RefIndent"connection - A pointer to a CS_CONNECTION structure. A CS_CONNECTION structure contains information about a particular client/ server connection. cmd_pointer - The address of a pointer variable. MOREINFO="NONE"ct_cmd_alloc sets *cmd_pointer to the address of a newly-allocated CS_COMMAND structure. REMAP="UN--Under"In case of error, MOREINFO="NONE"ct_cmd_alloc sets *cmd_pointer to NULL. ReturnsTOCENTRY="1"LBL="Table 3-19: " ID="XA21885"Return values (MOREINFO="NONE"ct_cmd_alloc)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="106*"COLNAME="C2" COLWIDTH="253*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine completed successfully.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BUSYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An asynchronous operation is already pending for this 
connection. For more information, see the 
MOREINFO="NONE"Asynchronous Programming topics page.ID="IN431291119"ct_cmd_allocreason for failureREMAP="BO--Body"The most common reason for a MOREINFO="NONE"ct_cmd_alloc failure is a lack of adequate memory.CommentsID="IN4320891311"CS_COMMAND structuredefinitionMARK="BULL" REMAP="BU--Bullet"A CS_COMMAND structure, also called a "command structure," is a control structure that a Client-Library application uses to send commands to a server and process the results of those commands. ID="IN4312871512"ct_con_allocwhen to useAn application must call MOREINFO="NONE"ct_con_alloc to allocate a connection structure before calling MOREINFO="NONE"ct_cmd_alloc to allocate command structures for the connection.REMAP="UN--Under"However, it is not necessary that the connection structure represent an open connection. (An application opens a connection by calling MOREINFO="NONE"ct_connect to connect to a server.)ID="IN4312851713"ct_cmd_alloccode exampleExampleREMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* Allocate a command handle to send the text with */if ((retcode = ct_cmd_alloc(connection, &cmd)) !=     CS_SUCCEED){     ex_error("UpdateTextData: ct_cmd_alloc() failed");    return retcode;}REMAP="BO--Body"This code excerpt is from the getsend.c example program. For further examples of using MOREINFO="NONE"ct_cmd_alloc, see the compute.c, csr_disp.c, ex_alib.c, exutils.c, i18n.c, and rpc.c example programs.See AlsoREMAP="BO--Body"LINKEND="X39849"ct_command
, LINKEND="X80102"ct_cmd_drop
, LINKEND="X90797"ct_cmd_props
, LINKEND="X20297"ct_con_alloc
, LINKEND="X36007"ct_cursor
, LINKEND="X77746"ct_dynamic
ID="IN4312822016"ct_cmd_alloc
ID="IN4311792317"ct_cmd_dropID="X80102"ct_cmd_dropID="IN4420752819"CS_COMMAND structuredropping;CS_COMMAND structure:de-allocating
De-allocate a CS_COMMANDID="IN4417752820"Command structuredropping
structure. REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_cmd_drop(cmd) CS_COMMAND     *cmd;ParametersREMAP="RI--RefIndent"cmd - A pointer to a CS_COMMAND structure. ReturnsTOCENTRY="1"LBL="Table 3-20: "Return values (MOREINFO="NONE"ct_cmd_drop)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="106*"COLNAME="C2" COLWIDTH="253*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine completed successfully.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BUSYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An asynchronous operation is already pending for this 
connection. For more information, see the 
MOREINFO="NONE"Asynchronous Programming topics page.REMAP="BO--Body"ID="IN4411733024"ct_cmd_dropreasons for failure
MOREINFO="NONE"ct_cmd_drop returns CS_FAIL if:MARK="DASH" REMAP="BS--BulletSub"*cmd has an active command. A command that has been initialized but not yet sent is considered to be active.*cmd has an open cursor.*cmd has pending results.CommentsA CS_COMMAND structure is a control structure that a Client-Library application uses to send commands to a server and process the results of those commands. Once a command structure has been de-allocated, it cannot be re-used. To allocate a new CS_COMMAND structure, an application can call MOREINFO="NONE"ct_cmd_alloc.ID="IN4417733026"Command structurewhat to do before de-allocating a command structureBefore de-allocating a command structure, an application should cancel any active commands, process or cancel any pending results, and close and de-allocate any open cursors on the command structure.ID="IN4411713227"ct_cmd_dropcode exampleExampleREMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"if ((retcode = ct_cmd_drop(cmd)) != CS_SUCCEED){     ex_error("DoCompute: ct_cmd_drop() failed");    return retcode;}REMAP="BO--Body"This code excerpt is from the compute.c example program. For further examples of using MOREINFO="NONE"ct_cmd_drop, see the csr_disp.c, ex_alib.c, exutils.c, and i18n.c example programs.See AlsoREMAP="BO--Body"LINKEND="X39849"ct_command
, LINKEND="X88589"ct_cmd_alloc
ID="IN4411683530"ct_cmd_drop
ID="IN4412653831"ct_cmd_propsID="X90797"ct_cmd_propsID="IN4510653933"Retrievingcommand structure information
ID="IN4517653934"Command structureproperties
ID="IN4510653935"Propertiescommand structure properties
Set or retrieve command structure properties. REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_cmd_props(cmd, action, property, buffer,               buflen, outlen) CS_COMMAND     *cmd;CS_INT         action;CS_INT         property;CS_VOID        *buffer;CS_INT         buflen;CS_INT         *outlen;ParametersREMAP="RI--RefIndent"cmd - A pointer to the CS_COMMAND structure managing a client/ server operation. action - One of the following symbolic values:TOCENTRY="1"LBL="Table 3-21: "Values for action (MOREINFO="NONE"ct_cmd_props)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 action:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ct_cmd_props:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Sets the value of the property.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_GETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieves the value of the property.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CLEARCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Clears the value of the property by resetting it to its 
Client-Library default value.property - The symbolic name of the property whose value is being set or retrieved. The MOREINFO="NONE"Properties topics page lists Client-Library properties.buffer - If a property value is being set, buffer points to the value to use in setting the property. REMAP="UN--Under"If a property value is being retrieved, buffer points to the space in which MOREINFO="NONE"ct_cmd_props will place the requested information. buflen - Generally, buflen is the length, in bytes, of *buffer. REMAP="UN--Under"If a property value is being set and the value in *buffer is null-terminated, pass buflen as CS_NULLTERM.REMAP="UN--Under"If *buffer is a fixed-length or symbolic value, pass buflen as CS_UNUSED.outlen - A pointer to an integer variable. REMAP="UN--Under"outlen is not used if a property value is being set and should be passed as NULL.REMAP="UN--Under"If a property value is being retrieved and outlen is supplied, MOREINFO="NONE"ct_cmd_props sets *outlen to the length, in bytes, of the requested information.REMAP="UN--Under"If the information is larger than buflen bytes, an application can use the value of *outlen to determine how many bytes are needed to hold the information. Summary of ParametersREMAP="BO--Body"For information on action, buffer, buflen, and outlen, see LINKEND="X49197""action, buffer, buflen, and outlen" 
.ReturnsTOCENTRY="1"LBL="Table 3-22: "Return values (MOREINFO="NONE"ct_cmd_props)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="106*"COLNAME="C2" COLWIDTH="253*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine completed successfully.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BUSYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An asynchronous operation is already pending for this 
connection. For more information, see the 
MOREINFO="NONE"Asynchronous Programming topics page.CommentsMARK="BULL" REMAP="BU--Bullet"Command structure properties affect the behavior of an application at the command structure level.ID="IN4512634141"ct_cmd_propswhen to useAll command structures allocated for a connection pick up default property values from the parent connection. An application can override these default values by calling MOREINFO="NONE"ct_cmd_props.REMAP="UN--Under"If an application changes connection property values after allocating command structures for the connection, the existing command structures will not pick up the new property values. New command structures allocated for the connection will use the new property values as defaults.See the MOREINFO="NONE"Properties topics page for more information on properties.An application can use MOREINFO="NONE"ct_cmd_props to set or retrieve the following properties:TOCENTRY="1"LBL="Table 3-23: "Client-Library propertiesCOLS="5" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="93*"COLNAME="C2" COLWIDTH="105*"COLNAME="C3" COLWIDTH="88*"COLNAME="C4" COLWIDTH="85*"COLNAME="C5" COLWIDTH="95*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Property name:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"What it is:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"*buffer is:COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Client-Library 
can set or 
retrieve at what 
level?COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NotesVALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CUR_IDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The cursor's 
identification 
number.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Set to an integer 
value.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Command.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieve only, after 
CS_CUR_STATUS 
indicates an 
existing cursor.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CUR_NAMECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The cursor's name, 
as defined in an 
application's 
MOREINFO="NONE"ct_cursor(CS_CUR
SOR_DECLARE) 
call.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Set to a null-
terminated 
character string.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Command.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieve only, after 
MOREINFO="NONE"ct_cursor(CS_CUR
SOR_DECLARE) 
returns 
CS_SUCCEED.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CUR_
ROWCOUNTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The current value of 
cursor rows. Cursor 
rows is the number 
of rows returned to 
Client-Library per 
internal fetch 
request.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Set to an integer 
value.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Command.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieve only, after 
CS_CUR_STATUS 
indicates an 
existing cursor.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CUR_STATUSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The cursor's status.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Set to a CS_INT-
sized bit-mask.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Command.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieve only. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_HIDDEN_
KEYSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether or not to 
expose hidden keys.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE or 
CS_FALSE.

The default is 
CS_FALSE.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context, 
connection, 
command.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Cannot be set at 
the command 
level if results are 
pending or a 
cursor is open.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_PARENT_
HANDLECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The address of the 
command 
structure's parent 
connection.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Set to an address.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection, 
command.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieve only.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_USERDATACOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"User-allocated data.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"User-allocated 
data.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection, 
command.

To set 
CS_USERDATA 
at the context 
level, call 
MOREINFO="NONE"cs_config.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"None.ID="IN4512614342"ct_cmd_propscode exampleExampleREMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/*** Extract the user area out of the command handle.*/retstat = ct_cmd_props(cmd, CS_GET, CS_USERDATA,    &ex_async, CS_SIZEOF(ex_async), NULL);if (retstat != CS_SUCCEED){   return retstat;}REMAP="BO--Body"This code excerpt is from the ex_alib.c example program. For another example of using MOREINFO="NONE"ct_cmd_props, see the rpc.c example programs.See AlsoREMAP="BO--Body"LINKEND="X62055"ct_config
, LINKEND="X88589"ct_cmd_alloc
, LINKEND="X57953"ct_con_props
, LINKEND="X70623"ct_res_info
ID="IN4512584645"ct_cmd_props
ID="IN4510554946"ct_commandID="X39849"ct_commandID="IN468555048"Commandsinitiating
Initiate a language, package, RPC, message, or send-data command. REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_command(cmd, type, buffer, buflen,               option) CS_COMMAND     *cmd;CS_INT         type;CS_VOID        *buffer;CS_INT         buflen;CS_INT         option;ParametersREMAP="RI--RefIndent"cmd - A pointer to the CS_COMMAND structure managing a client/ server operation. type - The type of command to initiate. The table in the MOREINFO="NONE"Summary of Parameters section lists the symbolic values that are legal for type.buffer - A pointer to data space. buflen - The length, in bytes, of the *buffer data, or CS_UNUSED if *buffer represents a fixed-length or symbolic value.option - The option associated with this command, if any.REMAP="UN--Under"Currently, RPC (remote procedure call), send-data, and send-bulk-data commands take options. For all other types of commands, pass option as CS_UNUSED.REMAP="UN--Under"The following table lists the symbolic values that are legal for option:TOCENTRY="1"LBL="Table 3-24: "Values for option (MOREINFO="NONE"ct_command)COLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="120*"COLNAME="C2" COLWIDTH="115*"COLNAME="C3" COLWIDTH="123*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"type is:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Value of option:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Meaning:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_RPC_CMDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_RECOMPILECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Recompile the stored 
procedure before 
executing it.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_NORECOMPILECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Do not recompile the 
stored procedure before 
executing it.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_UNUSEDCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Equivalent to 
CS_NORECOMPILE.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SEND_DATA_CMDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_COLUMN_DATACOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The data will be used for 
a text or image column 
update.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BULK_DATACOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"For internal Sybase use 
only.
The data will be used for 
a bulk copy operation.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SEND_BULK_CMDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BULK_INITCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"For internal Sybase use 
only. 
Initialize a bulk copy 
operation.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BULK_CONTCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"For internal Sybase use 
only.
Continue a bulk copy 
operation.Summary of ParametersTOCENTRY="1"LBL="Table 3-25: "Summary of parameters (MOREINFO="NONE"ct_command)COLS="4" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="118*"COLNAME="C2" COLWIDTH="102*"COLNAME="C3" COLWIDTH="124*"COLNAME="C4" COLWIDTH="124*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Value of type:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ct_command 
initiates:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"buffer is:COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"buflen is:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_LANG_CMDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A language 
command. COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to the text of 
the language command.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The length of the *buffer 
data or CS_NULLTERM.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_MSG_CMDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A message 
command.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to a 
CS_SMALLINT 
representing the 
message id.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_UNUSEDCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_PACKAGE_CMDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A package 
command.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to the name of 
the package.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The length of the *buffer 
data or CS_NULLTERM.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_RPC_CMDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A remote procedure 
call command. COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to the name of 
the remote procedure.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The length of the *buffer 
data or CS_NULLTERM.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SEND_DATA_CMDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A send-data 
command.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_UNUSEDCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SEND_BULK_CMDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A SYBASE internal 
send-bulk-data 
command. COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to the database 
table name.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The length of the *buffer 
data or CS_NULLTERM.ReturnsTOCENTRY="1"LBL="Table 3-26: "Return values (MOREINFO="NONE"ct_command)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="108*"COLNAME="C2" COLWIDTH="252*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine completed successfully.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BUSYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An asynchronous operation is already pending for this 
connection. For more information, see the 
MOREINFO="NONE"Asynchronous Programming topics page.CommentsMARK="BULL" REMAP="BU--Bullet"Initiating a command is the first step in sending it to a server.ID="IN468555054"Commandssending to a serverSending a command to a server is a four step process. To send a command to a server, an application must: MARK="DASH" REMAP="BS--BulletSub"Initiate the command by calling MOREINFO="NONE"ct_command. This routine sets up internal structures that are used in building a command stream to send to the server. Pass parameters for the command (if required) by calling MOREINFO="NONE"ct_param once for each parameter that the command requires.Not all commands require parameters. For example, a remote procedure call command may or may not require parameters, depending on the stored procedure being called. Send the command to the server by calling MOREINFO="NONE"ct_send.Verify the success of the command by calling MOREINFO="NONE"ct_results.REMAP="UN--Under"This last step does not imply that an application need only call MOREINFO="NONE"ct_results once. An application needs to continue calling MOREINFO="NONE"ct_results until it no longer returns CS_SUCCEED. See the Open Client Client-Library/C Programmer's Guide for a discussion of processing results.An application can call MOREINFO="NONE"ct_cancel with type as CS_CANCEL_ALLID="IN468555055"Commandsclearing an initiated command
to clear a command that has been initiated but not yet sent. ID="IN468535256"Commandsrules for using ct_commandWithin a single connection, the following rules apply to the use of MOREINFO="NONE"ct_command:MARK="DASH" REMAP="BS--BulletSub"After calling MOREINFO="NONE"ct_command to initiate a command, an application must either send the initiated command or clear it before calling MOREINFO="NONE"ct_command a second time. After sending a command initiated via MOREINFO="NONE"ct_command, an application must completely process or cancel all results generated by the command before calling MOREINFO="NONE"ct_command to initiate another command.An application cannot call MOREINFO="NONE"ct_command to initiate a command on a command structure that is managing a cursor.Each section below contains information on one of the types of commands that MOREINFO="NONE"ct_command can initiate.ID="IN4617535257"Language commandsinitiating
ID="IN468535258"Commandslanguage commandsLanguage CommandsMARK="BULL" REMAP="BU--Bullet"Language commands contain a character string that represents one or more commands in a server's own language.   For example, the following language command contains a Transact-SQL command:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"ct_command(cmd, CS_LANG_CMD,           "select * from authors", CS_NULLTERM,          CS_UNUSED);The character string must represent one or more entire server commands. Unlike DB-Library's MOREINFO="NONE"dbcmd routine, MOREINFO="NONE"ct_command does not append text to an internal buffer. If an application calls MOREINFO="NONE"ct_command twice in succession, the second MOREINFO="NONE"ct_command call will fail.ID="IN4621535259"Transact-SQL commandsThe character string can represent more than one server command. For example, the following language command contains three Transact-SQL commands:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"ct_command(cmd, CS_LANG_CMD, "use pubs2 \          select * from titles \          select * from authors ", CS_NULLTERM,          CS_UNUSED);A language command can be in any language, so long as the server to which it is directed can understand it. SQL Server understands Transact-SQL, but an Open Server application constructed with SYBASE Server-Library can be written to understand any language.ID="IN4617535260"Language commandsLanguage commandsand host variableshost variablesIf the language command string contains host variables, an application can pass values for these variable by calling MOREINFO="NONE"ct_param once for each variable that the language string contains. Transact-SQL command variables must begin with a colon (:).ID="IN4616535261"Language cursorswhen regular row result sets are generatedA language cursor generates a regular row result set when an application calls MOREINFO="NONE"ct_command to fetch against the cursor. The fetch command generates regular row results containing a number of rows equal to the current "cursor rows" setting for the cursor.ID="IN4616535262"Message commandsinitiating
ID="IN468535263"Commandsmessage commandsMessage CommandsID="IN4616535264"Message commandspurposeMARK="BULL" REMAP="BU--Bullet"Message commands and results provide a way for clients and servers to communicate specialized information to one another.A message has an "id", which an application provides via MOREINFO="NONE"ct_command's buffer parameter. ID="IN4610535265"Message IDvalid range for user-defined messagesIds for user-defined messages must be greater than or equal to CS_USER_MSGID and less than or equal to CS_USER_MAX_MSGID. If a message requires parameters, the application can call MOREINFO="NONE"ct_param once for each parameter that the message requires.ID="IN468535266"Commandspackage commands
ID="IN4616535267"Package commandsinitiatingPackage CommandsID="IN4616535268"Package commandspurposeMARK="BULL" REMAP="BU--Bullet"A package command instructs an IBM DB/2 database server to execute a package. A package is similar to a remote procedure. It contains precompiled SQL statements that are executed as a unit when the package is invoked.If the package requires parameters, the application can call MOREINFO="NONE"ct_param once for each parameter that the package requires.ID="IN468535269"CommandsRPC commands
ID="IN4622535270"Remote procedure callsinitiatingRPC (remote procedure call) CommandsID="IN4622535271"Remote procedure callspurposeMARK="BULL" REMAP="BU--Bullet"An RPC (remote procedure call) command instructs a server to execute a stored procedure either on this server or a remote server.An application initiates an RPC command by calling MOREINFO="NONE"ct_command with *buffer as the name of the stored procedure to execute.If an application is using an RPC command to execute a stored procedure that requires parameters, the application can call MOREINFO="NONE"ct_param once for each parameter the stored procedure requires.After sending an RPC command with MOREINFO="NONE"ct_sendID="IN4622535272"Remote procedure callsprocessing results
, an application can process the stored procedure's results with MOREINFO="NONE"ct_results and MOREINFO="NONE"ct_fetch. MOREINFO="NONE"ct_results and MOREINFO="NONE"ct_fetch are used to process both the result rows generated by the stored procedure and the return parameters and status from the procedure, if any. An alternative way to call a stored procedure is by executing a language command containing a Transact-SQL MOREINFO="NONE"execute statement. For more information, see the LINKEND="X68029""Remote Procedure Calls"
topics page.ID="IN468535273"Commandssend-data commands
ID="IN4618535274"Send-data commandsinitiatingID="X81429"Send-Data CommandsID="IN4614535275"Text and imagesend-data commandsMARK="BULL" REMAP="BU--Bullet"An application uses a send-data command to write large amounts of text or image data to a server.An application typically calls:MARK="DASH" REMAP="BS--BulletSub"MOREINFO="NONE"ct_command to initiate the send-data command.MOREINFO="NONE"ct_data_info to set the I/O descriptor for the operation.MOREINFO="NONE"ct_send_data to write the value, in chunks, to the data stream.MOREINFO="NONE"ct_send to send the command to the server.For more information on writing text or image values, see the MOREINFO="NONE"Text and Image topics page.ID="IN4623535276"Send-bulk-data commandsinitiating
ID="IN468535277"Commandssend-bulk-data commandsSend-Bulk-Data CommandsMARK="BULL" REMAP="BU--Bullet"Internally, SYBASE uses send-bulk-data commands as part of its implementation of Client-Library's bulk copy routines.ID="IN4610515478"ct_commandcode exampleExampleREMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/*** ex_execute_cmd()**** Type of function:   **      example program utility api**** Purpose:**      Sends a language command to the server. */REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"CS_RETCODE CS_PUBLICex_execute_cmd(connection, cmdbuf)CS_CONNECTION   *connection;CS_CHAR         *cmdbuf;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"{CS_RETCODE      retcode;CS_INT          restype;CS_COMMAND      *cmd;CS_RETCODE      query_code;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/*** Get a command structure,store the command string in it, ** and send it to the server.*/if ((retcode = ct_cmd_alloc(connection, &cmd)) !=    CS_SUCCEED){    ex_error("ex_execute_cmd: ct_cmd_alloc() failed");    return retcode;}REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"if ((retcode = ct_command(cmd, CS_LANG_CMD, cmdbuf,    CS_NULLTERM, CS_UNUSED)) != CS_SUCCEED){    ex_error("ex_execute_cmd: ct_command() failed");   (void)ct_cmd_drop(cmd);   return retcode;}REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* Now send the command and process the results */...CODE DELETED.....}REMAP="BO--Body"This code excerpt is from the exutils.c example program. For further examples of using MOREINFO="NONE"ct_command, see the compute.c, ex_alib.c, getsend.c, i18n.c, and rpc.c example programs.See AlsoREMAP="BO--Body"LINKEND="X88589"ct_cmd_alloc
, LINKEND="X36007"ct_cursor
, LINKEND="X77746"ct_dynamic
, LINKEND="X45322"ct_param
, LINKEND="X69834"ct_send
ID="IN4610485781"ct_commandct_compute_infoID="IN43109753"Retrievingcompute result information
ID="IN43159754"Compute resultsinformation about
Retrieve compute result information. REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_compute_info(cmd, type, colnum, buffer,                buflen, outlen) CS_COMMAND      *cmd;CS_INT          type;CS_INT          colnum;CS_VOID         *buffer;CS_INT          buflen;CS_INT          *outlen;ParametersREMAP="RI--RefIndent"cmd - A pointer to the CS_COMMAND structure managing a client/ server command. type - The type of information to return. For a list of the symbolic values that are legal for type, see the chart in theMOREINFO="NONE" Summary of Parameters section.colnum - The number of the compute column of interest, as it appears in the compute row result set. Compute columns appear in the order in which they are listed in the MOREINFO="NONE"compute clause of a MOREINFO="NONE"select statement. The first column is number 1, the second number 2, and so forth.buffer - A pointer to the space in which MOREINFO="NONE"ct_compute_info will place the requested information. REMAP="UN--Under"If buflen indicates that *buffer is not large enough to hold the requested information, MOREINFO="NONE"ct_compute_info returns CS_FAIL. buflen - The length, in bytes, of the *buffer data space or CS_UNUSED if *buffer represents a fixed-length or symbolic value.outlen - A pointer to an integer variable. REMAP="UN--Under"MOREINFO="NONE"ct_compute_info sets *outlen to the length, in bytes, of the requested information.Summary of ParametersREMAP="BO--Body"TOCENTRY="1"LBL="Table 3-27: "Summary of parameters (MOREINFO="NONE"ct_compute_info)COLS="5" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="99*"COLNAME="C2" COLWIDTH="81*"COLNAME="C3" COLWIDTH="117*"COLNAME="C4" COLWIDTH="88*"COLNAME="C5" COLWIDTH="82*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Value of MOREINFO="NONE"type:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Value of 
MOREINFO="NONE"colnum:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_compute_info 
returns:COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"*MOREINFO="NONE"buffer is set to:COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"*MOREINFO="NONE"outlen is set to:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BYLIST_LENCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_UNUSEDCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The number of 
elements in the bylist 
array.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An integer value.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"sizeof(CS_INT)COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_COMP_BYLISTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_UNUSEDCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An array containing the 
bylist that produced 
this compute row.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An array of 
CS_SMALLINT 
values.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The length of 
the array, in 
bytes.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_COMP_COLIDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The column 
number of the 
compute 
column.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The select-list column 
id of the column from 
which the compute 
column derives.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An integer value.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"sizeof(CS_INT)COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_COMP_IDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_UNUSEDCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The compute id for the 
current compute row.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An integer value.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"sizeof(CS_INT)COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_COMP_OPCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The column 
number of the 
compute 
column.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The aggregate operator 
type for the compute 
column.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A symbolic 
value, one of:
CS_OP_SUM
CS_OP_AVG
CS_OP_COUNT
CS_OP_MIN
CS_OP_MAXCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"sizeof(CS_INT)ReturnsREMAP="BO--Body"TOCENTRY="1"LBL="Table 3-28: "Return values (MOREINFO="NONE"ct_compute_info)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"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine completed successfully.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BUSYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An asynchronous operation is already pending for 
this connection. For more information, see the 
MOREINFO="NONE"Asynchronous Programming topics page.CommentsID="IN431197510"Compute rowdefinitionMARK="BULL" REMAP="BU--Bullet"Compute rows result from the MOREINFO="NONE"compute clause of a MOREINFO="NONE"select statement. A MOREINFO="NONE"compute clause generates a compute row every time the value of its MOREINFO="NONE"by column-list changes. A compute row will contain one column for each aggregate operator in the compute clause. If a MOREINFO="NONE"select statement contains multiple compute clauses, separate compute rows are generated by each clause. ID="INA431295711"Result typesCS_COMPUTE_RESULTREMAP="UN--Under"Each compute row returned by the server is considered to be a distinct result set. That is, each result set of type ID="IN432993912"CS_COMPUTE_RESULT result type
CS_COMPUTE_RESULT will contain exactly one row. ID="IN4315911113"ct_compute_infowhen to callIt is only legal to call MOREINFO="NONE"ct_compute_info when compute information is available; that is, after MOREINFO="NONE"ct_results returns CS_COMPUTE_RESULT or CS_COMPUTEFMT.Each section below contains information about a particular type of compute result information.ID="IN4314911114"Compute clausebylistThe Bylist for a Compute RowMARK="BULL" REMAP="BU--Bullet"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 aggregate operators are applied to each subgroup, generating a compute row for each subgroup. ID="IN4315911115"Compute columnsselect-list idThe Select-List Column ID for a Compute ColumnMARK="BULL" REMAP="BU--Bullet"The select-list column id for a compute column is the select-list id of the column from which the compute column derives.ID="IN4311911116"Compute rowidThe Compute ID for this Compute RowMARK="BULL" REMAP="BU--Bullet"A SQL MOREINFO="NONE"select statement can have multiple compute clauses, each of which returns a separate compute row. The compute id corresponding to the first compute clause in a select statement is 1. ID="IN4315911117"Compute columnsaggregate operatorThe Aggregate Operator for a Particular Compute Row ColumnMARK="BULL" REMAP="BU--Bullet"When called with type as CS_COMP_OP,MOREINFO="NONE" ct_compute_info sets *buffer to one of the following aggregate operator types: TOCENTRY="1"LBL="Table 3-29: "Aggregate operator typesCOLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="120*"COLNAME="C2" COLWIDTH="239*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"*buffer set to:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OP_AVGCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Average aggregate operator. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OP_COUNTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Count aggregate operator. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OP_MAXCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Maximum aggregate operator. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OP_MINCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Minimum aggregate operator. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OP_SUMCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Sum aggregate operator.ID="IN4315891318"ct_compute_infocode examplesExamplesREMAP="BO--Body" 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 NUMERATION="ARABIC" REMAP="S1--StepOne" CONTINUATION="RESTARTS" INHERITNUM="IGNORE"The call:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"CS_INT      mybuffer;REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"ct_compute_info(cmd, CS_BYLIST_LEN, CS_UNUSED,       &mybuffer, CS_UNUSED, CS_UNUSED);REMAP="UN--Under"sets mybuffer to 2, because there are two items in the bylist. The call:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"CS_SMALLINT    mybuffer[2];CS_INT         outlength;REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"ct_compute_info(cmd, CS_COMP_BYLIST, CS_UNUSED,        mybuffer, sizeof(mybuffer), &outlength)REMAP="UN--Under"copies the CS_SMALLINT values 1 and 2 into mybuffer[0] and mybuffer[1] to indicate that the bylist is composed of columns 1 and 2 from the select list.The call:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"CS_INT      mybuffer;REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"ct_compute_info(cmd, CS_COMP_COLID, 1, &mybuffer,       CS_UNUSED,NULL); sets mybuffer to 2, since name is the second column in the select list. The call:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"CS_INT     mybuffer;REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"ct_compute_info(cmd, CS_COMP_ID, CS_UNUSED,        &mybuffer, CS_UNUSED, NULL);sets mybuffer to 1 because there is only a single compute clause in the select statement.The call:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"CS_INT    mybuffer;REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"ct_compute_info(cmd, CS_COMP_OP, 1, &mybuffer,       CS_UNUSED, NULL);sets mybuffer to the symbolic value CS_OP_COUNT, since the aggregate operator for the first compute column is a count. REMAP="BO--Body"For another example of using MOREINFO="NONE"ct_compute_info, see the compute.c example program.See AlsoREMAP="BO--Body"LINKEND="X29013"ct_bind
, LINKEND="X64204"ct_describe
, LINKEND="X70623"ct_res_info
, LINKEND="X57817"ct_results
ID="IN4315861621"ct_compute_info
ID="IN4312831922"ct_con_allocID="X20297"ct_con_allocID="IN4410812224"AllocatingAllocatinga CS_CONNECTION structureCS_CONNECTION structure
ID="IN4423792425"CS_CONNECTION structureallocating
Allocate a CS_CONNECTIONID="IN4420792426"Connection structureallocating
structure. REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_con_alloc(context, con_pointer) CS_CONTEXT      *context;CS_CONNECTION   **con_pointer;ParametersREMAP="RI--RefIndent"context - A pointer to a CS_CONTEXT structure. con_pointer - The address of a pointer variable. MOREINFO="NONE"ct_con_alloc sets *con_pointer to the address of a newly-allocated CS_CONNECTION structure.ReturnsTOCENTRY="1"LBL="Table 3-30: "Return values (MOREINFO="NONE"ct_con_alloc)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="106*"COLNAME="C2" COLWIDTH="253*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine completed successfully.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed.ID="IN4412772630"ct_con_alloccommon reason for failureREMAP="BO--Body"The most common reason for a MOREINFO="NONE"ct_con_alloc failure is a lack of adequate memory.CommentsMARK="BULL" REMAP="BU--Bullet"A CS_CONNECTION structure, also called a "connection structure," contains information about a particular client/server connection.ID="IN4412752832"ct_con_allocwhat to do before calling itBefore calling MOREINFO="NONE"ct_con_alloc, an application must allocate a context structure by calling the CS-Library routine MOREINFO="NONE"cs_ctx_alloc, and must initialize Client-Library by calling MOREINFO="NONE"ct_init.ID="IN4422752833"Connecting to a server
ID="IN446752834"Serverconnecting to a serverConnecting to a server is a three-step process. To connect to a server, an application:MARK="DASH" REMAP="BS--BulletSub"Calls MOREINFO="NONE"ct_con_alloc to allocate a CS_CONNECTION structure. Calls MOREINFO="NONE"ct_con_props to set the values of connection-specific properties, if desired. Calls MOREINFO="NONE"ct_connect to create the connection and log in to the server. An application can have multiple open connections to one or more servers at the same time. REMAP="UN--Under"For example, an application can simultaneously have two connections to the server MARS, one connection to VENUS, and one connection to PLUTO. The context property ID="IN4411733035"ConnectionsConnectionsand CS_MAX_CONNECT propertyCS_MAX_CONNECT property
CS_MAX_CONNECT, set by MOREINFO="NONE"ct_config, determines the maximum number of open connections allowed per context.REMAP="UN--Under"Each server connection requires a separate CS_CONNECTION structure.In order to send commands to a server, one or more command structures must be allocated for a connection. MOREINFO="NONE"ct_cmd_alloc allocates a command structure.ID="IN4412713236"ct_con_alloccode exampleExampleREMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/*** DoConnect()**** Type of function:** async example program api*/CS_STATIC CS_CONNECTION CS_INTERNAL *DoConnect(argc, argv)int      argc;char     **argv;{    CS_CONNECTION   *connection;    CS_INT          netio_type = CS_ASYNC_IO;    CS_RETCODE      retcode;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /* Open a connection to the server */    retcode = ct_con_alloc(Ex_context, &connection);    if (retcode != CS_SUCCEED)    {       ex_panic("ct_con_alloc failed");    }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /* Set properties for the connection */    ...CODE DELETED.....REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /* Open the connection */   ...CODE DELETED.....}REMAP="BO--Body"For further examples of using MOREINFO="NONE"ct_con_alloc, see the blktxt.c, ex_amain.c, and exutils.c example programs.See AlsoREMAP="BO--Body"cs_ctx_alloc, LINKEND="X88589"ct_cmd_alloc
, LINKEND="X98839"ct_close
, LINKEND="X31502"ct_connect
, LINKEND="X57953"ct_con_props
ID="IN4412683539"ct_con_alloc
ID="IN4411653840"ct_con_dropID="X21849"ct_con_dropID="IN4523634142"CS_CONNECTION structuredropping
De-allocate a ID="IN4523614343"CS_CONNECTION structurede-allocating
CS_CONNECTIONID="IN4520614344"Connection structuredropping
structure. REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_con_drop(connection)REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_CONNECTION    *connection;ParametersREMAP="RI--RefIndent"connection - A pointer to a CS_CONNECTION structure. A CS_CONNECTION structure contains information about a particular client/ server connection. ReturnsTOCENTRY="1"LBL="Table 3-31: "Return values (MOREINFO="NONE"ct_con_drop)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="117*"COLNAME="C2" COLWIDTH="243*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine completed successfully.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BUSYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An asynchronous operation is already pending for 
this connection. For more information, see the 
MOREINFO="NONE"Asynchronous Programming topics page.ID="IN4511594548"ct_con_dropcommon reason for failureREMAP="BO--Body"The most common reason for a MOREINFO="NONE"ct_con_drop failure is that the connection is still open. CommentsMARK="BULL" REMAP="BU--Bullet"When a CS_CONNECTION structure is de-allocated, all CS_COMMAND structures associated with it are de-allocated. A CS_CONNECTION structure contains information about a particular client/server connection.Once a CS_CONNECTION has been de-allocated, it cannot be reused. To allocate a new CS_CONNECTION, an application can call MOREINFO="NONE"ct_con_alloc. ID="IN4511574750"ct_con_dropwhat to do before calling itAn application cannot de-allocate a CS_CONNECTION structure until the connection it represents is closed.   To close a connection, an application can call MOREINFO="NONE"ct_close. A connection can become unusable due to error. If this occurs, Client-Library marks the connection as "dead." An application can use the CS_CON_STATUS property to determine if a connection has been marked dead. ID="IN4511554951"ct_con_dropct_con_dropand dead connectionsdead connectionsREMAP="UN--Under"If a connection has been marked dead, an application must call MOREINFO="NONE"ct_close(CS_FORCE_CLOSE) to close the connection and MOREINFO="NONE"ct_con_drop to drop its CS_CONNECTION structure.REMAP="UN--Under"An exception to this rule occurs for certain types of results-processing errors. If a connection is marked dead while processing results, the application can try calling MOREINFO="NONE"ct_cancel(CS_CANCEL_ALL or CS_CANCEL_ATTN) to "revive" the connection. If this fails, the application must close the connection and drop its CS_CONNECTION structure.ID="IN4511535152"ct_con_dropcode exampleExampleREMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* ex_con_cleanup() */REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"CS_RETCODE CS_PUBLICex_con_cleanup(connection, status)CS_CONNECTION                *connection;CS_RETCODE                status;{    CS_RETCODE    retcode;     CS_INT        close_option;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /* Close connection */     ...CODE DELETED.....REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     retcode = ct_con_drop(connection);    if (retcode != CS_SUCCEED)    {        ex_error("ex_con_cleanup: ct_con_drop()             failed");        return retcode;    }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     return retcode;}REMAP="BO--Body"This code excerpt is from the exutils.c example program. For further examples of using MOREINFO="NONE"ct_con_drop, see the blktxt.c and ex_amain.c example programs.See AlsoREMAP="BO--Body"LINKEND="X20297"ct_con_alloc
, LINKEND="X98839"ct_close
, LINKEND="X31502"ct_connect
, LINKEND="X57953"ct_con_props
ID="IN4511505455"ct_con_drop
ID="IN4512475756"ct_con_propsID="X57953"ct_con_propsID="IN4631475858"Connection structure propertiessetting and retrieving
ID="IN4610475859"Propertiesconnection structure properties
Set or retrieve connection structure properties. REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_con_props(connection, action, property,               buffer, buflen, outlen) CS_CONNECTION    *connection;CS_INT           action;CS_INT           property;CS_VOID          *buffer;CS_INT           buflen;CS_INT           *outlen;ParametersREMAP="RI--RefIndent"connection - A pointer to a CS_CONNECTION structure. A CS_CONNECTION structure contains information about a particular client/ server connection.action - One of the following symbolic values:TOCENTRY="1"LBL="Table 3-32: "Values for action (MOREINFO="NONE"ct_con_props)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 action:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_con_props:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Sets the value of the property.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_GETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieves the value of the property.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CLEARCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Clears the value of the property by resetting it to its 
Client-Library default value.property - The symbolic name of the property whose value is being set or retrieved. The MOREINFO="NONE"Properties topics page lists Client-Library properties.buffer - If a property value is being set, buffer points to the value to use in setting the property. buflen - Generally, buflen is the length, in bytes, of *buffer. REMAP="UN--Under"If a property value is being set and the value in *buffer is null-terminated, pass buflen as CS_NULLTERM.REMAP="UN--Under"If *buffer is a fixed-length or symbolic value, pass buflen as CS_UNUSED.outlen - A pointer to an integer variable. REMAP="UN--Under"outlen is not used if a property value is being set and should be passed as NULL.REMAP="UN--Under"If a property value is being retrieved and outlen is supplied, MOREINFO="NONE"ct_con_props sets *outlen to the length, in bytes, of the requested information. REMAP="UN--Under"If the information is larger than buflen bytes, an application can use the value of *outlen to determine how many bytes are needed to hold the information. Summary of ParametersREMAP="BO--Body"For information on action, buffer, buflen, and outlen, see LINKEND="X49197""action, buffer, buflen, and outlen" 
.ReturnsTOCENTRY="1"LBL="Table 3-33: "Return values (MOREINFO="NONE"ct_con_props)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"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine completed successfully.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BUSYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An asynchronous operation is already pending for 
this connection. For more information, see the 
MOREINFO="NONE"Asynchronous Programming topics page.CommentsID="IN4611475865"Connectionsdefining behaviorMARK="BULL" REMAP="BU--Bullet"Connection properties define aspects of Client-Library behavior at the connection level.ID="IN4611475866"Connectionsinheriting parent contextÕ s property valuesAll connections created within a context pick up default property values from the parent context. An application can override these default values by calling MOREINFO="NONE"ct_con_props.REMAP="UN--Under"If an application changes context property values after allocating connections for the context, existing connections will not pick up the new property values. New connections allocated within the context will use the new property values as defaults.All command structures allocated for a connection pick up default property values from the parent connection. An application can override these default values by calling MOREINFO="NONE"ct_cmd_props to set property values at the command structure level. REMAP="UN--Under"If an application changes connection property values after allocating command structures for the connection, the existing command structures will not pick up the new property values. New command structures allocated for the connection will use the new property values as defaults.Some connection properties only take effect if they are set before an application calls MOREINFO="NONE"ct_connect to establish the connection. See the "Notes" column in LINKEND="X64792"Table 3-34: Client-Library connection properties
.See the MOREINFO="NONE"Properties topics page for more information on properties.An application can use MOREINFO="NONE"ct_con_props to set or retrieve the following properties:TOCENTRY="1"LBL="Table 3-34: " ID="X64792"Client-Library connection propertiesCOLS="5" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="112*"COLNAME="C2" COLWIDTH="122*"COLNAME="C3" COLWIDTH="83*"COLNAME="C4" COLWIDTH="67*"COLNAME="C5" COLWIDTH="86*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Property name:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"What it is:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"*buffer is:COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Client-
Library can 
set or 
retrieve at 
what level?COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NotesVALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_ANSI_BINDSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether or not to use 
ANSI-style binds.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE or 
CS_FALSE.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context,
connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_APPNAMECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The application name 
used when logging into 
the server.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A character 
string.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Login property.
Cannot be set 
after connection 
is established.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_ASYNC_
NOTIFSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether a connection 
will receive registered 
procedure notifications 
asynchronously.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE or 
CS_FALSE.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BULK_LOGINCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether or not a 
connection is enabled to 
perform bulk copy "in" 
operations. COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE or 
CS_FALSE.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Login property.
Cannot be set 
after connection 
is established.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CHARSETCNVCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether or not character 
set conversion is taking 
place.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE or 
CS_FALSE.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieve only, 
after connection 
is established.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_COMMBLOCKCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to a 
communication sessions 
block.
This property is specific 
to IBM-370 systems and 
is ignored by all other 
platforms.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer 
value.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Cannot be set 
after connection 
is established.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CON_STATUSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The connection's status.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A CS_INT-sized 
bit-mask.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieve only. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DIAG_TIMEOUTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"When in-line error 
handling is in effect, 
whether Client-Library 
should fail or retry on 
timeout errors.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE or 
CS_FALSE.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DISABLE_POLLCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether or not to 
disable polling. If polling 
is disabled, MOREINFO="NONE"ct_poll does 
not report asynchronous 
operation completions.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE or 
CS_FALSE.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context, 
connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Useful in 
layered 
asynchronous 
applications.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_EED_CMDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to a command 
structure containing 
extended error data.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer 
value.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieve only.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_ENDPOINTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The file descriptor for a 
connection.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An integer 
value, or -1 if 
the platform 
does not 
support 
CS_END
POINTCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieve only, 
after connection 
is established.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_EXPOSE_FMTSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether or not to expose 
results of type 
CS_ROWFMT_RESULT 
and 
CS_COMPUTEFMT_RE
SULT.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE or 
CS_FALSE.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context,
connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Cannot be set 
after connection 
is established.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_EXTRA_INFCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether or not to return 
the extra information 
that's required when 
processing Client-
Library messages in-line 
using a SQLCA, 
SQLCODE, SQLSTATE.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE or 
CS_FALSE.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context,
connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_HIDDEN_KEYSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether or not to expose 
hidden keys.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE or 
CS_FALSE.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context, 
connection, 
command.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_HOSTNAMECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The host machine name.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A character 
string.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Login property.
Cannot be set
after connection 
is established.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_LOC_PROPCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A CS_LOCALE structure 
that defines localization 
information.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A CS_LOCALE 
structure 
previously 
allocated by 
the application.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Login property.
Cannot be set 
after connection 
is established.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_LOGIN_STATUSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether or not the 
connection is open.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE or 
CS_FALSE.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieve only.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_NETIOCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether network I/O is 
synchronous or 
asynchronous.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SYNC_IO, 
CS_ASYNC_IO
.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context,
connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Asynchronous 
connections are 
either fully or 
deferred 
asynchronous, 
to match their 
parent context.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_NOTIF_CMDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to a command 
structure containing 
registered procedure 
notification parameters.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer 
value.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieve only.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_PACKETSIZECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The TDS packet size.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An integer 
value.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Negotiated 
login property.
Cannot be set 
after connection 
is established.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_PARENT_
HANDLECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The address of the 
connection structure's 
parent context.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Set to an 
address.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection,
command.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieve only.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_PASSWORDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The password used to 
log into the server.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A character 
string.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Login property.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SEC_
APPDEFINEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether or not the 
connection will use 
application-defined 
challenge/response 
security handshaking.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE or 
CS_FALSE.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Cannot be set 
after connection 
is established.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SEC_
CHALLENGECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether or not the 
connection will use 
Sybase-defined 
challenge/response 
security handshaking.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE or 
CS_FALSE.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Cannot be set 
after connection 
is established.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SEC_
ENCRYPTIONCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether or not the 
connection will use 
encrypted password 
security handshaking.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE or 
CS_FALSE.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Cannot be set 
after connection 
is established.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SEC_
NEGOTIATECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether or not the 
connection will use 
trusted-user security 
handshaking.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE or 
CS_FALSE.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Cannot be set 
after connection 
is established.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SERVERNAMECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The name of the server 
to which this connection 
is connected.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A string value.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieve only, 
after connection 
is established.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TDS_VERSIONCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The version of the TDS 
protocol that the 
connection is using.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A symbolic 
version level.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Negotiated 
login property.
Cannot be set 
after connection 
is established.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TEXTLIMITCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The largest text or image 
value to be returned on 
this connection.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An integer 
value.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context,
connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRANSACTION_
NAMECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A transaction name.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A string value.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_USERDATACOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"User-allocated data.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"User-allocated 
data.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection,
command.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_USERNAMECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The name used to log 
into the server.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A character 
string.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Login property.
Cannot be set 
after connection 
is established.ID="IN4612456067"ct_con_propscode exampleExampleREMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/*** EstablishConnection()**** Purpose:**  This routine establishes a connection to the server **  identified in example.h and sets the CS_USER,**  CS_PASSWORD, and CS_APPNAME properties for the **  connection.****  NOTE: The username, password, and server are defined**  in the example header file.*/REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"CS_STATIC CS_RETCODEEstablishConnection(context, connection)CS_CONTEXT      *context;CS_CONNECTION   **connection;{    CS_INT      len;    CS_RETCODE  retcode;    CS_BOOL     bool;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /* Allocate a connection structure */    ...CODE DELETED.....REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /*        ** If a username is defined in example.h, set the     ** CS_USERNAME property.    */    if (retcode == CS_SUCCEED && Ex_username != NULL)    {       if ((retcode = ct_con_props(*connection, CS_SET,            CS_USERNAME, Ex_username, CS_NULLTERM, NULL))           != CS_SUCCEED)     {       ex_error("ct_con_props(username) failed");     }   }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /*        ** If a password is defined in example.h, set the     ** CS_PASSWORD property.    */    if (retcode == CS_SUCCEED && Ex_password != NULL)    {       if ((retcode = ct_con_props(*connection, CS_SET,            CS_PASSWORD, Ex_password, CS_NULLTERM, NULL))           != CS_SUCCEED)     {       ex_error("ct_con_props(passwd) failed");       }       }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /* Set the CS_APPNAME property */     ...CODE DELETED.....REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* Enable the bulk login property */     if (retcode == CS_SUCCEED)     {        bool = CS_TRUE;        retcode = ct_con_props(*connection, CS_SET,         CS_BULK_LOGIN, &bool, CS_UNUSED, NULL);    if (retcode != CS_SUCCEED)    {     ex_error("ct_con_props(bulk_login) failed");    }}REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /* Open a server connection */    ...CODE DELETED.....REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"}REMAP="BO--Body"This code excerpt is from the blktxt.c example program. For further examples of using MOREINFO="NONE"ct_con_props, see the ex_alib.c, ex_amain.c, exutils.c, and rpc.c example programs.See AlsoREMAP="BO--Body"LINKEND="X94203"ct_capability
, LINKEND="X90797"ct_cmd_props
, LINKEND="X31502"ct_connect
, LINKEND="X62055"ct_config
, LINKEND="X55618"ct_init
, LINKEND="X81031"PropertiesID="X62055"ct_configID="IN43179754"Global propertiessetting
ID="IN43179755"Global propertiesretrieving
ID="IN43189756"Context properties
ID="IN43149757"Client-Libraryglobal properties
ID="IN43109758"Propertiescontext structure properties
Set or retrieve context properties. REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_config(context, action, property,               buffer, buflen, outlen) CS_CONTEXT     *context;CS_INT         action;CS_INT         property;CS_VOID        *buffer;CS_INT         buflen;CS_INT         *outlen;ParametersREMAP="RI--RefIndent"context ID="IN432095711"CS_CONTEXT structureproperties
- A pointer to a CS_CONTEXT structure. action - One of the following symbolic values:TOCENTRY="1"LBL="Table 3-35: "Values for action (MOREINFO="NONE"ct_config)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 action:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_config:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Sets the value of the property.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_GETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieves the value of the property.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CLEARCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Clears the value of the property by resetting it to its 
Client-Library default value.property - The symbolic name of the property whose value is being set or retrieved. The MOREINFO="NONE"Properties topics page lists Client-Library properties.buffer - If a property value is being set, buffer points to the value to use in setting the property. REMAP="UN--Under"If a property value is being retrieved, buffer points to the space in which MOREINFO="NONE"ct_config will place the requested information. buflen - Generally, buflen is the length, in bytes, of *buffer. REMAP="UN--Under"If a property value is being set and the value in *buffer is null-terminated, pass buflen as CS_NULLTERM.REMAP="UN--Under"If *buffer is a fixed-length value, symbolic value, or function, pass buflen as CS_UNUSED.outlen - A pointer to an integer variable. REMAP="UN--Under"outlen is not used if a property value is being set and should be passed as NULL.REMAP="UN--Under"If a property value is being retrieved and outlen is supplied, MOREINFO="NONE"ct_config sets *outlen to the length, in bytes, of the requested information. REMAP="UN--Under"If the information is larger than buflen bytes, an application can use the value of *outlen to determine how many bytes are needed to hold the information. Summary of ParametersREMAP="BO--Body"For information on action, buffer, buflen, and outlen, see LINKEND="X49197""action, buffer, buflen, and outlen" 
.ReturnsTOCENTRY="1"LBL="Table 3-36: "Return values (MOREINFO="NONE"ct_config)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="106*"COLNAME="C2" COLWIDTH="253*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine completed successfully.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed.CommentsMARK="BULL" REMAP="BU--Bullet"Context properties define aspects of Client-Library behavior at the context level.All connections created within a context pick up default property values from the parent context. An application can override these default values by calling MOREINFO="NONE"ct_con_props to set property values at the connection level. REMAP="UN--Under"If an application changes context property values after allocating connections for the context, existing connections will not pick up the new property values. New connections allocated within the context will use the new property values as defaults.ID="IN431895715"Context propertiestypes of context properties
ID="IN431095716"Propertiestypes of context propertiesThere are actually three kinds of context properties:MARK="DASH" REMAP="BS--BulletSub"Context properties specific to CS-Library.Context properties specific to Client-Library.Context properties specific to Server-Library. REMAP="UN--Under"ID="IN431893917"Context propertiesContext propertiesand cs_configcs_config
MOREINFO="NONE"cs_configID="IN431093918"PropertiesCS-Library-specific context properties
sets and retrieves the values of CS-Library-specific context properties. Properties set via MOREINFO="NONE"cs_config affect only CS-Library. REMAP="UN--Under"ID="IN4318911119"Context propertiesContext propertiesand ct_configct_config
MOREINFO="NONE"ct_configID="IN4310911120"PropertiesClient-Library-specific context properties
sets and retrieves the values of Client-Library-specific context properties. Properties set via MOREINFO="NONE"ct_config affect only Client-Library.REMAP="UN--Under"ID="IN4318891321"Context propertiesContext propertiesand srv_propssrv_props
MOREINFO="NONE"srv_propsID="IN4310891322"PropertiesServer-Library-specific context properties
sets and retrieves the values of Server-Library-specific context properties. Properties set via MOREINFO="NONE"srv_props affect only Server-Library.See the MOREINFO="NONE"Properties topics page for more information on properties.An application can use MOREINFO="NONE"ct_config to set or retrieve the following properties:TOCENTRY="1"LBL="Table 3-37: "Client-Library context propertiesCOLS="5" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="114*"COLNAME="C2" COLWIDTH="122*"COLNAME="C3" COLWIDTH="90*"COLNAME="C4" COLWIDTH="63*"COLNAME="C5" COLWIDTH="75*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Property name:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"What it is:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"*buffer is:COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Client-
Library can 
set or 
retrieve at 
what level?COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NotesVALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_ANSI_BINDSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether or not to use 
ANSI-style binds.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE or 
CS_FALSE.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context,
connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DISABLE_POLLCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether or not to 
disable polling. If 
polling is disabled, 
MOREINFO="NONE"ct_poll does not report 
asynchronous operation 
completions.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE or 
CS_FALSE.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context, 
connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Useful in 
layered 
asynchronous
applications.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_EXPOSE_FMTSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether or not to 
expose results of type 
CS_ROWFMT_RESULT 
and 
CS_COMPUTEFMT_
RESULT.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE or 
CS_FALSE.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context,
connectionCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Takes effect 
only if set 
before 
connection is 
established.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_EXTRA_INFCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether or not to return 
the extra information 
that's required when 
processing Client-
Library messages in-line 
using a SQLCA, 
SQLCODE, or 
SQLSTATE.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE or 
CS_FALSE.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context,
connectionCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_HIDDEN_KEYSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether or not to 
expose hidden keys.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE or 
CS_FALSE.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context, 
connection,
command.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_IFILECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The path and name of 
the interfaces file.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A character 
string.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_LOGIN_
TIMEOUTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The login timeout value.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An integer value.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_MAX_CONNECTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The maximum number 
of connections for this 
context.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An integer value.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_MEM_POOLCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A memory pool that 
Client-Library will use 
to satisfy interrupt-level 
memory requirements.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"If action is 
CS_SET, *buffer is 
a pool of bytes.

If action is 
CS_GET, *buffer is 
set to the address 
of a pool of bytes.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Useful in 
asynchronous
applications.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_NETIOCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether network I/O is 
synchronous, fully 
asynchronous, or 
deferred asynchronous.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SYNC_IO, 
CS_ASYNC_IO, 
or 
CS_DEFER_IO.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context,
connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Cannot be set 
for a context 
with open 
connections.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_NO_TRUNCATECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether Client-Library 
should truncate or 
sequence messages that 
are longer than 
CS_MAX_MSG.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE or 
CS_FALSE.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_NOINTERRUPTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether or not the 
application can be 
interrupted.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE or 
CS_FALSE.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TEXTLIMITCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The largest text or 
image value to be 
returned on this 
connection.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An integer value.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context,
connection.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TIMEOUTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The timeout value.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An integer value.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_USER_ALLOCCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A user-defined memory 
allocation routine.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"If action is 
CS_SET, *buffer is 
the user-defined 
function to 
install.

If action is 
CS_GET, *buffer is 
set to the address 
of the user-
defined function 
that is currently 
installed.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Useful in 
asynchronous
application.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_USER_FREECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A user-defined memory 
free routine.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"If action is 
CS_SET, *buffer is 
the user-defined 
function to 
install.

If action is 
CS_GET, *buffer is 
set to the address 
of the user-
defined function 
that is currently 
installed.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Useful in 
asynchronous
applications.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_VER_STRINGCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Client-Library's true 
version string.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A character 
string.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieve only.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_VERSIONCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The version of Client-
Library in use by this 
context.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A symbolic 
version level.

Currently, the 
only possible 
value is 
CS_VERSION_
100COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Context.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieve only.REMAP="BO--Body"ID="IN439871523"ct_configcode exampleExampleREMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* Set the input/output type to asynchronous */CS_INT        propvalue;if (retcode == CS_SUCCEED){    propvalue = CS_ASYNC_IO;    retcode = ct_config(*context, CS_SET, CS_NETIO,        (CS_VOID *)&propvalue, CS_UNUSED, NULL);   if (retcode != CS_SUCCEED)    {        ex_error("ex_init: ct_config(netio) failed");    }}REMAP="BO--Body"This code excerpt is based on code in the exutils.c example program.See AlsoREMAP="BO--Body"LINKEND="X62055"ct_config
, LINKEND="X90797"ct_cmd_props
, LINKEND="X94203"ct_capability
, LINKEND="X57953"ct_con_props
, LINKEND="X31502"ct_connect
, LINKEND="X55618"ct_init
ID="IN439841826"ct_config
, LINKEND="X81031"Properties
ID="IN4310812127"ct_connectID="X31502"ct_connectID="IN4411812229"Connectionsopening
ID="IN4422812230"Connecting to a server
ID="IN447812231"Serversconnecting to
ID="IN4421812232"Logging into a server
Connect to a server.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_connect(connection, server_name,                 snamelen) CS_CONNECTION    *connection;CS_CHAR          *server_name;CS_INT           snamelen;ParametersREMAP="RI--RefIndent"connection - A pointer to a CS_CONNECTION structure. A CS_CONNECTION structure contains information about a particular client/ server connection. REMAP="UN--Under"Use MOREINFO="NONE"ct_con_alloc to allocate a CS_CONNECTION structure, and MOREINFO="NONE"ct_con_props to initialize this structure with login parameters. server_name ID="IN4415792435"Interfaces fileInterfaces fileand ct_connectct_connect
- A pointer to the name of the server to connect to. *server_name is the name given to the server in the interfaces file on the application's host machine.   MOREINFO="NONE"ct_connect looks up *server_name in the interfaces file to determine how to connect to this server. REMAP="UN--Under"If server_name is NULL, MOREINFO="NONE"ct_connect 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 more information on the interfaces file, see the Open Client/Server Supplement.An interfaces file may not be used on some platforms. For information on whether your platform uses an interfaces file, see the Open Client/Server Supplement for your platform.snamelen - The length, in bytes, of *server_name. If *server_name is null-terminated, pass snamelen as CS_NULLTERM. If server_name is NULL, pass snamelen as 0 or CS_UNUSED.ReturnsTOCENTRY="1"LBL="Table 3-38: "Return values (MOREINFO="NONE"ct_connect)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="106*"COLNAME="C2" COLWIDTH="253*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine completed successfully.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_PENDINGCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Asynchronous network I/O is in effect. For more 
information, see the MOREINFO="NONE"Asynchronous MOREINFO="NONE"Programming topics 
page.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BUSYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An asynchronous operation is already pending for this 
connection. For more information, see the 
MOREINFO="NONE"Asynchronous Programming topics page.ID="IN4410772637"ct_connectreasons for failureREMAP="BO--Body"Common reason for a MOREINFO="NONE"ct_connect failure include:MARK="BULL" REMAP="BU--Bullet"Unable to allocate sufficient memory.The maximum number of connections is already established.MOREINFO="NONE" ct_config is used to set the maximum number of connections allowed per context. Unable to open socket. Server name not found in interfaces file. Unknown host machine name. SQL Server is unavailable or does not exist. Login incorrect. Could not open interfaces file.REMAP="BO--Body"When MOREINFO="NONE"ct_connect returns CS_FAIL, it generates a Client-Library error number that indicates the error. CommentsID="IN4411752839"Connectionsand CS_CONNECTION structureMARK="BULL" REMAP="BU--Bullet"Information about the connection is stored in a CS_CONNECTION structure, which uniquely identifies the connection. In the process of establishing a connection, MOREINFO="NONE"ct_connect sets up communication with the network, logs into the server, and communicates any connection-specific property information to the server. ID="IN4410733040"ct_connectwhat to do before calling itBecause creating a connection involves logging into a server, an application must define login parameters (such as a server user name and password) before calling MOREINFO="NONE"ct_connect. An application can call MOREINFO="NONE"ct_con_propsID="IN4411713241"Connectionsdefining login parameters with ct_con_props
to define login parameters. ID="IN4411713242"Connectionssynchronous or asynchronousA connection can be either synchronous or asynchronous. The Client-Library property ID="IN4417693443"CS_NETIO property
ID="IN4410653844"ct_connectct_connectand CS_NETIO propertyCS_NETIO property
CS_NETIO determines whether a connection will be synchronous or asynchronous.REMAP="UN--Under"For more information on asynchronous connections, see the LINKEND="X80066""Asynchronous Programming"
topics page.ID="IN4411653845"Connectionsmaximum number of connectionsThe maximum number of open connections per context is determined by the ID="IN4423634046"CS_MAX_CONNECT property
ID="IN4410594447"ct_connectct_connectand CS_MAX_CONNECT propertyCS_MAX_CONNECT property
CS_MAX_CONNECT property (set by MOREINFO="NONE"ct_config). If not explicitly set, the maximum number of connections defaults to a platform-specific value. For information on platform-specific property values, see the Open Client/Server Supplement.ID="IN4411594448"Connectionsfailure to connectWhen a connection attempt is made between a client and a server, there are two ways in which the process 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 that the server is supposed to be on will signal the client, via a network error, that the connection can't be formed. Regardless of the login timeout value, 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 a login timeout period has been set, a timeout error will occur when the client fails to receive a response within the set period. To close a connection, an application calls MOREINFO="NONE"ct_close. ID="IN447594449"Serversbackup:connecting to
ID="IN4417594450"Alternate serversconnecting to
ID="IN4414594451"Backup serversconnecting toMultiple QUERY Entries in an Interfaces File MARK="BULL" REMAP="BU--Bullet" It is possible to set up an interfaces file so that if MOREINFO="NONE"ct_connect 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"ct_connect call:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"ct_connect(connection, "MARS", CS_NULLTERM)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="UN--Under"The application is directed to port number 1025 on the machine violet. If MARS is not available, the MOREINFO="NONE"ct_connect call fails. If the interfaces file has multiple query entries in it for MARS, however, then when the first connection attempt fails, MOREINFO="NONE"ct_connect 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="UN--Under"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. REMAP="UN--Under"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. REMAP="UN--Under"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="UN--Under"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"ct_connect 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"ct_connect will try to connect to each query entry only once. REMAP="UN--Under"Looping through the list and pausing between loops is useful in case any of the candidate servers is in the process of booting. REMAP="UN--Under"Multiple query lines can be particularly useful when alternate servers contain mirrored copies of the primary server's databases. ID="IN4410574652"ct_connectcode example ExampleREMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* ex_connect() */REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"CS_RETCODE CS_PUBLICex_connect(context, connection, appname,username, password,    server)CS_CONTEXT       *context;CS_CONNECTION    **connection;CS_CHAR          *appname;CS_CHAR          *username;CS_CHAR          *password;CS_CHAR          *server;{   CS_INT        len;   CS_RETCODE    retcode;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /* Allocate a connection structure */    ...CODE DELETED.....REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /* Set properties for new connection */    ...CODE DELETED.....REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /* Open the connection */    if (retcode == CS_SUCCEED)    {       len = (server == NULL) ? 0 : CS_NULLTERM;        retcode = ct_connect(*connection, server, len);       if (retcode != CS_SUCCEED)       {           ex_error("ct_connect failed");       }    }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    if (retcode != CS_SUCCEED)    {        ct_con_drop(*connection);       *connection = NULL;   }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    return retcode;}REMAP="BO--Body"This code excerpt is from the exutils.c example program. For further examples of using MOREINFO="NONE"ct_connect, see the blktxt.c and ex_amain.c example programs.See AlsoREMAP="BO--Body"LINKEND="X98839"ct_close
, LINKEND="X20297"ct_con_alloc
, LINKEND="X21849"ct_con_drop
, LINKEND="X57953"ct_con_props
, LINKEND="X33916"ct_remote_pwd
ID="IN4410544955"ct_connect
ID="IN449515256"ct_cursorID="X36007"ct_cursorID="IN4522515358"Client-Library cursorsinitiating a command
ID="IN457515359"Cursorsinitiating a Client-Library cursor command
ID="IN4530515360"Client-Library cursor commandsinitiating
Initiate a Client-Library cursor command.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_cursor(cmd, type, name, namelen, text, textlen, option)CS_COMMAND         *cmd;CS_INT             type;CS_CHAR            *name;CS_INT             namelen;CS_CHAR            *text;CS_INT             textlen;CS_INT             option;ParametersREMAP="RI--RefIndent"cmd - A pointer to the CS_COMMAND structure managing a client/ server operation.type - The type of cursor command to initiate. The chart in the MOREINFO="NONE"Summary of Parameters section lists the symbolic values that are legal for type.name - A pointer to the name associated with the cursor command, if any. The chart in the MOREINFO="NONE"Summary of Parameters section indicates which types of commands require names.namelen - The length, in bytes, of *name. If *name is null-terminated, pass namelen as CS_NULLTERM. If name is NULL pass namelen as CS_UNUSED. text - A pointer to the text associated with the cursor command, if any. The chart in the MOREINFO="NONE"Summary of Parameters section indicates which commands require text and what that text must be.textlen - The length, in bytes, of *text. If *text is null-terminated, pass textlen as CS_NULLTERM. If text is NULL, pass textlen as CS_UNUSED.option - The option associated with this command, if any. The chart in the MOREINFO="NONE"Summary of Parameters section indicates which commands take an option and what that option can be.Summary of ParametersTOCENTRY="1"LBL="Table 3-39: "Summary of parameters (MOREINFO="NONE"ct_cursor)COLS="5" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="126*"COLNAME="C2" COLWIDTH="80*"COLNAME="C3" COLWIDTH="68*"COLNAME="C4" COLWIDTH="68*"COLNAME="C5" COLWIDTH="133*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Value of MOREINFO="NONE"type:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ct_cursor 
initiates:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"name is:COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"*MOREINFO="NONE"text is:COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"option is:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CURSOR_CLOSECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A cursor close 
command. COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DEALLOC to close and 
de-allocate the cursor.

CS_UNUSED to close the 
cursor without de-
allocating it.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CURSOR_DEALLOCCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A de-allocate 
cursor 
command.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_UNUSEDCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CURSOR_DECLARECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A cursor 
declare 
command. COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to 
the cursor 
name.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to 
the SQL text 
that is the 
body of the 
cursor.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FOR_UPDATE to 
indicate that the cursor is 
for update.

CS_READ_ONLY to 
indicate that the cursor is 
read-only. 

CS_UNUSED. The 
meaning of CS_UNUSED 
is server-defined.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CURSOR_DELETECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A cursor 
delete 
command.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to 
the name of 
the table to 
delete from.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_UNUSEDCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CURSOR_OPENCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A cursor open 
command. COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_UNUSEDCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CURSOR_OPTIONCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A cursor set 
options 
command.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FOR_UPDATE to 
indicate that th

CS_READ_ONLY to 
indicate that the cursor is 
read-only. 

CS_UNUSED. The 
meaning of CS_UNUSED 
is server-defined.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CURSOR_ROWSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A cursor set 
rows 
command. COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An integer representing the 
number of rows to be 
returned with a single fetch 
request.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CURSOR_UPDATECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A cursor 
update 
command. COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to 
the name of 
the table to 
update.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to 
the SQL 
update 
statement.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_UNUSEDReturnsTOCENTRY="1"LBL="Table 3-40: "Return values (MOREINFO="NONE"ct_cursor)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="106*"COLNAME="C2" COLWIDTH="253*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine completed successfully.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BUSYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An asynchronous operation is already pending for this 
connection. For more information, see the 
MOREINFO="NONE"Asynchronous Programming topics page.CommentsMARK="BULL" REMAP="BU--Bullet"Initiating a command is the first step in sending it to a server. Client-Library cursor commands include commands to declare, open, set cursor rows, close, and de-allocate a cursor as well as commands to update and delete rows in an underlying table.ID="IN457515367"Cursorssending a Client-Library cursor command to a server
ID="IN4530515368"Client-Library cursor commandssending to a serverSending a command to a server is a four step process. To send a command to a server, an application must: MARK="DASH" REMAP="BS--BulletSub"Initiate the command by calling MOREINFO="NONE"ct_cursor. This sets up internal structures that are used in building a command stream to send to the server.Pass parameters for the command (if required) by calling MOREINFO="NONE"ct_param once for each parameter that the command requires.Not all commands require parameters. See the LINKEND="X99106""Client-Library Cursor Declare"
section for an explanation of when to call MOREINFO="NONE"ct_param.Send the command to the server by calling MOREINFO="NONE"ct_send.Verify the success of the command by calling MOREINFO="NONE"ct_results.REMAP="UN--Under"This last step does not imply that an application need only call MOREINFO="NONE"ct_results once. If the value of MOREINFO="NONE"ct_results' result_type parameter indicates that there are fetchable results, the application will most likely process the results using a loop controlled by MOREINFO="NONE"ct_results. See the Open Client Client-Library/C Programmer's Guide for a discussion of processing results.Batching Client-Library Cursor CommandsID="IN457515369"Cursorsbatching Client-Library cursor commandsMARK="BULL" REMAP="BU--Bullet"An application can "batch" together commands to achieve reduced network traffic and improved application performance.REMAP="UN--Under"To batch together commands to declare, set rows for, and open a Client-Library cursor, the application:MARK="DASH" REMAP="BS--BulletSub"Calls MOREINFO="NONE"ct_cursor to declare the cursor.Calls MOREINFO="NONE"ct_param (if necessary) to define the format(s) of host variable(s).Calls MOREINFO="NONE"ct_cursor (optional) to set rows for the cursor.Calls MOREINFO="NONE"ct_cursor to open the cursor.Calls MOREINFO="NONE"ct_param (if necessary) to supply value(s) for the host variable(s).Calls MOREINFO="NONE"ct_send to send the command batch to the server.REMAP="UN--Under"The sequence of calls is:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"    ct_cursor(CS_CURSOR_DECLARE)    ct_param    ct_cursor(CS_CURSOR_ROWS)    ct_cursor(CS_CURSOR_OPEN)    ct_param    ct_sendREMAP="UN--Under"Commands must be batched in the logical order: declare, set cursor rows, open.ID="IN457515370"CursorsClient-Library cursor close commandClient-Library Cursor CloseMARK="BULL" REMAP="BU--Bullet"A MOREINFO="NONE"ct_cursor(CS_CURSOR_CLOSE) command throws away the cursor result set that was generated when the cursor was opened.An application can re-open a closed cursor.ID="IN457515371"CursorsClient-Library cursor de-allocate commandClient-Library Cursor De-allocateMARK="BULL" REMAP="BU--Bullet"A MOREINFO="NONE"ct_cursor(CS_CURSOR_DEALLOC) command de-allocates a Client-Library cursor. If a cursor has been de-allocated, it cannot be re-opened.An application cannot de-allocate an open cursor.To initiate a command to both close and de-allocate a Client-Library cursor, call MOREINFO="NONE"ct_cursor with type as CS_CURSOR_CLOSE and option as CS_DEALLOC.ID="IN457515372"CursorsClient-Library cursor declare commandID="X99106"Client-Library Cursor DeclareMARK="BULL" REMAP="BU--Bullet"Declaring a Client-Library cursor is equivalent to associating the cursor name with a SQL statement. This SQL statement is called the body of the cursor.REMAP="UN--Under"The SQL statement associated with a cursor can be a command to execute a stored procedure. For example:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"    ct_cursor (cmd, CS_CURSOR_DECLARE, "mycursor",        CS_NULLTERM, "execute my_proc",        CS_NULLTERM,CS_UNUSED);REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"    ct_send(cmd);REMAP="UN--Under"In this case, the body of the cursor is the text that makes up the stored procedure.The SQL statement associated with a cursor can contain host variables. If it does, an application must define the variables' formats for the server by calling MOREINFO="NONE"ct_param at cursor declare time, once for each variable.Defining a variable's format is not the same thing as supplying a value for the variable. An application supplies values for host variables at cursor open time.REMAP="UN--Under"Skip this step if the SQL statement is a stored procedure or a dynamic SQL statement, but supply values for a stored procedure's input parameter(s) or a dynamic SQL statement's placeholder(s) at cursor open time.ID="IN457495573"Cursorsread-only Client-Library cursorsTo declare a cursor as 'read-only', an application specifies option as CS_READ_ONLY. This means that the cursor cannot be used to change values in the underlying server tables.ID="IN457475774"Cursorsfor update Client-Library cursorsTo declare a cursor 'for update', an application specifies option as CS_FOR_UPDATE. This means that the cursor can be used to change values in the underlying server tables.REMAP="UN--Under"If some but not all of a cursor's columns are for update, an application must indicate which columns are for update by calling MOREINFO="NONE"ct_paramID="IN457475775"Cursorsupdate columns
once for each update column. If all of a cursor's columns are for update, an application does not have to call MOREINFO="NONE"ct_param to identify update columns.REMAP="UN--Under"For example, to indicate that the au_id and au_lname columns are for update:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"    ct_cursor(cmd, CS_CURSOR_DECLARE, "au_cursor",        CS_NULLTERM, "select * from authors"        CS_NULLTERM, CS_FOR_UPDATE);REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"    format.status = CS_UPDATECOL;REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"    ct_param(cmd, &format, "au_id", CS_NULLTERM,        CS_UNUSED);REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"    format.status = CS_UPDATECOL;REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"    ct_param(cmd, &format, "au_lname", CS_NULLTERM,        CS_UNUSED);REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"    ct_send(cmd);REMAP="UN--Under"To indicate that all columns returned by a cursor are for update:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"    ct_cursor(cmd, CS_CURSOR_DECLARE, "au_cursor",            CS_NULLTERM, "select * from authors"            CS_NULLTERM, CS_FOR_UPDATE);REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"    ct_send(cmd);ID="IN457475776"CursorsClient-Library cursor delete commandClient-Library Cursor DeleteMARK="BULL" REMAP="BU--Bullet"A MOREINFO="NONE"ct_cursor(CS_CURSOR_DELETE) command deletes the current cursor row from the cursor result set. The delete is propagated back to the underlying server tables.ID="IN457475777"CursorsClient-Library cursor open commandClient-Library Cursor OpenMARK="BULL" REMAP="BU--Bullet"A MOREINFO="NONE"ct_cursor(CS_CURSOR_OPEN) command executes the body of a Client-Library cursor, generating a CS_CURSOR_RESULT result set. To access the cursor rows, an application processes the cursor result set by calling MOREINFO="NONE"ct_results, MOREINFO="NONE"ct_bind, and MOREINFO="NONE"ct_fetch.ID="IN457475778"Cursorspassing input parameter valuesSome cursors require input parameter values at cursor open time. An application can pass input parameter values for a cursor open command by calling MOREINFO="NONE"ct_param after calling MOREINFO="NONE"ct_cursor. A cursor open command requires parameters if any of the following are true:MARK="DASH" REMAP="BS--BulletSub"The body of the cursor is a SQL statement that contains host variables.The body of the cursor is a stored procedure that requires input parameter values.The body of the cursor is a dynamic SQL statement that contains dynamic parameter markers.To open a cursor on a dynamic SQL prepared statement, specify the same command structure used to dynamically declare the cursor (MOREINFO="NONE"ct_dynamic(CS_CURSOR_DECLARE)).ID="IN457475779"CursorsClient-Library cursor rows command
ID="IN457475780"CursorsoptionsID="X11788"Dynamic SQL Cursor OptionMARK="BULL" REMAP="BU--Bullet"A MOREINFO="NONE"ct_cursor(CS_CURSOR_OPTION) command sets Client-Library cursor options ('read-only' or 'for update') for dynamic SQL prepared statements.REMAP="UN--Under"Applications that declare a cursor on a dynamically prepared SQL statement (MOREINFO="NONE"ct_dynamic(CS_CURSOR_DECLARE)) must follow the cursor declaration with a call to MOREINFO="NONE"ct_cursor(CS_CURSOR_OPTION). Unlike a Client-Library cursor declare command, the dynamic SQL cursor declare command does not provide a way to specify cursor options.REMAP="UN--Under"A dynamic SQL application declares a cursor on a prepared SQL statement to make use of Client-Library cursor functionality. Once an application calls MOREINFO="NONE"ct_dynamic(CS_CURSOR_DECLARE), it makes MOREINFO="NONE"ct_cursor calls from that point onwards, beginning with MOREINFO="NONE"ct_cursor(CS_CURSOR_OPTION).REMAP="UN--Under"An application that uses MOREINFO="NONE"ct_cursor to declare a cursor does not need to use the cursor option command because the cursor declare command (MOREINFO="NONE"ct_cursor(CS_CURSOR_DECLARE)) provides a way to specify cursor options (via the option parameter). However, it is not illegal to follow a cursor declare command with a cursor option command; the newly-specified option simply replaces the option that was originally specified.To declare a cursor as 'read-only', an application specifies option as CS_READ_ONLY. This means that the cursor cannot be used to change values in the underlying server tables.To declare a cursor 'for update', an application specifies option as CS_FOR_UPDATE. This means that the cursor can be used to change values in the underlying server tables.REMAP="UN--Under"If some but not all of a cursor's columns are for update, an application must indicate which columns are for update by calling MOREINFO="NONE"ct_param once for each update column. If all of a cursor's columns are for update, an application does not have to call MOREINFO="NONE"ct_param to identify update columns.An application can only specify cursor options before opening a cursor.ID="IN457475781"CursorsClient-Library cursor rows commandID="XA11788"Client-Library Cursor RowsMARK="BULL" REMAP="BU--Bullet"A MOREINFO="NONE"ct_cursor(ID="IN457475782"Cursorscursor rows setting
CS_CURSOR_ROWS) command specifies the number of rows that the server returns to Client-Library per internal fetch request. Note that this is not the number of rows returned to an application per MOREINFO="NONE"ct_fetch call. The number of rows returned to an application per MOREINFO="NONE"ct_fetch call is determined by the value of the count field in the CS_DATAFMT structures used in binding the cursor result columns.An application can only set cursor rows before opening a cursor.The cursor rows setting defaults to one row.ID="IN457475783"CursorsClient-Library cursor update commandClient-Library Cursor UpdateMARK="BULL" REMAP="BU--Bullet"A MOREINFO="NONE"ct_cursor(CS_CURSOR_UPDATEID="IN456475784"Cursorupdating
) command defines new column values for the current cursor row. These new values are used to update an underlying table.When updating a SQL Server table, an application must specify the name of the table to update twice: once as the value of MOREINFO="NONE"ct_cursor's *name parameter and a second time in the update statement itself (MOREINFO="NONE"update tablename...).An application can update only a single table.ID="IN459455985"ct_cursorcode exampleExampleREMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* DoCursor(connection) */REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"CS_STATIC CS_RETCODEDoCursor(connection)CS_CONNECTION  *connection;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"{    CS_RETCODE            retcode;    CS_COMMAND            *cmd;    CS_INT            res_type;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /* Use the pubs2 database */    ...CODE DELETED.....REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /*    ** Allocate a command handle to declare the     ** cursor on.    */    retcode = ct_cmd_alloc(connection, &cmd)    if (retcode != CS_SUCCEED)   {        ex_error("DoCursor: ct_cmd_alloc() failed");         return retcode;     }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /*    ** Declare the cursor. SELECT is a MOREINFO="NONE"select     ** statement defined in the header file.    */     retcode = ct_cursor(cmd, CS_CURSOR_DECLARE,         "cursor_a", CS_NULLTERM, SELECT, CS_NULLTERM,         CS_READ_ONLY);    if (retcode != CS_SUCCEED)    {        ex_error("DoCursor: ct_cursor(declare)              failed");        return retcode;    }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /* Set cursor rows to 10*/    retcode = ct_cursor(cmd, CS_CURSOR_ROWS, NULL,         CS_UNUSED, NULL, CS_UNUSED, (CS_INT)10);    if (retcode != CS_SUCCEED)     {         ex_error("DoCursor: ct_cursor(currows)            failed");         return retcode;     }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /* Open the cursor */    retcode = ct_cursor(cmd, CS_CURSOR_OPEN, NULL,         CS_UNUSED, NULL,     CS_UNUSED, CS_UNUSED);    if (retcode != CS_SUCCEED)    {        ex_error("DoCursor: ct_cursor() failed");        return retcode;    }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /*    ** Send (batch) the last 3 cursor commands to     ** the server     */    retcode = ct_send(cmd)    if (retcode != CS_SUCCEED)    {        ex_error("DoCursor: ct_send() failed");         return retcode;     }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /*    ** Process the results.  Loop while ct_results()     ** returns CS_SUCCEED, and then check ct_result's     ** final return code to see if everything went ok.    */    ...CODE DELETED.....REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /*    ** Close and deallocate the cursor. Note that we     ** don't have to do this, since it is done    ** automatically when the connection is closed.    */    retcode = ct_cursor(cmd, CS_CURSOR_CLOSE, NULL,         CS_UNUSED, NULL, CS_UNUSED, CS_DEALLOC);    if (retcode != CS_SUCCEED)    {        ex_error("DoCursor: ct_cursor(dealloc)             failed");        return retcode;    }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /* Send the cursor command to the server */    retcode = ct_send(cmd)    if (retcode != CS_SUCCEED)     {        ex_error("DoCursor: ct_send() failed");        return retcode;    }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /*    ** Check its results.  The command won't generate     ** fetchable results.    */    ...CODE DELETED.....REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /* Drop the cursor's command structure */    ...CODE DELETED.....REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    return retcode;}REMAP="BO--Body"This code excerpt is from the csr_disp.c example program.See AlsoREMAP="BO--Body"LINKEND="X50078"Cursors
, LINKEND="X88589"ct_cmd_alloc
, LINKEND="X50050"ct_keydata
, LINKEND="X45322"ct_param
, LINKEND="X57817"ct_results
, LINKEND="X69834"ct_send
ID="IN459426288"ct_cursorID="X75519"ct_data_infoID="IN43209753"Descriptor structuredefining and retrieving
ID="IN43249754"I/O descriptor structuredefining and retrieving
Define or retrieve a data I/O descriptor structure.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_data_info(cmd, action, colnum, iodesc) CS_COMMAND    *cmd;CS_INT        action;CS_INT        colnum;CS_IODESC     *iodesc;ParametersREMAP="RI--RefIndent"cmd - A pointer to the CS_COMMAND structure managing a client/ server operation. action - One of the following symbolic values:TOCENTRY="1"LBL="Table 3-41: "Values for action (MOREINFO="NONE"ct_data_info)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 action:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ct_data_info:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Defines an I/O descriptor. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_GETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieves an I/O descriptor.colnum - The number of the text or image column whose I/O descriptor is being retrieved. REMAP="UN--Under"If action is CS_SET, pass colnum as CS_UNUSED.REMAP="UN--Under"If action is CS_GET, colnum refers to the select-list id of the text or image column. The first column in a MOREINFO="NONE"select statement's select-list is column number 1, the second number 2, and so forth. An application must select a text or image column before it can update the column.REMAP="UN--Under"colnum must represent a text or image column.iodesc - A pointer to a CS_IODESC structure. A CS_IODESC structure contains information describing text or image data. For more information on this structure, see LINKEND="X66404""CS_IODESC Structure" 
.ReturnsTOCENTRY="1"LBL="Table 3-42: "Return values (MOREINFO="NONE"ct_data_info)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="106*"COLNAME="C2" COLWIDTH="253*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine completed successfully.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BUSYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An asynchronous operation is already pending for this 
connection. For more information, see the 
MOREINFO="NONE"Asynchronous Programming topics page.CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"ct_data_infoID="IN43199579"CS_IODESC structure
defines or retrieves a CS_IODESCID="IN431493910"Text and imageText and imageand CS_IODESC structureCS_IODESC structure
, also called an "I/O descriptor structure," for a text or image column. An application calls MOREINFO="NONE"ct_data_info to retrieve an I/O descriptor after calling MOREINFO="NONE"ct_get_data to retrieve a text or image column value that it plans to update at a later time. This I/O descriptor contains the text pointer and text timestamp that the server uses to manage updates to text or image columns.ID="IN432493911"I/O descriptor structurehow to useREMAP="UN--Under"After retrieving an I/O descriptor, a typical application changes only the values of the locale, total_txtlen, and log_on_update fields before using the I/O descriptor in an update operation:MARK="DASH" REMAP="BS--BulletSub"The total_txtlen field of the CS_IODESC represents the total length, in bytes, of the new text or image value.The MOREINFO="NONE"log_on_update field in the CS_IODESC to indicate whether or not the server should log the update.The locale field of the CS_IODESC points to a CS_LOCALE structure containing localization information for the value, if any.ID="IN4324911112"I/O descriptor structureI/O descriptor structureand ct_data_infoct_data_infoAn application calls MOREINFO="NONE"ct_data_infoID="IN4324891313"I/O descriptor structureI/O descriptor structureand ct_send_datact_send_data
to define an I/O descriptor before calling MOREINFO="NONE"ct_send_data to send a chunk or image data to the server. Both of these calls occur during a text or image update operation.A successful text or image update generates a parameter result set that contains the new text timestamp for the text or image value. If an application plans to update the text or image value a second time, it must save this new text timestamp and copy it into the CS_IODESC for the value before calling MOREINFO="NONE"ct_data_info to define the CS_IODESC for the update operation.It is illegal to call MOREINFO="NONE"ct_data_infoID="IN4312871514"ct_data_infowhat to do before calling it
to retrieve the I/O descriptor for a column before calling MOREINFO="NONE"ct_get_data for the column. REMAP="UN--Under"However, this MOREINFO="NONE"ct_get_data call does not have to actually retrieve any data. That is, an application can call MOREINFO="NONE"ct_get_data with a buflen of 0, and then call MOREINFO="NONE"ct_data_info to retrieve the descriptor. This technique is useful when an application needs to determine the length of a text or image value before retrieving it.For more information on the I/O descriptor structure, see LINKEND="X66404""CS_IODESC Structure" 
.For more information on text and image, see LINKEND="X51184""Text and Image" 
.ID="IN4312851715"ct_data_infocode exampleExampleREMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/*** FetchResults()**** The result set contains four columns: integer, text, ** float, and integer.*/REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"CS_STATIC CS_RETCODEFetchResults(cmd, textdata)CS_COMMAND *cmd;TEXT_DATA            *textdata;{     CS_RETCOD    retcode;     CS_DATAFMT   fmt;     CS_INT       firstcol;     CS_TEXT      *txtptr;     CS_FLOAT     floatitem;     CS_INT       count;     CS_INT       len;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /* < columns prior to the columns     ** to be retrieved by ct_get_data().     ** To demonstrate this, bind the first column returned.     */     ...CODE DELETED.....REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /* Retrieve and display the result */     while(((retcode = ct_fetch(cmd, CS_UNUSED, CS_UNUSED,        CS_UNUSED,&count)) == CS_SUCCEED) ||         (retcode == CS_ROW_FAIL) )    {         /* Check for a recoverable error */        ...CODE DELETED.....REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"         /* Get the text data item in the 2nd column */         ...CODE DELETED.....REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"         /*          ** Retrieve the descriptor of the text data. It         ** is available while retrieving results of a select          ** query. The information will be needed for later          ** updates.         */         retcode = ct_data_info(cmd, CS_GET,  2,                &textdata->iodesc);          if (retcode != CS_SUCCEED)          {                ex_error("FetchResults: cs_data_info()                 failed");              return retcode;          }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"         /* Get the float data item in the 3rd column */         ...CODE DELETED.....REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"         /* Last column not retrieved */     }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /*    ** We're done processing rows. Check the final return     ** value of ct_fetch().    */     ...CODE DELETED.....REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     return retcode;}REMAP="BO--Body"This code excerpt is from the getsend.c example program.See AlsoREMAP="BO--Body"LINKEND="X26819"ct_get_data
, LINKEND="X27057"ct_send_data
, LINKEND="X51184"Text and Image
ID="IN4312822018"ct_data_info
ID="IN438792319"ct_debugct_debugID="IN445792421"Debugmanaging debug library operations
Manage debug library operations.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_debug(context, connection, operation,                 flag, filename, fnamelen) CS_CONTEXT       *context;CS_CONNECTION    *connection;CS_INT           operation;CS_INT           flag;CS_CHAR          *filename;CS_INT           fnamelen;ParametersREMAP="RI--RefIndent"context - A pointer to a CS_CONTEXT structure. A CS_CONTEXT structure defines a Client-Library application context.REMAP="UN--Under"When operation is CS_SET_DBG_FILE, context must be supplied and connection must be NULL.REMAP="UN--Under"When setting or clearing flags, use the chart in the flag parameter section to determine whether or not to supply context.connection - A pointer to a CS_CONNECTION structure. connection must point to a valid CS_CONNECTION structure, but no actual connection to a server is necessary in order to enable debug operations.REMAP="UN--Under"When operation is CS_SET_PROTOCOL_FILE, connection must be supplied and context must be NULL.REMAP="UN--Under"When setting or clearing flags, see the chart in the flag parameter section to determine whether or not to supply connection.operation - The operation to perform. The table in the MOREINFO="NONE"Summary of Parameters section lists the symbolic values that are legal for operation.flag - A bit mask representing debug subsystems. The following table lists the symbolic values that can make up flag:TOCENTRY="1"LBL="Table 3-43: "Values for flag (MOREINFO="NONE"ct_debug)COLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="117*"COLNAME="C2" COLWIDTH="63*"COLNAME="C3" COLWIDTH="180*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Value of flag:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Requires:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"When the flag is enabled, Client-
Library:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DBG_ALLCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"context 
and 
connectionCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Takes all possible debug actions.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DBG_API_STATESCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"context COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Prints information relating to Client-
Library function-level state 
transitions.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DBG_ASYNCCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"context COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Prints function trace information each 
time an asynchronous function starts 
or completes.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DBG_DIAGCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"connection COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Prints message text whenever a 
Client-Library or server message is 
generated.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DBG_ERRORCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"context COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Prints trace information whenever a 
Client-Library error occurs. This 
allows a programmer to determine 
exactly where an error is occurring.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DBG_MEMCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"context COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Prints information relating to 
memory management.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DBG_NETWORKCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"context COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Prints information relating to Client-
Library's network interactions.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DBG_PROTOCOLCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"connection COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Captures information exchanged with 
a server in protocol-specific (for 
example, TDS) format. This 
information is not human readable.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DBG_PROTOCOL_
STATESCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"connection COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Prints information relating to Client-
Library protocol-level state 
transitions.filename - The full path and name of the file to which MOREINFO="NONE"ct_debug should write the generated debug information.fnamelen - The length, in bytes, of filename.Summary of ParametersTOCENTRY="1"LBL="Table 3-44: "Summary of parameters (MOREINFO="NONE"ct_debug)COLS="4" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="144*"COLNAME="C2" COLWIDTH="77*"COLNAME="C3" COLWIDTH="76*"COLNAME="C4" COLWIDTH="166*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"operation is:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"flag is:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"filename is:COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ct_debug:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SET_FLAGCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"suppliedCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Enables the subsystems specified 
by flag.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CLEAR_FLAGCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"suppliedCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Disables the subsystems specified 
by flag.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SET_DBG_FILECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_UNUSEDCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"suppliedCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Records the name of the file to 
which it will write character-
format debug information.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SET_PROTOCOL_FILECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_UNUSEDCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"suppliedCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Records the name of the file to 
which it will write protocol-form 
debug information.ReturnsTOCENTRY="1"LBL="Table 3-45: "Return values (MOREINFO="NONE"ct_debug)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="106*"COLNAME="C2" COLWIDTH="253*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine completed successfully.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BUSYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An asynchronous operation is already pending for this 
connection. For more information, see the 
MOREINFO="NONE"Asynchronous Programming topics page.CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"ct_debugID="IN4421792427"Diagnostic subsystemsenabling and disabling
ID="IN4430792428"Tracing diagnostic information
manages debug library operations, allowing an application to enable and disable specific diagnostic subsystems and send the resultant trace information to files.MOREINFO="NONE"ct_debug functionality is available only from within the debug version of Client-Library. When called from within the standard Client-Library, it returns CS_FAIL.Some debug flags can be enabled only at the connection level, while others can be enabled only at the context level. The chart for the flag parameter indicates the level at which each flag can be enabled.If an application does not call MOREINFO="NONE"ct_debugID="IN449792429"Debuggingspecifying debug files
ID="IN448772630"ct_debugdefault behavior
to specify debug files, MOREINFO="NONE"ct_debug writes character-format debug information to stdout and protocol-form debug information to connect.dat in the application's working directory.When the debug version of Client-Library is linked in with an application, the following behaviors automatically take place:ID="IN4425772631"Memory reference checking
ID="IN449772632"Debuggingmemory reference checkingMARK="DASH" REMAP="BS--BulletSub"Memory reference checks: Client-Library verifies that all memory references, both internal and application-specific, are valid.ID="IN4425772633"Data structure validation
ID="IN449772634"Debuggingdata structure validationData structure validation: each time a Client-Library function accesses a data structure, Client-Library first validates the structure.ID="IN4418772635"Assertion checking
ID="IN449772636"Debuggingassertion checkingSpecial assertion checking: Client-Library checks that all array references, including strings, are in bounds. ID="IN449772637"Debuggingimpact on performanceBecause the debug version of Client-Library performs extensive internal checking, application performance will decrease when the debug library is in use. The level of performance decrease depends on the type and number of tracing subsystems that are enabled. To minimize performance decrease, an application programmer can selectively enable tracing subsystems, limiting heavy tracing to problem areas of code.ID="IN449772638"Debuggingaffect on asynchronous programs
ID="IN4424772639"Asynchronous programmingdebugging affects behavior of timing problemsUse of the debug library will change the behavior of asynchronous applications that are experiencing timing problems. In this case, the use of external tracing tools (for example, a network protocol analyzer) is recommended.ID="IN448752840"ct_debugcode exampleExampleREMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"...CODE DELETED.....#ifdef EX_API_DEBUG     /*     ** Enable this function right before any call to     ** Client-Library that is returning failure.     */     retcode = ct_debug(*context, NULL, CS_SET_FLAG,         CS_DBG_API_STATES, NULL, CS_UNUSED);     if (retcode != CS_SUCCEED)     {         ex_error("ex_init: ct_debug() failed");     }#endif...CODE DELETED.....REMAP="BO--Body"This code excerpt is from the exutils.c example program. For further examples of using MOREINFO="NONE"ct_debug, see the ex_alib.c, and ex_amain.c example programs.See AlsoREMAP="BO--Body"LINKEND="X46924"Error and Message Handling
, LINKEND="X26600"Client-Library Messages
, LINKEND="X39627"ct_callback
, LINKEND="X20297"ct_con_alloc
, LINKEND="X70853"ct_diag
ID="IN448723143"ct_debug
ID="INA4411693444"ct_describeID="X64204"ct_describeID="IN4510693546"Retrievingdescription of result data
ID="IN4511693547"Result datagetting a description of
Return a description of result data. REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_describe(cmd, item, datafmt) CS_COMMAND    *cmd;CS_INT        item;CS_DATAFMT    *datafmt;ParametersREMAP="RI--RefIndent"cmd - A pointer to the CS_COMMAND structure managing a client/ server operation. item - An integer representing the result item of interest. REMAP="UN--Under"ID="IN457693550"Columnsretrieving descriptions of
When retrieving a column description, item is the column's column number. The first column in a MOREINFO="NONE"select statement's select-list is column number 1, the second number 2, and so forth. REMAP="UN--Under"ID="IN4515693551"Compute columnsbinding to program variables
ID="IN4515693552"Compute columnsretrieving descriptions of
When retrieving a compute column description, item is the column number of the compute column. Compute columns are returned in the order in which they are listed in the compute clause. The first column returned is number 1. REMAP="UN--Under"ID="IN4517693553"Return parametersretrieving descriptions of
When retrieving a return parameter description, item is the parameter number of the parameter. The first parameter returned by a stored procedure is number 1. Stored procedure return parameters are returned in the same order as the parameters were originally specified in the stored procedure's MOREINFO="NONE"create procedure statement. This is not necessarily the same order as specified in the RPC command that invoked the stored procedure. In determining what number to pass as item do not count non-return parameters. For example, if the second parameter in a stored procedure is the only return parameter, pass item as 1. REMAP="UN--Under"ID="IN4517693554"Stored proceduresretrieving description of return status
When retrieving a stored procedure return status description, item must be 1, as there can be only a single status in a return status result set.REMAP="UN--Under"ID="IN4518693555"Format informationretrieving
When retrieving format information, item takes a column or compute column number.ID="IN4511673756"ct_describewhen not to callAn application cannot call MOREINFO="NONE"ct_describe after MOREINFO="NONE"ct_results indicates a result set of type CS_MSG_RESULT. This is because a result type of CS_MSG_RESULT has no data items associated with it. Parameters associated with a message are returned as a CS_PARAM_RESULT result set. Likewise, an application cannot call MOREINFO="NONE"ct_describe after MOREINFO="NONE"ct_results sets its *result_type parameter to CS_CMD_DONE, CS_CMD_SUCCEED, or CS_CMD_FAIL to indicate command status information.datafmt - A pointer to a CS_DATAFMT structure. MOREINFO="NONE"ct_describe fills *MOREINFO="NONE"datafmt with a description of the result data item referenced by item. REMAP="UN--Under"ID="IN4511634157"ct_describect_describeand CS_DATAFMT structureCS_DATAFMT structure
MOREINFO="NONE"ct_describeID="IN4520594558"CS_DATAFMT structureCS_DATAFMT structureand ct_describect_describe
fills in the following fields in the CS_DATAFMT:TOCENTRY="1"LBL="Table 3-46: "Fields in the CS_DATAFMT structure (MOREINFO="NONE"ct_describe)COLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="63*"COLNAME="C2" COLWIDTH="180*"COLNAME="C3" COLWIDTH="225*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Field name:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"For which types of result items?COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_describe sets the field to:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"name COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Regular columns, column formats, 
and return parameters. COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The null-terminated name of the data item, if 
any. A NULL name is indicated by a namelen of 
0.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"namelen COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Regular columns, column formats, 
and return parameters.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The actual length of the name, not including the 
null terminator.

0 to indicate a NULL MOREINFO="NONE"name.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"datatype COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Regular columns, column formats, 
return parameters, return status, 
compute columns, and compute 
column formats.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A type constant (CS_xxx_TYPE) representing 
the datatype of the item. 

All type constants listed on the MOREINFO="NONE"Types topics 
page are valid, with the exceptions of 
CS_VARCHAR_TYPE and 
CS_VARBINARY_TYPE.

A return status has a datatype of CS_INT_TYPE.

A compute column's datatype depends on the 
type of the underlying column and the 
aggregate operator that created the column.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"format COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Not used.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"maxlength COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Regular columns, column formats, 
and return parameters.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The maximum possible length of the data for 
the column or parameter.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"scale COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Regular columns, column formats, 
return parameters, compute columns, 
or compute column formats of type 
numeric or decimal. COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The scale of the result data item.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"precision COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Regular columns, column formats, 
return parameters, compute columns, 
or compute column formats of type 
numeric or decimal. COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The precision of the result data item.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"status COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Regular columns and column 
formats.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A bitmask of the following symbols, or-ed 
together:

CS_CANBENULL to indicate that the column 
can contain NULL values.

CS_HIDDEN to indicate that the column is a 
"hidden" column that has been exposed. For 
information on hidden columns, see "Hidden 
Keys" on the MOREINFO="NONE"Properties topics page.

CS_IDENTITY to indicate that the column is an 
identity column.

CS_KEY to indicate the column is part of the key 
for a table.

CS_VERSION_KEY to indicate the column is 
part of the version key for the row.

CS_TIMESTAMP to indicate the column is a 
timestamp column.

CS_UPDATABLE to indicate that the column is 
an updatable cursor column.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"count COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Regular columns, column formats, 
return parameters, return status, 
compute columns, and compute 
column formats.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"count represents the number of rows copied to 
program variables per MOREINFO="NONE"ct_fetch call.MOREINFO="NONE"ct_describe 
sets count to 1 to provide a default value in case 
an application uses MOREINFO="NONE"ct_describe's return 
CS_DATAFMT as MOREINFO="NONE"ct_bind's input 
CS_DATAFMT.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"usertype COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Regular columns, column formats, 
and return parameters.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The SQL Server user-defined datatype of the 
column or parameter, if any. usertype is set in 
addition to (not instead of) datatype.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"locale COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Regular columns, column formats, 
return parameters, return status, 
compute columns, and compute 
column formats.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to a CS_LOCALE structure that 
contains locale information for the data.

This pointer can be NULL.ReturnsTOCENTRY="1"LBL="Table 3-47: "Return values (MOREINFO="NONE"ct_describe)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="106*"COLNAME="C2" COLWIDTH="253*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine completed successfully.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed.
MOREINFO="NONE"
ct_describe returns CS_FAIL if MOREINFO="NONE"item does not represent 
a valid result data item.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BUSYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An asynchronous operation is already pending for this 
connection. For more information, see the 
MOREINFO="NONE"Asynchronous Programming topics page.CommentsMARK="BULL" REMAP="BU--Bullet"An application can use MOREINFO="NONE"ct_describe to retrieve a description of a regular result column, a return parameter, a stored procedure return status number, or a compute column.REMAP="UN--Under"An application can also use MOREINFO="NONE"ct_describe to retrieve format information. Client-Library indicates that format information is available by setting MOREINFO="NONE"ct_results' *result_type to CS_ROWFMT_RESULT or CS_COMPUTEFMT_RESULT.ID="IN4511574761"ct_describewhen not to callAn application cannot call MOREINFO="NONE"ct_describe after MOREINFO="NONE"ct_results sets its *result_type parameter to CS_MSG_RESULT, CS_CMD_SUCCEED, CS_CMD_DONE, or CS_CMD_FAIL. This is because, in these cases, there are no result items to describe.An application can call MOREINFO="NONE"ct_res_info to find out how many result items are present in the current result set.ID="IN4511554962"ct_describewhen to useAn application generally needs to call MOREINFO="NONE"ct_describe to describe a result data item before it binds the result item to a program variable using MOREINFO="NONE"ct_bind.See the CS_DATAFMT topics page for a description of the CS_DATAFMT structure.See the MOREINFO="NONE"Results topics page for a description of result types.ID="IN4511535163"ct_describecode exampleExampleREMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* ex_fetch_data()*/REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"CS_RETCODE CS_PUBLICex_fetch_data(cmd)CS_COMMAND   *cmd;{     CS_RETCODE      retcode;     CS_INT          num_cols;     CS_INT          i;     CS_INT          j;     CS_INT          row_count = 0;     CS_DATAFMT      *datafmt;     EX_COLUMN_DATA  *coldata;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /*      ** Determine the number of columns in this result     ** set     */     ...CODE DELETED...REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     for (i = 0; i < num_cols; i++)     {         /*         ** Get the column description.  ct_describe()           ** fills the datafmt parameter with a          ** description of the column.          */    retcode = ct_describe(cmd, (i + 1),              &datafmt[i]);         if (retcode != CS_SUCCEED)          {              ex_error("ex_fetch_data: ct_describe()                 failed");             break;         }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"          /* Now bind columns */         ...CODE DELETED.....     }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /* Now fetch rows */     ...CODE DELETED.....REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     return retcode;}REMAP="BO--Body"This code excerpt is from the exutils.c example program. For further examples of using MOREINFO="NONE"ct_describe, see the compute.c, ex_alib.c, getsend.c, and i18n.c example programs.See AlsoREMAP="BO--Body"LINKEND="X29013"ct_bind
, LINKEND="X65123"ct_fetch
, LINKEND="X70623"ct_res_info
, LINKEND="X57817"ct_results
, LINKEND="X51426"Results
ID="IN4511505466"ct_describe
ID="IN457475767"ct_diagID="X70853"ct_diagID="IN4624475869"In-line message handlingmanaging
ID="IN4626456070"Error and message handlingSee In-line message handling
ID="IN4624436271"In-line message handlingIn-line message handlingand ct_diagct_diag
Manage in-line error handling.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_diag(connection, operation, type, index,                    buffer)CS_CONNECTION    *connection;CS_INT           operation;CS_INT           type;CS_INT           index;CS_VOID          *buffer;Parameters REMAP="RI--RefIndent"connection - A pointer to a CS_CONNECTION structure. A CS_CONNECTION structure contains information about a particular client/ server connection.operation - The operation to perform. The table in the MOREINFO="NONE"Summary of Parameters section lists the symbolic values that are legal for operation.type - Depending on the value of operation, type indicates either the type of structure to receive message information, the type of message on which to operate, or both. The following table lists the symbolic values that are legal for type:TOCENTRY="1"LBL="Table 3-48: "Values for type (MOREINFO="NONE"ct_diag)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"Value of type:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SQLCA_TYPECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A SQLCA structure.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SQLCODE_TYPECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A SQLCODE structure, which is a long integer. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SQLSTATE_TYPECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A SQLSTATE structure, which is an array of bytes.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CLIENTMSG_TYPECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A CS_CLIENTMSG structure. Also used to 
indicate Client-Library messages.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SERVERMSG_TYPECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A CS_SERVERMSG structure. Also used to 
indicate server messages.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_ALLMSG_TYPECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Client-Library and server messages.index - The index of the message of interest. The first message has an index of 1, the second an index of 2, and so forth.REMAP="UN--Under"If type is CS_CLIENTMSG_TYPE, then index refers to Client-Library messages only. If type is CS_SERVERMSG_TYPE, then index refers to server messages only. If type is CS_ALLMSG_TYPE, then index refers to Client-Library and server messages combined.buffer - A pointer to data space.REMAP="UN--Under"Depending on the value of operation, buffer can point to a structure or a CS_INT.Summary of ParametersTOCENTRY="1"LBL="Table 3-49: "Summary of parameters (MOREINFO="NONE"ct_diag)COLS="5" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="82*"COLNAME="C2" COLWIDTH="106*"COLNAME="C3" COLWIDTH="137*"COLNAME="C4" COLWIDTH="74*"COLNAME="C5" COLWIDTH="67*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Value of 
MOREINFO="NONE"operation:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_diag:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"type is: COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"index is:COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"buffer is:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_INITCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Initializes in-line 
error handling.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_UNUSEDCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_UNUSEDCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_MSGLIMITCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Sets the maximum 
number of messages 
to store.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CLIENTMSG_TYPE to 
limit Client-Library 
messages only.

CS_SERVERMSG_TYPE to 
limit server messages only.

CS_ALLMSG_TYPE to 
limit the total number of 
Client-Library and server 
messages combined.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_UNUSEDCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to 
an integer 
value.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CLEARCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Clears message 
information for this 
connection.

If buffer is not NULL 
and type is not 
CS_ALLMSG_TYPE, 
MOREINFO="NONE"ct_diag also clears the 
*buffer structure by 
initializing it with 
blanks and/or 
NULLs, as 
appropriate.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"One of the legal type values:

If type is 
CS_CLIENTMSG_TYPE, 
MOREINFO="NONE"ct_diag clears Client-
Library messages only.

If type is 
CS_SERVERMSG_TYPE, 
MOREINFO="NONE"ct_diag clears server 
messages only.

If type has any other legal 
value, MOREINFO="NONE"ct_diag clears both 
Client-Library and server 
messages.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_UNUSEDCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to 
a structure 
whose type 
is defined 
by type, or 
NULL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_GETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieves a specific 
message.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Any legal type value except 
CS_ALLMSG_TYPE.

If type is 
CS_CLIENTMSG_TYPE, a 
Client-Library message is 
retrieved into a 
CS_CLIENTMSG structure.

If type is 
CS_SERVERMSG_TYPE, a 
server message is retrieved 
into a CS_SERVERMSG 
structure.

If type has any other legal 
value, then either a Client-
Library or server message 
is retrieved.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The one-
based index 
of the 
message to 
retrieve.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to 
a structure 
whose type 
is defined 
by type.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_STATUSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Returns the current 
number of stored 
messages.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CLIENTMSG_TYPE to 
retrieve the number of 
Client-Library messages.

CS_SERVERMSG_TYPE to 
retrieve the number of 
server messages.

CS_ALLMSG_TYPE to 
retrieve the total number of 
Client-Library and server 
messages combined.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_UNUSEDCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to 
an integer 
variable.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_EED_CMDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Sets *buffer to the 
address of the 
CS_COMMAND 
structure containing 
extended error data.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SERVERMSG_TYPECOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The one-
based index 
of the 
message for 
which 
extended 
error data is 
available.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to 
a pointer 
variable.ReturnsTOCENTRY="1"LBL="Table 3-50: "Return values (MOREINFO="NONE"ct_diag)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="106*"COLNAME="C2" COLWIDTH="253*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine completed successfully.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed.
MOREINFO="NONE"
ct_diag returns CS_FAIL if the original error has made 
the connection unusable.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_NOMSGCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The application attempted to retrieve a message whose 
index is higher than the highest valid index. For 
example, the application attempted to retrieve 
message number 3, when there are only 2 messages 
queued.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BUSYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An asynchronous operation is already pending for this 
connection. For more information, see the 
MOREINFO="NONE"Asynchronous Programming topics page.ID="IN467416476"ct_diagreasons for failureREMAP="BO--Body"Common reasons for a MOREINFO="NONE"ct_diag failure include:MARK="BULL" REMAP="BU--Bullet"Invalid connection.Inability to allocate memory.Invalid parameter combination.CommentsMARK="BULL" REMAP="BU--Bullet"A Client-Library application can handle Client-Library and server messages in two ways:MARK="DASH" REMAP="BS--BulletSub"The application can call MOREINFO="NONE"ct_callback to install client message and server message callbacks to handle Client-Library and server messages.The application can handle Client-Library and server messages in-line, using MOREINFO="NONE"ct_diag.REMAP="UN--Under"It is possible for an application to switch back and forth between the two methods. For information on how to do this, see the MOREINFO="NONE"Errors and Messages topics page.MOREINFO="NONE"ct_diagID="IN467396678"ct_diagconnection-specific in-line message handling
manages in-line message handling for a specific connection. If an application has more than one connection, it must make separate MOREINFO="NONE"ct_diag calls for each connection.An application cannot use MOREINFO="NONE"ct_diagID="IN467376879"ct_diagnot for use at the context level
at the context level. That is, an application cannot use MOREINFO="NONE"ct_diag to retrieve messages generated by routines that take a CS_CONTEXT (and no CS_CONNECTION) as a parameter. These messages are unavailable to an application that is using in-line error handling.An application can perform operations on either Client-Library messages, server messages, or both.REMAP="UN--Under"For example, an application can clear Client-Library messages without affecting server messages:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"ct_diag(connection, CS_CLEAR, CS_CLIENTMSG,        CS_UNUSED, NULL);MOREINFO="NONE"ct_diag allows an application to retrieve message information into standard Client-Library structures (CS_CLIENTMSG and CS_SERVERMSG) or a SQLCA, SQLCODE, or SQLSTATE. When retrieving messages, MOREINFO="NONE"ct_diag assumes that buffer points to a structure of the type indicated by type.REMAP="UN--Under"An application that is retrieving messages into a SQLCA, SQLCODE, or SQLSTATE must set the Client-Library property ID="IN4624357080"In-line message handlingIn-line message handlingand CS_EXTRA_INF propertyCS_EXTRA_INF property
CS_EXTRA_INF to CS_TRUE. This is because the SQL structures require information that is not ordinarily returned by Client-Library's error handling mechanism.REMAP="UN--Under"An application that is not using the SQL structures can also set CS_EXTRA_INF to CS_TRUE. In this case, the extra information is returned as standard Client-Library messages.If MOREINFO="NONE"ct_diagID="IN4624337281"In-line message handlingct_diag can discard unread messages
does not have sufficient internal storage space in which to save a new message, it throws away all unread messages and stops saving messages. The next time it is called with operation as CS_GET, it returns a special message to indicate the space problem.REMAP="UN--Under"After returning this message, MOREINFO="NONE"ct_diag starts saving messages again.Initializing In-Line Error HandlingID="IN4624337282"In-line message handlinginitializingMARK="BULL" REMAP="BU--Bullet"To initialize in-line error handling, an application calls MOREINFO="NONE"ct_diag with operation as CS_INIT.Generally, if a connection will use in-line error handling, an application should call MOREINFO="NONE"ct_diag to initialize in-line error handling for a connection immediately after allocating it.Clearing MessagesID="IN4624337283"In-line message handlingclearing a connectionÕ s messagesMARK="BULL" REMAP="BU--Bullet"To clear message information for a connection, an application calls MOREINFO="NONE"ct_diag with operation as CS_CLEAR. MARK="DASH" REMAP="BS--BulletSub"To clear Client-Library messages only, an application passes type as CS_CLIENTMSG_TYPE.To clear server messages only, an application passes type as CS_SERVERMSG. To clear both Client-Library and server messages, pass type as SQLCA, SQLCODE, or CS_ALLMSG_TYPE.If type is not CS_ALLMSG_TYPE:MARK="DASH" REMAP="BS--BulletSub" MOREINFO="NONE"ct_diag assumes that buffer points to a structure of type type. MOREINFO="NONE"ct_diag clears the *buffer structure by setting it to blanks and/or NULLs, as appropriate.Message information is not cleared until an application explicitly calls MOREINFO="NONE"ct_diag with operations as CS_CLEAR. Retrieving a message does not remove it from the message queue.ID="IN4624337284"In-line message handlingretrieving messagesRetrieving MessagesMARK="BULL" REMAP="BU--Bullet"To retrieve message information, an application calls MOREINFO="NONE"ct_diag with operation as CS_GET, type as the type of structure in which to retrieve the message, index as the one-based index of the message of interest, and *buffer as a structure of the appropriate type.If type is CS_CLIENTMSG_TYPE, then index refers only to Client-Library messages. If type is CS_SERVERMSG_TYPE, index refers only to server messages. If type has any other value, index refers to the collective "queue" of both types of messages combined.MOREINFO="NONE"ct_diag fills in the *buffer structure with the message information.If an application attempts to retrieve a message whose index is higher than the highest valid index, MOREINFO="NONE"ct_diag returns CS_NOMSG to indicate that no message is available.See theMOREINFO="NONE" SQLCA, SQLCODE, CS_CLIENTMSG andMOREINFO="NONE" CS_SERVERMSG topics pages for information on these structures.ID="IN4624337285"In-line message handlinglimiting messagesLimiting MessagesMARK="BULL" REMAP="BU--Bullet"Applications running on platforms with limited memory may want to limit the number of messages that Client-Library saves.An application can limit the number of saved Client-Library messages, the number of saved server messages, and the total number of saved messages.To limit the number of saved messages, an application calls MOREINFO="NONE"ct_diag with operation as CS_MSGLIMIT and type as CS_CLIENTMSG_TYPE, CS_SERVERMSG_TYPE, or CS_ALLMSG_TYPE:MARK="DASH" REMAP="BS--BulletSub" If type is CS_CLIENTMSG_TYPE, then the number of Client-Library messages is limited.If type is CS_SERVERMSG_TYPE, then the number of server messages is limited.If type is CS_ALLMSG_TYPE, then the total number of Client-Library and server messages combined is limited.When a specific message limit is reached, Client-Library discards any new messages of that type. When a combined message limit is reached, Client-Library discards any new messages. If Client-Library discards messages, it saves a message to this effect.An application cannot set a message limit that is less than the number of messages currently saved.Client-Library's default behavior is to save an unlimited number of messages. An application can restore this default behavior by setting a message limit of ID="IN4625317486"CS_NO_LIMIT message limit
ID="IN4624297687"In-line message handlinglimiting messages:CS_NO_LIMIT
CS_NO_LIMIT.ID="IN4624297688"In-line message handlingretrieving the number of messagesRetrieving the Number of MessagesMARK="BULL" REMAP="BU--Bullet"To retrieve the number of current messages, an application calls MOREINFO="NONE"ct_diag with operation as CS_STATUS and type as the type of message of interest.Getting the CS_COMMAND for Extended Error DataID="IN4624277889"In-line message handlingretrieving a pointer to the CS_COMMAND structureMARK="BULL" REMAP="BU--Bullet"To retrieve a pointer to the CS_COMMANDID="IN4624277890"In-line message handlingextended error data
ID="IN467258091"ct_diagextended error data
structure containing extended error data (if any), call MOREINFO="NONE"ct_diag with operation as CS_EED_CMD and type as CS_SERVERMSG_TYPE. MOREINFO="NONE"ct_diag sets *buffer to the address of the CS_COMMAND structure containing the extended error data.When an application retrieves a server message into a CS_SERVERMSG structure, Client-Library indicates that extended error data is available for the message by setting the CS_HASEED bit in the status field in the CS_SERVERMSG structure.It is an error to call MOREINFO="NONE"ct_diag with operation as CS_EED_CMD when extended error data is not available.For more information on extended error data, see LINKEND="X78290""Extended Error Data" 
.ID="IN4624258092"In-line message handlingsequenced messages
ID="IN467238293"ct_diagsequenced messagesSequenced Messages and MOREINFO="NONE"ct_diagMARK="BULL" REMAP="BU--Bullet"If an application is using sequenced error messages, MOREINFO="NONE"ct_diag acts on message chunks instead of messages. This has the following effects:MARK="DASH" REMAP="BS--BulletSub"A MOREINFO="NONE"ct_diag(CS_GET) call with index i returns the i'th message chunk, not the i'th message.A MOREINFO="NONE"ct_diag(CS_MSGLIMIT) call limits the number of chunks, not the number of messages, that Client-Library will store.A MOREINFO="NONE"ct_diag(CS_STATUS) call returns the number of currently-stored chunks, not the number of currently-stored messages.For more information on sequenced messages, see LINKEND="X74900""Sequencing Long Messages" 
.See AlsoREMAP="BO--Body"LINKEND="X46924"Error and Message Handling
, LINKEND="X26600"Client-Library Messages
, LINKEND="X39627"ct_callback
, LINKEND="X61859"ct_options
ID="IN467208595"ct_diagID="X77746"ct_dynamicID="IN43519753"Initiating a prepared dynamic SQL statement command
ID="IN43199754"Prepared statementsinitiating a dynamic SQL statement command
ID="IN43119755"Dynamic SQLinitiating a prepared dynamic SQL statement command
ID="IN4389756"Commandsinitiating a prepared dynamic SQL statement command
Initiate a prepared dynamic SQL statement command.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_dynamic(cmd, type, id, idlen, buffer,                buflen)CS_COMMAND *cmd;CS_INT     type;CS_CHAR    *id;CS_INT     idlen;CS_CHAR    *buffer;CS_INT     buflen;ParametersREMAP="RI--RefIndent"cmd - A pointer to the CS_COMMAND structure managing a client/ server operation.type - The type of dynamic SQL command to initiate. The table in the MOREINFO="NONE"Summary of Parameters sections lists the symbolic values that are legal for type.id - A pointer to the statement identifier. This identifier is defined by the application and must conform to server standards.idlen - The length, in bytes, of *id. If *id is null-terminated, pass idlen as CS_NULLTERM. If id is NULL, pass idlen as CS_UNUSED.buffer - A pointer to data space.buflen - The length, in bytes, of *buffer. If *buffer is null-terminated, pass buflen as CS_NULLTERM. If buffer is NULL, pass buflen as CS_UNUSED.Summary of ParametersTOCENTRY="1"LBL="Table 3-51: "Summary of parameters (MOREINFO="NONE"ct_dynamic)COLS="4" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="126*"COLNAME="C2" COLWIDTH="171*"COLNAME="C3" COLWIDTH="90*"COLNAME="C4" COLWIDTH="81*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Value of MOREINFO="NONE"type:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ct_dynamic:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"*MOREINFO="NONE"id is:COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"*buffer is:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CURSOR_DECLARECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Declares a cursor on a previously-
prepared SQL statement.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The prepared 
statement 
identifier.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The cursor 
name.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DEALLOCCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"De-allocates a prepared SQL 
statement.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The prepared 
statement 
identifier.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DESCRIBE_INPUTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieves input parameter 
information. An application can 
access this information via 
MOREINFO="NONE"ct_describe or via MOREINFO="NONE"ct_dyndesc.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The prepared 
statement 
identifier.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DESCRIBE_OUTPUTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieves column list information. 
An application can access this 
information via MOREINFO="NONE"ct_describe or via 
MOREINFO="NONE"ct_dyndesc.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The prepared 
statement 
identifier.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_EXECUTECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Executes a prepared SQL statement 
that requires zero or more 
parameters.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The prepared 
statement 
identifier.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_EXEC_IMMEDIATECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Execute a literal SQL statement.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The SQL 
statement to 
execute.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_PREPARECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Prepares a SQL statement.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The prepared 
statement 
identifier.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The SQL 
statement to 
prepare.ReturnsTOCENTRY="1"LBL="Table 3-52: "Return values (MOREINFO="NONE"ct_dynamic)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="106*"COLNAME="C2" COLWIDTH="253*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine completed successfully.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BUSYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An asynchronous operation is already pending for this 
connection. For more information, see the 
MOREINFO="NONE"Asynchronous Programming topics page.REMAP="BO--Body"CommentsMARK="BULL" REMAP="BU--Bullet"Initiating a command is the first step in sending it to a server.ID="IN431197512"Dynamic SQLsending a command to a serverSending a command to a server is a four step process. To send a command to a server, an application must: MARK="DASH" REMAP="BS--BulletSub"Initiate the command by calling MOREINFO="NONE"ct_dynamic. This routine sets up internal structures that are used in building a command stream to send to the server.Pass parameters for the command, if required. Most applications will pass parameters by calling MOREINFO="NONE"ct_param once for each parameter that the command requires, but it is also possible to pass parameters for a command by using MOREINFO="NONE"ct_dyndesc.Send the command to the server by calling MOREINFO="NONE"ct_send.Verify the success of the command by calling MOREINFO="NONE"ct_results.REMAP="UN--Under"This last step does not imply that an application need only call MOREINFO="NONE"ct_results once. If the value of MOREINFO="NONE"ct_results' result_type parameter indicates that there are fetchable results, the application will most likely process the results using a loop controlled by MOREINFO="NONE"ct_results. See the Open Client Client-Library/C Programmer's Guide for a discussion of processing results.About Prepared StatementsID="IN431997513"Prepared statementsdefinition
ID="IN431997514"Prepared statementsassociated with unique identifiersMARK="BULL" REMAP="BU--Bullet"A prepared SQL statement is a SQL statement which is compiled and stored by a server. Each prepared statement is associated with a unique identifier.An application can prepare an unlimited number of statements, but identifiers for prepared statements must be unique within a connection.ID="IN431997515"Prepared statementscommand structures must belong to same connectionAlthough the command structure used to prepare a statement can be different from the one used to execute it, both of the command structures must belong to the same connection.ID="IN431997516"Prepared statementshow to specify host variables in Transact-SQL commandsIf a prepared statement is a Transact-SQL command containing host variables, each variable must begin with a colon (:).ID="IN431995717"Prepared statementspassing parameters using ct_paramIf a prepared statement requires parameters, they are passed using MOREINFO="NONE"ct_paramID="IN431993918"Prepared statementspassing parameters using ct_dyndesc
or MOREINFO="NONE"ct_dyndesc at execute time.Once a statement is successfully prepared, it can be executed repeatedly until it is de-allocated.For more information on dynamic SQL, see the MOREINFO="NONE"Dynamic SQL topics page.ID="IN431993919"Prepared statementspreparing a statementPreparing a StatementMARK="BULL" REMAP="BU--Bullet"To initiate a command to prepare a statement, an application calls MOREINFO="NONE"ct_dynamic with type as CS_PREPARE.ID="IN431993920"Prepared statementsdeclaring a cursor onDeclaring a Cursor on a Prepared StatementMARK="BULL" REMAP="BU--Bullet"To initiate a command to declare a cursor on a prepared statement, an application calls MOREINFO="NONE"ct_dynamic with type as CS_CURSOR_DECLARE.An application must declare a cursor on a prepared statement prior to executing the prepared statement.ID="IN4319891321"Prepared statementssetting readonly or for updateSetting OptionsMARK="BULL" REMAP="BU--Bullet"After declaring a cursor on a prepared statement, an application can call MOREINFO="NONE"ct_cursor(CS_CURSOR_OPTION) to set options (`readonly' and `for update') for the cursor.ID="IN4319891322"Prepared statementsgetting a description of input parametersGetting a Description of Prepared Statement InputMARK="BULL" REMAP="BU--Bullet"To initiate a command to get a description of prepared statement input parameters, an application calls MOREINFO="NONE"ct_dynamic with type as CS_DESCRIBE_INPUT.An application typically retrieves a description of prepared statement input parameters before passing input values to a prepared statement.For information on how to access the information returned as the result of a CS_DESCRIBE_INPUT command, see "Getting a Description of Prepared Statement Input," on the MOREINFO="NONE"Dynamic SQL topics page.ID="IN4319891323"Prepared statementsgetting a description of output fromGetting a Description of Prepared Statement OutputMARK="BULL" REMAP="BU--Bullet"To initiate a command to get a description of prepared statement output columns, an application calls MOREINFO="NONE"ct_dynamic with type as CS_DESCRIBE_OUTPUT.For information on how to access the information returned as the result of a CS_DESCRIBE_OUTPUT command, see "Getting a Description of Prepared Statement Output," on the MOREINFO="NONE"Dynamic SQL topics page.ID="IN4319891324"Prepared statementsexecutingExecuting a Prepared StatementMARK="BULL" REMAP="BU--Bullet"To initiate a command to execute a prepared statement, an application calls MOREINFO="NONE"ct_dynamic with type as CS_EXECUTE.ID="IN4318891325"Literal statementsexecuting a dynamic SQL literal statementExecuting a Literal StatementMARK="BULL" REMAP="BU--Bullet"To initiate a command to execute a literal SQL statement, an application calls MOREINFO="NONE"ct_dynamic with type as CS_EXEC_IMMEDIATE.ID="IN4319891326"Prepared statementsde-allocatingDe-allocating a Prepared StatementMARK="BULL" REMAP="BU--Bullet"To initiate a command to de-allocate a prepared statement, an application calls MOREINFO="NONE"ct_dynamic with type as CS_DEALLOC.See AlsoREMAP="BO--Body"LINKEND="X39013"Dynamic SQL
, LINKEND="X87963"ct_dyndesc
, LINKEND="X45322"ct_param
, LINKEND="X69834"ct_send
ID="IN4310861628"ct_dynamic
ID="IN4310831929"ct_dyndescID="X87963"ct_dyndescID="IN4411832031"Dynamic SQLperforming operations on a descriptor area
ID="IN4415832032"Descriptor areaperforming operations on
Perform operations on a dynamic SQL descriptor area.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_dyndesc(cmd, descriptor, desclen,                  operation, index, datafmt, buffer,                  buflen, copied, indicator)CS_COMMAND    *cmd;CS_CHAR       *descriptor;CS_INT        desclen;CS_INT        operation;CS_INT        index;CS_DATAFMT    *datafmt;CS_VOID       *buffer;CS_INT        buflen;CS_INT        *copied;CS_SMALLINT   *indicator;ParametersREMAP="RI--RefIndent"cmd - A pointer to a CS_COMMAND structure. Any CS_COMMAND in the same context in which a descriptor is allocated can be used to operate on the descriptor. descriptor - A pointer to the name of the descriptor. Descriptor names must be unique within a connection.desclen - The length, in bytes, of *descriptor. If *descriptor is null-terminated, pass desclen as CS_NULLTERM. operation - The descriptor operation to initiate. The following table lists the values that are legal for operation:TOCENTRY="1"LBL="Table 3-53: "Values for operation (MOREINFO="NONE"ct_dyndesc)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="99*"COLNAME="C2" COLWIDTH="262*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Value of operation:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ct_dyndesc:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_ALLOCCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Allocates a descriptor.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DEALLOCCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"De-allocates a descriptor.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_GETATTRCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieves a parameter or result item's attributes.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_GETCNTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieves the number of parameters or columns.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SETATTRCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Sets a parameter's attributes.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SETCNTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Sets the number of parameters or columns.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_USE_DESCCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Associates a descriptor with a statement or a command 
structure.index - When used, an integer variable.REMAP="UN--Under"Depending on the value of operation, index can be either the zero-based index of a descriptor item or the number of items associated with a descriptor.datafmt - When used, a pointer to a CS_DATAFMT structure.buffer - When used, a pointer to data space.buflen - When used, buflen is the length, in bytes, of the *buffer data.   copied - When used, a pointer to an integer variable. MOREINFO="NONE"ct_dyndesc sets *copied to the length, in bytes, of the data placed in *buffer.indicator - When used, a pointer to an indicator variable.REMAP="UN--Under"The following table lists the possible values of *indicator:TOCENTRY="1"LBL="Table 3-54: "Values for indicator (MOREINFO="NONE"ct_dyndesc)COLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="92*"COLNAME="C2" COLWIDTH="92*"COLNAME="C3" COLWIDTH="175*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Value of 
operation:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Value of 
*indicator:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_GETATTRCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"-1COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Truncation of a server value by 
Client-Library.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"0COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No truncation.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"integer valueCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Truncation of an application value 
by the server.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SETATTRCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"-1COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The parameter has a null value.ReturnsTOCENTRY="1"LBL="Table 3-55: "Return values (MOREINFO="NONE"ct_dyndesc)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="106*"COLNAME="C2" COLWIDTH="253*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine completed successfully.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_ROW_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A recoverable error occurred. Recoverable errors 
include conversion errors that occur while copying 
values to program variables as well as memory 
allocation failures.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CANCELEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The dynamic SQL operation was canceled.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BUSYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An asynchronous operation is already pending for this 
connection. For more information, see the 
MOREINFO="NONE"Asynchronous Programming topics page.CommentsID="IN4415832037"Descriptor areadefinition ofMARK="BULL" REMAP="BU--Bullet"A dynamic SQL descriptor area contains information about the input parameters to a dynamic SQL statement or the result data items generated by the execution of a dynamic SQL statement.Although MOREINFO="NONE"ct_dyndesc takes a CS_COMMANDID="IN4415832038"Descriptor areascope is a Client-Library context
structure as a parameter, the scope of a dynamic SQL descriptor area is a Client-Library context. That is:ID="IN4415832039"Descriptor areaname must be unique within a contextMARK="DASH" REMAP="BS--BulletSub"Descriptor names must be unique within a context.ID="IN4415832040"Descriptor areause of command structures within a contextAn application can use any command structure within a context to reference the context's descriptor areas. For example, a descriptor area allocated through one command structure can be de-allocated by another command structure within the same context.For more information about dynamic SQL, see theMOREINFO="NONE" Dynamic SQL topics page.ID="IN4415832041"Descriptor areaallocatingAllocating a DescriptorMARK="BULL" REMAP="BU--Bullet"To allocate a descriptor, an application calls MOREINFO="NONE"ct_dyndesc with operation as CS_ALLOC.The following table lists parameter values for CS_ALLOC operations:TOCENTRY="1"LBL="Table 3-56: "Parameter values for CS_ALLOC operationsCOLS="6" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="136*"COLNAME="C2" COLWIDTH="117*"COLNAME="C3" COLWIDTH="46*"COLNAME="C4" COLWIDTH="72*"COLNAME="C5" COLWIDTH="43*"COLNAME="C6" COLWIDTH="51*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"descriptor,
desclen:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"index:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"datafmt
:COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"buffer, 
buflen:COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"copied
:COLNAME="C6" ALIGN="LEFT" ROTATE="0" MOREROWS="0"indicator
:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The name of the descriptor 
to allocate,
the length of the name or 
CS_NULLTERM.COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The maximum number 
of items that the 
descriptor will 
accommodate.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULL,
CS_UNUSEDCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C6" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLID="IN4415832042"Descriptor areade-allocatingDe-allocating a DescriptorMARK="BULL" REMAP="BU--Bullet"To de-allocate a descriptor, an application calls MOREINFO="NONE"ct_dyndesc with operation as CS_DEALLOC.The following table lists parameter values for CS_DEALLOC operations:TOCENTRY="1"LBL="Table 3-57: "Parameter values for CS_DEALLOC operationsCOLS="6" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="173*"COLNAME="C2" COLWIDTH="78*"COLNAME="C3" COLWIDTH="46*"COLNAME="C4" COLWIDTH="72*"COLNAME="C5" COLWIDTH="43*"COLNAME="C6" COLWIDTH="51*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"descriptor,
desclen:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"index:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"datafmt
:COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"buffer, 
buflen:COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"copied
:COLNAME="C6" ALIGN="LEFT" ROTATE="0" MOREROWS="0"indicator
:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The name of the descriptor to de-
allocate,
the length of the name or 
CS_NULLTERM.COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_UNUSEDCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULL,
CS_UNUSEDCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C6" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLID="IN4415832043"Descriptor arearetrieving a parameter or result itemÕ s attributesRetrieving a Parameter or Result Item's AttributesMARK="BULL" REMAP="BU--Bullet"To retrieve a parameter's or a result data item's attributes, an application calls MOREINFO="NONE"ct_dyndesc with operation as CS_GETATTR.The following table lists parameter values for CS_GETATTR operations:TOCENTRY="1"LBL="Table 3-58: "Parameter values for CS_GETATTR operationsCOLS="6" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="88*"COLNAME="C2" COLWIDTH="67*"COLNAME="C3" COLWIDTH="78*"COLNAME="C4" COLWIDTH="104*"COLNAME="C5" COLWIDTH="67*"COLNAME="C6" COLWIDTH="67*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"descriptor,
desclen:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"index:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"datafmt:COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"buffer,
buflen:COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"copied:COLNAME="C6" ALIGN="LEFT" ROTATE="0" MOREROWS="0"indicator:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The name of the 
descriptor of 
interest,the length of the 
name or 
CS_NULLTERM.COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The 
number of 
the item 
whose 
description 
is being 
requested.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"As an input 
parameter, 
*datafmt 
describes 
*buffer.
MOREINFO="NONE"
ct_dyndesc 
overwrites 
*datafmt with 
a description 
of the item.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"If supplied, *buffer is 
set to the value of 
the item. 

If buffer is NULL, 
only a description 
of the item is 
returned.

buflen must be 
CS_UNUSED.

datafmtname='rArrow' font='symbol' code='174'  charset='fontspecific'maxlength 
describes *buffer's 
length.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"If supplied, 
*copied is 
set to the 
number of 
bytes placed 
in *buffer. 

Can be 
NULL.COLNAME="C6" ALIGN="LEFT" ROTATE="0" MOREROWS="0"If supplied, 
*indicator is 
set to the 
value of the 
item's 
indicator.

Can be 
NULL.An application needs to set the *datafmt fields for a CS_GETATTR operation exactly as they would be set for a MOREINFO="NONE"ct_bind call. The following table lists the fields that are used:TOCENTRY="1"LBL="Table 3-59: "CS_DATAFMT fields to set for CS_GETATTR operationsCOLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="90*"COLNAME="C2" COLWIDTH="268*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Field name:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Set the field to:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"datatype COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The datatype of the buffer variable.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"format COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A bit-mask of format symbols.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"maxlength COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The length of the buffer data space.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"scale COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The scale of a numeric or decimal buffer; ignored for all 
other datatypes.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"precision COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The precision of a numeric or decimal buffer; ignored for 
all other datatypes.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"count COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"0 or 1COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"locale COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to a valid CS_LOCALE structure or NULL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"All other fieldsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Are ignored.MOREINFO="NONE"ct_dyndesc(CS_GETATTR) sets the *datafmt fields exactly as MOREINFO="NONE"ct_describe would set them. The following table lists the fields in *datafmt that MOREINFO="NONE"ct_dyndesc sets:TOCENTRY="1"LBL="Table 3-60: "CS_DATAFMT fields set during CS_GETATTR operationsCOLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="90*"COLNAME="C2" COLWIDTH="270*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Field name:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_dyndesc sets the field to:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"name COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The null-terminated name of the data item, if any. A NULL 
name is indicated by a namelen of 0.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"namelen COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The actual length of the name, not including the null 
terminator.

0 to indicate a NULL MOREINFO="NONE"name.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"datatype COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The datatype of the item. All datatypes listed on the MOREINFO="NONE"types 
topics page are valid, with the exceptions of 
CS_VARCHAR and CS_VARBINARY.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"maxlength COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The maximum possible length of the data for the column 
or parameter.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"scale COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The scale of the result data item.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"precision COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The precision of the result data item.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"status COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A bitmask of the following symbols, or-ed together:

CS_CANBENULL to indicate that the column can contain 
NULL values.

CS_HIDDEN to indicate that the column is a "hidden" 
column that has been exposed. For information on hidden 
columns, see "Hidden Keys" on the MOREINFO="NONE"Properties topics page.

CS_IDENTITY to indicate that the column is an identity 
column.

CS_KEY to indicate the column is part of the key for a 
table.

CS_VERSION_KEY to indicate the column is part of the 
version key for the row.

CS_TIMESTAMP to indicate the column is a timestamp 
column.

CS_UPDATABLE to indicate that the column is an 
updatable cursor column.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"count COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"count represents the number of rows copied to program 
variables per MOREINFO="NONE"ct_fetch call.MOREINFO="NONE"ct_dyndesc sets count to 1 to 
provide a default value in case an application uses 
MOREINFO="NONE"ct_dyndesc's return CS_DATAFMT as MOREINFO="NONE"ct_bind's input 
CS_DATAFMT.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"usertype COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The SQL Server user-defined datatype of the column or 
parameter, if any. usertype is set in addition to (not instead 
of) datatype.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"locale COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to a CS_LOCALE structure that contains locale 
information for the data.

This pointer can be NULL.ID="IN4415832044"Descriptor arearetrieving the number of parameters or columnsRetrieving the Number of Parameters or ColumnsMARK="BULL" REMAP="BU--Bullet"To retrieve the number of parameters or result items a descriptor can describe, an application calls MOREINFO="NONE"ct_dyndesc with operation as CS_GETCNT.MOREINFO="NONE"ct_dyndesc sets *buffer to the number of dynamic parameter specifications or the number of columns in the dynamic SQL statement's select list, depending on whether input parameters or output columns are being described.The following table lists parameter values for CS_GETCNT operations:TOCENTRY="1"LBL="Table 3-61: "Parameter values for CS_GETCNT operationsCOLS="6" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="101*"COLNAME="C2" COLWIDTH="72*"COLNAME="C3" COLWIDTH="46*"COLNAME="C4" COLWIDTH="108*"COLNAME="C5" COLWIDTH="86*"COLNAME="C6" COLWIDTH="51*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"descriptor,
desclen:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"index:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"datafmt
:COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"buffer, 
buflen:COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"copied:COLNAME="C6" ALIGN="LEFT" ROTATE="0" MOREROWS="0"indicator
:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The name of the 
descriptor of 
interest, 
the length of the 
name or 
CS_NULLTERM.COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_UNUSEDCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to a 
CS_INT,
CS_UNUSED.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"If supplied,
*copied is set to 
the number of 
bytes placed in 
*buffer. 
Can be NULL.COLNAME="C6" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLID="IN4415832045"Descriptor areasetting a parameterÕ s attributesSetting a Parameter's AttributesMARK="BULL" REMAP="BU--Bullet"To set a parameter's attributes, an application calls MOREINFO="NONE"ct_dyndesc with operation as CS_SETATTR.The following table lists parameter values for CS_SETATTR operations:TOCENTRY="1"LBL="Table 3-62: "Parameter values for CS_SETATTR operationsCOLS="6" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="88*"COLNAME="C2" COLWIDTH="62*"COLNAME="C3" COLWIDTH="63*"COLNAME="C4" COLWIDTH="104*"COLNAME="C5" COLWIDTH="43*"COLNAME="C6" COLWIDTH="110*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"descriptor,
desclen:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"index:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"datafmt:COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"buffer, 
buflen:COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"copied
:COLNAME="C6" ALIGN="LEFT" ROTATE="0" MOREROWS="0"indicator:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The name of the 
descriptor of 
interest,the length of the 
name or 
CS_NULLTERM.COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The 
number of 
the item 
whose 
descriptionis being 
set.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"*datafmt 
contains a 
description
of the item.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to the 
value of the item, 
the length of the 
value.

Pass buflen as 
CS_UNUSED if 
buffer points to a 
fixed-length type.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C6" ALIGN="LEFT" ROTATE="0" MOREROWS="0"If supplied, *indicator 
is the value of the 
item's indicator.

If *indicator is -1 then 
buffer is ignored and 
the value of the item 
is set to NULL.

indicator can be 
NULL.An application needs to set the *datafmt fields for a CS_SETATTR operation exactly as they would be set for a MOREINFO="NONE"ct_param call. The following table lists the fields that are used:TOCENTRY="1"LBL="Table 3-63: "CS_DATAFMT fields for CS_SETATTR operationsCOLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="90*"COLNAME="C2" COLWIDTH="268*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Field name:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Set the field to:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"name COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The name of the parameter.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"namelen COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The length of the name or CS_NULLTERM.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"datatype COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The datatype of the item being set.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"maxlength COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"For variable-length return parameters, maxlength is the 
maximum number of bytes to be returned for this 
parameter.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"maxlength is ignored if status is CS_INPUTVALUE or if 
datatype represents a fixed-length type.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"status COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_INPUTVALUE, CS_UPDATECOL, or CS_RETURN. COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_UPDATECOL indicates an update column for a cursor 
declare command.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_RETURN indicates a return parameter.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"locale COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to a valid CS_LOCALE structure or NULL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"All other fieldsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Are ignored.ID="IN4415832046"Descriptor areasetting the number of parameters or columnsSetting the Number of Parameters or ColumnsMARK="BULL" REMAP="BU--Bullet"To set the number of parameters or columns a descriptor can describe, an application calls MOREINFO="NONE"ct_dyndesc with operation as CS_SETCNT.The following table lists parameter values for CS_SETCNT operations:TOCENTRY="1"LBL="Table 3-64: "Parameter values for CS_SETCNT operationsCOLS="6" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="136*"COLNAME="C2" COLWIDTH="117*"COLNAME="C3" COLWIDTH="46*"COLNAME="C4" COLWIDTH="72*"COLNAME="C5" COLWIDTH="43*"COLNAME="C6" COLWIDTH="51*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"descriptor,
desclen:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"index:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"datafmt
:COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"buffer, 
buflen:COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"copied
:COLNAME="C6" ALIGN="LEFT" ROTATE="0" MOREROWS="0"indicator
:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The name of the descriptor 
to allocate,the length of the name or 
CS_NULLTERM.COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The new descriptor 
count.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULL,
CS_UNUSEDCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C6" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLID="IN4415832047"Descriptor areaassociating with a statement or command structureAssociating a Descriptor with a Statement or Command StructureMARK="BULL" REMAP="BU--Bullet"To associate a descriptor with a prepared statement or command structure, an application calls MOREINFO="NONE"ct_dyndesc with operation as CS_USE_DESC.The following table lists parameter values for CS_USE_DESC operations:TOCENTRY="1"LBL="Table 3-65: "Parameter Values for CS_USE_DESC operationsCOLS="6" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="183*"COLNAME="C2" COLWIDTH="72*"COLNAME="C3" COLWIDTH="46*"COLNAME="C4" COLWIDTH="72*"COLNAME="C5" COLWIDTH="43*"COLNAME="C6" COLWIDTH="51*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"descriptor,
desclen:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"index:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"datafmt
:COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"buffer, 
buflen:COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"copied
:COLNAME="C6" ALIGN="LEFT" ROTATE="0" MOREROWS="0"indicator
:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The name of the descriptor to allocate,the length of the name or CS_NULLTERM.COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_UNUSEDCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULL,
CS_UNUSEDCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C6" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLDescriptor areas are normally associated with a context structure. When a descriptor area is used to describe input to or output from a cursor, however, it must first be associated with the command structure which opened the cursor. When using a descriptor to describe cursor input, a typical application's sequence of calls is:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"ct_dyndesc(CS_ALLOC)ct_dyndesc(CS_SETCNT)for each input value:    ct_dyndesc(CS_SETATTR)end forct_cursor to open the cursorct_dyndesc(CS_USE_DESC)ct_sendSee AlsoREMAP="BO--Body"LINKEND="X36007"ct_cursor
, LINKEND="X77746"ct_dynamic
, LINKEND="X65123"ct_fetch
ID="IN4410802349"ct_dyndesc
ID="IN447772650"ct_exitID="X58559"ct_exitID="IN457772752"ExitingClient-Library
ID="IN4514772753"Client-Libraryexiting
Exit Client-Library. REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_exit(context, option) CS_CONTEXT    *context;CS_INT        option;ParametersREMAP="RI--RefIndent"context - A pointer to a CS_CONTEXT structure.context identifies the Client-Library context being exited.option - MOREINFO="NONE"ct_exit can behave in different ways, depending on the value specified for option. The following table lists the symbolic values that are legal for option:TOCENTRY="1"LBL="Table 3-66: "Values for option (MOREINFO="NONE"ct_exit)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="106*"COLNAME="C2" COLWIDTH="253*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Value of option:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Behavior of MOREINFO="NONE"ct_exit:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_UNUSEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_exit closes all open connections for which no results 
are pending and terminates Client-Library for this 
context. If results are pending on one or more 
connections, MOREINFO="NONE"ct_exit returns CS_FAIL and does not 
terminate Client-Library.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FORCE_EXITCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_exit closes all open connections for this context, 
whether or not any results are pending, and terminates 
Client-Library for this context.ReturnsREMAP="BO--Body"TOCENTRY="1"LBL="Table 3-67: "Return values (MOREINFO="NONE"ct_exit)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="106*"COLNAME="C2" COLWIDTH="253*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine completed successfully.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed.CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"ct_exitID="IN4511772758"Connectionsclosing
terminates Client-Library for a specific context. It closes all open connections, de-allocates internal data space and cleans up any platform-specific initialization.ID="IN457752959"ct_exitwhen to use
MOREINFO="NONE"ct_exit must be the last Client-Library routine called within an Client-Library context. If an application finds it needs to call Client-Library routines after it has called MOREINFO="NONE"ct_exitID="IN4514752960"Client-Libraryre-initializing
, it can re-initialize Client-Library by calling MOREINFO="NONE"ct_init again. ID="IN457733161"ct_exitreason for failureIf results are pending on any of the context's connections and option is not passed as CS_FORCE_EXIT, MOREINFO="NONE"ct_exit returns CS_FAIL. This means that Client-Library is not correctly terminated and that the application must call MOREINFO="NONE"ct_exit again after handling the connections' pending results.MOREINFO="NONE"ct_exit always completes synchronously, even if asynchronous network I/O has been specified for any of the context's connections.An application can call MOREINFO="NONE"ct_close to close a single connection.If MOREINFO="NONE"ct_init is called for a context, it is an error to de-allocate the context before calling MOREINFO="NONE"ct_exitExampleREMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/*** ex_ctx_cleanup()**** Parameters:**  context  Pointer to context structure.**  status   Status of last interaction with Client-**           Library.**           If not ok, this routine will perform a**           force exit.**** Returns:** Result of function calls from Client-Library.*/REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"CS_RETCODE CS_PUBLICex_ctx_cleanup(context, status)CS_CONTEXT*    context;CS_RETCODE  status;{     CS_RETCODE  retcode;     CS_INT      exit_option;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     exit_option = (status != CS_SUCCEED) ? CS_FORCE_EXIT :          CS_UNUSED;     retcode = ct_exit(context, exit_option);     if (retcode != CS_SUCCEED)     {         ex_error("ex_ctx_cleanup: ct_exit() failed");         return retcode;     }     retcode = cs_ctx_drop(context);     if (retcode != CS_SUCCEED)     {          ex_error("ex_ctx_cleanup: cs_ctx_drop() failed");          return retcode;     }     return retcode;}REMAP="BO--Body"This code excerpt is from the exutils.c example program. For another example of using MOREINFO="NONE"ct_exit, see the ex_amain.c example program.See AlsoREMAP="BO--Body"LINKEND="X98839"ct_close
, LINKEND="X55618"ct_init
ID="IN457683665"ct_exit
ID="IN458653966"ct_fetchID="X65123"ct_fetchID="IN468654068"Fetchingresult data
ID="IN467654069"Resultsfetching
Fetch result data. REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_fetch(cmd, type, offset, option,                 rows_read) CS_COMMAND       *cmd;CS_INT           type;CS_INT           offset;CS_INT           option;CS_INT           *rows_read;ParametersREMAP="RI--RefIndent"cmd - A pointer to the CS_COMMAND structure managing a client/ server operation. type - This parameter is currently unused and must be passed as CS_UNUSED in order to ensure compatibility with future versions of Client-Library.offset -This parameter is currently unused and must be passed as CS_UNUSED in order to ensure compatibility with future versions of Client-Library.option - This parameter is currently unused and must be passed as CS_UNUSED in order to ensure compatibility with future versions of Client-Library.rows_read - A pointer to an integer variable. MOREINFO="NONE"ct_fetch sets rows_read to the number of rows read by the MOREINFO="NONE"ct_fetch call.REMAP="UN--Under"rows_read is an optional parameter intended for use by applications using array binding.ReturnsTOCENTRY="1"LBL="Table 3-68: "Return values (MOREINFO="NONE"ct_fetch)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="106*"COLNAME="C2" COLWIDTH="253*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine completed successfully
MOREINFO="NONE"
ct_fetch places the number of rows read in *MOREINFO="NONE"rows_read.

The application must continue to call MOREINFO="NONE"ct_fetch, as the 
result data is not yet completely fetched.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_END_DATACOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"All rows of the current result set have been fetched. 

The application should call MOREINFO="NONE"ct_results to get the next 
result set.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_ROW_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A recoverable error occurred while fetching a row.

Recoverable errors include memory allocation failures 
and conversion errors that occur while copying row 
values to program variables.

An application can continue calling MOREINFO="NONE"ct_fetch to keep 
retrieving rows, or can call MOREINFO="NONE"ct_cancel to cancel the 
remaining results.
MOREINFO="NONE"
ct_fetch places the number of rows fetched in 
*MOREINFO="NONE"rows_read. This number includes the row on which the 
error occurred.

The application must continue to call MOREINFO="NONE"ct_fetch, as the 
result data is not yet completely fetched.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed.
MOREINFO="NONE"
ct_fetch places the number of rows fetched in 
*MOREINFO="NONE"rows_read. This number includes the failed row. 

Unless the routine failed due to application error (for 
example, bad parameters), additional result rows are 
not available.

If MOREINFO="NONE"ct_fetch returns CS_FAIL, an application must call 
MOREINFO="NONE"ct_cancel with type as CS_CANCEL_ALL before using 
the affected command structure to send another 
command. 

If MOREINFO="NONE"ct_cancel returns CS_FAIL, the application must call 
MOREINFO="NONE"cs_close(CS_FORCE_CLOSE) to force the connection 
closed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CANCELEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The current result set and any additional result sets 
have been canceled. Data is no longer available.
MOREINFO="NONE"
ct_fetch places the number of rows fetched before the 
cancel occurred in *MOREINFO="NONE"rows_read.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_PENDINGCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Asynchronous network I/O is in effect. For more 
information, see the MOREINFO="NONE"Asynchronous MOREINFO="NONE"Programming topics 
page.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BUSYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An asynchronous operation is already pending for this 
connection. For more information, see the 
MOREINFO="NONE"Asynchronous Programming topics page.ID="IN468634273"ct_fetchreason for failureREMAP="BO--Body"A common reason for a MOREINFO="NONE"ct_fetch failure is that a program variable specified via MOREINFO="NONE"ct_bind is not large enough for a fetched data item.MARK="BULL" REMAP="BU--Bullet""Result data" is an umbrella term for all the types of data that a server can return to an application. These types of data include:MARK="DASH" REMAP="BS--BulletSub"Regular rows.Cursor rows.Return parameters. Types of data that are returned as parameters include message parameters, stored procedure return parameters, extended error data, and registered procedure notification parameters.Stored procedure status numbers. Compute rows. REMAP="UN--Under"MOREINFO="NONE"ct_fetch is used to fetch all of these types of data. ID="IN467634276"Resultsdefinition ofConceptually, result data is returned to an application in the form of one or more rows that make up a "result set". REMAP="UN--Under"Regular row and cursor row result sets can contain more than one row. For example, a regular row result set might contain a hundred rows.REMAP="UN--Under"If array binding has been specified for the data items in a regular row or cursor row result set, then multiple rows can be fetched with a single call to MOREINFO="NONE"ct_fetch.ID="IN4624634277"Asynchronous programmingfetching rows
ID="IN468614478"ct_fetchasynchronous programmingAsynchronous applications should always specify array binding to fetch multiple rows at a time. This ensures that the application has sufficient time in which to accomplish something before Client-Library calls the application's completion callback routine.REMAP="UN--Under"Return parameter, status number, and compute row result sets, however, only contain a single "row." For this reason, even if array binding is specified, only a single row of data is fetched.MOREINFO="NONE"ct_results sets *result_type to indicate the type of result available. MOREINFO="NONE"ct_resultsID="IN467614479"Resultstypes of
must indicate a result type ofID="IN467594680"ResultsCS_ROW_RESULT
ID="IN4625574881"CS_ROW_RESULT result type
ID="IN467555082"ResultsCS_CURSOR_RESULT
ID="IN4628535283"CS_CURSOR_RESULT result type
ID="IN467515484"ResultsCS_PARAM_RESULT
ID="IN4627495685"CS_PARAM_RESULT result type
ID="IN467475886"ResultsCS_STATUS_RESULT
ID="IN4628456087"CS_STATUS_RESULT result type
CS_ROW_RESULT, CS_CURSOR_RESULT, CS_PARAM_RESULT, CS_STATUS_RESULT, orID="IN467436288"ResultsCS_COMPUTE_RESULT
ID="IN4629416489"CS_COMPUTE_RESULT result type
CS_COMPUTE_RESULT before an application calls MOREINFO="NONE"ct_fetch.After calling MOREINFO="NONE"ct_results, an application can: MARK="DASH" REMAP="BS--BulletSub"Process the result set by binding the result items and fetching the data. (A typical application will call MOREINFO="NONE"ct_describe to get data descriptions, MOREINFO="NONE"ct_bind to bind result items, MOREINFO="NONE"ct_fetch to fetch result rows, and MOREINFO="NONE"ct_get_data, if the result set contains large text or image values. However, an application can also use MOREINFO="NONE"ct_fetch and MOREINFO="NONE"ct_dyndesc to process a result set.)Discard the result set, using MOREINFO="NONE"ct_cancel. ID="IN467396690"Resultsprocessing with ct_fetchIf an application does not cancel a result set, it must completely process the result set by calling MOREINFO="NONE"ct_fetch as long as MOREINFO="NONE"ct_fetch continues to indicate that rows are available.REMAP="UN--Under"The simplest way to do this is in a loop that terminates when MOREINFO="NONE"ct_fetch fails to return either CS_SUCCEED or CS_ROW_FAIL. After the loop terminates, an application can use a switch-type statement against MOREINFO="NONE"ct_fetch's final return code to find out what caused the termination.REMAP="UN--Under"If a result set contains zero rows, an application's first MOREINFO="NONE"ct_fetch call will return CS_END_DATA.An application must call MOREINFO="NONE"ct_fetch in a loop even if a result set contains only a single row. An application must call MOREINFO="NONE"ct_fetch until it fails to return either CS_SUCCEED or CS_ROW_FAIL. ID="IN467396691"Resultsconversion error during retrievalIf a conversion error occurs when retrieving a result item, the rest of the items in the row are retrieved. If truncation occurs, the indicator variable, if any, provided in the application's MOREINFO="NONE"ct_bind call for this item is set to the actual length of the result data.REMAP="UN--Under"MOREINFO="NONE"ct_fetch returns CS_ROW_FAIL if a conversion or truncation error occurs.ID="IN468396692"Fetchingregular rows
ID="IN4619396693"Regular row resultsfetching
ID="IN468396694"Fetchingcursor rows
ID="IN4618396695"Cursor row resultsfetchingFetching Regular Rows and Cursor RowsMARK="BULL" REMAP="BU--Bullet"Regular rows and cursor rows can be fetched one row at a time, or several rows at once. An application indicates the number of rows to be fetched per MOREINFO="NONE"ct_fetch call via the datafmtname='rArrow' font='symbol' code='174'  charset='fontspecific'count field in its MOREINFO="NONE"ct_bind calls that bind result columns to program variables. If datafmtname='rArrow' font='symbol' code='174'  charset='fontspecific'count is 0 or 1, each call to MOREINFO="NONE"ct_fetch fetches one row. If datafmtname='rArrow' font='symbol' code='174'  charset='fontspecific'count is greater than one, then array binding is considered to be in effect and each call to MOREINFO="NONE"ct_fetch fetches datafmtname='rArrow' font='symbol' code='174'  charset='fontspecific'count rows. (Note that datafmtname='rArrow' font='symbol' code='174'  charset='fontspecific'
count must have the same value for all MOREINFO="NONE"ct_bind calls for a result set.)When fetching multiple rows, if a conversion error occurs on one of the rows, no more rows are retrieved by this MOREINFO="NONE"ct_fetch call.ID="IN468396696"Fetchingreturn parameters
ID="IN4617396697"Return parametersfetchingFetching Return ParametersMARK="BULL" REMAP="BU--Bullet"Several types of data can be returned to an application as a parameter result set, including:ID="IN4617396698"Stored proceduresfetching return parametersMARK="DASH" REMAP="BS--BulletSub"Stored procedure return parametersID="IN4618396699"Message parametersfetchingMessage parametersExtended error data and registered procedure notification parameters are also returned as parameter result sets, but since an application does not call MOREINFO="NONE"ct_results to process these types of data, the application never sees a result type of CS_PARAM_RESULT. Instead, the row of parameters is simply available to be fetched after the application retrieves the CS_COMMAND structure containing the data.A return parameter result set consists of a single row with a number of columns equal to the number of return parameters. ID="IN4683966100"Fetchingreturn status
ID="IN46133966101"Return statusfetchingFetching a Return StatusMARK="BULL" REMAP="BU--Bullet"A stored procedure return status result set consists of a single row with a single column, the status number. ID="IN4683966102"Fetchingcompute rows
ID="IN46153966103"Compute resultsfetchingFetching Compute RowsMARK="BULL" REMAP="BU--Bullet"Compute rows result from the MOREINFO="NONE"compute clause of a MOREINFO="NONE"select statement. A compute row result set consists of a single row with a number of columns equal to the number of aggregate operators in the MOREINFO="NONE"compute clause that generated the row. Each compute row is considered to be a distinct result set.ID="IN4683768104"ct_fetchcode exampleExampleREMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/* ex_fetch_data()*/REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"CS_RETCODE CS_PUBLICex_fetch_data(cmd)CS_COMMAND  *cmd;{      CS_RETCODE    retcode;      CS_INT     num_cols;      CS_INT     i;      CS_INT     j;      CS_INT     row_count = 0;      CS_INT     rows_read;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /*     ** Determine the number of columns in this      ** result set.     */     ...CODE DELETED.....REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /* Get column descriptions and bind columns */     ...CODE DELETED.....REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /*     ** Fetch the rows.  Loop while ct_fetch() returns     ** CS_SUCCEED or CS_ROW_FAIL     */     while (((retcode = ct_fetch(cmd, CS_UNUSED,         CS_UNUSED, CS_UNUSED,&rows_read)) ==         CS_SUCCEED) || (retcode == CS_ROW_FAIL))     {         /*         ** Increment our row count by the number of         ** rows just fetched.         */         row_count = row_count + rows_read;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"         /* Check if we hit a recoverable error */        if (retcode == CS_ROW_FAIL)        {             fprintf(stdout, "Error on row %d.\n",                row_count);         }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"              /*             ** We have a row.  Loop through the columns             ** displaying the column values.             */            for (i = 0; i < num_cols; i++)            {                ...CODE DELETED.....            }              fprintf(stdout, "\n");    }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /* Free allocated space */    ...CODE DELETED.....REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /*     ** We're done processing rows.  Let's check the      ** final return value of ct_fetch().     */     switch ((int)retcode)     {          case CS_END_DATA:               /* Everything went fine */               fprintf(stdout, "All done processing                    rows.\n");              retcode = CS_SUCCEED;          break;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"          case CS_FAIL:               /* Something terrible happened */             ex_error("ex_fetch_data: ct_fetch()                    failed");               return retcode;               break;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"          default:               /* We got an unexpected return value */               ex_error("ex_fetch_data: ct_fetch() \                     returned an unexpected retcode");              return retcode;               break;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     return retcode;}REMAP="BO--Body"This code excerpt is from the exutils.c example program. For further examples of using MOREINFO="NONE"ct_fetch, see the compute.c, ex_alib.c,getsend.c, and i18n.c example programs.See AlsoREMAP="BO--Body"LINKEND="X29013"ct_bind
, LINKEND="X64204"ct_describe
, LINKEND="X26819"ct_get_data
, LINKEND="X57817"ct_results
, LINKEND="X50078"Cursors
, LINKEND="X51426"Results
ID="IN4683471107"ct_fetchID="X26819"ct_get_dataID="IN43219753"Read data from server
ID="IN4349574"Datareading data from a server via ct_get_data
ID="IN4379575"Serversreading data from a server
Read a chunk of data from the server.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_get_data(cmd, item, buffer,              buflen, outlen)REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_COMMAND    *cmd;CS_INT        item;CS_VOID       *buffer;CS_INT        buflen;CS_INT        *outlen;ParametersREMAP="RI--RefIndent"cmd - A pointer to the CS_COMMAND structure managing a client/ server operation. item - An integer representing the data item of interest. When using MOREINFO="NONE"ct_get_data to retrieve data for more than one item in a result set, item can be incremented only; that is, an application cannot retrieve data for item number 3 after it has retrieved data for item number 4.REMAP="UN--Under"When retrieving a column, item is the column's column number. The first column in a MOREINFO="NONE"select statement's select-list is column number 1, the second number 2, and so forth.REMAP="UN--Under"When retrieving a compute column, item is the column number of the compute column. Compute columns are returned in the order in which they are listed in the compute clause. The first column returned is number 1.REMAP="UN--Under"When retrieving a return parameter, item is the parameter number of the parameter. The first parameter returned by a stored procedure is number 1. Stored procedure return parameters are returned in the same order as the parameters were originally specified in the stored procedure's MOREINFO="NONE"create procedure statement. This is not necessarily the same order as specified in the RPC command that invoked the stored procedure. In determining what number to pass as item do not count non-return parameters. For example, if the second parameter in a stored procedure is the only return parameter, pass item as 1. REMAP="UN--Under"When retrieving a stored procedure return status, item must be 1, as there can be only a single status in a return status result set.ID="IN4379578"Columnsretrieving a columnID="IN43109579"RetrievingcolumnsID="IN431595710"Compute columnsretrieving a compute columnID="IN431095711"Retrievingcompute columnsID="IN431095712"Retrievingreturn parametersID="IN431795713"Return parametersretrieving return parametersID="IN431795714"Stored proceduresretrieving return statusID="IN431395715"Return statusretrieving a stored procedure return statusbuffer - A pointer to data space. MOREINFO="NONE"ct_get_data fills *buffer with a buflen-sized chunk of the column's value. REMAP="UN--Under"buffer cannot be NULL.buflen - The length, in bytes, of *buffer.REMAP="UN--Under"If buflen is 0, MOREINFO="NONE"ct_get_data updates the I/O descriptor for the item without retrieving any data.REMAP="UN--Under"buflen is required even for fixed-length buffers, and cannot be CS_UNUSED.outlen - A pointer to an integer variable. REMAP="UN--Under"If outlen is supplied,MOREINFO="NONE" ct_get_data sets *outlen to the number of bytes placed in *buffer.ReturnsREMAP="BO--Body"TOCENTRY="1"LBL="Table 3-69: "Return values (MOREINFO="NONE"ct_get_data)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="106*"COLNAME="C2" COLWIDTH="253*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_get_data successfully retrieved a chunk of data that 
is not the last chunk of data for this column.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed.

Unless the routine failed due to application error (for 
example, bad parameters), additional result data is not 
available.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_END_ITEMCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_get_data successfully retrieved the last chunk of 
data for this column. This is not the last column in the 
row.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_END_DATACOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_get_data successfully retrieved the last chunk of 
data for this column. This is the last column in the row.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CANCELEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The operation was canceled. Data for this result set is 
no longer available.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_PENDINGCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Asynchronous network I/O is in effect. See the 
MOREINFO="NONE"Asynchronous MOREINFO="NONE"Programming topics page for more 
information.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BUSYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An asynchronous operation is already pending for this 
connection. For more information, see the 
MOREINFO="NONE"Asynchronous Programming topics page.CommentsMARK="BULL" REMAP="BU--Bullet"An application typically calls MOREINFO="NONE"ct_get_dataID="IN431493918"Text and imageretrieving large values with ct_get_data
in a loop to retrieve large text or image values, although it can be used on columns of any datatype. Each call to MOREINFO="NONE"ct_get_data retrieves a buflen-sized chunk of data.For information on the steps involved in using MOREINFO="NONE"ct_get_data to retrieve a text or image value, see LINKEND="X53057""Using ct_get_data to Fetch Text and Image Values" 
.ID="IN4311911119"ct_get_datano conversion performed
MOREINFO="NONE"ct_get_data retrieves data exactly as it is sent by the server. No conversion is performed. For this reason, care must be taken when interpreting data contained in *buffer. In particular, CS_CHAR data may not be null-terminated and multi-byte character strings may be broken within a byte sequence defining a single character.ID="IN4311891320"ct_get_datawhen to useAn application calls MOREINFO="NONE"ct_get_data after calling MOREINFO="NONE"ct_fetch to fetch the row of interest. If array binding was indicated in an earlier call to MOREINFO="NONE"ct_bind, the application cannot use MOREINFO="NONE"ct_get_data.Only those columns following the last bound column are available to MOREINFO="NONE"ct_get_dataID="IN4311871521"ct_get_datadata can be discarded
. Data in unbound columns that precede bound columns is discarded. For example, if an application selects columns number 1 through 4 and binds columns number 1 and 3, the application cannot use MOREINFO="NONE"ct_get_data to retrieve the data for column 2, but can use MOREINFO="NONE"ct_get_data to retrieve the data for column 4.Once data has been retrieved for a column, it is no longer available.ID="IN4314871522"Text and imagereading data for later updateIf an application reads a text or image column that it will need to update at a later time, it needs to retrieve an I/O descriptor for the column. To do this, an application can call MOREINFO="NONE"ct_data_info after calling MOREINFO="NONE"ct_get_data for the column.An application cannot retrieve an I/O descriptor for a column before it has called MOREINFO="NONE"ct_get_data for the column. However, this MOREINFO="NONE"ct_get_data call does not have to actually retrieve any data. That is, an application can call MOREINFO="NONE"ct_get_data with a buflen of 0, and then call MOREINFO="NONE"ct_data_infoID="IN4314871523"Text and imagedetermining length of value before retrieving it
to retrieve the descriptor. This technique is useful when an application needs to determine the length of a text or image value before retrieving it.For more information on how to use MOREINFO="NONE"ct_get_data, see LINKEND="X51184""Text and Image" 
.ID="IN4311851724"ct_get_datacode exampleExampleREMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/*** FetchResults()**** The result set contains four columns: integer, text, ** float, and integer.*/REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"CS_STATIC CS_RETCODEFetchResults(cmd, textdata)CS_COMMAND   *cmd;TEXT_DATA    *textdata;{     CS_RETCODE   retcode;    CS_DATAFMT   fmt;     CS_INT       firstcol;     CS_TEXT      *txtptr;     CS_FLOAT     floatitem;    CS_INT       count;    CS_INT       len;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /*     ** All binds must be of columns prior to the columns     ** to be retrieved by ct_get_data().     ** To demonstrate this, bind the first column returned.     */      ...CODE DELETED.....REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /* Retrieve and display the results */     while(((retcode = ct_fetch(cmd, CS_UNUSED, CS_UNUSED,         CS_UNUSED,&count)) == CS_SUCCEED) ||          (retcode == CS_ROW_FAIL) )        {         /* Check for a recoverable error */          ...CODE DELETED.....REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"        /*        ** Get the text data item in the second column.         ** Loop until we have all the data for this item.         ** The text used for this example could be          ** retrieved in one ct_get_data call, but data         ** could be too large for this to be the case.        ** Instead, the data would have to be retrieved          ** in chunks. This example will retrieve the text          ** in 5 byte increments to demonstrate retrieving         ** data items in chunks.         */         txtptr = textdata->textbuf;        textdata->textlen = 0;         do        {            retcode = ct_get_data(cmd, 2, txtptr, 5,                 &len);            textdata->textlen += len;              /*             ** Protect against overflowing the string               ** buffer.             */              if ((textdata->textlen + 5) > (EX_MAX_TEXT -                 1))             {                  break;             }              txtptr += len;        } while (retcode == CS_SUCCEED);REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"         if (retcode != CS_END_ITEM)        {             ex_error("FetchResults: ct_get_data()                  failed");             return retcode;         }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"           /*              ** Retrieve the descriptor of the text data. It is              ** available while retrieving results of a select            ** query. The information will be needed for             ** later updates.             */            ...CODE DELETED....REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"           /* Get the float data item in the 3rd column */             retcode = ct_get_data(cmd, 3, &floatitem,                 sizeof (floatitem), &len);             if (retcode != CS_END_ITEM)             {                    ex_error("FetchResults: ct_get_data()                        failed");                   return(retcode);             }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"           /*           ** When using ct_get_data to process results, it is            ** not required to get all the columns in the row.              ** To illustratethis, the last column of the result           ** set is not retrieved.             */     }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /*     ** We're done processing rows. Check the     ** final return value of ct_fetch().     */    ...CODE DELETED.....REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     return retcode;}REMAP="BO--Body"This code excerpt is from the getsend.c example program.See AlsoREMAP="BO--Body"LINKEND="X29013"ct_bind
MOREINFO="NONE", LINKEND="X75519"ct_data_info
MOREINFO="NONE", LINKEND="X65123"ct_fetch
MOREINFO="NONE", LINKEND="X27057"ct_send_data
MOREINFO="NONE", LINKEND="X51184"Text and Image
ID="IN4311822027"ct_get_data
ID="IN4312792328"ct_getformatct_getformatID="IN4410792430"Retrievinguser-defined formats of result columns
ID="IN4420792431"User-defined formatsretrieving
ID="IN4414792432"Format resultsreturning a columnÕ s user-defined format string
ID="IN447792433"Resultsreturning a columnÕ s user-defined format string
Return the server user-defined format string associated with a result column.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_getformat (cmd, colnum, buffer, buflen,outlen CS_COMMAND       *cmd;CS_INT           colnum;CS_VOID          *buffer;CS_INT           buflen;CS_INT           *outlen;ParametersREMAP="RI--RefIndent"cmd - A pointer to the CS_COMMAND structure managing a client/ server operation.colnum - The number of the column whose user-defined format is desired. The first column in a MOREINFO="NONE"select statement's select-list is column number 1, the second number 2, and so forth.buffer - A pointer to the space in which MOREINFO="NONE"ct_getformat will place a null-terminated format string. buflen - The length, in bytes, of the *buffer data space. outlen - A pointer to an integer variable. REMAP="UN--Under"If outlen is supplied,MOREINFO="NONE" ct_getformat sets *outlen to the length, in bytes, of the format string. This length includes the null terminator.REMAP="UN--Under"If the format string is larger than buflen bytes, an application can use the value of *outlen to determine how many bytes are needed to hold the string. REMAP="UN--Under"If no format string is associated with the column identified by colnum, MOREINFO="NONE"ct_getformat sets *outlen to 1 (for the null terminator).ReturnsTOCENTRY="1"LBL="Table 3-70: "Return values (MOREINFO="NONE"ct_getformat)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="106*"COLNAME="C2" COLWIDTH="253*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine completed successfully.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BUSYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An asynchronous operation is already pending for this 
connection. For more information, see the 
MOREINFO="NONE"Asynchronous Programming topics page.CommentsID="IN4412772638"ct_getformatwhen to useMARK="BULL" REMAP="BU--Bullet"An application can call MOREINFO="NONE"ct_getformat after MOREINFO="NONE"ct_results indicates results of type CS_ROW_RESULT.If no format string is associated with the column identified by colnum, MOREINFO="NONE"ct_getformat sets *outlen to 1.Typical applications will not use MOREINFO="NONE"ct_getformatID="IN4420772639"Gateway applicationsreturning a columnÕ s user-defined format string
, which is provided primarily for gateway applications support.See AlsoREMAP="BO--Body"LINKEND="X29013"ct_bind
, LINKEND="X64204"ct_describe
ID="IN4412742941"ct_getformat
ID="IN4413713242"ct_getloginfoID="X32025"ct_getloginfoID="IN453713344"TDStransferring login response information
ID="IN4526713345"Login response informationtransferring
Transfer TDS login response information from a CS_CONNECTION structure to a newly-allocated CS_LOGINFO structure.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_getloginfo (connection, logptr) CS_CONNECTION    *connection;CS_LOGINFO       **logptr;ParametersREMAP="RI--RefIndent"connection - A pointer to a CS_CONNECTION structure. A CS_CONNECTION structure contains information about a particular client/ server connection.logptr - A pointer to a program variable which MOREINFO="NONE"ct_getloginfo sets to the address of a newly-allocated CS_LOGINFO structure.ReturnsTOCENTRY="1"LBL="Table 3-71: "Return values (MOREINFO="NONE"ct_getloginfo)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="106*"COLNAME="C2" COLWIDTH="253*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine completed successfully.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BUSYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An asynchronous operation is already pending for this 
connection. For more information, see the 
MOREINFO="NONE"Asynchronous Programming topics page.CommentsMARK="BULL" REMAP="BU--Bullet"TDS (Tabular Data Stream) is a communications protocol used for the transfer of requests and request results between clients and servers.ID="IN4513693550"ct_getloginfowhen to useThere are two reasons an application might call MOREINFO="NONE"ct_getloginfo:MARK="DASH" REMAP="BS--BulletSub"If it is an Open Server gateway application using TDS pass-through.In order to copy login properties from an open connection to a newly-allocated connection structure.ID="IN4513673751"ct_getloginfowhen not to useDo not call MOREINFO="NONE"ct_getloginfo from within a completion callback routine. MOREINFO="NONE"ct_getloginfo calls system-level memory functions which may not be re-entrant.ID="IN453673752"TDSpass-through operationTDS Pass-ThroughID="IN4520673753"Gateway applicationsGateway applicationsand TDS pass-throughTDS pass-throughMARK="BULL" REMAP="BU--Bullet"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 pass-through, the gateway 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"ct_getloginfoID="IN453673754"TDSnegotiating a TDS format
is the third of four calls, two of them Server Library calls, that allow a client and a remote server to negotiate a TDS format. The calls, which can only be made in an Open Server SRV_CONNECT event handler, are:NUMERATION="ARABIC" REMAP="S1--StepOne" CONTINUATION="RESTARTS" INHERITNUM="IGNORE"MOREINFO="NONE"srv_getloginfo to allocate a CS_LOGINFO structure and fill it with TDS information from a client login request.MOREINFO="NONE"ct_setloginfo to transfer the TDS information retrieved in step 1 from the CS_LOGINFO structure to a Client-Library CS_CONNECTION structure. The gateway uses this CS_CONNECTION structure in the MOREINFO="NONE"ct_connect call which establishes its connection with the remote server.MOREINFO="NONE"ct_getloginfo to transfer the remote server's response to the client's TDS information from the CS_CONNECTION structure into a newly-allocated CS_LOGINFO structure.MOREINFO="NONE"srv_setloginfo to send the remote server's response, retrieved in step 3, to the client.ID="IN4516673755"Login propertiescopying to new connectionCopying Login PropertiesREMAP="BO--Body"For information on using MOREINFO="NONE"ct_getloginfo to copy login properties from an open connection to a newly-allocated connection structure, see the MOREINFO="NONE"Properties topics page.See AlsoREMAP="BO--Body"LINKEND="X81597"ct_recvpassthru
MOREINFO="NONE", LINKEND="X54893"ct_sendpassthru
MOREINFO="NONE", LINKEND="X72103"ct_setloginfo
ID="IN4513644057"ct_getloginfo
ID="IN457614358"ct_initID="X55618"ct_initID="IN4627614460"Initializing Client-Library
ID="IN4614614461"Client-Libraryinitializing
Initialize Client-Library for an application context. REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_init(context, version) CS_CONTEXT    *context;CS_INT        version;ParametersREMAP="RI--RefIndent"context - A pointer to a CS_CONTEXT structure. An application must have previously allocated this context structure by calling the CS-Library routine MOREINFO="NONE"cs_ctx_alloc.REMAP="UN--Under"context identifies the Client-Library context being initialized.version - The version of Client-Library behavior that the application expects. The following table lists the symbolic values that are legal for version:TOCENTRY="1"LBL="Table 3-72: "Values for version (MOREINFO="NONE"ct_init)COLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="106*"COLNAME="C2" COLWIDTH="91*"COLNAME="C3" COLWIDTH="162*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Value of MOREINFO="NONE"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"CS_VERSION_100COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"10.0 behavior.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Cursors, registered procedures, 
remote procedure calls.

This is the initial version of 
Client-Library.ReturnsREMAP="BO--Body"TOCENTRY="1"LBL="Table 3-73: "Return values (MOREINFO="NONE"ct_init)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"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine completed successfully.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_MEM_ERRORCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed due to a memory allocation error.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed for other reasons.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_init returns CS_FAIL if Client-Library cannot 
provide version-level behavior.REMAP="BO--Body"A MOREINFO="NONE"ct_init failure does not typically make *context unusable. Instead of dropping the context structure, an application can try calling MOREINFO="NONE"ct_init again with the same context pointer.CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"ct_initID="IN467614466"VersionClient-Library
ID="IN4614614467"Client-Libraryversion
sets up internal control structures and defines the version of Client-Library behavior that the application expects. ID="IN467594668"ct_initwhen to call it
MOREINFO="NONE"ct_init must be the first Client-Library routine called in a Client-Library application context. Other Client-Library routines will fail if they are called before MOREINFO="NONE"ct_init. A Client-Library application can call CS-Library routines before calling MOREINFO="NONE"ct_init (and in fact must call the CS-Library routine MOREINFO="NONE"cs_ctx_allocID="IN467574869"ct_initwhat to do before calling it
before calling MOREINFO="NONE"ct_init).If MOREINFO="NONE"ct_init returns CS_SUCCEED, Client-Library will provide the requested behavior, regardless of the actual version of Client-Library in use. If Client-Library cannot provide the requested behavior, MOREINFO="NONE"ct_init returns CS_FAILID="IN4614574870"Client-Librarybackward-compatibility
. Generally speaking, higher-level versions of Client-Library can provide lower-level behavior, but lower versions cannot provide higher-level behavior. Because an application callsMOREINFO="NONE" ct_init before it sets up error handling, an application must check MOREINFO="NONE"ct_init's return code to detect failure. ID="IN467555071"ct_initcalling multiple timesIt is not an error for an application to call MOREINFO="NONE"ct_init multiple times for the same context. If this occurs, only the first call has any effect. Client-Library provides this functionality because some applications cannot guarantee which of several modules will execute first. In such a case, each module needs to contain a call to MOREINFO="NONE"ct_init. versionID="IN467535272"Versiondetermining the value of the CS_VERSION property
is the version of Client-Library behavior that the application expects. version determines the value of the context's ID="IN4619515473"CS_VERSION propertydetermining its value
CS_VERSION property. Connections allocated within a context use default CS_TDS_VERSION values based on their parent context's CS_VERSION level.ID="IN467495674"ct_initcode exampleExampleREMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/*** ex_init()** EX_CTLIB_VERSION is defined in the examples header file ** as CS_VERSION_100.                */REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"CS_RETCODE CS_PUBLICex_init(context)CS_CONTEXT  **context;{     CS_RETCODE   retcode;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /* Get a context handle to use */     retcode = cs_ctx_alloc(EX_CTLIB_VERSION, context);     if (retcode != CS_SUCCEED)     {         ...CODE DELETED.....     }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /* Initialize Open Client */     retcode = ct_init(*context, EX_CTLIB_VERSION);     if (retcode != CS_SUCCEED)     {         ex_error("ex_init: ct_init() failed");         cs_ctx_drop(*context);         *context = NULL;         return retcode;     }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"#ifdef EX_API_DEBUG     ...CODE DELETED.....#endifREMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /* Install client and server message handlers */     ...CODE DELETED.....REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /* Call ct_config to set context properties */     ...CODE DELETED.....REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     if (retcode != CS_SUCCEED)     {         ct_exit(*context, CS_FORCE_EXIT);         cs_ctx_drop(*context);         *context = NULL;    }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     return retcode;}REMAP="BO--Body"This code excerpt is from the exutils.c example program. For another example of using MOREINFO="NONE"ct_init, see the ex_amain.c example program.See AlsoREMAP="BO--Body"cs_ctx_alloc, LINKEND="X58559"ct_exit
ID="IN467465977"ct_init
ID="IN4610436278"ct_keydataID="X50050"ct_keydataID="IN4711436380"Key columnsspecifying
ID="IN4739436381"Extracting the contents of a key column
ID="IN4711436382"Key columnsextracting the contents of
Specify or extract the contents of a key column.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_keydata (cmd, action, colnum, buffer,              buflen, outlen) CS_COMMAND    *cmd;CS_INT        action;CS_INT        colnum;CS_VOID       *buffer;CS_INT        buflen;CS_INT        outlen;ParametersREMAP="RI--RefIndent"cmd - A pointer to the CS_COMMAND structure managing a client/ server cursor operation. action - One of the following symbolic values:TOCENTRY="1"LBL="Table 3-74: "Values for action (MOREINFO="NONE"ct_keydata)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 MOREINFO="NONE"action:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_keydata:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Sets the contents of the key column.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_GETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieves the contents of the key column.colnum - The number of the column of interest. The first column in a result set is column number 1, the second 2, and so forth.REMAP="UN--Under"colnum must represent a CS_KEY or CS_VERSION_KEY column. MOREINFO="NONE"ct_describe sets its *datafmtname='rArrow' font='symbol' code='174'  charset='fontspecific'status field to indicate whether or not a column is a CS_KEY or CS_VERSION_KEY column.buffer - If a key column is being set, buffer points to the value to use in setting the key column. REMAP="UN--Under"If a key column value is being retrieved, buffer points to the space in which MOREINFO="NONE"ct_keydata will place the requested information. buflen - The length, in bytes, of *buffer.REMAP="UN--Under"If a key column value is being set and the value in *buffer is null-terminated, pass buflen as CS_NULLTERM.REMAP="UN--Under"If a key column value is being retrieved and buflen indicates that *buffer is not large enough to hold the requested information, MOREINFO="NONE"ct_keydata sets *outlen to the length of the requested information and returns CS_FAIL. REMAP="UN--Under"buflen is required even for fixed-length buffers, and cannot be passed as CS_UNUSED.outlen - A pointer to an integer variable. REMAP="UN--Under"If a key column value is being set, outlen is unused and must be passed as NULL.REMAP="UN--Under"If a key column value is being retrieved, MOREINFO="NONE"ct_keydata sets *outlen to the length, in bytes, of the requested information. REMAP="UN--Under"If the information is larger than buflen bytes, an application can use the value of *outlen to determine how many bytes are needed to hold the information. REMAP="UN--Under"If an application is setting a key column value or does not care about return length information, it can pass outlen as NULL.ReturnsTOCENTRY="1"LBL="Table 3-75: "Return values (MOREINFO="NONE"ct_keydata)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="106*"COLNAME="C2" COLWIDTH="253*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine completed successfully.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed.
MOREINFO="NONE"
ct_keydata returns CS_FAIL if colnum does not 
represent a key column.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BUSYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An asynchronous operation is already pending for this 
connection. For more information, see the 
MOREINFO="NONE"Asynchronous Programming topics page.CommentsMARK="BULL" REMAP="BU--Bullet"An application can use MOREINFO="NONE"ct_keydataID="IN478436387"Updatingkey columns
ID="IN478436388"Deletingkey columns
to redefine "current" before performing a cursor update or delete.ID="IN4710416589"ct_keydataprimary uses
MOREINFO="NONE"ct_keydata has two primary uses:ID="IN4720396790"Gateway applicationspositioned updates and ct_keydataMARK="DASH" REMAP="BS--BulletSub"In gateway applications that buffer cursor rows between a client and a server. In this case, the client's notion of cursor position can differ from the gateway's. If the client sends a positioned update or delete request, the gateway can use MOREINFO="NONE"ct_keydataID="IN477396791"Cursorsrepositioning a cursor row
ID="IN4710376992"ct_keydataidentifying the current row to a server
to correctly identify the target row to the server.In applications that allows users to browse through data rows, altering or deleting them in random order. In this case, a user may ask the application to alter or delete a row that is not the current cursor row. The application can use MOREINFO="NONE"ct_keydata to redefine the target row as the current row.Because a key can span multiple columns, an application may need to call MOREINFO="NONE"ct_keydata multiple times to specify a row's entire key.ID="IN4711357193"Key columnsct_fetch deletes values previously specifiedCalling MOREINFO="NONE"ct_fetch wipes out any key column values that an application has specified.ID="IN4710337394"ct_keydatacircumstances for calling itAn application can call MOREINFO="NONE"ct_keydata only under the following circumstances:MARK="DASH" REMAP="BS--BulletSub"The current result type is CS_CURSOR_RESULT.ID="IN4723297795"CS_HIDDEN_KEYS propertyCS_HIDDEN_KEYS property and ct_keydatact_keydataThe command structure which is supporting the cursor must have its CS_HIDDEN_KEYS property set to CS_TRUE.At least one fetch must have occurred on the cursor.ID="IN4711297796"Key columnswhen updating, all key columns must be updatedWhen updating a key, all key columns must be updated. If a positioned update or delete is attempted when the row's entire key has not been redefined, MOREINFO="NONE"ct_cursor returns CS_FAIL.ID="IN4711297797"Key columnssetting a columnÕ s value to NULLAn application can set a key column's value to NULL by calling MOREINFO="NONE"ct_keydata with buffer as NULL and buflen as 0 or CS_UNUSED. If the column does not allow null values, MOREINFO="NONE"ct_keydata returns CS_FAIL.See AlsoREMAP="BO--Body"LINKEND="X50078"Cursors
, LINKEND="X36007"ct_cursor
, LINKEND="X64204"ct_describe
, LINKEND="X70623"ct_res_info
, LINKEND="X57817"ct_results
ID="IN4710268099"ct_keydata
ID="IN4792383100"ct_labelsct_labelsID="IN48152384102"Security labelsdefining and clearing
Define a security label or clear security labels for a connection.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_labels(connection, action,                 labelname, namelen, labelvalue,                 valuelen, outlen) CS_CONNECTION    *connection;CS_INT           action;CS_CHAR          *labelname;CS_INT           namelen;CS_CHAR          *labelvalue;CS_INT           valuelen;CS_INT           *outlen;ParametersREMAP="RI--RefIndent"connection - A pointer to a CS_CONNECTION structure. A CS_CONNECTION structure contains information about a particular client/ server connection. REMAP="UN--Under"*connection must represent a closed connection.action - One of the following symbolic values:TOCENTRY="1"LBL="Table 3-76: "Values for action (MOREINFO="NONE"ct_labels)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 MOREINFO="NONE"action:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_labels:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Sets a security label.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CLEARCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Clears all security labels previously specified for 
this connection.labelname - If action is CS_SET, labelname points to the name of the security label being set.REMAP="UN--Under"If action is CS_CLEAR, labelname must be NULL.namelen - The length, in bytes, of *labelname. If *labelname is null-terminated, pass namelen as CS_NULLTERM.REMAP="UN--Under"Security label names must be at least one byte long and no more than CS_MAX_NAME bytes long.REMAP="UN--Under"If action is CS_CLEAR, pass namelen as CS_UNUSED.labelvalue - If action is CS_SET, labelvalue points to the value of the security label being set.REMAP="UN--Under"If action is CS_CLEAR, labelvalue must be NULL.valuelen - The length, in bytes, of *labelvalue. If *labelvalue is null-terminated, pass valuelen as CS_NULLTERM.REMAP="UN--Under"Security label values must be at least one byte long.REMAP="UN--Under"If action is CS_CLEAR, pass valuelen as CS_UNUSED.outlen - This parameter is currently unused and must be passed as NULL.ReturnsTOCENTRY="1"LBL="Table 3-77: "Return values (MOREINFO="NONE"ct_labels)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="106*"COLNAME="C2" COLWIDTH="253*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine completed successfully.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BUSYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An asynchronous operation is already pending for this 
connection. For more information, see the 
MOREINFO="NONE"Asynchronous Programming topics page.CommentsID="IN48322384107"Trusted-user security handshakessecurity labelsMARK="BULL" REMAP="BU--Bullet"An application needs to define security labels if it will be connecting to a server that uses trusted-user security handshakes.ID="IN48172384108"Secure SQL Servertrusted-user security handshakes
ID="IN48172384109"Secure SQL Serverhandling security labelsSecure SQL Server uses trusted-user security handshakes. On Secure SQL Server, security labels are known as "sensitivity labels." There are two ways for an application to define security labels. An application can use either, or both, of these methods:MARK="DASH" REMAP="BS--BulletSub"The application can call MOREINFO="NONE"ct_labels one time for each label it wants to define.The application can call MOREINFO="NONE"ct_callback to install a user-supplied negotiation callback to generate security labels. At connection time, Client-Library automatically triggers the callback in response to a request for security labels.REMAP="UN--Under"If an application uses both methods, the labels defined via MOREINFO="NONE"ct_labels and the labels generated by the negotiation callback are sent to the server at the same time.ID="IN48322186110"Trusted-user security handshakesTrusted-user security handshakesand CS_SEC_NEGOTIATE propertyCS_SEC_NEGOTIATE propertyA connection that will be participating in trusted-user security handshakes must set the ID="IN48251988111"CS_SEC_NEGOTIATE propertyand trusted-user security handshakes
CS_SEC_NEGOTIATE property to CS_TRUE.ID="IN48151988112"Security labelsunlimited number per connectionThere is no limit on the number of security labels that can be defined for a connection.MOREINFO="NONE"ct_labels does not perform any type of checking on security labels, but simply passes the label name/label value combinations on to the server.REMAP="UN--Under"For example, MOREINFO="NONE"ct_labels does not raise an error if an application supplies two label values for the same label name. See AlsoREMAP="BO--Body"LINKEND="X39627"ct_callback
, LINKEND="X57953"ct_con_props
, LINKEND="X31502"ct_connect
ID="IN4891691114"ct_labels
ID="IN48101394115"ct_optionsID="X61859"ct_optionsID="IN4971395117"Settingserver options
ID="IN49101395118"Retrievingserver options
ID="IN4961395119"Serveroptions:setting and retrieving
ID="IN4971395120"Optionssetting and retrieving server options
Set, retrieve, or clear the values of server query-processing options. REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_options(connection, action, option,                 param, paramlen, outlen) CS_CONNECTION    *connection;CS_INT           action;CS_INT           option;CS_VOID          *param;CS_INT           paramlen;CS_INT           *outlen;ParametersREMAP="RI--RefIndent"connection - A pointer to a CS_CONNECTION structure. A CS_CONNECTION structure contains information about a particular client/ server connection.REMAP="UN--Under"connection is the server connection for which the option is set, retrieved, or cleared.action - One of the following symbolic values:TOCENTRY="1"LBL="Table 3-78: "Values for action (MOREINFO="NONE"ct_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 MOREINFO="NONE"action:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_options:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Sets the option.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_GETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieves the option.

An application can use MOREINFO="NONE"ct_options to retrieve 
options from 10.0+ SQL Servers only.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CLEARCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Clears the option by resetting it to its default value. 
Default values are determined by the server to 
which an application is connected.option - The server option of interest. The chart in theMOREINFO="NONE" Summary of Parameters section lists the symbolic values that are legal for option. For more information on these options, see the MOREINFO="NONE"Options topics page.param - All options take parameters. REMAP="UN--Under"When setting an option, param can point to a symbolic value, a boolean value, an integer value, or a character string.REMAP="UN--Under"For example:MARK="DASH" REMAP="BS--BulletSub"The CS_OPT_DATEFIRST option takes a symbolic value as a parameter:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"     CS_INT       parmvalue;     parmamvalue = CS_OPT_TUESDAY;     ct_options(conn, CS_SET, CS_OPT_DATEFIRST,          &paramvalue, CS_UNUSED, NULL);The CS_OPT_CHAINXACTS option takes a boolean value as a parameter:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"     CS_BOOL    parmvalue;     parmamvalue = CS_TRUE;     ct_options(conn, CS_SET, CS_OPT_CHAINXACTS,          &paramvalue, CS_UNUSED, NULL);The CS_OPT_ROWCOUNT option takes an integer as a parameter:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"     CS_INT       parmvalue;     paramvalue = 50;     oc_options(conn, CS_SET, CS_OPT_ROWCOUNT,          &paramvalue, CS_UNUSED, NULL);The CS_OPT_IDENTITYOFF option takes a character string as a parameter:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"     ct_options(conn, CS_SET, CS_OPT_IDENTITYOFF,          "authors", CS_NULLTERM, NULL);REMAP="UN--Under"When retrieving an option, param points to the space in which MOREINFO="NONE"ct_options places the value of the option. REMAP="UN--Under"If paramlen indicates that *param is not large enough to hold the option's value, MOREINFO="NONE"ct_param sets* outlen to the length of the value and returns CS_FAIL. REMAP="UN--Under"When clearing an option, param must be NULL. paramlen - The length, in bytes, of *param.REMAP="UN--Under"When setting or retrieving an option that takes a fixed-length parameter, pass paramlen as CS_UNUSED.REMAP="UN--Under"When setting an option that takes a character string parameter, if the value in *param is null-terminated, pass paramlen as CS_NULLTERM.REMAP="UN--Under"When retrieving an option, if paramlen indicates that *param is not large enough to hold the requested information, MOREINFO="NONE"ct_options sets outlen to the length of the requested information and returns CS_FAIL.REMAP="UN--Under"When clearing an option, paramlen must be CS_UNUSED. outlen - A pointer to an integer variable. REMAP="UN--Under"If an option is being set or cleared, outlen is not used and must be passed as NULL.REMAP="UN--Under"If an option is being retrieved, MOREINFO="NONE"ct_options sets *outlen to the length, in bytes, of the option's value. This length includes a null terminator, if applicable.REMAP="UN--Under"If the option's value is larger than paramlen bytes, an application can use the value of *outlen to determine how many bytes are needed to hold the information. Summary of ParametersTOCENTRY="1"LBL="Table 3-79: "Summary of parameters (MOREINFO="NONE"ct_options)COLS="4" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="132*"COLNAME="C2" COLWIDTH="115*"COLNAME="C3" COLWIDTH="131*"COLNAME="C4" COLWIDTH="87*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Value of MOREINFO="NONE"option:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"*param is:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Legal values for MOREINFO="NONE"*param:COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Defaults to:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_ANSINULLCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A boolean value.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE, CS_FALSECOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_ANSIPERMCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A boolean value.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE, CS_FALSECOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_ARITHABORTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A boolean value.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE, CS_FALSECOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_ARITHIGNORECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A boolean value.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE, CS_FALSECOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_AUTHOFFCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A string value 
representing an 
authority level.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A string value.

Possible values include 
"sa", "sso", and "oper".COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Not applicableCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_AUTHONCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A string value 
representing an 
authority level.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A string value.

Possible values include 
"sa", "sso", and "oper".COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Not applicableCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_CHAINXACTSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A boolean value. COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE, CS_FALSECOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_CURCLOSEON
XACTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A boolean value. COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE, CS_FALSECOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_CURREADCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A string value 
representing a read 
level label.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A string value.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_CURWRITECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A string value 
representing a write 
level label.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A string value.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_DATEFIRSTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A symbolic value 
representing the day to 
use as the first day of 
the week.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_SUNDAY,CS_OPT_MONDAY,CS_OPT_TUESDAY,CS_OPT_WEDNESDAY,CS_OPT_THURSDAY,CS_OPT_FRIDAY,CS_OPT_SATURDAYCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"For us_english, 
the default is 
CS_OPT_
SUNDAY.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_DATEFORMATCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A symbolic value 
representing the order 
of year, month, and 
day to be used in 
datetime values.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_FMTMDY,CS_OPT_FMTDMY,CS_OPT_FMTYMD,CS_OPT_FMTYDM,CS_OPT_FMTMYD,CS_OPT_FMTDYM"COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"For us_english, 
the default is 
CS_OPT_
FMTMDY.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_FIPSFLAGCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A boolean value. COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE, CS_FALSECOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_FORCEPLANCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A boolean value. COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE, CS_FALSECOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_FORMATONLYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A boolean value.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE, CS_FALSECOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_GETDATACOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A boolean value. COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE, CS_FALSECOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_IDENTITYOFFCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A string value 
representing a table 
name.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A string value.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_IDENTITYONCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A string value 
representing a table 
name.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A string value.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_ISOLATIONCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A symbolic value 
representing the 
isolation level.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_LEVEL1,
CS_OPT_LEVEL3COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_
LEVEL1COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_NOCOUNTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A boolean value. COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE, CS_FALSECOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_NOEXECCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A boolean value. COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE, CS_FALSECOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_PARSEONLYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A boolean value. COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE, CS_FALSECOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_QUOTED_
IDENTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A boolean value. COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE, CS_FALSECOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_RESTREESCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A boolean value. COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE, CS_FALSECOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_ROWCOUNTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The maximum 
number of regular 
rows to return.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An integer value.

0 means all rows are 
returned.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"0, meaning all 
rows are 
returned.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_SHOWPLANCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A boolean value. COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE, CS_FALSECOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_STATS_IOCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A boolean value.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE, CS_FALSECOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_STATS_TIMECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A boolean value.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE, CS_FALSECOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_STR_RTRUNCCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A boolean value.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE, CS_FALSECOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_TEXTSIZECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The length, in bytes, of 
the longest text or 
image value the server 
should return.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An integer value.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"32,768 bytes.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_OPT_TRUNCIGNORECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A boolean value. COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE, CS_FALSECOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSEReturnsTOCENTRY="1"LBL="Table 3-80: "Return values (MOREINFO="NONE"ct_options)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="106*"COLNAME="C2" COLWIDTH="253*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine completed successfully.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed.

If MOREINFO="NONE"ct_options returns CS_FAIL, *param remains 
untouched.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CANCELEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The operation was canceled.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_PENDINGCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Asynchronous network I/O is in effect. See the 
MOREINFO="NONE"Asynchronous MOREINFO="NONE"Programming topics page for more 
information.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BUSYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An asynchronous operation is already pending for this 
connection. For more information, see the 
MOREINFO="NONE"Asynchronous Programming topics page.CommentsMARK="BULL" REMAP="BU--Bullet"Although query-processing options can be set and cleared through the Transact-SQL MOREINFO="NONE"set command, it is recommended that Client-Library applications use MOREINFO="NONE"ct_options instead. This is because MOREINFO="NONE"ct_optionsID="IN4961395126"Optionchecking the status of server options
allows an application to check the status of an option, which cannot be done through the MOREINFO="NONE"set command.An application can use MOREINFO="NONE"ct_options to change server options only for a single connection at a time. The connection must be open and must have no active commands or pending results, but can have an open cursor.An application cannot use MOREINFO="NONE"ct_optionsID="IN49101395128"SQL Serveroptions:setting and retrieving
to retrieve options from pre-10.0 SQL Servers.An application can useMOREINFO="NONE" ct_options to set options in pre-10.0 SQL Servers, but pre-10.0 servers do not support all options listed in the MOREINFO="NONE"Summary of Parameters section. For example, the 4.9 SQL Server does not support the CS_OPT_RESTREES option. For information on which options a server supports, see the manual page for the MOREINFO="NONE"set command in the SQL Server Reference Manual.See AlsoREMAP="BO--Body"LINKEND="X94203"ct_capability
, LINKEND="X57953"ct_con_props
, LINKEND="X98856"Options
ID="IN49101098130"ct_optionsID="X45322"ct_paramID="IN43189753"Command parametersdefining
ID="IN43109754"Parametersdefining
Define a command parameter.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_param(cmd, datafmt, data, datalen,indicator);REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_COMMAND     *cmd;CS_DATAFMT     *datafmt;CS_VOID        *data;CS_INT         datalen;CS_SMALLINT    indicator;ParametersREMAP="RI--RefIndent"cmd - A pointer to the CS_COMMAND structure managing a client/ server operation. datafmt - A pointer to a CS_DATAFMT structure that describes the parameter.REMAP="UN--Under"For information on how to set these fields for specific uses of MOREINFO="NONE"ct_param, see the charts in the MOREINFO="NONE"Comments section.data - The address of the parameter data.REMAP="UN--Under"There are two ways to indicate a parameter with a null value:MARK="DASH" REMAP="BS--BulletSub"Pass indicator as -1. In this case, data and datalen are ignored.Pass data as NULL and datalen as 0 or CS_UNUSED.datalen - The length, in bytes, of the parameter data.   REMAP="UN--Under"If datafmtname='rArrow' font='symbol' code='174'  charset='fontspecific'datatype indicates that the parameter is a fixed-length type, datalen is ignored. CS_VARBINARY and CS_VARCHAR are considered to be fixed-length types.indicator - An integer variable used to indicate a parameter with a null value. To indicate a parameter with a null value, pass indicator as -1. If indicator is -1, data and datalen are ignored. Summary of ParametersTOCENTRY="1"LBL="Table 3-81: "Summary of parameters (MOREINFO="NONE"ct_param)COLS="4" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="117*"COLNAME="C2" COLWIDTH="117*"COLNAME="C3" COLWIDTH="106*"COLNAME="C4" COLWIDTH="129*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Type of command:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"ct_param called for 
what purpose?COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"datafmtname='rArrow' font='symbol' code='174'  charset='fontspecific'status is:COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"*data, datalen are:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Cursor declareCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To identify update 
columns.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_UPDATECOLCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The name of the update 
column and the name's 
length.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Cursor declareCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To define host variable 
formats.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_INPUTVALUECOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULL and CS_UNUSED.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Cursor openCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To pass input 
parameter values.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_INPUTVALUECOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The parameter value and 
length.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Cursor updateCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To pass input 
parameter values.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_INPUTVALUECOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The parameter value and 
length.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Dynamic SQL executeCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To pass input 
parameter values.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_INPUTVALUECOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The parameter value and 
length.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"LanguageCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To pass input 
parameter values.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_INPUTVALUECOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The parameter value and 
length.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MessageCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To pass input 
parameter values.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_INPUTVALUECOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The parameter value and 
length.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"RPCCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To pass input or return 
parameter values.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_RETURN to pass 
a return parameter; 
CS_INPUTVALUE 
to pass a non-return 
parameter.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The parameter value and 
length.ReturnsTOCENTRY="1"LBL="Table 3-82: "Return values (MOREINFO="NONE"ct_param)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="106*"COLNAME="C2" COLWIDTH="253*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine completed successfully.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BUSYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An asynchronous operation is already pending for this 
connection. For more information, see the 
MOREINFO="NONE"Asynchronous Programming topics page.REMAP="BO--Body"REMAP="BO--Body"CommentsID="IN43895710"ct_paramwhen to useMARK="BULL" REMAP="BU--Bullet"An application may need to call MOREINFO="NONE"ct_param:ID="IN43795711"Cursorsidentifying update columnsMARK="DASH" REMAP="BS--BulletSub"To identify update columns for a cursor declare command.ID="IN43795712"Cursorsdefining host variable formatsTo define host variable formats for a cursor declare command.ID="IN43795713"Cursorspassing input parameter valuesTo pass input parameter values for a cursor open, cursor update, dynamic SQL execute, language, message, or RPC command.An application calls MOREINFO="NONE"ct_command to initiate a language, RPC or message command, calls MOREINFO="NONE"ct_cursor to initiate a cursor declare or cursor open command, and calls MOREINFO="NONE"ct_dynamic to initiate a Dynamic SQL execute commandREMAP="UN--Under"For specific information on these uses, see the following sections, LINKEND="X23384""Identifying Update Columns for a Cursor Declare Command"
MOREINFO="NONE", LINKEND="X22761""Defining Host Variable Formats"
, and LINKEND="X69913""Passing Input Parameter Values"
MOREINFO="NONE".ID="IN431095714"Parameterspassing NULL valuesIn some cases an application may need to pass a parameter that has a value of NULL. For example, an application might pass parameters with null values to a stored procedure that assigns default values to NULL input parameters. REMAP="UN--Under"There are two ways to indicate a parameter with a null value:MARK="DASH" REMAP="BS--BulletSub"Pass indicator as -1. In this case, data and datalen are ignored.Pass data as NULL and datalen as 0 or CS_UNUSED.ID="IN431095715"Parametersconversion is serverÕ s responsibilityClient-Library does not perform any conversion on parameters before passing them to the server. If parameter conversion is required, it is the server's responsibility.ID="X23384"Identifying Update Columns for a Cursor Declare CommandID="IN431495716"Update columnsidentifying
ID="IN43795717"Cursorsidentifying update columnsMARK="BULL" REMAP="BU--Bullet"An application needs to identify update columns for a cursor declare command if some, but not all, of the columns are "for update." Update columns can be used to change values in underlying database tables.If all of the cursor's columns are for update, an application does not need to call MOREINFO="NONE"ct_param to specify them individually.To identify an update column for a cursor declare command, an application calls MOREINFO="NONE"ct_param with datafmtname='rArrow' font='symbol' code='174'  charset='fontspecific'
status as CS_UPDATECOL and *data as the name of the column.The following table lists the fields in *datafmt that are used when identifying update columns for a cursor declare command:TOCENTRY="1"LBL="Table 3-83: "CS_DATAFMT fields for identifying update columnsCOLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="90*"COLNAME="C2" COLWIDTH="268*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Field name:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Set the field to:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"status COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_UPDATECOLCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"All other fieldsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Are ignored.ID="IN431395718"Host variabledefining formats
ID="IN43995719"Variablesdefining host variable formats
ID="IN43795720"Formatsdefining host variable formatsID="X22761"Defining Host Variable FormatsMARK="BULL" REMAP="BU--Bullet"An application needs to define host variable formats for cursor declare commands, when the body of the cursor being declared is a SQL string that contains host variables.To define the format of a host variable, an application calls MOREINFO="NONE"ct_param with datafmtname='rArrow' font='symbol' code='174'  charset='fontspecific'
status as CS_INPUTVALUE, datafmtname='rArrow' font='symbol' code='174'  charset='fontspecific'datatype as the datatype of the host variable, data as NULL and datalen as CS_UNUSED.An application defines host variable formats during a cursor declare command but does not pass data values for the variables until cursor open time.When defining host variable formats, the variables can either be named or unnamed. If one variable is named, all variables must be named. If variables are not named, they are interpreted positionally.The following table lists the fields in *datafmt that are used when defining host variable formats:TOCENTRY="1"LBL="Table 3-84: "CS_DATAFMT fields for defining host variable formatsCOLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="90*"COLNAME="C2" COLWIDTH="268*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Field name:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Set the field to:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"name COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The name of the host variable.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"namelen COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The length, in bytes, of name, or 0 to indicate an unnamed 
parameter.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"datatype COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The datatype of the host variable.

All standard Client-Library types are valid except for 
CS_TEXT_TYPE, CS_IMAGE_TYPE, and Client-Library 
user-defined types.

If datatype is CS_VARCHAR_TYPE or 
CS_VARBINARY_TYPE then data must point to a 
CS_VARCHAR or CS_VARBINARY structure.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"status COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_INPUTVALUECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"All other fieldsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Are ignored.ID="IN432295721"Input parameter valuespassing
ID="IN431095722"Parameterspassing input parameter valuesID="X69913"Passing Input Parameter ValuesMARK="BULL" REMAP="BU--Bullet"An application may need to pass input parameter values for:MARK="DASH" REMAP="BS--BulletSub"Client-Library cursor open commandsClient-Library cursor update commandsDynamic SQL execute commandsLanguage commandsMessage commandsRPC commandsWhen passing input parameter valuesMOREINFO="NONE", parameters can either be named or unnamed. If one parameter is named, all parameters must be named. If parameters are not named, they are interpreted positionally.Client-Library cursor open commands require input parameter values when:MARK="DASH" REMAP="BS--BulletSub"The body of the cursor is a SQL text string containing host variables.The body of the cursor is a stored procedure that requires parameters. In this case, *datafmtname='rArrow' font='symbol' code='174'  charset='fontspecific'status can be either CS_RETURN, to indicate that the a return parameter, or CS_INPUTVALUE, to indicate a non-return parameter.Client-Library cursor update commands require input parameter values when the SQL text representing the update command contains host variables.Dynamic SQL execute commands require input parameter values when the prepared statement being executed contains dynamic parameter markers.Language commands require input parameter values when the text of the language command contains host variables.Message commands require input parameters values when the message takes parameters.RPC commands require input parameter values when the stored procedure being executed takes parameters.The following table lists the fields in *datafmt that are used when passing input parameter values:TOCENTRY="1"LBL="Table 3-85: "CS_DATAFMT fields for passing input parameter valuesCOLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="90*"COLNAME="C2" COLWIDTH="268*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Field name:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Set the field to:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"name COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The name of the parameter.

name is ignored for dynamic SQL execute commands.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"namelen COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The length, in bytes, of name, or 0 to indicate an unnamed 
parameter.

namelen is ignored for dynamic SQL execute commands.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"datatype COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The datatype of the input parameter value.

All standard Client-Library types are valid except for 
CS_TEXT_TYPE, CS_IMAGE_TYPE, and Client-Library 
user-defined types.

If datatype is CS_VARCHAR_TYPE or 
CS_VARBINARY_TYPE then data must point to a 
CS_VARCHAR or CS_VARBINARY structure.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"maxlength COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"When passing return parameters for RPC commands, 
maxlength represents the maximum length, in bytes, of 
data to be returned for this parameter.

maxlength is not used when passing input parameter 
values for other types of commands.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"status COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_RETURN when passing return parameters for RPC 
commands; otherwise CS_INPUTVALUE.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"All other fieldsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Are ignored.ID="IN43893923"ct_paramcode exampleExampleREMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/*** BuildRpcCommand()**** Purpose:**     Builds an RPC command but does not send it.***/REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"CS_STATIC CS_RETCODE BuildRpcCommand(cmd)CS_COMMAND     *cmd;{     CS_CONNECTION   *connection;     CS_CONTEXT      *context;     CS_RETCODE      retcode;     CS_DATAFMT      datafmt;     CS_DATAFMT      srcfmt;     CS_DATAFMT      destfmt;     CS_INT          intvar;     CS_SMALLINT     smallintvar;     CS_FLOAT        floatvar;     CS_MONEY        moneyvar;     CS_BINARY       binaryvar;     char            moneystring[10];     char            rpc_name[15];     CS_INT          destlen;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /*     ** Assign values to the variables used for      ** parameter passing.     */       intvar = 2;     smallintvar = 234;     floatvar = 0.12;     binaryvar = (CS_BINARY)0xff;     strcpy(rpc_name, "sample_rpc");     strcpy(moneystring, "300.90");REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /*     ** Clear and setup the CS_DATAFMT structures used      ** to convert datatypes.     */     memset(&srcfmt, 0, sizeof (CS_DATAFMT));     srcfmt.datatype = CS_CHAR_TYPE;     srcfmt.maxlength = strlen(moneystring);     srcfmt.precision = 5;     srcfmt.scale = 2;     srcfmt.locale = NULL;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     memset(&destfmt, 0, sizeof (CS_DATAFMT));     destfmt.datatype = CS_MONEY_TYPE;     destfmt.maxlength = sizeof(CS_MONEY);     destfmt.precision = 5;     destfmt.scale = 2;     destfmt.locale = NULL;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /*     ** Convert the string representing the money value     ** to a CS_MONEY variable. Since this routine      ** does not have the context handle, we use the      ** property functions to get it.     */     if ((retcode = ct_cmd_props(cmd, CS_GET,         CS_PARENT_HANDLE, &connection, CS_UNUSED,          NULL)) != CS_SUCCEED)     {          ...CODE DELETED.....     }     if ((retcode = ct_con_props(connection, CS_GET,         CS_PARENT_HANDLE, &context, CS_UNUSED,         NULL)) != CS_SUCCEED)     {     ...CODE DELETED.....     }     retcode = cs_convert(context, &srcfmt,          (CS_VOID *)moneystring, &destfmt, &moneyvar,         &destlen);     if (retcode != CS_SUCCEED)     {          ...CODE DELETED.....     }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /*     ** Initiate the RPC command for our stored     ** procedure.     */     if ((retcode = ct_command(cmd, CS_RPC_CMD,        rpc_name, CS_NULLTERM,CS_NO_RECOMPILE)) !=         CS_SUCCEED)     {         ...CODE DELETED.....     }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /*     ** Clear and setup the CS_DATAFMT structure, then      ** pass each of the parameters for the RPC.     */     memset(&datafmt, 0, sizeof (datafmt));     strcpy(datafmt.name, "@intparam");     datafmt.namelen = CS_NULLTERM;     datafmt.datatype = CS_INT_TYPE;     datafmt.maxlength = CS_UNUSED;     datafmt.status = CS_INPUTVALUE;     datafmt.locale = NULL;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     if ((retcode = ct_param(cmd, &datafmt,          (CS_VOID *)&intvar, sizeof(CS_INT),          CS_UNUSED)) != CS_SUCCEED)     {         ...CODE DELETED.....     }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     strcpy(datafmt.name, "@sintparam");     datafmt.namelen = CS_NULLTERM;     datafmt.datatype = CS_SMALLINT_TYPE;     datafmt.status = CS_RETURN;     datafmt.locale = NULL;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     if ((retcode = ct_param(cmd, &datafmt,          (CS_VOID *)&smallintvar,          sizeof(CS_SMALLINT), CS_UNUSED)) !=          CS_SUCCEED)     {         ...CODE DELETED.....     }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     strcpy(datafmt.name, "@floatparam");     datafmt.namelen = CS_NULLTERM;     datafmt.datatype = CS_FLOAT_TYPE;     datafmt.status = CS_RETURN;     datafmt.locale = NULL;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     if((retcode = ct_param(cmd, &datafmt,          (CS_VOID *)&floatvar, sizeof(CS_FLOAT),         CS_UNUSED))  != CS_SUCCEED)     {         ...CODE DELETED.....     }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     strcpy(datafmt.name, "@moneyparam");     datafmt.namelen = CS_NULLTERM;     datafmt.datatype = CS_MONEY_TYPE;     datafmt.status = CS_RETURN;     datafmt.locale = NULL;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     if((retcode = ct_param(cmd, &datafmt,          (CS_VOID *)&moneyvar, sizeof(CS_MONEY),          CS_UNUSED))  != CS_SUCCEED)     {         ...CODE DELETED.....     }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     strcpy(datafmt.name, "@dateparam");     datafmt.namelen = CS_NULLTERM;     datafmt.datatype = CS_DATETIME4_TYPE;     datafmt.status = CS_RETURN;     datafmt.locale = NULL;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /*     ** The datetime variable is filled in by the RPC      ** so pass NULL for the data, 0 for data length,      ** and -l for the indicator arguments.     */     if((retcode = ct_param(cmd, &datafmt, NULL, 0,          -1)) != CS_SUCCEED)     {         ...CODE DELETED.....     }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     strcpy(datafmt.name, "@charparam");     datafmt.namelen = CS_NULLTERM;     datafmt.datatype = CS_CHAR_TYPE;     datafmt.maxlength = EX_MAXSTRINGLEN;     datafmt.status = CS_RETURN;     datafmt.locale = NULL;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /*     ** The character string variable is filled in by      ** the RPC so pass NULL for the data 0 for data      ** length, and -l for the indicator arguments.     */< HR>     if((retcode = ct_param(cmd, &datafmt, NULL, 0,          -1)) != CS_SUCCEED)     {         ...CODE DELETED.....     }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     strcpy(datafmt.name, "@binaryparam");     datafmt.namelen = CS_NULLTERM;     datafmt.datatype = CS_BINARY_TYPE;     datafmt.maxlength = EX_MAXSTRINGLEN;     datafmt.status = CS_RETURN;     datafmt.locale = NULL;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     if((retcode = ct_param(cmd, &datafmt,          (CS_VOID *)&binaryvar, sizeof(CS_BINARY),         CS_UNUSED))  != CS_SUCCEED)     {         ...CODE DELETED.....     }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     return retcode;}REMAP="BO--Body"This code excerpt is from the rpc.c example program.See AlsoREMAP="BO--Body"LINKEND="X39849"ct_command
MOREINFO="NONE", LINKEND="X36007"ct_cursor
MOREINFO="NONE", LINKEND="X77746"ct_dynamic
MOREINFO="NONE", LINKEND="X69834"ct_send
ID="IN438901226"ct_param
MOREINFO="NONE"   ID="IN437871527"ct_pollID="X67063"ct_pollID="IN447871629"Pollingconnections
ID="IN4411871630"Connectionspolling for asynchronous operation completions and registered procedure notifications
ID="IN4424851831"Asynchronous programmingAsynchronous programmingand ct_pollct_poll
ID="IN4421851832"Registered procedurespolling for notifications
Poll connections for asynchronous operation completions and registered procedure notifications.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_poll (context, connection,                  milliseconds, compconn,                  compcmd, compid, compstatus) CS_CONTEXT        *context;CS_CONNECTION     *connection;CS_INT            milliseconds;CS_CONNECTION     **compconn;CS_COMMAND        **compcmd;CS_INT            *compid;CS_RETCODE        *compstatus;ParametersREMAP="RI--RefIndent"context - A pointer to a CS_CONTEXT structure.REMAP="UN--Under"Either context or connection must be NULL. If context is NULL, MOREINFO="NONE"ct_poll checks only a single connection.connection - A pointer to a CS_CONNECTION structure. A CS_CONNECTION structure contains information about a particular client/ server connection.REMAP="UN--Under"Either context or connection must be NULL. If connection is NULL, MOREINFO="NONE"ct_poll checks all open connections within the context.milliseconds - The length of time, in milliseconds, to wait for pending operations to complete. REMAP="UN--Under"If milliseconds is 0, MOREINFO="NONE"ct_poll returns immediately. To check for operation completions without blocking, pass milliseconds as 0.REMAP="UN--Under"If milliseconds is CS_NO_LIMIT, MOREINFO="NONE"ct_poll does not return until either a server response arrives or a system interrupt occurs.compconn - The address of a pointer variable. If connection is NULL, all connections are polled and MOREINFO="NONE"ct_poll sets *compconn to point to the connection structure owning the first completed operation it finds.REMAP="UN--Under"If no operation has completed by the time MOREINFO="NONE"ct_poll returns, MOREINFO="NONE"ct_poll sets *compconn to NULL.REMAP="UN--Under"If connection is supplied, compconn must be NULL.compcmd - The address of a pointer variable. ct_MOREINFO="NONE"poll sets *compcmd to point to the command structure owning the first completed operation it finds. If no operation has completed by the time MOREINFO="NONE"ct_poll returns, MOREINFO="NONE"ct_poll sets *compcmd to NULL.compid - The address of an integer variable. MOREINFO="NONE"ct_poll sets *compid to one of the following symbolic values to indicate what has completed:TOCENTRY="1"LBL="Table 3-86: "Values for compid (MOREINFO="NONE"ct_poll)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 MOREINFO="NONE"compid:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Indicating:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"BLK_ROWXFERCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"blk_rowxfer has completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"BLK_SENDROWCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"blk_sendrow has completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"BLK_SENDTEXTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"blk_sendtext has completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"BLK_TEXTXFERCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"blk_textxfer has completedCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CT_CANCELCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel has completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CT_CLOSECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_close has completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CT_CONNECTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_connect has completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CT_FETCHCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_fetch has completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CT_GET_DATACOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_get_data has completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CT_NOTIFICATIONCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A notification has been received.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CT_OPTIONSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_options has completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CT_RECVPASSTHRUCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_recvpassthru has completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CT_RESULTSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_results has completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CT_SENDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_send has completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CT_SEND_DATACOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_send_data has completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CT_SENDPASSTHRUCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_sendpassthru has completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A user-defined value. 
This value must be 
greater than or equal to 
CT_USER_FUNC.COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A user-defined function has completed.compstatus - A pointer to a variable of type CS_RETCODE. MOREINFO="NONE"ct_poll sets *compstatus to indicate the final return code of the completed operation. This can be any of the return codes listed for the routine, with the exception of CS_PENDING.Summary of ParametersTOCENTRY="1"LBL="Table 3-87: "Summary of parameters (MOREINFO="NONE"ct_poll)COLS="4" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="72*"COLNAME="C2" COLWIDTH="82*"COLNAME="C3" COLWIDTH="82*"COLNAME="C4" COLWIDTH="231*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"context:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"connection:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"compconn:COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_poll:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Must have a 
value.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Must be NULL.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Checks the single connection specified by 
MOREINFO="NONE"connection.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Has a valueCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Must be NULL.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Must have a 
value.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Checks all connections within this context. Sets 
MOREINFO="NONE"*compconn to point to the connection owning the 
first completed operation it finds.ReturnsTOCENTRY="1"LBL="Table 3-88: "Return values (MOREINFO="NONE"ct_poll)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="108*"COLNAME="C2" COLWIDTH="251*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An operation has completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An error occurred.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TIMED_OUTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The timeout value specified by MOREINFO="NONE"milliseconds elapsed 
before any operation completed.

Asynchronous operations may be in progress.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_QUIETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_poll was called with milliseconds as 0 (to indicate 
that it should return immediately).

No asynchronous operations are in progress, and no 
completed operations were found.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_INTERRUPTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A system interrupt has occurred.REMAP="BO--Body"MOREINFO="NONE"ct_poll returns CS_FAIL if it polls a connection that has died.CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"ct_poll will poll either a specific connection or all connections within a specific context.ID="IN447832038"ct_pollwhen to useIf a platform does not provide interrupt-driven I/O, then an application must read from the network in order to recognize asynchronous operation completions and registered procedure notifications.REMAP="UN--Under"All routines that can return CS_PENDING read from the network. If an application is not actively using any of these routines, it must call MOREINFO="NONE"ct_poll in order to recognize asynchronous operation completions and registered procedure notifications.ID="IN447812239"ct_pollcallbacksIf a platform allows the use of callback functions, MOREINFO="NONE"ct_poll automatically calls the proper callback routine, if one is installed, when it finds a completed operation or a notification.ID="IN447772640"ct_pollct_polland CS_DISABLE_POLL propertyCS_DISABLE_POLL property
MOREINFO="NONE"ct_poll does not check for asynchronous operation completions if the ID="IN4424733041"CS_DISABLE_POLL propertyCS_DISABLE_POLL propertyand ct_pollct_poll
CS_DISABLE_POLL property is set to CS_TRUE.ID="IN4424693442"CS_ASYNC_NOTIFS propertyCS_ASYNC_NOTIFS propertyand ct_pollct_poll
If CS_ASYNC_NOTIFS is CS_FALSEID="IN447653843"ct_pollct_polland CS_ASYNC_NOTIFS propertyCS_ASYNC_NOTIFS property
, MOREINFO="NONE"ct_poll will not read from the network. This means that an application must be reading results in order for MOREINFO="NONE"ct_poll to report a registered procedure notification.For more information see the MOREINFO="NONE"Callbacks and MOREINFO="NONE"Asynchronous MOREINFO="NONE"Programming topics pages.ID="IN447634044"ct_pollcode exampleExampleREMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/*** BusyWait()**** Prints out dots while waiting for an async ** operation to complete. It demonstrates an ** application's ability to do other work while an ** async operation is pending.*/REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"CS_STATIC CS_RETCODE CS_INTERNALBusyWait(connection, where)CS_CONNECTION   *connection;char         *where;{     CS_COMMAND   *compcmd;     CS_INT       compid;     CS_RETCODE   compstat;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     fprintf(stdout, "Waiting [%s]", where);     fflush(stdout);     while (completed == CS_FALSE)     {        fprintf(stdout, ".");        fflush(stdout);        ct_poll(NULL, connection, 100, NULL, &compcmd,             &compid, &compstat);     }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     fprintf(stdout, "\n");     return completed_retcode;}REMAP="BO--Body"This code excerpt is from the ex_amain.c example program.See AlsoREMAP="BO--Body"LINKEND="X80066"Asynchronous Programming
MOREINFO="NONE", LINKEND="X40634"Callbacks
MOREINFO="NONE", LINKEND="X39627"ct_callback
MOREINFO="NONE", LINKEND="X46507"ct_wakeup
MOREINFO="NONE", LINKEND="X81031"Properties
ID="IN447604347"ct_poll
ID="IN4415574648"ct_recvpassthruID="X81597"ct_recvpassthruID="IN453574750"TDSpass-through operation
ID="IN453574751"TDSreceiving a TDS packet
ID="IN4519545052"Tabular Data StreamSee TDS
ID="IN457545053"Packetsreceiving TDS packets
Receive a TDS (Tabular Data Stream) packet from a server.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_recvpassthru (cmd, recvptr) CS_COMMAND     *cmd;CS_VOID        **recvptr;ParametersREMAP="RI--RefIndent"cmd - A pointer to a CS_COMMAND structure. recvptr - The address of a pointer variable. MOREINFO="NONE"ct_recvpassthru sets the variable to the address of a buffer containing the most-recently-received TDS packet. The application is not responsible for allocating this buffer.ReturnsREMAP="BO--Body"TOCENTRY="1"LBL="Table 3-89: "Return values (MOREINFO="NONE"ct_recvpassthru)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"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_PASSTHRU_MORECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Packet received successfully; more packets are 
available.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_PASSTHRU_EOMCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Packet received successfully; no more packets are 
available.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CANCELEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The pass-through operation was canceled.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_PENDINGCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Asynchronous network I/O is in effect. For more 
information, see the MOREINFO="NONE"Asynchronous MOREINFO="NONE"Programming 
topics page.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BUSYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An asynchronous operation is already pending for 
this connection. For more information, see the 
MOREINFO="NONE"Asynchronous Programming topics page.CommentsMARK="BULL" REMAP="BU--Bullet"TDS is a communications protocol used for the transfer of requests and request results between clients and servers. Under ordinary circumstances, non-gateway applications do not usually have to deal with TDS, because Client-Library manages the data stream. MOREINFO="NONE"ct_recvpassthru and MOREINFO="NONE"ct_sendpassthruID="IN4520545058"Gateway applicationsGateway applicationsand TDS pass-throughTDS pass-through
are useful in gateway applications. When an application serves as the intermediary between two parties (such as a client and a remote server, or 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"ct_recvpassthru reads a packet of bytes from a server connection and sets *recvptr to point to the buffer containing the bytes.ID="IN457545059"Packetsdefault packet sizes vary by platformDefault packet sizes vary by platform. On most platforms, a packet has a default size of 512 bytes. A connection can change its packet size via MOREINFO="NONE"ct_con_props.MOREINFO="NONE"ct_recvpassthru returns CS_PASSTHRU_EOMID="IN453545060"TDSpacket marked as End of Message (EOM)
if the TDS packet has been marked by the server as EOM (End Of Message). If the TDS packet is not marked EOM, MOREINFO="NONE"ct_recvpassthru returns CS_PASSTHRU_MORE.A connection which is being used for a pass-through operation cannot be used for any other Client-Library function until CS_PASSTHRU_EOM has been received.See AlsoREMAP="BO--Body"LINKEND="X32025"ct_getloginfo
MOREINFO="NONE", LINKEND="X54893"ct_sendpassthru
MOREINFO="NONE", LINKEND="X72103"ct_setloginfo
ID="IN4515515362"ct_recvpassthru
MOREINFO="NONE"  REMAP="BO--Body"ID="X33916"ct_remote_pwdID="IN4399753"Passwordsdefining and clearing for remote servers
ID="IN4379754"Serversdefining and clearing passwords
ID="IN43289755"Server-to-server connectionsdefining and clearing passwords
Define or clear passwords to be used for server-to-server connections. REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_remote_pwd(connection, action,                 server_name, snamelen, password,                 pwdlen) CS_CONNECTION    *connection;CS_INT           action;CS_CHAR          *server_name;CS_INT           snamelen;CS_CHAR          *password;CS_INT           pwdlen;ParametersREMAP="RI--RefIndent"connection - A pointer to a CS_CONNECTION structure. A CS_CONNECTION structure contains information about a particular client/ server connection. REMAP="UN--Under"It is illegal to define remote passwords for a connection that is open.action - One of the following symbolic values:TOCENTRY="1"LBL="Table 3-90: "Values for action (MOREINFO="NONE"ct_remote_pwd)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 MOREINFO="NONE"action:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_remote_pwd:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Sets the remote passwordCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CLEARCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Clears all remote passwords specified for this 
connection by setting them to NULL.server_name - A pointer to the name of the server for which the password is being defined. *server_name is the name given to the server in an interfaces file.   REMAP="UN--Under"If server_name 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.REMAP="UN--Under"If action is CS_CLEAR, server_name must be NULL.snamelen - The length, in bytes, of *server_name. If *server_name is null-terminated, pass snamelen as CS_NULLTERM. REMAP="UN--Under"If action is CS_SET and server_name is NULL, pass snamelen as 0 or CS_UNUSED.REMAP="UN--Under"If action is CS_CLEAR, snamelen must be CS_UNUSED.password - A pointer to the password being installed for remote logins to the *server_name server. REMAP="UN--Under"If action is CS_CLEAR, password must be NULL.pwdlen - The length, in bytes, of *password. If *password is null-terminated, pass pnamelen as CS_NULLTERM.REMAP="UN--Under"If action is CS_SET and password is NULL, pass pwdlen as 0 or CS_UNUSED.REMAP="UN--Under"If action is CS_CLEAR, pwdlen must be CS_UNUSED.ReturnsTOCENTRY="1"LBL="Table 3-91: "Return values (MOREINFO="NONE"ct_remote_pwd)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="106*"COLNAME="C2" COLWIDTH="253*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine completed successfully.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BUSYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An asynchronous operation is already pending for this 
connection. For more information, see the 
MOREINFO="NONE"Asynchronous Programming topics page.CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"ct_remote_pwd defines the password that a server will use when logging into another server.A Transact-SQL language command or stored procedure running on one server can call a stored procedure located on another server. To accomplish this server-to-server communication, the first server to which an application has connected via MOREINFO="NONE"ct_connectID="IN432297510"Remote procedure callsserver-to-server communication
, actually logs into the second, remote server, performing a server-to-server remote procedure call.REMAP="UN--Under"MOREINFO="NONE"ct_remote_pwd allows an application to specify the password to be used when the first server logs into the remote server.Multiple passwords may be specified, one for each server that a server might need to log into. Each password must be defined with a separate call to ID="IN431395711"ct_remote_pwddefining multiple passwords
MOREINFO="NONE"ct_remote_pwd.ID="IN43995712"Passwordsdefault password for remote server
ID="IN432895713"Server-to-server connectionsdefault passwordsIf an application does not specify a remote password for a particular server, the password defaults to the password set for this connection via MOREINFO="NONE"ct_con_props, if any. If no password has been defined, the password defaults to NULL. If an application user generally has the same password on different servers, this default behavior may be acceptable.ID="IN43995714"Passwordsstoring remote passwords
ID="IN432895715"Server-to-server connectionsstoring remote passwordsRemote passwords are stored in an internal buffer which is only 255 bytes long. Each password's entry in the buffer consists of the password itself, the associated server name, and two extra bytes. If the addition of a password to this buffer would cause overflow, MOREINFO="NONE"ct_remote_pwd returns CS_FAIL and generates a Client-Library error message that indicates the problem.ID="IN431393916"ct_remote_pwdwhen not to useIt is an error to call MOREINFO="NONE"ct_remote_pwd to define a remote password for a connection that is already open. Define remote passwords before calling MOREINFO="NONE"ct_connect to create an active connection.An application can call MOREINFO="NONE"ct_remote_pwd to clear remote passwords for a connection at any time.See AlsoREMAP="BO--Body"LINKEND="X57953"ct_con_props
MOREINFO="NONE", LINKEND="X31502"ct_connect
ID="IN4313901218"ct_remote_pwd
MOREINFO="NONE"   ID="IN4311871519"ct_res_infoID="X70623"ct_res_infoID="IN4410871621"Retrievingcurrent result set or command information
ID="IN448871622"Commandscurrent command information
ID="IN447871623"Resultscurrent result set information
Retrieve current result set or command information.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_res_info(cmd, type, buffer, buflen,               outlen) CS_COMMAND     *cmd;CS_INT         type;CS_VOID        *buffer;CS_INT         buflen;CS_INT         *outlen;ParametersREMAP="RI--RefIndent"cmd - A pointer to the CS_COMMAND structure managing a client/ server command. type - The type of information to return. The table in the MOREINFO="NONE"Summary of Parameters section lists the symbolic values that are legal for type.buffer - A pointer to the space in which MOREINFO="NONE"ct_res_info will place the requested information. REMAP="UN--Under"If buflen indicates that *buffer is not large enough to hold the requested information, MOREINFO="NONE"ct_res_info sets *MOREINFO="NONE"outlen to the length of the requested information and returns CS_FAIL. buflen - The length, in bytes, of the *buffer data space, or CS_UNUSED if *buffer represents a fixed-length or symbolic value.outlen - A pointer to an integer variable. REMAP="UN--Under"MOREINFO="NONE"ct_res_info sets *outlen to the length, in bytes, of the requested information. REMAP="UN--Under"If the requested information is larger than buflen bytes, an application can use the value of *outlen to determine how many bytes are needed to hold the information. Summary of ParametersTOCENTRY="1"LBL="Table 3-92: "Summary of parameters (MOREINFO="NONE"ct_res_info)COLS="4" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="115*"COLNAME="C2" COLWIDTH="132*"COLNAME="C3" COLWIDTH="149*"COLNAME="C4" COLWIDTH="72*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Value of MOREINFO="NONE"type:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_res_info returns:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The information is available 
after MOREINFO="NONE"ct_results sets its 
*result_type parameter to:COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"*MOREINFO="NONE"buffer is set 
to:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BROWSE_INFOCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE if browse-mode 
information is available; 
CS_FALSE if browse-
mode information is not 
available.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_ROW_RESULTCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE or 
CS_FALSE.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CMD_NUMBERCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The number of the 
command that generated 
the current result set.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Any value.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An integer 
value.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_MSGTYPECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An integer representing 
the id of the message that 
makes up the current 
result set.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_MSG_RESULTCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A small 
integer.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_NUM_COMPUTESCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The number of compute 
clauses in the current 
command.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_COMPUTE_RESULTCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An integer 
value.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_NUMDATACOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The number of items in the 
current result set. COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_COMPUTE_RESULT,
CS_COMPUTEFMT_RESULT,
CS_CURSOR_RESULT,
CS_DESCRIBE_RESULT,
CS_PARAM_RESULT,
CS_ROW_RESULT,
CS_ROWFMT_RESULT,
CS_STATUS_RESULTCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An integer 
value.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_NUMORDER
COLSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The number of columns 
specified in the order-by 
clause of the current 
command.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_ROW_RESULTCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An integer 
value.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_ORDERBY_COLSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The select list id numbers 
of columns specified in a 
the MOREINFO="NONE"order by clause of the 
current command. COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_ROW_RESULTCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An array of 
integers.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_ROW_COUNTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The number of rows 
affected by the current 
command.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CMD_DONE,
CS_CMD_FAIL
CS_CMD_SUCCEEDCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An integer 
value.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRANS_STATECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The current server 
transaction state.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Any value.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A symbolic 
value.ReturnsTOCENTRY="1"LBL="Table 3-93: "Return values (MOREINFO="NONE"ct_res_info)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"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine completed successfully.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed.
MOREINFO="NONE"
ct_res_info returns CS_FAIL if the requested 
information is larger than buflen bytes, or if there is 
no current result set.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BUSYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An asynchronous operation is already pending for 
this connection. For more information, see the 
MOREINFO="NONE"Asynchronous Programming topics page.CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"ct_res_info returns information about the current result set or the current command. The current command is defined as the command that generated the current result set.A result set is a collection of a single type of result data. Result sets are generated by commands. For more information on result sets, see the MOREINFO="NONE"ct_results manual page and the MOREINFO="NONE"Results topics page.ID="IN4411851829"ct_res_infowhen to useMost typically, an application calls MOREINFO="NONE"ct_res_info with type as CS_NUMDATA, to determine the number of items in a result set.ID="IN4411851830"Browse modewhen browse mode information is availableDetermining Whether Browse Mode Information is AvailableMARK="BULL" REMAP="BU--Bullet"To determine whether browse-mode information is available, call MOREINFO="NONE"ct_res_info with type as CS_BROWSE_INFO. If browse-mode information is available, an application can call MOREINFO="NONE"ct_br_column and MOREINFO="NONE"ct_br_table to retrieve the information. If browse-mode information is not available, calling MOREINFO="NONE"ct_br_column or MOREINFO="NONE"ct_br_table will result in a Client-Library error.For more information on browse mode, see the MOREINFO="NONE"Browse Mode topics page in Chapter 2 of this manual.ID="IN447851831"Resultsretrieving the command number for the current result set
ID="IN4410851832"Retrievingcommand number for current result set
ID="IN448851833"Commandsretrieving the command number for the current result setRetrieving the Command Number for Current ResultsMARK="BULL" REMAP="BU--Bullet"To determine the number of the command that generated the current results, call MOREINFO="NONE"ct_res_info with type as CS_CMD_NUMBER.Client-Library keeps track of the command number by counting the number of times MOREINFO="NONE"ct_results returns CS_CMD_DONE.REMAP="UN--Under"An application's first call to MOREINFO="NONE"ct_results following a MOREINFO="NONE"ct_send call sets the command number to 1. After this, it is incremented each time MOREINFO="NONE"ct_results is called after returning CS_CMD_DONE.ID="IN4430832034"CS_CMD_NUMBER information typewhen useful
CS_CMD_NUMBER is useful in the following cases:MARK="DASH" REMAP="BS--BulletSub"To find out which Transact-SQL command within a language command generated the current result set.To find out which cursor command, in a batch of cursor commands, generated the current result set.To find out which MOREINFO="NONE"select command in a stored procedure generated the current result set.A language command contains a string of Transact-SQL text. This text represents one or more Transact-SQL commands. When used against a language command, "command number" refers to the number of the Transact-SQL command in the language command.REMAP="UN--Under"For example, the string:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"     select * from authors     select * from titles     insert newauthors          select *          from authors          where city = "San Francisco"REMAP="UN--Under"represents three Transact-SQL commands, two of which can generate result sets. In this case, the command number that MOREINFO="NONE"ct_res_info returns can be from 1 to 3, depending on when MOREINFO="NONE"ct_res_info is called.Inside stored procedures, only MOREINFO="NONE"select statements cause the command number to be incremented. If a stored procedure contains seven Transact-SQL commands, three of which are MOREINFO="NONE"selects, the command number that MOREINFO="NONE"ct_res_info returns can be any integer from 1 to 3, depending on which MOREINFO="NONE"select generated the current result set.MOREINFO="NONE"ct_cursor is used to initiate a cursor command. Several cursor commands can be defined, as a batch, before they are sent to a server. When used against a cursor command batch, "command number" refers to the number of the cursor command in the command batch.REMAP="UN--Under"For example, an application can make the following calls:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"     ct_cursor(...CS_CURSOR_DECLARE...);     ct_cursor(...CS_CURSOR_ROWS...);     ct_cursor(...CS_CURSOR_OPEN...);     ct_send();REMAP="UN--Under"The command number that MOREINFO="NONE"ct_res_info returns can be 1, 2, or 3, depending on which cursor command generated the current result type.ID="IN4410832035"Retrievingmessage idRetrieving a Message IDID="IN4410832036"Message IDretrieving a message IDMARK="BULL" REMAP="BU--Bullet"To retrieve a message id, call MOREINFO="NONE"ct_res_info with type as CS_MSGTYPE.Servers can send messages to client applications. Messages are received in the form of "message result sets." Message result sets contain no fetchable data, but rather have an id number.Messages can also have parameters. Message parameters are returned to an application as a parameter result set, immediately following the message result set.ID="IN4410832037"Retrievingnumber of compute clauses
ID="IN4414832038"Compute clauseretrieving the number of compute clausesRetrieving the Number of Compute ClausesMARK="BULL" REMAP="BU--Bullet"To determine the number of MOREINFO="NONE"compute clauses in the command that generated the current result set, call MOREINFO="NONE"ct_res_info with type as CS_NUM_COMPUTES.A Transact-SQL MOREINFO="NONE"select statement can contain MOREINFO="NONE"compute clauses that generate compute result sets.ID="IN4410832039"Retrievingnumber of result data items
ID="IN4411832040"Result dataretrieving the number of result data itemsRetrieving the Number of Result Data ItemsMARK="BULL" REMAP="BU--Bullet"To determine the number of result data items in the current result set, call MOREINFO="NONE"ct_res_info with type as CS_NUMDATA. Results sets contain result data items. Row, cursor, and compute result sets contain columns, a parameter result set contains parameters, and a status result set contains a status. The columns, parameters, and status are known as "result data items".A message result set does not contain any data items.ID="IN4410832041"Retrievingnumber of columns in an order-by clause
ID="IN447832042"Columnsretrieving the number of columns in an order-by clauseRetrieving the Number of Columns in an Order-By ClauseMARK="BULL" REMAP="BU--Bullet"To determine the number of columns in a Transact-SQL MOREINFO="NONE"select statement'sMOREINFO="NONE" order by clause, call MOREINFO="NONE"ct_res_info with type as CS_NUMORDERCOLS.A Transact-SQL MOREINFO="NONE"select statement can contain an MOREINFO="NONE"order by clause, which determines how the rows resulting from the MOREINFO="NONE"select are ordered on presentation.ID="IN4410832043"Retrievingcolumn ids of order-by columns
ID="IN447832044"Columnsretrieving the column idÕ s of order-by columnsRetrieving the Column ID's of Order-By ColumnsMARK="BULL" REMAP="BU--Bullet"To get the select list column id's of order-by columns, call MOREINFO="NONE"ct_res_info with type as CS_ORDERBY_COLS.Columns named in an MOREINFO="NONE"order by clause must also be named in the select list of theMOREINFO="NONE" select statement. Columns in a select list have a "select list id," which is the number in which they appear in the list. For example, in the following query, MOREINFO="NONE"au_lname and MOREINFO="NONE"au_fname have select list id's of 1 and 2 respectively:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"     select au_lname, au_fname from authors          order by au_fname, au_lnameGiven the preceding query, the call:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"     ct_res_info(cmd, CS_ORDERBY_COLS, myspace, 8,          outlength)REMAP="UN--Under"sets MOREINFO="NONE"*myspace to an array of two CS_INTs containing the integers 2 and 1.ID="IN4410832045"Retrievingnumber of rows for current command
ID="IN444832046"Rowsnumber of rows affected by most recent commandRetrieving the Number of Rows for the Current CommandMARK="BULL" REMAP="BU--Bullet"To determine the number of rows affected by the current command, call MOREINFO="NONE"ct_res_info with type as CS_ROW_COUNT.An application can retrieve a row count after MOREINFO="NONE"ct_results sets its *result_type parameter to CS_CMD_SUCCEED, CS_CMD_DONE, or CS_CMD_FAIL. A row count is guaranteed to be accurate if MOREINFO="NONE"ct_results has just set *result_type to CS_CMD_DONE.If the command is one that executes a stored procedure, for example a Transact-SQL MOREINFO="NONE"exec language command or a remote procedure call command, MOREINFO="NONE"ct_res_info sets *MOREINFO="NONE"buffer to the number of rows affected by the last statement in the stored procedure that affects rows.MOREINFO="NONE"ct_res_info sets *buffer to CS_NO_COUNT if any of the following are true: MARK="DASH" REMAP="BS--BulletSub"The Transact-SQL command fails for any reason, such as a syntax error. The command is one that never affects rows, such as a Transact-SQL MOREINFO="NONE"print command. The command executes a stored procedure that does not affect any rows.The CS_OPT_NOCOUNT option is on. ID="IN4410832047"Retrievingcurrent server transaction state
ID="IN4418832048"Transaction statesretrieving the current server transaction stateRetrieving the Current Server Transaction StateMARK="BULL" REMAP="BU--Bullet"To determine the current server transaction state, call MOREINFO="NONE"ct_res_info with type as CS_TRANS_STATE.For more information about server transaction states, see LINKEND="X41110""Server Transaction States" 
.ID="IN4411812249"ct_res_infocode exampleExampleREMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"...CODE DELETED.....REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"CS_INT   num_cols;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"*/** Determine the number of columns in this result ** set.*/retcode = ct_res_info(cmd, CS_NUMDATA, &num_cols,     CS_UNUSED, NULL);if (retcode != CS_SUCCEED){     ...CODE DELETED.....}REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"...CODE DELETED.....REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"case CS_MSG_RESULT:     retcode = ct_res_info(cmd, CS_MSGTYPE,         (CS_VOID *)&msg_id, CS_UNUSED, NULL);    if (retcode != CS_SUCCEED)    {         ...CODE DELETED.....    }    fprintf(stdout, "ct_result returned \        CS_MSG_RESULT where msg id = %d.\n", msg_id);     break;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"...CODE DELETED.....REMAP="BO--Body"This code excerpt is from the rpc.c example program. For further examples of using MOREINFO="NONE"ct_res_info, see the compute.c, ex_alib.c, exutils.c, and i18n.c example programs.See AlsoREMAP="BO--Body"LINKEND="X90797"ct_cmd_props
MOREINFO="NONE", LINKEND="X57953"ct_con_props
MOREINFO="NONE", LINKEND="X57817"ct_results
MOREINFO="NONE", LINKEND="X98856"Options
ID="IN4411782552"ct_res_info
ID="IN4410752853"ct_resultsID="X57817"ct_resultsID="IN457752955"Resultsprocessing
ID="IN4518723256"Processing resultsSee Also Results
ID="IN4518723257"Processing results
Set up result data to be processed. REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_results(cmd, result_type) CS_COMMAND     *cmd;CS_INT         *result_type;ParametersREMAP="RI--RefIndent"cmd - A pointer to the CS_COMMAND structure managing a client/ server operation. result_type - A pointer to an integer variable which MOREINFO="NONE"ct_results sets to indicate the current type of result.REMAP="UN--Under"The following table lists the possible values of *result_type:TOCENTRY="1"LBL="Table 3-94: "Values for *result_type (MOREINFO="NONE"ct_results)COLS="4" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="67*"COLNAME="C2" COLWIDTH="123*"COLNAME="C3" COLWIDTH="105*"COLNAME="C4" COLWIDTH="176*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Value of *MOREINFO="NONE"result_type:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"What it indicates:COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Result set contains:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Values that 
indicate 
command 
statusCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CMD_DONECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The results of a 
logical command 
have been 
completely 
processed.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Not applicable.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CMD_FAILCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The server 
encountered an error 
while executing a 
command.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CMD_SUCCEEDCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The success of a 
command that 
returns no data, such 
as a language 
command 
containing a 
Transact-SQL MOREINFO="NONE"insert 
statement.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Values that 
indicate 
fetchable 
resultsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_COMPUTE_RESULTCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Compute row 
results.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A single row of compute results.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CURSOR_RESULTCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Cursor row results.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Zero or more rows of tabular data.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_PARAM_RESULTCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Return parameter 
results.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A single row of return parameters.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_ROW_RESULTCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Regular row results.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Zero or more rows of tabular data.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_STATUS_RESULTCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Stored procedure 
return status results.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A single row containing a single 
status.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Values that 
indicate 
information 
is available.COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_COMPUTEFMT_
RESULTCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Compute format 
information.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No fetchable results. An application 
can call MOREINFO="NONE"ct_describe, MOREINFO="NONE"ct_res_info, andMOREINFO="NONE" 
ct_compute_info to retrieve compute 
format information.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_ROWFMT_RESULTCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Row format 
information.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No fetchable results. An application 
can call MOREINFO="NONE"ct_describe and MOREINFO="NONE"ct_res_info to 
retrieve row format information.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_MSG_RESULTCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Message arrival.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No fetchable results. An application 
can call MOREINFO="NONE"ct_res_info to get the 
message's id. Parameters associated 
with the message, if any, are returned 
as a separate parameter result set.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DESCRIBE_RESULTCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Dynamic SQL 
descriptive 
information.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No fetchable results. An application 
can call MOREINFO="NONE"ct_describe or MOREINFO="NONE"ct_dyndesc to 
retrieve the information.ReturnsTOCENTRY="1"LBL="Table 3-95: "Return values (MOREINFO="NONE"ct_results)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="106*"COLNAME="C2" COLWIDTH="253*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A result set is available for processing.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_END_RESULTSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"All results have been completely processed. COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed; any remaining results are no longer 
available.

If MOREINFO="NONE"ct_results returns CS_FAIL, an application must call 
MOREINFO="NONE"ct_cancel with type as CS_CANCEL_ALL before using 
the affected command structure to send another 
command. 

If MOREINFO="NONE"ct_cancel returns CS_FAIL, the application must call 
MOREINFO="NONE"cs_close(CS_FORCE_CLOSE) to force the connection 
closed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CANCELEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Results have been canceled.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_PENDINGCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Asynchronous network I/O is in effect. For more 
information, see the MOREINFO="NONE"Asynchronous Programming topics 
page.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BUSYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An asynchronous operation is already pending for this 
connection. For more information, see the 
MOREINFO="NONE"Asynchronous Programming topics page.CommentsID="IN4510703462"ct_resultswhen to useMARK="BULL" REMAP="BU--Bullet"An application calls MOREINFO="NONE"ct_results after sending a command to the server via MOREINFO="NONE"ct_send, and before reading the results of that command (if any) via MOREINFO="NONE"ct_fetch. ID="IN4511703463"Result datadefinition of"Result data" is an umbrella term for all the types of data that a server can return to an application. These types of data include: ID="IN4519703464"Regular row resultsprocessingMARK="DASH" REMAP="BS--BulletSub"Regular rowsID="IN4518703465"Cursor row resultsprocessingCursor rowsID="IN4517703466"Return parametersprocessingReturn parametersID="IN4517703467"Stored proceduresreturn status processingStored procedure return status numbersID="IN4511703468"Compute rowprocessingCompute rowsID="IN4511703469"Dynamic SQLprocessing descriptive informationDynamic SQL descriptive informationID="IN4518703470"Format informationprocessingRegular row and compute row format informationID="IN4515703471"Message resultsprocessingMessagesREMAP="UN--Under"MOREINFO="NONE"ct_results is used to set up all of these types of results for processing Don't confuse message results with server error and informational messages. See the LINKEND="X46924""Error and Message Handling" topics page for a discussion of error and informational messages.Result data is returned to an application in the form of a "result set". A result set includes only a single type of result data. For example, a regular row result set contains only regular rows, and a return parameter result set contains only return parameters.ID="IN4510683672"ct_resultsprocessing results in a loopThe MOREINFO="NONE"ct_results LoopID="IN457663873"ResultsResultsthe ct_results loopct_results loopMARK="BULL" REMAP="BU--Bullet"Because a command can generate a result set that spans multiple buffers, an application must call MOREINFO="NONE"ct_results as long as it continues to return CS_SUCCEED, indicating that results are available. The simplest way to do this is in a loop that terminates when MOREINFO="NONE"ct_results fails to return CS_SUCCEED. After the loop, an application can use a case-type statement to test MOREINFO="NONE"ct_results' final return code to determine why the loop terminated.Results are returned to an application in the order in which they are produced. However, this order is not always easy to predict. For example, when an application calls a stored procedure that in turn calls another stored procedure, the application might receive a number of regular row and compute row result sets, as well as a return parameter and a return status result set. The order in which these results are returned depends on how the stored procedures are written.REMAP="UN--Under"For this reason, it is recommended that an application's MOREINFO="NONE"ct_results loop be coded so that control drops into a case-type statement that handles all types of results that can be received. The return parameter result_type indicates symbolically what type of result data the result set contains. ID="IN457663874"Resultscompletely processedID="X17772"When are the Results of a Command Completely Processed?MARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"ct_results sets *result_type to CS_CMD_DONE to indicate that the results of a "logical command" have been completely processed.A logical command is defined as any command defined via MOREINFO="NONE"ct_command, MOREINFO="NONE"ct_dynamic, or MOREINFO="NONE"ct_cursor, with the following exceptions:MARK="DASH" REMAP="BS--BulletSub"Each Transact-SQL MOREINFO="NONE"select statement inside a stored procedure is a logical command. Other Transact-SQL statements inside stored procedures do not count as logical commands.Each Transact-SQL statement executed by a dynamic SQL command is a distinct logical command. Each Transact-SQL statement in a language command is a logical command.For example, suppose a Client-Library language command contains the following Transact-SQL statements:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"     select type, price          from titles          order by type, price          compute sum(price) by typeREMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"     select type, price, advance          from titles          order by type, advance          compute sum(price), max(advance) by typeREMAP="UN--Under"When calling MOREINFO="NONE"ct_results to process the results of this language command, an application would see the following *result_types:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"CS_ROW_RESULT       Row and compute results fromCS_COMPUTE_RESULT   the first select,...                 repeated as many times as the                    value of the type column                    changes.CS_CMD_DONE         Indicates that the results                     of the first query have been                    processed.REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"CS_ROW_RESULT       Row and compute results fromCS_COMPUTE_RESULT   the second select,...                 repeated as many times as the                    value of the type column                    changes.CS_CMD_DONE         Indicates that the results of                     the second query have been                     processed.A *result_type of CS_CMD_SUCCEED or CS_CMD_FAIL is immediately followed by a *result_type of CS_CMD_DONE.A connection has pending results if it has not processed all of the results generated by a Client-Library command. Usually, an application cannot send a new command on a connection with pending results. An exception to this rule occurs for CS_CURSOR_RESULT results. For more information on this exception, see "Connection and Command Rules" in Chapter 3, "Structures, Datatypes, Constants, and Conventions," of the Open Client Client-Library Programmer's Guide.ID="IN457663878"Resultscanceling resultsCanceling ResultsID="IN459663879"Cancelingremaining resultsMARK="BULL" REMAP="BU--Bullet"To cancel all remaining results from a command (and eliminate the need to continue calling MOREINFO="NONE"ct_results until it fails to return CS_SUCCEED), call MOREINFO="NONE"ct_cancel with type as CS_CANCEL_ALL.ID="IN457663880"Resultscanceling current results
ID="IN459663881"Cancelingcurrent resultsTo cancel only the current results, call MOREINFO="NONE"ct_cancel with type as CS_CANCEL_CURRENT.Special Kinds of Result SetsMARK="BULL" REMAP="BU--Bullet"ID="IN4515663882"Message results
ID="IN457663883"Resultsmessage results
A message result set contains no actual result data. Rather, a message has an "id". An application can call MOREINFO="NONE"ct_res_info to get a message's id. In addition to an id, messages can have parameters. Message parameters are returned to an application as a parameter result set, immediately following the message result set.ID="IN4518663884"Row format results
ID="IN457663885"Resultsrow format results
Row format andID="IN4522663886"Compute format results
ID="IN457663887"Resultscompute format results
 compute format result sets contains no actual result data. Instead, format result sets contain formatting information for the regular row or compute row result sets with which they are associated.REMAP="UN--Under"This type of format information is of use primarily in gateway applications, which need to repackage SQL Server format information before sending it to a foreign client. After MOREINFO="NONE"ct_resultsID="IN4520663888"Gateway applicationsretrieving format information
indicates format results, a gateway application can retrieve format information by calling MOREINFO="NONE"ct_describe, MOREINFO="NONE"ct_res_info, and MOREINFO="NONE"ct_compute_info.ID="IN4518663889"Format informationprecedes actual dataREMAP="UN--Under"All format information for a command is returned before any data. That is, the row format and compute format result sets for a command precede the regular row and compute row result sets generated by the command.ID="IN4514644090"Format resultsCS_EXPOSE_FMTS must be enabledREMAP="UN--Under"An application will not receive format results unless the Client-Library ID="IN4523624291"CS_EXPOSE_FMTS propertymust be enabled to receive format results
CS_EXPOSE_FMTS property is set to CS_TRUE.AID="IN4516624292"Describe results
ID="IN457624293"Resultsdescribe results
 describe result set contains no actual result data. Instead, a describe result set contains descriptive information generated by a dynamic SQL describe input or describe output command. After MOREINFO="NONE"ct_results indicates describe results, an application can retrieve information by calling MOREINFO="NONE"ct_describe and MOREINFO="NONE"ct_dyndesc.ID="IN4510604494"ct_resultsct_resultsand stored proceduresstored procedures
MOREINFO="NONE"ct_resultsID="IN4517584695"Stored proceduresStored proceduresand ct_resultsct_results
and Stored ProceduresID="IN4517584696"Stored proceduresrun-time errorsMARK="BULL" REMAP="BU--Bullet"A run-time error on a language command containing an MOREINFO="NONE"execute statement will generate a *result_type of CS_CMD_FAIL. For example, this occurs if the procedure named in the MOREINFO="NONE"execute statement cannot be found.REMAP="UN--Under"A run-time error on a statement inside a stored procedure will not generate a CS_CMD_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"ct_results will still return CS_SUCCEED. To check for run-time errors inside stored procedures, examine the procedure's return status number, which is returned as a return status result set immediately following the row and parameter results, if any, from the stored procedure. If the error generates a server message, it is also available to the application.ID="IN4510564897"ct_resultscode exampleExampleREMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/*** DoCompute(connection)*/REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"CS_STATIC CS_RETCODEDoCompute(connection)CS_CONNECTION    *connection;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     CS_RETCODE   retcode;     CS_COMMAND   *cmd;     /* Result type from ct_results */     CS_INT       res_type;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /* Use the pubs2 database */     ...CODE DELETED.....REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /*     ** Allocate a command handle to send the compute      ** query with.     */     ...CODE DELETED.....REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /*     ** Define a language command that contains a      ** compute clause.  SELECT is a MOREINFO="NONE"select statment      ** defined in the header file.     */     ...CODE DELETED.....REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /* Send the command to the server */     ...CODE DELETED.....REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /*     ** Process the results.       ** Loop while ct_results() returns CS_SUCCEED.     */     while ((retcode = ct_results(cmd, &res_type)) ==         CS_SUCCEED)     {         switch ((int)res_type)         {         case CS_CMD_SUCCEED:             /*             ** Command returning no rows             ** completed successfully.             */             break;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"             case CS_CMD_DONE:                   /*                 ** This means we're done with one result                 ** set.                 */                  break;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"             case CS_CMD_FAIL:                   /*                 ** This means that the server encountered                 ** an error while processing our command.                */                ex_error("DoCompute: ct_results() \                       returned CMD_FAIL");                  break;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"             case CS_ROW_RESULT:                   retcode = ex_fetch_data(cmd);                 if (retcode != CS_SUCCEED)                 {                     ex_error("DoCompute: ex_fetch_data()\                        failed");                        return retcode;               }              break;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"             case CS_COMPUTE_RESULT:                  retcode = FetchComputeResults(cmd);                  if (retcode != CS_SUCCEED)                 {                     ex_error("DoCompute: \                  FetchComputeResults() failed");                      return retcode;                       }                  break;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"             default:                 /* We got an unexpected result type */                      ex_error("DoCompute: ct_results() \                   returned unexpected result type");                       return CS_FAIL;                  }             }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"         /*         ** We've finished processing results. Let's check          ** the return value of ct_results() to see if          ** everything went ok.         */         switch ((int)retcode)         {              case CS_END_RESULTS:                    /* Everything went fine */                    break;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"            case CS_FAIL:                    /* Something went wrong */                    ex_error("DoCompute: ct_results() \                       failed");                    return retcode;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"            default:                   /* We got an unexpected return value */                   ex_error("DoCompute: ct_results() \                       returned unexpected result code");                  return retcode;             }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"            /* Drop our command structure */             ...CODE DELETED.....REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"            return retcode;}REMAP="BO--Body"This code excerpt is from the compute.c example program. For further examples of using MOREINFO="NONE"ct_results, see the csr_disp.c, ex_alib.c, exutils.c, getsend.c, i18n.c, and rpc.c example programs.See AlsoREMAP="BO--Body"LINKEND="X29013"ct_bind
MOREINFO="NONE", LINKEND="X39849"ct_command
MOREINFO="NONE", LINKEND="X36007"ct_cursor
MOREINFO="NONE", LINKEND="X64204"ct_describe
MOREINFO="NONE", LINKEND="X77746"ct_dynamic
MOREINFO="NONE", LINKEND="X65123"ct_fetch
MOREINFO="NONE", LINKEND="X69834"ct_send
ID="IN45105351100"ct_resultsREMAP="BO--Body"ID="X69834"ct_sendID="IN4389753"Commandssending to a server
Send a command to the server.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_send(cmd) CS_COMMAND     *cmd;ParametersREMAP="RI--RefIndent"cmd - A pointer to the CS_COMMAND structure managing a client/ server operation. Returns:TOCENTRY="1"LBL="Table 3-96: "Return values (MOREINFO="NONE"ct_send)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="108*"COLNAME="C2" COLWIDTH="252*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine completed successfully.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed.

For less serious failures, the application can call 
MOREINFO="NONE"ct_cancel(CS_CANCEL_ALL) to clean up the 
command structure.

For more serious failures, the application must call 
MOREINFO="NONE"cs_close(CS_FORCE_CLOSE) to force the connection 
closed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CANCELEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine was canceled.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_PENDINGCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Asynchronous network I/O is in effect. For more 
information, see the MOREINFO="NONE"Asynchronous Programming topics 
page.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BUSYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An asynchronous operation is already pending for this 
connection. For more information, see the 
MOREINFO="NONE"Asynchronous Programming topics page.CommentsID="IN4389758"Commandssteps in sending a command to a serverMARK="BULL" REMAP="BU--Bullet"Sending a command to a server is a four step process. To send a command to a server, an application must: MARK="DASH" REMAP="BS--BulletSub"Initiate the command by calling MOREINFO="NONE"ct_command, MOREINFO="NONE"ct_cursor, or MOREINFO="NONE"ct_dynamic. These routines set up internal structures that are used in building a command stream to send to the server. Pass parameters for the command (if required) by calling MOREINFO="NONE"ct_param once for each parameter that the command requires.Not all commands require parameters. For example, a remote procedure call command may or may not require parameters, depending on the stored procedure being called. Send the command to the server by calling MOREINFO="NONE"ct_send.Verify the success of the command by calling MOREINFO="NONE"ct_results.REMAP="UN--Under"This last step does not imply that an application need only call MOREINFO="NONE"ct_results once. An application needs to continue calling MOREINFO="NONE"ct_results until it no longer returns CS_SUCCEED. See the Open Client Client-Library/C Programmer's Guide for a discussion of processing results.An application can call MOREINFO="NONE"ct_cancel(CS_CANCEL_ALLID="IN4389759"Commandscanceling
) to cancel a command that has been initiated but not yet sent. REMAP="UN--Under"Once an application has sent a command, it must call MOREINFO="NONE"ct_results before calling MOREINFO="NONE"ct_cancel to cancel the command.MOREINFO="NONE"ct_sendID="IN43795710"ct_senddoesnÕ t wait for server response
uses an asynchronous write and not does wait for a response from the server. An application must call MOREINFO="NONE"ct_results to verify the success of the command and to set up the command results for processing. ID="IN43793911"ct_sendcode exampleExampleREMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/*** ex_execute_cmd()*/REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"CS_RETCODE      CS_PUBLICex_execute_cmd(connection, cmdbuf)CS_CONNECTION   *connection;CS_CHAR         *cmdbuf;{     CS_RETCODE   retcode;     CS_INT       restype;     CS_COMMAND   *cmd;     CS_RETCODE   query_code;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /*     ** Get a command handle, store the command string      ** in it, and send it to the server.     */     if ((retcode = ct_cmd_alloc(connection, &cmd)) !=        CS_SUCCEED)        {             ex_error("ex_execute_cmd: ct_cmd_alloc() \           failed");             return retcode;     }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     if ((retcode = ct_command(cmd, CS_LANG_CMD,         cmdbuf, CS_NULLTERM, CS_UNUSED)) !=         CS_SUCCEED)     {             ex_error("ex_execute_cmd: ct_command() \                 failed");             (void)ct_cmd_drop(cmd);             return retcode;     }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     if ((retcode = ct_send(cmd)) != CS_SUCCEED)     {             ex_error("ex_execute_cmd: ct_send() failed");             (void)ct_cmd_drop(cmd);             return retcode;     }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /*     ** Examine the results coming back. If any errors      ** are seen, the query result code (which we will      ** return from this function) will be set to FAIL.     */     ...CODE DELETED.....REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /* Clean up the command handle used */     if (retcode == CS_END_RESULTS)     {         retcode = ct_cmd_drop(cmd);         if (retcode != CS_SUCCEED)         {            query_code = CS_FAIL;        }     }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     else    {                    (void)ct_cmd_drop(cmd);                    query_code = CS_FAIL;               }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"               return query_code;          }REMAP="BO--Body"This code excerpt is from the exutils.c example program. For further examples of using MOREINFO="NONE"ct_send, see the compute.c, csr_disp.c, ex_alib.c, getsend.c, i18n.c, and rpc.c example programs.See AlsoREMAP="BO--Body"LINKEND="X39849"ct_command
MOREINFO="NONE", LINKEND="X36007"ct_cursor
MOREINFO="NONE", LINKEND="X77746"ct_dynamic
MOREINFO="NONE", LINKEND="X65123"ct_fetch
MOREINFO="NONE", LINKEND="X45322"ct_param
MOREINFO="NONE", LINKEND="X57817"ct_results
ID="IN437901214"ct_send
ID="IN4312871515"ct_send_dataID="X27057"ct_send_dataID="IN4418871617"Send-data commandsinitiating
ID="IN4414871618"Text and imagesending chunks of data to the server
Send a chunk of text or image data to the server.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_send_data(cmd, buffer, buflen) CS_COMMAND     *cmd;CS_VOID        *buffer;CS_INT         buflen;ParametersREMAP="RI--RefIndent"cmd - A pointer to the CS_COMMAND structure managing a client/ server operation. buffer - A pointer to the value to write to the server.buflen - The length, in bytes, of *buffer.REMAP="UN--Under"CS_NULLTERM is not a legal value for buflen.ReturnsTOCENTRY="1"LBL="Table 3-97: "Return values (MOREINFO="NONE"ct_send_data)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="106*"COLNAME="C2" COLWIDTH="253*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine completed successfully.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CANCELEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The send data operation was canceled.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_PENDINGCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Asynchronous network I/O is in effect. For more 
information, see the MOREINFO="NONE"Asynchronous Programming topics 
page.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BUSYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An asynchronous operation is already pending for this 
connection. For more information, see the 
MOREINFO="NONE"Asynchronous Programming topics page.CommentsID="IN4412851823"ct_send_datawhen to useMARK="BULL" REMAP="BU--Bullet"An application can use MOREINFO="NONE"ct_send_data to write a text or image value to a database column. This writing operation is actually an MOREINFO="NONE"update; that is, the column must have a value when MOREINFO="NONE"ct_send_data is called to write a new value.REMAP="UN--Under"This is because MOREINFO="NONE"ct_send_data uses text timestamp information when writing to the column, and a column does not have a valid text timestamp until it contains a value. The value contained in the text or image column can be NULL, but the NULL must be entered explicitly with the SQL MOREINFO="NONE"update statement.For information on the steps involved in using MOREINFO="NONE"ct_send_data to update a text or image column, see LINKEND="X31032""Updating a Text or Image Column" 
.ID="IN4418832024"Send-data commandsrequire a CS_IODESC structure
ID="IN4419792425"CS_IODESC structureCS_IODESC structureand ct_send_datact_send_dataIn order to perform a send-data operation, an application must have a current I/O descriptor, or CS_IODESC structure, describing the column value that will be updated:MARK="DASH" REMAP="BS--BulletSub"The textptr field of the CS_IODESC identifies the target column.The timestamp field of the CS_IODESC is the text timestamp of the column value. If timestamp does not match the current database text timestamp for the value, the update operation will fail.The total_txtlen field of the CS_IODESC indicates the total length, in bytes, of the column's new value. An application must call MOREINFO="NONE"ct_send_data in a loop to write exactly this number of bytes before calling MOREINFO="NONE"ct_send to indicate the end of the text or image update operation.The log_on_update of the CS_IODESC tells the server whether or not to log the update operation.The locale field of the CS_IODESC points to a CS_LOCALE structure that contains localization information for the new value, if any.REMAP="UN--Under"A typical application will change only the values of the locale, total_txtlen, and log_on_update fields before using an I/O descriptor in an update operation, but an application that is updating the same column value multiple times will need to change the value of the timestamp field as well.ID="IN4414792426"Text and imageupdating a text or image columnA successful text or image update generates a parameter result set that contains the new text timestamp for the text or image value. If an application plans to update the text or image value a second time, it must save this new text timestamp and copy it into the CS_IODESC for the value before calling MOREINFO="NONE"ct_data_info to define the CS_IODESC for the update operation.A text or image update operation is equivalent to a language command containing a Transact-SQL MOREINFO="NONE"update statement.The command space identified by cmd must be idle before a text or image update operation is initiated. A command space is idle if there are no active commands, pending results, or open cursors in the space.For more information on writing a text or image value, see LINKEND="X51184""Text and Image" 
.ID="IN4412772627"ct_send_datacode exampleExampleREMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/*** UpdateTextData()*/REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"CS_STATIC CS_RETCODEUpdateTextData(connection, textdata, newdata)CS_CONNECTION connection;TEXT_DATA     textdata;char          *newdata;{     CS_RETCODE  retcode;     CS_INT      res_type;     CS_COMMAND  *cmd;     CS_INT      i;     CS_TEXT     *txtptr;     CS_INT      txtlen;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /*     ** Allocate a command handle to send the text with     */     ...CODE DELETED.....REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /*     ** Inform Client-Library the next data sent will      ** be used for a text or image update.     */     if ((retcode = ct_command(cmd, CS_SEND_DATA_CMD,           NULL, CS_UNUSED, CS_COLUMN_DATA)) !=          CS_SUCCEED)     {          ex_error("UpdateTextData: ct_command() \               failed");         return retcode;     }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /*     ** Fill in the description information for the      ** update and send it to Client-Library.     */     txtptr = (CS_TEXT *)newdata;     txtlen = strlen(newdata);     /*     ** NOTE: The following is not needed...     **     strcpy(textdata->iodesc.name, "getsend_tbl.t");     textdata->iodesc.namelen = CS_NULLTERM;     */     textdata->iodesc.total_txtlen = txtlen;     textdata->iodesc.log_on_update = CS_TRUE;     retcode = ct_data_info(cmd, CS_SET, CS_UNUSED,          &textdata->iodesc);     if (retcode != CS_SUCCEED)     {         ex_error("UpdateTextData: ct_data_info() \                failed");          return retcode;     }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /*     ** Send the text one byte at a time. This is not     ** the best thing to do for performance reasons,     ** but does demonstrate that ct_send_data()     ** can handle arbitrary amounts of data.     */     for (i = 0; i < txtlen; i++, txtptr++)     {          retcode = ct_send_data(cmd, txtptr,               (CS_INT)1);          if (retcode != CS_SUCCEED)          {               ex_error("UpdateTextData: ct_send_data() \                    failed");               return retcode;          }     }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /*     ** ct_send_data() writes to internal network      ** buffers. To insure that all the data is      ** flushed to the server, a ct_send() is done.     */     if ((retcode = ct_send(cmd)) != CS_SUCCEED)     {     ex_error("UpdateTextData: ct_send() failed");     return retcode;     }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /* Process the results of the command */     while ((retcode = ct_results(cmd, &res_type)) ==          CS_SUCCEED)     {         switch ((int)res_type)          {               case CS_PARAM_RESULT:              /*               ** Retrieve a description of the               ** parameter data. Only timestamp data is               ** expected in this example.               */               retcode = ProcessTimestamp(cmd, textdata);              if (retcode != CS_SUCCEED)              {                    ex_error("UpdateTextData: \                        ProcessTimestamp() failed");                    /*                    ** Something failed, so cancel all                    ** results.                    */                    ct_cancel(NULL, cmd, CS_CANCEL_ALL);                    return retcode;              }              break;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"              case CS_CMD_SUCCEED:              case CS_CMD_DONE:               /*              ** This means that the command succeeded              ** or is finished.              */              break;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"             case CS_CMD_FAIL:             /*             ** The server encountered an error while             ** processing our command.             */             ex_error("UpdateTextData: ct_results() \                  returned CS_CMD_FAIL");             break;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"             default:             /*             ** We got something unexpected.             */             ex_error("UpdateTextData: ct_results() \                   returned unexpected result type");             /* Cancel all results */             ct_cancel(NULL, cmd, CS_CANCEL_ALL);             break;         }     }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"     /*     ** We're done processing results. Let's check the     **return value of ct_results() to see if      ** everything went ok.     */      ...CODE DELETED.....REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    return retcode;}REMAP="BO--Body"This code excerpt is from the getsend.c example program.See AlsoREMAP="BO--Body"LINKEND="X75519"ct_data_info
, LINKEND="X26819"ct_get_data
, LINKEND="X51184"Text and Image
ID="IN4412742930"ct_send_data
ID="IN4415713231"ct_sendpassthruID="X54893"ct_sendpassthruID="IN453713333"TDSsending a TDS packet to a server
Send a TDS (Tabular Data Stream) packet to a server.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_sendpassthru (cmd, sendptr) CS_COMMAND     *cmd;CS_VOID        *sendptr;ParametersREMAP="RI--RefIndent"cmd - A pointer to a CS_COMMAND structure. sendptr - A pointer to a buffer containing the TDS packet to be sent to the server.ReturnsTOCENTRY="1"LBL="Table 3-98: "Return values (MOREINFO="NONE"ct_sendpassthru)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"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_PASSTHRU_MORECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Packet sent successfully; more packets are 
available.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_PASSTHRU_EOMCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Packet sent successfully; no more packets are 
available.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CANCELLEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine was cancelled.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_PENDINGCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Asynchronous network I/O is in effect. For more 
information, see the MOREINFO="NONE"Asynchronous Programming 
topics page.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BUSYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An asynchronous operation is already pending for 
this connection. For more information, see the 
MOREINFO="NONE"Asynchronous Programming topics page.CommentsMARK="BULL" REMAP="BU--Bullet"TDS is a communications protocol used for the transfer of requests and request results between clients and servers. Under ordinary circumstances, non-gateway applications do not usually have to deal with TDS, because Client-Library manages the data stream. MOREINFO="NONE"ct_recvpassthru and MOREINFO="NONE"ct_sendpassthruID="IN4520713338"Gateway applicationsGateway applicationsand TDS pass-throughTDS pass-through
are useful in gateway applications. When an application serves as the intermediary between two parties (such as a client and a remote server, or 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"ct_sendpassthru sends a packet of bytes from the *sendptr buffer. Most commonly, sendptr will be *recvptr as returned by MOREINFO="NONE"srv_recvpassthru. sendptr can also be the address of a user-allocated buffer containing the packet to send.ID="IN453713339"TDSdefault packet sizes vary by platformDefault packet sizes vary by platform. On most platforms, a packet has a default size of 512 bytes. A connection can change its packet size via MOREINFO="NONE"ct_con_props.MOREINFO="NONE"ct_sendpassthru returns CS_PASSTHRU_EOM if the TDS packet in the buffer is marked EOM (End Of Message). If the TDS packet is not marked EOM, MOREINFO="NONE"ct_sendpassthru returns CS_PASSTHRU_MORE.A connection which is being used for a pass-through operation cannot be used for any other Client-Library function until CS_PASSTHRU_EOM has been received.See AlsoREMAP="BO--Body"LINKEND="X32025"ct_getloginfo
, LINKEND="X81597"ct_recvpassthru
, LINKEND="X72103"ct_setloginfo
ID="IN4515683641"ct_sendpassthru
ID="IN4513653942"ct_setloginfoID="X72103"ct_setloginfoID="IN463654044"TDStransferring login response information
ID="IN4626654045"Login response informationtransferring
Transfer TDS login response information from a CS_LOGINFO structure to a CS_CONNECTION structure.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_setloginfo (connection, loginfo) CS_CONNECTION       *connection;CS_LOGINFO          *loginfo;ParametersREMAP="RI--RefIndent"connection - A pointer to a CS_CONNECTION structure. A CS_CONNECTION structure contains information about a particular client/ server connection.loginfo - A pointer to a CS_LOGINFO structure.ReturnsTOCENTRY="1"LBL="Table 3-99: "Return values (MOREINFO="NONE"ct_setloginfo)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="106*"COLNAME="C2" COLWIDTH="253*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine completed successfully.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BUSYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An asynchronous operation is already pending for this 
connection. For more information, see the 
MOREINFO="NONE"Asynchronous Programming topics page.MOREINFO="NONE"CommentsMARK="BULL" REMAP="BU--Bullet"TDS (Tabular Data Stream) is a communications protocol used for the transfer of requests and request results between clients and servers.ID="IN4613614451"ct_setloginfofrees the CS_LOGINFO structureBecause MOREINFO="NONE"ct_setloginfo frees the CS_LOGINFO structure after transferring the TDS information, an application cannot re-use the ID="IN4620594652"CS_LOGINFO structurecannot be re-used
CS_LOGINFO. An application can get a new CS_LOGINFO by calling MOREINFO="NONE"ct_getloginfo.ID="IN4613574853"ct_setloginfowhen to useThere are two reasons an application might call MOREINFO="NONE"ct_setloginfo:MARK="DASH" REMAP="BS--BulletSub"If it is an Open Server gateway application using TDS pass-through.In order to copy login properties from an open connection to a newly-allocated connection structure.ID="IN4613555054"ct_setloginfowhen not to useDo not call MOREINFO="NONE"ct_setloginfo from within a completion callback routine. MOREINFO="NONE"ct_setloginfo calls system-level memory functions which may not be re-entrant.ID="IN463555055"TDSpass-through operationTDS Pass-ThroughID="IN463555056"TDSnegotiating a TDS formatMARK="BULL" REMAP="BU--Bullet"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 pass-through, the gateway 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"ct_setloginfo is the second of four calls, two of them Server Library calls, that allow a client and a remote server to negotiate a TDS format. The calls, which can only be made in an Open Server SRV_CONNECT event handler, are:NUMERATION="ARABIC" REMAP="S1--StepOne" CONTINUATION="RESTARTS" INHERITNUM="IGNORE"MOREINFO="NONE"srv_getloginfo to allocate a CS_LOGINFO structure and fill it with TDS information from a client login request.MOREINFO="NONE"ct_setloginfo to transfer the TDS information retrieved in step 1 from the CS_LOGINFO structure to a Client-Library CS_CONNECTION structure. The gateway uses this CS_CONNECTION structure in the MOREINFO="NONE"ct_connect call which establishes its connection with the remote server.MOREINFO="NONE"ct_getloginfo to transfer the remote server's response to the client's TDS information from the CS_CONNECTION structure into a newly-allocated CS_LOGINFO structure.MOREINFO="NONE"srv_setloginfo to send the remote server's response, retrieved in step 3, to the client.ID="IN4616555057"Login propertiescopying to new connectionCopying Login PropertiesREMAP="BO--Body"For information on using MOREINFO="NONE"ct_setloginfo to copy login properties from an open connection to a newly-allocated connection structure, see the MOREINFO="NONE"Properties topics page.See AlsoREMAP="BO--Body"LINKEND="X32025"ct_getloginfo
MOREINFO="NONE", LINKEND="X81597"ct_recvpassthru
MOREINFO="NONE", LINKEND="X54893"ct_sendpassthru
ID="IN4613525359"ct_setloginfoREMAP="BO--Body"ID="X46507"ct_wakeupID="IN43119753"Connectionscalling a completion callback
ID="INA43199754"Completion callbackcalling
Call a connection's completion callback.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE ct_wakeup(connection, cmd, function,                status) CS_CONNECTION   *connection;CS_COMMAND      *cmd;CS_INT          function;CS_RETCODE      status;ParametersREMAP="RI--RefIndent"connection - A pointer to the CS_CONNECTION structure whose completion callback will be called. A CS_CONNECTION structure contains information about a particular client/server connection.REMAP="UN--Under"Either connection or cmd must be non-NULL. REMAP="UN--Under"If connection is supplied, its completion callback is called. If connection is NULL, cmd's parent connection's completion callback is called.REMAP="UN--Under"If connection is supplied, it is passed as the connection parameter to the completion callback. If connection is NULL, cmd's parent connection is passed as the connection parameter to the completion callback.cmd - A pointer to the CS_COMMAND structure managing a client/ server operation. REMAP="UN--Under"Either connection or cmd must be non-NULL. REMAP="UN--Under"If connection is NULL, cmd's parent connection's completion callback is called. REMAP="UN--Under"cmd is passed as the command parameter to the completion callback. If cmd is NULL then NULL is passed for the command parameter.function - A symbolic value indicating which routine has completed. function can be a user-defined value. function is passed as the function parameter to the completion callback. The following table lists the symbolic values that are legal for function:TOCENTRY="1"LBL="Table 3-100: "Values for function (MOREINFO="NONE"ct_wakeup)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 MOREINFO="NONE"function:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"BLK_ROWXFERCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"blk_rowxfer has completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"BLK_SENDROWCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"blk_sendrow has completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"BLK_SENDTEXTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"blk_sendtext has completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"BLK_TEXTXFERCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"blk_textxfer has completedCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CT_CANCELCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_cancel has completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CT_CLOSECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_close has completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CT_CONNECTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_connect has completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CT_FETCHCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_fetch has completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CT_GET_DATACOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_get_data has completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CT_OPTIONSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_options has completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CT_RECVPASSTHRUCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_recvpassthru has completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CT_RESULTSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_results has completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CT_SENDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_send has completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CT_SEND_DATACOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_send_data has completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CT_SENDPASSTHRUCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"ct_sendpassthru has completed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A user-defined value. 
This value must be 
greater than or equal to 
CT_USER_FUNC.COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A user-defined function has completed.status - The return status of the completed routine. This value is passed as the status parameter to the completion callbackReturnsTOCENTRY="1"LBL="Table 3-101: "Return values (MOREINFO="NONE"ct_wakeup)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="106*"COLNAME="C2" COLWIDTH="253*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Returns:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine completed successfully.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BUSYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An asynchronous operation is already pending for this 
connection. For more information, see the 
MOREINFO="NONE"Asynchronous Programming topics page.CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"ct_wakeupID="IN43249579"Asynchronous programmingAsynchronous programmingand ct_wakeupct_wakeup
is intended for use in applications that create an asynchronous layer on top of Client-Library.ID="IN439911110"ct_wakeupct_wakupand CS_DISABLE_POLL propertyCS_DISABLE_POLL propertyAn application cannot call MOREINFO="NONE"ct_wakeup if the ID="IN4324871511"CS_DISABLE_POLL propertyCS_DISABLE_POLL propertyand ct_wakeupct_wakeup
CS_DISABLE_POLL property is set to CS_TRUE.See the callbacks topics page for information on completion callbacks.See theMOREINFO="NONE" Asynchronous Programming topics page for more information on using MOREINFO="NONE"ct_wakeup in asynchronous Client-Library applications.ID="IN439851712"ct_wakeupcode exampleExampleREMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"            ...CODE DELETED.....REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"            /* Force a wakeup on the connection handle */            retstat = ct_wakeup(connection, NULL,                EX_ASYNC_QUERY, status);            if (retstat != CS_SUCCEED)            {                 return retstat;            }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"            ...CODE DELETED.....REMAP="BO--Body"This code excerpt is from the ex_alib.c example program.See AlsoREMAP="BO--Body"LINKEND="X39627"ct_callback
, LINKEND="X67063"ct_poll
ID="IN439822015"ct_wakeupREMAP="BO--Body"GlossaryID="IN33510011"Arraydefinition ofarrayA structure composed of multiple identical variables which can be individually addressed.ID="IN331310012"Array bindingdefinition ofarray bindingThe process of binding a result column to an array variable. At fetch time, multiple rows' worth of the column are copied into the variable.ID="IN33510013"Batchdefinition ofbatchA group of commands or statements.A Client-Library command batch is one or more Client-Library commands terminated by an application's call to MOREINFO="NONE"ct_send. For example, an application can batch together commands to declare, set rows for, and open a cursor.A Transact-SQL statement batch is one or more Transact-SQL statements submitted to SQL Server by means of a single Client-Library command or Embedded SQL statement.ID="IN331110014"Browse modedefinition ofbrowse modeBrowse mode is a method that DB-Library and Client-Library applications can use to browse through database rows, updating their values one row at a time. Cursors provide similar functionality and are generally more portable and flexible.ID="IN33910015"Bulk copydefinition ofbulk copyA utility for copying data in and out of databases. Also called MOREINFO="NONE"bcp.ID="IN33910016"Callbacksdefinition ofcallbackA routine that Open Client or Open Server calls in response to a triggering event, known as a callback event.ID="IN331510017"Callback eventsdefinition ofcallback eventIn Open Client and Open Server, a callback event is an occurrence that triggers a callback routine.ID="IN331210018"Capabilitiesdefinition ofcapabilitiesA client/server connection's capabilities determine the types of client requests and server responses permitted for that connection.ID="IN331410019"Character setsdefinition ofcharacter setA set of specific (usually standardized) characters with an encoding scheme that uniquely defines each character. ASCII and ISO 8859-1 (Latin 1) are two common character sets.ID="IN3314100110"Character setscharacter set conversion:definition ofcharacter set conversionChanging the encoding scheme of a set of characters on the way into or out of a server. Conversion is used when a server and a client communicating with it use different character sets. For example, if SQL Server uses ISO 8859-1 and a client uses Code Page 850, character set conversion must be turned on so that both server and client interpret the data passing back and forth in the same way.ID="IN337100111"Clientsdefinition ofclientIn client/server systems, the client is the part of the system that sends requests to servers and processes the results of those requests.ID="IN3314100112"Client-Librarydefinition ofClient-LibraryPart of Open Client, Client-Library is 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.code setSee character set.collating sequenceSee sort order.ID="IN338100113"Commandsdefinition ofcommandIn Client-Library, a command is a server request initiated by an application's call to MOREINFO="NONE"ct_command, MOREINFO="NONE"ct_dynamic, or MOREINFO="NONE"ct_cursor and terminated by the application's call to MOREINFO="NONE"ct_send. ID="IN3317100114"Command structuredefinition ofcommand structureA command structure (CS_COMMAND) is a hidden Client-Library structure that Client-Library applications use to send commands and process results. ID="IN3320100115"Connection structuredefinition ofconnection structureA connection structure (CS_CONNECTION) is a hidden Client-Library structure that defines a client/server connection within a context.ID="IN3317100116"Context structuredefinition ofcontext structureA context structure (CS_CONTEXT) is a CS-Library hidden structure that defines an application "context," or operating environment, within a Client-Library or Open Server application. The CS-Library routines MOREINFO="NONE"cs_ctx_alloc and MOREINFO="NONE"cs_ctx_drop allocate and drop a context structure.conversionSee character set conversion.ID="IN3310100117"CS-Librarydefinition ofCS-LibraryIncluded with both the Open Client and Open Server products, CS-Library is a collection of utility routines that are useful to both Client-Library and Server-Library applications.ID="IN3311100118"Current rowdefinition ofcurrent rowWith respect to cursors, the current row is the row to which a cursor points. A fetch against a cursor retrieves the current row.ID="IN337100119"Cursorsdefinition ofcursorA cursor is a symbolic name that is associated with a SQL statement. In Embedded SQL, a cursor is a data selector that passes multiple rows of data to the host program, one row at a time.ID="IN338100120"Databasedefinition ofdatabaseA set of related data tables and other database objects that are organized to serve a specific purpose. ID="IN339100121"Datatypesdefinition ofdatatypeA defining attribute that describes the values and operations that are legal for a variable.ID="IN3310100122"DB-Librarydefinition ofDB-LibraryPart of Open Client, DB-Library is a collection of routines for use in writing client applications.ID="IN338100123"Deadlockdefinition ofdeadlockA situation that arises when two users, each having a lock on one piece of data, attempt to acquire a lock on the other's piece of data. SQL Server detects deadlocks and resolves them by killing one user's process. ID="IN337100124"Defaultdefinition ofdefaultDescribes the value, option, or behavior that Open Client/Server products use when none is explicitly specified.ID="IN3316100125"Default databasedefinition ofdefault databaseThe database that a user gets by default when he or she logs in to a database server.ID="IN3316100126"Default languagedefinition ofdefault language1. The language that Open Client/Server products use when an application does no explicit localization. The default language is determined by the "default" entry in the locales file. 2. The language that SQL Server uses for messages and prompts when a user has not explicitly chosen a language.ID="IN3315100127"Descriptor areadefinition ofdescriptor areaThe area that a DBMS uses to store information about dynamic parameters in a dynamic SQL statement.ID="IN3311100128"Dynamic SQLdefinition ofdynamic SQLDynamic SQL allows an Embedded SQL or Client-Library application to execute SQL statements containing variables whose values are determined at run-time.ID="IN3313100129"Error messagedefinition oferror messageA message that an Open Client/Server product issues when it detects an error condition.ID="IN336100130"Eventsdefinition ofeventAn occurrence that prompts an Open Server application to take certain actions. Client commands and certain commands within Open Server application code can trigger events. When an event occurs, Open Server calls either the appropriate event-handling routine in the application code or the appropriate default event handler.ID="IN3313100131"Event handlerdefinition ofevent handlerIn Open Server, a routine that processes an event. An Open Server application can use the default handlers Open Server provides or can install custom event handlers. ID="IN3318100132"Exposed structuresdefinition ofexposed structureAn exposed structure is a structure whose internals are exposed to Open Client/Server programmers. Open Client/Server programmers can declare, manipulate, and de-allocate exposed structures directly. The CS_DATAFMT structure is an example of an exposed structure.ID="IN3320100133"Extended transactiondefinition ofextended transactionIn Embedded SQL, an extended transaction is a transaction composed of multiple Embedded SQL statements.ID="IN334100134"FIPSdefinition ofFIPSFIPS is an acronym for Federal Information Processing Standards. If FIPS flagging is enabled, SQL Server or the Embedded SQL precompiler issue warnings when a non-standard extension to a SQL statement is encountered.ID="IN337100135"Gatewaydefinition ofgatewayA gateway is an application that acts as an intermediary for clients and servers that cannot communicate directly. Acting as both client and server, a gateway application passes requests from a client to a server and returns results from the server to the client.ID="IN3317100136"Hidden structuresdefinition ofhidden structureA hidden structure is a structure whose internals are hidden from Open Client/Server programmers. Open Client/Server programmers must use Open Client/Server routines to allocate, manipulate, and de-allocate hidden structures. The CS_CONTEXT structure is an example of a hidden structure.ID="IN3313100137"Host languagedefinition ofhost languageThe programming language in which an application is written.ID="IN3312100138"Host programdefinition ofhost programIn Embedded SQL, the host program is the application program that contains the Embedded SQL code.ID="IN3313100139"Host variabledefinition ofhost variableIn Embedded SQL, a variable which enables data transfer between SQL Server and the application program. See also indicator variable, input variable, output variable, result variable, and status variable.ID="IN3318100140"Indicator variabledefinition ofindicator variableA variable whose value indicates special conditions about another variable's value or about fetched data.When used with an Embedded SQL host variable, an indicator variable indicates when a database value is null.ID="IN3314100141"Input variabledefinition ofinput variableA variable that is used to pass information to a routine, a stored procedure, or SQL Server.ID="IN3315100142"Interfaces filedefinition ofinterfaces fileA file that maps server names to transport addresses. When a client application calls MOREINFO="NONE"ct_connect or MOREINFO="NONE"dbopen to connect to a server, Client-Library or DB-Library searches the interfaces file for the server's address. Note that not all platforms use the interfaces file. On these platforms, an alternate mechanism directs clients to server addresses.ID="IN331698343"isql script filedefinition ofisql script fileIn Embedded SQL, an isql script file is one of the three files the precompiler can generate. An isql script file contains precompiler-generated stored procedures, which are written in Transact-SQL.ID="IN33398344"Keydefinition ofkeyA subset of row data that uniquely identifies a row. Key data uniquely describes the current row in an open cursor.ID="IN33798345"Keyworddefinition ofkeywordA word or phrase that is reserved for exclusive use in Transact-SQL or Embedded SQL. Also called a reserved word. ID="IN331298346"Listing filedefinition oflisting fileIn Embedded SQL, a listing file is one of the three files the precompiler can generate. A listing file contains the input file's source statements and informational, warning, and error messages.ID="IN331298347"Locales filedefinition oflocales fileA file that maps locale names to language/character set pairs. Open Client/Server products search the locales file when loading localization information.ID="IN331198348"Locale namedefinition oflocale nameA character string that represents a language/character set pair. Locale names are listed in the locales file. SYBASE predefines some locale names, but a system administrator can define additional locale names and add them to the locales file.ID="IN331698349"Locale structuredefinition oflocale structureA locale structure (CS_LOCALE) is a CS-Library hidden structure that defines custom localization values for a Client-Library or Open Server application. An application can use a CS_LOCALE to define the language, character set, datepart ordering, and sort order it will use. The CS-Library routines MOREINFO="NONE"cs_loc_alloc and MOREINFO="NONE"cs_loc_drop allocate and drop a locale structure.ID="IN331298350"Localizationdefinition oflocalizationLocalization is the process of setting up an application to run in a particular national language environment. An application that is localized typically generates messages in a local language and character set and uses local datetime formats.ID="IN331098351"Login namedefinition oflogin nameThe name a user uses to log in to a server. A SQL Server login name is valid if SQL Server has an entry for that user in the system table syslogins. ID="IN331498352"Message numberdefinition ofmessage numberA number that uniquely identifies an error message. ID="IN331398353"Message queuedefinition ofmessage queueIn Open Server, a linked list of message pointers through which threads communicate. Threads can write messages into and read messages from the queue.ID="IN332498354"Multi-byte character setdefinition ofmulti-byte character setA character set that includes characters encoded using more than one byte. EUC JIS and Shift-JIS are examples of multi-byte character sets.ID="IN33598355"Mutexdefinition ofmutexA mutual exclusion semaphore. This is a logical object that an Open Server application uses to ensure exclusive access to a shared object.ID="IN33498356"Nulldefinition ofnullHaving no explicitly assigned value. NULL is not equivalent to zero, or to blank. A value of NULL is not considered to be greater than, less than, or equivalent to any other value, including another value of NULL. ID="IN331198357"Open Serverdefinition ofOpen ServerA SYBASE product than provides tools and interfaces for creating custom servers.ID="IN332398358"Open Server applicationdefinition ofOpen Server applicationA custom server constructed with Open Server.ID="IN331598359"Output variabledefinition ofoutput variableIn Embedded SQL, a variable which passes data from a stored procedure to an application program.ID="IN331098360"Parametersdefinition ofparameter1. A variable that is used to pass data to and retrieve data from a routine. 2. An argument to a stored procedure.ID="IN331798361"Pass-through modedefinition ofpass-through modeA state of being pertaining to gateway applications. When in pass-through mode, a gateway relays Tabular Data Stream (TDS) packets between a client and a remote data source without unpacking the packets' contents.ID="IN331098362"Propertiesdefinition ofpropertyA property is a named value stored in a structure. Context, connection, thread, and command structures have properties. A structure's properties determine how it behaves.ID="IN33598363"Querydefinition ofquery1. A data retrieval request; usually a MOREINFO="NONE"select statement. 2. Any SQL statement that manipulates data. ID="IN332198364"Registered proceduresdefinition ofregistered procedureIn Open Server, a collection of C statements stored under a name. Open Server-supplied registered procedures are called system registered procedures. ID="IN332298365"Remote procedure callsdefinition ofremote procedure call1. One of two ways in which a client application can execute a SQL Server stored procedure. (The other is with a Transact-SQL MOREINFO="NONE"execute statement.) A Client-Library application initiates a remote procedure call command by calling MOREINFO="NONE"ct_command. A DB-Library application initiates a remote procedure call command by calling MOREINFO="NONE"dbrpcinit.2. A type of request a client can make of an Open Server application. In response, Open Server either executes the corresponding registered procedure or calls the Open Server application's RPC event handler. 3. A MOREINFO="NONE"stored procedure executed on a different server from the server to which the user is connected.result variableIn Embedded SQL, a variable which receives the results of a MOREINFO="NONE"select or MOREINFO="NONE"fetch statement.ID="IN33698366"Serverdefinition ofserverIn client/server systems, the server is the part of the system that processes client requests and returns results to clients.ID="IN331498367"Server-Librarydefinition ofServer-LibraryA collection of routines for use in writing Open Server applications.ID="IN331098368"Sort orderdefinition ofsort orderUsed to determine the order in which character data is sorted. Also called collating sequence.ID="IN331596569"SQLCA structuredefinition ofsqlca1. In an Embedded SQL application, a SQLCA is a structure that provides a communication path between SQL Server and the application program. After executing each SQL statement, SQL Server stores return codes in the SQLCA.2. In a Client-Library application, a SQLCA is a structure that the application can use to retrieve Client-Library and server error and informational messages.ID="IN331794770"SQLCODE structuredefinition ofsqlcode1. In an Embedded SQL application, a SQLCODE is a structure that provides a communication path between SQL Server and the application program. After executing each SQL statement, SQL Server stores return codes in the SQLCODE. A SQLCODE can exist independently or as a variable within a SQLCA structure.2. In a Client-Library application, a SQLCODE is a structure that the application can use to retrieve Client-Library and server error and informational message codes.ID="IN331094771"SQL Serverdefinition ofSQL ServerA server in Sybase's client/server architecture. SQL Server manages multiple databases and multiple users, keeps track of the actual location of data on disks, maintains mapping of logical data description to physical data storage, and maintains data and procedure caches in memory.ID="IN33994772"Statementdefinition ofstatementIn Transact-SQL or Embedded SQL, an instruction that begins with a keyword. The keyword names the basic operation or command to be performed. ID="IN331594773"Status variabledefinition ofstatus variableIn Embedded SQL, a variable which receives the return status value of a stored procedure, thereby indicating the procedure's success or failure.ID="IN331794774"Stored proceduresdefinition ofstored procedureIn SQL Server, a collection of SQL statements and optional control-of-flow statements stored under a name. SQL Server-supplied stored procedures are called system procedures. ID="IN332094775"System Administratordefinition ofSystem AdministratorThe user in charge of server system administration, including creating user accounts, assigning permissions, and creating new databases. On SQL Server, the System Administrator's login name is sa. ID="IN331794776"System descriptordefinition ofsystem descriptorIn Embedded SQL, a system descriptor is an area of memory that holds a description of variables used in Dynamic SQL statements. ID="IN331794777"System proceduresdefinition ofsystem proceduresStored procedures that SQL Server supplies for use in system administration. These procedures are provided as shortcuts for retrieving information from system tables, or as mechanisms for accomplishing database administration and other tasks that involve updating system tables. ID="IN332894778"System registered proceduresdefinition ofsystem registered proceduresInternal registered procedures that Open Server supplies for registered procedure notification and status monitoring. ID="IN331194779"Target filedefinition oftarget fileIn Embedded SQL, a target file is one of the three files the precompiler can generate. A target file is similar to the original input file, except that all SQL statements are converted to Client-Library function calls.ID="IN33394780"TDSdefinition ofTDS(Tabular Data Stream) An application-level protocol that SYBASE clients and servers use to communicate. It transfers requests and results between clients and servers.ID="IN33694781"Threaddefinition ofthreadA path of execution through Open Server application and library code and the path's associated stack space, state information, and event handlers.ID="IN331294782"Transact-SQLdefinition ofTransact-SQLTransact-SQL is an enhanced version of the database language SQL. Applications can use Transact-SQL to communicate with SYBASE SQL Server.ID="IN331194783"Transactiondefinition oftransactionOne or more server commands that are treated as a single unit. Commands within a transaction are committed as a group; that is, either all of them are committed or all of them are rolled back.ID="IN331694784"Transaction modedefinition oftransaction modeTransaction mode refers to the manner in which SQL Server manages transactions. SQL Server supports two transaction modes: Transact-SQL mode (also called "unchained transactions") and ANSI mode (also called "chained transactions").user nameSee login name.