How to Read the NDS Schema Reference Document, Part 3: The Attribute Syntax Definition Page
Articles and Tips: article
Senior Editor
Novell AppNotes
nmclain@novell.com
01 Apr 2001
For the last two months I've been describing how to read the Novell Directory Services (NDS) Schema Reference object class and attribute pages. (The NDS Schema Reference document is freely available in the NDK section of the DeveloperNet Web sit at http://developer.novell.com .) This month I'll describe how to read the Attribute Syntax definition page.
About Attribute Syntaxes
An attribute syntax is the basic building block of an attribute. Every attribute is assigned a syntax that defines the attribute value's data format. For example, attribute syntaxes determine whether an attribute stores an integer, string, or stream data. The syntax also defines the matching rules that control the type of comparison operations you can perform on the attribute value when you write code.
You can't extend the schema by creating new attribute syntaxes. You must select your desired syntax from the set of predefined attribute syntaxes. This means that you can't assign a new data type or create an attribute that requires a data type that has not already been defined by the NDS schema.
Also, you must understand attribute syntaxes if you use any of the attribute searching and matching functions because the attribute matching rules use the attribute syntax. The matching rules are described later in this article.
Reading the Attribute Syntax Definition Page
The Attribute Syntax Definitions chapter of the NDS schema reference document lists and defines in alphabetic order all of the attribute syntax definitions that are in the operational schema. The only syntaxes available are those that are already in the operational schema. Since you can't extend the schema by adding new syntaxes, the schema reference contains only one chapter regarding attribute syntaxes.
The Attribute Syntax definition page is similar to the other definition pages we've looked at in previous articles dealing with this subject. Figure 1 shows the Back Link attribute syntax definition page. This is a typical attribute syntax definition page that we can examine in order to find out what information the attribute syntax definitions contain.
Back Link Attribute Syntax Page 1
Attribute Syntax Name
In Figure 1, you can see that the attribute syntax name (Back Link) is followed by a brief description of the attribute syntax's purpose. As a quick reference, the following tables summarize the different attribute syntaxes in the schema and their uses. These tables show only enough information to help you understand the different uses of the different syntaxes. For more detailed information about using the syntax, refer to the NDS schema documentation.
Name Syntaxes.
NDS automatically maintains the distinguished name in attribute values that use any name syntaxes. This is a main reason why you wouldn't want to choose an Octet String syntax for a value that contains a Domain Name (DN). NDS would not maintain the name, and if the object's context changed, your application would have to be responsible for relocating the object and changing its distinguished name.
If the data names an object or helps to locate an object, the attribute will have one of these name syntaxes:
|
Name
|
Description
|
|
Class Name |
Used for attributes whose values represent object class names. |
|
Distinguished Name |
Used for attributes whose values are the names of objects in the NDS tree. |
|
Typed Name |
Used for attributes whose values represent a level and an interval associated with an object. This syntax names an NDS object and attaches two numeric values to it:
The level and interval values are 32-bit numbers and aren't interpreted by NDS. The application must interpret them. |
|
Path |
Used for attributes whose values are a UINT32, Unicode string, and a distinguished name. These values are often used to represent a volume and file system path. |
|
Object ACLs |
Used for attributes whose values represent ACL (Access Control List) entries. An object ACL value can protect either an object or an attribute. The protected object is always the one that contains the ACL attribute. |
|
Hold |
Used for attributes whose values represent an object name/level pair. This syntax is an accounting quantity, which is an amount tentatively held against a subject's credit limit, pending the completion of a transaction. NDS treats the Hold amount similarly to the Counter syntax, with new values added to or subtracted from the base total. If the evaluated Hold amount goes to zero, the Hold record is deleted. |
|
Back Link |
Used for attributes that are a UINT32 and a DN. NDS uses the back Link syntax for Back Link attributes, which NDS uses for its internal management. |
Character String Syntax.
If the attribute value is a character string, the attribute uses one of these syntaxes:
|
Name
|
Description
|
|
Case Exact String |
Used for attributes whose values are strings. When these attributes are compared, upper- and lower-cases must match. For example, the strings "Nancy" and "nancy" would not match when they are compared. |
|
Case Ignore String |
Used for attributes whose values are strings. When these attributes are compared, upper- and lower-cases don't have to match. For example, the strings "Nancy" and "nancy" would match when they are compared. |
|
Case Ignore List |
Used for attributes whose values are ordered sequences of strings, or lists. When these attributes are compared, upper- and lower-cases don't have to match. For example, the strings "Nancy" and "nancy" would match when they are compared. |
|
Printable String |
Used for attributes whose values are printable strings, as defined in CCITT X.208, an RFC which specifies Abstract Syntax Notation One (ASN.1). ASN.1 standardizes the format of data transmitted between systems. |
Numeric String Syntaxes.
If the attribute value is a string of numbers, the attribute uses one of these syntaxes:
|
Name
|
Description
|
|
Numeric String |
Used for attributes whose values are numeric strings, as defined in CCITT X.208, an RFC which specifies Abstract Syntax Notation One (ASN.1). ASN.1 standardizes the format of data transmitted between systems. |
|
Octet String |
Used for attributes whose values are byte strings and aren't interpreted by NDS. |
|
Octet List |
Used for attributes that describe an ordered sequence of octet strings. |
Stream Syntax.
If the attribute value is a stream of data, or a file, the attribute uses this syntax:
|
Name
|
Description
|
|
Stream |
Used for attributes that are login scripts or other stream attributes. Streams are files of information. The data stored in a stream file has no syntax enforcement of any kind. It is purely arbitrary data, defined by the application that creates and uses it. Any attribute defined with this syntax is single-valued. The data size is limited to the maximum free space left on the volume that contains your NDS database. On a NetWare server, this is the SYS volume. Also, this syntax is used whenever the data string exceeds 63 KB. |
Numeric Syntaxes.
If the attribute data is a type of number, the attribute uses one of the following syntaxes:
|
Name
|
Description
|
|
Boolean |
Used for attributes whose values represent TRUE (1) or FALS (0). Any attribute that uses this syntax is single-valued. |
|
Counter |
Used for attributes whose values are signed integers. Any attribute that uses this syntax is single-valued. This syntax differs from the Integer syntax in that any value added to this type of attribute is arithmetically added to the total, and any value deleted is arithmetically subtracted from the total. |
|
Hold |
See the definition in the Name Syntaxes table. |
|
Integer |
Used for attributes whose values are signed integers. |
Address and Phone Number Syntaxes.
If the attribute data is a physical address, such as an e-mail address, a postal address, a network address, or a phone number, the attribute uses one of the following syntaxes:
|
Name
|
Description
|
|
EMail Address |
Used for attributes whose values represent e-mail addresses. |
|
Facsimile Telephone Number |
Used for attributes whose values are strings that comply with the internationally agreed-upon format for showing international telephone numbers, E.123, as well as an optional bit string formatted according to Recommendation T.30, which defines the format of data that is transmitted over a phone line. A telephone number in the E.123 format looks like: +44 171 732 8011. This syntax combines a telephone number with an optional bit string. |
|
Net Address |
Used for attributes whose values are network address in the NetWare environment. The address type indicates the type of communication protocol used (IPTM, AppleTalk, and so on). |
|
Postal Address |
Used for attributes whose values are postal addresses only. An attribute value for Postal Address will typically be composed of selected attributes from the MHS Unformatted Postal O/R Address version 1 according to Recommendation F.401, which is a recommendation for Naming and Addressing for Public Message Handling Service. The value must be six lines of up to 30 characters each, including a Postal Country Name. Normally the information contained in such an address could include a name, street address, city, state or province, postal code, and possibly a postal office box number, depending on the specific requirements of the named object. |
|
Telephone Number |
Used for attributes whose values are telephone numbers only. The length of telephone number strings must be between 1 and 32. |
Time Syntaxes.
If the attribute value has to do with time, the attribute uses one of these syntaxes:
|
Name
|
Description
|
|
Interval |
Used for attributes whose values represent intervals of time in seconds. |
|
Time |
Used for attributes whose values represent time. A Time value consists of a whole number of seconds, where zero equals 12:00 midnight, January 1, 1970, UTC (Universal Time Coordinated). |
|
Timestamp |
Used for attributes whose values mark the time when a particular event occurred or will occur. |
Unknown Syntax.
The Unknown syntax is used for attributes whose attribute definition was deleted from the schema. This syntax is reserved for use by NDS.
Syntax ID
In Figure 1, you can see that the next piece of information on the attribute syntax page is the Syntax ID. The Syntax ID is a 32-bit integer used as an identifier in the Application Programming Interface (API) functions that work with the attribute values. If you need to know the syntax ID, they are defined in the nwdsdefs.h file. You can read this file in a text reader, such as Windows 95/98 Notepad.
For convenience, I've listed the syntaxes and their IDs below:
SYN_UNKNOWN 0 SYN_DIST_NAME 1 SYN_CE_STRING 2 SYN_CI_STRING 3 SYN_PR_STRING 4 SYN_NU_STRING 5 SYN_CI_LIST 6 SYN_BOOLEAN 7 SYN_INTEGER 8 SYN_OCTET_STRING 9 SYN_TEL_NUMBER 10 SYN_FAX_NUMBER 11 SYN_NET_ADDRESS 12 SYN_OCTET_LIST 13 SYN_EMAIL_ADDRESS 14 SYN_PATH 15 SYN_REPLICA_POINTER 16 SYN_OBJECT_ACL 17 SYN_PO_ADDRESS 18 SYN_TIMESTAMP 19 SYN_CLASS_NAME 20 SYN_STREAM 21 SYN_COUNTER 22 SYN_BACK_LINK 23 SYN_TIME 24 SYN_TYPED_NAME 25 SYN_HOLD 26 SYN_INTERVAL 27
LDAP Name
If the attribute syntax has the same definition and purpose as any of the LDAP attributes syntaxes, you can find the names of that LDAP attribute syntax here. Hold is the only NDS attribute syntax that doesn't have a corresponding LDAP attribute syntax.
ASN.1 ID
The next piece of information in Figure 1 is the ASN.1 ID. Every attribute syntax in the NDS schema has an ASN.1 ID assigned to it. (For more information about the ASN1.ID see last month's Directory Primer column about reading the object class definition page.)
API Data Structure
The next piece of information on the attribute syntax page is the API data structure. This shows how the syntax is supported by the NDS API. If you're working with the APIs and need to know about the syntax structure, you can find it here.
Transfer Format
The next piece of information is the Transfer Format. This is the format the syntax takes when it's transferred on the wire. As a general rule, the only time you might need to refer to this information is if you're doing low-level troubleshooting with a protocol analyzer on the wire.
LDAP Format
The LDAP Format is the information below the Transfer Format. If an attribute syntax has an LDAP format, you'll find it here. Attribute syntaxes can have string and binary formats. Sometimes, they have either string or binary formats, and sometimes they have both. This information is useful when you're working with LDAP.
Matching Rules
The next piece of information on the sample attribute syntax definition page is the Matching Rules. These are the rules for matching two values that comply with the syntax. You can search for attributes using three matching rules: equality, ordering and substrings. If you're trying to find attributes that are equal, the attributes' values must be identical and use the same syntax.
NDS won't attempt to match two values if the syntax doesn't allow a match for equality. If you want to find attributes that are less then, equal to, or greater than another attribute, you would use the ordering rule. The rule requires that an attribute syntax must allow these types of comparisions.
Finally, if you want to match attribute values by using a wildcard, you would use the substring matching rule. The matching rule requires that the syntaxes must allow search and comparison patterns that include the asterisk wildcard.
Remarks
The next piece of information is the Remarks section. This section includes any information that might help you use and understand the attribute syntax. This section includes information concerning comparisons, explanations of structure members, and qualifiers.
Used In
As Figure 1 shows, the final piece of information on the attribute syntax definition page is a list of attribute type definitions that use the syntax.
Conclusion
The past three Directory Primer article have given you some basic information about how to read and use the NDS schema reference document. You'll find this document extremely useful when you work with the NDS schema. It'll help you understand the objects and attributes you're working with. It'll also be helpful if you must extend the NDS schema.
* Originally published in Novell AppNotes
Disclaimer
The origin of this information may be internal or external to Novell. While Novell makes all reasonable efforts to verify this information, Novell does not make explicit or implied claims to its validity.