1 02/03/84  tssi_
  2 
  3 The tssi_ (translator storage system interface) subroutine simplifies
  4 the way the language translators use the storage system.
  5 
  6 
  7 Entry points in tssi_:
  8    (List is generated by the help command)
  9 
 10 
 11 :Entry:  get_segment:  02/03/84 tssi_$get_segment
 12 
 13 
 14 Function:  This entry point returns a pointer to a specified segment.
 15 The ACL on the segment is rw for the current user.  If an ACL must be
 16 replaced to do this, aclinfo_ptr is returned pointing to information to
 17 be used in resetting the ACL.
 18 
 19 
 20 Syntax:
 21 declare tssi_$get_segment entry (char(*), char(*), ptr, ptr,
 22      fixed bin(35));
 23 call tssi_$get_segment (dir_name, entryname, seg_ptr, aclinfo_ptr,
 24      code);
 25 
 26 
 27 Arguments:
 28 dir_name
 29    is the pathname of the containing directory.  (Input)
 30 entryname
 31    is the entryname of the segment.  (Input)
 32 seg_ptr
 33    is a pointer to the segment, or is null if an error is encountered.
 34    (Output)
 35 aclinfo_ptr
 36    is a pointer to ACL information (if any) needed by the
 37    tssi_$finish_segment entry point.  (Output)
 38 code
 39    is a storage system status code.  (Output)
 40 
 41 
 42 :Entry:  get_file:  02/03/84 tssi_$get_file
 43 
 44 
 45 Function: returns a pointer to the specified multisegment file.
 46 Additional components, if necessary, can be accessed using the
 47 msf_manager_$get_ptr entry point (see the description of the
 48 msf_manager_ subroutine), with the original segment considered as
 49 component 0.
 50 
 51 
 52 Syntax:
 53 declare tssi_$get_file entry (char(*), char(*), ptr, ptr, ptr,
 54      fixed bin(35));
 55 call tssi_$get_file (dir_name, entryname, seg_ptr, aclinfo_ptr,
 56      fcb_ptr, code);
 57 
 58 
 59 Arguments:
 60 dir_name
 61    is the pathname of the containing directory.  (Input)
 62 entryname
 63    is the entryname of the multisegment file.  (Input)
 64 seg_ptr
 65    is a pointer to component 0 of the file.  (Output)
 66 aclinfo_ptr
 67    is a pointer to ACL information (if any) needed by the
 68    tssi_$finish_file entry point.  (Output)
 69 fcb_ptr
 70    is a pointer to the file control block needed by the msf_manager_
 71    subroutine.  (Output)
 72 code
 73    is a storage system status code.  (Output)
 74 
 75 
 76 :Entry:  finish_segment:  02/03/84 tssi_$finish_segment
 77 
 78 
 79 Function:  This entry point sets the bit count on the segment after the
 80 translator is finished with it.  It also terminates the segment and
 81 resets the ACL.  See "Notes" below.
 82 
 83 
 84 Syntax:
 85 declare tssi_$finish_segment entry (ptr, fixed bin(24), bit(36)
 86      aligned, ptr, fixed bin(35));
 87 call tssi_$finish_segment (seg_ptr, bc, mode, aclinfo_ptr, code);
 88 
 89 
 90 Arguments:
 91 seg_ptr
 92    is a pointer to the segment.  (Input)
 93 bc
 94    is the bit count of the segment.  (Input)
 95 mode
 96    is the access mode to be put on the segment.  (Input) It can be one
 97    of the following named constants (declared in
 98    access_mode_values.incl.pl1):
 99       "110"b   RE_ACCESS
100       "101"b   RW_ACCESS
101 
102 
103 aclinfo_ptr
104    is a pointer to the saved ACL information returned by the
105    tssi_$get_segment entry point.  (Input)
106 code
107    is a storage system status code.  (Output)
108 
109 
110 Notes: If the segment existed before the call to tssi_$get_segment,
111 the ACL is reset to the way it was before the tssi_$get_segment entry
112 point was called.  If no ACL existed for the current user, the mode is
113 set to "mode" for the current user.  If the segment was created, and
114 the "mode" parameter contains the "e" mode, all entries on the
115 segment's ACL (as derived from the containing directory's Initial ACL)
116 receive the "e" bit, as well as the other modes specified.  The
117 current user, if not specified on the Initial ACL, receives an ACL
118 term of "mode" on the segment.  Otherwise, the segment's Initial ACL
119 is restored, and, if the current user does not have an ACL term, the
120 segment receives an ACL term of "mode" for the user.
121 
122 
123 :Entry:  finish_file:  02/03/84 tssi_$finish_file
124 
125 
126 Function: This entry point sets the bit count on a multisegment file
127 after the translator is finished with it.  It also closes the file,
128 freeing the file control block.
129 
130 
131 Syntax:
132 declare tssi_$finish_file entry (ptr, fixed bin, fixed bin(24), bit(36)
133      aligned, ptr, fixed bin(35));
134 call tssi_$finish_file (fcb_ptr, component, bc, mode, aclinfo_ptr,
135      code);
136 
137 
138 Arguments:
139 fcb_ptr
140    is a pointer to the file control block returned by the
141    tssi_$get_file entry point.  (Input)
142 component
143    is the highest-numbered component in the file.  (Input)
144 bc
145    is the bit count of the highest-numbered component.  (Input)
146 mode
147    is the access mode to be put on the multisegment file.  (Input) It
148    can be one of the following named constants (declared in
149    access_mode_values.incl.pl1):
150       "110"b   RE_ACCESS
151       "101"b   RW_ACCESS
152 
153 
154 aclinfo_ptr
155    is a pointer to the saved ACL information returned by the
156    tssi_$get_file entry point.  (Input)
157 code
158    is a storage system status code.  (Output)
159 
160 
161 :Entry:  clean_up_segment:  02/03/84 tssi_$clean_up_segment
162 
163 
164 Function: frees the storage that the tssi_$get_segment entry point
165 allocated to save the old ACLs of the segments being translated.  It
166 is to be used in case the translation is aborted (e.g., by a quit
167 signal).
168 
169 Programs that use the tssi_ subroutine must establish a cleanup
170 procedure that calls this entry point.  (For a discussion of cleanup
171 procedures see the Programmer's Reference Manual.) If more than one
172 call is made to the tssi_$get_segment entry point, the cleanup
173 procedure must make the appropriate call to the tssi_$clean_up_segment
174 entry point for each aclinfo_ptr.
175 
176 
177 Syntax:
178 declare tssi_$clean_up_segment entry (ptr);
179 call tssi_$clean_up_segment (aclinfo_ptr);
180 
181 
182 Arguments:
183 aclinfo_ptr
184    is a pointer to the saved ACL information returned by the
185    tssi_$get_segment entry point.  (Input)
186 
187 
188 :Entry:  clean_up_file:  02/03/84 tssi_$clean_up_file
189 
190 
191 Function:  This entry point is the cleanup entry point for multisegment
192 files.  In addition to freeing ACLs, it closes the file, freeing the
193 file control block.
194 
195 
196 Syntax:
197 declare tssi_$clean_up_file entry (ptr, ptr);
198 call tssi_$clean_up_file (fcb_ptr, aclinfo_ptr);
199 
200 
201 Arguments:
202 fcb_ptr
203    is a pointer to the file control block returned by the
204    tssi_$get_file entry point.  (Input)
205 aclinfo_ptr
206    is a pointer to the saved ACL information returned by the
207    tssi_$get_segment entry point.  (Input)