08/22/90  get_equal_name_


The get_equal_name_ subroutine accepts an entryname and an equal
name as its input and constructs a target name by combining
components and subcomponents from an entry name and an equal name,
according to the Multics equal convention.  Refer to "Constructing
and Interpreting Names" in the Programmer's Reference Manual for a
description of the equal convention and for the rules used to
construct and interpret equal names.


Entry points in get_equal_name_:
   (List is generated by the help command)


:Entry: get_equal_name_: 08/22/90  get_equal_name_

Function: constructs a target name by combining components and
subcomponents from an entry name and an equal name which are supplied
as arguments according to the Multics equal convention.


Syntax:
declare get_equal_name_ entry (char(*), char(*), char(32),
        fixed bin (35));
call get_equal_name_ (entryname, equal_name, target_name, code);


Arguments:
entryname
   is the entryname from which the target is to be constructed.
   Trailing blanks in the entryname character string are ignored.
   (Input)
equal_name
   is the equal string from which the target is to be constructed.
   Trailing blanks in the equal name character string are ignored.
   (Input)
target_name
   is the target name that is constructed.  (Output)


code
   is a standard system error code.  (Output) It can have one of the
   following values:
   0
      the target name was constructed without error.
   error_table_$bad_equal_name
      the equal name has a bad format.


   error_table_$badequal
      there was no letter or component in the entryname that
      corresponds to a percent character (%) or an equal sign (=)
      in the equal name.

   error_table_$longeql
      the target name to be constructed is longer than 32 characters.
      Only the first 32 characters are returned.


Notes:

If the error_table_$badequal status code is returned, then a
target_name is returned in which null character strings are used to
represent the missing letter or component of entryname.

If the error_table_$longeql status code is returned, then the first
32 characters of the target name to be constructed are returned as
target_name.

The entryname argument that is passed to get_equal_name_ can also be
used as the target_name argument, as long as the argument has a
length of 32 characters.


:Entry:  check_equal_name:  08/22/90  get_equal_name_$check_equal_name


Function:  This entrypoint checks the validity of the equal name
based on the equal convention.


Syntax:
declare get_equal_name_$check_equal_name entry (char(*),
        fixed bin (35));
call get_equal_name_$check_equal_name (equalname, code);


Arguments:
equalname
   is the equal string to be checked.  (Input)
code
   is a standard system error code.  (Output) It can have the same
   values described for get_equal_name_.


:Entry: component: 08/22/90  get_equal_name_$component

Function: constructs a target archive and component name by
substituting components and or characters from the archive and
component name into the equal names, according to the Multics archive
component pathname equal convention.  Refer to the Programmer's
Reference Manual for a description of archive component pathnames and
the equal convention.


Syntax:
declare get_equal_name_$component entry (char(*), char(*), char(32),
        char(*), char(32), fixed bin (35));
call get_equal_name_$component (entryname, equal_entryname,
        equal_component, target_entryname, target_component, code);


Arguments:
entryname
   is the archive name from which the target archive name is
   constructed, or is the entryname from which the target component
   name is constructed if the source pathname is not an archive
   component pathname.  (Input)
component
   is the component name from which the target component name is
   constructed, or is a null string if the source pathname is not an
   archive component pathname.  (Input)
equal_entryname
   is the equal name from which the target archive name is
   constructed or is the equal name from which the target entryname
   is constructed if the target pathname is not an archive component
   pathname.  (Input)


equal_component
   is the equal name from which the target component name is
   constructed or is a null string if the target pathname is not an
   archive component pathname.  (Input)
target_entryname
   is the target archive name that is constructed or is the target
   entryname that is constructed if the target pathname is not an
   archive component pathname.  (Output)
target_component
   is the target component name that is constructed or is a null
   string if the target pathname is not an archive component
   pathname.  (Output)


code
   is a standard system error code.  (Output) It can have one of the
   following:

   error_table_$bad_equal_name
      either the equal_entryname or equal_component has a bad format.

   error_table_$badequal
      there was no letter or component in the archive or component
      name that corresponds to a percent character (%) or an equal
      sign (=) in the appropriate equal name.


   error_table_$longeql
      the target archive or component name to be constructed is
      longer than 32 characters.

   error_table_$no_archive_for_equal
      the target pathname has an equal name in the archive name
      position but the source pathname is not an archive component
      pathname.


Notes:

If the error_table_$badequal status code is returned, the name
returned in the appropriate output argument is constructed using null
character strings to represent the letter or component names missing
from the source name.

If the error_table_$longequal status code is returned, then the first
32 characters of the constructed name are returned in the appropriate
output argument.

The two parts of input arguments to this subroutine are expected to
be the output arguments from two calls to expand_pathname_$component,
one call for the source pathname and one for the pathname containing
the equal names.


The output arguments of this subroutine should be used in a call to
the initiate _file_$component subroutine.  For example:

call expand_pathname_$component (arg1, source_dir, source_ename,
	source_comp, code);
if code ^= 0 then ...

call expand_pathname_$component (arg2, target_dir, equal_entry,
	equal_component, code);
if code ^= 0 then ...

call get_equal_name_$component (source_ename, source_comp,
     equal_entry, equal_component, target_ename, target_comp, code);
if code ^= 0 then ...


call initiate_file_$component (source_dir, source_ename, source_comp,
	R_ACCESS, source_ptr, source_bit_count, code);
if code ^= 0 then ...

call initiate_file_$component (target_dir, target_ename, target_comp,
	R_ACCESS, target_ptr, target_bit_count, code);
if code ^= 0 then ...


                                          -----------------------------------------------------------


Historical Background

This edition of the Multics software materials and documentation is provided and donated
to Massachusetts Institute of Technology by Group BULL including BULL HN Information Systems Inc. 
as a contribution to computer science knowledge.  
This donation is made also to give evidence of the common contributions of Massachusetts Institute of Technology,
Bell Laboratories, General Electric, Honeywell Information Systems Inc., Honeywell BULL Inc., Groupe BULL
and BULL HN Information Systems Inc. to the development of this operating system. 
Multics development was initiated by Massachusetts Institute of Technology Project MAC (1963-1970),
renamed the MIT Laboratory for Computer Science and Artificial Intelligence in the mid 1970s, under the leadership
of Professor Fernando Jose Corbato. Users consider that Multics provided the best software architecture 
for managing computer hardware properly and for executing programs. Many subsequent operating systems 
incorporated Multics principles.
Multics was distributed in 1975 to 2000 by Group Bull in Europe , and in the U.S. by Bull HN Information Systems Inc., 
as successor in interest by change in name only to Honeywell Bull Inc. and Honeywell Information Systems Inc. .

                                          -----------------------------------------------------------

Permission to use, copy, modify, and distribute these programs and their documentation for any purpose and without
fee is hereby granted,provided that the below copyright notice and historical background appear in all copies
and that both the copyright notice and historical background and this permission notice appear in supporting
documentation, and that the names of MIT, HIS, BULL or BULL HN not be used in advertising or publicity pertaining
to distribution of the programs without specific prior written permission.
    Copyright 1972 by Massachusetts Institute of Technology and Honeywell Information Systems Inc.
    Copyright 2006 by BULL HN Information Systems Inc.
    Copyright 2006 by Bull SAS
    All Rights Reserved