NAME

rpccp - Starts the DCE remote procedure call (RPC) control program

SYNOPSIS

rpccp [rpccp-command]

ARGUMENTS

rpccp-command
Specifies one of the following control program commands:

add element
Adds an element to a profile in a name service entry; if the specified entry does not exist, creates the entry.

add entry
Adds an entry to the name service database.

add mapping
Adds or replaces server address information in the local endpoint map.

add member
Adds a member to a group in a name service entry; if the specified entry does not exist, creates the entry.

exit
Leaves the RPC control program.

export
Exports binding information for an interface identifier, object Universal Unique Identifiers (UUIDs), or both to a server entry; if the specified entry does not exist, creates the entry.

help 
Displays a list of commands or the possible options of a specified command.

import
Imports binding information and an object UUID from a server entry.

quit
Leaves the RPC control program.

remove element
Removes selected elements from a profile.

remove entry
Removes an entry from the name service database.

remove group
Removes all group members and the group from the specified entry.

remove mapping
Removes specified elements from the local endpoint map or from the endpoint map of a specified remote host.

remove member
Removes a selected member from a group.

remove profile
Removes all profile elements and the profile from the specified entry.

show entry
Shows the Name Service Interface (NSI) attributes of an entry.

show group
Shows the members of a group.

show mapping
Shows the elements of the local endpoint map.

show profile
Shows the elements of a profile.

show server
Shows the binding information, interface identifier, and object UUIDs in a server entry.

unexport
Removes binding information, interface identifiers, and object UUIDs from a server entry.

DESCRIPTION

Note:   With the exception of the help subcommand, this facility is superceded by the DCE control program (dcecp) in OSF DCE Version 1.1. This command may be fully replaced by the dcecp command in a future release of DCE, and may no longer be supported at that time. 

The RPC control program, rpccp, provides a set of commands for managing name service use for RPC applications and for managing the endpoint map. 

You can use control program commands from within the control program or from the system prompt.  To use the control program commands from inside the control program, Start and enter the control program by using the rpccp command alone, without any argument.  The control program then displays the control program prompt, rpccp>, as follows:

rpccp
rpccp>

You can then enter any control program command, as in the following example:

rpccp> show entry /.:/LandS/anthro/pr_server_node3

Leave the control program and return to the system prompt by using the exit or quit command.  If you enter invalid input, the control program displays the valid commands. 

To use the control program commands from the system prompt, enter the rpccp command with an internal command of the control program as the first argument.  You can do this either interactively or in a command procedure.  For example, you can enter the show entry command as follows:

rpccp show entry /.:/LandS/anthro/pr_server_node3

Arguments and Options

Except for the exit and quit commands, rpccp commands have one or more options.  Each option is identified by a - (dash) followed by a letter; for example, ­-s.  Some options require arguments. 

Commands that access NSI operations also require the name of a name service entry as an argument.  The order of arguments and the entry-name option is arbitrary; for example, the following placements of arguments and options are equivalent:

rpccp> add element  /.:/LandS/anthro/mis_node_2  \
       -i ec1eeb60-5943-11c9-a309-08002b102989,1.0
 rpccp> add element -i ec1eeb60-5943-11c9-a309-08002b102989,1.0 \
       /.:/LandS/anthro/mis_node_2

Environmental Influences on Command Syntax

There are variations in the action of the control program, depending on whether commands are entered from the system prompt or from within the control program.  For example, entering the annotation field of profile elements from the system prompt allows you to include internal spaces in an annotation. 

Function	At System Prompt	Inside rpccp
Strings within quotation marks	Supported	Not required
Wildcard substitution	Supported	Unsupported

Note:   Some UNIX systems require that you place a \ (backslash) before string binding delimiters such as [ ] (brackets) or that you place the delimiters within ’ ’ or " " (single or double quotation marks) at the system prompt. 

The following table describes the scope of the RPC control program commands. 

Scope	Command
All entries	add entry
	remove entry
	show entry
Server entry	export
	import
	show server
	unexport
Group	add member
	remove group
	remove member
	show group
Profile	add element
	remove element
	remove profile
	show profile
Endpoint map	add mapping
	remove mapping
	show mapping

Environment Variables

The control program supports environment variables.  Using environment variables facilitates interactive use of the control program. 

To distinguish environment variables, rpccp∗(8rpc) reference pages follow the convention of using all uppercase letters for examples of environment variables.  Note that UNIX environment variables are case sensitive. 

User-defined environment variables
You can set an environment variable to represent values to rpccp.  Using an environment variable is helpful for specifying a long string such as the following:

       •A string representation of binding information (binding string)

       •A string representation of an object or interface UUID (string UUID)

       •An interface identifier (the interface UUID and version numbers)

       •The name of a name service entry

In the following example, the environment variable JANE_CAL represents an object UUID, while /.:/LandS/anthro/Cal_host_2, the target name service entry, is in the local cell:

JANE_CAL=47f40d10-e2e0-11c9-bb29-08002b0f4528
export JANE_CAL
rpccp
rpccp> export -o JANE_CAL /.:/LandS/anthro/Cal_host_2

DCE RPC environment variables

NLSPATHThe environment variable NLSPATH must point to the location of dcerpc.cat and dcedcs.cat.  Otherwise, any run-time status codes returned by the control program will be hexadecimal, rather than textual.  form.  The value of this variable must include both the pathname of the directory where the .cat files reside and the string %N. 

RPC_DEFAULT_ENTRY_SYNTAX
The dce name syntax is the only syntax currently supported by the DCE Cell Directory Service (CDS).  However, NSI is independent of any specific name service and, in the future, may support name services that use other name syntaxes.  When alternative name syntaxes are supported, you can override the standard default with a process-specific default by setting the RPC_DEFAULT_ENTRY_SYNTAX environment variable.  When this variable is set for a process, the control program uses it to find out the default syntax for the process.  You can override this default in any NSI command of the control program by using the ­-s option to specify an alternative entry syntax.  Setting RPC_DEFAULT_ENTRY_SYNTAX requires specifying the integer 3 to indicate the dce syntax.  To set RPC_DEFAULT_ENTRY_SYNTAX, use the name=value command to define an environment variable.  The following command specifies dce as the default name syntax in a login command file:

# .login command file
# setting dce as default name syntax,
RPC_DEFAULT_ENTRY_SYNTAX=3

RPC_DEFAULT_ENTRY
For the import command, you can use this environment variable to indicate the entry where the search operation starts.  Usually, the starting entry is a profile. 

The Name Service Interface

The remainder of this description contains information to help you use commands that call NSI to access name service entries. 

DCE NSI is independent of any particular name service.  CDS, however, is the only name service available for DCE Version 1.0 RPC applications.  For more details on NSI, see the OSF DCE Application Development Guide—Core Components.  For a description of CDS, see the OSF DCE Administration Guide—Core Components. 

Name Service Entries

To store information about RPC servers, interfaces, and objects, NSI defines the following name service entries:

server entry
Stores binding information, interface identifiers, and object UUIDs for an RPC server

groupCorresponds to one or more RPC servers that offer a common RPC interface, type of RPC object, or both

profileDefines search paths for looking in a name service database for a server that offers a particular RPC interface and object

Note that when NSI is used with CDS, the name service entries are CDS object entries

Structure of Entry Names

Each entry in a name service database is identified by a unique global name made up of a cell name and a cell-relative name. 

A  cell is a group of users, systems, and resources that share common DCE services.  A cell configuration includes at least one cell directory server, one security server, and one time server.  A cell’s size can range from one system to thousands of systems.  For information on cells, see the CDS portion of this book. 

The following is an example of a global name:

/.../C=US/O=uw/OU=MadCity/LandS/anthro/Stats_host_2

The parts of a global name are as follows:

       •cell name The cell name must use X.500 name syntax. The symbol /... begins a cell name.  The letters before each = (equal sign) are abbreviations for country (C), organization (O), and organization unit (OU).  For example:

/.../C=US/O=uw/OU=MadCity

For entries in the local cell, the cell name can be represented by a /.: prefix, in place of the actual cell name, as in the following example:

/.:/LandS/anthro/Stats_host_2

For NSI operations on entries in the local cell you can omit the cell name. 

       •cell-relative name Each name service entry requires a cell-relative name, which contains a directory pathname and a leaf name.

       —
directory pathname Follows the cell name and indicates the hierarchical relationship of the entry to the cell root.

The directory pathname is the middle portion of the global name.  The cell name precedes the directory pathname, and the leaf name follows it, as follows:

cell-name + directory-pathname + leaf-name

The directory pathname contains the names of any subdirectories in the path; each subdirectory name begins with a / (slash), as follows:

/sub-dir-a-name/sub-dir-b-name/sub-dir-c-name

Directory paths are created by name service administrators.  If an appropriate directory path does not exist, ask your name service administrator to extend an existing path or create a new path.  In a directory path, the name of a subdirectory should reflect its relationship to its parent directory (the directory that contains the subdirectory). 

       —
leaf name Identifies the specific entry. The leaf name is the right-hand part of global name beginning with the rightmost slash.

In the following example, /.../C=US/O=uw/OU=MadCity is the cell name, /LandS/anthro is the directory pathname, and /Cal_host_4 is the leaf name:

/.../C=US/O=uw/OU=MadCity/LandS/anthro/Cal_host_4

If a name service entry is located at the cell root, the leaf name directly follows the cell name; for example, /.:/cell-profile. 

Note that when NSI is used with CDS, the cell-relative name is a CDS name. 

Guidelines for Constructing Names of Name Service Entries

A global name includes both a cell name and a cell-relative name composed of a directory pathname and a leaf name.  The cell name is assigned to a cell root at its creation.  When you specify only a cell-relative name to an NSI command, the NSI automatically expands the name into a global name by inserting the local cell name.  When returning the name of a name service entry, a group member, or member in a profile element, NSI operations return global names. 

The directory pathname and leaf name uniquely identify a name service entry.  The leaf name should somehow describe the entry—by identifying its owner or its contents, for example.  The remainder of this section contains guidelines for choosing leaf names.  Note that directory pathnames and leaf names are case sensitive. 

Naming a Server Entry

For a server entry that advertises an RPC interface or service offered by a server, the leaf name must distinguish the entry from the equivalent entries of other servers.  When a single server instance runs on a host, you can ensure a unique name by combining the name of the service, interface (from the interface definition), or the system name for the server’s host system. 

For example, consider two servers, one offering a calendar service on host JULES and one on host VERNE. 

The server on JULES uses the following leaf name:

calendar_JULES

The server on VERNE uses the following leaf name:

calendar_VERNE

For servers that perform tasks on or for a specific system, an alternative approach is to create server entries in a system-specific host directory within the name service database.  Each host directory takes the name of the host to which it corresponds. 

Because the directory name identifies the system, the leaf name of the server entry name need not include the host name, as in the following example:

/.:/LandS/host_1/Process_control

To construct names for the server entries used by distinctive server instances on a single host, you can construct unique server entry names by combining the following information: the name of the server’s service, interface, or object; the system name of the server’s host system, and a reusable instance identifier, such as an integer. 

For example, the following leaf names distinguish two instances of a calendar service on the JULES system:

calendar_JULES_01
 calendar_JULES_02

Avoid automatically generating entry names for the server entries of server instances—for example, by using unique data such as a time stamp (calendar_verne_15OCT91_21:25:32) or process identifier (calendar_­jules_­208004D6).  When a server incorporates such unique data into its server entry names, each server instance creates a separate server entry, causing many server entries.  When a server instance stops running, it leaves an obsolete server entry that is not reused.  The creation of a new entry whenever a server instance starts may impair performance. 

A server can use multiple server entries to advertise different combinations of interfaces and objects.  For example, a server can create a separate server entry for a specific object (and the associated interfaces).  The name of such a server entry should correspond to a well-known name for the object.  For example, consider a server that offers a horticulture bulletin board known to users as horticulture_bb.  The server exports the horticulture_bb object, binding information, and the associated bulletin-board interface to a server entry whose leaf name identifies the object, as follows:

horticulture_bb

Note that an RPC server that uses RPC authentication can choose identical names for its principal name and its server entry.  Use of identical names permits a client that calls the rpc_binding_set_auth_info routine to automatically determine a server’s principal name (the client will assume the principal name to be the same as the server’s entry name).  If a server uses different principal and server entry names, users must explicitly supply the principal name.  For an explanation of principal names, see the OSF DCE Application Development Guide. 

Naming a Group

The leaf name of a group should indicate the interface, service, or object that determines membership in the group.  For example, for a group whose members are selected because they advertise an interface named Statistics, the following is an effective leaf name:

Statistics

For a group whose members advertise laser-printer print queues as objects, the following is an effective leaf name:

laser-printer

Naming a Profile

The leaf name of a profile should indicate the profile users; for example, for a profile that serves the members of an accounting department, the following is an effective leaf name:

accounting_profile

Privileges Required

To use NSI commands to access entries in a CDS database, you need access control list (ACL) permissions.  Depending on NSI operation, you need ACL permissions to the parent directory or the CDS object entry (the name service entry) or both.  The ACL permissions are as follows:

       •To create an entry, you need i (insert) permission to the parent directory. 

       •To read an entry, you need r (read) permission to the CDS object entry. 

       •To write to an entry, you need w (write) permission to the CDS object entry. 

       •To delete an entry, you need d (delete) permission either to the CDS object entry or to the parent directory. 

Note that write permission does not imply read permission. 

ACL permissions for NSI commands of the control program are described in the reference pages. 

NOTES

A server entry equates to an NSI binding attribute and, optionally, an object attribute; a group equates to an NSI group attribute; and a profile equates to an NSI profile attribute.  Typically, each server’s entries, groups, and profiles reside in distinct name service entries. 

EXAMPLES

     1.The following command starts the RPC control program:

rpccp

     2.The following command, entered at the system prompt rather than in rpccp, removes the entry /.:/LandS/anthro/Cal_host_2:

rpccp remove entry /.:/LandS/anthro/Cal_host_2

RELATED INFORMATION

Commands: rpccp_add_element(8rpc), rpccp_add_entry(8rpc), rpccp_add_mapping(8rpc), rpccp_add_member(8rpc), rpccp_export(8rpc), rpccp_import(8rpc), rpccp_remove_element(8rpc), rpccp_remove_entry(8rpc), rpccp_remove_group(8rpc), rpccp_remove_mapping(8rpc), rpccp_remove_member(8rpc), rpccp_remove_profile(8rpc), rpccp_show_entry(8rpc), rpccp_show_group(8rpc), rpccp_show_mapping(8rpc), rpccp_show_profile(8rpc), rpccp_show_server(8rpc), rpccp_unexport(8rpc), dcecp(8dce).