Power-Programmierung

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

/ Power-Programmierung / CD2.mdf / c / library / dos / database / softc210 / docs / manual.doc < prev next >

Wrap

Text File | 1991-01-26 | 371.0 KB | 13,267 lines

SoftC Database Library Reference Guide Version 2.10 Manual and Software Copyright 1988, 1989, 1990 by SoftC, Ltd. 16820 Third Street North East Ham Lake, Minnesota 55304 Telephone/Facsimile (612) 434-6968 ALL RIGHTS RESERVED This document describes version 2.0 of the SoftC Database Library, released in July, 1990. Table Of Contents Chapter 1 Introduction..........................................1 Registration.................................................2 Shareware....................................................2 Typographic Conventions......................................2 Trademarks...................................................3 Support and Updates..........................................3 Chapter 2 Before You Begin......................................4 The READ.ME File.............................................4 The Demonstration Package....................................4 Sample Files.................................................4 Header Files.................................................5 Help Files...................................................5 Library Object Code Files....................................6 Library Source Files.........................................6 Installing SoftC on Your System..............................7 SoftC Applications...........................................8 Compiling with Microsoft C...................................8 Compiling with Quick C.......................................9 Compiling with Turbo C.......................................9 Compiling with Turbo C++.....................................9 Compiling with Zortech C++...................................9 Recompiling the Database Libraries..........................10 OS/2, Windows 3.0 and UNIX Support..........................10 Function Naming Conventions.................................11 Chapter 3 A Database Tutorial..................................12 Sequential Files............................................12 Random Access Files.........................................12 Keys........................................................13 ISAM........................................................13 Binary Trees................................................13 B- and B+ Trees.............................................13 Chapter 4 Database Functions...................................15 dBASE Data File Functions...................................15 dBASE Data Record I/O.......................................16 dBASE Data Field I/O........................................17 File Sharing Functions......................................17 dBASEIII Memo File Functions................................18 FoxPro Memo Functions.......................................18 dBASE Index File Functions..................................19 dBASE Index Page Functions..................................19 dBASE Index Key Functions...................................19 Clipper Index Functions.....................................20 FoxBase/FoxPro Index Functions..............................20 Chapter 5 Clock & Calendar Functions...........................21 Conversion to String........................................21 Conversion to Integers......................................21 i TABLE OF CONTENTS Conversion to Long Integer..................................21 Day of Week Conversions.....................................22 Month Conversions...........................................22 Date String Calculations....................................22 Date Validation and Testing.................................22 Get Current Date from DOS...................................22 Time String to Numeric Conversion...........................22 Time Numeric to String Conversion...........................22 Time String Calculations....................................23 Time Validation.............................................23 Get Current Time from DOS...................................23 Chapter 6 Miscellaneous Functions..............................24 Program Initialization......................................24 Program Termination.........................................24 Library Version.............................................24 Default Date String Format..................................24 Errors and Warnings.........................................24 Chapter 7 Sharing Files on a LAN...............................26 Updating a Data Record......................................26 Adding or Removing a Data Record............................27 Chapter 8 The SoftC Database Library...........................29 sccdi2l.....................................................31 sccdi2s.....................................................31 sccdiget....................................................32 sccdileap...................................................33 sccdiperm...................................................34 sccdl2dow...................................................35 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 ii TABLE OF CONTENTS scdcbfrsz...................................................56 scdcclose...................................................57 scdccreate..................................................58 scdcexpr....................................................59 scdcflush...................................................60 scdcindex...................................................61 scdchget....................................................62 scdcinfo....................................................63 scdckadd....................................................65 scdckbot....................................................66 scdckcur....................................................67 scdckdel....................................................68 scdckfind...................................................69 scdckmake...................................................71 scdcknext...................................................73 scdckprev...................................................74 scdcktop....................................................75 scdcopenx...................................................76 scddbfrsz...................................................77 scddbof.....................................................78 scddclose...................................................79 scddcreate..................................................80 scddeof.....................................................82 scddfget....................................................83 scddfgets...................................................85 scddfinfo...................................................86 scddflush...................................................88 scddfnam2no.................................................88 scddfput....................................................89 scddfputs...................................................91 scddhget....................................................92 scddinfo....................................................93 scddlock....................................................94 scddlud.....................................................95 scddopenx...................................................96 scddpack....................................................97 scddrclear..................................................98 scddrdel....................................................99 scddrget....................................................99 scddrgetx..................................................100 scddrinfo..................................................101 scddrlock..................................................102 scddrnum...................................................103 scddrput...................................................104 scddrputx..................................................105 scddrstat..................................................107 scddrundel.................................................108 scddsize...................................................109 scddunlock.................................................110 scdibfrsz..................................................111 scdiclose..................................................112 iii TABLE OF CONTENTS scdicreate.................................................112 scdiexpr...................................................114 scdiflush..................................................115 scdihget...................................................116 scdiindex..................................................117 scdiinfo...................................................118 scdikadd...................................................119 scdikbot...................................................120 scdikcur...................................................121 scdikdate..................................................122 scdikdel...................................................123 scdikfind..................................................124 scdikmake..................................................126 scdiknext..................................................128 scdiknum...................................................130 scdikprev..................................................131 scdiktop...................................................132 scdinit....................................................134 scdiopenx..................................................134 scdnbfrsz..................................................136 scdnclose..................................................137 scdncreate.................................................137 scdnexpr...................................................138 scdnflush..................................................139 scdnhget...................................................140 scdnindex..................................................141 scdninfo...................................................142 scdnkadd...................................................143 scdnkbot...................................................144 scdnkcur...................................................146 scdnkdate..................................................147 scdnkdel...................................................148 scdnkfind..................................................149 scdnkmake..................................................151 scdnknext..................................................153 scdnkprev..................................................155 scdnktop...................................................157 scdnopenx..................................................158 scdtclose..................................................159 scdtcreate.................................................160 scdterm....................................................160 scdthget...................................................161 scdtinfo...................................................162 scdtopenx..................................................163 scdtpack...................................................164 scdtrget...................................................165 scdtrput...................................................166 scdwclose..................................................167 scdwcreate.................................................168 scdwhget...................................................168 scdwinfo...................................................169 iv TABLE OF CONTENTS scdwopenx..................................................170 scdwpack...................................................171 scdwrget...................................................172 scdwrput...................................................173 sceclr.....................................................174 scemsg.....................................................175 Appendix A Result Codes and Messages..........................177 Warning Codes and Messages.................................177 Error Codes and Messages...................................178 Other Messages.............................................186 Appendix B Diskette TOC Demo Program..........................187 Index.........................................................189 v 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 why the SoftC Database Library was written. It 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: Clipper, dBASE III+, dBXL, FoxBase, FoxPro and Quicksilver. - 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 2.x, Turbo C 2.0, and Turbo C++ 1.0. These routines are written entirely in C. User's Reference Guide 1 CHAPTER 1, INTRODUCTION 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 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) is 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. 2 SoftC Database Library CHAPTER 1, INTRODUCTION 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. Trademarks Clipper is a registered trademark of Nantucket Software. dBASE, dBASEIII, and dBASEIV are registered trademarks of Ashton-Tate. dBXL is a registered trademark of WordTech Systems, Inc. FoxBase and FoxPro are registered trademarks of Fox Software. Microsoft is a registered trademark of Microsoft Corporation. Quicksilver is a trademark of Quicksilver Software, Inc. 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/facsimile (612) 434-6968 modem We do not have a BBS, but we have a second telephone line which can be used to upload/download. Please call the above number first so that arrangements can be made. GEnie "K.SCHUMANN" CompuServ 73667,3420. User's Reference Guide 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. The Demonstration Package The SoftC Database Library demonstration package consists of several archive files: DOCS.xxx - documentation for library, SAMPLE.xxx - sample programs, HEADERS.xxx - header files, and the small memory model libraries for supported compilers and operating systems. You are encouraged to freely share these completely unmodified programs with others. The documentation archive file contains three (3) files: LICENSE.DOC MANUAL.DOC ORDER.DOC The small memory model library archives are: MSC5S.xxx Microsoft C 5.x MSC6S.xxx Microsoft C 6.0 TC2S.xxx Turbo C 2.0 TCP1S.xxx Turbo C++ 1.0 ZTC2S.xxx Zortech 2.0 OS2S.xxx Microsoft C 6.0 for OS/2 Sample Files There are three sample files provided in the archive file SAMPLE.COM. They are variations of the program described in Appendix B. User's Reference Guide 4 CHAPTER 2, BEFORE YOU BEGIN CLIPPER.C Clipper version DBASE.C dBASE III version FOXBASE.C FoxBASE/FoxPro version Header Files There are three header files provided in the archive file HEADERS.COM: SOFTC.H SC_BASE.H SC_CLOCK.H SOFTC.H contains some common prototypes and definitions for error/warning codes. SC_BASE.H contains structure definitions and prototypes for data, memo, and index file input/output. SC_CLOCK.H contains structure definitions and prototypes for clock and calendar functions. There are two additional header files provided to users registered at the source code level in the archive file HEAD.COM: SOFTC.NTL SC_BASE.NTL SOFTC.NTL contains some common internal prototypes and definitions. SC_BASE.NTL contains structure definitions and internal prototypes for data, memo, and index file input/output. Help Files There are two help files included in the package: GUIDE.COM MSC-HELP.EXE GUIDE.COM is a Norton Guide compatible database containing function and error/warning code descriptions, structure definitions, etc. MSC-HELP.EXE is a Microsoft Programmer's Workbench compatible help file containing much the same information as GUIDE.COM. User's Reference Guide 5 CHAPTER 2, BEFORE YOU BEGIN Library Object Code Files Each of the memory model libraries for your selected compiler is archived in its own individual file. This is done so that you can extract only the memory model you actually need. SMALL.EXE Small memory model library MEDIUM.EXE Medium COMPACT.EXE Compact LARGE.EXE Large HUGE.EXE Huge The HUGE memory model library will not be present for all compilers. Library Source Files The source code archive (SOURCE.EXE), for users registered at that level, contains 139 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 CHGET.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 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 DHGET.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 ERRLOG.C HCREATE.C HEOF.C HERASE.C HEXIST.C HFLUSH.C HLEN.C HLOCK.C HREAD.C 6 SoftC Database Library CHAPTER 2, BEFORE YOU BEGIN HRENAME.C HSEEK.C HSIZE.C HTELL.C HWRITE.C IBFRSZ.C ICREATE.C IEXPR.C IFLUSH.C IHGET.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 NHGET.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 STRUPR.C TCREATE.C THGET.C TINFO.C TOPEN.C TPACK.C TRGET.C TRPUT.C WCREATE.C WHGET.C WINFO.C WOPEN.C WPACK.C WRGET.C WRPUT.C 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. User's Reference Guide 7 CHAPTER 2, BEFORE YOU BEGIN 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: #include <sc_base.h> /* global declarations */ void main() { /* local declarations */ scdinit(15,0); atexit(scdterm()); . . . /* body of application */ . . . } 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 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 8 SoftC Database Library CHAPTER 2, BEFORE YOU BEGIN 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 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 Compiling with Turbo C++ To use the library with Turbo C++'s command line compiler simply include the library name in the file name list: tcc -ms -I<header_file_path> -L<lib_file_path> myprog scdtp10s.lib Compiling with Zortech C++ To use the library with Zortech C++'s command line compiler simply include the library name in the file name list: User's Reference Guide 9 CHAPTER 2, BEFORE YOU BEGIN ztc -a -b -c -I<header_file_path> -ms -o -r myprog scdzc20s.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. Microsoft C command line: cl /AS /c /D__PCDOS__ /Olt /W3 /Zp *.c Quick C command line: qcl /AS /c /D__PCDOS__ /W3 /Zp *.c Turbo C/C++ command line: tcc -c -D__PCDOS__ -I<header_file_path> -ms -O *.c Zortech C++ command line: ztc -a -b -c -D__PCDOS__ -I<header_file_path> -ms -o -r *.c Refer to your compiler documentation for instructions for replacing modules in libraries. OS/2, Windows 3.0 and UNIX Support Although we can not provide complete support for OS/2, Windows 3.0 and UNIX/XENIX, the library is being used in each of these environments now. The source code for the library has support for OS/2 and UNIX/XENIX built in and we do have a set of libraries built specifically for OS/2. 10 SoftC Database Library CHAPTER 2, BEFORE YOU BEGIN 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, ...) "scdi" FoxBase/FoxPro index file functions (open, close, etc.) "scdik" FoxBase/FoxPro 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.) "scdw" FoxPro memo file functions (open, close, etc.) User's Reference Guide 11 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/FoxPro 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. User's Reference Guide 12 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. User's Reference Guide 13 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/FoxPro 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. 14 SoftC Database Library 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. User's Reference Guide 15 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. 16 SoftC Database Library 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 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), User's Reference Guide 17 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. FoxPro Memo Functions All the dBASE Memo File functions listed above have FoxPro equivalents. There are two differences between dBASE III and FoxPro memo files: dBASE uses a constant 512 byte block size where FoxPro allows the block size to be selected (between 18 SoftC Database Library CHAPTER 4, DATABASE FUNCTIONS 33 and 16384 bytes), and dBASE always appends memo text at the end of the file where FoxPro will allow you to update a memo block. 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 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 User's Reference Guide 19 CHAPTER 4, DATABASE FUNCTIONS 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. 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/FoxPro Index Functions All the dBASE Index File functions listed above have FoxBase/FoxPro equivalents. FoxBase/FoxPro has one additional function used to create a numeric key (scdiknum). The FoxBase/FoxPro numeric key format as stored on disk is different from 'C' doubles. 20 SoftC Database Library 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. User's Reference Guide 21 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. 22 SoftC Database Library 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). User's Reference Guide 23 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 User's Reference Guide 24 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. User's Reference Guide 25 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 User's Reference Guide 26 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. User's Reference Guide 27 CHAPTER 7, SHARING FILES ON A LAN The memo file must be updated before the data file because the memo record number must be recorded in the data record. 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/FoxPro 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. 28 SoftC Database Library 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/FoxPro index files) found in Appendix B. The following sample function description explains how to use this portion of the SoftC Database Library Reference Guide. User's Reference Guide 29 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. RETURN VALUE Some of the return codes are listed here for selected functions. A complete listing of all return codes can be found in Appendix A. 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. 30 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY sccdi2l___________________________________ USAGE int sccdi2l( long *date, int year, int month, 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(); } sccdi2s___________________________________ USAGE int sccdi2s( char *string, int format, int year, int month, int day ); User's Reference Guide 31 CHAPTER 8, THE SOFTC DATABASE LIBRARY 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() { char d[9]; sccdi2s(d,SC_YMD,1989,2,13); puts(d); } sccdiget__________________________________ USAGE int sccdiget( int *year, int *month, int *monthday, int *dayofweek ); 32 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY 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); } sccdileap_________________________________ USAGE int sccdileap( int leap ); User's Reference Guide 33 CHAPTER 8, THE SOFTC DATABASE LIBRARY 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 VALUE 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."); } sccdiperm_________________________________ USAGE int sccdiperm( char *days, int year, 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() { char d; sccdiperm(&d,1989,3); 34 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY printf("%d",d); } sccdl2dow_________________________________ USAGE int sccdl2dow( char *dayofweek, 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); } sccdl2i___________________________________ USAGE int sccdl2i( int *year, int *month, int *day, long date ); User's Reference Guide 35 CHAPTER 8, THE SOFTC DATABASE LIBRARY 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); } sccdl2sx__________________________________ USAGE int sccdl2sx( char *string, int format, 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: 36 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY 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() { char d[9]; sccdl2sx(d,SC_YMD,726489); puts(d); } sccds2day_________________________________ USAGE int sccds2day( char *dayofweek, char *daystr, 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: User's Reference Guide 37 CHAPTER 8, THE SOFTC DATABASE LIBRARY 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); } sccds2dow_________________________________ USAGE int sccds2dow( char *dayofweek, char *daystr, 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: 38 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY 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); } sccds2i___________________________________ USAGE int sccds2i( int *year, int *month, int *day, char *string, 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: User's Reference Guide 39 CHAPTER 8, THE SOFTC DATABASE LIBRARY 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() { int y, m, d; sccds2i(&y,&m,&d,"19890213",SC_YMD); printf("%d %d %d",y,m,d); } sccds2lx__________________________________ USAGE int sccds2lx( long *date, char *string, 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: 40 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY 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() { long l; sccds2lx(&l,"19890323",SC_YMD); printf("%ld",l); } sccds2mon_________________________________ USAGE int sccds2mon( char *monthstr, char *date, 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: User's Reference Guide 41 CHAPTER 8, THE SOFTC DATABASE LIBRARY 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); } sccds2s___________________________________ USAGE int sccds2s( char *outstr, int outformat, char *instr, 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: 42 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY 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); } sccdsday__________________________________ USAGE int sccdsday( char *daystr, 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: User's Reference Guide 43 CHAPTER 8, THE SOFTC DATABASE LIBRARY 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); } sccdsdiff_________________________________ USAGE int sccdsdiff( long *diff, char *date1, int format1, char *date2, 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: 44 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY 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() { long d; sccdsdiff(&d, "19890213", SC_YMD, "19881217", SC_YMD); printf("%ld",d); } sccdsget__________________________________ USAGE int sccdsget( char *date, int format ); PROTOTYPE IN sc_clock.h DESCRIPTION sccdsget returns the current "date" in ASCIIZ string "format" from DOS. Date string styles: User's Reference Guide 45 CHAPTER 8, THE SOFTC DATABASE LIBRARY 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); } sccdsleap_________________________________ USAGE int sccdsleap( char *leap, 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: 46 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY SC_GREGOR mm/dd/yy SC_GREGORL mm/dd/yyyy SC_JULIAN yyyy/ddd SC_YMD yyyymmdd SC_DMY ddmmyy RETURN VALUE 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."); } sccdsmonth________________________________ USAGE int sccdsmonth( char *monthstr, 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: User's Reference Guide 47 CHAPTER 8, THE SOFTC DATABASE LIBRARY 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); } sccdsperm_________________________________ USAGE int sccdsperm( char *days, char *date, 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: 48 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY 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() { char d; sccdsperm(&d, "19890325", SC_YMD); printf("%d",d); } sccdsvalid________________________________ USAGE int sccdsvalid( char *string, 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: User's Reference Guide 49 CHAPTER 8, THE SOFTC DATABASE LIBRARY 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."); } sccti2s___________________________________ USAGE int sccti2s( char *string, int format, int hours, int minutes, 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: 50 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY 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() { char d[9]; sccti2s(d,SC_GREGOR,12,3,59); puts(d); } scctiget__________________________________ USAGE int scctiget( int *hours, int *minutes, int *seconds, int *fraction ); User's Reference Guide 51 CHAPTER 8, THE SOFTC DATABASE LIBRARY 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); } sccts2i___________________________________ USAGE int sccts2i( int *hours, int *minutes, int *seconds, char *string, 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> 52 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY void main() { int h, m, s; sccts2i(&h,&m,&s,"12:03:59",SC_CSHMS); printf("%d %d %d",h,m,s); } scctsdiff_________________________________ USAGE int scctsdiff( long *diff, char *time1, int format1, char *time2, 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: User's Reference Guide 53 CHAPTER 8, THE SOFTC DATABASE LIBRARY 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() { long d; scctsdiff(&d, "12:03:59", SC_CSHMS, "11:30:00", SC_CSHMS); printf("%ld",d); } scctsget__________________________________ USAGE int scctsget( char *time, int format ); PROTOTYPE IN sc_clock.h DESCRIPTION scctsget returns the current "time" from DOS in ASCIIZ string "format". Time string styles: 54 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY 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); } scctsvalid________________________________ USAGE int scctsvalid( char *string, 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: User's Reference Guide 55 CHAPTER 8, THE SOFTC DATABASE LIBRARY 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."); } scdcbfrsz_________________________________ USAGE int scdcbfrsz( int handle, int *numpgs, 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; char *index="TOCNAME.NTX"; scdinit(20,0); if (scdcopenx(&ntx,index,SC_BUFFER)==SC_SUCCESS) { scdcbfrsz(ntx,&numpgs,SC_GETSZ); printf("Maximum number of pages = %d\n", numpgs); scdcclose(ntx); 56 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY } scdterm(); } /* set size */ #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int ntx, numpgs=5; char *index="TOCNAME.NTX"; scdinit(20,0); if (scdcopenx(&ntx,index,SC_BUFFER)==SC_SUCCESS) { scdcbfrsz(ntx,&numpgs,SC_SETSZ); printf("New max = %d\n",numpgs); scdcclose(ntx); } scdterm(); } scdcclose_________________________________ USAGE int scdcclose( int handle ); User's Reference Guide 57 CHAPTER 8, THE SOFTC DATABASE LIBRARY 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; char *index="TOCNAME.NTX"; scdinit(20,0); if (scdcopenx(&ntx,index,SC_BUFFER)==SC_SUCCESS) scdcclose(ntx); scdterm(); } scdccreate________________________________ USAGE int scdccreate( char *filename, int keytype, char *keyexpr, int keylen, 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. 58 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY When unique keys are required, OR SC_UNIQUE with "keytype". NOTES scdccreate will create a new index file even if one had already existed. "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(); } scdcexpr__________________________________ USAGE int scdcexpr( int handle, 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],*index="TOCNAME.NTX"; User's Reference Guide 59 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdinit(20,0); if (scdcopenx(&ntx,index,SC_BUFFER)==SC_SUCCESS) { scdcexpr(ntx,buffer); printf("key expression = %s",buffer); scdcclose(ntx); } scdterm(); } scdcflush_________________________________ USAGE int scdcflush( 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,*data="TOC.DBF",*index="TOCNAME.NTX"; long record; scdinit(20,0); if (scddopenx(&dbf,data,SC_BUFFER)==SC_SUCCESS) { if (scdcopenx(&ntx,index,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); 60 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY } scdterm(); } scdcindex_________________________________ USAGE int scdcindex( int datafile, char *filename, int keytype, char *keyexpr, int keylen, int decpl ); User's Reference Guide 61 CHAPTER 8, THE SOFTC DATABASE LIBRARY 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; char *data="TOC.DBF",*index="TOCNAME.NTX"; scdinit(20,0); if (scddopenx(&dbf,data,SC_BUFFER)==SC_SUCCESS) { scdcindex(dbf,index,SC_CKEY,"NAME",64,0); scddclose(dbf); } scdterm(); } scdchget__________________________________ USAGEint scdchget( int handle ); PROTOTYPE IN sc_base.h DESCRIPTION scdchget will read the index file header. This function should be called after the data file has been locked in order to reload the current file header information. RETURN VALUES SC_SUCCESS header read successfully SC_RDFAIL file read failure SC_SKFAIL file pointer reposition failed SC_BADHNDL invalid handle number SEE ALSO scddlock. 62 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int dbf, ntx; scdinit(20,0); if (scddopenx(&dbf,"TOC.DBF",SC_SHARED) == SC_SUCCESS) { scdcopenx(&ntx,"TOCNAME.NTX",SC_SHARED); scddlock(dbf); scddhget(dbf); scdchget(ntx); /* append records - add keys - etc. */ scddunlock(dbf); scddclose(dbf); } scdterm(); } scdcinfo__________________________________ USAGE int scdcinfo( 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 { User's Reference Guide 63 CHAPTER 8, THE SOFTC DATABASE LIBRARY char fname[80]; /* file name */ char keylen; /* key length */ char keydpl; /* decimal places */ 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() { int ntx; SC_NTXINFO info; char *index="TOCNAME.NTX"; scdinit(20,0); if (scdcopenx(&ntx,index,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(); } 64 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY scdckadd__________________________________ USAGE int scdckadd( int handle, void *key, long recno ); User's Reference Guide 65 CHAPTER 8, THE SOFTC DATABASE LIBRARY 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",*index="TOCNAME.NTX"; long recno; scdinit(20,0); if (scddopenx(&dbf,"TOC.DBF",0)==SC_SUCCESS) { if (scdcopenx(&ntx,index,SC_BUFFER)==SC_SUCCESS) { scddfputs(dbf,0,name); if (scddrput(dbf,&recno,SC_ADD) == SC_SUCCESS) scdckadd(ntx,name,recno); scdcclose(ntx); } scddclose(dbf) } scdterm(); } scdckbot__________________________________ USAGE int scdckbot( int handle, void *key, long *recno ); 66 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY 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],*index="TOCNAME.NTX"; long recno; scdinit(20,0); if (scdcopenx(&ntx,index,SC_BUFFER)==SC_SUCCESS) { name[64] = 0; scdckbot(ntx,name,&recno); printf("%s %ld\n",name,recno); scdcclose(ntx); } scdterm(); } scdckcur__________________________________ USAGE int scdckcur( int handle, void *key, long *recno ); User's Reference Guide 67 CHAPTER 8, THE SOFTC DATABASE LIBRARY 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],*index="TOCDATE.NTX"; long recno, recn; scdinit(20,0); if (scdcopenx(&ntx,index,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(); } scdckdel__________________________________ USAGE int scdckdel( int handle, void *key, long recno ); 68 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY 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],*index="TOCDATE.NTX"; scdinit(20,0); if (scdcopenx(&ntx,index,SC_BUFFER)==SC_SUCCESS) { strcpy(date,"12/05/8815:30:04"); scdckdel(ntx,date,7L); scdcclose(ntx); } scdterm(); } scdckfind_________________________________ USAGE int scdckfind( int handle, void *key, long *recno, int method ); User's Reference Guide 69 CHAPTER 8, THE SOFTC DATABASE LIBRARY 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. 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],*index="TOCNAME.NTX"; long recno; scdinit(20,0); if (scdcopenx(&ntx,index,SC_BUFFER)==SC_SUCCESS) { 70 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY 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(); } scdckmake_________________________________ USAGE int scdckmake( int datahandle, 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) User's Reference Guide 71 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. 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> 72 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY void main() { int ntx, dbf; char *key,*index="TOCNAME.NTX"; long recno; scdinit(20,0); if (scddopenx(&dbf,"TOC.DBF",0)==SC_SUCCESS) { if (scdcopenx(&ntx,index,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(); } scdcknext_________________________________ USAGE int scdcknext( int handle, void *key, 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. User's Reference Guide 73 CHAPTER 8, THE SOFTC DATABASE LIBRARY SEE ALSO scdcinfo. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int ntx; char key[11],*index="TOCLNGTH.NTX"; long recno; scdinit(20,0); if (scdcopenx(&ntx,index,SC_BUFFER)==SC_SUCCESS) { scdcknext(ntx,key,&recno); /* return first key */ printf("%s %ld\n",key,recno); scdcclose(ntx); } scdterm(); } scdckprev_________________________________ USAGE int scdckprev( int handle, void *key, 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. 74 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY SEE ALSO scdcinfo. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int ntx; char character[65],*index="TOCNAME.NTX"; long recno; scdinit(20,0); if (scdcopenx(&ntx,index,SC_BUFFER)==SC_SUCCESS) { scdckprev(ntx,character,&recno); /* get last key */ printf("%s %ld\n",character,recno); scdcclose(ntx); } scdterm(); } scdcktop__________________________________ USAGE int scdcktop( int handle, void *key, 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> User's Reference Guide 75 CHAPTER 8, THE SOFTC DATABASE LIBRARY void main() { int ntx; char date[17],*index="TOCDATE.NTX"; long recno; scdinit(20,0); if (scdcopenx(&ntx,index,SC_BUFFER)==SC_SUCCESS) { date[16] = 0; scdcktop(ntx,date,&recno); printf("%s %ld\n",date,recno); scdcclose(ntx); } scdterm(); } scdcopenx_________________________________ USAGE int scdcopenx( int *handle, char *filename, 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- 76 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY 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 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; char *index="UNKNOWN.NTX"; scdinit(20,0); if (scdcopenx(&ntx,index,SC_BUFFER)==SC_SUCCESS) { scdcclose(ntx); } scdterm(); } scddbfrsz_________________________________ USAGE int scddbfrsz( int handle, int *length, 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. User's Reference Guide 77 CHAPTER 8, THE SOFTC DATABASE LIBRARY 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; char *data="TOC.DBF"; scdinit(20,0); if (scddopenx(&dbf,data,SC_BUFFER)==SC_SUCCESS) { scddbfrsz(dbf,&length,SC_GETSZ); printf("%d\n",length); scddclose(dbf); } scdterm(); } /* Get Size */ #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int dbf, length = 100; char *data="TOC.DBF"; scdinit(20,0); if (scddopenx(&dbf,data,SC_BUFFER)==SC_SUCCESS) { scddbfrsz(dbf,&length,SC_SETSZ); printf("%d\n",length); scddclose(dbf); } scdterm(); } scddbof___________________________________ USAGE int scddbof( int handle ); 78 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY 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 VALUE 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(); } scddclose_________________________________ USAGE int scddclose( int handle ); User's Reference Guide 79 CHAPTER 8, THE SOFTC DATABASE LIBRARY 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(); } scddcreate________________________________ USAGE int scddcreate( char *filename, int numfields, SC_FIELD *fields, 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 { 80 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY char name[11]; /* field name */ char type; /* field type */ int len; /* field length */ int 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) '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, SC_DB4 - dBASEIV compatible, or SC_FP1 - FoxPro compatible. User's Reference Guide 81 CHAPTER 8, THE SOFTC DATABASE LIBRARY 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> 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(); } scddeof___________________________________ USAGE int scddeof( int handle ); 82 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY 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 VALUE 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(); } scddfget__________________________________ USAGE int scddfget( int handle, 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 type returned data type User's Reference Guide 83 CHAPTER 8, THE SOFTC DATABASE LIBRARY 'C' char * 'D' char [9] 'F' double (dBASEIV) 'L' char 'M' 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). 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); 84 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY scddfget(dbf,3,time); scddfget(dbf,4,&attribute); printf("%s %lf %s %s %lf\n", name,length,date,time,attribute); scddclose(dbf); } scdterm(); } scddfgets_________________________________ USAGE int scddfgets( int handle, 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); 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); User's Reference Guide 85 CHAPTER 8, THE SOFTC DATABASE LIBRARY scddfgets(dbf,4,attribute); printf("%s %s %s %s %s\n", name,length,date,time,attribute); scddclose(dbf); } scdterm(); } scddfinfo_________________________________ USAGE int scddfinfo( int handle, 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 { 86 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY char name[11]; /* field name */ char type; /* field type */ int len; /* field length */ int 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> void main() { int dbf, longfld, numflds, a, reclen; SC_FIELD fields[128]; /* dBASEIII max size */ 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(); } User's Reference Guide 87 CHAPTER 8, THE SOFTC DATABASE LIBRARY scddflush_________________________________ USAGE int scddflush( 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; char *data="TOC.DBF"; scdinit(20,0); if (scddopenx(&dbf,data,SC_BUFFER)==SC_SUCCESS) { . . . scddrput(dbf,&record,SC_ADD); scddflush(dbf); . . . scddclose(dbf); } scdterm(); } scddfnam2no_______________________________ USAGE int scddfnam2no( int handle, int *fieldno, char *fieldname ); PROTOTYPE IN sc_base.h DESCRIPTION scddfnam2no searches through the field description array for data file "handle" looking 88 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY 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(); } scddfput__________________________________ USAGE int scddfput( int handle, 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 type returned data type User's Reference Guide 89 CHAPTER 8, THE SOFTC DATABASE LIBRARY 'C' char * 'D' char [9] 'F' double (dBASE IV) 'L' char 'M' 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. 90 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY SEE ALSO scddfget, scddfputs. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { 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(); } scddfputs_________________________________ USAGE int scddfputs( int handle, 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. User's Reference Guide 91 CHAPTER 8, THE SOFTC DATABASE LIBRARY 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"); 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(); } scddhget__________________________________ USAGEint scddhget( int handle ); PROTOTYPE IN sc_base.h DESCRIPTION scddhget will read the data file header. This function should be called after the data file has been locked in order to reload the current file header information. RETURN VALUES SC_SUCCESS header read successfully SC_RDFAIL file read failure SC_SKFAIL file pointer reposition failed SC_BADHNDL invalid handle number SEE ALSO scddlock. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { 92 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY int dbf; scdinit(20,0); if (scddopenx(&dbf,"TOC.DBF",SC_SHARED) == SC_SUCCESS) { scddlock(dbf); scddhget(dbf); /* append records - add keys - etc. */ scddunlock(dbf); scddclose(dbf); } scdterm(); } scddinfo__________________________________ USAGE int scddinfo( int handle, SC_DBFINFO *info ); PROTOTYPE IN sc_base.h DESCRIPTION scddinfo returns an information structure for the file associated with "handle". typedef struct { char fname[80]; /* file name */ char style; /* file type */ /* (dBASE 3 or 4) */ char memo; /* memo file used */ char mdx; /* MDX file used */ char trans; /* transaction */ /* in progress */ char encrypt; /* data encrypted */ 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; User's Reference Guide 93 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(); } scddlock__________________________________ USAGE int scddlock( 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. 94 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY SEE ALSO scddopenx, scddrlock,scddunlock. EXAMPLE #include <softc.h> #include <sc_base.h> void main() { int dbf; long record; double length=1305,attribute=1; char *data="TOC.DBF"; scdinit(20,0); if (scddopenx(&dbf,data,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); scddlock(dbf); scddrput(dbf,&record,SC_ADD); scddunlock(dbf); scddclose(dbf); } scdterm(); } scddlud___________________________________ USAGE int scddlud( int handle, char *datestr, 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: User's Reference Guide 95 CHAPTER 8, THE SOFTC DATABASE LIBRARY 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(); } scddopenx_________________________________ USAGE int scddopenx( int *handle, char *filename, 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 96 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY 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. 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; char *data="TOC.DBF"; scdinit(20,0); scddopenx(&dbf,data,SC_SHARED|SC_FLUSH|SC_RDWR); scdterm(); } scddpack__________________________________ USAGE int scddpack( int *handle ); PROTOTYPE IN sc_base.h DESCRIPTION scddpack will remove all data file records which have been flagged as deleted User's Reference Guide 97 CHAPTER 8, THE SOFTC DATABASE LIBRARY (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(); } scddrclear________________________________ USAGE int scddrclear( 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); } 98 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY scdterm(); } scddrdel__________________________________ USAGE int scddrdel( int handle, 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 deleted */ scddclose(dbf); } scdterm(); } scddrget__________________________________ USAGE int scddrget( int handle, long recno ); User's Reference Guide 99 CHAPTER 8, THE SOFTC DATABASE LIBRARY 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. RETURN VALUES SC_DELREC inactive record read SC_SUCCESS data record read successfully SC_RDFAIL file read failure SC_SKFAIL file pointer reposition failed SC_BADHNDL invalid handle number SEE ALSO scddfget, scddfput, scddrgetx, 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(); } scddrgetx_________________________________ USAGE int scddrgetx( int handle, char *buffer, long recno ); 100 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY PROTOTYPE IN sc_base.h DESCRIPTION scddrgetx will read the data record specified by "recno" from the data file associated with "handle" into the user specified buffer. RETURN VALUES SC_DELREC inactive record read SC_SUCCESS data record read successfully SC_RDFAIL file read failure SC_SKFAIL file pointer reposition failed SC_BADHNDL invalid handle number SEE ALSO scddfget, scddfput, scddrget, scddrputx. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int dbf; struct { char status; char name[65]; char length[10]; char date[9]; char time[9]; char attribute[2]; } buffer; scdinit(20,0); if (scddopenx(&dbf,"TOC.DBF",0) == SC_SUCCESS) { scddrgetx(dbf,buffer,1L); printf("%s\n",buffer); scddclose(dbf); } scdterm(); } scddrinfo_________________________________ USAGE int scddrinfo( int handle, SC_DBFRINFO *rinfo ); User's Reference Guide 101 CHAPTER 8, THE SOFTC DATABASE LIBRARY 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 { int reclen; /* record length */ int numflds; /* number of */ /* fields */ 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(); } scddrlock_________________________________ USAGE int scddrlock( int handle, long record ); 102 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY 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; char *data="TOC.DBF"; scdinit(20,0); if (scddopenx(&dbf,data,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); scdnkmake(dbf,ndx,&key); scdrlock(dbf,record); scddrput(dbf,&record,SC_UPDATE); scddunlock(dbf); free(key); scddclose(dbf); } scdterm(); } scddrnum__________________________________ USAGE int scddrnum( int handle, long *position ); User's Reference Guide 103 CHAPTER 8, THE SOFTC DATABASE LIBRARY 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(); } scddrput__________________________________ USAGE int scddrput( int handle, long *recno, 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 104 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY 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 to load a data record or scddfput or scddfputs to fill the data record field by field. SEE ALSO scddfput, scddfputs, scddrget, scddrputx. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { 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(); } scddrputx_________________________________ USAGE int scddrputx( int handle, char *buffer, long *recno, int howto ); PROTOTYPE IN sc_base.h DESCRIPTION scddrputx will write the data record specified by "recno" to the data file associated with "handle" from the user specified buffer. User's Reference Guide 105 CHAPTER 8, THE SOFTC DATABASE LIBRARY "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 scddrgetx to load a data record or scddfput or scddfputs to fill the data record field by field. 106 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY SEE ALSO scddfput, scddfputs, scddrgetx, scddrput. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int dbf; struct { char status; char name[65]; char length[10]; char date[9]; char time[9]; char attribute[2]; } buffer; scdinit(20,0); if (scddopenx(&dbf,"TOC.DBF",0) == SC_SUCCESS) { scddrgetx(dbf,buffer,1L); strncpy(buffer.name,"ABC.XYZ",65); scddrputx(dbf,buffer,&recno,SC_ADD); scddclose(dbf); } scdterm(); } scddrstat_________________________________ USAGE int scddrstat( 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 VALUE SC_DELREC record inactive SC_SUCCESS active record SEE ALSO scddrget EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> User's Reference Guide 107 CHAPTER 8, THE SOFTC DATABASE LIBRARY 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(); } scddrundel________________________________ USAGE int scddrundel( int handle, long recno ); 108 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY 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(); } scddsize__________________________________ USAGE int scddsize( int handle, 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); User's Reference Guide 109 CHAPTER 8, THE SOFTC DATABASE LIBRARY printf("%ld",recsused); scddclose(dbf); } scdterm(); } scddunlock________________________________ USAGE int scddunlock( 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,*data="TOC.DBF",*index="TOCNAME.NDX"; long record; double length = 2367, attribute = 1; scdinit(20,0); if (scddopenx(&dbf,data,SC_SHARED)==SC_SUCCESS) { if (scdnopenx(&ndx,index,SC_SHARED)==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); scdnkmake(dbf,ndx,&key); scddlock(dbf); scddrput(dbf,&record,SC_ADD); 110 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY scdnkadd(ndx,key,record); scddunlock(dbf); free(key); scdnclose(ndx); } scddclose(dbf); } scdterm(); } scdibfrsz_________________________________ USAGE int scdibfrsz( int handle, int *numpgs, 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; char *index="TOCNAME.IDX"; scdinit(20,0); if (scdiopenx(&idx,index,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> User's Reference Guide 111 CHAPTER 8, THE SOFTC DATABASE LIBRARY void main() { char idx,numpgs=5,*index="TOCNAME.IDX"; scdinit(20,0); if (scdiopenx(&idx,index,SC_BUFFER)==SC_SUCCESS) { scdibfrsz(idx,&numpgs,SC_SETSZ); printf("New max = %d\n",numpgs); scdiclose(idx); } scdterm(); } scdiclose_________________________________ USAGE int scdiclose( 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; char *index="TOCNAME.IDX"; scdinit(20,0); if (scdiopenx(&idx,index,SC_BUFFER)==SC_SUCCESS) scdiclose(idx); scdterm(); } scdicreate________________________________ USAGE int scdicreate( char *filename, int keytype, char *keyexpr, int keylen ); 112 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY 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. "keyexpr" is NOT checked for validity during the file creation process. Currently only the scdikmake function uses "keyexpr". User's Reference Guide 113 CHAPTER 8, THE SOFTC DATABASE LIBRARY SEE ALSO scdikmake. EXAMPLE #include <sc_base.h> void main() { scdinit(20,0); scdicreate("TOCDATE.IDX",SC_CKEY,"dtoc(date) + time",16); scdterm(); } scdiexpr__________________________________ USAGE int scdiexpr( int handle, 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],*index="TOCNAME.IDX"; scdinit(20,0); if (scdiopenx(&idx,index,SC_BUFFER)==SC_SUCCESS) { scdiexpr(idx,buffer); printf("key expression = %s",buffer); scdiclose(idx); } 114 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY scdterm(); } scdiflush_________________________________ USAGE int scdiflush( int handle ); User's Reference Guide 115 CHAPTER 8, THE SOFTC DATABASE LIBRARY 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],*index="TOCNAME.IDX",*data="TOC.DBF" ; long record; scdinit(20,0); if (scddopenx(&dbf,data,SC_BUFFER)==SC_SUCCESS) { if (scdiopenx(&idx,index,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); } scdterm(); } scdihget__________________________________ USAGEint scdihget( int handle ); PROTOTYPE IN sc_base.h DESCRIPTION scdihget will read the index file header. This function should be called after the 116 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY data file has been locked in order to reload the current file header information. RETURN VALUES SC_SUCCESS header read successfully SC_RDFAIL file read failure SC_SKFAIL file pointer reposition failed SC_BADHNDL invalid handle number SEE ALSO scddlock. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int dbf, idx; scdinit(20,0); if (scddopenx(&dbf,"TOC.DBF",SC_SHARED) == SC_SUCCESS) { scdiopenx(&idx,"TOCNAME.IDX",SC_SHARED); scddlock(dbf); scddhget(dbf); scdihget(ntx); /* append records - add keys - etc. */ scddunlock(dbf); scddclose(dbf); } scdterm(); } scdiindex_________________________________ USAGE int scdiindex( int datafile, char filename, char keytype, char keyexpr, int keylen ); PROTOTYPE IN sc_base.h DESCRIPTION scdiindex will create and build a FoxBase/FoxPro 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 User's Reference Guide 117 CHAPTER 8, THE SOFTC DATABASE LIBRARY 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; char *index="TOCNAME.IDX",*data="TOC.DBF"; scdinit(20,0); if (scddopenx(&dbf,data,SC_BUFFER)==SC_SUCCESS) { scdiindex(dbf,index,SC_CKEY,"NAME",64); scddclose(dbf); } scdterm(); } scdiinfo__________________________________ USAGE int scdiinfo( 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 { char fname[80]; /* file name */ char keytype; /* key type (C,D,L,N) */ char keylen; /* key length */ char exprlen; /* expression length */ SC_FLAGS flags; /* misc. flags */ } SC_IDXINFO; 118 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY 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() { int idx; SC_IDXINFO info; char *index="TOCNAME.IDX"; scdinit(20,0); if (scdiopenx(&idx,index,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(); } scdikadd__________________________________ USAGE int scdikadd( int handle, void *key, 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. User's Reference Guide 119 CHAPTER 8, THE SOFTC DATABASE LIBRARY 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; char key[8],*index="TOCLNGTH.IDX"; double length = 123.67L scdinit(20,0); if (scddopenx(&dbf, "TOC.DBF",0) == SC_SUCCESS) { if (scdiopenx(&idx,index,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(); } scdikbot__________________________________ USAGE int scdikbot( int handle, void *key, 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 120 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY 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],*index="TOCNAME.IDX"; long recno; scdinit(20,0); if (scdiopenx(&idx,index,SC_BUFFER)==SC_SUCCESS) { name[64] = 0; scdikbot(idx,name,&recno); printf("%s %ld\n",name,recno); scdiclose(idx); } scdterm(); } scdikcur__________________________________ USAGE int scdikcur( int handle, void *key, 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 User's Reference Guide 121 CHAPTER 8, THE SOFTC DATABASE LIBRARY 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],*index="TOCDATE.IDX"; long recno, recn; scdinit(20,0); if (scdiopenx(&idx,index,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(); } scdikdate_________________________________ USAGE int scdikdate( char *key, char *string, int format ); PROTOTYPE IN sc_base.h DESCRIPTION scdikdate will translate an ASCIIZ date string "string" of style "format" into a valid FoxBase/FoxPro date key "key". Date string styles: 122 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY 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; char key[8],*index="TOCFDATE.IDX"; scdinit(20,0); if (scddopenx(&dbf,"TOC.DBF",0)==SC_SUCCESS) { if (scdiopenx(&idx,index,SC_BUFFER)==SC_SUCCESS) { scddfput(dbf,2,"07/21/90); . . . if (scddrput(dbf,&recno,SC_ADD) == SC_SUCCESS) { scdikdate(key, "07/21/90", SC_GREGOR); scdikadd(idx,key,recno); } scdiclose(idx); } scddclose(dbf) } scdterm(); } scdikdel__________________________________ USAGE int scdikdel( char handle, User's Reference Guide 123 CHAPTER 8, THE SOFTC DATABASE LIBRARY void *key, 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],*index="TOCNAME.IDX"; scdinit(20,0); if (scdiopenx(&idx,index,SC_BUFFER)==SC_SUCCESS) { strcpy(name,"ABC.DEF"); scdikdel(idx,name,3L); scdiclose(idx); } scdterm(); } scdikfind_________________________________ USAGE int scdikfind( int handle, void *key, long *recno, 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 124 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY "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. User's Reference Guide 125 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],*index="TOCNAME.IDX"; long recno; scdinit(20,0); if (scdiopenx(&idx,index,SC_BUFFER)==SC_SUCCESS) { strcpy(name,"ABCDE"); recno = 7L; if (scdikfind(idx, name, &recno, SC_FIRST) != SC_SUCCESS) puts(scemsg()); scdiclose(idx); } scdterm(); } scdikmake_________________________________ USAGE int scdikmake( int datahandle, 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/FoxPro functions or a combination thereof. Data field types of date, numeric, character or logical are allowed. FoxBase/FoxPro functions: dtoc, left, right, str, and substr are currently supported by scdikmake. 126 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY 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) 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 User's Reference Guide 127 CHAPTER 8, THE SOFTC DATABASE LIBRARY 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 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],*index="TOCNAME.IDX"; long recno; scdinit(20,0); if (scddopenx(&dbf,"TOC.DBF",0)==SC_SUCCESS) { if (scdiopenx(&idx,index,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(); } scdiknext_________________________________ USAGE int scdiknext( int handle, void *key, long *recno ); PROTOTYPE IN sc_base.h DESCRIPTION scdiknext will increment the key pointer and return the key value "key" and data 128 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY 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() { int idx; char name[65],*index="TOCNAME.IDX"; long recno; scdinit(20,0); if (scdiopenx(&idx,index,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; char *index="TOCLNGTH.IDX"; User's Reference Guide 129 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdinit(20,0); if (scdiopenx(&idx,index,SC_BUFFER)==SC_SUCCESS) { scdiknext(idx,&numeric,&recno); /* return first key */ printf("%lf %ld\n",numeric,recno); scdiclose(idx); } scdterm(); } scdiknum__________________________________ USAGE int scdiknum( char *key, double value ); PROTOTYPE IN sc_base.h DESCRIPTION scdiknum will translate a 'C' double "value" to a FoxBase/FoxPro numeric "key". SEE ALSO scdicreate, scdikdate, scdikmake. EXAMPLE #include <softc.h> #include <sc_base.h> void main() { int dbf, idx; long recno; char key[8],*index="TOCLNGTH.IDX"; double length = 123.67L scdinit(20,0); if (scddopenx(&dbf,"TOC.DBF",0)==SC_SUCCESS) { if (scdiopenx(&idx,index,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) } 130 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY scdterm(); } scdikprev_________________________________ USAGE int scdikprev( int handle, void *key, 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() { int idx; char name[65]; long recno; char *index="TOCNAME.IDX"; scdinit(20,0); if (scdiopenx(&idx,index,SC_BUFFER)==SC_SUCCESS) { scdikprev(idx, name, &recno); /* get last key */ printf("%s %ld\n",name,recno); scdiclose(idx); User's Reference Guide 131 CHAPTER 8, THE SOFTC DATABASE LIBRARY } scdterm(); } /* Numeric Key Example */ #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int idx; double length; long recno; char *index="TOCLNGTH.IDX"; scdinit(20,0); if (scdiopenx(&idx,index,SC_BUFFER)==SC_SUCCESS) { scdikprev(idx,&length,&recno); /* get last key */ printf("%lf %ld\n",length,recno); scdiclose(idx); } scdterm(); } scdiktop__________________________________ USAGE int scdiktop( int handle, void *key, 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. 132 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY SEE ALSO scdiinfo. EXAMPLE /* Character Key Example */ #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int idx; char name[65],*index="TOCNAME.IDX"; long recno; scdinit(20,0); if (scdiopenx(&idx,index,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; char *index="TOCLNGTH.IDX"; scdinit(20,0); if (scdiopenx(&idx,index,SC_BUFFER)==SC_SUCCESS) { scdiktop(idx,&length,&recno); printf("%lf %ld\n",length,recno); scdiclose(idx); } scdterm(); } User's Reference Guide 133 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdinit___________________________________ USAGE int scdinit( int files, 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_USEXHNDL 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. This implies that files cannot be less than five. 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. EXAMPLE #include <sc_base.h> void main() { scdinit(20,0); scdterm(); } scdiopenx_________________________________ USAGE int scdiopenx( int *handle, char *filename, int command ); 134 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY PROTOTYPE IN sc_base.h DESCRIPTION scdiopenx opens a FoxBase/FoxPro 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/FoxPro 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. 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; char *index="UNKNOWN.IDX"; scdinit(20,0); User's Reference Guide 135 CHAPTER 8, THE SOFTC DATABASE LIBRARY if (scdiopenx(&idx,index,SC_BUFFER)==SC_SUCCESS) { scdiclose(idx); } scdterm(); } scdnbfrsz_________________________________ USAGE int scdnbfrsz( int handle, int *numpgs, 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; char *index="TOCNAME.NDX"; scdinit(20,0); if (scdnopenx(&ndx,index,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() 136 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY { int ndx, numpgs = 5; char *index="TOCNAME.NDX"; scdinit(20,0); if (scdnopenx(&ndx,index,SC_BUFFER)==SC_SUCCESS) { scdnbfrsz(ndx,&numpgs,SC_SETSZ); printf("New max = %d\n",numpgs); scdnclose(ndx); } scdterm(); } scdnclose_________________________________ USAGE int scdnclose( 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; char *index="TOCNAME.NDX"; scdinit(20,0); if (scdnopenx(&ndx,index,SC_BUFFER)==SC_SUCCESS) scdnclose(ndx); scdterm(); } scdncreate________________________________ USAGE int scdncreate( char *filename, char keytype, char *keyexpr, int keylen ); User's Reference Guide 137 CHAPTER 8, THE SOFTC DATABASE LIBRARY 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". SEE ALSO scdnkmake. EXAMPLE #include <sc_base.h> void main() { scdinit(20,0); scdncreate("TOCDATE.NDX",'c',"dtoc(date) + time",16); scdterm(); } scdnexpr__________________________________ USAGE int scdnexpr( int handle, char *keyexpr ); 138 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY 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],*index="TOCNAME.NDX"; scdinit(20,0); if (scdnopenx(&ndx,index,SC_BUFFER)==SC_SUCCESS) { scdnexpr(ndx,buffer); printf("key expression = %s",buffer); scdnclose(ndx); } scdterm(); } scdnflush_________________________________ USAGE int scdnflush( int handle ); User's Reference Guide 139 CHAPTER 8, THE SOFTC DATABASE LIBRARY 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,*index="TOCNAME.NDX",*data="TOC.DBF"; long record; scdinit(20,0); if (scddopenx(&dbf,data,SC_BUFFER)==SC_SUCCESS) { if (scdnopenx(&ndx,index,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); } scdterm(); } scdnhget__________________________________ USAGEint scdnhget( int handle ); PROTOTYPE IN sc_base.h DESCRIPTION scdnhget will read the index file header. This function should be called after the data file has been locked in order to reload the current file header information. 140 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY RETURN VALUES SC_SUCCESS header read successfully SC_RDFAIL file read failure SC_SKFAIL file pointer reposition failed SC_BADHNDL invalid handle number SEE ALSO scddlock. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int dbf, ndx; scdinit(20,0); if (scddopenx(&dbf,"TOC.DBF",SC_SHARED) == SC_SUCCESS) { scdnopenx(&ndx,"TOCNAME.NDX",SC_SHARED); scddlock(dbf); scddhget(dbf); scdnhget(ntx); /* append records - add keys - etc. */ scddunlock(dbf); scddclose(dbf); } scdterm(); } scdnindex_________________________________ USAGE int scdnindex( int datafile, char filename, char keytype, char keyexpr, char keylen ); User's Reference Guide 141 CHAPTER 8, THE SOFTC DATABASE LIBRARY 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; char *data="TOC.DBF"; scdinit(20,0); if (scddopenx(&dbf,data,SC_BUFFER)==SC_SUCCESS) { scdnindex(dbf, "TOCNAME.NDX", SC_CKEY, "NAME", 64); scddclose(dbf); } scdterm(); } scdninfo__________________________________ USAGE int scdninfo( 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 { char fname[80]; /* file name */ char keytype; /* key type (C or N) */ char keylen; /* key length */ char exprlen; /* expression length */ SC_FLAGS flags; /* misc. flags */ } SC_NDXINFO; 142 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY 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() { int ndx; SC_NDXINFO info; char *index="TOCNAME.NDX"; scdinit(20,0); if (scdnopenx(&ndx,index,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(); } scdnkadd__________________________________ USAGE int scdnkadd( int handle, void *key, long recno ); User's Reference Guide 143 CHAPTER 8, THE SOFTC DATABASE LIBRARY 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],*index="TOCNAME.NDX"; long recno; scdinit(20,0); if (scddopenx(&dbf,"TOC.DBF",0)==SC_SUCCESS) { if (scdnopenx(&ndx,index,SC_BUFFER)==SC_SUCCESS) { strcpy(name,"XYZ.BAK"); scddfput(dbf,0,name); if (scddrput(dbf, &recno, SC_ADD) == SC_SUCCESS) scdnkadd(ndx,name,recno); scdnclose(ndx); } scddclose(dbf) } scdterm(); } scdnkbot__________________________________ USAGE int scdnkbot( int handle, void *key, long *recno ); 144 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY 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],*index="TOCNAME.NDX"; long recno; scdinit(20,0); if (scdnopenx(&ndx,index,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; char *index="TOCLNGTH.NDX"; User's Reference Guide 145 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdinit(20,0); if (scdnopenx(&ndx,index,SC_BUFFER)==SC_SUCCESS) { scdnkbot(ndx,&length,&recno); printf("%lf %ld\n",length,recno); scdnclose(ndx); } scdterm(); } scdnkcur__________________________________ USAGE int scdnkcur( int handle, void *key, 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],*index="TOCNAME.NDX"; long recno, recn; scdinit(20,0); if (scdnopenx(&ndx,index,SC_BUFFER)==SC_SUCCESS) { name[64] = 0; 146 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY nam[64] = 0; scdnktop(ndx,name,&recno); scdnkcur(ndx,nam,&recn); printf("%s %s %ld %ld\n",name,nam,recno,recn); scdnclose(ndx); } scdterm(); } scdnkdate_________________________________ USAGE int scdnkdate( double *key, char *string, 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"); User's Reference Guide 147 CHAPTER 8, THE SOFTC DATABASE LIBRARY printf("%lf",key); scdterm(); } scdnkdel__________________________________ USAGE int scdnkdel( int handle, void *key, long recno ); 148 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY 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],*index="TOCDATE.NDX"; long recno; scdinit(20,0); if (scdnopenx(&ndx,index,SC_BUFFER)==SC_SUCCESS) { strcpy(date,"12/02/8809:33:01"); recno = 71L; scdnkdel(ndx,date,recno); scdnclose(ndx); } scdterm(); } scdnkfind_________________________________ USAGE int scdnkfind( int handle, void *key, long *recno, int method ); User's Reference Guide 149 CHAPTER 8, THE SOFTC DATABASE LIBRARY 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 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],*index="TOCNAME.NDX"; long recno; scdinit(20,0); 150 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY if (scdnopenx(&ndx,index,SC_BUFFER)==SC_SUCCESS) { strcpy(key,"ABCDE"); recno = 7L; if (scdnkfind(ndx,key,&recno,SC_FIRST) != SC_SUCCESS puts(scemsg()); scddclose(ndx); } scdterm(); } scdnkmake_________________________________ USAGE int scdnkmake( int datahandle, 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) User's Reference Guide 151 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 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> 152 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY void main() { int ndx, dbf; char *key,*file="TOCNAME.NDX"; long recno; scdinit(20,0); if (scddopenx(&dbf,"TOC.DBF",0) == SC_SUCCESS) { if (scdnopenx(&ndx,file,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(); } scdnknext_________________________________ USAGE int scdnknext( int handle, void *key, 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. User's Reference Guide 153 CHAPTER 8, THE SOFTC DATABASE LIBRARY SEE ALSO scdninfo. EXAMPLE /* Character Key Example */ #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int ndx; char name[65],*index="TOCNAME.NDX"; long recno; scdinit(20,0); if (scdnopenx(&ndx,index,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; char *index="TOCLNGTH.NDX"; scdinit(20,0); if (scdnopenx(&ndx,index,SC_BUFFER)==SC_SUCCESS) { scdnknext(ndx,&length,&recno); /* return first key */ printf("%lf %ld\n",length,recno); scdnclose(ndx); } scdterm(); } 154 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY scdnkprev_________________________________ USAGE int scdnkprev( int handle, void *key, 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. User's Reference Guide 155 CHAPTER 8, THE SOFTC DATABASE LIBRARY SEE ALSO scdninfo. EXAMPLE /* Character Key Example */ #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int ndx; char name[65],*file="TOCNAME.NDX"; long recno; scdinit(20,0); if (scdnopenx(&ndx,file,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; char *file="TOCLNGTH.NDX"; scdinit(20,0); if (scdnopenx(&ndx,file,SC_BUFFER)==SC_SUCCESS) { scdnkprev(ndx,&length,&recno); /* get last key */ printf("%lf %ld\n",length,recno); scdnclose(ndx); } scdterm(); } 156 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY scdnktop__________________________________ USAGE int scdnktop( int handle, void *key, 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], *file="TOCNAME.NDX"; long recno; scdinit(20,0); if (scdnopenx(&ndx,file,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> User's Reference Guide 157 CHAPTER 8, THE SOFTC DATABASE LIBRARY void main() { int ndx; double length; long recno; char *file="TOCLNGTH.NDX"; scdinit(20,0); if (scdnopenx(&ndx,file,SC_BUFFER)==SC_SUCCESS) { scdnktop(ndx,&length,&recno); printf("%lf %ld\n",length,recno); scdnclose(ndx); } scdterm(); } scdnopenx_________________________________ USAGE int scdnopenx( int *handle, char *filename, 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 158 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY 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 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; char *index="UNKNOWN.NDX"; scdinit(20,0); if (scdnopenx(&ndx,index,SC_BUFFER)==SC_SUCCESS) scdnclose(ndx); scdterm(); } scdtclose_________________________________ USAGE int scdtclose( 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; User's Reference Guide 159 CHAPTER 8, THE SOFTC DATABASE LIBRARY scdinit(20,0); if (scdtopenx(&dbt,"TOC.DBT",SC_SHARED)==SC_SUCCESS) scdtclose(dbt); scdterm(); } scdtcreate________________________________ USAGE int scdtcreate( 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(); } scdterm___________________________________ USAGE int scdterm( void ); 160 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY 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 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..."); } scdthget__________________________________ USAGEint scdthget( int handle ); PROTOTYPE IN sc_base.h DESCRIPTION scdthget will read the memo file header. This function should be called after the data file has been locked in order to reload the current file header information. RETURN VALUES SC_SUCCESS header read successfully SC_RDFAIL file read failure SC_SKFAIL file pointer reposition failed SC_BADHNDL invalid handle number User's Reference Guide 161 CHAPTER 8, THE SOFTC DATABASE LIBRARY SEE ALSO scddlock. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int dbf, dbt; scdinit(20,0); if (scddopenx(&dbf,"TOC.DBF",SC_SHARED) == SC_SUCCESS) { scdtopenx(&dbt,"TOC.DBT",SC_SHARED); scddlock(dbf); scddhget(dbf); scdthget(dbt); /* append records - add keys - etc. */ scddunlock(dbf); scddclose(dbf); } scdterm(); } scdtinfo__________________________________ USAGE int scdtinfo( 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 { 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; 162 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY char *memo="TOC.DBT"; scdinit(20,0); if (scdtopenx(&dbt,memo,SC_SHARED)==SC_SUCCESS) { scdtinfo(dbt,&info); puts(info.fname); scdtclose(dbt); } scdterm(); } scdtopenx_________________________________ USAGE int scdtopenx( int *handle, char *filename, 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. EXAMPLE #include <softc.h> #include <sc_base.h> User's Reference Guide 163 CHAPTER 8, THE SOFTC DATABASE LIBRARY void main() { int dbt; char *memo="TOC.DBT"; scdinit(20,0); if (scdtopenx(&dbt,memo,SC_SHARED)==SC_SUCCESS) scdtclose(dbt); scdterm(); } scdtpack__________________________________ USAGE int scdtpack( int datafile, int *memofile ); 164 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY 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; char *data="TOC.DBF",*memo="TOC.DBT"; scdinit(20,0); if (scddopenx(&dbf,data,SC_SHARED)==SC_SUCCESS) { if (scdtopenx(&dbt,memo,SC_SHARED)==SC_SUCCESS) { scdtpack(dbf, &dbt); scdtclose(dbt); } scddclose(dbf); } scdterm(); } scdtrget__________________________________ USAGE int scdtrget( int handle, long recno, char **data, 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 User's Reference Guide 165 CHAPTER 8, THE SOFTC DATABASE LIBRARY 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,*memo="TOC.DBT"; scdinit(20,0); if (scdtopenx(&dbt,memo,SC_SHARED)==SC_SUCCESS) { scdtrget(dbt,1L,&data,SC_CRDELETE); puts(data); free(data); scddclose(dbt); } scdterm(); } scdtrput__________________________________ USAGE int scdtrput( int handle, long *recno, char *data, 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. 166 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY 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() { int dbt; char data[512],*memo="TOC.DBT"; long recno; scdinit(20,0); if (scdtopenx(&dbt,memo,SC_BUFFER)==SC_SUCCESS) { strcpy(data,"hello world."); scdtrput(dbt,&recno,data,66); printf("%ld",recno); scddclose(dbt); } scdterm(); } scdwclose_________________________________ USAGE int scdwclose( int handle ); PROTOTYPE IN sc_base.h DESCRIPTION scdwclose closes a memo file and frees all allocated memory associated with memo file "handle". RETURN VALUES SC_SUCCESS file closed successfully SC_CLOSFAIL file close failure SC_BADHNDL invalid handle number SEE ALSO scdwopenx. EXAMPLE #include <sc_base.h> void main() { int dbt; scdinit(20,0); User's Reference Guide 167 CHAPTER 8, THE SOFTC DATABASE LIBRARY if (scdwopenx(&dbt,"TOC.FPT",SC_SHARED)==SC_SUCCESS) scdwclose(dbt); scdterm(); } scdwcreate________________________________ USAGE int scdwcreate( char *filename, int blocksize ); PROTOTYPE IN sc_base.h DESCRIPTION scdwcreate creates a FoxPro memo file. The memo text record length is determined by blocksize. The legitimate values for blocksize are from 1 to 511. Values of 1 through 32 are multiplied by 512 (1 = 512, 2 = 1024, etc.) while the others are used as-is. This function will create a new memo file even if one had already existed. RETURN VALUES SC_SUCCESS file successfully created SC_WRTFAIL file write failure SC_NOHNDL no handles available SC_BADFNAME invalid filename SC_NULLPARM parameter address NULL EXAMPLE #include <sc_base.h> void main() { scdinit(20,0); scdwcreate("TOC.FPT",64); scdterm(); } scdwhget__________________________________ USAGEint scdwhget( int handle ); PROTOTYPE IN sc_base.h DESCRIPTION scdwhget will read the memo file header. This function should be called after the 168 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY data file has been locked in order to reload the current file header information. RETURN VALUES SC_SUCCESS header read successfully SC_RDFAIL file read failure SC_SKFAIL file pointer reposition failed SC_BADHNDL invalid handle number SEE ALSO scddlock. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int dbf, fpt; scdinit(20,0); if (scddopenx(&dbf,"TOC.DBF",SC_SHARED) == SC_SUCCESS) { scdwopenx(&fpt,"TOC.FPT",SC_SHARED); scddlock(dbf); scddhget(dbf); scdwhget(fpt); /* append records - add keys - etc. */ scddunlock(dbf); scddclose(dbf); } scdterm(); } scdwinfo__________________________________ USAGE int scdwinfo( int handle, SC_FPTINFO *info ); PROTOTYPE IN sc_base.h DESCRIPTION scdwinfo gets the name of the memo file associated with "handle" and returns it in a structure: typdef struct { char fname[80]; /* file name */ SC_FLAGS flags; /* misc. flags */ } SC_FPTINFO; User's Reference Guide 169 CHAPTER 8, THE SOFTC DATABASE LIBRARY RETURN VALUES SC_SUCCESS file information retrieved SC_BADHNDL invalid handle number SC_NULLPARM parameter address NULL SEE ALSO scdwopenx. EXAMPLE #include <softc.h> #include <sc_base.h> void main() { int fpt; SC_FPTINFO info; char *memo="TOC.FPT"; scdinit(20,0); if (scdwopenx(&fpt,memo,SC_SHARED)==SC_SUCCESS) { scdwinfo(fpt,&info); puts(info.fname); scdwclose(fpt); } scdterm(); } scdwopenx_________________________________ USAGE int scdwopenx( int *handle, char *filename, int command ); PROTOTYPE IN sc_base.h DESCRIPTION scdwopenx 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 FoxPro 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). 170 SoftC Database Library 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. SC_BUFFER is not used. "command" = 0 is equivalent to SC_EXCLUDE | SC_RDWR. RETURN VALUES SC_SUCCESS file opened successfully SC_RDFAIL file read failure SC_MEMERR memory allocation error SC_NOFILE file not found SC_NOHNDL no handles available SC_BADFNAME invalid file name SC_NODBT file not in memo format SC_NULLPARM parameter address NULL EXAMPLE #include <softc.h> #include <sc_base.h> void main() { int fpt; char *memo="TOC.FPT"; scdinit(20,0); if (scdwopenx(&fpt,memo,SC_SHARED)==SC_SUCCESS) scdwclose(fpt); scdterm(); } scdwpack__________________________________ USAGE int scdwpack( int datafile, int *memofile ); User's Reference Guide 171 CHAPTER 8, THE SOFTC DATABASE LIBRARY PROTOTYPE IN sc_base.h DESCRIPTION scdwpack 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. RETURN VALUES SC_SUCCESS memo file packed successfully SC_MEMERR memory allocation error SC_NOFILE file not found SC_NOHNDL no handles available SC_NULLPARM parameter address NULL SEE ALSO scddpack, scdwopenx EXAMPLE #include <softc.h> #include <sc_base.h> void main() { int dbf, fpt; char *data="TOC.DBF",*memo="TOC.FPT"; scdinit(20,0); if (scddopenx(&dbf,data,SC_SHARED)==SC_SUCCESS) { if (scdwopenx(&fpt,memo,SC_SHARED)==SC_SUCCESS) { scdwpack(dbf, &fpt); scdwclose(fpt); } scddclose(dbf); } scdterm(); } scdwrget__________________________________ USAGE int scdwrget( int handle, long recno, char **data ); PROTOTYPE IN sc_base.h DESCRIPTION scdwrget reads the desired record "recno" from the memo file specified by "handle". 172 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY A buffer large enough to hold the text will be allocated, the address of which is returned in "data". RETURN VALUES SC_SUCCESS memo record read successfully SC_RDFAIL file read failure SC_MEMERR memory allocation error SC_SKFAIL file pointer reposition failed SC_BADHNDL invalid handle number SC_NULLPARM parameter address NULL SEE ALSO scdwrget. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int fpt; char *data,*memo="TOC.FPT"; scdinit(20,0); if (scdwopenx(&fpt,memo,SC_SHARED)==SC_SUCCESS) { scdwrget(fpt,1L,&data,SC_CRDELETE); puts(data); free(data); scddclose(fpt); } scdterm(); } scdwrput__________________________________ USAGE int scdwrput( int handle, long *recno, char *data, int command ); PROTOTYPE IN sc_base.h DESCRIPTION scdwrput 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 User's Reference Guide 173 CHAPTER 8, THE SOFTC DATABASE LIBRARY "data" is an ASCIIZ string with a maximum length of 65,536 characters. Unlike dBASE III memo files which appends all writes at end of the file, FoxPro allows updating an existing memo in place. command determines how the memo text is written: SC_ADD append to end of file SC_UPDATE update current record RETURN VALUES SC_SUCCESS record written successfully SC_WRTFAIL file write failure SC_SKFAIL file pointer reposition failed SC_BADHNDL invalid handle number SC_NULLPARM parameter address NULL SEE ALSO scdwrput. EXAMPLE #include <stdio.h> #include <softc.h> #include <sc_base.h> void main() { int fpt; char data[512],*memo="TOC.FPT"; long recno; scdinit(20,0); if (scdwopenx(&fpt,memo,SC_BUFFER)==SC_SUCCESS) { strcpy(data,"hello world."); scdwrput(fpt,&recno,data,SC_ADD); printf("%ld",recno); scddclose(fpt); } scdterm(); } sceclr____________________________________ USAGE void sceclr( void ); 174 SoftC Database Library CHAPTER 8, THE SOFTC DATABASE LIBRARY 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],*memo="TOC.DBT"; long recno; scdinit(20,0); if (scdtopenx(&dbt,memo,SC_BUFFER)<SC_SUCCESS) { sceclr(); scdtcreate("TOC.DBT"); scdtopenx(&dbt,memo,SC_BUFFER); } . . . scddclose(dbt); scdterm(); } scemsg____________________________________ USAGE 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() User's Reference Guide 175 CHAPTER 8, THE SOFTC DATABASE LIBRARY { int dbf; scdinit(20,0); if (scddopenx(&dbf,"TOC.DBF",0)!=SC_SUCCESS) puts(scemsg()); scdterm(); } 176 SoftC Database Library 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 User's Reference Guide 177 APPENDIX A, RESULT CODES AND MESSAGES desired to be written is more precise than space in the 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. SC_NOFUNC 10 "WARNING - function not supported" ANSI C does not define functions to perform file/record locks, and changing the length of a file. These functions are no-op'd. 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. 178 SoftC Database Library APPENDIX A, RESULT CODES AND MESSAGES 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 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. User's Reference Guide 179 APPENDIX A, RESULT CODES AND MESSAGES 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. 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. 180 SoftC Database Library APPENDIX A, RESULT CODES AND MESSAGES SC_BADTIME -16 "ERROR - invalid time" The hour, minute, and/or second was invalid. Verify the time is correct. 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. User's Reference Guide 181 APPENDIX A, RESULT CODES AND MESSAGES 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. 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. 182 SoftC Database Library APPENDIX A, RESULT CODES AND MESSAGES 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. 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. User's Reference Guide 183 APPENDIX A, RESULT CODES AND MESSAGES 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. 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 184 SoftC Database Library APPENDIX A, RESULT CODES AND MESSAGES sure that all of your files are closed before calling scdterm. SC_OPENFAIL -46 "ERROR - could not open the file" Error code added for ANSI C support. The error codes available under ANSI C fopen do not fully define the reason for the failure. This is a catch-all error code. SC_FLSHFAIL -47 "ERROR - flush to disk failure" Error code added for ANSI C support. The error codes available under ANSI C fflush do not fully define the reason for the failure. This is a catch-all error code. SC_BADTAG -48 "ERROR - invalid tag handle" Error code added for dBASE IV multiple index file support. Index tag name supplied was not in file. SC_BLKSZ -49 "ERROR - invalid block size" Error code added for dBASE IV multiple index and memo file support. The block size supplied to the create function was invalid. SC_BADTNAME -50 "ERROR - invalid tag name" Error code added for dBASE IV multiple index file support. The index tag name was improperly formatted (zero length, too long). SC_BLKADR -51 "ERROR - invalid block adder size" Error code added for dBASE IV multiple index and memo file support. The byte block adder was invalid. SC_MAXTAGS -52 "ERROR - invalid maximum number of tags" Error code added for dBASE IV multiple index file support. The maximum number of tag table elements is invalid (0 or greater than 48). User's Reference Guide 185 APPENDIX A, RESULT CODES AND MESSAGES SC_TBLELEN -53 "ERROR - bad tag table element length" Error code added for dBASE IV multiple index file support. The tag table element length was not equal to 32. SC_TAGCNT -54 "ERROR - invalid tag count" Error code added for dBASE IV multiple index file support. Tag count was less than 1 or greater than 48. SC_KEYFORM -55 "ERROR - unknown key format switches" Error code added for dBASE IV multiple index file support. File error. SC_UNSWITCH -56 "ERROR - unknown switch error" Error code added for dBASE IV multiple index and memo file support. File error. SC_TAGOPEN -57 "ERROR - tag in use" Error code added for dBASE IV multiple index file support. Tag already open. 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. 186 SoftC Database Library 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, User's Reference Guide 187 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 ... 188 SoftC Database Library Index to integers 39 Data long 35 field to long 40 array 80, 86 integer 31 read to month memo 165, 172 string 41 strings 85 to string values 83 day of week 43 write integers 31 memo 166, 173 long 36 strings 91 month 47 values 89 string 42 file close 79 Functions create 80 sccdi2l 21, 31, 36 flush 88 sccdi2s 21, 31, 40, 45 I/O buffer clear 98 sccdiget 22, 32, 46 I/O cache 77 sccdileap 22, 33, 47 information 93 sccdiperm 22, 34, 49 last update 95 sccdl2dow 22, 35 lock file 94 sccdl2i 21, 31, 35 lock record 102 sccdl2sx 21, 36 number of records 109 sccds2day 22, 37, 39, 42 open 96 sccds2dow 22, 35, 38 pack 97 sccds2i 21, 32, 39 position 78, 82, 103 sccds2lx 21, 37, 40 read header 92 sccds2mon 22, 41 record sccds2s 21, 42, 45 status 107 sccdsday 22, 43, 48 unlock 110 sccdsdiff 22, 44 record sccdsget 22, 33, 45 delete 99 sccdsleap 22, 34, 46 read 99, 100 sccdsmonth 22, 44, 47 recover 108 sccdsperm 22, 34, 48 write 104, 105 sccdsvalid 22, 32, 45, 49 Date sccdxlat 42 calculate sccti2s 22, 50, 52, 54 days per month 34, 48 scctiget 23, 51 difference 44 sccts2i 22, 51, 52 get from DOS scctsdiff 23, 53 integers 32 scctsget 23, 46, 54 string 45 scctsvalid 23, 51, 54, test 55 leap year 33, 46 scdcbfrsz 56 valid 49 scdcclose 57 translate scdccreate 58, 62, 72 to day of week scdcexpr 59 integer 37 scdcflush 60 long 35 scdchget 62 string 38 scdcindex 61 User's Reference Manual 189 INDEX scdcinfo 59, 63, 67, 68, scddrput 16, 100, 104, 70, 73, 74, 75 107 scdckadd 65, 69 scddrputx 101, 105 scdckbot 66, 68 scddrstat 17, 107 scdckcur 67, 68 scddrundel 16, 99, 108 scdckdel 68 scddsize 15, 109 scdckfind 68, 69 scddunlock 18, 26, 95, scdckmake 59, 66, 71 103, 110 scdcknext 68, 73 scdibfrsz 111 scdckprev 68, 74 scdiclose 112 scdcktop 68, 75 scdicreate 112, 128, 130 scdcopenx 60, 64, 76 scdiexpr 114 scddbfrsz 16, 77 scdiflush 115 scddbof 15, 78, 83, 104 scdihget 116 scddclose 15, 79 scdiindex 117 scddcreate 15, 17, 80, scdiinfo 114, 118, 121, 82 122, 125, 126, 129, scddeof 15, 79, 82, 104 131, 132, 133 scddfget 17, 24, 83, 85, scdikadd 119, 124 91, 100, 101 scdikbot 120, 121, 122 scddfgets 17, 84, 85, scdikcur 121 91, 92 scdikdate 120, 122, 128, scddfinfo 17, 84, 85, 86 130 scddflush 16, 88 scdikdel 123 scddfnam2no 17, 88 scdikfind 121, 122, 124 scddfput 17, 18, 24, 84, scdikmake 113, 114, 120, 89, 91, 92, 100, 101, 123, 126, 130 105, 106, 107, 166, scdiknext 121, 122, 128 173 scdiknum 20, 120, 123, scddfputs 17, 85, 91, 128, 130 105, 106, 107 scdikprev 121, 122, 131 scddhget 92 scdiktop 121, 122, 132 scddinfo 15, 93 scdinit 3, 8, 24, 134, scddlock 18, 26, 62, 92, 161, 179, 185 94, 103, 110, 117, scdiopenx 116, 119, 134 141, 162, 169 scdnbfrsz 19, 136 scddlud 15, 95 scdnclose 19, 137 scddopenx 15, 78, 80, scdncreate 19, 137, 152 88, 93, 95, 96, 97, scdnexpr 19, 138 98, 103, 110 scdnflush 19, 139 scddpack 16, 97, 165, scdnhget 140 172 scdnindex 19, 98, 141 scddrclear 16, 98 scdninfo 19, 139, 142, scddrdel 16, 99, 109 145, 146, 150, 153, scddrget 16, 84, 85, 99, 154, 155, 156, 157 101, 105, 107 scdnkadd 20, 143, 149 scddrgetx 100, 106, 107 scdnkbot 20, 144, 146 scddrinfo 16, 87, 101 scdnkcur 20, 146 scddrlock 18, 26, 95, scdnkdate 20, 144, 147, 102, 110 152 scddrnum 17, 79, 83, 103 scdnkdel 20, 148 190 SoftC Database Library INDEX scdnkfind 20, 146, 149 create 58 scdnkmake 20, 138, 144, flush 60 151, 179 index 61 scdnknext 20, 146, 153 open 76 scdnkprev 20, 146, 155 read header 62 scdnktop 20, 146, 157 key scdnopenx 19, 140, 143, add 65 158 build 71 scdtclose 18, 159 delete 68 scdtcreate 18, 160 get first 75 scdterm 8, 15, 24, 134, get last 66 160, 185 read next 73 scdthget 161 read previous 74 scdtinfo 18, 162 search 69 scdtopenx 18, 159, 162, dBASE 163, 165 expression scdtpack 18, 98, 164 defined 138, 151 scdtrget 18, 84, 165, functions 166 dtoc 20, 151 scdtrput 18, 166, 167 left 20, 151 scdwclose 167 right 20, 151, 152 scdwcreate 168 str 20, 151, 152 scdwhget 168 substr 20, 151, 152 scdwinfo 169 read 138 scdwopenx 167, 170, 172 file scdwpack 171 cache 136 scdwrget 172, 173 close 137 scdwrput 173, 174 create 137 sceclr 25, 174, 175 flush 139 scemsg 25, 175, 186 index 141 open 158 Global variables read header 140 sc_code 25, 161, 175, key 186 add 143 sc_date_style 24, 84, 90 build 147, 151 sc_version 24 delete 148 get first 157 Index get last 144 Clipper read next 153 expression read previous 155 defined 58, 71 search 149 functions FoxBase/FoxPro dtoc 71 expression left 71 defined 113, 126 right 71, 72 functions str 71, 72 dtoc 126, 127 substr 71, 72 left 126, 127 read 59 right 126, 127 file str 126, 127 cache 56 substr 126, 127 close 57 read 114 User's Reference Manual 191 INDEX file SC_BADHNDL 180 cache 111 SC_BADKEYT 181 close 112 SC_BADPG 180 create 112 SC_BADROOT 182 flush 115 SC_BADTAG 185 index 117 SC_BADTIME 181 open 134 SC_BADTNAME 185 read header 116 SC_BLKADR 185 key SC_BLKSZ 185 add 119 SC_CLOSFAIL 180 build 122, 126, 130 SC_DBFDATE 181 delete 123 SC_DBFHLEN 181 get first 132 SC_DBFVERS 181 get last 120 SC_DECPL 182 read next 128 SC_FILBAD 179 read previous 131 SC_FILSOPEN 184 search 124 SC_FLDCNT 182 SC_FLDLEN 182 Initialization 134 SC_FLSHFAIL 185 SC_ITEMLEN 182 Memo SC_KEYFORM 186 dBASE SC_KEYLEN 181 close 159 SC_LCKBOVR 184 create 160 SC_LCKVIOL 183 open 163 SC_LINELEN 183 pack 164 SC_MAXKEYS 182 read 165 SC_MAXTAGS 185 read header 161 SC_MDXFLAG 183 write 166 SC_MEMERR 179 FoxPro SC_MINKEYS 184 close 167 SC_NEWDEV 184 create 168 SC_NODBT 181 open 170 SC_NOFILE 179 pack 171 SC_NOHNDL 179 read 172 SC_NOPATH 184 read header 168 SC_NOPGS 180 write 173 SC_NOTLCKD 184 SC_NULLPARM 181 Return codes SC_OPENFAIL 185 clear 174 SC_RDFAIL 178 defined 24, 177 SC_READOLY 183 errors SC_RECLEN 183 SC_ACCDEN 184 SC_SKFAIL 179 SC_BADACC 184 SC_TAGCNT 186 SC_BADCMD 180 SC_TAGOPEN 186 SC_BADDATA 183 SC_TBLELEN 186 SC_BADDATE 180 SC_UNSWITCH 186 SC_BADEXPR 179 SC_WRTFAIL 178 SC_BADFLDN 182 message translate 175 SC_BADFLDT 183 warnings SC_BADFNAME 180 SC_DELREC 177 192 SoftC Database Library INDEX SC_EMPTY 177 SC_FP1 81 SC_END 177 SC_FILENGTH 178 SC_GETSZ 56, 77, 111, 136 SC_FLDROUND 177 SC_FLDTRUNC 177 SC_GREGOR 21, 24, 32, 37, SC_MEMWRN 178 38, 39, 40, 41, 42, 43, 44, SC_NOFIND 177 45, 46, 47, 48, 49, 50, 84, SC_NOFUNC 178 90, 96, 123, 147 SC_NOTBFRD 178 SC_GREGORL 21, 32, 37, 38, SC_ADD 105, 106, 174 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 96, SC_BUFFER 16, 19, 60, 77, 123, 147 78, 88, 97, 116, 135, 140, 159, 163, 171, 178 SC_JULIAN 21, 32, 37, 38, 39, 40, 41, 42, 43, 44, 45, SC_CKEY 58, 113, 138 46, 47, 48, 49, 50, 96, 123, 147 SC_CRDELETE 166 SC_LKEY 113 SC_CRUNCHNG 166 SC_MIL 21, 51, 52, 54, 55, SC_CSHMS 21, 51, 52, 54, 56 55, 56 SC_NKEY 58, 113, 138 SC_DB3 81 SC_NOTUSED 98 SC_DB4 81 SC_RDONLY 76, 97, 98, 135, SC_DELREC 100, 101, 107 158, 163, 170 SC_DKEY 58, 113, 138 SC_RDWR 76, 96, 135, 158, 163, 170 SC_DMY 21, 24, 32, 37, 38, 39, 40, 41, 42, 43, 44, 45, SC_SETSZ 56, 77, 111, 136 46, 47, 48, 49, 50, 96, 123, 147 SC_SHARED 77, 94, 97, 103, 110, 135, 159, 163, 171 SC_EXACT 70, 125, 150 SC_SUCCESS 107 SC_EXCLUDE 77, 97, 135, 159, 163, 171, 184 SC_TRUE 15, 34, 47, 79, 83 SC_FALSE 34, 47, 79, 83 SC_UNIQUE 59, 113, 138 SC_FIELD 80, 86 SC_UPDATE 105, 106, 174 SC_FIRST 70, 125, 150 SC_USEXHNDL 134, 185 SC_FLUSH 77, 97, 135, 159, SC_YMD 21, 32, 37, 38, 39, 178 40, 41, 42, 43, 44, 45, 46, User's Reference Manual 193 INDEX 47, 48, 49, 50, 96, 123, 147 Structures SC_DBFINFO 93 SC_DBFRINFO 101, 102 SC_DBTINFO 162 SC_FIELD 80, 86 SC_FLAGS 64, 93, 118, 142, 162, 169 SC_FPTINFO 169 SC_IDXINFO 118 SC_NDXINFO 142 SC_NTXINFO 64 Termination 160 Time calculation 53 get from DOS integers 51 string 54 test 55 translation 50, 52 194 SoftC Database Library