1 2019-05-24  ioa_
  2 
  3 The ioa_ subroutine is used for formatting a character string from
  4 fixed-point numbers, floating-point numbers, character strings, bit
  5 strings, and pointers.  The character string is constructed according
  6 to the control characters entered in a "control string" and a variable
  7 list of arguments that are either edited into the output string in
  8 character form, or are used in some way to control the formatting of
  9 the string.  The entire procedure is similar to formatted output in
 10 PL/I or FORTRAN.
 11 
 12 
 13 The ioa_ subroutine has several entry points in order to provide
 14 options concerning the formatting and disposition of the resulting
 15 string.  Since any entry point can be called with various different
 16 arguments, each must be declared (in PL/I) with the following
 17 attributes:
 18      declare ioa_ entry options (variable);
 19 This entry declaration is assumed in all of the entries discussed.
 20 
 21 
 22 Calls to the ioa_ subroutine normally append a newline character to the
 23 end of the string created.  In order to suppress this character, most
 24 types of ioa_ calls have a corresponding entry point with "nnl" (for no
 25 newline character); this entry point does the same editing.
 26 
 27 
 28 Notes on control strings:
 29 All calls to the ioa_ subroutine require a control_string argument.
 30 This is a character string consisting of either text to be copied,
 31 ioa_ control codes, or both.  The control codes are always identified
 32 by a leading circumflex character (^).  For a complete list of control
 33 codes, type "help ioa_control.gi".
 34 
 35 
 36 Entry points in ioa_:
 37    (List is generated by the help command)
 38 
 39 
 40 :Entry: ioa_: nnl:  2019-05-24  ioa_, ioa_$nnl
 41 
 42 
 43 Function: These two entry points format the input data according to
 44 the control string and write the resulting string on the user_output
 45 I/O switch.
 46 
 47 
 48 Syntax:
 49 declare ioa_ entry options(variable);
 50 call ioa_ (control_string, arg1, ..., argN);
 51 declare ioa_$nnl entry options(variable);
 52 call ioa_$nnl (control_string, arg1, ..., argN);
 53 
 54 
 55 Arguments:
 56 control_string
 57    is a character string (char(*) or char(*) varying) of text and
 58    control characters that determines how the resulting string is to
 59    be formed.  (Input)
 60 argI
 61    are a variable number of arguments (possibly none) that are either
 62    edited into the resulting string, or used to control the formatting
 63    of it.  (Input)
 64 
 65 
 66 :Entry: general_rs: 1981-09-10  ioa_$general_rs
 67 
 68 
 69 Function: This entry point is used to provide the ioa_ subroutine with
 70 a control string and format arguments taken from a previously created
 71 argument list to which a pointer has been obtained.
 72 
 73 
 74 Syntax:
 75 declare ioa_$general_rs entry (ptr, fixed bin, fixed bin, char(*),
 76      fixed bin(21), bit(1) aligned, bit(1) aligned);
 77 call ioa_$general_rs (arglist_ptr, cs_argno, ff_argno, ret_string,
 78      len, pad_sw, nl_sw);
 79 
 80 
 81 Arguments:
 82 arglist_ptr
 83    is a pointer to the argument list from which the control string
 84    and format arguments are to be taken.  (Input)
 85 cs_argno
 86    is the argument number of the control string in the argument list
 87    pointed to by arglist_ptr. (Input)
 88 ff_argno
 89    is the argument number of the first format argument in the argument
 90    list pointed to by arglist_ptr.       (Input)
 91 ret_string
 92    contains the formatted string.  (Output) It should be large enough
 93    to allow for expansion.
 94 
 95 
 96 len
 97    specifies the number of significant characters in ret_string.
 98    (Output)
 99 pad_sw
100    is a switch to indicate whether the formatted string is padded.
101    (Input)
102    "0"b   no
103    "1"b   yes
104 nl_sw
105    is a switch to indicate whether a newline character is appended to
106    the formatted string.  (Input)
107    "0"b   no
108    "1"b   yes
109 
110 
111 :Entry: general_rs_control_string: 1985-08-29  ioa_$general_rs_control_string
112 
113 
114 Function: This entry point is used to provide the ioa_ subroutine with
115 format arguments taken from a previously created argument list to
116 which a pointer has been obtained.
117 
118 
119 Syntax:
120 declare ioa_$general_rs_control_string entry (ptr, char (*),
121      fixed bin, char(*), fixed bin(21), bit(1) aligned,
122      bit(1) aligned);
123 call ioa_$general_rs_control_string (arglist_ptr, control_string,
124      ff_argno, ret_string, len, pad_sw, nl_sw);
125 
126 
127 Arguments:
128 arglist_ptr
129    is a pointer to the argument list from which the format arguments
130    are to be taken.  (Input)
131 control_string
132    is the control string.     (Input)
133 ff_argno
134    is the argument number of the first format argument in the argument
135    list pointed to by arglist_ptr.       (Input)
136 ret_string
137    contains the formatted string.  (Output) It should be large enough
138    to allow for expansion.
139 len
140    specifies the number of significant characters in ret_string.
141    (Output)
142 
143 
144 pad_sw
145    is a switch to indicate whether the formatted string is padded.
146    (Input)
147    "0"b   no
148    "1"b   yes
149 nl_sw
150    is a switch to indicate whether a newline character is appended to
151    the formatted string.  (Input)
152    "0"b   no
153    "1"b   yes
154 
155 
156 :Entry:  ioa_stream:  ioa_stream_nnl:  2019-05-24  ioa_$ioa_stream, ioa_$ioa_stream_nnl
157 
158 
159 Function: These two entries format the resulting string as above, but
160 the string is then written to an I/O switch specified by the
161 switch_name argument in the parameter list.
162 
163 
164 Syntax:
165 declare ioa_$ioa_stream entry options(variable);
166 call ioa_$ioa_stream (switch_name, control_string, arg1,...,argN);
167 declare ioa_$ioa_stream_nnl entry options(variable);
168 call ioa_$ioa_stream_nnl (switch_name, control_string, arg1,...,argN);
169 
170 
171 Arguments:
172 switch_name
173    is the name of the I/O switch (char(*)) to which the resulting
174    character string is to be written.  (Input)
175 control_string
176    is a character string (char(*) or char(*) varying) of text and
177    control characters that determines how the resulting string is to
178    be formed.  (Input)
179 argI
180    are a variable number of arguments (possibly none) that are either
181    edited into the resulting string, or used to control the formatting
182    of it.  (Input)
183 
184 
185 :Entry:  ioa_switch:  ioa_switch_nnl:  2019-05-24 ioa_$ioa_switch, ioa_$ioa_switch_nnl
186 
187 
188 Function: These two entry points are identical to the ioa_$ioa_stream
189 and ioa_$ioa_stream_nnl entry points except that the I/O switch is
190 specified by a pointer to its control block, rather than by name.
191 Since this saves an extra call in the I/O system to locate the control
192 block, these calls are more efficient than ioa_$ioa_stream calls.
193 
194 
195 Syntax:
196 declare ioa_$ioa_switch entry options(variable);
197 call ioa_$ioa_switch (iocb_ptr, control_string, arg1, ..., argN);
198 declare ioa_$ioa_switch_nnl entry options(variable);
199 call ioa_$ioa_switch_nnl (iocb_ptr, control_string, arg1, ..., argN);
200 
201 
202 Arguments:
203 iocb_ptr
204    is a pointer to the control block of the switch.  (Input)
205 control_string
206    is a character string (char(*) or char(*) varying) of text and
207    control characters that determines how the resulting string is to
208    be formed.  (Input)
209 argI
210    are a variable number of arguments (possibly none) that are either
211    edited into the resulting string, or used to control the formatting
212    of it.  (Input)
213 
214 
215 :Entry:  rs: rsnnl: rsnp: rsnpnnl:  2019-05-24  ioa_$rs, ioa_$rsnnl, ioa_$rsnp, ioa_$rsnpnnl
216 
217 Function: These entry points edit the resulting string as in the above
218 calls, but instead of being written to an I/O switch as the other ioa_
219 entry points, the string is passed back to the caller.  The user
220 program must provide a character string variable into which the string
221 can be returned.  This variable may be varying or nonvarying, aligned
222 or unaligned, and of any length.  The resulting string is truncated if
223 it exceeds the length of the character string provided.
224 
225 
226 Syntax:
227 declare ioa_$rs entry options(variable);
228 call ioa_$rs (control_string, ret_string, len, arg1, ..., argN);
229 declare ioa_$rsnnl entry options(variable);
230 call ioa_$rsnnl (control_string, ret_string, len, arg1, ..., argN);
231 declare ioa_$rsnp entry options(variable);
232 call ioa_$rsnp (control_string, ret_string, len, arg1, ..., argN);
233 declare ioa_$rsnpnnl entry options(variable);
234 call ioa_$rsnpnnl (control_string, ret_string, len, arg1, ..., argN);
235 
236 
237 Arguments:
238 control_string
239    is a character string (char(*) or char(*) varying) of text and
240    control characters that determines how the resulting string is to
241    be formed.  (Input)
242 ret_string
243    is a string (char(*) or char(*) varying) into which the output
244    string will be edited.  (Output)
245 len
246    is the length of the returned string (fixed bin(21)).  (Output)
247 argI
248    are a variable number of arguments (possibly none) that are either
249    edited into the resulting string, or used to control the formatting
250    of it.  (Input)
251 
252 
253 Notes:
254 If the output string is nonvarying, it is padded on the right with
255 spaces if it is not completely filled; however, if the call is to
256 either the ioa_$rsnp or ioa_$rsnpnnl entry points, the padding is not
257 done.  Both the ioa_$rsnnl and ioa_$rsnpnnl entry points omit the
258 newline character in the normal way.  All of these entry points also
259 return the length of the significant data edited into the string.