HandTools 2.0 Release Notes - 03-30-98 

Oops! We left this out of the manual! 

Integer := CreateRunProcMacro(MacroName, HotKey, ProcedureToRun, Trigger)

Explanation This function creates a keyboard macro that will automatically fire off a procedure from record entry when the hot key is pressed. MacroName uniquely identifies the macro. Hotkey is the keycode of the keystroke that will fire the macro (use ParseKey to get this value). ProcedureToRun is the name of a DQL procedure to run. The macro created may be saved to disk, along with any other macros in effect, with SaveMacros. Example To create a macro called 'PrintInvoice' that will print an invoice by running the procedure 'Invoice Print' any time the F12 function key is pressed while in this record entry screen, create a virtual field with the following derivation formula: CreateMacro("PrintInvoice",ParseKey("F12"),"Invoice Print","") SEE THE 'Invoice' form in HandTools' database for an extensive example of this and other macros in action. The form and field help for this form, the Invoice Lines form, as well as comments contained in the Invoice Print procedure (and data-entry form) contain in-depth descriptions of the theory of operation of the macro facility. 

Bonus Programs 

One of the most overlooked, yet, when someone finds them, most praised features included in HandTools are the bonus programs ASK.EXE and BROWSE.EXE. ASK is a derivative of the 'PromptUser' CDF function. It allows you to embed intelligent prompts in batch files. The user's response to a prompt is usually saved to a DOS environment variable where it can be tested during execution of the batch file. ASK is really sophisticated and can add a lot of value to a system. 

BROWSE.EXE is simply a standalone version of the BrowseFile CDF function and can be used to view any ASCII text file. The bonus functions are discussed in the appendix of the manual. 

255-Function Limit in system Custom Functions

Note that even though all the collective CDF libaries you may be using can supply as many individual functions as you wish, only 255 can be defined at any one time in a given database. That is, the system Custom Functions form in the database should never contain more than 255 records. It will cause very weird behavior if it does, including crashes (version 4.5x). 

Where Stuff Is

There has been considerable shuffling of functions out of CORECDF. Most significantly, keyboard functions such as StuffKBKeycode have been moved to MACROCDF.EXE and bitwise operators for digitheads have been moved to a library named BITSCDF.EXE. HTCDF.EXE has everything in it. Use this unless you can confine your needs to a single subset library and need to conserve memory usage. DE45SYS functions ONLY work with version 4.53 databases. 

Installing HandTools in Other Applications 

HTCDF.MAS (included on the disk) is a DataEase Custom Functions master file that contains the appropriate entries for the entire HandTools 2.0 suite. You should install these definitions into your system Custom Functions form. We suggest installing the form CDFSFORM.DBS as a user form and naming the supplied HTCDF.MAS as the data file. This will insure that you have a virgin copy of the CDF master library installed in your database in a place other than the system Custom Functions form. Each of the subset libraries has its own .MAS file describing each of its functions. 

Faxing 

Note that the FaxPCLFile function REQUIRES that you specify the location of a directory containing (at least) the supplied *.FNT files (included on the install image). FNT files are simply Hewlett-Packard bitmapped (not True Type or scalables!) fonts. The supplied fonts should be sufficient for general purpose faxing, but you can add more downloadable fonts if you wish. Just make sure their extension is *.FNT as FaxPCLFile simply registers any *.FNT file found in the specified directory. Also, don't go overboard, as memory can be exhausted. The fax engine is VERY sensitive to parameter errors such as baud rate. Be sure to choose the correct rate for your modem (14,400 is correct for a 14,400/9,600 data/fax modem).

Building/Modifying Imports on the fly 

One of DataEase' biggest weaknesses is the inability to modify import parameters without user intervention. Many times the name of the import file is not known until run time. Now you have the power to create new or modify existing import definitions at run time. 

Be sure to check out 

Make sure you check out the macros of the Invoice record entry form. This is really cool. I know a lot of people have wanted the ability to run an invoice printer straight from record entry. This not only shows how, it also shows how you can automatically keep those summary virtual fields that rely on values contained in the sub-form records properly updated! 

HTUnique, our implementation of the popular UNIQUE number generator for multiuser primary keys is also demonstrated in the Invoice Form. 

Undeleting all deleted records in a form. 

This can be very useful for recovering from corrupted databases. Make sure you reorganize after using this procedure. 

The BuildMacro procedure implements a crude, but effective interactive macro builder. If there is enough demand, we will provide a full-blown interactive macro editor. Let us know. Be sure to examine ALL of the example DQL procedures and forms for ideas about how to best make use of HandTools. 

Odds and Ends

The print re-direction functions (of PRINTCDF) are considerable faster in this release than in past releases. The sky really is the limit with the functions of DE45SYS. This is good and DANGEROUS. Please be careful and keep a number of good backups! 

The Various Libraries Included and Memory Requirements

By default, HTCDF.EXE, which contains the entire HandTools suite, is installed for you by SETUP.EXE. In addition, we have provided seven other libraries, each of which contains a sub-set of the full HandTools repertoire. The general rule of thumb is to always use HTCDF.EXE unless, and only if, the functionality your application will require in any given form or procedure 'session' can be confined to only those functions found in one of the subset libraries AND you have a genuine need to conserve DOS memory. 

Memory used by a CDF under DOS is only used by that CDF library during its usage by DataEase. When the procedure or form which invoked the CDF library execution ends and returns to a menu, the library is unloaded from memory. CDFs use DOS, or conventional, memory. This is the amount of memory reported by the DOS MEM command as the 'Largest Exectuable Program Size' . There is a DataEase bug when DataEase is running in Windows DOS box that prevents a CDF from unloading once it has been loaded. For this reason, we recommend using CDF applications ONLY under pure DOS. HTCDF is by far the most voracious consumer of memory when compared to any other SINGLE CDF library in the suite (HTCDF requires at least 445,568 bytes and will grab up to 629,568 bytes if it finds that much available). However, it delivers all of the functionality of the other seven file, combined. Pay close attention to the RESERVELOW setting in your VMC file. DO YOU HAVE A VMC FILE DEFINED? If not, see HT.VMC shipped with the demo and HTDEMO.BAT for a guide to setting one up. You want to set RESERVELOW to as high a number as you can and still have DE16M start up. This will provide the most memory possible to your CDF library, while it is loaded. When the CDF is not in use, this memory will be available for external program calls, etc. 

Each Library's Memory Needs  

Each library has a minimum memory requirement. In addition, each library will grab as much memory as it can above this minimum value, up to a preset maximum. The minimum requirement and maximum memory used figures for the various HandTools EXE files appears below: 

What this means that HTCDF.EXE can be loaded in as little as 445,628 bytes of executable program memory, but, if it finds more available when it is loaded, it will use it, up to 629,568 bytes worth. Consider a scenario where MEM reports (after DataEase is loaded) available executable program memory of 500,000 bytes. Say an application only needed functions found in CORECDF.EXE and DOSCDF.EXE and was not using any of the other libraries. Many would make the innocent mistake of presuming that they would save memory by installing CORECDF.EXE and DOSCDF.EXE and deleting references to all other functions because CORECDF.EXE's minimum requirement (117,376) plus DOSCDF.EXE's minimum requirement (217,056) is less than (393,432) HTCDF.EXE's minimum requirement. WRONG! If a CORECDF function is referred to first, then CORECDF.EXE will be loaded first by DataEase. When CORECDF.EXE loads, it finds 500,000 bytes free and helps itself to 405,264 bytes, not 117,376 bytes, leaving only a little over 94,000 bytes remaining. When DOSCDF is subsequently requested, there is not enough memory for it to load and you get an error message. This is why we recommend using HTCDF.EXE in most cases. It simplifies things greatly and provides the most flexibility. Now, if you have an application that relies exclusively on the functions of say, MACROCDF.EXE, then, by all means, install only this library and delete the references to the other HandTools CDF functions from the custom functions form and change the remaining functions' library name field to point to MACROCDF.EXE. This will save you at least 264,000 bytes of memory over using HTCDF.EXE. And remember, we offer custom compiles for special needs!