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

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

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 Sybasedatabase management software and to any subsequent release until otherwiseindicated in new editions or technical notes. Information in this document issubject to change without notice. The software described herein is furnished undera license agreement, and it may be used or copied only in accordance with theterms of that agreement.

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–1997 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, APT-FORMS, Certified SYBASE Professional, DataWorkbench, Deft, First Impression, GainExposure, Gain Momentum, PowerBuilder,Powersoft, Replication Server, S-Designor, SQL Advantage, SQL Debug, SQLSMART, SQL Solutions, Transact-SQL, VisualWriter, and VQL are registeredtrademarks 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, BackupServer, BayCam, Bit-Wise, Client-Library, Client/Server Architecture for theOnline 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, DeftDesigner, Deft Educational, Deft Professional, Deft Trial, Designor, DevelopersWorkbench, Dimensions Anywhere, Dimensions Enterprise, Dimensions Server,DirectCONNECT, Easy SQR, Embedded SQL, EMS, Enterprise Builder, EnterpriseClient/Server, Enterprise CONNECT, Enterprise Manager, Enterprise SQL ServerManager, Enterprise Work Architecture, Enterprise Work Designer, EnterpriseWork Modeler, EWA, Formula One, Gateway Manager, GeoPoint, InfoMaker,InformationCONNECT, Intermedia Server, InternetBuilder, iScript,KnowledgeBase, MainframeCONNECT, Maintenance Express, MAP, MDI, MDI

Access Server, MDI Database Gateway, media.splash, MetaWorks, MethodSet,Movedb, Navigation Server Manager, Net-Gateway, NetImpact, Net-Library, NewMedia Studio, ObjectCONNECT, ObjectCycle, OmniCONNECT, OmniSQLAccess Module, OmniSQL Server, OmniSQL Toolkit, Open Client, OpenClientCONNECT, Open Client/Server, Open Client/Server Interfaces, OpenGateway, Open Server, Open ServerCONNECT, Open Solutions, Optima++, PB-Gen, PC APT-Execute, PC DB-Net, PC Net Library, PowerBuilt, PowerBuilt withPowerBuilder, PowerScript, PowerSocket, Powersoft Portfolio, 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 Anywhere, SQL Central, SQL CodeChecker, SQL Edit, SQL Edit/TPU, SQL Remote, SQL Server, SQL Server/CFT,SQL Server/DBM, SQL Server Manager, SQL Server Monitor, SQL Server SNMPSubAgent, SQL Station, SQL Toolset, StarDesignor, Sybase Client/ServerInterfaces, Sybase Development Framework, Sybase Dimensions, SybaseGateways, Sybase Intermedia, Sybase Interplay, Sybase IQ, Sybase MPP, SybaseSQL Desktop, Sybase SQL Lifecycle, Sybase SQL Workgroup, Sybase SynergyProgram, 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/ServerCompany, 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 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.

Open Client/Server Supplement for Macintosh and Power Macintosh v

Table of Contents

About This BookAudience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiHow to Use This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Documentation Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiRelated Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiOther Sources of Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

Electronic Information Sources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiiConventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xivIf You Need Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

1. Building Macintosh and Power Macintosh ApplicationsIntroduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1Open Client/Server Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1

C Compilers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1Header Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2CFM Import/Dynamic Link Libraries (DLLs) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3

CFM Import Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3CFM Dynamic Link Libraries (DLLs) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3

Configuration Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3Platform-Specific Default Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4Client-Library Programming Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5

ct_callback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5Using the Debug DLLs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5Multithreaded Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5Example Compile and Link Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6

DB-Library Programming Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7Standard Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7Compile and Link Line Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7

Server-Library Programming Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9srv_callback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9Scheduling Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9Multithreaded Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9Example Compile and Link Operations . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10

vi Table of Contents


2. Using Open Client Client-Library/C Example ProgramsIntroduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1Macintosh Example Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1How to Use the Example Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2General Requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2Header Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3

example.h File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4Client-Library Example Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6

Utility Routines for the Example Programs . . . . . . . . . . . . . . . . . . . . . . . . 2-6firstapp.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6exconfig.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7Bulk -Library Example Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7Compute Rows Example Program. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7Read-Only Cursor Example Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8Asynchronous Example Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8text and image Example Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9Localization and Internationalization Example . . . . . . . . . . . . . . . . . . . . . 2-9Multithreaded Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9RPC Command Example Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10Directory Service Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10

3. Using Open Client DB-Library/C Example ProgramsIntroduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1Macintosh Example Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1How to Use the Example Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1General Requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2Header Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3

example.h Header. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3DB-Library Example Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6

Send Queries, Bind, and Print Results. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6Insert Data into a New Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7Bind Aggregate and Compute Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7Row Buffering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7Data Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7Browse Mode Updates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7Browse Mode and Ad Hoc Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8RPC Command Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8Text and Image Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8

Open Client/Server Supplement for Macintosh and Power Macintosh vii


Inserting an Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9Retrieving an Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9International Language Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-10Bulk-Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-10Two-Phase Commit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-10

4. Using Open Server Server-Library/C Example ProgramsIntroduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1Macintosh Example Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1How to Use the Example Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2General Requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2Location and Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3Header Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4Server-Library Example Programs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4

Testing Example Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5Open Server Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5Gateway Open Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5srv_language Event Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6TDS Passthrough Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6Registered Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7International Languages and Character Sets . . . . . . . . . . . . . . . . . . . . . . . 4-7Multithreaded Programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7

A. Using isqlIntroduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1Using isql . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1

New Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2Additional Commands Within isql: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-7See Also . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-9

B. Building CFM Applications with Open Client/Server for MacintoshIntroduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1Open Client Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1

viii Table of Contents


Specifying the Location of Sybase Header Files. . . . . . . . . . . . . . . . . . . . . B-1Compiling, Linking, and Building an Application Using CodeWarrior B-1

Index

Open Client/Server Supplement for Macintosh and Power Macintosh ix

List of Tables

Table 1: Product documentation list .......................................................................................... xiiTable 2: Syntax conventions....................................................................................................... xivTable 1-1: Open Client/Server header files .................................................................................1-2Table 1-2: Open Client/Server DLLs ............................................................................................1-3Table 1-3: Client-Library platform-specific properties...............................................................1-4Table 2-1: Required header files for Client-Library applications..............................................2-3Table 4-1: Tracing options...............................................................................................................4-3

x List of Tables


Open Client/Server Supplement for Macintosh and Power Macintosh xi

About This Book

This book supplements the Open Client/Server™ reference manualsand programmer’s guide. It provides the platform-specificinformation you need to create, configure, and troubleshootapplications using Open Client/Server products for the followingdesktop 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 toyour operating environment and system requirements. This sectionhelps you determine which portions of the book to read andprovides a content overview of each chapter.

Chapter 1, “Building Macintosh and Power MacintoshApplications,” is the only platform-specific chapter in this book.

If you build applications with Client-Library™, DB-Library™, orServer-Library, read the chapter that applies to your platform. If youwant to experiment with the example programs, refer to the chapterthat contains the example programs for the Open Client/ServerLibrary product in which you are interested.

➤ NoteThe Macintosh 68K platform does not support the Open Server Library.

xii About This Book

Related Documents Open Client/Server Release 11.1.x

Documentation Overview

This book is organized as follows:

• Chapter 1, “Building Macintosh and Power MacintoshApplications,” provides Macintosh and Power Macintosh-specific information for application developers who use OpenClient/Server libraries.

• Chapter 2, “Using Open Client Client-Library/C ExamplePrograms,” provides information about Client-Library™example programs.

• Chapter 3, “Using Open Client DB-Library/C ExamplePrograms,” provides information about DB-Library™ exampleprograms.

• Chapter 4, “Using Open Server Server-Library/C ExamplePrograms,” provides information about Open Server™ exampleprograms.

• Appendix A, “Using isql,” explains how to use isql—the OpenClient interactive SQL utility.

• Appendix B, “Building CFM Applications with OpenClient/Server for Macintosh,” explains how to build an OpenClient/Server application using CodeWarrior. It providescompiler-specific information that complements the generalinformation discussed in previous Open Client/Server chapters.

If you have not yet installed the products, see the Open Client/ServerInstallation and Configuration Guide for Macintosh and Power Macintoshand the Release Bulletin for information about installation.

Related Documents

Each Open Client/Server product has its own set of userdocumentation. Table 1 lists the products and their relateddocuments:

Table 1: Product documentation list

Product Related documentation

Client-Library Open Client Client-Library/C Reference ManualOpen Client and Open Server Common Libraries Reference ManualOpen Client Client-Library/C Programmer’s Manual

DB-Library Open Client DB-Library/C Reference Manual

Open Client/Server Supplement for Macintosh and Power Macintosh xiii

Open Client/Server Release 11.1.x Other Sources of Information

See the Open Client/Server Installation and Configuration Guide for yourplatform for information on installation, folder structure, and logicalnames, and for information on how to:

• Set up your environment so that Open Client™ applications andservers can communicate

• Localize Sybase applications

Other Sources of Information

For information on developing applications on your platform, seethe documentation provided by the platform vendor.

Electronic Information Sources

For the most up-to-date information on Sybase products, includinginformation 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 onCompuServe

• The SupportPlusSM Online Services and SyBooks-on-the-WebWorld 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.

Server-Library Open Server Server-Library Reference ManualOpen Client and Open Server Common Libraries Reference ManualOpen Client Client-Library Reference Manual

Table 1: Product documentation list

Product Related documentation

xiv About This Book

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 inTable 2:

The following examples illustrate the syntax conventions describedabove.

Use of vertical bars means that you must choose one and only oneoption within the curly braces.

{red | yellow | blue}

Table 2: Syntax conventions

Key Definition

command Command names, command option names, utilitynames, utility flags, and other keywords are shownin bold Helvetica.

variable Variables, or words that stand for values that you fillin, are shown in italics.

ENVIRONMENTVARIABLE

Environment variables, or settings reserved forvalues specific to the operating environment ofSybase Open Client/Server products, are shown inuppercase.

{ } Curly braces indicate that you must choose at leastone of the enclosed options. Do not include braces inyour option.

[ ] Brackets mean that choosing one or more of theenclosed options is optional. Do not includebrackets in your option.

( ) Parentheses are to be typed as part of the command.

| The vertical bar means that you may select only oneof the options shown.

, The comma means that you may choose as manyoptions as you like. Separate your choices withcommas.

Open Client/Server Supplement for Macintosh and Power Macintosh xv

Open Client/Server Release 11.1.x If You Need Help

Use of commas means that you can choose one or more of the optionswithin the curly braces. If you choose more than one, separate yourchoices with commas.

{cash, check, credit}

Brackets indicate optional parameters. You don’t have to choose anyof 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 onewithin 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 yourchoices with commas.

[extra_cheese, avocados, sour_cream]

➤ NoteEnvironment 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 configutility to modify these values. For detailed information, see the OpenClient/Server Installation and Configuration Guide for Macintosh and PowerMacintosh.

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 your problem using yourdocumentation, have a designated person contact Sybase TechnicalSupport.

xvi About This Book

If You Need Help Open Client/Server Release 11.1.x

Please contact the distributor from which your software waspurchased if you do not know how to contact Sybase TechnicalSupport.

Open Client/Server Supplement for Macintosh and Power Macintosh 1-1

Building Macintosh andPower Macintosh Applications 1.

Introduction

This chapter explains how to start building Macintosh and PowerMacintosh applications using Open Client/Server libraries anddescribes the requirements for building Macintosh and PowerMacintosh executables using Sybase libraries. The chapter includesthese 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 OpenClient/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 orExtensions folder

• Have at least one Open Client Net-Library driver for Macintoshto make a network connection to the server.

C Compilers

You must have an ANSI-compliant C compiler installed thatsupports targeting Power Macintosh or CFM-68K type applications.

1

1-2 Building Macintosh and Power Macintosh Applications

Header Files Open Client/Server Release 11.1.x

Certified compilers are listed in the Release Bulletin for your platformand release level. Sybase may certify other compilers after the ReleaseBulletin is published. Check with your Sybase sales representative fora list of currently certified compilers.

◆ WARNING!If you have problems using an ANSI-compliant C compiler that Sybasehas not certified, Sybase will provided technical support only if theproblems can be reproduced using a Sybase-certified compiler.

Header Files

Table 1-1 lists header files that you need to include when youcompile 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 typedefinitions for use with DB-Libraryroutines. Use sybdb.h only as documentedin the Open Client DB-Library/C ReferenceManual. The sybdb.h file includes all otherrequired header files.

ssybfront.h – defines symbolic constantssuch as function return values, describedin the Open Client DB-Library/C ReferenceManual, and the exit values STDEXIT andERREXIT. sybfront.h also includes typedefinitions for datatypes that can be usedin program variable declaration.

ssyberror.h – contains error severityvalues and should be included if theprogram refers to those values.

ctpublic.h – required by allClient-Library applications.This file includes all otherrequired header files.

bkpublic.h – required if yourapplication makes calls toBulk-Library. This fileincludes all other requiredheader files.

ospublic.h – required by allServer-Library applications.This file includes all otherrequired header files.

bkpublic.h – required if yourapplication makes calls toBulk-Library. This fileincludes all other requiredheader files.


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 linkapplications.

CFM Dynamic Link Libraries (DLLs)

At run time, 68K Macintosh and Power Macintosh OpenClient/Server applications must be able to call functions in the OpenClient/Server CFM libraries. Make sure that the Sybase CFMlibraries are either in your application’s folder or theSystem:Extensions folder. Table 1-2 lists the DLLs that come withOpen Client/Server libraries.

Configuration Requirements

The following configuration and system requirements must be met ifthe example programs and your applications are to run properly:

• The SYBASE environment variable must be defined.

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 Localizationsupport library

libcs CS-Library libcs CS-Library

libtcl TransportControl Layer

libintl LocalizationsupportLibrary

libintl Localizationsupport library

libcomn Internalcommonlibrary



libcomn Internalcommonlibrary

libcomn Internalcommon library

libblk Bulk-Library libsrv Server-Library

libblk Bulk-Library


Platform-Specific Default Values Open Client/Server Release 11.1.x

• The interfaces file must have a query entry for the server nameused by Open Client applications.

• The interfaces file must have a query entry for the server nameused by Open Server applications.

• You must have a minimum of 8MB of memory. The performanceof complex applications benefits from having 16MB or more ofmemory available.

➤ NoteFor information on setting the SYBASE environment variable and

configuring the interfaces file, see the Open Client/Server Installation andConfiguration Guide for Macintosh and Power Macintosh.

Platform-Specific Default Values

Table 1-3 lists Open Client/Server properties with platform-specificdefault values.

Table 1-3: Client-Library platform-specific properties

Library Property Name Description Default Value onMacintosh/PowerPC

Client-LibraryandServer-Library

CS_IFILE The path and name of theinterfaces file.

The interfaces file in theroot folder defined bythe SYBASEenvironment variable.

CS_MAX_CONNECT The maximum number ofconnections for this context.

25

CS_PACKETSIZE The TDS packet size. 512 bytes

DB-Library DBSETFILE The path and name of theinterfaces file.

The interfaces file in theroot folder defined bythe SYBASEenvironment variable.

DBSETMAXPROS The maximum number ofconnections for this context.

25


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 andhow they are documented in the Open Client Client-Library/CReference Manual and the Open Client Client-Library/C Programmer’sGuide.

ct_callback

It is not necessary to declare a Client-Library application routine thatis registered with Client-Library via ct_callback as CS_PUBLIC.However, doing so ensures portability with platforms on which thisis required (including Windows, Windows NT, and OS/2). See theroutine ex_clientmsg_cb in exutils.c in the Sybase_root:sample folder foran example.

Using the Debug DLLs

Depending on the install options you selected, Client-Library debugand non-debug versions of libct could both be installed.The debugversion of the DLL is stored in the Sybase devlib folder; the non-debug version is stored in the lib folder. Copy the version you wantto use to System Folder:Extensions:Sybase. ct_debug functions onlywhen you use the debug version of libct.

Refer to the Open Client Client-Library/C Reference Manual for generalinformation about the debug version of Client-Library.

Multithreaded Support

Client-Library release 11.1 supports the Macintosh Thread Managerlibrary for the development of multithreaded applications. For anoverview of this process, refer to the Open Client Client-Library/CReference Manual.

Open Client/Server uses Macintosh cooperative threads for threadsupport. When using the Open Client library in either sync, deferred,or async mode, your application needs to periodically call the ThreadManager function YieldToAnyThread. A good location to callYieldToAnyThread is in the application’s main event loop. For the bestperformance, call YieldToAnyThread more often than WaitNextEvent.


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:"


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 Macintoshplatforms and how these routines are documented in the Open ClientDB-Library/C Reference Manual.

Standard Output

Typically, Open Client/Server DB-Library output writes to stdout orstderr. On the Macintosh and Power Macintosh, since there is nostdout or stderr, output is redirected to a file named sybdbg.out. Whenyou use debugging calls such as dbprhead or dbprrow, the output iswritten to sybdbg.out.

Compile and Link Line Examples

The general form of the command to compile and link aDB-Library/C application is:


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"


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 howthese routines are documented in the Open Server Server-Library/CReference Manual.

➤ NoteOpen Server is not available for 68K Macintosh.

srv_callback

Any Server-Library application routine that is registered withServer-Library via srv_callback must be declared as CS_PUBLIC. Seethe routine cs_err_handler in utils.c in the sample folder for an example.

Scheduling Modes

Server-Library applications running under Power Macintosh canonly operate in co-routine scheduling mode.

Multithreaded Support

Server-Library release 11.1.x supports the Macintosh ThreadManager 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 threadsupport. When using the Open Server Library, your applicationshould periodically call the Thread Manager functionYieldToAnyThread. A good location to call YieldToAnyThread is in theapplication’s main event loop. For the best performance, callYieldToAnyThread more often than WaitNextEvent.


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 aServer-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


Using Open Client Client-Library/CExample Programs 2.

Introduction

Open Client Client-Library is a collection of routines that you use towrite client applications.

The example programs in this chapter demonstrate Client-Libraryand CS-Library functions. This chapter contains the followingsections:

• Macintosh Example Application 2-1

• How to Use the Example Programs 2-2

• General Requirements 2-2

• Location 2-2


• Client-Library Example Programs 2-6

Client-Library includes routines that send commands to a server andother routines that process the results of those commands. Otherroutines set application properties, handle error conditions, andprovide a variety of information about an application’s interactionwith a server.

CS-Library, which is included with Open Client, is a collection ofutility routines that you can use to write either an Open Client or anOpen Server application. All Client-Library applications include atleast one call to CS-Library, because Client-Library routines use astructure 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-Libraryexamples into one application, which is accessible through thesample menu.

The Macintosh-specific source files are located in the:sample:mac support: folder under the Sybase installation folder.

2

2-2 Using Open Client Client-Library/C Example Programs

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 torun the sample, while the main application thread processes theEvent Loop.

How to Use the Example Programs

The System 11™ example programs demonstrate specific Client-Library/C functions. These programs are designed as guides forapplication programmers, not as Client-Library/C training aids.Read the descriptions at the top of each source file and examine thesource code before you use the example programs.

These simplified programs are not intended for use in a productionenvironment. Programs written for a production environment needadditional 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 Sybaseinstallation 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 executablenamed example_name.

For detailed information regarding the configuration of yourenvironment and variables, refer to the Open Client/Server Installationand 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 foldercontains:

• 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


Open Client/Server Release 11.1.x Header Files

• The source file, ex_mac.c, for the menu interface when buildingthe ctsample application

➤ NoteCreate 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 installationfolder. These folders contain:

• The project file, ctsample.π, for a Macintosh-style application thatcombines all of the Client-Library examples

• The project file, firstapp.π, for a “console-style” application for thefirstapp.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 applicationsource files that contain callsto Client-Library.

Definitions of symbolic constantsused by Client-Library routines

Declarations for Client-Libraryroutines

cspublic.h The CS-Library header file. Definitions of commonclient/server symbolic constants

Type definitions for commonclient/server structures

Declarations for CS-Libraryroutines

bkpublic.h Required in all applicationsource files that make callsto bulk-copy routines

cstypes.h Contains type definitionsfor Client-Library datatypes



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 theSybase** 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_SAMPLESint 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

sqlca.h Contains a type definitionsfor the SQLCA definestructure

Table 2-1: Required header files for Client-Library applications. (continued)

File Description Incudes



#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 sampleprograms*/#define EX_SERVER ““/* use DSQUERY env var*/#define EX_USERNAME “sa”#define EX_PASSWORD ““

These changes have been made to EX_USERNAME andEX_PASSWORD:

• EX_USERNAME is defined in example.h as “sa”. Before you runthe 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 theexample programs, you may want to edit example.h and change“ ” to your server password.

There are three ways to use EX_PASSWORD. Choose the onethat best meets your needs:


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 createsthe possibility of a security breach. While your password is setto this published value, an unauthorized person could log intothe server as you. If this presents a problem, choose anotherway 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’sprotection mechanisms to prevent others from accessing theheader file while you are using it. When you finish with theexamples, edit the line so that it again reads“server_password”.

- Method 3 – In the example programs, delete the ct_con_propscode that sets the server password and substitute your owncode to prompt users for their server passwords. (Because thiscode is platform-specific, Sybase does not supply it.)

Client-Library Example Programs

Example programs are included online with Client-Library todemonstrate typical uses for Client-Library routines. Some exampleprograms use the sample databases supplied with SQL Server. Referto your installation guide for information on installing the sampledatabases.

The example programs are C source files. The appropriate compilermust be installed on your platform if you plan to use theClient-Library example programs or build applications.

Utility Routines for the Example Programs

The exutils.c file contains utility routines that are used by all otherClient-Library example programs. It demonstrates how anapplication can hide some of the implementation details of Client-Library from a higher-level program.

For more information about these routines, see the leadingcomments in the example source file.

firstapp.c

The firstapp.c example is an introductory example that connects tothe server, sends a select query, and prints the rows. This example is


Open Client/Server Release 11.1.x Client-Library Example Programs

discussed in Chapter 1, “Getting Started With Client-Library,” in theOpen Client Client-Library/C Programmer’s Guide.

exconfig.c

The exconfig.c example program demonstrates how Client-Libraryapplication properties can be configured externally.

This example requires that you edit the default run timeconfiguration file, Sybase_home:config:ocs.cfg. The example sets theCS_CONFIG_BY_SERVERNAME Client-Library property and callsct_connect with a server_name parameter set to “server1”. In response,Client-Library looks for a [Server1] section in the externalconfiguration file. To run the example, createSybase_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 toconnect to.

For more information on how Client-Library uses externalconfiguration files, see the topics page “Using the Run-TimeConfiguration File” in the Open Client Client-Library/C ReferenceManual.

Bulk -Library Example Program

In the blktxt.c example program, bulk-library routines copy staticdata to a server table. In this program, three rows of data that arebound to program variables are sent to the server as a batch. Therows are sent again using blk_textxfer to send the text data.

For more information about this example program, see the leadingcomments 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 computeresults. It sends a canned query to the server via a languagecommand. It processes the results using the standard ct_results whileloop. It binds the column values to program variables. It then fetchesand displays the rows in the standard ct_fetch while loop.



This is the canned query:

select type, price from titleswhere type like "%cook"order by type, pricecompute sum(price) by typecompute sum(price)

This query returns both regular rows and compute rows. Thecompute rows are generated by the two compute clauses. The firstcompute clause, “compute sum(price) by type”, generates a computerow each time the value of type changes. The second compute clause,“compute sum(price)”, generates one compute row, which is the lastto be returned.


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-onlycursor. It opens a cursor with a canned query. It processes the resultsusing the standard ct_results while loop. It binds the column values toprogram variables. It then fetches and displays the rows in thestandard ct_fetch while loop.

This is the canned query:

select au_fname, au_lname, postalcodefrom authors


This example requires SQL Server release 10.0 or later, the pubs2database, 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 ofClient-Library. It uses hooks provided by Client-Library to allowseamless polling and use of Client-Library’s completion callbacks.

The example program comprises two files:


Open Client/Server Release 11.1.x Client-Library Example Programs

• ex_alib.c contains the source code of the library portion of theexample. It is meant to be part of a library interface that supportsasynchronous calls. This module provides a way to send a queryto and retrieve the results from a server in one asynchronousoperation.

• ex_amain.c contains the source code of the main program that usesthe services provided by ex_alib.c.

For more information about this example program, see the leadingcomments in the example source file and the EX_AREAD.ME file.


text and image Example Program

The getsend.c example program demonstrates how to retrieve andupdate text data from a table containing text and other datatypes.The process demonstrated could also be used for retrieving andupdating image data. If it connects to an Open Server application, theOpen Server application must be able to handle language commandsintended for SQL Server.

For more information about this example program, see the leadingcomments in the example source files.

This example requires SQL Server release 10.0 or later, the pubs2database, and the authors table.

Localization and Internationalization Example

The i18n.c example program demonstrates some of the internationalfeatures available in Client-Library, including:

• Localized error messages

• User-defined bind types


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:



• multthrd.c contains the source code that spawns five threads. Eachthread processes a cursor or a regular query. The main threadwaits until other threads complete query processing, thenterminates.

• thrdfunc.c contains platform specific information that determineswhich thread and synchronization routines the example uses forexecution.

For more information about this example program, see the leadingcomments in the example source files.


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.



Directory Service Example

The directory service example program, usedir.c, queries a directoryservice for a list of available servers.

usedir.c searches for Sybase server entries in the default directory, asdefined in the driver configuration file. First usedir.c queries theinterfaces file for server entries, then it displays a description of eachentry found and lets the user choose a server with which to connect.



Using Open Client DB-Library/CExample Programs 3.

Introduction

Open Client DB-Library is a collection of routines that you can use towriting client applications.

The example programs in this chapter demonstrate DB-Libraryfunctions. This chapter contains the following sections:




• Location 3-2


• DB-Library Example Programs 3-6

DB-Library includes routines that send commands to a server andothers that process the results of those commands. Other routines setapplication properties, handle error conditions, and provide avariety of information about an application’s interaction with aserver.


The Macintosh example project demonstrates how to use DB-Librarywith the Thread Manager and an Event Loop.

The sample project, dbsample.π, combines all of the DB-Libraryexamples into one application, which is accessible through thesample menu.


When you choose a sample from the menu, a thread is spawned torun the sample while the main application thread processes theEvent Loop.


The System 11 example programs demonstrate specificDB-Library/C functions. These programs are designed as guides for

3

3-2 Using Open Client DB-Library/C Example Programs

General Requirements Open Client/Server Release 11.1.x

application programmers, not as DB-Library/C training aids. Readthe descriptions at the top of each source file and examine the sourcecode before you use the sample programs. These simplifiedprograms are not intended for use in a production environment.Programs written for a production environment need additionalcode to handle errors and special cases.


Before you run the DB-Library examples, you must:


• Set the DSQUERY environment variable to the server name(server_name) to which you want to connect.



Location

The DB-Library example programs are located in the:sample:dblibrary: folder of the Sybase installation folder. This foldercontains:





• The source file, ex_mac.c, for the menu interface when buildingthe dbsample application



files.



Sample project files are located in the :sample:dblibrary:CFM(PPC):folder and the :sample:CFM(68K): folder of the Sybase installationfolder. These folders contain:

• The project file, dbsample.π, for a Macintosh-style application thatcombines all of the Client-Library examples

• The project file, example1.π, for a “console-style” application forthe example1.c example

Header Files

The following header files are required by all DB-Library/Capplications:

• sybfront.h defines symbolic constants, such as function returnvalues (described in the Open Client DB-Library/C ReferenceManual) and the exit values STDEXIT and ERREXIT. sybfront.hincludes type definitions for datatypes that can be used indeclaring program variables.

• sybdb.h contains additional definitions and type definitions. Mostof these are meant to be used only by DB-Library/C routines. Usesybdb.h only as documented in the Open Client DB-Library/CReference Manual.

• syberror.h contains error severity values and should be included ifthe program refers to those values.

See the Open Client DB-Library/C Reference Manual for moreinformation 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***/



/* 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



#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 programcontain 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 runthe 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 theexample programs, you may want to edit example.h and change““ to your server password.


DB-Library Example Programs Open Client/Server Release 11.1.x

There are three ways to use EX_PASSWORD. Choose the onethat best meets your needs:

- Method 1 – Change your server password to“server_password” while you run the examples. This createsthe possibility of a security breach. While your password is setto this published value, an unauthorized person could log intothe server as you. If this presents a problem, choose anotherway 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’sprotection mechanisms to prevent others from accessing theheader file while you use it. When you finish with theexamples, edit the line so that it again reads“server_password”.

- Method 3 – In the example programs, delete the DBSETLPWDcode that sets the server password and substitute your owncode to prompt users for their server passwords. (Because thiscode is platform-specific, Sybase does not supply it.)

• EX_LANGUAGE is defined in example.h as “us_english”. If yourserver’s language is not “us_english,” you may want to editexample.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 todemonstrate typical uses for DB-Library routines. Some exampleprograms use the sample databases supplied with SQL Server. Referto your installation guide for information on installing the sampledatabases.

The example programs are C source files. The appropriate compilermust be installed on your platform if you plan to use the DB-Libraryexample programs or build applications.

Send Queries, Bind, and Print Results

example1.c sends two queries to SQL Server in a single commandbatch, binds the results, and prints the returned rows of data.

Access to SQL Server is required.


Open Client/Server Release 11.1.x DB-Library Example Programs

Insert Data into a New Table

example2.c inserts data from a file into a newly created table, selectsthe server rows, and binds and prints the results.

Access to SQL Server is required. This example requires a file nameddatafile (supplied).You must have create database permission in yourlogin database to run this example.

Bind Aggregate and Compute Results

example3.c selects information from the titles table in the pubs2database and prints it. It illustrates binding of both aggregate andcompute results.

Access to a SQL Server that contains the pubs2 database is required.

Row Buffering

example4.c demonstrates row buffering. It sends a query to SQLServer, buffers the returned rows, and allows you to examine theminteractively.


Data Conversion

example5.c illustrates dbconvert, a DB-Library/C routine that handlesdata conversion.

Browse Mode Updates

example6.c demonstrates browse-mode techniques. It creates a table,inserts data into the table, and then updates the table using browse-mode routines. Browse mode is useful for applications that updatedata one row at a time.

example6.c requires a file named datafile (supplied). It creates the tablealltypes in your default database.




Browse Mode and Ad Hoc Queries

example7.c uses browse-mode techniques to determine the source ofresult columns from ad hoc queries.

Determining the source of result columns is important because abrowse-mode application can only update columns that are derivedfrom a browsable table and are not the result of a SQL expression.

This example demonstrates how an application can determine whichcolumns resulting from ad hoc queries are updatable using browse-mode techniques.

This example prompts you for an ad hoc query. Notice how theresults differ depending on whether or not the select query includesthe keywords for browse and whether or not the table selected isbrowsable.


RPC Command Example

example8.c sends a remote procedure call, prints the result rows fromthe call, and prints the parameters and status returned by the remoteprocedure.


Text and Image Routines

example9.c generates a random image, inserts it into a table, thenselects the image and compares it to the original following thesesteps:

1. Inserts all data into the row except the text or image value.

2. Updates the row, setting the text or image value to NULL. Thisstep is necessary because a text or image value that is null has avalid text pointer only if the null value was explicitly enteredwith the update statement.

3. Selects the column. You must specifically select the column thatwill contain the text or image value. This step provides theapplication’s DBPROCESS with the correct text pointer and texttimestamp information. The application should throw away thedata returned by this select command.



4. Calls dbtxtptr to retrieve the text pointer from DBPROCESS.dbtxtptr’s column parameter is an integer that refers to the selectoperation performed in step 3. For example, if the select statementreads:

select date_column, integer_column, text_column from bigtable

and text_column is the name of the text column, dbtxtptr requirescolumn to be passed as 3.

5. Calls dbtxtimestamp to retrieve the text timestamp from theDBPROCESS. dbtxtimestamp’s column parameter refers to the selectoperation performed in step 3.

6. Writes the text or image value to SQL Server. An application caneither:

- Write the value with a single call to dbwritetext, or

- Write the value in chunks, using dbwritetext and dbmoretext

7. If you want the application to perform another update to thistext or image value, you can save the new text timestamp that isreturned by SQL Server at the conclusion of a successfuldbwritetext operation. The new text timestamp can be accessed viadbtxtsnewval and stored for later retrieval via dbtxtsput.


Inserting an Image

exampl10.c prompts you for an author identification and for the nameof a file containing an image, reads the image from the file, andinserts a new row containing the author identification and the imageinto the pubs2 database table au_pix. For general information oninserting text and image values into a database table, see “Text andImage Routines” on page 3-8.

To run, exampl10.c requires access to SQL Server and the pubs2database. The author identification must be in the form “nnn-nn-nnnn”, where n is a numeric digit. imagefile, provided with thesample code, contains an image.

Retrieving an Image

exampl11.c retrieves an image from the au_pix table in the pubs2database. The author identification you enter determines which row



the program selects. After retrieving the row, this example copies theimage contained in the pic column to a file you specify.

There are two ways to retrieve a text or image value from SQL Server.This example selects the row containing the value and processes therow via dbnextrow. After dbnextrow is called, dbdata can be used to returna pointer to the returned image.

You can also use dbreadtext in conjunction with dbmoretext to read a textor image value in the form of a number of smaller chunks. For moreinformation on dbreadtext, see the Open Client DB-Library/C ReferenceManual.


International Language Routines

exampl12.c retrieves data from the interpubs database and prints itusing a us_english format.

Access to SQL Server and the interpubs database is required.

Bulk-Library

In the Bulk-Library example program, bulkcopy.c, the Bulk-Libraryroutines copy data from a host file into a newly created tablecontaining several SQL Server datatypes.

Access to SQL Server is required. You must have create database andcreate table permission.

Two-Phase Commit

This example, twophase.c, performs a simple update on two differentservers. See the source code for the exact contents of the update.Once you run the example, you can use isql on each of the servers todetermine whether the update actually took place.

This example assumes that you have two SQL Servers running.Theserver names, EX_SERVER and EX_SERVER2, are defined in theexample.h file.

Before you run the example, make sure that the interfaces file includesappropriate entries for both servers. See the Open Client DB-Library/CReference Manual and the Open Client/Server Installation and



Configuration Guide for Macintosh and Power Macintosh for informationabout the interfaces file.




4 Using Open Server Server-Library/CExample Programs 4.

Introduction

Open Server Server-Library is used to design servers that takeadvantage of the features of the client/server architecture. Thesefeatures include Remote Procedure Calls (RPCs), multithreading,remote access to SQL Server, and others. The example programsdiscussed in this chapter demonstrate these features.

This chapter contains the following sections:




• Location and Content 4-2

• Tracing 4-3


• Server-Library Example Programs 4-4

You can create a complete, standalone server using Server-Library.Open Client-based applications and utilities, such as isql, takeadvantage of the features built into these servers.

➤ Note68K Macintosh does not support Server-Library.


The Macintosh example project demonstrates how to use Server-Library with the Thread Manager and an Event Loop.

The sample project, srvsample.π, combines all of the Server-Libraryexamples into one application, which is accessible through thesample menu.


4-2 Using Open Server Server-Library/C Example Programs

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 torun the sample, while the main application thread processes theEvent Loop.


The System 11 example programs demonstrate specific Server-Library/C functionality. These programs are designed as guides forapplication programmers, not as Server-Library/C training aids.Read the descriptions at the top of each source file and examine thesource code before you use the example programs. These simplifiedprograms are not intended for use in a production environment.Programs written for a production environment need additionalcode to handle errors and special cases.


Before you run the Open Server examples, you must:


• Set the DSLISTEN environment variable to your server’s name(optional).



Location and Content

Sample files that come with Server-Library are located in the:sample:srvlibrary: folder beneath the Sybase installation folder.

The srvlibrary folder contains:






Open Client/Server Release 11.1.x Tracing

• The source file, ex_mac.c, for the menu interface when buildingthe srvsample application

• readme – a text file that has platform-specific and general notesabout building, executing, and troubleshooting the examples

• A SRV_CONNECT event handler

• Error handlers



files.

Sample project files are located in the :sample:srvlibrary:CFM(PPC):folder of the Sybase installation folder. This folder contains:

• The project file, srvsample.π, for a Macintosh-style application thatcombines all of the Server-Library examples

• The project file, ctos.π, for a “console-style” application for thectos.c example

Tracing

Tracing provides detailed information about activities carried out byyour application, depending on the options you select. The OpenServer example programs support tracing, sending tracing output tothe Open Server log file. To enable tracing, specify the followingoptions on the command line when executing an example program:

example_name [normal_sample_options][-h] [-d] [-i] [-a] [-m] [-t] [-e] [-q] [-n]

Table 4-1 describes the tracing information provided by each option.

Table 4-1: Tracing options

Option Description

-h TDS header

-d TDS data

-i I/O

-a Attention



➤ Note-e and -q are mutually exclusive.

Header Files

The following header files are required by all Open Serverapplications:

• ospublic.h contains public Open Server structures, datatypedefinitions, define statements, and function prototypes.

• oserror.h contains Open Server error message numbers and text.

• oscompat.h maps old datatype definitions, datatypes, routines,constants, and function prototypes to new versions.

See the Open Server Server-Library/C Reference Manual for moreinformation on header files.

Server-Library Example Programs

This section contains information about the example programs thatare included with Server-Library. The example programsdemonstrate typical uses for Server-Library routines in C programs.

The example programs are C source files. You must have theappropriate compiler installed for your platform to use theServer-Library example programs or build applications. For moreinformation on Sybase-supported compilers, see Chapter 1,“Building Macintosh and Power Macintosh Applications.”

-m Message queue

-t TDS token

-e Event tracing

-q Deferred event queue

-n Net-Library tracing

Table 4-1: Tracing options (continued)

Option Description


Open Client/Server Release 11.1.x Server-Library Example Programs

Testing Example Programs

To test the example program, follow these steps:

1. Use isql to connect to server_name:

isql -U username -P password -S server_name

2. Perform the following query:

select * from sysservers

or any SQL command.

You may now perform any SQL commands.

A client program can stop an example by executing the stop_servregistered procedure from a SQL server.

Open Server Introduction

The osintro.c example program demonstrates the basic componentsthat make up an Open Server application. osintro.c does not include alanguage handler and, therefore, cannot read commands sent by isql.

Gateway Open Server

ctosdemo.c is a gateway Open Server application. It uses 11.1 Server-Library calls and 11.1 Client-Library calls. It accepts commands froma client and passes them to a remote SQL Server. It then retrieves theresults from the remote server and passes them to the client.ctosdemo.c processes a variety of client commands, including:

• Bulk-copy commands

• Cursor commands

• Dynamic SQL commands

• Language commands

• Message commands

• Option commands

• Remote procedure calls (RPCs)

In addition, ctosdemo.c responds to attention requests from a client bycalling the SRV_ATTENTION event handler. It includes an eventhandler routine to process each type of client command.


Server-Library Example Programs Open Client/Server Release 11.1.x

➤ NoteUnlike other example programs included with Server-Library, ctosdemo.cattempts to be complete. It is provided as a coding template for use in a

production environment.

For more information on gateways, see the Open Server Server-Library/C Reference Manual.

srv_language Event Handler

lang.c demonstrates the use of a SRV_LANGUAGE event handler.The event handler responds to client language commands with aninformational message, which it sends to the client using thesrv_sendinfo routine. lang.c also contains a SRV_CONNECT eventhandler and error handlers.

For more information on processing language commands, see the“Language Calls” topics page in the Open Server Server-Library/CReference Manual.

TDS Passthrough Mode

fullpass.c is an Open Server gateway application that demonstratesthe Tabular Data Stream™ (TDS) passthrough mode. For moreinformation on TDS passthrough, see the “Passthrough Mode”topics page in the Open Server Server-Library/C Reference Manual.

The event handler routine receives client requests via srv_recvpassthruand forwards this information to a SQL Server using thect_sendpassthru routine. After the entire client command has beenforwarded to the remote server, the event handler reads results fromthe remote server via ct_recvpassthru and returns them to the clientusing srv_sendpassthru.

The application also includes a SRV_CONNECT event handler. Thishandler uses srv_getloginfo and ct_setloginfo to forward clientconnection information to the remote server. It then uses ct_getloginfoand srv_setloginfo to return connection acknowledgment informationto the client. All Open Server applications that use TDS passthroughmode must include these calls in their SRV_CONNECT eventhandler.

Use of this application requires access to SQL Server.


Open Client/Server Release 11.1.x Server-Library Example Programs

Registered Procedures

regproc.c demonstrates the use of registered procedures in OpenServer 11.1. The application registers several procedures at start-uptime and then waits for client commands. No Open Server eventhandlers are installed.

Clients send RPC commands to execute the registered proceduresdefined in regproc.c.

Several additional client programs are provided for use withregproc.c:

• version.c – executes a registered procedure (rp_version) that returnsthe version number of Open Server to the client

• dbwait.c – implemented with DB-Library, dbwait.c tells OpenServer to notify the client when rp_version executes

• ctwait.c – implemented with Client-Library, ctwait.c tells OpenServer to notify the client when rp_version executes

International Languages and Character Sets

The intlchar.c example program demonstrates how Open Serverhandles international languages and character sets. It initializesvalues for the Open Server application native language andcharacter set and then changes these values in response to clientrequests.

Client requests come in the form of option commands and languagecommands. intlchar.c installs SRV_OPTION and SRV_LANGUAGEevent handlers and a SRV_CONNECT handler.

Multithreaded Programming

multthrd.c illustrates a number of Open Server multithreadedprogramming features, including:

• Creation of a service thread using srv_spawn

• Interthread communication between client connection threadsand the service thread via message queues (using srv_getmsgq andsrv_putmsgq)

• Sleep and wake-up mechanisms (using srv_sleep and srv_wakeup)

• The use of a callback routine (using srv_callback) to reportscheduling information


Server-Library Example Programs Open Client/Server Release 11.1.x

multthrd.c installs a SRV_START handler, a SRV_LANGUAGEhandler, a SRV_CONNECT handler, and callback handlers. A servicethread logs all the language queries received by the Open Serverapplication.

In the application’s language handler, the client thread reads thequery from a client and sends a message to the service thread, knownas the logger, with the query as the message data.

The client thread then waits (srv_sleep). The service thread receivesthe message and wakes up the client thread (srv_wakeup).

The logger thus continuously loops waiting for messages. When itreceives a message, it prints the contents of the query to a file andalerts the sender.

The logger and client threads install SRV_C_RESUME,SRV_C_SUSPEND, SRV_C_TIMESLICE, and SRV_C_EXIT callbackhandlers to print scheduling information.

Open Client/Server Supplement for Macintosh and Power Macintosh A-1

A Using isqlA.

Introduction

This appendix explains how to use isql—the Open Client interactiveSQL utility. isql is included with Open Client release 11.1.x softwareand is located in the Sybase_root:bin folder.

➤ NoteIf you select Power Mactintosh or Universal applications during your

installation, isql runs as a Power Macintosh native application.

isql is an interactive SQL parser used to connect to and query a SQLServer or an Open Server. isql can be used to perform ad hoc ordiagnostic queries. For example, isql can be used as a diagnosticutility when SybPing reports a successful connection but your OpenClient application fails to run.

➤ NoteWhile all SQL Servers support isql, Open Server applications are not

required to provide isql support.

isql can only return results up to 50 columns. If a query returns more than

50 columns, isql generates an error message.

Using isql

To run isql, double click on the icon labeled ‘‘Isql’’ in theSybase_root:bin folder.

To exit isql, select Quit from the File menu.

New Features

isql for System 11 is built with Client-Library.

• The 5701 (“changed database”) server message is no longerdisplayed after login or issuing a use database command.

• There are two new optional flags:

A-2 Using isql

Using isql Open Client/Server Release 11.1.x

-b – disables column headers from printing-D database – selects the startup database that isql uses

• Error message format is different than previous versions of isql. Ifyou have scripts that perform routines based on the values ofthese messages you may need to re-write them.

• The -y sybase_directory option has been removed.

Syntax

isql [-b] [-e] [-F] [-n] [-p] [-v] [-X] [-Y][-a display_charset ][-A size ][-c cmdend][-D database ][-h headers ][-H hostname ][-i inputfilename ][-I interfaces_file ][-J client_charset ][-K keytab_file ][-l login_timeout ][-m errorlevel ][-o outputfilename ][-P password ][-R remote_server_principal ][-s colseparator ][-S server ][-t timeout ][-U username ][-V [ security_options ]][-w columnwidth ][-z language ][-Z security_mechanism ]

Additional Commands Within isql:

To clear the query buffer: reset

To exit from isql: quit or exit


Open Client/Server Release 11.1.x Using isql

Parameters

-a display_charset – allows you to run isql from a terminal where thecharacter set differs from that of the machine on which isql isrunning. -a in conjunction with -J specifies the character settranslation file (.xlt file) required for the conversion. Use -awithout -J only if the client character set is the same as the defaultcharacter set.

-A size – specifies the network packet size to use for this isql session.For example:

isql -A 2048

sets the packet size to 2048 bytes for this isql session. To check,type:

select * from sysprocesses

The value is displayed under the network_pktsz heading.

size must be between the values of the default network packet size andmaximum network packet size configuration variables, and must be amultiple of 512.

Use larger-than-default packet sizes to perform I/O-intensiveoperations, such as readtext or writetext operations.

Setting or changing SQL Server’s packet size does not affectremote procedure calls’ packet size.

-b – disables the display of the table headers output.

-c cmdend – resets the command terminator. By default, terminatecommands and send them to SQL Server by entering “go” on aline by itself. When you reset the command terminator, do not useSQL reserved words or control characters. Make sure to escapeshell meta characters such as , ? ( ) [ ] $ and so on.

-D database – selects a database that the isql session begins in.

-e – echoes input.

-E editor – specifies an editor other than your default editor.

-F – enables the FIPS flagger. With this option, the SQL server flagsany non-standard SQL commands sent.

-h headers – specifies how many rows to print between columnheadings. The default prints headings only once for each set ofquery results.

A-4 Using isql


-H hostname – sets the client host name.

-i inputfilename – specifies the name of an operating system file to usefor input to isql. The file must contain command terminators(“go” by default).

-I interfaces_file – specifies the name and location of the interfaces fileto search when connecting to SQL Server. If you do not specify -I,isql looks for an interfaces file (sql.ini for Windows platforms)located in the ini directory that is below the directory specified bythe SYBASE environment variable.

-J client_charset specifies the character set to use on the client. -Jclient_charset requests that SQL Server convert to and fromclient_charset, the character set used on the client. A filter convertsinput between client_charset and the SQL Server character set.

-J with no argument sets character set conversion to NULL. Noconversion takes place. Use this if the client and server use thesame character set.

Omitting -J sets the character set to a default for the platform.The default may not necessarily be the character set that theclient is using.

-K keytab_file – can be used only with DCE security. It specifies a DCEkeytab file that contains the security key for the user namespecified with -U option. Keytab files can be created with the DCEdcecp utility — see your DCE documentation for moreinformation.

If the -K option is not supplied, the user of isql must be logged into DCE with the same username as specified with the -U option.

-l login_timeout – specifies the maximum timeout value allowed whenconnecting to SQL Server.

-m errorlevel – customizes the error message display. For errors of theseverity level specified or higher only the message number, state,and error level display; no error text appears. For error levelslower than the specified level, nothing appears.

-n – removes numbering and the prompt symbol (>) from input lines.

-o outputfilename – specifies the name of an operating system file tostore the output from isql.

-p – prints out performance statistics.



-P password – specifies your current SQL Server password. Thisoption is ignored if -V is used. Passwords are case-sensitive andcan be from 6 to 30 characters in length.

-R remote_server_principal – specifies the principal name for the server.By default, a server’s principal name matches the server’snetwork name (which is specified with the -S option or theDSQUERY environment variable). The -R option must be usedwhen the server’s principal name and network name are not thesame.

-s colseparator – resets the column separator character, which is blankby default. To use characters that have special meaning to theoperating system (for example, |, ;, &, <, >), enclose them inquotes or precede them with a backslash.

-S server – specifies the name of the SQL Server to connect to. Without-S, isql looks for the server specified by your DSQUERYenvironment variable.

-t timeout – specifies the number of seconds before a command timesout. If you do not specify a timeout, a command runs indefinitely.This affects commands issued from within isql, not the connectiontime. The default timeout for logging into isql is 60 seconds.

-U username – specifies a login name. Logins are case-sensitive.

-V security_options – specifies network-based user authentication.With this option, the user must log in to the network’s securitysystem before running the utility. In this case, users must supplytheir network user name with the -U option; any passwordsupplied with the -P option is ignored.

-V can be followed by a security_options string of key-letteroptions to enable additional security services. These key lettersare:

c – Enable data confidentiality service

i – Enable data integrity service

m – Enable mutual authentication for connection establishment

o – Enable data origin stamping service

q – Enable out-of-sequence detection

r – Enable data replay detection

A-6 Using isql


-v – prints the version and copyright message of the isql software thatyou are using.

-w columnwidth – sets the screen width for output. The default is 80characters. When an output line reaches its maximum screenwidth, it breaks into multiple lines.

-X – initiates the login connection to the server with client-sidepassword encryption. isql (the client) specifies to the server thatpassword encryption is desired. The server sends back anencryption key, which isql uses to encrypt your password, and theserver uses the key to authenticate your password when itarrives.

-Y – tells the SQL Server to use chain transactions.

-z language – is the official name of an alternate language to displayisql prompts and messages. Without -z, isql uses the server’sdefault language. Add languages to a SQL Server at installation,or afterwards with the utility langinstall or the stored proceduresp_addlanguage.

-Z security_mechanism – specifies the name of a security mechanism touse on the connection.

Security mechanism names are defined in the libtcl.cfgconfiguration file located in the ini subdirectory below theSybase installation directory. If no security_mechanism name issupplied, the default mechanism is used.

Example

The figure below shows an example isql query.



Figure A-1: isql Example Query

Comments

• To use isql interactively, give the command isql (and any of theoptional flags) at your operating system prompt. The isql programaccepts SQL commands and sends them to SQL Server. Theresults are formatted and printed on standard output. Exit isqlwith quit or exit.

• Terminate a command by typing a line beginning with the defaultcommand terminator go or other command terminator if the -coption is used. You may follow the command terminator with aninteger to specify how many times to run the command. Forexample, to execute this command 100 times, type:

select x = 1go 100

The results display once at the end of execution.

• To clear the existing query buffer, type reset on a line by itself. isqldiscards any pending input. You can also press Cmd-. anywhereon a line to cancel the current query and return to the isql prompt.

• Case is significant for the isql flags.

• isql displays only six digits of float or real data after the decimalpoint, rounding off the remainder.

A-8 Using isql


• When using isql interactively, read an operating system file intothe command buffer with the command:

:r filename

Do not include a command terminator in the file; enter theterminator interactively once you have finished editing.

• You can include comments in a Transact-SQL statementsubmitted to SQL Server by isql. Open a comment with “/*”.Close it with “*/” as the following example demonstrates:

select au_lname, au_fname/*retrieve authors’ last and first names*/from authors, titles, titleauthorwhere authors.au_id = titleauthor.au_idand titles.title_id = titleauthor.title_id/*this is a three-way join that links authors**to the books they have written.*/



If you want to comment out a go command, it should not be atthe beginning of a line. For example:

/*

**go

*/

should be used to comment out the go command instead of:

/*

go

*/

See Also

sp_addlanguage, sp_addlogin, sp_configure, sp_defaultlanguage,sp_droplanguage, and sp_helplanguage in the SQL Server Reference Manual.

A-10 Using isql


Open Client/Server Supplement for Macintosh and Power Macintosh B-1

B Building CFM Applications withOpen Client/Server for Macintosh B.

Introduction

This appendix explains how to build an Open Client/Serverapplication using CodeWarrior. It provides compiler-specificinformation that complements the general information discussed inprevious Open Client/Server chapters. For more detailedinformation, refer to the documentation accompanying yourcompiler.

Open Client Applications

The following sections describe how to building a CFM Open Clientapplication using CodeWarrior.

Specifying the Location of Sybase Header Files

To specify the location of the Sybase Header files:

• Add the header file PATH to the project’s access paths.

• Select the Treat # Include check box as number include “...”

Access paths are set using the Preferences... command on the Editmenu.

Compiling, Linking, and Building an Application Using CodeWarrior

To compile, link, and build an Open Client application using CFM,you must add the appropriate libraries to the application’s project.

Open Client required libraries:

The non-debuggable libraries are located in Sybase_root:lib; thedebuggable libraries are located in Sybase_root:devlib. The librariesconsist of the following files:

File Description

libcomn Common Library

libcs CS-Library

B-2 Building CFM Applications with Open Client/Server for Macintosh

Open Client Applications Open Client/Server Release 11.1.x

Open Client product-specific libraries:

The non-debuggable libraries are located in Sybase_root:lib; thedebuggable libraries are located in Sybase_root:devlib. The librariesconsist of the following files:

➤ Notelibblk is only available with Client-Library and must be added if the Client-

Library application makes calls to Bulk-Library.

For 68K CFM applications:

• InterfaceLib

• ANSI (4i/8d) C.CFM68K.Lib

• MWCFM68KRuntime.Lib

• MathLibCFM68K (4i/8d).Lib

• SIOUX.CFM68K.Lib (for console style applications only)

• NuThreadsLib.slb if your application makes Thread Manager calls)

For Power Macintosh CFM applications:

• InterfaceLib

• MathLib

• MWCRuntime.Lib

• ANSI C.PPC.Lib

• SIOUX.PPC.Lib (for console style applications only)

libintl Internationalization Library

libctb Net-Library drivers

libtcl Transport Control Layer

File Description

libblk Bulk-Library

libct Client-Library

libsybdb DB-Library

libsrv Server-Library

File Description

Open Client/Server Supplement for Macintosh and Power Macintosh B-3

Open Client/Server Release 11.1.x Open Client Applications

• ThreadsLib (if your application makes Thread Manager calls)

CFM 68K CodeWarrior Preferences

The following required Preferences must be set to use Open Clientlibraries with CodeWarrior:

Any of the other available Processor Options are optional and can beset along with the required Preferences listed in the preceding table.

➤ NoteBuilding code resource is not supported because of Far DATA

requirements.

CodeGeneration → 68K Processor Setting

Codemodel Large

4-byte INTS Set

8-byte Doubles] Set

Far Data Set

Far Method Tables Set

Far String Costants Set

Linker → CFM68K Setting

Force Indirect Access Set

B-4 Building CFM Applications with Open Client/Server for Macintosh

Open Client Applications Open Client/Server Release 11.1.x

Open Client/Server Supplement for Macintosh and Power Macintosh Index-1

Index

Bbkpublic.h Bulk-Library header file 1-2bkpublic.h header file 2-3blktxt.c example program 2-7Building

a Client-Library executable onMacintosh 1-1 to 1-4

example compile and linkoperations 1-6

required configuration 1-1a DB-Library executable

link lines 1-7a DB-Library executable on

Macintosh 1-1 to 1-4a Server-Library executable on Power

Macintosh 1-1Client-Library executables using a

Net-Library driver 1-1bulkcopy.c example program 3-10

CC compilers

for Macintosh or PowerPC 1-1Client-Library 2-1 to 2-9

default values 1-4described 2-1Dynamic Link Libraries (DLLs) 1-3example programs 2-6 to 2-9

asynchronous program 2-8bulk copy 2-7compute rows 2-7configuration sample 2-7directory service 2-10header file 2-4 to 2-6internationalization 2-9location 2-2multithreaded program 2-9password 2-5read-only cursor 2-8

requirements 2-2RPC command 2-10text and image 2-9user name 2-5utility routines for examples 2-6

programming issues. SeeProgramming issues forClient-Library

sample programsintroductory sample 2-6

CodeWarriorcompiling and linking Open Client

applications B-1header files, specifying location B-1

Compile exampleClient-Library on Macintosh 1-6

Compilinga Client-Library executable on

Macinotsh 1-1a Client-Library executable on Power

Macintosh 1-1a Server-Library executable on Power

Macintosh 1-10Open Client applications using

CodeWarrior B-1compute.c example program 2-7CS_IFILE property 1-4CS_MAX_CONNECT property 1-4CS_PACKETSIZE property 1-4CS-Library 2-1cspublic.h header file 2-3csr_disp.c example program 2-8cstypes.h header file 2-3ct_callback 1-5ct_debug

and DLLs 1-5ctosdemo.c example program 4-5ctpublic.h Client-Library header file 1-2ctpublic.h header file 2-3

Index-2


DDB-Library

example programs 3-1bind aggregates and compute

results 3-7browse mode and ad hoc

queries 3-8browse mode updates 3-7bulk copy 3-10data conversion 3-7header file 3-3insert data into a new table 3-7inserting an image 3-9international language

routines 3-10location 3-2password 3-5retrieving an image 3-9row buffering 3-7send query and bind results 3-6text and image routines 3-8two-phase commit 3-10user name 3-5

DBMAXPROS property 1-4DBSETFILE property 1-4Debug DLLs 1-5Debugging 1-9Default values

Client-Library 1-4DLLs

libblk.dll 1-3libct.dll 1-3libintl.dll 1-3libsrv.dll 1-3libsybdb 1-3libtcl.dll 1-3

Documentationoverview xii

Documentation, related xiiDSQUERY environment variable 2-2,

3-2, 4-2Dynamic Link Libraries (DLLs)

for Open Client/Serverexecutables 1-3

EEnvironment Variables

DSQUERY 2-2, 3-2, 4-2SYBASE 2-2, 3-2, 4-2

Environment variablesdefinition xv

ERREXIT 1-2ex_alib.c example program 2-8EX_AREAD.ME 2-9ex_main.c example program 2-8EX_PASSWORD variable 2-5, 3-5EX_USERNAME variable 2-5, 3-5exampl10.c example program 3-9exampl11.c example program 3-9exampl12.c example program 3-10example.h header file 2-2, 3-2, 4-2example1.c example program 3-6example2.c example program 3-7example3.c example program 3-7example4.c example program 3-7example5.c example program 3-7example6.c example program 3-7example7.c example program 3-8example9.c example program 3-8Example programs

Client-Library 2-6 to 2-9DB-Library 3-1Open Server 4-5 to 4-8

exconfig.c sample program 2-7exutils.c example program 2-6

Ffirstapp.c sample program 2-6fullpass.c example program 4-6

Ggetsend.c example program 2-9

HHandlers 4-7

Open Client/Server Supplement for Macintosh and Power Macintosh Index-3


SRV_ATTENTION 4-5SRV_C_EXIT 4-8SRV_C_RESUME 4-8SRV_C_SUSPEND 4-8SRV_C_TIMESLICE 4-8SRV_CONNECT 4-6, 4-8SRV_LANGUAGE 4-6, 4-8SRV_OPTION 4-7SRV_START 4-8

Header Filesbkpublic.h 1-2, 2-3cspublic.h 2-3cstypes.h 2-3ctpublic.h 1-2, 2-3example.h 2-2, 3-2, 4-2oserror.h 4-4ospublic.h 1-2, 4-4required for Open Server

applications 4-4sqlca.h 2-4sybdb.h 1-2sybdbex.h 3-3syberror.h 1-2sybfront.h 1-2

Ii18n.c example program 2-9intlchar.c example program 4-7isql utility A-1 to A-8

Llang.c example program 4-6libblk.dll file 1-3libcomn.dll file 1-3libcs.dll file 1-3libct.dll file 1-3libintl.dll file 1-3libsrv.dll file 1-3libsybdb file 1-3libtcl.dll file 1-3Linking

a Client-Library executable onMacintosh 1-1

a Server-Library executable on PowerMacintosh 1-10

Linking Open Client applicationsusing CodeWarrior B-1

MMacintosh

building a Client-Libraryexecutable 1-1 to 1-4

building a DB-Library executable 1-1to 1-4

C compilers 1-1multithreaded programming

support 1-5, 1-9platforms xi

Macintosh propertiesClient-Library 1-4CS_IFILE 1-4CS_MAX_CONNECT 1-4CS_PACKETSIZE 1-4DBMAXPROS 1-4DBSETFILE 1-4

Multithread programmingsupport for Macintosh 1-5, 1-9

multthrd.c example program 2-9, 4-7

OOpen Server

example programs 4-5 to 4-8Gateway Open Server 4-5international languages and

character sets 4-7language event handler 4-6location 4-2Open Server introduction 4-5Open Server multithreaded

features 4-7registered procedures 4-7TDS pass through mode 4-6

oscompat.h header file 4-4

Index-4


oserror.h header file 4-4osintro.c example program 4-5ospublic.h header file 4-4ospublic.h Server-Library header file 1-2

PPlatforms

Macintosh xiPowerPC xi

Power Macintoshbuilding a Server-Library

executable 1-1PowerPC

platforms xiProgramming issues for Client-Library

on Macintosh 1-5ct_callback 1-5

Programming issues for Server-Libraryon Power Macintosh 1-9

scheduling modes 1-9srv_callback 1-9

PropertiesCS_IFILE 1-4CS_MAX_CONNECT 1-4CS_PACKETSIZE 1-4DBSETFILE 1-4DBSETMAXPROS 1-4

Rregproc.c example program 4-7rpc.c example program 2-10

SServer-Library

compile example 1-10example programs

requirements 4-2link example 1-10programming issues 1-9

Software requirements for exampleprograms 1-3

sql.ini file 1-4sqlca.h header file 2-4srv_callback 1-9STDEXIT 1-2SYBASE environment variable 2-2, 3-2,

4-2sybdb.h DB-Library header file 1-2sybdbex.h 3-3syberror.h DB-Library header file 1-2sybfront.h DB-Library header file 1-2

Tthrdfunc.c example program 2-9Tracing 4-3

options 4-3twophase.c example program 3-10

Uusedir.c example program 2-10

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

Documents

open clientserver

vertical bars

tabular data

supportplus

open clientserver

handle error

ad hoc queries

dsquery environment