NOTE
Use of these commands is not recommended as they are no longer officially supported and may not work as intended.
Description
List Issues based on search criteria
Syntax (following correct mrFile)
The program is the equivalent of the SQL select statement. Under SQL–based databases, mrList.pl, mrFast, or mrQuick (which are synonyms for the same program) all act as front ends for the “select * from table where” of a SQL database. Under the built–in FootPrints database, mrList.pl command has a syntax described in detail below.
Note
The first argument to mrQuick (the query) must be in double quotes and the second argument, the page number, starts at 0 and not 1.
Details for SQL based versions of FootPrints
The mrList.pl, mrQuick, mrFast commands for FootPrints using SQL–based systems (SQL–server, Access, Oracle, MySQL, or Postgres) are front ends to the select command of the underlying database used to store the FootPrints database whose issue number is less than 20:
mrList.pl “mrID < 20”
this is equivalent to:
select * from MASTER1 where mrID < 20
or:
mrList.pl “mrPRIORITY = 2 and mrSTATUS = CLOSED”
is equivalent to:
select * from MASTER1 where mrPRIORITY = 2 and mrSTATUS = CLOSED
A working knowledge of SQL language is required to use the mrList.pl/mrQuick/mrFast commands. A full layout of the FootPrints tables is defined in the ODBC table definition section of the manual and the help for assistance in running these commands.
Details for FootPrints built built–in database
mrList.pl with no query following it returns a list of every Issue in the database. A FootPrints query consists of two parts, either or both of which may be omitted. The first part is a range specification, and the second is a logical expression. Each part serves to constrain the set of Issues on which to reported.
A range specification is either a single number or a pair of integers separated by "–" or "to." It is okay to specify an ending number greater than the highest Issue number. The highest existing Issue number is used. Here are some examples:
|
Command |
Action |
|
mrList.pl 46 to 53 |
returns Issues 46 to 53 |
|
mrList.pl 5 |
returns Issue 5 |
|
mrList.pl 23 – 93 |
returns Issues 23 to 93 |
|
mrList.pl 47 to 99999 |
returns Issues 47 and up |
If you are also going to specify a logical expression, connect the range specification and the logical expression with the word "where".
For example:
Logical expressions describe other constraints on which Issues are to appear in mrList.pl. There are many types of these, as follows.
Description fields are queried using the keywords "description contains". For example, to return a list of Issues with the word "hello" in the description, you would type:
Title searches are constructed using a similar grammar, but using the keyword "summary" instead. For example, to return a list of Issues with the word "FootPrints FootPrints" in the title, you would type:
Important
The use of single quotes, double quotes and slashes is very important. On NT, if you do not type a "\" before the double quotes surrounding the string, the search fails.
Remember that NT queries are protected by double quotes, so that quotes protecting strings within queries must be escaped.
You may include Issues in a report based upon their current priority. You may use any of the numeric relational operators (<, <=, =, !=, >=, or >).
Examples (given here for NT only):
mrList.pl "priority > 3"
mrList.pl "priority <= 100"
mrList.pl "priority != 5"
You may include Issues in a report based upon their current status. Use any of the relational operators (<, <=, =, !=, >=, or >) to compare against other statuses. These statuses are Workspace–specific and are named in the Life.cycle ($CMMASTER/MR/Life.cycle) file. The earlier the status is mentioned in the Life.cycle file, the less its value. If you are getting syntax errors, make sure you check the Life.cycle file to see what FootPrints calls your status. For example, the status "upside down" might be stored as "upside__bdown."
Examples of queries:
status > Open
status = Closed
You may refer to the previous status the Issue had, like this:
previous status > Open
In fact, you may refer to the history of any status using the word "previous" as many times as necessary:
previous previous previous status > Open
If you use "previous" too many times and go back through more statuses than the Issue has had, FootPrints excludes it from the report.
You may include Issues in a report based upon the user ID that originally created the Issue. You may use any of the relational operators (<, <=, =, !=, >=, or >) to compare against user IDs.
Examples:
originator = suzy
originator != george
Assignee
You may include Issues in a report based upon one of the user IDs, which have been assigned to work on them.
Example:
assigned to dan
Unassigned
To include Issues in a report based upon the absence of anyone having been assigned to work on them, simply place the word "not" in front of "assigned."
Example:
not assigned
You may include Issues in a report based upon the date the Issue was created. You may use any of the relational operators (<, <=, =, !=, >=, or >) and the keywords “Issue date” to compare against a constant date in mm/dd/yy format.
Examples:
Issue date = 5/10/92
Issue date < 3/5/91
You may include Issues in a report based upon the date the Issue last changed. Use any of the relational operators (<, <=, =, !=, >=, or >) and the keywords “date of status” to compare against a constant date in mm/dd/yy format.
Examples:
date of status = 5/10/92
date of status < 3/5/91
You may refer to the date previous to the current one like this:
date of previous status < 3/5/91
In fact, you may refer to any status date previous to that one by using the word "previous" as many times as necessary:
date of previous previous status < 3/5/91
If you use "previous" too many times and go back through more statuses than the Issue had, FootPrints excludes it from the report.
You may include Issues in a report based upon the age of the Issue (how many days ago it was entered). You may use any of the relational operators (<, <=, =, !=, >=, or >) and the words “age of Issue date” to compare against a constant integer.
Examples:
age of Issue date > 30
age of Issue date < 7
Logical expressions may be combined with "and" and "or." You may use parentheses to force evaluation.
Examples:
priority > 2 and age of Issue date > 30
(age of Issue date > 30 or age of previous status > 30) and priority = 3
You may also use the "not" operator to negate a condition:
not priority = 3
You may sort the report by any combination of these criteria:
|
To sort by |
Use this term |
|
Issue number |
mr |
|
current priority |
priority |
|
Issue date |
Issue date |
|
originator |
originator |
|
current status |
status |
You may prefix a sort name by the word "ascending" or "descending." The default sorting order is ascending, so you need not use it except for clarity.
Examples:
order by descending priority
order by originator
All unclosed high–priority Issues that have been unresolved for over a month:
mrList.pl "priority > 5 and status < Closed and age of Issue date > 30 order by descending priority"
All Issues assigned to george, ordered by priority:
mrList.pl "assigned to george order by descending priority"
NOTE
When you run the mrList.pl command, you must protect the "<" and ">" signs from the shell by either escaping then with a back–quote or by quoting the entire query.
See Also