1 09/30/85  process_list, pls
  2 
  3 Syntax as a command:  pls list_path {form_path} {-control_args}
  4 
  5 
  6 Function: produces a document from all or selected records in a lister
  7 file.  The format of the document is defined in a listform file (see
  8 listform_segment.gi).  You can print the document on your terminal or
  9 save it in a segment.
 10 
 11 
 12 Arguments:
 13 list_path
 14    is the pathname of the lister file to be processed.  The suffix
 15    lister must be the last component of the lister file name; if you
 16    don't give it, it is assumed.
 17 form_path
 18    is the pathname of the listform file that defines the format of the
 19    document.  If it does not have the suffix listform, one is assumed.
 20    If you don't give it, the listform file in your working directory
 21    that has the same entryname as list_path is used, with the suffix
 22    lister changed to listform.  You can use the archive component
 23    convention.
 24 
 25 
 26 Control arguments:
 27 -arguments STR, -ag STR
 28    indicates that the listform segment requires arguments.  If present,
 29    follow it by at least one argument.  All arguments following it on
 30    the command line are taken as arguments to the listform segment;
 31    thus, make it the last control argument on the command line.
 32 -brief_errors, -bfe
 33    suppresses warnings about missing or extra arguments for -arguments
 34    or when you select no records.
 35 -extend, -ex
 36    specifies that the document produced by pls be appended to the
 37    segment indicated by path (also give -of).  (Default: to replace
 38    path completely)
 39 
 40 
 41 -output_file {path}, -of {path}
 42    specifies that the document produced by pls be saved in the segment
 43    given by path.  If you don't supply path, the output segment is
 44    placed in your working directory with the same entryname as
 45    form_path and the suffix listform changed to list.
 46 -select STR, -sel STR
 47    specifies the records selected for processing.  If you don't provide
 48    it, all records in the list are processed (see "Notes on selection
 49    expressions" below).
 50 
 51 
 52 -sort "STR", -st "STR"
 53    sorts the records processed according to STR (in quotes).  Sorting
 54    is in effect only for the duration of the command.  The lister file
 55    is not modified.  If you don't use -sort, records are processed in
 56    the current order in the lister file (see sort_list.info).
 57 -totals, -tt
 58    displays the number of records processed.
 59 
 60 
 61 Notes on selection expressions: The selection feature enables any of
 62 the list processing commands copy_list, describe_list, display_list,
 63 modify_list, process_list, and trim_list to select from a lister file
 64 only the records it will act on.  The command, using -select,
 65 specifies requirements for desired fields.  If a record meets the
 66 requirements, it is processed; otherwise it is skipped.
 67 
 68 The -select control argument always takes a character string (STR)
 69 argument.  Surround STR with quotation marks.  Each record in the
 70 specified lister file is tested to determine whether or not it
 71 fulfills the selection criteria.  Those that do are processed.
 72 
 73 
 74 This control argument consists of one or more field comparisons.  A
 75 field comparison involves comparing a test string with the value of
 76 the specified field in the current record.  The field comparison
 77 statement always consists of three parts:
 78    "field_name comparison_operator test_string"
 79 where
 80 field_name
 81    is the name of a field contained in the lister file.  You can use
 82    the reserved field names ":any" to specify any field in the record
 83    and ":uid" to specify the unique identifier of a record.  (See
 84    below.)
 85 comparison_operator
 86    specifies what comparison is performed.  The opposite comparison is
 87    performed if you precede the comparison operator by "not."  The list
 88    processing comparison operators are:
 89 
 90 
 91    begin(s)
 92       field value begins with the test string.  The comparison is made
 93       regardless of case.
 94    contain(s)
 95       test string is contained in the field value.  The comparison is
 96       made regardless of case.
 97    end(s)
 98       field value ends with the test string.  The comparison is made
 99       regardless of case.
100    equal(s)
101       test string is equal to the field value.  Uppercase and lowercase
102       letters are distinct with this operator.
103    greater
104       field value is alphabetically greater than the test string (e.g.,
105       0123456789Aa...Zz).
106 
107 
108    less
109       field value is alphabetically less than the test string.
110    nequal(s)
111       field value string is numerically equal to the numeric value of
112       test string.
113    ngreater
114       field value string is numerically greater than the test string.
115    nless
116       field value string is numerically less than the test string.
117 
118 
119 test_string
120    is the string that is compared to the field value string.  The
121    special test string ":null" is used to verify whether or not the
122    field is null (i.e., missing from the current record) and the
123    special test string ":numeric" to test whether or not the field
124    value string is numeric (i.e., can be converted to a number).  You
125    can only use them with the equal or nequal comparison operators.
126    Null fields are always nonnumeric.  (See below.)
127 
128 You can specify several field comparisons with -select.  Field
129 comparisons are combined by the logical operators "and," "or," or
130 "not."  With no parentheses the prefix "not" operator is evaluated
131 first, then the infix "and" operator, then the infix "or" operator.
132 You can use parentheses to specify the exact order of evaluation.
133 These rules are similar to the PL/I ones for Boolean expressions.
134 
135 
136 The comparison operators (not) begin, (not) contain, (not) end, (not)
137 greater, (not) less, (not) ngreater, and (not) nless ignore records
138 that have null fields.  Unless you use ":null", (not) equal and (not)
139 nequal also ignore records with null fields.
140 
141 For lists of field names and test strings, see listin_segment.gi and
142 listform_segment.gi; for examples of the use of -select, see the
143 Multics WORDPRO Reference Manual (AZ98).
144 
145 
146 Notes on severity: pls sets the "lister" severity indicator.  Severity
147 2 is set when the document is not produced due to some failure other
148 than no match on the selection expression or if the pls invocation
149 terminates abnormally.  Severity 1 is set when the document is not
150 produced due to no match on the selection expression.  Severity 0 is
151 set when the program terminates normally and the document is produced.