Инструменты пользователя

Инструменты сайта


msx:nextor_basic:nextor_basic

Nextor BASIC

Nextor

Nextor BASIC = MSX BASIC + X-BASIC + много дополнительных полезных подпрограмм.

Nextor BASIC

Файлы

NestorBASIC 1.11

User's manual in english

User's manual in english

User's manual in english

NestorBASIC version 1.11
By Nestor Soriano (Konami Man), December 2004

1. WHAT IS NESTORBASIC?

NestorBASIC is a set of machine code routines, integrated in a single file.
It is intended for being used within MSX-BASIC programs. Without losing Turbo-BASIC compatibility, NestorBASIC gives you the following capabilities:

  • Full access to all te available memory of the computer (all existing memory in the case of DOS 1, all free memory in the case of DOS 2), up to 4 Mb.
  • Access to VRAM, with data block exchange between VRAM and between RAM and VRAM feature.
  • Storage of BASIC programs in the mapped RAM, which can be executed without losing the existing variables.
  • Access to disk files and direct access to physical sectors, with read/write to RAM/VRAM feature. File search, directory management.
  • Graphic compression and decompression.
  • Moonblaster music replay. Samplekit load.
  • PSG sound effects replay.
  • Execution of machine code routines placed on BIOS, SUB-BIOS, normal BASIC memory, system work area, or a mapped RAM segment.
  • Machine code routines execution, from BIOS or from any RAM segment. User defined interrupts.
  • NestorMan functions, InterNestor Suite and InterNestor Lite routines execution.

All of these functions are available through a single USR and an integer parameter array, therefore they are fully TurboBASIC compatibles. In fact, the TurboBASIC compiler itself is included into the NestorBASIC file, and it is automatically loaded when NestorBASIC is installed.

NestorBASIC is loaded in a RAM segment not used by BASIC, so only a small amount of the BASIC main RAM (aprox. 500 bytes) is needed for a jump routine. The rest of the BASIC main RAM remains available for the BASIC program.

2. SYSTEM REQUIREMENTS. LOADING NESTORBASIC

NestorBASIC works in any MSX2/2+/Turbo-R with at least 128K of mapped RAM. 
When DOS 2 is installed, at least one free segment is needed in the primary 
mapper (at least two if the music replayer will be used. See section 8 for 
details).

To load NestorBASIC, just do BLOAD"NBASIC.BIN",R. No previous nor further 
CLEAR nor DEFUSR is needed. If the installation is completed successfully, 
the following has then happened:

- NestorBASIC and TurboBASIC have been loaded, each one in a different RAM 
segment. Both are ready for use.

- The amount of free BASIC main RAM has been decreased in aprox. 500 bytes, 
which are occuped by a routine that jumps to the NestorBASIC segment.

- The first USR [USR0(parameter) or just USR(parameter)] points to the jump 
routine mentioned above. This will be the entry point for using the 
NestorBASIC functions.

- The integer array P has been created. This array will be used for passing 
parameters to, and returning results from the NestorBASIC functions. The 
error codes will be returned by the USR command. (The file access function 
and other functions like the ones for string processing need its own string 
array, which must be defined separately. See section 4 for details). The 
first five elements of P have been initialised as follows:

P(0) = Number of available RAM segments, or error code
P(1) = NestorBASIC main version
P(2) = NestorBASIC secondary version, in BCD format (must be shown in 
       hexadecimal format)
P(3) = MSX-DOS main version
P(4) = MSX-DOS secondary version, in BCD format (must be shown in 
       hexadecimal format)

The number of available RAM segments will be always at least 5. A smaller 
number in P(0) means an error code that has aborted the installation of 
NestorBASIC:

0: The computer has not mapped RAM, or has only 64K of mapped RAM.
1: Disk error when reading NestorBASIC or TurboBASIC from NBASIC.BIN.
2: No free segments are available in the primary mapper. This error may 
   appear only under DOS 2.
3: NestorBASIC was already installed. All variables have been initialized.
4: Undefined in this version.

After NestorBASIC installation, the CLEAR statement can be freely used in 
order to reserve memory for loading other machine code routines or user data 
in the BASIC main RAM. However, due to the fact that NestorBASIC performs 
slot/segment switchings in page 2, and the BASIC interpreter puts the stack 
in the BASIC main RAM below the area reserved with CLEAR, there is a lower 
limit for the address that can be specified in the CLEAR statement. 
Concretely, the lowest address that can be specified in the CLEAR statement 
when NestorBASIC is installed is given by:

&HC000 + (MAXFILES+1)*267 + FRE("") + 100

Also, remember that the CLEAR statement, as well as the 
load/erase/modification of any BASIC program, delete all the variables. In 
such case, the P array must be redefined with DEFINT P:DIM P(15), and this 
must be done out of turbo-blocks. Also, the F array must be redefined if 
needed (see section 4 for details about the array F). Watch out: if you need 
to define the F array inside of a turbo-block, you must do it in the first 
line of the turbo-block:

10 'save"autoexec.bas"
20 BLOAD"nbasic.bin",R:IF P(0)<5 THEN PRINT "Error!":END
30 CLEAR 100:DEFINT P:DIM P(15)
40 _TURBO ON(P())
50 DIM F$(1) 'See section 4
...
65000 _TURBO OFF
65010 RUN"next.bas"

10 'save"next.bas"
20 DEFINT P:DIM P(15)
30 _TURBO ON(P())
40 DIM F$(0) 'If F$(1) is not needed. See section 4.1
...
65000 _TURBO OFF

Also, remember that the first USR is always reserved for NestorBASIC. USR1 
to USR9 remain available for the user.


3. LOGICAL SEGMENTS

3.1. WHAT IS A LOGICAL SEGMENT?

The mapped RAM of the MSX computers is structured in 16K segment. Each RAM 
slot contains a given number S of segments (numbered 0 to S-1), which are 
accessibles when they are connected to the addressing space of the active RAM 
slot through ports &HFC to &HFF.

When NestorBASIC is installed, all the exisiting slots are scanned for 
available RAM (all the existing RAM in the case of DOS 1, all the free RAM in 
the case of DOS 2), and a segment table is built. In this table, all the 
found segments are registered as a couple slot+segment number (under DOS 2, 
all the segments are first allocated). NestorBASIC identifies each of these 
couples with his index number in the table. This number is named logical 
segment number, and allows the user to manage all the RAM segments in an easy 
and ordered way, without having to care about the slot(s) in which the RAM is 
located nor about the physical segment numbers.

For example, let's suppose a MSX with 128K of internal RAM (8 segments) and 
an external mapper of 1024K (64 segments). Then, when NestorBASIC is 
installed, and supposing DOS 1, the user has 72 logical segments available 
for its own use. To use these segments, just specify a logical segment number 
between 0 and 71 in the appropriate NestorBASIC functions, and don't worry 
about RAM slots nor about physical segments number.

The address range of a logical segment (just "segment" from now on) is &H0000 
to &H3FFF. If higher addresses are specified in the NestorBASIC functions, 
they will be converted. That is, addresses &H4000-&H7FFF, &H8000-&HBFFF and 
&HC000-&HFFFF are the same as &H0000-&H3FFF when accessing to RAM segments 
through NestorBASIC. 
All the segments are readable and writable, but there are important 
restrictions that apply to the first six ones:

- Segment 0 contains NestorBASIC itself, and only a small amount of RAM 
remains available for the user at the end of the segment. Use function 1 to 
obtain the beginning address of this free area (see section 10 for the 
function description).

- Segment 1 contains the TurboBASIC compiler. You can overwrite this segment 
only if you will not use the compiler.

- Segment 2 is always connected to page 2 (addreses &H8000 to &HBFFF), and 
contains the BASIC program being executed and maybe some variables.

- Segment 3 is always connected to page 3 (addresses &HC000 to &HFFFF), and 
contains the MSX work area and part of the BASIC program variables. Be 
careful when writing here.

- Segment 4 is used as an internal buffer by some NestorBASIC functions. You 
can use this segment to store your own data as long as you don't use these 
NestorBASIC functions. See section 10 or appendix 1 to know which functions 
use this segment.

- If it exists, segment 5 is initially free, and is not used by NestorBASIC. 
But when the music replayer is loaded, it is stored in this segment. See 
section 8 for details.

All other existing segments are completely available for the user.

WARNING: The roles of logical segments 2 and 4 have been swapped when 
stepping from version 0.07 to 1.00. In version 0.07 and previous versions, 
segment 2 was NestorBASIC internal buffer, and segment 4 was BASIC page 2 
RAM.

When using the data block exchange functions, be careful for not surpassing 
the address &H3FFF when adding the block length to the destination address 
(for example, don't try to transfer &H2000 bytes specifying address &H3000 as 
destination address). In such a case, segment 0 or segment 3 is overwrited, 
and then the result is unpredictable.

Note: using function 80 it is possible to force NestorBASIC to allocate less 
memory segments than the total amount available. This is useful under DOS 2 
when other programs which also need to allocate memory (for example RAM disk 
or NestorMan) are used simultaneously with NestorBASIC. See section 10 for 
the functions' description.


3.2. USING VRAM AS LOGICAL SEGMENTS

NestorBASIC allows you to use the VRAM for emulate extra RAM segments. If 
NestorBASIC founds a number S of segments, segment numbers 0 to S-1 refers to 
RAM segments, as explained above. But segments S to S+7 or S+3 (according to 
the VRAM capacity, 128K or 64K) are also available, and they refer to VRAM.

Let's return to the previos sample. When installing NestorBASIC, the number 
of available segments is 72. Then, segments 72 to 79 (if the computer has 
128K VRAM) or 72 to 75 (if the computer has 64K VRAM) are available for VRAM 
access.

The correspondence between segments and VRAM address is reversed: the 
segments with the lowest number refers to the highest VRAM addresses. This is 
done in this way in order to help the user when discarding the VRAM segments 
corresponding to the screen visualization: these segments will be the last 
ones when working in text mode, or when using the page 0 in graphic modes.

Let's return to the previous sample: the computer with 72 RAM segments and 
128K VRAM. If the program works in text mode, only the first 2000 bytes of 
VRAM are used: this VRAM area corresponds to the last VRAM segment, with 
number 79. Then, the user can use freely the segments 72 to 78, and the range 
of available segments becomex 0 to 78, without having to discard any 
intermediate segment. If the program works in SCREEN 5 and uses only graphic 
page 0, the range is 0 to 77; in SCREEN 7, it is 0 to 75, and so on.

Of course, NestorBASIC also includes functions for accessing VRAM with direct 
addressing specification, useful when the VRAM must be treated as VRAM and 
not as emulated RAM.

WARNING: VRAM segments can be used as normal RAM segments in order to store 
data and BASIC programs; also, data block exchange functions and disk access 
funtions are available when using VRAM segments. But note that the VRAM 
segments can't be used for the following purposes:

- Graphic compression/decompression
- Machine code routines execution
- User defined interrupt execution
- PSG sound effects replay
- Music replay

If you try to use VRAM segments for any of these purposes, the called 
function will return the "non existing segment" error.


3.3. THE SEGMENT 255

The logical segment number 255 has a special meaning. It does not refer to a 
concrete RAM or VRAM segment, but to the BASIC main RAM, that is, the RAM 
used by BASIC at addresses &H8000 to &HFFFF (in this case, addresses are not 
converted to the range &H0000-&H3FFF). This segment number is useful for 
example to exchange data between any segment and a BASIC variable or array:

 1 'Copy 10 bytes from segment 7, begin address &H1000,
 2 'to integer array D.
 3 '(See section 10 for detailed functions specification)
 4 '
10 DEFINT D:DIM D(4) '5 integer data = 10 bytes
20 P(0)=7	     'Source segment
30 P(1)=&H1000	     'Source begin address
40 P(2)=255	     'Destination segment=BASIC main RAM
50 P(3)=VARPTR(D(0)) 'Destination begin address=D array
60 P(4)=10	     'length
70 J=USR(10)	     'Call to function 10 (block transfer between segments)


3.4. SEGMENTS MAP

As a summary of this section, here is a list of the available segments and 
its description. S is the number of available segments, given by NestorBASIC 
when it is installed or when using function 1.

0: NestorBASIC segment
1: Turbo-BASIC segment
2: BASIC main RAM, page 2 (&H8000-&HBFFF)
3: BASIC main RAM, page 3 (&HC000-&HFFFF)
4: Internal buffer segment
5 to S-1: Available RAM for the user (if S>5)
   If the music replayer is loaded,
   it is stored in segment 5. See section 8.
S:   VRAM, addresses &H1C000-&H1FFFF (64K VRAM: &HC000-&HFFFF)
S+1: VRAM, addresses &H18000-&H1BFFF (64K VRAM: &H8000-&HBFFF)
S+2: VRAM, addresses &H14000-&H17FFF (64K VRAM: &H4000-&H7FFF)
S+3: VRAM, addresses &H10000-&H13FFF (64K VRAM: &H0000-&H3FFF)
S+4: VRAM, addresses &H0C000-&H0FFFF (not available with 64K VRAM)
S+5: VRAM, addresses &H08000-&H0BFFF (not available with 64K VRAM)
S+6: VRAM, addresses &H04000-&H07FFF (not available with 64K VRAM)
S+7: VRAM, addresses &H00000-&H03FFF (not available with 64K VRAM)

S+8 to 254: Not available (if S+8<255)
255: BASIC main RAM (&H8000-&HFFFF)


3.5. ERRORS

All the functions which perform RAM and/or VRAM access returns the error code 
-1 if any non existing RAM segment or VRAM address (addresses above &HFFFF in 
computers with 64K VRAM) is specified in any input parameter, or if any VRAM 
segment or the 255 segment is specified and the function supports only normal 
RAM segments.


4. DISK ACCESS

NestorBASIC has functions for disk files management and for the use of other 
MSX-DOS capabilities:

* Create/delete/rename/search files.
* Read/write files to/from RAM or VRAM.
* Under DOS 2, move files and get/set file attributes.
* Read/write disk sectors to/from RAM or VRAM.
* Get/set the default drive/directory.
* Obtain the disk size and free space.
* Under DOS 2, get size/set the RAM disk.


4.1. THE ARRAY F$

For passing filenames and pathnames to these functions, a string array named 
F$ is used. The functions for search, rename and move files, and for parse a 
pathname need two strings are needed, so F$ must be defined with two elements 
[DIM F$(1)]. The rest of disk access functions need only one string; 
therefore, if none of the four functions mentioned above are needed, it is 
recommended to define the array with only one element [DIM F$(0)], due to the 
string storage method of TurboBASIC: each string uses 256 bytes in RAM, 
regardless of its real length.

Also, remember that if you define a turbo-block, the F$ array must be defined 
in the first line:

1000 _TURBO ON(P())
1010 DIM F$(1) or DIM F$(0)
...
65000 _TURBO OFF

IMPORTANT: String variables defined outside a turboblock, as well as the 
other variables, are not usable from inside the turboblock, and are restored 
when it finishes. For example:

10 A$="Outside"
20 _TURBO ON
30 A$="Inside":PRINT A$
40 _TURBO OFF
50 PRINT A$
run
Inside
Outside

With NestorBASIC this still being true, but F$() strings need an additional 
caution. If F$ array has been used outside the turboblock and it will be used 
again inside, the following line must be placed before CALL TURBO ON:

F$(0)=F$(0)+"":F$(1)=F$(1)+""

This caution is not needed if you don't care about the old contents of F$, or 
if F$ will not be defined inside the turboblock.

Another restriction of F$(0) and F$(1) is that they are limited in length to 
80 characters; exceeding characters will just be ignored by NestorBASIC 
functions having these strings as input parameters. All these restrictions 
are not present for indexes higher than 1 if F$ is defined with more 
elements; that is, you can define F$ with more than two elements and use 
F$(2), F$(3)... normally.


4.2. ERRORS

In addition to error -1, described in section 3, the disk access functions 
have its own error codes.

The following errors can appear only under DOS 1:

1: General error code of MSX-DOS 1. It can be caused by the following error 
conditions:

   - File not found.
   - Invalid filename.
   - File already exists (when renaming).
   - Invalid drive (when being part of a filename).
   - End of file found when reading from a file.
   - Disk full.
   - Root directory full.
   - Function not available under DOS 1.

Under DOS 2, each one of the errors mentioned above have its own error codes, 
which is never 1.

2: Invalid file number (no opened file has this number assigned).
3: Too many opened files. The maximum number of files that can be opened 
   simultaneously under DOS 1 can be checked by using function 1.

The following errors can appear under DOS 1 and DOS 2, and have the same 
error code that their BASIC equivalents:

60: Bad FAT.
62: Invalid drive (when changing the default drive).
68: Write protected disk.
69: Physical disk error.
70: Disk offline.

The DOS 2 error codes are the following:

222: Not enough free DOS 2 internal memory to create the RAM disk or
     to open a file.
219: Invalid drive (when being part of a filename or pathname).
218: Invalid filename.
217: Invalid pathname.
215: File not found.
214: Directory not found.
213: Root directory full.
212: Disk full.
211: File already exists (when renaming or moving a file).
210: Invalid directory movement operation (a directory can't be moved into
     one of its descendants).
209: Read only file (when writing into a file).
208: The directory is not empty (when deleting a directory).
207: Invalid attributes (when changing the attributes of a file/directory).
206: Invalid "." or ".." operation.
205: System file exists (when creating a file, any previous existing file is
     automatically deleted, except the files having the system
     attribute set).
204: System directory exists (same as above).
203: File already exists (when creating a directory).
202: File is open (when deleting, renaming or moving a file, or when changing
     the file attribute with direct filename specification).
199: End of file is found (when reading from a file).
196: Too many opened files (when opening a file).
195: Invalid file number (greatest than 63).
194: Invalid file number (never assigned to an opened file).
188: RAM disk already exists (when creating RAM disk).
187: RAM disk does not exist (when removing RAM disk).


5. GRAPHIC COMPRESSION AND DESCOMPRESSION

NestorBASIC includes functions for the compression of graphic data from VRAM 
to RAM, and decompression from RAM to VRAM. The compression format is the 
same as the one used by Sunrise in the logo appearing routine, it is 
byte-based and is as follows:

- Unrepeated bytes (up to 63):

  &B00nnnnnn &Hdd .. &Hdd

  &Bnnnnnn is the number of bytes, &Hdd are the bytes

- Repeated byte (up to 63 times):

  &B01nnnnnn &Hdd

  &Bnnnnnn is the number of times that the byte is repeated, &Hdd is the
  repeated byte

- Repeated byte (up to 16383 times):

  &B10nnnnnn &Bnnnnnnnn &Hdd

  &Bnnnnnnnnnnnnnn is the number of times that the byte is repeated, &Hdd is
  the repeated byte

- End of data mark:

  &B11000000 = &HC0

The (de)compression is performed through consecutive segments; that is, after 
(de)compressing from/to address &H3FFF of segment S, the process continues in 
address &H0000 of segment S+1.


5.1 ERRORS

The following error codes can be returned by the graphic compresssion and 
decompression functions:

-1: Error when compressing or decompressing. The specified segment does not
    exist, refers to VRAM or is the 255. Also, this error appears when an
    invalid VRAM address is specified in any input parameter.
 5: Error when compressing. Segments have been exhausted before having
    compressed all the required graphic data.
 6: Error when decompressing. An invalid data is found, or segments have been
    exhausted before finding the end of data mark.


6. BASIC PROGRAMS STORAGE AND EXECUTION

NestorBASIC includes functions that allows the storage of BASIC programs in 
RAM or VRAM segments, and its activation or execution, without losing the 
existing variables generated by the original program. 

WARNING: For using these functions, the begin address of the BASIC programs 
in the BASIC main RAM must be changed, from &H8000 to &H8003; this operation 
must be done only once, and BEFORE NestorBASIC is installed. You can 
do this in two different ways:

- In direct mode, enter the following commands:

POKE &HF676,4
POKE &H8003,0
NEW

- From a BASIC program. This is the best way, because you can use the same 
program for performing this change and, after that, for loading NestorBASIC. 
The first line of the program must be as follows:

1 'program.bas
10 IF PEEK(&HF676)<>4 THEN POKE &HF676,4:POKE &H8003,0:RUN"program.bas"
20 'From here, you can load NestorBASIC

When a BASIC program stored in a segment will be activated or executed, 
NestorBASIC stores all the existing variables in segment 4; after that, the 
new program is copied from the specified segment to the BASIC main RAM, all 
variables are placed after the program, and the appropriate pointers in the 
BASIC work area are updated. The last step is the execution of the new BASIC 
program from the first line, or a jump to the direct mode, depending on the 
called function (execution or activation of the program).

If a BASIC program is intended for being stored in a segment and executed or 
activated with these functions, it must be stored with a special header with 
information about its length, which is needed in the process of concatenating 
the existing variables to the new program. There is a function that saves the 
current BASIC program with this header; later, just load this generated file 
in any segment with the disk access functions, and then you have the program 
stored and ready for being executed or activated.


6.1 ERRORS

Obviously, if the BASIC commands placed after the USR that calls the 
execution or activation functions are executed, an error has occurred. Two 
possible error codes can then be returned:

- Error -1, if the specified segment does not exist. These functions work 
with VRAM segments, but not with segment 255.
- Error -2, if the BASIC main RAM has not enough size for storing the new 
progam and the existing variables. Such situation can arise if the new 
program is biggest than the previous one.


7. MISCELLANEOUS FUNCTIONS

In this group there are various functions for the following purposes:

- Machine code routines execution. Routines placed in BIOS, SUB-BIOS, BASIC 
main RAM, system work area or any segment (called then "user routines") may 
be executed.
- Storage of string variables in RAM segments.
- Screen print of a string variable in graphic mode.
- SCREEN 0 blink mode management.
- User defined interrupts definition (machine code routines which will be 
executed, from any RAM segment, in each 50/60 Hz timer interrupt).
- SEE 3.xx PSG sound effects replay.

Some of these functions need a srtrings array, named F$, for passing 
parameters and returning results, in addition to the integer array P. See 
section 4 for more details about array F$.

Some of the NestorBASIC internal machine code routines can be used by the 
user machine code routines and by the user defined interrupt. See appendix 2 
for a detailed description about the use of these routines.

The PSG sound effects editor SEE was created by Fuzzy Logic, and the use of 
the sound effects created with this editor in commercial programs implies the 
pay of a small amount of money to the authors. See appendix 4 for more 
details.


8. THE MUSIC REPLAYER

8.1. INITIALIZATION OF THE REPLAYER

NestorBASIC includes Moonblaster 1.4 and Moonblaster for MoonSound Wave 
version 1.05 music replayers.

These replayers are not automatically loaded when NestorBASIC is loaded: due 
to its big length, they don't fit in the NestorBASIC RAM segment, and must be 
loaded in a separate segment. Thus, for using a replayer, it must be 
explicitly loaded. Only one replayer can be loaded at the same time.

Function 71 loads and initializes the desired replayer, leaving it ready for 
use. This function checks if segment 5 exists and belongs to the primary 
mapper: in this case, the replayer is loaded in this segment, which is no 
longer available for the user. If segment 5 does not exist or does not belong 
to primary mapper, the replayer will not be loaded, and an error will be 
returned by the function.

NBASIC.BIN file contains two versions of the Moonblaster Wave replayer: one 
is for MSX2/2+ and Turbo-R in Z80 mode, and the other is for Turbo-R in R800 
mode. If the computer is a Turbo-R, NestorBASIC decides the version to be 
loaded according to the processor switched when function 71 is called. Note 
that if a processor change is performed, this function must be called again 
in order to load the appropriate replayer: Z80 version does not work in R800 
mode, and R800 version makes the system slower in Z80 mode.

When the replayer is installed, a sound chips search is done, and all found 
chips are marked as enabled. See funtion 73 description for more details 
about enabling and disabling the sound chips.


8.2. REPLAYER CAPABILITIES

Once the replayer is loaded, you can use the functions that NestorBASIC 
includes for the following purposes:

- Start playing a music stored in any RAM segment (VRAM segments are 
not supported).
- Stop playing a music being played.
- Pause/continue the music being played.
- Fade out the music being played, with specification of the fading speed.
- Obtain various information about the music being played (segment and 
begin address in which the music is stored, songname and samplekit or 
wavekit, current position and step).
- Obtain the sound chips found.
- Disable the sound chips, which in this case will not be used even if they 
have been detected.
- Load a Music Module samplekit or a Moonsound wavekit from a file.

While a music is being replayed, all the NestorBASIC functions can be used 
normally, including the PSG sound effects replay and the use of user defined 
interrupts. If NestorBASIC is uninstalled, the music being replayed will be 
automatically stopped.

Moonblaster 1.4 replayer fits in 4.5K, therefore the space between addresses 
&H1200 and &H3FFF on segment 5 remains free and can be used, for example, for 
storing the music to be replayed. This does not occur with Moonblaster Wave 
replayer, which uses itself the whole segment 5.

Moonblaster 1.4 musics must be stored in a single segment, so its maximum 
length is 16K. Moonblaster Wave musics can be stored through consecutive 
segments, maximum 3: when reading music data during the replaying, if 
address &H3FFF of a segment is reached, the process continues in address 0 of 
the next segment.

In order to load a music through consecutive segments, the following sample 
code can be used:

1000 'Loading a music through consecutive segments,
1010 'starting in segment S, address A
1020 F$(0)="music.mwm":P(2)=S:P(3)=A
1030 E=USR(31):IF E<>0 THEN 10000
1040 P(4)=&H4000:E=USR(33)
1050 IF (E<>0 AND E<>1 AND E<>199) THEN 10000
1060 IF E=0 THEN P(2)=P(2)+1:P(3)=0:GOTO 1040
1070 E=USR(32):IF E<>0 THEN 10000
...
10000 'Disk error E handling routine
...

WARNING: A Moonblaster Wave music can start at any address of a segment, if 
it continues at the beginning of the next segment. However the first 800 
bytes of the music, containing pattern table and various pointers, must be 
entirely stored in the first segment.


8.3 ERRORS

The following error codes can be returned by the music replay functions:

- Error 7, returned by the sound chips activation function, pause function 
and fade out function, if any of the input parameters is invalid.
- Error 12, returned by the play start function and sound chips enabling 
function, if the replayer is not installed. The rest of the functions will 
simply do nothing in such case.

The following errors can be returned by the replay start function:

-1: The specified segment does not exist, refers to VRAM or is the 255.
12: The replayer is not installed.
13: The music was saved in EDIT mode and can't be replayed
    (Moonblaster 1.4 replayer).
    In the specified address there is no Moonblaster Wave music,
    or there is a Moonblaster Wave music not saved in USER mode.
    (Moonblaster Wave replayer).
14: Other music is currently being replayed.

MoonSound wavekit load function can return the following error, apart from 
the disk access errors:

15: In the current position of the specified file there is not placed a
    Moonblaster wavekit, or there is placed a wavekit not saved in USER mode.

NOTE: Moonblaster 1.4 replayer can't detect if the data starting in the 
specified address is actually a Moonblaster 1.4 music, and relies only in the 
first byte for deciding if data is a Moonblaster EDIT music. Moonblaster Wave 
replayer has not these restriction.

The replayer initialization function returns the same error codes as the disk 
access functions, and the error code -1 if the segment 5 does not exists or 
does not belong to the primary mapper.


9. INTERACTION WITH NESTORMAN AND INTERNESTOR SUITE/LITE

NestorBASIC has special functions that allow interaction with NestorMan 
(resident dynamic memory manager for MSX-DOS 2), InterNestor Suite (TCP/IP 
stack for MSX-DOS 2) and InterNestor Lite (TCP/IP 
stack for MSX-DOS 1/2), if these programs are installed. Therefore it is 
possibole to develop BASIC applications that use dynamic memory blocks and 
chained lists, as well as Internet based applications. To check if NestorMan 
and InterNestor Suite are installed, use function 81. The procedure for 
checking if InterNestor Lite is installed is detailed in section 9.4.

Note: NestorMan and InterNestor Suite/Lite have their own manuals describing 
the 
functions and routines provided by each one. These programs are available for 
download at http://msx.konamiman.com


9.1. NESTORBASIC SEGMENTS AND NESTORMAN SEGMENTS

NestorMan uses a logical segments system very similar to the system used by 
NestorBASIC. Both segments space, NestorBASIC's and NestorMan's, are 
independent to each other, with the following exceptions:

- Segments 0, 1, 2 and 3 are common to NestorBASIC and NestorMan (in 
NestorMan's manual these segments are referred to as "TPA segments").

- If NestorMan is present at NestorBASIC installation time, NestorBASIC 
logical segment 4 is not allocated using DOS 2 mapper support routines, as 
are the other segments. Instead, NestorMan function 7 is used for this; this 
way, NestorBASIC segment 4 has a NestorMan segment number assigned as well 
(this number can be obtained using NestorBASIC function 81). This segment is 
reserved with the "exclusive" attribute set, therefore it is not used by 
NestorMan for memory block reservations.

If NestorMan and/or InterNestor Suite will be used together with NestorBASIC, 
it is recommended to limit the amount of RAM segments that NestorBASIC will 
use (use function 80 for this). Otherwise NestorBASIC will allocate for 
itself all the available RAM segments, and therefore NestorMan will not be 
able to perform RAM segments allocation (this is needed for memory block 
reservations, chained lists creation, and for sending/receiving data to/from 
Internet).

To call NestorMan functions you can use function 82; or you can use function 
58 specifying the extended BIOS hook (&HFFCA) as the calling address, &H2202 
in the registers pair DE, and the functin number in register C. See section 
10 for the functions de
scription.


9.2. DATA EXCHANGE BETWEEN NESTORBASIC AND NESTORMAN

When using NestorMan through NestorBASIC, normally you will need to perform 
data transfers between a NestorBASIC segment and a NestorMan segment. There 
are three ways to do this:

1) If the source or destination segment is a TPA segment (segment number 
between 0 and 3), it is sufficient to use the appropriate NestorMan function 
for data block transfer (function number 14), since NestorMan can see these 
segments.

2) NestorBASIC segment 4 can be used as an intermediate buffer for the 
transfer. For example, suppose a transfer from NestorBASIC to NestorMan. S1 
is NestorBASIC source segment, S2 is NestorMan destination segment, and S3 is 
NestorMan segment number of NestorBASIC segment 4. Then, first you do a 
transfer S1->4 using NestorBASIC data transfer function (function number 10), 
and then you do a transfer S3->S2 using NestorMan data transfer function 
(function number 14).

3) NestorBASIC functions 83 and 84 are for data transfer from a NestorMan 
segment to a NestorBASIC segment and vice-versa. To read or write only one 
byte of data on a NestorMan segment, the easiest way is to use the functions 
that NestorMan provides for this purpose (function numbers 12 and 13).

Remember that some NestorBASIC functions use segment 4 as a temporary data 
storage buffer. Refer to section 10 or appendix 1 to know which are these 
functions.


9.3. USING INTERNESTOR SUITE

The procedures for using InterNestor Suite from NestorBASIC are similar to 
those for using NestorMan explained above. However the following should be 
noted:

- Function 85 is for executing InterNestor Suite routines.

- To read and write data on the InterNestor Suite segments (configuration 
constants and variables), first use function 81 to obtain the segment numbers 
of the InterNestor Suite modules (each module resides on a NestorMan 
segment), and from this point, use the data exchange procedures explained in 
previous section.

- InterNestor Suite routines for reading/writing TCP data or UDP datagrams 
only allow the use of TPA segments as the source/destination for the data or 
the datagrams. For this purpose you can use the final portion of NestorBASIC 
segment (segment number 0) as intermediate storage buffer. This space will 
always be at least 600 bytes long, regardless of the NestorBASIC version 
being used; this is enough to store a standard datagram of up to 576 bytes 
(or to store up to 600 bytes of TCP data).

The sample program TCPCON-S.BAS, supplied with NestorBASIC, illustrates the 
ensemble use of NestorBASIC and InterNestor Suite.


9.4. USING INTERNESTOR LITE

InterNestor Lite is much simpler than InterNestor Suite, hence using it from 
NestorBASIC is also a simpler task. Only one function is provided (function 
86), allowing the execution of any routine of the InterNestor Lite code 
segment. To read or write in its data segment, you must use the GET_VAR, 
SET_VAR and COPY_DATA routines of the code segment.

To know whether InterNestor Lite is installed or not, use function 58 issue a 
call to the extended BIOS hook (address &HFFCA), passing A=0 and DE=&H2203. 
If A<>0 at return, then InterNestor Lite is installed. See the description of 
function 86 for details.

Many of the InterNestor Lite routines use TPA addresses as the source or 
destination when exchanging data with applications. For these routines you 
can specify addresses above &H8000, that will refer to the BASIC main memory 
and the system work area; or addresses below &H4000, that will refer to 
NestorBASIC segment (segmento number 0).

At the end of the NestorBASIC segment there is a free area, whose size 
depends on the NestorBASIC version but will never be smaller than 600 bytes, 
which can be used as a temporary buffer for exchanging data with InterNestor 
Lite. In other words, you can use the space between H3DA8 and &H3FFF as the 
source or destination TPA area for a data exchange between NestorBASIC and 
InterNestor Lite.

The sample program TCPCON-L.BAS, supplied with NestorBASIC, illustrates the 
ensemble use of NestorBASIC and InterNestor Lite.


9.5. ERRORS

Function 86 (InterNestor Lite routine execution)returns error -1 if 
InterNestor Lite is not installed.

Function 85 (InterNestor Suite routine execution) returns error -1 if 
InterNestor Suite is not installed, or if an invalid module number is 
specified in P(0) (valid segment numbers are 1 to 4).

Functions 83 and 84 (data transfer between a NestorMan segment and a 
NestorBASIC segment) return error -1 if a non existing NestorMan or 
NestorBASIC segment number is specified. VRAM segments and segment 255 can be 
used with these functions.

Functions 80, 81 and 82 never return error.


10. NESTORBASIC FUNCTIONS

10.1. GENERAL DESCRIPTION

All the NestorBASIC functions available for the user are identified by the 
number passed as a parameter to the USR command. That is, for using the 
function with number F you just do USR(F)M remember that if F is a variable 
and not an immediate number, it must be variable of integer type. Parameters 
for the function must be set in the array P (and, in some cases, also in the 
array F$) before calling the function. Once executed, the results of the 
function will be returned in the same arrays, P and/or F.

Items of P and F$ not explicitly mentioned in the results list of each 
funtion are not modified, except the segment addresses; these are converted 
to the range &H0000-&H3FFF (except in the case of the segment 255). When a 
function returns an error, the results will not be valid (P and F$ are not 
modified), except if otherwise is specified in the description of the 
funtion.

"VRAM block" refers to 64K lower VRAM (block 0) or to 64K upper VRAM (block 
1). VRAM addresses have the range &H0000-&HFFFF. If any VRAM address surpass 
&HFFFF after an autoincrement, the new address will be &H0000 and the VRAM 
block will be reversed (from 0 to 1, or from 1 to 0).

The USR command will return an error code, or 0 if there is not error. 
Specific error codes for each functions group are detailed in each section.

Appendix 1 contains a list of all available functions. Use it as a quick 
reference.

Functions that use segment 4 have a "(S4)" mark after their name. These 
functions are: 0, 26-28, 30, 33-41, 55-57, 71, 78, and 79.


10.2. GENERAL FUNCTIONS

* Function 0: NestorBASIC uninstallation (S4)

Input:	 P(0) = 0 -> Don't free BASIC main RAM area reserved by NestorBASIC
	 P(0) <>0 -> Free the BASIC main RAM area reserved by NestorBASIC
Out:	 -

This function uninstalls NestorBASIC: makes the USR unusable and, in the case 
of DOS 2, frees all the reserved segments. Also, all interrupt process (user 
defined interrupt, PSG sound effects replay and music replay) are stopped. 
NestorBASIC should always be uninstalled before returning to DOS; otherwise, 
all the allocated RAM segments will not be freed, and will therefore be 
unusable until the computer is reset.

Before uninstalling NestorBASIC, check that no files still open. Else, if you 
have done file writings, you can lost some data in the internal DOS buffers.

If P(0)=0 is specified, the BASIC main RAM zone ocuped by the jump routine 
(aprox. 500 bytes) is not freed; then, any memory reservation done with the 
CLEAR statement after the installation of NestorBASIC remains valid. If 
P(0)<>0 is specified, a new CLEAR statement is automatically executed, and 
the highest RAM address usable for BASIC programs and variables becomes the 
same as before the NestorBASIC installation; that is, FRE(0) returns the same 
value as before the installation of NestorBASIC. Note that in this case, 
variables are initialized.

This function never returns error.


* Function 1: General information about NestorBASIC and about a segment

Input:	 P(10)= Logical segment to investigate
Output:  P(0) = Number of available RAM segments
	 P(1) = NestorBASIC main version
	 P(2) = NestorBASIC secondary version, in BCD format
		(must be shown in hexadecimal format)
	 P(3) = MSX-DOS main version
	 P(4) = MSX-DOS secondary version, in BCD format
		(must be shown in hexadecimal format)
	 P(5) = Amount of memory occuped in the BASIC main RAM
		by the jump routine
	 P(6) = VRAM size in K (64 or 128)
	 P(7) = Begin address of the free area in segment 0
                (&H3DA8 at most)
	 P(8) = Number of last function called
	 P(9) = Number of currently opened files
	 P(10)= Maximum number of simultaneously opened files
		(valid only under DOS 1)
	 P(11)= Slot that contains the logical segment specified in P(0)
		(255 if this segment does not exist or refers to VRAM)
	 P(12)= Physical segment number of the logical segment
		specified in P(0)
	 F$(0)= Complete path of NBASIC.BIN file

In the case of DOS 2, the maximum number of simultaneously opened files 
depends on the state of the DOS internal memory, but will never be bigger 
than 63.

This function returns an error code of -1 if the logical segment specified in 
P(0) does not exist, refers to VRAM or is the 255. However, even in this case 
the results returned in P(0) to P(10) will be valid.

The number returned in P(0) by this function is the same as the number 
returned in P(0) by function 81; that is, it is the number of segments 
allocated by NestorBASIC. By default (if function 81 has never been called 
after installing NestorBASIC), NestorBASIC allocates for itself all the 
available RAM segments (up to 247) at installation time.

F$(0) will be just a drive letter and a colon under DOS 1 (for example "A:"), 
and a drive+directory finished with "\" under DOS 2 (for example 
"C:\UTILS\AMAZING\").

Address returned in P(7) dependes on NestorBASIC version, but it will be 
always equal to or smaller than &H3DA8; that is, at least 600 bytes will be 
always available at the end of the NestorBASIC segment. This area may be 
used, for example, for temporary storage of TCP data or a UDP datagram when 
using InterNestor Suite with NestorBASIC.

P(8) returns the number of the last function called, but function 1 itself is 
not counted. So if you call, for example, functions 64, 3, 10, 1, 1, 1 in 
sequence, you will obtain P(8)=10 at the end. A value of zero means that no 
functions were called other than function 1 since NestorBASIC was installed.


10.3. FUNCTIONS FOR LOGICAL SEGMENTS ACCESS

* Function 2: Read a byte from a segment

Input:	 P(0) = Segment
	 P(1) = Address
Output:  P(2) = Readed byte


* Function 3: Read a byte from a segment with address autoincrement

Input:	 P(0) = Segment
	 P(1) = Address
Output:  P(2) = Readed byte
	 P(1) = P(1) + 1


* Function 4: Read an integer (2 bytes) from a segment

Input:	 P(0) = Segment
	 P(1) = Address
Output:  P(2) = Readed integer

Low byte is read from address P(1), and high byte from address P(1)+1.


* Function 5: Read an integer (2 bytes) from a segment
	      with address autoincrement

Input:	 P(0) = Segment
	 P(1) = Address
Output:  P(2) = Readed integer
	 P(1) = P(1) + 2

Low byte is read from address P(1), and high byte from address P(1)+1.


* Function 6: Write a byte to a segment

Input:	 P(0) = Segment
	 P(1) = Address
	 P(2) = Byte to be written
Output:  -


* Function 7: Write a byte to a segment with address autoincrement

Input:	 P(0) = Segmento
	 P(1) = Address
	 P(2) = Byte to be written
Output:  P(1) = P(1) + 1


* Function 8: Write an integer (2 bytes) to a segment

Input:	 P(0) = Segment
	 P(1) = Address
	 P(2) = Integer to be written
Output:  -

Low byte is written to address P(1), and high byte to address P(1)+1.


* Function 9: Write an integer (2 bytes) to a segment
	      with address autoincrement

Input:	 P(0) = Segment
	 P(1) = Address
	 P(2) = Integer to be written
Output:  P(1) = P(1) + 2

Low byte is written to address P(1), and high byte to address P(1)+1.


* Function 10: Data block transfer between segments

Input:	 P(0) = Source segment
	 P(1) = Source start address
	 P(2) = Destination segment
	 P(3) = Destination start address
	 P(4) = Data length
	 P(5)<> 0 -> Autoincrement of P(1)
	 P(6)<> 0 -> Autoincrement of P(3)
Output:  P(1) = P(1) + P(4) if P(5)<>0
	 P(3) = P(3) + P(4) if P(6)<>0

P(3)+P(4) must be lower than &H4000, otherwise the result is unpredictable.


* Function 11: Fill a RAM zone with a byte

Input:	 P(0) = Segment
	 P(1) = Begin address
	 P(2) = Byte
	 P(3) = Zone length
Output:  -

P(3)+P(4) must be lower than &H4000, otherwise the result is unpredictable.


* Function 12: Fill a RAM zone with a byte with address autoincrement

Input:	 P(0) = Segment
	 P(1) = Begin address
	 P(2) = Byte
	 P(3) = Zone length
Output:  P(1) = P(1) + P(3)

P(3)+P(4) must be lower than &H4000, otherwise the result is unpredictable.


10.4. FUNCTIONS FOR VRAM ACCESS

* Function 13: Read a byte from VRAM

Input:	 P(0) = VRAM block
	 P(1) = Address
Output:  P(2) = Readed byte


* Function 14: Read a byte from VRAM with address autoincrement

Input:	 P(0) = VRAM block
	 P(1) = Address
Output:  P(2) = Readed byte
	 P(0):P(1) = P(0):P(1) + 1


* Function 15: Read an integer (2 bytes) from VRAM

Input:	 P(0) = VRAM block
	 P(1) = Address
Output:  P(2) = Readed integer

Low byte is read from address P(1), and high byte from address P(1)+1.


* Function 16: Read an integer (2 bytes) from VRAM
	       with address autoincrement

Input:	 P(0) = VRAM block
	 P(1) = Address
Output:  P(2) = Readed integer
	 P(0):P(1) = P(0):P(1) + 2

Low byte is read from address P(1), and high byte from address P(1)+1.


* Function 17: Write a byte to VRAM

Input:	 P(0) = VRAM block
	 P(1) = Address
	 P(2) = Byte to be written
Output:  -


* Function 18: Write a byte to VRAM with address autoincrement

Input:	 P(0) = VRAM block
	 P(1) = Address
	 P(2) = Byte to be written
Output:  P(0):P(1) = P(0):P(1) + 1


* Function 19: Write an integer (2 bytes) to VRAM

Input:	 P(0) = VRAM block
	 P(1) = Address
	 P(2) = Integer to be written
Output:  -

Low byte is written to address P(1), and high byte to address P(1)+1.


* Function 20: Write an integer (2 bytes) to VRAM
	       with address autoincrement

Input:	 P(0) = VRAM block
	 P(1) = Address
	 P(2) = Integer to be written
Output:  P(0):P(1) = P(0):P(1) + 2

Low byte is written to address P(1), and high byte to address P(1)+1.


* Function 21: Data block transfer from VRAM to RAM

Input	 P(0) = Source VRAM block
	 P(1) = Source start address (VRAM)
	 P(2) = Destination segment
	 P(3) = Destination start address (RAM)
	 P(4) = Block length
	 P(5)<> 0 -> Autoincrement of P(1)
	 P(6)<> 0 -> Autoincrement of P(3)
Output:  P(1) = P(1) + P(4) if P(5)<>0
	 P(2):P(3) = P(2):P(3) + P(4) if P(6)<>0

P(1)+P(4) must be lower than &H4000, otherwise the result is unpredictable.


* Function 22: Data block transfer from RAM to VRAM

Input:	 P(0) = Source segment
	 P(1) = Source start address (RAM)
	 P(2) = Destination VRAM block
	 P(3) = Destination start address (VRAM)
	 P(4) = Block length
	 P(5)<> 0 -> Autoincrement of P(1)
	 P(6)<> 0 -> Autoincrement of P(3)
Output:  P(1) = P(1) + P(4) if P(5)<>0
	 P(2):P(3) = P(2):P(3) + P(4) if P(6)<>0


* Function 23: Data block tranfer between VRAM

Input:	 P(0) = Source VRAM block
	 P(1) = Source start address
	 P(2) = Destination VRAM block
	 P(3) = Destination start address
	 P(4) = Block length (maximum &H4000)
	 P(5)<> 0 -> Autoincrement of P(1)
	 P(6)<> 0 -> Autoincrement of P(3)
Output:  P(0):P(1) = P(0):P(1) + P(4) if P(5)<>0
	 P(2):P(3) = P(2):P(3) + P(4) if P(6)<>0

If P(4) is greatest than &H4000 only &H4000 bytes will be transferred, and 
the addresses increment will be also limited to &H4000, but P(4) will not be 
modified. Thus, for transferring largest blocks (up to 64K) in a easy way you 
can do something like the following:

10 'P(0) to P(3) already set. Data block length set in L.
20 P(5)=1:P(6)=1
30 P(4)=VAL("&H"+HEX$(L)):J=USR(23):L=L-&H4000:IF L>0 THEN 30

The decimal to hexadecimal and further hexadecimal to decimal conversion of L 
is needed due to the integer variables range in BASIC: -32768 to 32767; if a 
biggest number is directly assigned to P(4), an overflow error will be 
generated.

Since TurboBASIC manages floating point variables in a special way, if you 
use this method inside a turbo-block, L must be an integer multiply of 256.


* Function 24: Fill a VRAM zone with a byte

Input:	 P(0) = VRAM block
	 P(1) = Start address
	 P(2) = Byte
	 P(3) = Zone length (maximum 16K)
Output:  -

For fill a zone largest than 16K, use the method described in function 23.


* Function 25: Fill a VRAM zone with a byte with address autoincrement

Input:	 P(0) = VRAM block
	 P(1) = Start address
	 P(2) = Byte
	 P(3) = Zone length (maximum 16K)
Output:  P(0):P(1) = P(0):P(1) + P(3)

For fill a zone largest than 16K, use the method described in function 23.


10.5. DISK ACCESS FUNCTIONS

* Function 26: Search for a file (S4)

Input:	 F$(1) = Searching mask (empty string="*.*")
	 P(0)  = 0 -> Seacrh for first mactching filename
	 P(0)  = 1 -> Seacrh for next matching filename
	 P(1)  = Search attributes: 2*H + 4*S + 8*V + 16*D
		 H = 1 -> Include hidden files in the search
		 S = 1 -> Include system files in the search
		 V = 1 -> Search only the volume label
		 D = 1 -> Include subdirectories in the search
Output:  F$(0) = Found filename
	 P(0)  = 1
	 P(1)  = File attributes (always 0 under DOS 1):
		 R + 2*H + 4*S + 8*V + 16*D + 32*A
		 R = 1 -> Read only
		 H = 1 -> Hidden
		 S = 1 -> System
		 V = 1 -> Volume label
		 D = 1 -> Directory
		 A = 1 -> Archive
	 P(2)  = Hour of creation/last modification (0 to 23)
	 P(3)  = Minute of creation/last modification (0 to 59)
	 P(4)  = Day of creation/last modification (1 to 31)
	 P(5)  = Month of creation/last modification (1 to 12)
	 P(6)  = Year of creation/last modification (1980 to 2079)
	 P(7)  = First cluster (2 to 4095)
	 P(8)  = Logical drive (0=A:,...,7=H:)
	 P(9)  = File length (lower part)
	 P(10) = File length (higher part)
	 P(11) = 0, if searching first no file is found
		 1, if searching first a file is found
		 P(11), if searching next no file is found
		 P(11)+1, if searching next a file is found

F$(1) can include a drive letter and, in the case of DOS 2, a pathname; F$(0) 
will contain only the filename found.

P(0) must be set to 0 to search the first filename matching the specified 
mask, and must be left to 1 to search the following filenames. This is done 
automatically by the function (P(0) is always set to 1). Besides, P(11) is 
set to 1 when the first filename is searched (0 if none is found), and is 
increased automatically in each successive search. Thus, to search all the 
matching filenames you can use a loop like the following one:

10 'Search of all the filenames in drive B: (default directory)
20 F$(1)="B:":P(0)=0:P(1)=2+16 'Include directories and hidden files
30 IF USR(26)<>0 THEN PRINT:PRINT"Total found:";P(11):END
40 PRINT F$(0),CHR$(-ASC("h")*((P(1)AND2)<>0));
	       CHR$(-ASC("d")*((P(1)AND16)<>0));
	       CHR$(-ASC("a")*((P(1)AND32)<>0)):GOTO 30

When there is no more matching files/directories remaining, the function will 
return the "File not found" error. Under DOS 1, an error when searching the 
first matching filename may also mean an invalid drive or filename 
specification in the input mask (under DOS 2, these errors have its own error 
code).

To obtain the file length, use the expression P(9)+65536*P(10). When printing
these lengths in the screen, remember that the numeric variables screen 
representation is different for BASIC and TurboBASIC when the number is big; 
therefore, it is better to print the file size in K: INT(P(9)/1024)+64*P(10).


* Function 27: Rename a file (S4)

Input:	 F$(0) = File name
	 F$(1) = New file name
Output:  -

F$(0) can include a drive letter and, in the case of DOS 2, also a pathname; 
F$(1) must contain only the new filename. Under DOS 1 you can rename several 
files at the same time by using wildcards; under DOS 2 you can rename only 
one file at the same time.


* Function 28: Delete a file

Input:	 F$(0) = File name
Output:  -

F$(0) can include a drive letter and, in the case of DOS 2, a pathname. Under 
DOS 2 this function will return an error if you try to delete an open file. 
Under DOS 1 you can delete opened files, but this is not advisable because 
further attempts to access this file may cause unpredictable results.

Under DOS 1 you can delete several files at the same time by using wildcards; 
under DOS 2 you can delete only one file at the same time.


* Function 29: Move a file (DOS 2)

Input:	 F$(0) = File name
	 F$(1) = New file location
Output:  -

This function is only available under DOS 2. Under DOS 1 will always return 
the error code 1.

F$(0) can include a drive letter and a pathname. F$(1) can not include a 
filename (the file is always moved with the same name) nor a drive letter (a 
file can be moved only to other directory on the same drive). If you specify 
a directory instead of a file in F$(0), all its subdirectories and contained 
files will also be moved.


* Function 30: Create a file or directory

Input:	 F$(0) = Name of the file or subdirectory
	 P(0)  = Creation attributes (ignored under DOS 1):
		 R + 2*H + 4*S when creating a file;
		 2*H + 16 when create a directory.
		 R = 1 -> Read only
		 H = 1 -> Hidden
		 S = 1 -> System

F$(0) can include a drive letter and a pathname. The file will be created 
with a length of 0 bytes, and will not remain open: for accessing the file, 
it must be first explicitly opened (use function 31 to open a file).

Under DOS 1 you can only create files, and P(0) is ignored. Under DOS 2 the 
files are always created with the "Archive" attribute set, in addition to the 
attributes specified in P(0).


* Function 31: Open a file

Input:	 F$(0) = File name
Output:  P(0)  = Number assigned to the file

F$(0) can contain a drive letter and, in the case of DOS 2, also a pathname. 
The number returned in P(0) identifies the file, and must be specified in 
further calls to the file access functions. The concrete value of this number 
depends on the DOS version and the number of previously opened and closed 
files: don't rely on it as a reference of the number of currently opened 
files (use function 1 to obtain the number of currently opened files).

Under DOS 1 an error code of 3 will be returned if there is already too many 
opened files. Use function 1 to obtain the maximum number of simultaneously 
opened files under DOS 1.


* Function 32: Close a file

Input:	 P(0) = File number
Output:  -

It is very important to close a file that will no longer be accessed: 
otherwise, if the file has been written you can lose some data in the DOS 
internal buffers; besides, in this case the directory entry of the file will 
not be updated.


* Function 33: Read from a file (S4)

Input:	 P(0) = File number
	 P(2) = Destination segment
	 P(3) = Destination start address
	 P(4) = Number of bytes to read
	 P(6) = Increase P(3) if <>0
Output:  P(7) = Number of bytes actually read
	 P(3) = P(3)+P(4) if P(6)<>0

P(3)+P(4) must be lowest than &H4000, otherwise the result is unpredictable.

The file is read from the position indicated by its file pointer; this 
pointer is automatically increased after the read. To examinate or modify 
a file pointer, use function 42.

To read till the end of the file, or to read the whole file if it is shorter 
that 16K, just try to read 16K (set P(4)=&H4000), and ignore the returned 
error if it is 1 or 199: for this function, these errors mean only 
that the end of the file has been reached.

If the end of the file is reached before having read P(4) bytes an error will 
be returned; to obtain the number of read bytes look at P(7). If no error is 
returned, P(7) will have the same value as P(4); in the case of a physical 
error (bad FAT, physical disk error or disk offline), P(7) will always be 0.


* Function 34: Read from a file to VRAM (S4)

Input:	 P(0) = File number
	 P(2) = Destination VRAM block
	 P(3) = Destination start address
	 P(4) = Number of bytes to read (maximum &H4000)
	 P(6) = Increase P(3) if <>0
Output:  P(7) = Number of bytes actually read
	 P(2):P(3) = P(2):P(3)+P(4) if P(6)<>0

If P(4) is greater than &H4000, only &H4000 bytes will be read, and the 
address increment will also be limited to &H4000, but P(4) will not be 
modified. Thus, to read larger blocks (up to 64K) you can use the method 
described in function 23.

See function 33 for explanations about the file pointer and the value 
returned in P(7).


* Function 35: Read disk sectors (S4)

Input:	 P(0) = Drive (0=A:,...,7=H:)
	 P(1) = First sector number
	 P(2) = Destination segment
	 P(3) = Destination start address
	 P(4) = Number of sectors to read (maximum 32)
	 P(6) = Increase P(3) if <>0
Output:  P(7) = P(4)*512 (0 in error condition)
	 P(3) = P(3)+P(4)*512 if P(6)<>0

P(3)+P(4)*512 must be lower than &H4000, otherwise the result is 
unpredictable.

This function does not support partial readings: if there is no error, P(7) 
will return the number of read bytes, that is, P(4)*512; but in case of error 
P(7) will be always 0. If P(6)<>0, P(3) will be increased by the number of 
readed bytes (P(7) or 0).


* Function 36: Read disk sectors to VRAM (S4)

Input:	 P(0) = Drive (0=A:,...,7=H:)
	 P(1) = First sector number
	 P(2) = Destination VRAM block
	 P(3) = Destination begin address
	 P(4) = Number of sectors to read (maximum 32)
	 P(6) = Increase P(3) if <>0
Output:  P(7) = P(4)*512 (0 in error condition)
	 P(3) = P(3)+P(4)*512 if P(6)<>0

If P(4) is greater than 32 only 32 sectors (&H4000 bytes) will be read, and 
the address increment will also be limited to &H4000, but P(4) will not be 
modified. Thus, to read larger blocks (up to 64K) you can use the method 
described in function 23.

See function 35 for an explanation about the value returned in P(7).


* Function 37: Write to a file (S4)

Input:	 P(0) = File number
	 P(2) = Source segment
	 P(3) = Source start address
	 P(4) = Number of bytes to be written
	 P(6) = Increase P(3) if <>0
Output:  P(7) = Number of bytes actually written
	 P(3) = P(3)+P(4) si P(6)<>0

P(3)+P(4) must be lower than &H4000, otherwise the data written to the file 
is unpredictable.

Data is written to the file from the position indicated by its file pointer; 
this pointer is automatically increased after the writing. For examinate or 
modify a file pointer use function 42. In the case of a physical error (bad 
FAT, physical disk error or disk offline) P(7) will always be 0.


* Function 38: Write to a file from VRAM (S4)

Input:	 P(0) = File number
	 P(2) = Source VRAM block
	 P(3) = Source start address
	 P(4) = Number of bytes to be written (maximum &H4000)
	 P(6) = Increase P(3) if <>0
Output:  P(7) = Number of bytes actually written
	 P(2):P(3) = P(2):P(3)+P(4) if P(6)<>0

If P(4) is greater than &H4000, only &H4000 bytes will be written, and the 
address increment will also be limited to &H4000, but P(4) will not be 
modified. Thus, to write larger blocks (up to 64K) you can use the method 
described in function 23.

See function 37 for an axplanation about the file pointer.


* Function 39: Write to disk sectors (S4)

Input:	 P(0) = Drive (0=A:,...,7=H:)
	 P(1) = First sector number
	 P(2) = Source segment
	 P(3) = Source start address
	 P(4) = Number of sectors to be written (maximum 32)
	 P(6) = Increase P(3) if <>0
Output:  P(7) = P(4)*512 (0 in error condition)
	 P(3) = P(3)+P(4)*512 if P(6)<>0

P(3)+P(4)*512 must be lowest than &H4000, otherwise the written data is 
unpredictable.

This function does not supports partial writes: if there is no error, P(7) 
will return the number of written bytes, that is, P(4)*512; but in case of 
error P(7) will be always 0. If P(6)<>0, P(3) will be increased by the number 
of written bytes (P(7) or 0).


* Function 40: Write to disk sectors from VRAM (S4)

Input:	 P(0) = Drive (0=A:,...,7=H:)
	 P(1) = First sector number
	 P(2) = Source VRAM block
	 P(3) = Source start address
	 P(4) = Number of sectors to be written (maximum 32)
	 P(6) = Increase P(3) if <>0
Output:  P(7) = P(4)*512 (0 in error condition)
	 P(3) = P(3)+P(4)*512 si P(6)<>0

If P(4) is greatest than 32 only 32 sectors (&H4000 bytes) will be written, 
and the address increment will also be limited to &H4000, but P(4) will not 
be modified. Thus, to write largest blocks (up to 64K) you can use the method 
described in function 23.

See function 39 for an explanation about the value returned in P(7).


* Function 41: Fill a file with one byte (S4)

Input:	 P(0) = File number
	 P(1) = Byte
	 P(4) = length (maximum &H4000)
Output:  P(7) = Number of bytes actually written

This function just writes P(4) bytes equal to the value indicated in P(1) in 
segment 4, beginning at address 0, and then calls function 37 with P(2)=4 and 
P(3)=0. Thus, all the explanations given in function 37 are also valid here.


* Function 42: Move a file pointer

Input:	 P(0) = File number
	 P(1) = Moving method:
		0 -> Relative to the beginning of the file
		1 -> Relative to the current position of the pointer
		2 -> Relative to the end of the file
	 P(2) = Signed offset (lower part)
	 P(3) = Signed offset (higher part)
Output:  P(4) = New file pointer position (lower part)
	 P(5) = New file pointer position (higher part)

TO set P(2) and P(3) with an offset D greater than 32768 or lower than 
0 you must use the followin formula:

P(3)=INT(D/65536):P(2)=VAL("&H"+HEX$(D-(P2*65536)))

and to obtain the new pointer P:

P=P(4)-(65536*(P(4)<0))+65536!*P(5)

Since TurboBASIC manages floating point variables in a special way, if you 
use these expressions inside a turbo-block, D must be an integer multiply of 
256.

To obtain the current file pointer position, just use this function with 
P(1)=1, P(2)=0 and P(3)=0; to obtain the file length, use it with P(1)=2, 
P(2)=0 and P(3)=0. In the first case the file pointer remains unmodified.

Rememeber that the offset is interpreted as a signed number. Therefore, when 
using this function note with the following:

- If you use this function with P(1)=0, the offset must be positive. 
Otherwise, further access to the file will have unpredictable results.

- If you use this function with P(1)=1, a positive offset will cause the file 
pointer to advance; a negative offset will cause the file pointer to move 
back.

- If you use this function with P(1)=2, the offset should normally be 
negative; otherwise, the file pointer will be placed beyond the file length. 
In this case, a further read of the file will cause an "End of file" error (0 
bytes will be read), and a write to the file will cause the space between the 
end of the file and the position indicated by the file pointer to be filled 
with zeros.


* Function 43: Obtain the default drive and the available drives vector

Input:	 -
Output:  P(0) = Default drive (0=A:,...,7=H:)
	 P(1) = Available drives vector

The available drives vector is a byte that contains, in each bit, information 
about the existence of each drive letter (bit=1: exists, bit=0: does not 
exist); the lower bit refers to drive A: and the upper bit refers to drive 
H:. For example, if the function returns P(1)=&B01000011, then the available 
drives are A:, B: and G:.


* Function 44: Set the default drive

Input:	 P(0) = Drive to be set (0=A:,...,7=H:)
Output:  -

This function returns the error code 62 to an attempt of setting an invalid 
drive (not available or higher than 7).


* Function 45: Obtain disk space information

Input:	 P(0) = Drive (0=Default drive, 1=A:,...,8=H:)
Output:  P(1) = Sectors per cluster
	 P(2) = Total number of clusters (maximum 4096)
	 P(3) = Number of free clusters

The free space in bytes can be obtained with the expression P(1)*P(3)*512, or 
in K with P(1)*P(3)/2; and the same for the total disk capacity, using P(2) 
instead of P(3).

This function returns the error code 62 to an attempt of obtaining 
information for an invalid drive (not available or higher than 8).


* Function 46: Obtain the default directory (DOS 2)

Input:	 P(0) = Drive (0=Default drive, 1=A:,...,8=H:)
Output:  F$(0)= Default directory

This function is only available under DOS 2. Under DOS 1 will always return 
the error code 1.

The returned string will not include drive letter, nor "\" at the beginning 
nor at the end; thus, the root directory will be represented as an empty 
string. 


* Function 47: Set the default directory (DOS 2)

Input:	 F$(0) = Drive (optional) + directory
Output:  -

This function is only available under DOS 2. Under DOS 1 will always return 
the error code 1.

This function will not change the default drive, to do this you must use 
function 44.


* Function 48: Obtain the RAM disk size (DOS 2)

Input:	 -
Output:  P(0) = RAM disk size in 16K segments

This function is only available under DOS 2. Under DOS 1 will always return 
the error code 1.

To obtain the RAM disk size in K just do P(0)*16. A size of zero means that 
the RAM disk dones not exist.


* Function 49: Create the RAM disk (DOS 2)

Input:	 P(0) = Size required in 16K segments
Output:  P(0) = Size of the RAM disk created in 16K segments

This function is only available under DOS 2. Under DOS 1 will always return 
the error code 1.

Since by dafualt NestorBASIC allocates all the available free RAM segments 
when it is installed, before this function is called function 80 should be 
used to reduce the number of segmens allocated by NestorBASIC; otherwise, no 
free segments for creating the RAM disk will be available (unless the 
computer has more than 4M RAM).

If there are not P(0) free segments but it is possible to create a smaller 
RAM disk, the function will do it and will not return error; P(0) will return 
the size of the RAM disk created. But if there are no available segments at 
all and the RAM disk has not been created, the function will return the 
appropriate error code.


* Function 50: Obtain the attributes byte for a file (DOS 2)

Input:	 P(0) = File number, or
	 P(0) = 255 and F$(0) = File name
Output:  P(1) = Attributes byte:
		R + 2*H + 4*S + 8*V + 16*D + 32*A
		R = 1 -> Read only
		H = 1 -> Hidden
		S = 1 -> System
		V = 1 -> Volume label
		D = 1 -> Directory
		A = 1 -> Archive

This function is only available under DOS 2. Under DOS 1 will always return 
the error code 1.

If P(0)=255, the attributes byte for the file with the name specified in 
F$(0) will be obtained (F$(0) can contain a drive letter and a pathname); 
otherwise, the attributes byte for the file previously opened and with the 
number P(0) assigned will be obtained.


* Function 51: Set the attributes byte for a file (DOS 2)

Input:	 P(0) = File number, or
	 P(0) = 255 and F$(0) = File name
	 P(1) = New attributes byte:
		R + 2*H + 4*S + 8*V + 16*D + 32*A
		R = 1 -> Read only
		H = 1 -> Hidden
		S = 1 -> System
		V = 1 -> Volume label
		D = 1 -> Directory
		A = 1 -> Archive
Output:  P(1) = New attributes byte actually set for the file

This function is only available under DOS 2. Under DOS 1 will always return 
the error code 1.

If P(0)=255, the attributes byte for the file with the name specified in 
F$(0) will be set (F$(0) can contain a drive letter and a pathname); 
elotherwise, the attributes byte for the file opened and with the P(0) number 
assigned will be set.

It is not possible to set the attributes byte of an opened file by specifying 
its filename in F$(0); if you try to do this, an error will be generated. If 
the file is open, you must specify its file number in P(0).

The only attributes than can be modified for a file are the system, hidden, 
read only and archive; and for a directory, only the hidden. If you try to 
change any other attribute, you will obtain an error. You can't change the 
attributes for the "." and ".." entries.


* Function 52: Parse pathname (DOS 2)

Input:	 F$(0) = Pathname to be parsed
	 P(10)<>0 if the pathname refers to a volume label
Output:  F$(1) = Last item of the pathname
	 P(8)  = Logical drive number (1=A:,...,8=H:)
	 P(9)  = Position in the pathname string of the last item
		 (0 if there is not last item)
	 The following results set to -1 if the specified condition mets,
	 otherwise set to 0:
	 P(0)	 The pathname contains characters other than the drive letter
	 P(1)	 A directory is specified in the pathname
	 P(2)	 A drive letter is specified in the pathname
	 P(3)	 A file name is specified in the pathname
	 P(4)	 A file extension is specified in the pathname
	 P(5)	 The last element is ambiguous
	 P(6)	 The last element is "." or ".."
	 P(7)	 The last element is ".."

This function is only available under DOS 2. Under DOS 1 will always return 
the error code 1.

This function just treats the input string returning the specified results. 
No disk accesses are done, and the default drive/directory are not modified.

If only a drive letter is specified, or if the last character of the string 
is the directory separator character "\", then there is no "last item" on the 
string; then P(9) will be 0 and F$(1) will be an empty string. Example: for 
F$(0) = "A:\DIR\FILES\ONEFI.LE", the last element, returned in F$(1), will be 
"ONEFI.LE", and P(9) will be 14.

If the pathname does not contain a drive letter, the current default drive 
will be returned in P(2). Therefore, P(2) will never be zero.

If P(10)<>0 is specified, P(1) and P(4) to P(7) will always be zero.


10.6. FUNCTIONS FOR GRAPHIC COMPRESSION AND DECOMPRESSION

* Function 53: Compression of graphic data

Input:	 P(0) = Source VRAM block
	 P(1) = Source start address (VRAM)
	 P(2) = First destination segment
	 P(3) = Destination start address (RAM)
	 P(4) = Size of the VRAM data to be compressed
	 P(5) = Increase P(1) if <>0
	 P(6) = Increase P(3) if <>0
Output:  P(7) = Size in RAM of the compressed data
	 P(8) = Number of used RAM segments
	 P(0):P(1) = P(0):P(1) + P(4) if P(5)<>0
	 P(2):P(3) = RAM address next to the last one used, if P(6)<>0

Compression is done through consecutive segments: after writting compressed 
data in the address &H3FFF of the segment S, the writting of the generated 
data continues on address &H0000 of the segment S+1. If this situation is 
done but the S+1 segment does not exists, an error 5 will be generated. This 
function does not supports VRAM segments, nor the segment 255.

If the last used RAM address is the &H3FFF of the segment S and P(6)<>0, then 
P(2) will be S+1 and P(3) will be 0 at the end. In such situation, if S was 
the last available RAM segment, P(2) will be zero at the end.


* Function 54: Decompression of graphic data

Input:	 P(0) = Destination VRAM block
	 P(1) = Destination start address (VRAM)
	 P(2) = First source segment
	 P(3) = Source start address (RAM)
	 P(5) = Increase P(1) if <>0
	 P(6) = Increase P(3) if <>0
Output:  P(7) = Size in VRAM of the decompressed image
	 P(8) = Number of used RAM segments
	 P(0):P(1) = P(0):P(1) + P(7) if P(5)<>0
	 P(2):P(3) = RAM address next to the last one used, if P(6)<>0

Decompression process is done through consecutive segments: after 
decompressing data stored in the address &H3FFF of segment S, the reading of 
the compressed data continues from the address &H0000 of segment S+1. If this 
situation is done but segment S+1 does not exist, or if invalid data is found 
in the compressed data, error 6 will be generated. This function does not 
support VRAM segments, nor the segment 255.

If the last used RAM address is the &H3FFF of the segment S and P(6)<>0, then 
P(2) will be S+1 and P(3) will be 0 at the end. In such situation, if S was 
the last available RAM segment, P(2) will be zero at the end.


9.6. FUNCTIONS FOR THE EXECUTION OF BASIC PROGRAMS

* Function 55: Execution of a BASIC program stored in a segment (S4)

Input:	 P(0) = Segment
	 P(1) = Start address
Output:  -

VERY IMPORTANT: For using this function you must change the BASIC programs 
begin address. See section 6 for more details.

This function executes the BASIC program stored in the specified segment. 
The program must be stored beginning in the P(1) specified address of the 
P(0) segment, with the following format:

+&H0000: Not used by NestorBASIC. You can use it, for example, for inserting 
	 an identification byte.
+&H0001: Last program address +1, in the range &H8000-&HBFFF; low byte.
+&H0002: Idem, high byte.
+&H0003: Here starts the program data.

All the exisiting numeric variables of the caller BASIC program will be 
transferred to the new program. You can use this function from inside a 
turbo-block, but in such case the only transferred variables will be the 
integer variables defined outside of the turbo-block and passed to it with 
CALL TURBO ON (variable, ..., array(), ...).

The string variables stored in the BASIC string area will also be 
transferred, but the strings defined directly in the BASIC text reside inside 
the own BASIC program data, and will be lost. For being sure that a string is 
stored inside the BASIC string area, do the following operation: C$=C$+"". Of 
course, the most practical way for managing it is to group all the string 
variables into a string array (for example F$), then this operation can be 
done with a loop.

This function will return the error code -1 if a non existing segment is 
specified, or if the segment 255 is specified, and error code -2 if the BASIC 
main RAM is not large enough to store the new program and the existing 
variables. This situation may arise if the new program is larger than the 
caller program, but if the lengths difference is not very big and the number 
of variables is reasonably small you should not reach this situation.


* Function 56: Activation of a BASIC program stored in a segment (S4)

Input:	 P(0) = Segment
	 P(1) = Begin address
Output:  -

VERY IMPORTANT: For using this function you must change the BASIC programs 
begin address. See section 6 for more details.

This function acts like function 55, with the following difference: once the 
new program is placed in RAM an the variables are placed after it, the new
program is not executed, and the BASIC interpreter returns to the direct 
mode. Except for this, the functionality is the same, as well as the error 
conditions and error codes.


* Function 57: Save a BASIC program with a special header (S4)

Input:	 P(0)  = Byte to be saved in the first header position
		 (not used by NestorBASIC)
	 F$(0) = Pathname + filename
Output:  P(1)  = -1 -> No error
	      <> -1 -> A disk error occurred, and the file remains open
		       with this number; look at the value returned by the
		       USR command for the error code, as usual.

VERY IMPORTANT: For using this function you must change the BASIC programs 
begin address. See section 6 for more details.

This function saves the active BASIC program in the specified file, with the 
appropriate header for being executed or activated with functions 55 or 56 
(see function 55 for details about this header).

The use of this function simplifies the conversion of BASIC normal programs 
to the appropriate format required by function 55; this conversion is then 
reduced to this:

load"prog.bas"                  'Load the BASIC program
F$(0)="prog.nba":?USR(57)       'Save the BASIC program with the header
				'(setting P(0) is optional)

Once saved in this way, loading and executing the program is easy:

1000 'Open prog.nba, read to segment S and close
1001 F$(0)="prog.nba":?USR(31):P(2)=S:P(3)=0:P(4)=&H4000:?USR(33):?USR(32)
...
10000 'Execution of the program (error treatment is optional)
10001 P(0)=S:P(1)=0:IF USR(55)=-1 THEN PRINT "ERROR: Non existing segment!"
      ELSE PRINT "ERROR: Out of memory!"
10002 END

Using function 56 instead of function 55 you can load programs saved with the 
header if you don't have a copy in normal BASIC format (LOADable).

Of course, you can also use the normal disk access functions to save the 
program, but in this case you must create the header manually:

POKE &H8000,P(0) 'Data not used by NestorBASIC
POKE &H8001,PEEK(&HF6C2)
POKE &H8002,PEEK(&HF6C3)
'Save from &H8000 to PEEK(&H8001)+256*PEEK(&H8002) to the file

The error codes returned by this function are the same as the ones returned 
by the disk access functions (see section 4). If a disk error caused the file 
to remain open, P(1) will contain the associated file number; otherwise, P(1) 
will be -1.


10.7. MISCELLAENOUS FUNCTIONS

* Function 58: Execution of a machine code routine placed on BIOS, SUB-BIOS,
               BASIC main RAM or system work area

Input:	 P(0) = 0 to execute a routine placed on BIOS,
                BASIC main RAM or system work area
	     <> 0 to execute a SUB-BIOS routine
	 P(1) = Begin address of the routine
	 P(2) to P(11) = Input registers for the routine:
			 P(2) = AF	 P(8) = AF'
			 P(3) = BC	 P(9) = BC'
			 P(4) = DE	 P(10)= DE'
			 P(5) = HL	 P(11)= HL'
			 P(6) = IX
			 P(7) = IY
Output:  P(2) to P(12) = Output registers of the routine,
			 with the same assignment as in the input,
			 plus the following ones:
			 P(12) = A
			 P(13) = Cy flag (-1 if set, 0 otherwise)
			 P(14) = Z flag (-1 if set, 0 otherwise)

With this function you can execute machine code routines placed on BIOS, 
SUB-BIOS, BASIC main RAM or system work area, having defined previously the 
registers input state using the array P; after the routine execution, the 
registers output contents will also be set in array P in the same way.

If P(0)=0 at input, this function will execute directly the machine code 
routine placed at the address specified in P(1), without doing any slot or 
segment switching. This means that this way you can execute BIOS routines (if 
the routine address is in the range 0-&H3FFF), routines loaded in BASIC RAM 
by user (for example with BLOAD), and routines placed in page 3 system work 
area (for example the extended BIOS hook, at address &HFFCA). Note however 
that when this function is executed, NestorBASIC segment will be switched on 
page 1. This implies that it is not possible to directly execute ruotines 
placed at the BASIC interpreter ROM. To execute such routines, use the BIOS 
routine CALBAS (&H0159), which accepts in IX the address of the BASIC 
interpreter routine to be called.

If P(0)<>0 at input, the SUB-BIOS routine whose address is specified in P(1) 
will be executed; in this case, an error code -1 will be returned if an 
address higher than &H3FFF is specified. To perform the SUB-BIOS call, the 
BIOS routine EXTROM is used, so the input contents of the IX register 
[variable P(6)] will be lost.

The value returned in P(12) will be the same as the value returned in the 
high byte of P(2). Likewise, the values returned in P(13) and P(14) will 
indicate the state of bits 0 and 6, respectively, of the low byte of P(2). 
Since normally one wants to retrieve the value returned in A register by 
itself or the output value of the flags Cy and Z by themselves, rather than 
the complete AF pair, using P(12) to P(14) will be more convenient than using 
P(2) when looking at the output registers. However, when establishing the 
input value for A and the flags you need to use P(2), you can't use P(12). 
You can calculate the value to set up in P(2) with the following formula:
P(2) = Cy + 2*N + 4*P/V + 16*H + 64*Z + 128*M + 256*A


* Function 59: User machine code routine execution
	       (machine code routine stored in a RAM segment)

Input:	 P(0) = Segment in which the routine is stored
	 P(1) = Start address of the routine
	 P(2) to P(11) = Input registers for the routine:
			 P(2) = AF	 P(8) = AF'
			 P(3) = BC	 P(9) = BC'
			 P(4) = DE	 P(10)= DE'
			 P(5) = HL	 P(11)= HL'
			 P(6) = IX
			 P(7) = IY
Output:  P(2) to P(12) = Output registers of the routine,
			 with the same assignment as in the input,
			 plus the following ones:
			 P(12) = A
			 P(13) = Cy flag (-1 if set, 0 otherwise)
			 P(14) = Z flag (-1 if set, 0 otherwise)

Using this function you can execute a machine code routine previously 
loaded in a RAM segment, having defined the registers input state using the 
array P; after the execution, the registers output contents will also be set 
in the array P in the same way.

The specified segment will be switched in page 2 for the execution of the 
routine, therefore the routine must have been assembled in the addresses 
range &H8000-&HBFFF. When the routine is executed, BIOS is connected and 
available in page 0, and NestorBASIC segment is available in page 1. This 
state must be restored by the routine itself before returning, if 
segment/slot switchings are done.

Some of the internal NestorBASIC routines and variables (for RAM and VRAM 
management, and for obtaining information about the interrupt process, 
amongst others) can be used by the user machine code routines. In appendix 2 
you can find the list and detailed description of these routines and 
variables.

See also the function 58 description for considerations about the output 
values of P(12) to P(14).

This function does not support VRAM segments nor the segment 255, and will 
return the error -1 if a non existing segment is specified in P(0).


* Function 60: Print a string in graphic mode

Input:	 F$(0) = String
Output:  -

This function works only in SCREEN 5 to 11 modes, and is equivalent to the 
PRINT#1,F$(0) command, having executed previously OPEN"GRP:"AS#1. The 
difference is that this function is TurboBASIC compatible. If executed in 
other graphic modes this function will do nothing, but will never return an 
error.

The maximum length of the string is 80 characters; if F$(0) is larger, only 
the first 80 characters will be printed. The string can't contain any 
character 0, because this code is interpreted as the end of the string.


* Function 61: Store a string in a segment

Input:	 F$(0) = String
	 P(0)  = Segment
	 P(1)  = Begin address
	 P(2)  = Increase P(1) if <>0
Output:  P(1)  = P(1) + LEN(F$(0)) + 1 if P(2)<>0

This function copies the string F$(0) to the specified address of the 
specified segment. The string is stored with a character 0 at the end, so 
LEN(F$(0))+1 bytes will be occuped.

The maximum length of the string is 80 characters; if F$(0) is largest, only 
the first 80 characters will be copied. The string can't contain any 
character 0, because this code is interpreted as the end of the string.

This function will return the error -1 if a non exisiting segment is 
specified in P(0).


* Function 62: Restore a string stored in a segment

Input:	 P(0)  = Segment
	 P(1)  = Begin address
	 P(2)  = Increase P(1) if <>0
Output:  F$(1) = String
	 P(1)  = P(1) + LEN(F$(1)) + 1 if P(2)<>0

This function sets in F$(1) the string stored from the specified address of 
the specified segment. The string is considered finished when a 0 character 
is found, or when 80 characters have been copied to F$(1).

If this function is executed from normal BASIC, the string can't contain the 
character 255, because if found, this character will be converted to the 
character 34 (quotation marks); this is due to the strings assignation method 
of BASIC, that requires a special treatment for the quotation marks. This 
does not happen when using TurboBASIC.

This function will return the error -1 if a non exisiting segment is 
specified in P(0).


* Function 63: Initialization of the SCREEN 0 blink mode

Input:	 P(0) = Foreground color of the blinking text
	 P(1) = Background color of the blinking text
	 P(2) = Time ON (0 to 15)
	 P(3) = Time OFF (0 to 15)
		IF P(2) and P(3) are both 0, this function
		will only clear the blink zone in VRAM
Output:  -

This function will initialize the colors and times for the SCREEN 0 blink 
mode, and will clear the VRAM blink zone. If P(2) and P(3) are both zero, 
only this last action will be done.

This function can only be used in SCREEN 0 mode with at least 41 columns; 
otherwise, nothing will be done, and the error -1 will be returned.

Actions done by this function can alse be done separately from BASIC, in the 
following way:

- Colors setting:

VDP(13) = Foreground color+ 16*Background color

- Times setting:

VDP(14) = Time ON + 16*Time OFF

- Clear VRAM:

Fill with zeros the 256 bytes VRAM zone beginning at &H0A00

System variables FORCLR (&HF3E9) and BAKCLR (&HF3EA) contain respectively the 
current foreground color and background color previously set with the COLOR 
statement. Thus, for obtain an inverse video effect just do:

P(0)=PEEK(&HF3EA):P(1)=PEEK(&HF3E9):P(2)=15:P(3)=0:?USR(63)

or

VDP(13)=PEEK(&HF3EA)+16*PEEK(&HF3E9):VDP(14)=&HF0


* Function 64: Make or erase a blinking characters block

Input:	 P(0) = 0 to erase block
	     <> 0 to create block
	 P(1) = Begin X coordinate (column) (0 to 79)
	 P(2) = Begin Y coordinate (line) (0 to 27)
	 P(3) = X length (columns)
	 P(4) = Y length (lines)
	 P(5) = Increase P(1) if <>0
	 P(6) = Increase P(2) if <>0
Output:  P(1) = P(1) + P(3) if P(5)<>0
	 P(2) = P(2) + P(4) if P(6)<>0

This function makes or erases a blinking characters block with the specified 
dimensions, in the specified coordinates. It is recommended to execute 
function 63 before use this function.

This function can only be used in SCREEN 0 mode with at least 41 columns; 
otherwise nothing will be done, but no error will be returned. If P(1)>79 
and/or P(2)>27, an error -1 will be returned.

This function does not check if the block surpasses the screen limits. If 
the block surpasses column 79, it will continue at the column 0 of the 
next line. But if a part of the block surpasses line 27, this part will 
not be shown.


* Function 65: Obtain information about interrupts

Input:	 -
Output:  P(0) = -1 if any interrupt process is active
	          (user defined interrupt, PSG sound effect or music replay)
	 P(1) = -1 if an user defined interrupt is active
	 P(2) = User defined interrupt segment
	 P(3) = User defined interrupt begin address
	 P(4) = -1 if a PSG sound effect is being replayed
	 P(5) = -1 if a music is being replayed

P(2) and P(3) will return the user interrupt definition, even if it is 
stopped. If no user interrupt has never been defined, both results will be 
zero.

To obtain more information about the active sound effect use function 67. 
For the music, use function 72.


* Function 66: Define or stop an user defined interrupt routine

Input:	 P(0) =  0 to stop the current user interrupt
		 1 to define and activate an user interrupt
		-1 to reverse the current status of the user interrupt
		   (actived <--> stopped)
	 P(1) = User interrupt segment (ignored if P(0)<>1)
	 P(2) = User interrupt begin address (ignored if P(0)<>1)
Output:  -

This function defines or stops an user defined interrupt routine, that is, a 
machine code routine that will be executed in each timer interrupt, 50 or 60 
times per second. The specified segment will be switched in page 2 for the 
execution of the routine, therefore the routine must have been assembled in 
the addresses range &H8000-&HBFFF.

If P(0)=1, the interrupt is defined by P(1) and P(2), and is activated (from 
this moment, it is executed to 50 or 60 Hz). If P(0)=0, the interrupt is 
stopped (it is no longer executed), but its definition is not changed. If 
P(0)=-1, the current status is reversed (actived to stopped and vice-versa), 
and its definition is not changed.

Interrupt segment is switched in page 2 for execution, so the code must be 
assembled in the address range &H8000-&HBFFF. BIOS is switched and available 
in page 0, and NestorBASIC segment is available in page 1. This state must be 
restored by the routine itself before returning, if segment/slot switchings 
are done. Also, the interrupts will be disabled and must be in this state 
during the routine execution. No register preservations are needed, because 
NestorBASIC handles this.

Some of the internal NestorBASIC routines and variables (for RAM and VRAM 
management, and for obtaining information about the interrupt process, 
amongst others) can be used by the user interrupt routines. In appendix 2 you 
will found the list and detailed description of these routines and variables.

You can't define an user interrupt routine in a VRAM segment, nor in the 
segment 255. If you specify a non existing or invalid segment in P(1) the 
function will return an error -1. If you specify a parameter other than 0, 1 
or -1 in P(0), an error 7 will be returned.


10.8. PSG SOUND EFFECTS

* Function 67: Obtain information about the PSG sound effects

Input:	 P(0) = New maximum volume (0 to 15, -1 to leave it unchanged)
Output:  P(1) = -1 if a sound effect is being replayed
	 P(2) = Number of the SFX being replayed, or the last one replayed
	 P(3) = Priority of the SFX being replayed, or the last one replayed
	 P(4) = Segment of the sound effects set
	 P(5) = Start address of the sound effects set
	 P(6) = Highest defined sound effect number
	 P(7) = Maximum volume

The results returned by this function will only be valid if the sound effects 
set has been initialized with function 68. The sound effects set must have 
been created with the editor SEE v3.xx, developped by Fuzzy Logic.

This function never returns error. If the value specified in P(0) is greater 
than 15, it will be interpreted as 15.


* Function 68: Initialization of a PSG sound effects set

Input:	 P(0) = Segment
	 P(1) = Address
Output:  -

This function initializes the sound effects set stored in the specified 
segment and address, leaving it ready for use with function 69.

The sound effects set must have been created with the editor SEE v3.xx, by 
Fuzzy Logic; if the set format is invalid, the function will return the error 
code 8.

You can't use a sound effects set stored in a VRAM segment, nor in the 
segment 255. If you specify a non existing segment in P(0), an error -1 will 
be generated.


* Function 69: Play a PSG sound effect

Input:	 P(0) = Effect number
	 P(1) = Priority (0: low, <>0: high)
Output:  -

This function begins the replay of the specified sound effect; the sound 
effects set must have been created with the editor SEE v3.xx, by Fuzzy Logic. 
If the sound effects set has not been initialized with function 68, the 
result is unpredictable.

P(1) handles the priority in the case of executing this function when
another sound effect is being replayed, in the following way:

- If the SFX being replayed and the new one have the same priority, the SFX 
being replayed is stopped, and the new one is played.
- If the SFX being replayed has low priority and the new one has high 
priority, same as above occurs.
- If the SFX being replayed has high priority and the new one has low
priority, the old SFX stills being replayed, and the function returns the 
error code 11.

If the sound effect specified in P(0) is not defined (the first track is left 
to "OFF" in the editor), the function will return the error code 9. If the 
effect does not exist (its number is higher than the maximum effect number), 
the function will return the error code 10.


* Function 70: Stop PSG sound effect replay

Input:	 -
Output:  -

This function stops the PSG sound effect being replayed, and silences the 
PSG. It never returns error.


10.9. FUNCTIONS FOR MOONBLASTER MUSIC REPLAY

* Function 71: Load and initialization, or uninstall,
	       of the Moonblaster replayer (S4)

Input:	 P(0)  = Replayer to be loaded:
		 0: Moonblaster 1.4
		 1: Moonblaster Wave 1.05
		 3: Autodetect:
		    Load Moonblaster Wave replayer if MoonSound is present,
		    otherwise load Moonblaster 1.4 replayer.
                -1: Uninstall the loaded replayer
Output:  P(0)  = Replayer loaded (0, 1 or -1, as above).
Output:  P(1)  = -1 -> No error
	      <> -1 -> A disk error occurred, and NBASIC.BIN remains open
		       with this number; look at the value returned by the
		       USR command for the error code, as usual.

This function loads the specified Moonblaster replayer in segment 5, leaving 
it ready for use. Also, searches for all the existing sound chips in the 
system, and leaves all the found chips enabled (see function 73 for more 
details about the sound chips activation).

The replayer can only be installed if the segment 5 exists and belongs to the 
primary mapper; otherwise, the function will return the error -1. If a disk 
error occurs, the function will return the appropriate error code (see 
section 4). If NBASIC.BIN remains opened due to a disk error, its associated 
file number will be returned in P(1); otherwise, P(1) will be -1.

NBASIC.BIN file contains two versions of the Moonblaster Wave replayer: one 
is for MSX2/2+ and Turbo-R in Z80 mode, and the other is for Turbo-R in R800 
mode. If the computer is a Turbo-R, NestorBASIC decides the version to be 
loaded according to the processor switched when function 71 is called. Note 
that if a processor change is performed, this function must be called again 
in order to load the appropriate replayer: Z80 version does not work in R800 
mode, and R800 version makes the system slower in Z80 mode.

To uninstall the replayer, use this function with P(0)=-1 at input; you don't 
need to previously stop any music being replayed, since the function itsef 
will do this task. After uninstallation (which just consists on erasing the 
sting "NestorPlayer" placed at the start of segment 5), segment 5 becomes 
available again, just like any other segment. If you try to uninstall the 
replayer when no replayer is actually loaded, the function will do nothing, 
and no error will be returned.

You can load, uninstall, and load again the Moonblaster replayer as many 
times as necessary within a program's lifetime. If there is a replayer loaded 
and you want to load another one, it is convenient to first uninstall the 
loaded replayer.


* Function 72: Obtain information about the music being replayed

Input:	 -
Output:  P(0) = -1 if a music is being replayed or is paused
	 P(1) = -1 if a Moonblaster 1.4 music is being replayed or paused
	 P(2) = -1 if a Moonblaster Wave music is being replayed or paused
	 P(3) = 0
	 P(4) = -1 if the music is paused
	 P(5) = Segment of the music being replayed,
		or segment of the last replayed music
	 P(6) = Begin address of the music being replayed,
		or begin address of the last replayed music
	 P(7) = Current position
	 P(8) = Current step (0 to 15)
	 P(9) = -1 if a MSX-MUSIC was detected
	 P(10)= -1 if a MSX-AUDIO was detected
	 P(11)= -1 if a OPL4 was detected
	 P(12)= -1 if the replayer is initialized
	 P(13)= Replayer installed (only if P(12)=-1):
		0: Moonblaster 1.4
		1: Moonblaster Wave 1.05
	 F$(0)= Songname (empty string if no music is being replayed)
	 F$(1)= Samplekit or wavekit (empty string if no music is being
		replayed)

If no Moonblaster replayer is loaded, P(12) will be zero the other results 
will not be set (except for P(9) to P(11); the function will not return any 
error. Use function 71 to initialize the replayer.

If no music is being replayed, P(5) and P(6) will return the position and the 
step in which the last replayed music was stopped, and F$(0) and F$(1) will 
be empty strings. Otherwise, F$(0) will return the songname (always 40 
characters for Moonblaster 1.4 musics, 50 for Moonblaster Wave musics) and 
F$(1) will return the samplekit or wavekit that was loaded in Moonblaster 
when the music was saved, in capital letters and without extension ("NONE" if 
there was no samplekit loaded).

P(9) to P(11) return information about the detected sound chips, even when no 
replayer is loaded. To obtain information about the enabled sound chips, use 
function 73.


* Function 73: Activation and deactivation of the sound chips

Input:	 P(0) = 0 -> Request for information only
		1 -> Enable or disable chips according to P(1) to P(3)
		2 -> Enable all the found sound chips
	 P(1) = 0 -> Don't modify MSX-MUSIC status
		1 -> Disable MSX-MUSIC
		2 -> Enable MSX-MUSIC
	       -1 -> Reverse MSX-MUSIC status
	 P(2) = 0 -> Don't modify MSX-AUDIO status
		1 -> Disable MSX-AUDIO
		2 -> Enable MSX-AUDIO
	       -1 -> Reverse MSX-AUDIO status
	 P(3) = 0 -> Don't modify OPL4 status
		1 -> Disable OPL4
		2 -> Enable OPL4
	       -1 -> Reverse OPL4 status
Output:  P(4) = 0 -> MSX-MUSIC not found
		1 -> MSX-MUSIC found but disabled
		2 -> MSX-MUSIC enabled
	 P(5) = 0 -> MSX-AUDIO not found
		1 -> MSX-AUDIO found but disabled
		2 -> MSX-AUDIO enabled
	 P(6) = 0 -> OPL4 not found
		1 -> OPL4 found but disabled
		2 -> OPL4 enabled

This function allows to disable and enable MSX-MUSIC, MSX-AUDIO and OPL4, 
which in such state will not be used, even if they are found in the system. 
This feature can be useful, for example, for earing only the MSX-AUDIO part 
of a music in a computer with internal MSX-MUSIC.

If P(0)=0, the function will only return information about the enabled sound 
chips in P(4) to P(5), and will not change the current status of the chips. 
If P(0)=2, all the found chips will be enabled (this is the default state 
when the replayer is initialized). To obtain information about the found 
sound chips use function 72.

If P(0)=1, the different sound chips will be enabled or disabled according to 
the values passed in P(1) to P(3); attempts to enable chips that are not 
present will be ignored. If MSX-AUDIO and MSX-MUSIC are both disabled 
(Moonblaster 1.4 replayer) or if OPL4 is disabled (Moonblaster wave 
replayer), function 74 (start the playing of a music) will do nothing but 
will not return error.

The changes done with this function will have not effect until the currently 
being replayed music is stopped (function 75 or 77) and restarted (function 
74). If no music is being replayed when you use this function, just start the 
music and you will note the changes.

This function will return the error code 7 if any of the input parameters in 
invalid (but if P(0)<>1 you don't need to set P(1) to P(3)), and error code 
12 if the replayer is not installed.


* Function 74: Start playing a Moonblaster music

Input:	 P(0) = Segment in which the music is stored
	 P(1) = Music begin address
Output:  -

This function begins the replay of the specified Moonblaster music. If the 
specified segment does not exist, refers to VRAM or is the 255, the error 
code -1 will be returned. If the replayer has not been initialized, the error 
code 12 will be returned (use function 71 to initialize the music replayer). 
Moonblter Wave musics can be stored through consecutive segments; see section 
8.2 for more details.

In the case of Moonblaster 1.4 music, this function examines the first byte 
of the music in the specified address; if this byte is &HFF it means that the 
music was saved in EDIT format, and therefore can't be replayed; in such case 
the error code 13 will be returned. Otherwise, NestorBASIC assumes that in 
the specified address a Moonblaster music saved in USER format begins, and 
the replay starts without further checkings. If the specified RAM area does 
not contain a Moonblaster music, the result is unpredictable.

Moonblaster Wave rapleyer has not these restrictions: it can detect if data 
in the specified address is really a Moonblaster music, and if it is saved in 
USER mode. If not, error 13 is returned.

If MSX-MUSIC and MSX-AUDIO were both disabled (Moonblaster 1.4 music) or OPL4 
was disabled (Moonblaster Wave music) with function 73, this function will do 
nothing, but no error will be returned. If another music is already being 
replayed, an error code 14 will be returned.


* Function 75: Stop the music replay

Input:	 -
Output:  -

This function stops the replay of the being replayed music and silences the 
sound chips. If no music is being replayed or if no music replayer was 
initialized, the function will do nothing. It never returns error.


* Function 76: Pause and continue the music

Input:	 P(0) = 0 -> Pause music
		1 -> Continue music
	       -1 -> Reverse current status (replay <--> pause)
Output:  -

This function pauses or continues the replay of a Moonblaster music. If no 
music is being replayed or paused, or if the replayer was not initialized, 
the function will do nothing, but no error will be returned. If the specified 
parameter is invalid, an error code 7 will be returned.


* Function 77: Fade out the music

Input:	 P(0) = 0      -> Request for information only
		-1     -> Pause fade out
		1..254 -> Start/continue fade out with the specified delay
Output:  P(1) = -1 if a music is being faded
	 P(2) = Current fade delay (-1 if the fade is paused)

This function begins to fade out the music being replayed. The delay means 
the number of clock cycles (of 1/50 or 1/60 seconds each) between fade 
steps, so the smallest is the delay, the faster is the fade. Once the fade is 
completed (the music main volume decreases to zero), the music will be 
automatically stopped: you don't need to stop it by yourself with function 
75.

If P(0)=-1 the fade will be paused, that is, the music will remain being 
normally replayed with the reached volume. To continue the fade, just execute 
again this function, specifying a new delay in P(0).

If P(0)=0, this function will only set P(1) and P(2) with the specified 
information. If no music is being replayed, or if the replayer was not 
initialized, this function will do nothing. It never returns error.


* Function 78: Load a Music Module samplekit (S4)

Input:	 P(0) = File number
Output:  P(7) = Number of readed bytes

This function loads from the specified opened file a Music Module samplekit, 
which must be saved in the Moonblaster format: 56 header bytes, which will be 
copied into the appropriate zone of the replayer; and 32K of samples, which 
will be transferred to the Music Module sample RAM.

Data will be read from a previously opened file. This feature allows you to 
concatenate the samplekit with other useful data in a single data file: in 
such case, just move the file pointer to the appropriate point, and execute 
this function. However, in the most common case you will need to load a MBK 
file generated with Moonblaster. In such case, you can load the samplekit by 
just doing the following:

F$(0)="sampkit.mbk":?USR(31):?USR(78):?USR(32)

If a disk error occurs, the function will return the appropriate error code, 
and you can look for the number of bytes that have been read from the file in 
P(7). If this number is greatert than 16K, only the first 16K of the 
samplekit will have been transferred to the sample RAM. Otherwise, no data 
will have been transferred to the sample RAM.

If the replayer was not initialized or if no Music Module is found, this 
functon will do nothing, but will not return error. If the whole samplekit is 
successfully loaded, P(7) will not return 32824 but -32712, due to the BASIC 
integer variables range (-32768 to 32767).


* Function 79: Load a MoonSound wavekit (S4)

Input:	 P(0) = File number
Output:  P(6):P(7) = Number of readed bytes

This function loads from the specified open file a Moonsound wavekit, which 
must be saved in USER format (otherwise, an error 15 is returned). 

Data will be read from a previously opened file. This feature allows you to 
concatenate the wavekit with other useful data in a single data file: in 
such case, just move the file pointer to the appropriate point, and execute 
this function. However, in the most common case you will need to load a MWK 
file generated with Moonblaster. In such case, you can load the wavekit by 
just doing the following:

F$(0)="wavkit.mwk":?USR(31):?USR(79):?USR(32)

If a disk error occurs, the function will return the appropriate error code, 
and you can look for the number of bytes that have been readed from the file 
in P(6):P(7). In this case MoonSound sample RAM can have been modified, but 
work area will not have been updated, so a partial wavekit load can't be 
supposed.

If the Moonblaster Wave replayer was not initialized or if no MoonSound is 
found, this functon will do nothing, but will not return error. If the whole 
samplekit is successfully loaded, P(6):P(7) will contain the wavekit size 
(same as the file size if you just load a .MWK file).


10.10. FUNCTIONS FOR CONTROLLING THE USAGE OF SEGMENTS

* Function 80: Obtain and set the number of segments
	       allocated for NestorBASIC

Input:   P(0) = Number of segments to be allocated for NestorBASIC
		(0: Do not modify, only obtain the number of segments
		 curently allocated) 
		This number includes NestorBASIC, TurboBASIC
		and BASIC main RAM segments
Output:  P(0) = Number of segments allocated for NestorBASIC
		after the function execution
	 P(1) = Maximum number of segments that can be allocated
		for NestorBASIC

This function works both in DOS 1 and DOS 2, however it is intended for being 
used in DOS 2.

Under DOS 2, when NestorBASIC is installed it allocates for itself all the 
free RAM segments available in the system, up to 247. This implies that no 
free segments remain available for other resident programs that also perform 
segment allocation, like the DOS 2 RAM disk, NestorMan or InterNestor Suite. 
To solve this problem, use this function to let NestorBASIC know how many 
segments we really need; the other segments will be freed and therefore will 
become available for other programs. For example, if you will use a music 
replayer (which will be installed on segment 5) and you need only one extra 
segment for data, then you should execute this function with P(0)=7; the 
extra data segment will have number 6.

If a number of segments lower than 6 is specified in P(0), NestorBASIC will 
allocate 5 segments (see section 2), or 6 if a music replayer has been 
installed. If a number of segments higher than the total number of available 
segments is specified, then as much segments as possible will be allocated 
(up to 247), and P(0) will return the number of segments that have been 
actually allocated. Whatever finally happens, this function will never return 
error.

Under DOS 1, this function just modifies some NestorBASIC internal variables; 
the value returned in P(1) is fixed and it is computed at NestorBASIC 
installation time. Under DOS 2, contrarywise, actual segment allocations or 
freeings are performed using DOS 2 mapper support routines; in this case, the 
value returned in P(1) is re-computed on each execution of the function, and 
depends on how many segments have been allocated by other resident programs. 


10.11. FUNCTIONS FOR NESTORMAN AND INTERNESTOR SUITE/LITE INTERACTION

* Function 81: Obtain information about NestorMan
	       and InterNestor Suite availability

Input:   -
Output:  P(0) = 0 if NestorMan is not installed
                1 if NestorMan is installed
                3 if NestorMan and InterNestor Suite are installed
         P(1) = NestorMan segment of InterNestor Suite level 1 module
         P(2) = NestorMan segment of InterNestor Suite level 2 module
         P(3) = NestorMan segment of InterNestor Suite level 3 module
         P(4) = NestorMan segment of InterNestor Suite level 4 module
         P(5) = NestorMan segment number of NestorBASIC segment 4

The value returned in P(5) will be valid only if P(0) is 1 or 3 at output. 
This value is necessary if a data transfer between a NestorMan segment and a 
NestorBASIC segment will be performed using segment 4 (common to both 
programs) as an intermediate buffer, as described in section 9.2.

The values returned in P(1) to P(4) will be valid only if P(0) is 3 at 
output. It is not necessary to know the InterNestor Suite modules location in 
order to execute their routines (using function 85), but it is necessary in 
order to read and write the modules configuration constants and variables, as 
detailed in section 9.3.


* Function 82: Execute a NestorMan function

Input:	 P(0) = Function number
	 P(2) to P(11) = Input registers for the function:
			 P(2) = AF	 P(8) = AF'
			 P(3) = BC	 P(9) = BC'
			 P(4) = DE	 P(10)= DE'
			 P(5) = HL	 P(11)= HL'
			 P(6) = IX
			 P(7) = IY
Output:  P(2) to P(12) = Output registers of the function,
			 with the same assignment as in the input,
			 plus the following ones:
			 P(12) = A
			 P(13) = Cy flag (-1 if set, 0 otherwise)
			 P(14) = Z flag (-1 if set, 0 otherwise)

This function executes the NestorMan function specified in P(0) using then 
indirect calling method, that is, using the extended BIOS hook. It is 
therefore equivalent to the execution of function 58 having established 
previously P(1)=&HFFCA, P(3)=Function+256*B, and P(4)=&H2202.

An error code -1 will be returned by this function if NestorMan is not 
installed. Note however that it does not check if the specified function does 
really exist in NestorMan.

See also the function 58 description for considerations about the output 
values of P(12) to P(14).

Section 9 describes some procedures for exachanging data between NestorMan 
and NestorBASIC.


* Function 83: Data block transfer from a NestorMan segment
	       to a NestorBASIC segment

Input:	 P(0) = NestorMan source segment
	 P(1) = Source start address
	 P(2) = NestorBASIC destination segment
	 P(3) = Destination start address
	 P(4) = Data length
	 P(5)<> 0 -> Autoincrement of P(1)
	 P(6)<> 0 -> Autoincrement of P(3)
Output:  P(1) = P(1) + P(4) if P(5)<>0
	 P(3) = P(3) + P(4) if P(6)<>0

This function is identical to function 10, except that the value passed on 
P(0) refers to a NestorMan segment. As in the case of function 10, P(3)+P(4) 
must be lower than &H4000, a VRAM segment or the segment 255 may be specified 
in P(2), and an error -1 is returned if any of the specified segments does 
not exist.

This function has one limitation: it is not possible to use it specifying 
segment 1 as the NestorBASIC destination segment. However, this will normally 
not be a problem, because segment 1 contains the TurboBASIC compiler, and 
usually one does not want to modify its contents. If anyway a transfer to 
segment 1 is needed, you must first copy the data to any other segment as an 
itermediate step, for example segment 4.


* Function 84: Data block transfer from a NestorBASIC segment
	       to a NestorMan segment

Input:	 P(0) = NestorBASIC source segment
	 P(1) = Source start address
	 P(2) = NestorMan destination segment
	 P(3) = Destination start address
	 P(4) = Data length
	 P(5)<> 0 -> Autoincrement of P(1)
	 P(6)<> 0 -> Autoincrement of P(3)
Output:  P(1) = P(1) + P(4) if P(5)<>0
	 P(3) = P(3) + P(4) if P(6)<>0

This function is identical to function 10, except that the value passed on 
P(2) refers to a NestorMan segment. As in the case of function 10, P(3)+P(4) 
must be lower than &H4000, a VRAM segment or the segment 255 may be specified 
in P(0), and an error -1 is returned if any of the specified segments does 
not exist.

This function has one limitation: it is not possible to use it specifying 
segment 1 as the NestorBASIC source segment. However, this will normally not 
be a problem, because segment 1 contains the TurboBASIC compiler, and usually 
one does not want to read its contents. If anyway a transfer from segment 1 
is needed, you must first copy the data to any other segment as an 
itermediate step, for example segment 4.


* Function 85: InterNestor Suite routine execution

Input:	 P(0) = Module number, 1 to 4
	 P(1) = Routine address
	 P(2) to P(11) = Input registers for the routine:
			 P(2) = AF	 P(8) = AF'
			 P(3) = BC	 P(9) = BC'
			 P(4) = DE	 P(10)= DE'
			 P(5) = HL	 P(11)= HL'
			 P(6) = IX
			 P(7) = IY
Output:  P(2) to P(12) = Output registers of the routine,
			 with the same assignment as in the input,
			 plus the following ones:
			 P(12) = A
			 P(13) = Cy flag (-1 if set, 0 otherwise)
			 P(14) = Z flag (-1 if set, 0 otherwise)

Using this function it is possible to execute any routine of any of the 
InterNestor Suite modules. To read or write the modules configuration 
constants and variables it is necessary to first obtain the NestorMan segment 
numbers of the modules using function 81, and then use any of the techniques 
described in section 9.2 for exchanging data between NetorBASIC and 
NestorMan.

This function will return an error -1 if InterNestor Suite is not installed, 
or if an invalid module number is passed on P(0).

See also the function 58 description for considerations about the output 
values of P(12) to P(14).

Section 9.3 mentions some considerations about the ensemble use of 
NestorBASIC and InterNestor Suite.


* Function 86: InterNestor Lite routine execution

Input:	 P(1) = Routine address
	 P(2) to P(11) = Input registers for the routine:
			 P(2) = AF	 P(8) = AF'
			 P(3) = BC	 P(9) = BC'
			 P(4) = DE	 P(10)= DE'
			 P(5) = HL	 P(11)= HL'
			 P(6) = IX
			 P(7) = IY
Output:  P(2) to P(12) = Output registers of the routine,
			 with the same assignment as in the input,
			 plus the following ones:
			 P(12) = A
			 P(13) = Cy flag (-1 if set, 0 otherwise)
			 P(14) = Z flag (-1 if set, 0 otherwise)

Using this function it is possible to execute any routine of InterNestor 
Lite. P(1) must contain the address of any of the InterNestor Lite routines 
listed in its programmer's manual, otherwise the results of executing this 
function are unpredictable.

This function will return an error -1 if InterNestor Lite is not installed. 
To know in advance whether InterNestor Lite is installed or not, use the 
following code, which performs the detection method described in section 9.4:

P(0)=0: P(1)=&HFFCA: P(2)=0: P(4)=&H2203: E=USR(58):
IF P(12)=0 THEN ... (not installed)

In section 9.4 there is a comment about the use of the InterNestor Lite 
routines that perform data exchange with TPA from NestorBASIC. See also the 
function 58 description for considerations about the output values of P(12) 
to P(14).

The following sample program shows the installed InterNestor Lite version 
number.

10 BLOAD"nbasic.bin",R
20 IF P(0)<5 AND P(0)<>3 THEN PRINT "Error "+P(0):END
30 '* Check that INL is installed
40 P(0)=0: P(1)=&HFFCA: P(2)=0: P(4)=&H2203: E=USR(58): IF P(12)=0 THEN
   PRINT "InterNestor Lite is not installed.":GOTO 100
50 '* The VERS_PAUSE routine(&H402A) returns the INL version in C.D.E
      and the implementation number in B, it must be called with A=0
60 P(1)=&H402A:P(2)=0:E=USR(86)
70 X=P(3):GOSUB 1000:RB=X '* B register
80 X=P(4):GOSUB 1000:RD=X '* D register
90 PRINT "InterNestor Lite version " ; P(3) AND &HFF ; "."
   ; RD ; "." ; P(4) AND &HFF ; ", implementation "
   ; RB ; " is installed."
100 '* Uninstalls NestorBASIC and finishes
110 P(0)=1:E=USR(0):END
1000 '* This subroutine extracts the high byte of X
1010 X=((X AND &HFF00)/256) AND &HFF
1020 RETURN

The program TCPCON-L.BAS, supplied with NestorBASIC, is a more complex 
example that illustrates the ensemble use of NestorBASIC and InterNestor 
Lite.


APPENDIX 1 - NESTORBASIC FUNCTIONS LIST

In this appendix, all the NestorBASIC functions are listed sorted by number. 
Functions that use segment 4 have a "(S4)" mark after their name. These 
functions are: 0, 26-28, 30, 33-41, 55-57, 71, 78, and 79.

--- General functions

* Function 0: NestorBASIC uninstallation (S4)
* Function 1: General information about NestorBASIC and about a segment

--- RAM access functions

* Function 2: Read a byte from a segment
* Function 3: Read a byte from a segment with address autoincrement
* Function 4: Read an integer (2 bytes) from a segment
* Function 5: Read an integr (2 bytes) from a segment
	      with address autoincrement
* Function 6: Write a byte to a segment
* Function 7: Write a byte to a segment with address autoincrement
* Function 8: Write an integer (2 bytes) to a segment
* Function 9: Write an integer (2 bytes) to a segment
	      with address autoincrement
* Function 10: Data block transfer between segments
* Function 11: Fill a RAM zone with a byte
* Function 12: Fill a RAM zone with a byte with address autoincrement

--- VRAM access functions

* Function 13: Read a byte from VRAM
* Function 14: Read a byte from VRAM with address autoincrement
* Function 15: Read an integer (2 bytes) from VRAM
* Function 16: Read an integer (2 bytes) from VRAM
	       with address autoincrement
* Function 17: Write a byte to VRAM
* Function 18: Write a byte to VRAM with address autoincrement
* Function 19: Write an integer (2 bytes) to VRAM
* Function 20: Write an integer (2 bytes) to VRAM
	       with address autoincrement
* Function 21: Data block transfer from VRAM to RAM
* Function 22: Data block transfer from RAM to VRAM
* Function 23: Data block tranfer between VRAM
* Function 24: Fill a VRAM zone with a byte
* Function 25: Fill a VRAM zone with a byte with address autoincrement

--- Disk access functions

* Function 26: Search for a file (S4)
* Function 27: Rename a file (S4)
* Function 28: Delete a file (S4)
* Function 29: Move a file (DOS 2)
* Function 30: Create a file or directory (S4)
* Function 31: Open a file
* Function 32: Close a file
* Function 33: Read from a file (S4)
* Function 34: Read from a file to VRAM (S4)
* Function 35: Read disk sectors (S4)
* Function 36: Read disk sectors to VRAM (S4)
* Function 37: Write to a file (S4)
* Function 38: Write to a file from VRAM (S4)
* Function 39: Write to disk sectors (S4)
* Function 40: Write to disk sectors from VRAM (S4)
* Function 41: Fill a file with one byte (S4)
* Function 42: Move a file pointer
* Function 43: Obtain the default drive and the available drives vector
* Function 44: Set the default drive
* Function 45: Obtain disk space information
* Function 46: Obtain the default directory (DOS 2)
* Function 47: Set the default directory (DOS 2)
* Function 48: Obtain the RAM disk size (DOS 2)
* Function 49: Create the RAM disk (DOS 2)
* Function 50: Obtain the attributes byte for a file (DOS 2)
* Function 51: Set the attributes byte for a file (DOS 2)
* Function 52: Parse pathname (DOS 2)

--- Graphic copression functions

* Function 53: Compression of graphic data
* Function 54: Decompression of graphic data

--- BASIC programs execution

* Function 55: Execution of a BASIC program stored in a segment (S4)
* Function 56: Activation of a BASIC program stored in a segment (S4)
* Function 57: Save a BASIC program with a special header (S4)

--- Miscellaneous functions

* Function 58: Execution of a machine code routine placed on BIOS, SUB-BIOS,
               BASIC main RAM or system work area
* Function 59: User machine code routine execution
	       (machine code routine stored in a RAM segment)
* Function 60: Print a string in graphic mode
* Function 61: Store a string in a segment
* Function 62: Restore a string stored in a segment
* Function 63: Initialization of the SCREEN 0 blink mode
* Function 64: Make or erase a blinking characters block
* Function 65: Obtain information about interruptw
* Function 66: Define or stop an user defined interrupt routine

--- PSG sound effects replay

* Function 67: Obtain information about the PSG sound effects
* Function 68: Initialization of a PSG sound effects set
* Function 69: Play a PSG sound effect
* Function 70: Stop PSG sound effect replay

--- Moonblaster music replay

* Function 71: Load and initialization, or uninstall,
	       of the Moonblaster replayer (S4)
* Function 72: Obtain information about the music being replayed
* Function 73: Activation and deactivation of the sound chips
* Function 74: Start playing a Moonblaster music
* Function 75: Stop the music replay
* Function 76: Pause and continue the music
* Function 77: Fade out the music
* Function 78: Load a Music Module samplekit (S4)
* Function 79: Load a MoonSound wavekit (S4)

--- Segments usage control

* Function 80: Obtain and set the number of segments
	       allocated for NestorBASIC

--- Interaction with NestorMan and InterNestor Suite/Lite

* Function 81: Obtain information about NestorMan
	       and InterNestor Suite availability
* Function 82: Execute a NestorMan function
* Function 83: Data block transfer from a NestorMan segment
	       to a NestorBASIC segment
* Function 84: Data block transfer from a NestorBASIC segment
	       to a NestorMan segment
* Function 85: InterNestor Suite routine execution
* Function 86: InterNestor Lite routine execution


APPENDIX 2 - USER ACCESSIBLE NESTORBASIC ROUTINES AND VARIABLES

When an user machine code routine or an user interrupt routine is executed, 
NestorBASIC segment is SWITCHED in page 1. At the beginning of this segment 
there is a table to some internal NestorBASIC routines and variables, which 
can be useful for the user routine. In this section, the location of these 
routines and variables and its meanings are described.

None of these routines modify the interrupts state, except PUTSLOT0, which
disables interrupts before finishing.

WARNING: Logical segment 255 refers always to the memory switched to pages 2 
and 3 when the segment is referred to. While an user machine code routine or 
an user interrupt routine is being executed, page 2 DOES NOT contain the 
BASIC main RAM segment, but the segment of the routine itself. So, to 
actually convert the segment 255 to the appropriate BASIC segment, do the 
following:

	ld	hl,address
	call	CHKSLFF
	cp	3
	jr	z,OKFF
	ld	a,2
OKFF:	;

Note: variables and data areas mentioned in this section are read-only. 
Modifying them may cause unpredictable results.

The contents of the table is as follows:


&H4100: Identification string "NestorBASIC x.xx"


&H4110: TABSEGS

Pointer to the segments table. The format of this table is as follows:

-2: Maximum number of segments that can be allocated for NestorBASIC
    (always valid under DOS 1; under DOS 2 this value is valid
     immediately after NestorBASIC installation, but may vary later)
-1: Number of available RAM segments (same as P(0) returned by
    functions 1 and 80)
+0: Slot of the logical segment 0
+1: Physical segment of the logical segment 0
+2: Slot of the logical segment 1
+3: Physical segment of the logical segment 1
...
+492: Slot of the logical segment 246
+493: Physical segment of the logical segment 246


&H4112: INT_DATA

Contains information about the NestorBASIC active interrupts:

bit 0 = 1: User defined interrupt is active
bit 1 = 1: PSG sound effect is being replayed
bit 2 = 1: Moonblaster 1.4 music is being replayed
bit 3 = 1: Moonblaster Wave music is being replayed


&H4113: PUTSLOT0

Enables the specified slot in page 0, without using ENASLT. Returns with 
interrupts disabled.

Input:	   A = Slot to switch
Output:    -
Registers: AF


&H4116: CHKSLE

Checks if the specified logical segment exists. DOES NOT recognize VRAM 
segments as valid segments, nor the segment 255.

Input:	   A = Logical segment
Output:    Cy= 1 -> Logical segment exists
	   Cy= 0 -> Logical segment does not exist
Registers: F


&H4119: CHKSLFF

Checks if the specified logical segment is the 255. If so, the segment 
is converted to the appropriate segment number (current page 2 segment if 
HL<&HC000, segment 3 if HL>=&HC000)

Input:	   A  = Logical segment
	   HL = Address
Output:    A  = Segment converted if it was 255; otherwise, unchanged
Registers: F


&H411C: CHKSLV

Checks if the specified logical segment refers to VRAM. If so, the 
specified segment address is converted to the appropriate VRAM address.

Input:	   A  = Logical segment
	   HL = Address
Output:    If segment refers to VRAM:
	      A  = VRAM block
	      HL = VRAM address
	      Cy = 1
	   If segment does not refer to VRAM:
	      A, HL unchanged
	      Cy = 0
Registers: -


&H411F: VTOSL

Converts a VRAM address to the appropriate VRAM segment

Input:	   A  = VRAM block
	   HL = VRAM address
Output:    A  = Equivalent logical segment
	   HL = Equivalent RAM address
	   Cy = 1 -> A=1 on input, but only 64K VRAM are available
Registers: F


&H4122: GET_SF

Obtains the physical segment and the slot for a logical segment.

Input:	   A = Logical segment
Output:    A = Physical segment
	   B = Slot (255 -> Logical segment does not exist)
Registers: -


&H4125: GET_SLT

Obtains the slot connected to page 1 or page 2.

Input:	   A  = Page (1 or 2)
Output:    B  = Slot
Registers: F, C


&H4128: READ_SL

Reads a byte from a logical segment.

Input:	   A  = Logical segment
	   HL = Address (0-&H3FFF)
Output:    A  = Byte read
Registers: F, AF'


&H412B: WRITE_SL

Writes a byte into a logical segment.

Input:	   A  = Logical segment
	   E  = Byte to be written
	   HL = Address (0-&H3FFF)
Output:    -
Registers: F, AF'


&H412E: LDIRSS

Transfers a data block from a logical segment to another.
Recognizes the segment 255 and the VRAM segments.
Returns with BIOS switched in page 0.
DON'T checks if BC>&H4000.

Input:	    IXh = Source logical segment
	    IXl = Destination logical segment
	    HL	= Source begin address (0..&H3FFF)
	    DE	= Destination begin address (0..&H3FFF)
	    BC	= Block length (0..&H3FFF)
Output:     A	= 0 -> Data block successfully transferred
	    A  <> 0 -> One of the specified logical segments does not exist
Registers:  All


&H4131: CHKBV

Checks if a VRAM address exists.

Input:	   A  = VRAM block (0 o 1, 64K low VRAM or high VRAM block)
Output:    Cy = 1 -> The specified VRAM block does not exist
		     (A = 1 but computer has only 64K VRAM)
Registers: -


&H4134: SET_RD

Sets VDP for reading VRAM.

Input:	   HL = VRAM address, 16 low bits
	   CY = VRAM address, bit 17
Output:    -
Registers: AF, HL


&H4137: SET_WR

Sets VDP for writing VRAM.

Input:	   HL = VRAM address, 16 low bits
	   CY = VRAM address, bit 17
Output:    -
Registers: AF, HL


&H413A: LDIRVR

Transfers data block from VRAM to RAM.

Input:	   VRAM source begin address previously set with SET_RD
	   DE = RAM destination begin address
	   BC = Block length
Output:    DE = RAM address next to the data block end
Registers: AF


&H413D: LDIRRV

Transfers data block from RAM to VRAM.

Input:	   VRAM destination begin address previously set with SET_WR
	   HL = RAM source begin address
	   BC = Block length
Output:    HL = RAM address next to the data block end
Registers: AF


&H4140: LDIRVV

Transfers data block from VRAM to VRAM through a RAM buffer.

Input:	   HL = VRAM source address, 16 low bits
	   DE = VRAM destination address, 16 low bits
	   BC = Block length
	   A  = %000000 D S, bit 17 of Destination and Source
	   IX = RAM buffer with a size of at least BC bytes
Output:    -
Registers: AF, HL, DE


&H4143: FILLVR

Fills a VRAM zone with un byte.

Input:	   VRAM address previously set with SET_WR
	   BC = Zone length
	   A  = Byte
Output:    -
Registers: -


&H4146: BLK_CLS

Clears the VRAM zone for the SCREEN 0 blink mode.

Input:	   -
Output:    -
Registers: AF


&H4149: BLK_COL

Sets the colors for SCREEN 0 blink mode.

Input:	   A = foreground color + 16* background color
Output:    -
Registers: A


&H414C: BLK_TIM

Sets the times for the SCREEN 0 blink mode.

Input:	   A = time ON + 16* time OFF
Output:    -
Registers: A


&H414F: BLK_ON

Makes a blinking block.

Input:	   HL = XXYY
	   B  = X length
	   C  = Y length
Output:    L  = YY next to the last line
	   H	unchanged
Registers: AF


&H4152: BLK_OF

Erases a blinking block.

Input:	   HL = XXYY
	   B  = X length
	   C  = Y length
Output:    L  = YY next to the last line
	   H	unchanged
Registers: AF


&H4155: C_BLKAD

Calculates the VRAM address in the blink area for the specified coordinates.

Input:	   HL = XXYY
Output:    HL = VRAM address
Registers: AF


&H4158: C_STBT

Calculates the appropriate bit of the appropriate VRAM address
for the specified coordinates.

Input:	   A = X coordinate
Output:    A has the appropriate bit set to 1
Registers: F


&H415B: GINFOUS

Returns information about the user interrupt definition.

Input:	 -
Output:  A  = Segment
	 HL = Address


&H415E: GINFOSFX

Returns information about the PSG sound effects.

Input:	 A  = New maximum volume (-1 to leave it unchanged)
Output:  A  = SFX set segment
	 HL = SFX set begin address
	 B  = Number of the SFX being replayed, or the last one replayed
	 C  = Priority of the SFX being replayed, or the last one replayed
	 D  = Number of the highest existing sound effect
	 E  = Maximum volume


&H4161: GINFOMUS

Returns information about the music being replayed and about the replayer.

Input:	 -
Output:  Cy = 1 -> No replayer is initialised,
		   the other results are invalid.
	 Cy = 0 -> Any replayer is initialised.
		   The other results are valid
		   if a music is being replayed (see INT_DATA).
	 A  = Logical segment of the music being replayed
	 HL = Begin address of the music being replayed
	 B  = Found sound chips:
	      bit 0 = 1 -> MSX-MUSIC found
	      bit 1 = 1 -> MSX-AUDIO found
	      bit 2 = 2 -> OPL4 found
	 C  = Enabled sound chips:
	      bit 0 = 1 -> MSX-MUSIC enabled
	      bit 1 = 1 -> MSX-AUDIO enabled
	      bit 2 = 2 -> OPL4 enabled
	 D  = Position
	 E  = Step (0 to 15)
	 IXl= 255 if the music is paused


&H4164: REPTYPE

This is a data byte that contains the type of the music replayer currently 
loaded:

0 = Moonblaster 1.4 replayer
1 = Moonblaster Wave replayer

Note that before looking for this information, you must check that actually 
any replayer is loaded. Use function GINFOMUS (&H4161) for this.


&H4165: GETF01

Input:  -
Output: -

This routine copies the contents of the strings F$(0) and F$(1) to two 
NestorBASIC buffers placed on page 3; the addresses of these buffers can be 
obtained from variables F0BUFADD and F1BUFADD, mentioned forward.

Only the first 80 characters of the strings are copied. A 0 character is 
placed at the end of the strings.


&H4168: SETF0
&H416B: SETF1

Input:  -
Output: -

These routines establish the strings F$(0) and F$(1), respectively, with the 
contents of two NestorBASIC buffers placed on page 3; the addresses of these 
buffers can be obtained from variables F0BUFADD and F1BUFADD, mentioned 
forward.

Strings must be finished with a 0 character in the buffers, and its maximum 
length is 80 characters; if they are larger, only the first 80 characters 
will be established.


&H416E: F0BUFADD
&H4170: F1BUFADD

These variables store the addresses of the page 3 buffers that are used as 
destination by routine GETF01 and as source by routines SETF0 and SETF1, 
respectively. The length of these buffers is 80 bytes each one.


&H4172: SL_2

Logical segment switched on page 2 (that is, logical segment where the 
routine reading this variable resides).


&H4173: NMAN_SL4

NestorMan segment number of NestorBASIC segment 4.


&H4174: INS_SL1
&H4175: INS_SL2
&H4176: INS_SL3
&H4177: INS_SL4

NestorMan segment numbers of InterNestor Suite modules 1 to 4, respectively.


APPENDIX 3 - INTERRUPTS IN MSX TURBO-R

NestorBASIC works perfectly in all the MSX2/2+/Turbo-R computers, but you may 
have problems with the interrupt process if your computer is a Turbo-R and 
you are running in DOS 1 mode, especially if you have an external mapper. 
This is due to the process needed for the interrupt request handling: 
NestorBASIC must check which segment is connected in page 1 before making any 
segment switching. In DOS 1 mode, the only way to do this is the use of a IN 
A,(&HFD) instruction, which in the Turbo-R computers does not work exactly in 
the same way as in the MSX2/2+ computers.

Thus, if you will use user interrupts, sound effects or music replay in your 
program using NestorBASIC, it is recommended to do the following: check if 
the computer is a Turbo-R (if PEEK(&H2D)=3) running in DOS 1 mode (use 
function 1 to check this); in such case, show a message asking to reboot in 
DOS 2 mode.


APPENDIX 4 - USAGE CONDITIONS

NestorBASIC is freeware, so you can use and distribute it freely. But if you 
use NestorBASIC in your programs you should do the following:

- Somewhere in your program (when loading, in an "about" option, when showing 
the staff, etc) you must place a mention to the use of NestorBASIC, as well 
as the version number (use function 1 to obtain NestorBASIC version number).

- If the program is not for author's personal use (that is, if the program 
will be distributed, freely or not) you must give a copy of the program to 
me.

For any suggestion, question or comment about NestorBASIC, please write to me 
at <konamiman@konamiman.com>.

The usage of the sound effects created with the sound effects editor SEE has 
its own use conditions. If you will shell your program for more than 15 NLG 
you must pay a little amount of money to the authors, never more than 25 NLG. 
For more details or for comments about SEE, please contact Fuzzy Logic:

       R. v/d Meulen		A. v/d Wal
       Lijsterstraat 25 	Tormentil 15
       8917 CX Leeuwarden	8445 RR Heerenveen
       Holland. 		Holland.

Загрузка

Для загрузки нужно выполнить в MSX BASIC команду:

BLOAD"NBASIC.BIN",R

Также можно выполнить вызов из файла автозапуска:

AUTOEXEC.BAS
10 BLOAD"NBASIC.BIN",R:NEW

Ссылки

msx/nextor_basic/nextor_basic.txt · Последние изменения: 2021-05-15 14:03 — GreyWolf