IBM®
Skip to main content
    Country/region select      Terms of use
 
 
   
     Home      Products      Services & solutions      Support & downloads      My account     

developerWorks  >  Lotus  >  Forums & community  >  Best Practice Makes Perfect

Best Practice Makes Perfect

A collaboration with Domino developers about how to do it and how to get it right in Domino

Got this via email from Martijn de Jong:

...How much at risk are we developers when we use undocumented features? Two of these features which I've for example used recently are:
- @LocationGetInfo([HomeServer]);
- Set dbdoc = db.GetDocumentByID("FFFF0010")
  If Not dbdoc.HasItem("$TITLE") Then etc.

I quickly tested the @Formula in Notes 8 beta 1 and it seemed to still work there, although in its documentation it's again undocumented. Should we developers fear that features like these will disappear one day or can we be confident that, having been there for a few versions already, these features are there to stay?

The official IBM position is don't do that, you're on thin ice. But I realize that sometimes it's the only way to reach your goal.

I can't commit as regards future implementation of specific features we haven't chosen to document, but I can say a little bit about our process and what it implies for these features.

Frequently, we add functions because the template development team needs them. Often, our schedule is tight; we have enough time to add and test the function for the specific use the template developers have in mind, but not enough time to test it fully (or sometimes, not enough time to implement it fully). As always, we have to make judgments about what's most important to include, and "finishing" a function can take a surprising amount of effort.

When there's not enough time to assure quality of a function, we don't document it. So you are basically using it at your own risk. The function is unlikely to go away, because it would break old copies of our own templates, and we want to avoid that at all costs. But the functionality could change in ways that don't break our own old apps, so you're at risk if you use these functions in ways that we don't. Our regression tests don't cover "off-label" uses, so even if the function works now, there's no guarantee that it will continue to do so in future versions.

In the specific cases you cite, the special note ID for the icon note is a long-standing custom that there's really no reason to change. A lot of API programs rely on it, including our own, so there's disincentive for us to change it. Again, if it's not in official documentation, I can't guarantee it, but I wouldn't feel nervous about using this in a Notes application.

I'm not actually familiar with the "[HomeServer]" option. If it's used in a formula in one of our applications, I think it's safe to assume that whatever the formula does now, it will continue to do, for the reasons I cited above. However, I consider it possible that the keyword [HomeServer] might change. For instance, we might decide we needed two variants of this function, change [HomeServer] to [HomeServerA] and add a new keyword [HomeServerB]. When a formula is compiled, square bracket keywords are changed to a number internally, so if you look at an old formula that used [HomeServer], it would now display [HomeServerA] because that's the new word corresponding to the number ID. Presumably, it would continue to work as before. This is the same thing that happened with the original @Username function, which changed to @V3Username so that we could have a new @Username function that works differently.

A change to the keyword text wouldn't be a problem for a normal formula, but it would cause a problem if you used an Evaluate statement or @Eval, since the string containing the formula to evaluate contains the obsolete keyword.

In general, think about different scenarios and exercise judgment. Some rules of thumb:

  • Don't rely on a behavior that could be seen as a bug. We're likely to fix it at some point.
  • The more widely an undocumented function is used by customers, the less likely it is to change in a way that will break apps. This is one of the things we consider. If it's been given as a tip dozens of times over several years, you're somewhat safer.
  • You're safer if you stick to using the function in the way we use it, as our pre-release test cases probably cover that use.
  • Consider in what ways we might plausibly want to change the function. Is there something we might do to it that would be considered an enhancement in the context where we use it, but that would cause you a problem in the way you want to use it?

Andre Guirard | 15 August 2007 03:03:55 PM ET | Café Porch, Plymouth, MN, USA | Comments (1)


 Comments

1) Thanks! More explanation on @GetLocationInfo
Martijn de Jong | 8/20/2007 6:12:54 AM

Thanks for your answer Andre. The note ID for the icon note is special is a function for which the only other way to get the same functionality which I use it for now, would be to use the C API and with platform dependabilities and the sorts that's often quite tricky.

Regarding @LocationGetInfo. This @Function just return the values from certain fields in the active location document. A couple of parameters for it are:

@LocationGetInfo([HomeServer])

@LocationGetInfo([CatalogServer])

@LocationGetInfo([SametimeServer])

@LocationGetInfo([NamePreference])

@LocationGetInfo([MailProtocol])

@LocationGetInfo([WebRetriever])

@LocationGetInfo([BookmarksFileName])

@LocationGetInfo([InternetMailAddress])

@LocationGetInfo([AreaCode])

More info on for example this website: { Link }

Also in the Domino forums there are quite a few mentions of this @Formula

 Add a Comment
Subject:
   
Name:
Comment:  (No HTML - Links will be converted if prefixed http://)
 
Remember Me?     Cancel

Search this blog 

Disclaimer 

    About IBM Privacy Contact