exec_com &condition_info_ptr parameter is mis-described.

[gary.c.dixon@…]

The exec_com (version 2) program language includes a set of features which enable the program to establish an on-unit to handle one or more conditions that might occur while the program is executing.

&on active_function_error &begin
   &set status_code 
&+      &[status_code_name &condition_name &condition_info_ptr]
   &print Condition &condition_name occurred to report event
   &print &"   " at location &condition_info_ptr 
   &print &"   " with status code named:  &(status_code)
   &goto EXIT
   &end

string [path <><>]

&label EXIT
&quit

The &condition_info_ptr parameter is documented to expand to a
virtual pointer (<segment_number>|<offset>) locating a
condition_info structure describing the condition being handled.

This description is wrong. &condition_info_ptr actually locates
a condition_info_header structure that begins the specific data
structure associated with the signaled condition named &condition_name.

For example, the data structure associated with a command_error or
active_function_error condition is called com_af_error_info. It is
declared as shown below.

/* BEGIN INCLUDE FILE com_af_error_info.incl.pl1 April 81 BIM */
/* format: style2 */

/* info structures for command error and active function error */
/* The include file condition_info_header must be included to  */
/* use this file */

     dcl com_af_error_info_ptr  pointer;
     dcl 1 com_af_error_info    aligned based (com_af_error_info_ptr),
           2 header             aligned like condition_info_header,
           2 name_ptr           ptr,
           2 name_lth           fixed bin,
           2 errmess_ptr        ptr,
           2 errmess_lth        fixed bin (21),
           2 max_errmess_lth    fixed bin (21),
           2 print_sw           bit (1);

dcl com_af_error_info_version_3 internal static options (constant) 
                                init (3);

/* END INCLUDE FILE com_af_error_info */

/* BEGIN INCLUDE FILE condition_info_header.incl.pl1 BIM 1981 */
/* format: style2 */

 dcl condition_info_header_ptr  pointer;
 dcl 1 condition_info_header    based (condition_info_header_ptr)
                                aligned,
     2 length                   fixed bin,              /* length in words of this structure */
     2 version                  fixed bin,              /* version number of this structure */
     2 action_flags             aligned,                /* tell handler how to proceed */
       3 cant_restart           bit (1) unaligned,      /* caller doesn't ever want to be returned to */
       3 default_restart        bit (1) unaligned,      /* caller can be returned to with no further action */
       3 quiet_restart          bit (1) unaligned,      /* return, and print no message */
       3 support_signal         bit (1) unaligned,      /* treat this signal as if the signalling procedure had the support bit set */
                                                        /* if the signalling procedure had the support bit set, do the same for its caller */
       3 pad                    bit (32) unaligned,
     2 info_string              char (256) varying,     /* may contain printable message */
     2 status_code              fixed bin (35);         /* if^=0, code interpretable by com_err_ */

/* END INCLUDE FILE condition_info_header.incl.pl1 */

The value displayed by the &condition_info_ptr parameter is
associated with a condition_info structure only in the sense
that condition_info.info_ptr holds the value reported by that
parameter.

Executing an exec_com program with the statements above correctly
reports the value stored in com_af_error_info.status_code.

ec test_status
Condition active_function_error occurred to report event
   at location 234|14716 
   with a status_code named: error_table_$bad_path

r 16:54 0.192 7 level 2

This documentation error should eventually be corrected. Meanwhile,
this ticket can warn users about the documentation flaw in
the Multics Commands and Active Functions (AG92-06B) page 3-322
where the &condition_info_ptr parameter is described.