TweetFollow Us on Twitter

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.
 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Latest Forum Discussions

See All

Combo Quest (Games)
Combo Quest 1.0 Device: iOS Universal Category: Games Price: $.99, Version: 1.0 (iTunes) Description: Combo Quest is an epic, time tap role-playing adventure. In this unique masterpiece, you are a knight on a heroic quest to retrieve... | Read more »
Hero Emblems (Games)
Hero Emblems 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: ** 25% OFF for a limited time to celebrate the release ** ** Note for iPhone 6 user: If it doesn't run fullscreen on your device... | Read more »
Puzzle Blitz (Games)
Puzzle Blitz 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: Puzzle Blitz is a frantic puzzle solving race against the clock! Solve as many puzzles as you can, before time runs out! You have... | Read more »
Sky Patrol (Games)
Sky Patrol 1.0.1 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0.1 (iTunes) Description: 'Strategic Twist On The Classic Shooter Genre' - Indie Game Mag... | Read more »
The Princess Bride - The Official Game...
The Princess Bride - The Official Game 1.1 Device: iOS Universal Category: Games Price: $3.99, Version: 1.1 (iTunes) Description: An epic game based on the beloved classic movie? Inconceivable! Play the world of The Princess Bride... | Read more »
Frozen Synapse (Games)
Frozen Synapse 1.0 Device: iOS iPhone Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: Frozen Synapse is a multi-award-winning tactical game. (Full cross-play with desktop and tablet versions) 9/10 Edge 9/10 Eurogamer... | Read more »
Space Marshals (Games)
Space Marshals 1.0.1 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0.1 (iTunes) Description: ### IMPORTANT ### Please note that iPhone 4 is not supported. Space Marshals is a Sci-fi Wild West adventure taking place... | Read more »
Battle Slimes (Games)
Battle Slimes 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: BATTLE SLIMES is a fun local multiplayer game. Control speedy & bouncy slime blobs as you compete with friends and family.... | Read more »
Spectrum - 3D Avenue (Games)
Spectrum - 3D Avenue 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: "Spectrum is a pretty cool take on twitchy/reaction-based gameplay with enough complexity and style to stand out from the... | Read more »
Drop Wizard (Games)
Drop Wizard 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: Bring back the joy of arcade games! Drop Wizard is an action arcade game where you play as Teo, a wizard on a quest to save his... | Read more »

Price Scanner via MacPrices.net

Our MacBook Price Trackers will show you the...
Our Apple award-winning MacBook Price Trackers are continually updated with the latest information on prices, bundles, and availability for 16″ and 14″ MacBook Pros along with 13″ and 15″ MacBook... Read more
Amazon is offering a 10% discount on Apple’s...
Don’t pay full price! Amazon has 16-inch M4 Pro MacBook Pros (Silver and Black colors) on sale today for 10% off Apple’s MSRP. Shipping is free. These are the lowest prices currently available for 16... Read more
13-inch M4 MacBook Airs on sale for $150 off...
Amazon has new 13″ M4 MacBook Airs on sale for $150 off MSRP right now, starting at $849. Sale prices apply to most colors and configurations. Be sure to select Amazon as the seller, rather than a... Read more
15-inch M4 MacBook Airs on sale for $150 off...
Amazon has new 15″ M4 MacBook Airs on sale for $150 off Apple’s MSRP, starting at $1049. Be sure to select Amazon as the seller, rather than a third-party: – 15″ M4 MacBook Air (16GB/256GB): $1049, $... Read more
Amazon is offering a $50 discount on Apple’s...
Amazon has Apple’s 11th-generation A16 iPads in stock on sale for $50 (or a little more) off MSRP this week. Shipping is free: – 11″ 11th-generation 128GB WiFi iPads: $299 $50 off MSRP – 11″ 11th-... Read more
Clearance 13-inch M1 MacBook Airs available f...
Walmart has clearance, but new, Apple 13″ M1 MacBook Airs (8GB RAM, 256GB SSD) available online for $649, $360 off original MSRP, in Space Gray, Silver, and Gold colors. These are new MacBooks for... Read more
iPad minis on sale for $100 off Apple’s MSRP...
Amazon is offering $100 discounts (up to 20% off) on Apple’s newest 2024 WiFi iPad minis, each with free shipping. These are the lowest prices available for new minis among the Apple retailers we... Read more
AirPods Max headphones on sale for $479, $70...
Amazon has AirPods Max with USB-C on sale for $479.99 in all colors. Shipping is free. Their price is $70 off Apple’s MSRP, and it’s the lowest price available today for AirPods Max. Keep an eye on... Read more
14-inch M4 Pro/M4 Max MacBook Pros on sale th...
Don’t pay full price! Get a new 14″ MacBook Pro with an M4 Pro or M4 Max CPU for up to $320 off Apple’s MSRP this weekend at these retailers…they are the lowest prices available for these MacBook... Read more
Get a 15-inch M4 MacBook Air for $150 off App...
A couple of Apple retailers are offering $150 discounts on new 15″ M4 MacBook Airs this weekend. Prices at these retailers start at $1049: (1): Amazon has new 15″ M4 MacBook Airs on sale for $150 off... Read more

Jobs Board

All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.