Syntax


Specific Format:


LOCATE



{ line-label | line-num }

Generic Format:


LOCATE



[ { { line-label-a | line-num-a }  { line-label-b | line-num-b }  }  ]

[ NOT ]

{ CHANGE | COMMAND  | DIFF    | ERROR  | EXCLUDED | FILE             | 

  FIND   | HANDLE   | KEEP    | LABEL  | LONG [n] | NOTE/xNOTE/ZNOTE | 

  NU/U   | PAGE [n] | SPECIAL | SIZE n | TAG      | tagname         }

[ NEXT    | FIRST   | LAST    | PREV   | CURRENT | ALL [ MX ] ]   

[ colorname | STD     ]

[ TOP ]


Operands


line-label | 

line-num

The line number or line label which you wish located and scrolled to the top of the screen when specifying a specific format LOCATE command.

line-label-a | line-num-a

line-label-b | line-num-b

An optional range of lines to be searched when using the generic format LOCATE command.

NOT

This will negate or reverse the generic search request to locate the next line which does not meet the specified criteria.

CHANGE

Locate the next line flagged as modified by Change processing. i.e. a line marked by ==CHG>.

DIFF

DIFF is simply an alias for U, the DIFF report marks lines which are altered as USER lines, so a LOCATE DIFF command takes you to the next marked DIFF block.

COMMAND

Locate the next line containing an unprocessed line command.

ERROR

Locate the next line flagged as in error. i.e. a line marked by ==ERR>. (Future use).  LOCATE ERROR is not currently supported. You can issue a command of LOCATE ERROR, but nothing will be found.

EXCLUDED

Locate the next excluded line.

FILE

Locate the next line marked by =FILE> marker.

FIND

Locate the next line which has been previously found by a FIND command, or changed by a CHANGE command. Even though there are no visible markers for found lines as there are for changed lines, SPFLite will ‘remember' the location of found lines as if a ‘hidden' marker existed on such lines. Just as with the ==CHG> marker, the hidden found-markers are cleared in response to a RESET command.

KEEP

Locate the next line containing a 'kept' line command.

HANDLE

Locate the next line containing a Handle.

LABEL

Locate the next line which contains a label.

LONG [ n ]

Locate the next line longer than the specified value (or when omitted, the current LRECL value when LRECL is > 0).

NOTE

Locate the next line having a =NOTE> marker.

xNOTE

Locate the next line having an extended xNOTE> marker, where "x" is any letter from A to Y.

ZNOTE

Locate the next line having an extended xNOTE> marker of any kind, where "x" is any letter from A to Y. When ZNOTE is specified, "plain"  =NOTE> markers are not located. As a reminder,  extended xNOTE> markers of type 'Z' are not permitted; that is, you cannot issue a line command of ZNOTE and no ZNOTE> line markers can be created.

SIZE n

Locate the next line whose length is equal to the specified value (0 is permitted to search for empty (null) lines).

PAGE [ n ]

Locate the next line having a =PAGE> marker. If the optional 'n' page number is provided, it will scroll to the requested page number.

SPECIAL

Locate the next special line (COLS, BNDS, TABS etc.)

TAG

Locate the next line containing a Tag

:tag

Locate the next occurrence of the specified Tag.

NEXT | FIRST |

LAST | PREV

These modify the search action from the normal default of NEXT and refer to a line's position within the file.

ALL [ MX ]

Specify ALL when LOCATE is used for the side-effect of changing the exclusion status of one or more lines. The ALL keyword will also report on the number of lines found.


LOCATE ALL will locate lines matching the specified condition, and will then unexclude them.

LOCATE ALL MX will locate lines matching the specified condition, and will then make them excluded.


The keywords FILE and ALL cannot be used together. See discussion below.

CURRENT | CURR

May be used only with LOCATE FIND and LOCATE CHANGE to locate the most recently found or changed line processed by these commands.

colorname

Used to locate lines having the specified color, as set by a corresponding (Pen/colorname)  "virtual highlighting pen" keyboard function. May be used with the NOT keyword to locate lines not having the specified color. To "have" a color means that at least one character on the line has the specified color. It is not necessary for the entire line to be of that color.


See Working with Virtual Highlighting Pens for more information.

STD

Used to locate lines not having any of the colors that can be set by a  (Pen/colorname) "virtual highlighting pen" keyboard function. That is, lines that are located are ones that only consist of the standard text color. When used with the NOT keyword, it can be use to locate lines having any text marked by a virtual highlighting pen in any of the standard colors. Because LOCATE locates lines and not any particular character string, a line is considered "standard" when there are no characters on it in any of the standard colors. Since at least one character must be present for a colorized character to exist, lines of length zero are always considered "standard" lines (because no characters of any of the other standard colors were present on the line).


See Working with Virtual Highlighting Pens for more information.

TOP

Normally, at the completion of the command, the first or only line located is highlighted (if it is on the current screen) or the screen is scrolled to the next appropriate screen line (as ISPF does) if the desired line is not on the current screen. 


If TOP is coded, then the line is always positioned as the top line of the screen, regardless of its current location. Using TOP can be helpful if you are scrolling through a large file containing many instances of repetitive data; TOP will prevent the appearance of the screen from "bouncing around" as you go through the file, making the data easier to read.

 

Abbreviations and Aliases


LOCATE can also be spelled as L or LOC

CHANGE can also be spelled as C, CHG or CHA

COMMAND can also be spelled as CMD or COM

CURRENT can also be spelled as CURR

EXCLUDED can also be spelled as X, EX, EXC, or EXCLUDE

LABEL can also be spelled as LAB or LABELS

SPECIAL can also be spelled as SPE

TAGS can also be spelled as TAG


Description


The LOCATE command repositions the visible portion of the file to the location specified by the operands.


The ALL option allows you to use LOCATE to exclude or unexclude lines based on a "locate condition".  When ALL is used on LOCATE, no particular line is located. In practice, the edit screen will be positioned at the last line located.  For example, suppose the condition you were interested in was whether lines had labels. Then, you can issue commands like this:


LOCATE ALL LABEL

Find all occurrences of labeled lines, and as a side-effect, unexclude all of them.


LOCATE ALL LABEL MX

Find all occurrences of labeled lines, and as a side-effect, make all of them excluded. The MX option is allowed only when ALL is present.


Note: In a Multi-Edit session, the =FILE> marker lines cannot be manually excluded or tampered with. To maintain the integrity of these lines, you cannot issue the command LOCATE ALL FILE MX, nor (for sake of consistency) can you say LOCATE ALL FILE without the MX either. LOCATE ALL FILE would only have reported the number files in the Multi-Edit session, and this information is available on the status line.


Note:  LOCATE ERROR is reserved for future use to support ISPF compatible functionality, but is not currently supported.



Examples


To find the next special line

LOCATE SPE


To find the next line with a label

LOC NEXT LABEL


To find the next line with a tag

LOC NEXT TAG


To find the last line with a tag of :T

LOC LAST :T


To find the next excluded line between .START and .END

LOC X .START .END

 

To find the first excluded line between .E and .S

L FIRST .E .S X


To find the first line that is exactly of length 25

L FIRST SIZE 25

 

To find the first line with text that is marked with the Green virtual highlighting pen color  

L FIRST GREEN  


To find the last line with text that is not marked with the Red virtual highlighting pen color

L LAST NOT RED 


To find the first line with text that is not marked with any virtual highlighting pen color  

L FIRST STD  


To find the last line with text that is marked with any virtual highlighting pen color

L LAST NOT STD 

Created with the Personal Edition of HelpNDoc: Full-featured Help generator