Nul-Terminated Strings

A Nul-Terminated string is called a STRINGZ with ANSI characters, or WSTRINGZ with WIDE, Unicode characters. When declared with ANSI characters, they are commonly known as ASCIIZ strings. You can think of NulTerm strings as fixed-length strings where the last character is always a nul (binary zero) terminator. This allows the data to be variable length, but only up to a predefined maximum. Any attempt to assign a string longer than the defined length will result in truncation.

If you assign a string that is shorter than the defined length, the string will not be padded on the right. The contents of the remainder of the string buffer are undetermined. Because a NulTerm string requires a NUL terminator, they are usually defined with a length of at least two characters.

You declare STRINGZ variables using the STRINGZ or WSTRINGZ keywords with the DIM statement. For example:

DIM MyStr1 AS STRINGZ * 40

DIM MyStr2 AS WSTRINGZ * 40

This creates a 40 byte STRINGZ (ASCIIZ) string named MyStr1, and an 80 byte WSTRINGZ string named MyStr2. The declared size always refers to the number of characters, not the number of bytes. The number of characters you can actually store is always one less than the defined length of the string. One character position is used to hold the NUL terminator. Therefore, MyStr1 and MyStr2 can each hold up to 39 characters.

When assigning string data to a NulTerm string, the assignment will stop if an embedded CHR$(0) (nul) is encountered. For example:

DIM a AS STRING

DIM b AS STRINGZ * 10

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

b = a ' b will contain "ABC"

Like Fixed-Length strings, the length of NulTerm strings is determined at compile-time, not run-time. In addition, unlike dynamic strings, NulTerm strings do not use handles. When you pass a NulTerm string to a procedure as a parameter, you are actually passing a pointer to the string data.

The address of the contents of a NulTerm string can always be obtained with the VARPTR function. LOCAL NulTerm string memory is released when the enclosing procedure ends. Subsequent calls to the procedure will result in new storage locations for them. However, the location of a LOCAL STRINGZ or WSTRINGZ does not move until the string memory is released when the procedure terminates.

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

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