Passing by value The following statement declares the external C function NAME in PocketBuilder. This function expects a string argument to be passed by value:
FUNCTION string NAME(string CODE) LIBRARY "LibName.DLL"
The same statement in C would point to a buffer containing the string:
char * _stdcall NAME(char * CODE)
Since the string is passed by value, the C function can change the contents of its local copy of CODE, but the original variable in PocketBuilder is not affected.
Passing by reference PocketBuilder has access only to its own memory. Therefore, an external function cannot return a pointer to a string. (It cannot return a memory address.)
When you pass a string to an external function, either by value or by reference, PocketBuilder passes a pointer to the string. If you pass by value, any changes the function makes to the string are not accessible to PocketBuilder. If you pass by reference, they are.
The following statement declares the external C function NAME2 in PocketBuilder. This function returns a string and expects a string argument to be passed by reference:
FUNCTION string NAME2(ref string CODE) & LIBRARY "LibName.DLL"
In C, the statement would be the same as when the argument is passed by value, shown above:
char * _stdcall NAME2(char * CODE)
The string argument is passed by reference, and the C function
can change the contents of the argument and the original variable
in PocketBuilder. For example, Strcpy(CODE,STUMP) would
change the contents of CODE to STUMP and
change the variable in the calling PocketBuilder script to the contents
of variable STUMP.
If the function NAME2 in the preceding example takes a user ID and replaces it with the user’s name, the PowerScript string variable CODE must be long enough to hold the returned value. To ensure that this is true, declare the String and then use the Space function to fill the String with blanks equal to the maximum number of characters you expect the function to return.
If the maximum number of characters allowed for a user’s name is 40 and the ID is always five characters, you would fill the string CODE with 35 blanks before calling the external function:
String CODE
CODE = ID + Space(35)
. . .
NAME2(CODE)
For information about the Space function, see the PowerScript Reference.
Passing chars to C functions Char variables passed to external C functions are converted to the C char type before passing. Arrays of char variables are converted to the equivalent C array of char variables.
An array of string variables embedded in a structure produces an embedded array in the C structure. This is different from an embedded string, which results in an embedded pointer to a string in the C structure.
