Lund Performance Solutions

MAGNET scans a set of files for the presence of one or more text strings. Many options allow for flexible pattern description. Moreover, MAGNET supports a very powerful fileset specification syntax so you can qualify your file searches for maximum efficiency.


Program capabilities required include IA, BA, DS and PH. No special user capabilities are required to run MAGNET.


MAGNET can be run from either the supplied UDC or from a fully-qualified RUN statement.
  • UDC
  • :MAGNET "-f@.c -c ’main’ ’define’"
    :MAGNET "<fileset> [options] <text string>" [parm=#]
  • RUN
  • :RUN MAGNET.PUB.LPSTOOLS;INFO="<fileset> [options]
    <text string>";[parm=#]
    Run MAGNET with parm=1 to suppress paging.
    Options are specified in a list separated by one or more spaces. Most options start with a hypen (- ) followed by an option character, followed by an optional string. The option character is not case- sensitive. Filesets may be specified using a LISTF style format or by using MAGNET’s extended fileset specification syntax. MAGNET scans normal ASCII flat files and QEDIT (filecode=111) work files by default. However, MAGNET can scan any other file type (using the -d option) except for privileged files.
    The output from MAGNET varies depending on user-selected options. The default output consists of a filename followed by an asterisk if the text string was found in the file.
    Output example:

    Figure 11.1 MAGNET Output
    If a "-l" option is specified, then the entire matching line is displayed as well as the name of the line in which it was found.

    NOTE MAGNET modifies the access date of files that it has scanned. The text string is always the last item specified.

    Figure 11.2 Text String Definition


    Multiple Word Searches

    You would enter the following to find all occurrences of the words "one", "two", and "three".

    NOTE Placing single quotes around each word is required for multiple word searches.

    :magnet "-f@ -l ’one’ ’two’ ’three’"

    Single Word Searches

    You would enter the following to find all occurrences of the word "five".

    NOTE Single word searches do not require single quotes.

    :magnet "-f@ -l five"
    :magnet "-f@ -L ’five’"

    Single Word Searches For Combined Words

    You would enter the following to find all occurrences of the combined words "Lund Performance Solutions".

    NOTE Single quotes are required when blanks are used to separate words within the desired string.

    :magnet "-f@ -l ’Lund Performance Solutions’"

    The file-set expression

    Figure 11.3 MAGNET Extended Fileset Syntax

    NOTE All literals are case insensitive.

    Some examples:
    Example 1 shows all the files in the group pub.
    Example 2 shows all the files in this account, but not in the group pub.
    @.@ -
    Example 3 shows all files in this account, created after January 15 1991.
    Example 4 shows all native mode program files in this account, larger than 1000 sectors.
    For further information, you may wish to refer to the appendices containing filecode lists (Appendix B) and the LISTF wildcard syntax (Appendix C).

    Options Summary

    MAGNET is a single-command based tool that uses multiple options to achieve the desired result. Options are briefly described below. Most options may be preceded with "no" to deselect the action (i.e., -noascii). Complete descriptions are provided in the next section.
    Table 11.1 MAGNET Options
    Option Name
    All words must be present
    Aligns file-group-account names into columns
    Defines printable as ascii 32..126 (see -printable)
    Saves output fileset as a permanent file. (see -o)
    All files (default is ASCII and Qedit only)
    Ignores Case
    Uses carriage control when the -p option is used
    Displays two lines before and two lines after every match
    -contexta #
    Displays # lines After every match
    -contextb #
    Displays # lines Before every match
    Displays # matches found in each file
    Causes ^Y (CTRL-Y) to immediately terminate MAGNET
    Synonym for -binary
    Prints line of dashes after 'hit' files.
    Shows line numbers in Editor format (12345.678)
    -f [fileset]
    Specifies set of files to search.
    Ignores filecodes (normally excludes most filecodes)
    Uses Gold Nugget KLONDIKE to prefetch
    Prints a page Header on each page
    Displays the help file
    Inverts final 'interesting' decision
    Lists each occurrence of search string found
    -lockword ccc
    Uses the specified lockword (-lockword fakelock)
    Scans for matches 'left-to-right' only
    Outputs set should have filenames in MPE format (-o)
    -maxlines #
    Limits number of matching lines shown per file to #
    -maxread #
    Limits number of records read per file to #
    -maxrecords #
    Limits number of records read per file to #
    -maxtotal #
    Stops scanning after that many total hits
    Allow MSG files to be read
    Uses COPY mode when opening MSG file (on by default)
    Allows waiting on empty MSG files (off by default)
    Shows line numbers for each line
    Tells MAGNET to ignore subsequent occurrences of five options
    Shows online line number of matching lines, not the text
    -o outputset
    Name of file to save the list of matching files in
    Tells MAGNET to restore the old access date of files
    Tells MAGNET to report origin of all option lines
    -p device
    Name of device for printed output (i.e.: -p LP)
    Turns on paging for interactive output
    Adds underscore (_) to definition of a word (-w)
    Use Gold Nugget KLONDIKE to prefetch (= -g)
    Causes non-printables to display as dot (.) (default)
    Quiet. Suppresses progress messages (unless -h or -l)
    Search QEDIT files as well as ASCII files (default)
    Search only QEDIT files
    -quote c
    Use the specified character as a quoted string delimiter
    -s specials
    Defines extra characters that may be in 'word' (-w)
    Adds apostrophe (') to definition of a word (-w)
    Adds apostrophe (') and underscore (_) to word (-w)
    -t text
    Specifies text string to look for.
    Multiple strings may be specified.
    -t "text"
    ’text with spaces’
    Sends message for each matching file to console
    Prints a timestamp at end
    Recursively search down any HFS directories we see
    Prevents screen-enhancements for search strings with -l
    Whole Word search only. -t fo -w won't match 'for'
    Summary of results
    -z #
    Debugging mask set to integer # value
    Strings must start in column 1 to match
    -( ###
    Start search in column ### (ignore prior columns)
    -) ###
    Right-most column search string may start in
    Limits searches to the first 72-bytes in a record

    NOTE Single letter options are not case-sensitive.
    The options flagged with "(-w)" above mean that specifying
    them implies -w as well.

    Options Definitions

    Following is a detailed description of each of the MAGNET options. Some options include syntax.
    Specifies that a file will only be flagged if it contains all the search strings. The default is that the file will be flagged if it contains one or more of the search strings.
    Tells MAGNET that filenames should be displayed in a manner where the group parts line up (align), and the account parts line up. (i.e., "FOO .A .SYS ")
    -NOalign tells MAGNET to display filenames in a compact manner (i.e., "FOO.A.SYS")
    DEFAULT: -NOalign
    Specifies that any ASCII characters outside of the range 32..126 should be displayed as dots (.). -NOascii will allow all characters in the range 32..255 to be displayed without change.
    DEFAULT: -NOascii7
    Specifies that the output set must be saved as a permanent file. The default is to save it as a temporary file. (See also -o).
    Specifies that all files must be searched. MAGNET normally defaults to searching only ASCII and QEDIT files (-qedit).
    DEFAULT: -NOd (ASCII and QEDIT only)
    Tells MAGNET to ignore the Case of alphabetic characters while searching.
    DEFAULT: -NOc (searching is case sensitive).
    Tells MAGNET to use Carriage Control when writing to -p device.
    DEFAULT: -cctl (if using -p, else -NOcctl)
    Tells MAGNET to display 2 lines before every matched line, and 2 lines after every matched line. Equivalent to saying: -contextb 2 -contexta 2
    DEFAULT: -NOcontext
    -contexta #
    Tells MAGNET to display # lines After every matched line.
    DEFAULT: -NOcontexta
    -contextb #
    Tells MAGNET to display # lines Before every matched line.
    DEFAULT: -NOcontextb
    Tells MAGNET to report number of matches found in each file (if the number is greater than 0).

    NOTE not intended to be used with "-and"

    Tells MAGNET to use stop immediately and terminate when control-Y is hit.
    DEFAULT: -NOcystop (control-Y will ask if you want to stop).
    Synonym for -binary (obsolete).
    Tells MAGNET to separate files with "hits" by a long dashed line. -dash implies -l. -NOdash does not imply -NOl.
    Tells MAGNET to convert line numbers in printed record to an Editor/3000 compatible format.
    DEFAULT: -NOe (record numbers are not converted)
    -f [fileset]
    Specifies set of files to search. The fileset syntax is the same as for the :LISTF command. Multiple -f options are allowed. If fileset is omitted, "@" is assumed.
    DEFAULT: -f@
    Normally, unless -binary was specified, MAGNET only looks at ASCII files (and, usually QEDIT files), but it will usually exclude ASCII files whose filecode isn't 0, 8, EDTCT, or OUTSP. -fcode tells MAGNET to skip the filecode check.
    DEFAULT: -NOfcode (which means: exclude some files by filecode)
    Tells MAGNET to print a page header on each page.
    DEFAULT: -NOh (no page header is printed)
    Tells MAGNET to print this display this entire help file.
    Tells MAGNET to invert the final "interesting" choice.
    Tells MAGNET to list all occurrences of the search string. If -NOl is in effect, lines are not listed (instead, files that contain one or more occurrences of the search string(s) are flagged with an asterisk).
    DEFAULT: -NOl (Lines are not listed)

    NOTE If more than one string is to be searched and the -L option is in effect, searching is considerably slower.

    -lockword ccc (or -NOlockword)
    -lockword tells MAGNET to use the specified lockword when opening a file to search. If the file doesn't have a lockword, then MPE ignores the supplied lockword and opens the file anyway. If the file has a lockword which differs from the supplied lockword, the open request fails.
    If -neverlockword is seen, then MAGNET ignores any subsequent -[no]lockword.
    If -NOlockword is specified, and a file has a lockword, then MPE will prompt the user for a lockword at open time.
    DEFAULT: -lockword fakelock (MPE/iX 5.0 and later)
    DEFAULT: -NOlockword (MPE/iX 4.5 and earlier)
    Specifies that the output set should contain file names in MPE format. (See also -o).
    -maxlines # (or -NOmaxlines)
    Tells MAGNET to stop scanning a file after "#" matches are found. This is only meaningful in conjunction with "-l".
    A value of 0 (or -NOmaxlines) means: don't limit the number of lines found.
    DEFAULT: -NOmaxlines
    -maxreads # (or -NOmaxreads)
    -maxrecords # (or -NOmaxrecords)
    Tells MAGNET to stop scanning a file after "#" records are examined. (MAXRECORDS is a synonym for MAXREAD).
    A value of 0 (or -NOmaxrecords) means: don't limit the number of records examined.
    DEFAULT: -NOmaxrecords
    -maxtotal # (or -NOmaxtotal)
    Tells MAGNET to stop scanning and terminate after a total of # hits have been found. It doesn't matter how many files were scanned, or how many had hits, or how many hits per file were found ... as long as the specified *total* number of hits were found, MAGNET will stop.
    A value of 0 (or -NOmaxtotal) means: don't limit the number of hits.
    DEFAULT: -NOmaxtotal
    Tells MAGNET to read MSG files (normally skipped over). If -msgcopy is true (which it is, by default), "COPY" mode is used in reading the file, so the records don't "disappear".

    NOTE Prior to MPE/iX 5.0, the records in a MSG file read in COPY mode are not neccessarily in chronological order.

    DEFAULT: -NOmsg
    Tells MAGNET to use COPY mode when opening a MSG file. If -msg is set, and -NOmsgcopy is set, then records read from a message file will "disappear" from the file.
    DEFAULT: -msgcopy
    Tells MAGNET to wait when reading from an empty MSG file. Only has effect when -msg and - NOmsgcopy.
    DEFAULT: -NOmsgwait
    Tells MAGNET to print line numbers for each listed line.
    DEFAULT: -NOn (no line numbers are shown)
    The five "-never..." options tell MAGNET to ignore subsequent occurrences of five options. The "never" option would typically be used in a global MAGNET configuration file. The options are:

    ignore all subsequent -[no]LOCKWORD
    ignore all subsequent -[no]OLDDATE
    ignore all subsequent -[no]PREFETCH
    ignore all subsequent -[no]TELLOP
    ignore all subsequent -Z #

    For example, if you never want to restore old access dates to files (and don't want any users overriding you!), add the following to MAGNET.CFG.LPSTOOLS:
    -noolddate -neverolddate
    Tells MAGNET to only list line numbers (or sequence numbers if -e is used too) instead of the complete text of matching lines.
    DEFAULT: -NOnumbers
    -o outputset
    Specifies that the file names of the files that "match" the search string(s) be saved in a file, named outputset.
    Tells MAGNET to try to restore the old access date for files that it touches. -NOolddates tells MAGNET to not try to reset the access dates of any files. -neverolddate tells MAGNET to ignore any subsequent -[no]olddates.
    DEFAULT: -olddates
    (Internal debugging option)
    Tells MAGNET to display the origin of the current (and subsequent) option string(s) being parsed, as well as a copy of the string. If the string came from the MAGNET.CFG file in the logon account, it will be prefaced with "[cfg]". If the string came from the MAGNET.CFG.LPSTOOLS file, it will be prefaced with "[cfg]". If the string came from the INFO string, it will be prefaced with "[INFO]". If MAGNET is run with PARM=2, an implied -origin is done at the start.
    DEFAULT: -NOorigin
    -p device
    Tells MAGNET the name of the device (e.g.: LP or 113) on which output is to be printed. When the -p option is given without a device, then LP is used. -NOp means: use $STDLIST.
    DEFAULT: -NOp (output is printed on $STDLIST)
    LPSLP is the formal file name opened when -p is specified. The -p directs most output to LPSLP, but some progress information will still come to $STDLIST for interactive users.

    NOTE If a file equation for LPSLP exists which specifies the device name (i.e.: FILE LPSLP;DEV=LP;CCTL), then the device name specified by the -p is ignored by MPE. A file equate for LPSLP which will allow a -p to specify a device AND which sets the output priority to 13 could be done: FILE LPSLP; DEV= ,13

    Tells MAGNET to paginate interactive output. See also PARM=1
    DEFAULT: -paging (for interactive, -NOpaging for batch)
    This option is used to suppress paging.

    NOTE No dash is used for this option.

    Does an implied -origin.
    Add underscore (_) to list of characters that make up words. This is a shorthand of saying: -w -s_
    DEFAULT: -NOpascal
    -prefetch (or: -g)
    Tells MAGNET to use the KLONDIKE tool to prefetch files that will be scanned. This may yield a substantial performance improvement for very large files. If -neverprefetch is seen, then MAGNET ignores any subsequent -[no]g or -[no]prefetch.
    DEFAULT: -NOprefetch
    Tells MAGNET to display non-printable characters as dots (.). (A non-printable character is one whose ASCII code is 0..31, or 127..255.)
    DEFAULT: -printable
    Tells MAGNET to be Quiet. This suppresses progress messages and (if -H and -L are not used) produces only a list (one per line) of file names of files that have one (or more) occurrences of the specified string(s). This output is appropriate for directing to a file and manipulating with an editor.
    DEFAULT: -NOq (not quiet)
    Tells MAGNET that it is allowed to treat (and read) QEDIT files as though they were ASCII files. NOQEDIT tells MAGNET to skip reading QEDIT files.
    DEFAULT: -qedit
    Tells MAGNET to only select QEDIT files.
    DEFAULT: -noqeditonly
    -quote c
    (where "c" is any printable character)
    Tells MAGNET the character you will be using as a "quote" to enclose tokens. For example, to search for the text "'" (composed of the 3 characters quote, apostrophe, quote), and also search for the three letter word FOO, you could say: -quote \ \"'"\ \FOO\
    DEFAULT: -quote '
    -s specials
    Specifies a string of characters to be considered as non-terminators when a WHOLE-WORD search is done (see -W option). Multiple -s strings are concatenated, along with any -pascal, -spl, and -splash.

    NOTE -s implies -w.

    Example: -s_ (includes "_" in words)
    DEFAULT: -NOs (no special characters for words defined)
    Add apostrophe (') to list of characters that make up words. This is shorthand for saying: -w -s'
    DEFAULT: -NOspl
    Add apostrophe (') and underscore (_) to list of characters that make up words. This is shorthand for saying: -w -s_'
    DEFAULT: -NOsplash
    -t text or -t "text" or text or "text" or ’text with spaces’
    - alternate ways of specifying search text
    Specifies the text to search for. The search text need not be enclosed in quotes. Quotes are necessary if any blanks or special characters are part of the text.
    DEFAULT: (no text is specified, MAGNET will report an error)
    More than one text can be given by repeating the text option. There is no default value, therefore at least one text option must be given.
    Examples: Fred
    Looks for: ...Fred... in
    "Fred Fulton"
    Looks for: ...Fred Fulton... in logon group
    Looks for: ...c@a... in logon group
    (note: "@" is not a wildcard here)

    Tells MAGNET to send a message to the operator console announcing each matching file found. If -nevertellop is seen, then MAGNET ignores any subsequent -[no]tellop.
    DEFAULT: -NOtellop
    Tells MAGNET to print a timestamp (date & time) at the end of its output.
    Tells MAGNET to recursively search down any hierarchical directories that the initial fileset might include.
    -NOtree tells MAGNET to ignore HFS directories.
    DEFAULT: -tree
    Tells MAGNET not to enhance the found data in lines printed to the screen.
    DEFAULT: -NOu (i.e.: enhance)
    Tells MAGNET to search for Whole words only. If this option is in effect, a string will only match if it is preceded and followed by a separator. A separator is any non-alphanumeric character, that is not given in the -s option. Using any of the options -s, -pascal, -spl, or -splash implies -w.
    DEFAULT: -NOw (any string matches)
    Tells MAGNET to produce a short summary of the search results. ("-summary" is a synonym for "- y")
    Example summary:
    Scanned 31 files in 2.914 seconds (found 1 matching files)
    Search string: magnet.

    NOTE If -p is used with -y, the summary is sent to both the terminal and the -p device.

    If -p is used with -y, the summary is sent to both the terminal and the -p device.
    -z #
    Sets some internal debugging flags to the specified value. If -neverz is seen, then MAGNET ignores any subsequent -[no]z
    Tells MAGNET to only check for a match against strings in column #1.
    DEFAULT: Search all columns.
    -( ###
    Tells MAGNET to start the search at column ###. The leftmost column of a file is 1. Example: -( 9
    -) ###
    Tells MAGNET the right-most column that text is allowed to start in. Example: -(4 -)5 -t begin will search for "begin" starting in columns 4 or 5.
    Shorthand method of saying -)72


    The ToolBox collections from Lund Performance Solutions have a uniform user interface. As a result, in addition to the commands specific to each Toolbox tool, most tools allow the commands described in "TOOLBOX STANDARDS".

    MAGNET Examples

    Example 1:
    :run;info="-f@.source foo -s_ -W -C"
    The above command line do the following: ignores the case of characters, searches for "whole words" only (so a line with "food" will not match), adds underscore to the list of characters that can be in a word (so "foo_foo" will not match, but foo'fum will). It also searches all ASCII/QEDIT files in the SOURCE group in the logon account. The -C options tells MAGNET to internally upshifts all text (and the string "foo") before checking for matches. Note that "-w" is redundant, as "-s" implies "-w".
    Because -L was not specified, MAGNET will simply produce a list of files that include one (or more) occurrences of "foo".
    Example 2:
    :run;info="-f@.source-@q.source-bnf.source - tFOO -L"
    Search all ASCII/QEDIT files in the SOURCE group except the file BNF.SOURCE and except any file ending in "Q". List each line that contains "FOO".
    Example 3:
    :run;info="-f@.source -(4 -)4 -tbegin -L - binary"
    Search all files in the SOURCE group for "begin" starting only in column 4. Each line found will be listed.
    Example 4:
    :run;info="-f@.source 'foo' -noqedit";parm=1
    Will search all ASCII files (no binary, no QEDIT) in the SOURCE group. However, after displaying 22 lines of matches (assuming there are that many matches) MAGNET will not pause. This is particularly useful when scanning large filesets.
    The following is an example of typical MAGNET output on the text string, "standard". MAGNET highlights each occurrence of the specified text string in context of the entire line in which it is found. After you enter the command, the resulting output is shown in Figure 11.4.

    Figure 11.4 MAGNET Output on a Text String Search

    MAGNET Error Messages

    Each MAGNET error message is described in the following table.
    Table 11.2 MAGNET Error Messages
    Invalid file set
    Improper use of fileset specification
    Review "specifying filesets" in the MAGNET chapter (see "The file-set expression").
    Unknown option
    An unknown option character was detected by MAGNET.
    Valid option character are: a, b, c, d, e, f, g, h, l, m, n, o, p, q, s, t, w, [, (, ).

    Lund Performance Solutions
    Voice: (541) 812-7600
    Fax: (541) 81207611