The Runtime Link Manager (or RLM) is that component of the RLL system that handles the runtime aspects of using the RLL system.
The RLM is intended to normally operate in a manner that is transparent to the average user. A programme using RLLs would be executed in the normal fashion and the program itself would automatically use the RLM to search for and load any RLLs it requires.
For experienced users, the RLM system also supplies commands that provide a greater level of control, and allow explicit loading and removal of RLLs
The operation of the RLM is similar to that of most other software components that are used on QDOS, SMSQ, SMSQ/E or SMS2 systems. The RLM is loaded as a resident extension at BOOT time. It provides both a SuperBasic and a low level programmers interface. The low level interface is only intended for specialist use, and it use is discussed in the RLM Programmers Guide section.
The RLM will normally be loaded at system start up time. For QDOS, SMSQ or SMSQ/E users this would be done via an entry in the BOOT file of the form:
a=respr(15000): LBYTES "flp1_RLM_rext",a: CALL a
You may also want to pre-load some RLL libraries during the boot stage. This would be done by including in your BOOT file (after the RLM has been loaded) lines of the form:
As long as the RLM has been loaded during the BOOT stage, the user would not normally need to do anything special when trying to execute programs that have been built to use RLLs. The RLM system will automatically be activated as soon as any program that tries to use a RLL starts to run.
If a RLL is required that is not already loaded, then the RLL is searched for in three directories:
Failure to find a required RLL or an error in the run time linking
process causes the programme that has just been started to be removed.
If the programme was loaded via
an error code will be returned to the caller.
If the interactive mode is in effect, or if the system has been
configured to do so, the RLM will display an appropriate error
message on such failures.
The interactive mode opens a console window which is then used to inform the user of the link status, errors etc. It also permits the user to retry on any failure to find an RLL (after say changing default directories or media). On successful linking the RLM console is closed and the job continues. On failure the user must press a key to exit.
N.B. All integer quantities when in the interactive mode screen are represented in hex.
The RLM also provides some additional support to assist in developing runtime libraries, or producing bug reports. This is the RLM debug facility. This can be switched on so that a debug file is produced for each programme linked. The average user will not need to make use of this capability - it is intended primarily for those who are developing RLL libraries.
The debug file format consists of lists of RLLs referenced and their version number. Following this each symbol is listed and its source RLL named with the offset in the RLL, followed by a list of offsets in the linked code of addresses referring to this symbol. Error messages are produced for any undefined symbols.
The debug file is opened for overwrite on a directory defined by the debug directory maintained internally to the RLM, this may be a directory or serial device. The file will be named as the job name truncated to 8 characters (or failing a job name the job tag in hex) with the extension "_DBG" appended.
The debug file also lists the absolute addresses of the code being linked and all the libraries to permit an interface to a symbolic debugger.
N.B. All integer quantities in the debug file are represented in hex.
The default settings of the RLM will satisfy many users so that the system can be left to function completely autonomously. However, there are a number of new SuperBasic keywords made available once the RLM has been loaded to help users exploit its capabilities to the maximum. Experienced users may well wish to use this SuperBasic interface to tailor the RLM system more closely to their particular system, or to explicitly preload RLL libraries in their BOOT files.
The following new SuperBasic procedures can be used to control or set aspects of the RLM. Note that many of the options that can be changed via these keywords can also be given default values via the CONFIG program.
|Procedure Name and syntax||Description|
||Relink RLM on accidental removal of RLM Thing|
||Load a RLL with a defined timeout. The file name of the RLL is assumed to have the extension "_RLL". This will be added automatically if omitted|
||Remove a RLL. This will also remove any jobs or other RLLs that have dependencies on the presence of this RLL.|
||Sets the default directory that is to be searched for RLL libraries. If any RLL cannot be found in this location, the system will also search the current PROG_USE and DATA_USE locations.|
||Set the device/directory to be used for storing debug information files.|
||Set interactive mode status, where
||Set debug mode status. The parameter m% specifies
the mode as follows:
||Set autoload timeout where m% has the
The following functions can be used to interrogate the RLM about its current settings:
|Function Name and syntax||Description|
||Returns interactive mode status as follows:
||Returns debug status as follows:
||Returns value of the autoload timeout as follows:
||Returns value of the default device/directory that will be searched for any RLLs that need loading.|
||Returns current value of the debug device/directory that will be used for storing any RLL debug files.|
The default settings of many of the RLM options are stored internally in a CONFIG block. You may configure your copy of RLM to set the startup state of these global settings using the QJUMP CONFIG program. You can also use the MENUCONFIG program provided by Jochen Merz.
Note that as level 1 CONFIG treats all values as unsigned. To specify a negative value in this case (to get infinite timeout) you will need to set a large positive number (i.e. > 32,768 and < 65537). The RLM will treat any negative number as infinite. Very small timeouts are not recommended as the RLL may be removed before the programme has a chance to use it. Positive values represent the unload time in seconds.