MPI 1.00 (Module Procedures Interface)


6 June 2006


PROGRAMMER REFERENCE GUIDE


05698-006-3008810-01001

Table of Contents

NAME

     MPI 1.00 (Module Procedures Interface) - Интерфейс модульных процедур.

SYNOPSIS

     1. Including (Подключение модуля интерфейса)

     Для подключения модуля следует использовать стандартные средства PDS

     2. Declaration (Объявление процедур интерфейса)

     Для объявления всех процедур модуля включите следующие строки в начало главного модуля Вашего проекта

DECLARE SUB MPI.LoadCFG (struct() AS STRING, FileName$, ret!, retf!)
DECLARE SUB MPI.Split (struct() AS STRING, Parameterslist$, Separatorchars$)
DECLARE SUB MPI.ReverseStruct (struct() AS STRING, ret!, retf!)
DECLARE SUB MPI.DelStruct (struct() AS STRING, key$, value$, ret!, retf!)
DECLARE SUB MPI.GetStruct (struct() AS STRING, key$, value$, ret!, retf!)
DECLARE SUB MPI.DatagramSplit (datagram$, key$, value$)
DECLARE SUB MPI.DatagramJoin (datagram$, key$, value$)
DECLARE FUNCTION MPI.SearchIndex! (struct() AS STRING, key$)
DECLARE SUB MPI.PutStruct (struct() AS STRING, key$, value$, ret!, retf!)
DECLARE FUNCTION MPI.GetCountIndex! (struct() AS STRING)
DECLARE FUNCTION MPI.GetLastIndex! (struct() AS STRING)
DECLARE FUNCTION MPI.GetSizeStruct! (struct() AS STRING)
DECLARE FUNCTION MPI.Error$ (ret!, retf!)

' MAIN
DECLARE FUNCTION CV& (value$, bytes!)
DECLARE FUNCTION mk$ (value, bytes!)
DECLARE FUNCTION trim$ (value$)
DECLARE FUNCTION exists! (FlN$, Par$)
DECLARE FUNCTION format.date$ (FD$, DWord$)
DECLARE FUNCTION Version.Convert$ (value$, method$)

' CRC16STD
DECLARE FUNCTION CRC! (message$, init!)

     3. codeparation (Подготовка перед использованием)

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


REDIM array(0 TO 255) AS STRING
DIM array(0 TO 255) AS STRING

     4. Using (Использование)

     Существует общая схема работы с интерфейсом.

A. Создание структуры / чтение из файла
B. Использование структуры
C. Запись структуры в файл

     Ниже детально описаны механизмы этих схем

     4.1. Добавление новых данных

MPI.PutStruct array(), "name", "Abalama", ret, retf
MPI.PutStruct array(), "sex", "male", ret, retf
MPI.PutStruct array(), "language", "russian", ret, retf

     4.2. Изменение данных

MPI.PutStruct array(), "name", "Halama", ret, retf

     4.3. Чтение данных

     Структура имеет заголовок, в котором содержатся основные дескрипторы, такие, как:

- Размер структуры
- Количество элементов (дейтаграмм)
- Номер последнего элемента, к которому было итеративное обращение

     Доступ к дескрипторам можно получить с помощью процедур:

PRINT "SizeStruct : "; MPI.GetSizeStruct(array())
PRINT "CountIndex : "; MPI.GetCountIndex(array())
PRINT "LastIndex : "; MPI.GetLastIndex(array())

     4.3.1. Итеративный метод

FOR i = 1 TO MPI.GetCountIndex(array())
PRINT array(i)
NEXT i

     или:

FOR j = 1 TO MPI.GetCountIndex(array())
key$ = ""
MPI.GetStruct array(), key$, value$, ret, retf
PRINT key$; ": "; value$
NEXT j

     При этом методе используется внутренний счетчик просмотра. Это дает возможность циклично прочитывать структуру несколько раз при условии что цикл был завершен полностью.

     4.3.2. Случайный метод (хеш метод)

key$ = "name"
MPI.GetStruct array(), key$, value$, ret, retf
PRINT key$; ": "; value$

     4.4. Удаление детаграммы

key$ = "name"
MPI.DelStruct array(), key$, value$, ret, retf

     Этот метод возвращает значение удаленного элемента структуры

     4.5. Разделение и добавление элементов списка в структуру

MPI.Split array(), "First;Second;Five", ";"

     Метод использует в качестве разделителя один из символов, заданных в последнеднем аргументе

     4.6. Переворот структуры (реверсирование)

     Метод меняет местами ключи и значения ключей. Метод полезен при сортировках, т.к. сортировки проходят по ключам.

MPI.ReverseStruct array(), ret, retf

     4.7. Сортировка

     Сортировка ASCII

MPI.SortS array(), ret, retf

     Сортировка по значению числовой составляющей

MPI.SortI array(), ret, retf

     Сортировка по значению

MPI.ReverseStruct array(), ret, retf
MPI.SortS array(), ret, retf
MPI.ReverseStruct array(), ret, retf

     4.8. Запись и чтение текстового файла настроек (*.CFG)

MPI.SaveCFG array(), "mpi.cfg", ret, retf
MPI.LoadCFG array(), "mpi.cfg", ret, retf

     4.9. Запись и чтение двоичного файла настроек (*.MPI)

MPI.Save array(), "mpi.mpi", ret, retf
MPI.Load array(), "mpi.mpi", ret, retf

     5. Использование флагов возврата

     Большая часть процедур методов использует в синтаксисе так называемые код и флаги возврата - ret и retf соответственно.

  1. 0 (1) - Overload structure! - Перегрузка структуры
  2. 1 (2) - Internal error! - Внутренняя ошибка
  3. 2 (4) - Index > MPIMAXIMUM! - Превышен индекс
  4. 3 (8) - Key or Value overload! - Перегрузка ключа/значения
  5. 4 (16) - File CFG error! - Ошибка файла CFG
  6. 5 (32) - File MPI error! - Ошибка файла MPI
  7. 6 (64) - File MPI error - data failed! - Ошибка данных файла MPI
  8. 7 (128) - RESERVED - Зарезервированный флаг

ABSTRACT

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

ANNOTATION

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

     MPI Разработана на базе ранних разработок - SSI и RSP, слив и доработав их функциональные возможности. Таким образом MPI способна выполнять такие манипуляции с данными, как:

  1. Создание структуры MPI в виде линейного массива, размером в 256 элементов
  2. Чтение данных из структуры итеративным и "хеш" способом.
  3. Удаление данных из структуры
  4. Сортировка структуры числовым и строковым методами
  5. Реверсирование структуры (замена ключей значениями и наоборот)
  6. Работа с конфигурационными файлами (CFG) в ASCCII режиме
  7. Работа с конфигурационными файлами (MPI) в двоичном режиме
  8. и другие

     Все вышеперечисленные методы и обеспечивают интерфейс, под названием MPI.

     Помимо этого, MPI определяет дополнительные особенности разработки программ:

  1. Связь между процедурами осуществляется с поддержкой кода и флагов возврата ret и retf соответственно, что позволяет контролировать статус выполнения процессов.
  2. Связь между приложениями DOS и Windows
  3. Связь между процедурами глобального уровня, уровня модуля и процедур

DISCLAIMER

     MPI - Это интерфейс, который распространяется по лицензии LGPL, поэтому мы не можем дать гарантий по надежности реализации интерфейса. Более подробную информацию см. в приложении A.

TERMS

Дейтаграмма и файл конфигурации

     Дейтаграмма - Это единица структуры, представляющая собой строку, состоящую из названия ключа (латинскими маленькими буквами), знака равенства "=" и значения ключа длиной не более 255 байт. Дейтаграммы могут находится в структуре, либо в файлах конфигурации. Допускается каждый элемент (ключ, знак равенства и значение обособлять пробельными символами). Например:

Name = Abalama

     В теле конфигурационного файла текстового формата дейтаграммы могут быть записаны в виде столбика (разделенные символами новой строки). Помимо дейтаграмм в файле могут присутствовать комментарии. Они бывают двух вариантов.

  1. Блок комментария (строки заключенные в квадратные скобки)
  2. Строка комментария (Строка, префиксом которой является знак "диез" - "#")

     Например

[ПримерБлокаКомментария]# Пример строки комментария

DESCRIPTION

     Модуль поставляется в виде не компилированного кода. Принципы работы каждого компонента (процедуры) модуля описываются в разделе Synopsis

REQUIREMENTS

Hardware requirements: Жесткий диск, объемом, достаточным для записи итогового файла.Оперативная память: 1MbТип процессора: Intel или любой совместимый с указаннымТип дисплея: VGA/SVGAТип клавиатуры: 101Key/PS2 Software requirements: Операционная система: MS-DOS 6.22, загруженная в область HMA, MS-WindowsЗагруженные драйверы: HIMEM.SYS, KBR101.COM, UNIVGA.COM Development requirements: Microsoft PDS 7.10Modules: CRC16 Standard 1.00 - Расчет CRC 16 стандартным методом Main 3.00 (MK/CV, Version class, AbsPath$)

COMMANDS

     Модуль в своей реализации предусматривает только вызовы, которые детально описываются в разделе Synopsis.

OPTIONS

     Опции детально описаны в разделе Synopsis.

NOTES

     Модуль MPI написан для выполнения в операционной системе MS-DOS. При использовании ее на других платформах следует использовать адаптированные реализации модуля для этих систем.

INTERFACE

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

CRC16STD 1.00

DECLARE FUNCTION CRC! (message$, init!)DECLARE FUNCTION reflect! (Value!, bitwidth!)DECLARE SUB tabinit (poly!)DECLARE FUNCTION shl! (Value!)DECLARE FUNCTION shr! (Value!)DECLARE FUNCTION shr1! (Value!)

MAIN 3.00

DECLARE FUNCTION CV& (Value$, bytes!)DECLARE FUNCTION mk$ (Value, bytes!)DECLARE FUNCTION Version.Convert$ (Value$, method$)DECLARE FUNCTION trim$ (Value$)DECLARE FUNCTION Exists! (FlN$, Par$)DECLARE FUNCTION format.date$ (FD$, dword$)DECLARE FUNCTION ValHex& (Strg$)

DIAGNOSTICS

     Модуль MPI 1.00 был протестирован на различных системах и до сих пор сбоев в ее работе обнаружено не было.

BUGS

     В настоящее время ошибок в работе модуля не обнаружено, но если вы обнаружили какие-либо ошибки, то вы сможете оказать свою помощь в их исправлении, отправив информацию об этом авторам продукта.

HISTORY

     06.06.2006 / Version 1.00- Первая, стартовая версия.

THANKS

     Мы, разработчики программы, выражаем благодарность всем тем, кто внес свой личный вклад в разработку:


Перевод:

Климов Дмитрий

Microsoft Corporation - за
предоставление платформы разработки - PDS

Группу компаний CountryCom & Excodess Telecom
за предоставление технической платформы

AUTHORS

     Serz Minus <minus@mail333.com> - programmer on chief; http://minus.fla-master.com

COPYRIGHTS

     Все права на этот продукт принадлежат их авторам и корпорации D&D. Эти права защищены американским и международным законодательством по правам авторской и коммерческой деятельности.

     Все права на продажу либо публичное использование исходного кода продукта принадлежат авторам, согласно лицензии GNU. См. приложение A

  1. Copyright © 1998-2006 D&D Corporation. All rights reserved
  2. Copyright © 1982-2005 Microsoft Corporation
  3. Copyright (C) 1989, 1991 Free Software Foundation, Inc. Temple Place, Suite 330, Boston, MA 02111-1307 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

  версия для печати