Museum

PGM_$SET_SEVERITY                 Domain/OS                  PGM_$SET_SEVERITY


NAME
     pgm_$set_severity - set the exit severity level

SYNOPSIS (C)
     #include <apollo/base.h>
     #include <apollo/pgm.h>

     void pgm_$set_severity(pgm_$mode &severity_level)

SYNOPSIS (Pascal)
     %include '/sys/ins/base.ins.pas';
     %include '/sys/ins/pgm.ins.pas';

     procedure pgm_$set_severity(in severity_level: integer);

SYNOPSIS (FORTRAN)
     %include '/sys/ins/base.ins.ftn'
     %include '/sys/ins/pgm.ins.ftn'

           integer*2 severity_level

           call pgm_$set_severity(severity_level)

DESCRIPTION
     Pgm_$set_severity sets the severity level for the calling process to
     severity_level.  Every invoked program returns a severity level to its
     invoking process, and by default the severity level is pgm_$ok.

   Choosing an Exit Severity Level
     The following are examples of appropriate choices for an exit severity
     level:

     ⊕  Pgm_$true or pgm_$false would be returned by a program that compared
        two values or tested some other condition.

     ⊕  Pgm_$warning would be returned by a file deleting program when its
        target file didn't exist.

     ⊕  Pgm_$error would be returned by a compiler if the input program con-
        tained a correctable syntax error, but the object was correct.

     ⊕  Pgm_$output_invalid would be returned by a compiler if an error in the
        input program resulted in an incorrect object.

     ⊕  Pgm_$internal_fatal would be returned by a program that could not
        proceed because its data was corrupted.

     ⊕  Pgm_$program_faulted would be returned by a program that received a
        fault and wished to inform the invoking program without resignaling
        the fault.

     severity_level
          The exit severity level to return to the invoking process.  Specify
          only one of the following values:

          pgm_$ok
               The program completed successfully and performed the requested
               action.

          pgm_$true
               The program completed successfully.  Its purpose was to test a
               condition, and the value of that condition was true.

          pgm_$false
               The program completed successfully.  Its purpose was to test a
               condition, and the value of that condition was false.

          pgm_$warning
               The program completed successfully and performed the requested
               action.  However, an unusual (but nonfatal) condition was
               detected.

          pgm_$error
               The program could not perform the requested action because of
               syntactic or semantic errors in the input, though the output is
               sound.

          pgm_$output_invalid
               The program could not perform the requested action because of
               syntactic or semantic errors in the input, and the output is
               not sound.

          pgm_$internal_fatal
               The program detected an internal fatal error and ceased pro-
               cessing.  The state of the output is not defined.

          pgm_$program_faulted
               The program detected and handled a fault.

          If severity_level is set greater than pgm_$max_severity, the status
          returned to the invoking process will be just pgm_$max_severity.

NOTES
     C programs that use pgm_$set_severity must be bound with the -entry
     option to /com/bind or the -e option to /bin/ld to specify the start rou-
     tine manually (normally "main").  The best alternative to
     pgm_$set_severity is to use a UNIX exit(2) or a return to return a pro-
     gram status.