Microsoft Programmer's Library 1.3

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

/ Microsoft Programmer's Library 1.3 / Microsoft_Programmers_Library.7z / MPL / msc / prftc.txt < prev next >

Wrap

Text File | 2013-11-08 | 851.5 KB | 22,571 lines

Proficient C The Microsoft(R) guide to intermediate and advanced C programming by AUGIE HANSEN PUBLISHED BY Microsoft Press A Division of Microsoft Corporation 16011 N.E. 36th Way, Box 97017, Redmond, Washington 98073-9717 Copyright (C) 1987 by Augie Hansen All rights reserved. No part of the contents of this book may be reproduced or transmitted in any form or by any means without the written permission of the publisher. Library of Congress Cataloging in Publication Data Hansen, Augie Proficient C. Includes index. 1. C (Computer program language) I. Title. QA76.73C15H367 1987 005.13'3 86-31109 ISBN 1-55615-007-5 Printed and bound in the United States of America. 4 5 6 7 8 9 FGFG 8 9 0 9 8 7 Distributed to the book trade in the United States by Harper & Row. Distributed to the book trade in Canada by General Publishing Company, Ltd. Distributed to the book trade outside the United States and Canada by Penguin Books Ltd. Penguin Books Ltd., Harmondsworth, Middlesex, England Penguin Books Australia Ltd., Ringwood, Victoria, Australia Penguin Books N.Z. Ltd., 182-190 Wairau Road, Auckland 10, New Zealand British Cataloging in Publication Data available Microsoft(R) and MS-DOS(R) are registered trademarks of Microsoft Corporation. This book is dedicated to my parents, who worried throughout my childhood and teenage years that I would electrocute myself in my electronics laboratory, and to my family, Doris, Lindsey, Reid, and Corri. They all mean much more to me than I can ever tell them using mere words. Contents Acknowledgments Introduction SECTION I Getting Started 1 The C Compiler System 2 Program Development 3 The DOS-to-C Connection SECTION II Standard Libraries and Interfaces 4 Using Standard Libraries 5 PC Operating System Interfaces 6 The User Interface 7 Automatic Program Configuration SECTION III File-Oriented Programs 8 Basic File Utilities 9 File Printing 10 Displaying Non-ASCII Text SECTION IV Screen-Oriented Programs 11 Screen Access Routines 12 Buffered Screen-Interface Functions 13 The ANSI Device Driver 14 Viewing Files SECTION V Appendixes A Microsoft C Compiler, Version 4.00 B Other C Compilers C Characters and Attributes D Local Library Summary Index Acknowledgments Working with the management and staff at Microsoft Press has been a distinct honor and a rewarding experience in many ways. I am impressed by the dedication, skill, and knowledge of all the individuals that I have dealt with either directly or indirectly during the development and preparation of Proficient C. The person who is responsible for suggesting this book to me is Claudette Moore. She helped me pare down the original outline to something manageable, provided all the needed software, arranged for Microsoft experts to answer my questions, and kept things moving in the right direction. Marie Doyle had the primary responsibility for editing the manuscript. She has been tireless in her efforts to obtain consistency and accuracy of the material and to ferret out my hidden assumptions. Thanks also to Dori Shattuck who participated in the early editing of the project. I am indebted to Jeff Hinsch for poring over all the figures and source listings, testing all programs to verify correct operation, and working with me at some pretty strange hours to transfer files electronically. Jim Beley has been involved throughout the project. He was best known to me as the hit man ("Just calling to check on our schedule ... "), but his efforts and those of his staff are essential to the preparation and delivery of a book. Jim made many helpful suggestions along the way to improve the book and assure its timely delivery. I also wish to thank Reed Koch, who reviewed the manuscript and contributed many useful comments and suggestions on the manuscript and the programs. Many other individuals who have devoted themselves to this project will probably never be known to me by name. I appreciate their efforts nonetheless. Introduction Building a house that someone is willing to live in is quite an undertaking. The process starts with a good design that makes sense in the context of its surroundings and proceeds to completion through a series of carefully planned steps. Throughout the process, the builder must select the right materials and must employ the right tools to shape and join those materials. A computer programmer faces a similar challenge. He or she needs good tools and needs to use them as effectively as a craftsperson in any other profession or trade. Rather than hammers and saws, the programmer needs assemblers, compilers, linkers, debuggers, and many other specialized tools. In addition, the computer programmer can benefit from the work of others by examining and using collections of ready-to-use program modules. Objectives of This Book Proficient C is a book for programmers. It is primarily about writing programs that are good tools for programmers. It demonstrates the use of C in the development of nontrivial applications, so we will not waste any time solving the Fibonacci series or calculating factorials. Although programs that do such things are instructive, they are of little value to us in building our tools. Proficient C presents proven techniques for developing programs that solve real problems. Now, any person with a modicum of business sense knows that a problem is simply an opportunity in disguise, and some programmers have been astute enough to detect this connection and turn it into piles of hard cash. Whether or not money is your motivation for programming is unimportant; if you are going to program for any reason, you should try to do it well. This book is designed to help you do just that. We will focus on creating building blocks--reusable modules that have wide applicability. Being frugal with our time and energy, we will use existing modules, such as those in the standard libraries that accompany most C compilers, as much as possible. And, of course, we will use our own modules again and again as we develop increasingly sophisticated programs. Intended Audience Programmers with at least a modest level of experience in some high- level language or assembly language will have an easy time going through this book. A working knowledge of C or a similar language (such as Pascal, ALGOL, Modula 2, or Ada) is assumed. Those readers without such experience will be best served by first reading an introductory text on C. Several good beginner- and intermediate-level C books are listed at the end of this introduction. I don't share the opinion that BASIC programmers are somehow crippled by the experience of programming in BASIC, but I admit that many will find some of the concepts embodied in C to have an alien feel. Topics like indirection and recursion don't become immediately clear to most programmers who encounter them for the first time. Study and practice are required in order to become comfortable with them. Hardware All functions and programs in this book were developed and tested in an MS-DOS environment on an AT&T PC6300, and in a PC-DOS environment on an IBM PC/AT. The programs will probably also work on other compatible hardware that runs MS-DOS version 2.00 or later. With suitable compilers, many of the programs in this book that are not dependent upon specific PC features can easily be ported to other hardware and operating systems. That's one of the many beauties of C. You are well advised to have as much primary and secondary storage as possible. A comfortable amount of random access memory (RAM) is 512 kilobytes. This allows room for a RAM disk to speed some operations. A hard disk is also recommended. These recommendations are based on the fact that most modern C compilers in the PC marketplace are large and are usually accompanied by massive libraries of standard functions. C compilers will function on less well-endowed systems, but the cost is usually diminished performance. Software Many of the programs in this book require MS-DOS or PC-DOS, version 2.00 or later. For the most part, I will refer to DOS in the generic sense. I will use the terms MS-DOS and PC-DOS in contexts where the difference is noticeable. (There are very few of these, limited mostly to a few external commands that may be available in one version and not in another.) A good text editor is critical to success in large programming projects. You can use the DOS EDLIN editor if you're a bit of a masochist, but I recommend that you acquire a good programmer's editor like EDIX (Emerging Technology Consultants, Inc.), Brief (Solution Systems), or Epsilon (Lugaru Software, Ltd.). You may also use Microsoft Word, WordStar, or any other word processor that permits files to be saved in a straight ASCII (unformatted) form. Without a C compiler, of course, this book will be of little value to you. The programs were written using Microsoft C, version 4.00, but other C compilers can be used instead. I have tried to minimize the use of features of one compiler that would prevent the use of others of comparable capability. Appendix B describes several other C compilers and what, if anything, must be done to compile the programs presented in this book using those compilers. The DOS linker (LINK) provided with the operating system is used to combine object files and library modules into executable programs. A version of the linker that understands DOS pathname conventions is a necessity. Microsoft provides updated versions of the linker with all of its language products. Organization Section I describes the C compiler system and presents some views on program development. In Chapter 1, we look at the proposed ANSI standard for C and at compilers that attempt to track this moving target. Chapter 2 explores ways in which program development can be made more of a science than an art. Chapter 3 shows how C is used in a DOS setting with emphasis placed on effective use of the DOS command-line and environment variables. Section II describes standard libraries and interfaces. Chapter 4 focuses on the use of the many existing functions in the standard C libraries. In Chapter 5, we explore the low-level interface to DOS from our C programs. Although not portable to other operating systems, such as UNIX/XENIX, these functions are important for certain classes of programs running on the PC. Additional functions built on top of the standard libraries are used at a higher level to manage the all-important user/machine interface. These functions are the topic of Chapter 6. In Chapter 7, we automate program configuration, but allow the user to override the automatic settings in various ways. Section III presents a useful set of file-oriented programs. Chapter 8 provides several UNIX-like file and directory utilities, including an LS program to list a directory in special formats, a TOUCH command to assist the MAKE program maintainer, and an RM command. This orientation to basic file utilities leads to the development of a versatile print command (PR) in Chapter 9. Chapter 10 deals with ways of viewing the contents of non-ASCII files. Section IV switches gears, leaving the realm of line-oriented programs to address the issues of screen-oriented programs. Chapter 11 introduces the concept of a buffered screen interface, and the concept is brought to fruition and expanded upon in Chapter 12, which covers screen-management functions. Chapter 13 describes an interface package that uses the much- maligned ANSI device driver provided with DOS. Chapter 14 presents a visual means of viewing files. Other Books on C Many introductory-level C books crowd the shelves in bookstores, with most of the books introduced in the past four or five years due to the rapidly increasing popularity of PCs and to the "discovery" that C is an extremely compliant and versatile computer programming language. Here is a list of some C books that my students and I have found to be valuable learning aids. The C Primer, 2nd Edition, by Les Hancock and Morris Krieger (McGraw- Hill, 1985), is noted for its gentle introduction to programming in C. The use of flowcharts and examples based on models familiar to everyone makes this an easy-to-read and enjoyable book. Programming in C, by Stephen G. Kochan (Hayden, 1983), has been my mainstay as a teaching book for beginning programmers. It covers the essentials of C without getting bogged down in superfluous detail. C Primer Plus by Mitchell Waite, Stephen Prata, and Donald Martin (SAMS, 1984), is replete with corny but memorable examples and illustrations. It is a comprehensive book that gets a bit deeper into C language than some of the other beginners' books. In addition to these introductory books, you may want to take a pass through Variations in C by Steve Schustack, another C book from Microsoft Press (1985). It is oriented toward developers of business applications and is loaded with advice on good programming style and many very useful examples. And every C programmer should have a copy of the ubiquitous The C Programming Language by Brian Kernighan and Dennis M. Ritchie (Prentice- Hall, 1978). Although it is somewhat dated now, it is a treasure trove of C lore and law and is still considered the standard reference on the C language. Notational Conventions The following notational conventions apply to the text and examples in this book: DOS program names are shown in capital letters (DIR, TYPE). The names of programs we develop are treated the same way (PR, VE, NOTES) when the executable program is being referred to. Names of C functions, variables, and keywords are shown in italics (environ, fgets(), main(), #define). This same treatment is given to the names of source and object files (myprog.c, myprog.obj) and user-supplied function, constant, and variable names. Command syntax follows these conventions: ═══════════════════════════════════════════════════════════════════════════ ITEM CONVENTION EXAMPLE ─────────────────────────────────────────────────────────────────────────── literal text │ roman type │ cmd placeholders │ italic type │ cmd option repeat item │ ellipses │ cmd file . . . optional item │ square brackets ([]) │ cmd [opts] file logical OR │ vertical bar (|) │ cmd [a | b] file . . . ─────────────────────────────────────────────────────────────────────────── SECTION I Getting Started Chapter 1 The C Compiler System The tradition of C, originally established in its UNIX context, has had a profound effect on the programming environments of a vast range of machine types and sizes and has influenced the gamut of computer operating systems. Whether you program on an S-100-bus 8080 system running CP/M or on a CRAY-2 hosting a version of UNIX System V, or nearly anything in between, there is probably a C compiler system available for your environment. In this chapter, we will briefly describe the proposed American National Standards Institute (ANSI) standard for C, some emerging standards for operating systems, and extensions of those that affect our C programming. Then we'll get a brief overview of the Microsoft C Compiler, its various memory models, and C programming support tools. Standards and Compatibility Anything that survives the test of time and that is likely to have a wide base of support is a candidate for standardization. As standards evolve, de facto or otherwise, we face the issue of compatibility with the standard. So it is with C. Proposed ANSI-Standard C The first attempt at standardizing C was the distribution of the "C Reference Manual" written by Dennis M. Ritchie, the author of C. The "C Reference Manual" was published as an appendix to the book The C Programming Language by Brian Kernighan and Dennis M. Ritchie. For many years, this book has been the only generally available description of C. However, since the "C Reference Manual" was promulgated, there have been numerous changes to C that are not supported by all C compiler suppliers, so portability among computer systems, and even among compilers on the same computer system, has been diminished. The /usr/group Committee produced the "UNIX 1984 Standard" document to attempt standardization of the UNIX operating system. One major aspect of the /usr/group proposal is a standard set of library routines. Many of the recommendations, but not all of them, have been incorporated into AT&T's "System V Interface Definition," which defines a standard base for, among other things, the Operating System Services and Other Library Routines, the two major components of the standard library for C. The current de facto standard for C is the UNIX System V implementation by AT&T. In recent years, the American National Standards Institute's Technical Committee on the C Programming Language--Committee X3J11--has been working to produce the first official American National Standard for C. Committee X3J11 is composed of members from various industrial companies, educational institutions, and government agencies. The proposed ANSI standard for C is an attempt to "promote portability, reliability, maintainability, and efficient execution of C language programs on a variety of computing systems." The draft standard uses the "C Reference Manual" and the "UNIX 1984 Standard" as base documents for the language and the library, respectively. The following list describes some of the features that have been added to C or changed since its original description and points out some of the implications of the new features and changes. The enum type specifier has been added, giving C an enumeration data type. The void keyword can be applied to functions that do not return a value. A function that does return a value can have its return value cast to void to indicate to the compiler (and lint, under UNIX/XENIX) that the value is being deliberately ignored. Structure handling has been greatly improved. The member names in structure and union definitions need not be unique. Structures can be passed as arguments to functions, returned by functions, and assigned to structures of the same type. Function declarations can include argument-type lists (function prototyping) to notify the compiler of the number and types of arguments. Hexadecimal character constants can be expressed using an introductory \x followed by from one to three hexadecimal digits (0--F). Example: 16 decimal=\x10, which can be written as 0x10 using the current notation. The # in preprocessor directives can have leading white space (any combination of spaces and tabs), permitting indented preprocessor directives for clarity. In addition, new preprocessor directives have been added: #if defined (expression) #elif (expression) Standard Run-Time Library Routines The standard libraries that accompany most C compilers are standard because we accept them as such, not because of any law. Over many years and millions of lines of C source code, programmers have evolved a set of often-used routines that have been polished and packaged into libraries. Some of the routines, such as read() and write(), provide system-level services and are essentially our hooks into the underlying operating system. Other routines--string-handling functions and macros, for example-- are part of the external subroutine library. (In Chapter 4, we will examine some representative standard library functions and present examples of their uses in programs.) In the last few years, some new additions have been made to the standard libraries. Among them are a set of buffer-management routines, some new string-handling routines, improved I/O error reporting, and additional debugging support routines. The proposed ANSI standard specifies a basic set of system-level and external routines. Microsoft C, Version 4.00 The Microsoft C Compiler, version 4.00, adheres closely to the proposed ANSI standard. I will briefly describe the compiler system and its features, to set the stage for the programs that follow. Appendix A provides a detailed description. The Microsoft C Compiler is a three-pass optimizing compiler. The passes are named C1, C2, and C3. These passes could be called directly, but in practice they should not be. We use one of the control programs MSC and CL to invoke them for us. MSC is the primary compiler control program. With MSC, the linker must be called separately to combine program object files and library modules into an executable program. CL is similar in operation to the UNIX/XENIX C compiler control program cc. It invokes both the compiler passes and the linker, as needed, to produce an executable program. The Microsoft C Compiler uses DOS environment variables to locate libraries and header files in special disk directories. These are normally set to \lib and \include, respectively. The compiler will use a designated temporary area on disk if the variable TMP is defined. The temporary area can be a virtual disk to speed disk-intensive processing. If the machine used at run time has a math coprocessor, the coprocessor is used automatically. Floating-point emulation is used if no coprocessor is installed. Thus, it is not necessary to have separately compiled versions of the same program for differently configured systems. The material in this book was developed on personal computers running MS-DOS and the Microsoft C Compiler, version 4.00. But many of the programs presented here can be moved with little or no change to other hardware, other operating systems, and other C compilers. Appendix B describes several other major C compilers and how they can be used to compile the programs in this book. The primary areas that preclude unqualified portability to other environments are related to the occasional use of special keys on the PCkeyboard, to screen updating via BIOS and direct-access routines, and to the use of other hardware elements of the PC, such as built-in timers and reserved memory areas. Where possible, dependencies on PC hardware have been avoided. One of the goals of the book is to show off some of the marvelous capabilities of the PC and the Microsoft C Compiler, so by design, some of the material is not portable to other environments without some changes. Memory Models and Uses Microsoft C supports programs up to one megabyte in size. It provides five primary memory models plus some extensions that let you produce mixed memory models to meet special needs. The memory models are defined by the following table: ═══════════════════════════════════════════════════════════════════════════ MODEL SIZES ─────────────────────────────────────────────────────────────────────────── Code Data Arrays ───────────────────────────────────────────────────────────── small │ 64 KB │ 64 KB │ 64 KB medium │ 1 MB │ 64 KB │ 64 KB compact │ 64 KB │ 1 MB │ 64 KB large │ 1 MB │ 1 MB │ 64 KB huge │ 1 MB │ 1 MB │ >64 KB ─────────────────────────────────────────────────────────────────────────── Support Tools When we talk about a C compiler, we usually implicitly include a set of support tools that make up a working C compiler system. We'll now examine some of the important support tools that enhance the C programming environment. LINK, the DOS Linker Regardless of what language you program in, you will use the DOS LINK program, the object linker provided with DOS. Depending upon which version of DOS and which language product you have, you may have to upgrade to a newer version of the linker. The linker must understand DOS pathnames and, when used with the Microsoft C Compiler, must be able to access the values in DOS environment variables that point to the library and include file directories. The version of LINK that is used to link the programs in this book is version 3.51. It was shipped with the version 4.00 C compiler. This version of LINK provides a single-level overlay-linking capability that permits memory space to be shared sequentially by several program modules. Earlier versions of LINK, back to version 3.12, will also work, but they do not have the overlay capability of the 3.51 version. I chose not to use overlays in this book, so there is no requirement for an overlay linker. LIB, the Object-File Library Maintainer A library in the computer programming context is a collection of compiled or assembled functions. The functions in a given library are typically related to each other by some common factor, such as the role they serve in handling one major programming task. LIB is provided with Microsoft language products. It allows us to create, organize, and maintain run-time libraries. The linker calls on various libraries to resolve external names during a linker session. The linker automatically looks for the standard C library (slibc.lib, mlibc.lib, and so on) for the appropriate memory model. It looks in the current directory unless the DOS environment variable LIB tells it to look elsewhere, or you provide a list of other libraries to search. We will make extensive use of the libraries provided with our compilers, and we will create some libraries of our own. (Our library strategy is documented in Chapter 2.) Nearly all of the service routines we write in this book will end up in an object library somewhere. Appendix D summarizes all object library functions developed in this book. MAKE, the UNIX-Style Program Maintainer Any repetitive task begs to be automated. MAKE is an automated program maintainer that emulates the basic behavior of the UNIX MAKE program. I will present information on the use of MAKE in building some of the programs in this book. Because my programs, even some of the simple ones, are usually broken into a number of small modules, it is important to have a tool that takes most of the drudgery out of maintaining the programs as changes are made to them during the development and lifetime maintenance periods. MAKE performs its magic by applying rules, both built-in and user- supplied, to keep each object file up to date with its sources. The user- supplied rules reside in a "makefile" that lists all the modules of a program; the dependencies of objects on sources, header files, and libraries; and the recipe for how to connect the pieces. MAKE is equally able to control documentation projects and other activities that manage groups of disk files. The next chapter describes the design and development process espoused in this book and shows the relationships of the various activities involved in building a program. MAKE plays an important role in the process. CodeView, the Symbolic Debugger With the release of version 4.00 of the Microsoft C Compiler, Microsoft unleashed CodeView, a spectacular window-oriented, source-level symbolic debugger. Anyone who has done even a modest amount of programming knows the sense of frustration that accompanies a bug hunt. A program that should take a couple of hours to design, write, and test can cost you many hours of anguish because of a subtle, hard-to-find bug. CodeView has the debugging capabilities and operating features needed to shrink the debugging task down to manageable proportions. The debugger is a logical extension of the DOS DEBUG program and Microsoft's SYMDEB, so knowledgeable users of those programs will find CodeView very easy to learn. Using multiple windows, CodeView allows you to view source code, disassemble object code, and monitor program variables, CPU registers, and the stack. Figure 1-1 is a sample CodeView screen that reveals some of the primary features of the debugger. CodeView works on color or monochrome systems, can handle a 43-line EGA (enhanced graphics adapter) screen, and supports both mouse and keyboard user interfaces. MASM, the Macro Assembler The Microsoft C Compiler produces object files in the Microsoft object format, so there is no need to run a separate assembler pass. For information about MASM and ASM, see Advanced MS-DOS by Ray Duncan, Microsoft Press, 1986. ╔══════════════════════════════════════════╗ ║ ║ ║ Figure 1-1 is found on page 10 ║ ║ in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ FIGURE 1-1 ▐ Sample CodeView screen display Chapter 2 Program Development Program development means different things to different people. The particular interpretation often depends on whether the question is asked of a programmer who always works independently or one who normally functions as a member of a team. Whether done by an independent programmer or a team of programmers, program development is a blending of art and science and is an iterative process. For anything but trivial projects, we rarely know exactly how we will do the job before actually starting to do it. We can usually make some good guesses, but there is often an element of discovery involved. As long as something is learned each time through the loop, and as long as mistakes are not repeated, we will likely make some headway. The science part is somehow keeping ourselves headed in the right direction, capturing needed information during the course of a project, and effectively applying what is learned. The art is in knowing what to try when all else fails and in being able to conjure up the correct data structures and algorithms to solve seemingly intractable problems. There is usually at least one approach to solving a problem that makes the task easier than do other approaches. Experience and imagination are your two most important allies in pursuit of this approach. The experience need not be all yours, either--try to borrow existing ideas and adapt them to your purpose if there is a reasonable fit. And be pleased to have other programmers borrow your ideas--it's a sure sign of success. Guiding Principles During the past 10 years or so, I have had the good fortune to be both an observer and a participant on solo and group programming efforts. As a technical writer and publications supervisor, I was able to see the good, the bad, and the ugly aspects of very large programming efforts. As a developer, I saw firsthand how the development process can be made to work well and how it can be made to fail pitifully. The consistent and careful application of structured design and the incremental development of both programs and the documents that describe them are critical factors in the success of programming projects. I suspect that the exact method used has less bearing on the outcome of a project than does the fact that the participants consciously attempt to control what is going on rather than just letting it happen. This book encourages a heavy dependence on the development of reusable modules. The concept of creating reusable modules--essentially stockpiling programming pieces--seems obvious in retrospect, but it was quite a revelation to a generation of programmers 10 to 15 years ago. The standard library is a wonderful example of the concept coming to fruition. There is something elegant about a function that, for example, copies a string onto the end of another string and returns a pointer to the start of the resulting string. Variations of this technique pervade the standard library and give us options in using the library routines that we would not have if the routines had been designed in a less general way. The point here is that we should keep an eye focused on the future use of what we are doing now. First, strive to get something working, but don't quit too soon. Refine it, generalize it, and make it available for future use, both by yourself and by others. The extra time spent in this endeavor will be paid back many times over in saved project time. Also, don't neglect to document what you do, both in comments within the sources and in separate manual-style documentation. The Development Cycle The first step in the development cycle is determining what must be done. This is the problem-definition phase and is the time when we determine the user's needs, investigate the operating environment, and try to get a feel for the boundary conditions that will influence our design. The next phase, program design, is anything but a straightforward process. We need to keep our minds open to many alternatives. We should attempt paper designs, perhaps written in pseudocode, which is a human- language description disguised as program code. Our hope is that at least one of the paper designs will lead to a solution that can be implemented. A major objective at this stage is to produce a language-independent solution to the problem at hand so that we have options later, in terms of choosing a language that best fits the circumstances. When we have what we believe is a workable solution, we can select a language and start coding. I prefer to use C because of its compactness and versatility, but I sometimes use Pascal, Assembler, or BASIC in my work. The choice should be based on factors such as the "lingua franca" of the host environment (local custom), whether any work has already been done on the problem in a particular language (invested value), and whether any of the current investment is worth saving (sometimes it isn't). But telling a hundred assembly-language programmers that from today forward all work will be in C is potentially risky business. It might be easier to learn yet another assembly language! The next phase of the program-development cycle is an important one that is often overlooked. Testing should be planned right along with development, and should be done either by the programmer of the item to be tested or by an associate working closely with the programmer. As soon as the code is done, there should be a way to exercise it to see that the program does what it is supposed to do, doesn't do anything it shouldn't, and protects itself from possible adverse effects of unwanted inputs. It is not too hard to check a program for correct behavior in the presence of expected inputs. This is, of course, important. But the behavior of a program in the face of unexpected inputs is equally important. Writing a program that defends itself well is a bit of a challenge and requires a somewhat perverse mentality on the part of the programmer and the tester. Checking boundary conditions, handling errors promptly and correctly, and generally just being on guard for the conditions that could make your program crumble is something that requires discipline and practice. Be sure to check the return codes from routines that flag errors. Standard library I/O routines are particularly good about telling you when something goes wrong (full disk, bad filename, and so forth). Don't let this vital information fall on the floor. As I said earlier, the program-development process is an iterative one. At any point in the process, don't be afraid to pull the plug and start over if you find yourself traveling the wrong path. If necessary, go to completion, refine the original definition, and do the job again until it's right. You'll be glad you did. Our Local Environment For the purposes of our development work in this book, we will set up some directories for header files and libraries. The hardware and software assumptions listed in the Introduction apply. We will use the Microsoft recommendations for the standard run-time libraries and supplied header- file locations. Any header and library files that we create will be placed in the new directories \include\local and \lib\local, respectively. This practice precludes one of our homegrown files from clobbering one of the files provided with the compiler if we accidentally use the same name. It also collects all of our own files together for convenient access. We will be preparing several header files as we go on through this book. For now, we'll start with the file std.h, which contains some basic information needed by many of our C source files. In addition to defining some often-used constants, std.h contains a definition of a Boolean data type (using the enum type specifier) and some aliases for standard data types that have long names (unsigned short, for example). I used to use these often, but as my typing speed increased, I began to use the original names. Feel free to use whatever you find most natural (or easiest to type). We can use the preprocessor to retrieve our local header files in a way that is consistent with the approach used for standard header files. The preprocessor directive #include <local\std.h> tells the preprocessor to read in the text of the file \include\local\std.h because we previously set the DOS environment variable INCLUDE to \include. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 15 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ Similarly, our local library directory will eventually contain a utility library, util.lib, a pair of operating-system interface libraries, dos.lib and bios.lib, and several other special-purpose libraries. The linker must always be given the correct name for the directory that contains the library files. We will arrange for this to be done automatically by using a makefile that includes pathname specifiers for the required directories. Then we'll let MAKE do all the hard work. Isn't high tech wonderful? Now it's time to do some programming. We begin in Chapter 3 with an examination of how our C programs interact with the MS-DOS system. Chapter 3 The DOS-to-C Connection DOS is, of course, the very popular and widely used operating system for the IBM PC and other personal computers that have a comparable 16-bit architecture. Proficient C is designed to help you write C programs in a DOS environment. To obtain the greatest benefit from our PCs, we must understand both the C language and the DOS environment in which we program. In addition, we would like to exploit the similarities among DOS, UNIX, and XENIX for some classes of programs, especially those that don't require the use of specialized hardware or direct screen access. From the beginning, DOS has had some features in common with UNIX and its many descendants, including XENIX. Among these similarities are basic aspects of command syntax (copy from to, rather than the "backward" approach of CP/M); the use of a common "file" orientation for all data streams, including the console (keyboard and screen) and the printer; and a batch-processing capability (.BAT files under DOS and shell scripts under UNIX). Starting with version 2.00, the operating system acquired many more features that are reminiscent of those provided by UNIX. Among the new features were a hierarchical file system and related support for a hard disk, installable device drivers for customization, a user-controllable environment, and input/output (I/O) redirection. These important features added greatly to the power and flexibility of DOS. In this chapter, we will examine I/O redirection, command-line processing, and access to the DOS environment. Some aspects of each of these topics will be involved in the construction of the programs that are presented in the remainder of this book. Proficient C makes extensive use of the routines in the C run-time library. In this chapter, we use only a few of the more common library routines. A detailed discussion of the C run-time library is presented in the next chapter (Chapter 4). We defer discussion of device drivers until Chapter 13. Input/Output Redirection and Piping By way of a few simple examples, we will quickly review some of the basics of input and output and set the stage for considerably more detailed work using the I/O features of the C run-time library, a marvelous collection of prepackaged routines. Program I/O is based on the concept of standard streams: standard input (stdin), standard output (stdout), and standard error (stderr). The stdin stream is usually "connected" to the keyboard, and both the stdout and stderr are usually connected to the screen. Under DOS, both stdin and stdout can be redirected to other devices, but stderr always goes to the screen. Because all references to I/O devices are treated like files under DOS, we can make ad hoc changes in the source or destination of data being processed by a program. The output of the DIR command, for example, normally goes directly to the screen (stdout). But with a minor change to the command line, we can send the directory listing directly to a printer by redirecting the DIR command's standard output. The command dir > prn tells DOS to feed the data that DIR normally sends to the console screen to the default printer device instead. Thus, the standard output of DIR is redirected. We can similarly redirect input to a command. The DOS MORE command is a good example. MORE is classified in the DOS manual as a filter--a program that is designed to read from the standard input device, perform a transformation of some kind on that input, and produce some output on the standard output device. The transformation performed by MORE is to parcel out the input it receives in screen-sized chunks. MOREcan be used as the termination of a pipeline--a series of programs connected to each other by a pipe, symbolized by the vertical bar (|). The DOS pipe is actually implemented as a pair of redirections. The output of one program is redirected to a specially named disk file, which then becomes the input to the next program in the pipeline. ┌────────────────────┐ ┌─────────────┐ │ ┌────────────────┐ │ │ │ │ │ │ │ stdout │ │ │ │ ├─┤────────────────────────────┤ │ │ │ screen ├─┤ stderr │ │ │ │ │.│────────────────────────────┤ │ │ └────────────────┘▓│ │ │ └────────────────────┘ │ │ │ program │ │ │ │ │ ┌───────────────────────────────┐ │ │ │┌─┬────────┬────────┬─┐ │ │ │ ││▒│▒▒▒▒▒▒▒▒│▒▒▒▒▒▒▒▒│▒│ ┌────┐│ │ │ ││ │ │ ││ stdin │ │ ││▒ keyboard ▒▒▒ └┐ │▒ │├────────────────│ │ │└┐▒▒▒ ▒┌┐▒┌┘ │ ▒▒ ││ │ │ │ └─────────────────┘└─┘ └────┘│ │ │ └───────────────────────────────┘ └─────────────┘ FIGURE 3-1 ▐ Default standard I/O streams The ability to join individual programs into custom-designed collections via the pipe mechanism is an important consideration in the design of an operating system. We can easily plug the output of one program into the input of another to perform special processing. To control the output of the TYPE command, for example, we issue the following command: type myfile.txt | more This command will display no more than a full screen of text at a time, allowing the user to page through the text at a leisurely pace rather than see the text flash by and scroll off the screen before it can be read. The same effect can be achieved by redirecting input to MORE using the command more < myfile.txt We have redirected the standard input of MORE in this case. To illustrate the use of redirection and piping techniques, here is a program called CP, which is a highly simplified version of the DOS COPY command. It is written as a filter in that it copies its standard input (stdin) to its standard output (stdout) one character at a time. Strictly speaking, however, CP is not a filter, because it simply passes its input to its output without modification. /* * cp -- a simplified copy command */ #include <stdio.h> main() { int ch; while ((ch = getc(stdin)) != EOF) putc(ch, stdout); exit(0); } This program should look familiar to anyone who has studied C programming at any level. Although very simple, CP allows us to copy a file from one place in a file system to another with ease. It has some serious limitations that we will address as we proceed through this chapter--for one thing, CP does no error checking, so it depends on DOS to do that work on its behalf. In addition, CP takes no filenames on the command line, so all input must be via redirection, which requires extra typing. CP simply gathers a single character at a time from the standard input and checks to see whether it is the EOF (end-of-file) indicator. If the input is not EOF, it is immediately sent to the standard output. If EOF is detected, the processing loop terminates, and so does the program. EOF is defined in stdio.h as -1. This is why the character-storage location ch is declared to be an int instead of a char data type. Since char can be signed or unsigned (depending on system implementation), we must always be prepared to detect the EOF flag to terminate the copying process. The getc() and putc() library routines are implemented as macros and are defined in stdio.h. They are fast and use the standard I/O library user-buffering scheme. A buffer of BUFSIZ bytes (512 bytes in the Microsoft C implementation) is used for reading and writing operations. When getc() attempts to read past the end of an input stream, it returns EOF. There are several ways to use CP. Simply typing CP on the DOS command line causes the program to take input from the keyboard and display a copy of it on the console screen. You will see the text you type twice, once as you type it, because DOS is echoing your input, and a second time after you type a carriage return to end your input. User input may be terminated by typing Ctrl-Z followed by a carriage return. C>cp This is a line of text. This is a line of text. ^Z C> To copy the contents of a file to the screen, you type the command CP < filename just as you would with the MORE command. To create a new file (or update an existing file), you can type CP >> newfile and CP will copy your keyboard input into newfile until you type Ctrl-Z (the DOS end-of-file marker). Although this simple program is useful, it would be much more versatile if it could accept optional parameters on the invocation commandline, such as the names of files to process, and control information to tailor the processing to meet user needs. The next section explores the use of command arguments and applies them in several demonstration programs. Command-line Processing A program's invocation command line may contain optional arguments in addition to the program name. The main() function of a C program is usually written in such a way as to look first for optional arguments and then for filenames or other parameters. Under UNIX, the convention is to start optional arguments with a leading dash. DOS, however, uses a forward slash (/) to specify options, or what are commonly referred to as switches. (UNIX uses the forward slash as the pathname separator. Since DOS was not originally so close in spirit to UNIX as it is now, DOS's use of the forward slash as a switch flag is forgivable. However, this choice made it necessary to use something else for a separator in pathnames when they were introduced in DOS version 2.00, so DOS designers decided to use the backslash (\) as the pathname separator.) I have elected to use the leading dash as an option flag, but you can easily modify the code to allow the use of /, or to accept either form, as is done in the Microsoft C Compiler programs. Arguments are passed to our programs by the C run-time startup function. A count of arguments, argc, and an array of pointers to character strings, argv, are passed as arguments to main() (along with envp, which we'll look at in detail shortly). If a program needs to access the arguments, it must include argc and argv in the definition of its main() function: main(argc, argv) int argc; char *argv[]; { /* function body */ } Figure 3-2 depicts how the command line and its components are managed in memory. The command line can be thought of as having two components: the command name itself (available within C programs only under DOS version 3.00 and later) and the command "tail," which may contain optional arguments such as filenames or input data. Only the command-name component is required by DOS. The command-line text, if present, is obtained from the DOS command-line tail. Information in the tail may be optional or required, based on the design of the program being executed. main (argc, argv) argc program name ┌─────┐ ┌─────┬─────┬─────┬─────┬─────┐ │ 3 │ │ P │ R │ O │ G │ \0 │ (DOS 3.00 │ │ │ │ │ │ │ │ and later) └─────┘ ─────┴─────┴─────┴─────┴─────┘ │ │ command-line arguments argv │ ┌─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┐ ┌─────┐ │ │ A │ R │ G │ 1 │ \0 │ A │ R │ G │ 2 │ \0 │ 0│ ■──┼──┘ │ │ │ │ │ │ │ │ │ │ │ │ │ ─────┴─────┴─────┴─────┴──────────┴─────┴─────┴─────┴─────┘ ├─────┤ │ │ 1│ ■──┼─────┘ │ │ │ │ ├─────┤ │ 2│ ■──┼───────────────────────────────────┘ │ │ ├─────┤ 3│ ■ │ NULL (per proposed ANSI C standard, but not done by │ │ all C compilers--don't depend on it yet) └─────┘ FIGURE 3-2 ▐ Command-line arguments Note the declaration of argv in the template for the main() function shown above. The declaration char *argv[]; says that argv is an "array of type pointer to type char." This declaration may also be written as char **argv; which says that argv is a "pointer to a pointer to type char." The net result is the same, but these are not identical declarations. Program Name The name used to invoke a program under DOS version 3.00 and later is available to the program as argv[0] (or *argv, if the pointer has not been moved). Earlier versions of DOS do not save the name used to invoke a program, so most C compilers for DOS substitute a dummy value, such as a null string or c. Being able to retrieve the invoking name can be very useful at times, so if our programs detect the use of DOS version 3.00 or later, we will let them use the name to their advantage. How can the name be used? For one thing, when many programmers are producing programs in diverse locations for the same family of machines and operating systems, it is likely that the same name will be used for two or more programs that come into general distribution. We might like to be able to rename one of two identically named commands to avoid problems. This is easy to do if we have the source code, but it might not work if all we have is the executable program. Moreover, some programs (usually copy-protected programs) will not run if called by a different name. Another problem occurs when a program is renamed because, in most cases, the program name is hard-coded into error and help messages. So if we renamed CP.EXE to CPY.EXE, we might still get an error message like cp: can't open file.txt, which isn't nearly as useful as one that displays the currently used program name. In Chapter 7, we'll find other uses for the command name. And throughout the programs in this book, where it makes sense to do so, we will try to obtain the invoking program name for use in error and help messages. Ambiguous Filenames Microsoft C provides a set of functions to handle the processing of wildcard characters in the formation of ambiguous filenames. Four object files are provided, one for each major memory model, and they may be placed in the default library directory for convenient access. The ssetargv.obj file is used with small-model programs; the csetargv.obj, msetargv.obj, and lsetargv.obj files are used with compact-, medium-, and large-model programs, respectively. The setargv() function expands wildcard characters in the command-line tail according to DOS rules (see the DOS manual for details) and passes them to the program in the form of an argument list. It is then up to the program to sift through the argument list it receives and separate optional arguments from filename arguments. Accessing the Command Line The following program shows how to access command-line arguments, including the program name. The REPLAY program first assumes that it will be called by the name replay but, just in case, it checks to see which version of DOS it is running under. If the DOS major number, obtained from the _osmajor global variable defined in stdlib.h, has a value of at least 3, REPLAY calls getpname() to extract the filename part of the full pathname passed by DOS. If the user renames REPLAY.EXE to something else-- say ARGLIST.EXE--then the program will issue the correct name when it displays the banner line just before displaying the arguments, if any, found on the command line. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 25 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ Notice a few things in this demonstration program. We test for the presence of arguments (if (argc == 1)) and quit with a nonzero exit code if there are none. An argument count of 1 means that only the command name was typed on the DOS command line. This simple precaution prevents us from printing a banner line and nothing more, which would look kind of silly. The temporary pointer p is declared as a pointer to a pointer to a character and is assigned the initial value of argv. When we enter the loop, argv is incremented so that it points past the command-name string to the first optional argument. Each time through the loop, argv gets incremented, so argv - p in the body of the loop yields the number of the current argument and *argv yields the argument string. We could just as easily have incremented p while leaving argv stationary, which would require the argument-number calculation to be reversed (p - argv). The pgm character array is large enough to hold an eight-character name plus a terminating null character. It must be declared static so that it can be initialized to the expected name. We put a name in the array so that if none is available from the operating system, we'll still have one to work with--although there is a small risk that it may be the wrong one, if someone has changed the program name. If _osmajor is 3 or more, we call getpname() to grab the base program name out of the pathname string, which may be anything from a simple filename to a full or relative pathname, complete with drive specifier and extension. (DOS allows pathnames for programs in version 2.00 and later. For the purposes of this book, earlier versions of DOS are considered to be obsolete.) Here is the code for getpname(): ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 26 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The program-name pointer, pname, accesses an array in the calling function that is large enough to hold the filename part (eight characters) of a valid DOS filespec, plus the terminating null byte. The getpname() function receives the full pathname of a file (path), immediately sets cp to the start of path, finds the terminating null byte, and backs up one position. It then moves backward to the start of the filename, which is marked by the beginning of path if the name is a simple filename, or by one of the accepted separators (:, \, or /). Notice that the backslash has to be escaped (\\) to turn off its special meaning. The last thing getpname() does is copy the filename part to pname, stopping when it sees a dot or a null byte. (It is customary in programming to refer to a single . as a dot.) The getpname() function is one we will use often, so it should be put in a place where it can be retrieved easily. We will now start accumulating useful object modules in a library of our own called util.lib, which will reside in a directory called \lib\local on the default disk drive. (Users of other compilers may need to make some adjustments if their compilers do not allow this.) The function is first compiled using the command msc getpname; and then the object file, getpname.obj, is added to the utility library by typing lib \lib\local\util +getpname; Any time we need to use this function, we add the library path to the list of libraries to be searched by LINK. We can automate the process by using MAKE with a script in a makefile routine such as the following one I assembled for the REPLAY program (the use of the MAKE program maintainer is explained in Chapter 1): # makefile for replay program LIB=c:\lib LLIB=c:\lib\local replay.obj: replay.c msc $*; replay.exe: replay.obj $(LLIB)\util.lib link $* $(LIB)\ssetargv $(LLIB)\util; This makefile, called replay.mk, is invoked using the command make replay.mk The MAKE program will take care of the details of recompiling objects and relinking the needed program modules to produce a new executable program. This example is the paradigm for all the programs that follow. Simple programs will be presented with specific compile and link descriptions; I will present makefiles for the more complex programs in later chapters. Pointers and Indirection The source code presented thus far uses quite a few pointers. Many programmers who are new to C language (and, for that matter, quite a few who are not so new to it) have problems with the declaration and application of pointers. Indeed, I have seen entire books written about C programming that sidestep the issue of pointers by using indexed arrays almost exclusively. That may seem a good way to minimize the difficulty one experiences in learning C, but it robs the programmer of one of C's most powerful capabilities and is really an unnecessary limitation. If you are having problems with pointers, try to visualize a pointer declaration in the following way. (We'll use a pointer to a character here because it is commonly encountered.) The line char *cp; declares a character pointer. Place your finger tip over the cp part of the declaration and see what's left (char *). Read this as "cp is a pointer (the *) to a character storage location (the char)." In an expression, then, the unadorned cp yields a storage location that holds a pointer to (the address of) a character. If, however, you cover the *cp grouping, you are left with the type char. This says that when you see *cp in an expression, it yields a character storage location. You can retrieve the value stored there and may assign a character value into the storage location. Look back through the source for getpname(), which is loaded with examples of the variable cp used in both contexts. Once you feel comfortable with single indirection, as this is called, try the same thing with double indirection, such as you encounter with the declaration of the argument vector: char **argv; The illustration in Figure 3-3 on the next page may help to clarify this a bit. If it doesn't come easily to you, don't give up on it. A little practice will make it clear. You have to get a picture in mind of what's happening. In Chapter 6, we will examine user/machine interfaces further. We will introduce a variety of ways of handling command-line arguments and talk about getopt(), an AT&T library routine that attempts to standardize command-line syntax. SINGLE INDIRECTION: ┌──────────────┐ ┌────┬────┬────┬────┬────┬────┬────┬────┐ │ ■───────┼─▒▒▒▒│▒▒▒▒│▒▒▒▒│▒▒▒▒│▒▒▒▒│▒▒▒▒│▒▒▒▒│▒▒▒▒│ └──────────────┘ └────┴────┴────┴────┴────┴────┴────┴────┘ char *s; ░ s yields a pointer to a char ▓▓ *s yields a char DOUBLE INDIRECTION: ┌──────────────┐ ┌──────────────┐ ┌────┬────┬────┬────┬────┬────┬────┬────┐ │ ■───────┼─ ■───────┼─▒▒▒▒│▒▒▒▒│▒▒▒▒│▒▒▒▒│▒▒▒▒│▒▒▒▒│▒▒▒▒│▒▒▒▒│ └──────────────┘ └──────────────┘ └────┴────┴────┴────┴────┴────┴────┴────┘ char **s; ░ s yields a pointer to a pointer to a char ▓▓ *s yields a pointer to a char ▒▒▒ ** yields a char FIGURE 3-3 ▐ Pointers and indirection DOS Environment Variables Another way to get data into a program or to modify a program's behavior is by using variables that are maintained in the DOS environment. To see which variables are in the environment and what their values are, type set at the DOS prompt and view the listing. All environments contain the values of COMSPEC and PATH. On my system, the environment list looks like this: COMSPEC=C:\COMMAND.COM PATH=C:\DOS;C:\BIN;C:\PWP;C:\WP; PROMPT=$p$g PWPLIB=c:\pwp INCLUDE=c:\include LIB=c:\lib TMP=c:\ CONFIG=c:\config FGND=cyan BKGND=blue BORDER=blue From the DOS command line or from within a batch file, a user can add variables to the operating environment by using the SET command. The command set var=val instructs DOS to add the variable var to the environment and assign it the value val. Within a batch file, the value of the DOS environment variable var can be obtained by using the construct %var%. The following batch file, SHOW.BAT, does this to display the values set for foreground and background colors (see Chapter 13 to find out how these values can be used): echo off echo FGND = %FGND% echo BKGND = %BKGND% The initial echo off is used to silence DOS, which displays each line in a batch file before processing it, unless it's told not to. (The default really ought to be echoing off, and many enterprising programmers have patched COMMAND.COM for each version of DOS to disable this echoing.) COMMENT The amount of environment space reserved by DOS (prior to version 3.2) is only 160 bytes. You may want to expand the default space by using SETENV, a utility program supplied with version 4.00 of the Microsoft C Compiler. Some other commercial software products include a program called ENVSIZE, or something similar, but not all C compilers have such a utility. We want to be able to selectively read DOS environment variables into our C programs, and we may even want to change them during the execution of our programs. The library functions getenv() and putenv() allow us to do both of these tasks. The functions use an environment pointer to gain access to the DOS environment. The Environment Pointer Access to the DOS environment is obtained through the global variable environ, or the main() function argument envp. The header file stdlib.h declares the environment pointer as extern char **environ Thus, environ is an array of pointers to environment strings. To add a third argument to main() to obtain a pointer to the environment, you would use the following form: main(argc, argv, envp) int argc; char *argv[]; char *envp[]; { . . . } If envp is declared as an argument to main(), both argc and argv also must be declared because of the way C function arguments are processed. Note that the declarations for argv and envp could be written char **argv; char **envp; because these are functionally identical to the previous declarations. The envp argument to main() is simply a copy of environ at the time the program began execution. If subsequent changes are made to the environment, the global environ variable is kept current, but the value of envp, which is local to main(), is not. Reading from the DOS Environment To read the value of a DOS variable into a C program, use the getenv() function, which returns a pointer to a character string if the variable is defined, or returns NULL if it is not. The following test program, SHOWENV, accepts a list of strings from the user and checks each in turn to see if it is the name of a currently defined environment variable. If it is, SHOWENV displays the string and its value. If not, SHOWENV displays the message "var not defined" and moves on to the next string, if any. If no arguments are given to the command, SHOWENV prints out the entire environment list. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 33 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The library function strupr() is applied to the string being processed, because DOS always converts the variable name to uppercase letters before saving it in the environment. If strupr() were not used, no match would be found if the user typed the string arguments in lowercase letters. Writing to the DOS Environment The process of modifying the DOS environment list is analogous to reading it, except that the putenv() function is called. A return value of 0 indicates success and -1 indicates failure, usually due to a lack of memory in which to write the modified environment. The program SETMYDIR attempts to add the variable MYDIR to the DOS environment by calling setenv(). ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 34 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ Please note that putenv() modifies the environment in which the current process is running (the environment inherited is a copy from DOS), but it does not change the original DOS environment. To observe this, compile the SETMYDIR program. Then run a SET command to list the starting environment (assuming you don't already have a MYDIR variable), run the SETMYDIR program, then run the SET command again. You'll see the MYDIR variable come into existence while the program is running, then it will disappear when the program stops executing. CAUTION Be careful to assign values into the environment correctly. The form of the SET command is rigid. No white space (space, tab) is permitted on either side of the equal sign. If spaces or tabs are inserted, neither getenv() nor the %var% batch-file mechanism will recognize that the variable is defined. The ability to modify the environment passed to a running program is important. A program can, for example, set up its own private PATH so that it can access its own set of commands while running, without disturbing the user's normal environment, which is restored when the program terminates. That's about it for the DOS-to-C connection via command lines and environment variables. We'll be using these connections extensively in our programs, so spend some time getting familiar with the techniques and routines described in this chapter. In the next chapter we will take a much closer look at some of the standard library routines that are part of the run-time library of the C compiler package. SECTION II Standard Libraries and Interfaces Chapter 4 Using Standard Libraries C has no built-in input/output capabilities; all I/O operations are handled by external functions. Neither does C have any built-in stringhandling facilities or mathematical functions. This is not a deficiency, but rather it is a benefit that permits each C compiler implementation to use features and capabilities of the host hardware and operating system, while presenting the same external interface to programs. All such facilities are external to C and are handled by routines (functions and macros) that typically reside in special libraries, which are collections of often-used routines. The UNIX heritage of C has produced a large body of ready-to-use routines that have successfully made the trip to DOS despite some significant differences in the underlying operating systems and their supporting environments. The routines mask the differences by providing a clean, consistent, and fairly well-documented interface to programs. In this chapter, we will explore a small selection of the hundreds of routines in the standard C run-time library and use them to construct some simple but useful programs. Other library routines will be introduced in later chapters as the need for them arises. Why Use Libraries? Simply put, the standard libraries give us a reasonable degree of program portability, provide consistent and predictable interfaces, and, most important, reduce programming effort. Out of the millions of lines of C code that have been written over the years, certain operations have been programmed over and over again. Just a few obvious examples include: opening and closing files; reading and writing characters; detecting errors and displaying relevant messages; splitting, concatenating, and copying strings; and managing a hierarchy of directories and files. In the standard libraries, many of these operations have been highly refined for speed, flexibility, and applicability to a wide range of situations. I prefer to use something that exists, if it works, rather than start from ground zero. Therefore, this book will concentrate on using the run-time library provided with the compiler wherever the library routines will do the job. We will develop mid-level and high-level routines that depend on standard libraries to carry out the low-level work. In all but a few special cases, we will avoid creating new low-level functions--it is simply not necessary most of the time. The portability issue is often the basis of religious debate, something I wish to avoid because it is a waste of valuable time and energy. The portability I strive for in the C programs in this book is that needed to move a program among the various MS-DOS and PC-DOS systems, to extensions of the DOS environment such as Windows, and to a lesser degree, to XENIX and other UNIX-like systems. In some cases, I will sacrifice portability to achieve a high level of performance under raw DOS because that's what will "sell" best for a given application. To go for complete DOS/UNIX transparency requires that some of the nicer features of a PC must be forsaken so that programs will run on any terminal type that can be connected to a multi-user system. In particular, this usually means saying good-bye to the use of function keys, arrow keys, attractive line-drawing characters, and fast screen updates. Going for the best performance on a PC usually means sacrificing portability to UNIX for such screen-intensive applications as a programmer's editor. However, careful design can minimize the effects of most of the differences between DOS and UNIX. The use of standard libraries goes a long way toward ensuring DOS/UNIX portability because of the effort Microsoft and other C compiler vendors have placed on providing compatible libraries. The differences among vendors' libraries usually occur in PCspecific low- level interfaces. Although I will discourage the use of such PC-specific functions in programs designed for general use, they are the subject of Chapter 5 and will be used in some of our programs. Exception Handling Some days, things just don't seem to go right. Ever had one of those? Well, programs have days like that, too. As programmers, we have a responsibility to our programs to build in some way of dealing with unexpected events. This is called exception handling and is an essential component in the development of commercial-quality programs. Exception handling has two parts: detection and recovery. The standard library functions attempt to detect errors and inform calling functions about them. It is up to us to build in the appropriate recovery procedures, even if that simply means giving up on a task, which is sometimes all we can do. One of the more common error conditions is the absence of a needed file. The fopen() function, for example, tries to open a named file. If asked to open a nonexistent file for reading, fopen() returns NULL instead of a valid file pointer. What's the appropriate response to this error condition? At the very least, we may want to inform the user about the missing file. If the error occurs in a loop that is processing a list of files, we may choose to print a brief but informative message ("file XYZ.C not found") to stderr before moving on to the next name in the list. In other circumstances, it may be best to print the message and terminate processing with an ERRORLEVEL (exit code), to tell DOS that something is wrong. Standard Library Error Functions A set of standard library functions assists us with exception handling. A global variable, errno, holds the number of the most recent error. This number is used as an index into an array of error messages, sys_errlist. (The message associated with error number 0 is "Error 0," a catchall for errors not described elsewhere.) Rather than access errno and sys_errlist directly, we can call on perror() to print the error message to the standard error output. The manual page summary of perror() is: #include <stdlib.h> void perror(string); char *string; where void indicates that there is no return value and string is a pointer to a message that we provide. COMMENT Compilers that do not adhere completely to the proposed ANSI C standard may not support the void data type (or lack of type, in this case) for functions. It may be necessary to use the following typedef to compensate for this deficiency: typedef int void; Calls to void functions will actually return an integer that can safely be ignored. The output of perror() is the string we provided, followed by a colon, a space, the text of the system message for the most recent error, and a trailing newline, all sent to stderr. Thus, the statement perror("File error"); if triggered by an attempt to open a nonexistent file for reading, produces the following output on the screen: File error: No such file or directory Appendix A of the Microsoft C Compiler Library Reference Manual lists the errno symbolic constants used under MS-DOS, the message text for each, and a description of each error. The DOS error messages are necessarily a subset of the error messages used by UNIX and XENIX. See your own C compiler library documentation for a detailed description of each error and message. Ambiguous Return Values Two macros, ferror() and feof(), are used to resolve an ambiguity that is produced by certain standard library routines: Because they are designed to return a pointer to a character, functions like fgets() (which we will use in an example shortly) must return NULL to indicate either that an error has occurred or that the end of the file has been reached. We need to take additional steps to determine which condition caused the NULL return value before we take any action. The manual page summary of ferror() is #include <stdio.h> int ferror(stream); FILE *stream; where stream must be the file or stream associated with the NULLreturning routine. The summary for feof() is the same except for the macro name. The ferror() macro returns a nonzero value to indicate that an error condition exists and feof() returns a nonzero value if the end of the file has been reached, thus resolving the ambiguity of the NULL value. The following code fragment illustrates a way of handling the ambiguous return: . . . errcount = 0; while ((s = fgets(line, BUFSIZ, fp)) != NULL) { /* process the line */ . . . } if (ferror(fp)) { perror("Read error"); clearerr(fp); if (++errcount >= MAX_ERR) { fprintf(stderr, "Too many errors\n"); exit(1); } } . . . Notice the use of clearerr() in the preceding fragment. Once an error occurs in a stream, the error indication remains until the stream is closed or until the indication is intentionally cleared by using either clearerr() or rewind(). In the foregoing example, we clear the error indication and allow some maximum number of errors (MAX_ERR) before giving up. On the other hand, if the NULL is the result of having reached the end of the file, we fall through to other processing. A common programming procedure is to display an error message and then call exit() to flush output buffers and return to the operating system with an exit code that indicates an abnormal termination. For convenience, we will package these statements into a function called fatal(), which displays the program name, the message text, the system error message, and a newline. This will usually provide enough information to the user to help determine the cause of the abnormal exit. /* fatal -- issue a diagnostic message and terminate */ #include <stdio.h> #include <stdlib.h> void fatal(pname, mesg, errlvl) char *pname; /* program name */ char *mesg; /* message text */ int errlvl; /* errorlevel (exit code) */ { fputs(pname, stderr); /* display error message */ fputc(':', stderr); fputc(' ', stderr); fputs(mesg, stderr); fputs('\n', stderr); /* return to DOS with the specified errorlevel */ exit(errlvl); } The fatal() function doesn't return to the calling function, hence the void return type. The errlvl value should be nonzero--a small positive integer--to indicate an abnormal termination. The specific values used for errlvl should be documented in a manual page for the program. Operating System Interrupts Another type of exception is an interrupt from the operating system, usually caused by the user pressing Ctrl-Break or Ctrl-C. The library function signal() can be used to control how such interrupts are handled. The summary for signal() is #include <signal.h> int (*signal(sig, func))(); int sig; int (*func)(); This bizarre-looking declaration is not a misprint. The line int (*func)(); declares a pointer to a function that returns an integer. This is not the same as int *func(); which declares a function that returns a pointer to an integer. The declaration of signal() also is a pointer to a function that returns an integer. The only value for sig permitted under DOS is SIGINT, #defined in the signal.h header file. SIGINT is the DOS Ctrl-Break interrupt. Other signals, including SIGHUP (hangup) and others that apply under the multitasking UNIX and XENIX operating system, currently have no meaning under DOS. One of three responses to the interrupt can be specified in the func argument. A value of SIG_IGN causes the interrupt to be ignored. We might choose to ignore the DOS Ctrl-Break interrupt during all or a portion of the lifetime of a program to prevent the user from aborting some critical operation. For example, it is unwise to let the user break out of a text editor without first presenting the opportunity of saving changes that were made to the editing buffer--it could be that the user was fumbling for, say, Ctrl-D to move the cursor right and hit Ctrl-C by mistake. I know, I've done it myself! Second, a func value of SIG_DFL causes the running program to abort upon receipt of the interrupt, closing all open files and returning control to DOS. Buffers are not flushed. This is usually what will happen if you don't use signal(), unless you are using DOS functions that ignore Ctrl- Break by design (see Chapter 5). A third type of response is to provide a pointer to a signal-handling function. This is referred to as signal catching and is more of an art than a science. The safest method of signal catching simply cleans up any work in progress and makes a graceful exit. It either accepts the default treatment or, in a few cases, simply ignores the interrupt. A return value of -1 from signal() flags an error, errno = EINVAL, which says that the sig argument is invalid. This identifies a programming problem that should be corrected before any user ever sees the program. Time Functions The standard library provides several routines for retrieving and converting time values. The UNIX ctime subroutine package and the time() system call are available as functions in the Microsoft C run-time library for DOS. Because these functions have received very little attention in books about DOS, we will give them a moment in the spotlight. The time() function returns the number of seconds that have elapsed since 00:00:00 GMT (Greenwich mean time) on January 1, 1970. This date and time is called the epoch. GMT is now officially called Universal time (UT), but the use of the term GMT is likely to continue indefinitely, just as core is still used to mean main memory, even if it's all solid state. File- modification times and other times and dates that are visible to the user are presented as local time values. The declaration of time() is #include <time.h> long time(timeptr); long *timeptr; /* (usually NULL) */ The time() function takes a pointer to long as an argument and produces a long return value. The argument can always be the NULL pointer. Before C had a long data type, it was necessary to provide a suitable buffer for the time value. Passing the address of the buffer synthesized a "call by reference" (C uses "call by value" for parameter passing). Now the application of time() simply assigns the return value to a long integer. Time Conversions The long time value is wonderful for the computer, but we humans don't often tell someone what time it is as a number of seconds since the epoch. A more convenient notation for us is a character string that spells out, at least as abbreviations, what the date and time are. We need some convenient way to make a conversion from the long value to a character string. We also have to deal with Universal time and local time and with the complications of daylight saving time. Figure 4-1 shows the relationships of the time() function and the functions that constitute the ctime subroutine package. Two functions, gmtime() and localtime(), can be used to convert values from the long result of time() to time structure pointers. The DOS time structure template, struct tm, defines a set of variables of type int that can hold hour, minute, second, month, day, and year values, plus a flag for daylight saving time and numbers for day-of-week and day-of-month calculations. This time structure template is defined in the file time.h. RELATIONSHIPS: ┌──────────┐ ┌───── ├──────────────────────────┐ │ │ ctime() │ │ │ └──────────┘ │ │ │ ┌────────┐ ┌──────┐ ┌───┴───┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌───────┐ │▒system▒│ │ │ │▒▒▒▒▒▒▒├─ ├─▒▒▒▒▒▒▒▒▒├─ ├─▒▒▒▒▒▒▒▒│ │▒▒time▒▒│ │time()│ │▒long▒▒│ │gmtime() │ │struct tm│ │asctime()│ │ string │ └────────┘ └──────┘ └───┬───┘ └─────────┘ └────────┘ └─────────┘ └────────┘ │ │ │ ┌───────────┐ │ │ │ │ │ └─────localtime()├─────┘ └───────────┘ ════════════════════════════════════════════════════════════════════════════ ┌──┐ LEGEND: ▒▒▒ = data type │ │ ▒▒▒ └──┘ = ctime package function FIGURE 4-1 ▐ Time and date functions and variables Time and date information in the structure is easy to access and use, but it is still not suitable for human consumption. Both gmtime() and localtime() return pointers to a time structure. The declarations for these functions are #include <time.h> struct tm *gmtime(time); long *time; struct tm *localtime(time); long *time; CAUTION These two functions use a single statically allocated structure. Any call to one of these functions, therefore, will overwrite the result of any previous call to either function. While gmtime() always returns a direct conversion of the time value returned by time(), localtime() does some additional adjustments to compensate for the difference between GMT and the time zone set into the DOS environment via the TZ variable. If TZ is not explicitly set (it usually isn't), then Pacific time is used. I am willing to wager that nearly every PC running DOS today thinks it is in Redmond, Washington! We'll see shortly how you can tell your PC where it really is, but first we need to examine how to convert the time structure data into strings we can read and understand. Creating Strings The function asctime() takes a pointer to the time structure and converts the structure members to a 26-byte string. The format of the string is Sat Jul 12 13:05:33 1986\n\0 where \n is a newline character and \0 is the terminating null byte. Each character should be surrounded by single quotes to show that it is a character constant. Rather than clutter the displayed string, I'll just ask you to imagine the quotes there. The function ctime() provides a shortcut for creating a local time string. It takes a long time result from time() and returns a pointer to a character string of the format described above. Its declaration is #include <time.h> char *ctime(time); long *time; CAUTION The character string pointed to by ctime() is the same statically allocated string pointed to by asctime(). A call to one of these routines destroys the result of any previous call to either of them. Time Zones Now on to the subject of time zones. A DOS environment variable called TZ can be set to reflect the time zone in which a PC is operating. Adding a line like set TZ=MST7MDT to my AUTOEXEC.BAT file tells DOS that my machine is running in the mountain time zone, that there is a 7-hour difference between mountain standard time and Greenwich mean time, and that daylight saving time is honored in this zone. Several other variables are also maintained by the ctime() subroutine package. They can all be updated by a call to tzset() (or to asctime(), which calls tzset()). These variables are ═══════════════════════════════════════════════════════════════════════════ VARIABLE MEANING ─────────────────────────────────────────────────────────────────────────── int daylight; │ Daylight savings time flag long timezone; │ Difference from GMT in seconds char *tzname[]; │ timezone strings ────────────────────────┴────────────────────────────────────────────────── If a daylight string is set in the TZ variable, daylight is set to a nonzero value. The value of timezone is the difference in seconds between local standard time and GMT. The variable tzname is an array of pointers to character strings. The first (tzname[0]) is a pointer to the three-letter string for the standard time zone and the second (tzname[1]) is a pointer to the daylight string (e.g., MDT) if one was specified. The last element (tzname[2]) is a NULL pointer that typically terminates an array of pointers. If no TZ setting is done at boot time, the ctime package uses PST8PDT as a default. When compiled and run, the following little program, TIMEDATA, shows some of the time-related values for your system. Don't be surprised to see Pacific time zone data even if that is not your "home" time zone. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 49 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ Here is an example of the output of TIMEDATA taken from my system in Denver, Colorado: daylight savings time flag = 1 difference (in seconds) from GMT = 25200 standard time zone string is mst daylight time zone string is mdt ctime(): Mon Feb 16 06:19:33 1987 local time: Mon Feb 16 06:19:33 1987 universal time: Mon Feb 16 13:19:33 1987 If you accept the Pacific default for timezone while operating in a different time zone, there is usually no harm done. The effect of not setting TZ is that you are fibbing about the local time, which will cause DOS to have an incorrect notion of what GMT is. For example, had I let TZ default to PST8PDT and set local time correctly for Denver, the system value for GMT would be off by one hour. However, problems might occur for systems connected into wide-area networks that must keep accurate track of file-modification times and various other timed events, possibly while crossing several time zones. In such cases, all connected systems should have the correct time zones set in the TZ variable and agree on what the value of GMT is. Getting a time-and-date string is a first step for us in the development of a program called NOTES, a simple electronic diary. But we will also need a way of creating and modifying files before we can assemble a working prototype, so let's talk about that next. Basic File and Character I/O Functions Much of what we will do in the rest of this book will involve some interaction with disk files. There are many standard I/O routines in the C run-time library that deal with files on various levels. In this section, we will review some of the more frequently used functions. Then we will create a useful demonstration program. The run-time library provides access to disk files and other I/Ostreams using DOS file handles. These functions--open(), close(), read(), write(), lseek(), and so on--are analogous to the UNIX system calls of the same names that use file descriptors. These functions are unbuffered from a user's perspective, although the operating-system kernel may anticipate read operations and delay write operations to minimize disk-head movement, and improve I/O efficiency. Buffered I/O Another level of file access is the set of standard library subroutines that do buffered I/O. The functions fopen), fclose(), fgetc(), fputc(), fgets(), and fputs() are representative of this level, and are used extensively in the programs in this book. These functions use a file pointer that points to a structure of type FILE. The FILE structure template is defined in stdio.h, the header file that is included in all source files that use standard I/O library functions. All file-access functions will be covered at one time or another in programs later in the book. For now, we'll concentrate on the buffered I/O library functions. By way of example, here is a fairly typical use of the standard run-time library in a program called NOTES, which lets us keep an electronic notebook or diary. This first version, NOTES1, is a simplified prototype. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 52 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ This program, although rather simple and not yet fully developed, is immediately useful in its current form. It takes input from the keyboard and appends it to a "notesfile" in the current directory. The program is invoked by typing NOTES on the DOS command line. Each new session starts by placing a blank line and a date/time stamp at the end of the data file, currently hard-coded into the program as NOTES.TXT. Text input is simply typed at the keyboard and terminated by the user typing a Ctrl-Z (end-of- file) character on a line by itself. This simple version of NOTES allows no options. If you make an error while inputting text, you must back up and correct it before moving off the line. To edit the NOTES.TXT file, you must leave the NOTES program and call upon some text-editing program. We will embellish the NOTES program with additional features in later chapters, but for now we will accept its limitations and treat it as a learning aid. The call to fopen() is interesting. The function will open the named file for appending if the file already exists, or it will silently create the file if it doesn't exist. The call returns a valid FILE pointer if the file is opened successfully, or NULL to flag an error. (Attempting to open a directory, for example, produces an error.) Our program must be prepared to deal with errors. Therefore, at the risk of having our programs look like LISP source code, we will always test the return value of I/O functions. To ignore this extra bit of work is not simply bad programming practice; it can be dangerous. A program that fails without a whimper is not apt to inspire strong feelings of trust in its users. The declaration of fopen() is #include <stdio.h> FILE *fopen(pathname, type); char *pathname; char *type; The pathname argument may be a simple filename and optional extension, or a full or relative pathname with an optional leading drive specifier. The type argument is one of the following: ═══════════════════════════════════════════════════════════════════════════ ARGUMENT MEANING ─────────────────────────────────────────────────────────────────────────── r │ Open for reading (file must exist) w │ Open for writing (create or truncate) a │ Open for appending (create if necessary) r+ │ Open for both reading and writing (the file must exist) w+ │ Open for both reading and writing (create or truncate) a+ │ Open for reading and appending (create if necessary) ─────────────────────────────────────────────────────────────────────────── The optional + within the type string specifies update mode, in which both reading and writing are allowed. The file pointer must be set by an intervening call to fseek() or rewind() when switching between read and write operations or vice versa. Unlike UNIX and XENIX, which use a single newline (NL) character to terminate a text line, DOS uses a carriage-return character (CR) plus a linefeed (LF) character. The codes to NL and LF are identical (ASCII code 10), so you will usually see the DOS end-of-line treatment described as CR/NL, but it is really CR/LF. Technically, LF moves down a line but retains the same column position, so a CR is needed to get back to the first column. The NL code convention achieves the two tasks in a single operation, saving a byte per line in ordinary text files. Both methods of terminating a line are allowed by the ANSI standard (see Chapter 13 for more information about ANSI standards). In addition to a different end-of-line treatment, DOS uses an explicit Ctrl-Z (ASCII code 26) to mark the end of a file. (Under UNIX and XENIX, the end-of-file condition is sensed when an attempt is made to perform an operation beyond the last position in a file, which is known because an exact size is maintained for each disk file.) The conventions just described for DOS text files do not apply to binary files (executable program files, for example), which can contain any arbitrary bit patterns in any position. For binary files, all bits are significant, and an accurate file size must be maintained by DOS so it knows where the end of the file is. To maintain compatibility with existing C programs, UNIX textfile conventions are used within C programs under DOS. When a file is opened, the differences are specified by a text (t) or binary (b) flag appended to the type argument to fopen(), or by the global _fmode translation-mode variable if neither t nor b is explicitly specified. The default for _fmode is text-translation mode. We can use separate statements for the processing and the errordetection phases of each call to a library routine: FILE *fp; fp = fopen(notesfile, "a"); if (fp == NULL) fatal(pgm, notesfile, 1); This is rarely done, however. You are more likely to see this written in the condensed form (shown in notes1.c, on page 52) which is the de facto convention for embedding assignments that is used by many, but by no means all, C programmers: FILE *fp; if ((fp = fopen(notesfile, "a")) == NULL) fatal(pgm, notesfile, 1); Don't let "convention" sway you, however. Use whichever form looks pleasing to your eye. Just be sure the statements are logically correct and that error conditions are checked and responded to in a reasonable way. The getchar() and putc() calls are actually macros defined in stdio.h. These calls tend to work somewhat faster than the equivalent functions, fgetchar() and fputc(), because they expand to in-line code and eliminate the function-call overhead associated with true functions. However, if we had many calls to putc() and getchar() (which is just getc() with stdin specified as the stream), we would save some space by using the functions because the code for the function only has to appear one time in the object file, rather than once for each call to the macros. Rather than clutter this chapter with information that is available to you in the C compiler's Library Reference Manual, we'll just refer to that document (or the equivalent for other C compilers) for more details and move on to some other interesting topics that are essential to the development of our programs. Process Control Functions A process is an environment in which a program executes. When you run the NOTES.EXE program, for example, DOS allocates an instruction segment, a user data segment, and a system data segment. It then initializes the instruction and data segments from the program and starts execution. The Microsoft C run-time library provides a group of functions for controlling the execution of processes from within a process. The easiest to use is system(), which takes a program-name argument (may be a full or relative pathname) and runs the named program as a subprocess. When the subprocess terminates, control is returned to the calling process. The declaration of system() is #include <process.h> int system(string); char *string; where the string argument is the name of a built-in DOS command or an external program that must be in the current directory or be accessible via the PATH variable. DOS must be able to find and load COMMAND.COM to service the system() call. A return of -1 indicates an error. A simple example of the system() function in use is the following code fragment that calls a text editor from within a running process: . . . if (system("EDIX") == -1) { perror("System error"); /* error recovery procedure */ . . . } An error return could be caused by the absence of a valid COMMAND.COM file or by the inability of DOS to find the EDIX.EXE file with the information provided by the system() call plus the current value of PATH. The exec() and spawn() families of process-control functions are more complicated to use, but they provide considerably more versatility. The two families have much in common and each has six members. The base function name--exec, for example--takes a one- or two-letter suffix to fully specify the function's behavior. Thus, the exec() function names are execl(), execle(), execlp(), execv(), execvp(), and execve(). The symbols appended to the base function names have these meanings: ═══════════════════════════════════════════════════════════════════════════ SUFFIX MEANING ─────────────────────────────────────────────────────────────────────────── l │ Uses a NULL-terminated list of arguments v │ Uses a variable list of arguments e │ Receives an environment pointer p │ Searches PATH to find program files ─────────────────────────────────────────────────────────────────────────── Rather than show all six function declarations for each of the families, we'll look at one representative function of each. Both of these functions automatically pass along a copy of the current environment to the child process. Here is the declaration for execl(): #include <process.h> int execl(pathname, arg0, arg1, ..., argn, NULL); char *pathname; char *arg0, *arg1, . . .,*argn; The declaration for spawnvp() is #include <process.h> int spawnvp(modeflag, pathname, argv); int modeflag; char *pathname; char *argv[]; The exec() family always overlays the current process (parent) with a new process (child) that destroys the parent, so it is impossible to return from an exec() function call. The spawn() family, however, runs the subprocess with an action determined by the modeflag parameter. A value of P_WAIT causes the parent process to suspend execution while the child runs. When the child process terminates, control is returned to the parent. A spawn() call with a modeflag value of P_OVERLAY produces the same effect as the equivalent exec() function call. Arguments are handled differently for the fixed-list (l) and variable- list (v) versions of these functions. The fixed-list version is used when we know in advance how many arguments will be presented. We place a NULL argument after the last argument we want to pass, to tell the exec() or spawn() function that the list is complete. In the variable-list version of the functions, a pointer to an argument list is passed. The argument list is handled just like the argv of a program's main() function, which was described earlier in this section. The first argument in a fixed list (arg0) or a variable list (argv[0]) is usually a copy of the pathname argument. Other values will not cause an error, but NULL should not be used in the first position of a fixed list: The NULL would effectively hide the remainder of the list from the child process, since a NULL argument marks the end of the list. Recall that under DOS version 3.00 and later, the program name is available to the child as arg0 or argv[0]. Here is an example of the spawnvp() function in action. It is used to run a text editor as a subprocess. If an EDITOR environment variable is defined, its string value is used as the program name. If EDITOR is not defined, NOTES uses the DOS EDLIN program. The editor is given the name of the current notesfile as an argument. This update to the NOTES program also adds an alternative way of terminating input (using a dot alone on a line like the UNIX mail program) and a way of ignoring the Ctrl-Break interrupt so that a user cannot garble the NOTES.TXT file by interrupting it in the middle of text entry. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 58 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The source listing for NOTES contains a few things we haven't shown before. First, the signal() function is used to disable the Ctrl-Break input from the keyboard. Since signal() returns a pointer value of -1 on errors instead of the usual NULL, we need to use the strange-looking cast of the value on the right side of the comparison. The (int(*)())-1 is needed because the C compiler expects a pointer to an integer. Second, the dot (.) is used to terminate data input. This involves a slight complication. A dot usually does not occur in free text as the first character of a line, but it may occur anywhere else. We depend on this, and check that the current position is the beginning of a line and that the input character is a dot before terminating data entry. Third, the EOF signal (a typed Ctrl-Z) may be used anywhere to halt data entry. It should, however, be used only on a line by itself. If Ctrl-Z is typed following some text on a line, some programs will not accept the line because it is not properly terminated. Programs should be written to handle this situation, but many insist that each line in a text file end with a CR/LF combination and may fail in unpredictable ways if a line dead- ends without the expected termination. The next program, RUN_ONCE, is a bit of a novelty, but it has a purpose in some restricted circumstances. Let's say you have an office setting in which computer users with very limited experience are expected to run a single program, perhaps an integrated database-spreadsheet-word processor-blender-and-kitchen-sink program. You want the system to come up running this program and you also want to prevent the users from exiting to DOS. If they quit the catchall program, the RUN_ONCE program tells them to turn off the power and then it locks up the machine. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 62 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ After compiling this program, try running it on your favorite text editor or some other program. For example, run_once word myfile.doc loads and executes the RUN_ONCE program, which spawns Microsoft Word with MYFILE.DOC as an argument. When the user quits Word, the system displays the exit message and appears to be dead. A reboot is required to restart the system. If the RUN_ONCE program is embedded in the AUTOEXEC.BAT file, it will prevent the users from doing anything except what is planned for them by whoever sets up the system. (This is easily defeated by someone who knows DOS. All that is required is to load a floppy disk with another copy of DOS that does not have the RUN_ONCE program installed. But someone who knows this probably knows how to use DOS anyway.) Other Library Functions We have barely scratched the surface of the standard run-time library provided with the Microsoft C compiler. Our purpose has been to describe some representative library routines and to illustrate their use in real programs. As we develop programmer's utilities and other programs in the remainder of this book, we will introduce more of these routines in context. The functions and macros we have looked at so far are portable, with little or no change, to various versions of DOS and to UNIX-based operating systems. The next chapter delves into functions that are tied intimately to DOS and are therefore not easily ported to other operating environments. Although they lack portability, the functions are important for programs that need to obtain the highest level of performance possible from a PC. Chapter 5 PC Operating System Interfaces For me, one of the joys of working with a personal computer, after having spent years working on time-sharing systems over slow-speed data lines, is the incredible responsiveness of the PC in terms of screen updates. To "paint" a 24-line screen at 9600 bps (bits per second) typically takes about 4 seconds--not too bad, really. But at the more common 1200 bps used by most dial-up connections, a complete paint job takes closer to 16 seconds. Paging through a document or a source list at this speed becomes a bit of a chore, and one quickly learns how to use regular expression searches, small window sizes, and other tricks to minimize the time it takes to find the material of interest. In contrast, using one of the slowest methods available on a PC, the DOS print-character function call, painting a full 25-line screen takes only about 4 seconds. By using BIOS routines intelligently, one often can do the job in less than half a second. Using direct screen access, the updates become virtually instantaneous. The PC has spoiled me, and it is really hard to go back to dial-up operations: It feels like the whole world has been put into slow motion. In this chapter, we'll explore methods of managing screen displays via the DOS and BIOS interrupt services. The methods used here are not portable to UNIX and XENIX, and the BIOS routines are not even guaranteed to be portable to some nominally IBM-compatible hardware. This material is presented to acquaint you with some of the techniques used in commercial-quality programs. The mark of such programs is how well they serve the user's needs. Among the needs I hear most often expressed, the following are related to screen and system configuration: The program must work on any compatible machine, regardless of the configuration (disks, display type, and so forth). The screen must be updated quickly_no growing old waiting around for the next frame. If both color/graphics and monochrome display systems are installed, it must be possible to choose which to use. There must be no flickering, blizzard effect, or other visual "noise" at any time. Using DOS and BIOS routines, we can satisfy these needs almost completely. Only the first one is a problem because some machines were designed in a way that limits their BIOS compatibility. As a developer, I want to maximize the audience, so I address such machines by using the ANSI device driver, which is covered in Chapter 13. The routines in this chapter cover needed functions that are not already handled by the standard run-time library, with a few exceptions. In those few cases, a function is presented that duplicates a system function because that function may not be available in the library of other C compilers. A case in point is kbhit(): The function keyready() performs the same function for those whose libraries don't have kbhit() available. We begin with an overview of the DOS and BIOS access routines in the standard library. These routines are the low-level access functions upon which our interface routines are built. Then we will write a program that shows how to use many of the routines we develop. The routines presented here are not a complete set; they are the high-use routines that we will need shortly. Other routines will be added to the DOS and BIOS libraries as we need them in later chapters. System Interface Functions The C run-time library provided with Microsoft C contains several low- level system-access functions. We will use three of them as a basis for our DOS and BIOS interfaces: bdos(), int86(), and intdos(). The functions int86x() and intdosx() are used in programs that use long addresses. They behave just like their int86() and intdos() counterparts, but they take an additional argument that specifies segment registers used in forming long addresses. The segment register values can be obtained by using the segread() function. The file dos.h in the \include directory contains several structure and union definitions that are needed by the system access functions. If you are not comfortable using C unions, here is a good example of how they may be used. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 67 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The header file defines two structures for the CPU registers and flags. The first is struct WORDREGS: /* word registers */ struct WORDREGS { unsigned int ax; unsigned int bx; unsigned int cx; unsigned int dx; unsigned int si; unsigned int di; unsigned int cflag; }; The second structure is struct BYTEREGS: /* byte registers */ struct BYTEREGS { unsigned char al, ah; unsigned char bl, bh; unsigned char cl, ch; unsigned char dl, dh; }; A composite word/byte register data structure is made by overlaying the two structures, like this: /* general purpose registers union - overlays the corresponding word and * byte registers. */ union REGS { struct WORDREGS x; struct BYTEREGS h; }; The union REGS lets us access the registers either as bytes (AL, AH, and so on) or as words (AX, BX, and so on). We can also access the system carry flag as a word register. It is unfortunate that we don't have similar access to the zero flag. Now that we have the data structures in mind (or at least on paper), we can examine the primary system-access routines. Each is presented here with a manual-page summary and a brief description. In the next two sections, we will apply these functions to the task of creating our DOS and BIOS libraries. Any file that calls the following functions must include the header file dos.h by using the line #include <dos.h> Here are the system-level functions: int bdos(dosfn, dosdx, dosal); int dosfn; /* function number */ unsigned int dosdx; /* DX register value */ unsigned int dosal; /* AL register value */ The bdos() function is a DOS function interface that loads the DX and AL registers with values provided by the caller and then executes an INT 21H. Following the DOS function call, the value of the AX register is returned to the caller. The uses of bdos() are limited to DOS function calls that take arguments in either or both of the DX and AL registers (or none at all) and that do not use the carry flag to indicate errors. To minimize function- call overhead, we will use bdos() in some keyboard functions and recommend its use for macros or for in-line code within a program. int int86(intno, inregs, outregs); int intno; /* interrupt number */ union REGS *inregs; /* register values on call */ union REGS *outregs; /* register values on return */ The int86() function is a general-purpose interface routine that gives us nearly complete access to the full range of software interrupts. The function sets up the registers according to the caller's wishes and executes the specified interrupt. Upon return from the function call, int86() fills outregs with the current register values and the value of the system carry flag, which will have a nonzero value if an error has occurred. We will use int86() to call BIOS routines for video and keyboard access and to check equipment and memory information. We also could use it to access DOS functions, but intdos() does the job faster. int intdos(inregs, outregs); union REGS *inregs; /* register values on call */ union REGS *outregs; /* registers values on return */ The intdos() function is just like the int86() function except that it is designed to make DOS function calls directly and does not require an interrupt number. The INT 21H interrupt number is effectively hard-coded into intdos(). The same input and output register behavior is observed as for int86(). The declaration of the register arguments to int86() and intdos() shows them as pointers. The union and structure definitions in dos.h do not reserve storage; they simply describe the needed storage requirements. We must declare storage in our routines by a statement like union REGS inregs, outregs; This statement allocates automatic storage for the unions. We then can load values into inregs, make the needed function call, and extract data from outregs. (There is nothing sacred about the names inregs and outregs. Use anything that seems appropriate, but ideally the names should be descriptive.) The int86() and intdos() functions need the addresses of the unions. A call to intdos() looks like this: intdos(&inregs, &outregs); We can access elements of the structures either as bytes or as words. To load a value into AL, for example, we use the byte-oriented approach: inregs.h.al = value; To read the results of a function from the DX register, we use the word- oriented approach: value = outregs.x.dx; Next, we will put these system-level library functions to work for us in two important libraries in our growing collection of function libraries. DOS Library Routines The DOS library is composed of only a few routines that supplement the standard run-time library, which is very complete in its coverage of disk, keyboard, date/time, and many other functions. The routines presented here are primarily for the benefit of those who are using C compilers with libraries that do not fully support the DOS interface. A local header file, doslib.h, contains constants used to specify DOS interrupts and the function numbers for calls to INT 21H, the DOS "umbrella" interrupt. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 72 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ DOS Version Number Under Microsoft C, the header file stdlib.h defines the global variables _osmajor and _osminor. These variables receive the DOS major and minor version numbers when a program starts running. The numbers may be used to verify that the version of DOS is capable of supporting features required by a program. For example, programs that use pathnames require DOS version 2.00 or later. The simple block of code added to the program provides low-cost insurance and alerts the user that it's time to upgrade. if (_osmajor < 2) { fprintf(stderr, "Need DOS 2.00 or later\n"); exit(1); } Another way to get the version number is to ask DOS for the number. The function ver() does the job. /* ver -- get the MS-DOS (or PC-DOS) version number */ #include <local\doslib.h> /************************************************************ * For MS-DOS versions prior to 2.00, the low byte (AL) of * the return value is zero. For versions 2.00 and beyond, * the low byte is the major version number and the high * byte (AH) is the minor version number. ************************************************************/ int ver() { return(bdos(DOS_VERSION, 0, 0)); } The ver() function uses bdos() to get the version number from DOS. It returns the return value from bdos(), which is the value in the AX register. AL holds the major version number and AH holds the minor version number. For versions of DOS prior to version 2.00, the returned major number is 0. Keyboard Functions The run-time library includes a couple of functions that read from and test the keyboard buffer. This section presents some alternative functions that do essentially the same jobs and which can easily be modified for use with other compilers. To gather the user's input, we can call the run-time library function getch(). It reads the next available character from the keyboard buffer and responds to a Ctrl-Break. If there is nothing ready to read, it waits until there is. This operation is called a "blocking read" because the machine simply marks time while waiting for the user to type something. If the user presses Ctrl-Break, getch() executes the Ctrl-Break handler. The function getkey() also does a blocking read. However, it differs from getch() in a few ways. First, it ignores Ctrl-Break. This prevents a user from breaking out of a program at a critical point that might damage files or data stored in memory. Second, getkey() checks the value of the keyboard code. If the code is a null byte (\0), it gets the next character code, bitwise-ORs it with 0x100 (which has the same effect as adding 256), and returns the modified value. This value can be compared against the constants that are defined in keydefs.h to determine what key was pressed. The defined values include most of the keys and combinations of keys on the keyboard. Here is the source code for keydefs.h: ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 76 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ This is the source code for getkey(): /* getkey -- return a code for single and combo keystrokes * - returns a unique code for each keystroke or combination * - ignores "Ctrl-Break" input */ #include <dos.h> #include <local\std.h> #include <local\doslib.h> #include <local\keydefs.h> int getkey() { int ch; /* normal key codes */ if ((ch = bdos(KEYIN, 0, 0) & LOBYTE) != '\0') return (ch); /* convert scan codes to unique internal codes */ return ((bdos(KEYIN, 0, 0) & LOBYTE) | XF); } To determine whether a key has been pressed, we would use the run-time library function kbhit(), which returns a nonzero value if a code is available in the keyboard buffer, indicating that at least one key has been pressed. The function keyready(), presented next, does the same job. /* keyready -- nonzero if the keyboard buffer * has any codes waiting */ #include <dos.h> #include <local\doslib.h> int keyready() { union REGS inregs, outregs; inregs.h.ah = CH_READY; intdos(&inregs, &outregs); return (outregs.h.al); } The kbhit() or keyready() function should be called before an attempt is made to read the keyboard. This produces a "nonblocking read." If nothing is ready, the program can do something useful while it waits for the user to press a key. That something should be broken up into brief allocations of work (i.e., sending a character to the printer), so that the keyboard provides a timely response to user input. There is, however, no good reason to put the entire computer to sleep waiting for user input. The following code fragment shows a way to handle keyboard processing and a background task: . . . int k, getkey(), keyready(); /* keyboard functions */ int do_task(TASK); /* task dispatcher */ TASK taskp; /* task pointer */ . . . while (1) { /* get user's input */ if (keyready()) { k = getkey(); switch (k) { case K_ESC: do_exit(); . . . } /* do background task */ do_task(taskp); } . . . For example, if the task dispatcher is calling a routine that dumps characters into a printer spooling buffer, the printer appears to run continuously while not burdening the main program at all. User commands and input will be honored immediately. Other background tasks might include doing a hard disk-to-tape backup, checking timed alarms, and running a sprinkler system. The makefile, dos.mk, automatically builds the library dos.lib: # makefile for the DOS library LINC = c:\include\local LLIB = c:\lib\local # --- inference rules --- .c.obj: msc $*; # --- objects --- OBJS = getkey.obj keyready.obj ver.obj # --- compile sources --- getkey.obj: getkey.c $(LINC)\std.h $(LINC)\doslib.h $(LINC)\keydefs.h keyready.obj: keyready.c $(LINC)\doslib.h ver.obj: ver.c $(LINC)\doslib.h # --- create and install the library --- $(LLIB)\dos.lib: $(OBJS) del $(LLIB)\dos.lib lib $(LLIB)\dos +$(OBJS); BIOS Library Routines The ROM BIOS in a PC offers a wide range of services that we can use to our advantage. We will write routines that let us determine how the host computer is configured, control the cursor, check the status of special keyboard keys (such as Caps Lock and Num Lock), and read and write characters and video attributes anywhere on the screen. The header file bioslib.h contains the constants needed to call various BIOS interrupts and services by symbolic names. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 82 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ Equipment Determination Functions We'll start with a pair of functions that help us determine what equipment is installed in a PC and how much memory it has. The first of these functions, equipchk(), uses BIOS interrupt 11H to determine what devices are installed. A structure is used to hold the data obtained by equipchk(), which declares the structure globally and fills it when called. Other functions can also access the data if they contain the following external definition: extern struct EQUIP Eq; Here is the source code for equip.h and equipchk(). /* equip.h -- header for equipment determination/inventory */ struct EQUIP { short disksys, /* 1 if disks installed */ game_io, /* 1 if game i/o adapter installed */ nprint, /* number of printer ports */ nrs232, /* number of serial ports */ vmode, /* initial video mode (from switches) */ ndrive, /* number of disk drives (from switches) */ basemem; /* amount of base memory in Kbytes */ }; ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 84 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ To find out whether a game port is installed, call equipchk() and then look at the game_io member of the structure. #include <local\equip.h> extern struct EQUIP Eq; . . . if (equipchk()) /* handle the error */; if (Eq.game_io == 1) printf("Game adapter installed\n"); Although equipchk() can tell us how much memory is installed on the main system board, it cannot help us get the total installed memory value. The memsize() function calls BIOS interrupt 12H to get the system memory size, including any memory in the I/O channel on adapter cards (exclusive of display memory and that which is not contiguous with the main system- board memory). /* memsize -- get memory size */ #include <dos.h> #include <local\std.h> #include <local\bioslib.h> int memsize() { union REGS inregs, outregs; return (int86(MEM_SIZE, &inregs, &outregs)); } The size of main memory is reported as a 16-bit integer that represents the total number of kilobytes found. Keyboard Status Older PC keyboards did not have status lights on the Caps Lock and Num Lock keys. It is helpful to the user if the status of these keys is reported on the screen in applications in which the status is important. The same holds true for the Ins key and, in some situations, the Scroll Lock key. Also, we can use the status of the Shift, Ctrl, and Alt keys to alter the meaning of the function keys to do other jobs. The kbd--stat() function lets us obtain the needed information. It calls BIOS interrupt 16H, service 2 (status), and returns the value of the AL register. The header file keybdlib.h contains definitions of masks that are used to test the return value from kbd_stat() to determine which keys were pressed. /* keybdlib.h */ #define KBD_READ 0 /* keyboard routine numbers */ #define KBD_READY 1 #define KBD_STATUS 2 #define KS_RSHIFT 0x0001 /* bit masks for keys and states */ #define KS_LSHIFT 0x0002 #define KS_CONTROL 0x0004 #define KS_ALT 0x0008 #define KS_SL_STATE 0x0010 #define KS_NL_STATE 0x0020 #define KS_CL_STATE 0x0040 #define KS_INS_STATE 0x0080 /* kbd_stat -- return the keyboard status * word (bit-significant) */ #include <dos.h> #include <local\bioslib.h> #include <local\keybdlib.h> unsigned char kbd_stat() { union REGS inregs, outregs; inregs.h.ah = KBD_STATUS; int86(KEYBD_IO, &inregs, &outregs); return ((unsigned char)(outregs.h.al)); } Video Access One of the most frequently used ROM BIOS interrupts is 10H, the access point for video services. We will use many of these services in our programs. The header file video.h contains some data structures used to hold important video-mode and cursor data. It also contains definitions of color and attribute values, special and drawing-character codes, and constants used by the mode and cursor structures. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 87 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The primary functions in interrupt 10H are those used to get the current video state data (mode, screen width, and visual page) and to set the video mode. The getstate() function invokes video service 15 to get the values of the video mode, the screen width (redundant information, because the mode number implies a width, but screen width is directly accessible), and the visual page number. Although the IBM Technical Reference manual calls this the active page, it is really the visual page. To be consistent with the way BASIC defines pages, the active page is defined as the one being written to and the visual page as the one being viewed. The page number returned by service 15 is the visual page. Most of the time, the visual and active page numbers are the same. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 91 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ Because getstate() contains the declarations of the video structures, it should be called before you use any of the other video functions (clrscrn(), clrw(), scroll(), and setctype()) that depend on the data in those structures. The setvmode() function is used to set the video mode. It cannnot be used, however, to switch from one adapter to another. That task must be handled in another way, which is described in Chapter 11. The mode numbers are defined in video.h. The mode number presented to setvmode() is not value-checked. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 92 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ For the IBM Monochrome Adapter, and for the standard Color Graphics Adapter (CGA) in any of its graphics modes, only page 0 is valid. On the CGA, the 40-column text modes permit up to eight screen pages in display memory and the 80-column text modes up to four screen pages. On the Enhanced Graphics Adapter (EGA), page ranges are a function of the mode as follows: mode 13, 0 through 7; mode 14, 0 through 3; modes 15 and 16, 0 and 1. The job of setting the visual page falls to setpage(). The pagenumber argument must be valid for the current video mode because its value is not checked. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 94 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ Next we have four functions that are used for cursor control. Two of them, readcur() and putcur(), deal with cursor positioning. The other two, getctype() and setctype(), are used to determine the cursor shape and to set it to a particular shape, respectively. The function readcur() gets the cursor position for the specified page and passes back the row and column position data to the calling routine. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 94 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The row and col arguments are pointers to simulate "call-by-reference" parameter passing, which allows readcur() to pass back more than a single value by directly accessing the storage locations of the variables in the calling function. The putcur() function moves the cursor to an absolute screen location on the specified screen page. The specified row, column, and screen-page values are not checked. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 95 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The cursor on a PC screen is a "hardware cursor" formed by one or more raster scan lines in the cell at the current cursor position. The cursor always blinks. A hardware cursor is available only in text modes and not in graphics modes, although it is quite easy to fabricate one in software. To determine the starting and ending scan lines for the cursor, we use getctype(). The function uses the same video service as readcur() but returns cursor type data, not position data. We can use getctype() in a program to save the starting and ending scan lines so that we can restore them with setctype() before the program terminates. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 96 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The inverse operation, setting the cursor type, is a bit more difficult than finding out what type it is. The job is done by setctype(). The setctype() function sets the starting and ending scan lines to the values given by its arguments. It is incumbent upon the calling function to specify correct values for the prevailing display mode. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 97 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The video functions described next are used to read and write characters and attributes in any video mode, and dots--individual pixel values--in graphics modes only. The function readca() gets the character and video attribute of the character cell at the cursor position without regard for the video mode. This is a neat trick in graphics modes when you realize that, to do this, the BIOS video routine has to do a pattern-matching operation on the displayed image to find out what the character is. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 98 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ When we are operating in one of the graphics modes, we can read the values of individual picture elements--pixels, or dots. The function readdot() returns the color number for the pixel at the specified row and column coordinates. /* readdot -- read the value of a pixel (in graphics mode only) */ #include <dos.h> #include <local\std.h> #include <local\bioslib.h> int readdot(row, col, dcolor) int row, col; int *dcolor; /* pointer to dot color */ { union REGS inregs, outregs; inregs.h.ah = READ_DOT; inregs.x.cx = col; inregs.x.dx = row; int86(VIDEO_IO, &inregs, &outregs); *dcolor = outregs.h.al; return (outregs.x.cflag); } The allowed row and column values depend on the graphics mode: ═══════════════════════════════════════════════════════════════════════════ MODE ROW RANGE COLUMN RANGE ─────────────────────────────────────────────────────────────────────────── 4 │ 0-319 │ 0-199 5 │ 0-319 │ 0-199 6 │ 0-639 │ 0-199 13 │ 0-319 │ 0-199 14 │ 0-639 │ 0-199 15 │ 0-639 │ 0-349 16 │ 0-639 │ 0-349 ─────────────────────────────────────────────────────────────────────────── The function writec() writes a character or a string of identical characters, starting at the current cursor position. It does not change the cursor position. The number of repetitions must not cause the function to write past the end of the current line. This function is particularly handy for quickly drawing lines and boxes on the screen. We will also use it as a building block in functions that manipulate higher-level objects, such as text strings that are presented in fixed-length fields and scrolling windows. /* writec -- write a character and attribute to the screen */ #include <dos.h> #include <local\std.h> #include <local\bioslib.h> int writec(ch, count, pg) unsigned char ch; /* character */ unsigned char attr; /* attribute */ int count; /* number of repetitions */ int pg; /* screen page for writes */ { union REGS inregs, outregs; inregs.h.ah = WRITE_CHAR_ATTR; inregs.h.al = ch; inregs.h.bh = pg; inregs.h.bl = attr; inregs.x.cx = count; int86(VIDEO_IO, &inregs, &outregs); return (outregs.x.cflag); } The writeca() function is the same as writec(), except that it also writes the video attribute at the same location or region. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 100 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ To simulate the printing behavior of a simple terminal, use the writetty() function to place characters on the screen. This function writes characters only, but it automatically does newline and screen-scrolling operations. /* writetty -- write to screen using TTY interface */ #include <dos.h> #include <local\std.h> #include <local\bioslib.h> int writetty(ch, attr, pg) unsigned char ch; /* character */ unsigned char attr; /* video attribute */ int pg; /* screen page for writes */ { union REGS inregs, outregs; inregs.h.ah = WRITE_TTY; inregs.h.al = ch; inregs.h.bl = attr; inregs.h.bh = pg; int86(VIDEO_IO, &inregs, &outregs); return (outregs.x.cflag); } The writedot() function writes a dot of the specified color at the row and column position passed as arguments. Valid color numbers are a function of the current graphics mode: ═══════════════════════════════════════════════════════════════════════════ MODE COLOR NUMBERS ─────────────────────────────────────────────────────────────────────────── 4, 5, 10 │ 0-3 6 │ 0 and 1 8, 9, 13, 14 │ 0-15 15 │ 0-1 16 │ 0-4 or 0-15 ─────────────────────────────────────────────────────────────────────────── If bit 7 of the AL register is a 1, the dot color is exclusive-ORed (XOR) with the current dot color value. /* writedot -- display a dot at the specified position */ #include <dos.h> #include <local\std.h> #include <local\bioslib.h> int writedot(r, c, color) int r, c; /* row and column coordinate */ int color; /* dot (pixel) color */ { union REGS inregs, outregs; inregs.h.ah = WRITE_DOT; inregs.h.al = color; inregs.x.cx = c; inregs.x.dx = r; int86(VIDEO_IO, &inregs, &outregs); return (outregs.x.cflag); } The following miscellaneous video functions are used to clear the current screen page, or a portion of it, scroll a region of the screen up or down, set the graphics palette or text border color, and write video attributes. The clrscrn() function uses the BIOS video scroll routine to initialize the visual screen page. The clrw() function clears a window of specified dimensions on the visual screen page. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 102 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 103 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The palette() function serves two purposes. In text modes, it sets the screen border color. In graphics modes, it sets the color palette from which drawing colors are selected. /* palette -- set graphics color values or border color */ #include <dos.h> #include <local\bioslib.h> int palette(id, color) unsigned int id, color; { union REGS inregs, outregs; inregs.h.ah = PALETTE; inregs.h.bh = id; inregs.h.bl = color; int86(VIDEO_IO, &inregs, &outregs); return(outregs.x.cflag); } To scroll the entire visual screen page or a rectangular portion of it up or down, use scroll(). The function takes a signed number: negative numbers scroll lines down the screen, nonzero positive numbers scroll lines up, and zero initializes the specified region. Vacated lines are set to blanks in the specified attribute. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 104 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The next function is really a composite of two BIOS video services. To change the attribute of a range of character positions without disturbing the characters, use writea(). This function reads the character and attribute at each affected position and writes back the same character in the new attribute while leaving the current cursor position unchanged. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 105 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ Demonstration Program Now that we have a collection of DOS and BIOS interface routines, what can we do with them? Perhaps the best way to answer the question is to demonstrate their use in a program. A vehicle for showing off some of the routines is CURSOR, a program that magnifies the current cursor and lets us change its shape. CURSOR is proof that carefully written and applied BIOS video routines can produce startlingly fast screen manipulation--far from instantaneous, but fast enough for demanding commercial applications. Before examining the source code for CURSOR, we will prepare several functions that are built on the current set of BIOS video routines. The functions put_ch(), putstr(), and drawbox() can be viewed as a layer above the writec() and putcur() functions of the BIOS library just described. They provide often-used capabilities that are not provided in a convenient way by the primary BIOS functions. The put_ch() function displays a single character at the current cursor position and then advances the cursor to the next position. The name includes the underscore to distinguish put_ch() from putch(), a standard console I/O routine in the Microsoft run-time library. The putstr() function displays a text string and advances the cursor to the next displayable position. Combining these two functions and several of the low- level BIOS functions in drawbox() lets us create fine-ruled boxes for highlighted text and graphical elements of our screens. The drawbox() function uses the single-line drawing characters that are part of the IBM extended-ASCII character set. We could also use double-line and other combinations of line-drawing characters to produce distinctive box shapes, as we will do in later chapters. Here are the C source listings for put_ch(), putstr(), and drawbox(): /* put_ch -- display a character in the prevailing video * attribute and advance the cursor position */ #include <local\video.h> int put_ch(ch, pg) register char ch; int pg; { int r, c, c0; readcur(&r, &c, pg); writec(ch, 1, pg); putcur(r, ++c, pg); return (1); } /* putstr -- display a character string in the * prevailing video attribute and return number * characters displayed */ int putstr(s, pg) register char *s; unsigned int pg; { unsigned int r, c, c0; readcur(&r, &c, pg); for (c0 = c; *s != '\0'; ++s, ++c) { putcur(r, c, pg); writec(*s, 1, pg); } putcur(r, c, pg); return (c - c0); } ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 108 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ Now we can write cursor.c. The goal is to design a program that presents a magnified view of the cursor and that allows us to interactively adjust the cursor shape. The source for CURSOR is quite long. It is one of several programs I wrote to test the DOS and BIOS interface functions. The program shows how the DOS and BIOS interface functions are used in a working example. By writing "driver" programs as I wrote the interface functions, I was able to both anticipate what functions might be needed and test the functions as they were written. The pseudocode for CURSOR shows how the program works. get video information save current attribute/color values draw basic screen (header, cursor image, instructions) while (key is not Return) switch selection modes on left or right arrow clear start/stop selection pointer display new pointer adjust scan line position on up or down arrow clear current scan-line pointer calculate new pointer value update cursor image display (scan lines, pointers) set new cursor type restore original attribute/color clear screen This simple description does not reveal a few details in the calculations needed to accurately display images for cursors on various types of hardware. For example, CURSOR automatically adjusts the displayed image to compensate for 80- and 40-column screen widths, and differing numbers of scan lines and widths in cursors on IBM monochrome display systems (9 by 14) and color/graphics systems (8 by 8). The C source, which shows how these details are handled, is in the file cursor.c. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 110 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The makefile, bios.mk, automatically builds the library bios.lib using the inference rules supplied by tools.ini. The makefile for CURSOR is contained in cursor.mk: ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 116 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ # makefile for CURSOR program LLIB=c:\lib\local cursor.obj: cursor.c msc $*; cursor.exe: cursor.obj $(LLIB)\bios.lib $(LLIB)\dos.lib link $*, $*, nul, $(LLIB)\bios $(LLIB)\dos; When you run the CURSOR program, some computers will exhibit unexpected behavior as a function of the installed hardware. The AT&T PC6300, for example, does not permit "split" cursors (the stop scan line is less than the start scan line). CURSOR will allow you to fashion a split cursor, but on the 6300, it disables the cursor instead. Also, I have not modified the program to work with EGA-compatible boards. EGA boards use different numbers of scan lines per character cell than standard CGA boards operating in the same (or equivalent) modes. Before moving on to user interfaces, we will add one more function to the BIOS video library. The writestr() function is not used in this chapter, but it is called by a user-input function in Chapter 6. It displays a two-part message in a fixed field and leaves the cursor at its current position. The design of writestr() lets us concatenate strings visually and prevents them from extending beyond the available display area. In addition, if the resulting string does not completely fill the display field, writestr() pads the field with spaces in the prevailing attribute to clear any residue from the previous contents of the field. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 118 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ Recommendations We need to address a few library management issues. In my work and in this book, I have elected to keep the number of functions at one per file except in rare circumstances where two or more functions have a symbiotic relationship. The cost of doing this is increased disk use. Although most of the source files are less than 500 bytes in size, they each require from 2 to 8 KB of storage capacity on a typical hard disk. The amount used is a function of the block or cluster size of the disk, which is in turn a function of its capacity and the version of DOS used to format the disk. The primary advantage of separate functions in libraries is that the linker program adds the object code only for the functions used in a program, thus avoiding the possibility of dragging in a lot of unneeded instructions. The alternative--packaging related functions in a single object module in a library--can be effective too, as long as the functions so grouped are likely to be used together in a program. We could, for example, group the getctype(), setctype(), and other cursor-related functions in a single object module because they are usually employed together, as in the CURSOR example. The issue of compatibility across a wide range of machines deserves comment. To obtain the broadest PC compatibility for your programs, use the higher-level DOS function calls. They are often slower and less versatile than the BIOS functions, but programs built on them can be run on virtually any machine that runs DOS. Using BIOS interfaces will erode your market a little, but probably not enough to fret about for more than a few seconds. If a large enough market exists for a non-compatible machine (the Zenith Z-100, for example), you can create a customized version of the program because the dependencies can be limited to a few interface library functions. Compatibility of PC/DOS-based programs to UNIX and XENIX is another matter. Some fundamental differences in architecture make transporting a program developed under DOS on a PC to a UNIX-based system difficult, but not impossible. The primary difficulty is that users in a multi-user environment are typically not using the console; they are connected by dial-up or hard-wired lines to the host computer. Those connections are a bottleneck that reduces the available "bandwidth" of the user interface to a tiny fraction of what a typical PC has available on a dedicated machine. Despite this difficulty, most programs can be written for portability between DOS and UNIX/XENIX. In fact, I have done most of my development work under XENIX and then converted to DOS afterward. Going from DOS to UNIX is tougher because I tend to take advantage of all that the PC and DOS offer for program performance reasons. To gain some needed portability to UNIX, we can use the Termcap/Curses virtual terminal interface packages that permit UNIX to work with just about any alphanumeric video terminal. Termcap is a set of low-level functions that get terminal information from a database of terminal capabilities and provide control over cursor positioning and other video terminal functions. Curses is a high-level screen-management package that provides optimization of cursor movements and control over displayed text, video attributes, and keyboard interactions. Curses also supports buffers that are larger than the screen and provides modest windowing features. It is outside the scope of this book to provide detailed information on Termcap/Curses software. You may want use the virtual-terminal interface in your programs for one important reason: A program written under DOS on a PC using a Curses interface for screen management is easily ported to UNIX/XENIX. Give it a shot. A very good Curses implementation for the PC from Aspen Scientific works well with Microsoft C and other C compilers under DOS and is compatible with UNIX System V Curses. Lattice offers a non-optimizing version of Berkeley Curses as an adjunct to its C compiler. Other Curses implementations are available, but I have not tested them. There is much more to the DOS/BIOS interface than we have covered in this chapter. As we need additional functions, we can use what we have done so far as models for the needed functions. Next, we look at one of the most important aspects of any program--the user interface. Chapter 6 The User Interface The user interface has received a lot of attention in recent years. Human factors engineering (ergonomics)--the endeavor that is one part each of engineering, science, and "black magic"--is best known for dealing with such topics as how to design safe, comfortable car seats and how to lay out the cockpit of a jet aircraft. However, it also offers much information about how people use machines that have neither wheels nor wings. Although by no means a dissertation on human factors engineering, this chapter focuses on the primary points of contact between the computer and the user--the keyboard, the display screen, and the speaker--and on how to use these communications pathways effectively. As programmers, we must consider both the application and the audience for the application. In addition, we need to know about the environment in which a program is to be used, in order to provide the best possible match between the program and its intended users. Some programs lend themselves to a command-oriented type of operation. Frequently used tools that may become components of pipeline commands are examples of this category. Other programs are well suited to windowing and menus, or at least benefit from their use. Programs that are infrequently used and that may involve complex step-by-step procedures fall into this category. Still other programs can successfully blend the two approaches or switch easily between them. In Chapter 13, we will develop a program that provides convenient screen control with instructions from either the DOS command line or a simple menu of commands. The mode of operation depends on how the program is called. The use of pleasing visual effects and appropriate sound can do a lot to enhance both the appeal and the utility of a program. However, effectively using visual effects and sound in programs is no less an art than playing a musical instrument. Later in this chapter, we will explore the use of sound and text-oriented visual effects in our programs. But we will start with a view toward standardizing the way programs gather and process command-line options. Then we will develop some timer functions that are needed to do several important jobs. Standard Command-line Processing The standard user interface of unadorned UNIX/XENIX and DOS is the command line. One of the major modes of communication from the user to a program is via command-line options and other arguments. For years, there has been a need to standardize command-line option processing by programs in order to provide a clean and consistent user interface. This was evident long before CP/M and DOS were conceived in the fertile minds of their developers; the problem exists in Multics, UNIX, XENIX, and many other minicomputer and mainframe operating systems. Here is an example of the problem. Under UNIX, command-line options are introduced by a leading dash (-). An option letter selects a particular program option and may require an option argument. Therefore, -w80 might be used to select a page width (w) of 80 columns when used with a printer program. The option argument--80, in this case, but other values may be allowed--must be entered if the w option letter is used. An early version of UNIX (Version 7 in commercial circles) requires that options to the print command, r, be invoked individually, each having its own option flag and letter. Thus, printing a file in multiple columns without the usual header and footer lines requires a command constructed according to the following template: pr -2 -t filename in which the -2 and -t arguments specify the desired options, and filename is the lone filename argument. Later versions of UNIX, starting with the release of System III, permit the option letters to be combined and introduced by a single option flag, so a command of the form pr -2t filename does precisely the same job as the first one shown. A command typed according to the older specification (separate option flags) is also allowed. To complicate matters, some programs enforce the requirement that option letters that take arguments must have a space or tab between the letter and the argument while other programs require no white space (-w 80 vs -w80, for example). These variations are the result of no small amount of anarchy among the developers and are the source of the confusion from which standards eventually evolve. So why should this matter to DOS programmers and users? Well, for one thing, DOS resembles UNIX in many ways and emulates many UNIX features and principles. For another, the same kinds of problems already exist under DOS. Some commands take option switches, usually indicated by the forward slash (/), but some programs accept the dash (-) as well. The option switches usually are placed after the command name but before any filenames, yet some commands require that option switches follow everything else on the command line. Still other programs don't care where the option flags and arguments go--they simply scan the entire command line before doing anything. Under recent versions of UNIX and XENIX, a utility function named getopt() is used to process option flags and arguments in a consistent way. The getopt() function can be used by any DOS program that accepts command- line options and arguments. We will apply it to a sample utility program, CAT, which concatenates files (one or more) onto the standard output stream. Figure 6-1 on the next page shows us how getopt() takes command lines and sensibly parses options and arguments. We have already seen in Chapter 3 how information in the DOS command tail is made available to a program via the argc and argv parameters to the main() function and how a program can be written to use the information in the command tail. We have not yet, however, agreed on a format for commands. For the programs in this book, we will present command lines according to a common template. The command name always appears first (this is an operating system requirement), followed by options, if any, followed by other data, typically filenames, if any. Options are introduced by a leading dash. Such a template works well for most of the commands we will encounter. However, with the more complicated commands, we probably will provide a menu-style interface instead of a command-oriented interface. C> cat -s *.c linebuf .h ░░░░░░░░░░░░░░░░░ the command tail is processed by setargv() ══════════════════════════════════════════════════════════════════════════ argc ┌────┐ │▒6▒▒│ ┌────┬────┬────┬────┐ └────┘ ┌───────│ C │ A │ T │ \O │ (DOS version 3.0 and later) │ └────┴────┴────┴────┘ │ │ ┌────┬────┬────┐ ┌────┐ │ ┌─────────│ - │ s │ \O │ 0 │▒▒■─┼──┘ │ └────┴────┴────┘ ├────┤ │ 1 │▒▒■─┼─────┘ ┌────┬────┬────┬────┬────┬────┬────┬────┐ ├────┤ ┌────────────────│ F │ I │ L │ E │ 1 │ . │ C │ \O │ 2 │▒▒■─┼────────┘ └────┴────┴────┴────┴────┴────┴────┴────┘ ├────┤ 3 │▒▒■─┼────────┐ ┌────┬────┬────┬────┬────┬────┬────┬────┐ ├────┤ └────────────────│ F │ I │ L │ E │ 2 │ . │ C │ \O │ 4 │▒▒■─┼─────┐ └────┴────┴────┴────┴────┴────┴────┴────┘ ├────┤ │ 5 │NULL│ │ ┌────┬────┬────┬────┬────┬────┬────┬────┬────┬────┐ └────┘ └─────────│ l │ i │ n │ e │ b │ u │ f │ . │ h │ \O │ └────┴────┴────┴────┴────┴────┴────┴────┴────┴────┘ FIGURE 6-1 ▐ Expanding ambiguous filename specifications Ambiguous filename arguments are expanded automatically by the setargv routine if it is included in the link list. The argument vector array, argv, contains pointers to strings in memory. The DOS command tail is everything that follows the command name on the DOS command line, including the initial space or tab that separates the first option or argument from the command name. Although the DOS command tail is limited to 128 bytes, ambiguous file names can be expanded to produce effective command tails of much greater length. The figure illustrates what the pointers and strings would look like for the command line cat -s *.c linebuf.h if the current directory contains the two C source files, file1.c and file2.c, the header file linebuf.h, and possibly other files. Consider what this command might produce if invoked in a directory with many C source files. The two C source-file names are stored with all letters converted to uppercase because DOS always converts to uppercase when it expands names. The -s option and the header file name are stored as literal copies because no expansions are required. The command name, available only under DOS 3.00 and later versions, is presented with all letters converted to uppercase regardless of how they are typed by the user, again because of a DOS convention. The following source for getopt() was provided by AT&T. It is the current version of getopt() that is available from the AT&T UNIX System Toolchest. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 127 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The following synopsis and description of getopt() are based on its observed behavior under UNIX System V, Release 2, the current UNIX standard. If we use this standard, programs developed under DOS that do not employ any hardware-dependent code will be readily transportable to UNIX/XENIX (and vice versa). The getopt() function receives an argument count and an array of pointers to argument strings (usually copies of the argc and argv parameters of main()) and a string variable that is a list of allowable option flags. Single letters (uppercase and lowercase letters are unique) and single-digit numbers are acceptable option letters. If a valid option letter in the list is followed by a colon, getopt() expects to find a following option argument. In addition to the parameters passed to the function, the interface to getopt() involves three global variables. The optind variable, the option index, is an integer that is initialized to 1; it keeps track of which option is currently being processed. A character pointer, optarg, is set to NULL unless the option being processed takes an argument, in which case optarg points to what should be the required argument. The third global variable is opterr. It is initialized to 1, which causes getopt() to report errors such as an option flag that is not a member of the passed list or a missing argument. Our programs can shut off error messages from getopt() by setting opterr to 0. Although optind and optarg must be declared as external variables in our programs, we need to declare opterr only if we intend to change its value. COMMENT The UNIX and XENIX manual pages for getopt() contain an error. The value of optind does not default to 0. It is initialized to 1. Also, previous versions of getopt() emitted error messages when opterr was 0. The latest versions of getopt() have reversed the sense of the opterr variable and emit error messages if opterr is 1 (the default value). The pseudocode for getopt() reveals the complexities of handling user input in a general way. The primary difficulty is in parsing optional arguments that may or may not be separated from the associated option letter by white space. index to first argument following command name (done before the first call to getopt()) if (no arguments OR arg not an option OR flag without option letter) return EOF else if (special end-of-options indicator) skip over argument return EOF if (option letter not in option string) if (opterr is non-zero) print error message return '?' if (option letter followed by ':' in option string) if (option argument found) set optarg to start of argument return option letter else if (opterr is non-zero) print error message return '?' else set optarg to NULL return option letter To show how the getopt() function is used in practice, we will now write a program that uses getopt() in its simplest form. Later in this chapter and in other chapters, we will use getopt() in more complex argumentprocessing situations. The CAT program, presented next, uses getopt() to process a single option. CAT is used to concatenate files. It accepts a list of zero or more files and produces a continuous data stream on its output. If only a single file is named, CAT simply lists the file's contents on the screen. Figure 6-2 on the next page is the manual page for CAT. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the figure found on page ║ ║ 132 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ FIGURE 6-2 ▐ Manual page for CAT The source for CAT follows: ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 132 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ CAT duplicates its input stream on its output stream by calling fcopy(). The input comes from files named on the command line or from stdin if no files are named. Output is to the standard output stream, stdout. Therefore, CAT is minimally a filter. The transformation it performs is to merge data streams into a single sequential output stream. CAT is most frequently used to list the contents of one file on the console screen or to combine a group of files into a single file. It may be used as the source node of a pipeline command, either taking its input from named files or the console. Following is the C source for fcopy(). /* * fcopy -- copy input stream (fin) to output stream (fout) * and return an indication of success or failure */ #include <stdio.h> int fcopy(fin, fout) FILE *fin, *fout; { int errcount = 0; char line[BUFSIZ]; char *s; while ((s = fgets(line, BUFSIZ, fin)) != NULL) if (fputs(s, fout) == EOF) ++errcount; if (ferror(fin)) ++errcount; return (errcount); /* 0 if all went well */ } Since both getopt() and fcopy() are going to be useful in other programs, add them to the utility library. Now that we have a function that lets us process command lines in a consistent way, we can move on to other aspects of the user-machine interface. We will now look at methods of producing machine-independent time measurements and delays. Timing Functions The routines and programs in this and the next subsections show how to time events, produce time delays, and create sounds. All depend in some way upon the PC's built-in timer circuits. We begin with a program called TIMER, which uses some of the ctime subroutines in the standard library that we examined in Chapter 4. TIMER is an external program that lets us time intervals from the DOS command level and from within batch files. The program is handy for timing events lasting from a few seconds to a few days. It is not suitable for shorter intervals because of the way it is implemented. A typical use consists of starting a timer, running a program or performing a task, and then calling the timer again to check the elapsed time. Figure 6-3 is the manual page for TIMER, and its source code is in timer.c. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the figure found on page ║ ║ 136 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ FIGURE 6-3 ▐ Manual page for TIMER The source for TIMER follows: ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 137 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The source for TIMER illustrates a slightly more complicated use of getopt() than we saw in the CAT program. In addition to handling more option flags, TIMER has one option flag that requires an argument. The option -f takes an argument that specifies a filename; if -f is present, the next argument is presumed to be the required argument. The user can insert extra white space characters between the option flag and the argument, but it's not required. When getopt() detects the -f option, it immediately sets optarg to point to the start of the argument string. The program calling getopt() then interprets the argument. The TIMER program uses a special area in memory that is called the intra-application communications area (ICA). The ICA resides in an area of memory (addresses 4F0--4FF hex) that is reserved by DOS. The ICA is a mere 16 bytes in length, but it's big enough to store four long integers, one for each of four separate timers. Few commercial programs use the ICA, but TIMER should protect itself against corruption of its data. Therefore, each timer value is represented by the lower 30 bits (0--29) of a four-byte long. The top two bits are used for status and identification purposes. The ID bit, bit 30, must be a logical value of 1. The most significant bit, bit 31, is also set to a logical value of 1 to indicate that a timer value has been stored. If these bits do not have the correct values, attempts to show an elapsed time produce an error message. The time() library function returns a long integer that is the number of seconds since the epoch (00:00:00 on January 1, 1970 for ctime subroutines). There are 31,536,000 seconds in a normal year (add one day, 86,400 seconds, for a leap year). Using the first 30 bits of a long to hold the time value gives us a range of 34 years, so TIMER will function correctly until 2004--by which time I hope to have a new computer and operating system. We can extend the span to 68 years by not using a separate ID bit, but that increases our risk of returning incorrect elapsed time values if some other program happens to use the ICA. TIMER is a small-model program because it requires little code space and even less data space. However, the ICA is in the BIOS segment, not the program's data space. TIMER uses the movedata() library function to read and write data in the ICA. Because movedata() requires two segmented addresses, TIMER also calls the segread() library function to get the data segment register value. The other address needed by movedata() is in the BIOS data segment. I chose to use 0x4F as the segment value (ICA_SEG) and an offset of 0 for the ICA, but these can be reversed if you prefer. When the -e flag is given, TIMER calls interval() with the number of seconds between "now" and when the timer was started. The saved timer is not altered. The interval() function translates the elapsed seconds into ASCII text using the form hh:mm:ss. If no timer number is specified, timer 0 is used. The user may restart an interval timer by using the -s (start) option along with the timer number. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 141 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ I have found TIMER to be most useful for recording work time against project accounts in my consulting practice and also as a means of measuring program execution times. Using the -f option, all data that would normally appear on the console screen is instead appended to the named file, which becomes a handy record of activities. When testing program execution speeds, I minimize the effects of disk loading times by setting up a virtual disk for the batch file, the TIMER program, and the data file. Everything else is run from a hard disk or a floppy disk so that loading and access times for the program will be taken into account. This beats using a stopwatch and ink on paper. The PC Timer and Time Delays Following is a brief description of the timer circuits in the PC and a look at some of the internal programs that keep track of time in various ways. Refer to Figure 6-4 while reading through this description. The figure shows the basic elements of the PC's timer and speaker-control circuits. We can ignore the speaker elements (shaded boxes) for now and concentrate our attention on the clock signal generator and timer/counters 0 and 1. ╔═════════════════╗ ║ ┌───────────┐ ║ ┌───────────┐┌─╫─│clk │0 ║ │1.19318 MHz││ ║ │ out├──╫───────── timer interrupt │from system││┌╫─│gate │ ║ │clock │││║ └───────────┘ ║ ┌─────── RAM refresh └─────┬─────┘││║ ║ │ ││║ ┌───────────┐ ║ │ ──────┼╫─┤clk │1 ║ │ AND gate Low-pass /│ │ tied │║ │ out├──╫─┘ ┌── driver filter /▒│ │ high ─╫─│gate │ ║┌───│▒▒▒\ ┌──────┐ ┌──────┐ ┌─┐▒▒│ │ ║ └───────────┘ ║│ │▒▒▒▒)───│▒▒▒▒▒▒│─│▒▒▒▒▒▒│─│▒│▒▒│ │ ║ ║│ ┌─│▒▒▒/ │▒▒▒▒▒▒│ │▒▒▒▒▒▒│ └─┘▒▒│ │ ║ ┌───────────┐ ║│ │ └─ └──────┘ └──────┘ \▒│ └────────╫─│clk ▒▒▒▒▒▒▒│2 ║│ └──────────────────────┐ \│ ║ │▒▒▒▒▒▒▒▒out├──╫┘ ╔════════════════════╪══════╗ ┌─╫─│gate▒▒▒▒▒▒▒│ ║ ║ port 61 hex │ ║ speaker │ ║ └───────────┘ ║ ║ ┌─────────────────┬┴─┬──┐ ║ │ ╚═════════════════╝ ║ │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│1 │0 │ ║ │ 8253-5 timer/counter ║ └─────────────────┴──┴┬─┘ ║ │ ╚═══════════════════════╪═══╝ └────────────────────────────────────────────────┘ 8255 programmable peripheral interface (PPI) FIGURE 6-4 ▐ Timer and speaker control circuits The primary clock rates for the system unit and peripheral interfaces are derived from a high speed crystal-controlled oscillator, an 8284A device. One of the output signals is divided down to 1.19318 megahertz (MHz) and is fed to the 8253-5 timer/counter on the CLK input of all three channels. (An 8254-2 timer/counter circuit is used in the PC/AT.) Channel 1 is used to refresh main memory; we should not alter this channel in any way. Channel 2 will be described when we cover sound generation. Of primary interest to us now is channel 0, which is used to provide a system-wide timer interrupt (interrupt 8). This interrupt is called a clock tick. A clock tick occurs at a rate of about 18.2 per second, or one approximately every 55 milliseconds. The number of ticks per second is the timer input clock rate, 1.19381 MHz, divided by 65536, which is the divisor on timer channel 0. Other divisors may be used to produce different interrupt frequencies. Each timer/counter channel contains a 16-bit counter, a pair of 8-bit latches to hold the starting count, a pair of 8-bit output latches, and control logic. Each input clock pulse decrements the value held in the 16- bit counter until the value is 0. Setting a count of FFFF hex gives us a divisor of 65535, which is one less than needed. If, however, we set the starting count to 0, the first input clock pulse will cause the counter to go from 0 to 65535 (0-1=-1; all bits set to logical 1). This technique produces an effective divisor of 65536, the correct value, because the counter is treated as an unsigned integer. Consult the Intel timer/counter documentation for more information on how it works and how it may be programmed. The ticks are used by the ROM BIOS to update the time-of-day (TOD) clock, which is stored as the number of ticks since midnight. Therefore, any program that modifies the count on timer channel 0 must compensate for the change to maintain the tick rate seen by BIOS. We can use the same 18.2 ticks per second as the basis of some machine-independent timing functions to produce delays and to create sound. We may want to build delays into our programs for a variety of reasons. A program that has a banner frame (I like to call it the "ego frame") must be seen to be appreciated, so it is appropriate to hold it on screen for a few seconds. Automated "slide shows" need controllable delays between frames to pace the presentation. Accurate short-duration delays are also needed to produce audible sound effects. When there was only a single PC model, many programmers were not too careful about how time delays were produced. We often depended upon the characteristics of the machine by using loops that went through the right number of iterations to waste the required time. Of course, faster processors and higher clock rates in many of the newer computers have shrunk delays produced this way to as little as an eighth of their former selves. We are now in need of a way to produce reliable, machine independent time delays. The delay() function uses the computer's timer to generate delays that are consistent with the entire family of IBM PCs and portable to most compatible machines. In order to produce the required waiting period, the delay() function converts the specified period into a number of timer ticks. It does so by multiplying the period by TICKRATE, which is defined in timer.h in the \include\local directory. It then adds that amount to the current number of clock ticks obtained from the time-of-day counter and stores the sum. Then getticks() is called repeatedly by delay(). The delay() function exits when the value returned by getticks() equals or exceeds the target value. The getticks() function queries the TOD clock and returns the current time of day as a count of clock ticks. One modification is made when the TOD clock rolls over from one day to the next: Since the TOD clock count is reset to zero and a flag is set to indicate the day increment, the getticks() function adds a day's worth of ticks (1,573,040 [1800B0 hex]) to the count it returns if the flag is nonzero. Since all machines in the IBM product line (and most compatibles) use the 1.19381 MHz timer clock rate, the delay period is the same on all of the machines and is totally independent of the CPU speed and master clock rate of the machine. The following files contain the sources for the header file, timer.h, and the functions delay() and getticks(): /* * timer.h -- header for timer control routines */ /* timer clock and interrupt rates */ #define TIMER_CLK 1193180L #define TIMER_MAX 65536L #define TICKRATE TIMER_CLK / TIMER_MAX /* timer port access for frequency setting */ #define TIMER_CTRL 0x43 #define TIMER_COUNT 0x42 #define TIMER_PREP 0xB6 ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 145 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 146 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The delay() function has general applicability and will be used in other programs. We need to put it someplace that is easy to access. Because delay() is based on the getticks() function, which in turn uses the ROM BIOS, we will add both of these functions to the bios library. And, of course, timer.h takes a permanent home in \include\local. Audible Feedback We now turn our attention to sound generation. The first thing to notice about sound is that it irritates some users. Also, sound is totally inappropriate in some settings. Therefore, we must provide a way for the user to disable sound. The programs in this book will use a variable, usually the global variable Silent, to record the user's preference regarding sound. If Silent is logically TRUE, our program will be mute. The shaded boxes in Figure 6-4 on page 143 show the PC sound system. Notice how the sound system is built upon channel 2 of the timer subsystem and a couple of I/O ports in the 8255-5 programmable peripheral interface (PPI) device. The timer/counter produces squarewave signals that are amplified and filtered, then passed to the speaker. The AND gate ahead of the driver is controlled by bit 1 of the PPI port 61 hex. In addition, bit 0 of the same port controls the gate lead of timer channel 2. Thus, the PPI can be used to turn sound on (both bits a logical 1) or off (either bit a logical 0). The advantage of using the timer to produce sound is that the sound plays in the "background," and does not steal precious cycles from the CPU. Alternatively, we can disable the timer by setting port 61 hex, bit 0 low, and pulse the speaker directly under program control via bit 1. The problem with this approach is that the program can do nothing else while it attends to the speaker. We will not use this approach. The file sound.h, also in \include\local, is the header file for our sound routines. It contains definitions and macros used to control the speaker's state. SPKR_ON sets the low two bits in the peripheral interface port to logical 1s. This enables the timer and passes signals through to the speaker. The SPKR_OFF macro sets both bits low, turning the speaker off by robbing it of input signals. /* * sound.h -- header for sound routines */ #define PPI 0x61 #define SPKR 0x03 #define SPKR_ON outp(PPI, inp(PPI) | SPKR) #define SPKR_OFF outp(PPI, inp(PPI) & ~SPKR) As noted already, the speaker can operate independently, letting us put sounds in the background. We can demonstrate this with a simple control program, SPKR. This program turns the speaker off if it is called with no arguments and on if it receives any other number of arguments. The source for this test driver is contained in spkr.c (on the following page). /* * spkr -- turn speaker ON/OFF * * no args => OFF * any arg(s) => ON */ #include <local\sound.h> main(argc, argv) int argc; char **argv; { /* turn speaker on or off */ if (argc == 1) SPKR_OFF; else SPKR_ON; exit(0); } The program has one problem--it does not set the pitch of the tone the speaker emits. This must be done by another program, TONE, a simple test driver that lets us set the pitch from the DOS command line. TONE takes a single argument that specifies the desired frequency in hertz. The usable range for the PC's internal speaker is about 40 Hz to a little more than 6 KHz. Higher frequencies can also be used; however, these may cause some speakers to produce barely audible tones or clicking sounds. TONE calls upon a low-level routine, setfreq(), to calculate the needed divisor for the specified frequency and to set up the timer's channel 2, from which the speaker derives its input. The setfreq() function includes the timer.h header file which contains the declarations for the port addresses and values needed to set the frequency of the timer. The code for TONE and setfreq() follow: /* * tone -- set the frequency of the sound generator */ #include <stdio.h> main(argc, argv) int argc; char **argv; { extern void setfreq(unsigned int); if (argc != 2) { fprintf(stderr, "Usage: tone hertz\n"); exit(1); } /* set the frequency in hertz */ setfreq(atoi(*++argv)); exit(0); } /* * setfreq -- sets PC's tone generator to run * continuously at the specified frequency */ #include <conio.h> #include <local\timer.h> void setfreq(f) unsigned f; /* frequency in hertz (approximate) */ { unsigned divisor = TIMER_CLK / f; outp(TIMER_CTRL, TIMER_PREP); /* prepare timer */ outp(TIMER_COUNT, (divisor & 0xFF)); /* low byte of divisor */ outp(TIMER_COUNT, (divisor >> 8)); /* high byte of divisor */ } To use these programs to demonstrate some of the capabilities of the sound system, compile and link them, and then type TONE 1000 SPKR ON This sets an audible pitch and turns on the speaker. You can do other work and the tone will continue to play unless some other program turns off the speaker. Typing SPKR without any arguments turns off the speaker. You can simulate a burglar alarm sound if you have a perverse nature. Key in the code for sweep.c, compile it and link it with the setfreq.obj file, and type SWEEP To stop the sound before the police arrive, press any key. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 150 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ All this noise making is wonderful for something, I'm sure, but we will want finer control of the sound subsystem in our programs. We obtain that control via the sound() function, our high-level sound interface function. Using sound(), we can produce distinctive sounds such as a confirmation signal (confirm()), a warning signal (warn()), and many others. The source for the sound() function is contained in sound.c. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 151 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ Notice that the speaker is turned on, continues to sound during the specified interval, and is then turned off for each tone being generated. Earlier demonstration programs turned on the speaker once, issued a series of pitch changes, and then turned off the speaker. Either way is OK, but the approach used by the sound() function is more versatile for our purposes. The program SOUNDS contains a few sample audible signals selected via a simple menu. You can use these as a starting point and create some of your own. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 152 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ Don't forget to check the user's preference before "making a joyful noise." Give the user a command-line argument to disable sound: Use -s, for example, to set Silent to TRUE if it is Boolean, or to a nonzero value if it is a simple integer. Then a simple conditional such as if (Silent == FALSE) warn(); will prevent the sound produced by warn() from being heard by an ungrateful audience! Getting User Input Next we turn our attention to the topic of getting input from the user. In our programs, we sometimes need to ask the user for a filename, a drive letter, or some other piece of important information. The goal of our next task is to design a general purpose input routine that prompts the user with a brief instruction and gathers a reply. It sounds simple enough: Just use printf() to display the prompt and scanf() to collect the response. This may sound reasonable, but this approach has some unnecessary limitations and some really serious problems. The scanf() function is not appropriate because it is designed for use with formatted data--the kind that is produced automatically by a program, not entered by hand. Besides, users are notorious for breaking things, accidentally or on purpose, and scanf() can be easily broken, even by the well-intentioned user who simply makes a typing mistake. We need something more versatile. Programs that have a lot of information on the screen may run short of screen space, so to make things interesting, we will require that the response field be able to take a response that is larger than the displayable field width. The response field must, therefore, be a window onto the user's response and must scroll sideways to permit the user to view and edit the response text. Figures 6-5A and 6-5B depict what we are trying to do in terms of screen presentation. We will use the BIOS video routines developed in Chapter 5 to control screen appearance and the DOS keyboard routines (also Chapter 5) to gather the user's input. Editing operations include the usual destructive backspace (<-) and single-character delete (Del). A character is inserted into the buffer by pushing all characters from the cursor to the end of the line, to the right one position, and by putting the input character in the vacated spot. The cursor moves to the right one position. prompt field reply field ┌─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┐ │░│░│░│░│░│░│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│ └─┴─┴─┴─┴─┴─┼─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┤ │ │ LINEBUF └───┐ └───┐ headers line buffers │ │ ┌─┬─┬─┐ ┌─┬─┬─┬─┬─┬─┬─┬─┼─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┼─┐ │■│■│■┼─│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│ └┴┬┴─┘ └─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘ │ │ ┌┼┬┬─┐ ┌─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┐ │■│■│■┼─│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│▒│ └─┴─┴─┘ └─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘ FIGURE 6-5A ▐ Memory and screen of getreply() TSTREPLY File: c:\book\06user\timer.c ─────────────────────────────────────────────────────────────────────────── FIGURE 6-5B ▐ Sample screen: Getting a pathname Cursor motions include moving to the beginning of text (Home), to the end of text (End), and left and right by one character (left and right arrows). Pressing Esc aborts the input operation and causes getreply() to return a NULL pointer to the calling function; pressing Enter anywhere in the line returns a pointer to the reply string. The calling function is responsible for validating the reply it receives. If getreply() is to be used more than once for a given reply field in a form or an interactive program, it would be wonderful if it could recall the most recent response, or better yet, scroll back and forth through a list of previous responses. Rather than put all of the complications associated with list management into getreply(), we will have the calling function pass a pointer to an array of line buffers that it sets up. Then getreply() permits the user to scan up and down the list of line buffers by using the up and down arrow keys. This design may seem to be a tall order to fill, but it is actually not that difficult. Several cooperating functions give us a very nice user interface routine and teach us a few things about windows and editing, too. We will name the routine getreply() and try to generalize it enough to make it useful in many programs. We will call on the standard library to help us with a few tasks. The memory function, memcpy(), copies strings within a single segment. The source and destination strings will be allowed to overlap to permit sideways scrolling. The memcpy() function guarantees that no characters will be lost in an overlapping copy operation. The reply string buffer within getreply() is initialized to null bytes (\0) before it is allowed to receive any user data. This action guarantees that the resulting string will be properly terminated. After getting a preliminary version of getreply() working and grousing over a few of its idiosyncracies, I arrived at the following sources for the function, which behaves rather well when challenged by even the most hostile users. The line buffer data structure is defined in linebuf.h, and the source for the getreply() function is in getreply.c. /* * linebuf.h */ typedef struct lb_st { struct lb_st *l_next; struct lb_st *l_prev; char *l_buf; } LINEBUF; ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 157 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ A few parts of the code appear to be a bit dense and need some explanation. The dimension of the reply field is calculated by subtracting the prompt field width from the working area allowed to getreply() by the calling function. Values are not error-checked, so be sure to pass something that makes sense. The bulk of the work is done in the while statement that loops as long as the Return key (or Enter as IBM prefers to call it) is not pressed. If a key is a printable ASCII character, it is inserted into the buffer. If not, it is checked to see whether it is an editing or cursor movement command. Valid commands are executed and invalid keypresses evoke an error response. Controlling the window position relative to the input text is handled by a pair of pointers. The character pointer cp tracks the current input/editing position in the buffer, and wp, also a character pointer, points to the first character in the buffer that will be displayed in the reply field window. A test within the loop assures that the editing/input position is always within the displayed reply window. The getreply() function uses an external error message routine. This practice assures the calling routine that nothing will be displayed arbitrarily on the screen. The calling function has complete control as to when and where the error message will appear. One thing that angers me when I use some programs is having old error messages still displayed on the screen. The code for getreply() prevents messages from being displayed past their time. A message flag is set when a new error message is issued and is cleared with the next keystroke. The message handler is sent a null message, which is its hint to clean up the message display area. It can ignore the hint, but it usually should not. To see getreply() in action, compile and link TSTREPLY, and run it. Although the program does little more than call getreply(), it gives us a way to test getreply() and demonstrate its operation. It also provides all of the code necessary to set up a message handler and manage a line buffer array. The C source is in tstreply.c: ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 161 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ Chapter 7 Automatic Program Configuration We saw in Chapters 3 and 6 how programs can be given optional arguments to control their behavior in order to meet special needs. In the case of CAT in Chapter 6, for example, the -s option causes CAT to remain silent about missing files. The use of such a command-line option is a manual means of configuring a program. However, the use of command-line options is often an impractical approach, particularly if a program uses many options. Users often will avoid reading the manual page and therefore may give up on a perfectly good program. What can be done about this? One solution is to treat an additional program feature as you would an extra nose on your face--avoid it if you can. No sense cluttering up a simple and effective program with lots of little gargoyle-like appendages. Try to keep a program simple and geared to doing a single task as well as possible. If you believe that a program needs another feature to round out its capabilities, see whether other users of the program agree. But avoid the temptation to put in every feature requested by every user; the result will usually be a program that nobody uses. Assuming that there is no way to avoid adding that slick new feature to your program, let's at least look at ways of automating things to make using your software product easier for the "liveware." We can provide automatic program configuration in several tidy, user-controlled ways, including, but not limited to, using the program name and using external configuration files. Using the Program Name As we learned earlier, the name used to invoke a program under DOS version 3.00 and later is available to the program. We could, therefore, use a program's name to alter its behavior. For example, if some additional code were put into our CAT program from the previous chapter, we could cause the program to become a "silent" CAT simply by making a copy of CAT.EXE with the name SCAT.EXE. Then the command C> scat filename would have the same effect as the command C> cat -s filename used in our current design. All we need to do is add these lines to cat.c just after line 46, following the optional argument-processing loop: if (strcmp(pgm, "SCAT") == 0) Silent = TRUE; Many other programs lend themselves to this form of configuration. Under UNIX and XENIX, giving a program another name adds only a link to the original file. No additional space is required for the program file's contents. However, there is a price for doing this under DOS. Every additional name for the same program file requires an additional directory entry, a file allocation table entry, and storage space. Using aliases, then, is not recommended except in rare situations in which the convenience outweighs the lost disk space. Using Configuration Files There is another convenient way to configure a program. Like the use of the program's name, it too provides automatic operation. Although it also requires additional disk space, it typically uses only a single cluster, not a complete duplication of the original program file. In this method, variables and values are read from a file and are used to initialize or update selected program variables at any time during the operation of the program. Several levels of configuration files may be used. An arrangement that works well in practice uses a global data file that is located in a directory pointed to by a DOS environment variable. For example, on my hard-disk-based systems, I use a single subdirectory called c:\config as a convenient location for all configuration files for the programs that accept external configuration. Each of these files bears the name of the program it configures plus a .CNF extension. Thus, c:\config\progname.cnf contains the configuration data for the PROGNAME program. The DOS variable CONFIG is defined by the statement set config=c:\config in my AUTOEXEC.BAT file. A local configuration file--one located in the current directory-- may override the global file. This permits directory-by-directory control over program behavior. For instance, a user of a program that prints the contents of a text file may want one type of behavior for program source files and quite another for a "dumb-things-I-gotta-do" list. The pseudocode for handling the configuration layers just described is as follows: initialize program control variables to built-in values if (local configuration file is found) overlay defaults with local configuration values else if (specified DOS variable found) if (global configuration file found) overlay defaults with global values else return NULL file pointer update variables per command-line instructions, if any It is not an error for either the local or the global configuration file, or both, to be missing, but it is an error for program-control variables not to be initialized by the program before they are used. The responsibility for the first step in the process--providing default initialization--is left to the main program. The local and global steps can be performed by a new addition to our utility library, the fconfig() function. We still permit command-line arguments to override other settings on a per-invocation basis, as indicated by the last step in the process described by the pseudocode. Here is the C source code for the fconfig() function, which seeks a configuration file and, if it finds one, returns a FILE pointer to the file, which is open and ready to read from the top. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 168 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The calling function must specify the name of an environment variable, which may contain a global-configuration directory name, and the name of the configuration data file itself. The name of the DOS variable that may hold a configurationdirectory pathname is passed as a parameter to fconfig(), not hard-coded into the function. This gives a calling program the latitude of specifying any environment-variable name it wants. The pname string variable within fconfig() is large enough (MAXPATH plus room for a terminating null byte) to hold the longest pathname permissible under DOS. The environment variable, if it exists, holds the pathname that represents the chain of directories leading up to the place where the global configuration file would be located. The fconfig() function still must append a backslash and the filename to complete the full pathname of the configuration file. (Because the backslash is the C "escape" character, two backslashes are needed to get one out, the first turning off the special meaning of the second.) Nothing we've done so far places any restrictions on the type of data that can be stored in and read from the configuration data file. The best format is highly dependent on the amount of data and what will be done with it. If a lot of Boolean flags are used to control a program, the best approach might be to use a binary format with all bits significant. If the data will be typed in by a casual user, the best approach might be to use strictly ASCII text. In practice, it turns out that the ordinary text file is best because it is more easily transported from one system to another without concerns about the native size of data words or the ordering of bytes within data words. All data read into a program from a configuration file should be qualified in some way before being used to update program data. Data files created by mere mortals often will contain errors, such as typos, incorrect data types, out-of-range values, or too many or too few values. Data files created by a custom-designed setup program are less prone to such problems; however, checking all data wastes little time compared with the time it takes to reboot a system that chokes on its input. Printer Control Functions Now we'll look at an example of program configuration that nearly every PC user has a need for at one time or another. In this section of the chapter, we will develop a set of printer-interface routines that are aimed primarily at controlling the fonts of Epson and IBM dot-matrix printers. Then, in the next section, we will use the printer routines as the basis of a printer-control program that enables us to control the printer from the DOS command line and from batch files. Let's begin with a look at Epson and compatible printers, including the original IBM PC printer. Many other printers use Epson-compatible control codes, so the following routines are applicable without change to a wide range of printers. For those printers that are not Epson compatible, our interface accepts user-supplied configuration data from a file. To simplify matters a bit, we will make a few rules. First, the printer must be able to produce emphasized text without having to backspace and retype the text repeatedly. Second, the printer must be able to underline without having to back up and restrike the text with underscores. Third, if the printer does not offer a particular mode (double-strike, compressed, or expanded, for example), initializing the control codes for the mode to null strings ("") must effectively turn off the mode in the interface routines; no attempt is made to synthesize a mode from combinations of other modes. Limitations such as these would be deadly to a commercial printer- control program, but they are acceptable here in our demonstration of printer control because they simplify our task and make it more manageable. If you need something more elaborate, you can use this program as a base and add controls for paper length, top-of-form position, line-to-line spacing, and many other features. The principles are the same as for the font-control set described here. The file printer.h in the \include\local directory contains the default values for Epson MX/FX-series printers and a set of printer variables used by the interface routines. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 170 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The ASCII codes are used directly to control printer modes (SO, SI, and so forth) or to build up control-code strings (ESC in conjunction with other characters). A set of font-type constants is defined so that each font type is mapped to a single bit. This permits fonts to be "stacked" to form composite fonts by using the bitwise OR. For example, ITALICS | UNDERLINE combines the values 0x10 and 0x20 to request an underlined italic font. The file printer.c contains a set of three related printer-control functions: setprnt(), clrprnt(), and setfont(). These functions use the variables defined in printer.h to determine what control strings to send to the printer. Here is the text of printer.c: ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 172 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The setprnt() function has the Epson default-control strings hard- coded into it. However, if the user wishes to use some other printer, setprnt() calls fconfig() to look for a local or global printer.cnf file to override these values. If a configuration file is found, each line is read in and assigned to the next printer control-code variable. If too many or too few codes are obtained, an error is indicated by a return value of -1. A return value of 0 tells the caller all went well, but it is still possible that the codes were received in the wrong sequence or that bad codes were given in the configuration file. The setprnt() function cannot detect such errors; the printer will simply not operate correctly if it gets bad control strings. The next function, clrprnt(), resets the printer to the normal font. It does so by turning off each special font individually rather than by using the hardware reset-control string. The hardware reset on most printers resets the top-of-form and causes the paper to creep a bit each time it is called. Because of this, I have elected to avoid using the reset command entirely, although its value is contained in the configuration data structure for possible future use. The clrprnt() function calls upon the standard library function fputs() with the control strings needed to turn off each printer font mode. It sends the strings to the output stream specified by its only argument. The setfont() function accepts two arguments: one specifies the desired font combination, and the other specifies the destination stream. The first thing setfont() does is call clrprnt() to cancel all currently active print modes. Then it issues control strings for each of the desired modes. Most print-mode combinations are legal, but a few are not. In this design, two font combinations are excluded. The setfont() function returns a FAILURE indication if the caller requests the compressed mode combined with either a double-strike or emphasized mode. Epson printers don't allow these, but some other printers might. All other combinations of supported fonts and print modes are permitted. The control strings are emitted one at a time for each requested mode. Thus the request setfont(EMPHASIZED | EXPANDED); in a program results in the control string for emphasized mode being sent to the destination stream, followed by the control string for expanded mode. To permit ready access to the printer interface, we will compile it by typing msc print; and then add the print.obj file to our utility library using the command lib\lib\local\util +print; Now we can proceed to an example of how to use this simple but effective printer interface. Printer Control Program My original purpose in designing the printer interface just described was to gain some control over the printer from within my C programs. (Chapter 9 is devoted to a general-purpose printer program that uses this interface.) The approach I took gave me reasonable printer control from C programs, and, with the small amount of extra work that we'll do next, from the DOS command line and from batch files as well. We now have the tools needed to control print modes, but getting access to the printer from DOS involves one additional step: packaging the basic control functions in a DOS program file that accepts option flags to set desired modes. In addition, we will write a supplementary program that allows us to send arbitrary text strings to the printer. The MX program, originally named for its use with my trusty old MX-80 printer, controls the basic print modes via command-line arguments. The program also works nicely with the Epson FX- and JX-series printers and with many other compatible printers. The configurability of MX permits its use with many other printers, too. A look at the manual page (Figure 7-1) and source listing for MX shows that it is simple to use and equally simple to program. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the figure found on page ║ ║ 177 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ FIGURE 7-1 ▐ Manual page for MX ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 178 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ Each time MX is invoked, it checks for a configuration file. This can take a little time on a floppy disk-only system. If you will be using MX with nothing but Epson-compatible printers on a floppy-based system, you may want to bypass the configuration step and build in the Epson default- control strings for faster execution. MX uses getopt(), which is now part of our utility library, plus all of the printer-interface routines in the printer object file. Most of the option flags are obvious; however, two require some explanation. The -o option takes as an argument the name of a destination stream, presumably a disk file, to be used in place of the standard output stream. This allows us to capture the output of MX for diagnostic purposes or to create files that can drive the printer directly as formatting scripts. The -t option uses the ASCII formfeed character to eject a page (go to top-of-form). This will work on nearly all modern printers. To accommodate all printers, you may instead want to permit the use of a series of newlines to get to the top of the next page. The PR program described in Chapter 9 shows how to use either control mechanism. The text of mx.mk tells the Microsoft MAKE command how to assemble the MX program. # makefile for mx program LINC=c:\include\local LLIB=c:\lib\local mx.obj: mx.c $(LINC) msc $*; mx.exe: mx.obj $(LLIB)\util.lib link $*, $*,, $(LLIB)\util; The PRTSTR program is an auxiliary program that prints an arbitrary string. PRTSTR also permits optional newline suppression, which gives users the ability to construct printed lines in a mixture of print modes to obtain various textual effects. The default for PRTSTR is to end the string with a newline, which causes the printer to return to the beginning of the current line and then move down one line. In addition, if it receives no arguments, PRTSTR issues a single newline. Think of PRTSTR as an intelligent substitute for the DOS ECHO command. The only advantage that ECHO has over PRTSTR is that ECHO is built into the DOS COMMAND processor, so it operates faster. However, because printers tend to move like molasses in the Arctic, PRTSTR poses no problem in typical uses. The manual page for PRTSTR (Figure 7-2) describes its operation and application. The source code and makefile (prtstr.mk) are, by now, quite predictable. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the figure found on page ║ ║ 183 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ FIGURE 7-2 ▐ Manual page for PRTSTR ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 184 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ This very simple program has only one wrinkle that requires close examination. When the newline-suppression option is selected, we suppress not only the trailing newline, but also the single space that follows the last argument string. This permits us to mix print modes within text strings. We could, for example, print part of a word in boldface and another part in italics to distinguish the fixed and variable parts of a user's response. # makefile for prtstr program LINC=c:\include\local LLIB=c:\lib\local prtstr.obj: prtstr.c $(LINC) msc $*; prtstr.exe: prtstr.obj $(LLIB)\util.lib link $*, $*,, $(LLIB)\util; The SAMPLE.BAT file is a demonstration of printer control from a DOS batch file. The sample text (Figure 7-3 on the next page) shows off some of the many text combinations that can easily be obtained with simple commands. Note the use of mixed print modes in some of the lines. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 186 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ ╔══════════════════════════════════════════╗ ║ ║ ║ Figure 7-3 is found on page 186 ║ ║ in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ FIGURE 7-3 ▐ Output from SAMPLE.BAT Please keep in mind that this is a minimal printer interface intended to demonstrate means of automatic program configuration. Modern dot-matrix and ink-jet printers offer many additional font and print-mode selections, and laser printers permit even greater selections. Have fun making the most of them! Selection Functions In configuring programs, some types of input require fairly elaborate processing to get the input data into an internal form that is suitable for program use. For example, the file select.c contains several functions that work together to manage input data presented in the form of lists. The next section of this chapter uses the SELECT package to process tab settings. Our objective is to take the user-supplied list of columns that represents tab stops and convert it into an array of integers that can be used by a program to initialize its internal tab stops to something other than the hardware tabs that occur at multiples of eight columns, starting in column one (1, 9, 17, and so on). (Users generally count the leftmost column as one, not zero.) The SELECT routines can be used to process other types of lists, too. For instance, the routines will be used in Chapter 9 to select pages to be printed by the PR program. By way of example, one of our programs might receive a list such as 6, 20, 71--80 as a command-line argument. To be used by the program, the data must be extracted from the list, which is a character string, converted to integer form, and stored somehow for easy access. We'll deal with internal data access soon. For now, let's just worry about the process of extracting and converting the data. The example specification shown has twelve members. Technically speaking, each entry in the list represents a range, although some ranges have the same minimum and maximum values. Thus the 6 entry may be represented internally as min = 6, max = 6, whereas the 71--80 entry is represented as min = 71, max = 80. We will use an array of structures to hold these values in data storage that is private to the routines within the SELECT module. The SELECT module contains three related functions: mkslist() creates a selection list from user data; save_range() is an internal function (static) called by mkslist() to extract starting and ending values from explicit and implicit range specifications; and selected() returns a nonzero value to its caller to indicate that a given value is contained in the selection list. The routines in the SELECT module communicate through a global data structure, Slist, which is defined as struct slist_st { long int s_min; long int s_max; } Slist[NRANGES + 1]; This allocates an array of NRANGES + 1 structures, each of which can hold a minimum and a maximum value for a single range. NRANGES is currently defined to be 10, but any reasonable number may be used. I have had no need to specify more than 10 ranges in a list. Slist is declared globally here for testing and demonstration purposes, but in practice it should be declared static so that only the functions in the SELECT module can access it. The pseudocode description of mkslist() shows how a selection list is parsed. The manifest constant BIGGEST is defined in \local\std.h to be the largest number (65535) that can be stored in an unsigned integer. A global variable, Highest, is initially 0 and is updated to the highest value received in the list. if (list in null) set min = 0 set max = BIGGEST else while (next token of list is not NULL) save_range(token) set min in next to -1 (terminate list) The save_range() function could be coded right in mkslist() because it is only called once. However, by separating out the task of converting a string token to a range of numbers, the apparent complexity of mkslist() is reduced. The save_range() function is described as follows: copy first number to a buffer convert to long int if (only one number received) set max = min else if (second number is null) set max = BIGGEST else copy second number into buffer convert to long int save in max return (max) This design lets the user specify open ranges such as 40--, which gives a firm minimum number but lets the maximum default to a large number. This is handy for telling a program to operate on all lines starting at 40 and continuing until the last line (of unknown number) is reached. To determine whether a number is a member of the selection list, we can call the function selected(), which returns a nonzero value if the specified entry is a member of a range in the list. The selected() function scans the selection list (Slist) one array element at a time until it finds a range that contains its argument or until it finds a -1 flag that terminates the list. The source code for the selection functions is contained in select.c: ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 189 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ In mkslist(), strtok() is called with a pointer that is initially set to the start of the user-supplied list, to extract the first (possibly the only) token. The pointer is then set to NULL for subsequent calls to strtok() to extract additional tokens, if any, from the list. Acceptable separators are comma, space, and tab. This gives the list-maker considerable flexibility in forming the list string. If the list contains embedded spaces or tabs, it must be quoted, so that DOS sees it as a single argument. A range specification must not have any white space around the hyphen (-), so that strtok() can parse it as a single token. TSTSEL is a program that I used to debug the SELECT functions. It accesses the Slist data structure directly, so that we can see what gets stored in there for various list specifications. The operation of this program is straightforward. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 192 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The TSTSEL program produced the following output for one of my test runs invoked with the command line tstsel 1,2,3,5--10 ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 193 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The first line shows the argument containing the user's list. The next block of lines displays the contents of the select list, Slist. Note the -1 sentinel that marks the list's end. The next block of lines shows the results when selected() is used to query the select list to determine if a value is a member of a range. We have shown the results as YES/NO strings. Setting Tab Stops In processing files that contain text, it is sometimes necessary or desirable to alter tab-stop positions, or to convert tabs to spaces or the reverse. The formula for determining regular tab-stop positions is 1 + kn, where k is the requested interval and n is an integer in the range of 0 through some maximum number determined by the line length. Thus, for the value k = 8, tabs fall at 1, 9, 17, and so on. Variable tab stops are a bit more difficult to set up, but they have their uses. We might appreciate being able to set the tab stops for a FORTRAN program source file to 1, 7, 11, 15, 19, and 23, for example. We can apply the selection-list technique just described to the setting of tab stops at variable column positions in a line. The file tabs.c contains the source code for three functions used to set and test tab stops. A private array of characters holds the tab-stop data. Each character represents a column position in a line and contains 1 if the associated column is a tab stop and 0 if it is not. Two of the functions in the TABS module are used to set the tab stops. The fixtabs() function installs tab stops at regular (fixed) intervals. The interval is given as an integer argument to fixtabs(). The vartabs() function works from a list to set tabs at variable intervals. We use the SELECT functions to gather data from a user-supplied list and then convert it to the needed form. A third function, tabstop(), is used to query the Tabstops array. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 195 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The TABS module uses C's natural base of 0 as the first element of an array; therefore, all calculations are based on 0 as the leftmost column. We accommodate the difference between the TABS module's view of the world and the user's view of the world in the programs that handle the collection and presentation of tab data. The best way to see how this all works is to demonstrate it. The showtabs.mk file tells MAKE how to put it all together. The SHOWTABS program gets a user specification of the needed tab stops. A -f option flag means SHOWTABS is getting a fixed interval specification, and a -v option flag signals a variable tab list. These options are mutually exclusive, and the parsing of the command-line options enforces the use of only one of them. #makefile for SHOWTABS program LLIB=c:\lib\local tabs.obj: tabs.c msc $*; select.obj: select.c msc $*; showtabs.obj: showtabs.c msc $*; showtabs.exe: showtabs.obj select.obj tabs.obj $(LLIB)\util.lib link $* select tabs, $*, , $(LLIB)\util; ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 197 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ If SHOWTABS receives a variable list, it calls the SELECT functions to do the necessary conversion from the string form of the program argument to an array of integers that vartabs() understands. In the case of a -f option, SHOWTABS uses atoi() to produce a single number, which is taken to be a fixed interval specifier that is passed to fixtabs(). Once the Tabstops array is populated, SHOWTABS calls upon tabstop() to display the status of every column in the first 80 columns of a line. A plus sign (+) in the display marks columns that are nonzero multiples of 10. A T marks a tab stop, and a minus sign (-) marks all other positions. Figure 7-4 on the next page shows the results of various tab-setting calls to SHOWTABS. C> showtabs -v 1,9,17,61-68 T-------T+------T--+---------+---------+---------+---------+TTTTTTTT-+ C> FIGURE 7-4 ▐ Output from SHOWTABS Because the functions in both the SELECT and TABS modules are generally useful, we will add select.obj and tabs.obj to util.lib in \lib\local. In the next chapter, we will develop a group of utilities for DOS that emulate some of the UNIX utilities; this will help ease the transition of new users from one system to the other and will help those who are constantly moving between the two operating systems, as is the case for many software developers. SECTION III File-Oriented Programs Chapter 8 Basic File Utilities This chapter presents a set of file-oriented utilities that satisfy two primary goals. First, the commands give programmers who divide their time between UNIX/XENIX and DOS a set of programs that make it easier to switch back and forth between the two environments. The programs essentially implement a UNIX/XENIX-style interface under DOS. Second, the programs serve as models for other utility programs that you might like to add to your toolkit. The programs employ many of the functions and techniques we have developed thus far in the book plus a few that are new. The programs in this set include the following utilities: ═══════════════════════════════════════════════════════════════════════════ UTILITY ACTION ─────────────────────────────────────────────────────────────────────────── TOUCH │ update the modification times of files TEE │ split a stream into two separate streams PWD │ print the working directory pathname RM │ remove files LS │ list the files in a directory ─────────────────────────────────────────────────────────────────────────── Some of these programs perform functions already provided by DOS, but in a way that is more familiar to UNIX/XENIX users. LS is similar to the DOS DIR command. PWD does the job of the DOS CD command, when CD is typed without an argument. The RM command provides some enhancements over the standard DOS ERASE/DEL command. Other programs in this set are tools used by programmers that have no DOS equivalents. Update File Modification Time (TOUCH) We have been using the MAKE command to assist us in creating and maintaining programs. The MAKE command uses a file's last modification time and instructions in a "makefile" as the basis of its decision-making process. MAKE compares the modification time of an object with that of its sources (specified in a dependency list in the makefile) to determine whether an object is older than one or more of its respective sources. So, when we modify a source file, every object that lists that source file in its dependency list will be remade. At times, we may want to force an object to be remade. We can do this in several ways. We can edit a source file; even if we make no changes to the file, the act of saving the file with an editor updates its modification time. The source will then be newer than the object that is created from it, so the object will be remade. Another way to force an object to be remade is to remove it. MAKE will discover that the object does not exist and will remake it from the recipe in the makefile. A third way is to use a program called TOUCH to update the file modification time of the source file without making any other changes to it. This will also cause MAKE to remake the object. TOUCH is particularly handy when you want to force all the files in an entire project or subproject to be remade. A single TOUCH command does the work of many separate DEL or editor commands. The following pseudocode describes how TOUCH works. for (each named file) update time if (update not successful) increment error count if (verbose) print error message else if (verbose) print confirmation message The manual page for TOUCH is presented in Figure 8-1. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the figure found on page ║ ║ 207 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ FIGURE 8-1 ▐ Manual Page for TOUCH The source code for the TOUCH program is in the file touch.c. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 208 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ Note the use of two dummy functions, _setenvp() and _nullcheck(). These functions reduce the final program code size slightly by eliminating the code for environment processing and for checking attempts to reference data through null pointers. The _nullcheck() function is inside a preprocessor directive block that includes the code during debugging and omits it when the program is finally compiled. If we are really serious about minimizing code size, we will also eliminate calls to printf-family functions because the formatting code is rather large (about 2.5--8 KB, depending on the compiler and memory model used). Using fputs() and fputc() to synthesize the fprintf() function, when it is used to process only strings, will save several kilobytes in the executable program. But be on the lookout for "hidden" formatting. Depending on how the compiler supplier implements perror(), for example, you may find that a call to fprintf() gets dragged in anyway, even though you didn't use one directly in your code. Tapping a Pipeline (TEE) The TEE program is often called the "pipefitters' dream." The manual page for TEE (Figure 8-2 on the next page) tells you why. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the figure found on page ║ ║ 212 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ FIGURE 8-2 ▐ Manual page for TEE TEE always writes a copy of its input to the standard output stream. In addition, TEE attempts to open for writing any files given as command- line arguments. If the option -a is given, TEE attempts to open the files in append mode instead of write mode. By naming output files, the user creates a multi-way split and sends copies of the same input stream to two or more output streams. The pseudocode for TEE is set file mode string for (each name file) open file per mode string for each character received from stdin copy the character to all open output streams close all streams TEE is especially useful in debugging programs. I use it to view the output of a program on the screen while capturing a copy of the data stream in a file for detailed inspection using DUMP (Chapter 10) or a text editor. It is surprising what kind of garbage finds its way into the output data stream of an ill-behaved program. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 213 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The source code for TEE introduces the use of the standard library function fcloseall(), which can be used to shut down all open streams except the standard streams that were opened for you by the C run-time startup system. The function returns -1 in the event that it cannot close a stream. We report this to the operating system via the exit() function. The ERRORLEVEL feature of batch files can be used to test the return value, but DOS ignores it. Print Working Directory Path (PWD) The manual page for PWD (Figure 8-3) says all you need to know about "what" but may leave you wondering "why." What's wrong with typing CD without an argument to find out the name of the current directory? Nothing, really. But those of us who switch back and forth between DOS and UNIX/XENIX have certain reflex reactions that cause problems. Under UNIX/XENIX, a bare CD command reports nothing. Instead, it takes you back to your "home" directory from anywhere in the directory hierarchy. The PWD command is used to display the current directory pathname. I wrote a DOS PWD command to make the two environments a bit more alike for some often- used commands. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the figure found on page ║ ║ 215 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ FIGURE 8-3 ▐ Manual page for PWD The source for PWD, pwd.c, uses the standard library function getcwd() to get the current "working" directory pathname. The first argument can be the address of a user-supplied buffer that is long enough to hold a DOS pathname (64 characters). If NULL is used instead, getcwd() creates its own buffer, the length of which is specified by the second argument. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 216 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ Remove Files (RM) One of the limitations of the DOS ERASE/DEL command is that it accepts only a single file specification; if we want to remove several different types of files, a series of ERASE commands must be issued. Another limitation is the lack of an interactive deletion feature. RM does the job of ERASE while adding these two useful features. The manual page for RM is presented in Figure 8-4. The basic behavior of RM is the same as ERASE except that you may provide any number of exact and ambiguous filename specifications up to the limits imposed by the DOS command line. Each command-line argument (following command options, if any) is expanded if necessary. The -i option, when used, puts RM into an interactive mode that is a great help in avoiding the unwanted loss of files. Each deletion must be confirmed by a Y response and a Return--more work for the user, but safer. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the figure found on page ║ ║ 217 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ FIGURE 8-4 ▐ Manual page for RM The pseudocode for the heart of RM is for each file if (interactive mode selected) print file name prompt user for reply (y/n) read a line of input if (no) break else unlink file if (error occurred) print error message The source for RM is composed of three functions: main(), do_rm(), and affirm(). The return value of the call to unlink(), a standard library function, is compared to -1, which flags an error condition. The perror() library function is used to print an error message. There is no exit made at this point because other files may still need to be removed. The most likely error is an attempt to remove a non-existent file. Also likely is the typical failure caused by attempts to access a floppy drive that has no disk or has its door open. RM simply reports about non- existent files; it lets the DOS error handler deal with drive problems. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 218 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ That's it for the easy utilities. The next is more powerful and useful than the utilities we have just written and is appropriately more complicated and more difficult to write as well. As the weight lifters say, "No pain, no gain." List Directories (LS) Let's start with the manual page for LS (Figure 8-5 on the next page); it shows us where we are headed. Note that this LS command has six options. That may sound like a lot, but the UNIX/XENIX ls command has more than three times as many! To keep things simple and usable, I elected to leave many bells and whistles out of LS. Anyone who wants another 15 options is free to put them in. The pseudocode for LS only hints at the complications of doing this job in a DOS environment. Ignoring startup tasks (version control, option parsing, setting up a Ctrl-Break handler, and so forth), LS follows this general blueprint: allocate a buffer for file data allocate a buffer for directory data if (no arguments) get current directory pathname else for each named item if (it's a directory) add directory name to directory buffer else if (it's a file) add file name and data to file buffer if (any files in file buffer) sort entries send file list to output if (any directories in directory buffer) for (each directory) expand it to a list of files sort entries output list The LS program resides in several files that are devoted exclusively to LS-related chores. In addition, several DOS functions of more farreaching application are used. These are new, and will be added to the local DOS library that we created in Chapter 5. The header file, ls.h, shows the data structures that describe file data and the manifest constants needed to request and interpret file data. Note that the LS program deals with information about files, rather than the information that is in them. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the figure found on page ║ ║ 223 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ FIGURE 8-5 ▐ Manual page for LS ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 223 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The OUTBUF structure template is used to allocate storage for an output buffer that contains the name of a file, its modification data and time, the file size in bytes, and the file mode for each file in the default directory and any named directories. The basic substance of the LS program is in the file ls.c. It contains a slew of include file directives, a set of global configuration variables, the main() function, and a Ctrl-Break handler function. LS can produce mountains of output; therefore, we must provide a convenient way to break out if the user gets bored or finds the sought-after information part way through the listing. The main() function orchestrates everything, calling on other functions to do most of the hard work. Its job is to collect the user's requests and preferences and then to parcel out the work of getting file data, expanding directory names to the contents of the directories, and much more. Here is the ls.c file. Think what it might look like with 15 additional options! ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 224 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ Global variables are used to hold control information that is needed by other functions in the LS program. Global variables should not be used to pass data between functions. The main() function calls on malloc() to allocate memory for the file data structure and for an array of pointers to directory names. The technique used here allocates a fixed amount. If that amount proves to be too small to handle the job, additional space is obtained from realloc(). This guarantees that the expanded allocation is contiguous with the earlier allocation (even if the whole block has to be moved to a new location in memory), which makes it possible to use pointers and array indexes to access elements in the data areas. Two DOS functions, getdrive() and drvpath(), are called by main(). The first gets the current drive number (0 = A, 1 = B, and so forth), and the second appends to a copy of the current pathname onto a drive specification. /* * getdrive -- return the number of the default drive */ #include <dos.h> #include <local\doslib.h> int getdrive() { return (bdos(CURRENT_DISK)); } ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 231 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ These two files should be compiled and the resulting object files should be added to the dos.lib in the \lib\local directory. After the file and directory buffers have been filled, main() sequences the outputting of the data. All file data goes out first, followed by the file and directory names associated with each named directory. The simplest case is a list of files produced by a request like ls which produces a one-column listing of the file and directory names in the current directory. The output is done in a multi-column format if the MULTICOLUMN variable is set to the value of logical 1 by using -C on the command line or by renaming the LS program to either LC or LF under DOS version 3.00 or later. The output of LS is directed to the standard output stream, so it appears on the screen unless it is redirected. A default of 80 columns maximum is used to determine line length. This fits easily on most display screens and printers. You might want to add a feature that allows the line length to be controlled, either from the command line or by a configuration file or an environment variable. Output lists are sorted lexically by default. Options allow the user to select reverse sorting (-r) and sorting by last modification time (-t). The standard library sort routine, qsort(), does the sorting and calls on ls_fcomp() to compare items being sorted. The file ls_fcomp.c contains the source for the comparison function. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 233 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ After lists are sorted, they are sent to the output device by functions in the ls_list module. Single-column output is done by ls_single(). Multi-column output is handled by ls_multi(). The latter function is the more interesting one. First, here is the source: ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 234 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The ls_multi() function receives a sorted list of names, scans it once to find the length of the longest name, and then outputs the list in columns. The number of columns depends on the file data. Optimal column width and number of columns are determined by the length of the longest filename or subdirectory name to be output, thus maximizing the number of columns output and minimizing the number of lines used. All names are output in lowercase. Most people find words in all uppercase letters difficult to read; if you don't, feel free to leave out the call to strlwr(). The next function, ls_dirx(), is the workhorse to which falls the task of expanding a directory name into a list of its subordinate file and subdirectory names. This is not a trivial task. The file system under DOS is fractured--part residing in a fixed directory at the "root" level of a disk, and the rest in dynamically allocated subdirectories that are simply special files in the file system. In addition, we must be concerned with the use of a drive name (A, for example) as an alias for the current directory on that drive. Note: The drive name is not an alias for the root directory. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 238 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ To get the data it needs from DOS, ls_dirx() calls on three DOS functions: setdta() to establish a disk transfer area in memory; first_fm() to obtain the name of the first file that matches an ambiguous filename specification; and next_fm() to get any subsequent matches to the same specification. We will compile these three functions and add the object modules to the DOS library. /* * setdta -- tell DOS where to do disk transfers */ #include <dos.h> #include <local\doslib.h> void setdta(bp) char *bp; /* pointer to byte-aligned disk transfer area */ { union REGS inregs, outregs; inregs.h.ah = SET_DTA; inregs.x.dx = (unsigned int)bp; (void)intdos(&inregs, &outregs); } ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 241 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ In addition, ls--dirx() calls last--ch() to examine the last character in the pathname. If the last character is not a \, a \ is appended to the pathname. The last--ch() function is added to the \lib\local\util.lib library. /* * last_ch -- return a copy of the last character * before the NUL byte in a string */ char last_ch(s) char *s; { register char *cp; /* find end of s */ cp = s; while (*cp != '\0') ++cp; /* return previous character */ --cp; return (*cp); } To assist you in producing and maintaining the LS program, here is a makefile, ls.mk: ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 243 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The temptation to add features to LS is great. It (and its equivalents, such as DIR) is a high-use program, typically accounting for some 30 to 40 percent of command executions on a given system. Perhaps because of its visibility, it is a frequent target for enhancements. Try to avoid turning LS into a program that no one uses because it is too complicated. Chapter 9 File Printing One essential programmer's tool is a program that displays or prints the contents of text files--program source files, debugging listings, program "map" files, and so on. The PR program developed in this chapter to take care of this task is patterned after the UNIX utility of the same name. It is designed to be flexible yet not encumbered with unnecessary features. It provides a basic file-printing capability supplemented by a collection of helpful options. By default, PR produces output suitable for a generic line printer. It uses only the standard format-effector codes (carriage return and linefeed) and normal displayable characters (including space). The options enable you to use special features of the Epson and Epson-compatible printers, sequentially number lines, print a list of pages from a file, and control basic page layout. Many options of PR allow the program to be used as a filter, reading from its standard input and producing formatted pages on its standard output or other output streams. Program Specification Figure 9-1 on the next page is the manual page that describes the features and applications of PR. During the development of the program, the manual page served as a wish list. A prototype of PR, based on an earlier version of the manual page, was tested on some "friendly users." Their feedback led to changes in the manual page and subsequent revisions of the program that eventually resulted in the final program presented here. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the figure found on page ║ ║ 246 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ FIGURE 9-1 ▐ Manual page for PR I will describe the program's basic features and its options in detail as the PR functions are presented, but before doing that, we need to define just what is meant by a "page" of output. Figure 9-2 is a proposed page layout. The assumption that governs choices of default values is that standard document paper is used. A sheet of letter-sized paper is 8-1/2 inches wide by 11 inches long. (An additional half-inch on either side of a sheet of pin-fed paper contains the holes for the tractor feed, resulting in a raw page size of 9-1/2 by 11 inches.) A good guideline regarding page appearance is that at least 1/2 inch of unused space should be left on both sides and at the top and bottom. Using less white space tends to make a printed page look too crowded. left margin right margin ┌──────┬─────────────────────────────┬──────┐ │ │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│ │║ (TOP 1)─┼──────┼────▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│ │║ │ │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│ │║ │ │ │ │║ header │ │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│ │║ (TOP 2)─┼──────┼────▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│ │║ │ │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│ │║ │ │ │ │ │ │ │ │ │ │ │ │ │ │ text │ │ │ │ body │ │ │ │ │ │ (MARGIN)──┼── │ │ ──┼──(MARGIN) │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│ │║ (BOTTOM)─┼──────┼─▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│ │║ footer ┌──┐ │ │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│ │║ ┌──┐ ┌──┐ │ │ └──────┴─────────────────────────────┴──────┘ │▒▒│ │ │ │ │ print area non-print area │▒▒│ │ │ └──┘ └──┘ └──┘ FIGURE 9-2 ▐ Proposed page layout The left side of a page may need to be punched for ring binding, so some additional clear space might be needed there. For most purposes, however, I find that the default of 1/2 inch is enough. This indentation or offset is obtained by spacing in five columns for a 10-pitch font. Condensed type, such as that produced by an Epson printer in condensed mode, requires a larger number of columns (about eight) to obtain the same physical offset. Given the specification presented in the manual page and the values obtained from the proposed page layout, we can now design a program to produce nicely formatted listings of text files. We can start by noting that PR follows a pattern of behavior that is similar to CAT: It takes some input, applies some transformation, and produces some output. However, we will have to treat lines a bit differently to accommodate optional line- numbering, page offset, and other aspects of format. If our design is done well, we should have enough flexibility to handle 90 percent of all the printing needs of a programmer. The behavior of the PR program will be controlled by reasonable built-in defaults that may be modified by configuration files located in the current directory or in a directory selected by the user and by command-line options. After analyzing the requirements for PR and trying several simple prototypes to investigate ways of implementing the features, I settled on an organization for the program. Each program module is packaged in a separate file, usually with one function per file. The program has the following functions and calling hierarchy: main() getpname() pr_gcnf() fconfig() getopt() pr_help() pr_file() pr_cpy() mkslist() pr_getln() fit() lines() spaces() setfont() selected() pr_line() exit() As you can see, many functions that we developed in earlier chapters are called by functions used in PR. These external names are resolved by the linker, using util.lib as one of the searched libraries. If the user gives an erroneous option, main() calls pr_help() to display an abbreviated manual page on the stderr channel. The C source for pr_help() is: ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 250 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The function uses a static array of string pointers to message lines. The calculation in the line n = sizeof (m_str) / sizeof (char *) sets n to the number of message lines in a way that lets us add message lines without having to count them and declare how many are used. This makes it easier to modify the function as the program evolves, as most programs do. To achieve the desired flexibility, we will use a global data structure to hold the values of the important formatting and program- operation control variables used by the program's various modules. Only those modules that need to know about the data will be given access to the data structure. Here is the header file, print.h, that contains the data structure definition and some manifest constants used to initialize the program: ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 251 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ A typedef is used to create a synonym, PRINT, for the struct pr_st data structure. The structure contains about a dozen integer-sized variable definitions and two string variable definitions. The header file defines the printer data structure, but it does not declare any storage for it. That is done in the configuration function, pr_gcnf(), which we'll examine shortly. First, let's take a look at PR from the top. The main() function is contained in the file pr.c. It declares and initializes global variables, establishes the default output channel, processes command-line arguments, and calls pr_file() with a list of files named as input by the user. If no filenames are specified, PR uses the standard input channel so that data can be routed through PR from a redirected input or from a pipeline. Thus, PR fits the description of a filter in the same way as the DOS programs MORE and SORT, except that PR can be configured to send its output to someplace other than the standard output. In such cases, PR is referred to as a sink instead of a filter, because it is a termination point for data flow. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 252 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The main() function calls getpname() to get the program name and then calls pr_gcnf() to get the configuration data needed to initialize the program. Next, it uses getopt() to process user-supplied options, if any, and finally it passes a list of filenames (possibly none) to pr_file(). We have seen the use of getpname() and getopt() before. There should be no surprises here. Option Handling The pr_gcnf() function is specific to PR, but the design can be applied to other programs. The pseudocode for this function is if (a configuration file exists) open the file read numeric data read string data if (data good) set flag close file if (flag is set) initialize to values just read else use defaults from the header file Here is the source code for pr_gcnf(): ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 255 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The PRINT type is used to declare a global data structure for the printer, pcnf, which stands for printer configuration. Any other source file that needs access to pcnf must declare it as external data. If no configuration file is found, pr_gcnf() falls through to the default assignments. The fconfig() function we created in Chapter 7 is used to query DOS for an external configuration file. A NULL result indicates that none was found. If a configuration file is found, it is read in a line at a time. Numeric values are obtained by converting the character representations in the file to integers by using the standard library function atoi(). Because atoi() accepts only characters that can be considered part of a number, we can add comments to the lines. Thus, when the line 66 number of lines per page is retrieved from the configuration file and is given as the string argument to atoi(), the function merely assigns the integer value 66 to a temporary array. String arguments are handled similarly. A line is read in and the library function strtok() extracts the first token, which is the string value we need to save. The remaining characters on the line, if any, are ignored. An example of a string variable is p--dest, which determines where PR's output will go. This variable is a member of pcnf and is accessed using the dot operator as in pcnf.p_dest. Each line of output is sent by default to the device specified in p_dest. If p_dest is set to CON, or if it is null (""), output is directed to the standard output channel and will be displayed on the user's console screen unless program output is redirected. (MS-DOS and UNIX permit the standard output of a program to be redirected using the greater-than (>) symbol--see Chapter 3 or your DOS manual for details. Thus, output that would otherwise be displayed on the system console or a terminal screen may be sent to a printer port or captured in another file.) In this presentation of the PR program, I have set p_dest to PRN, the default printer device, because that is where I usually want the output to go. We can still send the output to the screen by selecting the -p (preview) option, which uses CON as the destination for a single invocation of PR. To display the contents of a file named myfile.txt on the system console, you would type pr -p myfile.txt To send the output to a printer that is attached to the default printer port, you would instead type pr myfile.txt If PR is compiled with ssetargv.obj included in the linker object list (as shown in the makefile, pr.mk), PR permits the use of wildcards in filenames, letting you use abbreviated command lines to specify print jobs. For example, to print hard copies of all the header files in the include subdirectory and in the include\sys subdirectory, type pr \include\*.h \include\sys\*.h If you have a hardware or software print spooler on line (such as the one provided with Microsoft Windows), you can turn your attention to something productive while your printer dumps a mound of paper on the floor. Otherwise, you'll have to mark time for a while. File Handling The processing loop in pr_file() receives a list of files and tries to get each file formatted and printed. The function must handle errors gracefully. If, for example, a user specifies a file that does not exist or one that cannot be opened, the program sends an error message to the standard error channel and then continues looking for more files to print. The standard error channel is used because messages sent to it will appear on the console screen even when normal program output is directed elsewhere. The standard input channel is used as a data source if no files are named on the command line. The pr_file function is also responsible for connecting the output of PR to the required stream. If the user has configured PR to send output to one of the standard output channels (sdtout, stdprn, or stdaux), there is no need to open the stream, because DOS has already done so when PR started running. Other destinations, such as a named file, must be explicitly opened for writing. The source code for pr_file() is: ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 259 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ Notice the message "Cannot stat (filename)" after the call to pr_cpy() (described next). This tells the user that file statistics could not be obtained for the named file even though it was found and opened. This flags a possible error with the disk directory and should inspire the user to find out why the error occurred. It could be that a bad sector is developing or that a disk formatting or updating problem has occurred. What's My Line? The work of orchestrating the formatting and copying of text pages falls to pr_cpy(). A line in a text file may be thought of as a single logical line that may be represented as one or more physical lines of output. Long lines of output--those that exceed the width of the printable or displayable area--may be handled in at least three ways. We can: let the line run long and leave the treatment up to the printer and its driver software. This approach can result in some bizarre looking output. "fold" a long line so that what cannot be displayed or printed on the current line is moved to the next output line. truncate the input so that anything on a line that would have to be displayed past the last column is effectively lost. The PR program has been designed to fold lines so that nothing is lost on output. If line-numbering is turned on, a logical line number is displayed at the beginning of each line. If a line has to be folded, as shown in Figure 9-3, the additional physical lines needed to print or display it are indented as usual, but they do not have a number field associated with them. Logical lines are numbered starting with one. The number of a line indicates its relative offset from the beginning of the file. . . . 46 /* process command-line arguments */ 47 while ((ch = getopt(argc, argv, "efgh:l:no:ps:w:")) != EOF) { 48 switch (ch) { 49 case 'e': . . . FIGURE 9-3 ▐ A folded line, as displayed by PR Before going any further, here are the pseudocode and C source code for pr_cpy(): set up source and destination streams if (source is stdin) get current time else get file modification time for each line in source file or stream if (line won't fit on page OR formfeed) eject page if (at top of a page) print header print the logical line if (not at top of page) eject page ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 262 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The pr_cpy() function handles a few other tasks in addition to fold- ing long lines. It detects that an input stream has ended before the output page is full and emits enough extra blank lines to get back to the top of a fresh page. That's so the next file will start printing in the right place. It makes sure that there is enough room remaining on a page to accept the next logical line. The static function fit() within the pr_cpy.c file does the needed calculations. The function also needs to handle a special situation that results from a fairly widespread practice. Programmers often create source files with two or more functions in them. Sometimes a literal formfeed control character (Ctrl-L) is placed between functions. This causes most printers to eject a page and to begin printing anew at the top of the next page. Care must be taken to keep the file-relative line and page numbers accurate. The functions mkslist() and selected() obtain a selection list and determine whether an item is in the list; they were explained fully in Chapter 7. These functions are called by pr_cpy() to process a list of selected pages, the Pagelist variable, to be formatted and printed by PR. The special page number BIGGEST is used to supply the high end of an open range specification (like 20--), which causes PR to print all pages between 20 and the end of the file. The pr_getln() function obtains a line of text from the input stream and expands it while reading it into the line array. The expansion alluded to here is that of converting each tab character in the input into the right number of output spaces so that column alignments are retained. The expansion is necessary because we will be doing indenting (page offset) and other formatting operations upon output, and because some older printers do not handle tabs correctly. All positions in the line array that are used to hold the text must be filled with characters that have a single unit of displacement in the output. This facilitates character counting so that fit() can determine how much space is required for the expanded line. This is the source code for pr_getln(): ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 266 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The tab expansion is done by the functions in tabs.c that were described in Chapter 7. Top-of-page processing is done directly by pr_cpy(), which prints the page header composed of some blank lines, a header line that contains the name of the current file (or a substitute text string), the output page number, and the date and time when the file was created or last modified. The blank lines are produced by a call to lines(), a function that emits a series of newlines to the specified stream. /* * lines -- send newlines to the output stream */ #include <stdio.h> #include <stdlib.h> int lines(n, fp) int n; FILE *fp; { register int i; for (i = 0; i < n; ++i) if (putc('\n', fp) == EOF && ferror(fp)) break; /* return number of newlines emitted */ return (i); } The filename as typed by the user is converted to uppercase. This is done because DOS automatically converts filenames returned in response to an ambiguous specification (using wildcards) in uppercase letters. We could just as easily convert everything to lowercase. The formatting of the header line differs from the text body when the Epson-compatible mode is selected. The setprnt(), setfont(), and clrprnt() functions described in Chapter 7 are employed to control the printer so that headers may be printed in a different typeface than the main text. (Although not a necessary feature, this demonstrates a practical use of different typefaces on a single page.) The text body can be printed in a compressed form, to permit long lines (up to about 137 characters) to be printed on standard letter-sized paper. The function pr_line() is called to output a logical line of text composed of two or three parts: a left margin produced by a call to spaces(), an optional file-relative line-number field, and finally the text of the expanded line. If additional physical lines are needed, spaces() is called at the beginning of each to obtain a uniform page offset. Here is the source code for pr_line(): ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 268 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The pr_line() function returns the number of physical lines that were used to print the single logical input line. The spaces() function (on the next page) is almost identical to lines(), except for the character that it emits (space instead of newline). /* * spaces -- send spaces (blanks) to the output stream */ #include <stdio.h> #include <stdlib.h> int spaces(n, fp) int n; FILE *fp; { register int i; for (i = 0; i < n; ++i) if (putc(' ', fp) == EOF && ferror(fp)) break; /* return number of spaces emitted */ return (i); } Since the tasks performed by lines() and spaces() are needed frequently in programs that send text to the screen or some other output device, we will add the object files lines.obj and spaces.obj to our utility library, util.lib, by compiling them and using the command lib util +lines spaces; Remember to copy the updated library into the \lib\local subdirectory so that LINK can find it. Program Maintenance A special-purpose library called prlib.lib contains all but a few of the object modules that comprise the PR program. The pr.obj file, which contains the main() function, is kept separate from the rest because of the way the DOS linker, LINK, works. The executable filename defaults to the name of the first object module specified in the link list, and at least one module must be named. The makefile script for PR is in pr.mk. It automatically keeps the needed objects and the prlib.lib file up to date as changes are made to the program source files. Here is the text of pr.mk: ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 271 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ Possible Enhancements As well endowed as PR is already, there is always some new wrinkle or feature that some user would like to see. In trying to avoid making PR into a program that serves everyone in every way but no one particularly well in any way, I have chosen to stick with the feature set provided. However, some users of PR have requested the following features, which you may want to consider adding. First, it might be helpful to have a multi-column output feature. This would take lines from a file and present them in columns across the page. Each line would be truncated if it exceeded the column width minus one character position for a separator. It would be necessary to format an entire page in memory before sending anything to the output. Another feature of interest to some users is a more elaborate way of controlling the appearance of the header and footer. This, to me, smacks of word processing, and I have elected to use Microsoft Word if I need such control over the output. The addition of single-sheet control might be useful to some users. I always use pin-fed, fan-fold paper, so I have not felt a compelling need for this feature. It can be added easily by introducing a new numeric (actually a Boolean) variable in the PRINT data structure and testing it before outputting a new page. One additional feature may make it into my next version of PR. Some users would like to be able to do side-by-side printing of multiple files. This is a kind of visual file comparison. It can also be used to generate, in a somewhat restricted way, scripts for plays and motion pictures. This could be done either a line at a time or by doing full-page makeup before generating output. Next, we will devise a program that lets us peer into nontext files that cause PR and DOS text-file programs (TYPE, for example) to produce strange and not particularly useful output. Chapter 10 Displaying Non-ASCII Text Our kit of programmer's utilities now contains some pretty useful tools: the CAT program for concatenating files and PR to print them out on paper; LS to list a directory in a variety of display formats; TOUCH to assist the MAKE command in building programs; and RM to help us clean up our disk directories easily. In addition, we have a raft of low-level and mid-level routines to help us create other tools. Thus far, we have been concerned only with text files and tools that permit us to view and manipulate them. However, one of the essential tools that a programmer needs to have at the ready is a utility that permits the inspection of nontext files. Nontext files are produced by compilers, tokenizing interpreters (such as Microsoft interpretive BASIC), assemblers, program configurators (see Chapter 7), and many commercial word processors, database-management systems, and spreadsheets. If you were asked to convert a file produced by a word processor that you do not have to a form that is acceptable to one that you do, how would you go about it? Ignoring the possibility of buying the needed word processor, we will have to do some detective work, which is what makes the computer business such a lot of fun for some and such a pain in the neck for others. The form and content of the data file would have to be determined so that it could be converted to a suitable form for the target word processor. A straight ASCII text file would suffice as data to be merged into the input stream of most word processors, so we would first attempt to remove any non-ASCII characters from the data file and save the results of the conversion in an intermediate file for later processing. But how would we examine the data file? Our current tools are suitable only for text files, so we need something else. In this chapter, we will develop a program called DUMP that takes any file and produces an output listing that looks like the dump output of the DOS DEBUG program. Each line of the output listing includes a hexadecimal offset in the leftmost column, a hexadecimal display of 16 (10 hex) bytes from the data file in the center, and the equivalent data in extended ASCII in the rightmost column. A character code that would cause problems on the display and on a printer is converted to a dot (.) before being displayed. These filtered codes include newline, carriage return, and most other control codes. The reason for developing a stand-alone program is that DUMP will allow us to capture the converted output in a file or on paper for easy examination. Our design will also permit DUMP to be used as a filter in pipeline commands. Before designing and programming DUMP, let's review some of the most common data-presentation formats and prepare some functions to do needed conversions. Some Useful Conversion Functions The primary data-presentation formats for numbers are the binary, octal, decimal, and hexadecimal notations. While we humans take more or less naturally to decimal (something to do with fingers and toes), our machines tend to favor binary, in which things are on or off (1 or 0). The octal (base 8) and hexadecimal (base 16) formats are simply notations that make binary data more palatable to us. Octal number representations were widely used for many years and still are in some quarters, but octal notation has lost favor with the majority of programmers, who use hexadecimal notation instead. All characters in the computer are represented internally as binary numbers, however. That's all the computer "understands." Our task is to receive data, convert it to the desired form, and send it to the standard output. The output will be displayed on the computer or terminal screen, or sent to some other device if stdout is redirected. Our programs will need to convert the computer's internal representation of numbers into decimal, hexadecimal, or character forms, depending upon what we are trying to see. We will use two functions to do this. They are used in DUMP and will be placed in the utility library (util.lib) for use by other programs. The first function, byte2hex(), converts a byte-sized (8-bit) quantity to hexadecimal. The second, word2hex(), performs the same job on a word-sized (16-bit) quantity. These sizes are appropriate for the IBM PC and other 16-bit machines, but they are not universal, so portability to other machines is not guaranteed. Both byte2hex() and word2hex() are packaged in a single source file named hex.c, which has the following contents: ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 275 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The hextab array is a conversion lookup table. It uses a number in the range of 0 through 15 as an index into the table, where the corresponding character constant (number or letter) is found. Hence, the numeral 3 is represented by a character constant of 3 (ASCII code 51--be sure you know the difference), and the number 10 is represented by an A. These half-byte quantities are comically referred to as "nibbles" because they're smaller than bytes. The symbolic constant NIBBLE is defined as 0x000F. It is used to mask off all but the four bits of interest in each conversion step. Right-shift operations are used to pull the needed bits into the correct position for conversion to a hexadecimal digit. A byte can be conveniently expressed as two hex characters (two nibbles) that represent values in the range of 0 (00 hex) through 255 (FF hex). The same range in binary is 00000000 through 11111111, which obviously lacks notational convenience. The hex notation is more compact, requiring only two characters to represent any value in the range. Now that we have a simple means of displaying data in hexadecimal, we can move on to the development of the DUMP program. A DEBUG-style File-dump Program The design of DUMP is strongly influenced by the expectation that its output will be easy to feed to other programs and to a generic printer. We want to build in enough flexibility to permit DUMP to be used as a filter or as a stand-alone program. In stand-alone operation, DUMP takes a list of files as arguments and produces the hex/ASCII output for each in sequence on its standard output. As a filter, it receives a stream of arbitrary characters and transforms it to the hex/ASCII output stream. The proposed format of DUMP's output looks a lot like that of DEBUG. One difference is that the offset of each block of 16 bytes will be shown relative to the start of the displayed file. We won't know where the file is located in memory, so the offset value will stand alone. Another difference is more subtle. DEBUG converts all non-ASCII characters in the text display area to dots. DUMP will display all standard ASCII characters plus the IBM extended ASCII character set when output is directed to the screen. A command-line option will allow us to strip all nonprintable characters from the output stream so that we can use any type of printer as an output device. Figure 10-1 on the next page is the manual page for DUMP. Note the overall simplicity of the program. Therein lies its power, because it can be used in a wide range of situations without change. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the figure found on page ║ ║ 278 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ FIGURE 10-1 ▐ Manual page for DUMP The code for DUMP is straightforward. DUMP follows the pattern established in Chapter 8, where file-oriented utility programs used similar command-line options to control program operation and write to the standard output channel. Here is the pseudocode description of the main() function of DUMP, excluding the generic items, such as getting the program name from DOS and error checking at each step: if (no files named) hexdump(stdin) else for each file open(file) hexdump(file) close(file) The hexdump() function does the work of transforming the input into the desired presentation format: for each block of input [BUFSIZ] for each block of bytes [NBYTES] copy byte offset into output buffer [word2hex()] copy hex values into output buffer [byte2hex()] copy ASCII values into output buffer copy output buffer to stdout The main() function of DUMP uses getopt() to scan the command line for optional arguments and filename arguments. If the -s option is found, the Boolean variable sflag is set to TRUE to indicate that non-ASCII characters should be stripped. If the -v option is found, the Boolean variable vflag (verbose) is set to TRUE and a header consisting of a blank line followed by the name of the file being dumped is output before the formatted data for each file is listed. You may want to add other data to the verbose output, such as file date and time, character count, and so on. If no filenames are specified, DUMP reads from its standard input and the verbose option is ignored because no name is associated with the data stream. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 279 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ One or more filenames can be specified either directly or by wildcard specifications. Like CAT and PR, DUMP will operate sequentially on a list of files in the order in which they are presented. Ambiguous filenames under Microsoft C are expanded in lexical order, not directory order. Files are opened in binary mode, not translated mode, because we will most likely be reading nontext files. Even if we read a text file, we want to be able to see all characters, so the translation of the CR/LF and Ctrl- Z codes is inappropriate. The hexdump() function uses an internal buffer, outbuf, to form a line in memory before outputting it with the fputs() library function. Although the buffering is not essential, it collects the writing operation into a single function call instead of having five separate calls to several different library routines. This buffering approach makes it easier to change the output code if we decide to use a different means of writing the output to the screen. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 282 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ Figure 10-2 on the next page is a sample of the output produced by DUMP. The figure shows the hexadecimal and equivalent text output produced by DUMP when it uses the hex.obj object file as input. DUMP was not instructed to strip all nonprintable characters from the output listing. ╓┌─────────┌────────────────────────────────────────────────┌──────────────── 00000000 80 07 00 05 68 65 78 2E 43 BE 88 07 00 00 00 4D │Ç...hex.C╛ê....M│ 00000010 53 20 43 6E 88 05 00 00 9F 45 4D 42 88 09 00 00 │S Cnê...ƒEMBê...│ 00000020 9F 53 4C 49 42 46 50 10 88 08 00 00 9F 53 4C 49 │ƒSLIBFP.ê...ƒSLI│ 00000030 42 43 64 88 07 00 00 9F 4C 49 42 48 B3 88 06 00 │BCdê...ƒLIBH│ê..│ 00000040 00 9D 30 73 4F E3 88 06 00 00 A1 01 43 56 37 96 │.¥0sOπê...í.CV7û│ 00000050 2E 00 00 06 44 47 52 4F 55 50 05 5F 54 45 58 54 │....DGROUP._TEXT│ 00000060 04 43 4F 44 45 05 5F 44 41 54 41 04 44 41 54 41 │.CODE._DATA.DATA│ 00000070 05 43 4F 4E 53 54 04 5F 42 53 53 03 42 53 53 3F │.CONST._BSS.BSS?│ 00000080 98 07 00 28 CA 00 03 04 01 67 98 07 00 48 10 00 │ÿ..(╩....gÿ..H..│ 00000090 05 06 01 FD 98 07 00 48 00 00 07 07 01 0A 98 07 │...²ÿ..H......ÿ.│ 000000A0 00 48 00 00 08 09 01 07 9A 08 00 02 FF 03 FF 04 │.H......Ü... . .│ 000000B0 FF 02 56 9C 0D 00 00 03 01 02 02 01 03 04 40 01 │ .V£..........@.│ 000000C0 45 01 C0 8C 2D 00 0A 5F 5F 61 63 72 74 75 73 65 │E.└î-..__acrtuse│ 000000D0 64 00 09 5F 62 79 74 65 32 68 65 78 00 09 5F 77 │d.._byte2hex.._w│ 000000E0 6F 72 64 32 68 65 78 00 08 5F 5F 63 68 6B 73 74 │ord2hex..__chkst│ 000000E0 6F 72 64 32 68 65 78 00 08 5F 5F 63 68 6B 73 74 │ord2hex..__chkst│ 000000F0 6B 00 A8 A0 14 00 02 00 00 30 31 32 33 34 35 36 │k.¿á.....0123456│ 00000100 37 38 39 41 42 43 44 45 46 A8 A0 CE 00 01 00 00 │789ABCDEF¿á╬....│ 00000110 55 8B EC B8 04 00 E8 00 00 56 8A 46 04 2A E4 89 │Uï∞╕..Φ..VèF.*Σë│ 00000120 46 FE 8B 46 06 89 46 FC 8B D8 FF 46 FC 8B 76 FE │F■ïF.ëFⁿï╪ Fⁿïv■│ 00000130 B1 04 D3 EE 81 E6 0F 00 8A 84 00 00 88 07 8B 5E │▒.╙εüµ..èä..ê.ï^│ 00000140 FC FF 46 FC 8B 76 FE 81 E6 0F 00 8A 84 00 00 88 │ⁿ Fⁿïv■üµ..èä..ê│ 00000150 07 8B 5E FC C6 07 00 8B 46 06 5E 8B E5 5D C3 55 │.ï^ⁿ╞..ïF.^ïσ].U│ 00000160 8B EC B8 04 00 E8 00 00 56 8B 46 04 89 46 FE 8B │ï∞╕..Φ..VïF.ëF■ï│ 00000170 46 06 89 46 FC 8B D8 FF 46 FC 8B 76 FE B1 0C D3 │F.ëFⁿï╪ Fⁿïv■▒.╙│ 00000180 EE 81 E6 0F 00 8A 84 00 00 88 07 8B 5E FC FF 46 │εüµ..èä..ê.ï^ⁿ F│ FIGURE 10-2 ▐ Hex dump sample (HEX.DMP) When the -s option is selected, the ASCII text display is surrounded by vertical lines formed from the vertical bar symbol (|). The normal output, which assumes that the destination device is the PC screen, uses the IBM drawing character (code 179) for a single vertical line; this looks pretty on the screen, but cannot be printed correctly by many printers. The makefile for DUMP is contained in dump.mk: # makefile for dump utility LIB=c:\lib LLIB=c:\lib\local dump.obj: dump.c msc $*; hexdump.obj: hexdump.c msc $*; dump.exe: dump.obj hexdump.obj $(LLIB)\util.lib link $* hexdump $(LIB)\ssetargv, $*, nul, $(LLIB)\util; To compile DUMP, first compile hex.c and add the object file to the utility library (\lib\local\util.lib); then type MAKE DUMP.MK The resulting executable file, DUMP.EXE, should be placed, as usual, in a directory that is accessible to DOS via the PATH variable, so that it can be called from anywhere in the directory hierarchy. The DUMP program can now be used for one of its intended purposes-- determining the file format of a special-purpose data file. This will help us build another useful tool, SHOW, which lets us see nonprintable characters in files in an unambiguous way and recover text from specially formatted files. The SHOW Program The next program is called SHOW because it shows us things that we might not otherwise see. SHOW closely resembles DUMP in construction and purpose, but its output is very different from DUMP's. If the task at hand is to retrieve the essential text from a document file, rather than to determine how the formatting was done, we need a tool that filters out the nonprintable codes and emits a stream of ASCII-only text. In some situations, we might also want to see the formatting codes represented visibly. The SHOW program takes files that may contain special (usually nonprintable) characters in addition to normal text and produces an ASCII text output. Nonprintable codes are converted to their displayable hexadecimal notation--a backslash followed by two hex digits. Two options allow us to strip out special codes and produce an output that is pure text. The -s option strips all special codes except the usual format effectors (newline, tab, and space). The -w (word-processor) option strips special codes (by setting the -s option), but it handles several additional elements of word-processor data files as well. For example, when forming paragraphs, many word processors use a carriage return as a "soft" return (line break) and a combined carriage return and linefeed as a "hard" return (paragraph terminator). For compatibility with such word-processor file formats, the -w option of SHOW converts a lone carriage return to a newline, thus breaking long lines into a sequence of shorter ones. Also, some word processors use the eighth bit of some bytes to signal formatting options (bold, underline, end-of-word, and so on). To make these bytes visible, SHOW (with the -w option set) turns off the high bit of all bytes and displays the bytes that then fall into the printable ASCII range. The full manual page for SHOW is presented in Figure 10-3. Notice that SHOW is also a filter: It can read from its standard input channel and write the transformed output to the standard output channel. The pseudocode description for SHOW is nearly identical to that of DUMP. The primary differences are found in the showit() function, which is described (without options) by the following pseudeocode: for each input character if it's ASCII if it's printable or a format effector send it to stdout else send printable equivalent to stdout The options -s and -w add some minor complications to the description. The effects of the options are best seen in the code for the main() and showit() functions. In main() (in the file show.c), getopt() is once again used to process command-line options. A variable, wflag, controls whether SHOW attempts to convert word-processing data files. It is initially FALSE. The call to getopt() requires the addition of w to the allowed option list. The value of wflag is passed to showit() as an argument, rather than being treated as global data. If SHOW had a lot of functions that needed to know about wflag, we would probably make it a global variable. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the figure found on page ║ ║ 287 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ FIGURE 10-3 ▐ Manual page for SHOW ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 287 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The showit() function receives a FILE pointer and the values of sflag and wflag. If neither of the flags is TRUE, showit() passes anything that is printable (including format effectors) to the standard output channel and converts everything else to a displayable hexadecimal byte representation. Thus, the null byte is shown as \00, the ASCII Del character is shown as \7F, and so on. If -s was used on the command line, sflag (and therefore strip) is TRUE, which causes showit() to eliminate the hexadecimal conversions. Setting the -w option sets the wp variable in showit() to TRUE, causing the function to alter the default treatment of carriage returns and extended characters. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 290 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The makefile for SHOW is similar to the one for DUMP: # makefile for the show program LIB=c:\lib LLIB=c:\lib\local show.obj: show.c msc $*; showit.obj: showit.c msc $*; show.exe: show.obj showit.obj $(LLIB)\util.lib link $* showit $(LIB)\ssetargv, $*, nul, $(LLIB)\util; To see the output of SHOW, try the program on a data file from a word processor or spreadsheet with and without the optional processing features. The results should be at least intriguing and will probably be enlightening to those who have not snooped around in such files before. In the next section, we move from the line-by-line realm of file oriented programs to the intensely visually oriented programs that make the PC so popular with the average user. SECTION IV Screen-Oriented Programs Chapter 11 Screen Access Routines In this chapter and the next two, we will explore some of the many options available to designers for presenting information on a PC screen. The method of screen access presented in this chapter is relatively easy to implement, produces excellent results, and costs little in terms of program size and complexity. Its use is not recommended for programs that will operate in a windowing environment, however, because it violates one of the primary rules of good behavior: "Thou shalt not write directly to the screen." We will purposely break this rule at first to show what level of performance we are striving for. In Chapter 12, we will explore some interesting display buffering techniques and show how we can be "good" boys and girls by using BIOS-based screen routines as an alternative to direct access. Then, in Chapter 13, we will seek to be downright virtuous by using the ANSI standard interface that is portable to nearly every PC that runs a version of MS-DOS (and PC-DOS). Determining the Display System Type One of the challenges that has always faced PC software designers is writing a program that determines what type of display adapter and monitor is in use before it does anything else. It is unfortunate that many programs ignore this crucial first step. Many of the offending programs were designed by programmers working on monochrome-only systems. When run on a color/graphics-equipped system, these programs at least alter the user's selected video attributes so that either during or following the program's running, the screen is unpleasant to look at or has a whole new shade of reality. Sometimes, but not too often, the screen gets completely messed up by being left in an inappropriate video mode. Programs designed for color-only systems can produce similarly unpleasant effects on monochrome systems. For example, light blue is a very pleasing color for text, but it causes everything on a monochrome system to be underlined and intense. Then there's the problem of a program that assumes the needed display adapter is in use and does not check for its presence. This can leave the user with a system that appears to be frozen. And it isn't just amateur programmers who are guilty of these transgressions. Although most commercial software offerings check the hardware, many supposedly "commercial quality" programs have the bad manners to ignore the user's color preferences, video mode settings, and so on. We can do something about this situation. Following are some routines and program examples that show how to detect, save, and restore the user's operating conditions. The routines use BIOS functions and simple memory tests to determine what equipment is installed. You can call the functions, as demonstrated in the DSPYTYPE program that follows and the ScreenTest (ST) program later in this chapter, and save the video state at the time your program begins execution. The original operating conditions can then be restored before the program returns control to DOS. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 296 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The DSPYTYPE program is a test driver for the functions memchk() and ega_info(). These functions supplement the BIOS equipchk() and getstate() functions we saw in Chapter 5. The memchk() function looks for memory at a specified segment and offset. It is a small-model function that calls on the library function movedata() to write and read the contents of memory locations. A large-model version of memchk() would use memcpy() in place of movedata(). The memcpy() function takes long pointers used in large-model programs; movedata() requires segmented addresses to access far data items in small-model programs. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 298 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The technique used to detect the presence of a monochrome display adapter (MDA) or a color/graphics adapter (CGA) involves a sequence of operations that save, write, read, compare, and restore the contents of a memory location that is known to be in the range of the given adapter. The save and restore operations ensure that the test is non-destructive. The write-read-compare operation determines whether there is any active memory at the test location. The value 55H is a bit pattern of alternating 0s and 1s. Because unoccupied memory locations tend to look like 1s to programs that try to read them, the pattern of the test value used by memchk() is not likely to be duplicated. If you want to feel more sure of the results, use sequential tests at the same address with two or more different values. But why bother looking at the memory--why not simply read the mode value returned by getstate()? We will probably want to do both in our programs. Use getstate() to find out what the operating video mode is, and look for memory at the other adapter locations. Some PC users (programmers in particular) have both monochrome and color display systems installed in a PC. A program that was designed to work exclusively with a CGA system might find the system in mode 7 (monochrome). The program can respond to this in two ways: It can print a message stating its need for a CGA and quit, or it can look for a CGA system and switch to it if one is found. I favor the first approach because the user may have the color system turned off. He or she can use the DOS MODE command to select the needed display mode (MODE MONO to select monochrome; MODE CO80, MODE CO40, and so on, to select a CGA mode). The memchk() function has other uses, too, such as looking around for blocks of memory that might be separated from the main memory of a system. It cannot be used to detect the presence of read-only memory (ROM), of course, because ROM cannot be written to and it will fail our tests. You can use memchk() to check memory locations at one-kilobyte increments to count up how much RAM is available to DOS and how much might be noncontiguous. Many add-in memory boards permit splitmemory addressing, allowing you to set up stand-alone print spoolers and other special memory allocations. With memchk(), we have a convenient way to find them. Add memchk() to the utility library to make it readily accessible to your programs. The enhanced graphics adapter (EGA) complicates the video-adapter detection problem a bit. The address space of the EGA nominally starts at segment A000. However, an EGA's addressing modes are very flexible, and the adapter usually masquerades as a CGA or MDA while operating at the DOS command level, setting itself up to start at either the B800 or B000 memory segments. The problem is in determining whether an EGA or some other adapter is installed at a particular location. The function ega_info(), based on information provided by IBM, looks for an EGA by calling the BIOS video interrupt 10H and invoking the Alternate Function Select function AH = 18 (12H), which is an EGA BIOS feature (the EGA BIOS is located at segment C000H). When AL equals 10H upon entry, this function returns EGA information, which includes the EGA mode (color or monochrome) and memory size (64 to 256 KB) in addition to feature and switch-setting information. An EGA display system is absent if ega_info() returns mode values other than 0 and 1 and memory size values outside the range of 0 to 3. If an EGA is found, checking the video mode returned by getstate() tells us whether it is emulating a CGA or MDA. If we need to know if another adapter is installed, we can use memchk() to do the test. If an EGA is emulating a CGA, you cannot have a real CGA installed, so we need check only for the adapter type not being emulated by the EGA. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 301 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ DSPYTYPE is a simple program that calls ega_info() and memchk() to determine what display adapters are installed in a system and to report the results to the user. DSPYTYPE also reports the current video mode, screen width, and screen page number. In practice, we would use the functions to get the video mode and the display adapter configuration, and then set up the needed display conditions for our program or abort with an explanatory message about the lack of needed hardware. Next we will consider a method of direct screen access for reading and writing that serves as an alternative to using BIOS and DOS methods of screen access. The BIOS and DOS functions automatically deal with the wide variety of display configurations that are possible in a PC system, but they introduce a lot of processing overhead because an adapter test occurs with every character (or dot) that is written or read. The display-adapter detection methods just described are important to direct screen access because they let us do the adapter tests once at program start-up, cutting out a huge amount of processing during subsequent screen read and write operations. Direct Screen Access A fast but inherently nonportable way of updating the PC screen is to write directly to its associated memory. Using one or more off-screen buffers in the program's data space to create images before displaying them can produce excellent visual performances. A block-copy routine quickly copies the buffered-memory image to physical display memory, producing an "instant screen" effect. The IBM monochrome display adapter exhibits no problems with this strategy. Neither do the IBM enhanced graphics adapter and many third party monochrome and color/graphics adapters, all of which have been designed to permit simultaneous access to display memory by both the CPU and the display-refresh circuitry. The original CGA in either 40-column or 80-column text mode poses a problem for designers because, unlike the monochrome adapter, the CGA exhibits visible interference when a program tries to access display memory while the monitor screen is being updated (refreshed) from the same memory. The interference looks like "snow"--an irritating pulsing of short line segments covering all or portions of the screen. Several methods of avoiding the interference have been developed. One is to synchronize the display accesses during both reading and writing operations with the time periods within a display-refresh cycle that are considered "safe." The safe times are the horizontal and vertical retrace periods of each displayed frame. Another method involves blanking (turning off) the raster scan while the display memory is being written to. As we'll see, each approach has advantages and disadvantages. Display Adapter Basics We begin with a brief examination of the color/graphics adapter to see why the retrace periods are the only safe times for display memory accesses. This discussion is not applicable to the IBM enhanced graphics adapter because it uses faster memory devices and additional logic that prevent problems that occur when the CPU and video-refresh circuitry try to access the video buffer simultaneously. The memory on the standard CGA is placed within the address space of the central processor. The CGA memory starts at segment B800H and extends upward for 16 KB, enough memory for one high-resolution graphics screen (128,000 picture elements), or four screen pages in 80-column color text mode. The text mode is the focus of this discussion. ╔══════════════════════════════════════════╗ ║ ║ ║ Figure 11-1 is found on page 303 ║ ║ in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ FIGURE 11-1 ▐ Typical horizontal sweep signal Figure 11-1 on the previous page represents the horizontal sweep signal, which is the signal within the display device that is responsible for the horizontal deflection of the electron beam that paints the screen. The figure depicts one horizontal scan period. The dependent (vertical) axis depicts the amount of beam deflection as a function of time shown along the independent (horizontal) axis. On a computer display device, the image on the screen is under-scanned so that the image is completely visible within the normal viewing area, resulting in a framed picture with a visible border. Television sets, on the other hand, use over-scanning to make the image "bleed," leaving no border. The beam is turned off completely (blanked) during retrace to avoid leaving unwanted residue on the screen. The IBM display is not interlaced, so there are 262.5 horizontal scans per frame (one full screen image), and frames occur at a rate of 60 per second. With 15,750 horizontal scans per second, each one takes about 63.4 microseconds. Only a small portion of a single scan, typically 20 percent or less, is allocated to the horizontal retrace--one of the safe times for display memory accesses, as can be seen in the figure. The horizontal sweep signal moves the electron beam from side to side, and if it were the only sweep signal affecting the beam, there would be only a single straight line on the display surface. Another kind of sweep signal is needed to move the beam up and down the face of the tube. The vertical sweep has the same basic sawtooth shape as the horizontal sweep, but a slower rate of change. At minimum deflection, the beam is at the top of the screen; it moves toward the bottom with increasing deflection. There is a vertical retrace period at the end of each frame that occurs during the vertical-sync pulse period. During this time, the electron beam is blanked and moved from the lower right corner of the screen back to the upper left corner. The vertical-sync period (typically a little more than one millisecond for the standard American TV signals used by the CGA) is long enough to permit a block of about 250 data words (2- byte character and attribute pairs) to be transferred to or from display memory without interference. Most video controller designs disable the horizontal sweep during the vertical retrace, but some let it run continuously. Programming Considerations A few important choices affect the way programs that interact tightly with the display system are designed and written. There are enough choices at every step in the process of designing a video application so that no two designers are likely to do the job in exactly the same way. The following program implements one way of designing a video interface. It is not the only way. Other methods that are even more intimately tied to specific hardware can run as much as four times faster than the method described here, but they are much less portable to other hardware configurations. I decided to use a buffered screen interface. This means that the image to be sent to the display is assembled in the program's own data space. When complete, the image is copied in its entirety as quickly as possible to display memory. Conversely, an unbuffered approach is used by many programs and is adequate for most purposes. In the typical unbuffered scheme, characters are written into display memory via DOS and BIOS routines, but no memory image is retained by the application program. The DOS and BIOS routines can also be used in a buffered screen-management system but will slow things down quite a bit compared to direct methods. As we'll see in the next chapter, careful design can greatly improve the apparent speed of the DOS and BIOS routines under many operating conditions. The routines described in this chapter assume that programs calling them have already done an equipment inventory and have set up the display system in an 80-column text mode. The getstate() function obtains the current video mode, screen width, and visual display page values. Mode values of 2 or 3 indicate 80-column text modes (monochrome and color, respectively) on a CGA, and a value of 7 indicates a monochrome adapter. The DOS MODE command may be used to select an appropriate video mode before calling programs that require a particular mode. Alternative Solutions Available methods of synchronization to avoid visual interference on a CGA depend on the use of the status register at I/O address 3DA hex. This is a read-only register on the CGA that has two bits of interest to the block-copy routine described below. When high (1), bit 0 indicates that a horizontal retrace is in progress. When high, bit 3 indicates that a vertical retrace is in progress. Another register--a write-only register at I/O address 3D8 hex on the CGA--has a bit that may be reset (made 0) to disable video. Bit 3 must be set to a value of 1 to turn on the beam that paints the screen. Turning off the beam is an effective way to prevent visual interference from reaching the viewer's eye. However, the beam cannot be left off for more than about three character rows' worth of data before a flicker becomes apparent. The BIOS video scroll routines use this technique and are not pleasant to look at if the background color is anything but black. Even normal text on a black background appears to dim somewhat in the upper half on the display when the blanking method is used. A Synchronized Block-copy Routine The direct method of screen access uses a memory buffer that holds the same amount of data as one display page on the standard CGA. The block-copy routine, cpblk(), copies the contents of the memory buffer to display memory only during safe times. The memory buffer has a total of 4000 bytes; 2000 bytes are for characters (25 rows by 80 columns), and the other 2000 bytes hold the attributes associated with the characters. Display memory has 4096 bytes per page (four pages in 80-column mode), but the last 96 bytes of each page are unused (except by some programs that hide information in them). The C-language source for the block-copy routine is cpblk.c. An image is copied from application memory to display memory as a series of ten blocks of 200 words each. Each word represents a character and its associated video attribute. (An assembly-language version of this routine is described in my "Instant Screens" article in the June 1986 issue of PC Tech Journal. Portions of this chapter are based on that article.) ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 306 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The C version of cpblk() is about 60 percent slower than its assembly- language counterpart, but it is fast enough for most purposes, copying an entire screen in about two-tenths of a second. The assembly-language version uses both horizontal and vertical retrace periods to reduce the number of blocks needed to six instead of ten. The use of ten blocks is conservative and will work with nearly all IBM-compatible display reduce the number of blocks needed to six instead of ten. The use of ten blocks is conservative and will work with nearly all IBM-compatible display hardware. On all of the IBM machines I tested, eight blocks were sufficient; however, some compatibles required smaller blocks because of differences in the timing of the retrace signal used to determine the safe time for copying data. Double Buffering To obtain the snappiest looking performance from a buffered screen- interface technique, programs can use an in-memory screen buffer that is updated out of view of the user and then is copied to display memory as fast as possible. A way of achieving nearly instant CGA updates is shown in Figure 11-2. The technique is called double buffering because two levels of buffers are maintained in the application program and elsewhere in main memory. A two-step process is used to form a composite image in a screen buffer before it is copied to physical display memory. Data source buffers may be of any size and are usually thought of as being rectangular in shape although they are simply sequences of bytes in memory. They are mapped to the off-screen buffer as needed--a technique that permits windows for help frames, menus, and the like to be easily overlaid onto another image. In the next chapter, we will write a set of library functions that handle the needed operations, such as writing characters, attributes, and strings, scrolling regions, and so on, and demonstrate the technique in a sample program. ╔══════════════════════════════════════════╗ ║ ║ ║ Figure 11-2 is found on page 308 ║ ║ in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ FIGURE 11-2 ▐ Double buffering Once the off-screen buffer has all of its characters and attributes in the right places, the task of getting the data to the visual display is handled by the cpblk() routine described above. If the screen buffer is copied directly to the part of display memory being viewed, the user will see the screen being updated, albeit very quickly. If the contents of the before and after images vary only in small areas, it is difficult to notice that an update occurs. If, however, there are massive image changes, such as switching background colors, the user will detect the update. For some purposes, the visible updating of screen displays is desirable because it reassures the user that the program is doing something. In other situations, we will want screen images to snap instantly into place. We can have it either way. Demonstration Program The file st.c contains the C-language source for a test driver program called ST (for ScreenTest). The driver program uses a static screen buffer to hold text images that are copied en masse to display memory after the image is fully constructed. The getkey() function (see Chapter 5) calls DOS function 7 hex, which returns the next available character in the keyboard buffer. The function waits for a keypress if nothing is ready. The driver program displays a help message for any nonprintable keypress except Esc (the Quit command) and Ctrl-Break (Abort). As each character is keyed in, its value is used to fill the screen buffer. Differing color attributes derived from the character code are used to show the effects of massive color and intensity changes. The attribute for a given character is the code for the character shifted left 8 bit positions. The high bit is masked off to prevent screen blinking. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 309 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The driver program uses a trick called "page flipping" to produce the appearance of instant screen displays. It actually takes a few tenths of a second to copy a screen buffer in the application data space to the display adapter using the cpblk() routine. Although this is fast when compared to all other methods that avoid video interference, it is still far from instantaneous. The page flipping method is possible because the CGA has enough display memory to hold multiple screen pages simultaneously. An illustration of page flipping is presented in Figure 11-3. The method depends on having a means of telling the display system to view one page of display memory while the application program is writing to another. The ROM BIOS video interrupt includes a function (5) that sets the visual page. ╔══════════════════════════════════════════╗ ║ ║ ║ Figure 11-3 is found on page 313 ║ ║ in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ FIGURE 11-3 ▐ Page flipping COMMENT Ignore the Technical Reference statement that the function sets the "active" page. To be consistent with the way BASIC describes video pages, the active page should be the one being written and the visual page should be the one being viewed. Most frequently, the visual and active pages are one and the same display page. Notice that the fprintf() standard library function writes to standard error, which appears on the visual page. The cpblk() routine, however, is directed to write to the active page, which is effectively hidden from view. When the active page has been fully written, it is revealed to the user by flipping the pages. The function swap_int() exchanges the values of the apg and vpg variables. The source for swap_int() is contained in the file swap_int.c. The function is useful in other contexts, so we will add it to our utility library. /* * swap_int -- exchange the values of the two integers */ void swap_int(p1, p2) register int *p1; register int *p2; { int tmp; /* exchange the values */ tmp = *p1; *p1 = *p2; *p2 = tmp; } After building the active page, ST then calls setpage(), another of our bios library routines from Chapter 5, to switch to the new visual page. The effect from the computer user's perspective is that of an instant update. There is a short delay while the active page is being updated before the page swap, but it's not noticeable to the user. The screen is repainted in one-sixtieth of a second, far faster than the human eye can follow, and the response to a keypress is usually completed before the key is released. The special efforts to synchronize with the vertical-retrace signal taken by the cpblk() routine are not needed when an MDA is being used. Therefore, the driver program, ST, checks for mode 7 and uses a standard block-copy routine that invokes the string-copy feature of the 8086/88 processor. A string copy of 4 KB is done very quickly. There is no visible flicker and no apparent delay when this approach is used. An option on the invocation command line for ST permits a single argument (anything will do) to be given to turn off the special copy feature when operating on an EGA or on a compatible computer that does not experience display interference. Using the command ST x, for example, will tell the program to use a standard block-copy routine instead of the special one. If this option is selected on a system with a standard CGA, visible interference will be quite noticeable, especially if you hold down a key to repeatedly write the same data to the display. The makefile for ST, st.mk, contains the instructions needed by MAKE to build and maintain the ST programs. # makefile for ScreenTest (ST) program LLIB=c:\lib\local swap_int.obj: swap_int.c cpblk.obj: cpblk.c st.obj: st.c st.exe: st.obj swap_int.obj cpblk.obj $(LLIB)\bios.lib $(LLIB)\dos.lib link $* swap_int cpblk, $*, nul, $(LLIB)\bios $(LLIB)\dos; Design Considerations Because it takes a few tenths of a second to copy data from a screen buffer to display memory, programs should not attempt to write one character at a time from the keyboard. This would result in a maximum update rate of a few characters per second. Even a very slow typist would get way ahead of such a program. A better way to handle this situation is to use a modified cpblk() function that updates only the changed character or the rectangular region in which changes have been made to the buffer. We could also use routines based on the BIOS and DOS interrupts to update the visual display page (they do so without causing interference) and use a separate routine to update the in-memory buffer so that it continues to track what is being displayed. The screen-update routines mentioned above can be fashioned from the cpblk() function. For example, a routine that copies a single line or a small range of lines, or one that copies a small rectangular region from a screen buffer to display memory, would be useful in doing selective screen updates with shorter delays. The next chapter describes screen-buffer routines that do these and other screen-buffer management tasks. Remember that the cpblk() routine described here is inherently less portable than the DOS and BIOS calls and thus should be used only when necessary for speed and effect. The symbolic constant that holds the display memory segment could be replaced by a variable. It would then be a simple matter to change the value for machines that put display memory in a nonstandard place, if a reliable method can be developed for determining the identity of the host hardware and its display memory location(s). There is no foolproof method of doing the hardware identity tests; the best we can do is look for copyright notices and company names, but finding out the exact machine type remains an elusive goal. In my programs, I make the assumption that displays are in the standard IBM-specified locations. This works on 90 percent of the machines currently in use. For the other 10 percent I produce customized versions of the programs and charge a little extra to compensate for the added effort. Chapter 12 Buffered Screen-Interface Functions The purpose of this chapter is to extend the screen interface presented in Chapter 11 by building a set of routines that let us directly access a screen buffer as a virtual screen. A Buffered Screen-Interface Package We have already seen how a memory image of a text screen can be quickly copied to physical display memory, giving the appearance of instant or at least fast screen updates. Our concern now is how to form the memory image of the desired display. We want to form the images in a way that simplifies the effort needed to manage several distinct areas of the screen. For example, a screen may be divided into viewing areas devoted to user commands, program status, and text. A provision might also be made to display help frames in a region that partially or completely overlays another area of the screen. While developing the interface presented in this chapter, I wrote a test driver program (SB_TEST) that exercises each interface function to assure correct action. The test program creates several screen regions (or windows) that can be filled, cleared, scrolled, and so on, under control of the user at the keyboard. We'll develop the functions first, then apply the driver to show off some of the capabilities of the screen interface. An element in display memory consists of two bytes: one representing a character and the other an associated attribute. This design is considerably more flexible than the design used by many low-cost terminals that use a single byte for each screen location. The latter design requires that some screen positions be "wasted" (they appear blank) because they are used to select attributes for all positions that follow until the next attribute-setting position. (The attribute positions are referred to by some as "magic cookies.") The PC design requires twice as much storage but permits attributes to be assigned on a character-by-character basis. We will form a virtual-screen buffer as a two-dimensional array of "cells," with each cell being represented as a union. This allows our programs to access each cell as individual character and attribute bytes or as a single character/attribute pair. The definitions of a cell, the virtual-screen buffer, and other components of the buffered screen interface are contained in sbuf.h. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 318 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ Buffer Management Functions One of the other components referred to above is a definition of a REGION, a structure that effectively defines a window, which in this implementation is simply a rectangular region of the screen buffer. To keep things reasonably simple, this interface keeps all screen data (characters and attributes) in the screen-buffer array, which is created by sb_init(). There are no "shadow" buffers for individual windows. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 320 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The screen buffer is allocated as global data in sb_init.c. It has type union CELL. The declaration union CELL Scrnbuf[SB_ROWS][SB_COLS]; uses the constants defined in sbuf.h to allocate 4000 bytes of storage for the screen buffer. The sb_init.c file also allocates the Sbuf structure that holds screen-buffer control information. Sbuf is of type struct BUFFER. It contains "cursor" row and column position variables, a pointer to the screen-buffer array, 2 bytes (unsigned short) of status flags, and arrays of column positions that mark the beginning and end of changes to each screen-buffer row. The range limits allow the routine that copies the screen buffer to physical-display memory to restrict the number of characters that must actually be written, thus minimizing the time needed to do display updates. The sb_show() function (in sb_show.c) is capable of using several methods to copy the screen-buffer contents to display memory. The buffer- copying method that is actually selected depends upon the user-specified access type (UPDATEMODE equal to DIRECT or BIOS access) and the type of display system that is installed in the host machine (IBM monochrome display adapter, or MDA, versus all other types). ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 321 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The sb_show() function in DIRECT update mode checks to see how many screen-buffer rows differ from those currently displayed. If there are two or fewer, they are copied individually. Any greater number of changed screen rows causes a block-copy operation (based on the cpblk() function that is described in Chapter 11) to be performed. If the DOS variable UPDATEMODE is not set, BIOS is assumed. Adding the line set updatemode=direct to one's AUTOEXEC.BAT file (or typing it on the DOS command line) causes screen updates to use the faster, but less portable, direct-access method. General Window Functions Now that we can create a screen buffer and copy it to display memory, we can proceed to prepare functions that place the data to be displayed into the buffer. The user sees nothing until the image is fully formed and copied. This allows programs to handle overlapping windows and special effects without distracting the user. By writing the least amount of data to the screen, this buffered-screen interface also speeds up the apparent performance of programs. The following functions do the work. sb_new(). As noted earlier in this chapter, screens are easier to manage if they are divided into separate regions where each region is devoted to a single purpose. The function sb_new() is used to describe a new window by allocating a window- control structure that contains row and column values for two opposite corners (upper left and lower right) of the window and a scrolling region within it, a "cursor" position, and a status flag word. Initially, the scrolling region is set to the same dimensions as the window itself. It can be set to other dimensions by calling sb_set_scrl(). Space for the control structure is allocated by a call to malloc(). NULL is returned if there is not enough memory satisfy the request. A successful request results in a pointer to the window-control structure (struct REGION *) being returned. All positioning, character and string operations, scrolling, and clearing is done with respect to this window pointer. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 324 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ sb_move(). This function is used to move the cursor to a specified location within a window. Unreasonable requests (outside window boundaries) elicit an error return code (SB_ERR). If the request is in bounds, both the window-relative and buffer-relative cursor row and column values are updated and SB_OK is returned. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 325 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ sb_fill(). A window may be filled with a given character and attribute pair by calling sb_fill(). Every cell in the specified window is set equal to the character and attribute values passed as arguments. Two variations on the theme, sb_filla() and sb_fillc(), are used to fill a window with either an attribute or a character while leaving the other component of each cell undisturbed. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 326 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ sb_putc(). This function puts a character into a window at the current cursor position and advances the cursor. Accommodation is made for wrapping at the end of a window row, and scrolling is forced when a character is written to the last position of the last row of a window. Scrolling can be disabled by clearing the SB_SCROLL bit in the window flag word (the default state). Standard format-effector control codes (newline, carriage return, linefeed, and tab) are treated normally. sb_puts(). A string may be added to a window using sb_puts(), which simply calls sb_putc() to do its work for each character in the string. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 328 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ sb_rca(). Used to read the character and attribute values from the screen-buffer cell at the current window cursor location. The functions sb_ra() and sb_rc() read the individual attribute and character values, respectively. This is a simple task because all the data is available in the screen buffer. In the case of sb_rca(), an unsigned short quantity is returned. The sb_ra() and sb_rc() functions return an unsigned char value. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 331 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ sb_scrl(). To scroll a window vertically, use sb_scrl(). This function scrolls a region within a window. The scrolling region is frequently made smaller than the full window size to allow for a boxed border and a title line and other such trimmings. A comparable effect can be obtained by defining a window within a window, but then the regions must be managed individually, adding to program overhead. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 332 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ sb_wca(). The sb_wca() function writes both a character and an attribute to a window at the current cursor position. A repetition count tells the function the extent of the write operation. The cursor position is not changed. The sb_wa() and sb_wc() functions write an attribute and a character, respectively, to a window. Note that sb_wca() combines the two unsigned char values into a single word by shifting the attribute left eight positions and bitwise ORing the result with the character value. We could achieve the same result by using separate assignment statements for the attribute and character components of the screen-buffer cell. The "write" routines are useful for such tasks as displaying horizontal portions of character graphics and changing the highlighting of text strings like those used in menu bars and pop-up selection menus. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 335 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ Box-drawing Functions A portion of the screen that demands special attention is often highlighted by drawing a box around it. Some screen designs require that particular areas of the screen be set off by box designs that signify their purposes. For example, a program that displays multiple windows might identify inactive windows by surrounding them with single-line boxes while highlighting the currently active window with a double-line box. The IBM extended-ASCII character set (codes 128 through 255), which is supported by nearly all PC-compatible computers, includes a group of line- drawing characters that are suitable for drawing boxes and other shapes with various combinations of single and double lines, full and partial blocks, and various regular dot patterns. The sb_box() function can be called to draw a box around the perimeter of a window. The box is drawn entirely within the bounds of the specified window; therefore, to avoid overwriting it, text functions should be instructed to write to an area at least one character within the box. Box corners and edges are formed from characters that match correctly at all junctions. The box types are defined in the box.h header file. /* * box.h -- header for box-drawing functions */ typedef struct box_st { short ul, ur, ll, lr; /* corners */ short tbar, bbar; /* horizontal bars */ short lbar, rbar; /* vertical bars */ } BOXTYPE; /* box types */ #define BOXASCII 0 #define BOX11 1 #define BOX22 2 #define BOX12 3 #define BOX21 4 #define BOXBLK 5 ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 338 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The Screen-Buffer Library The sbuf.lib is a library that contains the object modules for each of the screen-buffer functions just described. The library has wide applicability to screen-oriented programs. It will reside in the \lib\local subdirectory for easy access by our programs. The makefile, sbuf.mk, using the inference rules in tools.ini, keeps all objects and the library file current and puts files in the required places. If you use a different directory scheme, you should modify the makefile to accommodate the differences. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 340 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ # inference rules for SB_TEST program # (small model with function prototyping enabled) [make] .c.obj: msc -DLINIT_ARGS $*; A Test Driver Program The SB_TEST program (sources are in files sb_test.c and sb_test.h) alluded to earlier is one of several programs I used to test the SBUF library functions as they were being developed. The makefile (sb_test.mk) presumes that the screen-buffer function library is up to date. To use the test driver program, simply type its name at the DOS prompt. SB_TEST creates several windows and places some text in each. On a color display, each window sports its own color scheme. On a monochrome display, the status window displays in reverse video and the help window contains bold text; the other windows display normal text. /* * sb_test.h -- header for sb_test program */ /* dimensions of the display windows */ #define CMND_ROW 0 #define CMND_COL 0 #define CMND_HT 1 #define CMND_WID SB_COLS #define STAT_ROW CMND_HT #define STAT_COL 0 #define STAT_HT 1 #define STAT_WID SB_COLS #define TEXT_ROW (CMND_HT + STAT_HT) #define TEXT_COL 0 #define TEXT_HT (SB_ROWS - TEXT_ROW) #define TEXT_WID SB_COLS #define HELP_ROW 5 #define HELP_COL 5 #define HELP_HT 18 #define HELP_WID 70 ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 342 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ # makefile for SB_TEST driver program LLIB = c:\lib\local LINC = c:\include\local sb_test.obj: sb_test.c $(LINC)\sbuf.h sb_test.h sb_test.exe: sb_test.obj $(LLIB)\sbuf.lib $(LLIB)\bios.lib $(LLIB)\dos.lib link $*, $*, nul, $(LLIB)\sbuf $(LLIB)\bios $(LLIB)\dos; After compiling and linking the program, try using scrolling and clearing commands in the help and text windows to see how the command actions are implemented. Of course, a real program would display real text rather than the repeated sequences of letters that are produced by the test driver. The commands are described in the following table: ═══════════════════════════════════════════════════════════════════════════ COMMAND DESCRIPTION ─────────────────────────────────────────────────────────────────────────── Up and down arrows │ Scroll up and down by one row PgUp, PgDn │ Scroll up and down by one page (a windowful │ minus one row) Alt-c │ Clear the current window Alt-h │ Display a help frame Alt-s │ Fill the status window Alt-r │ Read in a text file Alt-t │ Fill the text area Esc │ Clean up the display and quit ─────────────────────────────────────────────────────────────────────────── The file-reading operation in SB_TEST demonstrates how implicit scrolling works. The scroll is called by the sb_putc() function, called either directly or indirectly by sb_puts(). When used in the BIOS update mode, the screen-buffer function library is reasonably portable. Direct mode is, of course, portable only to highly PC-compatible computers. In the next chapter, we will look at the most portable of the screen management tools: the ANSI device driver. Chapter 13 The ANSI Device Driver DOS versions 2.00 and later can be extended to use peripheral devices not planned for in the basic design of DOS. The use of installable device drivers is the basis of this extendability. ANSI.SYS, the best known of these device drivers, is supplied with DOS to handle special keyboard and screen features. This chapter focuses on ANSI.SYS and its uses. ANSI Basics The American National Standards Institute (ANSI), long before becoming involved in efforts to standardize the C programming language, proposed terminal and computer-equipment standards that have since become adopted by the computer industry. Adherence to the standards is voluntary, but terminal and computer manufacturers who choose to ignore them do so at their own peril. Nearly all terminal equipment built since the late 1970s conforms, more or less, to the ANSI standards. Conformance to the ANSI standards can be claimed as long as functions that are implemented use the specified codes to invoke them; it is not necessary to implement every function and capability described by the standards. In addition, the ANSI standards permit the implementation of private functions that are invoked by codes outside the range of those specified. Thus, a Digital Equipment Corporation VT100 terminal, which does not have insert- and delete-line capabilities, and which has many private capabilities, is considered to be an ANSI-conforming terminal. The standard that concerns us most directly with regard to our program designs is X3.64--1979. (The number following the dash represents the year in which the standard became effective or was last revised.) This standard defines a set of "additional controls" for use with the ASCII character set defined in X3.4--1977 (a revision of X3.4--1968) and the code extensions defined in X3.41--1974. The additional controls are invoked by using control-function sequences and strings, which are commonly referred to as escape sequences because the ASCII escape code (ESC, 27 decimal, 16 hex) is used as the initial character. The escape code is the signal that identifies the codes that follow as control information rather than ordinary graphic symbols. The uses of ANSI control sequences are primarily those of screen and keyboard handling, but other control tasks, such as switching to alternate character sets and responding to requests for terminal type identification ("Who are you?"), are covered. The standard accommodates change with built- in mechanisms for adding controls and with periodic review and revision as circumstances dictate. ANSI control sequences have the general form shown in Figure 13-1. The ASCII escape (shown as ESC--a single code, not three characters) is the introducer. It is followed by a string called the intermediate bit combinations, usually a mixture of numeric and alphabetic characters, and a final character that represents the command to be executed. EXAMPLE: cursor position (CUP) ESC [20;42H ▒▒▒ ▒▒▒▒▒ ▒▒ │ │ │ │ │ │ ┌───────────────────────────────────┘ │ │ │ │ └─┐ │ ┌───────────────────┘ │ FORMAT: │ │ │ │ │ │ ESC (code 27) (optional parameters) (command name) │ │ │ ┌──────┴──────┐ ┌───────┴───────┐ ┌──────┴──────┐ │ │ │ │ │ │ │ introducer │ │ intermediate │ │ final │ │ character │ │ string │ │ character │ │ │ │ combinations │ │ │ └─────────────┘ │ │ └─────────────┘ The Escape code └───────────────┘ The letter H is the introduces the [ begins the intermediate "cursor position" control sequence. string, which includes command. the row and column numbers separated by a semicolon. FIGURE 13-1 ▐ ANSI control sequence formation The string in the middle of a control sequence provides variable data that modifies the behavior of the basic command. For example, the sequence for moving the cursor forward (CUF) is ESC[#C. The sharp sign (pound sign or octothorpe, if you prefer) is a replaceable numeric parameter. If a value is given, it specifies the number of columns to move the cursor. If the value is zero or not specified, the default value of one is used. Attempts to move past the end of the line are ignored. The example given in Figure 13-1 shows how to form the sequence that moves the cursor to an absolute position on the screen. Impossible requests are simply ignored. Display Memory Figure 13-2 shows how a character and its associated attribute are stored in a PC's display memory. In a 25-line by 80-column text mode, each display-screen image requires a total of 4000 bytes of memory, half devoted to characters and half to attributes. The even- numbered byte (starting at zero) of each display-memory word holds the code for the character. The odd-numbered byte holds the attribute. 7 6 5 4 3 2 1 0 ┌─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┐ │ │ │ │ │ │ │ │ │ character byte (even) └──┬──┴─────┴─────┴─────┴─────┴─────┴─────┴─────┘ │ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ │ │ │ ASCII character code │ └──extended character flag 7 6 5 4 3 2 1 0 ┌─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┐ │ B/I │ R │ G │ B │ I │ R │ G │ B │ attribute byte (odd) └──┬──┴─────┴─────┴─────┴──┬──┴─────┴─────┴─────┘ │ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ │ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ │ │ │ │ │ background color │ foreground color │ │ │ └────────────────────foreground intensity └──blink or background intensity FIGURE 13-2 ▐ Character and attribute bytes The low seven bits (0--6) of a character byte uniquely specify one of the possible 128 character codes (0--127) defined in the ASCII character set. The most significant bit of the character byte, when set (1), indicates an extended-ASCII code, one that falls in the range 128 through 255. On an IBM PC and most compatibles, these are foreign alphabetics, block graphics, and other special characters. The attribute byte is used to control monochrome and color attributes for each character on an individual basis. As Figure 13-2 shows, bits 0 through 2 specify the foreground color, and bit 3 indicates the intensity level of the foreground. Together, these four bits determine the color value of the character, providing a range of 16 colors. On an IBM monochrome adapter, only three of the values produce unique results (0 = black, 1 = underlined, and 7 = white). All other values below 7 produce normal white, while values between 8 and 15 produce "bright" versions of their respective values in the low range. Thus, the value 15 produces a bright white foreground. The background color (or grey level) of each character cell is specified by bits 4 through 6. The background can have one of only eight colors. Bit 7 serves one of two purposes depending on whether blinking is enabled or disabled. When the blink feature is enabled, setting background values above 7 (bit 7 set) produces quite an obnoxious blink in the foreground of the associated character. Disabling the blink produces a far more pleasing result: a stable background that can be any of 16 different colors on suitable display equipment. Chapter 5 presents routines for controlling the blink feature. ANSI.SYS As mentioned previously, the ANSI.SYS file provided with DOS versions 2.00 and later is an installable device driver that provides a subset of ANSI-standard screen and keyboard control functions. When loaded into the computer's memory, the ANSI driver monitors keyboard input and screen output data streams. For screen output, when one of the escape sequences handled by the ANSI driver is received, the driver performs the associated action, such as moving the cursor or setting a display attribute. During keyboard operations, individual keys and combinations of keys can be intercepted and converted into customized character strings. Most codes are simply passed on without anything being done to them. ANSI escape sequences can be called from within our C programs or even from DOS batch files. The SetColor program described later in this chapter is an example of a C program that uses the ANSI driver to do most of the work involved in controlling the attributes of a color text display. Installing ANSI.SYS Installation of ANSI.SYS is trivial. DOS uses the file CONFIG.SYS to configure the system when it is started. If the ANSI.SYS file is in the directory c:\dos, for example, adding the line device=c:\dos\ansi.sys to CONFIG.SYS will cause DOS to load the ANSI device driver each time the system is turned on ("cold boot") or restarted using Ctrl-Alt-Del ("warm boot"). A program that depends on the ANSI device driver should test for its presence. If the ANSI driver is not loaded into memory, the program should abort and provide instructions to the user about installing it. A method of testing for the presence of the device driver is presented in the next section of this chapter. The ANSI Control Codes Figure 13-3 (on the next page) summarizes the ANSI standard control capabilities and indicates which are supported by the DOS ANSI device driver. Note that some of the supported capabilities (for example, erase in display, ED) are implemented in a simplified way, and that others (for example, set mode, SM, and reset mode, RM) are decidedly implementation-dependent, being tied intimately to the IBM PC hardware architecture. The following descriptions are intended to supplement the information presented in the documentation provided with DOS, particularly with respect to usage guidelines. The subsequent section of this chapter develops an interface package to the ANSI driver and provides practical examples of these codes in use. CONTROL SEQUENCES WITH NUMERIC PARAMETERS ╓┌─────────────┌───────────┌─────────────────────────────────────────────────╖ ANSI.SYS Mnemonic Description ANSI.SYS Mnemonic Description ─────────────────────────────────────────────────────────────────────────── No CBT Cursor Backward Tabulation No CHA Cursor Horizontal Absolute No CHT Cursor Horizontal Tabulation No CNL Cursor Next Line No CPL Cursor Preceding Line Yes CPR Cursor Position Report Yes CUB Cursor Backward Yes CUD Cursor Down Yes CUF Cursor Forward Yes CUP Cursor Position Yes CUU Cursor Up No CVT Cursor Vertical Tabulation No DA Device Attributes No DCH Delete Character No DL Delete Line No ECH Erase Character No FNT Font Selection No GSM Graphic Size Modification No GSS Graphic Size Selection ANSI.SYS Mnemonic Description No GSS Graphic Size Selection No HPA Horizontal Position Absolute No HPR Horizontal Position Relative Yes HVP Horizontal and Vertical Position No ICH Insert Character No IL Insert Line No NP Next Page No PP Preceding Page No REP Repeat No SD Scroll Down No SL Scroll Left No SPI Spacing Increment No SR Scroll Right No SU Scroll Up No TSS Thin Space Specification No VPA Vertical Position Absolute No VPR Vertical Position Relative CONTROL SEQUENCES WITH SELECTIVE PARAMETERS ╓┌─────────────┌───────────┌─────────────────────────────────────────────────╖ ANSI.SYS Mnemonic Description ───────────────────────────────────────────────────────────────────────── No CTC Cursor Tabulation Control No DAQ Define Area Qualification Yes DSR Device Status Report No EA Erase in Area Yes ED Erase in Display No EF Erase in Field Yes EL Erase in Line No JFY Justify No MC Media Copy No QUAD QUAD Yes RM Reset Mode No SEM Select Editing Extent Mode Yes SGR Set Graphic Rendition Yes SM Set Mode No TBC Tabulation Clear FIGURE 13-3 ▐ ANSI control sequences Cursor Position (CUP) ESC[#;#H Horizontal and Vertical Position (HVP) ESC[#;#f These two control sequences do the same job. They move the cursor to the position designated by the parameters: the row (the first #) and the column. Illegal requests are ignored. The upper left corner of the screen is designated row 1, column 1. Missing or zero-valued parameters default to 1; therefore, a CUP or HVP sequence with no stated parameters is a synonym for "homing" the cursor. Cursor Up (CUU) ESC[#A Cursor Down (CUD) ESC[#B Cursor Forward (CUF) ESC[#C Cursor Backward (CUB) ESC[#D Each of these control sequences moves the cursor by # positions (the default is 1) in the specified direction. Attempts to move beyond either end of a row or off the top or bottom of the screen are ignored. For example, if a request to move the cursor down exceeds the number of rows between the one containing the cursor and the bottom row of the screen, the cursor is deposited on the bottom row. No scrolling occurs. Device Status Report (DSR) ESC[6n Save Cursor Position (SCP) ESC[s Restore Cursor Position (RCP) ESC[u These three control sequences are designed to assist in cursor control. The first two determine where the cursor is located, and the third returns the cursor to a saved location. The DSR request causes the ANSI driver to place a string, in the form ESC[#;#R plus a trailing carriage return, into the keyboard buffer. The position parameters are stored as two-character representations of the numbers, so the string contains a total of nine characters. The ansi_cpr() function described in the next section can be used to retrieve the row and column data. The SCP/RCP pair of control sequences can be used to save a cursor position so that it can be restored after an intervening operation moves the cursor from the saved position. Only one position can be saved for subsequent restoration. If multiple calls are made to SCP, a call to RCP will restore the cursor position obtained by the most recent call to SCP. Erase in Display (ED) ESC[2J Erase in Line (EL) ESC[K The ED control sequence erases the entire screen by displaying blanks in the prevailing video attribute (see SGR). The cursor is deposited at the upper left corner of the screen. EL erases the characters from the cursor position to the end of the current row. The "erased" positions are set to blanks in the prevailing attribute, and the cursor is left at its current position. CAUTION Some versions of the ANSI device driver provided with MS-DOS (for example, MS-DOS 2.11 for the AT&T PC6300) erase by setting characters to blanks in the normal (white on black) attribute rather than the attribute set by SGR. Set Graphic Rendition (SGR) ESC[#; ... ;#m A graphic rendition is the visual style of displaying a graphic symbol (number, letter, punctuation mark, and so forth), which in the IBM PC context translates into the attribute associated with a character. The ANSI driver uses the SGR control sequence to set the intensity, blink status, and color attributes of characters on a color adapter. On a monochrome system, SGR can be used to set intensity, blink status, and underlining. Some IBM- compatible machines (COMPAQ and AT&T are two examples) permit grey-scale settings on monochrome monitors in response to color attribute requests. SGR can take a series of numeric parameters in a single call. The effect of a single call to SGR with multiple parameters is the same as that produced by a series of calls to SGR with one parameter per call, but the former will be faster because of reduced function-call overhead. Set Mode (SM) ESC[=#h Reset Mode (RM) ESC[=#l The mode control sequences that are supported by the ANSI driver set the IBM PC and compatible hardware-dependent video modes for the color/graphics adapter and a "wrap-at-end-of-line" mode. The driver does not support switching to a monochrome adapter from a color/graphics adapter. Both SM and RM can be used to set a video mode with the parameters 0 through 6. Setting a different video mode clears the current mode. Using SM with a parameter of 7 enables wrap; RM given the same value disables wrap. Pros and Cons of ANSI.SYS The primary reasons for using the ANSI device driver are simplified programming and portability of programs to other versions of MS-DOS and PC-DOS and to the machines that run DOS. The amount of programming effort required to do many screen operations is reduced to simple calls to ANSI control sequences. Compare the short cursor-positioning macro shown in the next section to the BIOS-interrupt-based function presented in Chapter 5; both do the same job. Unfortunately, some limitations of the ANSI driver make it unsuitable for many applications. For some purposes--full-screen text editing is a good example--it is simply too slow. In addition, ANSI.SYS implements only a very limited subset of ANSI X3.64. It has no concept of fields, protected display areas, display regions (useful for windowing), and many other important capabilities. An ANSI Interface Package In spite of its limitations, the ANSI driver has its place. It comprises a useful but limited subset of ANSI capabilities that can do a surprising amount of work. The interface to the ANSI driver described here uses mostly macros in a header file to accomplish the tasks of moving the cursor, finding its position, setting video attributes, clearing the display, and setting video modes. A few supporting C functions built on the ANSI driver take care of some higher level tasks, such as testing to see whether the driver is installed. The macros and definitions of the video attributes and modes are contained in the header file ansi.h, which resides in the \include\local directory. You should #include the file in any C program or function that will need to access the keyboard or screen through the ANSI device driver. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 358 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ ANSI color attributes follow a different sequence from the standard IBM attribute set. The ansi.h file contains definitions for the basic colors and "shift" values (offsets) for foreground and background attribute specifications. In addition, there are definitions for normal, bright, blink, reverse, and invisible attributes. The normal attribute effectively clears all other special attributes. Thus, to set the foreground to bright green, one uses the statements ANSI_SGR(ANSI_GREEN + ANSI_FOREGROUND); ANSI_SGR(ANSI_BRIGHT); which will cause all subsequent characters sent to the screen to be displayed in the requested attribute until a new specification is given. A typedef is used to create a POSITION data type that is used by some of the functions in the SetColor program to keep track of which color attribute position (foreground, background, or border) is being attended to in the processing of attribute specifications. Each position must be handled in its own special way, as we'll see shortly. In addition to the macros defined in ansi.h, our interface employs several functions. The ansi_cpr() function is used to request a device status report (ANSI_DSR) and then to read the cursor-position data stored in the keyboard buffer. The format of the response is a string of nine characters, starting with ESC and ending with a carriage return. This is called the cursor position report, hence the name ansi_cpr() for the function. The ansi_cpr() function calls getkey(), a DOS interrupt-based routine (INT 21H) that was defined in Chapter 5, to gather input from the keyboard buffer. Here is the code for ansi_cpr(): ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 361 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ Because the characters are placed in the buffer in a reasonable order, successive keyboard read calls can be used to gather and process the numeric values easily. We must read every character in the string, even though we're really interested in only four of them, so that no residue is left behind to befuddle other parts of our program's input processing. The formal parameters row and col are pointers to storage outside the function. A character representation of the tens digit of a number (row or column) is obtained by a call to getkey(). It is converted to its numeric representation by subtracting 0 (decimal 48) and then multiplying by ten (its numeric weight). The value is then added to the converted value of the next character obtained by getkey(), which is the units digit, to produce the needed number in integer format. We now have the ability to determine the cursor's position and to save it or pass the information on to other parts of our programs. But, if the ANSI device driver is not already loaded into memory, calling ansi_cpr() will cause the computer to appear to lock up. We need to be sure the driver is installed before calling functions that depend on its presence. The function ansi_tst() calls ANSI_CUP, which sets the cursor to a known location, and then calls our bios library function readcur() to read the cursor location. If the row and column positions match, the driver is probably loaded. I say "probably" because the routine will falsely claim the driver is loaded if the cursor happens to be at the test location before the ANSI_CUP call. (However, this is not likely for the test values used.) To be certain, a series of two tests at differing locations could be used. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 362 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The code for ansi_tst() aborts with an error message and instructions to the user about installing the ANSI driver. An alternative design might simply return a true/false response and let the program deal with the lack of a driver in some other way, such as switching to a mode of operation that does not depend on the ANSI driver being loaded. The file ansi.mk is the makefile to compile the separate components of the ANSI interface package. # makefile for the ANSI library LINC=c:\include\local LLIB=c:\lib\local ansi_cpr.obj: ansi_cpr.c $(LINC)\ansi.h msc $*; lib $(LLIB)\ansi -+$*; ansi_tst.obj: ansi_tst.c $(LINC)\ansi.h $(LINC)\video.h msc $*; lib $(LLIB)\ansi -+$*; The SetColor Program Now we'll do something useful with the ANSI interface. SetColor, invoked as SC to save keystrokes (in the UNIX tradition), is designed to be used with a computer that has a color display system. With minor modifications it can be used in a limited way with monochrome systems, too. Figure 13-4 is the manual page for SetColor. The program sets foreground and background attributes via ANSI control sequences. The ANSI driver provides no way to control the border attribute, so we resort to a BIOS routine, palette(), developed in Chapter 5, to do that job. The use of palette() may make the program nonportable to some nominally IBM- compatible equipment. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the figure found on page ║ ║ 364 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ FIGURE 13-4 ▐ Manual page for SetColor The following pseudocode description of SetColor reveals that the program exhibits extreme schizophrenia. On the one hand, it operates in an interactive mode when invoked as SC without arguments. The user selects attributes by pressing function keys. Screen updates immediately show the user what the combined attribute selections look like. However, when called with attribute specifications as arguments, SetColor runs in batch mode. All attributes and intensity modifiers, if any, are taken from the command line. In this mode, SetColor can be used to control screen appearance from within DOS batch files. if ANSI driver not loaded print message exit if not in color text mode print message exit if command-line argument given run in batch mode else run in interactive (menu) mode clear the screen exit The SetColor program consists of several functions, each packaged in its own file. Some of the functions have general applicability to other tasks and are, therefore, placed in local libraries. Starting at the top, the source file sc.c contains the main() function. In main(), two tests are made that determine whether the SetColor program runs to completion or quits early. The first test, ansi_tst(), checks to see that the ANSI device driver is installed. If not, the program terminates. If the driver is installed, the second function, iscolor(), finds out what video mode is in use. Rather than do anything fancy at this point, we opt to simply terminate program execution with a help message if the mode is not a standard color-text mode. The user's selection of batch or interactive operation, based upon the presence or absence of command- line arguments, is also detected here. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 367 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ If attribute arguments are given, the function parse() is called with the argument list obtained by main(). The job of parse() is to analyze each argument and form attribute or color specifications that can be processed by the low-level ANSI interface functions. If no arguments are given, the menumode() function is called. Let's first examine the batch processing functions. Batch Mode If parse() receives a single attribute specification, it checks to see whether it is one of the special attributes (normal, reverse, invisible, or blink). None of these takes an optional intensity modifier, and each can be handled easily by a single call to ANSI_SGR. If the lone argument is not one of these special attributes or if there are two or more arguments, parse() falls through to a loop that analyzes each argument in turn and creates attribute specifications in a form suitable for processing by the ANSI interface functions. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 368 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The basic problem we face is receiving color/attribute specifications as text strings and converting them to numbers. We will also need to account for the differences between the standard IBM attribute numbers and the ANSI attribute numbers described earlier. The IBM attribute numbers are defined in the header file ibmcolor.h, which resides in the \include\local directory. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 370 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The colornum() function converts text strings into these IBM color/ attribute numbers. Given the string green as an argument, for example, colornum() returns the defined value IBM_GREEN, which is the number 2. Two synonyms for bright (bold and light) are allowed, and yellow is treated as a synonym for bright brown. The following is the source code for colornum(): ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 371 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The function uses a simple sequential search through a table of string/number pairs that compares the first three letters of the string argument with the table entries. The strlwr() standard library function converts the incoming argument to lowercase before any comparisons are made. Its return type is cast to void because the pointer to a character is not used. If no matching string is found, colornum() complains by returning -1 instead of a valid color number. A color number thus produced may be passed as an argument to setattr(), which takes a position indicator and an attribute value as input. It outputs an ANSI control sequence by applying the ANSI_SGR macro to a properly converted attribute number. The process sounds more confusing than it really is. First, the code for setattr(): ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 373 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The pos argument has type POSITION (defined in the ansi.h header file), and it tells setattr() which rules to apply to the attr argument. The attribute argument contains two kinds of information lumped together: The low three bits (0--2) represent the base color or video attribute, and bit 3 indicates the intensity. An intensity modifier is treated differently when it is applied to a foreground attribute than when it is applied to a background attribute. In the foreground case, bit 3 of the intensity modifier sets the foreground intensity bit in the attribute byte (bit 3). In the background case, it sets the blink bit (bit 7). If blinking is enabled (the default), setting the blink bit causes the foreground to blink and does not change the background intensity, resulting in a useful range of eight background colors. If blinking is disabled, setting the blink bit causes the background intensity to be bright. The full range of 16 background colors can be obtained with blinking disabled. The setattr() function calls ANSI_SGR once if attr is for normal intensity or twice for high intensity. A table of foreground and background attribute values in the array ibm2ansi[] contains the conversions from IBM attributes--represented by the index into the array--to the ANSI values needed by ANSI_SGR. Thus, the expression ibm2ansi[IBM_BLUE], where IBM_BLUE is defined in ibmcolor.h as the number 1, yields the value represented by ANSI_BLUE, which is defined in ansi.h as the number 4. The border, on display systems that support it, can be set to any of 16 colors by using palette(). There is no need to separate the intensity information from the rest of the attribute when setting the border because palette() is a BIOS-based function and uses the IBM attribute values directly. That explains batch-mode processing. The other processing path that can be taken from main() is interactive mode, which is handled by menumode(). The menumode() function calls upon palette(), setattr(), getkey(), and a new function, sc_cmds(), to do the bulk of the work. Interactive Mode In interactive mode, attributes are selected by pressing function keys. F1 decrements the foreground color and F2 increments it. The color values wrap around at the boundaries; therefore, a request to increment foreground = 15 (white) produces foreground = 0 (black). Similarly, the F3/F4 pair of function keys are used to select the background attribute, and the F5/F6 pair cycle through border attributes. The mainmenu() function returns control to DOS when the Return key is pressed, leaving the screen cleared to the most recently selected attribute combination. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 375 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ Because the color/attribute specifications are presented in interactive mode as numbers rather than as text strings, setattr() can process them directly. The process of updating the screen after each set of calls to setattr() means that the list of commands and the current status information must be rewritten following each keypress that affects the foreground or background color. This is done by the function sc_cmds(), which contains a static array that converts IBM color numbers into text strings suitable for humans. All cursor positioning is done via the ANSI_CUP macro. Text strings are written to the display by the standard library function fputs(), which is directed to send its output to stdout. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 377 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The file sc.mk is the makefile for SetColor. It collects several of the interface functions into a special-purpose library, color.lib. This is done to minimize the number of items that must be specified on the dependency and link lines that create SC.EXE and keep it up-to-date. A linker-response file could be used to achieve the same result. To rebuild the SetColor program after any changes are made to its source files or libraries, type make sc.mk ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 378 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ Using SetColor Aside from being a good demonstration of the ANSI device-driver interface, SetColor is a useful program. I use it most frequently in batch files to restore the screen to match my peculiar tastes after some other program has made a mess of things. Most programs, especially those that do full-screen operations, have built-in default settings for video attributes. These programs have no idea what attributes were in use before they were run; therefore, when they exit, they either leave the attributes as they are when the program terminates or set them to white on black. It would be better to have the colors set to the user's preferences, if possible. This can be achieved in a couple of ways. The first way uses a DOS batch file to intercept the call to a program. The batch file calls the real program and then calls SetColor to make things right again. For example, assume the program in BADPROG.EXE does bad things to the screen when it exits. A batch file called BADPROG.BAT with the lines badprog.exe sc white blue blue will clear the screen and set the foreground to white on a field of blue when the program returns to DOS. This can be generalized further by the use of DOS environment variables. If environment variables having the names FGND, BKGND, and BORDER are defined, the batch file can access the values and control the SetColor program automatically. DOS variable values are obtained in batch files by surrounding each variable name with percent signs. The revised batch file looks like this: badprog.exe sc %fgnd% %bkgnd% %border% Of course, SetColor may be called from the DOS command line with literal attribute specifications. I sometimes change the attributes just to minimize eyestrain during long programming and writing sessions. It's remarkable what a good effect a simple change in screen colors can have (unless it's to something like magenta on red!). A User-Attribute Function Here's a way for programmers to be kind to those who will be using their programs. The function userattr() that follows can be used in programs to restore the user's attribute preferences just before the return to DOS. It gets values directly from the DOS environment, just as the batch file in the previous section does. If no attribute variables are defined, userattr() uses some reasonable defaults as parameters. The userattr() function calls on colornum() and setattr() and uses the standard library functions getenv() and strtok() to look for user preferences and parse them into recognizable values. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 380 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The processing of the strings by strtok() is necessary because the attribute specifications may contain an intensity modifier. The strtok() function returns a pointer to a null-terminated string token taken from its first string argument; if no tokens are found, it returns NULL. Acceptable token separators are spaces and tabs, in any combination. Subsequent calls to strtok() use NULL as the first argument to request further searching in the string given in argument one of the first call. If the first call to strtok() retrieves an intensity modifier, a second call is made to strtok() on the same string to get the second token, which should be a valid attribute specifier. Error-checking code prevents bad attribute names from causing problems. The next time someone tells you the ANSI.SYS device driver is a worthless piece of software, you can show them how useful it really is! As a fitting end to this development session, echo ESC[2J (look it up). Chapter 14 Viewing Files The next program to be added to our kit of tools is a file viewer. ViewFile, called VF by its close friends and associates, is such a tool. The design for VF has two objectives: to obtain a convenient window into a file that permits us to look at the file without harming it and to experiment with some programming techniques that we can apply to other tasks. We will apply the linked-list techniques to the management of an in- memory text buffer. In addition, we will use the standard library function strncmp() to implement a simple but fast search capability. Some trade-offs made in VF's design are noteworthy. First, we sacrifice loading speed to obtain very quick response to user commands. By using an internal buffer, instead of buffering to disk, we provide speedy response to positioning requests but limit files to a size determined by the available memory of the host machine. Fortunately, most PCs these days have lots of memory. Second, VF uses some of the BIOS routines described in Chapter 5 to handle display interactions. It does not use the buffered screen interface described in Chapters 11 and 12. Even so, the display updates are tolerably quick, taking about a second or less for most operations on a standard PC for a typical file. ViewFile (VF) Features The features of ViewFile are summarized in the manual page below (Figure 14-1). ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the figure found on page ║ ║ 384 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ FIGURE 14-1 ▐ Manual page for ViewFile In addition to offering vertical scrolling by screen pages, VF provides convenient horizontal scrolling as a way of dealing with long lines. VF accepts lines up to MAXLINE characters (defined as 256 in our std.h header file) including the null-byte terminator. You can make this value larger if you wish. The horizontal scrolling feature lets you move right and left, 20 columns at a time. The horizontal offset is maintained when vertical movements are made. If a list of files is presented to VF, the program will view the files sequentially. Pressing the Escape key tells VF to read the next file in the list, if any. To quit without viewing any remaining files in the list, type Q instead. DOS wildcards may be used to specify ambiguous file names. Therefore, the command vf \src\*.h forms a list consisting of all header files in the \src directory on the current disk drive. VF then reads in the first matching file and displays the first screen page of its contents. The forward and reverse search feature looks through each line in the buffer for a literal string. VF searches around the end of the buffer, stopping at the first line that contains a match, or returning to the current line if no match is found. Searches in either direction may be repeated by pressing a carriage return in response to the "Search for:" prompt. VF has a built-in help "frame." When a user types a question mark, Alt-h, or H, VF overlays the help frame on the text-display area. The next keypress restores the covered text. Although it is only a brief memory- jogger, the help frame contains all the information needed to use VF successfully. VF should be compiled using the compact memory model so that it can handle large files. Compact model programs are distinguished by small code space (less than 64 KB) and large data space (whatever available memory permits). Files that exceed the capacity of VF produce the message "File too big to load." To use the compact memory model, you will have to create compact-model versions of the bios, dos, and util libraries by recompiling all functions with the -AC option. It is probably best to follow the pattern established by Microsoft of having separate library files for each version of a given library. Thus, for example, we might have the files bios.lib, cbios.lib, lbios.lib, and so on. The linker gets clues from the object files, so it will use the correct versions of the standard libraries. The makefile, vf.mk, contains the instructions required by MAKE. The library of object modules used to construct VF is maintained by vf.mk, which enables us to bypass the command-line length limitation imposed by DOS. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 386 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The initialization file tools.ini in the VF directory instructs MAKE to verify the number and types of function arguments and to use the compact memory model. Renaming or deleting this file causes the default small-model tools.ini file to be read for inference rules. # inference rules for VF program make # enable argument checking and compact memory model [make] .c.obj: msc -DLINT_ARGS -AC $*; Implementation Details VF is a modest-sized program. Some of its general-purpose functions are available to other programs. VF uses an in-memory text buffer. The decision to use an in-memory buffer has a profound impact on how a few of the functions are designed, but virtually no impact on the rest. We should try to keep the number of functions that actually know how the text is stored to a minimum; this permits us to apply them to a wider range of problems. The functions in the message module message.c, for example, don't know anything about the text buffer. Therefore, these message functions can be used unchanged in any program that uses the BIOS video routines. The functions in vf.c are also ignorant of the buffer mechanism. The main() function does the customary work of preserving the user's preferences for display type, video attributes, and cursor type. It also aborts the program if the operating environment is a DOS version earlier than 2.00, because VF is designed to accept pathnames in file specifications. The main() function also clears the screen and sets up the basic display appearance for the VF session. All program and status information, user input, and feedback messages are confined to the top two lines of the screen. The remaining 23 lines are used to display text and optional file- relative line numbers. When help is requested, the help frame is temporarily overlaid on a rectangular portion of the text display area. Because the cursor is turned off by VF (except during user input operations), it is necessary to restore its shape when the program ends. The clean() function in vf.c is called when the program terminates normally or when some condition (out of memory, for example) causes an abnormal termination. The user's original video attribute selection is restored by clean(), and the cursor is then sent to the home position. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 388 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ A set of manifest constants that controls placement of visual elements of the VF display, search direction, and the data structure that defines the text buffer are contained in vf.h. The buffer data structure and its application will be described in detail later. The constants determine where the program name and messages to the user appear, which screen line is the "header" row, and how many screen rows of text display and scrolling overlap are to be used. To simplify VF a bit, we do not add automatic configuration to the program. The information and samples in Chapters 7 and 9 give detailed information about configuring programs. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 391 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ For each file named on the command line (either literally or ambiguously), main() calls vf_cmd(), the ViewFile command module. The vf_cmd.c file, which contains the source for vf_cmd() and for the auxiliary function prtshift(), is a large file but it does only a few jobs--all related to controlling and accessing the text buffer. Chief among these jobs is setting up the text buffer for the file that is about to be read. Another major job is handled by the big switch statement within the while loop in vf_cmd(), which accepts keypresses as commands. Simple positioning commands are handled directly by vf_cmd(). Commands that require user input are handled by separate functions. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 392 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ Within vf_cmd() there are several calls on putstr(). This is a BIOS- based function that displays a string in the prevailing video attribute on a specified screen page. It advances the cursor by the number of characters written. (We could also use the BIOS writetty() function to help us with this task, but writetty() disturbs the video attribute, setting it to the default, which may not be what we want.) ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 399 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ As noted earlier, the vf.h header file contains the definition of the buffer node structure. In addition to having forward and backward pointers to other nodes, each node contains a pointer to a character string, a file- relative line number, and a "flag" word. The flag word is not used in this implementation of VF, but it could be used to mark lines for highlighting. The text buffer management functions are in vf.list.c: ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 399 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The text buffer used by VF consists of three parts: a group of "control nodes" that form a doubly linked list, pointers to the buffer "head" and the "current" position, and independent character strings for each line in the file being viewed. The node pointed to by head is a dummy node that is used to ease the work necessary to set up and maintain the list. Figure 14-2 depicts the text buffer. Note that the control nodes are in a circular list, which makes searching across the buffer boundaries easy. It takes the same amount of time to move backward in the buffer as it does to move forward, because of the use of a doubly linked list. Most other text buffer designs would exact a rather stiff time penalty for scrolling backward in a file. Figure 14-3 shows another aspect of the text buffer-allocation scheme used by VF. An initial pool of 256 "free" nodes is allocated by a call to vf_alloc(); the free nodes are controlled by the symbolic constant N_NODES. The list-header node is established by vf_mklst(). Both vf_mklst() and vf_alloc() call the library function malloc() to obtain needed storage. control nodes │ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒ text string buffers ┌─head ┌────────┐ │ │ │ ┌───┐ │ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ │┌──┐ │ │ ┌─┬┼─┬─────┬──┐ └│■─┼──┼─┼─│■ │■ │ │■ │ └──┘ │ │ └┼─┴─┴─────┴──┘ ┌──┐ │ │ ┌─┬┼─┬─────┬──┐ ┌───────────────────────────────────────┐ ┌┤■─┼──┼─┼─│■ │■ │ │■─┼──│ │ │└──┘ │ │ └┼─┴─┴─────┴──┘ └───────────────────────────────────────┘ │ │ │ ┌─┬┼─┬─────┬──┐ ┌──────────────────────────────┐ └─cur- │ │ │■ │■ │ │■─┼──│ │ rent │ │ └┼─┴─┴─────┴──┘ └──────────────────────────────┘ │ │ ┌─┬┼─┬─────┬──┐ ┌──────────────────────────────────────────┐ │ │ │■ │■ │ │■─┼──│ │ │ │ └┼─┴─┴─────┴──┘ └──────────────────────────────────────────┘ | | | | │ │ ┌─┬┼─┬─────┬──┐ ┌────────────────────────────┐ │ │ │■ │■ │ │■─┼──│ │ │ │ └┼─┴─┴─────┴──┘ └────────────────────────────┘ │ └───┘ │ └────────┘ FIGURE 14-2 ▐ Text buffer management ┌────────┐ │ ┌───┐ │ ┌──┐ │ │ ┌─┬┼─┬────────┐ head│■─┼─┼─┼─│■ │■ │ │ Inserting a node into the list: └──┘ │ │ └┼─┴─┴────────┘ │ │ ┌─┬┼─┬────────┐ if (insertion will exhaust the │ │ │■ │■ │ │ freelist) │ │ └┼─┴─┴────────┘ extract first node from the freelist │ │ ┌─┬┼─┬────────┐ insert the node after the "current" node │ │ │■ │■ │ │ return a pointer to the next free node │ │ └┼─┴─┴────────┘ │ │ ┌─┬┼─┬────────┐ │ │ │■ │■ │ │ │ │ └┼─┴─┴────────┘ ┌──┐ │ │ ┌─┬┼─┬────────┐ current│■─┼─┼─┼─│■ │■ │ │ └──┘ │ │ └┼─┴─┴────────┘ │ └───┘ │ └────────┘ ───────────────┐ │ ┌──┐ ┌──┬──┬────────┐ │ freelist│■─┼─────│■ │■ │ │ ────┘ └──┘ └┼─┴──┴────────┘ ┌─┬──┬────────┐ │■ │■ │ │ └┼─┴──┴────────┘ ┌─┬──┬────────┐ │■ │■ │ │ └┼─┴──┴────────┘ ┌─┬──┬────────┐ │■ │■ │ │ └──┴──┴────────┘ | | ┌─┬──┬────────┐ │■ │■ │ │ └──┴──┴────────┘ FIGURE 14-3 ▐ Buffer-allocation scheme The header-node pointers are both initially set to point to the header node itself. This constitutes the empty list. The freelist pointer points to the chained free nodes. Only the "next" pointers are used for chaining, and the last free node contains a NULL next pointer. Each line of text is effectively added to the buffer by the function vf_ins(), which inserts a free node into the list after the position of the current node. When the supply of free nodes is about to be exhausted, another block of nodes is allocated and added to the chain. This process continues as long as there are more lines to read from the file and there is enough memory to satisfy the allocation requests. Looking at vf_cmd.c, we see that after a new node has been inserted into the list by vf_ins(), there is still more work to be done. The Microsoft C standard library function strdup() is used to duplicate the text of the most recently read line from the file. This function also calls malloc() to obtain an array of characters that is large enough to hold a copy of the received string, including the terminating null byte. COMMENT Since strdup() is not a UNIX System V library function, many C compilers may not have it or an equivalent function in their run-time support libraries. You can easily mimic the function using malloc(), strlen(), and strcpy(): #include <stdio.h> #include <malloc.h> #include <string.h> char * strdup(str) char *str; { char *buf; buf = malloc(strlen(str) + 1); return (buf == NULL ? buf : strcpy(buf, str)); } We are careful to check for error returns that let us know if memory is exhausted. VF simply cleans up and quits with an error message if it runs out of memory. The function vf_del() takes a node out of the list and puts it back on the freelist. We call vf_del(), and free(), a standard library function, when the command loop is terminated by a "next file" (Escape) command. This frees the memory used by the current file, leaving the largest possible amount for the next file in the list. If we do not free the memory, we might eventually receive a "File too big to load" error message. After any command that affects the current buffer position, vf_dspy() is called to update the text display area of the screen. The version of vf_dspy() presented here uses the bios library functions that we constructed in Chapter 5 to position the cursor, control display attributes, and display text and optional line numbers. I elected to use global variables only for the video subsystem based on the BIOS interface. The Boolean variable numbers defaults to FALSE but may be set to TRUE for the duration of a VF session by using the command-line option -n. The numbers variable controls the displaying of line numbers. The initial setting of numbers is passed as an argument from main(), relayed through vf_cmd(), to vf_dspy(). The user may toggle line-numbering on and off while viewing a given file, but the state of line-numbering goes back to the initial setting when the next file from the list is brought into the viewing buffer. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 405 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The vf_dspy() function updates the text-display area by calling putfld(), which outputs a string of characters to a field starting at the current cursor position. The putfld() function uses a compression technique that is made possible by BIOS. All sequences of repeated characters are output by a single call to writec(). This technique reduces the time needed to update a screen that contains, for example, the large amounts of white space found in C and Pascal source files. Assembly-language source listings, on the other hand, usually do not benefit from this compression technique because they contain long lines and fewer repeated character sequences. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 407 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ This function becomes part of the bios library described in Chapter 5. It can be used by any program that uses BIOS to access the PC screen. We have to watch out for the boundary conditions imposed by physical realities. When there are not enough lines left in the buffer to fill the screen, vf_dspy() must be careful not to leave residue from previous displays. After displaying the last line of the text buffer, vf_dspy() clears each remaining screen line and deposits a tilde in the leftmost column to show that the line is an unused screen line, as opposed to an empty buffer line. Two utility functions that are specific to VF reside in vf_util.c. The first is gotoln(), which implements the absolute go-to-line feature. This function prompts the user for a line number. If the number is within the range of lines in the buffer, the current position is updated and the line sought by the user is brought to the top of the text display area. The second function is called showhelp(). To assist the user with a brief memory-jogger of command names and actions, showhelp() displays the essence of the manual page at the top of the text display area. When the user has finished reading the help frame, a keypress restores the screen to its former condition by rewriting all of the text lines. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 408 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The task of gathering the user's input for the gotoln() function falls to getstr(), a function that is constructed from several of the dos and bios library functions presented in Chapter 5. The getstr() function takes buffer and width parameters as arguments. It echoes keystrokes as it receives them and interprets a few keys as commands rather than as input. The user cancels input by pressing the Escape key, and signals the end of input with a carriage return. Errors may be corrected by pressing Ctrl-H (backspace). All input is in the form of character strings. If a program requires numeric input, such as a line number, it must convert the string to numeric form before using it. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 411 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ Notice that getstr() is actually a simplified version of the getreply() function that we used in Chapter 6. We don't need a sliding window or other fancy gimmicks, so we took out all the superfluous windowing and editing features, made the prompting external, and eliminated the response stack. What's left is a simple but effective function that collects a string from the keyboard. Two boundary conditions are addressed: First, we don't allow the user to backspace beyond the left column of the response field, and second, we return the response immediately if the user types past the right column of the response field. You may prefer to modify the latter condition to require an explicit carriage return before returning the response. Additional assistance is provided to the user via the message line on the right half of the top screen line. The simple message-line manager consists of three functions contained in message.c. The function initmsg() establishes the message display area by filling in the values called for by the MESSAGE data structure defined in the message.h header file. The message line can be placed anywhere on the screen by changing the values presented to initmsg(). The showmsg() function displays a message, and clrmsg() restores the message area to its pristine state. A flag in the message structure is set when a message is displayed and is reset when the message area is cleared. If a call is made to clrmsg() and the flag is not set, no action is taken. /* * message.h -- header for message-line manager */ typedef struct msg_st { int m_row; int m_col; int m_wid; int m_pg; int m_flag; unsigned char m_attr; } MESSAGE; ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 413 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ The message-line manager functions are based on bios library routines. They can be generalized to use either standard library routines or the screen-buffer routines described in Chapters 11 and 12, which permit their use in programs that do not use the BIOS interface. A simple but useful search feature is implemented by the functions in vf_srch.c. The getsstr() function prompts for a search string and reads it using getstr(). The string must be literal in this implementation. The string is presented to search(), which tries to find a line in the specified search direction that contains a match for the search string. Searching starts on the line following the current line (or the preceding line for a reverse search) and continues until a match is found or until search() returns to the current line. The search is circular because of the way the buffer is implemented. ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 415 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ /* nlerase -- replace the first newline in a string * with a null character */ char *nlerase(s) char *s; { register char *cp; cp = s; while (*cp != '\n' && *cp != '\0') ++cp; *cp = '\0'; return (s); } ╔══════════════════════════════════════════╗ ║ ║ ║ Click to view the listing found on page ║ ║ 417 in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ Figure 14-4 shows VF in operation. ViewFile/1.0 H=Help Q=Quit Esc=Next File: vf.c (126 lines) /* * vf -- view a file using a full-screen window onto * ┌──────────────────────────────────────────────────────────┐ */ │ PgUp (U) Scroll up the file one screen page │ │ PgDn (D) Scroll down the file one screen page │ #include│ Up arrow (-) Scroll up in the file one line │ #include│ Down arrow (+) Scroll down in the file one line │ #include│ Right arrow (>) Scroll right by 20 columns │ #include│ Left arrow (<) Scroll left by 20 columns │ #include│ Home (B) Go to beginning of file buffer │ #include│ End (E) Go to end of file buffer │ │ Alt-g (G) Go to a specified line in the buffer │ extern i│ Alt-h (H or ?) Display this help frame │ int Star│ Alt-n (N) Toggle line-numbering feature │ unsigned│ \ (R) Reverse search for a literal text string │ unsigned│ / (S) Search forward for a literal text string │ unsigned│ Esc Next file from list (quits if none) │ │ Alt-q (Q) Quit │ main(arg│ -------------------------------------------------------- │ int argc│ << Press a key to continue >> │ char **a└──────────────────────────────────────────────────────────┘ { int ch; FIGURE 14-4 ▐ The ViewFile program with the help frame displayed Considerations and Alternatives If you need to view very large files, the use of external storage is the best alternative. A theoretical maximum file size of 32 megabytes can be achieved under current versions of DOS, but some of that space will probably be needed to manage the data storage. With external storage, a file would be loaded from disk faster than by the current VF because only a small piece of the file need be in memory at one time. However, it's likely that there would be a significant increase in the time needed to access a particular line in the file because the disk must be accessed and read for each new portion of the file that is to be displayed. An area of the VF design that could use some enhancement is the search feature. Although literal-string searches satisfy most positioning requirements, a regular-expression capability can be extremely handy. Regular expressions are, in essence, text formulas that can be used to form patterns rather than fixed strings. Another option to consider is an incremental search. As the user types characters, the program accumulates them in the search pattern and moves immediately to a string in the text, if there is one, that matches the accumulated search string. The advantage of the incremental search is that the user need only type enough characters to get the match. You would need to provide an "escape" command to terminate the search when the desired string is found. The implementation of VF presented in this chapter wraps around the buffer boundaries. In most cases this action is appropriate, but not always. It may be useful to have a "no wrap" option that would terminate the search at the end (or beginning) of the buffer to avoid unwanted repositioning. SECTION V Appendixes Appendix A Microsoft C Compiler, Version 4.00 The current version of the Microsoft C Compiler at the time of this writing is version 4.00. The compiler is noted for producing very fast and compact executable program files. It trades compile time for a high degree of optimization and produces object code that is arguably in the same league as that produced by expert assembly-language programmers. "Hand tuning" to improve performance is virtually unnecessary. Technical Highlights The following material presents a general overview of the Microsoft C Compiler, version 4.00. The compiler system encompasses a three-pass compiler, extensive runtime library support, and a set of development tools. See Chapter 1 for additional information about the compiler, the impact of the proposed ANSI standard for C, and information about DOS and C compiler programs that assist programmers in the development of programs. Two compiler drivers are available with the Microsoft C Compiler. The MSC driver executes the preprocessor and compiler passes. The CL driver is similar to the CC driver on XENIX and UNIX, which compiles and links programs automatically. Either driver can take advantage of a variety of compile-time options. Program Size The Microsoft C Compiler now provides five distinct memory models-- small, medium, compact, large, and huge--plus extensions to produce mixed models. The small model generates tight, efficient code for programs with up to 64 KB of code and up to 64 KB of data. The medium model supports programs with up to 1 MB of code but only 64 KB of data. The compact model handles programs with up to 64 KB of code and up to 1 MB of data. The large model extends program space to 1 MB of code with 1 MB of data. The huge model is similar to the large model, but allows individual arrays to be larger than 64 KB. Mixed memory models are made possible through the use of near, far, and huge pointers. These pointers change the addressing conventions for one or more elements without changing them for the program as a whole. Overlays The Microsoft C Compiler single-level overlay linker allows memory space to be shared in turn by several program modules. Overlays may be called from the "root" program or from another overlay and are automatically loaded when needed. Multiple Math Libraries The Microsoft C Compiler offers several options for floating-point operations. If an 8087/80287 math coprocessor is available, the smallest and fastest floating-point library can be used. And even though a math coprocessor may not be present, identical math results can still be obtained from an emulator. This versatility gives programs the same high degree of precision whether or not a math coprocessor is available. For maximum speed, the emulator routines automatically use the math coprocessor if it is installed. When full 80-bit precision and consistency with the 8087/80287 math coprocessor are not required, the alternate math package can be selected. Supporting a compatible interface for single- and double-precision IEEE numbers, this math library is optimized for speed. Network File Sharing Under MS-DOS version 3.1 or higher with Microsoft Networks version 1.0, or under IBM PC Network, the Microsoft C Compiler supports multi-user network access with both file and record locking. Direct Interlanguage Calls Routines written in the Microsoft C Compiler (version 3.00 or higher), Microsoft FORTRAN (version 3.30 or higher), Microsoft Pascal (version 3.30 or higher), or Microsoft Macro Assembler can be linked together. So you can share the investment you've made in developing libraries in a different language. This interlanguage calling lets you use the best features of each language, or upgrade to a new language while retaining libraries written in the old one. Selected routines can be recoded as needed. Library Manager Entire program-development libraries can be built in any mix of C, Pascal, FORTRAN, and assembly language by using the library manager that's included with the Microsoft C Compiler. Once a library is constructed, the library subroutines can be called directly from your C program. Subroutine calls are resolved when the finished program is linked. Utility Programs The Microsoft C Compiler includes several utility programs; two are used to increase the efficiency of .EXE files: EXEPACK removes null characters from .EXE files and optimizes the relocation table. This results in smaller files on disk and faster loading at execution time. EXEMOD allows fine-tuning of file header information usually set by default, such as stack size. Language Details This is a summary of data types, keywords, compiler options, preprocessor directives, and other important aspects of the Microsoft C Compiler. Implementation-dependent items are grouped separately. Items that are new in version 4.00 are flagged, as are library routines that are implemented as macros. ═══════════════════════════════════════════════════════════════════════════ KEYWORDS ─────────────────────────────────────────────────────────────────────────── auto else long switch break enum register typedef case extern return union char float short unsigned continue for signed void default goto sizeof while do if static double int struct The keywords const and volatile are reserved for future use. ═══════════════════════════════════════════════════════════════════════════ IMPLEMENTATION-DEPENDENT KEYWORDS ___________________________________________________________________________ cdecl fortran near pascal far huge ═══════════════════════════════════════════════════════════════════════════ FUNDAMENTAL TYPES ─────────────────────────────────────────────────────────────────────────── char int signed void double long unsigned float short Enumeration types are also included. ═══════════════════════════════════════════════════════════════════════════ TYPE SPECIFIERS ─────────────────────────────────────────────────────────────────────────── char int struct unsigned double long typedef name void enum short union float signed ═══════════════════════════════════════════════════════════════════════════ DATA FORMATS ─────────────────────────────────────────────────────────────────────────── The standard C data types are implemented as follows: Type Length in Bytes Range ─────────────────────────────────────────────────────────────────────────── char 1 -128 to 127 double 8 10**±306 float 4 10**±38 int 2 -32768 to 32767 long 4 -2**31 to 2**31-1 short 2 -32768 to 32767 unsigned char 1 0 to 255 unsigned int 2 0 to 65535 unsigned long 4 0 to 2**32-1 unsigned short 2 0 to 65535 ═══════════════════════════════════════════════════════════════════════════ POINTER SIZES ─────────────────────────────────────────────────────────────────────────── Bytes Address Arithmetic ─────────────────────────────────────────────────────────────────────────── Near Pointer 2 16 bits (offset) Far Pointer 4 16 bits (offset) Huge Pointer 4 32 bits (segment offset) ═══════════════════════════════════════════════════════════════════════════ PREPROCESSOR DIRECTIVES ─────────────────────────────────────────────────────────────────────────── #define #endif #ifndef #pragma #elif #if #include #undef #else #ifdef #line ═══════════════════════════════════════════════════════════════════════════ STORAGE CLASSES ─────────────────────────────────────────────────────────────────────────── auto extern register static ═══════════════════════════════════════════════════════════════════════════ EXTENDED TYPE MODIFIERS ─────────────────────────────────────────────────────────────────────────── cdecl fortran near pascal far huge ═══════════════════════════════════════════════════════════════════════════ COMPILER STATEMENTS ─────────────────────────────────────────────────────────────────────────── break default for return case do goto switch continue else if while ═══════════════════════════════════════════════════════════════════════════ COMPILER OPTIONS ─────────────────────────────────────────────────────────────────────────── The Microsoft C Compiler supports a large number of compile-time options. Here is a partial list. /A string Sets program memory model /Dname [=text] Defines preprocessor macro /Fx Selects listing options for source, object, assembly, and testing /FPstring Selects floating-point options /Gx Specifies options for code generation; generates 8086/8088, 80186/80188, or 80286 instructions; disables stack checking /I path Adds to #include search path /Ox Controls optimization for speed and size /Wn Sets warning message level /Zx Selects language options for disabling extensions, emitting debugging information, and structure packing ═══════════════════════════════════════════════════════════════════════════ LIBRARY FUNCTIONS ─────────────────────────────────────────────────────────────────────────── The Microsoft C Compiler contains an extensive set of UNIX System V compatible library routines. This set includes many of the functions included in the emerging ANSI standard. Functions new in this version are designated by an exclamation point (!) before the function name. Functions implemented as Macros are designated by a double exclamation point (). Buffer Manipulation ─────────────────────────────────────────────────────────────────────────── memccpy memcmp !memicmp movedata memchr memcpy memset Character Classification and Conversion ─────────────────────────────────────────────────────────────────────────── isalnum isgraph isupper toupper isalpha islower isxdigit _toupper isascii isprint toascii iscntrl ispunct tolower isdigit isspace _tolower Data Conversion ─────────────────────────────────────────────────────────────────────────── atof ecvt itoa !strtol atoi fcvt ltoa ultoa atol gcvt !strtod Directory Control ─────────────────────────────────────────────────────────────────────────── chdir getcwd mkdir rmdir File Handling ─────────────────────────────────────────────────────────────────────────── access fstat remove unmask chmod isatty rename unlink chsize locking setmode filelength mktemp stat I/O Stream Routines ─────────────────────────────────────────────────────────────────────────── clearerr fopen getchar !setvbuf fclose fprintf gets sprintf fcloseall fputc getw sscanf fdopen fputchar printf !tempnam feof fputs putc !tmpfile ferror fread putchar !tmpnam fflush freopen puts ungetc fgetc fscanf putw !vfprintf fgetchar fseek rewind !vprintf fgets ftell !rmtmp !vsprintf fileno fwrite scanf flushall getc setbuf Low-Level Routines ─────────────────────────────────────────────────────────────────────────── close dup2 open tell creat eof read write dup lseek sopen Console and Port I/O Routines ─────────────────────────────────────────────────────────────────────────── cgets cscanf inp putch cprintf getch kbhit ungetch cputs getche outp Math (Floating Point) ─────────────────────────────────────────────────────────────────────────── acos !_control87 frexp sin asin cos hypot sinh atan cosh ldexp sqrt atan2 exp log !_status87 bessel fabs log10 tan cabs floor matherr tanh ceil fmod modf !_clear87 !_fpreset pow Memory Allocation ─────────────────────────────────────────────────────────────────────────── !alloca !_fmsize malloc !_nmsize calloc free !_memavl realloc !_expand !_freect !_msize sbrk !_ffree !halloc !_nfree !stackavail !_fmalloc !hfree !_nmalloc MS-DOS Interface ─────────────────────────────────────────────────────────────────────────── bdos int86 intdos segread dosexterr int86x intdosx Process Control ─────────────────────────────────────────────────────────────────────────── abort execve !onexit spawnv execl execvp signal spawnve execle !execvpe spawnl spawnvp execlp exit spawnle !spawnvpe !execlpe _exit spawnlp system execv getpid !spawnlpe Searching and Sorting ─────────────────────────────────────────────────────────────────────────── bsearch !lfind !lsearch qsort String Manipulation ─────────────────────────────────────────────────────────────────────────── strcat strdup strncmp strrev strchr !strerror strncpy strset strcmp !stricmp !strnicmp strspn strcmpi strlen strnset !strstr strcpy strlwr strpbrk strtok strcspn strncat strrchr strupr Time ─────────────────────────────────────────────────────────────────────────── asctime ftime localtime tzset ctime gmtime time utime !difftime Miscellaneous ─────────────────────────────────────────────────────────────────────────── abs getenv perror setjmp assert labs putenv srand FP_OFF longjmp rand swab FP_SEG ─────────────────────────────────────────────────────────────────────────── Appendix B Other C Compilers There are many C compilers for DOS in today's PC marketplace. If you are in the process of choosing one, I recommend that you read all you can before making a purchase. Price is not the only consideration. Look for features that will make your job easier: a complete standard library of functions and macros; DOS and BIOS interface functions; program development tools; and product support. If you are going to produce programs commercially, look for a compiler that produces compact, fast-running programs. Ultimately, it is the user of your programs who will benefit from your choice of a quality product. Using a compiler that compiles faster than others but produces sloppy object code is probably not in your best long-term interest if you intend to make a living by writing programs. It may save you a little development time, but it will penalize your program's users every time they run the program. Interactive tools such as C interpreters are now available and provide a comfortable testing and experimenting environment that helps a programmer to quickly examine a variety of problem-solving approaches. You may want to use a C interpreter for early development work. The current crop of C interpreters are, however, less appropriate for large programming projects, particularly projects that involve more than one programmer. Analyze your needs carefully before selecting a C compiler or interpreter. Here are some magazine review articles that may help you decide which C compiler is right for you: "The State of C," William Hunt, PC Tech Journal, January 1986. "Software Reviews (Department)--21 C Compilers," S. Leibson, J. Reed, and J. Kyle, Computer Language, February 1985 (page 73). If you already have a C compiler and plan to stick with it, you have a different concern. The task at hand is to use the available compiler features and support tools to produce functioning programs. I have used several C compilers in addition to the Microsoft C Compiler to compile the programs presented in this book. They are the C86 C Compiler (Computer Innovations), The C Programming System (Mark Williams Company), and the MS-DOS C Compiler (Lattice). Each has its own way of doing things, although nearly all C compiler vendors are starting to converge on the proposed ANSI standard for C. Although it is possible to write source code with conditional compilation directives to accommodate various compilers, I chose not to do so in the source in Proficient C because that tends to obscure the meaning of the code and makes the source files nearly unreadable. The following material briefly describes each compiler system, the major observable differences from Microsoft C, and what has to be done to accommodate those differences. Others may exist. The ones mentioned are those relevant to the programs and routines developed in Proficient C. The compilers mentioned here deliver full compatibility with the de facto specification of C presented in the book The C Programming Language, by Brian Kernighan and Dennis Ritchie, commonly referred to as "K&R" by the C programming community. Each compiler varies from the others in the level of support for the proposed ANSI standard for C. Computer Innovations--Optimizing C86, Version 2.3 One of the first C compiler entries into the PC marketplace was Computer Innovations' C86, which was later replaced by Optimizing C86. The compiler features good compatibility with the standard UNIX library (pre- System V), support for many DOS features (all versions), object libraries in MS-DOS object format, and is delivered with all library source (C and assembler) in compressed form on disk. The compiler is due for an update at the time this is being written to bring it up to System V and DOS (version 3.00 and higher) compatibility. Optimizing C86 differs fundamentally from Microsoft C in that it: Has no void function return specifier--use a typedef of an int to get around this. Has no enum keyword--either avoid the use of enums or synthesize a palatable substitute using a typedef of an int. Uses the sysint() function instead of intdos() and uses sysint21() instead of int86(). The calling sequence of parameters is different. Provides movblock() instead of movedata() for segmented address memory moves. The parameter ordering is different. Has no means of determining the DOS version provided by the compiler--use the ver() function described in Chapter 5. Has no structure assignment and no passing of entire structures as parameters or function return values. Has no perror()--use fprintf() and a message of your own making. Optimizing C86 supports small and large memory models in a way that is consistent with the equivalent Microsoft models. Programs may also be compiled in an 8080 .COM memory model, which is called "compact." It is not the same as the Microsoft compact memory model. There are no equivalents to the Microsoft medium and huge models. No data object can exceed 64 KB in size. Compiling programs under C86 involves the use of batch files. There are currently no compiler driver programs and no MAKE-like facility to control processing. C86 can be given path information for the default location of header files. Mark Williams--The C Programming System, Version 3.0.7 The Mark Williams C Programming System (MWC from now on) is a complete C programming system adapted from the Mark Williams Coherent operating system, a UNIX Version 7 work-alike system. MWC incorporates some of C's newer features such as enum and void and up-to-date library functions. The compiler can be told to produce object files in either the Mark Williams or Microsoft object file formats. Libraries for both formats are provided with the compiler. MWC produces both small and large model (32-bit pointers) programs. It offers nothing comparable to the compact, medium, and huge Microsoft models. A public domain full-screen editor, MicroEMACS, is included in the package along with a good selection of UNIX-style support tools (make, cc, ld, pr, wc, and others). A trimmed-down version of MWC called Let's C is also available from Mark Williams. It compiles small-model programs only and is supported by fewer utilities, but it is a full K&R C compiler that is a good entry vehicle for programmers who are new to C. The primary differences between MWC and Microsoft C are that MWC: Has no structure assignment and no passing of entire structures as parameters or function return values. Uses intcall() instead of intdos(). It has no equivalent to the Microsoft int86(), but intcall() with an interrupt number of 21H will do the job (a bit slower, however). Provides port access via inb() and outb() (equivalent to Microsoft's inp() and outp() routines). Has no perror()--use fprintf() and a message of your own making. The global variable errno produces valid values in connection with math library functions only. It is not generally useful with other standard I/O library routines. Lattice--MS-DOS C Compiler, Version 3.00H The Lattice C Compiler, particularly the library support package, has undergone significant changes. The version 3.00 Lattice C compiler is very compatible with Microsoft C, versions 3.00 and 4.00; it differs mostly in minor details: The standard printer device is called stdprt instead of stdprn. The Microsoft _osmajor and _osminor are handled by the external character variable _DOS, which may be accessed as a single character or a two-character array to obtain the DOS major and minor version numbers. You can use the ver() function described in the Proficient C DOS library to get the operating system version numbers. The MS-DOS interface functions emulate virtually all of the PC operating system functions provided by Microsoft C, so calls to kbhit(), int86(), intdos(), and so on require no modifications to compile under Lattice C. The compiler is accompanied by a library that classifies each function by its "environment" (i.e, origins and compatibility). The following classes are defined by Lattice: ═══════════════════════════════════════════════════════════════════════════ CLASS DESCRIPTION ─────────────────────────────────────────────────────────────────────────── ANSI Conforming to the proposed ANSI standard UNIX Conforming to AT&T's UNIX System V standard XENIX Compatible with Microsoft XENIX LATTICE Available on all systems for which Lattice provides a C compiler iAPX86 Available only on iAPX32 machines MS-DOS Designed for use under generic MS-DOS and compatible with PC-DOS (a superset of MS-DOS) PC-DOS For use under PC-DOS but not guaranteed to work under MS-DOS ─────────────────────────────────────────────────────────────────────────── Lattice offers four memory models: small, program, data, and large. The models are comparable to the Microsoft small, medium, compact, and large models, respectively. Objects are limited to 64 KB in size. There are no equivalents to Microsoft's huge keyword and huge model. Compiling programs with the latest Lattice C compiler is easier than under previous versions. A compiler driver program, LC, does most of the work of compiling by calling the passes in the correct order and bailing out in the event of compile-time errors. The linking step is still manual and is best handled by batch files tailored to the particular linking task and the selected memory model. Maintaining Programs For owners of C compilers that do not provide a MAKE command, several alternatives are available. The first is to use DOS batch files to control compilation and linking steps. The DOS ERRORLEVEL (program exit code) can be used to abort processing when errors occur (if the compiler programs use the error-return facility and you are running DOS version 2.00 or higher). The problem with batch files is that the burden of knowing which program modules have to be remade is left to you. Another alternative is to use a third-party MAKE utility. An excellent MAKE program called PolyMake is available from Polytron. It is as UNIX-like as any DOS MAKE I have seen and can be made to work with any C compiler via rules placed in a control file. Because PolyMake is closer to the UNIX model that I am familiar with, I prefer to use it rather than the MAKEs provided with most C compilers (with the exception of the Mark Williams MAKE program, which is excellent). Several other MAKE utilities for DOS are available at reasonable cost. Note: The makefiles in Proficient C are written for the Microsoft version of MAKE. They will probably need to be rewritten to run successfully with other MAKE programs. Appendix C Characters and Attributes A character code is a numeric value that is used to represent a character in computer memory and to control peripheral devices such as terminals, the console display screen, and printers. We are interested in two primary character-coding schemes: the ASCII character set, because it is the standard to which most commercial terminal and computer equipment designs adhere, and the IBM extended ASCII character set used by the IBM PC and work-alike computers. In dealing with terminals and PC console display devices, numeric codes are also used to control the appearance of a displayed character (video attribute), to prevent specified screen regions from being updated (protect), and even to make certain areas of the screen invisible to the user (nondisplay). IBM PCs do not directly support protected fields, although our programs can simulate the effect. On a PC, a nondisplay field is one that carries a special video attribute which sets the foreground color to the same value as the background color. This appendix is a detailed summary of the characters and attributes available to programmers of the IBM PC family of computers. ASCII Character Codes The ASCII (American National Standard Code for Information Interchange) character set is defined as a table of 7-bit codes that represent a collection of control characters and printable characters. In a 7-bit environment all data bits are significant. In the 8-bit environment typical of the IBM PC and similar equipment, the lower seven bits (0 through 6) are used to represent ASCII characters. The high bit (bit 7) is used for IBM code extensions, which are discussed later in this appendix. Figure C-1 shows the relationship between various character codes and the data bytes that hold them. Bit # 7 6 5 4 3 2 1 0 ┌──────┬──────┬──────┬──────┬──────┬──────┬──────┬──────┐ │▒▒▒▒▒▒│ │ │ │ │ │ │ │ Character │▒▒▒▒▒▒│ │ │ │ │ │ │ │ Byte └──────┴──────┴──────┴──────┴──────┴──────┴──────┴──────┘ Weight 128 64 32 16 8 4 2 1 ▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ │ │ Code Exten- 7-Bit ASCII Codes sion Bit ╔═══════════════════════════════════════════════════════╗ ║ Character Code Ranges: ║ ║ ║ ║ 0-31 Control Characters ▓ ║ ║ 32-126 Graphic Characters ▓ ASCII ║ ║ 127 Delete Character ▓ ║ ║ 128-255 IBM Special Graphic Characters ║ ╚═══════════════════════════════════════════════════════╝ FIGURE C-1 ▐ Character codes and bytes ASCII Control Character Table ASCII codes 0 through 31 and 127 decimal (shown in Figure C-2, next page) are called control codes because they are used to start, stop, or modify some action. Several of the control characters have meanings that vary with the context of their use, but most can be categorized as being one or more of the following types: Format Effector (FE)--controls the printed or displayed layout of graphic information Communications Control (CC)--controls the operation of communication devices and networks Information Separator (IS)_controls the logical separation of information It may seem a bit odd to have one control code (DEL = 127) isolated from all the others. This is due to its earliest use with paper-tape punches for which the DEL code means "erase or obliterate" an unwanted character, which on a medium like paper tape could be done only by punching out all seven of the holes (hence code 127 or 7F hex). In its design of the PC, IBM has attached special meanings to most of the ASCII control codes so that they have displayable graphic content when placed directly into display memory. Thus, the format effector CR (code 13 decimal), in addition to its "carriage return" meaning when embedded in data streams, can also be used to place a musical-note symbol on the display screen. Each of the control codes except NUL (0) have an associated displayable symbol on the IBM PC. ╓┌─────┌─────────────────────────┌──────────┌─────────┌──────────┌───────────╖ NAME DESCRIPTION DEC HEX IBM KEY (TYPE) CODE CODE GRAPHIC ─────────────────────────────────────────────────────────────────────────── NUL Null 0 00 nothing SOH Start of heading 1 01 ^A STX Start of text 2 02 ^B ETX End of text 3 03 ^C EOT End of transmission 4 04 ^D ENQ Enquiry 5 05 ^E ACK Acknowledge 6 06 ^F BEL Bell 7 07 ^G BS Backspace 8 08 ^H HT Horizontal tab 9 09 ^I LF1 Linefeed 10 0A ^J NAME DESCRIPTION DEC HEX IBM KEY (TYPE) CODE CODE GRAPHIC LF1 Linefeed 10 0A ^J VT Vertical tab 11 0B ^K FF Formfeed 12 0C ^L CR Carriage return 13 0D ^M SO Shift out 14 0E ^N SI Shift in 15 0F ^O DLE Data link escape 16 10 ^P DC1 Device control 1 17 11 ^Q DC2 Device control 2 18 12 ^R DC3 Device control 3 19 13 ^S DC4 Device control 4 20 14 ^T NAK Negative acknowledge 21 15 ^U SYN Synchronous idle 22 16 ^V ETB End transmission block 23 17 ^W CAN Cancel 24 18 ^X EM End of medium 25 19 ^Y SUB Substitute 26 1A ^Z ESC Escape 27 1B ^[ FS File separator 28 1C ^\ NAME DESCRIPTION DEC HEX IBM KEY (TYPE) CODE CODE GRAPHIC FS File separator 28 1C ^\ GS Group separator 29 1D ^] RS Record separator 30 1E ^^ US Unit separator 31 1F ^_ DEL Delete 127 7F Del FIGURE C-2 ▐ ASCII control character table Printable Character Table The ASCII codes in the range of 32 to 126 decimal are designated "graphic" characters to show that they have a visible representation on a display device. Only the meaning of code 32, space (SP), which prints or displays as a blank location in a graphic sequence, is defined by the ASCII standard. All of the remaining graphic characters have meanings that are, in effect, enforced by consensus. We simply accept the fact that code 65 decimal represents the letter 'A', for example. Nothing in the standard demands that the graphic symbols be shown as Gothic or Roman or any other type style. That decision is left to the terminal/computer maker and usually is determined by whatever type style the producer of the video controller chip supplies. The following table (Figure C-3) shows the accepted definitions of the graphic characters. ╓┌──────────┌────────┌───────────────────────────────────────────────────────╖ ASCII DEC HEX ────────────────────── <space> 32 20 ! 33 21 " 34 22 # 35 23 $ 36 24 % 37 25 & 38 26 ' 39 27 ( 40 28 ) 41 29 * 42 2A + 43 2B , 44 2C ASCII DEC HEX , 44 2C - 45 2D . 46 2E / 47 2F 0 48 30 1 49 31 2 50 32 3 51 33 4 52 34 5 53 35 6 54 36 7 55 37 8 56 38 9 57 39 : 58 3A ; 59 3B < 60 3C = 61 3D > 62 3E ? 63 3F ASCII DEC HEX ? 63 3F @ 64 40 A 65 41 B 66 42 C 67 43 D 68 44 E 69 45 F 70 46 G 71 47 H 72 48 I 73 49 J 74 4A K 75 4B L 76 4C M 77 4D N 78 4E O 79 4F P 80 50 Q 81 51 R 82 52 ASCII DEC HEX R 82 52 S 83 53 T 84 54 U 85 55 V 86 56 W 87 57 X 88 58 Y 89 59 Z 90 5A [ 91 5B \ 92 5C ] 93 5D ^ 94 5E _ 95 5F ` 96 60 a 97 61 b 98 62 c 99 63 d 100 64 e 101 65 ASCII DEC HEX e 101 65 f 102 66 g 103 67 h 104 68 i 105 69 j 106 6A k 107 6B l 108 6C m 109 6D n 110 6E o 111 6F p 112 70 q 113 71 r 114 72 s 115 73 t 116 74 u 117 75 v 118 76 w 119 77 x 120 78 ASCII DEC HEX x 120 78 y 121 79 z 122 7A { 123 7B | 124 7C } 125 7D ~ 126 7E FIGURE C-3 ▐ The ASCII standard character set IBM Extended ASCII Codes Because the ASCII character set is based on a 7-bit code, the high bit of each byte used by the IBM PC is available for other uses. When bit 7 (the high bit) is a logical 1, the character codes range from 128 to 255 decimal (Figure C-4). IBM uses these extra 128 codes for special characters (international symbols, line-and-block drawing characters, special symbols for mathematics, and so forth). ╓┌──────────┌─────────┌──────────────────────────────────────────────────────╖ IBM GRAPHIC DEC HEX ─────────────────────── Ç 128 80 ü 129 81 é 130 82 â 131 83 ä 132 84 à 133 85 å 134 86 ç 135 87 ê 136 88 ë 137 89 è 138 8A ï 139 8B î 140 8C ì 141 8D Ä 142 8E Å 143 8F É 144 90 IBM É 144 90 æ 145 91 Æ 146 92 ô 147 93 ö 148 94 ò 149 95 û 150 96 ù 151 97 ÿ 151 98 Ö 152 99 Ü 154 9A ¢ 155 9B £ 156 9C ¥ 157 9D ₧ 158 9E ƒ 159 9F á 160 A0 í 161 A1 ó 162 A2 ú 163 A3 IBM ú 163 A3 ñ 164 A4 Ñ 165 A5 ª 166 A6 º 167 A7 ¿ 168 A8 ⌐ 169 A9 ¬ 170 AA ½ 171 AB ¼ 172 AC ¡ 173 AD « 174 AE » 175 AF ░ 176 B0 ▒ 177 B1 ▓ 178 B2 │ 179 B3 ┤ 180 B4 ╡ 181 B5 ╢ 182 B6 IBM ╢ 182 B6 ╖ 183 B7 ╕ 184 B8 ╣ 185 B9 ║ 186 BA ╗ 187 BB ╝ 188 BC ╜ 189 BD ╛ 190 BE ┐ 191 BF └ 192 C0 ┴ 193 C1 ┬ 194 C2 ├ 195 C3 ─ 196 C4 ┼ 197 C5 ╞ 198 C6 ╟ 199 C7 ╚ 200 C8 ╔ 201 C9 IBM ╔ 201 C9 ╩ 202 CA ╦ 203 CB ╠ 204 CC ═ 205 CD ╬ 206 CE ╧ 207 CF ╨ 208 D0 ╤ 209 D1 ╥ 210 D2 ╙ 211 D3 ╘ 212 D4 ╒ 213 D5 ╓ 214 D6 ╫ 215 D7 ╪ 216 D8 ┘ 217 D9 ┌ 218 DA █ 219 DB ▄ 220 DC IBM ▄ 220 DC ▌ 221 DD ▐ 222 DE ▀ 223 DF α 224 E0 ß 225 E1 Γ 226 E2 π 227 E3 Σ 228 E4 σ 229 E5 µ 230 E6 τ 231 E7 Φ 232 E8 Θ 233 E9 Ω 234 EA δ 235 EB ∞ 236 EC φ 237 ED ε 238 EE ∩ 239 EF IBM ∩ 239 EF ≡ 240 F0 ± 241 F1 ≥ 242 F2 ≤ 243 F3 ⌠ 244 F4 ⌡ 245 F5 ÷ 246 F6 ≈ 247 F7 ° 248 F8 ∙ 249 F9 · 250 FA √ 251 FB ⁿ 252 FC ² 253 FD ■ 254 FE 255 FF FIGURE C-4 ▐ The IBM extended ASCII character set Line-Drawing Characters_Quick Reference Among the IBM extended ASCII characters are some line-drawing characters that allow us to draw boxes and other shapes that can be formed from various corners and straight-line segments. The codes are a bit scattered, so to make them accessible, Figure C-5 visually groups the codes for single- and double-line drawing characters. The origin of these design aids can be traced to Rich Schinnell in an item published in PC World (November 1983). 205 186 196 186 ═══════ ║ ─────── ║ ║ ║ 201 203 187 214 210 183 ╔═════ ══╦══ ═════╗ ╓───── ──╥── ─────╖ ║ ║ ║ ║ ║ ║ 204 206 185 199 215 182 ║ ║ ║ ║ ║ ║ ╠════ ═══╬═══ ════╣ ╟──── ───╫─── ────╢ ║ ║ ║ ║ ║ ║ 200 202 188 211 208 189 ║ ║ ║ ║ ║ ║ ╚═════ ══╩══ ═════╝ ╙───── ──╨── ─────╜ 196 179 205 179 ─────── │ ═══════ │ │ │ 218 194 191 213 209 184 ┌───── ──┬── ─────┐ ╒═════ ══╤══ ═════╕ │ │ │ │ │ │ 195 197 180 198 216 181 │ │ │ │ │ │ ├──── ───┼─── ────┤ ╞════ ═══╪═══ ════╡ │ │ │ │ │ │ 192 193 217 212 207 190 │ │ │ │ │ │ └───── ──┴── ─────┘ ╘═════ ══╧══ ═════╛ FIGURE C-5 ▐ Line-drawing character sets Block Characters--Quick Reference The treasure trove of special characters in the IBM extended ASCII character set also contains eight block characters that can be used to good effect in screen displays. They are detailed in Figure C-6. ╔══════════════════════════════════════════╗ ║ ║ ║ Figure C-6 is found on page 445 ║ ║ in the printed version of the book. ║ ║ ║ ╚══════════════════════════════════════════╝ FIGURE C-6 ▐ Block character sets Video Attributes Both the monochrome and color display systems used with PCs give us a considerable degree of control over the appearance of characters on the screen. Each character byte in memory is accompanied by an attribute byte that specifies the visual characteristics of each displayed character. Figure C-7 shows how the attribute byte is interpreted. Bit # 7 6 5 4 3 2 1 0 ┌──────┬──────┬──────┬──────┬──────┬──────┬──────┬──────┐ │ BL │ R │ G │ B │ I │ R │ G │ B │ Attribute └──────┴──────┴──────┴──────┴──────┴──────┴──────┴──────┘ Byte ░ 128 64 32 16 8 4 2 1 Weight ░ ░ 8 4 2 1 8 4 2 1 ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ │ │ Background Foreground ╔═══════════════════════════════════════════════════════╗ ║ Bit designations: ║ ║ ║ ║ BL Foreground blink or background intensity ║ ║ I Foreground intensity ║ ║ R Red ║ ║ G Green ║ ║ B Blue ║ ╚═══════════════════════════════════════════════════════╝ FIGURE C-7 ▐ Video attribute byte interpretation The following table summarizes the text mode attributes for both monochrome and color/graphics systems. The codes between 0 and 7 set the foreground (low 4 bits) or background (high 4 bits) attribute. Thus, storing the code 0x02 in an attribute byte produces a green foreground and a black background. The high bit in each 4-bit (nibble) attribute component determines the intensity. In the foreground component, setting bit 3 causes the foreground to be high intensity. Setting bit 7 of an attribute byte controls either foreground blinking or background intensity. On a CGA, port 3D8, bit 5 enables foreground blinking when set and disables blinking when cleared. The power-on default is blink (bit 5=1). The equivalent MDA port is 3B8. We can combine attribute values using bit shifting and ORing to produce various compound attributes. The combined code (0x01 << 4) | 0x07 | 0x08 yields a bright white character on a blue background. ═══════════════════════════════════════════════════════════════════════════ PRIMARY ATTRIBUTES ─────────────────────────────────────────────────────────────────────────── Dec Hex Binary Attribute Description Code Code Code CGA MDA FG MDA BG ─────────────────────────────────────────────────────────────────────────── 0 00 0000 Black Black Black 1 01 0001 Blue White Underline White 2 02 0010 Green White White 3 03 0011 Cyan White White 4 04 0100 Red White White 5 05 0101 Magenta White White 6 06 0110 Brown White White 7 07 0111 White White White ─────────────────────────────────────────────────────────────────────────── ═══════════════════════════════════════════════════════════════════════════ INTENSITY MODIFIERS ─────────────────────────────────────────────────────────────────────────── Dec Hex Binary Description Code Code Code ─────────────────────────────────────────────────────────────────────────── 8 08 1000 High Intensity 128 80 10000000 Blinking Foreground (or High Intensity Background). [This is just (0x08 << 4) and is referred to as the "blink" bit or background intensity bit depending upon whether blinking is enabled (default) or disabled.] ─────────────────────────────────────────────────────────────────────────── Appendix D Local Library Summary Proficient C is largely about stockpiling routines to augment those provided in the standard library. In the course of 14 chapters, we have developed numerous functions and macros for a wide range of purposes. To make the routines accessible to programmers, a brief manual page for each routine is presented here. The routines are grouped by library category and organized alphabetically within categories. The libraries we developed are the ansi.sys interface (ansi.lib), the operating system interfaces (bios.lib and dos.lib), the buffered screen interface (sbuf.lib), and the utility routines (util.lib). ═══════════════════════════════════════════════════════════════════════════ ANSI LIBRARY ─────────────────────────────────────────────────────────────────────────── The ANSI device driver is accessed primarily through the macros defined in the ansi.h header file that resides in \include\local. Two additional routines are implemented as functions in \lib\local\ansi.lib. The ANSI device driver and this interface are described in Chapter 13. ─────────────────────────────────────────────────────────────────────────── Function ansi_cpr--cursor position report Synopsis #include <local\ansi.h> void ansi_cpr(row, col) int *row; /* pointer to row value */ int *col; /* pointer to column value */ Description Request a cursor position report from the ANSI device driver. The driver must have been previously installed. The cursor position values are saved in the row and col variables whose addresses are passed as parameters. Notes This function will fail (hang the system waiting for keyboard input) if the ANSI device driver is not properly installed. ─────────────────────────────────────────────────────────────────────────── Macro ANSI_CUP--position the cursor ANSI_HVP--horizontal and vertical position Synopsis #include <local\ansi.h> ANSI_CUP(r, c) ANSI_HVP(r, c) short r, c; /* row and column */ Description These two macros achieve the same result. They attempt to move the cursor to the specified screen position. Illegal requests are ignored. ─────────────────────────────────────────────────────────────────────────── Macro ANSI_CUB--move cursor back (left) ANSI_CUD--move cursor down ANSI_CUF--move cursor forward (right) ANSI_CUU--move cursor up Synopsis #include <local\ansi.h> ANSI_CUB(n) ANSI_CUD(n) ANSI_CUF(n) ANSI_CUU(n) short n; /* number of repetitions (columns or rows) */ Description These four macros attempt to move the cursor in the specified direction. If n is larger than the number of rows or columns remaining in the direction of travel, the cursor is moved to the extreme position. ─────────────────────────────────────────────────────────────────────────── Macro ANSI_DSR--request a device status report ANSI_RCP--restore screen position ANSI_SCP--save screen position Synopsis #include <local\ansi.h> ANSI_DSR ANSI_RCP ANSI_SCP Description A call to ANSI_DSR causes the ANSI driver to deposit a string containing the cursor row and column data into the keyboard buffer where it can be read (see the ansi_cpr() function). ANSI_SCP and ANSI_RCP are cooperating macros that communicate through private storage to save and restore the cursor position. ─────────────────────────────────────────────────────────────────────────── Macro ANSI_ED--erase in display (clear screen) ANSI_EL--erase in line (clear to end of line) Synopsis #include <local\ansi.h> ANSI_ED ANSI_EL Description ANSI_ED sets all character locations in the display to blanks, effectively clearing the screen. Similarly, ANSI_EL sets all character positions from the cursor to the end of the line to blanks. Notes Most ANSI drivers use the prevailing video attribute for cleared character positions, but at least the MS-DOS version of the ANSI driver provided for the AT&T 6300 uses the "normal" (white on black) attribute. ─────────────────────────────────────────────────────────────────────────── Macro ANSI_RM--reset mode ANSI_SM--set mode Synopsis #include <local\ansi.h> ANSI_RM(m) ANSI_SM(m) short m; Description These two macros are used to set and reset (clear) video modes. In addition to the usual video modes that can be set from the DOS command line using the MODE command, ANSI_SM and ANSI_RM permit programs to control "wrapping" at the end of display lines. ─────────────────────────────────────────────────────────────────────────── Macro ANSI_SGR--set graphic rendition (video attribute) Synopsis #include <local\ansi.h> ANSI_SGR(a) unsigned char a; /* video attribute */ Description ANSI_SGR can be used to set any of the video attributes allowed for text modes. ─────────────────────────────────────────────────────────────────────────── Function ansi_tst--check for the presence of ANSI.SYS Synopsis #include <local\ansi.h> void ansi_tst() Description Uses cursor positioning and reading to determine whether the ANSI device driver is installed. If not, the function displays an error message and returns control to DOS. If the ANSI driver is installed, control is returned to the calling program. Notes This function uses the BIOS readca() function to find out where the cursor is located because ansi_cpr() cannot be called unless the ANSI driver is known to be installed. Thus, ansi_tst() may fail on PCs that are not completely BIOS-compatible with the IBM PC family. ─────────────────────────────────────────────────────────────────────────── Function colornum--convert a color string to a number Synopsis #include <local\ibmcolor.h> int colornum(name) char *name; /* color string */ Description Using a built-in lookup table, colornum() converts a color name in string form, "red" for example, to its IBM numeric equivalent (4 in this case). Return A number that specifies the IBM color value for the specified color name. ─────────────────────────────────────────────────────────────────────────── Function setattr--set video attribute Synopsis #include <local\ansi.h> #include <local\ibmcolor.h> void setattr(pos, attr) POSITION pos; int attr; Description Using information provided by the caller about the attribute position (pos), setattr() sets the foreground, background, or border attribute to the specified value. ─────────────────────────────────────────────────────────────────────────── Function userattr--set a user-specified attribute Synopsis #include <local\ansi.h> int userattr(foreground, background, border) char *foreground, *background, *border; Description A program can call userattr() just before exiting to set the video attributes to those specified by the user in the DOS environment (using FGND, BKGND, and BORDER DOS variables). The calling function must specify attribute values to be used in the event that none are specified in the environment. Return An indication of SUCCESS or FAILURE. ═══════════════════════════════════════════════════════════════════════════ BIOS LIBRARY ─────────────────────────────────────────────────────────────────────────── The BIOS library is composed of selected routines supported by the PC's ROM BIOS. Primary coverage is given to BIOS video and equipment-determination functions. In addition, keyboard status and some composite video functions are included in the library. Most other needed services can be obtained via routines in the standard libraries provided with nearly all C compilers for DOS. Most of the BIOS routines are designed to return the value of the carry flag, which is a nonzero value if an error occurs duing the interrupt operation. A few use the return value to pass back the information requested by the calling function. ─────────────────────────────────────────────────────────────────────────── Function clrscrn--clear the entire screen to spaces clrw--clear a "window" region to spaces Synopsis int clrscrn(a) int clrw(t, l, b, r, a) unsigned char a; /* video attribute */ int t, l; /* upper left corner */ int b, r; /* lower right corner */ Description The two functions, clrscrn() and clrw(), set all characters to spaces in the entire display memory or a specified region, respectively. The current "visual" page is cleared. Return The value of the carry flag. ─────────────────────────────────────────────────────────────────────────── Function delay--provide a machine-independent time delay Synopsis void delay(d) float d; /* delay duration */ Description The delay() function loops to waste the specified number of seconds and fractional seconds. The delay has a practical resolution of about .06 seconds. ─────────────────────────────────────────────────────────────────────────── Function drawbox--draw a single-line text graphics box shape Synopsis int drawbox(top, lft, btm, rgt, pg) int top, lft; /* upper left corner */ int btm, rgt; /* lower right corner */ int pg; /* screen page number */ Description The drawbox() function draws a fine-rule box (using the IBM single- line drawing characters) around the perimeter of the region specified by the corner parameters. The pg parameter specifies the screen page (active) to draw on. On a standard monochrome display adapter, this value must be 0. Notes This function is usually not appropriate for use in graphics modes because the special drawing characters are not defined unless you create your own table of "extended" character definitions. ─────────────────────────────────────────────────────────────────────────── Function ega_info--gather EGA-related information Synopsis #include <local\video.h> int ega_info(memsize, mode, features, switches) int *memsize; /* memory size index (0-3) */ int *mode; /* color (0)/mono (1) mode */ unsigned int *features; /* feature bit settings */ unsigned int *switches; /* EGA switch settings */ Description This function uses an EGA BIOS routine to gather and save EGA-related information including whether an EGA adapter is installed in the system. Memory size is reported by an index (from 0 = 64 KB up to 3 = 256 KB in 64-KB increments) and mode is indicated only as color (0) or monochrome. Use the getstate() function to find out what the video mode number is. Return A logical 1 if the reported memory size is valid or 0 otherwise. This is considered by IBM to be an adequate indicator of the presence or absence of an EGA adapter. ─────────────────────────────────────────────────────────────────────────── Function equipchk--get equipment list Synopsis #include <local\equip.h> int equipchk() Description The equipchk() function queries the system data areas and fills in the global Eq structure to indicate what equipment is installed. The data structure holds the number of logical disk drives, parallel printer ports, and serial ports. It also indicates whether the system has a game port and shows how much of the installed memory is on the system board. In addition, the current video mode is indicated by the BIOS video mode number (see getstate() for details). Return The value of the carry flag. ─────────────────────────────────────────────────────────────────────────── Function getctype--get the current cursor type Synopsis #include <local\bioslib.h> int getctype(start_scan, end_scan, pg) int *start_scan; /* starting cursor scan line */ int *end_scan; /* ending cursor scan line */ int pg; /* "visual" page */ Description The getctype() function retrieves the values of the starting and ending cursor scan rows. Return The value of the carry flag. ─────────────────────────────────────────────────────────────────────────── Function getstate--get the current video state Synopsis #include <local\video.h> int getstate() Description This function queries the system data areas in memory and updates the global video state variables. Return The value of the carry flag. ─────────────────────────────────────────────────────────────────────────── Function getticks--get the current timer "tick" count Synopsis long getticks() Description This function queries the BIOS data area via the time-of-day service to get a value that is the number of timer ticks since midnight. If the rollover flag is set, a full day's worth of ticks is added to the count. Return The current timer "tick" count. ─────────────────────────────────────────────────────────────────────────── Function kbd_stat--get keyboard status information Synopsis #include <local\keybdlib.h> unsigned char kbd_stat() Description The kbd_stat() function obtains keyboard status information and makes it available to the calling function. Each bit in the status byte is significant and is defined in the keybdlib.h file. This function lets the program determine the current state of the shift, control (Ctrl), alternate shift (Alt), and lock (Num, Caps, Scroll) keys. Return The value of the AL register, which contains the keyboard status information (bit-significant). ─────────────────────────────────────────────────────────────────────────── Function memsize--get memory size in kilobytes Synopsis int memsize() Description The memsize() function reads the system data area to determine the total amount of memory installed in the system. Return The total memory size (system board plus I/O channel) in kilobytes. ─────────────────────────────────────────────────────────────────────────── Function palette--select graphics palette or text border color Synopsis int palette(id, color) unsigned int id; /* palette identifier */ unsigned int color; /* color number */ Description The palette() function can be used in either graphics or text (alphanumeric) modes. It selects the palette of foreground drawing colors in graphics modes. In text modes, it selects the border color. Return The value of the carry flag. ─────────────────────────────────────────────────────────────────────────── Function putcur--move the cursor to a specified row and column Synopsis int putcur(r, c, pg) int r, c; /* row and column */ int pg; /* "active" screen page */ Description This function places the cursor at the specified row and column of the active page given by pg. Illegal requests are silently ignored by the BIOS routine. Return The value of the carry flag. ─────────────────────────────────────────────────────────────────────────── Function putfld--display a string in a field Synopsis int putfld(s, w, pg) register char *s; /* string to write */ int w; /* field width */ int pg; /* screen page for writes */ Description The putfld() function calls other BIOS functions to display a string within a field starting on page pg at the current cursor position and extending for w columns. Runs of a single given character, such as a series of spaces, are compressed to a single call on writec() to reduce function-call overhead. The field is padded with spaces if the string does not completely fill it. The string is truncated if it is too long to fit in the field. The cursor location is updated to the last position written. Return A 0 if all goes well or a nonzero value to flag an error. ─────────────────────────────────────────────────────────────────────────── Function putstr--display a string in the prevailing attribute Synopsis int putstr(s, pg) register char *s; /* string to display */ int pg; /* "active" screen page */ Description The putstr() function places the text of the string into display memory and advances the cursor position. Return Number of characters written. Notes Results are undefined if the string is not confined to the current screen row. ─────────────────────────────────────────────────────────────────────────── Function put_ch--display a character Synopsis int put_ch(ch, pg) register char ch; /* character to write */ int pg; /* "active" screen page */ Description The put_ch() function writes a single character to the display and advances the cursor position. Return Always 1 to indicate the number of characters written. ─────────────────────────────────────────────────────────────────────────── Function readca--read the character and attribute in a cell Synopsis int readca(ch, attr, pg) unsigned char *ch; /* character */ unsigned char *attr; /* video attribute */ int pg; /* "active" screen page */ Description The readca() function gets the values of the character and video attribute at the current cursor position on the specified active screen page and fills in the ch and attr variables pointed to by the parameters. Return The value of the carry flag. ─────────────────────────────────────────────────────────────────────────── Function readcur--get the current cursor row and column Synopsis int readcur(row, col, pg) int *row, *col; /* pointers to cursor values */ int pg; /* "active" screen page */ Description The readcur() function reports the location of the cursor on the specified screen page by storing the row and column values in the row and col variables pointed to by the parameters. Return The value of the carry flag. ─────────────────────────────────────────────────────────────────────────── Function readdot--read the value of a single pixel Synopsis int readdot(row, col, dcolor) int row, col; /* cursor position */ int *dcolor; /* pointer to dot color */ Description The readdot() function places the color number for the pixel at the row and column position into the variable pointed to by the dcolor parameter. The row and col parameters can be used to address up to 224,000 individual screen pixels in the high resolution mode of the Enhanced Graphics Adapter. Return The value of the carry flag. ─────────────────────────────────────────────────────────────────────────── Function scroll--scroll a specified screen region vertically Synopsis int scroll(t, l, b, r, n, a) int t, l; /* upper left corner */ int b, r; /* lower right corner */ int n; /* number of rows to scroll */ unsigned char a; /* video attribute */ Description The scroll() routine clears (initializes) the specified region if n is 0. It scrolls the display image up n lines if n is a positive nonzero value and down if n is negative. Vacated lines are filled with blanks (spaces) in the specified attribute. Return The value of the carry flag. ─────────────────────────────────────────────────────────────────────────── Function setctype--set the cursor type Synopsis int setctype(start, end) int start; /* starting cursor scan line */ int end; /* ending cursor scan line */ Description The setctype() function sets the starting and ending scan lines that form the cursor shape. If the starting scan line is greater than the ending scan line, the cursor is split (formed of two parts) on perfectly IBM-compatible machines. Setting the cursor starting scan line to a large value turns the cursor off on many machines, but this is not a reliable method on all hardware. Return The value of the carry flag. ─────────────────────────────────────────────────────────────────────────── Function setpage--select the "visual" video page Synopsis int setpage(pg) int pg; /* "visual" screen page */ Description This function sets the "visual" screen page to pg. It checks the value of pg against the valid page ranges for the current video mode. Return The value of the carry flag or -1 if an illegal page request is made. ─────────────────────────────────────────────────────────────────────────── Function setvmode--set the video mode Synopsis int setvmode(vmode) int vmode; /* video mode number */ Description The setvmode() function attempts to set the specified video mode. Illegal mode requests are not detected and are usually silently ignored by the BIOS routine. Return The value of the carry flag. Notes This function cannot be used to switch from one display adapter to another in systems equipped with more than one adapter. Instruct users to run the DOS MODE command to set the mode before entering the program. ─────────────────────────────────────────────────────────────────────────── Function writea--write an attribute writec--write a character writeca--write a character in a specified attribute Synopsis int writea(a, count, pg) int writec(ch, count, pg) int writeca(ch, attr, count, pg) unsigned char ch; /* character */ unsigned char attr; /* video attribute */ int count; /* number of repetitions */ int pg; /* "active" screen page */ Description These functions write a (possibly) repeated attribute, character, or a combination of the two to the specified screen page. The count specifies the number of characters to write and must fit entirely within the current screen row. Return The value of the carry flag. ─────────────────────────────────────────────────────────────────────────── Function writedot--write a single pixel Synopsis int writedot(r, c, color) int r, c; /* coordinates of the pixel */ int color; /* dot color */ Description This function is for use in graphics modes only. It sets the color of the specified pixel to color. Setting the color to the same color as the background effectively erases the pixel. Return The value of the carry flag. ─────────────────────────────────────────────────────────────────────────── Function writemsg--write a two-part message Synopsis int writemsg(r, c, w, s1, s2, pg) int r, c; /* starting location */ int w; /* field width */ char *s1, *s2; /* components of the string */ int pg; /* "active" screen page */ Description The writemsg() function places a two-part message (either or both parts may be empty) on the specified screen page. If the combined string is too long to fit in the field it is truncated. If it does not fill the field exactly, the field is padded with spaces. Return The number of characters written. ─────────────────────────────────────────────────────────────────────────── Function writetty--write a character using "teletype" style Synopsis int writetty(ch, attr, pg) unsigned char ch; /* character */ unsigned char attr; /* video attribute */ int pg; /* "active" screen page */ Description The writetty() function places a character into the specified screen page and advances the cursor position. The screen is scrolled if necessary to keep the current position within the viewable screen boundaries. The function responds to the usual format effectors (backspace, carriage return, and linefeed) correctly. All other codes, including other control codes, are simply displayed. Return The value of the carry flag. Notes The attribute specification is honored only in text modes. It is simply ignored in graphics modes. ═══════════════════════════════════════════════════════════════════════════ DOS LIBRARY ─────────────────────────────────────────────────────────────────────────── Only a very limited set of DOS routines are packaged in the local DOS library because the standard library provides rather complete DOS access to disk files, the console keyboard, DOS date and time, and so on. ─────────────────────────────────────────────────────────────────────────── Function drvpath--convert a drive name to a full pathname Synopsis char *drvpath(path) char path[]; /* path string buffer */ Description A disk drive designation (d:) is a shorthand notation for the current directory on disk drive d. The drvpath() function accepts a disk drive designation as the initial portion of a character buffer and appends the full pathname of the current directory on that drive to it. Return A pointer to a full pathname string starting with the drive letter. Notes The user-supplied buffer (path) must be large enough to hold the longest DOS directory pathname (64 characters) plus a terminating NUL. ─────────────────────────────────────────────────────────────────────────── Function first_fm--find the first matching filename next_fm--find the next matching filename Synopsis int first_fm(path, fa) int next_fm() char *path; /* ambiguous pathname */ int fa; /* file attributes */ Description Under DOS, we can specify filenames ambiguously using the * and ? wildcard characters. The first_fm() function finds the first match in directory order to an ambiguous specification. If the first match is found, additional matches, if any, may be found by calling the next_fm() function repeatedly until no match is found. The file attributes specified by the fa parameter determine which files that match the ambiguous name will be matched. If fa equals 0, the functions attempt to match only ordinary files. If the volume- label attribute is set, the functions search only for a volume label. Setting fa to system, hidden, subdirectory, or any combination of these attributes tells the functions to match files having those attributes in addition to all ordinary files. Return Both functions return the value of the carry flag, which is 0 for success or nonzero for failure. Notes These functions use a disk transfer area of type struct DTA, which is defined in the header file ls.h. The DTA is established by a call to setdta(). If any intervening functions alter the DTA, it must be reset by calling setdta() before making further calls to next_fm. ─────────────────────────────────────────────────────────────────────────── Function getdrive--return the ID of the default drive Synopsis int getdrive() Description The getdrive() function asks DOS for the ID of the current disk drive. The ID is the number used internally by DOS where 0 means drive A, 1 means B, and so on. Return The internal drive number of the current disk drive. ─────────────────────────────────────────────────────────────────────────── Function getkey--get a keystroke Synopsis #include <local\keydefs.h> int getkey() Description Gets the next available key code from the keyboard buffer. If nothing is ready, getkey() waits for the user to type something. If you do not want a "blocking" read, use keyready() (or kbhit()) to determine whether anything is ready to read before calling getkey(). Return The code associated with the oldest item in the keyboard buffer. If the returned value is 256 or more, the input was produced by a special key and the returned value represents an extended key code (NUL + scan code). Notes Because getkey() uses DOS function 7 (INT 21H), it is immune to Ctrl- Break and it does not echo the typed input to the screen. ─────────────────────────────────────────────────────────────────────────── Function keyready--check the keyboard buffer Synopsis int keyready() Description Checks the console for a waiting keystroke. Return A nonzero value if something is waiting in the keyboard buffer. Notes This function performs the same job as the kbhit() function in the standard Microsoft library. It is presented for those whose C compilers offer no equivalent function. ─────────────────────────────────────────────────────────────────────────── Function setdta--set the disk transfer area (DTA) Synopsis void setdta(bp) char *bp; /* buffer pointer */ Description This function establishes a buffer in memory where disk transfers take place. There may be multiple DTAs of varying sizes but only one may be active at any time. If no DTA is established by a program, DOS sets up a 128-byte default DTA in the program segment prefix (PSP) of the running program. ─────────────────────────────────────────────────────────────────────────── Function ver--get the DOS major and minor version numbers Synopsis int ver() Description Gets the DOS version major and minor numbers. Return The ver() function returns the DOS major version number in the low byte (bits 0-7) and the minor version number in the high byte (bits 8-15). Notes These values duplicate the values in the global _osmajor and _osminor variables supported by the Microsoft C Compiler. They are here for use with compilers that support the bdos() function but not the global version variables. ═══════════════════════════════════════════════════════════════════════════ SCREEN-BUFFER LIBRARY ─────────────────────────────────────────────────────────────────────────── The screen-buffer library routines are described in Chapter 12. The routines are used to form a display image in an off-screen buffer and to copy the image in the buffer to display memory. ─────────────────────────────────────────────────────────────────────────── Function sb_box--draw a box around a window Synopsis #include <local\sbuf.h> #include <local\box.h> int sb_box(win, type, attr) struct REGION *win; /* target window */ short type; /* line drawing type */ unsigned char attr; /* video attribute */ Description Draws a box shape around a rectangular region (defined by win) in the screen buffer. Types are summarized in the following table: ═══════════════════════════════════════════════════════════════════════════ Type Description ─────────────────────────────────────────────────────────────────────────── 0 Default type: + for corners, | for vertical edges, and - for horizontal edges 1 Single lines all around 2 Double lines all around 3 Single horizontal and double vertical lines 4 Double horizontal and single vertical lines 5 Block shapes for all lines and corners ─────────────────────────────────────────────────────────────────────────── Return SB_OK ─────────────────────────────────────────────────────────────────────────── Function sb_fill--fill the scrolling region of a window sb_filla--fill with an attribute only sb_fillc--fill with a character only Synopsis #include <local\sbuf.h> extern struct BUFFER Sbuf; extern union CELL Scrnbuf[SB_ROWS][SB_COLS]; int sb_fill(win, ch, attr) int sb_filla() int sb_fillc() struct REGION *win; /* target window */ unsigned char ch; /* character */ unsigned char attr; /* video attribute */ Description These three functions fill the scrolling region of a window (the entire window if not set explicitly). The sb_fill() function takes both a character and an attribute as parameters. The sb_filla() function sets all cells to a common video attribute while leaving the character in each cell undisturbed. And sb_fillc() sets all cells to a common character value while leaving the attribute in each cell undisturbed. Return SB_OK ─────────────────────────────────────────────────────────────────────────── Function sb_init--initialize the buffered-screen interface Synopsis int sb_init() Description Sets up the Sbuf buffer control structure and initializes the flag bits and line variables. The SB_DIRECT bit is set to a logical 1 if the DOS variable UPDATEMODE is set to DIRECT. Return SB_OK if the interface can be initialized and SB_ERR if not (due to a bad update mode specification). ─────────────────────────────────────────────────────────────────────────── Function sb_move--locate the cursor within a window Synopsis #include <local\sbuf.h> extern struct BUFFER Sbuf; extern union CELL Scrnbuf[SB_ROWS][SB_COLS]; int sb_move(win, r, c) struct REGION *win; /* target window */ register short r, c; /* row and column */ Description The cursor is moved to the specified window-relative row and column (r, c). The appropriate data structures are updated to reflect the change. Return SB_OK if the cursor location is valid for the window or SB_ERR if either r or c is an invalid value. ─────────────────────────────────────────────────────────────────────────── Function sb_new--establish a window (screen-buffer region) Synopsis #include <local\sbuf.h> struct REGION *sb_new(top, left, height, width) int top; /* top row */ int left; /* left column */ int height; /* total rows */ int width; /* total columns */ Description This function establishes a rectangular region of the screen buffer as a window, defined by the upper left corner position and the height and width values. The scrolling region is initially set to the window values, but may be altered by a call to sb_set_scrl(). Return A pointer to a newly allocated window structure or NULL if the window could not be established. ─────────────────────────────────────────────────────────────────────────── Function sb_putc--put a character into a window sb_puts--put a string into a window Synopsis #include <local\sbuf.h> extern struct BUFFER Sbuf; extern union CELL Scrnbuf[SB_ROWS][SB_COLS]; int sb_putc(win, ch) int sb_puts(win, s) struct REGION *win; /* target window */ char ch; unsigned char *s; /* text string */ Description The sb_putc() function puts the specified character into the screen- buffer array at the current window position and advances the window "cursor." If the character is a newline, the remainder of the current window row is cleared and the cursor advances to the first position of the next row. If scrolling is enabled and is required to keep the cursor inside the window, sb_scrl() is called and the cursor lands in the first position of the last window row. A call to sb_puts is treated as a call to sb_putc for each character in the string. A tab is expanded to spaces using a series of calls to sb_putc(). Expansion is limited to the current window row. Return SB_OK or SB_ERR if an error occurs. ─────────────────────────────────────────────────────────────────────────── Function sb_ra--read attribute sb_rc--read character sb_rca--read character and attribute Synopsis #include <local\sbuf.h> extern struct BUFFER Sbuf; extern union CELL Scrnbuf[SB_ROWS][SB_COLS]; unsigned char sb_ra(win) unsigned char sb_rc(win) unsigned short sb_rca(win) union REGION *win; /* target window */ Description Each of these functions is passed a window pointer and window-relative row and column values of a cell, and returns information about the specified cell. The sb_ra() function obtains only the video attribute; sb_rc() obtains only the character value. However, sb_rca() gathers both the character and the video attribute of the specified cell. Return The sb_ra() and sb_rc() functions return a byte that contains the attribute or character at the current window cursor position. A word containing both the character and attribute is returned by sb_rca(). ─────────────────────────────────────────────────────────────────────────── Function sb_scrl--scroll a window region sb_set_scrl--change the defined scrolling region Synopsis #include <local\sbuf.h> extern struct BUFFER Sbuf; extern union CELL Scrnbuf[SB_ROWS][SB_COLS]; int sb_scrl(win, n) int sb_set_scrl(win, top, left, bottom, right) union REGION *win; /* target window */ short top, left; /* upper left corner */ short bottom, right; /* lower right corner */ short n; /* number of rows to scroll */ Description If n is greater than 0, sb_scrl() scrolls the specified window down by n rows. A negative n causes upward scrolling. Vacated lines are filled with spaces in the prevailing attribute. If n equals 0, the entire scrolling region is set to spaces. Scrolling occurs within a window's scrolling region. The sb_set_scrl() function defines the scrolling region, which may be any size up to the full window size. Return SB_OK. If an illegal scrolling region is specified, SB_ERR is returned by sb_set_scrl(). ─────────────────────────────────────────────────────────────────────────── Function sb_show--copy the screen buffer to display memory Synopsis #include <local\sbuf.h> extern struct BUFFER Sbuf; extern union CELL Scrnbuf[SB_ROWS][SB_COLS]; int sb_show(pg) short pg; Description The screen-buffer array is copied to display memory by sb_show(), which uses either BIOS routines or direct display memory accesses, depending on the value of the variable UPDATEMODE (BIOS or DIRECT) in the DOS environment. Return SB_OK ─────────────────────────────────────────────────────────────────────────── Function sb_wa--write an attribute sb_wc--write a character sb_wca--write a character and attribute Synopsis #include <local\sbuf.h> extern struct BUFFER Sbuf; extern union CELL Scrnbuf[SB_ROWS][SB_COLS]; int sb_wa(win, attr, n) int sb_wc(win, ch, n) int sb_wca(win, ch, attr, n) union REGION *win; /* target window */ unsigned char ch; /* character */ unsigned char attr; /* video attribute */ short n; /* number of repetitions */ Description These functions place characters and attributes in the screen-buffer array. The window cursor position is not changed. The repetition number specifies the number of buffer cells that are affected. Return SB_OK if the write is successful or SB_ERR if an error occurs. Notes These functions are valid only within the current row. Behavior is undefined if writes are attempted outside the boundaries of the specified window. ═══════════════════════════════════════════════════════════════════════════ UTILITY LIBRARY ─────────────────────────────────────────────────────────────────────────── The development of the utility library starts in Chapter 3 and continues throughout the book. These routines are usable in a variety of programming situations and are not easily classified in any of the foregoing categories. ─────────────────────────────────────────────────────────────────────────── Function beep--issue a standard terminal beep (Ctrl-G) Synopsis void beep() Description Call beep() to sound the PC's internal speaker. ─────────────────────────────────────────────────────────────────────────── Function byte2hex--convert a byte value to hexadecimal Synopsis char *byte2hex(data, buf) unsigned char data; /* 1-byte data item */ char *buf; /* hex string buffer */ Description The byte2hex() function converts a 1-byte numeric value to a 2-byte hexadecimal representation. Return A pointer to the resulting hexadecimal string. Notes The calling function must provide a buffer that is large enough to receive the 2-byte string and the terminating null byte. ─────────────────────────────────────────────────────────────────────────── Function clrprnt--clear printer to default settings Synopsis #include <local\printer.h> int clrprnt(fout) FILE *fout; Description The clrprnt() function sends codes needed to set an attached printer back to its power-on default values for the major print modes. It does so by individually clearing each mode rather than sending a printer reset command to avoid "paper creep" and alteration of the top-of-form setting. Return SUCCESS if all goes well or FAILURE if any attempt at writing to the output stream fails. ─────────────────────────────────────────────────────────────────────────── Function fatal--print an error message and exit Synopsis void fatal(pname, str, errlvl) char *pname; char *str; int errlvl; Description If an error occurs in a program, fatal() can be called to display an error message and then exit with a status (ERRORLEVEL in DOS terms) other than 0 to indicate an error. The usual error code is 1, but other values can be used if a program can fail in more ways than one. ─────────────────────────────────────────────────────────────────────────── Function fcopy--copy input file to output file Synopsis int fcopy(fin, fout) FILE *fin, *fout; Description This function copies an input stream (FILE *) to an output stream (FILE *) using the standard library functions fgets() and fputs() and a private buffer of BUFSIZ bytes. The ferror() macro is used to check for input errors and testing is done for the unambiguous EOF on the output stream. Return A successful file copy operation produces a 0 return value. Any input or output error that is detected causes a nonzero return. ─────────────────────────────────────────────────────────────────────────── Function fixtabs--set fixed-interval tab stops Synopsis void fixtabs(interval) int interval; /* tabbing interval */ Description A set of fixed tab stops can be set using fixtabs() to initialize the private Tabstops array and then set tab stops at the specified intervals. Internally, the Tabstops array has tab stops at column 0 and repeating at the specified interval. Standard terminal usage has an interval of 8 columns. ─────────────────────────────────────────────────────────────────────────── Function getname--extract filename[.ext] from a pathname Synopsis char *getname(path) char *path; Description This function extracts a full filespec (filename[.ext]) from a pathname. It checks to see that the pathname given as a parameter is a valid pathname. Path separators of \ and / are accepted and may be intermixed. Return A pointer to a valid filespec or NULL if the path parameter is not a valid pathname. ─────────────────────────────────────────────────────────────────────────── Function getopt--get option letters and option arguments Synopsis extern int optind; extern int opterr; extern char *optarg; int getopt(argc, argv, opts) int argc; /* argument count */ char *argv[]; /* argument vector array */ char *opts; /* option string */ Description The string variable opts is a list of recognized option letters. Option letters that are followed by a colon are expected to take an argument. On each successive call to getopt(), the function returns the next option letter in argv that matches a letter in opts. The optarg variable points to an option argument, if any is expected and found or NULL otherwise. When all options have been processed, getopt() returns EOF. The special option "--" (double dash) may be used to mark the end of options. When found, this causes getopt() to skip the special option and return EOF. Return If an option letter in argv is not found in the opts string, getopt() returns a question mark and prints an error message. Setting opterr to 0 silences getopt(). Notes This getopt() is the public domain version that is provided by the AT&T UNIX System Toolchest. It is presented in this book with the permission of AT&T in the interest of promoting a common command-line interface for programs. ─────────────────────────────────────────────────────────────────────────── Function getpname--extract a program name from a pathname Synopsis void getpname(path, pname) char *path; /* full or relative pathname */ char *pname; /* filename part of program name */ Description The getpname() function receives a full or relative pathname. It strips off any leading path information and any trailing extension. This function accepts both \ and / as path separators. It does not check to see that the path parameter is a valid path. ─────────────────────────────────────────────────────────────────────────── Function getxline--get an expanded line of text Synopsis char *getxline(buf, size, fin) char *buf; /* output buffer */ int size; /* maximum number of bytes */ FILE *fin; /* input stream */ Description The getxline() function receives a line of text as input and "expands" the line by converting each tab to the correct number of spaces. The total character count may thus be altered, but the expanded line appears to be visually identical to the input line when displayed. Return A pointer to the buffer that contains the expanded line or NULL if an error occurs. Notes This function queries the tabstop array, so you must first call either fixtabs() or vartabs() to set tabs. ─────────────────────────────────────────────────────────────────────────── Function fconfig--get pointer to a configuration file Synopsis FILE *fconfig(varname, fname) char *varname; /* DOS environment variable name */ char *fname; /* file name */ Description This function looks for a configuration file by the name fname. It looks first in the current directory and then in a directory pointed to by the varname DOS variable. Return A pointer to the configuration file if one is found or a NULL pointer if not. ─────────────────────────────────────────────────────────────────────────── Function last_ch--get the last character of a string Synopsis char last_ch(s) char *s; /* source string */ Description The last_ch() function finds the last character of the source string, s (just before the NUL termination). Return The character value or -1 if the string is empty. ─────────────────────────────────────────────────────────────────────────── Function lines--send blank lines to an output stream Synopsis int lines(n, fp) int n; /* number of repetitions */ FILE *fp; /* output stream */ Description The lines() function places n newline characters on the output stream. Return The number of newlines actually emitted, which may be less than the number requested if an error occurs on the output stream. ─────────────────────────────────────────────────────────────────────────── Function memchk--check for physical memory at an address Synopsis int memchk(seg, os) unsigned int seg; /* segment */ unsigned int os; /* offset */ Description By sequentially writing and reading the memory location specified by the segmented address, memchk() attempts to determine whether any physical memory is installed. To prevent clobbering needed memory values, the original value is preserved and restored upon completion of the test. Return If active memory is found at the specified address, memchk() returns a 1. If no active memory is found, 0 is returned. ─────────────────────────────────────────────────────────────────────────── Function mkslist--create a selection list (lookup table) Synopsis extern long Highest; int mkslist(list) char *list; /* pointer to a list in string form */ Description The mkslist() function extracts tokens from a string representation of a list of numbers, converts the tokens to numeric values, and stores the values as a set of numeric ranges in an array (up to 10 ranges permitted by the current design). Single numbers are represented as ranges having the same starting and ending number. Open-ended ranges (for example, 3-) are represented as the starting number to some unreasonably high ending value (BIGGEST). The list of ranges is terminated by a -1 starting value in the last array element following the last valid range. Return Always zero. ─────────────────────────────────────────────────────────────────────────── Function nlerase--erase a newline in a string Synopsis char *nlerase(s) char *s; Description The nlerase() function scans a string and replaces the first newline it finds with a NUL (\0) character, effectively terminating the string and erasing the newline. Return A pointer to the modified string. ─────────────────────────────────────────────────────────────────────────── Function selected--determine whether a number is in a range Synopsis int selected(n) long n; /* number to test */ Description The selected() function queries the select-list array, Slist, which is established by mkslist(), to determine whether the number parameter is a member of one of the ranges in the list. Return Returns 1 if the number is in one of the ranges and 0 otherwise. ─────────────────────────────────────────────────────────────────────────── Function setfont--select a printer font Synopsis #include <local\printer.h> int setfont(ftype, fout) int ftype; /* font specifier */ FILE *fout; /* output stream */ Description This function is used to select a printer font type. The standard font is a 10 cpi (characters per inch) type and it can be obtained by list calling clrprnt(). The special types are chosen from the following list (based on Epson MX/FX-series printer codes): ─────────────────────────────────────────────────────────────────────────── Symbolic Name Description ─────────────────────────────────────────────────────────────────────────── CONDENSED A small but very readable type at about 14 cpi (136 characters per line) DOUBLE Double strike EMPHASIZED Emboldened by microspacing and restriking EXPANDED Wider than normal characters (6 cpi) ITALICS True italic characters (not supported by all Epson- compatible printers) UNDERLINE Continuous underline (without the need to backspace and restrike the character) ─────────────────────────────────────────────────────────────────────────── Return The setfont() function returns SUCCESS to indicate apparent success, or FAILURE if an error occurs or an illegal font combination is requested. Notes The CONDENSED font cannot be used with either DOUBLE or EMPHASIZED on most Epson-compatible printers, so such combinations are disallowed. ─────────────────────────────────────────────────────────────────────────── Function setprnt--install printer codes Synopsis #include <local\printer.h> int setprnt() Description This function installs printer codes from printer configuration files or from internal defaults (for Epson MX/FX series and compatible printers). Return The setprnt() function returns SUCCESS to indicate apparent success, or FAILURE if an error occurs. The only detectable failures are too many or too few lines in a configuration file. ─────────────────────────────────────────────────────────────────────────── Function spaces--send spaces to an output stream Synopsis int spaces(n, fp) int n; /* number of repetitions */ FILE *fp; /* output stream */ Description The spaces() function places n space (blank) characters on the output stream. Return The number of spaces actually emitted, which may be less than the number requested if an error occurs on the output stream. ─────────────────────────────────────────────────────────────────────────── Function tabstop--determine whether col is a tab stop Synopsis int tabstop(col) register int col; Description The tabstop() function queries the private Tabstops array to determine whether the specified column, col, is a tab stop. Return A nonzero value if col is a tab stop or 0 if it is not. ─────────────────────────────────────────────────────────────────────────── Function vartabs--set variable tabs from a list Synopsis void vartabs(list) int *list; /* pointer to an array of tab stops */ Description A set of tab stops can be set from a list using vartabs() to initialize the private Tabstops array and then set the specified tabs. ─────────────────────────────────────────────────────────────────────────── Function word2hex--convert a word value to hexadecimal Synopsis char *word2hex(data, buf) unsigned short data; /* 2-byte data item */ char *buf; /* hex string buffer */ Description The word2hex() function converts a 2-byte numeric value to a 4-byte hexadecimal representation. Return A pointer to the resulting hexadecimal string. Notes The calling function must provide a buffer that is large enough to receive the 4-byte string and the terminating null byte. ─────────────────────────────────────────────────────────────────────────── Augie Hansen Augie Hansen started programming on IBM mainframes more than 20 years ago and since then has been involved with computers and programming at various companies, including General Dynamics, Raytheon Company, and E.G. & G., Inc. In addition, Augie spent 7 years with AT&T Bell Laboratories, specializing in UNIX and C programming. He founded and is the president of Omniware, a company that provides academic and commercial training courses on UNIX, C, and MS/PC-DOS and custom programming consulting. Augie is a contributing editor of PC Tech Journal and has written one other book, vi--The UNIX Screen Editor, published in 1986 by Brady Books/Prentice-Hall Press. FIGURE 6-2 ▐ Manual page for CAT ─────────────────────────────────────────────────────────────────────────── NAME CAT--concatenate file FORMAT cat [ -s ] [ d: [ path [ filename [ .ext] ] ] ... ] DESCRIPTION The CAT command accepts the -s option (silent), which tells the program not to complain about missing files (this may be useful in batch files). If no filenames are specified, CAT reads from the standard input. DOS wildcard characters (? and *) may be used to specify ambiguous filenames. EXAMPLES Display the contents of a single file. cat hello.c Concatenate all C source files in the current directory into a single source file. cat *.c >program.c Create a new file with text typed by the user. cat >myfile.txt This is a test. ^Z FIGURE 6-3 ▐ Manual page for TIMER ─────────────────────────────────────────────────────────────────────────── NAME TIMER--provide timing data for up to four events SYNOPSIS timer [-efs#] DESCRIPTION TIMER uses command-line options to select program actions. The option letters may be combined following a single option flag (-) or invoked separately. If the f option is combined with other options, it must be last. These options are honored by TIMER: ══════════════════════════════════════════════════════════════════════ Option Meaning ────────────────────────────────────────────────────────────────────── -s Start (or restart) a timer -e Display or record elapsed time -f file Record the output of the TIMER command in file -# The # symbol is a numeric parameter in the range of 0 to 3 that selects one of the four timers. If no number is specified, TIMER uses 0 by default. ────────────────────────────────────────────────────────────────────── EXAMPLES Start the default timer: timer -s Restart timer 0 and record the output in the file project.dat: timer -s -f project.dat NOTES TIMER uses the intra-application communication area to hold starting times for each of the timers. If another program uses the same memory locations, timer data could be corrupted. When asked to produce an elapsed time, TIMER tries to detect corrupt data and outputs an error message rather than a time value. FIGURE 7-1 ▐ Manual page for MX ─────────────────────────────────────────────────────────────────────────── NAME MX--control printer modes SYNOPSIS mx -option(s) DESCRIPTION The MX program sends mode-setting control strings to a printer under control of options. Most of the modes may be set individually or in combinations of two or more. It should be obvious that normal (-n) should be used by itself. Less obvious is that condensed (-c) and either bold (-b) or double-strike (-d) cannot be used together. Within the limitations noted above, options listed below may be used singly or combined in any order: ═══════════════════════════════════════════════════════════════════════════ Option Meaning ────────────────────────────────────────────────────────────────────── -b Select bold (emphasized) mode -c Select compressed mode -d Select double-strike mode -e Select expanded mode -i Select italic font -n Select normal font. This command option clears all special font and print-mode selections. -o file Use the specified output file or stream -p Preview output on screen (may be redirected) -r Issue a hardware reset command. This clears all attributes and establishes the current position as the new top-of-form reference. -t Eject a page (top-of-form command) by issuing a formfeed -u Select underline mode ______________________________________________________________________ The reset (-r) and top-of-form (-t) options have temporal priority over any other options invoked in the same call to MX. Reset is done first, then formfeed, then font selection. Printer configuration can be controlled via optional local and global configuration files (local overrides global). EXAMPLES Request compressed and italicized printing: mx -ci Eject a page: mx -t FIGURE 7-2 ▐ Manual page for PRTSTR ─────────────────────────────────────────────────────────────────────────── NAME PRTSTR--print string(s) on standard printer SYNOPSIS prtstr [options ] [ string ... ] DESCRIPTION Use PRTSTR to send a string or group of strings given as arguments to the standard printer device (stdprn). PRTSTR appends one space after each argument and issues a newline to terminate the line. Use quotes to protect embedded special characters, such as tabs or spaces, in the text-argument list. The following options may be used separately or together to alter the default behavior: ══════════════════════════════════════════════════════════════════════ Option Meaning ────────────────────────────────────────────────────────────────────── -n Suppress newline and trailing space. -p Preview output on screen (may be redirected). ────────────────────────────────────────────────────────────────────── EXAMPLES Send the line C is a fantastic language! to the standard printer device (notice that no quotes are needed): prtstr C is a fantastic language! Send the string BASEBALL to a file: prtstr -p BASEBALL > baseball.txt Print some text and stop on the same line: prtstr -n "This is a test: " FIGURE 8-1 ▐ Manual page for TOUCH ─────────────────────────────────────────────────────────────────────────── NAME TOUCH--update file modification time(s) SYNOPSIS touch [-cv] file ... DESCRIPTION The TOUCH command updates the file modification times associated with a file or files. Under DOS, the last modification time (and last access time for DOS version 3.00 and later) maintained in the directory entry for a file are identical. TOUCH sets the file time to the current DOS time. TOUCH accepts the following command-line options, singly or in combination: ══════════════════════════════════════════════════════════════════════ Option Meaning ────────────────────────────────────────────────────────────────────── -c Control file creation. TOUCH usually creates a named file if it does exist. This option tells TOUCH not to create files. -v Verbose mode. Tells TOUCH to send information to the standard error stream about file times that have been successfully updated, about files that were created, and so forth. ────────────────────────────────────────────────────────────────────── EXAMPLES Update the modification times of all C source files in the current directory and tell the user what's going on: touch -v *.c Create a set of empty files in the current directory (assumes these files do not exist yet): touch file1.c file2.c file3.c FIGURE 8-2 ▐ Manual page for TEE ─────────────────────────────────────────────────────────────────────────── NAME TEE--split a stream into multiple streams SYNOPSIS tee [-a] [file ... ] DESCRIPTION TEE copies its standard input onto its standard output. If any files are named, they too become destinations for the output of TEE. The files are created if necessary. If they already exist, their prior contents are lost unless the -a option (append) is given on the command line. EXAMPLES Display the contents of a file (FILE1) and simultaneously copy it to another file (FILE2): type file1 tee file2 Use CAT to display the file timer.c on the console and append a copy of the output to two existing files (SRCFILE1 and SRCFILE2): cat timer.c tee -a srcfile1 srcfile2 NOTES TEE does not work with files that contain binary data. As designed, it handles only ASCII text. The number of destination files is limited by the operating system and by the use of the value _NFILE in the stdio.h header file (_NFILE is typically 20). There are five opened files (stdin, stdout, stderr, stdaux, and stdprn) when a program starts executing, which reduces the number of files you can open. FIGURE 8-3 ▐ Manual page for PWD ─────────────────────────────────────────────────────────────────────────── NAME PWD--print working directory SYNOPSIS pwd DESCRIPTION PWD displays the full pathname of the current ("working") directory. It is designed to ease the transition between UNIX/XENIX and DOS. It provides the same function as the DOScommand CD if CD is typed without a pathname argument. EXAMPLE Display the current directory pathname: pwd NOTES Under UNIX and XENIX, the CD command typed without a pathname argument moves the user's context to the "home" directory, which might surprise an experienced DOS user trying to get the current pathname by the standard technique. FIGURE 8-4 ▐ Manual page for RM ─────────────────────────────────────────────────────────────────────────── NAME RM--remove file(s) SYNOPSIS rm [-i] file ... DESCRIPTION RM removes a file or a group of files. Each file specification may be a full or relative pathname and may contain wildcards to name files ambiguously. The -i option causes RM to operate in an interactive mode. The program prompts the user to confirm each removal before it is executed. A response that starts with y or Y for "yes" confirms the removal. Any other initial character is interpreted as a "no" response. EXAMPLES Remove all backup files in the current directory: rm *.bak Remove object files and "map" files in the current directory interactively: rm -i *.obj *.map FIGURE 8-5 ▐ Manual page for LS ─────────────────────────────────────────────────────────────────────────── NAME LS--list information about a directory SYNOPSIS ls [-aCFlrt] [filespec] DESCRIPTION The LS command is a general-purpose directory lister. It has enough features to be useful without being threateningly complex. The most common use of LS is to find out what files are in the current directory. This requires no argument on the command line. To get greater amounts of detail or to modify the output of LS in some way, use one or more of the following options separately or grouped in any meaningful combination. ══════════════════════════════════════════════════════════════════════ Option Meaning ────────────────────────────────────────────────────────────────────── -a All files in the named directory are listed, even those marked hidden or system. The default is to shield hidden and system files from view. -C Produce multi-column output with items sorted down each column. Without this option, single-column output is employed. This option causes output to be in the largest number of columns possible (determined by the length of the longest item name). -F Show file type in the output listing. Directories are marked by a trailing backslash (mydir\). -l Produce a single-column "long" listing, including a summary of mode bits, file date and time stamp, and file size in bytes. This option overrides the -C and -F options. -r Reverse the sorting order. Works for the default sorting of file and directory names and for the sort on file modification time data (see -t option). -t Sort by file time rather than name. The default is oldest first, but most-recent-first may be obtained by combining this option with -r. ────────────────────────────────────────────────────────────────────── EXAMPLES Display a long list of the current directory: ls -l Display a multi-column listing of the root directory on the current disk from anywhere in the directory hierarchy: ls -C \ FIGURE 9-1 ▐ Manual page for PR ─────────────────────────────────────────────────────────────────────────── NAME PR--print file(s) SYNOPSIS pr [ options ] [ file ... ] DESCRIPTION The PR program takes a list of filenames and sends the contents of each in turn to the standard output. Formatting of the output "pages" is controlled via built-in defaults and may be modified by external configuration files and command-line options. If no filenames are specified, PR reads from its standard input (usually the keyboard, unless input is redirected). Each page starts with a header composed of the filename, the file- relative page number, and the file's modification date and time. When reading from the standard input, the filename is omitted and the current date and time are used. Long lines are folded onto the next line rather than being truncated. The line count is not affected by this. PR continues to track the number of logical lines in the source file, not the number of physical lines printed. The options listed below may be used singly or combined in any order. ══════════════════════════════════════════════════════════════════════ Option Action ────────────────────────────────────────────────────────────────────── -e Toggle the Epson-compatible printer mode -f Use a formfeed to eject a page (the default is spaces) -h hdr Replace the filename part of the header with the text given in hdr (must be quoted if it contains white space) -l len Set the page length to len lines (the default is 66) -n Enable the line-numbering feature (the initial setting is off) -o cols Set offset to cols columns from left edge of the paper -p Preview output on screen (may be redirected) -s list Output only those lines selected by the comma-separated list (must be quoted if it contains any white space) -w cols Set the output line width to cols columns ────────────────────────────────────────────────────────────────────── Program configuration may be controlled via optional local and global configuration files (local overrides global). Most settings established by configuration files may be altered by the user via the command-line arguments listed above. The following listing (comments are optional--only the numbers and strings at the beginning of each line are required) is the default global configuration file, which, if it exists, must reside in a subdirectory pointed to by the CONFIG environment variable: 2 top1 2 top2 3 bottom 132 width 5 left margin 3 right margin 66 lines per page 6 lines per inch 1 printer mode (Epson) 1 line number enabled 1 use formfeeds 8 standard tabs PRN output destination EXAMPLES Print all of the C source files in the current directory, with linenumbering turned on, to an Epson printer attached to the standard printer port: pr -en *.c Display the contents of the \include\std.h header file with an offset of 10 columns and a text file: pr -o10 \include\std.h Print the file myprog.pas on the default printer starting at page 4 and continuing up to and including page 10: pr -s4,10 myprog.pas FIGURE 10-1 ▐ Manual page for DUMP ─────────────────────────────────────────────────────────────────────────── NAME DUMP--dump file in hexadecimal and text formats SYNOPSIS dump [ -sv] [file ... ] DESCRIPTION The DUMP program is a stand-alone program that can be used as a filter. It receives a stream of data and transforms it into a combined hexadecimal and text output stream. Each line of output contains three fields: an offset from the start of the incoming stream; a hexadecimal display of a 16-byte block of data; and a text representation of the same block of bytes. The output of DUMP contains non-ASCII characters that may confuse printers and other output devices. The -s option causes these to be stripped out of the output stream and replaced by dots (.). When this option is used, the output of DUMP may be safely sent to any other program that can read from its standard input, and to any device that can accept an ASCII text stream. The -v option tells DUMP to be verbose. For each file given as a command-line argument, DUMP outputs a blank line, then the name of the file being dumped, and then moves to a new line before outputting the formatted file dump. When the standard input is the data source, the verbose option is ignored. EXAMPLES Display the converted contents of hex.obj on the screen: dump hex.obj Print the converted contents of PROG.COM: dump prog.com > prn FIGURE 10-3 ▐ Manual page for SHOW ─────────────────────────────────────────────────────────────────────────── NAME SHOW--make all characters in a stream visible SYNOPSIS show [-svw] [file ... ] DESCRIPTION The SHOW program is a stand-alone program that can be used as a filter. It receives a stream of data and transforms it into a straight ASCII output stream. Normal displayable characters pass through unchanged, but most nonprintable characters are converted to a two- digit hexadecimal form. The -s option strips all control codes and IBM extended ASCII characters from the text stream, except for the primary format effectors (tab and newline). The -v option tells SHOW to be verbose. When the -w (word-processing) option is used, a carriage return that is not paired with a newline is assumed to be a "soft" return and is replaced by a newline. The -w option also causes SHOW to convert all extended codes (eighth bit on) to 7-bit ASCII and outputs those whose converted values fall into the displayable ASCII range. EXAMPLES Display the contents of a spreadsheet data file: show data.wks Convert a word processor's formatted document file to straight ASCII text and save output in a file: show -w letter.doc >letter.txt FIGURE 13-4 ▐ Manual page for SetColor ─────────────────────────────────────────────────────────────────────────── NAME SC--control video attributes SYNOPSIS sc [ attribute ] sc [ foreground [ background [ border ] ] ] DESCRIPTION The SetColor program may be used in either batch mode or interactive mode to set the foreground, background, and border attributes of a color display system. The interactive mode, invoked by typing SC with no arguments, uses on-screen instructions to guide the user in selecting attributes via function keys. The display is updated with each keypress to reflect the current selections. The attribute selections in batch mode can be formed from the following list of argument values. Only the first three letters are significant and case is not relevant. ══════════════════════════════════════════════════════════════════════ Values For Values For Foreground, Attribute Background and Border ────────────────────────────────────────────────────────────────────── Normal Black Red Reverse Blue Magenta Green Brown Cyan White ────────────────────────────────────────────────────────────────────── All color specifications can be modified by prefixing bold, bright, or light to obtain high-intensity values of the base color. Yellow may be used as a synonym for bold brown. If "blink" is enabled (the default), selecting a high-intensity background will cause the background to be a low-intensity color and the foreground will blink. EXAMPLES Run SetColor in the interactive mode: sc Request bright white on a blue background with a cyan border: sc bold white blue cyan Set up a reverse video screen: sc reverse NOTES The ANSI.SYS device driver must be loaded into memory. This requires DOS version 2.00 or later and the line device=ansi.sys in the CONFIG.SYS file. The border cannot be set on some machines, notably the AT&T PC6300. Also, the ANSI.SYS device driver supplied with MS-DOS version 2.11 erases to Normal attribute (white on black) regardless of the specified attribute. However, displayed characters written after the erasure will have the specified attributes. FIGURE 14-1 ▐ Manual page for ViewFile ─────────────────────────────────────────────────────────────────────────── NAME VF_a full-screen file-viewing program SYNOPSIS vf [-n] file ... DESCRIPTION ViewFile is a file-viewing program that features fast vertical and horizontal scrolling through any text file. VF uses the PC arrow and special-purpose keys to move around quickly and easily in a file. Most commands have single-letter synonyms. Absolute go-to-line and search-for-string commands may also be used to seek a position in the file being viewed. Line-numbering is optional; it can be turned on from the command line by using the -n option. Numbering can also be toggled on and off while VF is running by using the N key. The following commands (and synonyms) are understood by VF: ══════════════════════════════════════════════════════════════════════ COMMAND MEANING ────────────────────────────────────────────────────────────────────── PgUp (U) Scroll up the file one screen page PgDn (D) Scroll down the file one screen page Up arrow (-) Scroll up in the file one line Down arrow (+) Scroll down in the file one line Right arrow (>) Scroll right by 20 columns Left arrow (<) Scroll left by 20 columns Home (B) Go to beginning of file buffer End (E) Go to end of file buffer Alt-g (G) Go to a specified line in the buffer Alt-h (H or ?) Display the help frame Alt-n (N) Toggle line-numbering feature \ (R) Reverse search for a literal string / (S) Search forward for a literal string Esc Next file from list (quits if none) Alt-q (Q) Quit ────────────────────────────────────────────────────────────────────── This information is also available on-line in the built-in ViewFile help frame. EXAMPLES "View" sequentially all of the C source files in the current directory: vf -n *.c std.h ─────────────────────────────────────────────────────────────────────────── /* * std.h */ /* data type aliases */ #define META short #define UCHAR unsigned char #define UINT unsigned int #define ULONG unsigned long #define USHORT unsigned short /* Boolean data type */ typedef enum { FALSE, TRUE } BOOLEAN; /* function return values and program exit codes */ #define OK 0 #define BAD 1 #define SUCCESS 0 #define FAILURE 1 /* infinite loop */ #define FOREVER while (1) /* masks */ #define HIBYTE 0xFF00 #define LOBYTE 0x00FF #define ASCII 0x7F #define HIBIT 0x80 /* lengths */ #define MAXNAME 8 #define MAXEXT 3 #define MAXLINE 256 #define MAXPATH 64 /* special number */ #define BIGGEST 65535 replay ─────────────────────────────────────────────────────────────────────────── /* * replay -- echo the command-line arguments * to standard output */ #include <stdio.h> #include <stdlib.h> #include <local\std.h> main(argc, argv) int argc; char **argv; { int i; char **p; static char pgm[MAXNAME + 1] = { "replay" }; void getpname(char *, char *); /* get program name from DOS (version 3.00 and later) */ if (_osmajor >= 3) getpname(*argv, pgm); /* check for arguments */ if (argc == 1) exit(1); /* none given */ /* echo the argument list, one per line */ p = argv; printf("%s arguments:\n\n", pgm); for (--argc, ++argv; argc > 0; --argc, ++argv) printf("argv[%d] -> %s\n", argv - p, *argv); exit(0); } /* end main() */ getpname ─────────────────────────────────────────────────────────────────────────── /* * getpname -- extract the base name of a program from the * pathname string (deletes a drive specifier, any leading * path node information, and the extension) */ #include <stdio.h> #include <ctype.h> void getpname(path, pname) char *path; /* full or relative pathname */ char *pname; /* program name pointer */ { char *cp; /* find the end of the pathname string */ cp = path; /* start of pathname */ while (*cp != '\0') ++cp; --cp; /* went one too far */ /* find the start of the filename part */ while (cp > path && *cp != '\\' && *cp != ':' && *cp != '/') --cp; if (cp > path) ++cp; /* move to right of pathname separator */ /* copy the filename part only */ while ((*pname = tolower(*cp)) != '.' && *pname != '\0') { ++cp; ++pname; } *pname = '\0'; } showenv ─────────────────────────────────────────────────────────────────────────── /* * showenv -- display the values of any DOS variables * named on the invocation command line */ #include <stdio.h> #include <stdlib.h> #include <string.h> #include <local\std.h> main(argc, argv, envp) int argc; char **argv; char **envp; { register char *ep; static char pgm[MAXNAME + 1] = { "showenv" }; extern void getpname(char *, char *); /* use an alias if one is given to this program */ if (_osmajor >= 3) getpname(*argv, pgm); /* if no arguments, show full environment list */ if (argc == 1) for (; *envp; ++envp) printf("%s\n", *envp); else { /* * treat all args as DOS variable names and * display values of only specified variables */ ++argv; /* skip past command name */ --argc; while (argc > 0) { if ((ep = getenv(strupr(*argv))) == NULL) fprintf(stderr, "%s not defined\n", *argv); else printf("%s=%s\n", *argv, ep); ++argv; --argc; } } exit(0); } setmydir ─────────────────────────────────────────────────────────────────────────── /* * setmydir -- try to change the DOS environment */ #include <stdio.h> #include <stdlib.h> #include <local\std.h> main(argc, argv) int argc; char **argv; { register char **p; static char var[] = { "MYDIR" }; static char pgm[MAXNAME + 1] = { "setmydir" }; extern void fatal(char *, int); extern void getpname(char *, char *); /* use an alias if one is given to this program */ if (_osmajor >= 3) getpname(*argv, pgm); /* try to add the MYDIR variable to the environment */ if (putenv("MYDIR=c:\\mydir") == -1) fatal(pgm, "Error changing environment", 1); /* display the environment for this process */ for (p = environ; *p; p++) { printf("%s\n", *p); } exit(0); } timedata ─────────────────────────────────────────────────────────────────────────── /* * timedata -- time zone and time value tests */ #include <stdio.h> #include <time.h> main() { long now; struct tm *tbuf; /* get TZ data into global variables */ tzset(); /* display the global time values */ printf("daylight savings time flag = %d\n", daylight); printf("difference (in seconds) from GMT = %ld\n", timezone); printf("standard time zone string is %s\n", tzname[0]); printf("daylight time zone string is %s\n", tzname[1]); /* * display the current date and time values for * local and universal time */ now = time(NULL); printf("\nctime():\t%s\n", ctime(&now)); tbuf = localtime(&now); printf("local time:\t%s\n", asctime(tbuf)); tbuf = gmtime(&now); printf("universal time:\t%s\n", asctime(tbuf)); exit(0); } notes1 ─────────────────────────────────────────────────────────────────────────── /* * notes1 -- add an entry to a "notes" text file * * version 1: appends new data to NOTES.TXT in the * current directory -- uses local date/time stamp * as a header for each new entry */ #include <stdio.h> #include <stdlib.h> #include <time.h> #include <local\std.h> main() { FILE *fp; static char notesfile[MAXPATH + 1] = { "notes.txt" }; char ch; long ltime; static char pgm[MAXNAME + 1] = { "notes1" }; extern void fatal(char *, char *, int); /* try to open notes file in current directory */ if ((fp = fopen(notesfile, "a")) == NULL) fatal(pgm, notesfile, 1); /* append a header and date/time tag */ ltime = time(NULL); fprintf(stderr, "Appending to %s: %s\n", notesfile, ctime(<ime)); fprintf(fp, "%s\n", ctime(<ime)); /* append new text */ while ((ch = getchar()) != EOF) putc(ch, fp); /* clean up */ if (fclose(fp)) fatal(pgm, notesfile, 2); exit(0); } notes2 ─────────────────────────────────────────────────────────────────────────── /* * notes2 -- add a date/time stamped entry to a * "notes" data file. Allow user to optionally * edit the data file upon completion of the entry. */ #include <stdio.h> #include <stdlib.h> #include <time.h> #include <signal.h> #include <process.h> #include <local\std.h> /* length of date/time string */ #define DT_STR 26 main(argc, argv) int argc; char **argv; { int n; /* number of lines added */ int exitcode = 0; FILE *fp; static char notesfile[MAXPATH + 1] = { "notes.txt" }; static char editname[MAXPATH + 1] = { "edlin" }; char ch; char dt_stamp[DT_STR]; char *s; long ltime; static char pgm[MAXNAME + 1] = { "notes2" }; extern void fatal(char *, char *, int); extern void getpname(char *, char *); static int addtxt(FILE *, FILE *); if (_osmajor >= 3) getpname(*argv, pgm); /* locate the "notes" database file and open it */ if (argc > 1) strcpy(notesfile, *++argv); else if (s = getenv("NOTESFILE")) strcpy(notesfile, s); if ((fp = fopen(notesfile, "a")) == NULL) fatal(pgm, notesfile, 1); /* disable Ctrl-Break interrupt */ if (signal(SIGINT, SIG_IGN) == (int(*)())-1) perror("Cannot set signal"); /* append a header and date/time tag */ ltime = time(NULL); strcpy(dt_stamp, ctime(<ime)); fprintf(stderr, "Appending to %s: %s", notesfile, dt_stamp); fprintf(fp, "\n%s", dt_stamp); /* add text to notes file */ if ((n = addtxt(stdin, fp)) == 0) { fputs("No new text", stderr); if (fclose(fp)) fatal(pgm, notesfile, 2); exit(0); } else fprintf(stderr, "%d line(s) added to %s\n", n, notesfile); if (fclose(fp)) fatal(pgm, notesfile, 2); /* optionally edit text in the notes file */ fprintf(stderr, "E + ENTER to edit; ENTER alone to quit: "); while ((ch = tolower(getchar())) != '\n') if (ch == 'e') { if (s = getenv("EDITOR")) strcpy(editname, s); if ((exitcode = spawnlp(P_WAIT, editname, editname, notesfile, NULL)) == -1) fatal(pgm, editname, 3); } exit(exitcode); } /* * addtxt -- append new text to notes file */ static int addtxt(fin, fout) FILE *fin, *fout; { int ch; int col = 0; /* column */ int n = 0; /* number of lines added */ while ((ch = fgetc(fin)) != EOF) { if (ch == '.' && col == 0) { ch = fgetc(fin); /* trash the newline */ break; } fputc(ch, fout); if (ch == '\n') { col = 0; ++n; } else ++col; } return (n); } run_once ─────────────────────────────────────────────────────────────────────────── /* * run_once -- run a program one time and then * "hang" the system to prevent unwanted use */ #include <stdio.h> #include <stdlib.h> #include <process.h> #include <local\std.h> main(argc, argv) int argc; char *argv[]; { extern void fatal(char *, *, int); ++argv; /* skip over the program name */ /* run the specified command line [pgmname arg(s)] */ if (spawnvp(P_WAIT, *argv, argv) == -1) fatal("run_once" "Error running specified program", 1); fprintf(stderr, "Please turn off the power to the computer.\n"); FOREVER /* do nothing */ ; } dos.h ─────────────────────────────────────────────────────────────────────────── /* * dos.h * * Defines the structs and unions used to handle the input and output * registers for the DOS interface routines defined in the V2.0 to V3.0 * compatibility package. It also includes macros to access the segment * and offset values of MS C "far" pointers, so that they may be used by * these routines. * * Copyright (C) Microsoft Corporation, 1984, 1985, 1986 */ /* word registers */ struct WORDREGS { unsigned int ax; unsigned int bx; unsigned int cx; unsigned int dx; unsigned int si; unsigned int di; unsigned int cflag; }; /* byte registers */ struct BYTEREGS { unsigned char al, ah; unsigned char bl, bh; unsigned char cl, ch; unsigned char dl, dh; }; /* general purpose registers union - overlays the corresponding word and * byte registers. */ union REGS { struct WORDREGS x; struct BYTEREGS h; }; /* segment registers */ struct SREGS { unsigned int es; unsigned int cs; unsigned int ss; unsigned int ds; }; /* dosexterror struct */ struct DOSERROR { int exterror; char class; char action; char locus; }; /* macros to break MS C "far" pointers into their segment and offset * components */ #define FP_SEG(fp) (*((unsigned *)&(fp) + 1)) #define FP_OFF(fp) (*((unsigned *)&(fp))) /* function declarations for those who want strong type checking * on arguments to library function calls */ #ifdef LINT_ARGS /* argument checking enabled */ #ifndef NO_EXT_KEYS /* extended keywords are enabled */ int cdecl bdos(int, unsigned int, unsigned int); int cdecl dosexterr(struct DOSERROR *); int cdecl intdos(union REGS *, union REGS *); int cdecl intdosx(union REGS *, union REGS *, struct SREGS *); int cdecl int86(int, union REGS *, union REGS *); int cdecl int86x(int, union REGS *, union REGS *, struct SREGS *); void cdecl segread(struct SREGS *); #else /* extended keywords not enabled */ int bdos(int, unsigned int, unsigned int); int dosexterr(struct DOSERROR *); int intdos(union REGS *, union REGS *); int intdosx(union REGS *, union REGS *, struct SREGS *); int int86(int, union REGS *, union REGS *); int int86x(int, union REGS *, union REGS *, struct SREGS *); void segread(struct SREGS *); #endif /* NO_EXT_KEYS */ #else #ifndef NO_EXT_KEYS /* extended keywords are enabled */ int cdecl bdos(); int cdecl dosexterr(); int cdecl intdos(); int cdecl intdosx(); int cdecl int86(); int cdecl int86x(); void cdecl segread(); #else /* extended keywords not enabled */ void segread(); #endif /* NO_EXT_KEYS */ #endif /* LINT_ARGS */ doslib.h ─────────────────────────────────────────────────────────────────────────── /* * doslib.h */ /* DOS interrupts */ #define PGM_TERMINATE 0x20 #define BDOS_REQ 0x21 #define TERMINATE_ADDR 0x22 #define CB_EXIT_ADDR 0x23 #define CRITICAL_ERR 0x24 #define ABS_DISK_READ 0x25 #define ABS_DISK_WRITE 0x26 #define PGM_TERM_RES 0x27 /* DOS functions -- usually placed in ah register for C86 calls */ #define PGM 0x0 #define KEYIN_ECHO_CB 0x1 #define DSPY_CHAR 0x2 #define AUX_IN 0x3 #define AUX_OUT 0x4 #define PRNT_OUT 0x5 #define KEYIN_ECHO 0x6 #define KEYIN 0x7 #define KEYIN_CB 0x8 #define DSPY_STR 0x9 #define KEYIN_BUF 0xA #define CH_READY 0xB #define GET_CH 0xC #define DISK_RESET 0xD #define SELECT_DISK 0xE #define OPEN_FILE 0xF #define CLOSE_FILE 0x10 #define FIRST_FM 0x11 #define NEXT_FM 0x12 #define DELETE_FILE 0x13 #define READ_SEQ 0x14 #define WRITE_SEQ 0x15 #define CREATE_FILE 0x16 #define RENAME_FILE 0x17 /* 0x18 reserved */ #define CURRENT_DISK 0x19 #define SET_DTA 0x1A #define DFLT_FAT_INFO 0x1B #define FAT_INFO 0x1C /* 0x1D - 0x20 reserved */ #define READ_RANDOM 0x21 #define WRITE_RANDOM 0x22 #define FILE_SIZE 0x23 #define SET_INT_VEC 0x25 #define NEW_PGM_SEG 0x26 #define RAND_BLK_READ 0x27 #define RAND_BLK_WRITE 0x28 #define PARSE_FILENAME 0x29 #define GET_DATE 0x2A #define SET_DATE 0x2B #define GET_TIME 0x2C #define SET_TIME 0x2D #define TOGGLE_VERIFY 0x2E #define GET_DTA 0x2F #define DOS_VERSION 0x30 #define PGM_TERM_KEEP 0x31 /* 0x32 reserved */ #define CB_CHECK 0x33 /* 0x34 reserved */ #define GET_INTR 0x35 #define GET_FREE_SPACE 0x36 /* 0x37 reserved */ #define INTL_INFO 0x38 #define MKDIR 0x39 #define RMDIR 0x3A #define CHDIR 0x3B #define CREAT 0x3C #define OPEN_FD 0x3D #define CLOSE_FD 0x3E #define WRITE_FD 0x40 #define UNLINK 0x41 #define LSEEK 0x42 #define CHMOD 0x43 #define IOCTL 0x44 #define DUP 0x45 #define FORCE_DUP 0x46 #define GET_CUR_DIR 0x47 #define ALLOC 0x48 #define FREE 0x49 #define SET_BLOCK 0x4A #define EXEC 0x4B #define EXIT 0x4C #define WAIT 0x4D #define FIND_FIRST 0x4E #define FIND_NEXT 0x4F /* 0x50 - 53 reserved */ #define VERIFY_STATE 0x54 /* 0x55 reserved */ #define RENAME 0x56 #define FILE_MTIME 0x57 keydefs ─────────────────────────────────────────────────────────────────────────── /* keydefs -- values for special keys on IBM PC and clones */ #define XF 0x100 /* extended key flag */ #define K_F1 59 | XF /* function keys */ #define K_F2 60 | XF #define K_F3 61 | XF #define K_F4 62 | XF #define K_F5 63 | XF #define K_F6 64 | XF #define K_F7 65 | XF #define K_F8 66 | XF #define K_F9 67 | XF #define K_F10 68 | XF #define K_SF1 84 | XF /* shifted function keys */ #define K_SF2 85 | XF #define K_SF3 86 | XF #define K_SF4 87 | XF #define K_SF5 88 | XF #define K_SF6 89 | XF #define K_SF7 90 | XF #define K_SF8 91 | XF #define K_SF9 92 | XF #define K_SF10 93 | XF #define K_CF1 94 | XF /* control function keys */ #define K_CF2 95 | XF #define K_CF3 96 | XF #define K_CF4 97 | XF #define K_CF5 98 | XF #define K_CF6 99 | XF #define K_CF7 100 | XF #define K_CF8 101 | XF #define K_CF9 102 | XF #define K_CF10 103 | XF #define K_AF1 104 | XF /* alternate function keys */ #define K_AF2 105 | XF #define K_AF3 106 | XF #define K_AF4 107 | XF #define K_AF5 108 | XF #define K_AF6 109 | XF #define K_AF7 110 | XF #define K_AF8 111 | XF #define K_AF9 112 | XF #define K_AF10 113 | XF #define K_HOME 71 | XF /* cursor keypad (NumLock off; */ #define K_END 79 | XF /* not shifted) */ #define K_PGUP 73 | XF #define K_PGDN 81 | XF #define K_LEFT 75 | XF #define K_RIGHT 77 | XF #define K_UP 72 | XF #define K_DOWN 80 | XF #define K_CHOME 119 | XF /* control cursor keypad */ #define K_CEND 117 | XF #define K_CPGUP 132 | XF #define K_CPGDN 118 | XF #define K_CLEFT 115 | XF #define K_CRGHT 116 | XF #define K_CTRLA 1 /* standard control keys */ #define K_CTRLB 2 #define K_CTRLC 3 #define K_CTRLD 4 #define K_CTRLE 5 #define K_CTRLF 6 #define K_CTRLG 7 #define K_CTRLH 8 #define K_CTRLI 9 #define K_CTRLJ 10 #define K_CTRLK 11 #define K_CTRLL 12 #define K_CTRLM 13 #define K_CTRLN 14 #define K_CTRLO 15 #define K_CTRLP 16 #define K_CTRLQ 17 #define K_CTRLR 18 #define K_CTRLS 19 #define K_CTRLT 20 #define K_CTRLU 21 #define K_CTRLV 22 #define K_CTRLW 23 #define K_CTRLX 24 #define K_CTRLY 25 #define K_CTRLZ 26 #define K_ALTA 30 | XF /* alternate keys */ #define K_ALTB 48 | XF #define K_ALTC 46 | XF #define K_ALTD 32 | XF #define K_ALTE 18 | XF #define K_ALTF 33 | XF #define K_ALTG 34 | XF #define K_ALTH 35 | XF #define K_ALTI 23 | XF #define K_ALTJ 36 | XF #define K_ALTK 37 | XF #define K_ALTL 38 | XF #define K_ALTM 50 | XF #define K_ALTN 49 | XF #define K_ALTO 24 | XF #define K_ALTP 25 | XF #define K_ALTQ 16 | XF #define K_ALTR 19 | XF #define K_ALTS 31 | XF #define K_ALTT 20 | XF #define K_ALTU 22 | XF #define K_ALTV 47 | XF #define K_ALTW 17 | XF #define K_ALTX 45 | XF #define K_ALTY 21 | XF #define K_ALTZ 44 | XF #define K_ALT1 120 | XF /* additional alternate key */ #define K_ALT2 121 | XF /* combinations */ #define K_ALT3 122 | XF #define K_ALT4 123 | XF #define K_ALT5 124 | XF #define K_ALT6 125 | XF #define K_ALT7 126 | XF #define K_ALT8 127 | XF #define K_ALT9 128 | XF #define K_ALT0 129 | XF #define K_ALTDASH 130 | XF #define K_ALTEQU 131 | XF #define K_ESC 27 /* miscellaneous special keys */ #define K_SPACE 32 #define K_INS 82 | XF #define K_DEL 83 | XF #define K_TAB K_CTRLI #define K_BACKTAB K_CTRLO #define K_CTRL_PRTSC 114 | XF /* printer echoing toggle */ #define K_RETURN 13 /* return key variations */ #define K_SRETURN 13 #define K_CRETURN 10 bioslib.h ─────────────────────────────────────────────────────────────────────────── /* bioslib.h */ #define PRINT_SCRN 0x05 /* BIOS interrupts */ #define TOD_INIT 0x08 #define KEYBD_INIT 0x09 #define DISK_INIT 0x0E #define VIDEO_IO 0x10 #define EQUIP_CK 0x11 #define MEM_SIZE 0x12 #define DISK_IO 0x13 #define RS232_IO 0x14 #define CASS_IO 0x15 #define KEYBD_IO 0x16 #define PRINT_IO 0x17 #define TOD 0x1A #define VIDEO_INIT 0x1D #define GRAPHICS 0x1F #define SET_MODE 0 /* video routine numbers */ #define CUR_TYPE 1 /* (placed in register AH */ #define CUR_POS 2 /* before a BIOS interrupt 10H) */ #define GET_CUR 3 #define LPEN_POS 4 #define SET_PAGE 5 #define SCROLL_UP 6 #define SCROLL_DN 7 #define READ_CHAR_ATTR 8 #define WRITE_CHAR_ATTR 9 #define WRITE_CHAR 10 #define PALETTE 11 #define WRITE_DOT 12 #define READ_DOT 13 #define WRITE_TTY 14 #define GET_STATE 15 #define ALT_FUNCTION 18 /* EGA only */ #define WRITE_STR 19 /* AT only */ #define RESET_DISK 0 /* disk routine numbers */ #define DISK_STATUS 1 #define READ_SECTOR 2 #define WRITE_SECTOR 3 #define VERIFY_SECTOR 4 #define FORMAT_TRACK 5 #define KBD_READ 0 /* keyboard routine numbers */ #define KBD_READY 1 #define KBD_STATUS 2 equipchk ─────────────────────────────────────────────────────────────────────────── /* equipchk -- get equipment list */ #include <dos.h> #include <local\bioslib.h> #include <local\equip.h> struct EQUIP Eq; int equipchk() { union REGS inregs, outregs; /* call BIOS equipment check routine */ int86(EQUIP_CK, &inregs, &outregs); /* extract data from returned data word */ Eq.nprint = (outregs.x.ax & 0xC000) / 0x8000; Eq.game_io = ((outregs.x.ax & 0x1000) / 0x1000) ? 1 : 0; Eq.nrs232 = (outregs.x.ax & 0x0E00) / 0x0200; Eq.ndrive = ((outregs.x.ax & 0x00C0) / 0x0040) + 1; Eq.vmode = (outregs.x.ax & 0x0030) / 0x0010; Eq.basemem = ((outregs.x.ax & 0x000C) / 0x0004) + 1; Eq.disksys = outregs.x.ax & 0x0001 == 1; return (outregs.x.cflag); } video.h ─────────────────────────────────────────────────────────────────────────── /* video.h */ /* current video state/mode information */ extern short Vmode; extern short Vwidth; extern short Vpage; #define MAXVMODE 17 /* video limit tables */ extern short Maxrow[MAXVMODE]; extern short Maxcol[MAXVMODE]; extern short Maxpage[MAXVMODE]; /* active display */ #define MONO 1 #define COLOR 2 /* cursor modes */ #define CURSOR_OFF 0 #define CURSOR_ON 1 /* installed display adapters */ #define MDA 1 #define CGA 2 #define EGA 4 /* --- video modes --- */ /* CGA modes */ #define CGA_M40 0 #define CGA_C40 1 #define CGA_M80 2 #define CGA_C80 3 #define CGA_CMRES 4 #define CGA_MMRES 5 #define CGA_MHRES 6 /* MDA mode */ #define MDA_M80 7 /* PCjr modes */ #define PCJR_CLRES 8 #define PCJR_CMRES 9 #define PCJR_CHRES 10 /* modes 11 and 12 are not currently used */ /* EGA modes */ #define EGA_CMRES 13 #define EGA_CHRES 14 #define EGA_MHRES 15 #define EGA_EHRES 16 /* miscellaneous video masks */ #define CMASK 0x00FF /* character mask */ #define AMASK 0xFF00 /* attribute mask */ /* attribute modifiers */ #define BRIGHT 8 #define BLINK 128 /* primary video attributes */ #define BLU 1 #define GRN 2 #define RED 4 /* composite video attributes */ #define BLK 0 #define CYAN (BLU | GRN) /* 3 */ #define MAGENTA (BLU | RED) /* 5 */ #define BRN (GRN | RED) /* 6 */ #define WHT (BLU | GRN | RED) /* 7 */ #define GRAY (BLK | BRIGHT) #define LBLU (BLU | BRIGHT) #define LGRN (GRN | BRIGHT) #define LCYAN (CYAN | BRIGHT) #define LRED (RED | BRIGHT) #define LMAG (MAG | BRIGHT) #define YEL (BRN | BRIGHT) #define BWHT (WHT | BRIGHT) #define NORMAL WHT #define REVERSE 112 /* drawing characters -- items having two numbers use * the first number as the horizontal specifier */ /* single-line boxes */ #define VBAR1 179 #define VLINE 179 /* alias */ #define HBAR1 196 #define HLINE 196 /* alias */ #define ULC11 218 #define URC11 191 #define LLC11 192 #define LRC11 217 #define TL11 195 #define TR11 180 #define TT11 194 #define TB11 193 #define X11 197 /* double-line boxes */ #define VBAR2 186 #define HBAR2 205 #define ULC22 201 #define URC22 187 #define LLC22 200 #define LRC22 188 #define TL22 204 #define TR22 185 #define TT22 203 #define TB22 202 #define X22 206 /* single-line horizontal & double-line vertical boxes */ #define ULC12 214 #define URC12 183 #define LLC12 211 #define LRC12 189 #define TL12 199 #define TR12 182 #define TT12 210 #define TB12 208 #define X12 215 /* double-line horizontal & single-line vertical boxes */ #define ULC21 213 #define URC21 184 #define LLC21 212 #define LRC21 190 #define TL21 198 #define TR21 181 #define TT21 209 #define TB21 207 #define X21 216 /* full and partial blocks */ #define BLOCK 219 #define VBAR 219 /* alias */ #define VBARL 221 #define VBARR 222 #define HBART 223 #define HBARB 220 /* special character-graphic symbols */ #define BLANK 32 #define DIAMOND 4 #define UPARROW 24 #define DOWNARROW 25 #define RIGHTARROW 26 #define LEFTARROW 27 #define SLASH 47 getstate ─────────────────────────────────────────────────────────────────────────── /* getstate -- update video state structure */ #include <dos.h> #include <local\std.h> #include <local\bioslib.h> /* current video state/mode information */ short Vmode; short Vwidth; short Vpage; /* video tables -- these tables of video parameters use * a value of -1 to indicate that an item is not supported * and 0 to indicate that an item has a variable value. */ /* video limit tables */ short Maxrow[] = { 25, 25, 25, 25, 25, 25, 25, /* CGA modes */ 25, /* MDA mode */ 25, 25, 25, /* PCjr modes */ -1, -1, /* not used */ 25, 25, 25, 43 /* EGA modes */ }; short Maxcol[] = { 40, 40, 80, 80, 40, 40, 80, /* CGA modes */ 80, /* MDA mode */ -1, 40, 80, /* PCjr modes */ -1, -1, /* not used */ 80, 80, 80, 80 /* EGA modes */ }; short Maxpage[] = { 8, 8, 4, 4, 1, 1, 1, /* CGA modes */ 1, /* MDA mode */ 0, 0, 0, /* PCjr modes */ -1, -1, /* not used */ 8, 4, 1, 1 /* EGA modes */ }; int getstate() { union REGS inregs, outregs; inregs.h.ah = GET_STATE; int86(VIDEO_IO, &inregs, &outregs); Vmode = outregs.h.al; Vwidth = outregs.h.ah; Vpage = outregs.h.bh; return (outregs.x.cflag); } setvmode ─────────────────────────────────────────────────────────────────────────── /* setvmode -- set the video mode (color/graphics systems only) */ #include <dos.h> #include <local\std.h> #include <local\bioslib.h> /*********************************************************** * mode # description * ------------ ---------------------------------- * PC MODES: * 0 40x25 Mono text (c/g default) * 1 40x25 Color text * 2 80x25 Mono text * 3 80x25 Color text * 4 320x200 4-color graphics (med res) * 5 320x200 Mono graphics (med res) * 6 640x200 2-color graphics (hi res) * 7 80x25 on monochrome adapter * * PCjr MODES: * 8 160x200 16-color graphics * 9 320x200 16-color graphics * 10 640x200 4-color fraphics * * EGA MODES: * 13 320x200 16-color graphics * 14 620x200 16-color graphics * 15 640x350 mono graphics * 16 640x350 color graphics (4- or 16-color) ***********************************************************/ int setvmode(vmode) unsigned int vmode; /* user-specified mode number */ { union REGS inregs, outregs; inregs.h.ah = SET_MODE; inregs.h.al = vmode; /* value not checked */ int86(VIDEO_IO, &inregs, &outregs); getstate(); /* update video structure */ return (outregs.x.cflag); } setpage ─────────────────────────────────────────────────────────────────────────── /* setpage -- select "visual" screen page for viewing * (the "active" page is the one being written to) */ #include <dos.h> #include <local\std.h> #include <local\bioslib.h> #include <local\video.h> int setpage(pg) int pg; /* visual screen page number */ { union REGS inregs, outregs; /* check page number against table */ if (Maxpage[Vmode] > 0 && (pg < 0 || pg >= Maxpage[Vmode])) return (-1); /* change the visual page */ inregs.h.ah = SET_PAGE; inregs.h.al = pg; int86(VIDEO_IO, &inregs, &outregs); return (outregs.x.cflag); } readcur ─────────────────────────────────────────────────────────────────────────── /* readcur -- pass back the cursor position (row, col) */ #include <dos.h> #include <local\std.h> #include <local\bioslib.h> unsigned int readcur(row, col, pg) unsigned int *row; /* current row */ unsigned int *col; /* current column */ unsigned int pg; /* screen page */ { union REGS inregs, outregs; inregs.h.ah = GET_CUR; inregs.h.bh = pg; int86(VIDEO_IO, &inregs, &outregs); *col = outregs.h.dl; /* col */ *row = outregs.h.dh; /* row */ return (outregs.x.cflag); } putcur ─────────────────────────────────────────────────────────────────────────── /* putcur -- put cursor at specified position (row, col) */ #include <dos.h> #include <local\std.h> #include <local\bioslib.h> unsigned int putcur(r, c, pg) unsigned int r, /* row */ c, /* column */ pg; /* screen page for writes */ { union REGS inregs, outregs; inregs.h.ah = CUR_POS; inregs.h.bh = pg & 0x07; inregs.h.dh = r & 0xFF; inregs.h.dl = c & 0xFF; int86(VIDEO_IO, &inregs, &outregs); return (outregs.x.cflag); } getctype ─────────────────────────────────────────────────────────────────────────── /* getctype -- pass back cursor type info (scan lines) */ #include <dos.h> #include <local\std.h> #include <local\bioslib.h> #define LO_NIBBLE 0x0F int getctype(start_scan, end_scan, pg) int *start_scan; /* starting scan line */ int *end_scan; /* ending scan line */ int pg; /* "visual" page */ { union REGS inregs, outregs; inregs.h.bh = pg; inregs.h.ah = GET_CUR; int86(VIDEO_IO, &inregs, &outregs); /* end_scan = low 4 bits of cl */ *end_scan = outregs.h.cl & LO_NIBBLE; /* starting_scan = low 4 bits of ah */ *start_scan = outregs.h.ch & LO_NIBBLE; return (outregs.x.cflag); } setctype ─────────────────────────────────────────────────────────────────────────── /* setctype -- set the cursor start and end raster scan lines */ #include <dos.h> #include <local\bioslib.h> #define LO_NIBBLE 0x0F #define CURSOR_OFF 0x2 #define MAXSCANLN 15 int setctype(start, end) int start; /* starting raster scan line */ int end; /* ending raster scan line */ { union REGS inregs, outregs; inregs.h.ah = CUR_TYPE; inregs.h.ch = start & LO_NIBBLE; inregs.h.cl = end & LO_NIBBLE; if (start >= MAXSCANLN) { inregs.h.ah |= CURSOR_OFF; inregs.h.al = MAXSCANLN; } int86(VIDEO_IO, &inregs, &outregs); return (outregs.x.cflag); } readca ─────────────────────────────────────────────────────────────────────────── /* readca -- read character and attribute at current position */ #include <dos.h> #include <local\std.h> #include <local\bioslib.h> int readca(ch, attr, pg) unsigned char *ch; unsigned char *attr; unsigned int pg; /* screen page for reads */ { union REGS inregs, outregs; inregs.h.ah = READ_CHAR_ATTR; inregs.h.bh = pg; /* display page */ int86(VIDEO_IO, &inregs, &outregs); *ch = outregs.h.al; /* character */ *attr = outregs.h.ah; /* attribute */ /* return the value in AX register */ return (outregs.x.cflag); } writeca ─────────────────────────────────────────────────────────────────────────── /* writeca -- write character and attribute to the screen */ #include <dos.h> #include <local\std.h> #include <local\bioslib.h> int writeca(ch, attr, count, pg) unsigned char ch; /* character */ unsigned char attr; /* attribute */ int count; /* number of repetitions */ int pg; /* screen page for writes */ { union REGS inregs, outregs; inregs.h.ah = WRITE_CHAR_ATTR; inregs.h.al = ch; inregs.h.bh = pg; inregs.h.bl = attr; inregs.x.cx = count; int86(VIDEO_IO, &inregs, &outregs); return (outregs.x.cflag); } clrscrn ─────────────────────────────────────────────────────────────────────────── /* clrscrn -- clear the "visual" screen page */ #include <dos.h> #include <local\std.h> #include <local\bioslib.h> #include <local\video.h> int clrscrn(a) unsigned int a; /* video attribute for new lines */ { union REGS inregs, outregs; inregs.h.ah = SCROLL_UP; inregs.h.al = 0; /* blank entire window */ inregs.h.bh = a; /* use specified attribute */ inregs.h.bl = 0; inregs.x.cx = 0; /* upper left corner */ inregs.h.dh = Maxrow[Vmode] - 1; /* bottom screen row */ inregs.h.dl = Maxcol[Vmode] - 1; /* rightmost column */ int86(VIDEO_IO, &inregs, &outregs); return (outregs.x.cflag); } clrw ─────────────────────────────────────────────────────────────────────────── /* clrw -- clear specified region of "visual" screen page */ #include <dos.h> #include <local\std.h> #include <local\bioslib.h> int clrw(t, l, b, r, a) int t; /* top row of region to clear */ int l; /* left column */ int b; /* bottom row */ int r; /* right column */ unsigned char a; /* attribute for cleared region */ { union REGS inregs, outregs; inregs.h.ah = SCROLL_UP; /* scroll visual page up */ inregs.h.al = 0; /* blank entire window */ inregs.h.bh = a; /* attribute of blank lines */ inregs.h.bl = 0; inregs.h.ch = t; /* upper left of scroll region */ inregs.h.cl = l; inregs.h.dh = b; /* lower right of scroll region */ inregs.h.dl = r; int86(VIDEO_IO, &inregs, &outregs); return (outregs.x.cflag); } scroll ─────────────────────────────────────────────────────────────────────────── /* scroll -- scroll a region of the "visual" screen * page up or down by n rows (0 = initialize region) */ #include <dos.h> #include <local\std.h> #include <local\bioslib.h> int scroll(t, l, b, r, n, a) int t; /* top row of scroll region */ int l; /* left column */ int b; /* bottom row */ int r; /* right column */ int n; /* number of lines to scroll */ /* sign indicates direction to scroll */ /* 0 means scroll all lines in the region (initialize) */ unsigned char a;/* attribute for new lines */ { union REGS inregs, outregs; if (n < 0) { /* scroll visual page down n lines */ inregs.h.ah = SCROLL_DN; inregs.h.al = -n; } else { /* scroll visual page up n lines */ inregs.h.ah = SCROLL_UP; inregs.h.al = n; } inregs.h.bh = a; /* attribute of blank lines */ inregs.h.bl = 0; inregs.h.ch = t; /* upper-left of scroll region */ inregs.h.cl = l; inregs.h.dh = b; /* lower-right of scroll region */ inregs.h.dl = r; int86(VIDEO_IO, &inregs, &outregs); return (outregs.x.cflag); } writea ─────────────────────────────────────────────────────────────────────────── /* writea -- write attribute only to screen memory (faked by * reading char and attr and writing back the original * character and the new attribute at each position) */ #include <local\std.h> int writea(a, n, pg) unsigned char a;/* video attribute */ int n; /* number of positions to write */ int pg; /* screen page */ { int i; int status; unsigned short chx, attrx; unsigned short r, c; /* get starting (current) position */ status = 0; status = readcur(&r, &c, pg); for (i = 0; i < n; ++i) { status += putcur(r, c + i, pg); status += readca(&chx, &attrx, pg); status += writeca(chx, a, 1, pg); } /* restore cursor position */ status += putcur(r, c, pg); return (status); } drawbox ─────────────────────────────────────────────────────────────────────────── /* drawbox -- create a box with IBM line-drawing characters */ #include <local\video.h> int drawbox(top, lft, btm, rgt, pg) int top, lft, btm, rgt, pg; { int i; int x; /* interior line length for top and bottom segments */ x = rgt - lft - 1; /* draw the top row */ putcur(top, lft, pg); put_ch(ULC11, pg); writec(HBAR1, x, pg); putcur(top, rgt, pg); put_ch(URC11, pg); /* draw the sides */ for (i = 1; i < btm - top; ++i) { putcur(top + i, lft, pg); put_ch(VBAR1, pg); putcur(top + i, rgt, pg); put_ch(VBAR1, pg); } /* draw the bottom row */ putcur(btm, lft, pg); put_ch(LLC11, pg); writec(HBAR1, x, pg); putcur(btm, rgt, pg); put_ch(LRC11, pg); } cursor ─────────────────────────────────────────────────────────────────────────── /* cursor -- interactively set cursor shape */ #include <dos.h> #include <stdlib.h> #include <local\video.h> #include <local\keydefs.h> /* additional drawing characters (others are defined in video.h) */ #define DOT 254 #define NO_DOT 196 #define D_POINT 31 #define R_POINT 16 #define L_POINT 17 /* dimensions of the help frame */ #define BOX_Y 6 #define BOX_X 30 /* upper-left row and column of big cursor */ int Ulr, Ulc; int Mid; /* cursor scan-line-selection modes */ typedef enum { STARTSCAN, ENDSCAN } CMODE; int main() { int i, j, ch; int start, end; int height, width; static char spoint[] = { "Start\020" }; /* contains right pointer */ static char epoint[] = { "\021Stop" }; /* contains left pointer */ static char title[] = { "CURSOR: Control cursor shape (V1.0)" }; unsigned char oldattr, /* video attribute upon entry */ headattr, /* video attribute of header */ attr, /* primary video attribute */ standout; /* highlighting video attribute */ CMODE mode; static void drawdspy(int, int, int, int, int); static void drawstart(int, char *); static void drawend(int, int, char *); static void drawactive(int, int, CMODE); static void showhelp(int, int); static void writestr(char *, int); /* get video information and initialize */ getstate(); Mid = Vwidth / 2; readca(&ch, &oldattr, Vpage); /* preserve user's video attribute */ getctype(&start, &end, Vpage); /* and cursor shape */ headattr = (WHT << 4) | BLK; /* set parameters based on video mode (default = CGA) */ height = width = 8; /* use an 8 by 8 block character cell */ attr = (BLU << 4) | CYAN | BRIGHT; standout = YEL; if (Vmode == MDA_M80) { /* uses a 14 by 9 dot block character cell */ height = 14; width = 9; attr = NORMAL; standout = BWHT; } setctype(height + 1, height + 1); /* cursor off */ /* basic text and layout */ Ulr = 2; Ulc = Mid - width / 2; clrscrn(attr); putcur(0, 0, Vpage); writeca(' ', headattr, Vwidth, Vpage); putcur(0, Mid - strlen(title) / 2, Vpage); writestr(title, Vpage); showhelp(Ulr + height + 1, Mid - BOX_X / 2); /* interactively select cursor shape */ mode = STARTSCAN; drawdspy(start, end, standout, width, height); drawstart(start, spoint); drawend(end, width, epoint); drawactive(height, width, mode); while (1) { switch (ch = getkey()) { case K_UP: /* move up one scan line */ if (mode == STARTSCAN) drawstart(start--, " "); else drawend(end--, width, " "); break; case K_DOWN: /* move down one scan line */ if (mode == STARTSCAN) drawstart(start++, " "); else drawend(end++, width, " "); break; case K_LEFT: /* starting scan-line-selection mode */ mode = STARTSCAN; drawactive(height, width, mode); continue; case K_RIGHT: /* ending scan-line-selection mode */ mode = ENDSCAN; drawactive(height, width, mode); continue; case K_RETURN: /* set the new cursor shape */ setctype(start, end); clrscrn(oldattr); putcur(0, 0, Vpage); exit(0); } /* make corrections at cursor image boundaries */ if (start < 0) start = 0; else if (start > height) start = height; if (end < 0) end = 0; else if (end >= height) end = height - 1; /* show updated cursor shape and pointers */ drawdspy(start, end, standout, width, height); drawstart(start, spoint); drawend(end, width, epoint); } exit(0); } /* end main() */ /* drawdspy -- draw a magnified image of a cursor with the * currently active scan lines depicted as a sequence of dots * and inactive lines depicted as straight lines */ static void drawdspy(s, e, a, w, h) int s; /* starting scan line */ int e; /* ending scan line */ int a; /* video attribute */ int w; /* width */ int h; /* height */ { int i; /* display an exploded image of each scan line */ for (i = 0; i < h; ++i) { putcur(Ulr + i, Ulc, Vpage); if (s >= h) /* cursor is effectively off */ writeca(NO_DOT, a, w, Vpage); else if ((s <= e && i >= s && i <= e) || /* a full block */ (s > e && (i <= e || i >= s))) /* a split block */ writeca(DOT, a, w, Vpage); else /* outside start/end range */ writeca(NO_DOT, a, w, Vpage); } } /* end drawdspy() */ /* drawstart -- display a pointer to the displayed starting * scan line in the magnified cursor image */ static void drawstart(s, sp) int s; /* starting scan line number */ char *sp; /* visual pointer to the displayed starting scan line */ { putcur(Ulr + s, Ulc - strlen(sp), Vpage); putstr(sp, Vpage); } /* end drawstart() */ /* drawend -- display a pointer to the displayed ending * scan line in the magnified cursor image */ static void drawend(e, w, ep) int e; /* ending scan line number */ int w; /* width of the cursor image */ char *ep; /* visual pointer to the displayed ending scan line */ { putcur(Ulr + e, Ulc + w, Vpage); putstr(ep, Vpage); } /* end drawend() */ static void drawactive(h, w, m) int h, w; CMODE m; { int col; /* clear active selector row */ putcur(Ulr - 1, Ulc, Vpage); writec(' ', w, Vpage); /* point to active selector */ col = (m == STARTSCAN) ? 0 : w - 1; putcur(Ulr - 1, Ulc + col, Vpage); writec(D_POINT, 1, Vpage); } /* end drawactive() */ / showhelp -- display a set of instructions about the * use of the cursor program in a fine-ruled box */ static void showhelp(r, c) int r, c; /* upper-left corner of help frame */ { static char title[] = { " Instructions " }; extern int drawbox(int, int, int, int, int); /* fine-ruled box */ clrw(r, c, r + BOX_Y, c + BOX_X, (WHT << 4) | GRN | BRIGHT); drawbox(r, c, r + BOX_Y, c + BOX_X, Vpage); /* centered title */ putcur(r, c + (BOX_X - strlen(title)) / 2, Vpage); putstr(title, Vpage); /* display symbols and text using brute-force positioning */ putcur(r + 2, c + 2, Vpage); put_ch(LEFTARROW, Vpage); put_ch(RIGHTARROW, Vpage); putstr(" Change selection mode", Vpage); putcur(r + 3, c + 2, Vpage); put_ch(UPARROW, Vpage); put_ch(DOWNARROW, Vpage); putstr(" Select scan lines", Vpage); putcur(r + 4, c + 2, Vpage); put_ch(L_POINT, Vpage); put_ch(LRC11, Vpage); putstr(" Set shape and exit", Vpage); } /* end showhelp() */ /* writestr -- write a string in the prevailing video attribute */ static void writestr(s, pg) char *s /* string to write*/ unsigned int pg; /* screen page for writes */ { unsigned int r, c, cO; readcur(&r, &c, pg); for (cO = c; *s != '\0'; ++s, ++c) { putcur(r, c, pg); writec(*s, 1, pg); } /* restore cursor position */ putcur(r, cO, pg); } /* end writestr() */ makefile for the BIOS library ─────────────────────────────────────────────────────────────────────────── # makefile for the BIOS library LINC = c:\include\local LLIB = c:\lib\local # --- inference rules --- .c.obj: msc $*; # --- objects --- O1 = clrscrn.obj clrw.obj drawbox.obj equipchk.obj getctype.obj getstate.obj O2 = kbd_stat.obj memsize.obj palette.obj putcur.obj putstr.obj put_ch.obj O3 = readca.obj readcur.obj readdot.obj scroll.obj setctype.obj setpage.obj O4 = setvmode.obj writea.obj writec.obj writeca.obj writedot.obj writetty.obj # --- compile sources --- clrscrn.obj: clrscrn.c $(LINC)\bioslib.h $(LINC)\std.h clrw.obj: clrw.c $(LINC)\bioslib.h $(LINC)\std.h drawbox.obj: drawbox.c $(LINC)\video.h equipchk.obj: equipchk.c $(LINC)\bioslib.h $(LINC)\equip.h getctype.obj: getctype.c $(LINC)\bioslib.h $(LINC)\std.h getstate.obj: getstate.c $(LINC)\bioslib.h $(LINC)\std.h kbd_stat.obj: kbd_stat.c $(LINC)\bioslib.h $(LINC)\keybdlib.h palette.obj: palette.c $(LINC)\bioslib.h putcur.obj: putcur.c $(LINC)\bioslib.h $(LINC)\std.h putstr.obj: putstr.c $(LINC)\bioslib.h put_ch.obj: put_ch.c $(LINC)\bioslib.h readca.obj: readca.c $(LINC)\bioslib.h $(LINC)\std.h readcur.obj: readcur.c $(LINC)\bioslib.h $(LINC)\std.h readdot.obj: readdot.c $(LINC)\bioslib.h $(LINC)\std.h scroll.obj: scroll.c $(LINC)\bioslib.h $(LINC)\std.h setctype.obj: setctype.c $(LINC)\bioslib.h setpage.obj: setpage.c $(LINC)\bioslib.h $(LINC)\std.h $(LINC)\video.h setvmode.obj: setvmode.c $(LINC)\bioslib.h $(LINC)\std.h writea.obj: writea.c $(LINC)\std.h writec.obj: writec.c $(LINC)\bioslib.h $(LINC)\std.h writeca.obj: writeca.c $(LINC)\bioslib.h $(LINC)\std.h writedot.obj: writedot.c $(LINC)\bioslib.h $(LINC)\std.h writetty.obj: writetty.c $(LINC)\bioslib.h $(LINC)\std.h # --- create and install the library --- $(LLIB)\bios.lib: $(O1) $(O2) $(O3) $(O4) del $(LLIB)\bios.lib lib $(LLIB)\bios +$(O1); lib $(LLIB)\bios +$(O2); lib $(LLIB)\bios +$(O3); lib $(LLIB)\bios +$(O4); del $(LLIB)\bios.bak writemsg ─────────────────────────────────────────────────────────────────────────── /* writemsg -- displays a message in a field of the prevailing * video attribute and returns the number of displayable message * characters written; truncates the message if its too long * to fit in the field */ #include <stdio.h> #include <local\std.h> int writemsg(r, c, w, s1, s2, pg) int r, c, w ; char *s1, *s2; int pg; { int n = 0; char *cp; /* display first part of the message */ if (s1 != NULL) for (cp = s1; *cp != '\0' && n < w; ++n, ++cp) { putcur(r, c + n, pg); writec(*cp, 1, pg); } /* display second part of the message */ if (s2 != NULL) for (cp = s2; *cp != '\0' && n < w; ++n, ++cp) { putcur(r, c + n, pg); writec(*cp, 1, pg); } /* pad the remainder of the field, if any, with spaces */ if (n < w) { putcur(r, c + n, pg); writec(' ', w - n, pg); } return (n); } getopt() ─────────────────────────────────────────────────────────────────────────── /* * Copyright (c) 1984, 1985 AT&T * All Rights Reserved * * ----- Author's Note ----- * getopt() is reproduced with permission of the AT&T UNIX(R) System * Toolchest. This is a public domain version of getopt(3) that is * distributed to registered Toolchest participants. * Defining DOS_MODS alters the code slightly to obtain compatibility * with DOS and support libraries provided with most DOS C compilers. */ #define DOS_MODS #if defined (DOS_MODS) /* getopt() for DOS */ #else #ident "@(#)getopt.c 1.9" #endif /* 3.0 SID # 1.2 */ /*LINTLIBRARY*/ #define NULL 0 #define EOF (-1) /* * For this to work under versions of DOS prior to 3.00, argv[0] * must be set in main() to point to a valid program name or a * reasonable substitute string. (ARH, 10-8-86) */ #define ERR(s, c) if(opterr){\ char errbuf[2];\ errbuf[0] = c; errbuf[1] = '\n';\ (void) write(2, argv[0], (unsigned)strlen(argv[0]));\ (void) write(2, s, (unsigned)strlen(s));\ (void) write(2, errbuf, 2);} #if defined (DOS_MODS) /* permit function prototyping under DOS */ #include <stdlib.h> #include <string.h> #else /* standard UNIX declarations */ extern int strcmp(); extern char *strchr(); /* * The following line was moved here from the ERR definition * to prevent a "duplicate definition" error message when the * code is compiled under DOS. (ARH, 10-8-86) */ extern int strlen(), write(); #endif int opterr = 1; int optind = 1; int optopt; char *optarg; int getopt(argc, argv, opts) int argc; char **argv, *opts; { static int sp = 1; register int c; register char *cp; if(sp == 1) if(optind >= argc || argv[optind][0] != '-' || argv[optind][1] == '\0') return(EOF); else if(strcmp(argv[optind], "--") == NULL) { optind++; return(EOF); } optopt = c = argv[optind][sp]; if(c == ':' || (cp=strchr(opts, c)) == NULL) { ERR(": illegal option -- ", c); if(argv[optind][++sp] == '\0') { optind++; sp = 1; } return('?'); } if(*++cp == ':') { if(argv[optind][sp+1] != '\0') optarg = &argv[optind++][sp+1]; else if(++optind >= argc) { ERR(": option requires an argument -- ", c); sp = 1; return('?'); } else optarg = argv[optind++]; sp = 1; } else { if(argv[optind][++sp] == '\0') { sp = 1; optind++; } optarg = NULL; } return(c); } cat ─────────────────────────────────────────────────────────────────────────── /* * cat -- concatenate files */ #include <stdio.h> #include <stdlib.h> #include <local\std.h> main(argc, argv) int argc; char **argv; { int ch; char *cp; FILE *fp; BOOLEAN errflag, silent; static char pgm[MAXNAME + 1] = { "cat" }; extern void getpname(char *, char *); extern int fcopy(FILE *, FILE *); extern int getopt(int, char **, char *); extern int optind; extern char *optarg; /* use an alias if one is given to this program */ if (_osmajor >= 3) getpname(*argv, pgm); /* process optional arguments, if any */ errflag = FALSE; silent = FALSE; while ((ch = getopt(argc, argv, "s")) != EOF) switch (ch) { case 's': /* don't complain about nonexistent files */ silent = TRUE; break; case '?': /* say what? */ errflag = TRUE; break; } if (errflag == TRUE) { fprintf(stderr, "Usage: %s [-s] file...\n", pgm); exit(1); } /* process any remaining arguments */ argc -= optind; argv += optind; if (argc == 0) /* no file names -- use standard input */ if (fcopy(stdin, stdout) != 0) { fprintf(stderr, "error copying stdin"); exit(2); } else exit(0); /* copy the contents of each named file to standard output */ for (; argc-- > 0; ++argv) { if ((fp = fopen(*argv, "r")) == NULL) { if (silent == FALSE) fprintf(stderr, "%s: can't open %s\n", pgm, *argv); continue; } if (fcopy(fp, stdout) != 0) { fprintf(stderr, "%s: Error while copying %s", pgm, *argv); exit(3); } if (fclose(fp) != 0) { fprintf(stderr, "%s: Error closing %s", pgm, *argv); exit(4); } } exit(0); } timer ─────────────────────────────────────────────────────────────────────────── /* * timer -- general purpose timer program; uses the * PC's intra-application communication area (ICA) as * a time and date buffer */ #include <dos.h> #include <stdio.h> #include <stdlib.h> #include <string.h> #include <time.h> #include <memory.h> #include <local\std.h> #define NBYTES 16 #define ICA_SEG 0x4F #define MAXTNUM 3 #define TIMEMASK 0x3FFFFFFF #define FLAGBIT 0x80000000 #define IDBIT 0x40000000 main(argc, argv) int argc; char *argv[]; { int ch; char *cp; int tn; /* timer number */ int errflag; /* error flag */ int eflag; /* elapsed time flag */ int sflag; /* start timer flag */ char dest[MAXPATH + 1]; /* destination file name */ char timestr[MAXLINE]; /* buffer for elapsed time string */ long now; /* current time */ long then; /* previously recorded time */ FILE *fout; unsigned long tdata[MAXTNUM]; struct SREGS segregs; static char pgm[MAXNAME + 1] = { "timer" }; static void usage(char *, char *); extern char interval(long, char *); extern void getpname(char *, char *); extern int getopt(int, char **, char *); extern int optind, opterr; extern char *optarg; if (_osmajor >= 3) getpname(*argv, pgm); /* process optional arguments */ fout = stdout; tn = 0; errflag = eflag = sflag = 0; while ((ch = getopt(argc, argv, "0123ef:s")) != EOF) { switch (ch) { case 'e': /* report elapsed timing */ ++eflag; break; case 'f': /* use specified log file or stream */ strcpy(dest, optarg); if ((fout = fopen(dest, "a")) == NULL) { fprintf(stderr, "%s: Cannot open %s\n", pgm, dest); exit(1); } break; case 's': /* start (or restart) timing an interval */ ++sflag; break; case '0': case '1': case '2': case '3': /* use specified timer */ tn = ch - 0x30; break; case '?': /* bad option flag */ ++errflag; break; } } argc -= optind; argv += optind; /* check for errors */ if (errflag > 0 || argc > 0) usage(pgm, "Bad command line option(s)"); segread(&segregs); /* report current date and time */ now = time(NULL); fprintf(fout, "%s", ctime(&now)); /* control and report timer data */ if (eflag) { /* report elapsed time for specified timer */ movedata(ICA_SEG, 0, segregs.ds, tdata, NBYTES); then = tdata[tn]; if ((then & FLAGBIT) != FLAGBIT || (then & IDBIT) != IDBIT) { fprintf(stderr, "Timer database corrupted or not set\n"); exit(1); } interval(now - (then & TIMEMASK), timestr); fprintf(stdout, "Elapsed time = %s\n", timestr); } if (sflag) { /* start (or restart) specified timer */ movedata(ICA_SEG, 0, segregs.ds, tdata, NBYTES); tdata[tn] = (now & TIMEMASK) | FLAGBIT | IDBIT; movedata(segregs.ds, tdata, ICA_SEG, 0, NBYTES); } fputc('\n', fout); exit(0); } /* * usage -- display a usage message and exit * with an error indication */ static void usage(pname, mesg) char *pname; char *mesg; { fprintf(stderr, "%s\n", mesg); fprintf(stderr, "Usage: %s [-efs#]\n", pname); fprintf(stderr, "\t-e \tshow an elapsed time (must use start first)\n"); fprintf(stderr, "\t-f file\tappend output to specified file\n"); fprintf(stderr, "\t-s \tstart (or restart) an interval timer\n"); fprintf(stderr, "\t-# \tselect a timer (0 to 3; default is 0)\n"); exit(2); } interval ─────────────────────────────────────────────────────────────────────────── /* * interval -- report the interval given in seconds as * a human-readable null-terminated string */ #include <stdio.h> char * interval(seconds, buf) long seconds; char *buf; { int hh, mm, ss; long remainder; /* calculate the values */ hh = seconds / 3600; remainder = seconds % 3600; mm = remainder / 60; ss = remainder - (mm * 60); sprintf(buf, "%02d:%02d:%02d\0", hh, mm, ss); return (buf); } delay ─────────────────────────────────────────────────────────────────────────── /* * delay -- provide a delay of ** approximately ** the * specified duration (resolution is about 0.055 second) */ #include <local\timer.h> void delay(d) float d;/* duration in seconds and fractional seconds */ { long ticks, then; extern long getticks(); /* convert duration to number of PC clock ticks */ ticks = d * TICKRATE; /* delay for the specified interval */ then = getticks() + ticks; while (1) if (getticks() >= then) break; } getticks ─────────────────────────────────────────────────────────────────────────── /* * getticks -- get the current bios clock ticks value */ #include <dos.h> #define BIOS_DATA_SEG 0x40 #define TIMER_DATA 0x6C #define TICKS_PER_DAY 0x01800B0L long getticks() { static long total = 0; /* accumulated count of timer ticks */ long count; /* current BIOS TOD count */ long far *lp /* far pointer */ /* set up the far pointera to the BIOS TOD counter */ FP_SEG(lp) = BIOS_DATA_SEG; FP_OFF(lp) = TIMER_DATA; while (1) { /* read the TOD count */ count = *lp if (*lp == count) break; /* two matching TOD readings */ } /* correct for clock roll-over, if necessary */ total = (count < total) ? count + TICKS_PER_DAY : count; return (total); } sweep ─────────────────────────────────────────────────────────────────────────── /* * sweep -- produce a sound that sweeps from * a low to a high frequency repeatedly until a * key is pressed */ #include <conio.h> #include <local\sound.h> main() { unsigned int f; int d, n; extern void setfreq(unsigned int); SPKR_ON; while (1) { /* give the user a way out */ if (kbhit()) break; n = 10; for (f = 100; f <= 5000; f += n) { setfreq(f); d = 1000; /* fake a short delay (machine dependent) */ while (d-- > 0) ; n += 10; } } SPKR_OFF; exit(0); } sound ─────────────────────────────────────────────────────────────────────────── /* * sound -- produce a constant tone for a specified duration */ #include <conio.h> #include <local\sound.h> void sound(f, dur) unsigned int f; /* frequency of pitch in hertz */ float dur; /* in seconds and tenths of seconds */ { extern void setfreq(unsigned int); extern void delay(float); /* set the frequency in hertz */ setfreq(f); /* turn the speaker on for specified duration */ SPKR_ON; delay(dur); SPKR_OFF; } sounds ─────────────────────────────────────────────────────────────────────────── /* * sounds -- make various sounds on demand */ #include <stdio.h> #include <conio.h> #include <math.h> #define ESC 27 extern void sound(unsigned int, float); main() { int ch; fprintf(stderr, "1=warble 2=error 3=confirm 4=warn\n"); fprintf(stderr, "Esc=quit\n"); while ((ch = getch()) != ESC) switch (ch) { case '1': warble(); break; case '2': error(); break; case '3': confirm(); break; case '4': warn(); break; } exit(0); } #define CYCLES 3 #define LOTONE 600 #define HITONE 1200 #define PERIOD 0.1 warble() { int i; for (i = 0; i < 2 * CYCLES; ++i) if (i % 2) sound(LOTONE, PERIOD); else sound(HITONE, PERIOD); } error() { float d = 0.1; sound(440, d); sound(220, d); } confirm() { float d = 0.1; sound(440, d); sound(880, d); } warn() { float d = 0.2; sound(100, d); } getreply ─────────────────────────────────────────────────────────────────────────── /* * getreply -- display a message and wait for a reply */ #include <stdio.h> #include <stdlib.h> #include <memory.h> #include <ctype.h> #include <local\std.h> #include <local\keydefs.h> #include "linebuf.h" char * getreply(row, col, width, mesg, lp, size, attr, pg) short row, col, width; /* window location and width */ char *mesg; /* message text */ LINEBUF *lp; /* line pointer */ short size; /* size of line buffer */ short attr; /* video attribute for response field */ short pg; /* active display page */ { int n, k, len; short mfw; /* message field width */ short rfw; /* response field width */ short ccol; /* visible cursor column */ int msgflag; /* nonzero after a message is displayed */ char *cp; /* character pointer */ char *wp; /* pointer to window start */ char *tmp; /* temporary char pointer */ extern int writemsg(short, short, short, char *, char *, short); /* display the prompt string and calculate response field width */ putcur(row, col, pg); mfw = writemsg(row, col, width, mesg, NULL, pg); rfw = width - mfw; writea(attr, rfw, pg); /* collect the user's response */ memset(lp->l_buf, '\0', size); wp = cp = lp->l_buf; putcur(row, col + mfw, pg); msgflag = 0; while ((k = getkey()) != K_RETURN) { if (msgflag) { /* clear old messages */ errmsg(""); putcur(row, ccol, pg); msgflag = 0; } if (isascii(k) && isprint(k)) { len = strlen(cp); if (cp + len - lp->l_buf < size - 1) { memcpy(cp + 1, cp, len); *cp = k; ++cp; } else { errmsg("input buffer full"); ++msgflag; } } else switch (k) { case K_LEFT: /* move left one character */ if (cp > lp->l_buf) --cp; break; case K_RIGHT: /* move right one character */ if (*cp != '\0') ++cp; break; case K_UP: /* pop a line off the stack */ if (lp->l_prev != NULL) { lp = lp->l_prev; wp = cp = lp->l_buf; } break; case K_DOWN: /* push a line onto the stack */ if (lp->l_next != NULL) { lp = lp->l_next; wp = cp = lp->l_buf; } break; case K_HOME: /* beginning of buffer */ cp = lp->l_buf; break; case K_END: /* end of buffer */ while (*cp != '\0') ++cp; break; case K_CTRLH: if (cp > lp->l_buf) { tmp = cp - 1; memcpy(tmp, cp, strlen(tmp)); --cp; } break; case K_DEL: /* delete character at cursor */ memcpy(cp, cp + 1, strlen(cp)); break; case K_ESC: /* cancel current input */ lp->l_buf[0] = '\0'; putcur(row, col, pg); writec(' ', width, pg); return (NULL); default: errmsg("unknown command"); ++msgflag; break; } /* adjust the window pointer if necessary */ if (cp < wp) wp = cp; else if (cp >= wp + rfw) wp = cp + 1 - rfw; /* display the reply window */ ccol = col + mfw; writemsg(row, ccol, rfw, wp, NULL, pg); /* reposition the cursor */ ccol = col + mfw + (cp - wp); putcur(row, ccol, pg); } putcur(row, col, pg); writec(' ', width, pg); /* blank message area */ return (lp->l_buf); } tstreply ─────────────────────────────────────────────────────────────────────────── /* * tstreply -- test the getreply function */ #include <stdio.h> #include <string.h> #include <local\std.h> #include <local\video.h> #include "linebuf.h" #define INPUT_ROW 0 #define INPUT_COL 40 #define WIDTH 40 int Apage = 0; BOOLEAN Silent = FALSE; main(argc, argv) int argc; char *argv[]; { unsigned int r, c, ch, attr, revattr; char reply[MAXPATH + 1]; LINEBUF buf; extern char *getreply(short, short, short, char *, LINEBUF *, short, short, short); /* process command line */ if (argc == 2 && strcmp(argv[1], "-s") == 0) Silent = TRUE; else if (argc > 2) { fprintf(stderr, "Usage: tstreply [-s]\n"); exit(1); } /* initial setup */ getstate(); readca(&ch, &attr, Apage); revattr = ((attr << 4) | (attr >> 4)) & 0x77; clrscrn(attr); putcur(0, 0, Apage); writestr("TSTREPLY", Apage); putcur(1, 0, Apage); writec(HLINE, Maxcol[Vmode} - 1, Apage); buf.l_buf = reply; buf.l_next = buf.l_prev = (LINEBUF *)NULL; /* demo getreply() */ if (getreply(INPUT_ROW, INPUT_COL, WIDTH, "File: ", &buf, MAXPATH, revattr, 0) == NULL) { putcur(INPUT_ROW, INPUT_COL, Apage); writeca(' ', attr, WIDTH, Apage); putcur(2, 0, Apage); fprintf(stderr, "input aborted\n"); exit(1); } putcur(INPUT_ROW, INPUT_COL, Apage); writeca(' ', attr, WIDTH, Apage); putcur(2, 0, Apage); fprintf(stderr, "reply = %s\n", reply); exit(0); } #define MSG_ROW 24 #define MSG_COL 0 int errmsg(mesg) char *mesg; { int n; extern void sound(unsigned int, float); putcur(MSG_ROW, MSG_COL, Apage); if ((n = strlen(mesg)) > 0) { writestr(mesg, Apage); if (Silent == FALSE) sound(100, 0.2); } else writec(' ', Maxcol[Vmode] - 1 - MSG_COL, Apage); return (n); } fconfig ─────────────────────────────────────────────────────────────────────────── /* * fconfig -- return a FILE pointer to a local or * global configuration file, or NULL if none found */ #include <stdio.h> #include <stdlib.h> #include <string.h> #include <ctype.h> #include <local\std.h> FILE * fconfig(varname, fname) char *varname; char *fname; { FILE *fp; char pname[MAXPATH + 1]; char *p; /* look for a local configuration file */ if ((fp = fopen(fname, "r")) != NULL) return (fp); /* look for a directory variable */ if ((p = getenv(strupr(varname))) != NULL) { strcpy(pname, p); strcat(pname, "\\"); strcat(pname, fname); if ((fp = fopen(pname, "r")) != NULL) return (fp); } /* didn't find anything to read */ return (NULL); } printer.h ─────────────────────────────────────────────────────────────────────────── /* * printer.h -- header for printer-control functions */ /* ASCII codes used for Epson MX/FX-series printer-control */ #define DC2 18 /* cancel condensed type mode */ #define DC4 20 /* cancel expanded type mode */ #define ESC 27 /* signal start of printer-control sequences */ #define FF 12 /* top of page next page */ #define SO 14 /* start expanded type mode */ #define SI 15 /* start condensed type mode */ /* font types */ #define NORMAL 0x00 #define CONDENSED 0x01 #define DOUBLE 0x02 #define EMPHASIZED 0x04 #define EXPANDED 0x08 #define ITALICS 0x10 #define UNDERLINE 0x20 /* miscellaneous constants */ #define MAXPSTR 32 /* maximum printer-control string length */ /* primary printer-control data structure */ typedef struct printer_st { /* hardware initialize/reset */ char p_init[MAXPSTR]; /* set option strings and codes */ char p_bold[MAXPSTR]; /* bold (emphasized) on */ char p_cmp[MAXPSTR]; /* compressed on */ char p_ds[MAXPSTR]; /* double strike on */ char p_exp[MAXPSTR]; /* expanded (double width) on */ char p_ul[MAXPSTR]; /* underline on */ char p_ital[MAXPSTR]; /* italic on */ /* reset option strings and codes */ char p_norm[MAXPSTR]; /* restore normal font */ char p_xbold[MAXPSTR]; /* bold (emphasized) off */ char p_xcmp[MAXPSTR]; /* compressed off */ char p_xds[MAXPSTR]; /* double strike off */ char p_xexp[MAXPSTR]; /* expanded (double width) off */ char p_xul[MAXPSTR]; /* underline off */ char p_xital[MAXPSTR]; /* italic off */ } PRINTER; printer ─────────────────────────────────────────────────────────────────────────── /* * printer -- interface functions for printer */ #include <stdio.h> #include <stdlib.h> #include <string.h> #include <local\std.h> #include <local\printer.h> PRINTER prt; /* printer data */ /* * setprnt -- install printer codes from configuration * file for printer (defaults to Epson MX/FX series) */ #define NSELEM 13 int setprnt() { int n; char *s, line[MAXLINE]; FILE *fp, *fconfig(char *, char *); /* use local or global config file, if any */ if ((fp = fconfig("CONFIG", "printer.cnf")) != NULL) { n = 0; while (fgets(line, MAXLINE, fp) != NULL) { if ((s = strtok(line, " \t\n")) == NULL) return (-1); switch (n) { case 0: strcpy(prt.p_init, s); break; case 1: strcpy(prt.p_bold, s); break; case 2: strcpy(prt.p_ds, s); break; case 3: strcpy(prt.p_ital, s); break; case 4: strcpy(prt.p_cmp, s); break; case 5: strcpy(prt.p_exp, s); break; case 6: strcpy(prt.p_ul, s); break; case 7: strcpy(prt.p_xbold, s); break; case 8: strcpy(prt.p_xds, s); break; case 9: strcpy(prt.p_xital, s); break; case 10: strcpy(prt.p_xcmp, s); break; case 11: strcpy(prt.p_xexp, s); break; case 12: strcpy(prt.p_xul, s); break; default: /* too many lines */ return (-1); } ++n; } if (n != NSELEM) /* probably not enough lines */ return (-1); } /* or use Epson defaults */ strcpy(prt.p_init, "\033@"); /* hardware reset */ strcpy(prt.p_bold, "\033E"); /* emphasized mode */ strcpy(prt.p_ds, "\033G"); /* double-strike mode */ strcpy(prt.p_ital, "\0334"); /* italic mode */ strcpy(prt.p_cmp, "\017"); /* condensed mode */ strcpy(prt.p_exp, "\016"); /* expanded mode */ strcpy(prt.p_ul, "\033-1"); /* underline mode */ strcpy(prt.p_xbold, "\033F"); /* cancel emphasized mode */ strcpy(prt.p_xds, "\033H"); /* cancel double-strike mode */ strcpy(prt.p_xital, "\0335"); /* cancel italic mode */ strcpy(prt.p_xcmp, "\022"); /* cancel condensed mode */ strcpy(prt.p_xexp, "\024"); /* cancel expanded mode */ strcpy(prt.p_xul, "\033-0"); /* cancel underline mode */ return (0); } /* * clrprnt -- clear printer options to default values * (clears individual options to avoid the "paper creep" * that occurs with repeated printer resets and to avoid * changing the printer's notion of top-of-form position) */ int clrprnt(fout) FILE *fout; { fputs(prt.p_xbold, fout); /* cancel emphasized mode */ fputs(prt.p_xds, fout); /* cancel double-strike mode */ fputs(prt.p_xital, fout); /* cancel italic mode */ fputs(prt.p_xcmp, fout); /* cancel condensed mode */ fputs(prt.p_xexp, fout); /* cancel expanded mode */ fputs(prt.p_xul, fout); /* cancel underline mode */ } /* end clrprnt() */ /* * setfont -- set the printing font to the type specified * by the argument (may be a compound font specification) */ int setfont(ftype, fout) int ftype; /* font type specifier */ FILE *fout; /* output stream */ { clrprnt(fout); if ((ftype & CONDENSED) == CONDENSED) if ((ftype & DOUBLE) == DOUBLE || (ftype & EMPHASIZED) == EMPHASIZED) return FAILURE; else if (*prt.p_cmp) fputs(prt.p_cmp, fout); if (*prt.p_ds && (ftype & DOUBLE) == DOUBLE) fputs(prt.p_ds, fout); if (*prt.p_bold && (ftype & EMPHASIZED) == EMPHASIZED) fputs(prt.p_bold, fout); if (*prt.p_exp && (ftype & EXPANDED) == EXPANDED) fputs(prt.p_exp, fout); if (*prt.p_ital && (ftype & ITALICS) == ITALICS) fputs(prt.p_ital, fout); if (*prt.p_ul && (ftype & UNDERLINE) == UNDERLINE) fputs(prt.p_ul, fout); return SUCCESS; } /* end setfont() */ mx ─────────────────────────────────────────────────────────────────────────── /* * mx -- control Epson MX-series printer */ #include <stdio.h> #include <stdlib.h> #include <local\std.h> #include <local\printer.h> extern PRINTER prt; /* printer data */ main(argc, argv) int argc; char **argv; { int ch, font; BOOLEAN errflag; /* option error */ BOOLEAN clrflag; /* clear special fonts */ BOOLEAN rflag; /* hardware reset */ BOOLEAN tflag; /* top-of-form */ FILE *fout; static char pgm[MAXNAME + 1] = { "mx" }; extern void getpname(char *, char *); extern int getopt(int, char **, char *); extern char *optarg; extern int optind, opterr; extern int setprnt(); extern int clrprnt(FILE *); extern int setfont(int, FILE *); if (_osmajor >= 3) getpname(*argv, pgm); if (setprnt() == -1) { fprintf(stderr, "%s: Bad printer configuration\n", pgm); exit(1); } /* interpret command line */ errflag = clrflag = rflag = tflag = FALSE; font = 0; fout = stdprn; while ((ch = getopt(argc, argv, "bcdefino:prtu")) != EOF) { switch (ch) { case 'b': /* set bold */ font |= EMPHASIZED; break; case 'c': /* set compressed */ font |= CONDENSED; break; case 'd': /* set double strike */ font |= DOUBLE; break; case 'e': /* set double strike */ font |= EXPANDED; break; case 'i': /* set italic */ font |= ITALICS; break; case 'n': /* set normal (clear all special fonts) */ clrflag = TRUE; break; case 'o': /* use specified output stream */ if ((fout = fopen(optarg, "w")) == NULL) fatal(pgm, "cannot open output stream"); break; case 'p': /* preview control strings on stdout */ fout = stdout; break; case 'r': /* hardware reset */ rflag = TRUE; break; case 't': /* top of form */ tflag = TRUE; break; case 'u': /* set underline */ font |= UNDERLINE; break; case '?': /* unknown option */ errflag = TRUE; break; } } /* report errors, if any */ if (errflag == TRUE || argc == 1) { fprintf(stderr, "Usage: %s -option\n", pgm); fprintf(stderr, "b=bold, c=compressed, d=double strike, e=expanded\n"); fprintf(stderr, "i=italic, n=normal, o file=output to file\n"); fprintf(stderr, "p=preview, r=reset, t=top-of-form, u=underline\n"); exit(2); } /* do hardware reset and formfeed first */ if (rflag == TRUE) fputs(prt.p_init, fout); else if (tflag == TRUE) fputc('\f', fout); /* clear or set the aggregate font */ if (clrflag == TRUE) clrprnt(fout); else if (setfont(font, fout) == FAILURE) { fprintf(stderr, "%s: Bad font spec\n", pgm); exit(3); } exit(0); } prtstr ─────────────────────────────────────────────────────────────────────────── /* * prtstr -- send text string(s) to standard printer */ #include <stdio.h> #include <stdlib.h> #include <local\std.h> main(argc, argv) int argc; char **argv; { int ch; BOOLEAN errflag, lineflag; static char pgm[MAXNAME + 1] = { "prtstr" }; FILE *fout; extern char *getpname(char *, char *); extern int getopt(int, char **, char *); extern int optind, opterr; extern char *optarg; if (_osmajor >= 3) getpname(*argv, pgm); errflag = FALSE; /* process options, if any */ lineflag = TRUE; fout = stdprn; while ((ch = getopt(argc, argv, "np")) != EOF) switch (ch) { case 'n': /* don't emit the trailing newline */ lineflag = FALSE; break; case 'p': /* preview on stdout */ fout = stdout; break; case '?': /* bad option */ errflag = TRUE; break; } if (errflag == TRUE) { fprintf(stderr, "Usage: %s [-np] [string...]\n", pgm); exit(1); } /* print the string(s) */ argc -= optind; argv += optind; while (argc-- > 1 ) { fputs(*argv++, fout); fputc(' ', fout); } fputs(*argv++, fout); if (lineflag == TRUE) fputc(' ', fout); if (lineflag == TRUE) fputc('\n', fout); exit(0); } sample.bat ─────────────────────────────────────────────────────────────────────────── echo off mx -n prtstr This is normal text. mx -b prtstr This is bold (emphasized) text. mx -n prtstr We can mix fonts, too. mx -be prtstr This is bold and expanded together. mx -n prtstr -n We can mix fonts in a line also: mx -b prtstr -n " bold" mx -i prtstr -n " and " mx -e prtstr expanded. mx -u prtstr This is underlined text... mx -i prtstr ... this is italicized. mx -n prtstr And finally back to normal type. select ─────────────────────────────────────────────────────────────────────────── /* * select -- functions to create a selection table and * to determine whether an item is an entry in the table */ #include <stdio.h> #include <stdlib.h> #include <string.h> #include <local\std.h> #define NRANGES 10 #define NDIGITS 5 struct slist_st { long int s_min; long int s_max; } Slist[NRANGES + 1]; long Highest = 0; /* * mkslist -- create the selection lookup table */ int mkslist(list) char *list; { int i; char *listp, *s; long tmp; static long save_range(); if (*list == '\0') { /* fill in table of selected items */ Slist[0].s_min = 0; /* if no list, select all */ Slist[0].s_max = Highest = BIGGEST; Slist[1].s_min = -1; } else { listp = list; for (i = 0; i < NRANGES; ++i) { if ((s = strtok(listp, ", \t")) == NULL) break; if ((tmp = save_range(i, s)) > Highest) Highest = tmp; listp = NULL; } Slist[i].s_min = -1; } return (0); } /* end mkslist() */ /* * selected -- return non-zero value if the number * argument is a member of the selection list */ int selected(n) long n; { int i; /* look for converted number in selection list */ for (i = 0; Slist[i].s_min != -1; ++i) if (n >= Slist[i].s_min && n <= Slist[i].s_max) return (1); return (0); } /* end selected() */ /* * save_range -- convert a string number spec to a * numeric range in the selection table and return * the highest number in the range */ static long save_range(n, s) int n; char *s; { int radix = 10; char *cp, num[NDIGITS + 1]; /* get the first (and possibly only) number */ cp = num; while (*s != '\0' && *s != '-') *cp++ = *s++; *cp = '\0'; Slist[n].s_min = atol(num); if (*s == '\0') /* pretty narrow range, huh? */ return (Slist[n].s_max = Slist[n].s_min); /* get the second number */ if (*++s == '\0') /* unspecified top end of range */ Slist[n].s_max = BIGGEST; else { cp = num; while (*s != '\0') *cp++ = *s++; *cp = '\0'; Slist[n].s_max = atol(num); } return (Slist[n].s_max); } /* end save_range() */ tstsel ─────────────────────────────────────────────────────────────────────────── /* * tstsel -- test driver for the "select" functions */ #include <stdio.h> #include <local\std.h> #define MAXTEST 20 #define NRANGES 10 #define NDIGITS 5 extern struct slist_st { long int s_min; long int s_max; } Slist[NRANGES + 1]; main (argc, argv) int argc; char **argv; { int i; extern int mkslist(char *); extern int selected(unsigned int); static void showlist(); if (argc != 2) { fprintf(stderr, "Usage: tstsel list\n"); exit(1); } printf("argv[1] = %s\n", argv[1]); mkslist(argv[1]); showlist(); for (i = 0; i < MAXTEST; ++i) printf("%2d -> %s\n", i, selected(i) ? "YES" : "NO"); exit(0); } /* * showlist -- display the contents of the select list */ static void showlist() { int i; /* scan the selection list and display values */ for (i = 0; i <= NRANGES; ++i) printf("%2d %5ld %5ld\n", i, Slist[i].s_min, Slist[i].s_max); } Sample output from tstsel ─────────────────────────────────────────────────────────────────────────── argv[1] = 1,2,3,5-10 0 1 1 1 2 2 2 3 3 3 5 10 4 -1 0 5 0 0 6 0 0 7 0 0 8 0 0 9 0 0 10 0 0 0 -> NO 1 -> YES 2 -> YES 3 -> YES 4 -> NO 5 -> YES 6 -> YES 7 -> YES 8 -> YES 9 -> YES 10 -> YES 11 -> NO 12 -> NO 13 -> NO 14 -> NO 15 -> NO 16 -> NO 17 -> NO 18 -> NO 19 -> NO tabs ─────────────────────────────────────────────────────────────────────────── /* * tabs -- a group of cooperating functions that set * and report the settings of "tabstops" */ #include <local\std.h> static char Tabstops[MAXLINE]; /* * fixtabs -- set up fixed-interval tabstops */ void fixtabs(interval) register int interval; { register int i; for (i = 0; i < MAXLINE; i++) Tabstops[i] = (i % interval == 0) ? 1 : 0; } /* end fixtabs() */ /* * vartabs -- set up variable tabstops from an array * integers terminated by a -1 entry */ void vartabs(list) int *list; { register int i; /* initialize the tabstop array */ for (i = 0; i < MAXLINE; ++i) Tabstops[i] = 0; /* set user-specified tabstops */ while (*list != -1) Tabstops[*++list] = 1; } /* end vartabs() */ /* * tabstop -- return non-zero if col is a tabstop */ int tabstop(col) register int col; { return (col >= MAXLINE ? 1 : Tabstops[col]); } /* end tabstop() */ showtabs ─────────────────────────────────────────────────────────────────────────── /* * showtabs -- graphically display tabstop settings */ #include <stdio.h> #include <stdlib.h> #include <local\std.h> #define MAXCOL 80 #define TABWIDTH 8 extern long Highest; main(argc, argv) int argc; char *argv[]; { int ch, i; int interval, tablist[MAXLINE + 1], *p; char *tabstr; BOOLEAN errflag, fflag, vflag; static char pgm[MAXNAME + 1] = { "showtabs" }; extern char *getpname(char *, char *); extern int getopt(int, char **, char *); extern char *optarg; extern int optind, opterr; extern int mkslist(char *); extern int selected(long); extern void fixtabs(int); extern void vartabs(int *); extern int tabstop(int); if (_osmajor >= 3) getpname(*argv, pgm); /* process command-line options */ errflag = fflag = vflag = FALSE; interval = 0; while ((ch = getopt(argc, argv, "f:v:")) != EOF) { switch (ch) { case 'f': /* used fixed tabbing interval */ if (vflag == FALSE) { fflag = TRUE; interval = atoi(optarg); } break; case 'v': /* use list of tabs */ if (fflag == FALSE) { vflag = TRUE; strcpy(tabstr, optarg); } break; case '?': errflag = TRUE; break; } } if (errflag == TRUE) { fprintf(stderr, "Usage: %s [-f interval | -v tablist]\n", pgm); exit(2); } /* set the tabstops */ if (vflag == TRUE) { /* user-supplied variable tab list */ mkslist(tabstr); p = tablist; for (i = 0; i < MAXLINE && i < Highest; ++i) *p++ = selected((long)i + 1) ? i : 0; *p = -1; /* terminate the list */ vartabs(tablist); } else if (fflag == TRUE) /* user-supplied fixed tabbing interval */ fixtabs(interval); else /* hardware default tabbing interval */ fixtabs(TABWIDTH); /* display current tabs settings */ for (i = 0; i < MAXCOL; ++i) if (tabstop(i)) fputc('T', stdout); else if ((i + 1) % 10 == 0) fputc('+', stdout); else fputc('-', stdout); fputc('\n', stdout); exit(0); } touch ─────────────────────────────────────────────────────────────────────────── /* * touch -- update modification time of file(s) */ #include <stdio.h> #include <stdlib.h> #include <ctype.h> #include <sys\types.h> #include <sys\stat.h> #include <sys\utime.h> #include <io.h> #include <errno.h> #include <local\std.h> /* error return -- big enough not to be mistaken for a bad file count */ #define ERR 0x7FFF main(argc, argv) int argc; char *argv[]; { int ch; int i; int badcount; /* # of files that can't be updated */ struct stat statbuf; /* buffer for stat results */ BOOLEAN errflag, /* error flag */ cflag, /* creation flag */ vflag; /* verbose flag */ FILE *fp; static char pgm[MAXNAME + 1] = { "touch" }; extern int getopt(int, char **, char *); extern int optind, opterr; extern char *optarg; extern void getpname(char *, char *); static void usage(char *); /* get program name from DOS (version 3.00 and later) */ if (_osmajor >= 3) getpname(argv[0], pgm); /* process optional arguments first */ errflag = cflag = vflag = FALSE; badcount = 0; while ((ch = getopt(argc, argv, "cv")) != EOF) switch (ch) { case 'c': /* don't create files */ cflag = TRUE; break; case 'v': /* verbose -- report activity */ vflag = TRUE; break; case '?': errflag = TRUE; break; } argc -= optind; argv += optind; /* check for errors including no file names */ if (errflag == TRUE || argc <= 0) { usage(pgm); exit(ERR); } /* update modification times of files */ for (; argc-- > 0; ++argv) { if (stat(*argv, &statbuf) == -1) { /* file doesn't exist */ if (cflag == TRUE) { /* don't create it */ ++badcount; continue; } else if ((fp = fopen(*argv, "w")) == NULL) { fprintf(stderr, "%s: Cannot create %s\n", pgm, *argv); ++badcount; continue; } else { if (fclose(fp) == EOF) { perror("Error closing file"); exit(ERR); } if (stat(*argv, &statbuf) == -1) { fprintf(stderr, "%s: Cannot stat %s\n", pgm, *argv); ++badcount; continue; } } } if (utime(*argv, NULL) == -1) { ++badcount; perror("Error updating date/time stamp"); continue; } if (vflag == TRUE) fprintf(stderr, "Touched file %s\n", *argv); } exit(badcount); } /* end main() */ /* * usage -- display an informative usage message */ static void usage(pname) char *pname; { fprintf(stderr, "Usage: %s [-cv] file ...\n", pname); fprintf(stderr, "\t-c Do not create any files\n"); fprintf(stderr, "\t-v Verbose mode -- report activities\n"); } /* end usage() */ /* * dummy functions to show how to save a little space */ _setenvp() { } #ifndef DEBUG _nullcheck() { } #endif tee ─────────────────────────────────────────────────────────────────────────── /* * tee -- a "pipe fitter" for DOS */ #include <stdio.h> #include <stdlib.h> #include <string.h> #include <local\std.h> main(argc, argv) int argc; char *argv[]; { register int ch, n; static char openmode[] = { "w" }; static char pgm[MAXPATH + 1] = { "tee" }; FILE *fp[_NFILE]; /* array of file pointers */ extern int getopt(int, char **, char *); extern int optind, opterr; extern char *optarg; extern void getpname(char *, char *); /* check for an alias */ if (_osmajor >= 3) getpname(argv[0], pgm); /* process command-line options, if any */ while ((ch = getopt(argc, argv, "a")) != EOF) switch (ch) { case 'a': strcpy(openmode, "a"); break; case '?': break; } n = argc -= optind; argv += optind; /* check for errors */ if (argc > _NFILE) { fprintf(stderr, "Too many files (max = %d)\n", _NFILE); exit(1); } /* open the output file(s) */ for (n = 0; n < argc; ++n) { if ((fp[n] = fopen(argv[n], openmode)) == NULL) { fprintf(stderr, "Cannot open %s\n", argv[n]); continue; } } /* copy input to stdout plus opened file(s) */ while ((ch = getchar()) != EOF) { putchar(ch); for (n = 0; n < argc; ++n) if (fp[n] != NULL) fputc(ch, fp[n]); } /* close file(s) */ if (fcloseall() == -1) { fprintf(stderr, "Error closing a file\n"); exit(2); } exit(0); } pwd ─────────────────────────────────────────────────────────────────────────── /* * pwd -- print (display actually) the current directory pathname */ #include <stdio.h> #include <direct.h> #include <local\std.h> main() { char *path; if ((path = getcwd(NULL, MAXPATH)) == NULL) { perror("Error getting current directory"); exit(1); } printf("%s\n", path); exit(0); } _setargv() { } _setenvp() { } _nullcheck() { } rm ─────────────────────────────────────────────────────────────────────────── /* * rm -- remove file(s) */ #include <stdio.h> #include <stdlib.h> #include <sys\types.h> #include <sys\stat.h> #include <ctype.h> #include <io.h> #include <local\std.h> main(argc, argv) int argc; char *argv[]; { int ch; BOOLEAN errflag, iflag; static char pgm[MAXNAME + 1] = { "rm" }; extern void getpname(char *, char *); static void do_rm(char *, char *, BOOLEAN); extern int getopt(int, char **, char *); extern int optind, opterr; extern char *optarg; /* get program name from DOS (version 3.00 and later) */ if (_osmajor >= 3) getpname(*argv, pgm); /* process optional arguments first */ errflag = iflag = FALSE; while ((ch = getopt(argc, argv, "i")) != EOF) switch (ch) { case 'i': /* interactive -- requires confirmation */ iflag = TRUE; break; case '?': /* say what? */ errflag = TRUE; break; } argc -= optind; argv += optind; if (argc <= 0 || errflag == TRUE) { fprintf(stderr, "%s [-i] file(s)\n", pgm); exit(1); } /* process remaining arguments */ for (; argc-- > 0; ++argv) do_rm(pgm, *argv, iflag); exit(0); } /* end main() */ /* * do_rm -- remove a file */ static void do_rm(pname, fname, iflag) char *pname, *fname; BOOLEAN iflag; { int result = 0; struct stat statbuf; static BOOLEAN affirm(); if (iflag == TRUE) { fprintf(stderr, "%s (y/n): ", fname); if (affirm() == FALSE) return; } if ((result = unlink(fname)) == -1) { fprintf(stderr, "%s: ", pname); perror(fname); } return; } /* * affirm -- return TRUE if the first character of the * user's response is 'y' or FALSE otherwise */ #define MAXSTR 64 static BOOLEAN affirm() { char line[MAXSTR + 1]; char *response; response = fgets(line, MAXSTR, stdin); return (tolower(*response) == 'y' ? TRUE : FALSE); } ls.h ─────────────────────────────────────────────────────────────────────────── /* * ls.h -- header file for ls program */ /* structure definition for output buffer elements */ struct OUTBUF { unsigned short o_mode; /* file mode (attributes) */ long o_size; /* file size in bytes */ unsigned int o_date; /* file modification date */ unsigned int o_time; /* file modification time */ char *o_name; /* DOS filespec */ }; /* constants for DOS file-matching routines */ #define FILESPEC 13 /* maximum filespec + NUL */ #define RNBYTES 21 /* bytes reserved for next_fm() calls */ /* file modes (attributes) */ #define READONLY 0x0001 #define HIDDEN 0x0002 #define SYSTEM 0x0004 #define VOLUME 0x0008 #define SUBDIR 0x0010 #define ARCHIVE 0x0020 /* structure definition for DOS file-matching routines */ struct DTA { unsigned char d_reserved[RNBYTES]; /* buffer for next_fm */ unsigned char d_attr; /* file attribute (type) byte */ unsigned d_mtime; /* time of last modification */ unsigned d_mdate; /* date of last modification */ long d_fsize; /* file size in bytes */ char d_fname[FILESPEC]; /* file spec (filename.ext + NUL) */ }; ls ─────────────────────────────────────────────────────────────────────────── /* * ls -- display a directory listing */ #include <stdio.h> #include <stdlib.h> #include <string.h> #include <memory.h> #include <dos.h> #include <direct.h> #include <signal.h> #include <search.h> #include <local\std.h> #include <local\doslib.h> #include "ls.h" /* allocation quantities */ #define N_FILES 256 #define N_DIRS 16 /* global data */ int Multicol = 0; int Filetype = 0; int Hidden = 0; int Longlist = 0; int Reverse = 0; int Modtime = 0; main(argc, argv) int argc; char *argv[]; { int ch, i; int errflag; /* error flag */ char *ep; /* environment pointer */ int status = 0; /* return status value */ int fileattr; /* file attribute number */ struct DTA buf; /* private disk buffer */ char path[MAXPATH + 1]; /* working pathname */ struct OUTBUF *fp, *fq; /* pointers to file array */ char **dp, **dq; /* pointer to directory pointer array */ int fbc = 1; /* file memory block allocation count */ int dbc = 1; /* directory memory block allocation */ /* count */ int nfiles; /* number of file elements */ int ndirs; /* number of directory elements */ static char pgm[MAXNAME + 1] = { "ls" }; /* function prototypes */ void getpname(char *, char *); extern int getopt(int, char **, char *); extern int optind, opterr; extern char *optarg; extern char *drvpath(char *); extern void fatal(char *, char *, int); extern void setdta(char *); extern int first_fm(char *, int); extern int next_fm(); extern int ls_fcomp(struct OUTBUF *, struct OUTBUF *); extern int ls_dcomp(char *, char *); extern int ls_single(struct OUTBUF *, int); extern int ls_multi(struct OUTBUF *, int); extern int ls_dirx(char *, char *); int bailout(); /* guarantee that needed DOS services are available */ if (_osmajor < 2) fatal(pgm, "ls requires DOS 2.00 or later", 1); /* get program name from DOS (version 3.00 and later) */ if (_osmajor >= 3) getpname(*argv, pgm); /* useful aliases (DOS version 3.00 and later) */ if (strcmp(pgm, "lc") == 0) ++Multicol; if (strcmp(pgm, "lf") == 0) { ++Multicol; ++Filetype; } /* prepare for emergencies */ if (signal(SIGINT, bailout) == (int(*)())-1) { perror("Can't set SIGINT"); exit(2); } /* process optional arguments first */ errflag = 0; while ((ch = getopt(argc, argv, "aCFlrt")) != EOF) switch (ch) { case 'a': /* all files (hidden, system, etc.) */ ++Hidden; break; case 'C': ++Multicol; break; case 'F': /* show file types (/=directory, *=executable) */ ++Filetype; break; case 'l': /* long list (overrides multicolumn) */ ++Longlist; break; case 'r': /* reverse sort */ ++Reverse; break; case 't': /* sort by file modification time */ ++Modtime; break; case '?': errflag = TRUE; break; } argc -= optind; argv += optind; /* check for command-line errors */ if (argc < 0 || errflag) { fprintf(stderr, "Usage: %s [-aCFlrt] [pathname ...]", pgm); exit(3); } /* allocate initial file and directory storage areas */ dp = dq = (char **)malloc(N_DIRS * sizeof (char *)); if (dp == NULL) fatal(pgm, "Out of memory", 4); fp = fq = (struct OUTBUF *)malloc(N_FILES * sizeof (struct OUTBUF)); if (fp == NULL) fatal(pgm, "Out of memory", 4); nfiles = ndirs = 0; /* use current directory if no args */ if (argc == 0) { if (getcwd(path, MAXPATH) == NULL) fatal(pgm, "Cannot get current directory", 5); *dq = path; ndirs = 1; } else { /* use arguments as file and directory names */ for ( ; argc-- > 0; ++argv) { strcpy(path, *argv); if (path[0] == '\\') { /* prepend default drive name */ memcpy(path + 2, path, strlen(path) + 1); path[0] = 'a' + getdrive(); path[1] = ':'; } if (path[1] == ':' && path[2] == '\0' && drvpath(path) == NULL) { fprintf(stderr, "%s: Cannot get drive path", pgm); continue; } /* establish private disk transfer area */ setdta((char *)&buf); /* set file attribute for search */ if (Hidden) fileattr = SUBDIR | HIDDEN | SYSTEM | READONLY; else fileattr = SUBDIR; if (first_fm(path, fileattr) != 0 && path[3] != '\0') { fprintf(stderr, "%s -- No such file or directory\n", path); continue; } if ((buf.d_attr & SUBDIR) == SUBDIR || path[3] == '\0') { /* path is a (sub)directory */ *dq = strdup(path); if (++ndirs == dbc * N_DIRS) { ++dbc; /* increase space */ /* requirement */ dp = (char **)realloc(dp, dbc * N_DIRS * sizeof (char *)); if (dp == NULL) fatal(pgm, "Out of memory", 4); dq = dp + dbc * N_DIRS; } else ++dq; } else { fq->o_name = strdup(path); fq->o_mode = buf.d_attr; fq->o_date = buf.d_mdate; fq->o_time = buf.d_mtime; fq->o_size = buf.d_fsize; if (++nfiles == fbc * N_FILES) { ++fbc; fp = (struct OUTBUF *)realloc(fp, fbc * N_FILES * sizeof (struct OUTBUF)); if (fp == NULL) fatal(pgm, "Out of memory", 4); fq = fp + fbc * N_FILES; } else ++fq; } } } /* output file list, if any */ if (nfiles > 0) { qsort(fp, nfiles, sizeof(struct OUTBUF), ls_fcomp); if (Longlist) ls_long(fp, nfiles); else if (Multicol) ls_multi(fp, nfiles); else ls_single(fp, nfiles); putchar('\n'); } free(fp); /* output directory lists, if any */ if (ndirs == 1 && nfiles == 0) { /* expand directory and output without header */ if (ls_dirx(pgm, *dp)) fprintf(stderr, "%s -- empty directory\n", strlwr(*dp)); } else if (ndirs > 0) { /* expand each directory and output with headers */ dq = dp; qsort(dp, ndirs, sizeof(char *), ls_dcomp); while (ndirs-- > 0) { fprintf(stdout, "%s:\n", strlwr(*dq)); if (ls_dirx(pgm, *dq++)) fprintf(stderr, "%s -- empty directory\n", strlwr(*dq)); putchar('\n'); } } exit(0); } /* * bailout -- optionally terminate upon interrupt */ int bailout() { char ch; signal(SIGINT, bailout); printf("\nTerminate directory listing? "); scanf("%1s", &ch); if (ch == 'y' || ch == 'Y') exit(1); } drvpath ─────────────────────────────────────────────────────────────────────────── /* * drvpath -- convert a drive name to a full pathname */ #include <stdio.h> #include <dos.h> #include <string.h> #include <ctype.h> #include <local\doslib.h> char * drvpath(path) char path[]; /* path string */ /* must be large enough to hold a full DOS path + NUL */ { union REGS inregs, outregs; static int drive(char); /* patch root directory onto drive name */ strcat(path, "\\"); /* set current directory path for drive from DOS */ inregs.h.ah = GET_CUR_DIR; inregs.h.dl = drive(path[0]); /* convert to drive number */ inregs.x.si = (unsigned)&path[3]; /* start of return string */ intdos(&inregs, &outregs); return (outregs.x.cflag ? (char *)NULL : path); } static int drive(dltr) char dltr; /* drive letter */ { /* 'A' (or 'a') => 1, 'B' (or 'b') => 2, etc. */ return (tolower(dltr) - 'a' + 1); } ls_fcomp ─────────────────────────────────────────────────────────────────────────── /* * ls_fcomp -- file and directory comparison functions */ #include <string.h> #include "ls.h" extern int Modtime; extern int Reverse; /* * ls_fcomp -- compare two "file" items */ int ls_fcomp(s1, s2) struct OUTBUF *s1, *s2; { int result; if (Modtime) { if ((result = s1->o_date - s2->o_date) == 0) result = s1->o_time - s2->o_time; } else result = strcmp(s1->o_name, s2->o_name); return (Reverse ? -result : result); } /* end_fcomp() */ /* * dcomp -- compare two "directory" items */ int ls_dcomp(s1, s2) char *s1, *s2; { int result; result = strcmp(s1, s2); return (Reverse ? -result : result); } /* end ls_dcomp() */ ls_list ─────────────────────────────────────────────────────────────────────────── /* * ls_list -- list functions (long, single, multi) for ls */ #include <stdio.h> #include <string.h> #include "ls.h" #define MAXCOL 80 #define MONTH_SHIFT 5 #define MONTH_MASK 0x0F #define DAY_MASK 0x1F #define YEAR_SHIFT 9 #define DOS_EPOCH 80 #define HOUR_SHIFT 11 #define HOUR_MASK 0x1F #define MINUTE_SHIFT 5 #define MINUTE_MASK 0x3F extern int Filetype; /* * ls_long -- list items in "long" format (mode time size name) */ int ls_long(buf, nelem) struct OUTBUF *buf; int nelem; { int n = 0; char modebuf[5]; static void modestr(unsigned short, char *); while (nelem-- > 0) { /* convert mode number to a string */ modestr(buf->o_mode, modebuf); printf("%s ", modebuf); /* display file size in bytes */ printf("%7ld ", buf->o_size); /* convert date and time values to formatted presentation */ printf("%02d-%02d-%02d ", (buf->o_date >> MONTH_SHIFT) & MONTH_MASK, buf->o_date & DAY_MASK, (buf->o_date >> YEAR_SHIFT) + DOS_EPOCH); printf("%02d:%02d ", (buf->o_time >> HOUR_SHIFT) & HOUR_MASK, (buf->o_time >> MINUTE_SHIFT) & MINUTE_MASK); /* display filenames as lowercase strings */ printf("%s\n", strlwr(buf->o_name)); ++buf; ++n; } /* tell caller how many entries were printed */ return (n); } /* end ls_long() */ /* * ls_single -- list items in a single column */ int ls_single(buf, nelem) struct OUTBUF *buf; int nelem; { int n = 0; while (nelem-- > 0) { printf("%s", strlwr(buf->o_name)); if (Filetype && (buf->o_mode & SUBDIR) == SUBDIR) putchar('\\'); putchar('\n'); ++buf; ++n; } /* tell caller how many entries were printed */ return (n); } /* end ls_single() */ /* * ls_multi -- list items in multiple columns that * vary in width and number based on longest item size */ int ls_multi(buf, nelem) struct OUTBUF *buf; int nelem; { int i, j; int errcount = 0; struct OUTBUF *tmp; /* temporary buffer pointer */ struct OUTBUF *base; /* buffer pointer for multi-col output */ int n; /* number of items in list */ int len, maxlen; /* pathname lengths */ int ncols; /* number of columns to output */ int nlines; /* number of lines to output */ /* * get length of longest pathname and calculate number * of columns and lines (col width = maxlen + 1) */ tmp = buf; n = 0; maxlen = 0; for (tmp = buf, n = 0; n < nelem; ++tmp, ++n) if ((len = strlen(tmp->o_name)) > maxlen) maxlen = len; /* * use width of screen - 1 to allow for newline at end of * line and leave two spaces between entries (one for optional * file type flag) */ ncols = (MAXCOL - 1) / (maxlen + 2); nlines = n / ncols; if (n % ncols) ++nlines; /* output multi-column list */ base = buf; for (i = 0; i < nlines; ++i) { tmp = base; for (j = 0; j < ncols; ++j) { len = maxlen + 2; len -= printf("%s", strlwr(tmp->o_name)); if (Filetype && (tmp->o_mode & SUBDIR) == SUBDIR) { putchar('\\'); --len; } while (len-- > 0) putchar(' '); tmp += nlines; if (tmp - buf >= nelem) break; } putchar('\n'); ++base; } return (errcount); } /* end ls_multi() */ static void modestr(mode, s) unsigned short mode; /* file mode number */ char s[]; /* mode string buffer */ { /* fill in the mode string to show what's set */ s[0] = (mode & SUBDIR) == SUBDIR ? 'd' : '-'; s[1] = (mode & HIDDEN) == HIDDEN ? 'h' : '-'; s[2] = (mode & SYSTEM) == SYSTEM ? 's' : '-'; s[3] = (mode & READONLY) == READONLY ? 'r' : '-'; s[4] = '\0'; } /* end modestr() */ ls_dirx ─────────────────────────────────────────────────────────────────────────── /* * ls_dirx -- expand the contents of a directory using * the DOS first/next matching file functions */ #include <stdio.h> #include <stdlib.h> #include <string.h> #include <malloc.h> #include <dos.h> #include <direct.h> #include <signal.h> #include <search.h> #include <local\std.h> #include <local\doslib.h> #include "ls.h" #define NFILES 1024 extern int Recursive; extern int Longlist; extern int Multicol; extern int Hidden; int ls_dirx(pname, namep) char *pname; char *namep; { int status = 0; /* function return value */ int n; /* number of items found */ int fileattr; /* attributes of file-matching */ struct DTA buf; /* disk transfer area */ struct OUTBUF *bp, *bq; /* output buffer pointers */ char path[MAXPATH + 1]; /* working path string */ extern void setdta(char *); extern int first_fm(char *, int); extern int next_fm(); extern int ls_fcomp(struct OUTBUF *, struct OUTBUF *); extern char last_ch(char *); /* allocate a buffer */ bp = bq = (struct OUTBUF *)malloc(NFILES * sizeof(struct OUTBUF)); if (bp == NULL) fatal(pname, "Out of memory"); /* form name for directory search */ strcpy(path, namep); if (last_ch(path) != '\\') strcat(path, "\\"); strcat(path, "*.*"); /* list the files found */ n = 0; /* establish a private DTA */ setdta((char *)&buf); /* select file attributes */ if (Hidden) fileattr = SUBDIR | HIDDEN | SYSTEM | READONLY; else fileattr = SUBDIR; if (first_fm(path, fileattr) == 0) { /* add file or directory to the buffer */ do { if (!Hidden && buf.d_fname[0] == '.') continue; bq->o_name = strdup(buf.d_fname); bq->o_mode = buf.d_attr; bq->o_size = buf.d_fsize; bq->o_date = buf.d_mdate; bq->o_time = buf.d_mtime; ++bq; ++n; setdta((char *)&buf); /* reset to our DTA */ } while (next_fm() == 0); if (n > 0) { /* got some -- sort and list them */ qsort(bp, n, sizeof(struct OUTBUF), ls_fcomp); if (Longlist) ls_long(bp, n); else if (Multicol) ls_multi(bp, n); else ls_single(bp, n); } } else ++status; free(bp); return (status); } first_fm ─────────────────────────────────────────────────────────────────────────── /* * first_fm - find first file match in work directory */ #include <dos.h> #include <local\doslib.h> int first_fm(path, fa) char *path; /* pathname of directory */ int fa; /* attribute(s) of file to match */ { union REGS inregs, outregs; /* find first matching file */ inregs.h.ah = FIND_FIRST; inregs.x.cx = fa; inregs.x.dx = (unsigned int)path; (void)intdos(&inregs, &outregs); return (outregs.x.cflag); } /* * next_fm - find next file match in work directory */ #include <dos.h> #include <local\doslib.h> int next_fm() { union REGS inregs, outregs; /* find next matching file */ inregs.h.ah = FIND_NEXT; (void)intdos(&inregs, &outregs); return (outregs.x.cflag); } makefile for the LS program ─────────────────────────────────────────────────────────────────────────── # makefile for the LS program LIB=c:\lib LLIB=c:\lib\local first_fm.obj: first_fm.c msc $*; lib $(LLIB)\dos -+ $*; next_fm.obj: next_fm.c msc $*; lib $(LLIB)\dos -+ $*; setdta.obj: setdta.c msc $*; lib $(LLIB)\dos -+ $*; getdrive.obj: getdrive.c msc $*; lib $(LLIB)\dos -+ $*; drvpath.obj: drvpath.c msc $*; lib $(LLIB)\dos -+ $*; ls_fcomp.obj: ls_fcomp.c ls.h msc $*; ls_dirx.obj: ls_dirx.c ls.h msc $*; ls_list.obj: ls_list.c ls.h msc $*; ls.obj: ls.c ls.h msc $*; ls.exe: ls.obj ls_dirx.obj ls_fcomp.obj ls_list.obj \ $(LLIB)\util.lib $(LLIB)\dos.lib link $* ls_dirx ls_fcomp ls_list $(LIB)\ssetargv, $*,, $(LLIB)\util $(LLIB)\dos; pr_help ─────────────────────────────────────────────────────────────────────────── /* * pr_help -- display an abbreviated manual page */ #include <stdio.h> #include <local\std.h> void pr_help(pname) char *pname; { static char *m_str[] = { "The following options may be used singly or in "combination:", "-e\t set Epson-compatible mode", "-f\t use formfeed to eject a page (default is newlines)", "-g\t use generic printer mode", "-h hdr\t use specified header instead of filename", "-l len\t set page length in lines (default = 66)", "-n\t enable line-numbering (default = off)", "-o cols\t offset from left edge in columns (default = 5)", "-p\t preview output on screen (may be redirected)", "-s list\t print only selected pages", "-w cols\t line width in columns (default = 80)" }; int i, n = sizeof (m_str)/ sizeof (char *); fprintf(stderr, "Usage: %s [options] file...\n\n", pname); for (i = 0; i < n; ++i) fprintf(stderr, "%s\n", m_str[i]); return; } print.h ─────────────────────────────────────────────────────────────────────────── /* * print.h -- header information for print programs */ /* default printing format information */ #define BOTTOM 3 /* blank lines at bottom of page */ #define MARGIN 5 /* default margin width in columns */ #define MAXPCOL 80 /* maximum number of printed columns per line */ #define MAXPSTR 64 /* maximum characters in a string variable */ #define PAGELEN 66 /* default page length (at 6 lines per inch) */ #define LPI 6 /* default lines per inch */ #define TABSPEC 8 /* default tab separation */ #define TOP1 2 /* blank lines above header line */ #define TOP2 2 /* blank lines below header line */ /* primary data structure for printer programs */ typedef struct pr_st { /* numeric variables */ int p_top1; /* lines above header */ int p_top2; /* lines below header */ int p_btm; /* lines in footer */ int p_wid; /* width in columns */ int p_lmarg; /* left margin */ int p_rmarg; /* right margin */ int p_len; /* lines per page */ int p_lpi; /* lines per inch */ int p_lnum; /* nonzero turns line-numbering on */ int p_mode; /* zero for generic printer */ int p_font; /* font number when in nongeneric mode */ int p_ff; /* nonzero uses formfeed to eject page */ int p_tabint; /* tab interval */ /* string variables */ char p_hdr[MAXPSTR]; char p_dest[MAXPSTR]; } PRINT; pr ─────────────────────────────────────────────────────────────────────────── /* * pr -- file printer */ #include <stdio.h> #include <stdlib.h> #include <dos.h> #include <local\std.h> #include "print.h" char Pagelist[MAXLINE]; main(argc, argv) int argc; char **argv; { int ch; BOOLEAN errflag; extern PRINT pcnf; static char pgm[MAXNAME + 1] = { "pr" }; extern char getpname(char *, char *); extern int getopt(int, char **, char *); extern char *optarg; extern int optind, opterr; extern int pr_gcnf(char *); extern pr_file(char *, int, char **); extern void pr_help(char *); extern void fixtabs(int); extern int setprnt(); if (_osmajor >= 3) getpname(*argv, pgm); /* do configuration */ if (pr_gcnf(pgm) != 0) { fprintf(stderr, "%s: Configuration error", pgm); exit(2); } if (setprnt() == -1) { fprintf(stderr, "%s: Bad printer configuration\n", pgm); exit(1); } fixtabs(pcnf.p_tabint); /* process command-line arguments */ while ((ch = getopt(argc, argv, "efgh:l:no:ps:w:")) != EOF) { switch (ch) { case 'e': /* force "Epson-compatible " printer mode */ pcnf.p_mode = 1; break; case 'f': /* use formfeed to eject a page */ pcnf.p_ff = 1; break; case 'g': /* force "generic" printer mode */ pcnf.p_mode = 0; break; case 'h': /* use specified header */ strcpy(pcnf.p_hdr, optarg); break; case 'l': /* set lines per page */ pcnf.p_len = atoi(optarg); break; case 'n': /* enable line-numbering */ pcnf.p_lnum = 1; break; case 'o': /* set left margin */ pcnf.p_lmarg = atoi(optarg); break; case 'p': /* preview output on screen */ strcpy(pcnf.p_dest, ""); break; case 's': /* output selected pages */ strcpy(Pagelist, optarg); break; case 'w': /* set page width in columns */ pcnf.p_wid = atoi(optarg); break; case '?': /* unknown option */ errflag = TRUE; break; } } if (errflag == TRUE) { pr_help(pgm); exit(3); } /* print the files */ pr_file(pgm, argc - optind, argv += optind); exit(0); } pr_gcnf ─────────────────────────────────────────────────────────────────────────── /* * pr_gcnf -- get configuration for pr program */ #include <stdio.h> #include <string.h> #include <local\std.h> #include <local\printer.h> #include "print.h" /* expected number of configuration items */ #define N_NBR 12 PRINT pcnf; int pr_gcnf(pname) char *pname; { char line[MAXLINE]; char *s; int cnf[N_NBR]; int n, errcount, good; FILE *fp, *fconfig(char *, char *); /* get configuration file values, if any */ n = good = errcount = 0; if ((fp = fconfig("CONFIG", "pr.cnf")) != NULL) { while (n < N_NBR && (s = fgets(line, MAXLINE, fp)) != NULL) { cnf[n] = atoi(s); ++n; } if ((s = fgets(line, MAXLINE, fp)) == NULL) ++errcount; else strcpy(pcnf.p_dest, strtok(line, " \t\n")); if (n != N_NBR) ++errcount; if (errcount == 0) good = 1; if (fclose(fp) == -1) fatal(pname, "cannot close config file", 1); } /* use config data if good; use defaults otherwise */ pcnf.p_top1 = good ? cnf[0]: TOP1; pcnf.p_top2 = good ? cnf[1] : TOP2; pcnf.p_btm = good ? cnf[2] : BOTTOM; pcnf.p_wid = good ? cnf[3] : MAXPCOL; pcnf.p_lmarg = good ? cnf[4] : MARGIN; pcnf.p_rmarg = good ? cnf[5] : MARGIN; pcnf.p_len = good ? cnf[6] : PAGELEN; pcnf.p_lpi = good ? cnf[7] : LPI; pcnf.p_mode = good ? cnf[8] : 0; pcnf.p_lnum = good ? cnf[9] : 0; pcnf.p_ff = good ? cnf[10] : 0; pcnf.p_tabint = good ? cnf[11] : TABSPEC; if (!good) strcpy(pcnf.p_dest, "PRN"); if (pcnf.p_mode == 1) pcnf.p_font = CONDENSED; strcpy(pcnf.p_hdr, ""); return (errcount); } pr_file ─────────────────────────────────────────────────────────────────────────── /* * pr_file -- process each filename or standard input */ #include <stdio.h> #include <stdlib.h> #include <string.h> #include <local\std.h> #include "print.h" int pr_file(pname, ac, av) char *pname; int ac; char **av; { int ch, errcount = 0; FILE *fin, *fout; extern PRINT pcnf; extern void fatal(char*, char*, int); extern int pr_cpy(FILE *, FILE *, char *); /* open output stream only if not already open */ if (*pcnf.p_dest == '\0' || strcmp(pcnf.p_dest, "CON") == 0) fout = stdout; else if (strcmp(pcnf.p_dest, "PRN") == 0) fout = stdprn; else if (strcmp(pcnf.p_dest, "AUX") == 0) fout = stdaux; else if ((fout = fopen(pcnf.p_dest, "w")) == NULL) fatal(pname, "Error open destination stream", 1); /* prepare input stream */ if (ac == 0) pr_cpy(stdin, fout, ""); else { for (; ac > 0; --ac, ++av) { if ((fin = fopen(*av, "r")) == NULL) { fprintf(stderr, "%s: Error opening %s\n", pname, *av); continue; } if (pr_cpy(fin, fout, *av) == -1) { fprintf(stderr, "%s: Cannot stat %s", pname, *av); continue; } if (fclose(fin) == EOF) fatal(pname, "Error closing input file", 1); } } return (errcount); } pr_cpy ─────────────────────────────────────────────────────────────────────────── /* * pr_cpy -- copy input stream to output stream */ #include <stdio.h> #include <string.h> #include <local\std.h> #include <local\printer.h> #include <sys\types.h> #include <sys\stat.h> #include <time.h> #include "print.h" extern PRINT pcnf; extern char Pagelist[MAXLINE]; extern long Highest; int pr_cpy(fin, fout, fname) FILE *fin; FILE *fout; char *fname; { int errcount = 0; unsigned int p_line; /* page-relative line number */ long f_line; /* file-relative line number */ long f_page; /* file-relative page number */ int lnlen; /* line length */ char line[MAXLINE]; /* input line buffer */ struct stat tbuf; /* file information */ long ltime; /* date and time */ FILE *fnull, *fx; /* additional output file pointers */ extern void mkslist(char *); /* make a selection list */ extern int selected(long); /* is item in the list? */ extern int spaces(int, FILE *); /* emit string of spaces */ extern int setfont(int, FILE *);/* set printer font type */ extern int clrprnt(FILE *); /* clear special fonts */ extern int lines(int, FILE *); /* emit string of blank lines */ static int fit(int, int); /* will line fit on page? */ extern int pr_line(char *, FILE *, unsigned int); /* install page selection list, if any */ if (Pagelist[0] != '\0') { /* open the NUL device for dumping output */ if ((fnull = fopen("NUL", "w")) == NULL) { perror("Error opening NUL device"); exit(1); } mkslist(Pagelist); } else Highest = BIGGEST; /* get date and time stamp */ if (*fname == '\0') /* using stdin -- use today's date and time */ ltime = time(NULL); else { if (stat(fname, &tbuf) == -1) return (-1); /* use file's modification time */ ltime = tbuf.st_mtime; } p_line = 0; f_line = 1; f_page = 1; while ((lnlen = pr_getln(line, MAXLINE, fin)) > 0 ) { /* if formfeed or no room for line, eject page */ if (line[0] == '\f' || !fit(lnlen, p_line)) { /* to top of next page */ if (pcnf.p_ff == 0) lines(pcnf.p_len - p_line, fx); else fputc('\f', fx); p_line = 0; } /* if at top of page, print the header */ if (p_line == 0) { if (f_page > Highest) break; fx = selected(f_page) ? fout : fnull; p_line += lines(pcnf.p_top1, fx); if (pcnf.p_mode != 0) setfont(EMPHASIZED, fx); spaces(pcnf.p_lmarg, fx); if (*pcnf.p_hdr != '\0') fprintf(fx, "%s ", pcnf.p_hdr); else if (*fname != '\0') fprintf(fx, "%s ", strupr(fname)); fprintf(fx, "Page %u ", f_page++); fputs(ctime(<ime), fx); ++p_line; if (pcnf.p_mode != 0) setfont(pcnf.p_font, fx); p_line += lines(pcnf.p_top2, fx); } /* OK to output the line */ if (line[0] != '\f') p_line += pr_line(line, fx, f_line++); } if (ferror(fin) != 0) ++errcount; if (p_line > 0 && p_line < pcnf.p_len) if (pcnf.p_ff == 0) lines(pcnf.p_len - p_line, fx); else fputc('\f', fx); if (pcnf.p_mode != 0) clrprnt(fx); return (errcount); } /* * fit -- return nonzero value if enough physical * lines are available on the current page to take * the current logical line of text */ #define NFLDWIDTH 8 /* width of number field */ static int fit(len, ln) int len, ln; { int need, left; /* physical lines */ int cols; /* columns of actual output */ int lw; /* displayable line width */ /* total need (columns -> physical lines) */ cols = len + (pcnf.p_lnum > 0 ? NFLDWIDTH : 0); lw = pcnf.p_wid - pcnf.p_lmarg - pcnf.p_rmarg; need = 1 + cols / lw; /* lines remaining on page */ left = pcnf.p_len - ln - pcnf.p_btm; return (need <= left ? 1 : 0); } pr_getln ─────────────────────────────────────────────────────────────────────────── /* * pr_getln -- get a line of text while expanding tabs; * put text into an array and return the length of the line * including termination to the calling function. */ #include <stdio.h> #include <stdlib.h> #include <local\std.h> int pr_getln(s, lim, fin) char *s; int lim; FILE *fin; { int ch; register char *cp; extern int tabstop(); /* query tabstop array */ cp = s; while (--lim > 0 && (ch = fgetc(fin)) != EOF && ch != '\n' && ch != '\f') { if (ch == '\t') /* loop and store spaces until next tabstop */ do *cp++ = ' '; while (--lim > 0 && tabstop(cp - s) == 0); else *cp++ = ch; } if (ch == EOF && cp - s == 0) ; else if (ch == EOF || ch == '\n') *cp++ = '\n'; /* assure correct line termination */ else if (ch == '\f' && cp - s == 0) { *cp++ = '\f'; fgetc(fin); /* toss the trailing newline */ } *cp = '\0'; return (cp - s); } pr_line ─────────────────────────────────────────────────────────────────────────── /* * pr_line -- ouput a buffered logical line and * return a count of physical lines produced */ #include <stdio.h> #include <stdlib.h> #include <local\std.h> #include "print.h" int pr_line(s, fout, rline) char *s; /* buffered line of text */ FILE *fout; /* output stream */ unsigned int rline; /* file-relative line number */ { int c_cnt; /* character position in output line */ int nlines; /* number of lines output */ extern PRINT pcnf; extern int spaces(int, FILE *); /* emit string of spaces */ nlines = 1; c_cnt = 0; /* output the left indentation, if any */ c_cnt += spaces(pcnf.p_lmarg, fout); /* output the line number if numbering enabled */ if (pcnf.p_lnum != 0) c_cnt += fprintf(fout, "%6u ", rline); /* output the text of the line */ while (*s != '\0') { if (c_cnt > (pcnf.p_wid - pcnf.p_rmarg)) { fputc('\n', fout); ++nlines; c_cnt = 0; c_cnt = spaces(pcnf.p_lmarg, fout); } fputc(*s, fout); ++s; ++c_cnt; } return (nlines); } makefile for the pr program ─────────────────────────────────────────────────────────────────────────── # makefile for the pr program LINC=c:\include\local LIB=c:\lib LLIB=c:\lib\local pr_cpy.obj: pr_cpy.c print.h $(LINC)\printer.h msc $*; lib prlib -+$*; pr_file.obj: pr_file.c print.h msc $*; lib prlib -+$*; pr_getln.obj: pr_getln.c msc $*; lib prlib -+$*; pr_help.obj: pr_help.c msc $*; lib prlib -+$*; pr_gcnf.obj: pr_gcnf.c print.h $(LINC)\printer.h msc $*; lib prlib -+$*; pr_line.obj: pr_line.c print.h msc $*; lib prlib -+$*; pr.obj: pr.c print.h msc $*; pr.exe: pr.obj prlib.lib $(LLIB)\util.lib link $* $(LIB)\ssetargv, $*,, prlib $(LLIB)\util; hex.c ─────────────────────────────────────────────────────────────────────────── /* * hex.c -- hex conversions routines */ #define NIBBLE 0x000F #define BYTE 0x00FF #define WORD 0xFFFF char hextab[] = { '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'A', 'B', 'C', 'D', 'E', 'F' }; /* * byte2hex -- convert a byte to a string * representation of its hexadecimal value */ char * byte2hex(data, buf) unsigned char data; char *buf; { char *cp; unsigned int d; d = data & BYTE; cp = buf; *cp++ = hextab[(d >> 4) & NIBBLE]; *cp++ = hextab[d & NIBBLE]; *cp = '\0'; return (buf); } /* * word2hex -- convert a word to a string * representation of its hexadecimal value */ char * word2hex(data, buf) unsigned int data; char *buf; { char *cp; unsigned int d; d = data & WORD; cp = buf; *cp++ = hextab[(d >> 12) & NIBBLE]; *cp++ = hextab[(d >> 8) & NIBBLE]; *cp++ = hextab[(d >> 4) & NIBBLE]; *cp++ = hextab[d & NIBBLE]; *cp = '\0'; return (buf); } dump ─────────────────────────────────────────────────────────────────────────── /* * dump -- display contents of non-ASCII files in hex byte and * ASCII character forms (like the DOS debug dump option) */ #include <stdio.h> #include <stdlib.h> #include <fcntl.h> #include <sys\types.h> #include <sys\stat.h> #include <io.h> #include <local\std.h> #define STDINPUT 0 #define LINEWIDTH 80 main(argc,argv) int argc; char *argv[]; { int ch; BOOLEAN sflag = FALSE, vflag = FALSE, errflag = FALSE; int fd; static char pgm[MAXNAME + 1] = { "dump" }; extern int getopt(int, char **, char *); extern char *optarg; extern int optind, opterr; extern void getpname(char *, char *); extern int hexdump(int, BOOLEAN); extern void fatal(char *, char *, int); if (_osmajor >= 3) getpname(*argv, pgm); while ((ch = getopt(argc, argv, "sv")) != EOF) switch (ch) { case 's': /* strip -- convert all non-ASCII to '.' */ sflag = TRUE; break; case 'v': /* verbose -- tell user what's happening */ vflag = TRUE; break; case '?': /* bad option */ errflag = TRUE; break; } if (errflag == TRUE) { fprintf(stderr, "Usage: %s [-sv] [file...]\n", pgm); exit(1); } if (optind == argc) { if (setmode(STDINPUT, O_BINARY) == -1) fatal(pgm, "Cannot set binary mode", 2); hexdump(STDINPUT, sflag); exit(0); } for ( ; optind < argc; ++optind) { if ((fd = open(argv[optind], O_BINARY | O_RDONLY)) == -1) { fprintf(stderr, "%s: Error opening %s -- ", pgm, argv[optind]); perror(""); continue; } if (vflag == TRUE) fprintf(stdout, "\n%s:\n", argv[optind]); if (hexdump(fd, sflag) == FAILURE) { fprintf(stderr, "%s: Error reading %s -- ", pgm, argv[optind]); perror(""); } if (close(fd) == -1) fatal(pgm, "Error closing input file", 3); } exit(0); } hexdump ─────────────────────────────────────────────────────────────────────────── /* * hexdump -- read data from an open file and "dump" * it in side-by-side hex and ASCII to standard output */ #include <stdio.h> #include <stdlib.h> #include <ctype.h> #include <local\std.h> #define LINEWIDTH 80 #define NBYTES 16 #define WORD 0xFFFF #define RGHTMARK 179 #define LEFTMARK 179 #define DEL 0x7F int hexdump(fd, strip) int fd; BOOLEAN strip; { unsigned char i; int n; /* bytes per read operation */ unsigned long offset; /* bytes from start of file */ char inbuf[BUFSIZ + 1], outbuf[LINEWIDTH + 1]; char hexbuf[5]; register char *inp, *outp; extern char *byte2hex(unsigned char, char *); extern char *word2hex(unsigned int, char *); offset = 0; while ((n = read(fd, inbuf, BUFSIZ)) != 0) { if (n == -1) return FAILURE; inp = inbuf; while (inp < inbuf + n) { outp = outbuf; /* offset in hex */ outp += sprintf(outp, "%08lX", offset + (unsigned long)(inp - inbuf)); *outp++ = ' '; /* block of bytes in hex */ for (i = 0; i < NBYTES; ++i) { *outp++ = ' '; strcpy(outp, byte2hex(*inp++, hexbuf)); outp += 2; } *outp++ = ' '; *outp++ = ' '; *outp++ = (strip == TRUE) ? '|' : LEFTMARK; /* same block of bytes in ASCII */ inp -= NBYTES; for (i = 0; i < NBYTES; ++i) { if (strip == TRUE && (*inp < ' ' || *inp >= DEL)) *outp = '.'; else if (iscntrl(*inp)) *outp = '.'; else *outp = *inp; ++inp; ++outp; } *outp++ = (strip == TRUE) ? '|' : RGHTMARK; *outp++ = '\n'; *outp = '\0'; fputs(outbuf, stdout); } offset += n; } return SUCCESS; } show ─────────────────────────────────────────────────────────────────────────── /* * show -- a filter that displays the contents of a file * in a way that is guaranteed to be displayable */ #include <stdio.h> #include <stdlib.h> #include <fcntl.h> #include <io.h> #include <local\std.h> main(argc, argv) int argc; char **argv; { int ch; FILE *fp; BOOLEAN sflag = FALSE; /* strip non-ASCII characters */ BOOLEAN vflag = FALSE; /* verbose mode */ BOOLEAN wflag = FALSE; /* filter typical word-processing codes */ BOOLEAN errflag = FALSE; static char pgm[] = { "show" }; extern int getopt(int, char **, char *); extern char *optarg; extern int optind, opterr; extern int showit(FILE *, BOOLEAN, BOOLEAN); extern void fatal(char *, char *, int); if (_osmajor >= 3) getpname(*argv, pgm); while ((ch = getopt(argc, argv, "svw")) != EOF) { switch (ch) { case 's': /* strip non-ASCII characters */ sflag = TRUE; break; case 'v': /* verbose */ vflag = TRUE; break; case 'w': /* use word-processing conventions */ wflag = sflag = TRUE; break; case '?': errflag = TRUE; break; } } /* check for errors */ if (errflag == TRUE) { fprintf(stderr, "Usage: %s [-sv] [file...]\n", pgm); exit(1); } /* if no file names, use standard input */ if (optind == argc) { if (setmode(fileno(stdin), O_BINARY) == -1) fatal(pgm, "Cannot set binary mode on stdin", 2); showit(stdin, sflag, wflag); exit(0); } /* otherwise, process remainder of command line */ for ( ; optind < argc; ++optind) { if ((fp = fopen(argv[optind], "rb")) == NULL) { fprintf(stderr, "%s: Error opening %s\n", pgm, argv[optind]); perror(""); continue; } if (vflag == TRUE) fprintf(stdout, "\n%s:\n", argv[optind]); if (showit(fp, sflag, wflag) != 0) { fprintf(stderr, "%s: Error reading %s\n", pgm, argv[optind]); perror(""); } if (fclose(fp) == EOF) fatal(pgm, "Error closing input file", 2); } exit(0); } showit ─────────────────────────────────────────────────────────────────────────── /* * showit -- make non-printable characters in * the stream fp visible (or optionally strip them) */ #include <stdio.h> #include <ctype.h> #include <local\std.h> int showit(fp, strip, wp) FILE *fp; BOOLEAN strip; /* strip non-ASCII codes */ BOOLEAN wp; /* filter typical word-processing codes */ { int ch; clearerr(fp); while ((ch = getc(fp)) != EOF) if (isascii(ch) && (isprint(ch) || isspace(ch))) switch (ch) { case '\r': if (wp == TRUE) { if ((ch = getc(fp)) != '\n') ungetc(ch, fp); putchar('\r'); putchar('\n'); } else putchar(ch); break; default: putchar(ch); break; } else if (strip == FALSE) printf("\\%02X", ch); else if (wp == TRUE && isprint(ch & ASCII)) putchar(ch & ASCII); return (ferror(fp)); } dspytype ─────────────────────────────────────────────────────────────────────────── /* * dspytype -- determine display adapter type */ #include <stdio.h> #include <dos.h> #include <local\bioslib.h> #include <local\video.h> #define MDA_SEG 0xB000 #define CGA_SEG 0xB800 main() { extern int memchk(unsigned int, unsigned int); int mdaflag, egaflag, cgaflag; int ega_mem, ega_mode; unsigned int features, switches; static int memtab[] = { 64, 128, 192, 256 }; mdaflag = egaflag = cgaflag = 0; /* look for display adapters */ if (ega_info(&ega_mem, &ega_mode, &features, &switches)) ++egaflag; fputs("Enhanced graphics adapter ", stdout); if (egaflag) { fputs("installed\n", stdout); fprintf(stdout, "EGA memory size = %d-KB\n", memtab[ega_mem]); fprintf(stdout, "EGA is in %s mode\n", ega_mode ? "monochrome" : "color"); } else fputs("not installed\n", stdout); /* look for IBM monochrome memory */ if (!egaflag || (egaflag && ega_mode == 0)) if (memchk(MDA_SEG, 0)) ++mdaflag; /* look for CGA memory */ if (!egaflag || (ega && ega_mode == 1)) if (memchk(CGA_SEG, 0)) ++cgaflag; } fputs("Monochrome adapter ", stdout); if (mdaflag) fputs("installed\n", stdout); else fputs("not installed\n", stdout); fputs("Color/graphics adapter ", stdout); if (cgaflag) fputs("installed\n", stdout); else fputs("not installed\n", stdout); /* report video settings */ getstate(); fprintf(stdout, "mode=%d width=%d page=%d\n", Vmode, Vwidth, Vpage); exit(0); } memchk ─────────────────────────────────────────────────────────────────────────── /* * memchk -- look for random-access memory at * a specified location; return nonzero if found */ #include <dos.h> #include <memory.h> int memchk(seg, os) unsigned int seg; unsigned int os; { unsigned char tstval, oldval, newval; unsigned int ds; struct SREGS segregs; /* get value of current data segment */ segread(&segregs); ds = segregs.ds; /* save current contents of test location */ movedata(seg, os, ds, &oldval, 1); /* copy a known value into test location */ tstval = 0xFC; movedata(ds, &tstval, seg, os, 1); /* read test value back and compare to value written */ movedata(seg, os, ds, &newval, 1); if (newval != tstval) return (0); /* restore original contents of test location */ movedata(ds, &oldval, seg, os, 1); return (1); } ega_info ─────────────────────────────────────────────────────────────────────────── /* * ega_info -- gather information about an EGA; * return a nonzero value if one is found */ #include <dos.h> #include <local\bioslib.h> #define EGA_INFO 0x10 #define NMODES 2 #define NMEMSIZ 4 int ega_info(memsize, mode, features, switches) int *memsize; /* EGA memory size indicator: 0 = 64K */ /* 1 = 128K; 2 = 192K; 3 = 256K */ int *mode; /* 0 = color mode; 1 = mono mode */ /* use getstate function to find out which mode */ unsigned int *features, /* feature bit settings */ *switches; /* EGA switch settings */ { int result = 0; union REGS inregs, outregs; /* request EGA information */ inregs.h.ah = ALT_FUNCTION; inregs.h.bl = EGA_INFO; int86(VIDEO_IO, &inregs, &outregs); *memsize = outregs.h.bl; *mode = outregs.h.bh; *features = outregs.h.ch; *switches = outregs.h.cl; /* return nonzero if EGA installed */ if (*memsize >= 0 && *memsize < NMEMSIZ && *mode >= 0 && *mode < NMODES) result = 1; return (result); } cpblk ─────────────────────────────────────────────────────────────────────────── /* * cpblk -- copy a block of characters and attributes * while eliminating "snow" on a standard CGA display */ #include <conio.h> #include <memory.h> #define BLKCNT 10 #define VSTAT 0x3DA #define VRBIT 8 #define WRDCNT 200 #define NBYTES (2 * WRDCNT) /* macro to synchronize with vertical retrace period */ #define VSYNC while ((inp(VSTAT) & VRBIT) == VRBIT); \ while ((inp(VSTAT) & VRBIT) != VRBIT) int cpblk(src_os, src_seg, dest_os, dest_seg) unsigned int src_os, src_seg, dest_os, dest_seg; { register int i; int n; register int delta; n = 0; delta = 0; for (i = 0; i < BLKCNT ; ++i) { /* copy a block of words during vertical retrace */ VSYNC; movedata(src_seg, src_os + delta, dest_seg, dest_os + delta, NBYTES); n += WRDCNT; /* adjust buffer offset */ delta += NBYTES; } return (n); } st ─────────────────────────────────────────────────────────────────────────── /* * st -- screen test using cpblk function */ #include <stdio.h> #include <stdlib.h> #include <conio.h> #include <ctype.h> #include <dos.h> #include <local\std.h> #include <local\video.h> #define CG_SEG 0xB800 #define MONO_SEG 0xB000 #define NBYTES 0x1000 #define PAGESIZ (NBYTES / 2) #define PG0_OS 0 #define PG1_OS PG0_OS + NBYTES #define ESC 27 #define MAXSCAN 14 main(argc, argv) int argc; char *argv[]; { int i; int k; /* user command character */ int ca; /* character/attribute word */ int ch; /* character value read */ int row, col; /* cursor position upon entry */ int c_start, c_end; /* cursor scan lines */ unsigned char attr; /* saved video attribute */ unsigned dseg; /* destination buffer segment */ unsigned os; /* page offset in bytes */ static unsigned sbuf[NBYTES]; /* screen buffer */ unsigned *bp; /* screen element pointer */ unsigned sseg; /* source segment */ int special; /* use special copy routine */ int apg, vpg; /* active and visual display /* pages */ /* segment register values */ struct SREGS segregs; extern void swap_int(int *, int *); static char pgm[] = { "st" }; /* program name */ /* save user's current video state */ getstate(); readcur(&row, &col, Vpage); putcur(row - 1, 0, Vpage); readca(&ch, &attr, Vpage); getctype(&c_start, &c_end, Vpage); setctype(MAXSCAN, c_end); clrscrn(attr); putcur(1, 1, Vpage); /* initialize destination segment */ special = 1; fputs("ScreenTest (ST): ", stderr); if (Vmode == CGA_C80 || Vmode == CGA_M80) { dseg = CG_SEG; fprintf(stderr, "Using CGA mode %d", Vmode); } else if (Vmode == MDA_M80) { dseg = MONO_SEG; fprintf(stderr, "Using MDA (mode %d)", Vmode); special = 0; } else fprintf(stderr, "%s: Requires 80-column text mode\n", pgm); /* process command-line arguments */ if (argc > 2) { fprintf(stderr, "Usage: %s [x]\n", pgm); exit(2); } else if (argc == 2) special = 0; /* bypass special block move */ /* get data segment value */ segread(&segregs); sseg = segregs.ds; /* set up "active" and "visual" display pages */ apg = 1; /* page being written to */ vpg = 0; /* page being viewed */ /* display buffers on the user's command */ fprintf(stderr, " -- Type printable text; Esc=exit"); while ((k = getkey()) != ESC) { if (isascii(k) && isprint(k)) { /* fill the buffer */ ca = ((k % 0xEF) << 8) | k; for (bp = sbuf; bp - sbuf < PAGESIZ; ++bp) *bp = ca; if (Vmode == MDA_M80) os = 0; else os = (apg == 0) ? PG0_OS : PG1_OS; if (special) cpblk(sbuf, sseg, os, dseg); else movedata(sseg, sbuf, dseg, os, NBYTES); if (Vmode != MDA_M80) { swap_int(&apg, &vpg); setpage(vpg); } } else { clrscrn(attr); putcur(0, 0, Vpage); writestr(" Type printable text; Esc = exit ", vpg); } } /* restore user's video conditions and return to DOS */ setpage(Vpage); clrscrn(attr); putcur(0, 0, Vpage); setctype(c_start, c_end); exit(0); } sbuf.h ─────────────────────────────────────────────────────────────────────────── /* * sbuf.h -- header file for buffered screen interface */ #define SB_OK 0 #define SB_ERR (-1) /* screen-buffer constants */ #define SB_ROWS 25 #define SB_COLS 80 #define SB_SIZ SB_ROWS * SB_COLS /* screen character/attribute buffer element definition */ struct BYTEBUF { unsigned char ch; /* character */ unsigned char attr; /* attribute */ }; union CELL { struct BYTEBUF b; unsigned short cap; /* character/attribute pair */ }; /* screen-buffer control structure */ struct BUFFER { /* current position */ short row, col; /* pointer to screen-buffer array */ union CELL *bp; /* changed region per screen-buffer row */ short lcol[SB_ROWS]; /* left end of changed region */ short rcol[SB_ROWS]; /* right end of changed region */ /* buffer status */ unsigned short flags; }; /* buffer flags values */ #define SB_DELTA 0x01 #define SB_RAW 0x02 #define SB_DIRECT 0x04 #define SB_SCROLL 0x08 /* coordinates of a window (rectangular region) on the screen buffer */ struct REGION { /* current position */ short row, col; /* window boundaries */ short r0, c0; /* upper left corner */ short r1, c1; /* lower right corner */ /* scrolling region boundaries */ short sr0, sc0; /* upper left corner */ short sr1, sc1; /* lower right corner */ /* window buffer flags */ unsigned short wflags; }; sb_init ─────────────────────────────────────────────────────────────────────────── /* * sb_init -- initialize the buffered screen interface */ #include <stdio.h> #include <stdlib.h> #include <string.h> #include <local\sbuf.h> /* global data declarations */ struct BUFFER Sbuf; /* control information */ union CELL Scrnbuf[SB_ROWS][SB_COLS]; /* screen-buffer array */ int sb_init() { int i; char *um; /* update mode */ /* set initial parameter values */ Sbuf.bp = &Scrnbuf[0][0]; Sbuf.row = Sbuf.col = 0; for (i = 0; i < SB_ROWS; ++i) { Sbuf.lcol[i] = SB_COLS; Sbuf.rcol[i] = 0; } Sbuf.flags = 0; /* set screen update mode */ um = strupr(getenv("UPDATEMODE")); if (um == NULL || strcmp(um, "BIOS") == 0) Sbuf.flags &= ~SB_DIRECT; else if (strcmp(um, "DIRECT") == 0) Sbuf.flags |= SB_DIRECT; else return SB_ERR; return SB_OK; } sb_show ─────────────────────────────────────────────────────────────────────────── /* * sb_show -- copy the screen buffer to display memory */ #include <stdio.h> #include <dos.h> #include <memory.h> #include <local\sbuf.h> #include <local\video.h> #define MDA_SEG 0xB000 #define CGA_SEG 0xB800 #define NBYTES (2 * SB_COLS) /* macro to synchronize with vertical retrace period */ #define VSTAT 0x3DA #define VRBIT 8 #define VSYNC while ((inp(VSTAT) & VRBIT) == VRBIT); \ while ((inp(VSTAT) & VRBIT) != VRBIT) extern struct BUFFER Sbuf; extern union CELL Scrnbuf[SB_ROWS][SB_COLS]; int sb_show(pg) short pg; { register short r, c; short n; short count, ncols; unsigned int src_os, dest_os; struct SREGS segregs; if ((Sbuf.flags & SB_DIRECT) == SB_DIRECT) { /* use the direct-screen interface */ segread(&segregs); /* determine extent of changes */ n = 0; for (r = 0; r < SB_ROWS; ++r) if (Sbuf.lcol[r] <= Sbuf.rcol[r]) ++n; src_os = dest_os = 0; if (n <= 2) /* copy only rows that contain changes */ for (r = 0; r < SB_ROWS; ++r) { if (Sbuf.lcol[r] <= Sbuf.rcol[r]) { /* copy blocks during vertical * retrace */ VSYNC; movedata(segregs.ds, &Scrnbuf[0][0] + src_os, CGA_SEG, dest_os, NBYTES); Sbuf.lcol[r] = SB_COLS; Sbuf.rcol[r] = 0; } src_os += NBYTES; dest_os += NBYTES; } else { /* copy the entire buffer */ count = 3 * NBYTES; ncols = 3 * NBYTES; for (r = 0; r < SB_ROWS - 1; r += 3) { VSYNC; movedata(segregs.ds, &Scrnbuf[0][0] +src_os, CGA_SEG, dest_os, count); src_os += ncols; dest_os += count; } VSYNC; movedata(segregs.ds, &Scrnbuf[0][0] + src_os, CGA_SEG, dest_os, NBYTES); for (r = 0; r < SB_ROWS; ++r) { Sbuf.lcol[r] = SB_COLS; Sbuf.rcol[r] = 0; } } } else /* use the BIOS video interface */ for (r = 0; r < SB_ROWS; ++r) /* copy only changed portions of lines */ if (Sbuf.lcol[r] < SB_COLS && Sbuf.rcol[r] > 0) { for (c = Sbuf.lcol[r]; c <= Sbuf.rcol[r]; ++c) { putcur(r, c, pg); writeca(Scrnbuf[r][c].b.ch, Scrnbuf[r][c].b.attr, 1, pg); } Sbuf.lcol[r] = SB_COLS; Sbuf.rcol[r] = 0; } /* the display now matches the buffer -- clear flag bit */ Sbuf.flags &= ~SB_DELTA; return SB_OK; } sb_new ─────────────────────────────────────────────────────────────────────────── /* * sb_new -- prepare a new window (rectangular region) * and return a pointer to it */ #include <stdio.h> #include <malloc.h> #include <local\sbuf.h> struct REGION * sb_new(top, left, height, width) int top; /* top row */ int left; /* left column */ int height; /* total rows */ int width; /* total columns */ { struct REGION *new; /* allocate the data-control structure */ new = (struct REGION *)malloc(sizeof (struct REGION)); if (new != NULL) { new->r0 = new->sr0 = top; new->r1 = new->sr1 = top + height - 1; new->c0 = new->sc0 = left; new->c1 = new->sc1 = left + width - 1; new->row = new->col = 0; new->wflags = 0; } return (new); } sb_move ─────────────────────────────────────────────────────────────────────────── /* * sb_move -- move the screen-buffer "cursor" */ #include <local\sbuf.h> extern struct BUFFER Sbuf; extern union CELL Scrnbuf[SB_ROWS][SB_COLS]; int sb_move(win, r, c) struct REGION *win; /* window pointer */ register short r, c; /* buffer row and column */ { /* don't change anything if request is out of range */ if (r < 0 || r > win->r1 - win->r0 || c < 0 || c > win->c1 - win->c0) return SB_ERR; win->row = r; win->col = c; Sbuf.row = r + win->r0; Sbuf.col = c + win->c0; return SB_OK; } sb_fill ─────────────────────────────────────────────────────────────────────────── /* * sb_fill -- fill region routines */ #include <local\sbuf.h> extern struct BUFFER Sbuf; extern union CELL Scrnbuf[SB_ROWS][SB_COLS]; /* * sb_fill -- set all cells in a specified region * to the same character/attribute value */ int sb_fill(win, ch, attr) struct REGION *win; unsigned char ch; /* fill character */ unsigned char attr; /* fill attribute */ { register int i, j; unsigned short ca; ca = (attr << 8) | ch; for (i = win->sr0; i <= win->sr1; ++i) { for (j = win->sc0; j <= win->sc1; ++j) Scrnbuf[i][j].cap = ca; if (win->sc0 < Sbuf.lcol[i]) Sbuf.lcol[i] = win->sc0; if (win->sc1 > Sbuf.rcol[i]) Sbuf.rcol[i] = win->sc1; } Sbuf.flags |= SB_DELTA; return SB_OK; } /* * sb_fillc -- set all cells in a specified region * to the same character value; leave attributes undisturbed */ int sb_fillc(win, ch) struct REGION *win; unsigned char ch; /* fill character */ { register int i, j; for (i = win->sr0; i <= win->sr1; ++i) { for (j = win->sc0; j <= win->sc1; ++j) Scrnbuf[i][j].b.ch = ch; if (win->sc0 < Sbuf.lcol[i]) Sbuf.lcol[i] = win->sc0; if (win->sc1 > Sbuf.rcol[i]) Sbuf.rcol[i] = win->sc1; } Sbuf.flags |= SB_DELTA; return SB_OK; } /* * sb_filla -- set all cells in a specified region * to the same attribute value; leave characters undisturbed */ int sb_filla(win, attr) struct REGION *win; unsigned char attr; /* fill attribute */ { register int i, j; for (i = win->sr0; i <= win->sr1; ++i) { for (j = win->sc0; j <= win->sc1; ++j) Scrnbuf[i][j].b.attr = attr; if (win->sc0 < Sbuf.lcol[i]) Sbuf.lcol[i] = win->sc0; if (win->sc1 > Sbuf.rcol[i]) Sbuf.rcol[i] = win->sc1; } Sbuf.flags |= SB_DELTA; return SB_OK; } sb_put ─────────────────────────────────────────────────────────────────────────── * sb_put -- routines to put characters and strings into the * screen buffer; the cursor location is altered */ #include <local\sbuf.h> #include <ctype.h> extern struct BUFFER Sbuf; extern union CELL Scrnbuf[SB_ROWS][SB_COLS]; /* * sb_putc -- put a character into a screen-buffer window */ int sb_putc(win, ch) struct REGION *win; unsigned char ch; { short cmax, rmax; short lim; short noscroll = 0, puterr = 0; /* calculate screen-buffer position and limits */ cmax = win->c1 - win->c0; rmax = win->r1 - win->r0; Sbuf.row = win->r0 + win->row; Sbuf.col = win->c0 + win->col; /* process the character */ switch (ch) { case '\b': /* non-destructive backspace */ if (win->col > 0) { --win->col; Sbuf.col = win->c0 + win->col; return SB_OK; } else return SB_ERR; case '\n': /* clear trailing line segment */ while (win->col < cmax) if (sb_putc(win, ' ') == SB_ERR) ++puterr; break; case '\t': /* convert tab to required number of spaces */ lim = win->col + 8 - (win->col & 0x7); while (win->col < lim) if (sb_putc(win, ' ') == SB_ERR) ++puterr; break; default: /* if printable ASCII, place the character in the buffer */ if (isascii(ch) && isprint(ch)) Scrnbuf[Sbuf.row][Sbuf.col].b.ch = ch; if (Sbuf.col < Sbuf.lcol[Sbuf.row]) Sbuf.lcol[Sbuf.row] = Sbuf.col; if (Sbuf.col > Sbuf.rcol[Sbuf.row]) Sbuf.rcol[Sbuf.row] = Sbuf.col; break; } /* update the cursor position */ if (win->col < cmax) ++win->col; else if (win->row < rmax) { win->col = 0; ++win->row; } else if ((win->wflags & SB_SCROLL) == SB_SCROLL) { sb_scrl(win, 1); win->col = 0; win->row = rmax; } else ++noscroll; /* update screen-buffer position */ Sbuf.row = win->r0 + win->row; Sbuf.col = win->c0 + win->col; Sbuf.flags |= SB_DELTA; return ((noscroll || puterr) ? SB_ERR : SB_OK); } /* end sb_putc() */ /* * sb_puts -- put a string into the screen buffer */ int sb_puts(win, s) struct REGION *win; unsigned char *s; { while (*s) if (sb_putc(win, *s++) == SB_ERR) return SB_ERR; return SB_OK; } /* end sb_puts() */ sb_read ─────────────────────────────────────────────────────────────────────────── /* * sb_read -- read character/attribute data */ #include <local\sbuf.h> extern struct BUFFER Sbuf; extern union CELL Scrnbuf[SB_ROWS][SB_COLS]; unsigned char sb_ra(win) struct REGION *win; /* window pointer */ { return (Scrnbuf[win->r0 + win->row][win->c0 + win->col].b.attr); } /* end sb_ra() */ /* * sb_rc -- read character from current location in screen buffer */ unsigned char sb_rc(win) struct REGION *win; /* window pointer */ { return (Scrnbuf[win->r0 + win->row][win->c0 + win->col].b.ch); } /* end sb_rc() */ /* * sb_rca -- read character/attribute pair from current * location in screen buffer */ unsigned short sb_rca(win) struct REGION *win; /* window pointer */ { return (Scrnbuf[win->r0 + win->row][win->c0 + win->col].cap); } /* end sb_rca() */ sb_scrl ─────────────────────────────────────────────────────────────────────────── /* * sb_scrl -- scrolling routines */ #include <local\sbuf.h> extern struct BUFFER Sbuf; extern union CELL Scrnbuf[SB_ROWS][SB_COLS]; /* * sb_scrl -- scroll the specified window * n lines (direction indicated by sign) */ int sb_scrl(win, n) struct REGION *win; short n; /* number of rows to scroll */ { register short r, c; if (n == 0) /* clear the entire region to spaces */ sb_fillc(win, ' '); else if (n > 0) { /* scroll n rows up */ for (r = win->sr0; r <= win->sr1 - n; ++r) { for (c = win->sc0; c <= win->sc1; ++c) Scrnbuf[r][c] = Scrnbuf[r + n][c]; if (win->sc0 < Sbuf.lcol[r]) Sbuf.lcol[r] = win->sc0; if (win->sc1 > Sbuf.rcol[r]) Sbuf.rcol[r] = win->sc1; } for ( ; r <= win->sr1; ++r) { for (c = win->sc0; c <= win->sc1; ++c) Scrnbuf[r][c].b.ch = ' '; if (win->sc0 < Sbuf.lcol[r]) Sbuf.lcol[r] = win->sc0; if (win->sc1 > Sbuf.rcol[r]) Sbuf.rcol[r] = win->sc1; } } else { /* scroll n rows down */ n = -n; for (r = win->sr1; r >= win->sr0 + n; --r) { for (c = win->sc0; c <= win->sc1; ++c) Scrnbuf[r][c] = Scrnbuf[r - n][c]; if (win->sc0 < Sbuf.lcol[r]) Sbuf.lcol[r] = win->sc0; if (win->sc1 > Sbuf.rcol[r]) Sbuf.rcol[r] = win->sc1; } for ( ; r >= win->sr0; --r) { for (c = win->sc0; c <= win->sc1; ++c) Scrnbuf[r][c].b.ch = ' '; if (win->sc0 < Sbuf.lcol[r]) Sbuf.lcol[r] = win->sc0; if (win->sc1 > Sbuf.rcol[r]) Sbuf.rcol[r] = win->sc1; } } Sbuf.flags |= SB_DELTA; return SB_OK; } /* end sb_scrl() */ /* * sb_set_scrl -- set the scroll region boundaries */ int sb_set_scrl(win, top, left, bottom, right) struct REGION *win; /* window pointer */ short top, left; /* upper left corner */ short bottom, right; /* lower left corner */ { if (top < 0 || left < 0 || bottom > win->r1 - win->r0 || right > win->c1 - win->c0) return SB_ERR; win->sr0 = win->r0 + top; win->sc0 = win->c0 + left; win->sr1 = win->r0 + bottom - 1; win->sc1 = win->c0 + right - 1; return SB_OK; } /* end sb_set_scrl() */ sb_write ─────────────────────────────────────────────────────────────────────────── /* * sb_write -- screen-buffer write routines */ #include <local\sbuf.h> extern struct BUFFER Sbuf; extern union CELL Scrnbuf[SB_ROWS][SB_COLS]; /* * sb_wa -- write an attribute to a region of the screen buffer */ int sb_wa(win, attr, n) struct REGION *win; /* window pointer */ unsigned char attr; /* attribute */ short n; /* repetition count */ { short i; short row; short col; i = n; row = win->r0 + win->row; col = win->c0 + win->col; while (i--) Scrnbuf[row][col + i].b.attr = attr; /* marked the changed region */ if (col < Sbuf.lcol[row]) Sbuf.lcol[row] = col; if (col + n > Sbuf.rcol[row]) Sbuf.rcol[row] = col + n; Sbuf.flags |= SB_DELTA; return (i == 0) ? SB_OK : SB_ERR; } /* end sb_wa() */ /* * sb_wc -- write a character to a region of the screen buffer */ int sb_wc(win, ch, n) struct REGION *win; /* window pointer */ unsigned char ch; /* character */ short n; /* repetition count */ { short i; short row; short col; i = n; row = win->r0 + win->row; col = win->c0 + win->col; while (i--) Scrnbuf[row][col + i].b.ch = ch; /* marked the changed region */ if (col < Sbuf.lcol[row]) Sbuf.lcol[row] = col; if (col + n > Sbuf.rcol[row]) Sbuf.rcol[row] = col + n; Sbuf.flags |= SB_DELTA; return (i == 0 ? SB_OK : SB_ERR); } /* end sb_wc() */ /* * sb_wca -- write a character/attribute pair to a region * of the screen buffer */ int sb_wca(win, ch, attr, n) struct REGION *win; /* window pointer */ unsigned char ch; /* character */ unsigned char attr; /* attribute */ short n; /* repetition count */ { int i; short row; short col; i = n; row = win->r0 + win->row; col = win->c0 + win->col; while (i--) Scrnbuf[row][col + i].cap = (attr << 8) | ch; /* marked the changed region */ if (col < Sbuf.lcol[row]) Sbuf.lcol[row] = col; if (col + n > Sbuf.rcol[row]) Sbuf.rcol[row] = col + n; Sbuf.flags |= SB_DELTA; return (i == 0 ? SB_OK : SB_ERR); } /* end sb_wca() */ sb_box ─────────────────────────────────────────────────────────────────────────── /* * sb_box -- draw a box around the perimeter of a window * using the appropriate IBM graphics characters */ #include <local\sbuf.h> #include <local\video.h> #include <local\box.h> int sb_box(win, type, attr) struct REGION *win; short type; unsigned char attr; { register short r; /* row index */ short x; /* interior horizontal line length */ short maxr, maxc; /* maximum row and col values */ BOXTYPE *boxp; /* pointer to box-drawing character struct */ static BOXTYPE box[] = { '+', '+', '+', '+', '-', '-', '|', '|', ULC11, URC11, LLC11, LRC11, HBAR1, HBAR1, VBAR1, VBAR1, ULC22, URC22, LLC22, LRC22, HBAR2, HBAR2, VBAR2, VBAR2, ULC12, URC12, LLC12, LRC12, HBAR1, HBAR1, VBAR2, VBAR2, ULC21, URC21, LLC21, LRC21, HBAR2, HBAR2, VBAR1, VBAR1, BLOCK, BLOCK, BLOCK, BLOCK, HBART, HBARB, BLOCK, BLOCK }; boxp = &box[type]; maxc = win->c1 - win->c0; maxr = win->r1 - win->r0; x = maxc - 1; /* draw top row */ sb_move(win, 0, 0); sb_wca(win, boxp->ul, attr, 1); sb_move(win, 0, 1); sb_wca(win, boxp->tbar, attr, x); sb_move(win, 0, maxc); sb_wca(win, boxp->ur, attr, 1); /* draw left and right sides */ for (r = 1; r < maxr; ++r) { sb_move(win, r, 0); sb_wca(win, boxp->lbar, attr, 1); sb_move(win, r, maxc); sb_wca(win, boxp->rbar, attr, 1); } /* draw bottom row */ sb_move(win, maxr, 0); sb_wca(win, boxp->ll, attr, 1); sb_move(win, maxr, 1); sb_wca(win, boxp->bbar, attr, x); sb_move(win, maxr, maxc); sb_wca(win, boxp->lr, attr, 1); return SB_OK; } makefile for SBUF.LIB ─────────────────────────────────────────────────────────────────────────── # makefile for SBUF.LIB (screen-buffer library) LLIB = c:\lib\local LINC = c:\include\local OBJS = sb_box.obj sb_fill.obj sb_init.obj sb_move.obj sb_new.obj \ sb_put.obj sb_read.obj sb_scrl.obj sb_show.obj sb_write.obj MODS = sb_box sb_fill sb_init sb_move sb_new.obj sb_put sb_read \ sb_scrl sb_show sb_write $(LINC)\sbuf.h: sbuf.h copy sbuf.h $(LINC)\sbuf.h $(LINC)\box.h: box.h copy box.h $(LINC)\box.h sb_box.obj: sb_box.c $(LINC)\sbuf.h $(LINC)\video.h $(LINC)\box.h sb_fill.obj: sb_fill.c $(LINC)\sbuf.h sb_init.obj: sb_init.c $(LINC)\sbuf.h sb_move.obj: sb_move.c $(LINC)\sbuf.h sb_new.obj: sb_new.c $(LINC)\sbuf.h sb_put.obj: sb_put.c $(LINC)\sbuf.h sb_read.obj: sb_read.c $(LINC)\sbuf.h sb_scrl.obj: sb_scrl.c $(LINC)\sbuf.h sb_show.obj: sb_show.c $(LINC)\sbuf.h sb_write.obj: sb_write.c $(LINC)\sbuf.h sbuf.lib: $(OBJS) del sbuf.lib lib sbuf +$(MODS); copy sbuf.lib $(LLIB) sb_test ─────────────────────────────────────────────────────────────────────────── /* * sb_test -- driver for screen-buffer interface functions */ #include <stdio.h> #include <stdlib.h> #include <conio.h> #include <local\std.h> #include <local\keydefs.h> #include <local\sbuf.h> #include <local\video.h> #include <local\box.h> #include "sb_test.h" #define BEL 7 extern struct BUFFER Sbuf; main(argc, argv) int argc; char *argv[]; { char *s, line[MAXLINE]; int k; short i; FILE *fp; char fname[MAXPATH]; struct REGION *cmnd, *stat, *text, *help, *curwin; unsigned char cmndattr, statattr, textattr, helpattr, curattr; unsigned char ch, userattr; /* function prototypes */ int sb_init(); int sb_move(struct REGION *, short, short); struct REGION *sb_new(short, short, short, short); int sb_putc(struct REGION *, unsigned char); int sb_puts(struct REGION *, char *); int sb_show(short); int sb_fill(struct REGION *, unsigned char, unsigned char); char *get_fname(struct REGION *, char *, short); getstate(); readca(&ch, &userattr, Vpage); /* set up the screen buffer */ if (sb_init() == SB_ERR) { fprintf(stderr, "Bad UPDATEMODE value in environment\n"); exit(1); } /* set up windows and scrolling regions */ cmnd = sb_new(CMND_ROW, CMND_COL, CMND_HT, CMND_WID); stat = sb_new(STAT_ROW, STAT_COL, STAT_HT, STAT_WID); text = sb_new(TEXT_ROW, TEXT_COL, TEXT_HT, TEXT_WID); help = sb_new(HELP_ROW, HELP_COL, HELP_HT, HELP_WID); text->wflags |= SB_SCROLL; sb_set_scrl(help, 1, 1, HELP_HT - 1, HELP_WID - 1); /* display each primary window in its own attribute */ cmndattr = GRN; statattr = (WHT << 4) | BLK; textattr = (BLU << 4) | CYAN; helpattr = (GRN << 4) | YEL; sb_fill(cmnd, ' ', cmndattr); if (sb_move(cmnd, 0, 0) == SB_OK) sb_puts(cmnd, "SB_TEST (Version 1.0)"); sb_fill(stat, ' ', statattr); if (sb_move(stat, 0, 0) == SB_OK) sb_puts(stat, "*** STATUS AREA ***"); for (i = 0; i <= text->r1 - text->r0; ++i) { sb_move(text, i, 0); sb_wca(text, i + 'a', textattr, text->c1 - text->c0 + 1); } if (sb_move(text, 10, 25) == SB_OK) sb_puts(text, " *** TEXT DISPLAY AREA *** "); sb_show(Vpage); curwin = text; curattr = textattr; /* respond to user commands */ while ((k = getkey()) != K_ESC) { switch (k) { case K_UP: sb_scrl(curwin, 1); break; case K_DOWN: sb_scrl(curwin, -1); break; case K_PGUP: sb_scrl(curwin, curwin->sr1 - curwin->sr0); break; case K_PGDN: sb_scrl(curwin, -(curwin->sr1 - curwin->sr0)); break; case K_ALTC: /* clear the current window */ sb_fill(curwin, ' ', curattr); break; case K_ALTH: /* display help */ curwin = help; curattr = helpattr; for (i = 0; i < help->r1 - help->r0; ++i) { sb_move(help, i, 0); sb_wca(help, i + 'a', helpattr, help->c1 - help->c0 + 1); } sb_box(help, BOXBLK, helpattr); break; case K_ALTS: /* fill the command area with letters */ curwin = stat; curattr = statattr; sb_fill(stat, 's', statattr); break; case K_ALTT: /* fill the text area */ curwin = text; curattr = textattr; for (i = 0; i <= text->r1 - text->r0; ++i) { sb_move(text, i, 0); sb_wca(text, i + 'a', textattr, text->c1 - text->c0 + 1); } break; case K_ALTR: /* read a file into the current window */ sb_fill(stat, ' ', statattr); sb_move(stat, 0, 0); sb_puts(stat, "File to read: "); sb_show(Vpage); (void)get_fname(stat, fname, MAXPATH); if ((fp = fopen(fname, "r")) == NULL) { sb_fill(stat, ' ', statattr); sb_move(stat, 0, 0); sb_puts(stat, "Cannot open "); sb_puts(stat, fname); } else { sb_fill(stat, ' ', statattr); sb_move(stat, 0, 0); sb_puts(stat, "File: "); sb_puts(stat, fname); sb_show(Vpage); sb_fill(text, ' ', textattr); sb_move(text, 0, 0); putcur(text->r0, text->c0, Vpage); while ((s = fgets(line, MAXLINE, fp)) != NULL) { if (sb_puts(text, s) == SB_ERR) { clrscrn(userattr); putcur(0, 0, Vpage); fprintf(stderr, "puts error\n"); exit(1); } sb_show(Vpage); } if (ferror(fp)) { putcur(text->r0, text->c0, Vpage); fprintf(stderr, "Error reading file\n"); } fclose(fp); } break; default: /* say what? */ fputc(BEL, stderr); continue; } if ((Sbuf.flags & SB_DELTA) == SB_DELTA) sb_show(Vpage); } clrscrn(userattr); putcur(0, 0, Vpage); exit(0); } /* * get_fname -- get a filename from the user */ char * get_fname(win, path, lim) struct REGION *win; char *path; short lim; { int ch; char *s; s = path; sb_show(Vpage); while ((ch = getch()) != K_RETURN) { if (ch == '\b') --s; else { sb_putc(win, ch); *s++ = ch; } sb_show(Vpage); } *s = '\0'; return (path); } ansi.h ─────────────────────────────────────────────────────────────────────────── /* * ansi.h -- header file for ANSI driver information and * macro versions of the ANSI control sequences */ /*****************/ /** ANSI macros **/ /*****************/ /* cursor position */ #define ANSI_CUP(r, c) printf("\x1B[%d;%dH", r, c) #define ANSI_HVP(r, c) printf("\x1B[%d;%df", r, c) /* cursor up, down, forward, back */ #define ANSI_CUU(n) printf("\x1B[%dA", n) #define ANSI_CUD(n) printf("\x1B[%dB", n) #define ANSI_CUF(n) printf("\x1B[%dC", n) #define ANSI_CUB(n) printf("\x1B[%dD", n) /* device status report (dumps position data into keyboard buffer) */ #define ANSI_DSR printf("\x1B[6n") /* save and restore cursor position */ #define ANSI_SCP fputs("\x1B[s", stdout) #define ANSI_RCP fputs("\x1B[u", stdout) /* erase display and line */ #define ANSI_ED fputs("\x1B[2J", stdout); #define ANSI_EL fputs("\x1B[K", stdout) /* set graphic rendition */ #define ANSI_SGR(a) printf("\x1B[%dm", a) /* set and reset modes */ #define ANSI_SM(m) printf("\x1B[=%dh", m) #define ANSI_RM(m) printf("\x1B[=%dl", m) /**********************/ /** ANSI color codes **/ /**********************/ /* special settings */ #define ANSI_NORMAL 0 #define ANSI_BOLD 1 #define ANSI_BLINK 5 #define ANSI_REVERSE 7 #define ANSI_INVISIBLE 8 /* shift values */ #define ANSI_FOREGROUND 30 #define ANSI_BACKGROUND 40 /* basic colors */ #define ANSI_BLACK 0 #define ANSI_RED 1 #define ANSI_GREEN 2 #define ANSI_BROWN 3 #define ANSI_BLUE 4 #define ANSI_MAGENTA 5 #define ANSI_CYAN 6 #define ANSI_WHITE 7 /*****************************/ /** modes for set and reset **/ /*****************************/ #define ANSI_M40 0 #define ANSI_C40 1 #define ANSI_M80 2 #define ANSI_C80 3 #define ANSI_C320 4 #define ANSI_M320 5 #define ANSI_M640 6 #define ANSI_WRAP 7 /* attribute "position" type */ typedef enum { FGND, BKGND, BDR } POSITION; cpr ─────────────────────────────────────────────────────────────────────────── /* * cpr -- report where the cursor is located * The position information is placed in the keyboard buffer in the * form ESC[rr;ccR, where ESC is the value of the ESCAPE character * and r and c represent decimal values of row and column data. */ #include <local\ansi.h> void ansi_cpr(row, col) int *row, *col; { int i; /* request a cursor position report */ ANSI_DSR; /* toss the ESC and '[' */ (void) getkey(); (void) getkey(); /* read the row number */ *row = 10 * (getkey() - '0'); *row = *row + getkey() - '0'; /* toss the ';' separator */ (void) getkey(); /* read the column number */ *col = 10 * (getkey() - '0'); *col = *col + getkey() - '0'; /* toss the trailing ('R') and return */ (void) getkey(); (void) getkey(); return; } ansi_tst ─────────────────────────────────────────────────────────────────────────── /* * ansi_tst -- verify that the ANSI.SYS driver is loaded * (prints message and exits if ANSI driver not working) */ #include <stdio.h> #include <local\ansi.h> #include <local\video.h> #define TST_ROW 2 #define TST_COL 75 void ansi_tst() { int row, col; static char *help[] = { "\n", "ANSI.SYS device driver not loaded:\n", " 1. Copy ANSI.SYS to your system disk.\n", " 2. Add the line device=ansi.sys to your\n", " CONFIG.SYS file and reboot your machine.\n", NULL }; char **msg; extern int getstate(); extern int readcur(int *, int *, int); getstate(); ANSI_CUP(TST_ROW, TST_COL); readcur(&row, &col, Vpage); if (row != TST_ROW - 1 || col != TST_COL - 1) { for (msg = help; *msg != NULL; ++msg) fputs(*msg, stderr); exit(1); } return; } sc ─────────────────────────────────────────────────────────────────────────── /* * SetColor (sc) -- set foreground, background, and border attributes * on systems equipped with color display systems * * Usage: sc [foreground [background [border]]] * sc [attribute] */ #include <stdio.h> #include <dos.h> #include <local\std.h> #include <local\ansi.h> #include <local\ibmcolor.h> main(argc, argv) int argc; char *argv[]; { void ansi_tst(); BOOLEAN iscolor(); extern void setattr(); extern void menumode(); ansi_tst(); if (iscolor() == FALSE) { fprintf(stderr, "\n\nSystem not in a color text mode.\n"); fprintf(stderr, "Use the MODE command to set the mode.\n"); exit(2); } /* process either batch or interactive commands */ if (argc > 1) /* batch mode processing */ parse(argc, argv); else /* no command-line args -- interactive mode */ menumode(); ANSI_ED; exit (0); } /* end main() */ /* * iscolor -- return TRUE if a color display system is * in use and is set to one of the text modes */ #include <local\std.h> #include <local\video.h> BOOLEAN iscolor() { getstate(); if (Vmode != CGA_C40 || Vmode != CGA_C80) return TRUE; return FALSE; } parse ─────────────────────────────────────────────────────────────────────────── /* * parse -- process a list of attribute specifications */ #include <stdio.h> #include <local\ansi.h> #include <local\std.h> #include <local\ibmcolor.h> /* buffer length for string comparisons */ #define NCHARS 3 #define C_MASK 0x7 void parse(nargs, argvec) int nargs; /* number of argument vectors */ char *argvec[]; /* pointer to the argument vector array */ { int i, intensity; int attribute; POSITION pos; char str[NCHARS + 1]; extern int colornum(); extern void setattr(); /* clear all attributes */ ANSI_SGR(ANSI_NORMAL); /* look for a single attribute specification */ if (nargs == 2) { attribute = colornum(argvec[1]); switch (attribute) { case IBM_NORMAL: palette(0, IBM_BLACK); return; case IBM_REVERSE: ANSI_SGR(ANSI_REVERSE); palette(0, IBM_WHITE); return; case IBM_INVISIBLE: ANSI_SGR(ANSI_INVISIBLE); return; case IBM_BLINK: ANSI_SGR(ANSI_BLINK); return; } } /* must be separate attribute specifications */ pos = FGND; intensity = 0; for (i = 1; i < nargs; ++i) { attribute = colornum(argvec[i]); if (attribute == -1) { ANSI_ED; fprintf(stderr, "\nIllegal parameter\n"); exit (2); } if (attribute == IBM_BRIGHT) { intensity = IBM_BRIGHT; continue; } setattr(pos, attribute | intensity); if (pos == FGND) pos = BKGND; else if (pos == BKGND) pos = BDR; intensity = 0; } return; } ibmcolor.h ─────────────────────────────────────────────────────────────────────────── /* * ibmcolor.h */ /* basic IBM color codes */ #define IBM_BLACK 0 #define IBM_BLUE 1 #define IBM_GREEN 2 #define IBM_CYAN 3 #define IBM_RED 4 #define IBM_MAGENTA 5 #define IBM_BROWN 6 #define IBM_WHITE 7 /* color modifiers */ #define IBM_BRIGHT 8 #define IBM_BLINK 16 /* special attribute codes */ #define IBM_NORMAL 7 #define IBM_REVERSE 112 #define IBM_INVISIBLE 128 colornum ─────────────────────────────────────────────────────────────────────────── /* * colornum -- return the IBM number for the color * presented as a string; return -1 if no match. */ #include <stdio.h> #include <string.h> #include <local\ibmcolor.h> #define NCHARS 3 int colornum(name) char *name; { int n; static struct color_st { char *c_name; int c_num; } colortab[] = { "black", IBM_BLACK, "blue", IBM_BLUE, "green", IBM_GREEN, "cyan", IBM_CYAN, "red", IBM_RED, "magenta", IBM_MAGENTA, "brown", IBM_BROWN, "white", IBM_WHITE, "normal", IBM_NORMAL, "bright", IBM_BRIGHT, "light", IBM_BRIGHT, "bold", IBM_BRIGHT, "yellow", IBM_BROWN + IBM_BRIGHT, "blink", IBM_BLINK, "reverse", IBM_REVERSE, "invisible", IBM_INVISIBLE, NULL, (-1) }; (void) strlwr(name); for (n = 0; colortab[n].c_name != NULL; ++n) if ((strncmp(name, colortab[n].c_name, NCHARS)) == 0) return (colortab[n].c_num); return (-1); } setattr ─────────────────────────────────────────────────────────────────────────── /* * setattr -- execute an attribute update */ #include <stdio.h> #include <local\ansi.h> #include <local\ibmcolor.h> #define C_MASK 0x7 void setattr(pos, attr) POSITION pos; /* attribute position */ int attr; /* composite attribute number (base attr | intensity) */ { static int ibm2ansi[] = { ANSI_BLACK, ANSI_BLUE, ANSI_GREEN, ANSI_CYAN, ANSI_RED, ANSI_MAGENTA, ANSI_BROWN, ANSI_WHITE }; switch (pos) { case FGND: if (attr & IBM_BRIGHT) ANSI_SGR(ANSI_BOLD); ANSI_SGR(ibm2ansi[attr & C_MASK] + ANSI_FOREGROUND); break; case BKGND: if (attr & IBM_BRIGHT) ANSI_SGR(ANSI_BLINK); ANSI_SGR(ibm2ansi[attr & C_MASK] + ANSI_BACKGROUND); break; case BDR: palette(0, attr); break; } return; } menumode ─────────────────────────────────────────────────────────────────────────── /* * menumode -- process user commands interactively */ #include <stdio.h> #include <local\ansi.h> #include <local\ibmcolor.h> #include <local\keydefs.h> /* maximum color number */ #define MAX_CNUM 15 void menumode() { int ch; int foreground, background, border; extern void setattr(); extern void sc_cmds(); /* default attributes */ foreground = IBM_WHITE; background = IBM_BLACK; border = IBM_BLACK; ANSI_SGR(ANSI_NORMAL); setattr(FGND, foreground); setattr(BKGND, background); ANSI_ED; palette(0, border); sc_cmds(foreground, background, border); while ((ch = getkey()) != K_RETURN) { switch (ch) { case K_F1: /* decrement foreground color */ if (--foreground < 0) foreground = MAX_CNUM; break; case K_F2: /* increment foreground color */ if (++foreground > MAX_CNUM) foreground = 0; break; case K_F3: /* decrement background color */ if (--background < 0) background = MAX_CNUM; break; case K_F4: /* increment background color */ if (++background > MAX_CNUM) background = 0; break; case K_F5: /* decrement border color */ if (--border < 0) border = MAX_CNUM; break; case K_F6: /* increment border color number */ if (++border > MAX_CNUM) border = 0; break; default: continue; } ANSI_SGR(ANSI_NORMAL); setattr(FGND, foreground); setattr(BKGND, background); palette(0, border); ANSI_ED; sc_cmds(foreground, background, border); } return; } sc_cmds ─────────────────────────────────────────────────────────────────────────── /* * sc_cmds -- display command summary */ #include <stdio.h> #include <local\ansi.h> void sc_cmds(fg, bkg, bdr) int fg, bkg, bdr; { static char *color_xlat[] = { "Black (0)", "Blue (1)", "Green (2)", "Cyan (3)", "Red (4)", "Magenta (5)", "Brown (6)", "White (7)", "Grey (8)", "Light blue (9)", "Light green (10)", "Light cyan (11)", "Light red (12)", "Light magenta (13)", "Yellow (14)", "Bright white (15)" }; ANSI_CUP(2, 29); fputs("*** SetColor (SC) ***", stdout); ANSI_CUP(4, 17); fputs("Attribute Decrement Increment Current Value", stdout); ANSI_CUP(5, 17); fputs("--------- --------- --------- -------------", stdout); ANSI_CUP(6, 17); fputs("Foreground F1 F2", stdout); ANSI_CUP(7, 17); fputs("Background F3 F4", stdout); ANSI_CUP(8, 17); fputs("Border F5 F6", stdout); ANSI_CUP(6, 50); fputs(color_xlat[fg], stdout); ANSI_CUP(7, 50); fputs(color_xlat[bkg], stdout); ANSI_CUP(8, 50); fputs(color_xlat[bdr], stdout); ANSI_CUP(10, 17); fputs("Type RETURN to exit. SetColor/Version 2.2", stdout); return; } /* end sc_cmds() */ makefile for the SC program ─────────────────────────────────────────────────────────────────────────── # makefile for the SC program LINC=c:\include\local LLIB=c:\lib\local iscolor.obj: iscolor.c msc $*; lib $(LLIB)\util -+$*; colornum.obj: colornum.c $(LINC)\ansi.h $(LINC)\ibmcolor.h msc $*; lib color -+$*; sc_cmds.obj: sc_cmds.c $(LINC)\ansi.h msc $*; lib color -+$*; menumode.obj: menumode.c $(LINC)\ansi.h $(LINC)\ibmcolor.h $(LINC)\keydefs.h msc $*; lib color -+$*; parse.obj: parse.c $(LINC)\ansi.h $(LINC)\ibmcolor.h msc $*; lib color -+$*; setattr.obj: setattr.c $(LINC)\ansi.h $(LINC)\ibmcolor.h msc $*; lib color -+$*; sc.obj: sc.c $(LINC)\ansi.h $(LINC)\ibmcolor.h $(LINC)\keydefs.h msc $*; sc.exe: sc.obj color.lib $(LLIB)\ansi.lib $(LLIB)\util.lib link $*, $*, nul, color $(LLIB)\ansi $(LLIB)\util $(LLIB)\bios $(LLIB)\dos; useattr ─────────────────────────────────────────────────────────────────────────── /* * userattr -- set video attributes to user-specified values * (DOS environment parameters) or to reasonable defaults and * return success or a failure indication for bad attributes */ #include <stdio.h> #include <stdlib.h> #include <string.h> #include <local\std.h> #include <local\ansi.h> #include <local\ibmcolor.h> int userattr(foreground, background, border) char *foreground, *background, *border; { char *s; static int attrset(); if ((s = getenv("FGND")) == NULL) s = foreground; if (attrset(FGND, s) == -1) return FAILURE; if ((s = getenv("BKGND")) == NULL) s = background; if (attrset(BKGND, s) == -1) return FAILURE; if ((s = getenv("BORDER")) == NULL) s = border; if (attrset(BDR, s) == -1) return FAILURE; return SUCCESS; } /* * attrset -- parse the color spec and try to set it. * return 0 if OK and -1 upon error (bad color number) */ static int attrset(apos, str) POSITION apos; char *str; { int attr; extern int colornum(); extern void setattr(); if ((attr = colornum(strtok(str, " \t"))) == IBM_BRIGHT) attr |= colornum(strtok(NULL, " \t")); if (attr >= 0) setattr(apos, attr); else return (-1); return (0); } makefile for the VF program ─────────────────────────────────────────────────────────────────────────── # makefile for the ViewFile (VF) program # (compile using "compact" memory model) LIB = c:\lib LLIB = c:\lib\local OBJS = vf_list.obj vf_dspy.obj vf_srch.obj vf_util.obj vf_cmd.obj \ message.obj getstr.obj vf_list.obj: vf_list.c vf.h vf_dspy.obj: vf_dspy.c vf.h vf_srch.obj: vf_srch.c vf.h vf_util.obj: vf_util.c vf.h vf_cmd.obj: vf_cmd.c vf.h getstr.obj: getstr.c message.obj: message.c message.h cvf.lib: $(OBJS) del cvf.lib lib cvf +$(OBJS); vf.obj: vf.c vf.exe: vf.obj cvf.lib $(LLIB)\cutil.lib $(LLIB)\cdos.lib $(LLIB)\cbios.lib link $* $(LIB)\csetargv, $*, NUL, cvf $(LLIB)\cutil $(LLIB)\cdos \ $(LLIB)\cbios; vf ─────────────────────────────────────────────────────────────────────────── /* * vf -- view a file using a full-screen window onto * an in-memory text file buffer */ #include <stdio.h> #include <stdlib.h> #include <string.h> #include <local\std.h> #include <local\video.h> #include "vf.h" extern int setctype(int, int); int Startscan, Endscan; /* cursor scan line range */ unsigned char Attr; /* primary display attribute */ unsigned char Revattr; /* reverse video for highlighting */ unsigned char Usrattr; /* user's original attribute */ main(argc, argv) int argc; char **argv; { int ch; static char pgm[MAXNAME + 1] = { "vf" }; BOOLEAN errflag; BOOLEAN numbers; int errcode; FILE *fp; extern char *optarg; extern int optind; void clean(); /* external function prototypes */ extern void getpname(char *, char *); extern void fixtabs(int); extern void initmsg(int, int, int, unsigned char, int); extern int getopt(int, char **, char *); extern int vf_cmd(FILE *, char *, BOOLEAN); extern int getctype(int *, int *, int); errcode = 0; getstate(); fixtabs(TABWIDTH); /* get program name from DOS (version 3.00 and later) */ if (_osmajor >= 3) getpname(*argv, pgm); /* be sure we have needed DOS support */ if (_osmajor < 2) { fprintf(stderr, "%s requires DOS 2.00 or later\n", pgm); exit(1); } /* process optional arguments first */ errflag = numbers = FALSE; while ((ch = getopt(argc, argv, "n")) != EOF) switch (ch) { case 'n': /* turn on line numbering */ numbers = TRUE; break; case '?': /* bad option */ errflag = TRUE; break; } /* check for command-line errors */ argc -= optind; argv += optind; if (errflag == TRUE || argc == 0) { fprintf(stderr, "Usage: %s [-n] file...\n", pgm); exit(1); } /* get current video attribute and set VF attributes */ getstate(); readca(&ch, &Usrattr, Vpage); /* save user's attribute settings */ Attr = (BLU << 4) | CYAN; /* basic text attributes */ Revattr = (CYAN << 4) | BLK; /* reverse video for highlighting */ clrscrn(Attr); /* save user's cursor shape */ getctype(&Startscan, &Endscan, Vpage); setctype(MAXSCAN, MAXSCAN); /* set up the message line manager */ initmsg(MSGROW, MSGCOL, Maxcol[Vmode] - MSGCOL, Attr, Vpage); /* display first screen page */ putcur(0, 0, Vpage); putstr("ViewFile/1.0 H=Help Q=Quit Esc=Next", Vpage); putcur(1, 0, Vpage); writea(Revattr, Maxcol[Vmode], Vpage); for (; argc-- > 0; ++argv) { if ((fp = fopen(*argv, "r")) == NULL) { fprintf(stderr, "%s: cannot open %s -- ", pgm, *argv); perror(""); ++errcode; continue; } if (vf_cmd(fp, *argv, numbers) != 0) break; } clean(); exit(errcode); } /* * clean -- restore the user's original conditions */ void clean() { /* set screen to user's attribute */ clrscrn(Attr); putcur(0, 0, Vpage); /* restore user's cursor shape */ setctype(Startscan, Endscan); } vf.h ─────────────────────────────────────────────────────────────────────────── /* * vf.h -- header for ViewFile program */ #define OVERLAP 2 #define MAXSTR 40 #define MSGROW 0 #define MSGCOL 40 #define HEADROW 1 #define TOPROW 2 #define NROWS 23 #define SHIFTWIDTH 20 #define N_NODES 256 #define TABWIDTH 8 #define MAXSCAN 14 typedef enum { FORWARD, BACKWARD } DIRECTION; /* doubly-linked list structure */ typedef struct dnode_st { struct dnode_st *d_next; struct dnode_st *d_prev; unsigned int d_lnum; /* file-relative line number */ unsigned short d_flags; /* miscellaneous line flags */ char *d_line; /* pointer to text buffer */ } DNODE; /* line flags */ #define STANDOUT 0x1 vf_cmd ─────────────────────────────────────────────────────────────────────────── /* * vf_cmd -- ViewFile command processor */ #include <stdio.h> #include <stdlib.h> #include <string.h> #include <ctype.h> #include <local\std.h> #include <local\keydefs.h> #include <local\video.h> #include "vf.h" #include "message.h" extern unsigned char Attr; int vf_cmd(fp, fname, numbers) FILE *fp; char *fname; BOOLEAN numbers; { register int i; /* general index */ unsigned int offset; /* horizontal scroll offset */ unsigned int n; /* relative line number */ int memerr; /* flag for memory allocation errors */ char *s, lbuf[MAXLINE]; /* input line buffer and pointer */ int k; /* key code (see keydefs.h) */ int radix = 10; /* base for number-to-character * conversions */ char number[17]; /* buffer for conversions */ int errcount = 0; /* error counter */ DNODE *tmp; /* pointer to buffer control nodes */ DIRECTION srchdir; /* search direction */ char *ss; /* pointer to search string */ static char srchstr[MAXSTR] = { "" }; /* search string buffer */ DNODE *head; /* pointer to starting node of * text buffer list */ DNODE *current; /* pointer to the current * node (text line) */ static DNODE *freelist; /* pointer to starting node of * "free" list */ /* initialized to 0 at runtime; retains * value */ /* function prototypes */ static void prtshift(int, int); extern DNODE *vf_mklst(); extern DNODE *vf_alloc(int); extern DNODE *vf_ins(DNODE *, DNODE *); extern DNODE *vf_del(DNODE *, DNODE *); extern DNODE *search(DNODE *, DIRECTION, char *); extern DNODE *gotoln(DNODE *); extern char *getxline(char *, int, FILE *); extern char *getsstr(char *); extern int clrscrn(unsigned char); extern void showhelp(unsigned char); extern void clrmsg(); extern void vf_dspy(DNODE *, DNODE *, int, BOOLEAN); extern int putstr(char *, int); extern int writec(char, int, int); extern char *nlerase(char *); /* display the file name */ offset = 0; putcur(HEADROW, 0, Vpage); writec(' ', Maxcol[Vmode], Vpage); putstr("File: ", Vpage); putstr(fname, Vpage); /* establish the text buffer */ memerr = 0; if ((head = vf_mklst()) == NULL) ++memerr; if (freelist == NULL && (freelist = vf_alloc(N_NODES)) == NULL) ++memerr; if (memerr) { clean(); fprintf(stderr, "Memory allocation error\n"); exit(1); } /* read the file into the buffer */ current = head; n = 0; while ((s = getxline(lbuf, MAXLINE, fp)) != NULL) { /* add a node to the list */ if ((freelist = vf_ins(current, freelist)) == NULL) ++memerr; current = current->d_next; /* save the received text in a line buffer */ if ((current->d_line = strdup(nlerase(s))) == NULL) ++memerr; if (memerr) { clean(); fprintf(stderr, "File too big to load\n"); exit(1); } current->d_lnum = ++n; current->d_flags = 0; } /* show the file size as a count of lines */ putstr(" (", Vpage); putstr(itoa(current->d_lnum, number, radix), Vpage); putstr(" lines)", Vpage); prtshift(offset, Vpage); current = head->d_next; vf_dspy(head, current, offset, numbers); /* process user commands */ while ((k = getkey()) != K_ESC) { clrmsg(); switch (k) { case 'b': case 'B': case K_HOME: current = head->d_next; break; case 'e': case 'E': case K_END: current = head->d_prev; i = NROWS - 1; while (i-- > 0) if (current->d_prev != head->d_next) current = current->d_prev; break; case K_PGUP: case 'u': case 'U': i = NROWS - OVERLAP; while (i-- > 0) if (current != head->d_next) current = current->d_prev; break; case K_PGDN: case 'd': case 'D': i = NROWS - OVERLAP; while (i-- > 0) if (current != head->d_prev) current = current->d_next; break; case K_UP: case '-': if (current == head->d_next) continue; current = current->d_prev; break; case K_DOWN: case '+': if (current == head->d_prev) continue; current = current->d_next; break; case K_RIGHT: case '>': case '.': if (offset < MAXLINE - SHIFTWIDTH) offset += SHIFTWIDTH; prtshift(offset, Vpage); break; case K_LEFT: case '<': case ',': if ((offset -= SHIFTWIDTH) < 0) offset = 0; prtshift(offset, Vpage); break; case K_ALTG: case 'g': case 'G': if ((tmp = gotoln(head)) == NULL) continue; current = tmp; break; case K_ALTH: case 'h': case 'H': case '?': showhelp(Attr); break; case K_ALTN: case 'n': case 'N': numbers = (numbers == TRUE) ? FALSE : TRUE; break; case K_ALTQ: case 'q': case 'Q': clrscrn(Attr); putcur(0, 0, Vpage); return (-1); case 'r': case 'R': case '\\': srchdir = BACKWARD; ss = getsstr(srchstr); if (ss == NULL) /* cancel search */ break; if (strlen(ss) > 0) strcpy(srchstr, ss); if ((tmp = search(current, srchdir, srchstr)) == NULL) continue; current = tmp; break; case 's': case 'S': case '/': srchdir = FORWARD; ss = getsstr(srchstr); if (ss == NULL) /* cancel search */ break; if (strlen(ss) > 0) strcpy(srchstr, ss); if ((tmp = search(current, srchdir, srchstr)) == NULL) continue; current = tmp; break; default: /* ignore all other keys */ continue; } vf_dspy(head, current, offset, numbers); } clrmsg(); /* release the allocated text buffer memory */ while (head->d_next != head) { /* release text buffer */ free(head->d_next->d_line); /* put node back on the freelist */ freelist = vf_del(head->d_next, freelist); } /* release the list header node */ free((char *)head); return (errcount); } /* * prtshift -- display the number of columns of horizontal shift */ #define SHFTDSP 5 static void prtshift(amt, pg) int amt, pg; { char number[17]; int radix = 10; /* clear the shift display area */ putcur(1, Maxcol[Vmode] - 1 - SHFTDSP, pg); writec(' ', SHFTDSP, pg); /* display the new shift amount, if any */ if (amt > 0) { putstr(itoa(amt, number, radix), pg); putstr("->", pg); } } putstr ─────────────────────────────────────────────────────────────────────────── /* * putstr -- display a character string in the * prevailing video attribute and return number * characters displayed */ int putstr(s, pg) register char *s; int pg; { int r, c, c0; readcur(&r, &c, pg); for (c0 = c; *s != '\0'; ++s, ++c) { putcur(r, c, pg); writec(*s, 1, pg); } putcur(r, c, pg); return (c - c0); } vf_list ─────────────────────────────────────────────────────────────────────────── /* * vf_list -- linked list management functions */ #include <stdio.h> #include <malloc.h> #include "vf.h" /* * vf_mklst -- create a new list by allocating a node, * making it point to itself, and setting its values * to zero (appropriately cast) */ DNODE * vf_mklst() { DNODE *new; new = (DNODE *)malloc(sizeof (DNODE)); if (new != NULL) { new->d_next = new; new->d_prev = new; new->d_lnum = new->d_flags = 0; new->d_line = (char *)NULL; } return (new); } /* end vf_mklst() */ /* * vf_alloc -- create a pool of available nodes */ DNODE * vf_alloc(n) int n; { register DNODE *new; register DNODE *tmp; /* allocate a block of n nodes */ new = (DNODE *)malloc(n * sizeof (DNODE)); /* if allocation OK, string the nodes in one direction */ if (new != NULL) { for (tmp = new; 1 + tmp - new < n; tmp = tmp->d_next) tmp->d_next = tmp + 1; tmp->d_next = (DNODE *)NULL; } return (new); /* pointer to free list */ } /* end vf_alloc() */ /* * vf_ins -- insert a node into a list after the specified node */ DNODE * vf_ins(node, avail) DNODE *node, *avail; { DNODE *tmp; DNODE *vf_alloc(int); /* * check freelist -- get another block of nodes * if the list is almost empty */ if (avail->d_next == NULL) if ((avail->d_next = vf_alloc(N_NODES)) == NULL) /* not enough memory */ return (DNODE *)NULL; /* get a node from the freelist */ tmp = avail; avail = avail->d_next; /* insert the node into the list after node */ tmp->d_prev = node; tmp->d_next = node->d_next; node->d_next->d_prev = tmp; node->d_next = tmp; /* point to next node in the freelist */ return (avail); } /* end vf_ins() */ /* * vf_del -- delete a node from a list */ DNODE * vf_del(node, avail) DNODE *node, *avail; { /* unlink the node from the list */ node->d_prev->d_next = node->d_next; node->d_next->d_prev = node->d_prev; /* return the deleted node to the freelist */ node->d_next = avail; avail = node; /* point to the new freelist node */ return (avail); } /* end vf_del() */ vf_dspy ─────────────────────────────────────────────────────────────────────────── /* * vf_dspy -- display a screen page */ #include <stdio.h> #include <stdlib.h> #include <string.h> #include <ctype.h> #include <local\video.h> #include <local\std.h> #include <local\bioslib.h> #include "vf.h" /* number field width */ #define NFW 8 void vf_dspy(buf, lp, os, numbers) DNODE *buf; register DNODE *lp; int os; BOOLEAN numbers; { register int i; int j; int textwidth; char *cp; char nbuf[NFW + 1]; textwidth = Maxcol[Vmode]; if (numbers == TRUE) textwidth -= NFW; for (i = 0; i < NROWS; ++i) { putcur(TOPROW + i, 0, Vpage); cp = lp->d_line; if (numbers == TRUE) { sprintf(nbuf, "%6u", lp->d_lnum); putfld(nbuf, NFW, Vpage); putcur(TOPROW + i, NFW, Vpage); } if (os < strlen(cp)) putfld(cp + os, textwidth, Vpage); else writec(' ', textwidth, Vpage); if (lp == buf->d_prev) { ++i; break; /* no more displayable lines */ } else lp = lp->d_next; } /* clear and mark any unused lines */ for ( ; i < NROWS; ++i) { putcur(i + TOPROW, 0, Vpage); writec(' ', Maxcol[Vmode], Vpage); writec('~', 1, Vpage); } return; } putfld ─────────────────────────────────────────────────────────────────────────── /* * putfld -- display a string in the prevailing * video attribute while compressing runs of a * single character, and pad the field to full width * with spaces if necessary */ int putfld(s, w, pg) register char *s; /* string to write */ int w; /* field width */ int pg; /* screen page for writes */ { int r, c, cols; register int n; extern int putcur(int, int, int); extern int readcur(int *, int *, int); extern int writec(unsigned char, int, int); /* get starting (current) position */ readcur(&r, &c, pg); /* write the string */ for (n = 0; *s != '\0' && n < w; s += cols, n += cols) { putcur(r, c + n, pg); /* compress runs to a single call on writec() */ cols = 1; while (*(s + cols) == *s && n + cols < w) ++cols; writec(*s, cols, pg); } /* pad the field, if necessary */ if (n < w) { putcur(r, c + n, pg); writec(' ', w - n, pg); } return (w - n); } vf_util ─────────────────────────────────────────────────────────────────────────── /* * vf_util -- utility functions for ViewFile */ #include <stdio.h> #include <stdlib.h> #include <string.h> #include <local\std.h> #include <local\video.h> #include <local\keydefs.h> #include "vf.h" extern int Startscan, Endscan; #define NDIGITS 6 /* * gotoln -- jump to an absolute line number */ DNODE * gotoln(buf) DNODE *buf; { register int ln; register DNODE *lp; char line[NDIGITS + 1]; extern void showmsg(char *); extern char *getstr(char *, int); /* get line number from user */ showmsg("Line number: "); setctype(Startscan, Endscan); /* cursor on */ ln = atoi(getstr(line, NDIGITS + 1)); setctype(MAXSCAN, MAXSCAN); /* cursor off */ /* check boundary conditions */ if (ln > buf->d_prev->d_lnum || ln <= 0) { showmsg("Line out of range"); return ((DNODE *)NULL); } /* find the line */ for (lp = buf->d_next; ln != lp->d_lnum; lp = lp->d_next) ; return (lp); } /* * showhelp -- display a help frame */ #define HELPROW TOPROW + 3 #define HELPCOL 10 #define VBORDER 1 #define HBORDER 2 void showhelp(textattr) unsigned char textattr; /* attribute of text area */ { register int i, n; int nlines, ncols; unsigned char helpattr; static char *help[] = { "PgUp (U) Scroll up in the file one screen page", "PgDn (D) Scroll down in the file one screen page", "Up arrow (-) Scroll up in the file one line", "Down arrow (+) Scroll down in the file one line", "Right arrow (>) Scroll right by 20 columns", "Left arrow (<) Scroll left by 20 columns", "Home (B) Go to beginning of file buffer", "End (E) Go to end of file buffer", "Alt-g (G) Go to a specified line in the buffer", "Alt-h (H or ?) Display this help frame", "Alt-n (N) Toggle line-numbering feature", "\\ (R) Reverse search for a literal text string", "/ (S) Search forward for a literal text string", "Esc Next file from list (quits if none)", "Alt-q (Q) Quit", "--------------------------------------------------------", " << Press a key to continue >>", (char *)NULL }; /* prepare help window */ ncols = 0; for (i = 0; help[i] != (char *)NULL; ++i) if ((n = strlen(help[i])) > ncols) ncols = n; nlines = i - 1; --ncols; helpattr = (RED << 4) | BWHT; clrw(HELPROW - VBORDER, HELPCOL - HBORDER, HELPROW + nlines + VBORDER, HELPCOL + ncols + HBORDER, helpattr); drawbox(HELPROW - VBORDER, HELPCOL - HBORDER, HELPROW + nlines + VBORDER, HELPCOL + ncols + HBORDER, Vpage); /* display the help text */ for (i = 0; help[i] != (char *)NULL; ++i) { putcur(HELPROW + i, HELPCOL, Vpage); putstr(help[i], Vpage); } /* pause until told by a keypress to proceed */ getkey(); /* restore help display area to the text attribute */ clrw(HELPROW - VBORDER, HELPCOL - HBORDER, HELPROW + nlines + VBORDER, HELPCOL + ncols + HBORDER, textattr); } getstr ─────────────────────────────────────────────────────────────────────────── /* * getstr -- get a string from the keyboard */ #include <stdio.h> #include <string.h> #include <local\std.h> #include <local\video.h> #include <local\keydefs.h> char * getstr(buf, width) char *buf; int width; { int row, col; char *cp; /* function prototypes */ extern int putcur(int, int, int); extern int readcur(int *, int *, int); extern int writec(char, int, int); extern int getkey(); /* gather keyboard input into a string buffer */ cp = buf; while ((*cp = getkey()) != K_RETURN && cp - buf < width) { switch (*cp) { case K_CTRLH: /* destructive backspace */ if (cp > buf) { readcur(&row, &col, Vpage); putcur(row, col - 1, Vpage); writec(' ', 1, Vpage); --cp; } continue; case K_ESC: /* cancel string input operation */ return (char *)NULL; } put_ch(*cp, Vpage); ++cp; } *cp = '\0'; return (buf); } message ─────────────────────────────────────────────────────────────────────────── /* * message -- routines used to display and clear * messages in a reserved message area */ #include "message.h" MESSAGE Ml; extern int writec(char, int, int); /* * set up the message-line manager */ void initmsg(r, c, w, a, pg) int r; /* message row */ int c; /* message column */ int w; /* width of message field */ unsigned char a; /* message field video attribute */ int pg; /* active page for messages */ { MESSAGE *mp; void clrmsg(); mp = &Ml; mp->m_row = r; mp->m_col = c; mp->m_wid = w; mp->m_attr = a; mp->m_pg = pg; mp->m_flag = 1; clrmsg(); } /* * showmsg -- display a message and set the message flag */ void showmsg(msg) char *msg; { MESSAGE *mp; mp = &Ml; putcur(mp->m_row, mp->m_col, mp->m_pg); writec(' ', mp->m_wid, mp->m_pg); putstr(msg, mp->m_pg); mp->m_flag = 1; return; } /* * clrmsg -- erase the message area and reset the message flag */ void clrmsg() { MESSAGE *mp; mp = &Ml; if (mp->m_flag != 0) { putcur(mp->m_row, mp->m_col, mp->m_pg); writec(' ', mp->m_wid, mp->m_pg); mp->m_flag = 0; } return; } vf_srch ─────────────────────────────────────────────────────────────────────────── /* * vf_srch -- search functions */ #include <stdio.h> #include <stdlib.h> #include <string.h> #include <local\std.h> #include "vf.h" /* * search -- search for a literal string in the buffer */ DNODE * search(buf, dir, str) DNODE *buf; DIRECTION dir; char *str; { int n; register DNODE *lp; register char *cp; extern void showmsg(char *); /* try to find a match -- wraps around buffer boundaries */ n = strlen(str); lp = (dir == FORWARD) ? buf->d_next : buf->d_prev; while (lp != buf) { if ((cp = lp->d_line) != NULL) /* skip over header node */ while (*cp != '\n' && *cp != '\0') { if (strncmp(cp, str, n) == 0) return (lp); ++cp; } lp = (dir == FORWARD) ? lp->d_next : lp->d_prev; } showmsg("Not found"); return ((DNODE *)NULL); } /* * getsstr -- prompt the user for a search string */ extern int Startscan, Endscan; char *getsstr(str) char *str; { char line[MAXSTR]; char *resp; extern int putstr(char *, int); extern char *getstr(char *, int); extern int put_ch(char, int); extern void showmsg(char *); extern void clrmsg(); static char prompt[] = { "Search for: " }; /* get search string */ showmsg(prompt); setctype(Startscan, Endscan); /* cursor on */ resp = getstr(line, MAXSTR - strlen(prompt)); setctype(MAXSCAN, MAXSCAN); /* cursor off */ if (resp == NULL) return (char *)NULL; if (strlen(resp) == 0) return (str); showmsg(resp); return (resp); } getxline ─────────────────────────────────────────────────────────────────────────── /* * getxline -- get a line of text while expanding tabs, * put text into an array, and return a pointer to the * resulting null-terminated line */ #include <stdio.h> #include <stdlib.h> #include <ctype.h> #include <local\std.h> char *getxline(buf, size, fin) char *buf; int size; FILE *fin; { register int ch; /* input character */ register char *cp; /* character pointer */ extern BOOLEAN tabstop(int); cp = buf; while (--size > 0 && (ch = fgetc(fin)) != EOF) { if (ch == '\n') { *cp++ = ch; break; } else if (ch == '\t') do { *cp = ' '; } while (--size > 0 && (tabstop(++cp - buf) == FALSE)); else *cp++ = ch & ASCII; } *cp = '\0'; return ((ch == EOF && cp == buf) ? NULL : buf); } Index Page numbers for illustrations are in italics Symbols ────────────────────────────────────────────────────────────────────── # %var% / (DOS option switch) \ (DOS pathname separator) \\ (C escape) \include \include\local \lib \lib\local \x | A ────────────────────────────────────────────────────────────────────── Advanced MS-DOS affirm() Alt key status American National Standards Institute (ANSI) basics color attributes control sequences device driver (see ANSI.SYS) display memory local library summary proposed standard for C language ansi_cpr() ANSI_CUP ANSI_DSR ansi.h ANSI_SGR ANSI.SYS control codes numeric parameters selective parameters installing interface package pros and cons of SetColor program set graphic rendition (SGR) user-attribute function ansi_tst() SetColor program arguments argc argv fixed/variable-list pathname and type video row and col ASCII codes. See also displaying non-ASCII text and ANSI controls block characters character code data bytes control character table for Epson MX/FX printer control extended line-drawing characters printable character table video attributes asctime() Aspen Scientific Assembler AT&T PC6300 UNIX System V atoi() attributes. See characters and attributes AUTOEXEC.BAT file automatic program configuration printer control functions selection functions using configuration files using the program name B ────────────────────────────────────────────────────────────────────── batch processing SetColor program bdos() beep() binary numbers, converting bios.lib bioslib.h BIOS library routines demonstration program equipment determination functions keyboard status library summary makefile video access bios.mk blink bit block characters block-copy routine synchronized blocking read box-drawing functions box.h header file buffer(s) input/output screen (see buffered screen interface; screen access routines) text (see text buffer) buffered screen interface box-drawing functions buffer management functions general window functions interface package screen buffer library byte2hex() C ────────────────────────────────────────────────────────────────────── call by reference call by value Caps Lock key status CAT program cells, buffer character I/O functions characters and attributes. See also ASCII codes; SetColor (SC) program display memory reading from screen buffers writing to windows char data type C language DOS-to-, (see DOS-to-C connection) language details Microsoft, version 4.00 PC interfaces (see PC operating system interfaces) standard routines (see standard libraries) standards/compatibility technical highlights user interface (see user interface) CL control program clean() clearerr() clock. See PC timer close() clrmsg() clrprnt() clrscrn() clrw() CodeView color graphics adapter (CGA) display adapter basics memory interference colornum() color numbers colors. See SetColor (SC) program command-line processing accessing the command line ambiguous filenames arguments pointers and indirection program name standardizing, to improve user interface compact memory model compatibility. See portability compiler Microsoft version 4.00 other compilers for DOS Computer Innovations C86 configuration. See automatic program configuration configuration files confirm() conversion functions, numbers cpblk() screen updates ST program CP program The C Programming Language "C Reference Manual" CR/LF ctime() Ctrl-Break Ctrl key status Ctrl-Z Curses cursor control functions position report restoring split window cursor.c cursor.mk CURSOR program makefile output pseudocode source code D ────────────────────────────────────────────────────────────────────── DEBUG program. See also DUMP program debugging programs. See also CodeView decimal numbers, converting delay() device driver. See ANSI.SYS device status report directories disk list (see LS utility program) pathname (see PWD utility program) direct screen access alternative solutions display adapter basics programming considerations disk routine numbers, BIOS display adapter basics displaying non-ASCII text conversion functions DUMP SHOW display memory display system type, determining do_rm() DOS compared to UNIX and XENIX error messages library (see DOS library routines) link (see LINK (3.51) program) -to-C (see DOS-to-C connection) version number DOS environment pointer reserved space setting values correctly variables dos.h dos.lib doslib.h DOS library routines demonstration program DOS version number keyboard functions summary DOS-to-C connection command-line processing DOS environment variables input/output redirection and piping double buffering drawbox() drvpath() DSPYTYPE program dump.c dump.mk DUMP program makefile manual page output pseudocode source code Duncan, Ray E ────────────────────────────────────────────────────────────────────── ECHO command EDITOR EDLIN program ega_info() element, in display memory enhanced graphics adapter (EGA) enum type specifier environment pointer environment variables ENVSIZE program EOF (end of file) indicator epoch time Epson dot-matrix printer interface routines MX program equipchk() equip.h equipment determination functions standards ERASE/DEL command errno error functions ambiguous return values getreply() operating system interrupts ERRORLEVEL exception handling exec() execl() EXEMOD EXEPACK exit() external storage for large files F ────────────────────────────────────────────────────────────────────── fatal() fclose() fcloseall() fconfig() fcopy() feof() ferror() fgetc() fgetchar() fgets() file(s) basic functions configuration (see configuration files) names (see filenames, ambiguous) network sharing nontext (see displaying non-ASCII text) printing (see file printing) utilities (see file utilities) viewing (see ViewFile (VF) program) filenames, ambiguous wildcards file printing file handling option handling possible enhancements to program maintenance program specification file utilities filter DUMP as PR as first_fm() fit() fixtabs() floating point fopen() FORTRAN fprintf() fputc() fputs() free() fseek() function(s). See also names of individual functions classified by environment error file and character I/O keyboard library management of local library summary number conversion printer control process control selection suffix meanings system interface time/date timing user attribute window function keys G ────────────────────────────────────────────────────────────────────── game port getc() getch() getchar() getctype() getcwd() getdrive() getenv() getkey() getname() getopt() pseudocode source getpname() getreply() getstate() to determine video mode getstr() getticks() getxline() global variables gmtime() gotoln() graphic rendition Greenwich mean time (GMT) H ────────────────────────────────────────────────────────────────────── hardware cursor hexadecimal character constants hexadecimal numbers, converting hex.c hexdump() horizontal sweep signal I ────────────────────────────────────────────────────────────────────── ibmcolor.h initmsg() input/output (I/O) buffered character functions redirection and piping with TEE terminating user input Ins key status intdos() intdosx() int86() int86x() interactive mode, SETCOLOR program interlanguage calls interrupts BIOS PC operating system interval() intra-application communications area (ICA) iscolor() K ────────────────────────────────────────────────────────────────────── kbd_stat() kbhit() Kernighan, Brian. See also Ritchie, Dennis M. keybdlib.h keyboard BIOS routine numbers functions (DOS) status stdin stream keydefs.h keyready() L ────────────────────────────────────────────────────────────────────── language(s) details, Microsoft C interlanguage calls last_ch() Lattice-MS-DOS C Compiler LF (linefeed) character LIB, object-file maintainer libraries. See local library summary; screen buffer library; standard libraries linebuf.h line-drawing characters lines() LINK (3.51) program list directories. See LS utility program local library summary ANSI BIOS DOS screen buffer utility localtime() ls.c ls_dirx() lseek() ls_fcomp() ls_list() ls.mk ls_multi() ls_single() LS utility program makefile manual page pseudocode source code M ────────────────────────────────────────────────────────────────────── macros. See function(s) "magic cookies" attribute positions mainmenu() MAKE command program maintainer. See also makefile makefile ANSI BIOS CURSOR DUMP LS MX PR PRTSTR REPLAY sbuf.lib SetColor SHOW SHOWTABS ST ViewFile malloc() Mark Williams C Programming System (MWC) MASM macro assembler math coprocessor math libraries, multiple memchk() memcpy() memory. See also buffer(s) checking, to determine screen type compact model determining total display (see display memory) intra-application communications area (ICA) models memsize() message.c message.h Microsoft C, version 4.00 language details technical highlights Microsoft C Compiler Library Reference Manual mkslist() pseudocode MODE command modeflag monochrome adapter MORE movedata() MSC control program MULTICOLUMN variable mx.mk MX program makefile manual page source code N ────────────────────────────────────────────────────────────────────── next_fm() NL (newline) character nlerase() non-ASCII text. See displaying non-ASCII text nonblocking read NOTES program NOTES2 program _nullcheck() numbers, conversion functions Num Lock key status O ────────────────────────────────────────────────────────────────────── open() operating system interrupts PC interfaces (see PC operating system interfaces) optarg opterr Optimizing C86 optind option flag(s) option switches _osmajor _osminor OUTBUF overlays P ────────────────────────────────────────────────────────────────────── page(s) active/visual "flipping" formatting/copying text layout Pagelist palette() parse() Pascal pathname display and type argument PC operating system interfaces BIOS library routines demonstration program (CURSOR) DOS library routines functions library management issues PC timer p_dest perror() pointer(s) environment and indirection PolyMake portability P_OVERLAY pr.c pr_cpy() pseudocode source code preprocessor directives pr_file() pr_gcnf() pseudocode source code pr_getln() pr_help() PRINT printer control functions MX program PRTSTR program printer.c printer.h printf() print.h printing files. See file printing print working directory path. See PWD utility program prlib.lib pr_line() pr.mk pr.obj process control functions program development development cycle guiding principles local environment programmable peripheral interface (PPI) programming languages interlanguage calls program name using, to alter program behavior program size PR program calling hierarchy file handling as filter folded lines formatting/copying text pages makefile manual page option handling page layout possible enhancements program maintenance as a sink source code specification prtshift() prtstr.c prtstr.mk PRTSTR program makefile manual page source code pseudocode for configuration layers CURSOR DUMP getopt() mkslist() pr_cpy() pr_gcnf() RM save_range showit() TEE TOUCH putc() put_ch() putcur() putenv() putfld() putstr() pwd.c PWD utility program manual page source code Q ────────────────────────────────────────────────────────────────────── qsort() R ────────────────────────────────────────────────────────────────────── read blocking characters/attributes from screen buffers from the DOS environment nonblocking video characters read() readca() readcur() readdot() realloc() REGION registers structures word/byte remove files. See RM utility program replay.c replay.mk REPLAY program makefile return values, ambiguous rewind() Ritchie, Dennis M.. See also Kernighan, Brian rm.c RM utility program manual page pseudocode source code routines. See function(s) rows and columns, video RUN_ONCE program S ────────────────────────────────────────────────────────────────────── SAMPLE.BAT file save_range() pseudocode sb_box() sb_fill() sb_init() sb_move() sb_new() sb_putc() sb_puts() sb_ra() sb_rc() sb_rca() sb_read() sb_scrl() sb_set_scrl() sb_show() sb_test.c SB_TEST driver program header file makefile source code sb_test.mk sbuf.h sbuf.lib makefile sb_wa() sb_wc() sb_wca() sb_write() scanf() sc.c sc_cmds() Schinnell, Rich sc.mk screen(s) access (see buffered screen interface; screen access routines; video access) color/graphics adapter basics determining type of scrolling/clearing commands stderr/stdout streams updates updates with cpblk() user input screen access routines. See also buffered screen interface demonstration program ST design considerations determining display system type direct screen access double buffering synchronized block-copy routine screen buffer library scroll() scrolling windows/screens commands Scroll Lock key status search() segread() select.c selected() selection functions SELECT module routines setargv() setattr() SetColor (SC) program batch mode function keys in interactive mode makefile manual page pseudocode source code using SET command setctype() setdta() _setenvp() SETENV program setfont() setfreq() set graphic rendition (SGR) SETMYDIR program setpage() setprnt() setvmode() sflag shift key status show.c SHOWENV program showhelp() showit() show.mk showmsg() SHOW program makefile manual page pseudocode source code SHOWTABS program makefile output signal() signal catching sink. See also filter Slist sorting sound() sound.c sound generation sound.h SOUNDS program spaces() spawn() spawnvp() SPKR program standard data streams standard libraries. See also function(s) basic file and character I/O functions BIOS routines DOS routines exception handling functions management LIB other library functions process control functions reasons for using system interface functions time functions st.c stderr (standard error) stream std.h stdin (standard input) stream stdio.h stdlib.h stdout (standard output) stream st.mk ST (screen test) program makefile source code strdup() string(s) creating time into windows strlwr() strtok() struct BYTEREGS struct pr_st struct tm structure handling struct WORDREGS strupr() support tools for C compiler swap_int() sweep.c switches. See option switches SYMDEB program system() T ────────────────────────────────────────────────────────────────────── tabs.c tabstop() tab stops, setting tee.c TEE utility program manual page pseudocode source code Termcap testing programs text buffer management TICKRATE time() time conversions creating strings time zones timedata.c TIMEDATA program time/date functions time delays time.h TIMER program manual page timing functions audible feedback PC timer and time delays TONE program tools.ini touch.c TOUCH utility program manual page pseudocode source code TSTREPLY program tstsel.c TSTSEL program output typedef TZ tzset() U ────────────────────────────────────────────────────────────────────── Universal time (UT) "UNIX 1984 Standard" UNIX operating system command-line processing compared to DOS control program (cc) ctime() getopt() error MAKE program portability standardization of starting optional arguments (-) System V unlink() UPDATEMODE userattr() user interface command-line processing timing functions user input utility programs library summary util.lib V ────────────────────────────────────────────────────────────────────── variables DOS environment global (see global variables) time vartabs() ver() vf_alloc() vf_cmd() vf_cmd.c vf_del() vf_dspy() vf.h vf_ins() vflag vf_list.c vf.mk vf_mklst() vf_srch.c vf_util.c video access. See also screen(s) video attributes video.h video routine numbers, BIOS ViewFile (VF) program external storage features header file help frame implementation details makefile manual page source code void W ────────────────────────────────────────────────────────────────────── warn() wflag wildcard characters in ambiguous filenames window(s) general functions REGION word2hex() write characters/attributes to windows to the DOS environment video characters write() writea() writec() writeca() writedot() writemsg() writestr() writetty() X ────────────────────────────────────────────────────────────────────── XENIX compared to DOS control program (cc) getopt() error portability