Museum

ERROR_$GET_TEXT                   Domain/OS                    ERROR_$GET_TEXT


NAME
     error_$get_text - get error reporting text

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

     void error_$get_text(
          status_$t &status,
          error_$string_t subsys_t,
          short *subsys_l,
          error_$string_t module_t,
          short *module_l,
          error_$string_t code_t,
          short *code_l)

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

     procedure error_$get_text(
          in status: status_$t;
          out sub_n: error_$string_t;
          out sub_nl: integer;
          out mod_n: error_$string_t;
          out mod_nl: integer;
          out err_t: error_$string_t;
          out err_l: integer);

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

           integer*4 status
           integer*2 subsys_l, module_l, code_l
           character subsys_t*80, module_t*80, code_t*80

           call error_$get_text(status, subsys_t, subsys_l, module_t,
          &                     module_l, code_t, code_l)

DESCRIPTION
     Error_$get_text supplies predefined strings for reporting the completion
     status of a Domain/OS call.  The strings supplied are up to 80 bytes long
     and not null terminated.  A program should check the length arguments
     (subsys_l, module_l, and code_l) before using the strings supplied by
     error_$find_text.

     status
          The completion status from a Domain/OS call.

     subsys_t
          The name of the subsystem associated with the subsys field in
          status.

     subsys_l
          The number of bytes in subsys_t.  A subsys_l of 0 indicates that the
          completion status passed in status is invalid, and subsys_t,
          module_t, and code_t will not contain any useful information.

     module_t
          The name of the module associated with the modc field in status.

     module_l
          The number of bytes in module_t.  A module_l of 0 indicates that the
          modc and code fields of the completion status passed in status are
          invalid, and module_t and code_t will not contain any useful infor-
          mation.

     code_t
          The diagnostic text associated with the code field in status.

     code_l
          The number of bytes in code_t.  A code_l of 0 indicates that the
          code field of the completion status passed in status is invalid, and
          code_t will not contain any useful information.

NOTES
     Error_$get_text and error_$find_text provide access to the same prede-
     fined strings, but error_$get_text actually copies the strings into
     buffers allocated by the calling program, whereas error_$find_text only
     supplies pointers to the strings.

     Because pointers are clumsy to use in FORTRAN, FORTRAN programmers will
     probably want to use error_$get_text.  C and Pascal programmers may also
     want to use error_$get_text when they plan to manipulate the returned
     text before printing.

     Because the strings returned by error_$get_text are not null terminated,
     a C program should use the length arguments (subsys_l, module_l, and
     code_l) to properly terminate the strings before processing them with
     standard libraries.

SEE ALSO
     error_$find_test, status_$intro.