Compiling GAWK on VMS:

     There's a DCL command procedure that will issue all the necessary

CC and LINK commands, and there's also a Makefile for use with the MMS

utility.  From the source directory, use either

 |$ @[.VMS]VMSBUILD.COM

or

 |$ MMS/DESCRIPTION=[.VMS]DESCRIP.MMS gawk

or

 |$ MMK/DESCRIPTION=[.VMS]DESCRIP.MMS gawk

Note that on IA64 and Alpha the case of the target may be important.

MMS has had problems on ODS-5 volumes.  MMK does not have these issues.

MMK is available free from https://github.com/endlesssoftware/mmk.

The most recent builds of gawk on VMS used MMK.

Support of the vmsbuild.com may get dropped in a future release.

DEC C  -- use either vmsbuild.com or descrip.mms as is.

       DEC C is also known as Compaq C and HP C.

VAX C  -- use `@vmsbuild VAXC' or `MMS/MACRO=("VAXC")'.  On a system

        with both VAX C and DEC C installed where DEC C is the default,

        use `MMS/MACRO=("VAXC","CC=CC/VAXC")' for the MMS variant; for

        the vmsbuild.com variant, any need for `/VAXC' will be detected

        automatically.

        * IMPORTANT NOTE * VAX C should not be used on VAX/VMS 5.5-2 and

        later.  Use DEC C instead.

GNU C  -- use `@vmsbuild GNUC' or `MMS/MACRO=("GNUC")'.  On a system

        where the GCC command is not already defined, use either

        `@vmsbuild GNUC DO_GNUC_SETUP' or

        `MMS/MACRO=("GNUC","DO_GNUC_SETUP")'.

Most recent builds are using:

    OpenVMS VAX 7.3 using DEC C 6.4

    OpenVMS Alpha 8.3 using HP C V 7.3

    OpenVMS Alpha 8.4 using HP C V 7.3

    OpenVMS IA64 8.4 using HP C V 7.3

GAWK was originally ported for VMS V4.6 and up.  It has not been tested

with a release that old for some time.

Compiling dynamic extensions on VMS:

GAWK comes with some dynamic extensions.  The extensions that have been

ported to VMS can be built using one of the following commands.

 |$ MMS/DESCRIPTION=[.VMS]DESCRIP.MMS extensions

or

 |$ MMK/DESCRIPTION=[.VMS]DESCRIP.MMS extensions

GAWK uses AWKLIBPATH as either an environment variable or a logical name

to find the dynamic extensions.

Dynamic extensions need to be compiled with the same compiler options for

floating point, pointer size, and symbol name handling as gawk.

Alpha and Itanium should use IEEE floating point.  The pointer size is 32 bits,

and the symbol name handling is to be exact case with CRC shortening for

symbols longer than 32 bits.

Currently dynamic extensions have only been tested to work on VMS 8.3 and later

on both Alpha and Itanium.  Dynamic extensions are not currently working on

VAX/VMS 7.3.

Compile time are macros needed to be defined before the first VMS supplied

header file is included.  Usually this will be done with a config.h file.

#if (__CRTL_VER >= 70200000) && !defined (__VAX)

#define _LARGEFILE 1

#endif

#ifndef __VAX

#ifdef __CRTL_VER

#if __CRTL_VER >= 80200000

#define _USE_STD_STAT 1

#endif

#endif

#endif

Alpha and Itanium:

/name=(as_is,short)

/float=ieee/ieee_mode=denorm_results

VAX:

/name=(as_is,short)

The linker option files are [.vms]gawk_plugin.opt for Alpha and Itanium.

As the VAX dynamic plug-in feature is not yet working, the files potentially

needed for a future VAX plugin are in [.vms.vax] directory of the source.

Testing GAWK on VMS:

After you build gawk, you can test it with the [.vms]vmstest.com procedure.

The procedure takes a parameter that is either for a list of tests or

a specific test.  The parameter clean cleans up files left over from running

the tests.

  $ set def [.test]

  $ @[-.vms]vmstest.com bigtest

  $ @[-.vms]vmstest.com clean

  $ set def [-]

To test the dynamic extensions on VMS 8.3 and later, use:

  $ set def [.test]

  $ @[-.vms]vmstest.com extension

  $ @[-.vms]vmstest.com clean

  $ set def [-]

Installing GAWK on VMS:

     All that's needed is a 'foreign' command, which is a DCL symbol

whose value begins with a dollar sign.

 |$ GAWK :== $device:[directory]GAWK

(Substitute the actual location of gawk.exe for 'device:[directory]'.)

That symbol should be placed in the user's login.com or in the system-

wide sylogin.com procedure so that it will be defined every time the

user logs on.

If your gawk was installed by a PCSI kit into the GNV$GNU: directory tree,

the program will be known as GNV$GNU:[bin]gnv$gawk.exe and the help file

will be GNV$GNU:[vms_help]gawk.hlp.  The GNV$GNU:[vms_bin]gawk_verb.cld can be

used to add GAWK and the alias AWK to a DCL command table.

     Optionally, the help entry can be loaded into a VMS help library.

 |$ LIBRARY/HELP SYS$HELP:HELPLIB [.VMS]GAWK.HLP

(You may want to substitute a site-specific help library rather than

the standard VMS library 'HELPLIB'.)  After loading the help text,

 |$ HELP GAWK

will provide information about both the gawk implementation and the

awk programming language.

     The logical name AWK_LIBRARY can designate a default location

for awk program files.  For the '-f' option, if the specified filename

has no device or directory path information in it, Gawk will look in

the current directory first, then in the directory specified by the

translation of AWK_LIBRARY if it the file wasn't found.  If the file

still isn't found, then ".awk" will be appended and the file access

will be re-tried.  If AWK_LIBRARY is not defined, that portion of the

file search will fail benignly.

Running GAWK on VMS:

     Command line parsing and quoting conventions are significantly

different on VMS, so examples in _The_GAWK_Manual_ or the awk book

often need minor changes.  They *are* minor though, and all the awk

programs should run correctly.

     Here are a couple of trivial tests:

 |$ gawk -- "BEGIN {print ""Hello, World!""}"

 |$ gawk -"W" version     !could also be -"W version" or "-W version"

Note that upper- and mixed-case text must be quoted.

     The VMS port of Gawk includes a DCL-style interface in addition

to the original shell-style interface.  See the help entry for details.

One side-effect of dual command line parsing is that if there's only a

single parameter (as in the quoted string program above), the command

becomes ambiguous.  To work-around this, the normally optional "--"

flag is required to force shell rather than DCL parsing.  If any other

dash-type options (or multiple parameters such as data files to be

processed) are present, there is no ambiguity and "--" can be omitted.

     The logical name AWKPATH can be used to override the default

search path of "SYS$DISK:[],AWK_LIBRARY:" when looking for awk program

files specified by the '-f' option.  The format of AWKPATH is a comma-

separated list of directory specifications.  When defining it, the

value should be quoted so that it retains a single translation, not a

multi-translation RMS searchlist.

     The exit status from Gawk is encoded in the the VMS $status exit

value so that the severity bits are set as expected and the original

Gawk exit value can be extracted.

To extract the actual gawk exit code from the VMS status use:

     unix_status = (vms_status .and. &x7f8) / 8

The exit value is encoded to comply with VMS coding standards and

will have the C_FACILITY_NO of 0x350000 with the constant 0xA000

added to the number shifted over by 3 bits to make room for the

severity codes.

The Gawk exit value of 1 will result in the VMS status having the

ERROR severity status set.  The Gawk exit value of 2 will result in

the FATAL severity status set.  All other Gawk exit values will have

the Success severity status set.

This change was needed to provide all Gawk exit values to VMS programs and

for compatibilty with programs written in C and the GNV environment.

Older versions of Gawk incorrectly mostly passed through the Gawk

status values instead of encoding them.  DCL scripts that were checking

the severity values will probably not need changing.  DCL scripts that

were checking the exact exit status will need an update.

VAX/VMS floating point uses unbiased rounding.  This is generaly incompatible

with the expected behavior.  The ofmta test in the test directory will

fail on VAX.

Gawk needs the SYS$TIMEZONE_RULE or TZ logical name to be defined or it

will output times in GMT.

The vmstest.com script needs SYS$TIMEZONE_NAME to be defined to match

the SYS$TIMEZONE_RULE.  Older versions of VMS do not define these logical

names.

TO DO Items (not in order of priority)

1. Implement dynamic plug-ins on VAX.

2. With the system() function, the status for DCL commands are not being

   returned.

3. Need gawk to accept logical names GNV$AWKPATH, GNV$AWKLIB, and

   GNV$AWK_LIBARARY in addtion to the unprefixed names.  This will allow

   system wide default values to be set by an installation kit.

4. Need to fix the gawk.cld file to not require a parameter for the options

   that do not use the parameter.