1 02/13/84  com_err_
  2 
  3 The com_err_ subroutine is the principal subroutine used by commands
  4 for printing error messages.  It is usually called with a nonzero
  5 status code to report an unusual status condition.  It can also be
  6 called with a code of 0 to report an error which does not have a status
  7 code associated with it.  Status codes are described in the
  8 Programmer's Reference Manual.
  9 
 10 See also the active_fnc_err_ subroutine which should be used by active
 11 functions for printing error messages.
 12 
 13 
 14 Entry points in com_err_:
 15    (List is generated by the help command)
 16 
 17 
 18 :Entry: com_err_: 02/13/84  com_err_
 19 
 20 
 21 Function: formats an error message and then signals the command_error
 22 condition.  The default handler for this condition simply returns
 23 control to the com_err_ subroutine, which then writes the error
 24 message on the error_output I/O switch.
 25 
 26 
 27 Syntax:
 28 declare com_err_ entry options (variable);
 29 call com_err_ (code, caller, control_string, arg1, ..., argN);
 30 
 31 
 32 Arguments:
 33 code
 34    is a standard status code, which normally is fixed binary (35), but
 35    can be any computational data type.  (Input) If it is not already
 36    fixed binary (35), it will be converted to fixed binary (35).
 37 caller
 38    is the name (char(*)) of the procedure calling the com_err_
 39    subroutine.  (Input) It can be either varying or nonvarying.
 40 
 41 
 42 control_string
 43    is an ioa_ subroutine control string (char(*)).  (Input) This
 44    argument is optional (see "Notes" below).
 45 argI
 46    are ioa_ subroutine arguments to be substituted into the
 47    control_string argument.  (Input) These arguments are optional.
 48    They can only be used, however, if the control_string argument is
 49    given first (see "Notes" below).
 50 
 51 
 52 Notes:  The error message prepared by the com_err_ subroutine has the
 53 following format:
 54 
 55         caller:  system_message user_message
 56 
 57 caller
 58    is the name of the program detecting the error.
 59 system_message
 60    is a standard message from the error table corresponding to the
 61    value of code.  If code is equal to 0, no system_message is printed.
 62 user_message
 63    is constructed by the ioa_ subroutine from the control_string and
 64    argI arguments.  If the control_string and argI arguments are
 65    omitted, no user_message is printed.
 66 
 67 
 68 If code is error_table_$active_function, com_err_ will print a slightly
 69 different message and signal the active_function_error condition to
 70 prevent the command from being restarted.  The message printed will be:
 71 
 72    caller:  This command cannot be invoked as an active function.
 73             user_message
 74    error:   Attempt to invoke command caller as an active function.
 75 
 76 
 77 If the com_err_ subroutine is passed a nonzero code that does not
 78 correspond to a standard format error table entry, the system_message
 79 is of the form:
 80 
 81         Code ddd
 82 
 83 where ddd is the decimal representation of code.  The argument caller
 84 must not be null or blank; if it is, the handlers for command_error
 85 cannot identify the signalling procedure.
 86 
 87 
 88 :Entry:  suppress_name:  02/13/84 com_err_$suppress_name
 89 
 90 
 91 Function:  This entry point should be used when the caller name and
 92 colon are not wanted.  The caller name is still passed to the
 93 command_error condition handler.  Otherwise, this entry point is the
 94 same as the com_err_ entry point.
 95 
 96 
 97 Syntax:
 98 declare com_err_$suppress_name entry options (variable);
 99 call com_err_$suppress_name (code, caller, control_string,
100      arg1, ..., argN);
101 
102 
103 Arguments:
104 code
105    is a standard status code, which normally is fixed binary (35), but
106    can be any computational data type.  (Input) If it is not already
107    fixed binary (35), it will be converted to fixed binary (35).
108 caller
109    is the name (char(*)) of the procedure calling the com_err_
110    subroutine.  (Input) It can be either varying or nonvarying.
111 
112 
113 control_string
114    is an ioa_ subroutine control string (char(*)).  (Input) This
115    argument is optional.
116 argI
117    are ioa_ subroutine arguments to be substituted into the
118    control_string argument.  (Input) These arguments are optional.
119    They can only be used, however, if the control_string argument is
120    given first.
121 
122 
123 Notes:  See "Notes" under the com_err_ entry point.