Фреймворк ManagedIrbis5

Введение. Установка. Примеры программ

Введение

Пакет ManagedIrbis5 представляет собой фреймворк для создания клиентских приложений для системы автоматизации библиотек ИРБИС64 на платформе Microsoft .NET 8.

Пакет не содержит неуправляемого кода и не требует irbis64_client.dll. Успешно работает на 32-битных и 64-битных версиях операционных систем Windows, Linux и Mac OS X.

Основные возможности пакета:

  • Поиск и расформатирование записей.

  • Создание и модификация записей, сохранение записей в базе данных на сервере.

  • Работа с поисковым словарем: просмотр термов и постингов.

  • Администраторские функции: получение списка пользователей, его модификация, передача списка на сервер, создание и удаление баз данных.

  • Импорт и экспорт записей в формате ISO 2709 и в обменном формате ИРБИС.

Поддерживаются Microsoft Visual Studio (в т. ч. Community Edition), начиная с версии 17.8 (2022), и сервер ИРБИС64, начиная с 2014. Более ранние версии Visual Studio будут выдавать ошибки, т. к. они не поддерживают .NET 8. Аналогично обстоит дело и с более ранними версиями сервера ИРБИС64.

Установка

ManagedIrbis5 загружен в централизованный репозиторий пакетов NuGet, поэтому можно установить его с помощью стандартной утилиты dotnet, входящей в поставку .NET:

dotnet add package ManagedIrbis5

Также можно установить пакет, скачав необходимые файлы с репозитория GitHub: https://github.com/amironov73/ManagedIrbis5

Кроме того, доступны ночные сборки на AppVeyor: https://ci.appveyor.com/project/AlexeyMironov/ManagedIrbis5/build/artifacts

Примеры программ

Ниже прилагается пример простой программы. Сначала находятся и загружаются 10 первых библиографических записей, в которых автором является А. С. Пушкин. Показано нахождение значения поля с заданным тегом и подполя с заданным кодом. Также показано расформатирование записи в формат brief.

using System;
using System.Threading.Tasks;

using ManagedIrbis;

using ManagedIrbis.Infrastructure;

using static System.Console;

#nullable enable

class Program
{
    static async Task<int> Main(string[] args)
    {
        try
        {
            await using var connection = ConnectionFactory.Shared
                .CreateConnection();

            connection.Host = args.Length == 0
                ? "127.0.0.1"
                : args[0];
            connection.Username = "librarian";
            connection.Password = "secret";

            var success = await connection.ConnectAsync();
            if (!success)
            {
                await Error.WriteLineAsync("Can't connect");
                return 1;
            }

            WriteLine("Successfully connected");

            // Ищем все книги, автором которых является А. С. Пушкин
            // Обратите внимание на двойные кавычки в тексте запроса
            var found = await connection.SearchAsync
                (
                    "\"A=ПУШКИН$\""
                );

            WriteLine($"Найдено записей: {found.Length}");

            // Чтобы не распечатывать все найденные записи,
            // отберем только 10 первых
            foreach (var mfn in found[..10])
            {
                // Получаем запись из базы данных
                var record = await connection.ReadRecordAsync(mfn);

                // Извлекаем из записи интересующее нас поле и подполе
                var title = record.FM(200, 'a');
                WriteLine($"Title: {title}");

                // Форматируем запись средствами сервера
                var description = await connection.FormatRecordAsync
                    (
                        "@brief",
                        mfn
                    );
                WriteLine($"Биб. описание: {description}");

                WriteLine(); // Добавляем пустую строку
            }

            // Отключаемся от сервера
            await connection.DisposeAsync();
            WriteLine("Successfully disconnected");
        }
        catch (Exception exception)
        {
            WriteLine(exception);
            return 1;
        }

        return 0;
    }
}

Совместимость с предыдущими версиями

Пятая версия фреймворка ManagedIrbis имеет ряд особенностей, делающей ее несовместимой с предыдущими версиями.

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

Благодарности

Автор выражает благодарность:

  • Ивану Батраку (СФУ), протестировавшему библиотеку на совместимость с разными версиями ИРБИС-сервера;

  • Шувалову Арсению Валентиновичу (Саратовская государственная консерватория им. Л. В. Собинова), выявившему ошибки в библиотеке;

  • Артёму Васильевичу Гончарову (Научная музыкальная библиотека Санкт-Петербургской Консерватории им. Н. А. Римского-Корсакова), выявившему некоторые досадные ошибки в библиотеке.

Лицензия

Пакет ManagedIrbis5 распространяется по лицензии MIT:

Данная лицензия разрешает лицам, получившим копию данного программного обеспечения и сопутствующей документации (в дальнейшем именуемыми «Программное обеспечение»), безвозмездно использовать Программное обеспечение без ограничений, включая неограниченное право на использование, копирование, изменение, слияние, публикацию, распространение, сублицензирование и/или продажу копий Программного обеспечения, а также лицам, которым предоставляется данное Программное обеспечение, при соблюдении следующих условий:

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

ДАННОЕ ПРОГРАММНОЕ ОБЕСПЕЧЕНИЕ ПРЕДОСТАВЛЯЕТСЯ «КАК ЕСТЬ», БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ, ЯВНО ВЫРАЖЕННЫХ ИЛИ ПОДРАЗУМЕВАЕМЫХ, ВКЛЮЧАЯ ГАРАНТИИ ТОВАРНОЙ ПРИГОДНОСТИ, СООТВЕТСТВИЯ ПО ЕГО КОНКРЕТНОМУ НАЗНАЧЕНИЮ И ОТСУТСТВИЯ НАРУШЕНИЙ, НО НЕ ОГРАНИЧИВАЯСЬ ИМИ. НИ В КАКОМ СЛУЧАЕ АВТОРЫ ИЛИ ПРАВООБЛАДАТЕЛИ НЕ НЕСУТ ОТВЕТСТВЕННОСТИ ПО КАКИМ-ЛИБО ИСКАМ, ЗА УЩЕРБ ИЛИ ПО ИНЫМ ТРЕБОВАНИЯМ, В ТОМ ЧИСЛЕ, ПРИ ДЕЙСТВИИ КОНТРАКТА, ДЕЛИКТЕ ИЛИ ИНОЙ СИТУАЦИИ, ВОЗНИКШИМ ИЗ-ЗА ИСПОЛЬЗОВАНИЯ ПРОГРАММНОГО ОБЕСПЕЧЕНИЯ ИЛИ ИНЫХ ДЕЙСТВИЙ С ПРОГРАММНЫМ ОБЕСПЕЧЕНИЕМ.

Класс Connection

Класс Connection - “рабочая лошадка”. Он осуществляет связь с сервером и всю необходимую перепаковку данных из клиентского представления в сетевое.

Экземпляр клиента создается фабрикой:

using ManagedIrbis

var connection = ConnectionFactory.Shared.CreateConnection();

Поле

Тип

Назначение

Значение по умолчанию

Host

string

Адрес сервера

"127.0.0.1"

Port

int

Порт

6666

Username

string

Имя (логин) пользователя

null

Password

string

Пароль пользователя

null

Database

string

Имя базы данных

"IBIS"

Workstation

char

Тип АРМа (см. таблицу ниже)

'C'

Типы АРМов

Обозначение

Тип

Константа

'R'

Читатель

READER

'C'

Каталогизатор

CATALOGER

'M'

Комплектатор

ACQUISITIONS

'B'

Книговыдача

CIRCULATION

'K'

Книгообеспеченность

PROVISION

'A'

Администратор

ADMINISTRATOR

Классы Record, Field и SubField

Классы Record, Field и SubField предназначены для создания и манипуляции записями, полями и подполями соответственно в клиентском представлении. Они также отвечают за перекодирование записей из серверного представления в клиентское и обратно.

Record

Каждый экземпляр класса Record соответствует одной записи в базе данных ИРБИС и имеет следующие свойства:

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

  • Mfn – порядковый номер записи в базе данных. Для вновь созданных записей 0. После отправки записи на сервер поле Mfn выставляется автоматически. Диапазон значений для MFN: от 1 до 4294967295. Обратите внимание, при реорганизации базы данных MFN записи может измениться!

  • Status – состояние записи: удалена, отсутствует и т. д. Для вновь созданных записей 0. После отправки записи на сервер поле Status выставляется автоматически. Обратите внимание, при реорганизации базе данных логически удалённые записи могут пропасть из неё.

  • Version – номер версии записи. Для вновь созданных записей 0. При каждой отправке записи на сервер поле version выставляется автоматически. Поле Version используется сервером ИРБИС64 для отслеживания конфликтов одновременного обновления записей несколькими клиентами. Обратите внимание, при реорганизации базе данных её версия может измениться!

  • Fields – запись содержит произвольное количество полей. Технически их может быть 0, но на практике это означает сбой системы.

При отправке записи на сервер ИРБИС64 тот отсылает обратно клиенту эту же запись со всеми модификациями, которые были проведены над ней сценарием autoin.gbl. При этом могут измениться любые поля записи, а также её статус и версия.

Атрибуты в виде таблицы:

Поле

Тип

Назначение

Database

string

Имя базы данных, из которой загружена данная запись.

Mfn

int

Номер записи в мастер-файле.

Status

int

Статус записи: логически удалена, отсутствует (см. ниже).

Version

int

Номер версии записи.

Fields

List<>

Список полей записи.

Статус записи: набор флагов

Имя

Число

Значение

LogicallyDeleted

1

Логически удалена (может быть восстановлена)

PhysicallyDeleted

2

Физически удалена (не может быть восстановлена)

Absent

4

Отсутствует

NonActualized

8

Не актуализирована

NewRecord

16

Первый экземпляр записи

Last

32

Последняя версия записи

Locked

64

Запись заблокирована на ввод

AutoinError

128

Ошибка в Autoin.gbl.

FullTextNotActualized

256

Полный текст не актуализирован.

Класс Record содержит следующие методы:

TO BE DONE

Field

Поле записи характеризуется числовой меткой в диапазоне от 1 до 2147483647 (на практике встречаются коды от 1 до 9999) и содержит значение до первого разделителя (опционально) и произвольное количество подполей (см. класс SubField).

Стандартом MARC у полей предусмотрены также два односимвольных индикатора, но ИРБИС вслед за ISIS их не поддерживает.

Кроме того, стандарт MARC предусматривает т. наз. “фиксированные” поля с метками от 1 до 9 включительно, которые не должны содержать ни индикаторов, ни подполей, но имеют строго фиксированную структуру. ИРБИС такие поля обрабатывает особым образом только в ситуации импорта/экспорта в формат ISO2709, в остальном же он их трактует точно так же, как и прочие поля (которые стандарт называет полями переменной длины).

Стандартом MARC предусмотрены метки в диапазоне от 1 до 999, все прочие являются самодеятельностью ИРБИС. Поля с нестандартными метками не могут быть выгружены в формат ISO2709.

Хотя технически поле может содержать одновременно и значение до первого разделителя, и подполя, но стандартом такая ситуация не предусмотрена, на практике она означает сбой. В стандарте MARC поле содержит либо значение либо подполя.

Начиная с версии 2018, ИРБИС64 резервирует метку 2147483647 для поля GUID - уникального идентификатора записи.

Порядок подполей в поле важен, т. к. на этот порядок завязана обработка т. наз. “вложенных полей”.

Стандартом MARC предусмотрено, что внутри поля могут повторяться подполя с одинаковым кодом, однако, ИРБИС вслед за ISIS очень ограниченно поддерживает эту ситуацию (см. форматный выход &umarci).

Класс Field имеет следующие атрибуты:

Класс Field содержит следующие методы:

TO BE DONE

SubField

Подполе характеризуется односимвольным кодом (как правило алфавитно-цифровым A-Z, 0-9, но бывают подполя с экзотическими кодами вроде !, ( и др.) и содержит строковое значение (технически может быть пустым, но на практике пустое значение означает сбой).

Коды подполей не чувствительны к регистру. Как правило, ИРБИС приводит коды к верхнему регистру, но это не точно. :)

ИРБИС трактует код подполя ‘*’ как “значение до первого разделителя либо значение первого по порядку подполя” (смотря по тому, что присутствует в записи).

Поле

Тип

Назначение

code

string

Код подполя (односимвольный!)

value

string

Значение подполя

Класс SubField содержит следующие методы:

TO BE DONE

Прочие (вспомогательные) классы и функции

FoundLine

Строка найденной записи, может содержать результат расформатирования найденной записи. Содержит два поля:

Поле

Тип

Значение

Mfn

int

MFN найденной записи

Description

string

Результат расформатирования записи (опционально)

Пример применения см. раздел SearchParameters в данной главе.

SearchParameters

Параметры для поиска записей (метод Search). Содержит следующие поля:

Поле

Тип

Значение по умолчанию

Назначение

Database

string

null

Имя базы данных (опционально)

Expression

string

null

Выражение для поиска по словарю (быстрый поиск)

First

int

1

Индекс первой из возвращаемых записей

Format

string

null

Опциональный формат для найденных записей

MaxMfn

int

0

Максимальный MFN для поиска (опционально)

MinMfn

int

0

Минимальный MFN для поиска (опционально)

Number

int

0

Количество возвращаемых записей (0 = все)

Sequential

string

null

Выражение для последовательного поиска (медленный поиск)

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

Построитель запросов

Класс Search представляет собой построитель запросов в синтаксисе прямого поиска ИРБИС64. В нём имеются следующие статические методы:

  • All() – отбор всех документов в базе. Фактически строит запрос I=$.

  • Equals – поиск по совпадению с одним из перечисленных значений. Возвращает построитель запросов для последующих цепочечных вызовов.

Экземплярные методы:

  • And – логическое И. Возвращает построитель запросов для последующих цепочечных вызовов.

  • Not – логическое НЕ. Возвращает построитель запросов для последующих цепочечных вызовов.

  • Or – логическое ИЛИ. Возвращает построитель запросов для последующих цепочечных вызовов.

  • SameField – логический оператор “в том же поле”. Возвращает построитель запросов для последующих цепочечных вызовов.

  • SameRepeat – логический оператор “в том же повторении поля”. Возвращает построитель запросов для последующих цепочечных вызовов.

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

Функция

Поиск по

author

автору

bbk

индексу ББК

document_kind

виду документа

keyword

ключевым словам

language

языку текста

magazine

заглавию журнала

mhr

месту хранения

number

инвентарному номеру

place

месту издания (городу)

publisher

издательству

rzn

разделу знаний

subject

предметной рубрике

title

заглавию

udc

индексу УДК

year

году издания

Пример применения построителя запросов:

// TO BE DONE

Экспорт/импорт

Пакет ManagedIrbis5 содержит функции, необходимые для экспорта и импорта записей в как в текстовом формате, принятом в системах ИРБИС32 и ИРБИС64, так и в международном формате ISO2709.

Текстовый экспорт/импорт

Текстовый обменный формат специфичен для ИРБИС, он не поддерживается другими библиотечными системами.

Вот как выглядит типичный файл в обменном формате ИРБИС:

#920: SPEC
#102: RU
#101: rus
#606: ^AХУДОЖЕСТВЕННАЯ ЛИТЕРАТУРА (ПРОИЗВЕДЕНИЯ)
#919: ^Arus^N02  ^KPSBO^Gca
#60: 10
#961: ^ZДА^AШукшин^BВ. М.^GВасилий Макарович
#210: ^D1998
#610: РУССКАЯ ЛИТЕРАТУРА
#610: РАССКАЗЫ
#1119: 7ef4c9af-f1d3-4adc-981b-5012463155a1
#900: ^B03^C11a^Xm^Ta
#215: ^A528^3в пер.
#200: ^VКн. 3^AСтранные люди
#10: ^A5-86150-048-7^D80
#907: ^CПК^A20180613^BNovikovaIA
#461: ^CСобрание сочинений : в 6 кн.^FВ. М. Шукшин^GНадежда-1^H1998^Z1998^XШукшин, Василий Макарович^DМосква^U1
#903: -051259089
#910: ^A0^B1759089^DФ104^U2018/45^Y45^C20180607
#905: ^21^D1^J1^S1
*****

Функция ReadTextRecord определена следующим образом:

// TO BE DONE

Она принимает в качестве аргумента текстовый поток, считывает запись и возвращает её. Если достигнут конец потока, возвращается None. Вот как можно использовать эту функцию:

// TO BE DONE

Обратите внимание, что функция принимает любой вид текстового потока: не только файл, но и сокет, консоль, массив символов в оперативной памяти и т. д.

Функция WriteTextRecord, обратная ReadTextRecord, определена следующим образом:

// TO BE DONE

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

// TO BE DONE

Формат ISO2709

// TO BE DONE

// TO BE DONE

Indices and tables