Language Enhancements in VFP 7, Part 1

Article
06/30/2006

This article may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist. To maintain the flow of the article, we’ve left these URLs in the text, but disabled the links.

Visual FoxPro 6 Language Reference Book on Archive.Org

Language Enhancements in VFP 7, Part 1

Doug Hennig

Want an early peek at what’s new in VFP 7? This is the first article in a series where Doug Hennig discusses the language enhancements Microsoft is implementing and how to take advantage of some of them now.

In my article in the December 2000 issue of FoxTalk (“Reusable Tools: Have Your Cake and Eat it, Too”), I discussed “version envy”: wanting to use features planned in an upcoming version of a product in the current version. In that article, I discussed several new functions in VFP 7 and showed PRGs that can provide their functionality in VFP 6. After reading this article, FoxTalk editor Whil Hentzen thought it would be a great idea to extend this to covering all of the new commands and functions in VFP 7, both to familiarize you with them and to enable you, where possible, to use them in VFP 6.

So, we’ll start the new year off with this idea and spend several months looking at language enhancements in VFP 7. We won’t look at everything that’s new in VFP 7 (such as IntelliSense, editor improvements, DBC events, and so forth); it would take a whole book to cover such a broad topic. Instead, we’ll focus on functions and commands with three things in mind:

We’ll briefly consider the purpose of each command and function without getting too bogged down in details (for example, I won’t discuss parameters or return values in detail; you can get that from the VFP 7 Help).
We’ll look at practical uses for the commands and functions.
Where possible, we’ll explore ways to get the functionality now in VFP 6.

Keep in mind that, as of this writing, VFP 7 isn’t even in beta yet (it’s considered a Tech Preview version), and these articles are based on the version distributed at DevCon in September 2000. So, commands and functions might be added, removed, or altered.

Let’s start off with improvements to existing commands and functions, going through them in alphabetical order. Once we’re finished with these, we’ll move on to new commands and functions.

ALINES()

ALINES() has been a favorite function of mine since it was introduced. It parses a string (which may be in a variable or memo field) into lines terminated with a carriage return (CR), linefeed (LF), or carriage return-linefeed combination (CRLF) and puts each line into its own element in an array. ALINES() can now accept one or more parse characters, so the “lines” can be delimited with something other than CR and LF. For example, a comma-delimited field list can easily be converted to an array. Why would you want to do this? Because it’s easier to process an array than a comma-delimited string. Here’s a brute-force way of processing the items in such a string:

This is ugly code to both read and write. Here’s a more elegant approach that converts commas to CR, then uses ALINES():

In VFP 7, the first two lines in this code can be reduced to the following:

AMEMBERS()

This is one of those functions you likely don’t use very often, but it’s very useful at those times when you need it. AMEMBERS() fills an array with the properties, events, and methods (PEMs) of an object or class. There are two changes to AMEMBERS() in VFP 7: You can now get the PEMs of a COM object, and you can specify a filter for the PEMs.

Passing 3 for the third parameter indicates that the second parameter is a COM object. Here’s an example that puts the PEMs for Excel into laPEMs:

A new fourth parameter allows you to filter the list of PEMs so the array contains only a desired subset. For example, you might want only protected, hidden, or public PEMs, native or user-defined PEMs, changed PEMs, and so forth. This is handy, because prior to VFP 7, the only way to filter a list of PEMs was to use PEMSTATUS() on each one. For example, I use the following routine, CopyProperties, in VFP 6 to copy the properties of one object to another instance of the same class. Why would you want to do that? Imagine a form that you pass an object to and have the user modify the properties of the object in the form’s controls. What if the user wants to press a Cancel button to undo his or her changes? I decided to copy the object’s properties to another object of the same class, and then have the form work on the new object and, if the user chooses OK, copy the properties of the edited object to the original object. If the user chooses Cancel instead, the original object isn’t touched. So, the form creates another instance of the passed object’s class and then calls CopyProperties to copy the properties of the original object to the new instance. Here’s the code for CopyProperties (you’ll also find it in COPYPROPERTIES6.PRG in the accompanying Download file):

The VFP 7 version is a bit simpler. First, it uses the new “G” flag so the array only contains the public properties of the source object—we don’t have to use PEMSTATUS() to later ignore protected or hidden properties. Next, although there’s currently a bug that prevents it from working with array properties, we’ll be able to use the “C” flag so the array only contains properties that have changed from their default values; when this bug is fixed (notice that I’m being optimistic and didn’t say “if” <g>), we’ll be able to remove the PEMSTATUS() check for changed properties. Finally, I’ve submitted an enhancement request (ER) to Microsoft to provide a flag for read-write properties. If this ER is implemented, we’ll be able to remove the PEMSTATUS() check for read-only properties. Thus, the VFP 7 version will be simpler and faster than its VFP 6 counterpart. Here’s the code for COPYPROPERTIES7.PRG (I removed a few comments that duplicate those in the VFP 6 version in order to conserve space):

By the way, if you examine COPYPROPERTIES7.PRG, you’ll see that the header comments include my e-mail address and Web site, and that they appear blue and underlined, just like a hyperlink in your browser. Clicking on either of these gives the expected action (a Send Message dialog box with my e-mail address already filled in or my Web site in your browser). This editor enhancement makes it simple to direct other developers to your Web site for support, more information or documentation, updates, and so on.

TESTCOPYPROPERTIES.PRG shows how CopyProperties can be used. Change the statement calling CopyProperties6 to CopyProperties7 to see how the VFP 7 version works.

Here’s another use of AMEMBERS() that’s somewhat similar. PERSIST.PRG provides a way to persist the properties of an object so they can be restored at another time (for example, the next time the user runs the application). It creates a string that can be stored, for example, in a memo field in a table. This string contains code that can be used to restore the properties of an object. For example, the string might look like this:

After retrieving this string from wherever it’s stored, you’d then do something like this to restore the saved properties (in this example, lcPersist contains the string):

This example uses the new VFP 7 EXECSCRIPT() function, which I discussed last month.

I won’t show the code for PERSIST.PRG here, both because of space limitations and because it’s quite similar to COPYPROPERTIES7.PRG. To see this routine in action, run TESTPERSIST.PRG.

ASCAN()

Two things I’ve wished for a long time that Microsoft would add to ASCAN() are the ability to specify which column to search in and to optionally return the row rather than the element (to avoid having to subsequently call ASUBSCRIPT() to get the row). My wish was granted in VFP 7, plus ASCAN() gains the ability to be exact or case-insensitive. The new fifth parameter specifies the column to search in, and the new sixth parameter is a “flags” setting that determines whether the return value is the element or the row and whether the search is exact or case-insensitive.

Because I always want the row and never want the element number, normally want a case-insensitive but exact search, and have a difficult time remembering exactly which values to use for the flags (no wisecracks from younger readers <g>), I created ArrayScan, which accepts an array, the value to search for, the column number to search in (the default is column 1), and logical parameters to override the exact and case-insensitive settings. Here’s the code in ARRAYSCAN7.PRG (I omitted header comments and ASSERT statements for brevity):

In VFP 6, we can do something similar, but since we don’t have the new capabilities of ASCAN(), we have to use a different approach: We’ll use ASCAN() to find the value anywhere in the array, then determine whether it’s in the correct column. If not, we’ll change the starting element number and try again. ARRAYSCAN6.PRG has almost the same functionality as ARRAYSCAN7.PRG (although it’s slower and has more complex code), except support for case-insensitivity—to implement that feature, you’d have to do it via the brute-force method of going through each row in the array and looking for a case-insensitive match in the desired column. Here’s the code for ARRAYSCAN6.PRG:

TESTARRAYSCAN.PRG demonstrates how both ARRAYSCAN6.PRG and ARRAYSCAN7.PRG work.

ASORT()

VFP 7 adds one new feature to ASORT(): a case-insensitivity flag (in VFP 6, ASORT() is always case-sensitive).

BITOR(), BITXOR(), and BITAND()

These functions can now accept more than the two parameters they do in VFP 6; they’ll accept up to 26 parameters in VFP 7. This is useful in cases (such as some API functions and COM objects) where several flags have to be ORed together; in VFP 6, you have to use something like BITOR(BITOR(BITOR(expr1, expr2), expr3), expr4) to do this.

BROWSE

At long last, we get a NOCAPTION option for BROWSE that displays the actual field names rather than the captions defined for the fields in the database container. You can get this behavior in VFP 6 by running BROWSEIT.PRG instead of using BROWSE. This relies on the fact that a browse window is really a grid, so we can change the caption of each column to the actual field name. Here’s the code for BROWSEIT.PRG:

COMPILE

In VFP 7, the COMPILE commands (COMPILE, COMPILE CLASSLIB, COMPILE REPORT, and so forth) respect the setting of SET NOTIFY. With SET NOTIFY OFF, no “compiling” dialog box is displayed. This is important for two reasons: In-process COM servers

can’t display any user interface, and you likely don’t want your users to see such a dialog box. In VFP 6, we can suppress the dialog box by using the Windows API LockWindowUpdate function, which prevents updates to a window similar to VFP’s LockScreen property (although this won’t help in-process COM servers, since the dialog is still being called). The Download file includes LOCKWINDOW.PRG, which accepts .T. to prevent window updates and .F. to restore window updates. Here’s the code for this PRG:

To prevent the “compiling” dialog box from being displayed, use code similar to the following:

Conclusion

Next month, we’ll carry on examining improved commands and functions in VFP 7. When we’re finished with them, we’ll move on to new commands and functions.

To find out more about FoxTalk and Pinnacle Publishing, visit their website at http://www.pinpub.com/html/main.isx?sub=57

Note: This is not a Microsoft Corporation website. Microsoft is not responsible for its content.

This article is reproduced from the January 2001 issue of FoxTalk. Copyright 2001, by Pinnacle Publishing, Inc., unless otherwise noted. All rights are reserved. FoxTalk is an independently produced publication of Pinnacle Publishing, Inc. No part of this article may be used or reproduced in any fashion (except in brief quotations used in critical articles and reviews) without prior consent of Pinnacle Publishing, Inc. To contact Pinnacle Publishing, Inc., please call 1-800-493-4867 x4209.

Driving the Data Bus: Chatting on Company Time–Building a VFP Chat Module

Article
06/30/2006

Driving the Data Bus: Chatting on Company Time—Building a VFP Chat Module

Andrew Coates

Passing data to and from applications over the network makes the synchronization of data simple. In this article, Andrew Coates uses a messaging hub server to develop a chat component that can carry more than just typed conversations between application users.

The chat system allows users across the network to exchange data in real time. Most commonly, this data consists of typed conversations, but the power of the system lies in its ability to pass other data as well. This could be in the form of audio or video or, as will be presented here, other text data that will allow the two chatting parties to retrieve the same database record by sending a primary key or keys from one to the other.

The chat system

To allow chatting, each client registers itself with a chat server as it starts up. The chat server maintains a list of connected clients and can detect disconnections automatically. If a client goes offline either by choosing to disconnect or due to network or some other failure, the server removes that client from the list. A schematic representation of the setup is shown in Figure 1.

Each client consists of a chat handler, which sends and receives the messages, and zero or more chat forms. A chat conversation is carried out between chat forms, which are created specifically for that conversation and destroyed at the conclusion of the conversation. A client may be involved in many chats simultaneously, so to ensure that messages are routed to the correct form, the chat handler employs a concept of “chat slots” or a collection of instances of the chat form so they can handle multiple chats simultaneously and not get crossed lines. A schematic of the clients, the chat handlers, and the chat forms is shown in Figure 2.

In Figure 2, there are two conversations being conducted. Client 1 is talking to client 2 and client 3. Because client 3 addresses its messages to client 1, chat slot 2, they never get mixed up with messages from client 2, which are addressed to client 1, chat slot 1.

Initiating a chat

To establish a conversation between two clients, one of the clients needs to initiate the chat. The initiating client sends a request to the intended recipient, and the recipient either accepts or declines the invitation to chat.

The process from the chat initiator’s point of view is shown in Figure 3.

When a client decides to start a chat, it creates a chat form and assigns the form a slot number. Next, it sends a request to the recipient that includes the sender’s ID and slot index. It waits for a response from the recipient, and if it gets the response, it shows the form and the chat begins. If it doesn’t get a response, it destroys the form and tells the user that the request timed out.

Responding to a request for a chat

The process from the chat recipient’s point of view is shown in Figure 4.

When the recipient receives a request to chat, it decides to either accept or decline the request. If it declines to chat, it simply sends a message back to the requester declining the invitation. If it decides to accept the invitation, it creates an instance of the chat form and assigns it to a chat slot of its own. As long as it creates the form successfully, it sends a message to the requester accepting the chat and informing it of the recipient’s chat slot index. It then displays the form, and the chatting begins.

Chatting

To chat, the two clients send messages to each other addressed using the client ID and the chat slot index. When a client receives a message, it passes it to the form in the applicable chat slot, and the form displays the message.

Ending the chat

When a chat form is closed, it removes itself from the chat slot collection and sends a message to the other client that it’s being closed. When a form receives a message that the other party has closed the form, it remains open so any further action can be taken by the client, such as logging the conversation to a table or other file, but it won’t allow the form to send any more messages.

InterCom System

The InterCom System server (available from www.cns.nl/) is a messaging hub—that is, an application that sits somewhere on the network where all users can access it and allows applications to connect to it, register interest in certain events (subscribe), trigger events for other users, send messages to specific users, and disconnect from the hub. It sits somewhere on an IP network (note that the system is restricted to running over an IP network), and any client on the network—which could include the entire Internet—can connect to the server. Any connected client can then send a message to any other connected client. Clients can also trigger an “event,” which is broadcast to all of the other connected clients that have subscribed to that event. The triggered event can have data associated with it. Therefore, clients can communicate:

with all other interested clients (by triggering an event to which other interested parties have subscribed);
with a specific client (by sending a message to a specific client ID); or
with the server to get information about the other clients connected to the system.

The client is in the form of an ActiveX control and can therefore be placed on a VFP form and its methods, properties, and events accessed as for any other such control. The InterCom System provides a client with three types of functionality—Notification, Messaging, and Inventory. The InterCom System is discussed in more detail in my article “Pushing the Point” in the August 1999 issue of FoxTalk.

At the time of this writing, the InterCom System costs $399 USD for a royalty-free, single-developer license. There’s also an evaluation version of the system available for free download. The evaluation system is limited to a maximum of three simultaneous connections, but it’s otherwise identical to the full version.

Wrapping the client

The InterCom client has one feature that makes it awkward to use in VFP. It employs arrays passed by reference to return lists of information. VFP doesn’t handle this data type well (the COMARRAY() function only appears to work with COM servers created via a CREATEOBJECT call, not with ActiveX controls). To overcome this limitation, a wrapper for the ActiveX control was developed in VB. The wrapper intercepts the method calls and translates the array into a delimited string, which VFP handles very well. The wrapper class is included in the accompanying Download file.

The chat handler

The core of the chat component on each client is the chat handler. This object is instantiated when the application starts up and provides the communications link to the InterCom server. It’s based on the Form base class, so it can provide a container for the ActiveX InterCom client control. The load method of the class simply checks that the wrapped InterCom client is installed on the system. The init method accepts a reference to the calling object (for callbacks) and the name or IP address of the InterCom server machine. It then attempts to connect to the server and returns a logical indicating success.

To initiate a chat, the application calls the chat handler’s StartChat() method, passing the descriptor of the client with whom the chat is requested. The sequence of events shown in Figure 3 then begins. The code for the StartChat() method is shown in Listing 1.

Listing 1. The chat handler’s StartChat() method.

In the example shown here, there’s the facility to pass two additional pieces of information with the chat request—a Company ID and a Contact ID. In this application, these are primary keys to two main tables. Passing these keys to the other client allows that client to retrieve the data about which the initiator wishes to chat, perhaps even displaying information from the relevant rows in the table as part of the chat dialog box.

After checking the validity of these key parameters, the method requests a list of clients matching the descriptor from the InterCom server. The request is rejected if no clients match. If there’s a matching client, the method obtains a chat slot and populates it with an instance of the chat form. The chat form sends a message to the remote client’s chat handler requesting the chat and sets a timer that will fire if the operation times out. It’s then up to the other client to respond within the timeout period.

The chat handler form class contains only one (significant) control—the InterCom client control. That control has only one overridden event—the one that processes incoming messages, which is called, originally enough, the OnMessage() event. The event code simply directs the message to the appropriate chat handler method. The OnMessage() event code is shown in Listing 2.

Listing 2. The chat handler’s InterCom client OnMessage() event code.

The important point to note from the OnMessage() event code is that the type of message being sent is stored in the message subject. All the OnMessage() handler does is work out what kind of message is being sent by reading the subject and then route the message to the appropriate message-handling method of the chat handler object.

The chat handler object has four main message-handling methods:

HandleRequest()—Handles an invitation to chat from a remote client.
HandleAccept()—Handles the acceptance of an invitation to chat.
HandleMessage()—Handles a standard message (usually a line of typed conversation).
HandleDisconnect()—Handles the message sent by the other party when they terminate the chat session.

HandleRequest()

The HandleRequest() method is fired on the remote client when an invitation to chat is received. The method initiates the sequence shown in Figure 4. The code for the HandleRequest() method is shown in Listing 3.

Listing 3. The chat handler’s HandleRequest() method.

The HandleRequest() method starts by reading the message and breaking it down into its component parts. Each part is sent in the message’s data property on a separate line. The handler prompts the user, inviting them to accept the chat, and if the user rejects the invitation, it simply sends a message back to the initiator rejecting the request. If the request is accepted, the chat handler finds the next available free chat slot (or creates a new slot if there isn’t one free already). It then populates that slot with a new instance of the chat form. If it’s instantiated successfully, the chat form handles the notification of the acceptance of the chat. If it’s not instantiated successfully, the chat handler sends a message notifying the initiator that the chat was accepted, but that technical difficulties prevented it from occurring.

HandleAccept()

The HandleAccept() method is fired on the initiating chat client when it receives acceptance of an invitation to chat from the remote client. The code for the HandleAccept() method is shown in Listing 4.

Listing 4. The chat handler’s HandleAccept() method.

The HandleAccept() method begins by reading the constituent parts of the message from the data parameter. It then checks to see whether the chat was accepted or rejected, either because the remote user declined or technical difficulties prevented the chat from occurring. If it was accepted, the remote chat slot is assigned to a property of the appropriate chat form, the timeout timer is disabled, and the chat form is displayed—everyone is ready to chat! If it’s rejected, a message is displayed to that effect, and the chat form is released and the chat slot cleared.

HandleMessage()

The HandleMessage() method is fired on receipt of a standard message—the type of message that’s passed back and forth between clients during the course of a chat. The code for the HandleMessage() method is shown in Listing 5.

Listing 5. The chat handler’s HandleMessage() method.

The HandleMessage() method simply breaks out the chat slot (so it knows where to send the message) and sends the text of the message to the appropriate chat form for handling.

HandleDisconnect()

The HandleDisconnect() method is fired when the chat handler receives notice that the remote client has disconnected from the chat. The code for the HandleDisconnect() method is shown in Listing 6.

Listing 6. The chat handler’s HandleDisconnect() method.

The HandleDisconnect() method simply breaks out the chat slot (so it knows where to send the message) and fires the HandleDisconnect() of the appropriate chat form.

The chat form

The other half of the chat client component is the chat form itself. This is the visible manifestation of the chat component where the user types messages and reads the messages typed by the other user. The chat form in our sample chat app is shown in Figure 5.

The chat form handles much of the communication once the chat handler has established the conversation. To do this, it uses the following key methods:

Init()—Responsible for notifying the remote client of some pertinent details and for actually displaying the form.
HandleDisconnect()—Responsible for handling the notification that the remote client has ended the chat session.
ReceiveMessage()—Responsible for displaying the text of a message received from the remote client.
SendDisconnect()—Responsible for notifying the remote client that the local client is terminating the chat session.
SendMessage()—Responsible for sending a line of text to the remote client.

Init()

The Init() method has two different behaviors, depending on whether the chat form is being instantiated as a chat initiator or a chat receiver. In the end, the functionality of each type of chat form is identical, but the process of creating the form differs depending on its role. The code for the Init() method is shown in Listing 7.

Listing 7. The chat form’s Init() method.

The Init() method accepts quite a list of parameters. The first is the mode in which this form is being instantiated. The allowable values are CHAT_RECEIVER or CHAT_CALLER (defined in chat.h). This information is used to determine the behavior of the object later in the Init() process. The next parameter refers to the local chat handler’s chat slot to which this chat form has been assigned. Next, a reference to the chat handler object is passed so the chat form can access its properties and methods. The next two parameters are additional data used in this sample application to pass the primary keys of two sample tables.

The keys can be used by the form to display the data applicable to the chat. The descriptor for the remote client is the next thing to be passed. This will be displayed in the form’s caption so the user can tell who this chat session is with. Finally, if the chat slot for this chat on the remote client is known, this is passed as the last parameter. If this is the chat receiver, the remote chat slot will be known, but if this is the chat initiator, the remote chat slot will be passed back as part of the chat acceptance message.

The parameters are assigned to properties of the form for later use, and the caption is set. Next, an application-specific method, SetButtonState(), is called. In this case, this method is designed to allow the retrieval of the linked data if primary keys have been passed to the form.

Now the code forks. If the form is a chat recipient, it sends a message back to the chat initiator, accepting the chat and telling the initiator the chat slot ID that’s been assigned for use on the chat receiver, and makes the form visible. If the form is a chat initiator, it sends a message to the chat receiver requesting the chat and sets a timer so the chat requester doesn’t wait forever for a response.

HandleDisconnect()

The HandleDisconnect() method informs the user that the remote user has disconnected and sets a local property of the chat form to indicate that the chat is no longer live. It doesn’t close the form, as the local user might wish to review the contents of the chat before closing the form. The code for the HandleDisconnect() method is shown in Listing 8.

Listing 8. The chat form’s HandleDisconnect() method.

ReceiveMessage()

The ReceiveMessage() method adds a line of text to the list box chat log. The code for the ReceiveMessage() method is shown in Listing 9.

Listing 9. The chat form’s ReceiveMessage() method.

SendDisconnect()

The SendDisconnect() method sends a line of text from the local client to the remote client. It also displays the line in the list box chat log for later reference. The code for the SendDisconnect() method is shown in Listing 10.

Listing 10. The chat form’s SendDisconnect() method.

The SendDisconnect() method builds a message string that simply consists of the chat slot ID on the remote client. It then calls the SendMessage() method of the chat handler’s InterCom client control. The message is addressed to the remote client’s client ID; it has a subject of CHAT_DISCONNECT (defined in chat.h), and the text of the message consists of the remote chat slot ID.

SendMessage()

The SendMessage() method sends a line of text from the local client to the remote client. It also displays the line in the list box chat log for later reference. The code for the SendMessage() method is shown in Listing 11.

Listing 11. The chat form’s SendMessage() method.

The SendMessage() method builds a message string that consists of the chat slot ID on the remote client and the text of the message. It then calls the SendMessage() method of the chat handler’s InterCom client control. The message is addressed to the remote client’s client ID; it has a subject of CHAT_MESSAGE (defined in chat.h), and the text of the message consists of the remote chat slot ID and the line of text to be displayed. Finally, the line of text is added to the chat log list box on the local chat form.

Sample code

To demonstrate the use of the chat component, you’ll need the following:

The InterCom System server installed somewhere on a TCP/IP network. For the purposes of this exercise, it’s assumed that the server is installed at IP address 192.168.0.1.
The InterCom System client installed on all machines that are going to act as chat clients.
The InterCom client wrapper (available in the Download file) installed and registered on all machines that are going to act as clients.
An instance of VFP for each chat client (either running on the same machine or on separate machines). Note that the evaluation version of the InterCom server only allows three concurrent connections. The full version has no such limitations.
The class library CHAT.VCX (available in the Download file) extracted to a commonly accessible location. For the purposes of this exercise, it’s assumed that the path to the class library is \\SERVER\UTILS\VFPCHAT.

Once these steps are complete, issue the following commands from the VFP command window for each instance of VFP. Substitute a unique number for n.

Next, on one of the clients, enter the following command, where n is the number of another client:

The second client should pop up a message box asking whether to accept the chat, and, if the chat is accepted, a chat form should be displayed on both the caller and receiver. Messages typed on one client should appear on the other (after the Enter key is pressed).

Conclusion

Being able to communicate with other users of an application in real time and with the facility to link the conversation with data from the application adds another powerful resource to the programmer’s toolbox. The techniques presented in this article combine a commercially available solution to inter-application communication with VFP’s data-handling and UI.

To find out more about FoxTalk and Pinnacle Publishing, visit their website at http://www.pinpub.com/html/main.isx?sub=57

Note: This is not a Microsoft Corporation website. Microsoft is not responsible for its content.

This article is reproduced from the February 2001 issue of FoxTalk. Copyright 2001, by Pinnacle Publishing, Inc., unless otherwise noted. All rights are reserved. FoxTalk is an independently produced publication of Pinnacle Publishing, Inc. No part of this article may be used or reproduced in any fashion (except in brief quotations used in critical articles and reviews) without prior consent of Pinnacle Publishing, Inc. To contact Pinnacle Publishing, Inc., please call 1-800-493-4867 x4209.

ClassNavigator

Article
06/30/2006

ClassNavigator

Jim Booth

Multi-tier system designs often require that we use base classes that can’t be defined visually. This means using PRGs to define our classes. The Class Browser built into VFP is a wonderful tool for navigating the hierarchy of class definitions. However, when we use programmatically defined classes, the value of the Class Browser is lost. This month, Jim Booth introduces Michael G. Emmons of Flash Creative Management (now GoAmerica), who has a solution for us.

Most of the classes we create in Visual FoxPro can be built using the visual class designer. For these visual classes, we have the Class Browser tool. However, there are a number of classes in Visual FoxPro that can’t be created in the visual designer. Classes like the column, page, session, and others must be created in program code using the DEFINE CLASS construct. For these classes the Class Browser fails, but the Class Navigator from Michael Emmons succeeds.

Simple installation

One thing that I dislike is a developer tool that takes a genius to install it and get it working. Michael has given us a utility that installs as simply as is possible. Just copy the APP file, ClassNavigator.app, to any directory on your machine, and it’s installed and ready to go.

The test run

To test this tool, I created two program files, as demonstrated in the following code:

Notice that the class defined in TestClass2 is a subclass of the one defined in TestClass.

Running ClassNavigator

Next, I ran ClassNavigator.app and was greeted by the screen shown in Figure 1.

There are four tabs—labeled Classes, Files, Options, and About—that are used in viewing the classes. The first tab we’ll visit is the Files tab, and we’ll select the Add button. In the file selection dialog box, I chose TestClass.prg; the resulting display is shown in Figure 2.

Switching to the Classes tab and expanding the tree gives the display shown in Figure 3.

The display has been expanded to show the existing details. You can see the filename and base class under Info, the Customer property under Properties, and the Custom method under Methods, just like the Class Browser would show us for a visual class definition.

Double-clicking on the class name in this display will open the editor with the program loaded for editing.

Hierarchies from multiple programs

Now return to the Files tab and open the TestClass2.prg file. The new Classes display is shown in Figure 4.

The Classes tab now shows us the hierarchy of these two classes, including the file information regarding each class.

Where to get ClassNavigator

This tool is included in the accompanying Download file. It’s also available at www.comcodebook.com, where future updates will be posted first (as well as the COM Codebook application framework). The source code for the Class Navigator is included in the download. The tool is freeware; you’re free to use or modify it to your desire, but you’re restricted from selling it to anyone else.

Summary

Michael G. Emmons has given us a utility that allows us to view classes that are defined in programs rather than visual class libraries. With his tool, we can see the inheritance hierarchy of these classes even when they cross multiple program files. A simple double-click opens any one of the classes for editing.

Michael and Flash Creative Management (now GoAmerica) have graciously made this tool, as well as many other tools including a complete application framework, available to us all at no charge.

The Component Gallery: VFP’s Best Kept Secret

Article
06/30/2006

The Component Gallery: VFP’s Best Kept Secret

Markus Egger

Visual FoxPro 6.0 shipped with a great new tool called the “Component Gallery.” This tool is mainly thought to be a productivity-enhancing tool that makes the use of components, classes, and other items found in Visual FoxPro much easier. Unfortunately, so far, very few third-party vendors and development teams have utilized the Component Gallery to the extent one would expect, making this great new addition to VFP one of VFP’s best kept secrets. In this article, Markus Egger not only demonstrates how the Component Gallery can be used, but also how you can create your own catalogs.

When you start the Component Gallery from the Tools menu, it starts up with several default catalogs already loaded. Catalogs are simply collections of items stored in hierarchical fashion. You can think of each item stored in the Component Gallery as a shortcut to a Visual FoxPro item such as a class, a form, or a report. You might wonder what makes this tool valuable since we already have access to these items through the Class Browser as well as the Project Manager. That’s correct; however, there’s a significant difference: The Class Browser as well as the Project Manager are built as tools for the developer who needs access to every single item in the project. They show all classes, support classes, include files, bitmaps, and much more. The Component Gallery, on the other hand, simply provides access to the top-level items such as classes or components, but hides the complexity under the hood. You can compare this to a car mechanic who needs access to every part of the car, including the engine, transition, and car alarm, while the driver who simply uses the car to get to work every day doesn’t worry about all of those things.

If you’re the “application mechanic,” you’ll be better off using the Class Browser or the Project Manager. It will provide access to every little bit of the application. This is especially true if you wrote the entire application by yourself. However, if you’re using third-party tools or even components written by your fellow co-workers, you might not need this level of granularity. In fact, it will make it much harder to use those components. Imagine that a team member provides you with a class library that you can utilize for a specific task. This library contains a number of classes, one of which is useful to you. All of the other classes are really just helper classes that the main class depends on, such as parent classes, members of the class, or other classes that are utilized by the main class to do its job. In addition, you get a number of external files such as include (.H) files, bitmaps, and XML definition files that are also required to make this component work.

Do you really care about all of this information? Of course not! Or, well… you shouldn’t. Why would you want to become the mechanic of somebody else’s “car”? However, in reality, you’ll have to familiarize yourself with all of those components to make sure you add them all to your project and to pick the right class in the first place. Little do you know at this point that your co-worker tried to make this class as easy to use as possible and even provided a builder that can be used to configure this class.

The Component Gallery will help you in this scenario. Your colleague can create a simple catalog that provides a link to the main class. When you drag and drop that link on your form, not only will the class get added, but, at the same time, all external references are taken care of, and immediately the provided builder starts to make it easy for you to configure the required properties rather than finding out manually which properties have to be set.

You say this isn’t a problem for you, because you don’t work in a team, or perhaps the team is so small you can simply ask the co-worker? Well, what about third-party products? At EPS, we produce a product line called the FEC (Fox Extension Classes). This is simply a set of classes stored in class libraries, plus a few external dependencies, just as described in the preceding scenario. We gave a lot of thought to the product architecture, resulting in a very flexible environment that farms most of the functionality out to special behavior objects that can be configured and extended at will. The downside of this architecture is that 80 percent of the classes shipped in the libraries aren’t made to be used directly, but are designed for internal use only. How would you like to navigate all of the information through the Class Browser? So there!

Another great advantage of the Component Gallery is its hierarchical representation of the information. It allows organizing items into folders. This is surely much easier to use than the inheritance-view provided by the Class Browser, or the flat-view provided by the Project Manager.

Using the Component Gallery

So let’s have a look at the Gallery. When you start it the first time, it shows several default catalogs that provide access to the FFC (Fox Foundation Classes) as well as VFP’s samples (see Figure 1).

Most of the items referenced in the default catalogs are FFC classes. Note that the Gallery can maintain a large number of different items, such as forms, reports, wizards, files, utilities, ActiveX controls, and much more. Basically, any Visual FoxPro as well as Windows item can be referenced through the Gallery. In addition to static links to items, the Gallery also supports a feature called “Dynamic Folder.” Figure 1 shows a reference to such a folder. It’s named “Installed Controls.” This folder automatically shows a list of all COM components and ActiveX controls installed on your system.

To use a specific class such as the FFC VCR Buttons class, simply select the item and drag and drop it to your form or class that’s open in the designer (note that the Gallery can also be used for source code editing). It will automatically add an instance of the class to your form. You don’t have to worry about what library it’s stored in, nor are you bothered with all of the other classes stored in the same library. The Gallery abstracted all of that complexity away and provides simple, categorized access to this component. Note also that the Gallery displays a description of the component you selected.

You want to know how much easier this is than using the Class Browser? Well, just right-click on the item and select “View in Browser.” This automatically opens the library in which the class is stored and switches the Component Gallery into Class Browser mode (the Gallery and the Browser internally are really the same application). The result is shown in Figure 2.

As you can see, this view is much more cryptic. Not only do you see all kinds of classes you have no interest in (how about those custom classes—what’s your guess, can they be used by themselves or not?), but you also see class names that are much harder to understand, and the Class Browser doesn’t even provide a description.

Another good example is the list of samples that ship with VFP. Perhaps you’re not aware of this, but the FoxPro team has produced a large number of examples that explain many aspects of the Visual FoxPro environment and language. In previous versions, this information was hard to find. Samples are scattered over all kinds of directories, and who wants to run all of them just to figure out what they’re doing? The Component Gallery ships with a special catalog that lists all of the included samples and provides access to them in ways that make sense for each individual example (see Figure 3).

As I mentioned earlier, the Component Gallery can also be used to automatically trigger builders whenever a complex class is dropped in a designer. Try dropping the “Field Mover” class from the Data Navigation folder in the main Visual FoxPro catalog. Immediately, the builder shown in Figure 4 starts up and asks you to provide important property values. You can drop the same class from the Class Browser or the Form Controls toolbar, but then you’d have to go through an almost endless list of properties and try to figure out what they’re for, whether or not they’re important, and what the appropriate settings are.

Creating your own catalogs

So, by now are you convinced of the usefulness of this tool and eager to provide your own catalogs for your libraries, or perhaps even commercial third-party products? Well, you’ve come to the right place.

Creating a new catalog is easy. Simply click the option button and select the Catalogs page in the options dialog box (see Figure 5). Click the New… button and specify the name of the catalog file (which is a regular DBF file). Initially, the new catalog is listed by its filename. We’ll define a friendlier name a little later. Click the OK button to close the dialog box and open the new catalog right away.

To rename the catalog, right-click the item and choose Properties (the Rename feature doesn’t appear to work). This launches the dialog box shown in Figure 6. Note that you might not see all of the same options shown in Figure 6. If this is the case, open the Options dialog box and check the “Advanced Editing Enabled” feature on the first page. You can use the Properties dialog box not only to change the name, but also to set descriptions as well as icons that are to be displayed by the Gallery.

To make the new catalog useful, you’ll have to add some items. First of all, add a new folder that provides links to the classes you’d like to keep track of. You can create new items, including folders, by right-clicking in the right-hand pane (see Figure 7). Again, you have to open the Properties dialog box to rename the folder and set other properties such as the icon.

You can now proceed to add items to that new folder, in the same way you created the folder itself: Right-click in the right-hand pane and choose to add a new Class. The Gallery will present you with a GetClass() dialog box to select the class. The item added to the Gallery will automatically be assigned the name of the class, but again, you can change this to a friendlier name through the Properties dialog box.

This is all you have to do to create a catalog for your classes. Note that the Gallery is smart enough to attach the proper behavior to your new class item. You can double-click on your class to edit it; you can drag and drop it to the form or class designer to create an instance; you can right-click on the item and open the class in the Class Browser; and much more. As you can see in Figure 7, the Gallery can handle a large number of different items and attaches the right behavior to them. This way, report items can be printed or previewed, video files can be played, tables can be opened, and so forth.

But what if you’d like to add items that the Gallery isn’t aware of? A little while ago I wrote a public domain utility called GenRepoX (you can download it for free from www.eps-software.com). It extends the Visual FoxPro Report Writer, but it uses the internal report engine. Reports can be modified in the same way regular Visual FoxPro reports can be modified, but to execute the reports, a special function has to be called. Otherwise, the special features provided by GenRepoX will be lost. The Gallery is aware of reports and allows modifying, printing, and previewing them, but of course it isn’t aware of GenRepoX. Luckily, there are ways to teach the Gallery new behaviors.

All Component Gallery behaviors are encapsulated in individual objects. The source code of those classes ships with Visual FoxPro in the _gallery.vcx and vfpglry.vcx class libraries. The behavior you need for GenRepoX is very similar to a regular report behavior, which is defined in the _reportitem class in the vfpglry.vcx library. To reuse what’s already there, you can simply subclass this behavior. I chose to call the subclass “GenRepoXItem.”

There are two methods we’re interested in: Run() and SetMenu(). Those methods do what you think they would. Run() executes the item, and SetMenu() creates the right-click menu. Our major modification will be making the Run() method aware of GenRepoX, which can be done like so:

I basically overwrite all of the default behavior and replace it with my own, which is rather simple in this case, since all I do is execute the report in preview mode. In the second line, I create a command that executes the report. Note that the cFileName property tells us what report filename the item is linked to (once it’s used in a catalog). In line 3, I execute the report by running it through the GenRepoX() method.

This is enough to make the new item work. However, I’d also like to give the user a little visual clue that the item at hand isn’t a standard report, so I decided to modify the menu. The SetMenu() method is responsible for displaying the menu. Each behavior provided by the Gallery has default menu items. Some of those items are defined in each behavior, others (such as Cut, Copy, and Properties) are provided by the parent class used for all items, named “_item.” In our scenario, I’d like all of the default items, but I don’t want report-specific items, since I want to introduce my own. In do this in the following fashion:

In line 3, I execute the item defined in the _item class. Note that I specifically name the class rather than issuing a DoDefault(), because I intend to skip the behavior defined in the direct parent class, which is the report item.

In the next line, I add a new menu item using the AddMenuBar() method, which exists on every Gallery item. Parameter one specifies the caption, and parameter two specifies the method that’s to be executed when the item is selected. In this case, I simply execute the Modify() method, which I inherited from the standard report item. Note the special “oTHIS…” syntax. oTHIS is a special pointer that allows me to access the current object. The SetMenu() method is called by a Gallery internal mechanism, so by the time the menu is actually displayed, my object isn’t accessible through the THIS pointer anymore, which is the reason for this special naming convention used by the Gallery.

The last parameter is interesting, too. From within an item, “THIS.oHost” always links you to an instance of the Gallery itself. The Gallery has a property named “lRunFileDefault” that tells you whether the Gallery is configured to run items whey they’re double-clicked (.T.) or modify them (.F.). In the menu, I’ll print the default item in bold as required by the Windows interface guidelines. I specify this using the last parameter. So if lRunDefaultFile is set to .F., I pass a .T. as the parameter, and vice versa.

I’m sure you can now figure out the last line by yourself. It simply displays another menu item labeled “Preview GenRepoX,” and it executes the Run() method (the one I coded earlier) when selected.

Now all that’s left to do is tell the Gallery about the new item type. I do that in the Properties dialog box of the main catalog item (see Figure 8).

From now on, the new item shows up in the New Item menu (see Figure 9).

Once you’ve added a GenRepoX report item, you can right-click it to see and use the behavior you added. Note that the item also exhibits default behavior that makes a lot of sense for our use. The icon defaults to a report, for instance (see Figure 10). In addition, the item uses the custom menu and behavior. You can use the right-click menu or double-click the item to execute the GenRepoX report.

The options outlined in this article only represent a small example of what’s possible with custom items. The possibilities are truly endless. You can find more information about this subject on the Microsoft Visual FoxPro Web site (https://msdn.Microsoft.com/vfoxpro), as well as in the documentation and in several books (such as my own <s>).

So far, so good. The new catalog is coming along nicely. But what if a user I’ve provided this catalog to has questions? Perhaps I should provide a link to my Web site. I can do this easily by adding a dynamic folder to my catalog. I add the folder just like any other folder, but this time, I set the folder’s “Dynamic folder” property (in the Node page of the folder’s Properties dialog box) to www.eps-software.com. That’s all there is to it!

Conclusion

The Component Gallery is a very powerful tool. Unfortunately, there have been very few products and projects that make use of it. Partly, this appears to be due to the poor documentation, but it’s also due to the not terribly obvious advantages the tool provides. However, once you’ve started using the Gallery, you’ll have a hard time living without it.

If you have questions regarding the Gallery’s use, custom catalogs, and even AddIns (a possibility I couldn’t discuss in this article), feel free to e-mail me at Markus@eps-software.com.

To find out more about FoxTalk and Pinnacle Publishing, visit their website at http://www.pinpub.com/html/main.isx?sub=57

Note: This is not a Microsoft Corporation website. Microsoft is not responsible for its content.

This article is reproduced from the April 2001 issue of FoxTalk. Copyright 2001, by Pinnacle Publishing, Inc., unless otherwise noted. All rights are reserved. FoxTalk is an independently produced publication of Pinnacle Publishing, Inc. No part of this article may be used or reproduced in any fashion (except in brief quotations used in critical articles and reviews) without prior consent of Pinnacle Publishing, Inc. To contact Pinnacle Publishing, Inc., please call 1-800-493-4867 x4209.

Understanding COM+ with VFP, Part 1

Article
06/30/2006

Understanding COM+ with VFP, Part 1

Craig Berntson

When COM+ debuted in Windows 2000, it introduced many new capabilities to enhance n-tier applications. Now with VFP 7, you can use these enhancements to make your applications more robust. In this first installment of a series, Craig Berntson reviews COM and MTS, and then introduces COM+.

For many years, we’ve heard about the importance of breaking applications into multiple tiers or services. By splitting the user interface, business rules, and database access, we can easily modify or completely replace one service without affecting the others.

Historically, Visual FoxPro applications have been single-tier solutions, even if the data resides on the server. This is because developers have mixed the user interface, business rules, and data access into one application or even the same form.

With the use of SQL Server, we move to a two-tier scenario. The data is normally accessed via ODBC by the use of Remote Views or SQL pass through. Stored procedures are often called on the server, and the SQL SELECT statement is resolved before sending any data across the wire. It’s the splitting of the processing onto the server and the workstation that makes this design two-tier.

In a three-tier solution, the user interface only displays data and accepts input from the user. There might be some minor data validation, such as ensuring that the required fields are populated or limiting the user’s selection via a list or combo box. However, all of the actual processing of the data takes place in a separate component that holds all of the business rules. Calculations of totals or taxes, validation of data, or the generating of report data are examples of things that occur in the middle-tier business logic. Finally, the data tier is responsible for the reading and writing of data into the data store. The user interface should never directly access the data services, but should go through the business services layer to get at the data.

This separating of multiple tiers is what Microsoft calls the Distributed interNetworking Architecture, or DNA. The different components of each service can reside on the same computer, making a logical separation of each service—or, on multiple computers, providing a physical separation of the tiers. Typically, the user interface resides on the client computer, while the business and data components reside on an application server with the data store on a second server. When access is via a Web browser, an additional server for IIS is often added to the mix.

COMmon knowledge

The way to access these components is via the Component Object Model. COM is a specification that allows components written in different languages to interact with each other. Therefore, we can create a component in VFP that can be accessed from a VB or Delphi application, or even from Word or Excel. ActiveX controls are another example of COM objects. When you control Word or Excel from your VFP application, it’s done via COM.

The first thing to consider when creating a COM component is how it will fit in with the other pieces of your application. In other words, you need to determine whether it should run in-process or out-of-process.

An in-process component is compiled as a DLL and must be hosted by an executable program. It runs in its host’s memory space—hence the name in-process—which makes instantiating (running) the component fast. Data is marshaled (passed) across the COM boundary. Because the component runs in the same memory space as the application, if the component crashes, it most likely will cause the application to crash. One other thing to keep in mind: In-process servers written in VFP can’t have any user interface exposed.

An out-of-process server is compiled as an EXE and runs in its own memory space. When it’s instantiated, there’s some overhead required such as allocation of memory, process id, and so on. This all takes time, which makes instantiating an out-of-process server slower than an in-process server. In addition, it takes longer to marshal data across the process boundaries from the application to the component, so it runs slower. However, because the COM server is running in a different memory space than the client application, if the component crashes, the application will quite possibly keep running.

Creating a COM component in VFP is quite easy. The OLEPUBLIC keyword tells VFP to compile the code with the proper COM information needed for access from other applications:

When you build the component (see Figure 1), you can choose “Win32 executable/COM server (exe)” to create an out-of-process server. To build an in-process server, select either “Single-threaded COM server (dll)” or “Multi-threaded COM server (dll).” I’ll talk more about the difference between the two types of DLLs later. Building the component will automatically register it on the development computer. You then instantiate it using the CreateObject() function:

Many of the rules and intricacies of COM are automatically handled for us by VFP. However, we have to manually follow one rule. That rule states that we should never change the interface of a component. If we do, we need to create a new ID for the component. By interface, I don’t mean user interface, but the public methods and parameters of the component. Let’s look at the preceding example. If we add a third parameter to the Multiply method, we change the interface and need to create a new component ID. This is done on the Build dialog box. The last option on the dialog box is “Regenerate Component IDs.” Check the option to create a new GUID for the component.

When you start deploying your COM components on remote servers, you’ll access them via Distributed COM (DCOM). Historically, under DCOM, you distribute an out-of-process server and set up the calling information on the client computer. Chapter 16 of the VFP Programmer’s Guide goes into detail about how to do this. When you install the component on a remote server, the code runs on the server, not on the client workstation. Don’t have any UI in your server because it will display on the server, not the client workstation.

MTS to the rescue

Microsoft saw the need for a better way for remote components to run, so they created Microsoft Transaction Server (MTS). Originally available for NT and Windows 9x through the NT 4.0 Option Pack, MTS solved a number of problems by providing a host for COM DLLs. It also provided a wizard that set up all of the DCOM calls on the client station for you. Some other features of MTS include:

Just-in-Time Activation: A component is kept on disk and then brought into memory (activated) only when needed.
Object Request Broker (ORB): MTS will handle multiple calls to the same component from multiple clients.
Transaction Services: Commits and aborts are handled by the Distributed Transaction Coordinator (DTC) instead of the application. This makes it possible to have a transaction that spans multiple databases.
Role-based Security: The security scheme allows you to determine who can access your components based on NT logins and groups. If a user doesn’t have authorization to access a component, an error message is returned to the client indicating that the component can’t be instantiated.
Connection Pooling: Typically, an application will make a connection to the data store, and then hold that connection during the life of the application. MTS allows multiple clients to use the same connection.

Creating components for use under MTS requires that you think differently about your application design. First, your application should be stateless. This means that your client program should instantiate the component, make calls to a method, and then release the component. The connection to the component should be as short a time as possible. You should avoid setting properties and pass all of the needed information as parameters. Note that COM doesn’t allow parameters to be passed to the Init method.

You also need to think about threading. We typically think of threading as single or multi-threading. VFP creates single-threaded applications. That is, it can only do one thing at a time. This is like going to the grocery store and only having one checkout stand open. All customers must go through the same line. Only one customer at a time can be helped. The others wait in the queue for their items to be processed.

Multi-threading allows your application to split processing into different pieces, all running simultaneously. Using the grocery store example, you can unload parts of your shopping cart into different lines and have all of your groceries rung up at the same time.

MTS uses a third type of threading, apartment model. Again using our grocery store example, customers may choose any open checkout stand, but once you’ve chosen one, you always have to use the same one. Luckily, MTS will open a new line for us when all are used.

So, how do we make use of MTS in our VFP components? First, we have to add some code. Let’s modify our Multiply example to handle MTS.

The Context object contains information about our particular instance of the COM component. Also, note the call to SetComplete(). This will commit any open transactions. If we need to abort the transaction, we would call SetAbort() instead.

When we build our component, we can’t use “Win32 executable/COM server (exe).” MTS requires that components be DLLs. That leaves us with two choices: single or multi-threaded.

The single-threaded DLL is a good choice when the method call will be very fast or there’s the possibility that only one user will hit it.

The multi-threaded DLL isn’t truly multi-threaded. It’s apartment-model threaded. Make this choice when the method call is slow or many users will simultaneously call your component.

Once you’ve built your component, you install it on the server with the appropriate VFP runtime libraries. Then, you create an MTS package and import your component using the MTS Explorer. Using MTS Explorer, you can set security and transactional support, and export a client setup program.

You can get more information on MTS from Randy Brown’s article, “Microsoft Transaction Server for Visual FoxPro Developers,”.

Windows 2000

When Microsoft introduced Windows 2000, it came with several new services. One of those is COM+. Basically, COM+ is the marrying of COM and MTS, but new COM+ features were also introduced. Under Windows NT, MTS ran on top of the operating system. Under Windows 2000, it’s integrated into the OS. COM+ is only available in Windows 2000. However, Windows 95, 98, Me, and NT users can use COM+ components running on a Windows 2000 server. COM+ not only includes (and enhances) the features of MTS, but also introduces new services: Queued Components (QC), Loosely Coupled Events (LCE), Object Pooling, and Dynamic Load Balancing. In the next installment of this series, we’ll begin to delve into these services in detail.

COM+ Applications are administered through the Component Services Manager (see Figure 2). You’ll find it in the Administrative Tools group in the Windows Control Panel. Let’s walk through registering the component that we saw earlier.

Expand the tree under Component Services until COM+ Applications is available.
Click on COM+ Applications to make it the currently selected node, and then right-click on COM+ Applications.
From the context menu, select “New Application” to launch the COM Application Wizard. Then click Next.
Click “Create an empty application” (see Figure 3).
Enter the name for your application. In the example, I’ve called it “MyFirstCOMApp.” Then select the Activation Type. Normally, you’ll select Server application because your component will run on a server. If you install the component on a workstation and want it to run in your application’s memory space, then select Library application (see Figure 4). Click Next.
Select the User ID that the component will run under. When installing on a server, it’s a good idea to set up a user specifically for your component. Be sure to assign the proper rights to the user so that the component will have access to all of the drives, directories, and resources that will be needed (see Figure 5). Click Next, then Finish.

We now have the application set up, but it doesn’t contain any components. We have to add the component to the application:

Click the plus sign (“+”) next to our new COM+ Application to expand the tree.
Click on Components, and then right-click on Components. Select New Component from the context menu to launch the Component Install Wizard. Click Next.
The wizard gives you three options: Install new component, Import component(s) that are already registered, or Install new event class(es). We’ll use the third option when I talk about Loosely Coupled Events. The second option, Import component(s) that are already registered, is used when you’ve previously installed the component on the computer. However, at the time this was written, there was a bug in Windows 2000 that caused this option to not work correctly. That leaves option 1. Click the button next to this option (see Figure 6).
You’ll next be prompted to select the DLLs to install. If you don’t have the proper VFP runtime files installed, you won’t be able to select and install your component (see Figure 7). Once you’ve selected your components, click Next, then Finish.

Now that your component is installed, how do you access it? The same way as before. Just use CREATEOBJECT() to instantiate the component and you’re ready to go.

Summary

We’ve covered quite a bit of ground in this article, but most of it should be review. You might be wondering whether all of this COM stuff is still useful in a .NET world. The answer is Yes! COM still exists in .NET. In fact, .NET was originally called COM+ 2.0. In upcoming articles in this series, I’ll discuss security, distribution, loosely coupled events, transactions, queued components, and other COM+ features.

Sidebar: It’s GUID for Me, is it GUID for You?

A GUID (pronounced GOO-id) is a Globally Unique Identifier. It’s a 128-bit Integer and looks something like {1EF10DF8-8BF9-4CD7-860A-8DCD84EA3197}. The GUID is generated using a combination of the current date and time, a counter, and the IEEE machine identifier from the network card. The chances of two GUIDs being the same are extremely remote.

So how is this GUID used? When you build a component, three files are produced. The first is the DLL, and the second is a Type Library (TLB). The TLB is a binary file that lists all of the public classes, properties, methods, and events in your automation server. The third file is a Registry file (VBR). This lists the GUIDs for your server and is used to register your component.

When you register the component, the VBR file is used to make Registry entries about your component. Things like the directory location of the DLL, its threading model, and its public interfaces are placed in the Registry. When you instantiate the component, the server name—for example, Excel.Application—is looked up in the Registry. The GUID will then be used to get additional information about the component, such as the directory location and public interfaces.

To find out more about FoxTalk and Pinnacle Publishing, visit their website at http://www.pinpub.com/html/main.isx?sub=57

Note: This is not a Microsoft Corporation website. Microsoft is not responsible for its content.

This article is reproduced from the May 2001 issue of FoxTalk. Copyright 2001, by Pinnacle Publishing, Inc., unless otherwise noted. All rights are reserved. FoxTalk is an independently produced publication of Pinnacle Publishing, Inc. No part of this article may be used or reproduced in any fashion (except in brief quotations used in critical articles and reviews) without prior consent of Pinnacle Publishing, Inc. To contact Pinnacle Publishing, Inc., please call 1-800-493-4867 x4209.

Understanding COM+ with VFP, Part 2

Article
06/30/2006

Understanding COM+ with VFP, Part 2

Craig Berntson

In Part 2 of this series, Craig Berntson examines client distribution, security, and error handling.

In Part 1 of this series (see the May 2001 issue of FoxTalk), I reviewed COM and MTS and introduced COM+ services under Windows 2000. I also showed you how to create a new COM+ application and install a component on the server. Now in Part 2, I’ll look at how to get the client to use the component on the server, security, and error handling.

Is the client always right?

Last month, I showed you how to install your application on the server. But that doesn’t do much good if you can’t get to the component from the client. The good news is, Windows 2000 makes it easy to set things up on the client. Let’s go back to the component we built and installed last month. As a quick review, here’s the component code:

I call this the world’s dumbest COM component. All it does is multiply two numbers. However, keeping the sample code simple allows us to concentrate on the COM+ aspects of the example.

Now we need to do an install on the client. Let’s go back to the Component Services Manager. Expand the tree under COM+ Applications and select MyFirstCOMApp. This is the COM+ Application that we built and installed last month. Now right-click on MyFirstCOMApp and select Export. The COM Application Export Wizard will appear (see Figure 1). You’re first prompted to enter the full path and filename for the application file. Enter C:\COMApps\MyFirstCOMAppProxy. Then make sure you’ve selected “Application Proxy—Install on other machines to enable access to this machine.” (The other option, “Server Application,” is used when you want to install the component on another server.) Then click Next and then Finish.

The wizard has created two files—MyFirstCOMAppProxy.MSI.CAB and MyFirstCOMAppProxy.MSI. These files can be copied and installed on the client computer. These files don’t include the component. You don’t need it on the client. They contain information on the public methods and properties of the component and pointers to the server so that Windows can find the component and instantiate it.

Again, you never install the component on the client. Instead, you install a proxy. Your application thinks the component is installed and running locally, but it isn’t. Make note of this. A component installed on an application server never runs on the client. For some reason, this is a difficult concept for some people to understand.

You instantiate the server component exactly the same way you instantiate a local component. Try this in the Command Window:

Why did this work? VFP makes a call to Windows, asking for the component to be instantiated. Windows looks up the component information in the Registry and finds that the component lives on an application server. Windows then instantiates a proxy to the component and makes a call to the server to instantiate the component. VFP doesn’t know it’s talking to the proxy; it thinks it’s talking directly to the component. When you call the Multiply method, the proxy sends the call to the server via DCOM and the result is passed back to the proxy, which passes it on to VFP.

Are you feeling insecure?

Now that the component is installed on the server and the client proxies are installed, let’s see how easily we can grant or prohibit access to the component. COM+ uses role-based security. A role is a type of user. For example, in a bank you might have tellers, managers, loan officers, customer service people, and so forth. Each of these people is a role. You want to prohibit tellers from making loans, so in COM+, you could set up security on a loan component to prohibit this. The nice thing is that this is a configuration option and easy to change using the Component Services Manager.

Roles are based on Windows users and groups, so the first step in setting up the security scheme is to establish the Windows security groups. It can be confusing to understand where roles fit in the hierarchy of groups and users. The COM+ Help file states, “Roles are categories of users that have been defined for the application for the purpose of determining access permissions to the application’s resources. The developer assigns the roles (as symbolic user categories) to the application.” That sounds a lot like a Windows user group to me, so to keep it easy, think of a role as a user group that’s application-specific.

Now, getting back to our bank example, we’d have four groups: tellers, managers, loan officers, and customer service. Go ahead and create them on the server using Windows User Manager in NT or the Computer Management Applet in Windows 2000. Enter the first user group, and then the other three.

Once those groups are created, go back to MyFirstCOMApp in the Component Services Manager. Click on Roles, and then right-click and select New Role. Enter the first role, Teller, and click OK (see Figure 2). It’s not necessary to name the roles the same as the Windows user groups, but it makes management easier. Now create the three remaining roles of Manager, Loan Officer, and Customer Service.

Next we need to identify the users in each role. Expand the tree under Teller. You’ll see a folder labeled “Users.” Click on the folder, and then right-click and select New User. Scroll down the list of Windows users and groups and select the Tellers user group, and then click Add. Do the same for Managers and Customer Service. Then click OK. You’ll see each of the Windows Security groups added to the Teller role in Component Services (see Figure 3).

When new users are added to the system, they’re added to the proper Windows group, which in turn automatically puts them in the proper role. So far, we’ve identified the roles, but we haven’t told Component Services to use any security. Click on MyFirstCOMApp, right-click and select Properties, and then select the Security tab. Check “Enforce access checks for this application,” and then click OK (see Figure 4). Ignore the other options for now, I’ll discuss them shortly.

Now right-click on MyComm.Math and select Properties, then the Security tab. You’ll see that “Enforce component level access checks” is selected. You’ll also see the security roles listed. Simply check the roles that are to have access to this component (see Figure 5).

You can drill down and assign the security access to the interface or method level if you want. This enables you to have a single component with several interfaces, each having different security levels. If a user doesn’t have the proper access to use a component, an error message is returned stating that the component couldn’t be instantiated.

Now, let’s go back to the Application Security dialog box (see Figure 4). There are some additional options that I need to discuss. The first is Security level. This controls when COM+ validates the user’s security. With the first option, “Perform access checks only at the process level,” role-checking won’t be done at the component, interface, or method levels. Under the second option, “Perform access checks at the process and component level,” the security role is checked when a call is made to the component. You’ll almost always use the second option. However, the first option is useful when you’ve already validated the user.

The next setting is “Authentication level for calls.” There are six options, as described in Table 1. As you move through the list, each option gets progressively more secure. Note that the higher the level of security, the longer it takes to validate the user. The default level is Packet.

Table 1. Authentication levels.Expand table

Level	Description
None	No authentication.
Connect	Checks security only when the client connects to the component.
Call	Check security at the beginning of every call.
Packet	Checks security and validates that all data was received.
Packet Integrity	Checks security and validates that none of the data was modified in transit.
Packet Privacy	Checks security and encrypts the packet.

Finally, we have “Impersonation level.” This sets the level of authority that the component gives to other processes. There are four different levels as described in Table 2. The default is Impersonate.

Table 2. Impersonation levels.Expand table

Level	Description
Anonymous	The second process knows nothing about the client.
Identify	The second process can identify who the client is.
Impersonate	The second process can impersonate the client, but only for processes on the same server.
Delegate	The second process can impersonate the client in all instances.

Thus far, I’ve discussed declarative, role-based security, which is defined and managed at runtime. You can also use programmatic security. This allows you to branch your code based on the access level of the user. For example, a loan officer might only be able to authorize a loan up to $50,000. After that, it takes a manager’s approval to authorize the loan.

By using both role-based and programmatic security, you can support just about any security scheme that you need.

Error handling

One of the questions I often see on online forums is, “How do I report an error back to the user?” If you think about this, the answer doesn’t seem easy. You can’t display any dialog boxes with the error from your component. It’s running on a different computer than the user interface. VFP has the COMRETURNERROR() function to send the error message back to the client. COMRETURNERROR() takes two parameters. The first is the name of the module where the error occurred. The second is the message to display to the user. Let’s look at the code.

Now compile the code into a DLL and instantiate it.

You might expect “This will never be displayed” to show on the VFP desktop. However, an error dialog box appears instead.

You can return any error information you want in the message parameter. You also might want to enhance the error method by capturing additional information using AERROR() or writing information to an error log. There’s one caveat: The Error method won’t fire if an error occurs in the Init method.

Conclusion

That pretty much covers installation, security, and error handling. Next month, I’ll discuss transactions and see how COM+ and VFP 7 allow us to include VFP data in transactions, something that couldn’t be done with MTS and VFP 6.

To find out more about FoxTalk and Pinnacle Publishing, visit their website at http://www.pinpub.com/html/main.isx?sub=57

Note: This is not a Microsoft Corporation website. Microsoft is not responsible for its content.

This article is reproduced from the June 2001 issue of FoxTalk. Copyright 2001, by Pinnacle Publishing, Inc., unless otherwise noted. All rights are reserved. FoxTalk is an independently produced publication of Pinnacle Publishing, Inc. No part of this article may be used or reproduced in any fashion (except in brief quotations used in critical articles and reviews) without prior consent of Pinnacle Publishing, Inc. To contact Pinnacle Publishing, Inc., please call 1-800-493-4867 x4209.

Understanding COM+ with VFP, Part 3

Article
06/30/2006

Understanding COM+ with VFP, Part 3

Craig Berntson

Transactions are an important part of any data update mechanism. Part 3 of this series by Craig Berntson introduces the Distributed Transaction Coordinator and explains how to use transactions under COM+.

Transactions, transactions, transactions. Without them, we can’t be sure that data is getting written to all of the Tables involved in an update. Before digging into how transactions work in COM+, let’s do a quick review of transactions.

A review of transactions

Joe wants to transfer $100 from his savings account to his checking account. He walks up to the ATM, inserts his card, and presses the buttons to initiate the transfer. Behind the scenes, this transfer can be accomplished two ways. The first way is that the balance of Joe’s savings account can be reduced by $100 and then his checking account balance increased by $100. The second option is that his checking account balance can be increased and then his savings account balance decreased. But what happens if there’s a system crash between the two updates? Under the first scenario, Joe isn’t happy. He’s lost $100. Under the second example, Joe is very happy. He’s $100 richer, but the bank has now lost $100. What we want is that, in the event of the aforementioned crash, either both accounts must be updated or neither of the accounts updated. To ensure that this happens is the purpose of transactions.

Transactions should follow the ACID rule—that is Atomicity, Consistency, Isolation, and Durability. Atomicity means that either all or none of the update is committed. Consistency means that if the transaction fails, the data is returned to the same state as before the transaction started. Isolation means that one transaction doesn’t know what another transaction is doing. Finally, Durability means that the transaction state is kept, no matter what happens to the system. This is generally handled through the use of a transaction log.

We can implement transactions on our VFP data by using the BEGIN TRANSACTION/END TRANSACTION/ROLLBACK commands. This pseudo-code shows the preceding example:

The transactions in VFP only work with VFP data, and VFP transactions fail the Durability rule of ACID. There’s no transaction logging.

If we’re using SQL Server, we need to use a different mechanism. We can use ADO commands to tell SQL Server when to begin and end a transaction or we can code it in a stored procedure. However, what happens if the savings account is in SQL Server and the checking account data is in Oracle? SQL Server transactions will only work on SQL Server, and Oracle transactions will only work on Oracle. We need a single transaction that will work against both databases. That’s where the Distributed Transaction Coordinator (DTC) comes in.

Using the DTC

The DTC allows us to have transactions that cross databases. This means that we can have data in both SQL Server and Oracle that will be updated by the same transaction. Under MTS and VFP 6, Fox data couldn’t participate in a DTS transaction. (This changes under COM+ and VFP7. More on that later.) Back to the DTC.

The DTS uses a two-phase commit. Basically, in phase one, DTS asks the database if it can do an update. If all of the databases respond yes to this question, then phase two begins, in which DTS tells the database to update the data. If any of the databases respond with a no, then DTS tells all of the databases to roll back the update.

Let’s look at how transactions were handled under MTS:

Note that when we either commit or abort the transaction, MTS will also release the component. This means that if the very next command in our application needs the component, we have to do another CREATEOBJECT() on the client. Let’s see how this changes in COM+:

In this example, we can either commit or abort the transaction with SetMyTransactionVote, but still keep the instance of the component active until we explicitly call SetDeactivateOnReturn with a .T. parameter.

You might now be wondering where the DTC fits in. COM+ automatically calls the DTC for us. The DTC talks to the database through the use of a Resource Manager. MTS and COM+ ship with Resource Managers for Oracle and SQL Server, but not for VFP. That’s why VFP data couldn’t take part in MTS transactions.

It turns out that Resource Managers are very difficult to implement. So, COM+ has what are called Compensating Resource Managers (CRMs). CRMs are easier to implement than a Resource Manager. By using a CRM we can have our Fox data be involved in DTC transactions.

A CRM consists of two parts, the CRM Worker and the CRM Compensator. These correspond to the two-phased commit of the DTC. A detailed discussion of the CRM is beyond the scope of this article. However, VFP 7 ships with a CRM sample application. You’ll find it in the SAMPLES\COM+\CRM folder under your VFP 7 installation.

Configuring COM+ transactions

Like many of the features in COM+, transactions are managed at runtime. Open the Component Services Manager applet and drill down to one of your components. Right-click on the component and select Properties, and then select the Transactions tab. You’ll see five transaction settings (see Figure 1 and Table 1).

Table 1. Transaction types supported for COM+ components.Expand table

Setting	Description
Disabled	Transactions aren’t needed. Set this when you don’t want the extra overhead of a transaction—for example, a component that doesn’t update any data.
Not Supported	Prevents a component from using a transaction, regardless of the transactional state of the calling component.
Supported	The component participates in the transaction if one is active.
Required	The component participates in the transaction if one is active. If there’s no active transaction, a new one is started.
Requires New	A new transaction is always started.

You’ll also notice the “Override global transaction timeout value” check box. When you select Required or Requires New transactions, this check box becomes enabled. You can then enter the number of seconds the transaction will run before timing out.

That’s it for transactions. In Part 4, we’ll look at a COM+ feature that gives you asynchronous calls: Queued Components.

To find out more about FoxTalk and Pinnacle Publishing, visit their website at http://www.pinpub.com/html/main.isx?sub=57

Note: This is not a Microsoft Corporation website. Microsoft is not responsible for its content.

This article is reproduced from the July 2001 issue of FoxTalk. Copyright 2001, by Pinnacle Publishing, Inc., unless otherwise noted. All rights are reserved. FoxTalk is an independently produced publication of Pinnacle Publishing, Inc. No part of this article may be used or reproduced in any fashion (except in brief quotations used in critical articles and reviews) without prior consent of Pinnacle Publishing, Inc. To contact Pinnacle Publishing, Inc., please call 1-800-493-4867 x4209.

Decorating for the Busy Developer

Article
06/30/2006

Decorating for the Busy Developer

Lauren Clarke

Decorating or “wrapping” an object represents a flexible alternative to subclassing. In this article, Lauren Clarke explains what a decorator is, demonstrates a novel way to implement the pattern in Visual FoxPro, and provides some application ideas.

If you’re like me, your eyes tend to glaze over a bit when object-oriented design pattern terms are thrown about. The word “decorator” is one of those terms, and due in part to the image of Martha Stewart it immediately conjures up, and the complete lack of tasteful decorations in most programmers’ lairs, it leaves one wondering what decorations and programming have to do with each other. Decorator (a noun) is a design pattern that uses aggregation (another OOP term, which means one object holds a reference to another) to “wrap” an object and perhaps provide some additional features not present in the wrapped object. Simply put, a decorator is a class that provides a “skin” around another object to which one wishes to add new responsibilities at runtime. A simple example follows.

Consider the object that SCATTER NAME creates in VFP:

This line of code creates an object with properties that correspond to the fields of the table in the current workarea, and property values corresponding to the values of those fields. This process represents a nice, lightweight alternative to assigning the properties of a custom data object from the fields of a table. However, wouldn’t it be nice if loData could do something other than store field values? It’d be nice if it had methods you could use in your day-to-day life as a developer working with this object. For example, what if it could validate itself, or render itself as an XML string, or save itself? The trouble is that we don’t have access to the internal Visual FoxPro class used to create loData. We can’t create subclasses of it, and even if we could, we couldn’t force SCATTER NAME to use our subclass instead of the base class. So we have an object that we’d like to endow… decorate… with new abilities, and we can’t (or don’t want to) create a subclass to deal with these new responsibilities. So, we’re going to implement a method of extending the abilities of the SCATTER NAME object at runtime. Enter the decorator pattern.

Well, that was a bunch of work (but don’t worry, I’m going to show you a way to avoid most of it). Let’s go over the highlights of this class. First, note that we have a property for each field in our customer table. Also, we have a property oData that will hold a reference to our SCATTER NAME generated data object. Finally, we have a property cFullName that will provide the customer’s full name based on the cFname and cLname fields. Then, we have a bevy of access and assign methods that serve to link the oData properties to the decorator’s properties. With this construct in place, the following expressions will both return the same value:

The access and assign approach ties us to version 6.0 or later of VFP. The alternative is to use GetProp() and SetProp() methods to provide access to the wrapped object. For example, we could have a GetFname() function that would return oData.cFname, but this really makes the wrapper less than transparent, which isn’t desirable. Finally, note that the INIT() method takes as a parameter a reference to the data object to be wrapped by the class. Okay, let’s put our decorator to work.

We’ll dissect the following code snippet line by line:

First, we create a standard SCATTER NAME object. The BLANK keyword indicates the object will be created with empty properties.

Next, we assign our new object a first and last name.

Nothing spectacular so far, but this next line is the point at which the rabbit goes into the hat.

Here, we instantiate a class DecoCust1, the init function of this class takes an object as a parameter, and we send our SCATTER NAME generated loData object for this parameter. DecoCust1 wraps itself around loData and augments its abilities. Note that we reuse the loData variable name to store a pointer to our new instance of DecoCust1. This isn’t necessary, but since DecoCust1 will seamlessly wrap our data object, presenting all of its original properties as if it were the old loData, it’s natural to do so. In our case, DecoCust1 has an IsValid() method, and we can use this to validate Mr. Yellow.

If we pass this test, a record is added to the current table and we fire the Save() method, which will save the record to the table.

Now that the object has been created and is decorated with additional properties and methods, we can check our record with IsValid(), save it with Save(), render it to XML with toXML(), and all the while we can still reference the objects’ original properties:

And we also have an additional property calculated from underlying fields.

To summarize, we have a class DecoCust1, which adds a cFullName property, IsValid(), Save(), and toXML() methods (and potentially many other useful methods) to our SCATTER NAME generated data object. From the developer’s standpoint, there’s very little practical difference between the wrapper and a bona fide subclass of the Visual FoxPro data object class. The key point, of course, is that you can’t subclass Visual FoxPro’s data object class. Also note that these abilities were added at runtime, meaning we have the option of adding these abilities if and when they’re needed without instantiating a large feature-ridden class each time a record object is needed.

Another real-world sample of a decorator, csZIP/csUnZip, is available in the accompanying Download file. It decorates the popular DynaZip utility to provide some simplifications and extensions that are helpful when using the utility from within VFP.

Subclasses vs. decorators

Decorators offer an alternative to subclassing, but they must be used judiciously. The advantages come from the fact that you can gain subclass-like behavior for classes that you can’t actually subclass. Also, you’re given more flexibility at runtime to endow your objects with abilities only if they need it to fulfill the current task. In our example, there might be many places in an application where the base FoxPro data object will suffice. This being the case, it would be a shame to have to instantiate and use a complicated and expensive class where the lightweight class would do. Decorators offer “pay as you go” options where one can add functionality as needed. It’s possible to nest decorators inside decorators. If we decided that mixing the validation code and the XML rendering code in one class made it too large and inflexible, we could create a separate decorator for each task. For example, we could start with the basic data object:

Then, if necessary, endow it with the ability to validate its properties:

Then, if needed, we could decorate again and gain some rendering functionality:

Which would allow us to do things like this:

or this:

And, unless you need to validate and render your data object every time you use it, you can save a lot of overhead by avoiding the giant do-everything data class.

The following lists summarize the pros and cons.

Advantages of decorators:

They allow extension of classes that we can’t directly subclass.
They allow us to avoid deep class hierarchies.
They provide a pay-as-you-go option, which avoids instantiating large feature-ridden classes when few of the features are needed.

Disadvantages of decorators:

Pass-through code must be maintained.
Passing requests through to the decorated component requires a performance hit.
They can complicate debugging.

From the developer’s perspective, the single most important issue here is the maintenance of pass-through code. The access and assign code must be maintained in concert with the wrapped object. In our example, this means that each time the structure of the table changes, we’ve got some work to do in our decorator class definition. This issue is exacerbated when we’re wrapping classes that have methods as well as properties, as we have to write pass-through code for each method. In short, if the interface of the wrapped object changes, so must the wrapper. Until recently, this fact was enough to really cool one’s feet to the idea of using the decorator in anything but the most dire situations. However, version 6.0 of Visual FoxPro gives us an opportunity to generalize decorator classes and completely eliminate this fragile use-case specific pass-through code. Our rescue comes in the form of the THIS_ACCESS method.

THIS_ACCESS overview

THIS_ACCESS is a method that can be added to any subclass in VFP. This method will fire every time the class is accessed. This means that every time a property is set or accessed or a method is called, the THIS_ACCESS method will fire prior to that action taking place. THIS_ACCESS takes as a parameter the name of the member being accessed. (Side note: It’s too bad that THIS_ACCESS only takes the called member as a parameter; if one could also access the value being sent [in the case of a property assignment] or the parameters being sent [in the case of a method call] inside the THIS_ACCESS method, it would open a world of possibilities, but that’s off topic for this article.) THIS_ACCESS must also return a reference to the object being accessed. It’s this last requirement that we leverage to implement an almost codeless delegation scheme for a generic decorator class. Let’s redo our prior example using this new approach.

Redecorating with THIS_ACCESS

Here’s what the class definition for DecoCust might look like when we utilize THIS_ACCESS:

That’s it. Notice the substantial reduction in lines of code from our previous DecoCust1 example. The “big idea” here is the THIS_ACCESS method that first checks to see whether the requested member belongs to the decorator class, and, if not, a reference to the wrapped data object is returned. This way, the decorator can decorate by adding functionality like this IsValid() while forwarding requests for the oData properties directly to the oData object.

Also, notice that the DecoCust2 class is very generic. The IsValid() and toXML() methods could be removed and we’d have a nice BaseDeco class to wrap any component that we could subclass to add things like IsValid() for specific implementations.

Paying the piper

Wrapping a class has some costs in terms of both development and runtime. The development costs come from the need to keep the interface of the wrapper synchronized with the interface of the wrapped component. If you choose to manually maintain the interface, this can be a costly proposition—especially if the wrapped class is changing often. Using the aforementioned THIS_ACCESS trick can vastly reduce your development load, as the interface will be updated automatically. However, since THIS_ACCESS fires each time the object is used, there’s a runtime cost to be paid for this approach. Table 1 will give you an idea of the runtime costs for these different approaches.

Table 1. The different approaches and their associated runtime costs.Expand table

Task	Subclass	Deco1	Deco2
Instantiation	1	1.81	2.66
Access decorator property	1	0.95	9.90
Assign decorator property	1	2.20	11.34
Call decorator method	1	0.96	4.48
Access decorated property	1	0.96	6.81
Assign decorated property	1	1.14	5.37
Call decorated method	1	2.15	4.88
Key: • Subclass = no decorator, subclass only. • Deco1 = a hardwired decorator with explicit pass-through code. • Deco2 = a decorator implemented with THIS_ACCESS.

This table has been normalized to be machine-independent and more readable. For each task, the “Subclass” option has been given a weight of 1 and the others scaled accordingly. So, for example, Deco2 takes 9.90 times longer to access a property than a traditional subclass. To get actual time values for your system, just run the perfcheck.prg provided in the Download file.

Some of these factors look pretty alarming, but keep in mind the times we’re talking about here. My system, a PIII that’s limping along at 500 Mhz, takes 0.000006 seconds to access a property from Deco1, and a staggering 0.00003 to access the same property through a decorator using THIS_ACCESS (Deco2). In a real use-case, say a middle-tier data object, an application might access a data object 100 times to serve a user’s request. In this situation, the THIS_ACCESS method represents a cost of no more than 0.003 seconds in our benchmark classes. Considering the THIS_ACCESS method might eliminate hundreds of lines of high-maintenance pass-through code, this might represent a good tradeoff. However, these results do make one pause to consider carefully where to implement these techniques.

WITH/ENDWITH and GATHER gotchas

If you plan on using a THIS_ACCESS decorated class in a WITH/ENDWITH loop, you’ll be in for a surprise. VFP exhibits some peculiar behavior in this area. In the April 2001 issue of FoxTalk, Randy Pearson wrote an article on the advantages of the WITH/ENDWITH command. It’s likely you’ll want to use this construct with a decorated class at some point. The trouble is that VFP won’t let you. The following code won’t fire the THIS_ACCESS method of loData and will result in an error:

A workaround is to reference the decorated component directly in the WITH construct:

There are some differences in the behavior here between VFP 6 and VFP 7 Beta 1. Both are odd and not really consistent with the documentation on access and assign methods. There’s a program in the Download file you can use to explore the differences.

In addition to this, while the GATHER NAME command works fine with the property-level access methods, it seems to ignore the THIS_ACCESS method at this time.

Conclusion

The decorator pattern offers a nice alternative to subclassing. The THIS_ACCESS method of building decorators allows us to avoid writing reams of pass-through code when building decorators in VFP. This convenience comes with a performance price, but in many situations I think the price is more than justified. I’ll leave you with one possibly interesting diversion. Look up “multiple inheritance” in a good general OOP reference. Then, take a look at our DecoCust2 class, and consider the possibility of aggregating more than one object at a time and replacing the IF/THEN in the INIT() clause with a CASE statement. Bon voyage!

(Lauren thanks the http://fox.wikis.com community for their help in refining and testing some of the ideas presented in this article.)

Sidebar: References

Design Patterns, Elements of Object Oriented Software, by E. Gamma, R. Helm, R. Johnson, and J. Vlissides (Addison Wesley, 1994, ISBN 0201633612).
“Simulating Multiple Inheritance,” by Michael Malak, in the April 2001 issue of Journal of Object-Oriented Programming.

To find out more about FoxTalk and Pinnacle Publishing, visit their website at http://www.pinpub.com/html/main.isx?sub=57

Note: This is not a Microsoft Corporation website. Microsoft is not responsible for its content.

This article is reproduced from the August 2001 issue of FoxTalk. Copyright 2001, by Pinnacle Publishing, Inc., unless otherwise noted. All rights are reserved. FoxTalk is an independently produced publication of Pinnacle Publishing, Inc. No part of this article may be used or reproduced in any fashion (except in brief quotations used in critical articles and reviews) without prior consent of Pinnacle Publishing, Inc. To contact Pinnacle Publishing, Inc., please call 1-800-493-4867 x4209.

TYPE() to StringType()–Bridging a Gap

Article
06/30/2006

TYPE() to StringType()—Bridging a Gap

Pradip Acharya

Intuitively, you’d think that the string “123” represents a number and the string “ABC” is of type character. Right? Not according to the standard TYPE() function in VFP. If ABC happens to be a date variable, for example, the type of “ABC” will be returned as D. Yet, in many situations, we need to know the data type of the contents of an unknown string. In this article, Pradip Acharya looks at the problems associated with determining the data type of a string and describes the creation of a new function, StringType(), suited for this purpose.

One of my customers called and said, “When I type an X in your program, I get an error message, and nothing happens. Am I doing something wrong?” I rushed over and discovered that, as always, the customer was right, and I needed to create a new function to get the customer going again.

A generic text input box was presented to the user for entering a search parameter for scanning a specific column in a table for the presence of such a value. For example, if the user needs to look at the invoices created on a certain date, a date will be typed in. To look for all five HP motors, one would enter a numeric value of “5” and so on. I had validation code that ensured that if the user entered data that clearly wasn’t of the same type as the field to be scanned, he or she would be notified and asked to re-enter the value. For a date type field, the user incorrectly entered an X. My validation, for some reason, failed to alert the user, and an unhandled data type mismatch error led to the previously noted disruption of work.

Dual use of the TYPE() function

Simply put, the TYPE() function in VFP accepts as input a character string and determines whether a memory variable or a field exists by that name and, if so, what its data type is. However, this description is deceptive and limiting. More strictly, TYPE() resolves the string as an expression and checks to see whether the result makes any sense.

To make sure that the slate is clean:

Now let’s define a memory variable:

?TYPE(“XYZ”) will display D. In this mode, the TYPE() function determined the data type of a prevailing memory variable (in scope). Next, if I do ?TYPE(“123”), I’ll get N. Obviously, in this second instance, my intention has been to use the TYPE() function to check the nature of a string and not the existence of a variable, field, object, or property.

In trying to use the TYPE() function for the two unrelated purposes, we fall into a trap. In the case study presented earlier, if the user types 123, I’ll correctly determine that the type of the value entered is numeric. If, however, the user types XYZ instead of the desired data type C, I’ll incorrectly determine the data type to be D because a date variable already exists by the name of XYZ. This was the reason behind the failure of my validation code that then led to a data type mismatch error. The target table field was of type date; the user typed a character instead of a date, and I incorrectly inferred that a date had been typed in because a date variable by that name existed and TYPE() fooled me.

To make matters worse, if the user enters a perfectly valid date such as 07/25/2001 (assuming that the date format is set to MDY), I’ll incorrectly determine that the data type of the string is N and not D. Why N? Because 07/25/2001 evaluates to 0.0001399 as an expression, having interpreted each “/” as a division operator—unintuitive indeed! What this proves is that using the TYPE() function to determine the data type of the content of a string is a misapplication of the TYPE() function. I created a new function, StringType(), to determine the type of data contained within a string, based on a string parsing strategy, and at the same time to internally take advantage of the TYPE() function.

Function StringType()

The purpose of this function is to determine the type of data contained in a text string that’s passed as the only argument. Case is immaterial, and leading and trailing white space, not just spaces, are ignored (see Table 1). White space is defined in Listing 1. (Note that there’s no U for undefined category.)

****

Table 1. The function returns a single-character uppercase letter.Expand table

L	Logical
N	Numeric
I	Integer
Y	Currency (for example, $53.27)
D	Date, either strict or conforming to the prevailing date format, but independent of SET CENTURY
C	Not one of the above, character, default

****

Listing 1. Code for function StringType().

This function can be useful in any situation where an unknown string is encountered and one needs to determine what kind data it contains prior to taking further action. In addition to Listing 1, the file STRTYPE.PRG is available in the Download file. Table 2 presents a comparison of the output.

****

Table 2. Comparison of output.Expand table

String	TYPE()	StringType()
“.T.”	L	L
“.False.”	U	L
“123.52”	N	N
“123”	N	I
“$53.68”	U	Y
“01/01/01”	N	D
“//”	U	D
“123abc”	U	C
“m.aVarName”	Depends	C

An empty string

An empty string or a string made up of white space isn’t interpreted. The function returns “C.” You may reserve a word BLANK, for example, and ask the user to enter BLANK if a distinction is to be made between no value entered and an intended empty value. Then test for “BLANK” on return. This isn’t done inside the StringType() as supplied, although you might wish to incorporate such a test inside the code yourself and assign a special return character—perhaps E.

Data type logical

The function will return L if the input string is one of the following:Expand table

.T.

.F.

.True.

.False.

The inclusion of the last two is an extension.

Data types numeric and integer

Normally, the function will return “N” if the string contains a number. As an extension, it will return “I” if the value entered is truly an integer. “123” and “123.” will both return “I”. The distinction between “N” and “I” might be useful, for example, prior to SEEKing an integer field of Invoice numbers. Under special circumstances, strings containing character data might be incorrectly identified as numeric in the presence of embedded operators. See the “Limitation” section later in the article.

Data type currency

Since parsing is involved, we might as well make a special case out of numeric data when the leading character is a $ sign. For example, “$ 52.68” will return Y instead of N. Probably no one will use this option.

Data type date

Correctly determining a string to be of type date is a vexatious problem. The problem is split into two parts. What’s an empty date? And what’s a valid date? If the input string is enclosed in curly brackets—that is, {…}—the result returned is always “D” regardless of the validity of what lies inside the brackets. In keeping with VFP convention, an input string like “{abc}” will return a value of “D.”

Only two character representations are recognized by StringType() as a blank date:

• //
• {}

In-between white space is ignored. Therefore, /ss/ or { ss} will also return “D”.

As for valid dates, internally, the TYPE() function is put to use. The problem is that VFP is highly forgiving in interpreting dates. For example, ?{4.7} will print as 04/07/2001, whereas, for our purposes, we’d like to interpret 4.7 as a numeric value and certainly not a date. Accordingly, reasonable parsing constraints have been introduced in StringType() before a string can be declared to be a date. For example, there must be two and only two identical separator characters, and the rest must be digits. Dates entered in the strict date format will also be correctly identified as date.

Limitation—no check for operators

In this version of StringType(), no attempt has been made to isolate an individual data item from an expression with embedded operators. “53.86” and “2+7” both will return N (or I). Should we interpret a string such as 27*3 as “C” or “N”? I don’t know. Furthermore, StringType() normally doesn’t depend on which work areas are open. Not checking for operators leaves a loophole in this regard. An input string such as “53 * Invoice.Total” will produce unpredictable output depending on whether Invoice.Total is a visible field or not. If you code a version that checks for operators and expressions and closes this loophole, I’ll be happy to get a copy.

A wish

TYPE() as it stands identifies a valid property of an object. If TYPE(“m.oMyObject.Size”) returns “U” or “O,” it’s not a valid property. Otherwise, the property exists. As a logical and consistent extension to this interpretation, it makes sense if TYPE() also identifies an unprotected method and returns, for example, “H” if a method by this name exists for the object. I believe this generalization will be useful.

Conclusion

The standard TYPE() function will return the data type of a variable but isn’t suitable for determining the data type of the contents of a string. The new function StringType() has been designed specifically for this purpose, with a few limitations. In a future article, I’ll present a utility for generic output formatting of any type of value into a printable character string.

To find out more about FoxTalk and Pinnacle Publishing, visit their website at http://www.pinpub.com/html/main.isx?sub=57

Note: This is not a Microsoft Corporation website. Microsoft is not responsible for its content.

This article is reproduced from the September 2001 issue of FoxTalk. Copyright 2001, by Pinnacle Publishing, Inc., unless otherwise noted. All rights are reserved. FoxTalk is an independently produced publication of Pinnacle Publishing, Inc. No part of this article may be used or reproduced in any fashion (except in brief quotations used in critical articles and reviews) without prior consent of Pinnacle Publishing, Inc. To contact Pinnacle Publishing, Inc., please call 1-800-493-4867 x4209.

Create Modern Interfaces with VFP 7

Article
06/30/2006

Create Modern Interfaces with VFP 7

Doug Hennig

It seems that every new version of Microsoft Office changes user interface standards. Whether you like it or not, your users expect your applications to keep up with this ever-moving target. Fortunately, VFP 7 adds new features that make it easier to create interfaces similar to Office 2000. Doug Hennig explains.

In addition to new language features (see my “Language Enhancements in VFP 7” series of articles in the January to June 2001 issues of FoxTalk), database events, support for COM+, Web Services, and a ton of other new features, VFP 7 provides some user interface improvements, including hot tracking and modern-looking toolbars and menus.

Hot tracking

Hot tracking means controls appear flat (rather than the three-dimensional appearance we’re used to) but change appearance as the mouse pointer moves over them. Most controls will then appear sunken (the way they normally appear with hot tracking off), except for check boxes, option buttons, and command buttons, which appear raised. For an example of hot tracking, look at the toolbars in Microsoft Office 2000 applications. As you can see in Figure 1, toolbar controls appear flat (for example, the command buttons have no outlines) until you move the mouse over them.

Hot tracking is easy to turn on in VFP 7: Simply set the SpecialEffect property to 2 (for check boxes and option buttons, you also have to set Style to 1-Graphical). For control classes that might have to be used in earlier versions of VFP, you should set this property programmatically (such as in the Init method) rather than in the Property Window to prevent an error when the control is used in those versions. Here’s an example (taken from SFToolbarButton in SFBUTTON.VCX):

clVFP7ORLATER is a constant defined in SFCTRLS.H, the include file for SFToolbarButton, as follows:

Since version(5) was added in VFP 6, the type() test and use of evaluate() in this statement ensure that it will work even in VFP 5.

You can create other types of effects with code in the new MouseEnter and MouseLeave events. For example, you can set This.FontBold = .T. in MouseEnter and This.FontBold = .F. in MouseLeave to make a control appear bolded when the mouse is over it. You can also change the foreground or background color, and do pretty much anything else you want in these events.

SwitchboardButton in MYCLASSES.VCX is an example. It’s used as a button in “switchboard” forms, forms that provide quick access to the major functions of an application. In VFP 7, as the user moves the mouse pointer around the form, the SwitchboardButton object under the mouse is surrounded with a blue outline (see Figure 2 for an example). SwitchboardButton is actually a container class with an image and a label. Its BorderColor is set to 0, 0, 255 (blue) and its Init method sets the BorderWidth to 0 (it’s left at the default of 1 in the Property Window so you can see it in the Class or Form Designers). The MouseEnter event sets BorderWidth to 3 and MouseLeave sets it back to 0.

In addition to the SpecialEffect property and MouseEnter and MouseLeave events, command buttons have a new VisualEffect property. This property, which is read-only at design time, allows you to programmatically control the raised or sunken appearance of the control at runtime. Although you won’t often use this, it’s handy when several buttons should change appearance as a group. We’ll see an example of that later.

Although you can use hot tracking wherever you want, I personally don’t care for hot tracking except in controls in toolbars (none of the dialogs in Microsoft Office use hot tracking, for example). So, rather than setting SpecialEffect to 2 in my base classes (those in SFCTRLS.VCX), I’ll do it in specific subclasses that I use for toolbars.

To see an example of hot tracking for different types of controls, run TESTHOTTRACKING.SCX and see what happens as you move the mouse over each control.

Toolbars

Like other “modern” applications, toolbars in VFP 7 now have a vertical bar at the left edge when docked to provide a visual anchor to grab to move or undock the toolbar (see Figure 1). Another improvement related to toolbars is the addition of a Style property to the Separator base class; setting this property to 1 makes a Separator appear as a vertical bar at runtime (at design time, Separators are still invisible, which is kind of annoying). As with hot tracking, you might want to set this property programmatically to prevent problems with earlier versions of VFP; I use the following code in the Init method of SFSeparator (in SFCTRLS.VCX):

Figure 3 shows the same toolbar running in VFP 6 and 7. The VFP 7 version looks and acts like a toolbar in a more modern application.

A new style of toolbar button showing up in more and more applications is the dual button/menu control. Figure 4 shows an example of such a button, taken from Internet Explorer 5.5. Clicking on the left part of the control (the button with the image) causes an action to occur, while clicking on the down arrow displays a drop-down menu of choices. Another place I’ve seen such a control used is in West Wind Technologies’ HTML Help Builder to open Help projects. Clicking on the button displays an Open File dialog, while clicking on the down arrow displays a “most recently used” (or MRU) list of files. The advantage of this control is that it doesn’t take up much screen real estate, yet it can have a large list of choices.

SFBUTTON.VCX has a couple of classes used to create such a control. SFDropDownMenuTrigger is a subclass of SFToolbarButton that’s sized appropriately and displays a down arrow (Caption = “6,” FontName = “Webdings,” FontSize = 6). It also has assign methods on its FontName and FontSize properties so they aren’t inadvertently changed programmatically by something like SetAll(). SFDropDownMenuButton is based on SFContainer, our container base class in SFCTRLS.VCX, and it contains an SFToolbarButton object named cmdMain and an SFDropDownMenuTrigger object named cmdMenu. The MouseEnter and MouseLeave events of each button set the VisualEffect property of the other button to 1 and 0, respectively, so the buttons’ hot tracking are synchronized. The Click event of cmdMain calls the ButtonClicked method of the container, which is empty since this is an abstract class and the desired behavior must be coded in a subclass or instance. The MouseDown event of cmdMenu has the following code to display the drop-down menu:

Since SFContainer already has methods and code for handling shortcut menus (see my column in the February 1999 issue of FoxTalk, “A Last Look at the FFC”), why reinvent the wheel? As a refresher, the ShowMenu method of SFContainer instantiates an SFShortcutMenu object (defined in SFMENU.VCX), which is an adaptation (not subclass) of the FFC _ShortcutMenu class. SFShortcutMenu handles all of the work of displaying a shortcut menu; you just call the AddMenuBar and AddMenuSeparator methods to define the bars in the menu, and then call the ShowMenu method to display it. SFContainer.ShowMenu calls the ShortcutMenu method to do the actual work of defining the bars (that method is abstract in SFContainer).

However, one issue SFDropDownMenuButton has to address that SFContainer doesn’t is menu placement. SFShortcutMenu automatically places the menu at the current mouse position, but if you look at Figure 4, you’ll notice the menu appears directly below the control, aligned with its left edge. To support that, I added nRow and nCol properties to SFShortcutMenu so you can control the position of the menu; if they contain 0, which they do by default, SFShortcutMenu will figure out where the menu should go, so the former behavior is maintained. The ShortcutMenu method of SFDropDownMenuButton, however, has to place the menu at the right spot, so it calculates the appropriate values for the nRow and nCol properties.

What’s the right spot? That depends on if and where the toolbar hosting the control is docked. If the toolbar is docked at the right or bottom edges, the menu has to be placed to the left or above the control so it appears inside the VFP window. Otherwise, it has to be placed below and at the left edge of the control. The code to perform these calculations is fairly long and complex (I adapted—okay, ripped off <g>—the code from NEWTBARS.VCX in the SOLUTION\SEDONA subdirectory of the VFP samples directory), so it isn’t shown here.

To use SFDropDownMenuButton, drop it or a subclass on a toolbar. To see an example, look at the instance named ColorPicker in the MyToolbar class in MYCLASSES.VCX, included in the Download file. ColorPicker is just a simple demonstration of this control; it allows the user to change the background color of the active form from either a pre-selected list of colors (the drop-down menu) or a color dialog (when you click on the button). The ButtonClicked method, called when the user clicks the button, displays a color dialog and sets the background color of the active form to the selected color:

The ShortcutMenu method has the following code:

toMenu is a reference to the SFShortcutMenu object. The first parameter for the AddMenuBar method is the prompt for the bar, and the second is the command to execute when that bar is chosen.

Menus

Modern applications usually provide many different ways to perform the same action: main menu selections, toolbar buttons, shortcut menu selections, and so on. I’ve already discussed toolbars, and the SFShortcutMenu class makes it easy to create shortcut menus for every form and object in your application. So, let’s talk about the main menu.

Menus haven’t changed much in FoxPro since FoxPro 2.0 (although in my August 2001 column, “Objectify Your Menus,” I presented a set of classes that make it easy to create object-oriented menus). New in VFP 7, however, are the abilities to specify pictures for bars (either the picture for a VFP system menu bar or a graphic file) and to create inverted bars that only appear when the user clicks on a chevron at the bottom of a menu popup (“MRU” menus, although the meaning of MRU here is different from how I used it earlier). These features allow us to create Office 2000-style menus.

Specifying a picture is easy. In the VFP Menu Designer, click on the button in the Options column for a menu bar, and in the Prompt Options dialog, select File if you want to specify a graphic file or Resource if you want to use the picture for a VFP system menu bar. If you select File, you can either enter the name of the file in the picture text box or click on the button beside the text box and select it from the Open File dialog. If you chose Resource, either enter the name of the VFP system menu bar (for example, “_mfi_open”) or click on the button and select it from the dialog showing the prompts of system menu bars. In either case, a preview of the picture is shown in the Prompt Options dialog. The settings result in the PICTURE or PICTRES clauses being added to the DEFINE BAR command that will ultimately be created for this bar. If you’re using the OOP menus I presented in August, set either the cPictureFile or cPictureResource property of an SFBar object to the desired value.

The MRU feature is more difficult to use, and much more difficult to implement in a practical manner. The DEFINE BAR command has new MRU and INVERT clauses, but because there are no specific options for either clause in the Menu Designer, you end up having to use a trick: Enter “.F.” followed by either “MRU” or “INVERT” in the Skip For option for the bar. VFP 7’s menu generator, GENMENU.PRG, is smart enough to see that you’re really using the Skip For setting as a way of sneaking other clauses into the DEFINE BAR command that the generator will create, so it leaves off the SKIP FOR .F. part of the command.

However, that’s only the beginning. You’re responsible for managing what happens when the user selects the MRU bar (the chevron at the bottom of the menu) yourself. Typically, you’ll remove the MRU bar from the menu and add bars with the INVERT clause to the menu, but since the Menu Designer doesn’t create those bars for you, you have to code the DEFINE BAR statements yourself (although you could create the desired bar in the Menu Designer, generate the MPR file, copy the DEFINE BAR statement for the bar from the MPR, and then remove it in the Menu Designer). Also, once the user has selected one of the inverted bars, you have to add the MRU bar back to the menu and remove the inverted bars, except perhaps the selected one, which you may decide to leave in the menu as Office applications do. But then you have the complication of changing it from an inverted bar to a normal one and not adding that bar the next time the user selects the MRU bar, and that’ll only last until the user exits the application. See what I mean by “much more difficult to implement in a practical manner”?

I can’t think of any application I’ve written in the past 20 years that was complex enough to actually use this type of MRU feature, but at least the OOP menu classes I presented in August manage a lot of this stuff for you. Set the lMRU property of an SFPad object to .T. if that pad should have an MRU bar in it, and set the lInvert property of any SFBar object to .T. to have that bar appear when the MRU bar is selected and disappear after a menu selection is made. You’ll have to subclass SFPad if you want different behavior, such as changing an inverted bar into a normal one if it’s selected.

A more useful version of an MRU feature is the one I referred to earlier—a list of things the user has accessed recently. Office 2000 applications use this: The bottom of the File menu shows a list of the most recently accessed documents. Most VFP applications don’t use the concept of “documents,” but they do use records. It might make sense in some applications to put the most recently accessed records at the bottom of a menu so users can quickly return to a record they were working with before. Rather than automatically doing that, you might want to provide a function the user can select to add the current record to the MRU list.

The sample application included in the Download file has an example of such a feature. First, a button in the MyToolbar class, used as the toolbar for the customers form, allows the user to “bookmark” the current record; it does so by calling the Bookmark method of the active form. That method in CUSTOMERS.SCX has the following code:

This code expects that the Bookmark class, which we’ll look at in a moment, has been instantiated into a global variable called oBookmark. The AddBookmark method of that class expects two parameters: the command to execute when the bookmark is selected and the caption for the bookmark. In this case, the command tells VFP that if the active form is the customers form, call the Seek method of that form with the customer’s CUST_ID value (that method positions the form to the specified key value); if there’s no active form or it isn’t the customers form, call the DoForm method of the application object, telling it to run the customers form and passing the CUST_ID value (the Init method of the customers form accepts an optional CUST_ID value and calls the Seek method if it’s passed). The company name is used as the caption for the bookmark.

The Bookmark class, in MYCLASSES.VCX, is a simple class based on SFCustom. It has a two-dimensional array called aBookmarks to store the bookmarks; the first column is the command to execute and the second is the caption. The nMaxBookmarks property determines how many bookmarks can be stored. The AddBookmark method adds a bookmark to the array and to the bottom of the File menu. Here’s the code:

Before the first bookmark is added to the File menu, a separator bar is added above the Exit bar. Then bars for the bookmarks are added above that separator. The cBarPosition property is used to control the bar positions.

Figure 5 shows an example of the File menu after I bookmarked four records. Selecting a bookmark opens the customers form (if necessary) and displays the chosen record.

The Bookmark class has a couple of other methods, SaveBookmarks and RestoreBookmarks, that save and restore the bookmarks, using BOOKMARKS.DBF. These methods ensure that the user’s bookmarks are persistent between application sessions.

Tying it all together

The sample application shows all of the techniques discussed in this article. DO MAIN starts the application. MAIN.PRG instantiates some objects, including a simple application object and the Bookmark class, and creates a menu for the application. It then runs the SWITCHBOARD form and issues a READ EVENTS. The only functions in the menu and switchboard that do anything are Customers (which runs CUSTOMERS.SCX) and Exit.

The switchboard form uses the SwitchboardButton class mentioned earlier to show hot tracking. The menu shows the use of MRU and inverted bars, includes pictures for some bars, and demonstrates the use of most recently used (bookmarked) records. The customers form isn’t fancy, but the toolbar it uses shows the SFDropDownMenuButton class (as a color picker), includes a button to bookmark the current record, and demonstrates the new features of VFP 7 toolbars, including buttons with hot tracking and vertical separator bars.

VFP 7 has several new features that make it easier to create applications that look and act like Office 2000. Of course, Office XP raises the bar yet again, but for now, our applications can look more modern than VFP 6 applications could.

To find out more about FoxTalk and Pinnacle Publishing, visit their website at http://www.pinpub.com/html/main.isx?sub=57

Note: This is not a Microsoft Corporation website. Microsoft is not responsible for its content.

This article is reproduced from the October 2001 issue of FoxTalk. Copyright 2001, by Pinnacle Publishing, Inc., unless otherwise noted. All rights are reserved. FoxTalk is an independently produced publication of Pinnacle Publishing, Inc. No part of this article may be used or reproduced in any fashion (except in brief quotations used in critical articles and reviews) without prior consent of Pinnacle Publishing, Inc. To contact Pinnacle Publishing, Inc., please call 1-800-493-4867 x4209.

Become the Master of All You Survey–Using XML as a Flexible Data Capture and Retrieval Medium

Article
06/30/2006

Become the Master of All You Survey–Using XML as a Flexible Data Capture and Retrieval Medium

Andrew Coates

Customer Relationship Management (CRM) systems often require that a survey or script be played for a particular customer while an agent is on the phone with them. Often, the exact content of the survey or script depends on the type of customer. In this article, Andrew Coates develops a system for capturing and retrieving such data. This technique uses XML as the storage medium for the answers to the questions and displays the enormous flexibility afforded by the use of a standard that is at once both free-form and structured.

I recently was asked to retrofit an existing Customer Relationship Management system with the ability to capture information that my client wanted to gather from a targeted group of his customers via a telephone survey. My first thought was to add a new table to the database with a one-to-one relationship to the main table and a field for each question in the survey, as shown in Figure 1. This was probably the simplest approach, but on further reflection I realized that it lacks flexibility should my client ever want to undertake additional surveys.

My next thought was to still have a table specific to the survey, but to have a one-to-many table allowing the entity to be linked to many survey tables. This would add some flexibility to the system in that new surveys could be added by adding a new table and adding rows to a survey master table. Information about which table referred to which survey could be stored in a survey master table, and information about which companies were eligible for which survey could be stored in a many-to-many table. This approach is illustrated in Figure 2.

The downside to the second approach is that every time a new survey is added, a new table has to be added to the database. In addition, if a survey needs fine-tuning by adding or changing questions, then the data structure needs to be updated. While these aren’t insurmountable problems, I’d rather not have to muck around with the data structure every time my client wants to tweak the survey.

What I needed was a flexible way of storing answers to survey questions that could still be retrieved in a structured way. I decided to store the answers directly in a text (or memo) field in the many-to-many table. To make sure that the data was still retrievable in a sensible manner, I decided to use XML as the storage format within the text field. The final layout of my database is shown in Figure 3.

Data—the object of my desire

The architecture I decided on for this project was one of data objects. Each set of answers to a survey is represented by a data object that has a property for each answer. The object is then converted to and from an XML representation using Rick Strahl’s ObjectToXML and XMLToObject from his (free) wwXML library. I’ve included the version of wwXML (with permission—thanks, Rick) that was current at the time of this writing in the accompanying Download file, but I strongly suggest that you visit Rick’s site (www.west-wind.com) to check whether there’s a more recent version. Rick’s constantly adding great stuff both to existing libraries and as completely new sets of useful things.

As a companion to the data objects, there’s a GUI class. This class instantiates the appropriate data object and then the data object’s properties as control sources for its various controls. The GUI class itself does no data manipulation or handling (apart from displaying the data and allowing the user to enter or change answers). Instead, it calls the methods of the data object, which knows how to load and save itself from and to the XML data on the back end.

Data object abstract class

Both the data object and the GUI object are defined in the first instance as abstract classes—that is, classes that are only ever subclassed, never themselves instantiated. The data class standard properties and methods are shown in Table 1. ******

Table 1. Methods and properties of the data object abstract class.Expand table

Property/Method	Description
LoadData()	Loads the XML data from the back end for the SurveyID/CompanyID combination specified in the properties.
SaveData()	Persists an XML representation of the object’s properties to the back end.
CreateCursor()	Creates a cursor with a field of the same name and of the appropriate type for each data property of the class.
cComments	Standard free text field available in all surveys.
cConnectString	Connect string for use when instantiating the object and connecting to a remote back end.
nCompanyID	ID of the company to which this set of answers applies.
nSurveyID	ID of the survey from which this set of questions is taken.
tLastUpdated	Last date/time this survey was saved for this CompanyID/SurveyID combination. Note that the default value is an empty time. You can’t just use {} for this, as this is interpreted as an empty date and the parser chokes on time values later on. You need to convert the empty date into an empty time like this: =DTOT({}).

The code for the Init() method is shown in Listing 1.

****

Listing 1. The data object’s Init() method.

When the object is instantiated, the Init code accepts two parameters. The first parameter is an integer representing a handle of an already established connection to a back-end data source via SQLCONNECT() or SQLSTRINGCONNECT(). This gives the object an opportunity to share a connection and thus reduce the resource requirements of the application. The second parameter (which is only used if the connection handle passed is non-numeric or <= 0) allows the overriding of the SQL connect string used to establish a connection to the back end if there’s no handle passed.

If there’s no connection handle passed, the data object’s first job is to establish a connection to the back end. If it can’t do this, there’s no use continuing and it bails out. Next it attempts to create an instance of the wwXML helper class. This class is vital for loading and saving the data to the back end, so again, if it can’t create an instance, it just bails out.

The grunt work of the object is done by the LoadData() and SaveData() methods, shown in Listing 2 and Listing 3, respectively.

****

Listing 2. Loading data from the back end.

****

Listing 3. Saving the answers back to the database.

If the method is passed XML as a parameter, it just uses that to load the values into the properties of the object (we’ll get to why this is useful a little later on). To load data from the back end, the method first checks that the company is listed for this survey. It then generates a SQL statement to retrieve any currently stored data for this company/survey combination. Finally, if there were already answers stored in the XML field, then the values are transferred to the data object’s properties with the single line:

This is the powerhouse of the method. This single line of code transfers each property’s stored value from the XML. There are a couple of cool things to note here:

If the property’s been changed or added since the data was persisted to the table, the default value is used—there’s no requirement to go back through the data retrofitting changes to the survey. (Of course, it’s possible you may want to do some translations for business reasons, but the architecture we’ve used means that it’s not required from a technical standpoint.)
Deleting a property from the data object means that the data for that property simply won’t appear in the new version of the object, and next time the object is persisted to the table, the deleted data will simply disappear.

Saving the properties in a data object is just as simple as loading them. Again the powerhouse of the method is a single line:

This takes the properties in the current object and converts them to an XML representation. A sample of the XML generated by this call is shown in Listing 4.

****

Listing 4. Survey answers stored in XML format.

The rest of the method simply writes the XML string into the text field. Note that I’ve used a parameterized update command:

The ?lcXML tells the ODBC connection to ask VFP for the value of the lcXML variable. Using this construct eliminates a large number of issues with encoding of illegal characters and so on. All of that is handled behind the scenes by the ODBC driver interface. Similarly, ?ltUpdateTime tells ODBC to ask VFP for the value of the ltUpdateTime variable. Dates are another great source of incompatibility between various back-end data sources. Letting the ODBC driver do the conversion and formatting in this way eliminates a potential headache if you change back ends.

Adding a new survey

The steps for adding a new survey are:

Decide what questions are to be asked (or, perhaps more accurately, which answers will be recorded) and what type their answers will be.
Subclass the surveybasedata class and add a property initialized to a value of the appropriate type for each answer. Override the CreateCursor() method to create a cursor with columns with the same names as the properties just added (don’t forget to add the four properties from the data base class—nSurveyID, nCompanyID, cComments, and tLastUpdated).
Update the nSurveyID property for the data object subclass so this survey has a unique number.
Create a subclass of the surveybase class that will present the survey to the user.
Add a control or controls to the subclassed form with controlsources in the form thisform.oDataObject.<data object property>
If there are any dependencies between the questions (for example, questions that should only be asked if others were answered in a certain way), then put code in the UpdateControls() method to change control states. Note that this method is called after the data object’s LoadData() method is called, so the control’s states are set initially. You should also call this method whenever there’s a potential need for a refresh. For example, if a check box state changes to true, another set of questions might become relevant.
Update the cDataObjectName property with the name of the subclass you created in step 2. This ensures that the UI object instantiates the correct data object when it’s created.
Make an entry in the Survey_Master table with the SurveyID from step 3, a description for the survey, the name of the data class from step 2, and the name of the UI class from step 4.
For each company that’s eligible for a survey, add a row to the Company_Survey table with that company’s CompanyID and the SurveyID from step 3.

While this might seem to be a lot of work, remember that you only need to do it once for each survey.

Putting it into practice

For the purposes of this exercise, I designed a simple survey with the questions shown in Table 2. ******

Table 2. The survey questions.Expand table

No.	Question	Comments
1	How did you hear about our company?	C(3) options are: WOM: Word of mouth YP: Yellow Pages WWW: Web search ADT: TV advertisement ADR: Radio advertisement OTH: Other
1a	If Other—where did you hear about us?	C(20) Only available if OTH selected for question 1
2	Gender?	I 1: Male 2: Female
3	Do you use SQL Server?	L
4	Do you use FoxPro (Visual or otherwise)?	L
5	Do you use Visual Basic (not VBA or VBS)?	L

Next, I created a subclass of surveybasedata called surveycustomerdata and added properties for each of the questions. The subclass is included in the Download file, but the properties added were: cSource, cSourceOther, nSex, lSQLServer, lFoxPro, and lVB. I also overrode the CreateCursor() method to create a cursor with a field of matching name and data type for each property.

I assigned this new survey an ID of 1.

The next step was to create a subclass of the surveybase GUI class. I called this subclass surveycustomer.

I added controls to the subclassed form—a drop-down for the source, a text box for the other source description, an option group for the gender, and check boxes for each of the development tool questions. These controls were in addition to those provided by the base class—companyID, last update date/time, and comments, as well as the Save and Cancel buttons.

Because the other source text box should only be available if the user chooses Other from the source drop-down, I added enable/disable code to the UpdateControls() method that checks the value of the drop-down and takes appropriate action.

I set the value of the cDataObjectName property to “surveycustomerdata” so the correct data object is instantiated by the GUI class.

I updated the survey_master table by adding a row with the values SurveyID = 1, Survey_Name = “Generic Customer Survey,” Data_Class = “surveycustomerdata,” UI_Class = “surveycustomer.”

Finally, I added two new rows to the Company_Survey table, one each for CompanyIDs 1 and 2, both with SurveyID 1.

To display the survey, I typed the following in the command window:

Note that the second and third parameters of the CreateObject() call are passed to the Init() method of the GUI object. In this case, the 1 means that I want to load the survey data for CompanyID 1, and the .t. means that I want to open the form in edit mode (rather than just viewing the data). The result is shown in Figure 4.

Answering the questions and clicking the Save button fires the form class’s SaveSurveyData() method, which in turn fires the data object’s SaveData() method. The XML generated and saved to the memo field is shown in Listing 4.

Retrieving the data

“But wait,” I hear you cry. And you’re right. Storing data in this format doesn’t make querying and retrieval a simple matter of running a SQL statement. The data is stored in a free-form memo field, and most of us have had experience with how much of a hassle it is to retrieve data from there. This is where the power of the XML format (and one of Visual FoxPro’s most useful commands) comes to the fore. It’s a simple matter to retrieve all of the data from the text field into a cursor, and once it’s in the cursor the whole might of the native data engine is available to you.

The code in Listing 5 (included as ExtractData.PRG in the Download file) shows how simple it is to retrieve all of the data from the XML memo fields into a single usable cursor.

****

Listing 5. Retrieving VFP data from the memo field quagmire.

After checking that the appropriate class library is loaded, the extraction program instantiates a data object and connects to the back end using the data object’s connect string. It then retrieves a cursor containing all of the rows with answers to survey questions. Next it calls the data object’s CreateCursor() method, which generates a cursor with a column of the appropriate type and name for each data object property.

Scanning through the list of answer text fields, the code then passes the XML for each set of answers to the data object’s LoadData() method. Remember when I said that the tcXML parameter of the LoadData() method would come in handy? Well, here it is. It means that there’s no requirement to go back to the back end to retrieve the answers for each company. We can just get them all into a cursor with one back-end hit and then use the local data engine to scan through them and pass the XML to the data object.

Once the data object has been loaded up with the answers, it’s time to add a row to the results table and populate it with the date. Two simple but very powerful lines of code do this:

GATHER NAME is a wonderful command. It makes the process so much simpler. The alternative would be to iterate through all of the properties of the object and do a REPLACE for each one with the corresponding field in the cursor. I haven’t benchmarked this, but I imagine that having a native command to do this results in significant efficiencies.

After scanning through the entire list of answers, this code will leave you with a cursor called ResultSet, which has a row for every company and a column for every answer. From there, the reporting process is up to you.

Making changes to a survey

The last thing I want to mention is how much flexibility this approach gives you. Let’s say that in our example you want to add a new question about the respondent’s income range and another about the number of computers at their primary working location. Let’s also suppose that you discovered the 30 characters you’d allocated to the other source field was too small—40 would be better—and that your boss is no longer interested in the answer to whether people are using VB. The following is all you’d have to do:

Add a property called cIncomeRange and another called nComputerCount to the surveycustomerdata class.
Remove the lVB property from the same class.
Update the surveycustomerdata::CreateCursor() method to include cIncomeRange C(3) and nComputerCount I. Remove lVB and change the length of the cSourceOther field from 30 to 40.
Update the surveycustomer class to include new controls for the income range (probably a drop-down like the source drop-down) and the number of computers (probably a spinner or text box). Ensure that their control sources are set to the matching properties of the data object. Remove the VB check box.

That’s it! No data changes are required either to capture or to retrieve the data. The next time a survey is opened that was completed using the old format, the default values will be used for the new properties, the VB property will be ignored, and the existing 30 characters will be used for the other source field. As soon as it’s saved, the data will be in the new format.

Extra credit

You can use the metadata stored in the survey_master table to build a list of the surveys to which a particular company is “subscribed.” You could present a list to the user, including the description of the survey and the data that was last completed for this company in a GUI. The UI_Class field would then allow you to instantiate an appropriate form for viewing or editing survey responses.

It’s quite simple to change the back-end database used for this class. In fact, I developed the system using a SQL Server back end. All you need to do is change the cConnectString property of the surveydatabase class to one that’s appropriate for your back end of choice and then set up the tables with the structure shown in Figure 3 on that back end. That’s it—the conversion’s complete.

Conclusion

Using XML to store data in a memo field provides an extremely flexible architecture while allowing the structured retrieval of the data. While it’s not essential that XML be used (it could have just as well been a proprietary text or even binary format in the memo fields), the fact that XML is a standard for this type of work means that tools like Rick Strahl’s wwXML library make working with the format simple and quick. I encourage you to get comfortable with this powerful data exchange format.

To find out more about FoxTalk and Pinnacle Publishing, visit their website at http://www.pinpub.com/html/main.isx?sub=57

Note: This is not a Microsoft Corporation website. Microsoft is not responsible for its content.

This article is reproduced from the November 2001 issue of FoxTalk. Copyright 2001, by Pinnacle Publishing, Inc., unless otherwise noted. All rights are reserved. FoxTalk is an independently produced publication of Pinnacle Publishing, Inc. No part of this article may be used or reproduced in any fashion (except in brief quotations used in critical articles and reviews) without prior consent of Pinnacle Publishing, Inc. To contact Pinnacle Publishing, Inc., please call 1-800-493-4867 x4209.

Subclassing Existing Applications

Article
06/30/2006

Subclassing Existing Applications

Richard David Hodder

Most developers have a store of reusable code they rely on during development. Most (if not all) of our apps use or subclass things from this store. In this article, Richard David Hodder presents an approach for reusing application functionality across applications.

You create subclasses to reuse existing functionality in a class and to extend/change its behavior. You can “subclass” an application to reuse existing functionality in the application and to extend/change its behavior. I use the term “subclassing” somewhat loosely here, but I think it conveys the right intent.

Let’s say that I have an existing application “Oingo” and I wish to create a new application “Boingo” that’s based on Oingo. There are several possible reasons to subclass the Oingo application:

Add functionality: I want Boingo to have all of the functionality of Oingo plus some new features.
Substitute/override functionality: I want Boingo to have all of the functionality of Oingo with substitutions for some existing functionality (for example, an Import form that looks totally different).
Remove functionality: I want Boingo to have all of the functionality of Oingo with some existing functionality removed (for example, remove the Import option from the menu).

The first approach that might come to mind would be to create a new project file for Boingo, within the Oingo application directory. This approach mixes code bases and leaves you at high risk for breaking Oingo while trying to extend behavior in Boingo.

The most direct approach would be to create a new directory for Boingo, copy all of the files from the Oingo application into the new directory, make changes/add functionality, rebuild, test, and distribute, right? The problem with this approach is that the “connection” between Oingo and Boingo no longer exists: They no longer stem from the same code base. There are now two distinct code bases: When changes to Oingo are made, the changes must also be applied to Boingo to maintain the same functionality.

In a perfect world, several things would happen:

The Boingo project would have its own directory.
The project file for Boingo would be pointing to the same code base that’s found in the Oingo project file. This would allow the changes to be made to Oingo and “ripple” to Boingo.
The project directory for Boingo should have markedly less code—only the code that implements the additions, substitutions, and removals of Oingo functionality.
Changes to the application layer (“a-layer”) code in Oingo would be inherited by Boingo.
Changes to the a-layer in Boingo wouldn’t be inherited by Oingo: Again I refer you to the subclass metaphor. Changes in subclasses don’t affect the superclass; there’s no “upward” inheritance.

One of my favorite quotes is, “Wherever you go, there you are.” In a perfect world, you’d know the exact locations where functionality would need to be added, substituted, and removed before the originating application (Oingo in this example) is designed. This would allow you to do things like place hooks into and data-drive the application in order to control what’s in an application and how to extend it. Most times it’s not possible, and you may not know beforehand that the application needs to be “subclassed.” That’s why I included the word “existing” in the title of this article: You’ve already created the application. Now you want to make use of your existing work.

The keys to subclassing an application

The approach I’ll present later for subclassing an application relies on being able to “trick” VFP into using other functions and classes. I’ll present the general concepts first, and then I’ll demonstrate how I applied them in Codebook applications I’ve written.

The keys to subclassing an application are:

Managing the program stack (SET PROCEDURE)
Managing the class stack (SET CLASSLIB)
Managing the pathing (SET PATH)
Copying the project file and massaging its contents
Copying supporting files

****

Management of the program stack

When you call a function, VFP goes through the list of PRGs in the SET PROCEDURE list until it finds the function and then executes it. It goes through the list in the order of the PRGs in the SET PROCEDURE list. If two functions with the same name exist in one or more of the PRGs, then VFP executes the first one it encounters. Most of us have made the mistake of accidentally creating two functions with the same name. It gets really fun (read: frustrating <g>) when you keep modifying the function that’s later in the stack, and then run the application and find that things still seem broken. It always happens at 3 a.m. when you’re tired and out of caffeine. Consider the following three programs (Test, Foo, and Bar):

*-- TEST.PRG
SET PROCEDURE TO FOO,BAR
Hello()
*-- FOO.PRG
PROC Hello
MESSAGEBOX("I'm broken")
ENDPROC
*-- BAR.PRG
PROC Hello
MESSAGEBOX("I'm fixed")
ENDPROC

When you run TEST.PRG, you’ll always get the message box saying “I’m broken,” no matter how many times you change the “I’m fixed” string in the Hello function in BAR.PRG. That’s because when walking through the list of PRGs in SET PROCEDURE, VFP finds the Hello function in FOO.PRG first. The same goes for instantiating classes stored in PRGs: The first class encountered in the SET PROCEDURE list is instantiated.

You might be asking, “What’s that got to do with subclassing an existing app?” Consider the following situation: Oingo has a stock price importing form that calls a function named ImportStockQuotes, which retrieves stock quotes from a Web site and imports them into a database. You want Boingo to import stock quotes from a file on disk rather than from a Web site. To change just the ImportStockQuotes “behavior” in Boingo, add a PRG to the Boingo project (for example, BoingoFunctionOverrides.PRG) and in that PRG create a function called ImportStockQuotes and fill it with the code to import the quotes from a file.

The only step left in order to override the ImportStockQuotes behavior is to make sure that Boingo loads BoingoFunctionOverrides.PRG into the SET PROCEDURE list earlier than Oingo’s ImportStockQuotes. If you want to change the behavior of a class called DataImporter stored in a PRG, add a PRG to the Boingo project (for example, BoingoClassOverrides.PRG). In that PRG, create a class called DataImporter and fill it with the code that performs the behavior you want that class to execute in Boingo. You can be surgically “precise” with what you change by using this approach.

****

Management of the class stack

Managing the class stack is very similar to managing the program stack. When you instantiate a class that exists in a VCX class library, VFP goes through the list of class libraries in the SET CLASSLIB list until it finds the class and then instantiates it. It goes through the list in the order of the class libraries in the SET CLASSLIB list. If two classes with the same name exist in one or more of the class libraries, then VFP instantiates the first one it encounters. There’s one important difference between managing the program and class stacks: The class stack can’t contain two class library files with the same name. For example, suppose you had two directories (Oingo and Boingo) and each had a class library called DeadMansParty.VCX. If you executed the following command:

SET CLASSLIB TO ;
\Oingo\DeadMansParty, ;
\Boingo\DeadMansParty

you’d get the cryptic error “Alias name is already in use.” Obviously, behind the scenes VFP is opening the class libraries as tables, and you can’t have two tables with the same alias (DeadMansParty) open in the same workarea. You could get around this by using the ALIAS parameter of the SET CLASSLIB command:

As with the program stack, the trick to subclassing an application is to make sure that the a-layer class libraries for the subclassed app (Boingo) are loaded into SET CLASSLIB earlier than the class libraries from the superclass app (Oingo).

****

Management of the pathing

Managing the path by using SET PATH can also be important. Codebook developers can test their applications without having to build executables by taking advantage of path settings. Boingo may rely on the setting of path to open a file that’s in the Oingo directory. ******

Copying the project file and massaging its contents

A few paragraphs ago I mentioned that it’s important to make sure that Oingo and Boingo are based on the same code base. What’s the quickest way to do that? Just copy the Oingo project file (PJX and PJT) into the Boingo directory, right? Close but no cigar. Now Boingo’s project thinks that its directory contains Oingo’s code: The pathing to the project items is wrong. The pathing needs to be adjusted so that the items in the Boingo project file point to the items in Oingo’s directory. Some care has to be taken with this because some items still should exist in the Boingo directory—supporting files, for example. ******

Copying supporting files

Some items in a project support a framework or application and are application-specific, and therefore copies should be made of them, rather than pointing to the superclass app’s files. Databases and tables are a good example of this. What good is it to point the Boingo project at Oingo’s data, when one of the things that may be changing from Oingo to Boingo is data structures? Also, for development environment purposes it’s better if Boingo has its own data structures, even if there are no changes. Other examples of supporting files are reports and INI files. Support files will differ based upon which framework(s) you develop with (for instance, Codebook, INTL, WebConnect, and so forth).

Frameworks can make most if not all of the keys to subclassing an application simpler to achieve because usually they’ve been addressed in the framework. For example, as you’ll soon see, Codebook keeps a table of the programs and class libraries to load. By changing the framework slightly, these programs and classes can be loaded in a manner that supports the task of a-layer ordering of items in SET CLASSLIB and SET PROCEDURE.

Subclassing a Codebook application

Rather than trying to address all possible frameworks and libraries, I’m going to stick to territory that’s familiar for me: the Codebook framework. ******

Management of the program and class stacks in Codebook

Codebook applications build a list of the programs and class libraries used by the application by querying the contents of the project file. In a function named BuildMetaData in Setup.PRG, the project file is opened with the alias “_project” and then the following query is run:

SELECT NAME, TYPE ;
FROM _project    ;
WHERE !DELETED() AND ;
(TYPE = "V" OR ;
TYPE = "P")   ;
ORDER BY TYPE    ;
INTO CURSOR cTemp

Records with a type equal to “V” are class libraries (VCXs), and records with a type equal to “P” are programs (PRGs). The contents of this cursor are saved to a table called METADATA, which is built into Codebook executables. In another program named SetPath, the information in this cursor is looped through. All of the program records (type=”P”) are used to build a comma-delimited list of the programs in the project. The function then SETs PROCEDURE to this list of files. All of the class library records (type=”V”) are used to build a comma-delimited list of the class libraries in the project. The code then SETs CLASSLIB to this list of files.

Although this list is organized by type, this doesn’t order the files so that the subclassed application’s a-layer will get loaded earlier. Then I came up with an idea. I had the project file opened as a table, and I was looking at the Name field of the PJX file. The Name field uses relative pathing to point to project items. Therefore, framework files all started with “..” (for example, “..\common50\libs\capp.vcx”). Files that were in the a-layer, on the other hand, did not start with “..” because they were either in the project’s directory or a subdirectory of the project’s directory (for example, “progs\solvetheworldsproblems.prg”).

I decided to change the contents of MetaData.DBF and reorder the records so that names not beginning with “..” float to the top of the list. Here’s the modified query that I used:

I created a new field (LAYER) that holds the first two characters of the name of the file. This field is only used for the ORDER BY of this query. The framework doesn’t use the field for anything. All non-a-layer code will have a LAYER equal to “..” and all a-layer code will not. Due to the fact that the period character “.” has a lower ASCII value than the alphabetic characters, it was necessary to order the list by descending LAYER so that all a-layer records would be at the top of the cursor. Being at the top of the cursor, they get loaded into the respective stacks first!

****

Management of the pathing in Codebook

The main reason for managing pathing in Codebook is to create a development environment that allows you to develop an application without constantly having to rebuild the executable. When subclassing an application, Codebook must know two things: first, whether the current application is a subclassed application (like Boingo), and second, if it is, where the superclass application (Oingo) resides so that it can adjust its paths to point at Oingo. To solve this, I create a #DEFINE called APPLICATION_SUPERCLASS_DIRECTORY that contains the superclass’s directory. This #DEFINE only exists if the current application is a subclass. Therefore I was able to use the #IFDEF directive to change the pathing in the SetPath function in Setup.PRG:

#IFDEF APPLICATION_SUPERCLASS_DIRECTORY
LOCAL lcAppSubClassDir
lcAppSubClassDir = ".."+ ;
APPLICATION_SUPERCLASS_DIRECTORY + ;
IIF(RIGHTC(APPLICATION_SUPERCLASS_DIRECTORY,1)!= ;
"","","")
lcPath = lcPath+ ","+;
lcAppSubClassDir+"\PROGS, "+ ;
lcAppSubClassDir+"\FORMS, "+ ;
lcAppSubClassDir+"\LIBS, "+ ;
lcAppSubClassDir+"\GRAPHICS"
#ENDIF

#IFDEF will only execute its code if the #DEFINE exists (if the application is a subclass).

****

Copying supporting files and the project file and massaging its contents in Codebook

I created a simple tool called the Codebook Application Subclasser (see Figure 1).

The form SUBCLASS.SCX is available in the accompanying Download file. I won’t show all of the code here, but once the superclass application directory and subclass application directory are chosen, the following steps are taken:

Let’s look at the last four function calls in this code snippet.

BuildIncludeFile—This routine creates the application include file for the subclass application (Boingo). It #INCLUDEs the application include file from the superclass application (Oingo). This is done so that #DEFINEs added to Oingo in the future will be “inherited” by Boingo. Boingo’s include file can be added to manually: #DEFINEs added to this file don’t affect Oingo (as I said before, inheritance doesn’t move upward).

ModifyMainProgram—Main.PRG is the main program for Codebook applications. Main.PRG gets copied over from the superclass. ModifyMainProgram uses LLFF (low-level file functions) to add the equivalent of the following to the bottom of Main.PRG:

This has no effect on the code, but it makes sure that the next time the Boingo project is built, the aappBoingo class library will be added to the Boingo project.

ModifyStartCB—StartCB.PRG is a program that sets up the development environment (paths and so on) for an application. It isn’t built into the application; it merely sets up the environment. ModifyStartCB adds code to StartCB so that the superclass application’s paths are included.

CreateApplicationObjectSubclass—Every application created with the Codebook framework has an application object stored in AAPP.VCX. The application object holds global information for the application. When subclassing an application, it may be necessary to add or change properties and functionality on the subclassed application’s application object. For example, Boingo might need to attach a timer object to the application object to remind the user to import stock prices (a feature not available in Oingo). Therefore, I create a subclass of the superclass app’s application object and place it in the LIBS directory of the Boingo project’s directory. Boingo-specific application object changes get made to this object. In order to avoid the class library naming collision problem mentioned earlier, I name the class library “AAPP<Subdirectory of CDBK50 To Create>” (for example, AAPPBoingo).

When to subclass an application

Just because cause you can subclass an application doesn’t mean that you should. I can think of two occasions when subclassing an application would be appropriate:

If you sell a product and receive a lot of requests for “one-off” functionality.

If products will be internationally distributed. I worked on products that were developed in the U.S., but with the foresight to make them ready for the international market by incorporating Steven Black’s INTL Toolkit (www.StevenBlack.com). As international versions of the product were developed, there was locale-specific functionality that needed to be incorporated. Spain required new reports, Italy needed enhancements to the import form, and so on.

Lessons learned

Having coding standards—particularly frameworks and standard directory structures and the like—made this process simpler: This is true for coding in general. I’m not suggesting that you use Codebook specifically (although four out of five VFP developers surveyed… <g>). Rather, I suggest that you pick (or create) standards and stick with them.

Also, use of the NEWOBJECT() function could actually get in your way because it hard-codes the location of the class library of the class you wish to instantiate. I’ve never really been a fan of this function for that very reason. I prefer to let the environment figure it out (particularly if I need to refactor classes into new class libraries), but that’s just my own bias.

To find out more about FoxTalk and Pinnacle Publishing, visit their website at http://www.pinpub.com/html/main.isx?sub=57

Note: This is not a Microsoft Corporation website. Microsoft is not responsible for its content.

This article is reproduced from the December 2001 issue of FoxTalk. Copyright 2001, by Pinnacle Publishing, Inc., unless otherwise noted. All rights are reserved. FoxTalk is an independently produced publication of Pinnacle Publishing, Inc. No part of this article may be used or reproduced in any fashion (except in brief quotations used in critical articles and reviews) without prior consent of Pinnacle Publishing, Inc. To contact Pinnacle Publishing, Inc., please call 1-800-493-4867 x4209.

By Amjad Izhar
Contact: amjad.izhar@gmail.com
https://amjadizhar.blog

Affiliate Disclosure: This blog may contain affiliate links, which means I may earn a small commission if you click on the link and make a purchase. This comes at no additional cost to you. I only recommend products or services that I believe will add value to my readers. Your support helps keep this blog running and allows me to continue providing you with quality content. Thank you for your support!

Visual FoxPro FoxTalk 2001

Language Enhancements in VFP 7, Part 1

Language Enhancements in VFP 7, Part 1

ALINES()

AMEMBERS()

ASCAN()

ASORT()

BITOR(), BITXOR(), and BITAND()

BROWSE

COMPILE

Conclusion

Driving the Data Bus: Chatting on Company Time–Building a VFP Chat Module

Driving the Data Bus: Chatting on Company Time—Building a VFP Chat Module

The chat system

Initiating a chat

Responding to a request for a chat

Chatting

Ending the chat

InterCom System

Wrapping the client

The chat handler

HandleRequest()

HandleAccept()

HandleMessage()

HandleDisconnect()

The chat form

Init()

HandleDisconnect()

ReceiveMessage()

SendDisconnect()

SendMessage()

Sample code

Conclusion

ClassNavigator

ClassNavigator

Simple installation

The test run

Running ClassNavigator

Hierarchies from multiple programs

Where to get ClassNavigator

Summary

The Component Gallery: VFP’s Best Kept Secret

The Component Gallery: VFP’s Best Kept Secret

Using the Component Gallery

Creating your own catalogs

Conclusion

Understanding COM+ with VFP, Part 1

Understanding COM+ with VFP, Part 1

COMmon knowledge

MTS to the rescue

Windows 2000

Summary

Sidebar: It’s GUID for Me, is it GUID for You?

Understanding COM+ with VFP, Part 2

Understanding COM+ with VFP, Part 2

Is the client always right?

Are you feeling insecure?

Error handling

Conclusion

Understanding COM+ with VFP, Part 3

Understanding COM+ with VFP, Part 3

A review of transactions

Using the DTC

Configuring COM+ transactions

Decorating for the Busy Developer

Decorating for the Busy Developer

Subclasses vs. decorators

THIS_ACCESS overview

Redecorating with THIS_ACCESS

Paying the piper

WITH/ENDWITH and GATHER gotchas

Conclusion

TYPE() to StringType()–Bridging a Gap

TYPE() to StringType()—Bridging a Gap

Dual use of the TYPE() function

Function StringType()

An empty string

Data type logical

Data types numeric and integer

Data type currency