6. ROMIT COMMANDS

This section contains a full description of each Romlt command. For a discussion of the use of star commands with Romlt and for a discussion of parameters used with them, see sections 1.5-1.8 of this manual.

*ACCESS

Use of this command will prevent the named file from being deleted with the command *DELETE, renamed with *RENAME, or being overwritten with

*SAVE. To so protect a file use the following form of the command:

*ACCESS <filename> L RETURN

When a file has been locked in this manner the INFO (see *INFO) of the file will show the letter L under the heading Flag.

To unlock the file so that it may be deleted or overwritten use the same command but without the second parameter, L:

*ACCESS <filename> RETURN

IMPORTANT

Locking files does not prevent them from being destroyed by the use of

*WIPE although if this command is accidentally issued it may be undone by using *UNWIPE .

*APPEND

Normally, saving a file into the RaFS will cause any old file having the same name to be overwritten. However, by issuing *APPEND the RaFS can be made to behave in a manner not unlike a the cassette filing system, thus allowing the same filename to be used without deleting any old versions. The new version is saved at the end of the RaFS so you know which is the latest version.

This facility might at first not seem very useful, but during program development you might like to keep all your old versions, just in case your latest crashes. This can easily be done by programming a function key thus:

*KEY0 SAVE"PROGRAM"¦M RETURN

Simply pressing function key 0 will then save your latest version with the filename PROGRAM at the end of the RaFS, space permitting. If the message 'RAM full' occurs you can always *DELETE the oldest version, as all commands such as LOAD, *DELETE, *ACCESS, *RENAME etc., always operate on the first found occurrence of the specified filename.

To return to the default system whereby saving deletes a file of the same name you use the command *OVERWRITE .

*BLOCK

1) To or from a specified page in the BBC micro's user Ram area.

2) Between sideways Ram and a selected filing system.

*BLOCK <source> <dest.> <page>

If you wish to blow the current contents of your RaFS Ram into a Rom the

*BLOCK command can be used to shift the entire contents of the RaFS, whether it is in user or sideways Ram, to a selected position in user Ram.

The parameter <page> signifies the top two bytes of the page boundary address in hex of the start of the workspace which is to carry the relocated code. For example, you would use 19 if you wanted to specify &1900.

The <source> and <destination> refer to the location of the block of sideways Ram. The single letter parameter represents the following:

R Ram
M Memory

The normal default page for cassette systems is &0E00. Hence to shift the entire contents of the RaFS from sideways Ram into memory that starts at page &E (decimal 14) you would enter:

*BLOCK R M 0E RETURN

Similarly disc users may want to shift the RaFS code from the RaFS to memory starting at &1900, and would enter:

*BLOCK R M 19 RETURN

To perform the reverse operation, transfering the block of code from memory to the RaFS, requires the M and R paramters to be reversed. The <page> parameter now signifies from where the block of code is to be transferred. For example, to move a block of code from &1100 to the RaFS you would enter:

*BLOCK M R 11 RETURN

The *BLOCK command shifts everything in the RaFS including all files, headers and service code. Do nor therefore try to run anything that has been shifted as you will probably only succeed in crashing the computer. This command is primarily intended for moving code from the RaFS to a position in user memory so that it may then be blown into a Rom. The type of Eprom programmer in use will determine the page address to be used, so please consult the manual of your blower to find this out. If you do not have access to an Eprom blower, but still want to have your code blown into a Rom, Beebugsoft will undertake this for you.

*BLOCK <source> <dest.> <filename>

The second use of this command is to transfer the complete contents of the RaFS Ram directly to or from disc, tape, or any other filing system.

The <source> or <destination> may be R for Ram, and also the filing system specified by name.

For example, to save the contents of the RaFS to disc under the filename 'DATA' you would issue the following:

*BLOCK R DISC DATA RETURN

Similarly, to load a previously saved RaFS Ram area back into sideways Ram from tape at 300 baud, enter:

*BLOCK TAPE3 R DATA RETURN

Either the first or second parameter must be an R. Other filing systems that may be used with this command include:

*BUFFER <<number>>

Issuing the *BUFFER command without the number parameter will turn the Ram used by Romlt, whether it is sideways or user Ram, into a printer buffer. Therefore, to list a program out to a printer you would issue the following commands:

*ENABLE RETURN
*BUFFER RETURN
VDU2 RETURN (or CTRL-B)
LIST RETURN
VDU3 RETURN (or CTRL-C)

With the number parameter being employed the Ram may be allocated as any of the following buffers:

The numbers in brackets may be used if you want the buffer to be flushed when ESCAPE is pressed. If you use the lower number the contents of the buffer will be preserved when ESCAPE is pressed. This is of particular importance when using the printer buffer.

When *BUFFER is called without any parameters it defaults to a printer buffer in such a way that ESCAPE will not flush the contents, (ie *BUFFER is the same as *BUFFER13).

When the buffer is in use all buffer related commands work as expected. Therefore, ADVAL(-(N+1)) will return the free space in the buffer, *FX15 will flush it as will *FX21, *FX138 will insert a character into the selected buffer and *FX145 will remove a character. Details of all of these commands may be found in the BBC User Guide.

To disable the buffer simply issue the command *RAM.

IMPORTANT.

Use of the BUFFER facility offered by Romlt will destroy any files held in the RaFS.

*DELETE

This command will delete the named file from the RaFS and then close up the space occupied by that file. This is the same as doing a *DELETE followed by a *COMPACT on the DFS. The command will only operate on a file that has not been locked with *ACCESS. If the file has been locked the error message 'File locked' will be issued.

*ENABLE

Since the commands *BUFFER and *WIPE can cause the entire contents of your Ram to be lost, the command *ENABLE must be issued immediately before, in order to prevent accidental misuse. For example:

>*WIPE RETURN
Not enabled

>*ENABLE RETURN
>*WIPE RETURN
Free bytes in RAM E .....(16291) &3FA3
>

*FILE

This command will transfer the specified file between the RaFS and any other specified filing system. This command is of particular use to those who have to employ the RaFS in user Ram, and therefore do not have sufficient room in memory for both the program and the RaFS.

During the transfer all headers are added to the program being transferred, and the correct load and execution addresses are added.

The <source> or <destination> may be R for RaFS Ram (whether in user Ram or sideways Ram), and also the filing system specified by name fie by its proper title).

For example, to transfer the file called PROGRAM from the RaFS to disc you would issue the following:

*FILE R DISC PROGRAM RETURN

Similarly, to load a previously saved file back into sideways Ram from tape at 300 baud, enter:

*FILE TAPE3 R PROGRAM RETURN

Either the first or second parameter must be an R.

For other filing systems that may be used refer to the *BLOCK command. In each case the specified source or destination should be the approved filing system name, For example, NET for Econet, TAPE or TAPE12 for the cassette filing system.

*HELP

Typing *HELP by itself will cause a display similar to that below to be shown:

*HELP

RAM Filing System 1.00
RFS
RAFS
UTILS

TOOLKIT PLUS 2.00
TOOLKIT

SLEUTH 1.06

DFS 0.90
DFS
UTILS

OS 1.20

Since this simply lists the resident Roms in your machine, the display might not be exactly as that shown. Typing *HELP followed by one of the three abbreviations RFS, RAFS and UTILS, produces the following displays:

*HELP RFS

BGET# <handle>
CHAIN <f ilename>
CLOSE# <handle>
EOF# <handle>
INPUT# <handle>,<variable list>
LOAD <filename>
OPENIN <filename>

*CAT
*EXEC <filename>
*LOAD <filename> <<load address>>
*OPT <number>,<number>
*RUN <filename>

*HELP RAFS

*ACCESS <filename> <<L>>
*DELETE <filename>
*RAM <<socket>> <<S>>
*RAM <<+>> <<S>>
*RAM <<->> <<S>>
*RBOOT <<->>
*RHELP <<->>
*RTITLE <<->>
*RENAME <oldname> <newname>
*RESTRICT <filename> <<R>>
*REXEC <filename> <address>
*RELOAO <filename> <address>

BPUT# <handle>,<number>
OPENOUT <filename>
PRINT# <handle>, <variable list>
SAVE <filename>
*SAVE <filename> <start> <end>
*SPOOL <filename>

*HELP UTILS

*APPEND
*BUFFER <<number>>
*BLOCK <source> <dest.> <page>
*BLOCK <source> <dest.> <filename>
*ENABLE
*FILE <source> <dest.> <filename>
*INFO
*MEND
*OVERWRITE
*PAD
*RBASIC
*SNAP <<R>> <<D>>
*SPACE
*UNWIPE
*WIPE

Please note that if you have a DFS fitted that also responds to *HELP UTILS, use of this will put up the information shown above as well as the DFS information. As this is so, it is probably advisable to set the screen to the paged scrolling mode via CTRL-N (ie press CTRL and tap N ), before issuing the *HELP, as this will enable you to read the commands without them scrolling off the top of the screen.

*INFO

Similar in many respects to the *INFO commands of the DFS, this command provides information about the files held in the RaFS, and data on the state of the RaFS itself. Typing *INFO will produce a display similar to that below:

This example simply shows the type of display achieved, and of course will differ unless you have a file named TEST saved in the RaFS.

The information given is as follows:

The information heading the program TEST is as follows:

Filenames used with the RaFS may be up to 10 characters in length. Unlike the DFS you may not specify directories or libraries within the filename. This means that if you try to save a file with the filename S.TEST it will be saved as S.TEST, and not as the file TEST in directory S.

*MEND

Following a 'Bad ROM' error subsequent commands operating on the RaFS will also present the same error. Use of this command will attempt to rectify this matter by removing the last file from the end of the RaFS, as this is the area where corruption is most likely to have occurred.

We must stress that this command only attempts to rectify the situation, but is successful in the majority of cases; in the remainder, the only effective answer is to issue the commands *RAM followed by *WIPE. If that doesn't work the only answer is to switch the machine off and then back on again. This is guaranteed to rectify even the most severe corruption of the RaFS! If you have battery backup, you may need to switch it off and even remove the Ram chips so they can discharge their memory.

*OVERWRITE

If you have issued the *APPEND command the *OVERWRITE command may be used to revert the RaFS back to it's default position. In the default condition, or after the *OVERWRITE command has been used to cancel

*APPEND, saving a file will first try to delete a file which has the same name.

*PAD

Some makes of Eprom blower work more efficiently if all unused bytes are set to hex &FF (decimal 255). This command simply does this for you by placing the value &FF in every unused byte in the RaFS. If the Eprom blower you are using does not require this operation then you can ignore this command.

*RAM

If the command *RAM is issued Romlt searches through the sideways sockets from number 15 down to 0 until it finds sideways Ram. When Ram is found the socket number is allocated to the RaFS and the free space in the RaFS displayed. The number displayed when *INFO is typed is the socket allocated in this manner. The command *RAM with no parameters selects the highest priority Ram located.

If no Ram is found in the sideways sockets 15 to 0 the error message 'No RAM' will be issued. To activate the RaFS when no sideways Ram is present, either *RAM+ or *RAM- may be issued (see below).

If a socket number is specified, i.e. *RAM E, the RaFS will be allocated the Ram located in that socket, provided of course that Ram actually resides there. If it does not, the 'No RAM' error message will be given. The socket number must be issued in hexadecimal, so *RAM E would activate Ram in socket 14 if Ram is found there.

*RAM+ *RAM-

If you do not have sideways Ram resident in your machine, the RaFS may be assigned either 8K or 16K of user Ram. To select an 8K RaFS issue the command *RAM-, and to select the 16K version issue the command *RAM+.

Issuing either of these commands necessitates that the Ram area is protected from other use, and to do this you should press the letter R and BREAK as prompted. The area allocated to the RaFS is located from OSHWM upwards, and PAGE is reset accordingly.

Do not forget that even in mode 7 the use of a 16K RaFS in user Ram will limit what else can be held in the memory. If you have an Acorn DFS fitted, the actual space left will be about 9.25K (9472 bytes, &2500 in hex) if the 16K RaFS is selected. With cassette based systems the 16K RaFS will leave about 11.5K of useable Ram (11776 bytes, &2E00 in hex).

*RAM S

If you wish to suppress the screen display each time the RaFS is called up, you may use the S parameter (S for suppress). To do this replace:

*RAM with *RAM S
*RAM + with *RAM+ S
*RAM- with •RAM- S

*RBASIC

Use of this command will render a program already held in the RaFS under the filename specified in a form that means that when it has been restricted with *RESTRICT the program may be *RUN as if it were a machine code program. This command should therefore be used on all BASIC programs that are to be blown into an Eprom and which you want to protect from prying eyes.

When this command has been used, some special code is attached to your program to make it respond to *RUN as if it were a machine code file. By then restricting the file with *RESTRICT it may not be run by any command other than *RUN. This therefore provides your software with a good degree of protection.

Cassette users who modify software with the *RBASIC command and then intend it to be used on a disc system, should emulate the disc enviroment by ensuring that page is set to &1900. Before writing or loading programs, you should enter:

PAGE=&1900 RETURN
NEW RETURN

*RBOOT

By issuing the command *RBOOT, special code is added to that held in the RaFS so that it is possible to automatically exectute the commands in a file called !BOOT when you press the keys R SHIFT BREAK in the following sequence:

Press SHIFT
Press R
Press BREAK
Release BREAK
Release R
Release SHIFT

This is called 'booting' a program.

The file called !BOOT holding the instructions must be made and saved in Ram. For example, to automatically select graphics mode 7, and then run a program called MENU, it would be necessary to create a file consisting of the Basic commands:

MODE 7
CHAIN"MENU"

If you are unfamiliar with creating such a file, you should refer to section 3.1.

*RBOOT-

The special code added to the RaFS to look for a !BOOT can be removed by issuing the command *RBOOT-.

*RELOAD

This command will directly change the load address of a file that is already held in the RaFS under the filename specified to the new address you require. The address you specify here must be in hexadecimal but the leading '&' is not required.

The address you give may be upto 32 bits in length (8 digits), and, although only 6 digits are displayed via *INFO, all 8 are significant and are stored. This command may be of little use to BASIC programmers, but will be of great use to machine code programmers.

*RENAME

Provided the file specified as <oldname> is stored in the RaFS and has not been locked via *ACCESS this command will change the filename to that specified as <newname>. If the file has been locked the error message 'File Locked' will be given. If there is no file under the filename <oldname> held in the RaFS the error message 'File not found' will be issued.

For example, to change the name of a file called TEMP to EXAMPLE, enter:

*RENAME TEMP,EXAMPLE RETURN

*RESTRICT

Use of this command restricts the named file so that it can only be *RUN and not be operated on by any other 'read' command. Use of this command in the RaFS stops normal loading or chaining of programs.

If a Rom is blown containing nothing but restricted files other users can then only *RUN those files. This therefore provides an extremely useful form of software protection. This is of course of immediate use to machine code files, but is of little use to Basic files until they have been modified by the 'RBASIC command of Romlt.

Please note that it is not advisable to restrict any data files as they cannot then be accessed via OPENIN, BGET#, *LOAD etc, or files that are used with *EXEC such as !BOOT, !TITLE and !HELP.

If the 'read' commands other than *RUN are attempted on a restricted file you will receive the error message: Locked

For example, to restrict a file called MY.PROGRAM so that it can not be loaded or chained, enter:

*RESTRICT MY.PROGRAM R RETURN

*REXEC

This command is very similar to *RELOAD and will directly change the execution, or run address of a file that is already held in the RaFS under the filename specified, to the new address you require. The address you specify here must be in hexadecimal but the leading '&' is not required.

The address you give may be upto 32 bits in length (8 digits), and, although only 6 digits are displayed via *INFO, all 8 are significant and are stored.

This command may be of little use to BASIC programmers as BASIC programs automatically load to PAGE and the run address is then ignored.

*RHELP

By issuing the command *RHELP special code is added to that held in the RaFS which will respond to the *HELP command by printing the contents of the text file !HELP.

The command *RHELP- will remove the code that *RHELP added to the RaFS. Either command may be used at any time without affecting anything already held in the RaFS, but if there is insufficient room to add the required code a 'RAM full' error message will be given.

There are three ways to construct the Ascii file !HELP for use with this command, and all are fully covered in section 3.1 to this manual. However, the simplest method is for users with a DFS fitted to enter the following:

*BUILD !HELP RETURN
1 <blank line> RETURN
2 First line of text RETURN
3 Second line of text RETURN
4 etc., etc., RETURN
5 ESCAPE

This will then give you the *HELP facility in your code so that when *HELP is issued your text is printed out. You may of course have as many or as few lines as you like, just so long as there is room in the RaFS to accomodate it all.

Suppose you have blown several Roms, each of which have the special code and corresponding !HELP file. Issuing the command *HELP will print the text in the !HELP file in the highest priority Rom socket only.

This may be avoided by using a filename that starts with the characters !HELP, but contains up to four additional characters as an identifier. For example, the following filenames are valid:

!HELP2
!HELPFour
!HELP+

When the command *RHELP is issued, it looks for a file that starts with the characters !HELP, and remembers the characters followng it.

If at any time you rename your !HELP file, you must enter *RHELP again so that the special code can be informed of the change.

The four characters following the !HELP filename which the special code currently identifies may be found by entering the *INFO command.

*RTITLE

By issuing the command *RTITLE special code is added to that held in the RaFS which means that you can then create a file with the filename !TITLE which will be printed on the screen whenever the BREAK key is pressed.

The command *RTITLE- will remove the code that *RTITLE added to the RaFS. Either command may be used at any time without affecting anything already held in the RaFS, but if there is insufficient room to add the required code a 'RAM full' error message will be given.

Please note that in order for the title to be printed on the screen once your code has been blown into an Eprom this Rom must be in a higher priority socket than the DFS, as this Rom inhibits any further Rom titles from being printed. Therefore, with the DFS in socket 14 and your Rom in socket 13 this function will not operate. However, reverse the position of the two Roms and the title will appear when BREAK is pressed.

The way in which a !TITLE file is built is exactly as given for *RHELP above. However, this time the information stored in that file will only be printed when the BREAK key is pressed. If your code contains several commonly used procedures to help you in your programming you could put the following in the !TITLE file. Again this shows the use of *BUILD, so users who do not have a DFS fitted should refer to section 3.1 which gives other methods for constructing this file.

*BUILD !TITLE RETURN
1 Graphics Procedures RETURN
2 *HELP gives names RETURN
3 <blank line> RETURN
4 ESCAPE

Suppose you have blown several Roms, each of which have the special code and corrosponding !TITLE file. Pressing BREAK will print the text in the !TITLE file in the highest priority Rom socket only.

This may be avoided by using a filename that starts with the characters !TITLE, but contains up to four additional characters as an idenifier. For example, the following filenames are valid:

!TITLErom7
!TITLE!!!
!TITLE-IAN

When the command *RTITLE is issued, it looks for a file that starts with the characters !TITLE, and remembers the characters following it.

If at any time you rename your !TITLE file, you must enter *RTITLE again so that the special code can be informed of the change.

The four characters following the !TITLE filename which the special code currently identifies may be found by entering the *INFO command.

*SNAP

Any time after issuing this command, pressing the CTRL key and the @ key together, releasing them and then pressing any other key will save the screen display to the RaFS under the filename SNAP plus the character of the key you pressed. For example:

*SNAPR
CTRL @
9

would save the current screen under the filename SNAP9 when the 9 is pressed.

To reload and display the screen image just saved, for example, SNAPS, it necessary to enter:

*LOAD SNAP9 RETURN

To use this SNAP-shot facility *RAM must have been previously issued. After issuing *SNAP any program may be run, and, if it is not protected, you may save any screen to the RaFS simply by pressing CTRL @ and another key.

Please note that this will not work with modes 0 to 3, as they are all too long to be stored in the RaFS. However, modes 4 to 7 may be saved in this way, and upto fourteen mode 7 screens may be held in the RaFS.

*SNAP

If *SNAP is called without the trailing R (as in *SNAPR) above), the screen will be saved to the currently activated filing system. This may or may not be the RaFS. (The trailing R selects the RaFS).

It should be noted that a screen that is to be saved with this method should not have been scrolled, as this can upset its internal start position.

For further details on the *SNAP command, refer to section 3.4.

*SPACE

When this command is issued the following display will result:

Free bytes in Ram E .... (16291) &3F93

The actual number displayed will of course depend on what you have in the RaFS, and that shown is how the command responds to a 16K RaFS with nothing having been saved to it.

Please note that the actual number of bytes given does not mean that a program of that length may be saved into the RaFS. This is because of the way the RaFS is handled. Each file saved is split into 256 byte blocks, and each block has a header. This header occupies a few extra bytes, so the actual space left to programs is less than that displayed. Note also that issuing either *RBOOT, *RHELP or *RTITLE also uses up space in the RaFS.

*UNWIPE

If the command *WIPE has been issued *UNWIPE will restore the contents of the RaFS. This however will only work if nothing has been saved to the RaFS since the *WIPE command was issued. *UNWIPE is equivalent to using OLD on a NEWed Basic program.

*WIPE

Issuing *WIPE has exactly the same effect on the RaFS as NEW does on a BASIC program. It may have its action reversed by using *UNWIPE.

*ENABLE must be issued immediately before *WIPE since the command will destroy the entire contents of the RaFS including those files that have been locked via *ACCESS. However, like NEW in Basic this is not fatal as it can be undone with *UNWIPE.

For example:

*ENABLE RETURN
*WIPE RETURN
Free bytes in RAM E .... (16291) &3FA3
>