Document revision date: 15 July 2002

The following sections list and describe the required OpenVMS Registry entries.

7.5.1 HKEY_CLASSES_ROOT\CLSID

The CLSID subkey contains all CLSIDs for the components supported on your system. You must register your components' CLSIDs here. Each registered CLSID should contain the following:

• An unnamed value whose type is a zero-terminated string with a data value describing the component.
• A named value, AppID , whose type is a zero-terminated string with a data value that is the CLSID of the component.

A class identifier (CLSID) is a globally unique identifier (GUID) associated with an OLE class object. COM for OpenVMS server applications typically register their CLSIDs in the OpenVMS Registry so clients can locate and load the executable code associated with the OLE class object.

Register the CLSID for the component under the subkey HKEY_CLASSES_ROOT\CLSID .

A component CLSID registration should contain the following subkeys:

• LocalServer32
  This key's value should contain a zero-terminated string with a data value that is the location of the out-of-process server executable.
• ProgID
  This key's value should contain a zero-terminated string with a data value that is the programmatic ID of the CLSID. These are typically in the format program.component.version.
• VersionIndependentProgID
  This key's value should contain a zero-terminated string with a data value that is the programmatic ID (less the version number) of the CLSID. These are typically in the format program.component.
• InProcServer32
  This key's value should contain a zero-terminated string with a data value that is the location of the in-process server's shareable image.
• Type Libraries
  Type libraries are important for implementing the IDispatch interface. A type library registers itself when it calls the OLE Automation RegisterTypeLib run-time routine. You must also add a Typelib subkey under your component's CLSID. The Typelib subkey contains your type library's GUID. For example, the following key should contain your LIBID:

  HKEY_CLASSES_ROOT\CLSID\{GUID}\TYPELIB {value=LIBID}

The proxy/stub shareable image provides an interface-specific object for packaging parameters for that interface. Because the proxy/stub shareable image contains an object, it needs a CLSID and it needs to be included in the OpenVMS Registry. You must register a CLSID for the proxy in the OpenVMS Registry the same way as the CLSID for the component.

The CLSID for the proxy should be registered under the subkey HKEY_CLASSES_ROOT\CLSID .

A proxy/stub CLSID registration should contain the following subkey:

• InProcServer32
  The InProcServer32 value should contain a zero-terminated string with a data value that is the location of the proxy/stub shareable image. The proxy/stub CLSID and its subkey enable COM to locate the proxy/stub shareable image.

The Interface subkey contains all interfaces registered with the system. You must register the component's interface IDs (IIDs) in this subkey.

Each interface registered contains at least one of the following subkeys:

• NumMethods
  The NumMethods value should contain a zero-terminated string with a data value that is the number of methods contained in the interface.
• ProxyStubClsid32
  The ProxyStubClsid32 value should contain a zero-terminated string with a data value that is the CLSID of the proxy/stub shareable image. This CLSID should be the same as that described in Section 7.5.1.2.

As you develop and test COM components, you will find that the OpenVMS and Windows systems return seemingly indecipherable error codes. To help you make these codes more understandable, Compaq has included some ways to translate them.

7.6.1 NTA$VMSGetMessage

Compaq has included the NTA$VMSGetMessage routine to translate error codes into displayable text. The following section describes the NTA$VMSGetMessage routine.

To implement this routine, you must include the NTA_MESSAGE.H file in the DCOM$LIBRARY: directory and link with the DCOM$LIBRARY:NTA_GETMSG.OBJ object module.

The NTA$VMSGetMessage routine, described in the next section, translates error codes into displayable text. The input error code must be one of the following:

• An OpenVMS error code
• A Windows HRESULT
• A Windows Win32 error code
• A Windows NT status code set as "user defined"

The NTA$VMSGetMessage routine translates error codes into displayable text.

Format

Return=NTA$VMSGetMessage (status, text, flag, [count])

Arguments

status

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

This status field must be one of the following:

Input Error Code	Example
OpenVMS error code	0x074AA6BA
Windows HRESULT	0x80070031
Windows Win32 error code	0x00000031
Windows NT status code with the user-defined bit set	0xE74AA6BA

If the security API returns a Windows NT status code, the format of the status field is an OpenVMS status code OR'd with the Windows NT status control bits set. For example:

Input Error Code	Result
OpenVMS error code	0x074AA6BA
Windows NT status code	0xE74AA6BA

text

OpenVMS usage:	error_text
type:	character string
access:	write
mechanism:	by reference

This argument is a NULL terminated string that contains the returned text from the SYS$GETMSG system service. The maximum size returned (as defined by the SYS$GETMSG system service) is 256 bytes. To avoid overwriting memory, the caller must provide a buffer address of at least 257 bytes.

flag

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

Controls the translation of the error code. The following values are defined in NTA_MESSAGE.H:

NTAWIN$_UNKNOWN	Unknown error code
NTAWIN$_VMS	OpenVMS error code
NTAWIN$_NT	Windows HRESULT error code
NTAWIN$_WINDOWS	Windows Win32 error code
NTAWIN$_USER	Windows NT status code

If you provide the value NTAWIN$_UNKNOWN, the routine makes its best estimate as to the correct text. The routine parses the text as follows:

1. Check for a Windows HRESULT (high-order nibble = 0x8). If this check fails, go to the next step.
2. Check for a Windows NT user-defined status code (high-order nibble = 0xE). If this check fails, go to the next step.
3. Assume this is an OpenVMS error code.
   The system cannot tell the difference between an OpenVMS error code and a Windows Win32 error code.

count

OpenVMS usage:	FAO count
type:	longword (unsigned)
access:	write
mechanism:	by reference

This argument is the optionally returned FAO argument count in the returned message. Currently all NTAWIN messages use ASCII substitution arguments (!AS) only. The caller must convert all numeric data to ASCII before performing the substitution with SYS$FAO.

To call this routine, you must include the NTA_MESSAGE.H file in the DCOM$LIBRARY: directory and link with the SYS$LIBRARY:DCOM$WIN32_SHR shareable image.

Condition Values Returned

Any status from the SYS$GETMSG system service.

For more information about the SYS$GETMSG system service, see the OpenVMS System Services Reference Manual.

7.6.2 DCOM$TOOL SHOW ERROR

To use the DCOM$TOOL utility to convert the codes, use any of the following methods:

• Enter the following command to run the DCOM$TOOL utility:

  $ RUN SYS$SYSTEM:DCOM$TOOL.EXE

• Define a DCL symbol to use DCOM$TOOL and specify parameters on the command line. For example:

  $ DCOMTOOL :== $SYS$SYSTEM:DCOM$TOOL.EXE $ DCOMTOOL

• Use the MCR command to use DCOM$TOOL to parse the command line. For example:

  $ MCR DCOM$TOOL

You can specify parameters for any of these methods on the command line. Table 7-1 shows the DCOM$TOOL utility command line parameters. If you do not specify any parameters, the system prompts you for the required information.

Table 7-1 DCOM$TOOL Utility Command Line Parameters

Argument	Value	Required or Optional
P1	Command verb : SHOW	Required
P2	Command adjective : ERROR	Required
P3	Error code in DCL number format (%X)	Required
P4	Optional qualifers	Optional

The following example shows a typical DCOM$TOOL session to translate error codes:

$ DCOMTOOL :== $DCOM$TOOL.EXE $ DCOMTOOL SHOW ERROR %x80070005

7.6.2.1 DCOM$TOOL Optional Qualifiers

DCOM$TOOL accepts the following optional qualifiers:

• /VMS_ERROR
  This is a OpenVMS error code. An example of an OpenVMS error code is as follows:

  %x074AA6BA

• /HRESULT
  This is a Windows HRESULT. An example of a Windows HRESULT is as follows:

  %x80070031

• /WIN32
  This is a Win32 error code. An example of a Win32 error code is as follows:

  %x00000031

• /USER_DEFINED
  This is a Windows NT status code with the user-defined bit set. An example of a User Defined error code is as follows:

  %xE74AA6BA

Authentication is the act of verifying a user's identity by the computer system before permitting access to the system. After successfully authenticating a user, the system binds the user's authorization information to the user's process in the form of credentials. The system uses these credentials to determine whether to grant or deny access to system resources.

OpenVMS provides both native (SYSUAF-based) and Windows NT compatible authentication and authorization capabilities as follows:

• Native: The system performs authentication using password information stored in the SYSUAF.DAT file. Authorization information consists of UIC, privileges, and rights identifiers.
• Windows NT: The system performs authentication using password information stored in a SAM database managed by domain controllers. Authorization information consists of primary SID, group SIDs, session key, and privileges obtained from the user's account information in the SAM database.

After OpenVMS successfully authenticates a user (either native or Windows NT), OpenVMS attaches the user's native credentials to the process using a structure known as a persona. If the system used Windows NT for authentication, OpenVMS also attaches the user's Windows NT credentials to the process (as an extension to the persona).

8.2 Acquiring Windows NT Credentials Using NTA$LOGON

NTA$LOGON is a utility that allows you to acquire NTLM credentials. All processes that need Windows NT security to access the OpenVMS Registry or COM for OpenVMS facilities require NTLM credentials.

You must provide NTA$LOGON with a user account name, a password, and (if required) a domain name. NTA$LOGON uses the Authentication and Credential Management (ACM) Authority to contact the domain controller and acquire a Windows NT access token. NTA$LOGON merges the Windows NT information with the user's OpenVMS credentials.

For a detailed review of NTA$LOGON dependencies and a description of how NTA$LOGON interacts with other parts of the OpenVMS infrastructure, see Section 5.1 and Section 4.8 (especially the ACME server and Compaq Advanced Server for OpenVMS server).

To use the NTA$LOGON utility, you can enter any of the following:

• Enter the following command to run the NTA$LOGON utility:

  $ RUN SYS$SYSTEM:NTA$LOGON

  
  The system prompts you for a user account name and password.

• Define a DCL symbol to use NTA$LOGON to parse the command line. For example:

  $ NTLOGON :== $NTA$LOGON $ NTLOGON

• Use the MCR command to use NTA$LOGON to parse the command line. For example:

  $ MCR NTA$LOGON

You can specify parameters on the command line. Table 8-1 shows the NTA$LOGON utility command-line parameters. If you do not specify any parameters, the system prompts you for the required information.

Table 8-1 NTA$LOGON Utility Command Line Parameters

Argument	Value	Required/Optional
P1	User account name. If an account name is needed but was not specified on the command line, NTA$LOGON prompts for input.	Optional
P2	Password. If a password is needed but was not supplied on the command line, NTA$LOGON prompts for input (echoing suppressed).	Optional

Example 8-1 shows a typical NTA$LOGON session to acquire credentials.

Example 8-1 Sample NTA$LOGON Session

$ NTLOGON :== $NTA$LOGON $ NTLOGON joesmith Password:

NTA$LOGON accepts the following optional qualifiers:

• /DELETE
  Deletes the current Windows NT credentials.
  If you specify the /DELETE qualifier with the /WRITE_FILE qualifier, the system deletes the password record for the specified domain name and user account name from the file.
• /DOMAIN=name
  Specifies a domain name. This qualifier converts the name to uppercase. If you do not specify this qualifier, the system uses the default domain name.
• /LIST
  Lists the domain name and the user account name assigned to the current process.
  If you use the /LIST qualifier with the /READ_FILE or /WRITE_FILE qualifier, the system lists the contents of the file.
• /LOG
  Displays a message when an operation completes.
• /OVERRIDE_MAPPING
  Acquires Windows NT credentials for the specified Windows NT user account name even if the OpenVMS user name of the process does not match the OpenVMS user name associated with that Windows NT user account name in the domain controller.
  This qualifier requires the IMPERSONATE privilege.
• /READ_FILE [=file]
  This qualifier causes the system to search the binary input file created by the /WRITE_FILE qualifier for the specified domain name and user account name, instead of reading the password from the user input device. The /READ_FILE qualifier supports only binary files created by the NTA$LOGON/WRITE_FILE command.
  If the system finds a matching record, NTA$LOGON attempts to use that password to acquire Windows NT credentials.
  If you do not provide a file specification, the system uses the following default file specification:

  DCE$COMMON:[000000]NTA$LOGON.DAT

• /TYPE={BATCH | DIALUP | LOCAL | NETWORK | REMOTE}
  Specifies the rules under which access is to be granted or denied. If you do not specify this qualifier, the default is the type of the current process. This qualifier is usually used for detached processes (detached processes do not have a default type).
  This qualifier requires IMPERSONATE privilege.
• /WRITE_FILE [=file]
  This qualifier causes the system to write the specified domain name, user account name, and password into an output file to be used later (see the /READ_FILE qualifier), instead of using the user-supplied password.
  If you do not provide a file specification, the system uses the following default location and file name:

  DCE$COMMON:[000000]NTA$LOGON.DAT

  Caution The /READ_FILE and /WRITE_FILE qualifiers are intended to be used only by servers that have no other way to acquire Windows NT credentials to access the OpenVMS Registry or COM for OpenVMS facilities. Compaq does not recommend general use of the /READ_FILE and /WRITE_FILE qualifiers. Once you have written a password into a disk file, Compaq recommends you take strong precautions to protect the password file from unauthorized access.

	privacy and legal statement
6539PRO_008.HTML