R. T. RUSSELL

BBC BASIC (86) Manual

Operating System Interface

Introduction

As with the BBC micro computer, the star (*) commands provide access to the operating system. Since the BBC operating system is completely different to MS-DOS (PC DOS) there are a number of differences in the star commands.

When a star command is issued, BBCBASIC(86) first checks to see if it is one of the resident star commands. If it is not a resident command, it is passed to MS-DOS (PC DOS) for action. MS-DOS then treats it as if it had been entered in the operating system command mode in the normal way.

File Specifiers

File specifiers must comply with the standard MS-DOS (PC DOS) conventions.

[drive:][\][path\]filename.extension
drive: The single letter name (A to P) of the drive where the file will be found. The colon is mandatory. If the drive name is omitted, the currently logged-on drive is assumed.

path The list of directories which must be followed in order to find the specified file. The names of each directory in the path must be separated by the backslash character. If the path is omitted, the current directory on the specified drive is assumed.

filename The name of the file. The length of the name must not exceed 8 characters.

extension The optional extension of the file. If an extension is used it must be separated from the filename by a full-stop. If the extension is omitted, .BBC is assumed.

Drives A: to P: are accepted in file specifications. Filenames in star commands may optionally be enclosed in quotes; unmatched quotes will cause a 'Bad string' error. The standard MS-DOS (PC DOS) 'wild-cards' may be used when an ambiguous file specifier is acceptable.

? Allow any single character in this position. If this is used as the last character in the name, a null character will be accepted.

* Allow any character (including a null) from the position of the '*' to the end of the name or extension.

Symbols

The following symbols and abbreviations are used as part of the explanation of the operating system commands.

{} The enclosed items may be repeated 0 or more times.

[] The items enclosed are optional, they may occur zero or one time.

num A numeric constant.

str A string constant.

<num> A numeric variable.

<str> A string variable.

afsp An ambiguous file specifier.

ufsp An unambiguous file specifier.

d: A disk drive name.

dir A directory name.

pth A directory path ( \dir\dir\etc ).

Accessing Star Commands

The star commands may be accessed directly or via the OSCLI statement. The two examples below both access the HELP command.

*HELP

OSCLI("HELP")

Syntax

A star command must be the last (or only) command on a program line and its argument may not be a variable. If you need to use one of these commands with a variable as the argument, use the OSCLI statement. Examples of the use of the OSCLI statement are given below in the Resident Star Commands sub-section.

Non Resident Star Commands

If a star command is not one of the resident commands, it is passed to COMMAND.COM for execution. This will only work if BBCBASIC(86) can find a copy of COMMAND.COM and there is sufficient RAM. BBCBASIC(86) uses the COMSPEC parameter in the MS-DOS environment area to locate COMMAND.COM. This parameter is automatically set by MS-DOS at boot up.

The appropriate .EXE or .COM file will be loaded and executed by COMMAND.COM.

For example, you can copy files by using the *COPY command, which will be processed by COMMAND.COM.

*COPY source-afsp dest-afsp /V

*COPY ADDRESS.DTA B:

Unlike the resident commands, commands passed to COMMAND.COM do NOT assume an extension of .BBC if the extension is omitted.

Similarly Named Star Commands

If you wish to execute a command with the same name as a resident command, precede it with a second star. For example,

*DIR

will execute BBCBASIC(86)'s resident directory listing command, (only .BBC files in this case) but

**DIR

will pass the command to COMMAND.COM and you will get the standard MS-DOS (PC DOS) directory listing (all the files plus date/time stamps, etc).

Errors in Star Commands

If the command passed to COMMAND.COM does not exist, the MS-DOS 'Bad command or file name' error will occur. This error cannot be detected or trapped by BBCBASIC(86), and execution of the BBCBASIC(86) program will continue. For this reason, the *FX (with the exception of *FX 15) and *TV commands are trapped and ignored (they are not passed to COMMAND.COM). These two star commands are commonly found in programs for the BBC Micro, but they have no counterpart in MS-DOS.

Case Conversion

Star commands and their associated qualifiers are converted from lower-case to upper-case if necessary. For example, *del wombat is converted to *DEL WOMBAT. This is in keeping with the general MS-DOS (PC DOS) philosophy and the BBC Micro's machine operating system (MOS).

Special Characters

Control characters, lower-case characters, DEL and quotation marks may be incorporated in filenames by using the 'escape' character '|'.

|A gives ^A.

|a gives lower-case A.

|? gives Del.

|" gives the quote marks ".

|| gives the escape character |.

|! sets bit 7 of the following character.

Additional OS Interfaces

In addition to the facilities already described, the operating system interface provides very limited emulation of OSBYTE and OSWORD. Currently, this emulation is limited to reading the character at the current text cursor position (OSBYTE function &87) and reading the dot pattern of a given font character (OSWORD call &A).

OSBYTE and OSWORD are accessed in the same way as on a BBC Micro by USR to addresses &FFF4 (OSBYTE) and CALL to address &FFF1 (OSWORD).

Because a call to either of these addresses only provides a single function, it is not strictly necessary to pass the OSBYTE or OSWORD function number in A%, but it is best to do so to ensure compatibility with any future enhancements to BBCBASIC(86).

Current Character - OSBYTE Call

The character at the current text cursor position is returned and assigned to a variable called 'char' by the following program segment.

A%=&87
char=(USR(&FFF4) AND &FF00) DIV 256

Character Dot Pattern - OSWORD Call

The dot pattern of a character can be read as follows:

DIM pattern 8
?pattern=character
A%=&A
X%=pattern MOD 256:Y%=pattern DIV 256
CALL &FFF1

The character is loaded into byte zero of the 9 byte table called 'pattern' and the pattern is returned in the 8 bytes 'pattern?1' to 'pattern?8. As with the BBC Micro, the address of the table 'pattern' is passed in X% and Y%. The least significant byte is passed in X% and the most significant in Y%

OSRDCH, OSWRCH, OSKEY and OSCLI Calls

Your machine code programs may access the OSRDCH, OSWRCH, OSKEY and OSCLI routines via vectors provided in page 3 as shown below.

OSRDCH: CALLF [&300] ;Waits for and returns a char in the al register.

OSWRCH: CALLF [&304] ;Sends the char in the al register to the VDU driver.

OSKEY: CALLF [&308] ;With the time limit set in the ax register. Returns a character in the al register. The carry flag is set to zero if a timeout has occurred.

OSCLI: CALLF [&30C] ;With the dx register set to the address of the command string. The string must be terminated by a CR.

See the program INKEY.BBC for an example of the use of OSKEY.

CONTENTS

CONTINUE

`drive:`	The single letter name (A to P) of the drive where the file will be found. The colon is mandatory. If the drive name is omitted, the currently logged-on drive is assumed.
`path`	The list of directories which must be followed in order to find the specified file. The names of each directory in the path must be separated by the backslash character. If the path is omitted, the current directory on the specified drive is assumed.
`filename`	The name of the file. The length of the name must not exceed 8 characters.
`extension`	The optional extension of the file. If an extension is used it must be separated from the filename by a full-stop. If the extension is omitted, .BBC is assumed.

`?`	Allow any single character in this position. If this is used as the last character in the name, a null character will be accepted.
`*`	Allow any character (including a null) from the position of the '*' to the end of the name or extension.

{}	The enclosed items may be repeated 0 or more times.
[]	The items enclosed are optional, they may occur zero or one time.
num	A numeric constant.
str	A string constant.
<num>	A numeric variable.
<str>	A string variable.
afsp	An ambiguous file specifier.
ufsp	An unambiguous file specifier.
d:	A disk drive name.
dir	A directory name.
pth	A directory path ( `\dir\dir\etc` ).

\|A	gives ^A.
\|a	gives lower-case A.
\|?	gives Del.
\|"	gives the quote marks ".
\|\|	gives the escape character \|.
\|!	sets bit 7 of the following character.

`OSRDCH:`	`CALLF [&300]`	`;Waits for and returns a char in the al register.`
`OSWRCH:`	`CALLF [&304]`	`;Sends the char in the al register to the VDU driver.`
`OSKEY:`	`CALLF [&308]`	`;With the time limit set in the ax register. Returns a character in the al register. The carry flag is set to zero if a timeout has occurred.`
`OSCLI:`	`CALLF [&30C]`	`;With the dx register set to the address of the command string. The string must be terminated by a CR.`