CSTRING (fixed-length null terminated string)

Top  Previous  Next

 

 

 

|

length

|

 

label

CSTRING

(|

string constant

|)

[,DIM( )] [,OVER( )] [,NAME( )] [,EXTERNAL] [,DLL]

 

 

|

picture

|

[,STATIC] [,THREAD] [,AUTO] [,PRIVATE] [,PROTECTED]

CSTRING

A character string.

 

Format: A fixed number of bytes.

Size:   4MB at design time. Can be extended using NEW at runtime.

 

length

A numeric constant that defines the number of bytes of storage the string will use. This must include a position for the terminating null character. String variables are not initialized unless given a string constant.

string constant

A string constant containing the initial value of the string. The length of the string is set to the length of the string constant plus the terminating null character.

picture

The picture token used to format the values assigned to the string. The length of the string is the number of bytes needed to contain the formatted string and the terminating null character.

DIM

Dimension the variable as an array.

OVER

Share a memory location with another variable.

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.

 

CSTRING declares a character string terminated by a null character (ASCII zero). The memory assigned to the CSTRING is initialized to a zero length string unless the AUTO attribute is present.

CSTRING matches the string data type used in the "C" language and the "ZSTRING" data type of the Btrieve Record Manager. Storage and memory requirements are fixed-length, however the terminating null character is placed at the end of the data entered. CSTRING should be used to achieve compatibility with outside files or procedures.

In addition to its explicit declaration, all CSTRINGs are implicitly declared as a STRING(1),DIM(length of string). This allows each character in the CSTRING to be addressed as an array element. If the CSTRING also has a DIM attribute, this implicit array declaration is the last (optional) dimension of the array (to the right of the explicit dimensions).

You may also directly address multiple characters within a CSTRING using the "string slicing" technique. This technique performs similar action to the SUB function, but is much more flexible and efficient (but does no bounds checking). It is more flexible because a "string slice" may be used on both the destination and source sides of an assignment statement and the SUB function can only be used as the source. It is more efficient because it takes less memory than individual character assignments or the SUB function.

To take a "slice" of the CSTRING, 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 CSTRING. 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 (to prevent PREfix confusion).

Since a CSTRING must be null-terminated, the programmer must be responsible for ensuring that an ASCII zero is placed at the end of the data if the field is only accessed through its array elements or as a "slice" (not as a whole entity). Also, a CSTRING can have "junk" stored after the null terminator. Because of this they do not work well inside GROUPs.

Example:

Name       CSTRING(21)                         !Declare 21 byte field - 20 bytes data

OtherName  CSTRING(21),OVER(Name)              !Declare field over name field

Contact    CSTRING(21),DIM(4)                  !Array 21 byte fields - 80 bytes data

Company    CSTRING('SoftVelocity Corporation') !21 byte string - 20 bytes data

Phone      CSTRING(@P(###)###-####P)           !Declare 14 bytes - 13 bytes data

ExampleFile FILE,DRIVER('Btrieve')             !Declare a file

Record       RECORD

NameField     CSTRING(21),NAME('ZstringField') !Declare with external name

            END

           END

CODE

Name = 'Tammi'               !Assign a value

Name[5] = 'y'                ! then change fifth letter

Name[6] = 's'                ! then add a letter

Name[7] = '<0>'              ! and handle null terminator

Name[5:6] = 'ie'             ! and change a "slice"

                             !  -- the fifth and sixth letters

Contact[1] = 'First'         !Assign value to first element

Contact[1,2] = 'u'           !Change first element 2nd character

Contact[1,2:3] = Name[5:6]   !Assign slice to slice

 

!Example that extends the size of the CSTRING

CS  &CSTRING

StringSize            LONG

 

CODE

StringSize = 0FFFFFFh     !16MB

CS &= NEW CSTRING(stringSize)