A Lotus Notes and Domino blog

IsArrayInitialised()

Glen Urban  August 4 2010 11:56:42 AM
Surprisingly LotusScript doesn't provide this but here's a function to test if a dynamic array is initialised.

Function IsArrayInitialised(a As Variant) As Boolean
 'returns True if an array is initialised
  On Error Resume Next
  IsArrayInitialised = False
  IsArrayInitialised = (Ubound(a) >= Lbound(a)) ' will generate error if not initialised    
End Function

NotesDatabase.Server Inconsistency

Glen Urban  April 13 2010 02:42:32 PM
Consider the following LotusScript code
Dim session As New NotesSession
Print session.CurrentDatabase.Server


Would you expect the server name to be in an Abbreviated (e.g. SERVER/GB/ACME) or Canonical format (e.g.CN=SERVER/OU=GB/O¬ME )?

The answer is "it could be either": I experienced a problem in some code that depended upon this property, on one Notes client it evaluated to an Abbreviated name and on another to a Canonical name. Both clients were 8.5.1. Both running on the same server. The only obvious difference was that the designer client was installed on one client machine but not the other.

I resolved the problem by forcing a conversion to a canonical format so that the code worked regardless of how database.server decided to return the name.

Has anyone else experienced this problem?

notesUIWorkspace.RepaintScreen()

Glen Urban  March 11 2010 03:21:34 PM
Ever wished you had a method to repaint the screen?

Recently I was working on some automation with Microsoft Word and wanted to display a message to the user warning them that the processing may take a while. I used a hide-when formula to display a message on my form but I found that the screen did not repaint correctly. Some controls on the form that should have been hidden were still displayed.

As far as I know there is no way in LotusScript to repaint the screen. To resolve this we can make a call to Windows to do the refresh for us.

Declare Function GetActiveWindow Lib "user32" Alias "GetActiveWindow" () As Integer
Declare Function UpdateWindow Lib "user32" (Byval hWnd As Integer) As Integer

Sub RepaintScreen
On Error Resume Next
Call UpdateWindow(GetActiveWindow())

End Sub

Dynamically Hide/Display Rich Text Fields

Glen Urban  January 9 2010 02:34:09 PM
Many Notes developers are aware of the problems with using Hide When formula on Notes Rich Text fields. It can have unpredictable results on the contents of the field, these are detailed in an IBM Technote here. In that note two solutions are proposed 1) use a computed Subform and 2) use a Controlled Access Section.  But these solutions are not without their problems.

On reading this blog entry it suddenly occurred to me that using a Layer could offer a better solution.
1) Create a Layer and place the Rich Text Field on that layer.
2) When you create a layer you will see that it has a Layer Anchor. You can set a Hide When formula on this anchor.

The advantages of this approach are:
1) The Hide When is not on the Rich Text Field so no unpredictable results
2) You can hide/show the Layer/Field dynamically. In the screen shot below I have used a Radio Button that can show/hide the Rich Text field.


Image:Dynamically Hide/Display Rich Text Fields

Dojo Samples

Glen Urban  December 1 2009 03:45:44 AM
If you are are looking for Dojo samples then you don't have to go far. With 8.5.1 the Dojo 1.3 toolkit and samples are installed with the designer client and server.

Dojo is installed in the data folder: data\domino\js\dojo-1.3.2\

If you browse through the folders you will see that there is a convention to add a tests folder with samples. Within this folder the samples are zipped into a file called tests.zip. Simply extract the zip file to see the sample web pages and code.

So, for example, if you wanted to see the charting samples you would extract the zip file data\domino\js\dojo-1.3.2\dojox\charting\tests\tests.zip

Remember when you preview (not just open the file) in your browser, replace domino\js with domjs. So if you wanted to preview the 2D pie chart sample on your local client you would use the following url: http://localhost/domjs/dojo-1.3.2/dojox/charting/tests/test_pie2d.html

One thing to be aware of is that if you try to open runTests.html it won't work because it references a file that is not in this version of the Dojo toolkit. You need to open each sample separately.

How to add a Dojo Chart to a Domino Form

Glen Urban  November 25 2009 09:27:49 AM
Creating a Dojo chart in Domino took a step forward with release 8.5.1. When you install or upgrade a Domino server Dojo 1.3.1 comes as standard.

If your looking to get started on Dojo charts then you should take a look at this guide on sitepen: A Beginner’s Guide to Dojo Charting.

The following builds on the code shown in that guide and describes how to add a Dojo chart to a Domino form. The JavaScript below needs to be in the JavaScript Header. I used pass through HTML on to my Domino form so added an opening and closing <head></head> tag (at the start of step 1 and the end of step 3).

1. Include a reference to the Dojo library

<head>
<script type="text/javascript" src="/domjs/dojo-1.3.2/dojo/dojo.js" djConfig="locale: 'en-gb', isDebug:false"></script>

2. Populate your JavaScript Variables from your Domino Data

<script type="text/javascript">
var fc = "<Computed Value>" ; // the Fill Color for the columns
var sc = "<Computed Value>" ;// the Stroke Color i.e. column outline colour
var series1 = [<Computed Value>]; // an array of data for the chart
var xlabels = [<Computed Value>]; // an array of x axis labels
</script>

Because I have written pass thru HTML on my form I can use Computed Text to reference data in my Notes application. For example, the formula within the Computed Text used to define variable fc is just "lightblue". This could easily reference a field on the form or do a look up to a configuration document.

Variable series1 needs to be an array. Here the Computed Text references a multi value field on my form. Again this field could look up data on the same form or elsewhere in your database. Keep in mind that JavaScript arrays are delimited by commas so this should evaluate to something like "1, 9, 9, 3, 5, 3, 2, 7, 9, 10"

The xlabels variable is a bit more complicated. It needs to be formatted like this:
{value: 1, text: "a"}, {value: 2, text: "b"}, {value: 3, text: "c"}, and so on...

To achieve this I have a multi value field on my form that lists the x axis labels i.e. "a":"b":"c":"d":"e":"f":"g":"h":"i":"j".
The Computed Text uses the following @Formula to parse it into the format necessary for Dojo.
@For(n :=1; n<=@Elements(XaxisLabels); n:= n + 1;
lblTxt := @If( n=1;
                        "{value: " + @Text(n) +  ", text: \"" + XaxisLabels[n] + "\"}" ;
                       lblTxt : (  "{value: " + @Text(n) +  ", text: \"" + XaxisLabels[n] + "\"}" )
                                )
);
lblTxt

3. Add the JavaScript code that will generate the graph

<script type="text/javascript">
dojo.require("dojox.charting.Chart2D");
var chart1;
makeCharts = function(){
chart1 = new dojox.charting.Chart2D("simplechart");
chart1.addPlot("default", {type: "Columns" , gap: 2});
chart1.addAxis("x" , {labels: xlabels  } );
chart1.addAxis("y", {vertical: true , min: 0});
chart1.addSeries("Series1", series1 , {stroke: {color: sc, width: 2}, fill: fc } );    
chart1.render();      
};

dojo.addOnLoad(makeCharts);
</script>
</head>

4. Add a HTML Div tag to your form

Now all that's needed is to place a div on your form, using pass thru HTML, wherever you want your chart to appear. Alter the height and width options to specify the size of your chart.
<div id="simplechart" style="width: 500px; height: 250px;"></div>


The resulting chart will look something like this
Image:How to add a Dojo Chart to a Domino Form
This chart is very basic and there is much more you can do with Dojo: multiple data series, 3D charts, stacked charts and so on.  

Setting up a Data Connection Resource (DCR) to an ODBC database

Glen Urban  November 19 2009 12:30:29 PM
DCRs allow developers to use Domino Designer to create connections from their Notes/Domino application to "enterprise" data in relational databases such as MS SQL, DB2, Oracle or any other data source that has an ODBC driver. It uses DECS technology and as a prerequisite DECS must be installed and running on the server. Once you've configured a DCR, and a corresponding Notes form, any data updated on the Notes form will update your back end data and, similarly, any updates to the back end data will be reflected on your Notes form.

DCRs are targeted at developers where as DECs are seen as more of an administrator tool. In reality either tool can be used to achieve the same goal but today I am looking at DCRs from a developers point of view. Having said that the first two steps would normally be seen as the role of your Domino server administrator and not a developer.

1. Ensure DECS is installed and running on the server.

DECS is an option in the server tasks to include when you install a new server. If you want to add the DECS task to an existing server ensure that the notes.ini "ServerTasks=" line has an entry for "DECS" and on a separate line add the entry "EXTMGR_ADDINS=decsext"

ServerTasks=....., DECS
EXTMGR_ADDINS=decsext

2. Use the ODBC data Source Administrator to create a Data Source.

(I'm assuming we are using a Windows server here)
On the Domino server where your Notes application will reside open the ODBC administrator (usually found in Control Panel -> Administrative Tools -> Data Sources) and create a System DSN connection to your enterprise database.

Image:Setting up a Data Connection Resource (DCR) to an ODBC database
Once you've pressed the "Add.." button the exact procedure will depend upon the specific ODBC driver for your back end data source.

3. Create the DCR in Domino Designer

Depending upon which version of the designer client you are using a DCR is created in under Data -> Data Connections (8.5) or under Shared Resources -> Data Connections (6.5 and 7)

Press the "New Data Connection Resource" button. We are using an ODBC source so under type choose "ODBC" and for "Name" enter the name of the ODBC data source you created in step 2.

Image:Setting up a Data Connection Resource (DCR) to an ODBC database

There is an option for a user name and password here but for an ODBC connection I would define those when you create the DSN in step 2.

You have the option to select a specific table/view to use for this DCR but can leave this blank and choose these later.

4. Set the Database Property

Set the database property "Allow connections to external databases using DCRs"

You will need to close and re-open the database before this option is recognised.
Image:Setting up a Data Connection Resource (DCR) to an ODBC database

5. Design your Form

Now you can add fields to a form and define the mapping to your external database. Select the tick box "External data source" on the first tab of the Field properties and a further set of Data Source Options appear at the bottom of the dialog box.
Image:Setting up a Data Connection Resource (DCR) to an ODBC database
Press "Browse" and select the DCR you defined in step 3. Then select the Table and Field in the external database that your Notes field maps to.

Your Notes form must have a Key field that corresponds to the primary key in your external data source. This Key field value will always be stored in the Notes document to maintain the link with your external data. For other fields you have the option to "store data locally". Storing your data locally allows you to use the data in views but if the back end data changes the your view maybe out of date until your Notes document is opened and saved again.

6. Import the Data to your Notes Database

Before importing any data you must turn off the database property "Allow connections to external databases using DCRs" (turned on in step 4).

From Domino designer select the DCR you created and when you press the "Import External Records" button you will then be prompted to select for which Form you want to import the data. Corresponding documents will be created for each record in your external data.

Once you turn back on the database property  "Allow connections to external databases using DCRs" you will be ready to use your application.


Important Considerations

If a new record is added in your back end data a corresponding document will not be added to your Notes database. If this is a must then may want to consider other options such as Lotus Enterprise Integrator.

Creating a new document in your Notes application can create a corresponding record in your back end data. There is an option on the second properties tab of the DCR called "Action on missing record" that dictates what happens in this instance.