Shareware Overload

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

/ Shareware Overload / ShartewareOverload.cdr / database / softc101.zip / SOFTC.MAN < prev next >

Wrap

Text File | 1989-02-15 | 240KB | 5,777 lines

SoftC Library Reference Manual Version 1.01 Manual and Software Copyright 1988, 1989 by K. L. Schumann 16820 3rd Street North East Ham Lake, Minnesota 55304 (612) 434-6968 ALL RIGHTS RESERVED This document describes version 1.01 of the SoftC Library, created in February 1989. DISCLAIMER The author makes no representation or warranties with respect to this product and specifically disclaims any implied warranties or merchantability or fitness for any particular purpose. The author shall have no liability with respect to his obligations under this agreement for compensatory, special, incidental, consequential, or exemplary damages. The author further reserves the right to make changes to the specifications of the library and contents of the manual without obligation to notify any person or organizations of such changes. Table of Contents Chapter 1 Introduction................................ 1 Registration...................................... 2 User Supported Software........................... 2 Typographic Conventions........................... 3 Trademarks........................................ 3 Support and Updates............................... 3 The Future........................................ 3 Chapter 2 Before You Begin............................ 4 The READ.ME File.................................. 4 Installing SoftC on Your System................... 4 SoftC Applications................................ 5 Compiling with Turbo C............................ 6 Recompiling the SoftC Libraries................... 6 Function Naming Conventions....................... 6 Chapter 3 A Windows Toolkit Tutorial.................. 7 Basic Rules....................................... 7 Screen Output..................................... 8 Cursor Control.................................... 8 Erase Functions................................... 9 Character Colors.................................. 9 Window Control.................................... 9 Window Colors..................................... 10 Window Border Styles.............................. 10 Window Titles..................................... 10 Chapter 4 A dBase III Toolkit Tutorial................ 11 Sequential Files.................................. 11 Random Access Files............................... 11 Keys.............................................. 11 ISAM and B-trees.................................. 12 Basic Rules....................................... 13 Data File Functions............................... 13 Data Record I/O................................... 13 Data Field I/O.................................... 14 Index File Functions.............................. 15 Index Page Functions.............................. 15 Index Key Functions............................... 15 Chapter 5 Clock & Calendar Functions.................. 17 Chapter 6 Miscellaneous Functions..................... 18 Chapter 7 The SoftC Library........................... 19 sccday............................................ 21 sccddiff.......................................... 22 sccdn2s........................................... 23 sccds2n........................................... 24 sccdvalid......................................... 25 sccdxlat.......................................... 25 sccleap........................................... 26 sccleapi.......................................... 27 sccmonth.......................................... 28 scdclose.......................................... 29 scdcreate......................................... 30 scdfget........................................... 32 iii Table of Contents scdfgets.......................................... 33 scdfinfo.......................................... 34 scdfnam2no........................................ 36 scdfput........................................... 37 scdfputs.......................................... 38 scdinfo........................................... 39 scdopen........................................... 40 scdrclear......................................... 41 scdrcopy.......................................... 42 scdrdel........................................... 43 scdrget........................................... 44 scdrinfo.......................................... 46 scdrput........................................... 47 scdrundel......................................... 48 scdsize........................................... 49 sceclr............................................ 50 scemsg............................................ 51 sciclose.......................................... 52 scicreate......................................... 53 sciexpr........................................... 54 sciinfo........................................... 55 scikadd........................................... 56 scikcur........................................... 58 scikdel........................................... 59 scikfind.......................................... 60 scikfirst......................................... 62 sciklast.......................................... 63 scikmake.......................................... 64 sciknext.......................................... 67 scikprev.......................................... 68 scinit............................................ 69 sciopen........................................... 70 scipinfo.......................................... 71 scipnum........................................... 72 scterm............................................ 73 scvers............................................ 74 scwaget........................................... 74 scwaput........................................... 75 scwbget........................................... 76 scwbput........................................... 78 scwcget........................................... 79 scwclose.......................................... 81 scwclr............................................ 83 scwclreol......................................... 83 scwcput........................................... 84 scwcursoff........................................ 85 scwcurson......................................... 86 scwgoto........................................... 87 scwinfo........................................... 88 scwopen........................................... 89 scwopenx.......................................... 90 iv Table of Contents scwprintf......................................... 92 scwputc........................................... 93 scwputs........................................... 94 scwselect......................................... 95 scwtget........................................... 96 scwtput........................................... 97 scwxloc........................................... 98 scwyloc........................................... 99 Index................................................. 100 v Chapter 1 Chapter 1 Introduction Introduction C is generally considered to be a "bare-bones" language. A way to put some flesh on those bones is to develop generalized functions (extensions) which may be reused in many programs. The presence of these functions can make programming a quick and simple task. The absence of these language extensions can mean many hours lost "re-inventing the wheel". Few programmers have the time required to develop and debug such a library of functions. This is where SoftC comes in. This library is a collection of functions designed to make your applications quicker and easier to code and test. With the SoftC library you can spend time on your application not on developing tools. There also is a benefit to using functions found in a toolkit library versus using the functions found in your compiler's library. It may seem trivial, but if you ever decide to change compilers you will find that it will take many hours to convert your source to match the new compiler's syntax. Using a generic toolkit such as SoftC will eliminate that effort. SoftC adds powerful capabilities to your function library: -cursor positioning -windowing -screen output -character attribute control -date manipulation and calculation -database data and index file functions The SoftC library is intended for use as a supplement to your compiler's object libraries. It contains over seventy functions. Currently is has three main features: text windowing, dBaseIII compatible data and index file manipulation, and clock/calendar functions. The library is currently available only for Turbo C (I am working on a Microsoft C version). These routines were written in C. The SoftC library is the copyrighted property of K. L. Schumann. You are granted a limited license to use the library, and to copy 2 Chapter 1, Introduction 2 and distribute the following files (without modification): SOFTC.H, DBASE.H, WINDOWS.H, SCTC20S.LIB, SOFTC.MAN, READ.ME and REGISTER. Registration Registration If you find this library useful, you are encouraged to register your copy for only $20. Once registered you will receive two diskettes containing the complete C source for the library and the remaining memory model libraries. To register print the file "REGISTER", read it, and mail the completed form to: Kim L. Schumann 16820 3rd Street North East Ham Lake, Minnesota 55304 User Supported Software User Supported Software This library is user supported software. This means that you may copy and distribute it (under the conditions specified above) to anyone at no cost. They are in turn requested to register if they decide to use it. The user supported software concept (often referred to as shareware) 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. User supported software is an attempt to develop a new marketing channel where products can be introduced at minimum cost. Everyone will benefit if user supported software works. The user benefits by receiving 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 couple of weeks, then it is obviously worth something to you, and a contribution should be sent. Chapter 1, Introduction 3 3 Typographic Conventions Typographic Conventions [] Square brackets enclose optional data. Boldface SoftC Library function names (such as Boldface scinit) and structure names when they scinit appear in text (but not in program examples). Italics indicate variable names (identifiers) that _______ ___________ appear in text. Trademarks Trademarks Clipper is a registered trademark of Nantucket Software. dBASEIII is a registered trademark of Ashton-Tate. Microsoft is a registered trademark of Microsoft Corporation. Turbo C is a registered trademark of Borland International. Support and Updates Support and Updates I will only offer advice and technical support to those who contribute via the shareware concept. Users who register will be notified when updates and new products are available. I can be contacted by telephone at (612) 434-6968 after 6pm Central Time, via mail at the registration address above, or on GEnie through GE Mail at "K.SCHUMANN". The Future The Future There are many enhancements that could be made to the dBaseIII routines: make them LAN multi-user, add functions found in dBase which do not have a corresponding C function, and add support for dBaseIII MEMO fields. The window toolkit was written with expansion into graphical windows in mind. Adding a virtual window feature could be incorporated if there is enough demand. I would like to add pop-up, and pull down menuing functions to the library. Formatted input functions are also on the "to do" list. Anyone wishing to offer advice and suggestions are most welcome to do so. Chapter 2 Chapter 2 Before You Begin Before You Begin This chapter supplies instructions for installing the library on your hard disk and compiling the source. The READ.ME File 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 found on the library diskette (or if you have the demonstration version of the library it will be found in the .ARC file). Installing SoftC on Your System Installing SoftC on Your System The Source Code disk is compatible with all of the compilers which I support. The Library disk, however, will differ from compiler to compiler. Check the label to be certain you have the proper library disk for your compiler. Because the library disk is supplied for your compiler, you can get started right away. The source can be recompiled if you ever change compilers. It is a good idea to recompile the library when you upgrade your 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, I will explain what files are required and where they are often located. The SoftC 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. I would suggest that they be placed where the header files for your compiler are located. All the header files will be found on the source code diskette. Your linker will need to be able to find the SoftC object libraries. It is suggested that these be placed where the run- time libraries for your compiler are found. Chapter 2, Before You Begin 5 5 Different libraries are supplied for the various memory models your compiler supports. The name of the library defines the compiler manufacturer and version, and the memory model for which it was compiled. All library names begin with "SC". The next few characters specify the compiler manufacturer. The last character defines the memory model. For example SCTC20S.LIB is the small memory model library for Borland's Turbo C compiler (version 2.x). You may copy only the libraries for the memory model(s) you plan to use. But then again, if you have the space available you could copy them all just to have them available. SoftC Applications SoftC Applications A typical application skeleton has the following form: #include <softc.h> #include <windows.h> /* global declarations */ void main() { /* local declarations */ scinit(20,20); . . . /* body of application */ . . . scterm(); } The scinit function must be the first function called in your scinit application and IT MUST BE CALLED ONLY ONCE. The last function IT MUST BE CALLED ONLY ONCE should be scterm. This is not a requirement but it is good scterm programming practice. This function should be called only once. See the descriptions of these functions in the library reference section of this manual. 6 Chapter 2, Before You Begin 6 Compiling with Turbo C Compiling with Turbo C Turbo C provides two ways of compiling programs: the integrated environment and the command line version. In order to use SoftC with the integrated environment a project file must be created and the appropriate library must be specified in that file: myprog /* your program name */ sctc20s.lib /* the desired SoftC library */ To use the library with the command line compiler simply include the library name in filename list: tcc -f -Ic:\c\include -Lc:\c\lib myprog sctc20s.lib Recompiling the SoftC Libraries Recompiling the SoftC Libraries If you modify a SoftC source code file, 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 SoftC program. Refer to your compiler documentation for instructions for replacing modules in libraries. Function Naming Conventions Function Naming Conventions All SoftC functions begin with the letters "sc". This is to differentiate them from the standard library functions. The window functions begin with "scw", the dBase III data file functions with "scd", the dBase III index file functions with "sci", and the clock/calendar functions with "scc". Chapter 3 Chapter 3 A Windows Toolkit Tutorial A Windows Toolkit Tutorial Screen I/O is a major part of almost every computer application. Because of the limited amount of space on the screen it is not unusual to run out of room. Windowing is one way of coping with this limitation, but perhaps more importantly it enables the programmer to organize and present information in a useful manner. If the concept of windows is new to you, think of your desktop covered by pages of paper. Some pages overlap at the edges, some are completely hidden by other pages. This is the same thing that happens on your computer screen. Ordinarily the entire screen is devoted to one page of information. Using windows you can have parts of many pages visible on your screen at once. You can open and overlay as many windows as the memory of your computer will allow. When you are finished with a window, close it and the underlying information is restored. Because each window is treated as a small screen, all of the window I/O functions will work the same whether windows are in use or not. In other words, there is no difference in functions (or syntax) to print to the physical screen or to a window. Basic Rules Basic Rules In order to benefit fully from the SoftC library, it is necessary to use only the functions found in the SoftC library when performing screen I/O. When standard functions such as printf and printf puts are used, the SoftC window manager is bypassed. This means puts that it can no longer keep track of the activities in your window which can lead to unpredictable results. SoftC has direct replacements for many of the standard C screen I/O functions (the following functions will work with or without a window): Standard C SoftC printf, cprintf scwprintf printf cprintf scwprintf puts, cputs scwputs puts cputs scwputs putch, putchar scwputc putch putchar scwputc 8 Chapter 3, A Windows Toolkit Tutorial 8 Also additional functions have been added to standardize cursor control functions between compilers (and in the future between text and graphics modes) (note that the following functions will work with or without a window): Turbo C SoftC gotoxy scwgoto gotoxy scwgoto wherex scwxloc wherex scwxloc wherey scwyloc wherey scwyloc clrscr scwclr clrscr scwclr clreol scwclreol clreol scwclreol textcolor, textbackground, textattr scwaput textcolor textbackground textattr scwaput gettextinfo scwinfo, scwaget gettextinfo scwinfo scwaget Screen Output Screen Output SoftC provides three methods of outputting characters to a window: scwprintf, scwputs, and scwputc. scwputc and scwputs are scwprintf scwputs scwputc scwputc scwputs implemented as macros which call scwprintf. scwprintf functions scwprintf scwprintf the same as the standard printf function: a format string printf followed by option arguments are passed to the function. One fact to be aware of is the string expansion limitation found in scwprintf: the data to be displayed cannot expand beyond 256 scwprintf characters including the terminating NULL byte or the stack will be corrupted with potentially disastrous results. Cursor Control Cursor Control The SoftC screen is divided into rows and columns. Rows are numbered vertically down the screen and columns are numbered horizontally across the screen. Coordinates of any point on the screen can be expressed in column numbers and row numbers. SoftC uses a coordinate system where the column is listed first and then the row. The upper left corner of the window is defined by the coordinates (1,1) (also known as the home coordinates). The row number is hereafter referred to as the 'y' coordinate, and the column number is referred to as the 'x' coordinate. Three types of cursor control functions exist in SoftC: move the cursor to a new location, tell where the cursor is currently positioned, and hide/show cursor. scwgoto is used to reposition scwgoto the cursor anywhere on the window. scwxloc and scwyloc return the scwxloc scwyloc current cursor 'x' and 'y' coordinates respectively. scwcursoff scwcursoff will hide the cursor and scwcurson will show it again. scwcurson Chapter 3, A Windows Toolkit Tutorial 9 9 Erase Functions Erase Functions When the entire window or only a portion of a line need to be cleared, the functions scwclr and scwclreol are used. scwclr will scwclr scwclreol scwclr erase everything from the current window and reposition the cursor at the home coordinates. scwclreol will erase all text scwclreol from the current cursor position to the right edge of the window. The cursor position will not be changed. Character Colors Character Colors Text color, background color, and blinking attributes are controlled via scwaput and scwaget functions. Currently sixteen scwaput scwaget colors are supported: black, blue, green, cyan, red, magenta, brown, light gray, dark gray, light blue, light green, light cyan, light red, light magenta, yellow, and white. It is suggested that you use the SoftC definitions for these colors in order to maintain compatibility with other monitors (such as EGA, and VGA). Window Control Window Control In order to use a window it must first be opened. There are two window opening functions: scwopen and scwopenx. scwopen is a high scwopen scwopenx scwopen level function which requires only the upper left corner screen coordinates (x and y) and the width and height of the desired window. The window colors and style are defaulted to zero (0) and there is no title. See the window color and border style discussions later in this chapter. scwopenx extends the high level window open by giving you control scwopenx over the window color and border style, and allows the use of a window title. After a window has been opened, any of the preceding window functions (scwputs, etc.) will work within the scwputs confines of that window. Multiple windows can open at the same time. scwselect provides a scwselect mechanism to switch between any of the non-overlaid windows on the screen. The library does not allow the selection of a window which is partially covered by another. When you are finished with a window it can be removed from the screen and the underlying data restored via a call to scwclose. scwclose This function will also free up the memory allocated for the window being closed. 10 Chapter 3, A Windows Toolkit Tutorial 10 At some point you may need some information about a window, such as its size, color scheme, border style, or title length. This is accomplished by a call to scwinfo. scwinfo Window Colors Window Colors There is a window color scheme array used by SoftC to control the colors of the window border, title, and the initial color of text printout. The array is large enough to hold color information for ten different color schemes. Each element in the array holds text color and background color information for each of the three previously mentioned items. There are two functions provided to access this color information: scwcget and scwcput. scwcget will retrieve the color scwcget scwcput scwcget scheme and scwcput will set it. scwcput Window Border Styles Window Border Styles SoftC uses another array to control the window border style. The six characters used to make a window are stored in each element of the array: the four corners of the window as well as horizontal and vertical connecting characters. This array is large enough to hold four different border styles. scwbget is scwbget used to retrieve border style information from the array, and scwbput is used to change it. scwbput Window Titles Window Titles Control over the title of the current window is provided by two functions: scwtget and scwtput. The title can be easily changed scwtget scwtput via a call to scwtput. The current window title can be retrieved scwtput through a call to scwtget. If you are uncertain as to the size of scwtget the title string a call to scwinfo will tell you how long the scwinfo string is including the terminating NULL byte. Chapter 4 Chapter 4 A dBase III Toolkit Tutorial A dBase III Toolkit 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 Library provides functions to enable you to integrate your program and dBase III compatible data and index 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 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 records will have to be moved in order to make room for the new record. Random Access Files 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. Keys 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 12 Chapter 4, A dBase III Toolkit Tutorial 12 together they form an index file. dBase uses a technique called ISAM to access the underlying B-tree structure of its index files. ISAM and B-trees ISAM and B-trees 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. B-tree (or branch tree) is the underlying structure used in ISAM. Searching always begins at the top of the tree. Each key item on an index page can point to another index page (this is where the "branching" comes into play). If a key item does not point to another index page it is referred to as a "terminal node". A search is ended when a terminal node is encountered. When a data record for a specific key needs to be accessed, The first (top) index page is searched with the desired key text. If not at a terminal node, a determination will be made using the branch trees as to which index page should next be searched. This sequence of searching and branching is followed until a terminal node is encountered. If an exact match is found the data record number found in that key item can be used to access the data file. When a key needs to be added to an index file, the above sequence of searching and branching is again followed until the location where the new key should be placed is found. Because of the nature of the ISAM file it is much easier and faster to add a key to the index page than appearances may indicate. If an index page overflows it will be split into two pages. Likewise if it underflows it will be joined with another index page. This system results in a minimal amount of file I/O. 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. Chapter 4, A dBase III Toolkit Tutorial 13 13 Basic Rules Basic Rules In order to benefit fully from the SoftC 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, fprintf the SoftC database 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. Data File Functions Data File Functions In order to use a data file it first must be opened. scdopen will scdopen open any dBase III or dBase III+ compatible data file. The SoftC database manager file 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 scdclose. This is true for a scdclose 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 scterm in that it will close all data scterm and index files as well as any windows open at program termination. The length of the data file in bytes can be found using scdsize. scdsize The name of the data file associated with a particular handle can be retrieved via a call to scdinfo. Also a new data file can be scdinfo created by scdcreate. scdcreate Data Record I/O Data Record I/O Having a data file is of little use unless you can manipulate the individual records. SoftC provides seven 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 scdrget. The scdrget actual data will be placed in a SoftC 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, scdrput should be used. This scdrput function is used both for the changing of a record as well as adding new records. 14 Chapter 4, A dBase III Toolkit Tutorial 14 dBase III 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. SoftC follows this guideline by providing the scdrdel function to mark a data scdrdel record as deleted, and the scdrundel function to recover the scdrundel record (or mark as active). Information about the data record structure can be retrieved by a called to scdrinfo. The record length, number of fields in the scdrinfo data record, and the addresses of the I/O buffers can be obtained in this way. Two additional functions are provided which deal exclusively with the internal SoftC I/O buffers: scdrclear, and scdrcopy. scdrclear scdrcopy scdrclear is useful in clearing the output buffer before placing scdrclear 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. scdrcopy can be useful scdrcopy when a record needs to be updated but the original also needs to be retained. Data Field I/O Data Field I/O The six data field manipulation functions provide for: the writing of data to a field in the output buffer, the reading of data from a field in the input buffer, the conversion of field names to field numbers, and the retrieval of the field descriptions originally setup with scdcreate. scdcreate There are two types of field I/O: standard C types and ASCIIZ string. scdfput and scdfget use the standard C types below to scdfput scdfget place data in and retrieve data from individual fields in a record. scdfput attempts to properly format the data before scdfput placing it in the field. This means that the proper number of spaces, zeros, and/or a decimal point will be added as appropriate. C types dBase III types char [8] date ASCIIZ string character double numeric char logical scdfputs and scdfgets use ASCIIZ strings exclusively. It is left scdfputs scdfgets up to the users of these functions to ensure that the data is properly formatted. Both "scdfput" functions work with the output buffer, and the "scdfget" functions work with the input buffer. Chapter 4, A dBase III Toolkit Tutorial 15 15 A field name to field number translation function (scdfnam2no) is scdfnam2no provided to isolate your application from the structure of the data files. Index File Functions Index File Functions In order to use an index file it first must be opened. sciopen sciopen will open any dBase III or dBase III+ compatible index file. The index files created by Clipper are not compatible with dBase III (and thusly with SoftC). The SoftC database manager file 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 scdclose. Information about the index file such as the scdclose file name and length of the key expression can be retrieved by a call to sciinfo. A new index file can be created by using the sciinfo function scicreate. scicreate sciexpr can be used to get the actual index key expression. This sciexpr 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". Index Page Functions Index Page Functions If memory is available the SoftC database manager will allocate space for ten index pages. In some instances more or less pages may be needed to provide fast access to index information. scipinfo is used to find out how many pages for which space was scipinfo allocated. To change the number of pages for which memory was allocated, scipnum can be used. scipnum Index Key Functions Index Key Functions Nine 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 first key (scikfirst), finding scikfirst the last key (sciklast), and searching for a specific key sciklast (scikfind). The keys found in this manner become the "current scikfind key". Wildcards such as "?" and "*" cannot be used. Once a particular key is found it is often desired to get the key following (sciknext) or the key preceding (scikprev) it. These sciknext scikprev 16 Chapter 4, A dBase III Toolkit Tutorial 16 keys, if found, become the current key. Another function is provided to return the current key, scikcur. scikcur It also desirable to be able to add and delete keys from the index file. scikadd and scikdel provide these functions. These scikadd scikdel functions also attempt to keep the B-tree balanced, so that one branch of the tree will not grow larger than the others. dBaseIII provides certain functions which may be used in a key expression. scikmake will build a key for you using the index key scikmake expression and the contents of the current output buffer. This function supports five of the more common dBaseIII functions: dtoc, left, right, str, and substr. dtoc left right str substr Chapter 5 Chapter 5 Clock & Calendar Functions Clock & Calendar Functions This chapter will describe the clock and date functions available in the SoftC Library. Currently only nine functions are implemented and they are all are date manipulators. Note that the date format is "yyyymmdd" for all functions unless otherwise specified. Internal to dBaseIII the date fields are formatted as "yyyymmdd". 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. If fact dBaseIII uses the date format "mm/dd/yy" when it displays dates. A function sccdxlat was created to allow switching between these sccdxlat two formats. An additional format is provided to enable the year section of the date to more accurately represent the year entered. This format is "mm/dd/yyyy". Quite often some calculations will need to be performed on date strings and two functions are provided for this purpose. sccddiff sccddiff calculates the difference between two date strings for you, and sccds2n will convert the date string into three integers: year, sccds2n month, and day so you can do your own calculations. sccdn2s will sccdn2s convert from three integers back to a string. Two functions are provided to test for leap year. sccleap sccleap requires a date string and sccleapi uses an integer. To check if sccleapi a given date string is valid sccdvalid can be used. Two sccdvalid additional functions are provided for displaying text strings: sccday is used to get the day of the week string and sccmonth sccday sccmonth returns the month string. Chapter 6 Chapter 6 Miscellaneous Functions Miscellaneous Functions This chapter will describe the miscellaneous functions found in the SoftC library. scinit sets up the SoftC window and database managers. Memory scinit 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. scterm is called at the end of scterm your application. It will close all windows and database files and free the memory allocated by scinit. scinit The scvers function has been provided to retrieve a NULL scvers terminated character string containing the version of the SoftC library you are currently using. This can then be printed by scwputs. scwputs A global variable sc_code will contain the results of the last sc_code SoftC function call executed. Errors are indicated by negative numbers, warnings by positive numbers greater than zero, and a zero indicates success. 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 sc_code scemsg message associated with the contents of sc_code, which can then sc_code be printed by scwputs. scwputs 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 sc_code sceclr can be used. It is preferable to use the function rather than the global variable. Chapter 7 Chapter 7 The SoftC Library The SoftC Library This chapter contains a detailed description of each of the functions in the SoftC library. The following sample function description explains how to use this portion of the SoftC Library Reference Manual. function name function name _____________ Usage Usage _____ function(modifier parameter[,...]); function _________ The declaration syntax for function, parameter names function _________ are italicized. The [,...] indicates that other parameters and their modifiers may follow. Prototype in Prototype in ____________ This lists the header files in which the function is prototyped. Description Description ___________ This describes what function does, the parameters it takes, and any details you need in order to use function and the related routines listed. See also See also ________ Routines related to function that you may wish to read about are listed here. Return Value Return Value ____________ The value(s) that function returns (if any) are listed here. The return value will also be set in sc_code. sc_code Unless otherwise noted in the specific function description, the function call will be ignored if sc_code contains an error (values less than zero). A sc_code good return will always be equal to zero. Any warning codes are always greater than zero. 20 Chapter 7, The SoftC Library 20 Example Example _______ A sample program listing demonstrating how function is used. Chapter 7, The SoftC Library 21 21 sccday sccday ______ Usage Usage _____ signed short int sccday( signed char day, sccday ___ signed char daystr[10] ); ______ Prototype in Prototype in ____________ SoftC.h Description Description ___________ sccday returns the day of the week string in daystr for sccday ______ 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. See also See also ________ sccmonth sccmonth Return Value Return Value ____________ SC_SUCCESS function successful SC_BADDATE invalid date Example Example _______ #include "SoftC.h" void main() { char day[10]; scinit(1,1); sccday(0,day); scwputs(day); scterm(); } 22 Chapter 7, The SoftC Library 22 sccddiff sccddiff ________ Usage Usage _____ signed short int sccddiff( signed char *date1, sccddiff _____ signed char *date2, _____ signed long *diff ); ____ Prototype in Prototype in ____________ SoftC.h Description Description ___________ sccddiff returns the difference in days between date1 sccddiff _____ and date2. The two date strings can be in any order, _____ but must be valid dates of the format "yyyymmdd" (eg "19890213"). This is the date format used internally by the SoftC database manager. sccdxlat can be used to sccdxlat translate an existing date string to this format, or a date string can be built using sccdn2s. sccdn2s See also See also ________ sccdxlat, sccdn2s, sccdvalid. sccdxlat sccdn2s sccdvalid Return Value Return Value ____________ SC_SUCCESS calculation successful SC_BADDATE invalid date Example Example _______ #include "SoftC.h" void main() { signed long d; scinit(1,1); sccddiff("19890213","19881217",&d); scwprintf("%ld",d); scterm(); } Chapter 7, The SoftC Library 23 23 sccdn2s sccdn2s _______ Usage Usage _____ signed short int sccdn2s( signed int year, sccdn2s _____ signed int month, _____ signed int day, ____ signed char *string ); ______ Prototype in Prototype in ____________ SoftC.h Description Description ___________ sccdn2s converts three integer date values (year, sccdn2s ____ month, and day) into a character string (string). A _____ ___ ______ check is made to verify that string is a valid date ______ string before exiting. See also See also ________ sccdvalid, sccds2n. sccdvalid sccds2n Return Value Return Value ____________ SC_SUCCESS conversion successful SC_BADDATE invalid date Example Example _______ #include "SoftC.h" void main() { signed char d[9]; scinit(1,1); sccdn2s(1989,2,13,d); scwputs(d); scterm(); } 24 Chapter 7, The SoftC Library 24 sccds2n sccds2n _______ Usage Usage _____ signed short int sccds2n( signed char *string, sccds2n ______ signed int *year, _ ____ signed int *month, _____ signed int *day ); _ ___ Prototype in Prototype in ____________ SoftC.h Description Description ___________ sccds2n converts dates from a character string (string) sccds2n ______ 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. See also See also ________ sccdn2s. sccdn2s Return Value Return Value ____________ SC_SUCCESS conversion successful SC_BADDATE invalid date Example Example _______ #include "SoftC.h" void main() { signed int y, m, d; scinit(1,1); sccds2n("19890213",&y,&m,&d); scwprintf("%d %d %d",y,m,d); scterm(); } Chapter 7, The SoftC Library 25 25 sccdvalid sccdvalid _________ Usage Usage _____ signed char sccdvalid( signed char *string ); sccdvalid ______ Prototype in Prototype in ____________ SoftC.h Description Description ___________ sccdvalid tests the date string (string) passed for sccdvalid ______ validity: string properly formatted ("yyyymmdd"), valid day of month, valid month of year. Return Value Return Value ____________ TRUE valid date FALSE invalid date Example Example _______ #include "SoftC.h" void main() { scinit(1,1); if (sccdvalid("19890213")) scwputs("Good Date."); else scwputs("Bad Date."); scterm(); } sccdxlat sccdxlat ________ Usage Usage _____ signed short int sccdxlat( signed char method, sccdxlat ______ signed char *source, ______ signed char *dest ); ____ 26 Chapter 7, The SoftC Library 26 Prototype in Prototype in ____________ SoftC.h Description Description ___________ sccdxlat translates from one date string format to sccdxlat another under control of method. Currently three ______ translation methods are supported: SC_2ASCII - from "yyyymmdd" to "mm/dd/yy", SC_2ASCIIL - from "yyyymmdd" to "mm/dd/yyyy", and SC_2DBASE - from "mm/dd/[yy]yy" to "yyyymmdd". The maximum lengths of dest and source are 10 ____ ______ characters (plus the NULL byte). Note that when converting using SC_2DBASE dates such as "2/1/89" will be translated to "19890201". Return Value Return Value ____________ SC_SUCCESS translation successful SC_BADCMD invalid translation method ______ SC_BADDATE invalid date Example Example _______ #include "SoftC.h" void main() { char date[11]; scinit(1,1); sccdxlat(SC_2ASCII,"2/1/89",date); scwputs(date); scterm(); } sccleap sccleap _______ Usage Usage _____ signed char sccleap( signed char *leap ); sccleap ____ Chapter 7, The SoftC Library 27 27 Prototype in Prototype in ____________ SoftC.h Description Description ___________ sccleap tests the string year passed to it in leap to sccleap ____ see if it is a leap year. See also See also ________ sccleapi sccleapi Return Value Return Value ____________ TRUE year was a leap year FALSE year was not a leap year Example Example _______ #include "SoftC.h" void main() { scinit(1,1); if (sccleap("1989") scwputs("Leap Year!"); else scwputs("Normal Year."); scterm(); } sccleapi sccleapi ________ Usage Usage _____ signed char sccleapi( signed int leap ); sccleapi ____ Prototype in Prototype in ____________ SoftC.h Description Description ___________ sccleapi tests the integer year passed to it in leap to sccleapi ____ see if it is a leap year. 28 Chapter 7, The SoftC Library 28 See also See also ________ sccleap sccleap Return Value Return Value ____________ TRUE year was a leap year FALSE year was not a leap year Example Example _______ #include "SoftC.h" void main() { scinit(1,1); if (sccleap(1989) scwputs("Leap Year!"); else scwputs("Normal Year."); scterm(); } sccmonth sccmonth ________ Usage Usage _____ signed short int sccmonth( signed char month, sccmonth _____ signed char monthstr[10] ); ________ Prototype in Prototype in ____________ SoftC.h Description Description ___________ sccmonth returns the month string in monthstr for the sccmonth ________ 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. See also See also ________ sccday sccday Chapter 7, The SoftC Library 29 29 Return Value Return Value ____________ SC_SUCCESS function successful SC_BADDATE invalid date Example Example _______ #include "SoftC.h" void main() { char month[10]; scinit(1,1); sccmonth(0,month); scwputs(month); scterm(); } scdclose scdclose ________ Usage Usage _____ signed short int scdclose( signed char handle ); scdclose ______ Prototype in Prototype in ____________ dbase.h Description Description ___________ scdclose closes a .DBF file and frees all allocated scdclose memory associated with .DBF file handle. See also See also ________ scdopen scdopen Return Value Return Value ____________ SC_SUCCESS .DBF file closed SC_CLOSFAIL file close failure SC_BADHNDL .DBF file not open or bad handle 30 Chapter 7, The SoftC Library 30 Example Example _______ #include "SoftC.h" #include "dbase.h" void main() { char dbf; scinit(20,20); if (scdopen(&dbf,"TEST.DBF") == SC_SUCCESS) scdclose(dbf); scterm(); } scdcreate scdcreate _________ Usage Usage _____ signed short int scdcreate( signed char *filename, scdcreate ________ signed char numfields, _________ SC_FIELD fields[]); ______ Prototype in Prototype in ____________ dbase.h Description Description ___________ scdcreate creates a .DBF file. A pointer to an array of scdcreate SC_FIELD must be passed. typedef struct { signed char name[11]; /* field name */ signed char type; /* field type */ unsigned char len; /* field length */ unsigned char decpl; /* decimal places */ } SC_FIELD; SC_FIELD The field description array must be initialized and each element set to appropriate values. The array determines the organization of a data record. The .DBF file does not remain open upon exit of this function. Chapter 7, The SoftC Library 31 31 This function will create a new .DBF file even if one had already existed. Field names and types are converted to all upper case when the file is created. Restrictions: DBaseIII: maximum record length is 4000 bytes. maximum number of fields is 128. maximum length of character fields is 254. SoftC: maximum length of numeric fields is 19 this includes the decimal point and the sign . length of date field is forced to 8. length of logical fields is forced to 1. the decimal places will be forced to zero for all types except NUMERIC in which case it must be less then 'len' - 2. Return Value Return Value ____________ SC_SUCCESS .DBF file created SC_WRTFAIL disk write failure SC_BADFLD user supplied field description bad SC_NOHNDL no DOS file handles available Example Example _______ #include "SoftC.h" #include "dbase.h" void main() { SC_FIELD fields[4] = { "character",'c',16,0, /* character field */ "date",'d',8,0, /* date field */ "logical",'l',1,0, /* logical field */ "numeric",'n',6,2 /* numeric field */ }; scinit(20,20); scdcreate("TEST.DBF",4,fields); scterm(); } 32 Chapter 7, The SoftC Library 32 scdfget scdfget _______ Usage Usage _____ signed short int scdfget( signed char handle, scdfget ______ signed char fieldno, _______ void *data ); ____ Prototype in Prototype in ____________ dbase.h Description Description ___________ scdfget gets data from the desired field (fieldno) of scdfget _______ the input buffer. data will be converted from DBaseIII to a more natural data type for 'c': DBaseIII field type returned data type 'C' signed char * 'D' signed char [9] 'L' signed char 'N' double scdfinfo can be used to determine the length of the scdfinfo longest data field in the file. Note that date fields are returned as NULL terminated character strings in the form: "mm/dd/yy", and character fields are returned as NULL terminated character strings. See also See also ________ scdfgets, scdfput, scdfinfo, scdrget. scdfgets scdfput scdfinfo scdrget Return Value Return Value ____________ SC_SUCCESS retrieved data from field SC_BADHNDL .DBF file not open or bad handle SC_BADFLD invalid data record field number Example Example _______ #include "SoftC.h" #include "dbase.h" #include "windows.h" Chapter 7, The SoftC Library 33 33 void main() { char dbf, character[17],logical,date[9]; double numeric; scinit(20,20); if (scdopen(&dbf,"TEST.DBF") == SC_SUCCESS) { scdrget(dbf,1L); scdfgets(dbf,0,character); scdfget(dbf,1,(void *) date); scdfget(dbf,2,(void *) &logical); scdfget(dbf,3,(void *) &numeric); scwprintf("%s %s %c %lf\n", character,date,logical,numeric); scdclose(dbf); } scterm(); } scdfgets scdfgets ________ Usage Usage _____ signed short int scdfgets( signed char handle, scdfgets _______ signed char fieldno, _______ char *data ); ____ Prototype in Prototype in ____________ dbase.h Description Description ___________ scdfgets gets data from the desired field (fieldno) of scdfgets _______ the input buffer. data will be returned as an ASCIIZ ____ string. scdfinfo can be used to determine the length of the scdfinfo longest data field in the file. Note that date fields are returned in the form "yyyymmdd". There is a difference between the date formats of scdfgets and scdfget. scdfgets scdfget 34 Chapter 7, The SoftC Library 34 See also See also ________ scdfget, scdfputs, scdfinfo, scdrget. scdfget scdfputs scdfinfo scdrget Return Value Return Value ____________ SC_SUCCESS retrieved data from field SC_BADHNDL .DBF file not open or bad handle SC_BADFLD invalid data record field number Example Example _______ #include "SoftC.h" #include "dbase.h" #include "windows.h" void main() { char dbf, character[17] = "Hello", logical = 'F', date[9] = "12/25/88"; double numeric = 150.00L; scinit(20,20); if (scdopen(&dbf,"TEST.DBF") == SC_SUCCESS) { scdrget(dbf,1L); scdfgets(dbf,0,character); scdfgets(dbf,1,date); scdfget(dbf,2,(void *) &logical); scdfget(dbf,3,(void *) &numeric); scwprintf("%s %s %c %lf\n", character,date,logical,numeric); scdclose(dbf); } scterm(); } scdfinfo scdfinfo ________ Usage Usage _____ signed short int scdfinfo( signed char handle, scdfinfo ______ signed char *longfldlen, __________ SC_FIELD *fields ); ______ Prototype in Prototype in ____________ dbase.h Chapter 7, The SoftC Library 35 35 Description Description ___________ scdfinfo copies the .DBF field descriptions to fields scdfinfo ______ using the structure SC_FIELD. The length of the longest SC_FIELD data field is also returned (longfldlen). __________ typedef struct { signed char name[11]; /* field name */ signed char type; /* field type */ unsigned char len; /* field length */ unsigned char decpl; /* decimal places */ } SC_FIELD; SC_FIELD The user must ensure that the array defined for fields is large enough to hold all of the field descriptions because scdfinfo blindly copies the descriptions to scdfinfo fields. Severe program errors can be the result if the field array is too small. Use scdrinfo to determine the scdrinfo number of fields in the data record. See also See also ________ scdrinfo scdrinfo Return Value Return Value ____________ SC_SUCCESS returned the field descriptions SC_BADHNDL .DBF file not open or bad handle Example Example _______ #include "SoftC.h" #include "dbase.h" #include "windows.h" void main() { char dbf, longfld, numflds, a; SC_FIELD fields[128]; /* dBaseIII max size */ short reclen; void *ibfr, *obfr; scinit(20,20); if (scdopen(&dbf,"TEST.DBF") == SC_SUCCESS) { scdrinfo(dbf,&reclen,&numflds,&ibfr,&obfr); scdfinfo(dbf,&longfld,fields); scwprintf("longest field length = %d\n",longfld); for (a = 0; a < numflds; a++) scwprintf("%s %c %d %d\n", fields[a].name, fields[a].type, fields[a].len, fields[a].decpl); scdclose(dbf); } 36 Chapter 7, The SoftC Library 36 scterm(); } scdfnam2no scdfnam2no __________ Usage Usage _____ signed short int scdfnam2no( signed char handle, scdfnam2no ______ signed char *fieldname, _________ signed char *fieldno ); _______ Prototype in Prototype in ____________ dbase.h Description Description ___________ scdfnam2no searches through the field description array scdfnam2no for .DBF file handle looking for fieldname. It will _________ return the corresponding field number. Note that .DBF files created by SoftC will have field names changed to all upper case. Return Value Return Value ____________ SC_SUCCESS field number returned SC_BADHNDL .DBF file not open or bad handle SC_BADFLD invalid data record field name Example Example _______ #include "SoftC.h" #include "dbase.h" #include "windows.h" void main() { char dbf, fldno scinit(20,20); if (scdopen(&dbf,"TEST.DBF") == SC_SUCCESS) { scdfnam2no(dbf,"LOGICAL",&fldno); scwprintf("%d",fldno); scdclose(dbf); } Chapter 7, The SoftC Library 37 37 scterm(); } scdfput scdfput _______ Usage Usage _____ signed short int scdfput( signed char handle, scdfput ______ signed char fieldno, _______ void *data ); ____ Prototype in Prototype in ____________ dbase.h Description Description ___________ scdfput will convert data from 'c' format to dBaseIII scdfput ____ format and place it in the proper field (fieldno) of _______ the output buffer. Field numbers begin with zero (0). If the field is numeric, data should be passed as a double. ____ Note that scdfput follows the date formatting standard scdfput of scdfget. It is optional to include the "19" from scdfget "1989" as this is assumed, however the date "2/1/00" will become "19000201" even if you had intended it to be "20000201". Date strings can be formatted as "2/1/2000" to overcome this problem. See also See also ________ scdfget, scdfputs. scdfget scdfputs Return Value Return Value ____________ SC_SUCCESS data placed in field SC_BADHNDL .DBF file not open or bad handle SC_BADFLD invalid data record field number Example Example _______ #include "SoftC.h" #include "dbase.h" 38 Chapter 7, The SoftC Library 38 #include "windows.h" void main() { char dbf, logical = 'T', date[9] = "12/25/88"; long recno; double numeric = 20.0L; scinit(20,20); if (scdopen(&dbf,"TEST.DBF") == SC_SUCCESS) { scdfputs(dbf,0,"SoftC Library "); scdfput(dbf,1,(void *) date); scdfput(dbf,2,(void *) &logical); scdfput(dbf,3,(void *) &numeric); scdrput(dbf,SC_ADD,&recno); scwprintf("Record number = %ld\n",recno); scdclose(dbf); } scterm(); } scdfputs scdfputs ________ Usage Usage _____ signed short int scdfputs( signed char handle, scdfputs ______ signed char fieldno, _______ char *data ); ____ Prototype in Prototype in ____________ dbase.h Description Description ___________ scdfputs will place data in the proper field (fieldno) scdfputs ____ _______ of the output buffer. It is the user's responsibility to provide a properly sized and formatted ASCIIZ string to scdfputs. scdfputs Field numbers begin with zero (0). If the field is numeric, data should be passed as a double. ____ Note that scdfputs follows the date formatting scdfputs conventions of scdfgets. Also be aware that the date scdfgets Chapter 7, The SoftC Library 39 39 formatting conventions of scdfget/scdfput are not the scdfget scdfput same as scdfgets/scdfputs. scdfgets scdfputs See also See also ________ scdfgets, scdfput. scdfgets scdfput Return Value Return Value ____________ SC_SUCCESS data placed in field SC_BADHNDL .DBF file not open or bad handle SC_BADFLD invalid data record field number Example Example _______ #include "SoftC.h" #include "dbase.h" #include "windows.h" void main() { char dbf, logical,date[9]; long recno; double numeric; scinit(20,20); if (scdopen(&dbf,"TEST.DBF") == SC_SUCCESS) { scdfputs(dbf,0,"SoftC Library "); scdfputs(dbf,1, date); scdfput(dbf,2,(void *) &logical); scdfput(dbf,3,(void *) &numeric); scdrput(dbf,SC_ADD,&recno); scwprintf("Record number = %ld\n",recno); scdclose(dbf); } scterm(); } scdinfo scdinfo _______ Usage Usage _____ signed short int scdinfo( signed char handle, scdinfo ______ signed char *filename ); ________ 40 Chapter 7, The SoftC Library 40 Prototype in Prototype in ____________ dbase.h Description Description ___________ scdinfo gets the name of the file associated with scdinfo handle. ______ See also See also ________ scdopen scdopen Return Value Return Value ____________ SC_SUCCESS returned the file name SC_BADHNDL .DBF file not open or bad handle Example Example _______ #include <dir.h> #include "SoftC.h" #include "dbase.h" #include "windows.h" void main() { char dbf; char filename[MAXPATH]; scinit(20,20); if (scdopen(&dbf,"TEST.DBF") == SC_SUCCESS) { scdinfo(dbf,filename); scwprintf("%s",filename); scdclose(dbf); } scterm(); } scdopen scdopen _______ Usage Usage _____ signed short int scdopen( signed char *handle, scdopen ______ signed char *filename ); ________ Chapter 7, The SoftC Library 41 41 Prototype in Prototype in ____________ dbase.h Description Description ___________ scdopen opens a .DBF file. Memory will be allocated for scdopen a file packet and I/O buffers for use internally by the SoftC file manager. Return Value Return Value ____________ SC_SUCCESS file opened and memory allocated SC_MEMERR memory allocation failure SC_NOFILE .DBF file not found SC_RDFAIL disk read failure SC_NODBF file not in .DBF format SC_SKFAIL disk seek failure SC_NOHNDL no SoftC file handles available SC_BADFNAME invalid filename Example Example _______ #include "SoftC.h" #include "dbase.h" void main() { char dbf; scinit(20,20); if (scdopen(&dbf,"TEST.DBF") == SC_SUCCESS) scdclose(dbf); scterm(); } scdrclear scdrclear _________ Usage Usage _____ signed short int scdrclear( signed char handle, scdrclear ______ signed short int buffer ); ______ Prototype in Prototype in ____________ dbase.h 42 Chapter 7, The SoftC Library 42 Description Description ___________ scdrclear clears a .DBF I/O buffer. buffer indicates scdrclear ______ which record buffer to clear. buffer = clears this buffer SC_INPUT input SC_OUTPUT output Return Value Return Value ____________ SC_SUCCESS buffer cleared SC_BADHNDL .DBF file not open or bad handle SC_BADCMD invalid buffer Example Example _______ #include "SoftC.h" #include "dbase.h" #include "windows.h" void main() { char dbf, character[17] = "Hello World!"; scinit(20,20); if (scdopen(&dbf,"TEST.DBF") == SC_SUCCESS) { scdfputs(dbf,0,"SoftC Library "); scdrclear(dbf,SC_INPUT); scdrcopy(dbf,SC_OUTPUT); scdfgets(dbf,0,character); scwprintf("%s\n",character); } scterm(); } scdrcopy scdrcopy ________ Usage Usage _____ signed short int scdrcopy( signed char handle, scdrcopy ______ signed short int buffer ); ______ Prototype in Prototype in ____________ dbase.h Chapter 7, The SoftC Library 43 43 Description Description ___________ scdrcopy copies the contents of one I/O buffer to the scdrcopy other. buffer indicates the direction of the copy. ______ buffer = copies this way SC_INPUT input to output SC_OUTPUT output to input Return Value Return Value ____________ SC_SUCCESS buffer copy SC_BADHNDL .DBF file not open or bad handle SC_BADCMD invalid buffer Example Example _______ #include "SoftC.h" #include "dbase.h" #include "windows.h" void main() { char dbf, character[17] = "Hello World!"; scinit(20,20); if (scdopen(&dbf,"TEST.DBF") == SC_SUCCESS) { scdfputs(dbf,0,"SoftC Library "); scdrclear(dbf,SC_INPUT); scdrcopy(dbf,SC_OUTPUT); scdfgets(dbf,0,character); scwprintf("%s\n",character); scdclose(dbf); } scterm(); } scdrdel scdrdel _______ Usage Usage _____ signed short int scdrdel( signed char handle, scdrdel ______ signed long int recno ); _____ Prototype in Prototype in ____________ dbase.h 44 Chapter 7, The SoftC Library 44 Description Description ___________ scdrdel will flag a record specified by recno as scdrdel _____ 'deleted'. To maintain compatibility with dBaseIII the data record cannot be reused, but it can be 'undeleted' by scdrundel. scdrundel See also See also ________ scdrundel. scdrundel Return Value Return Value ____________ SC_SUCCESS record marked 'deleted' SC_BADHNDL .DBF file not open or bad handle SC_SKFAIL invalid data record number or disk seek failure SC_RDFAIL disk read failure SC_WRTFAIL disk write failure Example Example _______ #include "SoftC.h" #include "dbase.h" #include "windows.h" void main() { char dbf; scinit(20,20); if (scdopen(&dbf,"TEST.DBF") == SC_SUCCESS) { scdrdel(dbf,1L); scdrget(dbf,1L); scwprintf("%s\n",scemsg()); scdclose(dbf); } scterm(); } scdrget scdrget _______ Usage Usage _____ signed short int scdrget( signed char handle, scdrget ______ signed long int recno ); _____ Chapter 7, The SoftC Library 45 45 Prototype in Prototype in ____________ dbase.h Description Description ___________ scdrget will read the data record specified by recno scdrget _____ from the .DBF file associated with handle into the internal input buffer. See also See also ________ scdfget, scdfputs, scdrget. scdfget scdfputs scdrget Return Value Return Value ____________ SC_SUCCESS record read SC_BADHNDL .DBF file not open or bad handle SC_SKFAIL invalid data record number or disk seek failure SC_RDFAIL disk read failure SC_DELREC record read was marked 'deleted' Example Example _______ #include "SoftC.h" #include "dbase.h" #include "windows.h" void main() { char dbf, character[17] = "Hello", logical = 'F', date[9] = "12/25/88"; double numeric = 150.00L; scinit(20,20); if (scdopen(&dbf,"TEST.DBF") == SC_SUCCESS) { scdrget(dbf,1L); scdfgets(dbf,0,character); scdfgets(dbf,1,date); scdfget(dbf,2,(void *) &logical); scdfget(dbf,3,(void *) &numeric); scwprintf("%s %s %c %lf\n", character,date,logical,numeric); scdclose(dbf); } scterm(); } 46 Chapter 7, The SoftC Library 46 scdrinfo scdrinfo ________ Usage Usage _____ signed short int scdrinfo( signed char handle, scdrinfo ______ signed long int *reclen, ______ signed char *numflds, _______ void **ibfr, ____ void **obfr ); ____ Prototype in Prototype in ____________ dbase.h Description Description ___________ scdrinfo gets the data record length (reclen), the scdrinfo ______ number of data fields per record (numflds), and the _______ addresses of the input (ibfr) and output (obfr) ____ ____ buffers. Return Value Return Value ____________ SC_SUCCESS requested information returned SC_BADHNDL .DBF file not open or bad handle Example Example _______ #include "SoftC.h" #include "dbase.h" #include "windows.h" void main() { char dbf, numflds; short reclen; void *ibfr, *obfr; scinit(20,20); if (scdopen(&dbf,"TEST.DBF") == SC_SUCCESS) { scdrinfo(dbf,&reclen,&numflds,&ibfr,&obfr); scwprintf("Record length = %d\n",reclen); scwprintf("Number of fields = %d\n",numflds); scwprintf("I/O buffers = %p %p\n",ibfr,obfr); scdclose(dbf); } scterm(); } Chapter 7, The SoftC Library 47 47 scdrput scdrput _______ Usage Usage _____ signed short int scdrput( signed char handle, scdrput ______ signed short int howto, _____ signed long int *recno ); _____ Prototype in Prototype in ____________ dbase.h Description Description ___________ scdrput will write the data record specified by recno scdrput _____ to the .DBF file associated with handle from the ______ internal output buffer. howto determines how the data _____ record is to be written: howto = action SC_ADD record appended to end of file SC_UPDATE current record updated If a record update is occurring the data record number associated with the record in the input buffer will be returned. An update will not be performed if the input buffer is empty. Use scdrget to load a data record or scdrget scdfput or scdfputs to fill the data record field by scdfput scdfputs field. See also See also ________ scdfput, scdfputs, scdrget. scdfput scdfputs scdrget Return Value Return Value ____________ SC_SUCCESS record read SC_BADHNDL .DBF file not open or bad handle SC_SKFAIL invalid data record number or disk seek failure SC_WRTFAIL disk write failure SC_BADCMD invalid record write command Example Example _______ #include "SoftC.h" #include "dbase.h" #include "windows.h" 48 Chapter 7, The SoftC Library 48 void main() { char dbf, logical = 'T', date[9] = "19881225"; long recno; double numeric = 20.0L; scinit(20,20); if (scdopen(&dbf,"TEST.DBF") == SC_SUCCESS) { scdfputs(dbf,0,"SoftC Library "); scdfput(dbf,1,(void *) date); scdfput(dbf,2,(void *) &logical); scdfput(dbf,3,(void *) &numeric); scdrput(dbf,SC_ADD,&recno); scwprintf("Record number = %ld\n",recno); scdclose(dbf); } scterm(); } scdrundel scdrundel _________ Usage Usage _____ signed short int scdrundel( signed char handle, scdrundel ______ signed long int recno ); _____ Prototype in Prototype in ____________ dbase.h Description Description ___________ scdrundel will remove the 'deleted' flag from the data scdrundel record specified by recno. _____ See also See also ________ scdrdel. scdrdel Return Value Return Value ____________ SC_SUCCESS record recovered SC_BADHNDL .DBF file not open or bad handle SC_SKFAIL invalid data record number or disk seek failure SC_RDFAIL disk read failure SC_WRTFAIL disk write failure Chapter 7, The SoftC Library 49 49 Example Example _______ #include "SoftC.h" #include "dbase.h" #include "windows.h" void main() { char dbf; long recno; scinit(20,20); if (scdopen(&dbf,"TEST.DBF") == SC_SUCCESS) { scdrundel(dbf,1L); scdrget(dbf,1L); scwprintf("%s\n",scemsg()); scdclose(dbf); } scterm(); } scdsize scdsize _______ Usage Usage _____ signed short int scdsize( signed char handle, scdsize ______ signed long int *recsused ); ________ Prototype in Prototype in ____________ dbase.h Description Description ___________ scdsize gets the number of records in the .DBF file. scdsize Return Value Return Value ____________ SC_SUCCESS returned the number of records SC_BADHNDL .DBF file not open or bad handle Example Example _______ #include "SoftC.h" #include "dbase.h" #include "windows.h" 50 Chapter 7, The SoftC Library 50 void main() { char dbf; long recsused; scinit(20,20); if (scdopen(&dbf,"TEST.DBF") == SC_SUCCESS) { scdsize(dbf,&recsused); scwprintf("%ld",recsused); scdclose(dbf); } scterm(); } sceclr sceclr ______ Usage Usage _____ void sceclr( void ); sceclr Prototype in Prototype in ____________ SoftC.h Description Description ___________ sceclr will clear the SoftC library error flag sceclr (sc_code). sc_code See also See also ________ scemsg. scemsg Return Value Return Value ____________ None. Example Example _______ #include "SoftC.h" #include "windows.h" void main() { scinit(20,20); sceclr(); Chapter 7, The SoftC Library 51 51 scterm(); } scemsg scemsg ______ Usage Usage _____ signed char * scemsg( void ); scemsg Prototype in Prototype in ____________ SoftC.h Description Description ___________ scemsg gets the SoftC library error message which scemsg corresponds to the last known error. Warning Codes and Messages: 1 "WARNING - record read is marked deleted", 2 "WARNING - file is empty", 3 "WARNING - no more keys", 4 "WARNING - could not find key in index file" Error Codes and Messages: -1 "ERROR - file write failure", -2 "ERROR - file read failure", -3 "ERROR - memory allocation error", -4 "ERROR - bad user specified field description", -5 "ERROR - file not in .DBF format", -6 "ERROR - file pointer reposition failed", -7 "ERROR - file not found", -8 "ERROR - file corrupted", -9 "ERROR - bad user specified key expression", -10 "ERROR - file not in .NDX format", -11 "ERROR - no handles available", -12 "ERROR - no index pages loaded", -13 "ERROR - index page was not loaded", -14 "ERROR - file close failure", -15 "ERROR - invalid command", -16 "ERROR - invalid handle number", -17 "ERROR - invalid filename", 52 Chapter 7, The SoftC Library 52 -18 "ERROR - invalid offset", -19 "ERROR - bad window coordinates", -20 "ERROR - window is overlaid by another", -21 "ERROR - too many open windows", -22 "ERROR - invalid date" See also See also ________ sceclr. sceclr Return Value Return Value ____________ scemsg returns the error message. scemsg Example Example _______ #include "SoftC.h" #include "windows.h" void main() { scinit(20,20); scwprintf("%s",scemsg()); scterm(); } sciclose sciclose ________ Usage Usage _____ signed short int sciclose( signed char handle ); sciclose ______ Prototype in Prototype in ____________ dbase.h Description Description ___________ sciclose closes an .NDX file and frees all allocated sciclose memory associated with .NDX file. Return Value Return Value ____________ SC_SUCCESS .NDX file closed SC_CLOSFAIL file close failure SC_BADHNDL .NDX file not open or bad handle Chapter 7, The SoftC Library 53 53 Example Example _______ #include "SoftC.h" #include "dbase.h" void main() { char ndx; scinit(20,20); if (sciopen(&ndx,"TEST.NDX") == SC_SUCCESS) sciclose(ndx); scterm(); } scicreate scicreate _________ Usage Usage _____ signed short int scicreate( signed char *filename, scicreate ________ signed char keytype, _______ signed char *keyexpr, _______ signed char keylen ); ______ Prototype in Prototype in ____________ dbase.h Description Description ___________ scicreate creates an .NDX file. keyexpr will be scicreate _______ translated to all upper case when the index file is created. If keytype is 'c', then keyexpr must be a character _______ _______ 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 'n' or 'd', then keyexpr should consist _______ _______ of only one data field. keylen will automatically be ______ set to 8 (numeric and date keys are stored as doubles). 54 Chapter 7, The SoftC Library 54 NOTE: scicreate will create a new .NDX file even if one scicreate had already existed. NOTE: keyexpr is used by dBaseIII. keyexpr is NOT _______ _______ checked for validity by the SoftC data file manager. Currently only the scikmake function uses keyexpr. scikmake _______ See also See also ________ scikmake. scikmake Return Value Return Value ____________ SC_SUCCESS .NDX file created SC_WRTFAIL disk write failure SC_BADEXPR invalid keytype or bad keyexpr SC_NOHNDL no DOS handles available Example Example _______ #include "SoftC.h" #include "dbase.h" void main() { scinit(20,20); scicreate("TEST.NDX",'d',"date",8); scterm(); } sciexpr sciexpr _______ Usage Usage _____ signed short int sciexpr( signed char handle, sciexpr ______ signed char *keyexpr ); _______ Prototype in Prototype in ____________ dbase.h Description Description ___________ sciexpr gets the index key expression and returns it as sciexpr a character string into a user supplied buffer (keyexpr). The user must ensure that the buffer is _______ Chapter 7, The SoftC Library 55 55 large enough (the key expression length can be determined via a call to sciinfo) to hold the entire sciinfo key expression. See also See also ________ sciinfo. sciinfo Return Value Return Value ____________ SC_SUCCESS returned the keyexpr SC_BADHNDL .NDX file not open or bad handle Example Example _______ #include "SoftC.h" #include "dbase.h" #include "windows.h" void main() { char ndx, buffer[512]; scinit(20,20); if (sciopen(&ndx,"TEST.NDX") == SC_SUCCESS) { sciexpr(ndx,buffer); scwprintf("key expression = %s",buffer); sciclose(ndx); } scterm(); } sciinfo sciinfo _______ Usage Usage _____ signed short int sciinfo( signed char handle, sciinfo ______ signed char *filename, ________ signed char *keytype, _______ signed char *keylen, ______ signed short int *exprlen ); _______ Prototype in Prototype in ____________ dbase.h 56 Chapter 7, The SoftC Library 56 Description Description ___________ sciinfo gets the filename of the .NDX file associated sciinfo with handle, the index key type (keytype), the maximum ______ _______ index key length (keylen), and the length of the index ______ key expression (exprlen). _______ See also See also ________ sciopen. sciopen Return Value Return Value ____________ SC_SUCCESS returned .NDX file information SC_BADHNDL .NDX file not open or bad handle Example Example _______ #include <dir.h> #include "SoftC.h" #include "dbase.h" #include "windows.h" void main() { char ndx, filename[MAXPATH], keytype, keylen, exprlen; scinit(20,20); if (sciopen(&ndx,"TEST.NDX") == SC_SUCCESS) { sciinfo(ndx,filename,&keytype,&keylen,&exprlen); scwprintf("File name = %s\n",filename); scwprintf("Index key type = %c\n",keytype); scwprintf("Maximum key length = %d\n",keylen); scwprintf("Key expression length = %d\n",exprlen); sciclose(ndx); } scterm(); } scikadd scikadd _______ Usage Usage _____ signed short int scikadd( signed char handle, scikadd signed char *key, signed long int recno ); Chapter 7, The SoftC Library 57 57 Prototype in Prototype in ____________ dbase.h Description Description ___________ scikadd will add key to the index file specified by scikadd ___ handle. recno is the data record number to be _____ associated with key (the data record pointed to by ___ recno must exist prior to calling scikadd). scikadd Return Value Return Value ____________ SC_SUCCESS key added to .NDX file SC_BADHNDL .NDX file not open or bad handle SC_SKFAIL disk seek failure SC_WRTFAIL disk write failure SC_RDFAIL disk read failure SC_MEMERR memory allocation failure Example Example _______ #include <string.h> #include "SoftC.h" #include "dbase.h" void main() { char dbf, ndx, date[9]; short result; long recno; scinit(20,20); if (scdopen(&dbf,"TEST.DBF") == SC_SUCCESS) { if (sciopen(&ndx,"TEST.NDX") == SC_SUCCESS) { strcpy(date,"19881201"); scdfputs(dbf,1,date); result = scdrput(dbf,SC_ADD,&recno) if (result == SC_SUCCESS) scikadd(ndx,date,recno); sciclose(ndx); } scdclose(dbf) } scterm(); } 58 Chapter 7, The SoftC Library 58 scikcur scikcur _______ Usage Usage _____ signed short int scikcur( signed char handle, scikcur ______ signed char *key, ___ signed long int *recno ); _____ Prototype in Prototype in ____________ dbase.h Description Description ___________ scikcur will return the key value (key) and data record scikcur ___ number (recno) associated with the current key in the _____ index file. The current key pointer must be set by a call to either scikfind, scikfirst, or sciklast before calling scikfind scikfirst sciklast scikcur. scikcur The user must ensure that the buffer used to return the key is long enough to hold the entire key. The maximum length of the key can be determined via a call to sciinfo. sciinfo See also See also ________ sciinfo, scikfind, scikfirst, and sciklast. sciinfo scikfind scikfirst sciklast Return Value Return Value ____________ SC_SUCCESS key and recno returned SC_BADHNDL .NDX file not open or bad handle SC_END no current key - no call to scikfind, scikfind scikfirst, or sciklast had been made to scikfirst sciklast initialize index pointers. SC_RDFAIL read index file failure SC_SKFAIL seek failure (bad record address or seek fail) Example Example _______ #include "SoftC.h" #include "dbase.h" #include "windows.h" void main() Chapter 7, The SoftC Library 59 59 { char ndx, date[9], dat[9]; long recno, rnum; scinit(20,20); if (sciopen(&ndx,"TEST.NDX") == SC_SUCCESS) { date[8] = 0; dat[8] = 0; scikfirst(ndx,date,&recno); scikcur(ndx,dat,&rnum); scwprintf("%s %s %ld %ld\n", date,dat,recno,rnum); sciclose(ndx); } scterm(); } scikdel scikdel _______ Usage Usage _____ signed short int scikdel( signed char handle, scikdel ______ signed char *key, ___ signed long int recno ); _____ Prototype in Prototype in ____________ dbase.h Description Description ___________ scikdel will remove key from the index file specified scikdel ___ by handle. recno is used along with key to ensure that ______ _____ the proper key has been removed from the .NDX file. Return Value Return Value ____________ SC_SUCCESS key removed from .NDX file SC_BADHNDL .NDX file not open or bad handle SC_SKFAIL disk seek failure SC_WRTFAIL disk write failure SC_RDFAIL index file read failure SC_EMPTY index file is empty - no keys found SC_NOFIND desired key was not found 60 Chapter 7, The SoftC Library 60 Example Example _______ #include <string.h> #include "SoftC.h" #include "dbase.h" void main() { char ndx, date[9]; long recno; scinit(20,20); if (sciopen(&ndx,"TEST.NDX") == SC_SUCCESS) { strcpy(date,"19881202"); recno = 7L; scikdel(ndx,date,recno); sciclose(ndx); } scterm(); } scikfind scikfind ________ Usage Usage _____ signed short int scikfind( signed char handle, scikfind ______ signed char method, ______ signed char *key, ___ signed long int *recno ); _____ Prototype in Prototype in ____________ dbase.h Description Description ___________ need to explain the two methods of key searching. scikfind searches through the .NDX file looking for a scikfind key and data record number match with key and recno. If ___ _____ an exact 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. ___ _____ Chapter 7, The SoftC Library 61 61 The user must ensure that the buffer used to return the key is long enough to hold the entire key. The maximum length of the key can be determined via a call to sciinfo. sciinfo See also See also ________ sciinfo. sciinfo Return Value Return Value ____________ SC_SUCCESS key found SC_NOFIND key not found SC_EMPTY .NDX file empty - no keys found SC_BADHNDL .NDX file not open or bad handle SC_SKFAIL seek failure (bad record address or seek fail) SC_RDFAIL read index file failure SC_END end of index file Example Example _______ #include <string.h> #include "SoftC.h" #include "dbase.h" #include "windows.h" void main() { char ndx, key[100]; long recno; int result; scinit(20,20); if (sciopen(&ndx,"TEST.NDX") == SC_SUCCESS) { strcpy(date,"19881202"); recno = 7L; scikfind(ndx,SC_EXACT,date,&recno); scwprintf("%s\n",scemsg()); scdclose(ndx); } scterm(); } 62 Chapter 7, The SoftC Library 62 scikfirst scikfirst _________ Usage Usage _____ signed short int scikfirst( signed char handle, scikfirst ______ signed char *key, ___ signed long int *recno ); _____ Prototype in Prototype in ____________ dbase.h Description Description ___________ scikfirst will set the current key pointer to the first scikfirst logical key in the .NDX and return the key value (key) ___ and data record number (recno) associated with the new _____ current key. The user must ensure that the buffer used to return the key is long enough to hold the entire key. The maximum length of the key can be determined via a call to sciinfo. sciinfo See also See also ________ sciinfo sciinfo Return Value Return Value ____________ SC_SUCCESS key and recno returned SC_BADHNDL .NDX file not open or bad handle SC_EMPTY .NDX file empty - no keys found SC_SKFAIL seek failure SC_RDFAIL read index file failure Example Example _______ #include "SoftC.h" #include "dbase.h" #include "windows.h" void main() { char ndx, date[9]; long recno; scinit(20,20); if (sciopen(&ndx,"TEST.NDX") == SC_SUCCESS) { date[8] = 0; Chapter 7, The SoftC Library 63 63 scikfirst(ndx,date,&recno); scwprintf("%d %ld\n",date,recno); sciclose(ndx); } scterm(); } sciklast sciklast ________ Usage Usage _____ signed short int sciklast( signed char handle, sciklast ______ signed char *key, ___ signed long int *recno ); _____ Prototype in Prototype in ____________ dbase.h Description Description ___________ sciklast will set the current key pointer to the last sciklast logical key in the .NDX and return the key value (key) ___ and data record number (recno) associated with the new _____ current key. The user must ensure that the buffer used to return the key is long enough to hold the entire key. The maximum length of the key can be determined via a call to sciinfo. sciinfo See also See also ________ sciinfo. sciinfo Return Value Return Value ____________ SC_SUCCESS key and recno returned SC_BADHNDL .NDX file not open or bad handle SC_EMPTY .NDX file empty - no keys found SC_SKFAIL seek failure SC_RDFAIL read from index file failure 64 Chapter 7, The SoftC Library 64 Example Example _______ #include "SoftC.h" #include "dbase.h" #include "windows.h" void main() { char ndx, date[9]; long recno; scinit(20,20); if (sciopen(&ndx,"TEST.NDX") == SC_SUCCESS) { date[8] = 0; sciklast(ndx,date,&recno); scwprintf("%s %ld\n",date,recno); sciclose(ndx); } scterm(); } scikmake scikmake ________ Usage Usage _____ signed short int scikmake( signed char datahandle, scikmake __________ signed char indexhandle, ___________ void ** key ); ___ Prototype in Prototype in ____________ dbase.h Description Description ___________ scikmake will build an index key using the key scikmake expression of the index file specified by indexhandle ___________ and the data found in the output buffer of the data file of 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 dBaseIII functions or a combination thereof. Data field types of date, numeric, or character are allowed. dBaseIII functions dtoc, left, dtoc left Chapter 7, The SoftC Library 65 65 right, str, and substr are current supported by right str substr scikmake. scikmake dBaseIII supports only two types of keys: character and numeric. The only numeric keys supported by SoftC are just the date and numeric data field names. dtoc will convert data from a date field to a character dtoc string of the format mm/dd/yy. Syntax is dtoc(field_name). left will return the left portion of a character field left as a 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 right field as a 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,count). str will convert a numeric field to an ascii string. str 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 substr 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 scikmake to create an index scikmake key string consisting of the year and month ("yymm"). For example if date equals "2/13/89" the resultant key would be "8902". 66 Chapter 7, The SoftC Library 66 Note that for key expressions consisting of only one data field scikmake is probably an overkill. You can scikmake easily generate these keys yourself. scikmake is a scikmake fairly large module and if not needed probably should not be used. This function is best used when the key expression is more complex. See also See also ________ scicreate. scicreate Return Value Return Value ____________ SC_SUCCESS key and recno returned SC_BADHNDL .NDX file not open or bad handle SC_MEMERR memory allocation failure SC_BADEXPR invalid key expression Example Example _______ #include "SoftC.h" #include "dbase.h" #include "windows.h" void main() { char ndx, dbf, char *key, date[9]; long recno; scinit(20,20); if (scdopen(&dbf,"TEST.DBF") == SC_SUCCESS) { if (sciopen(&ndx,"TEST.NDX") == SC_SUCCESS) { scdfput(dbf,0,&date); scdrput(dbf,SC_ADD,&recno); scikmake(dbf,ndx,(void **) &key); scikadd(ndx,key,recno); free(key); sciclose(ndx); } scdclose(dbf); } scterm(); } Chapter 7, The SoftC Library 67 67 sciknext sciknext ________ Usage Usage _____ signed short int sciknext( signed char handle, sciknext ______ signed char *key, ___ signed long int *recno ); _____ Prototype in Prototype in ____________ dbase.h Description Description ___________ sciknext will increment the key pointer and return the sciknext key value (key) and data record number (recno) ___ _____ associated with the new current key. The current key pointer must be set by a call to either scikfind, scikfirst, or sciklast before calling scikfind scikfirst sciklast sciknext. sciknext The user must ensure that the buffer used to return the key is long enough to hold the entire key. The maximum length of the key can be determined via a call to sciinfo. sciinfo See also See also ________ sciinfo, scikfind, scikfirst, and sciklast. sciinfo scikfind scikfirst sciklast Return Value Return Value ____________ SC_SUCCESS key and recno returned SC_BADHNDL .NDX file not open or bad handle SC_END no more keys - at end of .NDX file SC_RDFAIL index file read failure SC_SKFAIL seek failure (bad record address or seek failed) Example Example _______ #include "SoftC.h" #include "dbase.h" #include "windows.h" void main() { char ndx, date[9]; 68 Chapter 7, The SoftC Library 68 long recno; scinit(20,20); if (sciopen(&ndx,"TEST.NDX") == SC_SUCCESS) { scikfirst(ndx,date,&recno); sciknext(ndx,date,&recno); scwprintf("%s %ld\n",date,recno); sciclose(ndx); } scterm(); } scikprev scikprev ________ Usage Usage _____ signed short int scikprev( signed char handle, scikprev ______ signed char *key, ___ signed long int *recno ); _____ Prototype in Prototype in ____________ dbase.h Description Description ___________ scikprev will decrement the key pointer and return the scikprev key value (key) and data record number (recno) ___ _____ associated with the new current key. The current key pointer must be set by a call to either scikfind, scikfirst, or sciklast before calling scikfind scikfirst sciklast scikprev. scikprev The user must ensure that the buffer used to return the key is long enough to hold the entire key. The maximum length of the key can be determined via a call to sciinfo. sciinfo See also See also ________ sciinfo, scikfind, scikfirst, and sciklast. sciinfo scikfind scikfirst sciklast Return Value Return Value ____________ SC_SUCCESS key and recno returned Chapter 7, The SoftC Library 69 69 SC_BADHNDL .NDX file not open or bad handle SC_END no more keys - at end of .NDX file SC_RDFAIL index file read failure SC_SKFAIL index file record seek failure Example Example _______ #include "SoftC.h" #include "dbase.h" #include "windows.h" void main() { char ndx, date[9]; long recno; scinit(20,20); if (sciopen(&ndx,"TEST.NDX") == SC_SUCCESS) { sciklast(ndx,date,&recno); scikprev(ndx,date,&recno); scwprintf("%s %ld\n",date,recno); sciclose(ndx); } scterm(); } scinit scinit ______ Usage Usage _____ signed short int scinit( signed char files, scinit _____ signed char windows ); _______ Prototype in Prototype in ____________ SoftC.h Description Description ___________ scinit is called once and only once at the beginning of scinit the program. The maximum numbers of simultaneously open files and windows are passed. This function sets up the _____ _______ SoftC environment for processing. Memory will be allocated for a variety of control structures used internally by the SoftC manager. 70 Chapter 7, The SoftC Library 70 See also See also ________ scterm. scterm Return Value Return Value ____________ SC_SUCCESS completed initialization SC_MEMERR memory allocation failure SC_BADHNDL invalid number of handles Example Example _______ #include "SoftC.h" void main() { scinit(20,20); scterm(); } sciopen sciopen _______ Usage Usage _____ signed short int sciopen( signed char *handle, sciopen ______ signed char *filename ); ________ Prototype in Prototype in ____________ dbase.h Description Description ___________ sciopen opens an .NDX file. Memory will be allocated sciopen for a file packet, I/O buffers, and other miscellaneous structures for use internally by the SoftC file manager. Return Value Return Value ____________ SC_SUCCESS .NDX file opened SC_MEMERR memory allocation failure SC_NOFILE .NDX file not found SC_RDFAIL disk read failure SC_NONDX file not in .NDX format SC_SKFAIL disk seek failure SC_NOHNDL no SoftC handles available SC_BADFNAME invalid filename Chapter 7, The SoftC Library 71 71 Example Example _______ #include "SoftC.h" #include "dbase.h" void main() { char ndx; scinit(20,20); if (sciopen(&ndx,"UNKNOWN.NDX") == SC_SUCCESS) { sciclose(ndx); } scterm(); } scipinfo scipinfo ________ Usage Usage _____ signed short int scipinfo( signed char handle, scipinfo ______ signed char *numpgs ); Prototype in Prototype in ____________ dbase.h Description Description ___________ scipinfo gets the maximum number of index pages the scipinfo SoftC file manager can keep in memory and returns it via numpgs. Return Value Return Value ____________ SC_SUCCESS max number of pages allowed returned SC_BADHNDL .NDX file not open or bad handle Example Example _______ #include "SoftC.h" #include "dbase.h" #include "windows.h" void main() { char ndx, numpgs; 72 Chapter 7, The SoftC Library 72 scinit(20,20); if (sciopen(&ndx,"TEST.NDX") == SC_SUCCESS) { scipinfo(ndx,&numpgs) == SC_SUCCESS) scwprintf("Maximum number of pages = %d\n",numpgs); sciclose(ndx); } scterm(); } scipnum scipnum _______ Usage Usage _____ signed short int scipnum( signed char handle, scipnum ______ signed char *numpgs ); ______ Prototype in Prototype in ____________ dbase.h Description Description ___________ scipnum sets the maximum number of index pages (numpgs) scipnum ______ the SoftC file manager can keep in memory. Memory for index pages will be freed or allocated as appropriate. Return Value Return Value ____________ SC_SUCCESS new max number of pages allowed returned SC_BADHNDL .NDX file was open or bad handle SC_BADCMD invalid new number of pages requested Example Example _______ #include "SoftC.h" #include "dbase.h" #include "windows.h" void main() { char ndx, numpgs = 5; scinit(20,20); if (sciopen(&ndx,"TEST.NDX") == SC_SUCCESS) { scipnum(ndx,&numpgs); scipinfo(ndx,&numpgs); Chapter 7, The SoftC Library 73 73 scwprintf("New max = %d\n",numpgs); sciclose(ndx); } scterm(); } scterm scterm ______ Usage Usage _____ void scterm( void ); scterm Prototype in Prototype in ____________ SoftC.h Description Description ___________ scterm is called once at the end of the program. Memory scterm allocated by scinit for internal control structures scinit will be freed. All files and windows open will be closed and any memory allocated for them will be freed. See also See also ________ scinit. scinit Return Value Return Value ____________ SC_SUCCESS completed initialization Example Example _______ #include "SoftC.h" void main() { scinit(20,20); scterm(); } 74 Chapter 7, The SoftC Library 74 scvers scvers ______ Usage Usage _____ signed char * scvers( void ); scvers Prototype in Prototype in ____________ SoftC.h Description Description ___________ scvers gets the SoftC library revision in the form of a scvers character string. Return Value Return Value ____________ scvers returns the library revision. scvers Example Example _______ #include "SoftC.h" #include "windows.h" void main() { scinit(20,20); scwprintf("SoftC Library Revision %s",scvers()); scterm(); } scwaget scwaget _______ Usage Usage _____ void scwaget( unsigned char *foreground, scwaget __________ unsigned char *background ); __________ Prototype in Prototype in ____________ windows.h Chapter 7, The SoftC Library 75 75 Description Description ___________ scwaget gets the current text foreground and background scwaget __________ __________ color attributes. See also See also ________ scwaput. scwaput Return Value Return Value ____________ None. Example Example _______ #include "SoftC.h" #include "windows.h" void main() { unsigned char foreground,background; scinit(20,20); scwaget(&foreground,&background); scwprintf("%d %d",foreground,background); scterm(); } scwaput scwaput _______ Usage Usage _____ void scwaput( unsigned char foreground, scwaput __________ unsigned char background ); __________ Prototype in Prototype in ____________ windows.h Description Description ___________ scwaput sets the text foreground and background color scwaput __________ __________ attributes. See also See also ________ scwaget. scwaget 76 Chapter 7, The SoftC Library 76 Return Value Return Value ____________ None. Example Example _______ #include <conio.h> #include "SoftC.h" #include "windows.h" void main() { scinit(20,20); /* blinking yellow on black */ scwaput(YELLOW + BLINK,BLACK); scwputs("Hello world!"); scterm(); } scwbget scwbget _______ Usage Usage _____ signed short int scwbget( signed char offset, scwbget ______ unsigned char *uplft, _____ unsigned char *uprght, ______ unsigned char *lowlft, ______ unsigned char *lowrght, _______ unsigned char *horiz, _____ unsigned char *vert ); ____ Prototype in Prototype in ____________ windows.h Description Description ___________ scwbget is used to retrieve window border style scwbget information. This is where each border character will be displayed in relation to the other border characters of this style: Chapter 7, The SoftC Library 77 77 uplft horiz uprght vert vert lowlft horiz lowrght There are four (4) predefined border styles: ┌───┐ ╔═══╗ ╒═══╕ ╓───╖ │ 0 │ ║ 1 ║ │ 2 │ ║ 3 ║ └───┘ ╚═══╝ ╘═══╛ ╙───╜ There is only room for four styles in the array, if a different style is desired one of the default styles will have to be overwritten using scwbput. scwbput Border style zero (0) is the default style for scwopen. scwopen The characters found in style zero will always be used by scwopen. These characters can easily be changed by scwopen scwbput scwbput See also See also ________ scwbput. scwbput Return Value Return Value ____________ SC_SUCCESS record recovered SC_BADOFS invalid border array offset Example Example _______ #include "SoftC.h" #include "windows.h" void main() { unsigned char ul,ur,ll,lr,h,v; scinit(20,20); /* changes the default window border style */ scwbget(3,&ul,&ur,&ll,&lr,&h,&v); scwbput(0,ul,ur,ll,lr,h,v); scterm(); } 78 Chapter 7, The SoftC Library 78 scwbput scwbput _______ Usage Usage _____ signed short int scwbput( signed char offset, scwbput ______ unsigned char uplft, _____ unsigned char uprght, ______ unsigned char lowlft, ______ unsigned char lowrght, _______ unsigned char horiz, _____ unsigned char vert ); ____ Prototype in Prototype in ____________ windows.h Description Description ___________ scwbput is used to redefine a window border style. The scwbput six characters to be used when drawing a window outline are supplied along with an index into the window border array. This is where each character will be displayed in relation to the other new border style characters: uplft horiz uprght vert vert lowlft horiz lowrght See also See also ________ scwbget. scwbget Return Value Return Value ____________ SC_SUCCESS record recovered SC_BADOFS invalid border array offset Example Example _______ #include "SoftC.h" #include "windows.h" void main() { unsigned char ul,ur,ll,lr,h,v; scinit(20,20); Chapter 7, The SoftC Library 79 79 /* changes the default window border style */ scwbget(3,&ul,&ur,&ll,&lr,&h,&v); scwbput(0,ul,ur,ll,lr,h,v); scterm(); } scwcget scwcget _______ Usage Usage _____ signed short int scwcget( signed char offset, scwcget ______ unsigned char *hfore, _____ unsigned char *hback, _____ unsigned char *bfore, _____ unsigned char *bback, _____ unsigned char *tfore, _____ unsigned char *tback); _____ Prototype in Prototype in ____________ windows.h Description Description ___________ scwcget is used to retrieve window color scheme scwcget information. Three pairs of color information will be returned: title foreground (hfore) and background _____ (hback), border foreground (bfore) and background _____ _____ (bback), and text foreground (tfore) and background _____ _____ (tback) colors. _____ There are ten (10) predefined window color schemes: Scheme 0: Title: Light Gray on Blue. Border: Light Gray on Blue. Text: Light Gray on Blue. Scheme 1: Title: Light Gray on Green. Border: Light Gray on Green. Text: Light Gray on Green. 80 Chapter 7, The SoftC Library 80 Scheme 2: Title: Light Gray on Red. Border: Light Gray on Red. Text: Light Gray on Red. Scheme 3: Title: White on Black. Border: White on Black. Text: White on Black. Scheme 4: Title: Blue on Black. Border: Blue on Black. Text: Blue on Black. Scheme 5: Title: Green on Black. Border: Green on Black. Text: Green on Black. Scheme 6: Title: Cyan on Black. Border: Cyan on Black. Text: Cyan on Black. Scheme 7: Title: Red on Black. Border: Red on Black. Text: Red on Black. Scheme 8: Title: Magenta on Black. Border: Magenta on Black. Text: Magenta on Black. Scheme 9: Title: Brown on Black. Border: Brown on Black. Text: Brown on Black. If scinit senses a monochrome monitor the entire color scinit table will be written to all yellow foreground on black background. Chapter 7, The SoftC Library 81 81 There is only room for ten schemes in the array, if a different one is desired one of the default schemes will have to be overwritten using scwcput. scwcput Color scheme zero (0) is the default scheme for scwopen. The colors found in scheme zero will always be scwopen used by scwopen. These colors can easily be changed by scwopen scwcput. scwcput See also See also ________ scwcput. scwcput Return Value Return Value ____________ SC_SUCCESS record recovered SC_BADOFS invalid border array offset Example Example _______ #include "SoftC.h" #include "windows.h" void main() { unsigned char hf,hb,bf,bb,tf,tb; scinit(20,20); /* changes the default window color scheme */ scwcget(3,&hf,&hb,&bf,&bb,&tf,&tb); scwcput(0,hf,hb,bf,bb,tf,tb); scterm(); } scwclose scwclose ________ Usage Usage _____ signed short int scwclose( signed char handle ); scwclose ______ Prototype in Prototype in ____________ windows.h 82 Chapter 7, The SoftC Library 82 Description Description ___________ scwclose closes a window and frees all allocated memory scwclose associated with that window. Actual screen information overlaid by window will be restored. If the window attempting to be closed is overlaid by another window the close will be ignored and an error will be returned. If the current window is being closed, the window opened (or selected) just prior to this window will be selected. If no other windows remain to be selected, the entire screen will be selected. See also See also ________ scwopen, scwopenx, scwselect. scwopen scwopenx scwselect Return Value Return Value ____________ SC_SUCCESS window file closed SC_BADHNDL invalid window handle SC_WINOVRLAD window is overlaid by another Example Example _______ #include "SoftC.h" #include "windows.h" void main() { char win; scinit(20,20); if (scwopen(&win,5,5,20,1) == SC_SUCCESS) { scwputs("Hello world!"); scwclose(win); } scterm(); } Chapter 7, The SoftC Library 83 83 scwclr scwclr ______ Usage Usage _____ void scwclr( void ); scwclr Prototype in Prototype in ____________ windows.h Description Description ___________ scwclr clears the currently selected window (or, if no scwclr windows are open, the entire screen). The cursor will be moved to the upper left corner of the window (screen). See also See also ________ scwclreol. scwclreol Return Value Return Value ____________ None. Example Example _______ #include "SoftC.h" #include "windows.h" void main() { scinit(20,20); scwclr(); scwputs("Hello world!"); scterm(); } scwclreol scwclreol _________ Usage Usage _____ void scwclreol( void ); scwclreol 84 Chapter 7, The SoftC Library 84 Prototype in Prototype in ____________ windows.h Description Description ___________ scwclreol clears from the current cursor position to scwclreol the end of the current line. If a window is open, it will clear to the edge of the window. The cursor will not be advanced. See also See also ________ scwclr. scwclr Return Value Return Value ____________ None. Example Example _______ #include "SoftC.h" #include "windows.h" void main() { scinit(20,20); scwputs("Hello world!"); scwgoto(6,1); scwclreol(); scterm(); } scwcput scwcput _______ Usage Usage _____ signed short int scwcput( signed char offset, scwcput ______ unsigned char hfore, _____ unsigned char hback, _____ unsigned char bfore, _____ unsigned char bback, _____ unsigned char tfore, _____ unsigned char tback); _____ Prototype in Prototype in ____________ windows.h Chapter 7, The SoftC Library 85 85 Description Description ___________ scwcput is used to redefine a window color scheme. scwcput Three pairs of color information will be returned: title foreground (hfore) and background (hback), border _____ _____ foreground (bfore) and background (bback), and text _____ _____ foreground (tfore) and background (tback) colors. _____ _____ See also See also ________ scwcget. scwcget Return Value Return Value ____________ SC_SUCCESS record recovered SC_BADOFS invalid border array offset Example Example _______ #include "SoftC.h" #include "windows.h" void main() { unsigned char ul,ur,ll,lr,h,v; scinit(20,20); /* changes the default window color scheme */ scwcget(3,&hf,&hb,&bf,&bb,&tf,&tb); scwcput(0,hf,hb,bf,bb,tf,tb); scterm(); } scwcursoff scwcursoff __________ Usage Usage _____ void scwcursoff( void ); scwcursoff Prototype in Prototype in ____________ windows.h Description Description ___________ scwcursoff will turn off the blinking cursor. It does scwcursoff not affect the cursor positioning (scwgoto) or any of scwgoto the window printing functions. 86 Chapter 7, The SoftC Library 86 See also See also ________ scwcurson. scwcurson Return Value Return Value ____________ None. Example Example _______ #include "SoftC.h" #include "windows.h" void main() { scinit(1,1); scwcursoff(); scwprintf("Hello"); scwcurson(); scterm(); } scwcurso scwcurso ________ Usage Usage _____ void scwcurson( void ); scwcurson Prototype in Prototype in ____________ windows.h Description Description ___________ scwcurson will turn on the blinking cursor. It does not scwcurson affect the cursor positioning (scwgoto) or any of the scwgoto window printing functions. See also See also ________ scwcursoff. scwcursoff Return Value Return Value ____________ None. Chapter 7, The SoftC Library 87 87 Example Example _______ #include "SoftC.h" #include "windows.h" void main() { scinit(1,1); scwcursoff(); scwprintf("Hello"); scwcurson(); scterm(); } scwgoto scwgoto _______ Usage Usage _____ signed short int scwgoto( unsigned short int x, scwgoto _ unsigned short int y ); _ Prototype in Prototype in ____________ windows.h Description Description ___________ scwgoto moves the cursor to the desired position within scwgoto the current window (or screen if no windows are open). If the coordinates are invalid the call will be ignored. The upper left corner of the window is column 1 (x), _ row 1 (y). _ See also See also ________ scwxloc, scwyloc. scwxloc scwyloc Return Value Return Value ____________ SC_SUCCESS record recovered SC_BADCOORDS invalid window coordinates 88 Chapter 7, The SoftC Library 88 Example Example _______ #include "SoftC.h" #include "windows.h" void main() { scinit(20,20); scwgoto(10,20); scterm(); } scwinfo scwinfo _______ Usage Usage _____ signed short int scwinfo( signed char handle, scwinfo ______ unsigned short int *left, ____ unsigned short int *top, ___ unsigned short int *width, _____ unsigned short int *height, ______ signed char *hlen, ____ signed char *color, _____ signed char *border ); ______ Prototype in Prototype in ____________ windows.h Description Description ___________ scwinfo returns the parameters used to open the window. scwinfo The coordinates of the upper left hand corner of the window (left, top), the width and height of the window, ____ ___ _____ ______ the window title length (hlen), color scheme (color is ____ _____ an index into the color scheme table), and border style (border is an index into the border style table) will ______ be returned. See also See also ________ scwopen, scwopenx. scwopen scwopenx Return Value Return Value ____________ SC_SUCCESS window opened and memory allocated SC_BADHNDL too many open windows Chapter 7, The SoftC Library 89 89 Example Example _______ #include "SoftC.h" #include "windows.h" void main() { char win,hdrl,b,c; int l,t,w,h; scinit(20,20); scwopenx(&win,5,5,20,1,NULL,3,-1); scwinfo(win,&l,&t,&w,&h,hdrl,&b,&c); scwprintf("%u %u %u %u %d %d %d", l,t,w,h,hdrl,b,c); scwclose(win); scterm(); } scwopen scwopen _______ Usage Usage _____ signed short int scwopen( signed char *handle, scwopen ______ unsigned short int left, ____ unsigned short int top, ___ unsigned short int width, _____ unsigned short int height ); ______ Prototype in Prototype in ____________ windows.h Description Description ___________ scwopen opens a window on the screen. Memory will be scwopen allocated for a window packet and screen image buffer for use internally by the SoftC window manager. The window border will be drawn using border style zero. The colors used in the window will be defined by color style zero. The window will be cleared and the cursor moved to the upper left corner (of the window). Upon exit the new window will be the current window. 90 Chapter 7, The SoftC Library 90 A copy of the original screen overlaid by the new window will be kept. See also See also ________ scwclose, scwbget, scwcget. scwclose scwbget scwcget Return Value Return Value ____________ SC_SUCCESS window opened and memory allocated SC_MEMERR memory allocation failure SC_BADCOORDS invalid screen coordinates SC_NOHNDL too many open windows SC_BADOFS invalid color or border array offset Example Example _______ #include "SoftC.h" #include "windows.h" void main() { char win; scinit(20,20); if (scwopen(&win,5,5,20,1) == SC_SUCCESS) { scwputs("Hello world!"); scwclose(win); } scterm(); } scwopenx scwopenx ________ Usage Usage _____ signed short int scwopenx( signed char *handle, scwopenx ______ unsigned short int left, ____ unsigned short int top, ___ unsigned short int width, _____ unsigned short int height, ______ signed char *header, ______ signed char color, _____ signed char border ); ______ Chapter 7, The SoftC Library 91 91 Prototype in Prototype in ____________ windows.h Description Description ___________ scwopenx is an extended version of scwopen. This scwopenx scwopen function allows the user to specify a window title (header) and gives control over window colors (color is ______ _____ an index into the window color table) and border styles (border is an index into the border style table). ______ One option available under .i.scwopenx; is to specify that no window border should be drawn when opening a window. By using a minus one (-1) for the border ______ parameter a borderless window will be opened. See also See also ________ scwopen. scwopen Return Value Return Value ____________ SC_SUCCESS window opened and memory allocated SC_MEMERR memory allocation failure SC_BADCOORDS invalid screen coordinates SC_NOHNDL too many open windows SC_BADOFS invalid color or border array offset Example Example _______ #include "SoftC.h" #include "windows.h" void main() { char win; scinit(20,20); /* open a window with no border */ if (scwopenx(&win,5,5,20,1,NULL,3,-1) == SC_SUCCESS) { scwputs("Hello world!"); scwclose(win); } scterm(); } 92 Chapter 7, The SoftC Library 92 scwprintf scwprintf _________ Usage Usage _____ void scwprintf( signed char *format[, argument, ...] ); scwprintf ______ ________ Prototype in Prototype in ____________ windows.h Description Description ___________ scwprintf functions the same as the printf function scwprintf printf found in your compiler. It accepts an optional series of arguments (argument), applies to each a format ________ specification found in the string pointed to by format, ______ and outputs the formatted data to an internal data buffer. This data buffer is then output to the current window. See the description of printf in your compiler printf manual for more information. Note that if no window is open the text string will be output to the current cursor position on the screen. Because this function uses sprintf to first build an sprintf output string in an internal data buffer, care must be exercised by the user to supply a format descriptor ______ which when processed will result in a string no longer than 256 characters (including terminating NULL bytes). The cursor position will be updated. Any newline (\n) characters found in string will be translated into a carriage return - line feed (\r\n) sequence. See also See also ________ scwputc, scwputs. scwputc scwputs Return Value Return Value ____________ None. Example Example _______ #include "SoftC.h" #include "windows.h" Chapter 7, The SoftC Library 93 93 void main() { scinit(20,20); scwprintf("Hello world!"); scterm(); } scwputc scwputc _______ Usage Usage _____ void scwputc( signed char ch ); scwputc __ Prototype in Prototype in ____________ windows.h Description Description ___________ scwputc will put a single character out to the current scwputc window. The cursor position will be updated. The newline (\n) character is translated into a carriage return - line feed (\r\n) sequence. scwputc is implemented as a macro: scwputc scwprintf("%c",ch); scwprintf See also See also ________ scwprintf, scwputs. scwprintf scwputs Return Value Return Value ____________ None. Example Example _______ #include "SoftC.h" #include "windows.h" void main() { 94 Chapter 7, The SoftC Library 94 scinit(20,20); scwputc('H'); scterm(); } scwputs scwputs _______ Usage Usage _____ void scwputs( signed char *string ); scwputs ______ Prototype in Prototype in ____________ windows.h Description Description ___________ scwputs will put a NULL terminated string out to the scwputs ______ current window. The cursor position will be updated. Unlike most compiler's puts functions, a newline (\n) puts character is not appended to string. Any newline characters found in string will be translated into a carriage return - line feed (\r\n) sequence. scwputs is implemented as a macro: scwputs scwprintf("%s",string); scwprintf See also See also ________ scwprintf, scwputc. scwprintf scwputc Return Value Return Value ____________ None. Example Example _______ #include "SoftC.h" #include "windows.h" void main() Chapter 7, The SoftC Library 95 95 { scinit(20,20); scwputs("Hello world!"); scterm(); } scwselect scwselect _________ Usage Usage _____ unsigned short int scwselect( signed char handle ); scwselect ______ Prototype in Prototype in ____________ windows.h Description Description ___________ scwselect makes the window specified by handle the scwselect ______ current window. The current cursor x,y position in the previously selected window will be saved. The window specified by handle is selected and the cursor is restored to its previous location. Note that if the window attempting to be selected is overlaid by another window the call will be ignored. See also See also ________ scwopen. scwopen Return Value Return Value ____________ SC_SUCCESS window selected SC_BADHNDL invalid window handle SC_WINOVRLAD window is overlaid by another Example Example _______ #include "SoftC.h" #include "windows.h" void main() { signed char win, win2; 96 Chapter 7, The SoftC Library 96 scinit(20,20); scwopenx(&win,5,5,20,2,"Window One",0,0); scwputs("Hello world!"); scwopenx(&win2,1,10,60,5,"Window Two",1,1); scwputs("Hello world!"); scwselect(win); scwputs("I am back."); scwclose(win); scwclose(win2); scterm(); } scwtget scwtget _______ Usage Usage _____ signed short int scwtget( signed char *header ); scwtget ______ Prototype in Prototype in ____________ windows.h Description Description ___________ scwtget is used to get the title text string from the scwtget current window. scwinfo can be used to find the length scwinfo of the window title string. A NULL will be returned in header if there is no title or the length of the title ______ is zero. See also See also ________ scwtput. scwtput Return Value Return Value ____________ SC_SUCCESS record recovered SC_BADHDNL no window is open Example Example _______ #include "SoftC.h" #include "windows.h" void main() { Chapter 7, The SoftC Library 97 97 char win, h[81]; scinit(20,20); scwopenx(&win,2,2,20,5,"Title",0,0); scwtget(&h); scwputs(h); scwclose(win); scterm(); } scwtput scwtput _______ Usage Usage _____ signed short int scwtput( signed char *header); scwtput ______ Prototype in Prototype in ____________ windows.h Description Description ___________ scwtput is used to write a new title on an the current scwtput window. Memory will be allocated for the new title message and the old title will be freed. See also See also ________ scwtget. scwtget Return Value Return Value ____________ SC_SUCCESS record recovered SC_BADHNDL no window is open SC_MEMERR memory allocation failure Example Example _______ #include "SoftC.h" #include "windows.h" void main() { char win; scinit(20,20); scwopenx(&win,2,2,20,5,"Title",0,0); 98 Chapter 7, The SoftC Library 98 scwtput("Header"); scwclose(win); scterm(); } scwxloc scwxloc _______ Usage Usage _____ unsigned short int scwxloc( void ); scwxloc Prototype in Prototype in ____________ windows.h Description Description ___________ scwxloc returns the x coordinate (column number) of the scwxloc current cursor position within the selected window. See also See also ________ scwgoto, scwyloc. scwgoto scwyloc Return Value Return Value ____________ None. Example Example _______ #include "SoftC.h" #include "windows.h" void main() { unsigned short int x,y; scinit(20,20); scwputs("Hello world!"); x = scwxloc(); y = scwyloc(); scwgoto(1,1); scwprintf("%d %d",x,y); scterm(); } Chapter 7, The SoftC Library 99 99 scwyloc scwyloc _______ Usage Usage _____ unsigned short int scwyloc( void ); scwyloc Prototype in Prototype in ____________ windows.h Description Description ___________ scwyloc returns the y coordinate (row number) of the scwyloc current cursor position within the selected window. See also See also ________ scwgoto, scwxloc. scwgoto scwxloc Return Value Return Value ____________ None. Example Example _______ #include "SoftC.h" #include "windows.h" void main() { unsigned short int x,y; scinit(20,20); scwputs("Hello world!"); x = scwxloc(); y = scwyloc(); scwgoto(1,1); scwprintf("%d %d",x,y); scterm(); } INDEX dtoc 16, 64, 65 scikmake 16, 54, 64, 65, left 16, 64, 65 66 right 16, 65 sciknext 15, 67 sccday 17, 21, 28 scikprev 15, 68 sccddiff 17, 22 scinit 3, 5, 18, 69, 73, sccdn2s 17, 22, 23, 24 80 sccds2n 17, 23, 24 sciopen 15, 56, 70 sccdvalid 17, 22, 23, 25 scipinfo 15, 71 sccdxlat 17, 22, 25, 26 scipnum 15, 72 sccleap 17, 26, 27, 28 scterm 5, 13, 18, 70, 73 sccleapi 17, 27 scvers 18, 74 sccmonth 17, 21, 28 scwaget 8, 9, 74, 75 scdclose 13, 15, 29 scwaput 8, 9, 75 scdcreate 13, 14, 30 scwbget 10, 76, 78, 90 scdfget 14, 32, 33, 34, scwbput 10, 77, 78 37, 39, 45 scwcget 10, 79, 85, 90 scdfgets 14, 32, 33, 38, scwclose 9, 81, 82, 90 39 scwclr 8, 9, 83, 84 scdfinfo 32, 33, 34, 35 scwclreol 8, 9, 83, 84 scdfnam2no 15, 36 scwcput 10, 81, 84, 85 scdfput 14, 32, 37, 39, 47 scwcursoff 8, 85, 86 scdfputs 14, 34, 37, 38, scwcurson 8, 86 39, 45, 47 scwgoto 8, 85, 86, 87, 98, scdinfo 13, 39, 40 99 scdopen 13, 29, 40, 41 scwinfo 8, 10, 88, 96 scdrclear 14, 41, 42 scwopen 9, 77, 81, 82, 88, scdrcopy 14, 42, 43 89, 91, 95 scdrdel 14, 43, 44, 48 scwopenx 9, 82, 88, 90, 91 scdrget 13, 32, 34, 44, scwprintf 7, 8, 92, 93, 94 45, 47 scwputc 7, 8, 92, 93, 94 scdrinfo 14, 35, 46 scwputs 7, 8, 9, 18, 92, scdrput 13, 47 93, 94 scdrundel 14, 44, 48 scwselect 9, 82, 95 scdsize 13, 49 scwtget 10, 96, 97 sceclr 18, 50, 52 scwtput 10, 96, 97 scemsg 18, 50, 51, 52 scwxloc 8, 87, 98, 99 sciclose 52 scwyloc 8, 87, 98, 99 scicreate 15, 53, 54, 66 sc_code 18, 19, 50 sciexpr 15, 54 str 16, 65 sciinfo 15, 55, 56, 58, substr 16, 65 61, 62, 63, 67, 68 scikadd 16, 56, 57 scikcur 16, 58 scikdel 16, 59 scikfind 15, 58, 60, 67, 68 scikfirst 15, 58, 62, 67, 68 sciklast 15, 58, 63, 67, 68 100