Transform

Version 3.1

Transform is a program (and API calls) that substitutes field values in a template file by their corresponding values in a rules file.

2020-09-14 The information in this document is subject to change without notice and should not be construed as a commitment by anyone.

The software described in this document is provided as is. No guarantee is made to the suitability, reliability, security, usefulness, performance or good taste of this software.

Availability: Transform may be used, distributed or incorporated in any third party software, freeware or commercial, without requiring any additional license or incurring charges.

Restrictions Sources are provided under the understanding that

Any changes made to the code will be made available to the developer, after which they may be incorporated into the standard product.
No attempt will be made to port Transform onto a non-VMS platform.

Copyright ©2014 Tom Wade

Contents

Chapter 1
Introduction

1.1 Purpose of Transform

Transform is a tool that can process an input template file, which contains generic field specifiers, and replace those fields with a set of replacement values.

1.2 Sample Transformations

For example, if the fields 'x' and 'y' were defined as "230423" and "23:15" respectively, an input string of

foo bar %x is ready %y

would be translated to

foo bar 2304423 is ready 23:15

Field names greater than 1 character are allowed, in which case the syntax would be:

foo bar %[name] belongs to %[owner]

1.2.1 Numeric Offsets in Rules

Where the rule evaluates to a numeric value, you may include an offset using a plus or minus character to cause the value to be increased or decreased by the specified offset. For example, if rule "score" is defined as "24", then an input string of

Base score is %[score] and adjusted score is between %[score+5] & %[score-5]

would be translated to

Base score is 24 and adjusted score is between 29 & 19

Note that only one plus or minus may be specified, and the offset must be a constant (not another rule name).

1.3 The TRANSFORMER image

The Transformer image allows command line processing on an input file and a rules file into an output file. The image is invoked using a foreign command, as described in the TRANSFORMER chapter. It also serves as a sample program demonstrating the use of the TRANSFORM API.

1.4 Transform API

You can also define fields and apply transformations within your own program. The API provides standard VMS Calling Interface routines which can be called from any VMS language.

Chapter 2
Installation

2.1 Requirements

Transform requires OpenVMS VAX 5.5-2 or later, OpenVMS Alpha 6.1 or later (tested on 8.4) or OpenVMS IA64 8.2-1 or later. The disk utilization is about 1000 blocks including documentation and sources. Full sources are provided, along with an automated procedure to compile and relink. A FORTRAN compiler is required if you wish to recompile, but is not necessary for running Transform.

2.2 Savesets

Transform comes in a single saveset:

Saveset Contents

TRANSFORM031.A Executable code, documentation & sources

Transform is installed using the VMSINSTAL facility. The same savesets work for VAX, Alpha & IA64

Saveset	Contents
TRANSFORM031.A	Executable code, documentation & sources

2.2.1 Getting the saveset from the Internet

If you get the Transform saveset from an Internet FTP server, it will most likely be in a ZIP archive (file TRANSFORM031.ZIP). This format is used because it reduces network traffic by compressing the file, and because the compressed file is 512 byte fixed length records, which corresponds to a BINARY file type (allows any implementation of TCP/IP to retrieve the file without having to fiddle around with file headers afterwards). To decompress the file, you need the UNZIP program (a copy is normally available on the server, and as it is an .EXE file, it can be BINARY transferred as is). The ZIP file can be transferred via non-VMS systems provided binary mode is used. Note that you should only perform the UNZIP operation on a VMS system.

$ UNZIP :== $SYS$DISK:[]UNZIP $ UNZIP TRANSFORM031 $

The file COVER.TXT within the ZIP file contains release information.

2.3 Invoking VMSINSTAL

Invoke the VMSINSTAL procedure from the SYSTEM account. When asked for the product name, respond 'TRANSFORM'. The installation procedure will ask if you wish to purge previous versions of files. Answering 'YES' to this prompt will only affect previous versions of Transform.

2.3.1 Target Directory

The installation procedure will ask for a target directory for the files. All Transform files will be placed in this directory, and no other files on your system will be modified. The target directory defaults to SYS$SYSDEVICE:[TRANSFORM]). It is recommended that Transform be placed in a directory solely used for this product. The installation procedure will create subdirectories for architecture specific files, i.e. .EXE & .OLB files, and for the sources and documentation. Command files will be placed in the top level directory. The procedure will install binaries for VAX, Alpha & IA64.

2.3.2 Documentation

You will be asked if you want the documentation in source form (DOCUMENT), postscript or HTML. These files may be removed after printing.

2.4 Files

The following files are created:

File Purpose

TRANSFORMER.EXE Transformer Command Line executable file.

TRANSFORM.EXE Transform Shareable image file.

TRANSFORM.OLB Object library for API linking.

TRANSFORM_LINK.OPT Linker option file for shareble image.

BUILD.COM Command procedure to compile & link.

TRANSFORM-CLD.CLD Transform CLD definitions for command input.

TRANSFORMER.FOR Fortran source file for Command Line utility.

TRANSFORM.FOR Fortran source file for API routines.

TRANSFORM.INC Include source file for API routines.

TRANSFORM_STARTUP.COM Startup command file.

BUILD-SHARE-*.OPT Options files to build shareable images.

BUILD.COM Command file to compile from sources.

TRANSFORM.PS Documentation in Postscript form.

TRANSFORM*.HTML Documentation in HTML form.

TRANSFORM.TXT Documentation in text form.

File	Purpose
TRANSFORMER.EXE	Transformer Command Line executable file.
TRANSFORM.EXE	Transform Shareable image file.
TRANSFORM.OLB	Object library for API linking.
TRANSFORM_LINK.OPT	Linker option file for shareble image.
BUILD.COM	Command procedure to compile & link.
TRANSFORM-CLD.CLD	Transform CLD definitions for command input.
TRANSFORMER.FOR	Fortran source file for Command Line utility.
TRANSFORM.FOR	Fortran source file for API routines.
TRANSFORM.INC	Include source file for API routines.
TRANSFORM_STARTUP.COM	Startup command file.
BUILD-SHARE-*.OPT	Options files to build shareable images.
BUILD.COM	Command file to compile from sources.
TRANSFORM.PS	Documentation in Postscript form.
TRANSFORM*.HTML	Documentation in HTML form.
TRANSFORM.TXT	Documentation in text form.

A separate subdirectory for each architecture (VAX/Alpha/IA64) is created for the EXE and OLB files.

Chapter 3
Using the Command Line Utility

3.1 The Rules File

A rules file is required to define the various field names and their values. This is a text file containing one field definition per line. The syntax of each line is

field-name=value

Field names may be 1 to 16 characters in size, and are not case sensitive. The field value may be up to 104 characters, and its case is preserved. Blank lines and lines starting with the "!" character are ignored. A sample rules file might be:

! Field definitions for router 10414.2341.rtr1 host=10414.2341.rtr1 network=192.168.5 mask=255.255.255.0 cidr=/24

3.2 Input file

An extract from a sample input file that might be used with this rule file is:

! Router configuration for 1921 hostname %[host] interface gigabit0/0 desc LAN interface ip address %[network].1 %[mask] ip prefix-list LOCAL-ROUTES seq 10 permit %[network].0%[cidr]

3.3 Invoking the CLI utility

Define a foreign command to point at the image TRANSFORMER.EXE, e.g.

transformer = "$SYS$SYSDEVICE:[TRANSFORM.AXP]TRANSFORMER.EXE"

The utility can now be invoked using:

$ transform <input-file> <output-file> [/RULES=<file-file]- [/max_rules=n]

3.3.1 Parameters

The input-file is the file containing the generic text that refers to the field names defined in the Rules file. The output file is the resultant output with the generic fields replaced by the values in the rules file.

3.3.2 /RULES

/RULES specifies a rules file. If omitted, the logical TRANSFORM_RULE_FILE is used to specify the file. If this logical is not defined, the file TRANSFORM_RULE_FILE.DAT in the current directory is used.

3.3.3 /MAX_RULES

The /MAX_RULES qualifier specifies the maximum number of rules allowed. If omitted, the maximum is 100 rules.

3.3.4 Sample Output

The sample output from the example input and rules files above would be:

! Router configuration for 1921 hostname 19414.2341.rtr1 interface gigabit0/0 desc LAN interface ip address 192.168.5.1 255.255.255.0 ip prefix-list LOCAL-ROUTES seq 10 permit 192.168.5.0/24

Chapter 4
Using the API Routines

4.1 Calling the Routines

The routines follow the VMS calling standard, similar to that used by the system RTL routines. Integer arguments are passed by reference, and character arguments are passed by string descriptors. The routines are provided both as a shareable image, and a link library; either mechanism can be used, and both are described below.

4.1.1 Advantages of the Shareable Image

The Transform routines don't form part of your .EXE file.
Multiple applications can use the same memory copy of the API routines.
The Transform routines can be installed as a known image.
The Transform routines can be updated without requiring a relink of your application.

4.1.2 Advantages of the Object Library

Your application is completely self contained.
No need for a logical name pointing at the sharable image.
You don't need to install the shareable image file on any target machine.

4.2 Linking with the Shareable Image

Linking with the Shareable Image requires that a system logical be defined pointing at the image (alternatively, the shareable image can be put in SYS$SHARE, but this is generally not preferable). The file TRANSFORM_STARTUP.COM will define this logical, so it can be called from the System Startup file. Note that this logical is required to be defined when your application is used (not just when it is linked). The linker option file TRANSFORM_LINK.OPT must be invoked with your LINK command, e.g.

$ LINK MYPROG,MYROUTINES,SYS$SYSDEVICE:[TRANSFORM]TRANSFORM_LINK.OPT/option

Note that the target system must have a copy of the shareable image file. This either means installing Transform on the target system, or supplying a copy of the shareable image with your own application images.

4.3 Linking with the Object Library

To link with the object library, include the file TRANSFORM.OLB on your linker command. Note that you must specify the appropriate OLB file for your architecture (VAX, Alpha, IA64). Once linked, your .EXE file no longer has any dependency on any Transform files. For example

$ LINK MYPROG,MYROUTINES,SYS$SYSDEVICE:[TRANSFORM.VAX]TRANSFORM.OLB/LIB/SEL

4.4 The Transform Routines

The following is a description of each of the Transform routines. There are four routines. An initialization routine must be called before any of the others, and a finish routine is called to clear down any data structures when you are finished. The other routines consist of one to define a given rule (which you will call repeatedly for each rule your wish to define), and a routine to apply all these rules to a given line of text (if you were processing a file, you would call this for each line of text).

4.5 Init_Transformation

Initialize the transformation routines

4.5.1 Calling Sequence

status = Init_Transformation (rule, max_rules, flag_char, left_char, right_char)

Argument Data Type Access Mechanism

rule longword write reference

max_rules longword read reference

flag_char character string read descriptor

left_char character string read descriptor

right_char character string read descriptor

Argument	Data Type	Access	Mechanism
rule	longword	write	reference
max_rules	longword	read	reference
flag_char	character string	read	descriptor
left_char	character string	read	descriptor
right_char	character string	read	descriptor

4.5.2 Arguments

4.5.2.1 rule

Integer pointer which should be initialized to zero. This argument is passed to subsequent Transform calls, and should not be modified by the caller.

4.5.2.2 max_rules

Integer containing the maximum number of rules you intend to define. This argument is required.

4.5.2.3 flag_char

Specifies the flag character to be used to indicate the start of a field. This argument is required (in the samples provided a "%" character is used).

4.5.2.4 left_char

Specifies the character to be used as the left delimiter in a field name whose length is greater than 1. This argument is required (in the samples provided a "[" character is used).

4.5.2.5 right_char

Specifies the character to be used as the right delimiter in a field name whose length is greater than 1. This argument is required (in the samples provided a "]" character is used).

4.5.3 Description

This routine will initialize the data structures required by the Transform routines. A pointer to these structures is returned in the 'rules' parameter, which will be passed in subsequent calls.

4.5.4 Return Values

Any return code returned by the system RTL LIB$GET_VM. If the low order bit is set (TRUE value) this indicates success.

4.6 End_Transformation

4.6.1 Calling Sequence

status = End_Transformation (rule)

Argument Data Type Access Mechanism

rule integer read reference

Argument	Data Type	Access	Mechanism
rule	integer	read	reference

4.6.2 Arguments

4.6.2.1 rule

Pointer returned by the initial call to Init_Transformation.

4.6.3 Description

This routine will clear down any data structures set up by Init_Transformation. It should be called when you longer need to call any other Transform routine.

4.6.4 Return Values

Any return code returned by the system RTL LIB$FREE_VM. If the low order bit is set (TRUE value) this indicates success.

4.7 Define_Transformation

4.7.1 Calling Sequence

status = Define_Transformation (rule, name, value)

Argument Data Type Access Mechanism

rule integer read descriptor

name character string read descriptor

value character string read descriptor

Argument	Data Type	Access	Mechanism
rule	integer	read	descriptor
name	character string	read	descriptor
value	character string	read	descriptor

4.7.2 Arguments

4.7.2.1 rule

Pointer to data structure returned by the initial Init_Transformation routine.

4.7.2.2 name

The name of a rule. This can be between 1 and 16 characters and is case insensitive. Rule names should consist of characters, numbers, and optionally ".", "_" or "-".

4.7.2.3 value

The value of this rule. This is a character string between 1 and 104 characters, and case is preserved.

4.7.3 Description

This routine will define a rule. Subsequent calls to apply the rules to a text piece will replace any occurrences of the rule name with the value specified.

4.7.4 Return Values

SS$_NORMAL	Success.
SS$_BADPARAM	Parameters too long, or with invalid characters
SS$_DATAOVERUN	Attempt to define too many rules.

4.8 Apply_Transformation

4.8.1 Calling Sequence

status = Apply_Transformation (rule, instr, outstr, length)

Argument Data Type Access Mechanism

rule longword read reference

instr character string read descriptor

outstr character string write descriptor

length longword write reference

Argument	Data Type	Access	Mechanism
rule	longword	read	reference
instr	character string	read	descriptor
outstr	character string	write	descriptor
length	longword	write	reference

4.8.2 Arguments

4.8.2.1 rule

Pointer to data structure returned by initial call to Init_Transformation.

4.8.2.2 instr

Input string to be processed.

4.8.2.3 outstr

Descriptor for resultant string to be returned.

4.8.2.4 length

The number of characters returned in the outstr argument.

4.8.3 Description

This routine will process the input string and apply any defined rules that match those already defined by calls to Define_Transformation. The resultant string is returned in the output string argument, and the length of the string in the length argument.

4.8.4 Return Values

SS$_NORMAL	success.
STR$_INVDELIM	bad delimiter was used on rule name.
STR$_TRU	output string was truncated.
JBC$_NOSUCHQUE	illegal queue specified.
RMS$_FNF	file not found.
JBC$_NOSUCHQUE	illegal queue specified.
SS$_NOPRIV	file cannot be accessed.
SS$_UNSUPPORTED	Combined + and - characters not supported.
SS$_DECINV	Illegal character in + or - numeric offset.