Digital 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 Digital 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

This section describes command formats for compiling and linking applications on Digital 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

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

The DEC C/C++ Run-Time Components Kit must be installed before Digital DCE for OpenVMS VAX is installed. (Note that you do not install the DEC C/C++ Run-Time Components Kit if you are installing Digital DCE on OpenVMS Alpha.) See the Digital 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 DEC C RTL and not the VAX C RTL. The following sections describe two options. For more complete information on all available options, see the DEC 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 DEC C RTL:

SYS$SHARE:VAXCG2DECC.EXE

This image is provided by the DEC C/C++ Run-Time Components Kit. Linking with this interoperability image allows your DCE application to reference the DEC 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 DEC C/C++ Run-Time Components Kit Release Notes.

Using the DEC C Compiler for DCE Applications

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

Table 7-1 How to Link Applications Compiled with the DEC C Compiler

If you compile using the DEC C compiler...	Link against...
With the /NOPREFIX compiler qualifier	SYS$SHARE:VAXCG2DECC.EXE
Without the /NOPREFIX compiler qualifier	DEC 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 DEC C compiler but do not specify the /NOPREFIX compiler qualifier, you can link the application directly to the DEC C RTL (SYS$SHARE:DECC$SHR.EXE). For more information on how to link against the DEC C RTL, refer to the DEC C/C++ Run-Time Components Release Notes.

Digital 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 f or 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 extern 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 DEC OSF/1 and ULTRIX operating systems, users typically define the environment variable NLSPATH to reference DCE message catalog files. On OpenVMS VAX 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 DEC/Module Management System (MMS). You can also use makefiles under OpenVMS POSIX. The example programs include an example of an OpenVMS POSIX makefile.
• DECnet endpoints in IDL files must be uppercase and no longer than 15 characters. See the chapter on using Digital DCE with DECnet for more information.
• The UNIX feature fork is generally analogous to spawning a subprocess in OpenVMS. You can also use OpenVMS POSIX which supports fork.
• 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 MS RPC mapping file acts as a porting aid in mapping MSRPC calls to DCE RPC calls. This mechanism is provided for OpenVMS Alpha V7.2 only with the Application Developer's Kit.

To aid in porting MSRPC 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 which 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.

This chapter discusses Integrated Login, a component of Digital 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 Password
• Section 8.9 --- Frequently Asked Questions for Users

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

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

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

1. 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"

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

  Welcome to OpenVMS Alpha (TM) Operating System, Version V6.1 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:25:33.67 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 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 Alpha (TM) Operating System, Version V6.1 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 Alpha (TM) Operating System, Version V6.1 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 Alpha (TM) Operating System, Version V6.1 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 Alpha (TM) Operating System, Version V6.1 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

Compaq recommends that you change only your DCE password. After changing your DCE password, the next time you log in to the OpenVMS system specifying your new DCE password at the OpenVMS password prompt, your OpenVMS password is changed to match your DCE password. There is no need to separately change your OpenVMS password.

To change your DCE password, invoke the CHPASS utility with an optional DCE principal name. For example, entering any of the following invokes the CHPASS utility:

$ chpass $ chpass smith $ mcr dce$chpass $ mcr dce$chpass smith

If you do not specify a DCE principal name on the command line, the CHPASS utility obtains the DCE principal name from the current credentials. For example:

$ chpass Old password: New password: Verification:

If the process does not have a default login context, you are prompted for your principal name. For example:

$ kdestroy $ chpass Please enter the principal name: smith Old password: New password: Verification:

As you enter the old and new passwords, the terminal does not echo the input. Because echoing is turned off, the user is asked to enter the new password twice to verify the input.

SYS$COMMON:[SYSMGR]DCE$DEFINE_REQUIRED_COMMANDS.COM defines the DCE symbol CHPASS, which is used to invoke DCE$CHPASS. If this symbol is not defined in your environment, you can define the symbol as follows:

$ CHPASS :== $SYS$SYSTEM:DCE$CHPASS.EXE