Open Hypermedia Systems Working Group
Fred the programmer - Scenario
| OHSWG | 1997.03.13 |
Open Hypermedia Systems Working Group
Fred the programmer - Scenario
Authors
Kasper Østerbye
Updates
Most recent: 13 March 1997
References
Other Links
At the moment Fred is having problems with understanding the Miracle API. He is using the MegaSoft visual C++ development environment. The problem lies somewhere in the search routine he is developing. The idea is that the customer can type in free text descriptions, and the server will then respond with parts corresponding to the description. First guess is that it is the "pullDescription" that doe not properly return the string from the client message. He clicks on pullDescription in the editor, and a new window opens with the code for this procedure. "I always get this wrong Fred thinks" - "to get to the documentation you have to shift click the identifier so that it will use the CCLE (Corporate Collaborative Link Engine - by ViceCosm), rather than the build in hypertext facilities of MS Visual C++."
The documentation and a simple test convinces Fred that the pullDescription is not the problem. Somewhere else then. The function that categorizes keywords so that they can be searched for in the database is written by Fred himself, so he is certain that that is not the problem. "Is there something I have missed from the telephone-based system?" he wonders. He has forgotten where the design document is, but knows where the maintenance manual for the telephone-based system is, as he was in charge of that himself. And sure enough, on the first page it says "to get a overview of the system - read the introduction to the *Design Document*". He clicks on "Design Document", and CCLE resolves the link. "Document viewer for WordPerfect 2.1 now available" it responds. Fred ponders if it is worth the effort to find some one who has an old version of WordPerfect around. His version of Word will not convert WordPerfect documents that old. He decides against it, and hope that he is not fundamentally wrong.
"Didn't Barney do a free text search routine when he was here" Fred suddenly remembers. He loads the telephone system into the programming environment as the CCLE does not support wildcards in the link resolution mechanism, but the programming env. does. He search for all links tagged with "search" or "find", and among 16 hits, he sees Barney's routine. He follows the link, and the programming environment brings up the file, and scrolls to the appropriate place. The comment looks promising, but the routine is huge. He ..."shift clicks" on the routine name to get to any other stuff that is linked to this. There are again a number of possible hits from CCLE. But there is also a warning that "location specifier not link-resolvable". "I wish they would just use the net Fred punders, there I am lost but not put down". But the entry is selectable, and after a bit of investigation it turns out the link-base that Barney used is no longer available. An other dead end.
He returns to his own code. "There is the call to the Miracle database to perform a relational select". "Can't be that Fred thinks" but he decides to check it out anyway. Clicks on "select" and the source code pops up. "Not again..". He shift-clicks on the "select" identifier, and CCLE looks up this link. It is in the context of a module that uses the Miracle-API, so we also need to include links from the Miracle company online documentation. The CCLE gets the appropriate documentation page from Miracle, and displays the result in the Netscape browser. Fred is puzzled. The code seem to be just according to the specifications, but never the less, the database does not seem to return the right results. Fred decides to ask the resident Miracle expert. He writes a short description of the problem, with links to the documentation he relies on to the files he is using including the little test program he is not able to get to work. He then mails a reference to this description to Wilma.
He closes down the programming environment and starts to write a log entry about where he got to regarding the search routine. He adds a link to the message he sent to Wilma, and makes a personal note that he suspects in some way that the wrong database table is being used. He heads of for lunch - "Hope the afternoon is going to more productive!"
Wilma reads the message from Fred and look up the various aspects regarding the miracle database (just like people are always home to answer the phone in movies, programmers always respond to you call for help in scenarios). She reads the message - "Oh no, not again. He is relying on online documentation from the web." She follows the link to the page describing the select call. When scrolled to the very end she gets the version number. "As I thought, they have now a newer version of the Miracle database than we have. Silly plot to get people to upgrade!" Wilma decides to update (or is it downgrade) the entry in CCLE to use the old index and pages when looking up links to Miracle. She the follows the link to Fred’s test program, which brings up the MS Visual C++ environment and makes it scroll to where the call to select is done. She does the simple changes necessary, and the test program works. She writes an answer to Fred, stating that the documentation was wrong, but the it should be OK now, and includes a link to the corrected test program.
When Fred returns, he looks at the new documentation. The test program works fine, but he is quite annoyed that he cannot get to the new documentation, perhaps there was a way to make this "forward compatible", sometime soon we will get the new version of this Miracle database, and then I might have to change it. Well, he knows, the designers of CCLE say versioning of links across hypertext systems will be included in the next major release, but they always say so. He makes a entry in his log, and links it to the source of the search routine, so that he (or someone else) will at least know the problem and its solution when it arises next time.
Kasper Østerbye