#EDIR DATA#
DOCTYPE='BOOK' PUBLICID='-//SYBOOKS//Default DTD//EN' SYSTEMID=''DOCTYPE='book' PUBLICID='' SYSTEMID=''Open Client and Open Server Common Libraries Reference ManualOpen Clientname='trade' font='symbol' code='228'  charset='fontspecific' and Open Servername='trade' font='symbol' code='228'  charset='fontspecific'Common Libraries Reference ManualREMAP="titleBO--Body"Open Client and Open Server Release 10.0REMAP="titleBO--Body"Document ID: 32850-00-1000-04REMAP="titleBO--Body"Change Level: 2REMAP="titleBO--Body"Last Revised: May 15, 1994Principal authorship: Pegler Swift, Stacia SambarDocument ID: 32850-00-1000REMAP="discBO--Body"This publication pertains to Open Client and Open Server 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 and Open Server Common Libraries Reference Manual, contains reference information on:MARK="BULL" REMAP="BU--Bullet"The C version of CS-Library. CS-Library contains utility routines useful to both Open Client Client-Libraryname='trade' font='symbol' code='228'  charset='fontspecific' and Open Server Server-Libraryname='trade' font='symbol' code='228'  charset='fontspecific' applications.Client-Library and Server-Library bulk copy routines. Bulk copy is a tool for the high-speed transfer of data between a database table and program variables.RENDERAS="SECT1"AudienceREMAP="BO--Body"The Common Libraries Reference Manual is designed to serve as a reference manual for programmers who are writing Client-Library or Open Server applications. It is written for application programmers familiar with the C programming language.RENDERAS="SECT1"How to Use This BookREMAP="BO--Body"When writing an Open Client or Open Server application, use the Common Libraries Reference Manual as a source of reference information.REMAP="BO--Body"LINKEND="X26139"Chapter 1,  "Introducing CS-Library,"
 contains a brief introduction to CS-Library. REMAP="BO--Body"LINKEND="X98950"Chapter 2,  "CS-Library Routines,"
 contains specific information about each CS-Library routine, such as what parameters the routine takes and what it returns.REMAP="BO--Body"LINKEND="X73052"Chapter 3,  "Introducing Bulk Copy,"
 contains a brief introduction to bulk copy.REMAP="BO--Body"LINKEND="X73052"Chapter 4,  "Bulk Copy Routines,"
 contains specific information on each bulk copy routine.RENDERAS="SECT1"Related DocumentsREMAP="BO--Body"The Client-Library Programmer's Guide contains information on how to design and implement Client-Library programs.REMAP="BO--Body"The Client-Library Reference Manual contains reference information for Client-Library.REMAP="BO--Body"The Open Server Server-Library Reference Manual contains reference information for Server-Library.REMAP="BO--Body"The Open Client/Server Supplement contains platform-specific material for Open Client/Server products. This document includes information about:MARK="BULL" REMAP="BU--Bullet"Open Client/Server 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 that 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 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"CS-Library routine syntax is shown in a bold monospace font:REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"  CS_RETCODE cs_ctx_alloc(version, ctx_pointer)   CS_INT             version;  CS_CONTEXT         **ctx_pointer;REMAP="BO--Body"Program text and computer output are shown in a monospace font:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"cs_ctx_alloc(CS_VERSION_100, &context);REMAP="BO--Body"Structure names and symbolic constants are written in small capital letters:REMAP="BO--Body"       CS_CONTEXT, CS_EXTRA_INFREMAP="BO--Body"Routine names and Transact-SQL keywords are written in a narrow, bold font:REMAP="UN--Under"MOREINFO="NONE"cs_ctx_alloc, 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 and Server-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 CS-Library, Client-Library, or Server-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 CS-Library and bulk copy 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"Each SYBASE installation has a designated person to contact Sybase Technical Support. If you cannot resolve your problem with the manuals or on-line help, ask the designated person at your site to contact Technical Support.REMAP="BO--Body"NUMBER="1" ID="X26139"Introducing CS-LibraryID="IN1-10011"CS-Librarywhat it isRENDERAS="SECT1"What Is CS-Library?REMAP="BO--Body"CS-Library ("Client/Server Library") is a collection of utility routines for use in application programs.REMAP="BO--Body"CS-Library includes routines to support:MARK="BULL" REMAP="BU--Bullet"Datatype conversionArithmetic operationsCharacter set conversionDatetime operationsSort order operationsLocalized error messagesREMAP="BO--Body"CS-Library also includes routines to allocate and de-allocate CS-Library structures.REMAP="BO--Body"Although it is possible to write a stand-alone CS-Library application, the library's primary function is to provide common utilities to Client-Library and Server-Library applications.ID="IN1-10012"CS-Librarynecessary to Client-Library and Server-Library applicationsREMAP="BO--Body"Because Client-Library and Server-Library programs require a context structure, which can only be allocated using CS-Library, all Client-Library and Server-Library programs will include at least two calls to CS-Library - one to allocate a CS_CONTEXT and one to de-allocate it.REMAP="BO--Body"A context structure contains information about an application programming environment, or "context". For more information on the CS_CONTEXT, see LINKEND="X23056""Structures" 
.ID="IN1-10013"CS-Libraryhow to use itRENDERAS="SECT1"How to Use CS-LibraryREMAP="BO--Body"CS-Library routines can be called either from within a Client-Library or Server-Library application, or from within a stand-alone CS-Library application.RENDERAS="SECT2"Open Client and Open Server ApplicationsREMAP="BO--Body"Most typically, CS-Library routines are called from within a Client-Library or Server-Library application.ID="IN1-10014"Header filesREMAP="BO--Body"Because the standard Client-Library and Server-Library header files ID="IN1-9835"ctpublic.h header file
ID="IN1-9656"Header filesctpublic.h
ctpublic.h and ID="IN1-9477"ospublic.h header file
ID="IN1-9298"Header filesospublic.h
ospublic.h include the CS-Library header file ID="IN1-90119"cspublic.h header file
ID="IN1-881310"Header filescspublic.h
cspublic.h, it is not necessary for a Client-Library or Server-Library application to include a special header file in order to make CS-Library calls.REMAP="BO--Body"After calling ID="IN1-861511"cs_ctx_allocwhen to call
MOREINFO="NONE"cs_ctx_alloc to allocate a CS_CONTEXT, a Client-Library or Server-Library application is free to call any other CS-Library routines.RENDERAS="SECT2"A Stand-Alone CS-Library ApplicationREMAP="BO--Body"It is possible to write a stand-alone CS-Library application, though this is not a typical use of CS-Library routines.REMAP="BO--Body"This type of application needs to include the standard CS-Library header file, ID="IN1-841712"cspublic.h header file
ID="IN1-821913"Header filescspublic.h
cspublic.h.ID="X23056" RENDERAS="SECT1"StructuresID="IN1-782314"Context structureSee CS_CONTEXT structureREMAP="BO--Body"CS-Library makes use of several structures, including the CS_CONTEXT control structure, the ID="IN1-762515"CS_DATAFMT structure
ID="IN1-742716"StructuresCS_DATAFMT
CS_DATAFMT data format structure, and the ID="IN1-722917"CS_LOCALE structure
ID="IN1-703118"StructuresCS_LOCALE
CS_LOCALE locale information structure.REMAP="BO--Body"The CS_CONTEXTID="IN1-703119"Hidden structureshidden structures
 structure is a "hidden" data structure, whose internals are not available to an application. The CS_CONTEXT is discussed briefly in the following section. For more information, see the Client-Library Reference Manual, the Client-Library Programmer's Guide, or the Server-Library Reference Manual.REMAP="BO--Body"The CS_DATAFMT and CS_LOCALE structures are documented in Chapter 2, "Topics" in the Client-Library Reference Manual.ID="IN1-683320"CS_CONTEXT structure
ID="IN1-663521"StructuresCS_CONTEXTRENDERAS="SECT2"The CS_CONTEXT StructureREMAP="BO--Body"CS-Library defines a single control structure, the CS_CONTEXT. REMAP="BO--Body"A CS_CONTEXTID="IN1-643722"CS_CONTEXT structurepurpose
 is used to store configuration information that describes a particular programming context. An application must allocate a CS_CONTEXT structure before calling any other Client-Library, Server-Library, or CS-Library routine.ID="IN1-623923"CS_CONTEXT structureallocatingREMAP="BO--Body"An application allocates a CS_CONTEXT structure by calling MOREINFO="NONE"cs_ctx_alloc.ID="IN1-604124"CS_CONTEXT structurecustomizingREMAP="BO--Body"An application can customize a CS_CONTEXTID="IN1-604125"Context propertieschanging the values of
 by changing the values of context properties. The following routines change the values of context properties:MARK="BULL" REMAP="BU--Bullet"The CS-Library routine MOREINFO="NONE"cs_configThe Client-Library routine MOREINFO="NONE"ct_configThe Server-Library routine MOREINFO="NONE"srv_propsID="IN1-584326"CS_CONTEXT structurede-allocatingREMAP="BO--Body"An application should de-allocate all existing context structures before exiting. An application de-allocates a CS_CONTEXT structure by calling MOREINFO="NONE"cs_ctx_drop.RENDERAS="SECT1"Datatypes, Constants, and ConventionsREMAP="BO--Body"CS-Library uses the same datatypes, constants, and conventions as Client-Library and Server-Library. For information on these types, constants, and conventions, see:MARK="BULL" REMAP="BU--Bullet"Chapter 2, "Structures, Datatypes, Constants, and Conventions," in the Client-Library Programmer's GuideThe MOREINFO="NONE"Types topics page in the Client-Library Reference ManualThe MOREINFO="NONE"Types topics page in the Server-Library Reference ManualID="IN1-584327"Error handlingRENDERAS="SECT1"Error HandlingREMAP="BO--Body"All CS-Library routines return success or failure indications. It is highly recommended that applications check these return codes.REMAP="BO--Body"In addition, CS-Library routines can generate CS-Library messages, which range in severity from informational messages to fatal errors.ID="IN1-584328"Error handlingmethods of handling errorsRENDERAS="SECT2"Two Methods of Handling MessagesREMAP="BO--Body"An application can handle CS-Library messages in one of two ways:ID="IN1-584329"Message callbacksMARK="BULL" REMAP="BU--Bullet"By installing a callback routine to handle messages, or ID="IN1-584330"In-line message handlingIn-line, using the CS-Library routineMOREINFO="NONE" cs_diag.ID="IN1-584331"Message callbacksadvantagesREMAP="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. CS-Library automatically calls the appropriate message callback routine 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="IN1-584332"In-line message handlingadvantagesREMAP="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. ID="IN1-564533"Error handlingError handlingand cs_configcs_configREMAP="BO--Body"An application indicates which method it will use for a particular context either by calling ID="IN1-544734"Message callbacksMessage callbacksand cs_configcs_config
MOREINFO="NONE"cs_configID="IN1-524935"Error handlingError handlingand cs_diagcs_diag
 to install a message callback routine or by calling ID="IN1-505136"In-line message handlingIn-line message handlingand cs_diagcs_diag
MOREINFO="NONE"cs_diag to initialize in-line message handling.ID="IN1-505137"Error handlingswitching between error handling methodsREMAP="BO--Body"It is possible for an application to switch back and forth between the in-line and the callback method:ID="IN1-505138"Message callbacksconsequences of installing a message callback
ID="IN1-505139"Error handlingmessages can be discardedMARK="BULL" REMAP="BU--Bullet"Installing a message callback routine turns off in-line message handling. Any saved messages are discarded.ID="IN1-505140"In-line message handlingconsequences of initializingLikewise, calling MOREINFO="NONE"cs_diag to initialize in-line message handling de-installs the CS-Library message callback. If this occurs, the application's first CS_GET call to MOREINFO="NONE"cs_diag will retrieve a warning message to this effect.REMAP="BO--Body"If a message callback is not installed and in-line message handling is not enabled, CS-Library discards message information.ID="IN1-505141"Error handlingmessage callbacksRENDERAS="SECT2"Using a Callback to Handle MessagesREMAP="BO--Body"An application calls MOREINFO="NONE"cs_config to install a message callback.ID="IN1-505142"Message callbacksdefiningRENDERAS="SECT3"Defining a CS-Library Message CallbackREMAP="BO--Body"A CS-Library message callback is defined as follows:REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_INT cslibmsg_cb(context, message) CS_CONTEXT     *context;CS_CLIENTMSG   *message;REMAP="BO--Body"where:REMAP="RI--RefIndent"context is a pointer to the CS_CONTEXT structure for which the message occurred.message is a pointer to a CS_CLIENTMSG structure containing message information. For information on the CS_CLIENTMSG structure, see the MOREINFO="NONE"CS_CLIENTMSG topics page in the Client-Library Reference Manual.REMAP="UN--Under"Note that message can have a new value each time the message callback is called.ID="IN1-505143"Message callbacksvalid return valuesA CS-Library message callback must return either:MARK="BULL" REMAP="BU--Bullet"CS_SUCCEED, to instruct CS-Library to continue any processing that is currently occurring on this context, orCS_FAIL, to instruct CS-Library to terminate any processing that is currently occurring on this context.ID="IN1-505144"In-line message handling
ID="IN1-505145"Error handlingin-line message handlingRENDERAS="SECT2"In-Line Message HandlingREMAP="BO--Body"An application calls MOREINFO="NONE"cs_diagID="IN1-505146"In-line message handlinginitializing
 to initialize in-line CS-Library message handling for a context.ID="IN1-485347"In-line message handlingIn-line message handlingand CS_EXTRA_INF propertyCS_EXTRA_INF property
ID="IN1-465548"SQLCODE structureretrieving messages into
ID="IN1-445749"SQLSTATE structureretrieving messages into
ID="IN1-425950"SQLCA structureretrieving messages intoREMAP="BO--Body"An application that is retrieving messages into a SQLCA, SQLCODE, or SQLSTATE must set the CS-Library property ID="IN1-406151"CS_EXTRA_INF propertyin-line message handling
CS_EXTRA_INF to CS_TRUE. REMAP="BO--Body"For more information on the in-line method of handling CS-Library messages, see the manual page for MOREINFO="NONE"cs_diag.REMAP="BO--Body"NUMBER="2" ID="X98950"CS-Library RoutinesREMAP="BO--Body"This chapter contains a manual page for each CS-Library routine.ID="X12850"cs_calcID="IN43A-9753"Arithmetic operationsperforming
ID="IN43A-9754"Operationperforming an arithmetic operation
Perform an arithmetic operation on two operands.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE cs_calc(context, op, datatype, var1,            var2, dest) 
CS_CONTEXT      *context;
CS_INT          op;
CS_INT          datatype;
CS_VOID         *var1;
CS_VOID         *var2;
CS_VOID         *dest;ParametersREMAP="RI--RefIndent"context - A pointer to a CS_CONTEXT structure.op - The operation to perform. The following table lists the symbolic values that are legal for op:TOCENTRY="1"LBL="Table 2-1: "Values for op (MOREINFO="NONE"cs_calc)COLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="90*"COLNAME="C2" COLWIDTH="108*"COLNAME="C3" COLWIDTH="81*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Value of op:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"cs_calc performs:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"*dest is set to:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_ADDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"AdditionCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"var1 + var2COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUBCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"SubtractionCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"var1 - var2COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_MULTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MultiplicationCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"var1 * var2COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DIVCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"DivisionCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"var1 /var2datatype - The datatype of var1, var2, and dest. The following table lists the symbolic values that are legal for datatype:TOCENTRY="1"LBL="Table 2-2: "Values for datatype (MOREINFO="NONE"cs_calc)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="162*"COLNAME="C2" COLWIDTH="162*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Value of datatype:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate a Datatype of:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DECIMAL_TYPECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DECIMALCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_MONEY_TYPECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_MONEYCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_MONEY4_TYPECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_MONEY4COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_NUMERIC_TYPECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_NUMERICvar1 - A pointer to the first operand for the arithmetic operation.var2 - A pointer to the second operand for the arithmetic operation.dest - A pointer to a destination buffer. If MOREINFO="NONE"cs_calc returns CS_FAIL, *dest is not modified.ReturnsTOCENTRY="1"LBL="Table 2-3: "Return values (MOREINFO="NONE"cs_calc)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="IN43-9578"cs_calcreasons for failureREMAP="BO--Body"Common reasons for a MOREINFO="NONE"cs_calc failure include:MARK="BULL" REMAP="BU--Bullet"An invalid parameterAttempted division by 0Destination overflowCommentsMARK="BULL" REMAP="BU--Bullet"var1, var2, and dest must have the same datatype, as indicated by the datatype parameter.In case of error, *dest is not modified.See AlsoREMAP="BO--Body"LINKEND="X12687"cs_convert
ID="IN43-921011"cs_calc
 ID="IN43-891312"cs_cmpID="X26447"cs_cmpID="IN44-891414"Comparingdata values
ID="IN44-891415"Data valuescomparing
ID="IN44-891416"Valuescomparing data values
Compare two data values.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE cs_cmp(context, datatype, var1, var2,                 result)CS_CONTEXT       *context;CS_INT           datatype;CS_VOID          *var1;CS_VOID          *var2;CS_INT           *result;ParametersREMAP="RI--RefIndent"context - A pointer to a CS_CONTEXT structure.datatype - The datatype of var1 and var2. The following table lists the symbolic values that are legal for datatype:TOCENTRY="1"LBL="Table 2-4: "Values for datatype (MOREINFO="NONE"cs_cmp)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="162*"COLNAME="C2" COLWIDTH="162*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Value of datatype:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate a Datatype of:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATETIME_TYPECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATETIMECOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATETIME4_TYPECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATETIME4COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DECIMAL_TYPECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DECIMALCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_MONEY_TYPECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_MONEYCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_MONEY4_TYPECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_MONEY4COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_NUMERIC_TYPECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_NUMERICvar1 - A pointer to the first operand for the comparison.var2 - A pointer to the second operand for the comparison.result - A pointer to the result of the comparison. The following table lists the possible values for *result:TOCENTRY="1"LBL="Table 2-5: "Values for *result (MOREINFO="NONE"cs_cmp)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="90*"COLNAME="C2" COLWIDTH="189*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Value of *result:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="CENTER" ROTATE="0" MOREROWS="0"-1COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"var1 is less than var2.COLNAME="C1" ALIGN="CENTER" ROTATE="0" MOREROWS="0"0COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"var1 is equal to var2.COLNAME="C1" ALIGN="CENTER" ROTATE="0" MOREROWS="0"1COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"var1 is greater than var2.ReturnsTOCENTRY="1"LBL="Table 2-6: "Return values (MOREINFO="NONE"cs_cmp)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"cs_cmp returns CS_FAIL, *result is 
undefined.ID="IN44-871620"cs_cmpreason for failureREMAP="BO--Body"The most common reason for a MOREINFO="NONE"cs_cmp failure is an invalid parameter.CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"cs_cmp sets *result to indicate the result of the comparison.var1 and var2 must have the same datatype, as indicated by the datatype parameter.To compare string values, an application can call MOREINFO="NONE"cs_strcmp.See AlsoREMAP="BO--Body"LINKEND="X12850"cs_calc
MOREINFO="NONE", LINKEND="X12687"cs_convert
MOREINFO="NONE", LINKEND="X83895"cs_strcmp
ID="IN44-841923"cs_configID="X21848"cs_configID="IN45-842025"CS-Libraryproperties:setting and retrieving
ID="IN45-842026"Propertiessetting and retrieving CS-Library properties
Set or retrieve CS-Library properties.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE cs_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 - A pointer to a CS_CONTEXT structure. action - One of the following symbolic values:TOCENTRY="1"LBL="Table 2-7: "Values for action (MOREINFO="NONE"cs_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 MOREINFO="NONE"action:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"cs_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 
default value.property - The property whose value is being set or retrieved. The following table lists the symbolic values that are legal for MOREINFO="NONE"property:TOCENTRY="1"LBL="Table 2-8: "Values for property (MOREINFO="NONE"cs_config)COLS="4" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="114*"COLNAME="C2" COLWIDTH="153*"COLNAME="C3" COLWIDTH="99*"COLNAME="C4" COLWIDTH="114*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Value of MOREINFO="NONE"property:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"What it is:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An application can:COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"*MOREINFO="NONE"buffer is:VALIGN="TOP"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 
messages in-line, using a 
SQLCA, SQLCODE, or 
SQLSTATE.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Set, retrieve, or 
clear.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE or 
CS_FALSE.COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSE is the 
default.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 
for this context.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Set, retrieve, or 
clear.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A CS_LOCALE 
structure previously 
allocated by the 
application.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_MESSAGE_CBCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The CS-Library message 
callback routine.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Set, retrieve, or 
clear.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"If action is CS_SET, 
*buffer is the message 
callback routine.

If action is CS_GET, 
*buffer is set to the 
address of the message 
callback routine that is 
currently installed.

There is no default.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"Set, retrieve, or 
clear.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"User-allocated data.

A default is not 
applicable.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_VERSIONCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The version of CS-Library.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieve only.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A symbol. Currently, 
the only legal value for 
CS_VERSION is 
CS_VERSION_100.

There is no default.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"cs_config will place the value of the property.REMAP="UN--Under"If a property value is being cleared, pass buffer as CS_UNUSED.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. REMAP="UN--Under"If a property value is being retrieved, MOREINFO="NONE"cs_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. REMAP="UN--Under"If an application is setting a property value or does not care about return length information, it can pass MOREINFO="NONE"outlen as NULL.Summary of ParametersREMAP="BO--Body"For information on action, buffer, buflen, and outlen, see "Parameter Conventions" in the Client-Library Reference Manual.ReturnsTOCENTRY="1"LBL="Table 2-9: "Return values (MOREINFO="NONE"cs_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.CommentsID="IN45-842032"Context propertiesMARK="BULL" REMAP="BU--Bullet"There are three kinds of context properties:MARK="DASH" REMAP="BS--BulletSub"Context properties specific to CS-LibraryContext properties specific to Client-LibraryContext properties specific to Server-LibraryREMAP="UN--Under"ID="IN45-782633"cs_configcomparison to ct_config and srv_props
MOREINFO="NONE"cs_config sets and retrieves the values of CS-Library context properties. With the exception of CS_LOC_PROP, properties set via MOREINFO="NONE"cs_config affect only CS-Library. REMAP="UN--Under"ID="IN45-723234"ct_configcomparison to cs_config and srv_props
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.REMAP="UN--Under"ID="IN45-663835"srv_propscomparison to cs_config and ct_config
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.See the MOREINFO="NONE"Properties topics page in the Client-Library Reference Manual for information on Client-Library properties.About CS-Library PropertiesID="IN45-663836"Extra information propertyMARK="BULL" REMAP="BU--Bullet"Extra InformationMARK="DASH" REMAP="BS--BulletSub"ID="IN45-644037"CS_EXTRA_INF propertydetailed description
CS_EXTRA_INF determines whether or not CS-Library returns the extra information that is required to fill in a SQLCA, SQLCODE, or SQLSTATE structure.If an application is not retrieving messages into a SQLCA or SQLCODE, the extra information is returned as ordinary CS-Library messages.ID="IN45-644038"Locale information propertyLocale InformationMARK="DASH" REMAP="BS--BulletSub"TheID="IN45-624239"CS_LOC_PROP propertydetailed description
 CS_LOC_PROP property defines a ID="IN45-604440"CS_LOCALE structuredefining
CS_LOCALEID="IN45-584641"StructuresCS_LOCALE:defining
 structure that contains localization information for a context. Localization information includes a language, character set, datetime, money, and numeric formats, and a collating sequence.CS_LOC_PROP affects both CS-Library and Client-Library, because a new connection picks up default localization information from its parent context.If an application does not call MOREINFO="NONE"cs_configID="IN45-584642"Localizationdefault localization information
 to define localization information for a context, the context uses default localization information that it picks up from the operating system environment when it is allocated. If localization information is not available in the operating system environment, the context uses platform-specific default localization values.An application can call MOREINFO="NONE"cs_loc_alloc to allocate a ID="IN45-564843"CS_LOCALE structureallocating
CS_LOCALEID="IN45-545044"StructuresCS_LOCALE:allocating
 structure.ID="IN45-545045"CS-Library message callback propertyCS-Library Message CallbackMARK="DASH" REMAP="BS--BulletSub"TheID="IN45-525246"CS_MESSAGE_CB propertydetailed description
 CS_MESSAGE_CB property defines a pointer to a CS-Library message callback routine. ID="IN45-525247"Client-Library callbacksinstallingAn application installs Client-Library callback routines by calling MOREINFO="NONE"ct_callbackID="IN45-525248"CS-Library message callbacksinstalling
. An application installs a CS-Library message callback routine by calling MOREINFO="NONE"cs_config to set the value of the CS_MESSAGE_CB property. Aside from this difference, the CS-Library message callback is very similar to the Client-Library client message callback.For specific information on how to define a CS-Library message callback routine, see LINKEND="X26139"Chapter 1,  "Introducing CS-Library"
. For general information on callback routines, see the MOREINFO="NONE"Callbacks topics page in the Client-Library Reference Manual.ID="IN45-525249"User-allocated data property
User-Allocated DataID="IN45-505450"CS_USERDATA propertydetailed descriptionMARK="DASH" REMAP="BS--BulletSub"The CS_USERDATA property defines user-allocated data. This property allows an application to associate user data with a particular context structure.CS-Library copies the user data into internal data space. An application can then call MOREINFO="NONE"cs_config at a later time to retrieve the data.Although Client-Library also has a CS_USERDATA property, the Client-Library CS_USERDATA is set only at the connection and command levels.ID="IN45-505451"Version level propertyVersion LevelID="IN45-485652"CS_VERSION propertydetailed descriptionMARK="DASH" REMAP="BS--BulletSub"The CS_VERSION property represents the version of CS-Library behavior that an application has requested via MOREINFO="NONE"cs_ctx_alloc.An application can only retrieve the value of CS_VERSION.Currently, the only value that is legal for CS_VERSION is CS_VERSION_100.See AlsoREMAP="BO--Body"LINKEND="X31916"cs_ctx_alloc
MOREINFO="NONE", LINKEND="X57953" BOOK="ref"ct_con_props
MOREINFO="NONE", LINKEND="X21848"cs_config
MOREINFO="NONE", LINKEND="X55618" BOOK="ref"ct_init
ID="IN45-455954"cs_config
MOREINFO="NONE"   ID="IN45-426255"cs_convertID="X12687"cs_convertID="IN46-426357"Conversionconverting between datatypes
ID="IN46-426358"Data valuesconverting between datatypes
Convert a data value from one datatype to another.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE cs_convert(context, srcfmt, srcdata,                     destfmt, destdata, resultlen)CS_CONTXT            *context;CS_DATAFMT           *srcfmt;CS_VOID              *srcdata;CS_DATAFMT           *destfmt;CS_VOID              *destdata;CS_INT               *resultlen;ParametersREMAP="RI--RefIndent"context - A pointer to a CS_CONTEXT structure.srcfmt - A pointer to a CS_DATAFMT structure describing the source data format. The following table lists the fields in *srcfmt that are used:TOCENTRY="1"LBL="Table 2-10: "CS_DATAFMT fields for *srcfmt (MOREINFO="NONE"cs_convert)COLS="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"A type constant representing the source datatype. 
(CS_CHAR_TYPE, CS_BINARY_TYPE, etc.)COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"maxlength COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The length of the data in the *srcdata buffer.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"locale COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to a CS_LOCALE structure containing 
localization values for the source data, or NULL to use 
localization values from *context.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"All other fieldsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Are ignored.REMAP="UN--Under"For general information on the CS_DATAFMT structure, see the MOREINFO="NONE"CS_DATAFMT topics page in the Client-Library Reference Manual.srcdata - A pointer to the source data. If *srcdata is NULL, the null substitution value for the datatype indicated by *destfmt is placed in *destdata. REMAP="UN--Under"CS-Library defines a default null substitution value for each datatype. An application can define custom null substitution values by calling MOREINFO="NONE"cs_setnull.destfmt ID="IN46A-386761"CS_DATAFMT structurefields used by cs_convert
- A pointer to a CS_DATAFMT structure describing the destination data format. The following table lists the fields in *destfmt that are used:TOCENTRY="1"LBL="Table 2-11: "CS_DATAFMT fields for *destfmt (MOREINFO="NONE"cs_convert)COLS="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"A type constant representing the desired destination 
datatype. (CS_CHAR_TYPE, CS_BINARY_TYPE, etc.)COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"maxlength COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The length of the destdata buffer.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"locale COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to a CS_LOCALE structure containing 
localization values for the destination data, or NULL to 
use localization values from *context.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"formatCOLNAME="C2" 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"scaleCOLNAME="C2" 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"precisionCOLNAME="C2" 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"All other fieldsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Are ignored.REMAP="UN--Under"For general information on the CS_DATAFMT structure, see the MOREINFO="NONE"CS_DATAFMT topics page in the Client-Library Reference Manual.destdata - A pointer to the destination buffer space.resultlen - A pointer to an integer variable. MOREINFO="NONE"cs_convert sets *resultlen to the length, in bytes, of the data placed in *destdata. If the conversion fails, MOREINFO="NONE"cs_convert sets *resultlen to CS_UNUSED.REMAP="UN--Under"resultlen is an optional parameter and can be passed as NULL.ID="IN46-386762"Conversiondatatype conversion chartDatatype Conversion ChartREMAP="BO--Body"The following chart lists the datatype conversions that MOREINFO="NONE"cs_convert supports. The source datatypes are listed down the leftmost columns and the destination datatypes are listed along the top row of the tables. "T" indicates that the conversion is supported; a blank space indicates that the conversion is not supported:FLOAT="0"FORMAT="UNKNOWN" FILEREF="fig2_1.xwd"LBL="Figure 2-1: "Datatype conversion chart (continued)ReturnsTOCENTRY="1"LBL="Table 2-12: "Return values (MOREINFO="NONE"cs_convert)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="IN46-366964"cs_convertreason for failureREMAP="BO--Body"A common reason for a MOREINFO="NONE"cs_convert failure is that CS-Library does not support the requested conversion.CommentsID="IN46A-366966"Conversionhow to tell if a datatype conversion is permittedMARK="BULL" REMAP="BU--Bullet"To determine whether a particular conversion is permitted, an application can call MOREINFO="NONE"cs_will_convert.In Client-Library applications, MOREINFO="NONE"ct_bindID="IN46-366967"Automatic datatype conversion
ID="IN46-347168"Conversionct_bind sets up automatic datatype conversion
 sets up automatic data conversion. This makes it unnecessary for an application to convert result data that is fetched into program variables.ID="IN46-347169"Conversioninstalling custom conversion routinesAn application can install custom conversion routines by calling MOREINFO="NONE"cs_set_convert. Once a custom routine for a particular type of conversion is installed, MOREINFO="NONE"cs_convert calls the custom routine whenever a conversion of that type is required.MOREINFO="NONE"cs_convertID="IN46-347170"Conversionconverting between standard and user-defined datatypes
 can convert between standard and user-defined datatypes. To enable these types of conversions, an application must install the appropriate custom conversion routines via MOREINFO="NONE"cs_set_convert.ID="IN46-347171"Conversionconverting a datatype to itselfIn certain cases it can be useful to convert a datatype to itself. For instance, a conversion of CS_CHAR to CS_CHAR where srcfmtname='rArrow' font='symbol' code='174'  charset='fontspecific'locale and destfmtname='rArrow' font='symbol' code='174'  charset='fontspecific'localeID="IN46-347172"Translating strings by converting a datatype to itself
 define different character sets serves as a useful way to translate strings.For more information on CS-Library datatypes, see the MOREINFO="NONE"Types topics page in the Client-Library Reference Manual or Chapter 3, "Structures, Datatypes, Constants, and Conventions," in the Client-Library Programmer's Guide. For information on SQL Server datatypes, see the SQL Server Reference Manual.ID="IN46-347173"Conversionexceptional behaviorAbout Specific ConversionsMARK="BULL" REMAP="BU--Bullet"A conversion to or from binary and image datatypes is a straight byte-copy, except when the conversion involves character or text. When converting character or text data to binary or image, MOREINFO="NONE"cs_convert interprets the character or text string as hexadecimal, whether or not the string contains a leading "0x". When converting binary or image data to character or text, MOREINFO="NONE"cs_convert creates a hexadecimal string without a leading "0x".Converting a money, character, or text value to float can result in a loss of precision. Converting a float value to character or text can also result in a loss of precision.Converting a float value to money can result in overflow, because the maximum CS_MONEY value is $922,337,203,685,477.5807 and the maximum CS_MONEY4 value is $214,748.3648.If overflow occurs when converting integer or float data to character or text, the first character of the resulting value will contain an asterisk ("*") to indicate the error.A conversion to bit has the following effect: if the value being converted is not 0, the bit value is set to 1; if the value is 0, the bit value is set to 0.When converting decimal or numeric data to decimal or numeric data, CS_SRC_VALUE can be used in destfmtname='rArrow' font='symbol' code='174'  charset='fontspecific'
scale and destfmtname='rArrow' font='symbol' code='174'  charset='fontspecific'
precision to indicate that the destination data should have the same scale and precision as the source. CS_SRC_VALUE is valid only for decimal and numeric types.See AlsoREMAP="BO--Body"LINKEND="X71737"cs_set_convert
MOREINFO="NONE", LINKEND="X87482"cs_setnull
MOREINFO="NONE", LINKEND="X59015"cs_will_convertID="X31916"cs_ctx_allocID="IN43-9573"Allocatinga CS_CONTEXT structure
ID="IN43-9394"CS_CONTEXT structureallocating
Allocate a CS_CONTEXTID="IN43A-91115"StructuresCS_CONTEXT:allocating
 structure.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE cs_ctx_alloc(version, ctx_pointer) CS_INT          version;CS_CONTEXT      **ctx_pointer;ParametersREMAP="RI--RefIndent"version - The version of CS-Library behavior that the application expects. The following table lists the symbolic values that are legal for version:TOCENTRY="1"LBL="Table 2-13: "Values for version (MOREINFO="NONE"cs_ctx_alloc)COLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="135*"COLNAME="C2" COLWIDTH="99*"COLNAME="C3" COLWIDTH="135*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Value of version:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Features SupportedVALIGN="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"Initial version.ctx_pointer - The address of a pointer variable. MOREINFO="NONE"cs_ctx_alloc sets *ctx_pointer to the address of a newly-allocated CS_CONTEXT structure.REMAP="UN--Under"In case of error, MOREINFO="NONE"cs_ctx_alloc sets *ctx_pointer to NULL.ReturnsTOCENTRY="1"LBL="Table 2-14: "Return values (MOREINFO="NONE"cs_ctx_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_MEM_ERRORCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed because it could not allocate 
sufficient memory.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed for other reasons.ID="IN43A-89139"cs_ctx_allocreasons for failureREMAP="BO--Body"Common reasons for a MOREINFO="NONE"cs_ctx_alloc failure include:MARK="BULL" REMAP="BU--Bullet"Insufficient memory.Missing localization files.The value of the LANG environment variable does not match an entry in the locales file.CommentsMARK="BULL" REMAP="BU--Bullet"A CS_CONTEXTID="IN43-871511"CS_CONTEXT structurecontents
 structure, also called a "context structure," contains information that describes an application context. For example, a context structure contains default localization information, and defines the version of CS-Library that is in use.Allocating a context structure is the first step in any Client-Library or Server-Library application.After allocating a CS_CONTEXT structureID="IN43A-871512"Customizing a context structure
ID="IN43A-851713"CS_CONTEXT structurecustomizing
, a Client-Library application typically customizes the context by calling MOREINFO="NONE"cs_config and/or MOREINFO="NONE"ct_config, and then sets up one or more connections within the context. A Server-Library application can customize a context by calling MOREINFO="NONE"cs_config and MOREINFO="NONE"srv_props.ID="IN43A-831914"CS_CONTEXT structurede-allocatingTo de-allocate a context structure, an application can call MOREINFO="NONE"cs_ctx_drop.MOREINFO="NONE"cs_ctx_globalID="IN43-792315"cs_ctx_allocdifference from cs_ctx_global
 also allocates a context structure. The difference between MOREINFO="NONE"cs_ctx_allocID="IN43-752716"cs_ctx_globaldifference from cs_ctx_alloc
 and MOREINFO="NONE"cs_ctx_global is that MOREINFO="NONE"cs_ctx_alloc allocates a new context structure each time it is called, while MOREINFO="NONE"cs_ctx_global allocates a new context structure only once, the first time it is called. On subsequent calls, MOREINFO="NONE"cs_ctx_global simply returns a pointer to the existing context structure.ID="IN43-732917"cs_ctx_alloccode exampleExampleREMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"  /*  ** ex_init()  */REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"  CS_RETCODE CS_PUBLIC  ex_init(context)  CS_CONTEXT*     *context;  {       CS_RETCODE         retcode;       CS_INT             netio_type = CS_SYNC_IO;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"       /* Get a context handle to use */       retcode = cs_ctx_alloc(EX_CTLIB_VERSION, context);       if (retcode != CS_SUCCEED)       {            ex_error("ex_init: cs_ctx_alloc() failed");            return retcode;       }REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"        /* Initialize Open Client */        ...CODE DELETED.....REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"        /* Install client and server message handlers */        ...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;}See AlsoREMAP="BO--Body"LINKEND="X20297" BOOK="ref"ct_con_alloc
MOREINFO="NONE", LINKEND="X62055" BOOK="ref"ct_config
MOREINFO="NONE", LINKEND="X40738"cs_ctx_drop
MOREINFO="NONE", LINKEND="X45073"cs_ctx_global
MOREINFO="NONE", LINKEND="X21848"cs_config
ID="IN43-703220"cs_ctx_dropID="X40738"cs_ctx_dropID="IN44-683522"De-allocatingDe-allocatinga CS_CONTEXT structureCS_CONTEXT structure
ID="IN44-663723"CS_CONTEXT structurede-allocating
De-allocate a CS_CONTEXTID="IN44-643924"StructuresCS_CONTEXT:de-allocating
 structure.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE cs_ctx_drop(context) CS_CONTEXT      *context;ParametersREMAP="RI--RefIndent"context - A pointer to a CS_CONTEXT structure.ReturnsTOCENTRY="1"LBL="Table 2-15: "Return values (MOREINFO="NONE"cs_ctx_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. REMAP="BO--Body"MOREINFO="NONE"cs_ctx_drop returns CS_FAIL if the context contains an open connection.CommentsMARK="BULL" REMAP="BU--Bullet"A CS_CONTEXT structure describes a particular context, or operating environment, for a set of server connections.Once a CS_CONTEXT has been de-allocated, it cannot be re-used. To allocate a new CS_CONTEXT, an application can call MOREINFO="NONE"cs_ctx_alloc.ID="IN44-624129"cs_ctx_dropwhen not to callA Client-Library application cannot call MOREINFO="NONE"cs_ctx_drop to de-allocate a CS_CONTEXT structure until it has called MOREINFO="NONE"ct_exit to clean up Client-Library space associated with the context.ID="IN44-604330"cs_ctx_dropcode example   ExampleREMAP="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.*/CS_RETCODE CS_PUBLICex_ctx_cleanup(context, status)CS_CONTEXT*         context;CS_RETCODE          status;{     CS_RETCODE         retcode;     CS_INT             exit_option;     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;  }See AlsoREMAP="BO--Body"LINKEND="X31916"cs_ctx_alloc
MOREINFO="NONE", LINKEND="X98839" BOOK="ref"ct_close
MOREINFO="NONE", LINKEND="X58559" BOOK="ref"ct_exit
ID="IN44-574633"cs_ctx_drop
MOREINFO="NONE"   ID="IN44-544934"cs_ctx_globalID="X45073"cs_ctx_globalID="IN45-525236"Allocatinga CS_CONTEXT structure
ID="IN45-505437"CS_CONTEXT structureallocating
Allocate or return a CS_CONTEXTID="IN45-485638"StructuresCS_CONTEXT:allocating
 structure.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE cs_ctx_global(version, ctx_pointer) CS_INT       version;CS_CONTEXT   **ctx_pointer;ParametersREMAP="RI--RefIndent"version - The version of CS-Library behavior that the application expects. The following table lists the symbolic values that are legal for version:TOCENTRY="1"LBL="Table 2-16: "Values for version (MOREINFO="NONE"cs_ctx_global)COLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="135*"COLNAME="C2" COLWIDTH="99*"COLNAME="C3" COLWIDTH="135*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Value of version:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Features SupportedVALIGN="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"Initial version.REMAP="UN--Under"If an application has already allocated a CS_CONTEXT structure, version must match the version previously requested.ctx_pointer - The address of a pointer variable. MOREINFO="NONE"cs_ctx_global sets *ctx_pointer to the address of a new or previously-allocated CS_CONTEXT structure.REMAP="UN--Under"In case of error, MOREINFO="NONE"cs_ctx_global sets *ctx_pointer to NULL.ReturnsTOCENTRY="1"LBL="Table 2-17: "Return values (MOREINFO="NONE"cs_ctx_global)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_MEM_ERRORCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed because it could not allocate 
sufficient memory.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The routine failed for other reasons.ID="IN45-465842"cs_ctx_globalreasons for failureREMAP="BO--Body"Common reasons for a MOREINFO="NONE"cs_ctx_global failure include:MARK="BULL" REMAP="BU--Bullet"A lack of available memory.A version value that does not match a previously requested version.CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"cs_ctx_alloc also allocates a context structure. The only difference between MOREINFO="NONE"cs_ctx_alloc and MOREINFO="NONE"cs_ctx_global is that MOREINFO="NONE"cs_ctx_alloc allocates a new context structure each time it is called, while MOREINFO="NONE"cs_ctx_global allocates a new context structure only once, the first time it is called. On subsequent calls, MOREINFO="NONE"cs_ctx_global simply returns a pointer to the existing context structure.MOREINFO="NONE"cs_ctx_globalID="IN45-446044"cs_ctx_globalpurpose
 is of use in applications that need to access a single context structure from multiple independent modules.For more information on context structures, see the MOREINFO="NONE"cs_ctx_alloc manual page.See AlsoREMAP="BO--Body"LINKEND="X31916"cs_ctx_alloc
MOREINFO="NONE", LINKEND="X40738"cs_ctx_drop
MOREINFO="NONE", LINKEND="X21848"cs_config
MOREINFO="NONE", LINKEND="X20297" BOOK="ref"ct_con_alloc
MOREINFO="NONE", LINKEND="X62055" BOOK="ref"ct_config
ID="IN45-416346"cs_ctx_global
MOREINFO="NONE"  ID="IN45-386647"cs_diagcs_diagID="IN46-386749"In-line message handlingmanaging
Manage in-line error handling.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE cs_diag(context, operation, type, index,             buffer) CS_CONTEXT   *context;CS_INT       operation;CS_INT       type;CS_INT       index;CS_VOID      *buffer;ParametersREMAP="RI--RefIndent"context - A pointer to a CS_CONTEXT structure. 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 2-18: "Values for type (MOREINFO="NONE"cs_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 four-byte 
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 CS-Library 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.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 2-19: "Summary of parameters (MOREINFO="NONE"cs_diag)COLS="5" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="112*"COLNAME="C2" COLWIDTH="101*"COLNAME="C3" COLWIDTH="123*"COLNAME="C4" COLWIDTH="79*"COLNAME="C5" COLWIDTH="82*"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"cs_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 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 
context.

If buffer is not 
NULL, MOREINFO="NONE"cs_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.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"One of the legal type 
values.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_TYPECOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_UNUSEDCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to an 
integer value.ReturnsTOCENTRY="1"LBL="Table 2-20: "Return values (MOREINFO="NONE"cs_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.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.ID="IN46-366954"cs_diagreasons for failureREMAP="BO--Body"Common reasons for a MOREINFO="NONE"cs_diag failure include:MARK="BULL" REMAP="BU--Bullet"Invalid contextInability to allocate memoryInvalid parameter combinationCommentsID="IN46-366956"Error handlingmethods of handling errorsMARK="BULL" REMAP="BU--Bullet"An application that includes calls to CS-Library can handle CS-Library messages in one of two ways:MARK="DASH" REMAP="BS--BulletSub"The application can call MOREINFO="NONE"cs_config to install a CS-Library message callback, orThe application can handle CS-Library messages in-line, using MOREINFO="NONE"cs_diag.ID="IN46-366957"Error handlingswitching between error handling methodsREMAP="UN--Under"It is possible for an application to switch back and forth between the in-line and the callback method:MARK="DASH" REMAP="BS--BulletSub"Installing a CS-Library message callback turns off in-line message handling. Any saved messages are discarded.Likewise, callingMOREINFO="NONE" cs_diag to initialize in-line message handling de-installs an application's message callback. If this occurs, the application's first CS_GET call to MOREINFO="NONE"cs_diag will retrieve a warning message to this effect.REMAP="UN--Under"If a callback of the proper type is not installed and in-line message handling is not enabled, CS-Library discards message information.ID="IN46-347158"cs_diaghandles messages on a per-context basis
MOREINFO="NONE"cs_diagID="IN46-347159"In-line message handlingmanaged on a per-context basis
 manages in-line message handling for a specific context. If an application has more than one context, it must make separate MOREINFO="NONE"cs_diag calls for each context.MOREINFO="NONE"cs_diagID="IN46-347160"In-line message handlingretrieving message information into structures
 allows an application to retrieve message information into a CS_CLIENTMSGID="IN46-347161"Structuresretrieving message information into structures
 structure or a SQLCA, SQLCODE, or SQLSTATE structure. When retrieving messages, MOREINFO="NONE"cs_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 structure must set the CS-Library context property ID="IN46-327362"CS_EXTRA_INF propertyin-line message handling
ID="IN46-307563"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 contain information that is not ordinarily returned by CS-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 CS-Library messages.If MOREINFO="NONE"cs_diag 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"cs_diag starts saving messages again.ID="IN46-307564"In-line message handlinginitializingInitializing In-Line Error HandlingMARK="BULL" REMAP="BU--Bullet"To initialize in-line error handling, an application calls MOREINFO="NONE"cs_diag with operation as CS_INIT.Generally, if a context will use in-line error handling, an application should call MOREINFO="NONE"cs_diag to initialize in-line error handling for the context immediately after allocating it.ID="IN46-307565"In-line message handlingclearing messagesClearing MessagesMARK="BULL" REMAP="BU--Bullet"To clear message information for a context, an application calls MOREINFO="NONE"cs_diag with operation as CS_CLEAR. MARK="DASH" REMAP="BS--BulletSub"MOREINFO="NONE"cs_diag assumes that buffer points to a structure of type type. MOREINFO="NONE"cs_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"cs_diag with operations as CS_CLEAR. Retrieving a message does not remove it from the message queue.ID="IN46-307566"In-line message handlingretrieving messagesRetrieving MessagesMARK="BULL" REMAP="BU--Bullet"To retrieve message information, an application calls MOREINFO="NONE"cs_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.MOREINFO="NONE"cs_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"cs_diag returns ID="IN46-287767"CS_NOMSG returnwhen returned
CS_NOMSG to indicate that no message is available.See theMOREINFO="NONE" SQLCA, SQLCODE, CS_CLIENTMSG andMOREINFO="NONE" CS_SERVERMSG topics pages in the Client-Library Reference Manual for information on these structures.ID="IN46-287768"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 CS-Library saves.To limit the number of saved messages, an application calls MOREINFO="NONE"cs_diag with operation as CS_MSGLIMIT and type as CS_CLIENTMSG_TYPE.When a message limit is reached, CS-Library discards any new messages.An application cannot set a message limit that is less than the number of messages currently saved.CS-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 CS_NO_LIMIT.ID="IN46-287769"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"cs_diag with operation as CS_STATUS and type as the CS_CLIENTMSG_TYPE.See AlsoREMAP="BO--Body"LINKEND="X39627" BOOK="ref"ct_callback
MOREINFO="NONE", LINKEND="X61859" BOOK="ref"ct_options
ID="IN46-258071"cs_diag
MOREINFO="NONE"   ID="X37478"cs_dt_crackID="IN43B-9753"Conversionconverting a machine-readable datetime value into a user-accessible format
ID="IN43B-9754"Datetimeconverting a machine-readable datetime value into a user-accessible format
Convert a machine-readable datetime value into a user-accessible format.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE cs_dt_crack(context, datetype, dateval,                  daterec) CS_CONTEXT        *context;CS_INTdat         etype;CS_VOID           *dateval;CS_DATEREC        *daterec;ParametersREMAP="RI--RefIndent"context - A pointer to a CS_CONTEXT structure.datetype - The type of the datetime value. The following table lists the symbolic values that are legal for datetype:TOCENTRY="1"LBL="Table 2-21: "Values for datetype (MOREINFO="NONE"cs_dt_crack)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="135*"COLNAME="C2" COLWIDTH="162*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Value of datetype:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATETIME_TYPECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A CS_DATETIME *dateval.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATETIME4_TYPECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A CS_DATETIME4 *dateval.dateval - A pointer to a the datetime value to be converted.daterecID="IN43-9397"cs_dt_crackand CS_DATEREC structure
 - A pointer to a CS_DATERECID="IN43-91118"CS_DATEREC structuredefinition
ID="IN43-89139"StructuresCS_DATEREC:definition
 structure. MOREINFO="NONE"cs_dt_crack fills this structure with the translated datetime value. A CS_DATEREC is defined as follows:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"typedef struct cs_daterec {    CS_INT      dateyear;      /* year           */    CS_INT      datemonth;     /* month          */    CS_INT      datedmonth;    /* day of month   */    CS_INT      datedyear;     /* day of year    */    CS_INT      datedweek;     /* day of week    */    CS_INT      datehour;      /* hour           */    CS_INT      dateminute;    /* minute         */    CS_INT      datesecond;    /* second         */    CS_INT      datemsecond;   /* millisecond    */    CS_INT      datetzone;     /* timezone       */} CS_DATEREC;REMAP="UN--Under"where:REMAP="UN--Under"dateyear is a value greater than or equal to 1900.REMAP="UN--Under"datemonth is a value from 0 to 11.REMAP="UN--Under"datedmonth is a value from 1 to 31.REMAP="UN--Under"datedyear is a value from 1 to 366.REMAP="UN--Under"datedweek is a value from 0 to 6.REMAP="UN--Under"datehour is a value from 0 to 23.REMAP="UN--Under"dateminute is a value from 0 to 59.REMAP="UN--Under"datesecond is a value from 0 to 59.REMAP="UN--Under"datemsecond is a value from 0 to 997.REMAP="UN--Under"datetzone is a value from 0 to 127.REMAP="UN--Under"The meanings of these numbers vary according to an application's locale. For example, if localization information specifies that Sunday is the first day of the week, then a datedweek value of 2 represents Tuesday. If localization information specifies that Monday is the first day of the week, then a datedweek value of 2 represents Wednesday.REMAP="UN--Under"An application can call MOREINFO="NONE"cs_dt_info to find out what date-related localization values are in effect.REMAP="UN--Under"For more information on localization, see the MOREINFO="NONE"International Support topics page in the Client-Library Reference Manual.ReturnsTOCENTRY="1"LBL="Table 2-22: "Return values (MOREINFO="NONE"cs_dt_crack)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. REMAP="BO--Body"The most common reason for aMOREINFO="NONE" cs_dt_crack failure is an invalid parameter.CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"cs_dt_crack converts a datetime value into its integer components and places those components into a CS_DATEREC structure.ID="IN43A-891312"Datetimedatetime values stored in an internal formatDatetime values are stored in an internal format. For example, a CS_DATETIME value is stored as the number of days since January 1, 1900 plus the number of 300th's of a second since midnight. MOREINFO="NONE"cs_dt_crack converts a value of this type into a format that an application can more easily access.See AlsoREMAP="BO--Body"LINKEND="X91463"cs_dt_info
ID="IN43-861614"cs_dt_crack
MOREINFO="NONE" ID="IN43-831915"cs_dt_infoID="X91463"cs_dt_infoID="IN44-832017"Datetimesetting or retrieving language-specific datetime information
Set or retrieve language-specific datetime information.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE cs_dt_info(context, action, locale, type,                item, buffer, buflen, outlen) CS_CONTEXT      *context;CS_INT          action;CS_LOCALE       *locale;CS_INT          type;CS_INT          item;CS_VOID         *buffer;CS_INT          buflen;CS_INT          *outlen;ParametersREMAP="RI--RefIndent"context - A pointer to a CS_CONTEXT structure. REMAP="UN--Under"When retrieving datetime information, if locale is NULL, MOREINFO="NONE"cs_dt_info uses the default locale information contained in this context structure.action - One of the following symbolic values:TOCENTRY="1"LBL="Table 2-23: "Values for action (MOREINFO="NONE"cs_dt_info)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="120*"COLNAME="C2" COLWIDTH="237*"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"cs_dt_info:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Sets a datetime conversion format.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_GETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieves datetime information.locale - A pointer to a CS_LOCALE structure. A locale structure contains locale information, including datetime information.REMAP="UN--Under"When setting datetime information, locale must be supplied.REMAP="UN--Under"When retrieving datetime information, locale can be NULL. If locale is NULL, MOREINFO="NONE"cs_dt_info uses the default locale information contained in *context.type - The type of information of interest. The table in the MOREINFO="NONE"Summary of Parameters section lists the symbolic values that are legal for type.item - When retrieving information, item is the item number of the type category to retrieve. For example, to retrieve the name of the first month, an application passes type as CS_MONTH and item as 0.REMAP="UN--Under"When setting a datetime conversion format, pass item as CS_UNUSED.buffer - If datetime information is being retrieved, buffer points to the space in which MOREINFO="NONE"cs_dt_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"cs_dt_info sets *MOREINFO="NONE"outlen to the length of the requested information and returns CS_FAIL. REMAP="UN--Under"If a datetime conversion format is being set, buffer points to a symbolic value representing a conversion format.buflen - The length, in bytes, of *buffer.REMAP="UN--Under"If item is CS_12HOUR, pass buflen as CS_UNUSED.outlen - A pointer to an integer variable. REMAP="UN--Under"MOREINFO="NONE"cs_dt_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 2-24: "Summary of parameters (MOREINFO="NONE"cs_dt_info)COLS="5" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="107*"COLNAME="C2" COLWIDTH="110*"COLNAME="C3" COLWIDTH="50*"COLNAME="C4" COLWIDTH="81*"COLNAME="C5" COLWIDTH="117*"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"cs_dt_info:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"action 
can be:COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"item can be:COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"*MOREINFO="NONE"buffer is:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_MONTHCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieves the month 
name string.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_GETCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"0 - 11COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A character string.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SHORTMONTHCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieves the short 
month name string.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_GETCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"0 - 11COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A character string.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DAYNAMECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieves the day 
name string.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_GETCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"0 - 6COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A character string.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATEORDERCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieves the date 
order string.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_GETCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_UNUSEDCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A string containing the 
three characters "m", 
"d", and "y," to indicate 
the position of the 
month, day, and year 
in the national 
language's datetime 
format.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_12HOURCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieves whether or 
not the language uses 
12-hour time formats.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_GETCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_UNUSEDCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUE if 12-hour 
formats are used; 
CS_FALSE if 24-hour 
formats are used.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DT_CONVFMTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Sets or retrieves the 
datetime conversion 
format.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_GET
 or 
CS_SETCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_UNUSEDCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A symbolic value. See 
the Comments section, 
below, for a list of 
possible values.ReturnsTOCENTRY="1"LBL="Table 2-25: "Return values (MOREINFO="NONE"cs_dt_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. ID="IN44-812222"cs_dt_inforeason for failureREMAP="BO--Body"The most common reason for aMOREINFO="NONE" cs_dt_info failure is an invalid parameter.CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"cs_dt_info sets or retrieves national language-specific datetime information:MARK="DASH" REMAP="BS--BulletSub"MOREINFO="NONE"cs_dt_info can return national language date part names, date part ordering information, datetime format information, and whether or not the language uses 12-hour date formats.MOREINFO="NONE"cs_dt_info can set datetime format information.ID="IN44-792424"cs_dt_infowhere it looks for national language locale information
MOREINFO="NONE"cs_dt_info looks for national language locale information in *context. An application can set locale information for a CS_CONTEXT by calling MOREINFO="NONE"cs_config with property as CS_LOC_PROP.REMAP="UN--Under"If not specifically set, locale information in a CS_CONTEXT defaults to information that CS-Library picks up from the operating system when the context is allocated. If locale information is not available from the operating system, CS-Library uses platform-specific localization values in the new context.The following table lists the values that are legal for *buffer when type is CS_DT_CONVFMT:TOCENTRY="1"LBL="Table 2-26: "Values for *buffer when type is CS_DT_CONVFMT (MOREINFO="NONE"cs_dt_info)COLS="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_DATES_HMSCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"hh:mm:ss
MOREINFO="NONE"
16:15:31COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATES_SHORTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"monthname dd yyyy hh:mm [am|pm]
MOREINFO="NONE"
October 19 1961 04:15:31 pmCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATES_LONGCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"monthname dd yyyy hh:mm:ss:zzz [am|pm]
MOREINFO="NONE"
October 19 1961 04:15:31:665 pmCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATES_MDY1COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"mm/dd/yy
MOREINFO="NONE"
10/19/61COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATES_MYD1COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"mm/yy/dd
MOREINFO="NONE"
10/61/19COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATES_DMY1COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"dd/mm/yy
MOREINFO="NONE"
19/10/61COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATES_DYM1COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"dd/yy/mm
MOREINFO="NONE"
19/61/10COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATES_YDM1COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"yy/dd/mm
MOREINFO="NONE"
61/19/10COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATES_YMD2COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"yy/mm/dd
MOREINFO="NONE"
61/10/19COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATES_MDY1_YYYYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"mm/dd/yyyy
MOREINFO="NONE"
10/19/1961COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATES_DMY1_YYYYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"dd/mm/yyyy
MOREINFO="NONE"
19/10/1961COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATES_YMD2_YYYYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"yyyy/mm/dd
MOREINFO="NONE"
1961/10/19COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATES_DMY2COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"dd.mm.yy
MOREINFO="NONE"
19.10.61COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATES_YMD1COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"yy.mm.dd
MOREINFO="NONE"
61.10.19COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATES_DMY2_YYYYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"dd.mm.yyyy
MOREINFO="NONE"
19.10.1961COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATES_YMD1_YYYYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"yyyy.mm.dd
MOREINFO="NONE"
1961.10.19COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATES_DMY4COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"dd monthname yy
MOREINFO="NONE"
19 January 61COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATES_DMY4_YYYYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"dd monthname yyyy
MOREINFO="NONE"
19 January 1961COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATES_MDY2COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"monthname dd, yy
MOREINFO="NONE"
January 19,61COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATES_MDY2_YYYYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"monthname dd, yyyy
MOREINFO="NONE"
January 19,1961COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATES_DMY3COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"dd-mm-yy

19-10-61COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATES_MDY3COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"mm-dd-yy
MOREINFO="NONE"
10-19-61COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATES_DMY3_YYYYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"dd-mm-yyyy
MOREINFO="NONE"
19-10-1961COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATES_MDY3_YYYYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"mm-dd-yyyy
MOREINFO="NONE"
10-19-1961COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATES_YMD3COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"yymmdd
MOREINFO="NONE"
611019COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATES_YMD3_YYYYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"yyyymmdd
MOREINFO="NONE"
19611019See AlsoREMAP="BO--Body"LINKEND="X37478"cs_dt_crack
ID="IN44-762726"cs_dt_info
MOREINFO="NONE" ID="IN44-733027"cs_loc_allocID="X53799"cs_loc_allocID="IN45-713329"Allocatinga CS_LOCALE structure
ID="IN45-693530"CS_LOCALE structureallocating
Allocate a CS_LOCALEID="IN45-673731"StructuresCS_LOCALE:allocating
 structure.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE cs_loc_alloc(context, loc_pointer) CS_CONTENT       *context;CS_LOCALE        **loc_pointer;ParametersREMAP="RI--RefIndent"context - A pointer to a CS_CONTEXT structure.loc_pointer - The address of a pointer variable. MOREINFO="NONE"cs_loc_alloc sets *loc_pointer to the address of a newly-allocated CS_LOCALE structure.ReturnsTOCENTRY="1"LBL="Table 2-27: "Return values (MOREINFO="NONE"cs_loc_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="IN45-653935"cs_loc_allocreason for failureREMAP="BO--Body"The most common reason for a MOREINFO="NONE"cs_loc_alloc failure is a lack of adequate memory.CommentsMARK="BULL" REMAP="BU--Bullet"An Open Client/Server application can use a CS_LOCALEID="IN45-653937"Localizationdefining custom values
 structure to define custom localization values for a context, thread, connection, or data element. To define custom localization values, an application:MARK="DASH" REMAP="BS--BulletSub"Calls MOREINFO="NONE"cs_loc_alloc to allocate a CS_LOCALE structure.Calls MOREINFO="NONE"cs_locale(CS_SET) to load the CS_LOCALE with custom values.Uses the CS_LOCALE to set the CS_LOC_PROP property for a context or connection; calls MOREINFO="NONE"srv_thread_props to set the SRV_T_LOCALE property for a thread; uses the CS_LOCALE in a CS_DATAFMT structure that describes a program variable; or uses the CS_LOCALE as a parameter to an Open Client/Server routine.Calls MOREINFO="NONE"cs_loc_drop to drop the CS_LOCALE.ID="IN45-653938"Localizationwhat localization values defineLocalization values define:MARK="DASH" REMAP="BS--BulletSub"The language and character set to use for Open Client/Server and SQL Server messagesHow to represent dates and timesThe character set to use when converting data to and from character datatypesThe collating sequence used to define the sort order used by MOREINFO="NONE"cs_strcmpSee AlsoREMAP="BO--Body"LINKEND="X31916"cs_ctx_alloc
MOREINFO="NONE", LINKEND="X13400"cs_loc_drop
MOREINFO="NONE", LINKEND="X37122"cs_locale
ID="IN45-624240"cs_loc_dropID="X13400"cs_loc_dropID="IN46-604542"De-allocatingDe-allocatinga CS_LOCALE structureCS_LOCALE structure
ID="IN46-584743"CS_LOCALE structurede-allocating
De-allocate a CS_LOCALEID="IN46-564944"StructuresCS_LOCALE:de-allocating
 structure. REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE cs_loc_drop(context, locale) CS_CONTEXT      *context;CS_LOCALE       *locale;ParametersREMAP="RI--RefIndent"context - A pointer to the CS_CONTEXT structure that represents the context in which the CS_LOCALE was allocated.locale - A pointer to a CS_LOCALE structure.ReturnsTOCENTRY="1"LBL="Table 2-28: "Return values (MOREINFO="NONE"cs_loc_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.CommentsMARK="BULL" REMAP="BU--Bullet"A CS_LOCALEID="IN46-545149"LocalizationLocalizationand CS_LOCALE structureCS_LOCALE structure
 structure contains localization information.Once a CS_LOCALE structure has been de-allocated, it cannot be reused. To allocate a new CS_LOCALE structure, an application can call MOREINFO="NONE"cs_loc_alloc. An application should take care to ensure that it does not de-allocate a CS_LOCALE structure that is still in use. A CS_LOCALEID="IN46-525350"CS_LOCALE structurewhen in use
 structure is considered to be in use if a CS_DATAFMT structure references it.An application can de-allocate a CS_LOCALEID="IN46-505551"CS_LOCALE structurewhen a structure can be de-allocated
 structure after calling MOREINFO="NONE"cs_config or MOREINFO="NONE"ct_con_props to set the CS_LOC_PROP property for a context or connection. This is because MOREINFO="NONE"cs_config and MOREINFO="NONE"ct_con_props copy information from the user-supplied CS_LOCALE structure rather than setting up direct references to it.See AlsoREMAP="BO--Body"LINKEND="X53799"cs_loc_alloc
MOREINFO="NONE", LINKEND="X37122"cs_locale
ID="IN46-475853"cs_localeID="X37122"cs_localeID="IN47-456155"CS_LOCALE structureloading with localization values
Load a CS_LOCALEID="IN47-436356"Locale nameretrieving the locale name previously used to load a CS_LOCALE structure
ID="IN47-416557"CS_LOCALE structureretrieving the locale name previously used to load it
 structure with localization values or retrieve the locale name previously used to load a CS_LOCALE structure.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE cs_locale(context, action, locale, type,                buffer, buflen, outlen) CS_CONTEXT      *context;CS_INT          action;CS_LOCALE       *locale;CS_INT          type;CS_CHAR         *buffer;CS_INT          buflen;CS_INT          *outlen;ParametersREMAP="RI--RefIndent"context - A pointer to the CS_CONTEXT structure that represents the context in which the CS_LOCALE was allocated.action - One of the following symbolic values:TOCENTRY="1"LBL="Table 2-29: "Values for action (MOREINFO="NONE"cs_locale)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"cs_locale:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Loads the CS_LOCALE with new localization 
values.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_GETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieves the locale name that was used to load the 
CS_LOCALE.locale - A pointer to a CS_LOCALE structure. If action is CS_SET, MOREINFO="NONE"cs_locale modifies this structure. If action is CS_GET, MOREINFO="NONE"cs_locale examines the structure to determine the locale name that was previously used to load it.type - The type of localization information of interest. The following table lists the symbolic values that are legal for type:TOCENTRY="1"LBL="Table 2-30: "Values for type (MOREINFO="NONE"cs_locale)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="144*"COLNAME="C2" COLWIDTH="223*"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"CS_LC_ALLCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"All types of localization information. 

CS_LC_ALL is "set only"; that is, action must be 
CS_SET when type is CS_LC_ALL.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_LC_COLLATECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The collating sequence (also called "sort 
order"). Open Client uses a collating sequence 
when sorting and comparing character data.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_LC_CTYPECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The character set. Open Client uses a character 
set when it converts to or from character 
datatypes.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_LC_MESSAGECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The language and character set to use for Open 
Client/Server and SQL Server error messages.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_LC_TIMECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The language and character set to use when 
converting between datetime and character 
datatypes. CS_LC_TIME controls month names 
and abbreviations, datepart ordering, and 
whether the "am/pm" string is used.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SYB_LANG,
CS_SYB_CHARSET,
CS_SYB_SORTORDER,
CS_SYB_LANG_CHARSETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"For information on these values, see "Using
 Language, Character Set, and Sort Order Names With cs_locale".Open Server application programmers must set type to CS_LC_ALL when configuring the CS_LOCALE structure that applies to the Open Server application as a whole.buffer - If action is CS_SET, buffer points to a character string that represents a locale name.REMAP="UN--Under"This locale name must correspond to an entry in the SYBASE locales file. REMAP="UN--Under"If buffer is NULL, MOREINFO="NONE"cs_locale searches the operating system for a locale name to use. If an appropriate locale name cannot be found in the operating system environment, MOREINFO="NONE"cs_locale uses a platform-dependent default locale name.REMAP="UN--Under"For more information about the locales file and MOREINFO="NONE"cs_locale's search process, see the Open Client/Server Supplement for your platform.REMAP="UN--Under"If action is CS_GET, buffer points to the space in which MOREINFO="NONE"cs_locale will place a locale name.buflen - The length, in bytes, of *buffer.REMAP="UN--Under"If action is CS_SET and the value in *MOREINFO="NONE"buffer is null-terminated, pass MOREINFO="NONE"buflen as CS_NULLTERM.outlen - A pointer to an integer variable. REMAP="UN--Under"outlen is not used if action is CS_SET.REMAP="UN--Under"If action is CS_GET and outlen is supplied, MOREINFO="NONE"cs_locale sets *outlen to the length, in bytes, of the locale name.REMAP="UN--Under"If the name is larger than buflen bytes, an application can use the value of *outlen to determine how many bytes are needed to hold the name.REMAP="UN--Under"If action is CS_SET or an application or does not care about return length information, it can pass MOREINFO="NONE"outlen as NULL.ReturnsTOCENTRY="1"LBL="Table 2-31: "Return values (MOREINFO="NONE"cs_locale)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="IN47-396761"cs_localereasons for failureREMAP="BO--Body"Common reasons for a MOREINFO="NONE"cs_locale failure include:MARK="BULL" REMAP="BU--Bullet"action is CS_SET and the *buffer locale name cannot be found in the SYBASE locales file.action is CS_GET and buflen indicates that the *buffer data space is too small.Missing localization files.CommentsFor information on platform-specific issues relating to MOREINFO="NONE"cs_locale, see the Open Client/Server Supplement for your platform. You must read the localization chapter in the Supplement in order to get a full understanding of Client-Library's localization mechanism.MARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"cs_locale(CS_SET) loads a CS_LOCALE structure with localization values. MOREINFO="NONE"cs_locale(CS_GET) retrieves the locale name that was previously used to load the CS_LOCALE.ID="IN47-396763"Locale namewhat it isA locale name is a character string that represents a language/ character set/sort order triple. For example, the locale name "fr" might represent the language/character set/sort order triple "French, iso_1, binary". SYBASE pre-defines some locale names, which are listed in the locales file, but a system administrator can define additional locale names and add them to this file.For more information on localization, see the MOREINFO="NONE"International Support topics page in Chapter 2 of the Open Client Client-Library Reference Manual.ID="IN47-376964"CS_LOCALE structureloadingLoading a CS_LOCALE structureMARK="BULL" REMAP="BU--Bullet"An application needs to load a CS_LOCALE before using it to define custom localization values for a context, connection, or data element.ID="IN47-357165"CS_LOCALE structurewhat to do after loading itAfter loading a CS_LOCALE with custom values, 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.Supply the CS_LOCALE as a parameter to a routine that accepts custom localization values (MOREINFO="NONE"cs_convert, MOREINFO="NONE"cs_strcmp, MOREINFO="NONE"cs_time).Include the CS_LOCALE in a CS_DATAFMT structure describing a destination program variable (MOREINFO="NONE"ct_bind).Because MOREINFO="NONE"cs_configID="IN47-337366"CS_LOCALE structurewhen a structure can be de-allocated
 copies locale information, an application can de-allocate a CS_LOCALE structure after calling MOREINFO="NONE"cs_config to set the CS_LOC_PROP property. Likewise, an application can de-allocate a CS_LOCALE structure after calling MOREINFO="NONE"ct_con_props to set the CS_LOC_PROP property. If a CS_DATAFMT structure uses a CS_LOCALE structure, however, the application must not de-allocate the CS_LOCALE until the CS_DATAFMT no longer references it.ID="IN47-337367"Locale namereferencingThe first time a locale name is referenced, all localization information for the language, character set, and sort order that the locale name identifies is read from the environment and cached into *context. If this locale name is referenced again, MOREINFO="NONE"cs_locale will read the information from the CS_CONTEXT instead of the environment.ID="IN47-317568"Locale nameretrieving the locale name previously used to load a CS_LOCALE structureRetrieving a Locale NameMARK="BULL" REMAP="BU--Bullet"An application can retrieve the locale name that was used to load a CS_LOCALE by calling MOREINFO="NONE"cs_locale(CS_GET) with type as the type of localization information of interest and locale as a pointer to the CS_LOCALE structure.MOREINFO="NONE"cs_locale sets *buffer to a null-terminated character string representing the locale name that was used to load the CS_LOCALE.ID="X24462"Using Language, Character Set, and Sort Order Names With MOREINFO="NONE"cs_localeID="IN47-297769"cs_localeusing language, character set, and sort order namesMARK="BULL" REMAP="BU--Bullet"It is possible for an application to use language, character set, and sort order names, instead of a locale name, when calling MOREINFO="NONE"cs_locale. To do this, an application calls MOREINFO="NONE"cs_locale with type as CS_SYB_LANG, CS_SYB_CHARSET, CS_SYB_SORTORDER, or CS_SYB_LANG_CHARSET.The following table summarizes MOREINFO="NONE"cs_locale's parameters for these values of type:TOCENTRY="1"LBL="Table 2-32: "Using language, character set, and sort order names (MOREINFO="NONE"cs_locale)COLS="4" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="149*"COLNAME="C2" COLWIDTH="53*"COLNAME="C3" COLWIDTH="132*"COLNAME="C4" COLWIDTH="146*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Value of type:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"action is:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"buffer is:COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"cs_locale:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SYB_LANGCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SETCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to a language 
name. COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Loads the CS_LOCALE with 
the specified language 
information.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_GETCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to data space.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Places the current language 
name in *buffer.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SYB_CHARSETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SETCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to a character set 
name.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Loads the CS_LOCALE with 
the specified character set 
information.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_GETCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to data space.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Places the current character 
set name in *buffer.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SYB_SORTORDERCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SETCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to a sort order 
name.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Loads the CS_LOCALE with 
the specified sort order 
information.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_GETCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to data space.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Places the current sort order 
name in *buffer.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SYB_LANG_CHARSETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SETCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to a string of the 
form language_name.
character_set_name.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Loads the CS_LOCALE with 
the specified language and 
character set information.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_GETCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to data space.COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Places a string of the form 
language_name.character_set_
name in *buffer.The application must have previously loaded the CS_LOCALE structure with consistent information by calling MOREINFO="NONE"cs_locale with type as CS_LC_ALL.If an application specifies only a language name, then MOREINFO="NONE"cs_locale uses the character set and sort order already specified in the pre-loaded CS_LOCALE structure. REMAP="UN--Under"If an application specifies only a character set name, then MOREINFO="NONE"cs_locale uses the language and sort order already specified in the pre-loaded CS_LOCALE structure. REMAP="UN--Under"If an application specifies only a sort order name, then MOREINFO="NONE"cs_locale uses the language and character set already specified in the pre-loaded CS_LOCALE structure. REMAP="UN--Under"If a language/character set/sort order combination is not valid, MOREINFO="NONE"cs_locale returns CS_FAIL.ID="IN47-297770"Localizationvalid language, character set, and sort order namesValid language names correspond to subdirectories in the $SYBASE/locales directory. Valid character set names correspond to subdirectories in the $SYBASE/charsets directory. Valid sort order names for a character set correspond to file names, stripped of any suffix, in the $SYBASE/charsets/character_set_name directory.If the required localization files for the requested language or character set do not exist, MOREINFO="NONE"cs_locale returns CS_FAIL.See AlsoREMAP="BO--Body"LINKEND="X53799"cs_loc_alloc
MOREINFO="NONE", LINKEND="X13400"cs_loc_drop
ID="IN47-268072"cs_objectscs_objectsID="IN48-268174"Objectssaving, retrieving, or clearing objects
ID="IN48-268175"Data valuessaving, retrieving, or clearing objects and the data associated with them
Save, retrieve, or clear objects and data associated with them.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE cs_objects(context, action, objname,               objdata) CS_CONTEXT     *context;CS_INT         action;CS_OBJNAME     *objname;CS_OBJDATA     *objdata;ParametersREMAP="RI--RefIndent"context - A pointer to a CS_CONTEXT structure. action - One of the following symbolic values:TOCENTRY="1"LBL="Table 2-33: "Values for action (MOREINFO="NONE"cs_objects)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"cs_objects:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Saves an object.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_GETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieves the first matching object that it finds.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CLEARCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Clears all matching objects.objname ID="IN48-248378"CS_OBJNAME structuredefinition
ID="IN48-248379"Object name structuredefinition
ID="IN48-228580"StructuresCS_OBJNAME:definition
- A pointer to an object name structure. *objname names and describes the object of interest. An object name structure is defined as follows:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"/*** CS_OBJNAME*/typedef struct _cs_objname{  CS_BOOL         thinkexists;  CS_INT          object_type;  CS_CHAR         last_name[CS_MAX_NAME];  CS_INT          lnlen;  CS_CHAR         first_name[CS_MAX_NAME];  CS_INT          fnlen;  CS_VOID         *scope;  CS_INT          scopelen;  CS_VOID         *thread;  CS_INT          threadlen;} CS_OBJNAME;REMAP="UN--Under"The following table describes the CS_OBJNAME fields:TOCENTRY="1"LBL="Table 2-34: "CS_OBJNAME fieldsCOLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="72*"COLNAME="C2" COLWIDTH="148*"COLNAME="C3" COLWIDTH="257*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Field:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Description:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Notes:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"thinkexists COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Indicates whether the 
application expects this object 
to exist.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The value of thinkexists affects MOREINFO="NONE"cs_objects' return code. 
For more information, see the MOREINFO="NONE"Returns section.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"object_type COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The type of the object.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"This field is the first part of a 5-part key.

Legal values are:

- CS_CONNECTNAME
- CS_CURSORNAME
- CS_STATEMENTNAME
- CS_CURRENT_CONNECTION
- CS_WILDCARD (matches any value)
- A user-defined value. User-defined values must be >= 
100.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"last_name COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The "last name" associated 
with the object of interest, if 
any.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"This field is the second part of a 5-part key.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"lnlen COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The length, in bytes, of 
last_name.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Can be CS_NULLTERM to indicate a null-terminated 
last_name. 

Can be CS_UNUSED to indicate an internal "unused" 
value for last_name.

For CS_GET and CS_CLEAR operations, can be 
CS_WILDCARD to match with any last_name value.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"first_name COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The "first name" associated 
with the object of interest, if 
any.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"This field is the third part of a 5-part key.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"fnlen COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The length, in bytes, of 
first_name.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Can be CS_NULLTERM to indicate a null-terminated 
first_name.

Can be CS_UNUSED to indicate an internal "unused" 
value for first_name.

For CS_GET and CS_CLEAR operations, can be 
CS_WILDCARD to match with any first_name value.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"scope COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Data that describes the scope 
of the object.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"This field is the fourth part of a 5-part key.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"scopelen COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The length, in bytes, of scope.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Can be CS_NULLTERM to indicate null-terminated 
scope data.

Can be CS_UNUSED to indicate an internal "unused" 
value for *scope.

For CS_GET and CS_CLEAR operations, can be 
CS_WILDCARD to match with any scope value.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"thread COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Platform-specific data that is 
used to distinguish threads in 
a multi-threaded execution 
environment.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"This field is the fifth part of a 5-part key.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"threadlen COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The length, in bytes, of thread.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Can be CS_NULLTERM to indicate null-terminated 
thread data. 

Can be CS_UNUSED to indicate an internal "unused" 
value for *thread.

For CS_GET and CS_CLEAR operations, can be 
CS_WILDCARD to match with any thread value.objdata ID="IN48-228581"Object data structuredefinition
ID="IN48-208782"CS_OBJDATA structuredefinition
ID="IN48-188983"StructuresCS_OBJDATA:definition
- A pointer to an object data structure. *objdata is the object of interest and any data associated with it. An object data structure is defined as follows:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"/*** CS_OBJDATA*/typedef struct _cs_objdata{  CS_BOOL           actuallyexists;  CS_CONNECTION     *connection;  CS_COMMAND        *command;  CS_VOID           *buffer;  CS_INT            buflen;} CS_NAMEDATA;REMAP="UN--Under"The following table describes the CS_OBJDATA fields:TOCENTRY="1"LBL="Table 2-35: "CS_OBJDATA fieldsCOLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="84*"COLNAME="C2" COLWIDTH="164*"COLNAME="C3" COLWIDTH="234*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Field:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Description:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Notes:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"actuallyexists COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Indicates whether this object 
actually exists.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"cs_objects sets actuallyexists to CS_TRUE if it finds 
a matching object.

MOREINFO="NONE"cs_objects sets actuallyexists to CS_FALSE if it does 
not find a matching object.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"connection COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to the 
CS_CONNECTION structure 
representing the connection in 
which the object exists.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"command COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to the CS_COMMAND 
structure representing the 
command space with which the 
object is associated, if any.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"buffer COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to data space. An 
application can use buffer to 
associate data with a saved object.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"If action is CS_SET, *buffer contains the data to 
associate with the object.

If action is CS_GET, MOREINFO="NONE"cs_objects sets *buffer to the 
data associated with the object being retrieved.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"buflen COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The length, in bytes, of *buffer.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"If action is CS_SET, buflen is the length of the data 
contained in *buffer. Can be CS_NULLTERM to 
indicate null-terminated data. Can be 
CS_UNUSED to indicate that there is no data 
associated with the object being saved.

If action is CS_GET, buflen is the maximum 
capacity of *buffer. MOREINFO="NONE"cs_objects overwrites buflen 
with the number of bytes copied to *buffer. If buflen 
is CS_UNUSED, MOREINFO="NONE"cs_objects overwrites buflen with 
the length of the data but does not copy it to 
*buffer.Summary of ParametersTOCENTRY="1"LBL="Table 2-36: "Summary of parameters (MOREINFO="NONE"cs_objects)COLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="82*"COLNAME="C2" COLWIDTH="162*"COLNAME="C3" COLWIDTH="228*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Value of action:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"objname is:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"objdata is:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A five-part key for the object.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The object to save, and any additional data to 
save with it.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_GETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A five-part key for the object.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Set to the retrieved object.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CLEARCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A five-part key for the object.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_UNUSEDReturnsTOCENTRY="1"LBL="Table 2-37: "Return values (MOREINFO="NONE"cs_objects)COLS="5" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="90*"COLNAME="C2" COLWIDTH="80*"COLNAME="C3" COLWIDTH="82*"COLNAME="C4" COLWIDTH="87*"COLNAME="C5" COLWIDTH="82*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="CENTER" ROTATE="0" MOREROWS="0"MOREINFO="NONE"cs_objects Called WithCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C3" ALIGN="CENTER" ROTATE="0" MOREROWS="0"MOREINFO="NONE"cs_objects ReturnsCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"action as:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"objnamename='rArrow' font='symbol' code='174'  charset='fontspecific'
thinkexists as:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No Match:COLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Last-Name 
Match:COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Full Match:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_GETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_GETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CLEARCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FAILCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CLEARCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FALSECOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C4" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SUCCEEDCommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"cs_objectsID="IN48-169187"cs_objectswhen to call
 is useful in precompiler applications that need to retrieve structures and data items by name.MOREINFO="NONE"cs_objectsID="IN48-149388"cs_objectsuse of a five-part key
 uses a five-part key, composed of the object_type, last_name, first_name, scope, and thread fields of *objname structure. MARK="DASH" REMAP="BS--BulletSub"On CS_SET operations, MOREINFO="NONE"cs_objects uses this key to store the *objdata object.On CS_GET operations, MOREINFO="NONE"cs_objects uses this key to retrieve an object specification into *objdata.On CS_CLEAR operations, MOREINFO="NONE"cs_objects clears all objects that match the key.The following table describes the rules that MOREINFO="NONE"cs_objects uses to determine whether or not key fields match:TOCENTRY="1"LBL="Table 2-38: "Key matching rules (MOREINFO="NONE"cs_objects)COLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="117*"COLNAME="C2" COLWIDTH="112*"COLNAME="C3" COLWIDTH="112*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"*objname Key Value:COLNAME="C2" ALIGN="CENTER" ROTATE="0" MOREROWS="0"Stored Key Value:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"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"Other Legal ValueVALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"CS_WILDCARDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MatchCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MatchCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"CS_UNUSEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MatchCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No matchCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"Other Legal ValueCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"No match COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Match if the values are 
equal and of the same 
length.ID="IN48-129589"cs_objectstypes of matches achieved
MOREINFO="NONE"cs_objects can achieve two types of matches:MARK="DASH" REMAP="BS--BulletSub""last-name matches," in which the last_name, scope, and thread parts of the key match."full matches," in which all five parts of the key match.REMAP="UN--Under"The type of match that MOREINFO="NONE"cs_objects achieves, together with action and objnamename='rArrow' font='symbol' code='174'  charset='fontspecific'thinkexists, determine its return code. On CS_GET and CS_CLEAR operations, an application can specify ID="IN48-109790"CS_WILDCARD constant
CS_WILDCARD for one or more *objname key fields:MARK="DASH" REMAP="BS--BulletSub"On a CS_GET operation, MOREINFO="NONE"cs_objects sets *objdata to reflect the first matching object that it finds.On a CS_CLEAR operation, MOREINFO="NONE"cs_objects clears all matching objects.If an application has previously saved a ID="IN48-89991"CS_CURRENT_CONNECTION objectretrieving the current connection
CS_CURRENT_CONNECTIONID="IN48-89992"Connectionretrieving the current connection
 object, it can retrieve the current connection by:MARK="DASH" REMAP="BS--BulletSub"Calling MOREINFO="NONE"cs_objects with objnamename='rArrow' font='symbol' code='174'  charset='fontspecific'object_type as CS_CURRENT_CONNECTION, lnlen as CS_UNUSED, and fnlen as CS_UNUSED. MOREINFO="NONE"cs_objects ignores the last_name and first_name fields of objname, and sets objdataname='rArrow' font='symbol' code='174'  charset='fontspecific'buffer to the name of the current connection and objdataname='rArrow' font='symbol' code='174'  charset='fontspecific'buflen to the length of this name.Calling MOREINFO="NONE"cs_objects with objnamename='rArrow' font='symbol' code='174'  charset='fontspecific'object_type as CS_CONNECTNAME and objnamename='rArrow' font='symbol' code='174'  charset='fontspecific'last_name and objnamename='rArrow' font='symbol' code='174'  charset='fontspecific'lnlen as the newly-retrieved connection name and name length. MOREINFO="NONE"cs_objects sets objdata to the retrieved connection.MOREINFO="NONE"cs_objects(CS_SETID="IN48-610193"cs_objectswhen not to call
) is not asynchronous-safe. Because of this, an application cannot call MOREINFO="NONE"cs_objects(CS_SET) from within a completion callback routine.See AlsoREMAP="BO--Body"LINKEND="X31916"cs_ctx_alloc
ID="IN48-310495"cs_objects
MOREINFO="NONE" ID="IN48-010796"cs_set_convertID="X71737"cs_set_convertID="IN49-010898"Conversioninstalling or retrieving a conversion routine
Install or retrieve a user-defined conversion routine.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE cs_set_convert(context, action, srctype,              desttype, func) CS_CONTEXT    *context;CS_INT        action;CS_INT        srctype;CS_INT        desttype;CS_CONV_FUNC  *func;ParametersREMAP="RI--RefIndent"context - A pointer to a CS_CONTEXT structure.   A CS_CONTEXT structure defines a Client-Library application context. action - One of the following symbolic values:TOCENTRY="1"LBL="Table 2-39: "Values for action (MOREINFO="NONE"cs_set_convert)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"cs_set_convert:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Installs a conversion routine.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_GETCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Retrieves the current conversion routine of this 
type.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CLEARCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Clears the current conversion routine by replacing 
it with CS-Library's default conversion routine of 
this type.srctype - The datatype of the source data for the conversion.desttype - The datatype of the destination data.func - A pointer variable.REMAP="UN--Under"If a conversion routine is being installed, func is the address of the conversion routine to install.REMAP="UN--Under"If a conversion routine is being retrieved, MOREINFO="NONE"cs_set_convert sets *func to the address of the currently-installed conversion routine.REMAP="UN--Under"If a conversion routine is being cleared, pass func as NULL.ReturnsTOCENTRY="1"LBL="Table 2-40: "Return values (MOREINFO="NONE"cs_set_convert)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="IN49--2110102"cs_set_convertreason for failureREMAP="BO--Body"The most common reason for a MOREINFO="NONE"cs_set_convert failure is an invalid parameter.CommentsID="IN49--2110104"Conversionwhy install custom conversion routines?MARK="BULL" REMAP="BU--Bullet"An application can install custom conversion routines to convert data between:MARK="DASH" REMAP="BS--BulletSub"Standard Open Client or Open Server datatypesStandard and user-defined datatypesUser-defined datatypesID="IN49--2110105"Conversionhow custom conversion routines workOnce a custom routine is installed for a particular conversion, the client/server libraries call the custom routine transparently whenever a conversion of the specified type is required.ID="IN49--2110106"Datatypecreating a user-defined datatypeA Client-Library or Server-Library application creates a user-defined datatype by declaring it:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"typedef CS_SMALLINT          EMPLOYEE_ID;REMAP="UN--Under"Because the Open Client routines MOREINFO="NONE"ct_bind and MOREINFO="NONE"cs_set_convertID="IN49--4112107"User-defined datatypesmust be greater than or equal to CS_USERTYPE
ID="IN49--6114108"Datatypeuser-defined datatypes must be greater than or equal to CS_USERTYPE
 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 ID="IN49--8116109"CS_USERTYPE constant
CS_USERTYPE:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"#define EMPLOYEE_ID_TYPE     CS_USERTYPE + 1;REMAP="UN--Under"To enable conversion between a user-defined type and standard CS-Library datatypes, an application can call MOREINFO="NONE"cs_set_convert to install user-defined conversion routines for the new type. ID="IN49--8116110"Conversionclearing a custom conversion routineTo clear a custom conversion routine, an application can call MOREINFO="NONE"cs_set_convert with action as CS_CLEAR and func as NULL. MOREINFO="NONE"cs_set_convert replaces the custom routine with CS-Library's default conversion routine of the appropriate type, if any.An application can call MOREINFO="NONE"cs_setnullID="IN49--8116111"Datatypedefining null substitution values for user-defined datatypes
 to define null substitution values for a user-defined type.ID="IN49--8116112"Conversiondefining a custom conversion routineDefining a Custom Conversion RoutineMARK="BULL" REMAP="BU--Bullet"A custom conversion routine is defined as follows:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"CS_RETCODE convfunc(context, srcfmt, srcdata,              destfmt, destdata, destlen)CS_CONTEXT         *context;CS_DATAFMT         *srcfmt;CS_VOID            *srcdata;CS_DATAFMT         *destfmt;CS_VOID            *destdata;CS_INT             *destlen;REMAP="UN--Under"where:REMAP="UN--Under"context is a pointer to a CS_CONTEXT structure.REMAP="UN--Under"srcfmt is a pointer to a CS_DATAFMT structure describing the source data. srcfmtname='rArrow' font='symbol' code='174'  charset='fontspecific'
maxlength describes the actual length, in bytes, of the source data.REMAP="UN--Under"srcdata is a pointer to the source data.REMAP="UN--Under"destfmt is a pointer to a CS_DATAFMT structure describing the destination data. destfmtname='rArrow' font='symbol' code='174'  charset='fontspecific'
maxlength describes the actual length, in bytes, of the destination data space.REMAP="UN--Under"destdata is a pointer to the destination data space.REMAP="UN--Under"destlen is a pointer to an integer. If the conversion is successful, the custom routine should set *destlen to the number of bytes placed in *destdata.ID="IN49--10118113"Conversioncs_config:only routine callable from within a custom conversion routine
MOREINFO="NONE"cs_config is the only CS-Library, Client-Library, or Server-Library function that can be called from within a custom conversion routine.The following table lists the legal return values for a custom conversion routine. The client/server libraries use a custom conversion routine's return value to determine what, if any, message to return to an application:TOCENTRY="1"LBL="Table 2-41: "Return values for a custom conversion routineCOLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="153*"COLNAME="C2" COLWIDTH="189*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Return Value: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"Successful conversion.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TRUNCATEDCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The conversion resulted in truncation.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_MEM_ERRORCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A memory allocation failure has 
occurred.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_EBADXLTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Some characters could not be 
translated.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_ENOXLTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The requested translation is not 
supported.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_EDOMAINCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The source value is outside the domain 
of legal values for the datatype.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_EDIVZEROCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Division by zero is not allowed.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_EOVERFLOWCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The conversion resulted in overflow.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_EUNDERFLOWCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The conversion resulted in underflow.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_EPRECISIONCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The conversion resulted in loss of 
precision.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_ESCALECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"An illegal scale value was encountered.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_ESYNTAXCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The conversion resulted in a value 
which is not syntactically correct for the 
destination type.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_ESTYLECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The conversion operation was stopped 
due to a style error.See AlsoREMAP="BO--Body"LINKEND="X12687"cs_convert
MOREINFO="NONE", LINKEND="X87482"cs_setnull
MOREINFO="NONE", LINKEND="X29013" BOOK="ref"ct_bind
ID="IN49--13121115"cs_set_convert
MOREINFO="NONE"   ID="IN49--16124116"cs_setnullID="X87482"cs_setnullID="IN50--16125118"Substitution valuesdefining a null substitution value
Define a null substitution value to be used when binding or converting ID="IN50--18127119"NULL datadefining a null substitution value
NULL data.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE cs_setnull(context, datafmt, buffer,                buflen) CS_CONTEXT      *context;CS_DATAFMT      *datafmt;CS_VOID         *buffer;CS_INT          buflen;ParametersREMAP="RI--RefIndent"context - A pointer to a CS_CONTEXT structure. MOREINFO="NONE"cs_setnull defines a null substitution value for this context.datafmt - A pointer to a CS_DATAFMT structure describing the datatype for which a null substitution value is being defined.buffer - A pointer to the null substitution value. *buffer's datatype must match datafmtname='rArrow' font='symbol' code='174'  charset='fontspecific'type.buflen - The length, in bytes, of *buffer.ReturnsTOCENTRY="1"LBL="Table 2-42: "Return values (MOREINFO="NONE"cs_setnull)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="IN50--20129123"cs_setnullreasons for failureREMAP="BO--Body"Common reasons for a MOREINFO="NONE"cs_setnull failure include:MARK="BULL" REMAP="BU--Bullet"A memory allocation errorAn invalid parameterCommentsMARK="BULL" REMAP="BU--Bullet"If ID="IN50--20129125"ANSI-style bindsnull substitution values not used when in effect
ANSIID="IN50--20129126"Substitution valuesnot null when ANSI-style binds are in effect
-style binds are in effect, CS-Library does not use null substitution values. To activate ANSI-style binds, an application sets the Client-Library property CS_ANSI_BINDS to CS_TRUE.When ANSI-style binds are not in effect and source data for a conversion is NULL, CS-Library sets the destination data to the predefined null substitution value for that destination type. For example, converting a NULL value of any type to a CS_CHAR destination results in an empty string.ID="IN50--20129127"Substitution valuesnull substitution values defined at context levelIn a Client-Library application, null substitution values are defined at the context level. When a Client-Library connection is allocated, it picks up null substitution values from its parent context.ID="IN50--24133128"NULL dataconverting a NULL source valueWhen converting a NULL source value to a CS_CHAR or CS_BINARY destination variable, CS-Library first puts 0 bytes into the destination and then uses the format field of the CS_DATAFMT structure that describes the destination to determine whether to pad or null-terminate.To reinstate CS-Library's original default null substitution value for a particular datatype, an application can call MOREINFO="NONE"cs_setnull with buffer as NULL.ID="IN50--24133129"Substitution valuesdefault null substitution valuesCS-Library and Client-Library use the following default null substitution values:TOCENTRY="1"LBL="Table 2-43: "Default null substitution valuesCOLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="170*"COLNAME="C2" COLWIDTH="195*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Destination TypeCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Null Substitution ValueVALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BINARY_TYPECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Empty arrayCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_VARBINARY_TYPECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Empty arrayCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BIT_TYPECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"0COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_CHAR_TYPECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Empty stringCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_VARCHAR_TYPECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Empty stringCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATETIME_TYPECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"8 bytes of zerosCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DATETIME4_TYPECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"4 bytes of zerosCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TINYINT_TYPECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"0COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SMALLINT_TYPECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"0COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_INT_TYPECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"0COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_DECIMAL_TYPECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"0.0 (with default scale and precision)COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_NUMERIC_TYPECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"0.0 (with default scale and precision)COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_FLOAT_TYPECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"0.0COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_REAL_TYPECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"0.0COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_MONEY_TYPECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"$0.0COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_MONEY4_TYPECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"$0.0COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BOUNDARY_TYPECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Empty stringCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_SENSITIVITY_TYPECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Empty stringCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_TEXT_TYPECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Empty stringCOLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_IMAGE_TYPECOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Empty arraySee AlsoREMAP="BO--Body"LINKEND="X71737"cs_set_convert
MOREINFO="NONE", LINKEND="X59015"cs_will_convertcs_strbuildID="IN43C-9753"Constructing national language message strings
ID="IN43C-9754"National language message stringsconstructing
ID="IN43A-9755"Language message stringsconstructing
ID="IN43-9756"Message stringsconstructing national language message strings
ID="IN43-9757"Stringsconstructing national language message strings
Construct national language message strings.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE cs_strbuild(context, buffer, buflen,            resultlen, text, textlen             [, formats, formatlen]            [, arguments]); CS_CONTEXT  *context;CS_CHAR     *buffer;CS_INT      buflen;CS_INT      *resultlen;CS_CHAR     *text;CS_INT      textlen;CS_CHAR     *formats;        /* Optional */CS_INT      formatlen;       /* Optional */<optional arguments>ParametersREMAP="RI--RefIndent"context - A pointer to a CS_CONTEXT structure.buffer - A pointer to the space in which MOREINFO="NONE"cs_strbuild places the finished message. Note that the finished message is not a null-terminated string. An application must use *resultlen to determine the length of the message placed in *buffer.buflen - The length, in bytes, of the *buffer data space.resultlen - A pointer to an integer variable. MOREINFO="NONE"cs_strbuild sets *resultlen to the length, in bytes, of the string placed in *buffer.text - A pointer to the unfinished text of the message. The *text string contains message text and placeholders for variables. A placeholder has the form %integer!, for example %1!, %2!, and so forth. The integer indicates which argument to substitute for a particular place holder. Arguments are numbered from left to right.textlen - The length, in bytes, of *text. If *text is null-terminated, pass textlen as CS_NULLTERM.formats - A pointer to a string containing one MOREINFO="NONE"sprintf-style format specifier for each place holder in the *text string.formatlen - The length, in bytes, of *formats. If *formats is null-terminated, pass formatlen as CS_NULLTERM.arguments - The values which will be converted to character according to the *formats string and substituted into the *text string to produce the message which is placed in *buffer.REMAP="UN--Under"There must be one argument for each placeholder. The first value corresponds to the first format and the %1! placeholder, the second value corresponds to the second format and the %2! placeholder, and so forth. REMAP="UN--Under"If insufficient arguments are supplied, MOREINFO="NONE"cs_strbuild generates unpredictable results.REMAP="UN--Under"If too many arguments are supplied, the excess arguments are ignored.ReturnsTOCENTRY="1"LBL="Table 2-44: "Return values (MOREINFO="NONE"cs_strbuild)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"cs_strbuild builds a printable national language message string from a text containing placeholders for values, a format string containing information on the types and appearances of the values, and a variable number of arguments that represent the values.Parameters in error messages can occur in different orders in different languages. MOREINFO="NONE"cs_strbuild allows an application to construct error messages in a MOREINFO="NONE"sprintf-like fashion to ensure easy translation of error messages from one language to another.REMAP="UN--Under"For example, consider an error message that informs of a misused keyword in a stored procedure. The message requires three arguments: the misused keyword, the line in which the keyword occurs, and the name of the stored procedure. In the English localization file, the message text appears as:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"The keyword `%1!` is misused in line %2! of stored procedure `%3!`.REMAP="UN--Under"In the Yoda-speak localization file, the same message appears as:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"In line %2! of stored procedure `%3!`, the keyword `%1!` misused is!REMAP="UN--Under"The MOREINFO="NONE"cs_strbuild call for either of the above messages is:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"cs_strbuild(context, &mybuffer, buflength,   &resultlength, messagetext, CS_NULLTERM,   "%s, %d, %s", CS_NULLTERM,   keyword, linenum, sp_name);REMAP="UN--Under"The only difference is in the content of messagetext.MOREINFO="NONE"cs_strbuild format specifiers can be separated by any other characters, or they can be adjacent to each other. This allows pre-existing English-language message strings to be used as format parameters. The first format specifier describes the %1! placeholder, the second the %2! placeholder, and so forth.See AlsoREMAP="BO--Body"LINKEND="X37478"cs_dt_crack
MOREINFO="NONE", LINKEND="X91463"cs_dt_info
MOREINFO="NONE", LINKEND="X37122"cs_locale
ID="IN43-94813"cs_strcmpID="X83895"cs_strcmpID="IN44-94915"Comparingstrings
ID="IN44-94916"Stringscomparing using a specified sort order
Compare two strings using a specified sort order.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE cs_strcmp(context, locale, type str1,              len1, str2, len2, result) CS_CONTEXT    *context;CS_LOCALE     *locale;CS_INT        type;CS_CHAR       *str1;CS_INT        len1;CS_CHAR       *str2;CS_INTl       en2;CS_INT        *result;ParametersREMAP="RI--RefIndent"context - A pointer to a CS_CONTEXT structure.locale - A pointer to a CS_LOCALE structure. A CS_LOCALE structure contains locale information, including the collating sequence that MOREINFO="NONE"cs_strcmp uses to define a sort order.REMAP="UN--Under"An application can call MOREINFO="NONE"cs_locale with type as CS_LC_COLLATE or CS_SYB_SORTORDERID="IN44-94919"Collating sequencechanging
 to change the collating sequence in a CS_LOCALE structure.REMAP="UN--Under"locale can be NULL. If locale is NULL, MOREINFO="NONE"cs_strcmp uses whatever localization information is defined in the context CS_CONTEXT structure. Localization information is always defined at the context level, because a CS_CONTEXT picks up default localization information when it is allocated.type - The type of comparison to perform. REMAP="UN--Under"If type is CS_COMPARE, MOREINFO="NONE"cs_strcmp performs a lexicographic comparison.REMAP="UN--Under" If type is CS_SORT, the values are compared as they would appear in a sorted list. It is possible for strings that are lexicographically equal to belong in different places in a sorted list.str1 - A pointer to the first string for the comparison.len1 - The length, in bytes, of *str1. If *str1 is null-terminated, pass len1 as CS_NULLTERM.str2 - A pointer to the second string for the comparison.len2 - The length, in bytes, of *str2. If *str2 is null-terminated, pass len2 as CS_NULLTERM.result - A pointer to the result of the comparison. The following table lists the possible values for *result:TOCENTRY="1"LBL="Table 2-45: "Values for *result (MOREINFO="NONE"cs_strcmp)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="90*"COLNAME="C2" COLWIDTH="189*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Value of *result:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To Indicate:VALIGN="TOP"COLNAME="C1" ALIGN="CENTER" ROTATE="0" MOREROWS="0"<0COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"str1 is lexicographically less than str2, or 
str1 appears before str2 in a sorted list.COLNAME="C1" ALIGN="CENTER" ROTATE="0" MOREROWS="0"0COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"str1 is lexicographically equal to str1, or 
str1 is identical to str2.COLNAME="C1" ALIGN="CENTER" ROTATE="0" MOREROWS="0">0COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"str1 is lexicographically greater than 
str2, or str1 appears after str2 in a sorted 
list.ReturnsTOCENTRY="1"LBL="Table 2-46: "Return values (MOREINFO="NONE"cs_strcmp)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"cs_strcmp sets *result to indicate the result of the comparison.Some languages contain strings that are lexicographically equal according to a specific sort order, but contain different characters. Even though they are "equal," there is a standard order used when placing them into a sorted list. REMAP="UN--Under"For example, given a case-insensitive sort order that specifies that uppercase characters appear before lowercase characters in a sorted list, the strings "ABC" and "abc" are lexicographically equal, but do not appear in the same place in a sorted list.REMAP="UN--Under"An application can use MOREINFO="NONE"cs_strcmpID="IN44-94922"Lexicographical string comparison
ID="IN44-94923"Sorted string comparison
 to compare strings either lexicographically or with respect to how they appear in a sorted list.MOREINFO="NONE"cs_strcmp determines which sort order to use by examining *locale, (or *context, if locale is NULL). ID="IN44-921124"Sort orderchanging in a CS_LOCALE structureMARK="DASH" REMAP="BS--BulletSub"To change the sort order in a CS_LOCALE structure, an application calls MOREINFO="NONE"cs_locale with type as CS_LC_COLLATE or CS_SYB_SORTORDER.ID="IN44-901325"Sort orderchanging in a CS_CONTEXT structureTo change the sort order in a CS_CONTEXT structure, an application must first set up a CS_LOCALE structure with the desired sort order and then call MOREINFO="NONE"cs_config to set the CS_LOC_PROP property for the context.See AlsoREMAP="BO--Body"LINKEND="X26447"cs_cmp
MOREINFO="NONE", LINKEND="X37122"cs_locale
MOREINFO="NONE", LINKEND="X21848"cs_config
ID="IN44-871627"cs_timecs_timeID="IN45-871729"Dateretrieving the current date
ID="IN45-871730"Timeretrieving the current time
Retrieve the current date and time.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE cs_time(context, locale, buffer, buflen,               outlen, daterec) CS_CONTEXT     *context;CS_LOCALE      *locale;CS_VOID        *buffer;CS_INT         buflen;CS_INT         *outlen;CS_DATEREC     *daterec;ParametersREMAP="RI--RefIndent"context - A pointer to a CS_CONTEXT structure. locale - A pointer to a CS_LOCALE structure. A CS_LOCALE structure contains locale information, including formatting information that MOREINFO="NONE"cs_time uses to create a current datetime string.REMAP="UN--Under"locale can be NULL. If locale is NULL, MOREINFO="NONE"cs_time uses whatever localization information is defined in the context CS_CONTEXT structure. Localization information is always defined at the context level, because a CS_CONTEXT picks up default localization information when it is allocated.buffer - A pointer to the space in which MOREINFO="NONE"cs_time will place a character string representing the current date and time.REMAP="UN--Under"buffer is an optional parameter and can be passed as NULL. If buffer is NULL, daterec must be supplied.buflen - The length, in bytes, of *buffer.REMAP="UN--Under"If buffer is supplied and buflen indicates that *buffer is not large enough to hold the current datetime string, MOREINFO="NONE"cs_time sets *MOREINFO="NONE"outlen to the length of the datetime string and returns CS_FAIL. REMAP="UN--Under"If buffer is NULL, pass buflen as CS_UNUSED.outlen - A pointer to an integer variable. REMAP="UN--Under"MOREINFO="NONE"cs_time sets *outlen to the length, in bytes, of the current datetime string.REMAP="UN--Under"If the 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 buffer is NULL, pass outlen as NULL.REMAP="UN--Under"If an application does not care about return length information, it can pass MOREINFO="NONE"outlen as NULL.daterec - A pointer to a CS_DATEREC structure in which MOREINFO="NONE"cs_time will place the current date and time. Note that MOREINFO="NONE"cs_time does not fill in the datemsecond and datetzone fields of the CS_DATEREC structure.REMAP="UN--Under"For more information on the CS_DATEREC structure, see the manual page for MOREINFO="NONE"cs_dt_crack.REMAP="UN--Under"daterec is an optional parameter and can be passed as NULL. If daterec is NULL, buffer must be supplied.ReturnsTOCENTRY="1"LBL="Table 2-47: "Return values (MOREINFO="NONE"cs_time)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="IN45-851934"cs_timereasons for failureREMAP="BO--Body"Common reasons for a MOREINFO="NONE"cs_time failure include:MARK="BULL" REMAP="BU--Bullet"An invalid parameter.buflen indicates that the *buffer data space is not large enough to hold the formatted datetime string.CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"cs_time returns the current date and time either in character string format or in a CS_DATEREC structure, or both.MOREINFO="NONE"cs_time formats the date and time according to locale information contained in *context. See AlsoREMAP="BO--Body"MOREINFO="NONE"cs_ctx_props, LINKEND="X37478"cs_dt_crack
MOREINFO="NONE", LINKEND="X91463"cs_dt_info
MOREINFO="NONE", LINKEND="X37122"cs_locale
ID="IN45-822237"cs_will_convertID="X59015"cs_will_convertID="IN46-822339"Conversionindicating whether a specific datatype conversion is available
Indicate whether a specific datatype conversion is available in the Client/Server libraries.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE cs_will_convert(context, srctype, desttype,               result) CS_CONTEXT     *context;CS_INT         srctype;CS_INT         desttype;CS_BOOL        *result;ParametersREMAP="RI--RefIndent"context - A pointer to a CS_CONTEXT structure.srctype - The datatype of the source data.desttype - The datatype of the destination data.result - A pointer to a boolean variable. MOREINFO="NONE"cs_will_convert sets *result to CS_TRUE if the datatype conversion is supported and CS_FALSE if the datatype conversion is not supported.Datatype Conversion ChartREMAP="BO--Body"A chart listing the datatype conversions that MOREINFO="NONE"cs_convert supports is included on the manual page for MOREINFO="NONE"cs_convert.ReturnsTOCENTRY="1"LBL="Table 2-48: "Return values (MOREINFO="NONE"cs_will_convert)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"cs_will_convert allows an application to determine whether MOREINFO="NONE"cs_convert is capable of performing a specific conversion. When MOREINFO="NONE"cs_convert is asked to perform a conversion that it doesn't support, it returns CS_FAIL and generates a CS-Library error.MOREINFO="NONE"cs_convert can convert between standard and user-defined datatypes. To enable these types of conversions, an application must install custom conversion routines via MOREINFO="NONE"cs_set_convert. If a custom routine is supplied for a conversion, MOREINFO="NONE"cs_will_convert will indicate that the conversion is supported.ID="IN46-802545"cs_will_convertcode exampleExampleREMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/*** ex_display_column()*/REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"CS_RETCODE CS_PUBLICex_display_column(context, colfmt, data, datalength,     indicator)CS_CONTEXT           *context;CS_DATAFMT           *colfmt;CS_VOID              *data;CS_INT               datalength;CS_SMALLINT          indicator;{   char         *null = "NULL";   char         *nc   = "NO CONVERT";   char         *cf   = "CONVERT FAILED";   CS_DATAFMT   srcfmt;   CS_DATAFMT   destfmt;   CS_INT       olen;   CS_CHAR      wbuf[MAX_CHAR_BUF];   CS_BOOL      res;   CS_INT       i;   CS_INT       disp_len; if (indicator == CS_NULLDATA){    olen = strlen(null);    strcpy(wbuf, null);}else{    cs_will_convert(context, colfmt->datatype,       CS_CHAR_TYPE, &res);     if (res != CS_TRUE){       olen = strlen(nc);       strcpy(wbuf, nc);}else{       srcfmt.datatype  = colfmt->datatype;       srcfmt.format    = colfmt->format;       srcfmt.locale    = colfmt->locale;       srcfmt.maxlength = datalength;        destfmt.maxlength = MAX_CHAR_BUF;       destfmt.datatype  = CS_CHAR_TYPE;       destfmt.format    = CS_FMT_NULLTERM;       destfmt.locale    = NULL;        if (cs_convert(context, &srcfmt, data,          &destfmt, wbuf, &olen) != CS_SUCCEED)       {          olen = strlen(cf);          strcpy(wbuf, cf);       }       else       {          /*          ** output length include null          ** termination          */          olen -= 1;       }   }}fprintf(stdout, "%s", wbuf); disp_len = ex_display_dlen(colfmt);for (i = 0; i < (disp_len - olen); i++){   fputc(' ', stdout);}    return CS_SUCCEED;}See AlsoREMAP="BO--Body"LINKEND="X12687"cs_convert
MOREINFO="NONE", LINKEND="X71737"cs_set_convert
MOREINFO="NONE", LINKEND="X87482"cs_setnull
MOREINFO="NONE", LINKEND="X22337" BOOK="ref"Types
ID="IN46-772848"cs_will_convert
MOREINFO="NONE" NUMBER="3" ID="X73052"Introducing Bulk CopyREMAP="BO--Body"Bulk copy is a tool for the high-speed transfer of data between a database table and program variables. It provides an alternative to the use of SQL MOREINFO="NONE"insert and MOREINFO="NONE"select commands to transfer data.REMAP="BO--Body"Open Client Client-Library includes client-side bulk copy routines, while Open Server Server-Library includes server-side bulk copy routines.REMAP="BO--Body"Both Client-Library and Server-Library bulk copy routines are documented in this manual.ID="IN3-9831"bkpublic.h header file
ID="IN3-9652"Header filesbkpublic.h
ID="IN3-9473"Bulk copybkpublic.h header fileREMAP="BO--Body"The header file bkpublic.h contains bulk copy definitions and is required in all application source files that contain calls to bulk copy routines.ID="IN3-9474"Bulk copy client-side bulk copy routinesRENDERAS="SECT1"Client-Side Bulk Copy RoutinesID="IN3-9475"Bulk copypurposeREMAP="BO--Body"Client-Library bulk copy routines provide bulk copy functionality to Client-Library programs. A Client-Library program may find bulk copy useful if it needs to exchange data with a non-database application, load data into a new database, or move data from one database to another.REMAP="BO--Body"A Client-Library application can use bulk copy routines to either copy data into, or from, a database.ID="IN3-9476"Bulk copycopying data into a databaseRENDERAS="SECT2"Bulk Copies Into a DatabaseREMAP="BO--Body"An application can use Client-Library bulk copy routines to copy data from program variables into a database table.ID="IN3-9477"Bulk copyadvantages over alternativesREMAP="BO--Body"When copying into a database, the chief advantage of bulk copy over the SQL MOREINFO="NONE"insert alternative is speed. Also, while bulk copy can transfer native datatypes, SQL MOREINFO="NONE"insert requires that the data be in character string format.ID="IN3-9478"Bulk copyhigh speed transfer
ID="IN3-9299"SQL Server bulkcopy option
ID="IN3-901110"Bulk copybulkcopy optionREMAP="BO--Body"When copying data into a non-indexed table, the "high speed" version of bulk copy is used. High-speed means that no data logging is performed during the transfer. If the system fails before the transfer is complete, no new data will remain in the database. Because high-speed transfer affects the recoverability of the database, it is only enabled if the SQL Server option ID="IN3-881311"bulkcopy option
MOREINFO="NONE"select into/bulkcopyID="IN3-861512"Bulk copySQL Server bulkcopy option
 has been turned on. An application can call the SYBASE system procedure ID="IN3-841713"sp_dboption system procedure
ID="IN3-821914"Bulk copysp_dboption system procedure
MOREINFO="NONE"sp_dboption to turn this option on.REMAP="BO--Body"If the option is not set on and a user tries to copy data into a table that has no indexes, SQL Server generates an error message.ID="IN3-821915"Bulk copyensuring recoverabilityREMAP="BO--Body"After a bulk copy is complete, the system administrator should dump the database to ensure its future recoverability.ID="IN3-802116"Bulk copylogging row insertsREMAP="BO--Body"When copying data into an indexed table, a slower version of bulk copy is automatically used, and row inserts are logged.RENDERAS="SECT3"Program Structure for Copies Into a DatabaseID="IN3-802117"Bulk copysteps for copying data into a databaseREMAP="BO--Body"To perform a bulk copy into a database, a typical application follows these steps after allocating a connection structure for the bulk copy:NUMERATION="ARABIC" REMAP="S1--StepOne" CONTINUATION="RESTARTS" INHERITNUM="IGNORE"Call MOREINFO="NONE"ct_con_props to set the following properties for the connection:MARK="DASH" REMAP="BS--BulletSub"CS_BULK_LOGINAn application must set this property to CS_TRUE to enable the connection to perform bulk copies.CS_USERNAMECS_PASSWORDCall MOREINFO="NONE"ct_connect to open the connection.Call MOREINFO="NONE"blk_alloc to allocate a CS_BLKDESC.Call MOREINFO="NONE"blk_init to initialize the bulk copy operation.For each target column:MARK="DASH" REMAP="BS--BulletSub"Call MOREINFO="NONE"blk_describe, if desired. MOREINFO="NONE"blk_describe returns a column's description and can be useful if an application lacks information about a column's datatype or size.Call MOREINFO="NONE"blk_default, if desired. MOREINFO="NONE"blk_default returns a column's default value, if any. An application can call MOREINFO="NONE"blk_bind with *datalen as 0 to indicate that bulk copy should use a column's default value.Call MOREINFO="NONE"blk_bind to bind the variable to the target column. If data for the column will be transferred using MOREINFO="NONE"blk_textxfer, call MOREINFO="NONE"blk_bind with buffer as NULL. If bulk copy should use a column's default value, call MOREINFO="NONE"blk_bind with *datalen as 0.Note that it is possible to bind an array of program variables
to a column. This technique, called "array binding," enables multiple
rows to be transferred with a single call to MOREINFO="NONE"blk_rowxfer. The discussion in this chapter assumes that array binding is not in effect. For more information on array binding, see the manual page for LINKEND="X80356"blk_bind in Chapter 4 of this manual.Transfer the data:REMAP="UN--Under"While data remains to be transferred, pull data into program variables and call MOREINFO="NONE"blk_rowxfer to transfer the row.REMAP="UN--Under"If the row contains columns whose data is being transferred in chunks, call MOREINFO="NONE"blk_textxfer in a loop for each column. Data being transferred via MOREINFO="NONE"blk_textxfer must reside at the end of the row, following any bound columns.REMAP="UN--Under"Call MOREINFO="NONE"blk_done(CS_BLK_BATCH), if desired, to send a "batch" of rows. This call tells SQL Server to permanently save all rows transferred since the application's last MOREINFO="NONE"blk_done call. Call MOREINFO="NONE"blk_done(CS_BLK_ALL) to send the last batch of rows and indicate that the bulk copy operation is complete.Call MOREINFO="NONE"blk_drop to de-allocate the CS_BLKDESC.An application can call MOREINFO="NONE"blk_bind between calls to MOREINFO="NONE"blk_rowxfer if it needs to change a program variable's address or length.REMAP="BO--Body"Most applications will use a program structure similar to the following to perform a bulk copy into the database:FLOAT="0"FORMAT="UNKNOWN" FILEREF="fig3_1.xwd"LBL="Figure 3-1: "Bulk copying into the databaseID="IN3-802118"Bulk copycopying data from a databaseRENDERAS="SECT2"Bulk Copies From a DatabaseREMAP="BO--Body"An application can use Client-Library bulk copy routines to copy data from a database table into program variables.RENDERAS="SECT3"Program Structure for Copies From a DatabaseID="IN3-802119"Bulk copysteps for copying data from a databaseREMAP="BO--Body"To perform a bulk copy out from a database, a typical application follows these steps after allocating a connection structure for the bulk copy:NUMERATION="ARABIC" REMAP="S1--StepOne" CONTINUATION="RESTARTS" INHERITNUM="IGNORE"Call MOREINFO="NONE"ct_con_props to set the following properties for the connection:MARK="DASH" REMAP="BS--BulletSub"CS_USERNAME CS_PASSWORD Call MOREINFO="NONE"ct_connect to open the connection.Call MOREINFO="NONE"blk_alloc to allocate a CS_BLKDESC.Call MOREINFO="NONE"blk_init to initialize the bulk copy operation.For each source column of interest:MARK="DASH" REMAP="BS--BulletSub"Call MOREINFO="NONE"blk_describe, if desired. MOREINFO="NONE"blk_describe returns a column's description and can be useful if an application lacks information about a column's datatype or size.Call MOREINFO="NONE"blk_bind to bind a program variable to the source column. If the data for a column will be transferred via MOREINFO="NONE"blk_textxfer, call MOREINFO="NONE"blk_bind with *buffer as NULL.Note that it is possible to bind an array of program variables
to a column. This technique, called "array binding," enables multiple
rows to be transferred with a single call to MOREINFO="NONE"blk_rowxfer. The discussion in this chapter assumes that array binding is not in effect. For more information on array binding, see the manual page for LINKEND="X80356"blk_bind .Transfer the data:REMAP="UN--Under"While data remains to be transferred, call MOREINFO="NONE"blk_rowxfer to transfer a row to program variables. REMAP="UN--Under"If the row contains columns whose data is being transferred in chunks, call MOREINFO="NONE"blk_textxfer in a loop for each column. Data being transferred via MOREINFO="NONE"blk_textxfer must reside at the end of the row, following any bound columns.REMAP="UN--Under"For example, suppose an application is bulk-copying columns 1, 3, 5, 7 and 9 of a table, and needs to use MOREINFO="NONE"blk_textxfer to copy columns 7 and 9. The application calls MOREINFO="NONE"blk_bind once for each column, passing buffer as NULL for columns 7 and 9. After calling MOREINFO="NONE"blk_rowxfer to transfer a row from the table, the application must call MOREINFO="NONE"blk_textxfer in a loop to copy the data for column 7, and then call MOREINFO="NONE"blk_textxfer in another loop to copy the data for column 9.Call MOREINFO="NONE"blk_done(CS_BLK_ALL) to indicate that the bulk copy operation is complete.Call MOREINFO="NONE"blk_drop to de-allocate the CS_BLKDESC.An application can call MOREINFO="NONE"blk_bind between calls to MOREINFO="NONE"blk_rowxfer if it needs to change a program variable's address or length. REMAP="BO--Body"Most applications will use a program structure similar to the following to perform a bulk copy from the database:FLOAT="0"FORMAT="UNKNOWN" FILEREF="fig3_2.xwd"LBL="Figure 3-2: "Bulk copying from the databaseID="IN3-802120"Secure SQL Server bulk copiesRENDERAS="SECT2"Copying To and From a Secure SQL ServerID="IN3-802121"Bulk copycopying data to and from a Secure SQL ServerREMAP="BO--Body"Each row in a Secure SQL Server table has a sensitivityID="IN3-802122"Sensitivity label
ID="IN3-802123"Secure SQL Serversensitivity labels
 column, which contains the sensitivity label for the row. Secure SQL Server uses sensitivity labels to mediate access to data.REMAP="BO--Body"When bulk copying into or from a Secure SQL Server table, an application can choose whether or not to include the table's sensitivity column in the bulk copy operation.REMAP="BO--Body"To include the sensitivity column, an application sets the ID="IN3-782324"BLK_SENSITIVITY_LBL property
BLK_SENSITIVITY_LBLID="IN3-762525"Bulk copyBLK_SENSITIVITY_LBL property
 property to CS_TRUE. BLK_SENSITIVITY_LBL has a default value of CS_FALSE, which means that, by default, the sensitivity column is not included.ID="IN3-742726"Sensitivity columnbcpin_labels_role roleREMAP="BO--Body"Users copying into the sensitivity column must have the ID="IN3-722927"bcpin_labels_role role
MOREINFO="NONE"bcpin_labels_roleID="IN3-703128"Secure SQL Serverbcpin_labels_role role
 activated on Secure SQL Server. If a user does not have this role, the bulk copy operation will fail.ID="IN3-703129"Bulk copyserver-side bulk copy routinesRENDERAS="SECT1"Server-Side Bulk Copy RoutinesREMAP="BO--Body"Open Server 10.0 introduces functionality for processing requests to bulk copy data into a database. Only Open Server applications acting as gateways may utilize the bulk copy routines; an application would never call Server-Library bulk routines without utilizing the complementary Open Client routines.ID="IN3-703130"Bulk copyexamining each row of a bulk copy operationREMAP="BO--Body"The new bulk copy functionality allows Open Server applications to examine each row of a bulk copy operation. This permits an Open Server application to discard certain rows while keeping others, send all rows to the server, or route bulk copy requests to multiple SQL Servers based on the row content, as the diagram below outlines.FLOAT="0"FORMAT="UNKNOWN" FILEREF="fig3_3.xwd"Server-Library does not provide functionality for bulk copying from a database. ID="IN3-703131"Bulk copytypes of bulk requestsID="IN3-703132"Bulk copywritetext requestID="IN3-703133"Bulk copybulk copy requestID="IN3-703134"Text and image datasending a text or image streamREMAP="BO--Body"A client may issue two types of bulk requests, "writetext" or bulk copy. In the first case, the client simply wishes to send a text or image stream, and in the second it is actually initiating a bulk copy request. ID="IN3-703135"Bulk copyprocessing requests using event handlers
ID="IN3-683336"Event handlersSRV_LANGUAGE
ID="IN3-663537"Event handlersSRV_BULKREMAP="BO--Body"An Open Server application processes either of these requests using two event handlers: ID="IN3-643738"SRV_LANGUAGE event handler
SRV_LANGUAGE and ID="IN3-623939"SRV_BULK event handler
SRV_BULK. Inside the SRV_LANGUAGE event handler, it determines which kind of bulk request the client issued and records this information internally. In addition, if the request is for bulk copy, the application allocates and initializes a bulk descriptor structure. Inside the SRV_BULK handler, the application retrieves the request type and then processes the data accordingly.ID="IN3-604140"SRV_LANGUAGE event handlerwhat it should doRENDERAS="SECT2"Inside the SRV_LANGUAGE handlerREMAP="BO--Body"A gateway application which anticipates receiving either type of bulk request must code its SRV_LANGUAGE event handler to parse for the phrase "writetext bulk" or "insert bulk". The first indicates that the client will be issuing a stream of text or image bytes. The second indicates a bulk copy request. REMAP="BO--Body"If the handler detects "writetext bulk", the full string should look like this:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"writetext bulk <dbname>.<tblname>.<colname> <textptr> [timestamp=<timestamp>] [with log] REMAP="BO--Body"where the timestamp and logging indicator are optional.REMAP="BO--Body"The handler should:NUMERATION="ARABIC" REMAP="S1--StepOne" CONTINUATION="RESTARTS" INHERITNUM="IGNORE"Record the bulk type internally by calling MOREINFO="NONE"srv_thread_props with cmd set to CS_SET, property set to SRV_T_BULKTYPE, and bufp pointing to a value of SRV_TEXTLOAD or SRV_IMAGELOAD.Continue parsing to extract the object name, which is generally of the form <dbname>.<tblname>.<colname>. This name can then be stored in the name and namelen fields of a CS_IODESC structure, which can later be used in the SRV_BULK event handler as an argument to MOREINFO="NONE"ct_data_info, if the data stream is being passed on to a server in a gateway application.Continue parsing to extract the text pointer, which will appear as a large hexadecimal number. Once converted from a character string to an actual CS_BINARY value, the text pointer and its length may be stored in the textptr and textptrlen fields of the CS_IODESC structure.Continue parsing to extract the timestamp, which, if present, will appear as "timestamp = <large hexadecimal number>". Once converted from a character string to an actual CS_BINARY value, the timestamp and its length may be stored in the timestamp and timestamplen fields of the CS_IODESC structure.Finally, parse to extract the logging indicator, which, if present, will appear as "with log". If this indicator is present, the log_on_update field of the CS_IODESC structure should be set to CS_TRUE.REMAP="BO--Body"If the handler detects "insert bulk", the full string should look like:REMAP="CO--ComputerOutput" FORMAT="LINESPECIFIC"insert bulk <tablename> [with nodescribe]REMAP="BO--Body"where "with nodescribe" is optional.REMAP="BO--Body"The handler should:NUMERATION="ARABIC" REMAP="S1--StepOne" CONTINUATION="RESTARTS" INHERITNUM="IGNORE"Record the bulk type internally by calling MOREINFO="NONE"srv_thread_props with cmd set to CS_SET, property set to SRV_T_BULKTYPE, and bufp pointing to a value of SRV_BULKLOAD.Continue parsing to extract the table name, which is an argument to the MOREINFO="NONE"blk_init routine.Allocate a bulk descriptor structure, CS_BLKDESC, with a call to MOREINFO="NONE"blk_alloc.Initialize the client half of the exchange with a call to MOREINFO="NONE"blk_init.If "with nodescribe" is specified, it means that this data is part of a batch, and the table into which the bulk data will be loaded has already been described. The application need not call MOREINFO="NONE"blk_srvinit a second time.REMAP="UN--Under"If "with nodescribe" is not specified, initialize the server half of the exchange with a call to MOREINFO="NONE"blk_srvinit.ID="IN3-584341"SRV_BULK event handlerwhat it should doRENDERAS="SECT2"Inside the SRV_BULK Event HandlerREMAP="BO--Body"Inside the SRV_BULK event handler, the application must respond to the bulk request that triggered the handler. However, its response depends on which type of bulk request the client issued. The application retrieves the request type by calling MOREINFO="NONE"srv_thread_props with cmd set to CS_GET and property set to SRV_T_BULKTYPE. ID="IN3-564542"Bulk copyrequest types:SRV_TEXTLOAD
ID="IN3-544743"Bulk copyrequest types:SRV_IMAGELOADREMAP="BO--Body"If the request type is ID="IN3-524944"SRV_TEXTLOAD request type
SRV_TEXTLOAD or ID="IN3-505145"SRV_IMAGELOAD request type
SRV_IMAGELOAD, the application reads the text or image data from the client in chunks, using the ID="IN3-485346"srv_text_info
MOREINFO="NONE"srv_text_info and ID="IN3-465547"srv_get_text
MOREINFO="NONE"srv_get_text routines. For details, see the MOREINFO="NONE"Text and Image topics page in Chapter 2 of the Open Server Server-Library/C Reference Manual.REMAP="BO--Body"If the request type is SRV_BULKLOAD, the application processes the bulk copy rows using a combination of client-side and server-side routines, as follows:NUMERATION="ARABIC" REMAP="S1--StepOne" CONTINUATION="RESTARTS" INHERITNUM="IGNORE"Call MOREINFO="NONE"blk_rowalloc to allocate a CS_BLK_ROW structure to hold the formatted bulk copy rows. Server-Library will place formatted bulk rows into this space as they come over from the client portion of the gateway.Call MOREINFO="NONE"blk_getrow to retrieve the formatted row from the client. This call retrieves all column data except that of type text, image, sensitivity, or boundary. The gateway can process these later. If the row contains text, image, sensitivity, or boundary data, MOREINFO="NONE"blk_getrow will return CS_BLK_HASTEXT. Otherwise, it will return CS_SUCCEED. If there are no more rows, the bulk copy is complete and MOREINFO="NONE"blk_getrow returns CS_END_DATA.If the gateway wishes to route rows to particular remote servers based on the row content, it can call MOREINFO="NONE"blk_colval to examine the value of each column in the bulk row.Call MOREINFO="NONE"blk_sendrow to send the formatted rows to the remote server. If an incoming bulk row contains text, image, sensitivity, or boundary data, the server portion of the gateway calls MOREINFO="NONE"blk_gettext to retrieve the row's text, image, sensitivity, or boundary portion. The client portion calls MOREINFO="NONE"blk_sendtext to send it on to the remote server.Call MOREINFO="NONE"blk_rowdrop to de-allocate the CS_BLK_ROW structure allocated by MOREINFO="NONE"blk_rowalloc.Issue the client call MOREINFO="NONE"blk_done to indicate that the batch or bulk copy operation is complete.Call MOREINFO="NONE"blk_drop to de-allocate the bulk descriptor structure.RENDERAS="SECT2"ExampleID="IN3-465548"Bulk copyexample programREMAP="BO--Body"The online sample ID="IN3-445749"ctosdemo.c example program
ID="IN3-425950"Example programsctosdemo.c
ctosdemo.cID="IN3-406151"Bulk copyctosdemo.c example program
 includes code to process bulk copy requests. NUMBER="4" ID="XA73052"Bulk Copy RoutinesREMAP="BO--Body"This chapter contains a manual page for each bulk copy routine.ID="X83093"blk_allocID="IN43A-9573"AllocatingAllocatinga CS_BLKDESC structureCS_BLKDESC structure
ID="IN43A-9394"CS_BLKDESC structureallocating
Allocate a CS_BLKDESCID="IN43-91115"StructuresCS_BLKDESC:allocating
ID="IN43-91116"Bulk descriptor structureallocating
 structure.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE blk_alloc(connection, version, blk_pointer) CS_CONNECTION    *connection;CS_INT           version;CS_BLKDESC       **blk_pointer;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"This connection must not have any pending results.version - The version of bulk copy behavior that the application expects. During bulk copy initialization, version's value is checked for compatibility with Client-Library's version level.REMAP="UN--Under"Currently, BLK_VERSION_100 is the only value that is legal for version.blk_pointer - The address of a pointer variable. MOREINFO="NONE"blk_alloc sets *blk_pointer to the address of a newly-allocated CS_BLKDESC structure.REMAP="UN--Under"In case of error, MOREINFO="NONE"blk_alloc sets *blk_pointer to NULL. ReturnsTOCENTRY="1"LBL="Table 4-1: "Return values (MOREINFO="NONE"blk_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="IN43-891310"blk_allocreason for failureREMAP="BO--Body"The most common reason for a MOREINFO="NONE"blk_alloc failure is a lack of adequate memory.CommentsMARK="BULL" REMAP="BU--Bullet"A CS_BLKDESC structure, also called a "bulk descriptor structure," contains information about a particular bulk copy operation.ID="IN43-871512"blk_allocwhat to do before callingBefore calling MOREINFO="NONE"blk_alloc, an application must call the Client-Library routines MOREINFO="NONE"ct_con_alloc and MOREINFO="NONE"ct_connect to allocate a CS_CONNECTION structure and open the connection.MOREINFO="NONE"blk_alloc must be the first routine called in a bulk copy operation.To de-allocate a ID="IN43-851713"CS_BLKDESC structurede-allocating
CS_BLKDESCID="IN43-831914"StructuresCS_BLKDESC:de-allocating
 structure, an application can call MOREINFO="NONE"blk_drop.ID="IN43-812115"blk_alloccode exampleExampleREMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/*** BulkCopyIn()** Ex_tabname is globally defined.*/CS_STATIC CS_RETCODE BulkCopyIn(connection)CS_CONNECTION   *connection;{     CS_BLKDESC     *blkdesc;     CS_DATAFMT     datafmt;     /* variable descriptions */     Blk_Data       *dptr;       /* data for transfer */     CS_INT         datalen[5];  /* variable data length */     CS_INT         len;     CS_INT         numrows;      /*     ** Ready to start the bulk copy in now that all the     ** connections have been made and have a table name.     ** Start by getting the bulk descriptor and     ** initializing.     */     if (blk_alloc(connection, BLK_VERSION_100, &blkdesc)           != CS_SUCCEED)     {           ex_error("BulkCopyIn: blk_alloc() failed");           return CS_FAIL;} if (blk_init(blkdesc, CS_BLK_IN,           Ex_tabname, strlen(Ex_tabname)) == CS_FAIL){           ex_error("BulkCopyIn: blk_init() failed");           return CS_FAIL;}/*** Bind the variables to the columns and send the rows,** and then clean up.*/...CODE DELETED..... return CS_SUCCEED;}See AlsoREMAP="BO--Body"LINKEND="X82561"blk_drop
MOREINFO="NONE", LINKEND="X31050"blk_init
MOREINFO="NONE", LINKEND="X20297" BOOK="ref"ct_con_alloc
MOREINFO="NONE", LINKEND="X31502" BOOK="ref"ct_connect
ID="IN43-782418"blk_alloc
MOREINFO="NONE"   ID="X80356"blk_bindID="IN44-752819"blk_bind
ID="IN44-733020"BindingSee Also Bulk binding
ID="IN44-733022"Bindingbinding a program variable and a database column
ID="IN44-733023"Bulk bindingbinding a program variable and a database column
ID="IN44-733024"Program variablebinding with a database column
ID="IN44-733025"Variablebinding a program variable and database column
ID="IN44-733026"Columnbinding a program variable and database column
Bind a program variable and a database column.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE blk_bind(blkdesc, colnum, datafmt, buffer,               datalen, indicator) CS_BLKDESC     *blkdesc;CS_INT         colnum;CS_DATAFMT     *datafmt;CS_VOID        *buffer;CS_INT         *datalen;CS_SMALLINT    *indicator;ParametersREMAP="RI--RefIndent"blkdesc - A pointer to the CS_BLKDESC which is serving as a control block for the bulk copy operation. MOREINFO="NONE"blk_alloc allocates a CS_BLKDESC structure.colnum - The number of the column to bind to the program variable.REMAP="UN--Under"The first column in a table is column number 1, the second number 2, and so forth.datafmt ID="IN44-693429"CS_DATAFMT structurefields used by blk_bind
- A pointer to the CS_DATAFMT structure that describes the program variable to bind to the column.REMAP="UN--Under"The chart below lists the fields in *datafmt that are used by MOREINFO="NONE"blk_bind, and contains general information about the fields. MOREINFO="NONE"blk_bind ignores fields that it does not use:TOCENTRY="1"LBL="Table 4-2: "Fields in the CS_DATAFMT structure (MOREINFO="NONE"blk_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"Always.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A type constant (CS_xxx_TYPE) representing the datatype of the 
program variable.

All type constants listed on the MOREINFO="NONE"Types topics page in the  Open 
Client Client-Library Reference Manual are valid. 

Open Client user-defined types are not valid.
MOREINFO="NONE"
blk_bind supports a wide range of type conversions, so datatype 
can be different from the column's type. For instance, by 
specifying a variable type of CS_FLOAT_TYPE, a money column 
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_will_convert.

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"formatCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"When binding to 
character- or binary-
type destination 
variables on copies 
out from the 
database; 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 non-
fixed-length variables 
for copies out from 
the database.

When binding fixed-
length variables, 
maxlength is ignored.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The maximum length of the *buffer program variable.

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

For a bulk copy into the database, maxlength is the maximum 
length of the data that will be copied from the *buffer program 
variable.

For a bulk copy out from the database, maxlength is the length of 
the *buffer program variable.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"scale COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Only when binding 
to numeric or 
decimal variables.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The scale of the program 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"precisionCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Only when binding 
numeric or decimal 
destinations.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The precision of the program 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"Always.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"count is the number of rows to transfer per MOREINFO="NONE"blk_rowxfer call. If count 
is greater than 1, array binding is considered to be in effect.

On copies out from the database, if count is larger than the number 
of available rows, only the available rows are copied. 

count must have the same value for all columns being transferred, 
with one exception: an application can intermix counts of 0 and 1. 
This is because when count is 0, 1 row is transferred.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"If supplied, locale is 
used. Otherwise, 
default localization 
applies.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to a CS_LOCALE structure containing locale 
information for the *buffer program variable.buffer - The address of the program variable which MOREINFO="NONE"blk_bind binds to the column specified by colnum.REMAP="UN--Under"For bulk copies in, *buffer is the program variable from which MOREINFO="NONE"blk_rowxfer copies the data.REMAP="UN--Under"For bulk copies out, *buffer is the program variable in which MOREINFO="NONE"blk_rowxfer places the copied data. If datafmtname='rArrow' font='symbol' code='174'  charset='fontspecific'maxlength indicates that *buffer is not large enough to hold the copied data, MOREINFO="NONE"blk_rowxfer truncates the data at row transfer time. If this occurs, Client-Library sets *indicator to the actual length of the available data.REMAP="UN--Under"A NULL buffer indicates that data for the column will be transferred using the MOREINFO="NONE"blk_textxfer routine.datalen - A pointer to the length, in bytes, of the *buffer data.REMAP="UN--Under"For bulk copies in, *datalen represents the actual length of the data contained in the *buffer program variable. An application must set this length before calling MOREINFO="NONE"blk_rowxfer to transfer rows. In case of variable-length data, the length may be different for each row. If the data is fixed-length, pass datalen as CS_UNUSED.REMAP="UN--Under"For bulk copies out, *datalen represents the actual length of the data copied to *buffer. MOREINFO="NONE"blk_rowxfer sets *datalen each time it is called to transfer a row.indicator - The address of an integer variable. At row transfer time, the variable is used to indicate certain conditions about the bulk copy data.REMAP="UN--Under"The following table lists the values that an indicator variable can have: TOCENTRY="1"LBL="Table 4-3: "Values for indicator (MOREINFO="NONE"blk_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 data is NULL.

On bulk copies out, no data is copied to *buffer. 

On bulk copies in, the column's default value, if 
any, is used. If no default value is available, 
MOREINFO="NONE"blk_rowxfer returns CS_FAIL.COLNAME="C1" ALIGN="CENTER" ROTATE="0" MOREROWS="0"0COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The copy was successful. COLNAME="C1" ALIGN="CENTER" ROTATE="0" MOREROWS="0"integer valueCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The actual length of the available data, if the copy 
resulted in truncation. Summary of ParametersID="IN44-693431"Bulk bindingcopying data into a databaseCopies Into the DatabaseTOCENTRY="1"LBL="Table 4-4: "Parameter values for copies into the databaseCOLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="208*"COLNAME="C2" COLWIDTH="91*"COLNAME="C3" COLWIDTH="172*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"When calling MOREINFO="NONE"blk_bind to:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"buffer is:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"*datalen is:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Bind a normal value.COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to a 
program variable.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The length of the data in *buffer.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Indicate that a column value will be 
transferred using MOREINFO="NONE"blk_textxfer.COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The total length of the data that will 
be sent using MOREINFO="NONE"blk_textxfer.

In this case, datafmtname='rArrow' font='symbol' code='174'  charset='fontspecific'maxlength is 
ignored.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Instruct bulk copy to use the column's 
default value. If no default value is available 
for the column, NULL values are inserted.COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"IgnoredCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"0COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Set up array binding.COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to an 
array of program 
variables.COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"A pointer to an array containing the 
lengths of the data in the *buffer 
variables.ID="IN44-693432"Bulk bindingcopying data from a databaseCopies Out From the DatabaseTOCENTRY="1"LBL="Table 4-5: "Parameter values for copies out of the databaseCOLS="3" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="209*"COLNAME="C2" COLWIDTH="86*"COLNAME="C3" COLWIDTH="176*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"When calling MOREINFO="NONE"blk_bind to:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"buffer is:COLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"*datalen is:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Bind a normal value.COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Non-nullCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The length of the *buffer data space.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Indicate that a column value will be 
transferred using MOREINFO="NONE"blk_textxfer.COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NULLCOLNAME="C3" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Ignored.

In this case, datafmtname='rArrow' font='symbol' code='174'  charset='fontspecific'maxlength 
represents the length of the *buffer 
data space.ReturnsTOCENTRY="1"LBL="Table 4-6: "Return values (MOREINFO="NONE"blk_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.
MOREINFO="NONE"
blk_bind returns CS_FAIL if the application has not 
called MOREINFO="NONE"blk_init to initialize the bulk copy operation.CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"blk_bind is a Client-Library bulk copy routine.When copying into a database, an application must call MOREINFO="NONE"blk_bind once for each column in the database table. When copying out, an application need not call MOREINFO="NONE"blk_bind for columns in which it has no interest.ID="IN44-653835"blk_textferusing with blk_bindTo indicate that a column value will be transferred via MOREINFO="NONE"blk_textferID="IN44-614236"blk_bindusing with blk_textfer
, an application calls MOREINFO="NONE"blk_bind with buffer as NULL. A typical application will only use MOREINFO="NONE"blk_textxfer to transfer large text or image values.ID="IN44-574637"blk_bindusing with blk_rowxferAn application can call MOREINFO="NONE"blk_bindID="IN44-535038"blk_rowxferusing with blk_bind
 in between calls to MOREINFO="NONE"blk_rowxfer to reflect changes, if any, in a variable's address or length. If an application calls MOREINFO="NONE"blk_bind multiple times for a single column or variable, only the last binding takes effect.An application can call MOREINFO="NONE"blk_describe to get a CS_DATAFMT description of a particular column.ID="IN44-535039"Bulk bindingcopying data into a databaseBulk Copies Into the DatabaseMARK="BULL" REMAP="BU--Bullet"When copying in, an application can instruct bulk copy to use a column's default value by setting *datalen to 0. If no default value is defined for the column, NULL values are inserted.ID="IN44-535040"Bulk bindingclearing bindingsClearing BindingsMARK="BULL" REMAP="BU--Bullet"To clear a binding, call MOREINFO="NONE"blk_bind with buffer, datafmt, datalen, and indicator as NULL. Otherwise, bindings remain in effect until an application calls MOREINFO="NONE"blk_done with type as CS_BLK_ALL to indicate that the bulk copy operation is complete.To clear all bindings, pass colnum as CS_UNUSED, with buffer, datafmt, datalen, and indicator as NULL. An application typically clears all bindings when it needs to change the count that is being used for array binding. ID="IN44-535041"Array binding
ID="IN44-535042"Bulk bindingarray bindingArray Binding MARK="BULL" REMAP="BU--Bullet"Array binding is the process of binding a column to an array of program variables. At row transfer time, multiple rows' worth of the column are transferred either to or from the array of variables with a single MOREINFO="NONE"blk_rowxfer call. An application indicates array binding by setting datafmname='rArrow' font='symbol' code='174'  charset='fontspecific'count to a value greater than 1.If array binding is in effect, then each of buffer, datalen, and indicator must point to arrays. Each length and indicator variable describes the corresponding data in the buffer array.When array binding, all MOREINFO="NONE"blk_bind calls 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 your first two MOREINFO="NONE"blk_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"blk_rowxfer to transfer a single row.If array binding is in effect, an application cannot use MOREINFO="NONE"blk_textxfer to transfer data.ID="IN44-515243"blk_bindcode exampleExampleREMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/*** BulkCopyIn()** BLKDATA and DATA_END are defined in the bulk copy** example program.*/ CS_STATIC CS_RETCODE BulkCopyIn(connection)CS_CONNECTION   *connection;{     CS_BLKDESC    *blkdesc;     CS_DATAFMT    datafmt;    /* variable descriptions */     Blk_Data      *dptr;      /* data for transfer */     CS_INT        datalen[5]; /* variable data length */     CS_INT        len;     CS_INT        numrows;    /*   ** Ready to start the bulk copy in now that all the   ** connections have been made and have a table name.   ** Start by getting the bulk descriptor initializing.   */   ...CODE DELETED.....      /*   ** Bind the variables to the columns and   ** transfer the data.   */   datafmt.locale = 0;   datafmt.count = 1;   dptr = BLKDATA;   while (dptr->pub_id != DATA_END)   {        datafmt.datatype = CS_INT_TYPE;        datafmt.maxlength = sizeof(CS_INT);        datalen[0] = CS_UNUSED;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"        if (blk_bind(blkdesc, 1, &datafmt, &dptr->pub_id,             &datalen[0], NULL) != CS_SUCCEED)        {            ex_error("BulkCopyIn: blk_bind(1) failed");            return CS_FAIL;        }        datafmt.datatype = CS_CHAR_TYPE;        datafmt.maxlength = MAX_PUBNAME - 1;        datalen[1] = strlen(dptr->pub_name);        if (blk_bind(blkdesc, 2, &datafmt, dptr->pub_name,             &datalen[1], NULL) != CS_SUCCEED)        {            ex_error("BulkCopyIn: blk_bind(2) failed");            return CS_FAIL;        }        datafmt.maxlength = MAX_PUBCITY - 1;        datalen[2] = strlen(dptr->pub_city);        if (blk_bind(blkdesc, 3, &datafmt, dptr->pub_city,          &datalen[2], NULL) != CS_SUCCEED)        {            ex_error("BulkCopyIn: blk_bind(3) failed");            return CS_FAIL;        }        datafmt.maxlength = MAX_PUBST - 1;        datalen[3] = strlen(dptr->pub_st);        if (blk_bind(blkdesc, 4, &datafmt, dptr->pub_st,             &datalen[3], NULL) != CS_SUCCEED)        {            ex_error("BulkCopyIn: blk_bind(4) failed");            return CS_FAIL;        }        datafmt.maxlength = MAX_BIO - 1;        datalen[4] = strlen((char *)dptr->pub_bio);        if (blk_bind(blkdesc, 5, &datafmt, dptr->pub_bio,             &datalen[4], NULL) != CS_SUCCEED)       {           ex_error("BulkCopyIn: blk_bind(5) failed");           return CS_FAIL;       }       if (blk_rowxfer (blkdesc) == CS_FAIL)       {           ex_error("BulkCopyIn: blk_rowxfer() failed");           return CS_FAIL;       }       dptr++;   }      /* Mark the operation complete and then clean up */   ...CODE DELETED.....      return CS_SUCCEED;}See AlsoREMAP="BO--Body"LINKEND="X10539"blk_describe
MOREINFO="NONE", LINKEND="X75704"blk_default
MOREINFO="NONE", LINKEND="X31050"blk_init
ID="IN44-485546"blk_colval ID="X44199"blk_colvalID="IN45-485648"Columngetting the column value from a formatted bulk copy row
ID="IN45-485649"Bulk copygetting the column value from a formatted bulk copy row
ID="IN45-485650"Rowgetting the column value from a formatted bulk copy row
Get the column value from a formatted bulk copy row.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE blk_colval(srvproc, blkdescp, rowp, colnum,              valuep, valuelen, outlenp) SRV_PROC      *srvproc;CS_BLKDESC    *blkdescp;CS_BLK_ROW    *rowp;CS_INT        colnum;CS_VOID       *valuep;CS_INT        valuelen;CS_INT        *outlenp;ParametersREMAP="RI--RefIndent"srvproc - A pointer to the SRV_PROC structure associated with the client sending the bulk copy row. It contains all the information that Server-Library uses to manage communications and data between the Open Server application and the client.blkdescp - A pointer to a CS_BLKDESC structure containing information about bulk copy data. This structure must have been previously allocated with a call to MOREINFO="NONE"blk_alloc and initialized with a call to MOREINFO="NONE"blk_init. This structure is used to interpret incoming formatted bulk copy rows.rowp - A pointer to the formatted bulk copy row read from the client via a prior call to MOREINFO="NONE"blk_getrow.colnum - The column number of the column of interest. Column numbers start at 1. valuep - A pointer to the application buffer in which the column value from the bulk copy row is placed. valuelen - The size, in bytes, of the buffer to which valuep points.outlen - A pointer to the variable which is set to the size, in bytes, of the column data.ReturnsTOCENTRY="1"LBL="Table 4-7: "Return values (MOREINFO="NONE"blk_colval)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"blk_colval is a Server-Library bulk copy routine. After getting the value of a specified column from a formatted bulk copy row, it stores the value in an application buffer.This routine performs no implicit data conversion. Use MOREINFO="NONE"cs_convert to convert the data.In order to examine the column value after a call to MOREINFO="NONE"blk_colval, the application must know the column`s datatype before making the call.ID="IN45-446055"blk_colvalwhen to use blk_gettext insteadAn Open Server application cannot use this routine to retrieve text, image, sensitivity, or boundary columns. Use MOREINFO="NONE"blk_gettext to retrieve such columns.See AlsoREMAP="BO--Body"LINKEND="X95049"blk_getrow
ID="IN45-416357"blk_colval 
, LINKEND="X73052"Bulk CopyID="IN45-386658"blk_defaultID="X75704"blk_defaultID="IN46-386760"Columnretrieving a columnÕ s default value
ID="IN46-386761"Defaultretrieving a columnÕ s default value
Retrieve a column's default value.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE blk_default(blkdesc, colnum, buffer,             buflen, outlen)CS_BLKDESC   *blkdesc;CS_INT       colnum;CS_VOID      *buffer;CS_INT       buflen;CS_INT       *outlen;ParametersREMAP="RI--RefIndent"blkdesc - A pointer to the CS_BLKDESC which is serving as a control block for the bulk copy operation. MOREINFO="NONE"blk_alloc allocates a CS_BLKDESC structure.colnum - The number of the column of interest. The first column in a table is column number 1, the second is number 2, and so forth.buffer - A pointer to the space in which MOREINFO="NONE"blk_default will place the default value.buflen - The length, in bytes, of the *buffer data space. outlen - A pointer to an integer variable. REMAP="UN--Under"If supplied,MOREINFO="NONE" blk_default sets *outlen to the length, in bytes, of the default value.REMAP="UN--Under"If the default value is larger than buflen bytes, an application can use the value of *outlen to determine how many bytes are needed to hold the value.ReturnsTOCENTRY="1"LBL="Table 4-8: "Return values (MOREINFO="NONE"blk_default)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"blk_default returns CS_FAIL if the application has not 
called MOREINFO="NONE"blk_init to initialize the bulk copy operation.CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"blk_default is a Client-Library bulk copy routine.An application can call MOREINFO="NONE"blk_default to find out whether a default value is defined for a particular target column, and, if so, what the default value is.ID="IN46-366966"blk_defaultwhen to callREMAP="UN--Under"This information can be useful for bulk copies into a database, because an application can instruct bulk copy to insert a column's default value into a table by calling MOREINFO="NONE"blk_bind with *datalen as 0. If the column of interest does not have a default value, MOREINFO="NONE"blk_default sets *outlen to CS_NO_DEFAULT and returns CS_SUCCEED.An application can retrieve column defaults during a bulk copy in operation only.ID="IN46-347167"blk_defaultwhen not to callAn application cannot call MOREINFO="NONE"blk_default until MOREINFO="NONE"blk_init(CS_BLK_IN) returns CS_SUCCEED.See AlsoREMAP="BO--Body"LINKEND="X80356"blk_bind
MOREINFO="NONE", LINKEND="X10539"blk_describe
MOREINFO="NONE", LINKEND="X31050"blk_init
ID="IN46-317469"blk_describeID="X10539"blk_describeID="IN47-317571"Descriptionretrieving a columnÕ s description
ID="IN47-317572"Columnretrieving a columnÕ s description
Retrieve a description of a database column.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE blk_describe(blkdesc, colnum, datafmt) CS_BLKDESC        *blkdesc;CS_INT            colnum;CS_DATAFMT        *datafmt;ParametersREMAP="RI--RefIndent"blkdesc - A pointer to the CS_BLKDESC which is serving as a control block for the bulk copy operation. MOREINFO="NONE"blk_alloc allocates a CS_BLKDESC structure.colnum - The number of the column of interest. The first column in a table is column number 1, the second is number 2, and so forth.datafmt - A pointer to a CS_DATAFMT structure. MOREINFO="NONE"blk_describe fills *MOREINFO="NONE"datafmt with a description of the database column referenced by colnum. REMAP="UN--Under"For a bulk copy into the database, MOREINFO="NONE"blk_describeID="IN47-277975"blk_describeCS_DATAFMT fields it uses
 fills in the following fields in the CS_DATAFMT:TOCENTRY="1"LBL="Table 4-9: "Fields in the CS_DATAFMT structure, copies in (MOREINFO="NONE"blk_describe)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="63*"COLNAME="C2" COLWIDTH="297*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Field name:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"blk_describe 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 column, 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"A type constant representing the datatype of the column. All 
type constants listed on the MOREINFO="NONE"Types topics page are valid, with the 
exceptions of CS_VARCHAR_TYPE and 
CS_VARBINARY_TYPE.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.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"scale COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The scale of the column.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"precision COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The precision of the column.REMAP="UN--Under"For a bulk copy out from the database, MOREINFO="NONE"blk_describe fills in the following fields in the CS_DATAFMT:TOCENTRY="1"LBL="Table 4-10: "Fields in the CS_DATAFMT structure, copies out (MOREINFO="NONE"blk_describe)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="63*"COLNAME="C2" COLWIDTH="297*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Field name:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"MOREINFO="NONE"blk_describe 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 column, 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 column. All datatypes listed on the types 
topics page are valid.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.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"scale COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The scale of the column.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"precision COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The precision of the column.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 this column is a "hidden" column 
that has been exposed. For information on hidden columns, see 
"Hidden Keys" on the MOREINFO="NONE"Properties topics page in the Client-Library 
Reference Manual.

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.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, 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.ReturnsTOCENTRY="1"LBL="Table 4-11: "Return values (MOREINFO="NONE"blk_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"blk_describe returns CS_FAIL if colnum does not 
represent a valid result column.CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"blk_describe is a Client-Library bulk copy routine.ID="IN47-258178"blk_describepurposeAn application typically uses a column description in order to help determine compatible program variable types and sizes.See the CS_DATAFMT topics page in the Client-Library Reference Manual for a complete description of the CS_DATAFMT structure.See AlsoREMAP="BO--Body"LINKEND="X75704"blk_default
MOREINFO="NONE", LINKEND="X31050"blk_init
ID="IN47-228480"blk_doneID="X45055"blk_doneID="IN48-228582"Markinga complete bulk copy operation or batch
ID="IN48-228583"Bulk copymarking a complete bulk copy operation or batch
Mark a complete bulk copy operation or a complete bulk copy batch.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE blk_done(blkdesc, type, outrow) CS_BLKDESC      *blkdesc;CS_INT          type;CS_INT          *outrow;ParametersREMAP="RI--RefIndent"blkdesc - A pointer to the CS_BLKDESC which is serving as a control block for the bulk copy operation. MOREINFO="NONE"blk_alloc allocates a CS_BLKDESC structure.type - The type of operation. The following table lists the symbolic values that are legal for type:TOCENTRY="1"LBL="Table 4-12: "Values for type (MOREINFO="NONE"blk_done)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="99*"COLNAME="C2" COLWIDTH="261*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Value of type:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"blk_done:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BLK_ALLCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Marks a complete bulk copy in or bulk copy out 
operation.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BLK_BATCHCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Marks a complete "batch" in a batched bulk copy in 
operation.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BLK_CANCELCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Cancels a bulk copy batch or bulk copy operation.outrow - A pointer to an integer variable. MOREINFO="NONE"blk_done sets *outrow to the number of rows bulk copied to SQL Server since the application's last MOREINFO="NONE"blk_done call.ReturnsTOCENTRY="1"LBL="Table 4-13: "Return values (MOREINFO="NONE"blk_done)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"ReturnsCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"To IndicateVALIGN="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.

Common reasons for failure include an invalid blkdesc 
pointer or an illegal value for type 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.CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"blk_done is both a Client-Library and Server-Library bulk copy routine.Calling MOREINFO="NONE"blk_done with type as CS_BLK_ALL marks the end of a bulk copy operation. Once an application marks the end of a bulk copy operation, it cannot call any bulk copy routines (except for MOREINFO="NONE"blk_drop and MOREINFO="NONE"blk_alloc) until it initializes a new bulk copy operation by calling MOREINFO="NONE"blk_init.Calling MOREINFO="NONE"blk_done with type as CS_BLK_BATCH marks a complete batch in a bulk copy in operation. CS_BLK_BATCH is legal only for bulk copy in operations.Calling MOREINFO="NONE"blk_done with type as CS_BLK_CANCELID="IN48-228588"Bulk copyoperations:canceling
 cancels the current bulk copy operation. Rows transferred since an application's last MOREINFO="NONE"blk_done(CS_BLK_BATCH) call are not saved in the database. Once an application cancels a bulk copy operation, it cannot call any bulk copy routines (except for MOREINFO="NONE"blk_drop and MOREINFO="NONE"blk_alloc) until it initializes a new bulk copy operation by calling MOREINFO="NONE"blk_init.ID="IN48-208789"blk_donebulk copies into a databaseBulk Copies Into the DatabaseMARK="BULL" REMAP="BU--Bullet"When an application bulk copies data into a database, the rows are permanently saved only when the application calls MOREINFO="NONE"blk_done. If an application has large amounts of data to transfer, it can be convenient to "batch" the data into smaller units of recoverability.An application can batch rows by calling MOREINFO="NONE"blk_done with type as CS_BLK_BATCH once every n rows or when there is a lull between periods of data, as in a telemetry application. This causes all rows transferred since the application's last MOREINFO="NONE"blk_done call to be permanently saved.After saving a batch of rows, an application's first call to MOREINFO="NONE"blk_rowxfer implicitly starts the next batch.An application must call MOREINFO="NONE"blk_done with type as CS_BLK_ALL to send its final batch of rows. This call permanently saves the rows, marks the end of the bulk copy operation, and cleans up internal bulk copy data structures.ID="IN48-188990"blk_donebulk copies from a databaseBulk Copies Out From the DatabaseMARK="BULL" REMAP="BU--Bullet"After transferring the last row in a bulk copy out operation, an application must call MOREINFO="NONE"blk_done with type as CS_BLK_ALL to mark the end of the bulk copy operation and clean up internal bulk copy data structures.ID="IN48-169191"blk_donecode exampleExampleREMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/*** BulkCopyIn()*/REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"CS_STATIC CS_RETCODE BulkCopyIn(connection)CS_CONNECTION   *connection;{     CS_BLKDESC   *blkdesc;     CS_DATAFMT   datafmt;     /* variable descriptions */     Blk_Data     *dptr;       /* data for transfer */     CS_INT       datalen[5];  /* variable data length */     CS_INT       len;     CS_INT       numrows;      /*     ** Ready to start the bulk copy in now that all the     ** connections have been made and have a table name.     ** Start by getting the bulk descriptor initializing.     */     ...CODE DELETED.....      /*     ** Now to bind the variables to the columns and     ** transfer the data     */     ...CODE DELETED.....      /* ALL the rows sent so clear up */     if (blk_done(blkdesc, CS_BLK_ALL, &numrows) == CS_FAIL)     {        ex_error("BulkCopyIn: blk_done() failed");        return CS_FAIL;     }     if (blk_drop(blkdesc) == CS_FAIL)     {        ex_error("BulkCopyIn: blk_drop() failed");        return CS_FAIL;     }      return CS_SUCCEED;}See AlsoREMAP="BO--Body"LINKEND="X31050"blk_init
MOREINFO="NONE", LINKEND="X79318"blk_rowxfer
ID="IN48-139494"blk_dropID="X82561"blk_dropID="IN49-119796"De-allocatingDe-allocatinga CS_BLKDESC structureCS_BLKDESC structure
ID="IN49-99997"CS_BLKDESC structurede-allocating
De-allocate a CS_BLKDESCID="IN49-710198"StructuresCS_BLKDESC:de-allocating
ID="IN49-710199"Bulk copydescriptor structure:de-allocating
 structure. REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE blk_drop(blkdesc) CS_BLKDESC      *blkdesc;ParametersREMAP="RI--RefIndent"blkdesc - A pointer to a CS_BLKDESC previously allocated viaMOREINFO="NONE" blk_alloc.ReturnsTOCENTRY="1"LBL="Table 4-14: "Return values (MOREINFO="NONE"blk_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.CommentsMARK="BULL" REMAP="BU--Bullet"A CS_BLKDESC structure, also called a "bulk descriptor structure," contains information about a particular bulk copy operation.Once a bulk descriptor structure has been de-allocated, it cannot be re-used. To allocate a new CS_BLKDESC, an application can call MOREINFO="NONE"blk_alloc.ID="IN49-5103104"blk_dropwhen to call
MOREINFO="NONE"blk_drop is typically called after MOREINFO="NONE"blk_done. It must be the last routine called in a bulk copy operation.ID="IN49-3105105"blk_dropcode exampleExampleREMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/*** BulkCopyIn()*/ CS_STATIC CS_RETCODE BulkCopyIn(connection)CS_CONNECTION   *connection;{ CS_BLKDESC   *blkdesc;CS_DATAFMT   datafmt;      /* variable descriptions */Blk_Data     *dptr;        /* data for transfer */CS_INT       datalen[5];   /* variable data length */CS_INT       len;CS_INT       numrows; /*** Ready to start the bulk copy in now that all the** connections have been made and have a table name.** Start by getting the bulk descriptor initializing.*/...CODE DELETED..... /*** Now to bind the variables to the columns and** transfer the data*/...CODE DELETED..... /* ALL the rows sent so clear up */if (blk_done(blkdesc, CS_BLK_ALL, &numrows) == CS_FAIL){     ex_error("BulkCopyIn: blk_done() failed");     return CS_FAIL;}if (blk_drop(blkdesc) == CS_FAIL){     ex_error("BulkCopyIn: blk_drop() failed");     return CS_FAIL;} return CS_SUCCEED;}See AlsoREMAP="BO--Body"LINKEND="X83093"blk_alloc
MOREINFO="NONE", LINKEND="X45055"blk_done
ID="IN49-0108108"blk_getrow ID="X95049"blk_getrowID="IN50-0109110"Bulk copyretrieving and storing a formatted bulk copy row
ID="IN50-0109111"Rowretrieving and storing a formatted bulk copy row
Retrieve and store a formatted bulk copy row. REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE blk_getrow(srvproc, blkdescp, rowp)REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC" SRV_PROC        *srvproc;
CS_BLKDESC      *blkdescp;
CS_BLK_ROW      *rowp;ParametersREMAP="RI--RefIndent"srvproc - A pointer to the SRV_PROC structure associated with the client sending the bulk copy row. It contains all the information that Server-Library uses to manage communications and data between the Open Server and the client.blkdescp - A pointer to a CS_BLKDESC structure containing information about bulk copy data. This structure must have been previously allocated with a call to MOREINFO="NONE"blk_alloc and initialized with a call to MOREINFO="NONE"blk_init. This structure is used to interpret incoming formatted bulk copy rows.rowp - A pointer to a CS_BLK_ROW structure containing space for a formatted bulk copy row.ReturnsTOCENTRY="1"LBL="Table 4-15: "Return values (MOREINFO="NONE"blk_getrow)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_END_DATACOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"There are no more rows.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BLK_HAS_TEXTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The row contains some text, image, sensitivity, or 
boundary data. Use MOREINFO="NONE"blk_gettext to retrieve the text, 
image, sensitivity, or boundary data. Note that a return 
value of CS_BLK_HAS_TEXT implies a successful 
return, as in CS_SUCCEED.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"blk_getrowID="IN50--2111116"Gateway applicationsGateway applicationsand blk_getrowblk_getrow
 is a Server-Library bulk copy routine that is useful in gateway applications.This routine copies the incoming formatted bulk copy row into the ID="IN50--4113117"CS_BLK_ROW structure
CS_BLK_ROWID="IN50--6115118"StructuresCS_BLK_ROW
 structure to which rowp points. The row data is saved only until the next call to MOREINFO="NONE"blk_getrow. The application must have previously allocated the space for the row using MOREINFO="NONE"blk_rowalloc.Once a row has been received via MOREINFO="NONE"blk_getrow, the application may examine the contents of any fields (other than text, image, sensitivity, or boundary fields) using MOREINFO="NONE"blk_colval. ID="IN50--10119119"blk_getrowdifference from blk_gettextUse MOREINFO="NONE"blk_gettext to retrieve text, image, sensitivity, and boundary fields.A bulk copy row may subsequently be sent to another server using the MOREINFO="NONE"blk_sendrow routine.An application must read all incoming rows with MOREINFO="NONE"blk_getrow, until there are no more rows.ID="IN50--12121120"blk_getrowwhat to do nextOnce MOREINFO="NONE"blk_getrow finds no more data and returns CS_END_DATA, the application must drop the space allocated for the row, using MOREINFO="NONE"blk_rowdrop.See AlsoREMAP="BO--Body"LINKEND="X44199"blk_colval
MOREINFO="NONE", LINKEND="X80979"blk_gettext
ID="IN50--15124122"blk_getrow MOREINFO="NONE", LINKEND="X73052"Bulk CopyID="IN50--18127123"blk_gettext ID="X80979"blk_gettextID="IN51--18128125"Text and image dataretrieving the text or image portion of an incoming bulk copy formatted row
ID="IN51--18128126"Sensitivity columnretrieving the sensitivity portion of an incoming bulk copy formatted row
ID="IN51--18128127"Boundaryretrieving the boundary portion of an incoming bulk copy formatted row
ID="IN51--18128128"Bulk copyretrieving the text, image, sensitivity, or boundary portion of an incoming bulk copy formatted row
ID="IN51--18128129"Rowretrieving the text, image, sensitivity, or boundary portion of an incoming bulk copy formatted row
Retrieve the text, image, sensitivity, or boundary portion of an incoming bulk copy formatted row. REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE blk_gettext(srvproc,blkdescp, rowp, bufp,
bufsize, outlenp)REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC" SRV_PROC      *srvproc;
CS_BLKDESC    *blkdescp;
CS_BLK_ROW    *rowp;
CS_BYTE       *bufp;
CS_INT        bufsize;
CS_INT        *outlenp;ParametersREMAP="RI--RefIndent"srvproc - A pointer to the SRV_PROC structure associated with the client sending the bulk copy row. It contains all the information that Server-Library uses to manage communications and data between the Open Server application and the client.blkdescp - A pointer to a CS_BLKDESC structure containing information about bulk copy data. This structure must have been previously allocated with a call to MOREINFO="NONE"blk_alloc and initialized with a call to MOREINFO="NONE"blk_init. This structure is used to interpret incoming formatted bulk copy rows.rowp - A pointer to the formatted bulk copy row read from the client via a prior call to MOREINFO="NONE"blk_getrow.bufp - A pointer to the application buffer in which Server-Library places the text, image, sensitivity, or boundary data. bufsize - The size, in bytes, of buf. outlenp - A pointer to a CS_INT variable, which is set to the number of bytes actually read by MOREINFO="NONE"blk_gettext. It may be less than bufsize. To determine whether all of the text, image, sensitivity, or boundary part of the row has been read, check for a return code of CS_END_DATA. An outlenp value which is less than bufsize does not necessarily mean the end of a row. For example, it could indicate the end of a text, image, sensitivity, or boundary column that is not the last column in the row.ReturnsTOCENTRY="1"LBL="Table 4-16: "Return values (MOREINFO="NONE"blk_gettext)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_END_DATACOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"There are no more text, image, sensitivity, or boundary 
fields for the current incoming bulk copy row. Call 
MOREINFO="NONE"blk_getrow to get the next bulk copy row.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"blk_gettextID="IN51--20130134"Gateway applicationsGateway applicationsand blk_gettextblk_gettext
 is a Server-Library bulk copy routine that is useful in gateway applications.ID="IN51--26136135"blk_gettextusing with blk_getrow and blk_colvalThis routine is used with MOREINFO="NONE"blk_getrow and MOREINFO="NONE"blk_colval to receive formatted bulk copy rows and route them to SQL Servers. This routine retrieves the text, image, sensitivity, or boundary portions of the row. Bulk copy rows are formatted so that all text, image, sensitivity, and boundary fields occur at the end of the row, after all the other types of fields. To route a row to a SQL Server, first call MOREINFO="NONE"blk_getrow to retrieve all the parts of the row containing other types of fields. Then, call MOREINFO="NONE"blk_colval to retrieve and store portions of the row containing other types of fields. Decide where this data goes and then send it to the remote server using MOREINFO="NONE"blk_sendrow. Finally, call MOREINFO="NONE"blk_gettext to copy text, image, sensitivity, or boundary data into an application buffer and then call MOREINFO="NONE"blk_sendtext to send this information to the remote server.If an incoming bulk copy row has any text, image, sensitivity, or boundary fields, MOREINFO="NONE"blk_getrow returns CS_BLK_HAS_TEXT.It is not an error to call MOREINFO="NONE"blk_gettext if the row contains no text, image, sensitivity, or boundary fields. The routine simply returns CS_END_DATA.ID="IN51--28138136"blk_gettextwhen to callThis routine must be called after MOREINFO="NONE"blk_getrow. Also, it must be called until it returns CS_END_DATA, in order to fully read in a bulk copy row.Before rows can be sent to a server, the gateway application must have set up the bulk copy operation with a call to MOREINFO="NONE"blk_init.It is critical that the table for which the bulk copy was initialized and the table into which the client is bulk copying be the same table.See AlsoREMAP="BO--Body"LINKEND="X65669"blk_sendtext
MOREINFO="NONE", LINKEND="X44199"blk_colval
MOREINFO="NONE", LINKEND="X95049"blk_getrow
MOREINFO="NONE", LINKEND="X73052"Bulk CopyID="X31050"blk_initID="IN52--34145141"Bulk copyoperations:initiating
ID="IN52--34145142"Operationinitiating a bulk copy operation
Initiate a bulk copy operation.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE blk_init(blkdesc, direction, tablename,              tnamelen) CS_BLKDESC    *blkdesc;CS_INT        direction;CS_CHAR       *tablename;CS_INT        tnamelen;ParametersREMAP="RI--RefIndent"blkdesc - A pointer to the CS_BLKDESC controlling the bulk copy operation. An application can allocate a CS_BLKDESC by callingMOREINFO="NONE" blk_alloc.direction - The direction of the bulk copy. The following table lists the symbolic values that are legal for direction:TOCENTRY="1"LBL="Table 4-17: "Values for direction (MOREINFO="NONE"blk_init)COLS="2" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="99*"COLNAME="C2" COLWIDTH="261*"VALIGN="BOTTOM"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Value of direction:COLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"blk_init:VALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BLK_INCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Initializes a bulk copy operation into the database.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_BLK_OUTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Initializes a bulk copy operation out from the database.tablename - A pointer to the name of the table of interest. Any legal server table name is acceptable. tnamelen - The length, in bytes, of *tablename. If *tablename is null-terminated, pass tnamelen as CS_NULLTERM.ReturnsTOCENTRY="1"LBL="Table 4-18: "Return values (MOREINFO="NONE"blk_init)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.

A common cause of failure is specifying a non-existent 
table.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.CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"blk_init is both a Client-Library and Server-Library bulk copy routine.When a bulk copy operation is complete, an application must call MOREINFO="NONE"blk_done with type as CS_BLK_ALL in order to mark the end of the bulk copy operation and clean up internal bulk copy data structures.ID="IN52--36147147"blk_initcode exampleExampleREMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/*** BulkCopyIn()** Ex_tabname is globally defined.*/CS_STATIC CS_RETCODE BulkCopyIn(connection)CS_CONNECTION   *connection;{    CS_BLKDESC*    blkdesc;    CS_DATAFMT     datafmt;     /* variable descriptions */    Blk_Data       *dptr;       /* data for transfer */    CS_INT         datalen[5];  /* variable data length */    CS_INT         len;    CS_INT         numrows;
     /*    ** Ready to start the bulk copy in now that all the     ** connections have been made and have a table name.    ** Start by getting the bulk descriptor and    ** initializing.    */    if (blk_alloc(connection, BLK_VERSION_100, &blkdesc)        != CS_SUCCEED)    {        ex_error("BulkCopyIn: blk_alloc() failed");        return CS_FAIL;    }     if (blk_init(blkdesc, CS_BLK_IN,               Ex_tabname, strlen(Ex_tabname)) == CS_FAIL)    {        ex_error("BulkCopyIn: blk_init() failed");        return CS_FAIL;    }     /*    ** Bind the variables to the columns and send the rows,    ** and then clean up.    */    ...CODE DELETED.....     return CS_SUCCEED;}See AlsoREMAP="BO--Body"LINKEND="X80356"blk_bind
MOREINFO="NONE", LINKEND="X45055"blk_done
MOREINFO="NONE", LINKEND="X79318"blk_rowxferblk_propsID="IN43-9753"Bulk descriptor structuresetting and retrieving properties
ID="IN43D-9754"Structuressetting and retrieving bulk descriptor structure properties
ID="IN43-9755"Propertiessetting and retrieving bulk descriptor structure properties
Set or retrieve bulk descriptor structure properties.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE blk_props(blkdesc, action, property,                 buffer, buflen, outlen) CS_BLKDESC      *blkdesc;CS_INT          action;CS_INT          property;CS_VOID         *buffer;CS_INT          buflen;CS_INT          *outlen;ParametersREMAP="RI--RefIndent"blkdesc - A pointer to a CS_BLKDESC structure. A bulk descriptor structure contains information about a bulk copy operation. MOREINFO="NONE"blk_alloc allocates a bulk descriptor structure.action - One of the following symbolic values:TOCENTRY="1"LBL="Table 4-19: " ID="X64792"Values for action (MOREINFO="NONE"blk_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"blk_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 
default value.property - The symbolic name of the property whose value is being set or retrieved. LINKEND="X64793"Table 4-21: Client/Server bulk descriptor properties
 lists the values that are legal for property.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"blk_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"blk_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. ReturnsTOCENTRY="1"LBL="Table 4-20: "Return values (MOREINFO="NONE"blk_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.CommentsMARK="BULL" REMAP="BU--Bullet"Bulk descriptor properties define aspects of a specific bulk copy operation.ID="IN43-95710"blk_propswhen to callAn application must set bulk copy properties after calling MOREINFO="NONE"blk_alloc to allocate a bulk descriptor structure and before calling MOREINFO="NONE"blk_init to initiate a specific bulk copy operation.An application can use MOREINFO="NONE"blk_props to set or retrieve the following properties:TOCENTRY="1"ID="X64793" LBL="Table 4-21: "Client/Server bulk descriptor propertiesCOLS="5" CHAROFF="50" CHAR="" ALIGN="LEFT"COLNAME="C1" COLWIDTH="130*"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"Applicable 
to?COLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"NotesVALIGN="TOP"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"BLK_IDENTITYCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether a table's 
identity column is 
included in the bulk 
copy operation.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"IN copies 
onlyCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"BLK_SENSITIVITY_
LBLCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Whether a table's 
sensitivity column is 
included in the bulk 
copy operation.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"Both IN 
and OUT 
copiesCOLNAME="C5" ALIGN="LEFT" ROTATE="0" MOREROWS="0"Secure SQL 
Server onlyAbout the PropertiesMARK="BULL" REMAP="BU--Bullet"BLK_IDENTITY MARK="DASH" REMAP="BS--BulletSub"BLK_IDENTITYID="IN43-95712"Identity columnwhether included in a bulk copy operation
ID="IN43-95713"Bulk copyidentity column
 determines whether a table's identity column is included in a bulk copy in operation. BLK_IDENTITY does not affect bulk copy out operations.If BLK_IDENTITY is CS_TRUE, the application must supply data for the identity column.If BLK_IDENTITY is CS_FALSE, the application does not need to supply data for the identity column. In this case, the server supplies a default value for the column.BLK_IDENTITY works by setting MOREINFO="NONE"identity_insert MOREINFO="NONE"on for the database table of interest. This allows values to be inserted into the identity column. When the bulk copy operation is finished, the MOREINFO="NONE"identity_insert option for the table is reset to MOREINFO="NONE"off. For more information on MOREINFO="NONE"identity_insert, see the SQL Server Reference Manual.BLK_SENSITIVITY_LBLMARK="DASH" REMAP="BS--BulletSub"BLK_SENSITIVITY_LBLID="IN43-95714"Sensitivity labelwhether sensitivity column data is included in a bulk copy operation
 determines whether or not data for the sensitivityID="IN43-95715"Bulk copysensitivity column data
 column is included in a bulk copy operation. By default, sensitivity column data is not included.BLK_SENSITIVITY_LBL affects both bulk copy in and bulk copy out operations.If BLK_SENSITIVITY_LBL is CS_TRUE, the application must supply data for the sensitivity column on bulk copy in operations andwill receive data from the sensitivity column on bulk copy out operations.If BLK_SENSITIVITY_LBL is CS_FALSE, the application does not need to supply data for the sensitivity column on bulk copy in operations and will not receive data from the sensitivity column on bulk copy out operations.ID="IN43-93916"Sensitivity labelBLK_SENSITIVITY_LBL property
BLK_SENSITIVITY_LBLID="IN43-911117"Secure SQL ServerBLK_SENSITIVITY_LBL property
 is applicable to Secure SQL Server copies only. MOREINFO="NONE"blk_init fails if BLK_SENSITIVITY_LBL is CS_TRUE and a bulk copy operation is attempted against a standard SQL Server.Users copying into the sensitivity column must have the MOREINFO="NONE"bcpin_labels_role role activated on Secure SQL Server. MOREINFO="NONE"blk_init fails if the user does not have the MOREINFO="NONE"bcpin_labels_role.For more information on Secure SQL Server, see your Secure SQL Server documentation.See AlsoREMAP="BO--Body"LINKEND="X83093"blk_alloc
MOREINFO="NONE", LINKEND="X31050"blk_init
ID="IN43-881419"blk_rowalloc ID="X18194"blk_rowallocID="IN44-881521"Allocatingspace for a formatted bulk copy row
ID="IN44-881522"Bulk copyallocating space for a formatted bulk copy row
ID="IN44-881523"Rowallocating space for a formatted bulk copy row
Allocate space for a formatted bulk copy row. REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE blk_rowalloc(srvproc, row) SRV_PROC      *srvproc;CS_BLK_ROW    **row;ParametersREMAP="RI--RefIndent"srvproc - A pointer to the SRV_PROC structure associated with the client sending formatted bulk copy rows. It contains all the information that Server-Library uses to manage communications and data between the Open Server and the client.row - A pointer to a pointer to a formatted bulk copy row. The address of the allocated space for the row is returned here.ReturnsTOCENTRY="1"LBL="Table 4-22: "Return values (MOREINFO="NONE"blk_rowalloc)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.CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"blk_rowallocID="IN44-861728"Gateway applicationsGateway applicationsand blk_rowallocblk_rowalloc
 is a Server-Library bulk copy routine that is useful in gateway applications.This routine allocates space in which MOREINFO="NONE"blk_getrow will place the formatted bulk copy row.The row space is used by all calls to MOREINFO="NONE"blk_getrow.When all rows have been retrieved and sent to the remote server, call MOREINFO="NONE"blk_rowdrop to drop the space allocated for the row.See AlsoREMAP="BO--Body"LINKEND="X95049"blk_getrow
MOREINFO="NONE", LINKEND="X29766"blk_rowdrop
ID="IN44-832030"blk_rowalloc 
MOREINFO="NONE", LINKEND="X73052"Bulk CopyID="IN44-802331"blk_rowdrop ID="X29766"blk_rowdropID="IN45-802433"De-allocatingspace for a formatted bulk copy row
ID="IN45-802434"Bulk copyfreeing space for a formatted bulk copy row
ID="IN45-802435"Rowfreeing space for a formatted bulk copy row
Free space previously allocated for a formatted bulk copy row. REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE blk_rowdrop(srvproc, row) SRV_PROC       *srvproc;CS_BLK_ROW     *row;ParametersREMAP="RI--RefIndent"srvproc - A pointer to the SRV_PROC structure associated with the client sending formatted bulk copy rows. It contains all the information that Server-Library uses to manage communications and data between the Open Server application and the client.row - A pointer to space for a formatted bulk copy row. This is the address of the allocated space to be freed.ReturnsTOCENTRY="1"LBL="Table 4-23: "Return values (MOREINFO="NONE"blk_rowdrop)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.CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"blk_rowdropID="IN45-782640"Gateway applicationsGateway applicationsand blk_rowdropblk_rowdrop
 is a Server-Library bulk copy routine that is useful in gateway applications.This routine frees space previously allocated by MOREINFO="NONE"blk_rowalloc. ID="IN45-762841"blk_rowdropwhen to callIt must be called after all formatted bulk copy rows have been retrieved and sent to the remote server.See AlsoREMAP="BO--Body"LINKEND="X95049"blk_getrow
MOREINFO="NONE", LINKEND="X18194"blk_rowalloc
ID="IN45-733143"blk_rowdrop 
MOREINFO="NONE", LINKEND="X73052"Bulk CopyID="IN45-703444"blk_rowxferID="X79318"blk_rowxferID="IN46-703546"Transferringrows during a bulk copy operation
ID="IN46-703547"Rowtransferring one or more rows during a bulk copy operation
ID="IN46-703548"Bulk copytransferring one or more rows
Transfer one or more rows during a bulk copy operation.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE blk_rowxfer(blkdesc) CS_BLKDESC       *blkdesc;ParametersREMAP="RI--RefIndent"blkdesc - A pointer to the CS_BLKDESC which is serving as a control block for the bulk copy operation. MOREINFO="NONE"blk_alloc allocates a CS_BLKDESC structure.ReturnsTOCENTRY="1"LBL="Table 4-24: "Return values (MOREINFO="NONE"blk_rowxfer)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_BLK_HAS_TEXTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The row contains one or more columns which have 
been marked for transfer via MOREINFO="NONE"blk_textxfer.

The application must call blk_textxfer to transfer data 
for these columns row before calling MOREINFO="NONE"blk_rowxfer to 
transfer the next row.COLNAME="C1" ALIGN="LEFT" ROTATE="0" MOREROWS="0"CS_END_DATACOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"When copying data out from a database, MOREINFO="NONE"blk_rowxfer 
returns CS_END_DATA to indicate that all rows have 
been transferred.

When copying data into a database, MOREINFO="NONE"blk_rowxfer does 
not return CS_END_DATA.ID="IN46-683752"blk_rowxferreason for failureREMAP="BO--Body"A common reason for a MOREINFO="NONE"blk_rowxfer failure is conversion error.CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"blk_rowxfer is a Client-Library bulk copy routine.The number of rows transferred per MOREINFO="NONE"blk_rowxfer call is determined by the value of datafmtname='rArrow' font='symbol' code='174'  charset='fontspecific'count in an application's MOREINFO="NONE"blk_bind calls for the operation. If datafmtname='rArrow' font='symbol' code='174'  charset='fontspecific'count is greater than 1, array binding is considered to be in effect and multiple rows are transferred per MOREINFO="NONE"blk_rowxfer call.ID="IN46-663954"blk_rowxferpurposeAn application calls MOREINFO="NONE"blk_rowxfer to:MARK="DASH" REMAP="BS--BulletSub"Transfer rows into the database, during a bulk copy in operation.Transfer rows out from the database, during a bulk copy out operation.ID="IN46-663955"Array bindingtransferring rows during a bulk copy operation
ID="IN46-663956"Bulk copyarray binding
ID="IN46-624357"blk_textxferusing with blk_rowxferIf array binding is not in effect, an application can use MOREINFO="NONE"blk_textxferID="IN46-584758"blk_rowxferusing with blk_textxfer
 in conjunction with MOREINFO="NONE"blk_rowxferID="IN46-584759"Text and image datatransferring rows during a bulk copy operation
 to transfer rows containing large text or image values. For information on how to do this, see LINKEND="X73052"Chapter 3,  "Introducing Bulk Copy"
.ID="IN46-584760"Text and image datatransferring rows in chunks
ID="IN46-584761"Datatransferring data in chunks
ID="IN46-584762"Bulk copytransferring text and image data in chunksWhen transferring rows that contain large text or image columns, it is often convenient for an application to transfer the text or image data in fixed-size chunks, rather than all at once. To accomplish this:MARK="DASH" REMAP="BS--BulletSub"The application passes buffer as NULL in its MOREINFO="NONE"blk_bind call for the column. This tells Client-Library that data for this column will be transferred using MOREINFO="NONE"blk_textxfer.When the application calls MOREINFO="NONE"blk_rowxfer to transfer the row, MOREINFO="NONE"blk_rowxfer returns CS_BLK_HAS_TEXT, indicating that Client-Library expects further data for this row to be transferred with MOREINFO="NONE"blk_textxfer.Then, for each column requiring transfer, the application calls MOREINFO="NONE"blk_textxfer in a loop that terminates when MOREINFO="NONE"blk_textxfer returns CS_END_DATA, indicating that all of the data for this column has been transferred.A bulk copy operation is not automatically terminated if MOREINFO="NONE"blk_rowxfer returns CS_FAIL. An application can continue to call MOREINFO="NONE"blk_rowxfer after correcting (copy in operations only) or discarding the problem row.ID="IN46-564963"blk_rowxfercode exampleExampleREMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"/*** BulkCopyIn()** BLKDATA and DATA_END are defined in the bulk copy** example program.*/ CS_STATIC CS_RETCODE BulkCopyIn(connection)CS_CONNECTION   *connection;{    CS_BLKDESC   *blkdesc;    CS_DATAFMT   datafmt;/* variable descriptions */    Blk_Data     *dptr;/* data for transfer */    CS_INT       datalen[5];/* variable data length */    CS_INT       len;    CS_INT       numrows;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /*    ** Ready to start the bulk copy in now that all the    ** connections have been made and have a table name.    ** Start by getting the bulk descriptor initializing.    */    ...CODE DELETED.....REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"    /*    ** Now to bind the variables to the columns and    ** transfer the data    */    datafmt.locale = 0;    datafmt.count = 1;    dptr = BLKDATA;    while (dptr->pub_id != DATA_END)    {        datafmt.datatype = CS_INT_TYPE;        datafmt.maxlength = sizeof(CS_INT);        datalen[0] = CS_UNUSED;REMAP="COW--CompOutWide" FORMAT="LINESPECIFIC"        if (blk_bind(blkdesc, 1, &datafmt, &dptr->pub_id,             &datalen[0], NULL) != CS_SUCCEED)        {            ex_error("BulkCopyIn: blk_bind(1) failed");            return CS_FAIL;        }        datafmt.datatype = CS_CHAR_TYPE;        datafmt.maxlength = MAX_PUBNAME - 1;        datalen[1] = strlen(dptr->pub_name);        if (blk_bind(blkdesc, 2, &datafmt, dptr->pub_name,             &datalen[1], NULL) != CS_SUCCEED)        {            ex_error("BulkCopyIn: blk_bind(2) failed");            return CS_FAIL;        }        datafmt.maxlength = MAX_PUBCITY - 1;        datalen[2] = strlen(dptr->pub_city);        if (blk_bind(blkdesc, 3, &datafmt, dptr->pub_city,             &datalen[2], NULL) != CS_SUCCEED)        {            ex_error("BulkCopyIn: blk_bind(3) failed");            return CS_FAIL;        }        datafmt.maxlength = MAX_PUBST - 1;        datalen[3] = strlen(dptr->pub_st);        if (blk_bind(blkdesc, 4, &datafmt, dptr->pub_st,             &datalen[3], NULL) != CS_SUCCEED)        {            ex_error("BulkCopyIn: blk_bind(4) failed");            return CS_FAIL;        }        datafmt.maxlength = MAX_BIO - 1;        datalen[4] = strlen((char *)dptr->pub_bio);        if (blk_bind(blkdesc, 5, &datafmt, dptr->pub_bio,             &datalen[4], NULL) != CS_SUCCEED)        {            ex_error("BulkCopyIn: blk_bind(5) failed");            return CS_FAIL;        }        if (blk_rowxfer (blkdesc) == CS_FAIL)        {            ex_error("BulkCopyIn: blk_rowxfer() failed");            return CS_FAIL;        }        dptr++;    }     /* ALL the rows sent so clear up */    ...CODE DELETED.....     return CS_SUCCEED;}See AlsoREMAP="BO--Body"LINKEND="X80356"blk_bind
MOREINFO="NONE", LINKEND="X93934"blk_textxferID="X47553"blk_sendrowID="IN47-535366"blk_sendrow
ID="IN47-535368"Bulk copysending a formatted bulk copy row
ID="IN47-535369"Rowsending a formatted bulk copy row
Send a formatted bulk copy row.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE blk_sendrow(blkdesc, row) CS_BLKDESC     *blkdesc;CS_BLK_ROW     *row;ParametersREMAP="RI--RefIndent"blkdesc - A pointer to the CS_BLKDESC which is serving as a control block for the bulk copy operation. MOREINFO="NONE"blk_alloc allocates a CS_BLKDESC structure.row - A pointer to a CS_BLK_ROW structure containing a formatted bulk copy row. A gateway application can retrieve a CS_BLK_ROW structure containing a formatted row by calling the Server-Library bulk copy routine MOREINFO="NONE"blk_getrow.ReturnsTOCENTRY="1"LBL="Table 4-25: "Return values (MOREINFO="NONE"blk_sendrow)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_BLK_HAS_TEXTCOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"The row contains one or more text, image, sensitivity, 
or boundary columns. The application must call 
MOREINFO="NONE"blk_gettext and MOREINFO="NONE"blk_sendtext to transfer the columns for 
this row before calling MOREINFO="NONE"blk_getrow and MOREINFO="NONE"blk_sendrow to 
transfer the next row.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.CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"blk_sendrow is a Client-Library bulk copy routine.ID="IN47-515574"Gateway applicationsGateway applicationsand blk_sendrowblk_sendrowA gateway application uses MOREINFO="NONE"blk_sendrow in conjunction with the Server-Library bulk copy routine MOREINFO="NONE"blk_getrow. Together, the two routines enable a gateway application to receive formatted bulk copy rows from an Open Client application and send them on to a SQL Server.ID="IN47-475975"blk_sendrowwhen to use instead of blk_rowxfer
MOREINFO="NONE"blk_sendrow is a gateway-specific substitute for MOREINFO="NONE"blk_rowxfer. An application can call MOREINFO="NONE"blk_sendrow only after calling MOREINFO="NONE"blk_getrow to retrieve a formatted row.The sequence of calls in the gateway application is:MARK="DASH" REMAP="BS--BulletSub"MOREINFO="NONE"blk_getrow, to pick up a formatted bulk copy rowMOREINFO="NONE"blk_sendrow, to send the formatted row to SQL ServerREMAP="UN--Under"If MOREINFO="NONE"blk_getrow returns CS_BLK_HAS_TEXT, the application must call the following routines in a loop, until MOREINFO="NONE"blk_gettext returns CS_END_DATA:MARK="DASH" REMAP="BS--BulletSub"MOREINFO="NONE"blk_gettext, to pick up a chunk of text, image, sensitivity, or boundary dataMOREINFO="NONE"blk_sendtext, to send a chunk of text, image, sensitivity, or boundary dataREMAP="UN--Under"Only one MOREINFO="NONE"blk_gettext/MOREINFO="NONE"blk_sendtext loop is required, no matter how many text, image, sensitivity, or boundary columns are being transferred.See AlsoREMAP="BO--Body"LINKEND="X31050"blk_init
MOREINFO="NONE", LINKEND="X65669"blk_sendtext
MOREINFO="NONE", LINKEND="X44199"blk_colval
MOREINFO="NONE", LINKEND="X95049"blk_getrow
MOREINFO="NONE", LINKEND="X80979"blk_gettextID="X65669"blk_sendtextID="IN48-446377"blk_sendtext
ID="IN48-446379"Text and image datasending text and image data in a formatted bulk copy row
ID="IN48-446380"Sensitivity columnsending sensitivity data in a formatted bulk copy row
ID="IN48-446381"Boundarysending boundary data in a formatted bulk copy row
ID="IN48-446382"Bulk copysending text, image, sensitivity, or boundary data in a formatted bulk copy row
ID="IN48-446383"Rowsending text, image, sensitivity, or boundary data in a formatted bulk copy row
Send text, image, sensitivity, or boundary data in a formatted bulk copy row.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE blk_sendtext(blkdesc, row, buffer,              buflen) CS_BLKDESC    *blkdesc;CS_BLK_ROW    *row;CS_BYTE       *buffer;CS_INT        buflen;ParametersREMAP="RI--RefIndent"blkdesc - A pointer to the CS_BLKDESC which is serving as a control block for the bulk copy operation. MOREINFO="NONE"blk_alloc allocates a CS_BLKDESC structure.row - A pointer to a CS_BLK_ROW structure containing a formatted bulk copy row. A gateway application can retrieve a CS_BLK_ROW structure containing a formatted row by calling the Server-Library bulk copy routine MOREINFO="NONE"blk_getrow.buffer - A pointer to the space from which MOREINFO="NONE"blk_sendtext picks up the chunk of text, image, sensitivity, or boundary data.buflen - The length, in bytes, of the *buffer data space. ReturnsTOCENTRY="1"LBL="Table 4-26: "Return values (MOREINFO="NONE"blk_sendtext)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.CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"blk_sendtext is a Client-Library bulk copy routine.ID="IN48-426588"Gateway applicationsGateway applicationsand blk_sendtextblk_sendtext
ID="IN48-386989"blk_sendtextusing in conjunction with blk_gettextA gateway application uses MOREINFO="NONE"blk_sendtext in conjunction with the Server-Library bulk copy routine MOREINFO="NONE"blk_gettext. Together, the two routines enable a gateway application to receive chunks of text, image, sensitivity, or boundary data in formatted bulk copy rows from an Open Client application and send them on to a SQL Server.ID="IN48-347390"blk_sendtextwhen to use instead of blk_textxfer
MOREINFO="NONE"blk_sendtext is a gateway-specific substitute for MOREINFO="NONE"blk_textxfer. An application can call MOREINFO="NONE"blk_sendtext only after calling MOREINFO="NONE"blk_gettext to retrieve a chunk of text, image, sensitivity, or boundary data belonging to a formatted row.The sequence of calls in the gateway application is:MARK="DASH" REMAP="BS--BulletSub"MOREINFO="NONE"blk_getrow, to pick up a formatted bulk copy rowMOREINFO="NONE"blk_sendrow, to send the formatted row to SQL ServerREMAP="UN--Under"If MOREINFO="NONE"blk_sendrow returns CS_BLK_HAS_TEXT, the application must call the following routines in a loop, until MOREINFO="NONE"blk_gettext returns CS_END_DATA:MARK="DASH" REMAP="BS--BulletSub"MOREINFO="NONE"blk_gettext, to pick up a chunk of text, image, sensitivity, or boundary dataMOREINFO="NONE"blk_sendtext, to send a chunk of text, image, sensitivity, or boundary dataREMAP="UN--Under"Only one MOREINFO="NONE"blk_gettext/MOREINFO="NONE"blk_sendtext loop is required, no matter how many text, image, sensitivity, or boundary columns are being transferred.See AlsoREMAP="BO--Body"LINKEND="X31050"blk_init
MOREINFO="NONE", LINKEND="X47553"blk_sendrow
MOREINFO="NONE", LINKEND="X44199"blk_colval
MOREINFO="NONE", LINKEND="X95049"blk_getrow
MOREINFO="NONE", LINKEND="X80979"blk_gettext
ID="IN48-317692"blk_srvinit blk_srvinitID="IN49-317794"Descriptioncopying a column description to a client
ID="IN49-317795"Columncopying a column description to a client
Copy descriptions of server table columns to the client, if required. REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE blk_srvinit(srvproc, blkdescp) SRV_PROC      *srvproc;CS_BLKDESC    *blkdescp;ParametersREMAP="RI--RefIndent"srvproc - A pointer to the SRV_PROC structure associated with the client receiving column descriptions. It contains all the information that Server-Library uses to manage communications and data between the Open Server application and the client.blkdescp - A pointer to a structure containing information about bulk copy data. This structure must have been previously allocated with a call to MOREINFO="NONE"blk_alloc and initialized via a call to MOREINFO="NONE"blk_init. This structure is used to correctly interpret incoming formatted bulk copy rows.ReturnsTOCENTRY="1"LBL="Table 4-27: "Return values (MOREINFO="NONE"blk_srvinit)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; no action was taken.CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"blk_srvinitID="IN49-2979100"Gateway applicationsGateway applicationsand blk_srvinitblk_srvinit
 is a Server-Library bulk copy routine that is useful in gateway applications.This routine sends the current server table column descriptions in the ID="IN49-2583101"CS_BLKDESC structureused by blk_srvinit
CS_BLKDESC structure to the client, if the client's TDS (Tabular Data Stream) version is 5.0 or greater.ID="IN49-2385102"blk_srvinitcalled in response to an "insert bulk" requestThis routine must be called from within a ID="IN49-1989103"SRV_LANGUAGE event handlercalling blk_srvinit from within the event handler
SRV_LANGUAGE event handler, in response to an "insert bulk" request from the client.Once MOREINFO="NONE"blk_srvinit has returned successfully, the Open Server applications ID="IN49-1593104"SRV_BULK event handlerusing with blk_srvinit
SRV_BULK event handler may begin reading bulk data from the client, beginning first with a call to MOREINFO="NONE"blk_rowalloc, and followed by calls to MOREINFO="NONE"blk_getrow.MOREINFO="NONE"blk_init places the descriptions in the CS_BLKDESC structure, so the gateway application must call it before calling MOREINFO="NONE"blk_srvinit.See AlsoREMAP="BO--Body"LINKEND="X31050"blk_init
ID="IN49-1296106"blk_srvinit 
MOREINFO="NONE", LINKEND="X73052"Bulk CopyID="X93934"blk_textxferID="IN50-9100107"blk_textxfer
ID="IN50-9100109"Transferringa columnÕ s data in chunks
ID="IN50-9100110"Columntransferring a columnÕ s data in chunks
ID="IN50-9100111"Datatransferring columns in chunks
ID="IN50-9100112"Bulk copytransferring a columnÕ s data in chunks
Transfer a column's data in chunks during a bulk copy operation.REMAP="LS--LangSyntax" FORMAT="LINESPECIFIC"CS_RETCODE blk_textxfer(blkdesc, buffer, buflen,              outlen) CS_BLKDESC    *blkdesc;CS_BYTE       *buffer;CS_INT        buflen;CS_INT        *outlen;ParametersREMAP="RI--RefIndent"blkdesc - A pointer to the CS_BLKDESC which is serving as a control block for the bulk copy operation. MOREINFO="NONE"blk_alloc allocates a CS_BLKDESC structure.buffer - A pointer to the space from which MOREINFO="NONE"blk_textxfer picks up the chunk of text, image, sensitivity, or boundary data.buflen - The length, in bytes, of the *buffer data space. outlen - A pointer to an integer variable. REMAP="UN--Under"outlen is not used for a bulk copy in operation and should be passed as NULL.REMAP="UN--Under"For a bulk copy out operation, *outlen represents the length, in bytes, of the data copied to *buffer.ReturnsTOCENTRY="1"LBL="Table 4-28: "Return values (MOREINFO="NONE"blk_textxfer)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_END_DATACOLNAME="C2" ALIGN="LEFT" ROTATE="0" MOREROWS="0"When copying data out from a database, MOREINFO="NONE"blk_textxfer 
returns CS_END_DATA to indicate that a complete 
column value has been sent.
When copying data into a database, MOREINFO="NONE"blk_textxfer returns 
CS_END_DATA when an amount of data equal to 
MOREINFO="NONE"blk_bind's *datalen has been sent.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.CommentsMARK="BULL" REMAP="BU--Bullet"MOREINFO="NONE"blk_textxfer is a Client-Library bulk copy routine.Although MOREINFO="NONE"blk_textxferID="IN50-9100117"Text and image datatransferring data in chunks
 is primarily useful for transferring large text or image values, it can be used to transfer data of any datatype. However, MOREINFO="NONE"blk_textxfer does not perform any data conversion, but simply transfers data.There are two ways for an application to transfer text and image values during a bulk copy operation:MARK="DASH" REMAP="BS--BulletSub"The application can treat text or image data like ordinary data: that is, it can bind columns to program variables and transfer rows using MOREINFO="NONE"blk_rowxfer. Generally, this method is convenient for small text and image values but not larger ones, because it requires an application to allocate program variables large enough to hold entire columns.The application can transfer text or image data in chunks, using MOREINFO="NONE"blk_textxfer.ID="IN50-9100118"Markinga column for transfer
ID="IN50-9100119"Columnmarking a column for transferAn application marks a column for transfer via MOREINFO="NONE"blk_textxfer by calling MOREINFO="NONE"blk_bind for the column with a NULL buffer parameter.For more information on using MOREINFO="NONE"blk_textxfer, see LINKEND="X73052"Chapter 3,  "Introducing Bulk Copy"
.ID="IN50-7102120"blk_textxferbulk copies into a databaseBulk Copies Into a DatabaseMARK="BULL" REMAP="BU--Bullet"An application's MOREINFO="NONE"blk_bind calls do not have to be in column order, but data for MOREINFO="NONE"blk_textxfer columns must be transferred in column order.REMAP="UN--Under"For example, an application can bind columns 3 and 4, and then mark columns 2 and 1 for transfer via MOREINFO="NONE"blk_textxfer. After calling MOREINFO="NONE"blk_rowxfer to copy data for columns 3 and 4, the application needs to call MOREINFO="NONE"blk_textxfer to transfer data for column 1 before calling it for column 2.When copying data into a database, once a text, image, boundary, or sensitivity column is marked for transfer via MOREINFO="NONE"blk_textxfer, all subsequent columns of these types must also be marked for transfer via MOREINFO="NONE"blk_textxfer.REMAP="UN--Under"That is, an application cannot mark the first text column in a row for transfer via MOREINFO="NONE"blk_textxfer and then bind a subsequent text column to a program variable.When copying data into a database, an application is responsible for calling MOREINFO="NONE"blk_textxfer the correct number of times to transfer the complete text or image value.ID="IN50-5104121"blk_textxferbulk copies from a databaseBulk Copies From a DatabaseMARK="BULL" REMAP="BU--Bullet"When using MOREINFO="NONE"blk_textxfer to copy data out of a database, only columns that follow bound columns are available for transfer via MOREINFO="NONE"blk_textxfer.REMAP="UN--Under"That is, an application cannot bind the first two columns in a row to program variables, mark the third for transfer via MOREINFO="NONE"blk_textxfer, and bind the fourth. Another way to think of it is that columns being transferred via MOREINFO="NONE"blk_textxfer must reside at the end of row.When copying data out from a database, MOREINFO="NONE"blk_textxfer returns CS_END_DATA to indicate that a complete column value has been copied.ID="IN50-3106122"blk_textxfercode exampleExampleREMAP="COW10--CompOutWide10pt" FORMAT="LINESPECIFIC"         /*          ** BulkCopyIn()          **          ** BLKDATA and DATA_END are defined in the bulk copy          ** example program.          */           CS_STATIC CS_RETCODE           BulkCopyIn(connection)          CS_CONNECTION   *connection;          {               CS_BLKDESC   *blkdesc;               CS_DATAFMT   datafmt;      /* variable descriptions */               Blk_Data     *dptr;        /* data for transfer */               CS_INT       datalen[5];   /* variable data length */               CS_INT       len;               CS_INT       numrows;                /*               ** Ready to start the bulk copy in now that all the               ** connections have been made and have a table name.               ** Start by getting the bulk descriptor initializing.               */               ...CODE DELETED.....                /* Bind columns and transfer rows */               dptr = BLKDATA;               while (dptr->pub_id != DATA_END)               {                    datafmt.datatype = CS_INT_TYPE;                    datafmt.count = 1;                    datafmt.maxlength = sizeof(CS_INT);                    datalen[0] = CS_UNUSED;                     if (blk_bind(blkdesc, 1, &datafmt, &dptr->pub_id,                          &datalen[0], NULL) != CS_SUCCEED)                    {                         ex_error("BulkCopyIn: blk_bind(1) failed");                         return CS_FAIL;                    }                    datafmt.datatype = CS_CHAR_TYPE;                    datafmt.maxlength = MAX_PUBNAME - 1;                    datalen[1] = strlen(dptr->pub_name);                    if (blk_bind(blkdesc, 2, &datafmt, dptr->pub_name,                          &datalen[1], NULL) != CS_SUCCEED)                    {                         ex_error("BulkCopyIn: blk_bind(2) failed");                         return CS_FAIL;                    }                    datafmt.maxlength = MAX_PUBCITY - 1;                    datalen[2] = strlen(dptr->pub_city);                    if (blk_bind(blkdesc, 3, &datafmt, dptr->pub_city,                          &datalen[2], NULL) != CS_SUCCEED)                    {                         ex_error("BulkCopyIn: blk_bind(3) failed");                         return CS_FAIL;                    }                    datafmt.maxlength = MAX_PUBST - 1;                    datalen[3] = strlen(dptr->pub_st);                    if (blk_bind(blkdesc, 4, &datafmt, dptr->pub_st,                          &datalen[3], NULL) != CS_SUCCEED)                    {                         ex_error("BulkCopyIn: blk_bind(4) failed");                         return CS_FAIL;                    }                    datafmt.datatype = CS_TEXT_TYPE;                    datafmt.maxlength = MAX_BIO - 1;                    datalen[4] = strlen((char *)dptr->pub_bio);                    if (blk_bind(blkdesc, 5, &datafmt, NULL,                          &datalen[4], NULL) != CS_SUCCEED)                    {                         ex_error("BulkCopyIn: blk_bind(5) failed");                         return CS_FAIL;                    }                    if (blk_rowxfer (blkdesc) == CS_FAIL)                    {                         ex_error("BulkCopyIn: EX_BLK - Failed on \                              blk_rowxfer.");                         return CS_FAIL;                    }                    if (blk_textxfer(blkdesc, dptr->pub_bio,                         datalen[4], &len) == CS_FAIL)                    {                         ex_error("BulkCopyIn: blk_rowxfer() failed");                         return CS_FAIL;                    }                    dptr++;               }               /* ALL the rows sent so clear up */               ...CODE DELETED.....                return CS_SUCCEED;          }See AlsoREMAP="BO--Body"LINKEND="X80356"blk_bind
, LINKEND="X79318"blk_rowxfer