ALines Function

Request Example View Source

Parameters

ArrayName (Optional)

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

cExpression (Optional)

Type: Usual
Specifies the character expression or memo field containing the lines to copy to the array. All character expressions are case-sensitive. 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 (Optional)

Type: Usual
In previous versions of X#, nFlags was the lTrim option. The lTrim option corresponds to a value of 1 for nFlag. Previous code will run identically in X# 9.0. The table below describes the values for nFlags.

cParseChar (Optional)

Type: Usual
Specifies one or more character strings that terminate the elements in cExpression.

cParseChar2 (Optional)

Type: Usual
Specifies one or more character strings that terminate the elements in cExpression.

Return Value

Type: Usual
Numeric. ALines( ) returns the number of rows in the array, or, identically, the number of lines in the character expression or memo field.

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

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

When cParseChar is specified, the line breaks when cParseChar is found, and the next line continues with the character following cParseChar.
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.
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.
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. X# 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: - OR -

 1Close Databases
 2Clear
 3Open Database (HOME(2) + "data\testdata")
 4Use employee  // Open Employee table
 5? ALines(aMyArray, employee.notes)            // Displays 1
 6? ALines(aMyArray, employee.notes, CHR(13))   // Displays 1
 7? ALines(aMyArray, employee.notes, " ")       // Displays 75
 8? ALines(aMyArray, employee.notes, ".")       // Displays 7
 9? ALines(aMyArray, employee.notes, ",")       // Displays 4
10? ALines(aMyArray, employee.notes, ".", ",")  // Displays 10
11? ALines(aMyArray, employee.notes, 8, "m")    // Displays 14
12? ALines(aMyArray, employee.notes, "m")       // Displays 11
13? ALines(aMyArray, employee.notes, "M")       // Displays 4