1 08/11/2016  call, cl
  2 
  3 Syntax as a command:
  4   cl {global_opts} virtual_entry {arg_value_specifiers}
  5 
  6 
  7 Syntax as an active function:
  8   [cl {global_opts} virtual_entry {arg_value_specifiers}]
  9 
 10 
 11 Function:
 12 call invokes subroutine and function interfaces directly from the
 13 command line, to facilitate testing an entrypoint interface.
 14 
 15 Operating as either a command or an active function, call invokes an
 16 entrypoint by passing data given by arg_value specifiers for each
 17 entrypoint parameter.  Upon return from the entrypoint, it displays or
 18 returns selected argument values.
 19 
 20 
 21 Arguments:
 22 virtual_entry
 23   character representation of an external entrypoint to be invoked.
 24   Format of this string is described in: virtual_entries.gi.info
 25 
 26 arg_value_specifier
 27   one or more strings and options defining an argument to be passed to
 28   the entrypoint.  See "List of arg_value_specifiers".
 29 
 30 
 31 List of arg_value_specifiers:
 32   An argument corresponding to each entrypoint parameter is prepared
 33   using the following directional specifiers.
 34 
 35 -input arg_value {arg_options},
 36 -in arg_value {arg_options},
 37 -i arg_value {arg_options},
 38 arg_value {arg_options}
 39   gives an initial value for an entrypoint input argument before the
 40   call is made.  The argument value is not displayed after the
 41   entrypoint returns.  -input is the default if no direction option is
 42   given with an arg_value.
 43 
 44 
 45 -inout arg_value {arg_options},
 46 -io arg_value {arg_options}
 47   sets the initial value for the corresponding input-output argument
 48   before the entrypoint is called.  This argument value is displayed
 49   after the entrypoint returns.
 50 
 51 
 52 -output {arg_options},
 53 -out {arg_options},
 54 -o {arg_options}
 55   no arg_value is provided, so call clears storage for the
 56   corresponding output argument before the entrypoint is called.
 57   This argument value is displayed after the entrypoint returns.
 58 -outignore {arg_options},
 59 -ignore {arg_options},
 60 -ig {arg_options}
 61   clears storage for the corresponding argument before the entrypoint
 62   is called.  The argument value is not displayed after the
 63   entrypoint returns.
 64 
 65 
 66 List of arg_options:
 67   Each arg_value_specifier may end with one or more of the following
 68   options.
 69 -id ID
 70   gives an identifier for the argument.  This identifier is used when
 71   displaying an output argument, or when naming a -length ID in
 72   another argument's declaration.  (See -addr and -length below.)
 73 -return, -ret
 74   selects the argument that should be returned when call is invoked as
 75   an active function.  Only one argument may be returned as the value
 76   of the active function.  See "Notes on call as an active function".
 77 
 78 
 79 -code, -cd
 80   argument is a Multics status code (fixed bin(35) aligned).  For an
 81   input argument, the arg_value is a status code name (e.g.,
 82   error_table_$bad_arg).  For an output argument, status code name
 83   and the long status message is displayed/returned.
 84 -date_time,
 85 -date, -dt,
 86 -time, -tm
 87   argument is a Multics clock value (fixed bin(71) aligned).  For an
 88   input argument, arg_value is a string representation of a date or
 89   time value, acceptable to the convert_date_to_binary_ subroutine.
 90   For an output argument, clock value is converted to default process
 91   date_time, date, or time format.
 92 
 93 
 94 -octal, -oc
 95   displays an octal representation of storage for the argument,
 96   as well as a character string interpretation.  The final block
 97   of octal may include bytes (or bits) beyond the end of the
 98   argument's storage.
 99 -declare DECLARATION,
100 -dcl DECLARATION
101   argument has the attributes given in DECLARATION.  A descriptor
102   with these attributes is passed with this argument.  -dcl is useful
103   when calling an entrypoint that accepts a variable number of
104   parameters, or parameters of various data types.
105 
106 
107 -addr DECLARATION
108   for a pointer argument, sets its value to point to storage described
109   by the PL/I DECLARATION, which is a single string defining data type
110   and length attributes (e.g., "char(20)").  For an input argument,
111   the arg_value initializes this storage.  For an output argument, the
112   addressed storage is displayed or returned.
113 
114   A string DECLARATION may include the ID for another input parameter.
115   For example: -addr "char(buffL)", where -id buffL is given for
116   another fixed binary input parameter; the initial value for this
117   referenced parameter specifies length of the character string to be
118   allocated.
119 
120 
121 -max_length M, -ml M
122   for a string or area parameter with star extents (e.g., char(*),
123   char(*) var, bit(*), bit(*) var), gives the actual extent size M in
124   characters, bits, or area words of the storage for the corresponding
125   argument.
126 -length L, -ln L
127 -length ID, -ln ID
128   for a string argument, gives the length L in characters or bits to
129   be displayed upon return from the entrypoint.  The -length operand
130   may also be the ID (see -id above) of another integer output
131   argument, which gives the string length to display.
132 
133 
134 List of global options:
135   Global options are given either before or immediately after the
136   virtual_entry.  They are as follows.
137 -all, -a
138   display all arguments upon return from entrypoint.  The default
139   is to display only arguments with -inout or -out specifiers.
140 -octal, -oc
141   display all arguments with an octal storage representation, in
142   addition to its character string interpretation.
143 -debug INT, -db INT
144   displays debug information as call prepares to invoke the
145   virtual_entry.  An INT equaling 1 provides basic debugging data;
146   values between 2 and 5 provide additional details.
147 
148 
149 Notes on call as an active function:
150 call as an active function selects and returns its active function
151 value as follows:
152   - If any argument has the -code option and a non-zero status as its
153     value upon return from the entrypoint, the active function returns
154     the status code name and its associated long message.
155   - Otherwise, if any argument has the -return option, the active
156     function returns the character interpretation of that argument.
157   - Otherwise, if the entrypoint is a function, and the corresponding
158     return argument does not have an -ignore option, the active
159     function returns the character interpretation of the return
160     argument.
161   - Otherwise, the active function returns an empty string.
162 
163 
164 Notes on entrypoint parameters:
165 When the PL/I compiler creates object segments, each external
166 entrypoint is preceded by an entrypoint parameter list that includes:
167   - entrypoint attributes (e.g., subroutine or function; fixed or
168     variable argument count);  and
169   - a descriptor for each entrypoint parameter (including a function's
170     return value).
171 
172 These entrypoint descriptors give data type, storage requirements, and
173 other attributes for the parameter.  In effect, this entrypoint
174 parameter list includes all information needed to display a PL/I
175 declaration for the entrypoint.
176 
177 
178 External interfaces coded in assembly language (alm) do not provide
179 entrypoint parameter descriptors.  This includes all gate interfaces
180 to inner-ring routines.  Such interfaces are supported by call only if
181 an equivalent PL/I declaration for the entrypoint is found in a data
182 segment named by the "declare" search paths.
183 
184 Use the display_entry_point_dcl (depd) command to display the entry
185 parameter list for a given entrypoint.  This command looks for either:
186 a declaration of the entrypoint found using the "declare" search
187 paths; or an entrypoint parameter list compiled into the object
188 segment.  The call command uses this same information to actually
189 invoke the entrypoint.  See the "Notes on user-provided data files"
190 section of depd.info for information about declaring new entrypoints,
191 or customizing the declaration for existing entrypoints.
192 
193 
194 Notes on building the argument list:
195 Before invoking the entrypoint, call does the following for each
196 entrypoint parameter descriptor:
197   - allocate storage to hold an argument to pass to the parameter.
198   - convert the corresponding arg_value (if given) to the attributes
199     of the parameter descriptor.   PL/I rules for type conversion are
200     followed.  arg_values for pointer and entry data types use formats
201     accepted by cv_ptr_ and cv_entry_ subroutines, respectively.
202   - copy the converted value to its assigned storage location.
203   - for parameter with star extents (e.g., char(*), bit(*), etc),
204     update the parameter descriptor with actual size for the argument
205     being passed to the parameter.
206   - store pointers to assigned argument storage and its (perhaps
207     updated) descriptor in an argument list.
208   - invoke entrypoint using the constructed argument list.
209 
210 
211 Upon return from the invoked entrypoint, the call command does the
212 following for each -inout or -out argument when invoked as a command:
213   - convert its value from the parameter data type to a string
214     representation.
215   - display the value.
216   - for a function call, display the return value.
217 
218 
219 Notes on example - initiate_file_:
220 The initiate_file_ subroutine has the following PL/I calling sequence:
221 
222    call initiate_file_( dir, entry, access_mode, ptr,
223            bit_count, code);
224 
225 The attributes for each parameter may be displayed by using the depd
226 command:
227 
228    depd initiate_file_
229    dcl initiate_file_ entry( char(*), char(*), bit(*), ptr,
230            fixed bin(24), fixed bin(35));
231 
232 
233 The following command initiates a file for reading; the file in the
234 current working directory is named 'my_file'.  Upon return from
235 initiate_file_, call displays the output arguments: a pointer to the
236 initiated file, its bit count, and a Multics status code:
237 
238    call initiate_file_  [wd]  my_file  100  -out  -out  -out -code
239 
240 
241 Notes on example - cv_ptr_:
242 Calling sequence for a function includes a descriptor for its returns
243 attribute.  This defines data the function returns to the caller.  For
244 example:
245 
246    ptr_value = cv_ptr_ (virtual_pointer, code);
247 
248    depd cv_ptr_
249      dcl cv_ptr_ entry (char(*), fixed bin(35)) returns(ptr);
250 
251    call cv_ptr_  [hd]>[user name].profile  -out -code
252 
253 
254 The default action is equivalent to
255 
256    call cv_ptr_  [hd]>[user name].profile  -out -code  -out
257 
258 which displays both the status code and function return value
259 (ptr_value).  To display only the status code for the given
260 virtual_pointer (not displaying the function return value), use:
261 
262    call cv_ptr_  [hd]>[user name].profile  -out -code  -ignore
263 
264 
265 Notes on example - iox_$get_line:
266 When calling a subroutine that accepts inputs of a buffer pointer and
267 its maxlength, and outputs the number of valid characters in that
268 buffer, use the -addr and -length options to have the returned data
269 displayed.  iox_$get_line is described as follows:
270 
271    call iox_$get_line (iocb_ptr, buff_ptr, buff_max_len, n_read,
272           code);
273 
274    depd iox_$get_line
275      dcl iox_$get_line entry (ptr, ptr, fixed bin(21), fixed bin(21),
276           fixed bin(35));
277 
278 
279 Use call to invoke iox_$get_line, as follows.  [Input shown on
280 several lines should actually be given in a single command line.]
281 
282    call iox_$get_line -i [io find_iocb user_i/o]
283                       -o -id buff -addr "char(buffL)" -length readN
284                       -i 200 -id buffL
285                       -o -id readN
286                       -o -code
287 
288 
289 With user input...
290    Results from iox_$get_line are this line.
291 
292 call displays...
293    -- Return from: iox_$get_line -------
294     buff      337|2056 -> Results from iox_$get_line are this line.
295 
296     readN     42
297     code05    OK
298 
299 
300 Argument 1 names an I/O switch.  call converts this initial value to
301   an IOCB ptr.
302 Argument 2, named buff, is an output buffer pointer.  Call creates
303   storage for "char(buffL)" characters, where buffL is the input value
304   for the third argument.  Upon return, -length readN tells call how
305   many characters in this buffer to display, where readN references
306   the output value for the fourth argument.
307 Argument 3, named buffL, is an input argument giving max length (200
308   characters) for the buffer in the second argument.
309 Argument 4, named readN, is an output argument giving actual length to
310   display from the buffer in the second argument.
311 Argument 5 is a status code.
312 
313 
314 Notes on example - ioa_:
315 When calling a subroutine that accepts a variable number and type of
316 arguments, arguments have default attributes:  char(*) unaligned.
317 Use the -dcl option to specify the attributes of a different type.
318 ioa_ is described as:
319 
320    call ioa_ (control_string, arg1, ..., argN);
321 
322    depd ioa_
323      dcl ioa_ entry() options(variable);
324 
325 
326 Use call to pass a character control_string that displays a pointer
327 and fixed bin(35) number.  [Input shown on several lines should
328 actually be given in a single command line.]
329 
330    call ioa_ "data at: ^p (^d bits)"
331              247|400 -dcl ptr
332              39786   -dcl "fixed bin(35)"
333 
334    data at: 247|400 (39786 bits)
335 
336 
337 Notes on supported data attributes:
338 Every parameter of a PL/I entrypoint has a data type, an aggregate
339 type, and an alignment type.  The call command follows PL/I rules when
340 converting arg_value string to the corresponding parameter attributes.
341   - Alignment of storage supports both aligned and unaligned data.
342   - Aggregate (array and structure) data is not supported.
343 
344 The following data types are supported.
345 
346 
347 real fixed bin(P,S)
348   fixed-point binary data type, with or without a precision (P) and
349   scale factor (S).
350 real float bin(P)
351   floating-point binary data, with or without a precision (P).
352 real fixed dec(P,S)
353   fixed-point decimal data type, with or without a precision (P) and
354   scale factor (S).
355 real float dec(P)
356   floating-point decimal data type, with or without a precision (P).
357 char(N), char(N) varying, char(*), char(*) varying
358   character data, with a given length (N) or unspecified length (*).
359 bit(N), bit(N) varying, bit(*), bit(*) varying
360   bit string data, with a given length (N) or unspecified length (*).
361 
362 
363 pointer, ptr
364   pointer data.
365 entry
366   entry variable data.
367 area
368   PL/I allocation area of given size.
369 
370 
371 List of unsupported data types:
372   complex fixed bin(P,S)
373   complex float bin(P)
374   complex fixed dec(P,S)
375   complex float dec(P)
376   picture
377   offset
378   file
379   format
380   label
381 
382 
383 Notes on arg_value formats:
384 Each input arg_value includes a character representation of the
385 initial value for a subroutine argument.  In general, numbers and bit
386 strings are initialized by character data, in any format accepted by
387 PL/I conversion rules for character-to-numeric or character-to-bit.
388 
389 
390 real numbers (binary or decimal, fixed or float)
391   23  -23.45
392   2e3   (equivalent to 2000)
393   0.2345e5  2.45e-6
394 
395   Fixed binary arguments may also be entered as octal or hexadecimal
396   bit strings.  Bits are assigned to argument storage from
397   right-to-left, following PL/I rules for converting a bit string to
398   an fixed bin(17) parameter:
399     55b3     (uses octal suffix b3:       equivalent to  45)
400     2aDb4    (uses hexadecimal suffix b4: equivalent to 685)
401     777777b3 (uses octal suffix b3:       equivalent to  -1)
402 
403 
404 bit string data
405   Entered as a sequence of 1 and 0 characters (e.g., 10101101) which
406   are converted to a bit string following PL/I character-to-bit
407   conversion rules, and assigned left-to-right to the parameter.
408 
409   Values may also be entered in octal or hexadecimal format,
410   as shown above for real numbers.  Bits are assigned to parameter
411   storage from left-to-right.
412 
413 
414 pointer, ptr
415   Use any format given in: virtual_pointers.gi.info.
416 entry pointer
417   Use any format given in: virtual_entries.gi.info.
418 
419 
420 area
421   Since there is no way to provide an initialize an area, or display
422   its output value, an area is usually specified using the -ignore
423   arg_value specifier.  If an area parameter is declared:
424      dcl  area_parm area(*);
425   you can specify an actual size for the corresponding argument using
426   the -max_length M option:
427      -ignore -max_length 2000
428   Often, the parameter is declared as a pointer to an area:
429      dcl  area_ptr ptr;
430   In such cases, you can specify a pointer to an area of given word
431   size:
432      -ignore -addr "area(2000)"