Config::LotusNotes - Access Lotus Notes/Domino configuration

NAME

Config::LotusNotes - Access Lotus Notes/Domino configuration

VERSION

This documentation refers to Config::LotusNotes 0.23, released Oct 31, 2006.

SYNOPSIS

  $factory = Config::LotusNotes->new();

  # access default installation
  $conf = $factory->default_configuration();
  $data = $conf->get_environment_value('Directory');
  $conf->set_environment_value('$NotesEnvParameter', 'value');

  # find all installations 
  @installs = $factory->get_all_configurations();

DESCRIPTION

Config::LotusNotes gives you a view of your local Lotus Notes/Domino installations from the filesystem perspective. Its main purpose is to read and manipulate the main Notes configuration file, notes.ini.

The module can handle multiple installations.

You can use it to

 - enumerate local Notes/Domino installations
 - gather basic information about your local Notes/Domino installations 
 - exchange data with Lotus Notes via the environment functions.

A Config::LotusNotes object searches the Windows registry for Lotus Notes installations, which can then be accessed in their representations as Config::LotusNotes::Configuration objects.

The Lotus Notes environment

The Lotus Notes environment is often used to store local user preferences and to share information between separate parts of an application.

The Lotus Notes formula language has the @Environment and @SetEnvironment functions and the ENVIRONMENT keyword to access the program's environment. Lotus script uses the GetEnvironmentValue, GetEnvironmentString, SetEnvironmentVar and Environ functions for that purpose. The Lotus Notes environment is stored in the notes.ini file, which is instantly updated after each change to the environment. This allows you to communicate data to external programs.

Unfortunately, Lotus Notes does not recognize external changes to notes.ini while it is running. If you need to push data to a running instance of Lotus Notes, you can use the environment functions of the corresponding OLE object as shown in SEE ALSO. There might be problems with simultaneous programmatic and user access to the same Lotus Notes session.

METHODS

new();

Constructor, returns a Config::LotusNotes object that can give you Config::LotusNotes::Configuration objects via its default_configuration() and all_configurations() methods.

default_configuration();

Returns a Config::LotusNotes::Configuration object for the default Lotus Notes installation. The default installation is the one that is registered in the Windows registry as the handler for the Notes class.

If there is only one version of Lotus Notes installed on your machine, this is what you want.

This method will throw an 'No Lotus Notes/Domino installation found' exception if it cannot find any Lotus Notes installation.

all_configurations();

This gives you an array containing one Config::LotusNotes::Configuration object for each Lotus Notes/Domino installation found on your machine. If no installation is found, an empty array is returned. In rare cases, an installation might not be detected. See BUGS AND LIMITATIONS for details.

SEE ALSO

An alternative way of accessing Lotus Notes/Domino is via its OLE and COM scripting capabilities. Here is an OLE example:

  use Win32::OLE;

  # print Lotus Notes version:
  $Notes = Win32::OLE->new('Notes.NotesSession')
      or die "Cannot start Notes.NotesSession object.\n";
  ($Version) = ($Notes->{NotesVersion} =~ /\s*(.*\S)\s*$/); # remove blanks
  printf "Running Notes \"%s\" on \"%s\".\n", $Version, $Notes->Platform;

  # write value to environment
  print "Setting $key to $value\n";
  $session->SetEnvironmentVar('$NotesEnvParameter', 'test value');

This will start an instance of Lotus Notes if none is already running. See the Lotus Notes designer documentation for more information.

DIAGNOSTICS

Call the constructor method new() with the option debug => 1 to get diagnostic information on the search progress.

DEPENDENCIES

This module only runs under Microsoft Windows (tested on Windows NT, 2000 and XP). It uses Win32::TieRegistry and Config::IniFiles (which ist not a standard module). The test require Test::More. Optional modules for the tests are Test::Pod and Test::Pod::Coverage.

BUGS AND LIMITATIONS

Problems locating installations

Lotus Notes/Domino stores information about the installed versions in registry keys that are specific to the main version number only, e.g. 5.0, 6.0 and 7.0, with ".0" being fix. Each additional installation will overwrite the data of any previous installation that has the same main version number.

This module works around this problem by searching several additional places in the registry for possible installation locations. In complex installations this might not find all instances.

Please bear in mind that such complex situations can only be created if you cheat the Notes installer by renaming the paths of your existing installations before each additional installation. The normal behaviour of the installer is to force you to update your previous installation. So in real life, there should be no problem with missed installations.

Problems parsing notes.ini

If the notes.ini file is malformed, a warning will be issued and the corresponding installation will be skipped by all_configurations(). default_configuration() will throw an exception in that case. The reason for this is that Config::IniFiles cannot handle corrupt ini-files.

Malformed notes.ini files can be produced by writing multiline values to the environment, e.g. with Notes formula code like this: @SetEnvironment("testvalue"; "A"+@Char(10)+"B"), which produces two lines, the second one just containing "B". A successive read of testvalue will return just "A".

If you run into this kind of problem, check whether all lines except the first one are of the pattern parameter=value. If not, back up your notes.ini and delete any line with no "=" (except the [Notes] line, of course). Try again.

On the Config::IniFiles project homepage at http://sourceforge.net/projects/config-inifiles/ you can find a patch to "Support MySQL my.cnf". This patch also enables Config::IniFiles to work with corrupt notes.ini files.

EXAMPLES

  use Config::LotusNotes;
  $factory = Config::LotusNotes->new();

  # get default LotusNotes installation
  $conf = $factory->default_configuration();
  print 'Lotus Notes ', $conf->version, ' installed in ', $conf->notespath, "\n";

  # retrieving and setting notes.ini values
  # get name of the user's mail file.
  $mail_file = $conf->get_environment_value('MailFile');
  # store a value in notes.ini
  $conf->set_environment_value('$NotesEnvParameter', 'test value');

  # find all installations 
  @all_confs = $factory->all_configurations();

  # print a table with version, type and path of all installations.
  # see demo\FindNotes.pl for an extended version.
  printf "%-8s %-7s %s\n", 'version', 'type', 'path';
  foreach my $conf (@all_confs) {
      printf "%-8s %-7s %s\n", 
          $conf->version, 
          $conf->is_server ? 'server' : 'client', 
          $conf->notespath;
  }

  # filter the list: only servers
  @servers = grep { $_->is_server } @all_confs;

LICENCE AND COPYRIGHT

Copyright (C) 2006 HS - Hamburger Software GmbH & Co. KG. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

This library is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantibility or fitness for a particular purpose.

AUTOR

Harald Albers, albers@cpan.org

Version 0.1 written 10/2003. See the Changes file for change history.