See Also: Declaring Variables, Variable Declaration Commands, Struct, Char
Declares one or more UChar (one byte unsigned integer) variables. Arrays of UChar can be used to read and write entire files.
To declare UChar variables
UChar {identifier} [… {identifier}]
Where
Where {identifier} is the name of a new UChar variable.
{identifier} may be between 1 and 4096 characters in length, must start with a letter, and may not contain spaces. Recommended characters are 0-9, a-z, A-Z and _ (underscore).
To declare array variables of type UChar
UChar{dimension-list} {identifier} […{identifier}]
Where
{dimension-list} is a list of one or more array dimensions for the array. A dimension list is declared using square brackets []. One pair of brackets is used to declare each dimension. If the array is static, then you must specify the static size of each dimension between each pair of brackets. i.e. [{size}]. For more information about declaring arrays refer to Array Variable Assignments.
{identifier} may be between 1 and 4096 characters in length, must start with a letter, and may not contain spaces. Recommended characters are 0-9, a-z, A-Z and _ (underscore).
The UChar command declares 1 byte unsigned integer variables in the range 0 to 255.
Multiple variables may be declared on one command line, with their names separated from each other by spaces.
UChar arrays are useful for storing binary data and reading and writing from and to whole files.
Procedure DoTest
UChar ucMyVar
Move 1 To ucMyVar
End_Procedure
This example declares a UChar variable named ucMyVar and initializes its value to 1.
UChar[] ucBoatLength
This example declares 1 dynamic array variable, named ucBoatLength, containing an undefined number of elements of type UChar.
UChar[5] ucBoatLength
This example declares 1 static array variable, named ucBoatLength, containing 5 of elements of type UChar.
UChar[][3] ucBoatLength
This example creates a two-dimensional dynamic array variable named ucBoatLength, containing an undefined number of elements of type UChar. Conceptually, this represents a rectangular array with an undefined number of rows, each of 3 columns.
You can declare dynamic multi-dimensional arrays where all dimensions are dynamic; these are called jagged arrays.
An unsigned char (UChar) is a byte. An array of UChar (UChar[]) is therefore an array of bytes. In applications, arrays of bytes can be used to represent (single byte) character data or binary data.
In DataFlex, Strings are normally used to represent character data and Strings or a memory heap is used to represent binary data. With strings used for binary data, you have to be very careful about embedded nulls. With memory, you have to allocate and deallocate the memory yourself and then work with low level memory commands.
An alternate to these approaches is to use UChar arrays. You can do so using the following:
Use Get_Field_Value and Set_Field_Value to get and put UChar arrays. This lets you use UChar arrays when working with variable length table column data (DF_TEXT and DF_BINARY).
Use Write and Read_Block to read and write UChar arrays. This lets you use UChar arrays when reading and writing sequential files.
Numerous array functions make it easier for strings and UChar arrays to interact: StringToUCharArray, UCharArrayToString, AppendArray, CopyArray, RemoveFromArray, InsertInArray, ResizeArray, SearchArray and SizeOfArray.
This should greatly reduce the need to use memory for these tasks. However, interaction between a memory heap and a UChar array is easily handled by using AddressOf() with a UChar array variable (e.g., Move (AddressOf(MyUCharVar)) to pValue). This will point to the first byte of the UChar array. The length of that array is, of course, SizeOfArray().
It should also be noted that UChar array variables can be stored as properties with no size limitation or concern for embedded zeros.
The advantages of this are:
Makes it possible to read and write data large data without worrying about a maximum string size.
Lets you read/write binary data without having to be careful about embedded zeros.
Is superior to reading and writing to memory (a private interface we use) because you don't have to manage the memory yourself.
With variable length data, DF_TEXT and DF_BINARY, Get_Field_Value only returns the actual length of the data and not the maximum allowed. Upon return, the length of the actual data is the array size (SizeOfArray()). When used with fixed length data (DF_ASCII), the array is returned with the data padded with spaces.
With variable length data, DF_TEXT and DF_BINARY, Set_Field_Value determines the length of the actual data to be written by looking at the array size (SizeOfArray()).
UChar arrays are easily handled in the runtime. They can be stored in variables and in properties. Memory is allocated and deallocated automatically. You can use all of the built in array functions with these.
The use of global variables is discouraged for numerous reasons.