USADACS@SIMTEL20.ARPA (Al McIntosh) (06/11/88)
The following is an edited version of the documentation contained in the Simtel archive PD1:<MSDOS.C> @TITLE = C PROGRAMS @DISK LABEL = CP001 GETARGS - command line processor for C program. A command line switch is an argument preceded by a '-' that modifies the way in which a program works. This command line processor is a package of subroutines. Access to the routines is through one call to the procedure getargs(). The routines are table driven. Getargs() removes switches from the command line as it works and leaves other arguments (the ones not preceded by '-') alone. When getargs() finds an error, it prints an error message to stderr listing all the legal switches, descriptions of each, and their default values. It then terminates with exit(1), which should close any open files. To use getargs() you must: (1) Set up a table to tell the routine what switches to expect, (2) Declare the associated variables and initialize them to their default values, and (3) call the routine itself somewhere early in the main() routine. The file getargs.h contains the #defines and typedefs needed to create the command switch descriptor table. This table is an array of structures: typedef struct { unsigned arg; /* command line switch */; unsigned type; /* variable type (of those #defined above) */; int *variable; /* pointer to variable */; char *errmsg ; /* pointer to error message */ ARG; The arg field is a character that identifies the switch on the command line. In the following descriptions this character is represented by witch. The type field may take any one of five values, all #defined in getargs.h. INTEGER switches take the form -witch. Numbers preceded by 0x are hex, by 0 without the x, octal. All others are decimal. The number is terminated by any character not legal in the indicated radix. The int pointed to by the variable field of the ARG structure will be set to the value of the . If the isn't typed on the command line, *variable is set to 0. BOOLEAN switches will cause *variable to be set to 1 if present. If the switch is absent, *variable is not modified. CHARACTER switches take the form-witchharacter. When the switch is found on the command line, *variable is set to the character immediately following the witch character. STRING switches take the form -witchg. When the switch is found on the command line, the character pointer pointed to by the variable field is set to point at a string consisting of all characters following (but not including) the witch character up to the end of the current argument (not to the end of the command line). PROC switches take the form -witchanything. Here, the variable field is a pointer to a subroutine that is called indirectly as soon as the switch is encountered on the command line. A pointer to anything is passed to this subroutine as a single argument. It is the responsibility of the called subroutine to parse anything as appropriate. The errmsg field in the table is used to print an error message if an undefined switch is found. Switches may be combined into a single argument, but string switches must be last one because all following characters will be considered part of the g. When defining a STRING switch in the table, be sure to cast the variable into an integer pointer. See argtest.c for an example. DIRLIB.ARC - Enclosed is an implementation of the `dirlib' package for MS-DOS. The implementation is targeted for MS-C, although any reasonably competent C compiler should manage. The package consists of: dir.h, the header file; dir.c, the functions; testdir.c, a q&d test program. The package tries to view directory naming in a Un*x light; in particular, directories such as '/.' and '/..' (as well as `.' and `..' if your current directory is root) are understood. Indefinite paths like `/../.././../..' will correctly refer to the root (of the particular disk). Names such as `a:////./../' INPUT.ARC - read a string from console in a batch file. SYNTAX - INPUT ar name. Where is a "quoted" string and ar name is the name of an environment variable to accept the input string. Use \" to include the double quote character itself in the prompt. BRIEF DESCRIPTION - Just like BASIC's INPUT statement, except this one works in batch files, so you can read a string from the user and use the string in your batch file. MAEK.ARC - SYNOPSIS, make [filename]. MAKE performs the necessary actions to generate an updated version of the specified file when some of the files on which it depends have been changed. The dependency relationships and the required actions are described in the text file MKFILE. All the blank lines are required. Lines starting with '#' are comments. Otherwise, MKFILE consists of a series of blocks. Each block is a dependency line followed by zero or more action lines followed by a blank line. A dependency line has a target file name, a colon, and a list of the files on which the target file depends. Whitespace (blanks or tabs) can be added for clarity. Any line can be continued by ending it with '\'. MAKE will find the block in MKFILE which has the specified file as a target and record its dependencies and actions. It will repeat this recursively for each dependent file. It will then check the create times and dates of the files. If any dependent files is newer than the corresponding target file, the actions which follow will be performed. MAKE then updates the create times and repeats for the other blocks. If no filename is specified on the command line, MAKE will make the first file in MKFILE. There are several restrictions not present in the Unix facility of the same name. All dependent files must appear somewhere else as target files. That's why the null entries for try.c and make.c appear above. MV.ARC - move/rename files or subdirectories for PC DOS 2.xx and 3.xx; MV is like the mv program on UNIX (trademark of AT&T Bell Labs.) It moves files/sub-directories within a physical disk. This is done by manipulating directory entries and not by copying and deleting files. The advantage is that it's fast and non- recursive: moving a sub-directory containing six hundred files takes the same amount of time as it takes to move an empty sub- directory. The disadvantage is that you cannot move files/sub- directories from one physical drive to another. To do so you must copy and then delete; MV doesn't help in this case. In addition to normal physical disks, MV also works on 1) 'Join'-ed disks; of course you still cannot move things across different physical disks. 2) 'Subst'-ed disks. The above 'disks' can be created in DOS 3.xx. MV will not work on shared disk across the network. If you attempt to use it this way, you will get the message 'sorry, mv doesn't work on network disks.' When MV is writing to the disk, it will ignore the break key. This is to prevent you from messing up the disk. If you press the break key while running MV, the program might not stop immediately, but it will eventually - after it's done writing to the disk. However, you can still mess up your disk by rebooting or turning off your computer while running MV. So be careful: DO NOT STOP mv BY REBOOTING OR TURNING YOUR COMPUTER OFF; if you must stop MV, use the break key. SPLINE.ARC - Generates splines under tension and allows general curves and multiple independent curves in the same file. Text input and output files like the UNIX program. Written in C by J. R. Van Zandt, based on algorithms by A. K. Cline. Without options, SPLINE reads pairs of numbers (x- and y-values) from the standard input (or the given file), generates a smooth curve through the points, and writes to the standard output points from the smooth curve. The curve is a spline under tension (see references), which is somewhat "tighter" than a cubic spline, and less likely to have spurious inflection points. As with GRAPH, each pair of points may optionally be followed by a comment. If the comment is surrounded by quotes "...", it may contain spaces. The given points, and their comments if any, will be included in the output. Input lines starting with ";" are written to the beginning of the output file but are otherwise ignored. Blank lines are ignored. If the -c switch is not used, the input points must be from a function - that is, the x values must be strictly increasing. The output points will also be from a function. (If the -b switch is used, this restriction applies only within each segment.) If the -c switch is used (indicating a general curve), the input points need not be from a function, but each pair of points must be separated from the previous pair by a finite distance. (If the -b switch is used, this restriction applies only within each segment.) options are: -a [step [start]] Input data contains only y values - generate automatic abscissas at intervals of step (default 1) starting at start (default 0); -b break the interpolation at each label. That is, the input curve is divided into sections with the last point in each section marked by a label (which may be empty:""). A separate interpolating curve is to be found for each section. In this case, the requirements on the number of intervals (specified by the -n switch or defaulted) and the interpolation range (specified by the -x switch) are applied to each section independently; -c general curve rather than function. In this case, the curve is parameterized on the polygonal arclength from the first to the last given point, with the whole length scaled to be 1. Thus, the values min and max for the -x switch should satisfy 0 min max 1; -n num interpolate over num intervals (default is 100); -t num Specify tension in interpolating curve. Tension of 50 gives almost polygonal line, tension of .01 gives almost cubic spline. Default is 1; -x [min [max]] interpolate from min to max only. min and max should be in the range of the given x values, except that if the -c switch is used they should satisfy 0 min max 1; -xl take log of x values before interpolating, take exponential; -yl take log of y values before interpolating, take exponential afterwards (probably necessary if -xl switch is needed for GRAPH) UNDOC.CDS - Undocumented commands from Microsoft "C" compiler. MAKE.ARC - Source code for the MAKE command. MATH.ARC - Mathematical subroutines for use with Lattice or Microsoft-b compiler. This file contains the combined source files of the most important mathe- matical formulas written for the Lattice C Compiler. It makes no use of the 8087. Some of the functions make use of the internal binary representation of double precision numbers. As the internal data representation may vary between different compilers, watch out for errors e.g. in the power function. The function values are calculated through polynominal or rational approximations. The results are for allmost all functions precise for the first 9 to 10 decimal digits. For still higher precision or checking of values use functions from file mathf.c (not available here), which contains Taylor's expansions series. As this requires many iterations with multiplications and divisions, the calculation time is too long for use in regular programs. In order to use these functions, a program has to include the header file "math.h". Furthermore, either the compiled version (math.obj) or a library with the compiled functions has to be linked to the program. As exemples see included test programs "tstsin.c" and "tstpow.c" To compile: "mcb tstsin ", to link:"link c+%1+math.obj, %1, ,mc ". I recommend to compile the source of each function seperately with your personal compiler and use the MS-DOS ibrarian to build a library of just the functions you need. Some of the more esotheric functions used on "UNIX" are such as Bessel functions or the gamma function are not implemented. Evidently, this is not a professional implementation. SHAR.ARC - Here is a quick and dirty shar archiver that I use on an MS-DOS machine to package several C source files for porting to a UNIX system. The compiler I use (DeSmet) converts "\n" to "\r\n" so I run the resulting file through a '\r' remover (such as tr -d '\015'). The archive uses the "cat" format and goes to file "shar.out". TIMESTMP.ARC - File: timestmp.c. Function: Provides time and date information. This version is for IBM PC and PC compatibles. Written for Computer Innovations C86 compiler. 06/05/84 - V1.01, adapted to Unix V7 by defining symbol UNIX. 11 Dec 85 Craig Milo Rogers Converted to Lattice C 2.12. Left the C86 code around in a conditional. UNIXCLIB.ASM - This is a package of routines that (1) emulate routines found in the standard C function libraries on UNIX systems, and/or (2) help bridge the gap between MS-DOS and Unix. The routines are: file_exists, set_jmp, long_jmp, and sleep. CURPOS.ASM - Move the cursor to specified location (depends on mode); synopsis curpos(x, y), x and y coordinates of destination; description use video interrupt to go to (x,y) on screen. C-SUBS.ARC - A collection of useful subroutines in C. ARGTEST.C: - test program for getargs. GDIR.C: is an enhancement over DOS's dir command. It includes file attributes in its display, allows you to perform directories of hidden and system files, and also allows you to recursively check all of a directory's subdirectories as well. Usage: GDIR [/I] [/A] [/D] [/R] [d:][dirspec][filespec]. Options: /I - Include invisible (hidden and system) files in listing. Default is to not list invisible files. /A - Include files with leading dot in listing. Default is to not list files with a leading dot. /D - Only list directories. Default is to list directories and files. /R - Recursively GDIR on all subdirectories. Parameters: d - drive to search; defaults to current drive. Dirspec - directory to search; defaults to current directory. Filespec - file(s) to search; defaults to curent directory. HSORT.C; Based on algorithms by Jon Bentley [Communications of the ACM v 28 n 3 p 245 (Mar 85) and v 28 n 5 p 456 (May 85)], and the sort interface routines by Allen I. Holub [Dr. Dobb's Journal #102 (Apr 85)]. Including a #define for DEBUG will make this file a stand-alone program which sorts argv and prints the result, along with the heap at the intermediate stages. This is instructive if you want to see how the heap sort works. #defining DEBUG2 will also print results of comparisons. This routine sorts N objects in worst- case time proportional to N*log(N). The heapsort was discovered by J. W. J. Williams [Communications of the ACM v 7 p 347-348 (1964)] and is discussed by D. E. Knuth [The Art of Computer Programming, Volume 3: Sorting and Searching, Addison-Wesley, Reading, Mass., 1973, section 5.2.3]. This algorithm depends on a portion of an array having the "heap" property. The array X has the property heap[L,U] if: for all L, i, and U; such that 2L i U; we have X[i div 2] X[i]; sift_down enlarges the heap: It accepts an array with heap[L+1,U] and returns an array with heap[L,U]. IBMCUR.C - is a subroutine to position the cursor on a display. QSORT.C - general purpose quicksort. Including a #define for DEBUG will make this file a stand-alone program which sorts argv and prints the result, along with all intermediate stages. This is pretty instructive if you want to see how the quick sort works. ROOTPATH.C - CurrentDir - return text of current directory for a particular drive. Rootpath - convert a pathname argument to root based cannonical form. Rootpath determines the current directory, appends the path argument (which may affect which disk the current directory is relative to), and qualifies "." and ".." references. The result is a complete, simple, path name with drive specifier. If the relative path the user specifies does not include a drive spec., the default drive will be used as the base. (The default drive will never be changed.) SCALE.C - calculate scaling parameters for plotting so that axes have convenient labels. SINE.C - from Dr Dobb's Journal, May 1986. The article describes a simple plotting routine for the IBM EGA in high resolution (640x350) graphics mode. Author is Nabajyoti Barkakati. The program typed in is nearly but not EXACTLY verbatum. Execution of the program illustrates the slowness of drawing dots using the BIOS interface. SPEAKER.C - Demonstration program on how to program the speaker on a PC. TAGS.C - allows you to find the file which contains a definition if you know the name of the object being defined. For example, you are looking at a call on procedure xYzzY, and want to see what it does. Fine. Invoke TAGS by typing Alt-., give it the name xYzzY, and suddenly before your very orbs is the definition point for the function! If the cursor is sitting somewhere before a word, that word is the default name to look up and so A-. CR usually suffices. This requires running a program over your source file that locates all the tags and puts them in a tag dictionary, then having an editor command that looks things up in the tag dictionary. TESTDIR.C - Directory Access Library Test Program XRF.ARC - Cross-Reference Lister for C Programs. xrf prepares a cross-reference listing for C source programs. The following options are defined: -n Narrow output (80 columns). The default is 132 columns. -i Symbol size is 31, else truncated to 8 characters (default). -s Spool output to the default line printer. -p Print C source (with linenumbers). -c Concatanate input files(s). The default is seperate reference listings for each file. -o file Write output to the named file. The default is the first input file encountered, with a filetype (extension) of ".REF". C4WINDOWS.ARC - A collection of subroutines for the manipulation of screen windows. Allows for up to 255 separate windows. @DISK LABEL = CP002 C-TUTOR1.ARC - Before you can begin study of C, you must print out a copy of the tutorial text. The file named PRINTEXT.BAT is designed to help you to do this. Simply type the name PRINTEXT at the DOS prompt and all of the tutorial text will be printed for you. When the system displays "Name of list device [PRN]:", hit the return key to accept the default. This batch file uses the DOS command PRINT.COM to actually do the printing and it has an upper limit of 10 files that can be queued up at once. There is therefore a pause after each group of print requests to allow the queue to empty out, after which you must hit any key to allow printing to continue. If you key these commands in manually, you can print in the background, and be using your computer to do something else (provided of course that the something else doesn't require the printer). C-TUTOR2.ARC - a printout of all of the C files can be made using the PRINTALL.BAT file included. Simply type PRINTALL at the command prompt with the printer on and lots of paper in place. It will print about 150 pages including this file and some other definition files. You may want to edit a copy of the PRINTALL.BAT file to only print part of the files initially, and print the remainder as you come to them in the lessons. PRINTALL.BAT uses the file LIST.EXE to actually do the printing. This is a program written in C, and included in your tutorial as an example program in chapter 14, and compiled for you to use in this step. Since printers are not standard there is a chance that LIST.EXE will not work on your printer. If it doesn't, use the file named LIST.COM from the other disk. LIST.COM was written to do the same job, but it was written in Pascal and compiled with Turbo Pascal. Since it uses a different compiler, it may work correctly on your printer. After you gain experience, you can debug LIST.C and LISTF.C and compile them for use with your particular printer. If neither works, use whatever method you can to print out the files, if you desire to. It is not really necessary to print out the C example files, but sometimes a hardcopy is a real convenience. CCOMPILE.ARC - This program takes as input a "C" source program file and formats it with the proper indents for each statement. The original input file is renamed as a .BAK file, and the formatted output is placed in a file with the same name as the original input. A command line option allows the indent level to be specified as from 1 to 8 spaces. This program will only run under DOS 2.0 and later. DEBUGC.ARC - is a set of macro definitions that allow you fairly fine control over what parts of a program execute. It allows you to designate portions of code and printf statements that will execute only when you are debugging, and portions that will execute only when you are NOT debugging. Debugging messages can be left in the source code at no cost in object size. Time consuming portions of code that are known to work well can be skipped during debugging and will automatically be included in a regular compile. Messages that identify functions or specific locations as well as the value of variables will automatically be included when debugging and ignored when not debugging. DLC-TSR.ARC - Terminate and Stay Resident (TSR) library function for Datalight C. MAKE-PD.ARC - is a repost of the public domain 'make' that I posted to net.sources a couple of months ago. I have fixed a few bugs, and added some more features, and the resulting changes amounted to about as much text as the whole program (hence the repost). For those that missed the net.sources posting, this is a public domain re-implementation of the UNIX make program. There is no manual included; for documentation, refer to a UNIX manual, or the source. @DISK LABEL = CP003 BOSS.ARC - is a complete windowing system for the PC. A maximum of 1000 windows can be generated. Attributes can be controlled and all windows are memory resident for greater speed. A "C" compiler is required to use this progrram. CSR.ARC - C Spot Run is a library of C and Assembly routines for C programmers. These routines supplement the standard libraries provided with compilers, and provide tools for specialized applications. All routines in this library are in the public domain, and the accompanying utilities and programming aids are either public domain or are part of the user supported software world. The use of pre-written routines reduces the amount of tedious code writing. GRAPH.ARC - is assembly code that does graphics in CGA 320x200 mode with 4 colors, and in EGA 640x350 mode with 16 colors. The routines are intended to be called from C (Microsoft 4.0 flavor), but with fairly minor modification could be callable from assembly, Pascal, Fortran, BASIC, or whatever your favorite language is. The only things that are language specific are: 1) the structure of the GROUPs and SEGMENTS; 2) the underscore as the first char of all public/extern labels; 3) the way function arguments and return values are passed on the stack. All of the functions operate the same on both CGA and EGA (given the differences in number of pixels and colors available) except for the SETCOLOR and BPLOTXY functions. With those functions, the arguments mean slightly different things, as is mentioned in the (brief) reference card. The code should assemble OK with almost any version of the Microsoft assembler. There's not a lot of documentation included other than the comments in the code. TPC.ARC - Translate Pascal to C. This program will read a turbo pascal source file and convert it into the corresponding C source code. It does about 95% of the work required to do the translation. @DISK LABEL = CP004 TEACH-C.ARC - was written while the author was learning the language and since they are free ( to copy and/or distribute) there is a money-back guarantee on the accuracy of each and every statement in the lessons (!). The display program was written ( in C ) in order to provide a vehicle for displaying the lessons. -------