Document revision date: 5 July 2000

For LDAP:

1. Answer "Yes" to the configuration question "Do you want to register the DCE cell in LDAP".
2. Execute an intercell command similar to the following command to show the root of the new cell and to see if everything works:

   cdscp> show cell /.../c=us/o=compaq/ou=rubycell

   
   Enter the preceding command from an unauthenticated, nonprivileged account.

3. Run dce_login , and log in as cell_admin .
4. Run rgy_edit , and execute a cell command similar to the following:

   rgy_edit> cell /.../c=us/o=compaq/ou=lasercell Enter group name of the local account for the foreign cell: none Enter group name of the foreign account for the local cell: none Enter org name of the local account for the foreign cell: none Enter org name of the foreign account for the local cell: none Enter your password: Enter account id to log into foreign cell with: cell_admin Enter password for foreign account: Enter expiration date [yy/mm/dd or 'none']: (none) none

The Browser is a Motif-based tool for viewing the CDS namespace. The Browser can display an overall directory structure as well as show the contents of directories, enabling you to monitor growth in the size and number of directories in your namespace. You can customize the Browser so that it displays only a specific class of object names. The Compaq DCE Enhanced Browser contains some additional functions beyond those documented in the OSF DCE documentation.

10.1 Displaying the Namespace

When you start the Browser, an icon representing the root directory is the first item to appear in the window. Directories, soft links, and object entries all have distinct icons associated with them. Most object entries have unique icons based on their class; the class indicates the type of resource that the entry represents (for example, clearinghouse object entries). When the Browser does not recognize the class of an entry, it displays a generic icon. Figure 10-1 shows the Enhanced Browser icons and what they represent.

Figure 10-1 Enhanced Browser Icons

Using the Filters menu, you can selectively display object entries of a particular class. With the Enhanced Browser, you can choose from either the RPC_Class or CDS_Clearinghouse object classes. For example, if you are interested in seeing the entries for clearinghouse objects only, choose the class CDS_Clearinghouse from the Filters menu. If you are interested in seeing object entries used in the name service interface (NSI), choose RPC_Class. You can filter only one object class at a time.

Setting a filter does not affect the current display, but when you next expand a directory, you see only object entries whose class matches the filter. Note that soft links and directories still appear because only object entries can be filtered out. To reset the filter to view all object entries, choose the asterisk(*) from the Filters menu.

For a full description of the Browser, see the CDS section in the OSF DCE Administration Guide --- Core Components.

This chapter and the next two chapters describe enhancements to the IDL compiler supported by Compaq DCE for OpenVMS VAX and OpenVMS Alpha.

This chapter describes the following enhancements:

• The -standard application build options
• Treatment of stub auxiliary files
• Use of Compaq Language-Sensitive Editor (LSE) Templates
• The binding handle callout feature

The -standard IDL compiler command option allows you to specify portable or extended features of the OSF DCE.

The standard_type argument specifies what 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:

portable	Allows only the language features available in OSF DCE Version 1.0.2.
dce_v10, dce_v103, dec_v1.0	Synonymous with the portable argument.
dec_v13, dce_v11	Allows all language features supported by the -standard dce_v10 argument, plus a set of Compaq extensions to its products based on OSF DCE Version 1.0.3.
extended	Allows all language features supported in the current version of the compiler. This is the default.
dce_v20	Synonymous with the extended argument.

The following example command line compiles the IDL interface test.idl and enables extended features of the OSF DCE:

% idl test.idl -standard extended

11.2 Stub Auxiliary Files

By default, the OpenVMS DCE IDL compiler does not generate stub auxiliary (AUX) files.

For applications that use certain data types or certain features of RPC, the current OSF DCE IDL compiler generates stub auxiliary files that contain support routines that are called by the stubs. The Compaq DCE implementation of the IDL compiler does not need those support routines, and, by default, does not generate stub auxiliary files.

However, if you are porting an RPC application from a platform on which the IDL compiler generates stub auxiliary files, and you do not want to modify your build procedures, you can set the IDL compiler to generate stub auxiliary files. To tell the IDL compiler to generate empty auxiliary files, define the symbol IDL_GEN_AUX_FILES with the following command:

$ IDL_GEN_AUX_FILES:== 1

11.3 Compaq Language-Sensitive Editor (LSE) Templates on OpenVMS

The IDL compiler supports the use of Compaq Language-Sensitive Editor (LSE) templates on OpenVMS to help you develop your interfaces more efficiently. LSE is a multilanguage, advanced text editor that enhances program development.

LSE provides the following features:

• Error Correction and Review
  This feature allows you to compile, review, and correct compilation errors within a single editing session. LSE provides an interface to the IDL compiler so that you can perform compilations without leaving LSE. The compiler provides LSE with compilation diagnostics in a way that allows you to review compilation errors in one editing window while displaying the related source in another window.
• Language-Specific Templates
  LSE accesses a collection of formatted language constructs, called templates, that provides keywords, punctuation, and placeholders for IDL.

While writing your program, you can use the COMPILE and REVIEW commands to compile your code and review compilation errors without leaving the editing session. The IDL compiler generates a file of compile-time diagnostic information that LSE uses to review compilation errors.

The LSE COMPILE command issues the appropriate command in a subprocess to invoke the IDL compiler and appends the /DIAGNOSTIC qualifier to the compile command.

The LSE REVIEW command displays any diagnostic messages that result from a compilation. LSE displays the compilation errors in one window, with the corresponding source code displayed in a second window. This multiwindow capability allows you to review your errors while examining the associated source code. This eliminates tedious steps in the error-correction process and helps ensure that you fix all errors before running the compilation process again.

See the LSE documentation for complete information on using LSE.

11.4 Binding Handle Callout

The binding handle callout feature lets you specify a routine that is automatically called from an IDL-generated client stub routine, in order to modify the binding handle.

You can typically use this feature to augment the binding handle with security context, for example, so that authenticated RPC calls are used between client and server.

This feature is particularly targeted at clients that use automatic binding via the auto_handle ACF attribute. For automatic binding, it is the client stub rather than the client application code that obtains a server binding handle. The binding handle q~callout feature lets you modify binding handles obtained by the client stub. Without this feature, you cannot modify the binding handles before the client stub attempts to initiate a remote procedure call to the selected server.

11.4.1 Attribute Configuration File

To select the binding handle callout feature, create an attribute configuration file (ACF) for the interface (if necessary) and place the binding_callout attribute on the interface. An example follows:

[auto_handle, binding_callout(my_bh_callout)] interface bindcall { }

The binding_callout attribute has the following general form:

[binding_callout(<IDENTIFIER> )]

You can specify the binding_callout attribute only once per interface; it applies to all operations in that interface.

11.4.2 Generated Header File

The IDL-generated header file for the interface contains a function prototype for the binding callout routine. In the previous example, bindcall.h contains a declaration similar to the following declaration:

void my_bh_callout( rpc_binding_handle_t *p_binding, rpc_if_handle_t interface_handle, error_status_t *p_st );

11.4.3 Generated Client Stub

Each client stub routine in the IDL-generated client stub module calls the binding callout routine just before initiating the remote procedure call to the server. In the previous example, each client stub routine contains a call to my_bh_callout and passes the three arguments that are described in the following section.

11.4.4 Binding Callout Routine

The arguments to the binding callout routine are:

Input/Output:

rpc_binding_handle_t *p_binding

A pointer to a server binding handle for the remote procedure call. Generally, the binding callout routine augments this binding handle with additional context, such as for security.

Input:

rpc_if_handle_t interface_handle

The interface handle used to resolve a partial binding or for the binding callout routine to distinguish interfaces.

Output:

error_status_t *p_st

An error status code returned by the binding callout routine.

11.4.4.1 Error Handling

A binding callout routine returns error_status_ok when it successfully modifies the binding handle or decides that no action is necessary. This causes the client stub to initiate the remote procedure call.

When the binding callout routine returns an error status, the client stub does not initiate a remote procedure call. If auto_handle is being used, the client stub will attempt to locate another server of the interface and once again call the binding callout routine. Otherwise, the client stub executes its normal error handling logic.

A binding callout routine for a client using auto_handle can return rpc_s_no_more_bindings to prevent the client stub from trying to locate another server. The client stub will then execute its normal error handling logic.

By default, a client stub handles an error condition by raising an exception. If a binding callout routine returns an rpc_s_ status code, the client stub raises the matching rpc_x_ exception. If a binding callout routine returns any other error status, it is usually raised as an unknown status exception.

For an operation containing a comm_status parameter, the client stub handles an error condition by returning the error status value in the comm_status parameter. A binding callout routine can return any error status value to the client application code if the IDL operations are specified with comm_status parameters.

A binding callout routine can raise a user-defined exception rather than return a status code if it prefers to report application-specific error conditions back to the client application code via exceptions.

11.4.5 Predefined Binding Callout Routine

There is one predefined binding callout routine in the DCE library that may be suitable for some applications. To select this routine, specify a binding_callout(rpc_ss_bind_authn_client) ACF attribute.

rpc_ss_bind_authn_client matches the function prototype in the previous section, Generated Header File. It authenticates the client identity to the server, thereby allowing for one-way authentication. In other words, the client does not care which server principal receives the remote procedure call request, but the server verifies that the client is who the client claims to be.

rpc_ss_bind_authn_client does the following:

• Calls rpc_ep_resolve_binding() to resolve the binding handle if it is not fully bound (for example, for auto_handle ).
• Calls rpc_mgmt_inq_server_princ_name() to obtain the server identity (principal name).
• Calls rpc_binding_set_auth_info() with all default values except the server principal name obtained in the previous call.
• If any of these calls returns an error status, places the error status in the *p_st argument and rpc_ss_bind_authn_client returns.

The Remote Procedure Call (RPC) Interface Definition Language (IDL) compiler in Compaq DCE for OpenVMS VAX and OpenVMS Alpha includes enhanced application debugging support beyond the support provided with OSF DCE. The OpenVMS IDL compiler includes the RPC Event Logger, a software utility that records information about operations relating to the execution of an application. Operational information about the program state at a specific point during processing, called an event, is recorded in a file, called an event log. You have the option of directing event logging information to the terminal screen, rather than to a file. In this chapter, the terms event log and log are used interchangeably to refer to the stream of logging output captured in the event log file or displayed on the screen.

Event logging provides a detailed, low-level view of the execution of your RPC application. If development of your RPC application is proceeding well, this level of detail may not be necessary. However, when you are in the debugging phase of application development, the continuous execution information provided by the Event Logger and the ability to change the type and timing of logging can be valuable.

12.1 Introduction to the RPC Event Logging Facility

When event logging is enabled, the Event Logger creates one log for each client and server process. To enable the RPC Event Logger, you specify an IDL compiler option that traces events (described in Section 12.2.1).

Enabling event logging when compiling allows you the option of generating logs at runtime without rebuilding the application. Once logging is enabled, you can use OpenVMS symbols and the RPC Log Manager ( rpclm ) to control logging operations. The Log Manager provides a command interface for changing logging operations during application execution.

The RPC Event Logger records events about application calls, context handles, errors, miscellaneous events, and logging operations. These are called event types. Typical RPC events include the following:

• call_start --- A client application made a call to a server.
• call_failure --- A client stub terminated abnormally either through an exception or failing status.
• exception --- An exception was detected in the server stub, and the exception caused the call to terminate.
• context_rundown --- A context handle on a server was freed by the context rundown procedure.

For application calls, the Event Logger generates events that signal call activation, the call start and end, attempts to rebind to a server, and termination of a server thread.

For context handles, the Event Logger generates events that signal context handle creation and deletion by the client and server, and context handle modification, removal, and rundown.

For errors, the Event Logger generates events that signal call and receive failure from the client, exceptions, server failure, and call transmission failure from the server.

The miscellaneous events provide information about the application manager routine, and input and output argument processing events.

The logging operation itself generates events that display the logging output device, and that signal modification of logging parameters, and event log start and stop.

As a result of using the -trace option in the IDL compile command, idl , RPC events are generated by code in the client and server stub modules created by the compiler. Note that some events are generated at selected points in the RPC runtime library. For this reason, certain events, such as those relating to the logging operation, are always generated into the application code in addition to the event types you specify.

The events generated in each of these areas are shown in detail in Section 12.6.

In the event log, each event is described on a single line divided into five fields. The five fields are defined in Table 12-1.

Table 12-1 Event Log Fields

Field	Field Description
Event Time	The system clock at the time of the event. Events are listed chronologically in the log.
Thread Identity	The hostname, process ID, and thread ID.
Operation Name	The interface and operation name (if available).
Event Name	Name of the event.
Event Data	Data related to the event. This field contains either specific information about logging operations or a string binding that uniquely identifies the client process, server process, or Log Manager process.

The following is an example of an event log generated for an RPC client. The log contains five columns. To improve readability, columns four and five are shown below the first three columns. In addition, the field names have been added to identify the events; the names do not appear in an actual event log. (In subsequent event log examples, the field names are occasionally used instead of actual data to improve readability where necessary.)

EVENT TIME THREAD IDENTITY OPERATION NAME 1999-02-07:11:48:18.31.160-5:00I0.121 ifdef:8710/1 binopwk.binopwk_add 1999-02-07:11:48:18.32.170-5:00I0.121 ifdef:8710/1 binopwk.binopwk_add 1999-02-07:11:48:18.65.180-5:00I0.121 ifdef:8710/1 binopwk.binopwk_add

EVENT NAME EVENT DATA log_start all call_start ncacn_ip_tcp:16.31.48.109[1821] call_end

This small event log indicates that the following events occurred:

1. The log_start event indicates that logging started on February 7, 1999, at 11:48 a.m. on the host named ifdef , in process number 8710, and in thread number 1. Event logging was enabled when the binopwk interface was compiled with the IDL -trace option. The RPC call to the binopwk_add operation in the binopwk interface caused logging to begin and is the first event logged. The Event Data field indicates that all events are being logged.
2. The call_start event indicates an attempt to execute a call to a server. The string binding in the Event Data field shows that the call was made over the TCP/IP transport to host 16.31.48.109 with endpoint 1821. This string binding identifies the server being contacted.
3. The call_end event indicates that the RPC call is completed, and control has returned to the caller of binopwk_add .

This log indicates that the RPC call to the binopwk_add interface was successful because no error events occurred.

	privacy and legal statement
6532_DCE_PG_PRO_006.HTML