How Applications Can Detect When a Job Is Ending in a Controlled Manner

Applications which need to perform end-of-job cleanup can detect when the job is being ended in a controlled manner (*CNTRLD) via the End Job (ENDJOB), End Subsystem (ENDSBS) or the Power Down System (PWRDWNSYS) commands.

This function allows a signal handling procedure to receive control when a job is being ended in a controlled manner. The asynchronous signal SIGTERM is generated for the job being ended in a controlled manner if the job has expressed an interest in asynchronous signals and the asynchronous signal SIGTERM is being handled by a signal handling procedure. If either of the above conditions is not met, the asynchronous signal SIGTERM will not be generated for the job being ended.

When the How To End option of the End Job (ENDJOB), End Subsystem (ENDSBS), or Power Down System (PWRDWNSYS) command is specified as *CNTRLD -- end the job in a controlled manner -- the operating system will conditionally generate the asynchronous signal SIGTERM.

When the signal handling procedure for the asynchronous signal SIGTERM is given control, that procedure can take the appropriate actions to allow the application to be ended in a controlled manner. If the application has not ended when the delay time, specified by the DELAY keyword, expires, the job will be ended immediately. It might be necessary to increase to the delay time if the job being ended has multiple threads. There are several methods to determine if the job being ended has multiple threads:

1.	Work Active Job (WRKACTJOB) command. Either: a) Select Option 12, Work with Threads, for the job that is to be ended to view the list of threads in that job, or b) Press F11 until the Display thread data view and check the number of threads for the job to be ended.
2.	Work with Job (WRKJOB) command. Select Option 20, Work with threads (if active), to view the list of threads in the job to be ended.
3.	Display Job (DSPJOB) command. Select Option 20, Work with threads (if active), to view the list of threads in the job to be ended.

If the *IMMED value is specified for the OPTION keyword on either the ENDJOB, ENDSBS, or PWRDWNSYS command, the asynchronous signal SIGTERM is not generated for the job(s) being ended. For this reason, it is strongly recommended that you always attempt to end a job or a subsystem by specifying the *CNTRLD value for the OPTION keyword.

Any application that needs to perform end-of-job cleanup should detect when the job is ending in a controlled manner. There are three ways an application may detect this:

o	Synchronously retrieve End Status.
o	Synchronously check major and minor return codes after an I/O operation.
o	Handle the asynchronous signal SIGTERM.

Synchronous Retrieve of End Status

At certain points, an application may synchronously check the End Status of the job in which it is running. The job's End Status can be retrieved by calling the Retrieve Current Attributes (QWCRTVCA) API, the Retrieve Job Information (QUSRJOBI) API, the List Job (QUSLJOB) API, or by issuing the Retrieve Job Attributes (RTVJOBA) CL command.

Major and Minor Return Codes

For both display I/O and ICF communications I/O, a major return code of 02, or a major return code of 03 with a minor return code of 09 indicates the job is ending in a controlled manner. For more information, see Appendix E of the Application Display Programming book, SC41-5715-00, or Appendix B of the ICF Programming book, SC41-5442-00.

Asynchronous Signal SIGTERM

Some applications use a signal handling program to improve the cleanup of the application when the job is ended. Refer to the System API Reference for more information on POSIX APIs that enable a job to process signals. The system generates the asynchronous signal SIGTERM for the job being ended when the job is ending controlled and all of the following conditions are met:

o	The job is enabled for signals.
o	The job has a signal handling program that is established for the SIGTERM signal.
o	The job is currently running in the problem phase.

If any of the above conditions are not met, the SIGTERM signal is not generated for the job being ended. The SIGTERM signal is not generated when a job is ended immediately.

When a job being ended in a controlled manner has a signal handling procedure for the asynchronous signal SIGTERM, the SIGTERM signal is generated for that job. When the signal handling procedure for the SIGTERM signal is given control, the procedure can take the appropriate actions to allow the application to be ended in a controlled manner.

Programming Note

The Examine and Change Signal Action API, sigaction(), is the only mechanism to establish a signal handling procedure for the asynchronous signal SIGTERM. The sigaction() API is only available through the ILE C for IBM AS/400 or the IBM VisualAge C++ for AS/400 languages. The following example shows how the sigaction() API may be invoked from an ILE C for AS/400 program:

   /*
    * Title:  Wait for SIGTERM from ENDJOB *CNTRLD.
    *
    * Purpose:
    *
    *     The following program waits for the asynchronous signal
    *     SIGTERM to be generated by the ENDJOB, ENDSBS, or
    *     PWRDWNSYS command when the *CNTRLD value is specified
    *     for the OPTION keyword.
    */

   #include <sys/signal.h>
   #include <unistd.h>
   #include <stdlib.h>
   #include <stdio.h>

   void catcher( int sig) {

       printf( "SIGTERM signal received from ENDJOB *CNTRLD\n" );

       /*
        *  Take appropriate actions to end application in a
        *  controlled manner
        */

   }

   int main( int argc, char *argvì┘ ) {

       int result = -1;
       struct sigaction sigact, osigact;

       printf( "Start of ENDJOB *CNTRLD test\n" );

       /*
        *  Set up a signal handling procedure to handle the
        *  asynchronous signal SIGTERM being generated by
        *  ENDJOB, ENBSBS, or PWRDWNSYS when the *CNTRLD option is
        *  specified for the OPTION keyword
        */

       sigemptyset( &sigact.sa_mask );
       sigact.sa_flags = 0;
       sigact.sa_handler = catcher;
       sigaction( SIGTERM, &sigact, &osigact );

       printf( "Wait for SIGTERM signal to be generated\n" );
       pause();

       printf( "Back in main procedure\n" );

       printf( "Wait for ENDJOB *IMMED processing to occur\n" );
       pause();

       printf( "ERROR - back in main procedure\n" );
       printf( "End of ENDJOB *CNTRLD test\n" );

       return( result );
   }

The signal handling procedure may be any ILE procedure. Refer to the Signals APIs chapter in the Unix-Type APIs section of the System API Reference manual, publication number SC41-5801-01, for more information on asynchronous signals.