1 RPC The Remote Procedure Call (RPC) service provides connections between individual procedures in an application across heterogeneous systems in a transparent way. o The process or daemon which maintains the local endpoint map for RPC servers and looks up endpoints for RPC clients is called DCE Daemon (DCED). It allows client/server RPC applications to register their specific endpoints. Registering endpoints allows remote clients of the application to find the server application's entry point on the system. The DCE daemon can be started or stopped with the command files DCE$RPC_STARTUP.COM and DCE$RPC_SHUTDOWN.COM, which are located in SYS$COMMON:[SYSMGR]. o The rpccp control program accesses DCE$RPCCP.EXE, the RPC control program. RPCCP also supports showing the elements of the local endpoint map and removing elements from it. 2 Admin_Intro intro NAME Introduction to the DCE daemon and RPC control program commands DESCRIPTION RPC provides two administrative facilities, the DCE daemon and the RPC control program. o The DCE daemon is a process that provides the endpoint map service, which maintains the local endpoint map for local RPC servers and looks up endpoints for RPC clients. An endpoint is the address of a specific instance of a server executing in a particular address space on a given system (a server instance). Each endpoint can be used on a system by only one server at a time. An endpoint map is a database where servers register their binding information, including endpoints, for each of their RPC interfaces and the associated RPC objects. Each combination of binding information, interface identifier, and object UUID uses a distinct element in the local endpoint map. Running the DCE$RPC_STARTUP.COM procedure starts the RPC daemon. The DCE$RPC_SHUTDOWN.COM procedure is used to stop the RPC daemon. o The control program provides a set of commands for managing endpoint maps. The control program supports showing endpoint map elements and removing any set of map elements from the local endpoint map or from any remote endpoint map. The rpccp command starts the RPC control program (DCE$RPCCP.EXE). EXIT VALUES The RPC control program reports RPC error messages on the command line. If the command executes successfully, the value returned is 1 (one); otherwise, the value is an OpenVMS DCE error status. RELATED INFORMATION Type HELP RPC for help about: Commands: dced rpccp STARTING and STOPPING RPC: The RPC daemon can be started or stopped with the two new command files DCE$RPC_STARTUP.COM and DCE$RPC_SHUTDOWN.COM, which are located in SYS$COMMON:[SYSMGR]. STARTING: To start the DCE daemon, execute DCE$RPC_STARTUP.COM. The following options may be specified: [NO]CONFIRM - Turns user prompting on or off. CONFIRM is the default. STOPPING: To stop the Remote Procedure Call daemon execute DCE$RPC_SHUTDOWN.COM. The following options may be specified in any order. [NO]CONFIRM - Turns user prompting on or off. CONFIRM is the default. CLEAN - Deletes all entries from the RPC endpoint database. Note: The DCE daemon must not be stopped if any DCE components or RPC applications are running on the system. 2 rpccp NAME rpccp - Starts the RPC control program SYNOPSIS rpccp [ rpccp-command ] 3 ARGUMENTS rpccp-command Specifies one of the following control program commands: exit Leaves the RPC control program. help Displays a list of commands or the possible options of a specified command. quit Leaves the RPC control program. remove mapping Removes specified elements from the local endpoint map or from the endpoint map of a specified remote host. show mapping Shows the elements of the local endpoint map. 3 DESCRIPTION The RPC control program (rpccp) provides a set of commands 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 $). o From inside the control program: You can 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 mapping 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. o From the system prompt: Interactively or in a command procedure, enter the rpccp command with an internal command of the control program as the first argument. 4 Arguments_and_Options Except for the exit and quit commands, rpccp commands have one or more options. Each option is identified by a hyphen (-) followed by a letter; for example, -s. Some options require arguments. ___________________________________________________________ Function At System Prompt Inside Control Program ___________________________________________________________ Strings within Supported Not required quotation marks Wildcard Supported Unsupported substitution ___________________________________________________________ 4 RPC_Control_Program_Commands _________________________________________________________ Scope Command Unsupported in RPC-only Configuration _________________________________________________________ All entries add entry X remove entry X show entry X Server entry export X import X show server X unexport X Group add member X remove group X remove member X show group X Profile add element X remove element X remove profile X show profile X Endpoint map remove mapping show mapping ____________________________________________________ 3 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: exit quit 4 DESCRIPTION The help command displays information about the RPCCP command set or the options and argument associated with a specific command. 4 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 4 RELATED_INFORMATION Type HELP RPC for help about: Commands: remove mapping, rpccp, show mapping 3 remove_mapping NAME remove mapping - Removes specified elements from either the local or a remote endpoint map SYNOPSIS rpccp remove mapping [ host-address ] -b string-binding -i if-id [ -v versions ] [ -o object-uuid ] 4 OPTIONS -b Declares a string binding (required). 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, 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 Declares an interface identifier (required). Only one interface can be removed in a single operation. The interface identifier has the following form: interface-uuid,major-version.minor-version 4 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 what protocol sequence to use (optional); 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 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. 4 DESCRIPTION The remove mapping command removes one or more elements from an endpoint map. The target endpoint map can be either the local endpoint map or the endpoint map of a specified remote host. Each map element corresponds to an object UUID, interface identifier, annotation (optional), and binding information. The binding information contains an RPC protocol sequence, a network address, and an endpoint within brackets (rpc-prot-seq:network-addr[endpoint]). If entered without a remote host address as an argument, the command operates on the local endpoint map. 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). 4 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 \ > -b ncadg_ip_udp:16.20.16.64[3424] \ > -i EC1EEB60-5943-11C9-A309-08002B102989,1.1 \ > -o 30DBEEA0-FB6C-11C9-8EEA-08002B0F4528 $ The following commands start the control program and remove an element from a remote endpoint map. The remove mapping command operates on the endpoint map of the remote host specified by the host address (ncadg_ip_udp:16.20.16.44) and removes the map element that contains the specified interface identifier, server address (specified as a string binding), and object UUID: $ rpccp rpccp> remove mapping \ > -b ncadg_ip_udp:16.20.16.64[3424] \ > -i EC1EEB60-5943-11C9-A309-08002B102989,1.1 \ > -o 30DBEEA0-FB6C-11C9-8EEA-08002B0F4528 \ > ncadg_ip_udp:16.20.16.44 rpccp> 3 show_mapping NAME show mapping - Shows the elements of either the local or remote endpoint map SYNOPSIS rpccp show mapping [ host-address ] [ -i if-id [ -v versions ]] 4 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. -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 -v Indicates how a specified interface version is used (optional). If 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 version is ignored. upto The major and minor versions must be less than or equal to those specified. ________________________________________________ If the -v option is absent, the command shows compatible version numbers. 4 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 what protocol sequence to use (optional); 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 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. 4 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-prot-seq: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. Note: 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. 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). 4 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 Status: 200 OK Content-Type: text/plain; charset=ISO-8859-1 Last-Modified: Sat, 03 May 2014 07:56:20 GMT Script-Control: X-stream-mode=1 1 RPCGEN A code-generating tool for creating programming skeletons that implement the RPC mechanism. NOTE RPCGEN runs the C preprocessor, CC/DECC/PREPROCESSOR, on all input files before actually interpreted the files. Therefore, all the preprocessor directives are legal within an RPCGEN input file. For each type of output file, RPCGEN defines a special preprocessor symbol for use by the RPCGEN programmer: RPC_HDR Defined when compiling into header files RPC_XDR Defined when compiling into XDR routines RPC_SVC Defined when compiling into server-side skeletons RPC_CLNT Defined when compiling into client-side skeletons RPC_TBL Defined when compiling into RPC dispatch table In addition, RPCGEN does a little preprocessing of its own. RPCGEN passes any line beginning with "%" directly into the output file, without interpreting the line. Format 2 Parameters infile The input file to RPCGEN. The input file contains ONC RPC programming language. This language is very similar to the C language. By default, RPCGEN uses the name of the input file to create the four default output files as follows: o infile.H-the header file o infile_CLNT.C-the client skeleton o infile_SVC.C-the server skeleton with support for both UDP and TCP transports o infile_XDR.C-the XDR routines If you specify the /DISPATCH_TABLE qualifier, RPCGEN uses the default name infile_TBL.I for the dispatch table. 2 Qualifiers /CLIENT_STUBS_FILE Optional. DIGITAL UNIX equivalent: -l Default: Create a client skeleton file. Creates the client skeleton file. Mutually exclusive with the /DISPATCH_TABLE, /HEADER_FILE, /SERVER_STUBS_FILE, /TRANSPORT, and XDR_FILE qualifiers. /DEFINE /DEFINE = (name[=value][,....]) Optional. DIGITAL UNIX equivalent: -D Default: No definitions. Defines one or more symbol names. Equivalent to one or more #define directives. Names are defined as they appear in the argument to the qualifier. For example, /DEFINE=TEST=1 creates the line #define TEST=1 in the output files. If you omit the value, RPCGEN defines the name with the value 1. /DISPATCH_TABLE Optional. DIGITAL UNIX equivalent: -t Default: No dispatch file created. Creates the server dispatch table file. An RPCGEN dispatch table contains: o Pointers to the service routines corresponding to a procedure o A pointer to the input and output arguments o The size of these routines A server can use the dispatch table to check authorization and then to execute the service routine; a client may use it to deal with the details of storage management and XDR data conversion. Mutually exclusive with the /CLIENT_STUBS_FILE, /HEADER_FILE, /SERVER_STUBS_FILE, /TRANSPORT, and XDR_FILE qualifiers. /ERRLOG Optional. DIGITAL UNIX equivalent: -L Default: Logging to stderr. Specifies that servers should log errors to the operator console instead of using fprintf with stderr. You must install servers with OPER privileges in order to use this feature. /HEADER_FILE Optional. DIGITAL UNIX equivalent: -h Default: Create a header file. Creates the C data definitions header file. Use the /TABLE qualifier in conjunction with this qualifier to generate a header file that supports dispatch tables. Mutually exclusive with the /CLIENT_STUBS_FILE, /DISPATCH_TABLE, /SERVER_STUBS_FILE, /TRANSPORT, and XDR_FILE qualifiers. /INET_SERVICE Optional. DIGITAL UNIX equivalent: -I Default: no INETd support. Compiles support for INETd in the server side stubs. You can start servers yourself or you can have INETd start them. Servers started by INETd log all error messages to the operator console. If there are no pending client requests, the INETd servers exit after 120 seconds (default). You can change this default with the /TIMEOUT_SECONDS qualifier. When RPCGEN creates servers with INETd support, it defines two global variables: _rpcpmstart and rpcfdtype. The runtime value of _rpcpmstart is 1 or 0 depending on whether INDEd started the server program. The value of rpcfdtype should be SOCK_STREAM or SOCK_DGRAM depending on the type of the connection. /OUTPUT /OUTPUT = file Optional. DIGITAL UNIX equivalent: -o Default: Direct output to one of the standard default files. Use this qualifier to direct the output of the /CLIENT_STUBS_ FILE, /DISPATCH_TABLE, /HEADER_FILE, /SERVER_STUBS_FILE, /TRANSPORT, and /XDR_FILE qualifiers. /SERVER_STUBS_FILE Optional. DIGITAL UNIX equivalent: -m Default: Create a server skeleton file. Creates a server skeleton file without the main routine. Use this qualifier to generate a server skeleton when you wish to create your own main routine. This option is useful for programs that have callback routines and for programs that have customized initialization requirements. Mutually exclusive with the /CLIENT_STUBS_FILE, /DISPATCH_TABLE, /HEADER_FILE, /TRANSPORT, and XDR_FILE qualifiers. /TABLE Optional. DIGITAL UNIX equivalent: -T Default: No dispatch table code created. Creates the code in the header file to support an RPCGEN dispatch table. You can use this qualifier only when you are generating all files (the default) or when you are using the /HEADER_FILE qualifier to generate the header file. This /TABLE qualifier includes a definition of the dispatch table structure in the header file; it does not modify the server routine to use the table. /TRANSPORT /TRANSPORT [= (TCP, UDP)] Optional. DIGITAL UNIX equivalent: -s Default: Create a server-side skeleton that supports both protocols. Creates a server-side skeleton that includes a main routine that uses the given transport. The supported transports are UDP and TCP. To compile a server that supports multiple transports, specify both. /TIMEOUT_SECONDS /TIMEOUT_SECONDS=seconds Optional. DIGITAL UNIX equivalent: -K Default: 120 seconds. If INETd starts the server, this option specifies the time (in seconds) after which the server should exit if there is no further activity. By default, if there are no pending client requests, INETd servers exit after 120 seconds. This option is useful for customization. If seconds is 0, the server exits after serving a request. If seconds is -1, the server never exits after being started by INETd. /XDR_FILE Optional. DIGITAL UNIX equivalent: -c Default: Create an XDR file. You can customize some of your XDR routines by leaving those data types undefined. For every data type that is undefined, RPCGEN assumes that there exists a routine with the name xdr_ prepended to the name of the undefined type. Mutually exclusive with the /CLIENT_STUBS_FILE, /DISPATCH_TABLE, /HEADER_FILE, /TRANSPORT, and /SERVER_STUBS_FILE qualifiers. 2 Examples 1.RPCGEN /ERRLOG /TABLE PROTO.X This example generates all of the five possible files using the default file names: PROTO.H, PROTO_CLNT.C, PROTO_SVC.C, PROTO_ XDR.C, and PROTO_TBL.I. The PROTO_SVC.C code supports the use of the dispatch table found in PROTO_TBL.I. The server error messages are logged to the operator console, instead of being sent to the standard error. 2.RPCGEN /INET_SERVICE /TIMEOUT_SECONDS=20 PROTO.X This example generates four output files using the default file names: PROTO.H, PROTO_CLNT.C, PROTO_SVC.C, and PROTO_XDR.C. INETd starts the server and the server exits after 20 seconds of inactivity. 3.RPCGEN /HEADER_FILE /TABLE PROTO.X This example sends the header file (with support for dispatch tables) to the default output file PROTO.H. 4.RPCGEN /TRANSPORT=TCP PROTO.X This example sends the server skeleton file for the transport TCP to the default output file PROTO_SVC.C. 5.RPCGEN /HEADER_FILE /TABLE /OUTPUT=PROTO_TABLE.H PROTO.X This example sends the header file (with support for dispatch tables) to the output file PROTO_TABLE.H.