LotusScript to Lotus C API Programming Guide, LotusScript to Lotus C API Programming Guide

Home

Content

Purchase

Anonymous

LotusScript to Lotus C API Programming Guide

November 2003, softbound, 304 pages, ISBN 9984-19-492-2

...many C API functions may be used from such high-level environments as Visual Basic or LotusScript. In this way we leverage the extensive access to functionality provided by low-level C API and high-level rapid code development in LotusScript.

The risks and awards of this high-level access to low-level functionality is the principal focus of this book.

This book should be mandatory reading for any BP/Corporate Developer who ever thought [about using] or did use external functions. Any of them!
George Chiesa <chiesa @ dotNSF.com> CTO, dotNSF, Inc.

The LotusScript to Lotus C API Programming Guide consists of three parts: the introductory one that sets the scene, the second part that tells us hopefully everything worth knowing about calling of Lotus C API from LotusScript (LS2CAPI); it also includes a quick C course for a LotusScript developer. The third part takes you through many ready-to-use examples.

The principal focus of this book is going to be the following questions:

• how to achieve direct interaction with Notes core,

• what are its limitations,

• what are the traps and workarounds necessary in comparison with programming directly in C,

• what are the platform specific differences and what can we do to make our code run smoothly on different platforms?

In order to be able to benefit most from this book you should have a fair amount of experience in LotusScript programming and a good understanding of Notes internal structures. Still, I hope I have added enough details and samples and positioned the issues so that it will also help relative LotusScript and Notes newcomers.

Warning: if you are here you are probably writting or will write LotusScript code that calls C API. This is really different from writting plain LotusScript. Be extremely careful when using C from LotusScript. Simple as it looks, this approach accesses memory directly, hence bypassing most "foolproof" security nets maintained by LotusScript environment. Some important points:

do not use C API from LotusScript unless you have carefully investigated all other options and workarounds; it takes more knowledge and skills than it seems. Your work will have to be maintained by programmers who may not have your skills. Think one more time if it's worth it.
make sure all your declarations are correct; in case you port your code to different platform (for example Win32 to AIX) the declarations usually are different (and not only the library clause)
check all the possible error conditions, get out gracefully if you encounter error you cannot handle
release all resources you reserve in your code
when you have the code ready, preferably put all C API calls containing code in a script library and hide the design (for example by referencing the source code using %include statements), so that it is not available to an unskilled programmer or power user. Make sure that people responsible for development understand this point and do not allow any casual programmer muck around with it.
most of free samples you will find on Notes.net and other places do not work, are meant as an illustration of a point and work in a limited way and/or without implementing all the necessary error checking (I have provided samples like this myself); even if they do work, in most cases they will not work once you need to move to different operating system
unless you simply want to kick the tyres, read this book; it may be more fun to figure it out all by yourself, but it may get pretty hard and you probably have no time for this. If, after all the warnings, your boss is serious about producing this kind of code, he or she must buy this book and give you the time to get familiar with it.