Learn critical cleanup techniques that target end-of-job due to end job commands.
This article continues the discussion we started in Part I. Let's start by looking at invocation exit programs and procedures.
If an MI process phase is terminated and the process was not in termination phase, then the invocations are terminated. Invocation exit programs/procedures set for the terminated invocations are allowed to run. Invocation entries (aka call stack entries) are terminated in the order of from the bottom to the top of the invocation stack (aka call stack). Invocation exits are a cleanup mechanism targeting the abnormal end-of-invocation—for example, end-of-invocation due to unhandled exceptions or thread termination. For this reason, invocation exits can monitor for end job commands issued to a job and protect resources allocated in each individual invocation.
An OPM program can register an invocation exit program for itself via the Set Invocation Exit (SETIEXIT) MI instruction. An ILE HLL procedure can register one or more invocation exit procedures for itself via the Register Call Stack Entry Termination User Exit Procedure (CEERTX) API. Simon Coulter mentioned these invocation exits techniques that target end-of-job due to end job operations in a post called Re: Regarding *PSSR in the midrange-l mailing list back in 1999:
The *PSSR is not called when the job is terminated…. using SHTDN will work if the program is not waiting for input.
What is required here is an invocation exit program. Use the CEERTX (Register Call Stack Entry Termination User Exit Procedure) API. This should be the first thing the program does, then if it is terminated by anything other than a return-to-caller the named program is executed -- usually to clean-up or restore some state.
You can also use the SETIEXIT MI instruction.
The exit program will get control when the invocation is terminated due to normal exception handling or when the process (job) is terminated.
The CEEUTX API or the CLRIEXIT MI instruction can be used to remove the exit program.
For the same reason explained by Simon in his 2001 post, as an HLL-specific exception handling construct, *PSSR routine will not be invoked when an invocation is terminated due to an end job command.
Using Invocation Exit Programs in OPM Programs via the SETIEXIT and CLRIEXIT MI Instructions
For decades, the SETIEXIT instruction has been used in OPM RPG and OPM CL programs to register invocation exits. Issue a CRTRPGPGM or CRTCLPGM command with GENOPT(*LIST) and see the MI instructions in the result compiler listing. You will find the invocation exit programs used by OPM RPG and OPM CL are QSYS/QRGXINVX and QSYS/QCLCLNUP, respectively.
The Set Invocation Exit (SETIEXIT) and Clear Invocation Exit (CLRIEXIT) MI instructions register and unregister, respectively, the invocation exit program for the OPM program in which they are issued. The SETIEXIT instruction accepts an initialized or resolved system pointer to the invocation exit program as its first operand, and an argument list to be passed to the invocation exit program as its second operand. The system pointer to the invocation exit program must be in either the static or automatic storage of the program invoking this instruction. If the argument list operand is null, no arguments are passed to the invocation exit program. If an invocation exit program currently exists for the requesting invocation, it is replaced. No operand verification takes place when this instruction is executed. Nor are copies made of the operands, so changes made to the operand values after execution of this instruction will be used during later operand verification when the invocation exit program is invoked. At that time, execute authorization verification to the invocation exit program and any contexts referenced for materialization take place. Also, materialization lock enforcement occurs to contexts referenced for materialization. The CLRIEXIT instruction removes the invocation exit program for the requesting invocation. An implicit clear of the invocation exit occurs when the invocation exit program is given control or the program that set the invocation exit completes execution.
The following is an MI program, eoj09.emi, that registers itself as its invocation exit program via the SETIEXIT instruction. EOJ09 accept a CHAR(1) flag parameter passed by reference and an optional CHAR(20) arg parameter passed as scalar. When the flag parameter is set to 'E', EOJ09 works as an invocation exit program and does necessary cleanup work.
|
dcl spcptr @flag parm ; dcl dd arg char(20) parm ; /** * Parameter list of EOJ09's external entry point. * - CHAR(1) @var flag passed by reference. Set @var flag to 'E' if * EOJ09 is expected to execute as an invocation exit program. * - Optional CHAR(20) scalar. */ dcl ol plist ( @flag, arg ) parm ext min(1) ; entry i-main(plist) ext ;
dcl dd flag char(1) bas(@flag) ; /* Check flag parm. Branch to label i-inv-exit if flag equal to 'E'. */ cmpbla(b) flag, "E" / eq(i-inv-exit) ; brk "START" ; /* Retrieve a SYSPTR of mine via MATINVE, option hex 01 */ dcl dd inve-tmpl char(16) auto bdry(16) ; dcl sysptr me def(inve-tmpl) pos(1) ; matinve inve-tmpl, *, x'01' ; brk "1" ; /* Set myself as my INV-EXIT */ setiexit me, argl-exit ; brk "2" ; /* Do my works */ cpybrep msg, ' ' ; cpybla msg, "Doing my works ..." ; %sendmsg(msg, 32) ; dcl dd wt auto char(16) ; dcl dd * char(8) def(wt) pos(1) init( x"00000D ) ; /* 1 hour */ waittime wt ; /* Sleep ... */ see-you: rtx * ;
/* Run as INV-EXIT */ i-inv-exit: brk "INVEXIT" ; cpybrep msg, ' ' ; cpybla msg, "INV-EXIT:" ; cpybla msg(11:20), arg ; %sendmsg(msg, 32) ; cpybrep msg, "cleanup " ; %sendmsg(msg, 32) ;
b see-you ;
dcl dd exit-flag char(1) init("E") ; dcl spcptr @exit-flag auto init(exit-flag) ; dcl dd exit-arg char(20) stat init ( "Oops, time to leave!" ) ; /* Argument list to INV-EXIT */ dcl ol argl-exit ( @exit-flag, exit-arg ) arg ; dcl dd msg char(32) auto ;
pend ; |
Submit a batch job that calls EOJ09 like so:
|
SBMJOB JOB(A) CMD(CALL EOJ LOG(4 0 *MSG) /* Log message text */ |
Then end it with an ENDJOB A *IMMED command. The printed job log of job ABC might look like the following:
|
Job name . . . . . . . . . . : A User . . . . . . : LJL Number . . . . . . . . . . . : 531606 Job description . . . . . . : LJL Library . . . . . : LSBIN MSGID TYPE SEV DATE TIME FROM PGM LIBRARY INST TO PGM LIBRARY INST CPF1124 Information 00 12/09/26 14:18:12.843632 QWTPIIPP QSYS 0671 *EXT *N Message . . . . : Job 531606/LJL/A started on subsystem QBATCH in QSYS. Job entered system on CPI1125 Information 00 12/09/26 14:18:12.844144 QWTPCRJA QSYS Message . . . . : Job 531606/LJL/A submitted. *NONE Request 12/09/26 14:18:12.844304 QWTSCSBJ * Message . . . . : -CALL PGM(EOJ09) PARM(A) *NONE Information 12/09/26 14:18:12.844488 EOJ09 LSBIN 0019 QCMD QSYS Message . . . . : Doing my work ... CPC1125 Completion 50 12/09/26 14:18:18.576376 QWTCCCNJ QSYS 0794 *EXT *N Message . . . . : Job 531606/LJL/A was ended by user LJL. *NONE Information 12/09/26 14:18:18.576512 EOJ09 LSBIN 0019 EOJ09 LSBIN 0009 Message . . . . : INV-EXIT: Oops, time to leave! *NONE Information 12/09/26 14:18:18.576528 EOJ09 LSBIN 0019 EOJ09 LSBIN 0009 Message . . . . : cleanup cleanup cleanup cleanup CPF1164 Completion 00 12/09/26 14:18:18.576976 QWTMCEOJ QSYS 00D8 *EXT *N Message . . . . : Job 531606/LJL/A ended on used; end code 50 . |
Using Invocation Exit Procedures in ILE Programs via the CEERTX and CEEUTX CEE APIs
The Register Call Stack Entry Termination User Exit Procedure (CEERTX) and the Unregister Call Stack Entry Termination User Exit Procedure (CEEUTX) APIs register and unregister, respectively, an invocation exit procedure for the invocation entry in which they are invoked. Note that the CEERTX and CEEUTX APIs are implemented as system built-ins instead of ILE procedures (see <leenv.h>, aka source member QSYSINC/H.LEENV, in which these two CEE APIs are declared). Multiple invocation exit procedures can be registered via CEERTX for each invocation entry (aka call stack entry). When an invocation ends abnormally, invocation exit procedures registered for the invocation run in first in/first out (FIFO) order.
The CEERTX API accepts procedure pointer @exit_proc as its first (and only necessary) parameter, which specifies the invocation exit procedure. The second parameter of CEERTX is an optional space pointer, @exit_arg, addressing the argument to be passed to the invocation exit procedure when the target invocation ends abnormally. The third parameter of CEERTX is optional structure fc of type FEEDBACK (see Data Type Definitions of ILE CEE APIs for details). The invocation exit procedure registered by CEERTX accepts only one parameter, the space pointer @exit_arg passed to CEERTX. The CEEUTX API accepts an input procedure pointer and removes a previous registration of it for the target invocation. If the same procedure is registered for the invocation more than once, CEEUTX processes the registrations in last in/first out (LIFO) order. The following RPG example, eoj10.rpgle, demonstrates the basic usage of CEERTX.
|
h dftactgrp(*no) bnddir('QC2LE') * Prototype of CEERTX d ceertx pr extproc('CEERTX') d @exit_proc * procptr d @exit_arg * options(*omit) d fc * Prototype of CEEUTX d ceeutx pr extproc('CEEUTX') d @exit_proc * procptr d fc * Prototype of libc routine sleep() d sleep pr 10i 0 extproc('sleep') d 10u 0 value * Invocation exit procedure d inv_exit pr d @arg *
d @exit_proc s * procptr d inz(%paddr(inv_exit)) d @arg s * inz(%addr(hello)) d hello s
/free ceertx(@exit_proc : @arg : *omit); sleep(600); *inlr = *on; /end-free
p inv_exit b d inv_exit pi d @arg * d arg s /free dsply 'Exit Arg' '' arg; /end-free p e |
To test EOJ10, you can simply submit a batch job calls EOJ10, end it with a ENDJOB *IMMED command, and then check the QSYSOPR message queue for the output message of EOJ10.
Monitor for End Job Operations via the *EXT Scope Message
The Send Scope Message (QMHSNDSM) API sends a scope message to a call stack entry. Scope messages are a way to call a program when the call stack entry that called the QMHSNDSM API ends or when the job using this API ends. The exit can be either normal or abnormal. The three scope types (*EXT, *PGM, and *CSE) indicate when the scope-handling program should be called. As Simon mentioned in a 2011 post, to have the scope-handling program run at job or routing step ending, specify *EXT for the scope type parameter. To unregister a scope-handling program, you can remove the previously sent scope message by using the Remove Program Messages (QMHRMVPM) API.
An interesting part of the QMHSNDSM API's design is that it distinguishes between a normal exit of an invocation and a transfer control. The difference between program scoping (*PGM) and call stack entry (*CSE) scoping is in how they handle a transfer control. When a transfer control occurs, the scope-handling program is called for scope type *PGM because the program or ILE procedure ended, but the scope-handling program is not called for scope type *CSE because the call stack is still active.
The following is an RPG example, eoj11.rpgle, that monitors an end job operation by registering itself as a *EXT scope program. When the number of parameters passed to EOJ11 is more than zero, EOJ11 works as a scope program.
|
h dftactgrp(*no) bnddir('QC2LE') * API error code structure d qusec_t ds qualified d based(@dummy) d bytes_in 10i 0 d bytes_out 10i 0 d msgid d * Message-specific message data
* Prototype of the Send Scope Message (QMHSNDSM) API d QMHSNDSM pr extpgm('QMHSNDSM') d type d scope_pgm d arg d arg_len 10i 0 d msg_key d ec likeds(qusec_t) * Prototype of libc routine sleep() d sleep pr 10i 0 extproc('sleep') d 10u 0 value
d scope_type s d scope_pgm s d arg s d arg_len s 10i 0 inz(32) d msg_key s d ec ds likeds(qusec_t) d text s
d i_main pr extpgm('EOJ11') d greeting
d i_main pi d greeting
/free if %parms() > 0; // Now, EOJ11 works as a scope program. // Do cleanup works dsply 'Scope-handling program invoked' ''; text = 'ARG: ' + greeting; dsply text ''; dsply 'Cleanup, cleanup, cleanup ...' ''; *inlr = *on; return; endif;
// Register myself as a *EXT scope-handling program ec.bytes_in = %len(ec); QMHSNDSM( scope_type : scope_pgm : arg : arg_len : msg_key : ec);
// Do my works dsply 'Doing my works ...' ''; sleep(600);
*inlr = *on; /end-free |
To test EOJ11, submit a batch job that runs EOJ11, and then end it with an ENDJOB *IMMED command. The messages sent to the QSYSOPR message queue might look like the following:
|
DSPLY Doing my work ... Job 531775/LJL/A was ended by user LJL. DSPLY Scope-handling program invoked DSPLY ARG: Hi, scope program! DSPLY Cleanup, cleanup, cleanup ... |
Know the End Reason of an MI Process in an Invocation Exit, ACTGRP Exit, or Scope Program
An end job operation is one of the reasons that an invocation exit, ACTGRP exit, or scope program registered in an MI process is invoked, but it's not the only reason. An unhandled exception or an unhandled signal delivered to the process with a default signal-handling action of terminate the process or terminate the request would also lead to process termination. To know the process termination reason exactly, you can materialize the Process Status Indicators via the Materialize Process Attributes (MATPRATR) MI instruction with option hex 20 within an invocation exit, ACTGRP exit, or scope program. The Process Initial Internal Termination (PIIT) status and the Process Initial External Termination (PIET) status in the materialized Process Status Indicators represent the final internal termination status and external termination status prior to entering the termination phase, respectively, and are updated by the most recent internal termination action and external termination action, respectively. It is possible for both the PIIT and PIET status fields to contain valid termination status values. The PIIT and/or PIET status fields contain valid termination status values when an invocation exit, ACTGRP exit, or scope program registered for the process is invoked. The 1-byte PIIT reason and 1-byte PIET reason fields represent the reason of final internal termination and final external termination, respectively. The following ILE RPG prototype of the MATPRATR instruction and the definition of the materialization template structure for Process Status Indicators, matpratr_20_t, are extracted from mih-prcthd.rpgleinc. Possible internal/external process termination reasons are listed in the comments of subfields piit and piet of the matpratr_20_t structure.
|
/** * Materialization template for MATPRATR, option hex 20 -- * Process status indicators. */ d matpratr_20_t ds qualified d based(@dummy) d bytes_in 10i 0 d bytes_out 10i 0 * * Thread state. * Bits 0-2: External existence state * 000 = Suspended due to Suspend Process or Suspend Thread * 010 = Suspended due to Suspend Process or Suspend Thread, * in instruction wait * 100 = Active, in ineligible wait * 101 = Active, in current MPL * 110 = Active, in instruction wait * 111 = Active, in instruction wait, in current MPL * Bit 3: Invocation exit active * Bit 4: Stopped by a signal * Bit 5: Suspended by Suspend Thread * Bits 6-7: Reserved (binary 0) * Bits 8-10: Internal processing phase * 001 = Initiation phase * 010 = Problem phase * 100 = Termination phase * Bits 11-15: Reserved (binary 0) * d thd_state d pending_thread_interrupts... d * * Process initial internal termination status * * @remark The process initial internal termination status * represents the final internal termination status prior to * entering the termination phase. It is updated by the most * recent internal termination action. It is possible for both * the process initial internal termination status and the * process initial external termination status fields to contain * valid non-zero values. * d piit * * Hex 80 = Return from first invocation in problem phase * Hex 40 = Return from first invocation in initiation phase and * no problem phase program specified. * Hex 21 = Terminate Thread instruction issued against the * initial thread by a thread in the process. * Hex 20 = Terminate Process instruction issued by a thread * within the process. * Hex 18 = An unhandled signal with a default signal handling * action of terminate the process or terminate the * request was delivered to the process. * Hex 10 = Exception was not handled by the initial thread in * the process. * Hex 00 = Process terminated externally. * d iit_reason * Initial internal termination code d iit_code * * Process initial external termination status * * @remark The process external internal termination status * represents the final external termination status prior to * entering the termination phase. It is updated by the most * recent external termination action. It is possible for both * the process initial internal termination status and the * process initial external termination status fields to contain * valid non-zero values. * d piet * Initial external termination reason: * Hex 80 = Terminate Process instruction issued explicitly to * the process by a thread in another process. * Hex 40 = Terminate Thread instruction issued explicitly to * the initial thread of the process by a thread in * another process. * Hex 00 = Process terminated internally. d iet_reason * Initial external termination code d iet_code * * Process final termination status * * @remark The process final termination status is presented as * event-related data in the terminate process event. Usually the * event is the only source of the process final termination * status since the process will cease to exist before its * attributes can be materialized. * * @remark The process final termination status describes how the * final phase (aka the termination phase) of the process * terminated. It is updated by the most recent termination * action for the final process phase. * d pfit
/** * @BIF _MATPRATR1 (Materialize Process Attributes (MATPRATR)) */ d matpratr1 pr extproc('_MATPRATR1') d receiver likeds(matpratr_tmpl_t) d option
/** * @BIF _MATPRATR2 (Materialize Process Attributes (MATPRATR)) */ d matpratr2 pr extproc('_MATPRATR2') d receiver likeds(matpratr_tmpl_t) d pcs * d option |
The pcs operand of _MATPRATR2 identifies the process control space (PCS) object associated with the process whose attributes are to be materialized.
The following RPG example, eoj12.rpgle, reports the following information available in the Process Status Indicators returned by MATPRATR: current process phase, whether invocation exit is currently active, process initial internal termination (PIIT) reason, and process initial external termination (PIET) reason. Add a call to program EOJ12 to previously presented example ACTGRP exit, invocation exit, or scope programs so that you can tell whether your job is ending due to end job operations or not.
|
h dftactgrp(*no) bnddir('QC2LE') fQSYSPRT O f 132 printer
/copy mih-prcthd.rpgleinc d w s d item_name s d item_value s d psts ds likeds(matpratr_20_t) d opt s d a2 s
/free // Materialize process state indicators of the current MI process psts.bytes_in = %len(matpratr_20_t); matpratr1(psts : opt);
// Current process phase -- bits 8-10 of thd_state a2 = %bitand(psts.thd_state : x'00E0'); item_name = 'Current process phase:'; except ITEMREC; select; when a2 = x'0020'; item_value = 'Initiation phase'; when a2 = x'0040'; item_value = 'Problem phase'; when a2 = x'0080'; item_value = 'Termination phase'; endsl; except VALREC;
// Invocation exit active? item_name = 'Invocation exit active:'; except ITEMREC; a2 = %bitand(psts.thd_state : x'1000'); if a2 = x'0000'; item_value = 'No'; else; item_value = 'Yes'; endif; except VALREC;
if psts.iit_reason = x'00' and psts.iet_reason = x'00'; *inlr = *on; return; endif;
// Initial internal termination reason item_name = 'Initial internal termination reason:'; except ITEMREC; select; when psts.iit_reason = x'80'; item_value = 'Return from first invocation ' + 'in problem phase'; when psts.iit_reason = x'40'; item_value = 'Return from first invocation in ' + 'initiation phase and no problem phase program ' + 'specified'; when psts.iit_reason = x'21'; item_value = 'Terminate Thread instruction issued against ' + 'the initial thread by a thread in the process'; when psts.iit_reason = x'20'; item_value = 'Terminate Process instruction issued ' + 'by a thread within the process'; when psts.iit_reason = x'18'; item_value = 'An unhandled signal with a default signal ' + 'handling action of terminate the process or ' + 'terminate the request was delivered to the process'; when psts.iit_reason = x'10'; item_value = 'Exception was not handled by the initial ' + 'thread in the process'; when psts.iit_reason = x'00'; item_value = 'Process terminated externally'; endsl; except VALREC;
// Initial external termination reason item_name = 'Initial external termination reason:'; except ITEMREC; select; when psts.iet_reason = x'80'; item_value = 'Terminate Process instruction issued ' + 'explicitly to the process by a thread in ' + 'another process'; when psts.iet_reason = x'40'; item_value = 'Terminate Thread instruction issued ' + 'explicitly to the initial thread of the process ' + 'by a thread in another process'; when psts.iet_reason = x'00'; item_value = 'Process terminated internally'; endsl; except VALREC;
*inlr = *on; /end-free
oQSYSPRT e ITEMREC o item_name
oQSYSPRT e VALREC o w 5 o item_value |
For example, add a call to EOJ12 to the invocation exit procedure of the previous RPG example eoj10.rpgle as shown:
|
p inv_exit b d eoj12 pr extpgm('EOJ12') d inv_exit pi d @arg * d arg s /free eoj12(); dsply 'Exit Arg' '' arg; /end-free p e |
Submit a batch job that runs EOJ10, end the submitted job with an ENDJOB *IMMED command, and then check the output spooled file printed by EOJ12. The output of EOJ12 might look like the following:
|
Current process phase: Problem phase Invocation exit active: Yes Initial internal termination reason: Process terminated externally Initial external termination reason: Terminate Process instruction issued explicitly to the process by a thread in another process |
Submit a batch job to call EOJ10 again, and end the submitted job with an ENDJOB *CNTRLD command. The resulting output of EOJ12 might look like this:
|
Current process phase: Problem phase Invocation exit active: Yes Initial internal termination reason: Terminate Process instruction issued by a thread within the process Initial external termination reason: Process terminated internally |
Now you know how to tell whether a job is ending due to an end job command within an invocation exit, an ACTGRP exit, or a scope program.
Final Thoughts
As mentioned in Part I of this article, an end job command can specify a delay time, either via the DELAY parameter of an ENDJOB *CNTRLD command or the QENDJOBLMT system value for an ENDJOB *IMMED command. After the delay time specified by an end job command elapses, the job will be ended by the system. Be aware that the same is not the case for a job utilizing one of these three end-of-job cleanup techniques: invocation exits, ACTGRP exits, and scope programs. Any delay or hanging that occurs in an invocation exit, an ACTGRP exit, or a scope program will delay or hang the end-of-job processing. Imagine that you issue an ENDJOB *IMMED command to end a job. An invocation exit procedure registered for one of the programs currently in the job's call stack receives control and starts doing necessary cleanup work. However, the invocation exit is stuck for some reason (for example, trying to allocate an exclusive lock on an MI object being used by many processes). In this condition, how long it will take the job to end is undetermined. The last chance to end such a job is by issuing an End Job Abnormal (ENDJOBABN) command to the job 10 minutes after the previous ENDJOB *IMMED command.
More than ever, there is a demand for IT to deliver innovation. Your IBM i has been an essential part of your business operations for years. However, your organization may struggle to maintain the current system and implement new projects. The thousands of customers we've worked with and surveyed state that expectations regarding the digital footprint and vision of the company are not aligned with the current IT environment.
TRY the one package that solves all your document design and printing challenges on all your platforms. Produce bar code labels, electronic forms, ad hoc reports, and RFID tags – without programming! MarkMagic is the only document design and print solution that combines report writing, WYSIWYG label and forms design, and conditional printing in one integrated product. Make sure your data survives when catastrophe hits. Request your trial now! Request Now.
Forms of ransomware has been around for over 30 years, and with more and more organizations suffering attacks each year, it continues to endure. What has made ransomware such a durable threat and what is the best way to combat it? In order to prevent ransomware, organizations must first understand how it works.
Disaster protection is vital to every business. Yet, it often consists of patched together procedures that are prone to error. From automatic backups to data encryption to media management, Robot automates the routine (yet often complex) tasks of iSeries backup and recovery, saving you time and money and making the process safer and more reliable. Automate your backups with the Robot Backup and Recovery Solution. Key features include:
Business users want new applications now. Market and regulatory pressures require faster application updates and delivery into production. Your IBM i developers may be approaching retirement, and you see no sure way to fill their positions with experienced developers. In addition, you may be caught between maintaining your existing applications and the uncertainty of moving to something new.
IT managers hoping to find new IBM i talent are discovering that the pool of experienced RPG programmers and operators or administrators with intimate knowledge of the operating system and the applications that run on it is small. This begs the question: How will you manage the platform that supports such a big part of your business? This guide offers strategies and software suggestions to help you plan IT staffing and resources and smooth the transition after your AS/400 talent retires. Read on to learn:
LATEST COMMENTS
MC Press Online