TOCPREVNEXTINDEX

Lund Performance Solutions


The MAGNET Tool
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.

Capabilities

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

Usage

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

    Examples

    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.
    @.pub
    Example 2 shows all the files in this account, but not in the group pub.
    @.@ - @.pub
    Example 3 shows all files in this account, created after January 15 1991.
    @.@,credate>910115
    Example 4 shows all native mode program files in this account, larger than 1000 sectors.
    @.@,code=nmprg,eof>1000
    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
    Description
    -a
    All words must be present
    -align
    Aligns file-group-account names into columns
    -ascii7
    Defines printable as ascii 32..126 (see -printable)
    -b
    Saves output fileset as a permanent file. (see -o)
    -binary
    All files (default is ASCII and Qedit only)
    -c
    Ignores Case
    -cctl
    Uses carriage control when the -p option is used
    -context
    Displays two lines before and two lines after every match
    -contexta #
    Displays # lines After every match
    -contextb #
    Displays # lines Before every match
    -count
    Displays # matches found in each file
    -cystop
    Causes ^Y (CTRL-Y) to immediately terminate MAGNET
    -d
    Synonym for -binary
    -dash
    Prints line of dashes after 'hit' files.
    -e
    Shows line numbers in Editor format (12345.678)
    -f [fileset]
    Specifies set of files to search.
    -fcode
    Ignores filecodes (normally excludes most filecodes)
    -g
    Uses Gold Nugget KLONDIKE to prefetch
    -h
    Prints a page Header on each page
    -help
    Displays the help file
    -invert
    Inverts final 'interesting' decision
    -l
    Lists each occurrence of search string found
    -lockword ccc
    Uses the specified lockword (-lockword fakelock)
    -lr
    Scans for matches 'left-to-right' only
    -m
    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
    -msg
    Allow MSG files to be read
    -msgcopy
    Uses COPY mode when opening MSG file (on by default)
    -msgwait
    Allows waiting on empty MSG files (off by default)
    -n
    Shows line numbers for each line
    -never...
    Tells MAGNET to ignore subsequent occurrences of five options
    -numbers
    Shows online line number of matching lines, not the text
    -o outputset
    Name of file to save the list of matching files in
    -olddates
    Tells MAGNET to restore the old access date of files
    -origin
    Tells MAGNET to report origin of all option lines
    -p device
    Name of device for printed output (i.e.: -p LP)
    -paging
    Turns on paging for interactive output
    -pascal
    Adds underscore (_) to definition of a word (-w)
    -prefetch
    Use Gold Nugget KLONDIKE to prefetch (= -g)
    -printable
    Causes non-printables to display as dot (.) (default)
    -q
    Quiet. Suppresses progress messages (unless -h or -l)
    -qedit
    Search QEDIT files as well as ASCII files (default)
    -qeditonly
    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)
    -spl
    Adds apostrophe (') to definition of a word (-w)
    -splash
    Adds apostrophe (') and underscore (_) to word (-w)
    -t text
     
     
    Specifies text string to look for.
    Multiple strings may be specified.
    -t "text"
    text
    "text"
    ’text with spaces’
    -tellop
    Sends message for each matching file to console
    -timestamp
    Prints a timestamp at end
    -tree
    Recursively search down any HFS directories we see
    -u
    Prevents screen-enhancements for search strings with -l
    -w
    Whole Word search only. -t fo -w won't match 'for'
    -summary
    Summary of results
    -y
    -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
    -72
    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.
    -a
    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.
    DEFAULT: -NOa
    -align
    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
    -ascii7
    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
    -b
    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).
    DEFAULT: -NOb
    -binary
    Specifies that all files must be searched. MAGNET normally defaults to searching only ASCII and QEDIT files (-qedit).
    DEFAULT: -NOd (ASCII and QEDIT only)
    -c
    Tells MAGNET to ignore the Case of alphabetic characters while searching.
    DEFAULT: -NOc (searching is case sensitive).
    -cctl
    Tells MAGNET to use Carriage Control when writing to -p device.
    DEFAULT: -cctl (if using -p, else -NOcctl)
    -context
    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
    -count
    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"

    -cystop
    Tells MAGNET to use stop immediately and terminate when control-Y is hit.
    DEFAULT: -NOcystop (control-Y will ask if you want to stop).
    -d
    Synonym for -binary (obsolete).
    -dashes
    Tells MAGNET to separate files with "hits" by a long dashed line. -dash implies -l. -NOdash does not imply -NOl.
    -e
    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@
    -fcode
    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)
    -h
    Tells MAGNET to print a page header on each page.
    DEFAULT: -NOh (no page header is printed)
    -help
    Tells MAGNET to print this display this entire help file.
    -invert
    Tells MAGNET to invert the final "interesting" choice.
    -l
    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)
    -m
    Specifies that the output set should contain file names in MPE format. (See also -o).
    DEFAULT: -NOm
    -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
    -msg
    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
    -msgcopy
    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
    -msgwait
    Tells MAGNET to wait when reading from an empty MSG file. Only has effect when -msg and - NOmsgcopy.
    DEFAULT: -NOmsgwait
    -n
    Tells MAGNET to print line numbers for each listed line.
    DEFAULT: -NOn (no line numbers are shown)
    -never...
    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:

    -NEVERLOCKWORD
    ignore all subsequent -[no]LOCKWORD
    -NEVEROLDDATE
    ignore all subsequent -[no]OLDDATE
    -NEVERPREFETCH
    ignore all subsequent -[no]PREFETCH
    -NEVERTELLOP
    ignore all subsequent -[no]TELLOP
    -NEVERZ
    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
    -numbers
    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.
    DEFAULT: -NOo
    -olddates
    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
    -origin
    (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

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

    NOTE No dash is used for this option.

    parm=2
    Does an implied -origin.
    -pascal
    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
    -printable
    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
    -q
    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)
    -qedit
    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
    -qeditonly
    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)
    -spl
    Add apostrophe (') to list of characters that make up words. This is shorthand for saying: -w -s'
    DEFAULT: -NOspl
    -splash
    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:

    -f@.pub.sys Fred
    Looks for: ...Fred... in @.pub.sys
    "Fred Fulton"
    Looks for: ...Fred Fulton... in logon group
    c@a
    Looks for: ...c@a... in logon group
     
    (note: "@" is not a wildcard here)

    -tellop
    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
    -timestamp
    Tells MAGNET to print a timestamp (date & time) at the end of its output.
    -tree
    Tells MAGNET to recursively search down any hierarchical directories that the initial fileset might include.
    -NOtree tells MAGNET to ignore HFS directories.
    DEFAULT: -tree
    -u
    Tells MAGNET not to enhance the found data in lines printed to the screen.
    DEFAULT: -NOu (i.e.: enhance)
    -w
    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)
    -summary
    -y
    Tells MAGNET to produce a short summary of the search results. ("-summary" is a synonym for "- y")
    DEFAULT: -NOy
    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
    DEFAULT: -NOz
    -[
    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.
    -72
    Shorthand method of saying -)72

    TOOLBOX STANDARDS

    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 magnet.pub.lpstools;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 magnet.pub.lpstools;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 magnet.pub.lpstools;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 magnet.pub.lpstools;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
    Message
    Cause
    Action
    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
    www.lund.com
    Voice: (541) 812-7600
    Fax: (541) 81207611
    info@lund.com
    TOCPREVNEXTINDEX