| Previous | Contents | Index |
This chapter explains how to develop COM applications for OpenVMS.
The following sections describe how to create a COM for OpenVMS application.
Building COM for OpenVMS applications places demands on the virtual memory requirements of a process. You should have a minimum page file quota of 100,000 pagelets before building a COM for OpenVMS application. This is a HP C++ compiler requirement. |
Use the DCOM$GUIDGEN utility to generate 16-byte globally unique identifiers (GUIDs).
For example:
$ SET COMMAND DCOM$LIBRARY:DCOM$GUIDGEN.CLD $ DCOM$GUIDGEN [/FORMAT=value] - _$ [/COUNT=value] [/OUTPUT=value] |
The following table summarizes the GUID format options.
| OpenVMS qualifier (value) | UNIX switch | Use |
|---|---|---|
| IDL | -i | Output GUID in an IDL interface template. |
| STRUCT | -s | Output GUID as an initialized C struct. |
| IMPLEMENT_OLECREATE | -c | Output GUID in IMPLEMENT_OLECREATE(...) format. |
| DEFINE_GUID | -d | Output GUID in DEFINE_GUID(...) format. |
| GUID_STRUCT | -g | Output GUID as an initialized static const GUID struct. |
| REGISTRY_GUID | -r | Output GUID in registry format. |
The last four options in the preceding table are the same as the four options in the Windows Guidgen utility. |
The following table lists additional options supported by the DCOM$GUIDGEN utility.
| OpenVMS qualifier | UNIX switch | Use |
|---|---|---|
| /OUTPUT= filename | -o filename | Redirect output to a specified file. |
| /COUNT= number | -n number | Number of GUIDs to generate. |
| not available | -h , -? | Display command option summary. |
You can specify more than one format for the same GUID.
7.2 Step 2: Build an Application Using the MIDL Compiler
The following sections describe how to use the MIDL compiler to build
an application.
7.2.1 Running the MIDL Compiler
The MIDL compiler consists of the following separate images:
To run MIDL, you must first define a DCL symbol. For example:
$ midl :== $dcom$midl
$ midl -?
$ midl -Oicf -idcom$library: example.idl
|
The
midl -?
command displays a list of valid command-line arguments. For a list of
these arguments, see Appendix A.
7.2.2 Running the MIDL Compiler with DCOM$RUNSHRLIB
The DCOM$MIDL.EXE utility gets its arguments from the DCL foreign command-line buffer. DCL foreign commands can have a maximum of 255 characters.
Because of the number of arguments that DCOM$MIDL.EXE can accept, you might exceed this maximum number of characters if you specify a complex MIDL command (for example, a command that contains mixed-case arguments that require quotation marks).
As a workaround, you can use the SYS$SYSTEM:DCOM$RUNSHRLIB.EXE utility. Use the following procedure:
$ SET COMMAND DCOM$LIBRARY:DCOM$RUNSHRLIB.CLD |
| Argument | Value | Required/Optional |
|---|---|---|
| P1 | Name of the shareable image library. This can be a logical name, the name of an image in SYS$SHARE: , or a full file specification. | Required |
| P2 | Name of the routine to be called as a C or C++ main() routine with an argc/argv vector. | Required |
| P3 | List of qualifiers, in quotation marks. | Optional |
$ midl :== DCOM$RUNSHRLIB DCOM$MIDL_SHR DCOM$MIDL_MAIN |
$ midl :== $dcom$midl
$ midl -Zp8 -Oicf -Os -oldnames -char unsigned -
-error allocation -error bounds_check -error stub_data -
-ms_ext -c_ext -out [.OBJ] -
-I[INC] -I[PROJECT_WIDE_INC] -I[COMMON_INC] -IDCOM$LIBRARY: -
-DRMS_DB "-DOpenVMS_Definitions" "-DPermanentProcess" -
-header [.obj]example.h -client none -server none example.idl
%DCL-W-TKNOVF, command element is too long - shorten
|
$ set command dcom$library:dcom$runshrlib.cld
$ midl :== DCOM$RUNSHRLIB DCOM$MIDL_SHR DCOM$MIDL_MAIN
$ midl "-Zp8 -Oicf -Os -oldnames -char unsigned",-
"-error allocation -error bounds_check -error stub_data",-
"-ms_ext -c_ext -out [.OBJ]",-
"-I[INC] -I[PROJECT_WIDE_INC] -I[COMMON_INC] -IDCOM$LIBRARY:",-
"-DRMS_DB -DOpenVMS_Definitions -DPermanentProcess",-
"-header [.obj]example.h -client none -server none example.idl"
|
By default, the MIDL compiler included in COM for OpenVMS generates IDL files with a .CXX extension. If you previously specified names for the generated files in your MIDL command and want to use the COM for OpenVMS MIDL compiler changes, you need to update your command line.
For example, if you previously generated IDL files with the following command:
MIDL -Oicf server.idl -IDCOM$LIBRARY: -dlldata DLLDATA.C |
Change your command to the following:
MIDL -Oicf server.idl -IDCOM$LIBRARY: -dlldata DLLDATA.CXX |
If you want to continue to use the C compiler to build your generated files, simply specify them as .C files on your command line.
If you previously accepted the default file names, and want to continue to use the C compiler to build the IDL files, you must specify every IDL file on the command line. |
For example, if your MIDL command was similar to the following:
MIDL -Oicf server.idl -IDCOM$LIBRARY: -dlldata DLLDATA.C |
Change it to the following:
MIDL -Oicf server.idl -IDCOM$LIBRARY: -dlldata DLLDATA.C -guids
GUIDS.C -proxy SERVER_P.C
|
When running MIDL on OpenVMS, you must specify the
-Oicf
MIDL command-line switch.
7.2.5 Required Include Directories
MIDL components typically import UNKNWN.IDL , which contains the component definitions for IUnknown and IClassFactory . UNKNWN.IDL and other COM-related IDL and header files are located in DCOM$LIBRARY . To build your component's IDL file, use the following switch:
-IDCOM$LIBRARY: |
The following sections describe how to compile COM for OpenVMS applications.
COM application developers need access to the OpenVMS Registry to register and control access to a given application. For more information about OpenVMS Registry privileges, see Section 12.6.1 and Section 6.3. |
The VMS_DCOM.H header file contains macro definitions that enable your COM for OpenVMS application to compile properly. You must include this header file as the first uncommented line in every source file and header file you create.
The MIDL compiler for OpenVMS includes VMS_DCOM.H in all output files
that it generates.
7.3.2 Required Macro Definitions
Be sure to always include the following /DEFINE qualifier in all of your CXX commands:
/DEFINE=(UNICODE,_WIN32_DCOM) |
The UNICODE macro ensures that the wide character variants of Win32 APIs and data structures are enabled when you compile your code. (This macro is also defined in VMS_DCOM.H .)
The _WIN32_DCOM macro definition is recognized by the header files and
is required to ensure the proper definition of structures and COM APIs.
7.3.3 Required Include Directories
COM for OpenVMS applications typically require header files that come from DCOM$LIBRARY .
Include the following qualifier in your C and CXX commands:
/INCLUDE=DCOM$LIBRARY |
If you already have an
/INCLUDE
qualifier in your command line, modify the command to include
DCOM$LIBRARY
.
7.3.4 Required C++ Qualifiers
You must specify the following C++ qualifiers when you build COM for OpenVMS applications:
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 either a shareable image or an executable image, or both. If you are creating a new interface, you must also build a proxy/stub shareable image, unless you are using the IDispatch interface. In that case, the Automation Marshaler will be used instead of the proxy/stub shareable image. The proxy/stub shareable image provides an interface-specific object that packages parameters for that interface in preparation for a remote method call. A proxy runs in the sender's address space and communicates with a corresponding stub in the receiver's address space.
The following sections describe the steps you must follow to link the
client, component, and proxy/stub images.
7.4.1 Linking the Client and the Out-of-Process Component
Although you do not need to specify any qualifiers to link the client or the component executable images, you must link both images with the DCOM OLE32 shareable image (to satisfy references to COM APIs).
The specific link-time dependency is DCOM$LIBRARY:DCOM.OPT .
If you have one or more C++ modules, use the C++ linker (CXXLINK) instead of the standard OpenVMS linker so you can specify the location of your C++ repository (/CXX_REPOSITORY qualifier). For example:
$ CXXLINK/your-specific-linker-qualifiers list-of-object-modules, - _$ DCOM$LIBRARY:DCOM.OPT/OPTIONS - _$ application.OPT/OPTIONS /REPOSITORY=[.CXX_REPOSITORY] |
Other ways of including the options file are as follows:
The specific link-time dependency is
DCOM$LIBRARY:DCOM.OPT
.
7.4.2.1 Creating a Symbol Vector
Linking the in-process component shareable image requires that you create a symbol vector for the entry points that COM for OpenVMS expects to call within the shareable image. The Win32 run-time environment enforces a naming standard on the DllMain entry point, which must contain the following:
For example, a component shareable image with the name CMPNT$SHR would define the symbol vector using the following options file:
!
! The list of symbols exported by CMPNT$SHR.EXE.
!
SYMBOL_VECTOR=(-
_DllMain_CMPNT$/DllMain = PROCEDURE,-
DllGetClassObject = PROCEDURE,-
DllCanUnloadNow = PROCEDURE,-
DllRegisterServer = PROCEDURE,-
DllUnregisterServer = PROCEDURE)
|
A component shareable image with the name CMPNT_SHARE would define the symbol vector using the following options file:
!
! The list of symbols exported by CMPNT_SHARE.EXE.
!
SYMBOL_VECTOR=(-
_DllMain_CMPNT_SHARE/DllMain = PROCEDURE,-
DllGetClassObject = PROCEDURE,-
DllCanUnloadNow = PROCEDURE,-
DllRegisterServer = PROCEDURE,-
DllUnregisterServer = PROCEDURE)
|
The specific link-time dependency is
SYS$LIBRARY:DCOM$RPCRT4_SHR.EXE
.
7.4.3.1 Creating a Symbol Vector
Linking the proxy/stub shareable image is more involved because you must create a symbol vector for the entry points that COM for OpenVMS expects to call within the shareable image. The Win32 run-time environment enforces a naming standard on the DllMain entry point, which must contain the following:
For example, a proxy/stub shareable image with the name PROXY$SHR would define the symbol vector using the following options file:
!
! RPC Shareable Image
!
SYS$LIBRARY:DCOM$RPCRT4_SHR.EXE/SHARE
!
!
! The list of symbols exported by PROXY$SHR.EXE.
!
SYMBOL_VECTOR=(-
_DllMain_PROXY$/DllMain = PROCEDURE,-
DllGetClassObject = PROCEDURE,-
DllCanUnloadNow = PROCEDURE,-
GetProxyDllInfo = PROCEDURE,-
DllRegisterServer = PROCEDURE,-
DllUnregisterServer = PROCEDURE)
|
A proxy/stub shareable image with the name PROXY_SHARE would define the symbol vector using the following options file:
!
! RPC Shareable Image
!
SYS$LIBRARY:DCOM$RPCRT4_SHR.EXE/SHARE
!
!
! The list of symbols exported by PROXY_SHARE.EXE.
!
SYMBOL_VECTOR=(-
_DllMain_PROXY_SHARE/DllMain = PROCEDURE,-
DllGetClassObject = PROCEDURE,-
DllCanUnloadNow = PROCEDURE,-
GetProxyDllInfo = PROCEDURE,-
DllRegisterServer = PROCEDURE,-
DllUnregisterServer = PROCEDURE)
|
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:
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:
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:
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:
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, HP has included some
ways to translate them.
7.6.1 NTA$VMSGetMessage
HP 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:
The NTA$VMSGetMessage routine translates error codes into displayable text.
Return=NTA$VMSGetMessage (status, text, flag, [count])
Description This routine uses the OpenVMS SYS$GETMSG system service. The messages are stored in the SYS$MESSAGE:NTAWINMSG.EXE and SYS$MESSAGE:NTARPCMSG.EXE images.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 status code with the user-defined bit set 0xE74AA6BA If the security API returns a Windows status code, the format of the status field is an OpenVMS status code OR'd with the Windows status control bits set. For example:
Input Error Code Result OpenVMS error code 0x074AA6BA Windows 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 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:
- Check for a Windows HRESULT (high-order nibble = 0x8). If this check fails, go to the next step.
- Check for a Windows user-defined status code (high-order nibble = 0xE). If this check fails, go to the next step.
- 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.
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
HP has included command-line syntax to convert error codes into
displayable text. The following section describes the DCOM$TOOL SHOW
ERROR syntax.
To use the DCOM$TOOL utility to convert the codes, use any of the following methods:
$ RUN SYS$SYSTEM:DCOM$TOOL.EXE |
$ DCOMTOOL :== $SYS$SYSTEM:DCOM$TOOL.EXE $ DCOMTOOL |
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.
| 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 |
DCOM$TOOL accepts the following optional qualifiers:
%x074AA6BA |
%x80070031 |
%x00000031 |
%xE74AA6BA |
The DCOM$TOOL utility SHOW ERROR feature follows the rules, restrictions, and guidelines of the OpenVMS Message Utility. For more information, see the OpenVMS Command Definition, Librarian, and Message Utilities Manual. |
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 compatible authentication and authorization capabilities as follows:
After OpenVMS successfully authenticates a user (either native or
Windows), OpenVMS attaches the user's native credentials to the
process using a structure known as a persona. If the system
used Windows for authentication, OpenVMS also attaches the user's
Windows credentials to the process (as an extension to the
persona).
8.2 Acquiring Windows Credentials Using NTA$LOGON
NTA$LOGON is a utility that allows you to acquire NTLM credentials. All processes that need Windows 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 access token. NTA$LOGON merges the Windows 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.10 (especially the ACME server and HP Advanced Server for OpenVMS server).
To use the NTA$LOGON utility, you can enter any of the following:
$ RUN SYS$SYSTEM:NTA$LOGON
|
$ NTLOGON :== $NTA$LOGON
$ NTLOGON
|
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.
| 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:
|
Windows domain names and user account names are not case sensitive. NTA$LOGON converts all domain names and user account names to uppercase. If you specify a password on the command line, DCL converts all characters to uppercase, unless you enclose the password in quotation marks (""). |
NTA$LOGON accepts the following optional qualifiers:
DCE$COMMON:[000000]NTA$LOGON.DAT
|
If you are running COM on OpenVMS Version 7.3-2 or higher, the /TYPE=BATCH qualifer is not supported, and the IMPERSONATE privilege is not required. |
DCE$COMMON:[000000]NTA$LOGON.DAT
|
The /READ_FILE and /WRITE_FILE qualifiers are intended to be used only by servers that have no other way to acquire Windows credentials to access the OpenVMS Registry or COM for OpenVMS facilities. HP does not recommend general use of the /READ_FILE and /WRITE_FILE qualifiers. Once you have written a password into a disk file, HP recommends you take strong precautions to protect the password file from unauthorized access. |
Example 8-2 shows how a user acquires NT credentials for the first time.
| Example 8-2 Acquiring Windows 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 credentials.
| Example 8-3 Replacing Windows 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
|
The Authentication and Credential Management authority authenticates users and determines the user security profile for OpenVMS and Windows. 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 HP Advanced Server for OpenVMS product component) provides Windows connectivity services.
The MSV1_0 ACME agent forwards Windows connectivity service requests from NTA$LOGON and SSPI/NTLM to an HP 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 HP 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 HP Advanced Server for OpenVMS process needs to be present
on only one node in the cluster.
8.3.1 Windows Authentication on OpenVMS
Because the ACME_SERVER returns to its callers a complete OpenVMS persona with the requested attached Windows persona extension, the VMS ACME agent enforces the following rules:
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] |
Table 8-2 lists and describes systemwide logical names you can use to control certain features of the MSV1_0 ACME agent.
| Logical name | Description |
|---|---|
| PWRK$ACME_SERVER | Comma-delimited list of cluster SCS node names that are running HP Advanced Server for OpenVMS processes that can service Windows connectivity requests. If you do not define the node names, the MSV1_0 ACME agent tries to connect to the HP 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 HP 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 or higher for OpenVMS. ATL on OpenVMS Alpha 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 and OpenVMS.
| Implementation | Windows | 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 |
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 .
| 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/OpenVMS | Both |
| mycomapp.def |
The standard Windows module definition file for the DLL.
Note: MYCOMAPP.DEF becomes MYCOMPAP$SHR.OPT on OpenVMS. |
Windows | In process |
| mycomapp.dsw | The mycomapp workspace. | Windows | Both |
| mycomapp.dsp | The file that contains the mycomapp settings. | Windows | Both |
| mycomapp.idl | The interface definition language file, which describes the interfaces specific to your objects. | Windows/OpenVMS | Both |
| mycomapp.rc | The resource file, which initially contains the version information and a string containing the mycomapp name. | Windows | Both |
| Resource.h | The header file for the resource file. | Windows/OpenVMS | Both |
| mycomappps.mk | The make file that can be used to build a proxy/stub DLL. You do not need this file. | Windows | Proxy/stub |
| mycomapps.def |
The module definition file for the proxy/stub DLL.
Note: MYCOMAPPPS.DEF becomes MYCOMAPPPS$SHR.OPT on OpenVMS. |
Windows | Proxy/stub |
| StdAfx.cpp | The file that will include the ATL implementation files. | Windows/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/OpenVMS | Both |
| mycomapp.rgs | A registrar script for your COM server. | Windows/OpenVMS | Both |
| myinterface.rgs | A registrar script for your COM server. | Windows/OpenVMS | Both |
| myinterface.cpp | The interfaces specific to your object. | Windows/OpenVMS | Both |
| myinterface.h | The header file for the interfaces. | Windows/OpenVMS | Both |
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
|
Beginning in OpenVMS Version 7.3-2, HP no longer supports the PostThreadMesssage, GetMessage and DispatchMessage calls that are generated by the ATL COM AppWizard for out of process components.
The same functionality can be achieved by replacing these calls with the event-handling functions CreateEvent, SetEvent, and WaitForSingleObject. Refer to the source code for TESTATL.CXX in DCOM$EXAMPLES:[TESTATL_OUTPROC] for more information.
The following example shows some of the sample coding changes
#ifdef __vms
SetEvent(hMsg);
#else
PostThreadMessage(dwThreadID, WM_QUIT, 0, 0);
#endif
#ifdef __vms
WaitForSingleObject(hMsg, INFINITE);
#else
MSG msg;
while (GetMessage(&msg, 0, 0, 0))
DispatchMessage(&msg);
#endif
|
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
|
HP 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 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,_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.)
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:
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.
9.2.5.1 Linking the Client and the Out of Process Component
Although you do not need to specify any qualifiers to link the client or the component executable images, you must link both images. The specific link-time dependency is as follows:
If you have one or more C++ modules, use the C++ linker (CXXLINK) instead of the standard OpenVMS linker so you can specify the location of your C++ repository (/CXX_REPOSITORY qualifier). For example:
$ CXXLINK/your-specific-linker-qualifiers list-of-object-modules, - _$ DCOM$LIBRARY:DCOM.OPT/OPTIONS, application.OPT/OPTIONS - _$ /REPOSITORY=[.CXX_REPOSITORY] |
You can also include the list of object modules in an options file
instead of on the command line.
9.2.5.2 Linking the In Process Component Shareable Image
The in process component shareable image dependency list differs slightly from that of the client and component executables. The specific link-time dependencies are as follows:
To create a symbol vector for the in process component shareable image, use the procedure described in Section 7.4.2.1.
To create a symbol vector for the proxy/stub shareable image, use the
procedure described in Section 7.4.3.
9.3 ATL Samples
TESTATL is an out of process sample, and MATH101 is an in process sample.
You can find the sample ATL applications shown in this chapter in the following directories on the COM for OpenVMS kit:
DCOM$EXAMPLES:[TESTATL_OUTPROC] DCOM$EXAMPLES:[TESTATL_INPROC] |
If you are running authenticated COM, before you build the application on OpenVMS you must run NTA$LOGON and acquire Windows credentials. For more information, see Section 8.2. |
This sample implements a COM client and server in which the component provides one interface: ISum .
Given sources initially generated by the Microsoft Visual Studio ATL AppWizard and a few applied changes, the sample demonstrates the build, registration, and execution of the ATL application on OpenVMS.
The following sections describe how to create the application using the
Microsoft ATL AppWizard on Windows and how to build the
application on an OpenVMS system.
9.3.1.1 Creating the Application on Windows
To generate a skeleton project and simple objects using the Microsoft Visual Studio ATL AppWizard, follow these steps:
A README file describes how to build, register, and run this COM for OpenVMS sample. The file is located in:
DCOM$EXAMPLES:[TESTATL_OUTPROC]README-TESTATL_OUTPROC.TXT |
This sample implements a COM client and server in which the component provides three interfaces: ISum, IDiv, and IMul.
Given sources initially generated by the Microsoft Visual Studio ATL AppWizard, the sample demonstrates the build, registration, and execution of the shareable application on an OpenVMS system.
The following sections describe how to build the application.
9.3.2.1 Creating the Application on Windows
To generate a skeleton project and simple objects using the Microsoft Visual Studio ATL AppWizard, follow these steps:
A README file describes how to build, register, and run this COM for OpenVMS sample. The file is located in:
DCOM$EXAMPLES:[TESTATL_INPROC]README-TESTATL_INPROC.TXT |
The following resources provide more information about ATL:
www.microsoft.com/com |
| Previous | Next | Contents | Index |