TOOLBZ.SBR
An Enhanced Replacement for TOOLBX.SBR
By
James A. Jarboe IV
Most ESP xcalls (SBR's) are relatively small. They make extensive use of
TOOLBX.SYS calls and therefore are usually only involved in the task of
getting the arguments from the BASIC program, passing the call to
TOOLBX.SYS and returning the results back to the BASIC program.
When DMSI managed ESP and TOOLBX.SYS there was a concern with the growing
number of ESP related xcalls (SBR's). To circumvent this and other
concerns, such as adding more features for BASIC program users, TOOLBX.SBR
was created. TOOLBX.SBR was one XCALL (SBR) with many offsets that could
perform different functions.
As more and more users were utilizing the power of ESP, more and more
features were wanted. Most features that BASIC program users want, were
already available in TOOLBX.SYS but were normally only accessible from an
assembly language program using the TBX$????? calls.
The basic subroutine, TOOLBX.SBR helped overcome this restriction to
TOOLBX.SYS from a BASIC program. TOOLBX.SBR gave BASIC programs access to
some essential TOOLBX calls enabling the user to perform special ESP
functions from BASIC and enhance the performance of ESP screens in BASIC
programs.
The TOOLBZ.SBR basic subroutine (XCALL) provided on the AMUS Network is an
enhanced and expanded version of TOOLBX.SBR that is currently released with
ESP from Alpha Micro. It is 100% compatible with the three (3) current
calls that Alpha Micro provides in TOOLBX.SBR, 100% compatible with the
four (4) additional calls that was distributed from DMSI, and provides four
(4) more new calls for a total of eleven (11) calls within one XCALL to
TOOLBX.SYS from a Basic program.
Since the calling format is essentially the same for all calls, only
requiring different TBX$????? calls for particular functions, the current
size of TOOLBZ.SBR is only 946 bytes and fits in 2 disk blocks. Not bad for
eleven (11) xcalls.
With the current release of ESP from Alpha Micro, the TOOLBX.SBR basic
subroutine includes only three (3) offset calls. That version of the
TOOLBX.SBR subroutine gives basic programs accessibility to a few of the
TOOLBX.SYS calls. Those include the following:
TBX'FLDCNT - Get ESP screen's Field count.
TBX'GETOLH - Get a Field's on-line-help text.
TBX'SQFLSZ - Get Sequential file size in bytes.
In one of the last DMSI releases of ESP, the TOOLBX.SBR included access to
a few more TOOLBX.SYS calls. The three above and the following.
TBX'HIDFLD - Set a Field as HIDE or SHOW.
TBX'SKPFLD - Set a Field as SKIP or ALLOW.
TBX'SELFLD - Set a Field as SELECT or DESELECT mode.
TBX'GETFLUF - Get a Field's user Flags.
The TOOLBZ.SBR subroutine, provided on the AMUS Network includes and is
compatible with all of the above TOOLBX.SYS calls plus gives you the
following additional calls:
TBX'GETPUI - Get a Field's Popup item value.
TBX'SETPUI - Set a Field's Popup item value.
TBX'GETFID - Get a Field number using Field's Permanent ID number.
TBX'GETFPN - Get a Field Permanent ID number using Field number.
One of the drawbacks of TOOLBX.SBR distributed with ESP from Alpha Micro,
and the TOOLBX.SBR that was distributed from DMSI is lack of adequate
documentation.
While the following is not an extensive comprehensive documentation, it
should provide enough information to successfully incorporate the usage of
TOOLBZ.SBR into basic programs.
The TOOLBZ.SBR can be renamed or copied to the file name TOOLBX.SBR if you
so desire, and not loose any functionability with the currently released
version of TOOLBX.SBR.
Also, the BASIC include file, TOOLBZ.BSI is on the AMUS Network. This
include file contains the relative offset call values that are used to
access or call the various functions in TOOLBZ.SBR. The include file
TOOLBZ.BSI also includes information for field flags, and provides flag
values for the undocumented additional argument for the GTSCR.SBR xcall
routine.
The field usage flags that are used with the additional argument field in
GTSCR.SBR is not a new enhancement. The additional argument field has been
available with GTSCR.SBR for years. Only the documentation and flag values
have been lacking. See TOOLBZ.BSI, available on the AMUS Network, for
additional information about GTSCR.SBR.
The basic include file TOOLBZ.BSI can be renamed or copied to the file name
TOOLBX.BSI and still be compatible with the TOOLBX.BSI released with ESP
from Alpha Micro.
The TOOLBZ.SBR is one xcall with a number of offsets that perform the
desired function. The calling format in a basic program for all desired
functions is as follows:
XCALL TOOLBZ, OFFSET, ARGUMENT, ARGUMENT, ARGUMENT
Where:
OFFSET = The desired function offset value as defined in TOOLBZ.BSI.
ARGUMENT = The required argument as needed for the particular call.
Following are the calling formats and functions available in TOOLBZ.SBR.
TBX'FLDCNT - Get an ESP Screen's Field count.
This call will return the number of fields that are in an ESP screen.
The ESP Screen must have been previously loaded using the xcall
FETCH.SBR.
Usage: xcall TOOLBZ, TBX'FLDCNT, SCREEN, FLDCNT
Where:
TBX'FLDCNT - Numeric value defined in TOOLBZ.BSI to process the
TBX'FLDCNT call.
SCREEN - The ESP Screen buffer to access.
FLDCNT - Numeric value of the number of fields of the
requested ESP SCREEN is returned to.
TBX'GETOLH - Returns an ESP Screen's field on-line help text.
This call will return the on-line text that is associated with the
designated field. The ESP Screen must have been previously loaded using
the xcall FETCH.SBR.
Usage: xcall TOOLBZ, TBX'GETOLH, SCREEN, FIELD, OLHTEXT$
Where:
TBX'GETOLH - Numeric value defined in TOOLBZ.BSI to process the
TBX'GETOLH call.
SCREEN - The ESP Screen buffer to access.
FIELD - The Field number to get the on-line help text
from.
OLHTEXT$ - String variable that the requested field's on-line
help text is returned to.
TBX'SQFLSZ - Returns the size of a sequential file.
This call will return the size in bytes of a designated sequential
file. Most often this call is used to find the size of an ESP screen to
see if it will fit into the designated buffer before loading the ESP
screen into the variable buffer using the FETCH.SBR xcall.
It can also be used to find the size in bytes of any sequential file.
Usage: xcall TOOLBZ, TBX'SQFLSZ, FILE$, FSIZE
Where:
TBX'SQFLSZ - Numeric value defined in TOOLBZ.BSI to process the
TBX'SQFLSZ call.
FILE$ - String name of the file to return the size of.
FSIZE - Numeric field that the size of the sequential file
is returned to.
TBX'HIDFLD - HIDEs or SHOWs an ESP screen field.
This call will set the HIDE or SHOW status of a designated ESP screen
field. If the HIDE status is set then the designated field will be
hidden from view. If the SHOW status is set then a hidden field will be
shown. The ESP Screen must have been previously loaded using the xcall
FETCH.SBR.
Usage: xcall TOOLBX, TBX'HIDFLD, SCREEN, FIELD, FLAG
Where:
TBX'HIDFLD - Numeric value defined in TOOLBZ.BSI to process the
TBX'HIDFLD call.
SCREEN - The ESP Screen buffer to access.
FIELD - Numeric value that designates which field to
HIDE or SHOW.
FLAG - Numeric value to set to decide if this is to force
a HIDE or SHOW function.
HIDE = -1 or TRUE
SHOW = 0 or NOT(TRUE)
TBX'SKPFLD - SKIPs or ALLOWs an ESP screen field.
This call will set the SKIP or ALLOW status of a designated ESP screen
field. If the SKIP status is set then the designated field will not be
allowed to be entered into. If the ALLOW status is set then a
previously SKIPped field will be ALLOWed to be entered into. The ESP
Screen must have been previously loaded using the xcall FETCH.SBR.
Usage: xcall TOOLBX, TBX'SKPFLD, SCREEN, FIELD, FLAG
Where:
TBX'SKPFLD - Numeric value defined in TOOLBZ.BSI to process the
TBX'SKPFLD call.
SCREEN - The ESP Screen buffer to access.
FIELD - Numeric value that designates which field to SKIP
or ALLOW.
FLAG - Numeric value to set to decide if this is to force
a SKIP or ALLOW function.
SKIP = -1 or TRUE
ALLOW = 0 or NOT(TRUE)
TBX'SELFLD - Sets the Select or Deselect value for an ESP screen field.
This call will set the SELECT or DESELECT status of a designated ESP
screen field. If the SELECT status is set then the designated field
will be marked as SELECTed (bright display). If the DESELECT status is
set then the field will be DESELECted (dim display). The best way to
describe this feature is to relate it to how selections are made in
SEDIT. When editing a field in SEDIT and you are trying to figure the
settings of say the "Field flags:", it is possible to Press the F9
function key that presents a window of possible field flag values to
select from. The bright fields have the SELECT status set while the dim
fields have the DESELECT status set. Pressing the SPACE bar will SELECT
a Deselected field and DESELECT a selected field. This call presets the
SELECT or DESELECT status before entering a selection screen. The
information of whether a field has been selected or deselected can be
obtained via the TBX'GETFLUF call. The ESP Screen must have been
previously loaded using the xcall FETCH.SBR.
Usage: xcall TOOLBX, TBX'SELFLD, SCREEN, FIELD, FLAG
Where:
TBX'SELFLD - Numeric value defined in TOOLBZ.BSI to process the
TBX'SELFLD call.
SCREEN - The ESP Screen buffer to access.
FIELD - Numeric value that designates which field to SELECT
or DESELECT.
FLAG - Numeric value to set to designated the field's
SELECT or DESELECT Status.
TBX'GETFLUF - Gets a field's user flag values.
This call will return the current field usage flags. This call will
return whether a field has status of HIDDEN, SKIPPED, or SELECTED. This
call can return will return a single value or a logical sum of the
current usage status of the designated field. The ESP Screen must have
been previously loaded using the xcall FETCH.SBR.
Usage: xcall TOOLBX, TBX'GETFLUF, SCREEN, FIELD, FLAGS
Where:
TBX'SELFLD - Numeric value defined in TOOLBZ.BSI to process the
TBX'SELFLD call.
SCREEN - The ESP Screen buffer to access.
FIELD - Numeric value that designates which field to get
the Field User Flags from.
FLAG - Returned Numeric value that designated the field's
user status. Can be one of or a logical sum of the
following values:
FLUF'HIDE = 1
FLUF'SKIP = 2
FLUF'SELECT = 4
TBX'GETPUI - Gets an ESP screen's field POPUP item value.
This call will get the current POPUP Item value of a designated field.
No matter what text is associated with a POPUP item, the value of the
first selection on the POP-up MENU selection is one, the second is two,
the third is three and so on. This call will return the current POPUP
item value. The ESP Screen must have been previously loaded using the
xcall FETCH.SBR.
Usage: xcall TOOLBX, TBX'GETPUI, SCREEN, FIELD, VALUE
Where:
TBX'GETPUI - Numeric value defined in TOOLBZ.BSI to process the
TBX'GETPUI call.
SCREEN - The ESP Screen buffer to access.
FIELD - Numeric value that designates which field to get
the POPUP item value.
VALUE - Numeric value of the designated field's current
POPUP item.
TBX'SETPUI - Sets an ESP screen's field POPUP item value.
This call will set a POPUP Item value to a designated field. No matter
what text is associated with a POPUP item the value of the first
selection on the POP-up MENU selection is one, the second is two, the
third is three and so on. This call can set the current POPUP item
value so that the desired POP-UP text can be preset. The ESP Screen
must have been previously loaded using the xcall FETCH.SBR.
Usage: xcall TOOLBX, TBX'SETPUI, SCREEN, FIELD, VALUE
Where:
TBX'SETPUI - Numeric value defined in TOOLBZ.BSI to process the
TBX'SETPUI call.
SCREEN - The ESP Screen buffer to access.
FIELD - Numeric value that designates which field to set
the POPUP item value.
VALUE - Numeric value to set the POPUP item value of the
designated field.
TBX'GETFID - Gets a field number as referenced by the fields Permanent ID
number.
This call will return the current FIELD NUMBER by accessing the field's
PERMANENT ID NUMBER. Each ESP field is assigned a PERMANENT ID number
when it is created. This PERMANENT ID number is not modified until the
field is deleted. The PERMANENT ID number is not to be confused with
the ESP screen's field number. The field number is usually referred to
as the entry sequence number. The PERMANENT ID can be displayed in
SEDIT by setting the USRIMP READ SECURITY flag to 254. The PERMANENT ID
number is displayed to the right of the Field number in SEDIT or the
listing of an ESP screen that SEDIT creates with the /L option. The ESP
Screen must have been previously loaded using the xcall FETCH.SBR.
Usage: xcall TOOLBX, TBX'GETFID, SCREEN, FLDID, FLDNUM
Where:
TBX'GETFID - Numeric value defined in TOOLBZ.BSI to process the
TBX'GETFID call.
SCREEN - The ESP Screen buffer to access.
FLDID - Numeric value that contains the Permanent Field ID
number that is to be accessed.
FLDNUM - Returned Numeric value containing the Field number
of the requested Permanent Field ID.
TBX'GETFPN - Gets an ESP screen's field's Permanent ID number as
referenced by the field's Field Number.
This call will return the permanent ID number of an ESP field by
accessing the field's FIELD NUMBER. The FIELD NUMBER is not to be
confused with the field's PERMANENT ID NUMBER. Each ESP field is
assigned a permanent ID number when it is created. This permanent ID
number is not modified until the field is deleted. An ESP Screen's
FIELD NUMBER is usually referred to as the entry sequence number. The
permanent ID can be displayed in SEDIT by setting the USRIMP READ
SECURITY flag to 254. The Permanent ID number is displayed to the right
of the Field number in SEDIT or the listing of an ESP screen that SEDIT
creates with the /L option. The ESP Screen must have been previously
loaded using the xcall FETCH.SBR.
Usage: xcall TOOLBX, TBX'GETFPN, SCREEN, FLDNUM, FLDID
Where:
TBX'GETFPN - Numeric value defined in TOOLBZ.BSI to process the
TBX'GETFPN call.
SCREEN - The ESP Screen buffer to access.
FLDNUM - Numeric value that contains the Field number that
is to be accessed.
FLDID - Returned Numeric value containing the Permanent
Field ID number of the requested field.
Also available on the AMUS Network is SCROLL.BAS and SELFLD.BAS which gives
specific examples of how to utilize some of the neat features available in
TOOLBZ.SBR. Call up the AMUS Network and get your copy today!