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

Splash Cars guide - How to paint the tow...
Splash Cars is an arcade driving game that feels like a hybrid between Dawn of the Plow and Splatoon. In it, you'll need to drive a car around to repaint areas of a town that have lost all of their color. Check out these tips to help you perform... | Read more »
The best video player on mobile
We all know the stock video player on iOS is not particularly convenient, primarily because it asks us to hook a device up to iTunes to sync video in a world that has things like Netflix. [Read more] | Read more »
Four apps to help improve your Super Bow...
Super Bowl Sunday is upon us, and whether you’re a Panthers or a Broncos fan you’re no doubt gearing up for it. [Read more] | Read more »
LooperSonic (Music)
LooperSonic 1.0 Device: iOS Universal Category: Music Price: $4.99, Version: 1.0 (iTunes) Description: LooperSonic is a multi-track audio looper and recorder that will take your loops to the next level. Use it like a loop pedal to... | Read more »
Space Grunts guide - How to survive
Space Grunts is a fast-paced roguelike from popular iOS developer, Orange Pixel. While it taps into many of the typical roguelike sensibilities, you might still find yourself caught out by a few things. We delved further to find you some helpful... | Read more »
Dreii guide - How to play well with othe...
Dreii is a rather stylish and wonderful puzzle game that’s reminiscent of cooperative games like Journey. If that sounds immensely appealing, then you should immediately get cracking and give it a whirl. We can offer you some tips and tricks on... | Read more »
Kill the Plumber World guide - How to ou...
You already know how to hop around like Mario, but do you know how to defeat him? Those are your marching orders in Kill the Plumber, and it's not always as easy as it looks. Here are some tips to get you started. This is not a seasoned platform... | Read more »
Planar Conquest (Games)
Planar Conquest 1.0 Device: iOS Universal Category: Games Price: $12.99, Version: 1.0 (iTunes) Description: IMPORTANT: Planar Conquest is compatible only with iPad 3 & newer devices, iPhone 5 & newer. It’s NOT compatible with... | Read more »
We talk to Cheetah Mobile about its plan...
Piano Tiles 2 is a fast-paced rhythm action high score chaser out now on iOS and Android. You have to tap a series of black tiles that appear on the screen in time to the music, being careful not to accidentally hit anywhere else. Do that and it's... | Read more »
Ultimate Briefcase guide - How to dodge...
Ultimate Briefcase is a simple but tricky game that’s highly dependent on how fast you can react. We can still offer you a few tips and tricks on how to survive though. Guess what? That’s exactly what we’re going to do now. Take it easy [Read more... | Read more »

Price Scanner via MacPrices.net

12-inch 1.2GHz Silver Retina MacBook on sale...
B&H Photo has the 12″ 1.2GHz Silver Retina MacBook on sale for $1399 including free shipping plus NY sales tax only. Their price is $200 off MSRP, and it’s the lowest price for this model from... Read more
iPads on sale at Target: $100 off iPad Air 2,...
Target has WiFi iPad Air 2s and iPad mini 4s on sale for up to $100 off MSRP on their online store for a limited time. Choose free shipping or free local store pickup (if available). Sale prices for... Read more
Target offers Apple Watch for $100 off MSRP
Target has Apple Watches on sale for $100 for a limited time. Choose free shipping or free local store pickup (if available). Sale prices for online orders only, in-store prices may vary: - Apple... Read more
Apple refurbished 2014 13-inch Retina MacBook...
Apple has Certified Refurbished 2014 13″ Retina MacBook Pros available for up to $400 off original MSRP, starting at $979. An Apple one-year warranty is included with each model, and shipping is free... Read more
Macs available for up to $300 off MSRP, $20 o...
Purchase a new Mac or iPad using Apple’s Education Store and take up to $300 off MSRP. All teachers, students, and staff of any educational institution qualify for the discount. Shipping is free, and... Read more
Watch Super Bowl 50 Live On Your iPad For Fre...
Watch Super Bowl 50 LIVE on the CBS Sports app for iPad and Apple TV. Get the app and then tune in Sunday, February 7, 2016 at 6:30 PM ET to catch every moment of the big game. The CBS Sports app is... Read more
Two-thirds Of All Smart Watches Shipped In 20...
Apple dominated the smart watch market in 2015, accounting for over 12 million units and two-thirds of all shipments according to Canalys market research analysts’ estimates. Samsung returned to... Read more
12-inch 1.2GHz Retina MacBooks on sale for up...
B&H Photo has 12″ 1.2GHz Retina MacBooks on sale for $180 off MSRP. Shipping is free, and B&H charges NY tax only: - 12″ 1.2GHz Gray Retina MacBook: $1499 $100 off MSRP - 12″ 1.2GHz Silver... Read more
12-inch 1.1GHz Gray Retina MacBook on sale fo...
B&H Photo has the 12″ 1.1GHz Gray Retina MacBook on sale for $1199 including free shipping plus NY sales tax only. Their price is $100 off MSRP, and it’s the lowest price available for this model... Read more
Apple now offering full line of Certified Ref...
Apple now has a full line of Certified Refurbished 2015 21″ & 27″ iMacs available for up to $350 off MSRP. Apple’s one-year warranty is standard, and shipping is free. The following models are... Read more

Jobs Board

*Apple* Retail - Multiple Positions (US) - A...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* Subject Matter Expert - Experis (Uni...
This position is for an Apple Subject Matter Expert to assist in developing the architecture, support and services for integration of Apple devices into the domain. Read more
*Apple* Macintosh OSX - Net2Source Inc. (Uni...
…: * Work Authorization : * Contact Number(Best time to reach you) : Skills : Apple Macintosh OSX Location : New York, New York. Duartion : 6+ Months The associate would Read more
Computer Operations Technician ll - *Apple*...
# Web Announcement** Apple Technical Liaison**The George Mason University, Information Technology Services (ITS), Technology Support Services, Desktop Support Read more
Restaurant Manager - Apple Gilroy Inc./Apple...
…in every aspect of daily operation. WHY YOU'LL LIKE IT: You'll be the Big Apple . You'll solve problems. You'll get to show your ability to handle the stress and Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.