Return to q-dsap.tex CVS log

Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / doc / manual

Annotation of 43BSDReno/contrib/isode-beta/doc/manual/q-dsap.tex, revision 1.1

1.1     ! root        1: % run this through LaTeX with the appropriate wrapper
        !             2: 
        !             3: \chapter {Programming the Directory}
        !             4: 
        !             5: This part of the manual is written for implementors who wish to access the
        !             6: Directory using the \man libdsap(3n) library.
        !             7: This might be an OSI application wishing to look up information,
        !             8: or an interactive Directory user-interface.
        !             9: The interface to the Directory is defined as a series of procedures which
        !            10: closely parallel the service defined in \cite{CCITT.Directory}.  This section
        !            11: defines the procedures,
        !            12: and shows how they relate to the standard.
        !            13: To avoid unnecessary wordiness, the user is expected to be familiar with
        !            14: the standard.
        !            15: 
        !            16: \section      {Conventions}
        !            17: \label{quipu_conv}
        !            18: 
        !            19: The library defines various C structures, described in the 
        !            20: following sections
        !            21: Associated with the C structures, are routines which:
        !            22: 
        !            23: \begin{itemize}
        !            24: \item allocate structures
        !            25: 
        !            26: \item free structures, including sub-structures
        !            27: 
        !            28: \item compare structures
        !            29: 
        !            30: \item copy structures
        !            31: 
        !            32: \item print structures
        !            33: 
        !            34: \item parse structures
        !            35: \end{itemize}
        !            36: 
        !            37: The following conventions are followed in many routines, which are then
        !            38: briefly identified later.
        !            39: For a general structure x, there will be the following routines:
        !            40: \begin{itemize}
        !            41: \item Allocation:
        !            42: \begin{quote}\small\begin{verbatim}
        !            43: struct x *x_alloc ()
        !            44: \end{verbatim}\end{quote}
        !            45: Allocate memory for structure \verb"x".
        !            46: 
        !            47: \item Freeing:
        !            48: \begin{quote}\small\begin{verbatim}
        !            49: x_free (a)
        !            50: struct x * a;
        !            51: \end{verbatim}\end{quote}
        !            52: Free structure \verb"x", and any nested structures.
        !            53: 
        !            54: If the structure, \verb"x", is a linked-list type of structure, then as well
        !            55: as the routines described above, there will be routines of the
        !            56: form \verb"x_comp_function" (where \verb"function" is \verb"alloc",
        !            57: \verb"free", and so on).  These act upon a single element of the
        !            58: list rather than the list as a whole.
        !            59: 
        !            60: \item Copying:
        !            61: \begin{quote}\small\begin{verbatim}
        !            62: struct x * x_cpy (a)
        !            63: struct x *a;
        !            64: \end{verbatim}\end{quote}
        !            65: Return a copy of structure \verb"a".
        !            66: 
        !            67: \item Comparing:
        !            68: \begin{quote}\small\begin{verbatim}
        !            69: int     x_cmp (a, b)
        !            70: struct x *a, *b;
        !            71: \end{verbatim}\end{quote}
        !            72: Return \verb"0" if the structures \verb"a" and \verb"b" same.  Return
        !            73: \verb"-1" if \verb"a<b", or \verb"1" if \verb"a>b".
        !            74: For some structures the notion of \verb"a>b" and \verb"a<b" is not defined,
        !            75: but will be consistent.
        !            76: 
        !            77: \item Printing:
        !            78: \begin{quote}
        !            79: \index{rdn\_print}\index{dn\_print}\index{as\_print}\index{avs\_print}
        !            80: \index{AttrT\_print}\index{AttrV\_print}
        !            81: \small\begin{verbatim}
        !            82: int     x_print (ps, a, format)
        !            83: PS       ps;
        !            84: struct x *a;
        !            85: int      format;
        !            86: \end{verbatim}\end{quote}
        !            87: Print the structure \verb"a" to the presentation stream \verb"ps", using the
        !            88: specified format, either \verb"READOUT", for a pretty-printed format (for
        !            89: example the output of a showentry from \pgm{dish}); or,
        !            90: \verb"EDBOUT", for a format suitable for inclusion in an EDB file.
        !            91: The \verb"PS" structure is described in \volone/ of this manual.
        !            92: 
        !            93: For the structures representing a DN and RDN there is an extra format:-
        !            94: \verb"DIROUT", which is used to get a representation of the name suitable
        !            95: for inclusion in a \unix/ filename (essentially \verb"EDBOUT" with the
        !            96: \verb"@" symbols replaced with \verb"/" separators).
        !            97: 
        !            98: \item String format:
        !            99: \begin{quote}
        !           100: \index{str2rdn}\index{str2dn}\index{str2as}
        !           101: \index{str2AttrV}\index{str2AttrT}
        !           102: \small\begin{verbatim}
        !           103: struct x * str2x (str)
        !           104: char * str;
        !           105: \end{verbatim}\end{quote}
        !           106: Most attribute syntaxes have a string representation.
        !           107: A string of the required 
        !           108: syntax can be converted to the relevant c structure with the ``str2x''
        !           109: function.
        !           110: Each of the string parsers assumes the input string has had multiple spaces
        !           111: and tabs removed, and replaced with single spaces.
        !           112: The function 
        !           113: \begin{quote}\small\begin{verbatim}
        !           114: char * Tidy_String (a)
        !           115: char * a;
        !           116: \end{verbatim}\end{quote}
        !           117: will do the relevant tidying if required.
        !           118: Strings printed with the \verb"EDBOUT" format of x\_print should be parsable.
        !           119: 
        !           120: NOTE \verb"str2AttrV()" \index{str2AttrV} does not follow the ``convention''
        !           121: and has an extra parameter, 
        !           122: which is the expected syntax
        !           123: of the string.
        !           124: 
        !           125: \item Decoding:
        !           126: \begin{quote}\small\begin{verbatim}
        !           127: x_decode (a)
        !           128: struct x *a;
        !           129: \end{verbatim}\end{quote}
        !           130: For efficiency reasons,
        !           131: when information is read from a DSA any
        !           132: structures that contain nested AttributeTypes and
        !           133: AttributeValues will not be fully decoded.
        !           134: This will not matter if
        !           135: you only intend to use the structures internally, but if you
        !           136: intend to show the structure to a ``user'' or write to a log file, 
        !           137: you should call this
        !           138: routine to complete the decoding, which will replace the
        !           139: various ``unfriendly'' structures (such as OID) with string
        !           140: representations.
        !           141: \end{itemize}
        !           142: 
        !           143: The structures following the ``convention'' are listed below.
        !           144: The ``prefix'' column shows the value
        !           145: \verb"x" should be replaced by to use the routines for the associated
        !           146:  structure.
        !           147: \index{RDN}
        !           148: \index{DN}
        !           149: \index{AttributeType}\index{AttrT}
        !           150: \index{AttributeValue}\index{AttrV}
        !           151: \index{AV\_Sequence}\index{avs}
        !           152: \index{Attr\_Sequence}\index{as}
        !           153: \index{EntryInfo}
        !           154: 
        !           155: 
        !           156: \[\begin{tabular}{|l|l|} \hline
        !           157: Structure & Prefix \\ \hline
        !           158: RDN & rdn \\
        !           159: DN & dn \\
        !           160: AttributeType & AttrT \\
        !           161: AttributeValue & AttrV \\
        !           162: AV\_Sequence & avs \\
        !           163: Attr\_Sequence & as \\
        !           164: EntryInfo& entryinfo \\ \hline
        !           165: \end{tabular}\]
        !           166: 
        !           167: \section {Attributes}
        !           168: 
        !           169: Attributes are fundamental
        !           170: components of the directory.  
        !           171: Attributes have two parts, types and values, which are
        !           172: (respectfully) represented by two structures,
        !           173: \verb"AttributeType" and \verb"AttributeValue".
        !           174: 
        !           175: For programing purposes you should include the file \file{quipu/attrvalue.h}
        !           176: into your programs, which contains the following structure definitions:-
        !           177: 
        !           178: \begin{quote}\index{AttributeType}\small\begin{verbatim}
        !           179: typedef struct {
        !           180:         OID              at_oid;
        !           181:         oid_table_attr * at_table;
        !           182: } attrType, * AttributeType;
        !           183: #define NULLAttrT (AttributeType) NULL
        !           184: \end{verbatim}\end{quote}
        !           185: 
        !           186: 
        !           187: The \verb"AttributeType" structure contains two components, only one
        !           188: of which is used at any one time.  An \verb"AttributeType" is defined
        !           189: in \cite{CCITT.Directory} as an OBJECT IDENTIFIER, hence the field
        !           190: \verb"at_oid".  
        !           191: 
        !           192: But
        !           193: \man libdsap(3n) goes further than this, and has a table (described in
        !           194: Section~\ref{oidtables}) which maps strings onto these OIDs.  The
        !           195: second field (\verb"at_table") is a pointer to this table.  The table
        !           196: then contains the OID.  
        !           197: 
        !           198: This table must be loaded by calling
        !           199: \begin{quote}\index{load\_oid\_table}\small\begin{verbatim}
        !           200: load_oid_table(name)
        !           201: char * name;
        !           202: \end{verbatim}\end{quote}
        !           203: The \verb"name" parameter should be the name of the oidtable to load.
        !           204: For most purposes this should be ``\verb"oidtable"''.
        !           205: 
        !           206: Before you load the table, any syntaxes you want special attribute handlers
        !           207: for should be loaded.  To do this you will probably want to call
        !           208: \label{quipusyntaxes}
        !           209: \begin{quote}
        !           210: \index{quipu\_syntaxes}
        !           211: \begin{verbatim}
        !           212: quipu_syntaxes()
        !           213: \end{verbatim}
        !           214: \end{quote}
        !           215: which will load all the syntax handlers defined in Chapter~\ref{syntaxes}.
        !           216: If not all there syntaxes are required, then a subset can be loaded by
        !           217: calling only the handlers required.
        !           218: 
        !           219: 
        !           220: The call
        !           221: \begin{quote}\index{dsap\_init}\small\begin{verbatim}
        !           222: dsap_init(argc,argv)
        !           223: int *argc;
        !           224: char *** argv;
        !           225: \end{verbatim}\end{quote}
        !           226: can be used to load the oidtable for you, with the additional 
        !           227: benifit that it will
        !           228: read the file \file{/etc/dsaptailor} to 
        !           229: find the location on the oidtable.
        !           230: The parameters it expects are the pointers to the 
        !           231: \verb"argc" and \verb"argv"
        !           232: parameters passed to your ``main()'' routine
        !           233: (Beware: \verb"dsap_init" removes certain flags from the parameter list, if you care,
        !           234: pass a copy of them, or pass nulls!).
        !           235: If a ``\tt -c\rm '' flag is found then this is used as the name of
        !           236: the DSA to contact as per dish (see Section~\ref{dish_bind}).
        !           237: Other parameters are ignored.
        !           238: As with loading the tables, the syntaxes you require should have been loaded
        !           239: before you make this call.
        !           240: 
        !           241: The oidtables are represented using the following structures:-
        !           242: \begin{quote}\index{oid\_table}\small\begin{verbatim}
        !           243: typedef struct {
        !           244:         char      ot_name [BUFSIZE];
        !           245:         char      ot_stroid [BUFSIZE];
        !           246:         OID       ot_oid;
        !           247: } oid_table;
        !           248: #define NULLTABLE ((oid_table * )0)
        !           249: 
        !           250: typedef struct {
        !           251:         oid_table oa_ot;
        !           252:         int       oa_syntax;
        !           253: } oid_table_attr;
        !           254: #define NULLTABLE_ATTR ((oid_table_attr *)0)
        !           255: \end{verbatim}\end{quote}
        !           256: 
        !           257: 
        !           258: As structures come across the network,
        !           259: the AttributeType is decoded into the \verb"at_oid" field.  If you
        !           260: want to use the string representation you must call
        !           261: \verb"AttrT_decode" (described in Section~\ref{quipu_conv}), 
        !           262: if you do not decode the structure, the
        !           263: print routines will still work, but the result will numeric
        !           264: OIDs.
        !           265: If successfully decoded the field \verb"at_oid" will be set to \verb"NULLOID",
        !           266: to indicate that there is a table version of the oid.
        !           267: 
        !           268: The table consists to two fields, an integer syntax :- \verb"oa_syntax".
        !           269: This is an integer handle onto the abstract syntax of the attribute value.
        !           270: The value `\verb"0"' indicates an unknown syntax hence ``ASN'' is used.
        !           271: 
        !           272: The second field \verb"oa_ot" is a reference to a \verb"oid_table" structure,
        !           273: which contain the oid -- \verb"ot_oid", a numeric string representation of the oid
        !           274: -- \verb"ot_stroid", and the local key string -- \verb"ot_name".
        !           275: 
        !           276: To create an \verb"AttributeType" given a string representation of an
        !           277: OID, you should use
        !           278: \begin{quote}\index{str2AttrT}\small\begin{verbatim}
        !           279: AttributeType str2AttrT (str)
        !           280: char   *str;
        !           281: \end{verbatim}\end{quote}
        !           282: which looks up the string ``\verb"str"'' in the OID table, and creates an
        !           283: \verb"AttributeType" structure.
        !           284: 
        !           285: There are various low level routines to manipulate entries in
        !           286: the OID table, however the \verb"AttributeType" routines described in 
        !           287: Section~\ref{quipu_conv}
        !           288: will be sufficient for most uses, so the details of these
        !           289: ``invisible'' routines are omitted here.
        !           290: 
        !           291: 
        !           292: Attribute values are represented by the structure \verb"AttributeValue":-
        !           293: 
        !           294: \begin{quote}\index{AttributeValue}\small\begin{verbatim}
        !           295: typedef struct attrVal {
        !           296:         short      av_syntax;
        !           297:         caddr_t           av_struct;
        !           298: } * AttributeValue;
        !           299: 
        !           300: #define NULLAttrV (AttributeValue) NULL
        !           301: \end{verbatim}\end{quote}
        !           302: 
        !           303: The \verb"AttributeValue" structure can hold attribute values in two
        !           304: formats. Firstly as a specialised {\em C\/} structure pointed to by
        !           305: \verb"av_struct", the
        !           306: field \verb"av_syntax" defines the syntax represented by the
        !           307: \verb"av_struct" field.
        !           308: Secondly as a presentation element (also in the \verb"av_struct" field), this is the case when an attribute has
        !           309: been received from the net, but not decoded (indicated by
        !           310: the syntax being zero).  The routine \verb"AttrV_decode"
        !           311: will burst this presentation element into the relevant \verb"av_struct"
        !           312: field.
        !           313: Section ~\ref{add_syntax} describes this more fully.
        !           314: 
        !           315: 
        !           316: Attribute values can now be linked together to form a multi-value attribute
        !           317: value.
        !           318: For this the \verb"AV_Sequence" structure is used.
        !           319: 
        !           320: \begin{quote}\index{AV\_Sequence}\small\begin{verbatim}
        !           321: typedef struct avseqcomp {     
        !           322:     attrVal             avseq_av;
        !           323:     struct avseqcomp    *avseq_next;
        !           324: } avseqcomp, *AV_Sequence;
        !           325: 
        !           326: #define NULLAV ((AV_Sequence) 0)
        !           327: \end{verbatim}\end{quote}
        !           328: 
        !           329: This is simply a linked list of AttributeValues\footnote{
        !           330: For those of you who wrote interfaces using ISODE-5.0, you should note that
        !           331: the field \verb+avseq\_av+ is now an \verb+attrVal+ and not an 
        !           332: \verb+attrVal *+.
        !           333: }.
        !           334: 
        !           335: To create an \verb"AV_Sequence" the two routines
        !           336: \begin{quote}\index{avs\_comp\_new}\index{avs\_merge}\small\begin{verbatim}
        !           337: AV_Sequence avs_comp_new (av)
        !           338: AttributeValue av;
        !           339: 
        !           340: AV_Sequence avs_merge (a,b)
        !           341: AV_Sequence a,b;
        !           342: \end{verbatim}\end{quote}
        !           343: can be used.
        !           344: 
        !           345: Finally an attribute can now be formed by linking the attribute type, and
        !           346: multiple attribute values using the \verb"AttrSequence" structure:-
        !           347: 
        !           348: \begin{quote}\index{Attr\_Sequence}\small\begin{verbatim}
        !           349: typedef struct attrcomp {       
        !           350:     attrType            attr_type;
        !           351:     AV_Sequence         attr_value;
        !           352:     struct attrcomp     *attr_link;
        !           353:     struct acl_info     *attr_acl;
        !           354: } attrcomp, *Attr_Sequence;
        !           355: 
        !           356: #define NULLATTR ((Attr_Sequence) 0)
        !           357: \end{verbatim}\end{quote}
        !           358: 
        !           359: This structure is used singularly to represent an attribute, and as a linked
        !           360: list (linked using \verb"attr_link") to represent a set of attributes.
        !           361: 
        !           362: To create an \verb"Attr_Sequence" the two routines
        !           363: \begin{quote}\index{as\_comp\_new}\index{as\_merge}\small\begin{verbatim}
        !           364: Attr_Sequence as_comp_new (at,as,acl)
        !           365: AttributeType at;
        !           366: AV_Sequence as;
        !           367: struct acl_info * acl;
        !           368: 
        !           369: Attr_Sequence as_merge (a,b)
        !           370: Attr_Sequence a,b;
        !           371: \end{verbatim}\end{quote}
        !           372: 
        !           373: can be used.
        !           374: The \verb"acl" parameter is only used by the DSA, for use in a DUA it should be
        !           375: set to \verb"NULLACL_INFO".
        !           376: 
        !           377: The routine
        !           378: \begin{quote}\index{as\_combine}\small\begin{verbatim}
        !           379: Attr_Sequence as_combine (as,str)
        !           380: AV_Sequence as;
        !           381: char * str;
        !           382: \end{verbatim}\end{quote}
        !           383: is also provided, as an optimisation of
        !           384: \begin{quote}\small\begin{verbatim}
        !           385: as_merge(as,str2as(str));
        !           386: \end{verbatim}\end{quote}
        !           387: 
        !           388: \section {Distinguished Names}
        !           389: The structures which define names are critical.  
        !           390: Names are essentially made up of attributes, but because of their
        !           391: importance, a different --- more specific structure is used.
        !           392: 
        !           393: \begin{quote}\index{RDN}\small\begin{verbatim}
        !           394: typedef struct rdncomp {       
        !           395:     attrType            rdn_at;
        !           396:     attrVal             rdn_av;
        !           397:     struct rdncomp      *rdn_next;
        !           398: } rdncomp, *RDN;
        !           399: 
        !           400: #define NULLRDN ((RDN) 0)
        !           401: \end{verbatim}\end{quote}
        !           402: 
        !           403: An RDN consists of a set of Attribute Types 
        !           404: (\verb"rdn_at"\footnote{This was an \verb+attrType *+ in ISODE-5.0})
        !           405: and Attribute Values 
        !           406: (\verb"rdn_av"\footnote{This was an \verb+attrVal *+ in ISODE-5.0}),
        !           407: the set is linked using \verb"rdn_next".
        !           408: 
        !           409: RDNs can the be joined in a sequence to form a Distinguished Name (DN):-
        !           410: \begin{quote}\index{DN}\small\begin{verbatim}
        !           411: typedef struct dncomp {
        !           412:     RDN                 dn_rdn;
        !           413:     struct dncomp       *dn_parent;
        !           414: } dncomp, *DN;
        !           415: 
        !           416: #define NULLDN ((DN) 0)
        !           417: \end{verbatim}\end{quote}
        !           418: 
        !           419: The following routines are provided in addition to the routines defined is
        !           420: Section~\ref{quipu_conv} to allow the user to create and manipulate names
        !           421: 
        !           422: \begin{itemize}
        !           423: \item Create a DN given an RDN:
        !           424: \begin{quote}\index{dn\_comp\_new}\small\begin{verbatim}
        !           425: dn_comp_new (rdn)
        !           426: RDN     rdn;
        !           427: \end{verbatim}\end{quote}
        !           428: 
        !           429: \item Append a DN to the end of another DN:
        !           430: \begin{quote}\index{dn\_append}\small\begin{verbatim}
        !           431: dn_append (dn1, dn2)
        !           432: DN      dn1,
        !           433:         dn2;
        !           434: \end{verbatim}\end{quote}
        !           435: \verb"dn2" is added to \verb"dn1".
        !           436: 
        !           437: \item Create a RDN given and AttributeType and AttributeValue:
        !           438: \begin{quote}\small\index{rdn\_comp\_new}\begin{verbatim}
        !           439: RDN rdn_comp_new (at, av)
        !           440: AttributeType  at;
        !           441: AttributeValue av;
        !           442: \end{verbatim}\end{quote}
        !           443: 
        !           444: \item Merge two RDNs:
        !           445: \begin{quote}\small\index{rdn\_merge}\begin{verbatim}
        !           446: RDN rdn_merge (rdn1, rdn2)
        !           447: RDN     rdn1,
        !           448:         rdn2;
        !           449: \end{verbatim}\end{quote}
        !           450: RDN's form a set, to make comparisons easier, this
        !           451: implementation assumes them to be ordered sets.  This routine
        !           452: takes two ordered RDN sets, and merges them.
        !           453: If RDNs received across the network are not ordered, the decoding
        !           454: process will order them for you.
        !           455: \end{itemize}
        !           456: 
        !           457: The approach to access control is defined in
        !           458: \cite{QUIPU.Design}.
        !           459: The representation of the attribute for access control is given by the
        !           460: structure shown below.  This closely follows the ASN.1
        !           461: definition.
        !           462: 
        !           463: \begin{quote}\small\begin{verbatim}
        !           464: struct acl_info {
        !           465:     int              acl_categories;
        !           466: #define ACL_NONE        0
        !           467: #define ACL_DETECT      1
        !           468: #define ACL_COMPARE     2
        !           469: #define ACL_READ        3
        !           470: #define ACL_ADD         4
        !           471: #define ACL_WRITE       5
        !           472:     int              acl_selector_type;
        !           473: #define ACL_ENTRY       0
        !           474: #define ACL_OTHER       1
        !           475: #define ACL_PREFIX      2
        !           476: #define ACL_GROUP       3
        !           477:     DN               acl_name;
        !           478:     struct acl_info *acl_next;
        !           479: };
        !           480: \end{verbatim}\end{quote}
        !           481: 
        !           482: The DN \verb"acl_name" is used for the type \verb"ACL_PREFIX" and
        !           483: \verb"ACL_OTHER" only.
        !           484: 
        !           485: \section {Adding New Syntaxes to QUIPU}
        !           486: \label{add_syntax}
        !           487: 
        !           488: It will probably be necessary to add knowledge of extra syntaxes to
        !           489: Directory User Interfaces as the range of applications grow.
        !           490: QUIPU has been designed to make this as easy as possible.
        !           491: 
        !           492: This section describes how you might do this, by adding knowledge
        !           493: of a \verb"FOOBAR" syntax to \man libdsap(3n) library.
        !           494: \verb"FOOBAR" is represented by the c structure
        !           495: ``\tt struct foobar \{\ldots\};\rm ''.
        !           496: 
        !           497: The DSA does not need to know about the new structure, as it will
        !           498: handle unknown syntaxes as blocks of ASN.1.
        !           499: 
        !           500: The procedure call
        !           501: \begin{quote}\small\begin{verbatim}
        !           502: add_attribute_syntax (sntx,enc,dec,parse,
        !           503:                       print,cpy,cmp,sfree,
        !           504:                       print_pe,approx,multiline)
        !           505: char *  sntx;
        !           506: IFP     enc,dec,parse,print,cpy,cmp,sfree,approx;
        !           507: char *  print_pe;
        !           508: char    multiline;
        !           509: \end{verbatim}\end{quote}
        !           510: is used to add knowledge of new attribute syntaxes to quipu.
        !           511: 
        !           512: The parameters are used as follows:-
        !           513: 
        !           514: \begin{describe}
        !           515: \item [\verb"sntx":] The string defining the syntax, in this case it should
        !           516: be \verb"Foobar". Any attributes defined as having the syntax ``Foobar'' in
        !           517: the oidtables will the be handled using the following routines.
        !           518: 
        !           519: \item [\verb"enc":] This is a function pointer to a routine that will convert
        !           520: a C structure representation of foobar into a presentation element that can
        !           521: be sent across the network.
        !           522: The routine is given a single parameter --- a pointer to the foobar structure,
        !           523: and is expected to return a PE.
        !           524: You are reminded of the \man pepy(1c) and \man posy(1c) utilities described
        !           525: in \volfour/ of this manual, they may be of help in creating this encoder.
        !           526: 
        !           527: \item [\verb"dec":] This performs the inverse of the above, it is passed a
        !           528: PE, and should return a C structure representation.
        !           529: 
        !           530: \item [\verb"parse":] Each syntax needs to have a representation that can
        !           531: be read from and written to an EDB file.  This defined routine should take
        !           532:  a single
        !           533: \verb"char *" argument and return a C structure representation.
        !           534: 
        !           535: \item [\verb"print":] This routine is used to print the syntax to a 
        !           536: \verb+PStream+\footnote{\verb+PStream+'s are discussed in \volone/ of this
        !           537: manual.}.
        !           538: The arguments are:
        !           539: \begin{quote}\small\begin{verbatim}
        !           540: foobar_print (ps,fb,format)
        !           541: PS ps;
        !           542: struct foobar * fb;
        !           543: int format;
        !           544: \end{verbatim}\end{quote}
        !           545: If \verb"format" is \verb"READOUT" the structure should be printed to the
        !           546: stream PS in a ``human readable'' manner, otherwise is should be printed
        !           547: in a form that can be parsed by the ``parse'' function.
        !           548: NOTE in many case both formats will be the same.
        !           549: 
        !           550: \item [\verb"cpy":] This function should take a foobar structure as a
        !           551: parameter and returns a copy of it.
        !           552: 
        !           553: \item [\verb"cmp":] A function that takes two foobar structures and compares
        !           554: them --- returning 0 if they are the same, 1 is the first is considered
        !           555: ``greater'' than the second, -1 otherwise.
        !           556: If there is no appropriate ordering for the syntax, return 2.
        !           557: If an error occurs during the comparison return -2.
        !           558: 
        !           559: \item[\verb"sfree":] A routine to free the structure foobar.
        !           560: 
        !           561: \item[\verb"print\_pe":] The name of an external process to `exec' when the
        !           562: \verb+READOUT+ option is supplied to the print routine.
        !           563: This is generally set to \verb+NULLCP+ which means the default `print'
        !           564: routine is used.
        !           565: 
        !           566: \item[\verb"approx":] A routine to perform approximate matching (if
        !           567: required).
        !           568: The routine should expect two parameters as shown:
        !           569: \begin{quote}
        !           570: \begin{verbatim}
        !           571: foobar_approx (a,b)
        !           572:     struct filter_item * a;
        !           573:     AV_Sequence b;
        !           574: \end{verbatim}
        !           575: \end{quote}
        !           576: The routine should return \verb+OK+ or \verb+NOTOK+ depending on whether 
        !           577: any attribute value in the \verb+AV_Sequence+ approximately matches the 
        !           578: \verb+filter_item+.
        !           579: 
        !           580: \item[\verb"multiline":] If \verb"TRUE" the multi-value attributes will be
        !           581: printed on separate lines:
        !           582: \begin{quote}\small\begin{verbatim}
        !           583: foobar = value1
        !           584: foobar = value2
        !           585: \end{verbatim}\end{quote}
        !           586: otherwise the attribute will be printed on one
        !           587: line:
        !           588: \begin{quote}\small\begin{verbatim}
        !           589: foobar = value1 & value2
        !           590: \end{verbatim}\end{quote}
        !           591: 
        !           592: \end{describe}
        !           593: 
        !           594: \subsection {Where to Add the Syntax Definition}
        !           595: 
        !           596: Where should you add this procedure call, to define the new syntaxes?
        !           597: 
        !           598: This depends on which applications you want to know about the syntax.
        !           599: If you want the DSA and all DUAs to know about the syntax, then this call
        !           600: should be added to libdsap, in the directory dsap/common.
        !           601: The file dsap/common/quipu\_sntx.c is where other similar calls are made.
        !           602: A small test program \verb"test" is included in the common directory, and is
        !           603: made with ``\verb+make test+''.  It takes as input a string representation of
        !           604: attributes, and exercises the handlers.
        !           605: If this works for your new attribute, then it should be safe to re-compile the
        !           606: DSA/DUA and try them.
        !           607: 
        !           608: If you only wish your DUAs to know about the new syntax, then add the call
        !           609: into you DUAs code, before loading the oidtables of calling \verb+dsap_init+.
        !           610: 

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.