Programmer 7500/MAX_PROGRAMMERS.iso/CLIPPER/MISC/LIBTOOLS.ZIP/BRIAN_S.DOC

Text File | 1988-09-18 | 22.6 KB | 912 lines

                    LIBRARY APPLICATIONS TOOLKIT

                             Version 1.0

                              Written by:

                           Brian Vanlandingham
                           in cooperation with

                      North Carolina Central University
                  School of Library and Information Science

                                 c1988

                       Written in Clipper Summer '87

  The   library  applications  toolbox  contains  a   number   of
predefined  functions for developing library oriented information
retrieval systems.
 Parameters  are  evaluated  before  being  passed  to  the   the
procedures.  In  most  cases an improper parameter will return  a
null  value  although attempting to pass illegal data  types  may
result  in  ambiguous or bizarre results.  Variables used in  the
procedures  are declared private so there should be  no  problems
caused by duplicating variable names in other parts of a program.

  Each  of  the  extended search routines  provided  require  the
Clipper  Extend.lib  passed  in the linkage list to  the  linkage
editor.  Other  routines  are identified as to  any  restrictions
imposed by their syntax.

Syntax for the linkage list is:

(Turbo C linker)
TLINK <myfile>,<myfile>,,CLIPPER+EXTEND+BRIAN_S

(Microsoft Link) (May need to increase segments to 200)
TLINK <myfile>,<myfile>,,CLIPPER+EXTEND+BRIAN_S

(Clipper summer 87)
PLINK86 FI <my_file>, <myfile> LIB CLIPPER, EXTEND, BRIAN_S

***************************************


PROCEDURE BOX_WRAP

Displays a text variable with word wrap inside a box at specified
coordinates.

Call as:

do box_wrap with var_name,row_number,left_column,right_column,message

usage:

save screen
store "Annotation" to mess
do b_wrap with annotation,10,10,40,mess
wait
restore screen

Will  display  the variable field inside a box beginning  at  row
10,column ten, and extending to column 40.
The  message string is diplayed centered across the box  line  of
the box.

The vertical height of the box is dependent on the maximum length
of the  variable.  Passing untrimed character strings will result
in empty spaces being left at the bottom of the box.

The message must be small enough to fit across the top of the box
or it will be ignored.

Use for screen displays only since the printer does not use the
@ x,y BOX FRAME frame command.

*****************************************************

FUNCTION WRAP_ME()

Performs word wrap for print functions.

Call as:
 store wrap_me(var_name,startcol,endcol,indent) to line_cnt

var_name = variable passed
startcol = starting at left column #
endcol = endding at right column #
indent = indent 2,3,4,5... lines

line_cnt = number of lines taken by wrapped character string

Example:

store "abcdefg hi j klmno pqrstuv wxyz" to string
store wrap_me(string,5,20,3) to var



results in:

     accdefg hi j klmno
        pqrstuv wxyz

Returns a result of 2 that can be use to control pagebreaks.

example:

store 1 to linecnt
do while .not. eof()
store field_name to string
store wrap_me(string,5,20,3) + line_cnt to line_cnt
if line_cnt > 55
eject
store 2 to linecnt
endif
enddo


Optionally the return value can be discarded:

store wrap_me(string,5,20,3) to not_used_for_anything

***********************************************************

FUNCTION Q_WRAP()

usage: store Q_WRAP(var,0) to line_cnt
or:    store Q_WRAP(var,1) to line_cnt


Provides a quick, dirty word wrap with one command verb.

defaults are: begin at column 3
              end at column 70
              indent 4 spaces after first line

The second parameter (1 or 0) controls whether or not to include
blank spaces at the beginning of the character string as part
of the variable. The default is 0, not to count blank spaces.

i.e.  Q_WRAP(var,0) and Q_WRAP(var) are the same.
 Q_WRAP(var,1) will remove leading blanks before processing the
string.



To change defaults it will be necessary to recompile the function.
Returns line counter that can be used to control pagebreaks

example:

store 1 to linecnt
do while .not. eof()
store field_name to string

store Q_wrap(string) + line_cnt to line_cnt

if line_cnt > 50
eject
store 2 to line_cnt
endif
enddo

*****************************************************

FUNCTION CENTER()

Centers a line of text in N spaces

Usage:

@ 10,0 say center("Hello",80)
@ 20,0 say center("Hello",40)

etc..

If used without the second parameter a column width
of 80 if assumed.

@ 10,0 say center("Hello")

*********************************************************

FUNCTION NOPRINT()

Provides error trap to check online printer status.

usage:

if NOPRINT()
return         && or loop, or whatever
endif
            && else go ahead and print something

If printer is not available, saves screen, displays
message
              PRINTER IS NOT READY
        READY PRINTER, PRESS <Y> TO CONTINUE
           OR PRESS <N> TO ABANDON PRINT

The  message stays on the screen as long as the user continues to
press <Y> or until the printer is ready.

returns .T. if the printer is NOT READY
returns .F. if the printer IS READY

Requires extend.lib in the linkage list passed to the linker.

**************************************************************

FUNCTION SAIDYES()

Forces Y or N response to user prompt.

Turns off console and cursor, and forces a wait
state until 'YyNn' is entered at the keyboard
returns .t. if 'Yy' is entered, else .f. if 'Nn'
or the excape key is pressed.


SAIDYES() turns cursor on after return
SAIDYES(0) leaves cursor off after return

USAGE:

@ 10,3 say "Go ahead and do whatever? (Y/N) ?"

if SAIDYES()
 DO whatever
 else
return
endif

*****************************************************************

FUNCTION INWAIT()

Doesn't  do anything. Turns off console and cursor and forces  a
wait state until a keypress, then turns them back on again.

USAGE:

@ 5,10 say "press any key to continue"

inwait()  && turns cursor on after returning
inwait(0) && leaves cursor off after returning

do whatever

***********************************************************

FUNCTION AUT_KEY()

Returns OCLC type author search key from character string.

usage:

store "JONES, BILL A" to name
store AUT_KEY(name) to var
? var

returns "JONEBILA" as index key

Variables passed to the function must be of type string.  Shorter
names passed will return strings ending in blanks.

example:

store "JONES, BILL" to name
store AUT_KEY(name) to var
? var
returns "JONEBIL " as index key

(i.e. all return values are 8 characters long)

**************************************************************

FUNCTION TITL_KEY()

Returns OCLC type title index key from character string.

example:

store "CAT IN THE HAT" to title
store TITL_KEY(title) to var
? VAR

returns: "CATINTHH" as index key

Shorter character strings passed return strings ending in blanks.

usage:

store "CAT IN THE" to title
store TITL_KEY(title) to var
? var

returns: "CATINTH " as index key

(i.e. all return values are 8 characters long)

***************************************************************

FUNCTION U_NIQUE()

Returns unique index key for string variables.

Index based on charater data type must be in use before  function
is called.

Checks to see if key is unique in index,  if not, adds "A" to end
of   character   string,   and  checks  again.   If   still   not
unique,removes  the "A",  adds a "B",  etc.,  until a unique  key
value  is obtained.  In the event that all letters up through "Z"
are  in use,  the function adds another "A" and starts  over.  As
more letters are tried the time taken by the function increases.

Be  sure  data  field is long enough  to  accept  the  additional
letters added by the function.

returns .t.

usage:

store U_NIQUE(index_key) to var

replace field_name with var

********************************************************************

FUNCTION TITL_SRCH()

Use  with index key searches based on the TITL_KEY() function  to
list and display multiple items sharing the same index keys.

Displays  up  to  73  characters of  character  string  per  item
displayed.

TITL_SEARCH()  will  display  listing  of up  to  15  titles  per
screenload retrieved by the search.

Returns logical values .t. or .f.

  Returns  .t.  and leaves file open if the user A)ccepts a title
found in a list of items displayed in screenloads of items.

If  the  SEEK  command fails,  or if the user  quits  the  search
without A)ccepting a record from the screen display the  function
returns .f. and closes all data files.

File  must  be  indexed  on key expression  compatible  with  the
TITL_KEY function.  Parameters passed are the name of the  index
field and the expression to be displayed for selection.

usage:  TITL_SRCH("TKEY","TITLE")
        && uses the index key TKEY and displays the
        && retrieved field TITLE

Example:

use file index tkey

IF TITL_SRCH("TKEY","TITLE")
 DO edit   &&(print, display, etc.)
  else
   return
ENDIF

**********************************************************************

FUNCTION T_SEARCH()

Functions similar to the TITL_SRCH() function above, but displays
individual  records  one at a time with the options  of  browsing
forward  and  backward in the retrieval set  until  a  particular
record  is  selected.  Returns logical .t.  if a user A)ccepts  a
particular record in the retrieval set.  If no match is found  or
the Q)uit search option is selected, closes files and returns .f.

File  must  be  indexed  on key expression  compatible  with  the
TITL_KEY function.

CALL as T_SEARCH(<indexfieldname>,progname)

With  PROGNAME  as  the name of the  procedure  file  to  display
individual records.

Note  that T_SEARCH() reserves the bottom of the screen beginning
at  line  24  for the user  request  line.  PROGNAME  should  not
overwrite this area.

USAGE:

use file index tkey
store  "DISPLAY" to prog
do while .t.

IF T_SEARCH("TKEY",prog)
  do edit    && or print, delete, recall, or whatever
else
return
endif

procedure DISPLAY
clear
@ 2,0 say "TITLE" + title
@ 4,0 say "AUTHOR" + author
@ 6,0 say "PUB" + publisher
@ 8,0 say "DATE" + dtoc(date)
return

**********************************************************

FUNCTION GET_TKEY()

Prompts user for OCLC type title search key.

Returns  null  if  user escapes without entering  keys  otherwise
returns 8 character upper case search key.

USAGE: store GET_TKEY() to var_name

**********************************************************

FUNCTION GET_AKEY()

Prompts user for OCLC type author search key.

Returns  null  if user escapes without  entering  keys  otherwise
returns 8 character upper case search key.

USAGE: store GET_AKEY() to var_name

********************************************************************

FUNCTION GOOD_DOS()

Returns variable with illegal DOS filename characters removed and
replaced with underlines.

Intended  to  prevent  errors from attempting to open  file  with
illegal characters in name.

Illegal characters tested are:
 "/\[]:|<>+=;,  and blank (chr(32))

Usage:   GOOD_DOS(var)

example:
     store space(8) to var
     @ 5,1 say "Enter name of output file" get var
     read
     store GOOD_DOS(var) to var
     store var + ".txt" to var
     set printer to &var

Converts "my file" to "my_file", etc.
***************************************************

FUNCTION BAD_DOS

Checks for illegal characters in filename but does not
correct illegal characters.

Returns .t. if name contains
     "/\[]:|<>+=;,  and blank (chr(32))

otherwise returns .f.


***************************************************

FUNCTION STOPWORD()

Designed  to  be  used  with  the  TITL_KEY  function  to  remove
stopwords from the title keys generated by that function.

Requires  a  stopword data file be set up indexed  on  the  words
established as stopwords.

The function automatically adjusts to the length of the character
field in the stopword list.

EXAMPLE:

 Passing  "The cat in the hat" as a variable string
 to the function returns "CAT IN THE HAT".

 Passing "And the west was won" returns
 "WEST WAS WON"

... depending on the terms in the stopword list.

Items  entered  into the stopword list must be of type  character
and upper case.

USAGE:

select 1
use title index stop_title
select 2
use stopword index stopword
select 1

store space(100) to mtitle
@ 10,1 say "Enter title" get mtitle
read
select 2
store stopword(mtitle) to stop_title
select 1

replace title with mtitle
replace t_key with TITL_KEY(stop_title)


Syntax for indexing on stopword()

select 1
use filename
EXTERNAL STOPPER           && required
select 2
use stopword index stopword
select 1
index on stopper(keyfield) to indexname
close data
return

FUNCTION STOPPER
parameters instring
select 2
store len(instring) to inlength
store stopword(instring) to instring
if len(instring) < inlength
store instring + space(inlength - len(instring)) to instring
endif
select 1
return instring


******************************************************************

FUNCTION STOPPED()

Similar to the stopword() function above,  but rotates  stopwords
to the end of the string and appends the number of the characters
that have been rotated in the form "~#",  with # being the number
of  characters  rotated.  Strings longer than 252 characters  are
simply truncated at a 252 character limit.

EXAMPLE:
    store "A new bicycle" to title
    ? stopped(title)

RETURNS:   new bicycle A~2

    store "The new bicycle" to title
    ? stopped(title)

RETURNS: new bicycle The ~4

USAGE:

use title
index on title to titledex

select 1
use title index titledex
select 2
use stopword index stopword
select 1
store space(100) to mtitle
@ 10,1 say "Enter title" get mtitle
read

select 2
store stopped(mtitle) to stop_title
select 1

replace title with stop_title

  Since  the function adds at least 2 and sometimes 3  characters
to  the string,  make the field wherein the string is  stored  at
least 3 characters longer than the input line as displayed to the
user,  lest  the numerical counter be lost and the stopwords  are
left  in the rotated position forever.  The UNSTOPPED()  function
requires  the numerical information to unrotate the stopwords  to
the front of the string.

************************************************************************

FUNCTION UNSTOPPED()

 Reverses  the  action of the STOPPED()  function,  rotating  the
stopwords back to the front of the character string.

Strings passed the the STOPPED() and UNSTOPPED() functions should
not have a tilde "~" as part of the string,  as this will prevent
the  UNSTOPPED()  function  string  from  unrotating  the  string
properly.

USAGE:

? title

RETURNS: new bicycle The ~4

? UNSTOPPED(title)

RETURNS: The new bicycle


********************************************************************

FUNCTION AUT_SRCH()

Indexed author search based on AUT_KEY compatible index keys.

usage: AUT_SRCH("INDEXFIELD","SEARCHFIELD",PROG1, PROG2, PAGE_COUNT)

With  INDEXFIELD being the name of the AUT_KEY() compatible index
field,  SEARCHFIELD being the field to search for unique entries,
PROG1  being the procedure file use to format individual  records
on the screen,  and prog2 being the procedure file used to format
printed copy of search results. Page layout is the responsibility
of  PROG2.  PAGE_COUNT controls the number of individual  records
that  are printed by PROG2 before issuing a line feed to eject  a
page from the printer.



Retrieves multiple records for varying forms of authors names.

Displays results in form:
  Set 1)  SMITH, JOE             (8 records)
  Set 2)  SMITH JOE A            (4 records)
  Set 3)  SMITH JOE A, 1965-     (2 records)
    etc.

Records  may then be viewed individually of sets of  records  for
particular authors may be printed.

The  procedure use a temporary data file "TEMPSRCH" designated to
memory work area 9,  if this file is not on the logical path  the
function will create it.


Requires Extend.lib in linkage list.

Note  that the procedure uses the lower 2 lines of the screen for
user interface beginning at line 23.  PROG1 should not  overwrite
these areas.

Returns logical values .t. or .f.

Returns .t. and leaves file open if the desired item is found and
A)ccepted in a list of items displayed in screenloads of items.

If  the  SEEK  command fails,  or if the user does not  find  the
desired  item  in the screen displays and exits the  function  it
returns .f. and closes all data files.

EXAMPLE:

select 1
use file index akey

store "DISPLAY" to prog1
store "PRINTME" to prog2

 && to search a field called "AUTHOR" based on the index field "AKEY"
store 3 to pagecount
if AUT_SRCH("AKEY,"AUTHOR",prog1,prog2,pagecount)
do editer  &&printer,or whatever
else
return

endif









  && to search the fields "LNAME" + "FNAME" + "MID"
  && based on the index field "AKEY"
store "LNAME + FNAME + MID" to showfield
store 3 to pagecount
if AUT_SRCH("AKEY",SHOWFIELD,prog1,prog2,pagecount)
do editer  && printer, or whatever
else
return
endif


PROCEDURE DISPLAY

clear
@ 5,0 say "AUTHOR" + author
@ 6,0 say "TITLE"  + title
@ 8,0 say "PUBLISHER" + publisher
return

PROCEDURE PRINTME

? "AUTHOR " + author
? "TITLE " + title
? "PUBLISHER " + pub
return

**************************************************

PROCEDURE STOPMENU

A complete stopword maintenance menu with light bar interface.

Functions  supported  include  create/initialize  stopword  file,
search,  add,  delete,  list or edit stopwords,  pack and reindex
stopword  file,  reinitialize  title key index  fields  with  the
current stopwords in the file, and information screens.

Usage:

DO stopmenu

No  parameters are passed so the procedure returns nothing to the
calling program.

*************************************************************

PROCEDURE EDITHELP

Presents  a 2 screenload list of menu navigation and full  screen
editing  commands.  Called  from help.prg.  clears @ 0,0 so  GETS
remain  in memory after leaving the procedure.  Screen should  be
SAVED before  calling the procedure and RESTORED after it finishes.



******************************************************

PROCEDURE BAR_EDIT

Places  light  bar menu on row 24 of the screen display with  the
options  DELETE,  UNDELETE,  EDIT,  PRINT,  QUIT  EDIT  LINE  and
displays the message RECORD IS DELETED or RECORD IS NOT DELETED.

CALL as DO BAR_EDIT with PROG1,PROG2

prog1 is the name of the procedure to edit individual records.
prog2 is the name of the procedure to print individual records.

PROG1 should not overwrite line 24, as BAR_EDIT clears the screen
@ 24,0 for the edit line.  Any information displayed on that line
will be lost.  Printer and console control while printing is  the
responsibility of PROG2.

Options  to delete or undelete records are confirmed in a  series
of  pop up windows.  The status of the record is then updated  on
row  24.  Quitting the editline leaves the record pointer at  the
same record and leaves the files open.  While on the editline the
record can be repeatedly edited, deleted and recalled.

example:
use whatever

store "editprog" to prog1
store "printme" to prog2

   && goto individual record

do display
do BAR_EDIT with prog1,prog2

close data
return

********************************************************************

PROCEDURE STR_SRCH

Performs  substring  searching of field with up to  three  search
terms and the Boolean operators AND and OR.

The  procedure  calls  BAR_EDIT as editline  for  the  individual
records that are retrieved.

Four parameters are passed: the name of the field to be searched,
the name of the display procedure,  the edit procedure,  and  the
procedure  to format records for printing.  Console control while
printing is the responsibility of the print procedure.


usage:

use file index whatever

store "DISPLAY" to prog1
store "EDITME" to prog2
store "PRINTME" to prog3

do STR_SRCH with "TITLE",prog1,prog2,prog3
return

**************************************************************

FUNCTION NO_DUP_CHR()

Removes  duplicate  characters from a string,  beginning  at  the
leftmost position.

usage: store NO_DUP_CHR(string) to var

example:
      store "123451345AC1" to string
      ? NO_DUP_CHR(string)

      returns: "12345AC"

*******************************************************************

PROCEDURE BOOL_SRCH

Provides  sequential substring searching with up to  nine  search
terms and the Boolean operators AND, OR and NOT.

Four parameters are passed: the name of the field to be searched,
the name of the display procedure,  the edit procedure,  and  the
procedure  to format records for printing.  BAR_EDIT is called as
status line for editing of records.  Console and printer  control
while printing is the responsibility of the print procedure.

usage:

use file index whatever

store "DISPLAY" to prog1
store "EDITME" to prog2
store "PRINTME" to prog3

do BOOL_SRCH with "TITLE",prog1,prog2,prog3
return

*******************************************

FUNCTION EXPLODE()

 Opens 'exploding window' at specified coordinates
 parameters top, left, bottom, right of final position

 Useage: save screen
         explode(5,10,10,50)
         @ 6,11 say "whatever"
         inwait()
         restore screen

******************************************************


FUNCTION IMPLODE()

 closes 'exploding window at specified coordinates
 parameters top,left,bottom,right

    Usage:   save screen
             explode(5,5,20,50)
             @ 6,6 say "whatever"
             &&wait for input from user
             implode(5,5,20,50)


***************************************************

FUNCTION GOODNTX

Determines in .NTX index file is approriate for
 use with a particular .DBF. Useful for confirming
 indexes prior to opening.

CALL AS:

   if GOODNTX(datafile,indexfile)
   do whatever
   else
   do something_else
   endif

   DATAFILE should be passed as file name without .DBF etension
   INDEXFILE should be passed with .NTX extension
    (i.e.  if GOODNTX(mydbf,myindex.ntx)

returns .t. if index is valid for .DBF
returns .f. if error in opening file or if the
  index key is inaproriate for use with this .DBF

Does not accept UDFs in index key expression


*************************************************