June 91 - Data Access Language Unit for MacApp
Data Access Language Unit for MacApp
Mary Elaine Califf
A few months ago I began work on three Macintosh front-ends for administrative data.
The data resides in Rdb databases on our VAXcluster and was to be accessed using Apple's
Data Access Language (DAL).
Since all three projects were full-featured applications, I abandoned HyperCard-in
which the previous incarnations of two of these front-ends were written-and started
learning MacApp. When I couldn't find anyone else using DAL and MacApp together, UDAL
was born.
This version of the UDAL unit uses the cl1_api interface provided with DAL instead of
the Data Access Manager routines. Therefore, it works with both system 6.0.x and
system 7.0. UDAL is currently written in MacApp 2.0, but conversion to MacApp 3.0
requires only minor changes. The UDAL unit may not handle everything you want to do
with DAL, but should at least suggest a way to incorporate DAL into MacApp.
THE BASICS OF DATA ACCESS LANGUAGE
DAL is a client-server protocol for remote database access. The Macintosh client is a
system extension-included with system 7.0, available separately for system 6.0.x.
Servers are available with adapters for various databases on systems running VAX/VMS,
MVS/TSO, and VM/CMS. Other servers are under development, including one for A/UX
that has already been announced.
DAL uses an SQL-based language that includes some C-like programming constructs.
DAL's greatest asset is in providing applications with a uniform access method across
various systems, database management systems, and network connection types. Despite
the network overhead and the translation of DAL into the databases' SQL dialects, DAL's
performance is fairly good and is improving with newer versions of the servers.
OVERVIEW OF THE UDAL UNIT FOR MACAPP
UDAL defines two classes: TDALConnection and TDALRequest. TDALConnection maintains
information about a DAL session and contains methods that call the DAL functions.
TDALConnection also provides a Reconnect method that establishes a new session using a
previous connection object whose session aborted. One TDALConnection object is needed
for each concurrent DAL session.
TDALRequest manages DAL queries. This class is useful for long, complicated requests
or for requests that need to be reissued. Besides the two object types, the UDAL unit
provides an InitUDAL procedure, utility routines for converting between Pascal strings
and the null-terminated strings used by DAL, and default error handling routines.
INSIDE TDALCONNECTION-INTERFACING TO THE DAL API
The TDALConnection class provides an object-oriented interface to the DAL API
functions. Therefore, most of the object's methods are based on the API functions. Note:
API functions all begin with the letters CL; DAL was originally called CL/1, and the
original function names were retained for compatibility. Please refer to the
TDALConnection interface listing for the complete source of the class interface.
I added functionality to TDALConnection by including an error handling procedure as
one of the parameters to each of the methods based on an API function. This addition helps
to hide the details of managing the DAL connections from applications interested only in
the data retrieved. The procedure I usually pass to the functions, HandleDALError, is
included in the UDAL unit. All functions except GetString return the result code from the
API function called; this allows the calling method to handle error checking. GetString
returns the result code in a var parameter instead of returning it as its function result.
IDALConnection
The IDALConnection method initializes the object and establishes a DAL session using the
CLInit function. It takes the host name, user name, password, and connection options as
parameters. The Reconnect method also establishes a DAL session using CLInit, but it
uses the fields of the object to determine the parameters for CLInit since its purpose is
to re-establish the user's connection with the host.
HandleDroppedConnection
HandleDroppedConnection calls CLEnd to ensure that the last session was properly closed
and then displays an alert, enabling the user to reconnect immediately. My applications
all provide menu choices allowing later reconnection. When the user discovers a dropped
connection but wants to do something that doesn't require a current session (for
example, printing an existing document), he shouldn't have to wait for the new session
to be established. If the user does wish to reconnect immediately,
HandleDroppedConnection calls Reconnect.
CloseConnection
CloseConnection calls CLEnd to close down a DAL session. It doesn't free the
TDALConnection object, because the object could be used to handle another session after
calling Reconnect.
SendSQL and ExecuteRequest
SendSQL and ExecuteRequest allow the application to talk to the host database. SendSQL
sends a string to the host. The ExecuteRequest method tells the host to execute everything
received since the last call to ExecuteRequest. Note: The host doesn't do anything with the
commands received until the user tells it to execute them. Be careful to always complete
a DAL programming construct between calls to ExecuteRequest-telling DAL to execute
what it has when you're in the middle of a for loop always produces errors!
CheckState and GetString
CheckState and GetString retrieve information from the host. CheckState determines if a
value is waiting for retrieval; GetString retrieves a value from the host (if it doesn't
time out first) and returns it as a Pascal string. The timeout period is specified as a
parameter to the method. The routine returns values as strings because I couldn't get
DAL to give me anything else from my Rdb database, even when the value was clearly an
integer. Therefore, it was more convenient for the routine to convert the C strings into
Pascal strings.
StopRequest
The final method in TDALConnection (other than Fields) is StopRequest. This method
should abort the current request if the abortSession parameter is false and abort the
entire DAL session if abortSession is true. However, test the method thoroughly in your
environment before making it available to users. The CLBreak function it is based on is
not always reliable. In some environments, it occasionally hangs both the Macintosh and
the process on the mainframe. Everyone I've spoken to who uses DAL with Rdb databases
has experienced these crashes when using CLBreak. The function does, however, work
with some DBMSs.
A "Nothing" example for TDALConnection
Drop the source listed in A simple example using TDALConnection into a view's draw
method to provide a very simple example that shows how to use TDALConnection.
INSIDE TDALREQUEST-HANDLING COMPLEX REQUESTS
Many uses of DAL can be made using only the TDALConnection class-I handle a fair
amount of database communication in my applications using SendSQL, ExecuteRequest,
and GetString.
However, at least two situations require better request management and a subclass of
TDALRequest: inserting a few user-provided values into a query template, and saving a
query and repeating it with no modifications. (Please refer to the TDALRequest interface
listing for the complete source of the class interface.)
I had these needs in my applications. The template for one of my queries is a STR#
resource with 15 strings. Also, all my documents contain the results of a database query
that the user should be able to update without having to remember the query.
TDALRequest saves the text of a DAL request in a linked list of strings. It also contains
a reference to the DALConnection it is supposed to use. It provides three methods of
interest: SendRequest, ShowRequest, and BuildRequest.
SendRequest and ShowRequest
SendRequest sends each string in the request list using SendSQL, and then calls
ExecuteRequest.
ShowRequest provides for debugging by displaying a dialog box with a TTEView
containing the text of the request. If you cancel the dialog, ShowRequest returns false.
This helps you avoid sending a bad request to the host during debugging.
BuildRequest
Most programmers who use UDAL will want to override BuildRequest. UDAL provides a
default version that takes the STR# resource with id 2000 and stuffs the strings into a
TTEView in a dialog box. It then takes what is in the TTEView when the dialog box is
dismissed (if the OK button is pressed) and breaks the text into the request list. I find
this useful in early stages of my applications, but all requests in my finished
applications are implemented by subclasses of TDALRequest.
Your version of BuildRequest should usually display a dialog box to get user
information and then create the linked list of strings from a STR# resource, inserting
the information in the appropriate places. Make sure that each place where you need to
insert information falls between strings in your STR#. BuildRequest should return false
if the user cancels the request or some other error occurs while building the request.
Otherwise, BuildRequest should return true.
The following code example demonstrates the use of TDALRequest assuming that
aDALConn exists and that TMyDocument.GetData retrieves the data from the request:
New(aDALRequest);
FailNIL(aDALRequest);
aDALRequest.IDALRequest(kDefaultRequestID,fConn);
if aDALRequest.BuildRequest then
if aDALRequest.ShowRequest then
begin
aDALRequest.SendRequest;
aDocument.GetData;
end;
INSIDE TRETRIEVER-HANDLING ASYNCHRONOUS REQUESTS
DAL performance is improving, but some requests can take a long time. My applications
allow users to switch to another application while a request is pending, and they also
allow users to perform any task inside my application that doesn't require a database
lookup. If you handle more than one DAL session, you can even allow multiple lookups,
but only one per session.
To handle the retrieval of the information in the background, I create a TRetriever
class that overrides DoIdle. The instance of this class need only exist while a lookup is
occurring.
TRetriever = OBJECT(TEvtHandler)
fConn : TDALConnection;
fDocument : TFSDirDocument;
PROCEDURE TRetrever.IRetriever(conn: TDALConnection;
doc: TStuDirDocument);
FUNCTION TRetriever.DoIdle(phase:IdlePhase):BOOLEAN;
OVERRIDE;
END;
TRetriever's DoIdle method is fairly simple. It need only check to see if there is data
waiting and call an appropriate method of the document to retrieve the data-in this case,
GetPersonRecord. My DoIdle method also does some error handling-see the
TRetriever.DoIdle implementation listing for the complete source.
Installing an instance of TRetriever is quite simple. The following five lines of code
create the retriever and install it in the cohandler chain. You would include this code
right after a call to TDALRequest.SendRequest or after TDALConnection.ExecuteRequest.
New(aRetriever);
FailNIL(aRetriever);
aRetriever.IRetriever(fConn,SELF);
aRetriever.SetIdleFreq(1);
gApplication.InstallCoHandler(aRetriever,true);
LOOKING FOR OTHER DAL USERS
The UDAL unit may not do everything you'd like to do with DAL, but I hope it will prove
useful and suggest other ways that DAL can be used with MacApp. One future direction for
the unit is the creation of a system 7.0-only version that takes advantage of the
asynchronous capabilities of the new Data Access Manager routines. I welcome comments
and questions. I would appreciate hearing from anyone using DAL.
