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

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

{{blk2blue.jpg|blk2blue.jpg}}

| **USTRING** | A Unicode character string. |

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

**Size:   ****4MB at design time. Can be extended using ****[[new  allocate heap memory .htm|NEW]] at runtime.**

| //length// | A numeric constant that defines the maximum number of characters in the string. This must include the terminating null character. |
| //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 character. To define a Unicode string literal you must use the U specifier to tell the compiler that the static string is Unicode text (see details below). |
| //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 terminating character. Ustring 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. |

**USTRING** declares a Unicode character string terminated by a null character (ASCII zero). The length parameter declares the number of characters (minus 1 for the for the null character) that the USTRING can contain.  The memory allocated is double the declared size (2 bytes per character). The memory assigned to the USTRING is initialized to a zero length string unless the AUTO attribute is present.

A USTRING can contain both Unicode and ANSI characters. To define a Unicode string literal you must use the U specifier to tell the compiler that the static string is Unicode text. The specifier can be upper U or lower case  u and must be placed immediately before the apostrophe. For example:

UST USTRING(**U**'Ω')   ! define a Unicode string literal

or

UST USTRING(**u**'Ω')          ! define a Unicode string literal

You can address multiple characters within a USTRING 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:

USTR[1] = 'A'  <;----- Error, results in an invalid string

** Currently Unicode strings are not supported for the EVALUATE statement, and for the MATCH and STRPOS built-in functions.

**Example:**

**Name      USTRING(21)                         !Declare 21 character field,20 are available for data (42 bytes of memory)**

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

**Contact   USTRING(21),DIM(4)                  !4 dimensions of 21 bytes, each can have 20 characters**

**Company   USTRING('SoftVelocity')                   !13 character USTRING - 12 characters of data**

**Phone     USTRING(@P(###)###-####P)           !14 character USTRING - 13 characters of data**

**L         LONG**

**S         LONG**

**MYUSTR    USTRING(20)**

** CODE**

**SYSTEM {PROP:Codepage} = 1253 !Greece**

**     SYSTEM {PROP:Locale} = 1032   !Greece**

**     L = LEN(MYUSTR)   ! L equals 0**

**S = SIZE(MYUSTR)  ! S equals 40**

**MYUSTR =  u'Ά Ώ'  ! assign 3 Unicode characters using the lowercase u modifier**

**L = LEN(MYUSTR)   ! L equals 3**

**S = SIZE(MYUSTR)  ! S equals 40 (20 * 2)**

**See also:**

[[chr  return character from ascii .htm|CHR]]

[[val  return ascii value .htm|VAL]]