ØMQ for OpenVMS Integrity Server

Caution: This article appiles to an old version of ØMQ (0.6)

Introduction

This port is being made available initially on Integrity (Itanium) Servers in the form of a software development kit from which we hope to gain experience and feedback from those downloading and using it. Depending on demand and time, we will make a version for Alpha available.

While ØMQ APIs were implemented to facilitate the development applications using C, C++ and Java, there is no particular reason why it cannot be used to develop ØMQ applications using practically any OpenVMS 3GL such as COBOL, BASIC, Pascal, or FORTRAN. A library with wrapper code which will facilitate the calling of the ØMQ API from high-level languages is provided in the package.

Requirements

The kit you are installing has been compiled and built using the operating system and compiler versions listed below. While it is highly likely that you will have no problems installing and using the kit on systems running higher product versions, this may not be the case if your system is running older versions. We shall be pleased to hear from you should you have a requirement for older versions and will do our best to accommodate these wishes.

  • An ODS-5 formatted disk for the installation
  • OpenVMS 8.3-H1 IA64
  • HP TCP/IP Services for OpenVMS Industry Standard 64 Version V5.6 ECO 3
  • HP C S7.1-013
  • HP C++ V7.3 (if you wish to build from source code)
  • Java V5 (optional)
  • UnZip 5.42 (or similar) for OpenVMS is required to unpack the kit

In addition to the above requirements, it is assumed that the reader has a good knowledge of OpenVMS and of software development in the OpenVMS environment.

Installation

Unpacking and installing the ZIP file kit is very straightforward. After copying the ZIP file (0MQ-VMS-I64-01.ZIP) to a suitable location, simply enter the following command to unpack the contents of the ZIP file. After unpacking the kit, you will have a [ZMQ-DEV] directory in your current directory that contains the files from the package.

$ unzip 0MQ-VMS-I64-01.ZIP

NOTE: please ensure your default directory setting is where you wish the contents of the ZIP file to be placed, prior to unzipping the kit.

Post-installation Steps

Environment setup

The installation provides a command procedure called zmqSetEnv.com which is to be found in the OpenVMS directory once the unzip is complete. You will need to make some minor changes in this file to reflect the disk and directory into which you unzipped the ØMQ kit. These changes are:

The value of the symbol baseLevel. This symbol defines the version of the software and is an optional input parameter to the zmqSetEnv.com procedure. For example:

$ baseLevel == "ZMQ-06" ! Change this where required

The device and directory for zmqRoot. This is a concealed device logical name. The location in zmqSetEnv.com highlighted in the following fashion:

$!++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
$! Change the following line to reflect the disk and directory
$! of the installation.
$!------------------------------------------------------------
$ define/translation=(terminal,concealed)/job zmqRoot -
        "''f$trnlnm("disk$ods5disk")'[hintjens.''baseLevel'.]"
$!++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
$! Change the line above to reflect the disk and directory
$! of the installation.
$!------------------------------------------------------------

zmqSetEnv.com invokes the SYS$STARTUP:JAVA$150_SETUP.COM procedure when it is present

Note: You may also wish to copy the zmqSetEnv.com file to a device and directory outside the ØMQ installation where it is more easily accessible. For example: SYS$STARTUP or the SYS$LOGIN of the installing username. In addition, you may wish to change the logical name table used from JOB to group or system or even create your own.

zmqSetEnv.com defines several logical names – in the JOB name table by default – which you might find useful.

For example:

"LNK$LIBRARY" = "libzmq:libzmq.olb"       ! Main 0MQ library
              = "libczmq:libczmq.olb"     ! C wrapper library

"LIBCZMQ"     = "zmqRoot:[libczmq]"       ! C 0MQ directory
"LIBJZMQ"     = "zmqRoot:[libjzmq]"       ! Java 0MQ directory
"LIBZMQ"      = "zmqRoot:[libzmq]"        ! Main 0MQ directory

"zmqBASE"     = "zmqRoot:[000000]"        ! Home directory
"zmqOpenVMS"  = "zmqRoot:[OpenVMS]"       ! OpenVMS-specific files
"ZMQ"         = "zmqRoot:[OpenVMS]"       ! Search list for include
              = "zmqRoot:[libzmq.zmq]"    ! files. For example:
              = "zmqRoot:[libczmq.zmq]"   ! platform.hpp
              = "zmqRoot:[libjzmq.zmq]"

Object Libraries

There are two object libraries shipped with the kit:

  • LIBZMQ:LIBZMQ.OLB – contains the core C++ routines against which programs must be linked
  • LIBCZMQ:LIBCZMQ.OLB – contains the entry points for programs written in C and other high-level languages
  • TODO: libjzmq, libvmszmq

Ensuring correct file protection

You may wish to ensure correct file protection by performing the following command:

$ SET FILE/PROTECTION=W:RE/EXCLUDE=*.DIR zmqRoot:[*...]*.*;*

This will, of course, grant read and execute access to all files below the zmqRoot:[000000] directory. Since developers will be copying files or including them in compile jobs, there should be no harm in having the files set for world read.

Java Interface and Programming

The JNI module and its associated Java CLASS file are to be found in:

  • LIBJZMQ:Jzmq.class – copy this file to the directory where you build any Java programs
  • LIBJZMQ:jzmq.exe – ensure the logical name jzmq has been defined to point to this file prior to running any Java programs.

For example:

$ DEFINE/JOB JZMQ LIBJZMQ:JZMQ.EXE

Note: the logical name can be defined in any name table visible to the process running the Java programs

Privileges and Quotas

Generally speaking there are no special process quota or privilege requirements for applications developed using ØMQ. The authors typically operate (on OpenVMS Integrity Servers) with quota settings similar to the following, which should be more than adequate for most purposes:

Maxjobs:         0  Fillm:      4096  Bytlm:      2000000 
Maxacctjobs:     0  Shrfillm:      0  Pbytlm:           0 
Maxdetach:       0  BIOlm:       900  JTquota:      16384 
Prclm:           0  DIOlm:       900  WSdef:         4096 
Prio:            4  ASTlm:       900  WSquo:        16384 
Queprio:         0  TQElm:       900  WSextent:     32767 
CPU:        (none)  Enqlm:      8192  Pgflquo:    2000000

Throughput and latency testing

The tests are pre-built and installed with the kit and may be found int zmqroot:[perf.tests]. The command procedures for building the scripts can be found in the zmqroot:[openvms] directory.

See ØMQ documentation on the test programs and how to run them.

Examples and Tutorials

The directory zmqRoot:[examples] contains several example programs that illustrate various aspects of the ØMQ.

The OpenVMS version of ØMQ ships with three examples:

These samples provide an excellent introduction to the AMQ APIs, and provide a useful basis for the development of more sophisticated applications.