Error Guide

Open Client Error Messages Guide

Open Client 10.x and 11.x

Document ID: 35217-01-1100-03

Last Revised: June 28, 1999

Principal author: Hema Seshadri,

Contributing editors: Cris Gutierrez, Robin McCann, Jon Egerton-Kemp, Craig Sandvik, David Peterson

Document ID: 35217-01-1100

This publication pertains to Open Client 10.x and 11.x of the Sybase databasemanagement software and to any subsequent version until otherwise indicated innew editions or technical notes. Information in this document is subject to changewithout notice. The software described herein is furnished under a licenseagreement, and it may be used or copied only in accordance with the terms of thatagreement.

Document Orders

To order additional documents, U.S. and Canadian customers should callCustomer Fulfillment at (800) 685-8225, fax (617) 229-9845.

Customers in other countries with a U.S. license agreement may contact CustomerFulfillment via the above fax number. All other international customers shouldcontact their Sybase subsidiary or local distributor.

Upgrades are provided only at regularly scheduled software release dates.

Copyright © 1989–1999 by Sybase, Inc. All rights reserved.

No part of this publication may be reproduced, transmitted, or translated in anyform or by any means, electronic, mechanical, manual, optical, or otherwise,without the prior written permission of Sybase, Inc.

Sybase Trademarks

Sybase, the SYBASE logo, Adaptive Server, APT-FORMS, Certified SYBASEProfessional, the Certified SYBASE Professional logo, Column Design,ComponentPack, Data Workbench, First Impression, InfoMaker, ObjectCycle,PowerBuilder, PowerDesigner, Powersoft, Replication Server, S-Designor, SQLAdvantage, SQL Debug, SQL SMART, Transact-SQL, Visual Components,VisualWriter, and VQL are registered trademarks of Sybase, Inc.

Adaptable Windowing Environment, Adaptive Component Architecture,Adaptive Server Enterprise Monitor, Adaptive Warehouse, ADA Workbench,AnswerBase, Application Manager, AppModeler, APT-Build, APT-Edit, APT-Execute, APT-Library, APT-Translator, APT Workbench, Backup Server, BayCam,Bit-Wise, ClearConnect, Client-Library, Client Services, CodeBank, ConnectionManager, DataArchitect, Database Analyzer, DataExpress, Data Pipeline,DataServer, DataWindow, DB-Library, dbQueue, Developers Workbench,DirectConnect, Distribution Agent, Distribution Director, Embedded SQL, EMS,Enterprise Application Server, Enterprise Application Studio, EnterpriseClient/Server, EnterpriseConnect, Enterprise Data Studio, Enterprise Manager,Enterprise SQL Server Manager, Enterprise Work Architecture, Enterprise WorkDesigner, Enterprise Work Modeler, EWA, Formula One, Gateway Manager,GeoPoint, ImpactNow, InformationConnect, InstaHelp, InternetBuilder, iScript,

Jaguar CTS, jConnect for JDBC, KnowledgeBase, Logical Memory Manager,MainframeConnect, Maintenance Express, MAP, MDI Access Server, MDIDatabase Gateway, media.splash, MetaBridge, MetaWorks, MethodSet,MySupport, Net-Gateway, NetImpact, Net-Library, Next Generation Learning,ObjectConnect, OmniConnect, OmniSQL Access Module, OmniSQL Toolkit, OpenClient, Open ClientConnect, Open Client/Server, Open Client/Server Interfaces,Open Gateway, Open Server, Open ServerConnect, Open Solutions, Optima++,PB-Gen, PC APT-Execute, PC DB-Net, PC Net Library, Power++, Power AMC,PowerBuilt, PowerBuilt with PowerBuilder, PowerDynamo, PowerJ, PowerScript,PowerSite, PowerSocket, Powersoft Portfolio, PowerStudio, Power ThroughKnowledge, PowerWare Desktop, PowerWare Enterprise, ProcessAnalyst,Replication Agent, Replication Driver, Replication Server Manager, Report-Execute, Report Workbench, Resource Manager, RW-DisplayLib, RW-Library,SAFE, SDF, Secure SQL Server, Secure SQL Toolset, Security Guardian, SKILS,smart.partners, smart.parts, smart.script, SQL Code Checker, SQL Edit, SQLEdit/TPU, SQL Modeler, SQL Remote, SQL Server, SQL Server/CFT, SQLServer/DBM, SQL Server Manager, SQL Server SNMP SubAgent, SQL Station,SQL Toolset, Sybase Central, Sybase Client/Server Interfaces, SybaseDevelopment Framework, Sybase Financial Server, Sybase Gateways, SybaseLearning Connection, Sybase MPP, Sybase SQL Desktop, Sybase SQL Lifecycle,Sybase SQL Workgroup, Sybase Synergy Program, Sybase Virtual ServerArchitecture, Sybase User Workbench, SybaseWare, SyberAssist, SyBooks, System10, System 11, the System XI logo, SystemTools, Tabular Data Stream, TheEnterprise Client/Server Company, The Extensible Software Platform, The FutureIs Wide Open, The Learning Connection, The Model for Client/Server Solutions,The Online Information Center, Translation Toolkit, Turning Imagination IntoReality, UltraLite, UNIBOM, Unilib, Uninull, Unisep, Unistring, URK Runtime Kitfor UniCode, Viewer, VisualSpeller, VisualWriter, WarehouseArchitect, WarehouseStudio, Warehouse WORKS, Watcom, Watcom SQL, Watcom SQL Server, Web.PB,Web.SQL, WebSights, WebViewer, WorkGroup SQL Server, XA-Library, XA-Server, and XP Server are trademarks of Sybase, Inc. 2/99

Unicode and the Unicode Logo are registered trademarks of Unicode, Inc.

All other company and product names used herein may be trademarks orregistered trademarks of their respective companies.

Restricted Rights

Use, duplication, or disclosure by the government is subject to the restrictions setforth in subparagraph (c)(1)(ii) of DFARS 52.227-7013 for the DOD and as set forthin FAR 52.227-19(a)-(d) for civilian agencies.

Sybase, Inc., 6475 Christie Avenue, Emeryville, CA 94608.

Title for Your Book’s Footers v

Table of Contents

How to Find Error Information

1. BCP and Bulk Library Errors MessagesMemory allocation failed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2Front end does not support this feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4Bulk login property must be set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6Unknown datatype encountered . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8Conversion stopped due to syntax error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10Unknown version of bcp format-file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-13Unexpected EOF encountered . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-14Oversized row/overflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-15Unrecognized datatype found in format file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-17blk_init failed, or, Error occurred when attempting to localize . . . . . . . . . . . . . . . 1-18Bulk alloc failed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-20Identity columns and -E option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-22Missing external configuration data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-24

2. Embedded SQL/C and COBOL Error MessagesUnable to find ‘WHENEVER...’ statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2INCLUDE SQLDA not valid in ESQL/COBOL . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4Incorrect type of indicator variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5Unrecoverable error occurred. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6Unexpected CS_PARAM_RESULT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8Unexpected CS_ROW_RESULT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10Incomplete result set processing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12Error initializing Client Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14Server does not support TEXT or IMAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16Unterminated C string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-18Invalid column name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-19Unchained transaction mode only . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-21Invalid precision or scale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-23

3. Client Library Error MessagesCall to connect two endpoints failed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2

vi Table of Contents

Product Name & Version Number

Attempt to connect to the server failed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7Maximum number of connections already opened . . . . . . . . . . . . . . . . . . . . . . . . . 3-9Net-lib operation terminated due to disconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-10Routine cannot be called while results are pending . . . . . . . . . . . . . . . . . . . . . . . . 3-12Command structure has results pending . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-14Illegal value CS_DATAFMT structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-15Parameter must be 0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-17Illegal value for parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-19Server does not support parameters of type text/image . . . . . . . . . . . . . . . . . . . . . 3-23No driver of the requested protocol class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-25Data NULL when defining input parameters for cursors . . . . . . . . . . . . . . . . . . . 3-27Passing parameters by name and position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-30Bind resulted in truncation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-32Read from the server has timed out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-34Connection has been marked dead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-37CS_IODESC only for text or image columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-38CS_IODESC cannot be retrieved . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-40CS_IODESC structure must be set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-42Bytes exceeds the amount specified . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-44Bytes specified have not been sent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-46ID already exists on connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-48ID does not exist. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-51 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-53Sticky binds do not match result set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-54Error while binding to directory service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-56Attempt to load protocol driver failed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-59

4. DB-Library Error MessagesSQL Server connection timed out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2Read from SQL Server failed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4Unable to open socket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6SQL Server is unavailable or does not exist. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9Maximum dbprocesses already allocated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12Unexpected EOF from SQL Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14General SQL Server error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-17Results pending . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-19Bad token from SQL Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-24Unknown bind type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-26

Title for Your Book’s Footers vii


Unknown datatype encountered . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-28Attempt to bind to a non-existent column . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-30dbbind() with mismatched column and variable types . . . . . . . . . . . . . . . . . . . . . 4-32Attempt to retrieve data from a non-existent row . . . . . . . . . . . . . . . . . . . . . . . . . 4-33DBPROCESS is dead or not enabled. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-35Syntax error in source field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-37Unknown network type found in interface file . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-39Too much TEXT data via the bcp_moretext() call . . . . . . . . . . . . . . . . . . . . . . . . . 4-41dbreadtext() may only be used to receive the results... . . . . . . . . . . . . . . . . . . . . . . 4-43Zero length TEXT or IMAGE to dataserver via dbwritetext() . . . . . . . . . . . . . . . 4-45DBPROCESS is being used for another transaction . . . . . . . . . . . . . . . . . . . . . . . 4-47Called dbmoretext with a bad size parameter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-49Packet size of %1! not supported . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-51Function can be called only once . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-53RPC parameters cannot be of type Text/Image . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-55

A. Commands to Find Sybase Versions

B. Open Client/Server 10.0.x and 11.x Runtime Environment

C. How to Interpret Client-Library Error SQLCODEs

D. Sample Code for Error Handling

E. Sample Code for Handling Large Text and Image Data

viii Table of Contents


Open Client Error Messages Guide ix

How to Find Error Information

How to Use This Book

This manual is intended to help you troubleshoot error messagesfrom the following products:

• bcp utility and Bulk Library

• Open Client Embedded SQL/C and Embedded SQL/COBOL

• Open Client Client-Library

Which Errors Are Documented?

The errors documented in this manual are those that most frequentlyresult in Technical Support calls. The manual is intended to help youresolve the most common problems yourself. However, you mayexperience errors which are not documented here.

How Do I Locate the Error Message I Need?

The Open Client products do not use a consistent error numbersystem. Therefore, error numbers are not used as headings forsections on individual errors; instead, the headings are abbreviatedfrom the message text. The best way to find your error is to search fora string from the error message that you received.

When searching for a string, try to leave out details that refer to thespecific instance of the error; those details would be represented byplaceholders in this document. For example, the following errormessage:

ct_param(): user api layer: external error: Anillegal value of 0 was placed in the status fieldof the CS_DATAFMT structure.

is represented in this manual as:

ct_param(): user api layer: external error: Anillegal value of %1! was placed in the %2! fieldof the CS_DATAFMT structure.

See Search Help in Technical Library for types of searches that mightbe most efficient.

x


Related Documents

See the following manuals for more information on Open Clientproducts:

• Open Client Client-Library/C Programmer’s Guide

• Open Client Client-Library/C Reference Manual

• Open Client and Open Server Common Libraries Reference Manual

• Open Client DB-Library/C Reference Manual

• Open Client Embedded SQL/C Programmer’s Manual

• Open Client Embedded SQL/COBOL Programmer’s Manual

• Open Client/Server Configuration Guide for your platform

• Open Client/Server Programmer’s Supplement for your platform

• Utility Programs for your platform

Sample Programs

This book contains sample code to help you resolve specificproblems. You can find additional sample programs by going to theTechnical Documents collection of Technical Library on the Web athttp://support.sybase.com. From the Support Services tab, select thelink to “Technical Documents”. Search the collection for theseTechNote titles:

• Client-Library Sample Programs

• Embedded SQL/C Sample Programs

• Embedded SQL/COBOL Sample Programs

The TechNotes explain how to locate and download the samples.

Other Sources of Information

Use the Sybase Technical Library CD and the Technical Library Website to learn more about your product:

• Technical Library CD contains product manuals and technicaldocuments and is included with your software. The DynaTextbrowser (included on the Technical Library CD) allows you toaccess technical information about your product in an easy-to-use format.

Open Client Error Messages Guide xi


Refer to the Technical Library Installation Guide in yourdocumentation package for instructions on installing andstarting Technical Library.

• Technical Library Web site includes the Product Manuals site,which is an HTML version of the Technical Library CD that youcan access using a standard Web browser. In addition, you’ll findlinks to the Technical Documents Web site (formerly known asTechnical Information Library), the Solved Cases page, andSybase/Powersoft newsgroups.

To access the Technical Library Web site, go tosupport.sybase.com, click the Electronic Support Services tab,and select a link under the Technical Library heading.

If You Need Help

Each Sybase installation that has purchased a support contract hasone or more designated people who are authorized to contact SybaseTechnical Support. If you cannot resolve a problem using themanuals or online help, please have the designated person contactSybase Technical Support or the Sybase subsidiary in your area.

xii


Open Client Error Messages Guide Page -1

1 BCP and Bulk LibraryErrors Messages 1.

This chapter includes some of the more common error messagesreturned by the bcp utility and by Bulk Library, a set of commands forperforming bulk copying from Open Client applications.

Error numbers may vary or may not be displayed depending onwhether you are using bcp or Bulk Library. Therefore, error numbersare not always listed in this chapter.

Page -2 BCP and Bulk Library Errors Messages


Memory allocation failed

Error Number

None

Message Text

Open Client 11.x

Fatal error: memory allocation failed.

Open Client 10.0.x

Unable to allocate sufficient memory

Possible Cause

This error can occur when there is insufficient memory on the hostmachine to perform the requested bcp operation.

The amount of memory needed by bcp depends on the tabledefinition, including the number of columns in the table, the numberof text or image columns, batch size, and so on.

Action

To resolve the problem, take the following actions as appropriate:

• Check the amount of memory currently available to bcp on yourmachine. Increase physical or virtual memory, or exit otherapplications to free up resources.

To check memory resources, use one of the following methods:

UNIX

Several UNIX commands can give you total and availablememory information. Examples of UNIX commands that youcan use include:

• dmesg

• top

• hpglance (HP only)

See your operating system documentation for commandsspecific to your platform.



Windows NT

Check memory statistics as follows:

1. Start up the task manager.

2. Click on the performance tab. The box in the lower left corner ofthe performance display contains kernel memory information,including total, paged, and non-paged memory.

• If your bcp batch size is large, try setting it to a smaller size.

Versions in Which This Error Is Raised

• bcp 10.0.x and 11.x

• Bulk Library 10.0.x and 11.x.



Front end does not support this feature

Error Number

4805

Message Text

The front end tool you are using does not supportthe feature of bulk insert from host, please usethe proper tools for this command.

Possible Cause

Possible causes for this error include:

• The DB-library program initiating the bulk copy operation doesnot have the bulk copy property set.

• The bulk copy property was set after the connection was opened.

• See Error 4805 in the Adaptive Server(TM) EnterpriseTroubleshooting and Error Messages guide for other reasons forthe error.

Action

The call to enable bulk copy in a DB-library program must be madebefore you open a connection with dbopen(). Make the following DB-Library call to enable bulk copy for a connection:

BCP_SETL(login, true);....LOGINREC *login;DBPROCESS *dbproc;..../* Establish a login rec */login = dblogin();..../* Enable bulk copy for this loginrec */BCP_SETL(login, TRUE);..../* Establish a connection with the dataserver */dbproc = dbopen(login, NULL);..../* Begin bulk copy operations */bcp_init ( .. );....




This error is raised by Adaptive Server and SQL Server(R). andreturned to DB-Library 10.0.x and later.



Bulk login property must be set

Error Number

22

Message Text

Application must log in with bulk login propertyset.

Possible Cause

This error occurs when a Client-Library application attempts tomake Bulk Library calls without first enabling bulk copy.

Action

By default the CS_BULK_LOGIN property, which enables anapplication to make Bulk Library calls, is set to false (CS_FALSE). Anapplication enables bulk copy by setting the CS_BULK_LOGINproperty to CS_TRUE. You can set the property to true in two ways:

• In the ct_con_props routine. Your application must call ct_con_propsbefore calling ct_connect to establish the connection. You can setthe bulk login property to CS_TRUE in this routine, for examplelike this:

CS_BOOL bool;....bool = CS_TRUE;retcode = ct_con_props( *conn_ptr, CS_SET,CS_BULK_LOGIN, &bool, CS_UNUSED, NULL);....

• In a runtime configuration file. This is a new feature availablewith Open Client 11.x. Check to see if a runtime configuration fileexists. The usual file name is ocs.cfg, but any name can be usedand referenced within the application. If the file exists, check tosee if it has a line setting the bulk login to FALSE. Edit the line orenter a new line to set the property to TRUE as follows:

CS_BULK_LOGIN=CS_TRUE

If no file exists and you wish to create one, use the file sample.cfgas a template. On Microsoft Windows platforms, the sample.cfgfile is located in the ini subdirectory of the Open Clientinstallation. On UNIX platforms, you can find a sample.cfg file inthe config subdirectory.



➤ NoteCreating an external configuration file named ocs.cfg can affect Client-

Library based utilities such as bcp and isql. Unless you are completely

familiar with the use and naming of the configuration file, we recommend

setting the bulk login property in the application in the ct_con_props call.

Additional Information

See the Open Client Reference Manual for more information aboutsetting properties with ct_con_props and the configuration file.


• Bulk Library 10.0.x and later



Unknown datatype encountered

Error Number

20060

Message Text

Bulk Library

Unknown datatype encountered.

bcp

Unknown fixed-length datatype encountered.

➤ NoteThe first error text is displayed only by the DB-Library programming

interface (API). The error number is displayed only by the DB-Library

programming interface.

Possible Cause

DB-Library 4.x and bcp 4.x do not support numeric and decimaldatatypes. Support for these datatypes was introduced in Release10.x. If you get this error while using the bcp utility, you may be usinga 4.x version of bcp with a 10.x or higher version of the Server.

This error can occur with DB-Library 10.x and 11.x, as well as 4.x. DB-Library defaults to 4.x behavior unless you explicitly instruct it to use10.x or higher behavior.

Action

Take one of the following actions to correct the problem:

• If you are using bcp, upgrade to bcp 10.0.x or 11.x. The bcp utility isbundled with your Adaptive Server, SQL Server, and Open Clientsoftware. See Appendix A, “Commands to Find Sybase Versions”for the command for your platform to determine the version ofbcp that you are currently running.

• If you are using DB-Library 4.x and wish to use the numeric ordecimal datatypes, upgrade your Open Client product to thecurrent release. See Appendix A, “Commands to Find Sybase



Versions” for the command for your platform to determine theversion of DB-Library that you are currently running.

• If you are using DB-Library 10.0.x or 11.x, include the followingline of code in your DB-Library program:

dbsetversion(DBVERSION_100);

This call must be made before calling any other DB-Libraryroutine, with the exception of dbinit. See the DB-LibraryReference Manual page for dbsetversion for more details.


• bcp 4.x

• DB-Library 10.x and later.



Conversion stopped due to syntax error

Error Number

26

Message Text

bcp

The conversion/operation was stopped due to asyntax error in the source field.

Bulk Library

The conversion/operation was stopped due to asyntax error in the source field. Failed inconversion routine - syntax error.

Possible Cause

When copying data in ascii format from a bcp or Bulk Library file to adestination table, bcp automatically converts the data to thecorresponding column type in the destination table. This automaticconversion may fail for one of the following reasons:

• There is a mismatch between the data in the host file and itscorresponding column datatype. For example, bcp cannot copy avalue of 100 into a datetime column.

See the conversion table in the Adaptive Server Enterprise ReferenceManual for a list of conversions that the Server can do implicitly.

• The data in the host file does not match the format file definition.This is especially true of fixed length records, where a singlecharacter out of place can cause problems.

• Characters embedded in the data, such as commas in numericaldata, are not valid for the column type. For example, if bcp tries tocopy a number written as 1,234,567 into an int, float, numeric ordecimal column, it raises a syntax error. Similarly, a currencysymbol such as “$” will cause a problem in an int, float, numeric ordecimal column.

• The characters used to specify column or row delimiters areembedded in the data. For example, a hyphenated word maycause a problem if you have defined the column delimiter as ahyphen.



• The host file contains fewer columns than the target table. If thisis the case, the missing columns must allow nulls or havedefaults. If they allow nulls or defaults, you need to enter aplaceholder in the host file, separated by column delimiters. Forexample, if a table is defined as:

col1 intcol2 int nullcol3 int

the host file does not contain any data for column 2, and thedelimiter is a comma, the row in the host file should look likethis:

100,,200

• The hostfile contains more columns than the target table, and youhave not told bcp which columns to skip. This is done by enteringa “0” in the format file for that column.

• The bcp operation was not run in character mode. You must usecharacter mode with ascii data. To ensure that you are running incharacter mode, do one of the following:

- Launch bcp with the -c option

- If using a format file, enter all host types as SYBCHAR. Thedatatype listed in the format file refers to the datatype of thedata file, not the datatype of the column in the target table.

Action

To locate the source of the problem, issue the bcp command using the-e <error_file> option. bcp then reports the row and column numberwhere it detected the error and writes the row(s) to the error file.Look for one of the problems described in the previous section.

Error column information may be misleading

bcp reports the column where it detected the error, not necessarily thecolumn in which the error occurred.

The follow example illustrates this point. A target table is defined as:

fname char(15)lname char(15)birthdate datetime

The bcp format file contains this definition:



10.031SYBCHAR015"-"1col12SYBCHAR015"-"2col23SYBCHAR08"\n"3col3

The hostfile to be copied into the table includes the following rows:

Susan-Smith-12/12/67Cara-Jones-Parker-05/06/71

The first record is copied correctly: “Susan” is copied into Column 1,then the hyphen tells bcp to go to Column 2. In column 2, bcp enters“Smith”, then sees the hyphen and moves on to Column 3. InColumn 3, it enters “12/12/67”, sees the newline, and ends the row.

bcp begins the second record by copying “Cara” into Column 1,reading the hyphen and moving to Column 2. It enters “Jones” inColumn 2, but then interprets the hyphen of “Jones-Parker” as acolumn terminator and moves on to Column 3. It now wants to enter“Parker”, but Column 3 is defined as datetime, bcp then raises aconversion error.

When the operation is run with the -e option, the error is reported inthe third column. However, the problem is really in the previouscolumn. To find this kind of error, you may need to look at allcolumns in the host file and match them with the format file and thedatatype of the corresponding column in the destination table.


• bcp 10.0.x and later

• bcp using DB-Library calls 10.0.x and later.



Unknown version of bcp format-file

Error Number

None

Message Text

Attempt to read an unknown version of bcp format-file.

Possible Cause

The first row in the format file used for bcp operations contains thefile’s version number. The only two valid values for the versionnumber in a format file are 4.0 and 10.0, written exactly this way. Anyother value will return the “unknown version” error.

You must enter the correct format file version for the bcp version youare running. The following table lists bcp versions and their validformat file versions:

➤ NoteThe format file version is based on the TDS version (Sybase’s proprietary

protocol) and does not correspond exactly to software version.

Action

If you are running bcp version 10.0.x or higher, change the format fileversion to 10.0.

If you are running bcp 4.x, change the format file version to 4.0.


• bcp - all versions.

• Bulk Library 10.0.x and later.

• bcp calls using DB-Library 4.x and later.

For bcp version: Use format file version:

4.x 4.0

10.x, 11.x 10.0



Unexpected EOF encountered

Error Number

None

Message Text

Unexpected EOF encountered in bcp data-file.

Possible Cause

bcp detected an end-of-file marker while reading the host data file.

Action

Take the following actions to find the source of the problem:

• Check the data file for any blank rows and delete them.Sometimes an extra blank row may be found after the last rowand should be deleted.

• Check the data to see if any of the row or column delimiters areembedded in the data values. This confuses bcp and causesunexpected behavior. See “Conversion stopped due to syntaxerror” for an explanation of the delimiter issue.

If your data file is large, split it into batches to make checking easier.Start with a large batch size, such as 10,000 for a table of 100,000 rows.Determine which batch contains the error. Then narrow your searchby setting a smaller batch size and using the -F and -L options tospecify the first and last rows to copy, until you arrive at the problemrow.

➤ NoteUsing the -e error flag to generate an error log will not help you troubleshoot

this problem because it is not a bcp error, but a problem in the data.


• bcp 10.0.x and later.


• bcp calls using DB-Library 10.0.x and later.



Oversized row/overflow

Error Number

None

Message Text

bcp 10.0.4

Attempt to bulk-copy an oversized row to the SQLServer.

bcp 11.x

The result is truncated because theconversion/operation resulted in overflow.

Bulk Library 10.x and later

Failed in conversion routine - condition overflow.

➤ NoteThis error is silent in versions of bcp previous to 10.0.4

Possible Cause

The character data that bcp is copying into a destination column islarger than the defined width of the column, so the data is truncated.bcp continues the copy operation, but issues a warning.

The following example illustrates the truncation error. The publisherstable in the pubs2 database is defined as:

pub_id char(5),pub_name varchar(40),city char(20)state char (2)

Trying to insert the following record into this table would trigger atruncation error:

1234, Wagden Books, Washington, D.C.

The width of the state column is 2 but the value as written here is fourcharacters wide. Only the first two characters, “D.”, are copied intothe column state.



Action

Take one of the following actions as appropriate:

• Ignore the message, if truncation is not a cause for concern.

◆ WARNING!Data integrity could be compromised.

• Increase the width of the column to accommodate the newvalues. You need to create a new table to do this. Copy existingdata from the old table to the newly defined one, then drop theold table and rename the new one.

• Modify the data in the host file to the width of the column.

• If you think you should not be getting this error, check the data tosee if any row or column delimiters are embedded in the datavalues. This alters the position of subsequent fields and can causedata to be copied into the wrong column.


• bcp 10.0.4 and 11.x

• Bulk Library 10.0.x and later

• DB-Library 10.0.4



Unrecognized datatype found in format file

Error Number

None

Message Text

bcp 10.x

Unrecognized datatype found in format file. ()

bcp 11.x

Unrecognized datatype ‘xxx’ found in format file. ()

Possible Cause

This error may be caused by the following:

• An invalid datatype describing one or more columns in the hostdata file was found in the format file.

• The format file contains a typographical error.

Action

If the host data file is in ascii format, change all the host datatypes inthe format file to SYBCHAR. The datatype in the format file refers tothe datatype of data in the host file, not the datatype of thecorresponding table column. If you use bcp in native format, refer tothe ‘Utility Programs’ manual for a list of valid types.

Alternatively, you can perform the bcp out operation withoutspecifying the -n or -c (native or character) options. bcp will promptyou for the information it needs to automatically create a format file.


• bcp 11.x and 10.0.x.


• bcp using DB-Library calls 10.0.x and later.



blk_init failed, or, Error occurred whenattempting to localize

Error Number

None

Message Text

blk_init failed.

Or:

Internal error: An error occurred when attemptingto localize the application.

Possible Cause

This error may occur when either of the locales files blklib.loc orctbcp.loc is missing. If the file ctbcp.loc is missing, bcp raises thefollowing error:

Internal error: An error occurred when attemptingto localize the application.

If the file blklib.loc is missing, then bcp raises the following error:

blk_init failed.

Action

Take one of the following actions to correct the problem:

• Look for the files blklib.loc and ctbcp.loc in one of the followingdirectories:

- $SYBASE/locales/message/<language> (Open Client 11.x)

- $SYBASE/locales/<language>/<charset> (Open Client 10.0.x).

If one of these files is missing, download the Open Clientsoftware from your Sybase CD to a temporary location, thencopy the missing file to the appropriate directory. If a file ismissing from your CD, call Technical Support.

• If you are using bcp or Bulk Library 11.x, verify that you arerunning the task in an Open Client 11.x environment. Check the$SYBASE environment variable to see that it points to the 11.xdirectory. Open Client 11.x requires locales and configurationfiles that did not exist in earlier versions of Open Client.




bcp 11.x.



Bulk alloc failed

Error Number

None

Message Text

Bulk alloc failed.

➤ NoteThis error is returned by an application when it is unable to allocate memory

for a bulk copy call and returns CS_FAIL. At this point, Bulk Library error

messages have not yet been loaded

Possible Cause

Failure to allocate memory following a blk_alloc call may be due to oneof the following:

• A missing locales file, blklib.loc

• Inadequate memory on the host machine to allocate a bulkdescriptor for the bulk copy operation.

• An invalid connection pointer

Action

Take one of the following actions to resolve the problem:

• Look for the file blklib.loc in one of the following directories:

- $SYBASE/locales/message/<language> (Open Client 11.x)

- $SYBASE/locales/<language>/<charset> (Open Client 10.0.x).

If the file is missing, download the Open Client software fromyour Sybase CD to a temporary location, then copy the missingfile to the appropriate directory. If the file is missing from yourCD, call Technical Support.

• If you are using bcp or Bulk Library 11.x, verify that you arerunning the task in an Open Client 11.x environment. Check the$SYBASE environment variable to see that it points to the 11.xdirectory. Open Client 11.x requires locales and configurationfiles that did not exist in earlier versions of Open Client.



• Check the amount of memory currently available on yourmachine. Increase physical or virtual memory, or exit otherapplications to free up resources. Only a small amount ofmemory is allocated at this time, just enough for internalstructures for the bulk descriptor. (Space for tables to be copied isnot allocated until the blk_init call.)

To check memory resources, use one of the following methods:

UNIX

Several UNIX commands can give you total and availablememory information. Examples of UNIX commands that youcan use include:

• dmesg

• top (Sun only)

• hpglance (HP only)

See your operating system documentation for commandsspecific to your platform.

Windows NT

Check memory statistics as follows:

1. Start up the task manager.

2. Click on the performance tab. The box in the lower left corner ofthe performance display contains kernel memory information,including total, paged, and non-paged memory.

• Verify that you allocate a valid connection pointer in theconnection allocation statement.

See the Common Libraries Reference Manual for more information onblk_alloc.


• Bulk Library 10.0.x and 11.x.



Identity columns and -E option

Error Number

None

Message Text

The format-file instructed bcp not to copy theidentity column, conflicts with the -E option.

Possible Cause

This error occurs when both these conditions are present:

• The format file indicates that the column in the data filecorresponding to the identity column in the table should beskipped.

• bcp is started with the -E flag, which instructs bcp to read thevalues for the identity column from the data file.

This problem is illustrated by the following example. A table iscreated as follows:

create table test(col1 numeric identity,col2 int,col3 int,col4 int)

A row in the host datafile contains:

100,2,3,4

The format file reads as follows:

10.041 SYBCHAR 0 20 "," 0 col12 SYBCHAR 0 10 "," 2 col23 SYBCHAR 0 10 "," 3 col34 SYBCHAR 0 10 "\n" 4 col4

Although the value of the identity column in the host data file is 100,the 0 in the format file for that column indicates that the columnshould be skipped. However, the following command explicitly tellsbcp to read the values for the identity column:

bcp test in datafile -f bcp.fmt -Uuser -Ppasswd -E

This creates a contradiction that bcp is unable to resolve.



Action

Take either of the following actions to resolve the problem:

• Change the format file so you do not skip the values for theidentity column.

• Omit the -E flag and skip the identity column.

See the Utility Programs manual for your platform for more details onusing bcp with the -E and -N options. (The -N option is used when thedata file does not contain identity column values.)


bcp Utility 11.x.



Missing external configuration data

Error Number

None

Message Text

CS-Library

comn_get_cfg: user api layer: internal commonlibrary error: Configuration section bcp not found.

CT-Library

ct_connect(): user api layer: external error: Theconnection failed because of invalid or missingexternal configuration data.

Possible Cause

Open Client/C 11.x lets you use runtime configuration files forClient-Library applications, including bcp. There is no defaultruntime configuration file included with your software—you mustcreate your own if you wish to use one. You can create, place, andname configuration files as needed. However, when an Open Clientapplication is launched, by default Open Client looks for aconfiguration file named ocs.cfg under the config subdirectory of theOpen Client 11.x directory. If the file exists, Open Client expects tofind the configuration information for the application in it.

The “missing configuration” error occurs when both theseconditions are true:

• An ocs.cfg file exists

• The [bcp] section is missing

This usually occurs when you have created an ocs.cfg runtimeconfiguration file for use with other applications, but have notcreated a section for bcp.

Action

To resolve this problem, take one of the following actions:

• Create a section for bcp in the ocs.cfg file. Add this section head tothe file:

[bcp]



You can use the section to set properties for all bcp users or leaveit empty.

➤ NoteThe same error can occur in isql 11.x. if it does not find a section named

[ctisql] in the ocs.cfg file.

• You do not need a runtime configuration file to run bcp. If youcreate a runtime configuration file to use with another applicationand give it a name other than ocs.cfg, or place it in a directoryother than config, you will not get this error for bcp.

See the Open Client-Client Library Reference Manual for informationabout the ocs.cfg configuration file.


• bcp 11.x.




2 Embedded SQL/C and COBOLError Messages 2.

This chapter includes some of the more common error messagesreturned by Embedded SQL/C and Embedded SQL/COBOL.

Error numbers may vary or may not be meaningful. Therefore, errornumbers are not always listed in this chapter.

Page -2 Embedded SQL/C and COBOL Error Messages


Unable to find ‘WHENEVER...’ statement

Error Number

None

Message Text

Unable to find the SQL statement ‘WHENEVER NOTFOUND’.

Unable to find the SQL statement ‘WHENEVERWARNING’.

Unable to find the SQL statement ‘WHENEVERSQLERROR’.

Possible Cause

To help assure that you have included error handling instructions inyour program, the ESQL precompiler looks for three wheneverstatements:

• whenever sqlwarning

• whenever sqlerror

• whenever not found

If the precompiler fails to find these statements, it issues a warning.

Action

If you have written your own code to check for errors and warnings,you can do one of the following:

• Suppress the precompiler warnings by writing a whenever...continueclause for each condition. This instructs the precompiler to ignoreerrors and warnings.

• Precompile using the -w flag. This suppresses the warningmessages.

• Simply ignore the precompiler warnings.

If you have not written your own error-handling code, add themissing statement to the application. The statements can be placedafter the connect statement or ahead of the SQL statements that youwant them to affect.

The general syntax of the whenever statement is:



C language

exec sql whenever{sqlwarning | sqlerror | not found}{continue | stop | goto label |call function_name ([param [, param]...])};

COBOL

exec sql whenever{sqlwarning | sqlerror | not found ]{continue | goto label | stop |program call [using param . . .]) |perform paragraph_1 [through paragraph_2] }

end-exec

See the chapter on “Handling Errors” in the Embedded SQL/CProgrammer’s Manual for more information. See also the onlinesamples located under the $SYBASE/sample/esqlc directory.


• ESQL/C 10.0.x and later.

• ESQL/COBOL 10.0.x and later.



INCLUDE SQLDA not valid in ESQL/COBOL

Error Number

None

Message Text

The INCLUDE SQLDA statement is not valid inESQL/COBOL.

Possible Cause

The SQLDA feature for Dynamic SQL is available only in EmbeddedSQL/C 11.x. Currently, you cannot use it support SQLDA inESQL/COBOL.

Action

Instead of a SQLDA structure, use system descriptors for yourDynamic SQL commands. See the chapter on Dynamic SQL in theEmbedded SQL/COBOL Programmer’s Manual.


• ESQL/COBOL 11.x.



Incorrect type of indicator variable

Error Number

None

Message Text

Incorrect type of indicator variable %!.

Possible Causes

An indicator variable in ESQL must be a 2-byte integer. For ESQL/C,indicator variables must be declared as type short or CS_SMALLINT.For ESQL/COBOL, indicator variables must be declared as one ofthe following:

• PIC S9(2) COMP.

• PIC S9(4) DISPLAY SIGN LEADING [SEPARATE]

• PIC S9(4) DISPLAY SIGN TRAILING [SEPARATE]

• PIC S9(4) COMP-4

• PIC S9(4) COMP-5

• PIC S9(4) BINARY

• PIC S9(4) COMP.

Action

Follow the instructions for your programming environment:

C language

Change the host type of indicator variables in the program to typeshort or CS_SMALLINT.

COBOL

Change the host type of indicator variables in the program to one ofthe types listed above.






Unrecoverable error occurred

Error Number

25001

SQL State

ZZ000

Message Text

10.x

Unrecoverable error occurred. Fatal: Immediatelyreport this error to Sybase Technical Support.

11.x

The context allocation routine failed. Thefollowing problem caused the failure: Initializingthe error cache failed. Unrecoverable erroroccurred.

Possible Cause

Possible causes of this are detailed below:

• The error usually occurs when there is an incompatibilitybetween the runtime environment and build environment for theapplication. This is true whether your applications were builtusing static or dynamic libraries.

• The error can occur if the cslib.loc file is missing. It is possible,though less likely, that other missing locales files can cause theerror.

Action

Take one of the following actions to resolve this problem:

• Verify that the application is running on the same version ofESQL version that it was compiled and linked on. Check theSYBASE environment variable in both the development andruntime environments to see that it points to an installation of thesame version of ESQL. Also, check your makefile for the locationof the SYBASE directory used to build the application.



See Appendix A, “Commands to Find Sybase Versions” forinstructions on determining ESQL version.

• Verify that cslib.loc exists in one of the following directories:

10.x

- $SYBASE/locales/<language>/<charset>

11.x

- $SYBASE/locales/message/<language>

• Test the online sample program. This sample program is locatedin one of the following directories:

- $SYBASE/sample/esqlc/example1.cp (ESQL/C)

- $SYBASE/sample/esqlcob/example1.pco (ESQL/COBOL)

Make and test the program under the same conditions as yourapplication. If the sample works correctly, the problem is notyour runtime environment. Contact Technical Support.

See Appendix B, “Open Client/Server 10.0.x and 11.xRuntime Environment” for a complete list of locales files required fordifferent versions of ESQL.






Unexpected CS_PARAM_RESULT

Error Number

-25005 (C)

SQL State

ZF000 (COBOL)

Message Text

Unexpected CS_PARAM_RESULT received.

Possible Cause

The ESQL application received output parameters that it was notequipped to handle.

Action

To correct this problem, first check the stored procedure definition tosee if it has defined output parameters. Log into the server with isqland issue the following command:

sp_helptext stored_proc_name

If the stored procedure definition contains output parameters, edityour ESQL program to recognize them. The following exampleillustrates how you can code an application when a stored procedurereturns parameters.

Example

An ESQL application needs to execute the following storedprocedure:

create proc test_proc(@type char(10),@sales int output)

as select @sales=sum(tot_sales) from pubs2..titleswhere type = @typereturn

To execute this procedure from ESQL, you might code yourapplication as follows:



C language

....CS_CHAR type[15];CS_INT retcode, sales;....

exec sql exec :retcode = test_proc:type, :sales output;....

COBOL

01 type pic x(15).01 retcode pic 9999.01 sales pic S9(9) COMP.

....

exec sql exec :retcode = test_proc:type, :sales outputend-exec....

This tells the application to expect return parameters from the salesvariable defined in the stored procedure.






Unexpected CS_ROW_RESULT

Error Number

-25006

Message Text

Unexpected CS_ROW_RESULT received.

Possible Cause

This error indicates that the ESQL application received results from aselect statement that it was not equipped to handle. This may becaused by one of the following conditions:

• No into :<host_variable> clause provided for a select statement. Aselect generally contains an into :<host_variable> clause, with hostvariables provided for every column returned.

• No into :<host_variable> clause provided for an exec <stored_procedure>statement. If the stored procedure being executed returns a row,the program must contain an into :<host_variable> clause, with hostvariables provided for every column returned.

If a select statement or stored procedure returns multiple rows,you must either store the columns in host variable arrays, ordeclare a cursor for the exec statement and perform cursorprocessing.

• If the program did not previously return the error on executing agiven stored procedure, the stored procedure may have changed.According to ESQL rules, a stored procedure can return only oneset of row results and can therefore contain only one selectstatement (though it can include other SQL statements). TheESQL program must be able to handle results from the selectwithin the stored procedure.

Action

Take the following actions to correct this problem:

• Change the program code to include an into :hostvar list if one hasnot been specified for a select or fetch statement. For example:

....CS_CHARbook_id[8], type[15], price[8];

....select title_id, type, price from pubs2..titlesinto :book_id, :type, :price;



• If multiple rows are expected and no cursor has been declared forthe select, use arrays. For example:

....CS_CHARbook_id[18][8];CS_CHARtype[18][15], price[18][8];

....select title_id, type, price from pubs2..titlesinto :book_id, :type, :price;

Arrays can also be used for results from stored procedures. Forexample, if a stored procedure was defined as:

create proc test_proc(@type char(10))asselect title_id, type, pricefrom pubs2..titleswhere type = @typereturn

Write ESQL your code like this:

CS_CHARbook_id[18][8];CS_CHARtype[18][15], price[18][8];....exec sql exec :retcode = test_proc :typeinto :book_id, :type, :price;

See the Programmer’s Manual for your product for examples onusing cursors to process multiple rows.

• If the error occurs during a stored procedure call, check the storedprocedure definition to see if it contains more than one selectstatement. Log into the server with isql and issue the followingcommand:

sp_helptext stored_procedure

This displays the stored procedure code. Correct the procedureor program as necessary.





Incomplete result set processing

Error Number

-16843171

Error Message

ct_results(): user api layer: external error: Thisroutine cannot be called until all fetchableresults have been completely processed.

Possible Cause

This error occurs when a new command or operation is attemptedbefore all rows from a select, fetch, or exec <stored_procedure> statementhave been processed.

The error is also raised if:

• A non-cursor select statement returns multiple rows and the hostvariables are not arrays.

• A non-cursor select statement returns multiple rows and the hostvariable array defined for them is not large enough to hold allreturned rows. When you use arrays in non-cursor fetchoperations, the size of the array must be large enough to hold allrows returned for that query. If you fetch with a cursor, the arraysize can be smaller, as the data can be fetched in batches.

• While a cursor result set is still being processed, you issue newselect that returns multiple rows.

• You are using Dynamic SQL Method 2 and the statement returnsmultiple rows. With Method 2, “prepare and execute”, you canonly issue statements that return no rows or one row.

• An attempt to disconnect occurs before all results from thecurrent command have been processed

Action

To resolve this problem, take the following actions as appropriate:

• If a new operation or command is initiated during processing ofa previous select or fetch, check to see if it is allowable.

For example, the following commands do not require all resultsto be fetched before they can be issued:

- In-place cursor updates or deletes



- A new command issued on another connection while resultson the first connection are still being processed

• If the command being issued is not allowed, take one of thefollowing actions:

- If a select statement or stored procedure returns multiple rows,use a cursor to fetch the rows or use array variables largeenough to store all the returned rows.

- Log into the server with isql and issue the same query. Seewhether you get back more than one row (if using Method 2).

See the Programmer’s Manual for your product for more informationon the use of arrays to hold rows from stored procedures and for adiscussion of Dynamic SQL methods.






Error initializing Client Library

Error Number

-25016

SQL State

ZM000

Message Text

Error initializing Client Library.

Severity: Severe

Possible Causes(s)

ESQL calls are precompiled to Client Library calls and require aClient-Library runtime environment. This environment includes the$SYBASE/locales directory and the ctlib.loc file. If any of these files ismissing, you will get an initialization error.

In addition, if the ctlib.loc file is missing, you get the followingmessage:

LAYER = (1) ORIGIN = (1) SEVERITY = (4) NUMBER =(118) ct_init(): Unable to find file$SYBASE/<language>/<charset>/ctlib.loc

➤ NoteThe locales directory structure changed between 10.X and 11.x. This

example shows the 10.X directory structure.

Action

Check the following locales directories for missing files:

• $SYBASE/locales/<language>/<charset> (10.x)

• $SYBASE/locales/message/<language> (11.X)

If you are missing a file, take one of the following actions:

• Download your Embedded SQL software from the CD into atemporary directory, then copy the locales directory to youroriginal installation location.

• Re-install the Embedded SQL product



If the file appears to be missing from the CD, call technical support.

See Appendix B, “Open Client/Server 10.0.x and 11.xRuntime Environment” for a complete list of files required to run theEmbedded SQL product.


• ESQL/C 10.0.x and later

• ESQL/COBOL 10.0.x and later



Server does not support TEXT or IMAGE

Error Number

-16843056

Message Text

ct_param(): user api layer: external error: Theserver does not support parameters of type %1.

(Where%1 can be “TEXT” or “IMAGE”.)

Possible Cause

The program is attempting to use host variables of type CS_TEXT orCS_IMAGE incorrectly.

This error occurs when

• An input parameter of type text or image is passed to a storedprocedure. The server does not support parameters of type text orimage, so a stored procedure cannot be defined as having text orimage parameters.

• A Dynamic SQL statement contains placeholders correspondingto text or image columns. Dynamic SQL in Sybase Embedded SQLis implemented using temporary stored procedures in the server.Since Adaptive Server does not support text or image parameters,dynamic SQL parameters cannot be either of these types.

• A host variable of text or image datatype is used as an inputparameter in a SQL statement and the application was notcompiled with the -y option.

Action


• Copy the entire text or image value into a local buffer and then useDynamic SQL Method 1 to send the text of the command andcontents of the buffer to the server. The following exampledemonstrates this method:



....char buffer[10000], cmd[10100];inti = 0;

..../* for demo purposes, put something** into the buffer.*/for ( i = 0 ; i < 10000; i++ )buffer[i] = 'a';

sprintf(cmd, "insert big_table \values('%s')", buffer );

exec sql execute immediate :cmd;....

Using this method you can insert or update text or image valuesup to 65K bytes. Buffers that are larger than this are notsupported by Dynamic SQL.

• ESQL 11.x offers text and image support for regular (non-dynamic) SQL and stored procedure statements. Write your codeusing regular SQL and pre-compile with the -y flag, whichenables this support. This feature is available only in ESQLreleases 11.x and later.

• If you incorrectly declared a host variable in the ESQL program asCS_TEXT or CS_IMAGE, change the variable to anotherdatatype. Change the type to char if possible.

See Appendix E, “Sample Code for Handling Large Text and ImageData” for sample code to handle these datatypes.


• ESQL/C 11.x and later.



Unterminated C string

Error Number

-25014

Message Text

Data exception -- Unterminated C string.

Possible Cause

This error is raised when the data in a string variable is missing aclosing quote. This can happen when:

• The closing quote was omitted.

• The data in a character-type host variable was greater than 255bytes. In this case, any data after the first 255 bytes, including thequote mark, is truncated. This can happen when you try to insertor update text or image data larger than 255 bytes.

Action


• For data less than 255 bytes, terminate the string with a closingquote.

• For text or image data larger than 255 bytes, see the EmbeddedSQL/C Programmer’s Reference Manual for information abouthandling text and image data, and Appendix E, “Sample Code forHandling Large Text and Image Data” for a sample program.





Invalid column name

Error Number

-207

Message Text

Invalid column name.

Possible Cause

• One of the column names in the select list is incorrect. It may bespelled incorrectly or entered in the wrong case, or it may notexist in the table.

• The quoted identifier option is set on and the server encounters astring in double quotes in a SQL Statement. The quoted identifieroption is set on by default in ESQL. When the option is on, theserver treats data in double quotes as a column name. Forexample, the following statement causes an error when “CA”, indouble quotes, is interpreted as a column name:

exec sql select pub_id from publisherswhere state = "CA";

The following statement, with ‘CA’ in single quotes, would executecorrectly:

exec sql select pub_id from publisherswhere state = 'CA';

• Alternatively, you can precompile the application with the -d flag.This tells the server that the application will not be using quotedidentifiers and may send character data to the server in doublequotes (“ “). Precompiling with this flag turns the property off forthe session. If you need to use quoted identifiers in your code,turn the option on before any statement that requires it.

See the section on the set command in the Adaptive Server EnterpriseReference Manual for details on this option.

Action

• Log on to isql and issue the sp_help command for the table. Verifythat column names are spelled correctly in your program’s selectlist.

• If the column list is correct, identify the source of the problem bychecking your code for:



- SQL statements that contain values within double quotes

- The following command, which explicitly turns on the quotedidentifier option:

exec sql set quoted_identifier on;

By default, ESQL opens up a transaction with the quotedidentifier option set on. You may wish to edit data strings withdouble quotes, or you can decide to explicitly set the quotedidentifier option off before a statement containing doublequotes. To turn the option off, enter this line:

exec sql set quoted_identifier off;

You can turn the option off at any point before execution of thestatement. However, this turns the option off for the rest of thesession. If you need to use quoted identifiers in your code, as inthis example:

select “col1” from table

turn the quoted identifier option back on before execution of thestatement that requires it.


This error is returned by Adaptive Server and SQL server and isgeneric to all supported releases of the server and ESQL.



Unchained transaction mode only

Error Number

-7713

Message Text

Stored procedure “<stored_proc_name>” may be runonly in unchained transaction mode. The `SETCHAINED OFF’ command will cause the currentsession to use unchained transaction mode.

Possible Cause

For ANSI compliance, ESQL opens the server connection in chainedmode by default. However, Sybase stored procedures run inunchained mode by default. This error results when an ESQLtransaction running in chained mode calls a stored procedure thatrequires unchained mode.

➤ NoteThe mode determines the way transactions are begun and committed. For

information about modes, see the Transact_SQL User’s Guide.

Action

To correct this error, take one of the following actions:

• Set chained mode off. Add the following command to yourprogram anywhere after the connection is opened, but before thestored procedure is called:

exec sql set chained off;

➤ NoteIf other transactions in your program depend on ESQL running in chained

mode, reset the mode as necessary.

• Use the -m option when you precompile your program to run inunchained mode.

• Change the mode of the stored procedure so that it can run ineither mode. Log into the server with isql and enter the followingcommand:



sp_procxmode stored_procedure , anymode


This is an Adaptive Server and SQL Server error and is generic to allsupported server and Embedded SQL versions.



Invalid precision or scale

Error Number

-16843138

Message Text

ct_param(): user api layer: external error: Aninvalid precision or scale in the CS_NUMERIC orCS_DECIMAL value was supplied.

Possible Cause

This error can occur when:

• An invalid value is assigned to the precision or scale element of aCS_NUMERIC or CS_DECIMAL type.

• Precision or scale is not set in a parameter of type CS_NUMERICor CS_DECIMAL.

Action

Both output and input parameters, if they are set, require that theprecision and scale be valid. Precision, the total number of places forthe digits of a number, must be greater than scale, the number ofplaces after the decimal point. Valid values for precision are from 1 to77 and for scale from 0 to 77.

The following sections discuss some issues specific to output andinput parameters.

Handling output parameters

• Before you use output parameters of type CS_NUMERIC orCS_DECIMAL, you must define their precision and scale. Sinceoutput parameters do not have a value associated with them untilthe procedure has been executed, ESQL (and Client-Library)cannot determine the precision and scale to use. Defaults definedfor the parameter within the stored procedure cannot be usedbecause the client program does not know how the parameter hasbeen defined in the stored procedure.

If you have not defined the precision and scale in the program,do one of the following:

- Initialize the elements of the CS_NUMERIC or CS_DECIMALdatatype variable. For example:



EXEC SQL BEGIN DECLARE SECTIONCS_NUMERIC numeric_var = {18,0,0};CS_DECIMAL decimal_var = {20,2,0};CS_INT ret;

EXEC SQL END DECLARE SECTION....

/* Execute the stored procedure */exec sql exec :ret=proc_name :numeric_var :out;

- Explicitly set the precision and scale elements of the structure.For example:

....CS_NUMERIC numeric_var;

....

/* Do this before referencing the output** parameter in the stored procedure call.*/

numeric_var.precision = 18;numeric_var.scale = 0;

....

/* Execute the stored procedure */exec sql exec :ret=proc_name :numeric_var :out;

....

Any valid precision or scale value can be used in the definition.However, you should define the precision and scale so that theyare large enough to hold the return value.

➤ NoteC only: It is not necessary to map a numeric or decimal server data type to

a CS_NUMERIC or CS_DECIMAL type. You can use any compatible C

type, such as float, double, or int (if the value of scale is 0).

For the definition of CS_NUMERIC and CS_DECIMAL structures,see the file cstypes.h located in the $SYBASE/include directory.

Handling input parameters

If the error is raised on an input parameter, verify that the parameteris assigned a value before it is called. If you create a host variable tohold numeric or decimal query results, then use the variable as an



input parameter for another SQL statement, you could get an error ifthe first query did not yield any results. If no value was retrieved intothe host variable, the precision and scale would not be set for theinput parameter. The following example illustrates this problem:

....CS_NUMERIC num_var;

....exec sql select num_col from test_table

into :num_varwhere int_col > 10000;....

exec sql exec :ret_status = test_proc :num_var;

This select statement retrieves a value into a numeric host variable,and the following statement passes this value as an input parameterto a stored procedure. If the select statement returns a value, ESQLwill correctly set the precision and scale for the host variable.However, if no value is retrieved, the input parameter does not havea value, precision, or scale and an error is raised. To work around thisissue, you can do any of the following

• Take the actions listed for output parameters

• Set the indicator variable (see the last action)

• Check the number of rows returned by the last SQL commandInstructions for checking rows and setting the indicator variableare given in the sections below.

Checking the number of rows returned

Use one of these methods to check the number of rows returned:

• To check the number of rows returned in ESQL/C 10.x, do thefollowing:


into :num_varwhere int_col > 10000;....

/* Use the sqlca.sqlerrd[2] structure variable to* see if the last query returned any rows.*/if ( sqlca.sqlerrd[2] > 0 )/* Rows were returned */

/* Execute the procedure - we have a valid



* input value*/exec sql exec :ret_status = test_proc :num_var;

/* Execute the procedure - with a null* input value*/indic = -1;exec sql exec :ret_status = test_proc

:num_var :indic;

• To check the number of rows in ESQL/COBOL, do the following:


into :num_varwhere int_col > 10000 end-exec....

* Use the SQL--ROWSREAD variable to see* if the last query returned rows.if ( SQL--ROWSREAD > 0 )

* Execute the procedure - we have a valid* input valueexec sql exec :ret_status = test_proc :num_var end-exec

* Rows were returned* Execute the procedure - with a null input valuemove -1 to INDIC.exec sql exec :ret_status = test_proc

:num_var :indic end-exec

Setting the indicator variable

You can also set the indicator variable for the select or in any casewhere the input parameter may be NULL. Initialize the indicatorvariable before executing the statement. The following exampleshows how to do this for a select statement:



....indic = -99; /* Initialize this variable */exec sql select num_col from test_table

into :num_var :indicwhere int_col > 10000 ;

if ( indic == -1 )

/* handle the input param accordingly** before executing the stored procedure.*/

....

The following example shows how to use an indicator variable whenthe program calls a stored procedure:

CS_SMALLINT indic;....

CS_NUMERIC numeric_input;CS_SMALLINT indic;

....indic = -1;exec sql exec :ret=proc_name:numeric_input :indic;

....


This error is raised by:

• ESQL/C 10.0.x and 11.x.

• ESQL/COBOL 10.0.x and 11.x.




3 Client Library Error Messages 3.

This chapter includes some of the more common error messagesreturned by Client-Library.

Client-Library error numbers by themselves are not unique. Eacherror has unique a combination of elements, including severity, layer,and origin. Therefore, error numbers are not listed separately in thissection. For an explanation of the derivation of the error indentifiers,see Appendix C, “How to Interpret Client-LibraryError SQLCODEs”.

Page -2 Client Library Error Messages


Call to connect two endpoints failed

Message Text

Number: (4) Severity (5) Layer (5), Origin (3)text: ct_connect(): network packet layer: internalnet library error: Net-Lib protocol driver call toconnect two endpoints failed.

Possible Cause

This error is raised by the network layer when the client applicationis unable to connect to the server. The most common reasons for thisare:

• The target server is not running.

• There is a problem resolving the network address for the server,which may be due to:

- an error in interfaces or sql.ini file

- the setting of the DSQUERY environment variable

- an incorrect server name entered at the command line or in theapplication

• The server machine is down or not accepting connections.

Action

Because a variety of issues can cause a failure to connect, as well asrelated errors, this section takes you through a systematic check ofthe conditions necessary to connect. You may not need to perform allsteps. The troubleshooting approach breaks down into three mainparts:

1. Is the server running and listing on the expected port?

2. Can the client application locate the server on the network?

3. Can the client connect to the remote server?

1. Is the server running and listing on the expected port?

Check that the server is running and listening on the expected port.The server can be an Open Server as well as an Adaptive or SQLServer. The following sections tell you how to do this on UNIX,Windows, and VMS.



Checking the server on UNIX

On UNIX platforms, try issuing this command from the machinethe server is installed on:

netstat -a | grep < port_no >

where port_no is the number of the port the server is listening on.You can get the name of the server machine and the port numberfrom the interfaces file.

If the output shows a value of LISTEN, the server is up andrunning on that port.

For example, if the server that we wish to connect to is runningon a machine called SARAH on port 34987, on log into SARAHand enter:

netstat -an | grep 34987

If the server is running on SARAH, the output looks like this:

sarah.34987 *.* 0 0 0 0 LISTEN

Checking the server on Windows NT:

On NT platforms using TCP/IP, enter:

netstat -an

Check the output to see if a server is listening on the port.

Checking the server on OpenVMS on VAX or AXP:

For VMS, the command you use to test whether the server isrunning depends on the network protocol, as shown here:

- For AXP and VAX OpenVMS using TCP/IP, you can see aserver process by running the command:

show system

If the server we wish to connect to is called SYBASE and isrunning, the above command would generate an outputsimilar to:

3EC00847 SYBASE_SQL HIB 6 1380 0 02:04:27.96 1141 1424

- If you are using decnet, you can tell if a server is up by issuingthe command:

mc ncp show known objects



Look for a name with the value OBJ_###, where ### is the portnumber in the interfaces file. For example, the server“SYBASE” had the following entry in the interfaces file:

SYBASE master decnet ether MUDHEN 200

To see if this server is running on port 200 on MUDHEN, issuethe command:

$ mc ncp show known objects

Look for output similar to:

OBJ_200 200 3EC00847

➤ NoteOn both VAX and AXP platforms, VMS upshifts (translates logical values to

uppercase). For example, if your interfaces file contains an entry for the

server sybase (lowercase) and you define the DSQUERY logical as follows:

define DSQUERY sybase

you get a connection error because VMS upshifts the value and looks for an

interface entry for SYBASE in uppercase. To be able to use the same case,

issue the define command using double quotes around the name:

define DSQUERY “sybase”

This problem does not occur on UNIX platforms.

If you are still not sure whether the server is running, check withyour database administrator.

2. Can the client application locate the server on the network?

If you are sure the server is running, make sure your application canlocate the server on the network. Perform these checks:

• Check the SYBASE variable to make sure that it points to thecorrect location of your Open Client installation. This lets theclient locate the interfaces (UNIX, VMS) or sql.ini (NT) file.

• Verify that an entry exists in the interfaces or sql.ini file for theserver the application wants to connect to.

• Check the DSQUERY environment variable to make sure that itpoints to the server the client wants to connect to.



• If the error occurred when you tried to connect using isql or bcp,and you used the -S <server_name> parameter, verify that youentered the correct server name. When using isql or bcp, you musteither set the DSQUERY environment variable or specify a servername with -S.

• If the error is raised by a Client-Library application, check thesecond parameter of the ct_connect call, which specifies the servername. If it is set to NULL, then Client-Library uses the value ofDSQUERY. If the parameter is not NULL, then the name specifiedin this call is used to connect to the server.

• If the server name is passed at runtime to the application, verifythat the name being passed exists in the client’s interfaces file.

• If the client application uses the CS_IFILE property to specify alocation other than $SYBASE for the interfaces file, verify that thefile exists at that location.

• If the server name is passed at runtime to the application, makesure that the length parameter of the ct_connect call, whichspecifies the length of the server name, is either CS_NULLTERMor is a strlen of the host variable.

➤ NoteIf you request a connection to a server name that does not exist, you get the

“not found” error rather than the endpoint error:

ct_connect(): directory service layer: internal

directory control layer error: Requested server name not

found.

Follow the steps above to locate the source of the error.

3. Can the client connect to the remote server?

If the server is running and you are trying to connect from anothermachine, verify that you can connect to the server machine from theclient machine:

• Issue the telnet command using the name of the machine on whichthe server is running to verify that you can connect to thatmachine.



• Use sybinit or dsedit on the client machine to add an entry to theinterfaces or sql.ini file for the server, if necessary. These tools willensure that the server entry is written in the correct format.


• Client-Library 10.0.x and later.

• isql, bcp, defncopy 11.x.



Attempt to connect to the server failed

Message Text

Number: (44) Severity (4) Layer (4), Origin (1)text: ct_connect(): protocol specific layer:external error: The attempt to connect to theserver failed.

Possible Cause

This error is raised by isql, bcp, and defncopy, as well as Client-Libraryapplications. The error is usually preceded by an error from theserver that explains why the client connection attempt failed.Common server errors that can cause a failure to connect include thefollowing:

• An incorrect user name or password that causes the login attemptto fail. When this happens, the server generates an error messagelike the following:

Msg 4002, Level 14, State 1:Line 1:Login failed.

Then Client-Library raises the connection error.

• An invalid packet size specified in the CS_PACKETSIZE propertyby a Client-Library application, or with the -A option for isql andbcp.

For example, suppose the default packet size for a server is 512,the max default packet size is 1024, and you make the followinglogin request:

isql -Usa -P -A2048

The login attempt triggers the following error from the server:

The packet size (2048) specified at login time isillegal. Legal values are between ‘512’ and ‘1024’.

This message is then followed by the Client-Library connectionerror message.

Action

To resolve this problem, do the following:

• Verify that your user name and password are valid. If the error israised by a Client-Library application, verify that the valuespassed to CS_USERNAME and CS_PASSWORD are correct. If



your are using isql, bcp, or defncopy, check the values of the –U and–P options.

• If the error is accompanied by a server error referring to aninvalid packet size, log into the server with isql and check thedefault and maximum packet size run values. Use the followingcommand:

1> sp_configure "default network packet size"2> exec sp_configure "max network packet size"3> go

The value specified for CS_PACKETSIZE in the application, orwith the -A option for isql and bcp, must be a multiple of 512 thatlies within the range from the default and to the maximumpacket size.

See the System Administration Guide for more information onsetting packet size.


• Client-Library 10.0.x and later




Maximum number of connections alreadyopened

Message Text

Number: (6) Severity (1) Layer (1), Origin (1)text: ct_connect(): user api layer: externalerror: The maximum number of connections havealready been opened.

Possible Cause

This error occurs when an application tries to open more connectionsto the server than the limit set for the CS_MAX_CONNECT propertyin the ct_config call. The default value is 25. The value applies to thenumber of connections per context.

Action

To resolve this problem, take the following actions, as appropriate:

• Check the application source code for the value of theCS_MAX_CONNECT property. Then check the code for thenumber of connection requests. If the value of theCS_MAX_CONNECT property is smaller than the number ofconnection requests, or if CS_MAX_CONNECT is missing, setthe value to a number large enough to accommodate theconnection requests.

• Change the code to reuse or close some connections.

➤ NoteA different error is raised when the number of connections attempted is

more than the number of users the server is configured for. See “Net-lib

operation terminated due to disconnect” for a description of this error.





Net-lib operation terminated due to disconnect

Message Text

Number: (6) Severity (5) Layer (5), Origin (3)ct_results(): network packet layer: internal netlibrary error: Net-Library operation terminateddue to disconnect.

➤ NoteThis error message occurs only with UNIX versions of Client-Library.

Possible Cause

This error is raised by the network services layer when a clientdisconnects abnormally. This can happen when:

• The server refuses a connection because it would exceed themaximum number of user connections that the server isconfigured for.

• A problem in the network causes connections to be dropped.

• The client has been killed.

Action

To resolve this problem, take the following actions, as appropriate:

• To see if you have exceeded the configured server value for themaximum number of user connections, log into the server withisql and issue this command:

1> sp_configure ‘user connections’2> go

The “run value” is the value of the maximum number of usersparameter. Some of the connections are used for housekeepingtasks, so the number of connections your application may openis less than the maximum number of users allowed.

See the System Administration Guide for an explanation of thenumber of user connections parameter.

Then, issue sp_who to see how many connections have alreadybeen established. The sp_who output may show a lower numberof connections than existed when the error occurred. You mayneed to monitor the output continuously while the applicationruns to get an accurate picture.



If you need more connections than the server allows, ask yourdatabase administrator to raise the value of the number ofmaximum connections parameter.

• Check your network for lost packets. You may want to use a“sniffer” or equivalent tool to do this.

• On UNIX platforms, check the value of the tcp ip abort interval. Ifyour client application is waiting for the server to return resultsfrom a large or time-consuming query, the operating system maydisconnect the client.

• Consider disabling tcp no delay.

• Check the operating system parameter for the number of filedescriptors for both the client and server machines. On mostUNIX machines, you can get this value by issuing the limit or ulimit-a command. If you need to open more connections than thenumber of file descriptors allowed, ask the UNIX systemadministrator to set this parameter to a higher value.


• Client-Library 10.0.x and later




Routine cannot be called while results arepending

Message Text

Number: (16) Severity (1) Layer (1), Origin (1)text: ct_command(): user api layer: externalerror: This routine cannot be called while resultsare pending for a command that has been sent tothe server.

Possible Cause

In general, all results from one set of commands sent to the servermust be completely processed before a new command can beinitiated on the same command structure. This error can occur whenan application attempts to:

• Send a new command on the same command structure (make acall to ct_command) before all results from the previous commandhave been processed.

• Drop a command structure whose results have not beencompletely processed.

• Close a cursor before results have been fetched.

Action

To resolve the problem, take the following actions;

• Check your code to verify that you call ct_results after a ct_send call,then check your result processing loop to see that it processes allresults until ct_results returns a value of CS_SUCCEED. The resulttype retuned for every logical command should beCS_CMD_DONE.

For more information on result processing and logicalcommands, see the section on ct_results in the Client-Library/CReference Manual, which includes sample code that shows atypical result processing loop.

• Verify that both ct_command calls on the previous commandstructure and ct_cmd_drop calls are initiated only after all theresults for the previous command have been processed andct_results returns a value of CS_SUCCEED.







Command structure has results pending

Message Text

Number: (49) Severity (1) Layer (1), Origin (1)text: ct_command(): user api layer: externalerror: This routine cannot be called becauseanother command structure has results pending.

Or:

ct_close(): user api layer: external error: Thisroutine cannot be called because another commandstructure has results pending.

Possible Cause

This error can occur when an application:

• Initiates a new command on a new command structure before allof the results from a previous command have been processed.

• Attempts to close a connection where results are pending.

Action

To resolve the problem, take one of following actions, as appropriate:

• Check your code to verify that you are not issuing a newcommand on a new command structure until all results from aprevious command structure have been completely processed.

• Check your results processing loop. It must process all resultsreturned until ct_results returns a value of CS_SUCCEED.

For more information on result processing, see the section onct_results in the Client-Library/C Reference Manual.

If the error is raised on a ct_close statement, and you want theconnection closed when a certain condition has been met, whether ornot all results have been processed, make the ct_close call using theCS_FORCE_CLOSE option. This closes the connection regardless ofpending results. When you do this, however, the client does notnotify the server of the disconnect.





Illegal value CS_DATAFMT structure

Message Text

Number: (46) Severity (1) Layer (1), Origin (1)text: ct_bind(): user api layer: external error:An illegal value of %1! was placed in the %2!field of the CS_DATAFMT structure.

Or:

ct_param(): user api layer: external error: Anillegal value of %1! was placed in the %2! fieldof the CS_DATAFMT structure.

Possible Cause

This error can occur for the following reasons:

• You have not placed a value in a required field. For example, ifyou pass parameters using ct_param and do not set the status fieldof the CS_DATAFMT structure, you get the following error:

ct_param(): user api layer: external error: Anillegal value of 0 was placed in the status fieldof the CS_DATAFMT structure.

The error occurs because the status field must be set toCS_INPUTVALUE or CS_RETURN when you defineparameters.

• An illegal value is placed in a field of the data format structure ona ct_bind or ct_param call. Fields include name, namelen, maxlength,datatype, count, locale, usertype, precision, scale, status, and format.

For example, binding a column result of type char to a hostvariable, using the following data format structure, causes theerror:

...CS_DATAFMT datafmt;...datafmt.datatype = CS_CHAR_TYPE;datafmt.maxlength = -1;...ct_bind ( ... );...

ct_bind(): user api layer: external error: Anillegal value of -1 was placed in the maxlengthfield of the CS_DATAFMT structure.



The error occurs in this case because maxlength must be a non-negative number for variable length datatypes. (The maxlengthparameter is ignored for fixed-length types.)

• The call sequence is incorrect. For example, when you use cursorsand Dynamic SQL, you must make a describe output call after acursor has been opened. A call to describe output before thecursor is opened can result in an illegal value in the status field ofthe data format structure.

Action

To resolve the problem, take the following actions:

• See the sections on the CS_DATAFMT structure in the Open ClientClient-Library/C Reference Manual for a list of valid values for eachfield in a data format structure. See also the sections on the ct_bindand ct_param calls.

• Check the sequence of calls for describing input and outputparameters. Usually, input and output parameters are definedbefore the command is sent to the server. Calls to describe resultsmust be made after the command has been sent to the server.





Parameter must be 0

Message Text

Number: (4) Severity (1) Layer (1), Origin (1)text: When %1! is NULL the %2! parameter must be 0.

The following are examples of actual errors:

ct_connect(): user api layer: external error: Whenserver_name is NULL the snamelen parameter must be0.

ct_remote_pwd(SET): user api layer: externalerror: When password is NULL the pwdlen parametermust be 0.

ct_remote_pwd(SET): user api layer: externalerror: When server_name is NULL the snamelenparameter must be 0.

Possible Cause

The value of the length parameter for the property named in theerror message must be 0 when the buffer parameter value is NULL.The error occurs when you set the length parameter to a value otherthan 0. The most common reason for the error is specifying a lengthof CS_NULLTERM with a NULL buffer parameter.

The error usually occurs on ct_connect or ct_remote_pwd calls. Forexample, the following call causes the error:

ct_connect ( *conn_ptr, NULL, CS_NULLTERM );

ct_connect(): user api layer: external error: Whenserver_name is NULL the snamelen parameter must be0.

Action

If you specify a value for the buffer parameter, such as a server nameor password, then the length parameter must be set toCS_NULLTERM or strlen(buffer). However, if you want the bufferparameter to be NULL (for example, on a ct_connect call where youwant to get the server name from the DSQUERY variable), set thelength to 0 or to CS_UNUSED.

Check the Open Client Client-Library/C Reference Manual page for thespecific parameter for valid values.



Versions in Which This Error Is Raised:




Illegal value for parameter

Message Text

Number: (5) Severity (1) Layer (1), Origin (1) Anillegal value of %1 given for parameter %2.

Possible Cause

This error usually occurs because a statement contains an invalidcolumn or item number. Placeholder%1 in the error text usuallycontains the invalid column or item number. Placeholder%2 isusually replaced by the words “item” or “column”. The error textlooks similar to these examples:

An illegal value of %1 given for parameter item.

An illegal value of %1 given for parameter column.

The error can occur with ct_bind, blk_bind, ct_get_data, ct_data_info,ct_keydata, and ct_describe calls. The error message always includes thecall on which the error was raised.

An “item” is usually a piece of data that is returned from the serverand needs to be bound to a host variable. It could, but does notnecessarily, correspond to a column in the table; other items such asreturn statuses or output parameters from stored procedures canalso be bound or described.

For example, a value of 0 for a ct_bind item causes the following error:

ct_bind(): user api layer: external error: Anillegal value of 0 given for parameter item.

The term “column”, on the other hand, usually corresponds to aparticular column, such as one specified in a ct_get_data call.

Example of incorrect column reference in a loop

The error can occur when you use a loop to perform data descriptionand your loop is coded with a value outside the range of validcolumn numbers. The following example illustrates this problem.Suppose you send this command to the server:

select pub_id, pub_name from publishers

You need to bind the results from the two columns to variables, soyou write the following code:



....CS_RETCODE retcode;CS_INT i, num_cols;CS_DATAFMT datafmt;CS_SMALLINT indic;..../* get the number of columns */retcode = ct_res_info(cmd_ptr, CS_NUMDATA,&num_cols, CS_UNUSED, NULL) ;....for ( i = 0 ; i <= num_cols ; i++ ){/* describe the data format fields */....retcode = ct_bind (cmd_ptr, i, &datafmt,rowbuffer[i], NULL, &indic) ;....

However, the counter “i”, which has been set to 0, is also used as thefirst column number, generating this error:

ct_bind(): user api layer: external error: Anillegal value of 0 given for parameter item.

Another common cause of the error on a ct_bind call is a loopcondition that is hard-coded to the number of result items expected.This can cause problems with a statement such as:

select * from table_name

if the table definition changes, changing the number of itemsreturned.

Error on a blk_bind call

The error message for a blk_bind call is slightly different. For example,suppose that you want to bulk copy a table with three columns, butthe blk_bind call incorrectly refers to four columns:

....retcode = blk_bind(blkdesc, 4, &datafmt,(CS_VOID *)dptr->pub_name, &datalen[1], NULL);|....

The error message would look like this:

blk_bind(): blk layer: user error: Parametercolnum has an illegal value of 4



Action

In general, since this error is caused by an invalid column or itemnumber, check the number for validity. Use one of the followingmethods:

• Check your select statement list for the number of columns to bereturned and match them with the column numbers specified inyour call.

• If the error occurs on a ct_bind or ct_describe loop, call ct_res_infowith CS_NUMDATA to get the number of columns returned forthe SQL statement executed. Take the value returned, N, and callct_bind or ct_describe 1 to N times. If your loop is coded with a valueoutside this range, change your code as illustrated below.

For the following example, refer to the code in the section“Example of incorrect column reference in a loop”. This codeused a variable for the number of columns, but the variable wasset to the value of the loop counter, which started at “0”. Thefollowing code correctly starts the loop counting at “1”:

....CS_RETCODE retcode;CS_INT i, num_cols;CS_DATAFMT datafmt;CS_SMALLINT indic;..../* get the number of columns */retcode = ct_res_info(cmd_ptr, CS_NUMDATA,&num_cols, CS_UNUSED, NULL) ;....for ( i = 1 ; i <= num_cols ; i++ ){/* describe the data format fields */....retcode = ct_bind (cmd_ptr, i, &datafmt,rowbuffer[i], NULL, &indic) ;....}

If you hard-coded a loop to the number of expected columns,change the code to use a variable for the number of columns, asthe example above.

• If the error occurs on a bulk copy in operation, check your hostdata structure or file to make sure that you have the correctnumber of columns. Also check the corresponding table to see ifit has the same (or a smaller) number of columns.



If the error is on a blk_bind call, verify that the number of columnsspecified is equal to the number of columns you copied.

• If the error is on a ct_get_data or ct_data_info call, verify that thecolumn numbers specified to these calls match the text or imagecolumns in the select statement.





Server does not support parameters of typetext/image

Message Text

Number: (48) Severity (1) Layer (1), Origin (1)ct_param(): user api layer: external error: Theserver does not support parameters of type TEXT.

Or:

ct_param(): user api layer: external error: Theserver does not support parameters of type IMAGE.

Possible Cause

The program is attempting to use host variables of type CS_TEXT orCS_IMAGE as input parameters. These datatypes, as well as user-defined text or image datatypes, are invalid when used as parametersand or defined in a CS_DATAFMT structure. Text and imagedatatypes cause the error when used as:

• An input parameter passed to a stored procedure

• Placeholders corresponding to text or image columns in aDynamic SQL statement

• A host variable used as an input parameter in regular a SQLstatement

Action

To resolve the problem, take one of the following actions:

• Adaptive Server does not support parameters of type text orimage, therefore a stored procedure cannot be defined with text orimage parameters. If the problem occurs when the client programcalls a stored procedure, check the host variables in the programand change incorrect ones to valid types.

See the section on “Using CS_DATAFMT structures” in theClient-Library/C Reference Manual for a list of valid datatypes forparameters.

• Use regular text and image handling routines to handle this typeof data, rather than using parameters.

See the section “text and image Data Handling” in the Open ClientClient-Library/C Reference Manual for details.



• Dynamic SQL in Sybase creates temporary stored procedures inthe server. Because the server does not support text or imageparameters, Dynamic SQL cannot use them either. To workaround this restriction, try one of the following methods:

- Change the type of the parameter to char, if possible (the lengthof the data must be less than 255 characters).

- Copy the entire text or image value into a local buffer, then useDynamic SQL Method 1 to send the text of the command andthe contents of the buffer to the server, as in this example:

....CS_COMMAND *cmd;char data[10000], buffer[10100];int i = 0;CS_RETCODE retcode;..../* for demo purposes, stuff something** into the buffer.*/for ( i = 0 ; i < 10000; i++ )data[i] = 'a';

sprintf(buffer, "insert big_table \values('%s')", data );retcode = ct_command (cmd, CS_LANG_CMD,buffer, CS_NULLTERM ..);

....

➤ NoteYou can use this method to insert or update text or image values up to 65K

bytes. Buffers larger than 65K are not supported by Sybase Dynamic SQL.





No driver of the requested protocol class

Message Text

Number: (3) Severity (4) Layer (5), Origin (3)text: ct_connect(): network packet layer: internalnet library error: No driver of the requestedprotocol class is available.

Possible Cause

This error is usually raised by the network layer during a ct_connectcall when the server entry in the client’s interfaces file is in the wrongformat for the network protocol. For example, a TLI-based networkprotocol such as Sun Solaris looks for a server entry in tli format anda socket-based protocol such as HP-UX looks for a correspondingsocket-based tcp/ip format.

A TLI-based entry looks like this:

SYBASEquery tli tcp /dev/tcp \x000213e09d852c880000000000000000master tli tcp /dev/tcp \x000213e09d852c880000000000000000

A socket-based tcp/ip entry for the same server looks like this:

SYBASEquery tcp ether prod1 5088master tcp ether prod1 5088

If the server entry in the client’s interfaces file is in a format differentthan the one Client-Library expects for your operating system, youwill get an error.

➤ NoteClient-Library 11.x and later can interpret both tli and socket entries on

either network protocol.

Action

To correct the error, use a tool such as sybinit or dsedit to reenter theserver address. These tools will ensure that the entry is valid for yourplatform.

See the server installation or configuration guide for moreinformation on interfaces file formats.




• Client-Library 10.0.x.



Data NULL when defining input parameters forcursors

Message Text

Number: (119) Severity (1) Layer (1), Origin (1)text: ct_param(): user api layer: external error:The data must be NULL when defining CS_INPUTVALUEparameters for a ct_cursor (CS_CURSOR_DECLARE)command

Possible Cause

You must define host variable formats for a cursor command whoseSQL string contains host variables before you can pass values to thecursor. The formats should be defined soon after the cursor declarestatement.

Defining variable formats at declare time prepares the cursor for inputat open time. However, the data values for these variables are notpassed until you open the cursor. The error occurs when you pass thevalues to a ct_param call for a cursor before the cursor open call.

Action

To find the source of the error, check your source code for thesequence of calls for a cursor and make necessary corrections. Theusual sequence is:

...ct_cursor ( ... CS_CURSOR_DECLARE ... ) .. definethe dataformat structure for input paramsct_param .. define parameters if any, but do notpass the valuesct_cursor ( ... CS_CURSOR_OPEN ... )ct_param .. pass the data values for eachparameter defined with the cursor declarect_sendct_results

The following code sample illustrates the sequence:



....#define RETURN_IF(a,b) if (a != CS_SUCCEED) \{fprintf(stdout,"error in %s\n",b); return a;}....

CS_RETCODE open_cursor ( cmd_ptr )CS_COMMAND *cmd_ptr;{CS_RETCODE ret ;int sales = 100;CS_DATAFMT datafmt ;

/* Declare the cursor for a SQL select statement** with input host variabvles ( if any ).*/ret = ct_cursor ( cmd_ptr, CS_CURSOR_DECLARE, "sel_cursor",CS_NULLTERM, "select title_id from pubs2..titles where \total_sales > @sales", CS_NULLTERM, CS_FOR_UPDATE );RETURN_IF ( ret, "ct_cursor: declare ");

/* define the dataformat structures for each input** parameters one by one.*/memset(&datafmt, 0, sizeof (datafmt));strcpy(datafmt.name, "@sales");datafmt.namelen = CS_NULLTERM;datafmt.datatype = CS_INT_TYPE;datafmt.maxlength = CS_UNUSED;datafmt.status = CS_INPUTVALUE;datafmt.locale = NULL;

/* Call ct_param to specify the input paramter defin-** ition, but pass the 'data' paramter as NULL.*/ret = ct_param(cmd_ptr, &datafmt, NULL,CS_UNUSED, CS_UNUSED) ;RETURN_IF( ret, "ct_param select");

/* Open the cursor */ret = ct_cursor ( cmd_ptr, CS_CURSOR_OPEN, NULL, CS_UNUSED,NULL, CS_UNUSED, CS_UNUSED );RETURN_IF ( ret, "ct_cursor: open "); ;

/* Call ct_param with the actual data values for the** input params.*/ret = ct_param(cmd_ptr, &datafmt, (CS_VOID *)&sales,sizeof(CS_INT), CS_UNUSED) ;



RETURN_IF( ret, "ct_param select");

/* Send the cursor command to the server */ret = ct_send ( cmd_ptr );RETURN_IF ( ret, "ct_send : cursors ");

/* Call the result processing routine */ret = handle_returns ( cmd_ptr ) ;RETURN_IF ( ret, "ct_results : cursors ");

....}





Passing parameters by name and position

Message Text

Number: (47) Severity (1) Layer (1), Origin (1)text: ct_param(): user api layer: external error:When defining parameters, names must be suppliedfor either all of the parameters or none of theparameters.

Possible Cause

When you define parameters for a RPC command or languagecommand using a ct_param call, you must define names for all theparameters, or none of them can be called by name. If you do notspecify names, the parameters are passed by position. The parametername is specified in the name field of the CS_DATAFMT structure.

The following example demonstrates how the error occurs. Thefollowing code defines two parameters for a command, the first withno name and the second with the name @price_param:

/* Define the first input parameter */datafmt.datatype = CS_CHAR_TYPE;...ct_param ( .... );/* Define the second input parameter */strcpy(datafmt2.name,"@price_param");datafmt2.namelen = CS_NULLTERM ;datafmt2.datatype = CS_FLOAT_TYPE;...ct_param ( .... );

If you then issue the command using two parameter names, @typeand @price, in the select list, you will trigger the error:

select title_id, type, pricefrom pubs2.dbo.titleswhere type = @type_paramand price >= @price_param

Action

To resolve the error, modify the dataformat structures for theparameters defined for a command so that either all of them or noneof them have parameter names defined. Do this for both input andoutput parameters.



The name you define for the parameter must be the same name usedby the stored procedure or language command for that parameter.The following example illustrates how to name parameters:

...ct_command ( .., CS_LANG_COMMAND ,"select select title_id, type, pricefrom pubs2.dbo.titleswhere type = @type_paramand price >= @price_param", .. );.../* Define the first input parameter */strcpy(datafmt.name,"@type_param");datafmt.namelen = CS_NULLTERM ;datafmt.datatype = CS_CHAR_TYPE ;datafmt.status = CS_INPUTVALUE ;...retcode = ct_param ( cmd_ptr, &datafmt,(CS_VOID *)type, strlen(type), CS_UNUSED);.../* Define the second input parameter */...strcpy(datafmt2.name,"@price_param");datafmt2.namelen = CS_NULLTERM ;datafmt2.datatype = CS_FLOAT_TYPE ;datafmt2.datatype = CS_CHAR_TYPE ;...retcode = ct_param ( cmd_ptr, &datafmt2, &price,sizeof(CS_FLOAT), CS_UNUSED);...

See the Adaptive Server Enterprise Reference Manual for more details onpassing parameters to stored procedures by name and position.





Bind resulted in truncation

Message Text:

Number: (132) Severity (1) Layer (1), Origin (4)text: ct_fetch(): user api layer: internal commonlibrary error: The bind of result set item %1resulted in truncation.

Possible Cause

This error occurs when you bind data to a host variable, specifyingthe size of the data in the maxlength field of the CS_DATAFMTstructure, then retrieve data using ct_fetch that is larger than the sizeyou specified.

If you are retrieving variable length data and maxlength is smallerthan the result data, no data is copied into the host variable andct_fetch returns a CS_ROW_FAIL for this row. If you specified anindicator variable at ct_bind time and truncation occurred, the lengthof the data is stored in the indicator variable.

Action

To resolve the problem, set the maxlength field of the CS_DATAFMTstructure large enough to accommodate larger data sizes. Use one ofthe following methods:

• Set the bind variable to the maximum value possible for thevariable length datatype. For character fields, you can setmaxlength to 255, as this is the maximum length for characterdata.

Call ct_describe to get the maxlength of the data (as well as other resultdata descriptions) before calling ct_bind. See the ct_describe page in theOpen Client Client-Library/C Reference Manual for more informationon this call.

• Set your dataformat.maxlength to the current maximum length ofa column. To find this value, log into the server with isql and issuethe following command:

1> select max(datalength( column_name ))2> from table_name3> go

Set your dataformat.maxlength to this value, plus 1 (for the nullterminator). This value can change as the data in the tablecolumn changes.



➤ NoteThe maxlength field is ignored for fixed length datatypes defined in the

CS_DATAFMT structure.

Specify an indicator variable for each item bound to a host variable.Specify the indicator variable at ct_bind time so that, when data isfetched into the corresponding host variable, information about thedata can be stored in the indicator variable. A value greater than 0contained in the indicator variable is the length of the data andindicates that data truncation has occurred. You can set maxlength tothe value in the indicator variable, plus 1 (for the null terminator).See the Open Client Client-Library/C Reference Manual section onct_bind for more details.





Read from the server has timed out

Message Text

Number: (63) Severity (2) Layer (1), Origin (2)text: ct_results(): user api layer: internalClient Library error: Read from the server hastimed out.

Possible Cause

The time set by the Client-Library application to wait for a serverresponse to either a command or login attempt has elapsed.

By default, the timeout value for commands is CS_NO_LIMIT; thatis, Client-Library waits indefinitely for a response from the server ona command request. However, you can limit the time an applicationwaits for a response by setting the CS_TIMEOUT property in theapplication or in a runtime configuration file.

A timeout during command processing indicates that theapplication’s request is blocked because the server is executing arequest from another session or connection that requires an exclusivelock on the page or table.

The error can also occur on a login request. The default timeout valuefor a server login is 60 seconds. The application can increase ordecrease this time with the CS_LOGIN_TIMEOUT property. Theerror occurs when the server does not respond within the specifiedtime to a login request made by the ct_connect call.

For example, the timeout error on login can occur when the servermachine is down. Because “no response” is not considered an error,the network does not signal the client that an error has occurred.However, if a login timeout period has been set withCS_LOGIN_TIMEOUT, an error will occur when the client fails toreceive a response within the set period.

The error can also occur when you have network problems.



➤ NoteIf the server machine is up and running, but the server is not, you get a

different error. If no server is listening on the specified port, the server

machine signals the client, via a network error, that the connection cannot

be formed. The connection fails regardless of the CS_LOGIN_TIMEOUT

value. See the section “Call to connect two endpoints failed” for information

about this error.

Action

Check your application to see if the timeout period set is appropriatefor you. You can code your application to trap the error and wait formultiple timeout periods, or to cancel the command that got theerror and continue with the rest of the processing.

You can call ct_con_props with the CS_LOGIN_STATUS property todetermine if the error was caused by a login timeout or during acommand processing. A value of CS_TRUE means that the servertimed out during command processing. The following codeillustrates how to trap a timeout error on a command, and one wayto handle the error:

....if (CS_NUMBER(client_msgtxt->msgnumber) == 63 ){printf("A TIMEOUT ERROR OCCURRED. Please choose ");printf("one of the following options:\n");printf("1. Cancel only this command and continue \processing. \n");printf("2. Wait for another timeout period. \n");printf("\n\n Enter choice: "); scanf("%d",&ans);if ( ans == 1 ){retcode = ct_cancel(conn, NULL, CS_CANCEL_ATTN);if (retcode == CS_SUCCEED )printf("Command cancelled! ..\n");/* You must return CS_SUCCEED from the** callback, otherwise the connection will be** marked dead.*/return CS_SUCCEED ;}else if ( ans == 2 )



{printf("Waiting for another timeout period \n");return CS_SUCCEED ;}}....

See the Open Client Client-Library/C Reference Manual section on“Handling Timeout Errors” for more details.

• If you do not wish to wait for locks to be released on the serverand wish to allow dirty reads, you can set the transactionisolation level to 0. You can set this option using ct_command withthe command buffer:

set transaction_isolation level 0

Alternatively, call ct_options and set the buffer toCS_OPT_LEVEL0.

See the Adaptive Server Enterprise Performance and Tuning guide fordetails and cautions on the use of transaction isolation levels.

◆ WARNING!Isolation level 0 allows transactions to read uncommitted data andshould only be used when the accuracy of your read is not an issue.

• For login timeout errors, check the interfaces file entry for thisserver to get the machine name, than issue a telnet to that machineto see if it up and running. Check with your networkadministrator to see if there are any network problems.





Connection has been marked dead

Message Text

Number: (50) Severity (1) Layer (1), Origin (1)text: ct_xxxxx: user api layer: external error:The connection has been marked dead.

where “ct_xxxxx” is the first API to be called in the application afterthe connection has been marked dead.

Possible Cause

The most common reason for a connection to be marked dead is areturn code of CS_FAIL from the Client-Library or server messagecallback routines.

Even when the application does not explicitly return a CS_FAIL fromthe error callback routines, Client-Library can return a CS_FAIL if itdoes not t find enough memory to allocate for the error. This is a rareoccurrence, but it is possible even if you use inline error handling(ct_diag) in place of callbacks.

Action

To resolve the problem, take following actions as appropriate:

• Check your Client-Library and server error callback routines andverify that they always return CS_SUCCEED.

• If you are using inline error handling and a timeout error occurs,by default, Client-Library does not retry the read and marks theconnection dead. To make Client-Library retry the read, set theCS_DIAG_TIMEOUT property to CS_FALSE. If you usecallbacks, Client-Library retries the read on timeout errors as longas the callback routine returns CS_SUCCEED.

• If the connection has been marked dead because of a resultprocessing error, try calling ct_cancel with a type ofCS_CANCEL_ATTN or CS_CANCEL_ALL to revive theconnection. If this fails, the application must close the connectionand drop its CS_CONNECTION structure.





CS_IODESC only for text or image columns

Message Text

Number: (97) Severity (1) Layer (1) Origin (1)text: ct_data_info(GET): user api layer: externalerror: A CS_IODESC can only be retrieved for textor image columns. Column %1! is not a text orimage column.

Possible Cause

The application is making a call to ct_data_info to retrieve a CS_IODESCfor a non-text or non-image column. The CS_IODESC structuredescribes text or image data only.

Action

Check the column number specified in the ct_data_info call and verifythat it is a text or image column.

To do this, log into the server with isql and enter:

sp_help table_name

Compare the column information with your select statement to verifythat the column you are selecting is a text or image column. Thencompare the position of the column in the select statement with thecolumn number in the ct_data_info call. The column number in thect_data_info call is the position of the item in the select statement, not inthe table.

For example, the BIGTABLE table is defined as:

create table BIGTABLE(item_no int,item varchar(255),descr image,notes text)

The select statement in the application is:

SELECT item_no, notes, descrfrom BIGTABLE

You can make a ct_data_info call only on columns 2 and 3, but not oncolumn 1, which is of integer type, as shown here:



CS_COMMAND *cmd;CS_IODESC *des;...retcode = ct_data_info(cmd, CS_GET, 2, &des);...retcode = ct_data_info(cmd, CS_GET, 3, &des);...





CS_IODESC cannot be retrieved

Message Text

number (98) severity (1) layer (1), origin (1)text: ct_data_info(GET): user api layer: externalerror: A CS_IODESC cannot be retrieved for acolumn that has not been read. Column %1! has notbeen read.

Possible Cause

Before the application makes a call to ct_data_info to retrieve the I/Odescriptor for a text or image column, it must first select the columnand row by making a call to ct_get_data. The above error occurs whenyou skip this step.

Action

To resolve the problem, verify that your application does thefollowing:

• Makes a call to select the column and row, where the column isthe text or image column to be updated and the row, selected bythe WHERE CLAUSE, is the row in which the text or imagecolumn is to be updated.

• Calls ct_fetch to fetch the row.

• Calls ct_get_data to retrieve the column’s value and refresh the I/Odescriptor. If you wish, you can refresh the I/O descriptorwithout getting the column value by setting the buflen parameterto 0.

• Calls ct_data_info to retrieve the I/O descriptor into the CS_IODESCstructure.

The following code fragment illustrates this:

.....CS_RETCODE retcode;CS_COMMAND *cmd;CS_IODESC des;

.....ct_command( ...., "select intcol,image_col from tablex", ....);

...../* Retrieve and display the results. */while(((retcode = ct_fetch(cmd, CS_UNUSED,CS_UNUSED, CS_UNUSED, &count)) == CS_SUCCEED)



|| (retcode == CS_ROW_FAIL) ){

...../* Refresh the I/0 descriptor for the image col */retcode = ct_get_data(cmd, 2, Data, 0, NULL);

...../* Retrieve the descriptor of the image data.** It is available only after the column has*/ been fetched.

retcode = ct_data_info(cmd, CS_GET, 2, &des);.....

}.....

See the Open Client Client-Library/C Reference Manual section on “textand image Data Handling” and the reference pages for ct_get_data andct_data_info for more details. See also the sample program getsend.c,which comes with the Open Client/C product. The sample is locatedin the $SYBASE/sample/ctlibrary directory. This is a complete Client-Library program that shows how to retrieve and update text or imagedata.





CS_IODESC structure must be set

Message Text

number (92) severity (1) layer (1), origin (1)text: ct_send_data(): user api layer: externalerror: A CS_IODESC structure must be set withct_data_info() before ct_send_data() can be called.

Possible Cause

The I/O descriptor contains the text pointer and timestamp valuethat the server uses to manage updates to text and image columns.Before a call is made to send the new value for the update, theapplication must define the size of the new value in bytes andindicate whether the server should log the update.

The server uses this information to update the requested text or imagecolumn. The error occurs when this information is not available atthe time of the ct_send_data call.

Action

Check your code and ensure that ct_data_info is being called to set theI/O descriptor before calling ct_send_data. Verify that your applicationdoes the following before sending the new value for the update:

• Calls ct_command to initiate a command for the update.

• Modifies the I/O descriptor as required. Usually, you only needto modify the total_txtlen and possibly the log_on_update fields.

• Calls ct_data_info to set the I/O descriptor for the column to beupdated.

After performing these steps, call ct_send_data to write the new value.The following code fragment illustrates this sequence:

.....CS_RETCODE retcode;CS_COMMAND *cmd;CS_IODESC des;CS_TEXT *txtptr;CS_INT txtlen;...../* Inform Client-Library the next data sent will be** used for a text or image update.*/retcode = ct_command(cmd, CS_SEND_DATA_CMD, NULL,CS_UNUSED,



CS_COLUMN_DATA);...../* Fill in the description information for** the update and send it to Client-Library.*/txtptr = (CS_TEXT *)"This is the new update value";txtlen = strlen((CS_CHAR *)txtptr);des.total_txtlen = txtlen;des.log_on_update = CS_TRUE;retcode = ct_data_info(cmd, CS_SET,CS_UNUSED, &des);..... /* Check retcode status */retcode = ct_send_data(cmd, txtptr, txtlen);.....

See the Open Client Client-Library/C Reference Manual section on “textand image Data Handling” and the reference pages for ct_data_info andct_send_data for more details. Also see the sample getsend.c, which isshipped with the Open Client/C product. The sample is in the$SYBASE/sample/ctlibrary directory. This is a complete Client-Libraryprogram that shows how to retrieve and update text or image data.





Bytes exceeds the amount specified

Message Text

Number: (93) Severity (1) Layer (1) Origin (1)“%1! bytes exceeds the amount of bytes specifiedfor this send data operation. Only %2! more bytescan be sent.”

Possible Cause

The error occurs when the application calls ct_send_data to send to theserver text or image data whose size in bytes is greater than the valuespecified in the total_txtlen field of the CS_IODESC structure.

For example, if you wish to send text data whose size is 38 bytes, butthe application is coded like the fragment below, you will get aruntime error:

....CS_INT txtlen;CS_IODESC des;CS_TEXT *textdata;CS_CHAR *newdata;....strcpy(newdata,"This is the new text valuefor update.");txtlen = strlen((CS_CHAR *)textdata);des.total_txtlen = 10;retcode = ct_data_info(cmd, CS_SET,CS_UNUSED, &des);.... /* Check retcode value */retcode = ct_send_data(cmd, newdata, txtlen);.... /* Check retcode value */retcode = ct_send (cmd);....

The error occurs because the total_txtlen field in the CS_IODESCcontains the value 10, but the actual data being sent to the server is 38bytes, the value of txtlen.

Action

Check your code for the value of the total_txtlen field of theCS_IODESC structure. Compare this with the length specified in thect_send_data call.

You can choose to send all the data in one chunk or break up the dataand call ct_send_data in a loop until all of the data has been sent to the



server. If all of the text or image data is being sent in one chunk, thelength specified in the ct_send_data call must be equal to the valuespecified in the total_txtlen field. All the data must be sent to theserver, either in one or multiple chunks, before the ct_send commandsignals the end of the update.

The example can be corrected as follows:

.....strcpy(newdata,"This is the new text valuefor update.");txtlen = strlen((CS_CHAR *)textdata);des.total_txtlen = txtlen;retcode = ct_data_info(cmd, CS_SET,CS_UNUSED, &des);.... /* Check retcode value */retcode = ct_send_data(cmd, newdata, txtlen);.... /* Check retcode value */retcode = ct_send (cmd);....

See the Open Client Client-Library/C Reference Manual page onct_send_data for more details, including a code sample that callsct_send_data in a loop to send data in chunks. The complete samplecan be found in getsend.c located in your $SYBASE/sample/ctlibrarydirectory.





Bytes specified have not been sent

Message Text

Number: (94) Severity (1) Layer (1), Origin (1)text: ct_send(): user api layer: external error:The number of bytes specified for this send dataoperation have not been sent. %1! more bytes needto be sent.

Possible Cause

The application has called ct_send to write text or image data to theserver before ct_send_data sent all the bytes specified in the total_txtlenfield of the CS_IODESC structure.

For example, if you wish to send text data whose size is 38 bytes, butthe application is coded like the fragment below, you will get aruntime error:

CS_INT txtlen;CS_IODESC des;CS_CHAR *newdata;....strcpy(newdata,"This is the new text valuefor update.");txtlen = strlen(newdata);des.total_txtlen = 100;retcode = ct_data_info(cmd, CS_SET,CS_UNUSED, &des);.... /* Check retcode value */retcode = ct_send_data(cmd, (CS_TEXT *)newdata,txtlen);.... /* Check retcode value */retcode = ct_send (cmd);....

The error occurs because the total_txtlen field in the CS_IODESCcontains the value 100, but the actual data being sent to the server is38 bytes, the value of txtlen.

Action

Check your code for the value of the total_txtlen field of theCS_IODESC structure. Compare this with the length specified in thect_send_data call.

You can choose to send all the data in one chunk or break up the dataand call ct_send_data in a loop until all of the data has been sent to the



server. If all of the text or image data is being sent in one chunk, thelength specified in the ct_send_data call must be equal to the valuespecified in the total_txtlen field. All the data must be sent to theserver, either in one or multiple chunks, before the ct_send commandsignals the end of the update.

The example can be corrected as follows:

.....strcpy(newdata,"This is the new text valuefor update.");txtlen = strlen((CS_CHAR *)textdata);des.total_txtlen = txtlen;retcode = ct_data_info(cmd, CS_SET,CS_UNUSED, &des);.... /* Check retcode value */retcode = ct_send_data(cmd, newdata, txtlen);.... /* Check retcode value */retcode = ct_send (cmd);....

See the Open Client Client-Library/C Reference Manual page onct_send_data for more details, including a code sample that callsct_send_data in a loop to send data in chunks. The complete samplecan also be found in getsend.c located in your$SYBASE/sample/ctlibrary directory.





ID already exists on connection

Message Text

Number: (134) Severity (1) Layer (1), Origin (1)text: ct_dynamic(PREPARE): user api layer:external error: The specified id already exists onthis connection.

Possible Cause

Every Dynamic SQL call made by Client-Library has a statementidentifier. The identifier name is specified by the application duringa call to ct_dynamic with CS_PREPARE as the action type. The id, oridentifier parameter, for this call must be unique so that thestatement can be identified by the server and application.

If you call ct_dynamic with CS_PREPARE as the action type and id setto an existing identifier name, you get this error.

Action

To resolve the problem, take one of the following actions asappropriate:

• If you are using multiple prepare statements in your application,check the id parameter of each ct_dynamic call with an type ofCS_PREPARE to be sure that you are using a unique id parameterfor every statement on a given connection.

If you want to use the same id for a second CS_PREPARE call,deallocate the first Dynamic SQL statement by calling ct_dynamicwith type CS_DEALLOC. Verify that the call returnsCS_SUCCEED.

➤ NoteEach prepared SQL statement is a temporary stored procedure, compiled

and stored by the server until it is explicitly deallocated or the connection is

closed. Applications make connection requests quickly, and a new

connection might make a request for an id before the server has cleaned up

a previous connection for that id. Therefore, you may want to explicitly

deallocate statements rather than relying on the server to do it for you.

• If your application is already making a call to deallocate theprepared statement before issuing a new one with the same id,verify that the statement has been deallocated by the server.



Because dynamic objects are temporary, the stored procedure iscreated in the tempdb database. Log into the server with isql andissue the following query:

1> use tempdb2> go

1> select name from sysobjects2> where name like identifier_name3> go

The following example shows how this works. The call toprepare a statement looks like this:

....retcode = ct_dynamic(cmd_ptr, CS_PREPARE,"d_insert",strlen("d_insert"), insert_statement, CS_NULLTERM);RETURN_IF(retcode, "ct_dynamic: prepare failed");....

The id for the prepared statement is “d_insert”. To see if thisstatement was deallocated, log into the server and issue thefollowing query:

1> select name from tempdb..sysobjects2> where name like %d_insert%3> go

If the statement is not deallocated, you see this output:

name------------------------------#P$$000010022629487_d_insert

(1 row affected)

All Dynamic SQL statement names in the server begin with a “#”(pound sign), which denotes a temporary object. The id suppliedby the application appears at the end of the string.

If possible, restart the server to remove these objects.

➤ NoteAn incomplete cleanup can occasionally be the result of a bug. If you have

checked your application and verified that the error is not in the application

code, or you have restarted the server and the problem returned, call

Technical Support.







ID does not exist

Message Text

Number: (135) Severity (1) Layer (1), Origin (1)text: ct_dynamic(EXECUTE): user api layer:external error: The specified id does not exist onthis connection.

Possible Cause

Every Dynamic SQL call made by Client-Library has a statementidentifier. The identifier name is specified by the application duringa call to ct_dynamic with CS_PREPARE as the action type. This erroroccurs when an invalid id is used by a call to ct_dynamic of typeCS_EXECUTE, CS_DESCRIBE_INPUT, CS_DESCRIBE_OUTPUT orCS_DEALLOC. An invalid id can result when:

• You fail to specify a statement id in a call to ct_dynamic of typeCS_PREPARE before calling ct_dynamic of type CS_EXECUTE,CS_DESCRIBE_INPUT, CS_DESCRIBE_OUTPUT, orCS_DEALLOC.

• A ct_dynamic call uses a name different than the one specified inthe CS_PREPARE. Names are case sensitive.

• The length parameter of the identifier is incorrect.

• The prepared Dynamic SQL statement has already beendeallocated.

Action


• Verify that you are making a call to ct_dynamic with a type ofCS_PREPARE and that you are creating the Dynamic SQLstatement correctly before making a call to execute the statement,describe input or output data, or deallocate the statement.

• Verify that the idlen parameter passed to every ct_dynamic call(including CS_PREPARE) is accurate. Use a strlen of the identifieror CS_NULLTERM.

• Verify that the ct_dynamic calls are made on the same connection asthe one on which the statement was created. Also check to seethat the connection still exists, since the prepared statement isautomatically dropped by the server when that connection to theserver is closed.




Client-Library 10.0.x and later.





Sticky binds do not match result set

Message Text

Number: (184) Severity (0) Layer (1), Origin (1)text: ct_results(): user api layer: externalerror: The sticky binds do not match the currentresult set. The sticky binds have been discardedfor all result sets.

Possible Cause

If an application sets the command property CS_STICKY_BINDS toTRUE, Client-Library preserves all bindings for all result setsreturned by the first execution of a command. It then uses thesebindings for future executions of the same command within theapplication. After each execution of the command, a call to ct_resultscompares the current result format to that saved earlier. If ct_resultsfinds a mismatch, it displays this warning and clears all bindings.ct_results returns CS_SUCCEED, as this is only an informational errormessage.

Result formats for the same command can only vary if one of theseconditions exists:

• The SQL statement or stored procedure contains conditionalserver-side logic, such as an if or while clause.

• The definition of the stored procedure changes during multipleexecutions of the command.

• The table definition changes during multiple executions of thecommand. For example, this command:

select * from table_name

could return varying result sets if the table definition changesbetween iterations of the command.

Action


• Log on to the server with isql and check to see if the definition ofthe stored procedure or table has changed between iterations.

To get the table or procedure definition, issue one of thesecommands:

1> sp_help table_name2> go



or:

sp_helptext procedure_name2> go

• If the definitions have not changed, check the logic of the SQLstatement or stored procedure text. Are there conditions underwhich a different row format could be returned? If this is true,change the select list so that the results are in the same format asthe first row that is retrieved from the first execution of thecommand. If the row formats are not guaranteed to be the samein your scenario, do not use the CS_STICKY_BINDS feature.


• Client-Library 11.x and later.



Error while binding to directory service

Message Text

Number: (1) Severity (5) Layer (6), Origin (8)text: ct_connect(): directory service layer:internal directory control layer error: There wasan error encountered while binding to thedirectory service.

Possible Cause

Client Library 11.x provides alternatives to a Client-Libraryapplication for looking up an Adaptive Server, SQL Server, or OpenServer. In past versions, Sybase clients located the server they wishedto connect to by looking up the network address in the interfaces file,called sql.ini on PC platforms. With version 11.x, Client-Librarysupports other directory services such as DCE. A directory servicemanages the creation, modification, and retrieval of informationabout network entities. Client-Library 11.x applications can use thisservice as an alternative to the interfaces file to obtain informationabout servers.

By default, a Client-Library application attempts to locate the servervia the interfaces file. However, if the libtcl.cfg file, located in the$SYBASE/config (UNIX, VMS) or SYBASE/ini (NT) directory, listsanother directory service, Client-Library attempts to use thatdirectory service. If that service does not exist or can not be located inthe specified location, this error occurs. The error also occurs if theinterfaces or sql.ini file can not be located.

Action

Take one of the actions described in the following sections.

If you are using the interfaces or sql.ini file

If your application uses the standard mode of locating servers, theinterfaces file, verify that your SYBASE variable is pointing to thecorrect location for your Sybase directory. By default, Client-Libraryapplications look for a file called interfaces or sql.ini in the directorypointed to by the SYBASE environment variable. If SYBASE has notbeen set, at connect time Client-Library will look for a file calledinterfaces in the home directory of the “sybase” user.

If you wish to use an interfaces file from a different location, yourClient-Library application must call ct_config to set the CS_IFILEproperty. This property allows you to specify the location of the



interfaces file that you wish to use for this application. For example,if you wish to use the interfaces file from the directory/usr/u/sybase11, you might code your application as follows:

....CS_CONTEXT*cntx_ptr;CS_RETCODEretcode;

....retcode = ct_config( *cntx_ptr, CS_SET, CS_IFILE,"/usr/u/sybase11/interfaces", CS_NULLTERM, NULL );

....

If you wish to use the interfaces file from the SYBASE directory andhave verified that the variable is pointing to the correct location,check your libtcl.cfg file located in the config or ini subdirectory underSYBASE.

Depending on your operating system, you will see a line similar to:

[DIRECTORY];dce=libddce.so ditbase=/.:/subsys/sybase/dataservers

The word DIRECTORY within square brackets denotes the directoryservices section of the libtcl.cfg file. The semicolon (;) denotes acomment. In this example, the dce directory service entry iscommented out, as it should be when you use the interfaces file. Ifyour entry is not commented out with a semicolon as in the example,add a semicolon before the entry.

If you are using DCE services

If you are using DCE services, you can get the error when the DCEdirectory service entry can not be located in the directory servicessection in the libtcl.cfg file. Edit the entry in the libtcl.cfg file to point toyour DCE service. Refer to the Open Client/Server Configuration Guidefor your platform for details on configuring DCE entries.

A directory service can also be specified from within the Client-Library application by setting the CS_DS_PROVIDER property inthe ct_con_props call. See the Open Client Client-Library/C ReferenceManual chapters on “Directory Services and Properties” for moreinformation.



➤ NoteClient-Library falls back to the interfaces file to obtain the server’s address

if any of the following are true:

- The file libtcl.cfg does not exist in the config or ini subdirectory.

- There are no uncommented entries in the [DIRECTORY] section of the

libtcl.cfg file.

-The specified directory driver exists but fails to load.

See the Release Bulletin for your platform to find out which directoryservices Sybase supports. To find out which directory services yourplatform supports, contact your System Administrator or youroperating system documentation or vendor.


• Client-Library 11.x and later.



Attempt to load protocol driver failed

Message Text

Number: (4) Severity (5) Layer (5), Origin (3)text: ct_connect(): network packet layer: internalnet library error: Attempt to load protocol driverfailed

Possible Cause

This error occurs when Client-Library cannot load the networkdriver because the Net Library driver doesn’t exist or you havespecified an incorrect driver.

The Sybase network library, Net Library, interacts with the networkat the operating system level. Only certain drivers are supported onspecific platforms. See the Open Client/Server Configuration Guide foryour platform for platform-specific drivers.

Action

To resolve the problem, first verify that you have the correct networklibrary for your platform and version:

• If you have Client-Library 10.0.x, check the $SYBASE/libdirectory to verify that you have the right network library andthat the drivers are correctly linked. Network transport driversinclude:

• Client-Library 11.x supports dynamic loading of Net-Libraryservices. This allows you to change the driver that an applicationuses and to use features as they become available withoutrelinking the application. Client-Library 11.x looks in the[DRIVERS] section of libtcl.cfg to determine which network driverto load. This file is located in the $SYBASE/config directory. Seethe Open Client/Server Configuration Guide for your platform for a

Driver Platform

libtli.so or libtli.a for tli Sun Solaris

libinsck.sl or libinsck.a for tcp HP 9000

libinsck.so.a or libinsck.a for tcp RS/6000



list of valid network protocols and instructions on adding ormodifying a network driver. Network transport drivers include:

➤ Note11.x only provides for dynamic loading of the Net- Library drivers, whereas

10.x provided a statically linked version of the driver as well.

This element must match the protocol of the driver. For example,you cannot use a tcp protocol with a tli driver.

See the Open Client/Server Configuration Guide a complete list ofdriver/protocol mappings for UNIX and desktop platforms.

Example

The following example shows how to correct the error in theibtcl.cfg file. You can find this file in the $SYBASE/config orSYBASE/ini (NT) directory. In this example, the error occursbecause you are using the standard Sybase 11.x non-threadedlibraries, or isql or bcp 11.x, but your DRIVER entry in the libtcl.cfgfile reads:

[DRIVERS];libtli.so=tcp unused ; This is the non-threaded tli driver.libtli_r.so=tcp unused ; This is the threaded tli driver.

You have incorrectly specified the threaded tli driver, which isincompatible with the other non-threaded libraries used to buildyour application or with the standard utilities that have beenstatically linked with the non-threaded libraries.

You can correct the error by commenting out the threaded driverentry by placing a “;” (semicolon) in the first column, so that theentry reads:

;libtli.so=tcp unused ; This is the non-threaded tli driver.;libtli_r.so=tcp unused ; This is the threaded tli driver.

By default, both lines under the [DRIVERS] section arecommented, so that the application uses the default driver listed

Driver Platform

libtli.so for tli Sun Solaris

libinsck.sl for tcp HP 9000

libinsck.so.a for tcp RS/6000



in the table. Commenting both lines is the same asuncommenting the non-threaded driver line.






4 DB-Library Error Messages 4.

This chapter includes information on common error messagesreturned by DB-Library.

All DB-Library error messages have numbers and severity levels.Error numbers and severity levels have corresponding key wordsdefined in DB-Library; these appear next to the numbers in thischapter. For example, the following entry:

Error Number

20009 (SYBECONN)

means that you can use the key word “SYBECONN” in yourprograms to identify Error 20009.

For a listing of all DB-Library errors, including number and severity,see the files sybdb.h and syberror.h in the SYBASE/include directory.

Page -2 DB-Library Error Messages


SQL Server connection timed out

Error Number

20003 (SYBETIME)

Severity

6 (EXTIME)

Message Text

SQL Server connection timed out.

Possible Cause

This error occurs when the number of seconds specified by a DB-Library application for the server to send back results has elapsed.Usually, the server sends back results immediately after processing aquery. However, it is possible that a resource required by theapplication is locked by another connection to the database. If notimeout interval is set by the application, it will wait indefinitelyuntil the lock is released.

Action


• By default, DB-Library will wait indefinitely for results. Theroutine dbsettime lets you specify a timeout period. You can thencode the error handler to retry the timed-out command, cancel itand proceed with the rest of the processing, or exit the applicationby closing the DBPROCESS. See the page for dberrhandle in theOpen Client DB-Library/C Reference Manual for various codes thatcan be returned when you get a timeout error.

• You can use dbsqlsend to send a command to the server rather thandbsqlexec. After sending a query to the server, dbsqlexec waitsuntil a response is received or until the timeout period haselapsed. However, using the sequence dbsqlsend, dbpoll and dbsqlokinstead of dbsqlexec lets your application respond more effectivelyto multiple input and output streams so it can do other thingswhile waiting for the server to return results. See the page ondbsqlok in the Open Client DB-Library/C Reference Manual for anexample.

• Try to minimize timeouts in general by completing transactionsquickly. Keeping a transaction open until the end of an



application will cause locking issues for other users who need toaccess the same tables.

• To see which connection is blocking your query, log on to theserver with isql and issue the command sp_who. The outputcolumn blk shows you which spid is causing the problem. Thecommand sp_lock tells you what kind of locks are being held onthe table. Contact your Sybase system administrator to helpidentify the user and process causing the block.

If your application is the one blocking itself, check your codeand see if you have an open transaction on a different connectionwhich occurs prior to the blocked command and which uses thesame tables. If so, have the first transaction complete beforeissuing the second command, or try to issue the commands onthe same connection. See Error 20019, “Results pending”, for anexample.

• For reads, if you do not want to wait for locks to be released andare willing to get dirty reads—that is, reads of data that may be inthe process of changing—you can set the transaction isolationlevel to 0. You can set this option by issuing this command:

set transaction_isolation level 0

See the section on transaction levels in the Adaptive ServerEnterprise Reference Manual for complete information on thevarious isolation levels.

◆ WARNING!Using isolation level 0 may cause you to read inconsistent data.


DB-Library/C 4.x and later



Read from SQL Server failed

Error Number

20004 (SYBEREAD)

Severity

9 (EXCOMM)

Message Text

Read from SQL Server failed.

Possible Cause

This error occurs when the server does not respond to the client’srequest for communication, for instance when the server is down orhung, or there is a network problem. This error can only occur after aconnection has already been established. For example, if you make aSQL request to the server, but the server is shut down before it canreturn results, DB-Library raises the error and marks theDBPROCESS making the request as dead, making the structureunusable for any future requests.

The following example illustrates the general timing of this error. Inthe example, the DBPROCESS is valid when a SQL request goes tothe server, but the server or the network goes down before the servercan return results:

.....DBPROCESS *dbproc;

...../* Frame the sql command. */dbcmd(dbproc, "select * from publishers ");

...../* Send the command to the server but don't** wait for a response.*/if (dbsqlsend(dbproc) == FAIL)

...../* Check for results from the server with dbsqlok.** If successful, process results with dbresults.** If a network error occurs or the server goes** down at this point, dbsqlok returns FAIL and** the program calls the installed error handler.*/if (dbsqlok(dbproc) == FAIL)

.....



Action


• Code your error handler as in the following example:

int err_handler(dbproc, severity, dberr, oserr,dberrstr, oserrstr)

.....{

if ((dbproc == NULL) || (DBDEAD(dbproc))){

printf("DBPROC is dead or null. Thisdbprocess will be killed. \n");

return(INT_EXIT);else/* Print errors and return INT_CANCEL */

.....}

If the DBPROCESS has been marked as NULL, you have toreestablish your connection to the server.

• Check to see whether the server went down unexpectedly. Youmay also see the accompanying error ‘‘Unexpected EOF fromSQL Server’’.

• Check for corresponding errors in the server log.

• Have your network administrator check for possible networkissues.

• If the error usually seems to occur after the execution of aparticular query, check the server log for the SQL causing error.

• If you believe the problem is caused by a SQL command but arenot sure which one, make a call to dbrecftos in your application torecord all SQL sent to the server. See the error “General SQLServer error” in this manual for an example using dbrecftos.





Unable to open socket

Error Number

20008 (SYBESOCK)

Severity

None

Message Text

Unable to open socket.

Possible Cause

The following are the most common causes of this error:

• The error can occur when you call dbopen if a lack of operatingsystem resources prevents DB-Library from opening aconnection. It is usually accompanied by an operating systemerror, such as the following UNIX error:

OS error 24: too many files open.

This error is defined as EMFILE in the /usr/include/sys/errno.h fileon most UNIX operating systems. It might occur if yourapplication leaves a lot of connections open at the same time,causing the operating system to run out of file descriptors.

• The error might occur because the operating system thinks thatyou are trying to bind to an address that is already in use. Thiscan happen if you have an application that opens and closesmany connections very quickly. Although you may have calleddbclose to close a connection, the operating system may not haveyet released that resource for reuse.

• The error can be caused by an invalid interfaces file entry for theserver your application is attempting to connect to. Invalidinterfaces file entries can cause several errors, but in this case, theerror is due to an incorrect network address.

For a similar error, see Error 1605 in the Adaptive Server EnterpriseTroubleshooting and Error Messages Guide.

Action




• Reduce the number of simultaneous connections in yourapplication. You may need to close connections when they are notbeing used and reopen them later.

• If you cannot decrease the number of simultaneous connectionsopened by your application, increase the number of filedescriptors at the operating system level. This will increase thenumber of connections that you can open in your application.

First check the current value of the soft and hard file descriptorlimits. To check the soft limit, which is configurable by the user,type one of the following commands at the UNIX operatingsystem prompt:

% limit descriptors (C shell)

$ ulimit -n (Bourne shell)

To display the current hard limit, the maximum valueconfigured by the operating system administrator, type one ofthe following commands at the operating system prompt:

% limit -h descriptors (C shell)

$ ulimit -Hn (Bourne shell)

To increase the soft limit on UNIX, type the following commandat the operating system prompt:

% limit descriptors n (C shell)

$ ulimit -S n new_value (Bourne shell)

where n is the current value for the soft limit, and new_value isthe value to which you want to increase the soft limit.

➤ NoteYou can use Sybase CentralTM to read the o/s file descriptors parameter,

which tells you how many file descriptors have been allotted by the

operating system to Adaptive Server, but you cannot use this tool to change

the parameter’s value.

• If you are getting system errors indicating that addresses arealready in use, for example, on VMS with Pathworks, check withyour system administrator to see whether you can configuresystem parameters so that the operating system releases socketswith no delay. You can also try adding a small delay after everydbclose call.



• If you get the error on the very first call to dbopen, then theproblem is probably in the interfaces file. Be sure to use a Sybase-supplied tool such as sybinit, for pre-11.x releases, or dsedit, forOpen Client 11.x, to make entries to the interfaces file. Do notcopy an interfaces files from another machine, especially onewith a different operating system, as the network protocol couldbe different. If the client is on a different machine than the server,create the interface entry on the client machine. See the section“Related Interfaces File Errors” in the writeup for the error “SQLServer is unavailable or does not exist”





SQL Server is unavailable or does not exist

Error Number

20009 (SYBECONN)

Severity

9 (EXCOMM)

Message Text

Unable to connect: SQL Server is unavailable ordoes not exist.

Possible Cause

This error is raised when connection to the server has failed, or, thecurrent DBPROCESS is dead. Possible reasons include:

• The Server is not running. The error can occur if the server is notrunning at the start of the application, when it makes a dbopen call,or if the server goes down later and the application makes a callto connect.

• The application requests an incorrect server name. The servername can be the value of the DSQUERY environment variable orit can be specified in the application's dbopen function call.

• The interfaces file contains incorrect server information.

• The SYBASE environment variable does not point to the correctinterfaces (UNIX) or sql.ini (NT) file.

Action

To resolve the problem, take the following steps:

1. Check whether the server is still running.

On UNIX platforms, use the showserver command:

$SYBASE/install/showserver

On NT, check the console for the server process. Or simply tryconnecting to the server. Restart the server if necessary.

2. If your DB-Library program does not explicitly set the name ofthe server that you wish to connect to in the dbopen call, DB-Library uses the value of the DSQUERY environment variable.Verify that this variable is set to the correct server name. Forexample, on UNIX platforms, issue the command:



% echo $DSQUERY

To set the value, issue the command:

% setenv DSQUERY server_name

where server_name is the correct name of your server.

3. Check the program to see if it explicitly requests a server as partof the dbopen call. Look for an entry like this:

dbopen(dbproc, "SYBASE");

Verify that the server name is correct. If you want the applicationto use the value of DSQUERY instead, change the dbopen call to:

dbopen(dbproc, NULL);

➤ NoteIf you do not set the server name in the program or DSQUERY environment

variable, DB-Library looks for a server named “SYBASE”.

4. DB-Library uses the interfaces file to locate the server requested.If you are sure that the server name is correct, verify that theapplication can find the correct path to the interfaces file:

- Check the SYBASE environment variable. It should point to thedirectory where your current version of the software isinstalled. Verify that the interfaces file exists in this directory.

- Check the application for a dbsetifile command. This commandtells the application to look for the interfaces file in an alternatelocation. If this command exists in the application, verify thatthe interfaces file can be found in this path.

5. Check the information contained in the interfaces file to verifythat the following information is correct:

- Server name

- Machine name

- Port number

➤ NoteThe UNIX commands given in this section are C-shell (csh) commands. If

you are using a different UNIX shell check your operating system

documentation for the appropriate commands.



Related Interfaces File Errors

Other error messages referring to problems with the interfaces fileinclude the following:

• Network information for a server is not formatted correctly withtabs or is in the wrong format for the network protocol:

Severity: 2, Error No: 20055.Unknown network type found in interface file.

• Server name is not listed in the interfaces file:

Severity 2, Error No: 20012.Server name not found in interface file.

• The interfaces file does not exist at the location where theapplication looked for it:

Severity: 3, Error No: 20015.Could not open interface file.

See the installation guide for your platform for instructions on howto enter a server in the interfaces file. Sybase configuration tools suchas sybinit or sybsetup can help you perform this task. See Step 4 in theprevious section for information on locating the interfaces file.


• DB-Library/C 4.x and later



Maximum dbprocesses already allocated

Error Number

20011 (SYBEDBPS)

Severity

8 (EXRESOURCE)

Message Text

Maximum number of dbprocesses already allocated.

This error occurs during a dbopen call when an application tries toopen a DBPROCESS that would exceed the maximum number ofDBPROCESSes allowed. The maximum by default is 25, but you canset a maximum value in the application using dbsetmaxprocs.

This limit applies to the application session; it is not the maximumnumber of users that the server is configured for.

Action


• Check the application source code to see if dbsetmaxprocs has beenset. Then check the code to see if the number of connectionrequests exceeds the value of dbsetmaxprocs, if set, or the defaultvalue of 25. If the value of the dbsetmaxprocs is smaller than thenumber of connection requests, or if it is missing, set the value toa number large enough to accommodate the connection requestsby calling:

dbsetmaxprocs(maxprocs)

• Change the code to reuse or close some connections.

➤ NoteA different error is raised when the number of connections attempted is

more than the number of users the server is configured for. See “Net-lib

operation terminated due to disconnect” in Chapter 3, “Client Library Error

Messages” for information on what to do if you exceed maximum server

connections.







Unexpected EOF from SQL Server

Error Number

20017 (SYBESEOF)

Severity

9 (EXCOMM)

Message Text

Unexpected EOF from SQL Server

Possible Cause

This error can be caused by either of the following events:

• The server that the DB-Library application is connected to goesdown.

• The server process (spid) corresponding to the client connectionin the server dies.

Action


• Try to reconnect to the server. If you get this message:

20009 "SQL Server is unavailable or does not exist"

check to see whether the server process is still running. On UNIXsystems, you can use the command:

showserver

On NT, check the console, or simply try connecting to the server.If the server is not running, check the server error log and tryrestarting.

• If the connection attempt is successful, then the problem occurredwhen the spid for the previous connection stopped.

Troubleshoot the problem. To find out which SQL statement wasexecuting when the connection went down, add the followingcommand to your code before the first call to dbcmd:

dbrecftos(“ file_name ”);

dbrecftos writes the program's SQL statements as they execute tothe output file designated by file_name. Connect to the server



with isql and individually issue the final statements recorded inthe file to see if they cause the error.

• If you have a Solaris 2.4 or 2.5.x operating system, you may beexperiencing a problem caused by Solaris Bug 1233973 or1233827. These bugs in the Solaris tcp/ip code cause the server toreceive a spurious disconnect signal from the client.

As a workaround, you can try increasing the operating systemparameter tcp ip abort interval, using this command:

% ndd -set /dev/tcp tcp_ip_abort_interval new_value

where new_value is a value higher than the default of 480000, forexample, 960000.

Patches containing the fix for this problem are available fromSun. The following table lists patch numbers for Solaris 2.4, 2.5,and 2.5.1:

See TechNote 2530 for more details about this bug. TechNotesare posted in Sybase Technical Library on the Web athttp://techinfo.sybase.com.

• Solaris systems can also be affected by the values of the followingtcp parameters:

- tcp_rexmit_interval_max

- tcp_ip_abort_interval

If the tcp_rexmit_interval_max parameter is too high with respectto the tcp_ip_abort_interval, you can experience the disconnectproblem. Generally, you can use a tcp_rexmit_interval_max valueequal to one third the tcp_ip_abort_interval value. Contact yoursystem administrator or Sun technical support for the optimalvalues in your environment.

Background: This workaround is based on Sun’s pollingalgorithm. An internal tcp parameter, tcp_timer_backoff,determines how often a poll of the tcp window occurs. The value

Table 4-1: Patches available from Sun

Patch VersionsArea Affected Bug ID

2.4 2.5 2.5.1

101945-44 103169-06 103630-01 /kernel/drv/ip 1233973

101945-44 103447-03 103582-01 /kernel/drv/tcp 1233827



of tcp_timer_backoff is initially set to the value oftcp_rexmit_interval_initial. However, if there is no room in the tcpwindow to send data when a poll occurs, tcp_timer_backoffdoubles its value at each succeeding poll, up to the value oftcp_rexmit_interval_max. Reducing the tcp_rexmit_interval_maxvalue to less than half the value of tcp_ip_abort_interval ensuresthat the parameter tcp_timer_backoff never doubles to a valuegreater than the tcp_ip_abort_interval.

➤ NoteThe tcp_rexmit_interval_initial and tcp_rexmit_interval_max parameters

can be tuned using ndd, but tcp_timer_backoff is set internally.

• If the disconnect is accompanied by errors in the server log, suchas Error 1608:

A client process exited abnormally, or a networkerror was encountered. Unless other errorsoccurred, continue processing normally.

or Error 1605:

Failed to open virtual socket for new connections

check with your network administrator for possible networkproblems. Your administrator may have to use a tool such as a“sniffer” to do this. See the Adaptive Server EnterpriseTroubleshooting and Error Messages Guide for information onserver errors.





General SQL Server error

Error Number

20018 (SYBESMSG)

Severity

5 (EXSERVER)

Message Text

General SQL Server error: Check messages from theSQL Server.

Possible Cause

This error usually accompanies an error from the server. A servererror occurred while processing a SQL command sent by theapplication. The command could be a direct SQL command sent in adbcmd call or an indirect SQL command in a dbrpcsend, dbwritetext ordbsetopt call.

Action


• Check the server error message that accompanies the client errormessage to try to locate the problem. If you need moreinformation, check the server’s error log.

• If you think the problem might be in a query, try executing it inisql. If the query does not work in isql, fix the query first.

• If the query works in isql, look at your program for parameterspassed at runtime that might cause the problem. Use thefollowing call to see the SQL commands being sent by theapplication:

dbrecftos("<filename>");

The following example shows how to use dbrecftos:



.....DBPROCESS *dproc;LOGINREC *login;char tab_name[33]; .....dbrecftos("dblib.log");dbproc = dbopen(login, NULL); .....printf("Enter table name: ");gets(tab_name);dbfcmd(dbproc,"select * from '%s'", tab_name); ....

In this example, all SQL sent by the application is recorded in afile called dblib.log.0. If the query recorded does not look right,check your code again for logic errors and parametersubstitutions. Check the server log for related errors if theproblem is not obvious or the occurrence is inconsistent.

The dbrecftos call is especially useful if the error occurs on anindirect SQL call such as with dbwritetext. See the DB-Library/CReference Manual page for dbrecftos for more information.





Results pending

Error Number

20019 (SYBERPND)

Severity

7 (EXPROGRAM)

Message Text

Attempt to initiate a new SQL Server operationwith results pending.

Possible Cause

This error occurs when you try to send a new command to the serverbefore all the results of the previous command on the sameconnection have been completely processed. A connection in DB-Library is single-threaded and synchronous; it can handle only onerequest to the server at a time. Although this request may containmultiple commands, a new request cannot be initiated until all theresults from the first request set have been fully processed orcancelled. You are allowed to batch multiple SQL commands as onecommand request (one dbcmd or dbfcmd call). For example, thefollowing command:

dbcmd(dbproc, "select * from authors select titlefrom titles");

contains two SQL commands, but makes only one SQL operationrequest to the server.

Action


• The error often occurs when a DB-library program does not loopcorrectly on the results returned by the server. The proper way forany DB-library program to handle results is:



.....RETCODE result_code;DBPROCESS *dbproc;

.....

/* Process each command until there are no more results. */while ((result_code = dbresults(dbproc)) != NO_MORE_RESULTS){if (result_code == SUCCEED)

{/* If this is a command that returned rows */if(DBROWS(dbproc))

{/* Do the binds */....... while (dbnextrow(dbproc) != NO_MORE_ROWS){.......}

}else/* handle non-row results appropriately */

}else/* Handle failures appropriately */

} /* end of result processing loop */

Use this programming logic for processing results even whenyou expect a command to return only one result set. Thismethod is consistent for single or batched commands and canhandle one or multiple result sets. It safeguards yourapplications against changes in tables or stored procedures, andeven changes in SQL behavior that may occur in future releasesof the server.

• If you want to send a new request to the server on the sameDBPROCESS connection without processing all results from thefirst request, you must cancel the results from the first request.Use dbcancel to cancel results if you sent a batch of SQLcommands, dbcanquery if you sent a single command. Callingdbcanquery is equivalent to calling dbnextrow until it returnsNO_MORE_ROWS, but dbcanquery is faster because it doesn’tbind data.

• If you want to initiate a new SQL request while still processingresults from the first, and cancelling the current result set is not an



option, open a new connection with a new DBPROCESSstructure.

• If you wish to fetch or update rows without using cursors, andcannot open a new connection because of possible lockcontention, evaluate the method demonstrated by the followingexample.

For example, the code shown here causes the 20019 error:

.....DBPROCESS *dbproc;RETCODE result_code;DBCHAR col1[100];

.....

/* Issue the query */dbcmd(dbproc, "select col1 from table1 ");

if (dbsqlexec(dbproc) == fail)/* Handle the error */.....

/* Process results. */while ((result_code = dbresults(dbproc)) != NO_MORE_RESULTS){

...../* bind rows to host variable */dbbind(dbproc, 1, NTBSTRINGBIND, (DBINT)0, col1);/* While there are rows, display the row, then** issue the command for update.*/while (dbnextrow(dbproc) != NO_MORE_ROWS){

printf("Row value = %s\n", col1);dbfcmd(dbproc,"update table1 set col1 = new_value ");

.....}.....

}

This code causes the error because it issues a second commandon the same DBPROCESS as the select, without first processingall the results from the select.

The following code avoids the error without using cursors. Itprocesses the results, then uses a temporary array to hold thedata while you perform the updates:



/* Allocate a structure to store all the** returned values for the select.** The size of the array should be the maximum** number of rows you expect.*/

.....struct {

char tmp_col1[100];} objects[20];.....

/* Issue the query. */dbcmd(dbproc, "select col1 from table1 ");if (dbsqlexec(dbproc) == fail)/* Handle the error */.....

/* Process results. */while ((result_code = dbresults(dbproc)) != NO_MORE_RESULTS){

...../* bind rows to host variable */dbbind(dbproc, 1, NTBSTRINGBIND, (DBINT)0, col1);/* fetch a row into the host variable. Repeat** until there are no more rows. At the end** of the loop, all the data will have been** transferred from the bound host variable to** another variiable for future processing. */while (dbnextrow(dbproc) != NO_MORE_ROWS){/* Now transfer the data to the host array to** store the row values for future updates** or any other processing.*/

strcpy(objects[i].tmp_col1, col1);i++;

}.....

}/* You have fetched all the rows from the select'; now you** can use the same DBPROCESS to perform the updates. Scan** the array for the row to update.*/

.....for (i = 0 ; i < DBCOUNT(dbproc) ; i++){



dbfcmd(dbproc, "update table1 set col1 = new_value "where col1 = '%s'",objects[i].tmp_col1");if (dbsqlexec(dbproc) == fail)/* Handle the error */...../* Process results from the update. */while ((result_code = dbresults(dbproc)) !=NO_MORE_RESULTS).....

}





Bad token from SQL Server

Error Number

20020 (SYBETOK)

Severity

9 (EXCOMM)

Message Text

Bad token from SQL Server: Data-stream processingout of sync.

Possible Cause

The following are the most common causes of this error:

• This error usually occurs because the communication betweenthe client and the server becomes corrupted or out of sync. Thecorruption may be in the database you queried, or a networkproblem may have caused the data stream to become corrupt.Heavy network traffic could cause the error as well, in which casethe error is usually transient.

• The error may occur when the client and server are at differentTDS levels. TDS is Sybase's proprietary protocol used forcommunication between server and client. If the server and clientare at different release levels, the server might send a token at ahigher TDS level than the client which the client does notunderstand.

• Issuing too many cancels (dbcancel or dbcanquery) can also causedata processing to go out of sync.

Action

• Check for errors in the server log, especially for 605 errors relatedto corruption in the database. Ask your Sybase databaseadministrator to correct these first. If there are no errors in theserver log related to corruption, check for other errors that relateto the network. Contact your network administrator to check onpossible network problems.

• If you are running an 11.x server, be sure that you are using acompatible level of DB-Library (at least 10.x) and that yourapplication sets the DB-Library version to “10” by making thefollowing call:



dbsetversion (DBVERSION_100)

that sets the TDS level to the current level.

• Keep cancels to a minimum and use dbcanquery rather thandbcancel if possible.





Unknown bind type

Error Number

20023 (SYBEBTYP)

Severity

7 (EXPROGRAM)

Message Text

Unknown bind type passed to DB-Library function.

Possible Cause

This error occurs when you specify an invalid bind type for avariable at bind time. Often, this happens because you used a bindtype that was introduced in Release 10.x, but did not set the productversion to “10” in the application. DB-Library 10.x and later defaultsto 4.x behavior for backward compatibility. If you want to usefeatures from later releases, you need to explicitly set the productversion in the application.

DB-Library calls that can raise this error are dbbind, dbaltbind,dbcursorbind and dbsetnull.

Action


• Check your code to verify that dbbind, dbaltbind, dbcursorbind, anddbsetnull calls use only valid bind types. Although most bind typeerrors are found when you build the application, some are foundonly at runtime.

• The following types of binds (and datatypes) were introduced inversion 10.x:

- NUMERICBIND

- DECIMALBIND

- SENSITIVITYBIND

If your program uses any of these bind types, you must set theDB-Library version to 10. To do this, call dbsetversion after dbinitand before making any other calls, as in this example:



..../* Initialize DB-Library */dbinit();/* Set the version to 10.x and up behavior */dbsetversion(DBVERSION_100);

....

If you do not set the DB-Library version to 10, DB-Library uses4.x behavior, which did not include support for numeric ordecimal datatypes.

For More Information

See the Open Client DB-Library/C Reference Manual sections ondbbind, dbaltbind, dbcursorbind and dbsetnull for lists of legal bind typevalues, as well as their corresponding server and programvariable types.

[XREF] See also the section in this manual for Error 20060.





Unknown datatype encountered

Error Number

20029 (SYBEUDTY)

Severity

7 (EXPROGRAM)

Message Text

Unknown datatype encountered.

Possible Cause

This error occurs when your application uses numeric or decimaldatatypes, and one of the following conditions exists:

• You are using a pre-10.x version of DB-Library

• You are using DB-Library 10.x or 11.x, but have not explicitly setthe version to 10.

The numeric and decimal datatypes were introduced in version 10,but DB-Library defaults to 4.x behavior for backward compatibility.If you need 10.x behavior, you have to set the version explicitly inyour programs.

The error can occur on calls to dbconvert, dbrpcparam, dbcoltypeinfo,dbwillconvert, bcp_bind and any other call that references typesSYBNUMERIC, SYBDECIMAL, SYBBOUNDARY orSYBSENSITIVITY.

For example, suppose the application executed the following storedprocedure on the server:

create proc test_proc(@param numeric(25,2)) asinsert test_table values(@param)return

and the application passed the parameter as:

......

DBNUMERIC num_var;

......

dbrpcparam (dbproc, "@param", (BYTE)0, SYBNUMERIC,-1, -1, (BYTE *)&num_var);

......



You would get the error unless you were running DB-Library 10.xwith the version set to 10.

Action

To resolve the problem, be sure your are running DB-Library 10.x. Inyour application, set the version to 10 as follows to evoke 10.xbehavior:


Make this the first DB-Library call, or the call immediately after dbinit.Adding this call will allow you to use version 10 features. Do thiseven if you are running DB-Library 10.x or 11.x.





Attempt to bind to a non-existent column

Error Number

20032 (SYBEABNC)

Severity

7 (EXPROGRAM)

Message Text

Attempt to bind to a non-existent column.

Possible Cause

This error usually occurs when a DB-Library program attempts tobind a host variable to a column that does not exist in the select list ofthe previous dbcmd or dbrpcsend call. For example, suppose you issuethe following command, which lists two columns in the select:

select pub_id, city from pubs2.dbo.publishers

You can bind columns 1 and 2, but an attempt to bind column 3 willtrigger the error.

Action


• Check the number of binds issued by the application after a selectcommand. It should match the number of columns in the selectlist.

If the command which triggers the error is a request to execute astored procedure, check the stored procedure definition to matchthe number of columns with the number of binds. It is possiblethat the stored procedure or table definitions have changedwithin the server.

• If the number of columns in the select list and bind call matchesand the error persists, you may be getting incomplete data. Checkwith your network administrator to see if network problemscould be causing data packets to be lost or broken. Your networkadministrator may use a tool such as a “sniffer” to check forproblems.

• If taking these steps does not resolve the problem, contact SybaseTechnical Support. You may need to run a Sybase proprietarydebugging tool such as capture to diagnose the problem.







dbbind() with mismatched column and variabletypes

Error Number

20033 (SYBEABMT)

Severity

7 (EXPROGRAM)

Message Text

User attempted a dbbind() with mismatched columnand variable types.

Possible Cause

This error occurs when DB-Library cannot perform the requestedtype of bind for the specified host variable.This example illustratesthe problem:

....DBCHAR date_var;

....dbcmd(dbproc,"select getdate()");.. dbsqlexec(dbproc) ...while ((dbresults(dbproc)) != NO_MORE_RESULTS ){

dbbind( dbproc, 1, INTBIND, 0, date_var);....}

This code causes the error because it tries to perform a bind of typeINTBIND on a datetime value.

Action

To resolve the problem, check the bind type specified in the programagainst the datatype of the column requested. See the Open ClientDB-Library/C Reference Manual page for dbbind for a list of valid bindtypes and their corresponding host variable and server datatypes.





Attempt to retrieve data from a non-existentrow

Error Number

20044 (SYBERDNR)

Severity

7 (EXPROGRAM)

Message Text

Attempt to retrieve data from a non-existent row.

Possible Cause

This error occurs when the server does not return the expected rowsbecause:

• Your select has a where qualifier and no rows in the table meet thequalification.

• The table contains no rows.

The error can be returned by any of the following routines:

• dbqual

• dbtsput

• dbdata

• dbdatlen

• dbtxplen

• dbtxptr

• dbtxtimestamp

The following examples show how you can get the error if you callone of these routines without first checking to see if your queryreturned any rows. In the first example, the program uses browsemode to select and update rows. However, the employee tablecontains no rows, causing the dbqual routine to fail with the error:



.....DBPROCESS *dbproc;char *qualptr;

.....dbcmd(dbproc, "select * from employee for browse");... dbsqlexec(dbproc) ...;... dbresults(dbproc) ....

.....qualptr = dbqual(dbproc, -1, "employee");

.....

Similarly, the next example shows how you can get the error bycalling dbdata when the employee table has no rows.

.....DBPROCESS *dbproc;char data[100];

.....dbcmd(dbproc, "select * from employee ");dbsqlexec(dbproc);dbresults(dbproc);dbconvert ( dbproc, ( dbcoltype(dbproc,1)),

dbdata(dbproc,1),(int)dbdatlen(dbproc,1),SYBCHAR, data, -2);

printf("Data == %s\n", data);....

Action

To resolve the problem, verify that you call the routines listed in theprevious section only if a row is available. Use a sequence ofcommands similar to this:

- Call dbresults in a loop until it returns NO_MORE_RESULTS

- Use DBROWS to verify that rows were returned

- Call dbnextrow in a loop until it returns NO_MORE_ROWS

- Call the routine to process the row

See “Results pending” in this manual for an example of this logicalsequence of operations. See also the online samples in theSYBASE/sample/dblibrary directory as a guide to using the routines inthe previous section.





DBPROCESS is dead or not enabled

Error Number

20047 (SYBEDDNE)

Severity

1 (EXINFO)

Message Text

DBPROCESS is dead or not enabled.

Possible Cause

This error occurs when a DB-Library connection to the server is nolonger available. DB-Library marks a DBPROCESS dead when anerror occurs that makes the DBPROCESS unusable in any future DB-Library call. The most common reasons for this error include:

• The server experienced a severe error while processing a querysent by the DB-Library program. Severe server errors includedeadlocks (Error 1205), corruption (605), and memory problems(803). See the Adaptive Server Enterprise Error Messages Guide forinformation on server errors.

• A server timeout error occurred and the error handler returnedan INT_CANCEL.

• You have exceeded the maximum number of user connections forthe server.

• While the server was returning data to the client, networkproblems or an I/O error caused it to drop the connection. Anoperating system error could also cause the server to drop theconnection. See the section ‘‘Unexpected EOF from SQL Server’’for details on a known operating system bug on Solaris that cancause this error.

• You have connected to a non-Sybase server that does notunderstand the Sybase proprietary protocol, TDS.

• Memory allocation errors can also cause the error, for example,very large chunks of text/image data.

Action




• Check the server error log for error messages recorded at the timethe 20047 error occurred. Refer to the Adaptive Server EnterpriseTroubleshooting and Error Messages Guide more information onthese errors.

• If the error occurs after a server timeout error, see the Open ClientDB-Library/C Reference Manual page for dberrhandle for details onhandling timeout errors without killing the DBPROCESS.

• Check with your network administrator to see if you areexperiencing network problems.

• If you are asking the server to open more connections than it isconfigured for, try increasing the number of user connectionsparameter on the server. Contact your database administrator orsee the section on setting configuration variables in the SystemAdministration Guide for instructions on resetting this parameter.

• If the problem happens randomly and no errors appear in theserver error log, or if the error started after an operating systemchange, check both the Sybase website and informationpublished by your operating system vendor for related bugs.

• Verify that your DB-Library application is connecting to a Sybaseserver that understands TDS.

• If you are getting errors while dealing with large chunks of text or image data, you could be having memory allocation failures. Trybreaking the data into smaller chunks. See the sections ondbwritetext and dbmoretext in the Open Client DB-Library/C ReferenceManual.





Syntax error in source field

Error Number

20050 (SYBECSYN)

Severity

4 (EXCONVERSION)

Message Text

Attempt to convert data stopped by syntax error insource field.

Possible Cause

The main reason for this error is a failure in an implicit or explicitconversion by dbconvert. This can occur when:

• You make a direct call to dbconvert to perform a conversion that isnot supported or has resulted in a conversion error.

• DB-Library makes an implicit call to dbconvert as in a bind call,which results in a conversion error. In a bind call, the error couldoccur if either the data or the bind specifications were incorrect.For example, suppose you tried using bcp_bind to copy thefollowing comma-delimited datafile:

hello,world

into a table defined as:

create table test(col1 char(5), col2 int)

The second column, col2, is defined as integer, but the datafilecontains character data in the corresponding column, resultingin the error.

Action


• If you make an explicit call to dbconvert, check the type ofconversion you specified and verify that the conversion isallowed. If it is a valid conversion, check the source data and seeif it is valid.

• If the error occurs on bcp routines, check the data in the datafile orin your host variables. If you recently began experiencing theerror with an application, it may be that table definitions in the



server have changed. Map your data to the server columndatatype and make sure that they match.

Then, check your datafile against the bind type specified in yourapplication. If your datafile or host variable data is in ASCIIformat, you must specify the bind type as SYBCHAR for allcolumns, regardless of the corresponding server column type.All necessary conversions are done implicitly.

Your data is in native or binary format if you:

- Run bcp with the -n option

- Use bcp_exec to copy the data

- Bind the data with types of INTBIND, NUMERICBIND and soon

If this is the case, you must specify the same bind type on thecopy in operation.

• To help locate the error if it occurs with bcp, specify an error file inyour bcp_init call. DB-Library writes the row and column wherethe error occurred to the error file.





Unknown network type found in interface file

Error Number

20055 (SYBEUNT)

Severity

2 (EXUSER)

Message Text

Unknown network type found in interface file.

Possible Cause

Possible causes of the error include the following:

• This error is usually raised by the network layer during a dbopencall when the server entry in the client’s interfaces file is in thewrong format for the network protocol. For example, a TLI-basednetwork protocol such as Sun Solaris looks for a server entry in tliformat, whereas a socket-based protocol such as HP-UX looks fora corresponding socket-based tcp/ip format.

A TLI-based entry looks like this:

SYBASEquery tli tcp /dev/tcp \x000213e09d852c880000000000000000master tli tcp /dev/tcp \x000213e09d852c880000000000000000

A socket-based tcp/ip entry for the same server looks like this:

SYBASEquery tcp ether prod1 5088master tcp ether prod1 5088

If the server entry in the client’s interfaces file is in a formatdifferent than the one DB-Library expects for your operatingsystem, you will get an error.

Entries in the interfaces file are automatically formatted correctlyfor the network protocol when you use a Sybase tool such assybsetup to install your product or add a server to yourconfiguration. Formatting errors can result when you hand-editthe interfaces file, copy an interfaces file from one machine toanother, or use an interfaces file on an NFS-mounted file systemfrom a different platform.



➤ NoteThe format of the interfaces file entry must correspond to the client’s

network protocol, not the server’s.

• The error can also occur if the entry has a formatting mistake.Sybase products, including DB-Library, require an interface entryto be in a specific format. This is the format of a non-tli tcp/ipentry:

# put comments here<newline>SERVERNAME<tab>retry_attemps<tab>delay_interval<newline><tab>service_type protocol network machine port<newline>

If the tabs are missing or you have characters other than a singlespace before the keywords query or master, you can get the error.

Action

Always use a Sybase-supplied tool to enter server information in theinterfaces file. For example, use sybinit for DB-Library 4.x and 10.x,and dsedit for 11.x and above releases. This ensures that the interfacesfile entry is in the correct format for the platform and productversion.

See the server installation or configuration manual for moreinformation on interfaces file formats.

See also the Client-Library error “No driver of the requested protocolclass” in Chapter 3, “Client Library Error Messages”.





Too much TEXT data via the bcp_moretext() call

Error Number

20095 (SYBEBTMT)

Severity

7 (EXPROGRAM)

Message Text

Attempt to send too much TEXT data via thebcp_moretext() call.

Possible Cause

The bcp_moretext call is used in conjunction with bcp_bind andbcp_sendrow to send a large SYBTEXT or SYBIMAGE value to theserver in a number of smaller chunks. The general syntax of thebcp_moretext call is:

bcp_moretext(dbproc, size, text)

The error occurs if the sum of the sizes specified in a series ofbcp_moretext calls is greater than the size specified in the bcp_bind orbcp_collen call for the text or image column. For example, if youdefined a table as:

create table test (col1 int, col2 text)

and wished to send the data for the second column in chunks, wemight say:

.....char text_col1[5000], text_col2[5000];

.....strcpy(text_col1, "The sun was up and the tent was starting to

get hot. Nick crawled out under ");strcpy(text_col2, "the mosquito netting stretched across

the mouth of the tent, to look at the morning. ");.....

if (bcp_bind (dbproc, (BYTE *)NULL, 0,(DBINT) (strlen(text_col1) + strlen(text_col2))(BYTE *)NULL, 0, SYBTEXT, 2) == FAIL ).....



/* Now send this row, with the text value broken into chunks. */if (bcp_sendrow(dbproc) == FAIL)

.....if (bcp_moretext(dbproc, (DBINT)sizeof(text_col1), text_col1)

== FAIL).....

if (bcp_moretext(dbproc, (DBINT)sizeof(text_col2), text_col2)== FAIL).....

This code produces the error because the function sizeof used as aparameter for bcp_moretext indicates that 5000 bytes are being sent foreach bcp_moretext call. The bind call, using the strlen function, indicatedthat a total of 161 bytes were to be sent.

Rewriting the code as follows avoids the error:

if (bcp_moretext(dbproc, (DBINT)strlen(text_col1), text_col1)== FAIL).....

if (bcp_moretext(dbproc, (DBINT)strlen(text_col2), text_col2)== FAIL).....

➤ NoteThe sizeof function refers to the maximum size of the variable that it acts

upon. Confusing sizeof with strlen — the actual length of the character data

contained in the variable — is a common reason for this error.

Action

To resolve the problem, verify that the sum of the sizes specified in allof the bcp_moretext calls for the text or image column is equal to the sizeof the column specified in the bcp_bind call (or bcp_collen if used inplace of bcp_bind). See the page for bcp_moretext in the Open ClientDB-Library/C Reference Manual for an example, as well as notes onhandling multiple text and image columns in the same table.





dbreadtext() may only be used to receive theresults...

Error Number

20118 (SYBERTSC)

Severity

7 (EXPROGRAM)

Message Text

dbreadtext() may only be used to receive theresults of a query which contains a single resultcolumn.

Possible Cause

The dbreadtext is used to process the results of a SQL query thatreturns only one column, which must be of text or image datatype.The error occurs if a query returns more than one column of anytype. For example, if you had a table defined as:

create table test(id int, text_col text )

and your program was coded as follows:

....#define BUFSIZE 100DBPROCESS *dbproc;RETCODE ret;DBINT bytes = 0;char buf[1000];

....dbcmd(dbproc, "select * from test");dbsqlexec(dbproc);

/* Process the results: */while((ret = dbresults(dbproc)) != NO_MORE_RESULTS)



{if( ret == FAIL ){/* dbresults() failed */}while( (bytes = dbreadtext(dbproc,

(void *)buf, BUFSIZE)) != NO_MORE_ROWS )....

}....

you would get the above error. The correct query would be:

dbcmd(dbproc, "select text_col from test");

If your query selects a single column of a datatype other than text orimage, you get neither results nor an error message.

Action

Check the query in your application. Be sure that it selects only onecolumn of type text or image. State the column name in the queryrather than issuing a query in the form of “select * from table”. Thisensures that you get results only from the desired column, even if thetable definition changes.





Zero length TEXT or IMAGE to dataserver viadbwritetext()

Error Number

20169 (SYBEZTXT)

Severity

1 (EXINFO)

Message Text

Attempt to send zero length TEXT or IMAGE todataserver via dbwritetext().

Possible Cause

This error occurs if you set the value of the size parameter in thedbwritetext call to 0 and the value of the text parameter to NULL. Thesyntax of the dbwritetext call is:

dbwritetext(dbproc, objname, textptr, textptrlen,timestamp, log, size, text

where size is the size of the data to send to the server and text is apointer to the buffer containing the text or image data. You can enterNULL as the value of text if you intend to send the data in chunksusing dbmoretext calls.

The following example illustrates one way the error can occur:

....DBPROCESS *u_dbproc;DBBINARY *txptr; /* text pointer */DBBINARY *ts_ptr; /* time stamp */char *buf;int size = 0;

....dbwritetext (u_dbproc, "au_pix.pic", txptr,

DBTXPLEN, ts_ptr, TRUE, size, (BYTE *)buf);....

This code raises the error because the size parameter is set to 0 andbuf, the text value for update, is NULL.



➤ NoteIf the size parameter is set to 0, but the value of the text parameter is not

NULL, the dbwritetext call does not fail, but the update will not take place.

The error could also occur if you set the value of the size parameter toa value greater than the variable can hold. This causes numericaloverflow, and the value in the variable then becomes a negativenumber. See “Called dbmoretext with a bad size parameter” for anexample.

Action

Set the size parameter to a value greater than 0, specifically, the sizeof the text or image data you want to send. If the size parameter isgreater than 0 and the text or image value is NULL, the applicationmust call dbmoretext to write the data in chunks. See the page ondbwritetext in the Open Client DB-Library/C Reference Manual for anexample that illustrates the last combination.





DBPROCESS is being used for anothertransaction

Error Number

20180 (SYBETRAN)

Severity

1 (EXINFO)

Message Text

DBPROCESS is being used for another transaction.

Possible Cause

This error occurs when you initiate an RPC event on a DBPROCESSstructure and then make a second request of the same kind before thefirst request has been completed. The term “transaction” in this caseapplies to a command such as an RPC operation, a registeredprocedure operation, or a passthrough operation using Open Serverwith DB-Library. It does not refer to a transaction as defined by thebegin tran and commit or rollback tran SQL commands.

The follow example illustrates the problem. Two dbrpcinit commandsoccur in succession on the same DBPROCESS structure; “rcpA” hasnot been completed before “rpcB” is sent:

dbrpcinit(dbproc,"rpcA",...);dbrpcinit(dbproc,"rpcB",...);

Action


• If, after initiating a transaction, you do not wish to continue withit, and want to initiate a different transaction, cancel the firsttransaction with dbcancel.

• If you wish to continue processing the current transaction, youmust complete the logical sequence of commands required tosend it to the server and process the results. For RPC commands,the typical sequence is:



.....dbrpcinitdbrpcparam /* if parameters exist */dbsqlsenddbsqlokdbresults /* process in a loop until no more results */dbnumrets /* check for any return parameters */dbretstatus /* get the return status */

See the Open Client DB-Library/C Reference Manual page for the DB-Library call you are using for the correct sequence of commands.





Called dbmoretext with a bad size parameter

Error Number

20188 (SYBETEXS)

Severity

1 (EXINFO)

Message Text

Called dbmoretext with a bad size parameter.

Possible Cause

The error occurs if you set the size parameter in a dbwritetext ordbmoretext call to a value less than zero.

The dbwritetext call is used to read large text or image data in smallerchunks from the server. The general syntax of the dbwritetext call is:

dbwritetext(dbproc, buffer , bufsize )

where buffer is a pointer to a caller-allocated buffer for the chunk oftext or image data and bufsize is the size in bytes of the buffer.

The dbmoretext call is used in conjunction with the dbwritetext call tosend large image or text data to the server in smaller chunks. Thegeneral syntax of the dbmoretext call is:

dbmoretext(dbproc, size , text )

where size is the size in bytes of the chunk of text or image data beingsent to the server and text is a pointer to the text or image portion to bewritten.

➤ NoteThe error message text is the same whether the error is raised by dbwritetextor dbmoretext.

The error could occur if you set the value of the size parameter to avalue greater than the variable can hold. This causes numericaloverflow, and the value in the variable then becomes a negativenumber.

In the following example, the variable size_val, intended to hold thevalue of the size parameter, was created as a short datatype. However,the buffer created to hold the image data is 100,000 bytes, which is



beyond the range of values for a short datatype. The following codewould produce the error:

...short size_val;DBBINARY image_val[100000];....size_val = sizeof(image_val);

The code tries to set size_val to 100,000, causing it to overflow and beassigned a negative value. No error is raised by C, but when you usethis parameter in a dbmoretext call, you get this error.

Action

If possible, check the value of the size parameter before callingdbwritetext or dbmoretext. To resolve the problem, set the size parameterin the dbwritetext or dbmoretext call to a value greater than zero.

See the sections on dbwritetext and dbmoretext in the Open Client DB-Library/C Reference Manual.





Packet size of %1! not supported

Error Number

20201 (SYBEBADPK)

Severity

1 (EXINFO)

Message Text

Packet size of %1! not supported -- size of %2!used instead.

Possible Cause

This error occurs when the client requests a valid packet size(between the default and maximum network packet sizes), but theserver is unable to use the size at the time.

DB-Library and the server negotiate the packet size at login time.Memory for default packet sizes is allocated from the server memorypool. Memory for packet sizes larger than the default is allocatedfrom the additional network memory pool. If the additional memorypool does not have enough memory to handle the larger packet sizerequest from DB-Library, the server will set the packet size to thevalue it can support from the additional memory pool. If no moreadditional memory is left, the server sets the packet size at thedefault value. If DB-Library is unable to negotiate the requestedpacket size, it raises the error.

Action

To resolve the problem, contact your Sybase system administratorand request an increase in the additional network memory parameterfor the server. Use the following formula to calculate additionalmemory needed:

1. Estimate the number of simultaneous users requesting the largepacket size and multiply this number by the packet size.

2. Multiply the previous result by three, because each connectiongets three buffers for sending or receiving data on the network.

3. Add 2% overhead, rounded up to the nearest multiple of 512.

For example, if the default packet size is 512, the maximum networkpacket size is 8192, and the number of clients that could



simultaneously request this packet size is 2, then additional networkmemory needed could be calculated as follows:

2 * 8192 = 16384

16384 * 3 = 49152

(1.02 * 49152) = 50135.04

Additional netmem = 50176

See the System Administration Guide for more details on tuning theadditional network memory parameter.





Function can be called only once

Error Number

20207 (SYBEONCE)

Severity

7 (EXPROGRAM)

Message Text

Function can be called only once.

Possible Cause

If you use the dbsetversion call to change the behavior of a DB-Library10.x or 11.x program, you must make that call first or right after dbinit.Otherwise, DB-Library implicitly sets the version to 4.6 when itrequests a server login. If you make the dbsetversion call later in theprogram, DB-Library thinks you are making the call twice, and raisesthe error.

All current versions of DB-Library default to DB-Library 4.6behavior for backward compatibility. This means that new featuresin 10.x and later releases (such as numeric and decimal datatypes orclient cursors) are not be available to the program. If you want to usefeatures available in 10.x or later, you have to set the program versionto “10” by making a call to dbsetversion.

Action

Unless you are connecting to a 4.9 server, you should set the versionto the 10.x level to take advantage of the additional features. Makethe following call to set the version to 10:


This should be the first call in the program or the first call after dbinit.

The only valid values for dbsetversion are:

• DBVERSION_100

• DBVERSION_46

Specifying any other level causes the following error:

Error #: 20206 (SYBEIVERS)Message: Illegal version level specified.







RPC parameters cannot be of type Text/Image

Error Number

20209 (SYBERPTXTIM)

Severity

7 (EXPROGRAM)

Message Text

RPC parameters cannot be of type Text/Image.

Possible Cause

Your application attempted to pass parameters of type text or imageto a stored procedure. These datatypes are not supported by theserver for stored procedures, so you cannot define a storedprocedure to contain them, nor can you pass them as parametersfrom a client application.

Action

To resolve the problem, check your code to see if your DB-Libraryapplication passes parameters of host variable type SYBTEXT orSYBIMAGE in a dbrpcparam call, then check the stored proceduredefinition in the server. Change the host parameter types to oneswhich correspond to the stored procedure’s datatypes.

Use one of the following methods to write the data to the server:

• Use the dbwritetext call to write large text or image values. See theonline sample example9.c in the $SYBASE/sample/dblibrarydirectory.

• If the text or image data is small — for example, a few thousandbytes — you can copy the entire value into a buffer and send it tothe server in a dbcmd call. For example:



.....DBPROCESS *dbproc;char cmd_buff[500];DBBINARY img_col; .....img_col = 0x123456789;strcpy(cmd_buff,"insertbig_table(img_col)values('%x')", img_col);dbcmd(dbproc, cmd_buff);dbsqlexec(dbproc);while (dbresults(dbproc) != NO_MORE_RESULTS ) .....




A Commands to Find SybaseVersions A.

The following are commands that you can use to find out the versionof Sybase utilities and libraries. Issue these commands issued fromthe shell prompt.

ISQL

UNIX

$SYBASE/bin/isql -v

Windows, DOS

%SYBASE%\bin\isql -v

VMS

isql /version

BCP

UNIX

$SYBASE/bin/bcp -v

Windows, DOS

%SYBASE%\bin\bcp -v

VMS

bcp/version

Precompilers

UNIX

$SYBASE/bin/cpre

Or:

Page -2


$SYBASE/bin/cobpre (for ESQL/COBOL )

Windows, DOS

%SYBASE%\bin\cpre

Or:

%SYBASE%\bin\cobpre ( for ESQL/COBOL ).

VMS

cpre /version

Or:

cobpre /version ( if using esql/cobol ).

ESQL Library Version

UNIX

strings $SYBASE/lib/libct.a | grep -i Sybase

For COBOL:

strings $SYBASE/lib/libcobct.a | grep -i Sybase

Windows, DOS

find /I "intel" %SYBASE%\dll\libct.dll

VMS

search libct.olb /form=nonull Sybase

For COBOL:

search libcobct.olb /form=nonull Sybase

Open Client/Server libraries:

The general form of the command to determine the version of anOpen Client/Server library is as follows:

UNIX

strings $SYBASE/lib/< library_name > | grep -i Sybase



Windows, DOS

find /I "intel" %SYBASE%\dll\< library_name >

VMS

search < library_name > /form=nonull Sybase

In general, these commands can be issued on any of the library filesunder the lib or dll directory (depending on your platform) in theSybase installation directory.

The following table gives examples of files you can use to substitutefor library_name for different products:

The extension denoted by x in the name of the library can varyaccording to the platform and to whether you link dynamically orstatically. For example, to get the Client-Library version for theplatforms in the table, issue the following commands:

UNIX

strings $SYBASE/lib/libct.a | grep -i Sybase

Windows, DOS

find /I "intel" %SYBASE%\dll\libct.dll

On VMS

search libct.olb /form=nonull Sybase

To get the version of: Issue the command on:

DB-Library libsybdb.x

CT-Library libct.x

Open Server-Library libsrv.x

Page -4



B Open Client/Server 10.0.x and 11.xRuntime Environment B.

The following is a list of files required in your Sybase environment torun Open Client/Server 10.0.x and 11.x applications.

Files Required in $SYBASE

• interfaces

Files Required in $SYBASE/lib

If Application Has Been Complied Statically

Version 10.0.x

• None

Version 11.x only

You need the following Net Library files:

• TLI- based platforms: libtli.so

• Socket-based platforms: libinsck.so.a or .sl

If using threaded libraries on 11.x

You need the following Net Library files:

• TLI- based platforms: libtl_r.so

• Socket-based platforms: libinsck_r.so.a or libinsck_r.sl

If Application Has Been Compiled Dynamically

If the application has been compiled dynamically, you need thefollowing shared libraries (.sl on some platforms):

• libcomn.so

• libcs.so

• libct.so

Page -2


• libintl.so

• libtcl.so

• libtli.so, libinsck.so.a or libinscl.sl

Version 11.x only

If using threaded libraries, you need the 'libxxxx_r.xx' versions of thelibraries listed in the previous section.

Files Required Under $SYBASE/include

• None

Files Required Under $SYBASE/config

Version 11.x only

• libtcl.cfg

• objectid.dat

• mnemonic.dat, if the conversion configuration file, charset.cfg, fora destination character set specifies a mode of “Mnemonic”.

➤ NoteThe $SYBASE/config directory does not exist in 10.0.x versions of

Open Client/Server.

Files Required Under $SYBASE/locales

Version 10.0.x

• locales.dat

• <language_name>/<charset> (for example, us_english/iso_1)

• cobct.loc (ESQL/COBOL only)

• common.loc

• comnlib.loc

• cslib.loc



• ctlib.loc

• dcllib.loc

• libinsck.loc (for socket platforms)

• libtli.loc (for TLI platforms)

• scllib.loc

• tcllib.loc

Version 11.x

• locales.dat

• message/<language_name> (for example, us_english)

• cobct.loc (for ESQL/COBOL only)

• common.loc

• comnlib.loc

• cslib.loc

• ctlib.loc

• dcllib.loc

• libinsck.loc (for socket platforms)

• libtli.loc (for TLI platforms)

• scllib.loc

• tcllib.loc

Files Required Under $SYBASE/charsets

Version 10.0.x

• <charset_name> (for example, iso_1)

• binary.srt

• charset.loc

• iso_1.cfg

Version 11.x

• The directory and files listed in the previous section, plus:

• utf8.ctb

Page -4


• utf8

• charset.loc

• cp437.ctb

• cp850.ctb

• deckanji.ctb

• eucjis.ctb

• iso_1.ctb

• mac.ctb

• roman8.ctb

• sjis.ctb

• utf8.cfg

For a complete list of files shipped with your Open Client/Serverproduct, please refer to the Open Client/Server Supplement for yourplatform.


C How to Interpret Client-LibraryError SQLCODEs C.

SQLCODEs are used to perform inline error handling. For acomplete discussion of using SQLCODEs, see the Open Client Client-Library Reference Manual. This appendix describes the componentparts of the SQLCODE and explains how to interpret them.

The Elements of a SQLCODE

An error number in Client-Library is a negative number larger than-16777216 (Client-Library error message numbers are inverted beforebeing placed into the SQLCODE structure, so that the SQLCODE isalways negative). The error number is made up of four fields:

L = Layer (the Client-Library layer that generated the message)

O = Origin (internal or external origin of the error)

S = Severity (type of message or failure)

N = Number (the layer-specific error number)

The following section explains how to find the numbercorresponding to each field.

Breaking Down the SQLCODE to its Components

The find the value of each SQLCODE field, perform thesecalculations:

1. Transform the absolute value of the number into a hexadecimalnumber

2. Divide the hexadecimal into four bytes

3. Convert each byte back to decimal.

4. Map the four decimal numbers to L, O, S, and N (from left toright).

If you are working in C, you can perform the conversions with theSybase-supplied macros CS_LAYER(), CS_ORIGIN()(),CS_SEVERITY() and CS_NUMBER(). Run these against the absolutevalue of the SQLCODE. Each macro returns a value between 0 and255. See the Reference Manual for more information about the macros.

Page -2


Meanings of the Four Parts

The meaning of each component of the SQLCODE is explainedbelow. Whenever SQLCODE indicates an error, there is also anappropriate error message, a concatenation of substrings listed here,available in SQLERRMC (COBOL) or in sqlca.sqlerrm.sqlerrmc (C) Themessage that you construct by splitting up the SQLCODE into itscomponents and looking up their text strings in the lists below,should always be the same as the error message in SQLERRMC orsqlca.sqlerrm.sqlerrmc.

Layer

The meaning of Layer is as follows:

1 = “user api layer”

2 = “cslib user api layer”

3 = “generic protocol layer”

4 = “protocol specific layer”

5 = “network packet layer”

Origin

The meaning of Origin depends on the Layer, as follows:

If Layer = 1,3,4 or 5 the meaning of Origin is:

1 = “external error”

2 = “internal Client Library error”

3 = “internal net library error”

4 = “internal common library error”

5 = “internal intl library error”

6 = “internal async manager error”

7 = “internal memory management error”

If Layer = 2, the meaning of Origin is:

1 = “external error”

2 = “internal CS-Library error”



4 = “common library error”

5 = “intl library error”

Severity

The meaning of Severity is as follows:

0 = CS_SV_INFORM (No error has occurred. The message isinformational.)

1 = CS_SV_API_FAIL (A Client-Library routine generated an error.Typically caused by a bad parameter or calling sequence.)

2 = CS_SV_RETRY_FAIL (An operation has failed, but the operationcan be retried. E.g. a network read that times out.)

3 = CS_SV_RESOURCE_FAIL (A resource error has occurred.Typically caused by a malloc failure or lack of file descriptors.)

4 = CS_SV_CONFIG_FAIL (A SYBASE configuration error has beendetected. E.g. missing interfaces- or localization-files, unknownserver)

5 = CS_SV_COMM_FAIL (An unrecoverable error in the servercommunication channel has occurred. Server connection is notsalvageable.) 6 = CS_SV_INTERNAL_FAIL (An internal Client-Library error has occurred.) 7 = CS_SV_FATAL (A serious error hasoccurred. All server connections are unusable.)

See the table on “Client-Library message severities” in the OpenClient Client-Library Reference Manual for more information

Number

The meaning of Number depends on the Layer, as follows:

If Layer = 1 (user api layer), the meaning of Number is:

0 = “State validation succeeded.”

1 = “The information being retrieved will not fit in a buffer of %1!bytes.”

2 = “Memory allocation failure.”

3 = “The parameter %1! cannot be NULL.”

4 = “When %1! is NULL the %2! parameter must be 0.”

5 = “An illegal value of %1! given for parameter %2!.”

Page -4


6 = “The maximum number of connections have already beenopened.”

7 = “The server does not support the KEEP_CON capability.”

8 = “The %1! parameter must be NULL.”

9 = “The %1! parameter must be set to CS_UNUSED.”

10 = “Boolean values must be set to either CS_TRUE or CS_FALSE.”

11 = “A CS_SIGNAL_CB cannot be installed because the platformdoes not support interrupt driven network I/O.”

12 = “A CS_COMPLETION_CB cannot be installed because theplatform does not provide the interrupt or polling capabilitiesneeded.”

13 = “This property cannot be set after a connection to a server hasbeen established.”

14 = “This property/capability cannot be set.”

15 = “It is necessary to be connected to a server in order to get thisproperty/capability.”

16 = “This routine cannot be called while results are pending for acommand that has been sent to the server.”

17 = “The command structure already supports a declared cursor.”

18 = “A cursor must be declared before this command type can beinitialized.”

19 = “This routine may be called only after a CS_SEND_DATA_CMDcommand has been initialized.”

20 = “A command must be initialized before this routine can becalled.”

21 = “This routine cannot be used while a cursor is declared on thecommand structure.”

22 = “A cursor has already been declared on this commandstructure.”

23 = “The command cannot be initialized after the cursor has beenopened.”

24 = “The cursor on this command structure has already beenopened.”

25 = “Cursor updates and cursor deletes are not allowed afterct_fetch() returns CS_END_DATA.”



26 = “A command has already been initialized on this commandstructure.”

27 = “The initialized command cannot have parameters.”

28 = “A command has already been initialized.”

29 = “This type of command cannot be batched with the commandalready initialized on the command structure.”

30 = “A row must be fetched before this routine may be used.”

31 = “A cursor rows command cannot be initialized after a cursoropen command has been initialized.”

32 = “The connection’s capabilities do not support this type ofrequest.”

33 = “This routine cannot be called after ct_results() returns a resulttype of CS_CURSOR_RESULT.”

34 = “This routine cannot be called after ct_results() returns a resulttype of CS_CMD_DONE.”

35 = “This routine cannot be called after ct_results() returns a resulttype of CS_COMPUTE_RESULT.”

36 = “This routine cannot be called after ct_results() returns a resulttype of CS_COMPFMT_RESULT.”

37 = “This routine cannot be called after ct_results() returns a resulttype of CS_MSG_RESULT.”

38 = “This routine cannot be called after ct_results() returns a resulttype of CS_PARAM_RESULT.”

39 = “This routine cannot be called after ct_results() returns a resulttype of CS_ROWFMT_RESULT.”

40 = “This routine cannot be called after ct_results() returns a resulttype of CS_CMD_FAIL.”

41 = “This routine cannot be called after ct_results() returns a resulttype of CS_CMD_SUCCEED.”

42 = “This routine cannot be called after ct_results() returns a resulttype of CS_ROW_RESULT.”

43 = “This routine cannot be called after ct_results() returns a resulttype of CS_STATUS_RESULT.”

44 = “This routine cannot be called since an asynchronous operationis currently pending.”

45 = “There is an internal error in the user api layer.”

Page -6


46 = “An illegal value of %1! was placed in the %2! field of theCS_DATAFMT structure.”

47 = “When defining parameters, names must be supplied for eitherall of the parameters or none of the parameters.”

48 = “The server does not support parameters of type %1!.”

49 = “This routine cannot be called because another commandstructure has results pending.”

50 = “The connection has been marked dead.”

51 = “Exactly one of %1! and %2! must be non-NULL.”

52 = “In-line error handling must be initialized with the CS_INIToperation before any other ct_diag() action may be taken.”

53 = “There was not enough memory available to save messages. Allpreviously stored messages have been cleared.”

54 = “In-line error handling has already been initialized for thisconnection structure.”

55 = “WARNING: Existing error and message handlers have beenremoved.”

56 = “The message limit cannot be set to a value less than the numberof Client-Library or server messages which are currently saved.”

57 = “A result of type %1! cannot be bound to a program variable oftype %2!.”

58 = “The format field of the CS_DATAFMT structure must beCS_FMT_UNUSED if the datatype field is %1!.”

59 = “If the buffer parameter is NULL then the %1! parameter mustalso be NULL.”

60 = “There is a usage error. This routine has been called at an illegaltime.”

61 = “Item of %1! is not greater than the largest item bound.”

62 = “Item %1! has already been read.”

63 = “Read from the server has timed out.”

64 = “The option to specify debug files is not yet supported. Alldebug information will be sent to stdout.”

65 = “The requested type of trace information is not yet supported.”

66 = “A context structure must be supplied when setting/clearingthis type of debug information.”



67 = “A connection structure must be supplied whensetting/clearing this type of debug information.”

68 = “Descriptor not found.”

69 = “A descriptor of name %1! already exists on the connection”

70 = “The descriptor count of %1! is not possible because it exceedsthe maximum count of %2!.”

72 = “The descriptor %1! has already been associated with acommand structure.”

73 = “The %1! field of the CS_DATAFMT structure must be set toCS_UNUSED.”

74 = “When %1! is NULL the %2! field of the CS_DATAFMTstructure must be set to 0.”

75 = “Inconsistent parameter settings were found for the dynamicdescriptor when it was used as input parameters to a command. Alldescriptor values must be set.”

76 = “Inconsistent parameter names were found for the dynamicdescriptor when it was used as input parameters to a command. Aparameter name must be supplied for all of the items or none of theitems.”

77 = “A dynamic de scriptor is being used for input parameters;therefore ct_param() cannot be called.”

78 = “There are no rows affected.”

79 = “The bind of result set item %1! resulted in an overflow.”

80 = “The bind of result set item %1! resulted in an underflow.”

81 = “The bind of result set item %1! failed because an illegalprecision value was specified.”

82 = “The bind of result set item %1! failed because an illegal scalevalue was specified.”

83 = “The bind of result set item %1! failed due to a syntax error in thesource data.”

84 = “The bind of result set item %1! failed due to an illegal value inthe format field of a CS_DATAFMT structure.”

85 = “The bind of result set item %1! failed because the source fieldvalue was not within the domain of legal values.”

86 = “The bind of result set item %1! failed because of an attempt todivide by zero.”

Page -8


87 = “The bind of result set item %1! failed because Client-Librarywas unable to get a resource.”

88 = “The bind of result set item %1! failed. The cause of failure isunknown.”

89 = “The data for column %1! is NULL but no indicator wasavailable.”

90 = “The data for column %1! was truncated but no indicator wasavailable.”

91 = “The bind was missing for column %1!.”

92 = “A CS_IODESC structure must be set with ct_data_info() beforect_send_data() can be called.”

93 = “%1! bytes exceeds the amount of bytes specified for this senddata operation. Only %2! more bytes can be sent.”

94 = “The number of bytes specified for this send data operation havenot been sent. %1! more bytes need to be sent.”

95 = “The value %1! was truncated.”

96 = “No browse information exists.”

97 = “A CS_IODESC can only be retrieved for text or image columns.Column %1! is not a text or image column.”

98 = “A CS_IODESC cannot be retrieved for a column that has notbeen read. Column %1! has not been read.”

99 = “Capabilities cannot be set after a connection has beenestablished.”

100 = “Request capabilities cannot be set.”

101 = “There was a failure initializing the Client-Libray error cache.”

102 = “This option is not supported by server.”

103 = “This routine can be called only if the CS_HIDDEN_KEYSproperty has been set to CS_TRUE.”

104 = “This message should not be seen.”

105 = “There was an unexpected failure while retrieving key data.”

106 = “Column %1! is not a key column.”

107 = “Column %1! is not nullable. The key data for a column can beset to NULL only if the column accepts NULL values.”

108 = “The key data supplied for column %1! exceeds the maximumlength defined for the column.”



109 = “There was an unexpected failure while setting key data.”

110 = “A valid count does not exist for the descriptor.”

111 = “This message should not be seen.”

112 = “%1! rows affected.”

113 = “The command structure given to this routine containsnotification data or extended error data. This routine does not acceptsuch a command structure.”

114 = “Extended error data does not exist for message %1!.”

115 = “A remote password cannot be set when a connection to aserver exists.”

116 = “The server name/password combination supplied exceedsthe 255 byte limit enforced by Client-Library.”

117 = “The CS_DISABLE_POLL property must be set to CS_FALSEwhen this routine is called.”

118 = “Unable to open file %1!.”

119 = “The data must be NULL when defining CS_INPUTVALUEparameters for a ct_cursor(CS_CURSOR_DECLARE) command.”

120 = “The buffer must be NULL when the current result set consistsof format information only.”

121 = “There is no data associated with descriptor item %1!.”

122 = “Results are currently being fetched into this descriptor. Adescriptor count of %1! is less than the result set size of %2!.”

123 = “A descriptor has already been specified for the currentcommand.”

124 = “ct_param() has already been used to define parameters for thecommand.”

125 = “A descriptor of size %1! is not large enough for a result set ofsize %2!.”

126 = “Another command structure is using the descriptor.”

127 = “This routine cannot be called if ct_bind() has already beencalled for the result set.”

128 = “The datatype field of a CS_IODESC must be set to eitherCS_TEXT_TYPE or CS_IMAGE_TYPE.”

129 = “An invalid locale was supplied in the %1! structure.”

Page -10


130 = “An invalid precision or scale in the CS_NUMERIC orCS_DECIMAL value was supplied.”

131 = “A memory pool cannot be set or cleared if open connectionsexist on the context structure.”

132 = “The bind of result set item %1! resulted in truncation.”

133 = “No rows are affected. More result sets will follow.”

134 = “The specified id already exists on this connection.”

135 = “The specified id does not exist on this connection.”

136 = “A string of length 0 is not allowed for parameter %1!.”

137 = “A bind count of %1! is not consistent with the count suppliedfor existing binds. The current bind count is %2!.”

138 = “A data length of %1! exceeds the maximum length allowed for%2! data.”

139 = “Setting the precision or scale to CS_SRC_VALUE is allowedonly if the corresponding result set column is of type numeric ordecimal.”

140 = “Scale cannot be set greater than precision.”

141 = “%1! must be 0 or CS_UNUSED when %2! is NULL.”

142 = “This property can be used only in the appropriate Client-Library callback. This property cannot be used in main-line code.”

143 = “The maximum number of connections cannot be set to a valueless than the number of currently existing connections.”

144 = “This property can be used only if a cursor exists on thecommand structure.”

145 = “This property cannot be set when the command structure hasresults pending or has an open cursor.”

146 = “The CS_LOCALE structure supplied is not valid.”

147 = “This routine can be used only with the debug version ofClient-Library.”

148 = “The Client-Library async manager was not able to continue.This connection has been marked dead.”

149 = “The current row’s key has been partially set with ct_keydata().Every key column must be set with ct_keydata() before thisoperation can continue.”

150 = “This routine cannot be called because the context structure isin an undefined state. This is probably due to a ct_exit() failure.”



151 = “A connection to the server must exist on the connectionstructure before this routine can be called.”

152 = “A command structure must be supplied for aCS_CANCEL_CURRENT operation.”

153 = “This routine cannot be called when a connection to a serverexists on the CS_CONNECTION structure.”

154 = “This routine cannot be called because the connection structureis in an undefined state.”

155 = “This routine cannot be called when the command structure isidle.”

156 = “This routine cannot be called when a command has beeninitialized but not sent.”

157 = “This routine cannot be called until ct_results() has been calledfor the command that was sent to the server.”

158 = “This routine can be called only if fetchable results are availableto be read.”

159 = “This routine can be called only if the command structure isidle.”

160 = “This routine can be called only if the cursor rows are availableto be read.”

161 = “This routine can be called only if regular row results areavailable.”

162 = “A receive passthru operation is not legal while the connectionis in the middle of processing results in the standard manner.”

163 = “This routine cannot be called until all fetchable results havebeen completely processed.”

164 = “This routine can be called only if compute results areavailable.”

165 = “This routine cannot be called when a nested cursor commandis initialized.”

166 = “This routine cannot be called while the results of a nestedcursor command are not completely processed.”

167 = “This routine cannot be called because the command structureis in an undefined state.”

168 = “This routine cannot be called because a receive passthruoperation is in progress on this command structure.”

Page -12


169 = “This routine cannot be called because a send passthruoperation is in progress on this command structure.”

170 = “This routine cannot be called after ct_results() returns a resulttype of CS_DESCRIBE_RESULT.”

171 = “A cursor must be opened before this command type can beinitialized.”

172 = “This routine cannot be called because the CS_COMMANDstructure is in the middle of a send data operation.”

173 = “A return status of CS_PENDING must be returned from acompletion callback if additional async operations have beeninitiated.”

174 = “A context structure must be supplied when setting/clearingthis type of callback.”

175 = “There is not a callback handler installed for signal %1!.”

176 = “The server does not support null parameters of type %1!.”

177 = “The length of the null-terminated string parameter %1!exceeds the maxium length allowed.”

178 = “This routine cannot be called until at least one call toct_send_data() has been made.”

179 = “A cursor row must be fetched before this command can beinitialized.”

180 = “This command must come immediately after aCS_CURSOR_DECLARE command has been initialized.”

181 = “This command is not allowed when the cursor is closed.”

182 = “This command is not allowed after all the cursor’s rows havebeen fetched.”

If Layer = 2 (cslib user api layer), the meaning of Number is:

0 = “No error.”

1 = “Unknown error.”

2 = “The information being retrieved will not fit in a buffer of %1!bytes.”

3 = “Memory allocation failure.”

4 = “The parameter %1! cannot be NULL.”

5 = “When %1! is NULL the %2! parameter must be 0.”



6 = “An illegal value of %1! was given for parameter %2!.”

7 = “The %1! parameter must be NULL.”

8 = “The %1! parameter must be set to CS_UNUSED.”

9 = “The property %1! cannot be set or cleared.”

10 = “An invalid locale pointer was passed in.”

11 = “The parameter %1! points to an illegal datatype value.”

12 = “An unknown locale name was passed in.”

13 = “A CS_GET operation cannot be performed on type %1!.”

14 = “Localization information could not be loaded.”

15 = “Error handling could not be initialized.”

16 = “Conversion between %1! and %2! datatypes is not supported.”

17 = “The format field of a CS_DATAFMT structure should beCS_FMT_UNUSED when the datatype is %1!.”

18 = “An illegal value of %1! was placed in the %2! field of theCS_DATAFMT structure.”

19 = “An illegal locale pointer was specified in the CS_DATAFMTstructure.”

20 = “The conversion/operation resulted in overflow.”

21 = “The conversion/operation resulted in underflow.”

22 = “An illegal precision value was encountered.”

23 = “An illegal scale value was encountered.”

24 = “The conversion/operation was stopped due to a syntax error inthe source field.”

25 = “The datatype value is outside the domain of legal values for thedatatype.”

26 = “A division by zero is not allowed.”

27 = “WARNING: Existing error and message handlers have beendeinstalled.”

28 = “There was not enough memory available to save messages. Allpreviously stored messages have been cleared.”

29 = “In-line error handling must be initialized with the CS_INIToperation before any other cs_diag() action may be taken.”

30 = “The message limit cannot be set to a value less than the numberof CS-Library messages currently saved.”

Page -14


31 = “The context structure cannot be dropped because theapplication has not exited from %1!.”

32 = “When the type is CS_DT_CONFMT only a CS_SET operation isallowed.”

33 = “The requested translation is not supported.”

34 = “Some of the characters could not be translated.”

35 = “The conversion/operation stopped due to a style error.”

36 = “The result is truncated because the conversion/operationresulted in overflow.”

37 = “cs_ctx_name failed to match the given keys.”

38 = “The string was not copied because this would result inoverflow.”

39 = “The string could not be built. An illegal place holder was foundin the text string.”

40 = “Only 0, 1, or 2 stars are allowed in the format string.”

41 = “An unknown datatype token was found in the format string.”

42 = “The format string cannot be NULL.”

43 = “The custom format specifier is too long.”

44 = “A custom format specifier was not found to match the specifierin the format string.”

45 = “Bad locale handler for cs_locale on types CS_SYB_LANG,CS_SYB_CHARSET or CS_SYB_LANG_CHARSET.”

46 = “Can not access localization file %1!.”

47 = “%1! Connection exception -- Connection does not exist.”

48 = “%1! Connection exception -- Connection name in use.”

49 = “%1! Invalid cursor name.”

50 = “%1! Invalid SQL statement identifier.”

51 = “%1! cs_objects: error performing requested operation.”

52 = “An internal buffer overflow occurs.”



If Layer = 3 (generic protocol layer), Number has no meaning.

If Layer = 4 (protocol specific layer), the meaning of Number is:

1 = “There is a tds protocol error. Premature end of the datastreamwas encountered.”

2 = “There is a tds protocol error. An illegal tds version wasreceived.”

3 = “There is a tds protocol error. An illegal login status wasreceived.”

4 = “There is a tds protocol error. There are too many bytes in thedatastream.”

5 = “memory allocation failure.”

6 = “There is a tds protocol error. Duplicate ALT ID was seen whileprocessing results.”

7 = “There is a tds protocol error. Invalid ALT operator was seenwhile processing results.”

8 = “There is a tds protocol error. Invalid ALT id was seen whileprocessing results.”

9 = “There is a tds protocol error. Invalid ALT column count was seenwhile processing results.”

10 = “There is a tds protocol error. Invalid column number was seenwhile processing results.”

11 = “There is a tds protocol error. Invalid table index was seen whileprocessing results.”

12 = “There is a tds protocol error. An illegal browse status wasreceived.”

13 = “There is a tds protocol error. An illegal capability type wasreceived.”

14 = “There is a tds protocol error. An invalid cursor name wasreceived.”

15 = “There is a tds protocol error. A duplicate cursor id wasreceived.”

16 = “There is a tds protocol error. An invalid cursor id wasreceived.”

17 = “There is a tds protocol error. An invalid cursor row count wasreceived.”

Page -16


18 = “There is a tds protocol error. An invalid cursor status wasreceived.”

19 = “There is a tds protocol error. An invalid done status wasreceived.”

20 = “There is a tds protocol error. An illegal DONEINPROC tokenstream was received.”

21 = “There is a tds protocol error. An invalid dynamic status wasreceived.”

22 = “There is a tds protocol error. An invalid dynamic statementlength was received.”

23 = “There is a tds protocol error. An invalid dynamic type wasreceived.”

24 = “There is a tds protocol error. An invalid dynamic id wasreceived.”

25 = “There is a tds protocol error. An invalid packet size wasreceived.”

26 = “There is a tds protocol error. An illegal ENVCHANGE type wasreceived.”

27 = “There is a tds protocol error. An invalid message status wasreceived.”

28 = “There is a tds protocol error. An illegal token was received.”

29 = “There is a tds protocol error. An invalid option command wasreceived.”

30 = “There is a tds protocol error. An invalid option type wasreceived.”

31 = “There is a tds protocol error. An invalid orderby stream wasreceived.”

32 = “There is a tds protocol error. A PARAMFMT was received withno parameters specified.”

33 = “There is a tds protocol error. An invalid PARAMFMT streamwas received.”

34 = “There is a tds protocol error. A ROWFMT was received with nocolumns specified.”

35 = “There is a tds protocol error. An invalid ROWFMT stream wasreceived.”

36 = “There is a tds state machine error. An illegal tds token sequencewas received.”



37 = “There is a tds state machine error. Attempted operation withresults pending. This is an internal error.”

38 = “There is a tds login error. Illegal number of parameters seenduring negotiation.”

39 = “There is a tds protocol error. An invalid message id wasreceived during login negotiation.”

40 = “There is a tds protocol error. An invalid column status wasreceived.”

41 = “There is a tds protocol error. An invalid datatype wasreceived.”

42 = “There is a tds protocol error. An invalid numeric precision wasreceived.”

43 = “There is a tds protocol error. An invalid numeric scale wasreceived.”

44 = “The attempt to connect to the server failed.”

45 = “There is an internal tds layer error. Access to the row buffermanager failed.”

46 = “There is a tds login error. An attempt was made by the server toencrypt a password, but no encryption handler was installed.”

47 = “There is a tds login error. The installed encryption handlerreturned a status that was not CS_SUCCEED.”

48 = “There is a tds login error. An attempt was made by the server toissue a security challenge, but no challenge handler was installed.”

49 = “There is a tds login error. The installed challenge handlerreturned a status that was not CS_SUCCEED.”

50 = “There is an internal tds layer error. An error was returned fromthe server while processing an internal tds stream.”

51 = “There is an internal tds layer error. An unexpected error wasreturned from common library.”

52 = “There is an internal tds layer error. An unexpected error wasreturned from the async manager.”

If Layer = 5 (network packet layer), the meaning of Number is:

1 = “There was an error encountered while closing the connection.”

2 = “There was an error encountered while releasing the address.”

3 = “There was an error encountered while resolving the address.”

Page -18


4 = “There was an error encountered while establishing theconnection.”

5 = “There was an error encountered while executing the expeditedwrite.”

6 = “There was an error while executing the network read.”

7 = “There was an error while executing the network write.”

8 = “There was an error encountered while opening the addressdictionary.”

9 = “There was an error encountered while closing the addressdictionary.”

10 = “A read was attempted on a connection already executing aread.”

11 = “A write was attempted on a connection already executing awrite.”

12 = “State error: trying to write when connection is expecting aread.”

13 = “State error: trying to read when connection is expecting awrite.”

14 = “Buffer is too small to fit a whole packet.”

15 = “Reading from the network while there remains unprocesseddata from the last read.”

16 = “There was an error encountered while getting the addressinformation.”

17 = “There was an error encountered while getting the addressproperty.”

18 = “There is a protocol packet error. An illegal length was received”

128 = “There was an error encountered while initializing networkoptions recordkeeping.”

129 = “There was an error encountered while setting a networkoption.”

130 = “unused.”

131 = “There was an error encountered while initializing Net-Library.”

132 = “There was an error encountered while initializing Net-Libraryengine.”



133 = “There was an error encountered while setting Net-Librarycallback.”

134 = “There was an error encountered while exiting Net-Libraryengine.”

135 = “There was an error encountered while exiting Net-Library.”

136 = “There was an error encountered while setting Net-Librarycallback mode.”

137 = “There was an error encountered while chaining signals in Net-Library.”

Page -20



D Sample Code for Error Handling D.

This appendix contains sample error handling code for EmbeddedSQL/C, Embedded SQL/COBOL, and Client-Library. You can usethese examples to help you write your own error handling code.

You can find additional sample programs in the TechnicalDocuments collection of Technical Library on the Web. To access theTechnical Library Web site, go to support.sybase.com, then go to theSupport Services tab and select the link to “Technical Documents”.Search the collection for these TechNote titles:




Open Client and Open Server Program Disclaimer

The Open Client and Open Servers applications and code in thisdocument have been created to provide ideas and help working withSybase connectivity libraries.

Please read this disclaimer before using the code:

This code is being distributed free of charge. It is not a Sybaseproduct, is not supported by sybase, and is provided “as-is”without warranty of any kind. Sybase disclaims all warranties orconditions, either express or implied, including without limitationany implied warranties of merchantability, merchantable quality,noninfringement and fitness for a particular purpose (whetherarising by statute or in law or as a result of a course of dealing orusage of trade). In no event shall Sybase be liable for loss of profitsor loss of data or any damages whatsoever including withoutlimitation direct, indirect, incidental, consequential or specialdamages, even if Sybase has been advised of the possibility ofsuch damages.

ctlib_client_msg_handler(ctx, conn, client_msgtxt)

Embedded SQL/C Error Handler

The following is a code fragment for handling errors in anEmbedded SQL/C application:

Page -2


/* ..../* Declare the SQLCA */EXEC SQL INCLUDE sqlca;

#define ERREXIT -1

/* Forward declarations of the error and message handlers */int error_handler();int warning_handler();

int main(){

.....EXEC SQL WHENEVER SQLERROR CALL error_handler();EXEC SQL WHENEVER NOT FOUND CONTINUE ;EXEC SQL WHENEVER SQLWARNING CALL warning_handler();

.....

exit(0);}

/*** void error_handler()****Displays error codes and numbers from the SQLCA and exits with**an ERREXIT status.*/void error_handler(){fprintf(stderr, “\n** SQLCODE=(%d)”, sqlca.sqlcode);

if (sqlca.sqlerrm.sqlerrml){

fprintf(stderr, “\n** %s”, sqlca.sqlerrm.sqlerrmc);}

fprintf(stderr, “\n\n”);

exit(ERREXIT);}

/*** void warning_handler()**



**Displays warning messages.*/void warning_handler(){

if (sqlca.sqlwarn[1] == ‘W’){

fprintf(stderr,“\n** Data truncated.\n”);

}

if (sqlca.sqlwarn[3] == ‘W’){

fprintf(stderr,“\n** Insufficient host variables to store results.\n”);

}return;}

** void error_handler()****Displays error codes and numbers from the SQLCA and exits with**an ERREXIT status.*/void error_handler(){fprintf(stderr, "\n** SQLCODE=(%d)", sqlca.sqlcode);

if (sqlca.sqlerrm.sqlerrml){

fprintf(stderr, "\n** SQL Server Error ");fprintf(stderr, "\n** %s", sqlca.sqlerrm.sqlerrmc);

}

fprintf(stderr, "\n\n");

exit(ERREXIT);}

/*** void warning_handler()****Displays warning messages.*/void warning_handler(){

Page -4


if (sqlca.sqlwarn[1] == 'W'){

fprintf(stderr,"\n** Data truncated.\n");

}

if (sqlca.sqlwarn[3] == 'W'){

fprintf(stderr,"\n** Insufficient host variables to store results.\n");

}return;}

Embedded SQL/COBOL Error Handler

The following is a code fragment for handling errors in anEmbedded SQL/COBOL application:

.......EXEC SQL INCLUDE SQLCA END-EXEC.

.......EXEC SQL WHENEVER SQLERROR PERFORM ERR-PARA END-EXECEXEC SQL WHENEVER SQLWARNING PERFORM WARN-PARA END-EXECEXEC SQL WHENEVER NOT FOUND CONTINUE END-EXEC.

.......

*************************************************************WARN-PARA.

DISPLAY "Warning code is " SQLCODE.

DISPLAY "Warning message is " SQLERRMC.

IF SQLWARN2 EQUAL "W"DISPLAY "A null value was eliminated from the argument

- " set of a function.".IF SQLWARN3 EQUAL "W"

DISPLAY "An into clause had too many or too few host- " variables.".

IF SQLWARN4 EQUAL "W"DISPLAY "A dynamic update or delete was lacking a

- " where clause.".IF SQLWARN5 EQUAL "W"

DISPLAY "A server conversion or truncation error- " occurred.".WARN-PARA-END.

EXIT.



*************************************************************ERR-PARA.** print the error code and the error message*

DISPLAY "Error code is " SQLCODE.DISPLAY "Error message is " SQLERRMC.

STOP RUN.*************************************************************

Client-Library Error Handler

The following is a code fragment for handling errors in a Client-Library application:

/* ctlib_client_msg_handler** print any client library warning or** error message. By default return a** CS_SUCCEED, so we do not mark the** connection as dead.*/CS_RETCODE CS_PUBLIC ctlib_client_msg_handler

(ctx, conn, client_msgtxt)CS_CONTEXT *ctx;CS_CONNECTION *conn;CS_CLIENTMSG *client_msgtxt;{

fprintf(stderr, "\nOPEN CLIENT ERROR MESSAGE");fprintf(stderr, "\nnumber: layer (%ld), origin (%ld)",

CS_LAYER(client_msgtxt->msgnumber),CS_ORIGIN(client_msgtxt->msgnumber));

fprintf(stderr, "\ntext:\n%s", client_msgtxt->msgstring);if (client_msgtxt->osstringlen > 0)

fprintf(stderr, "\nOS error : %s",client_msgtxt->osstring);

fprintf(stderr, "\nERROR HANDLER OUTPUT ENDS\n");fflush(stderr);return(CS_SUCCEED);

}

/* ctlib_server_msg_handler** print any server error message.

Page -6


*/CS_RETCODE CS_PUBLIC ctlib_server_msg_handler

(ctx, conn, srvr_msgtxt)CS_CONTEXT *ctx;CS_CONNECTION *conn;CS_SERVERMSG *srvr_msgtxt;{

fprintf(stderr, "\nSERVER MESSAGE");if (srvr_msgtxt->svrnlen > 0)

fprintf(stderr, " from server '%s'",srvr_msgtxt->svrname);

if (srvr_msgtxt->proclen > 0)fprintf(stderr, " at procedure '%s'",

srvr_msgtxt->proc);fprintf(stderr, "\nnumber (%ld), severity (%ld)",

srvr_msgtxt->msgnumber, srvr_msgtxt->severity);fprintf(stderr, "\nstate (%ld), line (%ld)",

srvr_msgtxt->state, srvr_msgtxt->line);fprintf(stderr, "\ntext:\n%s", srvr_msgtxt->text);

fprintf(stderr, "\nMESSAGE HANDLER OUTPUT ENDS\n");fflush(stderr);return(CS_SUCCEED);

}


E Sample Code for Handling LargeText and Image Data E.

The following are sample programs for Embedded SQL whichdemonstrate the use of host variables in handling large text andimage data.

You can find additional sample programs in the TechnicalDocuments collection of Technical Library on the Web. To access theTechnical Library Web site, go to support.sybase.com, then go to theSupport Services tab and select the link to “Technical Documents”.Search the collection for these TechNote titles:




text_image.sql

Use this script to create the table “text_tab” which you will use to runthe sample program in the following section:

use tempdbgo

if exists (select 1 from sysobjectswhere name = ‘text_tab’ and type = ‘U’ )drop table text_tabgo

create table text_tab (text_col text null,image_col image null)go

Page -2


text_image.cp

/* Program name: text_image.cp**** Description: Inserting text and image data using host** variables of types CS_TEXT and CS_IMAGE.

** Notes: This is a new feature in 11.x which allows you to use** host variables of type CS_TEXT and CS_IMAGE in insert** or update statements to handle text or image data. You don’t** need to use to mixed-mode client-library programming or** dynamic sql, which had a limit of 64 k bytes.** The size of the text or image data that can now be sent is** limited only by memory or the maximum size allowed for** text and image data by the SQL Server. However,** the larger the data being sent this way, the slower the** performance.**** Script file: text_image.sql**** Notes: Make sure you compile the program using the '-y'** precompiler flag.***/

#include <stdio.h>#include "sybsqlex.h"

/* Declare the SQLCA */EXEC SQL INCLUDE sqlca;

/*** Forward declarations of the error and message handlers and** other subroutines called from main().*/void error_handler();void warning_handler();

int main(){int i=0;

EXEC SQL BEGIN DECLARE SECTION;/* storage for login name and password */

CS_CHAR username[30], password[30];CS_TEXT text_var[10000];CS_IMAGE image_var[10000];



EXEC SQL END DECLARE SECTION;

EXEC SQL WHENEVER SQLERROR CALL error_handler();EXEC SQL WHENEVER SQLWARNING CALL warning_handler();EXEC SQL WHENEVER NOT FOUND CONTINUE;

/*** Copy the user name and password defined in sybsqlex.h to** the variables declared for them in the declare section.*/strcpy(username, USER);strcpy(password, PASSWORD);

/* Connect to the server and specify the database to use */EXEC SQL CONNECT :username IDENTIFIED BY :password;

EXEC SQL USE tempdb;

/* Put something interesting in the variables. */for (i=0; i< 10000; i++ ) {

text_var[i] = 'a';image_var[i] = '@';

}

EXEC SQL INSERT text_tab VALUES(:text_var, :image_var);if ( sqlca.sqlcode == 0 )

{printf("Row successfully inserted! \n");EXEC SQL COMMIT WORK ;}

EXEC SQL DISCONNECT ALL;exit(0);}

/*** void error_handler()**** Displays error codes and numbers from the SQLCA and exits with** an ERREXIT status.*/void error_handler(){fprintf(stderr, "\n** SQLCODE=(%d)", sqlca.sqlcode);

if (sqlca.sqlerrm.sqlerrml)

Page -4


{fprintf(stderr, "\n** Error Message: ");fprintf(stderr, "\n** %s", sqlca.sqlerrm.sqlerrmc);}

fprintf(stderr, "\n\n");

exit(ERREXIT);}

/*** void warning_handler()**** Displays warning messages.*/void warning_handler(){

if (sqlca.sqlwarn[1] == 'W'){fprintf(stderr,"\n** Data truncated.\n");}

if (sqlca.sqlwarn[3] == 'W'){fprintf(stderr,"\n** Insufficient host variables to store results.\n");}

return;}

text_image.pco

IDENTIFICATION DIVISION.PROGRAM-ID. EXAMPLE1.ENVIRONMENT DIVISION.CONFIGURATION SECTION.SOURCE-COMPUTER. xyz.OBJECT-COMPUTER. xyz.DATA DIVISION.WORKING-STORAGE SECTION.

* text_image.pco

* This program uses text and image types (new to 11.1)* to insert large text and image values into the database.



* NOTE: The entire buffer of image and text data is sent* to the server regardless of content. The size of the* buffer is determined by its ESQL declaration. It is* therefore important to declare only the size that you* need for these datatypes.* You must pre-compile with the -y flag to use this feature.

EXEC SQL INCLUDE SQLCA END-EXEC.EXEC SQL BEGIN DECLARE SECTION END-EXEC .

* userid and password

01 UID PIC X(30).01 PASS PIC X(30).

*input from database

01 TEXT-VAR PIC X(20) USAGE IS CS-TEXT.01 IMG-VAR PIC X(20) USAGE IS CS-IMAGE.

EXEC SQL END DECLARE SECTION END-EXEC.

PROCEDURE DIVISION.P0.

EXEC SQL WHENEVER SQLERROR PERFORM ERR-PARA END-EXEC.EXEC SQL WHENEVER SQLWARNING PERFORM WARN-PARA END-EXEC.EXEC SQL WHENEVER NOT FOUND CONTINUE END-EXEC.

* NOTE: fill in your user name and password here.MOVE "sa" TO UID.MOVE "" TO PASS.

EXEC SQL CONNECT :UID IDENTIFIED BY :PASS END-EXEC.EXEC SQL USE tempdb END-EXEC.

* Fill up the text and image structure.MOVE "HELLO WORLD" TO TEXT-VAR.MOVE "0X12345" TO IMG-VAR.

EXEC SQL INSERT text_tab VALUES(:TEXT-VAR, :IMG-VAR)END-EXEC

EXEC SQL COMMIT WORK END-EXEC.

STOP RUN.

Page -6


*************************************************************WARN-PARA.

DISPLAY "Warning code is " SQLCODE.

DISPLAY "Warning message is " SQLERRMC.

IF SQLWARN1 EQUAL "W"DISPLAY "Data has been truncated.".

IF SQLWARN2 EQUAL "W"DISPLAY "A null value was eliminated from the argument

- " set of a function.".IF SQLWARN3 EQUAL "W"

DISPLAY "An into clause had too many or too few host- " variables.".

IF SQLWARN4 EQUAL "W"DISPLAY "A dynamic update or delete was lacking a

- where" clause.".IF SQLWARN5 EQUAL "W"

DISPLAY "A server conversion or truncation error- " occurred.".WARN-PARA-END.

EXIT.

*************************************************************ERR-PARA.** print the error code, the error message and the line number of* the command that caused the error.*

DISPLAY "Error code is " SQLCODE.

DISPLAY "Error message is " SQLERRMC.

STOP RUN.*************************************************************

Date post:	21-Feb-2015
Category:	Documents
Upload:	sadiq-basha
View:	701 times
Download:	3 times