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 ...
