home *** CD-ROM | disk | FTP | other *** search
/ World of Shareware - Software Farm 2 / wosw_2.zip / wosw_2 / CPROG / KSLIB.ZIP / KSLIB.DOC < prev    next >
Text File  |  1991-07-31  |  17KB  |  459 lines
  1. I retain full copyright on the following software.
  2.  
  3. Permission is hereby granted to copy and/or distribute this software, as long
  4. as no charge is made for such copying or distribution excepting any reasonable
  5. amount for media, mailing, and evaluation. This software may be embedded in
  6. a compiled application program sold for profit, as long as the libraries
  7. themselves are not part of the sale. The source code (if you have it) may
  8. not be distributed.
  9.  
  10. You may use this software for a reasonable period for evaluation, but if you
  11. find it useful, the registration fee is $20AUS, payable to :
  12.  
  13. Kevin Spencer
  14. 17 Winchelsea Rd
  15. NOLLAMARA
  16. WESTERN AUSTRALIA  6061
  17.  
  18. If you are using foreign currency, and can't get it converted, figure it out
  19. pretty close. I'm not worried about a couple of dollars either way. I'll
  20. accept anything except cash (Anything I can convert to cash at the local
  21. bank anyway). I'll even accept cash if you want to risk it not getting to me.
  22.  
  23. Registered users will receive a free copy of the next released version, through
  24. either E-mail or Snail-mail. The next release will have a vastly more
  25. comprehensive set of documentation, plus any bug-fixes or improvements
  26. resulting from this release. Registered users will have preference on any
  27. improvement suggestions. How long it takes for the next release depends mainly
  28. on how many people register.
  29.  
  30. The source to this software is available for $50AUS. Same conditions as above
  31. regarding foreign currency and acceptable payment methods. Source won't be
  32. released to non-registered users, and updates to the source will be available
  33. to those who already have a previous source version for $10AUS.
  34.  
  35. -------------------------------------------------------------------------------
  36. Header files :
  37. ---------------
  38. All functions must have the appropriate header files included. You could
  39. get away without it on some, but it is advised against. In view of this,
  40. I'm not going to tell you which ones are safe :-)
  41.  
  42. In general, functions beginning with capital letters use the header file
  43. consisting of those letters. ie, WNback() uses wn.h. The rest of the functions
  44. you'll need to look up. These are generally the miscellaneous functions.
  45.  
  46. Also, most (if not all) the functions refer to values defined in stdinc.h,
  47. such as TRUE, FALSE, etc. Therefore, you should include this file if you are
  48. using *any* of these functions.
  49.  
  50. For quick reference, an alphabetical list follows.
  51.  
  52. CFcolcvt                config.h
  53. CFcolor                    config.h
  54. CFcolval                config.h
  55. CFconf                    config.h
  56. CFinit                    config.h
  57. CFopen                    config.h
  58. CFread                    config.h
  59. CFwrite                    config.h
  60. DBadd                    db.h
  61. DBbot                    db.h
  62. DBclose                    db.h
  63. DBcmp                    db.h
  64. DBcopy                    db.h
  65. DBdelete                db.h
  66. DBend                    db.h
  67. DBfindfirst                db.h
  68. DBfindnext                db.h
  69. DBfindrec                db.h
  70. DBgo                    db.h
  71. DBindex                    db.h
  72. DBiread                    db.h
  73. DBiwrite                db.h
  74. DBopen                    db.h
  75. DBread                    db.h
  76. DBreadn                    db.h
  77. DBrecno                    db.h
  78. DBseekfirst                db.h
  79. DBseeknext                db.h
  80. DBselect                db.h
  81. DBsetindex                db.h
  82. DBskip                    db.h
  83. DBtop                    db.h
  84. DBwrite                    db.h
  85. KBcheck                    kb.h
  86. KBgetc                    kb.h
  87. KBgetch                    kb.h
  88. KBgetn                    kb.h
  89. KBgets                    kb.h
  90. KBnwgetch                kb.h
  91. KBsetfunc                kb.h
  92. KBsettrap                kb.h
  93. IFCin                    ifc.h
  94. IFCout                    ifc.h
  95. IFCset                    ifc.h
  96. MNcolor                    mn.h
  97. MNmenu                    mn.h
  98. MNselect                mn.h
  99. PRerror                    pr.h
  100. PRprintf                pr.h
  101. PRputs                    pr.h
  102. PRseterr                pr.h
  103. SCclear                    sc.h
  104. SCdisplay                sc.h
  105. SCgetfield                sc.h
  106. SCgetscreen                sc.h
  107. SCnf                    sc.h
  108. SCshow                    sc.h
  109. WNback                    wn.h
  110. WNbox                    wn.h
  111. WNclose                    wn.h
  112. WNcolor                    wn.h
  113. WNcursor                wn.h
  114. WNdisplay                wn.h
  115. WNend                    wn.h
  116. WNfore                    wn.h
  117. WNgcursor                wn.h
  118. WNinit                    wn.h
  119. WNload                    wn.h
  120. WNloadcurs                wn.h
  121. WNloaddos                wn.h
  122. WNmessage                wn.h
  123. WNopen                    wn.h
  124. WNputc                    wn.h
  125. WNsave                    wn.h
  126. WNsavecurs                wn.h
  127. WNsavedos                wn.h
  128. WNselect                wn.h
  129. datelong                date.h
  130. daynam                    date.h
  131. dayname                    date.h
  132. dice                    random.h
  133. getarg                    arg.h
  134. getopt                    arg.h
  135. handler                    misc.h
  136. leapyear                date.h
  137. longdate                date.h
  138. longdow                    date.h
  139. monlen                    date.h
  140. monsum                    date.h
  141. monthnam                date.h
  142. monthname                date.h
  143. mplay                    music.h
  144. play                    music.h
  145. randomise                random.h
  146. trapbreak                misc.h
  147. tri                        music.h
  148. -------------------------------------------------------------------------------
  149. Libraries :
  150. -----------
  151. Format is as follows :
  152.  
  153. LIBRARY
  154.     module
  155.         function
  156.             description
  157. ----------------------------------------
  158.  
  159. WN
  160.     wn
  161.         WNback(int c)
  162.             Set the current window background color to 'c'.
  163.         WNbox(int ulx,int uly,int lrx,int lry,int attr)
  164.             Draw a box from 'ulx','uly' to 'lrx','lry'. Box can be single
  165.             or double lined, as specified in 'attr'. 0 is single, 1 is
  166.             double.
  167.         WNclose()
  168.             Close the current window and select the last opened window.
  169.             Removes the window from the screen if it was opened as a
  170.             popup window.
  171.         WNcolor(int c)
  172.             Set the current window color to 'c'.
  173.         WNcursor(int posn)
  174.             Place the cursor at the absolute position 'posn'. 'posn' is
  175.             a value returned from WNgcursor.
  176.         WNdisplay(int x,int y,char *s)
  177.             Display the string pointed to by 's' in the current window
  178.             at coordinates 'x','y'.
  179.         WNend()
  180.             Close all windows and restore the DOS screen present before
  181.             WNinit was called. Should not be called by the programmer,
  182.             as it is set up as an 'atexit' function by WNinit.
  183.         WNfore(int)
  184.             Set the current window foreground color to 'c'.
  185.         WNgcursor()
  186.             Get the current absolute cursor position.
  187.         WNinit()
  188.             Initialise the Windowing System. Does not need to be called
  189.             by the programmer as all WN functions check for it first.
  190.         WNload()
  191.             Sets up window limits, screen color, and cursor position and
  192.             type as specified by the current window.
  193.         WNloadcurs()
  194.             Returns the cursor to the position previously saved by
  195.             WNsavecurs.
  196.         WNloaddos()
  197.             Restore the DOS screen.
  198.         WNmessage(WNwin *w,int x,int y,int c,char *s)
  199.             Place the character string 's' at the position 'x','y' in
  200.             the color 'c' in window 'w'.
  201.         WNopen(int ulx,int uly,int lrx,int lry,int c,int attr)
  202.             Open a window from 'ulx','uly' to 'lrx','lry'. Current
  203.             color is set to 'c', and attributes to 'attr'. 'attr' can
  204.             specify whether the window is a popup or not, as well as
  205.             the border style (None, single or double).
  206.         WNputc(char c)
  207.             Place the character 'c' in the current window.
  208.         WNsave()
  209.             Save the current window parameters.
  210.         WNsavecurs()
  211.             Save the current cursor position to be restored later by
  212.             WNloadcurs.
  213.         WNsavedos()
  214.             Save the current DOS screen. Used in WNinit.
  215.         WNselect(WNwin *w)
  216.             Make the window pointed to by 'w' the current window.
  217.     mn
  218.         MNcolor(int n,int h)
  219.             Set the menu colors. 'n' specifies the normal text color,
  220.             and 'h' the highlighted text color.
  221.         MNmenu(MNdata *mn)
  222.             Initiate the menu system, from the data pointed to by 'mn'.
  223.         MNselect(uint n,uint h,int min,int max,int *option,void (*)()func)
  224.             Select an item from a list. 'n' and 'h' are the normal and
  225.             highlighted colors to use. 'min' and 'max' are the lowest and
  226.             highest valid value for 'option'. 'option' is a pointer to an
  227.             integer which holds the current item number on entry to this
  228.             function, and the selected item on exit. 'func' is the function
  229.             which displays the current item.
  230.     sc
  231.         SCclear(SCdata *sc)
  232.             Clears the fields on the screen defined in 'sc'.
  233.         SCdisplay(SCdata f)
  234.             Displays the field pointed to by 'f'.
  235.         SCgetfield(SCdata f)
  236.             Gets the field pointed to by 'f'.
  237.         SCgetscreen(SCdata *sc,int *cf)
  238.             Gets a screen of data from the user, using the array of field
  239.             structures pointed to by 'sc'. On entry, the current field is
  240.             set to 'cf', and on exit, 'cf' is set to the current field.
  241.         SCnf(SCdata *sc)
  242.             Returns the number of fields in the screen pointed to by 'sc'.
  243.         SCshow(SCdata *sc)
  244.             Displays the current screen defined by 'sc'.
  245.     kb
  246.         KBcheck()
  247.             Checks to see if a key has been hit.
  248.         KBgetc(char *c,char *s,int f)
  249.             Gets a key from the keyboard. Will not return until a key
  250.             has been hit which is found in the string 's'. 'f' specifies
  251.             certain flags, such as 'allow upper case only', 'bell on
  252.             error', and 'return <RETURN> on valid'. The function will
  253.             also return if any non-alphanumeric key is pressed.
  254.         KBgetch()
  255.             Gets a character from the keyboard. Waits for a keypress and
  256.             does not echo.
  257.         KBgetn(double *n,uint w,uint d)
  258.             Gets a number from the keyboard. 'n' is a pointer to the
  259.             number, 'w' is the total width of the field, and 'd' is the
  260.             number of decimals.
  261.         KBgets(char *s,uint l)
  262.             Gets a string from the keyboard. 's' is a pointer to an area
  263.             to store the string, and 'l' is the total field width.
  264.         KBnwgetch()
  265.             Gets a character from the keyboard. Does not wait for a
  266.             keypress.
  267.         KBsetfunc(void (*func)())
  268.             Defines a function to be called while waiting for a keypress.
  269.         KBsettrap(uchar key,void (*func)())
  270.             Sets up trapping, so that the function 'func' is called
  271.             whenever the key 'key' is pressed.
  272. DB
  273.     db
  274.         DBadd(void *r)
  275.             Add the record pointed to by 'r' to the current database
  276.             file, updating all indexes.
  277.         DBbot()
  278.             Return the last record in the current database file, using
  279.             the current index to determine.
  280.         DBclose()
  281.             Close the current database file. The new current file is
  282.             the last opened one.
  283.         DBcmp(void *rs,void *rd)
  284.             Compares two memory areas. The number of bytes compared is
  285.             the current database file's record length.
  286.         DBcopy(void *rs,void *rd)
  287.             Copies the area pointed to by 'rs' into the area pointed to
  288.             by 'rd'. The number of bytes copied is the current database
  289.             file's record length.
  290.         DBdelete()
  291.             Delete the current record from the current file.
  292.         DBend()
  293.             Orderly shutdown of Database system. Closes all files.
  294.             Should not be called by the programmer, as it is set up as
  295.             an 'atexit' function by the first DBopen call.
  296.         DBfindfirst(void *r)
  297.             Return the first record in the current file which matches 'r',
  298.             using the current index function to determine. Return the
  299.             record before which 'r' should be inserted if no match.
  300.         DBfindnext(void *r)
  301.             Return the next record which matches the one previously
  302.             found by DBfindfirst.
  303.         DBfindrec(void *r)
  304.             Return the record number of the record which matches 'r' in
  305.             the current file, using the current index function to
  306.             determine a match. Return 0 if no matches.
  307.         DBgo(int r)
  308.             Set the current record to record 'r' in the current database.
  309.         DBindex(char *fn,int (*func)())
  310.             Open the file specified by 'fn' as an index file for the
  311.             current database file and make it the current index. 'func'
  312.             specifies the function called to determine ordering in the
  313.             file.
  314.         DBiread(int n,int d)
  315.             Read the index record 'n' into temporary storage, and return
  316.             either the next record in the linked list, or the previous,
  317.             depending on the value of 'd'. This is an internal routine
  318.             and should not be used by the programmer. It is specific to
  319.             linked list indexing.
  320.         DBiwrite(int n)
  321.             Write the temporary storage to the index record 'n'. See above.
  322.         DBopen(char *fn,int rs)
  323.             Open the database file specified by 'fn', record size is
  324.             'rs' bytes.
  325.         DBread(void *r)
  326.             Read the current record from the current file into the
  327.             buffer pointed to by 'r'.
  328.         DBreadn(int rn,void *r)
  329.             Read record 'rn' from the current file into 'r'.
  330.         DBrecno()
  331.             Return the current record number in the current file.
  332.         DBseekfirst(void *r,int (*func)())
  333.             Return the first record which matches 'r', using 'func' to
  334.             determine a match. Scan through the file using the current
  335.             index. Return 0 if no match.
  336.         DBseeknext(void *r,int (*func)())
  337.             Return the next matching record, as per the above function.
  338.         DBselect(DBfile *db)
  339.             Make the database file specified by 'db' the current one.
  340.         DBsetindex(int n)
  341.             Make index 'n' the current index for the current database
  342.             file. 'n'=0 means use no indexing.
  343.         DBskip(int n)
  344.             Skip 'n' records forwards ('n' +ve) or backwards ('n' -ve)
  345.             in the current file, using the current index to determine.
  346.         DBtop()
  347.             Return the first record in the current database file, using
  348.             the current index to determine.
  349.         DBwrite(void *r)
  350.             Write the record pointed to by 'r' to the current record
  351.             in the current file.
  352. TL
  353.     date
  354.         datelong(datest *d)
  355.             Convert a date to a long.
  356.         daynam(int d)
  357.             Return a pointer to the 3 character abbreviation for the
  358.             day 'n'.
  359.         dayname(int d)
  360.             Return a pointer to the full name of day 'n'.
  361.         leapyear(int y)
  362.             Return TRUE if 'y' is a leapyear.
  363.         longdate(datest *ds,long d)
  364.             Convert the long 'd' into a date and place it in 'ds'.
  365.         longdow(long d)
  366.             Return the day of the week on day 'd'.
  367.         monlen(int m,int y)
  368.             Return the number of days in month 'm' in year 'y'.
  369.         monsum(int m,int y)
  370.             Return the number of days in the year prior to the first of
  371.             month 'm' in year 'y'.
  372.         monthnam(int m)
  373.             Return a pointer to the 3 character abbreviation for month 'm'.
  374.         monthname(int m)
  375.             Return a pointer to the full name for month 'm'.
  376.     music
  377.         mplay(char *name)
  378.             Plays the Tri-voice tune defined in the file 'name'.
  379.         play(char *s)
  380.             Plays the music specified in the string 's', as per similar
  381.             functions in BASIC.
  382.         tri(short *tune)
  383.             Plays the Tri-voice tune specified by the array 'tune'.
  384.     config
  385.         CFcolcvt(char *s)
  386.             Returns the integer corresponding to the color specified in
  387.             the string 's'.
  388.         CFcolor(int c)
  389.             Returns a pointer to the character string for the color 'c'.
  390.         CFcolval(char *s)
  391.             Returns the 8-bit color code for the fg/bg colors specified
  392.             in the string 's', which is of the form 'fg,bg'.
  393.         CFconf(char *f,CFdata *d)
  394.             Read in the config file defined by 'f', using the structure
  395.             array pointed to by 'd' to determine type and location of
  396.             values read.
  397.         CFinit()
  398.             Initialise the configuration routines. Does not need to be
  399.             called by the programmer as any function which needs the
  400.             system initialised checks for it first and calls it if it
  401.             has not been called already.
  402.         CFopen(char *s)
  403.             Opens the configuration file specified by 's'. If 's' is
  404.             NULL or empty, the program name is used to check with,
  405.             first in the current directory, then the directory in which
  406.             the program exists.
  407.         CFread(char *cmd,char *arg)
  408.             Read the next assignment statement from the config file.
  409.             'cmd' will hold the "variable", and 'arg' the value.
  410.         CFwrite(char *f,CFdata *d)
  411.             Write out the data specified by the structure array pointer 'd'
  412.             to the file specified by 'f'.
  413.     arg
  414.         getarg()
  415.             Every call to getarg returns the next string in the string
  416.             array _argv. This function should be used after getopt to
  417.             successively get the non-switched command line arguments.
  418.         getopt(char *opts,void *ptr1,...,void *ptrn)
  419.             Decodes the array of strings pointed to by '_argv', according
  420.             to rules specified in 'opts'. Every alphabetic character in
  421.             'opts' is a valid command line switch. If the character is
  422.             followed by a ':', the switch has an argument. If the character
  423.             is followed by any other non-alphabetic character, any argument
  424.             present is appended, using the non-alphabetic character as a
  425.             separator.
  426.     ifc
  427.         IFCin()
  428.             Returns the value input from the current parallel port.
  429.         IFCout(uint8 val)
  430.             Outputs 'val' to the current parallel port.
  431.         IFCset(int lpt)
  432.             Sets the current parallel port to 'lpt'.
  433.     misc
  434.         handler()
  435.             Returns 0 to properly respond to a CTRL-C. Should not be
  436.             used by the programmer, as it is called when CTRL-C is pressed.
  437.         trapbreak()
  438.             Sets up CTRL-C handling, pointing it to handler.
  439.     random
  440.         dice(int n,int d)
  441.             Returns a random value as though you had just rolled 'n'
  442.             'd'-sided dice.
  443.         randomise()
  444.             Seeds the random number generator to a random point.
  445.     pr
  446.         PRerror(int n)
  447.             Calls the current specified error handling routine (if there
  448.             is one), and passes it a pointer to an appropriate error
  449.             string. Should not be called by the programmer, as it is
  450.             called by other PR functions when a printer error occurs.
  451.         PRprintf(char *fmt,arg1,...,argn)
  452.             Formats arg1...argn according to the string 'fmt', and outputs
  453.             the result to LPT1:.
  454.         PRputs(char *s)
  455.             Prints the string 's' to LPT1:.
  456.         PRseterr(void (*func)(char *))
  457.             Sets the current error handling routine to 'func'.
  458. -------------------------------------------------------------------------------
  459.