Subject: Re: Port to VMS; how to get changes into the main code stream?

Re: Port to VMS; how to get changes into the main code stream?

From: John E. Malmberg <>
Date: Sat, 06 Mar 2010 20:19:37 -0600

Peter Stuge wrote:
> Jose Baars wrote:
>> - Will there be more functions defined in the libssh2 API?
> Yes, new functions can and will be added.

You can leave spare symbol vector entries at the bottom of the list.

Also generally you can always add symbol vectors.

>> Will the parameters of functions be subject to change?
> There are a number of incompatible API changes coming, but there is
> no plan made for them. In Linux and other Unix-like systems dynamic
> libraries have a version called soname, and the linker knows which
> version of the API each application requires, so it's possible to
> have more than one library installed without conflict, and the linker
> will always do the right thing.

With VMS, you use a logical name to designate where the shared image is
for any libraries not stored in SYS$SHARE:.

The general convention is that third party libraries like this are not
put in SYS$SHARE:

A different image name would be used for different incompatible
revisions of a shared image.

A startup script is added to the system startup that installs the shared
image and defines the logical name in the SYSTEM EXECUTIVE table.

System Executive names can be accessed by privileged programs.

I have registered the prefix GNV$ for the logical names installed in the
gnv directory tree. Per HP conventions, all system logical names used
by layered products are required to have registered prefixes.

If a product is setting an un-prefixed logical name, that is a bug.

Also the xxx$ in front of filenames also need to have the xxx
registered. Again, I have gnv$ registered for use with ported programs.

By HP rules, the GNV directories should be in GNV$GNU: not GNU: which
the current GNV kit uses. The startup script needs to look for both
names until HP fixes the GNV kit.

A program does not have to be built with GNV to use the GNV directories
to hold it. The GNV directory tree is a convenient one to use to match
Unix conventions.

I would recommend having a PCSI kit install and if needed create the
GNV$GNU: directory tree, and to put everything under GNV$GNU:[usr] which
will be seen by Unix programs as "/usr"

Also please include a VMSified xxxx.pc file if the libssh2 project has
one, and any of the documentation files in the same directories that
they would be on a Unix system.

One benefit of using the GNV style build is that you can run the UNIX
install procedure in a test mode to identify what files should be in the
binary kit and where they should be. Otherwise, you have to figure that
out some other way.

>> In other words: To what extent will libssh2 be upward compatible?
> The API will change at some point, and backwards compatibility may
> break. I don't know if and how that can be dealt with for VMS?

One way is to use different names for the shared image for the newer
incompatible version.

The way that most shared images on VMS use is to use a different
"Universal" symbol name for the new image, typically by adding a prefix
to it.

A Universal symbol is one that is visible outside the shared image.

The old entry point remains the same for existing programs to use, but
the header files will set a prefix to the new routines for newly built

If new parameters are added, then the va args method can be used. VMS
calling standard allows a routine to be changed from a fixed number of
arguments to one that takes additional optional arguments, as long as
the routine understands that.

Direct references to data in a VMS shared image is a pain, because it is
difficult to maintain backwards compatibility if the size of the data
changes. The trick that I have seen to do this is to only use functions
that return a pointer to that data. Then the header files use macros
that will change direct references to the data to call the routines.

Please start a libssh2 note in the PORTING_TO_VMS conference about your

Once you get a PCSI kit built, I can get it added to the FTP repository

I have not been signing the PCSI kits with certificates. I have not
seen if I could qualify for one of the free ones from godaddy, and they
only last a year, so I would have to re-sign them. I have been
considering using a self-signed one, but I do not see how that would
really add more security.


Received on 2010-03-07