Русский   Home

Strings

Strings in JScript and VBScript are of the BSTR type. These are Unicode strings, i.e. the code of each character takes 2 bytes. The last character is followed by a terminator (two zero bytes), and the first character is preceded by a 4-byte number that contains the length of the string in bytes (excluding zero bytes at the end of the string). A script string variable holds a pointer to such a string, which is the address of the string's first character (i.e. the bytes that contain the string length remain "behind-the-scenes").

A string can be passed to a function in three ways:

• An input string: w, s, z. Strings passed as s or z are copied and converted into the relevant encoding. The API function receives a pointer to such a copy. As soon as the function returns, the memory used for the copy is released. In the case of w the function receives a pointer to the original (Unicode) string.
• An output string: W, S, Z. Here with all three types you pass a pointer to the original location of the string. S and Z strings are previously converted into the relevant encoding but without copying. When the function returns, the contents of S and Z strings are converted back into Unicode and their length is measured. W strings only have their length measured. The length (in bytes) is recorded in front of the string. The last operation is needed to avoid glitches when, for example, this and other strings will be concatenated further in the script. Since the output string, like all output parameters, is intended to be written to by the called function, make sure its length is sufficient.
• A pointer: p. This is the simplest way. Here you pass a pointer to the original string, without conversion. After the function returns, no conversion or length correction is made. So if the function has written something to this string, that data will remain there unchanged. This might look the same as w, but there is a difference. Parameters declared as p accept not only string variables but also numeric ones.

There are two ways to return a string:

• p means we get a numeric variable holding a pointer to the string returned by the API function.
• w, s and z mean we get a string variable holding a pointer to a copy of the string returned by the API function. Strings returned as s and z are copied with conversion. The original strings are not freed because DWX has no idea how memory for the string was allocated. If you are concerned about memory leak caused by that, use the p type for the return value, read the string to a variable with StrGet and then free the original string in the way recommended by the function's documentation.

API functions that take string arguments typically exist in two variants — for example, MessageBoxA and MessageBoxW. It appears more reasonable in scripts to use the Unicode versions (those having a 'W' at the end of the name) because this way you avoid conversion to and from Unicode.

Use of strings as memory buffers may or may not be a reliable technique depending on how the scripting engine treats strings internally. So I recommend using MemAlloc instead of Space for that purpose.