Using CDFs
In the last article ( What are CDFs?), I introduced you to
DataEase' Custom Defined Function (CDF) capability and described some of the more general
fundamental concepts involved in employing CDFs in an application. In this article we are
going to look at an actual CDF library implementation and show some example CDFs that you
may find useful to your application development efforts.
Installing a CDF Library
In order to take advantage of the power and utility of a CDF library, you must first
successfully install the library. Most commercial CDF packages should provide a turnkey
installation program that automates the install process for you. However, I will briefly
cover some of the details so that you will better understand CDF implementation.
Custom Functions
No record on screen
CUSTOM DEFINED FUNCTIONS - DESCRIPTION TEMPLATE
Function Name: OS Type:
Description:
CDF Library Name:
Memory Requirement: Entry Point: Return Type:
Parameter Name: Type:
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
F4CMDHELP ESCEXIT F2SAVE SH-F1TABLE F3VIEW F7DEL F8MODIFY F9QBE F10MULTI
|
(Figure 1 - CDF Descriptor Record)
CDF libraries for DOS are provided in the form of standard executable program (EXE)
files. CDF libraries for Express and the OS/2 version of DataEase are provided as
Dynamic-Link Libraries (DLL). Our discussion will center on the DOS platform, since it is
believed that DOS is the dominant platform for DataEase installations.
The main difference between a CDF program and a standard executable program is that a
CDF is never meant to be executed stand-alone, but is designed to be loaded, executed, and
unloaded by DataEase. Moreover, the bulk of the CDF 'program' never executes at all on its
own, but is called when one of its functions is requested in a field derivation formula or
a DQL statement.
In order to interface to the external CDF program, DataEase must be provided some
detailed information about the CDF library and each function it provides. This information
is provided by entering records into the Custom Functions (See Figure 1) file which may be
accessed through the System Administration menu.
Each CDF function used in a database must be described with a record in the Custom
Functions file. The record describes the function's name, operating system platform, the
name of the DOS file containing the CDF, how much memory is required by the library and,
optionally, the memory address of the function. In addition, the data type of the value
returned by the function as well as the data types of each of the function's input
parameters are also required.
Custom Functions
No record on screen
CUSTOM DEFINED FUNCTIONS - DESCRIPTION TEMPLATE
Function Name: FillLeft OS Type: DOS
Description: Right-Justifies Text
CDF Library Name: C:\HANDTOOL\CORECDF.EXE
Memory Requirement: 77,000 Entry Point: 10:988A Return Type: String
Parameter Name: Type:
1. Source Text String
2. Pad Character String
3. Total Length Integer
4. Nested Function String
5.
6.
7.
8.
9.
10.
F4CMDHELP ESCEXIT F2SAVE SH-F1TABLE F3VIEW F7DEL F8MODIFY F9QBE F10MULTI
|
(Figure 2 - Completed CDF Descriptor Record)
Some fields describe the library in which the function resides and others describe the
function itself (Codd wouldn't like it at all). Uniqueness is determined by the Function
Name and the OS Type fields.
It is extremely important for the descriptive information to be recorded with precise
accuracy. If a data type is incorrectly defined the application, at best, will receive
erroneous results from the function and could very well lock up when the function is
called. It is for this reason that commercial CDF packages should supply installation
software that populates the Custom Functions accurately and automatically.
Figure 2 illustrates a properly completed CDF descriptor record. The record shown
describes the FillLeft function supplied with the HandTools CDF library. FillLeft is a function that will return a string
that right-justifies Source Text within a new string that is Total Length long, with space
to the left of Source Text being filled with a the character specified by Pad Character,
thus:
FillLeft("$1,200.00 Blow","*",20,"") .
Returns a text string:
"***********$1,200.00"
Note that each database maintains its own Custom Functions file, so if you have
multiple databases with which you wish to use the same CDFs, you will need to repeat the
installation process once for each one.
In addition to describing each CDF in the Custom Functions file, you must also insure
that enough memory is available for DataEase to load the CDF program file. As stated in
the previous article, it is probably not wise to attempt to use CDFs with the 640k version
(DEASE.EXE) of DataEase, as it does not leave enough memory available for loading most CDF
libraries. In the protected-mode version of DataEase (DE16M.EXE) it is possible to make
all but about 100k of low memory (the value shown for 'Largest executable program size' by
the MEM utility) available for use by CDFs, since DataEase is loaded mostly into extended
memory. (CDFs must be loaded into low memory). To insure that you will have enough memory
to load the CDF file, you should create (or modify) a VMC file and set the RESERVELOW
parameter in the VMC file to the sum total memory required by all of the CDF libraries you
intend to use simultaneously. Again, an automated CDF installation facility provided by
the library author can help greatly with this.
Using CDF Functions
Once the Custom Functions form has been properly populated with CDF entries, you are
ready to begin employing the CDF library in your forms and procedures. The great thing
about CDF functions is that they may be used in a field derivation formula or report
procedure in exactly the same fashion as any of native DataEase' fifty six standard
functions.
This means that anywhere you can use standard DataEase functions such as Proper or
Upper or JoinText, you may also use a CDF function. In fact, when you are using High-Level
interactive mode in the DQL editor, DataEase provides a menu of available CDF functions in
the same way it does its internal functions. What could be more elegant, powerful, or
simple?
A Simple Field Derivation Example
As an example, the HandTools CDF library from LANimation Software provides a function
called CRTWriteAttr for displaying messages
on the screen in any color, for a definable length of time. Such a function might be
useful when you want to display a warning notice in response to data being entered into a
form or to provide visually appealing 'progress gauge' controls that indicates the
percent-complete status of a lengthy procedure.
Assume that you are designing a classic order entry system. New orders will be entered
in a master form-subform (OrderHeader-OrderLines) data entry screen. As each OrderLine is
entered into the sub-form, a lookup to an InventoryMaster record is performed which
retrieves each item's unit price, description, etc based on the item's part number. The
InventoryMaster record also contains a StockOnHand field that contains the current number
of item's available for shipment.
If someone enters an order that requests more units of an item than is presently on
hand you want the system to alert the user with a message to the effect 'WARNING: Order
quantity exceeds stock level'. Further, assume that the behavior you desire is to display
the message right in the middle of the screen and you want it to blink on and off AND you
want to display it for three seconds and then allow entry to continue.
Using native DataEase such behavior is not possible. You cannot output messages on the
screen at any location you want for a pre-determined length of time and then remove the
message and restore the underlying screen to it's original state. You can approximate the
desired behavior with clever composition of a field derivation that supplies the desired
message based on the condition, but such a solution will appear at a fixed screen
location, occupy space you might need for entry fields, appears in limited colors and only
disappears when the condition causing the derivation is eliminated.
Using HandTools' CRTWriteAttr we can
easily generate the desired behavior. To make this work we would add a hidden, virtual
field to the OrderLines definition that uses the following field derivation formula:
If(OrderQty > Lookup "InventoryMaster" "StockOnHand",
CRTWriteAttr(12,20,Color(12,15),"WARNING: Order quantity exceeds stock level", 3000, ""),
Blank )
Now, when an OrderLine record is entered and an OrderQty value is input that exceeds
available inventory the warning message will be displayed at screen row 12, screen column
20, in blinking white on red (Color(12,15)) for
3000 milliseconds or 3 seconds. After the message is displayed for 3 seconds it is erased
and the underlying screen is restored.
A Simple DQL Example
CDFs make it possible to obtain environmental information that was not previously
possible with native DataEase. For example, HandTools includes functions for searching for
DOS files, for determining the size, capacity and available space of a system's disk
drives, etc.
This information can be very valuable in preventing problems and controlling processes.
Assume that you have an end-of-day process that among other things, produces several disk
based report images that are to be e-mailed automatically to your branch offices. This
process runs, unattended, at night as part of a large, complex batch process. If the
process halts for any reason, the interruption will not be discovered until the next day,
plus the restart effort will be considerable, aggravating the problem.
In this scenario, one potential process abnormal end that you would probably like to
guard against is exhaustion of disk space. Since you are capturing a number of report
images to disk, it is likely that your procedure could exhaust free disk space, causing
the whole process to shut down. For each of your procedures you have come up with a
formula for approximating the number of bytes of disk that will be consumed by the report
image. Now you need a control mechanism that will check the free space and execute the
procedure only if it can be run safely.
Again, Handtools provides a function called GetDiskFree
that returns the amount (in bytes) of free space remaining on a disk drive. By adding the
following lines to each DQL procedure in the end-of-day process, we can check for enough
available space before running the procedure and abort the procedure if the amount
available is below the limit.
define "FreeSpace" number . assign temp
FreeSpace := GetDiskFree("C:","") .
If FreeSpace < MinimumSpaceNeeded then Enter a record in ProcessLog EventDate :=
current date ; EventTime := current time ; EventDesc := "Daily Sales Report aborted.
Insufficient Free Disk Space." . Exit . end .
A Progress Gauge
Progress meters are very appealing and useful, particularly in long-running procedures.
They indicate to the user that, indeed, the computer is still functioning as programmed.
You can achieve a semblance of progress reporting using native DataEase 'message'
statement. You can provide a professional looking bar meter with a CDF function.
Here, we will use the CRTWriteAttr and FillLeft functions together to perform this
feat. First, we will define some temporary variables to hold the total number of records
to process and the current count of records processed so far.
define "Total Recs" number .
define "Rec Count" number .
Then, initialize these variables. Total Recs holds the total number of records to be
printed. Rec Count will be incremented once for each record as the report processes:
Total Recs
:= Count of Inventory with ( Sold =no ).
Rec Count := 0 .
Then, write a cyan bar, 40 columns wide, on the screen:
Junk := CRTWriteAttr(
16, 20, Color(3,1),FillLeft(""," ",40,""),0,"") .
Now Process the records
for Inventory with Sold = no ;
Rec Count := Rec Count + 1 .
list records
Room in groups with group-totals ;
ID ;
Description ;
Serial # ;
Cost ;
Price : item sum ;
current date ;
current time ;
current page number .
For each record write a blue bar 'on top' of the cyan that indicates the percentage
complete. The length of the bar is determined by the '40*(Rec Count / Total Recs)'
calculation.
Junk := CRTWriteAttr(
16, 20, Color(1,7),FillLeft(""," ",40*(Rec Count / Total Recs),""),0) .
The effect of this is a 40-column-wide bar meter which appears on screen at row 16,
column 20 on the screen. Initially the bar is completely cyan. As the report progresses,
the cyan bar will begin to turn blue from left to right, indicating the percentage of
total records processed by the report.
Price List Running procedure Price List
Price List Report -
You may choose to print this report to the printer, the screen, or to a
file.
Where would you like the report to print ? DOS File
Enter a DOS filename to print to -
C:\HTD\PRCLIST.PRN
Press 'F2' when ready to print, 'Esc' to abort
€€€€€€€€€€€€€€€€
31%
F4CMDHELP ESCEXIT F2SAVE F5CLEAR FORM F6CLEAR FIELD 6:34 pm
|
(Figure 3 - The Progress Meter)
Where to from here?
With the advent and acceptance of CDFs by the DataEase community, DataEase can now, for
the first time, be considered a serious contender for all types of application
development. Those familiar with the XBase development platform will quickly affirm that
the popularity of that platform has as much to do with the broad availability of
third-party development-tool add-in products as it does with the qualities of Foxpro,
dBase, Clipper or other XBase core products. Now DataEase can count itself among these in
terms of flexibility and depth. Given that DataEase has always had a leg up on them from a
productivity and ease-of-use standpoint, this is good news indeed.
In this installment, I have only scratched the surface as far as what is available to
you in terms of CDF toolkits. HandTools CDF library contains
over 220 functions. From items as mundane as right-justifying text to dialing the
telephone.
|