SYNTAX

Get [dataFile1 [dataFile2]… | -dfl listFile] [-d default]
[-field fieldList] [-format formatString] [-h] [-h2] [-k key] [-l]
[-m] [-nf] [-q] [-s] [-search] [-sfl] [-t] [-width w] [-x] [-y]

DESCRIPTION

The Get tool retrieves information from the data files in 411 or from your own data files that have been tagged and indexed in the same manner. Normally Get is used to retrieve information stored in 411 data files. These data files consist of a set of records, each of which contains one or more fields of data. These records and fields are marked with special tags that Get recognizes and uses to retrieve the information you need.

Apart from supporting the 411 data files, you can use Get to create an information retrieval system for your own data files as specified by the dataFile parameter or the -dfl listFile option. Like the 411 data files, your files must consist of records that contain one or more fields of data.

Each record must start with the field tag æKy (æ is Option-'), followed by one or more keywords separated by spaces or carriage returns (see Examples). The field tag æKy signals the beginning of the record; other field tags within the record categorize information to be retrieved. The table below lists the field tags and the types of fields they indicate. To display these tagged fields, use the -field and -format options.

Given a data file tagged in this manner, Get creates an index file for it if one does not already exist. If you update the data file later on, Get needs to rebuild the index file. A dialog appears, requesting your permission to rebuild the index. Under ordinary circumstances, permission should be given.

INPUT

Standard input, unless you specify data files with the dataFile parameter or the -dfl listFile option.

OUTPUT

Standard output

STATUS

Get can return the following status codes:

PARAMETERS

dataFile1[,dataFile2]…

Specifies a list of comma-separated data file pathnames.

OPTIONS

-d default

Substitutes the keyword specified by default if the keyword option (-k key) is not specified and no selection has been made.

-dfl listFile

Specifies a file containing your list of data file pathnames. This option is an alternative to the dataFile parameter, which you can also use to specify one or more data files.

-field fieldList

Specifies which of the data fields associated with a keyword to display. This is a case-sensitive list of field categories, such as C for the commentary tagged by æC. Be sure to separate field categories with commas.

Note that if you specify this option, you must also specify the format of its display by using the -format option.

-format formatString

Formats output by inserting text strings before their associated data fields. By using text strings and the data field symbol (%s) you can specify the format in which you want data fields (-field) to appear. If you specify this option, you must also specify the data fields to be formatted by using the -field option.

The symbol %s represents the next field to be retrieved. You can embed more than one %s symbol in the text to represent data fields in the order in which they appear in the -field option. Note that you must place the entire formatString parameter within quotation marks. See Examples for a sample command line.

-h

Lists all data files in a header and indicates the one in which the keyword is found. The Get tool places the line that says

Look up… "key"

where key is the keyword, next to the file in which the keyword is found.

-h2

Places in a header only the single data file in which the keyword is found. If you use this option, Get displays a line that says

Look up… "key"

where key is the keyword, next to the name of the data file.

-k key

Retrieves the information in the record associated with the keyword (key). The data files are searched in the order in which you listed them in the dataFile parameter or in the -dfl listFile option.

-l

Lists all keywords that begin with the same letters as key in the -k option or, if you do not specify key, lists all keywords in the data file.

Note
The Get tool searches only the first data file listed. •

-m

Selects the keyword when found in a header. The selection is marked and {SaveOnClose} is set to false for the active window. You can use this option only in conjunction with -h or -h2, which display the keyword in the form

Look up… "key"

where key is the keyword.

-nf

Inhibits filtering field tags from the data. The Get tool retrieves the information exactly as it appears in the data file.

-q

Suppresses the error message "### key NOT found."

-s

Selects key from the current selection in the active window. If there is no selection, Get selects the text that the insertion cursor is in or near.

Use this option only if you have placed Get in a script executed from a menu.

-search

Searches the data file for all occurrences of the keyword specified by -k and lists all other keywords whose records contain that keyword.

Note
The Get tool searches only the first data file listed. •

-sfl

Produces an ordered list of the requested data files when you use -dfl listFile.

-t

Retrieves only a template of the function or procedure requested. When used in conjunction with -s, this option replaces the selected text with the template.

-width w

Specifies the window width w (from 1 to 200) in which a keyword list is displayed. This option applies only when you request a list of keywords explicitly by specifying -field KL or implicitly by using -l or -search.

-x

Builds or rebuilds a cross-reference index file, which indexes every word in the data file for rapid retrieval. Get automatically creates an index file, which allows rapid retrieval of information by specific keywords. If a cross-reference index file does not already exist, Get builds it; if it is merely out of date, Get rebuilds it.

Note
Get can take a long time to build the cross-reference index file. •

-y

Builds the index file automatically if it is out of date or missing. Normally a dialog appears asking you whether the index file should be built.

EXAMPLES

The example below prints a list of all keywords in the data file MPWHelp that begin with the letters "ad":

Get MPWHelp -k ad -l

When executed, the command produces the following list:

AddMenu
AddPane
Adjust

The following command line builds or rebuilds the cross-reference index file for NewHelpFile.WIndex if it is out of date or missing.

Get NewHelpFile.WIndex -k sin -x

In another example, the information retrieved by the keyword sin is formatted by the following command:

Get CIncludesHelp -k sin -field Fc,D ∂
-format "The file is: %sThe declaration is: %s"

The output from the command is:

The file is: Math.h
The declaration is: extended sin (extended x);

The following paragraph is an example of text marked with the special tags recognized by Get:

æKY  How Get Operates

æC  How Get Operates

When the Get tool is executed, it first retrieves
the byte offset of a keyword from the index file,
positions to the keyword line in the help file, and
then reads all of the following lines until another
keyword line is encountered. Get then outputs the
record, after first removing the field tag codes
from each field.

æR  How Get Operates

See the 411 Release Notes

LIMITATIONS

If you use -k, and the keyword key is also the name of one of the data files specified in the -dfl listFile option, that data file is moved to the top of the list in listFile.