User Tools

Site Tools


bstring.htm
Navigation:  Language Reference > 3 - Variable Declarations > Data Types >BSTRING (OLE API BSTR) Previous pageReturn to chapter overviewNext page
label BSTRING [,DIM( )], [,NAME( )] [,EXTERNAL] [,DLL]
[,STATIC] [,THREAD] [,AUTO] [,PRIVATE] [,PROTECTED]

blk2blue.jpg

BSTRING The BSTRING is equivalent to the OLE API 's BSTR data type. A BSTRING is a pointer. The pointer points to the first character in the string of Unicode characters (Wide characters of 2 bytes storage).  It consists of a string of Unicode characters, that may contain multiple embedded null characters, and a terminator (a NULL (0x0000) wide character).* BSTRINGs were designed for use in API functions; they are not suitable for usage as USE variables.If insufficient memory exists, returns NULL.

Format: A fixed number of Unicode characters.

Size:   The size is allocated when a value is assigned

 

DIM Dimension the variable as an array.
NAME Specify an alternate, “external” name for the field.
EXTERNAL Specify the variable is defined, and its memory is allocated, in an external library. Not valid within FILE, QUEUE, or GROUP declarations.
DLL Specify the variable is defined in a .DLL. This is required in addition to the EXTERNAL attribute.
STATIC Specify the variable's memory is permanently allocated.
THREAD   Specify memory for the variable is allocated once for each execution thread. Also implicitly adds the STATIC attribute on Procedure Local data.
AUTO Specify the variable has no initial value.
PRIVATE Specify the variable is not visible outside the module containing the CLASS methods. Valid only in a CLASS.
PROTECTED Specify the variable is not visible outside base CLASS and derived CLASS methods. Valid only in a CLASS.

A BSTRING (binary string) is a string data type that is used by COM, Automation, and Interop functions. The BSTRING is equivalent to the OLE API 's BSTR data type. A BSTRING consists of a string of Unicode characters (Wide characters of 2 bytes storage per character).

Example:

MYBSTR BSTRING

L LONG

S LONG

CODE

L = LEN(MYBSTR)   ! L equals 0

S = SIZE(MYBSTR)  ! S equals 0

MYBSTR =  u'Ά Ώ'    ! assign 3 Unicode characters (Alpha space Omega) using the lowercase u modifier

L = LEN(MYBSTR)   ! L equals 3

S = SIZE(MYBSTR)  ! S equals 6 (2 bytes per character)

You may also directly address multiple characters within a BSTRING using the “string slicing” technique. This technique performs similar action to the SUB function, but does no bounds checking so care must be used.

String slicing is not allowed on the left side of assignments. For example: MYBSTR[1] = 'A'  <;—– Error, results in invalid string To take a “slice” of the BSTRING, the beginning and ending character numbers are separated by a colon (:) and placed in the implicit array dimension position within the square brackets ([ ]) of the BSTRING. The position numbers may be integer constants, variables, or expressions. If variables are used, there must be at least one blank space between the variable name and the colon separating the beginning and ending number. see also:**

VARIANT

String Slicing

bstring.htm.txt · Last modified: 2021/04/15 15:57 (external edit)