ASCIIZ strings

You can think of ASCIIZ strings (or its synonym ASCIZ) as fixed-length strings where the last character is always a nul (CHR$(0) or $NUL) terminator.  Like fixed-length strings, ASCIIZ strings contain character data of fixed length and any attempt to assign a string longer than the defined length will result in truncation.

If you assign a string (a string literal, or a dynamic or fixed-length string variable) to an ASCIIZ string that is shorter than the defined length, the string will not be padded on the right.  Instead, the nul-terminator goes right after the last string character.  The contents of the remainder of the string buffer are undetermined.  Because an ASCIIZ string requires the nul-terminator byte, ASCIIZ strings are usually defined with a length of at least two bytes.

You declare ASCIIZ string variables using the ASCIIZ or ASCIZ keywords with the DIM statement.  For example:

DIM MyStr1 AS ASCIIZ * 40

DIM MyStr2 AS ASCIZ * 40

This creates a 40 byte ASCIIZ string named MyStr.  The number of characters you can store in an ASCIIZ string is always one less than the defined length of the string.  The last character is used to hold the nul-terminator.  Therefore, a 40 byte ASCIIZ string can hold up to 39 characters.  If you need 40 usable bytes, DIM the string to have a 41 byte length.  It is on this basis that ASCIIZ strings should be defined with a length of at least two bytes.

When assigning string data to an ASCIIZ string, the assignment will stop if an embedded $NUL byte is encountered.  For example:

DIM a AS STRING

DIM b AS ASCIIZ * 10

a = CHR$("ABC", 0, "DEF")

b = a  ' B will contain "ABC"

Unlike dynamic strings, the length of ASCIIZ strings is determined at compile-time, not run-time.  In addition, unlike dynamic strings, ASCIIZ strings do not use handles.  When you pass an ASCIIZ string to a routine, you are actually passing a pointer to the string's data.

The address of the contents of an ASCIIZ string can always be obtained with the VARPTR function.  LOCAL ASCIIZ string memory is released when the associated Sub or Function ends.  Subsequent calls to the Sub or Function will result in new storage locations for the ASCIIZ string data; however, the location of a LOCAL fixed-length string does not move until the string memory is released when the Sub/Function terminates.

LOCAL ASCIIZ strings are created on the stack frame, so LOCAL ASCIIZ strings will be limited to the amount of available stack space available.  Typically this is less than 1 MB unless a larger stack frame has been allocated with #STACK metastatement.  If larger ASCIIZ (or fixed-length) strings are required, it is advisable to make them STATIC or GLOBAL since those are not created within the stack frame.

The address of the contents of STATIC and GLOBAL ASCIIZ strings stays constant for the duration of the module.  STATIC and GLOBAL Scalar (non-array) ASCIIZ strings may be up to 16,777,216 bytes each.

 

See Also

Dynamic (Variable-length) strings ($)

FIELD strings

Fixed-length strings

String expressions