Chapter 18 - Editing an AVD File
After you use the default attribute list to plan which attributes you want STDA to collect, you are ready to assign labels to attributes. You edit the STANDARD.AVD file or you can create a new AVD file.
AVD files can exist in both binary and text formats. As binary files, STDA client programs and StreetTalk attribute editing programs use them to provide labels for attributes. As text files, you edit them to conform to your network attribute requirements.
To edit an AVD file, follow these steps:
1. Run the MAVD program supplied with the software to convert the file from its native binary form to text.
2. Edit attribute view definition files or create new files in any word processing program that accepts ASCII text, such as the EDIT program in DOS.
3. Use the MAVD utility to recompile the file back into binary form for access by STDA client programs.
You can edit and recompile a file as many times as necessary.
Use the MAVD utility supplied with the network software to convert binary AVD files into text and to convert text files to binary files. You must have rights to the subdirectory where the STANDARD.AVD file resides, or you cannot re-apply the file when you convert it back to its binary form. This process is illustrated in Figure 18-1.
In addition to modifying or creating text files, you can also use the MAVD utility to convert AVD files supplied by third-party application developers and merge them with the STANDARD.AVD file. You can convert one or more third-party AVD files to binary format at the same time you convert a STANDARD.AVD file you have edited. Third-party AVD files can also be converted separately.
If you do not want to display or assign values to an attribute collection, you can delete it from the text file. If you decide you want to reinstall the collection later, (for instance, you decide to implement the X.500 standard), you can de-compile the DEFAULT.AVD file using the MAVD utility, copy the attribute collection you want from it, and paste it into the file you are editing.
To decompile the binary AVD file to text format, use the following command syntax:
MAVD /d inputfilename [/o:outputfilename]
where:
/d specifies that the binary file specified by inputfilename will be decompiled, that is, converted to text. inputfilename specifies the path and filename to the Attribute Value Definition (AVD) file you want to convert. The AVD file that is used by default is stored in the MESSAGES subdirectory on the Z drive (for VINES or StreetTalk for Windows NT) to which you are currently connected. You must have administrative rights to convert this file in this directory. /o:outputfilename specifies the path and filename for the decompiled file. You must have administrative rights to output the converted file in the specified directory.
To compile the text files to binary format, use the following command syntax:
MAVD sourcefile1 [sourcefile2] [sourcefile3]...[sourcefilen] /o:outputfilename
Where sourcefile1, sourcefile2, sourcefile3, and sourcefilen specify from one up to ten AVD text source files to be compiled, that is, converted into binary format. The /o: switch can then write all the specified source files to one output file.
The only difference between the syntax for compiling and decompiling a file is the use of the /d switch to compile.
Example
The following command translates the standard.avd file to a file named avd.txt in Smith's directory on a network file service:
mavd /d z:\messages\standard.avd /o:f:\smith\avd.txt
Syntax Errors
The MAVD utility generates error messages when it encounters syntax errors. The error message remain until all the syntax errors are eliminated.
Formatting Characters
The MAVD utility is not line- and field-oriented, and it completely ignores any formatting characters embedded in the file. Theoretically, you can specify an AVD file on a single line as long as the relationship between text labels and attribute or filter references is in the proper sequence.
When you convert a binary AVD file to text, all entries in the filter and attribute definition sections are listed alphabetically. Individual attributes within collections also appear in alphabetic order.
AVD files have History, Filters, and Attribute component sections shown in Figure 18-2.
History - Each time an AVD file is converted or created, a history section is entered at the top of the file. It specifies the last time the file was edited and the person who edited it. Administrators cannot modify the history section.
Filters - Attribute collections appear in STDA client applications based on the type of StreetTalk resources users view at the time. The filter section contains labels and attribute value assertions (AVAs) that StreetTalk resources use as references to define which collections of attributes appear in client applications. (AVAs are described in the next section.) When users look at a User class StreetTalk resource, they see only those collections that apply to "User" class resources.
Attributes - All attribute labels and <v:a> pairs in the AVD file are grouped into logical collections in the attribute section. Each logical collection has a label such as "Group Information" or "Mail Addressing" that defines the type of attributes it contains. Filter labels, which identify the collection as appropriate for display with certain classes of StreetTalk resources, appear on the same line in square brackets, for example, ["StreetTalk Group"].
Under each collection label, attributes for that collection are listed. Next to each attribute is the <v:a> identifier. STDA client applications use <v:a> identifiers in combination with filters to refer to attribute values the service collects. StreetTalk attribute management programs also use them to assign values to programs.
Keywords
AVD files have two keywords: FILTERS and ATTR. Every filter and attribute section in an AVD file must be preceded by an appropriate keyword. If you use keywords as labels for attributes, enclose them in quotation marks.
The filter definition section in an AVD file consists of the keyword label, FILTERS, followed by descriptive labels and attribute value assertions (AVAs). This is illustrated in Figure 18-3.
Filter Labels
Filter labels are enclosed in square brackets (for example, ["StreetTalk Group"]) after an attribute collection label in the ATTRS section. Filter labels indicate that logical collections of <v:a> pairs and labels are displayed together.
For example, if a Collection Label has a reference to the "Users" filter, <v:a> pairs and label or logical collection under it appear when a user or administrator operates on a "User" class object. Attribute values an STDA service collects are available for display under the attribute labels. If a logical collection makes reference to filter labels "Users," "Nicknames," and "StreetTalk Groups," the collection appears when a user or administrator operates on any of those objects.
Each label has a maximum length of 40 characters, and labels that contain empty spaces must be enclosed in quotation marks.
Attribute Value Assertions
Attribute Value Assertions (AVAs) define filters for StreetTalk classes, StreetTalk categories, and STDA classes. Each AVA has the following format:
<v:a> = class
where <v:a> is the vendor attribute identifier and class is a number starting at 1 that identifies the StreetTalk or STDA class or category as shown in Table 18-1:
| Number | Class |
| 1 | User |
| 2 | Service |
| 3 | List |
| 4 | Nickname |
| 5 | Groups |
As a rule, do not change AVAs. If you are an administrator who wants to filter attributes, the filter label, not the AVAs, are important.
Filter labels always contain three AVAs representing the StreetTalk and STDA classes, and StreetTalk category. The order in which AVAs appear on a line does not matter.
The attribute definition section of AVD files consists of related sets of attributes grouped into collections under descriptive labels. These attribute collections have one or more filter labels.
This is illustrated in Figure 18-4 where the Description, Operator, and Rename/Move Status attributes are associated with the StreetTalk Group filter label.
Attribute Collection Labels
Collection labels categorize attribute identifiers and their labels. Each attribute or collection label has a maximum length of 40 characters. Labels that contain empty spaces must be enclosed in quotation marks.
This section describes how to edit AVD files. It provides syntax and formatting rules appropriate to editing different sections of the standard file, as well as guidelines for creating new files.
The AVD syntax is defined by a grammar that can be described using Backus-Naur notation. The following simplified rules are all that you normally need to modify a file. If you edit a filter and encounter a syntax error when you compile the file, you can find detailed information about grammar syntax at the end of this chapter.
Observe the following general formatting rules when you edit AVD files:
Each filter and attribute section must be properly formatted with the keyword FILTERS or ATTRS, followed by a colon preceding each section of definitions. AVD files contain two main sections: the filter definition section and the attribute definition section. The number of filter and attribute definition sections an AVD file can contain is unrestricted, but you can only refer to a filter label in a collection of attributes after you define it. If you refer to a filter label before you define it, an error message appears when you use the MAVD utility to convert the file back to binary form.
Because pre-defined filters already exist for all common resources in the standard AVD list, you normally do not need to make any changes to the filter definition section of an AVD file. Under certain circumstances, however, such as the installation of services developed by third-party vendors, you may need to edit a filter definition or create a new filter.
Format
Each filter definition has the following format:
"Filter Label" [<0:6>= value1, <0:7>= value2, <0:8>= value3]
where:
Filter label identifies the filter for reference by collections. 0:6 and value1 represent the StreetTalk class and define a unique filter criteria. 0:7 and value2 represent the StreetTalk category and define a unique filter criteria. 0:8 and value3 represent the STDA class and define a unique filter criteria.
Example Editing an Existing Filter
Filters are listed alphabetically. The label "FILTERS:" must always precede any filter definitions. The filter list is re-ordered each time the MAVD utility converts an AVD file from binary to text or from text to binary. As long as no filter labels precede a filter definition, you can enter your filter definition on any line.
FILTERS:
"AdminList" [<0:6>=3, <0:7>=10, <0:8>=1]
"Alert Management Service" [<0:6>=2, <0:7>=31, <0:8>=4]
"AppleTalk Agent Service" [<0:6>=2, <0:7>=30, <0:8>=4]
Example Creating a New Filter
The administrator of the Chicago sales office of WCTUS purchases a third-party service that analyzes network activity. When she receives the software, the vendor supplies her with the following label and attribute value assertions:
Name - Network Analyzer
StreetTalk Class - <0:6>=2
StreetTalk Category - <0:7>=1123
STDA Class - <0:8>=4
To create a filter for the service, she enters the name enclosed in quotes, and the assertions in this order, anywhere in the filter section of the AVD file:
"Network Analyzer" [<0:6>=2, <0:7>=1123, <0:8>=4]
After she adds the new filter definition, she uses the MAVD utility described earlier to convert the file back to binary form.
Editing Attributes and Collections
The STANDARD.AVD file supplied with your network software contains a set of attribute collections appropriate for most corporate environments. Often you can apply these collections without modification and begin assigning values to attributes. Sometimes, however, you may need to create or modify whole collections or the attributes within the collections to suit your particular network requirements.
Under some circumstances you may want to collect the same attribute in two different collections using different labels. For instance, you might refer to the QuickPick label "Primary Project" under another collection such as "Job Responsibilities." If you refer to the same attribute in two different collections, the values that appear under each label are identical. However, if you use the same <v:a> identifier with different labels, the second occurrence of the <v:a> identifier overwrites the first.
Example Editing the "Location" Attribute
To edit an existing attribute, modify the existing attribute label or attribute identifier consistent with the <v:a> syntax.
You want to change the label from the default collection "Quick Pick" to "Building Address" :
<0:104> "Location"
Delete "Location" and replace it with "Building Address" as shown:
<0:104> "Building Address"
The edited label is displayed in STDA client applications and StreetTalk editing menus after you recompile the AVD file and copy it to the Z drives of your network that users access.
Creating a New Attribute
To create a new attribute definition in a collection, enter an appropriate attribute identifier and a descriptive label in quotes on a single line inside of an existing collection of attributes.
Note: If you define a new <v:a> pair, make sure that the numbers you select are not reserved by Banyan, are not being used, and will not cause conflicts when you attempt to use them.
Example Inserting a New Attribute
You create a new attribute (<3:201>) labeled "Division." You want to insert "Division" into the "Quick Pick" collection shown:
"Quick Pick" ["Nickname" , "User" ]
<0:1> "Description"
<0:113> "FAX Number"
<0:104> "Location"
<0:103> "Mail Stop"
<0:111> "Phone Number"
<0:125> "Primary Project"
<0:101> "Title"
In this example <3:201> is used. Enter the new <v:a> identifier and the label "Division" on a line anywhere in the collection:
<3:201> "Division"
The new label is displayed in STDA client applications and StreetTalk editing menus after you recompile the AVD file and copy it to the VINES Files services (Z drives) of servers on your network that users access.
Editing an Existing Collection
If you decide to edit an existing collection, you can edit the collection itself or the attributes it contains.
Collection definitions have the following format:
"Collection Name" ["Filter Label1" ,"Filter Label2" ,..."Filter Labeln" ]
Where Collection Name is the label of a collection of attributes and Filter Label1 to n are valid filter labels.
Editing a collection involves one of two tasks:
Edit the collection label. You can edit a collection's label to reflect changes in the purpose of the collection. For example, you might want to change the label of a collection called "General Skills" to a more specific label associated with computer skills named "Software Skills."
To change a collection's label, enter a new text string in place of the existing label. Make sure to retain the quotes. Entering a collection name that already exists in the AVD list generates a syntax error when the file is compiled.
Modify the filter reference. You edit its list of filter labels to change which objects a collection applies to. For example, because most client programs convert nicknames into their full StreetTalk names automatically, you might want to change a collection filter section to refer to Nicknames as well as Users.
To change a collection filter reference, enter a new text string between the filter reference brackets on the same line as the collection name. Separate the reference by a comma from the preceding and next filter references, if any. You can also replace and delete existing labels using the same formatting rules. As noted earlier, the filter label must correspond to a filter that is defined.
Creating a New Collection
Under certain circumstances you may want to create a new collection that defines a logical grouping of attribute information. Any number of logical collections can be created by administrators to aid in the collection and tracking of information critical to their organizations.
Once you decide to create a new collection, follow these steps:
1. Enter a collection label in an attribute definition section of the AVD file.
2. Enter a filter label consistent with the format described in "Editing Attributes and Collections" earlier in this chapter.
3. After you specify the collection label and references, enter <v:a> pairs and labels for the attributes you want associated with that collection.
4. Use the MAVD utility to convert the edited AVD file to binary form and install it in the appropriate directory of the VINES Files service (drive Z) that users access in your network.
Example A Collection of Attributes for Commodity Traders
Every commodity trader employed by WCTUS in its offices around the world has a logical collection of attributes that broadly defines the broker's trading activities. Information tracked in the attributes includes generic data such as the city and country each trader works in, their phone and fax numbers:
"Broker Information" ["Users"]
<0:107> "City"
<0:108 "State"
<0:109> "Country"
<0:104> "Location"
<0:4> "Operator"
<0:113> "FAX Number"
<0:111> "Phone Number"
<3:101> "Immediate Superior"
<3:102> "Trade Ceiling Level"
<0:125> "Principal Commodity"
<3:103> "Active Market"
These attributes duplicate those found elsewhere in the default AVD file such as Quick Pick, and are repeated in the Broker Information collection so users can find all of the information in one place.
In addition to the generic categories, more specialized categories are defined to track and provide data about each trader's activities. The following attributes are defined with the corporate vendor number 3:
Immediate Superior - Defined and maintained by the administrator. This attribute is a string data type.
Trade Ceiling Level - Defined by the administrator and maintained by the individual trader's supervisor. This attribute is a integer data type.
Principal Commodity - Uses the default attribute for "Primary Project." It is maintained by the individual trader's supervisor. This attribute is a string data type. The "Primary Project" attribute has to be deleted. You cannot use a different label for another <v:a> identifier.
Active Market - Defined by the administrator and maintained by the individual trader's supervisor. It refers to the market where the trader typically does business. This attribute is a string data type.
Creating Multiple AVD Files
In theory, you can place an AVD file in any directory and users can access the AVD file. Both the XSTD command used to invoke the STDA client and the MATTR command used to invoke StreetTalk attribute editing commands let you specify the AVD file you want to use. As a rule, however, you should restrict the number of AVD files you maintain on your network. Ideally, you should only use the STANDARD.AVD file with whatever modifications you make to it.
Failure to restrict the number of AVD files can cause a proliferation of slightly different AVD files making it difficult to manage a standardized attribute scheme.
If you want to maintain a separate AVD file to store attribute information specific to the management of your network or for some activity that you do not want users to ordinarily see, store the AVD file in a location other than drive Z (native VINES and StreetTalk for Windows NT). You can then use StreetTalk programs to assign and view values for these special attributes.
Note: Creating a separate AVD file for information you want to restrict does not prevent users from running the XSTD program to access it. You must set appropriate access rights on that AVD file to prevent access. However, once information in a local AVD file is in StreetTalk, any user can view it.
Creating Multilingual AVD Files
Normally you use the STANDARD.AVD file for attribute definitions. However, under certain circumstances such as creating AVD files for different languages, you will need to create more than one AVD file. The following sections discuss how to create new AVD files in your native language and in other languages.
While you seldom have cause to create a new AVD file in your native language, under certain circumstances, you may want or need to create a unique file. New files can replace your existing STANDARD.AVD file or serve as additional files for specialized purposes. To create a new AVD file in your native language, follow these steps:
1. Convert the STANDARD.AVD file using the MAVD utility. If you are using the AVD file for a specialized purpose (that is, accessing it through the XSTD command and using the /V: parameter to point it at a specific file), you should decompile the AVD file to a local drive. Otherwise, decompile the AVD file in /MESSAGES.
2. Enter filter labels consistent with the format described in "Editing an Existing Collection" earlier in this chapter. Do not remove the FILTERS section label.
3. Modify any labels in the FILTERS section that need different meanings. Do not remove the FILTERS section label.
4. Delete all attribute collections you do not intend to use. Do not delete the ATTRS section label.
5. Insert new attribute collections using the rules described earlier in this section.
6. Compile the file to /MESSAGES or a local directory.
AVD files are well-suited to defining attributes in multilingual environments. If your organization's operations span a number of countries in which different languages are spoken, you can maintain a master AVD in your native language and localize the list.
You can distribute these translated lists to network operators in each geographic location where the operators can apply them to the appropriate directories on their network.
In multilingual versions of VINES Files, the labels in each country's AVD lists are translated. Creating a new AVD file in a language other than English is essentially a matter of editing text strings in the AVD file in the local language. To create a file, follow the steps outlined in the previous section, "In Your Native Language."
Converting Third-Party AVD Files
To merge a third-party AVD file with the AVD file your STDA and StreetTalk client programs service, insert the third-party files as one of the ten source files you are allowed to convert at one time.
Under certain circumstances, such as upgrades or service restorations, the DEFAULT.AVD file is replaced. When you install a new version of your network software or restore the VINES Files (drive Z) service on a server the following happens:
1. The STANDARD.AVD file is compared to the DEFAULT.AVD file to see if that file was modified.
2. If the STANDARD.AVD file was edited and recompiled, the DEFAULT.AVD file is replaced with the newer version. If the files are identical, both files are replaced with the newer version.
This section describes syntax rules of AVD source files that use the Backus-Naur notation system used to create and modify attribute definition files.
Figures 18-5 to 18-7 describe the syntax used in AVD source files.
