Dec 052017
 
PBEZ Library for Power Basic 3.0c.

Full Description of File


PBEZ! Library, v2.0a, for PowerBASIC 3.0c.
Pure assembly: Manipulate strings, memory
and variables, farpointers, and XMS-memory.
Country dependent time/date formats and CASE
conversions. Ext.keyb-control, Mouse event
handler, drives&dirs, direct file and
textscreen access, extensive online help.


File PBEZ!.ZIP from The Programmer’s Corner in
Category Recently Uploaded Files
PBEZ Library for Power Basic 3.0c.
File Name File Size Zip Size Zip Type
PBEZ!.DEC 92595 7638 deflated
FILE_ID.DIZ 304 229 deflated
PBEZ!.DOC 100380 25781 deflated
PBEZ!.FRM 6189 1859 deflated
PBEZ!.INC 92624 7662 deflated
PBEZ!.PBH 314241 103859 deflated
PBEZ!.PBL 83668 33449 deflated

Download File PBEZ!.ZIP Here

Contents of the PBEZ!.DOC file




The PowerBASIC EZ! Library

Version 2.0a

PBEZ! Copyright (c) 1994 Pieter Dirk van Dijk


PREFACE

The PowerBASIC EZ! library contains a collection of hundreds of
ASSEMBLY routines for use with PowerBASIC 3.0c.

The routines aim at lighting the burden of the programmer, and
are written by an experienced PowerBASIC and Assembly
programmer. The object of this library is to add speed and
functionality to the proces of developing programs by supplying
the programmer with a set of frequently used functions and
commands.

An extremely important part of any library is the documentation.
The usefulness and userfriendlyness of a library largely depends
on the documentation that comes with it.
That's why particular attention is paid to the online helpfile.
Besides the description of each and every routine, the helpfile
PBEZ!.PBH contains indexes (categorized and alphabetical)
and is thoroughly cross-refenced.
Copy this file to your PowerBASIC directory

Included are also files that contain function and sub
declarations of all routines.

The PBEZ! library and the files that come with it, including
this document, are protected by copyright, but may be
distributed, provided that:
All files are distributed together in unmodified form,
and no files are added or removed.

The routines in the PBEZ! library have all been tested.
However, I must point out to you that the use of this library is
at your own risk. If you do run across a problem then please let
me know.

PBEZ! is published as Shareware. This means that you can try out
the library for a period of 30 days. If you continue to use this
library, or any program written with the use of this library,
you must register. The registration fee is (the equivalent of)
40 Dutch guilders or US$ 25. See Chapter Registration for more.


The author makes no warranties of any kind, express or
implied, including without limitation, any warranties of
merchantability. Furthermore, the author shall not be
liable for any damage to data or property which may be
directly or indirectly caused by the use of PBEZ!. In no
event will the author be liable for any damages,
including lost profits, or for any claim by any other
party.



PBEZ! version 2.0a page 2


CONTENTS


Preface .................................................... 1

Table of Contents .......................................... 2

Introduction ............................................... 3

Installation and use ....................................... 5

Pointers and Memory (incl.XMS) ............................. 8

Strings and Characters ..................................... 9

Drives and Directories .................................... 11

Files, Read and Write ..................................... 12

Country Codes and Money ................................... 13

Dates, Times and Conversions .............................. 15

Keyboard Control .......................................... 17

Mouse and Textevents ...................................... 19

Textscreen, Printing and Colors ........................... 22

Miscellany ................................................ 24

Alphabetical list ......................................... 26

Registration .............................................. 33



For comments, suggestions, etc. the author can be reached by
mail at the following address:

P.D. van Dijk
Tulpstraat 6
8255BZ Swifterbant
HOLLAND

You can reach me on Internet with: [email protected]
or from inside holland: [email protected]


PBEZ! version 2.0a page 3


INTRODUCTION

The PBEZ! library aims at providing PowerBASIC programmers with
a large number of frequently used functions and commands. Making
life easier, that's what this library is about.

The library contains a large number of string functions and
commands.
Many string routines can also operate on flexstrings.
Functions and commands that operate on flexstrings have the
letters "FLX" appended to the routinename, or the routinename
ends with "FLX" instead of "STR". These routines are not
listed in either this document or in the alphabetical index of
the PBEZ! helpfile. They are however specified in the
topic-specific pages of the helpfile.

Through the use of aliases and pointers nearly all routines that
operate on memory can also operate on different types of integer
arrays.
About routines that operate on numerical variables and arrays
(usually the different types of integers):
To distinguish between the different types of numeric
variables and arrays, the last letter(s) of the function or
command usually indicates the type of variable or array the
routine acts on. (eg. B for BYTE, I for INTEGER, W for WORD, L
for LONG, D for DWORD) The names of these routines are listed
in this documentation and in the PBEZ! helpfile with one or
more periods (...) at the end.

A number of routines produce results depending on the setting of
the country-code, thus making PowerBASIC a truly international
programming language.
This applies specifically to the DATE and TIME routines, and
also to the CASE-conversion routines and the routines that
deal with currency (money).

PBEZ! also contains a large number of textscreen routines.
There are fast, clever printing routines, ansiprint, lineprint
and blockprint routines. And still lots more. You can recolor
foreground and background, or both, of textscreen areas, fill
them, clear them, draw textboxes with pre-defined or
user-defined borders, scroll a textscreen area in any
direction. Saving and restoring textscreen (areas) is a
breeze.

The library also offers better keyboard control, direct (DOS)
file reading and writing, extended directory info and
management, etc. etc.

An extended set of mouse routines provides a programmer-friendly
way to implement the mouse in your program. An event checking
mechanism makes it simple and easy to setup and check for
"mouse-events".



PBEZ! version 2.0a page 4


Experience has told me that some programmers like to
differentiate between SUBs and FUNCTIONs by letting function
names start with an "f". To facilitate those programmers, nearly
all functions in this library have synonyms: with and without a
precending "f". You can for instance use both fGETCOUNTRY and
GETCOUNTRY to obtain the current Country Code.

PBEZ! comes with a large (300+ Kb) PowerBASIC helpfile. The help
contains all the information the programmer may need.
In fact, it contains more information than this file.

The help includes:
- Purpose, Syntax and Remarks for each function/command;
- extensive "see also" cross-referencing;
- a main index and category-indexes with brief descriptions;
and an alphabetical index;
- importable FUNCTION and SUB declarations for all routines;
- lookup help for all PBEZ! functions and commands.
The lookup will respond regardless of the type identifier
of the function, e.g. UCASED$, UCASED, ASCMID% and ASCMID
will all work with .
In the registered version the lookup will also respond to
function names with a preceeding "f", such as fUCASED$,
fUCASED, fASCMID% and fASCMID.

The library includes files that contain declarations of all subs
and functions, with and without the above mentioned preceding
"f".


PBEZ! version 2.0a page 5


INSTALLATION AND USE

This library (unregistered) consists of the following files:
PBEZ!.DOC this file
PBEZ!.PBH PowerBASIC helpfile
PBEZ!.INC Routine declarations file (for compile EXE)
PBEZ!.DEC Routine declarations file (for compile UNIT)
PBEZ!.PBL The actual library-file
PBEZ!.FRM Registration form

To make things work you move or copy the following files to the
following directories:
PBEZ!.DOC anywhere you want
PBEZ!.PBH the PowerBASIC Directory (where you have PB.EXE)
PBEZ!.INC one of your Source Directories
PBEZ!.DEC one of your Source Directories
PBEZ!.PBL one of your Link Directories
PBEZ!.FRM anywhere you want

See page 76 and 77 of the PowerBASIC Programmer's Guide for
more on these directories.

Once you have correctly installed the files you can start
writing your programs. The only thing you need to do is to
include the following statement (at the top) in your program:

$INCLUDE "PBEZ!.INC"

PBEZ!.INC contains all the necessary declarations to compile
your program to an EXE file, including the statement:
$LINK "PBEZ!.PBL"

If you wish to use the PBEZ! library to write your own
PowerBASIC UNITs (PBUs) then you can use:

$INCLUDE "PBEZ!.DEC"

This will however increase the size of your PBU file(s) since
declarations for all PBEZ! library functions and commands will
be included in the resulting PBU-file. So once you've got your
unit working properly, take out the above $INCLUDE statement and
manually insert the proper declarations.
Remember, all declarations can be imported from the PowerBASIC
online helpscreens. So the easiest way is to move the cursor to
a PBEZ! function or command in your Unit source code, hit
, pagedown until the declaration appears on the help
screen and press to import the declarations. Then move the
cursor to the beginning of your source code and press to
paste the declarations into your unit file. The lines you now
have imported may still have unneeded declarations. You can
remove those lines with .

Since all routines are written in Assembly, they are extremely
fast and yet very compact. Also, they can never generate a
PowerBASIC error. Instead, many of the routines that could
generate an error simply return an error code, or for instance
TRUE if succesful, and FALSE if an error occurred.
This makes the library powerful and flexible.


PBEZ! version 2.0a page 6



On the other hand, since some routines directly address memory
and string space, errors of a more serious nature may occur as a
result of careless programming. You may accidently overwrite
memory locations that will cause the system to crash.
That's why you have to pay extra attention to routines that
address memory.

Particularly "dangerous" are routines that POKE, QCOPY, QFILL
and READBLK values into memory addressed by farpointers or a
specified array-element. Even if you have $ERROR BOUNDS ON and
use addressing by array-element, a routine may corrupt memory if
you specify too large a blok of data. But since these routines
provide a powerful tool to move around data, they are worth the
extra attention.

Another source for errors or misbehaviour are subs and functions
that create (and return) a new string or use string space as a
(sometimes temporary) workarea. Those routines may incorrectly
return a nul-string when PowerBASIC's has ran out of string
space, or when the programmer has chosen too small a string
segment size (with the compiler command $STRING ##) to hold the
data. An illustration:

$STRING 4 Max string length = 4078 chars
...
WIDTH 80,50 screensize = 2 bytes * 80 cols * 50 rows
... = 8000 bytes
GETTEXTSCRN Scrn$ Scrn$ = "" because screen is too big


The above example is clearly a programming error and can be
avoided by choosing a larger string segment size.
But sometimes a program just runs out of memory space. And that
can be awkward in the middle of the program. Error trapping
won't help. To avoid such situations the programmer should try
to estimate the maximum required string space for a particular
program, and place these lines at the start of the program (For
example):

%MEMREQUIRED = xxxxx rem in Kilobytes
IF %MEMREQUIRED * 1024 < FRE (-1) THEN
PRINT "Not enough memory free to run this program."
END Errorlevel%
END IF


By the way, the above precaution is recommended even if you
don't use the string routines of this library. An "Out of string
space" or "Out of memory" can thus usually be avoided.

You will find more information on the memory requirements of
certain routines in the online help.



PBEZ! version 2.0a page 7


And finally, very few routines require DOS-version 3.3 or
higher. When using those routines, you'd best check for the
DOS-version at the start of your program with:

IF DOSVERSION < 330 THEN
PRINT "This program requires DOS version 3.3 or higher."
END
END IF




PBEZ! version 2.0a page 8


POINTERS AND MEMORY (incl. XMS)

PBEZ! comes with a large number of routines to manage and
manipulate both DOS- and XMS-memory. Data can be stored in
different types of integer arrays, in strings or simply
somewhere in memory. This library contains all the routines to
handle the different types of data-storage.

You can:
- PEEK... and POKE... without using DEF SEG;
- move data around with QCOPY;
- fill an area of memory or an array with QFILL,;
- access extended memory by means of smart XMS routines;
- obtain addresses of variables as a 32-bit farpointer;
- obtain 20-bit addresses of variables;
- increase and decrease pointers without worrying about
"segment overflow";
- check for XMS version and availability;
- open, resize and close XMS memory blocks;
- write and read variables, arrays, blocks of data addressed
by pointers, and even strings to and from XMS memory.

List of functions and commands:
FPTR... Returns a far pointer to its argument

FADR... Returns a 20-bit address
INCRPTR Increments a farpointer, preventing "segment overflow"
INCRHUGEPTR Increments a farpointer, across segments
DECRPTR Decrements a farpointer, preventing "segment overflow"
DECRHUGEPTR Decrements a farpointer, across segments
PEEKSEG... PEEK without DEF SEG statement
POKESEG... POKE without DEF SEG statement
PEEKFAR... PEEK using a farpointer
POKEFAR... POKE using a farpointer
QCOPY... Copies data from one array/mem-location to another
QCOPYSTR... Copies data from a string to array/mem-location
QCOPYBSTR$... Creates a string from data in an array or mem-location
QFILL... Fills an array or memory with a predefined value
XMSEXISTS Returns TRUE if XMS exists, else FALSE
XMSVERSION Returns version of XMS driver if installed, else zero
XMSFREEMEM Returns total free XMS-memory in Kbytes
XMSFREEBLK Returns the size of the largest free XMS-block in Kbytes
XMSOPEN Allocates an XMS-memory block, TRUE if success
XMSRESIZE Resizes an open XMS-memory block, TRUE if success
XMSCLOSE Closes an XMS-memory block, TRUE if success
XMSERR Returns an XMS-errorcode for the last XMS-operation
XMSBLKWRITE... Writes a block of data to XMS-memory, TRUE if success
XMSBLKREAD... Reads a block of data from XMS-memory, TRUE if success
XMSWRITE... Writes a numeric variable to XMS-memory, TRUE if success
XMSREAD... Reads a numeric variable from XMS-memory, TRUE if success
XMSWRITESTR Writes a string variable to XMS-memory, TRUE if success
XMSREADSTR Reads a string variable from XMS-memory, TRUE if success



PBEZ! version 2.0a page 9


STRINGS AND CHARACTERS

PBEZ! provides you with a range of functions and commands with
which you can manipulate strings and characters. Most of these
routines can be found in this chapter, but some (like the CASE
conversion routines) can be found elsewhere.

There are routines to detab strings, reverse them, delete and
insert characters into strings. Routines to manage variable
length records and fields (the PIECE family), to search strings
for one or two characters, forwards or backwards (the SCAN
family), etc.

Some routines are fairly simple and you could easily write them
in PowerBASIC. But to increase speed and readability, and to
optimize for size you may prefer to use these routines.
For instance:

X% = ASCMID (Txt%,MidPos%) is much faster than:
X% = ASCII (MID$ (Txt%,MidPos%,1))

Or:

INSERTSTR Txt$, MidPos%, X$ instead of:
Txt$ = LEFT$(Txt$,MidPos%-1)+X$+MID$(Txt$,MidPos%)


Many string routines can also operate on flexstrings. Functions
and commands that operate on flexstrings have the letters "FLX"
appended to the routinename, or the routinename ends with "FLX"
instead of "STR". These routines are not listed in either this
document or in the alphabetical index of the PBEZ! helpfile.
They are however specified in the topic-specific pages of the
helpfile.

List of functions and commands:
MIDSTR$ returns a portion of a string (alternative MID$)
DETAB$ returns a copy of a string with embedded tabs expanded
REVERSED$ returns a reversed copy of a string
REVERSE reverses a string
GETPIECE$ returns any piece of a string using separators
REMOVEPIECE$ returns and removes a piece of a string using separators
DELETEPIECE removes a piece of a string using separators
INSERTPIECE inserts a piece into a string using separators
REPLACEPIECE replaces a piece of a string with a new value
PIECECOUNT returns the number of pieces in a string
LASTPIECE$ returns the last piece of a string using separators
PIECEPOS returns the INSTR of a given piece
TALLYSTR returns the number of occurrences of a specified char
TALLYMID as TALLYSTR but acts on a portion of a string
CHR2MID replaces a character at a position in a string
INT2MID or WRD2MID replaces 2 characters in a string
LNG2MID or DWD2MID replaces 4 characters in a string
INSERTCHR inserts a character into a string
INSERTWRD or INSERTINT inserts 2 characters into a string
INSERTSTR inserts a string into a string
DELETECHARS deletes one or more characters from a string
ASCMID returns the ASCII value of a string-character


PBEZ! version 2.0a page 10


ASCLAST returns the ASCII value of the last string-character
BINA$... returns correctly 0-padded binary string
HEXA$... returns correctly 0-padded hex string
BINVAL returns value of binary string
HEXVAL returns value of hex string
DECVAL returns value of decimal string
SCANB returns the INSTR of one char (faster than INSTR)
SCANBMID as SCANB but acts on a portion of a string
RSCANB as SCANB but scans from right to left
RSCANBMID as RSCANB but acts on a portion of a string
SCANW returns the INSTR of two chars (faster than INSTR)
SCANWMID as SCANW but acts on a portion of a string
RSCANW as SCANW but scans from right to left
RSCANWMID as RSCANW but acts on a portion of a string
CRLFINSTR returns the INSTR of a CR/LF
CHARINSTR returns the INSTR of the first non-whitespace char
HANDLESTR returns the handle of a string

Be aware that on rare occasions errors may occur, for instance
when you run out of string space, or when the maximum string
size (as set with PowerBASIC's $STRING statement) is exceeded.
These errors will not generate a PowerBASIC runtime error, as
the routines are written in assembly. Instead nulstrings are
returned. Particular attention should be paid to programs in
which you use SETMEM to release memory (in POPUP TSRs for
instance).



PBEZ! version 2.0a page 11


DRIVES AND DIRECTORIES

The routines in this section provide programmers with a powerful
tool to manage disks and directories, and to obtain information
about directories and files. Again, the routines will never
generate a runtime error.

List of functions and commands:
PROGRAMPATH$ returns the current program's drive and path
PROGRAMNAME$ returns the current program's drive:\path\progname.exe
CURRENTDIR$ returns the current directory of a drive, NULL if error
DRIVEREADY checks if the diskdrive is ready
ISDRIVE checks if the drive exists, returns TRUE/FALSE
DISKSIZE returns the disksize in bytes
DISKFREE returns the number bytes free on the disk
CHGDRIVE changes the default drive, returns TRUE if success
CHGDIR changes directory, returns TRUE if success
MAKEDIR creates a directory, returns TRUE if success
REMDIR removes a directory, returns TRUE if success
KILLFILE deletes a file, returns TRUE if success
FILEMATCH TRUE if filename matches a pattern with * and/or ?
DIRFIRSTFILE returns TRUE/FALSE if matching file was found
DIRNEXTFILE returns TRUE/FALSE if further files were found
DIRFILENAME$ returns the name of the last file found
DIRFILESIZE returns the size of the last file found
DIRFILEDATE returns the date of the last file found
DIRFILETIME returns the time of the last file found
DIRFILEATTR returns the attribute of the last file found
FILEATTRIB$ converts an attribute-byte to a 4 character string
GETDIR$ searches and returns matching filename (as PB's DIR$)
PADFILENAME$ returns a padded file name eg: "FILE .EXE "
DTAPTR returns a farpointer to the current DTA area
GETDTA$ returns the first 21 bytes of the current DTA area
PUTDTA sets (restores) the first 21 bytes of the current DTA
GETFIRSTDIR returns TRUE/FALSE if matching subdir was found
GETNEXTDIR returns TRUE/FALSE if further subdirs were found
SPLITFILESPEC splits full filespec into path and filename
STRIPPATH$ returns filename by stripping the path from filespec
STRIPFILE$ returns path by stripping the filename from filespec
SPLITFILENAME splits filename into name and extension
STRIPEXT$ returns name of file without extension
STRIPNAME$ returns extension of filename

Note: Directory specifications are always returned with a
trailing backslash ("\").
The trailing backslash is ignored by functions and
commands that take a directory path as argument (except by
CHGDIR when indicating the rootdirectory).



PBEZ! version 2.0a page 12


FILES, READ AND WRITE

PBEZ! includes a small number of routines to manipulate files,
and allows the programmer to directly read and write numeric
variables and arrays from/to open files.

List of functions and commands:
SEEKPOS returns the current filepointer location
SEEKBEG and SEEKEND: moves filepointer to start or end of file
SEEKABS and SEEKREL: moves filepointer
BLKREAD... reads a number of bytes or array elements from a file
BLKWRITE... writes a number of bytes or array elements to a file
READ... reads numeric variables directly from a file
WRITE... writes numeric variables directly to a file
GETATTRIB returns a file's attribute, 255 if error
SETATTRIB sets a file's attribute, returns TRUE if success
GETFILEDATE returns a file's date & time as a long integer
SETFILEDATE sets a file's date & time
DOSERR errorcode of the last DOS-operation
DISKERR errorcode of the last direct file-access

Note: For the read and write routines you need a DOS filehandle
which be obtained with:

Handle% = FILEATTR (PbFileNum%, 2)




PBEZ! version 2.0a page 13


COUNTRY CODES AND MONEY

The routines in this section make PowerBASIC a truly
international programming language. Once you have issued the
command
SETCOUNTRY 0

everything is ready for Country dependent input and output.
Dates and Times (see next sections) comply with the current
Country's format. UCASEing and LCASEing strings with foreign
characters is done correctly for any of the countries recognized
by DOS. COLLATESORT$ enables you to sort string arrays case-
independent according to National (DOS) conventions.
Expressing Money with USING is a breeze.

Besides automating the process for existing (DOS) Country Codes,
you can also define Date- and Time-formats, UCASE- and LCASE-
tables, Currency formats and symbols to suit your needs.
Greece for instance does not have it's own DOS Country Code. But
if you know the Greek ASCII-set, the Greek Time and Date
formats, and the Greek currency format and symbol, you can make
your program work the Greek way!
For more on Times and Dates, see next chapter.

List of functions and commands:
GETCOUNTRY system's current Country Code
SETCOUNTRY sets the Country Code, initializes internal variables
DATETYPE currently active date format (0,1 or 2)
DATESEP ascii value of the char used to separate Y,M and D
SETDATETYPE sets date-type and date-separator
TIMETYPE currently active time format (0 or 1)
TIMESEP ascii val of the char used to separate H,M and S
SETTIMETYPE sets time-type and time-separator
GETCURRENCY$ country's currency symbol as a string
SETCURRENCY sets the currency symbol (used with GETMONEYMASK$)
GETMONEYMASK$ formatted mask to be used with PRINT USING or USING$
CURRENCYPOS position of the currency symbol in currency expr.
CURDECIMALS number of decimals used in currency expressions
THOUSANDSEP ascii value of the thousands separator
DECIMALSEP ascii value of the decimal separator
THOUDECSEP$ string with thousands & decimal separator
LISTSEPAR ascii value of the char used as datalist separator
ISNLSFUNC returns TRUE if NLSFUNC is installed
UCASECHAR converts byte to uppercase (country dependent)
UCASED$ country dependent replacement for PB's UCASE$
UCASEMID$ as UCASED$, but returns ucased part of string
TOUPPER converts string to uppercase (country dependent)
TOUPPERMID as TOUPPER, but acts on part of string
LCASECHAR converts byte to lowercase (country dependent)
LCASED$ country dependent replacement for PB's LCASE$
LCASEMID$ as UCASED$, but returns lcased part of string
TOLOWER converts string to lowercase (country dependent)
TOLOWERMID as TOUPPER, but acts on part of string
COLLATESORT$ a 256 byte string to be used with ARRAY SORT
SETUCASEROUT sets a farpointer to the routine used by UCASECHAR
SETUPPERCASE sets an 128 byte internal table for UCASE conversions
SETLOWERCASE sets an 128 byte internal table for LCASE conversions



PBEZ! version 2.0a page 14


Note that the routines still work without the SETCOUNTRY
statement. The internal (default) tables and variables are set
to USA (12 hour) format and style.
If you want to setup your program to work with another Country
Code then the current default (as returned by GETCOUNTRY), you
need to have NLSFUNC installed. Your program can check this with
ISNLSFUNC.



PBEZ! version 2.0a page 15


DATES, TIMES AND CONVERSIONS

Very often programs need to deal with dates and times.
Dates can be expressed:
1) as a string;
2) in 3 integers holding year, month and day;
3) as a word holding the number of days since a certain date;
4) as a word with bit-specific fields for years since 1980,
month and day (DOS convention).

And times can be expressed:
1) as a string;
2) in 3 bytes holding Hour, Minutes and Seconds;
3) as a long integer holding the number of seconds since
midnight;
4) as a word with bit-specific fields for hours, minutes and
seconds divided by 2 (DOS convention).

PBEZ! provides you with all the routines needed to convert one
date- or time-expression into another. Furthermore, the date-
and time-strings are country dependent, in other words, once you
have issued the command

SETCOUNTRY 0

the routines "know" how to handle the input-strings, and will
correctly format the output-strings.

In case you are not aware of this, DOS recognizes three
date-formats:
1) MM-DD-YYYY (USA style)
2) DD-MM-YYYY (European style)
3) YYYY-MM-DD (Japanese style)
The Month-Day-Year separator varies from country to country.

And there are two time formats:
1) 12 hour am/pm HH:MM:SSp (USA style)
2) 24 hour HH:MM:SS (military style)
The Hour:Minute:Seconds separator is usually a colon, but
for a few countries it is another symbol (i.e. a period).

List of functions and commands:
THEDATE$ country dependent replacement for PB's DATE$
THETIME$ country dependent replacement for PB's TIME$
THEHOUR$ like THETIME$, but returns only hour and minute
GETHMS returns current Secs/100, Hour, Minute & Secs
TIMEINSECS returns current time in seconds since midnight
TIME2HMS converts time string to Hours, Minutes & Secs
TIME2SECS converts time string to seconds since midnight
TIME2WRD converts time string to DOS type timeword
HMS2TIME$ converts Hours, Minutes & Secs to time string
HM2TIME$ converts Hours & Minutes to time string
SECS2TIME$ converts seconds since midnight to time string
WRD2TIME$ converts DOS type timeword to time string
SECS2HMS converts seconds since midnight to Hours, Minutes & Secs
WRD2HMS converts DOS type timeword to Hours, Minutes & Secs
HMS2SECS converts Hour, Minute & Secs to seconds since midnight
HMS2WRD converts Hour, Minute & Secs to DOS type timeword


PBEZ! version 2.0a page 16


WRD2DIRTIME$ converts DOS type timeword to Directory-type time$
GETYMD returns current weekday, Year, Month and Day
DATE2YMD converts date string to Year, Month and Day
DATE2DAYS converts date string to days since Jan 1, 1872
DATE2WRD converts date string to DOS type dateword
YMD2DATE$ converts Year, Month and Day to date string
DAYS2DATE$ converts days since Jan 1, 1872 to date string
WRD2DATE$ converts DOS-type dateword to date string
DAYS2YMD converts days since Jan 1, 1872 to Year, Month and Day
WRD2YMD converts DOS-type dateword to Year, Month and Day
YMD2DAYS converts Year, Month and Day to days since Jan 1, 1872
YMD2WRD converts Year, Month and Day to DOS type dateword
THEDAY returns current weekday (0 to 6)
DAYS2WEEKDAY converts days since Jan 1, 1872 to weekday
YMD2WEEKDAY converts Year, Month and Day to weekday
YMD2DIRDATE$ converts Year, Month and Day to Directory-type date$
WRD2DIRDATE$ converts DOS-type dateword to Directory-type date$
ISLEAPYEAR returns TRUE if a year is a leapyear

By the way the default time format is the 12 Hour am/pm (USA)
style. So american users are advised to use THETIME$ instead of
PowerBASIC's TIME$ to display the current time.

Note: The 2 functions YMD2DIRDATE$ and WORD2DIRDATE$ will not
return centuries. Those functions are particularly useful
for displaying file-dates in directory listings. Another
function that is of particular use for directory listings:
WORD2DIRTIME$ returns only the Hour and Minute.



PBEZ! version 2.0a page 17


KEYBOARD CONTROL

The keyboard is still the most used user input medium. You
basically can't type a letter without the keyboard. For many
programmers PowerBASIC's INSTAT and INKEY$ don't provide
sufficient keyboard control.
For instance, INSTAT and INKEY$ will report certain keypresses
on an enhanced 101-key Keyboard, that it will not report on a
standard 84-key Keyboard. An example is the
key combination. You can now decide whether you want extended
keypresses to be recognized in your program (by for instance
ENSTAT or ENKEY$), or not.

Also, INKEY$ can not distinguish between the normal cursor keys
(numeric keypad) and the gray cursor keys on enhanced keyboards,
whereas ENKEY$ can. The default is that it won't (E0KEYOFF).
But if your program runs on a computer with an enhanced keyboard
(you can check this with EXTKEYB = TRUE) then ENKEY$, etc. will
return a scancode of E0-hex instead of a scancode of 0 for those
gray cursor keys (after issuing the command E0KEYON).

Seems a bit complicated, but once you give it a thought you'll
soon realize what you can do with this added keyboard control.

Instead of ENKEY$, which like INKEY$ returns the keypress in a
string, you can use SCANKEY, which returns both the scancode and
the asciicode. SCANKEY will return an asciicode of 0 for
function keys and cursor keys (E0-hex for gray cursor key with
E0KEYON)

Or you can use KEYWRD to obtain the keypress information as an
unsigned integer (WORD). Three functions will convert the
keypress info from one format in to another.

Two routines, ENKEYCHK$ and SCANKEYCHK don't remove the keypress
from the keyboard buffer. This is handy when you want to check
what the next keypress will be without "loosing" that keypress.

You can also fill the keyboard buffer with keypresses and change
the keyboard repeat-rate.
A large number of routines return the status of the toggle/shift
keys, and you can set and reset the toggle keys.

List of functions and commands:
CLEARKEYB clears the keyboard buffer
ENSTAT replacement for INSTAT (needed for library routines)
ENKEY$ gets normal/extended/enhanced keyboard input
ENKEYCHK$ like ENKEY$, but keypress stays in buffer
WAITKEY$ like ENKEY$, but waits for keypress
SCANKEY returns scancode & asciicode of keypress
SCANKEYCHK like SCANKEY, but keypress stays in buffer
WAITSCANKEY waits for keypress and returns scancode & asciicode
KEYWRD returns keypress as a word (0 if no keypress)
KEYWRDCHK like KEYWRD, but keypress stays in buffer
WAITKEYWRD waits for keypress and returns keypress as a word
ISEXTKEYB returns TRUE if extended keyboard
EXTKEYON extended keyboard codes are recognized
EXTKEYOFF extended keyboard codes are not recognized


PBEZ! version 2.0a page 18


E0KEYON gray (cursor)keys are distinguished (enhanced keyboard)
E0KEYOFF gray (cursor)keys are NOT distinguished
SHIFTSTATUS status of all shift and toggle keys
ISCAPSON status of CapsLock
ISINSON status of Insert
ISNUMON status of NumLock
ISSCROLLON status of ScrollLock
ALTdown status of the Alt-key
CTRLdown status of the Ctrl-key
SHIFTdown status of the Shift-key
LSHIFTdown status of the LeftShift-key
RSHIFTdown status of the RightShift-key
LALTdown status of the LeftAlt-key (extended Keyb)
RALTdown status of the RightAlt-key (extended Keyb)
LCTRLdown status of the LeftCtrl-key (extended Keyb)
RCTRLdown status of the RightCtrl-key (extended Keyb)
SETCAPS... set/reset/toggle CapsLock
SETINS... set/reset/toggle Insert
SETNUM... set/reset/toggle NumLock
SETSCROLL... set/reset/toggle ScrollLock
KEYSPEED sets key repeat rate for AT's
KEY2KEYBOARD fills the keyboard buffer with Scancode & Ascii
STR2KEYBOARD fills the keyboard buffer with a string
ALTKEY$ translates an Alt-key$, nulstring if no valid altkey
ALTCHAR as ALTKEY$ but returns the ASCII value, or zero
CWRD2KEY$ converts keypress (WORD) to a string
CKEY2WRD?? converts keypress (STRING) to a word
SCANASC2KEY$ converts scancode & asciicode to a string

By the way, you can NOT use PowerBASIC's INSTAT function (to
check if a keypress is available) in combination with PBEZ!'s
ENKEY$ and SCANKEY. Use ENSTAT instead. For example:

NOT: WHILE NOT INSTAT : WEND WRONG
K$ = ENKEY$

BUT: WHILE NOT ENSTAT : WEND OKAY
K$ = ENKEY$

OR: WHILE NOT ENSTAT : WEND OKAY
SCANKEY ScanCode?, Asci?

OR: WHILE NOT INSTAT : WEND OKAY
K$ = INKEY$

Still better, if you're going to wait for a keypress, you might
as well us WAITKEY$ or WAITSCANKEY.



PBEZ! version 2.0a page 19


MOUSE AND TEXT-EVENTS

Integrating the mouse into your PowerBASIC program is not an
easy task. Though quite a few "mouse libraries" are written for
PowerBASIC, most just provide the programmer with a simple
interface. The interface usually consists of nomore then calls
to the mouse interrupt functions.
The programmer is left to work out the details of implementing
the, rather simple, interface. Swapping the mouse buttons, for
instance, usually means that you have to set up an
IF..THEN..ELSE construction each time you wish to check for a
particular mouse button or click.
PBEZ!, on the other hand, goes much further than providing you
with a simple mouse interface.

Let's discuss a few of this library's capabilities:
1) After initializing the mouse with MOUSEINIT, all routines
"know" whether a mouse is available.
So you don't have to check for the presence of the mouse
before each mouse-function call.
2) You can enable and disable the mouse without resetting it.
Disabling the mouse doesn't disable the mousedriver. It just
hides the mouse cursor and a flag is simply set which makes
all routines behave as if there's no mouse present.
3) The way the mousedriver works, a MOUSEON call cannot
guarantee that the mousecursor actually becomes visible as
this depends on an internal mousedriver counter that is
decreased each time a MOUSEOFF call is issued. However, by
keeping track of the number MOUSEOFF calls the MOUSETURNON
function "knows" how often to call MOUSEON to make the
mousecursor visible, and in effect forces the mousecursor to
become visible. The programmer no longer needs to keep track
of the number of MOUSEOFF calls throughout his program.
4) You can swap the mousebuttons, and the swapping will take
effect for all routines that check for mousebuttons.
After your program has executed the command MOUSESWAP the
library knows that it should check for the "other" button.
For instance, when your program uses the function MOUSEDOWNL,
the results returned reflect the status of the right button,
after you have told the library to swap the buttons. Of
course MOUSESWAP only works for mice with two or three
buttons.
5) When in textmode the programmer is not interested in the
mouseposition as returned by the mousedriver. The mousedriver
returns screencoordinates that usually depend on the active
screenmode. But when in textmode, the programmer will be more
interested in the location of the mousecursor in terms of row
and column. A number of routines provide you with a row /
column oriented interface. These are, besides the text-event
routines: MOUSEROWCOL, MOUSEROW, MOUSECOL, MOUSELOCATE and
MOUSETXTWINDOW.
The actual coordinates returned by or sent to the mousedriver
are converted by the routines MOUSEXPOS2COL and
MOUSEYPOS2ROW. These routines check the BIOS data area to see
how many columns and rows the screen consists of and converts
the vertical and horizontal coordinates into row and column.
If you prefer to use the screencoordinates yourself the
library provides you with: MOUSEWHERE, MOUSEXPOS, MOUSEYPOS


PBEZ! version 2.0a page 20


and MOUSEMOVE.
6) You can easily use the mouse in your TSR's without loosing
the last mouse settings. Just use MOUSEPOPDOWN before you
popdown, and MOUSEPOPUP after popup. These routines save and
restore the internal mouse parameters.
7) The library comes with a clever event checking mechanism for
textmodes. It works quite simple and uses "text windows" to
setup and identify events.
First, you open an eventwindow with OPENTWNDEVENT. The
routine returns a free window eventhandle and defines an area
of the screen, further referred to as an eventwindow.
Next, you define textscreen areas within the previously
defined eventwindow using ADDTXTEVENT. This routine will
return a unique eventnumber for each textevent. Store the
eventnumbers in integer variables (or an integer array).
The event mechanism is now setup.
All you have to do is use the function GETTXTEVENT with a
specified row and column to check which eventwindow and which
textevent is activated, and use the returned values to take
action.
MOUSETXTEVENT makes it even easier. It checks for left
mousebutton clicks and subsequent releases. Only clicks and
releases on previously defined textevents are recognized, and
the eventwindow and textevent numbers are returned in
variables. You can check these variables to see which event
is activated. The function can return the following values:

value meaning remarks

0 not clicked, or ignore
clicked on NO event, or
released on NO event

-1 clicked on event ignore until released
(1e pass)

-2 clicked on event, and dragging:
left button still down ignore until released,
(2ed pass) or special action

1 once clicked on event and ignore if other event,
released on (other?) event or take action

=> 2 twice clicked on same event immediate action

To make it all work, you should use MOUSETXTEVENT inside a
loop that also checks for keypresses.
The remarks only indicate possible actions. Events should for
instance be activated when the mousebutton is released, but
feel free to take action when clicked on an event. Again,
MOUSETXTEVENT works for left mousebutton clicks and releases,
but you can make it work for the right button by issuing
MOUSESWAP.
Pressing the roght mouse button will call the routine
MOUSEEVENTRESET. This routine resets the internal variables and
counters of the mechanism and should be called after setting
up an eventwindow and the associated textevents, and before
the eventchecking loop.


PBEZ! version 2.0a page 21


As you can see, the routine can recognize double-clicks on
the same event. You can set the double-click speed with
MOUSECLICKSPEED (default: 18 clockticks = 1 second).
Of course you should not forget to close a particular
eventwindow after you're done with it, using CLOSETWNDEVENT.

List of functions and commands:
MOUSEINIT initializes and resets mouse, returns ## of buttons
MOUSERESET resets mouse software and parameters, NO initialize
MOUSEBUTTONS ## of mouse buttons detected
MOUSEENABLE enables the mouse library routines, calls MOUSEON
MOUSEDISABLE disables the mouse library routines, calls MOUSEOFF
MOUSEENABLED TRUE if mouse initialized and not disabled
MOUSEON increases counter, shows mousecursor if counter = 0
MOUSEOFF decreases counter, always hides mousecursor
MOUSETURNON always shows mousecursor (increases counter till 0)
MOUSEWHERE current position of mousecursor (coordinates)
MOUSEROWCOL current location of mousecursor in rows and columns
MOUSEXPOS horizontal position of mousecursor (coordinate)
MOUSECOL horizontal location of mousecursor in columns
MOUSEYPOS vertical position of mousecursor (coordinate)
MOUSEROW vertical location of mousecursor in rows
MOUSEMOVE positions the mousecursor (coordinates)
MOUSELOCATE positions the mousecursor at row, column
MOUSETXTCURSOR defines the mousecursor in textmode
MOUSETXTWINDOW sets minimum and maximum boundaries for mousecursor
MOUSESWAP swaps the Left and Right mouse buttons (userlevel)
MOUSESWAPPED TRUE if mousebuttons are swapped
MOUSEDOWNA TRUE if Any mouse button is down, else FALSE
MOUSEDOWNL TRUE if Left mouse button is down, else FALSE
MOUSEDOWNR TRUE if Right mouse button is down, else FALSE
MOUSEDOWNM TRUE if Middle mouse button is down, else FALSE
MOUSETCLICKL ## of leftbutton-clicks and row,col of last
MOUSETCLICKR ## of rightbutton-clicks and row,col of last
MOUSETCLICKM ## of middlebutton-clicks and row,col of last
MOUSETRELEASEL ## of leftbutton-releases and row,col of last
MOUSETRELEASER ## of rightbutton-releases and row,col of last
MOUSETRELEASEM ## of middlebutton-releases and row,col of last
MOUSESETSPEED sets mousecursor movement speed
MOUSEGETSPEED returns mouse speed parameters
FREETWNDEVENT returns free handle for text-event window
OPENTWNDEVENT opens (defines) text-event window, returns handle
CLOSETWNDEVENT closes (frees-up) text-event window
ADDTXTEVENT defines text-event for specified window handle and
screen area, returns event ## (subevent)
GETTXTEVENT returns handle and event ## for specified row,col
MOUSETXTEVENT THE mouse-text-event handler (uses GETTXTEVENT)
MOUSEEVENTRESET resets variables used by event checking mechanism
MOUSECLICKSPEED sets the double click speed in clockticks
MOUSEXPOS2COL converts horizontal-coordinate (mouse) to column
MOUSEYPOS2ROW converts vertical-coordinate (mouse) to row
MOUSEPOPDOWN saves the mousedriver state (before popping-down!)
MOUSEPOPUP restores the mousedriverstate (after popping-up!)



PBEZ! version 2.0a page 22


TEXTSCREEN, PRINTING AND COLORS

Nearly every PowerBASIC programmer has seen at least one fast
text-printing routine. They usually go under the name of QPRINT
or something similar. PBEZ! however offers the programmer a
whole range of fast screen-access routines, and most of them are
pretty versatile too.
You can for instance print a portion of a string (PRINTMIDS)
without using MID$. Using MID$ slows down the process
tremendously.
You can also print without affecting the current colors on
screen (PRINTSTR), or print with alternating color-attributes
(PRINTSWA). These color-attributes are imbedded in the string
and a preceeding (user-defined) signal-byte triggers the
color-attribute change. This is particularly useful for
high-lighting words or letters on screen.

But it doesn't stop there! LINEPRINT prints (a portion of) a
string to the textscreen, expanding tabs in the process and
clearing the screen-row if the number of chars printed is less
than the specified number of columns to be used for the string.
The part of the string to be "processed" is defined by an offset
(or MidPos) parameter, and "processing" stops when a
user-defined character (-combination) is encountered or enough
characters were printed to fill the number of colors as defined.
It also takes a parameter defining the horizontal-scroll effect,
which allows scrolling the visual part of the printed text.

Take this one step further and you have a block-print routine.
Well, BLOCKPRINT does it. You:
1) define the screen area to print to,
2) tell the routine whether:
- to wrap long lines of text to the next row, or
- to start on the next row after the next carriage return
symbol,
3) pass the number of columns for horizontal-scrolling (left),
4) pass the (flex)string,
5) where in the string to start processing characters (Midpos),
6) define the carriage-return symbol (can be two bytes),
7) define the tabwidth you want to use (0 means no tabs are
expanded),
8) define the color-attribute to start printing with, and
9) the change attribute symbol,
and BLOCKPRINT does the rest. No, wordwrap is not (yet?)
supported. As it is now, the linewrap may cut words in half.

There's also an ANSIPRINT routine, but (as all the routines in
this library) it's written in assembly and is so fast that you
may want to slow it down. INITANSIPRINT must be used at least
once before you start ANSIPRINTing, and you can define an area
of the screen within which to ANSIPRINT text, the default
(starting) color-attribute, and the ANSIPRINT speed.

But there's still lots more. You can recolor foreground and
background, or both, of textscreen areas, fill them, clear them,
draw textboxes with pre-defined or user-defined borders, scroll
a textscreen area in any direction. Saving and restoring
textscreens is a breeze with GETTEXT$ and PUTTEXT, and PUTTEXTAT


PBEZ! version 2.0a page 23


allows you to move textscreen areas around.

List of functions and commands:
PRINTS prints string at row,col with colorattr (QPRINT alias)
PRINTMIDS like PRINTS but prints a portion of the string
PRINTSTR like PRINTS but doesn't affect current screen colors
PRINTMIDSTR like PRINTSTR but prints a portion of the string
PRINTSWA like PRINTS but 6W3ith 6A3ttr chars to change colors
PRINTMIDSWA like PRINTSWA but prints a portion of the string
LINEPRINT prints (mid)string, expanding tabs, with offset
for horz.scroll, limited to cols or CRLF symbol, etc.
BLOCKPRINT like LINEPRINT but for multiple lines with(out) wrap
INITANSIPRINT sets up internal variables for ANSIPRINT
ANSIPRINT super fast ansi printing
CLRTEXTSCRN clears the entire textscreen
CLRTEXTBOX clears an area of the textscreen
FILLTEXTBOX fills a textscreen area with a specified character
COLORTEXT recolors an area of the textscreen
COLORTEXTFORE recolors the foreground of an area of the textscreen
COLORTEXTBACK recolors the background of an area of the textscreen
DRAWTEXTBOX draws a box on the textscreen and clears the inside
OUTLINETEXT draws a box but won't clear what's inside the box
DEFBOXBORDER sets up a user defined default border for boxes
CENTRECOL for centering boxes, strings, etc. on the textscreen
CENTREROW for centering boxes, strings, etc. on the textscreen
SCROLLLEFT scrolls an area of the textscreen to the left
SCROLLRIGHT scrolls an area of the textscreen to the right
SCROLLUP scrolls an area of the textscreen up
SCROLLDOWN scrolls an area of the textscreen down
GETTEXTSCRN saves the textscreen into a string
PUTTEXTSCRN restores the textscreen
GETTEXTCURS saves the position of the cursor
PUTTEXTCURS restores the position of the cursor
GETTEXT$ saves an area of the textscreen into a string
PUTTEXT restores an area of the textscreen
PUTTEXTAT restores a previously saved area at specified location
COLOR2ATTR converts normal color values to color attribute
ATTR2COLOR converts color attribute to normal color values
INVERSEATTR returns an attribute used to inverse colors
FORETOBACK as INVERSEATTR, but swaps intensity/blink bits as well
ISBLINKON TRUE if blink is enabled, else FALSE
BLINKTEXT enables or disables blinking foreground as specified
BLINKOFF disables blinking, enabling bright background colors
BLINKON enables blinking foreground colors
SCREENTEXT$ reads the text from the textscreen into a string
TXTSCRN2FILE dumps the textscreen to a file (appends)
ISMONOTEXT TRUE if current screen mode is monochrome text
VIDEOSEG returns segment of textscreen buffer
VIDEOPTR returns offset of textscreen buffer
VIDEOPAGE returns active videopage number
VIDEOROWS returns number of textscreen rows
VIDEOCOLS returns number of textscreen cols
CENTRETEXT for centering text between boundaries using a string
CENTREPOS for centering text between boundaries using a num.expr.



PBEZ! version 2.0a page 24


MISCELLANY

This section contains a number of miscellaneous routines.

A number of routines deal with manipulating (un)signed integers:
1) You can easily check if an integer expression is even or odd.
2) You can rotate and shift their bits, swap, combine and
extract the high-order and low-order bytes or words.
Note: Although PowerBASIC provides the SHIFT and ROTATE
commands, I found a way to increase speed and thought
it useful to write the routines as functions that leave
the original variable intact.
Besides that, PowerBASIC's "SHIFT SIGNED LEFT ivar,
count" doen't always preserve the sign.
3) You can store and extract (un)signed integers in reversed
byte-order into and from strings. This becomes useful when
you want to sort strings on fields that hold numeric values.
4) You can use ARRAYSUM to quickly obtain the sum of a number of
integer array elemants.
5) You can use INCRD... and DECRD... to increment and decrement
DOUBLE WORDS using faster integer instructions.
6) You can increment and decrement integers while "wrapping"
around a minimum (0 or 1) and maximum boundary with
WRAPAROUND0 and WRAPAROUND1.
7) You can obtain both the quotient and the remainder of an
integer divsion by 100.

Included are a few routines that allow you to setup delays with
a resolution of about 1 milli-second. These routines will only
work correctly on AT compatible machines (no harm done on
others).
DELAYSET and DELAYEND provide you with a tool to execute a piece
of your program independent of CPU-speed.
Example:
Suppose you want to blank the textscreen by scrolling the
screen right, one column at a time. And you want this to
happen in exactly one second. This is the way to accomplish
it:

MilliSecs?? = 1000 \ 80 For each column take 1/80 sec.
FOR Column% = 1 TO 80 Scroll 80 columns one by one.
DELAYSET MilliSecs?? This will execute on both slow
SCROLLRIGHT 0,0,0,0,1,Attr% AT's and fast 486's in
DELAYEND exactly one second.
NEXT


You can also use the function DELAYOVER to execute a specific
routine a number of times, until the delay is over.
Example:

MilliSecs?? = 100
DELAYSET MilliSecs??
DO
' do something here
LOOP UNTIL DELAYOVER




PBEZ! version 2.0a page 25


The function DOSVERSION will return the DOS version number times
100, e.g. version 3.3 will be returned as 330. As stated
elsewhere, some routines need DOS version 3.3 or higher, and it
would be a good thing to check this at the start of your
program. After all, versions before 3.3, do they still exist???

The function DOSEXECUTE provides a means to execute programs
(*.COM and *.EXE) as a child-process without loading a second
copy of COMMAND.COM. As such it's faster and uses less memory
that PowerBASIC's SHELL.
Besides that, information about possible errors is returned by
the function, and additional information can be obtained with
DOSERRORLEVEL, such as the errorlevel-code returned by the
"childprogram".

List of functions and commands:
ISEVEN... TRUE if (result of) expression is even
ISODD... TRUE if (result of) expression is odd
ROTLFT... returns a copy of an ivar with bits rotated left
ROTRGT... returns a copy of an ivar with bits rotated right
SHFLFT... returns a copy of an ivar with bits shifted left
SHFRGT... returns a copy of an ivar with bits shifted right
SHFLFTS... like SHFLFT... but with sign bit preserved
SHFRGTS... like SHFRGT.. but with sign bit preserved
HIGHBYTE... Returns the high BYTE of an INTEGER or WORD
HIGHWORD... Returns the high WORD of an LONG integer or DWORD
HILOSWAPPED swaps highpart and lowpart of an integer
HILOSPLIT... splits an integer into highpart and lowpart
HILOCOMBINED.. combines two values (Hi-Lo) into one integer
RCVI... converts reversed string to integer
RMKI$... converts integer to reversed string
ARRAYSUM... returns the sum of a number of array elements
INCRD... increments DWORDs using (faster) integer instructions
DECRD... decrements DWORDs using (faster) integer instructions
WRAPAROUND0... in- & decrements wrapping around max. & min. boundary
MODULO100 returns both quotient and remainder of division by 100
DELAYMS delays x milliseconds
DELAYSET sets delay timer to x milliseconds
DELAYEND awaits elapse of x milliseconds set with DELAYSET
DELAYOVER returns TRUE/FALSE if time has elapsed
DOSVERSION returns the systems DOSversion no
DOSEXECUTE runs a program as a child process (similar to SHELL)
DOSERRORLEVEL returns ErrorLevel and ExitCode of child program
CENTREOBJ returns position used to centre an object



PBEZ! version 2.0a page 26


ALPHABETICAL LIST

ADDTXTEVENT defines text-event for specified window handle and
screen area, returns event ## (subevent)
ALTCHAR as ALTKEY$ but returns the ASCII value, or zero
ALTdown status of the Alt-key
ALTKEY$ translates an Alt-key$, nulstring if no valid altkey
ANSIPRINT super fast ansi printing
ARRAYSUM... returns the sum of a number of array elements
ASCLAST returns the ASCII value of the last string-character
ASCMID returns the ASCII value of a string-character
ATTR2COLOR converts color attribute to normal color values
BINA$... returns correctly 0-padded binary string
BINVAL returns value of binary string
BLINKOFF disables blinking, enabling bright background colors
BLINKON enables blinking foreground colors
BLINKTEXT enables or disables blinking foreground as specified
BLKREAD... reads a number of bytes or array elements from a file
BLKWRITE... writes a number of bytes or array elements to a file
BLOCKPRINT like LINEPRINT but for multiple lines with(out) wrap
CENTRECOL for centering boxes, strings, etc. on the textscreen
CENTREOBJ returns position used to centre an object
CENTREPOS for centering text between boundaries using a num.expr.
CENTREROW for centering boxes, strings, etc. on the textscreen
CENTRETEXT for centering text between boundaries using a string
CHARINSTR returns the INSTR of the first non-whitespace char
CHGDIR changes directory, returns TRUE if success
CHGDRIVE changes the default drive, returns TRUE if success
CHR2MID replaces a character at a position in a string
CKEY2WRD?? converts keypress (STRING) to a word
CLEARKEYB clears the keyboard buffer
CLOSETWNDEVENT closes (frees-up) text-event window
CLRTEXTBOX clears an area of the textscreen
CLRTEXTSCRN clears the entire textscreen
COLLATESORT$ a 256 byte string to be used with ARRAY SORT
COLOR2ATTR converts normal color values to color attribute
COLORTEXT recolors an area of the textscreen
COLORTEXTBACK recolors the background of an area of the textscreen
COLORTEXTFORE recolors the foreground of an area of the textscreen
CRLFINSTR returns the INSTR of a CR/LF
CTRLdown status of the Ctrl-key
CURDECIMALS number of decimals used in currency expressions
CURRENCYPOS position of the currency symbol in currency expr.
CURRENTDIR$ returns the current directory of a drive, NULL if error
CWRD2KEY$ converts keypress (WORD) to a string
DATE2DAYS converts date string to days since Jan 1, 1872
DATE2WRD converts date string to DOS type dateword
DATE2YMD converts date string to Year, Month and Day
DATESEP ascii value of the char used to separate Y,M and D
DATETYPE currently active date format (0,1 or 2)
DAYS2DATE$ converts days since Jan 1, 1872 to date string
DAYS2WEEKDAY converts days since Jan 1, 1872 to weekday
DAYS2YMD converts days since Jan 1, 1872 to Year, Month and Day
DECIMALSEP ascii value of the decimal separator
DECRD... decrements DWORDs using (faster) integer instructions
DECRHUGEPTR Decrements a farpointer, across segments
DECRPTR Decrements a farpointer, preventing "segment overflow"
DECVAL returns value of decimal string


PBEZ! version 2.0a page 27


DEFBOXBORDER sets up a user defined default border for boxes
DELAYEND awaits elapse of x milliseconds set with DELAYSET
DELAYMS delays x milliseconds
DELAYOVER returns TRUE/FALSE if time has elapsed
DELAYSET sets delay timer to x milliseconds
DELETECHARS deletes one or more characters from a string
DELETEPIECE removes a piece of a string using separators
DETAB$ returns a copy of a string with embedded tabs expanded
DIRFILEATTR returns the attribute of the last file found
DIRFILEDATE returns the date of the last file found
DIRFILENAME$ returns the name of the last file found
DIRFILESIZE returns the size of the last file found
DIRFILETIME returns the time of the last file found
DIRFIRSTFILE returns TRUE/FALSE if matching file was found
DIRNEXTFILE returns TRUE/FALSE if further files were found
DISKERR errorcode of the last direct file-access
DISKFREE returns the number bytes free on the disk
DISKSIZE returns the disksize in bytes
DOSERR errorcode of the last DOS-operation
DOSERRORLEVEL returns ErrorLevel and ExitCode of child program
DOSEXECUTE runs a program as a child process (similar to SHELL)
DOSVERSION returns the systems DOSversion no
DRAWTEXTBOX draws a box on the textscreen and clears the inside
DRIVEREADY checks if the diskdrive is ready
DTAPTR returns a farpointer to the current DTA area
E0KEYOFF gray (cursor)keys are NOT distinguished
E0KEYON gray (cursor)keys are distinguished (enhanced keyboard)
ENKEY$ gets normal/extended/enhanced keyboard input
ENKEYCHK$ like ENKEY$, but keypress stays in buffer
ENSTAT replacement for INSTAT (needed for library routines)
EXTKEYOFF extended keyboard codes are not recognized
EXTKEYON extended keyboard codes are recognized
FADR... Returns a 20-bit address
FILEATTRIB$ converts an attribute-byte to a 4 character string
FILEMATCH TRUE if filename matches a pattern with * and/or ?
FILLTEXTBOX fills a textscreen area with a specified character
FORETOBACK as INVERSEATTR, but swaps intensity/blink bits as well
FPTR... Returns a far pointer to its argument
FREETWNDEVENT returns free handle for text-event window
GETATTRIB returns a file's attribute, 255 if error
GETCOUNTRY system's current Country Code
GETCURRENCY$ country's currency symbol as a string
GETDIR$ searches and returns matching filename (as PB's DIR$)
GETDTA$ returns the first 21 bytes of the current DTA area
GETFILEDATE returns a file's date & time as a long integer
GETFIRSTDIR returns TRUE/FALSE if matching subdir was found
GETHMS returns current Secs/100, Hour, Minute & Secs
GETMONEYMASK$ formatted mask to be used with PRINT USING or USING$
GETNEXTDIR returns TRUE/FALSE if further subdirs were found
GETPIECE$ returns any piece of a string using separators
GETTEXT$ saves an area of the textscreen into a string
GETTEXTCURS saves the position of the cursor
GETTEXTSCRN saves the textscreen into a string
GETTXTEVENT returns handle and event ## for specified row,col
GETYMD returns current weekday, Year, Month and Day
HANDLESTR returns the handle of a string
HEXA$... returns correctly 0-padded hex string
HEXVAL returns value of hex string


PBEZ! version 2.0a page 28


HIGHBYTE... Returns the high BYTE of an INTEGER or WORD
HIGHWORD... Returns the high WORD of an LONG integer or DWORD
HILOCOMBINED.. combines two values (Hi-Lo) into one integer
HILOSPLIT... splits an integer into highpart and lowpart
HILOSWAPPED swaps highpart and lowpart of an integer
HM2TIME$ converts Hours & Minutes to time string
HMS2SECS converts Hour, Minute & Secs to seconds since midnight
HMS2TIME$ converts Hours, Minutes & Secs to time string
HMS2WRD converts Hour, Minute & Secs to DOS type timeword
INCRD... increments DWORDs using (faster) integer instructions
INCRHUGEPTR Increments a farpointer, across segments
INCRPTR Increments a farpointer, preventing "segment overflow"
INITANSIPRINT sets up internal variables for ANSIPRINT
INSERTCHR inserts a character into a string
INSERTPIECE inserts a piece into a string using separators
INSERTSTR inserts a string into a string
INSERTWRD or INSERTINT inserts 2 characters into a string
INT2MID or WRD2MID replaces 2 characters in a string
INVERSEATTR returns an attribute used to inverse colors
ISBLINKON TRUE if blink is enabled, else FALSE
ISCAPSON status of CapsLock
ISDRIVE checks if the drive exists, returns TRUE/FALSE
ISEVEN... TRUE if (result of) expression is even
ISEXTKEYB returns TRUE if extended keyboard
ISINSON status of Insert
ISLEAPYEAR returns TRUE if a year is a leapyear
ISMONOTEXT TRUE if current screen mode is monochrome text
ISNLSFUNC returns TRUE if NLSFUNC is installed
ISNUMON status of NumLock
ISODD... TRUE if (result of) expression is odd
ISSCROLLON status of ScrollLock
KEY2KEYBOARD fills the keyboard buffer with Scancode & Ascii
KEYSPEED sets key repeat rate for AT's
KEYWRD returns keypress as a word (0 if no keypress)
KEYWRDCHK like KEYWRD, but keypress stays in buffer
KILLFILE deletes a file, returns TRUE if success
LALTdown status of the LeftAlt-key (extended Keyb)
LASTPIECE$ returns the last piece of a string using separators
LCASECHAR converts byte to lowercase (country dependent)
LCASED$ country dependent replacement for PB's LCASE$
LCASEMID$ as UCASED$, but returns lcased part of string
LCTRLdown status of the LeftCtrl-key (extended Keyb)
LINEPRINT prints (mid)string, expanding tabs, with offset for
horz.scroll, limited to cols or CRLF symbol, etc.
LISTSEPAR ascii value of the char used as datalist separator
LNG2MID or DWD2MID replaces 4 characters in a string
LSHIFTdown status of the LeftShift-key
MAKEDIR creates a directory, returns TRUE if success
MIDSTR$ returns a portion of a string (alternative MID$)
MODULO100 returns both quotient and remainder of division by 100
MOUSEBUTTONS ## of mouse buttons detected
MOUSECLICKSPEED sets the double click speed in clockticks
MOUSECOL horizontal location of mousecursor in columns
MOUSEDISABLE disables the mouse library routines, calls MOUSEOFF
MOUSEDOWNA TRUE if Any mouse button is down, else FALSE
MOUSEDOWNL TRUE if Left mouse button is down, else FALSE
MOUSEDOWNM TRUE if Middle mouse button is down, else FALSE
MOUSEDOWNR TRUE if Right mouse button is down, else FALSE


PBEZ! version 2.0a page 29


MOUSEENABLE enables the mouse library routines, calls MOUSEON
MOUSEENABLED TRUE if mouse initialized and not disabled
MOUSEEVENTRESET resets variables used by event checking mechanism
MOUSEGETSPEED returns mouse speed parameters
MOUSEINIT initializes and resets mouse, returns ## of buttons
MOUSELOCATE positions the mousecursor at row, column
MOUSEMOVE positions the mousecursor (coordinates)
MOUSEOFF decreases counter, always hides mousecursor
MOUSEON increases counter, shows mousecursor if counter = 0
MOUSEPOPDOWN saves the mousedriver state (before popping-down!)
MOUSEPOPUP restores the mousedriverstate (after popping-up!)
MOUSERESET resets mouse software and parameters, NO initialize
MOUSEROW vertical location of mousecursor in rows
MOUSEROWCOL current location of mousecursor in rows and columns
MOUSESETSPEED sets mousecursor movement speed
MOUSESWAP swaps the Left and Right mouse buttons (userlevel)
MOUSESWAPPED TRUE if mousebuttons are swapped
MOUSETCLICKL ## of leftbutton-clicks and row,col of last
MOUSETCLICKM ## of middlebutton-clicks and row,col of last
MOUSETCLICKR ## of rightbutton-clicks and row,col of last
MOUSETRELEASEL ## of leftbutton-releases and row,col of last
MOUSETRELEASEM ## of middlebutton-releases and row,col of last
MOUSETRELEASER ## of rightbutton-releases and row,col of last
MOUSETURNON always shows mousecursor (increases counter till 0)
MOUSETXTCURSOR defines the mousecursor in textmode
MOUSETXTEVENT THE mouse-text-event handler (uses GETTXTEVENT)
MOUSETXTWINDOW sets minimum and maximum boundaries for mousecursor
MOUSEWHERE current position of mousecursor (coordinates)
MOUSEXPOS horizontal position of mousecursor (coordinate)
MOUSEXPOS2COL converts horizontal-coordinate (mouse) to column
MOUSEYPOS vertical position of mousecursor (coordinate)
MOUSEYPOS2ROW converts vertical-coordinate (mouse) to row
OPENTWNDEVENT opens (defines) text-event window, returns handle
OUTLINETEXT draws a box but won't clear what's inside the box
PADFILENAME$ returns a padded file name eg: "FILE .EXE "
PEEKFAR... PEEK using a farpointer
PEEKSEG... PEEK without DEF SEG statement
PIECECOUNT returns the number of pieces in a string
PIECEPOS returns the INSTR of a given piece
POKEFAR... POKE using a farpointer
POKESEG... POKE without DEF SEG statement
PRINTMIDS like PRINTS but prints a portion of the string
PRINTMIDSTR like PRINTSTR but prints a portion of the string
PRINTMIDSWA like PRINTSWA but prints a portion of the string
PRINTS prints string at row,col with colorattr (QPRINT alias)
PRINTSTR like PRINTS but doesn't affect current screen colors
PRINTSWA like PRINTS but 6W3ith 6A3ttr chars to change colors
PROGRAMNAME$ returns the current program's drive:\path\progname.exe
PROGRAMPATH$ returns the current program's drive and path
PUTDTA sets (restores) the first 21 bytes of the current DTA
PUTTEXT restores an area of the textscreen
PUTTEXTAT restores a previously saved area at specified location
PUTTEXTCURS restores the position of the cursor
PUTTEXTSCRN restores the textscreen
QCOPY... Copies data from one array/mem-location to another
QCOPYBSTR$... Creates a string from data in an array or mem-location
QCOPYSTR... Copies data from a string to array/mem-location
QFILL... Fills an array or memory with a predefined value


PBEZ! version 2.0a page 30


RALTdown status of the RightAlt-key (extended Keyb)
RCTRLdown status of the RightCtrl-key (extended Keyb)
RCVI... converts reversed string to integer
READ... reads numeric variables directly from a file
REMDIR removes a directory, returns TRUE if success
REMOVEPIECE$ returns and removes a piece of a string using separators
REPLACEPIECE replaces a piece of a string with a new value
REVERSE reverses a string
REVERSED$ returns a reversed copy of a string
RMKI$... converts integer to reversed string
ROTLFT... returns a copy of an ivar with bits rotated left
ROTRGT... returns a copy of an ivar with bits rotated right
RSCANB as SCANB but scans from right to left
RSCANBMID as RSCANB but acts on a portion of a string
RSCANW as SCANW but scans from right to left
RSCANWMID as RSCANW but acts on a portion of a string
RSHIFTdown status of the RightShift-key
SCANASC2KEY$ converts scancode & asciicode to a string
SCANB returns the INSTR of one char (faster than INSTR)
SCANBMID as SCANB but acts on a portion of a string
SCANKEY returns scancode & asciicode of keypress
SCANKEYCHK like SCANKEY, but keypress stays in buffer
SCANW returns the INSTR of two chars (faster than INSTR)
SCANWMID as SCANW but acts on a portion of a string
SCREENTEXT$ reads the text from the textscreen into a string
SCROLLDOWN scrolls an area of the textscreen down
SCROLLLEFT scrolls an area of the textscreen to the left
SCROLLRIGHT scrolls an area of the textscreen to the right
SCROLLUP scrolls an area of the textscreen up
SECS2HMS converts seconds since midnight to Hours, Minutes & Secs
SECS2TIME$ converts seconds since midnight to time string
SEEKABS and SEEKREL: moves filepointer
SEEKBEG and SEEKEND: moves filepointer to start or end of file
SEEKPOS returns the current filepointer location
SETATTRIB sets a file's attribute, returns TRUE if success
SETCAPS... set/reset/toggle CapsLock
SETCOUNTRY sets the Country Code, initializes internal variables
SETCURRENCY sets the currency symbol (used with GETMONEYMASK$)
SETDATETYPE sets date-type and date-separator
SETFILEDATE sets a file's date & time
SETINS... set/reset/toggle Insert
SETLOWERCASE sets an 128 byte internal table for LCASE conversions
SETNUM... set/reset/toggle NumLock
SETSCROLL... set/reset/toggle ScrollLock
SETTIMETYPE sets time-type and time-separator
SETUCASEROUT sets a farpointer to the routine used by UCASECHAR
SETUPPERCASE sets an 128 byte internal table for UCASE conversions
SHFLFT... returns a copy of an ivar with bits shifted left
SHFLFTS... like SHFLFT... but with sign bit preserved
SHFRGT... returns a copy of an ivar with bits shifted right
SHFRGTS... like SHFRGT.. but with sign bit preserved
SHIFTdown status of the Shift-key
SHIFTSTATUS status of all shift and toggle keys
SPLITFILENAME splits filename into name and extension
SPLITFILESPEC splits full filespec into path and filename
STR2KEYBOARD fills the keyboard buffer with a string
STRIPEXT$ returns name of file without extension
STRIPFILE$ returns path by stripping the filename from filespec


PBEZ! version 2.0a page 31


STRIPNAME$ returns extension of filename
STRIPPATH$ returns filename by stripping the path from filespec
TALLYMID as TALLYSTR but acts on a portion of a string
TALLYSTR returns the number of occurrences of a specified char
THEDATE$ country dependent replacement for PB's DATE$
THEDAY returns current weekday (0 to 6)
THEHOUR$ like THETIME$, but returns only hour and minute
THETIME$ country dependent replacement for PB's TIME$
THOUDECSEP$ string with thousands & decimal separator
THOUSANDSEP ascii value of the thousands separator
TIME2HMS converts time string to Hours, Minutes & Secs
TIME2SECS converts time string to seconds since midnight
TIME2WRD converts time string to DOS type timeword
TIMEINSECS returns current time in seconds since midnight
TIMESEP ascii val of the char used to separate H,M and S
TIMETYPE currently active time format (0 or 1)
TOLOWER converts string to lowercase (country dependent)
TOLOWERMID as TOUPPER, but acts on part of string
TOUPPER converts string to uppercase (country dependent)
TOUPPERMID as TOUPPER, but acts on part of string
TXTSCRN2FILE dumps the textscreen to a file (appends)
UCASECHAR converts byte to uppercase (country dependent)
UCASED$ country dependent replacement for PB's UCASE$
UCASEMID$ as UCASED$, but returns ucased part of string
VIDEOCOLS returns number of textscreen cols
VIDEOPAGE returns active videopage number
VIDEOPTR returns offset of textscreen buffer
VIDEOROWS returns number of textscreen rows
VIDEOSEG returns segment of textscreen buffer
WAITKEY$ like ENKEY$, but waits for keypress
WAITKEYWRD waits for keypress and returns keypress as a word
WAITSCANKEY waits for keypress and returns scancode & asciicode
WRAPAROUND0... in- & decrements wrapping around max. & min. boundary
WRD2DATE$ converts DOS-type dateword to date string
WRD2DIRDATE$ converts DOS-type dateword to Directory-type date$
WRD2DIRTIME$ converts DOS type timeword to Directory-type time$
WRD2HMS converts DOS type timeword to Hours, Minutes & Secs
WRD2TIME$ converts DOS type timeword to time string
WRD2YMD converts DOS-type dateword to Year, Month and Day
WRITE... writes numeric variables directly to a file
XMSBLKREAD... Reads a block of data from XMS-memory, TRUE if success
XMSBLKWRITE... Writes a block of data to XMS-memory, TRUE if success
XMSCLOSE Closes an XMS-memory block, TRUE if success
XMSERR Returns an XMS-errorcode for the last XMS-operation
XMSEXISTS Returns TRUE if XMS exists, else FALSE
XMSFREEBLK Returns the size of the largest free XMS-block in Kbytes
XMSFREEMEM Returns total free XMS-memory in Kbytes
XMSOPEN Allocates an XMS-memory block, TRUE if success
XMSREAD... Reads a numeric variable from XMS-memory, TRUE if success
XMSREADSTR Reads a string variable from XMS-memory, TRUE if success
XMSRESIZE Resizes an open XMS-memory block, TRUE if success
XMSVERSION Returns version of XMS driver if installed, else zero
XMSWRITE... Writes a numeric variable to XMS-memory, TRUE if success
XMSWRITESTR Writes a string variable to XMS-memory, TRUE if success
YMD2DATE$ converts Year, Month and Day to date string
YMD2DAYS converts Year, Month and Day to days since Jan 1, 1872
YMD2DIRDATE$ converts Year, Month and Day to Directory-type date$
YMD2WEEKDAY converts Year, Month and Day to weekday


PBEZ! version 2.0a page 32


YMD2WRD converts Year, Month and Day to DOS type dateword



PBEZ! version 2.0a page 33


REGISTRATION

The PBEZ! library is written by Pieter van Dijk, and is
published as Shareware. This means that you can try out the
library for a period of 30 days. If you continue to use this
library, or any program written with the use of this library,
you must register. The registration fee is (the equivalent of)
US$ 25 or 40 Dutch guilders.

If you register you will receive:
1) the latest versions of PBEZ! (normal and 386 version)
2) the "source" of the PBEZ! helpfiles
3) a helpfile pre-compiler to be used with PowerBASIC's
MAKEHELP.EXE, including the sourcecode.
4) a program called MAKEPBL.EXE, including the sourcecode
5) at least one update of the next version of PBEZ!

Having the sourcecode of the helpfile enables you to add your
own routines, tables, notes and remarks etc. to that one big
PBEZ! helpfile.
The helpfile pre-compiler (MAKEHLP.EXE) allows you to write the
help in multiple files. The program (actually 2 programs) will
combine specified files to one big one, and in the process of
doing so it can:
- automatically generate /LOCAL statements (for cross-
references),
- automatically generate /LOOKUP statements (if you provide the
DECLARE SUB and DECLARE FUNCTION statement in your help), and
- generate an alphabetical list of keywords.
The program will also generate a detailed report with errors and
warnings, and prevent compilation by MAKEHELP.EXE if errors have
occurred. Besides that it allows you to use multiple /TOPIC
names, etc.

MAKEPBL.EXE is an easy-to-use PowerBASIC MAKE utility. You just
tell it where to find the sourcecode files and where to put the
object and/or pbu-files and PBL-file. It checks which files
need to be recompiled/reassembled and updates the PBL-file
accordingly. Automation is the word of the game. It makes
building and correcting your libraries so much easier.

MAKEPBL.BAS does not make use of the PBEZ! library, MAKEHLP.BAS
does!



PBEZ! version 2.0a page 34


For ordering the registered version from within Holland, see
last paragraph. For orders from outside Holland use the
following order form (as you wish) and send it to:

P.D. van Dijk
Tulpstraat 6
8255BZ Swifterbant
HOLLAND

or drop me a line on Internet: [email protected]

PBEZ! orderform

Pieter, please send me:

The latest version of PBEZ!, (8086 and 386)
...........................[__] copies at $25 each $______

The latest version of PBEZ!, (8086 and 386)
including the Assembly Source Code (TASM 2+)
...........................[__] copies at $100 each $______ +

Postage & packing $ 5.00

TOTAL $______
I prefer [__] 5.25" [__] 3.5"


Send the disks to:

Name: _____________________________________________________________

Company (if company address): _____________________________________

Address: __________________________________________________________

__________________________________________________________

Country & State: __________________________________________________



Your E-mail address: ______________________________________

Payment by: [_] Eurocheque
[_] International Money Order
[_] Other, ___________________________________





PBEZ! version 2.0a page 35


Vanuit Nederland kan de nieuwste, geregistreerde versie van
PBEZ! worden bestelt door overmaking van 40 gulden op
bankrekening nummer:
49.45.17.018
t.n.v. P.D. van Dijk
te Naaldwijk
onder vermelding van PBEZ!

Vergeet niet PBEZ! te vermelden op de overboeking!

Giro-rekening gebruikers dienen 40 gulden over te maken op
girorekening 3016 (tnv ABN-AMRO) alweer onder vermelding van:

bankrekening nummer 49.45.17.018
t.n.v. P.D. van Dijk
te Naaldwijk
onder vermelding van PBEZ!

U kunt ook de Assembly sourcecode ontvangen, dit echter tegen
betaling van 175 gulden.





 December 5, 2017  Add comments

Leave a Reply