Guide to installing Java on OpenVMS Alpha
  -----------------------------------------
  This document describes how to install Java and J2VMS package on OpenVMS Alpha.
  J2VMS enable Java programs to call VMS system services, RMS, etc.
  
  Author: Alex Wong, March 2004, alw1746 at yahoo com au

- Tested environment: Java 1.4.1, J2VMS, OpenVMS 7.3 Alpha

- Download ECOs from ftp://ftp.itrc.hp.com/openvms_patches/alpha/V7.3. The following patches are required:
  DEC-AXPVMS-VMS73_PCSI-V0200--4.PCSI;1
  DEC-AXPVMS-VMS73_UPDATE-V0300--4.PCSI;1
  DEC-AXPVMS-VMS73_ACRTL-V0600--4.PCSI;1
  DEC-AXPVMS-VMS73_BACKUP-V0200--4.PCSI;1
  DEC-AXPVMS-VMS73_CLUSTER-V0200--4.PCSI;1
  DEC-AXPVMS-VMS73_DCL-V0300--4.PCSI;1
  DEC-AXPVMS-VMS73_DRIVER-V0700--4.PCSI;1
  DEC-AXPVMS-VMS73_F11X-V0400--4.PCSI;1
  DEC-AXPVMS-VMS73_LAN-V0600--4.PCSI;1
  DEC-AXPVMS-VMS73_LIBRTL-V0300--4.PCSI;1
  DEC-AXPVMS-VMS73_MANAGE-V0200--4.PCSI;1
  DEC-AXPVMS-VMS73_PTHREAD-V0300--4.PCSI;1
  DEC-AXPVMS-VMS73_RMS-V0400--4.PCSI;1
  DEC-AXPVMS-VMS73_SHADOWING-V0400--4.PCSI;1
  DEC-AXPVMS-VMS73_SYS-V0800--4.PCSI;1
  DEC-AXPVMS-VMS73_SYSLOA-V0400--4.PCSI;1
  DEC-AXPVMS-VMS73_TDF-V0100--4.PCSI;1

- The ECOs are in compressed, executable form and must be run before a PCSI file is produced. Most of them
  require reboot after installation. PCSI and UPDATE must be installed first.
  
- Download, unzip and install DEC-AXPVMS-JAVA141-V0104-12-1.PCSI

  $ PROD INS JAVA141
  
- Configure the Java environment with the following command procedures:
  $ @SYS$COMMON:[JAVA$141.COM]JAVA$CHECK_ENVIRONMENT.COM  !One time
  $ mc authorize mod system/astlm=300/bytlm=400000/enqlm=4000/fillm=4096/pgflquo=2097152/tqelm=100/wsquo=4096
  <autogen modparams with CHANNELCNT_MIN=4096>
  $ @SYS$COMMON:[JAVA$141.COM]JAVA$CONFIG_WIZARD.COM      !One time-Build me a JAVA$CONFIG_SETUP.COM for my intended usage
  $ COPY JAVA$CONFIG_SETUP.COM UTIL:[COM]

- Put following lines into SYLOGIN.COM
  $ @SYS$COMMON:[JAVA$141.COM]JAVA$141_SETUP.COM          !use classic VM(supports jdb)
  $ @UTIL:[COM]JAVA$CONFIG_SETUP.COM                      !setup other java env stuff

- Put following line into SYLOGICALS.COM
  $ define/sys/nolog JAVA$CLASSPATH [],util:[class]

- Download j2vms package from http://www.j2vms.co.uk. This package provides an interface for Java apps to
  call VMS services such as RMS, system services, etc.

- Unpack and install as follows:
  $ set file /attribute=(rfm:STMLF) j2vms.zip
  $ jar "xvf" j2vms.zip 
  $ set file /attribute=(rfm:fix,lrl:32256) j2vms.bck
  $ backup j2vms.bck/saveset [...] /log
  $ copy [.j2vms]vs.jar util:[class]
  $ copy [.j2vms]j2vms_shr.exe sys$share:

- Put following line into SYLOGICALS.COM
  $ define/sys/nolog J2VMS sys$share:j2vms_shr.exe
  
- Java class,jar,etc files must be in stream_lf format.

- ensure vs.jar attributes are correct:
  $ set file /attr=(rfm:stmlf,rat:cr,mrs:0,lrl:32767) vs.jar
  $ set prot=(s:rwed,o:rwed,g:re,w:re) vs.jar
  $ set file/own=[system] vs.jar

- ensure j2vms_shr.exe attributes are correct:
  $ set prot=(s:rwed,o:rwed,g:re,w:re) j2vms_shr.exe
  $ set file/own=[system] j2vms_shr.exe

- Java source files must also be in stream_lf format.
  $ convert/fdl=sys$common:[java$141.com]stream_lf.fdl <infile> <outfile>

- modify the java$classpath logical in SYLOGICALS.COM
  $ define/sys/nolog JAVA$CLASSPATH [],util:[class],util:[class]vs.jar 

- Avoid multiple dots in filenames, rename them to '_' or '-'.

A Java utility class with methods to call TRNLNM and GETMSG
-----------------------------------------------------------

// Vms uses the j2vms package to call TRNLNM and GETMSG system services.
// Build: javac Vms.java
// Run: java Vms
// Alex Wong, March 2004
import vs.starlet.LNM; 
import vs.starlet.SS ;
import vs.*;            
import java.io.*;

public class Vms {
  private static int status;

  public static void main(String[] args) throws Exception {
    System.out.println("SYS$SYSDEVICE = "+sys_trnlnm("LNM$SYSTEM_TABLE","SYS$SYSDEVICE"));
    System.out.println("Exit status 12 = "+sys_getmsg(12));
  }

  public static String sys_trnlnm(String tabnamStr,String lognamStr) throws Exception {
    byte equnam[] = new byte[255] ;
    int equlen;
    byte tabnam[]  = tabnamStr.getBytes();
    byte lognam[]  = lognamStr.getBytes();
    
    Cmem cEqunam = new Cmem(255) ;
    Cmem equnamLength = new Cmem(4);
    int itemList[] = new int[4] ;
    itemList[0] = 255 + (LNM.LNM$_STRING << 16) ;
    itemList[1] = cEqunam.getPeer() ; 
    itemList[2] = equnamLength.getPeer() ;
    itemList[3] = 0;

    SS ss = new SS();

    SystemServices vms = new SystemServices() ;

    status = vms.sys$trnlnm  ( new VMSparam[] { 
       new ByValue(0),
       new ByDescriptor(tabnam),
       new ByDescriptor(lognam),
       new ByValue(0),
       new ByReference(itemList)
       } ) ;
    if (status != ss.SS$_NORMAL ) {
      throw new Exception(sys_getmsg(status));
    }
    else {
      equlen = (int)equnamLength.shortcopyout() ;
      cEqunam.copyout(equnam);
      return new String(equnam,0,equlen);
    }
  }

  public static String sys_getmsg(int msgid) {
    byte [] outbuf = new byte[256] ;
    Short outlen = new Short((byte)0) ;
    Cmem cMsglen = new Cmem(4);

    SS ss = new SS();
    SystemServices vms = new SystemServices();

    status = vms.sys$getmsg  ( new VMSparam[] { 
       new ByValue(msgid),
       new ByReference (outlen), 
       new ByDescriptor (outbuf),
       new ByValue(0),
       new ByValue(0)
       } ) ;
    if (status != ss.SS$_NORMAL )
      return "sys_getmsg failed to retrieve message for msgcode "+msgid;
    else
      return new String(outbuf,0,outlen.shortValue());
  }
  
  public int errorCode() {
    return status;
  }
}