Display part of an authority term's hierarchy
You can use the AU_USER_SYM_HIERARCHY subroutine in a complex User Symbolic to report on hierarchical authority files at a particular level. For example,
Subroutine name
AU_USER_SYM_HIERARCHY
Field type
Examples of use
You could report on the Place file at Nation level or report on the Classification file at Species level. If no term is found at the specified level, the subroutine will continue up the hierarchy until a term is found. You set the limit for when it should stop looking.
For example, you may only want to display the country an object was made in, not the city or suburb. So instead of seeing:
Morningside/Auckland/New Zealand
You would just see:
New Zealand
Argument syntax and parameters
The subroutine is a piece of code that uses ‘arguments’. An argument is a set of options that tells the subroutine what to do. The argument parameters are commonly separated by an exclamation mark.
The AU_USER_SYM_HIERARCHY subroutine argument structure is:
auth.fmc!auth.mv!auth.file!level.codes
What the argument parameters mean
| Argument parameter | Required or optional? | Explanation |
|---|---|---|
| auth.fmc | Required | The Field Mark Count (FMC) of the field to extract authority terms from. |
| auth.mv | Optional | For multi-value authority fields, set to 0 to only process the first authority term, 1 to process all terms (default) or F to find first relevant data. |
| auth.file | Required | The System ID of the authority file that controls the auth.fmc field. |
| level.codes | Required | Go up the hierarchy until a term has one of these hierarchical levels. System IDs of hierarchical levels should be separated by '~'. For example, ID1~ID2~ID3. Leave blank to indicate only Top Terms are to be returned. |
| limit | Optional | Stop looking at this level. That is, do not display terms at this level or above. Enter the System ID of the hierarchical level. |
| display.field | Optional | Conversion field. For example, show AU_ASCENDING for the term found. |
| auth.conv.file | Optional | Additional default authority conversion. For example, display.field may be AU_TAXONOMIC_LEVEL. Set auth.conv.file to CLASSIFICATION_TAX to convert the level to a name (CLASSIFICATION_TAX is the System ID of the Classification Level authority file). |
| level.count | Optional | Go up the hierarchy a maximum number of levels. For example, 1 will just show the current term and its next higher term. |
| display.fld2 | Optional | The second display field will be shown in brackets beside the first. If the field is authority controlled, then specify the conversion in display.fld2.conv. Use this if you have a field in a foreign language for which you would like the translation to display in brackets next to the term. For example, a product name in French with the English translation in brackets. |
| display.fld2.conv | Optional | Conversion for the second display field. |
| display.fld2.mv | Optional | If the second display field is multi-valued, set to 0 to only include the first term from display.fld2. |
Example of subroutine argument
This argument has been configured for the Classification field in the Object file. When reporting on natural science specimens, it will display the classification at Species level. If no species is entered, it will display the genus instead. If no Genus level term is entered, it will display the family. Terms at Order level and above will be ignored. That is, if no species, genus or family is found, the symbolic result will be null.
56!!CLASSIFICATION!LIN.SPE~LIN.GEN~LIN.FAM!LIN.ORD
