Q(uick)BASIC Routine: StringAssign

Quick View

StringAssign

This routine is used in mixed-language programming to transfer a string from BASIC to a non-BASIC routine or from a non-BASIC routine to BASIC. A typical use is to transfer a string from BASIC to a non-BASIC routine, process the string using the non-BASIC routine, and then transfer the modified string back to BASIC

Worth knowing

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

Syntax

StringAssign(sourceaddress&, sourcelength%, destaddress&, destlength%);

Description/Parameter(s)

sourceaddress&	Far address of the start of string data (if the source is a fixed-length string) or Far address of the string descriptor (if the source is a variable-length string).
sourcelength%	String length (if the source is a fixed-length string) or 0 (if the source is a variable-length string).
destaddress&	Far address of the start of string data (if the destination is a fixed-length string) or Far address of the string descriptor (if the destination is a variable-length string).
destlength%	String length (if the destination is a fixed-length string) or 0 (if the destination is a variable-length string).

The preceding syntax is for the C language. However, the order of the arguments in the syntax follows BASIC, Pascal, and FORTRAN calling conventions rather than the C calling convention. (In BASIC, Pascal, and FORTRAN, the arguments are passed in the order in which they appear in the source code. In C, the arguments are passed in the reverse order.)
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 StringAssign routine are usually made from a C, MASM, Pascal, or FORTRAN routine that is going to perform string processing functions on BASIC strings. Seldom, if ever, would you call StringAssign from inside a BASIC program.
StringAssign can be used to transfer both near and far strings. Using StringAssign, you can write mixed-language programs that are near string/far string independent.
MASM, C, Pascal and FORTRAN deal only with fixed-length strings. When programming in these languages you can use StringAssign to create a new BASIC variable-length string and transfer fixed- length string data to it. For example, to transfer a MASM fixed-length string containing the word "Hello" to a BASIC variable-length string, you use this data structure:
- ```
fixedstring      db       "Hello"     ; source of data
```
```
descriptor       dd        0          ; descriptor for destination
```
The second data element, descriptor, is a 4-byte string descriptor initialized to zero. BASIC interprets this to mean that it should create a new variable-length string and associate it with the address labelled descriptor.
To create a new BASIC variable-length string and transfer fixed-length data to it, the StringAssign routine requires four arguments:
- The far address of the fixed-length string in the MASM data segment
- The length of the fixed-length string in the MASM data segment.
- The far address of the string descriptor in the MASM data segment
- 0 (indicating the string in the BASIC data segment will be a variable-length string)
The following MASM code pushes these arguments on the stack and calls stringassign:
- ```
.model
```
```
extrn stringassign: far
```
```
.code
```
```
push         ds                    ; segment of fixed-length string
```
```
lea          ax, fixedstring       ; offset of fixed-length string
```
```
push ax
```
```
mov          ax, 5                 ; length of "Hello"
```
```
push ax
```
```
push         ds                    ; segment of descriptor
```
```
lea          ax, descriptor        ; offset of descriptor
```
```
push ax
```
```
mov          ax, 0                 ; 0 = variable-length string
```
```
push ax
```
```
call stringassign
```
When the call to StringAssign is made, BASIC will fill in the double word descriptor with the correct string descriptor.
For detailed instructions on mixed-language programming with strings, see "Mixed-Language Programming with Far Strings" and "Mixed-Language" Programming with Near Strings" in the Programmer's Guide.

Important

When creating a new variable-length string you must allocate four bytes of static data for a string descriptor as shown above. Allocating the data on the stack will not work.

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