OR(3)

NAME
or - library of O/R-address routines.

SYNOPSIS
cc [flags] files libpp.a [libraries]

DESCRIPTION
The or library provids a set of routines for building, transforming and manipulating X.400 O/R Names. Most routines work on a doubly linked list of structures representing the elements of the O/R Name. The list is kept in an ordered sequence of elements, with the "most significant" elements at the top. Significance is determined by "lowness" in the assocaited #defines. This is an extension of the precedence defined in RFC 987. Some of the choices are arbitrary, and do not really matter. The basic type is the OR_ptr which is defined in the header file or.h. The routines are provided to work at various levels of complexity.

  PRIMITIVE ROUTINES
#include "or.h"

or_init ()

OR_ptr or_add (list, or, before)
OR_ptr list, or;
int before;

or_cmp (or1, or2)
OR_ptr or1, or2;

OR_ptr or_dup (or)
OR_ptr or;

OR_ptr or_find (tree, type, ddname)
OR_ptr tree;
int type;
char *ddname;

or_free (or)
OR_ptr or;

OR_ptr or_lastpart (or)
OR_ptr or;

OR_ptr  or_locate (or, type)
OR_ptr or;
int type;

OR_ptr or_new (type, ddname, value)
int type;
char *ddname, *value;

char    *or_value (or, type)
OR_ptr or;
int type;

These routines are the primitive interface to the or package. Most routines use symbolic values to refer to the different components. These are the following

#define OR_C            1
#define OR_ADMD         2
#define OR_PRMD         3
#define OR_O            4
#define OR_OU           5
#define OR_X121         6
#define OR_TID          7
#define OR_UAID         8
#define OR_S            9
#define OR_G            10
#define OR_I            11
#define OR_GQ           12
#define OR_DD           99

In general if a routine fails then it returns either NOTOK if the return value is an integer, NULLOR if the return value is an or element and NULLCP if the return value is a character string. or_init initialises the package. It should be called before any other routines although more commonly a higher level initialising function is used. or_new creates a new element of the given type with the given value. If the element is a domain defined attribute, then ddname is the name of the attribute. All parameters are copied into allocated memory. or_add adds a new or element to the list, and inserts it in the correct place in the hierarchy. It will not allow duplicates, except for DDs and OUs. If the flag before is set and the element type is a recurring type, then the element is added before other elements of the same type. This flag is to cope with some of the oddities of EAN and RFC 987. or_cmp compares two elements. It returns true if the two elements are the same. or_dup duplicates an or element. Finally, or_free releases the storage associated with an element when finished with. or_locate locates an element of a specified type in a tree. or_find is a version generalised to acces domain defined. or_lastpart identifeis the last element of an or_tree. or_value returns the value of the first occurence of the specified type.

  CONVERSION ROUTINES
or_or2std (or, buf, nicepn)
OR_ptr or;
char *buf;
int nicepn;

OR_ptr or_std2or (str)
char *str;

or_or2dmn (first, last, buf)
OR_ptr first, last;
char *buf;

OR_ptr or_dmn2or (istr)
char *istr;
or_or2rfc (or, result)
OR_ptr or;
char *result;

or_rfc2or (rfc, or)
char *rfc;
OR_ptr *or;

PE or2pe (or)
OR_ptr or;

OR_ptr pe2or (pe)
PE pe;

These routines, in general, manipulate between OR_ptr trees and various forms of string. or_or2std maps an OR_ptr into RFC 987 std-orname (for human consumption). If nicepn is set, it produces a more readable, but illegal, version. or_std2or performs the reverse mapping. or_or2dmn and or_dmn2or do the same for the machine interpretable dmn-orname encodings of RFC 987. For or_or2dmn , the first and list paramters enable specification of an (inclusive) section of an OR_ptr tree to be encoded. or_or2rfc and or_rfc2or perform mappings between RFC 822 addresses and OR_ptr trees, according to RFC 987. or2pe and pe2or perform mappings between OR_ptr trees and PE pointer ones. They are PEPY generated routines. See the ISODE 5.0 documentation for more details.

  STRING ROUTINES
or_asc2ps (ascii, ps)
char *ascii, *ps;

or_ps2asc (ps, ascii)
char *ps, *ascii;

The first two routines convert between ascii character strings and the printable string encoding of the ascii string as specified in RFC-987.

  OTHER ROUTINES
OR_ptr or_default (or)
OR_ptr or;

or_default inserts local default components into partially specified OR Names.

SEE ALSO
ISODE 5.0 documentation.
The PP Manual: Volume 1 - Installation and Operation

FILES
Various tables, including: rfc2or/or2rfc (for 987 mappings); or (for or_check).

BUGS
Need to add an or_undefault function.