Understanding WebPAC's CFM File Layouts

0. General Issues
1. Atoms
2. Search Attributes
3. Object Identifiers
4. Maps
5. Views
6. Fields
7. Semantics
8. Schemas

RegularExpressions
New Hooks
Comments

Here are the valid atoms that a CFM file for WebPAC may contain. Only some of them are required, the rest are optional. A few are intentionally left without a value, for possible future use.

Name, Value,

------------------------------------------------------

SITE, University of Hoober,
DESCRIPTION, University of Hoober Library Catalog,
DATABASE, horizon,
IPADDRESS, z3950.spanky.hoober.edu,
SOCKET, 210,
TIMEOUT, 90,
IDAUTHTYPE, IDPASS, //Choice: {NONE,OPEN,IDPASS,ANON}
GROUPID, students,
ACCOUNTNUMBER, casmyn,
PASSWORD, x7y8z9,
FASTBRIEF, 15,
DEFAULTOP, and,
DEFAULTCOMM, ,
DEFAULTQUAL, ,
SMALLSETUB, 10,
MEDIUMSETESN, B,
MEDIUMSETPN, 20,
LARGESETLB, 50,
ELEMENTSETNAME, F, //or #APPMEDIUMSETESN
 

DISPCHARSET, 6, //HTMLLATIN1
FIELDCFM, fld_usmarc_eng_t.cfm,
ACCESSCFM, access_bib.cfm,
 
I2TITLESORT, 1,
SEARCHLIMIT, 500,

BRIEFVIEW_USING_TEMPLATES, 1,
LONGVIEW_USING_TEMPLATES, 1,

--------------------------------------------------------------------------
 

SITE                                               required

The name of the site where the OPAC resides. This name displays on the status line and provides internal documentation for your configuration file.

DESCRIPTION                            optional, recommended

A lengthier description of the database, up to 4096 characters maximum.

 
DATABASE                                  required

The name of the database for the configuration file. This is the name by which the Z39.50 server recognizes this database.

IPADDRESS                                   required

The address of the Z39.50 server. This is either the "dotted-quad" IP address, or the fully-qualified domain name.

SOCKET                                         required

The TCP/IP socket number upon which the Z39.50 server listens for incoming requests. The customary socket is 210.

TIMEOUT                                     required

The amount of time, in seconds, that will be allowed to pass before WebPAC terminates its connection to the Z39.50 server due to non-responsiveness. Servers are occasionally known to "hang", and the timeout feature ends a Z39.50 session, allowing a user to reconnect with a new session.

IDAUTHTYPE                             optional, Default: OPEN

Indicates whether id authentication is used for database security. Possible values are NONE, OPEN, IDPASS and ANON.
 
GROUPID                                     optional

A valid Group ID, if the database requires it for ID authentication. This value would normally be set if IDAUTHTYPE is set to IDPASS.

ACCOUNTNUMBER                 optional,

A valid username or account number for ID Authentication. This value would normally be set if IDAUTHTYPE is set to IDPASS.

PASSWORD                                 optional

A valid password for ID Authentication, often used in conjunction with an ACCOUNTNUMBER or GROUPID. This value would normally be set if IDAUTHTYPE is set to IDPASS.

FASTBRIEF                                 optional, recommended

This value, when set, tells WebPAC the number of brief records to request at a time from a Z39.50 server.

A value of 10 to 15 is optimal in most cases. Normally, this should be enough records to fill a display screen or templated view. If a search were to yield 200 records, WebPAC would request only 15 at a time for the user, sufficient to build a display, rather than waiting for all 200 records to be transferred.

DEFAULTOP                                 optional,

The default operator to be used in a Common Command Lanugage query, if no operator is specified in the query. Common values are: and, adj

DEFAULTCOMM                         optional,

The default command to be used in a Common Command Lanugage query, if no operator is specified in the query. Possible values are: find, scan

DEFAULTQUAL                             optional,

The default qualifier to be used in a Common Command Lanugage query, if none is specified in the query itself. Valid values are to be found among qualifiers within the Search Attributes section of the CFM.

DISPCHARSET                                optional,

If present, this value changes the display character set from its default of Latin1. This atom has a possible numeric value as follows:
 

SMALLSETUB                             optional, advanced

LARGESETLB                             optional, advanced

Setting these atoms with numeric values establishes the ranges of the "Small Set", "Medium Set" and the "Large Set". These affect the manner in which WebPAC obtains records from a Z39.50 server.

Functionally, if the number of "hits" a search returns is less than or equal to the Small Set Upper Boundary (SMALLSETUB), all of the records will be returned in the Z39.50 Search Response.

If the number of hits is equal to or greater than the Large Set Lower Boundary, no records will ever be returned in the Z39.50 Search Response, but only in an actual present request. In practical terms, setting this value will speed search response time when the a search yields a high number of results.

If both SMALLSETUB and LARGESETLB are set, then the range (if any) between them is known as the Medium Set. If the number of hits yielded by a search falls into the Medium Set range, then a portion of the records will be returned in the Search Response, the quantity of which is described by MEDIUMSETPN (Medium Set Present Number), and the format of which is described by MEDIUMSETESN (Medium Set Element Set Name). See these atoms for more details.

 MEDIUMSETESN                     optional, advanced, Default: B

The "Element Set" in which to return records when number the of "hits" is within the medium range.
The medium range is between the SMALLSETUB and the LARGESETLB. Either "B" (brief) or "F" (full). If not set, Element Set "B" (brief) is requested.

MEDIUMSETPN                         optional, advanced

Medium Set Present Number. Determines number of records returned in a search response when the number of "hits" is within the medium range. A value greater than 0.

ELEMENTSETNAME                 optional, advanced, Default: F

The name of the "Element Set" to request from the server for full-length records. If this atom is not set, the request defaults to "F".
 
FIELDCFM                                 optional, recommended

The name of the CFM file which contains field definitions for the final record display. This allows for small connection CFMs to all share a single CFM for definition of fields used in constructing views. If absent, WebPAC will look in the current CFM for field definition information.

 ACCESSCFM                             optional, recommended

The name of the separate CFM file which contains the schemas and semantics describing the structure of the records being searched for and displayed. This allows for small connection CFMs to all share a single CFM for record access. This atom should be defined in both the Connection CFM and the Field CFM. If absent, WebPAC will look in the current CFM for record access information.

I2TITLESORT                             optional,

When sorting records on title fields, this instructs WebPAC to use indicator 2 as an offset into the text.

A value of 1 enables this feature.

SEARCHLIMIT                         optional, recommended

Specifies the maximum number of records that a search may yield. A numeric value greater than 0.

BRIEFVIEW_USING_TEMPLATES     optional,

LONGVIEW_USING_TEMPLATES     optional,

If the WebPAC Administrator wishes to use standard Templates to define the layout of Brief and Long views, then these must be set to 1. Otherwise, brief and long view layout will be according to the formatting described by the CFM.
 

A Search Attribute defines a valid search that may be performed against a particular database.
It is enclosed in square brackets ("[" and "]"), and each of its elements is comma-delimited.
A Search Attribute has the following structure:
 

name	qualifier	view name	category	scannable	normalize	attrset id	attr pairs
Author,	AU,	BRIEF,	1,	1,	8,	BIB1,	[[1,4,]...]

Here is a typical Search Attribute for a search against an Author/Phrase index:
 

[Author Name, AU, BRIEF, 4, 0, 8, BIB1,
[ [1,1003,] [4,1,] [5,100,] ]
]

Qualifier
A short alpha-numeric token of up to 8 characters. Must be unique for each Search Attribute
May be used for Common Command Language searches.

View Name
Name of the view to use for record display when performing a search with this Search Attribute.
Not currently in use, but you may want to set this to BRIEF initially.

Category
The category to which this Search Attribute belongs. Used to organize Search Attributes in WebPAC.
Valid Values are:
 

Scannable
If the scan service is available for this attribute, this is set to 1. Otherwise, the value is 0.

Normalize
A flag which affects the handling of punctuation in search results. These values may be OR’ed together in combination, i.e., Remove End Punctuation & Lower Case: 1 + 4 = 5.
 
 

Attribute Set ID
The name of the Attribute Set to which the Type/Value pairs belong. In most cases, this is BIB1.

Attribute Set Type/Value Pairs
Numeric pairs defining the actual nature of the Search Attribute. Each pair consists of a type followed by a value, and is enclosed in brackets. The entire list of type/value pairs is also enclosed in brackets.

Here is an example:

[ [1,1003,] [4,1,] [5,100,] ]

- A Use attribute of 1003             (Author personal name)
- A Structure attribute of 1            (phrase search)
- A Truncation attribute of 100      (Do Not Truncate)

For BIB1, the types are as follows:
 

An object identifier uniquely identifies anything in the universe. It is based on a hierarchy of authorities. The OID prefix for Z39.50 is 1.2.840.10003. The Z39.50 record syntax identifier is 1.2.840.10003.5, USMARC is 1.2.840.10003.5.10 and record syntaxes developed at ALS begin with 1.2.840.10003.5.1000.11. Object identifiers can be named in the CFM file.

The ObjectIdentifiers section in the CFM specifies the record syntaxes of both Brief and Long records as they will be requested from a database. An ObjectIdentifier consists of a name followed by an OID.

Here is an example ObjectIdentifiers section:

{ObjectIdentifiers

[BRIEFSYNTAX,
1.2.840.10003.5.102, //OPAC syntax
]
[FULLSYNTAX,
1.2.840.10003.5.102, //OPAC syntax
]
}

The Maps section of a CFM file provides a way for WebPAC to translate any concept into another.
The syntax for a map is thus:

[MapName,             Item1, Value1,
  Item2, Value2,
  etc...
]

OID_SCHEMA

For most databases containing OPAC records, the normal OPAC record schema is SC_M_ZR_102.
However, for HORIZON databases, an alternate OPAC schema is used to describe record structures, and this must be so indicated with the OID_SCHEMA map. This map instructs WebPAC to use the BOGUS_SC_M_ZR_102 schema instead, whenever a record with the corresponding OID is received.

The OID_SCHEMA map should be removed for all other non-Horizon databases.

[OID_SCHEMA,
            1.2.840.10003.5.102, BOGUS_SC_M_ZR_102,
]

 SORT_FILTER_SEMANTICS

When Templates are in use, this map is necessary to correctly sort and filter upon specified fields.
This map relates a key in the sort-filter template file to a semantic item present in an actual record.

        [SORT_FILTER_SEMANTICS,
                    PUBDATE, TG_Pubdate,
                    AUTHOR, TG_Author,
                    TITLE, TG_Title,
                    856a, S856a,
                    007/1, LEADER7,
                    856u, S856u,
                    008/7, SORT_FILTER_PUBDATE,
        ]

RedirectionMap

To enable users to redirect a search from a Long record view, the RedirectionMap must be present.
This links a redirection token in the FieldCFM to an actual valid Search Attribute, indicated by a Qualifier. If a database does not possess one of the indexes contained within the RedirectionMap, the Qualifier may be left blank. Be sure to maintain the qualifier’s delimiting comma, however!

        [RedirectionMap,
                R_AUTHOR, AA,
                R_TITLE, TA,
                R_SUBJECT, SA,
                R_ISBN, ISBN,
                R_ISSN, ,
                R_SERIES, TA,
        ]

AvailabilityMap
Translates a TRUE or FALSE into "Available" or "Not Available" for the circulation data.

OnHoldMap

Translates a TRUE or FALSE into "On Hold" or "Not On Hold" for the circulation data.

RenewableMap

Translates a TRUE or FALSE into "Renewable" or "Not Renewable" for the circulation data.
 
T000_O6

Translates the value of offset 6 in the leader of a MARC record into its appropriate text, denoting Type of Record (material format).

T000_O7

Translates the value of offset 7 in the leader of a MARC record into its appropriate text, denoting Bibliographic Level.

A View references one or more Fields.
A Field references one or more Semantics.
A Semantic references one or more paths into a Schema.
A Schema just is, man!

A view produces a textual display of a structured record. Views consist of a view name followed by a list of one or more Fields. The Fields available for a view may be found in the Fields section of either the current CFM, in the FIELDCFM it references (usually fld_usmarc_eng_t.cfm), or in the Custom CFM (fld_usmarc_eng_t_custom.cfm) See Atoms for more information on specifying the FIELDCFM..

Standard views are BRIEF, LONG and HOLDINGS.

Here is the generic structure of a View:

    {Views

                    [VIEW_NAME, [FIELD1, FIELD2, ...]
                    ]
        }

In a CFM which is used along with WebPAC Templates, the following would be a possible Long View definition. Note that the Fields referenced all begin with "T_" . This indicates that the field is designed to work correctly with the WebPAC Templates.

[LONG,
        [T_AUTHOR, T_TITLE, T_EDITION, T_TRANSLATED_TITLE, T_PUBLISHED,
        T_DESCRIPTION, T_RELATED, T_SUBJECT, T_OTHERAUTHORS, T_OTHERTITLES,
T_NOTES, T_CONTENTS, T_SUMMARY, T_SERIES, T_INDEXEDBY, ]
]
 
For a CFM designed to work with WebPAC Templates, the following Views are standard:

        BRIEF01 - BRIEF14 // Standard Brief View componants
        BRIEF30 - BRIEF57 // Brief Holdings View componants
        LONG // The normal Long View of a record

Also, these Views are necessary to view Holdings info:
 
                    HOLDINGS_VIEW
                    HOLDINGS_HEADING_VIEW
                    HOLDINGS_ENDING_VIEW
                    CIRCULATION_VIEW
                    CIRCULATION_HEADING_VIEW
                    VOLUMES_VIEW
                    VOLUMES_HEADING_VIEW

A Field is a formatted component which is used to make up a View. Fields are normally defined in the FieldCFM file, which for WebPAC is usually "fld_usmarc_eng_t.cfm".

Here’s an example of a Field to display "Contents" from a record.

    [T_CONTENTS,
        [+ "{L}Contents:{/L}"
            [$
                   "{D}" [^ S505a,] "{/D}"
            ]
        ]
    ]

Fields that are designed to work with WebPAC Templates have the convention of being named with an initial "T_". Within these fields, special markup codes are used to indicate Labels, Display Text and Redirection Text, using curly braces:

· Labels are preceded by "{L}" and terminated by "{/L}".
· Display Text is preceded by "{D}" and terminated by "{/D}".
· Redirection Text is preceded by "{R}" and terminated by "{/R}".

· A BRIEF layout, if the CFM is not using WebPAC Templates.
· Layout for Templated BRIEF fields: BRIEF01-BRIEF12
· Layout for Templated brief holdings fields: BRIEF30-BRIEF54.
· Layout for HOLDINGS fields.

A set of one or more schemaPaths, which assigns meaning to a portion of a record. Semantics define meaning as a choice between schema paths. A schema path is a route along a logical tree to a piece of data within the record.

In practice, a single Semantic offers accessibility to a specific Tag and Subfield with a bibliographic record. Almost all of the regular MARC Tag/Subfield combinations in the format S999x are defined (e.g. S018c, S100a, S856u). For example, there is an S100a Semantic, defined for Tag "100", Subfield "a". Here it is:

[S100a,
        [[SC_M_ZR_10,SC_ZR_10,MainEntryPersonalName,Sa,]]
        [[SC_M_ZR_102,SC_ZR_102,SC_ZR_10,MainEntryPersonalName,Sa,]]
        [[BOGUS_SC_M_ZR_102,SC_ZR_102,SC_ZR_10,MainEntryPersonalName,Sa,]]
    ]

Observe that the syntax requires a Semantic Name, followed by several Schema Paths, defining both OPAC and MARC record structures. Each of the Schema Paths exists within the Schemas section of the AccessCFM.

                · Extended Scan Information (if available) is defined

A Schema describes the structure of a record returned by a Z39.50 server. It essentially maps a logical strucure onto a blob of data returned by the server, using a series of Triples (three context-dependent numbers. Schemas are directly referenced in the Semantics portion of the ACCESSCFM. The syntax of a Schema is too complex to discuss here, but here as an example is a portion of a schema for a MARC record:

[SC_ZR_10,
            [[0,1,0,]2,
                        [LEADER,
                                    [[6,2,1,]1, [LEADER6, ] ]
                                    [[7,2,1,]1, [LEADER7, ] ]
                                    [[18,2,1,]1, [EncodingLevel, ] ]
                        ]
            ]
                        [[7,1,0,]2,
                                    [F007,
                                                [[0,2,2,]1, [Format,] ]
                                    ]
                        ]
...etc...
]
 

{RegularExpressions

        [STRIP_END_PUNC, [ "[./]" "" 0,]]
}

{NewHooks
        [AUTO, [test1,0,[T,1,Again,][K,0,New2,]]
               [test2,0,[T,0,Again,]]
        ]
        [MENU,  [test1,0,[T,1,Again,][K,0,New2,]]
                [test2,0,[T,0,Again,]]
        ]
}

  UIAS Home Page