Ralf

3.5.2 Description

This routine makes a call to the File ACP to open the specified file. RMS is not used, allowing the routine to open a file that has been locked by a previous RMS open.

3.5.3 Return Values

Return Value	Description
SS$_NORMAL	Normal successful completion
Other error	See description of Ralf_Open

3.6 Obtaining File Header Information

When opening a file, you can obtain additional information about the file by specifying an item list to the Ralf_Open or Ralf_Open_By_Fid routines. Each item in the list looks like this:

31 16 15 0 -------------------------------- | Type code | Size | 63 -------------------------- 32 | Address of value | --------------------------------

The Size field indicates the size in bytes of the buffer to receive the required information. The Type code indicates the type of information required, and the Address field contains the address of your buffer to receive the information. The list should be terminated by a longword 0 (corresponding to a Size and Type of 0).

The following are the fields that can be returned. The mnemonic field names are defined in the RALFDEF macro provided with RALF. In addition to these, you can specify any field defined by the System Macro $ATRDEF that is a valid item in the ACP QIO call. For a complete list of these see the OpenVMS I/O User Guide (chapter on File ACP). Note that RALF provides some of the more commonly accessed fields in the definitions below.

3.6.1 Item Codes provided by Ralf

Field	Size	Description
Ralf_C_Efblk	Ralf_S_Efblk (longword)	Last block in file
Ralf_C_Efbyte	Ralf_S_Efbyte (word)	First Free byte in last block
Ralf_C_Rsize	Ralf_S_Rsize (word)	Record size
Ralf_C_Vfcsize	Ralf_S_Vfcsize (byte)	VFC control size
Ralf_C_Rtype	Ralf_S_Rtype (byte)	Record Type
Ralf_C_Attrib	Ralf_S_Attrib (byte)	Record Attributes
Ralf_C_Efn	Ralf_S_Efn (longword)	Event Flag used
Ralf_C_Chan	Ralf_S_Chan (word)	ACP channel used

3.6.2 Setting internal Buffer size

By default, Ralf allocates a 16 kB buffer when calling the ACP. If you wish to override this (for example to improve performance for larger files), you can do this by specifying the item code Ralf_C_Buffersize with a size of Ralf_S_Buffersize. The address field should point to a longword containing your desired buffer size.

Chapter 4
Linking with RALF

There are two supported ways of linking the RALF routines with your application. You can use the object library or you can link against the shareable image. The following sections describe how to do each, and their advantages and disadvantages.

4.1 Linking with the Object Library

The RALF routines are provided in the files RALF_VAX.OLB, RALF_ALPHA.OLB, RALF_IA64.OLB & RALF_X86.OLB. Obviously you will use the library corresponding to your current architecture. To link your application (e.g. MYAPP.OBJ produced by the compiler of your choice) on Alpha, issue the following command:

$ LINK MYAPP,RALF_DIR:RALF_ALPHA.OLB/library/select

This will produce MYAPP.EXE which contains all your code and the RALF routines you called. Use the corresponding .OLB file for VAX/IA64/X86 architectures.

4.2 Linking with the Shareable Library

The startup file will create the logical name RALF_SHARE_LIBRARY to point at the appropriate image for the current machine (e.g. RALF_ALPHA.EXE). You link against the shareable image using the following command:

$ LINK MYAPP,RALF_DIR:RALF_LINK.OPT/option

This will produce MYAPP.EXE which contains your code, which references the code in the appropriate shareable image.

4.3 Which approach is better?

Using the shareable image gives you the following advantages:

The resulting EXE file will be smaller than the resultant file linked from the OLB file.
The same copy of the RALF code will be shared in memory by different applications linking to it (if the shareable image is installed).
To upgrade RALF it is only necessary to replace the shareable image file. It is not necessary to relink your application.

Using the object library gives you the following advantages:

You produce a single self contained EXE containing all the code.
You don't need to define the RALF logical names to use RALF.

Chapter 5
Sample Utilities

There are two sample utilities provided with the RALF kit. You may find these useful utilities in themselves, but their main purpose is to demonstrate calling RALF routines from an application.

5.1 PEEK program

The PEEK program displays the contents of a file that may already be open for write access by another user (similar to a TYPE or TYPE/PAGE command). PEEK is invoked as a foreign command:

$ PEEK :== $RALF_DIR:PEEK_ALPHA.EXE $ PEEK <filename> [/PAGE=[value]]

5.1.1 Parameters & Qualifiers

The PEEK command takes one parameter, which is a single file name. Wildcards or lists are not supported. PEEK will open the file for reading (overriding existing locks) and display the contents record by record. There is one optional qualifier /PAGE which will cause PEEK to pause after each page. You can type a carriage return to continue or CTRL/Z to quit. If you specify /PAGE without a page value, PEEK will use the current terminal mode setting to determine the page size.

5.1.2 Restrictions

Note that the PEEK program requires SYSPRV privilege or a System UIC in order to bypass the Files-11 locking if the file is currently in use. Without this, you will receive the following error:

%SYSTEM-W-ACCONFLICT, file access conflict

Note

Do not install the PEEK program with SYSPRV in order to override this conflict. Doing so would allow users to read any file on the system.

5.2 FILEINFO program

The FILEINFO program displays some header information about a file. This program demonstrates how to use RALF's itemlist argument to find this information. The program is invoked as a foreign command:

$ FILEINFO :== $RALF_DIR:FILEINFO_ALPHA.EXE $ FILEINFO <filename> [/SYMBOL]

5.2.1 Parameters & Qualifiers

The FILEINFO command takes one parameter, which is a single file name. Wildcards or lists are not supported. FILEINFO will display limited header information on SYS$OUTPUT. If the /SYMBOL qualifier is present, the information is returned in DCL symbols (FILE_*) rather than displayed on SYS$OUTPUT.

5.2.2 Restrictions

Note that the FILEINFO program requires SYSPRV privilege or a System UIC in order to bypass the Files-11 locking if the file is currently in use. Without this, you will receive the following error:

%SYSTEM-W-ACCONFLICT, file access conflict

Note

Do not install the FILEINFO program with SYSPRV in order to override this conflict. Doing so would allow users to access information on any file on the system.

5.3 Compiling & Linking the Utilities

The utilities are written in Fortran, so a Fortran compiler is required to rebuild the .OBJ files from sources (a Fortran compiler is not required for relinking the supplied .OBJ files to .EXE). The utilities can either be linked against the supplied object library or shareable image file (see the chapter on linking applications for a detailed description of this process).

$ ! Compile the sample programs and associated CLD definitions. $ $ Fortran PEEK, FILEINFO $ Set Command /object PEEK-CLD $ Set Command /object FILEINFO-CLD

You can link the object files using either the .OLB library or the shareable image.

$ ! Link the sample utilities with the OBJECT library (Alpha example) $ $ Link FILEINFO,FILEINFO-CLD,RALF_ALPHA.OLB/library/select $ Link PEEK,PEEK-CLD,RALF_ALPHA.OLB/library/select

$ ! Link the sample utilities using the shareable image (Alpha example) $ Link FILEINFO,RALF_LINK.OPT/option $ Link PEEK,RALF_LINK.OPT/option

The .EXE files provided in the kit have been linked against the object library.

Previous Contents Contents