Продолжение цикла статей "что такое RPG и как с ним работать.

Предыдущие статьи
Современный RPG — что может и зачем нужен
Способы работы с БД DB2 в языке RPG на платформе IBM i

Как и прошлые статьи, эта носит исключительно обзорный характер, не претендуя на полноту изложения всех тонкостей работы с ошибками и исключениями на платформе IBM i в общем и в RPG в частности.

Преамбула

В настоящее время RPG существует (и активно используется) только на платформе IBM i. Эта платформа (как и сам RPG) позиционируется как платформа для коммерческих серверов. Т.е. для разного рода финансовых (главным образом) расчетов. Ошибки в этой области стоят очень дорого в прямом денежном выражении. Поэтому к обработке ошибок здесь принято относиться с с особым вниманием и тщательностью. И сама платформа и язык тому способствуют. Как пример - обычное переполнение (в отличии от других языков) в RPG вызывает исключение "Receiver value too small to hold result" аналогично исключению, возникающему при попытке деления на ноль. Попробуете присвоить значение, например, 60 000 переменной, объявленной как 16-битное знаковое целое - получите системную ошибку (исключение).

Любая ошибка здесь должна быть как минимум подробно зафиксирована, проанализирована и по возможности обработана. Будь то системная ошибка или ошибка бизнес-логики. И сама платформа, и язык предоставляют разнообразные возможности для работы с ошибками.

Сообщения, файлы сообщений

Основой для генерации ошибок и исключений в IBM i являются т.н. "сообщения".

Сообщение состоит из

Код (идентификатор) сообщения - 7 символов, традиционно первые три символа обозначают "мнемонику" (например, сообщения от SQL движка начинаются с SQL..., системные - MCH... или CPF... и т.п.), следующие 4 - номер внутри мнемоники.
Текст сообщения. Может содержать места для подстановки параметров (&1, &2 и т.д.) передаваемых как блок дополнительных данных
Уровень серьезности сообщения - 00 - информационное, 10 - предупреждение, 20 и выше - ошибка.
Количество и формат параметров

Например, сообщение с кодом KSM2010

ИД сообщения  Серьезность  Текст сообщения                               
  KSM2010          20      &1&2&3 does not exist on the database

Имеет три параметра

Поле     Тип данн.     Длина
&1       *CHAR            10
&2       *CHAR            10
&3       *CHAR            10

Сообщения хранятся в т.н. message files - объект типа *MSGF. Можно создавать свои файлы сообщений, добавлять туда свои типы сообщений, все это реализовано на уровне системных команд.

В нашей практике принято для каждой продуктовой линейки задавать свою "мнемонику" (3-символьный код) и использовать ее к качестве первых трех символов кода сообщения.

Для получения полного текста сообщения (с подставленными параметрами) есть системное API QMHRTVM (Retrieve Message) куда передается код сообщения, дополнительные данные (используемые для подстановки) и на выходе получим полный текст сообщения.

Например, передав туда 'KSM2010' и 'Client XXXXXX' получим текст 'Client XXXXXX does not exist on the database'

Структурированная ошибка

Данные для получения текста сообщения могут возвращаться в виде т.н. "структурированной ошибки". Системные API обычно используют следующую структуру (минимальный вариант)

typedef struct Qus_EC {
  int  Bytes_Provided;
  int  Bytes_Available;
  char Exception_Id[7];
  char Reserved;
  char Exception_Data[];           /* Varying length        */
} Qus_EC_t;

Где

Exception_Id - код сообщения, например, 'KSM2010'.
Exception_Data - блок дополнительных данных (переменной длины), например, 'Client XXXXXX'
Bytes_Provided - общий размер памяти, выделенный под эту структуру включая блок дополнительных данных, заполняется перед вызовом функции куда передается.
Bytes_Available - размер реально заполненных данных - определяется размером блока реально заполненных дополнительных данных, заполняется внутри вызываемой функции при формировании ошибки.

В RPG мы используем еще более простую версию:

dcl-ds t_dsError37 qualified template;
  errCode    char(7)   inz;
  errParm1   char(10)  inz;
  errParm2   char(10)  inz;
  errParm3   char(10)  inz;
  errParmAll char(30)  samepos(errParm1);
  errParm12  char(20)  samepos(errParm1);
  errParm23  char(20)  samepos(errParm2);
  errStr     char(37)  samepos(errCode);
end-ds;

Код ошибки + 3 параметра по 10 символов каждый (соответственно, все наши сообщения, которые мы сами создаем, имеют три 10-символьных параметра - для наших целей этого достаточно), плюс возможные их комбинации для случаев когда в тексте ошибки используются блоки типа &1&2&3, &1&2, &2&3. В приведенном выше примере:

dcl-ds dsError likeds(t_dsError37);

...

dsError.errCode    = 'KSM2010';
dsError.errParmAll = 'Client XXXXXX';

Очереди сообщений

В IBM i есть такой объект как "очередь сообщений" - *MSGQ. Мы можем создать свою очередь и посылать туда произвольные текстовые сообщения с тем, чтобы кто-то другой мог их оттуда извлечь. Для посылки сообщения в произвольную очередь есть системное API QMHSNDM (Send Nonprogram Message), для чтения сообщения из произвольной очереди - API QMHRCVM (Receive Nonprogram Message). Этот механизм бывает удобен для обмен сообщения между программами, работающими в разных заданиях или для мониторинга работы программы в реальном времени - в эмуляторе терминала можно подключиться к очереди сообщений и просматривать ее содержимое.

В RPG для посылки сообщения в произвольную очередь можно использовать оператор dsply с указанием имени очереди

dsply 'My message' 'MYMSGQ';

Особым случаем очереди сообщений является "очередь сообщений программы" - *PGMQ которая является частью стека вызовов - каждому уровню вызова (программе или процедуре в стеке) соответствует своя очередь сообщений. Это позволяет отправлять сообщения конкретной программе (например, предыдущей в стеке вызовов). Для работы с этими очередями также существуют системные API QMHSNDPM (Send Program Message) и QMHRCVPM (Receive Program Message)

Исключения

А что с исключениями? Тут все просто. IBM i предоставляет механизм системных, не зависящих от языка, исключений базирующихся на тех же самых сообщениях посылаемых в *PGMQ. Более того, поскольку на каждом уровне стека есть своя очередь сообщений, можно гибко управлять куда именно посылать исключение - самому себе (тот же уровень стека), вызывающей программе или выше по стеку с указанием от какого уровня и на сколько уровней вверх.

При посылке сообщения в *PGMQ необходимо указывать тип сообщения - информационное, диагностическое, прерывающее и т.п. Исключением (в привычном понимании) будет сообщение, посланное с типом "прерывающее" - *ESCAPE

Такой механизм позволяет не привязываться к конкретным языкам и их исключениям (которых может не быть или которые могут быть не совместимыми друг с другом), но использовать единый механизм, ограниченный только рамками задания (job) а не одной конкретной программы.

Более того, все сообщения (вне зависимости от типа), посланные в *PGMQ, автоматически фиксируются в логе задания (joblog) в котором работает программа, пославшая сообщение. Выглядит это примерно так:

CPF2105 Аварийное 40 24.04.25 10:23:58.882687 QLIDLOBJ QSYS 072F UTM10C1 KAPBASELIB *STMT
 Для модуля. . . . . . . . . : UTM10C1
 Для процедуры . . . . . . . : UTM10C1
 Оператор . . . . . . . . . : 10800
 Сообщение . . . : Объект DAJOBCTL в *LIBL типа *DTAARA не найден.
 Причина . . . . : Не было найдено объекта с указанным именем или типом.
 Исправление . . : Укажите правильное имя или тип объекта. Затем повторите
 запрос.

Как видно из примера, в joblog'е отображается достаточно подробная информация о том, что, когда и где случилось.

И, наконец, собственно про RPG

RPG, в отличии от современных языков, не поддерживает языковых исключений. Т.е. в нем нет привычных try/catch/throw. Но, как уже показано выше, их нет не потому что это нереализуемо, но просто потому что в этом нет необходимости при наличии мощного и гибкого механизма системных исключений.

Возможность перехвата исключений в RPG существует уже достаточно давно. Аналогом try/catch является оператор monitor

monitor ;
  Procedure1() ;
on-excp 'RNX1211' ;
  dsply ('RNX1211: Error in procedure') ;
on-error 202 ;
  dsply ('Handled by 202') ;
on-error ;
  dsply ('Catch all') ;
endmon ;

Оператор monitor в данном случае то же самое что try, on-excp и on-error - catch

on-error работает со кодами ошибок (статусами). Есть списки Program Status Codes - статусы ошибок, связанные с работой программы и File Status Codes - статусы ошибок, связанные с доступом к файлам. Также возможно использование мнемоник - *PROGRAM - для всех программных статусов или *FILE для всех статусов, касающихся работы с файлами.

on-excp появилась относительно недавно, работает непосредственно с ID сообщения. Одновременно с on-excp появилась очень удобная команда snd-msg, позволяющая посылать сообщение в очередь сообщений программы (аналог throw). Таким образом, получаем полный аналог try/catch/throw с использованием механизма системных исключений

monitor;
   subproc ();
on-excp 'ABC1234';
   dsply 'on-excp ABC1234';
endmon;

dcl-proc subproc;
   snd-msg *escape %msg('ABC1235': 'MYMSGF');
end-proc;

В данном случае предполагается что у нас есть файл сообщений MYMSGF в который мы записываем свои коды сообщений и мы предварительно записали туда сообщение с ID 'ABC1235'.

Далее, если у нас это действительно случилось в процедуре subproc, мы посылаем в очередь сообщений программы сообщение с ID 'ABC1235' описанное в файле MYMSGF.

При необходимости передачи дополнительной информации (параметров для подстановки в текст сообщения) блок параметров передается третьим параметром в %msg

snd-msg *escape %msg(dsError.errCode: 'KSMMSGF': dsError.errParmAll);

Чтобы он было перехвачено монитором, нужно указать, что это прерывающее сообщение - *escape.

Сообщение это будет перехвачено монитором и обработано в блоке on-excp 'ABC1234'.

Как уже писалось выше, можно посылать сообщение (исключение) не только себе, но и выше по стеку. Для этого у команды snd-msg есть дополнительный параметр %target позволяющий явно указывать куда посылать сообщение:

на текущий уровень стека - *SELF
на уровень стека выше - *CALLER
на произвольный уровень стека

Например, при необходимости послать сообщение на два уровня стека выше главной процедуры программы GFCLMTCMP пишем:

snd-msg *escape %msg(dsError.errCode: 'KSMMSGF': dsError.errParmAll) %target('GFCLMTCMP': 2);

Не перехваченные исключения

Отдельный вопрос - "а что будет если исключение возникло вне блока monitor?" На этот случай в RPG есть возможность описания специальной сабрутины со служебным именем *pssr, которая сама по себе является не обработчиком исключения, но точкой выхода из процедуры в случае возникновения внутри не перехваченного в monitor исключения.

Внутри *pssr уже можно сделать или полноценную обработку исключения, или, как минимум, запросить систему создать дамп где будет содержаться подробная информация о том, что и где пошло не так и получить значения всех переменных. В RPG для этого есть специальная команда dump.

При этом, если в *pssr будет присутствовать return (после всех необходимых действий), исключение будет считаться обработанным и программа завершится нормально. В отсутствие return исключение останется в статусе не обработаного и будет перколировать вверх по стеку вызовов.

Еще один важный момент - рекомендуется все действия по обработке исключения внутри *pssr оборачивать в блок monitor во избежание зацикливания в случае возникновения нового исключения в процессе обработки исходного.

dcl-proc mainProc;
  ...
  subprocA(...);
  ...
  return;

  begsr *pssr;
    // обрабатываем исключение
  endsr;
end-proc;

dcl-proc subprocA
  ...
  subprocB(...);
  ...
  return;

  begsr *pssr;
    dump;
  endsr;
end-proc;

dcl-proc subprocB
  ...
  return;

  begsr *pssr;
    dump;
  endsr;
end-proc;

При возникновении исключения в subprocB будет создан дамп для этой процедуры. Но само исключение пойдет вверх по стеку и в subprocA также будет создан дамп. Дальше исключение попадет в mainProc где уже будет полноценно обработано в ее *pssr

В результате получим два дампа в которых будет полная информация о состоянии как subprocB так и вызвавшей ее subprocA которое привело к исключению. Т.е. максимально полная информация для последующего "разбора полетов".

Альтернативой *pssr является блок on-exit - единая точка выхода из процедуры. То место, когда попадаем после любого return или исключения.

dcl-proc someProc;
  dcl-s wasError ind;
  ...
  return;

  on-exit wasError;
    if wasError;
      // попали сюда после исключения
      ...
    endif;
    ...
end-proc;

При возникновении исключения попадаем в on-exit с индикатором wasError = *on (устанавливается автоматически, достаточно просто его объявить и указать параметром для on-exit).

К сожалению, нельзя совместно использовать *pssr и on-exit, а сам on-exit достаточно ограничен по возможностям - там много чего делать нельзя. Например, нельзя использовать команду dump... Поэтому *pssr все-таки является более предпочтительным способом.

Чтобы понять что и где случилось если вдруг попали в *pssr, в RPG есть специальная структура - PSDS (Program Status Data Structure) которая объявляется глобальной переменной

dcl-ds dsRPGPS psds qualified ;
  Proc char(10) ;                              // Module or main procedure name
  StsCde zoned(5) ;                            // Status code
  PrvStsCde zoned(5) ;                         // Previous status
  SrcLineNbr char(8) ;                         // Source line number
  Routine char(8) ;                            // Name of the RPG routine
  Parms zoned(3) ;                             // Number of parms passed to program
  ExceptionType char(3) ;                      // Exception type
  ExceptionNbr char(4) ;                       // Exception number
  Exception char(7) samepos(ExceptionType) ;   // Exception Message Id
  Reserved1 char(4) ;                          // Reserved
  MsgWrkArea char(30) ;                        // Message work area
  PgmLib char(10) ;                            // Program library
  ExceptionData char(80) ;                     // Retrieved exception data
  Rnx9001Exception char(4) ;                   // Id of exception that caused RNX9001
  LastFile1 char(10) ;                         // Last file operation occurred on
  Unused1 char(6) ;                            // Unused
  DteEntered char(8) ;                         // Date entered system
  StrDteCentury zoned(2) ;                     // Century of job started date
  LastFile2 char(8) ;                          // Last file operation occurred on
  LastFileSts char(35) ;                       // Last file used status information
  JobName char(10) ;                           // Job name
  JobUser char(10) ;                           // Job user
  JobNbr zoned(6) ;                            // Job number
  StrDte zoned(6) ;                            // Job started date
  PgmDte zoned(6) ;                            // Date of program running
  PgmTime zoned(6) ;                           // Time of program running
  CompileDte char(6) ;                         // Date program was compiled
  CompileTime char(6) ;                        // Time program was compiled
  CompilerLevel char(4) ;                      // Level of compiler
  SrcFile char(10) ;                           // Source file name
  SrcLib char(10) ;                            // Source file library
  SrcMbr char(10) ;                            // Source member name
  ProcPgm char(10) ;                           // Program containing procedure
  ProcMod char(10) ;                           // Module containing procedure
  SrcLineNbrBin bindec(2) ;                    // Source line number as binary
  LastFileStsBin bindec(2) ;                   // Source id matching positions 228-235
  User char(10) ;                              // Current user
  ExtErrCode int(10) ;                         // External error code
  IntoElements int(20) ;                       // Elements set by XML-INTO or DATA-INTO (7.3)
  InternalJobId char(16) ;                     // Internal job id (7.3 TR6)
  SysName char(8) ;                            // System name (7.3 TR6)
end-ds ;

В объявлении должен присутствовать модификатор psds.

Здесь будет имя процедуры где произошло исключение (Proc), строка кода (SrcLineNbr), код сообщения (Exception) с блоком дополнительных данных (ExceptionData) и много другой полезной информации, позволяющей понять что и где произошло.

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

Основной минус исключений в том, что это достаточно ресурсоемкий механизм. И использовать его в высоконагруженных системах нежелательно. К счастью, в RPG есть способ обхода исключений - модификатор (e) существующий для большинства операторов языка и преобразующий исключение в статус ошибки.

Например, для чтения файла:

read(e) ...;
if %error;
  // случилась ошибка - обрабатываем
endif;

В данном случае вместо того чтобы перехватывать исключение при помощи monitor используется модификатор (e) с последующей проверкой была ли ошибка.

Если ошибка была, можно получить ее код через функцию %status которая вернет код ошибки (аналогично errno в С). Для файловых операций будет возвращаться код ошибки из списка File Status Codes, для остальных ситуаций - из списка Program Status Codes.

С точки зрения нагрузки этот способ предпочтительнее перехвата исключения через monitor или *pssr.

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

Итого

Отсутствие в RPG языковых исключений с лихвой компенсируется наличием в IBM i исключений системных и поддержкой этих исключений средствами языка.

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

Обработка ошибок и исключений в RPG на IBM i