DCE_RPC, rpccp
*Conan The Librarian (sorry for the slow response - running on an old VAX)
|
VMS Help DCE_RPC, rpccp *Conan The Librarian (sorry for the slow response - running on an old VAX) |
|
NAME
rpccp - Starts the RPC control program
SYNOPSIS
rpccp [rpccp-command]
NOTES
This facility is superceded by the DCE control program (dcecp) for
OSF DCE version 1.1.
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.
NOTES
With the exception of the rpccp_help subcommand, this command is
replaced at Revision 1.1 by the dcecp command. 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.
DESCRIPTION
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 (represented here as a $).
To use the control program commands from inside the control program,
Start and enter the control program 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, for example:
rpccp> show entry /.:/LandS/anthro/pr_server_node3
You leave the control program and return to the system prompt 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
RELATED INFORMATION
Commands: dcecp
add element
add entry
add mapping
add member
export
import
remove element
remove entry
remove group
remove mapping
remove member
remove profile
show entry
show group
show mapping
show profile
show server
unexport
| 1 - ARGUMENTS |
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
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 identif-
ier, object 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 speci-
fied 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 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.
1.1 - add_element
NAME
add element - Adds an element to a profile in a name service entry;
if the specified entry does not exist, creates the
entry.
SYNOPSIS
rpccp add element profile-entry-name -m member {-d | -i if-id
[-p priority]} [-a annotation] [-s syntax ]
OPTIONS
-m Defines a member name for the profile element to be added
(required).
-d Performs the add element operation on the default profile
element. With the -d option, the -i and -p options are
ignored.
-i Defines an interface identifier for the profile element to
be added. Only one interface can be added in a single
operation. An interface identifier is required, unless the
default profile element is being added. With the -d option,
the -i option is ignored. The value has the following form:
interface-uuid,major-version.minor-version
The UUID is a hexadecimal string and the version numbers
are a decimal string, for example:
-i ec1eeb60-5943-11c9-a309-08002b102989,3.11
Leading zeros in version numbers are ignored.
-p Defines a search priority for the new profile element. The
priority value is in the range 0 to 7, with zero having the
highest priority. When a default element is added (with the
-d option), the -p option is ignored. By default, a
nondefault element is assigned a priority value of zero.
-a Defines an annotation string for the profile element.
Note that the shell supports quotation marks around the
annotation field of profile elements, which allows you to
include internal spaces in an annotation; the control
program does not. To specify or refer to annotations from
within the control program, limit each annotation to an
unbroken alphanumeric string; for example, CalendarGroup.
To refer to annotations from the system prompt, do not
incorporate quotation marks into any annotation.
-s Indicates the name syntax of the entry name (optional).
The only value for this option is the dce name syntax,
which is the default name syntax. Until an alternative
name syntax becomes available, specifying the -s option
is unnecessary.
ARGUMENTS
profile-entry-name
Specifies the entry name of the target profile. For an entry
in the local cell, you can omit the cell name and specify only
the cell-relative name.
DESCRIPTION
The add element command adds an element to a profile in a name
service entry. The name of the entry containing the profile and
the entry name of the profile member in the new element are required.
The entry of a profile may have been created previously (by either
the add entry or add element command). But, if the specified entry
does not exist, the add element command tries to create the entry.
A profile element is a database record containing the following fields:
Interface identifier
This is the primary search key. The interface identifier
consists of the interface UUID and the interface version
numbers.
Member name
The entry name of one of the following kinds of name service
entries:
+ A server entry for a server offering the requested RPC
interface and object
+ A group corresponding to the requested RPC interface
+ A profile
Priority value
The priority value (0 (zero) is the highest priority; 7 is the
lowest) is designated by the creator of a profile element to
help determine the order for using the element. NSI search
operations select among like priority elements at random. For
the rpccp add element command, the default is 0.
Annotation string
The annotation string enables you to identify the purpose of
the profile element. The annotation can be any textual
information, for example, an interface name associated with the
interface identifier or a description of a service or resource
associated with a group. The annotation string is not a search
key for the import or lookup operations.
Privilege Required
You need both read permission and write permission to the CDS object
entry (the target profile entry). If the entry does not exist, you
also need insert permission to the parent directory.
NOTE
This command is replaced at Revision 1.1 by the dcecp command and
may not be provided in future releases of DCE.
EXAMPLES
The following command adds an element to the cell profile,
/cell-profile, in the local cell:
$ rpccp
rpccp> add element \
> -i ec1eeb60-5943-11c9-a309-08002b102989,1.1 \
> -m /.:/Calendar_profile \
> -a RefersToCalendarGroups \
> /.:/cell-profile
The following control program commands start the control program,
set up a user profile associated with the cell profile as its default
element, and add a user-specific element for the Calendar V1.1
interface, as follows:
$ rpccp
rpccp> add element /.:/LandS/anthro/molly_o_profile \
> -d -m /.:/cell-profile
rpccp>
rpccp> add element /.:/LandS/anthro/molly_o_profile \
> -m /.:/LandS/anthro/Calendar_group \
> -i ec1eeb60-5943-11c9-a309-08002b102989,1.1 \
> -a Calendar_Version 1.1_Interface
rpccp>
The added profile element contains the global name of the member
(specified using its cell-relative name,
/.:/LandS/anthro/Calendar_group) and the RPC interface identifier
for the Calendar Version 1.1 interface.
RELATED INFORMATION
Commands: remove element
remove profile
show profile
1.2 - add_entry
NAME
add entry - Adds a name service entry to the name service database
SYNOPSIS
rpccp add entry entry-name [-s syntax]
OPTIONS
-s Indicates the name syntax of the entry name (optional).
The only value for this option is the dce name syntax,
which is the default name syntax. Until an alternative
name syntax becomes available, specifying the -s option
is unnecessary.
ARGUMENTS
entry-name
Specifies the name of the target name service entry. For
an entry in the local cell, you can omit the cell name and
specify only the cell-relative name.
DESCRIPTION
The add entry command adds an unspecialized entry to the name service
database. The name of the entry is required.
The new entry initially contains no NSI attributes. This command
creates a general name service entry for an application or user.
The application or user can later use the export, add element, and
add member commands to make the generic entry into a server entry,
a group, or a profile (or a combination), as follows:
+ For a server entry, specify the new entry as the target entry
for the rpccp export command.
+ For a group, specify the new entry as the target group for the
rpccp add member command.
+ For a profile, specify the new entry as the target profile for
the rpccp add element command.
The add entry command enables administrators to add entries for users
who lack the required permissions. If you have the permissions
required by the add entry command, you can also add an entry using an
export, add member, or add element command; if the entry you specify
does not exist, the command creates the entry.
Privilege Required
To add an entry, you need insert permission to the parent directory
and both read permission and write permission to the CDS object entry
(the target name service entry).
NOTE
This command is replaced at Revision 1.1 by the dcecp command and may
not be provided in future releases of DCE.
EXAMPLES
The following commands start RPCCP and add an unspecialized entry to
the name service database:
$ rpccp
rpccp> add entry \
> /.:/LandS/anthro/Cal_host_2
The following command operates from the system prompt to add an
unspecialized entry to the name service database:
$ rpccp add entry \
> /.:/LandS/anthro/Cal_host_3
RELATED INFORMATION
Commands: remove entry
show entry
1.3 - add_mapping
NAME
add mapping - Adds or replaces server address information in the
local endpoint map
SYNOPSIS
rpccp add mapping -b string-binding -i interface-identifier
[-a annotation-string] [-o object-uuid] [-N]
OPTIONS
-b Specifies a string representation of a binding over which
the server can receive remote procedure calls. At least one
binding is required.
The value has the form of an RPC string binding, without an
object UUID, for example:
-b ncadg_ip_udp:63.0.2.17[5347]
Note that depending on your system, string binding
delimiters such as brackets ([ ]) may need to be preceded
by an escape symbol (\) or placed within quotation marks
(' ' or " "). Requirements vary from system to system,
and you must conform to the usage rules of a system.
-i Specifies an interface identifier to register with the
local endpoint map. An interface identifier is required.
Only one interface can be added (i.e., registered) in a
single operation. The interface identifier has the
following form:
interface-uuid,major-version.minor-version
The UUID is a hexadecimal string and the version numbers
are decimal strings, for example:
-i ec1eeb60-5943-11c9-a309-08002b102989,1.1
Leading zeros in version numbers are ignored.
-a Specifies a character string comment to be applied to each
cross product element that is added to the local endpoint
map. The string can be up to 64 characters long, including
the NULL terminating character.
The string is used by applications for informational
purposes only. The RPC runtime does not use this string
to determine which server instance a client communicates
with, or for enumerating endpoint map elements.
-o Defines an object UUID that further determines the endpoint
map elements that are removed (optional). Each add mapping
command accepts up to 32 -o options. The UUID is a
hexadecimal string, for example:
-o 3c6b8f60-5945-11c9-a236-08002b102989
-N Specifies that existing elements in the local host's
endpoint map should not be replaced when the new
information is added.
DESCRIPTION
The add mapping command adds to, replaces, or adds server address
information to the local endpoint map.
Each element in the local endpoint map logically contains the
following:
+ Interface ID, consisting of an interface UUID and versions
(major and minor)
+ Binding information
+ Object UUID (optional)
+ Annotation (optional)
This command should be used without the -N option when only a single
instance of the server in question runs on the server's host. Do not
use the -N option if no more than one server instance on the host
ever offers the same interface UUID, object UUID, and protocol
sequence.
When local endpoint map elements are not replaced, obsolete elements
accumulate each time a server instance stops running without
explicitly unregistering its endpoint map information. Periodically,
the RPC Daemon (DCED) will identify these obsolete elements and
remove them. However, during the interval between these removals,
the presence of the obsolete elements increases the chance that
clients will receive endpoints to nonexistent servers. The clients
will then waste time trying to communicate with these servers before
giving up and obtaining another endpoint.
Allowing DCED to replace any existing local endpoint map elements
(by not specifying -N) reduces the chance of this happening.
For example, suppose an existing element in the local endpoint map
matches the interface UUID, binding information exclusive of the
endpoint, and object UUID of an element this routine provides. The
routine changes the endpoint map according to the elements' interface
major and minor version numbers.
NOTE
This command is replaced at Revision 1.1 by the dcecp command and may
not be provided in future releases of DCE.
EXAMPLES
The following command operates from the system prompt to add a map
element to the local endpoint map. The command adds the map element
that contains the specified interface identifier, server address
(specified as a string binding), and object UUIDs.
$ rpccp add mapping -i ec1eeb60-5943-11c9-a309-08002b102989,1.1 \
-b ncadg_ip_udp:63.0.2.17[5347] \
-o 005077d8-8022-1acb-9375-10005a4f533a \
-o 001bc29a-8041-1acb-b377-10005a4f533a \
-a 'Calendar version 1.1'
$
The previous command adds the following elements:
interface ID
ec1eeb60-5943-1169-a309-08002b102989,1.1
string binding
ncadg_ip_udp:63.0.2.17[5347]
objects 005077d8-8022-1acb-9375-10005a4f533a
001bc29a-8041-1acb-b377-10005a4f533a
annotation
Calendar version 1.1
RELATED INFORMATION
Commands: export
remove mapping
show mapping
show server
Subroutines: rpc_ep_register
rpc_ep_register_no_replace
1.4 - add_member
NAME
add member - Adds a member to a group in a name service entry;
if the specified entry does not exist, creates the
entry
SYNOPSIS
rpccp add member group-entry-name -m member [-s syntax]
OPTIONS
-m Declares the name of a member to be added to the
specified group entry (required).
You can add only one member at a time.
-s Indicates the name syntax of the entry name (optional).
The only value for this option is the dce name syntax,
which is the default name syntax. Until an alternative
name syntax becomes available, specifying the -s option
is unnecessary.
ARGUMENTS
group-entry-name
Specifies the name of the target group. For an entry in
the local cell, you can omit the cell name and specify
only the cell-relative name.
DESCRIPTION
The add member command adds a member to a group in a name service
entry. The name of the entry containing the group and the name of
the new group member are required. The entry of a group may have
been created previously (by either the add entry or add member
command). If the specified entry does not exist, the add member
command tries to create the entry.
Privilege Required
You need both read permission and write permission to the CDS object
entry (the target group entry). If the entry does not exist, you
also need insert permission to the parent directory.
NOTE
This command is replaced at Revision 1.1 by the dcecp command and
may not be provided in future releases of DCE.
EXAMPLES
The following commands run RPCCP and add the member
/.:/LandS/anthro/Cal_host_3 to the group
/.:/LandS/anthro/Calendar_group:
$ rpccp
rpccp> add member \
> -m /.:/LandS/anthro/Cal_host_3 \
> /.:/LandS/anthro/Calendar_group
RELATED INFORMATION
Commands: remove group
remove member
show group
1.5 - export
NAME
export - Exports binding information for an interface identifier
or object UUIDs or both to a server entry; if the
specified entry does not exist, creates the entry
SYNOPSIS
rpccp export entry-name {-i if-id -b string-binding
[-b string-binding...] -o object-uuid
[-o object-uuid...] | -i if-id
-b string-binding [-b...] | -o object-uuid
[-o object-uuid...] } [-s syntax ]
OPTIONS
-i Declares the interface identifier of an RPC interface.
The export command operates on only one -i option; if you
enter more than one, the command ignores all but the last
interface identifier. If you specify an interface
identifier, you must specify at least one -b option. The
-i and -o options can occur together or separately, but
one of them is necessary. The interface identifier takes
the following form:
interface-uuid,major-version.minor-version
The version numbers are optional, but if you omit a version
number, the value defaults to 0. The UUID is a hexadecimal
string and the version numbers are decimal strings, for
example:
-i ec1eeb60-5943-11c9-a309-08002b102989,3.11
Leading zeros in version numbers are ignored.
-b Declares a string binding (optional). To use this option,
you must also specify an interface identifier (using the
-i option). Each command accepts up to 32 -b options.
The value has the form of an RPC string binding, without
an object UUID. The binding information contains an RPC
protocol sequence, a network address, and sometimes an
endpoint within brackets
(rpc-prot-seq:network-addr[endpoint]). For a well-known
endpoint, include the endpoint in the string binding, for
example:
-b ncadg_ip_udp:63.0.2.17[5347]
For a dynamic endpoint, omit the endpoint from the string
binding, for example:
-b ncacn_ip_tcp:16.20.15.25
Note that depending on your system, string binding
delimiters such as brackets ([ ]) may need to be preceded
by an escape symbol (\) or placed within quotation marks
(' ' or " "). Requirements vary from system to system,
and you must conform to the usage rules of a system.
-o Declares the UUID of an object. Each export command
accepts up to 32 -o options. The -i and -o options can
occur together or separately, but one of them is necessary.
The UUID is a hexadecimal string, for example:
-o 3c6b8f60-5945-11c9-a236-08002b102989
-s Indicates the name syntax of the entry name (optional).
The only value for this option is the dce name syntax,
which is the default name syntax. Until an alternative
name syntax becomes available, specifying the -s option
is unnecessary.
ARGUMENTS
entry-name
Specifies the name of the target name service entry.
Usually, the target is a server entry. However, objects
also can be exported (without an interface identifier or
any binding information) to a group or a profile.
For an entry in the local cell, you can omit the cell
name and specify only the cell-relative name.
DESCRIPTION
The export command places binding information and an interface
identifier, object UUIDs, or both into a server entry, or the
command object UUIDs into a group's entry. The export command
searches the name service database for the entry with the specified
entry name. If the entry exists, the command uses it; otherwise,
the command tries to create a new name service entry using the
specified entry name.
Minimally, the command requires the name of the entry and either an
identifier and binding string or an object.
If the specified entry does not exist, the export command tries to
create the entry.
Privilege Required
You need both read permission and write permission to the CDS object
entry (the target name service entry). If the entry does not exist,
you also need insert permission to the parent directory.
NOTE
This command is replaced at Revision 1.1 by the dcecp command and
may not be provided in future releases of DCE.
EXAMPLES
This example shows a control program export command that is stored
in a file for later execution from the system prompt. The command
exports two objects and an interface with two string bindings to the
server entry /.:/LandS/anthro/Cal_host_3 in the local cell:
# file to export Calendar 1.1 at installation time
rpccp export \
-i ec1eeb60-5943-11c9-a309-08002b102989,1.1 \
-b ncacn_ip_tcp:16.20.15.25 \
-b ncadg_ip_udp:63.0.2.17 \
-o 30dbeea0-fb6c-11c9-8eea-08002b0f4528 \
-o 16977538-e257-11c9-8dc0-08002b0f4528 \
/.:/LandS/anthro/Cal_host_3
The following example shows the use of a user-defined logical name
as an interface identifier, to facilitate entering an export command
interactively (in this case, from inside the control program). The
initial DCL command sets up a logical name Calendar_1_1, which
represents the interface identifier of an RPC interface. The rpccp
command then starts the control program, and the export command
exports the Calendar interface and two string bindings to the server
entry /.:/LandS/anthro/Cal_host_2 in the local cell, as follows:
$ define Calendar_1_1 ec1eeb60-5943-11c9-a309-08002b102989,1.1
$ rpccp
rpccp> export -i Calendar_1_1 \
> -b ncacn_ip_tcp:16.20.15.25 \
> -b ncadg_ip_udp:63.0.2.17 \
> /.:/LandS/anthro/Cal_host_2
The following example shows the use of user-defined logical names
for object UUIDs to facilitate entering an export command
interactively (in this case, from inside the control program).
The initial DCL commands set up the logical names LUKE_CAL and
JOSH_CAL, which represent personal calendars that are accessible
as objects to an RPC server. The rpccp command then starts the
control program, and the export command exports the two objects to
the server's entry /.:/LandS/anthro/Cal_host_2 in the local cell:
$ define LUKE_CAL 30dbeea0-fb6c-11c9-8eea-08002b0f4528
$ define JOSH_CAL 16977538-e257-11c9-8dc0-08002b0f4528
$ rpccp
rpccp> export -o LUKE_CAL -o JOSH_CAL \
> /.:/LandS/anthro/Cal_host_2
RELATED INFORMATION
Commands: import
show server
unexport
1.6 - help
NAME
help - Displays a list of commands or the options of a specified
command
SYNOPSIS
rpccp help [rpccp-command]
ARGUMENTS
rpccp-command
Specifies one of the following control commands:
add element
add entry
add member
exit
export
import
quit
remove element
remove entry
remove group
remove mapping
remove member
remove profile
show entry
show group
show mapping
show profile
show server
unexport
DESCRIPTION
The help command displays information about the RPCCP command set or
the options and argument associated with a specific command.
NOTE
This command may be replaced in future releases by the dcecp command,
and may no longer be supported at that time.
EXAMPLES
The following command operates from the system prompt to display the
internal commands of the control program:
$ rpccp help
The following commands start the control program and display the
syntax of the remove entry command:
$ rpccp
rpccp> help remove entry
RELATED INFORMATION
Commands: add element
add entry
add member
export
import
remove element
remove entry
remove group
remove mapping
remove member
remove
profile
rpccp
show entry
show group
show
mapping
show profile
show server
unexport
1.7 - import
NAME
import - Imports binding information and an object UUID from a
server entry
SYNOPSIS
rpccp import starting-entry-name -i if-id [-v versions] [-e]
[-n [integer]] [-o object-uuid] [-s syntax] [-u]
OPTIONS
-i Defines an interface identifier to be imported (required).
You can import only one interface at a time. The value has
the following form:
interface-uuid,major-version.minor-version The UUID is a
hexadecimal string and the version numbers are decimal
strings, for example:
-i ec1eeb60-5943-11c9-a309-08002b102989,1.1
Leading zeros in version numbers are ignored.
-v Indicates how a specified interface version is used
(optional). If it is used without the -i option, the
-v option is ignored. The possible combinations of
versions for the -v option and their actions are as
follows:
Versions Action
________________________________________________
all The interface version is ignored.
exact Both the major and minor versions
must match the specified versions.
compatible The major version must match the
specified version, and the minor
version must be greater than or
equal to the specified version.
major_only The major version must match the
specified version; the minor ver-
sion is ignored.
upto The major version must be less than
or equal to that specified. If the
major versions are equal, the minor
version must be less than or equal
to that specified.
________________________________________________
If the -v option is absent, the command shows compatible
version numbers.
-e Shows the name of the entry where the binding is found
(optional).
-n Declares that the import operation is to continue until no
more potential bindings are found (optional). Providing
a numeric value to this option restricts the number of
imported bindings. If you omit the number, only one
binding is imported. If repeated, this operation may
return the same binding. For example, -n imports all
available bindings, and -n 5 imports up to five bindings.
Note that the imported bindings are displayed as string
bindings.
-o Declares the UUID of an object to be imported (optional).
Only one UUID can occur in a single operation.
If an object is specified, the import operation limits its
search to server entries that contain both the specified
interface identifier and object UUID when searching for a
potential binding. Without the -o option, the import
operation ignores object UUIDs. The UUID is a hexadecimal
string, for example:
-o 3c6b8f60-5945-11c9-a236-08002b102989
-s Indicates the name syntax of the entry name (optional).
The only value for this option is the dce name syntax,
which is the default name syntax. Until an alternative
name syntax becomes available, specifying the -s option
is unnecessary.
-u Updates the local CDS cache copy of name service data
(optional). Name service data is cached locally on each
machine in a cell. If an rpccp inquiry can be satisfied
by data in the local CDS cache, this cached data is
returned. Locally cached copies of name service data
might not include a recent CDS update, however. If the
required data is not available in the local CDS cache,
rpccp goes to a CDS server(s) to retrieve the required
data. rpccp then updates the local CDS cache. Using the
-u option bypasses the local cache, allowing rpccp to go
directly to a CDS server for the inquiry. rpccp then
updates the local CDS cache.
ARGUMENTS
starting-entry-name
Indicates the name of the server entry where the import
operation starts. For an entry in the local cell, you
can omit the cell name and specify only the cell-relative
name.
DESCRIPTION
The import command imports binding information and an RPC object UUID
for a specific RPC interface from a server entry. The name of the
entry and the interface identifier are required. The entry name can
refer to a server entry, a group, or a profile.
Privilege Required
You need read permission to the specified CDS object entry (the
starting name service entry) and to any CDS object entry in the
resulting search path.
NOTE
This command is replaced at Revision 1.1 by the dcecp command and
may not be provided in future releases of DCE.
EXAMPLES
The following commands run RPCCP and import an interface and object:
$ rpccp
rpccp> import -i ec1eeb60-5943-11c9-a309-08002b102989,1.1 \
> -o 30dbeea0-fb6c-11c9-8eea-08002b0f4528 \
> /.:/LandS/anthro/Cal_host_3
RELATED INFORMATION
Commands: export
show server
unexport
1.8 - remove_element
NAME
remove element - Removes selected elements from a profile
SYNOPSIS
rpccp remove element profile-entry-name {-d | -i if-id -m member |
-a annotation} [-s syntax]
OPTIONS
-d Removes the default profile element. With the -d option,
the -a, -i, and -m options are ignored.
-i Defines an interface identifier for the profile element to
be removed for a member specified with the -m option. Only
one interface and member pair can be removed in a single
operation. If you supply multiple instances of the -i
option, the command uses the final instance.
The -i and -m options take precedence over the -a option.
However, if the default profile element is specified (by
the -d option), the -i and -m options are ignored.
The interface identifier value has the following form:
interface-uuid,major-version.minor-version
The UUID is a hexadecimal string and the version numbers
are decimal strings, for example:
-i ec1eeb60-5943-11c9-a309-08002b102989,1.1
Leading zeros in version numbers are ignored.
-m Defines a member name for the profile element to be removed.
This option is required if the interface identifier is
specified. Only one interface and member can be removed in
a single operation. If you supply multiple instances of
the -m option, the command uses the final instance.
-a Removes all elements whose annotation fields match the
specified annotation; in the presence of -d option or -i
and -m options, the -a option is ignored.
Note that the shell supports quotation marks around the
annotation field of profile elements, which allows you to
include internal spaces in an annotation; the control
program does not. To specify or refer to annotations from
within the control program, limit each annotation to an
unbroken alphanumeric string; for example, CalendarGroup.
To refer to annotations from the system prompt, do not
incorporate quotation marks into any annotation.
-s Indicates the name syntax of the entry name (optional).
The only value for this option is the dce name syntax,
which is the default name syntax. Until an alternative
name syntax becomes available, specifying the -s option
is unnecessary.
ARGUMENTS
profile-entry-name
Indicates the name of the target profile. For an entry in
the local cell, you can omit the cell name and specify only
the cell-relative name.
DESCRIPTION
The remove element command removes an element from a profile in the
name service database. For a description of the fields in a profile
element, see add entry.
The remove element command requires the entry name of the profile.
The command also requires one of the following options:
-d The default profile option takes precedence over the other
two options.
-i interface-id -m member-name An interface and member pair
takes precedence over the -a option.
-a annotation-string
The annotation option takes effect only if neither the
-d or -i option is specified.
Privilege Required
You need read permission and write permission to the CDS object
entry (the target profile entry).
NOTE
This command is replaced at Revision 1.1 by the dcecp command and
may not be provided in future releases of DCE.
EXAMPLES
The initial DCL command sets up a logical name Calendar_1_1, which
represents the interface identifier of an RPC interface. The
control program commands set up a logical name for the interface
identifier of the Calendar Version 1.1 RPC interface, run RPCCP, and
remove an element from a profile, as follows:
$ define Calendar_1_1 ec1eeb60-5943-11c9-a309-08002b102989,1.1
$ rpccp
rpccp> remove element -i Calendar_1_1 \
> -m /.:/LandS/anthro/Calendar_group \
> /.:/LandS/anthro/molly_o_profile
RELATED INFORMATION
Commands: add element
remove profile
show profile
1.9 - remove_entry
NAME
remove entry - Removes a name service entry from the name service
database
SYNOPSIS
rpccp remove entry entry-name [-s syntax]
OPTIONS
-s Indicates the name syntax of the entry name (optional).
The only value for this option is the dce name syntax,
which is the default name syntax. Until an alternative
name syntax becomes available, specifying the -s option
is unnecessary.
ARGUMENTS
entry-name
Indicates the name of the target name service entry. For
an entry in the local cell, you can omit the cell name and
specify only the cell-relative name.
DESCRIPTION
The remove entry command removes an entry from the name service
database. The name of the entry is required.
Privilege Required
You need read permission to the CDS object entry (the target name
service entry). You also need delete permission to the CDS object
entry or to the parent directory.
NOTE
This command is replaced at Revision 1.1 by the dcecp command and
may not be provided in future releases of DCE.
EXAMPLES
The following commands run RPCCP and remove the entry
/.:/LandS/anthro/Cal_host_2 from the local cell of the name service
database:
$ rpccp
rpccp> remove entry /.:/LandS/anthro/Cal_host_2
RELATED INFORMATION
Commands: add entry
show entry
1.10 - remove_group
NAME
remove group - Removes all group members and the group from the
specified name service entry
SYNOPSIS
rpccp remove group group-entry-name [-s syntax]
OPTIONS
-s Indicates the name syntax of the entry name (optional).
The only value for this option is the dce name syntax,
which is the default name syntax. Until an alternative
name syntax becomes available, specifying the -s option
is unnecessary.
ARGUMENTS
group-entry-name
Indicates the name of the target group. For an entry in
the local cell, you can omit the cell name and specify
only the cell-relative name.
DESCRIPTION
The remove group command removes a group from the name service
database. The group need not be empty. The entry name of the group
is required.
Privilege Required
You need write permission to the CDS object entry (the target group
entry).
NOTE
This command is replaced at Revision 1.1 by the dcecp command and
may not be provided in future releases of DCE.
EXAMPLES
The following commands run RPCCP and remove the group from the name
service entry /.:/LandS/anthro/Calendar_group:
$ rpccp
rpccp> remove group /.:/LandS/anthro/Calendar_group
RELATED INFORMATION
Commands: add member
remove member
show group
1.11 - remove_mapping
NAME
remove mapping - Removes specified elements from the local endpoint
map
SYNOPSIS
rpccp remove mapping -b string-binding -i interface-identifier
[-o object-uuid]
OPTIONS
-b Specifies a string representation of a binding over which
the server can receive remote procedure calls. At least
one binding is required. The value has the form of an RPC
string binding, without an object UUID, for example:
-b ncadg_ip_udp:63.0.2.17[5347]
Note that depending on your system, string binding
delimiters such as brackets ([ ]) may need to be preceded
by an escape symbol (\) or placed within quotation marks
(' ' or " "). Requirements vary from system to system,
and you must conform to the usage rules of a system.
-i Specifies an interface identifier to remove from the local
endpoint map. An interface identifier is required. Only
one interface can be removed in a single operation. The
interface identifier has the following form:
interface-uuid,major-version.minor-version
The UUID is a hexadecimal string and the version numbers
are decimal strings, for example:
-i ec1eeb60-5943-11c9-a309-08002b102989,1.1
Leading zeros in version numbers are ignored.
-o Defines an object UUID that further determines the endpoint
map elements that are removed (optional). Each remove
mapping command accepts up to 32 -o options. The UUID is a
hexadecimal string, for example:
-o 3c6b8f60-5945-11c9-a236-08002b102989
DESCRIPTION
The remove mapping command removes server address information from
the local endpoint map. Each element in the local endpoint map
logically contains the following:
+ Interface ID, consisting of an interface UUID and versions
(major and minor)
+ Binding information
+ Object UUID (optional)
+ Annotation (optional)
This command requires one interface identifier (the -i option); at
least one string binding (the -b option); and optionally, one or
more object UUIDs (the -o option). Each instance of the command
accepts from 1 to 32 -b options and from 0 to 32 -o options. The
options work together to delimit the elements to be removed from the
target endpoint map. The command removes any map element that
contains the specified interface identifier, a specified string
binding, and a specified object UUID (if any).
NOTE
This command is replaced at Revision 1.1 by the dcecp command and
may not be provided in future releases of DCE.
EXAMPLES
The following command operates from the system prompt to remove a map
element from the local endpoint map. The command removes only the
map element that contains the specified interface identifier, server
address (specified as a string binding), and object UUID.
$ rpccp remove mapping \
> -i ec1eeb60-5943-11c9-a309-08002b102989,1.1 \
> -b ncadg_ip_udp:16.20.16.64[3424] \
> -o 30dbeea0-fb6c-11c9-8eea-08002b0f4528
$
RELATED INFORMATION
Commands: add mapping
show mapping
show server
1.12 - remove_member
NAME
remove member - Removes a specified member from a group
SYNOPSIS
rpccp remove member group-entry-name -m member [-s syntax]
OPTIONS
-m Declares the entry name of the group member to be removed
(required).
-s Indicates the name syntax of the entry name (optional).
The only value for this option is the dce name syntax,
which is the default name syntax. Until an alternative
name syntax becomes available, specifying the -s option
is unnecessary.
ARGUMENTS
group-entry-name
Indicates the name of the target group. For an entry in
the local cell, you can omit the cell name and specify
only the cell-relative name.
DESCRIPTION
The remove member command removes a specified member from a specified
group.
Privilege Required
You need read permission and write permission to the CDS object
entry (the target group entry).
NOTE
This command is replaced at Revision 1.1 by the dcecp command and
may not be provided in future releases of DCE.
EXAMPLES
The following commands run RPCCP and remove the member
/.:/LandS/anthro/Cal_host_2 from the group
/.:/LandS/dept/Calendar_group:
$ rpccp
rpccp> remove member \
> -m /.:/LandS/anthro/Cal_host_2 \
> /.:/LandS/anthro/Calendar_group
The following command removes the member /.:/LandS/anthro/Cal_host_3
from the group /.:/LandS/anthro/Calendar_group:
$ rpccp remove member \
> -m /.:/LandS/anthro/Cal_host_3 \
> /.:/LandS/anthro/Calendar_group
RELATED INFORMATION
Commands: add member
remove group
show group
1.13 - remove_profile
NAME
remove profile - Removes all profile elements and the profile
from the specified name service entry
SYNOPSIS
rpccp remove profile profile-entry-name [-s syntax]
OPTIONS
-s Indicates the name syntax of the entry name (optional).
The only value for this option is the dce name syntax,
which is the default name syntax. Until an alternative
name syntax becomes available, specifying the -s option
is unnecessary.
ARGUMENTS
profile-entry-name
Indicates the name of the target profile. For an entry
in the local cell, you can omit the cell name and specify
only the cell-relative name.
DESCRIPTION
The remove profile command removes a profile (and all of its
elements) from the name service database. The entry name of the
profile is required.
Privilege Required
You need write permission to the CDS object entry (the target profile
entry).
NOTE
This command is replaced at Revision 1.1 by the dcecp command and
may not be provided in future releases of DCE.
EXAMPLES
The following commands run RPCCP and remove the profile named
/.:/LandS/anthro/molly_o_profile:
$ rpccp
rpccp> remove profile /.:/LandS/anthro/molly_o_profile
RELATED INFORMATION
Commands: add element
remove element
show profile
1.14 - show_entry
NAME
show entry - Shows the NSI attributes of a name service entry
SYNOPSIS
rpccp show entry entry-name [-i if-id] [-s syntax] [-u]
OPTIONS
-i Selects a specified interface identifier (optional).
Only elements containing that identifier are shown.
The interface identifier value has the following form:
interface-uuid,major-version.minor-version
The UUID is a hexadecimal string and the version numbers
are decimal strings, for example:
-i ec1eeb60-5943-11c9-a309-08002b102989,1.1
Leading zeros in version numbers are ignored.
-s Indicates the name syntax of the entry name (optional).
The only value for this option is the dce name syntax,
which is the default name syntax. Until an alternative
name syntax becomes available, specifying the -s option
is unnecessary.
-u Updates the local CDS cache copy of name service data
(optional). Name service data is cached locally on each
machine in a cell. If an rpccp inquiry can be satisfied
by data in the local CDS cache, this cached data is
returned. Locally cached copies of name service data
might not include a recent CDS update, however. If the
required data is not available in the local CDS cache,
rpccp goes to a CDS server(s) to retrieve the required
data. rpccp then updates the local CDS cache. Using the
-u option bypasses the local cache, allowing rpccp to go
directly to a CDS server for the inquiry. rpccp then
updates the local CDS cache.
ARGUMENTS
entry-name
Indicates the name of the target name service entry.
For an entry in the local cell, you can omit the cell
name and specify only the cell-relative name.
DESCRIPTION
The show entry command shows the NSI attributes of a name service
entry. The name of the entry is required.
Note that this operation shows all of the compatible bindings for a
given interface.
The show entry command shows the same list of string bindings as the
import operation returns for the specified entry. This list includes
all string bindings that refer to a major version that matches the
specified version and a minor version that is equal to or greater
than the specified version. The list may include string bindings
exported for other versions of the interface that are upwardly
compatible, rather than for this particular version of the interface.
Privilege Required
You need read permission to the CDS object entry (the target name
service entry).
NOTE
This command is replaced at Revision 1.1 by the dcecp command and
may not be provided in future releases of DCE.
EXAMPLES
The following command operates from the system prompt to show the
name service entry /.:/LandS/anthro/calendar_mgr_node_3.
$ rpccp show entry /.:/LandS/anthro/Cal_host_3
The following commands run the control program and show the name
service entry /.:/LandS/anthro/Calendar_group:
$ rpccp
rpccp> show entry \
> /.:/LandS/anthro/Calendar_group
RELATED INFORMATION
Commands: add entry
remove entry
1.15 - show_group
NAME
show group - Shows the members of a group
SYNOPSIS
rpccp show group group-entry-name [-m member] [-r [integer]]
[-s syntax] [-u]
OPTIONS
-m Declares the name of a single group member.
-r Indicates that the show group operation recurses. If
any members of a group are also groups, their entries are
shown. By default, the -r option causes the show group
operation to recurse until all nested groups are expanded;
for example, -r shows the members of the specified group
and all nested groups. You can limit recursion to one or
more levels by specifying a decimal integer as part of the
-r option. For example, -r 1 shows the members of the
specified group and, for members that are groups, the
command also shows their members; then recursion stops.
Without the -r option, only the members of the specified
group are shown.
-s Indicates the name syntax of the entry name (optional).
The only value for this option is the dce name syntax,
which is the default name syntax. Until an alternative
name syntax becomes available, specifying the -s option
is unnecessary.
-u Updates the local CDS cache copy of name service data
(optional). Name service data is cached locally on each
machine in a cell. If an rpccp inquiry can be satisfied
by data in the local CDS cache, this cached data is
returned. Locally cached copies of name service data
might not include a recent CDS update, however. If the
required data is not available in the local CDS cache,
rpccp goes to a CDS server(s) to retrieve the required
data. rpccp then updates the local CDS cache. Using the
-u option bypasses the local cache, allowing rpccp to go
directly to a CDS server for the inquiry. rpccp then
updates the local CDS cache.
ARGUMENTS
group-entry-name
Indicates the name of the target group. For an entry in
the local cell, you can omit the cell name and specify
only the cell-relative name.
DESCRIPTION
The show group command shows the members of a group in the name
service database. The entry name of the group is required. Unless
it is limited to a specific member (by the -m option), the show
group command shows all members. The command shows only the members
in the specified group; the -r option enables you to show members of
nested groups.
Privilege Required
You need read permission to the CDS object entry (the target group
entry). If you use the -r option, you also need read permission
to any nested groups.
NOTE
This command is replaced at Revision 1.1 by the dcecp command and
may not be provided in future releases of DCE.
EXAMPLES
The following example shows all the members of the group
/.:/LandS/anthro/Calendar_group, in the order in which they were
added to the group:
$ rpccp
rpccp> show group /.:/LandS/anthro/Calendar_group
The following command operates from the system prompt to show a
specific member of the group /.:/LandS/dept/Calendar_group:
$ rpccp show group \
> -m /.:/LandS/anthro/Cal_host_2 \
> /.:/LandS/anthro/Calendar_group
RELATED INFORMATION
Commands: add member
remove group
remove member
1.16 - show_mapping
NAME
show mapping - Shows the elements of the either the local or a
remote endpoint map
SYNOPSIS
rpccp show mapping [host-address] [-i if-id [-v versions]]
[-o object-uuid [ -o object-uuid...]]
OPTIONS
-i Defines an interface identifier to be shown (optional).
Only one interface can be shown in a single operation.
If specified, only elements containing this interface
identifier are shown. The -i option can be qualified by
the -v option. The value has the following form:
interface-uuid,major-version.minor-version
The UUID is a hexadecimal string and the version numbers
are decimal strings, for example:
-i ec1eeb60-5943-11c9-a309-08002b102989,1.1
Leading zeros in version numbers are ignored.
-v Indicates how a specified interface version is used
(optional). If it is used without the -i option, the
-v option is ignored. The possible combinations of
versions for the -v option and their actions are
described in the following table.
________________________________________________
Versions Action
________________________________________________
all The interface version is ignored.
exact Both the major and minor versions
must match the specified versions.
compatible The major version must match the
specified version, and the minor
version must be greater than or
equal to the specified version.
major_only The major version must match the
specified version; the minor ver-
sion is ignored.
upto The major version must be less than
or equal to that specified. If the
major versions are equal, the minor
version must be less than or equal
to that specified.
________________________________________________
If the -v option is absent, the command shows compatible
version numbers.
-o Defines an object to be shown (optional). Each show
mapping command accepts up to 32 -o options. The UUID
is a hexadecimal string, for example:
-o 3c6b8f60-5945-11c9-a236-08002b102989
ARGUMENTS
host-address
The host-address argument is a string binding that indicates
where to find the target endpoint map. When accessing the
local endpoint map, you can specify which protocol sequence
to use (optional); for example,
ncadg_ip_udp:
When accessing a remote endpoint map, you must specify both
a protocol sequence and a network address for the remote
system (required); for example,
ncadg_ip_udp:16.20.16.44
An endpoint is unnecessary in local or remote host
addresses, and the remove mapping command ignores any
endpoint specified as part of a host address.
DESCRIPTION
The show mapping command shows elements of an endpoint map.
Each element corresponds to an object UUID, interface identifier,
annotation, and binding information. The binding information
contains an RPC protocol sequence, a network address, and an
endpoint within square brackets (rpc- protseq:network-addr[endpoint]).
The endpoint map can be either the local endpoint map or the endpoint
map of a specified remote host. If entered without a remote host
address, the command accesses the local endpoint map. For the local
endpoint map, a show mapping command without any options displays all
the map elements. For a remote endpoint map, map elements are
accessible only for protocol sequences that are supported on both
your system and the remote system.
The options list a selected subset of map elements. The - i option
selects a specific interface, and the -v option qualifies the -i
option. The -o object selects a specific object. You can use from
0 to 32 -o options per command. The options work together to
specify the subset of elements for the target protocol sequence(s).
NOTES
Note that to ensure that you can remotely display all map elements
from every remote endpoint map, run the RPC control program on a
system that supports all of the protocol sequences available in
your network environment.
This command is replaced at Revision 1.1 by the dcecp command and
may not be provided in future releases of DCE.
EXAMPLES
The following commands start the control program and show the map
elements in the local endpoint map that contain the specified
interface identifier:
$ rpccp
rpccp> show mapping -i ec1eeb60-5943-11c9-a309-08002b102989,1.1
The following rpccp show mapping command operates from the system
prompt. The command accesses the endpoint map of the remote host
specified by the host address (ncadg_ip_udp:16.20.16.44) and displays
the one map element that contains both the specified interface
identifier and the specified object UUID:
$ rpccp show mapping \
> -i ec1eeb60-5943-11c9-a309-08002b102989,1.1 \
> -o 30dbeea0-fb6c-11c9-8eea-08002b0f4528 \
> ncadg_ip_udp:16.20.16.44
RELATED INFORMATION
Commands: remove mapping
show server
1.17 - show_profile
NAME
show profile - Shows the elements of a profile
SYNOPSIS
rpccp show profile profile-entry-name {-d | -a annotation |
-i if-id [-v versions] -m member}
[-r [integer]] [-s syntax] [-u]
OPTIONS
-d Selects the default profile element. With the -d option,
the -a, -i, and -m options are ignored.
Note that the -a option works with the -d option, but do
not use them together.
-a Declares a single annotation field (optional). The -a
option selects only elements containing the specified
annotation. The option is case sensitive.
The -a option works alone or in combination with the -i
or -m options or both; only elements containing all the
specified values are displayed.
Note that the shell supports quotation marks around the
annotation field of profile elements, allowing you to
include internal spaces in an annotation; the control
program does not. To specify or refer to annotations
from within the control program, limit each annotation
to an unbroken alphanumeric string; for example,
CalendarGroup. To refer to annotations from the system
prompt, do not incorporate quotation marks into any
annotation.
-i Selects a specified interface identifier (optional).
Only elements containing that interface identifier are
shown. The interface identifier value has the following
form:
interface-uuid,major-version.minor-version
The UUID is a hexadecimal string and the version numbers
are decimal strings, for example:
-i ec1eeb60-5943-11c9-a309-08002b102989,1.1
Leading zeros in version numbers are ignored.
The -i option works alone or in combination with the -a
or -m options or both; only elements containing all the
specified values are displayed. When the -d option is
specified, the -i option is ignored.
-m Declares a single member name (optional). Only elements
containing that member name are shown.
The -m option works alone or in combination with the -a
or -i options or both; only elements containing all the
specified values are displayed. When the -d option is
specified, the -m option is ignored.
-r Indicates that the show profile operation recurses. If
the member of any element of a profile is also a profile,
its elements are shown. By default, the -r option causes
the show profile operation to recurse until all nested
profiles are expanded; for example, -r shows the elements
of the specified profile and of all nested profiles.
You can limit recursion to one or more levels by specifying
a decimal integer as part of the -r option. For example,
-r 1 shows the elements of the specified profile and, for
element members that are profiles, the command also shows
their elements; then recursion stops.
Without the -r option, only the profile elements in the
specified entry are shown.
-s Indicates the name syntax of the entry name (optional).
The only value for this option is the dce name syntax,
which is the default name syntax. Until an alternative
name syntax becomes available, specifying the -s option
is unnecessary.
-u Updates the local CDS cache copy of name service data
(optional). Name service data is cached locally on each
machine in a cell. If an rpccp inquiry can be satisfied
by data in the local CDS cache, this cached data is
returned. Locally cached copies of name service data
might not include a recent CDS update, however. If the
required data is not available in the local CDS cache,
rpccp goes to a CDS server(s) to retrieve the required
data. rpccp then updates the local CDS cache. Using the
-u option bypasses the local cache, allowing rpccp to go
directly to a CDS server for the inquiry. rpccp then
updates the local CDS cache.
-v Indicates how a specified interface version is used
(optional). If it is used without the -i option, the
-v option is ignored. The possible combinations of
versions for the -v option and their actions are
described in the following table.
________________________________________________
Versions Action
________________________________________________
all The interface version is ignored.
exact Both the major and minor versions
must match the specified versions.
compatible The major version must match the
specified version, and the minor
version must be greater than or
equal to the specified version.
major_only The major version must match the
specified version; the minor ver-
sion is ignored.
upto The major version must be less than
or equal to that specified. If the
major versions are equal, the minor
version must be less than or equal
to that specified.
________________________________________________
If the -v option is absent, the command shows compatible
version numbers.
ARGUMENTS
profile-entry-name
Indicates the name of the target profile. For an entry
in the local cell, you can omit the cell name and specify
only the cell-relative name.
DESCRIPTION
The show profile command shows the elements of a profile in the name
service database. The entry name of the profile is required.
By default, all elements in the profile are shown. You can select
a subset of the elements by specifying the -a, -i, or -m options.
The -r option enables you to show nested profiles.
Privilege Required
You need read permission to the CDS object entry (the target profile
entry). If you use the -r option, you also need read permission to
any nested profiles.
NOTE
This command is replaced at Revision 1.1 by the dcecp command and
may not be provided in future releases of DCE.
EXAMPLES
The following command operates from the system prompt to show the
cell profile /.:/cell-profile in the local cell:
$ rpccp show profile /.:/cell-profile
The initial DCL command sets up a logical name MOLLY_O_PROFILE,
which represents the user profile /.:/LandS/anthro/molly_o_profile.
The control program commands start the control program and show the
user profile associated with the MOLLY_O_PROFILE logical name, as
follows:
$ define MOLLY_O_PROFILE "/.:/LandS/anthro/molly_o_profile"
$ rpccp
rpccp> show profile MOLLY_O_PROFILE
RELATED INFORMATION
Commands: add element
remove element
remove profile
1.18 - show_server
NAME
show server - Shows the binding information, interface identifiers,
and object UUIDs in a server entry
SYNOPSIS
rpccp show server server-entry-name [-i [if-id]]
[-o [object-uuid]] [-s syntax] [-u]
OPTIONS
-i Shows interface identifiers from binding information
found in the entry (optional). Without the -i option,
the command displays all interface identifiers.
To display a specific interface, supply its identifier
as the value. The value has the following form:
interface-uuid,major-version.minor-version
The UUID is a hexadecimal string and the version numbers
are decimal strings, for example:
-i ec1eeb60-5943-11c9-a309-08002b102989,1.1
Leading zeros in version numbers are ignored.
-o Shows object UUIDs found in the entry (optional).
Without the -o option, the command displays all object
UUIDs. To display a specific object UUID, supply its
string representation as the value, for example:
-o 3c6b8f60-5945-11c9-a236-08002b102989
-s Indicates the name syntax of the entry name (optional).
The only value for this option is the dce name syntax,
which is the default name syntax. Until an alternative
name syntax becomes available, specifying the -s option
is unnecessary.
-u Updates the local CDS cache copy of name service data
(optional). Name service data is cached locally on each
machine in a cell. If an rpccp inquiry can be satisfied
by data in the local CDS cache, this cached data is
returned. Locally cached copies of name service data
might not include a recent CDS update, however. If the
required data is not available in the local CDS cache,
rpccp goes to a CDS server(s) to retrieve the required
data. rpccp then updates the local CDS cache. Using
the -u option bypasses the local cache, allowing rpccp
to go directly to a CDS server for the inquiry. rpccp
then updates the local CDS cache.
ARGUMENTS
server-entry-name
Indicates the name of the target server. For an entry in
the local cell, you can omit the cell name and specify
only the cell-relative name.
DESCRIPTION
The show server command shows the RPC binding information, interface
identifiers, and object UUIDs in a server entry. The entry name of
the server entry is required.
This operation shows all of the potential bindings for an interface.
By default, this command displays bindings for the specified version
of the interface and for upwardly compatible versions of the
interface. The -v option controls which versions are targeted by
this command.
Privilege Required
You need read permission to the CDS object entry (the target server
entry).
NOTE
This command is replaced at Revision 1.1 by the dcecp command and
may not be provided in future releases of DCE.
EXAMPLES
The following commands start the control program and show the server
entry /.:/LandS/anthro/Cal_host_2 in the local cell:
$ rpccp
rpccp> show server /.:/LandS/anthro/Cal_host_2
The following command operates from the system prompt to display
a specific object and interface from the server entry
/.:/LandS/anthro/Cal_host_2 in the local cell:
$ rpccp show server \
> /.:/LandS/anthro/Cal_host_2 \
> -o 16977538-e257-11c9-8dc0-08002b0f4528 \
> -i ec1eeb60-5943-11c9-a309-08002b102989,1.1
RELATED INFORMATION
Commands: export
import
unexport
1.19 - unexport
NAME
unexport - Removes binding information, interface identifiers,
and object UUIDs from a server entry
SYNOPSIS
rpccp unexport entry-name {[-i if-id [-v versions]] |
[-o object-uuid]} [-s syntax]
OPTIONS
-i Defines an interface identifier to be unexported
(optional). Only one interface can be unexported in
a single operation. If specified, binding information
for this interface is removed from the entry. The -i
option can be qualified by the -v option. The value
has the following form:
interface-uuid,major-version.minor-version
The UUID is a hexadecimal string and the version numbers
are decimal strings, for example:
-i ec1eeb60-5943-11c9-a309-08002b102989,1.1
Leading zeros in version numbers are ignored.
-v Indicates how a specified interface version is used
(optional). If it is used without the -i option, the
-v option is ignored. The possible combinations of
versions for the -v option and their actions are
described in the following table.
Versions Action
________________________________________________
all The interface version is ignored.
exact Both the major and minor versions
must match the specified versions.
compatible The major version must match the
specified version, and the minor
version must be greater than or
equal to the specified version.
major_only The major version must match the
specified version; the minor ver-
sion is ignored.
upto The major version must be less than
or equal to that specified. If the
major versions are equal, the minor
version must be less than or equal
to that specified.
________________________________________________
If the -v option is absent, the command shows compatible
version numbers.
-o Defines an object to be unexported (optional). Each
unexport command accepts up to 32 -o options. The
UUID is a hexadecimal string, for example:
-o 3c6b8f60-5945-11c9-a236-08002b102989
-s Indicates the name syntax of the entry name (optional).
The only value for this option is the dce name syntax,
which is the default name syntax. Until an alternative
name syntax becomes available, specifying the -s option
is unnecessary.
ARGUMENTS
entry-name
Indicates the name of the target name service entry.
Usually, the target is a server entry. However, objects
also can be exported (without an interface identifier or
binding information) to a group or a profile.
For an entry in the local cell, you can omit the cell name
and specify only the cell-relative name.
DESCRIPTION
The unexport command removes binding information and an interface
identifier, object UUIDs, or both from a server entry, or it removes
object UUIDs from a group's entry. The command requires the entry
name and either the interface identifier or one or more object UUIDs.
By default, the unexport operation removes compatible interface
versions.
Privilege Required
You need both read permission and write permission to the CDS object
entry (the target name service entry).
NOTE
This command is replaced at Revision 1.1 by the dcecp command and
may not be provided in future releases of DCE.
EXAMPLES
The initial DCL command sets up a logical name Calendar_1_1,
which represents the interface identifier of an RPC interface.
The control program commands start the control program and
remove (unexport) the Calendar Version 1.1 interface from the
server entry /.:/LandS/anthro/Cal_host_2 in the local cell, as
follows:
$ define Calendar_1_1 "ec1eeb60-5943-11c9-a309-08002b102989,1.1"
$ rpccp
rpccp> unexport \
> -i Calendar_1_1 \
> /.:/LandS/anthro/Cal_host_2
rpccp>
RELATED INFORMATION
Commands: export
import
show server
| 2 - Environmental Influences on Command Syntax |
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 Control Program
_______________________________________________________________
Strings within quotation Supported Not required
marks
Wildcard substitution Supported Unsupported
_______________________________________________________________
Some UNIX systems require that you place an escape symbol (\) before
string binding delimiters such as brackets ([ ]) or that you place
the delimiters within quotation marks (' ' or " ") at the system
prompt.
| 3 - Scope of the RPC Control Program Commands |
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
_____________________________
| 4 - Logical Names |
The control program supports logical names. Using logical names
facilitates interactive use of the control program.
To distinguish logical names, rpccp* reference pages follow the
convention of using all uppercase letters for examples of logical
names. Note that OpenVMS logical names are NOT case sensitive.
User-defined logical names
You can set a logical name to represent values to rpccp.
Using a logical name 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
For example, in the following example, the logical name
JANE_CAL represents an object UUID; the target name service
entry, /.:/LandS/anthro/Cal_host_2, is in the local cell:
$ DEFINE JANE_CAL 47f40d10-e2e0-11c9-bb29-08002b0f4528
$ rpccp
rpccp> export -o JANE_CAL /.:/LandS/anthro/Cal_host_2
DCE RPC logical names
The dce name syntax is the only syntax currently supported
by the DCE Cell Directory Service (CDS). However, the Name
Service Interface (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 logical name. 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 a logical name. 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.
| 5 - Name Service Interface |
The remainder of this description contains information to help you use commands that call the name service interface to access name service entries (NSI commands). The DCE RPC name service interface (NSI) is independent of any particular name service. CDS, however, is the only name service available for DCE RPC Version 1.0 applications. For more details on the name service interface, see the OSF DCE Application Development Guide-Core Components. For a description of the DCE Cell Directory Service, see the OSF DCE Administration Guide-Core Components.
5.1 - Name Service Entries
To store information about RPC servers, interfaces, and objects, the
NSI defines the following name service entries:
server entry
Stores binding information, interface identifiers, and
object UUIDs for an RPC server.
group Corresponds to one or more RPC servers that offer a common
RPC interface, type of RPC object, or both.
profile Defines search paths for looking in a name service database
for a server that offers a particular RPC interface and
object.
Note that when the NSI is used with the Cell Directory Service, the
name service entries are CDS object entries.
5.2 - 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 (using X.500 name syntax)
For example:
/.../C=US/O=uw/OU=MadCity
The symbol /... begins a cell name. The letters before the
equal signs (=) are abbreviations for country (C),
organization (O), and organization unit (OU).
For entries in the local cell, the cell name can be
represented by a /.: prefix, in place of the actual cell
name; for 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 is to
the left of the directory pathname, and the leaf
name is to the right, 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 the NSI is used with CDS, the cell-relative name is a
CDS name.
5.3 - 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; for example,
by identifying its owner or its contents. 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 ser-
vice 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, for 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 iden-
tifier, 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 a 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 DCE Security Service part of the 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
5.4 - Permissions Required
To use the NSI commands to access entries in a CDS database, you
need access control list (ACL) permissions. Depending on the 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 insert permission to the parent
directory.
+ To read an entry, you need read permission to the CDS object
entry.
+ To write to an entry, you need write permission to the CDS
object entry.
+ To delete an entry, you need 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 the NSI commands of the control program are
described in the reference pages.
| 6 - EXAMPLES |
The following command starts the RPC control program:
$ rpccp
rpccp>
The following command at the system prompt removes the entry
/.:/LandS/anthro/Cal_host_2:
$ rpccp remove entry \
> /.:/LandS/anthro/Cal_host_2
|
|
