COM, Registry, and Events for OpenVMS Developer's Guide

Document revision date: 15 July 2002

COM, Registry, and Events for OpenVMS Developer's Guide

Contents

Index

DEC:253, 254, 255, 256, 257 (bytes/words, unaligned) DEC:253, 0, 254, 0, 255, 0, 256, 257 (bytes/words, word aligned) DEC:253, 0, 254, 0, 255, 0, 0, 1, 0, 2 (byte stream, word aligned)

The input and storage types must be compatible. For example, you cannot specify value type DWORD (which means that the stored data is 4 bytes) and then input the SZ string "A" because then the SZ string would consist of the character 00000041 and the terminator 00000000, which cannot fit in a DWORD. Attempting this will result in a REG-E-INVDATA error. However, specifying an empty string ("") does work and stores just the terminator. Conversely, the input type DWORD specifies an input data length of 4 bytes. You cannot specify value type SZ and input type DWORD:00000041 because SZ strings must be terminated. The only valid DWORD you can enter in this case is 00000000.

When specifying /INPUT, you cannot specify the /DATA qualifier.

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

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

SYMBOLICLINK
NONE

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:

SZ: a null-terminated Unicode string
EXPAND_SZ: a string of Unicode characters
MULTI_SZ: a concatenated array of SZ strings
DWORD: a 32-bit number
BINARY: raw binary data

/WAIT=seconds
/NOWAIT

Specifies the maximum amount of time, in seconds, that you are willing to wait for command completion. If the Registry server does not complete the request in the specified interval, REG$CP returns REG-F-NORESPONSE. The default interval is 90 seconds. /NOWAIT is equivalent to specifying /WAIT=0, but there may still be a short wait period.

/WRITEBEHIND
/NOWRITEBEHIND (default)

Specifies when the information can be written to disk. /WRITEBEHIND specifies that the information can be written to disk later. /NOWRITEBEHIND specifies write-through operation (that is, the information must be written to disk immediately).

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 .

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 maximum amount of time, in seconds, that you are willing to wait for command completion. If the Registry server does not complete the request in the specified interval, REG$CP returns REG-F-NORESPONSE. The default interval is 90 seconds. /NOWAIT is equivalent to specifying /WAIT=0, but there may still be a short wait period.

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 maximum amount of time, in seconds, that you are willing to wait for command completion. If the Registry server does not complete the request in the specified interval, REG$CP returns REG-F-NORESPONSE. The default interval is 90 seconds. /NOWAIT is equivalent to specifying /WAIT=0, but there may still be a short wait period.

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.

SHOW COUNTERS
Displays monitoring information from the OpenVMS Registry server.
SHOW FILE
Displays status information on files loaded into the OpenVMS Registry server.

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 maximum amount of time, in seconds, that you are willing to wait for command completion. If the Registry server does not complete the request in the specified interval, REG$CP returns REG-F-NORESPONSE. The default interval is 90 seconds. /NOWAIT is equivalent to specifying /WAIT=0, but there may still be a short wait period.

Examples

REG> SHOW COUNTERS/FILE
Displays monitoring information from the OpenVMS Registry server.
REG> SHOW COUNTERS/FILE REGISTRY$USERS
Displays monitoring information for file REGISTRY$USERS 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 maximum amount of time, in seconds, that you are willing to wait for command completion. If the Registry server does not complete the request in the specified interval, REG$CP returns REG-F-NORESPONSE. The default interval is 90 seconds. /NOWAIT is equivalent to specifying /WAIT=0, but there may still be a short wait period.

Examples

REG> START MONITORING/PERFORMANCE
Enables a monitoring component of the OpenVMS Registry.

STOP MONITORING

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 maximum amount of time, in seconds, that you are willing to wait for command completion. If the Registry server does not complete the request in the specified interval, REG$CP returns REG-F-NORESPONSE. The default interval is 90 seconds. /NOWAIT is equivalent to specifying /WAIT=0, but there may still be a short wait period.

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 maximum amount of time, in seconds, that you are willing to wait for command completion. If the Registry server does not complete the request in the specified interval, REG$CP returns REG-F-NORESPONSE. The default interval is 90 seconds. /NOWAIT is equivalent to specifying /WAIT=0, but there may still be a short wait period.

Examples

REG> ZERO COUNTERS/PERFORMANCE
This example resets the performance counters.

Part 3
OpenVMS Events

This part contains reference information about OpenVMS Events.

Chapter 15
OpenVMS Events

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

15.1.1 Suggested Reading

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

Third-party books on event logging:
- Windows NT Server 4.0 Unleashed, Jason Garms, SAMS Publishing, Indianapolis, IN, 1998. ISBN: 0-672-30933-5.
- Win32 System Services: The Heart of Window 95 and Windows NT, Marshall Brain, Prentice Hall, Upper Saddle River, NJ, 1996. ISBN: 0-13-324732-5.
Other sources:
- Microsoft Win32 Software Development Kit
  In particular, see the sections about the RegisterEventSource , ReportEvent , and DeregisterEventSource functions, and System Services: Event Logging section.

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

Windows NT event viewer (see Section 15.2.1)
Compaq Advanced Server for OpenVMS event viewer (see Section 15.2.2)
OpenVMS event log file (see Section 15.2.3)

15.2.1 Viewing OpenVMS Events Using Windows NT Event Viewer

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

Start the Windows NT event viewer.
From the Start menu, select Programs, Administrative Tools, Event Viewer.
From the Event Viewer window, click the menu bar Log option. Click Select Computer...., and select the OpenVMS system from the list box.
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:
- From the Event Viewer window, click the menu bar View option. Click Filter Events....
  The system displays the Filter window.
- On the Filter window, click the Source: list box. From the list, choose DCOM.

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

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

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

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

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

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).
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$_SERVER_NAME
The universal naming convention (UNC) name of the server on which this operation is to be performed.
UNC names have the form \\server\share\path\file. This item must be zero or unspecified. This performs the operation on an available Compaq Advanced Server for OpenVMS server in the cluster.
EVT$_SOURCE
The name of the application that logs the event. This field associates an application message file that contains descriptive text with the application's event log entries.
If specified, the source must be a subkey of the Eventlog\System key, the Eventlog\Security key, or the Eventlog\Application registry key. For example, a source name of Myapp indicates a registry entry in the following:
HKEY_LOCAL_MACHINE\System\CurrentControlSet\ Services\Eventlog\Application\Myapp)
The Myapp registry value EventMessageFile names the path and message file to be used to translate this application's events.
The source can be unspecified or specified as NULL. In this case, the system logs events to the Application log file but the application logs no message file (and, as a result, no replacement text) for the associated events.
EVT$_HANDLE
Returns a handle to the Application event log. This handle is required input for other $EVENT functions.
On failure, a handle of 0 is returned. This handle is outside the responsibility of the CloseHandle API.
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$_HANDLE
Value returned by a previous EVT$_FC_REGISTER_EVENT_SOURCE call.
EVT$_EVENT_TYPE
Indicates the severity of the event. The type is one of the following:
EVT$_SUCCESS
EVT$_ERROR
EVT$_WARNING
EVT$_INFO
EVT$_AUDIT_SUCCESS
EVT$_AUDIT_FAILURE

The severity type maps to its Windows NT equivalent, defined in WINNT.H.
EVT$_EVENT_CATEGORY
An integer value from 1 to 65535. EVT$_EVENT_CATEGORY is unique to a particular source.
EVT$_EVENT_CATEGORY allows an application to divide its message file into sections, each indexed by event ID. If you do not specify a category, the system defaults to a category of zero.
EVT$_EVENT_ID
An unlimited integer value. This value indexes the category in an application message file that locates the text string displayed for this event message. The event ID is unique to a particular source.
EVT$_USER_SID
The optional Windows NT Security ID of the thread logging the event. An application that has acquired Windows NT credentials through the $PERSONA system service can obtain its SID through calls to the OpenProcessToken and GetTokenInformation Win32 APIs. The format is opaque to this service.
EVT$_NUMSTRINGS
A count of the strings specified in the EVT$_STRING_ARRAY item code.
EVT$_DATASIZE
Length in bytes of the buffer indicated by the EVT$_RAW_DATA item code.
EVT$_STRING_ARRAY
An array of string pointers. Each entry points to a null terminated string. A description string in a message file can contain string placeholders in the form %n, where %1 indicates the first placeholder. Strings specified in this array replace these placeholders when the system displays the event message.
EVT$_RAW_DATA
Allows you to include binary data in an event message.
For example, you might use this to dump a data structure from a failing component.

EVT$_DEREGISTER_EVENT_SOURCE
Close an association with an event log.

Item code Required Parameter Data type

EVT$_HANDLE Yes Input Unsigned longword

EVT$_HANDLE
Value returned by a previous EVT$_FC_REGISTER_EVENT_SOURCE call.

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

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

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.

Contents

Index

privacy and legal statement

6539PRO_016.HTML

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

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

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

COM, Registry, and Events for OpenVMS Developer's Guide

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

/NAME=string

/TYPE_CODE=type

/WAIT=seconds /NOWAIT

/WRITEBEHIND /NOWRITEBEHIND (default)

Examples

SEARCH KEY

Format

Parameters

key-search

Qualifiers

/OUTPUT=file-spec

/WAIT=seconds /NOWAIT

Examples

SEARCH VALUE

Format

Parameters

key-name

value-name

Qualifiers

/OUTPUT=file-spec

/WAIT=seconds /NOWAIT

Examples

SHOW

Format

Parameters

name

Qualifiers

/FILE

/PERFORMANCE

/OUTPUT=file-spec

/WAIT=seconds /NOWAIT

Examples

START MONITORING

Format

Parameters

name

Qualifiers

/FILE

/PERFORMANCE

/WAIT=seconds /NOWAIT

Examples

STOP MONITORING

Format

Parameters

name

Qualifiers

/FILE

/PERFORMANCE

/WAIT=seconds /NOWAIT

Examples

ZERO COUNTERS

Format

Parameters

name

Qualifiers

/FILE

/PERFORMANCE

/WAIT=seconds /NOWAIT

Examples

Part 3OpenVMS Events

Chapter 15OpenVMS Events

15.1 What are Events?

15.1.1 Suggested Reading

15.2 Overview of OpenVMS Events

15.2.1 Viewing OpenVMS Events Using Windows NT Event Viewer

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

15.2.3 Event Logging on OpenVMS Only

NTA$EVENTW

Format

Arguments

nullarg

func

itmlst

evsb

EVT$_FC_REGISTER_EVENT_SOURCE

EVT$_FC_REPORT_EVENT

EVT$_DEREGISTER_EVENT_SOURCE

/WAIT=seconds
/NOWAIT

/WRITEBEHIND
/NOWRITEBEHIND (default)

/WAIT=seconds
/NOWAIT

/WAIT=seconds
/NOWAIT

/WAIT=seconds
/NOWAIT

/WAIT=seconds
/NOWAIT

/WAIT=seconds
/NOWAIT

/WAIT=seconds
/NOWAIT

Part 3
OpenVMS Events

Chapter 15
OpenVMS Events