| **Navigation:**  [[introduction.htm|Language Reference]] > 3 - Variable Declarations > Data Types >====== PSTRING (embedded length-byte string) ====== | [[cstring  fixed length null terminated string .htm|{{btn_prev_n.gif|Previous page}}]][[introduction.htm|{{btn_home_n.gif|Return to chapter overview}}]][[string  fixed length string .htm|{{btn_next_n.gif|Next page}}]] |
|  ||

|  |  | | | //length// | | |  |
| label | **PSTRING** | **( **| | //string constant// | | **)** | [,**DIM( )**] [,**OVER( )**] [,**NAME( )**] [,**EXTERNAL**] [,**DLL**] |
|  |  | | | //picture// | | | [,**STATIC**] [,**THREAD**] [,**AUTO**] [,**PRIVATE**] [,**PROTECTED**] |

{{blk2blue.jpg|blk2blue.jpg}}

| **PSTRING** | A character string. |

**Format: A fixed number of bytes.**

**Size:  2 to 256 bytes.**

| //length// | A numeric constant that defines the number of bytes in the string. This must include the length-byte. |
| //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 length-byte. |
| //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 plus the first position length byte. String variables are not initialized unless given a //string constant//. |
| **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. |

**PSTRING** declares a character string with a leading length byte included in the number of bytes declared for the string. The memory assigned to the PSTRING is initialized to a zero length string unless the AUTO attribute is present. PSTRING matches the string data type used by the Pascal language and the "LSTRING" data type of the Btrieve Record Manager. Storage and memory requirements are fixed-length, however, the leading length byte will contain the number of characters actually stored. PSTRING is internally converted to a STRING intermediate value for string operations during program execution. PSTRING should be used to achieve compatibility with outside files or procedures.

In addition to its explicit declaration, all PSTRINGs are implicitly declared as a PSTRING(1),DIM(//length of string//). This allows each character in the PSTRING to be addressed as an array element. If the PSTRING 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 PSTRING 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 PSTRING, 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 PSTRING. 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 PSTRING must have a leading length byte, the programmer must be responsible for ensuring that its value is always correct if the field is only accessed through its array elements or as a "slice" (not as a whole entity). The PSTRING's length byte is addressed as element zero (0) of the array (BLOB and PSTRING are the only exceptions in Clarion where an array has a zero element). Therefore, the valid range of array indexes for a PSTRING(30) would be 0 to 29. Also, a PSTRING can have 'junk' stored outside the active portion of the string. Because of this they do not work well inside GROUPs.

**Example:**

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

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

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

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

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

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

**Record       RECORD**

**NameField     PSTRING(21),NAME('LstringField')!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[0] = '<;6>'             ! and handle length byte**

** Name[5:6] = 'ie'            ! and change a "slice" -- the 5th and 6th 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**