DEFINITION - FUNCTION
    mstr& = CreateGPMString&(text$)
                           -- create a zero terminated string in GP Memory

OPERATION
    This function will allocate the required memory (inclusive the zero
    termination byte), then copying the given string to the reserved memory
    and finally write the termination byte.  As the memory allocation may
    fail, this routine may return a zero result.

ARGUMENTS
    text$ -- the string to create in GP memory, it will be copied, so you
             can re-use a given string variable after the call

RESULT
    mstr& -- a pointer to the newly created and zero terminated string in
             the GP memory region.  If there is not enough space remaining,
             return zero

NOTES
    The result of any string creation must be checked, and a viable error
    handling path taken.  Any string creation may fail if memory has been
    filled.

SEE ALSO
    Support Functions

                                                 Back to Function Reference