PL/I for OpenVMS and Tru64

4.  Integration

Overview

The following sections provide a range of tools and libraries for integrating PL/I on OpenVMS with other native languages. Although all native languages on OpenVMS adhere to the common calling standard, there are some situations where building up the necessary modules and include files can be a large and drawn out task. The tools offered here attempt to ease this difficulty.

The following tools and libraries are currently available:

  • J2VMS, a interface between the Java Virtual Machine and the native calling standard of OpenVMS,
  • SDLEXT, a collection of Structure Definition Language (SDL) compiler backends that generate output for Java (to be used with J2VMS) and other languages;
  • XMLRTL, a run-time library that provides native SAX, DOM and XML-RPC APIs; and
  • PLI/SDL, a compiler extension for taking PL/I structure and entry declarations and generating SDL modules. This utility is currently in field test and is available to customers by contacting Kednos at sales@kednos.com.

Use the menu on the left hand side to navigate to the language integration you are interested in.

In many situations the tools presented here are as useful to other languages as they are PL/I. For example, the J2VMS Java->OpenVMS interface can be used to call routines and manipulate data structures from any language.

Examples

The following is a growing collection of complete working examples that attempt to properly demonstrate the use of these integration tools.

Phone Book

This example demonstrates the calling of OpenVMS native routines from Java, as well as the manipulation of data structures. The original program is an example PL/I application called PHONE (not to be confused with the OpenVMS PHONE utility). It is a simple progam that presents an example for file I/O and screen management as a phone book.

For the purpose of demonstrating the integration utilities the file access routines were extracted and put into a run-time library. A Java-Swing application was then developed that uses this RTL to access and update the phone book file.

The main objectives were to:

  • move the application to a Java-Swing based frontend,
  • re-use the existing file access routines,
  • avoid any major changes to the original application,
  • allow the original application to continue being used in parallel with the new Java application.

All of these objectives were met and the whole process is demonstrated in the article, Calling Native OpenVMS Routines from Java.

A backup saveset containing the full source for both the PL/I and Java-Swing applications can be downloaded here. The saveset is also available inside a ZIP file here.
PHONE - The original PL/I application
Source:
BUILD_PHONE.COM Build Procedure.
CONSTANTS.PLI Some helpful constants (include file).
DATABASE.PLI Utility routines for working with the phone book file.
ENTRY.PLI Database entry record definition (include file).
KEYS.PLI Keypad constants (include file).
OPERATIONS.PLI Menu operation constants (include file).
PHONE.FDL Phone book database file.
PHONE.PLI Main program.
SCREEN.PLI Screen handling support routines.
Description: The PHONE utility (not to be confused with the OpenVMS PHONE utility) is a simple phone/address book utility that maintains it's data in an indexed file. It originally appeared in the Kednos PL/I for OpenVMS example program library that ships with the compiler.
Build Instructions:

The following build instructions, as well as building the PHONE utility, also build the run-time library necessary to implement the jPhone utility shown below.

$ TYPE BUILD_PHONE.COM
$ PLI PHONE
$ PLI DATABASE
$ PLI SCREEN
$ LINK/SHARE=DATABASE_RTL.EXE,SYS$INPUT/OPTION
SYMBOL_VECTOR = ( -
    OPEN_PHONEBOOK = PROCEDURE, -
    CLOSE_PHONEBOOK = PROCEDURE, -
    GET_A_RECORD = PROCEDURE, -
    GET_A_MONTH_RECORD = PROCEDURE, -
    GET_A_DATE_RECORD = PROCEDURE, -
    WRITE_A_RECORD = PROCEDURE, -
    DELETE_A_RECORD = PROCEDURE -
    )
$ DEFINE/NOLOG DATABASE_RTL SYS$DISK:[]DATABASE_RTL
$ LINK PHONE,SCREEN,SYS$INPUT/OPTIONS
DATABASE_RTL/SHARE
$ IF (F$SEARCH("PHONE.DAT") .EQS. "") THEN CREATE/FDL=PHONE.FDL
$ EXIT 1
$ @BUILD_PHONE.COM
jPhone - The Java/Swing version of PHONE.
Source: Database.java (javadoc) Java class interface to the native DATABASE_RTL run-time library.
DATABASEDEF.java Java class generated from DATABASEDEF.SDL. It details the record structure of the phone book database file and the native routines found in DATABASE_RTL.
DATABASEDEF.SDL SDL header file, generated from DATABASE.PLI (above).
EntryPanel.java Panel for manipulating phone book entries.
EventPanel.java Panel for querying the phone book for upcoming events.
JPhone.java Main application.
Description: This application is the Java/Swing based version of the PHONE utility. It uses J2VMS to interface with the DATABASE_RTL run-time library so it can manipulate the same data file in a way that can be viewed by either the Java or native application.
Build Instructions:

$ TYPE BUILD_JPHONE.COM
$ set noon
$ on control_y then goto bail_out
$
$ set process/parse_style=extended
$ define/nolog decc$efs_case_preserve enable
$ define/nolog decc$efs_case_special enable
$ define/nolog decc$efs_charset enable
$ define/nolog decc$argv_parse_style enable
$
$ jc = "''javac' -classpath - "
     + """/sys$library/j2vms$vs.jar:./bin"" -d ""./bin"""
$
$ set verify
$ $ ! Database Interface
$ jc Database.java
$ jc DATABASEDEF.java
$
$ ! Supporting classes
$ jc UpperCaseField.java
$
$ ! Application
$ jc EntryPanel.java
$ jc EventPanel.java
$ jc JPhone.java
$
$ set noverify
$
$ jphone == "''java' -classpath " -
          + """/sys$library/j2vms$vs.jar:./bin"" com.kednos.jphone.JPhone"
$
$ write sys$output "Type: ""jphone"" to run"
$bail_out:
$ set noverify
$ exitt 1
$ @BUILD_JPHONE.COM

 

4.1  SDL

Overview

Structure Definition Language (or SDL) is a language for defining data structures, constants, external symbols and entry points. The SDL compiler is a tool for taking those definitions and generating language specific include files.

The SDLEXT product offers a collection of backends that generate output for the following languages:

  • Java, for use with the J2VMS interface
  • XML Schema Definition

Future releases of SDLEXT will also include generators for other languages and utilities. Currently Perl and record definitions for the DIX utility are planned.

Software

SDLEXT ships in a combined PCSI kit. This means that the single kit contains software that will install on OpenVMS VAX, Alpha and I64.

  • SDLEXT V2.0 PCSI software kit PCSI|ZIP.

The SDL compiler kit is available on the OpenVMS Freeware distribution. It is also available online here. The last release (EV1-65) of ALPHA_SDL can also be downloaded (including source) from here.

If for some reason you are unable to download the SDLEXT software and/or the SDL compiler supplied by HP we can provide physical media kits with all necessary software upon request.

Documentation

The following documentation covers the SDLEXT software product:

All manuals are produced using DECdocument from Touch Technologies, Inc.

Documentation for the SDL compiler and language can be viewed in either HTML, PS or PDF formats. The original VAX SDL RUNOFF manual can be viewed here.

Licensing & Support

SDLEXT is a comercial product available from Kednos Enterprises. License PAKs and formal support agreements are available and can be discussed further by contacting sales@kednos.com.

Evaluation licenses are available on request by contacting sales@kednos.com.

4.2  Java

Overview

J2VMS is a generic calling interface for accessing native code on OpenVMS. By using a collection of classes that mimic the argument passing mechanisms of compiled languages and a helper class that is reminiscent of LIB$CALLG it is possible to call any routine found in a shareable run-time library. Also included is the ability to manipulate OpenVMS data structures using a method similar to that offered in the BLISS programming language.

Originally conceived and written by Jim Brankin, J2VMS disappeared into obscurity for some time. Kednos has since resurrected this software package and begun active development of the interface. Below is documentation and software for the latest release.

Articles relating to J2VMS have been published in the OpenVMS Technical Journal. Calling OpenVMS Native Routines From Java was published in V12. WSIT and J2VMS: A Comparative Analysis is an unpublished article that attempts to compare the merits of HP's Web Services Integration Toolkit and Kednos' Java-to-VMS Toolkit..

Software

The following J2VMS software product kits are available for download:

  • J2VMS PCSI software kit, PCSI|ZIP. This kit contains V1.3 of J2VMS and is for both OpenVMS Alpha and I64.

The last release from www.j2vms.co.uk (now defunct), Version 1.2 is available from here.

Java for OpenVMS Alpha and I64 can be downloaded from HP at their website here.

If for some reason you are unable to download the J2VMS software and/or the Java software supplied by HP we can provide physical media kits with all necessary software upon request.

Documentation

The following documentation covers the J2VMS product:

All manuals are produced using DECdocument from Touch Technologies, Inc. and Javadoc from Sun.

For all Java on OpenVMS Alpha and I64 related documentation please visit the following HP websites:

For documentation related to the Java language and API then please consult the Sun website.

Licensing & Support

J2VMS is a comercial product available from Kednos Enterprises. License PAKs and formal support agreements are available and can be discussed further by contacting sales@kednos.com.

Evaluation licenses are available on request by contacting sales@kednos.com.

For all Java related support queries please consult the Java for OpenVMS Alpha and I64 software support pages.

Examples

The following are a collection of examples demonstrating the J2VMS interface. Some have corresponding native language examples that can be used to compare the two environments. All Java examples are included in the software product kit.

Hello World
Source: put.java (javadoc)
Description: This example simply demonstrates the declaration of an external routine (similar to the C extern construct) and calling it. In this case it is the routine LIB$PUT_OUTPUT writting that familiar message to the terminal.
Build Instructions: Assuming the correct J2VMS and Java setup has been preformed, the following commands should build and execute the example program.
$ javac -classpath "/sys$library/j2vms$vs.jar" put.java
$ java -classpath "/sys$library/j2vms$vs.jar:./" put

Get Some Input
Source: get.java (javadoc)
Description: This example fetches a line of input using the LIB$ Run-Time Library routine LIB$GET_INPUT and then writes it to the terminal using LIB$PUT_OUTPUT. This example demonstrates the use of the StringBuffer class to pass a dynamic string to LIB$GET_INPUT for receiving the resulting string.
Build Instructions:

Assuming the correct J2VMS and Java setup has been performed, the following commands should build and execute the example program.

$ javac -classpath "/sys$library/j2vms$vs.jar" get.java
$ java -classpath "/sys$library/j2vms$vs.jar:./" get

Disk Driver
Source: disk_driver.java
Description:

This program is an example that demonstrates the use of OpenVMS disk drivers using RMS and QIO services. It is based on the C module of the same name and produces identical results. The C version can be found in SYS$EXAMPLES or can be downloaded here. The following comments are from the module header:

  DISK_DRIVER -- Programming example to demonstrate use of
  OpenVMS disk drivers using RMS and QIO services.  The module
  first uses RMS $CREATE to create a file called MYDATAFIL.DAT in
  the default directory and then writes one hundred 512-byte (1 disk
  block) records, each of which contains the record number
  repeated 512 times, using RMS $PUT.  It then uses QIO services
  to access, randomly read and write, and close the file, swapping the
  contents of each pair of records.  If any errors are detected,
  the program exits with the error status associated with the
  error.
Build Instructions:

Assuming the correct J2VMS and Java setup has been performed, the following commands should build and execute the example program.

$ javac -classpath "/sys$library/j2vms$vs.jar" disk_driver.java
$ java -classpath "/sys$library/j2vms$vs.jar:./" disk_driver

Working With Locks
Source: lock.java
Description: This example demonstrates calling the $ENQW and $DEQW System Services from Java including modifying the lock value block.
Build Instructions:

Assuming the correct J2VMS and Java setup has been performed, the following commands should build and execute the example program.

$ javac -classpath "/sys$library/j2vms$vs.jar" lock.java
$ java -classpath "/sys$library/j2vms$vs.jar:./" lock

Get Some More Input
Source: get.java
Description: This example is from the J2VMS User Guide. It simply demonstrates the difference between passing java.lang.String and java.lang.StringBuffer objects by descriptor. It does this by requesting input from the user via the LIB$ Run-Time Library LIB$GET_INPUT.
Build Instructions:

Assuming the correct J2VMS and Java setup has been performed, the following commands should build and execute the example program.

$ javac -classpath "/sys$library/j2vms$vs.jar" get2.java
$ java -classpath "/sys$library/j2vms$vs.jar:./" get2

4.3  XML

Overview

The XML Support Run-Time Library (also referred to as XMLRTL) is a shareable image providing an OpenVMS calling standard friendly interface to some commonly used XML APIs.

Most XML APIs are intended to be used from a C or scripting language environment only. This can make it difficult for languages that do not support C-specific features to call these APIs directly.  It is often necessary for developers to implement a layer (usually written in C) between the API and the intended environment. With XMLRTL there is no necessity for this, sometimes, awkward layer.  XMLRTL functions can be easily called from any native OpenVMS language.

The following XML standards and recommendations are supported by XMLRTL:

XMLRTL is supported on OpenVMS VAX, Alpha and I64. It ships with include files for PL/I, BASIC, Pascal, Fortran, BLISS and C. Intermediate SDL definitions are also provided for any languages not covered.

The XMLRTL library has been built on the eXpat XML parser.  Due to this the original eXpat interface is also available as a portable interface intended for use when porting eXpat dependent applications or writing software in C that is expected to be portable to another plaftorm using eXpat.  The HTTP connectivity is provided by the cURL library.

Software

XMLRTL ships in a combined PCSI kit. This means that the single kit contains software that will install on OpenVMS VAX, Alpha and I64.

  • XMLRTL V1.0 PCSI software kit PCSI|ZIP.

If for some reason you are unable to download the XMLRTL software we can provide physical media kits with all necessary software upon request.

Documentation

The following documentation covers the XMLRTL software product:

  • Kednos XML Support Run-Time Library User Guide & Release Notes HTML|PS|PDF

All manuals are produced using DECdocument from Touch Technologies, Inc.

Licensing & Support

XMLRTL is a comercial product available from Kednos Enterprises. License PAKs and formal support agreements are available and can be discussed further by contacting sales@kednos.com.

An evaluation license, valid till 01-Oct-2009, can be downloaded from here.

Examples

The following are a collection of examples demonstrating the different XML APIs.  All examples are available in the software product kit.

Elements
Source: elements.pli elements.bas
Description:

Elements is a simple XML parser that demonstrates how to create and free a parser context as well as how to specify event handlers.  It will produce a listing of all tags (and their attributes) present in the input document.

The program comes in both PL/I and BASIC flavours.  po.xml contains an example XML document.
Build Instructions: PL/I: $ PLI ELEMENTS
$ LINK ELEMENTS,SYS$INPUT/OPTION
SYS$LIBRARY:XML$SHR/SHARE
BASIC: $ BASIC ELEMENTS
$ LINK ELEMENTS,SYS$INPUT/OPTION
SYS$LIBRARY:XML$SHR/SHARE
 
 
 
 
 
 

 
\nAs at: Monday, 06 September 2010 23:16\n   \nUpdated: Wednesday, 28 April 2010 22:45