2. Tool Layout
General layout of the tool
In addition to the menu bar just below the title bar the Maintain viewer has three subviewers (four subviewers if in wizard mode). The first subviewer is the State Subviewer, the second subviewer is the Command Subviewer, and the last subviewer is a the Typescript Subviewer. Additionally, if in wizard mode, there is another subviewer (the Wizard Subviewer) before the typescript viewer. This wizard mode viewer contains a number of buttons for controlling wizardly type things.
A note about Help
Maintain uses PopUpButtons and its associated help facility. To use this facility hold down the mouse button over a command button (rather than "clicking"). After a moment you will get a PopUp menu. If you continue to hold the mouse button down you will notice that you will get a one line description of each option in the menu as you move the mouse around. Additionally, The top item in the menu will be "Help". If you select "Help" this will cause PopUpButtons to open up MaintainDoc.tioga and position it at a location relevant to the command you selected. (Note: to get help for guarded buttons you must click once to first remove the guard then hold down the button to get help.)
The Menu bar
The Menu bar contains a number of operations that are similar to those found in other tools.
STOP: Abort the current operation as soon as possible. This may take a few minutes if in the middle of a long courier call to a remote machine.
Another: Make another Maintain viewer. Multiple Maintain viewers may be run simultaneously. The mouse button controls the placement of the new viewer: left -> left column, right -> right column, and middle -> color column. Additionally, the shift key will cause the new viewer to be iconic.
Help: Gives a short explanation of how to use the PopUpButtons Help facility.
Find, Word, Normalize, PrevPlace: Operates on the Typescript Subviewer just like Tioga viewers.
Scratch: Toggles the existence of the "Scratch" rope in the Command Subviewer. This is just to help you save a bit of real-estate if you'd like. The value of Scratch is preserved even when you can't see it.
State Subviewer
As the name implies, the state subviewer is used to set the state of the Maintain Tool. As the state is changed other subviewers may come or go and the contents of the other subviewers may change. For example, the number of command buttons in the command subviewer grows as you change state from the Level of Normal to the level of Wizard.
Level: selects among
Normal,
Owner,
Administrator, and
Wizard depending on the degree of maintenance desired. It is best (safest) to only select the minimum level needed to get the job done. These levels are ordered, that is
Normal
is the least powerful while
Wizard
is the most powerful. The inner workings of both the GV and NS systems will still prevent a user from changing something that they are not allowed to change.
Normal allows virtually all query operations but only a few limited update operations, such as changing your own password.
Owner adds the ability to add and delete members, friends, and owners to groups (DLs) that one is the owner of.
Administrator adds the ability to add and delete objects to/from either registries and/or domains that you are an administrator for. In some cases you also gain the privilege to add and delete members, friends, and owners to/from groups, even if you aren't an explicit owner.
Wizard adds the fourth subviewer that gives you the ability to control a number of special switches within Maintain. These switches allow you to do such things as disable verification of members being added to a group and to explicitly set the server that queries and updates are directed to.
Verbose: When on (inverted) certain commands may provide additional information.
Mode:
DWIM uses GV or NS mode as a function of the names given to a particular command. For DWIM to select GV mode a name must have a period in it. Additionally, it should not have a colon in it, unless the first part is in quotes. DWIM mode is really quite good and is the preferred operating mode. Many of the automatic features of Maintain only operate when in DWIM mode.
GV forces all operations to pertain to the Grapevine database.
NS forces all operations to pertain to the ClearingHouse database.
Command Subviewer
The Command Subviewer has a number of buttons to invoke different commands. These buttons are grouped by the general type of operation that they perform: Type, IsMember, Set, Add, Remove, and Misc. All of these commands take some number of parameters. The user provides these parameters using the Name: and Argument: fields. There is also a Scratch: field provided for the user to do with as they wish. The value of all of these fields: Name, Argument, and Scratch may be set by making a selection and then middle-clicking on the field name; this is in a addition to conventional type-in.
The exact interpretation of both the Name: and Argument: fields are a function of what command is invoked with these values. In general, Name: is used to specify one or more names, possibly wildcarded, as the main subject of a given command. The main subject is the Grapevine/NS database entry you wish to query or modify. Names should be separated by commas or CR. Spaces are significant and do not separate names. Quotes around an entire name serve to group the enclosed letters as a single name, the quotes themselves are not passed on to the GV or NS systems. Quotes around the first part only of a GV looking name serve to group the enclosed letters as a single word and are included as part of the name. On non-quoted names leading and trailing whitespace is stripped off. Quotes must be used to generate names with leading or trailing whitespace. (As ugly as it is some NS names have leading or trailing whitespace!)
Wildcarding is supported using *. This may appear anywhere in a name, and more than once. It is generally a good idea to specify a name as completely as possible. The expansion of some wildcards can be very costly.
Argument: is often a name or list of names as just mentioned for Name:, but, for some operations, the entire Argument: field is taken as-is, such as in the Set Group Remark command.
Type: covers such things as listing names that match a given pattern, giving a summary of a given object, showing the mapping between a GV and NS name, etc.
IsMember: returns the status of membership for a given user in a given group.
Set: initializes and/or changes some value in the database.
Add: adds an element to some list such as a member to a group.
Remove: removes an element from a group.
Misc: contains such functions as the creation and deletion of a whole object.
Wizard Subviewer
Verify: When on, checks all arguments that are objects to see if they are valid or not. For example, when Verify is on it is impossible to add an invalid name as the member of a group.
Quote: When on it asserts that the entire rope in the Argument: button in the command Subviewer is a single name, exactly as it appears.
GV/MS updates: must be on in order to make changes to any objects in the .gv and .ms registries in the GV database.
Auto Delete: When on the TypeFinks command will not only indicate "bad" members in DLs but will also try to clean things up.
Debug: Enables some debugging diagnostics when on.
UpdateMap: causes the cached GV<->NS mapping information to be updated. In practice this map is very static (on the order of one change per N weeks) and rollback and/or booting is good enough. Clicking this button with the right mouse button will give you the statistics of the map rather than do an update. The statistics include: when the map was last updated, whether there were any troubles updating, the number of times the map has been updated, them number of entries in the map and the number of times the map has been consulted.
SetServer: points database operations at a particular server. An empty Host name will reset the NS world back to using all/any server. Clicking with the left mouse button uses DWIM to decide GV/NS node. The middle button forces GV mode and the right button forces NS mode. Be warned: that the GV servers doesn't stick. That is to say that it sticks only as long as that explicitly targeted server can answer all questions asked of it.
Host: provides the server name/address for the SetServer button above.
3. Commands
Below is a summary of all of the command buttons. The name of each button is followed by a description of what that button does. A description of exactly what the Name: and Argument: fields provide for that command is also given.
When the Name: parameter says it provides a "list of ..." that list may be different names separated by commas and/or patterns that will expand to zero or more names.
For the "normal" case all commands should be invoked with the left mouse button and without the SHIFT or CONTROL keys held down. Some commands act differently than "normal" if invoked with a different mouse button / SHIFT / CONTROL combination. Alternately, you can select a variant of the command by using the PopUpButtons PopUp menu feature. This is actually the preferred means of invoking a special feature since the accelerators (mouse button / SHIFT / CONTROL combinations) may change over time. Not all command variants are documented, sigh.
Matches: List all names matching the given pattern. The default is to check all group and user (individual) objects.
For the NS world other classes of objects may be checked by using the PopUpButtons PopUp menu. (Yes, you can use accelerators too but the intent is to use the pop-up menu.) Most of these classes are straight forward except for the FromSelection class. In this case the selection can be a property number (such as "42"), an abbreviation (such as "PS" for Print Service) or even full property names (such as "printService" or even "Print Service" or even just "print").
There is one very special case of a
FromSelection match. If you select a valid NS host address then only objects with the addressList property will be checked and then only those with a matching host addresses will be printed.
Name: list of names to match
Argument: ignored
Members
: List the names that are direct members of the given groups.
Name: list of groups
Argument: ignored
Summary
: Give a summary of the supplied names. A summary includes things such as the full name, a remark, owners (if a group), etc.
Name: list of names to summarize
Argument: ignored
Details
: Give a detailed summary of the given names. This is basically a summary as above but includes more detail.
Name: list of names to summarize in detail
Argument: ignored
Mapping
: Both Grapevine and NS have facilities to send mail to the other system. They achieve this by having a mapping from names in one system to names in the other. For example, the NS name "User:PARC:Xerox" can be reached from GV using the GV name User.parc. This example looks trivial because the NS Domain and the GV pseudo registry are identical, this will not always be the case. In general, the mapping command will take either a real or pseudo name in either GV or NS form and return the mapping to go to or from the other system. Right clicking this command will additionally check the name to see if it actually exists or not.
Name: list of names to be mapped
Argument: ignored
Domains
: List all Domains matching the given patterns. For example, the pattern "P*:Xerox" will list "PARC:Xerox" and possibly other domains. As with all NS names, the organization will default to that of the logged in user. This command will also work for matching GV registries but the Mode switch must be used to force GV mode.
Name: list of patterns to match domains/registries
Argument: ignored
Organizations
: List all Organizations matching the given patterns. For example, the pattern "X*" will list "Xerox" and possibly other organizations.
Name: list of patterns to match organizations
Argument: ignored
Finks: This command is mainly for administrative use.
For GV groups it finds and lists members that have their mail forwarded to the NS world.
For NS groups it lists all members that map to GV names. Additionally, if the
Verbose switch is on, it will check each member to see if it is a valid object and other such things.
NB: with the verbose switch on it may take a long time to do a group of any size because it has to get information from many different CHSs, some of which may be down and the time-outs are long... Additionally, if the
Auto Delete switch is on, not only will the "finks" be listed but the noSuchXxxx finks will automatically be deleted from the group. This assumes that you have the credentials to do so.
Name: list of groups to be checked for finks
Argument: ignored
Dead Matches
: This command is mainly for GVSupport use. It lists all RNames that match the given pattern and that have been recently deleted.
Name: list of names to match dead GV entries
Argument: ignored
Dead Details
: This command is mainly for GVSupport use. It gives a detailed summary of all matching RNames that have been recently deleted.
Name: list of dead GV entry names to summarize in detail
Argument: ignored
Direct
: Tests to see if the named groups has the supplied arguments as direct members. This is much simpler than listing the members of a group and then manually checking to see if some name is in that list. This command will report "IS a DIRECT member" or "is NOT a DIRECT member" depending on the outcome.
Name: list of groups to be checked
Argument: list of potential members (can be groups or individuals)
Extended: Similar to Direct as above but will recursively check for membership in groups that are members. This is the same membership test that is used by most (all?) access control facilities. GV actually has two subtle variations of IsMember Extended. In one variant only those names that end with an ^ (up-arrow) are recursively checked. The other variant actually checks every name to see if it is a group or not and then recursively check those groups. This Maintain command actually calls the variant that uses the ^ hint. As far as I know, this is what is actually used by other services such as IFS for access control.
Note: There is a difference between "members" of a group and the set of individuals that will receive a message if you send mail to that same group (or even some "individual"s for that matter). The complication has to do with forwarding, aliases, cross-world mail (GV/NS/Arpa/...), etc. This is a huge can of worms and Maintain doesn't even attempt to figure it out (at least not yet).
Name: list of groups to be checked
Argument: list of potential members (can be groups or individuals)
Occurrences
: IsMember Occurrences lists only those groups that match the given pattern AND that have the given argument as a direct member.
Set Occurrences is mainly for GVSupport use. It enumerates all groups matching the given pattern(s), if the first name in the arguments is a member of a group it will delete them and then add the second name in the argument as a new member. This is what needs to be done if someone changes their name. Remove Occurrences is mainly for GVSupport use. It enumerates all groups matching the given pattern(s) and removes any and all arguments that are members. Presently Set and Remove commands don't take care of the owners and friends fields, they should.
Name: list of groups to be checked
Argument: list of potential members (can be groups or individuals)
Password: At the normal and owner level this command is of the set MY password form, the Name: field should be set to your account name. At the administrator and wizard level the password of the supplied name is changed. In either case the new password is taken from the entire argument.
In the NS world there are actually two types of passwords: strong and simple. This command only changes the strong password. To change your NS simple password use the Simple Pwd command. (At present, your strong and simple NS passwords should probably be kept the same.)
NOTE: it is customary and convenient in our environment to set both your GV and NS passwords to the same thing. To do this you will actually need to set three passwords: your GV password, your NS (strong) password, and your NS simple password.
ALSO NOTE: changing your password(s) using maintain does not change your user credentials (your logged-in name(s) and password(s)). You probably want go to idle and log back in under the new password(s).
Name: The individual's name whose password is to be changed
Argument: the new password
Simple Pwd
: This command functions just like the
Password command above, except that it changes the simple password of the NS world.
Name: The individual's name whose simple password is to be changed
Argument: the new simple password
Indv Remark
: Change the remark information for the given individual. In the GV world individuals don't actually have a remark field, they have what is known as a
connect field. In most cases (except for the names of some servers) this connect field is just as good as a remark field. This command actually changes this connect field if the name provided is a GV individual.
Name: the individual whose remark is to be changed
Argument: the new remark
Group Remark
: Change the remark information for the given group.
Name: the group whose remark is to be changed
Argument: the new remark
File Serv
: In the NS world individuals can have a default File Service property. This sets that value.
Name: the NS individual whose default File Service property is to be changed
Argument: the new File Service name
Self
: Add/Remove yourself as a member to/from the groups listed. For split-DLs (groups that have sub-groups in both the GV and NS worlds) this command will try to add/remove you to the sub-list rather than the top-level list.
Name: list of groups that you wish to Add/Remove yourself to/from
Argument: ignored
Member
: Add/Remove members to/from the groups listed. If only at the
Normal or
Owner level this command will try to add/remove members from the sub-list rather than the top-level list of split-DLs (groups that have sub-groups in both the GV and NS worlds).
Name: list of groups that you wish to Add/Remove members to/from
Argument: list of members
Owner
: Add/Remove owners to/from the groups listed. In the NS world owners are known as
administrators.
Name: list of groups that you wish to Add/Remove owners to/from
Argument: list of owners
Friend
: Add/Remove friends to/from the groups listed. In the NS world friends are known as
self controllers.
Name: list of groups that you wish to Add/Remove friends to/from
Argument: list of friends
Mailbox
: Add/Remove mailboxes to/from the individuals listed.
Name: list of individuals whose mailbox list is to be changed
Argument: list of mailboxes
Forwarding: Add/Remove forwarding to/from the individuals listed. The implementation of forwarding differs between the GV and NS worlds. Therefore, this command functions differently depending on whether you are dealing with GV or NS names.
For GV names this command actually adds/removes members from the forwarding list. When the list is empty forwarding has been "removed".
For NS names this command actually adds/removes the group and members properties to the individuals named. You must use the Add/Remove Member command to actually change the names on the "forwarding" (group/members) list. Mailboxes should first be removed when adding forwarding to an NS name. (This is a precaution, I don't know if it's actually necessary.)
GV:
Name: list of individuals whose forwarding is to be changed
Argument: list of names to forward to
NS:
Name: list of individuals to add/remove forwarding to/from (group and members properties)
Argument: the remark for the group property (if add)
Alias
: Add/Remove aliases to/from the names listed. The GV world does not understand aliases, only NS does.
Name: the name whose aliases are to be updated
Argument: list of aliases
Create Indv
: Create the given individual with a remark of the entire argument.
Name: the new individuals name
Argument: the initial remark for this individual
Create Group
: Create the given group with a remark of the entire argument.
Name: the new groups name
Argument: the initial remark for this group
Delete
: Delete the given name.
Name: the name of the object to be deleted
Argument: ignored
New Name
: I'm not really sure what this does...
Name: the name of the object to be "New Named"
Argument: ???