Document revision date: 15 July 2002

Example 8-2 shows how a user acquires NT credentials for the first time.

Example 8-2 Acquiring Windows NT Credentials for the First Time

$ NTLOGON :== $NTA$LOGON $ NTLOGON/LIST ERROR: NtOpenProcessToken() failure: -1073741700 0xc000007c %SYSTEM-E-NOSUCHEXT, no such extension found $ NTLOGON/LOG JOESMITH [Persona #1 NT extension: Account= "JOESMITH" Domain= "NT_DOMAIN" ] Password:

Example 8-3 shows how the user replaces the Windows NT credentials.

Example 8-3 Replacing Windows NT Credentials

$ NTLOGON/DELETE $ NTLOGON/OVERRIDE_MAPPING/DOMAIN=OTHER_DOMAIN Username: janebrown Password:

Example 8-4 shows how a user saves a password in a disk file. The system requests that the user enter the password twice with echoing suppressed.

Example 8-4 Saving a Password to a File

$ NTLOGON :== $NTA$LOGON $ NTLOGON/WRITE_FILE=DEV:[DIR]NTA$LOGON.DAT COM_SERVER Password: Confirm: $ NTLOGON/READ_FILE=DEV:[DIR]NTA$LOGON.DAT/LIST File DEV:[DIR]NTA$LOGON.DAT contains the following records: 02-MAR-1999 16:57:23.20 COM_SERVER

After you have created this file, you can add the following to a DCL command procedure:

$ NTLOGON :== $NTA$LOGON $ NTLOGON/READ_FILE=DEV:[DIR]NTA$LOGON.DAT COM_SERVER

8.3 The Authentication and Credential Management (ACM) Authority

The Authentication and Credential Management authority authenticates users and determines the user security profile for OpenVMS and Windows NT. The ACME_SERVER process provides these ACM services. The ACME_SERVER process uses plug-in modules called ACME agents. ACME agents perform the actual work of responding to authentication requests, query requests, and event requests.

The OpenVMS ACME agent (VMS$VMS_ACMESHR.EXE) provides OpenVMS native services. The MSV1_0 ACME agent (PWRK$MSV1_0_ACMESHR.EXE, an Compaq Advanced Server for OpenVMS product component) provides Windows NT connectivity services.

The MSV1_0 ACME agent forwards Windows NT connectivity service requests from NTA$LOGON and SSPI/NTLM to an Compaq Advanced Server for OpenVMS process running on one or more systems in the cluster. The PWRK$ACME_SERVER logical name can contain a comma-delimited list of cluster node names to which the MSV1_0 ACME can forward requests. Running the Compaq Advanced Server for OpenVMS process on more than one cluster node and including the node names in the PWRK$ACME_SERVER logical name allows the MSV1_0 ACME agent to fail over a request automatically if a connection is interrupted. If the logical name is undefined, the system defaults to the local machine name.

The ACME_SERVER process must be present on any system running RPC or COM for OpenVMS. However, the Compaq Advanced Server for OpenVMS process needs to be present on only one node in the cluster.

8.3.1 Windows NT Authentication on OpenVMS

Because the ACME_SERVER returns to its callers a complete OpenVMS persona with the requested attached Windows NT persona extension, the VMS ACME agent enforces the following rules:

• Every Windows NT user must be mapped to a local OpenVMS user name.
  The MSV1_0 ACME provides this mapping through the Compaq Advanced Server for OpenVMS HOSTMAP database.
• The mapped OpenVMS user name must be a valid (and not disabled) account in the SYSUAF.DAT. The account's access restrictions must allow access during the specified days and times. COM for OpenVMS and RPC typically require NETWORK access during authentication.
• The mapped OpenVMS user name must be an account with the EXTAUTH flag set. EXTAUTH allows the system manager fine control over which OpenVMS accounts can be used for mapping. You can use the IGNORE_EXTAUTH bit (bit number 11 [decimal]) in the SECURITY_POLICY system parameter to override this per-account feature. If you set the IGNORE_EXTAUTH bit to 1, OpenVMS allows you to map to any account, regardless of the account's EXTAUTH setting. Note that the IGNOTE_EXTAUTH is used only for the ACME_SERVER and is ignored by Loginout.

To start the ACME_SERVER process and configure the MSV1_0 ACME agent at system startup, add the following entry to SYLOGICALS.COM:

$ DEFINE NTA$NT_ACME_TO_BE_STARTED YES

You can also start the ACME_SERVER process manually using the following startup command file:

$ @SYS$STARTUP:NTA$STARTUP_NT_ACME

To shut down ACME_SERVER, enter the following command:

$ SET SERVER ACME/EXIT

If an abnormal condition in an ACME agent prevents a normal server shutdown, use the /ABORT qualifier in the place of the /EXIT qualifier to force the ACME_SERVER to terminate.

To turn on ACME_SERVER logging, enter the following command:

$ SET SERVER ACME/LOG

This command creates a ACME$SERVER.LOG file in the SYS$MANAGER directory. You might find this file useful when you are trying to diagnose potential problems.

To display the ACME_SERVER configuration information, enter the following command:

$ SHOW SERVER ACME[/FULL]

8.3.3 Configuring the MSV1_0 ACME Agent

Table 8-2 lists and describes systemwide logical names you can use to control certain features of the MSV1_0 ACME agent.

Table 8-2 MSV1_0 ACME Agent Logical Names

Logical name	Description
PWRK$ACME_SERVER	Comma-delimited list of cluster SCS node names that are running Compaq Advanced Server for OpenVMS processes that can service Windows NT connectivity requests. If you do not define the node names, the MSV1_0 ACME agent tries to connect to the Compaq Advanced Server for OpenVMS process on the local system.
PWRK$ACME_RETRY_COUNT	The maximum number of retry attempts the MSV1_0 ACME agent performs when connecting to an Compaq Advanced Server for OpenVMS process. The default value is 10.
PWRK$ACME_RETRY_INTERVAL	The number of tenths of seconds between retry attempts. The default is 2.5 seconds.

ATL (Active Template Library) is a set of template-based C++ classes from Microsoft that simplify the development of COM components. ATL provides support for key COM features, such as stock implementations of IUnknown, IClassFactory, IDispatch, dual interfaces, and connection points. It also provides support for more advanced COM features, such as enumerator classes and tear-off interfaces.

The ATL COM AppWizard and ATL Object Wizard in Microsoft Visual Studio can be used to quickly create code for simple COM objects that can be copied to OpenVMS systems and built with very few modifications.

The COM for OpenVMS ATL is based on Microsoft ATL Version 3.0. You must be running COM Version 1.1-B for OpenVMS or higher. ATL on OpenVMS Alpha Version 7.2-1 requires Compaq C++ Version 6.2-016 or higher.

COM for OpenVMS provides ATL as source code in header files that you include in your application.

Table 9-1 shows the differences between the ATL implementation on Windows NT and OpenVMS.

Table 9-1 ATL Implementation Differences

Implementation	Windows NT	OpenVMS
Interface	GUI	Character cell
Server models	Single threaded or multithreaded	Multithreaded only
ATL available as DLL	Yes (not required)	No
Application registration	Automatic using UpdateRegistryFromResource function in ATLBASE.H	Automatic using UpdateRegistryFromFile function in ATLBASE.H
ATL component types	In process as DLL Out of process as EXE	In process as shareable image Out of process as an executable image

9.2 Developing a COM for OpenVMS Application Using ATL

The following sections describe how to create a COM for OpenVMS application using ATL.

9.2.1 Step 1: Create the ATL Component in Microsoft Visual Studio

Generate the code using the Microsoft Visual Studio ATL COM AppWizard. For information about using the ATL COM AppWizard, see the Microsoft Developer Network (MSDN) documentation.

Copy the generated files to OpenVMS. For example, copy the files using File Transfer Protocol (FTP) in ASCII mode. Table 9-2 lists and describes the files that the ATL COM AppWizard would generate for a project named mycomapp .

Table 9-2 Files Generated by ATL COM AppWizard for mycomapp

File name	Description	Platform	In Process or Out of Process
mycomapp.cpp	Contains the implementation of DllMain, DllCanUnloadNow, DllGetClassObject, DllRegisterServer and DllUnregisterServer. Also contains the object map, which is a list of the ATL objects in your mycomapp . This is initially blank, because you have not created an object yet.	Windows NT/OpenVMS	Both
mycomapp.def	The standard Windows module definition file for the DLL. Note: MYCOMAPP.DEF becomes MYCOMPAP$SHR.OPT on OpenVMS.	Windows NT	In process
mycomapp.dsw	The mycomapp workspace.	Windows NT	Both
mycomapp.dsp	The file that contains the mycomapp settings.	Windows NT	Both
mycomapp.idl	The interface definition language file, which describes the interfaces specific to your objects.	Windows NT/OpenVMS	Both
mycomapp.rc	The resource file, which initially contains the version information and a string containing the mycomapp name.	Windows NT	Both
Resource.h	The header file for the resource file.	Windows NT/OpenVMS	Both
mycomappps.mk	The make file that can be used to build a proxy/stub DLL. You do not need this file.	Windows NT	Proxy/stub
mycomapps.def	The module definition file for the proxy/stub DLL. Note: MYCOMAPPPS.DEF becomes MYCOMAPPPS$SHR.OPT on OpenVMS.	Windows NT	Proxy/stub
StdAfx.cpp	The file that will include the ATL implementation files.	Windows NT/OpenVMS	Both
StdAfx.h	The file that will include the ATL header files. To make the mycomapp DLL useful, you need to add a control, using the ATL Object Wizard.	Windows NT/OpenVMS	Both
mycomapp.rgs	A registrar script for your COM server.	Windows NT/OpenVMS	Both
myinterface.rgs	A registrar script for your COM server.	Windows NT/OpenVMS	Both
myinterface.cpp	The interfaces specific to your object.	Windows NT/OpenVMS	Both
myinterface.h	The header file for the interfaces.	Windows NT/OpenVMS	Both

9.2.2 Step 2: Modify Generated Files for ATL Applications on OpenVMS

Make the following changes to the generated files before you build ATL applications on OpenVMS.

9.2.2.1 Remove _ATL_MIN_CRT

When the ATL COM AppWizard generates mycomapp , it also defines the macro _ATL_MIN_CRT as part of the GUI support. Because OpenVMS does not have a graphical interface, you must remove (or not define) _ATL_MIN_CRT when you build on OpenVMS.

9.2.2.2 Include ATLMAIN.CXX

On OpenVMS, you must include ATLMAIN.CXX for out of process components. ATLMAIN.CXX defines the wWinMain() function.

9.2.2.3 Modify Registration Procedure

OpenVMS does not support registering the application using the UpdateRegistryFromResource function; rather, you must use the OpenVMS UpdateRegistryFromFile function in the ATLBASE.H header file. You must make the following changes to your application:

File to search	Search for	Replace with
Interface header file	DECLARE_REGISTRY_RESOURCEID	DECLARE_REGISTRY_FILE
Project source file	_Module.UpdateRegistryFromResource	_Module.UpdateRegistryFromFile

The following example shows sample coding changes:

#ifdef __vms DECLARE_REGISTRY_FILE(_T("MYINTERFACE.RGS")) #else DECLARE_REGISTRY_RESOURCEID(IDR_MYINTERFACE) #endif #ifdef __vms _Module.UpdateRegistryFromFile(_T_"MYCOMAPP.RGS"), TRUE); #else _Module.UpdateRegistryFromResource(IDR_MYCOMPAPP, TRUE); #endif

9.2.3 Step 3: Build an Application Using the MIDL Compiler

This process is the same as the one shown in Section 7.2.

In-process example:

$ MIDL :== $DCOM$MIDL.EXE $ MIDL -nologo -Oicf mycompapp.idl - -IDCOM$LIBRARY - -iid mycompapp_i.cxx - -proxy mycompapp_p.cxx - -dlldata dlldata.cxx - -tlb mycompapp$shr.tlb

Out-of-process example:

$ MIDL :== $DCOM$MIDL.EXE $ MIDL -nologo -Oicf mycompapp.idl - -IDCOM$LIBRARY - -iid mycompapp_i.cxx - -proxy mycompapp_p.cxx - -dlldata dlldata.cxx - -tlb mycompapp.tlb

Compaq recommends that the name of your type library match the name of your executable or shareable image.

9.2.4 Step 4: Compile the ATL COM Application

The following sections describe how to compile COM for OpenVMS applications.

9.2.4.1 Required Header File: ATLBASE.H

The VMS_ATL.H header file defines several macros used by the Wind/U header files. VMS_ATL.H is already included in the ATLBASE.H header file. When you create ATL source code, you must include ATLBASE.H as the first noncommented line in your source (both header and implementation) files.

9.2.4.2 Required Macro Definitions

Include the following /DEFINE qualifier on all of your CXX commands:

/DEFINE=(UNICODE=1,_WINDU_SOURCE=0X041000,_WIN32_DCOM,_ATL_STATIC_REGISTRY)

The UNICODE macro ensures that wide-character variants of Win32 APIs and data structures are enabled when you compile. (The UNICODE macro is also defined in VMS_DCOM.H.) If you omit the UNICODE macro, your compile will fail when you build using the Wind/U Win32 environment.

The other two macro definitions are recognized by the Wind/U header files and are required to ensure the proper definition of structures and COM APIs.

The _ATL_STATIC_REGISTRY macro enables you to statically link with the ATL registry component ( Registrar ) for optimized registry access. You can add the macro either by including the /DEFINE qualifier on the command line or by adding the stdafx.h header file to your code.

9.2.4.3 Required Include Directories

COM for OpenVMS applications typically require header files that come from DCOM$LIBRARY . The ATL header files and source files are also located in DCOM$LIBRARY .

Include the following qualifier on your CXX command lines:

/INCLUDE=DCOM$LIBRARY

If you already have an /INCLUDE qualifier on your command line, modify the command to include DCOM$LIBRARY .

9.2.4.4 Required C++ Qualifiers

You must specify the following C++ qualifiers when you build COM for OpenVMS applications:

• /EXCEPTIONS=CLEANUP
  Specify the /EXCEPTIONS=CLEANUP qualifier on C++ commands to enable C++ exceptions.
• /STANDARD=MS
  The C++ compiler supports many different compilation standards. You must use /STANDARD=MS for COM applications created by ATL.
  /STANDARD=MS informs the compiler that it should follow the language constructs supported by the Visual C++ compiler. This switch works well with the code generated by ATL.
• /TEMPLATE_DEFINE=(NOALL,NOPRAGMA)
  This switch controls the instantiation of C++ templates. You must specify the following options:
  • [NO]ALL
    Instantiate all function template entities declared or referenced in the compilation unit, including typedefs. For each fully instantiated template class, all its member functions and static data members are instantiated even if they were not used. Nonmember template functions are instantiated even if the only reference was a declaration. Instantiations are created with external linkage. Overrides /REPOSITORY at compile time. The compiler places instantiations in the user's object file. The template definition must be present before the point of each instantiation in the source file.
    The default is /TEMPLATE_DEFINE=NOALL .
  • [NO]PRAGMA
    Determines whether the C++ compiler ignores #PRAGMA DEFINE_TEMPLATE directives encountered during the compilation. This option lets you quickly switch to automatic instantiation without having to remove all the pragma directives from your program's code base.
    The default is /TEMPLATE_DEFINE=PRAGMA , which enables #PRAGMA DEFINE_TEMPLATE .

To build a COM for OpenVMS application, you must build both client and component images. Because you can implement a component as either an in process component or an out of process component, you must build a shareable image or an executable image, or both.

The following sections describe the steps you must follow to link the client, component, and proxy/stub images.

	privacy and legal statement
6539PRO_009.HTML