C/C++ Interactive Guide

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

/ C/C++ Interactive Guide / c-cplusplus-interactive-guide.iso / c_ref / csource4 / 272_01 / smlibdl.doc < prev next >

Wrap

Text File | 1987-08-17 | 26.7 KB | 991 lines

========================== = STEVE'S LIBRARY = = for Datalight = = - by - = = Steven E. Margison = ========================== Functions and Documentation Copyright 1986 & 1987 by Steven E. Margison -- All Rights Reserved ISBN 0-944267-06-8 --------- TABLE OF CONTENTS --------- Introduction ................................. 1 The Documentation ............................ 1 Installation ................................. 2 Linking ...................................... 3 Interrupt Handler Functions .................. 4 Utilities ..... .............................. 5 On Buffering STDOUT .......................... 10 Shareware .................................... 11 Warranty ..................................... 12 Registration Form ............................ -- Steve's Function Library for Datalight C I. INTRODUCTION The heart of the C language is its library. Each compiler has its own library of functions, which is complete only to the degree that the compiler author wishes to make it. The Datalight C Compiler is an excellent product which has gotten rave reviews in computer magazines. (I have both Lattice 3.1 and Datalight available to me and I prefer the Datalight by far.) The greatest criticism which can be leveled at Datalight is the size of its library. It has all the usual basic functions, plus some nice unique features. But it still can use some help. Enter Steve's Library! At over 100 functions my library greatly enhances program development with Datalight C. II. THE DOCUMENTATION The documentation for the library is contained in a number of .DOC files, which describe each function. When printed, these pages may be placed in a standard three-ring binder. A utility program, PMAN.COM is provided to generate the entire set of documents. PMAN requires the file LISTALL, which may be edited to eliminate printing of certain files if desired. (PMAN is copyrighted, but placed in the public domain.) To print the DOC files, you must be in a directory (or on a floppy) containing PMAN, LISTALL, and all the DOC files. Just type "PMAN" at your system prompt and the files will be printed to PRN:. Steve's C Library for Datalight Page 1 III. INSTALLATION Steve's Library is distributed as four library files for each type of memory model. (Only the full registration with source has all four libraries.) The filenames are: SMDLS.LIB Small Memory Model SMDLD.LIB Large Data Model SMDLP.LIB Large Code Model SMDLL.LIB Large Code and Data Model For the remainder of this manual the libraries will be referred to as SMDLx.LIB. A typical hard disk installation of Datalight will consist of a directory named \DC in which will be found the compiler, Datalight libraries, and Datalight header files. SMDLx.LIB should be copied into this directory as well, or into whatever directory the Datalight libraries have been installed. Steve's Library also includes several header files which list "define"s for many useful items. These header files are also required to re-compile the source for the libraries. The header files should be copied into the \DC directory, or in whatever other directory contains stdio.h, dos.h, and the other header files. If you have purchased the source files and wish to have them on hard disk, make a new subdirectory under the \DC main directory called SM (C:\DC\SM) and copy all source files to that directory. Steve's C Library for Datalight Page 2 IV. LINKING The SMDLx.LIB library must be linked with any other libraries whenever a function is used in your program. Some programs may not use SMDLx.LIB functions, and therefore the linking of the library may be eliminated to save time. The Datalight driver (DLC) command line would look like this: DLC MYPROGRAM \DC\SMDLS.LIB Naturally, if your directory structure is not the standard, specify the paths as needed. In addition, if you have other third party libraries, be sure to include them after SMDLx.LIB. Steve's C Library for Datalight Page 3 V. INTERRUPT HANDLER FUNCTIONS A special feature of Steve's Library is the various interrupt handler functions. These are: ticker ctlbrk criterr These functions provide the programmer with the ability to install a special routine to intercept one of the DOS interrupts. ctlbrk() installs a user-defined routine to be executed whenever a control-break is typed on the keyboard. criterr() traps the DOS critical error handler (the one that says Abort, Retry, etc.) and allows the programmer to substitute his own handler. ticker() is not really a user definable handler, but a pre-built handler which allows the user to perform operations relative to the system's clock. A special variable may be loaded with a value and then tested at intervals. When the variable has hit zero, a specific amount of time has passed. The variable counts 18.2 times per second, and is installed on INT 1CH. The usage of these interrupt handlers is slightly complex and interactive. For example, if you use ticker() you must use ctlbrk() and you may have to use criterr(). It has been said that a picture is worth a thousand words. Well, to me, a source file is worth a whole chapter of tutorial. Therefore, refer to TESTINTS.C, which is supplied with all distributions of Steve's Library , to see a heavily commented source code file which uses these interrupts. This program may be compiled and run to watch the result. Steve's C Library for Datalight Page 4 VI. THE UTILITIES Beginning with Release 1.20 of my library, I am shipping the source code for several utiltiies I have written. Nothing earth shaking here, just some convenient programs to make life a little easier. All the programs use several functions from Steve's Library, and can serve as an example of proper usage. Here is a short description of each utility: INPATH This utility searches for an EXECUTABLE program in the current path. Typing INPATH at the DOS prompt will display the version number and a short usage message. To use, type: inpath <filename> where filename is the basename portion of the executable file to find. Note that an extension can be specified, but it is ignored. INPATH will first look for the file in the current directory, and then look in the PATH environment variable (if it is present) in the order specified. For each directory, INPATH first tries to locate a .COM file, then a .EXE file, then a .BAT file, since that is the order in which DOS searches for files. On the first match, INPATH reports the directory and full filename of the program and then exits. If none are found, that fact is reported. INPATH demonstrates the use of newext() and error(). TC This is a quick Text Compare program to compare two ASCII files. Typing TC at the DOS prompt will display the version number and a short usage message. To use, type: tc file1 file2 where file1 and file2 are the two files to compare. If the files are identical, no more messages will appear. Otherwise, the program will report any lines which are different with the filename, line number, and a printout of the actual line. If one file ends before the other, the program reports which file terminated first. TC demonstrates the use of error() and cant(). Steve's C Library for Datalight Page 5 WC WC counts words, lines, characters, and checksums one or more files. Typing WC at the DOS prompt will display the version number and a short usage message. To use, type: wc filename [-wcls] where filename is the name of the file to act upon. With no options, the program will report words, characters, lines, and a checksum, which is a simple binary addition of all character values. No, it ain't a CRC, but it is a quick check to see if it the same as another file under the same name. The options [wcls] tell the program to report ONLY the items specified: -w report only words -l report only lines -c report only characters -s report only checksum Note that giving all options is the same as giving no options. Since words, lines, and characters are meaningless in a non-text file, the program examines the filename extension to determine if the file is a binary or text file. This isn't a perfect method, but it is good enough. If the file extension is .COM, .EXE, .OBJ, .REL, .PFS, .LIB, or .BIN, then only the checksum is reported, overriding all other options. The program supports wildcards in the filename, as well as drives and directories. WC demonstrates the use of exttyp(), cant(), and the wildcard _main object file by Datalight. Steve's C Library for Datalight Page 6 OKISET This program is used to set the printing options available on an Okidata ML84 (with IBM Plug 'n' Play), or most other IBM compatible printers. It may be easily customized for other printers. This is a menu driven program requiring no options. Just execute it and follow the directions! F1 PITCH Use the SPACE key to toggle between normal (10 cpi) and condensed (17.5 cpi) pitch. Press RETURN to make the selection. F2 STYLE Use the SPACE key to toggle between draft and letter quality style, and press RETURN to select. F3 LQ SPACING Enter 1 or 2 digits in the range 00-11 to select letter quality spacing. ESCape will abort this entry, BACKSPACE will allow you to start the entry over, and RETURN selects the entered value. This selection assumes letter quality mode, and forces the style to letter quality, and the pitch to 10 cpi. F4 LINES PER PAGE Enter 1 or 2 digits in the range 01-99 to set the page length in lines per page. ESCape, BACKSPACE, and RETURN operate as for F3. F5 LINE SPACING Use SPACE key to toggle between 6 LPI and 8 LPI spacing, and press RETURN to select. F7 OUTPUT CHANNEL Use SPACE key to step through output channels PRN, LPT1, and LPT2. Press RETURN to select. F9 NORMAL OPTIONS This key sets all other options as follows: pitch > 10 CPI style > Draft lines > 66 space > 6 LPI output > PRN F10 SEND CONTROL CODES and EXIT No control codes are sent until this key is pressed. Only control codes which have been selected are sent. If the pitch selection remains blank in the menu, for example, the pitch control code will not be sent. This allows only some options to be changed without disturbing the existing printer configuration. Letter quality and condensed modes cannot be mixed on the printer. Therefore, if a conflicting selection is made, the last entry will force correct options. OKISET will present various beeps for invalid keystrokes, and warning messages where appropriate. Steve's C Library for Datalight Page 7 OKISET will demonstrate cls(), mkbox(), d_say(), getkey(), d_pos(), and show how to manage a non-scrolling program. Programming idea: re-write this program using the direct video access routines. GTOD This utility will report the current system time and date in a variety of formats. GTOD may be invoked with or without options. Options may be preceded by dash, fraction bar, or nothing at all. gtod <options> -d report only date -t report only time -e report date in European format (DD/MM/YY) -s report seconds, if time reporting enabled -r reverse reporting order, with time first and date second -l spell out month in long format -n if option -l, then add name of weekday -m report time in 24 hour (military) format -v report version number -? usage message and exit no options defaults to -dt Output may be redirected to a file or another device, except for error messages. GTOD demonstrates the rather obscure Datalight system clock interface, as well as error(), monthis(), wkdayname(), i_dstr(), and weekday(). Program idea: allow calculation for other time zones. Steve's C Library for Datalight Page 8 DUMP (Oh! No! Not aNOTHer file dump utility!) Well, yes, and I apologize all to h*ll. However, this one started out as a utility supplied with the Datalight compiler, which I hacked to death. First, it will be in **COLOR** if it senses a CGA card installed, and will use blinks and highlights if a mono card is sensed. Second, it fixes a minor bug or two in Datalight's version. Third, and here comes the unique part, it will highlight any selected byte whenever it is found! (Well, at least I think it's handy.) Fourth, it displays only 20 lines at a time and waits for a keypress to continue. Invoke the program as follows: dump filename <offset> <byte> where filename is the file to dump, offset is the hex offset value in which to index into the file before dumping (defaults is 0000), and byte is the hex value to highlight (default is no highlight). The parameters MUST be in the order specified, and the offset must be supplied (as a place holder) if the byte option is desired. DUMP demonstrates the use of getkey(), stuff(), error(), plus many of the disp* functions of this library and Datalight, and the use of color attributes. Programming idea: there are several ways to increase the speed of the program. I haven't implemented them so that you can have the fun(!!) of doing it. Hint: the overhead in printf() is horrendous. Steve's C Library for Datalight Page 9 VII. ON BUFFERING STDOUT Beginning with Version 3.* of Datalight, the authors have decided to buffer the output to stdout. Well, this ain't quite right, thinks me. The result is that any data sent to stdout (usually the console) is held up until (a) the buffer is full, (b) a newline character is sent, or (c) fflush(stdout) is called. This is a royal pain, but it can be fixed. The module IOB.C can be modified to set _IONBF in the stdout definition. I have included a source module, IOBNBF.C, with this modification. It can be renamed to IOB.C and recompiled if desired. Use an object module librarian program to replace the module in the Datalight libraries. Or, simply leave it as an OBJ file and link it into your programs. Since the linker will see it before the same module in the library, it will then take precedence. This may actually be better, since it gives you the ability to use either buffered or unbuffered stdout output. All of the utilities I supply with my library are designed to use unbuffered output. Steve's C Library for Datalight Page 10 VIII. SHAREWARE ShareWare is "try-before-you-buy" software, reasonably priced and user-supported. This simply means that you can get ShareWare software for free from anyone who has a copy, or often from bulletin board systems. If you use and like the program, then the author asks that you register (purchase) the program for a stated fee. By registering you will often also receive notice of available upgrades or supplemental programs. Payment under shareware is on the "honor system", but if the program is useful and the price is right, then please play by the rules and purchase the program. Also, keep in mind that the purchase of a program from a public domain distributor or payment to an online service (such as CompuServe) does NOT constitute registration of the program since the producer of the program does not receive one penny of that payment. "Steve's Library" is shareware. If you use it, please register your copy on the registration form enclosed at the end of this manual. For a slightly higher charge, you may elect to obtain the source code for all functions, and the D, P, L libraries. Please note that the extra libraries and the source code are NOT SHAREWARE, and should not be distributed. Only the documentation, utilities, header files, and Small model library may be passed on under the shareware concept. Online help is available through CompuServe (74435,1042), or GEnie mail (S.MARGISON) to registered users ONLY. Help is also available by mail. I will try to answer all letters within 48 hours. Non-registered users must include a SASE for a reply. The degree of help available to non-registered users is purely discretionary. No phone calls, please. "Steve's Library" may be used in a commercial environment, with no royalties required if functions are included in a program for sale. However, the library, source code, and all related documentation may not be sold under any circumstances without my prior approval. Software library services and Users Groups may charge a nominal fee for copying and distributing those files which are shareware. Please contact me for a complimentary copy to insure that you are offering the most recent and complete release. The source code may NOT be offered for sale or trade by other than myself. "Steve's Library" may not be included or "bundled" with any other software without prior permission. "Steve's Library" and its documentation may not be transferred nor exchanged in any modified form. I cannot be expected to help others use these functions if they are not the same as distributed. Under no circumstances may the copyright notices be altered or removed from the functions or documentation. Steve's C Library for Datalight Page 11 IX. WARRANTY Oh, this shouldn't be necessary among friends and gentlemen, but it's really the lawyers who run the world and they say we gotta do this: ** Steve's Library functions and all documentation are copyright 1986, 1987 by Steven E. Margison. ** These functions and documentation are provided "as is" without warranty of any kind, either expressed or implied, including but not limited to the implied warranties of merchantability and fitness for a particular purpose. ** The user of these functions and documentation agree to hold the author and/or distributor(s) of this material harmless for any direct or consequential damages resulting from its use. In other words, "you're on your own!" ** IBM is a registered trademark of International Business Machines Corporation. ** MS-DOS is a trademark of MicroSoft Corporation. ** Datalight C is a registered trademark of Datalight, Inc. Steve's C Library for Datalight Page 12 ======================================================================= SOFTWARE REGISTRATION FORM AND ORDER ======================================================================= A separate form must be filled out for each product ordered or registered. This form may be photocopied, printed out, or edited to include all information and re-printed. PRODUCT: --------- STEVE'S DATALIGHT LIBRARY VERSION 1.30 -------------- QUANTITY: Amount: _____ Standard registration $10.00 ea $______ _____ Registration with Source code $25.00 ea $______ Shipping outside U.S. or Canada $ 3.00 TOTAL DUE $______ Payment must be made in U.S. Funds Source code is NOT SHAREWARE and is not to be transferred to other users. Only the DOC files, header files, utilities, and S library are released into shareware. Corporations: Write with your requirements for a quote on multiple copies or site licensing. If you already have this library, where was it obtained? [ ]CompuServe [ ]Friend [ ]Employer [ ]BBS:__________________ Version_____ Serial No._________ Payment is by check[ ] or money order[ ] (Sorry - no COD or charges) NAME _______________________________________________________ COMPANY ____________________________________________________ ADDRESS ____________________________________________________ CITY _______________________________________________________ STATE___________________________ ZIP _______________________ ======================================================================= Send completed form and payment to: Steven E. Margison 124 Sixth Street Downers Grove, IL, 60515 ======================================================================= - do not write below this line - recd________ sent________ version_______ serial no.__________________