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

Apple Configurator 2.5 - Configure and d...
Apple Configurator makes it easy to deploy iPad, iPhone, iPod touch, and Apple TV devices in your school or business. Use Apple Configurator to quickly configure large numbers of devices connected to... Read more
Smultron 10.0 - Easy-to-use, powerful te...
Smultron 10 is an elegant and powerful text editor that is easy to use. You can use Smultron 10 to create or edit any text document. Everything from a web page, a note or a script to any single piece... Read more
BetterTouchTool 2.304 - Customize multi-...
BetterTouchTool adds many new, fully customizable gestures to the Magic Mouse, Multi-Touch MacBook trackpad, and Magic Trackpad. These gestures are customizable: Magic Mouse: Pinch in / out (zoom... Read more
Drive Genius 5.0.5 - $49.50 (50% off)
Drive Genius features a comprehensive Malware Scan. Automate your malware protection. Protect your investment from any threat. The Malware Scan is part of the automated DrivePulse utility. DrivePulse... Read more
Apple Keynote 7.3 - Apple's present...
Easily create gorgeous presentations with the all-new Keynote, featuring powerful yet easy-to-use tools and dazzling effects that will make you a very hard act to follow. The Theme Chooser lets you... Read more
Apple Numbers 4.3 - Apple's spreads...
With Apple Numbers, sophisticated spreadsheets are just the start. The whole sheet is your canvas. Just add dramatic interactive charts, tables, and images that paint a revealing picture of your data... Read more
Apple Pages 6.3 - Apple's word proc...
Apple Pages is a powerful word processor that gives you everything you need to create documents that look beautiful. And read beautifully. It lets you work seamlessly between Mac and iOS devices, and... Read more
Smultron 9.4.2 - Easy-to-use, powerful t...
Smultron 9 is an elegant and powerful text editor that is easy to use. Use it to create or edit any text document. Everything from a web page, a note or a script to any single piece of text or code.... Read more
Xcode 9.0 - Integrated development envir...
Xcode includes everything developers need to create great applications for Mac, iPhone, iPad, and Apple Watch. Xcode provides developers a unified workflow for user interface design, coding, testing... Read more
iShowU Instant 1.2.0 - Full-featured scr...
iShowU Instant gives you real-time screen recording like you've never seen before! It is the fastest, most feature-filled real-time screen capture tool from shinywhitebox yet. All of the features you... Read more

The best games to play while you wait fo...
SteamWorld Dig 2 is out this week on PC and Switch, and people are understandably excited. This clever series by Image and Form combines our favorite metroidvania mechanics with an esquisite universe, excellent storytelling, and true wit. While... | Read more »
Drag'n'Boom beginner's gu...
Have you ever wanted to burn and pillage a village as a bloodthirsty dragon? If you answered yes to that question, Drag'n'Boom offers you the perfect chance to do so, casting you as an adorable little dragon that wants to set humankind aflame. It... | Read more »
Thimbleweed Park (Games)
Thimbleweed Park 1.0.0 Device: iOS Universal Category: Games Price: $9.99, Version: 1.0.0 (iTunes) Description: A brand new adventure game from Ron Gilbert and Gary Winnick, creators of the classics Monkey Island and Maniac Mansion!... | Read more »
The best simulation games on mobile
There's nothing like a good sim -- from the seemingly ridiculous to the incredibly mundane, you can be there's a simulation game out there for your every whim. [Read more] | Read more »
INKS guide - how to create works of pinb...
INKS puts a clever new spin on everyone's favorite classic arcade game, pinball. The core mechanics are the same -- keep a little ball pinging around the board for as long as possible without letting it fall into the precarious holes in the board.... | Read more »
Warbands: Bushido (Games)
Warbands: Bushido 1.0 Device: iOS Universal Category: Games Price: $3.99, Version: 1.0 (iTunes) Description: Warbands:Bushido is a miniatures board game with cards, miniatures, dice and beautiful terrains to fight on, with both... | Read more »
The best mobile games like Divinity: Ori...
Divinity: Original Sin 2 launched this week to the excitement of RPG fans everywhere. The game, which derives a lot of of its story and mechanics from old-school isometric RPGs and Dungeons & Dragons, has unseated PlayerUnknown's... | Read more »
Iron Marines guide - beginner tips and t...
Iron Marines is a brilliant RTS title that feels a bit like Starcraft. It's got a sci-fi setting and some of the most spectacular strategy mechanics we've seen in mobile games to date. With that said, the RTS genre can be a bit tricky to break... | Read more »
The best new games we played this week -...
The work week can be tough, but on the bright side, it's almost overandthere are bunches of brand new games to try out this weekend. This week definitely makes up for last week's sleepiness ten-fold. We've got one of the finest RTS game on mobile... | Read more »
Through the Ages (Games)
Through the Ages 1.0.60 Device: iOS Universal Category: Games Price: $9.99, Version: 1.0.60 (iTunes) Description: The offical adaptation of Vlaada Chvátil’s strategy classic, the second best board game ever by Board Game Geek website... | Read more »

Price Scanner via MacPrices.net

Wednesday deal: 15-inch MacBook Pros for up t...
B&H Photo has 2017 15″ MacBook Pros on sale for $150-$200 off MSRP. Shipping is free, and B&H charges sales tax in NY & NJ only: – 15″ 2.8GHz MacBook Pro Space Gray: $2199, $200 off MSRP... Read more
2.6GHz Mac mini on sale for $599, $100 off MS...
B&H Photo has the 2.6GHz Mac mini (MGEN2LL/A) on sale for $599 including free shipping plus NY sales tax only. Their price is $100 off MSRP. Read more
Snag a 15-inch 2.2GHz Retina MacBook Pro, App...
Apple has Certified Refurbished 2015 15″ 2.2GHz Retina MacBook Pros available for $1699. That’s $300 off original MSRP, and it’s the lowest price available for a 15″ MacBook Pro currently offered by... Read more
Apple Refurbished 3TB Time Capsule for $279,...
Apple has Certified Refurbished 3TB Time Capsules available for $279 including free shipping plus Apple’s standard one-year warranty. Their price is $120 off MSRP. Read more
19% off Smart Battery Cases for iPhone 7
Amazon has both Black and White Smart Battery Cases for iPhone 7s available for $80.41 including free shipping. Their price is $18.59, or 19%, off MSRP. Read more
Back on sale: 10.5-inch 64GB iPad Pros for $5...
MacMall has 10.5″ 64GB Apple iPad Pros on sale again for $599 including free shipping. That’s $50 off MSRP and the lowest price available for this model from any reseller. Read more
Verizon offers Certified Preowned 16GB iPhone...
Verizon has the 16GB iPhone 6, Certified Preowned, available for $259.99 or $10.83 per month for 24 months. Service plan required. According to Verizon, “All CPO devices have been reconditioned to... Read more
Preorder new iPhone 8 at US Cellular, and tak...
Preorder the new iPhone 8 or iPhone 8 Plus at US Cellular, and take $50 off the prepaid price: – 64GB iPhone 8: $649.99 – 128GB iPhone 8: $799.99 – 64GB iPhone 8 Plus: $749.99 – 128GB iPhone 8 Plus... Read more
12-inch and 9-inch Apple iPad Pros, Certified...
Apple has Certified Refurbished 2016 12″ WiFi iPad Pros available starting at $589. An Apple one-year warranty is included with each model, and shipping is free: – 32GB 12″ iPad Pro WiFi: $589... Read more
QuickerTek Announces Solar PV Chargers for US...
Wichita, Kansas based QuickerTek has announced its new 30 Watt and 60 Watt USB Type-C Solar Juicz Chargers. These solar panels are the only products of their kind, featuring the USB 3.1 adapter cable... Read more

Jobs Board

*Apple* News Product Marketing Mgr., Publish...
Job Summary The Apple News Product Marketing Manager will work closely with a cross-functional group to assist in defining and marketing new features and services. Read more
Development Operations and Site Reliability E...
Development Operations and Site Reliability Engineer, Apple Payment Gateway Job Number: 57572631 Santa Clara Valley, California, United States Posted: Jul. 27, 2017 Read more
*Apple* Solutions Consultant - Apple Inc. (U...
…about helping others on a team while also delighting customers? As an Apple Solutions Consultant (ASC), you will discover customers needs and help connect them Read more
Software/Data Engineer, *Apple* Media Produ...
Job Summary Apple Media Products is the team behind the App Store, Apple Music, iTunes, and many other high profile products on iPhone, Mac and AppleTV. Our Data Read more
SW Engineer , *Apple* Media - Apple Inc. (U...
Job Summary Our team is responsible for exposing Apple Media content and services to the world, and building the infrastructure for next generation internal and Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.