# Preface

OpenVMS and Open source both started using the Open prefix some time ago. Before that, all we had were a lot of operating systems, one of which was VAX VMS. Each operating system came with its own possibilities, strong and weak points. If you wanted a application to run on your computer you would buy or build the application yourself for your computer. The efforts needed to get the thing going, were often so great that people sought methods to make the process of implementing applications on a different platform (so called porting) easier. Especially software meant to be implemented on many different platforms and software developed for platforms not yet known had to take measures to make implementations as easy as possible. Conformation to open or industry standards helped a lot. If software was delivered including the sources so the client could modify the software to suit his (changing) needs with the obligation to make his changes available to other users of this software the term open source software comes to mind. Although open source software and open standards are strictly speaking not necessarily related, they are often mentioned in one breath, because people benefit the most if both are optimally available: easy (and thus cheap) deployment of applications. The open in OpenVMS just means that people can rely on the conformation to open standards in the OpenVMS operating system. OpenVMS is available not only on VAX hardware but also on Alpha and since 2004 also on industry standard IA64 hardware.

## Purpose

This guide will explain how to port opensource software to OpenVMS using the features introduced in the DII COE releases of OpenVMS (7.2-6C1 & 7.2-6C2). The guide does not specifically target these versions of OpenVMS but these were the first public versions of OpenVMS with some of these new UNIX features. To be more specific, OpenVMS versions 7.3 7.3- 1, 7.3-2 and up. The latest OpenVMS version (OpenVMS 8.4) has the most of these new features. Because the development of the porting tooling is progressing fast and more portability features will be added to OpenVMS in the future, we will regularly update this guide. Many open source projects use UNIX shell scripts to build and install. We will be looking on how to do the same thing on OpenVMS using the UNIX commands and utilities provided by the GNV kit. We will not look at porting open source software to older versions of OpenVMS, although some of these older versions are still supported. Porting to these older versions of OpenVMS can be done, but it is considerably more difficult.
Intended audience Basically everybody with interest in open source software. If everything was perfect this would be the only requirement, but alas, things are not perfect. In the current versions of open source software OpenVMS is seldom recognized or considered as a target platform. We think (and hope) this will change soon. In the meanwhile porters will benefit from some programming experience. C and/or C++ experience on OpenVMS or UNIX systems is a big plus. Other languages often used in open source world are bash, make and perl. System management experience is more a requirement because porting may require making adaptations to the porting environment on OpenVMS.

## Acknowledgments

We would like to thank all the people who contributed in any form to this guide. There are many people who contributed material, thoughts or inside information. Without their contributions this guide wouldn't be as useful l as it is now.

# Part I Open source, Unix and OpenVMS
## Open source versus propriety software

This guide will not start with a in depth philosophic discussion about the difference between Open source, Freeware, shareware and propriety software. Instead we prefer to follow the definitions given in the following publication:
These definitions and the legal implications the various license agreements have, are for our purpose not relevant. We will concentrate on the technical aspects of the process of the port of open source software to OpenVMS.

## Unix, Linux, Open Unix standard

As the majority of the open source software originates from a form of UNIX, we will have to know the characteristics of this type of platform and the differences between these platform and the target platform: OpenVMS. This is simpler said as done, as there are as many different implementations of UNIX as there are suppliers of hardware and operating system software. Starting in the early days of UNIX, when the universities not only had access to UNIX, but also had access to the source of the operating system, different solutions to common problems emerged. This resulted in a family of related operating systems commonly known as UNIX. Ownership of the UNIX brand name passed hands and the situation became rather confusing. Who had the one and only UNIX? So, people started to define standards (alas not one standard...) by which a "real" UNIX could be recognized. At <reference> is a comparison between the following UNIX standards with the OpenVMS features: XSI, POSIX Base, Unix 98, Unix 95, P96 P92, C99, C89, SVID3, BSD, LSB 1.3
LINUX is a very popular UNIX like operating system, available in many different distributions, each with slightly different characteristics.Making software for such a divers environment was a nightmare. But very inventive software developers found a solution. The solution was two fold:
* Define and enforce a minimum set of features through standardization, much like the RFC's for TCP/IP.
* Automate the build process by using a set of tools capable of finding and reacting (adapting) to differences between platforms. This led to the development of autoconf, automake and libtool. These tools are also known as the GNU autotools environment (http://sources.redhat.com/autobook/)

## OpenVMS, open standards

OpenVMS on the other hand is a propriety operating system owned and maintained by HP. There are a few initiatives to make OpenVMS clones (for instance freeVMS (http://www.freevms.net)), but in this guide we will concentrate on the OpenVMS operating system from HP. As stated in the SPD (software product description) OpenVMS conforms itself to a set of Open Standards. Open standards means in this respect that a standardization organization is responsible for the exact text of a standard. Full conformation to this standard means in our opinion that a product will be adapted to the standard if a difference is found, not the other way around (adapting the standard to the behavior of a product, as is mostly the case with so-called industry-standards). The open standards that are most interesting for open source to OpenVMS porters are:
* Distributed Computing Environment (DCE) Support
* Support for OSF/Motif and X Window System Standards (X11R6 server and X11R5 client)
* ANSI X3.4-1986: American Standard Code for Information Interchange
* ANSI X3.41-1974: Code Extension Techniques for Use with 7-bit ASCII
* FIPS 1-2: Code for Information Interchange, Its Representations, Subsets, and Extensions
* ISO 646: ISO 7-bit Coded Character Set for Information Exchange
* ISO 2022: Code Extension Techniques for Use with ISO 646
* ISO 3307: Representations of Time of the Day
* ISO 4873: 8-Bit Code for Information Interchange - Structure and Rules for Implementation
* ISO 9660: Information Processing - Volume and file structure of CD-ROM for information exchange

## Open source on OpenVMS

The question here is not, can we have open source software on OpenVMS, because you're already using some open source software. CDSA is an open source security framework that is now used on OpenVMS. You cannot install current releases of OpenVMS without it. There are two CDSA add-ons, SSL and Kerberos. Both are open source. In the TCP/IP package you'll find BIND and DHCP from the Internet Software Consortium. And what about the SMTP, POP, IMAP, SSH.... These are just some packages that are part of the standard OpenVMS distribution. But there's more, there's Apache, Mozilla, Samba, MySQL, Tomcat, Perl, Python. Then there's the business rationale of open source. Why should you, or your company use open source software. This is not as simple as many people think. The fact that open source is free does not necessarily mean that it is cheaper to run for you or your company. Because of the complexity of the subject we would like to point you to a good book on the subject:

## OpenVMS-UNIX differences

The best way to compare UNIX and OpenVMS is probably by way of a table with a side by side comparison of the interesting aspects. <reference> is such a table.This is but a partial list. It is probably best to point you to some good books on the subject. From John Wisniewski, who was the driving force behind the OpenVMS Hobbyist program, is the excellent book:
The following book is written to make life easier for OpenVMS literate people new to the UNIX environment:

# Part II: build the open source porting environment on OpenVMS
## Build the OpenVMS porting system

The first step in the porting process is getting a suitable OpenVMS system up and running. Although OpenVMS is available on three hardware platforms, only two of them are sufficiently equipped to do serious opensource porting: Alpha and IA64. The VAX platform lacks support for some important features in a stand-alone configuration. VAX OpenVMS for instance lacks support for native ODS5 and GNV. Because most people only have access to Alpha systems and because IA64 OpenVMS is for the most part, functionally equal to Alpha OpenVMS, all examples are based on Alpha OpenVMS. In the reference section of the www.oooovms.dyndns.org website are examples of steps involved in building a OpenVMS system. There are documents about upgrading firmware, initial installation of OpenVMS, first boot and initial configuration of OpenVMS.

#### Installation of OpenVMS 8.4 on an Emulator

To make an optimal environment we need to give some attention to system parameters, some system file sizing and process quota and settings. Lets proceed with the system parameters.

### System parameters

OpenVMS system parameters are very much like UNIX kernel parameters. System parameters take effect at system boot time, although there are system parameters that can be changed and have immediate effect on a running system. So, unless you want to reboot often, you should take some time to set the system parameters to their correct values for your system. New values for system parameters should be edited in the sys$system:modparams.dat. This file is node specific and should contain all changes you want to take effect to next time the system boots. This file is read by the autogen procedure. We recommend you comment on all changes in this file. CHANNELCNT should be set to a value at least as big as the UAF FILLM value. A good practice is to set the value to the biggest value of: the current value, the largest UAF FILLM value and 4096. Note that the SDK process will have the lower value of the UAF quota FILLM or the SYSGEN parameter CHANNELCNT.
Part of a modparams.dat:
After you made the necessary changes to sys$system:modparams.dat invoke the autogen procedure:
You can check the results of this procedure as follows:
If you are satisfied with the generated or changed system parameters, reboot the system when it suits you best:

### Other settings

PAGEFILESIZE When you increase the PGFLQUO UAF parameter, you should also increase the system's page file size as needed to accommodate the new PGFLQUO parameter. Autogen (see the system parameters section) also calculates new values for the swap, page and sysdump files, unless instructed not to do so by specifying a directive in sys$system:modparams.dat or by not specifying the genfiles phase. You can also use the sys$update:swapfiles.com procedure to set the pagefilesize manually:

## Installing GNV
### Introduction

GNV stands for GNU is not VMS. It is a set of open source commands and utilities that are ported to OpenVMS. The GNV kit contains a port of the bash shell, the gnu diff utilities, the gnu file utilities, the gnu find utilities, gawk, grep, gzip, less, gnu make, man, sed, gnu shell utilities, gnu text utilities, (un)zip, a vi wrapper for tpu, vms(un)tar and wrappers for ar, cc, gcc and cpp. This list is not complete and more UNIX utilities become available with every new version of the GNV kit. GNV is an open source project with a web page http://gnv.sourceforge.net and several mailing lists. If you are planning to add tools to GNV, join the gnv developer list.

#### Installation:

First download the latest kit from the OpenVMS open source page at http://www.openvms.compaq.com/opensource or from the GNV project page at http://gnv.sourceforge.net. Print the installation instructions and use them to install the kit. Please read it carefully because it contains some important information. The requirements for installing and using GNV are:
* must install on an ODS-5 disk
* must use on an ODS-5 disk
To check the installation disk use the following command:
And this is not all the information but the important bit is at the bottom of the example text. Right after the Volume Status: header it says ODS-5 in this case. So this disk should be OK for use. Also note that hard links are enabled. For UNIX portability it is generally a good idea to have this enabled. It is also a good idea to enable access dates on a volume because this is a POSIX requirement. We also recommend using multi member shadow sets. First of all, shadow sets are more secure, i.e., you won't lose all your data when a disk breaks down, but also because shadow set names have no “$”-sign in them. The “$”-sign has a special meaning in UNIX shell scripts. To use a “$”-sign in a name you'll have to escape the “$”-sign with a “\”-sign.By the way you can and should at least use single member shadow sets to prevent this got-ya. To make a disk ODS-5 compatible use the following command:
To enable hard links and access dates use the following command:
Be aware that enabling hard links can take a considerable amount of time! Everything you ever wanted to know about shadowing and a description on how you can mount your disks as shadow sets is described in the OpenVMS documentation: HP Volume Shadowing for OpenVMS. The “help” command can help you as well.
Another thing I would like to note here is high-water marking. This is another typical OpenVMS security feature that is on by default. High-water marking guarantees that a user cannot read data that was not written by the user, by destroying all data in the disk block after the EOF marker. There is a small performance penalty in doing this. Although the penalty is only marginal these days, many people will advice you to turn it off. You can do so by giving the following command:
Disabling high-water marking is not mandatory for the installation of GNV or the UNIX portability.
To do a default install of the current GNV software, follow these steps also described in the documentation:
* Log in to the SYSTEM account (at the login prompt, enter user name SYSTEM and the appropriate password), or an account with equivalent privileges.
* At the DCL prompt ($), go to the directory where you saved the executable you downloaded from the Internet and extract the PCSI kit by running the executable:
* Type the following command, as shown:
* When you enter the PRODUCT INSTALL command, the system responds with a display similar to the following:
Continue the procedure by pressing the ENTER key for the default answer (YES). The procedure might take several minutes and numerous messages might be displayed on the screen. In response to each prompt displayed by the system, choose the default answer by pressing the ENTER key.
* To use GNV we need to do some system wide setup. To do this we start the following DCL command procedure:
To do this setup every time we boot our system we need to add the above command to the system startup procedure SYS$MANAGER:SYSTARTUP_VMS.COM. So fire up the editor:
Go to the bottom of the file (DO bottom) and enter the following lines before the $ EXIT:
And exit the editor with <Crtl>Z. Note: The GNV$STARTUP.COM procedure uses the procedure sys$common:[sys$startup]gnv_destination.com to define the location where GNV was installed. You will have to modify this procedure if you move GNV to a different location by hand.
* There's also some user setup that we'll need to do. For our current login session do the following:
And if we want this user setup to happen when you log in, we must add the above line to our SYS$LOGIN:LOGIN.COM. This counts for every user on your system who wants to use the GNV tools. If we want this to happen for every user on our system, we could add the line to the system wide login procedure SYS$MANAGER:SYLOGIN.COM ($ EDIT 'F$TRNLNM(“SYS$SYLOGIN”)'.COM). Just remember to add the line before the EXIT statement (login scrips usually do things depending on the current mode login (F$MODE), note that the gnv setup procedure must be made to work in interactive mode if you plan to use it on the command line). And of course, no reboot is needed.

## Process quotas

Managing process quotas is another OpenVMS stronghold. It allows the system to manage the system resources and maintain an acceptable performance for all processes on the system. The following recommendation comes from the July 2003 issue of “Optimizing Java Technology Software Performance on HP OpenVMS”. You can find this document at the HP OpenVMS e- Business Technology page http://www.openvms.compaq.com/ebusiness/technology.html. Please note that the suggested quota's are a minimum requirement for UNIX compatibility. These quota's are specified for user accounts running JAVA applications, but in general its a good idea to give porters and users running ported open source software the same quota's. The look and feel (performance) on OpenVMS will more closely resemble the look and feel on other platforms.

### Account quotas

Log is as user SYSTEM and go to the SYS$SYSTEM directory:
Start the account management program:
Show your account settings (in the example below the DEFAULT account is shown, this is a special account used for account creation):
We are going to change the following minimum account quotas:
| Name | Value |
| Fillm | 4096 |
| Wsdef | 2048 |
| Wsquo | 4096 |
| Wsextent | 16384 |
| Wsmax | 16384 |
| Pgflquo | 2097152* |
| bytlm | 400000 |
| biolm | 150 |
| diolm | 150 |
| tqelm | 100 |
To change the values of the parameters do the following:
You can change multiple parameters in th same command just add another /= for each value you need to change. To change the WSDEF, WSQUO and WSEXTENT for the DEFAULT account you would enter the following command:
You exit the AUTHORIZE utility by typing EXIT, or
(It may be possible that the terminal emulator you are using correctly maps the EXIT function to the F10 function key). As said before, the DEFAULT account is used as a template for the creation of new accounts. If you want to raise the default quotas for all new accounts you are going to create on your system, it may be a good idea to modify the DEFAULT account. Changing the default account will not change any setting for existing accounts. Check and modify existing accounts as needed.

## Setting up porting accounts

So far we have set the correct environment for our porting attempts. Lets summarize the steps involved. To create porting accounts one has to follow a few steps:
* Setting up the OpenVMS porting system with the right system parameters
* Installing and starting GNV, compilers and other porting tools
* Setting up the default UAF account
* Creating additional porting accounts and/or modifying existing accounts.
* Creating and modifying home directories for porters.
After that, in order to use the changed account settings, you must log out and back in again.

### Creating additional accounts

To create additional porting accounts, you can use the following commands:
A procedure for creating a number of porting users including a example run can be found in appendix 3

# PART III: Hints and tips on using the porting environment and the GNV tools
## Working with GNV

When you have installed GNV correctly you should be able to use UNIX commands like ls right from DCL. However if you have LSE installed the ls command will start the LSE editor instead. When you type bash at the DCL prompt. The bash shell is started and from that point on everything works as if you were using a UNIX box. There are however some minor but important differences. You may know that UNIX systems use a hierarchical file-system and OpenVMS does not. However some of the important hierarchy is mimicked under OpenVMS. By default the / directory points to the OpenVMS GNU:[000000] directory. The /bin directory points to the OpenVMS GNU:[bin] directory. Etc. In short the / directory is not the root of a disk! You can access other locations by typing /device-name or concealed device logical/directory. I.E. DSA50:[kits.gnu] becomes /dsa50/kits/gnu. When in bash you can enter most DCL commands, unless there is a name conflict like the ls - LSE problem. In that case you can enter the bash dcl command and enter the DCL command behind it. I.E. the DCL LS Readme command becomes dcl “ls Readme” in bash and opens the Readme file in LSE. If you don't want bash to “Fall Back” to DCL to execute commands, do the following in BASH:
We recommend putting this command in the .bashrc procedure in your login directory. See the example procedure in the “creating additional accounts” section. By the way you can always use the BASH dcl command to execute any DCL command!

## Tips

* always work on ODS-5 disks
* always enable ODS-5 extended filename parsing
(you can put this line in your LOGIN.COM)
* because of the way bash handles pipes at the moment we need to do the following
(you can put this line in your LOGIN.COM)
* the best way to handle UNIX symbolic links is to use hard links on the disk you are working from
Please note that this can take a considerable amount of time.
* it may be necessary to support POSIX style access dates
* when running configure scripts, it may be a good idea to disable DCL fall back
(you can put this in your .bashrc)
If you want to know more about using UNIX or bash, there is plenty of information available on the Internet. If you like books better, take a look at the offerings from O'Reilly http://www.oreilly.com/. I suggest you do take some time to learn the UNIX environment before continuing.

# Part IV: Building open source software

Most of you probably know that open source means that the software is usually distributed in source form. To use the software on your system you need to build it yourself. To make this building much easier the GNU community developed the GNU build tools. These tools not only make your life much easier, they also make the life of the open source developers much easier. Now let's look at how you would build some open source software on a UNIX or Linux box.
* Download the source distribution from the Internet. Most of the time this will be a .tar.gz file but you'll also find .tgz, .tar.Z .tar.bzip2 or .zip files.
* Create a directory
* Go to the directory you just created
* Unpack the file (some options may not work on OpenVMS yet)
** .tar.gz
*** % zcat <filename> | tar xvf or
*** % tar xvzf <filename> or
*** % gunzip <filename> and % tar xvf <filename - .gz>
** .tgz see .tar.gz
** .tar.Z see .tar.gz or
*** % uncompress <filename> and
*** % tar xvf <filename - .Z>
** .tar.bz2
*** % bz2cat <filename> | tar xvf - or
*** % bunzip2 <filename> and
*** % tar xvf <filename - .bz2>
** .zip
*** % unzip <filename>
* Look for the configure script. This script may be in the directory you're in, but it may also be in the directory that was created by unpacking the distribution file. I.e. If the file you downloaded from the Internet was called tar-1.2.4.tar.gz it is possible that you now have a directory named tar-1.2.4 in your current directory. Enter that directory to look for a configure file. If you don't find one look for files with uppercase names like README or INSTALL.
* When you found the configure script, run it
* When all go's well you can build the executable(s)
* And install the package (usually you must first become the root user before you can install something)
And that's all folks.
Well, that was all when everything works the way it's supposed to. And even on a UNIX box things can go wrong. To analyze what went wrong do the following:
* read the files with uppercase names and find out if you meet the prerequisites, find out if you need to do something special for your UNIX (OpenVMS) version (after all UNIX (OpenVMS) != UNIX)
* try ./configure --help this may give you an idea about extra parameters you may have to specify with the ./configure command.
* check the files that were generated by the configure script: config.cache, config.log, config.status, config.h and Makefile(s)
If this didn't help you may need to make your hands dirty.

## The GNU build system

Didn't I say before that the GNU build system would make your life much easier? Well it does. But let me first explain what may go wrong in the last example. The configure script and the Makefile.in file(s) may have been created before your UNIX (OpenVMS!) system or system version came into existence, so it doesn't know about your systems specifics. Thinking about OpenVMS for a moment, probably none of the configure scripts and make files out there, know anything about our GNV environment on OpenVMS. But let's get back to the problem at hand. To make the configure script and the Makefile.in file(s) aware of our systems specifics we will need to add some steps to our build example. The following steps come between steps 5 and 6:
a.
b.
c.
To make this work, your system should have these packages and GNU make, m4, texinfo and GNU tar readily installed. For most open source UNIX clones like Linux, FreeBSD, NetBSD and MacOS X, this is true. But for many commercial UNIX systems this isn't the case. As for OpenVMS, only GNU make is available at the moment. The best thing for most commercial UNIX systems is to check out if the manufacturer of your UNIX system made the missing tools available for download. If not check out the latest versions of the missing tools from the GNU web site. If nothing worked out, you are in the same position as us with our GNV environment on OpenVMS. At this point I think that it should be clear to us that we need all these tools a.s.a.p. If you want to know more about the gnu build system, take a look at the following web site(s): GNU Autoconf, Automake and Libtool: http://sources.redhat.com/autobook/

## Recommendation for OpenVMS

Because of constant updates to GNV we recommend to get the latest GNV sources from the CVS repository and build the GNV kit yourself. See the build instructions on http://www.4ovms.dyndns.org. Don't forget to raise the pipe buffer size.
And don't forget to disable DCL fall back.
Always check the configure script for conftest.dir. Change the name of this file to something like conftest.ddd
Use the configure option --build=. For OpenVMS Alpha the configure option is --build=alpha-hp-vms. Because the GNV bash version is somewhat outdated, some shell scripts do not work. One of those scripts is called depcomp. This script is used to determine dependency's during compilation. To get rid of this dependency checking, you can add the --disable-dependency-tracking option to the configure command.

## The OpenVMS C runtime library

The C Run Time Library or CRTL is an OpenVMS shared library containing most of the “standard” C functions. I quoted the word standard because a) there are a lot of standards and I didn't say which one. b) every standard is bit of a moving target.Since the DII COE initiative, HP intends to make the CRTL compliant to the latest X-Open standard. Because of the architectural differences between OpenVMS and UNIX this is not an easy task, especially if you also want to maintain backwards compatibility.The OpenVMS CRTL developers decided to add these new features gradually with every new OpenVMS and CRTL release.HP also decided that these new features will become available on both the Alpha and the new Itanium architecture. Some features may also become available on the VAX, but because ODS-5 extended filename support is not available on the VAX, the functionality that is essential to open source porting will probably never become available on the VAX.The new CRTL features can be categorized in two groups:
* existing functions with new and more standard functionality
* completely new functions to make the CRTL more standard (X-Open v.6) compliant.
For the functions in group one the classic behavior is standard and to use the new functionality you need to set feature switches (more on those later).The functions in group two can be divided in two more groups
* functions that should work the same in both the classic OpenVMS environment as in the new UNIX like environment
* functions that should not work the same in both environments
For this last group, think about functions that use or return a path. For this group the behavior of these functions is determined by the previously mentioned feature switches.

### So what are these feature switches and how can I set them?

I will not explain what feature switches there are and what they do exactly because you can read all about them in the CRTL help, the CRTL release notes and the CRTL Reference manual. But I will show you some of the interesting new ones in OpenVMS 8.4. And I will show you how you can change their values. So let's first get to the most interesting new feature switch, especially when you're new to porting. It is DECC$UNIX_LEVEL. The text below is from the CRTL reference manual (CRTL 1-36):
With the DECC$UNIX_LEVEL logical name, you can manage multiple C RTL feature logical names at once. By setting a value for DECC$UNIX_LEVEL from 1 to 100, you determine the default value for groups of feature logical names. The value you set has a cumulative effect: the higher the value, the more groups that are affected. Setting a value of 20, for example, enables all the feature logicals associated with a DECC$UNIX_LEVEL of 20, 10, and 1.
The principal logical names affecting UNIX like behavior are grouped as follows:
Level 30 is appropriate for UNIX like programs such as BASH and GNV.
The DECC$UNIX_LEVEL values and associated groups of affected feature logical names are:
Notes:
* Defining a logical name for an individual feature logical supersedes the default value established by DECC$UNIX_LEVEL for that feature.
* Future revisions of the C RTL may add new feature logicals to a given DECC$UNIX_LEVEL. For applications that specify that UNIX level, the effect is to enable those features by default.
Please note that not all the available feature switches are listed in the quote. The ones not listed are not part of any UNIX level! Read the CRTL help, release notes and documentation for a full list of supported feature switches and their intended use. You may already have noticed one way of setting these feature switches. You can define a logical with the same name and appropriate value. And because the feature switches alter the behavior at runtime, you don't have to recompile while playing with the switches. But when you are finished determining the appropriate values for the switches you may want to set their values from within your program. You can of course do this by setting the logical from within your program, but there is a much better way. The CRTL functions decc$feature_get_index, decc$feature_get_name, decc$feature_get_value, and decc$feature_set_value are specially designed for this task.
Below you'll see a small example program:
It is not too difficult to add code like this to a program, but there's a catch. Feature switches like DECC$ARGV_PARSE_STYLE need to be set before the arguments are being parsed and this happens somewhere between image activation and the call to the programs main function. The process of what happens before your program starts is documented in the OpenVMS Programming Concepts Manual. In chapter 18 you'll find a complete flow of what happens and when (see picture below).
'insert Picture'
The important thing to note here is the LIB$INITIALIZE function. What we are going to do is create a source file that defines a LIB$INITIALIZE function that points to a function that sets the feature switches to their appropriate values. Now let's go back to the example I used above. An enhanced version of the example is presented below:
Put both parts of the example in one source file. Compile and link with your program to make it work. The beauty of it is that you don't have to change the program you are porting to set the feature switches! If you want to see a more complete example, take a look at GNU:[src.GNV.CRTLSUP.SRC]]VMS_CRTL_INIT.C file. This file is used by some of the GNV tools.

## Recommendation

A good starting point is UNIX level 30, but don't use the DECC$UNIX_LEVEL feature switch. Set the individual feature switches that make up UNIX level 30 and increase DECC$PIPE_BUFFER_SIZE to at least 8192. The reasons for not using the DECC$UNIX_LEVEL feature switch are compatibility with OpenVMS 7.3-1 and the simple fact that you may not need all the feature switches that make up level 30 or you want to use different values (see the recommendation for DECC$PIPE_BUFFER_SIZE).

## Macros
### Predefined macros

The list below is a list of predefined macros on OpenVMS 7.3-2 Alpha using the Standard DECC C compiler version 6.5.
The following macros are important for porting:
| Macro | Remark |
| VMS, vms | Are the ones we can use for general OpenVMS specific stuff |
| ALPHA, Alpha_AXP, __alpha | Can be used for Alpha specific stuff |
| VAXC, VAX11C, vaxc, vax11c | Can be used for VAX specific stuff |
| IA64, ia64 | Can be used for Itanium (ia64) specific stuff |
| __VMS_VER | Can be used for OpenVMS version specific stuff (please use __CRTL_VER instead |
| __DECC_VER | Can be used for compiler version specific stuff |
| __CRTL_VER | Can be used for CRTL version specific stuff |
Please note that I only included the preferred format of the macros, most of them also exist without the two dashes in front.

### Other macros

There are also numerous other macros that change the behavior of one or more CRTL functions.
| Macro | Remark |
| _XOPEN_SOURCE_EXTENDED | Makes visible XPG4-extended features, including traditional UNIX based interfaces not previously adopted by X/Open. Standard Selected: XPG4 V2. Other Standards Implied: XPG4, ISO POSIX-2, ISO POSIX-1, ANSI C |
| _XOPEN_SOURCE | Makes visible XPG4 standard symbols and causes _POSIX_C_SOURCE to be set to 2 if it is not already defined with a value greater than 2. Standard Selected: XPG4. Other Standards Implied: XPG4, ISO POSIX-2, ISO POSIX-1, ANSI C |
| _POSIX_C_SOURCE==199506 | Header files defined by ANSI C make visible those symbols required by IEEE 1003.1c-1995. Standard Selected: IEEE 1003.1c-1995. Other Standards Implied: ISO POSIX-2, ISO POSIX-1, ANSI C |
| _POSIX_C_SOURCE==2 | Header files defined by ANSI C make visible those symbols required by ISO POSIX-2 plus those required by ISO POSIX-1. Standard Selected: ISO POSIX-2. Other Standards Implied: ISO POSIX-1, ANSI C |
| _POSIX_C_SOURCE==1 | Header files defined by ANSI C make visible those symbols required by ISO POSIX-1. Standard Selected: ISO POSIX-1. Other Standards Implied: ANSI C |
| STDC_VERSION__==199409 | Makes ISO C Amendment 1 symbols visible. Standard Selected: ISO C Amendment 1. Other Standards Implied: ANSI C |
| _ANSI_C_SOURCE | Makes ANSI C standard symbols visible. Standard Selected: ANSI C. Other Standards Implied: None. |
| _POSIX_EXIT | To enable the ISO POSIX-1 compatible exit function. |
| _BSD44_CURSES | This macro selects the Curses package from the 4.4BSD Berkeley Software Distribution. |
| _VMS_CURSES | This macro selects a Curses package based on the VAX C compiler. This is the default Curses package. |
| _SOCKADDR_LEN | This macro is used to select 4.4BSD-compatible and XPG4 V2- compatible socket interfaces. These interfaces require support in your underlying TCP/IP software. Contact your TCP/IP vendor to inquire if the version of TCP/IP software you run supports 4.4BSD sockets. (HP TCP/IP supports this feature, as far as I can tell, Prosess Softwares Multinet and TCPware don't) |
| _LARGEFILE | The C RTL provides support for compiling applications to use file sizes and offsets that are two gigabytes (GB) and larger. This is accomplished by allowing file offsets of 64-bit integers. |
| __USE_LONG_GID_T | To compile an application for 32-bit UID/GID support. |
| _DECC_SHORT_GID_T | To compile an application for 16-bit UID/GID support |
Please read the CRTL help and/or CRTL Reference Manual for more information.

## Recommendation

Please don't use general macros like VMS, vms , or __vms. Use CRTL_VER instead. The C Runtime Library is becoming more “standard” with every new version of the CRTL. Fixes may no longer be necessary in newer versions of the CRTL. In some cases program functionality has been crippled with #ifndef VMS in a way that is no longer necessary. Using CRTL_VER will allow us to control more precisely what needs to be changed for the many different versions of the CRTL. When the macro CRTL_VER doesn't exist, define it with the value of __VMS_VER.
When compiling open source programs in DCL, add the /DEFINE=_POSIX_EXIT to your CC command! This is the default when compiling under bash.

## GCC wrapper

The GNV kit does not come with gcc but with a wrapper that uses HP C and C++ compilers to do its compilation work and it uses the standard OpenVMS Linker as a substitute for ld. By the way there is also a ar wrapper that uses the standard OpenVMS Librarian.The GCC wrapper does quite a good job, but it isn't perfect. Also note that the HP compilers are very strict. By this I mean that they complain immediately when something may not be entirely correct. So we'll see a lot of warnings when compiling open source software.You can see all the options the gcc wrapper supports by using the -h or -help option.I would like to note the following on the behavior of the GCC wrapper, the wrapper adds the /DEFINE=_POSIX_EXIT to the compile statement by default.The -Wc and -Wl gcc option may come in handy if you want to add a HP CC, CPP or LINK option to the gcc command line, that does not seem to be implemented.One gcc option you sometimes need is -names_as_is_short. This will make the compiler case sensitive and it allows function names with more than 32 characters.You may get into trouble with the gcc -g option in configure scripts. Many configure scripts use this option by default. This options is used to compile and/or link with debug information included in the program. The problem is that on UNIX systems a program compiled and linked with debug information doesn't start the debugger when executed. This is quite different from what we OpenVMS people are used to. If you see the debugger prompt pop up when running a configure script, either remove the -g option from the configure script or start configure with CFLAGS=””.

## Fork

The fork issue is quite high on the issue list because it is quite common to Open Source programs and we don't have this function on OpenVMS. We do have vfork on OpenVMS, but the implementation of vfork on OpenVMS is also not standard compliant. We can however use it to work around most of the fork calls in opensource software. Before we dig into the workarounds, lets first determine what fork is supposed to do. The fork function is the UNIX standard way to create a new process. The new (child) process is an exact duplicate of the calling (parent) process except:
* the child process has a unique process ID
* the child process ID does not match any active process group ID
* the child process has a different parent process ID
* the child process has its own copy of the parent's open file descriptors
* the child process has its own copy of the parent's open directory streams
* the child process may have its own copy of the parent's message catalog descriptors
* the child process' values of tms_utime, tms_stime, tms_cutime and tms_cstime are set to 0
* the time left until an alarm clock signal is reset to 0
* all semadj values are cleared
* file locks set by the parent process are not inherited by the child process
* the set of signals pending for the child process is initialized to an empty set
* interval timers are reset in the child process
After fork, both parent and child processes are capable of executing independently before either one terminates. The fork function returns 0 to the child process and returns the process ID of the child process to the parent process. Otherwise, -1 is returned to the parent process, no child process is created and errno is set to indicate the error. The vfork function is on most systems identical to the fork function. On some systems, child's created with vfork can share data or code segments with their parent process. On OpenVMS the vfork function only provides the setup necessary for a subsequent call to an exec function. No child process is create by a vfork call! When vfork is called:
* it saves the return address (the address of the vfork call) to be used later as a return address for the call to an exec function
* it saves the current context
* it returns the integer 0 the first time it is called (before the call to an exec function is made). After the exec call is made, the exec function returns control to the parent process, at the point of the vfork call, and returns the process ID of the child as the return value.
Some of you may already see some similarities between fork and OpenVMS vfork. If fork is closely followed by an exec call, we can use OpenVMS vfork with a little work. If fork stands on it's own, we're still screwed.
Example 1 (from GNU tar 1.15.1 lib/rmdir.c):
Example 2 (from GNU tar 1.15.1 lib/rtapelib.c):
This second example may look a little intimidating but remember that on OpenVMS the “Child” code is actually executed by the parent. The “Child” process is created by the execl function call not by the vfork function call.
Note 1: By default the OpenVMS exec call's use LIB$SPAWN to create child processes. In most cases this is what you want, however in some cases you may want the child processes to be a detached processes. To achieve this you can enable the DECC$DETACHED_CHILD_PROCESS feature switch. This has some implications. See CRTL Reference Guide chapter 5.
Note 2: On OpenVMS the execlp and execvp functions search VAXC$PATH and not the PATH environment variable to obtain the location of the file to execute. This can be quite problematic.

## RMS

RMS stands for Record Management System. The OpenVMS filesystem is built on RMS and all the files on an OpenVMS system are RMS files. An RMS file is record oriented and can contain keys for keyed access (RMS indexed files). There are many different kinds of records and countless record attributes in RMS. As with most record oriented systems, locking of files and records is something to be very aware of. UNIX doesn't have these features and on UNIX systems it is possible for two programs to have the same file open for writing at the same position in the file. On OpenVMS this is impossible and you have to deal with this problem when you run into it.Another problem is the difference between stream-lf files and variable-length records. Both files contain records of variable length, but from a UNIX programs point of view Stream-lf files best resemble UNIX files. However very few OpenVMS programs know how to handle stream-lf files. OpenVMS programs typically handle files with the variable-length record type.

## Known Porting Issues

Quite a few CRTL functions still don't quite work as their UNIX counterparts and some functions are still missing. To give you some examples:The vfork function does not behave exactly like its UNIX counterpart (read the section on vfork in the CRTL reference manual). If a program uses vfork it will probably check the existence of vfork during configure and this is also a situation where configure will hang. The solution to the hang is quite simple. Log in using a different session and look for the child process of your previous session. Kill it and the configure script continues.And while we're at it, OpenVMS unfortunately has no fork function yet, but there are many known workarounds available is only we know where.This is not a definitive guide on how to port open source to OpenVMS. Things are changing quite rapidly. We should continue to keep this document up to date with the current state of OpenVMS and the GNV kit.We found a list of known areas where compatibility problems occur when porting from UNIX to OpenVMS on comp.os.vms, This list is the basis for a list we maintain. This list can be found in appedix 2: List of known issues.
subject:Open source