User Valuelist Support in MARC Report

Note:This section describes a more direct method of validating against a user-supplied valuelist.
The previous method for doing this, using MARC Review, is still supported.

Valuelists have been a part of MARC since the beginning. Prominent examples are the codes that we enter into the 008 for Country of publication and Language. The usage of many similar “code lists” can be found in the variable fields as well (for example, the $2 subfield often used to indicate the “source of a term”).

Valuelists are useful for limiting the content of a data field to a finite number of choices. Since the content has been pre-defined, data entry is easier, consistent, and less prone to error; while at the same time, the results of automation applied to the data, such as search filtering, will be greatly improved.

User-defined valuelists are supported in MARC Report beginning with version 25x.

Two text files are required to setup user valuelist validation, and these files must reside in the '\lists' subdirectory of 'Documents\MarcReport'. Each file will contain several tab-delimited columns as described below. A program like Excel is a good choice for maintaining such data, provided that the 'Save As Type' is set to Text (tab-delimited) when saving the file.

The first required file is a 'map' file, which must be named 'myValuelistMap.txt'. This file will map each valuelist defined by the user to a MARC Tag and subfield. At present, up to 25 rows are supported.

The second required file contains the actual values and/or codes that the program will validate against. Typically each entry in the 'map' file will link to one or more rows (up to 500) in the valuelist file. This file must be named 'myValuelists.txt'.

In addition to these text files, an option will need to be enabled in the program itself to turn on support for user-defined valuelist validation. This option is at the bottom (right) of the Validation page of the main options:

When this option is checked, the program will quickly check whether the required data files (described below) are present. If they are, the option will be enabled; otherwise a pop-up will advise that a file is missing and that this page should be consulted.

The 'myValuelistMap.txt' file contains 4 columns:

1. A three-digit MARC tag followed by one subfield code (no spaces)
2. The name of the valuelist (no spaces)
3. '0' –the use for this column may be defined later
4. '0', or a note to be displayed to the user when validation fails

The purpose of the map file is to link each valuelist defined by the user to a MARC content designator.

Here is a brief example of a valuelist map:

  This line would be considered a comment as it does not begin with a tag
  // As would this. 
  521a	myList_1	0	The term should match an entry in myList_1.
  690a	myList_2	0	The term should match an entry in myList_2.
  690z	myList_2	0	The term should match an entry in myList_2.

Notes about the map

Column headers are not used in this file.

Comments are supported–any row that does not begin with a three-digit MARC tag followed by a subfield code will be ignored.

The subfield code is not case-sensitive. Thus “690A” is treated as if it were “690a”, etc.

A valuelist name may link to multiple Tag/Subfields (as in 'myOwnThesaurus_2' above), but each MARC Tag/Subfield must only appear once in the map file.

The name of a valuelist must not contain any blank spaces. Either replace the blank spaces with a dash (or underscore) as above, or use a form of camelcase. Be sure to standardize on one format for these list names, since it is the list name (and not the tag) that will link each list to its corresponding entries in the second file.

Column 3 of the map is still under development. For now, enter a '0' in column 3.

<!–The third column may optionally contain a sourcecode from one of the MARC Source Codelists. If it does, then validation of the user values will take place only when the subfield $2 of the corresponding tag matches the sourcecode in the third column. –>

Column 4 contains a note, which may be up to 500 characters. This will display in MARC Report's “Notes” window whenever a MARC record string fails to validate against the values referred to by the list. Be careful not to add any carriage reutrns, etc., when entering the note–it must be a single string.

The 'myValuelists.txt' file contains 4 columns:

1. The name of a valuelist as found in column 2 of the map (above)
2. The value
3. '0', a note about a value, or a definition of it
4. '0', or the uri of a value (if formally defined)

The purpose of the valuelists file is to enumerate all of the values assigned to each value list defined in the map file. Each valuelist may contain up to 500 entries.

Here is an example of a valuelist file that contains the entries of one valuelist:

myList_1	G (General Audiences)              0	0
myList_1	PG (Parental Guidance Suggested)   0	0
myList_1	PG-13 (Parents Strongly Cautioned) 0	0
myList_1	R (Restricted)                     0	0
myList_1	NC-17 (Adults Only)	           0	0

In the above example, the third column (definition) was set to 0 for readability; here is a complete example for the first and last rows:

myList_1	G (General Audiences)	All ages admitted.	        0
myList_1	NC-17 (Adults Only)	No one 17 and under admitted.	0

There is no URI available for these terms.

Notes about the value lists

Column headers are not used in this file.

The name in the first column must match a name in column 2 of the myValuelistMap file.

The value column contains a string that the MARC data will be matched against. The matching is not case-sensitive, and it will ignore ending punctuation from MARC (but not punctuation internal to the value). Any MARC data that does not match a value in the corresponding list, will be flagged as an error by MARC Report.

The third column will be displayed if F7 is pressed while editing (F7 displays all of values available for any list-driven content designator).

The URI if entered in the fourth column is not implemented at the present (but may someday be useful in populating $0, $1, etc.)

Using the above examples, MARC Report will expect field 521 $a to contain one of the following: G (General Audiences), PG (Parental Guidance Suggested), PG-13 (Parents Strongly Cautioned), R (Restricted), NC-17 (Adults Only); if 521 $a contains any other value, a 'brief error' message will be created.