UniAccess for OS 2200 Client-Library Programming Reference

UniAccess for OS 2200 Client-Library Programming Reference

Release 10R3Document Version: 1.00Last Revised: October 31, 2005Copyright 2005. All rights reserved.

UniAccess 10R3 Product Suite

Title

Principal Authorship

AIS Technical Publications Department

Document Version

This publication pertains to Release 10R2, version 1.00 of the Applied Information Sciences OS 2200 connectivity software and to any subsequent release until otherwise indicated in new editions or technical notes. Information in this document is subject to change without notice. The software described herein is furnished under a license agreement and may be used or copied only in accordance with the terms of the agreement.

Document Feedback

The Applied Information Sciences Technical Publications Department welcomes corrections and comments on its documents. Please send corrections and comments to UniAccess Technical Support at the address below.

Applied Information Sciences, Inc.1850 Centennial Park DriveReston, VA 20191USA

Phone (703) 860-7808FAX (703) 860-7820E-mail [email protected]

Document Orders and Upgrades

UniAccess documentation is provided on the UniAccess 10R2 PC Client CD for online viewing with Adobe Acrobat Reader. To order this CD, contact AIS at the above number or retrieve the documents from the Internet at http://www.uniaccess.com. Customers may make copies of the UniAccess 10R2 PC Client CD for their in-house use. Additionally, customers may print copies of the UniAccess documentation from the CD for their in-house use.

Customers may purchase printed copies of any document or the right to make photocopies of printed documentation for their in-house use. To order printed documents or photocopy rights, contact AIS at the address given above.

Upgrades are provided only at regularly scheduled software release dates.

http://www.uniaccess.com

Copyright 1989 to 2004 Applied Information Sciences, Inc. All rights reserved. No part of this publication may be reproduced, transmitted, or translated in any form or by any means, electronic, mechanical, manual, optical or otherwise, without prior written permission of Applied Information Sciences, Inc.

Restricted Rights Legend

Use, duplication, or disclosure by the U.S. Government is subject to restrictions set forth in FAR subparagraphs 52.227-19(a)-(d) for civilian agency contracts and DFARS 252.227-7013(c)(1)(ii) for Department of Defense contracts.

Applied Information Sciences, Inc. reserves all unpublished rights under the copyright laws of the United States.

Applied Information Sciences Trademarks

UniAccessTM is a trademark of Applied Information Sciences, Inc.

Sybase Trademarks

Sybase®, SYBASE® (logo), SQL Server®, Transact-SQL®, PowerBuilder®, and Adaptive Server® Enterprise are registered trademarks of Sybase, Inc.

Client-LibraryTM, CT-LibraryTM, DB-LibraryTM, Embedded SQLTM, Enterprise Client/ServerTM, Net-LibraryTM, Open ClientTM, Open ServerTM, and Tabular Data StreamTM are trademarks of Sybase, Inc.

Other Trademarks

Microsoft® is a registered trademark of Microsoft Corporation. Unisys® is a registered trademark of Unisys Corporation. All other company and product names used herein may be the trademarks or registered trademarks of their respective companies.

Release 10R2: December 24, 2004

Contents

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Contents

Table of ContentsPreface xi

About This Book. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiAudience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiUniAccess System Product Suite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiRelated Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii

Conventions Used in this Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiiFonts and Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiiTerminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv

How This Manual Is Organized . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

Chapter 1: Introduction to UniAccess Client-Library 1-1Client/Server Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2

Client/Server Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2Types of Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4Types of Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5

UniAccess System for OS 2200 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5The UniAccess Transaction Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6Communication with a Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8Servers in the UniAccess Transaction Client Environment . . . . . . . . . . . . 1-10

Using UniAccess Client-Library Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-15Basic Control Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-15Steps in a Simple Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-17Notes on the Simple Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-18Developing Client-Library Applications . . . . . . . . . . . . . . . . . . . . . . . . . . 1-21

iv UniAccess for OS 2200 Client-Library Programming Reference


Chapter 2: Topics 2-1Architectural Differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2Buffers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3CLIENTMSG Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6Compiling and Linking Programs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9

Compiling Client-Library Programs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9Linking Client-Library Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9

DATAFMT Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13Datatypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-18

Summary of UniAccess Client-Library Datatypes . . . . . . . . . . . . . . . . . . . 2-18Description of UniAccess Client-Library Datatypes . . . . . . . . . . . . . . . . . 2-21

Error and Message Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-26The CS-EXTRA-INF Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-27

Microsoft SQL Server Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-28Restrictions and Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-29

Nulls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-32NULL and Unused Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-32

Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-33Setting and Retrieving Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-33Summary of Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-34About the Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-37

Remote Procedure Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-43Comparing RPCs and Execute (language) Statements . . . . . . . . . . . . . . . . 2-43Servers Can Execute Remote Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . 2-44Remote Procedure Call Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-44Remote Procedure Call Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-45Return Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-45Return Status. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-46

Results. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-47Types of Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-47

SERVERMSG Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-49SQLCA Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-52SQLCODE Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-54

Mapping Server Messages to SQLCODE . . . . . . . . . . . . . . . . . . . . . . . . . 2-54Mapping Client-Library Messages to SQLCODE . . . . . . . . . . . . . . . . . . . 2-54

Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-55Hidden Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-55Exposed Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-59


Contents v

UCS C Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-60UniAccess Communication Server (UACS). . . . . . . . . . . . . . . . . . . . . . . . . . . 2-62

Client Application Programmer’s Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-62System Administrator’s Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-62

Word Alignment Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-64

Function Descriptions 3-1List of Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1CTBBIND. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3CTBCANCEL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-15CTBCLOSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-20CTBCMDALLOC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-25CTBCMDDROP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-28CTBCMDPROPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-30CTBCOMMAND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-35CTBCONALLOC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-41CTBCONDROP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-45CTBCONFIG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-49CTBCONNECT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-54CTBCONPROPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-58CTBDESCRIBE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-64CTBDIAG. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-70CTBEXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-83CTBFETCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-88CTBGETFORMAT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-94CTBINIT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-96CTBPARAM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-99CTBREMOTEPWD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-109CTBRESINFO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-115CTBRESULTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-122CTBSEND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-130CSBCONFIG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-134CSBCONVERT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-142CSBCTXALLOC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-151CSBCTXDROP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-155

Appendix A: Sample Programs A-1UniAccess Client-Library Programs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1

UACL Functions Demonstrated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-5UACL Datatypes Demonstrated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-5

vi UniAccess for OS 2200 Client-Library Programming Reference


The UniAccess Sample System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-5UniAccess Sample Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-7

Setting up the Sample System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-13UniAccess Transaction Client Sample Setup . . . . . . . . . . . . . . . . . . . . . . A-13SQL Server Database Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-14Additional Sample Setup Information . . . . . . . . . . . . . . . . . . . . . . . . . . . A-15

Appendix B: Return Codes B-1Client-Library RETCODE Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1CTBRESULTS RESULT-TYP Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-3

Appendix C: Client Program Messages C-1Server Messages returned by Client-Library . . . . . . . . . . . . . . . . . . . . . . . . . . . C-1Client Messages returned by Client-Library. . . . . . . . . . . . . . . . . . . . . . . . . . . . C-2Client-Library Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-3

Appendix D: UAMM Error Messages D-1UAMM General Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-1UAMM Detailed Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-2

Appendix E: Client-Library C Kit E-1UniAccess C Header Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-1

List of Header Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-2Using Client-Library C Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-3

Client-Library C Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-4ct_bind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-6ct_callback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-7ct_cancel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-12ct_close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-13ct_cmd_alloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-14ct_cmd_drop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-15ct_cmd_props . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-16ct_command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-17ct_compute_info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-18ct_con_alloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-23ct_con_drop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-24ct_con_props . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-25ct_config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-26ct_connect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-27


Contents vii

ct_describe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-28ct_diag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-29ct_exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-30ct_fetch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-31ct_get_format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-32ct_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-33ct_param . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-34ct_remote_pwd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-35ct_res_info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-36ct_results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-37ct_send . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-38cs_config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-39cs_convert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-40cs_ctx_alloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-42cs_ctx_drop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-43cs_will_convert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-44

Appendix F: References F-1AIS References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . F-1Microsoft References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . F-2Sybase References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . F-2Unisys References. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . F-2

Glossary G-1

Index I-1

viii UniAccess for OS 2200 Client-Library Programming Reference


List of FiguresFigure 1-1: Client/Server Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3Figure 1-2: Server Activities Available to UACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7Figure 1-3: UniAccess Client-Library Communications. . . . . . . . . . . . . . . . . . . . . . . . 1-9Figure 1-4A: UACL and UASL Using the Same UACS . . . . . . . . . . . . . . . . . . . . . . . 1-9Figure 1-4B: UACL and UASL Using Different UACSs . . . . . . . . . . . . . . . . . . . . . . . 1-9Figure 1-5: Basic Control Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-16Figure A-1: Components of the UniAccess Sample System . . . . . . . . . . . . . . . . . . . . A-6


Contents ix

List of TablesTable 1: Client-Library Programming Reference Organization . . . . . . . . . . . . . . . . . xviiTable 1-1: Attributes of UniAccess System Servers . . . . . . . . . . . . . . . . . . . . . . . . . 1-13Table 1-2: Attributes of Non-UniAccess System Servers . . . . . . . . . . . . . . . . . . . . . 1-14Table 1-3: Steps in a Simple Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-17Table 2-1: Summary of 8-bit-byte Architecture and OS 2200 Ranges . . . . . . . . . . . . . 2-2Table 2-2: Interaction between ACTION, BUFFER,

BUFFER-LEN, and OUTLEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4Table 2-3: Values for CLIENTMSG’s CMSG-SEVERITY Field . . . . . . . . . . . . . . . . 2-7Table 2-4: Fields in the DATAFMT Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14Table 2-5: Values for DATAFMT’s FMT-FORMAT Field . . . . . . . . . . . . . . . . . . . 2-15Table 2-6: Lengths Referred to by DATAFMT’s FMT-MAXLEN Field . . . . . . . . . 2-16Table 2-7: Values for DATAFMT’s FMT-STATUS Field . . . . . . . . . . . . . . . . . . . . 2-17Table 2-8: Summary of UniAccess Client-Library Datatypes . . . . . . . . . . . . . . . . . . 2-18Table 2-9: Summary of UniAccess Client-Library COBOL Definitions . . . . . . . . . . 2-19Table 2-10: Interoperability Between UniAccess Client-Library

and Microsoft SQL Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-28Table 2-11: UniAccess Client-Library for OS 2200 Properties . . . . . . . . . . . . . . . . . 2-34Table 2-12: Values for CS-TDS-VERSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-40Table 2-13: Values for SERVERMSG’s SMSG-SEVERITY Field . . . . . . . . . . . . . . 2-50Table 2-14: Context Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-56Table 2-15: Connection Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-57Table 2-16: Command Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-58Table 2-17: Functions that Manipulate Hidden Structures . . . . . . . . . . . . . . . . . . . . . 2-58Table 2-18: UCS C Equivalents for Client-Library Functions . . . . . . . . . . . . . . . . . . 2-60Table 2-19: Alignment Requirements for UACL and COBOL datatypes. . . . . . . . . . 2-64Table 2-20: Alignment Requirements for COBOL Datatypes . . . . . . . . . . . . . . . . . . 2-65Table 3-1: List of Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1Table 3-2: Fields in the DATAFMT Structure for CTBBIND . . . . . . . . . . . . . . . . . . . 3-5Table 3-3: Datatype Conversions Performed by CTBBIND . . . . . . . . . . . . . . . . . . . 3-10Table 3-4: Fields in the DATAFMT Structure for CTBDESCRIBE . . . . . . . . . . . . . 3-66Table 3-5: Summary of Arguments (CTBDIAG) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-72Table 3-6: Fields in the DATAFMT Structure for CTBPARAM . . . . . . . . . . . . . . 3-100Table 3-7: Summary of Arguments (CTBPARAM) . . . . . . . . . . . . . . . . . . . . . . . . . 3-102Table 3-8: DATAFMT Fields for Language Request Parameters

with CTBPARAM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-103Table 3-9: DATAFMT Fields for RPC Parameters with CTBPARAM . . . . . . . . . . 3-104Table 3-10: Summary of Arguments (CTBRESINFO) . . . . . . . . . . . . . . . . . . . . . . 3-116

x UniAccess for OS 2200 Client-Library Programming Reference


Table 3-11: Fields in the SRCFMT Structure for CSBCONVERT . . . . . . . . . . . . . 3-143Table 3-12: Fields in the DESTFMT Structure for CSBCONVERT . . . . . . . . . . . . 3-145Table 3-13: Datatype Conversions Performed by CSBCONVERT . . . . . . . . . . . . . 3-147Table A-1: UniAccess Client-Library Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2Table A-2: Functional View of the Sample Databases . . . . . . . . . . . . . . . . . . . . . . . . A-7Table A-3: Logical View of the Sample Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . A-8Table A-4: Physical View of the UASAMPLE RDMS 2200 Database . . . . . . . . . . . A-9Table A-5: Physical View of the uasample SQL Server Database . . . . . . . . . . . . . . A-10Table A-6: UniAccess Stored Procedures for SQL Server . . . . . . . . . . . . . . . . . . . . A-12Table B-1: RETCODE Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-2Table B-2: RESULT-TYP Values for CTBRESULTS . . . . . . . . . . . . . . . . . . . . . . . . B-3Table C-1: Values for CLIENTMSG's CMSG-SEVERITY Field . . . . . . . . . . . . . . . . C-3Table E-1: UniAccess Client-Library C Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-4Table E-2: Summary of Parameters (ct_compute_info) . . . . . . . . . . . . . . . . . . . . . . . E-19


Preface

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Preface

About This BookThis manual accompanies the UniAccess System for OS 2200 product suite. It references UniAccess Client-Library (UCS COBOL) functions and explains how to use them in writing OS 2200 client applications. It also documents the UCS C interface to UniAccess Client-Library.

Audience

The UniAccess for OS 2200 Client-Library Programming Reference is designed for programmers who are writing OS 2200 client applications. The application programmer should be familiar with the COBOL or C programming language.

UniAccess System Product Suite

UniAccess Client-Library is one component of the UniAccess Transaction Client package. The other components of the package, listed below, may be referred to in this manual, but are explained more fully in the UniAccess for OS 2200 System Administration Guide. The following is a list of the entire product suite for your convenience:

UniAccess Transaction Client for OS 2200, which includes:UACL (UniAccess Client-Library)ISQL for OS 2200 (Interactive SQL Parser)UniAccess core components

xii UniAccess for OS 2200 Client-Library Programming Reference


UniAccess Transaction Server for OS 2200, which includes:UASL (UniAccess Server-Library)UADriver (UniAccess ODBC Driver)UADTC (UniAccess Distributed Transaction Coordinator) UniAccess core components

UniAccess ODBC Server for RDMS 2200, which includes:UARS (UniAccess Relational Service)UADriver (UniAccess ODBC Driver)UADTC (UniAccess Distributed Transaction Coordinator) UniAccess core components

UniAccess ODBC Server for DMS 2200, which includes:UAHS (UniAccess Hierarchical Service)UADriver (UniAccess ODBC Driver)Schemadef utilityTabledef utilityUniAccess core components

The UniAccess core components, included in all product packages, are the UniAccess Communication Server (UACS), the UniAccess Configuration Utility (UACF), the UniAccess Data Manager (UADT), and the UniAccess Message Manager (UAMM). Their configuration and management are discussed in the UniAccess for OS 2200 System Administration Guide.

Related Documentation

In addition to this manual, the following documents are included in the UniAccess System for OS 2200 product suite:

UniAccess for OS 2200 System Administration GuideThis manual describes all installation and administrative aspects of the UniAccess for OS 2200 system. It describes the components of the UniAccess System and how to configure them to interface with Unisys 2200 components.

UniAccess for OS 2200 Client GuideThis manual describes the development and use of ODBC and Open Client applications that interface with UniAccess Transaction Server, UniAccess ODBC Server for RDMS 2200, and UniAccess ODBC Server for DMS 2200.


Preface xiii

It includes information on the UniAccess ODBC Driver, UniAccess Relational Service, and UniAccess Hierarchical Service.

UniAccess for OS 2200 Server-Library Programming ReferenceThis manual describes UniAccess Server-Library functions and contains instructions for using them to write OS 2200 applications that accept and process client requests. It documents the UCS COBOL, ASCII COBOL, and UCS C interfaces to UASL.

You will also need programmer’s guides and language reference manuals for the languages in which you will write OS 2200 programs. Appendix F lists other relevant manuals.

Conventions Used in this ManualAs you read this manual, you should understand how certain fonts, formats, and terminology are used.

Fonts and Format

The following general conventions are adhered to in this manual:

• Product names are capitalized: UniAccess Client-Library; SQL Server.

• Publication names and chapter names within publications are italicized: UniAccess for OS 2200 Client-Library/COBOL Reference; see Chapter 3, Function Descriptions.

• Bold type and italics are used for emphasis in the text.

In addition, certain fonts and conventions represent specific object types:

• In examples, information displayed on a computer screen is shown in Courier font: COPY CTPUBLIC.

• The following terms are in Arial bold:

— Client-Library and Server-Library function names: CTBINIT; TDINIT.

xiv UniAccess for OS 2200 Client-Library Programming Reference


— Other commands in the text: a select statement.

• The following terms are italicized:

— Client-Library function argument names and fields within arguments: DATAFMT; FMT-NAME.

— Variables: YES; UARS.

• All other terms are in regular typeface. Host-based objects and values are typically shown in all capital letters, e.g., datatypes, symbolic values, and file nameS: DATETIME; CS-SUCCEED; SYS$LIB$*UAUTIL.

Valid function names are only eight characters long; however, in this manual, the entire name will be used in the text to facilitate ease of understanding. For example, the complete name of the function that cancels a request is CTBCANCEL, but its valid name is CTBCANCE. Valid names are used in examples.

The syntax section for each function shows the order in which the arguments are coded, the datatype of each argument, and whether it is an input or output argument. Input arguments are indicated by an (I) following the argument name; output arguments are indicated by an (O). (See the definition of input and output arguments in the following subsection.)

Terminology

Some familiar terms have a particular meaning when used with the UniAccess System for OS 2200. The following list explains how they are used in this manual. (For a more comprehensive list of terms, please see the Glossary.)

UniAccess System for OS 2200. Refers to the entire suite of AIS products that implements Microsoft client/server architecture on the Unisys OS 2200 system. The UniAccess System provides components that function as either clients or servers, although some components, such as UACS, are shared by both client and server systems. To facilitate the discussion of client and server systems, the following terms are used:

UniAccess Transaction Client refers to UACL and core components when they function as an Open Client. It also includes an interactive SQL command line utility (ISQL).


Preface xv

UniAccess Transaction Server refers to UASL and core components when they function as a server. It also includes the client component UADriver and, optionally, UADTC.

UniAccess ODBC Server for RDMS 2200 refers to UARS and core components when they function as a server. It also includes the client component UADriver and, optionally, UADTC.

UniAccess ODBC Server for DMS 2200 refers to UAHS and core components when they function as a server. It also includes the client component UADriver.

Host. Refers to the hardware system on which a software application runs. In this manual, the term host generally refers to the Unisys OS 2200 mainframe where the UniAccess System for OS 2200 software is running.

Client. Anything functioning as a client in the Microsoft client/server architecture. A client can be an ODBC compliant application, an Open Client program, a UniAccess Client-Library program, or a stored procedure on a SQL Server. In this manual, the term Open Client application generally includes ODBC-compliant applications.

Server. Anything functioning as a server in the Microsoft client/server architecture. A server may be a UniAccess System server on the OS 2200 (UniAccess Transaction Server, UniAccess ODBC Server for RDMS 2200, or UniAccess ODBC Server for DMS 2200), a SQL Server, or a SYBASE Open Server application.

SQL Server. A database server in the Microsoft client/server architecture that accepts RPCs or language requests written in Transact-SQL. There are two implementations of SQL Server: Microsoft SQL Server and Sybase SQL Server (a.k.a. Adaptive Server Enterprise—ASE), which provide many similar features. When this manual refers to SQL Server, it is referring to features common to both SQL Servers. Features specific to an implementation will be identified as either Microsoft SQL Server or Sybase SQL Server.

Local / Remote. The term local usually refers to whatever system is the topic under discussion. The local system must be accessed directly without using network access. Remote refers to an area or system on the network but outside the local host. Thus, in the UniAccess System manuals, local may refer to the OS 2200 host when indicated by the context of the passage.

xvi UniAccess for OS 2200 Client-Library Programming Reference


Language request. A language request contains character strings that represent requests in a server’s own language. Language requests are flexible and interactive. They may be entered on an ad hoc basis (as in isql) or be predefined in an Open Client application (e.g., in the Client-Library function CTBCOMMAND). A language request can be in any language so long as the server to which it is directed understands it. For example, SQL Servers understand Transact-SQL and RDMS 2200 understands RDMS 2200-compliant SQL. A user-written language transaction can process whatever syntax (language) the user designs into the transaction.

Remote procedure call (RPC). A request issued by an Open Client (including ODBC client) application that is processed by a stored procedure on a SQL Server or by a Server-Library transaction.

Stored procedure. A collection of SQL statements and optional sequence of flow-of-control statements stored under a specific name on a server. In the UniAccess System, a stored procedure is one that has been created and exists (is stored) on a SQL server or in RDMS 2200.

Application. A program or group of programs that, when executed, accomplish a particular action.

Transaction. A program that runs in a TIP environment on the OS 2200 system and is initiated by a single request. In the UniAccess System, TIP transactions may act as either clients or servers. Client transactions are created with UACL (Client-Library) functions; server transactions are created with UASL (Server-Library) functions. The term Server-Library transaction refers to user-written UASL transactions as well as to the UARS and UAHS transactions (specific UASL-built transactions that process SQL language requests for RDMS 2200 and DMS 2200, respectively).

Argument. A Client-Library function parameter. Some functions operate on outgoing RPC parameters sent by the client; some operate on incoming RPC parameters returned by the server. For the sake of clarity, the function parameters are called arguments; the term parameter is used exclusively to refer to arguments sent by the client or returned by the server in response to an RPC request.

Input and Output Arguments. An input argument has its value specified by the program; an output argument returns a value to the program. For example, in the function CTBBIND, which associates a returned column, parameter, or status with a program


Preface xvii

variable, the argument DATAFMT is an input argument that describes destination variables. However, in CTBDESCRIBE, which uses the same argument to return a description of result data, the argument is an output argument. The RETCODE argument is always an output argument, since it is returned to, not specified by, the program.

How This Manual Is OrganizedThis manual is designed to be used as a reference. You do not have to read it from front to back. However, it is a good idea to read the introductory chapter before you begin to develop programs using these functions. Table 1 describes the contents of the chapters and appendixes in this manual.

Table 1: Client-Library Programming Reference Organization

Manual Organization Page

Chapters 1 Introduction to UniAccess Client-Library

Provides an overview of UniAccess Client-Library. This chapter contains a general discussion of client/server architecture and a description of the UniAccess Server-Library.

2 TopicsContains descriptions of UniAccess Client-Library concepts and information on how to accomplish specific programming tasks.

3 Function DescriptionsLists all Client-Library functions and describes each function in detail. Each function description contains sections on functionality, syntax, return codes, related functions, and explanatory comments, as well as an example.

1-1

2-1

3-1

Appendixes A Sample Programs

Describes the UniAccess sample program system in general and the Client-Library programs in particular. These programs are included on the UniAccess distribution tape.

B Return CodesLists all the return codes that can result from execution of Client-Library functions and gives a brief description of each. Includes values returned by CTBRESULTS.

A-1

B-1

xviii UniAccess for OS 2200 Client-Library Programming Reference


C Client Program MessagesExplains the types of messages returned by Client-Library functions and describes their format.

D UAMM Error MessagesLists error messages returned by the UniAccess Message Manager in the TDFHEIBLK TDSUBERROR field.

E Client-Library C KitProvides support for the UCS C language interface to UniAccess Client-Library.

F ReferencesLists technical references pertaining to the UniAccess System for OS 2200.

C-1

D-1

E-1

F-1

Manual Organization Page


1 Intro to Client-Library

1 Introduction to UniAccess Client-Library

This chapter provides a general discussion of client/server architecture and an overview of the UniAccess System for OS 2200. It also describes UniAccess Client-Library and explains how Client-Library functions are used to build client applications.

Topics Page

Client/Server Architecture 1-2

Client/Server Overview 1-2

Types of Servers 1-4

Types of Clients 1-5

UniAccess System for OS 2200 1-5

The UniAccess Transaction Client 1-6

Communication with a Server 1-8

Servers in the UniAccess Transaction Client Environment

1-10

Using UniAccess Client-Library Functions 1-15

Basic Control Structures 1-15

Steps in a Simple Program 1-17

Notes on the Simple Program 1-18

Developing Client-Library Applications 1-21

1-2 UniAccess for OS 2200 Client-Library Programming Reference


Client/Server ArchitectureThe Microsoft® client/server architecture provides common interfaces across the client and server operating systems. This consistency allows software developers and integrators to use common tools and methodologies for the client and the server portions of an application and to move components between the client and the server as the need arises. Microsoft’s unified client/server architecture also delivers the broadest possible range of hardware and software support, bringing users a multitude of industry-leading development tools, end-user query tools, and off-the-shelf packages without restriction or modification. It provides the foundation for using the best of the present hardware and ensures a smooth migration to new hardware and software technologies as they become available.

Client/Server Overview

Client/server architecture divides the work of computing between clients and servers and defines an interface between them.

• Clients make requests of servers and process the results of those requests. For example, a client application might request data from a database server. Another client application might send a request to an environmental control server to lower the temperature in a room. (See Figure 1-1.)

• Servers respond to requests by returning data or other information to clients, or by taking some action. For example, a database server returns tabular data and information about that data to clients, and an electronic mail server directs incoming mail toward its final destination.

• An interface connects client and server software through clearly defined, message-based protocols. Interface components are often incorporated within client and server systems and may be transparent to the user.

Figure 1-1 illustrates the relationship between clients and servers.


Introduction to UniAccess Client-Library 1-3

Figure 1-1: Client/Server Model

Client/server architecture has several advantages over traditional program architectures:

• Application size and complexity can be significantly reduced, because common services are handled in a single location, a server. This simplifies client applications, reduces duplicate code, and makes application maintenance easier.

• Application logic can be split among several different servers and/or clients to achieve flexibility and performance. Organizations can leverage all of their available computing power across a variety of clients and servers.

action

server

serverclient

client

results

request for data

request to take an action

request for data

results

request for data

results



• Client/server architecture facilitates communication between varied applications. Client applications that use dissimilar communication protocols cannot communicate directly to each other, but can communicate through a server that speaks both protocols.

• Client/server architecture allows applications to be developed with distinct components, which can be modified or replaced without affecting other parts of the application.

• A robust client/server architecture enables enterprise environments to handle multiple, simultaneous events without degradation of performance. It provides the capacity to handle a growing number of transactions.

Types of Servers

The UniAccess System allows access to several types of servers, among them:

• UniAccess Servers (see page 1-10)

— UniAccess Transaction Server (UASL transactions)

— UniAccess ODBC Server for RDMS 2200 (UARS transaction)

— UniAccess ODBC Server for DMS 2200 (UAHS transaction).

• Non-UniAccess Servers (see page 1-11)

— SQL Servers, including stored procedures on a SQL server

— SYBASE Open Server programs

— RDMS 2200 stored procedures (supported by UniAccess ODBC Server for RDMS 2200).



Types of Clients

Basically, a client is any application that makes requests of a server. Valid clients within the UniAccess System include:

• ODBC-based applications using the UniAccess ODBC Driver, such as:

— End-user query and decision-support tools, such as Microsoft Query

— Vertical applications written with ODBC-compliant application development tools, such as Microsoft Visual Basic

— Administrative and development utilities such as Microsoft ODBC Test.

• Open Client applications, including the following:

— Applications written using SYBASE Open Client programming interfaces

— Applications written using SYBASE Embedded SQL programming interface

— Requests written in Transact-SQL

— Applications written using UniAccess Transaction Client (UACL) programming interfaces, including ISQL for OS 2200

— Stand-alone utilities provided with SQL Servers, such as isql.

UniAccess System for OS 2200The UniAccess System for OS 2200 implements Microsoft client/server architecture for the Unisys OS 2200 system. It provides seamless integration among DBMSs, applications, and hardware systems within a TCP/IP network environment. Any application development tool, end-user tool, database server, Internet server, or transaction processing system compatible with the Microsoft architecture may interoperate through UniAccess with any data source or program on an OS 2200 system. Thus, UniAccess transforms OS 2200 systems into Microsoft enterprise servers and enables the modernization of existing applications and databases to client/server, intranet, or Internet applications.



UniAccess client, server, and interface components interact transparently with both local and remote services, allowing the client application to retrieve and manipulate data easily from an OS 2200 host. The OS 2200-based servers are UniAccess Transaction Server, UniAccess ODBC Server for RDMS 2200, and UniAccess ODBC Server for DMS 2200. They process requests from PC-based ODBC clients and Open Clients as well as from UniAccess Transaction Client. The UniAccess Transaction Client allows OS 2200 applications to make requests of various servers, including SQL Servers and OS 2200 transactions. To the client, the processes of the three UniAccess servers appear the same as those of a SQL Server. The processes of the Transaction Client, on the other hand, appear the same as other Open Client applications.

Programmers working in the UniAccess Transaction Client environment write the applications that will make requests of remote servers or of local UniAccess servers. Programmers working in the UniAccess Transaction Server environment generally write OS 2200 TIP transactions that process client requests. A TIP transaction must be associated with each client request to the UniAccess Transaction Server. No OS 2200 programming is required of those working with UniAccess ODBC Server for RDMS 2200 nor UniAccess ODBC Server for DMS 2200, as the required TIP transaction for each is provided.

The UniAccess ODBC Server for RDMS 2200 and the UniAccess ODBC Server for DMS 2200 are documented in the UniAccess for OS 2200 Client Guide. The UniAccess Transaction Server is documented in the UniAccess for OS 2200 Server-Library Programming Reference. All are explained in more detail in the UniAccess for OS 2200 System Administration Guide.

The UniAccess Transaction Client

UniAccess Transaction Client is the group of UniAccess System products that provide client capabilities on the OS 2200 system. It allows Unisys mainframe-based applications remote access to Microsoft and Sybase SQL Servers, as well as any Open Server applications. In addition, Transaction Client applications can access OS 2200 TIP transactions through the UniAccess Transaction Server and ODBC Servers. UniAccess Transaction Client includes the UniAccess Client-Library and the ISQL parser; it also includes UACS—the communication server—and other core (interface) components. (The configuration and management of the UniAccess core components are discussed in the UniAccess for OS 2200 System Administration Guide; ISQL is discussed in Chapter 13 of that manual.)



UniAccess Client-Library

UniAccess Client-Library (UACL) is the library of functions that allows programmers to write client applications on the OS 2200 system. These applications may make requests of Server-Library transactions on the OS 2200 host or of other servers in the same network environment, such as SQL Servers and Open Server applications. And, like other Open Clients, UACL-written applications can issue either RPCs or language commands; they can invoke stored procedures on servers.

The following diagram illustrates some of the different server activities available to UniAccess Client-Library applications:

Figure 1-2: Server Activities Available to UACL

SQL Server

Open Server

Open Server

real-time data

electronic mail

UniAccessClient-Library for OS 2200

request for data

results

request tosend mail

UniAccess Transaction Server and ODBC Servers

OS 2200 data

database



UniAccess Client-Library performs the following tasks:

• Establishes and manages program-to-program conversation

• Communicates with UniAccess System servers, SQL Servers, and Open Servers using TDS protocol

• Issues client language and RPC requests

• Accepts and processes responses and performs datatype translations as necessary

• Manages error, information, and security control.

UACL is implemented in the extended mode environment. It supports UCS COBOL and includes an interface to the UCS C language. This manual documents UACL and all Client-Library functions as well as the C programming language interface. (For information on the UCS C programming language interface, see page 2-60.)

Communication with a Server

UniAccess Communication Server (UACS) on the OS 2200 host provides the central communication link between the Client-Library application and its corresponding server application. This is true whether the server is a UniAccess System server on the OS 2200 system or a remote server, housed on another platform (a SQL Server or Open Server).

All requests sent from a client to a server and all replies returned from a server to a client pass through UACS. When UACS receives a client request, it processes the request as follows:

• It establishes a connection with the remote server and passes the request on to that server.

• It accepts results from the server transaction and returns them to the requesting client.

The role of UACS as the communications link between UACL transactions and a server is depicted in Figure 1-3.



Figure 1-3: UniAccess Client-Library Communications

When the server is the UniAccess Transaction Server, both the client and server applications will reside on the OS 2200 host and use UACS as the communication server. In this case, both the client and server could use a single UACS, as in Figure 1-4A or they may each use a different UACS, as in Figure 1-4B.

Figure 1-4A: UACL and UASL Figure 1-4B: UACL and UASL Using the Same UACS Using Different UACSs

SQ LServer

O pen Server

O S 2200

client application

W orkstation

U N IX

U A C L U A C S

UACL UACS1

UASL

client application

server application

OS 2200

UACS2

UACL

UACS

UASL

client application

server application

OS 2200



UACL uses the application-level protocol TDS (Tabular Data Stream) to transfer requests and replies between clients and servers. TDS describes the form and content of client login information, client requests, row and column information in results data, and security information. Client-Library functions automatically issue the appropriate TDS protocols; therefore, no additional OS 2200 code is needed to send or receive data streams. This enables applications programmers to write programs that use TDS without knowing the details of that protocol.

Servers in the UniAccess Transaction Client Environment

The UniAccess System allows access to several types of UniAccess and non-UniAccess servers. The UniAccess System servers include UniAccess Transaction Server for OS 2200, UniAccess ODBC Server for RDMS 2200, and UniAccess ODBC Server for DMS 2200. The non-UniAccess System servers include SQL Server, SYBASE Open Server programs, and RDMS 2200 stored procedures. Each are described in the following section.

UniAccess System Servers

In addition to the unique components discussed below, each UniAccess System server package includes UACS, the communications server, which translates and routes requests between clients and servers, other core components that define, manage, and relay system information, and the client-based UniAccess ODBC Driver.

UniAccess Transaction Server for OS 2200 allows new and existing Unisys TIP transactions on the OS 2200 system to respond as servers to client applications. UniAccess Server-Library (UASL), the unique component of UniAccess Transaction Server, provides a library of functions that allow programmers to create individual transactions to access a variety of OS 2200 data. Programmers can assemble transactions from pre-built software parts rather than write each transaction from scratch. They use these functions primarily to create RPC-processing transactions, although they may create general-purpose language transactions as well. Transactions written with Server-Library functions appear and act like stored procedures on SQL Servers—they follow similar routines to connect and communicate with specific environments. (Server-Library functions are documented in the UniAccess for OS 2200 Server-Library Programming Reference.)



UniAccess ODBC Server for RDMS 2200 services client language requests to RDMS 2200. Its unique component, UARS (UniAccess Relational Service for RDMS 2200) is an OS 2200 transaction that accepts SQL language requests from multiple clients, processes the requests using the RDMS 2200 interpretive SQL interface, and returns results to clients. In addition, UARS supports RDMS 2200 stored procedures. UARS is an AIS-written TIP transaction, built with UniAccess Server-Library functions. (UARS is explained in more detail in Chapter 6 of the UniAccess for OS 2200 Client Guide.)

UniAccess ODBC Server for DMS 2200 services client language requests to DMS 2200. Its unique component, UAHS (UniAccess Hierarchical Service for DMS 2200) is an OS 2200 transaction that provides multi-user SQL query capability to DMS 2200 databases by converting SQL commands to DMS access commands. UAHS is an AIS-written TIP transaction, built with UniAccess Server-Library functions. (UAHS is explained in more detail in Chapter 9 of the UniAccess for OS 2200 Client Guide.)

Non-UniAccess System Servers

SQL Server is a database server. SQL Servers manage multiple databases and multiple users, keep track of the actual location of data on disks, maintain mapping of logical data description to physical data storage, and maintain data and stored procedure caches in memory. SQL servers accept requests in the form of remote procedure calls (RPCs) or language requests written in Transact SQL. (See page 2-43 for a comparison of RPCs and language requests.) There are two implementations of SQL Server: Microsoft SQL Server and Sybase SQL Server. Both may be accessed by UACL applications.

SYBASE Open Server allows programmers to develop applications that can be any type of server. For example, an Open Server application can perform specialized calculations, provide access to real-time data, or interface with services such as electronic mail. An Open Server application is created individually, using the building blocks provided by SYBASE Open Server library functions. It can be programmed to accept any client request.

RDMS 2200 stored procedures are written by the customer and supported by the UniAccess Relational Service for RDMS 2200. An RDMS stored procedure (supported as of RDMS 2200 Level 9R1) is a group of SQL commands that reside in RDMS 2200 and can be executed as one unit (see the RDMS documentation, listed in Appendix E, for implementation details). Currently, they cannot generate result sets as can UniAccess Server-Library transactions.



Similarities and Differences in Servers

UniAccess Server, SQL Server, and Sybase Open Server applications and stored procedures are similar in some ways:

• The UniAccess System server, SQL Server, Open Server applications and stored procedures are all servers responding to client requests.

• These servers use the Tabular Data Stream (TDS) protocol to communicate with client applications.

But these servers differ in other ways:

• An application programmer must create a UASL or an Open Server application by using the products’ building blocks and by supplying custom code. Stored procedures are created by compiling SQL statements in the language of the database on which they will reside. SQL Servers and UARS are complete and do not require custom code.

• An Open Server application can be any kind of server and can be written to understand any language. UASL applications operate on an OS 2200 platform and may be programmed to understand any commands understood by the OS 2200 service it accesses. SQL Servers (and the stored procedures that reside on them) are database servers and understand only Transact-SQL. UARS is a transaction for RDMS 2200 and understands only dynamic SQL. (Likewise, stored procedures residing on RDMS 2200 understand only RDMS 2200 SQL syntax.)

• A Microsoft SQL Server (and the stored procedures that reside on it) can communicate directly with other Microsoft SQL Servers; to communicate with an OS 2200 server or client, it must utilize UniAccess Communication Service (UACS) for OS 2200. Likewise, RDMS stored procedures can communicate directly with the RDMS database, but require the UARS transaction, with its accompanying UACS component, to be accessed by a client in the UniAccess environment.



• UniAccess System server applications communicate with clients through UACS, the UniAccess Systems communications link. This communication, however, is transparent to the client and appears the same as a request sent to an SQL server.

Tables 1-1 and 1-2 show the similarities and differences among these servers.

Table 1-1: Attributes of UniAccess System Servers

UniAccess Transaction Server

UniAccess ODBC Server for RDMS 2200

UniAccess ODBC Server for DMS 2200

Server Type: Provides the tools to build OS 2200 servers; the programmer must create the server application.

Provides a server transaction for RDMS 2200(the server is complete).

Provides a server transaction for DMS 2200 (the server is complete).

Language: Application can be programmed to understand any OS 2200 application language.

Understands only dynamic SQL.

Converts dynamic SQL commands to DML access commands.

Platform: Operates on OS 2200 platform.

Operates on the OS 2200 platform against RDMS 2200.

Operates on the OS 2200 platform against DMS 2200.

Communica- tions:

Communicates directly with OS 2200 transactions.

Communicates transparently with Open Clients, SQL Servers, and UniAccess Client-Library applications through UACS.

Directly retrieves and/or modifies data on RDMS 2200.


Directly retrieves data on DMS 2200.


Protocol: Uses TDS protocol. Uses TDS protocol. Uses TDS protocol.



Table 1-2: Attributes of Non-UniAccess System Servers

SQL Server SYBASEOpen Server

RDMS 2200 Stored Procedures

Server Type: Database server(the server is complete).

Allows for the creation and maintenance of stored procedures.

Tools to build a variety of servers; the programmer must create the server application.

A collection of pre-complied SQL statements, executed as one unit.

Language: Understands only Transact-SQL.

Application can be programmed tounderstand any language.

Written in RDMS SQL.

Platform: Microsoft SQL Server operates on Windows platforms.

Sybase SQL Server operates on a variety of platforms.

Operates on a variety of platforms.

Operates on OS 2200, RDMS 2200 9R1 or greater.

Communications: Microsoft SQL Server can communicate directly with clients and other Microsoft SQL Servers. It can communicate indirectly with OS 2200 clients or servers through an interface such as UACS.

Sybase SQL Server can communicate directly with clients and other Sybase SQL Servers. It can communicate directly with OS 2200 clients or servers through an interface such as UACS.

Application can be programmed to communicate directly with any client or server.

Can communicate indirectly with OS 2200 clients or servers through UACS.

Communicates directly with an RDMS 2200 database.

To be accessed by an Open Client, requires support from UniAccess ODBC Server for RDMS 2200.

Protocol: Uses TDS protocol. Uses TDS protocol. Uses RDMS 2200.

When accessed via UniAccess ODBC Server for RDMS 2200, uses TDS.



Using UniAccess Client-Library FunctionsUACL contains a programming interface of functions to be used in writing OS 2200 system client applications. Some functions send requests to a server; others process the results. Additional functions set application properties, handle error conditions, and provide a variety of information about an application’s interaction with a server.

An application programmer writes an OS 2200 program using calls to Client-Library functions to set up control structures, connect to servers, send commands, process results, and clean up. A Client-Library program is compiled, linked, and run in the same way as any other COBOL program under OS 2200.

Although this manual only documents functions to be used in client applications, it is helpful to be aware that the functions of client and server applications must correspond to one another. For instance, each time a program at one end of a connection issues a sending function, the program at the other end issues a corresponding receiving function.

Basic Control Structures

In order to send commands to a server, an application must allocate three types of structures, illustrated in Figure 1-5:

• A context structure that defines a particular application context, or operating environment.

• A connection structure that defines a particular client/server connection.

• A command structure that defines a command space in which commands are sent to a server.

The relationship between these control structures is illustrated in Figure 1-5.

An application allocates these structures by calling the functions CSBCTXALLOC, CTBCONALLOC, and CTBCMDALLOC.



Figure 1-5: Basic Control Structures

NoteA UACL application is restricted to one context per application.

Client Application

Context Structure

CommandStructure

CommandStructure

Connection Structure

Connection StructureCommandStructure

commands

resultscommands

results

ServerApplication

results

commands



Steps in a Simple Program

A simple program involves the steps listed in Table 1-3.

Table 1-3: Steps in a Simple Program

Prepare the programming environment: Allocate a context structure; Initialize the environment.

CSBCTXALLOCCTBINIT

Establish a connection with a server: Allocate a connection structure; Set and retrieve the values of the connection’s properties; Open a connection to a server.

CTBCONALLOCCTBCONPROPS

CTBCONNECT

Send a command to the server: Allocate a command structure; Initiate the process of sending a command; Send the command to the server.

CTBCMDALLOCCTBCOMMANDCTBSEND

Process the results of the command: Retrieve the results; Determine the type of results; Process the results.

CTBRESULTS

CTRESINFOCTBBINDCTBFETCH

Finish up: De-allocate the command structure; Close the server connection; Clean up the remaining resources being used by command or connection handles; De-allocate the context structure.

CTBCMDDROPCTBCLOSECTBCONDROPCTBEXITCSBCTXDROP



Notes on the Simple Program

The following section explains the basic framework of a simple UACL program in more detail. Sample UACL programs are provided in SYS$LIB$*UASAMP (or SYS$LIB$*UASAMPT for test mode installations) and explained in Appendix A.

NoteThe copyproc CTPUBLIC is required in all source files that contain calls to UniAccess Client-Library.

Preparing the Programming Environment

CSBCTXALLOC allocates a context structure. A context structure is used to store configuration parameters that describe a particular context, or operating environment, for a set of connections.

Application properties that can be defined at the context level include the version of UniAccess Client-Library being used and the maximum number of connections allowed within the context.

CTBINIT initializes the environment. It must be the first call in an application after CSBCTXALLOC.

Connecting to a Server

CTBCONALLOC allocates a connection structure. A connection structure contains information about a particular client/server connection.

CTBCONPROPS sets and retrieves the values of a connection’s properties. Connection properties include the user name and password, which are used in logging into a server; the application name, which appears in the SQL Server sysprocesses table, and the packet size, which determines the size of network packets that an application will send and receive. User and server definitions are defined in the UniAccess Configuration File. (For more information about the configuration statements that define these attributes, see Chapter 16 of the UniAccess for OS 2200 System Administration Guide.



For a complete list of connection properties, see Properties on page 2-33.

CTBCONNECT opens a connection to a server, logging into the server with the connection information specified via CTBCONPROPS.

Sending a Command to the Server

CTBCMDALLOC allocates a command structure. A command structure is used to send commands to a server and to process the results of those commands.

CTBCOMMAND initiates the process of sending a command.

CTBSEND sends the command to the server.

Processing the Results of the Command Almost all Client-Library programs will process results by using a loop controlled by CTBRESULTS. Inside the loop, one of several actions takes place on the current type of result. Different types of results require different types of processing.

For row results, typically the number of columns in the result set is determined and then used to control a loop in which result items are bound to program variables. An application can call CTBRESINFO to get the number of result columns, but this is not necessary if an exact number of columns is selected. After the result items are bound using CTBBIND, the application calls CTBFETCH to fetch data rows until end-of-data.

A typical results-processing model looks like this:

Action Functions

1. Retrieve results: CTBRESULTS

2. Determine the type of results by examining the value in the RESULT-TYP field.

3. Process results: CTBRESINFO, CTBDESCRIBE, CTBIND, CTBFETCH



CTBRESULTS sets up results for processing. The CTBRESULTS return argument RESULT-TYP indicates the type of result data that is available for processing. (All values for RESULT-TYP returned by CTBRESULTS are listed in Appendix B.)

Note that the example code fragment on page 3-126 calls CTBRESULTS in a loop that continues as long as CTBRESULTS returns CS-SUCCEED, indicating that result sets are available for processing. Although this type of structure is not strictly necessary for simple language programs, it is highly recommended. In more complex programs, it is not possible to predict the number and type of result sets that an application will receive in response to a command.

CTBBIND binds a result item to a program variable. Binding creates an association between a result item and a program data space.

CTBFETCH fetches result data. If binding has been specified and the count field in the DATAFMT structure for each column is set to 1, each CTBFETCH call copies one row of data into program data space. As each row is fetched, the example program prints it.

After the CTBFETCH loop terminates, the program might be written to check its final return code to find out whether the loop terminated because of end-of-data or because of failure.

Close Connections and Terminate

CTBCMDDROP de-allocates the command structure.

CTBCLOSE closes the server connection.

CTBCONDROP de-allocates the connection structure.

CTBEXIT cleans up the remaining resources being used by command or connection handles.

CSBCTXDROP de-allocates the context structure.



Developing Client-Library Applications

Chapter 3 contains a detailed description of each Client-Library function. Each entry includes a functional description, the syntax (including the datatype of each argument), an explanation of each argument, an example of the function’s use, possible return codes, and a list of related topics.

Most code examples in the function descriptions are taken from the sample programs provided in SYS$LIBB$*UASAMP (or SYS$LIB$*UASAMPT for test mode installations) and explained in Appendix A. These programs show how the individual function is coded in context of a complete program. They demonstrate how to set up WORKING STORAGE.

Your application must include a set of constants supplied with the UniAccess System for OS 2200. These constants define the structures, types, and values for the COBOL/Client-Library interface. To include these constants in a COBOL program, specify the copyproc (CTPUBLIC) in the program’s WORKING STORAGE section. To include these constants in a C program, include the header uaclckit.h.

As you begin using Client-Library functions, it will be helpful to understand the following information:

• All arguments of each function are required. If the argument’s value is not needed under particular circumstances, the argument is ignored by the function.

• UACL includes utility functions that allocate, drop, and assign properties to context handles and one function used in datatype conversion. These functions begin with the prefix CSB instead of CTB.

• For most Client-Library functions, the return code is stored in a RETCODE argument. Where this argument exists, it is always the second argument for a function.

• The maximum length allowed for names is 30 bytes.

• Client-Library functions are similar in name and purpose to routines in SYBASE Open Client products. Currently, not all SYBASE Open Client routines are supported. For example, UniAccess Client-Library does not support cursors or compute rows.


2 Topics

2 Topics

This chapter contains information on programming topics, descriptions of datatypes and standard structures, and the use of functions to accomplish specific programming tasks, such as message handling. The topics listed below are discussed in this chapter.

Topics Page

Architectural Differences 2-2

Buffers 2-3

CLIENTMSG Structure 2-6

Compiling and Linking Programs 2-9

DATAFMT Structure 2-13

Datatypes 2-18

Error and Message Handling 2-26

Microsoft SQL Server Access 2-28

Nulls 2-32

Properties 2-33

Remote Procedure Calls 2-43

Results 2-47

SERVERMSG Structure 2-49

SQLCA Structure 2-52

SQLCODE Structure 2-54

Structures 2-55

UCS C Interface 2-60

UniAccess Communication Server (UACS) 2-62

Word Alignment Restrictions 2-64

2-2 Architectural Differences UniAccess for OS 2200 Client-Library Programming Reference


Architectural DifferencesThe 9-bit-byte architecture of the Unisys OS 2200 system supports different ranges of fixed-point binary (CS-TINYINT, CS-SMALLINT, CS-INT) and floating-point binary (CS-REAL, CS-FLOAT) values than are supported on more typical 8-bit-byte architectures. Fixed-point binary values passed to Client-Library functions must fit within the range supported by 8-bit-byte architectures. Fixed-point binary values specified by a Client-Library program that are outside the range supported by the 8-bit-byte architecture will return an error and prohibit the program from passing the value to the server. Floating point binary values passed to Client-Library functions that are outside the range supported by the 8-bit-byte architecture will be rounded before being passed to the server. Table 2-1 summarizes the pertinent 8-bit-byte architecture and OS 2200 ranges.

Table 2-1: Summary of 8-bit-byte Architecture and OS 2200 Ranges

NoteWhen floating point numbers are converted between the OS 2200 architectures and 8-bit-byte architectures, some precision will be lost.

Datatype 8-bit-byteMinimum / Maximum

OS 2200Minimum / Maximum

CS-TINYINT 0 / 255 0 / 511

CS-SMALLINT -32768 / 32767 -131071 / 131071

CS-INT -2147483648 / 2147483647 -34359738367 / 34359738367

CS-REAL machine specific 1.4693679385278600000E-39 /1.7014118219281863170E+38

CS-FLOAT machine specific 2.7813423231340017320E-309 /8.9884656743115795490E+307


Topics Buffers 2-3

BuffersA number of arguments used in Client-Library functions affect the contents of buffers: ACTION, BUFFER, BUFFER-LEN, BUFBLANKSTRIP, and OUTLEN.

ACTION describes what is done to the data. For most functions, ACTION can take the symbolic values CS-GET, CS-SET, and CS-CLEAR:

• CS-SET assigns a value

• CS-GET retrieves a value

• CS-CLEAR clears the buffer.

BUFFER is a program variable, called a buffer.

If ACTION is CS-SET, BUFFER contains the data being read by the function.

If ACTION is CS-GET, BUFFER is the variable in which the function places the retrieved information.

If the function returns CS-FAIL, the value in the buffer remains unchanged.

BUFFER-LEN is the length, in bytes, of BUFFER.

If the value in the buffer is a fixed-length or symbolic value, assign BUFFER-LEN the actual length of the value or CS-UNUSED.

If the value is of variable length, assign BUFFER-LEN the maximum number of bytes that the buffer can contain.

If ACTION is CS-GET and if the returned value is longer than BUFFER-LEN, the function will return CS-FAIL and will return the actual length of the requested information in OUTLEN.

BUFBLANKSTRIP is the blank stripping indicator. It indicates whether or not trailing blanks are stripped (that is, if the value in the buffer ends at the last non-blank character). This argument gets one of the symbolic values CS-TRUE and CS-FALSE:

2-4 Buffers UniAccess for OS 2200 Client-Library Programming Reference


• CS-TRUE indicates that trailing blanks are stripped. The buffer value in the buffer ends at the last non-blank character it contains.

• CS-FALSE indicates that trailing blanks are included in the value; that is, they are not stripped.

OUTLEN is an integer variable used when the function returns the actual length, in bytes, of the data being retrieved during a CS-GET operation. For all other operations, OUTLEN is ignored.

If the retrieved data is longer than BUFFER-LEN bytes, an application can use the value of OUTLEN to determine how many bytes are needed to hold the information. To do this, the application calls the function with the value of OUTLEN set to 0, then calls the function again, using the value returned in OUTLEN for BUFFER-LEN.

The following table summarizes the conventions for using buffers.

Table 2-2: Interaction between ACTION, BUFFER,BUFFER-LEN, and OUTLEN

For ACTION

... ifBUFFER

... then:BUFFER-LEN OUTLEN

What happens:

CS-CLEAR n/a is CS-UNUSED. is ignored. The property reverts to its default value.

CS-SET contains a variable-length character string,

is the length of the string.

is ignored. The data in BUFFER is read by the function.

CS-SET contains a variable-length character string whose terminating character is the last non-blank character,

is the maximum length of the string.

is ignored. The application sets the value of BUFBLANKSTRIP to CS-TRUE.

The data in BUFFER is read by the function.

CS-SET contains a fixed-length character string or symbolic value,

is CS-UNUSED. is ignored. The data in BUFFER is read by the function.


Topics Buffers 2-5

CS-GET is large enough for the return character string,

is the length of the buffer.

is set by Client-Library.

The retrieved value is copied to the buffer.

OUTLEN returns the length of the retrieved value.

CS-GET is not large enough for the return character string,

is the length of the buffer.

is set by Client-Library.

No data is copied to the buffer.

OUTLEN returns the length of the value being retrieved.

The function returns CS-FAIL, indicating that you should assign the value returned here to the length argument and execute the program again.

CS-GET is assumed to be large enough for a fixed-length or symbolic value,

is CS-UNUSED. is set by Client-Library.

The retrieved value is copied to the buffer.

OUTLEN returns the length of the value being retrieved.

For ACTION

... ifBUFFER

... then:BUFFER-LEN OUTLEN

What happens:

2-6 CLIENTMSG Structure UniAccess for OS 2200 Client-Library Programming Reference


CLIENTMSG StructureA client message structure (CLIENTMSG structure) contains information about an error or informational message returned by UniAccess Client-Library. This structure is defined within the application. If the error involves interaction with the operating system, the operating system error information will be returned to this structure. CTBDIAG returns a message string and information about the message into CLIENTMSG.

A CLIENTMSG structure is defined as follows:

01 CLIENT-MSG . 05 CMSG-SEVERITY PIC S9(10) BINARY .05 CMSG-OC-MSGNO PIC S9(10) BINARY .05 CMSG-OC-MSGTEXT PIC X(1024) . 05 CMSG-OC-MSGTEXT-LEN PIC S9(10) BINARY .05 CMSG-OS-MSGNO PIC S9(10) BINARY .05 CMSG-OS-MSGTEXT PIC X(1024) . 05 CMSG-OS-MSGTEXT-LEN PIC S9(10) BINARY .05 CMSG-STATUS PIC S9(10) BINARY .05 CMSG-SQLSTATE PIC X(8) . 05 CMSG-SQLSTATE-LEN PIC S9(10) BINARY .

CMSG-SEVERITY is a symbolic value representing the severity of the message. Severity values are provided in the CTPUBLIC copyproc.

The following table lists the legal values for CMSG-SEVERITY.


Topics CLIENTMSG Structure 2-7

Table 2-3: Values for CLIENTMSG’s CMSG-SEVERITY Field

CMSG-OC-MSGNO is the Client-Library message number. Client-Library messages are explained in Appendix C.

CMSG-OC-MSGTEXT is the text of the Client-Library message string.

CMSG-OC-MSGTEXT-LEN is the length, in bytes, of CMSG-OC-MSGTEXT. If there is no message text, the value of CMSG-OC-MSGTEXT-LEN is 0.

CMSG-OS-MSGNO is the operating system message number (if any). A value here indicates that the message is a UniAccess Message Manager (UAMM) error. (See Appendix D for UAMM error messages.).

These messages include I/O errors that occur while a client request is being processed.

Value of SEVERITY Meaning

CS-SV-INFORM No error has occurred. The message is informational.

CS-SV-CONFIG-FAIL A configuration error has occurred.

CS-SV-RETRY-FAIL An operation has failed, but it can be retried.

CS-SV-API-FAIL A Client-Library function generated an error. This error is typically caused by a bad parameter or calling sequence. The server connection is probably salvageable.

CS-SV-RESOURCE-FAIL A resource error has occurred. This error is typically caused by an allocation error, a lack of file descriptors, or timeout error. The server connection is probably not salvageable.

CS-SV-COMM-FAIL An unrecoverable error in the server communication channel has occurred. The server connection is not salvageable.

CS-SV-INTERNAL-FAIL An internal Client-Library error has occurred.

CS-SV-FATAL A serious error has occurred. All server connections are unusable.

2-8 CLIENTMSG Structure UniAccess for OS 2200 Client-Library Programming Reference


CMSG-OS-MSGTEXT is the text of the operating system message string (if any).

CMSG-OS-MSGTEXT-LEN is the length, in bytes, of CMSG-OS-MSGTEXT. If there is no message text, the value of CMSG-OS-MSGTEXT-LEN is 0.

CMSG-STATUS is reserved for future use.

CMSG-SQLSTATE is a byte string describing the error. Not all client messages have SQL state values associated with them. If no SQL state value is associated with a message, CMSG-SQLSTATE has the value “ZZZZZ”.

CMSG-SQLSTATE-LEN is the length, in bytes, of the CMSG-SQLSTATE string.


Topics Compiling and Linking Programs 2-9

Compiling and Linking ProgramsCompiling Client-Library Programs

To compile a Client-Library transaction, the copyproc CTPUBLIC must be included in the program, and the copyproc file—SYS$LIB$*UAINCL (SYS$LIB$*UAINCLT for TEST mode installations)—must be defined as an include search file. The following ECL segment, included before the @UCOB processor call accomplishes this task:

@USE COB$PF,SYS$LIB$*UAINCL.

For the TEST mode installation, use the following ECL sequence:

@USE COB$PF,SYS$LIB$*UAINCLT.

Linking Client-Library Programs

To link your UACL program to the UniAccess system, you must do the following:

• Resolve the external references to the UAFG subsystem.

• Eliminate dynamic memory allocation from occurring in program types (e.g., self-initializing or re-entrant transactions) where this activity is illegal.

Resolving External UAFG References

To resolve the external references to the UAFG subsystem, the UAFG library code name must be included on the resolve all references link option before the LCN option. If the test version of the UniAccess system has been installed, the UAFGT library code name must be included on the resolve all references link option before the LCN option. For example:

RESOLVE ALL REFERENCES USING (UAFG), LCN

Eliminating Dynamic Memory

The UAFG subsystem obtains memory from the UCS library to execute some functions. If requests for memory expansion by the UAFG subsystem and the application program exceed the initial size of memory reserved in URTS$TABLES, the system will dynamically

2-10 Compiling and Linking Programs UniAccess for OS 2200 Client-Library Programming Reference


expand the program. To eliminate the required swap from main memory for this expansion, you must manually size the element URTS$TABLES in your Link ECL. This element is a UCS Runtime System data bank that maintains the storage management reserve as well as Runtime System tables, I/O buffers and packets, etc. The following statement defines the number of words to set aside for expansion:

SET SIZE = 037777 FOR URTS$TABLES

The Unisys OS 2200 Universal Compiling System (UCS) COBOL Programming Reference Manual Vol. 2 contains information that will assist you in optimizing the size of URTS$TABLES.

NoteIf you do not prevent memory expansion, URTS$TABLES should be merged as the last bank to prevent it from overlaying data when it attempts to expand. Please see Unisys UCF number 76419370.

SET MERGE_ORDER = LAST FOR URTS$TABLES

Link Example

The following is an example of a LINK runstream for the default version of the UniAccess System:

@LINK,S ,FILE.CLNT1 INCLUDE FILE.CLNT1/OBJ RESOLVE ALL REFERENCES USING (UAFG), LCN SET MERGE_ORDER=ANY FOR ALL BANKS SET LOCALITY=PROGRAM FOR ALL BANKS SET SIZE=0377777 FOR URTS$TABLES PROCESS FOR EXTENDED ZOOM DELETE ALL DEFINITIONS EXCEPT START$

The following is an example of a LINK runstream for the TEST version of the UniAccess System:


Topics Compiling and Linking Programs 2-11

@LINK,S ,FILE.CLNT1 INCLUDE FILE.CLNT1/OBJ RESOLVE ALL REFERENCES USING (UAFGT), LCN SET MERGE_ORDER=ANY FOR ALL BANKS SET LOCALITY=PROGRAM FOR ALL BANKS SET SIZE=0377777 FOR URTS$TABLES PROCESS FOR EXTENDED ZOOM DELETE ALL DEFINITIONS EXCEPT START$

Parameter Alignment Checking

A special UACL stub is included with UniAccess Client-Library that will help in detecting UACL function parameter alignment problems during program development. By including this module, all incorrectly aligned parameters passed to UACL functions will be detected at runtime. If a parameter is incorrectly aligned, the UACL program will abnormally terminate, and the following message will be generated in a program print file:

*ERROR (URTS) 21002: Reference parameter passed to a UC function with the interface pragma applied has incorrect alignment.

To activate parameter checking, the module SYS$LIB$*UAUTIL.UACLSTUBDBG/OBJ should be included before the RESOLVE ALL REFERENCES line. Also the module SYS$LIB$*UAUTIL.CLPRMCHK should be included after the RESOLVE ALL REFERENCES line in the program link.

NoteThe SYS$LIB$*UAUTIL.UACLSTUBDBG/OBJ and SYS$LIB$*UAUTIL. CLPRMCHK modules should only be used during program development as a large amount of overhead is incurred by the runtime system in validating parameter alignment.

2-12 Compiling and Linking Programs UniAccess for OS 2200 Client-Library Programming Reference


The following is an example of a LINK runstream with the parameter alignment detection processing in effect:

@LINK,S ,FILE.CLNT1 INCLUDE FILE.CLNT1/OBJ INCLUDE SYS$LIB$*UAUTIL.UACLSTUBDBG/OBJ RESOLVE ALL REFERENCES USING (UAFG), LCN ADD SYS$LIB$*UAUTIL.CLPRMCHK SET MERGE_ORDER=ANY FOR ALL BANKS SET LOCALITY=PROGRAM FOR ALL BANKS SET SIZE=0377777 FOR URTS$TABLES PROCESS FOR EXTENDED ZOOM DELETE ALL DEFINITIONS EXCEPT START$


Topics DATAFMT Structure 2-13

DATAFMT StructureA DATAFMT structure is used to describe data values and program variables. For example:

• CTBBIND requires a DATAFMT structure describing a destination variable.

• CTBDESCRIBE returns a DATAFMT structure describing a result data item.

• CTBPARAM requires a DATAFMT describing an input parameter.

• CSBCONVERT requires DATAFMT structures describing source and destination data.

Most functions use only a subset of the fields in a DATAFMT. For example, CTBBIND does not use the FMT-NAME, FMT-STATUS, and FMT-UTYPE fields, and CTBDESCRIBE does not use the FMT-FORMAT field. Table 2-4 indicates which DATAFMT fields are used by which functions. For more detailed information, see the description of each function in Chapter 3.

A DATAFMT structure is defined as follows:

01 DATAFMT . 05 FMT-NAME PIC X(132).05 FMT-NAMELEN PIC S9(10) BINARY.05 FMT-TYPE PIC S9(10) BINARY. 05 FMT-FORMAT PIC S9(10) BINARY.05 FMT-MAXLEN PIC S9(10) BINARY. 05 FMT-SCALE PIC S9(10) BINARY.05 FMT-PRECIS PIC S9(10) BINARY.05 FMT-STATUS PIC S9(10) BINARY.05 FMT-COUNT PIC S9(10) BINARY.05 FMT-UTYPE PIC S9(10) BINARY.05 FMT-LOCALE PIC X(68).

where the information in the following table is true.

2-14 DATAFMT Structure UniAccess for OS 2200 Client-Library Programming Reference


Table 2-4: Fields in the DATAFMT Structure

Field name Contents Used by:

FMT-NAME Name of the data item. CTBDESCRIBECTBPARAM

FMT-NAMELEN Length of FMT-NAME. CTBDESCRIBECTBPARAM

FMT-TYPE Datatype of the data. See the specific function to determine which data this refers to.

CSBCONVERTCTBBINDCTBDESCRIBECTBPARAM

FMT-FORMAT Format of data, represented by symbolic values. CTBBIND

FMT-MAXLEN Maximum length of data. CSBCONVERTCTBBINDCTBDESCRIBECTBPARAM

FMT-SCALE Number of digits in the decimal part of a number. Used only when FMT-TYPE is set to CS-DECIMAL, CS-NUMERIC, or CS-PACKEDEC.

CTBBINDCSBCONVERTCTBPARAM

FMT-PRECIS Total number of digits in a number. Used only when FMT-TYPE is set to CS-DECIMAL, CS-NUMERIC, or CS-PACKEDEC.

CTBBINDCSBCONVERT

FMT-STATUS Status values. CTBDESCRIBECTBPARAM

FMT-COUNT Number of rows. CTBBINDCTBDESCRIBE

FMT-UTYPE User-defined datatype of retrieved data. The UDT is assigned by the server.

CTBDESCRIBECTBPARAM

FMT-LOCALE Reserved for future use. CSBCONVERTCTBBINDCTBDESCRIBECTBPARAM



FMT-NAME is the name of the data item. This can be a column, a parameter, or a return status name.

FMT-NAMELEN is the length, in bytes, of FMT-NAME. Assign FMT-NAMELEN a value of 0 if the data item is unnamed.

FMT-TYPE is the datatype of the data. This value is one of the Client-Library datatypes listed under Datatypes on page 2-18.

NoteReturn status values always have a datatype of CS-INT.

FMT-FORMAT is the destination format of fixed-length character or binary data. FMT-FORMAT is one of the following symbolic values.

Table 2-5: Values for DATAFMT’s FMT-FORMAT Field

FMT-MAXLEN can represent various lengths, depending on which function is using the DATAFMT. Lengths are represented in bytes. The following table lists the meaning of FMT-MAXLEN for each function that uses it.

Value Indicates: Notes

CS-FMT-PADBLANK The data should be padded with blanks to the full length of the destination variable.

For fixed-length character data only.

CS-FMT-PADNULL The data should be padded with LOW-VALUES to the full length of the destination variable.

For binary or fixed-length character data.

2-16 DATAFMT Structure UniAccess for OS 2200 Client-Library Programming Reference


Table 2-6: Lengths Referred to by DATAFMT’s FMT-MAXLEN Field

FMT-SCALE is the number of decimal places in the value being converted. FMT-SCALE is only used with CTBBIND and CSBCONVERT when converting to or from decimal datatypes (that is, CS-NUMERIC, CS-DECIMAL, and CS-PACKEDEC). FMT-SCALE is used during a CTBPARAM call for a PACKEDEC datatype.

Legal values for FMT-SCALE are from 0 to 77 for CS-NUMERIC and CS-DECIMAL, and 0 to 18 for CS-PACKEDEC. The default scale is 0.

To indicate that destination data should use the same scale as the source data, FMT-SCALE must be set to CS-SRC-VALUE. FMT-SCALE must be less than or equal to FMT-PRECIS.

FMT-PRECIS is the precision of the value being converted. FMT-PRECIS is used only with CTBBIND and CSBCONVERT when converting to or from packed decimal datatypes (CS-NUMERIC, CS-DECIMAL, and CS-PACKEDEC). Legal values for FMT-PRECIS are from 1 to 77 for CS-NUMERIC and CS-DECIMAL and 18 for CS-PACKEDEC. The default precision is 18. FMT-PRECIS is used during a CTBPARAM call for a CS-PACKEDEC datatype.

To indicate that destination data should use the same precision as the source data, FMT-PRECIS must be set to CS-SRC-VALUE. FMT-PRECIS must be greater than or equal to FMT-SCALE.

Function FMT-MAXLEN is:

CTBBIND The length of the variable to which the data will be bound.

CSBCONVERT The length of the source variable and the length of the destination variable.

CTBDESCRIBE The maximum possible length of the column or parameter being described.

CTBPARAM The maximum length of return parameter data.



FMT-STATUS is one or more of the symbolic values listed in Table 2-7.

Table 2-7: Values for DATAFMT’s FMT-STATUS Field

FMT-COUNT is the number of rows to copy to program variables per CTBFETCH call.

FMT-UTYPE is user-defined datatype (if any) of data returned by the server.

NoteFMT-UTYPE is used only for datatypes defined at the server (for example, SQL Server-defined datatypes or datatypes defined with TDSETUDT in UniAccess Server-Library), not for datatypes defined by UniAccess Client-Library.

FMT-LOCALE is reserved for future use. You must move LOW-VALUES to this field.

Symbolic Value Indicates: Value is legal for:

CS-CANBENULL The column can contain nulls. CTBDESCRIBE

CS-NODATA No data is associated with the result data item.

CTBDESCRIBE

CS-INPUTVALUE The parameter is a non-return RPC parameter (i.e., an input parameter).

CTBPARAM

CS-RETURN The parameter is an RPC return parameter. CTBPARAM

2-18 Datatypes UniAccess for OS 2200 Client-Library Programming Reference


DatatypesUniAccess Client-Library supports a wide range of datatypes. These datatypes are shared with SYBASE Open Client, Open Server, and UniAccess Server-Library. They correspond directly to SQL Server datatypes.

Summary of UniAccess Client-Library Datatypes

Table 2-8 lists and describes the UniAccess Client-Library type constants passed to various Client-Library functions, together with their corresponding Open Client/Server and SQL Server datatypes.

Table 2-8: Summary of UniAccess Client-Library Datatypes

UniAccess Client-Library Type Constant

DescriptionCorresponding Open Client/Server Typedef

CorrespondingSQL Server Datatype

Binary types CS-BINARY-TYPE n-byte binary CS_BINARY binary

CS-LONGBINARY-TYPE(not supported)

n-byte character CS_LONGBINARY (none)

CS-VARBINARY-TYPE variable binary CS_VARBINARY (none)

Bit type CS-BIT-TYPE bit CS_BIT bit

Character types CS-CHAR-TYPE n-byte character CS_CHAR char

CS-LONGCHAR-TYPE(not supported)

n-byte character CS_LONGCHAR (none)

CS-VARCHAR-TYPE variable character CS_VARCHAR (none)

Datetime types CS-DATETIME-TYPE 8-byte datetime CS_DATETIME datetime

CS-DATETIME4-TYPE 4-byte datetime CS_DATETIME4 smalldatetime

Integer types CS-TINYINT-TYPE 1-byte unsigned char

CS_TINYINT tinyint

CS-SMALLINT-TYPE 2-byte signed integer

CS_SMALLINT smallint


Topics Datatypes 2-19

Table 2-9 presents the COBOL WORKING STORAGE format of the Open Client/Server types. (See the Unisys OS 2200 Universal Compiling System (UCS) C Programming Reference Manual Vol 2 for information on the corresponding C datatypes.)

Table 2-9: Summary of UniAccess Client-Library COBOL Definitions

CS-INT-TYPE 4-byte signed integer

CS_INT int

Approximate decimal types

CS-REAL-TYPE 4-byte floating point

CS_REAL real

CS-FLOAT-TYPE 8-byte floating point

CS_FLOAT float

Exact decimal types

CS-PACKEDEC-TYPE OS 2200 packed decimal

(none) (none)

CS-NUMERIC-TYPE exact decimal CS_NUMERIC numeric

CS-DECIMAL-TYPE exact decimal CS_DECIMAL decimal

Money types CS-MONEY4-TYPE 4-byte money CS_MONEY4 smallmoney

CS-MONEY-TYPE 8-byte money CS_MONEY money

Text and image types

CS-TEXT-TYPE(not supported except when binding return colums of type CS-TEXT-TYPE)

text CS_TEXT text

CS-IMAGE-TYPE (not supported)

image CS_IMAGE image

Open Client/Server Typedef COBOL WORKING STORAGE

Binary types CS-BINARY 01 COB-BINARY PIC X(n).

CS-LONGBINARY (not supported)

CS-VARBINARY 01 COB-VARBINARY. 05 LENGTH 05 TEXT

PIC S9(5) BINARY.PIC X(n).

UniAccess Client-Library Type Constant

DescriptionCorresponding Open Client/Server Typedef

CorrespondingSQL Server Datatype



Bit type CS-BIT 01 COB-BIT PIC 1(9) BINARY-1.

Character types CS-CHAR 01 COB-CHAR PIC X(n).

CS-LONGCHAR (not supported)

CS-VARCHAR 01 COB-VARCHAR. 05 LENGTH 05 TEXT

PIC S9(5) BINARY.PIC X(n).

Datetime types CS-DATETIME 01 COB-DATETIME. 05 DATE 05 TIME

PIC S9(10) BINARY.PIC S9(10) BINARY.

CS-DATETIME4 01 COB-DATETIME4. 05 DATE 05 TIME

PIC 9(5) BINARY.PIC 9(5) BINARY.

Integer types CS-TINYINT 01 COB-TINT PIC 1(9) BINARY-1.

CS-SMALLINT 01 COB-SINT PIC S9(5) BINARY.

CS-INT 01 COB-INT PIC S9(10) BINARY.

Approximate decimal types

CS-REAL 01 COB-REAL COMP-1.

CS-FLOAT 01 COB-FLOAT COMP-2.

Exact decimal types CS-PACKEDEC 01 PACKED-DATA PIC S9(18) USAGE PACKED-DECIMAL.

CS-NUMERIC 01 COB-NUMERIC. 05 PRECISION 05 SCALE 05 ARRAY

PIC 1(9) BINARY-1.PIC 1(9) BINARY-1.PIC X(33)

CS-DECIMAL 01 COB-DECIMAL. 05 PRECISION 05 SCALE 05 ARRAY

PIC 1(9) BINARY-1.PIC 1(9) BINARY-1.PIC X(33).

Money types CS-MONEY 01 COB-MONEY. 05 HIGH 05 LOW

PIC S9(10) BINARY.PIC 9(10) BINARY.

CS-MONEY4 01 COB-MONEY4 PIC S9(10) BINARY.




Description of UniAccess Client-Library Datatypes

UniAccess Client-Library datatypes are designed to match the corresponding OS 2200 datatypes. For example, PACKEDEC is the same as a COBOL packed decimal datatype, which is different from the SQL Server decimal type.

Certain SQL Server datatypes (such as MONEY, DATETIME, NUMERIC, and DECIMAL) are usable by a COBOL program only when they are converted to another datatype. However, these datatypes are provided for situations where a COBOL program retrieves data from one SQL Server and immediately uses that data in an outgoing request to another SQL Server.

Binary Datatypes

UniAccess Client-Library supports two binary types, CS-BINARY, and CS-VARBINARY:

• CS-BINARY is a binary type.

• CS-VARBINARY is a variable-length binary type. It corresponds to DB-Library’s DBVARYBIN and Server-Library’s TDSVARYBINARY datatypes, and it includes a length specification (the initial two bytes, referred to in print as ‘LL’) along with the data.

NoteCS-VARBINARY does not correspond to the SQL Server type varbinary. UniAccess Client-Library converts SQL Server varbinary data to CS-VARBINARY.

Text and image types CS-TEXT(not supported except when binding returned columns of type CS-TEXT-TYPE)

01 CS-TEXT-BUFFER PIC X(n). (where N cannot be greater than 65535)

CS-IMAGE (not supported)




Bit Datatype

CS-BIT corresponds to SQL Server bit. CS-BIT columns may be used for true/false or yes/no types of data. They hold either 0 or 1. Integer values other than 0 or 1 are accepted, but are always interpreted as 1. Storage size is 1 byte.

Character Datatypes

UniAccess Client-Library supports two character types, CS-CHAR and CS-VARCHAR:

• CS-CHAR is a fixed-length character type.

• CS-VARCHAR is a variable-length character type. It corresponds to DB-Library’s DBVARYCHAR and Server-Library’s TDSVARYCHAR datatypes, and includes a length specification (the initial two bytes, referred to in print as ‘LL’) along with the data.

• CS-TEXT is valid only when binding and retrieving returned columns of datatype CS-TEXT-TYPE. Note that although a returned column of CS-TEXT-TYPE is of variable length of up to 65535 bytes, the definition of the buffer into which CS-TEXT data is retrieved must be set to the maximum width of the column; for example, if a CS-TEXT column’s maximum width is 28000, then the buffer is defined as:

01 CS-TEXT-BUFFER PIC X(28000).

The determination of the size of the actual returned data of a CS-TEXT column is some agreed protocol between the server transaction and the client program, for instance:

— The client program could fill the CS-TEXT-BUFFER with spaces and find the first non-space character by searching from the buffer’s end.

— The server transaction could include the actual data size of the data in the returned data.



NoteCS-VARCHAR does not correspond to the SQL Server type varchar. UniAccess Client-Library converts SQL Server varchar data to CS-VARCHAR.

Datetime Datatypes

UniAccess Client-Library supports two datetime types, CS-DATETIME and CS-DATETIME4. These datatypes are intended to hold 8-byte and 4-bytes datetime values, respectively.

• CS-DATETIME corresponds to SQL Server datetime. The range of valid CS-DATETIME values is from January 1, 1753 to December 31, 9999, with a precision of 1/300th of a second (3.33 milliseconds).

Client-Library can convert a CS_DATETIME datatype field to a CS_CHAR datatype field. The following is a representative output of that conversion:

• CS-DATETIME4 corresponds to SQL Server smalldatetime. The range of valid CS-DATETIME4 values is from January 1, 1900 to June 6, 2079, with a precision of 1 minute.

Client-Library can convert a CS_DATETIME4 datatype field to a CS_CHAR datatype field. The following is a representative output of that conversion:

A normal datetime value: Mar 31 3009 12:21:22:120PM

The minimum datetime value: Jan 1 1753 12:00:00:000AM

The maximum datetime value: Dec 31 9999 11:59:59:996PM

A normal datetime4 value: Mar 31 2078 1:29PM

The minimum datetime4 value: Jan 1 1900 12:00AM

The maximum datetime4 value: Jun 6 2079 11:59PM



Integer Datatypes

UniAccess Client-Library supports integer types CS-TINYINT, CS-SMALLINT, and CS-INT.

• CS-TINYINT is a 1-byte integer.

• CS-SMALLINT is a 2-byte integer.

• CS-INT is a 4-byte integer.

Approximate Decimal Datatypes

UniAccess Client-Library supports two approximate decimal types, CS-REAL and CS-FLOAT.

• CS-REAL is a 4-byte decimal value.

• CS-FLOAT is an 8-byte decimal value.

Approximate decimal types round the number at the point of truncation.

Exact Decimal Datatypes

UniAccess Client-Library supports three exact decimal types: CS-PACKEDEC, CS-NUMERIC, and CS-DECIMAL.

• CS-PACKEDEC is used to handle OS 2200 packed decimal data. It may contain an exact decimal number of up to 18 digits. CS-PACKEDEC can be converted to the SQL Server MONEY, CHAR, NUMERIC, DECIMAL, or FLOAT datatypes with CSBCONVERT.

The CS-PACKEDEC type may be used by COBOL programs to retrieve and manipulate SQL Server datatypes that are not supported in a native mode by OS 2200. For example, when retrieving a CS-DECIMAL or CS-MONEY field, the COBOL program would bind these fields to a CS-PACKEDEC field in its program.



NoteTruncation errors can result when a COBOL program is retrieving a CS-DECIMAL field into a CS-PACKEDEC field. A CS-DECIMAL field can hold up to 77 digits of precision while CS-PACKEDEC may hold only up to 18 digits.

• CS-NUMERIC represents exact decimal numbers with associated precision and scale. It can be converted to other datatypes such as CS-PACKEDEC.

• CS-DECIMAL is equivalent to CS-NUMERIC.

Money Datatypes

UniAccess Client-Library supports two money datatypes, CS-MONEY and CS-MONEY4. These datatypes are intended to hold 8-byte and 4-byte money values, respectively.

• CS-MONEY corresponds to SQL Server money. The range of valid CS-MONEY values is between +/- $922,337,203,685,477.5807.

Client-Library can convert a CS_MONEY datatype field to a CS_CHAR datatype field. The following is a representative output of that conversion:

• CS-MONEY4 corresponds to SQL Server smallmoney. The range of valid CS-MONEY4 values is between -$214,748.3648 and +$214,748.3647.

Client-Library can convert a CS_MONEY4 datatype field to a CS_CHAR datatype field. The following is a representative output of that conversion:

A normal money value: 1234560.89

The minimum money value: -922337203685477.58

The maximum money value: 922337203685477.58

A normal money4 value: 52111.00

The minimum money4 value: -214748.36

The maximum money4 value: 214748.36

2-26 Error and Message Handling UniAccess for OS 2200 Client-Library Programming Reference


Error and Message HandlingAll UniAccess Client-Library functions return success or failure indications in their RETCODE arguments. An application should be written to check these return codes.

In addition, Client-Library applications must handle three types of error and informational messages:

• Client messages, that is, Client-Library messages, are generated by the functions documented in this book. They range in severity from informational messages to fatal errors. For more information on messages, see Appendix C in this reference manual.

• Server messages are generated by a UniAccess Transaction Server or UniAccess ODBC Server component and returned to a client application. Server messages also range in severity from informational messages to fatal errors. (A complete list of UniAccess Server Program Messages is found in Appendix D of the UniAccess for OS 2200 System Administration Guide.

• Operating System messages are those detected by Client-Library functions and returned to the client application.

A Client-Library application uses the function CTBDIAG to handle messages in line. CTBDIAG returns message information to two structures defined within the application: the CLIENTMSG structure for client messages and the SERVERMSG structure for server messages.

An application calls CTBDIAG to initialize in-line message handling for a connection. CTBDIAG cannot be used at the context level.

NoteWhenever a Client-Library function returns CS-FAIL (0), you should call CTBDIAG to determine what the error is.


Topics Error and Message Handling 2-27

An application can retrieve messages into SQLCA and SQLCODE structures. If the application uses these structures, it must set the property CS-EXTRA-INF to CS-TRUE, using CTBCONPROPS. (See The CS-EXTRA-INF Property below and SQLCA Structure on page 2-52 for more information.)

For additional information on the in-line method of handling function and server messages, see the function description section for CTBDIAG in Chapter 3 and the topics CLIENTMSG Structure on page 2-6 and SERVERMSG Structure on page 2-49.

The CS-EXTRA-INF Property

The CS-EXTRA-INF property is used by an application to determine the number of rows affected by the most recent command. If you want this extra information, you must set this property before calling the function.

An application can determine the number of rows in two ways:

• An application that is retrieving messages into a SQLCA structure must set the property CS-EXTRA-INF to CS-TRUE, using CTBCONPROPS. This is necessary because the SQLCA structure needs to know the number of rows affected, information that functions do not customarily return. If CS-EXTRA-INF is not set, information will be lost.

• An application that is not using SQLCA can also set CS-EXTRA-INF to CS-TRUE. In this case, the extra information is returned as standard Client-Library messages.

For further information on the use of the SQLCA structure in UniAccess Client-Library, turn to SQLCA Structure on page 2-52.

2-28 Microsoft SQL Server Access UniAccess for OS 2200 Client-Library Programming Reference


Microsoft SQL Server AccessUniAccess uses an application-level protocol, Tabular Data Stream (TDS), for all communications between client and server applications. Microsoft SQL Server and Sybase SQL Server both use TDS for communications.

UniAccess Client-Library is a source-code-based implementation of Open Client for OS 2200, based on TDS 5.0. TDS has evolved into two distinct TDS dialects:

• Microsoft SQL Server 6.5, 6.0, and 4.21a all use TDS 4.2. Microsoft SQL Server 7.0 uses TDS 7.0. Microsoft SQL Server 2000 uses TDS 8.0.

• Sybase ASE uses TDS 5.0. (For compatibility of Sybase datatypes, seepage 2-18).

TDS protocol is designed to allow different versions of the protocol to interoperate. Client-Library applications accessing Microsoft SQL Server use TDS 4.2. Interoperability with Microsoft SQL Server is based upon the TDS capabilities supported via the targeted level of Microsoft SQL Server.

Table 2-10: Interoperability Between UniAccess Client-Library and Microsoft SQL Server

MS SQL Server Version

TDS Version Client-Library Interoperability

Microsoft SQL Server 6.5

TDS 4.2 Client-Library transactions can access Microsoft SQL Server fully, utilizing both language requests and RPCs.

MicrosoftSQL Server 7.0

TDS 7.0 Client-Library transactions can access Microsoft SQL Server utilizing both language requests and RPCs.*

MicrosoftSQL Server 2000

TDS 8.0 Client-Library transactions can access Microsoft SQL Server utilizing language requests. Language requests can include the execution of stored procedures using the exec T-SQL command.*

*See the restrictions described in the following section.


Topics Microsoft SQL Server Access 2-29

Restrictions and Limitations

The following restrictions and limitations apply to Client-Library applications accessing Microsoft SQL Server 7.0 and Microsoft SQL Server 2000.

• char, varchar, nchar, nvarchar, binary, and varbinary values longer than 255 bytes are truncated to 255 bytes.

• sql_variant data values are returned as varchar(255) values to UniAccess clients.

• nchar and nvarchar values are converted to char and varchar using the non-Unicode Windows code page of the server, with possible loss of extended characters.

• SQL Server 2000 always reports the instance default collation to UniAccess clients.

• uniqueidentifier datatypes are converted to varbinary(16).

• NULL values in bit columns are returned as 0. Catalog and meta data functions report all bit columns as NOT NULL because NULL was not allowed for bit columns in SQL Server version 6.5 and earlier.

• Client-Library applications cannot access SQL Server 2000 objects that have greater than 30 characters in length or that include characters not represented in the Windows code page on the client computer. The basis for this restriction is that in SQL Server 6.5 and earlier, sysname was defined as varchar(30).

Client-Library applications will not be able to access objects that contain names exceeding 30 characters in length directly, but Client-Library applications can indirectly access them (e.g., selecting every column in a table). Microsoft SQL Server 2000 database objects with names exceeding 30 characters in length will be truncated when viewed via Client-Library applications.

2-30 Microsoft SQL Server Access UniAccess for OS 2200 Client-Library Programming Reference


For example, a Microsoft SQL Server 2000 database with a column named:

Thisisaveryveryveryveryveryveryveryveryveryveryveryveryveryverylongcolumnname

will be viewed by Client-Library applications as having a column name:

Thisisaveryveryveryveryveryver

• bigint data values are returned as float values to UniAccess clients. The following examples query the same Microsoft SQL Server 2000 database. The first query is performed using Query Analyzer, the second query is performed using isql on OS 2200.

Request issued using Query Analyzer:

select C2 from TestDataC2--------------------123456789012345

(1 row(s) affected)

Request issued using isql running on OS 2200:

-1> -select C2 from TestData-2> -go-C2

--------------------------------123456789012345.0--(1 row(s) affected)

• Client-Library applications attempting to execute SELECT statements with a FOR XML clause will receive an error. Attempts to retrieve data with a FOR XML clause will receive an error similar to the following:

-1>select * from TestData for xml auto-2>go


Topics Microsoft SQL Server Access 2-31

-Msg 4004, Level 16, State 1:-Server ’L00207’, Line 1:-Unicode data in a Unicode-only collation or ntext data -cannot be sent to clients using DB-Library (such as -ISQL) or ODBC version 3.7 or earlier.

• ntext values cannot be retrieved. Attempts to retrieve ntext values will receive an error similar to the following:

-1>select homepage from northwind..suppliers-2>go-Msg 4004, Level 16, State 1:-Server ’L00207’, Line1:-Unicode data in a Unicode-only collation or ntext data -cannot be sent to clients using DB-Library (such as -ISQL) or ODBC version 3.7 or earlier.

2-32 Nulls UniAccess for OS 2200 Client-Library Programming Reference


NullsClient-Library allows parameters to have a null value—that is, to contain no information, not even blanks. A null value is usually represented in COBOL by LOW-VALUES.

NULL and Unused Parameters

There are several rules for assigning null values to arguments:

• For context handles, connection handles, and command handles, an application assigns the symbolic value CS-NULL.

• For output arguments:

— If they return a single integer, they will never be null.

— If they are longer than a single integer, a null value will be noted by a separate argument, indicating that the argument referred to should be treated as null.

• For arguments that have a corresponding length argument: assign the value CS-NULL-STRING to the corresponding length argument, if one is present, to indicate that the value of an argument should be treated as null.

• For arguments that have NULL indicators, assign CS-PARAM-NULL to the indicator argument.

For example, CTBBIND has the arguments COPIED and COPIED-NULL. If COPIED is null, assign CS-PARAM-NULL to COPIED-NULL; if COPIED is not null, assign CS-PARAM-NOTNULL to COPIED-NULL.

• For all other variables, assign CS-UNUSED to indicate that the argument should be ignored.


Topics Properties 2-33

PropertiesProperties define aspects of UniAccess Client-Library’s behavior.

Login properties are used when logging into a server. Login properties include CS-USERNAME, CS-PASSWORD, and CS-TDS-VERSION.

A server can change the values of some login properties during the login process. For example, if an application sets CS-TDS-VERSION to CS-TDS-50 and then logs into a server that cannot support this TDS version, the server will overwrite CS-TDS-50 with a version it can support. These properties are called negotiated properties.

Setting and Retrieving Properties

An application calls CTBCONFIG, CTBCONPROPS, and CTBCMDPROPS to set and retrieve properties at the context, connection, and command structure levels, respectively. An application calls CTBCONFIG to set and retrieve most context properties; it calls CSBCONFIG to set and retrieve global context properties.

When a context structure is allocated, its property values default to standard values.

When a connection structure is allocated, it picks up default property values from its parent context. For example, if CS-TEXTLIMIT is set to 16,000 at the context level, then any connection created within this context will have a default text limit value of 16,000. Likewise, when a command structure is allocated, it picks up default property values from its parent connection.

An application can override a default property value by calling CSBCONFIG, CTBCONFIG, CTBCONPROPS, or CTBCMDPROPS to change the value of the property.

Most properties’ values can be either set or retrieved by an application, but some properties are retrieve only.

2-34 Properties UniAccess for OS 2200 Client-Library Programming Reference


Summary of Properties

The following table lists the UniAccess Client-Library properties.

Table 2-11: UniAccess Client-Library for OS 2200 Properties

Property name What it is Possiblevalues

Available through the function:

Notes

CS-APPNAME The application name used when logging into the server.

A character string.

The default is NULL.

CTBCONPROPS Login property.

Takes effect onlyif set before the connection is established.

CS-CHARSETCNV Whether or not character set conversion is taking place.

CS-TRUE or CS-FALSE.

A default is n/a.

CTBCONPROPS Retrieve only, after connection is established.

CS-COMMBLOCK A pointer to a communication sessions block.

A pointer to a communication sessions block (EIB).

n/a not supported

CS-EXTRA-INF Whether or not to return the extra information that is required when processing messages in-line using a SQLCA or SQLCODE.


The default is CS-FALSE.

CSBCONFIG,CTBCONFIG,CTBCONPROPS

CS-HOSTNAME The host machine name.

A character string.



Takes effect only if set before the connection is established.



CS-LOC-PROP A pointer to a CS-LOCALE structure that defines localization information.

A pointer value.

A connection picks up a default CS-LOC-PROP from its parent context.


NOTE: Currently only 1 locale is supported by UACL.

CS-LOGIN-STATUS Whether or not the connection is open.

CS-TRUE or CS-FALSE.A default is n/a.

CTBCONPROPS Retrieve only.

CS-LOGIN- TIMEOUT

The login timeout value.

An integer value.

The default is 60 seconds. A value of CS-NO-LIMIT represents an infinite timeout period.

CTBCONFIG UACL ignores this property.

CS-MAX-CONNECT The maximum number of connections for this context.

An integer value.

The default varies by platform. On machines running UniAccess System, the default is 25.

CTBCONFIG

CS-NETIO Whether network I/O is synchronous or asynchronous.

CS-SYNC-IO or CS-ASYNC-IO.The default is CS-SYNC-IO.

CTBCONFIG,CTBCONPROPS

With UACL,this value will always be CS-SYNC-IO.

CS-NOINTERRUPT Whether or not the application can be interrupted.


The default is CS-FALSE, which means the application can be interrupted.

CTBCONFIG,CTBCONPROPS

n/a for UACL.

This property is included for compatibility with other Open Client libraries.



Notes



CS-PACKETSIZE The TDS packet size. An integer value.

The default varies by platform. On UNIX and OS 2200 platforms, the default is 512 bytes.

CTBCONPROPS Negotiated login property.

Cannot be set to another value under UACL.

CS-PASSWORD The password used to log into the server.

A character string.The default is NULL.



CS-TDS-VERSION The version of the TDS protocol that the connection is using.

A symbolic version level.

CS-TDS-VERSION defaults to the value of CS-VERSION.

CTBCONPROPS Negotiated login property.


CS-TEXTLIMIT The largest text or image value to be returned on this connection.

An integer value.

The default is CS-NO-LIMIT.

n/a not supported

CS-TIMEOUT The timeout value. An integer value. The default is CS-NO-LIMIT.

n/a not supported

CS-TRANSACTION -NAME

A transaction name. A string value.


CTBCONPROPS not supported

CS-USERDATA User-allocated data. User-allocated data. CTBCONPROPSCTBCMDPROPS

Allows an application to associate user data with a particular connection or command structure.



Notes



About the Properties

Application Name

• CS-APPNAME defines the application name that a connection will use when connecting to a server.

Character Set Conversion

• CS-CHARSETCNV describes whether or not the server is converting between the client and server character sets. This property is retrieve-only, after a connection is established.

• A value of CS-TRUE indicates that the server is converting between the client and server character sets; CS-FALSE indicates that no conversion is taking place.

CS-USERNAME The name used to log in to the server.

A character string.




CS-VERSION A symbolic version level representing the version of Open Client in use by this context.

CS-VERSION gets its value from a context’s CTBINIT call.

Possible values: CS-VERSION-100 CS-VERSION-110

CSBCONFIGCTBCONFIG

CS-VERSION-100 is the default value.

CS-VERSION-110 reduces overhead by not assigning the following language files unless they are required: SYS$LIB$*ISO (T) SYS$LIB$*ENGL$ ISO-1 (T)



Notes



Extra Information

• CS-EXTRA-INF determines whether or not UniAccess Client-Library returns the extra information that CTBDIAG requires to fill in SQLCA or SQLCODE structures.

• This extra information includes the number of rows affected by the most recent command.

• If an application is not retrieving messages into a SQLCA or SQLCODE, the extra information is returned as ordinary Client-Library messages.

Host Name

• CS-HOSTNAME is the name of the host machine, used when logging in to a server.

Locale Information

• CS-LOC-PROP defines a pointer to a CS-LOCALE structure, which contains localization information. Localization information includes a language, a character set, datetime, money, and numeric formats, and a collating sequence.

Login Status

• CS-LOGIN-STATUS is CS-TRUE if a connection is open, CS-FALSE if it is not. This property can only be retrieved.

• CTBCONNECT is used to open a connection.

Login Timeout

• CS-LOGIN-TIMEOUT defines the length of time, in seconds, that an application waits for a login response when making a connection attempt. Timeouts are not supported under UniAccess Client-Library.



Maximum Number of Connections

• CS-MAX-CONNECT defines the maximum number of simultaneously open connections that a context can have. The default varies by platform. Negative and zero values are not allowed for CS-MAX-CONNECT.

— For UniAccess Client-Library, CS-MAX-CONNECT has a default value of 25.

— If CTBCONFIG is called to set a value for CS-MAX-CONNECT that is

less than the number of currently open connections, CTBCONFIG generates an error and returns CS-FAIL without altering the value of CS-MAX-CONNECT.

Network I/O

• CS-NETIO determines whether a connection is synchronous or asynchronous.

• Since UniAccess Client-Library does not support asynchronous processing, this value will always be CS-FALSE.

No Interrupt

• CS-NOINTERRUPT is not supported for UniAccess Client-Library. It is included for compatibility with other Open Client libraries.

Packet Size

• CS-PACKETSIZE determines the packet size that UniAccess Client-Library uses when sending Tabular Data Stream (TDS) packets.

• The default packet size is 512. Under UniAccess Client-Library, this value cannot be changed.

Password

• CS-PASSWORD defines the password that a connection uses when logging in to a server.



TDS Version

• CS-TDS-VERSION defines the version of the Tabular Data Stream (TDS) protocol that the connection is using.

• Because CS-TDS-VERSION is a negotiated login property, its value can change during the login process. An application can set CS-TDS-VERSION to request a TDS level before calling CTBCONNECT. When CTBCONNECT creates the connection, if the server cannot provide the requested TDS version, a new (lower) TDS version is negotiated. An application can retrieve the value of CS-TDS-VERSION after a connection is established to determine the actual version of TDS in use.

• The following table lists the symbolic values that CS-TDS-VERSION can have.

Table 2-12: Values for CS-TDS-VERSION

Text and Image Limit

• CS-TEXTLIMIT indicates the length, in bytes, of the longest text or image value that an application wants to receive. UniAccess Client-Library will read but ignore any part of a text or image value that goes over this limit.

• The default value of CS-TEXTLIMIT is CS-NO-LIMIT. This means that the application reads and returns all data sent by the server.

• This value is ignored by UniAccess Client-Library.

VALUE Indicates: Features supported

CS-TDS-40 4.0 TDS Browse mode, text and image handling, remote procedure calls

CS-TDS-42 4.2 TDS Internationalization

CS-TDS-46 4.6 TDS Registered procedures, TDS passthrough, negotiable TDS packet size, multi-byte character sets

CS-TDS-50 5.0 TDS Cursors



Timeout

• CS-TIMEOUT controls the length of time, in seconds, that Client-Library waits for a server response when making a request.


Transaction Name

• CS-TRANSACTION-NAME names an OS 2200 transaction. If the server is a Server-Library application, this is the name of the OS 2200 transaction.

• Calls to a SQL Server do not require a transaction name.

• All Client-Library applications can set CS-TRANSACTION-NAME. If a transaction name is not required, CS-TRANSACTION-NAME is ignored.


User Data

• The CS-USERDATA property defines user-allocated data. This property allows an application to associate user data with a particular connection or command structure. An application allocates a data space from which it can get this data when needed.

• To associate user data with a context structure, an application can call CSBCONFIG.

• A COBOL program can use the Working Storage section to define this data.

User Name

• CS-USERNAME defines the user login name that the connection will use to log into a server.



Version of UniAccess Client-Library

• The CS-VERSION property represents the version of Client-Library behavior that an application has requested using CTBINIT. The value of this property can only be retrieved.

• Connections allocated within a context pick up default CS-TDS-VERSION values from their parent context’s CS-VERSION level.

• Currently, the values for CS-VERSION are CS-VERSION-100 and CS-VERSION-110.


Topics Remote Procedure Calls 2-43

Remote Procedure CallsIn the Sybase client/server architecture, a client application can call a stored procedure on a server in one of two ways:

• by executing a language command (e.g., execute myproc)

• by making a remote procedure call (RPC) to a stored procedure on a SQL Server or a Server-Library transaction running in an OS 2200 host.

RPCs have a particular function that is comparable to the Transact-SQL language request’s execute statement. Both RPCs and execute statements allow the execution of stored procedures on an SQL server. Because Server-Library transactions behave the same as stored procedures on an SQL server, they are executed in the same manner and referred to here as if they were stored procedures.

Comparing RPCs and Execute (language) Statements

Remote procedure calls have a few advantages over execute statements in language commands:

• An RPC can be used to execute a variety of functions, including SQL Server stored procedures and any Server-Library transaction. A Transact-SQL execute statement, however, can be used only to execute a SQL Server stored procedure.

• An RPC command passes the stored procedure’s parameters in their native datatypes, in contrast to the execute statement, which passes parameters as ASCII characters. This difference means that the RPC method is faster and more efficient than the execute method, because it does not require either the application program or the server to convert between native datatypes and their ASCII equivalents.

• Accommodating stored procedure return parameters is simpler and faster if the procedure is invoked with an RPC instead of a language command.

With an RPC command, the return parameter values automatically become available to the application as a parameter result set. (Note, however, that a return parameter must be specified as such when it is originally added to the RPC command stream with CTBPARAM.)

2-44 Remote Procedure Calls UniAccess for OS 2200 Client-Library Programming Reference


With an execute statement, on the other hand, the return parameter values are available only if the language command declares local variables and passes these variables (not constants) for the return parameters. Because the language command contains more than one SQL statement, this technique involves additional parsing each time the language command is executed. Further, the language command must explicitly select the local variables after the RPC is executed. Their values are then returned to the application as a regular row result set.

Servers Can Execute Remote Procedures

A server can execute a stored procedure or transaction residing on another server. This might occur when a stored procedure being executed on one SQL Server contains an execute statement for a stored procedure on another SQL Server. The execute command causes the first server to log into the second server and execute the remote procedure. This process happens without any intervention from the application, although the application can specify the remote password that the first server uses to login to the second.

Remote Procedure Call Functions

The following functions are related to remote procedure calls:

• CTBREMOTEPWD sets and clears the passwords that are used when logging into a remote server. (This feature is not available for OS 2200 to OS 2200 calls.)

• CTBCOMMAND initiates an RPC.

• CTBPARAM defines parameters for an RPC.

• CTBSEND sends an RPC.

• CTBRESULTS, CTBBIND, and CTBFETCH are used to process remote procedure results.


Topics Remote Procedure Calls 2-45

Remote Procedure Call Results

In addition to results generated by the SQL statements they contain, SQL Server stored procedures and Server-Library transactions that are executed with an RPC:

• Can generate a return parameter result set

• Can generate a row result set

• Always generate a return status result set.

All types of results can be processed using CTBRESULTS, CTBBIND, and CTBFETCH.

Return Parameters

SQL Server stored procedures and Server-Library transactions can return values for specified return parameters. Changes made to the value of a return parameter inside the stored procedure or transaction are then available to the program that called the procedure or transaction. This is analogous to the pass by reference facility available in some programming languages. In order for a parameter to function as a return parameter, it must be declared as such within the stored procedure. The execute statement or RPC command that invokes the stored procedure must also indicate that the parameter is a return parameter. Client-Library applications use the CTBPARAM function to indicate which parameters are return parameters.

Processing Return Parameters

As mentioned in the preceding section, Comparing RPCs and Execute (language) Statements, return parameter values are available to an application as a parameter result set only if the application invoked the stored procedure using an RPC.

CTBRESULTS returns CS-PARAM-RESULT if a parameter result set is available to be processed. Because stored procedure parameters are returned to an application as a single row, one call to CTBFETCH will copy all of a procedure’s return parameters into the program variables designated with CTBBIND. However, an application should always call CTBFETCH in a loop until it returns CS-END-DATA.

2-46 Remote Procedure Calls UniAccess for OS 2200 Client-Library Programming Reference


When executing a stored procedure, the server returns any parameter values immediately after returning all row results. Therefore, an application can fetch return parameters only after processing the stored procedure’s row results. A stored procedure can generate several sets of row results—one for each select it contains. An application must call CTBRESULTS and CTBFETCH as many times as necessary to process these row results before calling CTBFETCH to fetch the stored procedure’s return parameters.

Return Status

SQL Server, SYBASE Open Server, UniAccess Transaction Server, and UniAccess ODBC Server applications can all return a status number.

All stored procedures that run on a SQL Server version 4.0 or greater return a status. Stored procedures usually return 0 to indicate normal completion. For a list of SQL Server default return status values, see return in your SQL Server Commands Reference manual. UniAccess Server-Library status values are documented under TDSNDDON and TDSTATUS in the UniAccess for OS 2200 Server-Library Programming Reference.

Because return status values are a feature of stored procedures, only an RPC or a language request containing an execute statement can generate a return status.

When executing a stored procedure, a SQL Server returns the status immediately after returning all other results. Therefore, an application can fetch a return status only after processing the stored procedure’s row and parameter results (if any).

Open Server applications return the status after any row results, but either before or after return parameters.

Processing a Return Status

CTBRESULTS returns CS-STATUS-RESULT if a return status result set is available to be processed. Because a return status result set contains only a single value, one call to CTBFETCH will copy the status into the program variable designated with CTBBIND. However, an application should always call CTBFETCH in a loop until it returns CS-END-DATA.


Topics Results 2-47

ResultsWhen a client request executes a server procedure or transaction, it can generate various types of results that are returned to the client application:

They are:

• Regular row results

• Return parameter results

• Return status results.

Results are returned to an application in the form of result sets. A result set contains only a single type of result data. Regular row result sets can contain multiple rows of data, but other types of result sets contain at most a single row of data.

An application processes results by calling CTBRESULTS. The type of result available is indicated in the RESULT-TYP argument. The application calls CTBRESULTS once for each result set. CTBRESULTS returns CS-CMD-DONE in RESULT-TYP to indicate that a result set has been completely processed. An application should continue to call CTBRESULTS to process the remaining result sets until it returns CS-END-RESULTS.

Some requests, for example a language request containing a Transact-SQL update statement, do not generate results. CTBRESULTS returns CS-CMD-SUCCEED to indicate the success of a request that does not return results.

Types of Results

Regular Row Results

A regular row result set contains one or more rows of tabular data.

Return Parameter Results

A return parameter result set contains a single row of return parameter data. Return parameters are values returned by stored procedures and transactions in the arguments of the called function. For information on return parameters, see Remote Procedure Calls on page 2-43.

2-48 Results UniAccess for OS 2200 Client-Library Programming Reference


Return Status Results

A status result set consists of a single row that contains a single value, a return status. For more information on a stored procedure return status, see Remote Procedure Calls on page 2-43.


Topics SERVERMSG Structure 2-49

SERVERMSG StructureA server message structure (SERVERMSG structure) contains information about an error or informational message returned by the server. This structure is defined within the application. CTBDIAG returns a message string and information about the message into this structure.

This structure is used for all server messages received. It contains the details of any message returned by the server application, including messages returned by the UniAccess Transaction Server and the UniAccess ODBC Servers, by remote transactions, and by the SQL Server.

A SERVERMSG structure is defined as follows:

01 SERVER-MSG . 05 SMSG-MSGNO PIC S9(10) BINARY.05 SMSG-STATE PIC S9(10) BINARY.05 SMSG-SEV PIC S9(10) BINARY.05 SMSG-TEXT PIC X(1024). 05 SMSG-TEXT-LEN PIC S9(10) BINARY.05 SMSG-SVRNAME PIC X(132). 05 SMSG-SVRNAME-LEN PIC S9(10) BINARY.05 SMSG-PROC PIC X(132). 05 SMSG-PROC-LEN PIC S9(10) BINARY.05 SMSG-LINE PIC S9(10) BINARY.05 SMSG-STATUS PIC S9(10) BINARY.05 SMSG-SQLSTATE PIC X(8). 05 SMSG-SQLSTATE-LEN PIC S9(10) BINARY.

where:

SMSG-MSGNO is the server message number. This field corresponds to the MESSAGE-NUMBER argument of the Server-Library function TDSNDMSG.

SMSG-STATE is the message state. This field corresponds to the ERROR-STATE argument of the Server-Library function TDSNDMSG.

2-50 SERVERMSG Structure UniAccess for OS 2200 Client-Library Programming Reference


SMSG-SEVERITY is a symbolic value representing the severity of the message. Severity values are provided in the CTPUBLIC copyproc. This field corresponds to the SEVERITY argument of the Server-Library function TDSNDMSG.

The following table lists the legal values for SMSG-SEVERITY.

Table 2-13: Values for SERVERMSG’s SMSG-SEVERITY Field

SMSG-TEXT is the text of the message string. This field corresponds to the MESSAGE-TEXT argument of the Server-Library function TDSNDMSG.

SMSG-TEXT-LEN is the length, in bytes, of SMSG-TEXT. If there is no message text, the value of SMSG-TEXT-LEN is 0. This field corresponds to the MESSAGE-LENGTH argument of the Server-Library function TDSNDMSG.

SMSG-SVRNAME the name of the server that generated the message. SMSG-SVRNAME-LEN is the length, in bytes, of SMSG-SVRNAME.

Value of SEVERITY Indicates:



CS-SV-RETRY-FAIL An operation has failed, but the operation can be retried.







Topics SERVERMSG Structure 2-51

SMSG-PROC is the name of the remote procedure or transaction that returned the message—the name of the SQL Server stored procedure or the transaction ID of the Server-Library transaction. This field corresponds to the TRANSACTION-ID argument of the Server-Library function TDSNDMSG.

SMSG-PROC-LEN is the length, in bytes, of SMSG-PROC. This field corresponds to the TRANSACTION-ID-LENGTH argument of the Server-Library function TDSNDMSG.

SMSG-LINE is the line number in the called procedure or transaction where the error occurred. It may also be used for miscellaneous information. This field corresponds to the LINE-ID argument of the Server-Library function TDSNDMSG.

SMSG-STATUS is reserved for future use.

SMSG-SQLSTATE is a byte string describing the error. Not all server messages have SQL state values associated with them. If no SQL state value is associated with a message, SMSG-SQLSTATE has the value “ZZZZZ”.

SMSG-SQLSTATE-LEN is the length, in bytes, of the SMSG-SQLSTATE string.

2-52 SQLCA Structure UniAccess for OS 2200 Client-Library Programming Reference


SQLCA StructureA SQLCA structure can be used in conjunction with CTBDIAG to retrieve Client-Library and server error and informational messages.

A SQLCA structure is defined as follows:

01 SQLCQ-MSG.05 SQLCAID PIC X(8).05 SQLCABC PIC S9(10) BINARY VALUE +0.05 SQLCODE PIC S9(10) BINARY VALUE +0.05 SQLERRM.

49 SQLERRML PIC S9(10) BINARY VALUE +0.49 SQLERRMC PIC X(256).

05 SQLERRP PIC X(8).05 SQLERRD OCCURS 6 TIMES PIC S(10).05 SQLWARN.

49 SQLWARN0 PIC X(1).49 SQLWARN1 PIC X(1).49 SQLWARN2 PIC X(1).49 SQLWARN3 PIC X(1).49 SQLWARN4 PIC X(1).49 SQLWARN5 PIC X(1).49 SQLWARN6 PIC X(1).49 SQLWARN7 PIC X(1).

05 SQLTEXT PIC X(8).

where:

SQLCAID is SQLCA. (This value is automatically provided.)

SQLCABC is ignored.

SQLCODE is the server or Client-Library message number. For information on how Client-Library maps message numbers to SQLCODE, see SQLCODE Structure on page 2-54. Appendix C in this manual explains client program messages returned to the Client-Library application. Appendix D in the UniAccess for OS 2200 System Administration Guide lists server program messages returned by UniAccess System servers.


Topics SQLCA Structure 2-53

SQLERRML is the length of the actual message text (not the length of the text placed in SQLERRMC).

SQLERRMC is the null-terminated text of the message. If the message is too long for the array, Client-Library truncates it before appending the null terminator.

SQLERRP is the first eight characters of the stored procedure (if any) being executed at the time of the error.

SQLERRD is the number of rows successfully inserted, updated, or deleted before the error occurred.

SQLWARN is an array of warnings:

• If SQLWARN0 is blank, then all other SQLWARN variables are blank. If SQLWARN0 is not blank, then at least one other SQLWARN variable is set to ‘W.’

• If SQLWARN1 is ‘W,’ then Client-Library truncated at least one column’s value when storing it into a host variable.

• If SQLWARN2 is ‘W,’ then at least one null value was eliminated from the argument set of a function.

• If SQLWARN3 is ‘W,’ then the number of host variables specified in the into clause of a select statement is not equal to the number of result columns.

• If SQLWARN4 is ‘W,’ then a dynamic SQL update or delete statement did not include a where clause.

• If SQLWARN5 is ‘W,’ then a server conversion or truncation error has occurred.

SQLEXT is ignored.

2-54 SQLCODE Structure UniAccess for OS 2200 Client-Library Programming Reference


SQLCODE StructureA SQLCODE structure can be used in conjunction with CTBDIAG to retrieve error and informational messages from Client-Library and server applications. A SQLCODE structure can be located anywhere and mapped to SQLCA.

A SQLCODE structure is defined as a 4-byte integer.

Client-Library always sets SQLCODE and the SQLCODE field of the SQLCA structure identically. (See SQLCA Structure on page 2-52.)

Mapping Server Messages to SQLCODE

A server message number is mapped to a SQLCODE of 0 if it has a severity of 0.

Other server messages may be mapped to a SQLCODE of 0 as well.

Server message numbers are negated before being placed into SQLCODE. Thus, a negative SQLCODE number indicates than an error has occurred.

For a list of program messages returned by UniAccess System serves see Appendix D in the UniAccess for OS 2200 System Administration Guide.

Mapping Client-Library Messages to SQLCODE

The Client-Library message “No rows affected” is mapped to a SQLCODE of 100.

Client-Library messages with CS-SV-INFORM severities are mapped to a SQLCODE of 0.

Other Client-Library messages may be mapped to a SQLCODE of 0 as well.

Client-Library message numbers are negated before being placed into SQLCODE. Thus, a negative SQLCODE number indicates that an error has occurred.

For an explanation of Client-Library messages, see Appendix C.


Topics Structures 2-55

StructuresUniAccess Client-Library structures fall into two categories: hidden structures, whose internal formats are not documented, and exposed structures, whose internal formats are documented.

Hidden Structures

Hidden structures in UniAccess Client-Library are called handles. An application needs to call Client-Library functions to allocate, use, and de-allocate these handles, but does not need to access them directly.

Client-Library uses handles at three levels. Each handle defines and manages a particular environment (for an illustration of this environment, see Figure 1-5 on page 1-16). Each type of handle can have certain properties, listed below.

NoteMost Client-Library functions include a handle argument. An application must allocate these handles before using them as arguments.

Types of Handles

The following handles are used with Client-Library:

• Context handle. A context handle defines a particular application, context, or operating environment. The context handle is defined in the program’s CSBCTXALLOC call.

NoteAn application can have only one context.

2-56 Structures UniAccess for OS 2200 Client-Library Programming Reference


The context handle can have the properties listed in Table 2-13.

Table 2-14: Context Properties

• Connection handle. This is the handle for an individual client/server connection. The connection handle is defined in the program’s CTBCONALLOC call. If parallel sessions are used, there must be one connection handle for each session. An application can have up to 25 connections.

The UniAccess Configuration File defines which UACS will be used and where the server is located. For details about the configuration statements that define these attributes, see Chapter 16 of the UniAccess for OS 2200 System Administration Guide.

Property Set by:

CS-EXTRA-INF CSBCONFIG

CS-LOGIN-TIMEOUT CTBCONFIG

CS-MAX-CONNECT CTBCONFIG

CS-NETIO CTBCONFIG

CS-NOINTERRUPT CTBCONFIG

CS-TEXTLIMIT CTBCONFIG (not supported)

CS-TIMEOUT CTBCONFIG (not supported)

CS-VERSION CSBCONFIG



A connection handle can have the properties shown in Table 2-15.

Table 2-15: Connection Properties

• Command handle. A command handle defines a command space that is used to send commands to a server over a connection and process the results. A command handle is defined in the program’s CTBCMDALLOC call. Each command handle is associated with a particular connection. There can be any number of command handles associated with a connection.

Property Set by:

CS-APPNAME CTBCONPROPS

CS-CHARSETCNV CTBCONPROPS

CS-EXTRA-INF CTBCONPROPS

CS-HOSTNAME CTBCONPROPS

CS-LOC-PROP CTBCONPROPS

CS-LOGIN-STATUS CTBCONPROPS

CS-NETIO CTBCONPROPS

CS-NOINTERRUPT CTBCONPROPS

CS-PACKETSIZE CTBCONPROPS

CS-PASSWORD CTBCONPROPS

CS-TDS-VERSION CTBCONPROPS

CS-TEXTLIMIT CTBCONPROPS

CS-TRANSACTION-NAME CTBCONPROPS

CS-USERDATA CTBCONPROPS

2-58 Structures UniAccess for OS 2200 Client-Library Programming Reference


A command handle can have the properties shown in Table 2-16.

Table 2-16: Command Properties

Functions that Affect Handles

The following table lists the functions that allocate, use, and de-allocate handles.

Table 2-17: Functions that Manipulate Hidden Structures

Property Set by:

CS-USERDATA CTBCONPROPS

Structure Functions

CONTEXT CSBCTXALLOC, CTBCONFIG, CSBCONFIG, CSBCTXDROP

CONNECTION CTBCONALLOC, CTBCONPROPS, CTBCONDROP

COMMAND CTBCMDALLOC, CTBCMDPROPS, CTBCMDDROP



Exposed Structures

A UniAccess Client-Library exposed structure is a work area where a particular type of data is stored. Exposed structures provide a way for UniAccess Client-Library to exchange information with a Client-Library application.

Typically, applications set fields in an exposed structure before passing the structure as a parameter to a Client-Library function; they retrieve the values of fields in an exposed structure after calling a Client-Library function.

UniAccess Client-Library functions use the following exposed structures:

• CLIENTMSG, the Client-Library message structure

• DATAFMT, the data format structure

• SERVERMSG, the server message structure

• SQLCA, the SQL Communications Area structure

• SQLCODE, the SQL Code structure.

Each of these structures is described in detail on its own topics page.

2-60 UCS C Interface UniAccess for OS 2200 Client-Library Programming Reference


UCS C InterfaceThe UniAccess for OS 2200 Client-Library C Kit provides a UCS C language interface to the UniAccess Client-Library. Appendix E in this manual describes the Client-Library C Kit and includes a description of the C header files and their use and the definition of each Client-Library C function. Table 2-18 below lists the C equivalent of each Client-Library COBOL function.

Table 2-18: UCS C Equivalents for Client-Library Functions

Client-Library Function

C Call Function Description

CTBBIND ct_bind Binds a returned column or parameter to a program variable.

none ct_callback Installs or retrieves a Client-Library callback routine.

CTBCANCEL ct_cancel Cancels a request or the results of a request.

CTBCLOSE ct_close Closes a server connection.

CTBCMDALLOC ct_cmd_alloc Allocates a command handle.

CTBCMDDROP ct_cmd_drop De-allocates a command handle.

CTBCMDPROPS ct_cmd_props Sets, retrieves, or clears command structure properties.

CTBCOMMAND ct_command Initiates a language request or an RPC.

none ct_compute_info Returns compute result information.

CTBCONALLOC ct_con_alloc Allocates a connection handle.

CTBCONDROP ct_con_drop De-allocates a connection handle.

CTBCONFIG ct_config Sets or retrieves context properties.

CTBCONNECT ct_connect Connects to a server.

CTBCONPROPS ct_con_props Sets or retrieves connection handle properties.

CTBDESCRIBE ct_describe Returns a description of result data.


Topics UCS C Interface 2-61

CTBDIAG ct_diag Manages in-line error handling.

CTBEXIT ct_exit Exits the programming interface.

CTBFETCH ct_fetch Fetches result data.

CTBGETFORMAT ct_get_format Returns the user-defined format for a result column.

CTBINIT ct_init Initializes the programming interface.

CTBPARAM ct_param Defines a command parameter.

CTBREMOTEPWD ct_remote_pwd Defines or clears passwords to be used for server-to-server connections.

CTBRESINFO ct_res_info Returns result set information.

CTBRESULTS ct_results Sets up result data to be processed.

CTBSEND ct_send Sends a request to the server.

CSBCONFIG cs_config Sets or retrieves global context properties.

CSBCONVERT cs_convert Converts a data value from one datatype to another.

CSBCTXALLOC cs_ctx_alloc Allocates a context structure.

CSBCTXDROP cs_cxt_drop De-allocates a context structure.

none cs_will_convert Indicates whether or not a specific datatype conversion is available in Client-Library.

Client-Library Function

C Call Function Description

2-62 UniAccess Communication Server UniAccess for OS 2200 Client-Library Programming Reference


UniAccess Communication Server (UACS) All requests directed to server applications are sent to UACS, a component of the UniAccess System. These requests include both those to Server-Library transactions on an OS 2200 system and those to other servers in a LAN-based environment. UACS, then, is the path through which the client communicates with any server.

The work of UACS is transparent to the client application. UACS logs in to the target server, passing along login information, does the necessary conversions, and forwards the request. When results are ready, it passes them through from the server to the client, again performing any necessary conversions.

At run time, UniAccess Client-Library retrieves user and server information that was previously defined in the UniAccess Configuration File. The configuration file contains a list of userids and remote server connections and the associated information required to process the client request. In addition, it contains message information and the set of system configuration statements that define the environment in which the UniAccess System operates.

Client Application Programmer’s Tasks

To prepare the client application to communicate with UACS, the application programmer must:

• Specify a userid with the CS-USERNAME property, available through the CTBCONPROPS function

• Specify the name of the server in the SERVERNAME argument of the CTBCONNECT function.

System Administrator’s Tasks

To ensure that the client application will process correctly, the system administrator must do the following tasks before the client application calls UACS:

• Configure the particular UACS to which the client wishes to connect

• Define the user record with its associated information in the UniAccess Configuration File


Topics UniAccess Communication Server 2-63

• Define the target server with its associated information in the UniAccess Configuration File

• Boot the target UACS and ensure that it is running properly.

These tasks are explained in Part II, Installation and Initial Configuration Procedures, in the UniAccess for OS 2200 System Administration Guide. The client programmer is not concerned with these details.

2-64 Word Alignment Restrictions UniAccess for OS 2200 Client-Library Programming Reference


Word Alignment RestrictionsDue to the OS 2200 method of passing arguments between programming languages, all arguments passed to Client-Library functions must be aligned on a boundary that reflects the machine-level storage of the datatype. Table 2-19 describes the alignment requirements for each of the UACL datatypes and the underlying COBOL datatypes that impose alignment restrictions. (See Datatypes on page 2-18 for a complete description of the COBOL datatypes.)

Table 2-19: Alignment Requirements for UACL and COBOL datatypes

Table 2-20 describes the alignment requirements for all COBOL datatypes that can be passed to UACL functions.

UACL Datatype COBOL Datatype Restrictions

CS-BINARY X(n) quarter-word alignment

CS-BIT 1(9) BINARY-1 quarter-word alignment

CS-CHAR X(n) quarter-word alignment

CS-DATETIME S9(10) BINARY word alignment

CS-DATETIME4 9(5) BINARY half-word alignment

CS-DECIMAL 1(9) BINARY-1 quarter-word alignment

CS-FLOAT COMP-2 word alignment

CS-INT S9(10) BINARY word alignment

CS-MONEY S9(10) BINARY word alignment

CS-MONEY4 S9(10) BINARY word alignment

CS-NUMERIC 1(9) BINARY-1 quarter-word alignment

CS-PACKEDEC PIC S9(18) PACKED-DECIMAL word alignment

CS-REAL COMP-1 word alignment

CS-SMALLINT S9(5) BINARY half-word alignment

CS-TINYINT 1(9) BINARY-1 quarter-word alignment

CS-VARBINARY S9(5) BINARY half-word alignment

CS-VARCHAR S9(5) BINARY half-word alignment


Topics Word Alignment Restrictions 2-65

Table 2-20: Alignment Requirements for COBOL Datatypes

The following WORKING STORAGE code example demonstrates an example of the correct alignment of working storage fields.

01 EMPLOYEE05 EMPLOYEE-ID PIC 9(5) BINARY.05 EMPLOYEE-JC PIC 9(5) BINARY.05 EMPLOYEE-SAL PIC 9(10) BINARY.05 EMPLOYEE-FNAME PIC X(30).05 EMPLOYEE-LNAME PIC X(30).

The fields EMPLOYEE-ID and EMPLOYEE-JC are aligned on half-word boundaries. EMPLOYEE-SAL is aligned on a word boundary. EMPLOYEE-FNAME and EMPLOYEE-LNAME have quarter-word alignment restrictions.

NoteTo detect incorrectly aligned parameters the debug version of the UACL should be linked with your application during development. See Compiling and Linking Programs on page 2-9 for details on how to use the debug version.

Restrictions COBOL Datatype

quarter-word alignment X(n)

1(9) BINARY-1

half-word alignment 9(5) BINARY

word alignment 9(10) BINARY

COMP-1

COMP-2

S9(18) PACKED-DECIMAL


3 Functions

3 Function Descriptions

This chapter describes each Client-Library function in detail. Each function description contains sections on the function’s purpose, syntax, return codes, and related functions, as well as explanatory comments and examples.

The Client-Library functions described herein are COBOL functions. However, much of the information applies to the UCS C functions as well. See Appendix E, Client-Library C Kit, for information of the C language headers, the syntax and description of each function, and additional functions that are not currently available in COBOL.

List of FunctionsTable 3-1 lists the UniAccess Client-Library functions supported in the UniAccess System for OS 2200.

Table 3-1: List of Functions

Function Description Page

CTBBIND Binds a returned column or parameter to a program variable. 3-3

CTBCANCEL Cancels a request or the results of a request. 3-15

CTBCLOSE Closes a server connection. 3-20

CTBCMDALLOC Allocates a command handle. 3-25

CTBCMDDROP De-allocates a command handle. 3-28

CTBCMDPROPS Sets, retrieves, or clears command structure properties. 3-30



CTBCOMMAND Initiates a language request or remote procedure call. 3-35

CTBCONALLOC Allocates a connection handle. 3-41

CTBCONDROP De-allocates a connection handle. 3-45

CTBCONFIG Sets or retrieves context properties. 3-49

CTBCONNECT Connects to a server. 3-54

CTBCONPROPS Sets or retrieves connection handle properties. 3-58

CTBDESCRIBE Returns a description of result data. 3-64

CTBDIAG Manages in-line error handling. 3-70

CTBEXIT Exits the programming interface. 3-83

CTBFETCH Fetches result data. 3-88

CTBGETFORMAT Returns the user-defined format for a result column. 3-94

CTBINIT Initializes the programming interface. 3-96

CTBPARAM Defines a command parameter. 3-99

CTBREMOTEPWD Defines or clears passwords to be used for server-to-server connections.

3-109

CTBRESINFO Returns result set information. 3-115

CTBRESULTS Sets up result data to be processed. 3-122

CTBSEND Sends a request to the server. 3-130

CSBCONFIG Sets or retrieves global context properties. 3-134

CSBCONVERT Converts a data value from one data type to another. 3-142

CSBCTXALLOC Allocates a context structure. 3-151

CSBCTXDROP De-allocates a context structure. 3-155



Function Descriptions CTBIND 3-3

CTBBIND

Purpose

Associate a returned column, parameter, or status with a program variable.

Syntax

COPY CTPUBLIC.01 COMMAND COMP-2.01 RETCODE PIC S9(10) BINARY.01 ITEM-NUM PIC S9(10) BINARY.01 DATAFMT

05 FMT-NAME PIC X(132).05 FMT-NAMELEN PIC S9(10) BINARY.05 FMT-TYPE PIC S9(10) BINARY.05 FMT-FORMAT PIC S9(10) BINARY.05 FMT-MAXLEN PIC S9(10) BINARY.05 FMT-SCALE PIC S9(10) BINARY.05 FMT-PRECIS PIC S9(10) BINARY.05 FMT-STATUS PIC S9(10) BINARY.05 FMT-COUNT PIC S9(10) BINARY.05 FMT-UTYPE PIC S9(10) BINARY.05 FMT-LOCALE PIC X(68).

01 BUFFER type.01 COPIED PIC S9(10) BINARY.01 COPIED-NULL PIC S9(10) BINARY.01 INDICATOR PIC S9(5) BINARY.01 INDICATOR-NULL PIC S9(10) BINARY.

CALL 'CTBBIND' USING COMMAND, RETCODE, ITEM-NUM, DATAFMT, BUFFER, COPIED, COPIED-NULL, INDICATOR, INDICATOR-NULL.

Arguments

COMMAND — (I) The command handle for this client/server operation. This handle is defined in the CTBCMDALLOC call for this connection.

RETCODE — (O) The variable to which the result of function execution is returned. Its value is one of the codes listed under Returns below.

3-4 CTBIND UniAccess for OS 2200 Client-Library Programming Reference


ITEM-NUM — (I) The number of the result column, return parameter, or return status value that is to be bound.

When a result column is to be bound, ITEM-NUM is the column’s ordinal number. For example, the first column in a SQL select statement’s select list is column number 1, the second is column number 2, and so forth.

When return parameter is to be bound, ITEM-NUM is the ordinal rank of the return parameter. The first parameter returned by a procedure or parameter is number 1. SQL Server stored procedure return parameters are returned in the order originally specified in the stored procedure’s create procedure statement. This is not necessarily the same order as specified in the RPC that invoked the stored procedure or transaction.

In determining what number to assign to ITEM-NUM, do not count non-return parameters. For example, if the second parameter in a stored procedure is the only return parameter, its ITEM-NUM will be 1. When a stored procedure return status is to be bound, ITEM-NUM must be 1, as there can be only a single status in a return status result set.

When all bindings are to be cleared, ITEM-NUM must be the value CS-UNUSED.

DATAFMT — (I) A structure that contains a description of the destination variable(s). This structure is also used by CTBDESCRIBE, CTBPARAM and CSBCONVERT and is explained in the Topics section, under DATAFMT Structure on page 2-13.

The following chart lists the fields in the DATAFMT structure, indicates if they are used by CTBBIND, and contains general information about each field. CTBBIND ignores DATAFMT fields that it does not use.

WarningYou must initialize the entire DATAFMT structure to zeroes or low values. Failure to do so causes addressing exceptions.



Table 3-2: Fields in the DATAFMT Structure for CTBBIND

Field name When is the field used? Field’s value represents:

FMT-NAME Not used. n/a.

FMT-NAMELEN Not used. n/a.

FMT-TYPE When binding all types of results. The datatype of the destination variable (BUFFER).

All datatypes listed under Datatypes on page 2-18 are valid.

CTBBIND supports a wide range of type conversions, so FMT-TYPE can be different from the type returned by the server. For instance, by specifying a float destination type, a money result type can be bound to a float-type program variable. The appropriate data conversion happens automatically.

NOTE: A return status always has a datatype of CS-INT.

FMT-FORMAT When binding results to fixed-length character or binary destination variables; otherwise CS-FMT-UNUSED.

The destination format of character or binary data.

For fixed-length character-type destinations only: CS-FMT-PADBLANK pads to the full length of the variable with spaces (ASCII) or blanks (EBCDIC).

For fixed-length character or binary type destination variables: CS-FMT-PADNULL pads to the full length of the variable with LOW-VALUE.



FMT-MAXLEN When binding all types of results, except integer and float.

FMT-MAXLEN is ignored when binding to fixed-length types.

The length of the destination variable, in bytes. If BUFFER has more than one element, FMT-MAXLEN is the length of one element.

When character or binary destinations are to be bound, FMT-MAXLEN must describe the total length of the destination variable, including any space required for special terminating bytes, with this exception: when binding to a VARYCHAR-type destination, FMT-MAXLEN does not include the length of the ‘LL’ length specification.

To clear bind values for a column, assign FMT-MAXLEN a value of 0.

If FMT-MAXLEN indicates that the destination variable is not large enough to hold a result data item, then at fetch time CTBFETCH will discard the result item that is too large, fetch any remaining items in the row, and return CS-ROW-FAIL.

FMT-SCALE Only when converting column results or return parameters to or from CS-NUMERIC, CS-DECIMAL, and CS-PACKEDEC datatypes.

The number of digits to the right of the decimal point.

If the source value is the same datatype as the destination value, then FMT-SCALE can be set to CS-SRC-VALUE to indicate that the destination should pick up its value for FMT-SCALE from the source data.

FMT-SCALE must be less than or equal to FMT-PRECIS. For CS-PACKEDEC, FMT-SCALE cannot be greater than 18. For CS-NUMERIC and CS-DECIMAL, FMT-SCALE cannot be greater than 77. The default scale is 0.




FMT-PRECIS Only when converting column results or return parameters CS-NUMERIC, CS-DECIMAL, and CS-PACKEDEC datatypes.

The total number of decimal digits in the destination variable. This is the n in PIC S9(n).

If the source data is the same type as the destination, then FMT-PRECIS can be set to CS-SRC-VALUE to indicate that the destination should pick up its value for FMT-PRECIS from the source data.

If the precision of the value fetched exceeds the precision of the destination variable, CTBFETCH will return a warning message.

FMT-PRECIS must be greater than or equal to FMT-SCALE. For CS-PACKEDEC, FMT-PRECIS must be 18. For CS-NUMERIC and CS-DECIMAL, FMT-PRECIS cannot be less than 1 or greater than 77. The default precision is 18.

FMT-STATUS Not used. n/a.

FMT-COUNT When binding all types of results. The number of result rows to be copied to program variables per CTBFETCH call. If FMT-COUNT is larger than the number of available rows, only the available rows are copied.

FMT-COUNT must have the same value for all columns in a result set.

If FMT-COUNT is 0 or 1, 1 row will be fetched; if FMT-COUNT is greater than 1, it represents the number of rows that will be fetched. In this case, BUFFER must be an array.

FMT-UTYPE Not used. n/a.

FMT-LOCALE Not used. Reserved for future use.




BUFFER — (I) The destination variable. A single field or an array of n elements where n is FMT-COUNT. Each array element is of size FMT-MAXLEN. BUFFER is the program variable to which CTBBIND binds the server results. When the application calls CTBFETCH to fetch the result data, it is copied into this space.

This argument will usually be one of the following datatypes:

01 BUFFER PIC S9(10) BINARY. 01 BUFFER PIC X(n).

If you no longer want to store incoming data in this buffer, set FMT-MAXLEN to 0.

COPIED — (I) The length of the incoming data. This can be a single field or, if BUFFER is an array, it can be an array of n elements where n is FMT-COUNT. At fetch time, CTBFETCH fills COPIED with the lengths of the copied data.

COPIED-NULL — (I) The NULL indicator for COPIED. This argument allows you to indicate that COPIED should be treated as empty. If COPIED is an array, assigning CS-PARAM-NULL to this argument causes all elements of COPIED to be treated as empty; assigning CS-PARAM-NOTNULL to this argument causes all elements of INDICATOR to be examined for their assigned values.

INDICATOR — (I) Integer variables from 1 to FMT-COUNT. At fetch time, CTBFETCH uses each variable to indicate the following conditions about the fetched data.

If BUFFER is an array, INDICATOR will also be an array.

Symbolic Valueof INDICATOR

Integer Value Indicates:

CS-NULLDATA -1 The fetched data was NULL. In this case, no data is copied to the destination variable.

CS-GOODDATA 0 The fetch was successful.

________ integer value The actual length of the server data, if the fetch resulted in truncation.



INDICATOR-NULL — (I) The NULL indicator for INDICATOR. This argument allows you to indicate that INDICATOR should be treated as empty. If INDICATOR is an array, assigning CS-PARAM-NULL to this argument causes all elements of INDICATOR to be treated as empty; assigning CS-PARAM-NOTNULL to this argument causes all elements of INDICATOR to be examined for their assigned values.

Comments

• CTBBIND associates (binds) a column, parameter, or status returned by a server to a program variable. Once a result is bound to a variable, any information returned in that column or parameter, or any status returned during a CTBFETCH call is copied to that variable.

• An application must call CTBBIND once for each result column or return parameter.

• CTBBIND can be used to bind a result column, a return parameter, or a stored procedure status value. Multiple rows of a result column can be bound with a single call to CTBBIND. A return status must be bound with the single integer datatype, CS-INT.

• An application calls CTBBIND after CTBRESULTS and before CTBFETCH. CTBRESULTS tells the application if there are any results to be bound and if so, what kind; CTBFETCH retrieves the results and copies them into the bound variable.

• CTBBIND binds only the current result type. CTBRESULTS indicates the current result type by its RESULT-TYP argument. For example, if CTBRESULTS returns CS-STATUS-RESULT, a return status is available for binding.

• An application can call CTBRESINFO to determine the number of items in the current result set; it can call CTBDESCRIBE to get a description of each item.

• An application can only bind a result item to a single program variable. If an application binds a result item to multiple variables, only the last binding takes effect.



• Binding for a particular type of result remains in effect until CTBRESULTS returns CS-CMD-DONE to indicate that the results of a logical command are completely processed.

• If you no longer want to store incoming data in the program variable, the application may call CTBBIND with a null BUFFER (i.e., FMT-MAXLEN = 0).

• The following table lists the conversions performed by CTBBIND.

Table 3-3: Datatype Conversions Performed by CTBBIND

Source Type Result Type

CS-BINARY CS-CHAR

CS-CHAR CS-DATETIMECS-DATETIME4CS-MONEYCS-MONEY4CS-PACKEDECCS-VARCHAR

CS-DATETIME CS-CHAR

CS-DATETIME4 CS-CHAR

CS-DECIMAL CS-PACKEDEC

CS-FLOAT CS-PACKEDECCS-REAL

CS-MONEY CS-CHARCS-FLOATCS-PACKEDECCS-VARCHAR

CS-MONEY4 CS-CHAR

CS-NUMERIC CS-PACKEDEC

CS-REAL CS-FLOAT



Array Binding

• Array binding is the act of binding a result column to an array of program variables. At fetch time, multiple rows of the column are copied to the array of variables with a single CTBFETCH call. An application indicates array binding by assigning FMT-COUNT a value greater than 1.

• Array binding is only practical for regular row results. Other types of results are considered the equivalent of a single row.

• When columns are bound to arrays in a single command, all CTBBIND calls in the sequence of calls binding the columns must use the same value for FMT-COUNT. For example, when binding three columns to arrays, it is an error to assign FMT-COUNT a value of 5 in the first two CTBBIND calls and 3 in the last.

Example

The following code fragment demonstrates the use of CTBBIND. It is taken from the sample program CLNT1, described in Appendix A.

****************************************************************** * Return the Number of Items in the Current Result Set * * ( CTBRESIN ) * ****************************************************************** * SET RESULT-TYPE = CS-NUMDATA. REQ THE # OF ITEMS IN RESULT SET * * RETURN: RF-NUMDATA = THE NUMBER OF ITEMS IN THE RESULT SET * ******************************************************************

. . . . PERFORM 3300-BIND-COLUMNS THRU 3300-BIND-COLUMNS-EXIT VARYING CL-INDEX FROM 1 BY 1 UNTIL CL-INDEX IS GREATER THAN RF-NUMDATA. . . . .



****************************************************************** * 3300-BIND-COLUMNS * ****************************************************************** * Bind the returned column data to a variable name * ****************************************************************** * Describe a piece of datum. - 'CTBDESCR' * * Bind the returned data to a variable name. - 'CTBBIND' * * 3210-BIND-EACH-COLUMN. * ****************************************************************** 3300-BIND-COLUMNS. *----------------------------------------------------------------* * Return a Description of a Piece of Datum of the Result Set * * ( CTBDESCR ) * *----------------------------------------------------------------* * INPUT: ( CL-INDEX = DATUM ITEM NUMBER ) * * OUTPUT ( DATA-FORMAT = RESULT DESCRIPTION STRUCTURE ) * *----------------------------------------------------------------* MOVE LOW-VALUE TO DATA-FORMAT.

CALL 'CTBDESCR' USING CL-COMMAND-HANDLE, CL-RETURN-CODE, CL-INDEX, DATA-FORMAT.

IF CL-RETURN-CODE NOT EQUAL CS-SUCCEED THEN MOVE ERR-U-CTBDESCR TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT PERFORM 9800-CLIENT-MSG THRU 9800-CLIENT-MSG-EXIT PERFORM 7000-TERMINATE THRU 7000-TERMINATE-EXIT END-IF.

D DISPLAY 'CTBDESCR: Describe ITEM #: ', CL-INDEX UPON PRT. D PERFORM 9500-DISPLAY-DATAFMT THRU D 9500-DISPLAY-DATAFMT-EXIT.

*----------------------------------------------------------------* * Bind the Returned Data to a Program Variable * * ( CTBBIND ) * *----------------------------------------------------------------* * CALL 'CTBBIND' USING COMMAND-HANDLE, RETURN-CODE, ITEM-NUMBER, * * DATA-FORMAT-STRUCTURE, * * DESTINATION-VARIABLE, * * DATA-LENGTH, DATA-LENGTH-NULL, * * INDICATOR, INDICATOR-NULL. * *----------------------------------------------------------------*



MOVE 1 TO DF-COUNT. IF PROCESSING-STATUS THEN CALL 'CTBBIND' USING CL-COMMAND-HANDLE, CL-RETURN-CODE, CL-INDEX, DATA-FORMAT, ST-STATUS, ST-LENGTH, CS-PARAM-NOTNULL, ST-NULLIND, CS-PARAM-NULL

IF CL-RETURN-CODE NOT EQUAL CS-SUCCEED THEN MOVE ERR-U-CTBBIND-STATUS TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT PERFORM 9800-CLIENT-MSG THRU 9800-CLIENT-MSG-EXIT PERFORM 7000-TERMINATE THRU 7000-TERMINATE-EXIT END-IF

GO TO 3300-BIND-COLUMNS-EXIT

END-IF.

IF PROCESSING-RTPARM THEN CALL 'CTBBIND' USING CL-COMMAND-HANDLE, CL-RETURN-CODE, CL-INDEX, DATA-FORMAT, RT-NUMROWS, RT-LENGTH, CS-PARAM-NOTNULL, ST-NULLIND, CS-PARAM-NULL

IF CL-RETURN-CODE NOT EQUAL CS-SUCCEED THEN MOVE ERR-U-CTBBIND-RTPARM TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT PERFORM 9800-CLIENT-MSG THRU 9800-CLIENT-MSG-EXIT PERFORM 7000-TERMINATE THRU 7000-TERMINATE-EXIT END-IF

GO TO 3300-BIND-COLUMNS-EXIT

END-IF.



EVALUATE FUNCTION LOWER-CASE(DF-NAME)

WHEN CL-DEST-NAME OF EMPLOYEE-ID

CALL 'CTBBIND' USING CL-COMMAND-HANDLE, CL-RETURN-CODE, CL-INDEX, DATA-FORMAT, CL-HOST-DATA OF EMPLOYEE-ID, CL-HOST-DATA-LEN OF EMPLOYEE-ID, CS-PARAM-NOTNULL, CL-HOST-DATA-IND OF EMPLOYEE-ID, CS-PARAM-NULL

IF CL-RETURN-CODE NOT EQUAL CS-SUCCEED THEN MOVE ERR-U-CTBBIND-EMP-ID TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT PERFORM 9800-CLIENT-MSG THRU 9800-CLIENT-MSG-EXIT PERFORM 7000-TERMINATE THRU 7000-TERMINATE-EXIT END-IF

. . . .

Returns

CTBBIND returns one of the following values.

See Also

CTBDESCRIBE, CTBFETCH, CTBRESINFO, CTBRESULTS

Topics: Datatypes

Value Meaning

CS-SUCCEED The routine completed successfully.

CS-FAIL The routine failed.


Function Descriptions CTBCANCEL 3-15

CTBCANCEL

Purpose

Cancel a request or the results of a request.

SyntaxCOPY CTPUBLIC01 CONNECTION COMP-2.01 RETCODE PIC S9(10) BINARY.01 COMMAND COMP-2.01 CANCELTYPE PIC S9(10) BINARY.

CALL 'CTBCANCE' USING CONNECTION, RETCODE COMMAND, CANCELTYPE.

Arguments

CONNECTION — (I) The command handle for this connection. This connection handle must already be allocated with CTBCONALLOC.

Either CONNECTION or COMMAND must be LOW-VALUES. If CONNECTION is supplied and COMMAND is LOW-VALUES, the CTBCANCEL operation applies to all commands pending for this connection.

RETCODE — (O) The variable in which the result of function execution is returned. Its value is one of the codes listed under Returns below.

COMMAND — (I) The command handle for this client/server operation. This handle is defined in the associated CTBCMDALLOC call.

Either CONNECTION or COMMAND must be LOW-VALUES. If COMMAND is supplied and CONNECTION is LOW-VALUES, the cancel operation applies only to the command pending for this command structure.

3-16 CTBCANCEL UniAccess for OS 2200 Client-Library Programming Reference


CANCELTYPE — (I) The type of cancel requested. The following table lists the symbolic values that are legal for CANCELTYPE.

Comments

• CTBCANCEL cancels the current result set.

• Canceling the current result set is equivalent to discarding the current set of results. Once results are discarded, they are no longer available to an application.

• In UniAccess Client-Library, CS-CANCEL-ALL and CS-CANCEL-ATTN function identically. Both immediately cancel the current request and discard all results generated by it.

Canceling a Request

• To cancel the current request and all results generated by it, an application calls CTBCANCEL with CANCELTYPE as CS-CANCEL-ATTN or CS-CANCEL-ALL. These calls tell UniAccess Client-Library to:

— Discard all results already generated by the request.

— Send an attention to the server instructing it to halt execution of the current request.

For example, suppose the current request is a Transact-SQL language request that contains the queries:

select * from titles select * from authors

Value of CANCELTYPE Action taken by CTBCANCEL

CS-CANCEL-ALL orCS-CANCEL-ATTN

CTBCANCEL sends an attention to the server, instructing it to cancel the current request, and immediately discards all results generated by the request.



If an application cancels the language request after the first query has executed but before the second query has executed:

— All remaining results from the first query are discarded.

— Execution of the second query is halted.

NoteA call to CTBCANCEL with CANCELTYPE as either CS-CANCEL-ALL or CS-CANCEL-ATTN must be immediately followed by a CTBRESULTS call.

• In Client-Library, canceling with CANCELTYPE as CS-CANCEL-ALL or CS-CANCEL-ATTN leaves the command structure in a clean state, available to be used for another operation.

• For both the CS-CANCEL-ATTN and CS-CANCEL-ALL types of cancels, if no request is in progress, CTBCANCEL returns CS-SUCCEED immediately.

• If a request has been initiated but not yet sent, a CS-CANCEL-ALL is rejected.

Example

This code fragment demonstrates the use of CTBCANCEL. It is taken from the sample program CLNT1, described in Appendix A.

CALL 'CTBRESUL' USING CL-COMMAND-HANDLE, CL-RETURN-CODE, RF-TYPE. . . . .

EVALUATE CL-RETURN-CODE

WHEN CS-SUCCEED

EVALUATE RF-TYPE

3-18 CTBCANCEL UniAccess for OS 2200 Client-Library Programming Reference


WHEN CS-ROW-RESULT . . . WHEN CS-PARAM-RESULT . . . . WHEN CS-STATUS-RESULT . . . . WHEN CS-CMD-FAIL MOVE ERR-U-CTBRESUL TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT PERFORM 9600-CANCEL-COMMAND THRU 9600-CANCEL-COMMAND-EXIT . . . . ****************************************************************** * 9600-CANCEL-COMMAND * ****************************************************************** * Cancel the Current Command Results ( CTBCANCE ) * ****************************************************************** * CTBCANCE: CONNECTION = LOW-VALUES * * COMMAND = COMMAND-HANDLE * * CANCEL TYPE = CS-CANCEL-ALL * ****************************************************************** 9600-CANCEL-COMMAND.

CALL 'CTBCANCE' USING CL-LOW-VALUES, CL-RETURN-CODE, CL-COMMAND-HANDLE, CS-CANCEL-ALL.



IF CL-RETURN-CODE NOT EQUAL CS-SUCCEED THEN MOVE ERR-U-CTBCANCE-COM TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT MOVE 'N' TO SW-RESULTS GO TO 9600-CANCEL-COMMAND-EXIT END-IF.

D DISPLAY 'CTBCANCE: Current command cancelled.' UPON PRT. . . .

Returns

CTBCANCEL returns one of the following values.

See Also

CTBFETCH, CTBRESULTS

Value Meaning



3-20 CTBCLOSE UniAccess for OS 2200 Client-Library Programming Reference


CTBCLOSE

Purpose

Close a server connection.

Syntax

COPY CTPUBLIC.01 CONNECTION COMP-2.01 RETCODE PIC S9(10) BINARY.01 OPTION PIC S9(10) BINARY.

CALL 'CTBCLOSE' USING CONNECTION, RETCODE, OPTION.

Arguments

CONNECTION — (I) The handle for this connection. This connection handle must already be allocated with CTBCONALLOC.


OPTION — (I) The option (if any) to use for the close. The following table lists the symbolic values that are legal for OPTION.

Value of OPTION Action taken by CTBCLOSE

CS-UNUSED CTBCLOSE logs out and closes the connection.

If the connection has results pending, CTBCLOSE returns CS-FAIL.

This option is the default behavior.

CS-FORCE-CLOSE CTBCLOSE closes the connection whether or not results are pending and without notifying the server.

This option is primarily for use when an application is hung waiting for a server response.

CS-KEEP-CON This option is ignored. UACL treats it like CS-UNUSED.


Function Descriptions CTBCLOSE 3-21

Comments

• CTBCLOSE closes a server connection. All command handles associated with the connection are de-allocated.

• To de-allocate a connection handle, an application can call CTBCONDROP after the connection has been successfully closed.

• The behavior of CTBCLOSE depends on the value of OPTION, which determines the type of close. Each section below contains information on a type of close.

Default Close Behavior

• If the connection has any pending results, CTBCLOSE returns CS-FAIL.

• Before terminating the connection with the server, CTBCLOSE sends a logout message to the server and reads the response to this message. The contents of this message do not affect CTBCLOSE’s behavior.

CS-FORCE-CLOSE Behavior

• The connection is closed whether or not it has pending results.

• Because this option sends no logout message to the server, the server cannot tell whether the close is intentional or whether it is the result of a lost connection or crashed client.

CS-KEEP-CON Behavior

• CTBCLOSE closes the connection using default behavior but leaves the connection handle and the physical channel for the connection intact so that they can be used again.

• To re-use a connection handle, an application calls CTBCONNECT specifying the connection handle to be reused.

If the CTBCONNECT call specifies a new server, the saved physical channel is discarded and a channel to the new server is opened.



Example

The following code fragment demonstrates the use of CTBCLOSE. It is taken from the sample program CLNT1, described in Appendix A.

****************************************************************** * 7100-DROP-COMHANDLE * ****************************************************************** * De-Allocate (Drop) a Command Handle ( CTBCMDDR ) * ****************************************************************** 7100-DROP-COMHANDLE.

CALL 'CTBCMDDR' USING CL-COMMAND-HANDLE, CL-RETURN-CODE. . . . .

****************************************************************** * 7200-CLOSE-SERVER * ****************************************************************** * Close a Server Connection ( CTBCLOSE ) * ****************************************************************** 7200-CLOSE-SERVER.

CALL 'CTBCLOSE' USING CL-CONNECTION-HANDLE, CL-RETURN-CODE, CS-UNUSED.

IF CL-RETURN-CODE NOT EQUAL CS-SUCCEED THEN MOVE ERR-U-CTBCLOSE TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT PERFORM 9800-CLIENT-MSG THRU 9800-CLIENT-MSG-EXIT

CALL 'CTBCLOSE' USING CL-CONNECTION-HANDLE, CL-RETURN-CODE, CS-FORCE-CLOSE IF CL-RETURN-CODE NOT EQUAL CS-SUCCEED THEN MOVE ERR-U-CTBCLOSE-FORCE TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT PERFORM 9800-CLIENT-MSG THRU 9800-CLIENT-MSG-EXIT END-IF


Function Descriptions CTBCLOSE 3-23

END-IF.

D DISPLAY 'CTBCLOSE: Server Connection Closed' UPON PRT.

7200-CLOSE-SERVER-EXIT. EXIT.

. . . .

****************************************************************** * 7300-DROP-CONHANDLE * ****************************************************************** * De-Allocate (Drop) a Connection Handle ( CTBCONDR ) * ****************************************************************** 7300-DROP-CONHANDLE.

CALL 'CTBCONDR' USING CL-CONNECTION-HANDLE, CL-RETURN-CODE.

IF CL-RETURN-CODE NOT EQUAL CS-SUCCEED THEN MOVE ERR-U-CTBCONDR TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT PERFORM 9800-CLIENT-MSG THRU 9800-CLIENT-MSG-EXIT END-IF.

. . . .

****************************************************************** * 7400-EXIT-CLIENT * ****************************************************************** * Exit UniAccess Client Library ( CTBEXIT ) * ****************************************************************** 7400-EXIT-CLIENT.

CALL 'CTBEXIT' USING CL-CONTEXT-HANDLE, CL-RETURN-CODE, CS-UNUSED.



. . . .

****************************************************************** * 7500-DROP-CTXHANDLE * ****************************************************************** * De-Allocate (Drop) a Context Handle ( CTBCTXDR ) * ****************************************************************** 7500-DROP-CTXHANDLE.

CALL 'CSBCTXDR' USING CL-CONTEXT-HANDLE, CL-RETURN-CODE. . . . .

Returns

CTBCLOSE returns one of the following values.

See Also

CTBCONDROP, CTBCONNECT, CTBCONPROPS

Value Meaning



The most common reason for a CTBCLOSE failure is pending results on the connection.


Function Descriptions CTBCMDALLOC 3-25

CTBCMDALLOC

Purpose

Allocate a command handle.

Syntax

COPY CTPUBLIC.01 CONNECTION COMP-2.01 RETCODE PIC S9(10) BINARY.01 COMMAND COMP-2.

CALL 'CTBCMDAL' USING CONNECTION, RETCODE, COMMAND.

Arguments



COMMAND — (O) The variable in which this newly-allocated command handle is returned. All subsequent client requests using this connection must use this same name in the COMMAND argument.

In case of error, CTBCMDALLOC returns NULL to this argument.

Comments

• CTBCMDALLOC allocates a command handle on a specified connection. A command handle is a control structure that a UniAccess Client-Library application uses to send requests to a server and to process the results of those requests.

• A Client-Library application uses a command handle to send commands to a server and process the results of those commands.

3-26 CTBCMDALLOC UniAccess for OS 2200 Client-Library Programming Reference


• Before calling CTBCMDALLOC, an application must allocate a connection structure using the Client-Library function CTBCONALLOC.

• An application must call CTBCMDALLOC once for each logical command it issues. Note that each language statement is considered a separate logical command.

Example

The following code fragment demonstrates the use of CTBCMDALLOC. It is taken from the sample program CLNT1, described in Appendix A.

****************************************************************** * 1800-COMMAND-HANDLE * ****************************************************************** * Allocate a Command Handle ( CTBCMDAL ) * ****************************************************************** 1800-COMMAND-HANDLE.

CALL 'CTBCMDAL' USING CL-CONNECTION-HANDLE, CL-RETURN-CODE, CL-COMMAND-HANDLE.

IF CL-RETURN-CODE NOT EQUAL CS-SUCCEED THEN MOVE ERR-U-CTBCMDAL TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT PERFORM 9800-CLIENT-MSG THRU 9800-CLIENT-MSG-EXIT PERFORM 7200-CLOSE-SERVER THRU 7200-CLOSE-SERVER-EXIT PERFORM 7300-DROP-CONHANDLE THRU 7300-DROP-CONHANDLE-EXIT PERFORM 7400-EXIT-CLIENT THRU 7400-EXIT-CLIENT-EXIT PERFORM 7500-DROP-CTXHANDLE THRU 7500-DROP-CTXHANDLE-EXIT END-IF. . . . .


Function Descriptions CTBCMDALLOC 3-27

Returns

CTBCMDALLOC returns one of the following values.

See Also

CTBCMDDROP, CTBCMDPROPS, CTBCOMMAND, CTBCONALLOC

Value Meaning



The most common reason for a CTBCMDALLOC failure is a lack of adequate memory.

3-28 CTBCMDDROP UniAccess for OS 2200 Client-Library Programming Reference


CTBCMDDROP

Purpose

De-allocate (drop) a command handle.

Syntax

COPY CTPUBLIC.01 COMMAND COMP-2.01 RETCODE PIC S9(10) BINARY.

CALL 'CTBCMDDR' USING COMMAND, RETCODE.

Arguments

COMMAND — (I) The handle for this client/server operation. This handle is defined in the associated CTBCMDALLOC call.


Comments

• CTBCMDDROP de-allocates a command handle.

• If CTBCMDDROP is called while a command is pending (results have not all been returned), this function will fail. Before dropping a command structure, an application should process or cancel any pending results.

• Once a command handle has been de-allocated, it cannot be re-used. To allocate a new command handle, an application can call CTBCMDALLOC.


Function Descriptions CTBCMDDROP 3-29

Example

The following code fragment demonstrates the use of CTBCMDDROP. It is taken from the sample program CLNT1, described in Appendix A.


CALL 'CTBCMDDR' USING CL-COMMAND-HANDLE, CL-RETURN-CODE.

IF CL-RETURN-CODE NOT EQUAL CS-SUCCEED THEN MOVE ERR-U-CTBCMDDR TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT PERFORM 9800-CLIENT-MSG THRU 9800-CLIENT-MSG-EXIT END-IF. . . . .

Returns

CTBCMDDROP returns one of the following values.

See Also

CTBCMDALLOC, CTBCOMMAND

Value Meaning


CS-FAIL The routine failed. CTBCMDDROP returns CS-FAIL if the command handle has any results pending.

3-30 CTBCMDPROPS UniAccess for OS 2200 Client-Library Programming Reference


CTBCMDPROPS

Purpose

Set, retrieve, or clear information for the current command handle about the current result set.

Syntax

COPY CTPUBLIC.01 COMMAND COMP-2.01 RETCODE PIC S9(10) BINARY.01 ACTION PIC S9(10) BINARY.01 PROPERTY PIC S9(10) BINARY.01 BUFFER type.01 BUFFER-LEN PIC S9(10) BINARY.01 BUFBLANKSTRIP PIC S9(10) BINARY.01 OUTLEN PIC S9(10) BINARY.

CALL 'CTBCMDPR' USING COMMAND, RETCODE, ACTION, PROPERTY, BUFFER, BUFFER-LEN, BUFBLANKSTRIP, OUTLEN.

Arguments



ACTION — (I) The action to be taken by this call. ACTION is an integer variable that indicates the purpose of this call.

Assign ACTION one of the following symbolic values.


Function Descriptions CTBCMDPROPS 3-31

PROPERTY — (I) The symbolic name of the property whose value is being set or retrieved. UniAccess Client-Library properties are listed under Properties on page 2-33, with descriptions, possible values, and defaults.

BUFFER — (I/O) The variable (buffer) that will contain the specified property value. If ACTION is CS-SET, CTBCMDPROPS will write the specified value from this buffer; if ACTION is CS-GET, CTBCMDPROPS will return the requested information to this buffer; if ACTION is CS-CLEAR, this buffer will be empty.



BUFFER-LEN — (I) Length, in bytes, of the buffer.

If a property value is being set and the value in the buffer is a fixed-length or symbolic value, assign BUFFER-LEN a value of CS-UNUSED.

If a property value is being retrieved and BUFFER-LEN indicates that BUFFER is not large enough to hold the requested information, CTBCMDPROPS will set OUTLEN to the length of the requested information and return CS-FAIL. To retrieve all the requested information, change the value of BUFFER-LEN to the length referenced in OUTLEN; rerun the application.

If a property value is being set and the terminating character is the last non-blank character, assign CS-TRUE to BUFBLANKSTRIP.

If ACTION is CS-CLEAR, this value will be ignored.

Value of ACTION Action taken by CTBCMDPROPS

CS-SET Sets the value of the property.

CS-GET Retrieves the value of the property.

CS-CLEAR Clears the value of the property by resetting it to its Client-Library default value.



BUFBLANKSTRIP — (I) Blank stripping indicator. Indicates whether or not trailing blanks are stripped (that is, if the value in the buffer ends at the last non-blank character).

Assign this argument one of the following symbolic values.

OUTLEN — (O) Length, in bytes, of the retrieved information. OUTLEN is an integer variable in which CTBCMDPROPS returns the length of the property value being retrieved.

When the retrieved information is larger than BUFFER-LEN bytes, an application uses the value of OUTLEN to determine how many bytes are needed to hold the information.

When ACTION is CS-CLEAR or CS-SET, this value is ignored.

Comments

• CTBCMDPROPS sets or retrieves the values of properties of command handle structures.

• Command handle properties affect the behavior of an application at the command structure level.

• Some properties default to the value of the property in the parent context. To find out which ones, see Properties on page 2-33.

Value of BUFBLANKSTRIP Indicates

CS-TRUE Value in the buffer ends at the last non-blank character (that is, trailing blanks are stripped).

CS-FALSE Trailing blanks are included in the value (that is, they are not stripped).


Function Descriptions CTBCMDPROPS 3-33

Example

The following code fragment demonstrates the use of CTBCMDPROPS. This sample is not part of any sample program, so the WORKING STORAGE section is included here.

* * The following vars are for testing property user data*

01 USER-DATA PIC X(20) .01 USER-DATA-RECV PIC X(8) .01 USER-DATA-LEN PIC S9(10) BINARY VALUE +0 .

MOVE 'userdata' TO USER-DATA . MOVE 8 TO USER-DATA-LEN .

CALL 'CTBCMDPR' USING CSL-CMD-HANDLE, CSL-RC, CS-SET CS-USERDATA, USER-DATA, USER-DATA-LEN, CS-FALSE, PF-OUTLEN . IF CSL-RC NOT EQUAL CS-SUCCEED THEN MOVE " Error in CTBCMDPR-USEDATA " TO ERROR-TEXT MOVE CSL-RC TO ERROR-RC PERFORM ERROR-OUT PERFORM DONE-PARA END-IF . DISPLAY "CTBCMDPR-USEDATA DONE" UPON PRINTER .

CALL 'CTBCMDPR' USING CSL-CMD-HANDLE, CSL-RC, CS-GET CS-USERDATA, USER-DATA-RECV, USER-DATA-LEN, CS-FALSE, PF-OUTLEN . IF CSL-RC NOT EQUAL CS-SUCCEED THEN MOVE " Error in CTBCMDPR-USEDATA-RECV " TO ERROR-TEXT MOVE CSL-RC TO ERROR-RC PERFORM ERROR-OUT PERFORM DONE-PARA END-IF . DISPLAY "CTBCMDPR-USEDATA-RECV DONE" UPON PRINTER . DISPLAY USER-DATA-RECV UPON PRINTER . DISPLAY PF-OUTLEN UPON PRINTER .



Returns

CTBCMDPROPS returns one of the following values.

See Also

CTBCMDALLOC, CTBCONFIG, CTBCONPROPS, CTBRESINFO

Topics: Buffers, Properties

Value Meaning




Function Descriptions CTBCOMMAND 3-35

CTBCOMMAND

Purpose

Initiate a language request or remote procedure call.

Syntax

COPY CTPUBLIC.01 COMMAND COMP-2.01 RETCODE PIC S9(10) BINARY.01 REQTYPE PIC S9(10) BINARY.01 BUFFER type.01 BUFFER-LEN PIC S9(10) BINARY.01 OPTION PIC S9(10) BINARY.

CALL 'CTBCOMMA' USING COMMAND, RETCODE, REQTYPE, BUFFER, BUFFER-LEN, OPTION.

Arguments



REQTYPE — (I) The type of request to initiate. The following symbolic values are legal for REQTYPE.

Value of REQTYPE

Action taken byCTBCOMMAND Buffer contains

CS-LANG-CMD Initiates a language request. The text of the language request.

CS-RPC-CMD Initiates a remote procedure call.

The name of the remote procedure.

3-36 CTBCOMMAND UniAccess for OS 2200 Client-Library Programming Reference


BUFFER — (I) The variable (buffer) that contains the language request or RPC name.



BUFFER-LEN — (I) The length, in bytes, of the buffer. If the value in the buffer is a fixed-length or symbolic value, assign BUFFER-LEN a value of CS-UNUSED.

OPTION — (I) The option (if any) associated with this request.

Currently, only RPCs take options. For language requests, assign OPTION a value of CS-UNUSED.

The following symbolic values are legal for OPTION when REQTYPE is CS-RPC-CMD.

Comments

• CTBCOMMAND initiates a language request or RPC. Initiating a request is the first step in sending it to a server.

Value of OPTION Requested server action

CS-RECOMPILE Recompile the stored procedure before executing it.

CS-NORECOMPILE Do not recompile the stored procedure before executing it.

CS-UNUSED Do not recompile the stored procedure before executing it.



• Sending a request to a server is a three step process. To send a request to a server, an application must:

1. Initiate the request by calling CTBCOMMAND. CTBCOMMAND sets up internal structures that are used in formatting the request sent to the server.

2. Pass parameters for the request, by calling CTBPARAM once for each parameter that the request requires.

3. Call CTBSEND to send the request to the server.

Language Requests

• Language requests contain character strings that represent requests in a server’s own language.

• The character string that makes up a language request can contain more than one server request.

• A language request can be in any language, so long as the server to which it is directed can understand it. For example, SQL Servers understand Transact-SQL, but a server application constructed with UniAccess Server-Library can be written to understand any language.

• If the language request string contains variables, an application can pass values for these variables by calling CTBPARAM once for each variable that the language string contains. A language request can have up to 255 parameters.

• Transact-SQL request variables must begin with the character (:).



Remote Procedure Calls

• An RPC instructs a server to execute a stored procedure or transaction on either itself or a remote server.

• If an application is using an RPC to execute a stored procedure or transaction that requires parameters, the application calls CTBPARAM once for each parameter the stored procedure or transaction requires.

• After sending an RPC with CTBSEND, an application can process the stored procedure or transaction’s results with CTBRESULTS and CTBFETCH. CTBRESULTS and CTBFETCH are used to process both the result rows generated by the stored procedure or transaction and the return parameters and status from the procedure (if any).

Example

The following code fragment demonstrates the use of CTBCOMMAND. It is taken from the sample program CLNT1, described in Appendix A.



. . . .



*----------------------------------------------------------------* * Initiate the Remote Procedure Call ( CTBCOMMA ) * *----------------------------------------------------------------* * REQUEST-TYPE = CS-RPC-CMD (FOR REMOTE PROCEDURE CALL) * * REQUEST-BUFFER = NAME OF REMOTE PROCEDURE CALL * * BUFFER-LENGTH = LENGTH OF NAME OF REMOTE PROCEDURE CALL * *----------------------------------------------------------------* MOVE CF-RPC-SIZE TO PF-STRLEN. CALL 'CTBCOMMA' USING CL-COMMAND-HANDLE, CL-RETURN-CODE, CS-RPC-CMD, CF-RPC, PF-STRLEN, CS-UNUSED. IF CL-RETURN-CODE NOT EQUAL CS-SUCCEED THEN MOVE ERR-U-CTBCOMMA TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT PERFORM 9800-CLIENT-MSG THRU 9800-CLIENT-MSG-EXIT PERFORM 7000-TERMINATE THRU 7000-TERMINATE-EXIT END-IF. *----------------------------------------------------------------* * Define each Parameter to be sent to Server ( CTBPARAM ) * *----------------------------------------------------------------* *----------------------------------------------------------------* * Define Input Parameter: FIRST-NAME * * ( DF-STATUS OF DATA-FORMAT = CS-INPUTVALUE ) * *----------------------------------------------------------------* MOVE CL-PARM-NAME OF FIRST-NAME-PARM TO DF-NAME. MOVE CL-PARM-NAME-LEN OF FIRST-NAME-PARM TO DF-NAME-LENGTH . MOVE CS-INPUTVALUE TO DF-STATUS. MOVE CS-CHAR-TYPE TO DF-DATATYPE. MOVE CS-UNUSED TO DF-MAX-LENGTH.

CALL 'CTBPARAM' USING CL-COMMAND-HANDLE, CL-RETURN-CODE, DATA-FORMAT, CL-PARM-DATA OF FIRST-NAME-PARM, CL-PARM-LEN OF FIRST-NAME-PARM, INDICATOR.



. . . . *----------------------------------------------------------------* * Send the Remote Procedure Request ( CTBSEND ) * *----------------------------------------------------------------* CALL 'CTBSEND' USING CL-COMMAND-HANDLE, CL-RETURN-CODE.

. . . .

Returns

CTBCOMMAND returns one of the following values.

See Also

CTBCMDALLOC, CTBPARAM, CTBSEND

Topics: Remote Procedure Calls

Value Meaning




Function Descriptions CTBCONALLOC 3-41

CTBCONALLOC

Purpose

Allocate a connection handle.

Syntax

COPY CTPUBLIC.01 CONTEXT COMP-2.01 RETCODE PIC S9(10) BINARY.01 CONNECTION COMP-2.

CALL 'CTBCONAL' USING CONTEXT, RETCODE, CONNECTION.

Arguments

CONTEXT — I) A context handle. The context handle is defined in the program’s CSBCTXALLOC call.

If this value is invalid or NULL, CTBCONALLOC will fail.


CONNECTION — (O) The handle for this connection. All subsequent Client-Library calls using this connection must use this same name in their CONNECTION argument.

In case of error, CTBCONALLOC returns LOW-VALUES to this argument.

Comments

• CTBCONALLOC allocates a connection handle.

• A connection handle contains information about a particular client/server connection.

3-42 CTBCONALLOC UniAccess for OS 2200 Client-Library Programming Reference


• Before calling CTBCONALLOC, an application must:

— Call CSBCTXALLOC to allocate a context structure

— Call CTBINIT to initialize UniAccess Client-Library.

• Connecting to a server is a three-step process. To connect to a server, an application:

1. Calls CTBCONALLOC to obtain a connection handle

2. Calls CTBCONPROPS to set the values of connection-specific properties, if desired

3. Calls CTBCONNECT to create the connection and log in to the server..

• All connections created within a context pick up default property values from the parent context. An application can override these default values by calling CTBCONPROPS to set property values at the connection level.

• An application can have multiple connections to one or more servers at the same time.

For example, an application can simultaneously have two connections to the UniAccess Transaction Server named UACS1 on the local OS 2200 host, one connection to the UniAccess ODBC Server for RDMS 2200 named UACS2 on a remote OS 2200, and one connection to a SQL Server named sybase. The context property CS-MAX-CONNECT, set by CTBCONFIG, determines the maximum number of connections allowed per context.

Each server connection requires a separate connection handle.

• In order to send requests to a server, one or more command handles must be allocated for a connection. CTBCMDALLOC allocates a command handle.


Function Descriptions CTBCONALLOC 3-43

Example

The following code fragment demonstrates the use of CTBCONALLOC. It is taken from the sample program CLNT1, described in Appendix A.

****************************************************************** * 1200-CONTEXT-HANDLE * ****************************************************************** * Allocate a Context Handle ( CSBCTXAL ) * ****************************************************************** 1200-CONTEXT-HANDLE.

CALL 'CSBCTXAL' USING CS-VERSION-100, CL-RETURN-CODE, CL-CONTEXT-HANDLE. . . . .

****************************************************************** * 1300-INIT-CLIENT-LIB * ****************************************************************** * Initialize UniAccess Client Library ( CTBINIT ) * ****************************************************************** 1300-INIT-CLIENT-LIB.

CALL 'CTBINIT' USING CL-CONTEXT-HANDLE, CL-RETURN-CODE, CS-VERSION-100. . . . .

****************************************************************** * 1400-CONNECT-HANDLE * ****************************************************************** * Allocate a Connection (Connection Handle) to the Server * ****************************************************************** 1400-CONNECT-HANDLE.

3-44 CTBCONALLOC UniAccess for OS 2200 Client-Library Programming Reference


CALL 'CTBCONAL' USING CL-CONTEXT-HANDLE, CL-RETURN-CODE, CL-CONNECTION-HANDLE.

IF CL-RETURN-CODE NOT EQUAL CS-SUCCEED THEN MOVE ERR-U-CTBCONAL TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT PERFORM 7400-EXIT-CLIENT THRU 7400-EXIT-CLIENT-EXIT PERFORM 7500-DROP-CTXHANDLE THRU 7500-DROP-CTXHANDLE-EXIT END-IF. . . . .

Returns

CTBCONALLOC returns one of the following values.

See Also

CTBCLOSE, CTBCMDALLOC, CTBCONNECT, CTBCONPROPS, CSBCTXALLOC

Value Meaning



The most common reason for a CTBCONALLOC failure is a lack of adequate memory.


Function Descriptions CTBCONDROP 3-45

CTBCONDROP

Purpose

De-allocate (drop) a connection handle.

Syntax

COPY CTPUBLIC.01 CONNECTION COMP-2.01 RETCODE PIC S9(10) BINARY.

CALL 'CTBCONDR' USING CONNECTION, RETCODE.

Arguments

CONNECTION — (I) The handle for this connection. This must be the same value specified in the CTBCONALLOC call that initialized this connection.


Comments

• CTBCONDROP de-allocates a connection handle and all command handles associated with that connection.

• Once a connection handle has been de-allocated, it cannot be reused. To allocate a new connection handle, an application calls CTBCONALLOC.

• An application cannot de-allocate a connection handle until the connection it represents has been successfully closed. To close a connection, an application calls CTBCLOSE.

3-46 CTBCONDROP UniAccess for OS 2200 Client-Library Programming Reference


Example

The following code fragment demonstrates the use of CTBCONDROP. It is taken from the sample program CLNT1, described in Appendix A.




CALL 'CTBCLOSE' USING CL-CONNECTION-HANDLE, CL-RETURN-CODE, CS-UNUSED. . . . .


CALL 'CTBCONDR' USING CL-CONNECTION-HANDLE, CL-RETURN-CODE.


Function Descriptions CTBCONDROP 3-47

. . . . ****************************************************************** * 7400-EXIT-CLIENT * ****************************************************************** * Exit UniAccess Client Library ( CTBEXIT ) * ****************************************************************** 7400-EXIT-CLIENT.

CALL 'CTBEXIT' USING CL-CONTEXT-HANDLE, CL-RETURN-CODE, CS-UNUSED. . . . .



3-48 CTBCONDROP UniAccess for OS 2200 Client-Library Programming Reference


Returns

CTBCONDROP returns one of the following values.

See Also

CTBCLOSE, CTBCONALLOC, CTBCONNECT, CTBCONPROPS

Value Meaning



The most common reason for a CTBCONDROP failure is that the connection is still open.


Function Descriptions CTBCONFIG 3-49

CTBCONFIG

Purpose

Set or retrieve context properties.

Syntax

COPY CTPUBLIC.01 CONTEXT COMP-2.01 RETCODE PIC S9(10) BINARY.01 ACTION PIC S9(10) BINARY.01 PROPERTY PIC S9(10) BINARY.01 BUFFER type.01 BUFFER-LEN PIC S9(10) BINARY.01 BUFBLANKSTRIP PIC S9(10) BINARY.01 OUTLEN PIC S9(10) BINARY.

CALL 'CTBCONFI' USING CONTEXT, RETCODE, ACTION, PROPERTY, BUFFER, BUFFER-LEN, BUFBLANKSTRIP, OUTLEN.

Arguments

CONTEXT — (I) A context handle. The context handle is defined in the program’s CSBCTXALLOC call.

If this value is invalid or NULL, CTBCONFIG will fail.



3-50 CTBCONFIG UniAccess for OS 2200 Client-Library Programming Reference



PROPERTY — (I) The symbolic name of the property whose value is being set or retrieved. UniAccess Client-Library properties are listed under Properties on page 2-33 with description, possible values, and defaults.

BUFFER — (I/O) The variable (buffer) that will contain the specified property value. If ACTION is CS-SET, CTBCONFIG will write the specified value from this buffer; if ACTION is CS-GET, CTBCONFIG will return the requested information to this buffer; if ACTION is CS-CLEAR, this buffer will contain a null value.



BUFFER-LEN — (I) The length, in bytes, of the buffer.



If a property value is being retrieved and BUFFER-LEN indicates that BUFFER is not large enough to hold the requested information, CTBCONFIG sets OUTLEN to the length of the requested information and returns CS-FAIL. To retrieve all the requested information, change the value of BUFFER-LEN to the length referenced in OUTLEN; rerun the application.


Value of ACTION Action taken by CTBCONFIG



CS-CLEAR Sets the buffer and the OUTLEN parameter to NULL.



BUFBLANKSTRIP — (I) The blank stripping indicator. Indicates whether or not trailing blanks are stripped (that is, if the value in the buffer ends at the last non-blank character).


OUTLEN — (O) The length, in bytes, of the retrieved information. OUTLEN is an integer variable in which CTBCONFIG returns the length of the property value being retrieved. OUTLEN is used only when ACTION is CS-GET. When the retrieved information is larger than BUFFER-LEN bytes, an application uses the value of OUTLEN to determine how many bytes are needed to hold the information.

If the ACTION is CS-SET or CS-CLEAR, this value is ignored.

Comments

• CSBCONFIG sets or retrieves the values of the CS-EXTRA-INF and CS-VERSION. All other context properties are set or reset by CTBCONFIG.

• Context properties define aspects of Client-Library behavior at the context level.

• All connections created within a context pick up default property values from the parent context. An application can override these default values by calling CTBCONPROPS to set property values at the connection level.

• If an application changes context property values after allocating connections for the context, the existing connections will not pick up the new property values. Only new connections allocated after the new context property values have been set will use the new values as defaults.

Value Indicates:



3-52 CTBCONFIG UniAccess for OS 2200 Client-Library Programming Reference


Example

The following code fragment demonstrates the use of CTBCONFIG. The example is not part of any sample program, so the WORKING STORAGE section is included here.

WORKING-STORAGE SECTION . COPY CTPUBLIC .

01 CS-LIB-MISC-FIELDS . 05 CSL-CTX-HANDLECOMP-2 VALUE +0 . 05 CSL-CON-HANDLECOMP-2 VALUE +0 . 05 CSL-CMD-HANDLECOMP-2 VALUE +0 . 05 CSL-RC PIC S9(10) USAGE BINARY . 05 CSL-NULL PIC S9(10) BINARY VALUE +0 .

01 PF-USER PIC X(12) VALUE 'user1234' . 01 PF-PWD PIC X(08) VALUE '111111' . 01 PF-SERVER PIC X(08) VALUE 'SYBASE10' . 01 PF-APPNAME PIC X(08) VALUE 'UACL' . 01 PF-USER-SIZE PIC S9(10) BINARY VALUE +8 . 01 PF-PWD-SIZE PIC S9(10) BINARY VALUE +6 . 01 PF-SERVER-SIZE PIC S9(10) BINARY VALUE +8 . 01 PF-APPNAME-SIZE PIC S9(10) BINARY VALUE +4 . 01 PF-OUTLEN PIC S9(10) BINARY VALUE +0 . 01 PF-STRLEN PIC S9(10) BINARY VALUE +0 . 01 PF-MSGLIMIT PIC S9(10) BINARY VALUE +0 . 01 CF-MAXCONNECT PIC S9(10) BINARY VALUE +0 . 01 CF-FOUR PIC S9(10) BINARY VALUE +4 . 01 CF-OUTLEN PIC S9(10) BINARY VALUE +0 .** Open a connection to server* CALL 'CTBCONNE' USING CSL-CON-HANDLE, CSL-RC, PF-SERVER, PF-STRLEN, CS-FALSE .

IF CSL-RC NOT EQUAL CS-SUCCEED THEN MOVE " Error in CTBCONNE " TO ERROR-TEXT MOVE CSL-RC TO ERROR-RC PERFORM ERROR-OUT PERFORM DONE-PARA END-IF .



** Find out what the maximum connection is*

CALL 'CTBCONFI' USING CSL-CTX-HANDLE, CSL-RC, CS-GET, CS-MAX-CONNECT, CF-MAXCONNECT, CF-FOUR, CS-FALSE, CF-OUTLEN .

IF CSL-RC NOT EQUAL CS-SUCCEED THEN MOVE " Error in CTBCONFI " TO ERROR-TEXT MOVE CSL-RC TO ERROR-RC PERFORM ERROR-OUT PERFORM DONE-PARA END-IF .

Returns

CTBCONFIG returns one of the following values.

See Also

CTBCMDPROPS, CTBCONNECT, CTBCONPROPS, CTBINIT Topics: Buffers, Properties

Value Meaning



3-54 CTBCONNECT UniAccess for OS 2200 Client-Library Programming Reference


3 Function DescriptionsCTBCONNECT

Purpose

Connect to a server.

Syntax

COPY CTPUBLIC01 CONNECTION COMP-2.01 RETCODE PIC S9(10) BINARY.01 SERVERNAME PIC X(30).01 SERVERNAME-LEN PIC S9(10) BINARY.01 BUFBLANKSTRIP PIC S9(10) BINARY.

CALL 'CTBCONNE' USING CONNECTION, RETCODE, SERVERNAME, SERVERNAME-LEN, BUFBLANKSTRIP.

Arguments



SERVERNAME — (I) The name of the connected server. This name is defined in a SERVER configuration statement in the UniAccess Configuration File (see Chapter 16 of the UniAccess for OS 2200 System Administration Guide).

A value must be assigned to this argument. If no server name is specified, CTBCONNECT will fail.

SERVERNAME-LEN — (I) The length, in bytes, of SERVERNAME. If the server name ends at the last non-blank character, CS-TRUE should be assigned to BUFBLANKSTRIP.


Function Descriptions CTBCONNECT 3-55

BUFBLANKSTRIP — (I) The blank stripping indicator. Indicates whether or not trailing blanks are stripped (that is, if the value in the buffer ends at the last non-blank character).


Comments

• CTBCONNECT establishes a connection between a client application and a server application. Information about the connection is stored in a connection handle, which uniquely identifies the connection.

• The remote server can be the UniAccess Transaction Server, the UniAccess ODBC Server for RDMS 2200, the UniAccess ODBC Server for DMS 2200, or a remote server on the network, such as a SQL Server or an Open Server. Server names are defined in the UniAccess Configuration File. (For information, see the SERVER configuration statement in Chapter 16 of the UniAccess for OS 2200 System Administration Guide.)

• When CTBCONNECT establishes a connection, it sets up communication with the server, forwards login information, and communicates any connection-specific property information to the server.

• Because creating a connection involves sending login information, an application must define login parameters (the password and the userid for this server) before calling CTBCONNECT. An application calls CTBCONPROPS to define login parameters.

• The maximum number of open connections per context is determined by the CS-MAX-CONNECT property (set by CTBCONFIG). The default maximum is 25 connections.

Value of BUFBLANKSTRIP Indicates:



3-56 CTBCONNECT UniAccess for OS 2200 Client-Library Programming Reference


• There are several ways that an attempt to establish a connection can fail (assuming that the system is correctly configured):

— If there is no server listening on the specified port (even though both the machine that the server is supposed to be on and the network are running correctly), the connection cannot be formed. The machine the server is supposed to be on will signal the client with a network error. Regardless of the login time-out value, the connection will fail.

— If the machine that the server is on is down, the server will not respond.

Because no response is not considered to be an error, the network will not signal the client that an error has occurred. However, a time-out error will occur when the client fails to receive a response within the period specified by the NWRTIMEOUT parameter in the COMSRV configuration statement.

— If the maximum number of open connections exceed the PIDCNT parameter in the COMSRV statement of the UniAccess Configuration File or if the maximum number of open connections exceeds the value in CS-MAX-CONNECT, the server will not respond.

• To close a connection, an application calls CTBCLOSE.

• You can find further information about defining servers and connections in Chapter 16 of the UniAccess for OS 2200 System Administration Guide.

Example

The following code fragment demonstrates the use of CTBCONNECT. It is taken from the sample program CLNT1, described in Appendix A.

****************************************************************** * 1700-OPEN SERVER * ****************************************************************** * Open The Connection to the Server ( CTBCONNE ) * ****************************************************************** 1700-OPEN-SERVER.

MOVE CL-SERVER-LENGTH TO PF-STRLEN.


Function Descriptions CTBCONNECT 3-57

CALL 'CTBCONNE' USING CL-CONNECTION-HANDLE, CL-RETURN-CODE, CL-SERVER, PF-STRLEN, CS-FALSE. IF CL-RETURN-CODE NOT EQUAL CS-SUCCEED THEN MOVE ERR-U-CTBCONNE TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT PERFORM 9800-CLIENT-MSG THRU 9800-CLIENT-MSG-EXIT PERFORM 7300-DROP-CONHANDLE THRU 7300-DROP-CONHANDLE-EXIT PERFORM 7400-EXIT-CLIENT THRU 7400-EXIT-CLIENT-EXIT PERFORM 7500-DROP-CTXHANDLE THRU 7500-DROP-CTXHANDLE-EXIT END-IF. . . . .

Returns

CTBCONNECT returns one of the following values.

See Also

CTBCLOSE, CTBCONALLOC, CTBCONDROP, CTBCONFIG, CTBCONPROPS, CTBREMOTEPWD

Value Meaning



3-58 CTBCONPROPS UniAccess for OS 2200 Client-Library Programming Reference


CTBCONPROPS

Purpose

Set or retrieve connection handle properties.

Syntax

COPY CTPUBLIC.01 CONNECTION COMP-2.01 RETCODE PIC S9(10) BINARY.01 ACTION PIC S9(10) BINARY.01 PROPERTY PIC S9(10) BINARY.01 BUFFER type.01 BUFFER-LEN PIC S9(10) BINARY.01 BUFBLANKSTRIP PIC S9(10) BINARY.01 OUTLEN PIC S9(10) BINARY.

CALL 'CTBCONPR' USING CONNECTION, RETCODE, ACTION, PROPERTY, BUFFER, BUFFER-LEN, BUFBLANKSTRIP, OUTLEN

Arguments






Function Descriptions CTBCONPROPS 3-59

PROPERTY — (I) The symbolic name of the property whose value is being set or retrieved. Client-Library properties are listed under Properties on page 2-33, with description, possible values, and defaults.

BUFFER — (I/O) The variable (buffer) that will contain the specified property value. If ACTION is CS-SET, CTBCONPROPS will write the specified value from this buffer; if ACTION is CS-GET, CTBCONPROPS will return the requested information to this buffer; if ACTION is CS-CLEAR, this buffer will contain a null value.



BUFFER-LEN — (I/O) The length, in bytes, of the buffer.



If a property value is being retrieved and BUFFER-LEN indicates that BUFFER is not large enough to hold the requested information, CTBCONPROPS sets OUTLEN to the length of the requested information and returns CS-FAIL. To retrieve all the requested information, change the value of BUFFER-LEN to the length referenced in OUTLEN; rerun the application.


Value of ACTION Action taken by CTBCONPROPS



CS-CLEAR Clears the value of the property by resetting it to its Client-Library default value.



BUFBLANKSTRIP — (I) Blank stripping indicator. Indicates whether or not trailing blanks are stripped (that is, if the value in the buffer ends at the last non-blank character).


OUTLEN — (O) The length, in bytes, of the retrieved information. OUTLEN is an integer variable in which CTBCONPROPS returns the length of the property value being retrieved. OUTLEN is used only when ACTION is CS-GET.

If the retrieved information is larger than BUFFER-LEN bytes, an application uses the value of OUTLEN to determine how many bytes are needed to hold the information.

If the ACTION is CS-CLEAR or CS-SET, this value will be ignored.

Comments

• CTBCONPROPS sets or retrieves the values of properties for a connection handle. Connection properties define aspects of Client-Library behavior at the connection level.

• All command structures allocated for a connection pick up default property values from the parent connection. An application can override these default values by calling CTBCMDPROPS at the command structure level.

• If an application changes connection property values after allocating command structures for the connection, the existing command structures will not pick up the new property values. New command structures allocated for the connection will use the new property values as defaults.


CS-TRUE Value in the buffer ends at the last non-blank character; that is, trailing blanks are stripped.

CS-FALSE Trailing blanks are included in the value; that is, they are not stripped.



• Note that some connection properties only take effect if they are set before an application calls CTBCONNECT to establish the connection.

• An application can use CTBCONPROPS to set or retrieve the following properties:

CS-APPNAMECS-CHARSETCNVCS-EXTRA-INFCS-HOSTNAMECS-LOGIN-STATUSCS-NETIOCS-NOINTERRUPTCS-PACKETSIZECS-PASSWORDCS-TDS-VERSIONCS-TRANSACTION-NAMECS-USERDATA

Example

The following code fragment demonstrates the use of CTBCONPROPS. It is taken from the sample program CLNT1, described in Appendix A.


CALL 'CTBCONAL' USING CL-CONTEXT-HANDLE, CL-RETURN-CODE, CL-CONNECTION-HANDLE. . . .



****************************************************************** * 1600-ALTER-PROPERTY * ****************************************************************** * Alter Properties of the Connection ( CTBCONPR ) * ****************************************************************** 1600-ALTER-PROPERTY. *----------------------------------------------------------------* * CTBCONPR: SET USERNAME = CL-USERID * *----------------------------------------------------------------* MOVE CL-USERID-LENGTH TO PF-STRLEN.

CALL 'CTBCONPR' USING CL-CONNECTION-HANDLE, CL-RETURN-CODE, CS-SET, CS-USERNAME, CL-USERID, PF-STRLEN, CS-FALSE, CS-UNUSED. IF CL-RETURN-CODE NOT EQUAL CS-SUCCEED THEN MOVE ERR-U-CTBCONPR-USERID TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT PERFORM 9800-CLIENT-MSG THRU 9800-CLIENT-MSG-EXIT PERFORM 7300-DROP-CONHANDLE THRU 7300-DROP-CONHANDLE-EXIT PERFORM 7400-EXIT-CLIENT THRU 7400-EXIT-CLIENT-EXIT PERFORM 7500-DROP-CTXHANDLE THRU 7500-DROP-CTXHANDLE-EXIT END-IF.

D DISPLAY 'CTBCONPR: USERID Property Altered' UPON PRT.

*----------------------------------------------------------------* * CTBCONPR: SET PASSWORD = CL-PASSWORD * *----------------------------------------------------------------* MOVE CL-PASSWORD-LENGTH TO PF-STRLEN. CALL 'CTBCONPR' USING CL-CONNECTION-HANDLE, CL-RETURN-CODE, CS-SET, CS-PASSWORD, CL-PASSWORD, PF-STRLEN, CS-FALSE, CS-UNUSED.



IF CL-RETURN-CODE NOT EQUAL CS-SUCCEED THEN MOVE ERR-U-CTBCONPR-PASSWD TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT PERFORM 9800-CLIENT-MSG THRU 9800-CLIENT-MSG-EXIT PERFORM 7300-DROP-CONHANDLE THRU 7300-DROP-CONHANDLE-EXIT PERFORM 7400-EXIT-CLIENT THRU 7400-EXIT-CLIENT-EXIT PERFORM 7500-DROP-CTXHANDLE THRU 7500-DROP-CTXHANDLE-EXIT END-IF.

. . . .

Returns

CTBCONPROPS returns one of the following values.

See Also

CTBCMDPROPS, CTBCONFIG, CTBCONNECT, CTBINIT

Topics: Buffers, Properties

Value Meaning



3-64 CTBDESCRIBE UniAccess for OS 2200 Client-Library Programming Reference


CTBDESCRIBE

Purpose

Return a description of result data.

Syntax

COPY CTPUBLIC.01 COMMAND COMP-2.01 RETCODE PIC S9(10) BINARY.01 ITEM-NUM PIC S9(10) BINARY.01 DATAFMT


CALL 'CTBDESCR' USING COMMAND, RETCODE, ITEM-NUM, DATAFMT.

Arguments



ITEM-NUM — (I) The order number of the column, parameter, or status being returned. This value is an integer.


Function Descriptions CTBDESCRIBE 3-65

When a column is being described, ITEM-NUM is the column’s ordinal number. For example, the first column in a SQL select statement’s select list is column number 1, the second is column number 2, and so forth.

When a return parameter is being described, ITEM-NUM is the parameter number of the parameter. The first parameter returned by a procedure or server is number 1. SQL Server stored procedure return parameters are returned in the same order as the parameters were originally specified in the stored procedure’s or transaction’s CREATE PROCEDURE statement. This is not necessarily the same order as specified in the RPC that invoked the stored procedure or transaction. In determining what number to assign to ITEM-NUM do not count non-return parameters. For example, if the second parameter in a stored procedure or transaction is the only return parameter, its ITEM-NUM is 1. When a stored procedure return status is being described, ITEM-NUM must be 1, as there can be only a single status in a return status result set.

DATAFMT — (O) A structure that contains a description of the result data item referenced by ITEM-NUM. This structure is also used by CTBBIND, CTBPARAM, and CSBCONVERT. The topic Structures on page 2-55 provides an overview of this structure.

The DATAFMT structure has the fields described in the following table.



Table 3-4: Fields in the DATAFMT Structure for CTBDESCRIBE

Field name For which types of result items? CTBDESCRIBE sets the field to:

FMT-NAME Regular columns, return parameters. The null-terminated name of the data item, (if any). To indicate that there is no name, assign 0 to FMT-NAMELEN.

FMT-NAMELEN Regular columns, return parameters. The actual length, in bytes, of NAME, not including the null terminator.

A zero value here indicates no name.

FMT-TYPE Regular columns, return parameters, return status.

The datatype of the data item. All datatypes listed under Datatypes on page 2-18 are valid.

NOTE: A return status always has a datatype of CS-INT.

FMT-FORMAT Not used. n/a

FMT-MAXLEN Regular columns, return parameters. The maximum possible length, in bytes, of the data for the column or parameter being described.

FMT-SCALE Regular columns and return parameters of datatype packed decimal.

The number of digits to the right of the decimal point.

FMT-PRECIS Regular columns and return parameters of datatype packed decimal.

The total number of decimal digits in the result data item.

FMT-STATUS Regular columns only. One or more of the following symbolic values, added together:

CS-CANBENULL to indicate that the column can contain null values.

CS-NODATA to indicate that no data is associated with the column.



Comments

• CTBDESCRIBE returns a complete description of a result data item in the current result set. Result data items include regular result columns, return parameters, and stored procedure return status values.

• An application can call CTBRESINFO to find out how many result items are present in the current result set.

• An application generally needs to call CTBDESCRIBE to describe a result data item after it has established a connection and sent a request, and before it binds the result item to a program variable using CTBBIND.

FMT-COUNT Regular columns, return parameters, return status.

The number of rows copied to destination variables per CTBFETCH call. CTBDESCRIBE initializes FMT-COUNT as 1 to provide a default value in case an application uses CTBDESCRIBE’s return DATAFMT structure as CTBBIND’s input DATAFMT structure.

This value will always be 1 for return parameters and status results.

FMT-UTYPE Regular columns, return parameters. The user-defined datatype of the column or parameter (if any). USERTYP is set in addition to (not instead of) DATATYPE.

NOTE: This field is used for datatypes defined at the server, not for Open Client user-defined datatypes.

FMT-LOCALE Not used. n/a

Field name For which types of result items? CTBDESCRIBE sets the field to:



Example

This code fragment demonstrates the use of CTBDESCRIBE. It is taken from the sample program CLNT1, described in Appendix A.

*----------------------------------------------------------------* * Return a Description of a Piece of Datum of the Result Set * * ( CTBDESCR ) * *----------------------------------------------------------------* * INPUT: ( CL-INDEX = DATUM ITEM NUMBER ) * * OUTPUT ( DATA-FORMAT = RESULT DESCRIPTION STRUCTURE ) * *----------------------------------------------------------------* MOVE LOW-VALUE TO DATA-FORMAT.

CALL 'CTBDESCR' USING CL-COMMAND-HANDLE, CL-RETURN-CODE, CL-INDEX, DATA-FORMAT.

IF CL-RETURN-CODE NOT EQUAL CS-SUCCEED THEN MOVE ERR-U-CTBDESCR TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT PERFORM 9800-CLIENT-MSG THRU 9800-CLIENT-MSG-EXIT PERFORM 7000-TERMINATE THRU 7000-TERMINATE-EXIT END-IF. . . . .

*----------------------------------------------------------------* * Bind the Returned Data to a Program Variable * * ( CTBBIND ) * *----------------------------------------------------------------* * CALL 'CTBBIND' USING COMMAND-HANDLE, RETURN-CODE, ITEM-NUMBER, * * DATA-FORMAT-STRUCTURE, * * DESTINATION-VARIABLE, * * DATA-LENGTH, DATA-LENGTH-NULL, * * INDICATOR, INDICATOR-NULL. * *----------------------------------------------------------------*

MOVE 1 TO DF-COUNT.



IF PROCESSING-STATUS THEN CALL 'CTBBIND' USING CL-COMMAND-HANDLE, CL-RETURN-CODE, CL-INDEX, DATA-FORMAT, ST-STATUS, ST-LENGTH, CS-PARAM-NOTNULL, ST-NULLIND, CS-PARAM-NULL . . . .

Returns

CTBDESCRIBE returns one of the following values.

See Also

CTBBIND, CTBFETCH, CTBRESINFO, CTBRESULTS

Topics: DATAFMT Structure, Results

Value Meaning



CTBDESCRIBE returns CS-FAIL if ITEM-NUM does not represent a valid result data item.

3-70 CTBDIAG UniAccess for OS 2200 Client-Library Programming Reference


CTBDIAG

Purpose

Manage in-line error handling.

Syntax

COPY CTPUBLIC.01 CONNECTION COMP-2.01 RETCODE PIC S9(10) BINARY.01 COMPILER PIC S9(10) BINARY.01 OPERATION PIC S9(10) BINARY.01 MSGTYPE PIC S9(10) BINARY.01 INDEX PIC S9(10) BINARY.01 BUFFER type.

CALL 'CTBDIAG' USING CONNECTION, RETCODE, COMPILER, OPERATION MSGTYPE INDEX BUFFER.

Arguments



COMPILER — This argument is ignored.

OPERATION — (I) The operation to perform. The table under Summary of Arguments lists the symbolic values that are legal for OPERATION.

MSGTYPE — (I) The type of message or structure on which the operation is to be performed. Assign one of the following symbolic values.


Function Descriptions CTBDIAG 3-71

INDEX — (I) The index number of the message being retrieved. Messages are numbered sequentially: the first message has an index of 1, the second an index of 2, and so forth.

If TYP is CS-CLIENTMSG-TYPE, then INDEX refers to Client-Library messages only. If TYP is CS-SERVERMSG-TYPE, then INDEX refers to server messages only. If TYP is CS-ALLMSG-TYPE, then INDEX refers to Client-Library and server messages combined.

INDEX should be initialized to 1.

BUFFER — (I/O) An integer or a variable (buffer) that will contain the message. See the Summary of Arguments, below, to see the relationship between BUFFER and other arguments.



Summary of Arguments

The following table shows the action taken by CTBDIAG when it has been called using the specified argument OPERATION.

Value of MSGTYPE Indicates:

SQLCA-TYPE A SQLCA structure.

SQLSTATE-TYPE A SQLSTATE structure.

CS-CLIENTMSG-TYPE A CLIENTMSG structure.Used to indicate Client-Library messages.

CS-SERVERMSG-TYPE A SERVERMSG structure. Indicates messages sent by the a UniAccess System server.

CS-ALLMSG-TYPE Both Client-Library and server messages.



Table 3-5: Summary of Arguments (CTBDIAG)

Value of OPERATION

Action taken by CTBDIAG

Legal values for:

MSGTYPE INDEX BUFFER

CS-INIT Initializes in-line error handling.

An application must call CTBDIAG with a CS-INIT operation before it can process error messages in line.

CS-UNUSED CS-UNUSED Ignored.

CS-CLEAR Clears message information for this connection.

If BUFFER is not empty and MSGTYPE is not CS-ALLMSG-TYPE, then CTBDIAG clears the buffer by initializing it with blanks and/or zeroes.

One of the legal MSGTYPE values.

If MSGTYPE is CS-CLIENTMSG-TYPE, CTBDIAG clears Client-Library messages only.

If MSGTYPE is CS-SERVERMSG-TYPE, CTBDIAG clears server messages only.

If MSGTYPE has any other value, CTBDIAG clears both Client-Library and server messages.

CS-UNUSED A buffer whose type is defined by MSGTYPE.

CS-MSGLIMIT Sets the maximum number of messages to store.

CS-CLIENTMSG-TYPE to limit Client-Library messages only.

CS-SERVERMSG-TYPE to limit server messages only.

CS-ALLMSG-TYPE to limit the total number of Client-Library and server messages combined.

CS-UNUSED An integer value.



CS-GET Retrieves a specific message.

Any legal MSGTYPE value except CS-ALLMSG-TYPE.

If MSGTYPE is CS-CLIENTMSG-TYPE,a Client-Library message is retrieved into a CLIENTMSG structure.

If MSGTYPE is CS-SERVERMSG-TYPE, a server message is retrieved into a SERVERMSG structure.

If MSGTYPE has any other value, then either a Client-Library or server message is retrieved.

The index number of the message to retrieve.

A buffer whose type is defined by MSGTYPE.

CS-STATUS Returns the current number of stored messages.

CS-CLIENTMSG-TYPE to retrieve the number of Client-Library messages.

CS-SERVERMSG-TYPE to retrieve the number of server messages.

CS-ALLMSG-TYPE to retrieve the total number of Client-Library and server messages combined.

CS-UNUSED An integer variable.

Value of OPERATION

Action taken by CTBDIAG

Legal values for:

MSGTYPE INDEX BUFFER



Comments

• CTBDIAG manages in-line message handling for a specific connection. If an application has more than one connection, it must make separate CTBDIAG calls for each connection.

• Client-Library applications always use CTBDIAG to handle Client-Library and server messages.

• An application can perform operations on Client-Library messages, server messages, or both.

For example, an application can clear Client-Library messages without affecting server messages:

CALL 'CTBDIAG' USING CONHANDLE RETCODE CS-UNUSED CS-CLEAR CS-CLIENTMSG CS-UNUSED MSGBUFFER.

• CTBDIAG allows an application to retrieve message information into standard Client-Library structures (CLIENTMSG and SERVERMSG), a SQLCA or SQLCODE structure.

When CTBDIAG retrieves messages, it assumes that BUFFER points to a structure of the type indicated by MSGTYPE.

— An application that is retrieving messages into a SQLCA or SQLCODE structure must set the Client-Library property CS-EXTRA-INF to CS-TRUE. This is because the SQL structures require information that is not ordinarily returned by Client-Library’s error handling mechanism.

— An application that is not using the SQLCA structure can also set CS-EXTRA-INF to CS-TRUE. In this case, the extra information is returned as standard Client-Library messages.

For more about CS-EXTRA-INF, see Properties on page 2-33 CTBCONPROPS on page 3-58, and CSBCONFIG on page 3-134.



• If CTBDIAG does not have sufficient internal storage space in which to save a new message, it throws away all unread messages and stops saving messages. The next time it is called with OPERATION as CS-GET, it returns a message to indicate the space problem. After returning this message, CTBDIAG starts saving messages again.

Initializing In-Line Error Handling

• An application must initialize in-line error handling before it can retrieve any errors. To initialize in-line error handling, call CTBDIAG with OPERATION as CS-INIT.

• Generally, if a connection will use in-line error handling, the application should call CTBDIAG to initialize in-line error handling for a connection immediately after allocating it with CTBCONALLOC.

Clearing Messages

• To clear message information for a connection, an application calls OPERATION as CS-CLEAR.

— To clear Client-Library messages only, set MSGTYPE to CS-CLIENTMSG-TYPE.

— To clear server messages only, set MSGTYPE to CS-SERVERMSG-TYPE.

— To clear both Client-Library and server messages, set MSGTYPE to SQLCA, SQLCODE, or CS-ALLMSG-TYPE.

• If OPERATION is CS-CLEAR and MSGTYPE is not CS-ALLMSG-TYPE:

— CTBDIAG assumes that BUFFER is a structure of type MSGTYPE.

— CTBDIAG clears the buffer by setting it to blanks and/or NULLs, as appropriate.



• Message information is not cleared until an application explicitly calls CTBDIAG with OPERATION as CS-CLEAR. Retrieving a message does not remove it from the message queue.

Retrieving Messages

• To retrieve message information, an application calls CTBDIAG with the following, as appropriate: OPERATION as CS-GET, MSGTYPE as the type of structure in which to retrieve the message, INDEX as the index number of the message of interest, and BUFFER as an integer or a variable.

• If MSGTYPE is CS-CLIENTMSG-TYPE, then INDEX refers only to Client-Library messages. If MSGTYPE is CS-SERVERMSG-TYPE, INDEX refers only to server messages. If MSGTYPE has any other value, INDEX refers to the collective queue of both types of messages combined.

• CTBDIAG creates a messages queue in the buffer and fills the buffer with message information. It returns messages to the client in the order in which they are received.

• If an application attempts to retrieve a message whose index is higher than the highest valid index, CTBDIAG returns CS-NOMSG to indicate that no message is available.

Limiting Messages

By default, UniAccess Client-Library saves an unlimited number of messages. However, applications running on platforms with limited memory may want to limit the number of messages that Client-Library saves.

• An application can limit the number of saved Client-Library messages, the number of saved server messages, and the total number of saved messages.

• To limit the number of saved messages, an application calls CTBDIAG with OPERATION as CS-MSGLIMIT and with MSGTYPE as CS-CLIENTMSG-TYPE, CS-SERVERMSG-TYPE, or CS-ALLMSG-TYPE:



— If MSGTYPE is CS-CLIENTMSG-TYPE, then the number of Client-Library messages is limited.

— If MSGTYPE is CS-SERVERMSG-TYPE, then the number of server messages is limited.

— If MSGTYPE is CS-ALLMSG-TYPE, then the total number of Client-Library and server messages combined is limited.

• When a specific message limit is reached, Client-Library discards any new messages of that type. When a combined message limit is reached, Client-Library discards any new messages.

Retrieving the Number of Messages

• To find out how many messages have been retrieved (are in the queue), an application calls CTBDIAG with OPERATION as CS-STATUS and MSGTYPE as the type of message of interest.

Example 1

The following example uses CTBDIAG to prepare for receiving messages. This example is taken from the sample program CLNT1, described in Appendix A.

****************************************************************** * 1500-INIT-CS-MSGS * ****************************************************************** * Initialize the Retrieval of Client and Server Messages * * ( CTBDIAG ) * ****************************************************************** 1500-INIT-CS-MSGS.

*----------------------------------------------------------------* * CTBDIAG: OPERATION = CS-INIT * * MESSAGE TYPE = CS-ALLMSG-TYPE * *----------------------------------------------------------------* CALL 'CTBDIAG' USING CL-CONNECTION-HANDLE, CL-RETURN-CODE, CS-UNUSED, CS-INIT,



CS-ALLMSG-TYPE, CS-UNUSED, CS-UNUSED. IF CL-RETURN-CODE NOT EQUAL CS-SUCCEED THEN MOVE ERR-U-CTBDIAG-INIT TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT PERFORM 9800-CLIENT-MSG THRU 9800-CLIENT-MSG-EXIT PERFORM 7300-DROP-CONHANDLE THRU 7300-DROP-CONHANDLE-EXIT PERFORM 7400-EXIT-CLIENT THRU 7400-EXIT-CLIENT-EXIT PERFORM 7500-DROP-CTXHANDLE THRU 7500-DROP-CTXHANDLE-EXIT END-IF.

D DISPLAY 'CTBDIAG: C/S Message Retrieval Initialized' D UPON PRT.

*----------------------------------------------------------------* * Set the Maximum Number of Messages to Store (CTBDIAG ) * *----------------------------------------------------------------* * CTBDIAG: OPERATION = CS-MSGLIMIT * * MESSAGE TYPE = CS-ALLMSG-TYPE * *----------------------------------------------------------------* MOVE 5 TO PF-MSGLIMIT. CALL 'CTBDIAG' USING CL-CONNECTION-HANDLE, CL-RETURN-CODE, CS-UNUSED, CS-MSGLIMIT, CS-ALLMSG-TYPE, CS-UNUSED, PF-MSGLIMIT. IF CL-RETURN-CODE NOT EQUAL CS-SUCCEED THEN MOVE ERR-U-CTBDIAG-MSGLIM TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT PERFORM 9800-CLIENT-MSG THRU 9800-CLIENT-MSG-EXIT PERFORM 7300-DROP-CONHANDLE THRU 7300-DROP-CONHANDLE-EXIT PERFORM 7400-EXIT-CLIENT THRU 7400-EXIT-CLIENT-EXIT PERFORM 7500-DROP-CTXHANDLE THRU 7500-DROP-CTXHANDLE-EXIT END-IF. . . . .



Example 2

The following example uses CTBDIAG to process message results. This example is taken from the sample program CLNT1, described in Appendix A.

****************************************************************** * 9710-SL-STATUS * ****************************************************************** * Retrieve the Current Number of Stored Server Messages * * ( CTBDIAG ) * ****************************************************************** * CTBDIAG: OPERATION = CS-STATUS * * MESSAGE-TYPE = CS-SERVERMSG-TYPE * ****************************************************************** 9710-SL-STATUS.

MOVE ZEROS TO CL-RETURN-CODE, SL-NUM-OF-MSGS.

CALL 'CTBDIAG' USING CL-CONNECTION-HANDLE, CL-RETURN-CODE, CS-UNUSED, CS-STATUS, CS-SERVERMSG-TYPE, CS-UNUSED, SL-NUM-OF-MSGS.

D DISPLAY 'CTBDIAG: NUMBER OF SERVER MSGS: ', D SL-NUM-OF-MSGS UPON PRT.

IF CL-RETURN-CODE NOT EQUAL CS-SUCCEED THEN MOVE ERR-U-CTBDIAG-SL-STAT TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT ELSE IF SL-NUM-OF-MSGS = 0 THEN GO TO 9700-SERVER-MSG-EXIT END-IF

PERFORM 9720-SL-GET-MSG THRU 9720-SL-GET-MSG-EXIT VARYING SL-MSG-INDEX FROM 1 BY 1 UNTIL SL-MSG-INDEX IS GREATER THAN SL-NUM-OF-MSGS

PERFORM 9730-SL-CLEAR THRU 9730-SL-CLEAR-EXIT END-IF.



9710-SL-STATUS-EXIT. EXIT. ****************************************************************** * 9720-SL-GET-MSG * ****************************************************************** * Retrieve a Specific Message from the Server ( CTBDIAG ) * ****************************************************************** * CTBDIAG: OPERATION = CS-GET * * MESSAGE-INDEX = SL-MSG-INDEX * * MESSAGE-TYPE = CS-SERVERMSG-TYPE * * BUFFER = SERVER-MESSAGE STRUCTURE * ****************************************************************** 9720-SL-GET-MSG.

MOVE LOW-VALUES TO SERVER-MESSAGE. MOVE SPACES TO SM-TEXT, SM-SERVER-NAME, SM-SQLSTATE, SM-MSG-BUFFER.

CALL 'CTBDIAG' USING CL-CONNECTION-HANDLE, CL-RETURN-CODE, CS-UNUSED, CS-GET, CS-SERVERMSG-TYPE, SL-MSG-INDEX, SERVER-MESSAGE.

IF CL-RETURN-CODE NOT EQUAL CS-SUCCEED THEN MOVE ERR-U-CTBDIAG-SL-GET TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT PERFORM 9800-CLIENT-MSG THRU 9800-CLIENT-MSG-EXIT DISPLAY 'CTBDIAG: MSG INDEX = ', SL-MSG-INDEX UPON PRT PERFORM 7000-TERMINATE THRU 7000-TERMINATE-EXIT

ELSE

IF SM-MESSAGE-NUMBER IS NOT EQUAL +5701 THEN

MOVE SM-MESSAGE-NUMBER TO SM-MSG-NUM-EDITED

STRING SM-SERVER-NAME DELIMITED BY SPACE, ': ', SM-MSG-NUM-EDITED, ' - ', SM-TEXT DELIMITED BY FOUR-SPACES INTO SM-MSG-BUFFER



DISPLAY SM-LINE01 UPON PRT WITH NO ADVANCING DISPLAY SM-LINE02 UPON PRT WITH NO ADVANCING DISPLAY SM-LINE03 UPON PRT WITH NO ADVANCING DISPLAY SM-LINE04 UPON PRT WITH NO ADVANCING

END-IF

END-IF.

9720-SL-GET-MSG-EXIT. EXIT.

. . . .

Returns

CTBDIAG returns one of the following values.

Common reasons for a CTBDIAG failure include:

• Invalid CONNECTION

• Inability to allocate memory

• Invalid parameter (e.g., parameter is not allowed for operation)

• Invalid parameter combination.

Value Meaning



CS-NOMSG The application attempted to retrieve a message whose index number is greater than the number of messages in the queue. For example, the application attempted to retrieve message number 3, when there are only 2 messages queued.



See Also

CTBCONFIG, CSBCONFIG

Topics: Error and Message Handling, CLIENTMSG Structure, SERVERMSG Structure, SQLCA Structure, SQLCODE Structure


Function Descriptions CTBEXIT 3-83

CTBEXIT

Purpose

Exit UniAccess Client-Library.

Syntax

COPY CTPUBLIC.01 CONTEXT COMP-2.01 RETCODE PIC S9(10) BINARY.01 OPTION PIC S9(10) BINARY.

CALL 'CTBEXIT' USING CONTEXT, RETCODE, OPTION.

Arguments

CONTEXT — (I) A context handle. The context handle is defined in the program’s CSBCTXALLOC call. This value identifies the Client-Library context being exited.

If this value is invalid or NULL, CTBEXIT will fail.


OPTION — (I) The indicator specifying whether or not CTBEXIT will close connections for which results are pending.

CTBEXIT can function in different ways, depending on the value specified for OPTION. The following table lists the symbolic values that are legal for OPTION.

3-84 CTBEXIT UniAccess for OS 2200 Client-Library Programming Reference


Comments

• CTBEXIT terminates a UniAccess Client-Library context. It closes all open connections, de-allocates internal data space and cleans up any platform-specific initialization.

• CTBEXIT must be the last Client-Library function called within a Client-Library context.

• If an application finds it needs to call Client-Library functions after it has called CTBEXIT, it can re-initialize Client-Library by calling CTBINIT again.

• If results are pending on any of the context’s connections and OPTION is not passed as CS-FORCE-EXIT, CTBEXIT returns CS-FAIL. This means that Client-Library is not correctly terminated. The application must handle the pending results before calling CTBEXIT, or it may call CTBEXIT again, specifying CS-FORCE-EXIT.

• To close a single connection, an application calls CTBCLOSE.

• If CTBINIT is called for a context, the application must call CTBEXIT before it calls CSBCTXDROP to de-allocate the context.

Value of OPTION Action taken by CTBEXIT

CS-UNUSED CTBEXIT closes all open connections for which no results are pending and terminates Client-Library for this context. If results are pending on one or more connections, CTBEXIT returns CS-FAIL and does not terminate Client-Library.

CS-FORCE-EXIT CTBEXIT closes all open connections for this context, whether or not any results are pending, and terminates Client-Library for this context.



Example

The following code fragment demonstrates the use of CTBEXIT. It is taken from the sample program CLNT1, described in Appendix A.




CALL 'CTBCLOSE' USING CL-CONNECTION-HANDLE, CL-RETURN-CODE, CS-UNUSED. . . . .


CALL 'CTBCONDR' USING CL-CONNECTION-HANDLE, CL-RETURN-CODE. . .

3-86 CTBEXIT UniAccess for OS 2200 Client-Library Programming Reference


. . ****************************************************************** * 7400-EXIT-CLIENT * ****************************************************************** * Exit UniAccess Client Library ( CTBEXIT ) * ****************************************************************** 7400-EXIT-CLIENT.

CALL 'CTBEXIT' USING CL-CONTEXT-HANDLE, CL-RETURN-CODE, CS-UNUSED.

IF CL-RETURN-CODE NOT EQUAL CS-SUCCEED THEN MOVE ERR-U-CTBEXIT TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT CALL 'CTBEXIT' USING CL-CONTEXT-HANDLE, CL-RETURN-CODE, CS-FORCE-EXIT

IF CL-RETURN-CODE NOT EQUAL CS-SUCCEED THEN MOVE ERR-U-CTBEXIT-FORCE TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT END-IF END-IF. . . .





Returns

CTBEXIT returns one of the following values.

See Also

CTBCLOSE, CTBINIT

Value Meaning



3-88 CTBFETCH UniAccess for OS 2200 Client-Library Programming Reference


CTBFETCH

Purpose

Fetch result data.

Syntax

COPY CTPUBLIC.01 COMMAND COMP-2.01 RETCODE PIC S9(10) BINARY.01 TYP PIC S9(10) BINARY.01 OFFSET PIC S9(10) BINARY.01 OPTION PIC S9(10) BINARY.01 ROWS-READ PIC S9(10) BINARY.

CALL 'CTBFETCH' USING COMMAND, RETCODE, TYP, OFFSET, OPTION, ROWS-READ.

Arguments



TYP — (I) This argument is currently unused and should be passed as CS-UNUSED in order to ensure compatibility with future versions of UniAccess Client-Library.

OFFSET — (I) This argument is currently unused and should be passed as CS-UNUSED in order to ensure compatibility with future versions of UniAccess Client-Library.

OPTION — (I) This argument is currently unused and should be passed as CS-UNUSED in order to ensure compatibility with future versions of UniAccess Client-Library.


Function Descriptions CTBFETCH 3-89

ROWS-READ — (O) The variable in which the number of result rows is returned. This variable is an integer type. CTBFETCH sets ROWS-READ to the number of rows read by the CTBFETCH call. This argument is required.

Comments

• CTBFETCH fetches result data. Result data is an umbrella term for the various types of data that a server can return to an application. These types of data include:

— Regular rows.

— Return parameters, including both message parameters and RPC return parameters.

— Stored procedure status results.

CTBFETCH is used to fetch all of these types of data.

• Conceptually, result data is returned to an application in the form of one or more rows that make up a result set.

Regular row result sets can contain more than one row. For example, a regular row result set might contain a hundred rows. If array binding has been specified for the data items in a regular row result set, then multiple rows can be fetched with a single call to CTBFETCH. The number of rows fetched will be returned in the ROWS-READ argument.

Return parameters and status results, however, only contain a single row. For this reason, even if array binding is specified, only a single row of data is fetched.

• CTBRESULTS specifies the type of result available in the RESULT-TYP variable. CTBRESULTS must indicate a result type of CS-ROW-RESULT, CS-PARAM-RESULT, or CS-STATUS-RESULT before an application calls CTBFETCH.



• After calling CTBRESULTS, an application can:

— Process the result set by binding the result items and fetching the data, using CTBFETCH (optionally preceded by CTBDESCRIBE and CTBBIND).

or:

— Discard the result set, using CTBCANCEL.

• If an application does not cancel a result set, it must completely process the result set by repeatedly calling CTBFETCH as long as CTBFETCH continues to indicate that rows are available.

The simplest way to do this is in a loop that terminates when CTBFETCH fails to return either CS-SUCCEED or CS-ROW-FAIL. After the loop terminates, an application can check CTBFETCH’s final return code to find out what caused the termination.

Fetching Regular Rows

• Regular rows can be fetched from the server one row at a time or several rows at a time.

• When multiple rows are fetched, the number of rows to be fetched is indicated by the FMT-COUNT field in the DATAFMT structures used to bind the data items in the result set. Note that the FMT-COUNT field must have the same value for all CTBBIND calls for a result set.

If FMT-COUNT is 0 or 1, CTBFETCH fetches one row.

Fetching Return Parameters

• A return parameter result set contains either stored procedure return parameters or message parameters.

• A return parameter result set consists of a single row with a number of columns equal to the number of return parameters.



Fetching a Return Status

• A stored procedure return status result set consists of a single row with a single column, containing the status.

Example

The following example shows a typical use of CTBFETCH. It is taken from the sample program CLNT1, described in Appendix A.

****************************************************************** * 3400-FETCH * ****************************************************************** * FETCH Result Data into 'Binded' Program Variables ( CTBFETCH )* ****************************************************************** 3400-FETCH.

CALL 'CTBFETCH' USING CL-COMMAND-HANDLE, CL-RETURN-CODE, CS-UNUSED, CS-UNUSED, CS-UNUSED, FF-ROWS-READ.

D DISPLAY 'CTBFETCH: RETURN CODE: ', CL-RETURN-CODE UPON PRT. D DISPLAY '0=FAIL,1=SUCCEED,-203=ROW-FAIL,-204=END-DATA' D UPON PRT.


WHEN CS-SUCCEED MOVE 'Y' TO SW-FETCH MOVE 'Y' TO SW-DATA-FOUND

IF PROCESSING-DATA THEN PERFORM 3500-DISPLAY-RESULTS THRU 3500-DISPLAY-RESULTS-EXIT END-IF

D IF PROCESSING-STATUS THEN D DISPLAY 'PROCESSING STATUS: ', D ST-STATUS UPON PRT D END-IF



IF PROCESSING-RTPARM THEN DISPLAY 'Number of rows in the database = ', RT-NUMROWS UPON PRT END-IF

WHEN CS-END-DATA MOVE 'N' TO SW-FETCH

WHEN CS-FAIL MOVE 'N' TO SW-FETCH MOVE ERR-U-CTBFETCH TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT PERFORM 9600-CANCEL-COMMAND THRU 9600-CANCEL-COMMAND-EXIT PERFORM 9800-CLIENT-MSG THRU 9800-CLIENT-MSG-EXIT

WHEN CS-ROW-FAIL MOVE 'N' TO SW-FETCH MOVE ERR-U-CTBFETCH-ROW TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT DISPLAY ERROR-MSG UPON PRT PERFORM 9600-CANCEL-COMMAND THRU 9600-CANCEL-COMMAND-EXIT PERFORM 9800-CLIENT-MSG THRU 9800-CLIENT-MSG-EXIT WHEN CS-CANCELED MOVE 'N' TO SW-FETCH DISPLAY ' Result Set Canceled ' UPON PRT

WHEN OTHER MOVE 'N' TO SW-FETCH MOVE ERR-U-CTBFETCH-UNK TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT PERFORM 9600-CANCEL-COMMAND THRU 9600-CANCEL-COMMAND-EXIT PERFORM 9800-CLIENT-MSG THRU 9800-CLIENT-MSG-EXIT END-EVALUATE. 3400-FETCH-EXIT. EXIT.

. . . .



Returns

CTBFETCH returns one of the following values.

See Also

CTBBIND, CTBDESCRIBE, CTBRESULTS

Value Meaning


CTBFETCH places the total number of rows read in ROWS-READ.

CS-END-DATA No more rows are available in this result set. (Note that this is also a successful completion.)

CS-ROW-FAIL A recoverable error occurred while fetching a row.

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

An application can continue calling CTBFETCH to keep retrieving rows, or can call CTBCANCEL to cancel the remaining results.

CTBFETCH places the number of rows fetched before the error occurred in ROWS-READ, then continues by fetching the row after the error.


CTBFETCH places the number of rows fetched before the failure occurred in ROWS-READ.

A common reason for a CTBFETCH failure is that a program variable specified with CTBBIND is not large enough for a fetched data item.

CS-CANCELED The operation was canceled.

CTBFETCH places the number of rows fetched before the cancel occurred in ROWS-READ.

3-94 CTBGETFORMAT UniAccess for OS 2200 Client-Library Programming Reference


CTBGETFORMAT

Purpose

Return the user-defined format for a result column.

Syntax

COPY CTPUBLIC.01 COMMAND COMP-2.01 RETCODE PIC S9(10) BINARY.01 COLUMN-NUM PIC S9(10) BINARY.01 BUFFER type.01 BUFFER-LEN PIC S9(10) BINARY.01 OUTLEN PIC S9(10) BINARY.

CALL 'CTBGETFO' USING COMMAND, RETCODE, COLUMN-NUM,BUFFER, BUFFER-LEN, OUTLEN.

Arguments



COLUMN-NUM — (I) The number of the column whose user-specified format is desired.

COLUMN-NUM is the select-list ID of the column. The first column in a select statement’s select-list is column number 1, the second number 2, and so forth.

BUFFER — (O) The variable (buffer) in which CTBGETFORMAT will place the requested information.

This argument will usually be:

01 BUFFER PIC X(n).


Function Descriptions CTBGETFORMAT 3-95


If BUFFER-LEN is not large enough to hold the requested information, CTBGETFORMAT sets OUTLEN to the length of the requested information and returns CS-FAIL.

OUTLEN — (O) The length, in bytes, of the retrieved information. OUTLEN is an integer variable in which CTBGETFORMAT returns the total number of bytes being retrieved.

If the requested information is larger than BUFFER-LEN bytes, an application uses this value to determine how many bytes are needed to hold the information.

Comments

• CTBGETFORMAT returns the user-defined format for a result column. It indicates how the field should be formatted on screen.

• An application can call CTBGETFORMAT after CTBRESULTS indicates results of type CS-ROW-RESULT.

• For a description of how to add user-defined formats to SQL Server databases or Open Servers, see the SQL Server and Open Server documentation.

Returns

CTBGETFORMAT returns one of the following values.

See Also

CTBBIND, CTBDESCRIBE

Value Meaning



3-96 CTBINIT UniAccess for OS 2200 Client-Library Programming Reference


CTBINIT

Purpose

Initialize UniAccess Client-Library.

Syntax

COPY CTPUBLIC.01 CONTEXT COMP-2.01 RETCODE PIC S9(10) BINARY.01 VERSION PIC S9(10) BINARY.

CALL 'CTBINIT' USING CONTEXT, RETCODE, VERSION.

Arguments

CONTEXT — (I) A context handle. The context handle is defined in the program’s CSBCTXALLOC call. If this value is invalid, CTBINIT will fail.


VERSION — (I) The version of Client-Library behavior that the application has been programmed to accept. The following table lists the symbolic values that are legal for VERSION.

Value of VERSION Indicates: Features supported

CS-VERSION-100 10.0 behavior Remote procedures.

This is the initial version of UACL.

CS-VERSION-110 11.0 behavior Reduces overhead by not assigning the following language files unless they are needed to display error or warning messages: SYS$LIB$*ISO$1 (T) SYS$LIB$*ENGL$ISO-1 (T)


Function Descriptions CTBINIT 3-97

Comments

• CTBINIT initializes UniAccess Client-Library. It sets up internal control structures and defines the version of Client-Library behavior that an application expects. Client-Library will provide the requested behavior, regardless of the actual version of Client-Library in use.

• CTBINIT must be the first Client-Library function all after CSBCTXALLOC. Other Client-Library functions will fail if they are called before CTBINIT.

• Because an application calls CTBINIT before it sets up error handling, an application must check CTBINIT’s return code to detect failure.

• An application may call CTBINIT multiple times. Some applications cannot guarantee which of several modules will execute first. In such a case, each module should contain a call to CTBINIT.

• CS-VERSION-100 is always used with levels of UniAccess Client-Library prior to 10R1.

• CS-VERSION-110 may be used with UniAccess Client-Library levels 10R1 and later to reduce overhead. The overhead reduction is most notable when UniAccess Client-Library functions are used in a TIP transaction environment.

Example

The following code fragment demonstrates the use of CTBINIT. It is taken from the sample program CLNT1, described in Appendix A.


CALL 'CTBINIT' USING CL-CONTEXT-HANDLE, CL-RETURN-CODE, CS-VERSION-100.

3-98 CTBINIT UniAccess for OS 2200 Client-Library Programming Reference


IF CL-RETURN-CODE NOT EQUAL CS-SUCCEED THEN MOVE ERR-U-CTBINIT TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT PERFORM 7500-DROP-CTXHANDLE THRU 7500-DROP-CTXHANDLE-EXIT END-IF. . . . .

Returns

CTBINIT returns one of the following values.

See Also

CTBEXIT, CSBCTXALLOC

Value Meaning


CS-MEM-ERROR The routine failed due to a memory allocation error.

CS-FAIL The routine failed for other reasons.


Function Descriptions CTBPARAM 3-99

CTBPARAM

Purpose

Define a command parameter.

Syntax

COPY CTPUBLIC.01 COMMAND COMP-2.01 RETCODE PIC S9(10) BINARY.01 DATAFMT


01 DATA type 01 DATALEN PIC S9(10) BINARY.01 INDICATOR PIC S9(5) BINARY.

CALL 'CTBPARAM' USING COMMAND, RETCODE, DATAFMT, DATA, DATALEN, INDICATOR.

Arguments



3-100 CTBPARAM UniAccess for OS 2200 Client-Library Programming Reference


DATAFMT — (I) A structure that contains a description of the parameter. This structure is also used by CTBBIND, CTBDESCRIBE, and CTBCONVERT. See DATAFMT Structure on page 2-13.

The table below lists the fields in the DATAFMT structure, indicates if and when they are used by CTBPARAM, and contains general information about the fields. For specific information on how to set these fields when defining a parameter for a particular kind of command, see the tables in the Comments section for this function description.

Table 3-6: Fields in the DATAFMT Structure for CTBPARAM


FMT-NAME When defining parameters for all supported commands.

The name of the parameter being defined.

If FMT-NAMELEN is 0, the parameter is considered to be unnamed. Unnamed parameters are interpreted positionally. It is an error to mix named and unnamed parameters in a single command.

NOTE: To send parameters to a SQL Server, FMT-NAME must begin with the @ symbol, which prefixes all SQL Server stored procedure parameter names.

To send parameters with language requests, FMT-NAME must be the variable name as it appears in the language string. Transact-SQL names begin with the (:) symbol.

The programmer is responsible for adhering to these rules. Client-Library does not enforce them.

FMT-NAMELEN When defining parameters for all supported commands.

The length, in bytes, of FMT-NAME. If FMT-NAMELEN is 0, the parameter is considered to be unnamed.

FMT-TYPE When defining parameters for all supported commands.

The datatype of the parameter value. All datatypes listed under Datatypes on page 2-18 are valid.

FMT-FORMAT Not used. n/a



FMT-MAXLEN When defining non-fixed-length return parameters for RPCs; otherwise CS-UNUSED.

The maximum length, in bytes, of the return parameter data sent by the server.

For character or binary data, FMT-MAXLEN must represent the total length of the return parameter, including any space required for special terminating bytes, with this exception: when the parameter is a VARYCHAR datatype, FMT-MAXLEN does not include the length of the ‘LL’ length specification.

Set FMT-MAXLEN to CS-UNUSED if the parameter is non-return, if FMT-TYPE is fixed-length, or if the application does not need to restrict the length of return parameters.

FMT-SCALE If datatype is PACKEDEC. If CTBPARAM is called with a PACKEDEC datatype, Client-Library automatically converts it to a NUMERIC datatype before sending it to a server.

FMT-PRECIS If datatype is PACKEDEC. If CTBPARAM is called with a PACKEDEC datatype, Client-Library automatically converts it to a NUMERIC datatype before sending it a server.

FMT-STATUS When defining parameters for all types of commands except message commands.

The type of parameter being defined. Legal values for FMT-STATUS are:

CS-INPUTVALUE — The parameter is an input parameter value for a non-return RPC parameter.

CS-RETURN — The parameter is a return parameter to an RPC command.

FMT-COUNT Not used. n/a

FMT-UTYPE Not used. n/a

FMT-LOCALE Not used. n/a.




DATA — (I) The variable that contains the parameter’s data.

To indicate a parameter with a null value, assign INDICATOR a value of -1.

If INDICATOR is -1, DATA and DATA-LEN are ignored. For example, an application might pass parameters with null values to a stored procedure or transaction that assigns default values to null input parameters.

DATA-LEN — (I) The length, in bytes, of the parameter data.

INDICATOR — (I) An integer variable used to indicate a parameter with a null value. To indicate a parameter with a null value, assign INDICATOR a value of -1. If INDICATOR is -1, DATA and DATA-LEN are ignored.


The following table shows how CTBPARAM uses the value of the argument FMT-STATUS to determine whether the parameter is a return parameter or not, and how CTBPARAM interprets the DATA and DATA-LEN arguments.

Table 3-7: Summary of Arguments (CTBPARAM)

Comments

• An application can call a stored procedure or transaction in two ways: (1) by sending a language request or (2) by issuing an RPC. See Remote Procedure Calls on page 2-43 for a discussion of the differences between these techniques.

.• An application calls CTBCOMMAND to initiate a language request, RPC or

message command.

Type of command: FMT-STATUS is: DATA, DATA-LEN are:

RPC return parameter CS-RETURN The parameter value and length.

RPC non-return parameter CS-INPUTVALUE The parameter value and length.



• CTBPARAM defines parameters for both language requests and RPCs.

• An application calls CTBPARAM once for each parameter that is sent with the current RPC or language request. It describes each parameter. That description is forwarded to the procedure or transaction called.

.• Language requests require input parameters when the text of the language

request contains host variables.

• Parameters must be described by CTBPARAM in the same order in which they will be sent to server. The first CTBPARAM call describes the first parameter, the second CTBPARAM call describes the second parameter, etc., until all parameters have been described and sent.

Defining Arguments for Language Commands

• An application calls CTBPARAM with FMT-STATUS as CS-INPUTVALUE to define a parameter value for a language command containing variables.

• A language command can have up to 255 parameters.

• The following fields in the DATAFMT structure take special values when describing a parameter for a language request.

Table 3-8: DATAFMT Fields for Language Request Parameterswith CTBPARAM

Field name: Set the field to:

NAME The variable name as it appears in the language string. Transact-SQL names begin with the (:) symbol.

FMT-STATUS CS-INPUTVALUE

All other fields Take standard CTBPARAM values.



Defining Arguments for RPCs

• An application calls CTBPARAM with FMT-STATUS as CS-RETURN to define a return parameter for an RPC, and calls CTBPARAM with FMT-STATUS as CS-INPUTVALUE to define a non-return parameter.

• To send an RPC, a Client-Library application:

— Calls CTBCOMMAND to initiate the request.

— Calls CTBPARAM once for each parameter that is being passed to the remote procedure.

— Calls CTBSEND to send the request to the server. One CTBSEND forwards the RPC with all defined parameters; the application does not call CTBSEND separately for each parameter.

• An RPC can have up to 255 parameters.

• The following fields in the DATAFMT structure take special values when describing an RPC parameter.

Table 3-9: DATAFMT Fields for RPC Parameters with CTBPARAM

Field name: Set the field to:

FMT-NAME When parameters are being sent to a SQL Server, FMT-NAME must begin with the @ symbol, which prefixes all SQL Server stored procedure parameter names.

FMT-MAXLEN The maximum length of data to be returned by the server.

Set to CS-UNUSED if the parameter is non-return, if FMT-TYPE is fixed-length, or if the application does not need to restrict the length of return parameters.

FMT-STATUS CS-RETURN to indicate that the parameter is a return parameter.

CS-INPUTVALUE to indicate that the parameter is not a return parameter.

All other fields Take standard CTBPARAM values.



Example

The following code fragment demonstrates the use of CTBPARAM. It is taken from the sample program CLNT1, described in Appendix A.

*----------------------------------------------------------------* * Initiate the Remote Procedure Call ( CTBCOMMA ) * *----------------------------------------------------------------* * REQUEST-TYPE = CS-RPC-CMD (FOR REMOTE PROCEDURE CALL) * * REQUEST-BUFFER = NAME OF REMOTE PROCEDURE CALL * * BUFFER-LENGTH = LENGTH OF NAME OF REMOTE PROCEDURE CALL * *----------------------------------------------------------------* MOVE CF-RPC-SIZE TO PF-STRLEN. CALL 'CTBCOMMA' USING CL-COMMAND-HANDLE, CL-RETURN-CODE, CS-RPC-CMD, CF-RPC, PF-STRLEN, CS-UNUSED. IF CL-RETURN-CODE NOT EQUAL CS-SUCCEED THEN MOVE ERR-U-CTBCOMMA TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT PERFORM 9800-CLIENT-MSG THRU 9800-CLIENT-MSG-EXIT PERFORM 7000-TERMINATE THRU 7000-TERMINATE-EXIT END-IF. D DISPLAY 'CTBCOMMA: RPC Command Initiated' UPON PRT.

*----------------------------------------------------------------* * Define each Parameter to be sent to Server ( CTBPARAM ) * *----------------------------------------------------------------* *----------------------------------------------------------------* * Define Input Parameter: FIRST-NAME * * ( DF-STATUS OF DATA-FORMAT = CS-INPUTVALUE ) * *----------------------------------------------------------------* MOVE CL-PARM-NAME OF FIRST-NAME-PARM TO DF-NAME. MOVE CL-PARM-NAME-LEN OF FIRST-NAME-PARM TO DF-NAME-LENGTH . MOVE CS-INPUTVALUE TO DF-STATUS. MOVE CS-CHAR-TYPE TO DF-DATATYPE. MOVE CS-UNUSED TO DF-MAX-LENGTH.



CALL 'CTBPARAM' USING CL-COMMAND-HANDLE, CL-RETURN-CODE, DATA-FORMAT, CL-PARM-DATA OF FIRST-NAME-PARM, CL-PARM-LEN OF FIRST-NAME-PARM, INDICATOR.

IF CL-RETURN-CODE NOT EQUAL CS-SUCCEED THEN MOVE ERR-U-CTBPARAM-FNAME TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT PERFORM 9800-CLIENT-MSG THRU 9800-CLIENT-MSG-EXIT PERFORM 7000-TERMINATE THRU 7000-TERMINATE-EXIT END-IF.

D DISPLAY 'CTBPARAM: @first_name Parameter Defined' UPON PRT.

*----------------------------------------------------------------* * Define Input Parameter: LAST-NAME * * ( DF-STATUS OF DATA-FORMAT = CS-INPUTVALUE ) * *----------------------------------------------------------------* MOVE CL-PARM-NAME OF LAST-NAME-PARM TO DF-NAME. MOVE CL-PARM-NAME-LEN OF LAST-NAME-PARM TO DF-NAME-LENGTH. MOVE CS-INPUTVALUE TO DF-STATUS. MOVE CS-CHAR-TYPE TO DF-DATATYPE. MOVE CS-UNUSED TO DF-MAX-LENGTH.

CALL 'CTBPARAM' USING CL-COMMAND-HANDLE, CL-RETURN-CODE, DATA-FORMAT, CL-PARM-DATA OF LAST-NAME-PARM, CL-PARM-LEN OF LAST-NAME-PARM, INDICATOR.

IF CL-RETURN-CODE NOT EQUAL CS-SUCCEED THEN MOVE ERR-U-CTBPARAM-LNAME TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT PERFORM 9800-CLIENT-MSG THRU 9800-CLIENT-MSG-EXIT PERFORM 7000-TERMINATE THRU 7000-TERMINATE-EXIT END-IF.

D DISPLAY 'CTBPARAM: @last_name Parameter Defined' UPON PRT.



*----------------------------------------------------------------* * Define Return Parameter: RT-NUMROWS * * ( DF-STATUS OF DATA-FORMAT = CS-RETURN ) * * RT-NUMROWS will = the number of rows in the database * *----------------------------------------------------------------* MOVE '@row_count' TO DF-NAME. MOVE 10 TO DF-NAME-LENGTH . MOVE CS-RETURN TO DF-STATUS. MOVE CS-INT-TYPE TO DF-DATATYPE. MOVE CS-UNUSED TO DF-MAX-LENGTH. CALL 'CTBPARAM' USING CL-COMMAND-HANDLE, CL-RETURN-CODE, DATA-FORMAT, RT-NUMROWS, RT-NUMROWS-SIZE, INDICATOR.

IF CL-RETURN-CODE NOT EQUAL CS-SUCCEED THEN MOVE ERR-U-CTBPARAM-RTPARM TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT PERFORM 9800-CLIENT-MSG THRU 9800-CLIENT-MSG-EXIT PERFORM 7000-TERMINATE THRU 7000-TERMINATE-EXIT END-IF.

D DISPLAY 'CTBPARAM: @row_count Parameter Defined' UPON PRT.

*----------------------------------------------------------------* * Send the Remote Procedure Request ( CTBSEND ) * *----------------------------------------------------------------* CALL 'CTBSEND' USING CL-COMMAND-HANDLE, CL-RETURN-CODE. . . . .



Returns

CTBPARAM returns one of the following values.

See Also

CTBCOMMAND, CTBSEND

Value Meaning




Function Descriptions CTBREMOTEPWD 3-109

3 Function DescriptionsCTBREMOTEPWD

Purpose

Define or clear passwords to be used for server-to-server connections.

Syntax

COPY CTPUBLIC01 CONNECTION COMP-2.01 RETCODE PIC S9(10) BINARY.01 ACTION PIC S9(10) BINARY.01 SERVERNAME PIC X(30).01 SRV-LEN PIC S9(10) BINARY.01 SRV-BLANKSTRIP PIC S9(10) BINARY.01 PASSWD PIC X(30).01 PWD-LEN PIC S9(10) BINARY.01 PWD-BLANKSTRIP PIC S9(10) BINARY.

CALL 'CTBREMOT' USING CONNECTION, RETCODE, ACTION, SERVERNAME, SRV-LEN, SRV-BLANKSTRIP, PASSWD, PWD-LEN, PWD-BLANKSTRIP.

Arguments


Remote passwords can only be defined for a connection that has not yet been opened. Passwords defined after a connection is open are ignored.



3-110 CTBREMOTEPWD UniAccess for OS 2200 Client-Library Programming Reference


ACTION can be any of the following symbolic values.

SERVERNAME — (I) The name of the server for which the password is being defined.

If ACTION is CS-CLEAR, SERVERNAME will default to LOW-VALUES.

If SERVERNAME is LOW-VALUES, the specified password will be considered a universal password, to be used with any server that does not have a password explicitly specified for it.

SERVERNAME-LEN — (I) The length, in bytes, of SERVERNAME. To use the default universal password, assign CS-NULL-STRING to this argument. To indicate that the value is terminated at the last non-blank character, assign CS-TRUE to SRV-BLANKSTRIP.

SRV-BLANKSTRIP — (I) The blank termination indicator. Indicates whether or not the value in the buffer is terminated at the last non-blank character.


PASSWD — (I) The password being installed for remote logins to the server named in SERVERNAME.

If ACTION is CS-CLEAR, PASSWD is passed as LOW-VALUES, and the password defaults to the one set for this connection in CTBCONPROPS (if any).

Value of ACTION Action taken by CTBREMOTEPWD

CS-SET Sets the remote password.

CS-CLEAR Clears all remote passwords specified for this connection by assigning LOW-VALUES to SERVERNAME and PASSWD.

Value of SRV-BLANKSTRIP Indicates:

CS-TRUE Value in the buffer ends at the last non-blank character.

CS-FALSE Value in the buffer does not end at the last non-blank character.



PDW-LEN — (I) The length, in bytes, of PASSWD. To indicate that the value is terminated at the last non-blank character, assign CS-TRUE to PWD-BLANKSTRIP.

PWD-BLANKSTRIP — (I) The blank termination indicator. Indicates whether or not the value of the password is terminated at the last non-blank character.


Comments

• CTBREMOTEPWD defines the password that a server will use when logging into another server.

• A language command, stored procedure, or transaction running on one server can call a stored procedure or transaction located on another server. To accomplish this server-to-server communication, the first server, to which an application has connected using CTBCONNECT, actually logs into the second, a remote server, performing a server-to-server remote procedure call.

CTBREMOTEPWD allows an application to specify the password to be used when the first server logs into the remote server.

• Multiple passwords may be specified, one for each server that the first server might need to log into. Each password must be defined with a separate call to CTBREMOTEPWD.

• If an application does not specify a remote password for a particular server, the password defaults to the password set for this connection by CTBCONPROPS (if any). If no password has been defined, the password is set to null (LOW-VALUES). If an application user generally has the same password on different servers, this default setting may be sufficient.

Value of PWD-BLANKSTRIP Indicates:

CS-TRUE Value in the buffer ends at the last non-blank character.

CS-FALSE Value in the buffer does not end at the last non-blank character.



• Remote passwords are stored in an internal buffer that is only 255 bytes long. Each password’s entry in the buffer consists of the password itself, the associated server name, and two extra bytes. If the addition of a password to this buffer would cause overflow, CTBREMOTEPWD returns CS-FAIL and generates a Client-Library error message that indicates the problem.

• Remote passwords should be defined before calling CTBCONNECT to create an active connection. It is an error to call CTBREMOTEPWD to define a remote password for a connection that is already open.

• An application can call CTBREMOTEPWD to clear remote passwords for a connection at any time.

Example

The following code fragment demonstrates the use of CTBREMOTEPWD. This sample is not part of any sample program, so the WORKING STORAGE section is included here.

WORKING-STORAGE SECTION . COPY CTPUBLIC .

01 CS-LIB-MISC-FIELDS . 05 CSL-CTX-HANDLE COMP-2 VALUE +0 . 05 CSL-CON-HANDLE COMP-2 VALUE +0 . 05 CSL-CMD-HANDLE COMP-2 VALUE +0 . 05 CSL-RC PIC S9(10) USAGE BINARY . 05 CSL-NULL PIC S9(10) BINARY VALUE +0 .

01 PF-USER PIC X(12) VALUE 'user1234' . 01 PF-PWD PIC X(08) VALUE '111111' . 01 PF-SERVER PIC X(08) VALUE 'SYBASE10' . 01 PF-APPNAME PIC X(08) VALUE 'UACL' . 01 PF-USER-SIZE PIC S9(10) BINARY VALUE +8 . 01 PF-PWD-SIZE PIC S9(10) BINARY VALUE +6 . 01 PF-SERVER-SIZE PIC S9(10) BINARY VALUE +8 . 01 PF-APPNAME-SIZE PIC S9(10) BINARY VALUE +4 . 01 PF-OUTLEN PIC S9(10) BINARY VALUE +0 . 01 PF-STRLEN PIC S9(10) BINARY VALUE +0 . 01 PF-MSGLIMIT PIC S9(10) BINARY VALUE +0 .



* * Remote Server related storage * 01 PF-REM-SERVER PIC X(30) . 01 PF-REM-SERVER-LEN PIC S9(10) BINARY VALUE +0 . 01 PF-REM-PWD PIC X(30) . 01 PF-REM-PWD-LEN PIC S9(10) BINARY VALUE +0 . * * Fire up a remote passwd call * MOVE LOW-VALUES TO PF-REM-SERVER . STRING 'SYBASE3' DELIMITED BY SIZE INTO PF-REM-SERVER . MOVE 7 TO PF-REM-SERVER-LEN . MOVE LOW-VALUES TO PF-REM-PWD . STRING '111111' DELIMITED BY SIZE INTO PF-REM-PWD . MOVE 6 TO PF-REM-PWD-LEN . DISPLAY PF-REM-SERVER UPON PRINTER . DISPLAY PF-REM-PWD UPON PRINTER .

CALL 'CTBREMOT' USING CSL-CON-HANDLE, CSL-RC, CS-SET, PF-REM-SERVER, PF-REM-SERVER-LEN, CS-FALSE, PF-REM-PWD, PF-REM-PWD-LEN, CS-FALSE .

IF CSL-RC NOT EQUAL CS-SUCCEED THEN MOVE " Error in CTBREMOT" TO ERROR-TEXT MOVE CSL-RC TO ERROR-RC PERFORM ERROR-OUT PERFORM DONE-PARA END-IF . * * Open connection to the server .................. * MOVE PF-SERVER-SIZE TO PF-STRLEN . CALL 'CTBCONNE' USING CSL-CON-HANDLE, CSL-RC, PF-SERVER, PF-STRLEN, CS-FALSE .



Returns

CTBREMOTEPWD returns one of the following values.

See Also

CTBCONNECT, CTBCONPROPS

Value Meaning

CS-SUCCEED Results are available for processing.



Function Descriptions CTBRESINFO 3-115

CTBRESINFO

Purpose

Return result set information.

Syntax

COPY CTPUBLIC.01 COMMAND COMP-2.01 RETCODE PIC S9(10) BINARY.01 RESULT-TYP PIC S9(10) BINARY.01 BUFFER type.01 BUFFER-LEN PIC S9(10) BINARY.01 OUTLEN PIC S9(10) BINARY.

CALL 'CTBRESIN' USING COMMAND, RETCODE, RESULT-TYP, BUFFER, BUFFER-LEN, OUTLEN.

Arguments


RETCODE — (O) The variable in which the result of function execution is returned. Its

value is one of the codes listed under Returns below.

RESULT-TYP — (I) The type of information to return. The table under Summary of Arguments lists the symbolic values that are legal for RESULT-TYP.

BUFFER — (O) The variable (buffer) in which CTBRESINFO returns the requested information.



3-116 CTBRESINFO UniAccess for OS 2200 Client-Library Programming Reference


BUFFER-LEN — (I) The length, in bytes, of the buffer.If the returned value is longer than BUFFER-LEN, CTBRESINFO will set OUTLEN to the length of the requested information and return CS-FAIL.

OUTLEN — (O) The length, in bytes, of the retrieved information. OUTLEN is an integer variable in which CTBRESINFO returns the length of the information being retrieved.

If the retrieved information is larger than BUFFER-LEN bytes, an application uses the value of OUTLEN to determine how many bytes are needed to hold the information.


After CTBRESULTS indicates that results are present, the following information is returned to BUFFER by CTBRESINFO, based on the argument RESULT-TYP.

Table 3-10: Summary of Arguments (CTBRESINFO)

Value of RESULT-TYP

Action taken by CTBRESINFO

The information is available after CTRESULTS sets its result_type parameter to:

BUFFER is:

CS-CMD-NUMBER Returns the number of the command that generated the current result set.

Any value. An integer value.

CS-NUMDATA Returns the number of items in the current result set.

CS-COMPUTE-RESULT,CS-COMPUTEFMT-RESULT,CS-CURSOR-RESULT,CS-DESCRIBE-RESULT,CS-PARAM-RESULT,CS-ROW-RESULT,CS-ROWFMT-RESULT,CS-STATUS-RESULT

An integer value.

CS-ROW-COUNT Returns the number of rows affected by the current command.

CS-CMD-DONE,CS-CMD-FAIL,CS-CMD-SUCCEED

An integer value.



Comments

• CTBRESINFO returns information about the current result set or the current command. The current command is the request that generated the current result set.

• A result set is a collection of a single type of result data. Result sets are generated by commands. For more information on result sets, see the CTBRESULTS function description and Results on page 3-122.

• Most typically, an application calls CTBRESINFO with type as CS-NUMDATA, to determine the number of items in a result set.

Retrieving the Command Number for the Current Result Set

• To determine the number of the command that generated the current result set, call CTBRESINFO with RESULT-TYP as CS-CMD-NUMBER.

• UniAccess Client-Library keeps track of the command number by counting the number of times CTBRESULTS returns CS-CMD-DONE.

An application’s first call to CTBRESULTS following a CTBSEND call sets the command number to 1. The command number remains 1 until CTBRESULTS returns CS-CMD-DONE. The next time the application calls CTBRESULTS, the command number is incremented to 2. The command number continues to be incremented each time CTBRESULTS is called after returning CS-CMD-DONE.

• CS-CMD-NUMBER is useful in the following cases:

— To find out which command within a language request generated the current result set.

— To find out which select command in a stored procedure or transaction generated the current result set.

• A language request contains a string of text. This text represents one or more SQL commands or other language request statements. If the application is sending a language request, command number refers to the number of the statement in the language request.



For example, the Transact-SQL string:

select * from authorsselect * from titlesinsert newauthorsselect *from authorswhere city = "San Francisco"

represents three Transact-SQL commands—two selects and one insert. The two select statements can generate result sets. In this case, the command number that CTBRESINFO returns can be from 1 to 3, depending on when CTBRESINFO is called.

NoteWhen you send SQL strings to UniAccess Relational Service, remember to use semicolons to separate SQL statements.

• Within stored procedure or transactions, only select statements cause the command number to be incremented. For example, if a stored procedure or transaction contains seven SQL commands, three of which are selects, the command number that CTBRESINFO returns can be any integer from 1 to 3, depending on which select generated the current result set.

Retrieving the Number of Result Data Items

• To determine the number of result data items in the current result set, call CTBRESINFO with RESULT-TYP as CS-NUMDATA.

• Results sets contain result data items: a row result set contains columns; a parameter result set contains parameters; and a status result set contains a status. The columns, parameters, and status are known as result data items.

Retrieving the Number of Rows for the Current Command

• To determine the number of rows affected by the current command, call CTBRESINFO with RESULT-TYP as CS-ROW-COUNT.



• If the current command does not return rows—for example, a language command containing an insert statement—an application can get the row count immediately after CTBRESULTS returns CS-CMD-SUCCEED.

• If the current command does return rows:

— An application can get a total row count after processing all the rows.

— An application can get an intermediate row count any time after CTBRESULTS indicates that results are available. An intermediate row count is equivalent to the number of rows fetched that have been fetched so far.

• If the command executes a stored procedure or transaction—for example a Transact-SQL exec language command or a remote procedure call—CTBRESINFO returns either of the following:

— The number of rows returned by the latest select statement executed by the stored procedure or transaction

— The CS-NO-COUNT if the stored procedure or transaction does not execute any select statements.

Note that a stored procedure or transaction that contains no select statements may execute a select by calling another stored procedure or transaction that contains a select.

• CTBRESINFO returns CS-NO-COUNT if any of the following are true:

— The command fails for any reason, such as a syntax error.

— The command never affects rows, such as a Transact-SQL print command.

— The command executes a stored procedure or transaction that does not execute any select statements.



Example

The following code fragment demonstrates the use of CTBRESINFO. It is taken from the sample program CLNT1, described in Appendix A.

****************************************************************** * 3200-PROCESS-ROW * ****************************************************************** * Return the Number of Items in the Current Result Set * * ( CTBRESIN ) * ****************************************************************** * SET RESULT-TYPE = CS-NUMDATA. REQ THE # OF ITEMS IN RESULT SET * * RETURN: RF-NUMDATA = THE NUMBER OF ITEMS IN THE RESULT SET * ****************************************************************** 3200-PROCESS-ROW.

CALL 'CTBRESIN' USING CL-COMMAND-HANDLE, CL-RETURN-CODE, CS-NUMDATA, RF-NUMDATA, RF-NUMDATA-SIZE, CTBRESIN-LENGTH.

IF CL-RETURN-CODE NOT EQUAL CS-SUCCEED THEN MOVE ERR-U-CTBRESIN TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT PERFORM 9800-CLIENT-MSG THRU 9800-CLIENT-MSG-EXIT PERFORM 7000-TERMINATE THRU 7000-TERMINATE-EXIT END-IF.

PERFORM 3300-BIND-COLUMNS THRU 3300-BIND-COLUMNS-EXIT VARYING CL-INDEX FROM 1 BY 1 UNTIL CL-INDEX IS GREATER THAN RF-NUMDATA.

3200-PROCESS-ROW-EXIT. EXIT . . . . .



Returns

CTBRESINFO returns one of the following values.

See Also

CTBCMDPROPS, CTBCONPROPS, CTBRESULTS

Topics: Results

Value Meaning

CS-SUCCEED Results are available for processing.


CTBRESINFO returns CS-FAIL if the requested information is larger than BUFFER-LEN bytes.

3-122 CTBRESULTS UniAccess for OS 2200 Client-Library Programming Reference


CTBRESULTS

Purpose

Sets up result data to be processed.

Syntax

COPY CTPUBLIC.01 COMMAND COMP-2.01 RETCODE PIC S9(10) BINARY.01 RESULT-TYP PIC S9(10) BINARY.

CALL 'CTBRESUL' USING COMMAND, RETCODE, RESULT-TYP.

Arguments



RESULT-TYP — (O) The variable containing the result type. CTBRESULTS returns to this variable a symbolic value that indicates the type of result returned by the current request.

The result type can be any of the symbolic values in the list that follows.


Function Descriptions CTBRESULTS 3-123

Comments

• CTBRESULTS tells the application what kind of results have been returned and sets up result data for processing. An application calls CTBRESULTS after sending a request to the server by CTBSEND and before binding and retrieving the results of that request (if any) with CTBBIND and CTBFETCH.

• Result data is an umbrella term for all the types of data that a server can return to an application:

— Regular rows

— Return parameters

— Stored procedure return status.

CTBRESULTS is used to set up all of these types of results for processing.

Value of RESULT-TYP Indicates: Result set contains:

CS-CMD-DONE The results of the request have been completely processed.

n/a

CS-CMD-FAIL The server encountered an error while executing the request. This value may indicate that the connection failed or was terminated.

No results.

CS-CMD-SUCCEED A request that returns no data, such as a language request containing an insert statement, has been successful.

No results.

CS-PARAM-RESULT Return parameter results have arrived. A single row of return parameters.

CS-ROW-RESULT Regular row results have arrived. One or more rows of tabular data.

CS-STATUS-RESULT Stored procedure return status results have arrived. A single row containing a single status.



• Result data is returned to an application in the form of result sets. A result set includes only a single type of result data. For example, a regular row result set contains only regular rows, and a return parameter result set contains only return parameters.

The CTBRESULTS Loop

• Because a request can generate multiple result sets, an application must call CTBRESULTS as long as it continues to return CS-SUCCEED, indicating that results are available. The simplest way to do this is in a loop that terminates when CTBRESULTS fails to return CS-SUCCEED. After the loop, an application can test CTBRESULTS’ final return code to determine why the loop terminated.

• Results are returned to an application in the order in which they are produced. However, this order is not always easy to predict. For example, when an application calls a stored procedure or transaction that in turn calls another stored procedure or transaction, the application might receive a number of row result sets, as well as a return parameter and a return status result set. The order in which these results are returned depends on how the called stored procedure or transaction is written.

For this reason, it is recommended that an application contain a series of IF statements, ending with a statement that handles all types of results that can be received. The RESULT-TYP argument indicates what type of result data the result set contains.

When are the Results of a Command Completely Processed?

• CTBRESULTS sets the result type to CS-CMD-DONE to indicate that the results of a logical command have been completely processed.

A logical command is any command defined with CTBCOMMAND, with the following exceptions:

— Each Transact-SQL select statement inside a stored procedure is a logical command. Other Transact-SQL statements inside stored procedures do not count as logical commands.



— Each Transact-SQL statement in a language request is a logical command.

• A result type of CS-CMD-SUCCEED or CS-CMD-FAIL is immediately followed by a result type of CS-CMD-DONE.

Canceling Results

• To cancel remaining results from a request (and eliminate the need to continue calling CTBRESULTS until it fails to return CS-SUCCEED), call CTBCANCEL.

CTBRESULTS and Stored Procedures

• A run-time error on a language request containing an execute statement will generate a result type of CS-CMD-FAIL. However, a run-time error on a statement inside a stored procedure or transaction will not generate a CS-CMD-FAIL. For example, if the stored procedure or transaction contains an insert statement and the user does not have insert permission on the database table, the insert statement will fail, but CTBRESULTS will still return CS-SUCCEED.

To check for run-time errors inside stored procedures or transactions, examine the procedure’s return status. The value is returned as a return status result set immediately following the row and parameter results (if any). If the error generates a server message, the message is also available to the application.

If results are coming from UniAccess Server-Library, an error will be indicated by a return status of TDS-DONE-ERROR.



Example

This code fragment that demonstrates the use of CTBRESULTS. It is taken from the sample program in CLNT1, described in Appendix A.

****************************************************************** * 3100-RECEIVE-RESULTS * ****************************************************************** * Receive Results from server ( CTBRESUL ) * ****************************************************************** 3100-RECEIVE-RESULTS.

MOVE ZEROS TO CL-RETURN-CODE, RF-TYPE.

CALL 'CTBRESUL' USING CL-COMMAND-HANDLE, CL-RETURN-CODE, RF-TYPE.

D DISPLAY 'CTBRESUL: Result Type Determined = ', RF-TYPE D UPON PRT. D DISPLAY RESULT-STATUS-CODES UPON PRT. D DISPLAY 'CTBRESUL: RETURN CODE = ', CL-RETURN-CODE D UPON PRT.


WHEN CS-SUCCEED

EVALUATE RF-TYPE

WHEN CS-ROW-RESULT MOVE 'D' TO SW-PROCESS-MODE PERFORM 3200-PROCESS-ROW THRU 3200-PROCESS-ROW-EXIT MOVE 'N' TO SW-DATA-FOUND MOVE 'Y' TO SW-FETCH PERFORM 3400-FETCH THRU 3400-FETCH-EXIT UNTIL NO-MORE-ROWS IF NO-DATA-FOUND THEN DISPLAY SPACE UPON PRT DISPLAY ' A RECORD DOES NOT EXIST FOR: ', FULL-NAME UPON PRT END-IF



WHEN CS-PARAM-RESULT D DISPLAY 'RETURN PARAMETER PROCESSING' D UPON PRT MOVE 'P' TO SW-PROCESS-MODE MOVE 1 to CL-INDEX MOVE ZERO TO DF-DATATYPE PERFORM 3200-PROCESS-ROW THRU 3200-PROCESS-ROW-EXIT MOVE 'Y' TO SW-FETCH PERFORM 3400-FETCH THRU 3400-FETCH-EXIT UNTIL NO-MORE-ROWS D DISPLAY 'RETURN PARAMETER = ', RT-NUMROWS D UPON PRT

WHEN CS-STATUS-RESULT D DISPLAY 'STATUS PARAMETER PROCESSING' D UPON PRT MOVE 'S' TO SW-PROCESS-MODE MOVE 1 to CL-INDEX MOVE ZERO TO DF-DATATYPE PERFORM 3200-PROCESS-ROW THRU 3200-PROCESS-ROW-EXIT MOVE 'Y' TO SW-FETCH PERFORM 3400-FETCH THRU 3400-FETCH-EXIT UNTIL NO-MORE-ROWS D DISPLAY 'RESULT STATUS = ', ST-STATUS D UPON PRT

WHEN CS-CMD-FAIL MOVE ERR-U-CTBRESUL TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT PERFORM 9600-CANCEL-COMMAND THRU 9600-CANCEL-COMMAND-EXIT

WHEN CS-CMD-SUCCEED MOVE 'S' TO RESULTS-CODE D DISPLAY ' CS-CMD-SUCCEED RECEIVED' UPON PRT

WHEN CS-CMD-DONE MOVE 'D' TO RESULTS-CODE D DISPLAY 'End of a Logical set of data' D UPON PRT



WHEN OTHER MOVE 'Result processing unknown RF-TYPE' TO ERROR-TEXT MOVE RF-TYPE TO ERROR-RC DISPLAY ERROR-MSG UPON PRT MOVE 'N' TO SW-RESULTS

END-EVALUATE

WHEN CS-END-RESULTS MOVE 'N' TO SW-RESULTS D DISPLAY 'All Done processing rows' UPON PRT

WHEN CS-CANCELED MOVE 'N' TO SW-RESULTS DISPLAY 'Results Canceled' UPON PRT

WHEN CS-FAIL MOVE ERR-U-CTBRESUL TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT PERFORM 9600-CANCEL-COMMAND THRU 9600-CANCEL-COMMAND-EXIT

WHEN OTHER MOVE 'N' TO SW-RESULTS MOVE ERR-U-CTBRESUL-UNK TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT PERFORM 9600-CANCEL-COMMAND THRU 9600-CANCEL-COMMAND-EXIT

END-EVALUATE.

3100-RECEIVE-RESULTS-EXIT. EXIT. . . . .



Returns

CTBRESULTS returns one of the following values.

See Also

CTBBIND, CTBCOMMAND, CTBDESCRIBE, CTBFETCH, CTBSEND

Topics: Remote Procedure Calls, Results

Value Meaning

CS-SUCCEED A result set is available for processing.

CS-END-RESULTS No more result sets are available for processing.


CS-CANCELED Results were canceled.

3-130 CTBSEND UniAccess for OS 2200 Client-Library Programming Reference


CTBSEND

Purpose

Send a request to the server.

Syntax

COPY CTPUBLIC.01 COMMAND COMP-2.01 RETCODE PIC S9(10) BINARY.

CALL 'CTBSEND' USING COMMAND, RETCODE.

Arguments



Comments

• CTBSEND signals the end of the data to be sent to a server (no more parameters, data, messages) and sends a request to the server.

• Sending a request to a server is a three-step process. To send a request to a server, an application:

— Initiates the request by calling CTBCOMMAND. CTBCOMMAND initiates a language request or an RPC.

— Describes parameters for the request, using CTBPARAM.

Not all requests require parameters. For example, a remote procedure call may or may not require parameters, depending on the stored procedure or transaction being called.


Function Descriptions CTBSEND 3-131

— Calls CTBSEND to send the request stream to the server.

• CTBSEND does not wait for a response from the server. An application must call CTBRESULTS to verify the success of the request and to set up the results for processing.

Example

This code fragment demonstrates the use of CTBSEND. It is taken from the sample program in CLNT1, described in Appendix A.



IF CL-RETURN-CODE NOT EQUAL CS-SUCCEED THEN MOVE ERR-U-CTBCMDAL TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT PERFORM 9800-CLIENT-MSG THRU 9800-CLIENT-MSG-EXIT PERFORM 7200-CLOSE-SERVER THRU 7200-CLOSE-SERVER-EXIT PERFORM 7300-DROP-CONHANDLE THRU 7300-DROP-CONHANDLE-EXIT PERFORM 7400-EXIT-CLIENT THRU 7400-EXIT-CLIENT-EXIT PERFORM 7500-DROP-CTXHANDLE THRU 7500-DROP-CTXHANDLE-EXIT END-IF. . . . .

*----------------------------------------------------------------* * Initiate the Remote Procedure Call ( CTBCOMMA ) * *----------------------------------------------------------------* * REQUEST-TYPE = CS-RPC-CMD (FOR REMOTE PROCEDURE CALL) * * REQUEST-BUFFER = NAME OF REMOTE PROCEDURE CALL * * BUFFER-LENGTH = LENGTH OF NAME OF REMOTE PROCEDURE CALL * *----------------------------------------------------------------* MOVE CF-RPC-SIZE TO PF-STRLEN.

3-132 CTBSEND UniAccess for OS 2200 Client-Library Programming Reference


CALL 'CTBCOMMA' USING CL-COMMAND-HANDLE, CL-RETURN-CODE, CS-RPC-CMD, CF-RPC, PF-STRLEN, CS-UNUSED. IF CL-RETURN-CODE NOT EQUAL CS-SUCCEED THEN MOVE ERR-U-CTBCOMMA TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT PERFORM 9800-CLIENT-MSG THRU 9800-CLIENT-MSG-EXIT PERFORM 7000-TERMINATE THRU 7000-TERMINATE-EXIT END-IF. . . . .

*----------------------------------------------------------------* * Send the Remote Procedure Request ( CTBSEND ) * *----------------------------------------------------------------* CALL 'CTBSEND' USING CL-COMMAND-HANDLE, CL-RETURN-CODE.

IF CL-RETURN-CODE NOT EQUAL CS-SUCCEED THEN MOVE ERR-U-CTBSEND TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT PERFORM 9800-CLIENT-MSG THRU 9800-CLIENT-MSG-EXIT PERFORM 7000-TERMINATE THRU 7000-TERMINATE-EXIT END-IF.

D DISPLAY 'CTBSEND: RPC Request Sent' UPON PRT.

2100-SEND-RPC-EXIT. EXIT.


Function Descriptions CTBSEND 3-133

Returns

CTBSEND returns one of the following values.

See Also

CTBCOMMAND, CTBFETCH, CTBPARAM, CTBRESULTS

Value Meaning



3-134 CSBCONFIG UniAccess for OS 2200 Client-Library Programming Reference


CSBCONFIG

Purpose

Set or retrieve context structure properties.

Syntax

COPY CTPUBLIC.01 CONTEXT COMP-2.01 RETCODE PIC S9(10) BINARY.01 ACTION PIC S9(10) BINARY.01 PROPERTY PIC S9(10) BINARY.01 BUFFER type.01 BUFFER-LEN PIC S9(10) BINARY.01 BUFBLANKSTRIP PIC S9(10) BINARY.01 OUTLEN PIC S9(10) BINARY.

CALL 'CSBCONFI' USING CONTEXT, RETCODE, OPTION, ACTION, BUFFER, BUFFER-LEN, BUFBLANKSTRIP, OUTLEN.

Arguments

CONTEXT — (I) The context handle whose properties are being set or retrieved. The context handle is defined in the program’s CSBCTXALLOC call.




Function Descriptions CSBCONFIG 3-135


PROPERTY — (I) The symbolic name of the property whose value is being set or retrieved. Client-Library properties are listed under Properties on page 2-33, with description, possible values, and defaults.

CSBCONFIG can set or retrieve the following properties.

BUFFER — (I/O) The variable (buffer) that will contain the specified property value. If ACTION is CS-SET, CSBCONFIG will take the value from this buffer; if ACTION is CS-GET, CSBCONFIG will return the requested information to this buffer; if ACTION is CS-CLEAR, this value will be ignored.



Value of ACTION Action taken by CSBCONFIG



CS-CLEAR Clears the value of the property by resetting it to its default value.

PROPERTY name Action taken by CSBCONFIG Notes

CS-EXTRA-INF Set, retrieve, or clear. Indicates whether or not to return the extra information required when processing messages in line, using the SQLCA or SQLCODE structure.

CS-VERSION Retrieve only. The version number of Open Client currently in use.





If a property value is being retrieved and BUFFER-LEN indicates that BUFFER is not large enough to hold the requested information, CSBCONFIG sets OUTLEN to the length of the requested information and returns CS-FAIL. To retrieve all the requested information, change the value of BUFFER-LEN to the length referenced in OUTLEN; rerun the application.



BUFBLANKSTRIP — (I) The blankstripping indicator. Indicates whether or not trailing blanks are stripped (that is, the value in the buffer ends at the last non-blank character).

Assign this argument one of the following symbolic values:

OUTLEN — (O) The length, in bytes, of the retrieved information. OUTLEN is an integer variable in which CSBCONFIG returns the length of the property value being retrieved. OUTLEN is used only when ACTION is CS-GET.

If the retrieved information is larger than BUFFER-LEN bytes, an application may use the value of OUTLEN to determine how many bytes are needed to hold the information.

If the ACTION is CS-SET or CS-CLEAR, this variable will be ignored.






Comments

NoteCSBCONFIG and CTBCONFIG both set and retrieve context properties. CSBCONFIG is used with global context properties; CTBCONFIG is used with Client-Library properties.

• CSBCONFIG sets or retrieves the values of global properties, namely the CS-EXTRA-INF property and the version number of Open Client currently in use.

• Use CTBCONFIG to set and retrieve the values of Client-Library-specific context properties. Properties set with CTBCONFIG affect only Client-Library behaviors.

About Global Context Properties

• Extra Information

— CS-EXTRA-INF determines whether or not Client-Library returns the extra information that is required to fill in a SQLCA or SQLCODE structure.

— If an application is not retrieving messages into a SQLCA or SQLCODE structure, the extra information is returned as ordinary Client-Library messages.

• Version Level

— The CS-VERSION property represents the version of Client-Library behavior that an application has requested using CSBCTXALLOC.

— An application can only retrieve the value of CS-VERSION; it cannot assign a value to CS-VERSION.

— Currently, the legal values for CS-VERSION are CS-VERSION-100 and CS-VERSION-110.



Example

This code fragment demonstrates the use of CSBCONFIG. It is not taken from any of the sample programs.

COPY CTPUBLIC

01 CTX COMP-2.01 CON COMP-2.01 CMD COMP-2.01 RET PIC S9(10) BINARY VALUE +0.01 RETCODE PIC S9(10) BINARY VALUE +0.01 RESTYPE PIC S9(10) BINARY VALUE +0.01 DATALEN PIC S9(10) BINARY VALUE +0.01 INTARG PIC S9(10) BINARY VALUE +0.01 INDIC PIC S9(10) BINARY VALUE +0 .01 ERRSTR PIC X(200).01 CMDSTR PIC X(200).01 USER PIC X(30).01 INTSIZE PIC S9(10) BINARY VALUE +4 .01 PWD PIC X(30).01 COL-NUM PIC S9(10) BINARY VALUE +0 .01 FMT-BUFFER PIC X(6).01 FMT-LEN PIC S9(10) BINARY VALUE +0 .01 REM-PWD PIC X(30).01 REM-PWD-LEN PIC S9(10) BINARY VALUE +0 .01 VERSION PIC S9(10) BINARY VALUE +0 .01 INF-VAL PIC S9(10) BINARY VALUE +0 . 01 ERRFILE-ARG PIC S9(10) BINARY.01 STRLEN PIC S9(10) BINARY.01 CSBLEN PIC S9(10) BINARY.01 OUTLEN PIC S9(10) BINARY.01 OUTDATA PIC S9(10) BINARY.01 SERVNAME PIC X(30).01 USER-DATA PIC X(30).01 USER-BUF PIC X(8).01 NUMCOLS PIC S9(10) BINARY.01 ROWS-READ PIC S9(10) BINARY.01 NUM-ROWS PIC S9(10) BINARY.01 NUMROWS PIC S9(10) BINARY.01 I PIC S9(10) BINARY.01 I2 PIC S9(10) BINARY VALUE IS 0.01 ONE-CONST PIC S9(10) BINARY VALUE 1.



01 COPIED PIC S9(10) BINARY.01 COPIED-NULL PIC S9(10) BINARY.01 INDICATOR PIC S9(10) BINARY.01 INDICATOR-NULL PIC S9(10) BINARY.

01 ERROR-MSG . 05 ERROR-TEXT PIC X(36) VALUE 'I am here.' . 05 ERROR-RC PIC -ZZZ9 .01 ERROR-MSG-STR REDEFINES ERROR-MSG PIC X(41) .

PROCEDURE DIVISION. * * ALLOCATE A CONTEXT STRUCTURE * CALL 'CSBCTXAL' USING CS-VERSION-46 RETCODE CTX.

IF CSL-RC NOT EQUAL CS-SUCCEED THEN MOVE " Error in CSBCTXAL" TO ERROR-TEXT MOVE CSL-RC TO ERROR-RC PERFORM ERROR-OUT PERFORM DONE-PARA END-IF .

* * SET THE CONTEXT STRUCTURE PROPERTY CS-EXTRA-INF * CALL 'CSBCONFI' USING CTX RETCODE CS-SET CS-EXTRA-INF CS-TRUE CS-UNUSED CS-FALSE OUTLEN.

IF CSL-RC NOT EQUAL CS-SUCCEED THEN MOVE " Error in CSBCONFI-CSSET-EXTINFO" TO ERROR-TEXT MOVE CSL-RC TO ERROR-RC PERFORM ERROR-OUT PERFORM DONE-PARA END-IF .



CALL 'CSBCONFI' USING CTX RETCODE CS-GET CS-EXTRA-INF INF-VAL CS-UNUSED CS-FALSE OUTLEN. IF CSL-RC NOT EQUAL CS-SUCCEED THEN MOVE " Error in CSBCONFI-CSGET-EXTINFO" TO ERROR-TEXT MOVE CSL-RC TO ERROR-RC PERFORM ERROR-OUT PERFORM DONE-PARA END-IF

IF INF-VAL NOT EQUAL CS-TRUE MOVE " CSBCONFI returned wrong value" TO ERROR-TEXT MOVE CSL-RC TO ERROR-RC PERFORM ERROR-OUT PERFORM DONE-PARA END-IF .

CALL 'CSBCONFI' USING CTX RETCODE CS-GET CS-VERSION VERSION CS-UNUSED CS-FALSE OUTLEN.

IF CSL-RC NOT EQUAL CS-SUCCEED THEN MOVE " Error in CSBCONFI-CSGET-VERSION" TO ERROR-TEXT MOVE CSL-RC TO ERROR-RC PERFORM ERROR-OUT PERFORM DONE-PARA END-IF

IF INF-VAL NOT EQUAL CS-TRUE MOVE " CSBCONFI returned wrong value-VERSION" TO ERROR-TEXT MOVE CSL-RC TO ERROR-RC PERFORM ERROR-OUT PERFORM DONE-PARA END-IF .



Returns

CSBCONFIG returns one of the following values.

See Also

CTBCONFIG, CTBCONPROPS, CTBINIT, CSBCTXALLOC

Value Meaning



3-142 CSBCONVERT UniAccess for OS 2200 Client-Library Programming Reference


CSBCONVERT

Purpose

Convert a data value from one datatype to another.

Syntax

COPY CTPUBLIC.01 CONTEXT COMP-2.01 RETCODE PIC S9(10) BINARY.01 SRCFMT

05 SRC-NAME PIC X(132).05 SRC-NAMELEN PIC S9(10) BINARY.05 SRC-TYPE PIC S9(10) BINARY.05 SRC-FORMAT PIC S9(10) BINARY.05 SRC-MAXLEN PIC S9(10) BINARY.05 SRC-SCALE PIC S9(10) BINARY.05 SRC-PRECISION PIC S9(10) BINARY.05 SRC-STATUS PIC S9(10) BINARY.05 SRC-COUNT PIC S9(10) BINARY.05 SRC-UTYPE PIC S9(10) BINARY.05 SRC-LOCALE PIC X(68).

01 SRCDATA type.01 DESTFMT

05 DEST-NAME PIC X(132).05 DEST-NAMELEN PIC S9(10) BINARY.05 DEST-TYPE PIC S9(10) BINARY.05 DEST-FORMAT PIC S9(10) BINARY.05 DEST-MAXLEN PIC S9(10) BINARY.05 DEST-SCALE PIC S9(10) BINARY.05 DEST-PRECISION PIC S9(10) BINARY.05 DEST-STATUS PIC S9(10) BINARY.05 DEST-COUNT PIC S9(10) BINARY.05 DEST-UTYPE PIC S9(10) BINARY.05 DEST-LOCALE PIC X(68).

01 DESTDATA type.01 OUTLEN PIC S9(10) BINARY.

CALL 'CSBCONVE' USING CONTEXT, RETCODE, SRCFMT, SRCDATA, DESTFMT, DESTDATA, OUTLEN.


Function Descriptions CSBCONVERT 3-143

Arguments

CONTEXT — (I) A context handle. The context handle is defined in the program’s CSBCTXALLOC call.


SRCFMT — (I) A structure that contains a description of the variable(s) that contain the source data.

The chart below lists the fields in the SRCFMT structure and indicates if and how they are used by CSBCONVERT. For a general discussion of this structure, see DATAFMT Structure on page 2-13.

CSBCONVERT ignores SRCFMT fields that it does not use.

Table 3-11: Fields in the SRCFMT Structure for CSBCONVERT


SRC-NAME Not used. n/a

SRC-NAMELEN Not used. n/a

SRC-TYPE For all datatype conversions.

The datatype of the source data.

CSBCONVERT converts this datatype to the datatype specified for the destination variable (DEST-TYPE).

SRC-FORMAT Not used. n/a

SRC-MAXLEN When converting non-fixed-length source datatypes to any destination type.

SRC-MAXLEN is ignored when converting fixed-length types.

The length of the source variable, in bytes. If SRCDATA is an array, SRC-MAXLEN is the length of an element in the array.

When character or binary datatypes are being converted, SRC-MAXLEN must describe the total length of the source variable, including any space required for special terminating bytes, with this exception: when converting a VARYCHAR-type source, SRC-MAXLEN does not include the length of the ‘LL’ length specification.



SRCDATA — (I) The name of the source variable that contains the data to be converted. This is the variable described in the SRCFMT structure.

DESTFMT — (I) A structure that contains a description of the variable(s) that contain destination (converted) data.

The following chart lists the fields in the DESTFMT structure and indicates if and how they are used by CSBCONVERT. For a general discussion of this structure, see DATAFMT Structure on page 2-13.

CSBCONVERT ignores DESTFMT fields that it does not use.

SRC-SCALE Only when converting to or from packed decimal datatypes.

The number of digits that follow the decimal point in the source variable.

SRC-SCALE must be less than or equal to SRC-PRECIS. For CS-PACKEDEC, SRC-SCALE cannot be greater than 18. For CS-NUMERIC and CS-DECIMAL, SRC-SCALE cannot be greater than 77. The default scale is 0.

SRC-PRECIS Only when converting to or from packed decimal datatypes.

The total number of digits in the source variable. This is the n in PIC S9(n).

SRC-PRECIS must be greater than or equal to SRC-SCALE. For CS-PACKEDEC, SRC-SCALE must be 18. For CS-NUMERIC and CS-DECIMAL, SRC-SCALE cannot be less than 1 or greater than 77. The default precision is 18.

SRC-STATUS Not used n/a

SRC-COUNT Not used. n/a

SRC-UTYPE Not used. n/a

SRC-LOCALE Not used. n/a




Table 3-12: Fields in the DESTFMT Structure for CSBCONVERT


DEST-NAME Not used. n/a

DEST-NAMELEN Not used. n/a

DEST-TYPE For all datatype conversions.

The datatype of the destination variable.

CSBCONVERT converts the datatype specified for the source data (SRC-TYPE) to this datatype.

DEST-FORMAT Not used. n/a

DEST-MAXLEN When converting all source datatypes to non-fixed-length datatypes.

DEST-MAXLEN is ignored when converting to fixed-length datatypes.

The length of the destination variable, in bytes. If DESTDATA is an array, DEST-MAXLEN is the length of an element in the array.

When character or binary datatypes are being converted, DEST-MAXLEN must describe the total length of the destination variable, including any space required for special terminating bytes, with this exception: when converting to a VARYCHAR-type destination, DEST-MAXLEN does not include the length of the ‘LL’ length specification.

DEST-SCALE Only when converting to or from packed decimal datatypes.

The number of digits that follow the decimal point in the destination variable.

DEST-SCALE must be less than or equal to DEST-PRECIS. For CS-PACKEDEC, DEST-SCALE cannot be greater than 18. For CS-NUMERIC and CS-DECIMAL, DEST-SCALE cannot be greater than 77. The default scale is 0.

DEST-PRECIS Only when converting to or from packed decimal datatypes.

The total number of digits in the destination variable. This is the n in PIC S9(n).

DEST-PRECIS must be greater than or equal to DEST-SCALE. For CS-PACKED, DEST-SCALE must be 18. For CS-NUMERIC and CS-DECIMAL, DEST-SCALE cannot be less than 1 or greater than 77. The default precision is 18.

DEST-STATUS Not used. n/a

DEST-COUNT Not used. n/a



DESTDATA — (O) The name of the variable that will contain the converted data. This is the variable described in the DESTDATA structure.

OUTLEN — (O) The length, in bytes, of the data placed in DESTDATA. If the conversion fails, CSBCONVERT sets OUTLEN to CS-UNUSED.

Comments

A client application can use this function to convert the datatype of RPC return parameters to the datatype of the target server, and to convert the datatype of a retrieved value to a datatype that can be used by UniAccess Client-Library.

• This function converts a single variable each time it executes.

If converting columns, an application must issue a separate CSBCONVERT call for each column to be converted. If several rows of data need converting, the application must issue a separate CSBCONVERT call for every column that needs conversion in each row (in other words, for each cell).

• The following chart lists the conversions that can be performed with CSBCONVERT.

DEST-UTYPE Not used. n/a

DEST-LOCALE Not used. n/a




Table 3-13: Datatype Conversions Performed by CSBCONVERT

WarningConverting CS-MONEY or CS-CHAR values to CS-FLOAT can result in a loss of precision. Converting a CS-FLOAT value to a character type can also result in a loss of precision.

Source type Result type

CS-BINARY CS-CHAR

CS-CHAR CS-DATETIMECS-DATETIME4CS-MONEYCS-MONEY4CS-PACKEDECCS-VARCHAR

CS-DATETIME CS-CHAR

CS-DATETIME4 CS-CHAR

CS-DECIMAL CS-PACKEDEC

CS-FLOAT CS-PACKEDECCS-REAL

CS-MONEY CS-CHARCS-FLOATCS-PACKEDECCS-VARCHAR

CS-MONEY4 CS-CHAR

CS-NUMERIC CS-PACKEDEC

CS-PACKEDEC CS-CHARCS-DECIMALCS-FLOATCS-MONEYCS-NUMERIC

CS-REAL CS-FLOAT

CS-VARCHAR CS-CHARCS-PACKEDEC



Example

The following code fragment demonstrates the use of CSBCONVERT. It is taken from the sample program CLNT1, described in Appendix A.

****************************************************************** * 3400-FETCH * ****************************************************************** * FETCH Result Data into 'Binded' Program Variables ( CTBFETCH )* ****************************************************************** 3400-FETCH.

CALL 'CTBFETCH' USING CL-COMMAND-HANDLE, CL-RETURN-CODE, CS-UNUSED, CS-UNUSED, CS-UNUSED, FF-ROWS-READ.

D DISPLAY 'CTBFETCH: RETURN CODE: ', CL-RETURN-CODE UPON PRT. D DISPLAY '0=FAIL,1=SUCCEED,-203=ROW-FAIL,-204=END-DATA' D UPON PRT.


WHEN CS-SUCCEED MOVE 'Y' TO SW-FETCH MOVE 'Y' TO SW-DATA-FOUND

IF PROCESSING-DATA THEN PERFORM 3500-DISPLAY-RESULTS THRU 3500-DISPLAY-RESULTS-EXIT END-IF

. . .

3500-DISPLAY-RESULTS.

DISPLAY SPACE UPON PRT.

IF FIRST-NAME NOT = SPACES THEN MOVE SPACES TO FULL-NAME



STRING CL-HOST-DATA OF FIRST-NAME DELIMITED BY SPACE, SPACE DELIMITED BY SIZE, CL-HOST-DATA OF LAST-NAME DELIMITED BY SPACE INTO FULL-NAME END-IF.

DISPLAY SPACE UPON PRT. DISPLAY ' **** EMPLOYEE RECORD FOR: ', FULL-NAME UPON PRT. DISPLAY SPACE UPON PRT. DISPLAY ' Employee ID: ', CL-HOST-DATA OF EMPLOYEE-ID UPON PRT. DISPLAY ' Password: ', CL-HOST-DATA OF PASSWORD UPON PRT.

PERFORM 3600-CONVERT-DATETIME4 THRU 3600-CONVERT-DATETIME4-EXIT.

DISPLAY ' Birth Date: ', BD-DATE-CHAR UPON PRT. . . .

****************************************************************** * 3600-CONVERT-DATETIME4 * ****************************************************************** 3600-CONVERT-DATETIME4.

MOVE LOW-VALUES TO DATA-FORMAT, DATA-FORMAT-2. MOVE CS-DATETIME4-TYPE TO DF-DATATYPE. MOVE 4 TO DF-MAX-LENGTH. MOVE CS-CHAR-TYPE TO DF2-DATATYPE. MOVE 26 TO DF2-MAX-LENGTH. MOVE 0 TO DF2-PRECISION, DF2-SCALE. CALL 'CSBCONVE' USING CL-CONTEXT-HANDLE, CL-RETURN-CODE, DATA-FORMAT, CL-HOST-DATA OF BIRTH-DATE, DATA-FORMAT-2, CL-HOST-DATA-CHR OF BIRTH-DATE, CL-HOST-DATA-LEN OF BIRTH-DATE.



IF CL-RETURN-CODE NOT EQUAL CS-SUCCEED THEN MOVE ERR-U-CSBCONVE-DT4 TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT PERFORM 7000-TERMINATE THRU 7000-TERMINATE-EXIT END-IF.

D DISPLAY 'CSBCONVE: DATETIME4 Converted' UPON PRT. 3600-CONVERT-DATETIME4-EXIT. EXIT.

. . . .

Returns

CSBCONVERT returns one of the following values.

See Also

CTBFETCH

Topics: DATAFMT Structure, Datatypes

Value Meaning




Function Descriptions CSBCTXALLOC 3-151

CSBCTXALLOC

Purpose

Allocate a context structure.

Syntax

COPY CTPUBLIC.01 VERSION PIC S9(10) BINARY.01 RETCODE PIC S9(10) BINARY.01 CONTEXT COMP-2.

CALL 'CSBCTXAL' USING VERSION, RETCODE, CONTEXT.

Arguments

VERSION — (I) The version of Client-Library behavior that the application has been programmed to accept. The following table lists the symbolic values that are legal for VERSION:


Value of VERSION Indicates: Features supported

CS-VERSION-100 10.0 BEHAVIOR Remote procedure calls.

This is the initial version of UniAccess Client-Library.

CS-VERSION-110 11.0 behavior Reduces overhead by not assigning the following language files unless they are needed to display error or warning messages: SYS$LIB$*ISO$1 (T) SYS$LIB$*ENGL$ISO-1 (T)

3-152 CSBCTXALLOC UniAccess for OS 2200 Client-Library Programming Reference


CONTEXT — (O) The variable in which this newly-allocated context handle is returned. This is the argument used by CTBINIT when it initializes UniAccess Client-Library.

Comments

• CSBCTXALLOC allocates a context structure.

• A context structure contains information that describes an application context. For example, a context structure defines the version of UniAccess Client-Library that is in use.

• Allocating a context structure is the first step in any Client-Library application.

• After allocating a context structure, a Client-Library application typically customizes the context by calling CSBCONFIG and/or CTBCONFIG, and then sets up one or more connections within the context.

• To de-allocate a context structure, an application calls CSBCTXDROP.

Example

The following code fragment demonstrates the use of CSBCTXALLOC. It is taken from the sample program CLNT1, described in Appendix A.


CALL 'CSBCTXAL' USING CS-VERSION-100, CL-RETURN-CODE, CL-CONTEXT-HANDLE.

IF CL-RETURN-CODE NOT EQUAL CS-SUCCEED THEN MOVE ERR-U-CSBCTXAL TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT STOP RUN END-IF.


Function Descriptions CSBCTXALLOC 3-153

D DISPLAY 'CSBXTAL: Context Handle allocated' UPON PRT.

1200-CONTEXT-HANDLE-EXIT. EXIT.


CALL 'CTBINIT' USING CL-CONTEXT-HANDLE, CL-RETURN-CODE, CS-VERSION-100. IF CL-RETURN-CODE NOT EQUAL CS-SUCCEED THEN MOVE ERR-U-CTBINIT TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT PERFORM 7500-DROP-CTXHANDLE THRU 7500-DROP-CTXHANDLE-EXIT END-IF.

D DISPLAY 'CTBINIT: UniAccess Client Library Initialized' D UPON PRT.

1300-INIT-CLIENT-LIB-EXIT. EXIT.


CALL 'CTBCONAL' USING CL-CONTEXT-HANDLE, CL-RETURN-CODE, CL-CONNECTION-HANDLE.

IF CL-RETURN-CODE NOT EQUAL CS-SUCCEED THEN MOVE ERR-U-CTBCONAL TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT PERFORM 7400-EXIT-CLIENT THRU 7400-EXIT-CLIENT-EXIT PERFORM 7500-DROP-CTXHANDLE THRU 7500-DROP-CTXHANDLE-EXIT END-IF.

3-154 CSBCTXALLOC UniAccess for OS 2200 Client-Library Programming Reference


D DISPLAY 'CTBCONAL: Connection Handle Allocated' UPON PRT. 1400-CONNECT-HANDLE-EXIT. EXIT. . . .

Returns

CSBCTXALLOC returns one of the following values.

See Also

CTBCONALLOC, CTBCONFIG, CTBINIT, CSBCTXDROP, CSBCONFIG

Value Meaning



The most common reason for a CSBCTXALLOC failure is a lack of available memory.


Function Descriptions CSBCTXDROP 3-155

CSBCTXDROP

Purpose

De-allocate (drop) a context structure.

Syntax

COPY CTPUBLIC.01 CONTEXT COMP-2.01 RETCODE PIC S9(10) BINARY.

CALL 'CSBCTXDR' USING CONNECTION, RETCODE.

Arguments

CONTEXT — (I) A context structure.


Comments

• CSBCTXDROP de-allocates a context structure.

• A context structure describes a particular context, or operating environment, for a set of server connections.

• Once a context has been de-allocated, it cannot be re-used. To allocate a new context, an application can call CSBCTXALLOC.

• A Client-Library application cannot call CSBCTXDROP to de-allocate a context structure until it has called CTBEXIT to clean up Client-Library space associated with the context.

• CSBCTXDROP will fail if the context contains an open connection.

3-156 CSBCTXDROP UniAccess for OS 2200 Client-Library Programming Reference


Example

The following code fragment demonstrates the use of CSBCTXDROP. It is taken from the sample program CLNT1, described in Appendix A.


CALL 'CSBCTXAL' USING CS-VERSION-100, CL-RETURN-CODE, CL-CONTEXT-HANDLE.

IF CL-RETURN-CODE NOT EQUAL CS-SUCCEED THEN MOVE ERR-U-CSBCTXAL TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT STOP RUN END-IF.

D DISPLAY 'CSBXTAL: Context Handle allocated' UPON PRT.

1200-CONTEXT-HANDLE-EXIT. EXIT.


CALL 'CTBINIT' USING CL-CONTEXT-HANDLE, CL-RETURN-CODE, CS-VERSION-100. IF CL-RETURN-CODE NOT EQUAL CS-SUCCEED THEN MOVE ERR-U-CTBINIT TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT PERFORM 7500-DROP-CTXHANDLE THRU 7500-DROP-CTXHANDLE-EXIT END-IF.


Function Descriptions CSBCTXDROP 3-157

D DISPLAY 'CTBINIT: UniAccess Client Library Initialized' D UPON PRT.

1300-INIT-CLIENT-LIB-EXIT. EXIT.

. . .


CALL 'CSBCTXDR' USING CL-CONTEXT-HANDLE, CL-RETURN-CODE. IF CL-RETURN-CODE NOT EQUAL CS-SUCCEED THEN MOVE ERR-U-CSBCTXDR TO CL-ERROR-STRING PERFORM 9200-UACL-ERROR THRU 9200-UACL-ERROR-EXIT END-IF.

D DISPLAY 'CSBCTXDR: Context Handle Dropped' UPON PRT. DISPLAY 'CLIENT: CLNT1 TERMINATED.' UPON PRT.

7500-DROP-CTXHANDLE-EXIT. STOP RUN.

Returns

CSBCTXDROP returns one of the following values.

See Also

CTBCLOSE, CTBEXIT, CSBCTXALLOC

Value Meaning



Appendixes

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Appendixes

Appendix A: Sample Programs

Appendix B: Return Codes

Appendix C: Client Program Messages

Appendix D: UAMM Error Messages

Appendix E: Client-Library C Kit

Appendix F: References


A Sample Programs

A Sample Programs

This appendix describes the sample UniAccess Client-Library programs and explains how to set them up. It also overviews the UniAccess Sample System.

UniAccess Client-Library ProgramsThe UniAccess Transaction Client package includes seven Client-Library programs. CLNT1, CLNT2, and CLNT3 programs send RPCs to a OS 2200 server or Sybase SQL Server; CLNT1SS and CLNT2SS programs process language requests that invoke stored procedures on SQL Server; CLNT4 sends a language request to a OS 2200 server, Microsoft SQL Server or Sybase SQL Server; CLNT5 sends an RPC to a OS 2200 server. Table A-1 provides the file names for each client sample program, the name of the

Topics Page

UniAccess Client-Library Programs A-1

UACL Functions Demonstrated A-5

UACL Datatypes Demonstrated A-5

The UniAccess Sample System A-5

UniAccess Sample Databases A-7

Setting up the Sample System A-13

UniAccess Transaction Client Sample Setup A-13

SQL Server Database Setup A-14

Additional Sample Setup Information A-15

A-2 UniAccess for OS 2200 Client-Library Programming Reference


corresponding server program, the stored procedure name, and the element where the client source program resides. A description of each program follows.

Table A-1: UniAccess Client-Library Samples

CLNT1 CLNT1 prompts the user for @first_name and @last_name. It calls a remote procedure named get_employee with the user-specified fields as input parameters and a program-defined field as an output parameter. It displays the row results and the return parameter value. In addition to being an example of efficient Client-Library program design, this program demonstrates the following concepts:

• issuing RPCs• processing input parameters• processing output parameters• retrieving 1 result set consisting of a variety of datatypes• processing errors.

UniAccess Client Program

UniAccess Server Program

Microsoft SQL Server Stored Procedure

Sybase SQL Server Stored Procedure

UniAccess Client Element

CLNT1

SERV1(get_employee)

n/a get_employee CLNT1/UCOB CLNT1/C

CLNT1SS n/a get_employee n/a CLNT1SS/UCOB

CLNT2 SERV2(get_description)

n/a get_description CLNT2/UCOB

CLNT2SS n/a get_description n/a CLNT2SS/UCOB

CLNT3 SERV3(store_employee)

n/a store_employee CLNT3/UCOB

CLNT4 UARS (language request)

n/a(language request)

n/a(language request)

CLNT4/UCOB

CLNT5 SERV5(get_emp_review)

n/a n/a CLNT5/UCOB


Sample Programs A-3

CLNT1SS CLNT1SS prompts the user for @first_name and @last_name. It calls a language request to invoke the get_employee stored procedure on Microsoft SQL Server with the user-specified fields as input parameters and a program-defined field as an output parameter. It displays the row results and the return parameter value. In addition to being an example of efficient Client-Library program design, this program demonstrates the following concepts:

• issuing a language request that invokes a stored procedure.• processing input parameters• processing output parameters• retrieving 1 result set consisting of a variety of datatypes• processing errors.

CLNT2 CLNT2 prompts the user for @category_code. It calls a remote procedure named get_description with a user-specified field as an input parameter. It displays the two row result sets. In addition to demonstrating a variety of Client-Library programming techniques, this program demonstrates the following concepts:

• issuing RPCs• processing input parameters• retrieving 2 result sets consisting of a variety of datatypes• processing errors.

CLNT2SS CLNT2SS prompts the user for @category_code. It calls a language request to invoke the get_description stored procedure on Microsoft SQL Server with a user-specified field as an input parameter. It displays the two row result sets. In addition to demonstrating a variety of Client-Library programming techniques, this program demonstrates the following concepts:

• issuing a language request that invokes a stored procedure• processing input parameters• retrieving 2 result sets consisting of a variety of datatypes• processing errors.



CLNT3 CLNT3 prompts the user for all employee columns and for an extended session flag. It calls a remote procedure named store_employee with the user-specified parameters. It displays the status result. If the extended session flay is ‘y’ or ‘Y’, the server transaction will process multiple CLNT3 inputs as a single TIP transaction. CLNT3 demonstrates the following concepts:

• processing client RPCs• processing input parameters of a variety of datatypes• extended session use by a client application• processing errors.

CLNT4 CLNT4 sends a hardcoded language request to the language transaction

requesting all records from the employee_job_description view. It displays the row result set. It demonstrates the following concepts:

• issuing language requests• retrieving 1 result set consisting of a variety of datatypes• processing errors.

CLNT5 CLNT5 prompts the user for either @employee_id or ALL. It calls a remote procedure named get_emp_review with the user-specified field as input parameters and a program-defined field as an output parameter. It displays the row results and the return parameter value. In addition to being an example of efficient Client-Library program design, this program demonstrates the following concepts:

• issuing RPCs• processing input parameters • processing output parameters, particularly TDS-TEXT data. • retrieving 1 result set consisting of a variety of datatypes • processing errors.


Sample Programs A-5

UACL Functions Demonstrated

The sample Client-Library programs demonstrate the use of the following functions:

CTBBIND CTBDIAGCTBCANCEL CTBEXITCTBCLOSE CTBFETCHCTBCMDALLOC CTBINITCTBCMDDROP CTBPARAMCTBCOMMAND CTBRESINFOCTBCONALLOC CTBRESULTSCTBCONDROP CTBSENDCTBCONNECT CSBCONVERTCTBCONPROPS CSBCTXALLOCCTBDESCRIBE CSBCTXDROP

UACL Datatypes Demonstrated

The sample Client-Library programs demonstrate the use of the following datatypes:

CS-BINARY CS-INTCS-BIT CS-MONEYCS-CHAR CS-MONEY4CS-DATETIME CS-REALCS-DATETIME4 CS-SMALLINTCS-FLOAT CS-TINYINT

The UniAccess Sample SystemThe Client-Library programs described previously are part of the UniAccess Sample System of demonstration programs. The sample programs provided are modular and flexible, allowing them to operate in a variety of client/server environments. The sample servers provided are UniAccess Transaction Server (UATS) and SQL Server. The sample clients provided are UniAccess Transaction Client (UATC), PC Client, and SQL Server.

The sample system has the following components, illustrated in Figure A-1.

• RDMS 2200 UASAMPLE Database. The sample database accessed by the sample UATS programs.



• SQL Server uasample Database. The sample database accessed by the sample UATC and PC Client programs.

• SQL Server Stored Procedures. The stored procedures used in conjunction with the sample UATC and PC Client programs.

• UATS Samples. UniAccess Server-Library programs that work with the sample UATC and PC Client programs.

• UATC Samples. UniAccess Client-Library programs that work with the sample UATS programs and sample SQL Server stored procedures.

• PC Client Samples. PC Client programs that work with the sample UATS programs and sample SQL Server stored procedures.

Figure A-1: Components of the UniAccess Sample System

SQL Server Platform

PC ClientSamples

SQL ServerUASAMPLEDatabase

UATSSamples

UATCSamples

RDMS 2200UASAMPLEDatabase

OS 2200 Host

Workstation

SQL Server Stored

Procedures


Sample Programs A-7

Figure A-1 illustrates the modularity of the sample programs. The UATC samples, the PC Client samples and SQL Server stored procedure samples can all function as client applications. They can issue requests to UATS or to SQL Servers.

UniAccess Sample Databases

The UniAccess Sample System provides two sample databases: the UASAMPLE database for RDMS 2200 and the uasample database for SQL Server. Both databases are functionally equivalent.

Functional View of the Sample Databases

The following high-level, functional view of the sample system databases applies to both the RDMS 2200 and SQL Server versions.

Table A-2: Functional View of the Sample Databases

Table Name Column Name Description

employee employee_idfirst_namelast_namepasswordbirth_datejob_code salarystart_timeshift_rotationwithhold_401kwithhold_statewithhold_local

employee identification numberfirst namelast namepassworddate of birthjob code numberannual salarywork start timeshift rotation date and time401K withholding percentagestate/province withholding percentagelocal government withholding percentage

job_description job_code category_codesalariedhourlymin_salarymax_salarydescription

job code numberjob category codesalaried indicatorhourly indicatorminimum salarymaximum salaryjob description

job_category category_codedescription

job category codecategory description

employee_review employee_idreview text

employee identification numberemployee performance review



Logical View of the Sample Databases

Table A-3 demonstrates the relationship among the employee, job_description, and job_category tables. The shaded cells in the table indicate primary keys.

This high-level, logical view of the sample system databases applies to both the RDMS 2200 and SQL Server versions.

Table A-3: Logical View of the Sample Databases

employee job_description job_category

employee_id job_code job_code N 1 job_code category_code category_code

N 1 category_code

first_name category_code description

last_name salaried

password hourly

birth_date min_salary

job_code max_salary

salary description

start_time

shift_rotation

withhold_401k

withhold_state

withhold_local

employee_review employee job_description

employee_id employee_id employee_id 1 1

employee_id job_code job_code N 1

job_code

review_text first_name category_code

last_name salaried

as above as above


Sample Programs A-9

Physical View of the UASAMPLE RDMS 2200 Database

Table A-4 describes the physical implementation of the UASAMPLE database for RDMS 2200.

Table A-4: Physical View of the UASAMPLE RDMS 2200 Database

Table Name Column Name Datatype Characteristics


integercharacter(30)character(30)character(30)datesmallintnumeric(8,2)timetimestamprealfloatdouble

not null, primary keynot nullnot null

not nullnot nullnot null

not nullnot null

job_description job_codecategory_codesalariedhourlymin_salarymax_salarydescription

smallintsmallintcharacter(1)character(1)decimal(8,2)decimal8,2)character(255)

not null, primary keynot nullnot nullnot nullnot nullnot null


smallintcharacter(30)

not null, primary key

employee_review employee_id review_text

integercharacter (1920)




Physical View of the uasample SQL Server Database

Table A-5 describes the physical implementation of the uasample database for SQL Server.

Table A-5: Physical View of the uasample SQL Server Database

Table Name Column Name Datatype Characteristics


intchar(30)char(30)binary(30)smalldatetimesmallintmoneydatetimedatetimerealfloatdouble precision

not null, primary keynot nullnot nullnullnot nullnot nullnot nullnullnullnullnot nullnot null

job_description job_codecategory_codesalariedhourlymin_salarymax_salarydescription

smallinttinyintbitbitsmallmoneysmallmoneyvarchar(255)

not null, primary keynot nullnot nullnot nullnot nullnot null


tinyintchar(30)


employee_review employee_id review_text

integertext



Sample Programs A-11

Constraints, Triggers, and Views

Foreign Key Constraints. The following foreign key constraints apply to both the RDMS 2200 and SQL Server sample databases.

Check Constraint. The following check constraints apply to both the RDMS 2200 and SQL Server sample databases.

check (job_category.category_code > 0 and job_category.category_code < 100)

Trigger. This trigger is created for the SQL Server database only. The integrity of this trigger is maintained in the RDMS 2200 database by the Server-Library transactions.

create trigger salary_checkon employeefor insert asif (select count(*) from job_description, inserted where job_description.job_code = inserted.job_code and (job_description.min_salary > inserted.salary or job_description.max_salary < inserted.salary)) > 0begin rollback transaction print "Salary outside job description range."endgo

Table Foreign Key Primary Key Table

job_description category_code job_category

employee job_code job_description

employee_review employee_id employee



View. The following view applies to both the RDMS 2200 and SQL Server sample databases.

create view employee_job_description ( employee_id, first_name, last_name, cat_description, job_description ) as select employee_id, first_name, last_name, job_category.description, job_description.description from employee, job_description, job_category where employee.job_code = job_description.job_code and job_description.category_code = job_category.category_code

SQL Server Stored Procedures

The following stored procedures apply to the SQL Server sample database. They are created in the SSRVBLD/SQL script.

Table A-6: UniAccess Stored Procedures for SQL Server

Procedure Name Description

get_employee The get_employee stored procedure accepts @first_name and @last_name as input parameters and @row_count as an output parameter. It returns one or more employee records as a result set based upon the received @first_name and @last_name parameters. It also updates the @row_count parameter with the number of rows in the database.

get_description The get_description stored procedure accepts @category_code as an input parameter. It returns one job description record based upon the received job code parameter and one category record based upon the category code of the retrieved job description record.

store_employee The store_employee stored procedure accepts all employee table columns as input parameters. It stores an employee record in the employee table using the received parameters.



Setting up the Sample SystemTo set up the sample system, you must create the sample database and then build and install the client and server applications. Scripts to create all the components of the sample system are included with each product package. This section describes the set up of those sample system components relevant to UniAccess Transaction Client. The set up of other sample system components is described in Appendix C of the UniAccess for OS 2200 System Administration Guide. UniAccess Transaction Client must be installed in order to compile and run the Client-Library examples.

All sample scripts described in the setup sections are located in the OS 2200 file SYS$LIB$*UASAMP (or SYS$LIB$*UASAMPT for test mode installations). Some of these scripts can be downloaded to a Windows workstation and executed from there.

UniAccess Transaction Client Sample Setup

The UniAccess Client-Library sample runstreams contain the source program as well as the ECL to compile and link each program. As depicted in the following table, CLNT1 provides sample syntax in UCS COBOL and UCS C, while CLNT1SS, CLNT 2, CLNT2SS, CLNT3, CLNT4, CLNT5 provide sample syntax in UCS COBOL.

To set up the sample Client-Library programs, perform the following steps:

• Select the appropriate runstreams for your environment and add them.

Program Name UCS COBOL Source Runstream

UCS C Source Runstream

CLNT1 CLNT1/UCOB UACLSAMPLE/C CLNT1/C

CLNT1SS CLNT1SS/UCOB n/a

CLNT2 CLNT2/UCOB n/a

CLNT2SS CLNT2SS/UCOB n/a






• After the Client-Library programs have been successfully created, configure the Internet address, server name, and server port of the remote server to which the Client-Library programs will access. These configuration parameters are defined in the SERVER statement of the UniAccess Configuration File. The following syntax is an example of configuring a remote server. (See Chapter 16 in UniAccess for OS 2200 System Administration Guide for a complete description of the SERVER statement.)

SERVER ADDR,192.152.80.3 ;NAME,SYBASE10 ;PORT,2025

• Re-load the UADT using the UACF processor. (See Chapter 17 in the UniAccess for OS 2200 System Administration Guide for the execution syntax of the UACF processor.)

SQL Server Database Setup

The SSRVBLD/SQL element contains SQL commands to create the SQL Server version of the uasample database. It also contains commands to create the get_employee, get_description, and store_employee stored procedures. To run the script from Windows, it must be downloaded to a Windows workstation. The following sections provide information for a variety of installation options.

Creating the SQL Server Database from Microsoft Windows

The steps required to create the database from Windows are outlined below. The userid you use to connect to a SQL Server should permit the ability to create databases. The SSRVBLD/SQL script can be used from an ODBC client to create the SQL Server uasample database. The following steps illustrate creating the SQL Server uasample database using the Microsoft ODBC Test program.

• Connect to the appropriate data source using the ODBC Test.

• Retrieve the SSRVBLD/SQL script from the File/Open menu item.

• Execute the script in its entirety using the SQL EXECUTE statement.



Creating the SQL Server Database from OS 2200

From an OS 2200 demand session, you can use the SSRVBLD/SQL script as input to the ISQL processor provided with UniAccess Transaction Client. The userid you use to connect to SQL Server should permit the ability to create databases. See Chapter 13 of the UniAccess for OS 2200 System Administration Guide for details about ISQL input file specification.

Deleting the SQL Server Database

Use the Transact-SQL command DROP DATABASE to delete the uasample database from SQL Server.

Additional Sample Setup Information

User Definition

If UACS is configured to validate userids, all UniAccess System users must be configured in the UniAccess Configuration File. Each time a client request is received by UACS, the login information packaged with the request is validated against the list of UAUSER records maintained in UADT. Additionally, the following conditions should be met when defining users to UniAccess:

• All UniAccess Transaction Client users must have the UAUSER COMSRV configured. The following is an example of a UAUSER statement. (See Chapter 16 of the UniAccess for OS 2200 System Administration Guide for a complete description of the UAUSER statement.)

UAUSER USERID,uademo ;COMSRV,UACS ;SCHEMA,UASAMPLE

• After adding a UAUSER statement, UADT must be re-loaded using the UACF processor. (See Chapter 17 of the UniAccess for OS 2200 System Administration Guide for the execution syntax of the UACF processor.)


B Return Codes

B Return Codes

This appendix describes the RETCODE and RESULT-TYP values that may be returned by Client-Library functions.

Client-Library RETCODE Values

Table B-1 describes each of the return codes that may be passed back by functions in UniAccess Client-Library, indicating the result of the function's execution. These values are returned to the RETCODE argument, which is the second argument of most Client-Library functions.

The return codes that may be returned for a particular function are listed under the Returns section for that function in Chapter 3. A list of all return codes, with their COBOL definition statements, are supplied in the copyproc CTPUBLIC of your UniAccess System OS 2200 package.

NoteClient-Library programs should be coded using only the symbolic name of the RETCODE/RESULT-TYP, not the numeric values. These numeric values may change between product releases. They are shown in the following tables for reference purposes only.

Topics Page

Client-Library RETCODE Values B-1

CTBRESULTS RESULT-TYP Values B-3

B-2 UniAccess for OS 2200 Client-Library Programming Reference


Table B-1: RETCODE Values

Symbolic name of RETCODE

Value of RETCODE Meaning

CS-CANCELED -202 The results/operation was canceled.

CS-END-DATA -204 No more rows are available in this result set. (Note that this is also a successful completion.)

CS-END-RESULTS -205 No more result sets are available for processing.

CS-FAIL 0 The routine failed.

CS-MEM-ERROR -1 The routine failed due to a memory allocation error.

CS-NOMSG -207 The application attempted to retrieve a message whose index number is greater than the number of messages in the queue. For example, the application attempted to retrieve message number 3, when there are only 2 messages queued.

CS-ROW-FAIL -203 A recoverable error occurred while fetching a row.

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

CS-SUCCEED 1 The routine completed successfully.


Return Codes B-3

CTBRESULTS RESULT-TYP Values

Table B-2 describes each of the values that may be returned by CTBRESULTS. These values are returned by the RESULT-TYP argument. (See page 3-122 for more discussion of this argument.)

Table B-2: RESULT-TYP Values for CTBRESULTS

Symbolic name of RESULT-TYP

Value of RESULT_TYP

Meaning Result set contains:

CS-CMD-DONE 4046 The results of the request have been completely processed.

n/a

CS-CMD-FAIL 4048 The server encountered an error while executing the request. This value may indicate that the connection failed or was terminated.

No results

CS-CMD-SUCCEED 4047 A request that returns no data, such as a language request containing an insert statement, has been successful.

No results

CS-PARAM-RESULT 4042 Return parameter results have arrived. A single row of return parameters

CS-ROW-RESULT 4040 Regular row results have arrived. One or more rows of tabular data

CS-STATUS-RESULT 4043 Stored procedure return status results have arrived.

A single row containing a single status

B-4 UniAccess for OS 2200 Client-Library Programming Reference



C Client Program Messages

C Client Program Messages

This appendix describes how client program messages are returned by the UniAccess System for OS 2200. Client program messages are those client and server messages returned to the Client-Library application. These messages are handled differently than messages from other UniAccess System for OS 2200 products.

Server Messages returned by Client-Library

Client-Library returns server error messages from SQL Servers, Open Servers, and the UniAccess Transaction Server or ODBC Server. Server error messages are retrieved with Client-Library’s CTBDIAG function using a SERVERMSG structure. This structure contains two key fields that should be processed by the application program. These fields are:

• SMSG-MSGNO, which contains the error message number from the SQL Server, Open Server, or UniAccess Transaction Server

• SMSG-TEXT, which contains the actual error message text.

For a list of server messages returned by Client-Library, refer to the following sources:

SQL Servers — query and/or print the SQL Server’s SYSMESSAGES table, which contains copies of all the error messages SQL Server can return.

Topics Page

Server Messages returned by Client-Library C-1

Client Messages returned by Client-Library C-2

Client-Library Error Messages C-3

C-2 UniAccess for OS 2200 Client-Library Programming Reference


Open Servers — are defined by the application.

UniAccess Transaction Server or ODBC Server — consult the list of Server Program Messages contained in Appendix D of the UniAccess for OS 2200 System Administration Guide.

Client Messages returned by Client-Library

Client error messages are generated internally by Client-Library when it detects an error locally. They are retrieved with the CTBDIAG function call using a CLIENTMSG structure. This structure contains two key fields that should be processed by the application program:

• CMSG-OC-MSGNO contains the error message number that was locally generated by Client-Library when it detected an error. CMSG-OC-MSGNO is an encoded field consisting of four bytes. The four bytes are explained below.

Byte One. Byte 1 (the high-order byte) represents the Client-Library layer that is reporting the error. Normally, this byte is used only internally by UniAccess Client-Library. Byte Two. Byte 2 represents the message's origin and is used internally by UniAccess Client-Library.

Byte Three. Byte 3 denotes the severity of the error. The following table lists the legal values for CMSG-SEVERITY.


Client Program Messages C-3

Table C-1: Values for CLIENTMSG's CMSG-SEVERITY Field

Byte Four. Byte 4 (the low-order byte) denotes the specific error Client-Library detected.

• CMSG-OC-MSGTEXT contains the error message text.

Client-Library Error Messages

The text for all client messages generated by Client-Library’s CLIENTMSG structure can be found in the localization file for your language /character set.

Value of SEVERITY Meaning



CS-SV-RETRY-FAIL An operation has failed, but it can be retried.






C-4 UniAccess for OS 2200 Client-Library Programming Reference



D UAMM Error Messages

D UAMM Error Messages

This appendix lists the error codes returned by UniAccess Message Manager (UAMM). These error codes are returned in the Client-Library CLIENTMSG CMSG-OS-MSGNO and CMSG-OS-MSGTEXT fields. (See the CLIENTMSG Structure topic on page 2-6 and the CTBDIAG function description.).

UAMM can return both General and Detailed error message information. The message text containing the message or the description of the message in the documentation will indicate whether the message is a General or Detailed UAMM error message.

UAMM General Error Messages

1 Close request failed — library error %d

2 Connect request failed — library error %d

3 Receive request failed — library error %d

4 Unsupported driver operation called

5 Send request failed — library error %d

Sections Page

UAMM General Error Messages D-1

UAMM Detailed Error Messages D-2

D-2 UniAccess for OS 2200 Client-Library Programming Reference


6 Initialization request failed — library error %d

7 Accept request failed — library error %d

8 Exit request failed — library error %d

UAMM Detailed Error Messages

1 UAMM is already initialized.

2 Error encountered attempting to create the Management Bank.

3 Error encountered attempting to create the Process Storage Bank.

4 Error encountered attempting to create the Memory Allocation Bank.

5 Error encountered attempting to create the Primary Storage Bank.

6 Error encountered attempting to reference Secondary Storage.

7 Attempted to allocate a MMPROC but none were available. This error can occur when a site has exceeded its allowable PID configuration limit or when a site has hung UAMM processes (mmprocs).

If the error is due to exceeding the PID configuration limit, increase the number of PIDs in the COMSRV parameter of the site configuration file, if permitted. If the error is due to hung mmprocs, deactivate the fixed-gate and reactivate it. If this occurs regularly, verify that the site configuration file UAMM PROCCNT is set high enough.

8 UAMM is not initialized.

9 Client has errored or been errored by another process.

10 Primary banks are full. No memory available to allocate for messages.

11 Illegal access attempted. User program rejected.


UAMM Error Messages D-3

12 The maximum number of UACS processes are attached. Connect rejected.

13 Invalid UACS identifier. Client possibly corrupted.

14 Error encountered attempting to create the MMq Bank.

15 Attempt to release the UACS MMq failed.

16 MMq is full. Attempt to write a queue item failed.

17 Client has an invalid UAMM identifier.

18 An attempt to read from or write from the network failed.

19 Client received an event to read however no message was available.

20 Attempt to read a storage block failed.

21 UACS connect failed. A UACS with this name is already attached.

22 Attempted to allocate a context but none were available. This error can occur when a site has exceeded its allowable PID configuration limit or when a site has hung UAMM processes (mmprocs).

If the error is due to exceeding the PID configuration limit, increase the number of PIDs in the COMSRV parameter of the site configuration file, if permitted. If the error is due to hung mmprocs, deactivate the fixed-gate and reactivate it. If this occurs regularly, verify that the site configuration file UAMM PROCCNT is set high enough.

23 This UACL client has already initialized. ipd_init failed.

24 The UACS this client was communicating with is no longer available.

25 Attempt to register for termination failed.

26 Attempt to deregister for termination failed.

D-4 UniAccess for OS 2200 Client-Library Programming Reference


27 The UACS name requested by this UACL client is not attached.

28 Attempted to allocate a CSPROC but none were available.

29 Attempted to mmclose a UAMM process that is not in use.

30 Attempted to read page zero.

31 Network error. Check UACS trace file for error information.

32 Attempted to exceed maximum allowable number of endpoints.

33 Attempted to open more client connections than allowed by the product key.


E Client-Library C Kit

E Client-Library C Kit

The UniAccess for OS 2200 Client-Library C Kit provides a USC C language interface to the UniAccess Client-Library. It includes the C language headers required to interface to UACL. The C Kit reference material in this appendix should be used in conjunction with the rest of this manual.

NoteThe information contained in the UniAccess Client-Library C Header files is proprietary information of both Sybase, Inc. and Applied Information Sciences, Inc. All licensing restrictions apply to the use of these C language headers.

UniAccess C Header FilesThe Client-Library C Kit headers are placed in the standard include file: SYS$LIB$*UAINCL (or SYS$LIB$*UAINCLT for test mode installations). The elements of this file are listed in Appendix A of the UniAccess for OS 2200 System Administration Guide. This file is automatically installed with UniAccess Transaction Client 10R2.

Topics Page

UniAccess C Header Files E-1

List of Header Files E-2

Using Client-Library C Headers E-3

Client-Library C Functions E-4

E-2 UniAccess for OS 2200 Client-Library Programming Reference


There are five headers provided with the UniAccess Client-Library C Kit: ctpublic.h, cspublic.h, cstypes.h, csconfig.h, and sqlca.h. Only the ctpublic.h needs to be directly included in the user program.

A brief description of the headers follows.

List of Header Files

ctpublic.h

This header defines the symbolic constants and declarations used by Client-Library routines, as well as some internal information.

cspublic.h

This header defines data structures shared by all libraries. It is included within ctpublic.h.

cstypes.h

This header defines the basic error codes and datatypes used in all System 10 products. It is included within cspublic.h.

csconfig.h

This header hides interface differences found on various platform-compiler combinations. It is included within cstypes.h.

sqlca.h

This is the header file for the SQL structure. It is included within cspublic.h.

NoteProgrammers should not make use of the either UniAccess or Sybase internal definitions, since they may not be included in subsequent releases and they are subject to change.


Client-Library C Kit E-3

Using Client-Library C Headers

The Client-Library C headers should be included in the C program after the standard headers provided by Unisys. The sample program CLNT1/C, included on the distribution tape, provides an example of a Client-Library program in UCS C and illustrates the use of the Client-Library C headers. (Appendix A discusses this sample program, explains how to set it up, and indicates how this program works in conjunction with other UniAccess System sample programs.)

The include statements should be in the following order.

#include <stdio.h> /* Normal UC includes*/#include <stdlib.h> /* Normal UC includes*/#include <string.h> /* Normal UC includes*/#include <ctpublic.h>

At compile time, a use name of UC$PF should be attached to the file containing the Client-Library C headers. If the application utilizes multiple EXEC files containing headers, the search sequence is specified in the use name. For example, if there are three EXEC files containing header files to be used by the compilation of program ABC, the header files would have use names of UC$PF, UC$PF1, and UC$PF2.

The following example utilizes system standard and UniAccess Client-Library C headers. The UniAccess C headers are in file SYS$LIB$*UAINCL (or SYS$LIB$*UAINCLT for a test mode install).

@USE UC$PF.,SYS$LIB$*UAINCL.@ASG,A UC$PF.@UC,S MYFILE.PROG/C,TPF$.PROG/OBJ,,MYFILE.OPTIONS



Client-Library C FunctionsTable E-1 lists the Client-Library C functions supported in the UniAccess System for OS 2200 Client-Library C Kit. Most of the supported Client-Library C functions have COBOL equivalents. These functions are documented in detail in Chapter 3. The function descriptions on pages E-6 to E-50 give the functions’ syntax and a brief explanation of its parameters. They also document in full those functions that are not documented in Chapter 3 of this manual.

Table E-1: UniAccess Client-Library C Functions

C Function Client-Library Function


ct_bind CTBBIND Binds a returned column or parameter to a program variable.

E-6

ct_callback* none Installs or retrieves a Client-Library callback routine.

E-7

ct_cancel CTBCANCEL Cancels a request or the results of a request. E-12

ct_close CTBCLOSE Closes a server connection. E-13

ct_cmd_alloc CTBCMDALLOC Allocates a command handle. E-14

ct_cmd_drop CTBCMDDROP De-allocates a command handle. E-15

ct_cmd_props CTBCMDPROPS Sets, retrieves, or clears command structure properties.

E-16

ct_command CTBCOMMAND Initiates a language request or an RPC. E-17

ct_compute_info* none Returns compute result information. E-18

ct_con_alloc CTBCONALLOC Allocates a connection handle. E-23

ct_con_drop CTBCONDROP De-allocates a connection handle. E-24

ct_con_props CTBCONPROPS Sets or retrieves connection handle properties. E-25

ct_config CTBCONFIG Sets or retrieves context properties. E-26

ct_connect CTBCONNECT Connects to a server. E-27

* Descriptions of these functions are included in this appendix. They are not included in Chapter 3.


Client-Library C Kit E-5

Note All other functions are currently reserved for AIS use only.

ct_describe CTBDESCRIBE Returns a description of result data. E-28

ct_diag CTBDIAG Manages in-line error handling. E-29

ct_exit CTBEXIT Exits the programming interface. E-30

ct_fetch CTBFETCH Fetches result data. E-31

ct_get_format CTBGETFORMAT Returns the user-defined format for a result column. E-32

ct_init CTBINIT Initializes the programming interface. E-33

ct_param CTBPARAM Defines a command parameter. E-34

ct_remote_pwd CTBREMOTEPWD Defines or clears passwords to be used for server-to-server connections.

E-35

ct_res_info CTBRESINFO Returns result set information. E-36

ct_results CTBRESULTS Sets up result data to be processed. E-37

ct_send CTBSEND Sends a request to the server. E-38

cs_config CSBCONFIG Sets or retrieves global context properties. E-39

cs_convert CSBCONVERT Converts a data value from one datatype to another E-40

cs_ctx_alloc CSBCTXALLOC Allocates a context structure. E-42

cs_ctx_drop CSBCTXDROP De-allocates a context structure. E-43

cs_will_convert* none Indicates whether or not a specific datatype conversion is available in Client-Library

E-44

C Function Client-Library Function


* Descriptions of these functions are included in this appendix. They are not included in Chapter 3.

E-6 ct_bind UniAccess for OS 2200 Client-Library Programming Reference


ct_bind

Function

Bind server results to program variables.

Syntax

CS_RETCODE ct_bind ( CS_COMMAND *cmd,CS_INT item,CS_DATAFMT *datafmt,CS_VOID *buffer,CS_INT *copied,CS_SMALLINT *indicator );

Parameters

cmd — A pointer to the CS_COMMAND structure managing a client/server operation.

item — An integer representing the number of the column, parameter, or status to bind.

datafmt — A pointer to the CS_DATAFMT structure that describes the destination variable(s).

buffer — The address of an array of datafmt/count variables, each of which is of size datafmt/maxlength.

copied — The address of an array of datafmt/count integer variables.

indicator — The address of an array of datafmt/count CS_SMALLINT variables.

Comments

See Chapter 3, CTBBIND for a complete description of this function.


Client-Library C Kit ct_callback E-7

ct_callback

Function

Install or retrieve a Client-Library callback routine.

Syntax

CS_RETCODE ct_callback ( CS_CONTEXT *context,CS_CONNECTION *connection,CS_INT action,CS_INT type,(AIS_GEN_FUNC) *func );

Parameters

context — A pointer to a CS_CONTEXT structure. A CS_CONTEXT structure defines a Client-Library application context.

Either context or connection must be NULL:

— If context is supplied, the callback is installed as a default callback for the specified context. Once installed, a default callback is inherited by all connections subsequently allocated within the context.

— If context is NULL, the callback is installed for the individual connection specified by the connection.

connection — A pointer to a CS_CONNECTION structure. A CS_CONNECTION

structure contains information about a particular client/server connection.

Either context or connection must be NULL:

— If connection is supplied, the callback is installed for the specified connection.

— If connection is NULL, the callback is installed for the application context specified by the context structure.

E-8 ct_callback UniAccess for OS 2200 Client-Library Programming Reference


action — The action taken by this call. Assign action one of the following symbolic values.

type — The type of callback routine of interest. The following table lists the symbolic values that are legal for type.

func — A pointer variable.

If a callback routine is being installed, func is the address of the address of the callback routine to install.

If func is NULL, a callback routine is being de-installed.

If a callback routine is being retrieved, ct_callback sets *func to the address of the currently-installed callback routine.

Value of action Action taken by ct-callback

CS_SET Installs a callback.

CS_GET Retrieves the currently-installed callback of this type.

Value of type ct-callback installs:

CS_CLIENTMSG_CB A client message callback.

CS_COMPLETION_CB A completion callback.

CS_ENCRYPT_CB An encryption callback.

CS_CHALLENGE_CB A negotiation callback.

CS_SERVERMSG_CB A server message callback.

CS_NOTIF_CB A registered procedure notification callback.

CS_SIGNAL_CB A signal callback.



Comments

• Callbacks are user-supplied routines that are automatically called by Client-Library whenever certain triggering events, known as callback events, occur.

Some callback events are the result of a server response arriving for an application. For example, a notification callback event occurs when a registered procedure notification arrives from an Open Server.

Other callback events occur at the internal Client-Library level. For example, a client message callback event occurs when Client-Library generates an error message.

• A typical application will use ct_callback only to install callback routines. However, some applications may need to retrieve previously-installed callback routines.

• To install a callback routine, an application calls ct_callback with action as CS_SET and func as the address of the address of the callback to install.

• To retrieve the address of a previously-installed callback, an application calls ct_callback with action as CS_GET and func as a pointer to a pointer. In this case, ct_callback sets *func to the address of the current callback of the specified type. An application can save this address for re-use at a later time. Note that retrieving the address of a callback does not de-install it.

• ct_callback can be used to install a callback routine either for a context or for a particular connection. To install a callback for a context, pass connection as NULL. To install a callback for a connection, pass context as NULL.

• When a context is allocated, it has no callback routines installed. An application must specifically install any callbacks that are required.

• When a connection is allocated, it picks up default callback routines from its parent context. An application can override these default callbacks by calling ct_callback to install new callbacks at the connection level.

E-10 ct_callback UniAccess for OS 2200 Client-Library Programming Reference


• To de-install an existing callback routine, an application can call ct_callback with func as NULL. An application can also install a new callback routine at any time. The new callback will automatically replace any existing callback.

• For most types of callbacks, if no callback of a particular type is installed for a connection, Client-Library discards callback information of that type.

The client message callback is an exception to this rule. When an error or informational message is generated for a connection that has no client message callback installed, Client-Library calls the client message callback (if any) of the connection’s parent context, rather than discarding the message. If the context has no client message callback installed, then the message is discarded.

• A connection picks up its parent context’s callback routines only once, when it is allocated. This has two important implications:

— Existing connections are not affected by changes to their parent context’s callback routines.

— If a callback routine of a particular type is de-installed for a connection, the connection does not pick up its parent context’s callback routine. Instead, the connection is considered to have no callback routine of this type installed.

Example

The following example shows a typical use of ct_callback. It is taken from the sample program CLNT1/C, available on the distribution tape.

AIS_GEN_FUNC cmsgcbfunc=(AIS_GEN_FUNC)clientmsg_cb ,smsgcbfunc=(AIS_GEN_FUNC)servermsg_cb ;

...

/* ** Install client and server message handlers. */ if( CS_SUCCEED != ct_callback( Context, NULL, CS_SET, CS_CLIENTMSG_CB, (AIS_GEN_FUNC *)&cmsgcbfunc) )



{ printf( "CT-Library call to ct_callback failed\n" ); return( UA_TERMINATE ); }

...

int clientmsg_cb( CS_CONTEXT *context, CS_CONNECTION *connection, CS_CLIENTMSG *errmsg ){ printf( "Msg %ld, Layer %ld, Origin %ld, Severity %ld\n", CS_NUMBER(errmsg->msgnumber), CS_LAYER(errmsg->msgnumber), CS_ORIGIN(errmsg->msgnumber), CS_SEVERITY(errmsg->msgnumber) ); print_msg( rtrim(errmsg->msgstring) );

if( errmsg->osstringlen > 0 ) { printf( "OS error %ld\n", errmsg->osnumber ); print_msg( rtrim(errmsg->osstring) ); } return( CS_SUCCEED );}

Returns

ct_callback returns one of the following values.

See Also

ct_config, ct_con_props, and ct_connect

(CTBCONFIG, CTBCONPROPS and CTBCONNECT in Chapter 3)

Value Meaning

CS_SUCCEED The routine completed successfully.

CS_FAIL The routine failed.

E-12 ct_cancel UniAccess for OS 2200 Client-Library Programming Reference


ct_cancel

Function

Cancel a command or the results of a command.

Syntax

CS_RETCODE ct_cancel (CS_CONNECTION *connection,CS_COMMAND *cmd,CS_INT type );

Parameters

connection — A pointer to a CS_CONNECTION structure.

cmd — A pointer to the CS_COMMAND structure managing a client/ server operation.

type — The type of cancel.

Comments

See Chapter 3, CTBCANCEL for a complete description of this function.


Client-Library C Kit ct_close E-13

ct_close

Function

Close a server connection.

Syntax

CS_RETCODE ct_close (CS_CONNECTION *connection,CS_INT option );

Parameters


option — The option, if any, to use for the close.

Comments

See Chapter 3, CTBCLOSE for a complete description of this function.

E-14 ct_cmd_alloc UniAccess for OS 2200 Client-Library Programming Reference


ct_cmd_alloc

Function

Allocate a CS_COMMAND structure.

Syntax

CS_RETCODE ct_cmd_alloc (CS_CONNECTION *connection,CS_COMMAND **cmd_pointer );

Parameters


cmd_pointer — The address of a pointer variable.

Comments

See Chapter 3, CTBCMDALLOC for a complete description of this function.


Client-Library C Kit ct_cmd_drop E-15

ct_cmd_drop

Function

De-allocate a CS_COMMAND structure.

Syntax

CS_RETCODE ct_cmd_drop ( CS_COMMAND *cmd );

Parameters

cmd — A pointer to a CS_COMMAND structure.

Comments

See Chapter 3, CTBCMDDROP for a complete description of this function.

E-16 ct_cmd_props UniAccess for OS 2200 Client-Library Programming Reference


ct_cmd_props

Function

Set or retrieve command structure properties.

Syntax

CS_RETCODE ct_cmd_props (CS_COMMAND *cmd,CS_INT action,CS_INT property,CS_VOID *buffer,CS_INT buflen,CS_INT *outlen );

Parameters


action — An integer variable that has been set to one of the symbolic values, CS_SET, CS_GET, or CS_CLEAR.

property — The symbolic name of the property whose value is being set or retrieved.

buffer — If a property value is being set, buffer points to the value to use in setting the property. If a property value is being retrieved, buffer points to the space in which ct_cmd_props will place the requested information.

buflen — Generally, buflen is the length, in bytes, of *buffer.

outlen — A pointer to an integer variable.

Comments

See Chapter 3, CTBCMDPROPS for a complete description of this function.


Client-Library C Kit ct_command E-17

ct_command

Function

Initiate a language, package, RPC, message, or send-data command.

Syntax

CS_RETCODE ct_command ( CS_COMMAND *cmd,CS_INT type,CS_VOID *buffer,CS_INT buflen,CS_INT option );

Parameters

cmd — A pointer to the CS_COMMAND structure managing a client/server operation. type — The type of command to initiate.

buffer — A pointer to data space.

buflen — The length, in bytes, of the *buffer data, or CS_UNUSED if *buffer represents a fixed-length or symbolic value.

option — The option associated with this command, if any.

Comments

See Chapter 3, CTBCOMMAND for a complete description of this function.

E-18 ct_compute_info UniAccess for OS 2200 Client-Library Programming Reference


ct_compute_info

Function

Retrieve compute result information.

Syntax

CS_RETCODE ct_compute_info ( CS_COMMAND *cmd,CS_INT type,CS_INT column,CS_VOID *buffer,CS_INT buflen,CS_INT *outlen );

Parameters

cmd — A pointer to the CS_COMMAND structure managing a client/server command. type — The type of information to return. For a list of the symbolic values that are legal

for type, see Summary of Parameters on page E-19.

column — The number of the compute column of interest, as it appears in the compute row result set. Compute columns appear in the order in which they are listed in the compute clause of a select statement. The first column is number 1, the second number 2, and so forth.

buffer — A pointer to the space in which ct_compute_info will place the requested information.

If buflen indicates that *buffer is not large enough to hold the requested information, ct_compute_info returns CS_FAIL.

buflen — The length, in bytes, of the *buffer data space or CS_UNUSED if *buffer represents a fixed-length or symbolic value.


Client-Library C Kit ct_compute_info E-19


ct_compute_info sets *outlen to the length, in bytes, of the requested information.

If the requested information is larger than buflen bytes, an application can use the value of *outlen to determine how many bytes are needed to hold the information.

Summary of Parameters

The following table summarizes the parameters for ct_compute_info.

Table E-2: Summary of Parameters (ct_compute_info)

Value of type Value of column

ct_compute_info returns: *buffer is set to: *outlen is set to:

CS_BYLIST_LEN CS_UNUSED The number of elements in the bylist array.

An integer value sizeof(CS_INT)

CS_COMP_BYLIST CS_UNUSED An array containing the bylist that produced this compute row.

An array of CS_SMALLINT values.

The length of the array, in bytes.

CS_COMP_COLID The number of the compute column.

The select-list column id of the column from which the compute column derives.

An integer value. sizeof(CS_INT)

CS_COMP_ID CS_UNUSED The compute id for the current compute row.

An integer value. sizeof(CS_INT)

CS_COMP_OP The column number of the compute column.

The aggregate operator type for the compute column.

A symbolic value, one of:CS_OP_SUMCS_OP_AVGCS_OP_COUNTCS_OP_MINCS_OP_MAX

sizeof(CS_INT)



Comments

• Compute rows result from the compute clause of a select statement. A compute clause generates a compute row every time the value of its by column-list changes. A compute row will contain one column for each aggregate operator in the compute clause. If a select statement contains multiple compute clauses, separate compute rows are generated by each clause.

Each compute row returned by the server is considered to be a distinct result set. That is, each result set of type CS_COMPUTE_RESULT will contain exactly one row.

• It is only legal to call ct_compute_info when compute information is available; that is, after ct_results returns CS_COMPUTE_RESULT or CS_COMPUTEFMT.

• Each section below contains information about a particular type of compute result information.

The Bylist for a Compute Row

• A select statement’s compute clause may contain the keyword by, followed by a list of columns. This list, known as the bylist, divides the results into subgroups, based on changing values in the specified columns. The compute clause’s aggregate operators are applied to each subgroup, generating a compute row for each subgroup.

The Select-List Column ID for a Compute Column

• The select-list column id for a compute column is the select-list id of the column from which the compute column derives.

The Compute ID for this Compute Row

• A SQL select statement can have multiple compute clauses, each of which returns a separate compute row. The compute id corresponding to the first compute clause in a select statement is 1.


Client-Library C Kit ct_compute_info E-21

The Aggregate Operator for a Particular Compute Row Column

• When called with type as CS_COMP_OP, ct_compute_info sets *buffer to one of the following aggregate operator types.

Examples

Assume the following command has been executed:

select dept, name, year, sales from employee order by dept, name, year compute count(name) by dept, name

1. The call:

CS_INT mybuffer;ct_compute_info(cmd, CS_BYLIST_LEN, CS_UNUSED, &mybuffer, CS_UNUSED, CS_UNUSED);

sets mybuffer to 2, because there are two items in the bylist.

2. The call:

CS_SMALLINT mybuffer[2];CS_INT outlength;ct_compute_info(cmd, CS_COMP_BYLIST, CS_UNUSED, mybuffer, sizeof(mybuffer), &outlength)

copies the CS_SMALLINT values 1 and 2 into mybuffer[0] and mybuffer[1] to indicate that the bylist is composed of columns 1 and 2 from the select list.

*buffer set to: Indicates:

CS_OP_AVG Average aggregate operator.

CS_OP_COUNT Count aggregate operator.

CS_OP_MAX Maximum aggregate operator.

CS_OP_MIN Minimum aggregate operator.

CS_OP_SUM Sum aggregate operator.



3. The call:

CS_INT mybuffer;ct_compute_info(cmd, CS_COMP_COLID, 1, &mybuffer, CS_UNUSED,NULL);

sets mybuffer to 2, since name is the second column in the select list.

4. The call:

CS_INT mybuffer;ct_compute_info(cmd, CS_COMP_ID, CS_UNUSED, &mybuffer, CS_UNUSED, NULL);

sets mybuffer to 1 because there is only a single compute clause in the select statement.

5. The call:

CS_INT mybuffer;ct_compute_info(cmd, CS_COMP_OP, 1, &mybuffer, CS_UNUSED, NULL);

sets mybuffer to the symbolic value CS_OP_COUNT, since the aggregate operator for the first compute column is a count.

Returns

ct_compute_info returns one of the following values.

See Also

ct_bind, ct_describe, ct_res_info, and ct_results

(CTBBIND, CTBDESCRIBE, CTBRESINFO, and CTBRESULTS in Chapter 3)

Value Meaning

CS_SUCCEED The routine completed successfully.

CS_FAIL The routine failed.


Client-Library C Kit ct_con_alloc E-23

ct_con_alloc

Function

Allocate a CS_CONNECTION structure.

Syntax

CS_RETCODE ct_con_alloc (CS_CONTEXT *context,CS_CONNECTION **con_pointer );

Parameters

context — A pointer to a CS_CONTEXT structure.

con_pointer — The address of a pointer variable.

Comment

See Chapter 3, CTBCONALLOC for a complete description of this function.

E-24 ct_con_drop UniAccess for OS 2200 Client-Library Programming Reference


ct_con_drop

Function

De-allocate a CS_CONNECTION structure.

Syntax

CS_RETCODE ct_con_drop ( CS_CONNECTION *connection );

Parameter


Comments

See Chapter 3, CTBCONDROP for a complete description of this function.


Client-Library C Kit ct_con_drop E-25

ct_con_props

Function

Set or retrieve connection structure properties.

Syntax

CS_RETCODE ct_con_props (CS_CONNECTION *connection,CS_INT action,CS_INT property,CS_VOID *buffer,CS_INT buflen,CS_INT *outlen );

Parameters


action — An integer value that has been set to one of the symbolic values, CS_SET, CS_GET, or CS_CLEAR.


buffer — If a property value is being set, buffer points to the value to use in setting the property. If a buffer value is being retrieved, buffer points to the space in which ct_con_props will place the requested information.



Comments

See Chapter 3, CTBCONPROPS for a complete description of this function.

E-26 ct_config UniAccess for OS 2200 Client-Library Programming Reference


ct_config

Function

Set or retrieve context properties.

Syntax

CS_RETCODE ct_config ( CS_CONTEXT *context,CS_INT action,CS_INT property,CS_VOID *buffer,CS_INT buflen,CS_INT *outlen );

Parameters


action — An integer variable that has been set to one of the symbolic values, CS_SET, CS_GET, or CS_CLEAR.


buffer — If a property value is being set, buffer points to the value to use in setting the property. If a buffer value is being retrieved, buffer points to the space in which ct_config will place the requested information.



Comments

See Chapter 3, CTBCONFIG for a complete description of this function.


Client-Library C Kit ct_connect E-27

ct_connect

Function

Connect to a server.

Syntax

CS_RETCODE ct_connect ( CS_CONNECTION *connection,CS_CHAR *server_name,CS_INT snamelen );

Parameters


server_name — A pointer to the name of the server to connect to.

snamelen — The length, in bytes, of *server_name.

Comments

See Chapter 3, CTBCONNECT for a complete description of this function.

E-28 ct_describe UniAccess for OS 2200 Client-Library Programming Reference


ct_describe

Function

Return a description of result data.

Syntax

CS_RETCODE ct_describe ( CS_COMMAND *cmd,CS_INT item,CS_DATAFMT *datafmt );

Parameters


item — An integer representing the result item of interest.

datafmt — A pointer to a CS_DATAFMT structure.

Comments

See Chapter 3, CTBDESCRIBE for a complete description of this function.


Client-Library C Kit ct_diag E-29

ct_diag

Function

Manage in-line error handling.

Syntax

CS_RETCODE ct_diag ( CS_CONNECTION *connection,CS_INT operation,CS_INT type,CS_INT index,CS_VOID *buffer );

Parameters


operation — The operation to perform.

type — Depending on the value of operation, type indicates either the type of structure to receive message information, the type of message on which to operate, or both.

index — The index of the message of interest.

buffer — A pointer to data space.

Comments

See Chapter 3, CTBDIAG for a complete description of this function.

E-30 ct_exit UniAccess for OS 2200 Client-Library Programming Reference


ct_exit

Function

Exit Client-Library.

Syntax

CS_RETCODE ct_exit ( CS_CONTEXT *context,CS_INT option );

Parameters


option — A variable that controls the behavior of ct_exit. Legal symbolic values are CS_UNUSED and CS_FORCE_EXIT.

Comments

See Chapter 3, CTBEXIT for a complete description of this function.


Client-Library C Kit ct_fetch E-31

ct_fetch

Function

Fetch result data.

Syntax

CS_RETCODE ct_fetch (CS_COMMAND *cmd,CS_INT type,CS_INT offset,CS_INT option,CS_INT *rows_read );

Parameters

cmd — A pointer to the CS_COMMAND structure managing a client/server operation. type — This parameter is currently unused and must be passed as CS_UNUSED in order

to ensure compatibility with future versions of Client-Library.

offset — This parameter is currently unused and must be passed as CS_UNUSED in order to ensure compatibility with future versions of Client-Library.

option — This parameter is currently unused and must be passed as CS_UNUSED in order to ensure compatibility with future versions of Client-Library.

rows_read — A pointer to an integer variable.

Comments

See Chapter 3, CTBFETCH for a complete description of this function.

E-32 ct_get_format UniAccess for OS 2200 Client-Library Programming Reference


ct_get_format

Function

Return the server user-defined format string associated with a result column.

Syntax

CS_RETCODE ct_getformat (CS_COMMAND *cmd,CS_INT column,CS_VOID *buffer,CS_INT buflen,CS_INT *outlen );

Parameters


column — The number of the column whose user-defined format is desired.

buffer — A pointer to the space in which ct_getformat will place the format string. buflen — The length, in bytes, of the *buffer data space.


Comments

See Chapter 3, CTBGETFORMAT for a complete description of this function.


Client-Library C Kit ct_init E-33

ct_init

Function

Initialize Client-Library for an application context.

Syntax

CS_RETCODE ct_init ( CS_CONTEXT *context,CS_INT version );

Parameters


version — The version of Client-Library behavior that the application expects.

Comments

See Chapter 3, CTBINIT for a complete description of this function.

E-34 ct_param UniAccess for OS 2200 Client-Library Programming Reference


ct_param

Function

Define a command parameter.

Syntax

CS_RETCODE ct_param (CS_COMMAND *cmd,CS_DATAFMT *datafmt,CS_VOID *data;CS_INT datalen,CS_SMALLINT indicator );

Parameters


datafmt — A pointer to a CS_DATAFMT structure that describes the parameter.

data — The address of the parameter data.

datalen — The length, in bytes, of the parameter data.

indicator — An integer variable used to indicate a parameter with a null value.

Comments

See Chapter 3, CTBPARAM for a complete description of this function.


Client-Library C Kit ct_remote_pwd E-35

ct_remote_pwd

Function

Define or clear passwords to be used for server-to-server connections.

Syntax

CS_RETCODE ct_remote_pwd ( CS_CONNECTION *connection,CS_INT action,CS_CHAR *server_name,CS_INT snamelen,CS_CHAR *password,CS_INT pwdlen );

Parameters


action — An integer variable that has been set to one of the symbolic values, CS_SET or CS_CLEAR.

server_name — A pointer to the name of the server for which the password is being defined.

snamelen — The length, in bytes, of *server_name.

password — A pointer to the password being installed for remote logins to the *server_name server.

pwdlen — The length, in bytes, of *password.

Comments

See Chapter 3, CTBREMOTEPWD for a complete description of this function.

E-36 ct_res_info UniAccess for OS 2200 Client-Library Programming Reference


ct_res_info

Function

Retrieve current result set or command information.

Syntax

CS_RETCODE ct_res_info ( CS_COMMAND *cmd,CS_INT type,CS_VOID *buffer,CS_INT buflenCS_INT *outlen );

Parameters

cmd — A pointer to the CS_COMMAND structure managing a client/server command. type — The type of information to return.

buffer — A pointer to the space in which ct_res_info will place the requested information.

buflen — The length, in bytes, of *buffer.


Comments

See Chapter 3, CTBRESINFO for a complete description of this function.


Client-Library C Kit ct_results E-37

ct_results

Function

Set up result data to be processed.

Syntax

CS_RETCODE ct_results ( CS_COMMAND *cmd,CS_INT *result_type );

Parameters

cmd — A pointer to the CS_COMMAND structure managing a client/server operation. result_type — A pointer to an integer variable that ct_results sets to indicate the current

type of result.

Comments

See Chapter 3, CTBRESULTS for a complete description of this function.

E-38 ct_send UniAccess for OS 2200 Client-Library Programming Reference


ct_send

Function

Send a command to the server.

Syntax

CS_RETCODE ct_send ( CS_COMMAND *cmd );

Parameter


Comments

See Chapter 3, CTBSEND for a complete description of this function.


Client-Library C Kit cs_config E-39

cs_config

Function

Set or retrieve CS-Library properties.

Syntax

CS_RETCODE cs_config (CS_CONTEXT *context,CS_INT action,CS_INT property,CS_VOID *buffer,CS_INT buflen,CS_INT *outlen );

Parameters


action — An integer variable that has been set to one of the symbolic values CS-SET, CS_GET, CS_CLEAR.

property — The property whose value is being set or retrieved.

buffer — If a property value is being set, buffer points to the value to use in setting the property. If a property value is being retrieved, buffer points to the space in which cs_config will place the value of the property. If a property value is being cleared, buffer should be passed as CS_UNUSED.

buflen — Generally, buflen is the length, in bytes, of *buffer. If a property value is being set and the value in *buffer is null-terminated, buflen should be passes as CS_NULLTERM. If *buffer is a fixed-length or symbolic value, buflen should be passed as CS_UNUSED.


Comments

See Chapter 3, CSBCONFIG for a complete description of this function.

E-40 cs_convert UniAccess for OS 2200 Client-Library Programming Reference


cs_convert

Function

Convert a data value from one datatype to another.

Syntax

CS_RETCODE cs_convert ( CS_CONTXT *context,CS_DATAFMT *srcfmt,CS_VOID *srcdata,CS_DATAFMT *destfmt,CS_VOID *destdata,CS_INT *resultlen );

Parameters


srcfmt — A pointer to a CS_DATAFMT structure describing the source data format.

srcdata — A pointer to the source data.

destfmt — A pointer to a CS_DATAFMT structure describing the destination data format.

destdata — A pointer to the destination buffer space.

resultlen — A pointer to an integer variable. cs_convert sets *resultlen to the length, in bytes, of the data placed in *destdata.


Client-Library C Kit cs_convert E-41

Comments

The conversion capabilities supported for this function are described in Chapter 3, CSBCONVERT. Numerous other conversions are possible; they can be tested with cs_will_convert.

NoteThe conversions involving CS_PACKEDEC are not supported. Additionally, some conversions involving money and date datatypes may not yield correct results.

E-42 cs_ctx_alloc UniAccess for OS 2200 Client-Library Programming Reference


cs_ctx_alloc

Function

Allocate a CS_CONTEXT structure.

Syntax

CS_RETCODE cs_ctx_alloc (CS_INT version,CS_CONTEXT **cxt_pointer );

Parameters

version — The version of CS-Library behavior that the application expects.

ctx_pointer — The address of a pointer variable.

Comments

See Chapter 3, CSBCTXALLOC for a complete description of this function.


Client-Library C Kit cs_ctx_drop E-43

cs_ctx_drop

Function

De-allocate a CS_CONTEXT structure.

Syntax

CS_RETCODE cs_ctx_drop ( CS_CONTEXT *context );

Parameter


Comments

See Chapter 3, CSBCTXDROP for a complete description of this function.

E-44 cs_will_convert UniAccess for OS 2200 Client-Library Programming Reference


cs_will_convert

Function

Indicate whether or not a specific datatype conversion is available in the UniAccess Client-Library.

Syntax

CS_RETCODE cs_will_convert ( CS_CONTEXT *context,CS_INT srctype,CS_INT desttype,CS_BOOL *result );

Parameters


srctype — The datatype of the source data.

desttype — The datatype of the destination data.

result — A pointer to a boolean variable. cs_will_convert sets *result to CS_TRUE if the datatype conversion is supported and to CS_FALSE if the datatype conversion is not supported.

Comments

• cs_will_convert allows an application to determine whether or not cs_convert is capable of performing a specific conversion. When cs_convert is asked to perform a conversion it doesn’t support, it returns CS_FAIL and generates a Client-Library error.


Client-Library C Kit cs_will_convert E-45

Example

The following example shows a typical use of cs_will_convert. It is taken from the sample program CLNT1/C, available on the distribution tape.

/*** ex_display_column()*/

CS_RETCODE CS_PUBLICex_display_column(context, colfmt, data, datalength, indicator)CS_CONTEXT *context;CS_DATAFMT *colfmt;CS_VOID *data;CS_INT datalength;CS_SMALLINT indicator;{ char *null = "NULL"; char *nc = "NO CONVERT"; char *cf = "CONVERT FAILED"; CS_DATAFMT srcfmt; CS_DATAFMT destfmt; CS_INT olen; CS_CHAR wbuf[MAX_CHAR_BUF]; CS_BOOL res; CS_INT i; CS_INT disp_len;

if (indicator == CS_NULLDATA) { olen = strlen(null); strcpy(wbuf, null); } else { cs_will_convert(context, colfmt->datatype, CS_CHAR_TYPE, &res); if (res != CS_TRUE) { olen = strlen(nc); strcpy(wbuf, nc); }

E-46 cs_will_convert UniAccess for OS 2200 Client-Library Programming Reference


else { srcfmt.datatype = colfmt->datatype; srcfmt.format = colfmt->format; srcfmt.locale = colfmt->locale; srcfmt.maxlength = datalength;

memset(&destfmt, 0, sizeof(destfmt));

destfmt.maxlength = MAX_CHAR_BUF; destfmt.datatype = CS_CHAR_TYPE; destfmt.format = CS_FMT_NULLTERM; destfmt.locale = NULL;

if (cs_convert(context, &srcfmt, data, &destfmt, wbuf, &olen) != CS_SUCCEED) { olen = strlen(cf); strcpy(wbuf, cf); } else { /* ** output length include null ** termination */ olen -= 1; } } } fprintf(stdout, "%s", wbuf); fflush(stdout);

disp_len = ex_display_dlen(colfmt); for (i = 0; i < (disp_len - olen); i++) { fputc(' ', stdout); } fflush(stdout); return CS_SUCCEED;}


Client-Library C Kit cs_will_convert E-47

Returns

cs_will_convert returns one of the following values.

See Also

cs_convert

(CSBCONVERT in Chapter 3 and Datatypes in Chapter 2)

Value Meaning




F References

F References

This appendix contains a list of books, manuals, and Web sites that provide further information about products discussed in the UniAccess Documentation set. The list includes references for use at both the client and the host. A publication number is given to facilitate ordering.

AIS ReferencesUniAccess for OS 2200 Client Guide. AIS Release 10R2, Document Version:

1.00.

UniAccess for OS 2200 Client-Library Programming Reference. AIS Release 10R2, Document Version 1.00.

UniAccess for OS 2200 Server-Library Programming Reference. AIS Release 10R2, Document Version: 1.00.

UniAccess for OS 2200 System Administration Guide. AIS Release 10R2, Document Version: 1.00.

Topics Page

AIS References F-1

Microsoft References F-2

Sybase References F-2

Unisys References F-2

F-2 UniAccess for OS 2200 Client-Library Programming Reference


Microsoft ReferencesFor Microsoft manuals and technical papers, visit the following Microsoft technology home pages on the World Wide Web:

Microsoft Management Services home page, http://www.microsoft.com/ntserver/techresources/management/default.asp.

Microsoft COM Technologies home page, http://www.microsoft.com/com/tech/complus.asp.

Microsoft Universal Data Access home page, http://www.microsoft.com/data.

Sybase ReferencesFor Sybase product manuals and technical papers, visit the appropriate section of the Sybase site of the World Wide Web at: http://www.sybase.com.

Unisys ReferencesThe following documents are included in the OS 2200 series of Unisys documentation, unless otherwise noted. References preceded by an asterisk (*) are those referred to specifically in the UniAccess Documentation. Other references are provided because we feel they may be useful to those administrating the UniAccess System on the OS 2200.

*Collector Programming Reference Manual. Unisys Document Number: 7830 9887-000.

Communications Management System (CMS 1100) Installation and Configuration Guide. Unisys Document Number: 7830 9846.

Communications Management System (CMS 1100) Operations Reference Manual. Unisys Document Number: 7831 5694.

*Communications Management System (CMS 1100) Programming Reference Manual. Unisys Document Number: 7831 5827.

Cooperative Processing Communications Platform (CPComm) Configuration and Operations Guide. Unisys Document Number 7844 8438.

http://www.microsoft.com/ntserver/techresources/management/default.asp

http://www.microsoft.com/ntserver/techresources/management/default.asp

http://www.microsoft.com/com/tech/complus.asp

http://www.microsoft.com/com/tech/complus.asp

http://www.microsoft.com/data

http://www.sybase.com


References F-3

*Cooperative Processing Communications Platform (CPComm) Programming Reference Manual. Unisys Document Number 7844- 8446.

Data Management System (DMS 2200) Schema Data Definition Language (DDL) Administration, Operations, and Programming Guide. Unisys Document Number: 7831 0745.

Data Management System (DMS 2200) Subschema Data Definition Language (SDDL) Administration, Operations, and Programming Guide. Unisys Document Number: 7831 0752.

Enterprise Relational Database Server for ClearPath OS 2200 SQL Programming Reference Manual. Document Number: 7830 8610.

*EXEC System Software Executive Requests Programming Reference. Unisys Document Number: 7830 7899.

*EXEC System Software Installation and Configuration Guide. Unisys Document Number: 7830 7915.

*HMP-IX4.0 Software, Planning and Migration Overview. Unisys Document Number: 7831 0349-019.

*Integrated Recovery Conceptual Overview. Unisys Document Number: 7830 8186.

Linking System Programming Guide. Unisys Document Number: 7831 0521.

*Linking System Programming Reference Manual. Unisys Document Number: 7831 0505.

*Linking System Subsystems Programming Guide. Unisys Document Number: 7830 7451.

*Log Operations and Support Reference Manual. Unisys Document Number: 7831 0315.

*Message Control Bank (MCB) Installation Guide. Unisys Document Number: 7430 0476.



Message Control Bank (MCB) Operations Reference Manual. Unisys Document Number: 7833 1550.

*Message Control Bank (MCB) Programming Reference Manual. Unisys Document Number: 7833 1568.

*OS 1100 LINC II Installation and Operations Guide. Unisys Document Number: 7844 7935.

Relational Data Management System (RDMS 2200) Administration Guide. Unisys Document Number: 7831 0760.

*Relational Data Management System (RDMS 2200) SQL Programming Reference Manual. Unisys Document Number: 7830 8160.

*Security Planning and Administration Reference Manual. Unisys Document Number: 7831-0307.

*Service Library (SLIB) Programming Reference Manual. Unisys Document Number: 7830 7857.

*Software Library Administrator (SOLAR) End Use Reference. Unisys Document Number: 7831 0604.

System Services Programming Reference Manual. Unisys Document Number: 7833 4455.

*Transaction Processing Administration and Operations Reference Manual. Unisys Document Number: 7830 7881.

*Transaction Processing Programming Reference Manual. Unisys Document Number: 7830 7402.

*Unisys Repository Manager (UREP) Administration Guide. Unisys Document Number: 7830 8087.

*Unisys Repository Manager (UREP) Programming Reference Manual. Unisys Document Number: 7830 8079.


References F-5

*Universal Compiling System (UCS) Application Development Programming Guide. Unisys Document Number: 7831 4077.

Universal Compiling System (UCS) Conceptual Overview. Unisys Document Number: 7831 0802.

Universal Compiling System (UCS) C Programming Reference Manual Vol 1. Unisys Document Number: 7831 0422.

*Universal Compiling System (UCS) C Programming Reference Manual Vol 2. Unisys Document Number: 7831 0430.

Universal Compiling System (UCS) COBOL Programming Reference Manual Vol 1. Unisys Document Number: 7831 0448.

*Universal Compiling System (UCS) COBOL Programming Reference Manual Vol 2. Unisys Document Number: 7831 0455.

*Universal Data System (UDS) Administration and Support Reference Manual. Unisys Document Number: 7831 0737.

*Universal Data System Control (UDS Control) Conceptual Overview. Unisys Document Number: 7831 0794.

*Universal Data System (UDS) Configuration Guide. Unisys Document Number: 7844 8362.

Universal Data System Relational Data Management System (UDS RDMS) IPF SQL Interface End Use Guide. Unisys Document Number: 7831 0778.

Glossary

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G Glossary

A

application. A program or group of programs that, when executed, accomplish a particular action.

application group. A group that consists of an integrated recovery database, audit trail, data dictionary (optional), and message retention files. In the UniAccess System, multiple application groups can be configured on one OS 2200 host.

array. A structure composed of multiple identical variables that can be individually addressed.

array binding. The process of binding a result column to an array variable. At fetch time, multiple rows’ worth of the column are copied into the variable.

ASCII (American Standard Code for Information Interchange). An 8-bit code used to represent data and certain machine statements.

ASCII COBOL interface. Translation routines from the basic mode environment to the extended mode environment that allow basic mode ASCII COBOL programs to use the extended mode UniAccess Fixed-gate subsystem.

B

batch run. A type of data processing where processing is controlled by a predefined runstream. Once the runstream is started, little or no intervention by an operator or end user is required.

bind. A program binds server results to a program variable, thereby telling the program to copy the data received in a return parameter or result column into the named variable.

G-2 UniAccess for OS 2200 Client-Library Programming Reference


C

Catalog RPCs. Remote procedure calls that request RDMS and DMS catalog information used by the UniAccess ODBC Driver. In the UniAccess System, these RPCs are processed by the UARS and UAHS transactions respectively.

character set. A set of specific (usually standardized) characters with an encoding scheme that uniquely defines each character. ASCII and ISO 8859-1 (Latin 1) are two common character sets.

character set conversion. Changing the encoding scheme of a set of characters on the way into or out of a server. Conversion is used when a server and a client communicating with it use different character sets.

ClearPath IX. A family of enterprise servers, or mainframes, that are object-code compatible with 2200 Series systems.

client. In client/server architecture, clients are the part of the system that send requests to servers and process the results of those requests. (Contrast with server.)

client message structure. In UniAccess Client-Library, a structure that contains a message string and information about an error or informational message returned by the UniAccess System. This structure is defined within the Client-Library application program. If the error involves interaction with the operating system, the operating system error information will be returned to this structure. (Contrast with server message structure.)

client/server architecture. A method of distributed computing that divides the work of computing between clients and servers and defines an interface between them. Client applications provide user interface and presentation logic; they make requests of server applications. Server applications provide the logic to accept client requests, process them in a host database, and return the results to the client.

client user. In the context of this manual, a person entering commands at a workstation or a Microsoft SQL Server.

CMS 1100 (Communications Management System). CMS 1100 provides a processing path through which application systems on the host can access the services of the data transport network.


Glossary G-3

command handle. A control structure that defines a command space in which client commands are sent to a server. A Client-Library application program uses a command handle to send requests to a server and to process the results of those requests.

configuration statement. Formatted system data format (SDF) ASCII images that define entities and operational characteristics of UniAccess System components.

connection. A network path between two systems. For TCP/IP, it connects TCP modules on separate machines.

connection handle. A control structure that contains information about a particular client/server connection.

console command. A keyin that is performed at the system console or while in console mode. These commands are used to manage and derive status information from UACS.

context handle. A control structure containing information that describes an application context or operating environment. For example, a context handle defines the version of Client-Library that is in use.

CT-Library. A set of C routines and macros that allow an application to interact with a SQL Server.

current command. The request that generated the current result set.

D

datatype. A defining attribute that describes the values and operations that are legal for a variable.

dbcmd() statement. This Open Client DB-Library/C function adds text to the command buffer. It is used to generate SQL language requests.

DB-Library. A set of C routines and macros that allow an application to interact with a SQL Server.

DMS 2200 (Data Management System 2200). The software product on Unisys OS 2200 systems that is the DBMS for databases defined and structured according to a hierarchical or network data model. Conforms to the CODASYL data model.



dynamic request. In the context of this manual, a SQL language statement entered online (as in isql), incorporated in an RPC, or sent by UniAccess Client-Library and processed during execution. Dynamic refers to the language request’s flexibility and interactivity. (Contrast with static request; see language request.)

E

embedded SQL (ESQL). SQL commands that are placed in a UCS COBOL program using the special markers (or delimiters) EXEC SQL and END-EXEC. ESQL statements are compiled instead of interpreted and take two forms: static and dynamic. Static ESQL is processed more extensively at compile time than dynamic ESQL and thus executes faster. Dynamic ESQL receives more extensive run-time processing than static ESQL and provides greater flexibility.

exposed structure. A structure whose internal formats are exposed to UniAccess System programmers. Programmers can declare, manipulate, and de-allocate exposed structures directly. The DATAFMT structure in UniAccess Client-Library is an example of an exposed structure.

F

fixed-gate. A component of a subsystem that is partitioned off from the rest of the system by a combination of hardware and software.

fixed-gate shared subsystem. The extended mode equivalent of common banks. It allows multiple applications to share the same stored information.

H

hierarchical database. A data model or database that represents entities as owner-member record structures. (Contrast with relational database.)

hidden structure. A structure whose internal formats are hidden from UniAccess System programmers. Programmers must use UniAccess Client-Library functions to allocate, manipulate, and de-allocate hidden structures. The Client-Library context, command, and connection structures are hidden structures.


Glossary G-5

HLC (Host LAN Controller). A control unit that connects an OS 2200 host to an IEEE 802.3 or Ethernet LAN. In the context of this manual, the HLC connects UniAccess System on the OS 2200 host to the LAN on which clients and SQL Servers reside.

host. The hardware system on which a software application runs. In the UniAccess documentation, the term host generally refers to the OS 2200 mainframe where the UniAccess System software is running.

I

input variable. A variable that has its value specified by the program. (Contrast with output variable.)

interface components. In client/server architecture, components that connect client and server software through clearly defined, message-based protocols. Interface components (like the UACS, UAMM, and UADT components in the UniAccess System) are often incorporated within client and server systems and may be transparent to the user.

interpretive SQL. A SQL language statement that is analyzed and executed at run time.

isql. Interactive SQL parser to SQL Server.

ISQL. Applied Information Sciences’ Interactive SQL Parser for OS 2200.

I/O (Input/Output). See input variable; output variable.

L

language request (command). A language request contains character strings that represent requests in a server’s own language. Language requests are flexible and interactive. They may be entered online (as in isql) or incorporated in a client request. A language request may contain one or more language statements. (Contrast with remote procedure call.)

language transaction. A general-purpose, database-specific OS 2200 TIP transaction designed to process client language requests. The UniAccess System offers two language transactions—UniAccess Relational Service for RDMS 2200 and UniAccess Hierarchical Service for DMS 2200—and supports the creation of user-written language transactions through the UniAccess Server Library service.



link. The process of executing a linkage editor to create an executable program.

local. Usually refers to the system that is the topic under discussion. The system must be accessed directly, without using network access. In the UniAccess System documentation, local often refers to the OS 2200 host where the UniAccess System is installed. (Contrast with remote.)

logical command. Any Client-Library command defined by CTBCOMMAND, with the following exceptions: (1) Each Transact-SQL SELECT statement inside a stored procedure is a logical command. Other Transact-SQL statements inside stored procedures do not count as logical commands. (2) Each Transact-SQL statement in a language request is a logical command.

login information. The userid and password used by a client user when logging in to the system. This information is part of the client’s login definition in UADT.

login properties. Properties that are defined to the UniAccess System during login, such as the client’s userid, password, and packet size. (Contrast with negotiated properties.)

M

message text. A string of characters that relay error, warning, and informational messages to the user.

N

negotiated properties. UniAccess System properties whose values have been changed during the login process. For example, when the defined packet size is larger than the server can support, the server changes the packet size to one it can support. (Contrast with login properties.)

null. Having no explicitly assigned value. Null is not equivalent to zero or to blank. A value of null is not considered to be greater than non-nulls when sorted with an ORDER BY clause. That is, if a column is sorted in ascending order rows, a null in that column will follow all rows with non-null in that column.


Glossary G-7

O

ODBC (Microsoft® Open Database Connectivity). An interface that allows applications to access data in heterogeneous database management systems (DBMS) using Structured Query Language (SQL) as a standard for accessing data.

Open Client. An application written using the CT-Library, DB-Library, or UniAccess Client-Library API. In this document, an Open Client generally refers to a non-ODBC client. (Contrast with server.)

OS 2200 (Operating System 2200). System software for Unisys Series 1100/90 and Series 2200 systems.

output variable. A variable that returns data to a program. (Contrast with input variable.)

P

padding. Characters used to fill out the unused bytes in a field whose length is longer than the length of the actual data. A variety of characters can be used for padding, but the default is usually 0 for numeric fields and blank for character fields. Numeric fields are padded to the left of the value; character fields are padded to the right of the value.

parameter. (1) A variable that is used to pass data to and retrieve data from a routine. (2) An argument to a stored procedure.

PICTURE clause (PIC). A COBOL syntax component (also used in DMS DDL) that describes the general characteristics and editing requirements of an elementary data item. Together, the PICTURE and USAGE clauses completely define the datatype of an item. (See also USAGE clause.)

PID (Position Identifier). The internal number used by TIP to address a terminal.

precision. The maximum number of digits used by the numeric datatype of a column or input parameter.

product key. A customer-specific string provided to each UniAccess customer. It activates the features and connection limits in UniAccess that the customer purchased.



program message. Any error that is generated by a UniAccess System component or user-written transaction that is returned to a client application.

property. A named value stored in a structure. In UniAccess Client-Library, context, connection, and command structures have properties. A structure’s properties determine how it behaves.

protocol. The meaning of and sequencing rules for requests and responses used to manage a TCP/IP network, transfer data, and synchronize the states of network components.

R

RDMS 2200 (Relational Data Management System 2200). The software product on Unisys OS 2200 systems that is the DBMS for databases defined and structured according to a relational data model. RDMS 2200 has its own version of SQL that is used to access data stored in its tables.

RDMS 2200 stored procedures. A group of SQL commands that reside in RDMS 2200 and can be executed as one unit (supported by RDMS 2200 as of Level 9R1). In the UniAccess System, support for RDMS 2200 stored procedures is provided through the UniAccess Relational Service (UARS).

real time. A mode of operation in which the system’s response to input is immediate. In the real-time mode, the program generally has exclusive use of a processor.

relational database. A data model or database that represents entities as two-dimensional tables of rows and columns. (Contrast with hierarchical database.)

remote. A system, program, or device that is on the network but outside the local host. In the UniAccess System documentation, remote often refers to systems outside the OS 2200 host, such as the UniAccess ODBC Driver, SQL Servers, and Open Client software. (Contrast with local.)

remote procedure call. Specifically coded requests mapped to server software that has been designed to receive it, such as a stored procedure on a SQL Server or a UniAccess Transaction Server program. (Contrast with language request.)

request. An RPC or language request sent by a client to a server.


Glossary G-9

result data item. An individual column, parameter, or status item in a UniAccess Client-Library result set. Row result sets contain columns, a parameter result set contains parameters, and a status result set contains status.

return parameter. RPC parameters whose values can be changed at the server, then returned to the client. UniAccess Server-Library transactions send return parameters back to the client when they call TDSNDDON.

RPC. See remote procedure call.

S

scale. The number of digits to the right of the decimal point. Scale applies only to some datatypes. For exact decimal datatypes, scale is the second value specified in the datatype definition. For example, the scale of CS-NUMERIC (10,3) is 3.

server. An application that manages data and access to that data. A server accepts and processes client requests for data, then returns results to the client. Server functions can include enforcing integrity and security and, as in the case of SQL Servers, managing databases. (Contrast with client and Open Client.)

server message structure (SERVERMSG). A structure that contains a message string and information about messages returned to a client. This structure is defined within a Client-Library application program. This structure contains information about all messages received by the client application from the server application, including UniAccess Transaction Server messages. (Contrast with client message structure.)

session. In UniAccess System for OS 2200, a connection between a client application and the UniAccess System.

Site Information File. An SDF file that contains the site-specific configuration statements that define the environment in which the UniAccess System operates and specifies its operational characteristics. This file is built from a template supplied by AIS and modified by the system administrator with site-specific information. The UACF utility processes this file when it is executed. (See UniAccess Configuration Utility; contrast with UA Information File, UniAccess Configuration File.)



SQL (Structured Query Language). An industry-standard language that enables the creation, modification, and retrieval of data in a relational database.

SQLCA structure. In UniAccess Client-Library, a structure that the application can use to retrieve Client-Library and server error and informational messages.

SQLCODE structure. In UniAccess Client-Library, a structure that the application can use to retrieve Client-Library and server error and informational message codes.

SQL Server. A database server in the Microsoft client/server architecture that accepts RPCs or language requests written in Transact-SQL. SQL Servers manage multiple databases and multiple users, keep track of the actual location of data on disks, maintain mapping of logical data description to physical data storage, and maintain data and procedure caches in memory.

There are two implementations of SQL Server: Microsoft SQL Server and Sybase SQL Server (a.k.a. Adaptive Server Enterprise—ASE), which provide many similar features. When this manual refers to SQL Server, it is referring to features common to both SQL Servers. Features specific to an implementation will be identified as either Microsoft SQL Server or Sybase SQL Server.

static request. In the context of this manual a fixed-format request to a server using embedded SQL statements. (See remote procedure call; contrast with dynamic request.)

storage area. A UDS database file, actually stored in an Exec or TIP file. For RDMS, the data stored in one or more relational tables; for DMS, an area of records; for SFS, a file of PCIOS or SFS data.

stored procedure. A collection of SQL statements and an optional sequence of flow-of-control statements stored under a specific name on a server. In the UniAccess System, a stored procedure is one that has been created and exists (is stored) on a SQL server or in RDMS 2200.

T

TCP/IP (Transmission Control Protocol/Internet Protocol). An open systems network architecture and set of communications protocols.


Glossary G-11

TDPROC structure. A structure in UniAccess Server-Library that represents a client/server conversation. Once the environment has been initialized, an application must establish a logical connection between the client and the server. The TDPROC structure performs functions equivalent to those performed by the UniAccess Client-Library connection and command handles. It is analogous to the DBPROCESS structure in DB-Library.

TDS (Tabular Data Stream). Sybase’s defined application-level protocol that defines the internal format of client/server requests and replies.

TIP. An OS 2200 software product that supports development and execution of online transaction processing applications. (See transaction).

TIP session control. An OS 2200 security feature that validates the user security identity (userid and security record) as a communications path is opened to a terminal through CMS 1100.

TIP transaction. OS 2200 transactions that are created and run in an TIP environment. UAHS, UARS, and all UASL transactions are TIP transactions. UACL applications may be TIP transactions.

trace. A function whereby a record of data traffic and events is stored in a designated file. The trace function is useful for troubleshooting problems. Trace files can be set at several levels within the UniAccess System.

Transact-SQL. An enhanced version of the database language SQL. Applications can use Transact-SQL to communicate with SQL Server.

transaction. A program that runs in a TIP environment on the OS 2200 system and is initiated by a single request. In the UniAccess System for OS 2200, TIP transactions may act as either clients or servers. Client transactions may be created with UACL functions; server transactions may be created with UASL functions. The term Server-Library transaction refers to UASL transactions as well as to the UARS and UAHS language transactions.

U

UA Information File. An SDF file that contains UniAccess-specific configuration statements that define mapping and message records for the UniAccess System. This file normally does not need to be modified by the system administrator. The UACF utility processes this file when it is executed. (See UniAccess Configuration Utility; contrast with Site Information File, UniAccess Configuration File.)



UCS C interface. Two collections of C language headers, one required to interface with UniAccess Client-Library, the other required to interface with UniAccess Server-Library.

UDS (Universal Data System). An expandable, modular collection of related Unisys products used for database management.

UniAccess Client-Library (UACL). A set of standard routines (functions) that provide OS 2200 programs the ability to function as Open Clients in the Microsoft client/server architecture.

UniAccess Communication Server (UACS). The UniAccess System processor on the OS 2200 that manages network input and output for all UniAccess System clients and servers.

UniAccess Configuration File. The processed form of the two source configuration files (the UA Information File and the Site Information File) maintained by the system administrator. The UniAccess Configuration File is in a fixed-binary form that is readable by UniAccess products. The configurations in the file define the environment in which the UniAccess System operates and specify its operational characteristics. They also contain definitions of users, messages, and remote server connections. (See UniAccess Configuration Utility; contrast with Site Information File, UA Information File.)

UniAccess Configuration Utility (UACF). The processor in the UniAccess System that converts the Source Configuration File of configuration statements to the UniAccess Configuration File that is readable by UniAccess products. UACF also initializes UAFG, the fixed-gate service within the UniAccess System.

UniAccess Data Manager (UADT). A service within the UniAccess Fixed-gate that manages user definitions, message information, remote server information, and other system definition information. This data is shared by all components of the UniAccess System. (See UniAccess Fixed-gate.)

UniAccess Distributed Transaction Coordinator (UADTC). The UniAccess distributed transaction facility for Microsoft Windows. It serves as the interface between MS DTC and the OS 2200-based resource manager components; that is, it acts as a gateway forwarding two-phase commit commands between MS DTC and UniAccess on the OS 2200.

UniAccess Fixed-gate (UAFG). The system-wide fixed-gate shared subsystem that contains UADT, UASL, UACL, and UAMM services.


Glossary G-13

UniAccess Hierarchical Service for DMS 2200 (UAHS). The database language transaction in the UniAccess ODBC service for DMS 2200. A TIP transaction that allows read-only SQL access to DMS data using a relational mapping of a DMS schema and provides ODBC-style catalog information in response to client requests. UAHS supports a subset of standard SQL SELECT statement syntax and catalog procedure calls.

UniAccess Message Manager (UAMM). A service within the UniAccess Fixed-gate that manages the transport of messages between one or more UACSs and UniAccess library-based programs. (See UniAccess Fixed-gate).

UniAccess ODBC Driver (UADriver). The UniAccess implementation of Microsoft’s Open Database Connectivity (ODBC). The driver processes ODBC API function calls from a wide variety of client tools, submits SQL language and RPC requests to OS 2200 transactions, and returns results to the application.

UniAccess ODBC Server for DMS 2200. The UniAccess System server package that services client language requests to DMS 2200. The ODBC Server for DMS 2200 includes UniAccess Hierarchical Server, UniAccess Communication Server, and other components that act together as a server on the OS 2200 host, and the UniAccess ODBC Driver for client workstations.

UniAccess ODBC Server for RDMS 2200. The UniAccess System server package that services client language requests to RDMS 2200. The ODBC Server for RDMS 2200 includes UniAccess Relational Service, UniAccess Communication Server, and other components that act together as a server on the OS 2200 host, and additionally the UniAccess ODBC Driver for client workstations.

UniAccess Relational Service (UARS) for RDMS 2200. The database language transaction in the UniAccess ODBC service for RDMS 2200. A TIP transaction that allows SQL access to RDMS data, provides ODBC-style catalog information in response to client requests, and supports RDMS stored procedures.

UniAccess Security API. A UniAccess feature that establishes communication between local or third-party security systems and the UniAccess System using a request and notification protocol.

UniAccess Server-Library (UASL). A set of standard routines (functions) that provide OS 2200 programs the ability to function as servers in the Microsoft client/server architecture. The term Server-Library transaction refers to TIP transactions created with UASL functions, including the UARS and UAHS transactions.



UniAccess System for OS 2200. The Applied Information Sciences product suite that implements the Microsoft client/server architecture on the Unisys OS 2200 system.

UniAccess System servers. The three UniAccess System product packages that provide server capabilities on the OS 2200, namely UniAccess Transaction Server, UniAccess ODBC Server for RDMS 2200, and UniAccess ODBC Server for DMS 2200.

UniAccess Transaction Client. A set of standard routines (functions) that provide OS 2200 programs the ability to function as clients in the Microsoft client/server architecture.

UniAccess Transaction Server for OS 2200. The UniAccess System server package that supports access to OS 2200 resources by site-written UASL transactions. The Transaction Server includes UniAccess Server Library, UniAccess Communication Server, and other components that act together as a server on the OS 2200 host, and additionally the UniAccess ODBC Driver for client workstations.

USAGE clause. A COBOL syntax component (also used in DMS DDL) that defines the representation of a data item in storage. Together, the USAGE and PICTURE clauses completely define the datatype of an item. (See also PICTURE clause.)

user datatype. A 4-byte field provided by Open Client and TDS protocol to return user datatype information. The UARS, UAHS, and UAINFO transactions use this field to return detailed information about OS 2200 datatypes. This information is used by UADriver and is also available to user-written Open Client applications that utilize these UniAccess transactions.

user-written language transaction. A general-purpose, database-specific OS 2200 TIP transaction designed to process client language requests. The transaction would be written by a UniAccess System customer using UniAccess Server Library functions.

V

VALTAB (Program Validation Table). A TIP system file containing transaction code definitions called VALTAB entries and information on the characteristics of the associated transaction programs.

versions. An RDMS 2200 term referring to another copy of a table, which may contain different data. Many versions of a table can exist. Each version of the table is associated with the same storage area name but has a different version name attached to it within that storage area definition. Data associated with each version is stored in its own file.


Index

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . I Index

AACTION

description 2-3Adaptive Server Enterprise—ASE

a.k.a. Sybase SQL Server xvalignment

checking 2-11restrictions 2-64

allocatingcommand handles 3-25connection handles 3-41context handles 3-151structures 1-15

application nameproperty 2-37

applications(see also Client-Library applications)definition xvi

Applied Information Sciencescopyright information iireferences F-1

architectural differences8-bit-byte architecture 2-2

argumentsall are required 1-21definition xviinput xvioutput xvi

array binding 3-11

Bbinary datatypes

list of 2-21ranges 2-2

bindingarray binding 3-11to program variables 3-3

BUFBLANKSTRIPdescription 2-3

BUFFERdescription 2-3

BUFFER-LENdescription 2-3

buffersarguments affecting 2-3conventions for using 2-4

CC functions

(see Client-Library C Kit)C headers

(see Client-Library C Kit)cancel

results of a request 3-15character datatypes

list of 2-22character set conversion

property 2-37

I-2 UniAccess for OS 2200 Client-Library Programming Reference


clientdefinition xv

client messagesdescription 2-26fields C-2

Client-Librarycommunications 1-8datatypes 2-18error messages C-3exiting 3-83initializing 3-96properties 2-33sample programs A-1simple program 1-17version of 2-42

Client-Library applicationscompiling 2-9linking 2-9notes on a simple program 1-18steps in a simple program 1-17

Client-Library C KitC functions

definitions E-4listed E-4

C header filesdescribed E-2discussion E-1using E-3

Client-Library functionslist of 3-1use of 1-15

CLIENTMSG structuredescription 2-6fields C-3used with CTBDIAG 3-71

clientsdefinition 1-2types of 1-5

client/server architectureadvantages of 1-3general discussion 1-2model 1-3

closinga server connection 1-20, 3-20

CMSG-SEVERITYdefinition 2-6values of 2-7

columnsbinding results to program variables 3-4

command handlesallocating 3-25de-allocating 3-28definition 3-25retrieving properties 3-30setting properties 3-30

command numberretrieving information about 3-117

command parametersdefining 3-99

commandscurrent command 3-117language requests 3-35processing results of 1-19RPCs 3-35sending to a server 1-19, 3-130steps in sending a command 3-37, 3-130

compilingClient-Library applications 2-9

connectingto a server 3-54

connection handlesallocating 3-41de-allocating 3-45retrieving properties 3-58setting properties 3-58


Index I-3

connectionsclosing 3-20forcing a close 3-21retaining a physical connection 3-21setting maximum number of 2-39

context handlesallocating 3-151de-allocating 3-155retrieving properties 3-49, 3-134setting properties 3-49, 3-134

control structures 1-15conversions

performed by CSBCONVERT 3-147performed by CTBIND 3-10

copyprocuse of 1-21, 2-9

CS-APPNAMEdescription 2-34

CS-CHARSETCNVdescription 2-34

CS-COMMBLOCK(not supported) 2-34

CS-EXTRA-INFdescription 2-27, 2-34

CS-HOSTNAMEdescription 2-34

CS-LOC-PROPdescription 2-35

CS-LOGIN-STATUSdescription 2-35

CS-LOGIN-TIMEOUTdescription 2-35

CS-MAX-CONNECTdescription 2-35

CS-NETIOdescription 2-35

CS-NOINTERRUPTdescription 2-35

CS-PACKETSIZEdescription 2-36

CS-PASSWORDdescription 2-36

CS-TDS-VERSIONdescription 2-36values of 2-40

CS-TEXTLIMIT(not supported) 2-36

CS-TIMEOUT(not supported) 2-36

CS-TRANSACTION-NAMEdescription 2-36

CS-USERDATAdescription 2-37

CS-USERNAMEdescription 2-37

CS-VERSIONdescription 2-37

cs_will_convert (C function)description E-44

CSBCONFIGdescription 3-134

CSBCONVERTDATAFMT structure 2-13description 3-142

CSBCTXALLOCdescription 3-151

CSBCTXDROPdescription 3-155

ct_callback (C function)description E-7

ct_compute_info (C function)description E-18

CTBBINDDATAFMT structure 2-13description 3-3

CTBCANCELdescription 3-15



CTBCLOSEdescription 3-20

CTBCMDALLOCdescription 3-25

CTBCMDDROPdescription 3-28

CTBCMDPROPSdescription 3-30

CTBCOMMANDdescription 3-35

CTBCONALLOCdescription 3-41

CTBCONDROPdescription 3-45

CTBCONFIGdescription 3-49setting maximum number of connections

2-39CTBCONNECT

description 3-54CTBCONPROPS

description 3-58CTBDESCRIBE

DATAFMT structure 2-13description 3-64

CTBDIAGdescription 3-70

CTBEXITdescription 3-83

CTBFETCHdescription 3-88

CTBGETFORMATdescription 3-94

CTBINITdescription 3-96

CTBPARAMdescription 3-99Summary of Arguments table 3-102

CTBREMOTEPWDdescription 3-109

CTBRESINFOdescription 3-115

CTBRESULTScoding hints 3-124description 3-122RESULT-TYP values 3-122, B-3

CTBSENDdescription 3-130

CTPUBLIC 1-18, 1-21, 2-9current command

definition 3-117custom code 1-12

DDATAFMT structure

destination format 2-15fields 2-14fields for CTBBIND 3-5fields for CTBDESCRIBE 3-66fields for CTBPARAM 3-100

language request 3-103RPC 3-104

general description 2-13datatypes

approximate decimal 2-24binary 2-21character 2-22converted by CSBCONVERT 3-147converted by CTBBIND 3-10corresponding 2-18datetime 2-22exact decimal 2-24integer 2-24limitations for MS SQL Server 2-29money 2-25summary of 2-18

datetime datatypeslist of 2-22


Index I-5

de-allocatingcommand handles 3-28connection handles 3-45context handles 3-155

decimal datatypesapproximate 2-24exact 2-24

definingcommand parameters 3-99

DESTFMT structuredefinition 3-144fields for CSBCONVERT 3-145

EECL (executive control language)

segments 2-9EIB

pointer to 2-34encoded field bytes C-3error handling

general discussion 2-26in-line initialization 3-75in-line management 3-70

error messagesUAMM D-1

execute statementscompared to RPCs 2-43

exitingClient-Library programs 3-83

extra informationdescription 3-137property 2-38

Ffetching

regular rows 3-90result data 3-88return parameters 3-90return status 3-91

floating point datatypesin 8-bit-byte architecture 2-23

FMT-FORMATvalues of 2-15

FMT-PRECISwhen used 2-16

FMT-SCALEwhen used 2-16

FMT-STATUSvalues of 2-17

FOR XML clause 2-30

Gglobal context properties 3-137

Hhandles

command 2-57allocating 3-25de-allocating 3-28definition 3-25retrieving properties 3-30setting properties 3-30

connection 2-56allocating 3-41de-allocating 3-45retrieving properties 3-58setting properties 3-58

context 2-55allocating 3-151de-allocating 3-155retrieving properties 3-49, 3-134setting properties 3-49, 3-134

functions used with 2-55list of 2-55

hostdefinition xv

host nameproperty 2-38



Iinput arguments

definition xviinteger datatypes

list of 2-24interface

definition 1-2ISQL (Interactive SQL Parser for OS 2200)

a component of UniAccess Transaction Client xi

Llanguage requests (commands)

compared to RPCs 2-43defining arguments for 3-103definition xviinitiation 3-35

linking UACL applications 2-9eliminating dynamic memory 2-9parameter alignment checking 2-11resolving external UAFG references 2-9

localdefinition xv

locale informationproperty 2-38

logical commanddefinition 3-124

login properties 2-33login status

property 2-38login timeout

property 2-38loops 1-19

Mmaximum number of connections

property 2-39

messagesclearing 3-75Client-Library C-1discussion 2-26limiting 3-76number of 3-77retrieving 3-76type with CTBDIAG 3-70UAMM D-1

Microsoftreferences F-2

Microsoft SQL Serveraccess 2-28in the UniAccess System 1-12restrictions and limitations 2-29versions 2-28

money datatypeslist of 2-25

Nnames

maximum length of 1-21negotiated properties 2-33network I/O

property 2-39no interrupt

property 2-39ntext values 2-31null values

assigning 2-32

OOperating System messages 2-26OUTLEN

description 2-4output arguments

definition xvi


Index I-7

Ppackets

packet size property 2-39padding data 2-15passwords

clearing 3-109defining 3-109password property 2-39

precisionof datatypes 2-16

program messagesclient C-1

programming environmentpreparing 1-18

propertiesapplication name 2-37character set conversion 2-37Client-Library 2-33command handle properties 3-31extra information 2-38general discussion 2-33host name 2-38locale information 2-38login 2-33login status 2-38login timeout 2-39maximum number of connections 2-39negotiated properties 2-33network I/O 2-39no interrupt 2-39packet size 2-39password 2-40setting and retrieving 2-33Summary of Properties table 2-34TDS version 2-40text and image limit 2-40timeout 2-41

transaction name 2-41user data 2-41user name 2-42

Rranges

OS 2200 2-2real datatype

description 2-23references

AIS (Applied Information Sciences) F-1Microsoft F-2Sybase F-2Unisys F-2

remotedefinition 0-xv

remote procedure call(see RPCs)

remote server connectionslisted in the UniAccess Configuration File

2-62result data

definition 3-89fetching 3-88returning a description of 3-64

result parametersbinding to program variables 3-4

result setsdefinition 2-47, 3-117retrieving command number for 3-117retrieving number of data items 3-118retrieving number of rows 3-118returning result set information 3-115

resultsbinding to program variables 3-3canceling 3-15, 3-125determining when completely processed

3-124



general discussion 2-47processing 1-19, 2-47result type values 3-122return parameters 2-47row 2-47run-time errors 3-125setting up 3-122types of 2-47, 3-122

RESULT-TYPvalues listed B-3

RETCODEdiscussion B-1values listed B-2

return codeslisted B-2

return parametersdiscussion 2-45processing 2-45

return statusbinding to a program variable 3-4discussion 2-46processing 2-46

RPCscompared to execute (language) statements

2-43defining arguments for 3-104definition xvifunctions used with 2-44general discussion 2-43initiation 3-35results 2-45

run-time errors 3-125

Ssample programs

Client-Library A-1components of A-6databases A-7setting up A-12stored procedures A-12

Transaction Client A-1UniAccess System A-5

scaleof datatypes 2-16

server messagesdescription 2-26returned by Client-Library C-1

server name 3-54Server-Library transactions

definition xviSERVERMSG structure

description 2-49fields C-1used with CTBDIAG 3-71

serversactivities with UACL 1-7attributes of various 1-13, 1-14connecting to 1-18, 3-54definition xv, 1-2in the UniAccess Transaction Client

environment 1-10non-UniAccess System 1-14similarities and differences in 1-12types of 1-4UniAccess System 1-13

simple programnotes on 1-18steps in 1-17

SMSG-SEVERITYdefinition 2-50values of 2-50

SQL Server(see also Microsoft SQL Server)attributes of 1-14datatype correspondence 2-18definition xvdiscussion 1-11sample database A-7

setup A-14sample stored procedures A-12


Index I-9

SQLCA structuredescription 2-52

SQLCODEmapping Client-Library messages to 2-54mapping server messages to 2-54SQLCODE structure 2-54

SRCFMT structuredefinition 3-143fields for CSBCONVERT 3-143

stored proceduresbinding return status results 3-4definition xviexecuting from another server 2-44return parameters 2-45return status 2-46sample A-12two ways to execute 2-43

structurescommand 1-15connection 1-15context 1-15control, diagram illustrating relationship of

1-16control, discussion of 1-15exposed 2-59hidden (see also handles) 2-55

Sybasereferences F-2

SYBASE Open Client 1-5SYBASE Open Server 1-11

TTDS

TDS version property 2-40versions 2-28

terminatingserver connections 1-20

text and imagelimiting text and image values 2-40text and image limit property 2-40

timeoutstimeout property 2-41

transaction nameproperty 2-41

transactionsdefinitions xvi

Transact-SQL 1-12

UUACL (UniAccess Client-Library)

a component of UniAccess Transaction Client xi

general discussion 1-7UCS C interface 2-60UCS COBOL functions 3-1

UACS (UniAccess Communication Server)application programmer's tasks 2-62role of 1-8system administrator's tasks 2-62

UADriver (UniAccess ODBC Driver)inclusion in UniAccess product packages

xiiUAHS (UniAccess Hierarchical Service for

DMS 2200)a component of UniAccess ODBC Server

for DMS 2200 xiidescription 1-11

UAMM (UniAccess Message Manager)error messages

detailed D-2general D-1

UARS (UniAccess Relational Service for RDMS 2200)

a component of UniAccess ODBC Server for RDMS 2200 xii

description 1-11



UASAMPLE database (RDMS 2200)description A-7

uasample database (SQL Server)description A-7setting up A-14

UASL (UniAccess Server-Library)a component of UniAccess Transaction

Server xiidescription 1-10

UCS C interfaceClient-Library C Kit E-1equivalents for Client-Library functions

2-60UCS COBOL functions

(see Client-Library functions)UniAccess Configuration File

contains user and server definitions 1-18defines which UACS will be used 2-56definition 2-62

UniAccess ODBC Driver(see UADriver)

UniAccess ODBC Server for DMS 2200components of xiidefinition xvdescription 1-11

UniAccess ODBC Server for RDMS 2200components of xiidefinition xvdescription 1-11

UniAccess System for OS 2200definition xivdocumentation F-1general discussion 1-5sample programs A-5

UniAccess Transaction Client(see also UACL)components of xidefinition xiv

discussion 1-6sample programs

description A-1setting up A-15

UniAccess Transaction Server(see also UASL)components of xiidefinition xvdescription 1-10

uniqueidentifier datatypes 2-29Unisys

references F-2unused parameters 2-32user data

property 2-41user name

property 2-41user-defined format 3-94userids

listed in the UniAccess Configuration File 2-62

Vversion of UniAccess Client-Library

determining 3-151properties 2-42retrieving 3-137

Wword alignment

checking 2-11restrictions 2-64

WORKING STORAGE 1-21

UniAccess for OS 2200 Client-Library Programming Reference

Documents

Transcript of UniAccess for OS 2200 Client-Library Programming Reference