LOCATE

Purpose

Use the LOCATE subcommand to scan the file for a specified target, which (if found) becomes the new current line. The search starts with the line after the current line. Optionally, you can specify an XEDIT subcommand; it is executed starting at the specified target.

Operands

Locate

is the subcommand name but is optional. The target operand itself implies the LOCATE subcommand.

target

defines the line that is to become the new current line. It can be specified as an absolute line number, a relative displacement from the current line, a line name, a simple string expression, or a complex string expression. A complete description of targets follows.

subcommand

is any XEDIT subcommand, which is executed starting at the specified target.

Usage Notes

The ability to locate a line with a target is one of the editor's most versatile functions. A target is not only the operand of the LOCATE subcommand but is also an operand in many other XEDIT subcommands.

A target is a way to define a line to be searched for within the current top and bottom of the file (or top and bottom of the range — see SET RANGE) and between the beginning and end of each line (or between the left and right zones — see SET ZONE).

You can specify a target in the following ways:

1. An absolute line number is a colon (:) followed by a file line number or an asterisk. An asterisk indicates the null End of File (or End of Range) line. For example:

   :8

   makes file line number 8 the new current line.

   You can also search for a character string by preceding it with a colon. For example:

   :ABC

   searches for the first occurrence of ABC. If the character string starts with a number, an error will occur.

2. A relative displacement from the current line is an integer that can be preceded by a plus (+) or minus (–) sign, which indicates a forward (+) or backward (–) displacement from the current line. If the sign is omitted, a plus (+) is assumed.
   You can also specify a relative displacement as an asterisk (*), which means the Top of File (–*) or the End of File (+* or *) line. When you specify an asterisk as the target operand of a subcommand, the subcommand executes to the end (or top) of the file. For example, DELETE * deletes lines from the current line to the end of the file. Examples of relative displacement follow:

   • +3
     • The target is three logical lines down (toward the end of the file) from the current line.
   • -5
     • The target is five logical lines up (toward the top of the file) from the current line.
   • +*
     • The target is the null End of File (or End of Range) line.
   • -*
     • The target is the null Top of File (or Top of Range) line.
   • :5 copy +3 :25
     • copies lines 5, 6, and 7 after line number 25.
     • In this example, three targets are specified. The first (:5) is a LOCATE, even though the subcommand name is not specified.
3. A line name is 1 - 8 characters preceded by a period (.), which has been previously defined by a SET POINT subcommand or a .xxxx prefix subcommand (which limits the name to four characters). For example:

    .PART

   locates the file line whose name is PART and makes it the current line.

   The SET CASE (UPPERCASE or MIXED) option determines whether the line name is translated to uppercase. Additionally, in locating a line name target, uppercase and lowercase characters are significant regardless of the SET CASE option RESPECT or IGNORE.

4. A string expression defines a group of characters to be located. The characters in the string must be delimited by any character that does not appear in the string itself. However, if you use the XEDIT special characters (+ – .) to delimit a string target, the search direction (+ or –) must be stated explicitly. When a string target is entered by itself (without the optional subcommand name LOCATE), the delimiter must be a diagonal (/). In the examples that follow, a diagonal (/) is used.

   If SET HEX ON is in effect, you can specify a string in hexadecimal notation, and the editor searches for its EBCDIC equivalent. For example, if you specify a string as /X'C3D4E2'/, the editor searches for the string CMS.

   If SET ESCAPE ON is in effect, the commonly used LOCATE delimiter (/) may be interpreted as the ESCAPE character. To avoid this problem, use the LOCATE subcommand explicitly (for example, LOCATE /string/).

   The general format for a string expression is:

   

   Notes:

   • ¹ The final delimiter (/) is optional after the last string. Leading or trailing blanks are considered part of string.

   + or -

   The search direction is toward the end of the file (+) or toward the top of the file (–). If the sign is omitted, the default is plus (+).

   ¬

   NOT symbol (Locate something that is not the specified string.)

   string

   Character (or hexadecimal) string. The trailing delimiter may be necessary in certain circumstances. For example, if the first string has trailing blanks, use the trailing delimiter to indicate where the string ends.

   &

   AND symbol (ampersand) (Locate the line containing all of the strings separated by an &.)

   |

   OR symbol (vertical bar) (Locate the line containing any of the strings, separated by OR symbols, starting with the first string specified.)

   For example:

   • /horse/
     • searches downward in the file, beginning after the current line, for the first line that contains horse and makes it the current line.
   • ¬/house/
     • searches downward in the file for the first line that does not contain house and makes it the current line.
   • /horse/ & /house/ | /hay/
     • searches downward in the file for a line that contains either both horse and house or a line that contains hay, whichever comes first.
     • Targets anded together can overlap. For example, L/This/&/history/ could find the string “Thistory” as well as the string “This history”.
   • /horse/|¬/house/
     • searches downward in the file for the first line that contains horse or does not contain house.
   • -/X'C1'/|/X'C2'/
     • searches upward for the first line containing either or both of the strings specified here in hexadecimal.
     • If SET HEX ON is in effect, the editor locates a line containing A or B. If SET HEX OFF is in effect, the editor locates a line containing X'C1' or X'C2'.
   • //
     • advances the line pointer by one line.
5. A complex string expression has the same format as a simple string expression. A complex string is a string associated with one or more of the following SET subcommand options:
   • SET ARBCHAR
     • allows you to specify only the beginning and end of a string, using an arbitrary character to represent all characters in the middle.
   • SET CASE
     • allows you to specify whether the difference between uppercase and lowercase is to be significant in locating a string target.
   • SET ETARBCH
     • See Using Double-Byte Character Sets.
   • SET SPAN
     • allows you to specify if a string target must be included in one file line or if it can span a specified number of lines.
   • SET VARBLANK
     • allows you to control whether or not the number of blank characters between two words is significant in a target search.

   For example:

   LOCATE and SET ARBCHAR

      set arbchar on .
      /air.plane/

   would locate in the text either one of the following:

      the airplane was landing
      cold air surrounded the plane

   LOCATE and SET CASE

      set case m ignore
      /computer/

   would locate in the text any of the following:

      computer
      Computer
      comPUTer

   LOCATE and SET SPAN

   • If SET SPAN OFF is in effect, a string must be contained within one file line in order to match a target.
   • If SET SPAN ON is in effect, a string may start on one line and continue on n lines (as specified in the SET SPAN subcommand) and still match a target. In this case, the line containing the beginning of the string becomes the current line.
   LOCATE and SET VARBLANK

      set varblank on
      /the  house/

   will locate in the text either of the following:

      the house
      the                house

   Note: Target as discussed here is a line target, not to be confused with a column-target, which is the operand of only the CLOCATE and CDELETE subcommands.

Usage Notes for LOCATE Targets

1. LOCATE targets and SET STAY: If SET STAY OFF is in effect and the target is not located, the new current line is the bottom (or top) of the file (or range).

   If SET STAY ON is in effect and the target is not located, the line pointer remains unchanged.

   Note that SET STAY only applies when the target is not located and the search is issued to the end of file or end of range (that is, SET WRAP OFF is in effect).

2. LOCATE targets and SET WRAP: If SET WRAP OFF is in effect, the search for a string expression target stops with the end of file or range (or top of file or range).

   If SET WRAP ON is in effect, the editor wraps around the file and continues the search for a string expression up to and including the line preceding the current line. If a range has been defined, the editor wraps around the bottom of the range and continues at the top of the range (or if the search is in the other direction, the editor wraps around the top and continues at the bottom).

   When a wrap occurs under these conditions, the following warning message is displayed:

   592W Wrapped ....

   Note that if SET WRAP ON is in effect and the target is not located, the line pointer remains unchanged regardless of the SET STAY setting.
3. The LOCATE subcommand updates the LASTLORC buffer. See the SET LASTLORC subcommand.
4. For more information on the LOCATE subcommand, see Effects of Selective Line Editing Subcommands.
5. If the LOCATE subcommand reaches its target successfully (either return code 0 or 1), subcommand is executed.

Notes for Macro Writers

1. In a macro, an implicit backward locate (for example, –3) is interpreted by EXEC 2 as a label. To avoid this problem, use the LOCATE subcommand explicitly (for example, LOCATE –3), or use the COMMAND subcommand (COMMAND –3).

Messages and Return Codes

520E

Invalid operand: operand [RC=5]

545E

Missing operand(s) [RC=5]

546E

Target not found [RC=2]

592W

Wrapped ....

where return codes are: