 |
Logiciel-serveur de métadonnées Z39.50
zserver.pl - Z39.50 server,
with GEO compliance,
for Solaris and Windows.
- zserver.pl
Starts up Zserver with the default configuration.
Zserver will read the map file fgdcMap.xml and monitor port 9999 for connection requests.
- zserver.pl -m/test/user/TestMap.xml -p9000
Starts up Zserver with the map file "/test/user/TestMap.xml" and monitors port 9000 for connection requests.
On Windows,
the syntax for specifying the very same map file is "\test\user\TestMap.xml".
Zserver uses Z39.50 to make databases available as GEO Profile compliant metadata.
Z39.50 (http://lcweb.loc.gov/z3950/agency/markup/toc.html) is a communication protocol specifying how server and client software exchange messages to retrieve information.
The server software in this case is Zserver.
Most client software were created for bibliographic databases.
However,
the client at http://cgkn.net/2002/datacat/index.php focuses on geospatial metadata.
GEO Profile (http://www.fgdc.gov/standards/projects/GeoProfile) is a framework for organizing information known as geospatial metadata.
Using this framework,
end-users can indicate the metadata of interest without knowing how the underlying databases organize the data.
- Supports GEO Profile,
version 2.2 (http://www.fgdc.gov/standards/projects/GeoProfile).
Zserver's support of GEO is based on the formally expressed (XML DTD) schema found at:
http://www.fgdc.gov/standards/projects/GeoProfile/annex_c.html#XML%20DTD.
If you do not get the expected query result from Zserver,
check the client application that you use for connecting to Zserver.
Make sure that the application is sending out queries conforming to GEO's requirement on attribute combination:
http://www.fgdc.gov/standards/projects/GeoProfile/annex_b.html#Attribute%20Combination%20Guidelines
If the client is ZNavigator and you use its query builder to build a query,
do not allow any of the term qualifiers (attributes) to use default value.
ZNavigator does not always generate an appropriate query involving one or more defaults.
- Supports various database systems.
Zserver can access the following database systems:
- Microsoft SQL Server
On Solaris,
Zserver accesses SQL Server via FreeTDS.
Thus,
FreeTDS must be installed.
On Windows,
Zserver accesses SQL Server via the ODBC driver that comes with Windows.
- MySQL
You can download MySQL from http://www.mysql.com.
- Oracle
To have Zserver accesses an Oracle database,
you must install Oracle software on the machine running Zserver.
- PostgreSQL
You can download PostgreSQL from http://www.postgresql.org.
- Supports Latin-1 encoding.
Zserver supports database content stored as Latin-1 encoding.
This includes French characters.
- Allows attributes mapped to various target types.
Zserver allows the GEO Profile Use attributes mapped to database table columns,
SQL scalar expressions,
and constant expressions containing text,
number,
or date.
- Presents output in a consistent order.
GEO Profile is based on the FGDC standard (http://geology.usgs.gov/tools/metadata/standard) which includes a structure for presenting metadata.
Zserver observes the same FGDC structure when presenting metadata.
Thus,
providing a consistent way of presenting search result regardless of which database the data comes from.
The same structure also applies to different output formats,
i.e.
XML,
HTML,
SUTRS,
and GRS-1.
- Includes links to FGDC explanations in HTML output.
When asked to present metadata as HTML output,
Zserver includes links to the FGDC explanation (http://geology.usgs.gov/tools/metadata/standard) of the individual Use attributes.
- Fills in missing components for incomplete queries.
The Z39.50 clients ZNavigator and Compusult sometimes send in incomplete search queries.
Zserver has special handling to fill in the missing parts.
On the command line invoking Zserver,
you can supply parameters separated by spaces.
- -m<map_file_name>
For example,
"zserver.pl -m/test/user/TestMap.xml" specifies the map file "/test/user/TestMap.xml".
On Windows,
the syntax for specifying the same map file is "\test\user\TestMap.xml".
- -p<port_number>
For example,
"zserver.pl -p9000" asks Zserver to monitor port 9000 for connection requests.
Note that when multiple parameters are specified,
the port parameter must be the last.
- -pf<pre-fetch_count>
For example,
"zserver.pl -pf200" asks Zserver to pre-fetch 200 matching records after each search.
By pre-fetching records,
Zserver does not have to issue a separate database request for individual records.
The overall response is therefore improved.
The price for such improvement is the memory used for storing the pre-fetched records.
When Zserver receives a request for records beyond the pre-fetched ones,
Zserver will ask the database server for those records and,
if applicable,
the preceding ones.
For example,
with 200 records pre-fetched and there is a request for the 284th record,
Zserver will issue a database request for record 201 to 284.
After that,
any requests for record 1 to 284 will cause Zserver to look into the 284 pre-fetched records.
The default is 100.
- -trace
For example,
"zserver.pl -trace" asks Zserver to output overall trace messages.
- -tracepqf
For example,
"zserver.pl -tracepqf" asks Zserver to output trace messages on the parsing of search query.
PQF stands for Prefix Query Format.
It is the search query's format.
Zserver includes the following limitations:
- Composite attributes cannot be mapped.
Many of the GEO Profile Use attributes are composite,
meaning that they have sub-attributes.
Composite attributes cannot be mapped.
Only basic attributes (attributes without sub-attributes) can be mapped.
- One database per search request.
A search request cannot search multiple databases.
- Limited support of database table relationships.
Relationships among database tables are supported via SQL scalar expressions.
When a Use attribute is mapped to a SQL scalar expression,
that expression can include SQL code to navigate among tables and therefore follow the appropriate table relationships.
- No @prox,
@set,
@term,
and @attr-specific attribute set in search query.
Zserver recognizes PQF (Prefix Query Format) search query.
The PQF specification (http://www.indexdata.dk/yaz/doc/tools.tkl#PQF) includes @prox,
@set,
and @term.
But they are not supported by Zserver.
The optional attribute set in an attribute specification (@attr) is also ignored.
- Not all features in the Z39.50 specification are implemented.
Zserver uses SimpleServer (http://www.indexdata.dk/simpleserver) to handle the Z39.50 protocol (http://lcweb.loc.gov/z3950/agency/markup/toc.html).
SimpleServer implements only the basic features.
Here are the steps for getting Zserver up and running:
- 1.
Download and install Zserver.
-
Download http://cgkn.net/cur/zserver/zserver-0.84.zip.
For Solaris,
see "Installing on Solaris".
For Windows,
see "Installing on Windows".
- 2.
Edit map file.
-
Map file tells Zserver how individual GEO Profile Use attributes should be mapped to database fields.
For the details on editing a map file,
see "MAP FILE".
- 3.
Start Zserver (e.g.
perl zserver.pl).
-
For parameter description,
see "COMMAND LINE PARAMETERS".
On a Solaris machine with Perl and C installed,
you need to compile and install the following:
NOTE:
On Windows (Win32),
you can go through the same compile-and-install process as in Solaris.
You do not need DBD::Oracle and DBD::Pg.
However,
you need Microsoft Visual C++.
Without that,
you will have to install pre-compiled binaries.
This section is about installing pre-compiled binaries.
The reference in parenthesis after a package name refers to either a binary distribution's URL or an ActivePerl "ppm install" command.
In the case of an URL,
download and install the binary.
Note the version number.
It is important to get the exact version.
In the case of a PPM (Perl Package Manager) command,
run it inside a Command Prompt window to install the package.
To run Zserver on Windows,
you need the following:
- ActivePerl 5.8.3 Build 809 (http://ftp.activestate.com/ActivePerl/Windows/5.8/ActivePerl-5.8.3.809-MSWin32-x86.msi)
- MySQL ODBC Driver
Required only if you want to access MySQL databases.
Note that when you run Zserver on a machine without the MySQL ODBC driver installed,
and yet the map file (see "MAP FILE") has <database> elements referring to a MySQL database,
you will see errors about the MySQL database during Zserver start-up.
You can ignore the errors as long as Zserver won't be asked to access the MySQL database.
See "Installation for connecting to a remote MySQL database" for details.
- Oracle Software (http://www.oracle.com)
Required only if you want to access Oracle databases.
Note that when you run Zserver on a machine without Oracle installed,
and yet the map file (see "MAP FILE") has <database> elements referring to an Oracle database,
you will see errors about the Oracle database during Zserver start-up.
You can ignore the errors as long as Zserver won't be asked to access the Oracle database.
See "Installation for connecting to a remote Oracle database" for an example of setting up using an Oracle freeware.
- PostgreSQL ODBC Driver (http://gborg.postgresql.org/project/psqlodbc/genpage.php?downloads)
Required only if you want to access PostgreSQL databases.
- DBI (ppm install DBI)
- DBD::ODBC (ppm install DBD::ODBC)
Required only if you want to access a MySQL or Oracle database.
To access such database,
Zserver requires a DSN (Data Source Name) defined on the machine running Zserver.
TIP:
When you have problem connecting to a database through Zserver and the type of database does not require a DSN,
you can still go through the process of defining a DSN to find out whether the problem is specific to Zserver or with the environment.
When defining a DSN for diagnostic purpose,
note that Zserver uses the following database drivers:
- "PostgreSQL" for PostgreSql
- "SQL Server" for MS SQL
After specifying a name for the DSN,
you will see an option like "Connect to SQL Server to obtain default settings for the additional configuration options.".
Select it and provide the Login ID and Password as used in the database mapping (see "Database declaration").
Then click on Next.
If the connection cannot go through,
you will see error messages.
Resolve them before trying again with Zserver.
- XML::LibXML::Common (ppm install http://theoryx5.uwinnipeg.ca/ppms/XML-LibXML-Common.ppd)
In response to the "Fetch libxml2.dll [yes]" prompt,
press enter to download and install the DLL.
In response to the "Where should libxml2.dll be placed?
[Perl/bin]" question,
enter a directory that is in the system variable "path".
- XML::SAX (ppm install http://theoryx5.uwinnipeg.ca/ppms/XML-SAX.ppd)
After installation,
check the SAX directory to look for a file called ParserDetails.ini.
If there is no such file,
create a blank file and name it as such.
If ActivePerl was installed on c:\perl,
the SAX directory is typically c:\perl\site\lib\XML\SAX.
- XML::LibXML (ppm install http://theoryx5.uwinnipeg.ca/ppms/XML-LibXML.ppd)
- XML::LibXSLT (ppm install http://theoryx5.uwinnipeg.ca/ppms/XML-LibXSLT.ppd)
In response to the "Fetch libxslt_win32.dll [yes]" prompt,
press enter to download and install the DLL.
In response to the "Where should libxslt_win32.dll be placed?
[Perl/bin]" question,
enter a directory that is in the system variable "path".
In response to the "Fetch libexslt_win32.dll [yes]" prompt,
press enter to download and install the DLL.
In response to the "Where should libexslt_win32.dll be placed?
[Perl/bin]" question,
enter a directory that is in the system variable "path".
- YAZ 2.0.20 (http://ftp.indexdata.dk/pub/yaz/win32/yaz_2.0.20.exe)
After installing YAZ,
remember to add the YAZ installation directory's bin sub-directory to the system variable "path".
That is required by SimpleServer.
- Net::Z3950::SimpleServer (ppm install http://cgkn.net/2002/zserver/Net-Z3950-SimpleServer.ppd)
If for whatever reasons you need to re-build the SimpleServer PPM package,
see "Building a SimpleServer PPM package".
To connect to a remote MySQL database,
you must have MySQL ODBC driver installed.
Here is an example of setting up Windows XP using the MySQL ODBC Connector from http://www.mysql.com:
- 1.
Download and run the MSI Installer of the version 5.1 driver
-
http://dev.mysql.com/downloads/connector/odbc/5.1.html#win32
- 2.
Define a system DSN
-
A system DSN indicates how to reach the remote MySQL server.
In the map file (see "MAP FILE"),
you refer to the system DSN to indicate how Zserver should access the remote MySQL database.
Here is how to define a system DSN:
- Go to:
Start> Settings> Control Panel> Administrative Tools> Data Sources (ODBC)
- Click on the "System DSN" tab
- Click "Add..."
- Select "MySQL ODBC 5.1 Driver"
This is the driver installed in step 1.
- Click "Finish"
- Enter "myRemoteMySqlDb" into "Data Source Name"
This is the name to use for "dbNameToServer" when defining a database entry in the map file (see "MAP FILE").
- Enter "Sample database" into "Description"
- Enter the server address into "Server"
- Click "OK"
To connect to a database hosted on a remote Oracle server, you can install the Oracle Instant Client from:
http://www.oracle.com/technology/software/tech/oci/instantclient/htdocs/winsoft.html
Here is an example of installing Instant Client 10.2.0.4 on Windows XP:
- 1. Download basic Instant Client
-
http://download.oracle.com/otn/nt/instantclient/10204/instantclient-basic-win32-10.2.0.4.zip
- 2. Download ODBC Instant Client
-
http://download.oracle.com/otn/nt/instantclient/10204/instantclient-odbc-win32-10.2.0.4.zip
- 3. Combine downloads
-
Unzip the above two downloads into a single installation directory (e.g. C:\bin\oracleInstantClient_10_2).
- 4. Enable basic Instant Client
-
Add the installation directory (C:\bin\oracleInstantClient_10_2) to the system environment variable PATH:
- 5. Enable ODBC Instant Client
-
With the basic Instant Client enabled, execute the odbc_install.exe found in the installation directory (C:\bin\oracleInstantClient_10_2).
- 6. Specify content display (NLS_LANG)
-
To ensure the proper display of database content, Oracle needs to know the language, country, and character set involved. You specify them through the system environment variable NLS_LANG.
In this installation example, equate NLS_LANG with "AMERICAN_CANADA.WE8ISO8859P1" which means:
- Language is American
- Country is Canada
- Character set is 8-bit West European conforming to part 1 of the standard ISO 8859.
For more information on NLS_LANG, see the FAQ at:
http://www.oracle.com/technology/tech/globalization/htdocs/nls_lang%20faq.htm
- 7. Define TNS (Transparent Network Substrate) service name
-
A TNS service name brings together the network parameters for reaching a remote database server. Here is a way of defining TNS service name:
- Inside the installation directory (C:\bin\oracleInstantClient_10_2), create the file tnsnames.ora.
- In that file, define a TNS service name for connecting to the remote Oracle server (you will need the host IP, port number, and service name for connecting to the server).
Here is an example of defining the TNS service name MY_REMOTE_ORACLE_SERVER:
MY_REMOTE_ORACLE_SERVER =
(DESCRIPTION =
(ADDRESS_LIST =
(ADDRESS =
(PROTOCOL = TCP)
(HOST = host.nrcan.gc.ca)
(PORT = 1234)))
(CONNECT_DATA =
(SERVICE_NAME = service.nrcan.gc.ca)))
- 8. Specify TNS service name directory (TNS_ADMIN)
-
This tells Oracle where to get the list of TNS service names. Define the system environment variable TNS_ADMIN by equating it with "C:\bin\oracleInstantClient_10_2".
- 9. Define system DSN (Data Source Name)
-
A system DSN represents a specific combination of database driver and TNS service name. At runtime, the database driver uses network parameters (found with the specified TNS service name) to reach the remote server.
In the map file (see "MAP FILE"), you refer to a system DSN to indicate how Zserver should access a remote database.
Here is how to define a system DSN:
- Go to:
Start> Settings> Control Panel> Administrative Tools> Data Sources (ODBC)
- Click on the "System DSN" tab
- Click "Add..."
- Select "Oracle in instantclient10_2"
This is the database driver that comes with the above Oracle ODBC Instant Client installation (see step 5).
- Click "Finish"
- Enter "myRemoteOracleDb" into "Data Source Name"
This is the name to use for "dbNameToServer" when defining a database entry in the map file (see "MAP FILE").
- Enter "Sample database" into "Description"
- Select "MY_REMOTE_ORACLE_SERVER" from the "TNS Service Name" selection list
This is the name defined earlier (see step 7).
- Click "OK"
A SimpleServer PPM package allows SimpleServer to be installed on a Windows machine not set up for compilation. To build the package, you need a machine with ActivePerl 5.8+, YAZ 2+, and Microsoft Visual C++ installed. After downloading the SimpleServer 0.08+ source, go to the source directory and do the following:
- Change Makefile.PL
- Comment out the line starting with "my $libs". For example,
#my $libs = `yaz-config --libs threads` || die "ERROR: Unable to call script: yaz-config";
- Specify in LIBS, the location of yaz.lib. For example,
'LIBS' => 'c:\bin\yaz\lib\yaz.lib',
- Specify in INC, the YAZ include path. For example,
'INC' => '-Ic:\bin\yaz\include',
- Add, right after the 'INC' line, the following lines:
'AUTHOR' => 'Index Data(www.indexdata.dk)',
'ABSTRACT' => 'Z39.50(ActivePerl 5.8.3.809, Yaz 2.0.20)',
Note that the abstract includes the version numbers of ActivePerl and Yaz that the SimpleServer is compiled with. Update those numbers to reflect the versions you are using.
- Compile SimpleServer and create a ppd
Start up a Visual Studio .NET 2003 Command Prompt window:
Start> Programs> Microsoft Visual Studio .NET 2003> Visual Studio .NET Tools> Visual Studio .NET 2003 Command Prompt
and execute the following commands:
perl MakeFile.PL
nmake
nmake ppd
- Copy run-time library
The "nmake" in the above created a set of binaries inside the directory blib. You need to copy the C run-time library %SystemRoot%\system32\msvcr71.dll to blib\arch\auto\Net\Z3950\SimpleServer.
- Create an archive
Use tar and gzip to create an archive of the blib binaries. For example,
tar cvf Net-Z3950-SimpleServer.tar blib
gzip --best Net-Z3950-SimpleServer.tar
- Specify archive in ppd
Now the package is ready. It is consisted of the ppd file and the .gz archive. Both of them have to be in the same directory. If that directory is accessible from the web, people can install SimpleServer by opening a Command Prompt window and issuing a command such as:
ppm install http://cgkn.net/2002/zserver/Net-Z3950-SimpleServer.ppd
GEO Profile recognizes a set of searchable fields known as Use attributes. Through a map file (in XML format), you specify how those Use attributes are mapped to database tables and columns.
Zserver comes with a default map file known as fgdcMap.xml. It resides in the same directory where you find Zserver. A recommended way of creating your own map file is to modify fgdcMap.xml. In it, you can remove any of the <database> elements, except the one with dbNameFromClient="ignore". That <database> element must remain in the map file.
A map file can provide mappings to different databases. To specify a new database mapping:
- Add a <database> element to <schema>.
- Add <field> elements to the <database> element.
Note that, as specified in the XML standard, the element and attribute names are case-sensitive. To have the character "<" appears inside an attribute value, you have to use "<".
The <database> element's attributes provide database connection information. For example:
<database dbSystem="postgreSql"
dbNameFromClient="MIRAGE"
dbNameToServer="gscmaps"
host="region11.agg.nrcan.gc.ca"
port="1234"
user="userAbc"
password="userAbcPassword" >
A <database> element has the following attributes:
- dbNameFromClient
The name that a database is known to the client (software or user) connecting to Zserver.
Note that, as stated in the Z39.50 specification, section 3.2.2.1.2 (http://lcweb.loc.gov/z3950/agency/markup/04.html), the name is case-insensitive. Thus, "MyDatabase" is the same as "mydatabase".
- dbNameToServer
The name that a database is known to the managing database server. This name typically appears in a database connection string.
- dbSystem
A case-sensitive code indicating the type of database server managing the database. The valid codes are :
- msSql
Microsoft SQL server.
- mySql
To access a MySQL database from a Zserver running on Windows, you need to define a system DSN with the same name as that in dbNameToServer.
- odbcSocketServer
odbcSocketServer refers to a type of database connection in which there is an ODBC Socket Server running on a Windows PC acting as a bridge between a Microsoft SQL server and Zserver.
ODBC Socket Server is the slowest form of database access. The socket server does not support partial fetching of matching records. It always returns all the matching records. Depending on how fast the socket server can respond, which is affected by the amount of matching data from a query, a timeout can occur at the TCP/IP level.
ODBC Socket Server is available from http://odbcsock.sourceforge.net. After installing it, remember to create a DSN (Data Source Name) with the same name as that in dbNameToServer.
Zserver's support of ODBC Socket Server is experimental.
- oracle
To access an Oracle database from a Zserver running on Windows, you need to define a system DSN with the same name as that in dbNameToServer.
- postgreSql
PostgreSQL server.
- host
The host name or IP address of the machine on which the database server is running.
For a MySQL database, this attribute is ignored by the Zserver running on Windows.
For an Oracle database, this attribute is ignored by the Zserver running on Windows.
- port
The port number which the database server will monitor for incoming database request.
For a Microsoft SQL server database, this attribute is ignored by the Zserver running on Windows. It is optional on Solaris.
For a MySQL database, this attribute is ignored by the Zserver running on Windows.
For an ODBC Socket Server database, this attribute is ignored.
For an Oracle database, this attribute is ignored by the Zserver running on Windows.
- user
The user name for logging in to the database server.
- password
The password for logging in to the database server.
A <field> element specifies how a Use attribute as defined in the GEO Profile is mapped to a database. For examples:
<field usePath="metadata->dataqual->lineage->srcinfo->srccite->citeinfo->title"
table="tableName"
column="columnName" />
<field usePath="metadata->idinfo->citation->citeinfo->pubdate"
sql="to_char(metamaps.publication_date,'YYYYMMDD')" />
<field usePath="metadata->idinfo->ptcontac->cntinfo->cntaddr->country"
const="Canada" />
<field> element recognizes the following attributes (some are applicable only to a certain type of mapping):
- column
Name of a database column.
A <field> element with "column" attribute cannot have "sql" or "const" attributes.
- const
A string constant. The constant must be enclosed within double quotes ("). Please note the following special handling of characters found in a constant:
- All ampersand (&) characters within the constant must be changed to &.
- To have a constant including executable HTML, replace the less than sign (<) by <. For example,
const="HTML code: &lt;a href='http://gdcinfo.agg.nrcan.gc.ca/gdc/index_f.html'>Centre de données géoscientifiques&lt;/a>"
- To have a constant including HTML intended only for display and not for execution, replace < by &amp;lt;. For example,
const="HTML display: &amp;lt;a href='http://gdcinfo.agg.nrcan.gc.ca/gdc/index_f.html'>Centre de données géoscientifiques&amp;lt;/a>"
A <field> element with "const" attribute cannot have "table", "column", or "sql" attributes.
- sql
An SQL scalar expression. It must be enclosed within double quotes (").
A scalar expression is an expression returning a single value. For example,
"to_char(metamaps.ending_date,'YYYYMMDD')"
A scalar expression can have a scalar subquery, i.e. a SELECT statement returning a single value. Therefore, you can link tables together. For example, let's say the Use attribute, Series Name (sername), is stored in a table column. But the name stored there is a short name. There is another table translating short names to long names. To map Series Name to a long name, you can do the following:
<field usePath="metadata->idinfo->citation->citeinfo->title"
table="main_table"
column="title" />
<field usePath="metadata->idinfo->citation->citeinfo->serinfo->sername"
sql="(SELECT long_name FROM name_table WHERE name_table.short_name = main_table.short_name)" />
NOTES:
- It is OK for the above subquery to reference main_table even though main_table is not in the subquery's FROM clause. That is because main_table is referenced from somewhere else, i.e. the Title <field> element. In other words, the Title <field> element pulls in main_table and makes it available to all the subqueries within the same database mapping.
- The parenthesis surrounding a subquery are required by SQL's subquery syntax.
- If a subquery is for a text Use attribute, the subquery should return a fixed length string (padded with blanks if necessary).
- A <field> element with "sql" attribute cannot have "table", "column", or "const" attributes.
- table
Name of a database table.
A <field> element with "table" attribute cannot have "sql" or "const" attributes.
- usePath
The path of a Use attribute.
NOTE: A database mapping must have at least two <field> elements. One of them must be mapped to a table column.
To prepare a map file, you need to understand the concept of path as used in the map file. This section provides an introduction.
GEO Profile specifies the relationships among Use attributes. For instance, it states that:
- "Metadata" includes "Identification Information".
- "Identification Information" includes "Point of Contact".
- "Point of Contact" includes "Contact Information".
- "Contact Information" includes "Contact Address".
- "Contact Address" includes "Country".
Expressing the above series of relationships as a path (using the Use attribute short names), we have:
metadata->idinfo->ptcontac->cntinfo->cntaddr->country
Furthermore, GEO allows some Use attributes to appear in multiple places. For instance, "Country" is a part of "Contact Information" and "Contact Information" can appear in four places. Thus, "Country" has four possible paths:
metadata->dataqual->lineage->procstep->proccont->cntinfo->cntaddr->country
metadata->distinfo->distrib->cntinfo->cntaddr->country
metadata->idinfo->ptcontac->cntinfo->cntaddr->country
metadata->metainfo->metc->cntinfo->cntaddr->country
When you specify a Use attribute, you need to indicate which of the possible paths you have in mind. You do that by including the path in the usePath attribute. For example,
usePath="metadata->idinfo->ptcontac->cntinfo->cntaddr->country"
As shown in the above illustration, a Use attribute may appear in multiple places - each with an unique path. When a database map has different entries (each with a different path) referring to the same Use attribute, it affects how Zserver selects the matching records.
For example, let's say a database map includes the following <field> elements:
<field usePath="metadata->dataqual->lineage->srcinfo->srccite->citeinfo->title"
table="Landscapes"
column="srcTitle" />
<field usePath="metadata->idinfo->citation->citeinfo->title"
table="Landscapes"
column="idTitle" />
Both <field> elements address Title. One refers to the Title in Source Information (srcinfo); the other refers to the Title in Identification Information (idinfo).
When Zserver processes a query looking for records with Title containing "abc", a record will be selected when its Title in Identification Information or Source Information contains "abc".
Here is a 3-step process of locating the various paths associated with a Use attribute:
- Find the Use attribute's numeric value by going to the "<useDefList>" section in the map file and search for a "titleKey" containing your Use attribute's title. When you find such line, the "value" entry on that line is the Use attribute's numeric value.
For example, to get the numeric value of the use attribute, Contact Person, search for "Contact Person" (double quotes included). You will see that Contact Person has the numeric value of 2023.
<useDef titleKey="Contact Person" value="2023" type="text" defaultStruct="6" />
- With the numeric value in hand, search further down the map file for an "<usePath" line with the "valueKey" equals to the Use attribute's numeric value.
Once you've located that line, you will see a group of "<usePath" lines with the same "valueKey", if the Use attribute can appear in multiple places. The "pathKey" entries in those lines are the available paths that you can use in specifying a field for the Use attribute.
Carry on with the Contact Person example, when you search for an "<usePath" line with "2023", you will see a number of lines with such value. You can use any of those pathKey values to specify a path in your database mapping.
<usePath valueKey="2023" pathKey="metadata->dataqual->lineage->procstep->proccont->cntinfo->cntorgp->cntper" />
<usePath valueKey="2023" pathKey="metadata->dataqual->lineage->procstep->proccont->cntinfo->cntperp->cntper" />
<usePath valueKey="2023" pathKey="metadata->distinfo->distrib->cntinfo->cntorgp->cntper" />
<usePath valueKey="2023" pathKey="metadata->distinfo->distrib->cntinfo->cntperp->cntper" />
<usePath valueKey="2023" pathKey="metadata->idinfo->ptcontac->cntinfo->cntorgp->cntper" />
<usePath valueKey="2023" pathKey="metadata->idinfo->ptcontac->cntinfo->cntperp->cntper" />
<usePath valueKey="2023" pathKey="metadata->metainfo->metc->cntinfo->cntorgp->cntper" />
<usePath valueKey="2023" pathKey="metadata->metainfo->metc->cntinfo->cntperp->cntper" />
- A path is consisted of short names. The meaning of those short names may not be very intuitive. To expand the short names, search further down the map file for the short name path.
Continuing with the Contact Person example, when you search for:
"metadata->dataqual->lineage->procstep->proccont->cntinfo->cntorgp->cntper"
you will see:
<usePathTitle
pathKey="metadata->dataqual->lineage->procstep->proccont->cntinfo->cntorgp->cntper"
title="'Metadata'->'Data Quality Information'->'Lineage'->'Process Step'->'Process Contact'->'Contact Information'->'Contact Organization Primary'->'Contact Person'"
/>
Thus, the path in expanded names is:
'Metadata'->'Data Quality Information'->'Lineage'->'Process Step'->'Process Contact'->'Contact Information'->'Contact Organization Primary'->'Contact Person'
NOTE: You CANNOT use a path with expanded names to specify a field in the database mapping. You must use a path with short names.
To report problem, Zserver generates Bib-1 diagnostic messages according to:
http://www.fgdc.gov/standards/projects/GeoProfile/index_html#7.4.1.1.%20Attribute%20Set
Any related attributes will be included in the message body as "Related Attributes" in parenthesis. For example,
(Related Attributes - Use: 1003, Term: "sample")
means the diagnostic message is about the Use attribute "1003" and the search term "sample".
For a list of possible Bib-1 diagnostic messages, see:
http://www.loc.gov/z3950/agency/defns/bib1diag.html
- 0.84 (2008) - Added MySQL support for Windows (Boniface Lau).
- 0.83 (2006) - Added MySQL support for Solaris (James Rupert).
- 0.82 (2004) - Initial release (Boniface Lau).
Jean-François Doyon (Canadian Centre for Remote Sensing, Natural Resources Canada) started Zserver.
Zoltan Bardossy (Natural Resources Canada) further enhanced it.
Boniface Lau (under contract to James Rupert at Natural Resources Canada) rewrote Zserver to add numerous functionality and provided user documentation.
James Rupert (Natural Resources Canada) added support for MySQL.
Copyright (c) 2004 Natural Resources Canada
This program is free software. You can redistribute it and/or modify it under the same terms as Perl itself.
|
|
