09/23/85	ioa_

The ioa_ subroutine is used for formatting a character string from
fixed-point numbers, floating-point numbers, character strings, bit
strings, and pointers.  The character string is constructed according
to the control characters entered in a "control string" and a variable
list of arguments that are either edited into the output string in
character form, or are used in some way to control the formatting of
the string.  The entire procedure is similar to formatted output in
PL/I or FORTRAN.


The ioa_ subroutine has several entry points in order to provide
options concerning the formatting and disposition of the resulting
string.  Since any entry point can be called with various different
arguments, each must be declared (in PL/I) with the following
attributes:
     declare ioa_ entry options (variable);
This entry declaration is assumed in all of the entries discussed.


Calls to the ioa_ subroutine normally append a newline character to the
end of the string created.  In order to suppress this character, most
types of ioa_ calls have a corresponding entry point with "nnl" (for no
newline character); this entry point does the same editing.


Notes on Control Strings: 
All calls to the ioa_ subroutine require a control_string argument.
This is a character string consisting of either text to be copied,
ioa_ control codes, or both.  The control codes are always identified
by a leading circumflex character (^).  For a complete list of control 
codes, type "help ioa_control.gi".


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


:Entry: ioa_: nnl:  09/10 81  ioa_, ioa_$nnl


Function: These two entry points format the input data according to
the control string and write the resulting string on the user_output
I/O switch.


Syntax:
call ioa_ (control_string, arg1, ..., argN);


Arguments:
control_string
   is a character string (char(*) or char(*) varying) of text and 
   control characters that determines how the resulting string is to 
   be formed.  (Input)
argI
   are a variable number of arguments (possibly none) that are either 
   edited into the resulting string, or used to control the formatting 
   of it.  (Input)


:Entry: general_rs: 09/10/81 ioa_$general_rs


Function: This entry point is used to provide the ioa_ subroutine with
a control string and format arguments taken from a previously created
argument list to which a pointer has been obtained.


Syntax:
declare ioa_$general_rs entry (ptr, fixed bin, fixed bin, char(*),
     fixed bin(21), bit(1) aligned, bit(1) aligned);
call ioa_$general_rs (arglist_ptr, cs_argno, ff_argno, ret_string, 
     len, pad_sw, nl_sw);


Arguments:
arglist_ptr
   is a pointer to the argument list from which the control string 
   and format arguments are to be taken.  (Input)
cs_argno
   is the argument number of the control string in the argument list 
   pointed to by arglist_ptr.	(Input)
ff_argno
   is the argument number of the first format argument in the argument
   list pointed to by arglist_ptr.	 (Input)
ret_string
   contains the formatted string.  (Output) It should be large enough
   to allow for expansion.
len
   specifies the number of significant characters in ret_string.  
   (Output)


pad_sw
   is a switch to indicate whether the formatted string is padded.  
   (Input)
   "0"b	no
   "1"b	yes
nl_sw
   is a switch to indicate whether a newline character is appended to
   the formatted string.  (Input)
   "0"b	no
   "1"b	yes


:Entry: general_rs_control_string: 08/29/85 ioa_$general_rs_control_string


Function: This entry point is used to provide the ioa_ subroutine with
format arguments taken from a previously created argument list to
which a pointer has been obtained.


Syntax:
declare ioa_$general_rs_control_string entry (ptr, char (*),
     fixed bin, char(*), fixed bin(21), bit(1) aligned,
     bit(1) aligned);
call ioa_$general_rs_control_string (arglist_ptr, control_string,
     ff_argno, ret_string, len, pad_sw, nl_sw);


Arguments:
arglist_ptr
   is a pointer to the argument list from which the format arguments
   are to be taken.  (Input)
control_string
   is the control string.	(Input)
ff_argno
   is the argument number of the first format argument in the argument
   list pointed to by arglist_ptr.	 (Input)
ret_string
   contains the formatted string.  (Output) It should be large enough
   to allow for expansion.
len
   specifies the number of significant characters in ret_string.
   (Output)


pad_sw
   is a switch to indicate whether the formatted string is padded.
   (Input)
   "0"b	no
   "1"b	yes
nl_sw
   is a switch to indicate whether a newline character is appended to
   the formatted string.  (Input)
   "0"b	no
   "1"b	yes


:Entry:  ioa_stream:  ioa_stream_nnl:  09/10/81 ioa_$ioa_stream, ioa_$ioa_stream_nnl


Function: These two entries format the resulting string as above, but
the string is then written to an I/O switch specified by the
switch_name argument in the parameter list.


Syntax:
call ioa_$ioa_stream (switch_name, control_string, arg1, ..., argN);


Arguments:
switch_name
   is the name of the I/O switch (char(*)) to which the resulting 
   character string is to be written.  (Input)
control_string
   is a character string (char(*) or char(*) varying) of text and 
   control characters that determines how the resulting string is to 
   be formed.  (Input)
argI
   are a variable number of arguments (possibly none) that are either 
   edited into the resulting string, or used to control the formatting
   of it.  (Input)


:Entry:  ioa_switch:  ioa_switch_nnl:  09/10/81  ioa_$ioa_switch, ioa_$ioa_switch_nnl


Function: These two entry points are identical to the ioa_$ioa_stream
and ioa_$ioa_stream_nnl entry points except that the I/O switch is
specified by a pointer to its control block, rather than by name.
Since this saves an extra call in the I/O system to locate the control
block, these calls are more efficient than ioa_$ioa_stream calls.


Syntax:
call ioa_$ioa_switch (iocb_ptr, control_string, arg1, ..., argN);


Arguments:
iocb_ptr
   is a pointer to the control block of the switch.  (Input)
control_string
   is a character string (char(*) or char(*) varying) of text and 
   control characters that determines how the resulting string is to 
   be formed.  (Input)
argI
   are a variable number of arguments (possibly none) that are either
   edited into the resulting string, or used to control the formatting 
   of it.  (Input)


:Entry:  rs: rsnnl: rsnp: rsnpnnl:  09/10/81  ioa_$rs, ioa_$rsnnl, ioa_$rsnp, ioa_$rsnpnnl

Function: These entry points edit the resulting string as in the above
calls, but instead of being written to an I/O switch as the other ioa_
entry points, the string is passed back to the caller.  The user
program must provide a character string variable into which the string
can be returned.  This variable may be varying or nonvarying, aligned
or unaligned, and of any length.  The resulting string is truncated if
it exceeds the length of the character string provided.


Syntax:
call ioa_$rs (control_string, ret_string, len, arg1, ..., argN);


Arguments:
control_string
   is a character string (char(*) or char(*) varying) of text and 
   control characters that determines how the resulting string is to 
   be formed.  (Input)
ret_string
   is a string (char(*) or char(*) varying) into which the output 
   string will be edited.  (Output)
len
   is the length of the returned string (fixed bin(21)).  (Output)
argI
   are a variable number of arguments (possibly none) that are either
   edited into the resulting string, or used to control the formatting
   of it.  (Input)


Notes:
If the output string is nonvarying, it is padded on the right with spaces if it
is not completely filled; however, if the call is to either the ioa_$rsnp or
ioa_$rsnpnnl entry points, the padding is not done.  Both the ioa_$rsnnl and
ioa_$rsnpnnl entry points omit the newline character in the normal way.  All of
these entry points also return the length of the significant data edited into
the string.



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


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