Changes between Version 1 and Version 2 of Ticket #391


Ignore:
Timestamp:
06/19/2026 08:21:21 AM (5 weeks ago)
Author:
Gary Dixon
Comment:

Legend:

Unmodified
Added
Removed
Modified

  • Ticket #391

    • Property Component Standard Library → Documentation
    • Property Summary exec_com &condition_info_ptr parameter does not point to a good condition_info structure → exec_com &condition_info_ptr parameter is mis-described.
    • Property Version MR12.8 → MR12.5

  • Ticket #391 – Description

    v1 v2  
    33{{{
    44&on active_function_error &begin
    5    &set status_code &[status_code_name &condition_info_ptr]
     5   &set status_code
     6&+      &[status_code_name &condition_name &condition_info_ptr]
    67   &print Condition &condition_name occurred to report event
    78   &print &"   " at location &condition_info_ptr
    8    call cu_$cl
     9   &print &"   " with status code named:  &(status_code)
     10   &goto EXIT
    911   &end
    10 ...
     12
     13string [path <><>]
     14
     15&label EXIT
     16&quit
    1117}}}
    1218
    13 The &condition_info_ptr parameter is supposed to expand to a virtual pointer
    14 (<segment_number>|<offset>) locating a condition_info structure 
    15 describing the condition being handled.  This permits a command or
    16 active function to access added details about the event being handled
    17 by the current on-unit invocation.  For example, the on-unit shown above
    18 sets the status_code variable to the name of the Multics status code
    19 being reported in a com_err_ or active_fnc_err_ subroutine call.
     19The &condition_info_ptr parameter is documented to expand to a
     20virtual pointer (<segment_number>|<offset>) locating a
     21condition_info structure describing the condition being handled. 
    2022
    21 However, the exec_com interpreter does not properly call the
    22 find_condition_info_ subroutine to fill-in elements of the
    23 condition_info structure before executing line of the on-unit.  The
    24 &condition_info_ptr parameter does locate a data structure, but
    25 elements of that structure contain previous stack data because
    26 the structure was not properly initialized with details from the
    27 reported event.
     23This description is wrong.  &condition_info_ptr actually locates
     24a condition_info_header structure that begins the specific data
     25structure associated with the signaled condition named &condition_name.
    2826
    29 Executing an exec_com program with the statements above currently
    30 generates a virtual_ptr value for the &condition_info_ptr that has
    31 a correct format for a pointer locator, but points to storage for a
    32 condition_info structure with bogus element contents.
     27For example, the data structure associated with a command_error or
     28active_function_error condition is called com_af_error_info.  It is
     29declared as shown below.
     30
     31{{{
     32/* BEGIN INCLUDE FILE com_af_error_info.incl.pl1 April 81 BIM */
     33/* format: style2 */
     34
     35/* info structures for command error and active function error */
     36/* The include file condition_info_header must be included to  */
     37/* use this file */
     38
     39     dcl com_af_error_info_ptr  pointer;
     40     dcl 1 com_af_error_info    aligned based (com_af_error_info_ptr),
     41           2 header             aligned like condition_info_header,
     42           2 name_ptr           ptr,
     43           2 name_lth           fixed bin,
     44           2 errmess_ptr        ptr,
     45           2 errmess_lth        fixed bin (21),
     46           2 max_errmess_lth    fixed bin (21),
     47           2 print_sw           bit (1);
     48
     49dcl com_af_error_info_version_3 internal static options (constant)
     50                                init (3);
     51
     52/* END INCLUDE FILE com_af_error_info */
     53
     54/* BEGIN INCLUDE FILE condition_info_header.incl.pl1 BIM 1981 */
     55/* format: style2 */
     56
     57 dcl condition_info_header_ptr  pointer;
     58 dcl 1 condition_info_header    based (condition_info_header_ptr)
     59                                aligned,
     60     2 length                   fixed bin,              /* length in words of this structure */
     61     2 version                  fixed bin,              /* version number of this structure */
     62     2 action_flags             aligned,                /* tell handler how to proceed */
     63       3 cant_restart           bit (1) unaligned,      /* caller doesn't ever want to be returned to */
     64       3 default_restart        bit (1) unaligned,      /* caller can be returned to with no further action */
     65       3 quiet_restart          bit (1) unaligned,      /* return, and print no message */
     66       3 support_signal         bit (1) unaligned,      /* treat this signal as if the signalling procedure had the support bit set */
     67                                                        /* if the signalling procedure had the support bit set, do the same for its caller */
     68       3 pad                    bit (32) unaligned,
     69     2 info_string              char (256) varying,     /* may contain printable message */
     70     2 status_code              fixed bin (35);         /* if^=0, code interpretable by com_err_ */
     71
     72/* END INCLUDE FILE condition_info_header.incl.pl1 */
     73}}}
     74
     75The value displayed by the &condition_info_ptr parameter is
     76associated with a condition_info structure only in the sense
     77that condition_info.info_ptr holds the value reported by that
     78parameter.
     79
     80Executing an exec_com program with the statements above correctly
     81reports the value stored in com_af_error_info.status_code.
    3382
    3483{{{
    … …  
    3685Condition active_function_error occurred to report event
    3786   at location 234|14716
     87   with a status_code named: error_table_$bad_path
    3888
    3989r 16:54 0.192 7 level 2
    4090
    41 ds 234|14716 -as condition_info -lg
    42 014716
    43 condition_info                @ 234|14716
    44   mc_ptr = 0(0),au [invalid]
    45   version = 0,
    46   condition_name = ""
    47   info_ptr = 6(0) [invalid]
    48   wc_ptr = 247|7034   [pd]>!BBBKbbxJZGjlPk.area.linker
    49   loc_ptr = 234|14562   [pd]>stack_4
    50   flags                       @ 234|14740
    51     OFF: crawlout
    52   user_loc_ptr = 234|14516   [pd]>stack_4
    53 r 16:54 0.182 5 level 2
    5491}}}
    5592
    56 The condition_name is blank, and most other data in the structure is
    57 invalid.  This is especially true of condition_info.info_ptr which
    58 is supposed to locate the com_af_error_info structure created by
    59 active_fnc_err_ when it signals the active_function_error condition.
    60 
    61 The data at location 234|14716 is shown by the dump_segment command.
     93This documentation error should eventually be corrected.  Meanwhile,
     94this ticket can warn users about the documentation flaw.