NAME

rpcentry  — A  dcecp object that manages an RPC entry in the DCE Cell Directory Service

SYNOPSIS

rpcentry create entry_name_list

rpcentry delete entry_name_list

rpcentry export entry_name_list  [object object_uuid_list]  [interface interface_id binding string_binding_list ]

rpcentry help  [operation | verbose  ]

rpcentry import entry_name_list interface interface_id  [object object_uuid]  [max integer]  [noupdate ]

rpcentry operations

rpcentry show entry_name_list interface interface_id_list  [object object_uuid_list]  [noupdate ]

rpcentry unexport entry_name_list  [object object_uuid_list]  [interface interface_id  [version versions] ]

Arguments

entry_name_list
Specifies a list of one or more names of the target name service entry. For an entry in the local cell, you can omit the cell name and specify only cell-relative names.

operationThe name of the rpcentry  operation for which to display help information. 

Description

The rpcentry  object represents a remote procedure call (RPC) server entry in the cell name service.  Use the rpcentry  commands to create, modify, display, and delete name service entries. 

Data Structures

interface_id
The interface identifier of an RPC interface.  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:

-interface ec1eeb60-5943-11c9-a309-08002b102989,3.11  

Leading zeros in version numbers are ignored. 

Alternatively, you can use dcecp  string syntax in the following form:

{interface-UUID major-version.minor-version}

For example:

-interface {458ffcbe-98c1-11cd-bd93-0000c08adf56 1.0}  

string_binding_list
An RPC string binding that describes a server’s location.  The value has the form of an RPC string binding, without an object UUID.  The binding information contains an RPC protocol, a network address, and (sometimes) an endpoint within [] (square brackets) as follows:

rpc-prot-seq:network-addr[endpoint]    

For a well-known endpoint, include the endpoint in the string binding surrounded by brackets.  You may need to use the \fP (backslash) to escape the brackets as shown in the following example.  Otherwise dcecp  interprets the brackets as enclosing another command. 

-binding 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  

Alternatively, you can use dcecp  string syntax.  For example:

-binding {ncacn_ip_tcp 130.105.1.227 1072}  

object_uuid
The UUID of an object.  The UUID is a hexadecimal string, for example:

-object 3c6b8f60-5945-11c9-a236-08002b102989  

Alternatively, you can use dcecp  string syntax.  For example:

-object {3c6b8f60-5945-11c9-a236-08002b102989}  

versionSpecifies which interface version numbers should be returned by a show operation.  Specify versions by using one of the following values for the version  option:

allThe interface version is ignored. 

exactBoth 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 version is ignored.

uptoThe 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 version  option is absent, the command shows compatible version numbers. 

Errors

A representative list of errors that might be returned is not shown here.  Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages. 

Operations

rpcentry create

Creates an empty entry in the name service.  The syntax is as follows:

rpcentry create entry_name_list

The create  operation creates an empty entry in the name service.  Since an empty entry is the same as an empty RPC group or RPC profile, calling rpcentry create  is the same as calling rpcgroup create  or rpcprofile create .  The entry_name_list argument is a list of names of RPC entries to be created.  If the RPC entry already exists, an error message is returned.  This operation returns on empty string on success. 

Privileges Required

To create an rpcentry , you need i (insert) permission to the parent directory and both r (read) permission and w (write) permission to the Cell Directory Service (CDS) object entry (the target name service entry). 

Examples

The following command adds an unspecialized entry to the name service database:

dcecp> rpcentry create /.:/LandS/anthro/Cal_host_2
dcecp>  

rpcentry delete

Removes the specified entry from the name service.  The syntax is as follows:

rpcentry delete entry_name_list

The delete  operation removes the specified entry from the name service.  The entry_name_list argument is a list of one or more names of server entries to be deleted.  This operation returns an empty string on success.  If the entry does not exist, an error is returned. 

Privileges Required

To delete an entry, you need r (read) permission to the CDS object entry (the target name service entry).  You also need d (delete ) permission to the CDS object entry or to the parent directory. 

Examples

The following command removes the entry /.:/LandS/anthro/Cal_host_2 from the local cell of the name service database:

dcecp> rpcentry delete /.:/LandS/anthro/Cal_host_2
dcecp> 

rpcentry export

Transfers information to the specified entry in the name service.  The syntax is as follows:

rpcentry export entry_name_list {[object  object_uuid_list]
[interface  interface_id binding  string_binding_list]}

Options

object  object_uuid_list
Declares the UUID of an object.  Accepts a list of up to 32 object UUIDs.  The UUID is a hexadecimal string.  See Data Structures for the format of the object UUID. 

interface  interface_id
Declares the interface identifier of one RPC interface.  If you specify an interface identifier, you must specify at least one binding  option. 

See Data Structures for the format of the interface identifier. 

binding  string_binding_list
Declares a list of one or more protocol sequences (RPC bindings).  To use this option, you must also use the interface  option to specify an interface identifier. 

See Data Structures for the format of a protocol sequence. 

The export  operation transfers information to the specified entry in the name service.  The entry_name_list argument is a list of one or more names of server entries to be exported to.  If an entry does not exist, it is created.  Uses the interface , binding , and object options to specify what to export.  This operation returns an empty string on success. 

Privileges Required

To export an entry, you need both r (read) permission and w (write) permission to the CDS object entry (the target name service entry).  If the entry does not exist, you also need i (insert) permission to the parent directory. 

Examples

The following example uses the dcecp  string syntax to export an RPC entry to CDS:

dcecp> rpcentry export /.:/subsys/applications/bbs_server
> -interface {458ffcbe-98c1-11cd-bd93-0000c08adf56 1.0}
> -binding {ncacn_ip_tcp 130.105.1.227}
> -object {76030c42-98d5-11cd-88bc-0000c08adf56}
dcecp> 

rpcentry help

Returns help information about the rpcentry  object and its operations.  The syntax is as follows:

rpcentry help [operation | verbose ]

Options

verboseDisplays information about the rpcentry  object. 

Used without an argument or option, the rpcentry help  command returns brief information about each rpcentry  operation.  The optional operation argument is the name of an operation about which you want detailed information.  Alternatively, you can use the verbose  option for more detailed information about the rpcentry  object itself. 

Privileges Required

No special privileges are needed to use the rpcentry help command. 

Examples

dcecp> rpcentry help
create              Creates a list of empty RPC entries.
delete              Deletes a list of RPC entries.
export              Stores bindings in a list of RPC entries.
import              Returns the bindings from a list of RPC entries.
show                Returns the attributes of a list of RPC entries.
unexport            Deletes bindings from a list of RPC entries.
help                Prints a summary of command-line options.
operations          Returns a list of the valid operations for this command.
dcecp> 

rpcentry import

Returns a string binding from the specified RPC entry.  The syntax is as follows:

rpcentry import entry_name_list interface  interface_id
 [object  object_uuid] [max  integer] [noupdate ]

Options

interface  interface_id
Declares the interface identifier of one RPC interface.

See Data Structures for the format of the interface identifier. 

object  object_uuid
Declares the UUID of one object.  The UUID is a hexadecimal string.

See Data Structures for the format of the object UUID. 

max  integer
Specifies the maximum number of string bindings to return.  A value greater than one returns a list containing up to the number of bindings specified by the value.

noupdateNormally, name service data is cached locally on each machine in a cell.  If a name service inquiry can be satisfied by data in the local CDS cache, this cached data is returned.  However, locally cached copies of name service data might not include a recent CDS update.  If the noupdate  option is not specified, dcecp goes to a CDS server to retrieve the required data, updating the local CDS cache.  Use the noupdate  option to avoid taking the time to update the local cache when you have reason to believe that the local cache is up to date. 

The import  operation returns a string binding from the specified RPC entry.  The entry_name_list argument is a list of names of RPC entries (not a list of RPC entries) to import from.  The order of returned bindings is arbitrary. 

Privileges Required

You need r (read) permission to the specified CDS object entry (the starting name service entry) and to any CDS object entry in the resulting search path. 

Examples

The following command imports a binding:

dcecp> rpcentry import /.:/LandS/anthro/Cal_host_3
> -interface {ec1eeb60-5943-11c9-a309-08002b102989 1.1}
> -object 30dbeea0-fb6c-11c9-8eea-08002b0f4528
{ncacn_ip_tcp 130.105.1.227}
dcecp>

rpcentry operations

Returns a list of the operations supported by the rpcentry object.  The syntax is as follows:

rpcentry operations

The list of available operations is in alphabetical order except for help  and operations, which are listed last. 

Privileges Required

No special privileges are needed to use the rpcentry operations command. 

Examples

dcecp> rpcentry operations
create delete export import show unexport help operations
dcecp>  

rpcentry show

Returns a list containing the binding information in the specified RPC entries.  The syntax is as follows:

rpcentry show entry_name_list interface  interface_id_list
 [object  object_uuid_list] [noupdate ]

Options

interface  interface_id_list
Declares a list of one or more interface identifiers of RPC interfaces.

See Data Structures for the format of the interface identifier. 

object  object_uuid_list
Declares the UUID of an object.  Accepts a list of up to 32 object UUIDs.  The UUID is a hexadecimal string.

See Data Structures for the format of the object UUID. 

noupdateNormally, name service data is cached locally on each machine in a cell.  If a name service inquiry can be satisfied by data in the local CDS cache, this cached data is returned.  However, locally cached copies of name service data might not include a recent CDS update.  If the noupdate  option is not specified, dcecp goes to a CDS server to retrieve the required data, updating the local CDS cache.  Use the noupdate  option to avoid taking the time to update the local cache when you have reason to believe that the local cache is up to date. 

The show  operation returns a list containing the binding information in the specified RPC entry.  The entry_name_list argument is a list of one or more names of RPC entries to return information about. 

The returned list consists of two lists.  Each item in the first list is also a list, the first two elements of which are the interface identifier (the UUID and then the version), and the remaining are string bindings in Tcl syntax.  The second list is a list of object UUIDs exported by the server.  The order of the data returned is arbitrary. 

Privileges Required

You need r (read) permission to the CDS object entry (the target name service entry). 

Examples

The following command uses the dcecp  string syntax to show a name service entry:

dcecp> rpcentry show /.:/subsys/applications/bbs_server
{458ffcbe-98c1-11cd-bd93-0000c08adf56 1.0
  {ncacn_ip_tcp 130.105.1.227}}
{76030c42-98d5-11cd-88bc-0000c08adf56}
dcecp>

The following command operates from the system prompt to show a name service entry:

% dcecp  -c rpcentry show /.:/subsys/applications/bbs_server
{458ffcbe-98c1-11cd-bd93-0000c08adf56 1.0
  {ncacn_ip_tcp 130.105.1.227}}
{76030c42-98d5-11cd-88bc-0000c08adf56}
%

rpcentry unexport

Removes binding information from an entry in the name service.  The syntax is as follows:

rpcentry unexport entry_name_list
{[object  object_uuid_list] [interface  interface_id [version  versions]]}

Options

object  object_uuid_list
Declares the UUID of an object.  Accepts a list of up to 32 object UUIDs.  The UUID is a hexadecimal string.

See Data Structures for the format of the object UUID. 

interface  interface_id
Declares the interface identifier of an RPC interface.  Only a single interface_id can be specified. 

See Data Structures for the format of the interface identifier. 

version  versions
Specifies interface version numbers to be returned with the unexport  operation. 

See Data Structures for the exact behavior and format of the version values. 

The unexport  operation removes binding information from an entry in the name service.  The entry_name_list argument is a list of one or more entry names from which binding information is to be removed.  This operation returns an empty string on success. 

Privileges Required

You need d (delete ) permission on the parent directory and r (read) permission and w (write) permission on the CDS object entry (the target name service entry). 

Examples

The following example uses the dcecp  syntax to unexport the binding information for an interface.  The third command entered (rpcentry show ) shows the RPC entry after the unexport operation; the object UUID remains in the entry. 

dcecp> rpcentry show /.:/subsys/applications/bbs_server
{458ffcbe-98c1-11cd-bd93-0000c08adf56 1.0
  {ncacn_ip_tcp 130.105.1.227}}
{76030c42-98d5-11cd-88bc-0000c08adf56}
dcecp>
 dcecp> rpcentry unexport /.:/subsys/applications/bbs_server  
> -interface {458ffcbe-98c1-11cd-bd93-0000c08adf56 1.0}
dcecp>
 dcecp> rpcentry show /.:/subsys/applications/bbs_server
{76030c42-98d5-11cd-88bc-0000c08adf56}
dcecp> 

Related Information

Commands: dcecp(8dce), endpoint(8dce), rpcgroup(8dce), rpcprofile(8dce).