Opentext Pat 5.0 Manual

changes the file name used by save.commands and exec.

The CommandFile setting determines which file the save.commands command writes to and the exec command reads from. It has a default value of pat.cmd. If the string begins with a numeral or contains blanks or non-alphanumeric characters, it must be enclosed within double quote marks. The file name must also conform to the file naming conventions of the host operating system. It can be changed at any time during a PAT session and remains in effect until changed again or until the end of the session. The current value of CommandFile is displayed by the command {Settings}.

marks the start of a comment.

The comment, that is the # and the rest of the line following the #, is ignored by PAT. The comment can be placed on a line by itself or following a PAT query. It is useful for annotating queries stored in a file to be processed in batch mode or to be read in by the exec command. The queries may be created externally or generated during a PAT session and saved by save.commands for later use.

determines which region set is the current default.

The DefaultRegion setting designates a special region set, known as the default region. The default region can be referred to as region without specifying the actual region name. The setting can be changed at any time during a PAT session and remains in effect until it is changed again or until the end of the session.

If the string giving the setting value begins with a numeral or contains blanks or non-alphanumeric characters it must be enclosed within double quote marks.

Using the default region in a command, without having previously specified one, is illegal and results in the following message.

No information for region in the data dictionary

removes members from a set.

The difference operator (-) creates a new set containing the members of set1 that are not members of set2. Set1 and set2 can be either point sets or region sets. The new set is of the same type as set1.

If either set1 or set2 is a region set, the first pointer delineating each region is used to determine if a member of set1 also occurs in set2. Thus, for set arithmetic (difference, union and intersection) in PAT, set members of a region set are considered to be equal if they start at the same location in the text. The end point of a region is ignored in such operations.

terminates a PAT session.

The done command ends the session and causes the PAT process to exit. A message may be generated telling how much computer time has been used during the session.

allows the use of strings that include special characters.

Normally, PAT interprets a sequence of characters as a string and searches the database for matches to it. However, there are certain types of strings that PAT cannot recognize as search targets unless they are enclosed within double quote marks. The special strings are: strings which begin with a numeral, for example 2nd; strings which contain blanks or non-alphanumeric characters, for example end of the year or <Author>Scott; and strings which are PAT commands, for example near and within. In each case, a string that is not enclosed in double quote marks but should be will result in a syntax error or unexpected result.

Note that if numbers are not enclosed in double quote marks, they are interpreted as a reference to the number of a set previously calculated in the PAT session.

A pair of quotes representing an empty string ("") stands for the set of all index points in the text being searched.

reads a file into a PAT session and executes the commands contained in the file.

The name of the file read by the exec command is determined by the value of the CommandFile setting. By default, the value is pat.cmd but can be changed at any time during the PAT session.

The exec command can be used to enter queries to a PAT session. The queries, for example macro definitions, may be recorded in a file using an editor or saved in a file from a previous PAT session using save.commands.

saves information about sets created in a PAT session.

Export writes a detailed description of the members of set1, created during a PAT session, to a file. The description includes the type (region or point) of the set and sufficient information to recreate a copy of the set. The name of the file is determined by the value of the ExportFile setting. By default the file name is pat.exp but can be changed during a session by using the command ExportFile. When export writes to the named file it writes over anything that may currently exist in the file. Assuming a default ExportFile setting of pat.exp, the following message is given:

Exporting to pat.exp.

The file may subsequently be read into a PAT session by the import command.

If the saved set is a frequently used region set, it can be made available as a predefined region in future PAT sessions by editing the data dictionary file and adding the appropriate information. If the new region set, containing 150 regions, is named newregion and saved in the file newregion_file, the following lines, added to the data dictionary, would make it available to PAT.

<Region>
 <Name>newregion</Name>
 <Desc>This new region set describes ....</Desc>
 <File>
  <SysName>newregion_file</SysName>
  <Offset>0</Offset>
 </File>
 <Count>300</Count>
 <Type>pairs</Type>
</Region>

changes the file name used by export and import.

The ExportFile setting determines the file written by the export command and read by the import command. It has a default value of pat.exp. If the string begins with a numeral or contains blanks or non-alphanumeric characters, it must be enclosed within double quote marks. The file name must also conform to the file naming conventions of the host operating system. It can be changed at any time during a PAT session and remains in effect until it is changed again or until the end of the session. The current value of the ExportFile setting is displayed by the command {Settings}.

finds members of sets that occur close to each other in a specified order.

Fby (followed by) creates a set containing those members of set1 that have one or more members of set2 within a specified number of characters to their right . Set1 and set2 may be either point sets or region sets. The new set is of the same type as set1.

The distance between members of the two sets is calculated by counting the number of characters in the text from the first character of a member of set1 to the first character of a member of set2. The measure used to determine closeness is the value of the Proximity setting which has a default value of 80 characters. This can be changed for all subsequent uses of fby by changing the Proximity setting, or it can be changed for an individual use of fby by using a modifier attached to the command. The form of the modifier is a period followed by a number representing the maximum distance (in characters).

If either set1 or set2 is a region set, the first of the two pointers delineating the region is used to determine the distance between the set members.

Multiple fby commands are not parsed left to right. A command of the form

       set1 fby set2 fby set3

is handled as if parenthesized as follows:

       set1 fby (set2 fby set3)

The command not fby creates a set containing the members of set1 that are not within the specified distance to the left of any member of set2.

       set1 not fby (set2 fby set3)

is the same as

       set1 - (set1 fby (set2 fby set3))

finds a specific number of contiguous members from the start of a set.

First creates a set of a specified size which is comprised of members from the beginning of set1. The members of the new set are in the order they appear in set1. Set1 may be either a region set or a point set. The new set is of the same type as set1.

The operation of the first command involves the set member counter that keeps track of the selected members, the identification of the size of the requested set, and the SortOrder setting that determines which members are in the new set.

First selects members from the beginning of a set. The ordering of a set, and hence which members occur at the beginning, is controlled by the SortOrder setting. If the SortOrder setting is Alpha, the set is ordered alphabetically. If the SortOrder setting is Occur or OccurHead, the set is ordered according to occurrence in the text. If the SortOrder setting is AsIs, the set order is the current one which may be either alphabetic or occurrence order.

Each set that is used with a first, next or ~nextemp command has a cursor (set member counter) associated with it. The cursor indicates the location in set1 at which to start selecting members for the set being created. Each first command resets the cursor so members for the new set are chosen from the beginning of set1. On completion of the first command the cursor is updated to point at the beginning of the next set. Note, when the SortOrder setting changes and the set ordering is changed, the cursor is reset to the beginning of set1.

The size of the set created is determined by the value of SampleSize which has a default value of 10. If the size of set1 is less than SampleSize then the new set created is the same size as set1. Changing the SampleSize setting affects all subsequent uses of first during the current session. For an individual use of the command, the size of the new set can be specified by using a modifier attached to the first command. This modifier is in the form of a period followed by a numeric value giving the desired set size.

The first command can be used by itself or with the pr, save or export commands.

releases a PAT set.

Following the ~free command, the set number is no longer available for reference in a PAT command. The set is no longer displayed by the history command.

If the sets freed are at the end of the current history list, the set numbers will be reused for the next sets created in the PAT session. For example, if the history list contains set numbers 1 to 8, and 6 through 8 are freed using the ~free command, the next set number assigned is 6. However, if set number 2 is freed and the history list includes set numbers 1 to 8, the next set is number 9.

releases all PAT sets.

Following the ~freeall command, all the sets that existed in the current session are no longer available for reference in a PAT command. In addition, those sets are no longer displayed by the history command.

Following the ~freeall, the next set number assigned is 1.

displays the record of the current PAT session.

Information about each set created during the PAT session is recorded in a history list. For each of the sets, history displays a set number, the number of members in the set and the query that produced the set. Sets created during the current session can be accessed by referring to the number of the set in the history list. The results of pr, save, Settings, { }, and certain tilde (~) commands do not appear in this list since no sets are produced by these commands.

As the entire history list may become quite long, it is useful to be able to view only a part of the list. The History setting determines what portion of the history list is displayed by the history command. The History setting has a default value of 0. This indicates that the entire history list is to be displayed. When set to an integer n (any integer greater than zero) the final n elements in the history list are displayed by any subsequent use of the history command during the session.

The items listed can also be changed for an individual use of the history command. Modifiers may be attached to the history command to request that a certain number of items and that a particular portion of the list be displayed.

The first modifier, in the form of a period followed by a number, indicates where in the history list to begin the display. A positive integer p requests that the display start at the pth item from the start of the history list. A negative integer p requests that the display start at the pth item from the end of the history list. The number of items displayed is the value of the History setting.

The number of items displayed can also be changed for an individual use of the history command by using a second modifier attached to an already modified history command. This second modifier is also in the form of a period followed by a number giving the number of items to be displayed.

The default maximum size of the history list is 300 items. If more than 300 sets are created the last 300 sets created during this PAT session are retained in the list. This maximum size can be altered by a command line parameter when starting a PAT session.

Note that a set can be removed from the history list by the ~free command.

changes the number of items from the history list displayed by the history command.

The History setting determines the number of items displayed by the history command. Note that the setting may be overridden and the number of items displayed determined by a modifier for an individual use of the history command. The default value of the setting is 0 indicating that all sets created in this session are to be shown by the history command. The setting can be changed at any time during a PAT session and stays in effect until changed again or until the end of the session. The current value of the History setting is displayed by the command {Settings}.

changes the file name used by save.history.

The HistoryFile setting determines the file written by the save.history command. It has a default value of pat.his. If the string begins with a numeral or contains blanks or non-alphanumeric characters, it must be enclosed within double quote marks. The file name must also conform to the file naming conventions of the host operating system. It can be changed at any time during a PAT session and remains in effect until it is changed again or until the end of the session. The current value of the HistoryFile setting is displayed by the command {Settings}.

reads information that has been saved in a file by the export command.

Import reads data from a file and creates a new set which can be used as if it had been created during the current PAT session. PAT determines from the header information whether the saved set is a point set or a region set, and the new set is of the same type. The file read is determined by the ExportFile setting which has a default value of pat.exp. The file name can be changed during a session by resetting the ExportFile setting.

Assuming the default setting of ExportFile, if the imported set is a region set, the following message is generated:

Importing regions from 'pat.exp'

If it is a point set, the message generated is:

Importing point set from 'pat.exp'.

set1 incl set2

find regions that contain members of a set.

Including or incl creates a set comprised of members of set1 that include one or more members of set2. Set1 must be a region set. Set2 may be either a point set or a region set. The new set is a region set.

Set1 may be a predefined region set, a region set created during the PAT session using the region command, a region set resulting from the use of the import command, or the result of a previous query in the session.

If set2 is a point set, and if one or more of the points occur in a region from set1, then that set1 region is included in the new set.

If set2 is a region set, and the first of the pair of pointers (offsets into the text) describing a region of set2 is contained in a region of set1, that set1 region is included in the new set. The second pointer of the pair delineating set2 does not have to fall within the region of set1 in order that the set1 region be included in the new set.

The including command can also be used to find regions that contain more than one member of set2, by attaching a modifier specifying the minimum number of members of set2 to the including command. This modifier is in the form of a period followed by the value of the minimum number of members.

The command not including creates a set containing those members of set1 that do not contain any of the members in set2.

 set1 not including set2 

is the same as

 set1 - (set1 including  set2) 

Including and within are similar in that they both restrict searches to specified regions in the text. They differ in the set that is created. The including command creates a set of regions that contain one or more members of another set, while within creates a set of pointers or regions that are contained in members of a region set.

The PAT index is made up of the starting points of each string. The index points make up the possible match points for a string search. Parameters set when the index is built determine which strings are in the index. The parameters specify patterns in the text that define the beginnings of strings to be indexed. For example, one pattern could specify that every character in the text is to be indexed, while another pattern could specify that each printable character following a blank is to be indexed.

When the index is created, two additional settings can alter how PAT sees the text. Character mappings cause PAT to see certain characters as equivalent to other characters. For example, all upper case letters may be mapped to lower case letters so that PAT does not distinguish between upper and lower case when searching for a string. Also, some words may be designated as stopwords. PAT views the text as if these words are not there. PAT ignores strings in the text that start at an index point and match the given stopword strings followed by a blank after the character mappings have been applied. The character mappings also affect the strings chosen to be index points. For example, if a > is mapped to a blank and if the index points are defined as blanks followed by printable characters, in the text ...<tag>wisdom... the w in the string wisdom is an index point. Text with character mappings applied and stopwords removed is referred to as converted text.

When searching for a given string, a match is found if the given string (after having the character mappings applied to it and the stopwords removed) is the same as the converted text that begins one of the indexed strings.

finds members common to two sets.

The intersect operator (^) creates a new set consisting of the members in set1 that are also in set2. Set1 and set2 can be either point sets or region sets. The new set is of the same type as set1.

If either of set1 or set2 is a region set, only the first of the pointers describing the region is used in the comparison to determine if a member should be included in the new set. Two members of a region set are considered to be equal if they start at the same location in the text.

specifies an identifying string to be used as a label.

When PAT is operating in quiet mode with labels requested, any set displayed by a pr or save command shows the label string preceding the numeric value of the text offset. This can be used to identify which database the information is from. In a PAT session, if a value for Label has not been set by this command, the default value used is the name of the data dictionary. The label string must begin with an alphabetic character and contain no blanks or non-alphanumeric characters. The setting can be changed at any time during a PAT session and remains in effect until it is changed again or until the end of the session.

refers to the previous result.

% is used as shorthand to refer to the set created most recently in the PAT session. The set is the final one in the current history list. Some commands, such as pr and save, do not create sets that are saved and recorded in the history list and thus cannot be accessed by using the %. If there is no history, the last set is the null set which contains all index points.

specifies how many characters of context are displayed to the left of a set member.

By default, when a set is displayed with the pr command or written to a file by the save command, the text has 14 characters to the left of the match point. The setting can be changed at any time during a PAT session and remains in effect until it is changed again or until the end of the current session. The current value of the LeftContext setting is displayed by the command {Settings}.

A macro can be defined in a PAT session and be available only for the duration of that session, or a macro can be created externally and read into any PAT session by an exec command or during initialization.

The definition of a macro (here called name) begins with the following:

After this line the system prompt changes from >> to || for the duration of the macro definition. The body of the macro may begin on the same line or on a subsequent line. PAT interprets anything immediately following the word macro, that is not a blank or new line, as the beginning of the macro definition. The body of the macro may contain arguments. The nth argument to the macro is identified within the macro definition by the string $n$. Any sets that are created by the macro may also be used in its definition. The string *n* refers to the nth set created within the macro. The end of the macro definition is indicated by a @. After the @ the system prompt returns to the form >>.

References to other macros may be used within the definition of a macro. If the macro contains more than one PAT query, they can be put on separate lines or on the same line with the queries separated by a semi-colon. The body of the macro is not checked for syntax errors when it is defined. Any errors are reported when the macro is used.

The macro is invoked by the following call:

If the number of arguments in the macro call is less than the number in the macro definition a syntax error is reported. If it is greater, the extra arguments are ignored.

Each argument consists of all the text occurring between argument delimiters: parentheses and commas. That is, if a macro takes three arguments - (arg1,arg2,arg3) - arg1 consists of the text between the opening parenthesis and the first comma, arg2 consists of the text between the first and second comma, and arg3 consists of the text between the second comma and closing parenthesis. If a macro takes only one argument - (arg1) - the parentheses are the argument delimiters. Note that any spaces entered with an argument string will be included with the parameter substitution which is unlikely to be the intent of the user. To avoid unexpected results, enter only the exact text that you wish to be substituted in the arguments of the macro call. Also note that macros may have no arguments.

When the macro is invoked, the invocation is replaced by an exact copy of the body of the macro with the arguments substituted for the formal parameters. This means that the macro can be used within other PAT queries. This may require that the macro definition have the closing @ on the same line as the final line of the body of the macro definition to avoid introducing an unwanted new-line character.

If improperly used, macros that produce multiple sets and are used within other queries may cause more than one syntax error to be reported. Care must be taken with bracketing in order to ensure that the results reflect what was actually intended.

A macro can be redefined during a PAT session. When the macro is redefined, the previous definition of the macro is displayed following the first new line entered after the word macro. The format of this previous definition consists of the macro name followed by a colon, followed by the body of the macro on subsequent lines.

For convenience, macros that are used frequently can be defined within an init file whose location is given in the data dictionary file. The init file is read and executed by a PAT session when it is initially started. (See the data dictionary documentation for details.)

assigns a name to a set.

A set which has been named can be referred to either by that name or its set number. Set1 can be either a point set or a region set.

A name that starts with a letter and contains only letters and numbers does not need to be enclosed within double quote marks. However, if the name contains special characters (blanks or non-alphanumeric characters), or does not start with a letter, it must be enclosed within double quote marks both in the assignment statement and in subsequent use.

To use the name in a query it must be preceded by an asterisk (*). Without the asterisk (*), PAT interprets the name as a string rather than as the name of a set.

finds members of sets that are close to each other.

Near creates a set containing the members of set1 that are within a specified number of characters before or after one or more members of set2. Set1 and set2 may be either point sets or region sets. The new set is of the same type as set1.

The distance between members of the two sets is calculated by counting the number of characters in the text between the first character of a member of set1 and the first character of a member of set2. The measure used to determine closeness is the value of the Proximity setting which has a default value of 80 characters. The value can be changed for all subsequent uses of near by changing the Proximity setting, or it can be changed for an individual use of near by using a modifier attached to the command. The form of the modifier is a period followed by a number representing the maximum distance (in characters).

If either set1 or set2 is a region set, the first of the two pointers describing the region is used in finding the distance between the members of the sets.

Multiple near commands are not parsed left to right. A command of the form

       set1 near set2 near set3 

is handled as if parenthesized as follows:

       set1 near (set2 near set3)

The command not near creates a set containing those members of set1 that are not within the specified distance of any member of set2.

 set1 not near set2 

is the same as

 set1 - (set1 near set2) 

finds a specified number of contiguous members of a set following members already identified by a first or next command.

Next creates a set of a specified size containing the members of set1 that start at the current cursor position associated with this set. The cursor position is determined by a previous first or next command applied to set1. The members of the new set are in the order they appear in set1. Set1 may be either a region set or a point set. The new set is of the same type as set1.

The operation of the next command depends on the set order established by the SortOrder setting. If the SortOrder setting is Alpha, the set is ordered alphabetically; if the SortOrder setting is Occur or OccurHead, the set is ordered as the members occur in the text; and if the SortOrder setting is AsIs, the set ordering is the current one and may thus be either alphabetic or occurrence order.

Each set that is used with a first, next or ~nextemp command has a cursor (set member counter) associated with it. The cursor indicates the location in set1 at which to begin selection for the set being created. On completion of the next command the cursor is updated to point at the beginning of the next set. Note, when the SortOrder setting changes and the set ordering is changed, the cursor is reset to the first element.

The size of the set created is determined by the value of SampleSize which has a default value of 10. If the size of set1 is less than SampleSize, then the new set created is the same size as set1. Changing the SampleSize affects all subsequent uses of next during the current session. For an individual use of the command, the size of the new set can be specified by using a modifier attached to the next command. The modifier is in the form of a period followed by a numeric value giving the desired set size.

The next command can be used by itself or with the pr, save or export commands. Note that next may only be used in conjunction with these commands.

finds a specified number of contiguous members of a set following members already identified by a first or next command.

The command ~nextemp creates a set of a specified size containing the members of set1 that start at the current cursor position associated with the set. The cursor position is determined by the previous first or next command applied to set1. The members of the new set are in the order they appear in set1. Set1 may be either a region set or a point set. The new set is of the same type as set1.

The ~nextemp command is identical to the next command except that the cursor is unchanged by the ~nextemp command.

The operation of the ~nextemp command depends on the set order established by the SortOrder setting. If the SortOrder setting is Alpha, the set is ordered alphabetically; if the SortOrder setting is Occur or OccurHead, the set is ordered as the members occur in the text; and if the SortOrder setting is AsIs, the set ordering is the current one and may thus be either alphabetic or occurrence order.

Each set that is used with a first, next or ~nextemp command has a cursor (set member counter) associated with it. The cursor indicates the location in set1 to start selecting members for the set being created. After completion of the ~nextemp command, the cursor is unchanged. This differs from the behaviour of the next command, which updates the cursor to point at the last member of set1 selected for the new set. Note, when the SortOrder setting and the set ordering change, the cursor is reset to the first element.

The size of the set created is determined by the value of the SampleSize setting which has a default value of 10. If the size of set1 is less than SampleSize, then the new set created is the same size as set1. Changing the SampleSize setting affects all subsequent uses of ~nextemp during the current session. For an individual use of the command, the size of the new set can be specified by using a modifier attached to the ~nextemp command. This modifier is in the form of a period followed by a numeric value giving the desired set size.

The ~nextemp command can be used by itself or with the pr, save or export commands. Note that ~nextemp may only be used in conjunction with these commands.

The forms in which not can appear are not fby, not including, not near, and not within. These uses are described in the entries for fby, including, near, and within. Not cannot be used to modify any other commands.

[label:number]

generate a point set containing a specified position in the text.

The number in the square brackets is a logical position in the text and need not be an index point. The number indicates the offset, measured in number of characters, from the beginning of the text database. The first character of the text has offset [1]. If the number used in square brackets exceeds the size of the text PAT gives the message

Error: Input number too large.

Note that the new set is a point set with only one member.

The second form of the command, shown above, uses offsets that are produced when PAT is operating in quiet mode and using labels. In this form, in order to produce correct results, the label string must be the current value of the setting Label. When the label is different from the current Label setting the resulting set has size 0.

displays contents of PAT sets.

Pr displays each member of set1 with surrounding context. A modifier can be attached to the pr command in order to control the context exactly. Set1 can be any region set or point set. If set1 is a region set, the first of the pair of points describing each region in the text is displayed by the pr command. If no set1 is given, the operand for the command is the most recent set created in the session.

For each member in the given set, the output is in the form of an integer giving the offset of the set member in the text file, followed by a comma, a blank, two periods and then the characters surrounding the set member. The first character in the database is considered to be offset 1. The order in which the set is displayed depends on the current SortOrder setting.

With no modifier, pr prints a line of text for each element in set1. The PrintLength and LeftContext settings determine the content of the line printed. With the default settings, the printed text is 64 characters in length of which 14 precede the match point. The number of characters displayed to the left of the match point can be altered by changing the LeftContext. The total number of characters printed can be altered by changing the PrintLength setting.

The total number of characters to be displayed can be set, for a single instance of the command, by using a numeric modifier attached to the pr. The modifier is in the form of a period followed by a number giving the total number of characters to be displayed. The left context that is displayed is still determined by the value of the LeftContext setting.

The second form the modifier can have is a period followed by the string region. When the modifier .region is used, the output text starts at the match point and continues to the end of the default region in which the match point occurs. If the match point is not within the default region, no output is displayed for the match point.

The second form of the modifier can be refined to request that the text displayed is a region other than the default region. An additional modifier specifying a defined region set can be attached to the already modified pr command (i.e. to the pr.region). The additional modifier can specify the region in one of three ways: a string giving the name of a predefined region, the number of a region set created in the PAT session, or a string preceded by an asterisk (*) referring to a named region set defined in the PAT session (see the examples below). As with the form pr.region, described above, this use results in the displayed text starting at the match point with no left context and continuing to the end of the region. When the match point is not contained in the designated region set, no output is displayed.

specifies how many characters of text are displayed.

By default, when the members of a set are displayed with the pr command or written to a file by the save command, each member contains 64 characters of context, 14 to the left of the match point, the match point itself, and 49 to the right. This setting may be overridden so that the number of characters processed is determined by a modifier for an individual use of the pr or save commands. The PrintLength setting determines the total number of characters processed and thus affects the number of characters shown to the right of the match point. The number of characters to the left of the match point is determined by the LeftContext setting.

The setting can be changed at any time during a PAT session and remains in effect until changed again or until the end of the session. The current value of the PrintLength setting is displayed by the command {Settings}.

specifies the measure of closeness for the near and fby commands.

The Proximity default for the fby and near commands is 80 characters. That is, a match point of a member of set1 must be within 80 characters of a match point of a member of set2 to be included in a new set created by the near and fby commands.

The Proximity setting may be overridden for an individual use of the fby and near commands by appending a modifier to the command.

The Proximity setting can also be changed at any time during a PAT session and remains in effect until changed again or until the end of the session (see example below). The current value of the Proximity setting is displayed by the command {Settings}.

outputs a query number.

The ~qnum command operates in both standard and quiet mode. In standard mode, the number of the next query is output. In quiet mode, the information is tagged and the number of the next query is contained within <Qnum> tags.

{QuietOff}

changes the mode of operation of PAT. {QuietOn} causes PAT to operate in quiet mode. {QuietOff} causes PAT to revert to standard (non-quiet) mode.

Each of the four arguments to QuietOn is optional and may appear in any order. When an argument is present in a QuietOn command, the corresponding setting is turned on. Conversely, when an argument is not present in a QuietOn command, the corresponding setting is turned off. Settings are not carried forward from one QuietOn command to the next but are reset with each QuietOn command.

All PAT commands that create sets operate the same way in quiet mode and in standard mode. However, the output generated by PAT is different in the two modes. No prompt or newline appears when PAT is operating in quiet mode. In addition, the output from PAT in quiet mode is in a tagged format.

In standard mode, when a command or query creates a new set, a set number and the number of matches is output. In quiet mode, the tagged output contains the number of matches within <SSize> tags but no set number. For example, if a set of 122 matches is created by a PAT query the output is of the form:

<SSize>122</SSize>

In standard mode, information displayed about a set by a pr command is affected if a modifier is attached to the command. The output from a pr command is preceded by the offset in the text of the set member being printed. If the set is a region set, the offset is the start of each region in the set. In quiet mode, the output contains the numeric offset in a tagged format. The settings of Raw, Converted, Label and Persistent affect the information displayed by the pr command. Each of the settings is discussed below.

{QuietOn}

With Persistent turned off, the values of the offsets that are output are the logical offsets into the file. The logical and persistent offsets are different and non- interchangeable. Persistent offsets are designed for use with the update system. (See the documentation for the PAT update system.)

If the pr command is not of the form pr.region, the offset of each set member is contained within <Start> tags and the entire output is contained within <PSet> (for Point Set) tags. For example, if the set is of size 2, the output might look as follows (without the line breaks).

<PSet><Start>1234</Start>
<Start>5554</Start></PSet>

If the modifier to the pr command is .region, in standard mode the text displayed is from the match point to the end of a specified region. In quiet mode, the tagged output contains both the offset of the match point and the offset of the end of the specified region. The offsets of the ends of the region are contained within <End> tags and the entire output is contained within <RSet> (for Region Set) tags. For example, for the above set of size 2, output from a pr.region might look like

<RSet><Start>1234</Start><End>1444</End>
<Start>5554</Start><End>6000</End></RSet>

{Quiet On Label}

When Label is turned on, the form in which the offset is printed changes. The numeric value of the offset into the text within the <Start> or <End> tags is preceded by an identifying label and a colon. This label string is the value of the Label setting. If Label has not been set, the label used in the output is the name of the data dictionary file up to the first non-alphanumeric character. For example, if the data dictionary is news.dd and Label has not been set, the output from a pr command would look like:

<PSet><Start>news:1234</Start>
<Start>news:5554</Start></PSet>

{QuietOn Raw }

When Raw is turned on, in addition to the tagged offsets, the output contains text showing the match point and surrounding context. For each member of the set, this additional information is output within <Raw> tags following the tagged offset information for each member of the set.

The length of the string being output is given within <Size> tags and is followed by the text. As in standard mode, if pr has no modifier, the length of string output is determined by the PrintLength setting and the context shown to the left of the match point is determined by the LeftContext setting. If the modifier is a numeric value, this value determines the length of the string and the left context is still determined by the LeftContext setting. If the modifier to the pr command is .region, the text starts at the match point and continues to the end of the specified region.

For example, assuming a PrintLength setting of 25, and a LeftContext setting of 5, the output from a pr command applied to a set of 2 matches to the string sample would be (without the line breaks shown here):

<PSet><Start>1234</Start><Raw><Size>25</Size>
This sample is to be firs</Raw>
<Start>3456</Start>
<Raw><Size>25</Size>
This sample is to be seco</Raw>
</PSet>

If the SortOrder setting is OccurHead, in addition to the above output, the descriptive header is output in a tagged format. (See the entry for SortOrder for a description of the header). This information is contained within <Hdr> tags and includes the length of the descriptive string within <Size> tags followed by the string of the header. If the SortOrder setting was OccurHead in the above example, the output would be (without the line breaks shown here):

<PSet><Start>1234</Start>
<Hdr><Size>10</Size>First     </Hdr>
<Raw><Size>25</Size>
This sample is to be firs</Raw>
<Start>3456</Start>
<Hdr><Size>10</Size>Second    </Hdr>
<Raw><Size>25</Size>
This sample is to be seco</Raw>
</PSet>

{QuietOn Converted}

When Converted is turned on, in addition to the tagged offsets, text following the match point is output for each member of the set. This text is displayed with the appropriate character mappings for the PAT index and any stopwords removed. For example, if upper case is mapped to lower case when creating the index, the text is displayed in lower case. If the index has the word to as a stopword, to would not appear in the converted text.

For each member of the set, this additional information is output within <Cvt> tags. The length of the output text string is enclosed within <Size> tags and is followed by the text itself. For each set member, the text string shown starts at the match point. This is in contrast to the Raw text output which shows the match point with some left context. If the pr has no modifier, the length of the string is determined by the PrintLength setting. If the modifier is numeric, this determines the string length. If the modifier is .region, the length of the string is the value of the difference between the offsets of the match point and the end of the region. As the displayed text is converted text, it is possible that some text conversions cause output, such as multiple blanks resulting from character mappings or stopwords, to be suppressed. This may result in text that occurs past the end of the region to be displayed.

For example, using the above example of a set of size 2 and further assuming that to and be are stopwords the output might be:

<PSet><Start>1234</Start>
<Cvt><Size>25</Size>
sample is first used for </Cvt>
<Start>3456</Start>
<Cvt><Size>25</Size>
sample is second used for</Cvt>
</PSet>

If the SortOrder setting is OccurHead, in addition to the above output, the descriptive header is given in a tagged format. (See the entry for SortOrder for a description of the header). The information giving the descriptive string precedes the <Cvt> tag and does not have the character mappings applied to it. The previous example would change to:

<PSet><Start>1234</Start>
<Hdr><Size>10</Size>First                   
  ..<Cvt><Size>25</Size>
this sample is first used</Cvt>
<Start>3456</Start>
<Hdr><Size>10</Size>Second                  
  ..<Cvt><Size>25</Size>
this sample is second use</Cvt>
</PSet>

{QuietOn Persistent}

When Persistent is turned on, the offsets that are output are the persistent (persistent) positions within the text database. As noted earlier, in a database that has not been initialized for update, the persistent and logical offsets are identical.

{QuietOn Raw Converted Label}

Any combination of the QuietOn arguments may be used. Thus, after the command {QuietOnRaw Converted Label}, the following would result:

<PSet><Start>news:1234</Start>
<Raw><Size>25</Size>
This sample is to be firs</Raw>
<Cvt><Size>25</Size>
sample is used first for </Cvt>
<Start>news:3456</Start>
<Raw><Size>25</Size>
This sample size is to be seco</Raw>
<Cvt><Size>25</Size>
sample is second used for</Cvt>
</PSet>

The save command results in identical behaviour to that of the pr command except that the information is written to a designated file rather than displayed on the standard output.

Syntax errors that occur during the PAT session are reported in a tagged format. A set size of -1 is indicated and the error information is contained within <Error> tags. For example, if a command uses the default region before it is set, the error shown is (without the line breaks shown here):

<SSize>-1</SSize>
<Error>No information for default region
</Error>

Although the sets created by the signif command are the same in quiet and standard mode, signif does not display the text string associated with the set in quiet mode. If signif is modified with a negative integer n requesting n sets, only information about the last set created is shown.

History and {Settings} display no output in quiet mode.

terminates a PAT session.

The use of the quit command causes the session to end and the PAT process to exit. A message may be generated telling how much computer time has been used during the PAT session.

finds strings that begin with strings occurring within an alphabetic range.

The range operator creates a point set consisting of those indexed points in the text that fall alphabetically between string1 and string2 inclusive. String1 and string2 are patterns that may or may not actually occur in the text being searched. The resulting set contains the matches to both string1 and string2.

Both the operands to the range command must be strings. Using a set number with the range command is illegal and results in a syntax error.

ranks a region set by the number of contained members of another set.

Rankedby creates a set containing those members of set1 that contain the greatest number of occurrences of members of set2. Set1 must be a region set. Set2 may be either a point set or a region set. The new set is a region set.

Set1 may be a predefined region set, a region set that has been created within the current PAT session using the region command, a region set resulting from the use of the import command, or the result of a previous query during the current session.

The size of the new set is by default the value of the SampleSize. Another size may be requested with a numeric modifier in the form of a period followed by the requested size.

The set that is created, when accessed by pr, save and subset in SortOrder AsIs, is naturally ordered by rank. That is to say, the first member will be that element of set1 that contains the most occurrences of members of set2.

In detail, the rankedby command operates as follows. It first splits all the members of set1 into groups. Each member of a group includes the same number of members of set2 as the other members of the group. In addition, within a group, the members are sorted into occurence order. After it has grouped the members of set1, the rankedby command sorts the groups into decreasing order of number of included members of set2.

For example, say that set1 has 6 members, as follows: 3 members that each contain 2 members of set2, 2 members that each contain 4 members of set2, and 1 member that contains no members of set2. After rankedby has grouped and sorted set1, the groups are be as follows. The first group consists of the 2 members of set1 that contain 4 members of set2. The second group consists of the 3 members of set1 that contain 2 members of set2, and the third group consists of the 1 member of set1 that contains no members of set2. Within each group, the members are in occurence order. If the user has requested the top 4 sets, the result set would contain both members of the first group and the first two members of the second group.

region string

region set1 .. set2

produce region sets in a text database. The first two forms of the region command refer to region sets that have been defined externally to a PAT session and for which information is available in the data dictionary. These region sets may have been defined using patregion or any other program that generates information (in the form that PAT understands) about regions in the text. The third form of the command defines a region set during a PAT session. The results of any of these commands can be used as operands to any of the PAT commands that operate on region sets.

region

Region, used with no operand, refers to the particular predefined region set that has been designated as the default region. The default region is defined by the DefaultRegion setting and can be reset for the remainder of a PAT session by changing the setting. If no default region has been defined, using region in this form causes an error. The following message is generated:

No information for default region.

region string

The second form of the region command indicates one of the named predefined region sets. The string is the name that has been given to the region set in the data dictionary. For example, the region sets might be the chapters of a book, the entries in a dictionary or the headlines in a newspaper database. The information about certain regions in the text database is generated by a program external to PAT and is made available during a PAT session via the data dictionary. One program that generates the information is patregion.

Note that the string giving the name of the region set can contain blanks or special characters, if it is enclosed within double quote marks.

region set1 .. set2

The third form of the region command defines a new region set. The region set that is created by this command is only available for the duration of the PAT session. Information about this region set can be written to a file using the export command and read into a future PAT session using the import command.

Set1 and set2 are used to define regions in the new set. Set1 and set2 can be either point sets or region sets. If either set1 or set2 is a region set, the region command uses only the first of the pair of pointers describing its members in defining the new region.

Each region in the new set is formed as follows. A member of set1 is the beginning of a region if it is followed by a member from set2 with no other member of set1 occurring between the two members. The end point of the new region is defined by the member in set2 that most closely follows the set1 member. The region contains the text from the beginning of the member of set1 up to but not including the member of set2. This produces the smallest non-overlapping region set that can be formed by set1 and set2. The size of the region set created is equal to or smaller than the size of set1. If the members of set2 are matches to a pattern, the new region set does not contain the occurrences of that pattern. For example, if set2 is the set of matches to the string End of Message, the new region set contains no occurrences of the string End of Message.

If set1 and set2 are identical, two extra regions may be included in the newly created set. These are: a region from the beginning of the text to the member of set1 that occurs earliest in the text; and a region from the last element of set1 in the text to the end of the text. If either of these regions is a substring of length zero, it is not included. If the shift command is applied to set1 or set2, the extra regions are not included in the new set.

Some programs, such as patregion, that produce predefined region sets, define the end point of the region in a somewhat different manner. These programs deal with patterns of text (rather than points in the text) and the end point of the region that is defined is usually the last character in the pattern that is used to define the regions. If desired, the region command within a PAT session can be used in conjunction with the shift command to create a set of regions in which the ends of the regions are at the end of a pattern. See the examples below.

PAT does not support region sets whose members nest or overlap. As described above, using region with operands that are patterns defining nested or overlapping regions, creates a region set which is the smallest non-overlapping set of regions. Patregion used on the same text creates a possibly different region set (also non-overlapping) consisting of regions from an opening pattern to the following end pattern.

finds representative members of a larger set.

Sample creates a set containing a specified number of members of set1. Set1 may be either a region set or a point set. The new set is of the same type as set1.

The size of the set created is determined by the value of the SampleSize setting which has a default value of 10. If the size of set1 is less than SampleSize, then the new set created is the same size as set1. The size can be changed for all subsequent uses of sample during the current session by changing the SampleSize setting. For an individual use of the sample command, the setting can be changed by using a modifier attached to the command. The form of the modifier is a period followed by a number giving the desired size of the sample set.

The members of the sample set are chosen as follows. If the size of set1 is x and the sample size requested is y, each x/yth member of set1 is in the sample set. For example, if a sample of size 20 is requested from a set of size 2000, the 100th, 200th members etc. are chosen. The ordering of the set, and hence the members of the sample set, is determined when the set is created. The SortOrder setting does not determine which members are included in the set created by the sample command as it does for the subset, next, ~nextemp, and first commands. However, this setting does affect how the sample set is ordered when used with a pr command (or save command).

The sample command can be used by itself or with the pr, save or export commands. The sample may only be used in conjunction with these commands.

specifies the size of the set produced by the sample, subset, and rankedby commands.

By default, sample and subset create a set of 10 members of a given set. This setting may be overridden and the size of the result determined by a modifier for an individual use of these commands. The SampleSize setting can be changed at any time during a PAT session and remains in effect until changed again or until the end of the session. The current value of the SampleSize setting is displayed by the command {Settings}.

writes the contents of a set to a file.

The save command is identical to the pr command except that the output is written to a file. The name of the file where the information is written is determined by the value of the setting SaveFile. The default value of the setting is pat.res. The file used by the save command can be changed at any time during the PAT session by changing the setting. The information output by the save command is concatenated onto the end of the save file if one of the same name already exists. Otherwise, a new file is created and the information is written to the new file. Assuming the default setting of SaveFile, the following message is printed on execution of the save command:

Saving in pat.res.

For each member in the given set, the output is in the form of an integer giving the offset of the set member in the text file followed by a comma, a blank, two periods and the characters surrounding the set member. The order in which the set is output is determined by the current SortOrder setting.

With no modifier, Save outputs a line of text for each element in set1. The PrintLength and LeftContext determine the content of the line saved. With the default settings, the saved text is 64 characters in length of which 14 precede the match point. The number of characters to the left of the match point can be altered by changing the LeftContext setting. The total number of characters printed can be altered by changing the PrintLength setting.

The total number of characters to be saved can be set for a single instance of the command, by using a numeric modifier attached to the save command. The modifier is in the form of a period followed by a number giving the total number of characters to be saved. The left context that is saved is still determined by the value of the LeftContext setting.

The second form the modifier can have is a period followed by the string region. When the command save.region is used, the output text starts at the match point and continues to the end of the default region in which the match point occurs. If the match point is not within a default region, no output is saved for the match point.

The second form of the modifier can be refined to request that the text output be in a region other than the default region. An additional modifier, specifying a defined set of regions, can be attached to the already modified save command (i.e. to the save.region). This additional modifier can be in one of three forms: a string giving the name of a predefined region, the number of a region set created in the PAT session, or a string preceded by an asterisk (*) referring to a named region set defined in the PAT session. As with the form save.region, described above, this use results in the output text starting at the match point with no left context and continuing to the end of the region. When the match point is not contained in the designated set, no output is saved.

The similarly named commands save.commands and save.history result in very different behaviour and are described in separate entries.

writes information to a file about the queries in the PAT session. These are saved in a form that allows them to be used in another PAT session.

Save.commands saves, in a file, all the queries that have been executed and have produced sets during the current session. These are the queries that appear in the history list. Only the command is saved in the file, not the set number or number of matches. The setting CommandFile, that determines the file where the information is written, has a default value of pat.cmd. The output file can be changed at any time during the session by changing the CommandFile setting. If a file of this name already exists, the information is concatenated onto the end of the file. Otherwise a new file is created.

The saved information can be read into a PAT session and executed using the exec command.

changes the file name used by save.

The SaveFile setting determines the file written by the save command. It has a default value of pat.res. If the string begins with a numeral, or contains blanks or non-alphanumeric characters, it must be enclosed within double quote marks. The file name must also conform to the file naming convention of the host operating system. It can be changed at any time during a PAT session and remains in effect until it is changed again or until the end of the session. The current value of the SaveFile setting is displayed by the command {Settings}.

writes information to a file about the queries and results in the current PAT session.

Save.history writes a record of a PAT session. PAT's history list records information about all queries that produce sets. For these queries, save.history saves the set number, the number of members in the set, and the query that produced the set in a file. The setting HistoryFile, that determines the file where the information is written, has a default value of pat.his. A different output file can be chosen at any time during a session by changing the setting. If a file of this name already exists, the information is concatenated onto the end of the file. Otherwise a new file is created. Note that comments are saved only if they are on the same line as the command itself.

refers to a named set.

Query result sets may be named and subsequently referred to either by set number or by name. The name must be preceded by an asterisk (*) to reference the set; otherwise, PAT interprets the name as a command or search string.

references a previously created set.

After the first query in a session, PAT displays a line of the form:

1: 300 matches

The number 1 here names the set of results and can be used in subsequent searches. The valid set numbers are those displayed by the history command.

When an invalid set number is used PAT generates a message. If, for example, set number 33 is referenced before it has been calculated or after it has been freed the message is:

Expression 33 is out of range

These sets can be used as operands in subsequent queries. In contrast to the conventional approach of a single, nested compound query, PAT allows complex queries to be expressed as a series of simple queries. This provides an opportunity to try alternative ways of combining previous result sets to arrive at a solution. PAT provides a history list of all previous sets created in a session and a convenient notation to access them.

A member of a point set is a location in the text which is the start of a string that continues to the end of the text. The PAT system finds locations in the text where strings, matching pattern(s) given in the query, begin. The members of a point set are usually index points, however, in the sets created by shift or offsets, (the notation [n]), the members refer to positions in the text that may or may not be index points.

The members of a region set are substrings of the text, beginning and ending at specified points. Region sets that are the result of a query within a PAT session are available only for the duration of the session. However, region sets can also be defined externally and be made available to the PAT session. Each member of a region set is described by two locations in the database, indicating the start and end of the region and these locations may or may not be index points.

Region sets may be used in PAT to restrict searches to desired parts of the text. The within command finds the members of a set that are contained in a designated region set. The including command finds the members of the designated region set that contain one or more members of a given set.

The sets produced within PAT can be refined using set arithmetic or proximity commands. The difference (-) and intersection (^) commands remove members of an existing set. The proximity (fby and near) commands reduce sets by finding the members of a given set that have specified text close by.

In addition to refining sets, it is possible to combine two sets to create a larger one by using the union (+) command.

PAT queries, applied to a text database, may create large sets; analyzing a smaller, representative subset might aid in making decisions about how to proceed appropriately with a search. Several commands in PAT provide this capability. Sample creates a representative subset while subset, next, and first each create contiguous smaller subsets of a larger set.

shows the current values of a number of PAT parameters.

creates a point set whose members are a specified distance from a set of matches.

Shift creates a new set whose members are locations in the text which result from an equal shift being applied to all members of set1. Set1 may be either a point set or a region set. If it is a region set, the resulting set is a point set containing the first of the pair of pointers describing each member of the set. The set created by the shift command is always a point set.

The shift command creates a new set consisting of pointers that are (by default) 10 characters after the original set members. The set created is in occurrence order. This default shift distance (10) and direction can be changed by using a modifier attached to the shift command. The modifier is of the form of a period followed by a positive or negative integer. If the modifier is a negative integer n, each member of set1 is shifted to n characters before the original location. If it is a positive integer n, the shift is to n characters after that location.

The points in the new set need not be index points.

finds frequently occurring words or phrases in the text.

Signif finds the most frequent words or phrases following the text matching set1. Set1 can be either a point set or a region set for the first two forms of the command but has a restriction, as noted below, for the third form of the command. The set (or sets) created are point sets. If set1 is not given, signif uses the last set produced as its operand.

The signif command looks for words or phrases, in contrast to the other PAT commands that operate on points and regions. For signif, a word is defined as a string of characters ending either in a blank or a character that has been mapped to a blank by the character mappings used in building the index being used in the current PAT session.

The signif command examines the words or phrases that begin with a string. The string used is the longest string common to the text pointed to by each of the members of set1. If set1 is a point set resulting from a string search, signif starts with that string. If set1 is not given and the previous result was from a signif command, the string is the one associated with the set created. (Note that, in addition to the number of matches in the set, signif returns a string value.) If set1 is a region set, the first of the pairs of pointers describing the regions are used to find any common string beginning in these regions. For example, this might be the pattern used to define the regions. If set1 is a point set that is not the result of a string search, PAT checks for a common string beginning the text pointed to by each member of set1. In some cases, this common string is the null (empty) string.

Signif has three different modes of operation. A modifier can be attached to the signif command. The syntax of the modifier is a period followed by an integer n.

The first mode of the command, signif with no modifier, finds a frequent word or phrase and then, by reapplying signif to the resulting set, may be used to extend this phrase. In this mode, the command finds the string and then finds all possible extensions, in the text, of this string up to the next blank. Signif creates the set, among the matches to these possible extensions, with the most members.

The second mode of the command, signif with a positive integer n as modifier, finds the most commonly occurring phrase of length n words beginning with the string. The set created contains those members of set1 that are the matches to the most frequent phrase beginning with the given string that is at least n words in length.

The third mode of the command, signif with a negative integer n as modifier, creates n sets which are the matches to the n most frequent phrases beginning with the string. This use of the signif command is restricted to sets matching a string or a set created by a range command. Using any other set as an operand is illegal and results in the error message:

Repetitive signif should be on strings or ranges only

Note that the set created by signif is identical to that created by signif.-1 but not necessarily to the one created by signif.1.(See the examples.)

The displayed output from the signif command gives the number of matches and the word or phrase found (preceded by text=). The text is shown with the character mappings applied and stop words removed (see data dictionary documentation). For example, this means, if > has been mapped to a blank and the word the is not a stopword, one would see the following:

  >> signif  "<HL>"
    2: 604 matches, text=<hl the

determines the ordering of a set.

The behaviour of first, next, pr, save, subset and ~nextemp are affected by the ordering associated with their operands. The SortOrder setting indicates whether these sets are to be treated in alphabetical order or in the order that members of the set occur in the text (occurrence order). (A SortOrder setting of OccurHead (explanation below) also determines what is displayed by the pr and save commands.)

Every set in PAT has an internal ordering which varies from set to set, as described below. The ordering is chosen by PAT, for reasons of efficiency, and no assumptions can be made in this regard. It is often desirable, however, to present results in a certain order, and the SortOrder setting exists to control this. When a set is an operand of a pr or save command or a new set is created by a first, next, subset or ~nextemp command, the ordering of the set and hence the behaviour of the command is determined by the SortOrder setting. This may mean that the existing set must be reordered for processing with these commands. For some PAT commands this results in a change in the internal ordering, and this change is reflected when subsequently operating with a SortOrder setting of AsIs (explanation below). The ordering of a set that is not an operand to one of the above commands is not affected when the SortOrder setting changes.

The permissible values for the SortOrder setting are AsIs, Alpha, Occur and OccurHead. The default value of SortOrder is AsIs. If the SortOrder setting is AsIs, the set is processed in the order in which it currently exists. If the SortOrder setting is Alpha, the set is processed in alphabetical order. If the SortOrder setting is Occur or OccurHead, the set is processed in occurrence order. For sets whose internal ordering is not alphabetical, for example region sets, displaying results with a SortOrder setting of Alpha will require resorting which may result in additional computation delay depending on the set size.

Setting the SortOrder setting to Occur results in further changes to the behaviour of the pr and save commands. For Pr and save, with a SortOrder setting of AsIs, Alpha or Occur, the position offset for each set member is displayed. With a SortOrder setting of OccurHead, the contents of a named region set are output in place of the position offset. Setting SortOrder to OccurHead requires reference to two regions within the brace brackets used to change the SortOrder setting. The first region referenced is the one whose contents are displayed in place of an offset when members of a set are displayed. The second region referenced must be one that contains both the match points of the members of a set and the first region referenced in the SortOrder setting (OccurHead).

The text displayed in place of the offset, as a result of SortOrder being set to OccurHead, is the first region found of the specified type within the containing region (also specified in the OccurHead setting). If the text to be displayed begins with an opening angle bracket, the text until the closing angle bracket is ignored and the next character is displayed. If the next character is another angle bracket, the preceding process is repeated iteratively. A maximum of 10 characters or up to the next < in the text is displayed. Both these region sets, named in the OccurHead setting, must be in the data dictionary. If they are not, for example if X is named in the setting but does not exist in the data dictionary, the following error message results:

No information for region X in the data dictionary

The SortOrder setting can be changed at any time during a PAT session and remains in effect until it is changed again or until the end of the session. The current value of the SortOrder setting is displayed by the command {Settings}.

terminates a PAT session. The use of this command causes the session to end and the PAT process to exit. A message may be generated telling how much computer time has been used during the PAT session.

A command consisting only of a string causes PAT to search for occurrences of the string in the text database. A set is created whose members are matches to all index points in the text that begin with the given string. A match occurs when the given string (after having the character mappings applied to it and stopwords removed) is the same as the text that begins at an index point (also having had the character mappings applied and stopwords removed). Searching for phrases with a PAT index is as fast as searching for a word or a prefix of a word. After a search, the number of matches to the pattern is displayed, but the results of the search are not shown unless requested by a pr command.

finds a number of contiguous members of a set.

Subset creates a set of a specified size containing members starting at a designated location in set1. The members of the new set are in the order they appear in set1. Set1 may be a region set or a point set. The new set is of the same type as set1.

The operation of the subset command is affected by the size of the set requested and the SortOrder setting.

The ordering of a set, and hence which members are chosen to be in the set created by the subset command, is controlled by the SortOrder setting. If the SortOrder setting is Alpha, the set is ordered alphabetically; if it is Occur or OccurHead, the set is ordered as the members occur in the text; and if the SortOrder setting is AsIs, the set order is the current one and may thus be either alphabetic or occurrence order. The location within set1 to start selecting members for the new set is indicated by a numeric location in the ordered set. This numeric location is given to the subset command as a modifier attached to the command. The modifier is in the form of a period followed by an integer that can be either positive or negative. A positive integer gives the desired location relative to the beginning of the set and a negative integer gives it relative to the end of the set. Without any modifier the subset is taken from the start of set1.

The size of the set created is determined by the value of the setting SampleSize which has a default value of 10. If the size of set1 is less than SampleSize, then the new set created is the same size as set1. Changing the SampleSize setting affects all subsequent uses of subset during the current session. The size of the subset can be specified for an individual use of the command by using a second modifier attached to the already modified subset command. This modifier is also of the form of a period followed by a numeric value giving the desired set size.

The subset command can be used by itself or with the pr, save or export commands. The subset may only be used in conjunction with these commands.

outputs a tagged identifier.

The command ~sync is available only when the PAT session is operating in quiet mode. ~sync outputs a message tagged with Sync tags containing the given string. This command is mainly used when PAT is integrated into a more complex system. The output from the ~sync command can then be used to identify a position in an input stream when information is being received from several different sources.

For example, if many searches of a database involve finding references in the text to money in different currencies, the thesaurus provides the capability to define a variable describing all the possible patterns to be used in these searches.

The thesaurus variable is defined in a file named in the data dictionary. Within the thesaurus file, each separate variable, called a word, is surrounded by <Entry> tags. Within the <Entry> tags are other tagged areas: the name of the variable is contained within <Word> tags, followed by the associated query contained within <Query> tags. The thesaurus capability is implemented using macros so the query may be a complex one creating more than one set. The same cautions, described for macros, apply to bracketing and syntax errors.

To invoke a thesaurus variable the name is preceded by the character <. For example, a thesaurus variable named money may be used within a PAT session as follows:

As with macros, thesaurus invocations are replaced by an exact copy of the definition. This means that a thesaurus variable can be used as an operand in other PAT queries. Note, however, that it may be necessary to bracket the entire invocation in order to ensure correct results from the query. In practice, bracketing the definition itself is a good general method.

If an undefined thesaurus variable is used, for example <testing, the following error message is generated.

The macro testing is undefined

combines two sets.

The union operator (+) creates a new set containing the members of both set1 and set2, with duplicates removed. Set1 and set2 can be either point sets or region sets. If either of set1 or set2 is a point set the new set is also a point set.

If both set1 and set2 are region sets and there is no overlap or nesting of any member from set1 and any member from set2, the union set is a region set. If overlap or nesting occurs, set1 and set2 are treated as point sets by using the first of each pair of pointers describing the regions in the sets. The new set created is the union of these point sets. The following message is generated when this occurs:

Warning: Addition of Region objects produced a region
with overlaps -- simplified into a point set

Note that if both set1 and set2 are region sets and a member of set1 coincides exactly with a member of set2, this is not considered to be an instance of overlap or nesting; rather, these members are considered identical and only one will be a member of the output set.

finds members of a set within a given region.

Within creates a set containing those members of set1 that are located in one of the regions of the text described by set2. Set1 may be either a point set or a region set. Set2 must be a region set. The new set is of the same type as set1.

Set2 may be a predefined region set, a region set that has been created within the PAT session using the region command, a region set resulting from the use of the import command, or the result of a previous query in the session.

If set1 is a point set, each member is examined to see if it falls within a region from set2 in order to determine inclusion in the new set. If set1 is a region set, the first of the pair of pointers (offsets into the text) describing each member is examined to see if it falls within a region of set2. The second pointer of the pair does not have to fall within a region of set2 for the region to be included in the new set. That is to say, if set1 and set2 are both region sets and they overlap, members of set1 are included in the result of within if they begin within a member of set2.

The command not within creates a set containing those members of set1 that are not in any of the regions described by set2.

 set1 not within set2 

is the same as

 set1 - (set1 within set2) 

Including and within are similar in that they both restrict searches to specified regions in the text. They differ in the set that is created. The including command creates a set of regions that contain one or more members of another set, while within creates a set of pointers or regions that are contained in members of a region set.