Dev buchan leveraging the notes c api

© 2007 Wellesley Information Services. All rights reserved.
Leveraging the Notes
C API in LotusScript:
“A How-to Guide”
Bill Buchan
HADSL

2
What We’ll Cover …
• Introduction
• Architectures
• Platform differences
• Calling simple Notes C API
• Notes C API handles
• Custom classes help hide platform differences
• Complex Notes C API
• Pros and cons
• Wrap-up

3
Target and Purpose
• Who is the target audience?
 Advanced Lotus Notes Developers
 Developers who have a little experience in C API
• What is this about?
 This talk demonstrates advanced LotusScript, showing the
Notes C API interface
• Why Notes C API?
 900+ supported methods
 Many complex tasks can be called via API

4
Who Am I?
• Bill Buchan
• Dual Principal Certified Lotus Professional (PCLP) in v3,
v4, v5, v6, v7
• 10+ years senior development consultancy for Enterprise
customers
 Learn from my pain!
• 5+ years code auditing
• CEO of HADSL
 Developing best-practice tools

5
Notes C API Programming Toolkit
• Where can you find information on C API?
 The Lotus Notes C Programming toolkit
• The toolkit:
 Contains two documentation databases
 Documents each function and structure
 Includes a large number of sample C programs
 Provides compile-time libraries for all platforms
• Generally speaking, backward compatibility is good
 For instance, if you have v6 and v7 servers, creating the
program using v6 of the API toolkit means that it will run on v6
and v7 servers

6
• Introduction
• Architectures
• Pros and cons
• Wrap-up

7
Notes/Domino Architectures
• Domino is a multi-platform server product
• Notes now supports four clients:
 Windows, Mac (Power PC), Mac (Intel), Linux
• LotusScript supported from v4.x of Notes, on all server
and client platforms
 Rich set of APIs for general business logic
 Robust, supported environment for general business
applications
 Amazing level of multi-platform support
• What if you want to go further?
 Exploit a piece of Notes C API interface?
 Call a platform-specific DLL?

8
Why Worry About Platform Independence?
• Currently, something like:
 90% of all Domino servers run on Windows
 95% of all Notes clients run on Windows
• Why not write platform code for that and that alone?
 A short-sighted decision
 Your environment may start supporting more platforms
 Windows 64-bit coming over the horizon
 Treat it as a separate platform
 As was 16-bit Windows
• Corporate push to centralize and consolidate
 Especially on medium-high level platforms
 Linux, Solaris, AIX, HP/UX

9
Be Pragmatic — The Skills Triangle
Few Code Examples
C API
LotusScript, Java
Many Code Examples
Easier
Harder

10
Be Pragmatic
• Call the Notes C API from LotusScript if:
 You cannot find a supported architectural solution
 You have the skills to support Notes C API coding
 You might possibly require multi-platform code
 You accept that this code will be harder to write, harder to
maintain, and harder to support

11
Architectures — Conclusion
• If you have to step outside the comfort zone, you have
two choices:
 LotusScript eXtension Toolkit (LSX)
 This builds a library — on Windows, a DLL — which allows
you to extend LotusScript with custom C code
 Fairly straightforward
 Not part of this presentation
 LotusScript calling the Notes C API interface directly
 Not straightforward
 One code base can cover all platforms

12
• Introduction
• Architectures
• Pros and cons
• Wrap-up

13
Platform Differences: Definitions
• In LotusScript, platform differences are taken care of
 Not so in direct LotusScript to C API calls
• Each platform represents data in a subtly different
manner
 For instance, the HANDLE datatype has different lengths on
different platforms:
 32 bits long in Windows and OS/400
 16 bits long on AIX, Macintosh, etc.
 Memory alignment widths on iSeries are different from other
platforms

14
Platform-Specific Implementations
• In order to call the Notes library, you will have to link to
different library files on each platform:
 Windows/32: nnotes.dll
 Solaris, Linux: libnotes.so
 AIX: lnotes_r.a
 HPUX: libnotes.sl
 MacOs, OS/X: NotesLib
 OS/400: libnotes.srvpgm
 OS/390 libnotes
 OS/2: lnotes.dll
 Windows Alpha: anotes.dll

15
Platform Differences: Endians
• Little endians
 Some platforms represent multi-byte numbers with the lowest
value bytes in the lower segments of memory
• Big endians
 Macintosh (on PowerPC!) represents the larger value bytes in
the lower segments of memory

16
Coding for Platform Differences
• Our challenge is to construct a code sequence that:
 Knows which platform it’s running on
 Makes calls to the platform-specific library file
 Understands platform differences in terms of alignment and
data item size
 And most importantly — fails “safe” when presented with a new
platform that it cannot deal with
• This is not a trivial exercise
 My estimate is that this exercise will take at least 5-10 times
more effort — development and testing — than a normal
LotusScript business function

17
Decoding Signatures
Bold indicates a different memory structure for the same type across platforms. In other words, “Watch out!”

18
• Introduction
• Architectures
• Pros and cons
• Wrap-up

19
Calling a Simple C API Function
• Let’s get our feet wet with some simple API
 No complex sequence of calls handling a shared memory
resource
 A single call with simple datatypes
 A call that will not result in client memory corruption should we
get it wrong
 Hopefully
• Let’s call it from Windows and ignore other platforms
 A function that tells you the network latency, in milliseconds,
between the current Notes instance and a target server
 NSFGetServerLatency

20
NSFGetServerLatency() — API Reference
• We shall call NSFGetServerLatency()
 This returns the network latency time described in milliseconds
for a call to a remote server
• Useful to decide which server is closest in terms of
network response
• Its signature from the C API reference is:
STATUS LNPUBLIC NSFGetServerLatency(
char far *ServerName,
DWORD Timeout,
DWORD far *retClientToServerMS,
DWORD far *retServerToClientMS,
WORD far *ServerVersion);

21
NSFGetServerLatency() — API Reference (cont.)
• From Lotus C API Notes/Domino 7.0 Reference:
Input Parameters
ServerName — Null-terminated string containing the name of the
server to query.
Timeout — Number of milliseconds to wait for a reply from the server.
A timeout of 0 indicates that the default timeout value is to be used.
Output Parameters
(routine) — Return status from this call:
NOERROR — Success
retClientToServerMS — Optional — If not NULL, the number of
milliseconds required to send the request to the server is stored at this
address.
retServerToClientMS — Optional — If not NULL, the number of
milliseconds required for the reply to return from the server is stored at
this address.
ServerVersion — Optional — If not NULL, the server version (the
Domino build number for the server) is stored at this address.

22
Simple C API Calling
' This is a constant for our windows-based
' Library file:
Const LIB_W32 = "nnotes.dll"
' Declare our function for windows
Declare Function W32_NSFGetServerLatency _
Lib LIB_W32 Alias {NSFGetServerLatency} (_
Byval ServerName As Lmbcs String, _
Byval Timeout As Long, _
retClientToServerMS As Long, _
retServerToClientMS As Long, _
ServerVersion As Integer) As Integer

23
Simple C API Calling: Execution
' A function to get network latency time...
Public Function getServerLatency _
(strServer As String) As Long
Dim nnServer As New NotesName(strServer)
Dim ToServer As Long, fromServer As Long
Dim ver As Integer
Dim timeout As Long
timeout = 1000 ' 1000ms == 1 second
Call W32_NSFGetServerLatency(nnServer.Canonical,_
timeout, toServer, fromServer, ver)
' Return both directional latencies added together
getServerLatency = fromServer + ToServer
End Function

24
Simple C API Calling: Execution (cont.)
Sub initialise
Print “Calling function”
Print “Latency is: “ + _
cstr(getServerLatency(“domino-90.hadsl.com/
HADSL/US”))
Print “Finished calling”
end sub

25
Database Handle Class — Introduction
Demo of
GetServerLatency

26
• Running the agent “Example1” in the database produces
the following runtime output:
• Now, this is not production code! It requires:
 Error handling
 Multi-platform support
Simple C API Calling: The Results

27
What Can’t You Call?
• Callback routines
 Some Notes C API functions require you to specify mandatory
callback routines — other pieces of C API that will get called by
the target C API routine
 LotusScript does not (and, IMHO, never will) support this
 This rules out:
 Extension Manager routines
 Menu Addin routines
 In terms of callback routines that allow you to specify optional
callbacks (progress status indicators, etc.), you can pass in
NULL (or ZERO), and the callback function will be ignored

28
• Introduction
• Architectures
• Pros and cons
• Wrap-up

29
API Handles
• A handle is a numeric reference to a structure in memory
that the C API interface has created
 For example, a handle to a Notes database
• You do not deal with the memory structure itself; you deal
with the handle to the memory structure
 Example: NSFDbOpen() creates a new memory structure and
gives you back the handle to that
 You perform some work using NSFDInfoGet()
 You close the database using NSFDbClose()

30
Some Rules on Handles
• There are different types of handles:
 Document handle, database handle, etc.
 Do not mix these handles up!
 Doing so will crash the session/client/server
• Always properly close your handles:
 You have to properly trap all code branches
 You have to keep track of the handle until you specifically
de-allocate it
 Not doing so will crash the session/client/server
 It may not crash immediately
 It may crash when the session, client, or server closes
• You cannot change the value of the handle:
 Doing so will crash the session/client/server

31
Coding Around Handles
• Track handles with classes
 Perform the “open” of the handle on the class constructor
 Perform the “close” of the handle on the class destructor
 This means that no matter what happens, the handle
operation will be properly closed — even if this is not
specifically coded in your LotusScript
 All the code specific to this handle operation is embedded in
the class
 And can include multi-platform code
 All the consumer sees is an operation with this specific class

32
Handle Summary
• If you get a handle, you have to de-allocate it
• Only use handle data you know is valid
 If a handle == NULLHANDLE (or ZERO), then its not a valid
handle
• Bonus
 NotesDocument.handle returns the current handle
 You can easily use LotusScript to:
 Find a document
 Use direct calls to update information that the object model
does not support (at the moment)
 e.g., writing Notes replica items

33
• Introduction
• Architectures
• Pros and cons
• Wrap-up

34
Custom Classes Can Help Us Considerably
• We can construct classes which “hide” the platform
differences
• Each platform will have its own set of classes
• Each code sequence will be small, easily maintainable
• We can reuse common code
• We can use the custom class constructor and destructor
to ensure that resources are properly returned

35
Custom Classes: Architecture
Base Class
Object
Handler
Platform
Specific
Object
Handlers
Platform
Specific
Object
Handlers
Platform
Specific
Object
Handlers
Factory
User Code
Dim F As New APIFactoryClass()
Dim dbH As Variant
Set dbH = F.getDbHandler()
…
Hidden Code

36
Custom Classes
• Our base class carries infrastructure code
 Logging, string handling, etc.
• Our object base class:
 Defines the functions that we will use
 Defines the business logic
• Our platform-specific classes:
 Override platform-specific functions with that platform’s
implementation
• Our factory class:
 Helps the user of the code find the correct platform-specific
class to use

37
Is This Over-Engineered?
• At first sight, this looks complex
• However, it does allow us to:
 Keep platform-specific code in well-defined classes
 Leverage class constructor/destructor calls to ensure handles
are properly managed
 Perform a simple “Copy+Paste” of the object class to port to a
new platform
 Keep code sequences short and clear
 Hide the implementation of the code from the consumer of
the code

38
Demo of
IDRefresh

39
• Introduction
• Architectures
• Pros and cons
• Wrap-up

40
Defining Complex C API
• Complex C API is where:
 More than one function call is required to perform a task
 And/or
 A HANDLE of some description is needed to reference a
data object

41
Complex C API
• Where more than one function call is required to perform
a function it is recommended that:
 You use defensive coding techniques to understand and make
“safe” every single coding branch possible
 Any handle information used during this sequence is kept safe
and its de-allocation specifically catered to
 You use classes to ensure proper construction and destruction
of handle information

42
Our Complex Example
• Is passed through a server and database path
• Opens and gets the DBHANDLE for that database
• Extracts the replication flags into a memory structure
• Checks to see if the “Disable Replication” flag is on
 If it is, switches that flag off
 Saves the replication flags
• Finally, closes the DBHANDLE

43
We Use Custom Classes To …
• Ensure that the DBHANDLE is always properly returned
• Insulate the consumer of the code from the platform
differences
• Contain all the platform-specific code in separate classes
• Keep it simple!

44
Demo of
DbHandleManager

45
• Introduction
• Architectures
• Pros and cons
• Wrap-up

46
Know Your Battleground
• LotusScript coding is:
 Fairly straightforward
 Supported
 Platform-independent
• Stepping outside of this comfort zone is going to be hard
 Take far more time in development and testing
 Push development resources to the limit
 Only do this if you have an absolute business need

47
LSX vs. Notes C API
• You need to establish, based on your requirements,
which is the best fit:
Feature LSX LotusScript calling Notes C API
Deployment Requires code deployment No deployment required
Multi-platform Recompile LSX for each
platform
Same code in library
C API integration Very good integration —
supports callbacks, etc.
Basic integration
Code difficulty Medium Hard
Stability Extremely stable Stable

48
• Introduction
• Architectures
• Pros and cons
• Wrap-up

49
Resources
• Normunds Kalnberzin, LotusScript to Lotus C API
Programming Guide (November, 2003).
 The ultimate reference
 www.ls2capi.com
• Tools for Lotus Notes and Domino
 Lotus Notes API tips
 www.nsftools.com/tips/APITips.htm
• Working application with several Notes C API calls
 Included on the conference CD

50
7 Key Points to Take Home
• Calling Notes C API is difficult
 Only use it if absolutely required
• It has to be tested on all platforms
• It can easily take out a client or server process
• Use defensive coding!
• Use classes to hide platform differences
• It’s the next stage beyond the well-regulated
LotusScript sandbox
• It gives you all possible Notes capability

51
Your Turn!
How to contact me:
Bill Buchan
Bill@hadsl.com

Dev buchan leveraging the notes c api

More Related Content

What's hot (20)

Viewers also liked (11)

Similar to Dev buchan leveraging the notes c api (20)

More from Bill Buchan (20)

Recently uploaded (20)

Dev buchan leveraging the notes c api