Compaq DCE for OpenVMS VAX and OpenVMS Alpha

Document revision date: 5 July 2000

Compaq DCE for OpenVMS VAX and OpenVMS Alpha
Product Guide

Contents

Index

6.4 Library Images

Following installation on an OpenVMS VAX or OpenVMS Alpha system, all DCE library images reside in the SYS$LIBRARY directory. On a Tru64 UNIX system, these images reside in /usr/lib.

Table 6-4 lists the names of the library images on OpenVMS VAX and OpenVMS Alpha systems and the names of equivalent library images on an Tru64 UNIX system.

Table 6-4 DCE Library Images for OpenVMS and Tru64 UNIX
OpenVMS Filename Tru64 UNIX Equivalent

DCE$IDL_CXX_SHR.EXE NONE

DCE$KERNEL.EXE NONE

DCE$LGI_CALLOUTS.EXE NONE

DCE$LIB_SHR.EXE libdce.a

DCE$SOCKSHR_IP.EXE NONE

DCE$SOCKSHR_DNET_IV.EXE NONE

DTSS$SHR.EXE NONE

DTSS$RUNDOWN.EXE NONE

DXD$CDS_SHR.EXE NONE

DCE$NSEDIT_SHR.EXE NONE

DCE$SOCKSHR_DNET_OSI.EXE NONE

DCE$SOCKSHR_TPS.EXE NONE

DCE$UAF_SHR.EXE NONE

DCE$MSRPC_MAPPING_SHR.EXE NONE

**Table 6-4 DCE Library Images for OpenVMS and Tru64 UNIX**
OpenVMS Filename	Tru64 UNIX Equivalent
DCE$IDL_CXX_SHR.EXE	NONE
DCE$KERNEL.EXE	NONE
DCE$LGI_CALLOUTS.EXE	NONE
DCE$LIB_SHR.EXE	libdce.a
DCE$SOCKSHR_IP.EXE	NONE
DCE$SOCKSHR_DNET_IV.EXE	NONE
DTSS$SHR.EXE	NONE
DTSS$RUNDOWN.EXE	NONE
DXD$CDS_SHR.EXE	NONE
DCE$NSEDIT_SHR.EXE	NONE
DCE$SOCKSHR_DNET_OSI.EXE	NONE
DCE$SOCKSHR_TPS.EXE	NONE
DCE$UAF_SHR.EXE	NONE
DCE$MSRPC_MAPPING_SHR.EXE	NONE

6.5 Message Files

After you install Compaq DCE for OpenVMS VAX or OpenVMS Alpha, all DCE message files reside in the SYS$MESSAGE directory. On a Tru64 UNIX system, the message files reside in /usr/lib/nls/msg/en_US.88591.

Table 6-5 lists the names of the message files on an OpenVMS system and the names of equivalent files on a Tru64 UNIX system.

Table 6-5 Message Files for OpenVMS and Tru64 UNIX
OpenVMS Filename Tru64 UNIX Equivalent

DCE$IDL_MSG.EXE idl.cat

DCE$RPC_MSG.EXE dcerpc.cat

DCE$UUIDGEN_MSG.EXE uuidgen.cat

DCE$SEC_MSG.EXE dcesec.cat

DCE$IL_MSG.EXE NONE

**Table 6-5 Message Files for OpenVMS and Tru64 UNIX**
OpenVMS Filename	Tru64 UNIX Equivalent
DCE$IDL_MSG.EXE	idl.cat
DCE$RPC_MSG.EXE	dcerpc.cat
DCE$UUIDGEN_MSG.EXE	uuidgen.cat
DCE$SEC_MSG.EXE	dcesec.cat
DCE$IL_MSG.EXE	NONE

6.6 Development Files

On an OpenVMS system, all DCE.h and .idl application development files reside in the SYS$COMMON:[DCE$LIBRARY] directory. You can also access this directory through the logical name DCE. On a Tru64 UNIX system, these files reside in the directory /usr/include/dce. Except for case-sensitivity differences between systems, all .h and .idl files have the same names on both OpenVMS and Tru64 UNIX systems.

6.7 Sample Applications

Both Compaq DCE for OpenVMS VAX and OpenVMS Alpha and Compaq DCE for Tru64 UNIX provide RPC and DCE sample applications. On OpenVMS, all example source and build files are located in the following separate subdirectories:

SYS$COMMON:[SYSHLP.EXAMPLES.DCE]
SYS$COMMON:[SYSHLP.EXAMPLES.DCE.RPC].

On Tru64 UNIX systems, the sample applications reside in subdirectories of /usr/examples/dce and /usr/examples/dce/rpc.

On both OpenVMS and Tru64 UNIX systems, example application files reside in subdirectories named for the sample applications. For example, on OpenVMS systems, all Distributed Calendar Program (book) example source and build files are located in the directory SYS$COMMON:[SYSHLP.EXAMPLES.DCE.RPC.BOOK].

On Tru64 UNIX systems, the equivalent files for the calendar program reside in the directory /usr/examples/dce/rpc/book.

Chapter 7
Application Development Considerations and Differences

Compaq DCE for OpenVMS VAX and OpenVMS Alpha provides universal command interfaces, as well as directory structures, filenames, and application development environments that resemble those on UNIX systems. In general, this allows users to read any standard DCE documentation, such as that provided with this release, and create DCE applications on OpenVMS systems.

Although Compaq DCE for OpenVMS VAX and OpenVMS Alpha is designed to minimize differences from DCE as it is installed on UNIX systems, there are reasons to conform to OpenVMS standards and conventions first.

Primarily, users encounter the differences between the OpenVMS and UNIX platforms when they compile and link programs, but running compiled programs can require setup procedures specific to OpenVMS or this DCE kit.

This chapter describes application development formats and rules on OpenVMS systems that may differ from those described in the OSF DCE Application Development Guide. The following topics are discussed:

Building applications
Considering structure alignment with C compilers
Building applications using OpenVMS object libraries
Running applications
Translating OSF DCE documentation examples to OpenVMS

7.1 Building Applications

This section describes command formats for compiling and linking applications on Compaq DCE for OpenVMS VAX and OpenVMS Alpha. For general information about compiling and linking applications, refer to the OSF DCE Application Development Guide.

7.1.1 Linking DCE Applications

Compaq DCE uses the Compaq C Run-Time Library (Compaq C RTL) to provide C runtime library functions for DCE software and DCE applications. DCE supports only the Compaq C RTL. Although you can compile with either the VAX C compiler or the Compaq C compiler, you must use special consideration when linking. The Compaq C/C++ Run-Time Components Kit, which is included on the kit for use with Compaq DCE for OpenVMS, provides images that let users of both the VAX C and the Compaq C/C++ compilers use the Compaq C RTL for building and running DCE applications.

Note

You must link applications against the Compaq C RTL. Do not use the VAX C RTL; your applications may fail in unpredictable ways.

The Compaq C/C++ Run-Time Components Kit must be installed before Compaq DCE for OpenVMS is installed. (Note that you do not install the Compaq C/C++ Run-Time Components Kit if you are installing Compaq DCE on OpenVMS Version 7.0 or higher.) See the Compaq DCE for OpenVMS VAX and OpenVMS Alpha Installation and Configuration Guide for more information.

There are several ways to ensure that your DCE applications use the Compaq C RTL and not the VAX C RTL. The following sections describe two options. For more complete information on all available options, see the Compaq C/C++ Run-Time Components Kit Release Notes.

Using the VAX C Compiler for DCE Applications

If you compile your DCE application using the VAX C compiler, you must link with the following C RTL interoperability image which allows your application to use the Compaq C RTL:

SYS$SHARE:VAXCG2DECC.EXE

This image is provided by the Compaq C/C++ Run-Time Components Kit. Linking with this interoperability image allows your DCE application to reference the Compaq C RTL.

The following example shows how to compile and link the server portion of an application named APP. In this example, you can compile and link the application with the following commands:

$ CC APP_MAIN.C, APP_MGR.C $ LINK /EXE=APPD.EXE APP_MAIN,APP_MGR,APP_SSTUB,- DCE:DCE/OPT,DCE:DCE_VAXC/OPT

The linker options files must include both the DCE shareable library and the C RTL interoperability image, as follows:

SYS$SHARE:DCE$LIB_SHR /SHARE SYS$SHARE:VAXG2DECC /SHARE

For more information on the C RTL interoperability images, refer to the Compaq C/C++ Run-Time Components Kit Release Notes.

Using the Compaq C Compiler for DCE Applications

Table 7-1 shows how to link DCE applications that you compiled using the Compaq C compiler.

Table 7-1 How to Link Applications Compiled with the Compaq C Compiler
If you compile using the Compaq C compiler... Link against...

With the /NOPREFIX compiler qualifier SYS$SHARE:VAXCG2DECC.EXE

Without the /NOPREFIX compiler qualifier Compaq C RTL (SYS$SHARE:DECC$SHR.EXE)

**Table 7-1 How to Link Applications Compiled with the Compaq C Compiler**
If you compile using the Compaq C compiler...	Link against...
With the /NOPREFIX compiler qualifier	SYS$SHARE:VAXCG2DECC.EXE
Without the /NOPREFIX compiler qualifier	Compaq C RTL (SYS$SHARE:DECC$SHR.EXE)

If you use the /NOPREFIX qualifier, you must link the application using an options file such as the following:

SYS$SHARE:DCE$LIB_SHR /SHARE

If you compile your DCE application using the Compaq C compiler but do not specify the /NOPREFIX compiler qualifier, you can link the application directly to the Compaq C RTL (SYS$SHARE:DECC$SHR.EXE). For more information on how to link against the Compaq C RTL, refer to the Compaq C/C++ Run-Time Components Release Notes.

Compaq DCE for OpenVMS VAX and OpenVMS Alpha also has an options file, DCE:DCE.OPT, which you should use. This DCE.OPT options file includes SYS$SHARE:DCE$LIB_SHR and other libraries needed by DCE applications. In addition, if you are using the VAX C compiler, use the file, DCE_VAXC.OPT, which includes SYS$LIBRARY:VAXCG2DECC/Share.

7.1.2 Considerations for Structure Alignment with C Compilers

On OpenVMS VAX systems, DCE stub and library code assumes the native, nonaligned form for structures. Do not use the C preprocessor pragma to enable structure member alignment (#pragma member_alignment) in your DCE applications for OpenVMS VAX. On OpenVMS Alpha systems, DCE stub and library code assumes native, aligned form for structures. Do not use the C preprocessor pragma to prevent member alignment.

7.1.3 Considerations for Building DCE Applications Using OpenVMS Object Libraries

When moving programs from one operating system to another, you must consider the operations of different linkers. The following OpenVMS Linker operations are relevant to programmers developing DCE applications:

The OpenVMS Linker does not load an object module from an object library unless the module is needed to resolve a reference in another component of the program.
The OpenVMS Linker does not load an object module from an object library to resolve a reference to an external variable if that object module contains only a compile-time initialization of the variable. In this case, the Linker creates an uninitialized PSECT for the variable. References to this variable at program runtime will yield incorrect results.

These Linker operations are important to DCE application developers because the stub code produced by the IDL compiler contains only compile-time initialization for some external variables that will be referenced by DCE applications. To ensure that these variables are initialized properly, you must explicitly include the stub modules when you link your DCE application.

Suppose you are building the client portion of your DCE application, MYAPP. The MYAPP application contains two client stub modules, MYAPP_1_CSTUB.OBJ and MYAPP_2_CSTUB.OBJ, that are stored in an object library called MYLIB. To create the MYAPP executable code, enter the following link command:

$ LINK/EXE=MYAPP,MYLIB.OLB/LIB/INCLUDE=(MYAPP_1_CSTUB,MYAPP_2_CSTUB)

Use a similar linking method to create executable server code.

7.2 Running Applications

After you compile and link an application, the result is an executable image. For example, you may create an executable image named APPD.EXE.

If your application is a simple executable file, you can run it as you do any OpenVMS executable. However, if your application accepts command line switches or input that is unacceptable from DCL (such as -d), you must define a foreign command that can invoke the executable. For example, assign a symbol with a command such as the following:

$ APPD:== $WORK1:[CARL.MYDCETEST]APPD.EXE

This assignment allows you to run the application with a command such as the following:

$ appd -d

7.3 Translating OSF DCE Documentation Examples to OpenVMS

The OSF DCE Application Development Guide refers to files that do not exist on OpenVMS systems and illustrates commands and command syntax that do not work in an OpenVMS environment. The example in Section 7.1 includes a command line that illustrates many of the differences you see when you compile DCE code on OpenVMS. Note the following differences for writing applications on OpenVMS systems:

The name for libdce is DCE$LIB_SHR.EXE.
Object format files created by the IDL and C compilers have the file extension .OBJ instead of .o.
On the Compaq Tru64 UNIX operating system, users typically define the environment variable NLSPATH to reference DCE message catalog files. On OpenVMS systems, there is no need for users to establish a symbolic reference to message catalog files.
Using the UNIX command setenv is equivalent to defining an OpenVMS logical name. Note that many important logical names are defined during DCE configuration. See the installation and configuration guide for more information.
OpenVMS does not have a program called MAKE or the makefiles that use it. On OpenVMS systems, you can convert these files to command procedures or use source-control software such as the Compaq/Module Management System (MMS) for OpenVMS.
DECnet endpoints in IDL files must be uppercase and no longer than 15 characters. See the chapter on using Compaq DCE with DECnet for more information.
The UNIX feature fork is generally analogous to spawning a subprocess in OpenVMS.
Programs that accept arguments require foreign command assignment on OpenVMS. Unless you define a foreign command first, examples such as the following do not work:
$ bookd -v $ test1 -d
Any examples or descriptions that use specific UNIX commands or syntax do not work on OpenVMS systems. A command such as the following, which redirects output to a file called binop.idl, does not work on OpenVMS:
$ uuidgen -i > binop.idl
For this particular command, uuidgen, you can direct output to a file by using the command option -o as follows:
$ uuidgen -i -o binop.idl
You can substitute the OpenVMS equivalent SYS$DISK[] for the ./ syntax. However, to make an example such as this work on OpenVMS, you must first define a foreign command that points to the executable using standard OpenVMS directory syntax.
In addition, the various UNIX commands for TYPE (cat), DIRECTORY (ls), SHOW PROCESS (ps), and STOP/ID=process-id (kill) do not work directly on OpenVMS systems.
DCE filenames and locations are similar but different on OpenVMS. See the Directory Names, Filenames, and Locations Across DCE Platforms chapter for more information about the differences and similarities.

The PIPE command can be used to simulate some UNIX style redirection. Type HELP PIPE for more information. The PIPE command is only available on OpenVMS Version 7.0 or greater.

7.4 Mapping MSRPC Calls to DCE RPC Calls

The Microsoft RPC mapping file acts as a porting aid in mapping Microsoft RPC calls to DCE RPC calls. This mechanism is provided for OpenVMS Alpha Version 7.2 and higher only with the Application Developer's Kit.

To aid in porting Microsoft RPC applications to the DCE format, a new shareable image SYS$LIBRARY:MSRPC_MAPPING_SHR.EXE can be used to link with the RPC application. This new image provides entry points that map a subset of MSRPC calls to their DCE equivalents. To identify which APIs have been mapped, see the MSRPC_MAPPING.H file. This file needs to be included in the RPC application.

Chapter 8
Integrated Login

This chapter discusses Integrated Login, a component of Compaq DCE for OpenVMS VAX and OpenVMS Alpha that combines the DCE and OpenVMS login procedures.

Integrated Login users should read the following sections:

Section 8.1 --- Overview
Section 8.3 --- Integrated Login Procedure
Section 8.4 --- Changing Your DCE Password
Section 8.9 --- Frequently Asked Questions for Users

System administrators should read the entire chapter (especially Section 8.5 and Section 8.10).

8.1 Overview

Integrated Login allows you to do the following:

Obtain DCE credentials when you interactively log in to OpenVMS. There is no need for a separate DCE login.
Enter either the DCE principal name and password or the OpenVMS username and password at the OpenVMS username and password prompt. (Using the DCE principal name and password is recommended.)
Automatically synchronize DCE and OpenVMS passwords on every system throughout the cell that supports Integrated Login.
Use local login if the DCE Security Service is unavailable.

Integrated login is different from single login. Integrated login means that the OpenVMS and DCE login processes are combined. When you log in to the OpenVMS system specifying a single username and password, you are automatically logged in to DCE as well. Single login means that once you have been authenticated on one system (that is, integrated login has occurred), you are automatically authenticated on any other system within the cell. (For example, with single login it would be possible for telnet not to prompt for a username and password.) DCE for OpenVMS VAX and OpenVMS Alpha provides integrated login, not single login.

Integrated Login occurs when you log in to a standard interactive session, start a remote interactive session, or create a terminal window. Integrated Login is not supported for network jobs, batch jobs, or detached processes.

8.2 Integrated Login Components

The components of Integrated Login include the following:

Integrated Login procedure
DCE User Authorization File (DCE$UAF)
DCE$UAF Command Line Interface
DCE IMPORT utility
DCE EXPORT utility

8.3 Integrated Login Procedure

To log in to an OpenVMS system where DCE Integrated Login is enabled, perform the following steps:

At the OpenVMS username prompt, enter your DCE principal name or OpenVMS username.

Note

Compaq recommends that you specify your DCE principal name and password when logging in to a system on which Integrated Login is enabled.
The DCE principal name you specify can contain no more than 32 characters. If your principal name and cell name combination contains more than 32 characters, specify the OpenVMS username that is associated with your DCE account instead. (This username is entered in the DCE$UAF file.) You should still enter your DCE password to obtain DCE credentials even if you specify your OpenVMS username.
If the DCE principal name or cell name contains lowercase characters or OpenVMS special characters (for example, "/" and ","), enclose the entire entry in quotation marks.

If a cell name is entered with a principal name, separate the two with an at sign (@). If you do not specify a cell name, the current DCE cell name is assumed. For example:

Username: "JaneSmith@paper_cell.widget.com"

At the password prompt, enter your DCE password (recommended) or OpenVMS password. If you enter your DCE password and your OpenVMS password is not currently synchronized, Integrated Login attempts to reset your OpenVMS password to match your DCE password.

When you specify your principal name, Integrated Login maps the principal name to your OpenVMS username by performing a lookup in the DCE$UAF. Similarly, if you specify your OpenVMS username, Integrated Login maps the username to your principal name by performing a case-blind lookup in the DCE$UAF. (If the principal name or username you specify is not found in DCE$UAF, a regular OpenVMS login is attempted.)

When the lookup is complete, Integrated Login has obtained both your username and principal name. With that information, Integrated Login first attempts an OpenVMS login, then a DCE login. (The same password is used for both login attempts.) Depending on the principal name, username, and password you specify, four possible outcomes can occur, as follows:

DCE Login: Success OpenVMS Login: Success
If the password provided results in a valid OpenVMS login and a valid DCE login, the OpenVMS login succeeds and you have DCE credentials. Following is an example of a successful login:

DCE Login: Failure OpenVMS Login: Success
If the password provided results in a valid OpenVMS login but a failed DCE login, the OpenVMS login succeeds but you do not have DCE credentials. Integrated Login displays a message stating that the DCE login failed. For example:

Welcome to OpenVMS (TM) Alpha Operating System, Version V7.2 Username: smith Password: Welcome to OpenVMS Alpha (TM) Operating System, Version V6.1 on node NODE Last interactive login on Tuesday, 10-JAN-1995 08:26:49.50 Last non-interactive login on Tuesday, 10-JAN-1995 08:18:52.81 %DCE-I-IL_VMSONLY, DCE login as principal "/.../dce_cell.widget.com/Smith" failed, OpenVMS login to SMITH successful $

If the "DCE login required" feature is enabled, this outcome will fail and you will receive the user authorization failure message. See Section 8.5 for information on the DCE login required feature.

DCE Login: Success OpenVMS Login: Failure
If the password provided results in a valid DCE login but a failed OpenVMS login, you are given DCE credentials and you are logged in to OpenVMS. Integrated Login then attempts to set the OpenVMS password to match the DCE password. In the following example, the password was successfully synchronized:

Welcome to OpenVMS (TM) Alpha Operating System, Version V7.2 Username: smith Password: Welcome to OpenVMS Alpha (TM) Operating System, Version V6.1 on node NODE Last interactive login on Tuesday, 10-JAN-1995 08:13:00.47 Last non-interactive login on Tuesday, 10-JAN-1995 08:18:52.81 %DCE-S-IL_DCECERT, Certified DCE login for SMITH as principal "/.../dce_cell.widget.com/Smith" %DCE-S-IL_VMSPWDSYNC, OpenVMS password synchronized with DCE password $

In this example, the password was not successfully synchronized:

Welcome to OpenVMS (TM) Alpha Operating System, Version V7.2 Username: smith Password: Welcome to OpenVMS Alpha (TM) Operating System, Version V6.1 on node NODE Last interactive login on Tuesday, 10-JAN-1995 06:44:16.15 Last non-interactive login on Tuesday, 10-JAN-1995 07:02:58.95 %DCE-S-IL_DCECERT, Certified DCE login for SMITH as principal "/.../dce_cell.widget.com/Smith" %DCE-I-IL_ERRVMSPWD, Error synchronizing OpenVMS password with DCE password -DCE-F-IL_INVPWDLEN, password length must be between 15 and 32 characters $

DCE Login: Failure OpenVMS Login: Failure
If the password provided results in a failed DCE login and a failed OpenVMS login, you are not given DCE credentials and the OpenVMS login does not succeed. For example:
Welcome to OpenVMS (TM) Alpha Operating System, Version V7.2 Username: smith Password: User authorization failure
When a login fails, you do not receive a message stating the reason for the login failure. If you are a system administrator, you can enable auditing to see the reasons for login failures. To enable auditing, enter the following command:
$ SET AUDIT/ALARM/ENABLE=LOGFAIL=ALL

Contents

Index

privacy and legal statement

6532_DCE_PG_PRO_003.HTML

Compaq DCE for OpenVMS VAX and OpenVMS AlphaProduct Guide