Chapter 13 - Managing STDA Inclusions
STDA inclusions allow you to include non-StreetTalk names, with attributes, in the database of an STDA master or satellite service. Non-StreetTalk names typically include those of users on other networks with mail gateway addresses.
You can also use inclusions to add StreetTalk names of users on servers with restricted access to the network. In both cases, you view and search for those names just as if they were StreetTalk names. For more information on restricted access, refer to Chapter 10 or Managing StreetTalk for Windows NT Services, or the Intelligent Messaging Administrator's Guide.
After you add an inclusion file to an STDA service's database, the service rebuilds. Inclusion files are then sent as part of the downloaded database whenever an STDA satellite service requests a download.
A satellite service can have locally defined inclusions in addition to those it downloads from, merging them into a new list that is downloaded to other satellite servers requesting inclusions. Because you can configure satellites to not collect inclusions from masters and satellites they download from, a user's access to information can be controlled. By localizing inclusions used by a subset of your network users, you can restrict their access to other users across the network.
After you specify the inclusions file to an STDA service, a rebuild of the service starts within 15 minutes. The exact length of time it takes for the inclusion to show up in the service's database depends on factors such as database size and whether the database is a master or a satellite.
STDA satellite services that download from a service where inclusions have been submitted do not receive the new inclusions until their next scheduled rebuild times. This schedule can sometimes result in different sections of your network having more complete views of the network than others. You should plan your rebuild schedule accordingly. More information on this topic is available in Chapter 11.
Note: STDA inclusion names support the same characters, including multinational characters, in the same way as StreetTalk. However, only supported multinational characters should be part of inclusion names. If unsupported characters are added, the results are unpredictable. For information on supported multinational characters, see Chapter 3.
Formatting an Inclusion Parameter
The format of an inclusion parameter is:
LABEL: [labeling text]
DESC: descriptive text
ADDR: [address-pattern]<-----------blank line
ATTR:<v:a>[string value]
<-----------blank line
ATTR:<v:a>[string value]
<-----------blank line
Each inclusion begins with a LABEL keyword and ends with a blank line character.
LABEL is the only keyword you must enter; other keywords are optional. Enter each keyword in upper- or lower-case letters, followed by a colon (:). The blank space between a keyword and its field is optional.
The following descriptions cover the function of each keyword available for inclusion entries:
LABEL - Text in the LABEL field appears as a name in the Users class of the STDA database, and has a maximum length of 31 characters. All inclusion entries must have a label.
DESC - Text in the DESC field appears in the description field at the bottom of the STDA screen when the cursor is positioned on the corresponding user name. The DESC field has a maximum of 63 characters and is optional.
ADDR - The address pattern that appears in the ADDR field is used in Intelligent Messaging. When a user selects an inclusion from the STDA client's list of names and places it in a message header, the inclusion's address pattern in used as the address of that recipient. A user only sees the address pattern expanded in the message header if the mail message is retained in the mailbox before being sent. You may use carriage returns in the ADDR field. The ADDR field has a maximum length of 511 characters and is also optional.
Note: If you specify a server name in the ADDR field, you must specify a Banyan server.
ATTR - The ATTR field allows you to establish string values for attributes associated with inclusions. You may enter as many attribute values as you want, each separated by a newline character. The ATTR field has a maximum length of 4096 characters and is also optional.
The inclusion program accepts one or more of the special newline characters, or their hexadecimal equivalent if you use a program to generate inclusion files.
The newline character arrangement varies according to the word processing or editing program you use to prepare the inclusion file. The newline character is inserted into the inclusion file automatically when you press ENTER and may not be visible to you.
A blank line must follow ADDR and ATTR lines in the file. (Two or more consecutive newline characters is also a correct format.)
If you create an inclusion file that has no blank lines between the ADDR and ATTR, add the inclusions to the STDA database, and then retrieve them from STDA, you get unexpected results. If the file has blank lines, what you entered is returned.
For example, entering a file with this entry that contains no blank lines:
LABEL: John Smith
DESC: Engineering Manager XYZ Corp via mail gateway
ADDR: SSWGATE@USCHI01@SERVERS[Smith.ATST]
ATTR:<0:100> 2
results in an incorrect file that looks like this when it is retrieved:
LABEL: John Smith
DESC: Engineering Manager XYZ Corp via mail gateway
ADDR: SSWGATE@USCHI01@SERVERS[Smith.ATST]ATTR:<0:100> 2
The following file is displayed correctly when it is retrieved and the entries will be correctly displayed from STDA:
LABEL: John Smith
DESC: Marketing Manager XYZ Corp via mail gateway
ADDR: SSWGATE@USCHI01@SERVERS[Smith.ATST]<-----------blank line
ATTR:<0:100> 2
<-----------blank line
Note: Do not place any blank space characters at the end of the line before you press ENTER.
Preparing and Applying Inclusion Files
The following section describes procedures for creating and editing inclusions files.
To prepare an inclusions file, list your inclusions together in a text file, using any text editor that can store the file in ASCII format. Separate each entry from the next with a newline character, as explained in "Formatting an Inclusion Parameter" earlier in this chapter.
Example Sample Inclusions File
A short list of STDA inclusions may look like this:
Label: Dave's List
Desc: Vice President of Sales, x2232
Addr: ServerOne[Dave Zwibeck@Sales@WCTUS],
ServerTen[Lee Anderson@Admin@WCTUS],
SMTPgate@TechSppt@WCTUS[William Bruford@X.CS.CMU.EDU],
Theodore Bair@Mkting@WCTUSATTR:<1:106> 118 Decalb St.
ATTR:<1:111> 555-2223
Label: World Commodities Trading
Desc: (617) 555-1000
Label: Jack Robinson
Addr: SMTPgate@TechSupport@WCTUS[Jack Robinson@MIT]ATTR:<1:106> 321 Binney St
ATTR:<1:107> Cambridge MA
Label: Rachel
Desc: part-time system operator
Addr: Rachel Wallace@TechSupport@WCTUS
When there is more than one entry in the ADDR: field of an inclusion, the addresses must be separated by commas. The final address does not receive a comma. This syntax is illustrated in the previous example.
Use inclusions to list together:
StreetTalk names StreetTalk names on servers with restricted access Non-StreetTalk names with mail gateway addresses
Example Inclusions List
This example is an STDA inclusion:
Label: Rachel's Group
Desc: Assistant operator's mailing list
Addr: ServerOne[Dave Zwibeck@Sales@WCTUS],
ServerTen[Lee Anderson@Admin@WCTUS],
SMTPgate@TechSppt@WCTUS[William Bruford@X.CS.CMU.EDU],
Theodore Bair@Mkting@WCTUS
After this inclusion is added to the database of an STDA service, select Rachel's Group from the names listed on the STDA screen to send mail to:
Dave Zwibeck and Lee Anderson (both users in groups on restricted access servers) William Bruford (a user on another network with a mail gateway address) Theodore Bair
Note that Rachel's Group appears under the Users class on the STDA screen. This relationship is true of all inclusion labels.
If two inclusion file entries with identical label entries exist in the STDA database, they must have different attribute values specified in an ATTR entry to differentiate them. Use administrative attribute <0:100>. (Chapter 16 has more information on this attribute.) The values that you enter do not matter but they must be different for each user who has the same label. If identical label values exist, configure them so that a user can tell them apart by reading the description field.
In addition, when identical label values exist, using them from within Intelligent Messaging may be confusing. When a user runs STDA from within mail and selects the first name (based upon the order in which they are listed in STDA), the name is placed on the message's address line (TO, CC, or BCC). When a user selects another name that is identical to the first name, the string value of the ADDR entry of the second duplicate name is placed on the message's address line instead.
For example, suppose you want to add three identical non-StreetTalk names to the STDA database. These names refer to three different people in three different companies. In this sample inclusion file, the LABEL fields are identical (John Smith) but the DESC and ADDR fields are different reflecting the different companies these individuals work for and the different addresses of their companies.
Example Sample Inclusions File
This is a sample inclusion file.
LABEL: John Smith
DESC: Marketing Manager XYZ Corp via mail gateway
ADDR: SSWGATE@USCHI01@SERVERS[Smith.ATST]ATTR:<0:100> 1
LABEL: John Smith
DESC: Third party developer - Start Software Inc.
ADDR: smtp@uschi03@servers[John Smith@Start.Com]ATTR:<0:100> 2
LABEL: John Smith
DESC: Sales Manager ABC Reseller Houston
ADDR: MCIGate@USCHI01@SERVERS[JSmith.ABC]ATTR:<0:100> 3
When the attributes in this file are loaded into STDA and you search for a name, you see three consecutive "John Smith" entries. If you highlight the first entry, you should see the first description ("Marketing Manager XYZ Corp via mail gateway" ). Highlighting the second label should show the second description ("Third party developer - Start Software Inc." ) and so on.
If you select just the first John Smith entry to bring it into mail, your To: address field displays:
To: John Smith
If you select just the second John Smith entry to bring it into mail, your To: address field displays:
To: smtp@uschi03@servers[John Smith@Start.Com]
If you select all three John Smith entries in STDA and bring them into mail, your To: address field displays:
To: John Smith, smtp@uschi03@servers[John Smith@Start.Com],
MCIGate@USCHI01@SERVERS[JSmith.ABC]
Once you select F10 in mail to send or to save the message, all inclusion address entries are resolved and stored as the string value of the ADDR entry. The To: address field displays:
To:SSWGATE@USCHI01@SERVERS[Smith.ATST],
smtp@uschi03@servers[John Smith@Start.Com],MCIGate@USCHI01@SERVERS[JSmith.ABC]
An address associated with a unique label or with the first occurrence of a duplicate label is replaced by the string value associated with the ADDR entry. The addresses associated with other labels that have identical label values are not changed since they already appear as the string value of the ADDR entry.
Note: All of the above examples are based upon how the Banyan Intelligent Messaging client program works. Other mail client programs that use STDA may work differently.
You cannot edit an STDA service's list of inclusions from your Banyan Management Tool (StreetTalk Explorer or MSERVICE). You must use a text editor. However, you can edit new or existing inclusions files and apply them to the STDA database you manage.
From StreetTalk Explorer:
1. If you know the STDA name, right-click the STDA service in the right pane and select Properties from the Context menu.
To locate the STDA service for a particular group, enter *@groupname@servers in the Browse field and press ENTER, then click the Services icon. Right-click the STDA service you want in the right pane and select Properties from the shortcut menu.
2 Click the Inclusions tab.
3 Click Add, Modify, or Delete and select a file from a dialog box.
Add from File - STDA uses the file in the next rebuild as its sole source of inclusions. It overwrites any previous inclusions.
Modify from File - STDA uses the file as a change file. In the next rebuild, it adds any names in the change file to the existing inclusions.
Delete from File - STDA uses the file as a change file. In the next rebuild, it deletes any names in the change file from the existing inclusions.
From the System Prompt:
1. Make sure that the STDA service is running.
2. Enter MSERVICE from the command line or select it from the MANAGE menu. The Manage A Service menu appears.
3. Select CONTROL the service. The Control A Service menu appears.
4. Select CONFIGURE service. The Configure STDA Service menu appears.
5. Select MANAGE inclusions. The Manage STDA Inclusions menu appears.
6. Select an option:
Get /Write Inclusions to a file - Extracts existing inclusions from the service you are managing and writes them to a file you specify. This file can then be edited and re-applied to the service.
Enter a filename to which you want the inclusions currently maintained on the server written.
Delete Inclusions from a file - Takes the contents of a file you specify, compares them to those maintained on the service you are managing, and deletes any inclusions from the service that are in the file.
Enter the name of the file you want to use as source deleting existing inclusions on the service you are managing.
Add Inclusions from a file - Takes the contents of a file you specify and adds them to the service you are managing.
Enter the name of the file you want to use as source for adding existing inclusions on the service you are managing.
Replace Inclusions from a file - Takes the contents of a file you specify and overwrites any inclusions maintained on the service you are managing.
Enter the name of the file you want to use as source for overwriting existing inclusions on the service you are managing.
After You Select An Option
After you enter a pathname, STDA immediately processes the list for errors. If an error is detected, a message appears informing you of the type of error and its approximate location. The program halts further processing of the file and you must click Close or Finish (your Banyan Management Tool) or press ESC (MSERVICE) to exit the screen. Edit the file, then repeat the steps.
When no errors are detected, the inclusion list is added to the service. This message appears as a confirmation:
--> Inclusions replaced.
