Passing strings

PowerBuilder assumes all string arguments and returned values use Unicode encoding. If a function uses strings with ANSI encoding, you need to add an ALIAS FOR clause to the function declaration and add a semicolon followed by the ansi keyword. For example:

FUNCTION string NAME(string CODE) 	LIBRARY "LibName.DLL" ALIAS FOR "NAME;ansi"

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 PowerBuilder is not affected.

When you pass a string to an external function, either by value or by reference, PowerBuilder passes a pointer to the string. If you pass by value, any changes the function makes to the string are not accessible to PowerBuilder. If you pass by reference, they are.

The following statement declares the external C function NAME2 in PowerBuilder. 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 PowerBuilder. For example, Strcpy(CODE,STUMP) would change the contents of CODE to STUMP and change the variable in the calling PowerBuilder 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.