1 01/06/82  apl_quadcall
 2 
 3 
 4 Syntax:  Function call:  V <- qCALL (entry_dcl; arg1; arg2; ...; argN)
 5          Subroutine call:  qCALL (entry_dcl; arg1; arg2; ...; argN)
 6 
 7  where 'q' is the APL quad symbol.
 8 
 9 
10 Function: an APL system function to provide APL users the ability to
11 call a FORTRAN or PL/I routine.  If the routine is a subroutine, no
12 result is returned to APL.  But if the routine is a function, the
13 function's value is returned as the result.
14 
15 
16 Arguments:
17 entry_dcl
18    is an APL character value containing a PL/I style entry declaration
19    specifying the routine to be called, the number of arguments it
20    takes, whether it is a subroutine or function, and the types of the
21    arguments and function value.  (Input)  (See 'Entry Declaration'
22    below for details.)
23 arg1, arg2, ... argN
24    are the APL variables and values to be used as the arguments of the
25    routine which is being called.  (Update) If an argument is a simple
26    variable (as opposed to a constant, an expression or an indexed
27    variable), the value of that variable is updated to reflect any
28    changes made by the called routine.
29 
30 
31 Entry Declaration:
32 The entry declaration is identical to that of PL/I (except that the
33 'entry' keyword is optional), with the following restrictions:
34 
35 (1) The attributes in a parameter declaration must be in the folowing
36     order:  dimensions, type, size and alignment.
37 (2) A lower bound may not be specified for a dimension.
38 (3) The mode (i.e 'real' or 'complex') may not be specified.
39 (4) The only types supported are:  bit, char, entry, fixed bin, and
40     float bin.
41 (5) Neither dimensions nor parameter descriptions (other than 'options
42     (variable)') may be specified for 'entry' values.
43 (6) A scale factor may not be specified for 'fixed' values.
44 (7) 'fixed' and 'float' values may not be unaligned.
45 
46 A typical declaration would be:
47   'get_line_length_$stream(char(*), fixed bin(35)) returns(fixed bin)'
48 
49 
50 Notes: If a simple variable is passed as an argument, that variable
51 need not have been previously assigned a value.  In such a case, the
52 value passed to the called routine for that argument has the shape and
53 type indicated by the entry declaration and is initialized to binary
54 zeroes.
55 
56 The value of an argument must agree with the type specified in the
57 entry declaration.  For example, if an argument is to be passed as a
58 'bit' value, it must be numeric and contain only zeroes and ones.
59 
60 
61 The shape of an argument must agree with that specified in the entry
62 declaration.  This usually means that an argument has the shape
63 indicated by the declaration.  However, an argument that is to be
64 passed as a 'bit' or 'char' value is also considered to have the
65 correct shape if its rank is one greater than in the declaration, its
66 shape when the last dimension is excluded is the same as in the
67 declaration, and the length of the last dimension is the same as the
68 size attribute in the declaration.  For example a 3x4 character matrix
69 may be passed as '(3, 4) char (1)' or '(3) char (4)'.
70 
71 
72 Either a positive integer or an asterisk may be used in the entry
73 declaration to specify the length of a dimension or the size of a
74 'bit' or 'char' value.  An asterisk in a dimension specification means
75 use the current length of the corresponding dimension of the argument.
76 An asterisk in a size attribute means use the current length of the
77 last dimension of the argument.  Asterisks may not be used when the
78 corresponding argument is a simple variable that has not yet been
79 assigned a value.  Asterisks may only be used in the 'returns'
80 attribute if the routine being called was written in PL/I and contains
81 asterisks in the 'returns' attribute of its header.
82 
83 
84 If 'options (variable)' is given in place of parameter declarations,
85 any number of arguments may be supplied.  A rank N numeric argument is
86 passed as an N-dimension array of 'float bin(63)' numbers.  A rank N
87 character argument is passed as an (N-1)-dimension array of 'char(M)',
88 where M is the size of the argument's last dimension.