4.5.216. besRETURN_POINTER(X)

[<<<] [>>>]

Use this macro to return a pointer. The argument of the macro should be the pointer to return. The BASIC program will see this value as a string of four (32 bit machines) or eight (64bit machines) characters. The BASIC program should not alter the value but pass it back to the module wherever the program needs. In other words the program should treat the value as an abstract handle and not try to manipulate it.

The macro allocates the return string, copies the pointer into the string and returns from the function using the macro with no error (COMMAND_ERROR_SUCCESS).

If the return value can not be allocated the macro returns with COMMAND_ERROR_MEMORY_LOW.

If the pointer is NULL the function will return the BASIC value undef. This way you can not pass a NULL pointer back to the BASIC program stored as four (or eight) zero characters in a string. On the other hand this is usually not what you really want and the BASIC program can check undefindeness of the value. When undef is passed back to the module the argument handling functions convert it back to NULL.

[<<<] [>>>]