Category : C Source Code
Archive   : KSLIB.ZIP
Filename : KSLIB.DOC

I retain full copyright on the following software.

Permission is hereby granted to copy and/or distribute this software, as long
as no charge is made for such copying or distribution excepting any reasonable
amount for media, mailing, and evaluation. This software may be embedded in
a compiled application program sold for profit, as long as the libraries
themselves are not part of the sale. The source code (if you have it) may
not be distributed.

You may use this software for a reasonable period for evaluation, but if you
find it useful, the registration fee is $20AUS, payable to :

Kevin Spencer
17 Winchelsea Rd
NOLLAMARA
WESTERN AUSTRALIA 6061

If you are using foreign currency, and can't get it converted, figure it out
pretty close. I'm not worried about a couple of dollars either way. I'll
accept anything except cash (Anything I can convert to cash at the local
bank anyway). I'll even accept cash if you want to risk it not getting to me.

Registered users will receive a free copy of the next released version, through
either E-mail or Snail-mail. The next release will have a vastly more
comprehensive set of documentation, plus any bug-fixes or improvements
resulting from this release. Registered users will have preference on any
improvement suggestions. How long it takes for the next release depends mainly
on how many people register.

The source to this software is available for $50AUS. Same conditions as above
regarding foreign currency and acceptable payment methods. Source won't be
released to non-registered users, and updates to the source will be available
to those who already have a previous source version for $10AUS.

-------------------------------------------------------------------------------
Header files :
---------------
All functions must have the appropriate header files included. You could
get away without it on some, but it is advised against. In view of this,
I'm not going to tell you which ones are safe 🙂

In general, functions beginning with capital letters use the header file
consisting of those letters. ie, WNback() uses wn.h. The rest of the functions
you'll need to look up. These are generally the miscellaneous functions.

Also, most (if not all) the functions refer to values defined in stdinc.h,
such as TRUE, FALSE, etc. Therefore, you should include this file if you are
using *any* of these functions.

For quick reference, an alphabetical list follows.

CFcolcvt config.h
CFcolor config.h
CFcolval config.h
CFconf config.h
CFinit config.h
CFopen config.h
CFread config.h
CFwrite config.h
DBadd db.h
DBbot db.h
DBclose db.h
DBcmp db.h
DBcopy db.h
DBdelete db.h
DBend db.h
DBfindfirst db.h
DBfindnext db.h
DBfindrec db.h
DBgo db.h
DBindex db.h
DBiread db.h
DBiwrite db.h
DBopen db.h
DBread db.h
DBreadn db.h
DBrecno db.h
DBseekfirst db.h
DBseeknext db.h
DBselect db.h
DBsetindex db.h
DBskip db.h
DBtop db.h
DBwrite db.h
KBcheck kb.h
KBgetc kb.h
KBgetch kb.h
KBgetn kb.h
KBgets kb.h
KBnwgetch kb.h
KBsetfunc kb.h
KBsettrap kb.h
IFCin ifc.h
IFCout ifc.h
IFCset ifc.h
MNcolor mn.h
MNmenu mn.h
MNselect mn.h
PRerror pr.h
PRprintf pr.h
PRputs pr.h
PRseterr pr.h
SCclear sc.h
SCdisplay sc.h
SCgetfield sc.h
SCgetscreen sc.h
SCnf sc.h
SCshow sc.h
WNback wn.h
WNbox wn.h
WNclose wn.h
WNcolor wn.h
WNcursor wn.h
WNdisplay wn.h
WNend wn.h
WNfore wn.h
WNgcursor wn.h
WNinit wn.h
WNload wn.h
WNloadcurs wn.h
WNloaddos wn.h
WNmessage wn.h
WNopen wn.h
WNputc wn.h
WNsave wn.h
WNsavecurs wn.h
WNsavedos wn.h
WNselect wn.h
datelong date.h
daynam date.h
dayname date.h
dice random.h
getarg arg.h
getopt arg.h
handler misc.h
leapyear date.h
longdate date.h
longdow date.h
monlen date.h
monsum date.h
monthnam date.h
monthname date.h
mplay music.h
play music.h
randomise random.h
trapbreak misc.h
tri music.h
-------------------------------------------------------------------------------
Libraries :
-----------
Format is as follows :

LIBRARY
module
function
description
----------------------------------------

WN
wn
WNback(int c)
Set the current window background color to 'c'.
WNbox(int ulx,int uly,int lrx,int lry,int attr)
Draw a box from 'ulx','uly' to 'lrx','lry'. Box can be single
or double lined, as specified in 'attr'. 0 is single, 1 is
double.
WNclose()
Close the current window and select the last opened window.
Removes the window from the screen if it was opened as a
popup window.
WNcolor(int c)
Set the current window color to 'c'.
WNcursor(int posn)
Place the cursor at the absolute position 'posn'. 'posn' is
a value returned from WNgcursor.
WNdisplay(int x,int y,char *s)
Display the string pointed to by 's' in the current window
at coordinates 'x','y'.
WNend()
Close all windows and restore the DOS screen present before
WNinit was called. Should not be called by the programmer,
as it is set up as an 'atexit' function by WNinit.
WNfore(int)
Set the current window foreground color to 'c'.
WNgcursor()
Get the current absolute cursor position.
WNinit()
Initialise the Windowing System. Does not need to be called
by the programmer as all WN functions check for it first.
WNload()
Sets up window limits, screen color, and cursor position and
type as specified by the current window.
WNloadcurs()
Returns the cursor to the position previously saved by
WNsavecurs.
WNloaddos()
Restore the DOS screen.
WNmessage(WNwin *w,int x,int y,int c,char *s)
Place the character string 's' at the position 'x','y' in
the color 'c' in window 'w'.
WNopen(int ulx,int uly,int lrx,int lry,int c,int attr)
Open a window from 'ulx','uly' to 'lrx','lry'. Current
color is set to 'c', and attributes to 'attr'. 'attr' can
specify whether the window is a popup or not, as well as
the border style (None, single or double).
WNputc(char c)
Place the character 'c' in the current window.
WNsave()
Save the current window parameters.
WNsavecurs()
Save the current cursor position to be restored later by
WNloadcurs.
WNsavedos()
Save the current DOS screen. Used in WNinit.
WNselect(WNwin *w)
Make the window pointed to by 'w' the current window.
mn
MNcolor(int n,int h)
Set the menu colors. 'n' specifies the normal text color,
and 'h' the highlighted text color.
MNmenu(MNdata *mn)
Initiate the menu system, from the data pointed to by 'mn'.
MNselect(uint n,uint h,int min,int max,int *option,void (*)()func)
Select an item from a list. 'n' and 'h' are the normal and
highlighted colors to use. 'min' and 'max' are the lowest and
highest valid value for 'option'. 'option' is a pointer to an
integer which holds the current item number on entry to this
function, and the selected item on exit. 'func' is the function
which displays the current item.
sc
SCclear(SCdata *sc)
Clears the fields on the screen defined in 'sc'.
SCdisplay(SCdata f)
Displays the field pointed to by 'f'.
SCgetfield(SCdata f)
Gets the field pointed to by 'f'.
SCgetscreen(SCdata *sc,int *cf)
Gets a screen of data from the user, using the array of field
structures pointed to by 'sc'. On entry, the current field is
set to 'cf', and on exit, 'cf' is set to the current field.
SCnf(SCdata *sc)
Returns the number of fields in the screen pointed to by 'sc'.
SCshow(SCdata *sc)
Displays the current screen defined by 'sc'.
kb
KBcheck()
Checks to see if a key has been hit.
KBgetc(char *c,char *s,int f)
Gets a key from the keyboard. Will not return until a key
has been hit which is found in the string 's'. 'f' specifies
certain flags, such as 'allow upper case only', 'bell on
error', and 'return on valid'. The function will
also return if any non-alphanumeric key is pressed.
KBgetch()
Gets a character from the keyboard. Waits for a keypress and
does not echo.
KBgetn(double *n,uint w,uint d)
Gets a number from the keyboard. 'n' is a pointer to the
number, 'w' is the total width of the field, and 'd' is the
number of decimals.
KBgets(char *s,uint l)
Gets a string from the keyboard. 's' is a pointer to an area
to store the string, and 'l' is the total field width.
KBnwgetch()
Gets a character from the keyboard. Does not wait for a
keypress.
KBsetfunc(void (*func)())
Defines a function to be called while waiting for a keypress.
KBsettrap(uchar key,void (*func)())
Sets up trapping, so that the function 'func' is called
whenever the key 'key' is pressed.
DB
db
DBadd(void *r)
Add the record pointed to by 'r' to the current database
file, updating all indexes.
DBbot()
Return the last record in the current database file, using
the current index to determine.
DBclose()
Close the current database file. The new current file is
the last opened one.
DBcmp(void *rs,void *rd)
Compares two memory areas. The number of bytes compared is
the current database file's record length.
DBcopy(void *rs,void *rd)
Copies the area pointed to by 'rs' into the area pointed to
by 'rd'. The number of bytes copied is the current database
file's record length.
DBdelete()
Delete the current record from the current file.
DBend()
Orderly shutdown of Database system. Closes all files.
Should not be called by the programmer, as it is set up as
an 'atexit' function by the first DBopen call.
DBfindfirst(void *r)
Return the first record in the current file which matches 'r',
using the current index function to determine. Return the
record before which 'r' should be inserted if no match.
DBfindnext(void *r)
Return the next record which matches the one previously
found by DBfindfirst.
DBfindrec(void *r)
Return the record number of the record which matches 'r' in
the current file, using the current index function to
determine a match. Return 0 if no matches.
DBgo(int r)
Set the current record to record 'r' in the current database.
DBindex(char *fn,int (*func)())
Open the file specified by 'fn' as an index file for the
current database file and make it the current index. 'func'
specifies the function called to determine ordering in the
file.
DBiread(int n,int d)
Read the index record 'n' into temporary storage, and return
either the next record in the linked list, or the previous,
depending on the value of 'd'. This is an internal routine
and should not be used by the programmer. It is specific to
linked list indexing.
DBiwrite(int n)
Write the temporary storage to the index record 'n'. See above.
DBopen(char *fn,int rs)
Open the database file specified by 'fn', record size is
'rs' bytes.
DBread(void *r)
Read the current record from the current file into the
buffer pointed to by 'r'.
DBreadn(int rn,void *r)
Read record 'rn' from the current file into 'r'.
DBrecno()
Return the current record number in the current file.
DBseekfirst(void *r,int (*func)())
Return the first record which matches 'r', using 'func' to
determine a match. Scan through the file using the current
index. Return 0 if no match.
DBseeknext(void *r,int (*func)())
Return the next matching record, as per the above function.
DBselect(DBfile *db)
Make the database file specified by 'db' the current one.
DBsetindex(int n)
Make index 'n' the current index for the current database
file. 'n'=0 means use no indexing.
DBskip(int n)
Skip 'n' records forwards ('n' +ve) or backwards ('n' -ve)
in the current file, using the current index to determine.
DBtop()
Return the first record in the current database file, using
the current index to determine.
DBwrite(void *r)
Write the record pointed to by 'r' to the current record
in the current file.
TL
date
datelong(datest *d)
Convert a date to a long.
daynam(int d)
Return a pointer to the 3 character abbreviation for the
day 'n'.
dayname(int d)
Return a pointer to the full name of day 'n'.
leapyear(int y)
Return TRUE if 'y' is a leapyear.
longdate(datest *ds,long d)
Convert the long 'd' into a date and place it in 'ds'.
longdow(long d)
Return the day of the week on day 'd'.
monlen(int m,int y)
Return the number of days in month 'm' in year 'y'.
monsum(int m,int y)
Return the number of days in the year prior to the first of
month 'm' in year 'y'.
monthnam(int m)
Return a pointer to the 3 character abbreviation for month 'm'.
monthname(int m)
Return a pointer to the full name for month 'm'.
music
mplay(char *name)
Plays the Tri-voice tune defined in the file 'name'.
play(char *s)
Plays the music specified in the string 's', as per similar
functions in BASIC.
tri(short *tune)
Plays the Tri-voice tune specified by the array 'tune'.
config
CFcolcvt(char *s)
Returns the integer corresponding to the color specified in
the string 's'.
CFcolor(int c)
Returns a pointer to the character string for the color 'c'.
CFcolval(char *s)
Returns the 8-bit color code for the fg/bg colors specified
in the string 's', which is of the form 'fg,bg'.
CFconf(char *f,CFdata *d)
Read in the config file defined by 'f', using the structure
array pointed to by 'd' to determine type and location of
values read.
CFinit()
Initialise the configuration routines. Does not need to be
called by the programmer as any function which needs the
system initialised checks for it first and calls it if it
has not been called already.
CFopen(char *s)
Opens the configuration file specified by 's'. If 's' is
NULL or empty, the program name is used to check with,
first in the current directory, then the directory in which
the program exists.
CFread(char *cmd,char *arg)
Read the next assignment statement from the config file.
'cmd' will hold the "variable", and 'arg' the value.
CFwrite(char *f,CFdata *d)
Write out the data specified by the structure array pointer 'd'
to the file specified by 'f'.
arg
getarg()
Every call to getarg returns the next string in the string
array _argv. This function should be used after getopt to
successively get the non-switched command line arguments.
getopt(char *opts,void *ptr1,...,void *ptrn)
Decodes the array of strings pointed to by '_argv', according
to rules specified in 'opts'. Every alphabetic character in
'opts' is a valid command line switch. If the character is
followed by a ':', the switch has an argument. If the character
is followed by any other non-alphabetic character, any argument
present is appended, using the non-alphabetic character as a
separator.
ifc
IFCin()
Returns the value input from the current parallel port.
IFCout(uint8 val)
Outputs 'val' to the current parallel port.
IFCset(int lpt)
Sets the current parallel port to 'lpt'.
misc
handler()
Returns 0 to properly respond to a CTRL-C. Should not be
used by the programmer, as it is called when CTRL-C is pressed.
trapbreak()
Sets up CTRL-C handling, pointing it to handler.
random
dice(int n,int d)
Returns a random value as though you had just rolled 'n'
'd'-sided dice.
randomise()
Seeds the random number generator to a random point.
pr
PRerror(int n)
Calls the current specified error handling routine (if there
is one), and passes it a pointer to an appropriate error
string. Should not be called by the programmer, as it is
called by other PR functions when a printer error occurs.
PRprintf(char *fmt,arg1,...,argn)
Formats arg1...argn according to the string 'fmt', and outputs
the result to LPT1:.
PRputs(char *s)
Prints the string 's' to LPT1:.
PRseterr(void (*func)(char *))
Sets the current error handling routine to 'func'.
-------------------------------------------------------------------------------