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.
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.
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.
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
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:
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.
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:
||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.|
||This is a data structure that is held at the start of a RLL library that holds certain control information about the library.|
||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.|
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:
||Open an existing RLL library or program file for reading|
||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|
||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|
||Close an open RLL file releasing all resources and closing the file|
||Close an open RLL file releasing resources but keeping file descriptor active.|
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:
||Report if file is a library (i.e. not a program)|
||Get the version number of a RLL library|
||Set the version number of a RLL library|
|RLL_BSSHeader||Get the BSS Header for a RLL file|
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
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
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
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
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
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
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.
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)
||This is returned (where relevant) when no error has occurred|
||This is returned when you try to read a property that would normally return a list, and the list is empty.|
||There is a problem with the file format that stops the requested operation from being performed.|
||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.|
||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|
||There was insufficient free memory to complete the operation required.|
||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.|
||A failure occurred while reading a file.|
||A failure occurred while writing a file.|
This library and associated documentation has been produced by:
This library and its associated documentation are copyright ©1996-1999 by
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.