Passing strings

When you pass a string by reference, LotusScript® passes a 4-byte pointer to a copy of the string in an internal buffer allocated in memory. The C function cannot safely modify the contents of this buffer unless the function is written specifically for LotusScript®.

When a string is passed by value, LotusScript® passes a 4-byte pointer to a null-terminated string (which is what the C function expects) and passes a pointer to the string. The C function can modify this string, but can't lengthen it. Any changes to the string will be reflected in the script variable on return from the function. If you are passing a pointer to something other than a string, then pass the parameter by reference.

You can specify the use of non-platform-native characters as arguments and return values using the LMBCS and Unicode keywords.

Unicode specifies a Unicode string of two-byte characters (words) using the platform-native byte order.
LMBCS specifies a LMBCS optimization group 1 string (multibyte characters).

The following table summarizes the behavior of string arguments to a C function.


Declaration for the string argument in the Declare statement for the C function cF	How the arg is passed when cF is called in one of these forms: cF ( ( arg ) ) cF ( ByVal ( arg ) )	How the arg is passed when cF is called in one of these forms: cF ( arg ) cF ( ByVal arg )
ByVal String	As a 4-byte pointer to a copy of arg's character bytes. If cF changes the bytes, the value of arg does not change. If cF writes past the end of the string, it produces an error.	As a 4-byte pointer to arg's character bytes. If cF changes the bytes, the value of arg changes. If cF writes past the end of the string, it produces an error.
String	As a 4-byte pointer to a copy of the string in the platform-native character set format. If cFchanges the bytes, the value of arg does not change.	As a 4-byte pointer to the string in the platform-native character set format. cF can change the bytes only by dereferencing the existing string and adding a reference to the new one.

Here is a sub that uses the Windows™ C functions GetActiveWindow and SetWindowText to set the title of the active window (the window with focus):

Sub Initialize
   Dim activeWin As Long, winTitle As String, _
    winLength as Long
   winTitle = String(255,0)
   activeWin = GetActiveWin
   winLength = GetWindowText(activeWin, winTitle, 255)
   winTitle = Left(winTitle, winlength)
   Messagebox winTitle, "Window title"
End Sub

To get a window title at run time, use the GetWindowText function. GetWindowText has one input parameter (the window handle, of data type long) and two output parameters: a String variable and a buffer size (the maximum length of the string). The return value is the length of the string that the function places in the String variable.

Declare Function GetWindowText Lib "User32" Alias _
"GetWindowTextA" _
                    (ByVal hWnd As Long, _
                    ByVal lpString As Long _
                    ByVal chMax As Long) As Long

Note: You must be careful when working with a String variable that is given a value by a C function. If the C function assigns a value that is larger than the length already allocated for the string, it overwrites memory not allocated for the string. The results are unpredictable and may cause a crash.

You can make sure that the String variable has space for the string in one of two ways:

Assign it a value that is at least as long as the string to be returned before you pass the variable to the C function.
Declare it as a sufficiently sized fixed-length String variable.

For example, if the maximum length for the string is 255, then you can use the String function to put 255 NULL characters in a variable-length String variable:

winTitle$ = String(255, 0)

Or you can declare winTitle as a fixed-length String variable:

Dim winTitle As String * 255

GetWindowText returns the actual length of the string. If you use a variable-length String variable, you can use the return value to get rid of the padding at the end of the string. For example:

Dim winTitle As String, winLength As Long
winTitle = String(255, 0)
activeWin% = GetActiveWindow()
winTitleLength% = GetWindowText(activeWin%, winTitle$, 255)
winTitle$ = Left(winTitle$, winTitleLength%)

Note: If you use a C function that does not return the length of a string, you can extract the left portion of the string up to the first NULL character as follows:

stringFromC$ = Left(stringFromC$, Instr(stringFromC$,_
    Chr$(0)) -1)