Category : C Source Code
Archive   : JER_MSC.ZIP
Filename : LIBLIST

LIBLIST, JER.LIB, JER.H - Copyright (C) Jerry Houston, 1987
Released for Private Use Only - All Commercial Rights Reserved


This document is a brief owner's manual for the functions that are included in
the library JER.LIB. As I get more time, I will edit a real manual, but for
now this information should make it possible for you to use the functions that
are part of JER.LIB. These are functions that I feel shouldn't have been left
out of C's standard library, and some that are specific to the PC. I use them
very often, and I have made them available to others by request.

JER.LIB is going through some changes right now, as I replace functions that
were once written in C with new versions that were all written with assembler.
The new versions are usually both smaller and faster than the previous ones.

This version of JER.LIB is for use with Microsoft C, or any other version of
C that observes the same call/return protocol (arguments pushed onto the stack
last-first, and ints returned in AX). If anyone wants copies of the source
files so they can be modified to work with a different brand of C, just ask.
I'll gladly make them available for non-commercial use, but I don't want to
require everyone to download them just to get a working library.

Nearly all of these routines require the header file JER.H to be #included,
so no further notice will be given for that. A few of them (the window
routines) also require the header WINDOWS.H, and reminders to that effect are
printed with the descriptions, below.


CLRSCR
------
void clrscr()

Clears the screen, regardless of which video mode is being used. This
is accomplished by reading the current mode, then resetting that same
mode, using calls to the appropriate BIOS functions.



DELAY
-----
void delay(n)
int n;

Does nothing for 'n' milliseconds. Actually, the use of milliseconds
is an accomodation for previous source of mine. delay(3000) will indeed
do nothing for three seconds, but the resolution is in clock tics, or
about 1/18th second. delay(55) is therefore the shortest meaningful
pause.
Example:
.
.
.
put("Finally! Finished with this job!");
delay(3000);
.
.
.
etc.

will display the message shown for three seconds before continuing



DOPEN
-----
DIR *dopen(pathname)
char *pathname; (requires DIR.H for directory structures)

Opens a directory, places information into the members of a structure
defined by DIR (see the header file DIR.H for more details). This is
done one time to obtain a pointer to DIR, after which repeated calls
to the DREAD() function (which see) will return information about
individual files. Provides matching file names, sizes, dates, times.
Example:

DIR *dptr;
struct direct *buff;
.
.
.
dptr = dopen(pathname);
buff = dread(dptr);
while(dptr->error == 0)
{
put(dptr->name);
.
.
.
dread(dptr);
}
etc.



DRAWBOX
-------
void drawbox(ur,lc,lr,rc,style,attrib)
int ur,lc,lr,rc,style,attrib;

Draws a box on the screen with the upper left corner at (ur,lc) and the
lower right corner at (lr,rc). Uses the ASCII character 'style' for the
horizontal characters, and it can be one that represents a single line,
a double line, or several others. drawbox() will automatically match the
proper corners and vertical lines to it. If a character is selected that
drawbox doesn't recognize, it defaults to single lines.
Example:

drawbox(0,0, 24,79, 205, 15);

encloses the entire screen within a double-line (205) box that's written
using the bold (15) attribute.



DREAD
-----
struct direct *dread(dptr)
DIR *dptr; (requires DIR.H for directory structures)

Reads from a directory that's been opened with the DOPEN() function.
See the header file DIR.H for more detailed information about the
structures that are used for reading directories. This set of
functions has been made to work as much like reading from a file as
possible, so that it will be easy to learn to use. See the function
DOPEN() for an example.



GETKEY
------
int getkey(c)
char *c;

A function to return the value of a key that's been pressed without
waiting for the key to be pressed. If this function is called and none
was pressed, it returns a null int and the character pointed to by 'c'
is set to null.

If a key was pressed and it was an ordinary key, then the function will
return a null int and 'c' will be set to the ASCII value of the key that
was pressed. If a special key was pressed, then the function returns a 1
and 'c' takes on the value of the second keypress that DOS determines.
These values appear on page 135 of the Peter Norton book, Programmer's
Guide to the IBM-PC. For example, a few of them are:

59 = F1 84 = Shift-F1
30 = Alt-A 71 = Home
72 = Up Arrow 82 = Insert



HLINE
-----
void hline(lc,rc,row)
int lc,rc,row;

hline() draws a single thin horizontal line on the screen, such as can be
used to divide menus and windows, etc. It is a close companion to the
window-handling functions.

The arguments include left column, right column, and row. The attributes
are the same as are used with drawbox and windows.

hline11, hline12, hline21, and hline22 are variations of hline. hline11
is the same as hline, and draws a single line to connect with two single
lines. hline12 draws a single line to connect with two double lines, etc.



INPUT
-----
int input(string,n)
char *string;
int n;

Used for general-purpose string input from the terminal. Puts characters
into 'string' up to the limit of 'n'. After 'n' characters are reached,
the computer will just beep at further intput, but will allow editing
with the backspace key. If 'n' is 'sizeof(string)' (or less), then
'string' can not be overrun by an overambitious data entry operator.
Example:

char string[20];
int age;
.
.
.
lput("Please enter your age: ");
input(string, 3);
age = atoi(string);
.
.
.
etc.



KEYPRESSED
----------
int keypressed()

Returns a NULL if no key was pressed, or a 1 if a key has been pressed.
Does not remove a character from the keyboard buffer, but just lets you
know whether there is one there. This can be used to take a look at
input while a process continues, without waiting for someone to type
anything in. This is the functional equivalent of Microsoft's kbhit()
function, and I write it to keep from having to edit a lot of previous
code that uses keypressed() instead.



LOCATE
------
void locate(row,col)
int row,col;

Positions the cursor at the indicated (row,col) location. Rows are
from 0 .. 24 and columns from 0 .. 79.



LINPUT
---------
int linput(row,col,string,num)
int row,col,num;
char *string;

The equivalent of BOTH the locate() and input() functions. Nearly every
time I use input() to get a string from the user, I precede it with a
call to locate() to position the cursor. This does both at one time.
Example: linput(10, 15, instring, 20);



LPUT
-------
int lput(row,col,string)
int row,col;
char *string;

The equivalent of BOTH the locate() and put() functions. Nearly every
time I use put() to write a string to the screen, I precede it with a
call to locate() to position the cursor. This does both at one time.

Example:
lput(10, 15, "Hello, World!");



PUT
---
int put(string)
char *string;

Nearly the same as puts(), but smaller and faster. Does not append a
newline to the string that's printed, so put() can be used several times
on the same line, where puts() can't. This means that put() can
substitute quite often for printf(), at a tiny fraction of its size.



SCR_GMODE
---------
int scr_gmode()

Returns the current video mode. See the DOS literature for a complete
listing of these. This lets you determine what video mode is being used,
in case your program has to do things differently according to whether
a CGA is in use, or a MONO card, etc.



SCR_GPAGE
---------
int scr_gpage()

Returns an int that represents the current video page number. Usually
this is 0, but certain modes can use extended color memory to store a
number of black-and-white pages. Not enough time or space to explain
it all here, but if you know about video pages, this is a way to find
out which one you're currently using.



SCR_GWIDTH
----------
int scr_gwidth()

Returns an int that represents the column-width (40 or 80) of the
current video mode.



SCR_POS
-------
void scr_pos(row,col)
int row,col;

The equivalent of locate() (which see). This is in the library because
of some old source code of mine that I didn't want to have to edit.



SCR_PUT
-------
int scr_put(string,attrib)
char *string;
int attrib;

Writes the string 'string' using the attribute 'attrib'. See the function
drawbox() for a partial listing of attributes.



SCR_SCROLL
----------
void scr_scroll(ur,lc,lr,rc,n,attrib)
int ur,lc,lr,rc,n,attrib;

Scrolls the screen area defined by (ur,lc) and (lr,rc) up by 'n' lines,
and clears the new empty lines with the attribute 'attrib'.



SCR_SCTYPE
----------
void scr_sctype(top,bottom)
int top,bottom;

Sets the cursor type to one defined by 'top' and 'bottom', where those
are the top and bottom scan lines for the cursor. A CGA cursor has eight
scan lines numbered 0 .. 7, so a call to this function wtih top=6 and
bottom=7 would produce an underline cursor. A MONO or EGA cursor has
fourteen lines, numbered 0 .. 13, so an underline for MONO would require
a top=12 and a bottom=13. Other combinations can be used to create a
block or a dash, and top=0, bottom=0 will turn off the cursor.



SCR_WAC
-------
void scr_wac(c,a,t)
int c,a,t;

Writes character 'c' to the screen using attribute 'a', for 't' number
of times. Does not advance the cursor automatically. Used by other
functions like drawbox().



VLINE
-----
void vline(ur,lr,col,attrib)
int ur, lr, col, attrib;

Draws a thin vertical line, such as to divide a box into parts. Draws
from an upper row of 'ur' to a lower row of 'lr', at column number 'col'.
Uses attribute 'attrib'.

vline11, vline12, vline21, vline22 are all variations. vline11 is the
same as vline. vline12 draws a single line that conects double lines,
vline22 draws a double line that connects double lines, etc.



WHEREC
------
int wherec()

Returns an int that represents the current column position of the cursor.
Usually used in another function call to locate the cursor in a position
relative to its current one. Also can be used to select from a menu
based on the column that the cursor is in.



WHERER
------
int wherer()

Returns an int that represents the current cursor row position, from
0 .. 24. Used mainly in other function calls to move the cursor a
given number of rows up or down from the current row, and in routines
that select from a menu based on the line where the cursor happens to
be when is pressed.



W_LOCATE
--------
void w_locate(w,row,col)
struct WINDOW *w;
int row, col; (requires WINDOWS.H for WINDOW structure)

A variation of the locate() function that is designed to work with rows
and columns that are relative to the origin of a window (upper left
corner is 0,0). See the locate() function for more info. The only
usage difference is that w_locate() is passed an additional first
argument that is a pointer to type struct WINDOW, and of course, that
pointer has to point to a window that's been opened, or there isn't
any point in using w_locate() at all.



W_MAKE
------
int w_make(w)
struct WINDOW *w; (requires WINDOWS.H for window structure)

int w_close(w)
struct WINDOW *w; (requires WINDOWS.H for window structure)

These two routines are always used together. The calling logic must
declare one or more variables of type struct WINDOW. Then assignments
are made to that structure to define the rows and columns that limit
the window, the style (for drawbox()), and the attribute to be used.

Passing a pointer to that window to w_make() will create the window,
after which any output function can be used to put data there. A
subsequent call to w_close() will restore the screen as it was before,
returning the screen buffer to the heap for re-use.

As many windows can be open at once as memory will allow, and each that
is open at one time will require 4K.



W_PUT
-----
int w_put(w,string)
struct WINDOW *w;
char *string;

This is the windowing equivalent of the put() function (which see), and
it requires an additional first argument that is a pointer to an open
window. This function also resets the ->nextrow and ->nextcol members
of the window structure after output, so that subsequent calls to
functions that output to the window will know where to start relative
to the last place that was written.