hodza/BlackBox.Shkola.2014 huggingface dataset:
i21sys/Docu/ru/Windows.odc

i21sysWindows

DEFINITION i21sysWindows;

	PROCEDURE AlignTopLeft;
	PROCEDURE AlignTopRight;
	PROCEDURE SetPos (xnew, ynew: INTEGER);
	PROCEDURE SetSize (w, h: INTEGER);

END i21sysWindows.

Простые операции с окнами в ОС MS Windows.

Возможная команда меню:

MENU "Info"
	"&Open Log"	""	"StdLog.Open;i21sysWindows.AlignTopLeft"	""
END

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

PROCEDURE AlighTopLeft
Перемещает переднее окно в верхний левый угол экрана.

PROCEDURE AlignTopRight
Перемещает переднее окно в верхний правый угол экрана.

PROCEDURE SetPos (xnew, ynew: INTEGER)
Перемещает переднее окно в положение с указанными координатами (в пикселях) левого верхнего угла. Здесь речь о полном окне с учетом рамки.

PROCEDURE SetSize (w, h: INTEGER)
Устанавливает размеры переднего окна по горизонтали и вертикали в w и h пикселей, соответственно. Здесь речь о размере внутреннего видимого поля окна без учета рамки, полос прокрутки и т.п.
i21sys/Docu/ru/Национальные литеры в идентификаторах.odc

Поддержка национальных литер в идентификаторах в учебных сборках Блэкбокса

Речь о сборках Блэкбокса от проекта Информатика-21, способных поддерживать национальные алфавиты в идентификаторах. Для этого служат модули i21sysCharacters, i21sysLatin1, i21sysCyrillic и т.п. 


Где сосредоточено знание о литерах, допустимых в идентификаторах

Все служебные модули Блэкбокса, которые должны знать, какие литеры допустимы в идентификаторах, поправлены так, чтобы получать всё это знание из модуля i21sysCharacters. Другими словами, если, например, в каком-то модуле Блэкбокса диапазон допустимых литер задавался в явном виде перечислением в логическом выражении, то теперь там просто стоит обращение к соответствующей функции из модуля i21sysCharacters.
Сам модуль i21sysCharacters  интерфейсный и переадресует вызовы процедур модулю для конкретного национального алфавита, указанному в его списке импорта. 
Например, для поддержки кириллицы i21sysCharacters импортирует модуль i21sysCyrillic. 
Чтобы привести в действие соглашения оригинальной конфигурации Блэкбокса (в идентификаторах допускаются только литеры набора Latin-1), то нужно вместо i21sysCyrillic указать i21sysLatin1.

Модули i21sysCyrillic, i21sysLatin1 и другие, которые могут быть построены по их образцу для поддержки других национальных языков, формально автономны и могут, например, использоваться как независимые компоненты при работе в оригинальной конфигурации Блэкбокса. (Например, можно представить себе, что работа ведется в оригинальной конфигурации Блэкбокса, и в программах нужно обрабатывать текстовые данные с учетом специфики национальных алфавитов.)


Создание BlackBox.exe с поддержкой национального языка

Предположим, что по образцу i21sysCyrillic сделан модуль i21sys<National> для поддержки некоторого национального языка.
Тогда для создания BlackBox.exe нужно будет использовать следующие коммандеры.
Их лучше вызывать в рабочей папке (серверный режим Блэкбокса).

Не забыть сделать резервную копию Блэкбокса, прежде чем играть в эти игры!

1. Пишется/редактируется исходник модуля i21sys<National>, где сосредоточивается необходимая информация о национальном алфавите.

2. Исходник модуля i21sysCharacters редактируется так, чтобы в списке импорта фигурировал i21sys<National>.

3. Выполняется компиляция с помощью следующего коммандера:

DevCompiler.CompileThis  i21sys<National> i21sysCharacters Kernel HostFiles

4. Создается BlackBoxN.exe:

DevLinker.Link
BlackBoxN.exe := i21sys<National> i21sysCharacters Kernel$+ Files HostFiles StdLoader
1 Applogo.ico 2 Doclogo.ico 3 SFLogo.ico 4 CFLogo.ico 5 DtyLogo.ico
1 Move.cur 2 Copy.cur 3 Link.cur 4 Pick.cur 5 Stop.cur 6 Hand.cur 7 Table.cur

5. Блэкбокс закрывается.

6. Сохранив старый BlackBox.exe (например, переименовав его), скопировать вновь созданный BlackBoxN.exe в основную папку (если он был создан в отдельной рабочей папке) и переименовать на BlackBox.exe.

И можно запускать новый BlackBox.exe.

Если что-то пошло не так, достаточно вернуть на место старый BlackBox.exe.

-----------
info21@inr.ac.ru
2012-09-15
i21sys/Docu.Полезные сведения/О комментариях.odc

О комментариях в Компонентном Паскале

Комментарии в тексте программ на Компонентном Паскале оформляются составными скобками (* и *). Между ними может быть любой текст.

Комментарии могут быть вложенными. Например:

	(* (* это комментарий *) в другом комментарии *)

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

Полезно иметь в виду, что длинные комментарии можно прятать в так называемых складках (folds; см. меню Инструменты, группу команд, начиная с Создать складку и т.д., а также документацию к модулю StdFolds). 



________________
info21@inr.ac.ru
последние изменения: 2010-10-23
i21sys/Docu.Полезные сведения/О компиляции.odc

О компиляции

Ниже объясняется, как компилировать модуль в различных ситуациях.

1.
Пусть текст модуля находится в открытом документе Блэкбокса. 
Обычно текст модуля располагается в самом начале документа. 
Если это так, то для компиляции модуля достаточно нажать на клавиатуре Ctrl+K (латинское K, переключать с русской раскладки на латинскую не обязательно),
или из меню Разработка > Компилировать.
В этом случае компилятор проигнорирует все, что находится за текстом модуля  там удобно ставить коммандеры для вызова процедур модуля, хранить программные фрагменты и т.п.

2.
Если текст модуля находится в середине документа, то достаточно выделить мышкой начало модуля (например, дважды кликнуть по слову MODULE, с которого начинается текст модуля) и выполнить команду меню Разработка > Компилировать выделенное. Будет скомпилирован весь модуль.
Если это приходится делать часто, то лучше модифицировать меню, указав там нужную клавишу (keyboard shortcut) по стандартным правилам Блэкбокса. (При подготовке текстов с компилируемыми модулями удобно вставить такую команду в контекстное меню -- меню со зведочкой в конце файла Text/Rsrc/Menus.odc.)

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

DevCompiler.CompileThis i21sysIn i21sysInПримеры

После коммандера идёт список имён компилируемых модулей через пробелы или любые другие белые литеры. Заканчиваться список может, например, cпец. вьюшкой   (Ctrl+Shift+Q) или просто другим коммандером.
Если один из модулей не скомпилировался, то остальные модули не компилируются. 
В списке модулей важно учитывать связи по экспорту-импорту: импортирующий модуль должен стоять после импортируемого (т.к. компилировать импортирующий бессмысленно до компиляции импортируемого).

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

DevDebug.UnloadThis i21sysInПримеры i21sysIn

Но порядок выгрузки должен быть обратным к порядку компиляции.



________________
info21@inr.ac.ru
последние изменения: 2010-10-23
i21sys/Docu.Полезные сведения/О порядке процедур.odc

О порядке определения процедур в модуле

В Обероне/Компонентном Паскале есть одна тонкость, связанная с порядком следования процедур в модуле. Эта тонкость требует некоторого (впрочем, минимального) внимания со стороны программиста, но имеет то капитальное положительное следствие, что компилятор удается сохранить чрезвычайно быстрым (однопроходным).

Тонкость состоит в следующем. Предположим, что в модуле стоят подряд две процедуры (неважно, помечены они знаками экспорта или нет):
	
MODULE  Пример;
	
	PROCEDURE Первая ( x: INTEGER );
		VAR  
	BEGIN
		Вторая( x + 1 )
	END Первая;
	
	PROCEDURE Вторая ( y: REAL );
		VAR  
	BEGIN
		(* сделать что-нибудь *)
	END Вторая;
	
END  Пример.

Попытка скомпилировать этот модуль даст ошибку с сообщением "необъявленный идентификатор" после идентификатора Вторая в теле первой процедуры (выделен цветом).
Причина в том, что по правилам Компонентного Паскаля диапазон видимости идентификатора распространяется от точки его объявления до конца той структурной единицы (модуля или процедуры), в которой этот идентификатор объявлен. В данном случае идентификатор процедуры Вторая появляется в тексте после процедуры Первая и его диапазон видимости распространяется от заголовка процедуры Вторая до конца модуля. Соответственно та точка, где стоит вызов процедуры Вторая, находится за пределами диапазона видимости идентификатора Вторая, откуда и ошибка.

Обойти эту трудность позволяет т.наз. "упреждающее объявление" процедуры (forward declaration): скопируем заголовок процедуры Вторая перед процедурой Первая и пометим его значком ^ после ключевого слова PROCEDURE: 

MODULE  Пример;
	
	PROCEDURE^ Вторая ( y: REAL );

	PROCEDURE Первая ( x: INTEGER );
		VAR  
	BEGIN
		Вторая( x + 1 )
	END Первая;
	
	PROCEDURE Вторая ( y: REAL );
		VAR  
	BEGIN
		(* сделать что-нибудь *)
	END Вторая;
	
END  Пример.

Теперь модуль компилируется без ошибок. 

Важно, чтобы упреждающее определение совпадало с заголовком соответствующей процедуры (за исключением символа ^) литера в литеру. Проще всего это обеспечить простым копированием.

Вообще проектные решения такого рода  учитывая не только чисто технические, но и более широкие "социальные" аспекты такого феномена как язык программирования  достаточно нетривиальны, т.к. просчитать все, в том числе отдаленные последствия таких решений практически невозможно. 
Есть много примеров того, как простые и на первый взгляд очевидно разумные решения оборачиваются в конечном счете потерями, далеко перевешивающими тот выигрыш, который при принятии решения кажется очевидным. Учитывая, что добавить в язык программирования новую "фичу" легко, а устранить неудачную почти невозможно [это неоднократно подчеркивал Н.Вирт], оптимальной стратегией в этих вопросах следует считать здоровый консерватизм.



________________
info21@inr.ac.ru
последние изменения: 2010-10-23
i21sys/Docu.Полезные сведения/О точке с запятой.odc

О постановке точки с запятой в Компонентном Паскале


По сравнению со старым Паскалем, в Компонентном Паскале правила постановки точки с запятой немного упрощены. Теперь в конце любого оператора можно ставить точку с запятой  независимо от того, стоит ли за этим ключевое слово вроде END.

Пример:

	PROCEDURE Сорт* ( VAR a: ARRAY OF INTEGER );
		VAR  i: INTEGER;
	BEGIN
		FOR  i := 1  TO  LEN(a) - 1  DO
			Вставить(  );
		END;
	END Сорт;

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

Формально говоря, эта возможность обеспечена тем, что правила Компонентного Паскаля допускают пустые операторы, и считается, что между ; и END стоит такой пустой оператор, так что программа сохраняет корректность. 
По этой же причине в исполняемом теле процедуры может идти подряд несколько ;;; (и тогда считается, что между каждой парой ;; находится пустой оператор). Но в разделе объявлений это не допускается, т.к. там никаких операторов быть не может, в том числе и пустых.


________________
info21@inr.ac.ru
последние изменения: 2010-10-23; 2012-12-04
i21sys/Docu.Полезные сведения/Полезные сведения.odc

Полезные сведения о работе в системе Блэкбокс

Кусочки текста, выделенные синим цветом с подчеркиванием, работают как обычные гиперссылки на страничках в Сети: клик мышкой открывает соответствующий документ в отдельном окошке.

Опроцедурахимодулях (как вызывать процедуры и почему нет главных процедур)
Оподсистемах (правила хранения модулей)
Окомпиляции
Окомментариях
Оточкесзапятой
ОбиспользованииклавишиF5дляпечатиключевыхсловиззаглавныхбукв
Вводданныхспомощьюсредствмодуля(i21sys)In
Обиспользованиицветавпрограммах
Опорядкепроцедур
Оскладках

При первоначальном знакомстве с Блэкбоксом рекомендуется прочесть примеры в учебных сборках Блэкбокса.

См. также
Орабочихпапкахисерверномрежиме
Обзорподсистемыi21sys
Тексткакинтерфейс
ОциклеДейкстры

_______________
info21@inr.ac.ru
2010-09-26
i21sys/Docu.Работа с DLL/calling-from-C++.odc

Вызов DLL из C++
Microsoft Visual C++ 6.0
Напомним, что DLL можно загружать статически и динамически. Мы рассмотрим только динамическую загрузку.
Есть два способа импортировать функцию из DLL: (1) по имени; (2) по порядковому номеру в DLL.
Подобно процедуре, описанному в документе ВызовDLLизБлэкбокса, нужно выполнить следующие шаги:
 Загрузить DLL с помощью функции Windows API, называющейся LoadLibrary(). 
 Вызвать GetProcAddress() для получения указателя на функцию, которую нужно вызвать. 
 Когда DLL больше не нужна, выгрузить ее с помощью FreeLibrary().
Чтобы вызвать вышеуказанные функции Windows API functions, нужно вставить следующие директивы в начале программы:
#include <windows.h>
Пример, которыей использует anyname.dll, созданную в первом примере в СозданиеDLLвБлэкбоксе, может быть таким:

#include <iostream.h>
#include <windows.h>

int ( __stdcall *Add ) ( int, int );

void main( void )
{
	int a = 1, b = 3, c;

//  Get a handle to the DLL module:
	HINSTANCE dllInstance = LoadLibrary( "c:\!\anyname.dll" );

	cout << endl << "dllInstance = " << long( dllInstance ) << endl << endl;

	// If the handle is valid, try to get the function address:

	if ( dllInstance != NULL ) 
	{ 
		Add = ( int ( __stdcall* ) ( int, int ) )GetProcAddress(  dllInstance, "Add" );

		// If the function address is valid, call the function:
		if (Add != NULL) 
			c = ( *Add )( a, b ); 
		else 
			cout << "Error 1 : Add = NULL" << endl;

		// Free the DLL module.
  
		fFreeResult = FreeLibrary( dllInstance ); 
	}
	else
		cout << "Error 0 : the DLL file is not loaded " << endl;

	cout << "a = " << a << endl
		<< "b = " << b << endl
		<< "a + b = " << c << endl;

} // End main();
//==============================================
i21sys/Docu.Работа с DLL/creating-in-C++.odc

Создание DLL в C++
Общее замечание: подобно сказанному о доступе к COMMON-блокам в фортране, может понадобиться сделать косметические изменения к интерфейсам процедур в исходниках на C++, например, дописать дополнительные процедуры для доступа к глобальным переменным и т.п. 
Создание DLL в Microsoft Visual C++
Создадим новый Проект (File, New, Project). Дадим ему имя (скажем, project_name) и выберем ему тип как Win32 Dynamic-Link Library. 
В поле Location можно указать путь к папке, где будут сохраняться файлы проекта. Кликнем OK. 
Появится диалог, в котором выставим флажок A simple DLL project. (Не следует оставлять опцию по умолчанию An empty DLL project!)
Будут созданы все необходимые файлы, среди которых будет project_name.CPP,
в конце которого нужно вставить код для нужных процедур/функций.
Отметим те из них, которые должны появиться в списке экспорта DLL модификатором __declspec(dllexport)  [см. примеры ниже]. 
Если нужно, чтобы имена процедур в списке экспорта DLL оставались в минимальной степени искажены по сравнению с исходником, тогда следует включить модификатор extern "C" :

extern "C" __declspec(dllexport) void __stdcall swap( int& a, int& b )
{
	int temp;
	temp = a;
	a = b;
	b = temp;
}

Заметим также, что здесь требуется выполнение соглашений stdcall.
Наконец, нажмем кнопку Build  (F7).
NB Если вместо этого нажать Compile (Ctrl + F7), то появится следующее сообщение об ошибке: fatal error C1083: Cannot open precompiled header file: 'Debug/ project_name.pch': No such file or directory].
Будут созданы два файла project_name.dll и project_name.lib в папке \project_nameта\Debug  или \project_name\Release.
Второй файл (*.lib) подобен символьному файлу, который автоматически создается в Блэкбоксе.
Сигнатура для вышеприведенной процедуры в Компонентном Паскале будет такой:
	PROCEDURE swap* ( VAR a, b: INTEGER );
Если процедура на C++ модифицирует массив, например,
extern "C" __declspec(dllexport) void __stdcall sort( int* a, int len )
то соответствующая сигнатура в Блэкбоксе будет такой:

	PROCEDURE sort* ( VAR a: ARRAY [untagged] OF INTEGER, len: INTEGER );
i21sys/Docu.Работа с DLL/Dependency-Walker.odc

Использование программы Dependency Walker
Программа Dependency Walker позволяет исследовать DLL, в частности, определить имена и порядковые номера процедур в списке экспорта DLL. 
(В системе Win 2000, DLL можно также исследовать с помощью Quick View; эта опция недоступна в Win XP.)
Программа Dependency Walker имеется в составе Microsoft Visual Studio.
Она также доступна бесплатно в виде zi-файла с сайта http://www.dependencywalker.com/.
Просто раззипуйте ее в любую папку и запустите depends.exe. Можно связать depends.exe с файлами *.dll для автоматического вызова двойным кликом по файлу DLL.
Запустите depends.exe, выполните команду меню File, Open, и найдите нужную DLL.
В качестве примера можно открыть KERNEL32.DLL в папке the c:\winnt\system32. 
Программа Dependency Walker покажет 5 окон (здесь используется версия 2.1):
	
 
Верхнее левое окно содержит имя открытого файла DLL вместе с именами DLL, которые он использует. 
Важное окно находится справа, второе сверху. В нем показаны точные имена функций в столбце Function.
NB Если DLL была написана на C++, то важно, чтобы кнопка [с++] (6-я слева на полоске инструментов; Undecorate C++ Functions) была НЕ нажата!
Столбец Ordinal в том же окне показывает порядковые номера экспортируемых функций. В ниижнем окне дается список обнаруженных ошибок. 

Полные пути для DLL можно видеть, нажав кнопку [c:\] (5-я слева на полоске инструментов).
i21sys/Docu.Работа с DLL/Intro.odc

Введение в DLL
DLL (Dynamic Link Library)  это файл с расширением *.dll , который содержит выполняемый код для набора процедур. 
DLL содержит список экспорта, в котором для каждой процедуры даны:
	ее имя  чувствительная к регистру цепочка литер расширенной кодировки ASCII;
	ее порядковый номер  целое число >=1, которое однозначно идентифицирует фукнцию из DLL. 
NB Две процедуры в DLL могут иметь одинаковое имя, но у них всегда разные порядковые числа.
Компиляторы обычно допускают создание DLL вместо обычного EXE. См. документацию к конкретному компилятору.
В данном документации обсуждаются Блэкбокс, PowerStation Fortran и MS Visual C++.
Соглашения о передаче параметров
Процедуры в DLL могут придерживаться одного из двух соглашений о передаче параметров  ccall или stdcall (имена могут чуть отличаться в разным системах программирования).
По умолчанию Блэкбокс использует соглашения stdcall, а C/C++  соглашения ccall; поведение по умолчанию может быть изменено с помощью специальных опций.
Важно правильно указать соглашение для каждой процедуры, создавая и используя DLL.
Функции Windows API используют соглашение stdcall.
Имена и порядковые номера
Функции из DLL могут быть идентифицированы либо по имени, либо по их порядковым числам.
Имена функций в DLL могут отличаться от их имен в исходнике. Это зависит от конкретного компилятора. Поэтому для использования функции из DLL важно точно определить ее имя.
Чтобы определить точные имена экспортированных функций в DLL, можно использовать бесплатную утилиту Dependency Walker (depends.exe; http://www.dependencywalker.com/); см. этотдокумент.
В ОС Windows NT можно сделать правый клик по файлу DLL и выбрать Quick View.
Загрузка DLL
DLL могут быть загружены двумя способами: статически и динамически. 
Статическая загрузка означает, что DLL загружается автоматически при запуске программы, ее вызывающей. Это более простой способ и обычно обеспечиватеся компилятором и компоновщиком.
Динамическая загрузка означает, что DLL загружается во время выполнения программы, и выгружается после использования. в то время как основная программа продолжает работать. Это более гибкий способ, но требует обращений к функциям Windows API во время выполнения:
 LoadLibrary() для загрузки DLL в память;
 GetProcAddress() для получения указателя на нужную функцию из DLL; 
 FreeLibrary() для выгрузки DLL из памяти, когда она больше не нужна.

Чтобы узнать, какие DLL загружены, можно выполнить (Start, Run...) msinfo21 и выбрать Software Environment, Loaded Modules.
i21sys/Docu.Работа с DLL/Map.odc

Работа с унаследованным ПО через DLL
Данный материал был первоначально подготовлен на английском языке для физической аудитории на cовещаниии Oberon Day @ CERN, проведенного в марте 2004 г. в CERN, Женева.
(С) Ф.В.Ткачев и С.О.Чумаков, 2004.
(С) Русский перевод для проекта Информатика-21: Ф.В.Ткачев, 2009.
Учитывая историю фортрана в научном мире, физикам при работе с Блэкбоксом важно иметь возможность использовать имеющиеся библиотеки на фортране (а также C/C++). Наплатформе Windows простейший способ для этого без полного переписывания исходников на фортране/C/C++ состоит в перекомпиляции их в т.наз. DLL. 
DLL  это файл с расширением *.dll, который содержит исполняемый код для набора процедур (в какой-то степени подобный модулям Компонентного Паскаля). Поскольку DLL являются стандартным механизмом на платформе Windows любой приличный компилятор имеет соответствующую опцию. Может понадобиться произвести косметические модификации для интерфейсов процедур, компилируемых в DLL. В большинстве случаев это не вызывает затруднений, хотя в общем случае здесь требуется хорошее понимание соответствия типов и параметров в разных языках, правил выравнивания полей записей и т.п.

	ВведениевDLL
		ИспользованиепрограммыDependencyWalkerдляисследованияDLL

	Создание DLL для использования из Блэкбокса: 
		вфортране, 
		C++,
		вБлэкбоксе (для полноты).

	Вызов DLL, созданных в фортране или C++ из Блэкбокса.

Блэкбокс тоже допускает создание DLL, так что алгоритмы, разработанные в Блэкбоксе и обладающие соответствующими свойствами безопасности (автоматическое управление памятью), могут быть предоставлены в форме DLL для использования из внешних программ, написанных на других языках (фортран, C/C++ и т.д.). Предполагается, что гуру, способные работать с внешними DLL из, скажем, C++, не нуждаются в советах (некоторые  замечания можно найти здесь).