 Home |
 Content |
| Purchase |
| Ready-to-use samples |
| Online resources |
| Forum |
| Links |
| Happy readers |
Anonymous
Technotes & goodies
| Installation of Ls2capi wrappers for iSeries |
| Ls2Capi on iSeries |
| R5 Database Manager |
Ls2Capi on iSeries
Calling of C API from LotusScript on iSeries does not work as smoothly as on the rest of platforms.
There are three major showstoppers:
1. Pointers are 16-bytes long. No LotusScript datatype can be used to receive return value by OSLockObject. A lot of useful functionality can not be used.
2. In order to call C code from LotusScript and pass parameters by value, C code must use _System linking convention. This is not the case with Domino. As a result only functions passing parameters by reference (or ByVal As String that also passes a pointer) work fine.
3. Data alignment in LotusScript is different from alignment on other platforms
| Data type | Space occupied / alignment in LotusScript | |
| iSeries | Other platforms | |
| Long | 16 | 4 |
| Integer | 8 | 2 |
| Fixed string | 8 per char | 2 bytes per char |
| String | 16 | 4 |
| Double | 32 | 8 |
| Variant | 64 | 16 |
| Currency | 32 | 8 |
| Object | 16 | 4 |
In order to solve these issues I have generated wrappers that use correct linking convention (see the bottom of this document for a link to Download and installation instructions). All the functions names in wrappers compared to regular Notes C API function names are prefixed with "w", e.g. wNSFDbOpen. w-functions allow to call Notes API function that need to pass parameters byVal.
The wrappers contain also a second group of functions — prefixed with "x" or x-functions allow to workaround the long pointer limitations. They also facilitate passing structures byVal that is fairly kludgy task on other platforms. x-functions when they pass pointers or structures always pass them by reference.
The list of x-functions. First group has been modified exactly as mentioned before — they pass pointers and structures only by reference. Mind you — corresponding w-functions are also available for the functions in the list. If you know what you do they might sometimes also be useful.
xNSFNoteFindMatchingItem
xNSFVerifyFileObjSignature
xNSFNoteDetachFile
xNSFNoteExtractFileExt
xNSFNoteExtractFile
xNSFItemConvertValueToText
xNSFItemGetModifiedTimeByBLOCKID
xNSFItemInfoNext
xNSFItemCopy
xNSFItemRealloc
xNSFItemDeleteByBLOCKID
xNSFItemAppendObject
xNSFItemAppendByBLOCKID
Following functions have been changed to return parameter as argument instead of function value:
void xOSLockObject (HANDLE h, void * ptr)
xOSMemoryLock (MEMORYHANDLE h, void * ptr)
Also few x-functions have been added to facilitate pointer handling:
void xOSPtrCpy (char * *ptrSource, char * *ptrTarget) /* you can not assign variable containing pointer */
void xOSPtrAdd (char * *ptr, DWORD *offset) /* same goes for arithmetic operations */
void xOSLockBlock (BLOCKID * block, char * *returnPtr)
Version 0.7 adds following functions:
(nls.h)
xNLS_unload_charset
xNLS_find_substr
xNLS_translate
xNLS_find
xNLS_get
xNLS_goto_next
xNLS_goto_prev
xNLS_goto_next_word_end
xNLS_goto_next_word_start
xNLS_goto_next_break
xNLS_goto_prev_word_end
xNLS_goto_prev_word_start
xNLS_isalpha
xNLS_isalnum
xNLS_isarith
xNLS_iscntrl
xNLS_isdigit
xNLS_islower
xNLS_ispunct
xNLS_isspace
xNLS_isupper
xNLS_isleadbyte
xNLS_string_chars
xNLS_put
xNLS_put_term
(osmisc.h)
xOSTranslateIn
xOSTranslateOut
xOSTranslateInOut
xOSGetLMBCSCLS
xOSGetNativeCLS
As an example the function xNSFItemDeleteByBLOCKID has been modified to enable pass structure (BLOCKID) by reference. It has a signature:
STATUS LNPUBLIC xNSFItemDeleteByBLOCKID (NOTEHANDLE hNote, BLOCKID *bItem)
It should be declared in LotusScript:
Declare Function OS400_NSFItemDeleteByBLOCKID Lib LIB_OS400 Alias {xNSFItemDeleteByBLOCKID} (byVal hNote as Long, bItem as BLOCKID) as Integer
Function xNSFItemInfoNext illustrates another type of modification. It has been modified to enable passing pointer by reference. It has C signature:
NLS_STATUS LNPUBLIC CALLING_MODIFIER xNLS_unload_charset (NLS_PINFO * ppInfo)
Declare Function OS400_NLS Lib LIB_OS400 Alias {xNLS} (ppInfo As Long) as Integer
Use of wrappers neither are supported nor imply any guaranty of usability. But they work — as far as tested. In case you have any problems with installation or use, please let me know.
For installation instructions see Installation of Ls2capi wrappers for iSeries
This website contains material that complements "LotusScript to Lotus C API Programming Guide". Some parts of it including posting of comments and discussion items are available only to authenticated readers of the book. Enter your username and password to authenticate.
You should have cookies and JavaScript enabled for the authentication to work..
You should have received your username and password by email to the address you provided during the purchase of the book. In case you failed to receive it or you have any problems loging in let me know about it.