Open Client/Server™ Programmer's Supplement for Macintosh and ...

696 views
652 views

Published on

0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total views
696
On SlideShare
0
From Embeds
0
Number of Embeds
0
Actions
Shares
0
Downloads
1
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

Open Client/Server™ Programmer's Supplement for Macintosh and ...

  1. 1. Open Client/Server™ Programmer’s Supplement for Macintosh and Power Macintosh Open Client/Server Release 11.1.x Document ID: 32662-01-1110-01 Last Revised: May 15, 1997
  2. 2. Principal author: Patricia Quinn Contributing authors: Carl Edwards Document ID: 32662-01-1110 This publication pertains to Open Client/Server Release 11.1.x of the Sybase database management software and to any subsequent release until otherwise indicated in new editions or technical notes. Information in this document is subject to change without notice. The software described herein is furnished under a license agreement, and it may be used or copied only in accordance with the terms of that agreement. Document Orders To order additional documents, U.S. and Canadian customers should call Customer Fulfillment at (800) 685-8225, fax (617) 229-9845. Customers in other countries with a U.S. license agreement may contact Customer Fulfillment via the above fax number. All other international customers should contact their Sybase subsidiary or local distributor. Upgrades are provided only at regularly scheduled software release dates. Copyright © 1989–1997 by Sybase, Inc. All rights reserved. No part of this publication may be reproduced, transmitted, or translated in any form or by any means, electronic, mechanical, manual, optical, or otherwise, without the prior written permission of Sybase, Inc. Sybase Trademarks Sybase, the Sybase logo, APT-FORMS, Certified SYBASE Professional, Data Workbench, Deft, First Impression, GainExposure, Gain Momentum, PowerBuilder, Powersoft, Replication Server, S-Designor, SQL Advantage, SQL Debug, SQL SMART, SQL Solutions, Transact-SQL, VisualWriter, and VQL are registered trademarks of Sybase, Inc. Adaptable Windowing Environment, Adaptive Server, ADA Workbench, AnswerBase, Application Manager, AppModeler, APT-Build, APT-Edit, APT-Execute, APT-Library, APT-Translator, APT Workbench, Backup Server, BayCam, Bit-Wise, Client-Library, Client/Server Architecture for the Online Enterprise, Client/Server for the Real World, Client Services, CodeBank, Column Design, Connection Manager, DataArchitect, Database Analyzer, DataExpress, Data Pipeline, DataWindow, DB-Library, Deft Analyst, Deft Designer, Deft Educational, Deft Professional, Deft Trial, Designor, Developers Workbench, Dimensions Anywhere, Dimensions Enterprise, Dimensions Server, DirectCONNECT, Easy SQR, Embedded SQL, EMS, Enterprise Builder, Enterprise Client/Server, Enterprise CONNECT, Enterprise Manager, Enterprise SQL Server Manager, Enterprise Work Architecture, Enterprise Work Designer, Enterprise Work Modeler, EWA, Formula One, Gateway Manager, GeoPoint, InfoMaker, InformationCONNECT, Intermedia Server, InternetBuilder, iScript, KnowledgeBase, MainframeCONNECT, Maintenance Express, MAP, MDI, MDI
  3. 3. Access Server, MDI Database Gateway, media.splash, MetaWorks, MethodSet, Movedb, Navigation Server Manager, Net-Gateway, NetImpact, Net-Library, New Media Studio, ObjectCONNECT, ObjectCycle, OmniCONNECT, OmniSQL Access Module, OmniSQL Server, OmniSQL Toolkit, Open Client, 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, PowerBuilt, PowerBuilt with PowerBuilder, PowerScript, PowerSocket, Powersoft Portfolio, Power Through Knowledge, 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 Anywhere, SQL Central, SQL Code Checker, SQL Edit, SQL Edit/TPU, SQL Remote, SQL Server, SQL Server/CFT, SQL Server/DBM, SQL Server Manager, SQL Server Monitor, SQL Server SNMP SubAgent, SQL Station, SQL Toolset, StarDesignor, Sybase Client/Server Interfaces, Sybase Development Framework, Sybase Dimensions, Sybase Gateways, Sybase Intermedia, Sybase Interplay, Sybase IQ, Sybase MPP, Sybase SQL Desktop, Sybase SQL Lifecycle, Sybase SQL Workgroup, Sybase Synergy Program, Sybase Virtual Server Architecture, Sybase User Workbench, SybaseWare, SyBooks, System 10, System 11, the System XI logo, SystemTools, Tabular Data Stream, The Architecture for Change, The Enterprise Client/Server Company, The Online Information Center, Turning Imagination Into Reality, Visual Components, VisualSpeller, Warehouse WORKS, Watcom, Watcom SQL, Watcom SQL Server, web.sql, WebSights, WebViewer, WorkGroup SQL Server, XA-Library, and XA-Server are trademarks of Sybase, Inc. 1/97 All other company and product names used herein may be trademarks or registered trademarks of their respective companies. Restricted Rights Use, duplication, or disclosure by the government is subject to the restrictions set forth in subparagraph (c)(1)(ii) of DFARS 52.227-7013 for the DOD and as set forth in FAR 52.227-19(a)-(d) for civilian agencies. Sybase, Inc., 6475 Christie Avenue, Emeryville, CA 94608.
  4. 4. Table of Contents About This Book Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi How to Use This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi Documentation Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii Related Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii Other Sources of Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii Electronic Information Sources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv If You Need Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv 1. Building Macintosh and Power Macintosh Applications Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1 Open Client/Server Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1 C Compilers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1 Header Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2 CFM Import/Dynamic Link Libraries (DLLs) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3 CFM Import Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3 CFM Dynamic Link Libraries (DLLs) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3 Configuration Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3 Platform-Specific Default Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4 Client-Library Programming Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5 ct_callback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5 Using the Debug DLLs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5 Multithreaded Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5 Example Compile and Link Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6 DB-Library Programming Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7 Standard Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7 Compile and Link Line Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7 Server-Library Programming Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9 srv_callback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9 Scheduling Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9 Multithreaded Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9 Example Compile and Link Operations . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10 Open Client/Server Supplement for Macintosh and Power Macintosh v
  5. 5. Open Client/Server Release 11.1.x 2. Using Open Client Client-Library/C Example Programs Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1 Macintosh Example Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1 How to Use the Example Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2 General Requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2 Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2 Header Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3 example.h File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4 Client-Library Example Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6 Utility Routines for the Example Programs . . . . . . . . . . . . . . . . . . . . . . . . 2-6 firstapp.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6 exconfig.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7 Bulk -Library Example Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7 Compute Rows Example Program. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7 Read-Only Cursor Example Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8 Asynchronous Example Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8 text and image Example Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9 Localization and Internationalization Example . . . . . . . . . . . . . . . . . . . . . 2-9 Multithreaded Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9 RPC Command Example Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10 Directory Service Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10 3. Using Open Client DB-Library/C Example Programs Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1 Macintosh Example Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1 How to Use the Example Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1 General Requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2 Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2 Header Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3 example.h Header. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3 DB-Library Example Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6 Send Queries, Bind, and Print Results. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6 Insert Data into a New Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7 Bind Aggregate and Compute Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7 Row Buffering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7 Data Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7 Browse Mode Updates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7 Browse Mode and Ad Hoc Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8 RPC Command Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8 Text and Image Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8 vi Table of Contents
  6. 6. Open Client/Server Release 11.1.x Inserting an Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9 Retrieving an Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9 International Language Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-10 Bulk-Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-10 Two-Phase Commit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-10 4. Using Open Server Server-Library/C Example Programs Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1 Macintosh Example Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1 How to Use the Example Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2 General Requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2 Location and Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2 Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3 Header Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4 Server-Library Example Programs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4 Testing Example Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5 Open Server Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5 Gateway Open Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5 srv_language Event Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6 TDS Passthrough Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6 Registered Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7 International Languages and Character Sets . . . . . . . . . . . . . . . . . . . . . . . 4-7 Multithreaded Programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7 A. Using isql Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1 Using isql . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1 New Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2 Additional Commands Within isql: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6 Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-7 See Also . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-9 B. Building CFM Applications with Open Client/Server for Macintosh Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1 Open Client Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1 Open Client/Server Supplement for Macintosh and Power Macintosh vii
  7. 7. Open Client/Server Release 11.1.x Specifying the Location of Sybase Header Files. . . . . . . . . . . . . . . . . . . . . B-1 Compiling, Linking, and Building an Application Using CodeWarrior B-1 Index viii Table of Contents
  8. 8. List of Tables Table 1: Product documentation list.......................................................................................... xii Table 2: Syntax conventions....................................................................................................... xiv Table 1-1: Open Client/Server header files .................................................................................1-2 Table 1-2: Open Client/Server DLLs ............................................................................................1-3 Table 1-3: Client-Library platform-specific properties...............................................................1-4 Table 2-1: Required header files for Client-Library applications..............................................2-3 Table 4-1: Tracing options...............................................................................................................4-3 Open Client/Server Supplement for Macintosh and Power Macintosh ix
  9. 9. Open Client/Server Release 11.1.x x List of Tables
  10. 10. About This Book This book supplements the Open Client/Server™ reference manuals and programmer’s guide. It provides the platform-specific information you need to create, configure, and troubleshoot applications using Open Client/Server products for the following desktop platforms: • Macintosh (68K) • Power Macintosh (PowerPC) Audience The audiences for this book are: • Desktop application developers who create Sybase® or third- party applications using Open Client/Server products • Anyone who needs information about the isql utility How to Use This Book You only need to read the sections of this book that are relevant to your operating environment and system requirements. This section helps you determine which portions of the book to read and provides a content overview of each chapter. Chapter 1, “Building Macintosh and Power Macintosh Applications,” is the only platform-specific chapter in this book. If you build applications with Client-Library™, DB-Library™, or Server-Library, read the chapter that applies to your platform. If you want to experiment with the example programs, refer to the chapter that contains the example programs for the Open Client/Server Library product in which you are interested. ® Note The Macintosh 68K platform does not support the Open Server Library. Open Client/Server Supplement for Macintosh and Power Macintosh xi
  11. 11. Related Documents Open Client/Server Release 11.1.x Documentation Overview This book is organized as follows: • Chapter 1, “Building Macintosh and Power Macintosh Applications,” provides Macintosh and Power Macintosh- specific information for application developers who use Open Client/Server libraries. • Chapter 2, “Using Open Client Client-Library/C Example Programs,” provides information about Client-Library™ example programs. • Chapter 3, “Using Open Client DB-Library/C Example Programs,” provides information about DB-Library™ example programs. • Chapter 4, “Using Open Server Server-Library/C Example Programs,” provides information about Open Server™ example programs. • Appendix A, “Using isql,” explains how to use isql—the Open Client interactive SQL utility. • Appendix B, “Building CFM Applications with Open Client/Server for Macintosh,” explains how to build an Open Client/Server application using CodeWarrior. It provides compiler-specific information that complements the general information discussed in previous Open Client/Server chapters. If you have not yet installed the products, see the Open Client/Server Installation and Configuration Guide for Macintosh and Power Macintosh and the Release Bulletin for information about installation. Related Documents Each Open Client/Server product has its own set of user documentation. Table 1 lists the products and their related documents: Table 1: Product documentation list Product Related documentation Client-Library Open Client Client-Library/C Reference Manual Open Client and Open Server Common Libraries Reference Manual Open Client Client-Library/C Programmer’s Manual DB-Library Open Client DB-Library/C Reference Manual xii About This Book
  12. 12. Open Client/Server Release 11.1.x Other Sources of Information Table 1: Product documentation list Product Related documentation Server-Library Open Server Server-Library Reference Manual Open Client and Open Server Common Libraries Reference Manual Open Client Client-Library Reference Manual See the Open Client/Server Installation and Configuration Guide for your platform for information on installation, folder structure, and logical names, and for information on how to: • Set up your environment so that Open Client™ applications and servers can communicate • Localize Sybase applications Other Sources of Information For information on developing applications on your platform, see the documentation provided by the platform vendor. Electronic Information Sources For the most up-to-date information on Sybase products, including information on availability, certifications, bugs, and troubleshooting, refer to Sybase’s electronic services: • AnswerBase™, Sybase’s CD-ROM knowledge base • Sybase OpenLine and PrivateLine, the Sybase forums on CompuServe • The SupportPlusSM Online Services and SyBooks-on-the-Web World Wide Web pages SupportPlus Online Services and SyBooks-on-the-Web To get to SupportPlus Online Services and Sybooks-on-the-Web: 1. Connect to the Sybase home page: www.sybase.com. 2. Follow links to Services and Support. 3. Follow links to Sybase Enterprise Technical Support. 4. Follow links to SupportPlus Online Services or SyBooks-on-the- Web. Open Client/Server Supplement for Macintosh and Power Macintosh xiii
  13. 13. Conventions Open Client/Server Release 11.1.x SyBooks-on-the-Web is accessible to the public. SupportPlus Online Services is intended for customer use only. Therefore, you must register to access SupportPlus Online Services. Conventions The conventions for syntax statements in this manual are shown in Table 2: Table 2: Syntax conventions Key Definition command Command names, command option names, utility names, utility flags, and other keywords are shown in bold Helvetica. variable Variables, or words that stand for values that you fill in, are shown in italics. ENVIRONMENT Environment variables, or settings reserved for VARIABLE values specific to the operating environment of Sybase Open Client/Server products, are shown in uppercase. { } Curly braces indicate that you must choose at least one of the enclosed options. Do not include braces in your option. [ ] Brackets mean that choosing one or more of the enclosed options is optional. Do not include brackets in your option. ( ) Parentheses are to be typed as part of the command. | The vertical bar means that you may select only one of the options shown. , The comma means that you may choose as many options as you like. Separate your choices with commas. The following examples illustrate the syntax conventions described above. Use of vertical bars means that you must choose one and only one option within the curly braces. {red | yellow | blue} xiv About This Book
  14. 14. Open Client/Server Release 11.1.x If You Need Help Use of commas means that you can choose one or more of the options within the curly braces. If you choose more than one, separate your choices with commas. {cash, check, credit} Brackets indicate optional parameters. You don’t have to choose any of the items in square brackets. One item in square brackets means that you can omit it entirely. [anchovies] Use of vertical bars means that you can choose none or only one within the square brackets. [beans | rice | sweet_potatoes] Commas within square brackets means that you can choose none, one, or more options. If you choose more than one, separate your choices with commas. [extra_cheese, avocados, sour_cream] ® Note Environment variables are settings reserved for values specific to the operating environment of Sybase Open Client/Server products. While environment variables may be unfamiliar to Macintosh and Power Macintosh users, they are used on many Sybase platforms to provide values to Open Client/Server products. Therefore, to remain consistent, the term is also used in this manual. Open Client/Server for Macintosh and Power Macintosh acquires its environment variables from the Sybase Preferences file. Use the ocs config utility to modify these values. For detailed information, see the Open Client/Server Installation and Configuration Guide for Macintosh and Power Macintosh. If You Need Help Each Sybase installation that has purchased a support contract has one or more designated people who are authorized to contact Sybase Technical Support. If you cannot resolve your problem using your documentation, have a designated person contact Sybase Technical Support. Open Client/Server Supplement for Macintosh and Power Macintosh xv
  15. 15. If You Need Help Open Client/Server Release 11.1.x Please contact the distributor from which your software was purchased if you do not know how to contact Sybase Technical Support. xvi About This Book
  16. 16. 1 Building Macintosh and Power Macintosh Applications 1. Introduction This chapter explains how to start building Macintosh and Power Macintosh applications using Open Client/Server libraries and describes the requirements for building Macintosh and Power Macintosh executables using Sybase libraries. The chapter includes these sections: • Open Client/Server Requirements 1-1 • Header Files 1-2 • CFM Import/Dynamic Link Libraries (DLLs) 1-3 • Configuration Requirements 1-3 • Platform-Specific Default Values 1-4 • Client-Library Programming Issues 1-5 • DB-Library Programming Issues 1-7 • Server-Library Programming Issues 1-9 Open Client/Server Requirements Certain criteria must be met before you compile and link Open Client/Server applications on the Macintosh. You must: • Have an ANSI-compliant C compiler installed • Add the Sybase:Include folder to the Access Path • Add the Sybase Libraries to the Project file or makefile • Have the Sybase CFM libraries located in the Applications or Extensions folder • Have at least one Open Client Net-Library driver for Macintosh to make a network connection to the server. C Compilers You must have an ANSI-compliant C compiler installed that supports targeting Power Macintosh or CFM-68K type applications. Open Client/Server Supplement for Macintosh and Power Macintosh 1-1
  17. 17. Header Files Open Client/Server Release 11.1.x Certified compilers are listed in the Release Bulletin for your platform and release level. Sybase may certify other compilers after the Release Bulletin is published. Check with your Sybase sales representative for a list of currently certified compilers. x WARNING! If you have problems using an ANSI-compliant C compiler that Sybase has not certified, Sybase will provided technical support only if the problems can be reproduced using a Sybase-certified compiler. Header Files Table 1-1 lists header files that you need to include when you compile Open Client/Server applications. Table 1-1: Open Client/Server header files DB-Library Header Files Client-Library Header Files Server-Library Header Files sybdb.h – contains definitions and type ctpublic.h – required by all ospublic.h – required by all definitions for use with DB-Library Client-Library applications. Server-Library applications. routines. Use sybdb.h only as documented This file includes all other This file includes all other in the Open Client DB-Library/C Reference required header files. required header files. Manual. The sybdb.h file includes all other bkpublic.h – required if your bkpublic.h – required if your required header files. application makes calls to application makes calls to ssybfront.h – defines symbolic constants Bulk-Library. This file Bulk-Library. This file such as function return values, described includes all other required includes all other required in the Open Client DB-Library/C Reference header files. header files. Manual, and the exit values STDEXIT and ERREXIT. sybfront.h also includes type definitions for datatypes that can be used in program variable declaration. ssyberror.h – contains error severity values and should be included if the program refers to those values. 1-2 Building Macintosh and Power Macintosh Applications
  18. 18. Open Client/Server Release 11.1.x CFM Import/Dynamic Link Libraries (DLLs) CFM Import/Dynamic Link Libraries (DLLs) CFM Import Libraries Use the CFM libraries in your project when you compile and link applications. CFM Dynamic Link Libraries (DLLs) At run time, 68K Macintosh and Power Macintosh Open Client/Server applications must be able to call functions in the Open Client/Server CFM libraries. Make sure that the Sybase CFM libraries are either in your application’s folder or the System:Extensions folder. Table 1-2 lists the DLLs that come with Open Client/Server libraries. Table 1-2: Open Client/Server DLLs DB-Library DLLs Client-Library DLLs Server-Library DLLs libsybdb DB-Library libct Client-Library libct Client-Library libintl Localization libcs CS-Library libcs CS-Library support library libtcl Transport libintl Localization libintl Localization Control Layer support support library Library libcomn Internal libtcl Transport libtcl Transport common Control Layer Control Layer library libcomn Internal libcomn Internal common common library library libblk Bulk-Library libsrv Server-Library libblk Bulk-Library Configuration Requirements The following configuration and system requirements must be met if the example programs and your applications are to run properly: • The SYBASE environment variable must be defined. Open Client/Server Supplement for Macintosh and Power Macintosh 1-3
  19. 19. Platform-Specific Default Values Open Client/Server Release 11.1.x • The interfaces file must have a query entry for the server name used by Open Client applications. • The interfaces file must have a query entry for the server name used by Open Server applications. • You must have a minimum of 8MB of memory. The performance of complex applications benefits from having 16MB or more of memory available. ® Note For information on setting the SYBASE environment variable and configuring the interfaces file, see the Open Client/Server Installation and Configuration Guide for Macintosh and Power Macintosh. Platform-Specific Default Values Table 1-3 lists Open Client/Server properties with platform-specific default values. Table 1-3: Client-Library platform-specific properties Default Value on Library Property Name Description Macintosh/PowerPC Client-Library CS_IFILE The path and name of the The interfaces file in the and interfaces file. root folder defined by Server-Library the SYBASE environment variable. CS_MAX_CONNECT The maximum number of 25 connections for this context. CS_PACKETSIZE The TDS packet size. 512 bytes DB-Library DBSETFILE The path and name of the The interfaces file in the interfaces file. root folder defined by the SYBASE environment variable. DBSETMAXPROS The maximum number of 25 connections for this context. 1-4 Building Macintosh and Power Macintosh Applications
  20. 20. Open Client/Server Release 11.1.x Client-Library Programming Issues Client-Library Programming Issues This section explains the differences between how certain Client- Library routines behave on Macintosh and Power Macintosh and how they are documented in the Open Client Client-Library/C Reference Manual and the Open Client Client-Library/C Programmer’s Guide. ct_callback It is not necessary to declare a Client-Library application routine that is registered with Client-Library via ct_callback as CS_PUBLIC. However, doing so ensures portability with platforms on which this is required (including Windows, Windows NT, and OS/2). See the routine ex_clientmsg_cb in exutils.c in the Sybase_root:sample folder for an example. Using the Debug DLLs Depending on the install options you selected, Client-Library debug and non-debug versions of libct could both be installed.The debug version of the DLL is stored in the Sybase devlib folder; the non- debug version is stored in the lib folder. Copy the version you want to use to System Folder:Extensions:Sybase. ct_debug functions only when you use the debug version of libct. Refer to the Open Client Client-Library/C Reference Manual for general information about the debug version of Client-Library. Multithreaded Support Client-Library release 11.1 supports the Macintosh Thread Manager library for the development of multithreaded applications. For an overview of this process, refer to the Open Client Client-Library/C Reference Manual. Open Client/Server uses Macintosh cooperative threads for thread support. When using the Open Client library in either sync, deferred, or async mode, your application needs to periodically call the Thread Manager function YieldToAnyThread. A good location to call YieldToAnyThread is in the application’s main event loop. For the best performance, call YieldToAnyThread more often than WaitNextEvent. Open Client/Server Supplement for Macintosh and Power Macintosh 1-5
  21. 21. Client-Library Programming Issues Open Client/Server Release 11.1.x Example Compile and Link Operations This section shows an example makefile for a Macintosh Client- Library application for use by Metrowerks MPW C Compiler. 68K Macintosh: mwc68k -indirect -intsize 4 -dsize 80 ∂ -model CFMflatdf -model far -nosyspath -sym off ∂ exutils.c ∂ -o exutils.c.o ∂ -prefix "MacHeaders.h" ∂ -i ":::include:" mwc68k ∂ -indirect -intsize 4 -dsize 80 ∂ -model CFMflatdf -model far -nosyspath -sym off ∂ compute.c ∂ -o compute.c.o ∂ -prefix "MacHeaders.h" ∂ -i ":::include:" MWLink68K -xm a -sym off -o "compute"∂ -model CFMflatdf ∂ compute.c.o ∂ exutils.c.o ∂ "{MW68KLibraries}ANSI (N/4i/8d) C.CFM68K.Lib" ∂ "{MW68KLibraries}MWCFM68KRuntime.Lib" ∂ "{MW68KLibraries}SIOUX.CFM68K.Lib" ∂ "{MW68KLibraries}MathLibCFM68K (4i/8d).Lib" ∂ "{MW68KLibraries}InterfaceLib" ∂ "{MW68KLibraries}NuThreadsLib.slb" ∂ ":::lib:libct" ∂ ":::lib:libcs" ∂ ":::lib:libcomn" ∂ ":::lib:libtcl" ∂ ":::lib:libintl" Rez -a -d __kPrefSize=2500 -d __kMinSize=2500 ∂ "{RIncludes}"SIOW.r -o compute Power Macintosh: mwcppc -sym off -nosyspath exutils.c ∂ -o exutils.c.o ∂ -prefix "MacHeaders.h" ∂ -i ":::include:" 1-6 Building Macintosh and Power Macintosh Applications
  22. 22. Open Client/Server Release 11.1.x DB-Library Programming Issues mwcppc -sym off -nosyspath compute.c ∂ -o compute.c.o ∂ -prefix "MacHeaders.h" ∂ -i ":::include:" MWLinkPPC -xm e -sym off -o "compute"∂ compute.c.o ∂ exutils.c.o ∂ "{MWPPCLibraries}ANSI (NL) C.PPC.Lib" ∂ "{MWPPCLibraries}MWCRuntime.Lib" ∂ "{MWPPCLibraries}InterfaceLib" ∂ "{MWPPCLibraries}MathLib" ∂ "{MWPPCLibraries}ThreadsLib" ∂ "{MWPPCLibraries}SIOUX.PPC.Lib" ∂ ":::lib:libct" ∂ ":::lib:libcs" ∂ ":::lib:libcomn" ∂ ":::lib:libtcl" ∂ ":::lib:libintl" Rez -a -d __kPrefSize=2500 -d __kMinSize=2500 ∂ "{RIncludes}"SIOW.r -o compute DB-Library Programming Issues This section explains the differences between how certain DB- Library routines behave on the Macintosh and Power Macintosh platforms and how these routines are documented in the Open Client DB-Library/C Reference Manual. Standard Output Typically, Open Client/Server DB-Library output writes to stdout or stderr. On the Macintosh and Power Macintosh, since there is no stdout or stderr, output is redirected to a file named sybdbg.out. When you use debugging calls such as dbprhead or dbprrow, the output is written to sybdbg.out. Compile and Link Line Examples The general form of the command to compile and link a DB-Library/C application is: Open Client/Server Supplement for Macintosh and Power Macintosh 1-7
  23. 23. DB-Library Programming Issues Open Client/Server Release 11.1.x 68K Macintosh: mwc68k ∂ -indirect -intsize 4 -dsize 80 ∂ -model CFMflatdf -model far -nosyspath -sym off ∂ example1.c ∂ -o example1.c.o ∂ -prefix "MacHeaders.h" ∂ -i ":::include:" MWLink68K -xm a -sym off -o "example1"∂ -model CFMflatdf ∂ example1.c.o ∂ "{MW68KLibraries}ANSI (N/4i/8d) C.CFM68K.Lib" ∂ "{MW68KLibraries}MWCFM68KRuntime.Lib" ∂ "{MW68KLibraries}SIOUX.CFM68K.Lib" ∂ "{MW68KLibraries}MathLibCFM68K (4i/8d).Lib" ∂ "{MW68KLibraries}InterfaceLib" ∂ "{MW68KLibraries}NuThreadsLib.slb" ∂ ":::lib:libsybdb" ∂ ":::lib:libcs" ∂ ":::lib:libcomn" ∂ ":::lib:libtcl" ∂ ":::lib:libintl" Rez -a -d __kPrefSize=2500 -d __kMinSize=2500 ∂ "{RIncludes}"SIOW.r -o examples Power Macintosh: mwcppc -sym off -nosyspath example1.c ∂ -o example1.c.o ∂ -prefix "MacHeaders.h" ∂ -i ":::include:" MWLinkPPC -xm e -sym off -o "example1"∂ example1.c.o ∂ "{MWPPCLibraries}ANSI (NL) C.PPC.Lib" ∂ "{MWPPCLibraries}MWCRuntime.Lib" ∂ "{MWPPCLibraries}InterfaceLib" ∂ "{MWPPCLibraries}MathLib" ∂ "{MWPPCLibraries}ThreadsLib" ∂ "{MWPPCLibraries}SIOUX.PPC.Lib" ∂ ":::lib:libsybdb" ∂ ":::lib:libcs" ∂ ":::lib:libcomn" ∂ ":::lib:libtcl" ∂ ":::lib:libintl" 1-8 Building Macintosh and Power Macintosh Applications
  24. 24. Open Client/Server Release 11.1.x Server-Library Programming Issues Rez -a -d __kPrefSize=2500 -d __kMinSize=2500 ∂ "{RIncludes}"SIOW.r -o examples Server-Library Programming Issues This section explains the differences between how certain Server- Library routines behave on the Power Macintosh platform and how these routines are documented in the Open Server Server-Library/C Reference Manual. ® Note Open Server is not available for 68K Macintosh. srv_callback Any Server-Library application routine that is registered with Server-Library via srv_callback must be declared as CS_PUBLIC. See the routine cs_err_handler in utils.c in the sample folder for an example. Scheduling Modes Server-Library applications running under Power Macintosh can only operate in co-routine scheduling mode. Multithreaded Support Server-Library release 11.1.x supports the Macintosh Thread Manager library for the development of multithreaded applications. For an overview of this process, refer to the Open Client Client- Library/C Reference Manual. Open Client/Server uses Macintosh cooperative threads for thread support. When using the Open Server Library, your application should periodically call the Thread Manager function YieldToAnyThread. A good location to call YieldToAnyThread is in the application’s main event loop. For the best performance, call YieldToAnyThread more often than WaitNextEvent. Open Client/Server Supplement for Macintosh and Power Macintosh 1-9
  25. 25. Server-Library Programming Issues Open Client/Server Release 11.1.x Example Compile and Link Operations The following example shows a makefile for compiling and linking a Server-Library application: Power Macintosh: mwcppc -sym off -nosyspath utils.c ∂ -o utils.c.o ∂ -prefix "MacHeaders.h" ∂ -i ":::include:" mwcppc -sym off -nosyspath lang.c ∂ -o lang.c.o ∂ -prefix "MacHeaders.h" ∂ -i ":::include:" MWLinkPPC -xm e -sym off -o "lang"∂ lang.c.o ∂ utils.c.o ∂ "{MWPPCLibraries}ANSI (NL) C.PPC.Lib" ∂ "{MWPPCLibraries}MWCRuntime.Lib" ∂ "{MWPPCLibraries}InterfaceLib" ∂ "{MWPPCLibraries}MathLib" ∂ "{MWPPCLibraries}ThreadsLib" ∂ "{MWPPCLibraries}SIOUX.PPC.Lib" ∂ ":::lib:libsrv" ∂ ":::lib:libct" ∂ ":::lib:libcs" ∂ ":::lib:libcomn" ∂ ":::lib:libtcl" ∂ ":::lib:libintl" Rez -a -d __kPrefSize=4000 -d __kMinSize=4000 ∂ "{RIncludes}"SIOW.r -o lang 1-10 Building Macintosh and Power Macintosh Applications
  26. 26. 2 Using Open Client Client-Library/C Example Programs 2. Introduction Open Client Client-Library is a collection of routines that you use to write client applications. The example programs in this chapter demonstrate Client-Library and CS-Library functions. This chapter contains the following sections: • Macintosh Example Application 2-1 • How to Use the Example Programs 2-2 • General Requirements 2-2 • Location 2-2 • Header Files 2-3 • Client-Library Example Programs 2-6 Client-Library includes routines that send commands to a server and other routines that process the results of those commands. Other routines set application properties, handle error conditions, and provide a variety of information about an application’s interaction with a server. CS-Library, which is included with Open Client, is a collection of utility routines that you can use to write either an Open Client or an Open Server application. All Client-Library applications include at least one call to CS-Library, because Client-Library routines use a structure which is allocated in CS-Library. Macintosh Example Application The Macintosh example project demonstrates how to use Client- Library with the Thread Manager and an Event Loop. The sample project, ctsample.π, combines all of the Client-Library examples into one application, which is accessible through the sample menu. The Macintosh-specific source files are located in the :sample:mac support: folder under the Sybase installation folder. Open Client/Server Supplement for Macintosh and Power Macintosh 2-1
  27. 27. How to Use the Example Programs Open Client/Server Release 11.1.x When you choose a sample from the menu, a thread is spawned to run the sample, while the main application thread processes the Event Loop. How to Use the Example Programs The System 11™ example programs demonstrate specific Client- Library/C functions. These programs are designed as guides for application programmers, not as Client-Library/C training aids. Read the descriptions at the top of each source file and examine the source code before you use the example programs. These simplified programs are not intended for use in a production environment. Programs written for a production environment need additional code to handle errors and special cases. General Requirements Before you run the Open Client examples, you must: • Set the SYBASE environment variable to the path of the Sybase installation folder (if it has not already been set). • Set the DSQUERY environment variable to the server name (server_name) to which you want to connect. • Use the CodeWarrior project file to produce a sample executable named example_name. For detailed information regarding the configuration of your environment and variables, refer to the Open Client/Server Installation and Configuration Guide for Macintosh and Power Macintosh. Location The Client-Library example programs are located in the :sample:ctlibrary: folder of the Sybase installation folder. This folder contains: • Online source code for the example programs • Data files for the examples • The header file, example.h, for the examples • The header file, ex_port.h, for platform-specific defines 2-2 Using Open Client Client-Library/C Example Programs
  28. 28. Open Client/Server Release 11.1.x Header Files • The source file, ex_mac.c, for the menu interface when building the ctsample application ® Note Create a backup copy of the examples folder contents. Then you can experiment with the examples without affecting the integrity of the original files. Sample project files are located in the :sample:ctlibrary:CFM(PPC): folder and the :sample:CFM:(68K): folder of the Sybase installation folder. These folders contain: • The project file, ctsample.π, for a Macintosh-style application that combines all of the Client-Library examples • The project file, firstapp.π, for a “console-style” application for the firstapp.c example Header Files Table 2-1 describes the header files that are required by all Client- Library applications: Table 2-1: Required header files for Client-Library applications. File Description Incudes ctpublic.h Required by all application Definitions of symbolic constants source files that contain calls used by Client-Library routines to Client-Library. Declarations for Client-Library routines cspublic.h The CS-Library header file. Definitions of common client/server symbolic constants Type definitions for common client/server structures Declarations for CS-Library routines bkpublic.h Required in all application source files that make calls to bulk-copy routines cstypes.h Contains type definitions for Client-Library datatypes Open Client/Server Supplement for Macintosh and Power Macintosh 2-3
  29. 29. Header Files Open Client/Server Release 11.1.x Table 2-1: Required header files for Client-Library applications. (continued) File Description Incudes sqlca.h Contains a type definitions for the SQLCA define structure example.h File All of the example programs reference the example header file, example.h. The contents of example.h are as follows: /* ** example.h ** ** This is the header file that goes with the Sybase ** Client-Library example programs. ** ** */ /* Sccsid %Z% %M% %I% %G% */ /* ** Define symbolic names, constants, and macros */ #include <ex_port.h> /* ** entrypoints for samples programs ** if EX_COMBINE_SAMPLES is not defined ** we will use ‘main’ as the entrypoint. */ #if EX_COMBINE_SAMPLES int ex_blktxt PROTOTYPE((CS_VOID)); int ex_compute PROTOTYPE((CS_VOID)); int ex_csr_disp PROTOTYPE((CS_VOID)); int ex_exasync PROTOTYPE((CS_VOID)); int ex_getsend PROTOTYPE((CS_VOID)); int ex_i18n PROTOTYPE((CS_VOID)); int ex_rpc PROTOTYPE((CS_VOID)); int ex_exconfig PROTOTYPE((CS_VOID)); int ex_usedir PROTOTYPE((CS_VOID)); int ex_multthrd PROTOTYPE((CS_VOID)); #define EX_BLKTXT ex_blktxt #define EX_COMPUTE ex_compute #define EX_CSR_DISP ex_csr_disp #define EX_EXASYNC ex_exasync 2-4 Using Open Client Client-Library/C Example Programs
  30. 30. Open Client/Server Release 11.1.x Header Files #define EX_GETSEND ex_getsend #define EX_I18N ex_i18n #define EX_RPC ex_rpc #define EX_EXCONFIG ex_exconfig #define EX_USEDIR ex_usedir #define EX_MULTTHRD ex_multthrd #else /* EX_COMBINE_SAMPLES */ #define EX_BLKTXT main #define EX_COMPUTE main #define EX_CSR_DISP main #define EX_EXASYNC main #define EX_GETSEND main #define EX_I18N main #define EX_RPC main #define EX_EXCONFIG main #define EX_USEDIR main #define EX_MULTTHRD main #endif /* EX_COMBINE_SAMPLES */ #define EX_MAXSTRINGLEN 255 #define EX_BUFSIZE 1024 #define EX_NAMEBUFSIZE 64 #define EX_CTLIB_VERSION CS_VERSION_110 /* ** Define global variables used in all sample programs */ #define EX_SERVER ““ /* use DSQUERY env var */ #define EX_USERNAME “sa” #define EX_PASSWORD ““ These changes have been made to EX_USERNAME and EX_PASSWORD: • EX_USERNAME is defined in example.h as “sa”. Before you run the example programs, you must edit example.h and change “sa” to your server login name. • EX_PASSWORD is defined in example.h as “ ”. Before running the example programs, you may want to edit example.h and change “ ” to your server password. There are three ways to use EX_PASSWORD. Choose the one that best meets your needs: Open Client/Server Supplement for Macintosh and Power Macintosh 2-5
  31. 31. Client-Library Example Programs Open Client/Server Release 11.1.x - Method 1 – Change your server password to “server_password” while you run the examples. This creates the possibility of a security breach. While your password is set to this published value, an unauthorized person could log into the server as you. If this presents a problem, choose another way to handle passwords for the example programs. - Method 2 – In example.h, change the string “server_password” to your own server password. Use the operating system’s protection mechanisms to prevent others from accessing the header file while you are using it. When you finish with the examples, edit the line so that it again reads “server_password”. - Method 3 – In the example programs, delete the ct_con_props code that sets the server password and substitute your own code to prompt users for their server passwords. (Because this code is platform-specific, Sybase does not supply it.) Client-Library Example Programs Example programs are included online with Client-Library to demonstrate typical uses for Client-Library routines. Some example programs use the sample databases supplied with SQL Server. Refer to your installation guide for information on installing the sample databases. The example programs are C source files. The appropriate compiler must be installed on your platform if you plan to use the Client-Library example programs or build applications. Utility Routines for the Example Programs The exutils.c file contains utility routines that are used by all other Client-Library example programs. It demonstrates how an application can hide some of the implementation details of Client- Library from a higher-level program. For more information about these routines, see the leading comments in the example source file. firstapp.c The firstapp.c example is an introductory example that connects to the server, sends a select query, and prints the rows. This example is 2-6 Using Open Client Client-Library/C Example Programs
  32. 32. Open Client/Server Release 11.1.x Client-Library Example Programs discussed in Chapter 1, “Getting Started With Client-Library,” in the Open Client Client-Library/C Programmer’s Guide. exconfig.c The exconfig.c example program demonstrates how Client-Library application properties can be configured externally. This example requires that you edit the default run time configuration file, Sybase_home:config:ocs.cfg. The example sets the CS_CONFIG_BY_SERVERNAME Client-Library property and calls ct_connect with a server_name parameter set to “server1”. In response, Client-Library looks for a [Server1] section in the external configuration file. To run the example, create Sybase_home:config:ocs.cfg (if necessary), and add the section: [server1] CS_SERVERNAME = real_server_name where real_server_name is the name of the server that you want to connect to. For more information on how Client-Library uses external configuration files, see the topics page “Using the Run-Time Configuration File” in the Open Client Client-Library/C Reference Manual. Bulk -Library Example Program In the blktxt.c example program, bulk-library routines copy static data to a server table. In this program, three rows of data that are bound to program variables are sent to the server as a batch. The rows are sent again using blk_textxfer to send the text data. For more information about this example program, see the leading comments in the example source file. This example requires SQL Server release 10.0 or later. Compute Rows Example Program The compute.c example program demonstrates processing compute results. It sends a canned query to the server via a language command. It processes the results using the standard ct_results while loop. It binds the column values to program variables. It then fetches and displays the rows in the standard ct_fetch while loop. Open Client/Server Supplement for Macintosh and Power Macintosh 2-7
  33. 33. Client-Library Example Programs Open Client/Server Release 11.1.x This is the canned query: select type, price from titles where type like "%cook" order by type, price compute sum(price) by type compute sum(price) This query returns both regular rows and compute rows. The compute rows are generated by the two compute clauses. The first compute clause, “compute sum(price) by type”, generates a compute row each time the value of type changes. The second compute clause, “compute sum(price)”, generates one compute row, which is the last to be returned. For more information about this example program, see the leading comments in the example source file. This example requires the pubs2 database and the titles table. Read-Only Cursor Example Program The csr_disp.c example program demonstrates the use of a read-only cursor. It opens a cursor with a canned query. It processes the results using the standard ct_results while loop. It binds the column values to program variables. It then fetches and displays the rows in the standard ct_fetch while loop. This is the canned query: select au_fname, au_lname, postalcode from authors For more information about this example program, see the leading comments in the example source file. This example requires SQL Server release 10.0 or later, the pubs2 database, and the authors table. Asynchronous Example Program This example program contains two files, ex_alib.c and ex_amain.c, which demonstrate how to write an asynchronous layer on top of Client-Library. It uses hooks provided by Client-Library to allow seamless polling and use of Client-Library’s completion callbacks. The example program comprises two files: 2-8 Using Open Client Client-Library/C Example Programs
  34. 34. Open Client/Server Release 11.1.x Client-Library Example Programs • ex_alib.c contains the source code of the library portion of the example. It is meant to be part of a library interface that supports asynchronous calls. This module provides a way to send a query to and retrieve the results from a server in one asynchronous operation. • ex_amain.c contains the source code of the main program that uses the services provided by ex_alib.c. For more information about this example program, see the leading comments in the example source file and the EX_AREAD.ME file. This example requires SQL Server release 10.0 or later. text and image Example Program The getsend.c example program demonstrates how to retrieve and update text data from a table containing text and other datatypes. The process demonstrated could also be used for retrieving and updating image data. If it connects to an Open Server application, the Open Server application must be able to handle language commands intended for SQL Server. For more information about this example program, see the leading comments in the example source files. This example requires SQL Server release 10.0 or later, the pubs2 database, and the authors table. Localization and Internationalization Example The i18n.c example program demonstrates some of the international features available in Client-Library, including: • Localized error messages • User-defined bind types For more information about this example program, see the leading comments in the example source file. Multithreaded Example This example program contains two files, multthrd.c and thrdfunc.c, which demonstrate a multithreaded Client-Library application. The example program comprises two files: Open Client/Server Supplement for Macintosh and Power Macintosh 2-9
  35. 35. Client-Library Example Programs Open Client/Server Release 11.1.x • multthrd.c contains the source code that spawns five threads. Each thread processes a cursor or a regular query. The main thread waits until other threads complete query processing, then terminates. • thrdfunc.c contains platform specific information that determines which thread and synchronization routines the example uses for execution. For more information about this example program, see the leading comments in the example source files. This example requires SQL Server release 10.0 or later. RPC Command Example Program The RPC (remote procedure call) command example program, rpc.c, sends an RPC command to a server and processes the results. For more information about this example program, see the leading comments in the example source file. This example requires SQL Server release 10.0 or later. Directory Service Example The directory service example program, usedir.c, queries a directory service for a list of available servers. usedir.c searches for Sybase server entries in the default directory, as defined in the driver configuration file. First usedir.c queries the interfaces file for server entries, then it displays a description of each entry found and lets the user choose a server with which to connect. For more information about this example program, see the leading comments in the example source file. 2-10 Using Open Client Client-Library/C Example Programs
  36. 36. 3 Using Open Client DB-Library/C Example Programs 3. Introduction Open Client DB-Library is a collection of routines that you can use to writing client applications. The example programs in this chapter demonstrate DB-Library functions. This chapter contains the following sections: • Macintosh Example Application 3-1 • How to Use the Example Programs 3-1 • General Requirements 3-2 • Location 3-2 • Header Files 3-3 • DB-Library Example Programs 3-6 DB-Library includes routines that send commands to a server and others that process the results of those commands. Other routines set application properties, handle error conditions, and provide a variety of information about an application’s interaction with a server. Macintosh Example Application The Macintosh example project demonstrates how to use DB-Library with the Thread Manager and an Event Loop. The sample project, dbsample.π, combines all of the DB-Library examples into one application, which is accessible through the sample menu. The Macintosh-specific source files are located in the :sample:mac support: folder under the Sybase installation folder. When you choose a sample from the menu, a thread is spawned to run the sample while the main application thread processes the Event Loop. How to Use the Example Programs The System 11 example programs demonstrate specific DB-Library/C functions. These programs are designed as guides for Open Client/Server Supplement for Macintosh and Power Macintosh 3-1
  37. 37. General Requirements Open Client/Server Release 11.1.x application programmers, not as DB-Library/C training aids. Read the descriptions at the top of each source file and examine the source code before you use the sample programs. These simplified programs are not intended for use in a production environment. Programs written for a production environment need additional code to handle errors and special cases. General Requirements Before you run the DB-Library examples, you must: • Set the SYBASE environment variable to the path of the Sybase installation folder (if it has not already been set). • Set the DSQUERY environment variable to the server name (server_name) to which you want to connect. • Use the CodeWarrior project file to produce a sample executable named example_name. For detailed information regarding the configuration of your environment and variables, refer to the Open Client/Server Installation and Configuration Guide for Macintosh and Power Macintosh. Location The DB-Library example programs are located in the :sample:dblibrary: folder of the Sybase installation folder. This folder contains: • Online source code for the example programs • Data files for the examples • The header file, example.h, for the examples • The header file, ex_port.h, for platform-specific defines • The source file, ex_mac.c, for the menu interface when building the dbsample application ® Note Create a backup copy of the examples folder contents. Then you can experiment with the examples without affecting the integrity of the original files. 3-2 Using Open Client DB-Library/C Example Programs
  38. 38. Open Client/Server Release 11.1.x Header Files Sample project files are located in the :sample:dblibrary:CFM(PPC): folder and the :sample:CFM(68K): folder of the Sybase installation folder. These folders contain: • The project file, dbsample.π, for a Macintosh-style application that combines all of the Client-Library examples • The project file, example1.π, for a “console-style” application for the example1.c example Header Files The following header files are required by all DB-Library/C applications: • sybfront.h defines symbolic constants, such as function return values (described in the Open Client DB-Library/C Reference Manual) and the exit values STDEXIT and ERREXIT. sybfront.h includes type definitions for datatypes that can be used in declaring program variables. • sybdb.h contains additional definitions and type definitions. Most of these are meant to be used only by DB-Library/C routines. Use sybdb.h only as documented in the Open Client DB-Library/C Reference Manual. • syberror.h contains error severity values and should be included if the program refers to those values. See the Open Client DB-Library/C Reference Manual for more information on header files. example.h Header All example programs reference the example header file, example.h. The contents of example.h are as follows: /* ** Confidential property of Sybase, Inc. ** (c) Copyright Sybase, Inc. 1992 to 1997 ** All rights reserved. */ /* ** %M%: %I% %G% %U% ** ** example.h ** */ Open Client/Server Supplement for Macintosh and Power Macintosh 3-3
  39. 39. Header Files Open Client/Server Release 11.1.x /* Sccsid %Z% %M% %I% %G% */ /* ** Define symbolic names, constants, and macros */ #include <ex_port.h> #if EX_COMBINE_SAMPLES /* ** Prototypes of samples */ int ex_example1 PROTOTYPE((CS_VOID)); int ex_example2 PROTOTYPE((CS_VOID)); int ex_example3 PROTOTYPE((CS_VOID)); int ex_example4 PROTOTYPE((CS_VOID)); int ex_example5 PROTOTYPE((CS_VOID)); int ex_example6 PROTOTYPE((CS_VOID)); int ex_example7 PROTOTYPE((CS_VOID)); int ex_example8 PROTOTYPE((CS_VOID)); int ex_example9 PROTOTYPE((CS_VOID)); int ex_example10 PROTOTYPE((CS_VOID)); int ex_example11 PROTOTYPE((CS_VOID)); int ex_example12 PROTOTYPE((CS_VOID)); int ex_bulkcopy PROTOTYPE((CS_VOID)); int ex_twophase PROTOTYPE((CS_VOID)); #define EX_EXAMPLE1 ex_example1 #define EX_EXAMPLE2 ex_example2 #define EX_EXAMPLE3 ex_example3 #define EX_EXAMPLE4 ex_example4 #define EX_EXAMPLE5 ex_example5 #define EX_EXAMPLE6 ex_example6 #define EX_EXAMPLE7 ex_example7 #define EX_EXAMPLE8 ex_example8 #define EX_EXAMPLE9 ex_example9 #define EX_EXAMPLE10 ex_example10 #define EX_EXAMPLE11 ex_example11 #define EX_EXAMPLE12 ex_example12 #define EX_BULKCOPY ex_bulkcopy #define EX_TWOPHASE ex_twophase #else /* EX_COMBINE_SAMPLES */ #define EX_EXAMPLE1 main #define EX_EXAMPLE2 main #define EX_EXAMPLE3 main #define EX_EXAMPLE4 main #define EX_EXAMPLE5 main #define EX_EXAMPLE6 main #define EX_EXAMPLE7 main 3-4 Using Open Client DB-Library/C Example Programs
  40. 40. Open Client/Server Release 11.1.x Header Files #define EX_EXAMPLE8 main #define EX_EXAMPLE9 main #define EX_EXAMPLE10 main #define EX_EXAMPLE11 main #define EX_EXAMPLE12 main #define EX_BULKCOPY main #define EX_TWOPHASE main #endif /* EX_COMBINE_SAMPLES */ #defineEX_MAXSTRINGLEN 255 #defineEX_BUFSIZE 1024 #define EX_NAMEBUFSIZE 64 /* ** Defines used in all sample programs */ #define EX_SERVER ““ /* use DSQUERY env var */ #define EX_USERNAME “sa” #define EX_PASSWORD ““ #define EX_LANGUAGE “us_english” /* ** Defines used in twophase sample program */ #define EX_SERVER2 “TWOPHASE” /* must not be the same as EX_SERVER */ #define EX_USERNAME2 “sa” #define EX_PASSWORD2 ““ All the examples except the data conversion example program contain these lines: DBSETLUSER(login, EX_USERNAME); DBSETLPWD(login, EX_PASSWORD); These changes have been made to the EX_USERNAME, EX_PASSWORD, and EX_LANGUAGE variables: • EX_USERNAME is defined in example.h as “sa”. Before you run the example programs, you must edit example.h and change “user” to your server login name. • EX_PASSWORD is defined in example.h as ““. Before you run the example programs, you may want to edit example.h and change ““ to your server password. Open Client/Server Supplement for Macintosh and Power Macintosh 3-5
  41. 41. DB-Library Example Programs Open Client/Server Release 11.1.x There are three ways to use EX_PASSWORD. Choose the one that best meets your needs: - Method 1 – Change your server password to “server_password” while you run the examples. This creates the possibility of a security breach. While your password is set to this published value, an unauthorized person could log into the server as you. If this presents a problem, choose another way to handle passwords for the example programs. - Method 2 – In example.h, change the string “server_password” to your own server password. Use the operating system’s protection mechanisms to prevent others from accessing the header file while you use it. When you finish with the examples, edit the line so that it again reads “server_password”. - Method 3 – In the example programs, delete the DBSETLPWD code that sets the server password and substitute your own code to prompt users for their server passwords. (Because this code is platform-specific, Sybase does not supply it.) • EX_LANGUAGE is defined in example.h as “us_english”. If your server’s language is not “us_english,” you may want to edit example.h and change “us_english” to your server’s language. The international languages routine example program, exampl12.c, is the only example that references EX_LANGUAGE. DB-Library Example Programs Example programs are included online with DB-Library to demonstrate typical uses for DB-Library routines. Some example programs use the sample databases supplied with SQL Server. Refer to your installation guide for information on installing the sample databases. The example programs are C source files. The appropriate compiler must be installed on your platform if you plan to use the DB-Library example programs or build applications. Send Queries, Bind, and Print Results example1.c sends two queries to SQL Server in a single command batch, binds the results, and prints the returned rows of data. Access to SQL Server is required. 3-6 Using Open Client DB-Library/C Example Programs

×