FIND - Find a Character String

Syntax



FIND


WORDS | CHARS                          (Alter search context)


FIND


Alias - FF

(See Line Range / Pending Copy Conflict discussion below.)

search-string                          (Perform a normal FIND)

[ start-column [ end-column ] ]

[ FIRST | LAST | NEXT | PREV | ALL ]

[ PREFIX | SUFFIX | WORD | CHAR ]

[ LEFT | RIGHT ]

[ line-control-range ]

[ color-selection-criteria ]

[ color-change-request ]

[ X | NX ]

[ U | NU ]

[ MX | DX ]

[ TOP ]


Operands


There are two basic formats for the FIND command as shown in the syntax boxes above.   The first is used to alter the basic search context as it relates to use of the WORD option in normal searching.  This is covered below under the heading  "Search Context".


The following operand descriptions are for the normal use of the FIND command.


search-string

The search string that identifies the lines to be found


start-column

Left column of a range (with end-column) within which the search-string value must be found. If no end-column operand, then the search-string operand must be found starting in start-col.


end-column

Right column of a range (with start-column) within which the search-string value must be found.


FIRST

Starts at the top of the data and searches ahead to find the first occurrence of search-string.


LAST

Starts at the bottom of the data and searches backward to find the last occurrence of search-string.


NEXT

Starts at the first position after the current cursor location and searches ahead to find the next occurrence of search-string.  NEXT is the default.


PREV

Starts at the current cursor location and searches backward to find the previous occurrence of search-string.


ALL

Starts at the top of the data and searches ahead to find all occurrences of search-string.


LEFT

LEFT causes the search-string to be found at most once in any given line.  Where the search-string occurs more than once in the same line, only the left-most occurrence of search-string is found, and any other instances on that same line are ignored.


RIGHT

RIGHT causes the search-string to be found at most once in any given line.  Where the search-string occurs more than once in the same line, only the right-most occurrence of search-string is found, and any other instances on that same line are ignored.


PREFIX

Locates search-string at the beginning of a word.


WORD

Locates search-string when it is delimited on both sides by blanks or other non-Word characters.


CHAR


Locates search-string regardless of what precedes or follows it.

SUFFIX

Locates search-string at the end of a word.


line-control-range

The range of lines which are to be processed by the command.  Line control ranges provide a powerful tool to customize the range of lines to be processed.   The full syntax and allowable operands which make up a line control range are discussed in "Line Control Range Specification".  Refer to that section of the documentation for details.


See also the Line Range / Pending Copy Conflict discussion below.


color-selection-criteria

A request for selection based on the highlight color of the search-string. Color requests provide another powerful tool to control search selection.   The full syntax and allowable operands which make up a color-selection-criteria  are discussed in "Color Selection Criteria Specification".   Refer to that section of the documentation for details.


color-change-request

A request for highlighting of the found string.  The full syntax and allowable operands for the color-change-request are discussed in "Color Change Request Specification".   Refer to that section of the documentation for details.


X | NX

Specifies a subset of the line range to be processed.   X requests only excluded lines are to be examined, NX requests only non-excluded lines are to be examined.   If neither X or NX are specified, all lines in the range will be examined.


U | NU

Specifies a subset of the line range to be examined.   U requests only User lines are to be examined, NU requests only non-User lines are to be examined.   If neither U or NU are specified, all lines in the range will be examined.


MX

MX requests that all lines which DO contain search-string be excluded from the display following command processing.  

MX = Make Excluded.


DX

DX requests that lines which DO contain search-string, which, if excluded, would normally be made visible, be left in their excluded status.  DX = Don't change Excluded status


TOP

Normally, at the completion of the command, the first, or only, line processed is highlighted (if it is on the current screen) or the screen is scrolled to the 2nd screen line (as ISPF does) if the 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.


Abbreviations and Aliases


FIND can also be spelled as F

PREFIX can also be spelled as PRE or PFX

SUFFIX can also be spelled as SUF or SFX

WORDS can also be spelled as WORD

CHARS can also be spelled as CHAR

Description


You can use the FIND command to locate line(s) within the file which contain a specified string.  


To find the next occurrence of the letters ELSE without specifying any other qualifications:

On the Command line, type:


FIND ELSE


Press Enter. Since no other qualifications were specified, the letters ELSE can be:


To find the next occurrence of the letters ELSE, but only if the letters are uppercase:

On the Command line, type:


FIND C'ELSE'


Press Enter. This type of search is called a character string search (note the C that precedes the search string) because it finds the next occurrence of the letters ELSE only if the letters are in uppercase. However, since no other qualifications were specified, the letters can be found anywhere in the file, as outlined in the preceding list.


For more information, including other types of search strings, see Finding and Changing Data and Specifying a Picture or Format String.


Note:  When the FIND search operand is a Regular Expression (a string with an R type code) and reverse-order searching is done with PREV or LAST, only the left-most occurrence on any given line is found.  That is, the command


       FIND R'ABC' PREV


is treated as if it were specified as


       FIND LEFT R'ABC' PREV


and


       FIND R'ABC' LAST


is treated as if it were specified as


       FIND LEFT R'ABC' LAST


Note:  FIND cannot be used to find zero-length blank lines based on a string.  See NFIND for an example of how to do this.


Setting the search context with FIND WORDS and FIND CHARS


Operands


WORD | WORDS    |

CHAR | CHARS


Note: WORD and WORDS are interchangeable, as are CHAR and CHARS.


Description


This variation of the FIND command is a special extension to the syntax of the FIND command, and must be specified exactly as shown, with no other regular FIND operands.


FIND WORDS is used to set the default search context to WORD mode.

FIND CHARS is used to set the default search context to CHARS mode.  


This means that whenever a FIND, CHANGE or similar command is used, and none of the operands CHARS, WORD, PREFIX or SUFFIX are specified, the FIND or CHANGE command will proceed using the default assigned here.


This is convenient, for example,  when many FIND and CHANGE commands are required that need WORD mode.  By setting the search context to WORD mode, the operand WORD can be omitted from the individual FIND and CHANGE commands, making them shorter and faster to type.


CHARS mode is the installation default, and is how ISPF normally operates.  The main reason to issue FIND CHARS would be to change back to the standard active after a FIND WORDS command had been issued.


Setting the search context in this manner is only a default, applied when none of the operands CHARS, WORD, PREFIX or SUFFIX are specified.  Any of these keywords can be used on a FIND or CHANGE to override the current default search context, whatever it may be at that time.


When the default search context is set to WORDS, a W will appear the C/T indicator on the status line that shows the current CASE C/T mode.  Thus, depending on the CASE mode, the indicator will show either  C  W  or  T  W  on the status line.


If you issue a RESET command with no operands, the default search context will revert to the system-wide default (either WORDS or CHARS) that is defined on the Options - General screen using the checkbox, Use WORD as the default for FIND/CHANGE commands.   If that default is CHARS (checkbox not checked) the indicator will revert to either C or T on the status line.


The search context checkbox defined on the Options - General screen is the default when a file is opened.  You can set the search option to FIND CHARS or FIND WORDS any time you wish on any file tab.  This setting is not saved in the profile.


Line Range / Pending Copy Conflict - a Play in Three Acts


Synopsis




This new arrangement resolves a long-running conflict that pitted IBM ISPF compatibility with our desire for SPFLite to provide as many productivity extensions as possible.  We appreciate everyone's patience as we worked through this issue and "threaded the needle the right way".  


It is quite a tale, and here it is, told in three acts ...


Act I


The extended line-range-operand support provided by SPFLIte allowed you to specify a line range that a primary command is to use, either by specific command line operands (like .FROM .TO  or .20 .250), or by marking the line range with C/CC line commands.


This extended line-range-operand support was a general feature that applied to all primary commands that took a line range, including FIND.  Therein lies the rub ...


Act II


It was found that a common use case in ISPF was to first define a block of lines using C/CC, and then use the FIND command to locate a destination for those lines to be copied into, a task usually involving repetitive FIND commands (via RFIND) and/or manual scrolling.  By SPFLite making the general assumption (for every primary command, including FIND) that a CC or MM block always defined a line range, that assumption prevented this commonly-practiced ISPF use case from being performed.


Here's an example of this problem:


Suppose you want to copy line 2500 to some other part of the file, a long way from line 2500.  You're not sure where the right place is to copy the line, but you do know there's a string of ABC somewhere near where the new line needs to go.  Also, there's more than one ABC in the file, and so just finding one of them is not enough; you have to find the right ABC.


Incidentally, there is no string of ABC on line 2500 itself.  


So, you wanted to do this:


Scene I



Well, that's what you wanted to do, and in IBM ISPF, that's how it always worked.  


However, because of the general feature (added in "Act I"), every primary command that took a line range (including FIND), treated a pending C/CC or M/MM block as defining the range of lines that the primary command (FIND, in this case) was to operate on.


Thus, what actually happened was this:


Scene II



Hmm ... that's not right.  


What happened in Scene II is not ISPF compatible, and doesn't do anything useful.  So, the FIND command was recently exempted from the general line-range-defining role of C/CC and M/MM, in the name of ISPF compatibility, to make it possible to FIND with an active/pending C/CC block present.  Because of that exemption, FIND with a pending C/CC or M/MM works like Scene I shows it to work.

Act III


The exemption for FIND that was added in Act II is great, and solves a big problem.  However, that exemption for FIND removed the convenience of SPFlite's ability of FIND to use C/CC and M/MM as general command line-ranges, which is also an important and valuable use case - too useful to give up.


For example, suppose you wanted to quickly count the number of left parentheses in the first 100 lines of the file.  


You would like to be able to do something this:


Scene III



But, that won't work, because of the exemption added in Act II.  The block of lines is just "left hanging", and you get a message, "Pending Destination line command range".  So, it doesn't do anything wrong - it just doesn't do anything period.


To restore that capability, a FIND command alias of FF has been defined.  


What FF does is to treat any pending C/CC or M/MM line commands as defining the find operation's line range to search for, rather than keeping those lines as "pending" while scrolling through the data.  So, the new FF command works like the old FIND command did, before the FIND exemption was put in.  That's because FF uses  pending C/CC or M/MM line commands in the "general" way that other SPFLite primary commands do, and not like the "exempted FIND" command does.


In other words, the following now will work:


Scene IV



Other than the different name, and the different way that C/CC and M/MM blocks are handled, FF and FIND are the same command and accept exactly the same parameters.



Note:  The Find in Files command FF should not be confused with the new FF alias for the edit primary command FIND; the two commands are not related.  However, if you issue a File Manager command of FF ABC, and then open a file listed in the Found FIles FILELIST, you can quickly find the string ABC by retrieving the FF command (usually by the command mapped to F12).  Assuming there is no outstanding CC or MM blocks in the edit file, the FF ABC in the edit session will find the string ABC within the file, the same way that a regular FIND edit command would.  This can be a time-saving shortcut.


Created with the Personal Edition of HelpNDoc: Free EPub producer