Q(uick)BASIC Routine: StringRelease

Quick View

StringRelease

This routine is used in mixed-language programming. A non- BASIC routine uses StringRelease to deallocate variable-length strings that have been transferred to BASIC's string space from the non-BASIC routine

Worth knowing

Useful and cross-version information about the programming environments of QBasic and QuickBasic.

Syntax

StringRelease(string-descriptor%);

Description/Parameter(s)

string-descriptor%

The near address of a string descriptor within a non-BASIC routine.

The preceding syntax is for the C language.
For C, MASM, Pascal, and FORTRAN examples, see Chapter 13, "Mixed-Language Programming with Far Strings" in the Programmer's Guide.

Usage Notes

Calls to the StringRelease routine are made from a non-BASIC routine to free up space in BASIC's data area.

Note:

Use the StringRelease routine only to deallocate variable- length strings that have been transferred to BASIC's string space from a non-BASIC routine. Never use it on strings created by BASIC. Doing so will cause unpredictable results.

BASIC automatically deallocates strings allocated by BASIC. However, strings that have been transferred to BASIC from a non-BASIC routine should be deallocated from the non-BASIC routine using the StringRelease routine. (The reason for this is that StringAssign transfers strings but not string descriptors. Without the string descriptor, BASIC cannot deallocate the string; the deallocation has to be done from the non-BASIC routine with StringRelease.)
As an example, assume that you have passed a string from a MASM routine to BASIC's string space using StringAssign. To deallocate this string, assuming a descriptor for the variable-length string exists at offset descriptor, the code is:
- ```
.model
```
```
extrn stringrelease: far
```
```
.code
```
```
lea          ax, descriptor        ; offset of descriptor
```
```
push ax
```
```
call stringrelease
```
For detailed instructions on mixed-language programming with strings, see Chapter 12, "Mixed-Language Programming" and Chapter 13, "Programming with Near Strings" in the Programmer's Guide.

Example

This example uses the StringAssign and StringRelease routines to get a string from an assembly-language program.
Note: To use this program, you must compile the following code and link it with the assembled MASM program (shown below in remarks) and the appropriate runtime library (BCL71ENR.LIB).

DEFINT A-Z
'Declare external MASM procedures.
DECLARE FUNCTION MakeString$
DECLARE SUB ReleaseIt
 
'Get string from MASM and print it.
PRINT MakeString
 
'Have MASM release the variable-length string it created.
CALL ReleaseIt
 
 
'; *********************** MakeString ********************************
'
';This MASM program creates a fixed-length string and
';then assigns it to a BASIC variable-length string.
';It then releases the string after BASIC has used it.
'
'                .model  medium, basic   ;Use same model as BASIC
'
';Declare routines in BASIC library to be used.
'                extrn   StringAssign: far
'                extrn   StringRelease: far
'
'                .data
';Create MASM string and a place for BASIC to create a
';variable-length string descriptor.
'String2         db      "This is a string created by MASM."
'Descriptor      dd      0
'
'                .code
'
'MakeString      proc                    ;Push arguments:
'                push        ds          ;MASM string segment.
'                lea     ax, String2     ;MASM string offset.
'                push        ax
'                mov     ax, 33          ;MASM string length.
'                push        ax
'                push        ds          ;BASIC descriptor segment.
'                lea     ax, Descriptor
'                push        ax          ;BASIC descriptor offset
'                xor     ax, ax          ;variable-length indicator.
'                push        ax
'                call        StringAssign   ;Assign the string.
'
'                lea     ax, descriptor  ;Return with descriptor
'                ret                     ;address in AX.
'MakeString      endp
'
'ReleaseIt           proc                ;Routine to release
'                lea     ax, Descriptor  ;the string.
'                push        ax
'                call        StringRelease
'                ret
'ReleaseIt           endp
'                end