Ralf

Ralf

Version 2.4

RALF (Restricted Access to Locked Files) is a set of routines that allow the caller to open, obtain header information about, and optionally read records from a file that is already locked by RMS (typically while another user has it open for write).

2024-03-17

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.

Email addresses: ralf at tomwade.eu or ralf at beyondthepale.ie

Availability: Permission is granted to use, copy, and distribute this program in any form as long as:

  1. this notice of copyright and distribution policy remain intact
  2. the distribution is made without charge above and beyond any reasonable fee to cover costs in making and delivering the copy, and
  3. no additional restrictions are imposed, either as to distribution or as to use.

Please contact the authors for permission to incorporate the program or a work derived from it into a commercial product for sale, lease, rent etc.

Please advise the authors of any modifications or improvements in order that they may be considered for incorporation in a future release. Modified versions should be clearly distinguished from the original before being distributed.

Copyright ©2024 Peter Coghlan and Tom Wade

Contents

Chapter 1
Introduction

1.1 Purpose of RALF

 RALF is a set of routines that allow the caller to bypass RMS locking and access a file's header information and data. Routines are provided to open such a file, return specified information from the file header, and optionally read records from the file.

1.2 Implementation

 RALF works by making QIO calls to the File ACP directly, bypassing RMS. It should be noted, however, that Files-11 also locks a file that is open, and it requires SYSPRV privilege to override this. Thus these routines must be used by a process having this privilege (or a System UIC). We hope to provide a mechanism to provide this functionality to non-privileged users in a future release, if enough interest is found (please let the developers know if this would be a desirable feature for you).

RALF is written in Macro32, but can be called by any language using the VMS calling standard. Include files defining constants are provided for Fortran, Pascal, Basic, and C.

RALF is provided both as an object library (.OLB) and shareable image (.EXE), along with full sources. Sample programs that use the RALF calls are also provided.

RALF runs on OpenVMS VAX, OpenVMS Alpha, Integrity (Itanium) and OpenVMS X86.

Chapter 2
Installation

2.1 Requirements

 RALF 2.4 requires OpenVMS VAX 5.5-2 or later, OpenVMS Alpha 6.2 or later, OpenVMS IA64 8.3 or later, or OpenVMS X86 9.1 or later. It has been tested on OpenVMS VAX 7.3, OpenVMS Alpha 8.4, OpenVMS IA64 8.4 & OpenVMS X86 9.2. Disk requirements are minimal (less than 2000 blocks). Full sources are provided, along with an automated procedure to compile and relink. A Macro32 compiler is required, but this is normally provided on all the architectures supported. The installation procedure places all the RALF files into a single directory specified by the installer. It does not place, remove or change any files outside this area (other than VMSINSTAL's own housekeeping information). Files for all four architectures are installed. The startup file will set up logicals appropriate for the current architecture.

2.2 Savesets

 RALF comes in VMSINSTAL savesets, RALF024.(A,B,C,D,E). The same kit is used for installation on all supported architectures. For distribution over the Internet, this is normally supplied in a VMS ZIP archive RALF024.ZIP. This file must be unzipped on an OpenVMS platform---performing the unzip on a PC will result in the VMS attributes of the RALF024.A file being lost. The ZIP file can be transferred via non-VMS systems provided binary mode is used. 


      $ UNZIP :== $SYS$DISK:[]UNZIP 
      $ UNZIP RALF024 
      $
The Zip archive also contains the file COVER.TXT, which briefly describes this version of RALF.

2.3 Invoking VMSINSTAL

Invoke the VMSINSTAL procedure from the SYSTEM account. When asked for the product name, respond 'RALF'. 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 RALF and will not cause any other files to be deleted.

2.3.1 Target Directory

 The installation procedure will ask for a target directory for the files. All RALF files will be placed in this directory, and no other files on your system will be modified. The target directory defaults to SYS$SYSDEVICE:[RALF] It is recommended that RALF be placed in a directory solely used for this product. The installation procedure will install binaries for all architectures.

2.3.2 Documentation

 Documentation in HTML, Postscript, PDF & plain text will be placed in this directory along with the source SDML file.

2.4 Files

 The following files are created:

File Purpose
RALF.PS Postscript documentation
RALF*.HTML HTML documentation files
RALF.TXT Text documentation
RALF.PDF PDF documentation
RALF.SDML Documentation source
BUILD.COM Command procedure to compile & link.
RALF_VAX.EXE VAX shareable image.
RALF_ALPHA.EXE Alpha shareable image.
RALF_IA64.EXE Integrity shareable image.
RALF_X86.EXE X86 shareable image.
RALF_VAX.OLB VAX object library.
RALF_ALPHA.OLB Alpha object library.
RALF_IA64.OLB IA64 object library.
RALF_X86.OLB X86 object library.
RALF_LINK.OPT Option file for linking caller applications.
RALF_STARTUP.COM Startup file.
RALF.MAR Macro32 source file.
RALFLIB.MLB Macro symbol definition library.
RALFDEFS.* Symbolic constants for various languages.
PEEK.* Sample PEEK program with sources.
FILEINFO.* Sample FILEINFO program with sources.

2.5 Postinstallation Tasks

The RALF_STARTUP.COM file should be called from the System startup file (SYSTARTUP_VMS.COM). Note that this is not required if you wish to link applications using the object library rather than the shareable image.

2.6 Sample Installation

 The following shows a sample installation using the VMSINSTAL facility. 


 
$ @sys$update:vmsinstal 
 
 
        OpenVMS  Software Product Installation Procedure V8.3 
 
 
It is 8-DEC-2020 at 14:00. 
 
Enter a question mark (?) at any time for help. 
 
* Are you satisfied with the backup of your system disk [YES]? 
* Where will the distribution volumes be mounted: us$:[twade.ralf] 
 
Enter the products to be processed from the first distribution volume set. 
* Products: ralf 
* Enter installation options you wish to use (none): 
 
The following products will be processed: 
 
  RALF V2.4 
 
 
        Beginning installation of RALF V2.4 at 14:00 
 
%VMSINSTAL-I-RESTORE, Restoring product save set A ... 
 
******************************************************************************* 
*                   Ralf V2.4                                                 * 
*                                                                             * 
*       by Peter Coghlan & Tom Wade                                           * 
******************************************************************************* 
%VMSINSTAL-I-RESTORE, Restoring product save set B ... 
%VMSINSTAL-I-RESTORE, Restoring product save set C ... 
%VMSINSTAL-I-RESTORE, Restoring product save set D ... 
* Do you want to purge files replaced by this installation [YES]? y 
 
        You must specify a directory in which RALF files are stored. 
        If the directory does not exist, the installation procedure will 
        create it. 
 
* Directory for RALF files [SYS$SYSDEVICE:[RALF]]: sw$:[ralf] 
 
        The documentation for RALF is in DecDocument.  The documentation 
        source is provided, along with generated output in HTML, Postscript 
        and plain text. 
 
 
        All questions regarding the installation have been asked. The 
        installation will now continue without the need for further 
        operator intervention 
 
%VMSINSTAL-I-SYSDIR, This product creates system disk directory  SW$:[RALF]. 
 
%VMSINSTAL-I-MOVEFILES, Files will now be moved to their target directories... 
 
        Installation of RALF V2.4 completed at 14:01 
 
    Adding history entry in VMI$ROOT:[SYSUPD]VMSINSTAL.HISTORY 
 
    Creating installation data file: VMI$ROOT:[SYSUPD]RALF024.VMI_DATA 
 
Enter the products to be processed from the next distribution volume set. 
* Products:

2.7 Rebuilding RALF

The RALF kit provides executables and object files, so it is not necessary to rebuild it from the sources. However, if you wish to do so, you can execute the command: 


 $ @BUILD

which will rebuild the the object files for the current architecture (VAX, Alpha, Integrity or X86). Note that you will have to execute this command on each architecture to build the complete object set.

Chapter 3
RALF Routines

 This chapter describes the various RALF routines available to the caller.

3.1 Ralf_Open

 Opens a file specified by name.

Usage:

status = RALF_Open (context, filespec, [default_filespec], [itemlist])

Argument Data Type Access Mechanism
context Longword Write Address
Filespec Character Read Descriptor
Default Filespec Character Read Descriptor
Itemlist Data Structure Read/Write Address

3.1.1 Arguments

Context

Address of a longword integer into which RALF_Open returns a context variable. This context variable is used in subsequent read or close calls. You may have several files opened by Ralf simultaneously, using the context variable to specify which file is the target of the read or close operation.

Filespec

File specification of the file to be opened.

Default Filespec

Specifies a partial file specification, the fields of which are used to fill in any unspecified fields of the Filespec argument. This argument is optional.

Itemlist

Optional argument allowing you to specify additional information to Ralf, or to return information from the file's file header. See the section on Obtaining File Header Information for a full description of this argument.

3.1.2 Description

This routine makes a call to the File ACP to open the specified file, rather than use an RMS $OPEN call, allowing the routine to open a file that has been opened exclusively by RMS. The routine will translate the file specification into a device name and File ID (FID), which is then passed to the ACP for the open operation.

3.1.3 Return Values

Return Value Description
SS$_NORMAL Normal successful completion
SS$_UNSUPPORTED Attempt to open a non sequential file
SS$_INSFARG Caller must specify at least 2 arguments
SS$_TRU Device name truncated
SS$_IVBUFLEN Optional Buffer size must be at least 1 block
SS$_BADPARAM Invalid size specified for an item
SS$_TOOMUCHDATA List is more than 29 items or no terminator
Other error returned by System Service

3.2 Ralf_Close

Closes a file that has been opened by Ralf_Open or Ralf_Open_By_FID)

Usage:

status = RALF_Close (context)

Argument Data Type Access Mechanism
context Longword Read Address

3.2.1 Arguments

Context

Address of a longword integer containing the Ralf context. This context must have been returned by a previous call to Ralf_Open or Ralf_Openbyfid.

3.2.2 Description

This routine deaccesses the file, deassigns the channel, releases the event flag and frees allocated buffer memory.

3.2.3 Return Values

Return Value Description
SS$_NORMAL Normal successful completion
SS$_INSFARG Missing context argument
Other error as returned by system services

3.3 Ralf_Read_Record

Reads a record from the opened file.

Usage:

status = RALF_Read_Record (context, buffer, [length])

Argument Data Type Access Mechanism
context Longword Read Address
Buffer Character Write Descriptor
Length Longword Write Address

3.3.1 Arguments

Context

Address of a longword integer containing a context returned by a previous call to Ralf_Open or Ralf_Open_By_Fid.

Buffer

Address of a character string buffer into which Ralf will return the record.

Length

Address of a longword into which Ralf will write the length (in bytes) or the record returned.

3.3.2 Description

This routine will return the next record from the opened file. It will use the file header information to determine the nature of the RMS record structure in the file. For example for a variable length sequential file Ralf will interpret the first two bytes as a record length indicator, or will look for a record terminator in a stream file, or will simply return the next count of data for a fixed record file. It will also skip over the null byte inserted by RMS to ensure records begin on a word boundary.

3.3.3 Return Values

Return Value Description
SS$_NORMAL Normal successful completion
SS$_ENDOFFILE No more data in file
SS$_TRU Data truncated as buffer too small
SS$_UNSUPPORTED Ralf could not determine the record format
Other error as returned by System Services

3.4 Ralf_Name_To_Fid

Convert a file name to File Identifier (FID).

Usage:

status = RALF_Name_To_FID (device, ldev, fid, filespec, [default_filespec])

Argument Data Type Access Mechanism
Device Character Write Descriptor
Ldev Longword Write Address
FID 3 Word array Write Address
Filespec Character Read Descriptor
Default_Filespec Character Read Descriptor

3.4.1 Arguments

Device

Name of the disk device on which the file resides.

Ldev

Length of the device name string returned in 1st argument.

FID

Address of a 3 word array in which the File Identifier (FID) is returned.

Filespec

Name of the file (including directory path).

Default Filespec

Default file specification. This argument is optional. If provided, it is combined with the filespec argument to provide any unspecified fields.

3.4.2 Description

The File ACP accesses files using a File Identifier. This is a data structure 3 words (6 bytes) long. This routine translates a file specification string into a device name and File ID.

The output of this routine may be used in a call to the Ralf_Open_By_Fid routine. Alternatively, you can call the Ralf_Open routine directly specifying a single file specification.

3.4.3 Return Values

Return Value Description
SS$_NORMAL Normal successful completion
STR$_TRU Device name truncated to fit in user argument
SS$_INSFARG Caller passed less than four arguments to routine

3.5 Ralf_Open_By_Fid

Opens a file specified by File ID.

Usage:

status = RALF_Open_By_FID (context, device, fid, [itemlist])

Argument Data Type Access Mechanism
context Longword Write Address
Device Character Read Descriptor
FID 3 Word array Read Address
Itemlist Data Structure Read/Write Address

3.5.1 Arguments

Context

Address of a longword integer into which RALF_Open_By_FID returns a context variable. This context variable is used in subsequent read or close calls. You may have several files opened by Ralf simultaneously, using the context variable to specify reach file is the target of the read or close operation.

Device

Name of the disk device on which the file resides.

FID

Address of a 3 word array containing the File I/D.

Itemlist

Optional argument allowing you to specify additional information to Ralf, or to return information from the file's file header. See the section on Obtaining File Header Information for a full description of this argument.

Next Contents