view release on metacpan or  search on metacpan

lib/Config/LotusNotes.pm  view on Meta::CPAN

L<Config::LotusNotes::Configuration|Config::LotusNotes::Configuration> objects
via its default_configuration() and all_configurations() methods.

=item default_configuration();

Returns a L<Config::LotusNotes::Configuration|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 C<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.

=item all_configurations();

This gives you an array containing one
L<Config::LotusNotes::Configuration|Config::LotusNotes::Configuration> object
for each Lotus Notes/Domino installation found on your machine.
If no installation is found, an empty array is returned.

=back

=head1 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.

=head1 DIAGNOSTICS

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

=head1 DEPENDENCIES

This module only works with Microsoft Windows.
It has been tested on Windows NT, 2000, XP and 7 (64-bit).
It uses L<Win32::TieRegistry|Win32::TieRegistry>,
L<Config::IniHash|Config::IniHash> and L<File::HomeDir|File::HomeDir>
(the latter two not being standard modules).
The test require Test::More.
Optional modules for the tests are Test::Pod and Test::Pod::Coverage.

=head1 BUGS AND LIMITATIONS

Please report any bugs or feature requests through the web interface at
http://rt.cpan.org/Public/Bug/Report.html?Queue=Config-LotusNotes

=head2 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.

=head2 Malformed notes.ini files

Under certains conditions a F<notes.ini> file may contain malformed lines,
i.e. lines that do not match the pattern C<parameter=value>.

Such lines are ignored when reading values.
If you write back values to a corrupt F<notes.ini> file using the
L<set_environment_value()|Config::LotusNotes::Configuration/set_environment_value>
function, the malformed lines are removed from F<notes.ini>.

If a F<notes.ini> file cannot be parsed at all, a warning will be issued and the
corresponding installation will be skipped by all_configurations()Z<>.
default_configuration() will throw an "Error parsing ..." exception in that case.

Malformed F<notes.ini> files can be reproduced by writing multiline values to the
environment, e.g. with Notes formula code like this:
C<@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".

In my environment lines like

 3.2008 09:32:30

are quite common and seem to originate from the Smart Upgrade process.

=head2 Parameter order in notes.ini

If you write to a F<notes.ini> file with the
L<set_environment_value()|Config::LotusNotes::Configuration/set_environment_value>
function, the entries in that file will appear in random order.
This should not pose any problems.

=head1 EXAMPLES

=head2 code example