-<!-- $Id: asn.xml,v 1.19 2007-05-04 12:24:15 adam Exp $ -->
+<!-- $Id: asn.xml,v 1.20 2007-10-16 10:45:53 adam Exp $ -->
<chapter id="asn"><title>The Z39.50 ASN.1 Module</title>
<sect1 id="asn.introduction"><title>Introduction</title>
<para>
</para>
</sect1>
- <sect1 id="asn.oid"><title>Object Identifiers (YAZ 2)</title>
-
- <note>
- <para>
- This material only applies to version 2 series of YAZ. You need not
- read this material if you are working with YAZ 3.
- See <xref linkend="tools.oid"/> for more information on OIDs.
- </para>
- </note>
-
- <para>
- When you refer to object identifiers in your application, you need to
- be aware that SR and Z39.50 use two different set of OIDs to refer to
- the same objects. To handle this easily, &yaz; provides a utility module
- to &asn; which provides an internal representation of the OIDs used in
- both protocols. Each oid is described by a structure:
- </para>
-
- <screen>
-typedef struct oident
-{
- enum oid_proto proto;
- enum oid_class class;
- enum oid_value value;
- int oidsuffix[OID_SIZE];
- char *desc;
-} oident;
- </screen>
-
- <para>
- The <literal>proto</literal> field can be set to either
- <literal>PROTO_SR</literal> or <literal>PROTO_Z3950</literal>.
- The <literal>class</literal> might be, say,
- <literal>CLASS_RECSYN</literal>, and the <literal>value</literal> might be
- <literal>VAL_USMARC</literal> for the USMARC record format. Functions
- </para>
-
- <screen>
-int *oid_ent_to_oid(struct oident *ent, int *dst);
-struct oident *oid_getentbyoid(int *o);
- </screen>
-
- <para>
- are provided to map between object identifiers and database entries.
- If you store a member of the <literal>oid_proto</literal> type in
- your association state information, it's a simple matter, at runtime,
- to generate the correct OID when you need it. For decoding, you can
- simply ignore the proto field, or if you're strict, you can verify
- that your peer is using the OID family from the correct protocol.
- The <literal>desc</literal> field is a short, human-readable name
- for the PDU, useful mainly for diagnostic output.
- </para>
-
- <note>
- <para>
- The old function <function>oid_getoidbyent</function> still exists but
- is not thread safe. Use <function>oid_ent_to_oid</function> instead
- and pass an array of size <literal>OID_SIZE</literal>.
- </para>
- </note>
-
- <note>
- <para>
- Plans are underway to merge the two protocols into a single
- definition, with one set of object identifiers. When this happens, the
- oid module will no longer be required to support protocol
- independence, but it should still be useful as a simple OID database.
- </para>
- </note>
-
- </sect1>
<sect1 id="asn.external"><title>EXTERNAL Data</title>
<para>
-<!-- $Id: tools.xml,v 1.63 2007-05-22 11:10:08 adam Exp $ -->
+<!-- $Id: tools.xml,v 1.64 2007-10-16 10:45:53 adam Exp $ -->
<chapter id="tools"><title>Supporting Tools</title>
<para>
</para>
</example>
</sect2>
-
- <sect2 id="tools.oid.oident"><title>OID oident</title>
-
- <note>
- <para>
- The oident utility has been removed from YAZ version 3. This
- sub section only applies to YAZ version 2.
- </para>
- </note>
-
- <para>
- The OID module provides a higher-level representation of the
- family of object identifiers which describe the Z39.50 protocol and its
- related objects. The definition of the module interface is given in
- the <filename>oid.h</filename> file.
- </para>
-
- <para>
- The interface is mainly based on the <literal>oident</literal> structure.
- The definition of this structure looks like this:
- </para>
-
- <screen>
-typedef struct oident
-{
- oid_proto proto;
- oid_class oclass;
- oid_value value;
- int oidsuffix[OID_SIZE];
- char *desc;
-} oident;
- </screen>
-
- <para>
- The proto field takes one of the values
- </para>
-
- <screen>
- PROTO_Z3950
- PROTO_GENERAL
- </screen>
-
- <para>
- Use <literal>PROTO_Z3950</literal> for Z39.50 Object Identifers,
- <literal>PROTO_GENERAL</literal> for other types (such as
- those associated with ILL).
- </para>
- <para>
-
- The oclass field takes one of the values
- </para>
-
- <screen>
- CLASS_APPCTX
- CLASS_ABSYN
- CLASS_ATTSET
- CLASS_TRANSYN
- CLASS_DIAGSET
- CLASS_RECSYN
- CLASS_RESFORM
- CLASS_ACCFORM
- CLASS_EXTSERV
- CLASS_USERINFO
- CLASS_ELEMSPEC
- CLASS_VARSET
- CLASS_SCHEMA
- CLASS_TAGSET
- CLASS_GENERAL
- </screen>
-
- <para>
- corresponding to the OID classes defined by the Z39.50 standard.
-
- Finally, the value field takes one of the values
- </para>
-
- <screen>
- VAL_APDU
- VAL_BER
- VAL_BASIC_CTX
- VAL_BIB1
- VAL_EXP1
- VAL_EXT1
- VAL_CCL1
- VAL_GILS
- VAL_WAIS
- VAL_STAS
- VAL_DIAG1
- VAL_ISO2709
- VAL_UNIMARC
- VAL_INTERMARC
- VAL_CCF
- VAL_USMARC
- VAL_UKMARC
- VAL_NORMARC
- VAL_LIBRISMARC
- VAL_DANMARC
- VAL_FINMARC
- VAL_MAB
- VAL_CANMARC
- VAL_SBN
- VAL_PICAMARC
- VAL_AUSMARC
- VAL_IBERMARC
- VAL_EXPLAIN
- VAL_SUTRS
- VAL_OPAC
- VAL_SUMMARY
- VAL_GRS0
- VAL_GRS1
- VAL_EXTENDED
- VAL_RESOURCE1
- VAL_RESOURCE2
- VAL_PROMPT1
- VAL_DES1
- VAL_KRB1
- VAL_PRESSET
- VAL_PQUERY
- VAL_PCQUERY
- VAL_ITEMORDER
- VAL_DBUPDATE
- VAL_EXPORTSPEC
- VAL_EXPORTINV
- VAL_NONE
- VAL_SETM
- VAL_SETG
- VAL_VAR1
- VAL_ESPEC1
- </screen>
-
- <para>
- again, corresponding to the specific OIDs defined by the standard.
- Refer to the
- <ulink url="&url.z39.50.oids;">
- Registry of Z39.50 Object Identifiers</ulink> for the
- whole list.
- </para>
-
- <para>
- The desc field contains a brief, mnemonic name for the OID in question.
- </para>
-
- <para>
- The function
- </para>
-
- <screen>
- struct oident *oid_getentbyoid(int *o);
- </screen>
-
- <para>
- takes as argument an OID, and returns a pointer to a static area
- containing an <literal>oident</literal> structure. You typically use
- this function when you receive a PDU containing an OID, and you wish
- to branch out depending on the specific OID value.
- </para>
-
- <para>
- The function
- </para>
-
- <screen>
- int *oid_ent_to_oid(struct oident *ent, int *dst);
- </screen>
-
- <para>
- Takes as argument an <literal>oident</literal> structure - in which
- the <literal>proto</literal>, <literal>oclass</literal>/, and
- <literal>value</literal> fields are assumed to be set correctly -
- and returns a pointer to a the buffer as given by <literal>dst</literal>
- containing the base
- representation of the corresponding OID. The function returns
- NULL and the array dst is unchanged if a mapping couldn't place.
- The array <literal>dst</literal> should be at least of size
- <literal>OID_SIZE</literal>.
- </para>
- <para>
-
- The <function>oid_ent_to_oid()</function> function can be used whenever
- you need to prepare a PDU containing one or more OIDs. The separation of
- the <literal>protocol</literal> element from the remainder of the
- OID-description makes it simple to write applications that can
- communicate with either Z39.50 or OSI SR-based applications.
- </para>
-
- <para>
- The function
- </para>
-
- <screen>
- oid_value oid_getvalbyname(const char *name);
- </screen>
-
- <para>
- takes as argument a mnemonic OID name, and returns the
- <literal>/value</literal> field of the first entry in the database that
- contains the given name in its <literal>desc</literal> field.
- </para>
-
- <para>
- Three utility functions are provided for translating OIDs'
- symbolic names (e.g. <literal>Usmarc</literal> into OID structures
- (int arrays) and strings containing the OID in dotted notation
- (e.g. <literal>1.2.840.10003.9.5.1</literal>). They are:
- </para>
-
- <screen>
- int *oid_name_to_oid(oid_class oclass, const char *name, int *oid);
- char *oid_to_dotstring(const int *oid, char *oidbuf);
- char *oid_name_to_dotstring(oid_class oclass, const char *name, char *oidbuf);
- </screen>
-
- <para>
- <literal>oid_name_to_oid()</literal>
- translates the specified symbolic <literal>name</literal>,
- interpreted as being of class <literal>oclass</literal>. (The
- class must be specified as many symbolic names exist within
- multiple classes - for example, <literal>Zthes</literal> is the
- symbolic name of an attribute set, a schema and a tag-set.) The
- sequence of integers representing the OID is written into the
- area <literal>oid</literal> provided by the caller; it is the
- caller's responsibility to ensure that this area is large enough
- to contain the translated OID. As a convenience, the address of
- the buffer (i.e. the value of <literal>oid</literal>) is
- returned.
- </para>
- <para>
- <literal>oid_to_dotstring()</literal>
- Translates the int-array <literal>oid</literal> into a dotted
- string which is written into the area <literal>oidbuf</literal>
- supplied by the caller; it is the caller's responsibility to
- ensure that this area is large enough. The address of the buffer
- is returned.
- </para>
- <para>
- <literal>oid_name_to_dotstring()</literal>
- combines the previous two functions to derive a dotted string
- representing the OID specified by <literal>oclass</literal> and
- <literal>name</literal>, writing it into the buffer passed as
- <literal>oidbuf</literal> and returning its address.
- </para>
-
- <note>
- <para>
- The OID module has been criticized - and perhaps rightly so
- - for needlessly abstracting the
- representation of OIDs. Other toolkits use a simple
- string-representation of OIDs with good results. In practice, we have
- found the interface comfortable and quick to work with, and it is a
- simple matter (for what it's worth) to create applications compatible
- with both ISO SR and Z39.50. Finally, the use of the
- <literal>/oident</literal> database is by no means mandatory.
- You can easily create your own system for representing OIDs, as long
- as it is compatible with the low-level integer-array representation
- of the ODR module.
- </para>
- </note>
-
- </sect2>
</sect1>
<sect1 id="tools.nmem"><title>Nibble Memory</title>
projects / yaz-moved-to-github.git / commitdiff