LibRLL

(RLL Support Library)

 

Contents

 


* Introduction

The LIBRLL library is intended to help those who which to develop utility software that manipulate files conforming to the standard introduced as part of the support for Runtime Link Libraries (RLLs). This in effect applies to any program or RLL linked with LD v2.0 or later (as long as you did not explicitly ask for LD v1 compatibility). The idea is that this library provides a set of standard routines that carry out some of the analysis and manipulation of a RLL library or program.

The advantage of this approach is that the programmer does not have to be too aware of the internal structure of a RLL file except at the basic concept level. The messy details of actually handling the different sections of a RLL file can be left to the LIBRLL library routines. This has a secondary advantage in that if it is decided to enhance the RLL format in any way, this can be handled by enhancing the LIBRLL library. The programmer can relink with the enhanced library and his program will autmoatically start working with the enhanced format.

This library was actually developed while building the new versions of the C68 linker and associated utilities that manipulate RLL programs and libraries. These programs all use the LIBRLL library themselves to avoid unnecessary duplication of effort to develop similar code in each of the relevant programs.

LIBLIST library

The LIBRLL library internally makes use of the LIBLIST library to build up the internal memory structures used to store information by the various LIBRLL functions. This means it is necessary to have a copy of the LIBLIST library available at the time you link any program that uses the LIBRLL library. The actual details of how the LIBRLL makes use of the LIBLIST library are hidden within the internal routines, so it is not necessary to understand how the LIBLIST library works to use the LIBRLL library at a very superficial level.

Having said that, it is quite likely that the sort of program that is going to make use of the LIBRLL library is also going to want to be able to navigate the various lists that are built up in memory. These lists are all in the format maintained by the LIBLIST library, and the LIBLIST library supplied functions should be used to navigate these lists.

 


* USING THE LIBRLL LIBRARY

Files Supplied

When you get this library, you should have the following files provided:

LIBRLL.HTM Documentation in HTML format
RLL.H Header file for use with library (packed format)
RLL.HDR Annotated (unpacked) version of above header
LIBRLL.A Statically linked version of library
LIBRLL.RLL RLL version of library (not always supplied)
RLLSRC.ZIP Source of the LIBRLL library as a ZIP archive.

Note that you will also need a copy of the LIBLIST library. This is supplied as a separate item, and is not included in the files supplied with the LIBSROFF library.

Source File Implications

In your source files you must include the rll.h header file supplied with this library in any module that is going to make use of any of the methods that are part of this library. This is done by including a line of the form

#include <rll.h> in your source at an appropriate point.

Linking implications

You need to tell the linker that it needs to search the LIBRLL library to find the routines that you have used. The exact format of the linker commands depends on which variant of the LIBRLL library you decide to use:

Standard version
This is a normal statically linked version of the library, and is provided as the file LIBRLL.A. To tell the linker to use this version of the library, then you need to give it some additional parameters. The exact format can vary between linkers, but it is likely to be something like: -lrll -llist This will result in a version of the program that is optimised for runtime efficiency, and has no dependency on any external files being present at runtime. Note to that the above parameters have also specified that the LIBLIST library should be searched after the LIBRLL library. This order is important.
RLL version

The RLL version of the library can only be used for programs that are to run on QDOS (or compatible) systems. It allows the necessary routines to be picked up dynamically at runtime from a separately loaded RLL library.

To tell the linker to use the RLL variant of the library you need to add the following options to the end of the linker command line (after any of your own object files):

-rrll -lrll -rlist -llist

Note that both the RLL and standard versions of the libraries are specified. This is to allow for the fact that there are still a few routines (at this release anyway) that can only be statically linked, and so are not present in the RLL version of the library. The order of the parameters is important.

To be able to use the version of the program generated using the RLL libraries, then it is necessary to have a copy of the LIBRLL.RLL and LIBLIST.RLL files at runtime. The user will also need to have the Runtime Link Manager (or RLM) loaded on his system. The RLM is supplied as part of the RLL system to provide runtime support for loading and using RLL libraries.

 


* Data Types

The LIBRLL library defines some specific data types for use within the LIBRLL library. Many of these data types are actually structures, but the details of the structures are not directly exposed to the end-user. Instead they are manipulated using functions supplied with the LIBLIST library (for the list types) and LIBRLL library (for the remainder). This separation makes it easier to change the internal details of any future release of the LIBRLL library, while at the same time maintaining the interface exposed to user programs.

The actual LIBRLL specific data types defined are as follows:

RLL_BSS This is a data structure that is used to maintain information about the structure of a BSS area in a particular RLL library or program.
RLL_HEADER This is a data structure that is held at the start of a RLL library that holds certain control information about the library.
RLL_FILE This is a data structure that is used to maintain information about an opened RLL file. It is analogous to the FILE data type used for stdio files.

 


* Methods

The following is a summary list of the routines provided by the LIBRLL library. Each of the routines is then described in more detail. The detailed descriptions are organised in alphabetical order:

 Scope

Method Name

Description

File

RLL_Open Open an existing RLL library or program file for reading
RLL_OpenFile  
RLL_OpenProg Open an existing RLL program for reading given the name of the file
RLL_OpenProgFile Open an existing RLL program for reading given the file descriptor of the file
RLL_OpenRLL Open an existing RLL library for reading given the name of the file
RLL_OpenRLLFile Open an existing RLL library for reading given the file descriptor for the file
RLL_Close Close an open RLL file releasing all resources and closing the file
RLL_CloseFile Close an open RLL file releasing resources but keeping file descriptor active.
BSS RLL_BssLibRead  
RLL_BssXrefRead  
RLL_BssXdefRead  
RLL_BssXrefRead  
Lib RLL_LibRead  
Xdef RLL_XdefRead  
Xref RLL_XrefRead  
Reloc RLL_RelocRead  

 


* Properties

The properties available for use with the LIBRLL library can in effect be divided up by the scope within which they operate. The list of properties defined is as follows:

Scope

Property Name

Description

File RLL_IsLibrary Report if file is a library (i.e. not a program)
Lib RLL_VersionGet Get the version number of a RLL library
RLL_VersionSet Set the version number of a RLL library
BSS
RLL_BSSHeader Get the BSS Header for a RLL file
Xdef    
Xref    
Reloc    

The methods and properties are now described in more detail. They are listed below in alphabetical order.

 


int RLL_BssHeader (SROFF_FILE * pRllFile);

Returns a pointer to a memory structure containing the BSS Header information.  This structure should not ever be de-allocated by the user.


int RLL_Close (SROFF_FILE * pRllFile);

This method closes a file previously opened using RLL_FileOpen, RLL_FileOpenProg or RLL_FileOpenLib. It will release all memory resources associated with that file. On completion, the pRllFile pointer will no longer be valid for use. If this routine completes without error, then it will return 0. If for any reason an error occurs, then the relevant error code will be returned. However, the pRllFile pointer should still be considered invalid as the data structures linked to it could be in an inconsistent state.


RLL_FILE * RLL_Open (char * FileName);

This method opens a RLL compatible file. It will handle both library and program type files. If after you have opened the file you want to know what type it was, then you can use the RLL_FileIsLibrary property. If the open fails, then NULL will be returned.


RLL_FILE * RLL_OpenProg (char * FileName);

This function opens a RLL compatible program file. On success it returns a pointer to a RLL_FILE type that can then be used as a handle for further function calls on this file. This function will fail if the file is not a RLL program file, so if you know you are expecting a program it is better to use this function instead of the more general RLL_Open method which will also succeed if the file is a RLL library.


RLL_FILE * RLL_OpenProgFile (int * FileDescriptor);

This function takes a file descriptor and then attempts to treat it as a RLL compatible program file. On success it returns a pointer to a RLL_FILE type that can then be used as a handle for further LIBRLL method calls on this file. This function will fail if the file is not a RLL program file, so if you know you are expecting a program it is better to use this function instead of the more general RLL_OpenFile method which will also succeed if the file is a RLL library.


RLL_FILE * RLL_OpenRLL (char * FileName);

This method opens a RLL library file given its name. On success it returns a pointer to a RLL_FILE type that can then be used as a handle for further function calls on this file. This function will fail if the file is not a RLL library file, so if you know you are expecting a RLL library it is better to use this function instead of the more general RLL_FileOpen method which will also succeed if the file is a RLL compatible program.


RLL_FILE * RLL_OpenRLLFile (int * FileDescriptor);

This method takes the file descriptor for an already opened file and then treats it as if it were a RLL library file. On success it returns a pointer to a RLL_FILE type that can then be used as a handle for further method calls on this file. This method will fail if the file is not a RLL library file, so if you know you are expecting a RLL library it is better to use this method instead of the more general RLL_OpenFile method which will also succeed if the file is a RLL compatible program.


int RLL_RLLHeader (SROFF_FILE * pRllFile);

This method reads the Header of a RLL library.


 


* ERROR CODES

The following symbolic names are used for the error codes that can be set by the LIBRLL library.

These values are always negative to help distinguish them from success code, and they will not overlap the error code used by the standard libraries (i.e. the ones defined in the errno.h header file)

RLL_ERROR_NONE This is returned (where relevant) when no error has occurred
RLL_ERROR_EMPTYLIST This is returned when you try to read a property that would normally return a list, and the list is empty.
RLL_ERROR_BADFORMAT There is a problem with the file format that stops the requested operation from being performed.
RLL_ERROR_BADOBJECT This is returned if you pass in a reference to an object that is the wrong type of object for the method or property that you are trying to use.
RLL_ERROR_BADPARAM This is returned if there is something wrong with the parameter supplied to a method or property call. This would typically be something like passing in an object reference for a object that either does not exist
RLL_ERROR_NOMEMORY There was insufficient free memory to complete the operation required.
RLL_ERROR_NOTRLL The physical file was opened correctly, but from looking at the data at the start of the file it does not appear to be a valid RLL file.
RLL_ERROR_READ A failure occurred while reading a file.
RLL_ERROR_WRITE A failure occurred while writing a file.

 


* AUTHOR AND COPYRIGHT 

This library and associated documentation has been produced by:

Dave Walker
22 Kimptons Mead
Potters Bar,
Herts,
EN6 3HZ
United Kingdom

Web: http://www.itimpi.freeserve.co.uk
Email: dave.walker@icl.com
   or: librll@itimpi.freeserve.co.uk

This library and its associated documentation are copyright 1996-1999 by D.J.Walker. All rights are reserved.

Every effort has been made to ensure that the LIBRLL software operates correctly as specified in this document. However no guarantee of any kind is given that the software is reliable or that the descriptions contained in this document is accurate. It is up to the user of the LIBRLL library to satisfy himself that it is suitable for the use to which it will be put.

Permission is given to freely distribute this library, including its documentation and source as long as the following terms are adhered to:

If anyone wishes to distribute the LIBRLL library under any other terms, then they should contact the author to discuss these terms.

 


* RELEASE HISTORY

 OCtober 1999: Release 0.1