The OpenVMS Porting Library is designed to address some of the more common porting issues that occur when you port C/C++ applications from Unix to OpenVMS. However, it will not solve all the problems you may encounter.

Note that the code in the Porting Library is not always completely functional and will not work in all of the situations in which you try to use it. The code was written to solve specific problems while porting specific products. The code usually does "just enough."

OpenVMS is continually improving and evolving the C RTL. Some functions that were missing two or three years ago are available in more recent versions of the C RTL. This eliminates the need for some of the routines in the Porting Library. Whenever possible, use the C RTL version of a routine, because this is likely to be a more complete implementation (and is supported).

Benefits of the Porting Library

Porting C/C++ applications from Unix to OpenVMS requires quite a bit of repetitive work, because many of the changes you need to make are common across several applications. The Porting Library captures some of these frequently made changes and includes them in a library that can be reused. This allows additional applications to be ported more quickly and easily.

Functionality Provided

Some of the major functionality provided by the Porting Library is as follows:

• File name parsing and conversion of filenames into routines such as open and stat. This allows otherwise invalid names to be accepted (for example, long names or names of the form a.b.c).
• All files are opened with shr=get,put to mimic the UNIX behavior. (This is the default, but it can be changed at run time using a logical.)
• A poll function that can accept event flags as well as sockets. This makes it easy to integrate X events into poll/select code.
• A socket pair implementation.
• A getpwent, setpwent, and endpwent implementation.
• Enhancements to opendir (and related routines) to allow opendir("/") to return a list of all disk devices on the system.
• Easy tracing of all files being opened.
• Easy tracing of all dlsym operations.

Products Ported Using the OpenVMS Porting Library

Versions of the OpenVMS Porting Library were used to port the following products to OpenVMS:

• Java Development Kit for OpenVMS
• Netscape FastTrack Web Server for OpenVMS
• Netscape Commerce and Communications Web Servers for OpenVMS
• Navigator V3.x for OpenVMS
• Mozilla for OpenVMS

Contents of the Kit

The OpenVMS Porting Library consists of the following:

• Jacket routines for many of the C RTL functions (for example, creat, open, rmdir). Each jacket routine performs some additional work before calling the real C RTL function.
• Routines to supplement the C RTL (for example, socketpair, writev).
• Header file to perform PTHREAD redefines (solves casing problem when compiling with /NAMES=AS_IS).
• Header file to perform MOTIF redefines (solves casing problem when compiling with /NAMES=AS_IS).
• Header files that are not usually shipped on OpenVMS (for example, poll.h).
• Makefile to build on OpenVMS.
• gmake (3.76.1) image pre-built for OpenVMS Alpha Version 7.1 and OpenVMS VAX Version 7.1.

Not Included in the Kit

The following functionality is not included:

Building the Porting Library

This section explains how to build the Porting Library.

The OpenVMS Porting Library requires the following software:

• OpenVMS Alpha or OpenVMS VAX Version 7.1 (or later)
• DEC C Version 6.2 (or later)

The Porting Library code is intended to be built on OpenVMS Version 7.1 or later. It will run on the version of OpenVMS on which is was built or any later version.

Earlier versions of OpenVMS and DEC C have not been tested.

Expanding the Kit

Two self-extracting archives and a .ZIP file are available for download. The contents of the kits are identical. Alpha and VAX versions are provided because the kit is distributed as a self-extracting archive.

Download the Alpha version to expand and install the kit on an Alpha system, and the VAX version to expand and install the kit on a VAX system. You can expand the .ZIP file on Alpha or VAX, or on a PC if you want to simply view the files in the kit.

After you download the appropriate kit, create a directory where you want the source code tree to reside. Set your default directory to that location.

Then, to expand the OpenVMS Porting Library self-extracting archive, run the Alpha or VAX kit you downloaded. For example:

$ CREATE/DIRECTORY DKA0:[PORTING]
$ SET DEFAULT DKA0:[PORTING]
$ RUN DKA0:[KITS]PORTING-A1-SFX_AXP.EXE

Files Built by the Library

After you expand the OpenVMS Porting Library kit, you must build the library.

When you run the Makefile, the following files are built:

• VMS_JACKETS.EXE

  Shareable image. Define NOSHR to prevent the shareable image from being built.

• VMS_JACKETS.OLB

  Object library. Define NOLIB to prevent the object library from being built.

• VMS_JACKETS.A

  A second version of the object library, with a filetype of .A instead of .OLB. This is for use within POSIX. Define NOPOSIX to prevent the POSIX object library from being built.

Logical Name Prefix

Any logical names used in the code will use "VMS_" as a prefix. You can override this default by defining VMS_PREFIX.

Building the Code

Perform the following steps to build the OpenVMS Porting Library code.

1. Define a symbol to invoke gmake. For example, the symbol on Alpha is similar to the following:

   $ gmake == "$DKA0:[PORTING]make_3_76_1_vms_alpha"

2. Use the gmake command, specifying any required options on the command line. Note that quotation marks are needed around any options. For example:

   $ gmake  ! builds the library optimized (no debug)
   

   $ gmake "DEBUG=1" "VAX=1" ! VAX debug build
   

3. Afer you build the Porting Library, you must install it. Again use gmake:

   $ gmake "DIST_TOP=DKA0:[PORTING.DIST.]" install
   

   This command moves the files you need to build with the Porting Library to the DKA0:[PORTING.DIST] directory tree. It is this [PORTING.DIST.INCLUDE] directory that you need to specify in the include path when you build the library.

Build Options

DEBUG - Compile with /DEBUG /NOOPTIMIZE. Link with /DEBUG.

DIST_TOP - Specifies where the Porting Library files should be installed. Note that the directory specification must have a trailing period. If the value contains any dollar sign characters, then you must preceed each dollar sign with another dollar sign.

NOLIB - Do not build the object library LIBVMS.OLB.

NOPOSIX - Do not build the POSIX object library LIBVMS.A. (LIBVMS.A is a copy of LIBVMS.OLB for use with POSIX).

NOSHR - Do not build the shared library LIBVMS.EXE.

VMS_PREFIX=name - Use name as a prefix for logical names. Some of the jackets contain features that are enabled or disabled by logical names. By default all such logical names are prefixed with "VMS_", but you can change this by using the VMS_PREFIX option. VMS_PREFIX is also used to determine the names of the library and sharable image produced.

WITH_UNEXPECTED - Compile a routine named unexpected. This is a workaround for an old problem with the C++ compiler.

VAX - Build is being done on a VAX system (default is Alpha).

Building the Application

• GENERIC_MOTIF_REDEFINES - Forces extra include file(s) to be included that handle the casing problems in MOTIF.
• GENERIC_PTHREAD_REDEFINES - Forces extra include file(s) to be included that handle the casing problems in PTHREADS.

VMS_JACKETS.H

You must include VMS_JACKETS.H as the first include file of every module. The following methods will achieve this result.

Include Path

Make sure that the include path contains the [PORTING.DIST.INCLUDE] directory, which is the directory where VMS_JACKETS.H is located. This directory was created and populated when you ran gmake install.

Note that there are other include files in subdirectories such as rpc and sys, so be very careful if you move VMS_JACKETS.H.

Linking

Once you've compiled your code with VMS_JACKETS.H in each module, you need to link your code. Select either the object library or the shareable image; both contain the same routines, and both are placed in the [PORTING.DIST.LIB] directory by gmake install.

If you link against the shareable image, there is a linker options file in [PORTING.DIST.LIB] for this purpose.

Running the Application

Once you have successfully built your application, you are ready to run it. This section contains information that you need to be aware of when you run your application.

Logical Names

The following logical names may need to be defined in order for your application to run after you have built it with the OpenVMS Porting Library.

Files and Routines

The naming convention is as follows:

• Files
• Files containing new functionality have the name of the function, for example fchmod.c.
• Files containing jacketed functionality have the name of the function and the "_jacket" appendix, for example chdir_jacket.c.
• Routines
• A routine that does not exist in the C RTL is named GENERIC_ROUTINE, where ROUTINE is the uppercased C function name. A prefix is used to make it obvious that it is not a genuine C RTL function.
• A routine that exists in the C RTL and is being jacketed is named GENERIC_ROUTINE_JACKET, where ROUTINE is the name of the C function that is being jacketed.

Header Files

Following are the header files included in the OpenVMS Porting Library. Some header files are referenced by the main VMS_JACKETS.H header file, while others are listed because UNIX code requires them.

C/C++ Code

Other Files