36.12. $getInArea

$getInArea does nothing if s or p is Zero or if $inArea is TRUE of its arguments; otherwise, it copies the characters of s or the dynamic object pointed to by p into area, and returns the STRING descriptor or POINTER referencing the copied data. If s is a STRING, then $getInArea(s,a) is equivalent to:

IF $inArea(s,a) THEN s EL $getToTop(s,a)

If area is omitted, $defaultArea is used. This is useful, for example, when a STRING has been created in static space and the user wishes to have the STRING collected like a normal MAINSAIL STRING, or if the static space is to be reused to allocate a new STRING. For example, if a foreign language procedure returns a STRING with length len at CHARADR ch, $getInArea can be used in conjunction with the PROCEDURE newString as in:

INTEGER len; CHARADR ch; STRING s;
...
# foreignProcedure creates a STRING at ch with length len
foreignProcedure(ch,len);
s := $getInArea(newString(ch,len));

The resulting STRING s is a STRING in MAINSAIL STRING space that is subject to MAINSAIL STRING collection.