OpenVMS Connectivity Developer Guide


Previous Contents Index

Using this item code, you can group multiple requests into a single call to the $REGISTRY service. If you use this multiple-request feature, use the REG$_SEPARATOR item code to indicate the end of the set of item codes for the current request and that there is another request to process.

REG$_SUBKEYINDEX

The REG$_SUBKEYINDEX item code is an input item code. It is a longword that specifies the index of the subkey to retrieve.

REG$_SUBKEYNAME

The REG$_SUBKEYNAME item code is an input item code. It is a string of Unicode characters that specifies the name of a subkey. A Unicode character is 4 bytes long.

REG$_SUBKEYNAMEMAX

The REG$_SUBKEYNAMEMAX item code is an output item code. It is a longword that receives the length (in characters) of a specified key's longest subkey name.

REG$_SUBKEYSNUMBER

The REG$_SUBKEYSNUMBER item code is an output item code. It is a longword that receives the number of subkeys contained in a specified key.

REG$_VALUEINDEX

The REG$_VALUEINDEX item code is an input item code. It is a longword that specifies the index of the value to retrieve within a specified key. Note that the value index starts at zero and can be any value up to one less than the count returned by REG$_VALUENUMBER .

REG$_VALUEDATA

The REG$_VALUEDATA item code is, depending on the function code, either an input or output item code. It is a buffer that contains either the value data component to write to the OpenVMS Registry (input), or it receives a data value component from the OpenVMS Registry (output).

REG$_VALUEDATAMAX

The REG$_VALUEDATAMAX item code is an output item code. It is a longword that receives the length (in bytes) of the specified key's longest data component value.

REG$_VALUENAME

The REG$_VALUENAME item code is, depending on the function code, either an input or an output item code. It is a string of Unicode characters that specifies the name of a value.

REG$_VALUENAMEMAX

The REG$_VALUENAMEMAX item code is an output item code. It is a longword that receives the length (in characters) of a specified key's longest value name.

REG$_VALUENUMBER

The REG$_VALUENUMBER item code is an output item code. It is a longword that receives the number of values contained in a specified key.

REG$_VOLATILE

The REG$_VOLATILE item code identifies the volatility of an item. As an output, it returns the volatility of the object. On OpenVMS, volatile keys and values are lost when all nodes running an OpenVMS Registry server are rebooted. (In a standalone system, volatile keys and values are lost when the system reboots.)
Volatile Type Description
REG$K_CLUSTER The item is removed when the cluster reboots.
REG$K_NONE The item is not volatile (default).
Function Modifiers You can optionally specify the high-order bits of a function code value with function modifiers. These individual bits can alter the operation of the function.

For example, you can specify the function modifier REG$M_CASE_SENSITIVE with the function REG$FC_CREATE_KEY . When you use the function and function modifier together, the data passed to the OpenVMS Registry is treated as case sensitive. The two values are written in DEC C as REG$M_CASE_SENSITIVE | REG$FC_CREATE_KEY .

The OpenVMS Registry function modifiers are defined in the header file REGDEF.H .

REG$M_CASE_SENSITIVE

Use case-sensitive matching for keys and values.

REG$M_DISABLE_WILDCARDS

Treat wildcard characters as normal characters for this function.

REG$M_IGNORE_LINKS

Force the operation to not follow any symbolic links associated with a key or a value.

By default, if a key or value is symbolically linked to another key or value, the system follows all links so that the operation specified by the function code is performed on the linked key or value.

When you specify the REG$M_IGNORE_LINKS function modifier, the operation specified by the function code affects only the specified key or value, not the linked key or value.

By default, if a key or value has a symbolic link, it can not be deleted. If you specify the REG$M_IGNORE_LINKS function modifier, the system deletes the key or value.

REG$M_NOW

Write to disk immediately, regardless of the REG$_CACHEACTION item code value.


Part 3
OpenVMS Events

This part contains reference information about OpenVMS Events.


Chapter 14
OpenVMS Events

14.1 What are Events?

On a Windows NT system, an event is any significant occurrence in the system or an application---for example, a service starting or stopping, a user logging on or off, or accessing resources. When the system encounters an event, the Event Log service writes the event (or audit entry) in the form of a record that contains date and time, source, category, event number, user, and computer information to a system, security, or application log, creating an audit trail. On Windows NT systems, you display these logs and their recorded events using the Event Viewer.

With COM Version 1.0 for OpenVMS, OpenVMS wrote all COM for OpenVMS events to the DCOM$EVENTLOG.RPT text file. With COM Version 1.1-B for OpenVMS, OpenVMS supports both Windows NT logging and Advanced Server for OpenVMS logging of COM for OpenVMS events. You can now log a COM for OpenVMS event (such as the starting of a COM server on OpenVMS), and review these OpenVMS events from a Windows NT system or an OpenVMS system.

For a detailed review of OpenVMS Events dependencies and a description of how OpenVMS Events interacts with other parts of the OpenVMS infrastructure, see Section 4.8.

14.1.1 Suggested Reading

The following sources can provide you with more information on Events and related topics:

14.2 Overview of OpenVMS Events

The system logs OpenVMS Events to a Windows NT event log, to the Advanced Server for OpenVMS event log, and to a log file on the OpenVMS system.

You can use the following techniques to view OpenVMS Events:

14.2.1 Viewing OpenVMS Events Using Windows NT Event Viewer

Use the following procedure to view OpenVMS Events through the Windows NT event viewer:

  1. Start the Windows NT event viewer.
    From the Start menu, select Programs, Administrative Tools, Event Viewer.
  2. From the Event Viewer window, click the menu bar Log option. Click Select Computer...., and select the OpenVMS system from the list box.
  3. From the Event Viewer window, click the menu bar Log option. Click System to display the System event log. The System event log contains the COM for OpenVMS events.
    To display COM for OpenVMS events only, use the following procedure:

14.2.2 Viewing OpenVMS Events Using Advanced Server for OpenVMS Event Viewer

Use the following procedure to view the COM for OpenVMS events:

  1. Ensure that the Advanced Server for OpenVMS is running.
  2. Enter the following Advanced Server for OpenVMS ADMINISTRATOR command:


      $ ADMIN SHOW EVENTS/TYPE=SYSTEM/SOURCE=DCOM/FULL 
    

    The viewer displays COM for OpenVMS events only, along with any additional information associated with the COM for OpenVMS event.

14.2.3 Event Logging on OpenVMS Only

In some cases, you might want to write and view COM for OpenVMS events only on an OpenVMS system. In place of the Windows NT log, Compaq has included an alternate event logger that writes COM event information to an OpenVMS file. You can find this file in the following location:


SYS$MANAGER:DCOM$EVENTLOG.RPT 

COM for OpenVMS creates this event logging report automatically when the COM server ( DCOM$RPCSS ) encounters an error. The event logger appends new events at the bottom (end) of the file. A logged event has the following format:


event type : ddd mmm dd hh:mm:ss yyyy
First event message
 
event type : ddd mmm dd hh:mm:ss yyyy
Second event message
. 
. 
. 

Example 14-1 shows the contents of an event log.

Example 14-1 Sample OpenVMS Event Log

$ Type SYS$MANAGER:DCOM$EVENTLOG.RPT 
 
(1)
ERROR : Tue Sep 15 11:18:54 1998 
Unable to start a DCOM Server: {5E9DDEC7-5767-11CF-BEAB-00AA006C3606} 
Runas (null)/SMITH 
The Windows NT error: 1326 
Happened while starting: device:[account]SSERVER.EXE 
 
(2)
ERROR : Tue Sep 15 19:14:45 1998 
The server {0C092C21-882C-11CF-A6BB-0080C7B2D682} did not register 
with DCOM within the required timeout. 
 

  1. The system logged the first error event on Tue Sep 15 11:18:54 1998. The COM server (DCOM$RPCSS) was unable to start the COM application device:[account]SSERVER.EXE on behalf of the client running under the SMITH account. (The client may have received an error such as "access denied.") The resulting Windows NT error was 1326 , which translates as "Logon failure: unknown user name or bad password."
    If you see this error, check the validity of the user account using the OpenVMS Authorize utility (AUTHORIZE).
  2. The system logged the second error event on Tue Sep 15 19:14:45 1998. The COM server (DCOM$RPCSS) was able to start the COM application {0C092C21-882C-11CF-A6BB-0080C7B2D682} , but the application did not run successfully. The application failed to register with DCOM$RPCSS within the specified time limit. (The client may have received an error such as "Server execution failed" CO_E_SERVER_EXEC_FAILURE. )
    If you see this error, run the server application interactively to determine its integrity.

NTA$EVENTW

Allows an application to record information in the event log files.

The NTA$EVENTW routine completes all operations synchronously.


Format

NTA$EVENTW [nullarg], func, itmlst, evsb


Arguments

nullarg


OpenVMS usage: reserved
type: longword (unsigned)
access: read only
mechanism: by value

Reserved for Compaq use.

func


OpenVMS usage: function_code
type: longword (unsigned)
access: read only
mechanism: by value

Function code specifying the function NTA$EVENTW is to perform. The func argument is a longword containing this function code. The $EVENTDEF macro defines the names of each function code.

itmlst


OpenVMS usage: address of item list
type: 64-bit address
access: read only
mechanism: by value

Item list specifying information about the event source or the event. The itmlst argument is the 64-bit address of a list of item descriptors, each of which describes an item of information. An item list in 64-bit format is terminated by a quadword of 0.

The following diagram shows the 64-bit format of a single item descriptor.


evsb


OpenVMS usage: address of status block
type: 64-bit address
access: write only
mechanism: by reference

Event status block to contain the completion status for the requested operation.

NTA$EVENTW sets the status block to 0 upon request initiation. Upon request completion, the EVT$L_VMS_STATUS field contains the primary (OpenVMS) completion status for the operation.

If an error occurs, EVT$L_NT_STATUS (if non-zero) is the secondary error status to further define the error condition. Function Codes

EVT$_FC_REGISTER_EVENT_SOURCE

Open an association with an event log.
Item code Required Parameter Data type
EVT$_SERVER_NAME No Input String (4-byte Unicode)
EVT$_SOURCE No Input String (4-byte Unicode)
EVT$_HANDLE Yes Output Unsigned longword

EVT$_FC_REPORT_EVENT

Generate an event log entry.
Item code Required Parameter Data type
EVT$_HANDLE Yes Input Unsigned longword
EVT$_EVENT_TYPE Yes Input Word mask
EVT$_EVENT_CATEGORY No Input Word
EVT$_EVENT_ID Yes Input Longword
EVT$_USER_SID No Input NT Security ID
EVT$_NUMSTRINGS No Input Word
EVT$_DATASIZE No Input Longword
EVT$_STRING_ARRAY No Input Array of varying-length descriptors. (4-byte Unicode)
EVT$_RAW_DATA No Input Binary data

EVT$_DEREGISTER_EVENT_SOURCE

Close an association with an event log.
Item code Required Parameter Data type
EVT$_HANDLE Yes Input Unsigned longword
Item Codes
Item Code Parameter Type Data Type
EVT$_SERVER_NAME Input String
EVT$_SOURCE Input String
EVT$_HANDLE Input/Output Unsigned longword
EVT$_EVENT_TYPE Input Word mask
EVT$_EVENT_CATEGORY Input Word
EVT$_EVENT_ID Input Longword
EVT$_USER_SID Input NT security ID
EVT$_NUMSTRINGS Input Word
EVT$_DATASIZE Input Longword
EVT$_STRING_ARRAY Input Array of string pointers
EVT$_RAW_DATA Input Binary data
Description The NTA$EVENTW routine allows you to register and deregister an event source and report event data. This event logging allows you to record information from within an application. You can use the events routines to track progress within an application or identify problems encountered by an application.

The NTA$EVENTW routine completes synchronously; that is, control is returned to the caller only after the request completes.

Use the following process to write event data:

  1. Register the event source.
    This operation defines the event log to which the system writes event data.
  2. Report the event.
    This operation causes the system to write the information to the appropriate event log.
  3. Deregister the event source.
    This operation frees resources acquired as part of the event source registration operation.

Condition Values Returned

SS$_NORMAL Service completed successfully.
SS$_ACCVIO One of the arguments cannot be read/written.
SS$_BADPARAM Bad parameter.
SS$_NOPRIV Insufficient privilege to access the specified event log.
SS$_TIMEOUT Request timed out.
SS$_UNREACHABLE Events service unavailable.
SS$_REJECT The Windows NT LAN Manager server encountered an error. See the Win32 status for more information.

14.3 Writing Your Own Events

By default, the system logs DCOM events generated by COM for OpenVMS. In addition to recording COM for OpenVMS events, the system can also log COM application events for COM applications that you create.

The COM for OpenVMS kit includes sample code that shows how to generate an application event using Win32 APIs. You can use this example as is on a Windows NT system. The example also builds correctly using the instructions for building COM for OpenVMS applications on OpenVMS (to get the required header files from DCOM$LIBRARY). See Chapter 7 for these instructions. The example also includes the linking instructions to build the example using Wind/U.

14.4 Troubleshooting OpenVMS Events

Errors that occur during event reporting can be difficult to trace because of the number of intervening software layers through which the event passes. The following list describes how OpenVMS Events pass through other software layers until they are recorded in the Windows NT log.

  1. An application calls one of the Win32 event functions ( RegisterEventSource , ReportEvent , or DeregisterEventSource ).
  2. Using the supplied arguments, the Win32 API builds an appropriate item list and calls the NTA$EVENTW routine.
  3. The NTA$EVENTW routine validates the information supplied (function code, item list, and so on) and builds an appropriate item list for the SYS$ACM system service.
    If NTA$EVENT detects any errors NTA$EVENT returns the errors to the Win32 API using R0 and the event status block.
  4. The SYS$ACM system service validates the information and passes it to the NT ACME.
    If SYS$ACM detects any errors, SYS$ACM returns the errors to NTA$EVENTW using R0 and the ACM status block..
  5. The NT ACME passes the supplied information (using an IPC pipe) to a dispatcher in the Advanced Server for OpenVMS.
    If the NT ACME detects any errors, the NT ACME returns the errors to the caller using the ACM status block.
  6. The Advanced Server for OpenVMS dispatcher validates the information and calls the appropriate routines to perform the requested operation (register, report, or deregister).
    If the Advanced Server for OpenVMS detects any errors, it reports the errors to the NT ACME. The NT ACME passes the errors back to the other callers.

Checking the contents of the event status block help you determine where the failure might have happened. Table 14-1 lists (in order of importance) the checks you should perform.

Table 14-1 Troubleshooting OpenVMS Events Failures
R0 Status Status Field Value Component to Check
Failure (bit 0 clear) EVT$L_NT_STATUS field is nonzero. Error most likely occurred within Advanced Server for OpenVMS.
Failure EVT$L_VMS_STATUS field is nonzero and the EVT$L_NT_STATUS is zero. Error most likely occurred within the SYS$ACM system service or the NT ACME.
Failure EVT$L_VMS_STATUS is zero and EVT$L_NT_STATUS is zero. Error most likely occurred within the SYS$ACM system service.

Note

The Win32 API usually converts the error status to an appropriate NT error status code and makes it available through the GetLastError Win32 API. (The status returned by the event API simply indicates a generic failure.)


Part 4
Appendixes

This part contains reference information about COM for OpenVMS and the OpenVMS Registry.

The appendixes provide information about the MIDL compiler, troubleshooting tips, COM sample code, running COM for OpenVMS in an unauthenticated environment, and APIs and interfaces.

This part also includes coupons for related COM books, a glossary, and a list of acronyms.


Appendix A
MIDL Compiler Options

A.1 Mode

Switch Use
/ms_ext Microsoft extensions to the IDL language (default)
/c_ext Allow Microsoft C extensions in the IDL file (default)
/osf OSF mode - disables /ms_ext and /c_ext options
/app_config Allow selected ACF attributes in the IDL file
/mktyplib203 MKTYPLIB Version 2.03 compatibility mode

A.2 Input

Switch Use
/acf filename Specify the attribute configuration file
/I directory-list Specify one or more directories for include path
/no_def_idir Ignore the current and the INCLUDE directories

A.3 Output File Generation

Switch Use
/client none Do not generate client files
/client stub Generate client stub file only
/out directory Specify destination directory for output files
/server none Generate no server files
/server stub Generate server stub file only
/syntax_check Check syntax only; do not generate output files
/Zs Check syntax only; do not generate output files
/old Generate old format type libraries
/new Generate new format type libraries

A.4 Output File Names

Switch Use
/cstub filename Specify client stub file name
/dlldata filename Specify dlldata file name
/h filename Specify header file name
/header filename Specify header file name
/iid filename Specify interface UUID file name
/proxy filename Specify proxy file name
/sstub filename Specify server stub file name
/tlb filename Specify type library file name

A.5 C Compiler and Preprocessor Options

Switch Use
/cpp_cmd cmd_line Specify name of C preprocessor
/cpp_opt options Specify additional C preprocessor options
/D name[=def] Pass #define name, optional value to C preprocessor
/no_cpp Turn off the C preprocessing option
/nocpp Turn off the C preprocessing option
/U name Remove any previous definition (undefine)

A.6 Environment

Switch Use
/char signed C compiler default char type is signed
/char unsigned C compiler default char type is unsigned
/char ascii7 Char values limited to 0-127
/dos Target environment is MS-DOS client
/env dos Target environment is MS-DOS client
/env mac Target environment is Apple Macintosh
/env powermac Target environment is Apple PowerMac
/env win16 Target environment is Microsoft Windows 16-bit (Win 3.x)
/env win32 Target environment is Microsoft Windows 32-bit (NT)
/mac Target environment is Apple Macintosh
/ms_union Use Midl 1.0 non-DCE wire layout for non-encapsulated unions
/oldnames Do not mangle version number into names
/powermac Target environment is Apple PowerMac
/rpcss Automatically activate rpc_sm_enable_allocate
/use_epv Generate server side application calls via entry-pt vector
/no_default_epv Do not generate a default entry-point vector
/prefix client str Add "str" prefix to client-side entry points
/prefix server str Add "str" prefix to server-side manager routines
/prefix switch str Add "str" prefix to switch routine prototypes
/prefix all str Add "str" prefix to all routines
/win16 Target environment is Microsoft Windows 16-bit (Win 3.x)
/win32 Target environment is Microsoft Windows 32-bit (NT)

A.7 Error and Warning Messages

Switch Use
/error none Turn off all error checking options
/error allocation Check for out of memory errors
/error bounds_check Check size vs transmission length specification
/error enum Check enum values to be in allowable range
/error ref Check ref pointers to be non-null
/error stub_data Emit additional check for server side stub data validity
/no_warn Suppress compiler warning messages

A.8 Optimization

Switch Use
/align {1|2|4|8} Designate packing level of structures
/pack {1|2|4|8} Designate packing level of structures
/Zp{1|2|4|8} Designate packing level of structures
/Oi Generate fully interpreted stubs
/Oic Generate fully interpreted stubs for standard interfaces and stubless proxies for object interfaces as of NT 3.51 release
/Oicf Generate fully interpreted stubs with extensions and stubless proxies for object interfaces as of NT 4.0 release
/Os Generate inline stubs
/hookole Generate HookOle debug info for local object interfaces

A.9 Miscellaneous

Switch Use
@response_file Accept input from a response file
/? Display a list of MIDL compiler switches
/confirm Display options without compiling MIDL source
/help Display a list of MIDL compiler switches
/nologo Suppress displaying of the banner lines
/o filename Redirects output from screen to a file
/W{0|1|2|3|4} Specify warning level 0-4 (default = 1)
/WX Report warnings at specified /W level as errors


Appendix B
Troubleshooting

B.1 RPC Troubleshooting

When you perform a significant number of simultaneous NTLM authentications, the following errors are likely to occur. Several factors affect the number of simultaneous NTLM authentications, however, you are most likely to see these errors when the network is congested or when the RPC application server does not respond to requests in a timely manner. The errors are returned as standard RPC application return values.

Table B-1 provides a description of the suspected cause and possible workarounds.

Table B-1 RPC Errors
Error Cause/Corrective Actions
RPC_S_CONNECTION_REJECTED This error is seen by the client application as an exception when using either DECnet Phase IV or DECnet Phase V as a transport and when the server is heavily loaded servicing other DECnet clients.

The system returns this error when the client RPC run time binds to a newly created socket and the socket call returns error 61 (connection refused).

Possible solutions:

  1. Raise DECnet resource quotas.
  2. Enhance the client RPC program to catch the exception and either retry the RPC or choose a different server.
RPC_S_CONNECTION_TIMED_OUT This error is seen by the client application as an exception when using TCP or DECnet as a transport and when the server is heavily loaded.

The system returns this error when the client RPC run time binds to a newly created socket and the server takes too long to either accept or reject the connection.

Possible solutions:

  1. Configure TCP or DECnet to wait longer before sockets time out.
  2. Enhance the RPC client application to call rpc_mgmt_set_com_timeout() and instruct the RPC run time to retry when it gets this socket error.
  3. Recode the client RPC program to catch the exception and either retry the RPC or choose a different server.
RPC_S_ASSOC_SHUTDOWN This error is seen by the client application as an exception when using TCP or DECnet as a transport and when the client is heavily loaded (usually when the client is also an RPC server).

After an RPC server receives an RPC_BIND packet from a client and the server sends back an RPC_BIND_ACK packet to the client, the server expects to receive a REQUEST packet within 12 seconds. If the client does not send the REQUEST packet within 12 seconds, the RPC server deletes the association and sends a SHUTDOWN packet to the client. The client RPC run time raises an exception to the RPC application.

This scenario is likely to occur when the client RPC application is also acting as an RPC server and that RPC server is already heavily loaded.

Possible solutions:

  1. Implement the client RPC program to catch the exception and either retry the RPC or choose a different server.
RPC_S_COMM_FAILURE

This error is seen by the client application as an exception when using DG (UDP) as a transport and when the RPC server is heavily loaded.

The RPC client sends a REQUEST packet to the server. If the client does not get a WORKING packet response from the server within 30 seconds, the client sends a PING packet to the server to see if the server is still active and working on the client's request. If the RPC server is under heavy load, the server may not return the WORKING packet to the client before the client times out.

Possible solutions:

  1. RPC client application can call rpc_mgmt_set_com_timeout() to instruct the RPC run time to wait longer than 30 seconds before timing out.
  2. Implement the client RPC program to catch the exception and either retry the RPC or choose a different server.

B.2 Troubleshooting the ACME server

Use the following procedure to troubleshoot problems with the ACME server:

  1. Verify that the ACME_SERVER process is running (use the SHOW SERVER ACME command) and verify there is a connection between the MSV1_0 ACME agent and the Advanced Server for OpenVMS process.
  2. If no connection exists, verify that the PWRK$ACME_SERVER logical name contains the SCS node names of systems in the cluster that are running the Advanced Server for OpenVMS process.
  3. If the PWRK$ACME_SERVER logical name is defined correctly, verify that the Advanced Server for OpenVMS process is running on the systems specified (look for the PWRK$LMSRV process).
  4. If authentications are failing, check the following:

B.3 Troubleshooting the DCOM$RPCSS Process

The DCOM$RPCSS process must be running to run any COM for OpenVMS applications on your OpenVMS system. The DCOM$STARTUP.COM command file is automatically starts this process. If you have problems running COM for OpenVMS applications, check that this process is running. Use the following command:


  $ SHOW SYSTEM 

If the process is initializing, the process name is DCOM$STARTUP-**. If the process is in its normal running state, the process name is be DCOM$RPCSS.

Check the SYS$MANAGER:DCOM$RPCSS.OUT log file for error messages from the DCOM$RPCSS process. The messages can include the following:

B.4 Troubleshooting the Advanced Server for OpenVMS

The Advanced Server for OpenVMS must be running to authenticate users with NT credentials.

A troubleshooter may wish to enable the audit policy to capture failures for logonoff and system events. For example, on systems running Advanced Server for OpenVMS, issue the command:


    $ ADMINISTER SET AUDIT POLICY/AUDIT/FAILURE=(LOGONOFF,SYSTEM) 

To monitor events, issue the commands:


    $ ADMINISTER SHOW EVENT /FULL /TYPE=SYSTEM 
    $ ADMINISTER SHOW EVENT /FULL /TYPE=SECURITY 

For more information, the Advanced Server for OpenVMS Server Administrator's Guide provides a chapter on Monitoring Events and Troubleshooting.

Additionally, the system manager may want to check the system operator log, SYSMANAGER:OPERATOR.LOG, to verify that no network errors have occurred.

B.5 Troubleshooting COM for OpenVMS Application Failures

This section describes problems you may encounter when running a COM application.

B.5.1 Access Denied Failures

For information on access denied failures, see Section 5.4.6.


Appendix C
Cookbook Examples: Building a Sample Application on OpenVMS

Note

SAMPLE1 and DISPATCH_SAMPLE1 are taken from Dale Rogerson's book, Inside COM, published by Microsoft Press.

C.1 COM Example (Sample1)

This sample implements a COM client and server in which the component provides two interfaces: IX and IY . The client also queries the component for a third interface, IZ , an interface that the component does not provide.

This sample demonstrates connectivity between two OpenVMS systems, between two Windows NT systems, or between an OpenVMS system and a Windows NT system.

Note

Before you build the application on OpenVMS, you must run NTA$LOGON and acquire Windows NT credentials. For more information, see Section 8.2.

C.1.1 OpenVMS Instructions

The following sections describe how to build the application on an OpenVMS system.

C.1.1.1 Building the Application on OpenVMS

Copy files from the DCOM examples directory to your local directory. For example:


   $ set default mydisk:[mydirectory] 
   $ copy dcom$examples:[sample1]*.* [] 

To build the application, run the following command procedure:


   $ @build_sample1 

If you have MMS, you can use the included description file as follows:


   $  MMS/DESCRIPTION=BUILD_SAMPLE1.MMS 

The BUILD file builds and registers both the in-process and out-of-process servers.

C.1.1.2 Registering the Application on OpenVMS

The build procedure automatically registers both DISPCMPNT$SHR.EXE and DISPCMPNT.EXE . To register the components manually, use the following procedure:

C.1.1.3 Running the Application on OpenVMS as an Out-of-Process Server

To run the sample where the component is an out-of-process server, run DISPCMPNT.EXE . When the system displays the Server: Waiting message from the component, run the client in a separate window or terminal session.

The client displays the following:


  To which server do you want to connect? 
   1) In-Process Server 
   2) Out-of-Process Server 
   : 

Enter 2 to select the out-of-process server.

C.1.1.4 Running the Application on OpenVMS and Specifying a Remote Server

Run DISPCMPNT.EXE on the system you designate as the remote machine (or server system). The remote system can also be a Windows NT system. When you receive the Server: Waiting message from the component, run the client on the system you designate as the local machine (or client system). For example:


   $ client :== $path-nameCLIENT.EXE 
   $ client remote-system-name
   2 
   $ 

The client displays the following:


  To which server do you want to connect? 
   1) In-Process Server 
   2) Out-of-Process Server 
   : 

Enter 2 to select remote server execution, out-of-process server.

C.1.1.5 Running the Application on OpenVMS as an In-Process Server

To run the sample where the component is an in-process server, run only the client. For example:


   For InProc: 
   $ client 
   1 
   $ 

The client displays the following:


  To which server do you want to connect? 
   1) In-Process Server 
   2) Out-of-Process Server 
   : 

Enter 1 to select the in-process server.

C.1.2 Windows NT Instructions

The following sections describe how to build the application on a Windows NT system.

Note

In order to build Visual C++ applications from a DOS window, you must first set up a number of environment variables. If you did not select the option to have these variables set up automatically when you installed Visual C++, you will need to set them up each time you create a DOS window. To set up these variables, execute the file


C:\Program Files\Microsoft Visual Studio\VC98\BIN\VCVARS32.BAT 

C.1.2.1 Building the Application on Windows NT

Copy the README-SAMPLE1.TXT file and the following files from the COM examples directory to your Windows NT system:


   CLIENT.CXX 
   DCLIENT.CXX 
   DISPCMPNT.CXX 
   DISPCMPNT.DEF 
   DISPCMPNT.IDL 
   MAKE-ONE. 
   MAKEFILE.BAT 
   REGISTRY.CXX 
   REGISTRY.H 

Build the sample using the MAKEFILE.BAT file. For example:


   > MAKEFILE 

The Makefile builds and registers both the in-process and out-of-process servers.

C.1.2.2 Registering the Application on Windows NT

The build procedure make-one automatically registers DISPCMPNT.DLL , PROXY.DLL , and CMPNT.EXE as follows:


   regsvr32 -s Dispcmpnt.dll 
   regsvr32 -s Proxy.dll 
   Dispcmpnt /RegServer 

To unregister the application, enter the following:


   regsvr32 -u Dispcmpnt.dll 
   regsvr32 -u Proxy.dll 
   Dispcmpnt /UnRegServer 

C.1.2.3 Running the Application on Windows NT

Run CLIENT . Follow the same procedure as described for OpenVMS for running the application as an in-process server ( Section C.1.1.5) and out-of-process server Section C.2.1.3).

Use the name of a remote machine (UNC or DNS) as an argument to instantiate the object on the remote machine. For example:


   >Client hostname        ! point the client at the remote system  
   2                       ! means outproc invocation       
   >                                                        

C.2 Automation Example (Dispatch_Sample1)

This sample implements the Automation component server as a dual interface. There are two separate clients: Dclient , which connects to the dual interface through the dispinterface, and Client , which is a COM client implementation that connects through the IUnknown interface (using a v-table).

This sample demonstrates connectivity between two OpenVMS systems, between two Windows NT systems, or between an OpenVMS system and a Windows NT system.

C.2.1 OpenVMS Instructions

The following sections describe how to build the application on an OpenVMS system.

C.2.1.1 Building the Application on OpenVMS

Copy files from the DCOM examples directory to your local directory. For example:


   $ set default mydisk:[mydirectory] 
   $ copy dcom$examples:[dispatch_sample1]*.* [] 

To build the application, run the following command procedure:


   $ @build_dispatch_sample1 

If you have MMS, you can use the included description file as follows:


   $  MMS/DESCRIPTION=BUILD_DISPATCH_SAMPLE1.MMS 

The BUILD file builds and registers both the in-process and out-of-process servers.

C.2.1.2 Registering the Application on OpenVMS

The build procedure automatically registers both DISPCMPNT$SHR.EXE and DISPCMPNT.EXE . To register the components manually, use the following procedure:

C.2.1.3 Running the Application on OpenVMS as an Out-of-process Server

To run the sample where the component is an out-of-process server, run DISPCMPNT.EXE .

When the system displays the Server: Waiting message from the component, run the client in a separate window or terminal session.

The client displays the following:


  To which server do you want to connect? 
   1) In-Process Server 
   2) Out-of-Process Server 
   : 

Enter 2 to select the out-of-process server.

C.2.1.4 Running the Application on OpenVMS and Specifying a Remote Server

Run DISPCMPNT.EXE on the system you designate as the remote machine (or server system). The remote system can also be a Windows NT system. When you receive the Server: Waiting message from the component, run the client on the system you designate as the local machine (or client system). For example:

To use the COM client, enter the following:


   $ client :== $path-nameCLIENT.EXE 
   $ client remote-system-name
  To which server do you want to connect? 
   1) In-Process Server 
   2) Out-of-Process Server 
   : 

Enter 2 to select remote server execution, out-of-process server.

C.2.1.5 Running the Application on OpenVMS as an In-Process Server

To run the sample where the component is an in-process server, run only the client. For example:

The client displays the following:


  To which server do you want to connect? 
   1) In-Process Server 
   2) Out-of-Process Server 
   : 

Enter 1 to select the in-process server.

C.2.2 Windows NT Instructions

The following sections describe how to build the application on a Windows NT system.

Note

In order to build Visual C++ applications from a DOS window, you must first set up a number of environment variables. If you did not select the option to have these variables set up automatically when you installed Visual C++, you will need to set them up each time you create a DOS window. To set up these variables, execute the file


C:\Program Files\Microsoft Visual Studio\VC98\BIN\VCVARS32.BAT 

C.2.2.1 Building the Application on Windows NT

Copy the README-DISPATCH-SAMPLE1.TXT file and the following files from the COM examples directory to your Windows NT system:


   CLIENT.CXX 
   DCLIENT.CXX 
   DISPCMPNT.CXX 
   DISPCMPNT.DEF 
   DISPCMPNT.IDL 
   MAKE-ONE. 
   MAKEFILE.BAT 
   REGISTRY.CXX 
   REGISTRY.H 

Build the sample using the MAKEFILE.BAT file. For example:


   C:> MAKEFILE 

The Makefile builds and registers both the in-process and out-of-process servers.

C.2.2.2 Registering the Application on Windows NT

The build procedure make-one automatically registers DISPCMPNT.DLL , PROXY.DLL , and DISPCMPNT.EXE as follows:


   regsvr32 -s Dispcmpnt.dll 
   Dispcmpnt /RegServer 

To unregister the application, enter the following:


   regsvr32 -u Dispcmpnt.dll 
   Dispcmpnt /UnRegServer 

C.2.2.3 Running the Application on Windows NT

Run DCLIENT or CLIENT . Follow the same procedure as described for OpenVMS for running the application as an in-process server ( Section C.2.1.5) and an out-of-process server ( Section C.2.1.3).

Use the name of a remote machine (UNC or DNS) as an argument to instantiate the object on the remote machine.

C.3 Cross-Domain Security Example (CLIENTAUTH)

This sample shows how you can authenticate a remote client that is not in the server's domain or in a domain that has a trust with the server's domain. The client must pass to this application the credentials (user name, domain and password) of an account on the server's domain that is allowed access and launch permissions. In fact, the client need not be in any domain and can be anywhere on the network. This is demonstrated in Section C.3.1.3.

C.3.1 OpenVMS Instructions

The following sections describe how to build the application on an OpenVMS system.

Note

Not all functionality is present in the underlying Windows NT infrastructure on OpenVMS. Therefore, you cannot currently run the client on OpenVMS. This sample works when you run the client on Windows NT and the server on OpenVMS.

Copy files from the DCOM examples directory to your local directory.


   $ set default mydisk:[mydirectory] 
   $ copy dcom$examples:[clientauth]*.* [] 

To build the application, run the command procedure:


   $ @build_clientauth 

The BUILD file builds and registers both the in-process and out-of-process servers.

C.3.1.1 Registering the Application on OpenVMS

PROXY$SHR.EXE , CLIENTAUTH$SHR.EXE , and CLIENTAUTH.EXE are registered automatically by the build procedure. To register the application manually, use the following procedure:

C.3.1.2 Running the Application on OpenVMS as an Out-of-Process Server

To run the sample where the component is an out-of-process server, run CLIENTAUTH.EXE . When you receive the server waiting message from the component, run the client (in a separate window or terminal session).

C.3.1.3 Running the Application on OpenVMS and Specifying a Remote Server

Run CLIENTAUTH.EXE on the system you designate as the remote machine, or server system. The remote system can also be a Windows NT system. When you receive the server waiting message from the component, run the client on the system you designate as the local machine, or client system.


   $ client :== $<path-name>CLIENT.EXE 
   $ client <remote-system-name> 
   2 
   $ Please enter account to use on remote machine: 
   $ Username: 
   $ Domain: 
   $ Password: 

The client will ask whether you want to start an in-process server or an out-of-process server. For remote server execution, select out-of-process server. You will then be prompted to enter the user name, domain and password of an account on the remote server. Make sure this account has been granted access and launch permissions to the component (see Section 6.3.2).

C.3.1.4 Running the Application on OpenVMS as an In-Process Server

To run the sample where the component is an in-process server, run only the client:


   For InProc: 
   $ client 
   1 
   $ 

The client will ask whether you want to start an in-process server or an out-of-process server. Select in-process server.

C.3.2 Windows NT Instructions

The following sections describe how to build the application on a Windows NT system.

Note

In order to build Visual C++ applications from a DOS window, you must first set up a number of environment variables. If you did not select the option to have these variables set up automatically when you installed Visual C++, you will need to set them up each time you create a DOS window. To set up these variables, execute the file


C:\Program Files\Microsoft Visual Studio\VC98\BIN\VCVARS32.BAT 

C.3.2.1 Building the Application on Windows NT

Copy this file README-CLIENTAUTH.TXT and the following files from the DCOM examples directory to your Windows NT system:


   CLIENT.CXX 
   CLIENTAUTH.CXX 
   CLIENTAUTH.DEF 
   CLIENTAUTH.IDL 
   GUIDS.CXX 
   MAKE-ONE. 
   MAKEFILE.BAT 
   PROXY.DEF 
   REGISTRY.CXX 
   REGISTRY.H 

Build the sample using the MAKEFILE.BAT file.


   > MAKEFILE 

The Makefile builds and registers both the in-process and out-of-process servers.

C.3.2.2 Registering the Application on Windows NT

CLIENTAUTH.DLL , PROXY.DLL , and CLIENTAUTH.EXE are registered automatically by the build procedure <make-one>:


   regsvr32 -s clientauth.dll 
   regsvr32 -s Proxy.dll 
   clientauth /RegServer 

To unregister:


   regsvr32 -u clientauth.dll 
   regsvr32 -u Proxy.dll 
   clientauth /UnRegServer 

C.3.2.3 Running the Application on Windows NT

Run CLIENT. Follow the same procedure as described for OpenVMS for running application as in-process and out-of-process (see Section C.3.1.2 and Section C.3.1.4).

Do not use command line arguments to instantiate the object on the current machine. Use the name of a remote machine (UNC or DNS) as an argument to instantiate the object on the remote machine.


  (i.e) >Client hostname        ! point the client at the remote system 
        2                       ! means outproc invocation       
        >                                                        
        >Username: 
        >Domain: 
        >Password: 


Previous Next Contents Index