OpenVMS Connectivity Developer Guide


Previous Contents Index


DELETE KEY

Removes a specified key from the OpenVMS Registry database. The system does not delete a key if the key has subkeys.

Caution

Deleting a key results in symbolic links not being followed. This is because the system deletes the key you specified, even if it has symbolic links.

Note

The OpenVMS Registry database predefined keys are reserved keys and cannot be deleted. These keys include HKEY_USER , HKEY_LOCAL_MACHINE , and HKEY_CLASSES_ROOT . For a complete list, see Section 12.3.

This command requires the SYSPRV privilege or the REG$UPDATE rights identifier.


Format

DELETE KEY key-path key-name


Parameters

key-path

Specifies the key path.

key-name

Specifies the name of the key to delete.

Qualifiers

/WAIT=seconds
/NOWAIT

Specifies the number of seconds that the OpenVMS Registry should wait for the command to complete. By default, the OpenVMS Registry waits 90 seconds for the command to complete.

/WRITEBEHIND
/NOWRITEBEHIND (default)

Specifies that the key information must be written to disk immediately. /NOWRITEBEHIND specifies a write-through operation.

Examples


REG> DELETE KEY HKEY_USERS\NODE GUEST

Deletes the GUEST key from the OpenVMS Registry database.


DELETE VALUE

Removes a value from a specified key.

Caution

Deleting a value results in symbolic links not being followed. This is because the system deletes the value you specified, even if it has symbolic links.

This command requires the SYSPRV privilege or the REG$UPDATE rights identifier.


Format

DELETE VALUE key-name value-name


Parameters

key-name

Specifies the key name whose value should be removed.

value-name

Specifies the value to remove.

Qualifiers

/WAIT=seconds
/NOWAIT

Specifies the number of seconds that the OpenVMS Registry should wait for the command to complete. By default, the OpenVMS Registry waits 90 seconds for the command to complete.

/WRITEBEHIND
/NOWRITEBEHIND (default)

Specifies that the information must be written to disk immediately. /NOWRITEBEHIND specifies a write-through operation.

Examples


REG> DELETE VALUE HKEY_USERS\GUEST PASSWORD

Deletes the PASSWORD value from the GUEST key.


EXPORT

Allows a user to export the OpenVMS Registry database content to a text format. You can export the entire database or specific keys and subkeys.

You can specify the exported file as a Windows NT compatible format or in an OpenVMS format. The IMPORT command support both Windows NT 4.0 Regedit format and the OpenVMS Registry format.

This command requires the REG$LOOKUP rights identifier. If you do not have the REG$LOOKUP rights identifier, you must have the SYSPRV privilege to export keys that require the REG$LOOKUP rights identifier.


Format

EXPORT [DATABASE | KEY [key-name [/[NO]SUBKEYS]]] [/LOG] [/OUTPUT=file-name ] [/FORMAT=[NT | OPENVMS]]


Parameters

DATABASE

Exports the full OpenVMS Registry database.

KEY [key-name [/[NO]SUBKEYS]]

Exports a specific OpenVMS Registry key and, optionally, its subkeys. NOSUBKEYS is the default.

Qualifiers

/FORMAT=[NT | OPENVMS]

Specifies the format in which the system writes the database. OPENVMS is the default.

/LOG

Displays the export progress to the screen.

/OUTPUT=file-name

Specifies a name for the exported file. The default output file name is REGISTRY.TXT .

/WAIT=seconds
/NOWAIT

Specifies the number of seconds that the OpenVMS Registry should wait for the command to complete. By default, the OpenVMS Registry waits 90 seconds for the command to complete.

Examples


REG> EXPORT DATABASE/LOG/OUTPUT=TUES_VERSION.TXT/FORMAT=NT

The EXPORT command in this example logs the progress of the export to the screen as the system exports the entire OpenVMS Registry database to the TUES_VERSION.TXT file in Windows NT 4.0 Regedit format.


IMPORT

Allows a user to import a text-formatted file (created by the EXPORT command) into an OpenVMS Registry database.

Also allows a user to import into an OpenVMS Registry database the Windows NT data exported by Windows NT 4.0 Regedit (from the Registry menu choose the Export Registry File... option).

Conversion of Windows NT binary values

You can import Windows NT binary values (such as configuration data) into the OpenVMS Registry database, even though OpenVMS does not support the binary values. The system displays a message when importing and converting unsupported binary values.

This command requires the REG$UPDATE rights identifier. If you do not have the REG$UPDATE rights identifier, you must have the SYSPRV privilege to import keys that require the REG$LOOKUP or REG$UPDATE rights identifier.

The following table summarizes how rights identifiers and privileges affect your ability to import and export keys.
If you have: You can export from Windows NT: You can import to the OpenVMS Registry:
No privileges.
No rights identifiers
All keys created by Compaq Advanced Server for OpenVMS except HKEY_LOCAL_MACHINE\SECURITY Nothing
REG$LOOKUP All keys created by Compaq Advanced Server for OpenVMS Nothing
REG$UPDATE All keys created by Compaq Advanced Server for OpenVMS All keys created by Compaq Advanced Server for OpenVMS
SYSPRV All keys created by Compaq Advanced Server for OpenVMS All keys created by Compaq Advanced Server for OpenVMS


Format

IMPORT [/LOG] [/INPUT=file-name ]


Parameters

None


Qualifiers

/INPUT=file-name

Specifies a name of the file to import. The default input file name is REGISTRY.TXT .

/LOG

Displays the import progress to the screen.

/WAIT=seconds
/NOWAIT

Specifies the number of seconds that the OpenVMS Registry should wait for the command to complete. By default, the OpenVMS Registry waits 90 seconds for the command to complete.

Examples


REG> IMPORT/LOG/INPUT=TUES_VERSION.TXT

The IMPORT command in this example logs the progress of the import to the screen as the system imports the TUES_VERSION.TXT file.


LIST KEY

Displays the attributes for the specified key.

Note

Symbolic links are not followed.

This command requires the SYSPRV privilege or the REG$LOOKUP rights identifier.


Format

LIST KEY key-name


Parameters

key-name

Specifies the name of the key to list.

Qualifiers

/CACHE_ACTION=value

Specifies the cache attribute for the subkey. The value can be WRITEBEHIND (default) or WRITETHRU (write to disk immediately).

/CLASS_NAME

Displays the class name of the subkey.

/FULL

Displays all available information---that is, information displayed by the /LAST_WRITE, /CACHE_ACTION, /INFORMATION, /LINK_PATH, and /CLASS_NAME qualifiers.

/INFORMATION

Displays the information (subkey number, value number, subkey name max, and so on) about the specified key.

/LAST_WRITE

Displays the time when the subkey was last updated.

/LINK_PATH

Displays the key path to which the subkey is linked.

/OUTPUT=file-spec

Controls where the output of the command is sent. If you do not specify a file name, the system uses the default name REGISTRY.LIS .

/WAIT=seconds
/NOWAIT

Specifies the number of seconds that the OpenVMS Registry should wait for the command to complete. By default, the OpenVMS Registry waits 90 seconds for the command to complete.

Examples


REG> LIST KEY/FULL HKEY_USERS\GUEST 
 
Key name:            HKEY_USERS\GUEST 
Security policy:     REG$K_POLICY_NT_40 
Volatile:            REG$K_NONE 
Cache:               REG$K_WRITEBEHIND 
Class:               System Authorization 
Link Type:           REG$K_NONE 
Last written:         7-AUG-1998 12:42:08.55 
 
Key information: 
  Number of subkeys:             2        Number of values:              0 
  Max size of subkey name:      40        Max size of class name:       40 
  Max size of value name:        0        Max size of value data:        0 
 
Subkey(s): 
 
    Key name:            QUOTAS 
    Security policy:     REG$K_POLICY_NT_40 
    Volatile:            REG$K_NONE 
    Cache:               REG$K_WRITEBEHIND 
    Class:               Disk quota 
    Link Type:           REG$K_NONE 
    Last written:         7-AUG-1998 12:41:19.21 
 
    Key information: 
      Number of subkeys:             0        Number of values:              0 
      Max size of subkey name:       0        Max size of class name:        0 
      Max size of value name:        0        Max size of value data:        0 
 
    Key name:            IDENTIFIER 
    Security policy:     REG$K_POLICY_NT_40 
    Volatile:            REG$K_NONE 
    Cache:               REG$K_WRITETHRU 
    Class:               Disk quota 
    Link Type:           REG$K_SYMBOLICLINK 
    Link Path:           HKEY_LOCAL_MACHINE\SOFTWARE\IDENTIFIER\GUEST 
    Last written:         7-AUG-1998 12:42:08.55 
 
    Key information: 
      Number of subkeys:             0        Number of values:              0 
      Max size of subkey name:       0        Max size of class name:        0 
      Max size of value name:        0        Max size of value data:        0 
 

The LIST KEY/FULL command in this example displays the GUEST key attributes as well as the name and attributes of the subkeys of GUEST .

Note

The Max sizes information shows the number of bytes, not characters. (Each character is 4 bytes long.)

LIST VALUE

Displays all values and value attributes of the specified key.

Note

Symbolic links are not followed.

This command requires the SYSPRV privilege or the REG$LOOKUP rights identifier.


Format

LIST VALUE key-name


Parameters

key-name

Specifies the name of the key to enumerate.

Qualifiers

/DATA

Displays an ASCII representation of the value in hexadecimal format.

/FULL

Displays all available information---that is, information displayed by the /TYPE_CODE, /LINK_PATH, /DATA_FLAGS, and /VALUE_DATA qualifiers.

/FLAGS

Displays an ASCII representation of the data flag of the value in hexadecimal format.

/LINK_PATH

Displays the key path to which the subkey is linked.

/OUTPUT=file-spec

Controls where the output of the command is sent. If you do not specify a file name, the system uses the default name REGISTRY.LIS .

/TYPE_CODE

Display the type code of the value.

/WAIT=seconds
/NOWAIT

Specifies the number of seconds that the OpenVMS Registry should wait for the command to complete. By default, the OpenVMS Registry waits 90 seconds for the command to complete.

Examples


REG> LIST VALUE/TYPE_CODE/DATA HKEY_LOCAL_MACHINE\SOFTWARE\FORTRAN 
 
   Key name:            HKEY_LOCAL_MACHINE\SOFTWARE\FORTRAN 
   Security policy:     REG$K_POLICY_NT_40 
   Volatile:            REG$K_NONE 
   Last written:        11-AUG-1998 16:27:55.81 
 
   Value(s): 
 
     Value name:   Version 
     Volatile:     REG$K_NONE 
     Type:         REG$K_SZ 
     Data:         5.3-50 
 
     Value name:   Date Installed 
     Volatile:     REG$K_NONE 
     Type:         REG$K_SZ 
     Data:         04-Jan-1998 

The LIST VALUE/TYPE_CODE/DATA command in this example displays the FORTRAN key and its value names, types, and data.


MODIFY KEY

Modifies the attributes of the specified key.

Caution

Modifying a key results in symbolic links not being followed. This is because the system modifies the key you specified, not the key pointed to by the symbolic link.

This command requires the SYSPRV privilege or the REG$UPDATE rights identifier.


Format

MODIFY KEY key-name


Parameters

key-name

Specifies the name of the key to modify.

Qualifiers

/CACHE_ACTION=value

Specifies the cache attribute for the new key. The value can be WRITEBEHIND (default) or WRITETHRU (write to disk immediately).

/CLASS_NAME=string

Specifies the new class name of the key.

/LINK=(TYPE=value, NAME=key-name)

Defines the key as a link to another key. The link value must be one of the following:

To remove a link, enter the following:


/LINK=(TYPE=NONE,NAME="") 

/NEW_NAME=new-key-name

Specifies the new name of the key.

/SECPOLICY=policy

Defines the security policy for the key. Currently the only valid policy is NT_40 .

/WAIT=seconds
/NOWAIT

Specifies the number of seconds that the OpenVMS Registry should wait for the command to complete. By default, the OpenVMS Registry waits 90 seconds for the command to complete.

/WRITEBEHIND
/NOWRITEBEHIND (default)

Specifies that the key information must be written to disk immediately. /NOWRITEBEHIND specifies a write-through operation.

Examples


REG> MODIFY KEY/CACHE_ACTION=WRITEBEHIND HKEY_USERS\GUEST

Modifies the cache attribute of the GUEST key.


MODIFY VALUE

Specifies the data component for the specified value. This command modifies an existing value.

Caution

Modifying a value results in symbolic links not being followed. This is because the system modifies the value you specified, not the value pointed to by the symbolic link.

This command requires the SYSPRV privilege or the REG$UPDATE rights identifier.


Format

MODIFY VALUE /NAME=string key-name


Parameters

key-name

Specifies the name of the key for which to set the value.

Qualifiers

/DATA=value

Specifies the data for the value. The value can be:

/FLAGS=flag

Specifies the data flags value. This is an application-dependent 64-bit flag specified as a decimal number or as a hexadecimal number preceded by 0x or %X.

/LINK=(TYPE=value, NAME=key-name)

Defines the key as a link to another key. The link value must be one of the following:

To remove a link, enter the following:


/LINK=(TYPE=NONE,NAME="") 

/NAME=string

Specifies the name of the value.

/TYPE_CODE=type

Specifies the type of the new value. The type value must be one of the following:

/WAIT=seconds
/NOWAIT

Specifies the number of seconds that the OpenVMS Registry should wait for the command to complete. By default, the OpenVMS Registry waits 90 seconds for the command to complete.

/WRITEBEHIND
/NOWRITEBEHIND (default)

Specifies that the value information must be written to disk immediately. /NOWRITEBEHIND specifies a write-through operation.

Examples


REG> MODIFY VALUE/DATA=COSMOS/TYPE=SZ/NAME=COMPUTERNAME HKEY_LOCAL_MACHINE\NODE

Creates COMPUTERNAME value for the key HKEY_LOCAL_MACHINE\NODE , and sets its type code to SZ and its data value to COSMOS .


MODIFY TREE

Modifies the information for the specified key and its subkeys.

Caution

Modifying a tree results in symbolic links not being followed. This is because the key and subkeys you specify are modified, not the key pointed to by the symbolic link.

This command requires the SYSPRV privilege or the REG$UPDATE rights identifier.


Format

MODIFY TREE key-name


Parameters

key-name

Specifies the name of key to modify.

Qualifiers

/CACHE_ACTION=value

Specifies the cache attribute for the key and its subkeys. The value can be WRITEBEHIND (default) or WRITETHRU (write to disk immediately).

/CLASS_NAME=string

Specifies the new class name for the given key and all its subkeys.

/SECPOLICY=policy

Defines the security policy for the key. Currently the only valid policy is NT_40 .

/WAIT=seconds
/NOWAIT

Specifies the number of seconds that the OpenVMS Registry should wait for the command to complete. By default, the OpenVMS Registry waits 90 seconds for the command to complete.

/WRITEBEHIND
/NOWRITEBEHIND (default)

Specifies that the key information must be written to disk immediately. /NOWRITEBEHIND specifies a write-through operation.

Examples


REG> MODIFY TREE/CACHE_ACTION=WRITEBEHIND HKEY_USERS\GUEST

Modifies the cache attribute of the GUEST key and all its subkeys.


SEARCH KEY

Displays the path name of all the keys that match the specified key.

This command requires the SYSPRV privilege or the REG$LOOKUP rights identifier.


Format

SEARCH KEY key-search


Parameters

key-search

Specifies the key name for which to search.

Qualifiers

/OUTPUT=file-spec

Controls where the output of the command is sent. If you do not specify a file name, the system uses the default name REGISTRY.LIS .

/WAIT=seconds
/NOWAIT

Specifies the number of seconds that the OpenVMS Registry should wait for the command to complete. By default, the OpenVMS Registry waits 90 seconds for the command to complete.

Examples


REG> SEARCH KEY HKEY_LOCAL_MACHINE\...\NODE
HARDWARE\CLUSTER\NODE 
HARDWARE\LOCAL\NODE  
NODE  

Displays all the key paths that match the HKEY_LOCAL_MACHINE\...\NODE selection. The ellipsis (...) wildcard specifies that there can be any number of subkeys between the HKEY_LOCAL_MACHINE entry point and the NODE subkey. Note that the search is not case sensitive.


SEARCH VALUE

Displays the path name of all the values that match the specified value name.

This command requires the SYSPRV privilege or the REG$LOOKUP rights identifier.


Format

SEARCH VALUE key-name value-name


Parameters

key-name

Specifies the name of the key path to search.

value-name

Specifies the value name for which to search.

Qualifiers

/OUTPUT=file-spec

Controls where the output of the command is sent. If you do not specify a file name, the system uses the default name REGISTRY.LIS .

/WAIT=seconds
/NOWAIT

Specifies the number of seconds that the OpenVMS Registry should wait for the command to complete. By default, the OpenVMS Registry waits 90 seconds for the command to complete.

Examples


REG> SEARCH VALUE HKEY_LOCAL_MACHINE\... *AM%
HARDWARE\CLUSTER\Name  
HARDWARE\CLUSTER\NODE\Name  
HARDWARE\LOCAL\NODE\Name  
NODE\COMPUTERNAME  

Displays all the value names that match the HKEY_LOCAL_MACHINE\...\*am% selection. The ellipsis (...) wildcard specifies that there can be any number of subkeys between the HKEY_LOCAL_MACHINE entry point and the *am% value name. Note that the search is not case sensitive.


SHOW

Displays OpenVMS Registry server internal statistics and information.

This command requires the SYSPRV privilege or the REG$PERFORMANCE rights identifier.


Format

SHOW COUNTERS/FILE [name]

SHOW FILE [name]


Parameters

name

Identifies the file (used with the /FILE qualifier only).

Qualifiers

/FILE

Displays counters for the specified file or for all files.

/PERFORMANCE

Displays performance counters.

/OUTPUT=file-spec

Controls where the output of the command is sent. If you do not specify a file name, the system uses the default name REGISTRY.LIS .

/WAIT=seconds
/NOWAIT

Specifies the number of seconds that the OpenVMS Registry should wait for the command to complete. By default, the OpenVMS Registry waits 90 seconds for the command to complete.

Examples


REG> SHOW COUNTERS/FILE

Displays monitoring information from the OpenVMS Registry server.


START MONITORING

Starts a monitoring component within the OpenVMS Registry server.

This command requires the SYSPRV privilege or the REG$PERFORMANCE rights identifier.


Format

START MONITORING/FILE [name]

START MONITORING/PERFORMANCE


Parameters

name

Identifies the file (used with the /FILE qualifier only).

Qualifiers

/FILE

Start gathering counters for the specified file or for all files.

/PERFORMANCE

Start gathering performance counters.

/WAIT=seconds
/NOWAIT

Specifies the number of seconds that the OpenVMS Registry should wait for the command to complete. By default, the OpenVMS Registry waits 90 seconds for the command to complete.

Examples


REG> START MONITORING/PERFORMANCE

Enables a monitoring component of the OpenVMS Registry.


STOP

Stops a monitoring component within the OpenVMS Registry server.

This command is used to stop a monitoring component within the OpenVMS Registry server.

This command requires the SYSPRV privilege or the REG$PERFORMANCE rights identifier.


Format

STOP MONITORING/FILE [name]

STOP MONITORING/PERFORMANCE


Parameters

name

Identifies the file (used with the /FILE qualifier only).

Qualifiers

/FILE

Stop gathering counters for the specified file or for all files.

/PERFORMANCE

Stop gathering performance counters.

/WAIT=seconds
/NOWAIT

Specifies the number of seconds that the OpenVMS Registry should wait for the command to complete. By default, the OpenVMS Registry waits 90 seconds for the command to complete.

Examples


REG> STOP MONITORING/PERFORMANCE

Disables a monitoring component of the OpenVMS Registry.


ZERO COUNTERS

Initializes counters within the OpenVMS Registry server.

This command requires the SYSPRV privilege or the REG$PERFORMANCE rights identifier.


Format

ZERO COUNTERS/FILE [name]

ZERO COUNTERS/PERFORMANCE


Parameters

name

Identifies the file (used with the /FILE qualifier only).

Qualifiers

/FILE

Initializes the file counters for the specified file or for all files.

/PERFORMANCE

Initializes all performance counters.

/WAIT=seconds
/NOWAIT

Specifies the number of seconds that the OpenVMS Registry should wait for the command to complete. By default, the OpenVMS Registry waits 90 seconds for the command to complete.

Examples


REG> ZERO COUNTERS/PERFORMANCE

Resets the performance counters.


Chapter 15
OpenVMS Registry System Services

The OpenVMS Registry $REGISTRY and $REGISTRYW system services are described in the OpenVMS System Services Reference Manual.


Part 3
OpenVMS Events

This part contains reference information about OpenVMS Events.


Chapter 16
OpenVMS Events

16.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 Compaq 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.

16.1.1 Suggested Reading

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

16.2 Overview of OpenVMS Events

The system logs OpenVMS Events to a Windows NT event log, to the Compaq 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:

16.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:

16.2.2 Viewing OpenVMS Events Using Compaq Advanced Server for OpenVMS Event Viewer

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

  1. Ensure that the Compaq Advanced Server for OpenVMS is running.
  2. Enter the following Compaq 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.

16.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 16-1 shows the contents of an event log.

Example 16-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.

16.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.

16.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 Compaq 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 Compaq Advanced Server for OpenVMS dispatcher validates the information and calls the appropriate routines to perform the requested operation (register, report, or deregister).
    If the Compaq 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 16-1 lists (in order of importance) the checks you should perform.

Table 16-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 Compaq 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 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


Previous Next Contents Index