Это статья написана на основе документации User's manual in english, version 1.11, оригинал
Автор: Nestor Soriano (Konami Man), Декабрь 2004

Nestor Soriano также является автором Nextor

Официальная страница NestorBASIC

Перевод документации выполнил: ATroubleshooter, 2021–2023
Перевод документации NestorBASIC version 1.11 на русский

Оформление и корректура: Алексей Сысоев aka GreyWolf.

NestorBASIC — это набор подпрограмм(функций, процедур) в машинном коде, интегрированных в один файл, предназначенных для использования в программах на Бейсике. NestorBASIC обеспечивает, без утраты совместимости с MSX X-BASIC, следующую функциональность:

• Полный доступ ко всей страничной оперативной памяти компьютера(всей памяти, в случае MSX-DOS, всей свободной памяти в случае MSX-DOS 2), вплоть до 4 Мб.
• Доступ ко всей видеопамяти(VRAM), с возможностью пересылки блоков данных как в пределах VRAM, так и между VRAM и RAM.
• Размещение программ MSX BASIC в страничной памяти, с возможностью выполнять переход из одной программы в другую с сохранением переменных.
• Доступ к файлам на диске и непосредственно к физическим секторам, с возможностью чтения/записи напрямую в/из страничной RAM и VRAM. Поиск файлов, работа с директориями.
• Сжатие и распаковка графики.
• Проигрывание Moonblaster-музыки. Подгрузка samplekit'ов.
• Воспроизведение звуковых эффектов на PSG(AY-3-8910).
• Вызов подпрограмм в машинном коде, находящихся в BIOS, Sub-BIOS, в основной области памяти MSX BASIC, рабочей области системы, или в сегменте страничного ОЗУ.
• Вызов функций NestorMan, процедур InterNestor Suite и InterNestor Lite.

Все имеющиеся функции доступны через один единственный USR и массив целочисленных параметров, следовательно они полностью совместимы с MSX X-BASIC.

Собственно, сам компилятор MSX X-BASIC содержится в файле NBASIC.BIN, и автоматически загружается при резидентной установке NestorBASIC.

NestorBASIC загружается в сегмент ОЗУ, не используемый MSX BASIC, так что нужен лишь небольшой объем основной памяти MSX BASIC (примерно 500 байт) для программы перехода. Остальная основная память MSX BASIC свободна для программы на Бейсике.

NestorBASIC работает на любой MSX2/2+/Turbo-R с как минимум 128 кБ страничной памяти. В случае с MSX-DOS 2 нужен хотя бы один свободный сегмент ОЗУ в первичном маппере (два, если собираетесь использовать проигрыватели музыки. См. раздел 8 для подробностей).

Этот архив содержит все исходные файлы для сборки.

Для сборки из исходного текста рекомендуется использовать среду разработки Compass, либо кросс-ассемблер SjAsm на ПК.

Для загрузки NestorBASIC, просто выполните в MSX BASIC команду:

BLOAD"NBASIC.BIN",R

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

AUTOEXEC.BAS

10 BLOAD"NBASIC.BIN",R:NEW

Ни предварительных, ни последующих команд CLEAR и DEFUSR не требуется. Если все прошло без ошибок, мы получаем следующее:

1. NestorBASIC и MSX X-BASIC загружены, каждый в свой сегмент ОЗУ, и готовы к работе.
2. Размер свободной основной памяти MSX BASIC уменьшился примерно на 500 байт, которые были заняты программой, осуществляющей переход в сегмент NestorBASIC.
3. Первый USR [USR0(параметр) или просто USR(параметр)] указывает на вышеупомянутую программу перехода — это hook для вызова функций NestorBASIC.
4. Создан целочисленный массив параметров P. Этот массив используется для передачи параметров в функции NestorBASIC и приёма из них результатов, за исключением кодов ошибок. Коды ошибок возвращаются командой USR (функции для работы с файлами и функции обработки строк требуют собственный строковый массив, который нужно объявлять отдельно. См. раздел 4 для подробностей). Первые пять элементов P инициализированы следующим образом:

Число доступных сегментов ОЗУ всегда будет как минимум 5. Меньшее значение в P(0) будет отражать код ошибки, возникшей при резидентной установке NestorBASIC:

После резидентной загрузки NestorBASIC можно резервировать память для других резидентных подпрограмм в обычном порядке, т. е. использовать команду CLEAR для установки начала зарезервированной области.

Тем не менее, в связи с тем, что NestorBASIC производит переключения слотов/сегментов в странице 2, и интерпретатор MSX BASIC располагает стек в области памяти ниже области строковых переменных и области, зарезервированной для пользователя, есть нижний предел для адреса, устанавливаемого командой CLEAR. А конкретно, нельзя зарезервировать память с адреса меньше, чем определяется данной формулой:

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

Также, помните, что команда CLEAR, как и загрузка/очистка/модификация программы на MSX BASIC стирает все переменные. В этом случае, массив P должен быть переопределён командой DEFINT P:DIM P(15), и это должно быть сделано вне блоков компиляции (далее — турбо-блоков). Также, должен быть переопределен массив F, если требуется (см. раздел 4 для подробностей о массиве F). Если нужно объявить массив F внутри турбо-блока, необходимо сделать это в первой строке турбо-блока, чтобы обеспечить работу функций NestorBASIC:

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

Также, помните, что нулевой USR всегда зарезервирован за NestorBASIC как служебный вызов. Вызовы с USR1 по USR9 не заняты.

Страничное ОЗУ компьютеров MSX организовано в сегменты по 16 кБ. Каждый слот ОЗУ содержит определённое число S сегментов (нумеруемых от 0 до S-1), доступных, когда они подключены в адресное пространство активного слота памяти, что контролируется через порты с &HFC по &HFF.

При загрузке NestorBASIC, все имеющиеся слоты сканируются на наличие ОЗУ (всей памяти в случае MSX-DOS, всей свободной памяти в случае MSX-DOS 2), и строится таблица сегментов. В этой таблице, все найденные сегменты регистрируются в пары слот-сегмент (под MSX-DOS 2, сегменты сначала выделяются). NestorBASIC идентифицирует каждую из этих пар по порядковому номеру в таблице. Этот номер называется номером логического сегмента, и позволяет пользователю оперировать всей доступной памятью в последовательном виде, не заботясь ни о номерах слотов, ни о номерах физических сегментов, в которых она находится. Например, представим MSX с 128 кБ внутренней RAM (8 сегментов) и маппер на 1024 кБ (64 сегмента) во внешнем слоте. Тогда, после инициализации NestorBASIC, в случае MSX-DOS, пользователю будет доступно 72 логических сегмента, под номерами от 0 до 71, и достаточно указать этот номер в соответствующих функциях NestorBASIC для их использования. Номера физических слотов и сегментов уже не потребуются.

Адресное пространство логического сегмента (далее — просто «сегмента») от &H0000 до &H3FFF. Если заданы более высокие адреса при вызове функций NestorBASIC, они будут преобразованы. То есть, адреса &H4000–&H7FFF, &H8000–&HBFFF и &HC000–&HFFFF эквивалентны &H0000–&H3FFF при доступе к сегментам ОЗУ через NestorBASIC.

Все сегменты доступны для чтения и записи, но есть важные ограничения по отношению к первым шести:

1. Сегмент 0 содержит собственно NestorBASIC, и лишь небольшая область ОЗУ остаётся доступной для пользователя в конце него. Используйте функцию 1 чтобы получить начальный адрес этой области (описание функции см. в разделе 10).
2. Сегмент 1 содержит компилятор MSX X-BASIC. Можно перезаписать этот сегмент только в том случае, если Вы не собираетесь использовать компилятор.
3. Сегмент 2 всегда подключён к 2 странице (адреса &H8000–&HBFFF), и содержит исполняемую программу на MSX BASIC и часть её переменных.
4. Сегмент 3 всегда подключён к странице 3 (адреса &HC000–&HFFFF), и содержит рабочую область системы и часть переменных программы на MSX BASIC. Будьте внимательны при записи сюда.
5. Сегмент 4 используется как служебный буфер некоторыми функциями NestorBASIC. Вы можете использовать этот сегмент для ваших данных, если Вы не обращаетесь к этим функциям NestorBASIC. См. раздел 10 или приложение 1 чтобы узнать, какие функции используют этот сегмент.
6. Сегмент 5, если он есть, изначально свободен, и не используется NestorBASIC.

Но если используются музыкальные плееры, при инициализации они занимают этот сегмент. См. раздел 8 для подробностей.

Все оставшиеся сегменты — в полном распоряжении программиста.

При использовании функций обмена блоками данных, нужно быть осторожным, чтобы сумма адреса назначения и длины пересылаемого блока не превысила адрес &H3FFF (например, не пытайтесь переслать &H2000 байт указывая адрес &H3000 как адрес назначения). В таком случае, сегмент 0 или сегмент 3 будут перезаписаны, и результат будет непредсказуем.

NestorBASIC позволяет использовать VRAM для ваших данных, путём эмуляции дополнительных сегментов ОЗУ. Если NestorBASIC показывает, что располагает S сегментами памяти, то номера сегментов с 0 по S-1 соотносятся со страничной RAM, тогда как номера сегментов с S по S+7 (или S+3, в зависимости от объёма видеопамяти, 128 кБ или 64 кБ) соотносятся с VRAM.

Вернёмся к компьютеру из предыдущего примера. После резидентной загрузки NestorBASIC или после вызова функции 1 (см. список функций) получаем P(0)=72. Это значит (предполагая, что у нас 128 кБ видеопамяти), что сегменты с 72 по 79 соотносятся с VRAM.

Соответствие между сегментами и адресами VRAM обратное: сегменты с меньшими номерами соответствуют наибольшим адресам VRAM. Это сделано так для того, чтобы помочь программисту при освобождении сегментов VRAM, соответствующих области отображения: это будет последний сегмент, при работе в текстовом режиме или при использовании лишь одной страницы в графическом режиме.

Вернёмся к предыдущему примеру: компьютеру с 72 сегментами RAM и 128 кБ VRAM. Если программа работает в текстовом режиме, используются только первые 2000 байт VRAM: это видео-ОЗУ соответствует последнему сегменту VRAM, под номером 79. В этом случае, программист может свободно использовать сегменты с 72 по 78, и диапазон доступных сегментов будет 0–78, без необходимости пропускать какой-либо сегмент внутри этой последовательности. Если программа работает в SCREEN 5 и использует только графическую страницу 0, диапазон сегментов будет с 0 по 77; в SCREEN 7 он будет с 0 по 75, и т.д.

Конечно, NestorBASIC также имеет функции для работы с VRAM напрямую, без эмуляции в ней сегментов RAM. Эти функции позволяют пересылать данные VRAM ↔ RAM и VRAM ↔ файл.

Внимание: сегменты VRAM могут использоваться — как и обычные сегменты RAM — для размещения данных и программ на MSX BASIC, а также для блоковых операций обмена с диском и сегментами RAM. Но учтите, что сегменты VRAM не могут быть использованы для:

• Сжатия/распаковки графики
• Исполнения программ в машинном коде
• Исполнения прерываний, определяемых пользователем.
• Воспроизведения звуковых эффектов на PSG(AY-3-8910)
• Воспроизведения музыки

Если Вы попытаетесь использовать сегменты VRAM для какой-то из этих целей, функция вернёт ошибку «несуществующий сегмент».

Логический сегмент 255 имеет особое предназначение. Он соотносится не с каким-то конкретным сегментом RAM или VRAM, а с основной памятью MSX BASIC, то есть — c ОЗУ используемым MSX BASIC по адресам &H8000–&HFFFF (к нему не применяются ни ограничения, ни преобразования адресов в диапазон &H0000—&H3FFF, как к другим сегментам). Это удобно использовать для обмена данными между каким–либо сегментом и переменной MSX BASIC или массивом переменных:

 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)

Резюмируя данный раздел, предоставим весь список имеющихся сегментов и их описание. S — это количество сегментов, возвращаемое в P(0) при резидентной загрузке NestorBASIC или при вызове функции USR0(1)

Все функции доступа к RAM и/или VRAM возвращают код ошибки -1 в следующих случаях:

• указан номер отсутствующего сегмента памяти;
• попытка доступа к адресу VRAM выше &HFFFF в компьютерах с 64 кБ VRAM;
• указан сегмент VRAM или 255-й сегмент в функциях, которые поддерживают только обычные сегменты RAM.

NestorBASIC включает функции для работы с файлами на диске и доступа к другим возможностям MSX-DOS, а именно:

• создание/удаление/переименование/поиск файлов;
• чтение/запись файлов в/из любого сегмента или области VRAM;
• чтение/запись секторов в/из любого сегмента или области VRAM;
• определение ёмкости диска, свободного пространства.

Функции, доступные только под MSX-DOS 2:

• перемещение файлов, чтение/установка атрибутов файла;
• получение/смена текущего рабочего диска/каталога (директории);
• определение ёмкости/создание RAM-диска.

Для передачи имён файлов и директорий, эти функции задействуют массив строковых переменных F$. Четыре из них — поиск, переименование и перемещение файлов, а также обработка пути файлов требуют двух строковых элементов, для чего нужно, чтобы был объявлен массив F$ из двух элементов DIM F$(1). Остальным функциям требуется только одна строка; поэтому, если не будет использоваться ни одна из вышеперечисленных четырех функций, можно объявить массив F$ только из одного элемента DIM F$(0). Особенно это рекомендуется в случае использования MSX X-BASIC, потому что внутри турбо-блоков каждая строка занимает 256 байт, независимо от её реальной длины.

Также, нужно иметь в виду, что массив F$ должен объявляться сразу же после начала турбо-блока, следующей строкой:

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

Пример.

41.bas

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

run
Inside
Outside

Запустить в WebMSX

С NestorBASIC это правило по-прежнему верно, но со строками F$() требуется дополнительная предосторожность. Если массив F$ использовался вне турбо-блока и будет затем объявляться внутри него — следующая строка должна быть помещена перед CALL TURBO ON:

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

Эта строка не нужна, если не требуется сохранять прежнее состояние F$, или если Вы не будете объявлять F$ внутри турбо–блока.

Ещё одно ограничение F$(0) и F$(1) — их длина ограничена 80 символами; остальные символы будут просто отброшены функциями NestorBASIC, которым эти строки поданы в качестве входных параметров. Все эти ограничения не действуют для индексов выше чем 1, если в массиве F$ больше элементов; то есть, Вы можете объявить F$ из более чем двух элементов, и использовать элементы F$(2), F$(3)… как обычно.

Помимо ошибки -1, описанной в разделе 3, функции работы с диском имеют собственные коды ошибок.

Следующие ошибки могут появиться только под MSX-DOS:

Следующие ошибки одинаковы под MSX-DOS и MSX-DOS 2, и имеют те же коды ошибок, что и их эквиваленты в MSX BASIC:

Специфичные для MSX-DOS 2, ошибки:

NestorBASIC включает функции для сжатия графических данных из VRAM в RAM, и распаковки из RAM в VRAM. Формат сжатия тот же самый, что используется в процедуре вывода логотипа Sunrise, он работает по–байтно по следующему принципу:

(Де)компрессия осуществляется в последовательные сегменты; то есть, после (де)компресии из/в адреса &H3FFF сегмента S, процесс продолжается с адреса &H0000 сегмента S+1.

Функции компрессии/декомпрессии графики могут возвращать следующие коды ошибок:

NestorBASIC включает функции, которые позволяют Вам помещать программы на Бейсике в любой сегмент RAM или VRAM, актуализировать или запускать их, не теряя переменные исходной программы (из которой произведен переход в новую).

ВНИМАНИЕ: Чтобы использовать данные функции, нужно изменить адрес начала Бейсик-программы в основной памяти MSX BASIC с &H8000 на &H8003; это действие должно быть выполнено лишь однократно, и обязательно ПЕРЕД загрузкой NestorBASIC. Это можно сделать двумя способами:

• В интерактивном режиме, напечатав следующие команды:

  POKE &HF676,4
  POKE &H8003,0
  NEW

• Из программы на Бейсике. Этот способ лучше, так как в этой же программе можно, следом, загрузить NestorBASIC. Первая строка программы должна быть такой:

  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

Когда Вы актуализируете или запускаете программу, размещенную в сегменте, NestorBASIC сохраняет все переменные и массивы в сегменте 4; затем, копируется программа из желаемого сегмента в основную память MSX BASIC, и все ранее сохраненные переменные помещаются после программы, после чего обновляются соответствующие указатели в рабочей области MSX BASIC. И, наконец, будет осуществлено выполнение программы с первой строки, либо переход в интерактивный режим — в зависимости от примененной функции (запуск или актуализация).

Для того, чтобы программу на Бейсике можно было держать в сегменте и, в последствии, актуализировать или запустить, она должна там храниться со специальным заголовком, содержащим информацию о её длине, которая требуется для конкатенации уже существующих переменных с новой программой. Есть функция NestorBASIC, которая позволяет сохранить в файл активную программу с таким заголовком. В дальнейшем, просто загрузите этот файл в какой-нибудь сегмент с помощью дисковой функции, и программа готова к использованию — её можно актуализировать или выполнить в любой момент.

Очевидно, что если исполняется команда или строка, следующая за USR-функцией, которая актуализирует или запускает другую программу на BASIC, то это означает, что мы находимся в состоянии ошибки. Возможна одна из двух ошибок:

В этой группе собраны функции, предназначенные для:

• Вызова подпрограмм в машинном коде, находящихся в BIOS, Sub-BIOS, в основной памяти Бейсик, рабочей области системы или в сегменте ОЗУ (так называемые «пользовательские подпрограммы»).
• Размещения строковых переменных в сегментах RAM и извлечения их оттуда.
• Вывода на экран строковых переменных в графическом режиме.
• Управления миганием (blink mode) в SCREEN 0
• Назначения пользовательских прерываний (программы в машинном коде, находящиеся в сегменте RAM, выполняемые каждое прерывание по таймеру 50/60 Гц).
• Воспроизведения звуковых эффектов на PSG(AY-3-8910), созданных в SEE версий 3.xx

Некоторые из этих функций требуют строковый массив F$ для передачи параметров и возврата результатов, в дополнение к целочисленному массиву P. Больше подробностей о массиве F$ см. в разделе 4.

Некоторые из внутренних процедур NestorBASIC могут вызываться из других машинных подпрограмм пользователя и использоваться прерыванием, определяемым пользователем. См. приложение 2 для детального описания использования этих процедур.

Редактор SEE (sound effects editor) для создания звуковых эффектов под PSG был разработан группой Fuzzy Logic, и использование звуковых эффектов, сделанных в этом редакторе, в коммерческих продуктах подразумевает отчисление небольшой суммы авторам. Больше деталей в приложении 4.

Плеер nplayer, оригинал

Примеры, оригинал

NestorBASIC включает музыкальные проигрыватели Moonblaster 1.4 и Moonblaster Wave для MoonSound версии 1.05

Эти плееры не загружаются автоматически вместе с NestorBASIC: вследствие своего большого размера, они не помещаются в сегмент ОЗУ NestorBASIC, и должны загружаться в отдельный сегмент. Поэтому, чтобы использовать плеер, его нужно загружать директивно. Одновременно может быть загружен лишь один плеер.

Функция 71 загружает и инициализирует желаемый плеер, оставляя его готовым к работе. Эта функция проверяет наличие 5-го сегмента и принадлежность его к первичному мапперу: если это так, то плеер загружается в этот сегмент, после чего сегмент становится не доступен для программы пользователя. Если сегмент 5 не существует, или подключён не к первичному мапперу, плеер не будет загружен, и функция выдаст ошибку.

Файл NBASIC.BIN содержит два варианта проигрывателя Moonblaster Wave: один для MSX2 / 2+ и Turbo-R в режиме Z80, а другой для Turbo-R в режиме R800. Если компьютер это Turbo-R, то NestorBASIC определяет, какой вариант загружать, в соответствии с тем, в каком режиме работает процессор в момент вызова функции 71. Заметьте, что если произведено переключение режима процессора, эту функцию нужно вызвать заново, чтобы загрузить соответствующий плеер: вариант для Z80 не работает в режиме R800, а вариант для R800 привносит ненужное замедление системы в режиме Z80.

После того, как плеер загружен, происходит поиск звуковых устройств, и все найденные помечаются как активные. Подробности о включении и отключении звуковых устройств см. в описании функции 73.

Как только плеер загружен, он может использоваться функциями NestorBASIC для:

• Начала проигрывания музыки, предварительно загруженной в сегмент RAM (сегменты VRAM не поддерживаются).
• Остановки воспроизведения музыки.
• Паузы/продолжения воспроизведения музыки.
• Постепенного затухания музыки, с выбором скорости затухания.
• Получения информации о воспроизводимой музыке (сегмент и начальный адрес, по которому она находится, название мелодии, набор сэмплов (samplekit) или набор PCM-инструментов (wavekit), текущая позиция и темп).
• Получения сведений о обнаруженных звуковых устройствах.
• Отключения звуковых устройств, чтобы они не задействовались, несмотря на то, что были обнаружены.
• Загрузки samplekit-а музыкальной композиции или wavekit-а для Moonsound из файла.

Во время проигрывания музыки, все функции NestorBASIC работают как обычно, включая проигрывание PSG эффектов и использование прерываний, определяемых пользователем. Если NestorBASIC выгрузить из памяти, то воспроизводимая музыка будет автоматически остановлена.

Плеер Moonblaster 1.4 помещается в 4,5 кБ, следовательно — адресное пространство с &H1200 по &H3FFF сегмента 5 остаётся свободно, и может использоваться, например, для хранения воспроизводимой музыки. Это не работает в случае с плеером Moonblaster Wave, который занимает 5 сегмент полностью.

Музыкальные композиции Moonblaster 1.4 должны помещаться в один сегмент, поэтому их размеры ограничены 16кБ. Мелодии Moonblaster Wave могут занимать несколько сегментов подряд, максимум 3: если при разборе воспроизводимых аудиоданных NestorBASIC доходит до адреса &H3FFF, процесс продолжается с адреса 0 следующего сегмента.

Чтобы загрузить муз. композицию Moonblaster Wave из файла, можно воспользоваться следующим примером:

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
...

Функции проигрывания музыки могут возвращать следующие коды ошибок:

Следующие ошибки могут произойти при выполнении функции запуска воспроизведения:

Функция загрузки wavekit для Moonsound, помимо ошибок работы с диском, может вернуть такую ошибку:

ВНИМАНИЕ: Плеер Moonblaster 1.4 не умеет различать, являются ли данные по конкретному адресу в действительности композицией Moonblaster 1.4, и лишь всецело полагается на первый байт для определения того, что это данные композиции, сохранённой в режиме EDIT. Плеер Moonblaster Wave не имеет этой проблемы.

Функция загрузки плеера выдаёт такие же коды ошибок, как и функции для работы с диском, а также код -1 — если сегмент 5 не существует или не принадлежит первичному мапперу.

NestorBASIC имеет специальные функции, которые позволяют взаимодействовать с NestorMan (резидентный динамический менеджер памяти для MSX-DOS 2), пакетом InterNestor Suite (стек TCP/IP для MSX-DOS 2) и InterNestor Lite (стек TCP/IP для MSX-DOS), если эти программы запущены. Таким образом, возможна разработка приложений на Бейсике, которые используют динамические блоки памяти и связанные списки, а также Internet–приложения. Чтобы узнать, запущен ли NestorMan и InterNestor Suite, можно воспользоваться функцией 81. Процедура проверки наличия загруженного InterNestor Lite детально описана в разделе 9.4.

ВНИМАНИЕ: NestorMan и InterNestor Suite / InterNestor Lite имеют собственную документацию, описывающую их функции и процедуры. Эти программы доступны здесь.

TCPCON, оригинал

NestorMan реализует систему логических сегментов, очень похожую на ту, что применяется в NestorBASIC. Оба пространства сегментов, NestorBASIC и NestorMan, полностью независимы друг от друга, за несколькими исключениями:

• Сегменты 0, 1, 2 и 3 являются общими для NestorBASIC и NestorMan (в документации к NestorMan эти сегменты называются «TPA segments»).
• Если, при резидентной загрузке NestorBASIC, NestorMan запущен — тогда логический сегмент 4 NestorBASIC выделяется не с использованием механизмов MSX-DOS 2, как остальные сегменты. Вместо этого, используется функция 7 NestorMan; таким образом, 4-му сегменту NestorBASIC присваивается, в свою очередь, номер сегмента NestorMan (этот номер можно узнать посредством 81-й функции NestorBASIC). Этот сегмент зарезервирован установкой атрибута «exclusive», и поэтому не используется NestorMan для выделения блоков памяти.

Если NestorMan и/или InterNestor Suite будут использоваться вместе с NestorBASIC, рекомендуется ограничить, с помощью функции 80, количество сегментов RAM, которые будут использоваться NestorBASIC. В противном случае, NestorBASIC зарезервирует для себя все доступные сегменты, и NestorMan не сможет задействовать резервы ОЗУ (необходимые для выделения блоков памяти, создания связанных списков и для отправки/получения данных в/из Интернета).

Для вызова функций NestorMan можно использовать 82-ю функцию; или можно использовать 58-ю функцию, указав хук EXTBIO (&HFFCA) в качестве адреса перехода, занеся &H2202 в регистровую пару DE, и номер функции в регистр C. См. описание функций в разделе 10.

При использовании NestorMan из NestorBASIC, обычно Вам придётся осуществлять передачу данных между сегментом NestorBASIC и сегментом NestorMan. Есть три способа сделать это:

1. Если сегмент источника или назначения — это сегмент TPA (номер сегмента от 0 до 3), достаточно использовать соответствующую функцию NestorMan для передачи блока данных (функция 14), поскольку NestorMan и так видит эти сегменты.
2. Можно использовать сегмент 4 NestorBASIC как промежуточный буфер для пересылки. Например, предположим пересылку из NestorBASIC в NestorMan. S1 это источник — сегмент NestorBASIC, S2 это назначение — сегмент NestorMan, и S3 это номер сегмента NestorMan, соответствующий 4 сегменту NestorBASIC. Тогда, сначала делается пересылка S1→4 с помощью функции NestorBASIC (функция 10), и затем делается пересылка S3→S2 с использованием функции NestorMan (функция 14).
3. Функции 83 и 84 NestorBASIC осуществляют блочное копирование данных из сегмента NestorMan в сегмент NestorBASIC и наоборот.

Чтобы прочитать или записать единственный байт данных из/в сегмент NestorMan, проще всего использовать соответствующие функции, которые предоставляет NestorMan (функции 12 и 13).

Помните, что некоторые функции NestorBASIC используют сегмент 4 как служебный буфер для временного размещения данных. См. раздел 10 или приложение 1, чтобы узнать эти функции.

Методика, при использовании InterNestor Suite из NestorBASIC, схожа с той, что применяется для работы с NestorMan. Единственно, нужно иметь в виду следующее:

• Функция 85 позволяет исполнять процедуры InterNestor Suite.
• Чтобы читать и записывать данные в сегменты InterNestor Suite (константы конфигурации и переменные), сначала нужно, используя функцию 81, выяснить номера сегментов модулей InterNestor Suite (каждый модуль занимает сегмент NestorMan), а далее, использовать методы обмена данными, описанные в предыдущем разделе.
• Процедуры InterNestor Suite для чтения/записи данных TCP или датаграмм UDP

допускают использование только сегментов TPA как источника/назначения данных или датаграмм. Для этой цели можно использовать последнюю часть сегмента NestorBASIC (сегмент 0) как временный буфер. Это свободное пространство всегда будет, как минимум, размером 600 байт, независимо от используемой версии NestorBASIC.
Этого достаточно для размещения стандартной датаграммы до 576 байт длинной (или для размещения блока данных TCP до 600 байт включительно).

Пример программы TCPCON-S.BAS (см. здесь), поставляемый с NestorBASIC, иллюстрирует использование NestorBASIC'а совместно с InterNestor Suite.

ВНИМАНИЕ: InterNestor Suite это устаревшее ПО и не рекомендуется к спользованию. Если Вам нужен рабочий стэк TCP/IP, посмотрите в сторону InterNestor Lite.

InterNestor Lite это гораздо более простая программа, чем InterNestor Suite, поэтому использовать её из NestorBASIC также проще. Предоставляется единственная функция (функция 86), которая позволяет выполнять несколько процедур из сегмента кода InterNestor Lite. Чтобы читать или писать в его сегмент данных, необходимо использовать процедуры GET_VAR, SET_VAR и COPY_DATA, которые находятся в сегменте кода.

Чтобы узнать, запущен InterNestor Lite или нет, используйте функцию 58 для вызова хука EXTBIO (адрес &HFFCA), передав A=0 и DE=&H2203. Если подпрограмма вернула A≠0, значит InterNestor Lite запущен. Больше подробностей в описании функции 86.

Многие из процедур InterNestor Lite используют адреса TPA как источник либо назначение для обмена данными с приложениями. Для таких процедур можно указать адреса выше &H8000, которые соответствуют основной памяти MSX BASIC и рабочей области системы; или адреса ниже &H4000, которые соответствуют сегменту NestorBASIC (сегмент 0).

В конце сегмента NestorBASIC есть свободная область, размер которой варьируется, в зависимости от версии NestorBASIC, но никогда не бывает меньше, чем 600 байт. Эта область может быть использована как временный буфер для обмена данными с InterNestor Lite. Другими словами, можно использовать диапазон от H3DA8 до &H3FFF в качестве TPA области — источника или приёмника для обмена данными между NestorBASIC и InterNestor Lite.

Пример программы TCPCON-L.BAS (см. здесь), поставляемый с NestorBASIC, иллюстрирует использование NestorBASIC совместно с InterNestor Suite.

Функция 86 (вызов процедуры InterNestor Lite) возвращает ошибку -1, если InterNestor Lite не обнаружен.

Функция 85 (вызов процедуры InterNestor Suite) возвращает ошибку -1, если InterNestor Suite не обнаружен, или если в P(0) указан недействительный номер модуля (действительны номера с 1 по 4).

Функции 83 и 84 (передача блоков данных между сегментом NestorMan и сегментом NestorBASIC) выдаёт ошибку -1, если задан несуществующий сегмент NestorMan или NestorBASIC. Эти функции могут использовать сегменты VRAM и 255-й сегмент.

Функции 80, 81 и 82 никогда не выдают ошибок.

Запуск программы на BASIC, находящейся в сегменте (S4)

ВАЖНО: Чтобы использовать эту функцию нужно изменить начальный адрес BASIC–программ. Детально об этом — в разделе 6.

Эта функция запускает программу на BASIC, расположенную в указанном сегменте. Программа должна находиться, начиная с адреса, указанного в P(1), в сегменте номер P(0), в следующем формате:

Все существующие числовые переменные вызывающей BASIC–программы будут переданы в вызываемую программу. Вы можете использовать данную функцию внутри турбо–блока, но в таком случае будут переданы только те целочисленные переменные, которые были объявлены вне турбо–блока и переданы в него посредством

CALL TURBO ON (переменная, ..., массив(), ...)

Строковые переменные, хранящиеся в строковой области переменных MSX BASIC будут также перенесены, но строки, определённые непосредственно в тексте программы, хранятся внутри самого текста программы на BASIC, и не будут переданы. Чтобы гарантированно удостовериться, что строка хранится в области строковых переменных BASIC, выполните следующую операцию:

C$=C$+""

Конечно, самым практичным способом было бы сосредоточить все строковые переменные в строковый массив (например, F$), и проделать эту операцию в простом цикле.

Эта функция выдаст ошибку -1, если указан несуществующий сегмент или 255-й. Ошибка -2 будет выдана, если основной памяти MSX BASIC не достаточно, чтобы вместить вызываемую программу и существующие переменные вызывающей программы. Такая ситуация может возникнуть, если новая (вызываемая) программа больше, чем вызывающая программа. Но если разница в размерах не очень велика, и переменных не слишком много, вы не должны оказаться в этой ситуации.

Актуализация программы на BASIC, находящейся в сегменте (S4)

ВАЖНО: Чтобы использовать эту функцию нужно изменить начальный адрес BASIC–программ. Детально об этом — в разделе 6.

Эта функция работает так же, как функция 55, с единственным отличием: после того, как новая программа помещена в основное ОЗУ MSX BASIC, и переменные размещены после неё — программа не выполняется, а интерпретатор BASIC возвращается в командный режим. За исключением этого — функционал тот же, как и причины и коды ошибок.

Сохранить программу на BASIC со специальным заголовком (S4)

ВАЖНО: Чтобы использовать эту функцию нужно изменить начальный адрес BASIC–программ. Детально об этом — в разделе 6.

Данная функция сохраняет активную BASIC–программу в указанный файл, с соответствующим заголовком, чтобы запускаться или активироваться с помощью функций 55 или 56 (см. функцию 55 для подробностей о формате заголовка).

Эта функция облегчает конвертацию обычных программ на BASIC в программы, исполняемые функцией 55; эта конвертация, таким образом, упрощается до следующего:

load"prog.bas"                  'Загрузка программы на BASIC
F$(0)="prog.nba":?USR(57)       'Сохранение программы на BASIC с заголовком
				'Задавать P(0) не обязательно

Сохранённая таким образом, программа загружается и запускается просто:

1000 'Открыть prog.nba, прочитать в сегмент S и закрыть
1001 F$(0)="prog.nba":?USR(31):P(2)=S:P(3)=0:P(4)=&H4000:?USR(33):?USR(32)
...
10000 'Запуск программы (обработка ошибок не обязательна)
10001 P(0)=S:P(1)=0:IF USR(55)=-1 THEN PRINT "ОШИБКА: Несуществующий сегмент!"
      ELSE PRINT "ОШИБКА: Не достаточно памяти!"
10002 END

Используя функцию 56 вместо функции 55, вы можете загружать программы, сохранённые с заголовком, для которых не имеется копий в обычном формате (LOADable).

Конечно же, вы можете также использовать обычные функции доступа к диску для сохранения программ, но тогда вам придётся создать заголовок вручную:

POKE &H8000,P(0) 'Байт не используемый NestorBASIC
POKE &H8001,PEEK(&HF6C2)
POKE &H8002,PEEK(&HF6C3)
'Сохранить начиная с &H8000 по PEEK(&H8001)+256*PEEK(&H8002) в файл

Коды ошибок, возвращаемые этой функцией — такие же, как у функций доступа к диску (см. раздел 4). Если дисковая ошибка повлекла за собой то, что файл остался открытым, тогда в P(1) будет содержаться соответствующий номер файла.

В противном случае, в P(1) будет -1.

Функции, которые составляют NestorBASIC, обозначаются числом, которое задаётся в качестве операнда команды USR. Таким образом, чтобы использовать функцию номер F, Вам нужно просто выполнить USR(F), имея в виду, что если F — это переменная, то она должна быть целочисленного типа. Параметры для функций должны быть установлены в массиве P (и, в некоторых случаях, в массиве F$) перед вызовом функции. После выполнения, результаты функции записываются в те же массивы, P и/или F.

Элементы массивов P и F$, которые не упоминаются явно в списках результатов каждой функции, возвращаются неизмененными, за исключением адресов в сегменте — они приводятся к диапазону &H0000-&H3FFF (кроме адресов сегмента 255, которые никогда не конвертируются). Если функция возвращает ошибку, выходные параметры будут недействительными (P и F$ остаются неизменны), если иное не сказано в описании функции.

«Блок VRAM» соотносится либо с 64кБ нижней VRAM (блок 0), либо с 64кБ верхней VRAM (блок 1). Адреса VRAM имеют диапазон &H0000-&HFFFF. Если адрес VRAM переходит из &HFFFF в &H0000 путём автоинкремента, блок VRAM также изменяется (c 0 на 1, или с 1 на 0).

Команда USR возвращает код ошибки, или 0, если ошибок не возникло. Коды ошибок, характерные для каждой группы функций, объяснены в соответствующих разделах.

Приложение 1 содержит полный список функций, который может быть полезен в качестве краткого справочника.

Выгрузка NestorBASIC'а из памяти (S4)

Эта функция выгружает NestorBASIC: высвобождает USR и, в случае MSX-DOS 2, освобождает все выделенные сегменты. Также, останавливаются все процессы, завязанные на прерывания (прерывания, определяемые пользователем, проигрывание звуковых эффектов PSG и музыки). Всегда следует выгружать NestorBASIC прежде чем вернуться в MSX-DOS; в противном случае, все зарезервированные сегменты ОЗУ не будут высвобождены, и, следовательно, не смогут быть использованы до перезагрузки компьютера.

Перед тем как выгрузить NestorBASIC, убедитесь, что не оставили открытых файлов. В противном случае, если в них осуществлялась какая-то запись, во внутренних буферах MSX-DOS могут оставаться несохраненные данные, которые будут потеряны. Вдобавок, в случае с MSX-DOS 2, не высвобождаются дескрипторы открытых файлов (file handles).

Если функции передано P(0)=0, то область основной памяти MSX BASIC, занятая обработчиком вызовов NestorBASIC (примерно 500 байт) не освобождается, что оставляет в силе схему распределения памяти, заданную командами CLEAR после загрузки NestorBASIC. Если функции передано P(0)≠0, схема распределения ОЗУ возвращается к параметрам, установленным до загрузки NestorBASIC. То есть, FRE(0) возвращает такое же значение, как до загрузки NestorBASIC. Учтите, что переменные в этом случае инициализируются.

Эта функция никогда не выдаёт ошибки.

Получение общей информации о NestorBASIC и конкретном логическом сегменте.

Под DOS 2, максимальное количество одновременно открытых файлов зависит от состояния внутренней памяти DOS, но не может превышать 63.

Эта функция возвращает ошибку -1 если заданный в P(0) логический сегмент не существует, является сегментом VRAM или 255-м сегментом. Как бы то ни было, даже в этом случае результаты в элементах с P(0) по P(10) будут действительными.

Число, возвращаемое в P(0) этой функцией будет таким же, как число, возвращаемое в P(0) функцией 80; а конкретно — это количество сегментов, зарезервированных для NestorBASIC. По-умолчанию (если функция 80 ещё не вызывалась после загрузки NestorBASIC), NestorBASIC резервирует для себя все свободные сегменты ОЗУ (до 247) во время своей загрузки.

Под MSX-DOS, F$(0) будет содержать только букву диска и двоеточие (например A:), а под MSX-DOS 2 — имя диска и каталога, заканчивающиеся «\» (например C:\UTILS\AMAZING\).

Адрес, возвращаемый в P(7) зависит от версии NestorBASIC, но всегда будет меньше или равен &H3DA8; то есть, как минимум 600 байт в конце сегмента NestorBASIC всегда будет доступно. Эта область может быть использована, например, как буфер для данных TCP или UDP-датаграмм при использовании InterNestor Suite с NestorBASIC.

В P(8) содержится номер последней вызванной функции, не считая саму 1 функцию. Так что если были последовательно вызваны, например, функции 64, 3, 10, 1, 1, 1, в конечном счёте Вы получите P(8)=10. Значение ноль будет означать, что ни одной функции, помимо 1-й, не выполнялось с момента загрузки NestorBASIC.

Прочесть байт из сегмента

Прочесть байт из сегмента с автоинкрементом адреса

Прочесть целое число (2 байта) из сегмента

Младший байт берётся из адреса P(1), а старший байт из адреса P(1)+1.

Прочесть целое число (2 байта) из сегмента с автоинкрементом адреса

Младший байт берётся из адреса P(1), а старший байт из адреса P(1)+1.

Записать байт в сегмент

Записать байт в сегмент с автоинкрементом адреса

Записать целое число (2 байта) в сегмент

Младший байт записывается в адрес P(1), а старший байт в адрес P(1)+1.

Записать целое число (2 байта) в сегмент с автоинкрементом адреса

Младший байт записывается в адрес P(1), а старший байт в адрес P(1)+1.

Блочная пересылка данных между сегментами

P(3)+P(4) должно быть меньше &H4000, иначе результат непредсказуем.

Заполнить область ОЗУ байтом

P(3)+P(4) должно быть меньше &H4000, иначе результат непредсказуем.

Заполнить область ОЗУ байтом с автоинкрементом адреса.

P(3)+P(4) должно быть меньше &H4000, иначе результат непредсказуем.

Прочесть байт из VRAM

Прочесть байт из VRAM с автоинкрементом адреса

Прочесть целое число (2 байта) из VRAM

Младший байт берётся из адреса P(1), а старший байт из адреса P(1)+1.

Прочесть целое число (2 байта) из VRAM с автоинкрементом адреса

Младший байт берётся из адреса P(1), а старший байт из адреса P(1)+1.

Записать байт в VRAM

Записать байт в VRAM с автоинкрементом адреса

Записать целое число (2 байта) в VRAM

Младший байт записывается в адрес P(1), а старший байт в адрес P(1)+1.

Записать целое число (2 байта) в VRAM с автоинкрементом адреса

Младший байт записывается в адрес P(1), а старший байт в адрес P(1)+1.

Блочная пересылка данных из VRAM в RAM

P(3)+P(4) должно быть меньше &H4000, иначе результат непредсказуем.

Пакетная пересылка данных из RAM в VRAM

Пакетная пересылка данных в пределах VRAM

Если P(4) больше &H4000, только &H4000 байт будет переслано, и инкремент адреса тоже будет ограничен &H4000, но P(4) не будет модифицирован. Таким образом, для пересылки больших блоков (до 64Кб) простым способом Вы можете выполнить примерно следующее:

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

Преобразование L из десятичного в шестнадцатиричный формат, а потом обратно — требуется из-за того, что целочисленные переменные в MSX BASIC имеют диапазон значений от -32768 до 32767; если большее значение непосредственно занести в P(4), случится ошибка переполнения.

Так как MSX X-BASIC работает с вещественными переменными особым способом, то, если применять этот приём внутри турбо-блока, L должно быть целым, кратным 256.

Заполнить область VRAM байтом

Чтобы заполнить область, размером больше 16кБ, используйте метод, описанный в функции 23.

Заполнить область VRAM байтом с автоинкрементом адреса

Чтобы заполнить область, размером больше 16кБ, используйте метод, описанный в функции 23.

Поиск файла (S4)

F$(1) может включать букву диска и, в случае MSX-DOS 2, путь; F$(0) будет содержать только имя найденного файла.

P(0) должен быть установлен в 0, чтобы искать первое встретившееся совпадение с заданной маской, и оставлен равным 1, чтобы искать следующие файлы. Это то, что функция делает автоматически (всегда устанавливает P(0) в 1). Кроме того, P(11) устанавливается в 1 при первоначальном поиске файла (0 если ничего не найдено), и инкрементируется автоматически на каждой последующей итерации. Поэтому, чтобы найти соответствующие маске файлы, можно использовать цикл вроде этого:

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

Если больше не осталось совпадающих с маской файлов/директорий, функция вернёт ошибку «Файл не найден». Под MSX-DOS, ошибка при поиске первого файла может означать также, что диск не существует или имя файла задано некорректно (под MSX-DOS 2 эти ошибки имеют свой собственный код).

Чтобы получить длину файла, можно использовать формулу P(9)+65536*P(10). При выводе на экран этих длин, помните, что представление числовых переменных различается в MSX BASIC и MSX X-BASIC для больших чисел; лучше всего отображать размер файлов сразу в килобайтах: INT(P(9)/1024)+64*P(10).

Переименование файла (S4)

F$(0) может также включать имя диска и, в случае с MSX-DOS 2, путь; F$(1) должен содержать только новое имя файла. Под MSX-DOS можно переименовывать несколько файлов за один раз, используя маски; под MSX-DOS 2 можно переименовать только один файл за раз.

Удаление файла

F$(0) может также включать имя диска и, в случае с MSX-DOS 2, путь. Под MSX-DOS 2 эта функция выдаст ошибку, если Вы попытаетесь удалить открытый файл. Под MSX-DOS можно удалить открытые файлы, но это не рекомендуется, потому что последующие попытки доступа у этим файлам могут привести к непредсказуемым результатам.

Под MSX-DOS можно удалять несколько файлов за один раз, используя маски; под MSX-DOS 2 можно удалить только один файл за раз.

Перемещение файла (MSX-DOS 2)

Эта функция доступна только под MSX-DOS 2. Под MSX-DOS всегда возвращает ошибку 1.

F$(0) может также включать имя диска и путь. F$(1) не должен содержать ни имени файла (файл при перемещении сохраняет то же имя), ни буквы диска (файл может быть перемещен только в другой каталог на том же диске). Если задать каталог вместо файла в F$(0), все его подкаталоги и содержащиеся в нём файлы тоже будут перемещены.

Создание файла или директории

F$(0) может также включать имя диска и путь. Файл будет создан с нулевой длиной и не останется открытым: для доступа к файлу, его нужно будет предварительно явно открыть (функция 31).

Под MSX-DOS можно создавать только файлы, и P(0) игнорируется. Под MSX-DOS 2 файлы всегда создаются с установленным атрибутом «архивный», в дополнение к атрибутам, заданным в P(0).

Открытие файла

F$(0) может содержать букву диска и, в случае с DOS 2, путь. Число, возвращаемое в P(0), идентифицирует файл, и будет указываться при последующих вызовах дисковых функций. Конкретное значение этого числа зависит от версии MSX-DOS и того, сколько файлов было открыто и закрыто ранее; не нужно воспринимать это значение как показатель текущего количества открытых файлов (используйте для этого функцию 1).

Под MSX-DOS, если превысить допустимое число одновременно открытых файлов, возникнет ошибка 3. Максимальное число одновременно открытых файлов под MSX-DOS можно узнать посредством 1-й функции.

Закрытие файла

Очень важно закрывать файлы, которые уже не будут использоваться: иначе, если в них осуществлялась какая–то запись, во внутренних буферах MSX-DOS могут оставаться несохраненные данные, которые будут потеряны; к тому же, в этом случае, элемент каталога для этого файла не будет обновлён.

Чтение из файла (S4)

P(3)+P(4) должно быть меньше &H4000, иначе результат непредсказуем.

Файл читается с позиции, на которую указывает файловый указатель; этот указатель автоматически увеличивается после чтения. Чтобы узнать или изменить этот указатель, используйте функцию 42.

Чтобы прочитать файл до конца, или прочитать весь файл, если он короче 16кБ, проще всего попытаться прочесть 16кБ (установить P(4)=&H4000) и игнорировать ошибку с кодом 1 или 199: для данной функции, эти ошибки означают лишь то, что был достигнут конец файла.

Если конец файла был достигнут до прочтения P(4) байт, будет выдана ошибка. Чтобы узнать число прочитанных байт, смотрите в P(7). Если нет ошибки, то в P(7) будет то же значение, что и в P(4); в случае физической ошибки (неисправная FAT, физическая ошибка диска или диск не вставлен), в P(7) всегда будет 0.

Чтение из файла в VRAM (S4)

Если P(4) больше &H4000, только &H4000 байт будет прочитано, и приращение адреса также будет ограничено &H4000, но P(4) не будет изменено. Поэтому, чтобы читать более крупные куски (до 64кБ), можно использовать приём, описанный в функции 23.

Для этой функции также действительны замечания насчет файлового указателя и значения P(7), сделанные в описании функции 33.

Чтение секторов диска (S4)

P(3)+P(4)×512 должно быть меньше &H4000, иначе результат непредсказуем.

Эта функция не поддерживает частичное чтение: если не возникло ошибки, тогда P(7) будет содержать число прочитанных байт, то есть P(4)×512; но в случае ошибки в P(7) будет 0. Если P(6)≠0, P(3) будет увеличен на число прочитанных байт (P(7) или 0).

Чтение секторов диска в VRAM (S4)

Если P(4) больше, чем 32 — только 32 сектора (&H4000 байт) будет прочитано, и приращение адреса также будет ограничено &H4000, но P(4) не будет изменено. Поэтому, чтобы читать более крупные куски (до 64кБ), можно использовать прием, описанный в функции 23.

Для этой функции также действительны соображения относительно значения P(7), сделанные в описании функции 35.

Запись в файл (S4)

P(3)+P(4) должно быть меньше &H4000, иначе данные, записанные в файл, будут непредсказуемыми.

Данные записываются в файл с позиции, на которую указывает файловый указатель; этот указатель автоматически увеличивается после чтения. Чтобы узнать или изменить этот указатель, используйте функцию 42. В случае физической ошибки (неисправная FAT, физическая ошибка диска или диск не вставлен), в P(7) всегда будет 0.

Запись в файл из VRAM (S4)

Если P(4) больше &H4000, только &H4000 байт будет записано, и приращение адреса также будет ограничено &H4000, но P(4) не будет изменено. Поэтому, чтобы записывать более крупные куски (до 64кБ), можно использовать прием, описанный в функции 23.

Для этой функции также справедливы замечания касательно файлового указателя, сделанные в описании функции 37.

Запись в сектора диска (S4)

P(3)+P(4)×512 должно быть меньше &H4000, иначе данные, записанные в файл, будут непредсказуемыми.

Эта функция не поддерживает частичную запись: если не возникло ошибки, тогда P(7) будет содержать число записанных байт, то есть P(4)×512; но в случае ошибки в P(7) будет 0. Если P(6)≠0, P(3) будет увеличен на число записанных байт (P(7) или 0).

Запись в сектора диска из VRAM (S4)

Если P(4) больше, чем 32 — только 32 сектора (&H4000 байт) будет записано, и приращение адреса также будет ограничено &H4000, но P(4) не будет изменено. Поэтому, чтобы записывать более крупные куски (до 64кБ), можно использовать прием, описанный в функции 23.

Для этой функции также справедливы замечания, касающиеся значения P(7), представленные в описании функции 39.

Заполнение файла байтом (S4)

Эта функция просто записывает P(4) байт, равных содержимому P(1), в сегмент 4, начиная с адреса 0, и затем вызывает функцию 37 с P(2)=4 и P(3)=0. Поэтому, все замечания, сделанные в функции 37, будут также справедливы и здесь.

Перемещение файлового указателя

Чтобы установить в P(2) и P(3) смещение D большее, чем 32768 или меньшее, чем 0, нужно использовать следующую формулу:

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

а чтобы восстановить полученный новый указатель в переменную P, следующую:

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

Так как MSX X-BASIC работает с вещественными переменными особым способом, то, если применять этот приём внутри турбо-блока, D должно быть целым, кратным 256.

Чтобы узнать текущую позицию файлового указателя, просто используйте эту функцию с параметрами P(1)=1, P(2)=0 и P(3)=0; чтобы узнать длину файла, вызовите её с параметрами P(1)=2, P(2)=0 и P(3)=0. В первом случае указатель файла остаётся неизменным.

При использовании данной функции, помните, что смещение интерпретируется со знаком. Поэтому:

• Если Вы вызываете функцию с P(1)=0, смещение должно быть положительным. Иначе, при последующем доступе к файлу, результат будет непредсказуемым.
• Если Вы вызываете функцию с P(1)=1, положительное смещение передвинет файловый указатель вперёд; отрицательное смещение передвинет файловый указатель назад.
• Если Вы вызываете функцию с P(1)=2, смещение должно быть отрицательным; в противном случае, файловый указатель будет помещён после конца файла. В таком случае, дальнейшее чтение файла вызовет ошибку «End of file» (будет прочитано 0 байт), а запись в файл приведёт к тому, что пространство между концом файла и указателем будет заполнено нулями.

Узнать текущий диск и вектор доступных дисков (login vector)

Вектор доступных дисков это байт, который содержит, в каждом бите, информацию о наличии или отсутствии (бит=1: присутствует, bit=0: отсутствует); младший бит соответствует диску A: а старший - диску H:. Например, если функция возвращает P(1)=&B01000011, значит присутствуют диски A:, B: и G:

Задать текущий диск

Эта функция выдаст ошибку 62 если попытаться установить текущим неверный диск (отсутствующий, или выше, чем 7).

Информация о дисковом пространстве

Свободное пространство в байтах можно вычислить по формуле P(1)*P(3)*512, или в килобайтах по формуле P(1)*P(3)/2; и то же самое с общим размером диска, используя P(2) вместо P(3).

Эта функция выдаст ошибку 62 если попытаться получить информацию о неверном диске (отсутствующий, или выше, чем 8).

Узнать текущую директорию

Эта функция доступна только под MSX-DOS 2. Под MSX-DOS она будет всегда возвращать код ошибки 1.

Полученная строка не содержит имени привода, а также «\» ни в начале, ни в конце; так, корневая директория будет представлена в виде пустой строки.

Задать текущую директорию

Эта функция доступна только под MSX-DOS 2. Под MSX-DOS она будет всегда возвращать код ошибки 1.

Эта функция не меняет текущий рабочий диск. Чтобы сделать это, используйте функцию 44.

Узнать размер RAM-диска

Эта функция доступна только под MSX-DOS 2. Под MSX-DOS она будет всегда возвращать код ошибки 1.

Чтобы получить размер RAM–диска в килобайтах, просто вычислите P(0)*16. Нулевой размер диска будет означать, что RAM–диск отсутствует.

Создать RAM–диск

Эта функция доступна только под MSX-DOS 2. Под MSX-DOS она будет всегда возвращать код ошибки 1.

Так как по-умолчанию NestorBASIC при первоначальном запуске выделяет себе все свободные сегменты, нужно вызвать функцию 80 для начала, чтобы уменьшить количество сегментов, выделенных NestorBASIC; в противном случае, не будет свободных сегментов для RAM–диска (если только в компьютере не больше 4Мб ОЗУ).

Если нет P(0) свободных сегментов, но можно создать меньший по размеру RAM–диск, функция сделает это и не выдаст никакой ошибки; в P(0) будет возвращён размер созданного RAM–диска. Но если свободных сегментов не было вообще, и RAM–диск не был создан, тогда функция выдаст соответствующую ошибку.

Получить атрибуты файла

Эта функция доступна только под MSX-DOS 2. Под MSX-DOS она будет всегда возвращать код ошибки 1.

Если P(0)=255, будет прочитан байт атрибутов для файла с именем, указанным в F$(0). F$(0) может содержать букву имени привода и путь;

Если нет, то будет прочитан байт атрибутов для уже открытого файла под номером P(0).

Установить атрибуты файла

Эта функция доступна только под MSX-DOS 2. Под MSX-DOS она будет всегда возвращать код ошибки 1.

Если P(0)=255, то будет установлен байт атрибутов для файла с именем, заданным в F$(0). F$(0) может содержать букву имени привода и путь;

Иначе, байт атрибутов будет установлен для уже открытого файла под номером P(0).

Невозможно задать атрибуты уже открытого файла путём указания его имени в F$(0); если попытаться сделать это, произойдёт ошибка. Для открытого файла необходимо указывать его номер файла в P(0).

Для файлов — могут быть модифицированы только атрибуты системный, скрытый, только чтение и архивный;

Для директорий — только скрытый. Если вы попытаетесь изменить любой другой атрибут, вы получите ошибку. Нельзя изменить атрибуты «.» и «..» элементов каталога.

Синтаксический разбор пути

Эта функция доступна только под MSX-DOS 2. Под MSX-DOS она будет всегда возвращать код ошибки 1.

Эта функция только обрабатывает входящую строку, возвращая соответствующие результаты. Не осуществляется никаких обращений к диску, не меняются текущие рабочий привод и директория.

Если строка состоит из одной только лишь буквы привода, или если последним символом в строке является разделитель «\», это будет означать, что в строке нет «последнего элемента»; в этом случае, P(9) будет равняться 0 и F$(1) будет пустой строкой.

Пример:
Для F$(0) = «A:\DIR\FILES\ONEFI.LE», «последним элементом», возвращаемым в F$(1), будет «ONEFI.LE», и P(9) будет равно 14.

Если строка не содержит буквы привода, в P(2) будет возвращено текущее значение рабочего привода. Таким образом, P(2) никогда не будет равняться 0.

Если на входе задано P(10)<>0, то P(1) и P(4) по P(7) всегда будут равны 0.

Сжатие графических данных

Компрессия осуществляется в последовательные сегменты: после записи сжатых данных по адресу &H3FFF сегмента S, запись продолжается с адреса &H0000 сегмента S+1. Если при этом сегмент S+1 не существует, то произойдёт ошибка 5. Эта функция не поддерживает сегменты VRAM и 255 сегмент.

Если последним использованным RAM адресом был &H3FFF сегмента S, и было задано P(6)<>0, то в P(2) будет S+1 и в P(3) 0 по завершении. В этом случае, если S был последним доступным RAM–сегментом, по возвращении из функции в P(2) будет 0.

Распаковка графических данных

Распаковка осуществляется в последовательные сегменты: после декомпрессии данных, находящихся по адресу &H3FFF в сегменте S, чтение исходных сжатых данных продолжается с адреса &H0000 сегмента S+1. Если при этом сегмент S+1 не существует, или обнаружена ошибка в сжатых данных, то произойдёт ошибка 6. Эта функция не поддерживает сегменты VRAM и 255 сегмент.

Если последним использованным RAM адресом был &H3FFF сегмента S, и было задано P(6)<>0, то в P(2) будет S+1 и в P(3) 0 по завершении. В этом случае, если S был последним доступным RAM-сегментом, по возвращении из функции в P(2) будет 0.

Выполнение подпрограммы в машинном коде, находящейся в BIOS, SUB-BIOS, основном ОЗУ MSX BASIC или системной рабочей области

С помощью этой функции можно вызвать машинную подпрограмму, расположенную в BIOS, SUB-BIOS, основном ОЗУ MSX BASIC или системной рабочей области, задав предварительно входные значения регистров через массив P; после возвращения из подпрограммы, выходные значения регистров будут помещены в массив P, в таком же соответствии.

Если на входе P(0)=0, данная функция напрямую запустит машинный код, находящийся по адресу, указанному в P(1), без каких–либо переключений слотов и сегментов. Практически это означает, что данным образом Вы можете вызывать процедуры BIOS (если их адрес находится в диапазоне 0–&H3FFF), программы, загруженные в основное ОЗУ Бейсика пользователем (например, командой BLOAD), и код, расположенный в рабочей области системы в странице 3 (например, хук расширенного BIOS, по адресу &HFFCA). Заметьте, однако, что при выполнении этой функции, сегмент NestorBASIC подключается в страницу 1. Из этого следует, что невозможно напрямую запустить код, находящийся в ПЗУ интерпретатора MSX BASIC. Чтобы вызвать процедуры ПЗУ MSX BASIC, используйте BIOS–процедуру CALBAS (&H0159), которая принимает в IX адрес вызываемой подпрограммы интерпретатора BASIC.

Если на входе P(0)<>0, то будет запущена подпрограмма из SUB-BIOS, адрес которой указан в P(1); в этом случае, если указанный адрес больше, чем &H3FFF, будет возвращена ошибка с кодом -1. Для вызова подпрограмм SUB-BIOS используется BIOS–процедура EXTROM, так что входящее значение регистра IX [переменной P(6)] будет потеряно.

Значение, возвращаемое в P(12), будет тем же самым, что и значение, возвращаемое в старшем байте P(2). Подобным же образом, значения, возвращаемые в P(13) и P(14) будут отражать состояние, соответственно, битов 0 и 6 младшего байта P(2). Так как обычно хотят получить именно значение регистра A, либо выходное состояние флагов Cy и Z, а не целой пары AF, то использование переменных с P(12) по P(14) представляется гораздо более удобным, чем использование P(2) при обработке результирующих значений регистров. Как бы то ни было, для установки входящих значений регистра A и флагов, необходимо использовать P(2), использование P(12)–P(14) не допускается. Вычислить значение, которое нужно занести в P(2), можно по следующей формуле:
P(2) = Cy + 2*N + 4*P/V + 16*H + 64*Z + 128*M + 256*A

Выполнение подпрограммы пользователя (подпрограммы на машинном коде , размещённой в сегменте ОЗУ)

С помощью этой функции можно вызвать подпрограмму в кодах, размещённую в сегменте ОЗУ, с возможностью задать значения регистров ЦП перед вызовом, используя массив P; после возврата из подпрограммы, выходные значения регистров будут помещены в массив P, в том же соответствии.

Указанный в P(0) сегмент будет подключён в страницу 2 для исполнения программы, поэтому она должна быть ассемблирована в диапазон адресов &H8000–&HBFFF. Перед выполнением подпрограммы, BIOS будет подключён в страницу 0, а сегмент NestorBASIC в страницу 1. Перед возвратом из пользовательской подпрограммы, это состояние должно быть восстановлено ей же самой, если осуществлялось какое-либо переключение слотов/сегментов.

Некоторые из внутренних процедур и переменных NestorBASIC (для управления RAM и VRAM, и получения информации о прерываниях, среди прочего) могут использоваться пользовательскими подпрограммами в кодах. В приложении 2 вы можете найти список и подробное описание этих процедур и переменных.

Смотрите также описание функции 58 по поводу замечаний относительно возвращаемых значений P(12)–P(14).

Эта функция не поддерживает сегменты VRAM и 255 сегмент, и выдаст ошибку -1, если несуществующий сегмент указан в P(0).

Вывести строку на дисплей в графическом режиме

Эта функция работает только в видеорежимах со SCREEN 5 по 11, и эквивалентна команде

PRINT#1,F$(0)

предварённой командой

OPEN"GRP:"AS#1

Разница в том, что данная функция совместима с MSX X-BASIC. При вызове в других видеорежимах, эта функция не будет делать ничего, но не выдаст никакой ошибки.

Максимальная длина строки — 80 символов; если F$(0) больше, только первые 80 символов будут выведены. Строка не может содержать символа 0, потому что этот код интерпретируется как конец строки.

Сохранить строку в сегмент

Эта функция копирует строку F$(0) по заданному адресу указанного сегмента. Строка хранится с символом 0 в конце, поэтому будет занимать LEN(F$(0))+1 байт.

Максимальная длина строки — 80 символов; если F$(0) длиннее, только первые 80 символов будут скопированы. Строка не должна содержать 0, потому что этот символ будет интерпретирован как конец строки.

Эта функция вернет ошибку -1, если в P(0) будет указан несуществующий сегмент.

Прочитать строку из сегмента

Эта функция помещает в строковую переменную F$(1) строку, хранящуюся по указанному адресу заданного сегмента. Строка считается законченной когда встречается символ 0, или когда 80 знаков скопированы в F$(1).

Если эта функция вызывается из обычного MSX BASIC, строка не может содержать символа 255, потому что он, если будет найден, будет преобразован в символ 34 (кавычки); это происходит в соответствии с методом присвоения строк в Бейсике, в котором требуется специальная обработка кавычек. Это не происходит при вызове функции из MSX X-BASIC.

Эта функция вернет ошибку -1, если в P(0) будет указан несуществующий сегмент.

Инициализация режима мигания в SCREEN 0

Если P(2) и P(3) оба равны нулю 0, эта функция просто очищает зону мигания в VRAM.

Эта функция инициализирует цвета и интервалы режима мигания в SCREEN 0, и очищает область VRAM, предназначенную для хранения координат мигающих знакомест. Если P(2) и P(3) нулевые, то будет выполнено только последнее.

Эта функция может исполняться только в режиме SCREEN 0 с как минимум 41 столбцами; в противном случае, ничего не будет сделано, кроме возврата ошибки -1.

Действия, которые реализуются этой функцией, могут быть также выполнены независимо, из Бейсика, следующим образом:

Системные переменные FORCLR (&HF3E9) и BAKCLR (&HF3EA) содержат соответственно текущий цвет текста и текущий цвет фона, ранее установленные оператором COLOR. Таким образом, чтобы достичь визуального эффекта инверсии, просто выполните:

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

или

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

Создать или удалить мигающий блок символов

Эта функция создает или удаляет блок мигающих знакомест определенных размеров с заданными координатами. Рекомендуется вызывать функцию 63, прежде чем использовать данную функцию.

Эта функция может исполняться только в режиме SCREEN 0 с как минимум 41 столбцами; в противном случае — ничего не будет сделано, но не будет возвращено никакой ошибки. Если P(1)>79 и/или P(2)>27, будет выдана ошибка -1.

Эта функция не проверяет, выходит ли блок за пределы экрана. Если блок заходит за столбец 79, он продолжается в столбце 0 следующей строки. Но если часть блока выходит за строку 27, эта часть не будет отображена.

Получить информацию о прерываниях

P(2) и P(3) вернут сегмент и адрес прерывания, определяемого пользователем, даже если оно приостановлено. Если пользовательского прерывания не было определено, оба параметра будут нулевыми.

Чтобы получить больше информации о воспроизводимом звуковом эффекте, используйте функцию 67. Для музыки, используйте функцию 72.

Задать или приостановить прерывание, определяемое пользователем

Эта функция задает или останавливает программу, работающую от определяемого пользователем прерывания, то есть, программа в машинном коде, которая будет запускаться при каждом прерывании от таймера, 50 или 60 раз в секунду. NB: Указанный сегмент будет подключен в страницу 2 для исполнения программы, а следовательно, код должен быть собран под адреса в интервале &H8000–&HBFFF.

Если P(0)=1, прерывание определяется через P(1) и P(2), и активируется (исполняется на 50 или 60 Гц). Если P(0)=0, прерывание приостанавливается (не исполняется более), но его определение не изменяется. Если P(0)=-1, его состояние инвертируется (с активного на приостановленное, и наоборот), и его определение не изменяется.

Сегмент прерывания будет подключен в страницу 2 для исполнения программы, а значит код должен быть собран под адреса в интервале &H8000–&HBFFF. BIOS подключен в страницу 0, а сегмент NestorBASIC'а доступен в странице 1. Это состояние должно быть восстановлено самой программой перед возвратом, если осуществлялось переключение слотов/сегментов. Также, прерывания будут запрещены и должны оставаться таковыми в ходе исполнения программы. Сохранения регистров не требуется, потому что NestorBASIC обеспечит это.

Некоторые из внутренних процедур и переменных NestorBASIC (для управления RAM и VRAM, а также для получения информации о процессах, работающих от прерываний, среди прочего) могут быть использованы программами прерываний, определяемых пользователем. В приложении 2 находится перечень и подробное описание этих процедур и переменных.

Вы не можете определить код программы пользовательского прерывания в сегменте VRAM, а также в сегменте 255. Если Вы укажете несуществующий или неверный сегмент в P(1), функция выдаст ошибку -1. Если задать значение, отличное от 0, 1 или -1 в P(0), будет выдана ошибка 7.

Получить информацию о звуковых эффектах PSG

Результаты, возвращаемые данной функцией, будут действительны только если набор SFX был инициализирован функцией 68. Набор эффектов создается с помощью редактора SEE v3.xx, разработанного Fuzzy Logic.

Эта функция не возвращает никаких ошибок. Если значение, указанное в P(0), больше, чем 15, оно будет истрактовано как 15.

Инициализация набора звуковых эффектов PSG

Эта функция инициализирует набор звуковых эффектов, хранящийся в указанных сегменте и адресе, оставляя его готовым к использованию функцией 69.

Набор SFX создается с помощью редактора SEE v3.xx от Fuzzy Logic; если формат набора некорректен, функция выдаст ошибку 8.

Не допускается использование набора SFX, находящегося в сегменте VRAM или 255–м сегменте. Если в P(0) был указан несуществующий сегмент, произойдет ошибка -1.

Воспроизвести звуковой эффект PSG

Эта функция запускает проигрывание указанного SFX эффекта; набор эффектов создается с помощью редактора SEE v3.xx, созданного Fuzzy Logic. Если набор SFX не был инициализирован функцей 68, то поведение непредсказуемо.

P(1) управляет приоритетом в случае попытки воспроизвести эффект, когда уже воспроизводится другой. Это работает следующим образом:

• Если новый и уже воспроизводимый SFX имеют одинаковый приоритет, то воспроизводимый SFX останавливается, и проигрывается новый.
• Если воспроизводимый SFX имеет низкий приоритет, а новый - высокий, то происходит то же самое.
• Если воспроизводимый SFX имеет высокий приоритет, а новый SFX - низкий, то старый SFX продолжает звучать, и функция возвращает ошибку 11.

Если звуковой эффект, указанный в P(0), не определен (первый трэк установлен в «OFF» в редакторе), функция вернет код ошибки 9. Если эффект не существует (его номер больше, чем последний определенный номер эффекта), функция вернет код ошибки 10.

Остановить воспроизведение звукового эффекта PSG

Эта функция останавливает воспроизведение звукового эффекта PSG, если таковой проигрывался, и заглушает PSG. Функция не выдает ошибок.

Загрузка и инициализация, или выгрузка Moonblaster-плеера (S4)

Эта функция загружает указанный MoonBlaster–плеер в сегмент 5, оставляя готовым к использованию. Также, производит поиск всех присутствующих в системе звуковых чипов, и оставляет все найденные чипы включенными (см. функцию 73, чтобы узнать больше подробностей об активации звуковых чипов).

Проигрыватель может быть загружен только если сегмент 5 существует и принадлежит первичному мапперу; в противном случае, функция выдаст ошибку -1. Если случается дисковая ошибка, функция возвращает соответствующий код ошибки (см. раздел 4). Если NBASIC.BIN в результате ошибки остается открытым, его соответствующий номер файла будет в P(1); иначе, P(1) будет -1.

Файл NBASIC.BIN содержит две версии плеера Moonblaster Wave: одна из них — для MSX2/2+ и Turbo-R в режиме Z80, а другая - для Turbo-R в режиме R800. Если компьютер является Turbo-R, то NestorBASIC решает, какую версию загрузить в зависимости от работающего процессора в момент вызова функции 71. Заметьте, что если произведено переключение процессора, эта функция должна быть вызвана снова чтобы загрузить подходящий плеер: версия для Z80 не работает в режиме R800, а версия для R800 привносит замедление в режиме Z80.

Чтобы выгрузить плеер, используйте эту функцию с P(0)=-1 на входе; Вам не нужно предварительно останавливать воспроизводимую музыку, так как функция позаботится об этом сама. После выгрузки проигрывателя (которая заключается просто в удалении строки «NestorPlayer» в начале сегмента 5), сегмент 5 снова становится доступным, как любой другой. Если Вы попытаетесь выгрузить проигрыватель когда никакой плеер не загружен, функция не сделает ничего и не выдаст никакой ошибки.

Можно загружать, выгружать и загружать снова MoonBlaster–плееры столько раз, сколько понадобится, в ходе выполнения программы. Если какой-то проигрыватель загружен, его легко можно заменить на другой, что очень удобно.

Получить информацию о проигрываемой музыке

Если не загружен никакой плеер, в P(12) будет ноль, остальные выходные параметры не будут выставлены (кроме P(9)–P(11)); функция не возвращает никаких ошибок. Для загрузки плеера используйте функцию 71.

Если никакая музыка не воспроизводится, в P(5) и P(6) будут возвращены позиция и шаг, где последняя проигрываемая мелодия была остановлена, а F$(0) и F$(1) будут пустыми строками. В противном случае, в F$(0) будет содержаться имя мелодии (всегда 40 символов для музыки Moonblaster 1.4, 50 для музыки Moonblaster Wave) F$(1) будет содержать имя samplekit'а или wavekit'а, который был загружен в Moonblaster на момент сохранения композиции, заглавными буквами и без расширения («NONE», если никакого samplekit'а не было загружено).

В P(9)–P(11) возвращается информация о обнаруженных звуковых устройствах, даже когда проигрыватель не загружен. Чтобы узнать информацию об активных звуковых устройствах, используйте функцию 73.

Активация и деактивация звуковых устройств

Эта функция позволяет отключать MSX Music, MSX Audio и OPL4, которые, в этом состоянии, не будут использоваться, несмотря на то, что были обнаружены в системе. Эта возможность будет полезна, например, для прослушивания только MSX Audio–части композиции на компьютере со встроенным MSX Music.

Если P(0)=0, функция только выдаст сведения об активных звуковых устройствах в P(4)–P(5), и не изменит их состояние. Если P(0)=2, все найденные звуковые устройства будут включены (это действие по-умолчанию при загрузке плеера). Для получения сведений о присутствии звуковых устройств используйте функцию 72.

Если P(0)=1, звуковые устройства будут активированы либо отключены согласно значениям, переданным в P(1)–P(3); попытки активировать устройства, которые отсутствуют в системе, будут проигнорированы. Если отключен и MSX Audio, и MSX Music (Moonblaster 1.4 player), или отключен OPL4 (Moonblaster Wave player), функция 74 (начало воспроизведения музыки) не будет ничего делать, но не выдаст никакой ошибки.

Изменения, сделанные этой функцией, не вступят в силу, пока играющая музыка не будет остановлена (функция 75 или 77), и запущена по новой (функция 74). Если никакой музыки не воспроизводилось в момент, когда Вы использовали данную функцию, просто стартуйте воспроизведение, обычным образом.

Эта функция вернет код ошибки 7, если какой-либо из входящих параметров не корректен (но если P(0)<>1, не требуется устанавливать P(1)–P(3)), и код ошибки 12, если плеер не загружен.

Старт воспроизведения Moonblaster–музыки

Эта функция запускает воспроизведение указанной Moonblaster–музыки. Если заданный сегмент не существует, является сегментом VRAM или 255–м, произойдет ошибка -1. Если не был загружен плеер, соответствующий типу музыки, возникнет ошибка 12 (используйте для загрузки проигрывателя функцию 71). Композиции Moonblaster Wave могут находиться в нескольких смежных сегментах; подробности см. в разделе 8.2.

В случае с плеером Moonblaster 1.4, данная функция проверяет первый байт данных по указанному адресу; если там &HFF, то это означает, что композиция была сохранена в режиме EDIT, и, следовательно, не может быть воспроизведена; в таком случае будет выдана ошибка 13. Иначе, NestorBASIC считает, что по заданному адресу расположена Moonblaster–музыка, сохраненная в режиме USER, и начинает воспроизведение без дальнейших проверок. Если означенная область памяти не содержит Moonblaster–музыки, результат будет непредсказуемым.

Проигрыватель Moonblaster Wave не имеет подобных недостатков: он может определять, действительно ли по заданному адресу содержится музыка Moonblaster Wave, и что она записана в режиме USER. Если нет, то выдается ошибка 13.

Если и MSX Music, и MSX Audio были деактивированы (музыка Moonblaster 1.4), или OPL4 был деактивирован (музыка Moonblaster Wave) функцией 73, данная функция не произведёт никаких действий, и не выдаст никакой ошибки. Если в данный момент уже воспроизводится, или стоит на паузе, другая музыка — случится ошибка 14.

Останов воспроизведения музыки

Эта функция останавливает воспроизведение музыки и заглушает звуковые устройства. Если никакая музыка не играет в этот момент, или ни один музыкальный проигрыватель не загружен, функция не выполнит никаких действий. Она не возвращает ошибок.

Постановка на паузу и продолжение воспроизведения музыки

Эта функция приостанавливает или возобновляет воспроизведение Moonblaster–музыки. Если никакая музыка не воспроизводится и не стоит на паузе, или проигрыватель не загружен, функция не будет ничего делать и не выдаст никакой ошибки. Если входной параметр недействителен, будет возвращена ошибка с кодом 7.

Постепенное затухание музыки

Эта функция стартует затухание проигрываемой музыки. Интервал задержки это число тактов (1/50 или 1/60 секунды каждый) между шагами затухания, так, что наименьшая задержка соответствует наиболее быстрому затуханию. Как только затухание завершилось (громкость музыки уменьшилась до нуля), воспроизведение будет автоматически остановлено: Вам не придется останавливать его директивно функцией 75.

Если P(0)=-1, угасание будет приостановлено, то есть, музыка продолжит играть обычным образом, с достигнутым уровнем громкости. Чтобы возобновить затухание, просто вызовите эту функцию снова, указав новое значение задержки в P(0).

Если P(0)=0, данная функция только вернет в P(1) и P(2) актуальные значения. Если никакая музыка не играет, или проигрыватель не загружен, функция не сделает ничего. Она не возвращает ошибок.

Загрузка samplekit-а для Phillips NMS 1205 Music Module (S4)

Эта функция загружает из указанного открытого файла samplekit (набор сэмплов) для Phillips Music Module, который должен быть записан в формате Moonblaster: 56 байт заголовка, которые будут скопированы в соответствующую область плеера; и 32Кб сэмплов, которые будут переданы в sample-RAM Music Modul-я.

Данные будут считаны из предварительно открытого файла. Это позволяет Вам совмещать samplekit с другими данными в одном и том же файле: в таком случае, достаточно поместить файловый указатель в нужное место, и затем вызвать данную функцию. Однако, как правило, чаще всего требуется загрузить MBK–файл, созданный непосредственно в Moonblaster–е. В таком случае, Вы можете загрузить samplekit, просто выполнив следующее:

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

Если случилась дисковая ошибка, функция вернет соответствующий код ошибки, и число прочитанных байт будет содержаться в P(7). Если это число больше 16Кб, то только первые 16Кб samplekit-a было передано в sample-RAM. Если меньше, то значит никаких данных не было передано в sample-RAM.

Если плеер был не загружен, или Music Module не найден, данная функция не совершит никаких действий и не выдаст ошибки. Если весь samplekit успешно загружен, в P(7) вернется не 32824, а -32712, соответственно диапазону целочисленных переменных (-32768 to 32767) MSX BASIC.

Загрузить wavekit для Moonsound(S4)

Эта функция загружает из указанного открытого файла wavekit для Moonsound, который должен быть записан в формате USER (иначе, случится ошибка 15).

Данные будут считаны из предварительно открытого файла. Это позволяет хранить samplekit в одном файле с другими данными: в таком случае, достаточно поместить файловый указатель в нужное место, и затем вызвать данную функцию. Однако, как правило, чаще всего требуется загрузить MWK-файл, созданный непосредственно в редакторе Moonblaster Wave. В этом случае, Вы можете загрузить samplekit, просто выполнив следующее:

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

Если случилась дисковая ошибка, функция вернет соответствующий код ошибки, и число прочитанных байт будет содержаться в P(6):P(7). В таком случае, память сэмплов Moonsound могла быть изменена, но рабочая область проигрывателя не была обновлена, поэтому нельзя считать, что wavekit был частично загружен.

Если плеер Moonblaster Wave не был загружен, или не было найдено Moonsound-а в системе, функция не осуществит никаких действий и не выдаст ошибки. Если весь wavekit был успешно загружен, P(6):P(7) будут содержать размер wavekit-а (будет равен размеру файла, если Вы просто загрузили .MWK файл).

Узнать или задать количество сегментов выделенных для NestorBASIC

Эта функция работает и в MSX-DOS, и в MSX-DOS 2, как бы то ни было, она предназначена для применения в MSX-DOS 2.

Под MSX-DOS 2, NestorBASIC, инициализируясь после загрузки, резервирует для себя все свободные сегменты в системе, вплоть до 247-го. Это означает, что не останется свободных сегментов для других резидентных программ, которые тоже осуществляют аллокацию памяти — такие как MSX-DOS 2 RAM-диск, NestorMan или InterNestor Suite. Решение этой проблемы заключается в использовании этой функции для того, чтобы сообщить NestorBASIC, сколько сегментов реально нужно; остальные сегменты будут будут освобождены и станут доступными для других программ. Например, если Вы собираетесь использовать музыкальный плеер (который загружается в сегмент 5), и Вам нужен лишь один дополнительный сегмент для данных, тогда нужно вызвать эту функцию с P(0)=7; дополнительный сегмент будет номер 6.

Если в P(0) задано количество сегментов меньше 6, NestorBASIC выделит 5 сегментов (см. раздел 2), или 6 если проигрыватель музыки был загружен. Если задано число сегментов, большее, чем общее количество доступных сегментов, то будет зарезервировано столько сегментов, сколько возможно (вплоть до 247), и в P(0) вернется число сегментов, которое было в действительности выделено. В любом случае, данная функция не выдаст никакой ошибки.

Под MSX-DOS, всё, что делает эта функция - только изменяет некоторые внутренние переменные NestorBASIC; значение, возвращаемое в P(1), фиксированное и вычисляется во время первоначального запуска NestorBASIC. Под MSX-DOS 2, напротив, происходит реальное выделение и освобождение сегментов с использованием процедур MSX-DOS 2 для работы с маппером; в этом случае, значение, возвращаемое в P(1), пересчитывается при каждом вызове функции, и зависит от того, сколько сегментов было зарезервировано другими резидентными программами.

Проверка присутствия NestorMan и InterNestor Suite в ОЗУ

Значение, возвращаемое в P(5) будет действительно, только если P(0) равно 1 или 3 на выходе. Это значение требуется для того, чтобы осуществлять обмен данными между сегментом NestorMan и сегментом NestorBASIC, используя сегмент 4 (общий для обей программ) как промежуточный буфер, как описано в разделе 9.2.

Значения, возвращаемые в P(1)–P(4), будут действительны только если P(0) равно 3 на выходе. Не обязательно знать расположение модулей InterNestor Suite, чтобы вызывать его подпрограммы (используя функцию 85), но это необходимо знать, чтобы читать и записывать конфигурационные константы и переменные модулей, как описано в разделе 9.3.

Выполнить функцию NestorMan

Эта функция вызывает функцию NestorMan, указанную в P(0), посредством метода непрямого вызова, то есть, используя hook расширенного BIOS. Таким образом, это равносильно использованию функции 58 с установленными предварительно P(1)=&HFFCA, P(3)=Функция+256*B, и P(4)=&H2202.

Функцией будет возвращен код ошибки -1, если NestorMan отсутствует. Отметьте, тем не менее, что не производится проверка, существует ли действительно в NestorMan указанная функция.

См. также описание функции 58 для понимания выходных значений P(12)–P(14).

Раздел 9 демонстрирует некоторые техники для обмена данными между NestorMan и NestorBASIC.

Передача блока данных из сегмента NestorMan в сегмент NestorBASIC

Эта функция идентична функции 10, кроме того, что значение, передаваемое через P(0) соотносится с сегментом NestorMan. Как и в случае с функцией 10, P(3)+P(4) должно быть меньше &H4000, в P(2) может быть указан сегмент VRAM или 255–й сегмент, и ошибка -1 будет выдана, если любой из указанных сегментов не существует.

У данной функции есть одно ограничение: её нельзя использовать, указав сегмент 1 в качестве NestorBASIC–сегмента назначения. Как правило, это не является проблемой, потому что 1–й сегмент содержит компилятор MSX X-BASIC, и обычно никому не нужно менять его содержимое. Если, тем не менее, передача в 1-й сегмент необходима, Вам придется сначала скопировать данные в какой-то другой сегмент, в качестве промежуточного шага — например, в сегмент 4.

Передача блока данных из сегмента NestorBASIC в сегмент NestorMan

Эта функция идентична функции 10, кроме того, что значение, передаваемое через P(2) соотносится с сегментом NestorMan. Как и в случае с функцией 10, P(3)+P(4) должно быть меньше &H4000, в P(0) может быть указан сегмент VRAM или 255–й сегмент, и ошибка -1 будет выдана, если любой из указанных сегментов не существует.

У данной функции есть одно ограничение: её нельзя использовать, указав сегмент 1 в качестве NestorBASIC–сегмента источника. Как правило, это не является проблемой, потому что 1–й сегмент содержит компилятор MSX X-BASIC, и обычно никому не нужно менять его содержимое. Если, тем не менее, передача в 1–й сегмент необходима, Вам придется сначала скопировать данные в какой-то другой сегмент, в качестве промежуточного шага - например, в сегмент 4.

Вызов процедуры InterNestor Suite

С помощью этой функции можно вызвать любую подпрограмму любого из модулей InterNestor Suite. Чтобы читать или изменять конфигурационные константы и переменные модулей, нужно сначала узнать номера NestorMan-сегментов модулей, используя функцию 81, а затем применить любой из приемов, описанных в разделе 9.2, для обмена данными между NestorBASIC и NestorMan.

Данная функция выдаст ошибку -1, если InterNestor Suite отсутствует в памяти, или в P(0) указан недействительный номер модуля.

См. также описание функции 58 для понимания выходных значений P(12)–P(14).

Раздел 9.3 содержит некоторые соображения насчет совместного использования NestorBASIC и InterNestor Suite.

Вызов процедуры InterNestor Lite

С помощью этой функции можно вызвать любую процедуру InterNestor Lite. P(1) должен содержать адрес какой-либо из подпрограмм InterNestor Lite, перечисленных в его руководстве программиста, иначе результаты исполнения данной функции непредсказуемы.

Данная функция выдаст ошибку -1, если InterNestor Lite отсутствует в памяти. Чтобы заранее узнать, загружен InterNestor Lite или нет, используйте следующий код, в котором применяется метод обнаружения, описанный в разделе 9.4:

P(0)=0: P(1)=&HFFCA: P(2)=0: P(4)=&H2203: E=USR(58):
IF P(12)=0 THEN ... (отсутствует)

В разделе 9.4 есть комментарий относительно применения процедур InterNestor Lite для обмена данными с TPA из NestorBASIC. См. также описание функции 58 для понимания выходных значений P(12)–P(14).

Следующий пример выводит номер версии InterNestor Lite, загруженного в данный момент.

10 BLOAD"nbasic.bin",R
20 IF P(0)<5 AND P(0)<>3 THEN PRINT "Error "+P(0):END
30 '* Check the presence of INL
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 present.":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 present."
100 '* Unloads 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

Программа TCPCON-L.BAS, поставляемая с NestorBASIC, является более сложным примером, который иллюстрирует совместную работу NestorBASIC и InterNestor Lite.

Функции, которые используют 4-й сегмент, имеют метку «(S4)» после их названий.
Это функции: 0, 26-28, 30, 33-41, 55-57, 71, 78, и 79.

Доступные пользователю внутренние процедуры и переменные NestorBASIC

Когда выполняются подпрограммы пользователя в кодах или пользовательские прерывания, сегмент NestorBASIC остается подключенным в страницу 1. В его начале есть таблица, содержащая переходы на некоторые внутренние процедуры NestorBASIC, а также его внутренние переменные, которые могут быть полезны для подпрограмм пользователя. В этом разделе описывается расположение и назначение этих подпрограмм и переменных.

Все эти процедуры не меняют состояние прерываний, кроме PUTSLOT0, возврат из которой происходит с запрещенными прерываниями.

К сведению: Логический сегмент 255 всегда ссылается на память, подключенную во 2 и 3 страницы на момент обращения к данному сегменту. Когда выполняется подпрограмма пользователя в машинных кодах, или подпрограмма прерывания пользователя, страница 2 содержит НЕ сегмент основного ОЗУ MSX BASIC, а сегмент самой подпрограммы. Чтобы действительно сконвертировать сегмент 255 в соответствующий сегмент MSX BASIC, нужно выполнить следующее:

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

Содержимое таблицы представлено ниже:

&H4100
Идентификационная строка «NestorBASIC x.xx»

&H4110: TABSEGS
Указатель на таблицу сегментов. Формат этой таблицы следующий:

&H4112: INT_DATA
Содержит информацию об активных прерываниях NestorBASIC:

&H4113: PUTSLOT0
Подключает слот к странице 0 без использования ENASLT. После возврата из данной процедуры прерывания запрещены.

&H4116: CHKSLE
Проверяет, существует ли логический сегмент. НЕ распознает как действительные, сегменты, соответствующие VRAM, а также 255–й.

&H4119: CHKSLFF
Проверяет, является ли логический сегмент 255–м, и в этом случае преобразует его в соответствующий сегмент (текущий сегмент страницы 2 если HL<&HC000, сегмент 3 если HL>=&HC000)

&H411C: CHKSLV
Проверяет, является ли логический сегмент сегментом VRAM, и если да, то преобразует его в соответствующий адрес VRAM.

&H411F: VTOSL
Преобразует адрес VRAM в соответствующий ему логический сегмент.

&H4122: GET_SF
Получить физический сегмент и слот, соответствующие логическому сегменту.

&H4125: GET_SLT Узнать слот, подключенный в страницу 1 или 2.

&H4128: READ_SL
Прочесть один байт из логического сегмента.

&H412B: WRITE_SL
Записать байт в логический сегмент

&H412E: LDIRSS
Осуществляет копирование данных из одного логического сегмента в другой. Распознает логический сегмент 255 и сегменты VRAM. Возвращается с BIOS подключенным в страницу 0. Не проверяет случаи, когда BC>&H4000.

&H4131: CHKBV
Проверяет, существует ли адрес VRAM.

&H4134: SET_RD
Подготавливает VDP к чтению VRAM.

&H4137: SET_WR
Подготавливает VDP к записи в VRAM.

&H413A: LDIRVR
Копирует блок данных из VRAM в RAM.

&H413D: LDIRRV
Копирует блок данных из RAM в VRAM.

&H4140: LDIRVV
Копирует блок данных из VRAM в VRAM через буфер в RAM.

&H4143: FILLVR
Заполняет область VRAM байтом.

&H4146: BLK_CLS
Очищает область VRAM предназначенную для режима мигания (SCREEN 0 «blink» mode).

&H4149: BLK_COL
Устанавливает цвета режима мигания.

&H414C: BLK_TIM
Устанавливает временные интервалы режима мигания.

&H414F: BLK_ON
Создание мигающего блока.

&H4152: BLK_OF Удаление мигающего блока.

&H4155: C_BLKAD
Вычисление адреса VRAM, соответствующего заданным координатам мигающего блока.

&H4158: C_STBT
Вычисление бита, соответствующего заданным координатам мигающего блока.

&H415B: GINFOUS
Выдает информацию о прерывании пользователя.

&H415E: GINFOSFX
Выдает информацию о звуковых эффектах PSG

&H4161: GINFOMUS
Выдает информацию о музыке, которая проигрывается, и о присутствии плеера Moonblaster.

&H4164: REPTYPE
Байт информации, содержащий тип проигрывателя музыки, который загружен:

• 0: Проигрыватель MoonBlaster 1.4
• 1: Проигрыватель MoonBlaster Wave

Внимание: прежде чем обращаться к данной информации, необходимо выяснить, загружен ли хоть один плеер. Это можно сделать с помощью функции GINFOMUS (&H4161).

&H4165: GETF01

Эта процедура копирует содержимое строковых массивов F$(0) y F$(1) в два буфера NestorBASIC, находящихся в странице 3; адреса этих буферов указаны в переменных F0BUFADD и F1BUFADD, упоминаемых позже.

Копируется только первые 80 символов строк. В конце их добавляется символ 0.

&H4168: SETF0
&H416B: SETF1

Эти процедуры заносят в строковые массивы F$(0) y F$(1), соответственно, содержимое двух внутренних буферов NestorBASIC, находящихся в странице 3; адреса этих буферов указаны в переменных F0BUFADD и F1BUFADD, упоминаемых позже.

Строки должны оканчиваться символом 0 в буферах, и их длина должна быть не более 80 знаков; если они больше, то только первые 80 знаков будут занесены.

&H416E: F0BUFADD
&H4170: F1BUFADD
Эти внутренние переменные содержат адреса буферов в странице 3, которые используются в качестве приемника процедурой GETF01, и в качестве источника процедурами SETF0 и SETF1. Эти буферы имеют размер 80 байт каждый.

&H4172: SL_2
Номер логического сегмента, подключенного в страницу 2 (то есть, номер логического сегмента, в котором находится программа, читающая эту переменную).

&H4173: NMAN_SL4
Номер сегмента NestorMan, соответствующего сегменту 4 NestorBASIC.

&H4174: INS_SL1 &H4175: INS_SL2 &H4176: INS_SL3 &H4177: INS_SL4
Номера сегментов NestorMan модулей InterNestor Suite с 1 по 4, соответственно.

Прерывания на MSX Turbo-R

NestorBASIC отлично работает на любом MSX 2/2+/Turbo-R, но может вызвать проблемы с прерываниями, если исполняется на Turbo-R в режиме MSX-DOS 1, особенно если используется внешнее расширение ОЗУ. Это связано с тем, что перед выполнением прерывания, NestorBASIC должен убедится, что сегмент подключен в страницу 1, и в режиме MSX-DOS 1 это может быть сделано только инструкцией IN A,(&HFD), которая на Turbo-R работает не совсем так, как на MSX2/2+.

Поэтому, если Вы собираетесь использовать пользовательские прерывания или звуковые эффекты в программе, которая использует NestorBASIC, самое лучшее будет проверять — является ли компьютер Turbo-R (если PEEK(&H2D)=3), и не работает ли в режиме MSX-DOS 1 (это можно сделать функцией 1), и в этом случае сообщить пользователю, что требуется загрузиться в режиме MSX-DOS 2.

Условия использования

NestorBASIC это бесплатная программа, или, на профессиональном языке, freeware.

Тем не менее, есть несколько условий для использования его в ваших программах:

• Где-нибудь в программе (при загрузке, в разделе «О программе», и т.п.) должно появляться упоминание об использовании NestorBASIC, а также его версия (чтобы узнать версию NestorBASIC, используйте функцию 1).
• Если программа предназначена не исключительно для личного пользования автора (то есть, если она будет распространяться бесплатно или за плату), нужно предоставить мне ее копию.

Если у вас есть предложения, вопросы или комментарии относительно NestorBASIC, вы можете связаться со мной по адресу konamiman@konamiman.com.

Использование звуковых эффектов, созданных в редакторе SEE, обусловлено своими собственными требованиями. Если вы собираетесь продавать вашу программу за более чем 15 гульденов, вы должны будете заплатить небольшую сумму авторам, как максимум 25 гульденов. Для конкретных деталей касательно SEE свяжитесь с Fuzzy Logic:

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

NestorBASIC

MBWAVE DISKMENU EN - MSX MUSIC WIKI