basic.locate Statement/BASIC Program

basic.locate

Command basic.locate Statement/BASIC Program
Applicable release versions: R83, AP, AP 6.0
Category BASIC Program (486)
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.
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]
Options
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.
Purpose
Related basic.statements
basic.num.expression
basic.array.references
basic.delete.function
basic.ac.expression
basic.string.expression
basic.then/else.construct
statement.block
basic.replace
basic.insert
basic.vc.expression
basic.ins
basic.extract
basic.array.variable
ue.1072
setting
basic.sc.expression
basic.sort