MARJAM10.LIB

The MARJAM Library for Clipper

Version 1.0

Designed & Developed

by

Margaret G. Bodine & James C. Bodine

March 1, 1989
























Page 1

MARJAM10.LIB Documentation March 1, 1989
====================================================================

Table of Contents

Copyrights....................................... 3

Disclaimer....................................... 3

Overview......................................... 3

Registration..................................... 3

Usage............................................ 4

Linking.......................................... 4

Agreement........................................ 4

QBE_MENU......................................... 5

QBE_COUNT........................................ 6

QBE_DELETE....................................... 7

QBE_FILTER....................................... 8

QBE_LABEL........................................ 9

QBE_LOCATE.......................................10

QBE_RECALL.......................................11

QBE_REPORT.......................................12

WNDW_DOWN........................................13

WNDW_LEFT........................................14

WNDW_OUT.........................................15

WNDW_RIGHT.......................................16

WNDW_UP..........................................17

DIM_CLR..........................................18

RVRS_CLR.........................................19

SWTCH_CLR........................................20

UNSLCT_CLR.......................................21

FILE_CNT.........................................22

USR_SLCT.........................................23

History..........................................24

Order Form.......................................25



Page 2

MARJAM10.LIB Documentation March 1, 1989
====================================================================

Copyrights

CLIPPER is a trademark of Nantucket, Corporation

IBM is a trademark of International Business Machines

PLINK86 and PLINK86plus are trademarks of Phoenix Technologies, Ltd.

--------------------------------------------------------------------

Disclaimer

While significant amounts of time and effort were expended designing
and developing the functions and procedures contained in The MARJAM
Library, it can not be guaranteed that they are totally error free.
The MARJAM Library is released "as is" and the authors make no
warranties, expressed or implied, with respect to this software,
including without limitation, warranties of merchantability and
fitness for a particular use. In no event shall the authors be liable
for any direct, indirect or consequential damages, real or imagined.

--------------------------------------------------------------------

Overview

The MARJAM Library is written entirely in the Clipper S87 language
and as such is compatible with IBM computers and any 100% IBM
compatibles that can use the Clipper S87 language. The MARJAM
Library contains one (1) procedure and eighteen (18) functions
that provide the Clipper programmer with additional tools to
develop programs. Basically, The MARJAM Library procedure and
functions are divided into four (4) sections. These include the
Query-By-Example (QBE) procedure and functions, the Window (WNDW)
functions, the Color (CLR) functions and additional miscellaneous
functions. These procedure and functions are designed to allow
the Clipper programmer to provide additional database tools for
the end user as well as screen interface tools.

--------------------------------------------------------------------

Registration

In order to become a registered user of The MARJAM Library, please
send $25, check or money order, in US funds to the following address:

The MARJAM Library
149 Stockton Lane
Rochester, NY 14625

Please make checks payable to Margaret G. Bodine or James C. Bodine.

Becoming a registered user will entitle you to the following:

- Notification of future revisions prior to release
- Updating to future revisions for $10 prior to release
- Source code for currently released version of the MARJAM Library

Please use the ORDER FORM on the last page of this documentation
to become a registered user.

Page 3

MARJAM10.LIB Documentation March 1, 1989
====================================================================

Usage

All procedures and functions, since written entirely with the
Clipper S87 language, of The MARJAM Library can be used like any
other Clipper procedure or function. No special usage is required
however, examples of sample usages of each procedure and function
are provided in the discussion for each procedure and function.
Proper syntax for each procedure or function is also provided in
this discussion area.

--------------------------------------------------------------------

Linking

During the design and development of The MARJAM Library, the only
linker used was the PLINK86 linker provided with the Clipper S87
program. Since the MARJAM Library is a library, it should be copied
into the same directory as the Clipper and Extend libraries. If
your application utilizes any procedure or function of The MARJAM
Library, than you link command need only include The MARJAM Library
in the command. For example if you were to use the RVRS_CLR function
in your application, than your link command would need to be executed
as follows:

PLINK86 Fi [your filename] Lib Clipper, MARJAM, Extend

The above command assumes you have included a library path for the
various libraries you use in your AUTOEXEC file.

--------------------------------------------------------------------

Agreement

Any user of The MARJAM Library is hereby authorized to use this
library on a trial basis for evaluation purposes. If a user is
interested in using The MARJAM Library in its applications, than
that user is expected to become a registered user. If a user
does not plan on using The MARJAM Library, buts would like to pass
a copy of The MARJAM Library on to other potential users, all
copies passed shall be in the archived format and must contain The
MARJAM Library and Documentation, files MARJAM10.LIB and MARJAM10.DOC.
Your adherence to this agreement will be appreciated.



















Page 4

MARJAM10.LIB Documentation March 1, 1989
====================================================================

QBE_MENU

This procedure allows you to execute any of the Query-By-Example
(QBE) functions contained in the MARJAM Library by presenting a
menu of these functions. Since these functions can only work if
an active database is used, this program also provides you with
a list of available databases (if one is not already used) for the
user to select prior to executing the QBE function selected.

There are two (2) ways a programmer can make use of this procedure.
First, you can make this an option on a menu and execute the procedure
if selected. Thus programming would appear as follows:

@ x,y PROMPT "option 1"
@ x,y+1 PROMPT "option 2"
@ x,y+2 PROMPT "QUERY" && use MARJAM Library functions
@ x,y+3 PROMPT "option 4"
MENU TO choice
DO CASE
CASE choice = 1
commands
CASE choice = 2
commands
CASE choice = 3
DO qbe_menu
CASE choice = 4
commands
ENDCASE

The other method would be to make using the QBE functions a "hot
key" for the user to select. For this method the programming would
be as follows:

EXTERNAL qbe_menu
SET KEY -1 TO qbe_menu && make F2 key the "hot key"

Either method is acceptable and will execute the QBE_MENU procedure.























Page 5

MARJAM10.LIB Documentation March 1, 1989
====================================================================

QBE_COUNT

This function allows the end user to count the number of records of
an active database which meet the conditions established by the user
via the Query-By-Example method.

SYNTAX: QBE_COUNT()

PASS: nothing

RETURN: .F. if aborted
.T. if completed

SAMPLE:

USE database INDEX data
QBE_COUNT()
USE










































Page 6

MARJAM10.LIB Documentation March 1, 1989
====================================================================

QBE_DELETE

This function allows the end user to mark for deletion records of
an active database which meet the conditions established by the user
via the Query-By-Example method.

SYNTAX: QBE_DELETE()

PASS: nothing

RETURN: .F. if aborted
.T. if completed

SAMPLE:

USE database INDEX data
QBE_DELETE()
IF mconfirm = "Y" && confirm permanent removal
PACK
ENDIF
USE


SEE ALSO: QBE_RECALL




































Page 7

MARJAM10.LIB Documentation March 1, 1989
====================================================================

QBE_FILTER

This function allows the end user to set a filter for an active
database which meet the conditions established by the user via
the Query-By-Example method. The function internally sets the
filter and executes the necessary GO TOP command to make the
filter active.

SYNTAX: QBE_FILTER()

PASS: nothing

RETURN: .F. if aborted
.T. if completed

SAMPLE:

USE database INDEX data
QBE_FILTER()
commands && other commands such as DBEDIT()
USE







































Page 8

MARJAM10.LIB Documentation March 1, 1989
====================================================================

QBE_LABEL

This function allows the end user to output any number of records of
an active database which meet the conditions established by the user
via the Query-By-Example method using any predefined .LBL file. A
menu of all available .LBL files are presented to the user for
selection prior to executing the Query-By-Example prompts.

Since this function will fail if the selected .LBL file is not
compatible with the database in use (ie: the fields in the database
are not those contained in the .LBL file), this function allows for
the user to pass a character string to "filter" only those .LBL files
that contain the character string. If no string is provided, all
.LBL files will be listed.

In order to make this function more useful, and to prevent failure
it is suggested that individual .LBL files utilize a unique letter
as the first character in the .LBL filename that ties the file to
its associated database. For instance, if a database of customers
existed called CUST.DBF, any associated .LBL files would start with
the letter "C", such as CACTIVE.LBL for a label file of active
customers.

The function will list those records meeting the QBE condition in
the label format to the screen, printer or file, the choice also
made by the user. If a file is selected, the user is prompted for
a name and the suffix .TXT is automatically appended to the name.

SYNTAX: QBE_LABEL([expC])

expC must be enclosed in quotes - "C"

PASS: expC

RETURN: .F. if aborted
.T. if completed

SAMPLE:

USE database INDEX data
QBE_LABEL("D")
USE


SEE ALSO: QBE_REPORT















Page 9

MARJAM10.LIB Documentation March 1, 1989
====================================================================

QBE_LOCATE

This function allows the end user to locate the first record of
an active database which meet the conditions established by the user
via the Query-By-Example method. After locating the first record,
the function allows the user to continue locating records which meet
the condition or quit locating records. The record number of each
record located is displayed on the screen for the user to view.

SYNTAX: QBE_LOCATE()

PASS: nothing

RETURN: .F. if aborted
.T. if completed

SAMPLE:

USE database INDEX data
QBE_LOCATE()
USE







































Page 10

MARJAM10.LIB Documentation March 1, 1989
====================================================================

QBE_RECALL

This function allows the end user to recall records marked for
deletion in an active database which meet the conditions established by
the user via the Query-By-Example method. This function will only
recall records marked for deletion that have not been permanently
removed via the PACK command. If the user is recalling records
marked for deletion via the QBE_DELETE function, care should be
taken to use the same Query-By-Example conditions with the QBE_RECALL
function as used with the QBE_DELETE function or all records deleted
many not be recalled.

SYNTAX: QBE_RECALL()

PASS: nothing

RETURN: .F. if aborted
.T. if completed

SAMPLE:

USE database INDEX data
QBE_RECALL()
USE


SEE ALSO: QBE_DELETE

































Page 11

MARJAM10.LIB Documentation March 1, 1989
====================================================================

QBE_REPORT

This function allows the end user to output any number of records of
an active database which meet the conditions established by the user
via the Query-By-Example method using any predefined .FRM file. A
menu of all available .FRM files are presented to the user for
selection prior to executing the Query-By-Example prompts.

Since this function will fail if the selected .FRM file is not
compatible with the database in use (ie: the fields in the database
are not those contained in the .FRM file), this function allows for
the user to pass a character string to "filter" only those .FRM files
that contain the character string. If no string is provided, all
.FRM files will be listed.

In order to make this function more useful, and to prevent failure
it is suggested that individual .FRM files utilize a unique letter
as the first character in the .FRM filename that ties the file to
its associated database. For instance, if a database of customers
existed called CUST.DBF, any associated .FRM files would start with
the letter "C", such as CACTIVE.FRM for a report file of active
customers.

The function will list those records meeting the QBE condition in
the report format to the screen, printer or file, the choice also
made by the user. If a file is selected, the user is prompted for
a name and the suffix .TXT is automatically appended to the name.

SYNTAX: QBE_REPORT([expC])

PASS: expC character string (must be enclosed in quotes)

RETURN: .F. if aborted
.T. if completed

SAMPLE:

USE database INDEX data
QBE_REPORT("D")
USE


SEE ALSO: QBE_LABEL

















Page 12

MARJAM10.LIB Documentation March 1, 1989
====================================================================

WNDW_DOWN

This function allows the programmer to display an "exploding"
window that "explodes" in the down direction. Options as to the
location, border, time for the "exploding" effect and whether the
completed window is "shadowed" or not are provided.

SYNTAX:

WNDW_DOWN(,,,,,,[expN7])

PASS: expN1 top row of window
expN2 left column of window
expN3 bottom row of window
expN4 right column of window
expN5 border type number (see table below)
expN6 time of "explosion" (min 1)
expN7 optional shadow number (0 = no shadow, 1 = shadow)

TABLE OF BORDERS
--------------------------
0 = no border
1 = single top, bottom & sides
2 = single top & bottom, double sides
3 = double top & bottom, single sides
4 = double top, bottom & sides

RETURN: .T.
.F. if width or height less than 3 columns or 3 rows or
less than 6 parameters are passed.

SAMPLE:

WNDW_DOWN(5,10,20,20,4,5,0)

This will "explode" a window down from row 5, column 10
to row 20, column 20 with a double line border and no shadow.

WNDW_DOWN(5,40,20,50,1,10,1)

This will "explode" a window down from row 5, column 40
to row 20, column 50 with a single line border and a
a shadow. This window will take twice as long to "explode".


SEE ALSO: WNDW_UP














Page 13

MARJAM10.LIB Documentation March 1, 1989
====================================================================

WNDW_LEFT

This function allows the programmer to display an "exploding"
window that "explodes" in the left direction. Options as to the
location, border, time for the "exploding" effect and whether the
completed window is "shadowed" or not are provided.

SYNTAX:

WNDW_LEFT(,,,,,,[expN7])

PASS: expN1 top row of window
expN2 left column of window
expN3 bottom row of window
expN4 right column of window
expN5 border type number (see table below)
expN6 time of "explosion" (min 1)
expN7 optional shadow number (0 = no shadow, 1 = shadow)

TABLE OF BORDERS
--------------------------
0 = no border
1 = single top, bottom & sides
2 = single top & bottom, double sides
3 = double top & bottom, single sides
4 = double top, bottom & sides

RETURN: .T.
.F. if width or height less than 3 columns or 3 rows or
less than 6 parameters are passed.

SAMPLE:

WNDW_LEFT(5,10,10,60,4,5,0)

This will "explode" a window left from row 5, column 60
to row 10, column 10 with a double line border and no shadow.

WNDW_LEFT(15,10,20,70,1,10,1)

This will "explode" a window left from row 15, column 70
to row 20, column 10 with a single line border and a
shadow. This window will take twice as long to "explode".


SEE ALSO: WNDW_RIGHT














Page 14

MARJAM10.LIB Documentation March 1, 1989
====================================================================

WNDW_OUT

This function allows the programmer to display an "exploding"
window that "explodes" in the left and right directions. Options
as to the location, border, time for the "exploding" effect and
whether the completed window is "shadowed" or not are provided.

SYNTAX:

WNDW_OUT(,,,,,,[expN7])

PASS: expN1 top row of window
expN2 left column of window
expN3 bottom row of window
expN4 right column of window
expN5 border type number (see table below)
expN6 time of "explosion" (min 1)
expN7 optional shadow number (0 = no shadow, 1 = shadow)

TABLE OF BORDERS
--------------------------
0 = no border
1 = single top, bottom & sides
2 = single top & bottom, double sides
3 = double top & bottom, single sides
4 = double top, bottom & sides

RETURN: .T.
.F. if width or height less than 3 columns or 3 rows or
less than 6 parameters are passed.

SAMPLE:

WNDW_OUT(5,10,10,60,4,5,0)

This will "explode" a window from the center of column 60
and column 10 (column 35) out to row 5, column 10 and to
row 10, column 60 with a double line border and no shadow.

WNDW_OUT(15,10,20,70,1,10,1)

This will "explode" a window from the center of column 70
and column 10 (column 40) out to row 15, column 10 and to
row 20, column 70 with a single line border and a shadow.
This window will take twice as long to "explode".

The QBE functions use this function rather extensively.













Page 15

MARJAM10.LIB Documentation March 1, 1989
====================================================================

WNDW_RIGHT

This function allows the programmer to display an "exploding"
window that "explodes" in the right direction. Options as to the
location, border, time for the "exploding" effect and whether the
completed window is "shadowed" or not are provided.

SYNTAX:

WNDW_RIGHT(,,,,,,[expN7])

PASS: expN1 top row of window
expN2 left column of window
expN3 bottom row of window
expN4 right column of window
expN5 border type number (see table below)
expN6 time of "explosion" (min 1)
expN7 optional shadow number (0 = no shadow, 1 = shadow)

TABLE OF BORDERS
--------------------------
0 = no border
1 = single top, bottom & sides
2 = single top & bottom, double sides
3 = double top & bottom, single sides
4 = double top, bottom & sides

RETURN: .T.
.F. if width or height less than 3 columns or 3 rows or
less than 6 parameters are passed.

SAMPLE:

WNDW_RIGHT(5,10,10,60,4,5,0)

This will "explode" a window right from row 5, column 10
to row 10, column 60 with a double line border and no shadow.

WNDW_RIGHT(15,10,20,70,1,10,1)

This will "explode" a window right from row 15, column 10
to row 20, column 70 with a single line border and a
shadow. This window will take twice as long to "explode".


SEE ALSO: WNDW_LEFT














Page 16

MARJAM10.LIB Documentation March 1, 1989
====================================================================

WNDW_UP

This function allows the programmer to display an "exploding"
window that "explodes" in the up direction. Options as to the
location, border, time for the "exploding" effect and whether the
completed window is "shadowed" or not are provided.

SYNTAX:

WNDW_UP(,,,,,,[expN7])

PASS: expN1 top row of window
expN2 left column of window
expN3 bottom row of window
expN4 right column of window
expN5 border type number (see table below)
expN6 time of "explosion" (min 1)
expN7 optional shadow number (0 = no shadow, 1 = shadow)

TABLE OF BORDERS
--------------------------
0 = no border
1 = single top, bottom & sides
2 = single top & bottom, double sides
3 = double top & bottom, single sides
4 = double top, bottom & sides

RETURN: .T.
.F. if width or height less than 3 columns or 3 rows or
less than 6 parameters are passed.

SAMPLE:

WNDW_UP(5,10,20,20,4,5,0)

This will "explode" a window up from row 20, column 10
to row 5, column 20 with a double line border and no shadow.

WNDW_UP(5,40,20,50,1,10,1)

This will "explode" a window up from row 20, column 40
to row 5, column 50 with a single line border and a
a shadow. This window will take twice as long to "explode".


SEE ALSO: WNDW_DOWN














Page 17

MARJAM10.LIB Documentation March 1, 1989
====================================================================

DIM_CLR

This function allows the programmer to eliminate any "bright"
colors in the current color setting. In other words, any "+'s"
in the current color settings are eliminated. This function
actually resets the color setting.

SYNTAX: DIM_CLR()

PASS: nothing

RETURN: .T.

SAMPLE:

SET COLOR TO w+/b,gr+/r,n,n,w+/n
currcolor = SETCOLOR()

currcolor would be w+/b,gr+/r,n,n,w+/n

DIM_CLR()
newcolor = SETCOLOR()

newcolor would be w/b,gr/r,n,n,w/n

SETCOLOR(currcolor)

this would return colors to "bright"
































Page 18

MARJAM10.LIB Documentation March 1, 1989
====================================================================

RVRS_CLR

This function allows the programmer to reverse the colors in the
current color setting. In other words, the background will become
the foreground and the foreground the background in both the normal
area and the enhanced area. Any enhancements to the color settings,
such as bright or flash, remain with their original area.
(ie: start in foreground, end in foreground)

SYNTAX: RVRS_CLR()

PASS: nothing

RETURN: .T.

SAMPLE:

SET COLOR TO w+/b,gr+/r,n,n,w+/n
currcolor = SETCOLOR()

currcolor would be w+/b,gr+/r,n,n,w+/n

RVRS_CLR()
newcolor = SETCOLOR()

newcolor would be b+/w,r+/gr,n,n,w+/n

SETCOLOR(currcolor) && to return to original settings
































Page 19

MARJAM10.LIB Documentation March 1, 1989
====================================================================

SWTCH_CLR

This function allows the programmer to switch the colors in the
current color setting. In other words, the normal colors will be
switched with the enhanced colors. Any enhancements to the color
settings, such as bright or flash, transfer to their new area.
(ie: start in enhanced area, end in enhanced area)

SYNTAX: SWTCH_CLR()

PASS: nothing

RETURN: .T.

SAMPLE:

SET COLOR TO w+/b,gr+/r,n,n,w+/n
currcolor = SETCOLOR()

currcolor would be w+/b,gr+/r,n,n,w+/n

SWTCH_CLR()
newcolor = SETCOLOR()

newcolor would be gr+/r,w+/b,n,n,w+/n

SETCOLOR(currcolor) && to return to original settings

































Page 20

MARJAM10.LIB Documentation March 1, 1989
====================================================================

UNSLCT_CLR

This function allows the programmer to "blank out" the unselected area
of the current color settings. In other words, the unselected color
foreground will be the same as the background in order for unselected
items to appear to be "blanked out". This function is especially
during the use of the ACHOICE() function for items that are not
available for selection.

SYNTAX: UNSLCT_CLR()

PASS: nothing

RETURN: .T.

SAMPLE:

SET COLOR TO w+/b,gr+/r,n,n,w+/n
currcolor = SETCOLOR()

currcolor would be w+/b,gr+/r,n,n,w+/n

UNSLCT_CLR()
newcolor = SETCOLOR()

newcolor would be b+/w,r+/gr,n,n,n/n

SETCOLOR(currcolor) && to return to original settings
































Page 21

MARJAM10.LIB Documentation March 1, 1989
====================================================================

FILE_CNT

This function allows the programmer to accurately determine the
number of files in a directory using the ADIR() function. One
problem with the ADIR() function is that if the attribute array
( the array5 option on the Clipper S87 manual) is not passed with
the ADIR() function, the two directory files "." and ".." will
not be counted by the function when matching a "*.*" skeleton.
While a programmer can prevent this by including this fifth array
in the ADIR() function after DECLARE'ing it, the FILE_CNT function
takes care of this with one line of code.

SYNTAX: FILE_CNT()

PASS: expC a character string of the skeleton such as *.*
this string must be enclosed in quotes.

RETURN: a numeric integer of the number of files that meet the
skeleton.

SAMPLE:

DECLARE all_files[FILE_CNT("*.*")]

or

filecount = FILE_CNT("*.*")
DECLARE all_files[filecount]
































Page 22

MARJAM10.LIB Documentation March 1, 1989
====================================================================

USR_SLCT

This function is a general all purpose function that can be used
with ACHOICE to control the returned value when a key that generates
an exception is pressed. These keys include Leftarrow, Rightarrow,
Home, End, Return, Escape and any letter key. This function either
returns a value to ACHOICE that maintains it active or terminates
its execution. Some keys will generate a beep to indicate the error
of pressing the key.

SYNTAX:

ACHOICE(,,,,[,,
"USR_SLCT",[[,]]])

PASS: nothing

RETURN: .T.

SAMPLE:

DECLARE array1[5]
DECLARE array2[5]
choice = ACHOICE(5,10,9,20,array1,array2,USR_SLCT)


While not verified, it is suspected that this function will also
work with the DBEDIT() function to handle keys that generate exceptions.
































Page 23

MARJAM10.LIB Documentation March 1, 1989
====================================================================

History


March 12, 1989 Initial release
























































Page 24

MARJAM10.LIB ORDER FORM March 1, 1989
====================================================================


DATE: ______________


Please rush to me the MARJAM Library, Version 1.0 in the quantity
indicated below. Enclosed is a check or money order in US funds
which entitles me to become a registered user of the MARJAM Library.
I understand that this registration will provide me with:

- Notification of future revisions prior to release
- Updating to future revisions for $10 prior to release
- Source code for currently released version of the MARJAM Library

I understand all the statements made in the Disclaimer section of
the Documentation and agree to abide by the rules of the Agreement
section of this same Documentation.


____ One (1) copy of the MARJAM Library $ 25.00

____ Four (4) copies of the MARJAM Library $ 75.00

____ Eight (8) copies of the MARJAM Library $125.00

____ Twelve or more copies of the MARJAM Library $175.00


Please make checks payable to Margaret G. Bodine or James C. Bodine

Mail your check or money order to:

The MARJAM Library
149 Stockton Lane
Rochester, NY 14625

Please allow 2 to 3 weeks for delivery.

Thank you in advance for your interest in The MARJAM Library.






















Page 25