








                             DBEXT


                   (A Programmer's Utility)



                          Version 1.0


                      Author:  Keith Roddey


                  Copyright (C) Keith Roddey 1989


DBEXT is a dBASE III/III Plus utility written by a dBASE programmer.  When 
incorporated in your programs, it will cut down on the number of lines of 
code that you will have to write, and it will lend a professional look to 
your programs and allow you to program features otherwise impossible to 
write in straight dBASE code.

DBEXT.BIN and the accompanying documentation are being offered under the
"ShareWare Concept".  If you find this utility of value and plan to 
use it in your programs it is requested that you reward the author's efforts 
by sending him $9.00.  This money will be used to offset the costs associated 
with program developement and distribution.


Keith Roddey
2823 Corning St. #2
Los Angeles, CA.  90034




                        TABLE OF CONTENTS

                 General .....................  2
                 Cursor ......................  3
                 Attribute ...................  4
                 Fill ........................  5
                 Boxes .......................  6
                 Windows ....... .............  7
                 Scrolling ................... 10
                 Printer ..................... 11
                 Cut ......................... 15
                 Defaults .................... 16
                 Command Card ................ 17



                               1

                         GENERAL


DBEXT consists of one file, DBEXT.BIN.  As with any binary module, it must 
first be loaded with the "LOAD" command.

DBEXT is loaded with the command

     LOAD DBEXT

Since DBEXT will keep track of certain defaults after it has been loaded, 
to insure that these defaults are kept, only load it once while running 
your program.  Those defaults that are kept track of are the default 
cursor, the default border characters used to draw boxes and windows, the 
user defined characters used to draw boxes and windows, and the default 
attributes to use when drawing windows.  In addition to these defaults, 
when a window is created, the contents of the screen which the window will 
cover is saved in a dynamic buffer.  If you reload DBEXT while a window is 
still open, then the screen cannot be redrawn.

Once DBEXT is loaded, it is invoked by the following command:

     CALL DBEXT WITH parameter_list

The parameter_list is a character memory variable or it is a literal.  In 
the case where a function returns a value, the parameter_list must be a 
memory variable.  For the command part of the parameter list, it doesn't 
matter whether you use upper or lower case letters.  In addition, leading 
blanks are ignored.  Only one function can be accessed per CALL.  If a 
function is passed an invalid parameter list, DBEXT will return control 
back to dBASE.  This means the only way you know that the function you 
requested of was accomplished is if you see the physical results, either on 
the screen or on the printer.

Return values are specific to the particular function.  You will either use 
the VAL(), the CHR(), or the SUBSTR() or LEFT() functions to get the return 
value.  Only the CUT and PRINTER functions return values.  An example using 
the PRINT function would be:

     print_stat = "P,S"
     CALL DBEXT WITH mstr
     ? ASC(print_stat)

In the explanations that follow regarding the parameter list, brackets [] 
indicate that a parameter is optional and parenthesis () indicate that one 
of the comma delimited values is necessary.













                               2

                          CURSOR


The Cursor function enables you to control the way the cursor is displayed 
(or not displayed).  You may disable the cursor, enable the cursor, or 
specify which scan lines to use when displaying the cursor. 

The 1st parameter is "C" and the 2nd parameter is either "D" (disable), "E" 
(enable), or "T" (type).  If you want to change the type of cursor then a 
3rd and 4th parameter are required.  The 3rd parameter is the starting scan 
line and the 4th is the ending scan line


EXAMPLES

CALL DBEXT WITH "C,D"        && Disable the cursor
CALL DBEXT WITH "C,E"        && Enable the cursor
CALL DBEXT WITH "C,T,0,13"   && Block cursor (monochrome)
CALL DBEXT WITH "C,T,0,7"    && Block cursor (color)
CALL DBEXT WITH "C,T,12,13"  && Standard cursor (monochrome)
CALL DBEXT WITH "C,T,6,7"    && Standard cursor (color)
CALL DBEXT WITH "C,T,13,0"   && Split cursor (monochrome)



Some Clones are not capable of a split cursor.

































                               3

                       ATTRIBUTE


The Attribute function enables you to change the attributes on the screen 
without affecting the character(s) currently displayed.  The attribute 
characters (or switches) are the same as those used by dBASE with the 
exception of 'U' and 'I', which are not available options.  When you supply 
the attributes, you will specify either the foreground attribute, the 
background attribute, or both.  If no foreground attribute is specified, 
white will be used, and if no background attribute is specified, black 
(none) will be used.  A backslash (/) character precedes the background 
attributes.

The following attribute switches are valid

     R - Red                  G - Green           B - Blue
     N - Black (none)         W - White
     + - High Intensity       * - Blinking   
   
     (+ and * are valid only as foreground switches)

Each of these attribute switches can be combined to produce other colors 
and attribute combinations.

The 1st parameter is "A".  The next 4 parameters define the region that you 
want to change the attributes of.  The region is defined by the top row, 
left column, bottom row, and the right column.  The last parameter (the 
6th) identifies what attributes to use.

      
EXAMPLES

Set the region 0, 0, 10, 30 to cyan on a red background:

     CALL DBEXT WITH "A,0,0,10,30,BG/R"

Set the entire screen to black on white (reverse video):

     CALL DBEXT WITH "A,0,0,24,79,N/W"

Set row zero to red on black:

     CALL DBEXT WITH "A,0,0,0,79,R"

Set the top five rows to blinking green on white:

     CALL DBEXT WITH "A,0,0,4,79,*G/W"













                               4

                            FILL


The Fill function enables you to fill a region on the screen with a 
particular character and an optional attribute.  If the attribute string is 
not supplied, Fill will write the character to the screen without affecting 
the attribute. 

The 1st parameter is "F".  The next parameter is the character that you 
want to fill the screen region with.  If your word processor does not allow 
you to type a character higher than 7EH, you can either prefix the decimal 
number of the ASCII character you want to use with a 'B' or you can insert 
the character in the variable or literal with the CHR() function.  The next 
4 parameters define the region of the screen that you want to fill.  The 
region is defined by the top row, left column, bottom row, and the right 
column.  The last parameter (the 7th) is optional.  It is an attribute 
string.  If supplied, the character you fill the screen with will be 
displayed using this attribute.  If it is not supplied, the attribute will 
not change.


EXAMPLES

Fill the region 0,0,10,79 with asterisks:

     CALL DBEXT WITH "F,*,0,0,10,79"

Fill the region 0,0,24,0 with the extended ASCII character 186 (the double 
vertical line character).  This command will draw a vertical line since the 
column coordinates are the same.

     CALL DBEXT WITH "F,B186,0,0,24,0"

Fill the region 0,0,12,79 with the space character using inverse video:

     CALL DBEXT WITH "F,B32,0,0,12,79,N/W"



Since DBEXT ignores leading blanks while parsing the parameter list, the 
Fill function will not allow you to fill a region with a space character 
unless you use the "B" (byte) operator as in the previous example or by 
using the CHR() function.
















                               5

                             BOX


The Box function enables you to draw a box on the screen.  This box can be 
drawn with several different borders.

The 1st parameter is "B".  The next parameter is optional; it identifies 
which border characters to use when drawing the box.  There are six types: 
"D" (double), "S" (single), "M" (mixed), "B" (block), "N" (none), and "U" 
(user defined).  The next parameter (and it's comma) is also optional.  If 
you don't want the interior of the box cleared, then supply the parameter 
"P".  The next 4 parameters define the region of the screen that you want 
to draw the box on.  The region is defined by the top row, left column, 
bottom row, and the right column.  The next two parameters are optional.  
The first is the attribute to use for the border and the second is the 
attribute to use for the interior.  If they are not supplied, the 
attributes currently used on the top left corner of the region will be 
used.


EXAMPLES

Draw a box on the region 0,0,24,79 using the double line characters. The 
foreground will be red and the background blue.

     CALL DBEXT WITH "B,D,0,0,24,79,R/B"

Erase the perimeter of the box drawn in the previous example:

     CALL DBEXT WITH "B,N,P,0,0,24,79,R/B"

Blank the region 0,10,10,50 using the attributes currently in use:

     CALL DBEXT WITH "B,N,0,10,10,50"



You may use the Box function to draw horizontal and vertical lines by using 
the same row or column coordinates.




















                               6

                          WINDOW


The Window function enables you to add window like capabilities to your 
programs.  There are five functions that this utility performs.  

The five functions perform one or more of the following procedures.
     1. Save a region of the screen into a dynamic memory buffer.
     2. Clear a region of the screen.
     3. Draw a box around a region.
     4. Re-draw the region of the screen that was previously saved.
     5. Free up the memory buffer space used to save a screen region.

There are 8 buffers that may be used to contain the screen regions that you 
save.  These buffers are allocated space dynamically from a 16,000 byte 
memory pool. As long as the combined byte count of the regions that you 
save is no greater that 16,000 you will be able to open 8 windows.  
Otherwise, the total size of the windows (regions) that you want to open at 
one time will determine the number of windows that you can open.  Since 
each character on the screen takes up 2 bytes (character and attribute), 
there is enough space to hold 3 full screen images, 6 half screen images, 
or 8 screen images if their combined byte count is no greater than 16,000 
bytes.  The buffers are identified by the numbers 1-8.  Once you open a 
buffer it is not released (the space used to hold the region is freed up) 
until one of the functions releases it or DBEXT is reloaded.  This is one 
of the reasons to load DBEXT only once.

The first parameter of this function is "W".  The next parameters are 
specific to the particular function requested.


OPEN WINDOW

This function will save the screen region in a buffer, clear the region on 
the screen, and draw a border around the region.

To invoke this function use the following command:

CALL DBEXT WITH "W,O(1-8),[(D,S,M,B,N,U),][X,]tr,lc,br,rc[,[battr][,iattr]]"

O              The parameter for opening a window.
(1-8)          Identifies which buffer to use for this window.
(D,S,M,B,N,U)  Optional.  If supplied, it identifies which border 
               characters to use for the border of the window.
X              This is the expand, or shadow, switch.  Use it if you 
               want the window to be drawn with a shadow on the left and 
               bottom of the border.  The bottom row coordinate must be 
               less than 24 and the left column coordinate must be 
               greater than 0.
tr             The top row (0-24) of the region.
lc             The left column (0-79) of the region.
br             The bottom row (0-24) of the region.
rc             The right column (0-79) of the region.
battr          Optional.  If supplied, it identifies what attributes to 
               use for the border of the window.
iattr          Optional.  If supplied, it identifies what attributes to 
               use for the interior of the window.


                               7

                          WINDOW


CLOSE WINDOW

This function will restore the screen image previously saved and free up 
the buffer space used for this window.

To invoke this function use the following command:

CALL DBEXT WITH "W,C(1-8)"

C              The parameter for closing a window.
(1-8)          Identifies which buffer (window) to close.



SAVE WINDOW

This function will save the screen region in a buffer.

To invoke this function use the following command:

CALL DBEXT WITH "W,S(1-8),tr,lc,br,rc"

S              The parameter for saving a window.
(1-8)          Identifies which buffer to use to save this region into.
tr             The top row (0-24) of the region.
lc             The left column (0-79) of the region.
br             The bottom row (0-24) of the region.
rc             The right column (0-79) of the region.



RE-DRAW WINDOW

This function will re-draw the saved screen region.

To invoke this function use the following command:

CALL DBEXT WITH "W,R(1-8)"

R              The parameter for re-drawing a window.
(1-8)          Identifies which buffer to re-draw.


DELETE WINDOW

This function will free up the space used to save a screen region.

To invoke this function use the following command:

CALL DBEXT WITH "W,D(1-8)"

D              The parameter for deleting a view.
(1-8)          Identifies which buffer to delete.
EXAMPLES


                               8

                          WINDOW



Open a window using buffer 1.  The window will occupy the region 0,0,9,79.  
The border will be bright white on green and will be drawn using the 
default border characters.  The interior will be white on blue.

     CALL DBEXT WITH "W,O1,0,0,9,79,+W/G,W/B"

Open a window using buffer 8.  The window will occupy the region 5,5,10,10.  
The border will be blinking red on blue and will be drawn using the user 
defined border characters.  The interior will be white on blue.

     CALL DBEXT WITH "W,O8,U,5,5,10,10,*R/B,W/B"

Open a window using buffer 2.  The window will occupy the region 0,0,24,79.  
The border will be drawn using the default border characters and 
attributes, and the interior will use the default interior attributes.

     CALL DBEXT WITH "W,O2,0,0,24,79"

Open a window using buffer 2.  The window will occupy the region 0,1,23,79.  
The border will be drawn using the default border characters and 
attributes, and the interior will use the default interior attributes.  
This window will also be drawn with a shadow down column 0 and on row 24.

     CALL DBEXT WITH "W,O2,X,0,1,23,79"

Close the window associated with buffer 1:

     CALL DBEXT WITH "W,C1"

Save an image of the entire screen into buffer 8:

     CALL DBEXT WITH "W,S8,0,0,24,79"

Re-draw the screen image that was saved into buffer 8:

     CALL DBEXT WITH "W,R8"

Delete (release) the space in buffer 8:

     CALL DBEXT WITH "W,D8"

Perform the same functions as the 2 preceding examples:

     CALL DBEXT WITH "W,C8"











                               9

                          SCROLL


The Scroll function is used to scroll a region of the screen up or down one 
or more lines.  This function is especially useful for applications when 
you want to display multiple records on the screen.  When the screen is 
filled and you want to display another record just scroll the screen up or 
down and display the new record.

The first parameter is "S".  The next parameter is either a "U" to scroll 
up, or a "D" to scroll down.  The next four parameters define the region to 
scroll.  The next parameter, and its' comma, are optional.  It is a number 
from 1-24 (dependent on the region) which is the number of lines to scroll.  
If this parameter is not given, the default is 1.  The last parameter is 
also optional.  It is an attribute string which defines what attributes to 
use on the blank line(s) introduced when the region is scrolled.  If not 
supplied, the attributes currently use on the top row (if scrolling down) 
or the attributes currently use on the bottom row (if scrolling up) are 
used.


EXAMPLES

Scroll the region 10,10,20,30 up 2 lines.  The 2 lines that become blank 
will be set to the attributes bright blue on red.  

     CALL DBEXT WITH "S,U,10,10,20,30,2,+B/R"

Scroll the screen down one row.  The blank line will be drawn using the 
current attribute being used at coordinate 0,0.

     CALL DBEXT WITH "S,D,0,0,24,79"

Scroll the region 0,0,5,50 up one line.  The attributes for the new line 
will be red on a black background.

     CALL DBEXT WITH "S,U,0,0,5,50,R"






















                               10

                         PRINTER


The Printer function gives you complete control over your printer.  It will 
allow you to check the status of the printer, initialize the printer, send 
NULLs to the printer, and more.

The first parameter is a "P".  The next parameters are specific to the 
feature that you require.  They are explained below.


SELECT LPT PORT

This feature allows you to select which LPT port you wish to work with.  As 
a default, all of the Printer features act on LPT1.  You may select LPT1-
LPT3.  Once selected, it will stay in affect until a different port is 
selected or DBEXT is reLOADed.  This selection will not affect which port 
dBASE works with.

The calling sequence is:

     CALL DBEXT WITH "L,n"            && Where n is 1, 2, or 3.


GET PRINTER STATUS

This feature returns the status of the printer.  It will return the status 
in the first byte of the memory variable passed.  This value is dependent 
on the particular printer in use, and, with certain clones, on the computer 
itself.  If your programs are to run on a true IBM or compatible, then the 
values returned will be the same as outlined in the "IBM Technical Manual"; 
otherwise, before incorporating this feature in your programs, check the 
status of the printer when the printer is in various states - off-line, 
on-line, out of paper, etc. - and make note of the return values.  After 
determining these return values, you can then code them in your programs.

The calling sequence is

     mem_var    = "P,S"
     CALL DBEXT WITH mem_var
     lpt_status = ASC(mem_var)

If the printer is ready, a value of 144 should be returned.
















                               11

                         PRINTER


INITIALIZE PRINTER

This feature will initialize the printer.  It will return after the printer 
indicates that it is ready (on-line) or, if the printer is not ready, will 
return after a specified number of seconds.  With some printers, namely 
EPSON compatibles, initializing  an off-line printer will turn it on-line.  
When this function returns, the printer status will be returned in the 
first byte of the memory variable passed.  You may also tell this function 
to initialize the printer only if it is not on-line.

The calling sequence is:

     mem_var    = "P,I[[,n][,C]]"      && Where n is a number from 0-
180.
     CALL DBEXT WITH mem_var
     lpt_status = ASC(mem_var)


Example parameter strings

This parameter string will initialize the printer.  If the printer returns 
a status of 144, it will return; otherwise, it will continue polling the 
port until it becomes ready or 5 seconds (the default) has elapsed.

     mem_var = "P,I"

This string will initialize the printer.  If the printer returns a status 
of 144, it will return; otherwise, it will poll the port until it becomes 
ready or 30 seconds has elapsed.

     mem_var = "P,I,30"

This string will, if the printer is on-line, return; otherwise, it will 
initialize the printer and return if it becomes on-line or 10 seconds 
passes.

     mem_var = "P,I,10,C"

This string will, if the printer is on-line, return; otherwise, it will 
initialize the printer and return if it becomes on-line or 5 seconds 
passes.

     mem_var = "P,I,C"













                               12

                         PRINTER


WRITE STRING

This feature will send a string of characters to the printer.

EXAMPLES

Send the string "ABC" to the printer:

     CALL DBEXT WITH "P,W,ABC"

Send the string "  xx " to the printer:

     CALL DBEXT WITH "P,W  xx "


SEND BYTE

This is by far the most useful feature.  It will allow you to send any byte 
(decimal 0-255) to the printer.  Each byte is delimited by a comma.  In 
addition, there are certain operators, or commands, that may be included in 
the byte list.

The parameter list consists of the following parameters:

     "P,B,n1,n2,n3,nN"

The parameter list always begins with "P,B,".  "n1...nN" are the byte 
values and one or more of the following commands (which were added to 
reduce the lenght of the parameter list):

"Rn1,n2"   This is the Replicate command.  "n1" is the byte (0-255) that 
          you want to replicate and "n2" is the number (1-65535)  of 
          times to send this byte to the printer.

"Nn1"     This is the NULL command.  It is used to send NULL characters 
          (ASCII 0) to the printer.  "n1" is the number of Nulls to send 
          to the printer.  This number can be between 1 and 65535.

"Sn1"     This is the Space command.  It is used to send Space characters 
          (ASCII 32) to the printer.  "n1" is the number of Spaces to 
          send to the printer.  This number can be between 1 and 65535.

"Gn1"     This is the Goto command.  It is used to move the print head to 
          a certain column.  "n1" is the column that you want to move the 
          print head to.  This number can be between 0 and 255.  This 
          command works by sending a carriage return (ASCII 13) to the 
          printer.  It then sends the space character to the printer 
          until it has reached the desired column.








                               13

                         PRINTER


****  Printer Demo Program.
****  The status of the printer is checked.  If the printer status
****  is other than READY a message will be displayed on the screen
****  until the printer becomes READY.  Once the printer is ready,
****  this program will print the words "Male    Female" in bold,
****  "(check appropriate box)" in condensed print (17 cpi), and
****  draw empty boxes on the right of "Male" and "Female".

SET TALK OFF
LOAD DBEXT
**** EPSON PRINTER CODES
p_12cpi    = "27,77,"
p_17cpi    = "27,80,15,"
p_bold1    = "27,69,"
p_bold0    = "27,70,"
g_box      = "27,75,7,0,255,R129,5,255,"

p_status   = "P,I,C"
CALL DBEXT WITH p_status
DO WHILE ASC(p_status) <> 144
   @  0, 0 SAY "ERROR: PRINTER NOT READY"
   p_status   = "P,I,C"
   CALL DBEXT WITH p_status
   @  0, 0
ENDDO

SET DEVICE TO PRINT
SET MARGIN TO 0
CALL DBEXT WITH "P,B,"+p_12cpi+p_bold1
@  1, 0 SAY "Male    Female    "
CALL DBEXT WITH "P,B,"+p_bold0+p_17cpi
@  1, PCOL() SAY "(check appropriate box)"
CALL DBEXT WITH "P,B,"+p_12cpi+"G5,"+g_box+"G15,"+g_box
EJECT
SET DEVICE TO SCREEN
SET TALK ON
RETURN
**** end of Printer Demo Program


















                               14

                             CUT


The Cut function is used to return the characters that are displayed on the 
screen at a certain coordinate.  The first parameter is "C".  The second is 
the row number; the third, the left column; and the forth, the right 
column.    Make sure the memory variable you pass is long enough to hold 
the characters.  If it is not, only the characters that will fit in the 
variable will be returned.  This function can be used in a point and shoot 
procedure.


EXAMPLE

This example will return the characters that are displayed on the screen at 
row 10, within the columns 0 through 9.

     mem_var    = "C,10,0,9  "
     CALL DBEXT WITH mem_var








































                               15

                        DEFAULTS


There are several defaults that may be set with the Default function.  The 
first parameter is "D" and the second is either "W" if setting a Window 
default or a "B" if setting a Box default.


WINDOW DEFAULTS

To define the user defined border characters for windows - where "tlc" is 
the character to use for the top left corner, "tl" for the top line, "trc" 
the top right corner, "vl" the vertical lines, "blc" the bottom left 
corner, "bl" the bottom line, and "brc" the bottom right corner - use the 
following command:

     CALL DBEXT WITH "D,W,U,tlc,tl,trc,vl,blc,bl,brc"

Use this command to set the default border characters used for windows:

     CALL DBEXT WITH "D,W,B,(D,S,M,B,N,U)"

Use this command to set the default attributes used when drawing the border 
and interior of a window:

     CALL DBEXT WITH "D,W,A,border_attr,interior_attr,shadow_attr"


BOX DEFAULTS

To define the user defined border characters for boxes - where "tlc" is the 
character to use for the top left corner, "tl" for the top line, "trc" the 
top right corner, "vl" the vertical lines, "blc" the bottom left corner, 
"bl" the bottom line, and "brc" the bottom right corner - use the following 
command:

     CALL DBEXT WITH "D,B,U,tlc,tl,trc,vl,blc,bl,brc"

Use this command to set the default border characters used for boxes:

     CALL DBEXT WITH "D,B,B,(D,S,M,B,N,U)"


















                               16

                    COMMAND CARD


          


CURSOR
  C,D               Disable cursor.
  C,E               Enable cursor.
  C,T,n1,n2         Type.  n1=starting scan line, n2=ending scan line.

ATTRIBUTE
  A,tr,lc,br,rc,attr

FILL
  F,{Bbyte,char},tr,lc,br,rc[,attr]

BOX
  B,[(D,S,M,B,N,U),][P,]tr,lc,br,rc[,[border_attr][,interior_attr]]

SCROLL
  S,(U,D),tr,lc,br,rc[,[lines]][,attr]

PRINTER
  P,L,port_number
  P,S
  P,I[,seconds][,C]
  P,W[,]string
  P,B,byte,byte,byte...

WINDOW
  W,O(1-8),[(D,S,M,B,N,U),][X,]tr,lc,br,rc[,[border_attr][,interior_attr]]
  W,C(1-8)
  W,S(1-8),tr,lc,br,rc
  W,R(1-8)
  W,D(1-8)

CUT
  C,row,left_col,right_col,

DEFAULTS
  D,W,U,tlc,tl,trc,vl,blc,bl,brc
  D,W,B,(D,S,M,B,N,U)
  D,W,A,border_attr,interior_attr,shadow_attr
  D,B,U,tlc,tl,trc,vl,blc,bl,brc
  D,B,B,(D,S,M,B,N,U)













                               17

