Home > MultiValue Central > Online D3 Reference > BASIC Program > basic.locate

basic.locate

Statement/BASIC Program, Releases: R83, AP, and AP 6.0

Locates element in string expression.

Syntax

locate(string.expression, dynamic.array.expression {, ac.expression{, vc.expression{, start.expression}}}; position.variable {; sequence.expression}) [then | else statement.block] locate string.expression in dynamic.array.expression{ <ac.expression{, vc.expression}>} {,start.expression} {by sequence.expression} setting position.variable [then | else statement.block]

Description

searches for the location of a specific 'string.expression' and returns the location in 'position.variable' of where the string was found or if the string wasn't found, the position that it should be placed.

The elements of 'dynamic.array.expression' may be specified as being in ascending or descending ASCII sequence, and sorted with either right or left justification.

Sequence parameters: (In AP, the single quotes around the sequence parameters are no longer required.)


al Ascending, left-justified.
ar Ascending, right-justified.
dl Descending, left-justified.
dr Descending, right-justified.


If the first character in the 'sequence' expression is anything except 'a' or 'd', or the 'l' or 'r' is not specified, no sort is performed. If the second character is anything except 'r', left justification is assumed. If no 'sequence' parameter is specified, the 'position.variable' position defaults to the end of the string.expression.

The use of the optional 'ac.expression' and 'vc.expression' indicates whether the value returned into 'position.variable' is a value count or a subvalue count. If both are omitted, the value returned into 'position.variable' is an attribute count.

'start.expression' is the first field to search. If not specified, the entire string is searched.

If 'ac.expression' and 'vc.expression' are both specified, 'start.expression' is the first subvalue to search.

If only 'ac.expression' is specified, 'start.expression' is the first value to search.

If 'ac.expression' is not specified, 'start.expression' is the first attribute to search.

The 'string.expression' must match the element exactly in order for the location to be returned.

To use the 'start.expression' while not specifying the 'ac.expression' and 'vc.expression', a '0' (zero) must be substituted to hold the syntactical position.

See the 'then/else construct' for an explanation on the use of 'then' and 'else' clauses in statements that allow or require them.

Example

equ vm to char(253)
continents = 'africa':vm:'asia':vm:'south america'
input acontinent
locate(acontinent,continents,1;position;'al') then
crt acontinent:' is already there'
end else
continents=insert(continents,1,position;acontinent)
end
crt continents

'continents' is a list of continents in alphabetical order.
'acontinent' is added to the list only if it does not already exist.
The 'locate' statement uses the sequence parameter 'al',
ascending, left-justified.

If the value of 'acontinent' is 'europe', it does not exist
in 'continents', causing 'locate' to take the
'else' clause with the value of 'position' set to 3. The
'insert' function places 'europe' in front of 'south
america' leaving 'continents' as:

africa]asia]europe]south america

The ']' (bracket) represents a value mark.

See Also

Command Name Type Description
basic.statements Definition Definition of statements and functions.
basic.num.expression Definition An expression which evaluates to a number.
basic.array.references Definition Referencing arrays.
basic.delete.function Function Deletes element from array.
basic.ac.expression Definition Derives an attribute count.
basic.string.expression Definition An expression which evaluates to a string.
basic.then/else.construct Definition provide program flow change based upon a boolean condition.
statement.block Definition one or more statements that follow a Pick/BASIC decision-path related token such as, but not limited to, 'then', 'else', 'locked' and 'onerr'.
basic.replace Function Replaces element in string expression.
basic.insert Function Inserts element into array.
basic.vc.expression Definition Derives a value count.
basic.ins Statement Alternate method of 'insert'.
basic.extract Function Extracts element from array.
basic.array.variable Definition References a dimensioned array.
ue.1072 User Exit Sorts a dynamic array.
setting Command see 'get' and 'locate'.
basic.sc.expression Definition Derives a subvalue count.
basic.sort Function Sorts a string of attributes or values.

User Comments

What do you think?

Share your experience or ask a question by using the form below.

Login to leave your comments.