1 12/23/81  apl_coded_
 2 
 3 This PL/1 subroutine has entry points that can be called as external
 4 functions from within APL, for the purpose of manipulating Multics
 5 segments as stream files.  Operations equivalent to the APL standard
 6 file handling routines are provided, plus several which are meaningful
 7 only in the sequential access stream file environment.
 8 
 9 
10 Syntax:  The syntax of each entry point is described below.
11 
12 
13 List of entry points in apl_coded_:
14 create
15    Usage:  'path_name' CREATE file_number
16 
17    (like FCREATE).  Creates segment named 'path_name' and opens it
18    for stream i/o.  Path_name may be relative or absolute.  File
19    number is analogous to 'tie number' in APL files but the two
20    systems are independent.  (That is, you may have a stream file 7
21    and an APL file 7 tied concurrently. )
22 eof
23    Usage:  R <- EOF file_number_vector
24 
25    Returns boolean vector of 'end-of-file' status for each file
26    specified.  EOF becomes true when the last character in a file has
27    been read.
28 
29 
30 nums
31    Usage:  R <- NUMS
32 
33    (like FNUMS).  Returns vector of tied file numbers.
34 position
35    Usage:  type [,skip] POSITION file_number
36 
37     Repositions the file.  If 'type' is -1, the file is rewound.  If
38     type is 0, 'skip' lines are skipped.  If 'type' is 1, the file is
39     positioned after the last line.  If 'type' is 2, the file is
40     positioned at the 'skip'th character.  If 'type' is 3, 'skip'
41     characters are skipped.  'skip' is ignored if 'type' is -1 or 1.
42     'skip' may be negative if 'type' is 0 or 3, in which case a
43     backward skip is performed.  If 'skip' is omitted, 1 is assumed.
44 
45 
46 read
47    Usage:  R <- no_of_lines READ file_number
48 
49     Returns character matrix of dimension [I J] where I is the number
50     of lines actually read (I<=left argument) and J is the length of
51     the longest line (J<=512).  Lines containing less than J characters
52     are right-padded with blanks.
53 rewind
54    Usage:  REWIND file_number_vector
55 
56     Positions each file specified in right argument so that next READ
57     operation would read first line in file or next WRITE operation
58     would truncate and replace file contents with the new data.
59 
60 
61 tie
62    Usage:  'path_name' TIE file_number
63 
64    (like FTIE).  Opens segment named 'path_name' and opens it for
65    stream i/o.  Path_name may be relative or absolute.
66 untie
67    Usage:  UNTIE file_number_vector
68 
69    (like FUNTIE).  Detaches each file in right argument.
70 write
71    Usage:  'char_vector' WRITE file_number
72 
73    Writes the characters of the left argument to the designated
74    stream file.  Newline characters (octal escape "012) must be
75    included explicitly if desired.
76 
77 
78 Access:  To access the coded file functions, you must enter the
79 following external function definitions:
80 
81 )DFN CREATE APL_CODED_$CREATE
82 )MFN EOF APL_CODED_$EOF
83 )ZFN NUMS APL_CODED_$NUMS
84 )DFN POSITION APL_CODED_$POSITION
85 )DFN READ APL_CODED_$READ
86 )MFN REWIND APL_CODED_$REWIND
87 )DFN TIE APL_CODED_$TIE
88 )MFN UNTIE APL_CODED_$UNTIE
89 )DFN WRITE APL_CODED_$WRITE