Shareware Overload

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Overload / ShartewareOverload.cdr / database / softc2.zip / MANUAL.DOC < prev next >

Wrap

Text File | 1990-08-02 | 351KB | 15,841 lines

SoftC Database Library Reference Manual Version 2.0 Manual and Software Copyright 1988, 1989, 1990 by SoftC, Ltd. 16820 Third Street North East Ham Lake, Minnesota 55304 Telephone (612) 434-6968 Fax (612) 780-8728 ALL RIGHTS RESERVED This document describes version 2.0 of the SoftC Database Library, released in July, 1990. SoftC Database Library License Agreement This License Agreement (Agreement) is between you (the Customer) and SoftC, Ltd. (SoftC). The Agreement pertains to the SoftC Database Library, including the object code libraries, sample programs, source code (if provided), and modifications and/or recompilations of the source code (the Product), and the documentation. In exchange for the non-exclusive right to use the Product, the Customer agrees to the following terms. OWNERSHIP AND LIMITED LICENSE: The Product is owned by SoftC and is protected by applicable copyright laws and international treaty provisions. Licensed GTDA. The Customer is granted a non-exclusive license to use the Product on a single computer system (i.e., with a single CPU) or network node at a time. COPYING AND USE: The Customer may make backup copies of the Product, but may install and use the Product (including modifications and/or recompilations of the software) on only one computer or network node at a time. This means that the Product may be used by any number of people and may be freely moved from one computer location to another, so long as there is no possibility of it being used at one location while it is being used at another. PRODUCT CODE AND DERIVATIVE WORKS: In exchange for the benefit from having access to the Product the Customer agrees to protect the copyright and other proprietary rights of SoftC. Such protection includes, but is not limited to, a) the Customer not disclosing the code (object and/or source) and the way it functions to any party not bound by this Agreement, b) the Customer not allowing any party not bound by this Agreement to copy or use the Product or documentation in violation of this Agreement and c) the Customer may not disclose, allow disclosure, transmit, or allow transmission, either directly or indirectly, of the source code to any third party without the prior written consent of SoftC. The Customer may modify and/or re-compile the Product source code solely for the Customer's use. Such modified and/or re-compiled versions, regardless of the extent of the modifications or the compiler versions, operating systems, or computer systems used, are part of the same Product under this Agreement and shall remain the property of SoftC subject to the same limitations upon transfer or use as the original Product. The Customer may reproduce and distribute application programs created using the Product without additional licenses or fees. Any 2 modification of the Product source code resulting in an application or derivative work intended for distribution requires prior written permission from SoftC and may require additional terms and fees. TRANSFER: The Customer may transfer this Agreement and Product along with all originals, any copies, and the documentation to another party provided that such party agrees in writing to be legally bound by these terms. The Customer's rights shall terminate upon transfer and the Customer agrees to discontinue immediately the use of and destroy any and all retained copies of the Product upon transfer. The software source code if provided under the license is not transferrable. LIMITED WARRANTY: The physical diskette(s) and physical documentation are warranted to be free of defects in materials and workmanship for a period of sixty (60) days from the date of original purchase. For the same period, the software is warranted against significant errors that make it unusable for the operating system and compiler version originally provided by SoftC. If the Customer notifies SoftC within this 60 day period, SoftC will replace any defective diskette and/or documentation. SoftC will attempt to correct or help the Customer to avoid errors in the software with efforts that SoftC believes suitable to the problem, or at SoftC's option, authorize a refund of the Customer's license fee. OTHER THAN THE FOREGOING WARRANTIES, SOFTC, LTD. MAKES NO WARRANTIES, EXPRESS OR IMPLIED, AND SPECIFICALLY DISCLAIMS ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE. SoftC, Ltd. FURTHER RESERVES THE RIGHT TO MAKE CHANGES TO THE SPECIFICATIONS OF THE PRODUCT WITHOUT OBLIGATION TO NOTIFY ANY PERSON OR ORGANIZATION OF SUCH CHANGES. LIMITATION OF LIABILITY: The Customer's sole remedies are set forth in the warranty clause above. SoftC's liability for damages shall not exceed SoftC's suggested retail price for the Product. In no event will SoftC be liable for any special, incidental or consequential damages even if SoftC has been advised of the possibility of the same. SUPPORT: Product support, updates, fixes, enhancements, if and as they become available, may be offered for a separate charge, but SoftC has no obligation to provide any such support, updates, fixes, or enhancements to the Product. SoftC may at its sole discretion provide or discontinue support to specific customers on separate terms determined solely by SoftC. 3 EXPORT: The Customer agrees not to allow the Product or applications created using the Product to be sent to or used in any other country except in compliance with applicable U.S. laws and regulations. If the Customer needs advice on such export laws and regulations, the Customer shall contact the U.S. Department of Commerce, Export Division, Washington, DC 20230, U.S.A. for clarification. LICENSE TERMINATION: This Agreement shall terminate upon the transfer of the Product or upon breach of any term of this Agreement by the Customer. The Customer shall cease use of the Product upon termination. In the event that Customer has received source code for the Product, upon written request by SoftC, Customer shall provide written certification by an officer of Customer that all copies of the source code have been returned or destroyed. GOVERNING LAW: This Agreement shall be governed by the laws of the State of Minnesota. If any provision of this Agreement is found void, invalid, or unenforceable, it will not affect the validity of the balance of the Agreement, which shall remain valid and enforceable according to its terms. In the event any remedy herein is determined to have failed of its essential purpose, all limitations of liability and exclusion of damages set forth herein shall remain in full force and effect. This Agreement may be modified only in writing by the Customer and an authorized representative of SoftC. Reasonable attorneys' fees and court costs shall be awarded to the prevailing party in any action brought in connection with an alleged breach of the terms of this Agreement. U.S. GOVERNMENT RESTRICTED RIGHTS: The software and documentation are provided with RESTRICTED RIGHTS. Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at 52.227-7013. Contractor/manufacturer is SoftC, Ltd. ACCEPTANCE OF AGREEMENT: The licensed use of the Product is expressly conditioned upon the Customer's acceptance of these terms. The Customer may accept these terms only by signing and returning the Registration Form. SoftC's acceptance of these terms is represented by shipment of the Product. 4 Table Of Contents Chapter 1 Introduction..........................................1 Registration.................................................1 Shareware....................................................2 Typographic Conventions......................................2 Trademarks...................................................3 Support and Updates..........................................3 Chapter 2 Before You Begin......................................4 The READ.ME File.............................................4 Library Files................................................4 Installing SoftC on Your System..............................6 SoftC Applications...........................................6 Compiling with Turbo C.......................................7 Compiling with Microsoft C...................................8 Compiling with Quick C.......................................8 Recompiling the Database Libraries...........................8 Function Naming Conventions..................................9 Chapter 3 A Database Tutorial..................................10 Sequential Files............................................10 Random Access Files.........................................10 Keys........................................................11 ISAM........................................................11 Binary Trees................................................11 B- and B+ Trees.............................................11 Chapter 4 Database Functions...................................13 dBASE Data File Functions...................................13 dBASE Data Record I/O.......................................14 dBASE Data Field I/O........................................15 File Sharing Functions......................................15 dBASEIII Memo File Functions................................16 dBASE Index File Functions..................................16 dBASE Index Page Functions..................................17 dBASE Index Key Functions...................................17 Clipper Index Functions.....................................18 FoxBASE+ Index Functions....................................18 Chapter 5 Clock & Calendar Functions...........................19 Conversion to String........................................19 Conversion to Integers......................................19 Conversion to Long Integer..................................19 Day of Week Conversions.....................................20 Month Conversions...........................................20 Date String Calculations....................................20 Date Validation and Testing.................................20 Get Current Date from DOS...................................20 Time String to Numeric Conversion...........................20 Time Numeric to String Conversion...........................20 Time String Calculations....................................21 v TABLE OF CONTENTS Time Validation.............................................21 Get Current Time from DOS...................................21 Chapter 6 Miscellaneous Functions..............................22 Program Initialization......................................22 Program Termination.........................................22 Library Version.............................................22 Default Date String Format..................................22 Errors and Warnings.........................................22 Chapter 7 Sharing Files on a LAN...............................24 Updating a Data Record......................................24 Adding or Removing a Data Record............................25 Chapter 8 The SoftC Database Library...........................27 sccdi2l.....................................................29 sccdi2s.....................................................30 sccdiget....................................................31 sccdileap...................................................32 sccdiperm...................................................33 sccdl2dow...................................................34 sccdl2i.....................................................35 sccdl2sx....................................................36 sccds2day...................................................37 sccds2dow...................................................38 sccds2i.....................................................39 sccds2lx....................................................40 sccds2mon...................................................41 sccds2s.....................................................42 sccdsday....................................................43 sccdsdiff...................................................44 sccdsget....................................................45 sccdsleap...................................................46 sccdsmonth..................................................47 sccdsperm...................................................48 sccdsvalid..................................................49 sccti2s.....................................................50 scctiget....................................................51 sccts2i.....................................................52 scctsdiff...................................................53 scctsget....................................................54 scctsvalid..................................................55 scdcbfrsz...................................................56 scdcclose...................................................58 scdccreate..................................................59 scdcexpr....................................................61 scdcflush...................................................63 scdcindex...................................................65 scdcinfo....................................................66 scdckadd....................................................68 scdckbot....................................................70 vi TABLE OF CONTENTS scdckcur....................................................72 scdckdel....................................................74 scdckfind...................................................76 scdckmake...................................................78 scdcknext...................................................81 scdckprev...................................................83 scdcktop....................................................85 scdcopenx...................................................87 scddbfrsz...................................................89 scddbof.....................................................91 scddclose...................................................92 scddcreate..................................................93 scddeof.....................................................96 scddfget....................................................97 scddfgets...................................................99 scddfinfo..................................................101 scddflush..................................................103 scddfnam2no................................................104 scddfput...................................................105 scddfputs..................................................107 scddinfo...................................................109 scddlock...................................................111 scddlud....................................................113 scddopenx..................................................114 scddpack...................................................116 scddrclear.................................................117 scddrdel...................................................118 scddrget...................................................119 scddrinfo..................................................120 scddrlock..................................................121 scddrnum...................................................123 scddrput...................................................124 scddrstat..................................................126 scddrundel.................................................127 scddsize...................................................128 scddunlock.................................................129 scdibfrsz..................................................131 scdiclose..................................................133 scdicreate.................................................134 scdiexpr...................................................136 scdiflush..................................................138 scdiindex..................................................140 scdiinfo...................................................141 scdikadd...................................................143 scdikbot...................................................145 scdikcur...................................................147 scdikdate..................................................149 scdikdel...................................................151 scdikfind..................................................153 scdikmake..................................................155 scdiknext..................................................158 vii TABLE OF CONTENTS scdiknum...................................................160 scdikprev..................................................161 scdiktop...................................................163 scdinit....................................................165 scdiopenx..................................................167 scdnbfrsz..................................................169 scdnclose..................................................171 scdncreate.................................................172 scdnexpr...................................................174 scdnflush..................................................176 scdnindex..................................................178 scdninfo...................................................179 scdnkadd...................................................181 scdnkbot...................................................183 scdnkcur...................................................185 scdnkdate..................................................187 scdnkdel...................................................188 scdnkfind..................................................190 scdnkmake..................................................192 scdnknext..................................................195 scdnkprev..................................................197 scdnktop...................................................199 scdnopenx..................................................201 scdtclose..................................................203 scdtcreate.................................................204 scdterm....................................................205 scdtinfo...................................................206 scdtopenx..................................................207 scdtpack...................................................209 scdtrget...................................................210 scdtrput...................................................212 sceclr.....................................................214 scemsg.....................................................215 Appendix A Result Codes and Messages..........................216 Warning Codes and Messages.................................216 Error Codes and Messages...................................217 Other Messages.............................................224 Appendix B Diskette TOC Demo Program..........................225 Index.........................................................227 viii Chapter 1 Introduction C is generally considered to be a "bare-bones" language. A way to put some flesh on those bones is to develop generalized functions (extensions) which may be reused in many programs. The presence of these functions can make programming a quick and simple task. The absence of these language extensions can mean many hours lost "re-inventing the wheel". Few programmers have the time required to develop and debug such a library of functions. This is where the SoftC Database Library comes in. This library is a collection of functions designed to make your applications quicker and easier to code and test. With the library you can spend time on your application not on developing tools. The SoftC Database Library adds powerful capabilities to your function library: - data, memo, and index file access functions for: dBASE III, Clipper, FoxBASE+ - dBASEIV data file functions - date and time manipulation and calculation The SoftC Database Library is intended for use as a supplement to your compiler's object libraries. It contains 120 user functions. The primary purpose of the library is to provide completely compatible access to dBASE data, memo, and index files. The clock/calendar functions have been added to enhance the core dBASE routines. The library is currently available for Microsoft C 5.x and 6.0, Quick C 1.0/2.0, and Turbo C 2.0. These routines are written entirely in C. Registration If you find this library useful, you are encouraged to register. Refer to ORDER.DOC for registration fees. To register, read the license agreement, print the file 1 CHAPTER 1, INTRODUCTION ORDER.DOC, and mail the completed form and appropriate fees to: SoftC, Ltd. 16820 Third Street N.E. Ham Lake, MN 55304-4703 USA Shareware This library is "shareware" (user supported software) NOT "public domain", which means that the SoftC Database Library (including the demonstration programs - SOFTC200.EXE and SOFTC200.ZIP) are the copyrighted property of SoftC, Ltd. Registered users are legally bound by the terms and conditions set forth in the license agreement. Everyone is granted the right to make copies and to freely share the UNMODIFIED demonstration programs. The shareware concept is an attempt to provide useful software at low cost. The expense of offering a new product by conventional means is quite high and thus discourages many independent authors and small companies from developing and promoting their ideas. Shareware is an attempt to develop a new marketing channel where products can be introduced at minimum cost. Everyone will benefit if shareware works. The user benefits by having quality products at low cost, and by being able to test software thoroughly before purchasing it. The author benefits by being able to enter the commercial software market without the need of large amounts of venture capital. But it can only work with your support. If you obtain a user supported product from a friend or coworker, and are still using it after a few weeks, then it is obviously worth something to you and you should register it. Typographic Conventions [] Square brackets enclose optional data. Boldface SoftC Database Library function names (such as scdinit) and structure names when they appear in text (but not in program examples). Underline indicate variable name "identifiers" which appear in text. 2 CHAPTER 1, INTRODUCTION Trademarks Clipper is a registered trademark of Nantucket Software. dBASE, dBASEIII, and dBASEIV are registered trademarks of Ashton-Tate. FoxBASE+ is a registered trademark of Fox Software. Microsoft is a registered trademark of Microsoft Corporation. R&R Relational Report Writer is a registered trademark of Concentric Data. SoftC is a trademark of SoftC, Ltd. Turbo C is a registered trademark of Borland International. Support and Updates Technical advice and technical support will be offered to registered users only. Registered users will also be notified when updates and new products are available. We can be contacted by: mail SoftC, Ltd. 16820 Third Street N.E. Ham Lake, MN 55304-4703 USA telephone (612) 434-6968 after 6pm Central Time modem at above number (use voice first so that we can set up the modem). GEnie "K.SCHUMANN" CompuServ 73667,3420. 3 Chapter 2 Before You Begin This chapter supplies instructions for installing the library on your hard disk and compiling the source. The READ.ME File For last minute update information not contained in this documentation, and/or a brief description of what's new with this release please read the READ.ME file. Library Files The SoftC Database Library is distributed in several archive files. The demonstration package (SOFTC200.EXE or SOFTC200.ZIP) contains twelve (12) files (you are encouraged to freely share this completely unmodified program with others): CLIPPER.C DBASE.C FOXBASE.C LICENSE.DOC MANUAL.DOC ORDER.DOC SC_BASE.H SC_CLOCK.H SOFTC.H SCDMC50S.LIB SCDMC60S.LIB SCDTC20S.LIB The source code archive (SOURCE.EXE), for users registered at that level, contains 125 files: CBFRSZ.C CCREATE.C CDI2L.C CDI2S.C CDIGET.C CDILEAP.C CDIPERM.C CDL2DOW.C CDL2I.C CDL2S.C CDS2DAY.C CDS2DOW.C CDS2I.C CDS2L.C CDS2MON.C CDS2S.C CDSDAY.C CDSDIFF.C CDSGET.C CDSLEAP.C CDSMONTH.C CDSPERM.C CDSVALID.C CEXPR.C CFLUSH.C CINDEX.C CINFO.C CKADD.C CKBOT.C CKCUR.C CKDEL.C CKFIND.C CKMAKE.C CKNEXT.C CKPREV.C CKTOP.C COPEN.C CPGET.C CPPUT.C 4 CHAPTER 2, BEFORE YOU BEGIN CTI2S.C CTIGET.C CTS2I.C CTSDIFF.C CTSGET.C CTSVALID.C DBFRSZ.C DBOF.C DCREATE.C DEOF.C DFGET.C DFINFO.C DFLUSH.C DFNAM2NO.C DFPUT.C DINFO.C DLOCK.C DLUD.C DOPEN.C DPACK.C DRCLEAR.C DRGET.C DRINFO.C DRNUM.C DRPUT.C DRSTAT.C DSIZE.C EMSG.C HCREATE.C HEOF.C HERASE.C HFLUSH.C HLEN.C HLOCK.C HREAD.C HRENAME.C HSEEK.C HSIZE.C HTELL.C HWRITE.C IBFRSZ.C ICREATE.C IEXPR.C IFLUSH.C IINDEX.C IINFO.C IKADD.C IKBOT.C IKCUR.C IKDATE.C IKDEL.C IKFIND.C IKMAKE.C IKNEXT.C IKPREV.C IKTOP.C INIT.C IOPEN.C IPGET.C IPPUT.C NBFRSZ.C NCREATE.C NEXPR.C NFLUSH.C NINDEX.C NINFO.C NKADD.C NKBOT.C NKCUR.C NKDATE.C NKDEL.C NKFIND.C NKMAKE.C NKNEXT.C NKPREV.C NKTOP.C NOPEN.C NPGET.C NPPUT.C TCREATE.C TINFO.C TOPEN.C TPACK.C TRGET.C TRPUT.C SC_BASE.NTL The Turbo C object code library archive (TC2LIBS.EXE) contains the following eleven (11) files: CLIPPER.C DBASE.C FOXBASE.C SC_BASE.H SC_CLOCK.H SOFTC.H SCDTC20S.LIB SCDTC20M.LIB SCDTC20C.LIB SCDTC20L.LIB SCDTC20H.LIB The Microsoft C 5.x object code library archive (MSC5LIBS.EXE) contains the following eleven (11) files: CLIPPER.C DBASE.C FOXBASE.C SC_BASE.H SC_CLOCK.H SOFTC.H SCDMC50S.LIB SCDMC50M.LIB SCDMC50C.LIB SCDMC50L.LIB SCDMC50H.LIB 5 CHAPTER 2, BEFORE YOU BEGIN The Microsoft C 6.0 object code library archive (MSC6LIBS.EXE) contains the following eleven (11) files: CLIPPER.C DBASE.C FOXBASE.C SC_BASE.H SC_CLOCK.H SOFTC.H SCDMC60S.LIB SCDMC60M.LIB SCDMC60C.LIB SCDMC60L.LIB SCDMC60H.LIB Installing SoftC on Your System The SoftC Database Library source code is compatible with all of the compilers which we support. The object code provided is for a specific C compiler. Many compiler manufacturers suggest a certain directory setup to enable the compiler to find the header, object, and library files. Rather than trying to explain the various manufacturers suggested directory setups, we will explain what files are required and where they are often located. The library header files need to be placed where they can be found by your compiler. In many cases this is in a special "INCLUDE" directory. Other times they are placed where your source code is found. We would suggest that they be placed where the header files for your compiler are located. Your linker will need to be able to find the SoftC object code libraries. It is suggested that these be placed where the run-time libraries for your compiler are found. The name of the library defines the compiler manufacturer and version, and the memory model for which it was compiled. All library names begin with "SCD". The next few characters specify the compiler manufacturer and version. The last character defines the memory model. For example SCDTC20S.LIB is the small memory model library for Borland's Turbo C compiler (version 2.0x). SoftC Applications A typical application skeleton has the following form: 6 CHAPTER 2, BEFORE YOU BEGIN #include <sc_base.h> /* global declarations */ void main() { /* local declarations */ scdinit(15,0); . . . /* body of application */ . . . scdterm(); } The scdinit function must be the first function called in your application and IT MUST BE CALLED ONLY ONCE. The last function should be scdterm. This is not a requirement but it is good programming practice. This function should also be called only once. See the descriptions of these functions in the library reference section of this manual. Compiling with Turbo C Turbo C provides two ways of compiling programs: the integrated environment and the command line version. In order to use the SoftC Database Library with the integrated environment a project file must be created and the appropriate library must be specified in that file: myprog /* your program name */ scdtc20s.lib /* the desired SoftC Database library */ To use the library with the command line compiler simply include the library name in the file name list: tcc -ms -I<header_file_path> -L<lib_file_path> myprog scdtc20s.lib 7 CHAPTER 2, BEFORE YOU BEGIN Compiling with Microsoft C To use the library with Microsoft's command line compiler simply include the library name in the file name list: cl /AS /Zp myprog scdmc50s.lib The above example used the small memory model for C 5.x. Use SCDMC60S.LIB for C 6.0. Compiling with Quick C To use the library with Quick C's command line compiler simply include the library name in the file name list: qcl /AS /Zp myprog /link scdmc50s.lib Recompiling the Database Libraries If you modify a SoftC Database Library source module, then that module and any related modules (if any) must be recompiled and replaced in the libraries. The library source code is compiled just like any other program. Turbo C command line: tcc -c -ms -I<header_file_path> *.c Microsoft C command line: cl /AS /c /Zp /W3 *.c 8 CHAPTER 2, BEFORE YOU BEGIN Quick C command line: qcl /AS /c /Zp /W3 *.c Refer to your compiler documentation for instructions for replacing modules in libraries. Function Naming Conventions All of the SoftC Database Library functions begin with the letters "sc". This is to differentiate them from the standard library functions. "scc" clock/calendar functions "sccd" date or calendar functions "scct" time functions "scd" database file functions "scdc" Clipper index file functions (open, close, etc.) "scdck" Clipper index key functions (add, delete, etc.) "scdd" dBASE data file functions (open, close, etc.) "scddf" dBASE data field functions "scddr" dBASE data record functions (write, read, delete, etc.) "scdi" FoxBASE+ index file functions (open, close, etc.) "scdik" FoxBASE+ index key functions (add, delete, etc.) "scdn" dBASE index file functions (open, close, etc.) "scdnk" dBASE index key functions (add, delete, etc.) "scdt" memo file functions (open, close, etc.) 9 Chapter 3 A Database Tutorial Most applications need to do some file I/O operations. Your C compiler provides you with basic functions to do general file I/O. But many cases will arise when you need to use a database within your application. The SoftC Database Library provides functions to enable you to integrate your program and dBASEIII/Clipper/FoxBASE+ compatible data, memo, and index files, and dBASEIV compatible data files. For those of you who may be unfamiliar with databases, think of a filing cabinet filled with folders of invoices ordered alphabetically by company name. If we wish to put this information "on computer" we have two choices for data file I/O: a simple sequential file, or a random access file. Sequential Files The concept of using a sequential file to store invoice data by company name is very simple. Just enter the data as it's found in the filing cabinet. To access the information just begin reading at the start of the file and continue until finished. As you can see the time required to find a specific record greatly increases as more and more records are added to the file. Also the act of adding information to the file while trying to keep it in alphabetical order becomes very time consuming due to the fact that many existing records will have to be moved in order to make room for the new record. Random Access Files By using random access techniques it becomes much easier to access any particular data record. All that is required is the desired record number and you can seek to the proper location within the data file. But how do you know which record number to use? And what about adding records in the middle of the data file? dBASE uses keys and an indexed lookup system called ISAM to solve both of these problems. 10 CHAPTER 3, A DATABASE TUTORIAL Keys Keys are generally comprised of one or more pieces of information (data fields) found in a data record. In our example the company name could be used as a key. Each key would point to one or more records found in the data file. When many keys are grouped together they form an index file. A technique called ISAM is used to access the underlying binary tree structure of the index files. ISAM The relationship between a key and the data file record number is established via a "key item". Many key items are found on an "index page". Many index pages are combined to form an "index file". The method used to navigate through the index file is called "Indexed Sequential Access Method" or ISAM. The underlying structure used in ISAM is the binary tree (or decision tree). Binary Trees Binary trees are composed of nodes. Each node contains a key item (key value, data reference, and pointers to left and right subtrees). The node that begins the tree is known as the root, and leaf nodes are found at the end of the tree. To find a particular data reference, the binary tree is traversed from the root node. At each node, the desired key is compared with the node's key; if they don't match, one branch of the node's subtree or the other is selected based on whether the desired key is less than or greater than the node's key. This process continues until a match is found or an empty subtree is encountered. Binary trees can get quite unbalanced causing erratic tree traversal times. There are two variations of the binary tree commonly used to create balanced trees: B- and B+. B- and B+ Trees Generally speaking B- trees allow more than one key item to be stored in a node (now called pages), and all the branches of the tree are of identical length. The B- tree offers significant speed advantages over binary trees, but the maintenance of a B- tree is correspondingly more complex. 11 CHAPTER 3, A DATABASE TUTORIAL Adding, modifying, or deleting a key value may result in the splitting or merging of a page, which in turns forces additional operations on the tree to rebalance it. A B+ tree is a specialized form of the B- tree that has two types of pages: internal, which only point to other pages (do not contain data reference field), and external, which contain the actual data reference (do not contain subtree fields). The advantage of the B+ tree is that the internal pages can hold more decision values than the intermediate pages of a B- tree, so that the fan out of the tree is faster and the average length of the branch is shorter. This makes up for the fact that you must always follow a B+ tree to the leaf page to get the data reference, whereas in a B- tree the data reference may be found in an intermediate page or even in the root page. dBASE and Clipper use a B- tree structure, but dBASE does not make use of the data reference in intermediate and root pages. FoxBASE+ uses a B+ tree structure. The first question above has been obviously answered, but what about the second? The answer lies in the fact that because we are using an index file we no longer have to keep the data file in alphabetical order, all we need to do is append records to the end of the data file and add a key to the index file. This ends the general discussion of databases. One note, it is good programming practice to create keys only from data fields found in the data record, this allows the reconstruction of an index file should something catastrophic happen. 12 Chapter 4 Database Functions In order to benefit fully from the SoftC Database Library, it is necessary to use only the functions found in the library when performing database I/O. When standard functions such as fprintf are used, the SoftC Database Library file manager is bypassed. This means that it can no longer keep track of the activities in your database files which can lead to unpredictable results. This is not to say that you cannot use the standard C file I/O functions found in your compiler's libraries, but their use should be restricted to non-database I/O. dBASE Data File Functions In order to use a data file it first must be opened. scddopenx will open any dBASEIII, dBASEIII+, or dBASEIV compatible data file. The SoftC Database Library file manager handle will be returned. This handle number must be used for all I/O with that specific data file. When you are finished with a data file it is good practice to close that data file via a call to scddclose. This is true for a couple of reasons: 1) the data will be safe if your application crashes, and 2) computer memory will be freed for other use. A safety net is provided by scdterm in that it will close all data, memo, and index files open at program termination. The length of the data file in bytes can be found using scddsize. The name of the data file (and other information) associated with a particular handle can be retrieved via a call to scddinfo. Also a new data file can be created by scddcreate. scddbof checks the file pointer position and returns SC_TRUE if at the beginning of the file. scddeof returns SC_TRUE if at the end of file. The date the file was created or last modified is returned by scddlud. 13 CHAPTER 4, DATABASE FUNCTIONS Record I/O will be buffered if the file was opened using the SC_BUFFER switch. scddflush will flush all buffered data to the disk. To get the current size of the I/O buffer or to change it, use scddbfrsz. dBASE Data Record I/O Having a data file is of little use unless you can manipulate the individual records. The library provides nine functions to: read/write individual records, delete/recover deleted records, manipulate I/O buffers, and retrieve information about the record structure. A data record can be read from the data file using scddrget. The actual data will be placed in an internal buffer. See the discussion on Data Field I/O for more information on accessing the individual fields found in a data record. When a data record needs to be written to the file, scddrput should be used. This function is used both for the changing of a record as well as adding new records. dBASE data records are not physically removed from the data file when they are deleted. This enables the user to change his mind and recover the deleted records for use again. The SoftC Database Library follows this guideline by providing the scddrdel function to mark a data record as deleted, and the scddrundel function to recover the record (or mark as active). When you have inactive data records which you no longer want to save use scddpack to "pack" the data file. All inactive data records will be removed from the file and the file compressed. Information about the data record structure can be retrieved by a call to scddrinfo. The record length, number of fields in the data record, and the address of the internal record buffer can be obtained in this way. scddrclear is useful in clearing the record buffer before placing data in the individual fields. The entire data record will be set to spaces (" "). This has the effect on numeric fields of placing nothing in the field rather than zero. 14 CHAPTER 4, DATABASE FUNCTIONS To get the status (active/inactive) of the current record use scddrstat. Use scddrnum to get the current record number. dBASE Data Field I/O The six data field manipulation functions provide for: the writing and reading of data to and from fields in the internal I/O buffer, the conversion of field names to field numbers, and the retrieval of the field descriptions originally setup with scddcreate. There are two types of field I/O: standard C types and ASCIIZ string. scddfput and scddfget use the standard C types below to place data in and retrieve data from individual fields in a record. scddfput attempts to properly format the data before placing it in the field. This means that the proper number of spaces, zeros, and/or a decimal point will be added as appropriate. Please see the "Default Date String Format" discussion in Chapter 6 for more information about date fields. C types dBASE types ASCIIZ string character ASCIIZ string date double float (dBASEIV BCD) char logical unsigned long memo double numeric scddfputs and scddfgets use ASCIIZ strings exclusively. It is left up to the users of these functions to ensure that the data is properly formatted. A function exists to retrieve the field descriptions (name, type, length, number of decimal places) and the length of the longest data field (scddfinfo). A field name to field number translation function (scddfnam2no) is provided to isolate your application from the structure of the data files. File Sharing Functions Three functions are available to facilitate file sharing on a local area network: scddlock (locks the entire data file), 15 CHAPTER 4, DATABASE FUNCTIONS scddrlock (locks an individual record of the data file), and scddunlock (unlocks the locked region). Please refer to Chapter 7 for more information on sharing files on a network. dBASEIII Memo File Functions dBASE stores the memo file record number in the data file. The "scddfget" functions return the record number and the "scddfput" functions expect a valid memo record number. Memo files are not automatically opened when the data files are opened. These files must be explicitly opened via scdtopenx. Any dBASEIII+ compatible memo file can be opened with this function. The SoftC Database Library file manager handle will be returned on exit. This handle number must be used for all I/O with that memo file. When you are finished with a memo file it should be closed with a call to scdtclose. The name of the memo file associated with a particular handle can be retrieved via a call to scdtinfo. A new file can be created by scdtcreate. dBASEIII inserts soft carriage returns in the memo data as it is written to the file. scdtrget will return the contents of the memo record. The user specifies whether or not the soft carriage returns are removed. scdtrput allows the user to specify whether or not soft carriage returns are added and, if added, the line length. Note that the memo file record number returned by this function should be written into the appropriate data file field by using scddfput. There will be times when the data record associated with a memo record has been physically removed (data file packed). When this occurs the memo file must be packed with scdtpack. dBASE Index File Functions In order to use an index file it first must be opened. scdnopenx will open any dBASEIII, dBASEIII+, or dBASEIV compatible index file (.NDX). The SoftC Database Library 16 CHAPTER 4, DATABASE FUNCTIONS file manager handle will be returned. This handle number must be used for all I/O with that specific index file. When you are finished with an index file, it can be closed via a call to scdnclose. Information about the index file such as the file name and length of the key expression can be retrieved by a call to scdninfo. A new index file can be created by using the function scdncreate. scdnexpr can be used to get the actual index key expression. This key expression is generally a formula listing the field names used to make the index key. For example, FIRST_NAME and LAST_NAME are both fields found in a data file. If an index key was made from the combination of these fields, the key expression could be "LAST_NAME + FIRST_NAME". The functional equivalent to dBASE's "INDEX ON" command is provided by scdnindex. This function will build an index file. dBASE Index Page Functions Page I/O will be buffered if the file was opened using the SC_BUFFER switch. scdnflush will flush all buffered data to the disk. To get the current size of the I/O buffer or to change it, use scdnbfrsz. dBASE Index Key Functions Twelve functions have been provided for use in: finding a key, moving to the next or previous key, adding/deleting a key, retrieving the current key, and building a key. There are three search functions supported: find the first key (scdnktop), find the last key (scdnkbot), and search for a specific key (scdnkfind). The keys found in this manner become the "current key". Wildcards such as "?" and "*" cannot be used. Once a particular key is found it is often desired to get the key following (scdnknext) or preceding (scdnkprev) it. These keys, if found, become the current key. Another function is provided to return the current key, scdnkcur. 17 CHAPTER 4, DATABASE FUNCTIONS It is also desirable to be able to add and delete keys from the index file. scdnkadd and scdnkdel provide these functions. A function is supplied to convert date fields to valid index keys, scdnkdate allows the user to specify the date string format. dBASE provides certain functions which may be used in a key expression. scdnkmake will build a key for you using the index key expression and the current contents of the internal record buffer of the data file. This function supports five of the more common dBASE functions: dtoc, left, right, str, and substr (and the various legitimate combinations). Note that this function is not necessary for single field character or numeric keys, but it (or scdnkdate) can be used for date keys. Clipper Index Functions All the dBASE Index File functions listed above have Clipper equivalents with the exception of scdnkdate. Clipper does not need the functionality provided by this function. FoxBASE+ Index Functions All the dBASE Index File functions listed above have FoxBASE+ equivalents. FoxBASE+ has one additional function used to create a numeric key (scdiknum). The FoxBASE+ numeric key format as stored on disk is different from 'C' doubles. 18 Chapter 5 Clock & Calendar Functions This chapter will describe the time and date functions available in the SoftC Database Library. Currently there are twenty-seven functions implemented: twenty-one calendar, and six clock. Five date string formats are supported: SC_GREGOR (mm/dd/yy), SC_GREGORL (mm/dd/yyyy), SC_JULIAN (yyyy/ddd), SC_YMD (yyyymmdd), and SC_DMY (ddmmyy). Two time string formats are supported: SC_CSHMS (hh:mm:ss) and SC_MIL (0000 - 2359). Conversion to String Internal to dBASE the date fields are formatted as SC_YMD. This format enables the date field to be used properly as an index key and ensures that the date "February 13, 1989" will always be larger than the date "December 15, 1988". Note that this date format is not the one normally used when entering or displaying dates. In fact dBASE uses the date format SC_GREGOR when it displays dates. A function sccds2s was created to allow switching between the various date formats. There are two functions available to translate from numeric dates to string format: sccdi2s, source date is three integers, and sccdl2sx, source date is a long integer. Conversion to Integers Conversion to integer date from a string is accomplished via sccds2i, and from a long integer by sccdl2i. Conversion to Long Integer Two functions are provided to assist in the conversion to a long integer date: sccdi2l translates an integer date, and sccds2lx translates a string date. 19 CHAPTER 5, CLOCK & CALENDAR FUNCTIONS Day of Week Conversions Two functions are provided to calculate the numeric day of week (0-Sunday ... 6-Saturday): sccdl2dow uses a long integer date input, and sccds2dow uses an ASCIIZ string. Two functions are available to return the day of week string: sccdsday accepts a numeric input and sccds2day uses a date string. Month Conversions sccds2mon converts from a date string to a month of year string. Another function uses the month number as input (sccdsmonth). Date String Calculations Three functions are provided to perform date calculations: sccdsdiff will compute the difference in days between two dates, sccdsperm and sccdiperm return the number of days found in the month of the desired year. sccdsperm requires an ASCIIZ string and sccdiperm requires an integer year and month as input. Date Validation and Testing Two functions are provided to test for leap year: one requires an ASCIIZ string as input (sccdsleap) and the other an integer (sccdileap). Also sccdsvalid can be used to check the validity of an ASCIIZ date string. Get Current Date from DOS The current DOS date can be returned either in a string (sccdsget) or in three integers (sccdiget). Time String to Numeric Conversion sccts2i can be used to convert an ASCIIZ string to three integers (hours, minutes, and seconds). Time Numeric to String Conversion A function is also provided to convert from integers to an ASCIIZ string: sccti2s. 20 CHAPTER 5, CLOCK & CALENDAR FUNCTIONS Time String Calculations scctsdiff can be used to calculate the difference between two ASCIIZ time strings. The difference in seconds is returned in a long integer. Time Validation A function is included in the library to validate an ASCIIZ time character string: scctsvalid. Get Current Time from DOS The current DOS time can be returned either in a string (scctsget) or in four integers (scctiget). 21 Chapter 6 Miscellaneous Functions This chapter will describe the miscellaneous functions found in the SoftC Database Library. Program Initialization scdinit sets up the SoftC Database Library file manager. Memory will be allocated for a variety of internal structures. As previously mentioned this function should be called only once at the beginning of your application. Program Termination scdterm is called at the end of your application. It will close all dBASE files (unlocking any shared files) and free the memory allocated by scdinit. It is suggested that scdterm be registered with atexit in order to activate a simple safety-net. Library Version The global variable sc_version contains the SoftC Database Library version as an ASCIIZ string. Default Date String Format The global variable sc_date_style holds the date string format style used by scddfget and scddfput. The initial value for this variable is SC_GREGOR. If, for example, you desire European/Military dates as the default style then set sc_date_style equal to SC_DMY at the beginning of your program. Errors and Warnings A global variable sc_code will contain the results of the last library function call executed. Errors are indicated by negative numbers, warnings by positive numbers greater than zero, and a zero indicates success. Most functions in the 22 CHAPTER 6, MISCELLANEOUS FUNCTIONS library will NOT execute if sc_code contains an error. Because the functions will not operate on errant information, this feature provides a small measure of security for your data. During program debug it may be advantageous to print the text message associated with the contents of sc_code. scemsg will return the address of the message associated with the contents of sc_code, which can then be printed by puts. If you desire to clear an error or warning condition either the global variable sc_code can be set to zero or the function sceclr can be used. It is preferable to use the function rather than the global variable. See Appendix A for a complete list of error and warning codes and their associated messages. 23 Chapter 7 Sharing Files on a LAN As discussed previously, the SoftC Database Library provides three functions to facilitate sharing files with dBASE on a Local Area Network (LAN): scddlock, scddrlock, and scddunlock. scddrlock is used only when you are updating an individual record. If a record is to be added to the data file or an index or memo file is to be modified (or even read), then scddlock must be used to lock the entire data file. scddunlock is used to remove either of the locks. It is NEVER a good idea to keep a record/file locked while input is solicited from the keyboard. Updating a Data Record The proper sequence to follow when updating a record (no changes required to any associated index or memo files) is: 1) Lock the record in the data file. If the record cannot be locked then wait for a period of time and try again. If after a reasonable number of retries the record still cannot be locked then fail. 2) Read the original contents of the record. 3) Unlock the record. 4) Solicit keyboard input. 5) Lock the record (as in step 1). 6) Re-read the record. 7) Verify no one else has changed it. If altered then either go back to step 3, or if changes made by others are unaffected by your changes then update modified fields and continue. 8) Update the record. 9) Unlock the record. If you think about it the reason for steps 5-7 above is fairly obvious. It is reasonable to expect that since you are updating a record someone else may want to update that 24 CHAPTER 7, SHARING FILES ON A LAN same record. Changes could be lost if steps are not taken to explicitly protect them. There will be occasions when the field modified in the record will be: 1) part of or the entire key for an index file, or 2) an added or modified memo record. When this occurs the following sequence should be followed: 1) Lock the record in the data file. If the record cannot be locked, then wait for a period of time and try again. If after a reasonable number of retries the record still cannot be locked then fail. 2) Read the original contents of the record. 3) Unlock the record. 4) Solicit keyboard input. 5) Lock the data file (similar to step 1). 6) Re-read the record. 7) Verify no one else has changed it. If altered then either unlock the file and go back to step 4, or if changes made by others are unaffected by your changes then update modified fields and continue. 8) Modify any memo or index files required. 9) Update the record. 10) Unlock the file. The memo file must be updated before the data file because the memo record number must be recorded in the data record. Adding or Removing a Data Record The proper sequence to follow when adding or removing a record is: 1) Lock the data file. If the file cannot be locked, then wait for a period of time and try again. If after a reasonable number of retries the file still cannot be locked then fail. 2) Modify memo file as needed. 3) Add or delete the record. 4) Update index file(s) as needed. 5) Unlock the file. The memo file must be updated before the data file because the memo record number must be recorded in the data record. 25 CHAPTER 7, SHARING FILES ON A LAN The index file(s) must be updated after the data record is added because the data record number is written into the index file along with the key. The locking mechanisms provided by dBASE (Clipper and FoxBASE+ as well) are very simple and crude. Many other schemes exist to provide a more elegant solution to the locking problem, but keep in mind that they are not implicitly compatible with dBASE. They will not work with dBASEIII+'s ASSIST or with R&R Report Writer, for example. We would advise caution when contemplating straying too far from the dBASE standards. 26 Chapter 8 The SoftC Database Library This chapter contains a detailed description of each of the functions in the library. Many of the code samples listed in this chapter are based upon the demo programs (versions for dBASE, Clipper, and FoxBASE+ index files) found in Appendix B. The following sample function description explains how to use this portion of the SoftC Database Library Reference Manual. 27 CHAPTER 8, THE SOFTC DATABASE LIBRARY function name USAGE function( modifier parameter[,...]); The declaration syntax for function, "parameter" names are underlined. The [,...] indicates that other parameters and their modifiers may follow. PROTOTYPE IN This lists the header files in which the function is prototyped. DESCRIPTION This describes what the function does, the parameters it takes, and any details you need in order to use the function and the related routines listed. SEE ALSO Routines related to the function about which you may wish to read are listed here. EXAMPLE A sample program listing demonstrating how the function is used. 28 CHAPTER 8, THE SOFTC DATABASE LIBRARY sccdi2l USAGE signed int sccdi2l( signed long *date, signed int year, signed int month, signed int day ); PROTOTYPE IN sc_clock.h DESCRIPTION sccdi2l converts three integer date values ("year", "month", and "day") into a long integer. The integer values are verified to be a valid date before conversion. SEE ALSO sccdl2i. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_clock.h> void main() { int year = 1990, month = 5, day = 16; long date = 0L; scdinit(20,0); sccdi2l(&date, year, month, day); printf("%d %d %d = %ld\n", year, month, day, date); scdterm(); } 29 CHAPTER 8, THE SOFTC DATABASE LIBRARY sccdi2s USAGE signed int sccdi2s( signed char *string, signed int format, signed int year, signed int month, signed int day ); PROTOTYPE IN sc_clock.h DESCRIPTION sccdi2s converts three integer date values ("year", "month", and "day") into an ASCIIZ string "string" using the date string style "format". A check is made to verify that "string" is a valid date string before exiting. Date string styles: SC_GREGOR mm/dd/yy SC_GREGORL mm/dd/yyyy SC_JULIAN yyyy/ddd SC_YMD yyyymmdd SC_DMY ddmmyy SEE ALSO sccdsvalid, sccds2i. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_clock.h> void main() { signed char d[9]; sccdi2s(d,SC_YMD,1989,2,13); puts(d); } 30 CHAPTER 8, THE SOFTC DATABASE LIBRARY sccdiget USAGE signed int sccdiget( signed int *year, signed int *month, signed int *monthday, signed int *dayofweek ); PROTOTYPE IN sc_clock.h DESCRIPTION sccdiget returns the current date in integer form from DOS. SEE ALSO sccdsget. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_clock.h> void main() { int year, month, dayofmonth, dayofweek; sccdiget(&year, &month, &dayofmonth, &dayofweek); printf("%d %d %d %d\n",year, month, dayofmonth, dayofweek); } 31 CHAPTER 8, THE SOFTC DATABASE LIBRARY sccdileap USAGE signed int sccdileap( signed int leap ); PROTOTYPE IN sc_clock.h DESCRIPTION sccdileap tests the integer year passed to it in "leap" to see if it is a leap year. RETURN VALUES SC_TRUE is leap year SC_FALSE not leap year SEE ALSO sccdsleap. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_clock.h> void main() { if (sccdileap(1989)) puts("Leap Year!"); else puts("Normal Year."); } 32 CHAPTER 8, THE SOFTC DATABASE LIBRARY sccdiperm USAGE signed int sccdiperm( signed char *days, signed int year, signed int month ); PROTOTYPE IN sc_clock.h DESCRIPTION sccdiperm calculates the number of "days" in "month" for "year". This function also senses leap year and will properly return 29 days for February. SEE ALSO sccdsperm. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_clock.h> void main() { signed char d; sccdiperm(&d,1989,3); printf("%d",d); } 33 CHAPTER 8, THE SOFTC DATABASE LIBRARY sccdl2dow USAGE signed int sccdl2dow( signed char *dayofweek, signed long date ); PROTOTYPE IN sc_clock.h DESCRIPTION sccdl2dow converts a long integer "date" to an integer "dayofweek". "dayofweek" will be a value between 0 (Sunday) and 6 (Saturday). SEE ALSO sccds2dow. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_clock.h> void main() { char dayofweek; long date; sccdi2l(&date,1990,5,16); sccdl2dow(&dayofweek,date); printf("%d\n",dayofweek); } 34 CHAPTER 8, THE SOFTC DATABASE LIBRARY sccdl2i USAGE signed int sccdl2i( signed int *year, signed int *month, signed int *day, signed long date ); PROTOTYPE IN sc_clock.h DESCRIPTION sccdl2i converts a long integer "date" into three integers: "year", "month", and "day". The long "date" is tested for validity before the conversion takes place. SEE ALSO sccdi2l. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_clock.h> void main() { int year, month, day; long date; sccdi2l(&date,1990,5,16); date++; sccdl2i(&year,&month,&day,date); printf("%d %d %d\n",year,month,day); } 35 CHAPTER 8, THE SOFTC DATABASE LIBRARY sccdl2sx USAGE signed int sccdl2sx( signed char *string, signed int format, signed long date); PROTOTYPE IN sc_clock.h DESCRIPTION sccdl2sx converts a long "date" into an ASCIIZ string "string" of the date style "format". A check is made to verify that "string" is a valid date string before exiting. Date string styles: SC_GREGOR mm/dd/yy SC_GREGORL mm/dd/yyyy SC_JULIAN yyyy/ddd SC_YMD yyyymmdd SC_DMY ddmmyy SEE ALSO sccds2lx. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_clock.h> void main() { signed char d[9]; sccdl2sx(d,SC_YMD,726489); puts(d); } 36 CHAPTER 8, THE SOFTC DATABASE LIBRARY sccds2day USAGE signed int sccds2day( signed char *dayofweek, signed char *daystr, signed int format ); PROTOTYPE IN sc_clock.h DESCRIPTION sccds2day converts an ASCIIZ string date "datestr" of style "format" to an ASCIIZ string "dayofweek". "dayofweek" will be a NULL terminated string "Sunday" ... "Saturday". Date string styles: SC_GREGOR mm/dd/yy SC_GREGORL mm/dd/yyyy SC_JULIAN yyyy/ddd SC_YMD yyyymmdd SC_DMY ddmmyy SEE ALSO sccds2dow. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_clock.h> void main() { char dayofweek[10]; sccds2day(dayofweek, "19900516", SC_YMD); printf("%s\n",dayofweek); } 37 CHAPTER 8, THE SOFTC DATABASE LIBRARY sccds2dow USAGE signed int sccds2dow( signed char *dayofweek, signed char *daystr, signed int format ); PROTOTYPE IN sc_clock.h DESCRIPTION sccds2dow converts an ASCIIZ string date "datestr" to an integer "dayofweek". "dayofweek" will be a value between 0 (Sunday) and 6 (Saturday). Date string styles: SC_GREGOR mm/dd/yy SC_GREGORL mm/dd/yyyy SC_JULIAN yyyy/ddd SC_YMD yyyymmdd SC_DMY ddmmyy SEE ALSO sccds2day. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_clock.h> void main() { char dayofweek; sccds2dow(&dayofweek, "19900516", SC_YMD); printf("%d\n",dayofweek); } 38 CHAPTER 8, THE SOFTC DATABASE LIBRARY sccds2i USAGE signed int sccds2i( signed int *year, signed int *month, signed int *day, signed char *string, signed int format ); PROTOTYPE IN sc_clock.h DESCRIPTION sccds2i converts dates from an ASCIIZ string "string" of the style "format" to three integer values ("year", "month", and "day"). A partial check is made to verify that "string" is a valid date string before attempting to convert. Date string styles: SC_GREGOR mm/dd/yy SC_GREGORL mm/dd/yyyy SC_JULIAN yyyy/ddd SC_YMD yyyymmdd SC_DMY ddmmyy SEE ALSO sccdi2s. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_clock.h> void main() { signed int y, m, d; sccds2i(&y,&m,&d,"19890213",SC_YMD); printf("%d %d %d",y,m,d); } 39 CHAPTER 8, THE SOFTC DATABASE LIBRARY sccds2lx USAGE signed int sccds2lx( signed long *date, signed char *string, signed int format ); PROTOTYPE IN sc_clock.h DESCRIPTION sccds2lx converts an ASCIIZ "string" into a long "date". The date string must be of the style "format". This date is a calculated count of days since 1/1/0001. No attempt has been made to adjust for changes made in the calendar. This function is used predominantly for date arithmetic, calculating elapsed days, etc. Date string styles: SC_GREGOR mm/dd/yy SC_GREGORL mm/dd/yyyy SC_JULIAN yyyy/ddd SC_YMD yyyymmdd SC_DMY ddmmyy EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_clock.h> void main() { signed long l; sccds2lx(&l,"19890323",SC_YMD); printf("%ld",l); } 40 CHAPTER 8, THE SOFTC DATABASE LIBRARY sccds2mon USAGE signed int sccds2mon( signed char *monthstr, signed char *date, signed int format ); PROTOTYPE IN sc_clock.h DESCRIPTION sccds2mon returns the ASCIIZ month of year ("monthstr"). The ASCIIZ date string ("date") is converted to integers under control of the date string format indicator ("format") and then the month is translated into a string. Date string styles: SC_GREGOR mm/dd/yy SC_GREGORL mm/dd/yyyy SC_JULIAN yyyy/ddd SC_YMD yyyymmdd SC_DMY ddmmyy SEE ALSO sccds2day. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_clock.h> void main() { char month[10]; sccds2mon(&month,"5/16/90",SC_GREGOR); puts(month); } 41 CHAPTER 8, THE SOFTC DATABASE LIBRARY sccds2s USAGE signed int sccds2s( signed char *outstr, signed int outformat, signed char *instr, signed int informat ); PROTOTYPE IN sc_clock.h DESCRIPTION sccds2s translates one ASCIIZ date string "instr" of "informat" to another ("outstr" of "outformat"). The input date string is converted to integers and checked for validity before being translated to a string again. This function replaces the sccdxlat function which has been removed from the library. Date string styles: SC_GREGOR mm/dd/yy SC_GREGORL mm/dd/yyyy SC_JULIAN yyyy/ddd SC_YMD yyyymmdd SC_DMY ddmmyy EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_clock.h> void main() { char day[10]; sccds2s(day, SC_GREGOR, "19900516", SC_YMD); puts(day); } 42 CHAPTER 8, THE SOFTC DATABASE LIBRARY sccdsday USAGE signed int sccdsday( signed char *daystr, signed char day ); PROTOTYPE IN sc_clock.h DESCRIPTION sccdsday returns the day of the week ASCIIZ string in "daystr" for the day specified by "day". "day" must be in the range of 0 (Sunday) to 6 (Saturday). The maximum length of the string returned will be 9 plus the NULL byte. Date string styles: SC_GREGOR mm/dd/yy SC_GREGORL mm/dd/yyyy SC_JULIAN yyyy/ddd SC_YMD yyyymmdd SC_DMY ddmmyy SEE ALSO sccdsmonth. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_clock.h> void main() { char day[10]; sccdsday(day,0); puts(day); } 43 CHAPTER 8, THE SOFTC DATABASE LIBRARY sccdsdiff USAGE signed int sccdsdiff( signed long *diff, signed char *date1, signed int format1, signed char *date2, signed int format2 ); PROTOTYPE IN sc_clock.h DESCRIPTION sccdsdiff returns the difference in days between "date1" and "date2". The two ASCIIZ date strings can be in any order, but the styles ("format1", "format2") must be valid. Date string styles: SC_GREGOR mm/dd/yy SC_GREGORL mm/dd/yyyy SC_JULIAN yyyy/ddd SC_YMD yyyymmdd SC_DMY ddmmyy SEE ALSO sccds2s, sccdi2s, sccdsvalid. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_clock.h> void main() { signed long d; sccdsdiff(&d, "19890213", SC_YMD, "19881217", SC_YMD); printf("%ld",d); } 44 CHAPTER 8, THE SOFTC DATABASE LIBRARY sccdsget USAGE signed int sccdsget( signed char *date, signed int format ); PROTOTYPE IN sc_clock.h DESCRIPTION sccdsget returns the current "date" in ASCIIZ string "format" from DOS. Date string styles: SC_GREGOR mm/dd/yy SC_GREGORL mm/dd/yyyy SC_JULIAN yyyy/ddd SC_YMD yyyymmdd SC_DMY ddmmyy SEE ALSO sccdiget, scctsget. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_clock.h> void main() { char date[10]; sccdsget(date,SC_GREGOR); puts(date); } 45 CHAPTER 8, THE SOFTC DATABASE LIBRARY sccdsleap USAGE signed int sccdsleap( signed char *leap, signed int format ); PROTOTYPE IN sc_clock.h DESCRIPTION sccdsleap tests the ASCIIZ year string formatted as "format" passed to it in "leap" to see if it is a leap year. Date string styles: SC_GREGOR mm/dd/yy SC_GREGORL mm/dd/yyyy SC_JULIAN yyyy/ddd SC_YMD yyyymmdd SC_DMY ddmmyy RETURN VALUES SC_TRUE is leap year SC_FALSE not leap year SEE ALSO sccdileap EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_clock.h> void main() { if (sccdsleap("19890101",SC_YMD)) puts("Leap Year!"); else puts("Normal Year."); } 46 CHAPTER 8, THE SOFTC DATABASE LIBRARY sccdsmonth USAGE signed int sccdsmonth( signed char *monthstr, signed char month ); PROTOTYPE IN sc_clock.h DESCRIPTION sccdsmonth returns the ASCIIZ month string in "monthstr" for the month specified by "month". "month" must be in the range of 1 (January) to 12 (December). The maximum length of the string returned will be 9 plus the NULL byte. Date string styles: SC_GREGOR mm/dd/yy SC_GREGORL mm/dd/yyyy SC_JULIAN yyyy/ddd SC_YMD yyyymmdd SC_DMY ddmmyy SEE ALSO sccdsday EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_clock.h> void main() { char month[10]; sccdsmonth(month,4); puts(month); } 47 CHAPTER 8, THE SOFTC DATABASE LIBRARY sccdsperm USAGE signed int sccdsperm( signed char *days, signed char *date, signed int format ); PROTOTYPE IN sc_clock.h DESCRIPTION sccdsperm calculates the number of "days" in the month for the year specified in "date". The date string style ("format") must be valid. This function also senses leap year and will properly return 29 days for February. Date string styles: SC_GREGOR mm/dd/yy SC_GREGORL mm/dd/yyyy SC_JULIAN yyyy/ddd SC_YMD yyyymmdd SC_DMY ddmmyy SEE ALSO sccdiperm. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_clock.h> void main() { signed char d; sccdsperm(&d, "19890325", SC_YMD); printf("%d",d); } 48 CHAPTER 8, THE SOFTC DATABASE LIBRARY sccdsvalid USAGE signed int sccdsvalid( signed char *string, signed int format ); PROTOTYPE IN sc_clock.h DESCRIPTION sccdsvalid tests the date ASCIIZ "string" passed for validity: string properly formatted (format), valid day of month, and valid month of year. Date string styles: SC_GREGOR mm/dd/yy SC_GREGORL mm/dd/yyyy SC_JULIAN yyyy/ddd SC_YMD yyyymmdd SC_DMY ddmmyy EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_clock.h> void main() { if (sccdsvalid("19890213" SC_YMD) == SC_SUCCESS) puts("Good Date."); else puts("Bad Date."); } 49 CHAPTER 8, THE SOFTC DATABASE LIBRARY sccti2s USAGE signed int sccti2s( signed char *string, signed int format, signed int hours, signed int minutes, signed int seconds ); PROTOTYPE IN sc_clock.h DESCRIPTION sccti2s converts three integer time values "hours", "minutes", and "seconds" into an ASCIIZ string "string" of the string style "format". A check is made to verify that "string" is a valid time string before exiting. Time string styles: SC_CSHMS hh:mm:ss SC_MIL European/military SEE ALSO scctsvalid, sccts2i. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_clock.h> void main() { signed char d[9]; sccti2s(d,SC_GREGOR,12,3,59); puts(d); } 50 CHAPTER 8, THE SOFTC DATABASE LIBRARY scctiget USAGE signed int scctiget( signed int *hours, signed int *minutes, signed int *seconds, signed int *fraction ); PROTOTYPE IN sc_clock.h DESCRIPTION scctiget returns the current time from DOS in integer form: "hours", "minutes", "seconds", and hundredths of a second ("fraction"). EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_clock.h> void main() { int hours, minutes, seconds, fraction; scctiget(&hours, &minutes, &seconds, &fraction); printf("%d %d %d %d\n", hours, minutes, seconds, fraction); } 51 CHAPTER 8, THE SOFTC DATABASE LIBRARY sccts2i USAGE signed int sccts2i( signed int *hours, signed int *minutes, signed int *seconds, signed char *string, signed int format ); PROTOTYPE IN sc_clock.h DESCRIPTION sccts2i converts times from an ASCIIZ string "string" of style "format" to three integer values "hour", "minute", and "second". A partial check is made to verify that "string" is a valid time string before attempting to convert. Time string styles: SC_CSHMS hh:mm:ss SC_MIL European/military SEE ALSO sccti2s. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_clock.h> void main() { signed int h, m, s; sccts2i(&h,&m,&s,"12:03:59",SC_CSHMS); printf("%d %d %d",h,m,s); } 52 CHAPTER 8, THE SOFTC DATABASE LIBRARY scctsdiff USAGE signed int scctsdiff( signed long *diff, signed char *time1, signed int format1, signed char *time2, signed int format2 ); PROTOTYPE IN sc_clock.h DESCRIPTION scctsdiff returns the difference in seconds between "time1" and "time2". The two ASCIIZ time strings can be in any order, but must be valid string styles ("format1", "format2"). Time string styles: SC_CSHMS hh:mm:ss SC_MIL European/military SEE ALSO sccti2s, scctsvalid. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_clock.h> void main() { signed long d; scctsdiff(&d, "12:03:59", SC_CSHMS, "11:30:00", SC_CSHMS); printf("%ld",d); } 53 CHAPTER 8, THE SOFTC DATABASE LIBRARY scctsget USAGE signed int scctsget( signed char *time, signed int format ); PROTOTYPE IN sc_clock.h DESCRIPTION scctsget returns the current "time" from DOS in ASCIIZ string "format". Time string styles: SC_CSHMS hh:mm:ss SC_MIL European/military EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_clock.h> void main() { char time[10]; scctsget(time,SC_MIL); puts(time); } 54 CHAPTER 8, THE SOFTC DATABASE LIBRARY scctsvalid USAGE signed int scctsvalid( signed char *string, signed int format ); PROTOTYPE IN sc_clock.h DESCRIPTION scctsvalid tests the ASCIIZ time string "string" passed for validity: string properly formatted ("format"), valid hours, minutes, and seconds. Time string styles: SC_CSHMS hh:mm:ss SC_MIL European/military EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_clock.h> void main() { if (scctsvalid("12:03:59",SC_CSHMS) == SC_SUCCESS) puts("Good Time."); else puts("Bad Time."); } 55 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdcbfrsz USAGE signed int scdcbfrsz( signed int handle, signed int *numpgs, signed int command ); PROTOTYPE IN sc_base.h DESCRIPTION scdcbfrsz will either get (SC_GETSZ) or set (SC_SETSZ) the maximum number of index pages the library file manager can keep in memory and returns it via "numpgs". This is under control of "command". EXAMPLE /* get size */ #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int ntx, numpgs; scdinit(20,0); if (scdcopenx(&ntx,"TOCNAME.NTX",SC_BUFFER) == SC_SUCCESS) { scdcbfrsz(ntx,&numpgs,SC_GETSZ); printf("Maximum number of pages = %d\n", numpgs); scdcclose(ntx); } scdterm(); } /* set size */ #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() 56 CHAPTER 8, THE SOFTC DATABASE LIBRARY { int ntx, numpgs = 5; scdinit(20,0); if (scdcopenx(&ntx,"TOCNAME.NTX",SC_BUFFER) == SC_SUCCESS) { scdcbfrsz(ntx,&numpgs,SC_SETSZ); printf("New max = %d\n",numpgs); scdcclose(ntx); } scdterm(); } 57 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdcclose USAGE signed int scdcclose( signed int handle ); PROTOTYPE IN sc_base.h DESCRIPTION scdcclose closes a Clipper index file and frees all allocated memory associated with "handle". EXAMPLE #include <softc.h> #include <sc_base.h> void main() { int ntx; scdinit(20,0); if (scdcopenx(&ntx, "TOCNAME.NTX", SC_BUFFER) == SC_SUCCESS) scdcclose(ntx); scdterm(); } 58 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdccreate USAGE signed int scdccreate( signed char *filename, signed int keytype, signed char *keyexpr, signed int keylen, signed int decpl ); PROTOTYPE IN sc_base.h DESCRIPTION scdccreate creates a Clipper index file. "keyexpr" will be translated to all upper case when the index file is created. If "keytype" is SC_CKEY, then "keyexpr" must be an ASCIIZ string consisting of one or more field names from the data record. All fields included in the expression must be of type 'c' or be translated into type 'c'. No check is made to verify this. "keylen" cannot exceed 100. If "keytype" is SC_NKEY, then "keyexpr" should consist of only one data field. "keylen" cannot exceed 19, and "decpl" must be 2 less than "keylen" and not more than 15. If "keytype" is SC_DKEY, then "keyexpr" should consist of only one data field. "keylen" and "decpl" are ignored as the length is forced to 8. When unique keys are required, OR SC_UNIQUE with "keytype". NOTES scdccreate will create a new index file even if one had already existed. 59 CHAPTER 8, THE SOFTC DATABASE LIBRARY "keyexpr" is NOT checked for validity during the file creation process. Currently only the scdckmake function uses "keyexpr". SEE ALSO scdckmake. EXAMPLE #include <sc_base.h> void main() { scdinit(20,0); scdccreate("TOCNAME.NTX", SC_DKEY, "name", 64, 0); scdterm(); } 60 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdcexpr USAGE signed int scdcexpr( signed int handle, signed char *keyexpr ); PROTOTYPE IN sc_base.h DESCRIPTION scdcexpr gets the index key expression and returns it as an ASCIIZ string into a user supplied buffer "keyexpr". The user must ensure that the buffer is large enough (the key expression length can be determined via a call to scdcinfo) to hold the entire key expression. NOTES A NULL byte will be appended to the end of the expression string returned. SEE ALSO scdcinfo. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int ntx; char buffer[512]; scdinit(20,0); if (scdcopenx(&ntx, "TOCNAME.NTX", SC_BUFFER) == SC_SUCCESS) { scdcexpr(ntx,buffer); printf("key expression = %s",buffer); scdcclose(ntx); } 61 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdterm(); } 62 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdcflush USAGE signed int scdcflush( signed int handle ); PROTOTYPE IN sc_base.h DESCRIPTION scdcflush will write the contents of the I/O cache to disk. An I/O cache will be used only if the index file was opened with SC_BUFFER command switch. SEE ALSO scdcopenx EXAMPLE #include <string.h> #include <softc.h> #include <sc_base.h> void main() { int dbf, ntx; char *key; long record; scdinit(20,0); if (scddopenx(&dbf, "TOC.DBF", SC_BUFFER) == SC_SUCCESS) { if (scdcopenx(&ntx, "TOCNAME.NTX", SC_BUFFER) == SC_SUCCESS) { scddfput(dbf,0,"TOC.DBF"); scddrput(dbf,&record,SC_ADD); scdckmake(dbf,ntx,&key); scdckadd(ntx,key,record); free(key); scdcflush(ntx); scdcclose(ntx); } scddclose(dbf); } 63 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdterm(); } 64 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdcindex USAGE signed int scdcindex( signed int datafile, signed char *filename, signed int keytype, signed char *keyexpr, signed int keylen, signed int decpl ); PROTOTYPE IN sc_base.h DESCRIPTION scdcindex will create and build a Clipper index file. A blank file will be created using "filename", "keytype", "keyexpr", "keylen", and "decpl". The resultant file will be opened, and the "datafile" will be read sequentially building keys from each data record. The index file will be closed at exit. The "datafile" must be open prior to the function call. SEE ALSO scdccreate EXAMPLE #include <softc.h> #include <sc_base.h> void main() { int dbf; scdinit(20,0); if (scddopenx(&dbf,"TOC.DBF",SC_BUFFER) == SC_SUCCESS) { scdcindex(dbf, "TOCNAME.NTX", SC_CKEY, "NAME", 64, 0); scddclose(dbf); } scdterm(); } 65 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdcinfo USAGE signed int scdcinfo( signed int handle, SC_NTXINFO *info ); PROTOTYPE IN sc_base.h DESCRIPTION scdcinfo gets the filename of the index file associated with "handle", the index key type, the maximum index key length and number of decimal places (numeric keys) , and the length of the index key expression via the structure: typedef struct { signed char fname[80]; /* file name */ signed char keylen; /* key length */ signed char keydpl; /* decimal places */ signed char exprlen; /* expression len */ SC_FLAGS flags; /* misc. flags */ } SC_NTXINFO; NOTES If you are using the value returned for the index expression to dynamically allocate memory to hold the key expression, be sure to add one to the length before allocation. SEE ALSO scdcopenx. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { 66 CHAPTER 8, THE SOFTC DATABASE LIBRARY int ntx; SC_NTXINFO info; scdinit(20,0); if (scdcopenx(&ntx, "TOCNAME.NTX", SC_BUFFER) == SC_SUCCESS) { scdcinfo(ntx,&info); printf("File name = %s\n",info.fname); printf("Maximum key length = %d\n",info.keylen); printf("Number of decimals = %d\n,info.keydpl); printf("Key expression length = %d\n",info.exprlen); scdcclose(ntx); } scdterm(); } 67 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdckadd USAGE signed int scdckadd( signed int handle, void *key, signed long recno ); PROTOTYPE IN sc_base.h DESCRIPTION scdckadd will add "key" to the index file specified by "handle". "recno" is the data record number to be associated with "key" (the data record pointed to by recno must exist prior to calling scdckadd). NOTES When adding character keys it is not necessary to pad the key string to size with spaces (" "), because the function will automatically do this for you. SEE ALSO scdckmake. EXAMPLE #include <string.h> #include <softc.h> #include <sc_base.h> void main() { int dbf, ntx; char name[65] = "ABC.DEF"; long recno; scdinit(20,0); if (scddopenx(&dbf,"TOC.DBF",0) == SC_SUCCESS) { if (scdcopenx(&ntx, "TOCNAME.NTX", SC_BUFFER) == SC_SUCCESS) { 68 CHAPTER 8, THE SOFTC DATABASE LIBRARY scddfputs(dbf,0,name); if (scddrput(dbf,&recno,SC_ADD) == SC_SUCCESS) scdckadd(ntx,name,recno); scdcclose(ntx); } scddclose(dbf) } scdterm(); } 69 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdckbot USAGE signed int scdckbot( signed int handle, void *key, signed long *recno ); PROTOTYPE IN sc_base.h DESCRIPTION scdckbot will set the current key pointer to the last logical key in the index and return the key value "key" and data record number "recno" associated with the new current key. NOTES The user must ensure that the buffer used to return the key is large enough to hold the entire key. The maximum length of the key can be determined via a call to scdcinfo. All keys are returned as strings. SEE ALSO scdcinfo. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int ntx; char name[65]; long recno; scdinit(20,0); if (scdcopenx(&ntx, "TOCNAME.NTX", SC_BUFFER) == 70 CHAPTER 8, THE SOFTC DATABASE LIBRARY SC_SUCCESS) { name[64] = 0; scdckbot(ntx,name,&recno); printf("%s %ld\n",name,recno); scdcclose(ntx); } scdterm(); } 71 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdckcur USAGE signed int scdckcur( signed int handle, void *key, signed long *recno ); PROTOTYPE IN sc_base.h DESCRIPTION scdckcur will return the key value "key" and data record number "recno" associated with the current key in the index file. The current key pointer must be set by a call to either scdckfind, scdcktop, scdckbot, scdcknext, or scdckprev before calling scdckcur. NOTES The user must ensure that the buffer used to return the key is large enough to hold the entire key. The maximum length of the key can be determined via a call to scdcinfo. SEE ALSO scdcinfo, scdckfind, scdcktop, scdckbot, scdcknext, scdckprev. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int ntx; char date[17], dat[17]; long recno, recn; 72 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdinit(20,0); if (scdcopenx(&ntx, "TOCDATE.NTX", SC_BUFFER) == SC_SUCCESS) { date[16] = 0; dat[16] = 0; scdcktop(ntx,date,&recn); scdckcur(ntx,dat,&recno); printf("%s %s %ld %ld\n", date,dat,recno,recn); scdcclose(ntx); } scdterm(); } 73 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdckdel USAGE signed int scdckdel( signed int handle, void *key, signed long recno ); PROTOTYPE IN sc_base.h DESCRIPTION scdckdel will remove "key" from the index file specified by "handle". "recno" is used along with "key" to ensure that the proper key has been removed from the index file. NOTES When deleting keys it is not necessary to pad the key string to size with spaces (" "), the function will automatically do this for you. SEE ALSO scdckadd. EXAMPLE #include <string.h> #include <softc.h> #include <sc_base.h> void main() { int ntx; char date[17]; scdinit(20,0); if (scdcopenx(&ntx, "TOCDATE.NTX", SC_BUFFER) == SC_SUCCESS) { strcpy(date,"12/05/8815:30:04"); scdckdel(ntx,date,7L); scdcclose(ntx); } 74 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdterm(); } 75 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdckfind USAGE signed int scdckfind( signed int handle, void *key, signed long *recno, signed int method ); PROTOTYPE IN sc_base.h DESCRIPTION scdckfind supports two key search methods (determined by "method"): SC_EXACT - find an exact match with "key" and "recno", and SC_FIRST - find the first logical occurrence of "key" in the index and return the associated record number "recno" if found. If a match cannot be found, the current key will be the physical key which would immediately precede "key". The current key's value and data record number will be returned in "key" and "recno". NOTES The user must ensure that the buffer used to return the key is large enough to hold the entire key. The maximum length of the key can be determined via a call to scdcinfo. When searching it is not necessary to pad the key string to size with spaces (" "), the function will automatically do this for you. Searching for partial keys can be accomplished by using the SC_FIRST method. For example, you are using a fifteen character key and you want to find the first entry where the first five characters are "ABCDE". All you need do is copy that five character ASCIIZ string into your key buffer and then call scdckfind. The function will space pad to length and then find the first matching entry. 76 CHAPTER 8, THE SOFTC DATABASE LIBRARY All keys are returned as strings. SEE ALSO scdcinfo. EXAMPLE #include <stdio.h> #include <string.h> #include <softc.h> #include <sc_base.h> void main() { int ntx; char key[65]; long recno; scdinit(20,0); if (scdcopenx(&ntx, "TOCNAME.NTX", SC_BUFFER) == SC_SUCCESS) { strcpy(key,"ABCDE.XYZ"); recno = 7L; if (scdckfind(ntx,key,&recno,SC_FIRST) != SC_SUCCESS) printf("%s\n",scemsg()); else printf("%s %ld\n",key,recno); scdcclose(ntx); } scdterm(); } 77 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdckmake USAGE signed int scdckmake( signed int datahandle, signed int indexhandle, void **key ); PROTOTYPE IN sc_base.h DESCRIPTION scdckmake will build an index key using the key expression of the index file specified by "indexhandle" and the data found in the record buffer of the data file "datahandle". Memory space for the "key" will be allocated and the address of this block will be returned. The key expression can consist of either the data field name or one of five Clipper functions or a combination thereof. Data field types of date, numeric, or character are allowed. Clipper functions dtoc, left, right, str, and substr are currently supported by scdckmake. Following is a brief description of the five expression functions: dtoc will convert data from a date field to an ASCIIZ string of the format "mm/dd/yy". Syntax is: dtoc(field_name) left will return the left portion of a character field as an ASCIIZ string. The number of characters returned is specified after the field name. Syntax is: left(field_name,number) 78 CHAPTER 8, THE SOFTC DATABASE LIBRARY right will return the right portion of a character field as an ASCIIZ string. The number of characters returned is specified after the field name. This is a count from the right side of the field. Syntax is: right(field_name,number) str will convert a numeric field to an ASCIIZ string. The total length of the string and the number of decimal places are optional parameters. The default string length is 10 and the number of decimal places is 0. Syntax is: str(field_name,length,decimal_places) substr will return the middle portion of a character field. The starting offset into the field is a required parameter. The number of characters to be used is an optional parameter whose default value is the remainder of the field. Syntax is: substr(field_name,start,count) An example of a more complex key expression: right(dtoc(date),2)+left(dtoc(date,2) This expression would cause scdckmake to create an index key string consisting of the year and month ("yymm"). For example if date equals "2/13/89" the resultant key would be "8902". NOTES For key expressions consisting of only one data field scdckmake is probably an overkill. You can easily generate these keys yourself. scdckmake is a fairly large module and if not needed probably should not be used. This function is best used when the key expression is more complex. 79 CHAPTER 8, THE SOFTC DATABASE LIBRARY Memory is allocated for the generated key and it is the responsibility of the caller to free this memory when finished. SEE ALSO scdccreate. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int ntx, dbf; char *key; long recno; scdinit(20,0); if (scddopenx(&dbf, "TOC.DBF", 0) == SC_SUCCESS) { if (scdcopenx(&ntx, "TOCNAME.NTX", SC_BUFFER) == SC_SUCCESS) { scddfput(dbf,0,"ABCDEF.XYZ"); scddrput(dbf,&recno,SC_ADD); scdckmake(dbf,ntx,(void **) &key); printf("%s\n",key); scdckadd(ntx,key,recno); free(key); /* free memory allocated for key */ scdcclose(ntx); } scddclose(dbf); } scdterm(); } 80 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdcknext USAGE signed int scdcknext( signed int handle, void *key, signed long *recno ); PROTOTYPE IN sc_base.h DESCRIPTION scdcknext will increment the key pointer and return the key value "key" and data record number "recno" associated with the new current key. If scdcknext is called immediately after opening the index file the first logical key will be returned. NOTES The user must ensure that the buffer used to return the key is large enough to hold the entire key. The maximum length of the key can be determined via a call to scdcinfo. All keys are returned as strings. SEE ALSO scdcinfo. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int ntx; char key[11]; 81 CHAPTER 8, THE SOFTC DATABASE LIBRARY long recno; scdinit(20,0); if (scdcopenx(&ntx, "TOCLNGTH.NTX", SC_BUFFER) == SC_SUCCESS) { scdcknext(ntx,key,&recno); /* return first key */ printf("%s %ld\n",key,recno); scdcclose(ntx); } scdterm(); } 82 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdckprev USAGE signed int scdckprev( signed int handle, void *key, signed long *recno ); PROTOTYPE IN sc_base.h DESCRIPTION scdckprev will decrement the key pointer and return the key value "key" and data record number "recno" associated with the new current key. If scdckprev is called immediately after opening the index file the last logical key will be returned. NOTES The user must ensure that the buffer used to return the key is large enough to hold the entire key. The maximum length of the key can be determined via a call to scdcinfo. All keys are returned as strings. SEE ALSO scdcinfo. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int ntx; char character[65]; 83 CHAPTER 8, THE SOFTC DATABASE LIBRARY long recno; scdinit(20,0); if (scdcopenx(&ntx,"TOCNAME.NTX",SC_BUFFER) == SC_SUCCESS) { scdckprev(ntx,character,&recno); /* get last key */ printf("%s %ld\n",character,recno); scdcclose(ntx); } scdterm(); } 84 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdcktop USAGE signed int scdcktop( signed int handle, void *key, signed long *recno ); PROTOTYPE IN sc_base.h DESCRIPTION scdcktop will set the current key pointer to the first logical key in the index and return the key value "key" and data record number "recno" associated with the new current key. NOTES The user must ensure that the buffer used to return the key is large enough to hold the entire key. The maximum length of the key can be determined via a call to scdcinfo. All keys are returned as strings. SEE ALSO scdcinfo. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int ntx; char date[17]; long recno; scdinit(20,0); if (scdcopenx(&ntx,"TOCDATE.NTX",SC_BUFFER) == SC_SUCCESS) 85 CHAPTER 8, THE SOFTC DATABASE LIBRARY { date[16] = 0; scdcktop(ntx,date,&recno); printf("%s %ld\n",date,recno); scdcclose(ntx); } scdterm(); } 86 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdcopenx USAGE signed int scdcopenx( signed int *handle, signed char *filename, signed int command ); PROTOTYPE IN sc_base.h DESCRIPTION scdcopenx opens a Clipper index file (.NTX). Memory will be allocated for a file packet, I/O buffers, and other miscellaneous structures for use internally by the SoftC Database Library file manager. The index file will be tested as much as possible to insure that it is a legitimate Clipper index file. A block of memory large enough to hold at least 3 pages (3072 bytes) will be allocated during the open. Three pages is the minimum number of buffers required to add or delete index keys. The file will be opened under control of the "command" parameter. Using SC_RDWR opens the file for both read and write access. SC_RDONLY overrides SC_RDWR and causes the file to be opened for read access only. Any attempt to write to a read only file will result in an error (SC_READOLY). Using SC_EXCLUDE opens the file for exclusive use of this station (single user). SC_SHARED overrides SC_EXCLUDE and opens the file in multi- user mode. This mode is used when a LAN file is to be shared with other stations. Using SC_BUFFER opens the file with I/O caching enabled. Memory for up to 10 pages will be allocated during the open. Caching of page I/O greatly increases the speed of file access. Typically this mode is used with single user 87 CHAPTER 8, THE SOFTC DATABASE LIBRARY files. SC_FLUSH overrides SC_BUFFER and causes the file to be opened with no caching. This mode is generally used with file sharing, although it is not required. The index expression will be translated to upper case after being read from the index file. EXAMPLE #include <softc.h> #include <sc_base.h> void main() { int ntx; scdinit(20,0); if (scdcopenx(&ntx, "UNKNOWN.NTX", SC_BUFFER) == SC_SUCCESS) { scdcclose(ntx); } scdterm(); } 88 CHAPTER 8, THE SOFTC DATABASE LIBRARY scddbfrsz USAGE signed int scddbfrsz( signed int handle, signed int *length, signed int command ); PROTOTYPE IN sc_base.h DESCRIPTION scddbfrsz either sets (SC_SETSZ) or gets (SC_GETSZ) the I/O cache "length" (in records) based upon the value of "command". If the cache length is being set, the current cache will be flushed to disk before the buffer is reallocated. An I/O cache will be used only if the data file was opened with SC_BUFFER in the command field. SEE ALSO scddopenx EXAMPLE /* Get Size */ #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int dbf, length; scdinit(20,0); if (scddopenx(&dbf,"TOC.DBF",SC_BUFFER) == SC_SUCCESS) { scddbfrsz(dbf,&length,SC_GETSZ); printf("%d\n",length); scddclose(dbf); 89 CHAPTER 8, THE SOFTC DATABASE LIBRARY } scdterm(); } /* Get Size */ #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int dbf, length = 100; scdinit(20,0); if (scddopenx(&dbf, "TOC.DBF", SC_BUFFER) == SC_SUCCESS) { scddbfrsz(dbf,&length,SC_SETSZ); printf("%d\n",length); scddclose(dbf); } scdterm(); } 90 CHAPTER 8, THE SOFTC DATABASE LIBRARY scddbof USAGE signed int scddbof( signed int handle ); PROTOTYPE IN sc_base.h DESCRIPTION scddbof returns an indicator as to whether or not the record pointer is positioned at the beginning of the file. RETURN VALUES SC_TRUE at beginning of file SC_FALSE somewhere else SEE ALSO scddeof, scddrnum. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int dbf; scdinit(20,0); if (scddopenx(&dbf,"TOC.DBF",0) == SC_SUCCESS) { if (scddbof(dbf) < SC_SUCCESS) puts(scemsg()); else if (sc_code == SC_TRUE) puts("At beginning of file"); else puts("Somewhere else."); scddclose(dbf); } scdterm(); } 91 CHAPTER 8, THE SOFTC DATABASE LIBRARY scddclose USAGE signed int scddclose( signed int handle ); PROTOTYPE IN sc_base.h DESCRIPTION scddclose closes a data file and frees all allocated memory associated with data file "handle". If the data file was modified, today's date will be written into the file header. NOTES If any locks are applied to the file, they will be removed before closing. SEE ALSO scddopenx EXAMPLE #include <softc.h> #include <sc_base.h> void main() { int dbf; scdinit(20,0); if (scddopenx(&dbf,"TOC.DBF",0) == SC_SUCCESS) scddclose(dbf); scdterm(); } 92 CHAPTER 8, THE SOFTC DATABASE LIBRARY scddcreate USAGE signed int scddcreate( signed char *filename, signed int numfields, SC_FIELD *fields, signed int style ); PROTOTYPE IN sc_base.h DESCRIPTION scddcreate creates a dBASEIII or dBASEIV compatible data file. A pointer to an array of SC_FIELD must be passed. typedef struct { signed char name[11]; /* field name */ signed char type; /* field type */ unsigned char len; /* field length */ unsigned char decpl; /* decimal places */ } SC_FIELD; The field description array must be initialized and each element set to appropriate values. The array determines the organization of the data record. The data file does not remain open upon exit of this function. This function will create a new data file even if one had already existed. Field names and types are converted to all upper case when the file is created. Valid field types are: 'C' character (not NULL terminated in record) 'D' date ("yyyymmdd" format) 'F' floating point (valid only for dBASEIV files) 'L' logical (TRUE, FALSE) 93 CHAPTER 8, THE SOFTC DATABASE LIBRARY 'M' memo (memo file record number) 'N' numeric. Both 'F' and 'N' fields are handled as doubles by the library. The library does not support BCD numbers. The type of data file created depends upon the value of the "style" parameter: SC_DB3 - dBASEIII compatible, or SC_DB4 - dBASEIV compatible. RESTRICTIONS The maximum record length is 4000 bytes. The maximum number of dBASE III fields is 128, but the maximum number of dBASEIV fields is 255. The maximum length of character fields is 254, and they cannot be longer than 100 if used as a key. The maximum length of dBASE III numeric fields is 19, but the maximum length of dBASE IV numeric & float fields is 20. The length of a date field is forced to 8. The length of a logical field is forced to 1. The length of a memo field is forced to 10. The number of decimal places will be forced to zero for all types except: 1) dBASE III NUMERIC - it must be less than ('len' - 2) and also less than 16, and 2) dBASE IV NUMERIC and FLOAT - it must be less than ('len' - 2). The number of decimal places cannot be less than zero. SEE ALSO scddcreate EXAMPLE #include <softc.h> #include <sc_base.h> 94 CHAPTER 8, THE SOFTC DATABASE LIBRARY void main() { SC_FIELD fields[] = { "name",'c',64,0, /* file name */ "length",'n',10,0, /* file size */ "date",'d',8,0, /* date */ "time",'c',8,0, /* time */ "attribute",'c',3,0 /* file attributes */ }; scdinit(20,0); scddcreate("TOC.DBF",5,fields,SC_DB3); scdterm(); } 95 CHAPTER 8, THE SOFTC DATABASE LIBRARY scddeof USAGE signed int scddeof( signed int handle ); PROTOTYPE IN sc_base.h DESCRIPTION scddeof returns an indicator as to whether or not the record pointer is positioned at the end of the file. RETURN VALUES SC_TRUE at end of file SC_FALSE somewhere else SEE ALSO scddbof, scddrnum. EXAMPLE #include <sc_base.h> void main() { int dbf; scdinit(20,0); if (scddopenx(&dbf, "TOC.DBF", 0) == SC_SUCCESS) { if (scddeof(dbf) < SC_SUCCESS) puts(scemsg()); else if (sc_code == SC_TRUE) puts("At end of file"); else puts("Somewhere else"); scddclose(dbf); } scdterm(); } 96 CHAPTER 8, THE SOFTC DATABASE LIBRARY scddfget USAGE signed int scddfget( signed int handle, signed int fieldno, void *data ); PROTOTYPE IN sc_base.h DESCRIPTION scddfget gets data from the desired field "fieldno" of the record I/O buffer. "data" will be converted from dBASE to a more natural data type for 'c': dBASE field type returned data type 'C' signed char * 'D' signed char [9] 'F' double (dBASEIV) 'L' signed char 'M' unsigned long 'N' double Date and character fields are returned as ASCIIZ strings. The date strings will be formatted under control of the global variable sc_date_style. This variable will default to SC_GREGOR. Data returned by this function for memo fields is the memo file record number NOT the actual memo text. A call must be made to scdtrget to retrieve the memo text. scddfinfo can be used to determine the length of the longest data field in the file. NOTES Fields are numbered from zero (0). 97 CHAPTER 8, THE SOFTC DATABASE LIBRARY SEE ALSO scdtrget, scddfgets, scddfput, scddfinfo, scddrget. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int dbf; char name[65], time[9], date[9]; double length, attribute; scdinit(20,0); if (scddopenx(&dbf,"TOC.DBF",0) == SC_SUCCESS) { scddrget(dbf,1L); scddfget(dbf,0,name); scddfget(dbf,1,&length); scddfget(dbf,2,date); scddfget(dbf,3,time); scddfget(dbf,4,&attribute); printf("%s %lf %s %s %lf\n", name,length,date,time,attribute); scddclose(dbf); } scdterm(); } 98 CHAPTER 8, THE SOFTC DATABASE LIBRARY scddfgets USAGE signed int scddfgets( signed int handle, signed int fieldno, char *data ); PROTOTYPE IN sc_base.h DESCRIPTION scddfgets gets data from the desired field "fieldno" of the record I/O buffer. "data" will be returned as an ASCIIZ string. scddfinfo can be used to determine the length of the longest data field in the file. NOTES Date fields are returned in the form "yyyymmdd". There is a difference between the date formats of scddfgets and scddfget. Fields are numbered from zero (0). SEE ALSO scddfget, scddfputs, scddfinfo, scddrget. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int dbf; char name[65], time[9], date[9], length[11], attribute[4]; scdinit(20,0); 99 CHAPTER 8, THE SOFTC DATABASE LIBRARY if (scddopenx(&dbf,"TOC.DBF",0) == SC_SUCCESS) { scddrget(dbf,1L); scddfgets(dbf,0,name); scddfgets(dbf,1,length); scddfgets(dbf,2,date); scddfgets(dbf,3,time); scddfgets(dbf,4,attribute); printf("%s %s %s %s %s\n", name,length,date,time,attribute); scddclose(dbf); } scdterm(); } 100 CHAPTER 8, THE SOFTC DATABASE LIBRARY scddfinfo USAGE signed int scddfinfo( signed int handle, signed int *longfldlen, SC_FIELD *fields ); PROTOTYPE IN sc_base.h DESCRIPTION scddfinfo copies the data field descriptions to "fields" using the structure SC_FIELD. The length of the longest data field is also returned "longfldlen". typedef struct { signed char name[11]; /* field name */ signed char type; /* field type */ unsigned char len; /* field length */ unsigned char decpl; /* decimal places */ } SC_FIELD; NOTES The user must ensure that the array defined for "fields" is large enough to hold all of the field descriptions because scddfinfo blindly copies the descriptions to "fields". Severe program errors can be the result if the field array is too small. Use scddrinfo to determine the number of fields in the data record. SEE ALSO scddrinfo EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> 101 CHAPTER 8, THE SOFTC DATABASE LIBRARY void main() { int dbf, longfld, numflds, a, reclen; SC_FIELD fields[128]; /* dBASEIII max size */ unsigned char *bfr; SC_DBFRINFO rinfo; scdinit(20,0); if (scddopenx(&dbf,"TOC.DBF",0) == SC_SUCCESS) { scddrinfo(dbf,&rinfo); scddfinfo(dbf,&longfld,fields); printf("longest field length = %d\n",longfld); for (a=0; a<rinfo.numflds; a++) printf("%s %c %d %d\n", fields[a].name, fields[a].type, fields[a].len, fields[a].decpl); scddclose(dbf); } scdterm(); } 102 CHAPTER 8, THE SOFTC DATABASE LIBRARY scddflush USAGE signed int scddflush( signed int handle ); PROTOTYPE IN sc_base.h DESCRIPTION scddflush will write the contents of the I/O cache to disk. An I/O cache will be used only if the data file was opened with SC_BUFFER in the command switch. SEE ALSO scddopenx EXAMPLE #include <softc.h> #include <sc_base.h> void main() { int dbf; long record; scdinit(20,0); if (scddopenx(&dbf,"TOC.DBF",SC_BUFFER) == SC_SUCCESS) { . . . scddrput(dbf,&record,SC_ADD); scddflush(dbf); . . . scddclose(dbf); } scdterm(); } 103 CHAPTER 8, THE SOFTC DATABASE LIBRARY scddfnam2no USAGE signed int scddfnam2no( signed int handle, signed int *fieldno, signed char *fieldname ); PROTOTYPE IN sc_base.h DESCRIPTION scddfnam2no searches through the field description array for data file "handle" looking for "fieldname". It will return the corresponding field number. NOTES Data files created by the SoftC Database Library will have field names and types changed to all upper case. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int dbf, fldno scdinit(20,0); if (scddopenx(&dbf,"TOC.DBF",0) == SC_SUCCESS) { scddfnam2no(dbf,&fldno,"ATTRIBUTE"); printf("%d",fldno); scddclose(dbf); } scdterm(); } 104 CHAPTER 8, THE SOFTC DATABASE LIBRARY scddfput USAGE signed int scddfput( signed int handle, signed int fieldno, void *data ); PROTOTYPE IN sc_base.h DESCRIPTION scddfput will convert "data" from 'c' format to dBASE format and place it in the proper field "fieldno" of the record I/O buffer. dBASE field type returned data type 'C' signed char * 'D' signed char [9] 'F' double (dBASE IV) 'L' signed char 'M' unsigned long 'N' double NOTES Fields are numbered from zero (0). scddfput uses the global variable sc_date_style to control date string formatting. The initial value of this variable is SC_GREGOR. SEE ALSO scddfget, scddfputs. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() 105 CHAPTER 8, THE SOFTC DATABASE LIBRARY { int dbf; double length = 1200.0L, attribute = 1.0L; long recno; scdinit(20,0); if (scddopenx(&dbf,"TOC.DBF",0) == SC_SUCCESS) { scddfput(dbf,0,"ABC.XYZ"); scddfput(dbf,1,&length); scddfput(dbf,2,"07/21/90"); scddfput(dbf,3,"20:01:45"); scddfput(dbf,4,&attribute); scddrput(dbf,&recno,SC_ADD); scddclose(dbf); } scdterm(); } 106 CHAPTER 8, THE SOFTC DATABASE LIBRARY scddfputs USAGE signed int scddfputs( signed int handle, signed int fieldno, char *data ); PROTOTYPE IN sc_base.h DESCRIPTION scddfputs will place "data" in the proper field "fieldno" of the record I/O buffer. It is the user's responsibility to provide a properly sized and formatted ASCIIZ string to scddfputs. NOTES Fields are numbered from zero (0). scddfputs follows the date formatting conventions of scddfgets. Also be aware that the date formatting conventions of scddfget/scddfput are not the same as scddfgets/scddfputs. SEE ALSO scddfgets, scddfput. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int dbf; long recno; scdinit(20,0); if (scddopenx(&dbf,"TOC.DBF",0) == SC_SUCCESS) { scddfputs(dbf,0,"ABC.XYZ"); 107 CHAPTER 8, THE SOFTC DATABASE LIBRARY scddfputs(dbf,1," 1234.0"); scddfputs(dbf,2,"19900721"); scddfputs(dbf,3,"20:01:45"); scddfputs(dbf,4," 1"); scddrput(dbf,&recno,SC_ADD); scddclose(dbf); } scdterm(); } 108 CHAPTER 8, THE SOFTC DATABASE LIBRARY scddinfo USAGE signed int scddinfo( signed int handle, SC_DBFINFO *info ); PROTOTYPE IN sc_base.h DESCRIPTION scddinfo returns an information structure for the file associated with "handle". typedef struct { signed char fname[80]; /* file name */ signed char style; /* file type */ /* (dBASE 3 or 4) */ signed char memo; /* memo file used */ signed char mdx; /* MDX file used */ signed char trans; /* transaction */ /* in progress */ signed char encrypt; /* data encrypted */ signed char lockt; /* lock status */ unsigned long ladrs; /* address of lock */ unsigned long lsize; /* locked length */ SC_FLAGS flags; /* misc. flags */ } SC_DBFINFO; SEE ALSO scddopenx EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int dbf; SC_DBFINFO info; 109 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdinit(20,0); if (scddopenx(&dbf,"TOC.DBF",0) == SC_SUCCESS) { scddinfo(dbf,&info); puts(info.fname); if (info.style == SC_DB3) puts("dBASE III data file"); else { puts("dBASE IV data file"); if (info.memo) puts("memo file attached"); else puts("no memo file attached"); if (info.mdx) puts(".MDX file used") else puts("No .MDX file used"); if (info.trans) puts("Transaction in progress"); if (info.encrypt) puts("File encrypted"); } scddclose(dbf); } scdterm(); } 110 CHAPTER 8, THE SOFTC DATABASE LIBRARY scddlock USAGE signed int scddlock( signed int handle ); PROTOTYPE IN sc_base.h DESCRIPTION scddlock will lock the entire data file for exclusive use by this station. This function should be used immediately prior to adding records to the data file, or writing to the index and/or memo files. A call to scddunlock should immediately follow the write so that others may again access the data, memo, and index files. File sharing is enabled by opening the data file with SC_SHARED in the command switch. Any associated index and memo files should also be opened with SC_SHARED in the command switch. SEE ALSO scddopenx, scddrlock,scddunlock. EXAMPLE #include <softc.h> #include <sc_base.h> void main() { int dbf; long record; double length = 1305, attribute = 1; scdinit(20,0); if (scddopenx(&dbf,"TOC.DBF",SC_SHARED) == SC_SUCCESS) { scddfput(dbf,0,"MNO.XYZ"); scddfput(dbf,1,&length); scddfput(dbf,2,"07/22/90"); scddfput(dbf,3,"20:10:45"); 111 CHAPTER 8, THE SOFTC DATABASE LIBRARY scddfput(dbf,4,&attribute); scddlock(dbf); scddrput(dbf,&record,SC_ADD); scddunlock(dbf); scddclose(dbf); } scdterm(); } 112 CHAPTER 8, THE SOFTC DATABASE LIBRARY scddlud USAGE signed int scddlud( signed int handle, signed char *datestr, signed int format ); PROTOTYPE IN sc_base.h DESCRIPTION scddlud returns the ASCIIZ date string ("datestr") of when the last update to the data file was made. The date string will be under control of the "format" command. This date will be updated after the data file has been closed. Date string styles: SC_GREGOR mm/dd/yy SC_GREGORL mm/dd/yyyy SC_JULIAN yyyy/ddd SC_YMD yyyymmdd SC_DMY ddmmyy EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int dbf; char date[9]; scdinit(20,0); if (scddopenx(&dbf,"TOC.DBF",0) == SC_SUCCESS) { scddlud(dbf,&date,SC_YMD); puts(date); scddclose(dbf); } scdterm(); } 113 CHAPTER 8, THE SOFTC DATABASE LIBRARY scddopenx USAGE signed int scddopenx( signed int *handle, signed char *filename, signed int command ); PROTOTYPE IN sc_base.h DESCRIPTION scddopenx opens a data file. Memory will be allocated for a file packet and I/O buffers for use internally by the SoftC Database Library file manager. The data file will be tested as much as possible to insure that it is a legitimate dBASE data file. The file will be opened under control of the "command" parameter. Using SC_RDWR opens the file for both read and write access. SC_RDONLY overrides SC_RDWR and causes the file to be opened for read access only. Any attempt to write to a read only file will result in an error (SC_READOLY). Using SC_EXCLUDE opens the file for exclusive use of this station (single user). SC_SHARED overrides SC_EXCLUDE and opens the file in multi- user mode. This mode is used when a LAN file is to be shared with other stations. Using SC_BUFFER opens the file with I/O caching enabled. A buffer of at least 512 bytes but no more than 16384 will be allocated during the open. Caching of record I/O greatly increases the speed of sequential file access. Typically this mode is used with single user files. SC_FLUSH overrides SC_BUFFER and causes the file to be opened with no caching. This mode is generally used with file sharing, although it is not required. 114 CHAPTER 8, THE SOFTC DATABASE LIBRARY NOTES All field names and types, and the file name will be converted to upper case after the file has been opened. SEE ALSO scddopenx EXAMPLE #include <softc.h> #include <sc_base.h> void main() { int dbf; scdinit(20,0); scddopenx(&dbf, "TOC.DBF", SC_SHARED|SC_FLUSH|SC_RDWR); scdterm(); } 115 CHAPTER 8, THE SOFTC DATABASE LIBRARY scddpack USAGE signed int scddpack( signed int *handle ); PROTOTYPE IN sc_base.h DESCRIPTION scddpack will remove all data file records which have been flagged as deleted (SC_NOTUSED). The data file will be compressed so that all active records will be contiguous after the pack. Files opened with the read only flag (SC_RDONLY) cannot be packed. SEE ALSO scddopenx,scdnindex,scdtpack EXAMPLE #include <softc.h> #include <sc_base.h> void main() { int dbf; scdinit(20,0); if (scddopenx(&dbf,"TOC.DBF",0) == SC_SUCCESS) { scddpack(dbf); scddclose(dbf); } scdterm(); } 116 CHAPTER 8, THE SOFTC DATABASE LIBRARY scddrclear USAGE signed int scddrclear( signed int handle ); PROTOTYPE IN sc_base.h DESCRIPTION scddrclear clears the record buffer. The buffer will be written with spaces (" ") NOT zeros (0). EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int dbf; char name[65]; scdinit(20,0); if (scddopenx(&dbf,"TOC.DBF",0) == SC_SUCCESS) { scddfput(dbf,0,"Now is the time for all..."); scddrclear(dbf); scddfget(dbf,0,name); puts(name); } scdterm(); } 117 CHAPTER 8, THE SOFTC DATABASE LIBRARY scddrdel USAGE signed int scddrdel( signed int handle, signed long recno ); PROTOTYPE IN sc_base.h DESCRIPTION scddrdel will flag a record specified by "recno" as 'deleted'. To maintain compatibility with dBASE the data record cannot be reused, but it can be recovered by scddrundel. SEE ALSO scddrundel. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int dbf; scdinit(20,0); if (scddopenx(&dbf,"TOC.DBF",0) == SC_SUCCESS) { scddrdel(dbf,1L); scddrget(dbf,1L); puts(scemsg()); /* WARNING - record read is marked deleted */ scddclose(dbf); } scdterm(); } 118 CHAPTER 8, THE SOFTC DATABASE LIBRARY scddrget USAGE signed int scddrget( signed int handle, signed long recno ); PROTOTYPE IN sc_base.h DESCRIPTION scddrget will read the data record specified by "recno" from the data file associated with "handle" into the internal record buffer. SEE ALSO scddfget, scddfput, scddrput. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int dbf; char name[65], time[9], date[9]; double length, attribute; scdinit(20,0); if (scddopenx(&dbf,"TOC.DBF",0) == SC_SUCCESS) { scddrget(dbf,1L); scddfget(dbf,0,name); scddfget(dbf,1,&length); scddfget(dbf,2,date); scddfget(dbf,3,time); scddfget(dbf,4,&attribute); printf("%s %lf %s %s %lf\n", name,length,date,time,attribute); scddclose(dbf); } scdterm(); } 119 CHAPTER 8, THE SOFTC DATABASE LIBRARY scddrinfo USAGE signed int scddrinfo( signed int handle, SC_DBFRINFO *rinfo ); PROTOTYPE IN sc_base.h DESCRIPTION scddrinfo gets the data record length, the number of data fields per record, and the address of the record buffer. typedef struct { signed int reclen; /* record length */ signed int numflds; /* number of */ /* fields */ unsigned char *bfr; /* buffer address */ } SC_DBFRINFO; EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int dbf; SC_DBFRINFO rinfo; scdinit(20,0); if (scddopenx(&dbf,"TOC.DBF",0) == SC_SUCCESS) { scddrinfo(dbf,&rinfo); printf("Record length = %d\n",rinfo.reclen); printf("Number of fields = %d\n",rinfo.numflds); printf("Record buffer = %p\n",rinfo.bfr); scddclose(dbf); } scdterm(); } 120 CHAPTER 8, THE SOFTC DATABASE LIBRARY scddrlock USAGE signed int scddrlock( signed int handle, signed long record ); PROTOTYPE IN sc_base.h DESCRIPTION scddrlock will lock the specified "record" in the data file for exclusive use by this station. This function should be used immediately prior to updating a data file record. A call to scddunlock should immediately follow the write so that others may again access the data record. File sharing is enabled by opening the data file with SC_SHARED in the command switch. SEE ALSO scddopenx, scddlock,scddunlock. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int dbf; long record = 1L; double length = 1936, attribute = 1; scdinit(20,0); if (scddopenx(&dbf,"TOC.DBF",SC_SHARED) == SC_SUCCESS) { scddfput(dbf,0,"MNO.XYZ"); scddfput(dbf,1,&length); scddfput(dbf,2,"07/22/90"); scddfput(dbf,3,"20:10:45"); scddfput(dbf,4,&attribute); 121 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdnkmake(dbf,ndx,&key); scdrlock(dbf,record); scddrput(dbf,&record,SC_UPDATE); scddunlock(dbf); free(key); scddclose(dbf); } scdterm(); } 122 CHAPTER 8, THE SOFTC DATABASE LIBRARY scddrnum USAGE signed int scddrnum( signed int handle, signed long *position ); PROTOTYPE IN sc_base.h DESCRIPTION scddrnum returns the current position (record number) in the data file. SEE ALSO scddbof, scddeof. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int dbf; long position; scdinit(20,0); if (scddopenx(&dbf,"TOC.DBF",0) == SC_SUCCESS) { scddrget(dbf,4L); scddrnum(dbf,&position); printf("%ld\n",position); scddclose(dbf); } scdterm(); } 123 CHAPTER 8, THE SOFTC DATABASE LIBRARY scddrput USAGE signed int scddrput( signed int handle, signed long *recno, signed int howto ); PROTOTYPE IN sc_base.h DESCRIPTION scddrput will write the data record specified by "recno" to the data file associated with "handle" from the internal record buffer. "howto" determines how the data record is to be written: "howto" = action SC_ADD append to end of file SC_UPDATE update current record If a record update is occurring the data record number passed in "recno" will be written in the disk file. Use scddrget/scddrcopy to load a data record or scddfput or scddfputs to fill the data record field by field. SEE ALSO scddfput, scddfputs, scddrget. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int dbf; 124 CHAPTER 8, THE SOFTC DATABASE LIBRARY double length = 1200.0L, attribute = 1.0L; long recno; scdinit(20,0); if (scddopenx(&dbf,"TOC.DBF",0) == SC_SUCCESS) { scddfput(dbf,0,"ABC.XYZ"); scddfput(dbf,1,&length); scddfput(dbf,2,"07/21/90"); scddfput(dbf,3,"20:01:45"); scddfput(dbf,4,&attribute); scddrput(dbf,&recno,SC_ADD); scddclose(dbf); } scdterm(); } 125 CHAPTER 8, THE SOFTC DATABASE LIBRARY scddrstat USAGE signed int scddrstat( signed int handle ); PROTOTYPE IN sc_base.h DESCRIPTION scddrstat returns an indicator as to whether or not the current record loaded is active or inactive (flagged as deleted). RETURN VALUES SC_DELREC record inactive SC_SUCCESS active record SEE ALSO scddrget EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int dbf; scdinit(20,0); if (scddopenx(&dbf,"TOC.DBF",0) == SC_SUCCESS) { scddrget(dbf,1L); if (scddrstat(dbf) == SC_DELREC) puts("Record is inactive."); else puts("Record is active."); scddclose(dbf); } scdterm(); } 126 CHAPTER 8, THE SOFTC DATABASE LIBRARY scddrundel USAGE signed int scddrundel( signed int handle, signed long recno ); PROTOTYPE IN sc_base.h DESCRIPTION scddrundel will remove the 'deleted' flag from the data record specified by "recno". SEE ALSO scddrdel. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int dbf; scdinit(20,0); if (scddopenx(&dbf,"TOC.DBF",0) == SC_SUCCESS) { scddrundel(dbf,1L); scddrget(dbf,1L); puts(scemsg()); scddclose(dbf); } scdterm(); } 127 CHAPTER 8, THE SOFTC DATABASE LIBRARY scddsize USAGE signed int scddsize( signed int handle, signed long *recsused ); PROTOTYPE IN sc_base.h DESCRIPTION scddsize gets the number of records "recsused" in the data file. This number will include all records inactive as well as active records. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int dbf; long recsused; scdinit(20,0); if (scddopenx(&dbf,"TOC.DBF",0) == SC_SUCCESS) { scddsize(dbf,&recsused); printf("%ld",recsused); scddclose(dbf); } scdterm(); } 128 CHAPTER 8, THE SOFTC DATABASE LIBRARY scddunlock USAGE signed int scddunlock( signed int handle ); PROTOTYPE IN sc_base.h DESCRIPTION scddunlock will unlock the data file/record for shared use by other stations. This function should be used immediately after writing to all required data, index and memo files. File sharing is enabled by opening the data file with SC_SHARED in the command switch. Any associated index and memo files should also be opened with SC_SHARED in the command switch. SEE ALSO scddopenx, scddlock,scddrlock. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int dbf, ndx; char *key; long record; double length = 2367, attribute = 1; scdinit(20,0); if (scddopenx(&dbf,"TOC.DBF",SC_SHARED) == SC_SUCCESS) { if (scdnopenx(&ndx,"TOCNAME.NDX",SC_SHARED) == SC_SUCCESS) { scddfput(dbf,0,"ABC.XYZ"); scddfput(dbf,1,&length); scddfput(dbf,2,"07/21/90"); 129 CHAPTER 8, THE SOFTC DATABASE LIBRARY scddfput(dbf,3,"20:01:45"); scddfput(dbf,4,&attribute); scdnkmake(dbf,ndx,&key); scddlock(dbf); scddrput(dbf,&record,SC_ADD); scdnkadd(ndx,key,record); scddunlock(dbf); free(key); scdnclose(ndx); } scddclose(dbf); } scdterm(); } 130 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdibfrsz USAGE signed int scdibfrsz( signed int handle, signed int *numpgs, signed int command ); PROTOTYPE IN sc_base.h DESCRIPTION scdibfrsz will either get (SC_GETSZ) or set (SC_SETSZ) the maximum number of index pages the library file manager can keep in memory and returns it via "numpgs". This is under control of "command". EXAMPLE /* Get Size */ #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int idx, numpgs; scdinit(20,0); if (scdiopenx(&idx, "TOCNAME.IDX", SC_BUFFER) == SC_SUCCESS) { scdibfrsz(idx,&numpgs,SC_GETSZ) == SC_SUCCESS) printf("Maximum number of pages = %d\n",numpgs); scdiclose(idx); } scdterm(); } /* Set Size */ #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() 131 CHAPTER 8, THE SOFTC DATABASE LIBRARY { char idx, numpgs = 5; scdinit(20,0); if (scdiopenx(&idx, "TOCNAME.IDX", SC_BUFFER) == SC_SUCCESS) { scdibfrsz(idx,&numpgs,SC_SETSZ); printf("New max = %d\n",numpgs); scdiclose(idx); } scdterm(); } 132 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdiclose USAGE signed int scdiclose( signed int handle ); PROTOTYPE IN sc_base.h DESCRIPTION scdiclose closes an index file and frees all allocated memory associated with the index file specified by "handle". EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int idx; scdinit(20,0); if (scdiopenx(&idx, "TOCNAME.IDX", SC_BUFFER) == SC_SUCCESS) scdiclose(idx); scdterm(); } 133 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdicreate USAGE signed int scdicreate( signed char *filename, signed int keytype, signed char *keyexpr, signed int keylen ); PROTOTYPE IN sc_base.h DESCRIPTION scdicreate creates an index file. "keyexpr" will be translated to all upper case when the index file is created. If "keytype" is SC_CKEY, then "keyexpr" must be an ASCIIZ string consisting of one or more field names from the data record. All fields included in the expression must be of type 'c' or be translated into type 'c'. No check is made to verify this. "keyexpr" cannot be longer that 220 characters. "keylen" cannot exceed 100. If "keytype" is SC_DKEY or SC_NKEY, then "keyexpr" should consist of only one data field. "keylen" will automatically be set to 8 (numeric and date keys are stored as modified doubles). If "keytype" is SC_LKEY, then "keyexpr" should consist of only one data field. "keylen" will automatically be set to 1 (logical keys are stored as characters). When unique keys are required, OR SC_UNIQUE with "keytype". NOTES scdicreate will create a new index file even if one had already existed. 134 CHAPTER 8, THE SOFTC DATABASE LIBRARY "keyexpr" is NOT checked for validity during the file creation process. Currently only the scdikmake function uses "keyexpr". SEE ALSO scdikmake. EXAMPLE #include <sc_base.h> void main() { scdinit(20,0); scdicreate("TOCDATE.IDX",SC_CKEY,"dtoc(date) + time",16); scdterm(); } 135 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdiexpr USAGE signed int scdiexpr( signed int handle, signed char *keyexpr ); PROTOTYPE IN sc_base.h DESCRIPTION scdiexpr gets the index key expression and returns it as an ASCIIZ string into a user supplied buffer "keyexpr". The user must ensure that the buffer is large enough (the key expression length can be determined via a call to scdiinfo) to hold the entire key expression. NOTES A NULL byte will be appended to the end of the expression string returned. If you are dynamically allocating memory be sure to make the buffer large enough. SEE ALSO scdiinfo. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int idx; char buffer[512]; scdinit(20,0); if (scdiopenx(&idx, "TOCNAME.IDX", SC_BUFFER) == SC_SUCCESS) { scdiexpr(idx,buffer); printf("key expression = %s",buffer); 136 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdiclose(idx); } scdterm(); } 137 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdiflush USAGE signed int scdiflush( signed int handle ); PROTOTYPE IN sc_base.h DESCRIPTION scdiflush will write the contents of the page cache to disk. A page cache will be used only if the index file was opened with SC_BUFFER in the command field. SEE ALSO scdiopenx EXAMPLE #include <string.h> #include <softc.h> #include <sc_base.h> void main() { int dbf, idx; char *key, name[65]; long record; scdinit(20,0); if (scddopenx(&dbf, "TOC.DBF", SC_BUFFER) == SC_SUCCESS) { if (scdiopenx(&idx, "TOCNAME.IDX", SC_BUFFER) == SC_SUCCESS) { strcpy(name,"TOC.DBF"); scddfput(dbf,0,name); scddrput(dbf,&record,SC_ADD); scdikmake(dbf,idx,&key); scdikadd(idx,key,record); free(key); scdiflush(idx); scdiclose(idx); } scddclose(dbf); 138 CHAPTER 8, THE SOFTC DATABASE LIBRARY } scdterm(); } 139 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdiindex USAGE signed int scdiindex( signed int datafile, signed char filename, signed char keytype, signed char keyexpr, signed int keylen ); PROTOTYPE IN sc_base.h DESCRIPTION scdiindex will create and build a FoxBASE+ index file. A blank file will be created using "filename", "keytype", "keyexpr", and "keylen". The resultant file will be opened, and the "datafile" will be read sequentially building keys from each data record. The index file will be closed at exit. The "datafile" must be open prior to the function call. EXAMPLE #include <softc.h> #include <sc_base.h> void main() { int dbf; scdinit(20,0); if (scddopenx(&dbf, "TOC.DBF", SC_BUFFER) == SC_SUCCESS) { scdiindex(dbf, "TOCNAME.IDX", SC_CKEY, "NAME", 64); scddclose(dbf); } scdterm(); } 140 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdiinfo USAGE signed int scdiinfo( signed int handle, SC_IDXINFO *info ); PROTOTYPE IN sc_base.h DESCRIPTION scdiinfo gets the filename of the index file associated with "handle", the index key type, the maximum index key length, and the length of the index key expression and returns in "info": typedef struct { signed char fname[80]; /* file name */ signed char keytype; /* key type */ /* (C,D,L,N) */ signed char keylen; /* key length */ signed char exprlen; /* expression */ /* length */ SC_FLAGS flags; /* misc. flags */ } SC_IDXINFO; NOTES If you are using the expression length to dynamically allocate memory to hold the key expression be sure to add one to the length before allocation. SEE ALSO scdiopenx. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() 141 CHAPTER 8, THE SOFTC DATABASE LIBRARY { int idx; SC_IDXINFO info; scdinit(20,0); if (scdiopenx(&idx, "TOCNAME.IDX", SC_BUFFER) == SC_SUCCESS) { scdiinfo(idx,&info); printf("File name = %s\n",info.fname); printf("Index key type = %c\n",info.keytype); printf("Maximum key length = %d\n",info.keylen); printf("Key expression length = %d\n",info.exprlen); scdiclose(idx); } scdterm(); } 142 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdikadd USAGE signed int scdikadd( signed int handle, void *key, signed long recno ); PROTOTYPE IN sc_base.h DESCRIPTION scdikadd will add "key" to the index file specified by "handle". "recno" is the data record number to be associated with "key" (the data record pointed to by "recno" must exist prior to calling scdikadd). NOTES When adding character keys it is necessary to pad the key string to size with spaces (" "), the function will not automatically do this for you. This differs from the dBASE and Clipper corresponding functions. SEE ALSO scdikdate, scdikmake,scdiknum. EXAMPLE #include <softc.h> #include <sc_base.h> void main() { int dbf, idx; long recno; unsigned char key[8] double length = 123.67L scdinit(20,0); if (scddopenx(&dbf, "TOC.DBF",0) == SC_SUCCESS) { if (scdiopenx(&idx, "TOCLNGTH.IDX", SC_BUFFER) == 143 CHAPTER 8, THE SOFTC DATABASE LIBRARY SC_SUCCESS) { scddfput(dbf,1,&length); if (scddrput(dbf,&recno,SC_ADD) == SC_SUCCESS) { scdiknum(key,length); scdikadd(idx,key,recno); } scdiclose(idx); } scddclose(dbf) } scdterm(); } 144 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdikbot USAGE signed int scdikbot( signed int handle, void *key, signed long *recno ); PROTOTYPE IN sc_base.h DESCRIPTION scdikbot will set the current key pointer to the last logical key in the index and return the key value "key" and data record number "recno" associated with the new current key. NOTES The user must ensure that the buffer used to return the key is large enough to hold the entire key. The maximum length of the key can be determined via a call to scdiinfo. Numeric keys are returned as doubles, and character keys are returned as strings. SEE ALSO scdiinfo. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int idx; char name[65]; long recno; scdinit(20,0); 145 CHAPTER 8, THE SOFTC DATABASE LIBRARY if (scdiopenx(&idx, "TOCNAME.IDX", SC_BUFFER) == SC_SUCCESS) { name[64] = 0; scdikbot(idx,name,&recno); printf("%s %ld\n",name,recno); scdiclose(idx); } scdterm(); } 146 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdikcur USAGE signed int scdikcur( signed int handle, void *key, signed long *recno ); PROTOTYPE IN sc_base.h DESCRIPTION scdikcur will return the key value "key" and data record number "recno" associated with the current key in the index file. The current key pointer must be set by a call to either scdikfind, scdiktop, scdikbot, scdiknext, or scdikprev before calling scdikcur. NOTES The user must ensure that the buffer used to return the key is large enough to hold the entire key. The maximum length of the key can be determined via a call to scdiinfo. SEE ALSO scdiinfo, scdikfind, scdiktop, scdikbot, scdiknext, scdikprev. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int idx; char date[17], dat[17]; long recno, recn; 147 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdinit(20,0); if (scdiopenx(&idx, "TOCDATE.IDX", SC_BUFFER) == SC_SUCCESS) { date[16] = 0; dat[16] = 0; scdiktop(idx,date,&recno); scdikcur(idx,dat,&recn); printf("%s %s %ld %ld\n", date,dat,recno,recn); scdiclose(idx); } scdterm(); } 148 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdikdate USAGE signed int scdikdate( unsigned char *key, signed char *string, signed int format ); PROTOTYPE IN sc_base.h DESCRIPTION scdikdate will translate an ASCIIZ date string "string" of style "format" into a valid FoxBASE+ date key "key". Date string styles: SC_GREGOR mm/dd/yy SC_GREGORL mm/dd/yyyy SC_JULIAN yyyy/ddd SC_YMD yyyymmdd SC_DMY ddmmyy SEE ALSO scdikmake, scdiknum. EXAMPLE #include <softc.h> #include <sc_base.h> void main() { int dbf, idx; long recno; unsigned char key[8] scdinit(20,0); if (scddopenx(&dbf, "TOC.DBF",0) == SC_SUCCESS) { if (scdiopenx(&idx, "TOCFDATE.IDX", SC_BUFFER) == SC_SUCCESS) { scddfput(dbf,2,"07/21/90); . . 149 CHAPTER 8, THE SOFTC DATABASE LIBRARY . if (scddrput(dbf,&recno,SC_ADD) == SC_SUCCESS) { scdikdate(key, "07/21/90", SC_GREGOR); scdikadd(idx,key,recno); } scdiclose(idx); } scddclose(dbf) } scdterm(); } 150 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdikdel USAGE signed int scdikdel( signed char handle, void *key, signed long recno ); PROTOTYPE IN sc_base.h DESCRIPTION scdikdel will remove "key" from the index file specified by "handle". "recno" is used along with "key" to ensure that the proper key has been removed from the index file. NOTES When deleting character keys it is necessary to pad the key string to size with spaces (" "), the function will not automatically do this for you. This differs from the corresponding dBASE and Clipper functions. SEE ALSO scdikadd. EXAMPLE #include <string.h> #include <sc_base.h> void main() { int idx; char name[65]; scdinit(20,0); if (scdiopenx(&idx, "TOCNAME.IDX", SC_BUFFER) == SC_SUCCESS) { strcpy(name,"ABC.DEF"); scdikdel(idx,name,3L); scdiclose(idx); 151 CHAPTER 8, THE SOFTC DATABASE LIBRARY } scdterm(); } 152 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdikfind USAGE signed int scdikfind( signed int handle, void *key, signed long *recno, signed int method ); PROTOTYPE IN sc_base.h DESCRIPTION scdikfind supports two key search methods (determined by "method"): SC_EXACT - find an exact match with "key" and "recno", and SC_FIRST - find the first logical occurrence of "key" in the index and return the associated record number "recno" if found. If a match cannot be found, the current key will be the physical key which would immediately precede "key". The current key's value and data record number will be returned in "key" and "recno". NOTES The user must ensure that the buffer used to return the key is large enough to hold the entire key. The maximum length of the key can be determined via a call to scdiinfo. When searching using character keys it is necessary to pad the key string to size with spaces (" "), the function will not automatically do this for you. Because of the above restriction, searching for partial keys is not currently supported. Numeric keys are returned as doubles, and character keys are returned as strings. 153 CHAPTER 8, THE SOFTC DATABASE LIBRARY SEE ALSO scdiinfo. EXAMPLE #include <stdio.h> #include <string.h> #include <softc.h> #include <sc_base.h> void main() { int idx; char name[65]; long recno; scdinit(20,0); if (scdiopenx(&idx, "TOCNAME.IDX", SC_BUFFER) == SC_SUCCESS) { strcpy(name,"ABCDE"); recno = 7L; if (scdikfind(idx, name, &recno, SC_FIRST) != SC_SUCCESS) puts(scemsg()); scdiclose(idx); } scdterm(); } 154 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdikmake USAGE signed int scdikmake( signed int datahandle, signed int indexhandle, void **key ); PROTOTYPE IN sc_base.h DESCRIPTION scdikmake will build an index key using the key expression of the index file specified by "indexhandle" and the data found in the record buffer of the data file "datahandle". Memory space for the "key" will be allocated and the address of this block will be returned. The key expression can consist of either the data field name or one of five FoxBASE+ functions or a combination thereof. Data field types of date, numeric, character or logical are allowed. FoxBASE+ functions: dtoc, left, right, str, and substr are currently supported by scdikmake. Following is a brief description of the five expression functions: dtoc will convert data from a date field to an ASCIIZ string of the format mm/dd/yy. Syntax is: dtoc(field_name) left will return the left portion of a character field as an ASCIIZ string. The number of characters returned is specified after the field name. Syntax is: left(field_name,number) 155 CHAPTER 8, THE SOFTC DATABASE LIBRARY right will return the right portion of a character field as an ASCIIZ string. The number of characters returned is specified after the field name. This is a count from the right side of the field. Syntax is: right(field_name,number) str will convert a numeric field to an ASCIIZ string. The total length of the string and the number of decimal places are optional parameters. The default string length is 10 and the number of decimal places is 0. Syntax is: str(field_name,length,decimal_places) substr will return the middle portion of a character field. The starting offset into the field is a required parameter. The number of characters to be used is an optional parameter whose default value is the remainder of the field. Syntax is: substr(field_name,start,count) An example of a more complex key expression: right(dtoc(date),2)+left(dtoc(date,2) This expression would cause scdikmake to create an index key string consisting of the year and month ("yymm"). For example if date equals "2/13/89" the resultant key would be "8902". NOTES For key expressions consisting of only one data field scdikmake is probably an overkill. You can easily generate these keys yourself. See scdikdate for information on date string to key translation, and scdiknum for numeric field to key translation. scdikmake is a fairly large module and if not needed probably should not be used. This function 156 CHAPTER 8, THE SOFTC DATABASE LIBRARY is best used when the key expression is more complex. Memory is allocated for the generated key and it is the responsibility of the caller to free this memory when finished. SEE ALSO scdicreate, scdikdate, scdiknum. EXAMPLE #include <sc_base.h> void main() { int idx, dbf; char *key, name[65]; long recno; scdinit(20,0); if (scddopenx(&dbf, "TOC.DBF", 0) == SC_SUCCESS) { if (scdiopenx(&idx, "TOCNAME.IDX", SC_BUFFER) == SC_SUCCESS) { scddfput(dbf,0,name); scddrput(dbf,&recno,SC_ADD); scdikmake(dbf,idx,(void **) &key); scdikadd(idx,key,recno); free(key); /* free memory allocated for key */ scdiclose(idx); } scddclose(dbf); } scdterm(); } 157 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdiknext USAGE signed int scdiknext( signed int handle, void *key, signed long *recno ); PROTOTYPE IN sc_base.h DESCRIPTION scdiknext will increment the key pointer and return the key value "key" and data record number "recno" associated with the new current key. If scdiknext is called immediately after opening the index file the first logical key will be returned. NOTES The user must ensure that the buffer used to return the key is large enough to hold the entire key. The maximum length of the key can be determined via a call to scdiinfo. Numeric keys are returned as doubles, and character keys are returned as strings. SEE ALSO scdiinfo. EXAMPLE /* Character Key Example */ #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { 158 CHAPTER 8, THE SOFTC DATABASE LIBRARY int idx; char name[65]; long recno; scdinit(20,0); if (scdiopenx(&idx,"TOCNAME.IDX",SC_BUFFER) == SC_SUCCESS) { scdiknext(idx,name,&recno); /* return first key */ printf("%s %ld\n",name,recno); scdiclose(idx); } scdterm(); } /* Numeric Key Example */ #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int idx; double numeric; long recno; scdinit(20,0); if (scdiopenx(&idx,"TOCLNGTH.IDX",SC_BUFFER) == SC_SUCCESS) { scdiknext(idx,&numeric,&recno); /* return first key */ printf("%lf %ld\n",numeric,recno); scdiclose(idx); } scdterm(); } 159 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdiknum USAGE signed int scdiknum( unsigned char *key, double value ); PROTOTYPE IN sc_base.h DESCRIPTION scdiknum will translate a 'C' double "value" to a FoxBASE+ numeric "key". SEE ALSO scdicreate, scdikdate, scdikmake. EXAMPLE #include <softc.h> #include <sc_base.h> void main() { int dbf, idx; long recno; unsigned char key[8] double length = 123.67L scdinit(20,0); if (scddopenx(&dbf, "TOC.DBF",0) == SC_SUCCESS) { if (scdiopenx(&idx, "TOCLNGTH.IDX", SC_BUFFER) == SC_SUCCESS) { scddfput(dbf,1,&length); if (scddrput(dbf,&recno,SC_ADD) == SC_SUCCESS) { scdiknum(key,length); scdikadd(idx,key,recno); } scdiclose(idx); } scddclose(dbf) } scdterm(); } 160 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdikprev USAGE signed int scdikprev( signed int handle, void *key, signed long *recno ); PROTOTYPE IN sc_base.h DESCRIPTION scdikprev will decrement the key pointer and return the key value "key" and data record number "recno" associated with the new current key. If scdikprev is called immediately after opening the index file the last logical key will be returned. NOTES The user must ensure that the buffer used to return the key is large enough to hold the entire key. The maximum length of the key can be determined via a call to scdiinfo. Numeric keys are returned as doubles, and character keys are returned as strings. SEE ALSO scdiinfo. EXAMPLE /* Character Key Example */ #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { 161 CHAPTER 8, THE SOFTC DATABASE LIBRARY int idx; char name[65]; long recno; scdinit(20,0); if (scdiopenx(&idx,"TOCNAME.IDX",SC_BUFFER) == SC_SUCCESS) { scdikprev(idx, name, &recno); /* get last key */ printf("%s %ld\n",name,recno); scdiclose(idx); } scdterm(); } /* Numeric Key Example */ #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int idx; double length; long recno; scdinit(20,0); if (scdiopenx(&idx,"TOCLNGTH.IDX",SC_BUFFER) == SC_SUCCESS) { scdikprev(idx,&length,&recno); /* get last key */ printf("%lf %ld\n",length,recno); scdiclose(idx); } scdterm(); } 162 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdiktop USAGE signed int scdiktop( signed int handle, void *key, signed long *recno ); PROTOTYPE IN sc_base.h DESCRIPTION scdiktop will set the current key pointer to the first logical key in the index and return the key value "key" and data record number "recno" associated with the new current key. NOTES The user must ensure that the buffer used to return the key is large enough to hold the entire key. The maximum length of the key can be determined via a call to scdiinfo. Numeric keys are returned as doubles, and character keys are returned as strings. SEE ALSO scdiinfo. EXAMPLE /* Character Key Example */ #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int idx; char name[65]; long recno; 163 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdinit(20,0); if (scdiopenx(&idx,"TOCNAME.IDX",SC_BUFFER) == SC_SUCCESS) { name[64] = 0; scdiktop(idx,name,&recno); printf("%s %ld\n",name,recno); scdiclose(idx); } scdterm(); } /* Numeric Key Example */ #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int idx; double length; long recno; scdinit(20,0); if (scdiopenx(&idx,"TOCLNGTH.IDX",SC_BUFFER) == SC_SUCCESS) { scdiktop(idx,&length,&recno); printf("%lf %ld\n",length,recno); scdiclose(idx); } scdterm(); } 164 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdinit USAGE signed int scdinit( signed int files, signed int command ); PROTOTYPE IN sc_base.h DESCRIPTION scdinit should be called once and only once at the beginning of the program. The maximum number of simultaneously open "files" is passed. This function sets up the SoftC Database Library file manager environment for processing. Memory will be allocated for a variety of control structures used internally by the file manager. If the "command" switch SC_USEXHNDLS is passed, more than 20 (the default) open files per program is allowed. A larger handle table will be allocated and the DOS PSP will be changed. NOTES The first five file handles per program are taken up with printer, console, auxiliary port, etc. leaving only 15 file handles available per program in the default state. Neither Microsoft C 5.x/6.0 nor Turbo C 2.0 support more than 20 open files. In other words if you want to open more than 20 files you have to go directly to DOS. SEE ALSO scdterm. 165 CHAPTER 8, THE SOFTC DATABASE LIBRARY EXAMPLE #include <sc_base.h> void main() { scdinit(20,0); scdterm(); } 166 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdiopenx USAGE signed int scdiopenx( signed int *handle, signed char *filename, signed int command ); PROTOTYPE IN sc_base.h DESCRIPTION scdiopenx opens a FoxBASE+ index file. Memory will be allocated for a file packet, I/O buffers, and other miscellaneous structures for use internally by the SoftC Database Library file manager. The index file will be tested as much as possible to insure that it is a legitimate FoxBASE+ index file. A block of memory large enough to hold at least 4 pages (2048 bytes) will be allocated during the open. Four pages is the minimum number of buffers required to add or delete index keys. The file will be opened under control of the "command" parameter. Using SC_RDWR opens the file for both read and write access. SC_RDONLY overrides SC_RDWR and causes the file to be opened for read access only. Any attempt to write to a read only file will result in an error (SC_READOLY). Using SC_BUFFER opens the file with I/O caching enabled. Memory for up to 10 pages will be allocated during the open. Caching of page I/O greatly increases the speed of file access. Typically this mode is used with single user files. SC_FLUSH overrides SC_BUFFER and causes the file to be opened with no caching. This mode is generally used with file sharing, although it is not required. 167 CHAPTER 8, THE SOFTC DATABASE LIBRARY Using SC_EXCLUDE opens the file for exclusive use of this station (single user). SC_SHARED overrides SC_EXCLUDE and opens the file in multi- user mode. This mode is used when a LAN file is to be shared with other stations. NOTES The index expression will be translated to upper case after being read from the index file. EXAMPLE #include <softc.h> #include <sc_base.h> void main() { int idx; scdinit(20,0); if (scdiopenx(&idx, "UNKNOWN.IDX", SC_BUFFER) == SC_SUCCESS) { scdiclose(idx); } scdterm(); } 168 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdnbfrsz USAGE signed int scdnbfrsz( signed int handle, signed int *numpgs, signed int command ); PROTOTYPE IN sc_base.h DESCRIPTION scdnbfrsz will either get (SC_GETSZ) or set (SC_SETSZ) the maximum number of index pages the library file manager can keep in memory and returns it via "numpgs". This is under control of "command". EXAMPLE /* Get Size */ #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int ndx, numpgs; scdinit(20,0); if (scdnopenx(&ndx, "TOCNAME.NDX", SC_BUFFER) == SC_SUCCESS) { scdnbfrsz(ndx,&numpgs,SC_GETSZ) == SC_SUCCESS) printf("Maximum number of pages = %d\n",numpgs); scdnclose(ndx); } scdterm(); } /* Set Size */ #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() 169 CHAPTER 8, THE SOFTC DATABASE LIBRARY { int ndx, numpgs = 5; scdinit(20,0); if (scdnopenx(&ndx, "TOCNAME.NDX", SC_BUFFER) == SC_SUCCESS) { scdnbfrsz(ndx,&numpgs,SC_SETSZ); printf("New max = %d\n",numpgs); scdnclose(ndx); } scdterm(); } 170 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdnclose USAGE signed int scdnclose( signed int handle ); PROTOTYPE IN sc_base.h DESCRIPTION scdnclose closes an index file and frees all allocated memory associated with index file. EXAMPLE #include <softc.h> #include <sc_base.h> void main() { int ndx; scdinit(20,0); if (scdnopenx(&ndx, "TOCNAME.NDX", SC_BUFFER) == SC_SUCCESS) scdnclose(ndx); scdterm(); } 171 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdncreate USAGE signed int scdncreate( signed char *filename, signed char keytype, signed char *keyexpr, signed int keylen ); PROTOTYPE IN sc_base.h DESCRIPTION scdncreate creates an index file. "keyexpr" will be translated to all upper case when the index file is created. If "keytype" is SC_CKEY, then "keyexpr" must be an ASCIIZ string consisting of one or more field names from the data record. All fields included in the expression must be of type 'c' or be translated into type 'c'. No check is made to verify this. "keyexpr" cannot be longer that 220 characters. "keylen" cannot exceed 100. If "keytype" is SC_DKEY or SC_NKEY, then "keyexpr" should consist of only one data field. "keylen" will automatically be set to 8 (numeric and date keys are stored as doubles). For both date and numeric keys "keytype" will be forced to 'n'. When unique keys are required, OR SC_UNIQUE with "keytype". NOTES scdncreate will create a new index file even if one had already existed. "keyexpr" is used by dBASE. "keyexpr" is NOT checked for validity during the file creation process. Currently only the scdnkmake function uses "keyexpr". 172 CHAPTER 8, THE SOFTC DATABASE LIBRARY SEE ALSO scdnkmake. EXAMPLE #include <sc_base.h> void main() { scdinit(20,0); scdncreate("TOCDATE.NDX",'c',"dtoc(date) + time",16); scdterm(); } 173 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdnexpr USAGE signed int scdnexpr( signed int handle, signed char *keyexpr ); PROTOTYPE IN sc_base.h DESCRIPTION scdnexpr gets the index key expression and returns it as an ASCIIZ string into a user supplied buffer "keyexpr". The user must ensure that the buffer is large enough (the key expression length can be determined via a call to scdninfo) to hold the entire key expression. NOTES A NULL byte will be appended to the end of the expression string returned. If you are dynamically allocating memory be sure to make the buffer large enough. SEE ALSO scdninfo. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int ndx; char buffer[512]; scdinit(20,0); if (scdnopenx(&ndx, "TOCNAME.NDX", SC_BUFFER) == SC_SUCCESS) { scdnexpr(ndx,buffer); printf("key expression = %s",buffer); 174 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdnclose(ndx); } scdterm(); } 175 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdnflush USAGE signed int scdnflush( signed int handle ); PROTOTYPE IN sc_base.h DESCRIPTION scdnflush will write the contents of the I/O cache to disk. An I/O cache will be used only if the index file was opened with SC_BUFFER in the command field. SEE ALSO scdnopenx EXAMPLE #include <string.h> #include <softc.h> #include <sc_base.h> void main() { int dbf, ndx; char *key; long record; scdinit(20,0); if (scddopenx(&dbf, "TOC.DBF", SC_BUFFER) == SC_SUCCESS) { if (scdnopenx(&ndx, "TOCNAME.NDX", SC_BUFFER) == SC_SUCCESS) { scddfput(dbf,0,"TOC.DBF"); scddrput(dbf,&record,SC_ADD); scdnkmake(dbf,ndx,&key); scdnkadd(ndx,key,record); free(key); scdnflush(ndx); scdnclose(ndx); } scddclose(dbf); } 176 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdterm(); } 177 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdnindex USAGE signed int scdnindex( signed int datafile, signed char filename, signed char keytype, signed char keyexpr, signed char keylen ); PROTOTYPE IN sc_base.h DESCRIPTION scdnindex will create and build an dBASE index file. A blank file will be created using "filename", "keytype", "keyexpr", and "keylen". The resultant file will be opened, and the "datafile" will be read sequentially building keys from each data record. The index file will be closed at exit. The "datafile" must be open prior to the function call. EXAMPLE #include <sc_base.h> void main() { int dbf; scdinit(20,0); if (scddopenx(&dbf, "TOC.DBF", SC_BUFFER) == SC_SUCCESS) { scdnindex(dbf, "TOCNAME.NDX", SC_CKEY, "NAME", 64); scddclose(dbf); } scdterm(); } 178 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdninfo USAGE signed int scdninfo( signed int handle, SC_NDXINFO *info ); PROTOTYPE IN sc_base.h DESCRIPTION scdninfo gets the filename of the index file associated with "handle", the index key type, the maximum index key length, and the length of the index key expression. typedef struct { signed char fname[80]; /* file name */ signed char keytype; /* key type */ /* (C or N) */ signed char keylen; /* key length */ signed char exprlen; /* expression */ /* length */ SC_FLAGS flags; /* misc. flags */ } SC_NDXINFO; NOTES If you are using the expression length to dynamically allocate memory to hold the key expression be sure to add one to the length before allocation. SEE ALSO scdnopenx. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() 179 CHAPTER 8, THE SOFTC DATABASE LIBRARY { int ndx; SC_NDXINFO info; scdinit(20,0); if (scdnopenx(&ndx, "TOCNAME.NDX", SC_BUFFER) == SC_SUCCESS) { scdninfo(ndx,&info); printf("File name = %s\n",info.fname); printf("Index key type = %c\n",info.keytype); printf("Maximum key length = %d\n",info.keylen); printf("Key expression length = %d\n",info.exprlen); scdnclose(ndx); } scdterm(); } 180 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdnkadd USAGE signed int scdnkadd( signed int handle, void *key, signed long recno ); PROTOTYPE IN sc_base.h DESCRIPTION scdnkadd will add "key" to the index file specified by "handle". "recno" is the data record number to be associated with "key" (the data record pointed to by "recno" must exist prior to calling scdnkadd). NOTES When adding character keys it is not necessary to pad the key string to size with spaces (" "), the function will automatically do this for you. SEE ALSO scdnkdate, scdnkmake. EXAMPLE #include <string.h> #include <softc.h> #include <sc_base.h> void main() { int dbf, ndx; char name[65]; long recno; scdinit(20,0); if (scddopenx(&dbf, "TOC.DBF", 0) == SC_SUCCESS) { if (scdnopenx(&ndx, "TOCNAME.NDX", SC_BUFFER) == SC_SUCCESS) { strcpy(name,"XYZ.BAK"); 181 CHAPTER 8, THE SOFTC DATABASE LIBRARY scddfput(dbf,0,name); if (scddrput(dbf, &recno, SC_ADD) == SC_SUCCESS) scdnkadd(ndx,name,recno); scdnclose(ndx); } scddclose(dbf) } scdterm(); } 182 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdnkbot USAGE signed int scdnkbot( signed int handle, void *key, signed long *recno ); PROTOTYPE IN sc_base.h DESCRIPTION scdnkbot will set the current key pointer to the last logical key in the index and return the key value "key" and data record number "recno" associated with the new current key. NOTES The user must ensure that the buffer used to return the key is large enough to hold the entire key. The maximum length of the key can be determined via a call to scdninfo. Numeric keys are returned as doubles, and character keys are returned as strings. SEE ALSO scdninfo. EXAMPLE /* Character Key Example */ #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int ndx; char name[65]; long recno; 183 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdinit(20,0); if (scdnopenx(&ndx,"TOCNAME.NDX",SC_BUFFER) == SC_SUCCESS) { name[64] = 0; scdnkbot(ndx,name,&recno); printf("%s %ld\n",name,recno); scdnclose(ndx); } scdterm(); } /* Numeric Key Example */ #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int ndx; double length; long recno; scdinit(20,0); if (scdnopenx(&ndx,"TOCLNGTH.NDX",SC_BUFFER) == SC_SUCCESS) { scdnkbot(ndx,&length,&recno); printf("%lf %ld\n",length,recno); scdnclose(ndx); } scdterm(); } 184 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdnkcur USAGE signed int scdnkcur( signed int handle, void *key, signed long *recno ); PROTOTYPE IN sc_base.h DESCRIPTION scdnkcur will return the key value "key" and data record number "recno" associated with the current key in the index file. The current key pointer must be set by a call to either scdnkfind, scdnktop, scdnkbot, scdnknext, or scdnkprev before calling scdnkcur. NOTES The user must ensure that the buffer used to return the key is large enough to hold the entire key. The maximum length of the key can be determined via a call to scdninfo. SEE ALSO scdninfo, scdnkfind, scdnktop, scdnkbot, scdnknext, scdnkprev. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int ndx; char name[65], nam[65]; long recno, recn; 185 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdinit(20,0); if (scdnopenx(&ndx, "TOCNAME.NDX", SC_BUFFER) == SC_SUCCESS) { name[64] = 0; nam[64] = 0; scdnktop(ndx,name,&recno); scdnkcur(ndx,nam,&recn); printf("%s %s %ld %ld\n",name,nam,recno,recn); scdnclose(ndx); } scdterm(); } 186 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdnkdate USAGE signed int scdnkdate( double *key, signed char *string, signed int format ); PROTOTYPE IN sc_base.h DESCRIPTION scdnkdate will translate an ASCIIZ date string "string" of style "format" into a valid dBASE date key "key". Date string styles: SC_GREGOR mm/dd/yy SC_GREGORL mm/dd/yyyy SC_JULIAN yyyy/ddd SC_YMD yyyymmdd SC_DMY ddmmyy EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { double key; scdinit(20,0); scdnkdate(&key,"19890801"); printf("%lf",key); scdterm(); } 187 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdnkdel USAGE signed int scdnkdel( signed int handle, void *key, signed long recno ); PROTOTYPE IN sc_base.h DESCRIPTION scdnkdel will remove "key" from the index file specified by "handle". "recno" is used along with "key" to ensure that the proper key has been removed from the index file. NOTES When deleting character keys it is not necessary to pad the key string to size with spaces (" "), the function will automatically do this for you. SEE ALSO scdnkadd. EXAMPLE #include <string.h> #include <softc.h> #include <sc_base.h> void main() { int ndx; char date[16]; long recno; scdinit(20,0); if (scdnopenx(&ndx, "TOCDATE.NDX", SC_BUFFER) == SC_SUCCESS) { strcpy(date,"12/02/8809:33:01"); recno = 71L; scdnkdel(ndx,date,recno); 188 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdnclose(ndx); } scdterm(); } 189 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdnkfind USAGE signed int scdnkfind( signed int handle, void *key, signed long *recno, signed int method ); PROTOTYPE IN sc_base.h DESCRIPTION scdnkfind supports two key search methods (determined by "method"): SC_EXACT - find an exact match with "key" and "recno", and SC_FIRST - finds the first logical occurrence of "key" in the index and returns the associated record number "recno" if found. If a match cannot be found, the current key will be the physical key which would immediately precede "key". The current key's value and data record number will be returned in "key" and "recno". NOTES The user must ensure that the buffer used to return the key is large enough to hold the entire key. The maximum length of the key can be determined via a call to scdninfo. When searching using character keys it is not necessary to pad the key string to size with spaces (" "), the function will automatically do this for you. Searching for partial keys can be accomplished by using the SC_FIRST method. For example, you are using a fifteen character key size and you want to find the first entry where the first five characters are "ABCDE". All you need do is copy that five character ASCIIZ string into your key buffer and then call scdnkfind. The function will 190 CHAPTER 8, THE SOFTC DATABASE LIBRARY space pad to length and then find the first matching entry. Numeric keys are returned as doubles, and character keys are returned as strings. SEE ALSO scdninfo. EXAMPLE #include <string.h> #include <softc.h> #include <sc_base.h> void main() { int ndx; char key[16]; long recno; scdinit(20,0); if (scdnopenx(&ndx, "TOCNAME.NDX", SC_BUFFER) == SC_SUCCESS) { strcpy(key,"ABCDE"); recno = 7L; if (scdnkfind(ndx,key,&recno,SC_FIRST) != SC_SUCCESS puts(scemsg()); scddclose(ndx); } scdterm(); } 191 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdnkmake USAGE signed int scdnkmake( signed int datahandle, signed int indexhandle, void **key ); PROTOTYPE IN sc_base.h DESCRIPTION scdnkmake will build an index key using the key expression of the index file specified by "indexhandle" and the data found in the output buffer of the data file "datahandle". Memory space for the "key" will be allocated and the address of this block will be returned. The key expression can consist of either the data field name or one of five dBASE functions or a combination thereof. Data field types of date, numeric, or character are allowed. dBASE functions dtoc, left, right, str, and substr are currently supported by scdnkmake. Following is a brief description of the five expression functions: dtoc will convert data from a date field to an ASCIIZ string of the format mm/dd/yy. Syntax is: dtoc(field_name) left will return the left portion of a character field as an ASCIIZ string. The number of characters returned is specified after the field name. Syntax is: left(field_name,number) 192 CHAPTER 8, THE SOFTC DATABASE LIBRARY right will return the right portion of a character field as an ASCIIZ string. The number of characters returned is specified after the field name. This is a count from the right side of the field. Syntax is: right(field_name,number) str will convert a numeric field to an ASCIIZ string. The total length of the string and the number of decimal places are optional parameters. The default string length is 10 and the number of decimal places is 0. Syntax is: str(field_name,length,decimal_places) substr will return the middle portion of a character field. The starting offset into the field is a required parameter. The number of characters to be used is an optional parameter whose default value is the remainder of the field. Syntax is: substr(field_name,start,count) An example of a more complex key expression: right(dtoc(date),2)+left(dtoc(date,2) This expression would cause scdnkmake to create an index key string consisting of the year and month ("yymm"). For example if date equals "2/13/89" the resultant key would be "8902". NOTES For key expressions consisting of only one data field scdnkmake is probably an overkill. You can easily generate these keys yourself. See scdnkdate for information on date string to key translation. scdnkmake is a fairly large module and if not needed probably should not be used. This function 193 CHAPTER 8, THE SOFTC DATABASE LIBRARY is best used when the key expression is more complex. Memory is allocated for the generated key and it is the responsibility of the caller to free this memory when finished. SEE ALSO scdncreate, scdnkdate. EXAMPLE #include <sc_base.h> void main() { int ndx, dbf; char *key; long recno; scdinit(20,0); if (scddopenx(&dbf,"TOC.DBF",0) == SC_SUCCESS) { if (scdnopenx(&ndx, "TOCNAME.NDX", SC_BUFFER) == SC_SUCCESS) { scddfput(dbf,0,"HELLO.C"); scddrput(dbf,&recno,SC_ADD); scdnkmake(dbf,ndx,(void **) &key); scdnkadd(ndx,key,recno); free(key); /* free memory allocated for key */ scdnclose(ndx); } scddclose(dbf); } scdterm(); } 194 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdnknext USAGE signed int scdnknext( signed int handle, void *key, signed long *recno ); PROTOTYPE IN sc_base.h DESCRIPTION scdnknext will increment the key pointer and return the key value "key" and data record number "recno" associated with the new current key. If scdnknext is called immediately after opening the index file the first logical key will be returned. NOTES The user must ensure that the buffer used to return the key is large enough to hold the entire key. The maximum length of the key can be determined via a call to scdninfo. Numeric keys are returned as doubles, and character keys are returned as strings. SEE ALSO scdninfo. EXAMPLE /* Character Key Example */ #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { 195 CHAPTER 8, THE SOFTC DATABASE LIBRARY int ndx; char name[65]; long recno; scdinit(20,0); if (scdnopenx(&ndx,"TOCNAME.NDX",SC_BUFFER) == SC_SUCCESS) { scdnknext(ndx,name,&recno); /* return first key */ printf("%s %ld\n",name,recno); scdnclose(ndx); } scdterm(); } /* Numeric Key Example */ #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int ndx; double length; long recno; scdinit(20,0); if (scdnopenx(&ndx,"TOCLNGTH.NDX",SC_BUFFER) == SC_SUCCESS) { scdnknext(ndx,&length,&recno); /* return first key */ printf("%lf %ld\n",length,recno); scdnclose(ndx); } scdterm(); } 196 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdnkprev USAGE signed int scdnkprev( signed int handle, void *key, signed long *recno ); PROTOTYPE IN sc_base.h DESCRIPTION scdnkprev will decrement the key pointer and return the key value "key" and data record number "recno" associated with the new current key. If scdnkprev is called immediately after opening the index file the last logical key will be returned. NOTES The user must ensure that the buffer used to return the key is large enough to hold the entire key. The maximum length of the key can be determined via a call to scdninfo. Numeric keys are returned as doubles, and character keys are returned as strings. SEE ALSO scdninfo. EXAMPLE /* Character Key Example */ #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { 197 CHAPTER 8, THE SOFTC DATABASE LIBRARY int ndx; char name[65]; long recno; scdinit(20,0); if (scdnopenx(&ndx,"TOCNAME.NDX",SC_BUFFER) == SC_SUCCESS) { name[64] = 0; scdnkprev(ndx,name,&recno); /* get last key */ printf("%s %ld\n",name,recno); scdnclose(ndx); } scdterm(); } /* Numeric Key Example */ #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int ndx; double length; long recno; scdinit(20,0); if (scdnopenx(&ndx,"TOCLNGTH.NDX",SC_BUFFER) == SC_SUCCESS) { scdnkprev(ndx,&length,&recno); /* get last key */ printf("%lf %ld\n",length,recno); scdnclose(ndx); } scdterm(); } 198 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdnktop USAGE signed int scdnktop( signed int handle, void *key, signed long *recno ); PROTOTYPE IN sc_base.h DESCRIPTION scdnktop will set the current key pointer to the first logical key in the index and return the key value "key" and data record number "recno" associated with the new current key. NOTES The user must ensure that the buffer used to return the key is large enough to hold the entire key. The maximum length of the key can be determined via a call to scdninfo. Numeric keys are returned as doubles, and character keys are returned as strings. SEE ALSO scdninfo. EXAMPLE /* Character Key Example */ #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int ndx; char name[65]; long recno; 199 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdinit(20,0); if (scdnopenx(&ndx,"TOCNAME.NDX",SC_BUFFER) == SC_SUCCESS) { name[64] = 0; scdnktop(ndx,name,&recno); printf("%s %ld\n",name,recno); scdnclose(ndx); } scdterm(); } /* Numeric Key Example */ #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int ndx; double length; long recno; scdinit(20,0); if (scdnopenx(&ndx,"TOCLNGTH.NDX",SC_BUFFER) == SC_SUCCESS) { scdnktop(ndx,&length,&recno); printf("%lf %ld\n",length,recno); scdnclose(ndx); } scdterm(); } 200 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdnopenx USAGE signed int scdnopenx( signed int *handle, signed char *filename, signed int command ); PROTOTYPE IN sc_base.h DESCRIPTION scdnopenx opens a dBASE index file. Memory will be allocated for a file packet, I/O buffers, and other miscellaneous structures for use internally by the SoftC Database Library file manager. The index file will be tested as much as possible to insure that it is a legitimate dBASE index file. A block of memory large enough to hold at least 3 pages (1536 bytes) will be allocated during the open. Three pages is the minimum number of buffers required to add or delete index keys. The file will be opened under control of the "command" parameter. Using SC_RDWR opens the file for both read and write access. SC_RDONLY overrides SC_RDWR and causes the file to be opened for read access only. Any attempt to write to a read only file will result in an error (SC_READOLY). Using SC_EXCLUDE opens the file for exclusive use of this station (single user). SC_SHARED overrides SC_EXCLUDE and opens the file in multi- user mode. This mode is used when a LAN file is to be shared with other stations. Using SC_BUFFER opens the file with I/O caching enabled. Memory for up to 10 pages will be allocated during the open. Caching of page I/O greatly increases the speed of file access. Typically this mode is used with single user files. SC_FLUSH overrides SC_BUFFER and causes 201 CHAPTER 8, THE SOFTC DATABASE LIBRARY the file to be opened with no caching. This mode is generally used with file sharing, although it is not required. NOTES The index expression will be translated to upper case after being read from the index file. EXAMPLE #include <softc.h> #include <sc_base.h> void main() { int ndx; scdinit(20,0); if (scdnopenx(&ndx, "UNKNOWN.NDX", SC_BUFFER) == SC_SUCCESS) { scdnclose(ndx); } scdterm(); } 202 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdtclose USAGE signed int scdtclose( signed int handle ); PROTOTYPE IN sc_base.h DESCRIPTION scdtclose closes a memo file and frees all allocated memory associated with memo file "handle". SEE ALSO scdtopenx. EXAMPLE #include <sc_base.h> void main() { int dbt; scdinit(20,0); if (scdtopenx(&dbt,"TOC.DBT",SC_SHARED) == SC_SUCCESS) scdtclose(dbt); scdterm(); } 203 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdtcreate USAGE signed int scdtcreate( signed char *filename ); PROTOTYPE IN sc_base.h DESCRIPTION scdtcreate creates a memo file. This function will create a new memo file even if one had already existed. EXAMPLE #include <sc_base.h> void main() { scdinit(20,0); scdtcreate("TOC.DBT"); scdterm(); } 204 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdterm USAGE signed int scdterm( void ); PROTOTYPE IN sc_base.h DESCRIPTION scdterm is called once at the end of the program. Memory allocated by scdinit for internal control structures will be freed. All files open will be closed, any locks applied will be released, and any memory allocated for them will be freed. Any errors encountered will be returned in sc_code. NOTES It is probably a good idea to call atexit with scdterm at the very beginning of your application. This will ensure that all buffered data is written to disk before the program terminates. Be aware that scdterm can encounter errors which you may or may not be able to display if atexit is used. SEE ALSO scdinit. EXAMPLE #include <stdio.h> #include <sc_base.h> void main() { atexit(scdterm()); scdinit(20,0); . . body of application . puts("Terminating..."); } 205 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdtinfo USAGE signed int scdtinfo( signed int handle, SC_DBTINFO *info ); PROTOTYPE IN sc_base.h DESCRIPTION scdtinfo gets the name of the memo file associated with "handle" and returns it in a structure: typdef struct { signed char fname[80]; /* file name */ SC_FLAGS flags; /* misc. flags */ } SC_DBTINFO; SEE ALSO scdtopenx. EXAMPLE #include <softc.h> #include <sc_base.h> void main() { int dbt; SC_DBTINFO info; scdinit(20,0); if (scdtopenx(&dbt,"TOC.DBT",SC_SHARED) == SC_SUCCESS) { scdtinfo(dbt,&info); puts(info.fname); scdtclose(dbt); } scdterm(); } 206 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdtopenx USAGE signed int scdtopenx( signed int *handle, signed char *filename, signed int command ); PROTOTYPE IN sc_base.h DESCRIPTION scdtopenx opens a memo file. Memory will be allocated for a file packet and I/O buffers for use internally by the library file manager. The memo file will be tested as much as possible to insure that it is a legitimate dBASEIII+ memo file. The file will be opened under control of the "command" parameter. Using SC_RDWR opens the file for both read and write access. SC_RDONLY overrides SC_RDWR and causes the file to be opened for read access only. Any attempt to write to a read only file will result in an error (SC_READOLY). Using SC_EXCLUDE opens the file for exclusive use of this station (single user). SC_SHARED overrides SC_EXCLUDE and opens the file in multi- user mode. This mode is used when a LAN file is to be shared with other stations. SC_BUFFER is not used. "command" = 0 is equivalent to SC_EXCLUDE | SC_RDWR. 207 CHAPTER 8, THE SOFTC DATABASE LIBRARY EXAMPLE #include <softc.h> #include <sc_base.h> void main() { int dbt; scdinit(20,0); if (scdtopenx(&dbt, "TOC.DBT", SC_SHARED) == SC_SUCCESS) scdtclose(dbt); scdterm(); } 208 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdtpack USAGE signed int scdtpack( signed int datafile, signed int *memofile ); PROTOTYPE IN sc_base.h DESCRIPTION scdtpack will remove all "memofile" records which are not referenced by records in the "datafile". The "memofile" will be compressed so that all active records will be contiguous after the pack. Files opened with the read only flag (SC_RDONLY) cannot be packed. SEE ALSO scddpack, scdtopenx EXAMPLE #include <softc.h> #include <sc_base.h> void main() { int dbf, dbt; scdinit(20,0); if (scddopenx(&dbf, "TOC.DBF", SC_SHARED) == SC_SUCCESS) { if (scddopenx(&dbt, "TOC.DBT", SC_SHARED) == SC_SUCCESS) { scdtpack(dbf, &dbt); scdtclose(dbt); } scddclose(dbf); } scdterm(); } 209 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdtrget USAGE signed int scdtrget( signed int handle, signed long recno, signed char **data, signed int command ); PROTOTYPE IN sc_base.h DESCRIPTION scdtrget reads the desired record "recno" from the memo file specified by "handle". A buffer large enough to hold the text will be allocated, the address of which is returned in "data". "command" controls whether or not the soft carriage returns are stripped. Use SC_CRUNCHNG to leave the soft carriage returns alone, or use SC_CRDELETE to remove them. SEE ALSO scdtrget. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int dbt; char *data; scdinit(20,0); if (scdtopenx(&dbt,"TOC.DBT",SC_SHARED) == SC_SUCCESS) { scdtrget(dbt,1L,&data,SC_CRDELETE); puts(data); free(data); scddclose(dbt); 210 CHAPTER 8, THE SOFTC DATABASE LIBRARY } scdterm(); } 211 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdtrput USAGE signed int scdtrput( signed int handle, signed long *recno, signed char *data, signed int linelength ); PROTOTYPE IN sc_base.h DESCRIPTION scdtrput writes "data" to the memo file specified by "handle". The record number written is returned in "recno". This record number must be then written to the data output buffer via a call to scddfput. This function assumes that "data" is an ASCIIZ string with a maximum length of 65,536 characters. The user can directly control whether or not the soft carriage returns are added and, if so, where. If "linelength" is zero (0) no soft carriage returns will be added, else "linelength" specifies the maximum length of a memo line. It cannot be less than 10 nor greater than 132. NOTES Existing soft carriage returns are not removed before new ones are added. SEE ALSO scdtrput. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() 212 CHAPTER 8, THE SOFTC DATABASE LIBRARY { int dbt; char data[512]; long recno; scdinit(20,0); if (scdtopenx(&dbt,"TOC.DBT",SC_BUFFER) == SC_SUCCESS) { strcpy(data,"hello world."); scdtrput(dbt,&recno,data,66); printf("%ld",recno); scddclose(dbt); } scdterm(); } 213 CHAPTER 8, THE SOFTC DATABASE LIBRARY sceclr USAGE void sceclr( void ); MACRO IN softc.h DESCRIPTION sceclr is a macro which expands to "sc_code = SC_SUCCESS". The SoftC Database Library error flag (sc_code) will be cleared. SEE ALSO scemsg. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int dbt; char data[512]; long recno; scdinit(20,0); if (scdtopenx(&dbt,"TOC.DBT",SC_BUFFER) == SC_SUCCESS) { . . . scddclose(dbt); } else { sceclr(); puts("File not found. Create? Y/N"); if (getch() == 'Y') scdtcreate("TOC.DBT"); } scdterm(); } 214 CHAPTER 8, THE SOFTC DATABASE LIBRARY scemsg USAGE signed char *scemsg( void ); PROTOTYPE IN softc.h DESCRIPTION scemsg returns a pointer to the SoftC Database Library error or warning message which corresponds to the code found in sc_code. Refer to Appendix A for more information on error and warning codes. SEE ALSO sceclr. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int dbf; scdinit(20,0); if (scdopen(&dbf, "TOC.DBF", 0) != SC_SUCCESS) puts(scemsg()); else puts("File opened O.K."); scdterm(); } 215 Appendix A Result Codes and Messages Warning Codes and Messages SC_DELREC 1 "WARNING - record read is marked deleted" The data file record just read was flagged as "inactive" or "deleted". dBASE retains "deleted" records until the data file is packed. SC_EMPTY 2 "WARNING - file is empty" You have attempted to read from an index file which has no keys (is empty). SC_END 3 "WARNING - no more keys" The current key pointer is located at the physical end of the index file, either at the first key or at the last key. The actual position depends upon the function called. SC_NOFIND 4 "WARNING - could not find key in index file" The index key supplied to the function could not be found in the index file. Make sure that the index key is being built properly. SC_FLDTRUNC 5 "WARNING - data field truncated" The length of the data supplied is larger than the space allocated for the field in the data file record. This usually occurs only with character type fields. SC_FLDROUND 6 "WARNING - numeric field rounded" Numeric data is not stored in the data record in floating point format, rather it is converted to ASCII and then stored complete with a decimal point. If the numeric value desired to be written is more precise than space in the 216 APPENDIX A, RESULT CODES AND MESSAGES field permits, the data will be rounded and this warning returned. SC_FILENGTH 7 "WARNING - file length is incorrect" After data, index, or memo files are opened, the calculated file length is compared to the actual length. If they do not agree this code is returned. This warning will occur most frequently with data files. SC_NOTBFRD 8 "WARNING - I/O not buffered" An attempt was made to flush data to a file which was not opened with buffering enabled. Check how the data or index file was opened. It should be opened using the SC_BUFFER switch, not SC_FLUSH. See "scd?openx" function descriptions for more information. SC_MEMWRN 9 "WARNING - memory allocation incomplete" The file manager has been unsuccessful in allocating all the memory requested. This failure could be caused by many things: not enough memory available, memory threads corrupted, using a null pointer, ... Check your code to ensure that you do not have a problem in this area. You may need to use a larger data model. Error Codes and Messages SC_WRTFAIL -1 "ERROR - file write failure" This indicates an incomplete file write. The disk may be full. SC_RDFAIL -2 "ERROR - file read failure" This indicates an incomplete read. SC_MEMERR -3 "ERROR - memory allocation error" An attempt to allocate memory by the file manager has failed. This failure could be caused by many things: not enough memory available, memory threads corrupted, using a null pointer, ... Check your code to ensure that you do not 217 APPENDIX A, RESULT CODES AND MESSAGES have a problem in this area. You may have to go to a larger data model. SC_SKFAIL -4 "ERROR - file pointer reposition failed" This error is returned under two circumstances: actual seek failed or an attempt was made to seek beyond the end of the file in a function intending to read after seek. You should verify the record number (for either data, index, or memo files) being requested is legitimate. SC_NOFILE -5 "ERROR - file not found" You have attempted to open a data, index, or memo file which cannot be found. If you are certain the file exists, check the path specification. SC_FILBAD -6 "ERROR - file corrupted" The file manager has noticed something seriously wrong with the index file. Close and reopen the file, it may still be good. Otherwise you will have to rebuild the index file. SC_BADEXPR -7 "ERROR - bad user specified key expression" This indicates an error either with the length or the contents of the expression. The length can be no larger than 220 characters. See scdnkmake for more information on valid expression content. SC_NOHNDL -8 "ERROR - no handles available" Either DOS or the file manager has no more unused file handles. Each DOS application is allowed to have a maximum of twenty files open (up to the total defined by "FILES=" in "CONFIG.SYS"). Five of these files are reserved for console, printer, etc. which leaves only fifteen available for you. scdinit can be used to specify the maximum number of SoftC Database Library files which can be open simultaneously. SC_NOPGS -9 "ERROR - no index pages loaded" This is an internal file manager error which should never occur. Contact SoftC, Ltd. if you get this error. 218 APPENDIX A, RESULT CODES AND MESSAGES SC_BADPG -10 "ERROR - index page was not loaded" This is an internal file manager error which should never occur. Contact SoftC, Ltd. if you get this error. SC_CLOSFAIL -11 "ERROR - file close failure" This indicates that DOS could not properly close the file. Check errno for help in isolating further. SC_BADCMD -12 "ERROR - invalid command" This error is a general purpose indicator. It means that the I/O buffer selected, date string translation format, data file record write type, or maximum number of resident index pages was invalid depending upon the function executed. SC_BADHNDL -13 "ERROR - invalid handle number" The file handle does not match the function required file type or there is no file open for that handle. For example this will occur when using an index file handle with a data file function. SC_BADFNAME -14 "ERROR - invalid filename" The length of the file name was zero or the file name was invalid in some other way. The file manager expects file names to be complete with an extension. File paths are optional. SC_BADDATE -15 "ERROR - invalid date" The year, month, and/or day was invalid. Verify the date is correct. SC_BADTIME -16 "ERROR - invalid time" The hour, minute, and/or second was invalid. Verify the time is correct. 219 APPENDIX A, RESULT CODES AND MESSAGES SC_NODBT -17 "ERROR - file not in .DBT format" The memo file length was too short. This file cannot be used. SC_DBFVERS -18 "ERROR - invalid dBASE version" The dBASE version number in the data file header was unsupported. Only dBASEIII, dBASEIII+, and dBASEIV versions are valid. This file cannot be used. SC_DBFHLEN -19 "ERROR - file header length error" The length of the dBASE header was invalid. The length of the header must be divisible by 32 with a remainder of either 0 or 1. This file cannot be used. SC_DBFDATE -20 "ERROR - last file change date in error" The data file header last modified date was invalid. This file cannot be used. SC_NULLPARM -21 "ERROR - parameter address null" The address of a parameter is NULL. Check the parameters on the call to ensure they are correct. SC_BADKEYT -22 "ERROR - invalid key type" The selected key type is invalid for the index file type. Refer to scd?create for further information regarding allowable key types. SC_KEYLEN -23 "ERROR - invalid key length" The character key maximum length definition exceeds 100 characters. This error does not occur for numeric (or date) keys. SC_ITEMLEN -24 "ERROR - item length incorrect" The file manager index key item length not agree with the value read from the index file. This file cannot be used. 220 APPENDIX A, RESULT CODES AND MESSAGES SC_BADROOT -25 "ERROR - invalid root page" The index page number for the top of the Btree does not exist in the index file. This file cannot be used. SC_MAXKEYS -26 "ERROR - bad maximum number of keys per page" The file manager maximum number of index keys per index page does not agree with the value read from the index file. This file cannot be used. SC_FLDCNT -27 "ERROR - invalid number of fields" A data file record can consist of a maximum of 128 individual fields for dBASE III or 255 for dBASE IV. SC_BADFLDN -28 "ERROR - field name invalid" The field name length cannot exceed ten characters not including the null bye. SC_FLDLEN -29 "ERROR - bad field length" Character fields cannot be longer than 254 bytes. dBASE III numeric fields cannot be longer than 19 bytes. dBASE IV numeric and float fields cannot be longer than 20 bytes. This error will not occur for the other field types. SC_DECPL -30 "ERROR - decimal places parameter invalid" The decimal places definition portion of the field description cannot be less than 0 nor can it be greater than the field length minus two. SC_BADFLDT -31 "ERROR - invalid field type" Only character ('C'), date ('D'), logical ('L'), memo ('M'), and numeric ('N') are allowed in dBASE III files. Additionally, dBASE IV supports a floating point ('F') field type. 221 APPENDIX A, RESULT CODES AND MESSAGES SC_RECLEN -32 "ERROR - invalid record length" The record length cannot exceed 4000 bytes. Check your field lengths and make sure that they total 4000 or less. SC_BADDATA -33 "ERROR - bad data" The data you requested to be written into a data field was invalid. For example a pointer to a floating point variable was passed for a character field. Ensure the data type passed matches the field definition. SC_LINELEN -34 "ERROR - memo soft line length invalid" Valid values for line lengths are 0, and between 10 and 132. The line length parameter is used when the file manager is inserting soft carriage returns in memo text as it is written to the memo file. SC_MDXFLAG -35 "ERROR - MDX flag in DBF file invalid" The value found in byte twenty eight (28) of the dBASEIV data file is not valid. Only values of zero (0) and one (1) are currently supported. This may indicate a corrupted file. SC_READOLY -36 "ERROR - file open for reading only" An attempt was made to execute a write function to a file opened for reading only. Check the switches used to open the file. SC_LCKVIOL -37 "ERROR - file locking violation" This only occurs when sharing files. There are two situations when this error is returned: 1) attempting to lock a record/file that is already locked, and 2) attempting to unlock a record/file which is not currently locked. SC_LCKBOVR -38 "ERROR - sharing buffer overflow" This is an internal file manager error which should never occur. Contact SoftC, Ltd. if you get this error. 222 APPENDIX A, RESULT CODES AND MESSAGES SC_NOPATH -39 "ERROR - path not found" The path specified in the file open command could not be found. Make sure the path is correct. SC_ACCDEN -40 "ERROR - access to file denied" This error occurs only when sharing files. The file could not be accessed. This can occur if another station has the file opened in SC_EXCLUDE mode. SC_BADACC -41 "ERROR - invalid access code" This is an internal file manager error which should never occur. Contact SoftC, Ltd. if you get this error. SC_NOTLCKD -42 "ERROR - file must be locked first" This error occurs only when sharing files. The file must be locked before executing this function. SC_NEWDEV -43 "ERROR - diskette changed" DOS believes that the diskette has been changed. SC_MINKEYS -44 "ERROR - bad minimum number of keys per page" The value found in the minimum number of keys per page field was incorrect. This error can occur only when opening Clipper index files. This may indicate a corrupted file. SC_FILSOPEN -45 "ERROR - some files remain open" This error is returned by scdterm. In order for this error to occur, scdinit must have been called with SC_USEXHNDL switch and the "files parameter is greater than twenty. The error indicates that a file handle above nineteen (19) remains open after all SoftC files have been closed. Make sure that all of your files are closed before calling scdterm. 223 APPENDIX A, RESULT CODES AND MESSAGES Other Messages "Unknown error or warning code" This message is returned by scemsg if it cannot find a message which corresponds to the value found in sc_code. The function scemsg may be old or otherwise incompatible with the value found in sc_code. 224 Appendix B Diskette TOC Demo Program The Diskette TOC Program is a simple program which will create a database (TOC.DBF) and three index files. The database record contains the following fields: field name type length description __________________________________________ NAME C 64 file name LENGTH N 10.0 file size in bytes DATE D 8 file creation date TIME C 8 file creation time ATTRIBUTE C 3 file attribute (READ ONLY, HIDDEN) The index files created are: TOCNAME (file name), TOCLNGTH (file length), and TOCDATE (file creation date and time). The program uses the DOS functions "findfirst" and "findnext" to step through the files in the directory. It reformats the compressed file date ("mm/dd/yy") and time ("hh:mm:ss") and places the resultant data into the output buffer. After all fields have been entered it will append a record to the end of the database and add keys for each file found. After all records have been added, the contents of the data file are displayed in the filename order using index file TOCNAME. The program only works on the current directory. It does not support any command line arguments, although it would be easy for the user to add such support. Very little error checking is performed. The program as it stands has value only in the demonstration of certain library functions: scdinit, scdterm, scddclose, scddcreate, scddopenx, scddfget, scddfput, scddrget, scdrput, 225 APPENDIX B, DISKETTE TOC DEMO PROGRAM scd?create, scd?openx, scd?kadd, scd?kmake, scd?knext, scd?ktop However, it could form the basis of a diskette cataloger, or ... 226 Index long 35 Data to long 40 field integer 29 array 93, 101 to month read string 41 memo 210 to string strings 99 day of week 43 values 97 integers 30 write long 36 memo 212 month 47 strings 107 string 42 values 105 file Functions close 92 sccdi2l 19, 29, 35 create 93 sccdi2s 19, 30, 39, 44 flush 103 sccdiget 20, 31, 45 I/O buffer clear 117 sccdileap 20, 32, 46 I/O cache 89 sccdiperm 20, 33, 48 information 109 sccdl2dow 20, 34 last update 113 sccdl2i 19, 29, 35 lock file 111 sccdl2sx 19, 36 lock record 121 sccds2day 20, 37, 38, 41 number of records 128 sccds2dow 20, 34, 37, 38 open 114 sccds2i 19, 30, 39 pack 116 sccds2lx 19, 36, 40 position 91, 96, 123 sccds2mon 20, 41 record sccds2s 19, 42, 44 status 126 sccdsday 20, 43, 47 unlock 129 sccdsdiff 20, 44 record sccdsget 20, 31, 45 delete 118 sccdsleap 20, 32, 46 read 119 sccdsmonth 20, 43, 47 recover 127 sccdsperm 20, 33, 48 write 124 sccdsvalid 20, 30, 44, 49 Date sccdxlat 42 calculate sccti2s 20, 50, 52, 53 days per month 33, 48 scctiget 21, 51 difference 44 sccts2i 20, 50, 52 get from DOS scctsdiff 21, 53 integers 31 scctsget 21, 45, 54 string 45 scctsvalid 21, 50, 53, test 55 leap year 32, 46 scdcbfrsz 56 valid 49 scdcclose 58 translate scdccreate 59, 65, 80 to day of week scdcexpr 61 integer 37 scdcflush 63 long 34 scdcindex 65 string 38 scdcinfo 61, 66, 70, 72, to integers 39 76, 77, 81, 83, 85 227 INDEX scdckadd 68, 74 scddunlock 16, 24, 111, scdckbot 70, 72 121, 129 scdckcur 72 scdibfrsz 131 scdckdel 74 scdiclose 133 scdckfind 72, 76 scdicreate 134, 157, 160 scdckmake 60, 68, 78 scdiexpr 136 scdcknext 72, 81 scdiflush 138 scdckprev 72, 83 scdiindex 140 scdcktop 72, 85 scdiinfo 136, 141, 145, scdcopenx 63, 66, 87 147, 153, 154, 158, scddbfrsz 14, 89 161, 163 scddbof 13, 91, 96, 123 scdikadd 143, 151 scddclose 13, 92 scdikbot 145, 147 scddcreate 13, 15, 93, scdikcur 147 94 scdikdate 143, 149, 157, scddeof 13, 91, 96, 123 160 scddfget 15, 22, 97, 99, scdikdel 151 105, 107, 119 scdikfind 147, 153 scddfgets 15, 98, 99, scdikmake 135, 143, 149, 107 155, 160 scddfinfo 15, 97, 98, scdiknext 147, 158 99, 101 scdiknum 18, 143, 149, scddflush 14, 103 157, 160 scddfnam2no 15, 104 scdikprev 147, 161 scddfput 15, 16, 22, 98, scdiktop 147, 163 105, 107, 119, 124, scdinit 2, 7, 22, 165, 212 205, 218, 223 scddfputs 15, 99, 105, scdiopenx 138, 141, 167 107, 124 scdnbfrsz 17, 169 scddinfo 13, 109 scdnclose 17, 171 scddlock 15, 24, 111, scdncreate 17, 172, 194 121, 129 scdnexpr 17, 174 scddlud 13, 113 scdnflush 17, 176 scddopenx 13, 89, 92, scdnindex 17, 116, 178 103, 109, 111, 114, scdninfo 17, 174, 179, 115, 116, 121, 129 183, 185, 190, 191, scddpack 14, 116, 209 195, 197, 199 scddrclear 14, 117 scdnkadd 18, 181, 188 scddrcopy 124 scdnkbot 17, 183, 185 scddrdel 14, 118, 127 scdnkcur 17, 185 scddrget 14, 98, 99, scdnkdate 18, 181, 187, 119, 124, 126 194 scddrinfo 14, 101, 120 scdnkdel 18, 188 scddrlock 16, 24, 111, scdnkfind 17, 185, 190 121, 129 scdnkmake 18, 172, 173, scddrnum 15, 91, 96, 123 181, 192, 218 scddrput 14, 119, 124 scdnknext 17, 185, 195 scddrstat 15, 126 scdnkprev 17, 185, 197 scddrundel 14, 118, 127 scdnktop 17, 185, 199 scddsize 13, 128 scdnopenx 16, 176, 179, 201 228 INDEX scdtclose 16, 203 dtoc 18, 192 scdtcreate 16, 204 left 18, 192 scdterm 7, 13, 22, 165, right 18, 192, 193 205, 223 str 18, 192, 193 scdtinfo 16, 206 substr 18, 192, 193 scdtopenx 16, 203, 206, read 174 207, 209 file scdtpack 16, 116, 209 cache 169 scdtrget 16, 97, 98, 210 close 171 scdtrput 16, 212 create 172 sceclr 23, 214, 215 flush 176 scemsg 23, 214, 215, 224 index 178 open 201 Global variables key sc_code 22, 23, 205, add 181 214, 215, 224 build 187, 192 sc_date_style 22, 97, delete 188 105 get first 199 sc_version 22 get last 183 read next 195 Index read previous 197 Clipper search 190 expression FoxBASE+ defined 59, 78 expression functions defined 134, 155 dtoc 78 functions left 78 dtoc 155 right 78, 79 left 155 str 78, 79 right 155, 156 substr 78, 79 str 155, 156 read 61 substr 155, 156 file read 136 cache 56 file close 58 cache 131 create 59 close 133 flush 63 create 134 index 65 flush 138 open 87 index 140 key open 167 add 68 key build 78 add 143 delete 74 build 149, 155, 160 get first 85 delete 151 get last 70 get first 163 read next 81 get last 145 read previous 83 read next 158 search 76 read previous 161 dBASE search 153 expression defined 172, 192 Initialization 165 functions 229 INDEX Memo SC_NOPATH 223 file SC_NOPGS 218 pack 209 SC_NOTLCKD 223 SC_NULLPARM 220 Memo file SC_RDFAIL 217 close 203 SC_READOLY 222 create 204 SC_RECLEN 222 open 207 SC_SKFAIL 218 read 210 SC_WRTFAIL 217 write 212 message translate 215 warnings Return codes SC_DELREC 216 clear 214 SC_EMPTY 216 defined 22, 216 SC_END 216 errors SC_FILENGTH 217 SC_ACCDEN 223 SC_FLDROUND 216 SC_BADACC 223 SC_FLDTRUNC 216 SC_BADCMD 219 SC_MEMWRN 217 SC_BADDATA 222 SC_NOFIND 216 SC_BADDATE 219 SC_NOTBFRD 217 SC_BADEXPR 218 SC_BADFLDN 221 SC_ADD 124 SC_BADFLDT 221 SC_BADFNAME 219 SC_BUFFER 14, 17, 63, 87, SC_BADHNDL 219 89, 103, 114, 138, 167, SC_BADKEYT 220 176, 201, 207, 217 SC_BADPG 219 SC_BADROOT 221 SC_CKEY 59, 134, 172 SC_BADTIME 219 SC_CLOSFAIL 219 SC_CRDELETE 210 SC_DBFDATE 220 SC_DBFHLEN 220 SC_CRUNCHNG 210 SC_DBFVERS 220 SC_DECPL 221 SC_CSHMS 19, 50, 52, 53, SC_FILBAD 218 54, 55 SC_FILSOPEN 223 SC_FLDCNT 221 SC_DB3 94 SC_FLDLEN 221 SC_ITEMLEN 220 SC_DB4 94 SC_KEYLEN 220 SC_LCKBOVR 222 SC_DELREC 126 SC_LCKVIOL 222 SC_LINELEN 222 SC_DKEY 59, 134, 172 SC_MAXKEYS 221 SC_MDXFLAG 222 SC_DMY 19, 22, 30, 36, 37, SC_MEMERR 217 38, 39, 40, 41, 42, 43, 44, SC_MINKEYS 223 45, 46, 47, 48, 49, 113, SC_NEWDEV 223 149, 187 SC_NODBT 220 SC_NOFILE 218 SC_EXACT 76, 153, 190 SC_NOHNDL 218 230 INDEX SC_EXCLUDE 87, 114, 168, SC_TRUE 13, 32, 46, 91, 96 201, 207, 223 SC_UNIQUE 59, 134, 172 SC_FALSE 32, 46, 91, 96 SC_UPDATE 124 SC_FIELD 93, 101 SC_USEXHNDL 223 SC_FIRST 76, 153, 190, 191 SC_USEXHNDLS 165 SC_FLUSH 88, 114, 167, 201, 217 SC_YMD 19, 30, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, SC_GETSZ 56, 89, 131, 169 46, 47, 48, 49, 113, 149, 187 SC_GREGOR 19, 22, 30, 36, 37, 38, 39, 40, 41, 42, 43, Structures 44, 45, 46, 47, 48, 49, 97, SC_DBFINFO 109 105, 113, 149, 187 SC_DBFRINFO 120 SC_DBTINFO 206 SC_GREGORL 19, 30, 36, 37, SC_FIELD 93, 101 38, 39, 40, 41, 42, 43, 44, SC_FLAGS 66, 109, 141, 45, 46, 47, 48, 49, 113, 179, 206 149, 187 SC_IDXINFO 141 SC_NDXINFO 179 SC_JULIAN 19, 30, 36, 37, SC_NTXINFO 66 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 113, Termination 205 149, 187 Time SC_LKEY 134 calculation 53 get from DOS SC_MIL 19, 50, 52, 53, 54, integers 51 55 string 54 test 55 SC_NKEY 59, 134, 172 translation 50, 52 SC_NOTUSED 116 SC_RDONLY 87, 114, 116, 167, 201, 207 SC_RDWR 87, 114, 167, 201, 207 SC_SETSZ 56, 89, 131, 169 SC_SHARED 87, 111, 114, 121, 129, 168, 201, 207 SC_SUCCESS 126 231