     OpenVMS Porting Library         Release Notes        Introduction         Contents of the Kit  !      Building the Porting Library             * Software Prerequisites         * Expanding the Kit $         * Files Built by the Library         * Logical Name Prefix          * Building the Code          * Build Options         Building the Application            * Defines          * VMS_JACKETS.H          * Include Path         * Linking         Running the Application           * Logical Names         Files and Routines            * Header Files         * C/C++ Code         * Other Files         Introduction   C      The OpenVMS Porting Library is designed to address some of the >      more common porting issues that occur when you port C/C++B      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 alwaysE      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."  B      OpenVMS is continually improving and evolving the C RTL. SomeE      functions that were missing two or three years ago are available C      in more recent versions of the C RTL. This eliminates the need >      for some of the routines in the Porting Library. WheneverB      possible, use the C RTL version of a routine, because this isD      likely to be a more complete implementation (and is supported).  $      Benefits of the Porting Library  E      Porting C/C++ applications from Unix to OpenVMS requires quite a D      bit of repetitive work, because many of the changes you need toE      make are common across several applications. The Porting Library E      captures some of these frequently made changes and includes them <      in a library that can be reused. This allows additional7      applications to be ported more quickly and easily.         Functionality Provided   D      Some of the major functionality provided by the Porting Library      is as follows:   E         * File name parsing and conversion of filenames into routines D           such as open and stat. This allows otherwise invalid namesA           to be accepted (for example, long names or names of the            form a.b.c).  A         * All files are opened with shr=get,put to mimic the UNIX B           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.  A         * Enhancements to opendir (and related routines) to allow B           opendir("/") to return a list of all disk devices on the           system.   1         * Easy tracing of all files being opened.   /         * Easy tracing of all dlsym operations.   6      Products Ported Using the OpenVMS Porting Library  B      Versions of the OpenVMS Porting Library were used to port the#      following products to OpenVMS:   *         * Java Development Kit for OpenVMS3         * 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        Included in the Kit  ;      The OpenVMS Porting Library consists of the following:   >         * Jacket routines for many of the C RTL functions (forD           example, creat, open, rmdir). Each jacket routine performs<           some additional work before calling the real C RTL           function.   D         * Routines to supplement the C RTL (for example, socketpair,           writev).  A         * Header file to perform PTHREAD redefines (solves casing 4           problem when compiling with /NAMES=AS_IS).  ?         * Header file to perform MOTIF redefines (solves casing 4           problem when compiling with /NAMES=AS_IS).  C         * Header files that are not usually shipped on OpenVMS (for            example, poll.h).   '         * Makefile to build on OpenVMS.   B         * gmake (3.76.1) image pre-built for OpenVMS Alpha Version*           7.1 and OpenVMS VAX Version 7.1.        Not Included in the Kit  1      The following functionality is not included:   @         * A method to automatically include the main header fileD           (VMS_JACKETS.H) into each compilation (although some ideas           are offered).   E         * Java and JavsScript redefines. These are version dependent.   !      Building the Porting Library   <      This section explains how to build the Porting Library.        Software Prerequisites   A      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 OpenVMSC      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  D      Two kits self-extracting archives and a .ZIP file are availableD      for download. The contents of the kits are identical. Alpha andB      VAX versions are provided because the kit is distributed as a      self-extracting archive.   D      Download the the Alpha version to expand and install the kit onC      an Alpha system, and the VAX version to expand and install the B      kit on a VAX system. You can expand the .ZIP file on Alpha orE      VAX, or on a PC if you want to simply view the files in the kit.   E      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-extractingC      archive, run the Alpha or VAX kit you downloaded. For example:   +           $ CREATE/DIRECTORY DKA0:[PORTING] &           $ SET DEFAULT DKA0:[PORTING]-           $ RUN DKA0:[KITS]PORTING.SFX_AXPEXE         Files Built by the Library   E      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   D           Object library. Define NOLIB to prevent the object library           from being built.            * VMS_JACKETS.A   D           A second version of the object library, with a filetype ofB           .A instead of .OLB. This is for use within POSIX. Define@           NOPOSIX to prevent the POSIX object library from being           built.        Logical Name Prefix  D      Any logical names used in the code will use "VMS_" as a prefix.:      You can override this default by defining VMS_PREFIX.  ,      See Build Options for more information.        Building the Code  E      Perform the following steps to build the OpenVMS Porting Library 
      code.  E        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"  C        2. Use the gmake command, specifying any required options on @           the command line. Note that quotation marks are needed*           around any options. For example:  A                $ gmake  ! builds the library optimized (no debug)   :                $ gmake "DEBUG=1" "VAX=1" ! VAX debug build  B        3. Afer you build the Porting Library, you must install it.           Again use gmake:  9           $ gmake "DIST_TOP=DKA0:[PORTING.DIST.]" install   A           This command moves the files you need to build with the D           Porting Library to the DKA0:[PORTING.DIST] directory tree.C           It is this [PORTING.DIST.INCLUDE] directory that you need D           to specify in the include path when you build the library.        Build Options  ?      DEBUG - Compile with /DEBUG /NOOPTIMIZE. Link with /DEBUG.   C      DIST_TOP - Specifies where the Porting Library files should be A      installed. Note that the directory specification must have a ;      trailing period. If the value contains any dollar sign D      characters, then you must preceed each dollar sign with another      dollar sign.   8      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).   8      NOSHR - Do not build the shared library LIBVMS.EXE.  C      VMS_PREFIX=name - Use name as a prefix for logical names. Some D      of the jackets contain features that are enabled or disabled byB      logical names. By default all such logical names are prefixedA      with "VMS_", but you can change this by using the VMS_PREFIX B      option. VMS_PREFIX is also used to determine the names of the)      library and sharable image produced.   D      WITH_UNEXPECTED - Compile a routine named unexpected. This is a9      workaround for an old problem with the C++ compiler.   B      VAX - Build is being done on a VAX system (default is Alpha).        Building the Application   E      This section explains how to integrate your application with the @      Porting Library. It assumes that you have already built andE      installed the Porting Library as described in Building the Code.         Defines  C      If you compile your application with the /NAMES=AS_IS compiler C      option, consider defining these on your compiler command line:   C         * GENERIC_MOTIF_REDEFINES - Forces extra include file(s) to ?           be included that handle the casing problems in MOTIF.   E         * GENERIC_PTHREAD_REDEFINES - Forces extra include file(s) to B           be included that handle the casing problems in PTHREADS.        VMS_JACKETS.H  @      You must include VMS_JACKETS.H as the first include file ofB      every module. The following methods will achieve this result.  B         * Edit every file and add the following line to the top of           the file:   "           #include "VMS_JACKETS.H"  A           This can be time-consuming for a large number of files.   2         * Use a shortcut similar to the following:  A              o Define the cc command to invoke a command file (or 4                script if you are building in POSIX).  @              o For this example, assume that the command file is0                passed the file foo.c to compile.  <              o The command file creates another file (with aD                different name in the same directory or the same name=                in a mirror directory) called fake_foo.c, that "                contains two lines:  '                #include "VMS_JACKETS.H"                 #include "foo.c"   =              o The command file compiles fake_foo.c, creating                 foo.obj.   :         * If you are using make (or similar) to build yourC           application, you can change the rule for compiling C (and @           C++) code to the following. (Note that this example isA           simply demonstrating the principle and will not work as            is.)    7           $(CC) $(CFLAGS) /OBJ=$@ DIST:VMS_JACKETS.H+$<   D         * If you are using GNV, use the -include option. (If you are6           porting UNIX code to OpenVMS, be sure to see&           http://gnv.sourceforge.net.)        Include Path   1      Make sure that the include path contains the C      [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.  C      Note that there are other include files in subdirectories such B      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 eachA      module, you need to link your code. Select either the object D      library or the shareable image; both contain the same routines,E      and both are placed in the [PORTING.DIST.LIB] directory by gmake 
      install.   ?      If you link against the shareable image, there is a linker 9      options file in [PORTING.DIST.LIB] for this purpose.         Running the Application  E      Once you have successfully built your application, you are ready E      to run it. This section contains information that you need to be ,      aware of when you run your application.        Logical Names  D      The following logical names may need to be defined in order forE      your application to run after you have built it with the OpenVMS       Porting Library.   C      The default logical name prefix is "VMS_". You can change this C      when you build the Porting Library. See Build Options for more       information.         VMS_DEBUG_STAT         Used in STAT_JACKET.C  ?      If defined, enables logging code in the stat routines. The @      default is off, and the logging code is only built in DEBUG%      versions of the Porting Library.         VMS_FILENAME_CONTROLS  !      Used in FILESYSTEM_PARSING.C   C      Allows you to control many aspects of how filenames are parsed >      before they are handed to routines such as open and stat.        For more information, seeE      SYS$SYSROOT:[SYSHLP.JAVA]JAVA$FILENAME_CONTROLS.COM on any Alpha D      Version 7.1 or later system. This is the same code that is used
      by Java.         VMS_FILE_OPEN_MODE         Used in OPEN_JACKET.C  ?      Affects how a file is opened. The default is to always use .      "shr=get,put". Other modes are available.  E      Usually the open jacket routine will call umask before opening a E      file in order to get the requested protection set correctly. The A      umask call can be disabled by adding 10 to the value of this 
      logical.         VMS_NULL_DL_NAME         Used in DL.C   @      The name of the shareable image to be loaded when dlopen is"      passed NULL as the file name.  @      There is no default. If you want to specify a value so that=      dlopen(NULL,mode) will succeed, use something similar to A      SYS$SHARE:CMA$TIS_SHR.EXE or SYS$SHARE:DECC$CRTL.EXE (or any E      image that you know will always be loaded for your application).         VMS_POLL_TIMER_MIN       VMS_POLL_TIMER_MAX       VMS_POLL_TIMER_DELTA         Used in POLL_JACKET.C  C      In order to support event flags in the poll code, the code has A      to periodically check the event flags to see if any are set. @      These logicals control the frequency at which the flags are
      checked.         The defaults are:  +         * VMS_POLL_TIMER_MIN = 10 millisecs ,         * VMS_POLL_TIMER_DELTA = 1 millisecs,         * VMS_POLL_TIMER_MAX = 200 millisecs  4      The poll timer is a sliding timer. It begins atB      VMS_POLL_TIMER_MIN, and increases by VMS_POLL_TIMER_DELTA for>      each poll operation. The timer is never allowed to exceedC      VMS_POLL_TIMER_MAX. As soon as any activity is seen, the timer       resets to the start value.         VMS_STAT_DEVICE_ROOTS        Used in OPENDIR_JACKET.C   C      Usually the Porting Library's stat code will not stat a device C      root directory ([000000]) because performing a stat on certain ?      device roots can be very slow. (For example, an infoserved ?      device can take 15-20 seconds to respond.) The information %      returned can usually be guessed.   D      Define this logical (to any value) if you wish root directories&      to be stat'd. The default is off.        VMS_TRACE_FILENAMES  ,      Used in VMS_JACKETS.H and many C files.  C      Many of the jacket routines such as open, stat, and dlsym have 0      tracing functionality. This is very useful.  2      The default is off. To enable tracing, define&      VMS_TRACE_FILENAMES to any value.        Files and Routines   )      The naming convention is as follows:            * Files B              o Files containing new functionality have the name of2                the function, for example fchmod.c.D              o Files containing jacketed functionality have the name>                of the function and the "_jacket" appendix, for&                example chdir_jacket.c.           * RoutinesB              o A routine that does not exist in the C RTL is namedA                GENERIC_ROUTINE, where ROUTINE is the uppercased C A                function name. A prefix is used to make it obvious 7                that it is not a genuine C RTL function. >              o A routine that exists in the C RTL and is being>                jacketed is named GENERIC_ROUTINE_JACKET, whereB                ROUTINE is the name of the C function that is being                jacketed.        Header Files   C      Following are the header files included in the OpenVMS Porting :      Library. Some header files are referenced by the mainD      VMS_JACKETS.H header file, while others are listed because UNIX      code requires them.  $       Header File        Description  >       dlfcn.h            Protos and constants for dll routines+                          contained in dl.c.   ;       endian.h           Defines a few of the common endian                           items. 4       gen64def.h         Defines _generic_64 struct.;       grp.h              Empty file. Present for compilers. 5       malloc.h           According to the Single UNIX ?                          Specification, there is no such header ?                          file. However, we have found some code @                          that includes it. This version includes@                          stdlib.h which is where you find malloc$                          and others.>       motif_redefines.h  X redefines. Only needed if compiling                          AS_IS. <       poll.h             Accompanies the poll_jacket.c code.:       pthread_redefines.hPthread redefines. Only needed if)                          compiling AS_IS. /       termios.h          Standard UNIX version. /       utime.h            Standard UNIX version.   ?       vms_jackets.h      Main include file. Must be included by -                          all your C/C++ code. ;       rpc/types.h        Empty file. Present for compilers. ;       rpc/xdr.h          Empty file. Present for compilers. ;       sys/param.h        Empty file. Present for compilers. ;       sys/select.h       Empty file. Present for compilers. 7       sys/statfs.h       Accompanies the statfs.c code. ;       sys/un.h           Empty file. Present for compilers.         C/C++ Code   $       Source File           Routines1       access_jacket.c       GENERIC_access_Jacket 0       chdir_jacket.c        GENERIC_chdir_Jacket0       chmod_jacket.c        GENERIC_chmod_Jacket0       chown_jacket.c        GENERIC_chown_Jacket0       creat_jacket.c        GENERIC_creat_Jacket1       delete_jacket.c       GENERIC_delete_Jacket +       dl.c                  GENERIC_dlclose +                             GENERIC_dlerror *                             GENERIC_dlopen)                             GENERIC_dlsym *       fchmod.c              GENERIC_fchmod)       fcntl.c               GENERIC_fcntl 7       filesystem_parsing.c  GENERIC_VMS_Filename_parser 6                             Plus some support routines0       fopen_jacket.c        GENERIC_fopen_Jacket0       fread_jacket.c        GENERIC_fread_Jacket0       fstat_jacket.c        GENERIC_fstat_Jacket,       getpwent.c            GENERIC_endpwent,                             GENERIC_getpwent,                             GENERIC_setpwent3       getpwnam_jacket.c     GENERIC_getpwnam_Jacket 3       getpwuid_jacket.c     GENERIC_getpwuid_Jacket 1       getcwd_jacket.c       GENERIC_getcwd_Jacket ,       is_image.c            GENERIC_is_image)       lockf.c               GENERIC_lockf )       lstat.c               GENERIC_lstat 0       mkdir_jacket.c        GENERIC_mkdir_Jacket/       mmap_jacket.c         GENERIC_mmap_Jacket 0                             GENERIC_mmap_Jacket81                             GENERIC_munmap_Jacket *       noecho.c              GENERIC_noecho2       opendir_jacket.c      GENERIC_opendir_Jacket2                             GENERIC_readdir_Jacket3                             GENERIC_closedir_Jacket 4                             GENERIC_rewinddir_Jacket2                             GENERIC_seekdir_Jacket/       open_jacket.c         GENERIC_open_Jacket 6                             GENERIC_open_shared_Jacket4                             GENERIC_open_java_Jacket(       poll_jacket.c         GENERIC_poll6       privs.c               GENERIC_remove_image_privs-                             GENERIC_set_privs 1                             GENERIC_restore_privs 9       pthread_routines.c    GENERIC_pthread_attr_getscope 9                             GENERIC_pthread_attr_setscope ,       readlink.c            GENERIC_READLINK,       realpath.c            GENERIC_realpath(       recv.c                GENERIC_RECV1       remove_jacket.c       GENERIC_remove_Jacket 1       rename_jacket.c       GENERIC_rename_Jacket 0       rmdir_jacket.c        GENERIC_rmdir_Jacket(       send.c                GENERIC_SEND*       setsid.c              GENERIC_setsid3       share_file_support.c  GENERIC_File_Share_INIT 2                             GENERIC_File_Share_REG4                             GENERIC_File_Share_UNREG4                             GENERIC_Mark_Share_WRITE4                             GENERIC_File_Share_CHECK.       socketpair.c          GENERIC_socketpair/       stat_jacket.c         GENERIC_stat_Jacket 5                             __UTC_GENERIC_STAT_JACKET *       statfs.c              GENERIC_statfs,       syslog.c              GENERIC_closelog*                             GENERIC_syslog2       tempnam_jacket.c      GENERIC_tempnam_Jacket/       time_r.c              GENERIC_localtime_r ,                             GENERIC_gmtime_r7                             __UTCTZ_GENERIC_LOCALTIME_R 4                             __UTCTZ_GENERIC_GMTIME_R&       unexpected.c          unexpected1       unix2vms.c            GENERIC_external_name 5                             GENERIC_external_dir_name :                             GENERIC_is_valid_VMS_file_spec1       unlink_jacket.c       GENERIC_unlink_Jacket <       utils.c               Various utility/support routines)       utime.c               GENERIC_utime )       write.c               GENERIC_WRITE *       writev.c              GENERIC_writev        Other Files  *       File                     Description  8       makefile.vms             Used to build the Porting'                                Library. ?       make_options.com         Used by makefile.vms to create a 3                                linker options file. :       make_options.dat         List of all Porting Library5                                routine names. Used by 0                                make_options.com.4       make_opt_file.com        Used by makefile.vms.?       make_3_76_1_vms_alpha.exePre-built make image for OpenVMS 3                                Alpha V7.1 or later.   ?       make_3_76_1_vms_vax.exe  Pre-built make image for OpenVMS 1                                VAX V7.1 or later. F      -----------------------------------------------------------------  -      Distribution restrictions and disclaimer   A      Customer agrees that he/she is not prohibited by the U.S. or D      other government export control regulations from receiving this       software or technical data.F      -----------------------------------------------------------------  (      Copyright and trademark information  D      Compaq believes the information in this document is accurate asC      of its publication date; such information is subject to change       without notice.  E      Copyright Compaq Computer Corporation 2000. All rights reserved.   D      Compaq, the Compaq logo, and the DIGITAL logo are registered inB      the U.S. Patent and Trademark Office. Java and all Java-based9      marks are trademarks or registered trademarks of Sun C      Microsystems, Inc. in the U.S. and other countries. Microsoft, B      Windows, and Windows 95 are registered trademarks, and NT and9      Windows NT are trademarks, of Microsoft Corporation.   D      Alpha, AlphaServer, AlphaStation, DEC, DIGITAL, OpenVMS, Tru64,@      VAX, and VMS are trademarks of Compaq Computer Corporation.  