10 —
RPC, IDL, ACF, and IDL Compiler Enhancements
[Previous]
[Next]
[Contents]
[Index]
10.1 Overview of Enhancements
This chapter describes enhancements to RPCs, IDL, and the ACF language:
10.2 Local RPC Protocol Sequence
Gradient DCE for Tru64 UNIX now supports a new protocol sequence (protseq) in addition to TCP, UDP, DECnet, and OSI (ncacn_ip_tcp, ncadg_ip_udp, ncacn_dnet_nsp, and ncacn_osi_dna protocol sequence strings, respectively). The new protocol sequence is implemented with UNIX domain sockets and can be used only by clients and servers that are on the same node. The protocol sequence name is localrpc.
By using UNIX domain sockets, the IP layer can be bypassed, giving performance gains that vary with the nature of the RPC traffic.
This is not a "transparent" implementation that switches the user automatically to UNIX domain sockets when appropriate; rather, the user must explicitly use the localrpc protocol sequence in either a well-known endpoint in the IDL file, or as called out by one of the family of rpc_server_use_protseq*() functions (where * can be any characters) wherever a protocol sequence string can be used. String bindings can also be used to pass localrpc binding information from server to client.
10.2.1 Using localrpc with well-known endpoints
Within the IDL file, the user might have previously had an endpoint section as follows:
endpoint("ncadg_ip_udp:[2001]", "ncacn_ip_tcp:[2001]",
"ncacn_dnet_nsp:[my_app_server]", "ncacn_osi_dna:[2001]")
Now this section can be expanded to:
endpoint("localrpc:[/tmp/my_app_server]",
"ncadg_ip_udp:[2001]", "ncacn_ip_tcp:[2001]",
"ncacn_dnet_nsp:[my_app_server]", "ncacn_osi_dna:[2001]")
If the corresponding server code calls rpc_server_use_all_protseqs_if(), a UNIX domain socket is created at /tmp/my_app_server in addition to using the rest of the protseqs specified in the endpoint section. A client residing on the same node as the server can then connect to the server using this socket to gain some performance advantage.
10.2.2 Affected RPC API calls
The following RPC API calls have been affected in some way by localrpc, or in some cases significantly not affected.
rpc_server_use_protseq()
This function can now be handed "localrpc" for the protseq parameter and
a socket in the form of /tmp/LOCAL_RPC_42670001 will be dynamically
formed, where "4267" is the hex form of the server pid, and the "0001" is
a counter to ensure a unique name. The hex version of the pid is used in
cleaning up unused sockets by dced.
rpc_server_use_protseq_ep()
This function can now be handed "localrpc" for the protseq parameter and
a pathname for the endpoint. The socket is created at the given endpoint.
rpc_server_use_protseq_if()
This function can now be handed "localrpc" for the protseq parameter and
the endpoint from the interface specification will be used.
rpc_server_use_all_protseqs()
This function does not use localrpc in the list of valid protseqs. This is to
prevent breaking existing programs that randomly pick a binding and
attempt endpoint operations using it. Endpoint database operations do not
accept localrpc endpoints.
rpc_server_use_all_protseqs_if()
This function will now create a localrpc binding if it has been specified
(along with any other protseqs) in the interface specification (IDL file).
rpc_ep_register()
This function will not put any localrpc binding handles into the endpoint
database. If the entire binding vector consists only of localrpc binding
handles, then the status rpc_s_no_bindings is returned. Otherwise, localrpc
bindings are skipped over and other bindings are inserted.
rpc_ep_register_no_replace()
See rpc_ep_register() for identical restrictions.
rpc_string_binding_compose()
This routine will now accept localrpc in addition to the other protocol
sequences already supported. When composing a string binding that has
localrpc as its protocol sequence, it is only necessary to provide a NULL
for the hostname as the parameter placeholder. The hostname, hostname
IP, or "localhost" would also be acceptable.
rpc_binding_from_string_binding()
For localrpc string bindings, the hostname can be omitted. See the string
binding style in the next call, rpc_binding_to_string_binding().
rpc_binding_to_string_binding()
For localrpc bindings, the hostname is not used in the string binding
returned from this routine. Instead of localrpc:hostname:[/tmp/sockname],
it simply uses: localrpc:[/tmp/sockname]
rpc_network_inq_protseqs()
This routine does not return localrpc in the list of supported protseqs to
maintain compatibility with existing programs. Some existing programs
call this routine, pick a binding, and use only that one binding in
rpc_server_use_protseq() and rpc_ep_register() calls. The
rpc_ep_register() call with only a localrpc binding would fail.
rpc_network_is_protseq_valid()
This routine will now return true for "localrpc," as well as the previously
supported protseqs.
10.2.3 Suppressing localrpc (or any other protseq)
Particular protseqs can be suppressed from RPC's consideration by listing only the desired protseqs in the RPC_SUPPORTED_PROTSEQS environment variable, for example:
setenv RPC_SUPPORTED_PROTSEQS ncacn_ip_tcp:ncadg_ip_udp
This example effectively suppresses DECnet, OSI, and Local-RPC protocol sequences. (Note: DECnet/OSI protocols will not be used if DECnet/OSI has not been configured.)
10.2.4 Permissions of localrpc Socket
The UNIX permission used on the socket created will normally follow from the user's current umask value and the permissions of the directory where the socket is created. This can be tuned by using a "permission network option" in the endpoint. For example, if the interface specification (IDL file) contained:
endpoint("localrpc:[/tmp/my_app_server,perm=666]",
"ncadg_ip_udp:[2001]", "ncacn_ip_tcp:[2001]",
"ncacn_dnet_nsp:[my_app_server]", "ncacn_osi_dna:[2001]")
The socket permission will be set to read and write for all users regardless of the current umask value. The network option can also be used when directly calling rpc_server_use_protseq_ep().
10.2.5 Added dced Support
Any localrpc sockets created (dynamically) in the form of
/tmp/LOCAL_RPC_%4x%4d (e.g. /tmp/LOCAL_RPC_42670001)
by using the rpc_server_use_protseq() function will be garbage-collected by dced some time after the server process has gone away. The reaper thread that accomplishes this will only be activated 3 times a day to keep the additional overhead very low.
10.2.6 Compatibility Issues
Localrpc endpoints will not be inserted into the Endpoint Database so that remote clients will not waste time attempting to connect to them. (See the rpc_ep_register() and rpc_ep_register_no_replace() functions in the above API section.)
Localrpc entries in the endpoint section of the interface specification are ignored by platforms that don't support this protocol sequence.
10.3 DTSD Timing and Timeout Changes
Within RPC, the API is extended with the effect of distributing timing signals from a different source and reducing the default TCP timeout period from 2 hours to 10 minutes. Previously, dtsd listened for the DECnet time service (DECdts) synchronization messages on data link interface (DLI). Now, dtsd defaults to RPC only.
To overturn the new default value (RPC only) and return to the former way of accepting timing messages:
% dtsd -m
The dtsd command invokes the DTS daemon (server or clerk process). This command is usually executed as part of the overall DCE startup script, dcesetup.
You can enter the command manually under the following conditions:
In normal rebooting, the rc.dce script automatically provides arguments appropriate to the choice of configuration options.
If dtsd is started with no arguments (other than -d for debugging and -w for serviceability determinations), then the server must be started with dcecp. The following example configures a local server:
dcecp> dts configure -notglobal
dcecp> dts activate
DTS runs as the host machine principal, which is usually root.
Use dtsd interactively only when troubleshooting; use the /sbin/rc3.d/S66dce script to start the DTS daemon. On some systems the superuser is associated with the machine principal.
10.3.1 Affected RPC API Call
The following RPC API calls has been affected by setting the default TCP timeout from (kernel tunable) two hours to (DCE) ten minutes:
rpc_mgmt_set_com_timeout()
rpc_mgmt_set_server_com_timeout()
Previously, these functions recognized only two timeout values for TCP connections. The two values were 0 or 10: rpc_c_binding_min_timeout(0) or rpc_c-binding_infinite_timeout(10). Those same calls recognized all integer values from 0 to 10 for UDP connections, however.
Currently, all values from 0 to 10 affect the timeout properties of each call without regard for the protocol selected. A value of 10 corresponds to two hours with each lower integer corresponding to a smaller period.
10.4 Using Environment Variables to Restrict Network Interfaces and Addresses
This section describes two environment variables that are useful controls for cluster environments and for systems with more than one network interface:
Remove the device named "te1" from RPC consideration.
% setenv RPC_UNSUPPORTED_NETIFS te1:te2
Remove the two devices named "te1"and "te2" from RPC consideration.
NOTE:
To list more than one device, use a colon-separated list.
% setenv RPC_SUPPORTED_NETADDRS 16.20.16.144
Of all network addresses that are available, use only 16.20.16.144.
% setenv RPC_SUPPORTED_NETADDRS 16.20.16.144:16.20.40.139
Use two of the available addresses, "16.20.16.144"and "16.20.40.139".
NOTE:
To list more than one network address, use a colon-separated list.
10.5 IDL and ACF Enhancements
This section describes the following enhancements to IDL and the ACF language:
10.5.1 Automatic Binding Enhancement
When a client uses the automatic binding method, DCE must use the name service to obtain binding information. However, the client host must have a starting entry from which to begin the namespace search. If the RPC_DEFAULT_ENTRY environment variable is defined on the client host, DCE uses the entry in that variable to obtain binding information. If RPC_DEFAULT_ENTRY is not defined, DCE looks for binding information from the host's name service profile.
10.5.2 Enumeration in IDL
An IDL enumeration provides names for integers. It is specified as follows:
enum {identifier[= integer], ...}
Each identifier in an enumeration is assigned an integer, either explicitly in the interface or automatically by the IDL compiler. If all the identifiers are unassigned, the IDL compiler begins assigning 0 (zero) to the first identifier, 1 to the next identifier, and so on. If an unassigned identifier follows an assigned one, the compiler restarts number assignment with the next consecutive integer. An enumeration can have up to 32,767 identifiers.
Assignments can be made in any order, and multiple identifiers can have the same value. For example:
typedef enum {
SHOVEL = 9, AX, MATTOCK = 3, PITCHFORK, SPADE = 9
} yard_tools;
/* values assigned: SHOVEL:9, AX:10, MATTOCK:3, PITCHFORK:4, SPADE:9 */
10.5.3 The client_memory ACF Attribute
While marshaling parameters, the client stub uses built-in routines to manage memory. You can use the client_memory attribute to specify different memory allocation and free routines. The client_memory attribute has the following syntax in the ACF header:
[client_memory(malloc_routine, free_routine)] interface idl_interface_name
The routines you specify must have the same respective procedure declarations as the system's malloc( ) and free( ) routines.
Applications need to manage memory consistently, so if your application needs to do other memory allocation, be sure to use the same routines you specified with the client_memory attribute.
You can use the client_memory attribute in conjunction with RPC stub support API routines such as rpc_sm_set_client_alloc_free( ) and rpc_sm_swap_client_alloc_free( ).
10.6 IDL Compiler Enhancements
This section describes the following enhancements to the IDL compiler supported by Gradient DCE for Tru64 UNIX:
10.6.1 The -standard Build Option
The -standard_type IDL compiler command option allows you to specify portable or extended features of the OSF DCE.
The standard_type argument specifies which IDL features to enable. If you do not specify this argument, the compiler generates warning messages for all features that are not available in the previous version of OSF DCE.
You can specify one of the following values for the standard_type argument:
The command line in the following example compiles the IDL interface test.idl and enables extended features of the OSF DCE:
% idl test.idl -standard extended
10.6.2 Stub Auxiliary Files
By default, the OSF DCE IDL compiler at V1.0.3 or later does not generate the -caux and -saux files that V1.0.2 does. However, if you want to use build procedures that work with the V1.0.2 IDL compiler, you can direct the V1.0.3 (or later) IDL compiler to generate empty auxiliary files. To do this, define the environment variable IDL_GEN_AUX_FILES as follows:
% setenv IDL_GEN_AUX_FILES "1"
10.6.3 Generating Application Templates Using the IDL Compiler
The IDL compiler can use your interface definition file to generate a C language template that you can modify to create executable client and server applications. The template feature simplifies the implementation of distributed applications by generating a module of templates for many of the routines that must be provided by the application programmer.
A template is a generated RPC routine that includes the function header and an empty function body. You fill in the function body with application-specific information and integrate the module into your application. By using templates, you can concentrate on the functional aspects of your application program instead of the mechanical process of writing function definitions that match the corresponding IDL definitions.
The template feature is designed to support applications written in the C programming language, and it supports all functions defined in IDL. The template feature does not generate completely executable client and server applications.
To use the IDL compiler to create a template of the manager routines in the server side of your distributed application, specify the template_manager option when you compile the application interface module(filename.idl) with IDL. You can generate a template module containing the client-side routines for your distributed application by specifying the template_client option to the IDL compiler.
The template_manager compiler option generates a module that contains templates for the routines required in the manager portion of a server application. The template_client compiler option generates a module that contains templates for some of the routines used to create the client side of an application. The following IDL compiler command options control generation of template modules.
The next table lists every IDL construct that can be defined in a template module. The table indicates whether each construct is specific to a client template, a manager template, or both. If your client application does not use any of the IDL constructs (in the next table) that support client modules, then you will not benefit from using the template feature.
Note that remote procedure implementations are defined as all functions defined in IDL for the C programming language.
The template feature is for use during application development, when you might generate template modules repeatedly as you add new functions to an interface. However, after you create and modify the first template module, you should specify a temporary filename for subsequent template modules. Otherwise, you will overwrite the existing modified template module. After creating a new template module in a temporary file, use a text editor to move the new template module into the existing application file which includes the modified templates.
10.6.4 Example of IDL Template Feature
The following sections illustrate how to use the IDL template feature with the test2 example program included with your DCE software kit. (See Chapter 13 for more information on programs in this software kit.) The following files are discussed:
10.6.4.1 Example Interface Definition File
This section shows the test2.idl interface definition source code.
/*
** COPYRIGHT (C) 1993 BY
** DIGITAL EQUIPMENT CORPORATION, MAYNARD
** MASSACHUSETTS. ALL RIGHTS RESERVED.
**
** THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE
** USED AND COPIED ONLY IN ACCORDANCE WITH THE TERMS OF
** SUCH LICENSE AND WITH THE INCLUSION OF THE ABOVE COPYRIGHT NOTICE.
** THIS SOFTWARE OR ANY OTHER COPIES THEREOF MAY NOT BE PROVIDED
** OR OTHERWISE MADE AVAILABLE TO ANY OTHER PERSON. NO TITLE
** TO AND OWNERSHIP OF THE SOFTWARE IS HEREBY TRANSFERRED.
**
** THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE
** WITHOUT NOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT
** BY DIGITAL EQUIPMENT CORPORATION.
**
** DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF ITS
** SOFTWARE ON EQUIPMENT THAT IS NOT SUPPLIED BY DIGITAL.
**
**
** NAME
**
** test2.idl
**
** FACILITY:
**
** RPC Test Program #2
**
** ABSTRACT:
**
** Definitions of types/constants and procedures that make up the
** remote interface to the RPC Test Program #2.
**
*/
[
uuid(eef82780-53bb-11c9-94e0-08002b13d56d),
version(0)
]
interface test2
{
[idempotent] void test2_add
(
[in] long a,
[in] long b,
[out] long *c
);
}
10.6.4.2 Example Manager Template
The following IDL command creates a manager template for the server side of the test2 application interface. The IDL file for the server side of the application is shown in Section 10.6.4.1 on page 113.
% idl test2.idl -template_manager test2_mgr.c
As a result of this command, the compiler generates the test2_mgr.c source code template for the test2.idl interface definition, shown next. The template begins with comment lines that indicate the version of the IDL compiler that generated the template and the name of the IDL interface for which the template was generated. These comment lines are followed by an include statement for the interface header file and the template routines.
The generated template modules provide the function definition under conditional compilation in both the ANSI-C form and in the older form of the C language. The template module contains both forms of IDL functions so you can use the generated templates on systems on which the C compiler does not yet support the ANSI-C standard.
The following is the test2_mgr.c source code template generated by IDL.
/* Generated by IDL compiler version DEC DCE T1.0.3-A6 */
/*
** Support routines and Remote Procedure Implementations for interface test2
*/
#include "test2.h"
/*
** Implementation of Remote Procedures for test2
*/
void test2_add
#ifdef IDL_PROTOTYPES
(
/* [in] */ idl_long_int a,
/* [in] */ idl_long_int b,
/*
[out] */ idl_long_int *c
)
#else
(a, b, c)
#endif
#ifndef IDL_PROTOTYPES
idl_long_int a;
idl_long_int b;
idl_long_int *c;
#endif
{
}
10.6.4.3 Creating the Executable Manager Program
From the manager template module, you can create the complete, executable server by including the application-specific implementation of the manager routine, as follows:
{
*c = a + b;
}
10.6.5 C++ Application Support
The idl compiler has several options that support the use of C++ language syntax features. The options -lang and -no_cxxmgr are described in the Gradient DCE for Tru64 UNIX Reference Guide.
[Previous]
[Next]
[Contents]
[Index]
To make comments or ask for help, contact
support@entegrity.com.
Copyright © 2001 Entegrity Solutions Corporation & its subsidiaries.
Copyright © 1998-2001 Compaq Computer Corporation.
All rights reserved.