Difference between revisions of "I2Rpc"

From i2Rest
Jump to: navigation, search
m (→‎Контекст сессии)
(→‎I2RC000005 изменение контекста вызова)
Line 476: Line 476:
  
 
==I2RC000005 изменение контекста вызова==
 
==I2RC000005 изменение контекста вызова==
 +
Команда I2RC000005 позволяет клиенту выполнить установку/изменение клиентского [[#session_context|контекста сессии]]. Данный вызов сохраняет/заменяет содержимое области данных клиентского контекста, эти данные передаются серверу i2Rpc при всех последующих вызовах программ командой I2RC000002.
 +
 +
Вызов команды I2RC000005 не изменяет непосредственно окружение в клиентской сессии. При этом вызове только сохраняется новое содержимое области данных контекста сессии, и если это содержимое будет отличаться от того, которое было использовано ранее при вызове программы в сессии (команда I2RC000002), то перед следующим вызовом программы будет предварительно вызван вызван user exit, указанный в параметре конфигурации <code>state{full|less}.contextSetExit</code>
 +
 +
Структура параметров
 +
 +
// I2RC000005 - SetContext
 +
typedef struct i2R_SetContext_t {
 +
    // Input
 +
    void *connection;
 +
    int contextLength;
 +
    char *contextData;
 +
} i2R_SetContext_t;
 +
 +
D i2RSetContext  DS                  Qualified Inz
 +
D  connection                    *
 +
D  contextLength                10I 0
 +
D  contextData                    *
 +
 +
Описание параметров
 +
* '''connection''' полученный ранее handler соединения
 +
* '''contextLength''' длина параметра contextData
 +
* '''contextData''' указатель на данные контекста
  
 
=Трассировка RPC вызовов=
 
=Трассировка RPC вызовов=

Revision as of 18:04, 25 July 2025

i2Rpc - инструмент удаленного вызова программ на платформе IBMi. Позволяет вызывать программы в отдельном задании, как локально, так и на удаленном сервере IBMi.

Архитектура

i2Rpc server


Сервер i2Prc

Расположенный на сервере IBMi экземпляр сервера i2Rpc - это многопоточный сервер, выполняющий прием и обработку запросов на выполнение удаленных вызовов программ от Клиентов i2Rpc. Сервер взаимодействует с клиентами i2Rpc по частному протоколу, построенному поверх протокола TCP/IP. Сервер обрабатывает запросы клиентов на подключение, и обеспечивает соединение клиентов с сессиями, выполняющими обслуживание удаленных вызовов программ.

Для обслуживания клиентов сервера i2Rpc, сервер поднимает листенер входящих TCP/IP или UNIX соединений. Номер порта или адрес unix сокета входящих запросов определяется в параметрах конфигурации сервера. Если используется TCP/IP порт, то сервер может принимать запросы, поступающие от клиентов, расположенных на других серверах IBMi, имеющих доступ к данному серверу. Использование UNIX соединений позволяет ограничить область видимости экземпляра сервера i2Rpc только данным сервером IBMi.

Для подключения сессий, сервер i2Rpc открывает листенер UNIX соединений на локальном unix сокете. Сервер запускает сессии командой SBMJOB, при этом задание сессии уведомляется об адресе, который слушает листенер сервера для обработки соединений с сессиями. После старта, сессия подключается к серверу и переходит в состояние ожидания заданий на обработку клиентских RPC запросов.

Клиенты i2Rpc

Клиентом i2Rpc может являться любая программа для IBMi, которой требуется удаленное выполнение другой программы на сервере IBMi, на котором запущен экземпляр сервера i2Rpc. Для взаимодействия с сервером i2Rpc, клиенту предоставляется специальное API, реализуемое программой i2RpcAPI. i2RpcAPI имеет несколько вариантов использования, которые определяются в первом параметре программы i2RpcAPI. Основные варианты использования:

  • I2RC000001 - подключение к серверу i2Rpc и получение хэндлера соединения
  • I2RC000002 - удаленный вызов программы в рамках данного соединения
  • I2RC000004 - закрытие соединения с сервером i2Rpc, освобождение хэндлера

В зависимости от варианта использования, клиентская программа должна передать в i2RpcAPI соответствующие структуры данных, содержащие параметры того или иного действия. Параметры действия I2RC000002 спроектированы таким образом, чтобы минимизировать доработки программ при переходе от локального вызова к удаленному. Фактически, вместо передачи списка параметров при локальном вызове, в RPC нужно передать такой же список параметров, и сопроводить его формальным описанием этого списка - указать количество параметров и их размерность

Пул сессий i2Rpc

Непосредственное выполнение удаленных вызовов программ происходит в Сессиях i2Rpc. Сессия - это отдельное однопоточное задание, которое подключается к Серверу i2Rpc и получает от сервера соединение с клиентом, от которого поступил запрос на RPC вызов.

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

Существуют два вида сессий i2Rpc:

  • statefull сессия (SF сессия) - задание, в рамках которого выполняются запросы только одного клиента. В задании сохраняются неизменными все свойства окружения вызова, сформированные клиентом - library list, activation groups, блокировки объектов и записей, объекты в QTEMP и т.д. При подключении клиента к i2Rpc серверу в SF режиме, сервер запускает отдельное задание, в котором выполняются все RPC вызовы от данного клиента. При первом вызове RPC, сервер передает в задание сессии дескриптор клиентского соединения, и дальшейшее взаимодействие клиента с i2Rpc происходит непосредственно между клиентом и сессией, без привлечения сервера i2Rpc. Сервер отслеживает активность клиентского соединения и сессии. В случае отключения клиентского соединения, SF сессия будет автоматически остановлена. И наоборот - если задание сессии будет прекращено тем или иным способом, сервер закроет соедиение с клиентом
  • stateless сессия (SL сессия) - задание, которое может обслуживать RPC вызовы нескольких клиентов. Сервер i2Rpc не гарантирует, что обращения определенного клиента к SL сессии будут выполняться в рамках одного и того же задания. Таким образом, клиент SL соединения не может рассчитывать на сохранение окружения в последовательных вызовах RPC. При обращении клиента к SL сессии, сервер определяет свободное задание из пула запущенных SL заданий, при необходимости стартует новое задание SL сессии, и передает ему дескриптор клиентского соедиения. SL сессия, после завершения обработки RPC запроса (запросов) данного клиента, возвращается в пул доступных SL сессий, и может быть использована в дальнейшем для обработки запросов от других клиентов. В параметрах настройки сервера i2Rpc может быть определен размер пула SL сессий - минимальное и максимальное количество заданий. Сервер автоматически поддерживает указанную ширину пула, контролируя завершение заданий и запуская новые задания по мере необходимости.

Контекст сессии

Контекст сессии - это небольшой объем клиентских данных, который передается в сессию вместе с каждым удаленным вызовом программ. API клиента имеет интерфейс, позволяющий установить/изменить содержимое контекста сессии. В свою очередь, содержимое контекста сессии анализируется на стороне сессии непосредственно перед вызовом пользовательских программ. В случае, если контекст сессии изменен по отношению к предыдущему вызову, то до вызова программы будет выполнен вызов специальной user exit программы, которая может сформировать/изменить новое пользовательское окружение (например изменить список библиотек или содержимое объектов в библиотеке QTEMP). Для stateless и statefull сессий можно установить свое имя user exit программы - оно указывается в параметрах конфигурации сервера --stateless.contextSetExit или --statefull.contextSetExit

Логирование и трассировка

В контексте данного проекта, разделяются понятия Логирование и Трассировка.

Логированием называется протоколирование событий, возникающих в процессе работы сервера и сессий. Для регистрации таких событий может быть использован job log задания, его spool файл QPRINT, или сервер syslog, запущенный на локальном сервере IBMi или на удаленной машине.

Трассировка - это протоколирование параметров RPC вызовов, которое выполняется отдельной user exit программой. Данная user exit программа может быть вызвана до и/или после непосредственного вызова сессией программы, обрабатывающей RPC запрос. По сути трассировка - это прикладное протоколирование вызовов RPC процедур, выполняемое пользовательским user exit.

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

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

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

Установка i2Rpc

Сервер i2Rpc устанавливается как лицензионое программное обеспечение. Для установки:

  1. Загрузите файл i2Rpc_Install.ZIP
  2. Скопируйте файл в папку на IFS сервера IBMi
  3. Откройте сессию эмулятора терминала и выполните команду
    1. CHGCURDIR <Папка куда скопирован файл i2Rpc_Install.ZIP>
      Система выдаст сообщение "Current directory changed."
    2. QSH CMD('jar xMvf i2Rpc_Install.ZIP')
      Данная команда распакует SAVF из архива, будет выдано сообщение "inflated: I2RPCINST.SAVF"
    3. CRTSAVF FILE(QTEMP/I2RPCINST)
      File I2RPCINST created in library QTEMP.
    4. CPYFRMSTMF FROMSTMF(I2RPCINST.SAVF) TOMBR('/qsys.lib/qtemp.lib/I2RPCINST.file') MBROPT(*REPLACE)
      "Stream file copied to object."
    5. RSTLICPGM LICPGM(0AI2R11) DEV(*SAVF) SAVF(QTEMP/I2RPCINST)
      *PGM objects for product 0AI2R11 option *BASE release *FIRST restored.
  4. Проверьте установку продукта i2Rpc:
    1. WRKLICINF PRDID(0AI2R11)
      Будут отображены сведения об установленном лицензионном продукте i2Rpc
    2. WRKOBJPDM I2RPCPROD
      Появится список объектов в библиотеке продукта I2RPCPROD

Настройка сервера

Параметры функционирования сервера i2Rpc задаются в конфигурационном файле, имеющем формат JSON. Имя файла указывается в параметрах старта сервера. Параметры сервера, заданные в json файле, могут быть переопределены непосредственно в командной строке запуска. Например:

call i2rpcg parm('--config=config.json' '--stateless.minJobs=1' '--stateless.maxJobs=1')

В этой команде запуска сервера параметры конфигурации заданы в файле config.json, при этом параметры stateless.minJobs и stateless.maxJobs переопределены на уровне командной строки

Содержимое файла конфигурации сервера - текст в кодировке utf-8, представляющий собой json объект. Текст может содержать C-образные комментарии, например

// Это комментарий, действует до конца строки

/* Это комментарий, действует пока не закрыт */

Полный перечень параметров сервера

Все параметры конфигурации разбиты на отдельные секции:

  • gateway - общие параметры сервера, такие как параметры логирования, адрес листенера сервера и прочие
  • session - общие параметры сессий
  • stateless - параметры настройки stateless сессий
  • statefull - параметры настройки statefull сессий
  • logger - параметры настройки пользовательской трассировки

Секция gateway

  • debugIdentity - идентификатор логирования, указываемый в протоколах syslog, по умолчанию - I2RPCG
  • debugLevel - уровень логирования. Возможные значения EMERG, ALERT, CRIT, ERR, ERROR, WARNING, NOTICE, INFO, DEBUG, по умолчанию ERROR
  • debugFacility - идентификатор источника сообщений в syslog. Возможные значения ERN, USER, MAIL, DAEMON, AUTH, SYSLOG, LPR, NEWS, UUCP, CRON, AUTHPRIV, FTP, LOCAL0, LOCAL1, LOCAL2, LOCAL3, LOCAL4, LOCAL5, LOCAL6, LOCAL7, по умолчанию - LOCAL0
  • debugProtocol - протокол логирования. Определяет способ логирования сообщений сервером. Возможные значения - UDP, TCP (отправка сообщений на syslog сервер UDP или TCP), STDOUT, STDERR (печать в spool файл), JOBLOG (вывод в job log задания). По умолчанию - UDP
  • syslogHost, syslogPort - параметры сервера логирования, если используется протокол UDP или TCP. По умолчанию "syslog" и "514" соответственно
  • link - имя файла на файловой системе IFS, которое используется в качестве unix сокета, на котором листенер сервера "слушает" обращения клиентов i2Rpc. Не используется совместно с параметром port. По умолчанию - ""
  • port - номер порта, на котором листенер сервера "слушает" обращения клиентов i2Rpc по протоколу TCP. Не используется совместно с параметром link. Обязательно для заполнения, если не указан параметр link. Если указан параметр port, листенер i2Rpc "слушает" обращения клиентов по адресу 0.0.0.0:<port>
  • maxDescriptors - максимальное количество файловых дескрипторов, доступных серверному заданию i2Rpc. Операционная система IBMi по умолчанию ограничивает количество файловых дескрипторов, доступных заданию, значением 200. Серверу i2Rpc требуется минимум 2 файловых дескриптора на каждого подключенного клиента, и по 2 дескриптора на каждую подключенную сессию. Рекомендуется указывать значение maxDescriptors, которое будет достаточным для обслуживания планируемого количества клиентов и сессий.

Секция session

  • debugIdentity, debugLevel, debugFacility, debugProtocol, syslogHost, syslogPort - параметры логирования, аналогичные описанным выше в секции gateway
  • link - линк (unix сокет), через который общаются сервер и сессии. По умолчанию формируется в виде /tmp/I2R@<port>.do_not_delete, где port - номер порта gateway. Сервер и сессии должны иметь доступ к указанному ресурсу. Удаление линка в момент работы сервера ЗАПРЕЩЕНО
  • maxLoggerQueueSize - Максимальная длина очереди отправки сообщений в прикладную трассировку (общая длина всех неотправленных сессией сообщений, в байтах). При превышении отправка сообщений в трассировщик останавливается

Секция stateless

  • job, user, profile - имя работы, пользователя и профайл запускаемыx stateless сессий.
Если что-то не указано, по умолчанию используются параметры из серверного задания. То есть, если что-то из job, user, profile не указаны, и например запущенное задание данного сервера i2Rpc - 123456/I2RUSER/I2RPCG, работает под профилем I2RPRF, то stateless сессии будут запускаться под профилем I2RPRF, и будут иметь имя NNNNNN/I2RUSER/I2RPCG
  • submit - команда запуска stateless сессии.
Указывается шаблон команды SBMJOB, которую сервер будет использовать для запуска новых stateless сессий. Можно указать любые параметры команды SBMJOB, за исключением параметра CMD. Параметр CMD формируется сервером самостоятельно
В шаблоне команды можно использовать следующие макроподстановки - при формировании команды данные макроподстановки будут заменены на соответствующие параметры конфигурации
  • ${gateway.link}
  • ${gateway.debugLevel}
  • ${gateway.debugFacility}
  • ${gateway.debugProtocol}
  • ${gateway.syslogHost}
  • ${gateway.syslogPort}
  • ${session.debugLevel}
  • ${session.debugFacility}
  • ${session.debugProtocol}
  • ${session.syslogHost}
  • ${session.syslogPort}
  • ${stateless.job}
  • ${stateless.user}
  • ${stateless.profile}
  • ${stateless.init}
По умолчанию используется значение:
SBMJOB JOB(${stateless.job}) USER(${stateless.user})
  • init - команда инициализации задания сессии. Будет выполнена первой командой в сессии, сразу после запуска задания
По умолчанию *NONE - команда инициализации не выполняется
  • submitTimeout - время ожидания готовности задания сессии на стороне сервера (мкс).
Если после запуска сессии прошло указанное время, но сессия не подключилась к серверу, то считается что сессия не стартовала
По умолчанию = 5000000, (5 секунд)
  • jobTimeout - время неактивности (мкс).
Если сессия не получает запросов в течение указанного времени, она будет завершена
По умолчанию = 600000000 (10 минут)
  • minJobs - минимальное количество stateless сессий.
Указанное количество запускается при старте сервера, и далее количество stateless сессий не опускается ниже данного значения. В подсчет количества сессий принимаются также запущенные но еще не подключившиеся к серверу задания, у которых не истекло время submitTimeout
По умолчанию 0
  • maxJobs - максимальное количество stateless сессий, 0 - не ограничено
По умолчанию 0 - не ограничено
  • watermark - пороговый уровень запуска stateless сессий
Пока количество клиентов, ожидающих обработки своего запроса, не превысит указанное значение, сервер не будет запускать новые stateless сессии
По умолчанию 0, то есть новая stateless сессия будет запускаться каждый раз при поступлении нового коннекта от stateless клиента
  • batchCalls - количество запросов от одного клиента, которые может обработать сессия без переключения на другого stateless клиента.
Если от клиента поступило меньше чем batchCalls запросов, сессия ждет batchCallTimeout и переключается на следующего клиента
По умолчанию 0, то есть сессия переключается на следующего клиента сразу после обработки очередного запроса
  • batchCallTimeout - используется совместно с параметром batchCalls
Определяет время ожидания очередного запроса от одного и того же клиента в рамках обработки batchCalls запросов
Если от клиента поступило меньше чем batchCalls запросов, но с момента последнего запроса прошло больше чем batchCallTimeout микросекунд, сессия возвращается в пул свободный сессий и может быть использована для обработки запросов другого клиента
По умолчанию 0
  • sendTimeout - время, в течение которого клиент ожидает отправки сообщения в сессию
Если клиент не указал параметр sendTimeout при вызове RPC процедуры, то по умолчанию используется данное значение. i2RpcAPI ожидает завершения отправки указанное количество микросекунд, и если отправка не завершена - клиент получит сообщение об ошибке I2RC031
По умолчанию 5000000 (5 секунд)
  • receiveTimeout - время, в течение которого клиент ожидает приема сообщения от сессии
Используется аналогично sendTimeout, для ограничения времени, затрачиваемого на прием ответа от сессии. Если прием ответа от сессии не будет завершен в течение receiveTimeout микросекунд после отправки - клиент получит сообщение об ошибке I2RC032
По умолчанию 5000000 (5 секунд)

Секция statefull

  • job, user - имя работы и пользователя запускаемыx statefull сессий.
Если что-то не указано, по умолчанию используются параметры из клиентского задания. То есть, если что-то из job или user не указаны, и например запущенное задание данного клиента i2Rpc - 123456/I2RUSER/I2RPCC, запущено под профилем I2RPRF, то statefull сессии, запускаемые для данного клиента, будут запускаться под профилем I2RPRF, и будут иметь имя NNNNNN/I2RUSER/I2RPCC
  • submit - команда запуска statefull сессии.
Указывается шаблон команды SBMJOB, которую сервер будет использовать для запуска новых statefull сессий. Можно указать любые параметры команды SBMJOB, за исключением параметра CMD. Параметр CMD формируется сервером самостоятельно
В шаблоне команды можно использовать следующие макроподстановки - при формировании команды данные макроподстановки будут заменены на соответствующие параметры конфигурации
  • ${gateway.link}
  • ${gateway.debugLevel}
  • ${gateway.debugFacility}
  • ${gateway.debugProtocol}
  • ${gateway.syslogHost}
  • ${gateway.syslogPort}
  • ${session.debugLevel}
  • ${session.debugFacility}
  • ${session.debugProtocol}
  • ${session.syslogHost}
  • ${session.syslogPort}
  • ${statefull.job}
  • ${statefull.user}
  • ${statefull.init}
  • ${statefull.profile} - этот параметр определяется на основе наименования профайла, под которым работает исходное клиентское задание
  • ${statefull.system} - этот параметр содержит имя системы, в которой запущено исходное клиентское задание
По умолчанию используется значение:
SBMJOB JOB(${statefull.job}) USER(${statefull.user})
  • init - команда инициализации задания сессии. Будет выполнена первой командой в сессии, сразу после запуска задания
По умолчанию *NONE - команда инициализации не выполняется
  • submitTimeout - время ожидания готовности задания сессии на стороне сервера (мкс).
Если после запуска сессии прошло указанное время, но сессия не подключилась к серверу, то считается что сессия не стартовала, клиент получит сообщение об ошибке I2RC005 "Unable to get i2Rpc connection. Session submit timed out"
  • jobTimeout - время неактивности (мкс).
Если сессия не получает запросов в течение указанного времени, она будет завершена
По умолчанию = 5000000, (5 секунд)
  • maxJobs - максимальное количество statefull сессий, 0 - не ограничено
По умолчанию 0 - не ограничено
  • sendTimeout - время, в течение которого клиент ожидает отправки сообщения в сессию
Если клиент не указал параметр sendTimeout при вызове RPC процедуры, то по умолчанию используется данное значение. i2RpcAPI ожидает завершения отправки указанное количество микросекунд, и если отправка не завершена - клиент получит сообщение об ошибке I2RC031
По умолчанию 5000000 (5 секунд)
  • receiveTimeout - время, в течение которого клиент ожидает приема сообщения от сессии
Используется аналогично sendTimeout, для ограничения времени, затрачиваемого на прием ответа от сессии. Если прием ответа от сессии не будет завершен в течение receiveTimeout микросекунд после отправки - клиент получит сообщение об ошибке I2RC032
По умолчанию 5000000 (5 секунд)

Секция logger

Данная секция предназначена для настройки параметров протоколирования вызовов RPC прикладной программой трассировки (см. Логирование и трассировка)

Протоколирование параметров вызовов RPC внешней user exit программой - достаточно нагруженная процедура, поэтому в целях оптимизации вычислительных ресурсов задача протоколирования может быть отделена от основного задания сервера i2Rpc и вынесена в изолированное задание. То есть можно говорить об использовании встроенного и внешнего протоколирования вызовов RPC. За это отвечает параметр embedded.

Сервер протоколирования (встроенный или внешний) - это многопоточный сервер, в котором организована внутренняя очередь сообщений, подлежащих передаче в user exit программу протоколирования. Для передачи сообщений от сессий в сервер протоколирования используется отдельный unix сокет (файл на файловой системе IFS), который определяется в настройках сервера

  • embedded - Признак использования встроенного в gateway прикладного трассировщика
Если embedded=false, для логирования вызовов можно запустить отдельное задание логирования
Задание имеет те же параметры, что и основное задание gateway, только вместо CALL I2RPCG должен быть сделан CALL I2RPCL
  • listenerThreads - количество потоков сервера протоколирования. При использовании встроенного сервера протоколирования, данные потоки запускаются параллельно с остальными потоками сервера i2Rpc
  • link - линк (сокет), который используется для передачи сообщений серверу протоколирования
По умолчанию формируется в виде /tmp/I2R@<port>_log.do_not_delete, где port - номер порта gateway
Сервер протоколирования и сессии должны иметь доступ к указанному ресурсу
Удаление линка в момент работы сервера ЗАПРЕЩЕНО
  • output - сохраняются только ответные сообщения
  • input - сохраняются только входящие запросы
  • both/inputoutput - сохраняются входящие запросы и ответные сообщения
  • none - протоколирование не выполняется

Запуск сервера

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

SBMJOB CMD(CALL PGM(I2RPCG) PARM(<Параметры командной строки>)) ALWMLTTHD(*YES)

Параметры команды SBMJOB могут быть любыми, однако:

  • ALWMLTTHD(*YES) - обязательный параметр
  • Программа I2RPCG должна присутствовать в списке библиотек

TODO: Требуемая авторизация пользователя, который запускает I2RPCG

Параметры командной строки

Параметры конфигурации экземпляра сервера i2RPC указываются в параметрах вызова программы I2RPCG, в формате:

--parameter=value или

--parameter value или

--parameter - если параметр представляет собой некий признак, и не предусматривает указания значения

Пример:

SBMJOB CMD(CALL PGM(I2RPCG) PARM('--config=/home/i2rpc/config.json' '--stateless.minJobs' '1')) ALWMLTTHD(*YES)

Параметр --config, если указан, определяет имя файла, содержащего параметры конфигурации экземпляра сервера. Файл должен иметь кодировку 1208 (utf-8), и содержать валидный json объект с атрибутами, соответствующими параметрам конфигурации сервера.

Если какой-то из параметров конфигурации сервера содержится и в командной строке, и в файле конфигурации, то значение параметра из командной строки имеет преимущество

Встроенный и внешний сервер трассировки

Как отмечено в разделе Логирование и трассировка, для сохранения отладочных сведений о выполнении пользовательских программ, используется специальная user exit программа. Для уменьшения влияния производительности данной user exit программы на совокупную производительность сервера i2Rpc, все процедуры, связанные с трассировкой, вынесены в отдельный сервер трассировки. Сервер представляет собой поток(и), которые ожидают трассировочные сообщения от обработчиков и вызывают user exit программу протоколирования. Сервер может быть запущен как в составе основного задания сервера i2RpcG, так и в отдельном задании.

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

  • logger.embedded = true
  • logger.listenerThreads - значение больше нуля. Определяет количество потоков сервера трассировки, которые будут запущены в составе сервера i2RpcG

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

  • Указать в logger.embedded=false, logger.listenerThreads - ненулевое значение
  • Запустить внешний сервер протоколирования командой, аналогичной команде запуска основного сервера i2RpcG, используя имя программы I2RPCL вместо I2RPCG, например:
SBMJOB CMD(CALL PGM(I2RPCL) PARM('--config=/home/i2rpc/config.json' '--stateless.minJobs' '1')) ALWMLTTHD(*YES)

Использование i2RpcAPI

Параметры вызова i2RpcAPI

Для взаимодействия клиентского ПО с сервером i2Rpc, используется программа I2RPCAPI

Прототипы: 

#include <QUSEC.h>   
#pragma linkage(I2RPCAPI,OS)
void I2RPCAPI(char *format, void *apiData, ... /* Qus_EC_t *error */ );

D/COPY QSYSINC/QRPGLESRC,QUSEC
 * Основной модуль i2Rpc API
 * Параметры:
 *   format  - определяет команду i2Rpc API и формат ее параметров
 *   ApiData - параметры вызова i2RpcAPI, структура зависит от Format
 *   error   - (не обязательно) - структура для возврата кода ошибки 
 *            
D i2RpcAPI        PR                  EXTPGM('I2RPCAPI')
D  format                       10A   Const
D  apiData                   99999A   Options(*Varsize)
D  error                              Likeds(QUSEC) Options(*NOPASS)


Формальный список параметров программы i2RpcAPI:

  • format - команда i2Rpc, определяет команду i2Rpc и формат ее параметров. Одно из:
    • I2RC000001
    • I2RC000002
    • I2RC000003
    • I2RC000004
    • I2RC000005
  • apiData - cтруктура, содержащая параметры вызова данной команды
  • error (не обязательно) cтандартная структура для обмена информацией об ошибках, в стандартном формате API IBMi QUSEC ERRC0100

Если параметр ошибки не передан, то в случае возникновения ошибок, i2RpcAPI сгенерирует прерывающее escape сообщение. Если параметр ошибки передан, то после вызова i2RpcAPI в нем будет содержаться код ошибки и сопровождающая ошибку информация

I2RC000001 подключение к серверу

Команда I2RC000001 используется для получения хендлера соединения к серверу i2Rpc. Структура параметров команды I2RC000001: 

// I2RC000001 - Connect
typedef struct i2R_Connect_t {
   // Input
   char gateway[256];
   int  port;
   char statefull;              // 0/1
   int  connectTimeout;
   int  contextLength;
   char *contextData;

   // Output
   void *connection;
   char system[8];
   char number[6];
   char user[10];
   char id[10];
} i2R_Connect_t;

D i2RConnect      DS                  Qualified Inz

 * Input
D  gateway                     256A
D  port                         10I 0
D  statefull                     3I 0                                      1/0
D  connect...                                  
D     Timeout                   10I 0
D  contextLength                10I 0
D  contextData                    *

 * Output
D  connection                     *
D  system                        8A                                        System
D  number                        6A                                        Job number
D  user                         10A                                        Job user
D  id                           10A                                        Job id

Параметры:

  • gateway адрес сервера i2Rpc (IP адрес или сетевое имя, или имя файла на файловой системе, если сервер запущен на unix-сокете)
  • port порт сервера i2Rpc. Должно равняться 0, если используется unix-сокет
  • statefull если = 1, то для данного соединения будет запущено персональное задание, и все RPC вызовы будут адресованы в это задание. Если = 0, то сервер i2Rpc будет использовать любое доступное задание для RPC вызовов в рамках данного соединения
  • connectTimeout таймаут установки соединения. Если=0, по умолчанию используется 5с.
  • contextLength длина параметра contextData
  • contextData указатель на данные контекста
  • connection handler соединения
  • system, number, user, id имя задания, запущенного на сервере i2Rpc для обслуживания данного соединения (только для statefull=1)
Если statefull=0, то данные параметры в ответе не заполняются

I2RC000002 RPC вызов программ

Формат I2RC000002 используется для удаленного вызова программ при помощи i2Rpc

Структура параметров 

// I2RC000002 - Run program
typedef struct i2R_RunProgram_t {
   void  *connection;
   char   lib[10];
   char   pgm[10];
   int    argc;
   char **argv;  
   int   *argl;
   int    sendTimeout;
   int    recvTimeout;
   char   traceIn;
   char   traceOut;
   char   withJobLog;
   char   withJobLogOnError;
   char   returnResolvedName;
   char   logging;
   int    jobLogProvided;
   char  *jobLog;
} i2R_RunProgram_t;

D i2RCallProgram  DS                  Qualified Inz
D  connection                     *
D  lib                          10A                                        I/O (returnResolvedName)
D  pgm                          10A                                        I/O (returnResolvedName)
D  argc                         10I 0
D  argv                           *                                        Input/Output
D  argl                           *
D  sendTimeout                  10I 0                                      I
D  recvTimeout                  10I 0                                      I
D  traceIn                       3I 0                                      1/0
D  traceOut                      3I 0                                      1/0
D  withJobLog                    3I 0                                      1/0
D  withJobLog...
D     OnError                    3I 0                                      1/0
D  return...
D    Resolved...
D    Name                        3I 0                                      1/0
D  logging                       1A                                        I/O/B/D/N
D  joblog...
D    Provided                   10I 0
D  joblog                         *                                        O (withJobLog*+joblogProvided)

Описание параметров:

  • connection полученный ранее handler соединения
  • lib/pgm input - имя вызываемой программы. В lib можно использовать *LIBL. Программа должна быть "видна" в списке библиотек целевого задания
output - если параметр returnResolvedName=1, то в данных полях возвращается реальное имя библиотеки и программы, использованной при удаленном вызове
  • argc количество параметров программы
  • argv массив из argc элементов - указателей на параметры программы
  • argl массив длин параметров программы. Каждый элемент массива определяет длину соответствующего элемента массива argv
  • sendTimeout таймаут (мкс) отправки сообщения в сессию
Если отправка не завершится за указанное время, то i2RpcAPI вернет ошибку I2RC031
если = 0, то используется соответствующий параметр конфигурации сервера
  • recvTimeout таймаут (мкс) приема сообщения от сессии
Если ответное сообщение от сессии не поступит в течение указанного времени после отправки, то i2RpcAPI вернет ошибку I2RC032
если = 0, то используется соответствующий параметр конфигурации сервера
  • traceIn 0/1
Если = 1, то в job log сессии будет распечатан массив входных параметров программы в hex формате
  • traceOut 0/1
Если = 1, то в job log сессии будет распечатан массив выходных параметров программы в hex формате
  • withJobLog 0/1
Если = 1, то сервер вернет клиенту содержимое job log сессии, сформированное в процессе вызова программы.
Для приема joblog необходимо передать в параметре joblog указатель на область памяти, где должен быть размещен текст протокола задания, и указать в параметре joblogProvided длину данной области
  • withJobLogOnError 0/1
Аналогично предыдущему параметру, но job log будет возвращен только в случаях критических сбоев вызова программы
  • returnResolvedName 0/1
Если = 1, то после вызова API в переменных lib/pgm будет возвращено реальное значение использованных при вызове библиотеки и программы
  • logging I/O/B/N/D
Указывает что передается в трассировку:
  • I - входной PLIST перед вызовом программы
  • O - выходной PLIST после вызова программы
  • B - PLIST до и после вызова программы
  • N - Трассировка не выполняется
  • D или пробел - Трассировка определяется на основе настроек сервера
Параметры игнорируются, если на сервере отключена трассировка (нет потоков обработки трассировочных сообщений)
  • joblogProvided - количество байт, доступных в переменной joblog для приема возвращаемого joblog программы
  • joblog указатель на область памяти длиной joblogProvided, куда будет размещен joblog вызванной программы

I2RC000003 печать joblog

Данная команда API i2RpcAPI служит для печати содержимого joblog, полученного при вызове программы при помощи I2RC000002. Job log представляет собой текстовую строку, содержащую разделители (cr+lf), которая заканчивается нулевым символом (x'00'). Функция печати I2RC000003 разбивает полученный job log на отдельные строки и выполняет их вывод в job log клиентского задания, используя функцию Qp0zLprintf.

Структура параметров: 

// I2RC000003 - Print job log
typedef struct i2R_PrintJobLog_t {
   int   jobLogProvided;
   char *jobLog;
} i2R_PrintJobLog_t;

D i2RJobLog       DS                  Qualified Inz
D  jobLog...
D    Provided                   10I 0
D  jobLog                         *

Описание параметров:

  • jobLogProvided длина параметра joblog
  • jobLog указатель на содержимое joblog, полученное при вызове i2RpcAPI в режиме I2RC000002

I2RC000004 отключение от сервера

Если в клиентском соединении более нет необходимости, клиент может выполнить отключение от сервера командой I2RC000004. Этот вызов освободит на стороне сервера ресурсы, зарезервированные для обслуживания соединения с данным клиентом, а также (для statefull сессии) - завершит сессионное задание данного клиента.

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

Структура параметров 

// I2RC000004 - Disconnect
typedef struct i2R_Disconnect_t {
   void *connection;
} i2R_Disconnect_t;



D i2RDisconnect   DS                  Qualified Inz
D  connection                     *

Параметры

  • connection указатель на хэндлер соединения, полученный ранее командой I2RC000001

I2RC000005 изменение контекста вызова

Команда I2RC000005 позволяет клиенту выполнить установку/изменение клиентского контекста сессии. Данный вызов сохраняет/заменяет содержимое области данных клиентского контекста, эти данные передаются серверу i2Rpc при всех последующих вызовах программ командой I2RC000002.

Вызов команды I2RC000005 не изменяет непосредственно окружение в клиентской сессии. При этом вызове только сохраняется новое содержимое области данных контекста сессии, и если это содержимое будет отличаться от того, которое было использовано ранее при вызове программы в сессии (команда I2RC000002), то перед следующим вызовом программы будет предварительно вызван вызван user exit, указанный в параметре конфигурации state{full|less}.contextSetExit

Структура параметров 

// I2RC000005 - SetContext
typedef struct i2R_SetContext_t {
   // Input
   void *connection;
   int contextLength;
   char *contextData;
} i2R_SetContext_t;

D i2RSetContext   DS                  Qualified Inz
D  connection                     *
D  contextLength                10I 0
D  contextData                    *

Описание параметров

  • connection полученный ранее handler соединения
  • contextLength длина параметра contextData
  • contextData указатель на данные контекста

Трассировка RPC вызовов

Примеры клиентского ПО

Клиент на языке C

Клиент на RPGLE

Пример user exit трассировки вызовов

Retrieved from "https://www.i2rest.com/index.php?title=I2Rpc&oldid=2114"