Genii Weblog

Foolish consistency is the hobgoblin of little minds

Fri 19 Sep 2003, 12:35 AM



by Ben Langhinrichs
OK, I've probably bored everybody to death on the subject of @Midas Formulas, and I don't know whether anyone is reading these or not anymore (Actually, that isn't quite true.  Due to the wonders of Nedstat, I know that yesterday 52 people read my blog, and they read 103 pages, but I don't know whether they were happy about it).  Anyway, here's a promise.  Stick with me through just one more, and I'll try to write a nice juicy Rich Text 101 article tomorrow.  Is it a deal?

I feel that it is very important when writing an extension to a language to be consistent with the way things are done in that language (except when they are done wrong, and then all bets are off).  When writing the Midas Rich Text LSX, I wanted to make it easy, but I also wanted to make it work the way LotusScript seemed to work.  [Note: I think the Notes 6 developers missed this when they added the new rich text classes, and even more the XML classes.  Instead, they tried to make the LotusScript classes consistent with the C++ API classes, which I feel was a big mistake.  Anyway, that is the topic for another blog one day.]

Similarly, when working with the formula language, I try to stay consistent with the way the current @formulas are written.  But what am I to do when the formula language itself isn't consistent.  Take, for example, @Environment.  This function gets or sets the value of an environment variable.  That's right, it does either.

Using @Environment to get the value of an environment variable

If your formula says:

@Environment("LastReturnState")

and there is an environment variable called LastReturnState with the value Ohio, then the return value is Ohio.

Using @Environment to set the value of an environment variable

If your formula says:

@Environment("LastReturnState"; "Michigan")

then this sets the value of the LastReturnState environment variable to the value Michigan.

So why isn't there a single function @DocValue?

To be consistent with @Environment, which has been around for a gazillion years, there should be a single function called @DocField.  It would have two required parameters, and one options.  @DocField(unid; fieldname) would return the value, the way @GetDocField does now.  @DocField(unid; fieldname; newValue) would set the value, the way @SetDocField does now.  Similar get/set pairs are found with @Field, @ProfileField, @TargetFrame.  In fact, they even added a new function called @SetEnvironment which does the same thing as the latter use of @Environment.  One can only presume that a new developer was working on formulas by this time, and that new developer was more comfortable with Java than with C++.  Or, it is simply possible that the developers agreed with Ralph Waldo Emerson about foolish consistency.

OK, Ben, what's your point?

I'm getting there, I'm getting there.  Let's return to the intriguing (to me) concept of treating rich text fields as data, especially by using @DbColumn/@DbLookup on rich text tables.  I have blogged about how to do this with @Midas.  I have blogged about how to use the same technique in Java.  Now, let's take it one step further.  

I could define a function using @DbCommand to set a column of data in a rich text table, but it doesn't seem consistent.  What occurs to me is, why not be consistent with @Enviornment?  Why not use the syntax

@DbColumn("Midas" : "NoCache" ; server : database ; 
                              @DocumentUniqueID ; columnNumber )

to get the value of a column, and use

@DbColumn("Midas" : "NoCache" ; server : database ; 
                             @DocumentUniqueID ; columnNumber ; columnValues )

to set the value of a column.  Similarly, use:

@DbLookup("Midas" : "NoCache" ; server : database ; 
                             @DocumentUniqueID ; fieldName ) or
@DbLookup("Midas" : "NoCache" ; server : database ; 
                             @DocumentUniqueID ; key ; columnNumber )
to get the value of a particular column or field based on a key, then use

@DbLookup("Midas" : "NoCache" ; server : database ; 
                             @DocumentUniqueID view ; key ; fieldName ; fieldValue ) or
@DbLookup("Midas" : "NoCache" ; server : database ; 
                            @DocumentUniqueID; key ; columnNumber ; columnValues )

In our table from  before, we took a table such as this one from the Partnerworld site and put it in a rich text field:

IBM Value Package for Developers
Annual fee
North America, Europe, Middle East, Africa 
$595 
Latin America 
$750 
Asia Pacific region
$350

Then, we specified a command such as:

prices := @DbColumn("Midas"; @DbName; @DocumentUniqueID; "Body";
                                             2; "Format='Currency' SkipTitle='Yes' ");

and the prices were returned as three numeric values in a multi-value list.  What if we could use our new alternate syntax and say 

@DbColumn("Midas"; @DbName; @DocumentUniqueID; "Body";
                           2; "Format='Currency' SkipTitle='Yes' "; 625:775:375);

and the table would change to:

IBM Value Package for Developers
Annual fee
North America, Europe, Middle East, Africa 
$625 
Latin America 
$775 
Asia Pacific region
$375

Now try to guess what would happen if we specified the following two commands in a row with too many values:

@DbColumn("Midas"; @DbName; @DocumentUniqueID; "Body";
                           2; "Format='Currency' SkipTitle='Yes' "; 625:775:375:515:775);
@DbColumn("Midas"; @DbName; @DocumentUniqueID; "Body";
                           2; "Format='Currency' SkipTitle='Yes' ";
                           "North America, Europe, Middle East, Africa":"Latin America":"Asia Pacific region":
                           "Antarctica":"Pacific Islands");

You would get the following result:

IBM Value Package for Developers
Annual fee
North America, Europe, Middle East, Africa 
$625 
Latin America 
$775 
Asia Pacific region
$375
Antarctica
$515
Pacific Islands
$775

There are a few loose ends, but this is nearly complete for @Midas Formulas.  Let me know what you think.

Copyright © 2003 Genii Software Ltd.

What has been said:


50.1. Thomas Duff (09/19/2003 05:40 AM)

Yes, we're reading, and yes, we like it... :-)


50.2. Julian Robichaux (09/19/2003 08:07 AM)

Ben -

Definitely keep the technical stuff coming, regardless of what it's about (@Midas, Rich Text, whatever). There are (at least) two reasons why it's great:

1. For your existing customers, it's good knowledgebase kind of information. You can never have too many code samples, or too many examples of where, when, or how to use something.

2. For developers who aren't Midas customers, this is great to read because a lot of the things you're talking about are real eye openers. "Oh my gosh, I thought that was impossible. You mean you can do that with just a few lines of code?"

I hate to admit it, but I'm in the second category, and I'm thoroughly enjoying the Midas information. I've never happened to work for a company that already has the product, nor have I worked on a project that demands the functionality, but now I can file this information in the back of my mind as a good option if I ever have the need. When and if I do have the need, I'll just call you up (or e-mail you, or send you a telegram, or whatever).

Keep on truckin'.

- Julian