The payroll example program is a simple client/server application that makes minimal use of the DCE services. Its main intent is to show a complete example application with FORTRAN code. See Chapter 16 for a detailed description of this example program.

20.8 RPC Phonebook Program

This section describes how to build and run a phonebook application called phnbk. Company employees use the phnbk client program to look up employee contact information that resides with the phnbk server.

The phnbk application is included with Digital DCE for OpenVMS. Because the phnbk source code is portable, you can build and run the phnbk server on many DCE machines.

The sample phnbk client/server program demonstrates several aspects of cross-environment applications:

• Basic connectivity between a Microsoft RPC client and a DCE server.
• Client use of automatic binding in which the client gets the server binding information from the DCE Cell Directory Service. Alternatively, users manually enter a server's binding information as part of the command to start the client. Use the manual method to bypass the DCE Cell Directory Service, or to select a specific server for use when several are available.
• The use of a portability file (dosport.h) that resolves differences between Microsoft RPC and DCE RPC.
• The use of portable server and client code. The server code builds and executes on DEC OSF/1, Windows NT, and OpenVMS systems. The client code builds and executes on personal computers running the MS-DOS operating system, the Microsoft Windows NT operating system, and on DEC OSF/1 and OpenVMS systems.

To build the phnbk client and server programs on an OpenVMS system that has Digital DCE Version 1.5 installed, copy the files to your directory and build the program, as follows:

$ COPY SYS$COMMON:[SYSHLP.EXAMPLES.DCE.RPC.PHONEBOOK]*.* []

$ @PHNBK.COM

20.8.2 Starting the phnbk Server

After the build is complete, you can run the server and the client. Note that you have the ability to log all events with the RPC Event Logger. See Chapter 17 for information on activating and using the event logger.

On OpenVMS systems, you must define a foreign command with the full directory specification. For example:

$ PHNBKD :== "$MYDISK:[MYDIRECTORY]PHNBKD.EXE"

Start the server with the following command:

$ PHNBKD

The server displays the binding information for each of the protocol sequences it is using. Three elements make up a server's binding information: a protocol sequence, a network address, and a transport end point. For example, a server might report the following binding information.

[1] 23789 ncacn_ip_udp:16.20.16.134.[1229] ncacn_ip_tcp:16.20.15.134.[1474]

20.8.3 Starting the phnbk Client

Once the server is running, you can run the client on the same host or on any other host in the network. To run the client, you can either provide the server binding information reported by the server as a command line argument or run it without arguments. Running it without arguments lets the client application resolve server binding information through the name service.

To run the client on OpenVMS, you must first define a foreign command with the full directory specification. For example:

$ PHNBK :== "$MYDISK:[MYDIRECTORY]PHNBK.EXE"

When specifying an end point, start the client with the following command:

$ PHNBK ncacn_dnet_nsp:2.642[RPC2080001]

The phnbk client is a simple interactive application that prompts you for the following commands:

Resolving binding through name server Server returned from name server is: ncacn_ip_tcp:16.20.16.134[] Valid commands are: (b)rowse - List next entry (r)eset - Reset to beginning of file (f)ind <STRING> - Find a substring (f)ind - Find next occurrence of <STRING> (q)uit - Exit program

Note that the string argument is case-sensitive.

To stop the client, use the (q)uit command from the client menu.

20.9 Other Example Programs

The following additional example programs are shipped with Digital DCE for OpenVMS:

• Arithmetic Example Program
  These files are located in the following directory:

  SYS$COMMON:[SYSHLP.EXAMPLES.DCE.GDE_DCE_APPS.ARITHMETIC]

• Inventory Example Program
  These files are located in the following directories:

  SYS$COMMON:[SYSHLP.EXAMPLES.DCE.GDE_DCE_APPS.INVENTORY] SYS$COMMON:[SYSHLP.EXAMPLES.DCE.GDE_DCE_APPS.INVENTORY.IMPLICIT] SYS$COMMON:[SYSHLP.EXAMPLES.DCE.GDE_DCE_APPS.INVENTORY.EXPLICIT]

• Remote File Example Program
  These files are located in the following directory:

  SYS$COMMON:[SYSHLP.EXAMPLES.DCE.GDE_DCE_APPS.REMOTE_FILE]

• Transfer Data Example Program
  These files are located in the following directory:

  SYS$COMMON:[SYSHLP.EXAMPLES.DCE.GDE_DCE_APPS.TRANSFER_DATA]

These example programs are all documented in detail in the appendixes of the Guide to Writing DCE Applications.

To copy, build, and run the examples on either OpenVMS or OpenVMS POSIX, see the README files for each example program.

This appendix provides information on using the Namespace Editor (NSedit). Note that at this time NSedit is only a prototype of a system management tool. Note also that this release of NSedit does not yet have complete functionality.

NSedit is a graphical user interface to the namespace. A namespace is a collection of names that one or more CDS servers know about, look up, modify, and share. Usually only one namespace is associated with a particular cell.

A.1 Starting NSedit

To start NSedit, you must first log in to DCE as cell_admin. Then, enter the following command:

$ MCR DCE$NSEDIT

A.2 NSedit Functionality

NSedit is a Graphical User Interface for CDS. Although it does not provide the complete functionality of the CDS clerk interface, it does provide a user-friendly environment for creating, viewing, and modifying entries in a namespace.

NSedit provides an additional level of namespace data caching. The NSedit cache is used to store data read from the clerk's local cache or from the CDS server. This allows for faster retrieval of data at the expense of accuracy. (Changes may have occurred in the namespace that are not reflected in the NSedit cache.) The tradeoff between speed and accuracy can be controlled by setting the appropriate mode in the Display menu of the tree browser.

NSedit consists of three windows:

• Tree Browser Window
  The entire left window of the NSedit screen is a tree browser that allows users to view the hierarchical structure of the namespace and to create and delete entries.
• Entry Attributes Window
  The top right window is a list management utility that allows users to view, modify, and delete attributes and values of namespace entries.
  Note that most of the features in this window are Read Only for this release.
• ACL Window
  The bottom right window is a second tree browser that allows users to view, modify, and delete ACLs of namespace entries.

The tree browser lets you view the namespace and create and delete namespace entries. Each CDS entry is represented in the tree browser by a rectangle containing the name of the entry and an icon indicating the entry type. A CDS entry can be one of the following:

• Directory: A directory contains objects, soft links, or other directories (child pointers) as its children. The icon is a filled square.
• Object: An object represents a physical resource in the network. Its icon is an empty square.
• Group: A group is a set of names in the network. The icon is a set of seven small squares.
• Soft link: A soft link is a pointer to a CDS entry. The icon is a right arrow.

The tree browser provides the user with the ability to expand a node and view all its children (objects, subdirectories, or soft links) by clicking Mouse Button 3 (MB3) on a tree node or by specifying the appropriate maximum tree level to display, as described in Section A.3.1.

A.2.2 Entry Attributes Window

The Entry Attributes Window is the part of NSedit that lets you create, view, modify, and delete attributes and values from an existing object, directory or \ soft link. When you select a CDS entry with the tree browser, the attributes and values of this entry are shown on the Entry Attributes Window. You can then add, modify, or delete attributes from this entry, as described in this appendix.

A.2.3 ACL Window

This window lets you perform the following functions.

• List the ACL entries.
• Add an ACL entry.
• Modify an ACL entry.
• Delete an ACL entry.
• Substitute all ACL entries with a new ACL entry. This function is not yet implemented.
• Load an ACL from a file. This function is not yet implemented.
• Save an ACL to a file. This function is not yet implemented.
• Copy an ACL entry to another. This function is not yet implemented.
• Copy an ACL to another (for example, an Object ACL can be copied onto an Initial Container Creation ACL for the selected object). This function is not yet implemented.
• Delete all ACL entries except the user_obj entry (kill the ACL). This function is not yet implemented.
• List the available permission tokens.

The following sections describe what you can do with NSedit.

A.3.1 Expanding and Collapsing Tree Nodes

To expand a tree node and view its children, click MB3 on the node. This works only for directory and soft link nodes. For example, by successively expanding nodes, you can see all of the hosts's children as well as their children.

To collapse a tree node whose children are at a higher level than the maximum tree level specified by the user (with the Set Level selection of the Display menu), click MB3 on the node. The node will not collapse if the level of its children is lower than the maximum tree level. The default maximum tree level is 1, which means that only the children of the root node are displayed.

A.3.2 Creating an Object or a Directory

To create an object or directory:

• Type in the name of the new object or directory in the top left selection area and press RETURN. The create_entry_dialogue_popup appears.
• Select Object, Directory, Group, or Soft Link and press OK.

If the object or directory has been successfully created, a new rectangle with the name of the new object or directory appears as a child of the specified parent directory. If CDS cannot create the object or directory, an error message appears.

A.3.3 Creating and Viewing a Soft Link

Note that the following functionality is not yet supported.

• Click the left mouse button on a rectangle, to define the target of the soft link to be created. This target entry appears highlighted.
• Type in the name of the new soft link in the prompt window and press RETURN.

If the soft link has been successfully created, a new rectangle with the name of the new soft link is displayed as a child of the specified parent directory. To verify the creation of the soft link, you can click the right mouse button on the soft link rectangle. If CDS could not create the soft link, an error message appears.

A.3.4 Deleting an Entry

To delete an entry:

• Click the left mouse button on a rectangle, to define the target to be deleted. This target entry is displayed highlighted.
• Select Delete from the Edit menu.

If the entry has been successfully deleted, the rectangle will also disappear from the tree structure. If CDS could not delete the entry, an error message is displayed.

A.3.5 Viewing Attributes and Values

To view the attributes and values of a CDS entry, click the left mouse button on this entry in the Tree Browser window. The attributes and values of this entry is displayed in the Entry Attributes Window. An alternative way to view an entry is to type its full name in the top left selection area. Then the attributes and values of this entry is displayed in the Entry Attributes Window (or an empty list will appear if the entry does not exist).

A.3.6 Creating a Group and Adding Members

To create a group, follow the steps described in Section A.3.2. Select Create Group from the create_entry_dialog_popup.

A.4 NSedit Menus and Dialog Box

There are three pull-down menus in NSedit and one popup dialog box:

• File Menu
• Display Menu
• Edit Menu
• Create Entry Dialog Popup Box

The File menu has the following choice:

• Exit: This selection exits NSedit.

The Display menu has the following choices:

• Set Root: This selection allows the user to specify the root of the tree structure to display. After a root is specified, only entries that are children of the root will be displayed by the tree browser.
• Set Depth: This selection allows the user to specify a maximum tree depth to display. Nodes deeper than the specified depth are not displayed, unless explicitly selected for expansion (by clicking the right mouse button).
• Show Entry: This selection toggles between enabling and disabling the Entry Attributes Window. When the Entry Attributes Window is disabled, no text can be typed in its text input areas and these areas as well as the area where attributes and values appear grayed.
• Show ACLs: This selection toggles between enabling and disabling the ACL window. When the ACL window is disabled, no text can be typed into its text input area. These areas, as well as the area where ACLs appear, are grayed. The ACLs menu selections also are greyed to indicate that no operations are possible at that time.
• Caching: This menu sets the level of caching for NSedit operations:
• Internal: This selection tells the program to read the children of a directory from the program's own cache and not from the namespace. Every time a directory's children are read from the namespace, they are placed in a local cache (data structure) by NSedit. In Internal mode, every time a node is collapsed and reexpanded, its children are read from this cache. You want to use this mode most of the time, unless you suspect that new entries have been created in the namespace. In that case you have to collapse the directory entry, select either Local mode or Server mode and click the right mouse button on the directory to reexpand the directory and see the new information.
• Local: This selection tells the program to read the children of a directory from the CDS local cache (as opposed to reading them from the program's own cache or querying the CDS server) when you click the right mouse button on a directory entry. This selection is useful when new information is stored in the CDS local cache but NSedit is not aware of it (because it has already stored some old information in its own cache).
• Server: This selection tells the program to query the CDS server when reading children of a directory (as opposed to reading them from the program's own cache or from the CDS local cache) when you click the right mouse button on a directory entry. This selection is useful when new information has been stored in the namespace (and the server is aware of it), but is not yet propagated to the CDS local cache (as, for example, when another user creates a new object on a different machine).

The Edit menu has the following choices:

• Delete Entry: Deletes a selected entry. Select an entry in the Tree Browser Window, pull down the Edit menu, and choose Delete Entry to delete the selected entry.
• Delete Attribute: This selection sets the delete mode for attribute names.
• Delete Value: This selection sets the delete mode for attribute values.
• Delete: Deletes an ACL entry or a complete ACL.
• Substitute ACL: (Not supported in this release.) Substitutes all ACL entries with a new ACL entry.
• Kill ACL: (Not supported in this release.) Removes all ACL entries other than type user_obj from a given ACL.
• Show Tokens: (Not supported in this release.) Shows the tokens allowed by the ACL manager for permission strings.

The Create Entry Dialog Popup box has the following choices:

• Create Object: This selection sets the create object mode. Select OK in the dialog box to create a new object as a child of the directory node.
• Create Directory: This selection sets the create directory mode. Select OK in the dialog box to create the new (sub)directory as a child of the directory node.
• Create Soft Link: (Not supported in this release.) This selection sets the create soft link mode. To create a soft link, you click the left mouse button on the target node and type in the full name of the soft link in the prompt window.
• Create Group: This selection sets the create group mode. Select OK in the dialog box to create a new group as a child of the directory node.