gtpa2m3lApplication Programming

System Error Processing

Errors may occur at any point of processing. There may be programming errors, such as incorrect function parameters, hardware malfunctions, and a variety of unusual conditions such as identification check failures on file operations. Three levels of errors are:

  1. Hardware malfunctions that are overcome by retrying the I/O operation. In this case, error statistics are recorded, but the entry is insulated from the problem (for example, unit checks).
  2. An error is detected by TPF from which the programs related to an entry may be able to recover. In this case the ECB-controlled program regains control.
  3. An error is detected by TPF or the hardware from which the entry cannot recover (for example, an addressing exception generated by an ECB-controlled program). In this case the entry is forced to exit.
  4. An error is detected that makes any more processing inadvisable. This is called catastrophic failure (for example, an operation exception in TPF). Such a failure is detected by various components of TPF and may require a system restart.

The general philosophy of TPF system error processing is:

If an ECB-controlled program is given control after an error is detected, then error indicators are set in the affected ECB. The program is assumed to contain the procedures to respond accordingly. These procedures typically include:

An important reason for returning control to the application (when possible) is to allow response to online terminal operators. The application can respond to the operator in the most meaningful manner once the condition is analyzed. If TPF is unable to return to the application program, it will force a standard message to be sent to the operator/terminal: "Check data and call supervisor".

Given the many possible errors and variations in the nature and complexity of applications, it is not meaningful to generalize about what the application should do. Designers and applications programmers must be alert to the possibility of errors at any point, and diligent in making the best possible response based on what is known. Additional information about TPF system error processing can be found in TPF General Macros and TPF System Macros. Error processing with the control program save area in the ECB is discussed briefly in Control Program Save Area.

SYSRA Macro

The SYSRA macro enables assembly language application programs to:

For a complete description of SYSRA, see TPF General Macros.

Standard Error Functions

The TPF system provides several C functions that can be used for standard error processing by an application program. They are:

All of these functions can be used to generate a main storage dump. The snapc, serrc_op, and serrc_op_ext functions determine whether, after dump processing, the ECB is to be exited or the control returned to the application program. It is an application's responsibility to test the I/O indicators in the ECB (ce1sug) to determine the nature of the abnormality and specify the action to be taken.

The serrc_op function enables an application to:

In addition to the serrc_op capabilities, the serrc_op_ext function enables an application to associate a particular prefix with a system error identification number to determine which user application generated the dump or whether it was an IBM program that generated the dump.

The snapc function allows an application to:

Using C Language Error Functions

Following are several examples of C language error functions:

  1. serrc_op function

    The following example generates a main storage dump bearing the identification number U012345 (U is the default prefix). "ERROR OCCURRED" is the message displayed at the prime CRAS and appended to the dump. TPF returns control to the application program after generating the dump.

      #include <tpfapi.h>
    
      ·
      ·
      ·
    serrc_op(&RETURN;,0x12345,"ERROR OCCURRED",NULL);
  2. serrc_op_ext

    The following example generates a main storage dump bearing identification number A012345 (A is the user-chosen prefix). "ERROR OCCURRED" is the message displayed at the prime CRAS and appended to the dump. TPF returns control to the application program after generating the dump.

      #include <tpfapi.h>
    
      ·
      ·
      ·
    serrc_op_ext(&RETURN.,0x12345,"ERROR OCCURRED",'A',NULL);
  3. snapc function

    This example forces a snapshot dump bearing ID number 12345 with a prefix of 'A' to be issued. Control returns to the program after the dump. The registers are included in the dump. The ECB is used for the SS and SSU names, and terminal ID and the program name are "C001". The snapc_list is snapstuff and the message is "PROGRAM BLEW UP".

    #include <tpfeq.h>
    #include <tpfapi.h>
     
    test()
    {
     struct snapc_list *snapstuff[2]
     
     snapstuff[0]->snapc_len = 4;
     snapstuff[0]->snapc_name = "MYSTUFF ";
     snapstuff[0]->snapc_tag = ecbptr()->ebw000;
     snapstuff[0]->snapc_indir = SNAPC_INDIR;
     
     snapstuff[1]->snapc_len = 0;
     
     snapc(SNAPC_RETURN,0x12345,"PROGRAM BLEW UP",snapstuff,\
           'A',SNAPC_REGS, SNAPC_ECB, "C001");
     
     exit(0):
    }