name

The name of this parameter (as displayed to the user in the Parameter Entry screen).

field

The field name for this parameter, including the table name where necessary to avoid ambiguity, apart from:

·         when type=”VagueDate”, the field attribute should only supply the prefix used for the three fields that represent the vague date in the database – i.e. without the suffix VAGUE_DATE_START, VAGUE_DATE_END, or VAGUE_DATE_TYPE.

·         When type=”SpatialRef”, the field attribute should only supply the prefix used for the five fields that represent the spatial reference in the database – i.e. without the suffixes LAT, LONG, or SPATIAL_REFERENCE, SPATIAL_REFERENCE_QUALIFIER or SPATIAL_REFERENCE_SYSTEM.  In many cases the field will be empty (or just contain the alias and full stop, e.g. “S.”), except for examples such as the SW and NE spatial references attached to SURVEY records.

operator

The text name of the comparison operator to be used – one of “equal”, “not equal”, “like”, “less than”, “greater than”, “less than equal” or “greater than equal” (required unless type=”CSVFile”, when the SQL IN operator is always used).  The actual symbols for the operators themselves cannot be used since < is illegal in an XML attribute value. 

If the operator is “like” then the type must be set to “text”, in which case an SQL like query is used with a wildcard added to the end.  If the user types a * into the parameter then this is converted to a wildcard (%).

type

The data type of this parameter (one of Text, Number, Date, VagueDate, TrueFalse, CSVFile (not working), OptionSet, Location, Name (= either an individual or organisation), Individual, Organisation, Taxon, BoundingBox, GridSquareRange, SpatialRef, LocationsInPolygon, SamplesInPolygon).  If type= “VagueDate”, “Location”, “Name”, “Individual”, “Organisation”, “Taxon”, “BoundingBox”, “GridSquareRange”, “SpatialRef” or “TrueFalse” the only valid operators are “equal” and “not equal” and for the dates the report includes or excludes respectively all records that have dates overlapping with the vague date supplied at run time, not just exact matches.  If type=”LocationsInPolygon” or “SamplesInPolygon” then the operator, SubstituteFor and entrycount is ignored. For these types, the condition creates a clause of format WHERE field IN (‘key1’, ‘key2’, …) where the keys are a list of the samples or locations found within the map polygons selected by the user on the Parameter Entry screen.

includepartialoverlap

Ignored unless the type is SamplesInPolygon or LocationsInPolygon. Possible values are “true“ (default) and “false”. If true, then an OSGB grid square is included in the report results if inside or overlapping the polygon, otherwise its only included if inside the polygon.

entrycount

Optional attribute.  If “1” (default) then only a single instance of the parameter entry control is available on the report parameters entry screen.  If greater than 1 then the data entry control is repeated n times allowing multiple entries to be made.  The report SQL generated uses an IN (…) or NOT IN (…) clause to implement the query.  If a value of “-1” is used then the number of parameter data entry controls can be controlled by the user – add and delete buttons allow them to add and remove controls from a list on the screen allowing a flexible number of parameter entries to be created.

If this value is not “1”, then the only valid operator is “equal”. 

userucksack

Optional attribute, only used when entrycount=-1 and type is one of Taxon, Location, Individual, Organisation, Name. Allowed values are “yes”, “no” and “optional”. Default value if not specified is “no”.

Defines if the parameter entry screen obtains the list of values for this condition by loading a saved rucksack (value=yes), by allowing the user to enter individual values on the screen (value=no), or by allowing the user to select between these 2 methods on the parameter entry screen (value=optional).

selectoneofgroup

Optional attribute.  If specified, then any other conditions with the same value in this attribute are grouped together.  For each grouping, there are radio buttons on the parameter entry screen and only one parameter of the group can be active at any one time.

For example, a report’s default where clause defines 2 parameters using conditions with selectoneofgroup=”spatial”.  The first parameter is a spatial reference, the second a bounding box.  In this case the user is able to specify either a bounding box or a spatial reference as a report filter, not both.

datatype

The type of the data for this parameter – one of “Text”, “Number” or “Date” (only relevant to CSVFile parameters, since their contents must be converted to a string suitable for including in an SQL IN clause, with strings and dates delimited using the appropriate characters).

SubstituteFor

This attribute defines a piece of text which is used in the defined SQL and should be substituted with the value of the parameter throughout.

For example if the SQL says:

Select {0}, taxon_list_item_key from Index_taxon_name

And the SubstituteFor parameter is set to {0}, then whatever is entered as the value for this parameter will be substituted. If the Paramter type is text and the value entered is ‘My Records’, then the SQL executed would be

Select ‘My Records’, taxon_list_item_key from Index_taxon_name

If the SubstituteFor text appears more than once it is substituted in ALL cases. SubstituteFor is free text; therefore SQL keywords and Field Names (unless intentional) should be avoided.

<Option>

<Option> tags are only required if Type= “OptionSet”, when each <Option> tag specifies the name and value for one option in the list of possible choices.