Copies each line in a character expression or memo field to a corresponding row in an array.

ALINES(ArrayName, cExpression [, nFlags] [, cParseChar [, cParseChar2 [, ...]]])

Parameters

ArrayName

Specifies the name of the array to store the copied lines in the character expression or memo field.

Note
If the array you specify does not exist, Visual FoxPro automatically creates the array. If the array exists but is not large enough to contain all the lines in the memo field, Visual FoxPro automatically increases the size of the array. If the array is larger than necessary, Visual FoxPro truncates the array.

Note
When used with binary values, such as Varbinary and Blob, ALINES( ) creates an array with elements that have Varbinary type.

cExpression

Specifies the character expression or memo field containing the lines to copy to the array. All character expressions are case-sensitive.

Note
If cExpression is the empty string or the null value, an array with a single row is created and the row contains the empty string. You can use double-byte expressions.

[, nFlags]

Note
In previous versions of Visual FoxPro, nFlags was the lTrim option. The lTrim option corresponds to a value of 1 for nFlag. Previous code will run identically in Visual FoxPro 9.0.

The following table describes the values for nFlags.

Bit	Value (additive)	Description
0	1	(Default) Removes leading and trailing spaces from lines, or for Varbinary and Blob values, removes trailing zeroes (0) instead of spaces.
1	2	Include the last element in the array even if the element is empty.
2	4	Do not include empty elements in the array.
3	8	Specifies case-insensitive parsing.
4	16	Include the parsing characters in the array.

[, cParseChar[, c ParseChar2[, ...]]]

Specifies one or more character strings that terminate the elements in cExpression. When cParseChar is specified, the line breaks when cParseChar is found, and the next line continues with the character following cParseChar.

Note
The maximum number of strings permitted in cParseChar is 23.

You can use a line feed (CHR(10)) or carriage return (CHR(13)) character to denote the end of a line. You can also denote the end of the line with either combination of these two characters, for example, (CHR(10) + CHR(13) or CHR(13) + CHR(10)). The default behavior for ALINES( ) is to ignore CHR(13) and CHR(10) when you specify one or more values for cParseChar, unless you also specify the end of line characters.

Note
When cParseChar is omitted for Varbinary or Blob input, ALINES( ) treats the hexadecimal value 0hA (10) as a carriage return and discontinues the line at that location. The value, 0hA, is not saved in the resulting array element and might result in an incorrect binary value. For example, given the binary value, 0hFE0AF2, ALINES( ) creates a two-element array with the values, 0hFE and 0hF2.

Return Value

Remarks

ALINES( ) provides an easy way to parse lines in a character expression or memo field. While you can also use MLINES( ) to parse a character expression or memo field, ALINES( ) is faster and requires less programming. Also, ALINES( ) is not affected by the value of SET MEMOWIDTH.

The first line of the character expression or memo field is copied to the first row of the array, the second line of the character expression or memo field is copied to the second row of the array, and so on.

You must have sufficient memory to copy the lines in a large memo field to an array. Visual FoxPro generates an error message if you lack sufficient memory.

If you want to perform a case-insensitive parse, you can follow one of the following examples:

	Copy Code
? ALINES(aMyArray, UPPER(employee.notes), "R.")

- OR -

	Copy Code
? ALINES(aMyArray, employee.notes, "R.", "r.")

Example

The following example opens the Employee table in the Testdata.dbc sample database. ALINES( ) is used to copy the lines in the Notes memo field to an array named aMyArray, and then the contents of the array is displayed. Various parsing character are specified in each of the ALINES( ) statements.

Copy Code

CLOSE DATABASES CLEAR SET TALK OFF OPEN DATABASE (HOME(2) + "data\testdata") USE employee && Open Employee table ? ALINES(aMyArray, employee.notes) && Displays 1 ? ALINES(aMyArray, employee.notes, CHR(13)) && Displays 1 ? ALINES(aMyArray, employee.notes, " ") && Displays 75 ? ALINES(aMyArray, employee.notes, ".") && Displays 7 ? ALINES(aMyArray, employee.notes, ",") && Displays 4 ? ALINES(aMyArray, employee.notes, ".", ",") && Displays 10 ? ALINES(aMyArray, employee.notes, 8, "m") && Displays 14 ? ALINES(aMyArray, employee.notes, "m") && Displays 11 ? ALINES(aMyArray, employee.notes, "M") && Displays 4

See Also