%STATUS (Return File or Program Status)

%STATUS{(file_name)}

%STATUS returns the most recent value set for the program or file status. %STATUS is set whenever the program status or any file status changes, usually when an error occurs.

If %STATUS is used without the optional file_name parameter, then it returns the program or file status most recently changed. If a file is specified, the value contained in the INFDS *STATUS field for the specified file is returned. The INFDS does not have to be specified for the file.

%STATUS starts with a return value of 00000 and is reset to 00000 before any operation with an 'E' extender specified begins.

%STATUS is best checked immediately after an operation with the 'E' extender or an error indicator specified, or at the beginning of an INFSR or the *PSSR subroutine.

For more information, see File Operations, Result Operations, or Built-in Functions.

The operations that set %STATUS are:
Figure 1. %STATUS and %ERROR with 'E' Extender
 *..1....+....2....+....3....+....4....+....5....+....6....+....7...+....
 * The 'E' extender indicates that if an error occurs, the error
 * is to be handled as though an error indicator were coded.
 * The success of the operation can then be checked using the
 * %ERROR built-in function.  The status associated with the error
 * can be checked using the %STATUS built-in function.
 /FREE
    exfmt(e) InFile;
    if %error;
       exsr CheckError;
    endif;
 
  //-------------------------------------------------------------------
  // CheckError: Subroutine to process a file I/O error
  //-------------------------------------------------------------------
    begsr CheckError;
       select;
       when  %status < 01000;
 
          // No error occurred
       when  %status = 01211;
          // Attempted to read a file that was not open
          exsr InternalError;
 
       when  %status = 01331;
          // The wait time was exceeded for a READ operation
          exsr TimeOut;
 
       when  %status = 01261;
          // Operation to unacquired device
          exsr DeviceError;
 
       when  %status = 01251;
          // Permanent I/O error
          exsr PermError;
 
       other;
          // Some other error occurred
          exsr FileError;
       endsl;
    endsr;
 /END-FREE
Figure 2. %STATUS and %ERROR with 'E' Extender, Error Indicator and *PSSR
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords++++++++++++++++++++++++++
D Zero            S              5P 0 INZ(0)
CL0N01Factor1+++++++Opcode(E)+Factor2+++++++Result++++++++Len++D+HiLoEq....
 * %STATUS starts with a value of 0
 *
 * The following SCAN operation will cause a branch to the *PSSR
 * because the start position has a value of 0.
C     'A'           SCAN      'ABC':Zero    Pos
C     BAD_SCAN      TAG
 * The following EXFMT operation has an 'E' extender, so %STATUS will
 * be set to 0 before the operation begins.  Therefore, it is
 * valid to check %STATUS after the operation.
 * Since the 'E' extender was coded, %ERROR can also be used to
 * check if an error occurred.
C                   EXFMT(E)  REC1
C                   IF        %ERROR
C                   SELECT
C                   WHEN      %STATUS = 01255
C ...
C                   WHEN      %STATUS = 01299
C ...                                                                
 * The following scan operation has an error indicator.  %STATUS will
 * not be set to 0 before the operation begins, but %STATUS can be
 * reasonably checked if the error indicator is on.
C     'A'           SCAN      'ABC':Zero    Pos                    10
C                   IF        *IN10 AND %STATUS = 00100
C ...
                                                                      
 * The following scan operation does not produce an error.
 * Since there is no 'E' extender %STATUS will not be set to 0,
 * so it would return a value of 00100 from the previous error.
 * Therefore, it is unwise to use %STATUS after an operation that
 * does not have an error indicator or the 'E' extender coded since
 * you cannot be sure that the value pertains to the previous
 * operation.
C     'A'           SCAN      'ABC'         Pos
C ...
C     *PSSR         BEGSR
 * %STATUS can be used in the *PSSR since an error must have occurred.
C                   IF        %STATUS = 00100
C                   GOTO      BAD_SCAN
C ...