1 02/27/85  convert_access_class_
  2 
  3 
  4 The convert_access_class_ subroutine is provided to convert an access
  5 attribute in the Multics access isolation mechanism (AIM) back and
  6 forth between its binary and character-string representations.
  7 Additional entries provide the ability to encode an access attribute as
  8 a short character string for use in entrynames.
  9 
 10 
 11 Entry points in convert_access_class_:
 12    (List is generated by the help command)
 13 
 14 
 15 :Entry:  decode:  02/27/85 convert_access_class_$decode
 16 
 17 
 18 Function:  This entry point takes the character string produced by the
 19 convert_access_class_$encode entry point and returns the original
 20 access attribute.  The null string and the string "system_low" are both
 21 converted to return the system_low access attribute.
 22 
 23 
 24 Syntax:
 25 declare convert_access_class_$decode entry (bit(72) aligned, char(*));
 26 call convert_access_class_$decode (acc_att, decoded_string);
 27 
 28 
 29 Arguments:
 30 acc_att
 31    is the the decoded authorization.  (Output)
 32 decoded_string
 33    is a short string (maximum of 15 characters) that uniquely
 34    represents the input access attribute.  (Input)
 35 
 36 
 37 :Entry:  encode:  02/27/85 convert_access_class_$encode
 38 
 39 
 40 Function:  This entry point encodes an access attribute into a short
 41 character string, suitable for inclusion in entrynames.  If the input
 42 access attribute represents system_low, the returned string is
 43 "system_low".
 44 
 45 
 46 Syntax:
 47 declare convert_access_class_$encode entry (bit(72) aligned, char(*));
 48 call convert_access_class $encode (acc_att, encoded_string);
 49 
 50 
 51 Arguments:
 52 acc_att
 53    is the input access attribute (Input)
 54 encoded_string
 55    is a short string (maximum of 15 characters) that uniquely
 56    represents the input access attribute.  (Output)
 57 
 58 
 59 :Entry:  from_string:  02/27/85 convert_access_class_$from_string
 60 
 61 
 62 Function:  This entry point converts the character string
 63 representation of an access attribute to an encoded binary form
 64 suitable for storage in system tables and as input to the various
 65 modules that accept the binary form.
 66 
 67 
 68 Syntax:
 69 declare convert_access_class_$from_string entry (bit(72) aligned,
 70      char(*), fixed bin(35));
 71 call convert_access_class_$from_string (acc_att, string, code);
 72 
 73 
 74 Arguments:
 75 acc_att
 76    is the binary representation of string.  (Output)
 77 string
 78    is the character string to be converted (see "Notes" below).
 79    (Input)
 80 code
 81    is a standard status code.  (Output) It can be one of the following:
 82    error_table_$ai_invalid_string
 83       one or more namei is misspelled (see "Notes" below).
 84    error_table_$ai_above_allowed_max
 85       no error in conversion; but the resulting access attribute is
 86       greater than the system_high access attribute.
 87 
 88 
 89 Notes:  The string argument must be of the form:
 90         name1,name2,...,nameN
 91 where namei represents the mnemonic for a sensitivity level or access
 92 category.  The print_auth_names command can be used to obtain a list of
 93 acceptable mnenomics.  If the string argument is null or system_low,
 94 the resulting authorization is level 0 and no categories.  If the
 95 string is system_high, the system access_ceiling is returned (the
 96 maximum access attribute allowed).
 97 
 98 
 99 :Entry:  from_string_range: 02/27/85 convert_access_class_$from_string_range
100 
101 
102 Function:  This entry point converts a character string to the form of
103 a binary access attribute range.
104 
105 
106 Syntax:
107 declare convert_access_class_$from_string_range entry (bit(72) aligned
108      dimension(2), char(*), fixed bin(35));
109 call convert_access_class_$from_string_range (acc_att_range, string,
110      code)
111 
112 
113 Arguments:
114 acc_att_range
115    is the binary representation of string.  (Output)
116 string
117    is the character string to be converted (see "Notes" below).
118    (Input)
119 code
120    is a standard status code.  (Output) It can be one of the following:
121    error_table_$ai_invalid_string
122       one or more namei are misspelled (see "Notes" below).
123    error_table_$ai_above_allowed_max
124       no error in conversion; but the resulting access attribute is
125       greater than the system_high access attribute.
126    error_table_$ai_invalid_range
127       no error in conversion; but acc_att_range (2) does not represent
128       an access attribute greater than or equal to acc_att_range (1).
129 
130 
131 Notes:  The string must be one of the two forms:
132         name1,name2,...,nameN
133         name1a,name2a,...,nameNa:name1b,name2b,...nameNb
134 where namei represents the mnemonic for a sensitivity level or access
135 category.  If the string is in the first form, both elements of
136 acc_att_range will be set to equal values (similar to the operation of
137 convert_access_class_$from_string).  If string is in the second form,
138 acc_att_range (1) will be returned as the binary representation of the
139 part of string left of the colon, and acc_att_range (2) will be
140 returned as the binary representation of the part of the string right
141 of the colon.
142 
143 
144 :Entry:  minimum:  02/27/85 convert_access_class_$minimum
145 
146 
147 Function:  This entry point accepts an array of access attributes and a
148 binary number indicating how many elements to process from the array.
149 It returns an access attribute class whose category set is the
150 intersection of all input category sets and whose sensitivity level is
151 the minimum of all input sensitivity levels.  The returned value need
152 not equal any of the input values.
153 
154 
155 Syntax:
156 declare convert_access_class_$minimum entry (dim(*) bit(72) aligned,
157      fixed bin, bit(72) aligned);
158 call convert_access_class_$minimum (acc_att_array, n_elements,
159      minimum_acc_att)
160 
161 
162 Arguments:
163 acc_att_array
164    are the input access attributes(Input)
165 n_elements
166    is the number of elements to be processed in the acc_att_array
167    argument.  (Input)
168 minimum_acc_att
169    is the result.  (Output)
170 
171 
172 :Entry:  to_string:  02/27/85 convert_access_class_$to_string
173 
174 
175 Function:  This entry point accepts a binary form of an access
176 attribute and returns it as a printable string.  This output string is
177 suitable for input to the convert_access_class_$from_string entry
178 point.  Each level/category name has a maximum length of 32 characters.
179 
180 
181 Syntax:
182 declare convert_access_class_$to_string entry (bit(72) aligned,
183      char(*), fixed bin(35));
184 call convert_access_class_$to_string (acc_att, string, code);
185 
186 
187 Arguments:
188 acc_att
189    is the access attribute to be converted.  (Input)
190 string
191    is the resultant character string (see "Notes" below).  (Output)
192 code
193    is a standard status code.  (Output) It can be one of the following:
194    error_table_$smallarg
195       string is too short to hold the converted result (see "Notes"
196       below).
197    error table_$ai_invalid binary
198       either the level number or category set is invalid; the resulting
199       output is also invalid.
200 
201 
202 Notes:  When the error_table_$smallarg code is returned, as much of the
203 resulting conversion as fits in the output string is returned.
204 However, since the results are not complete, they should not be used as
205 input to the convert_access_class_$from_string entry point.
206 
207 If the access attribute is equal to the site access ceiling as defined
208 by the installation_parms and returned by system_info_$access_ceiling,
209 then "system_high" is returned in the string.
210 
211 
212 :Entry:  to_string_range: 02/27/85 convert_access_class_$to_string_range
213 
214 
215 Function:  This entry point accepts a binary access attribute range
216 pair and returns it as a printable string.  This output string is
217 suitable for input to the convert_access_class_$from_string_range entry
218 point.  Each level/category name has a maximum length of 32 characters.
219 
220 
221 Syntax:
222 declare convert_access_class_$to_string_range entry (bit (72) aligned
223      dimension (2), char (*), fixed bin (35));
224 call convert_access_class_$to_string_range (acc_att_range, string,
225      code);
226 
227 
228 Arguments:
229 acc_att_range
230    is the binary representation of an access attribute range to be
231    converted.  (Input)
232 string
233    is the resultant character string (see "Notes" below).  (Output)
234 
235 
236 code
237    is a standard status code.  (Output) It can be one of the following:
238    error_table_$smallarg
239       string is too short to hold the converted result (see "Notes"
240       below).
241    error_table_$ai_invalid_binary
242       either the level number or category set is invalid; the resulting
243       output is also invalid.
244    error_table_$ai_invalid_range
245       no error in conversion; but acc_att_range (2) does not represent
246       an access attribute greater than or equal to acc_att_range (1).
247 
248 
249 Notes:  When the error_table_$smallarg code is returned, as much of the
250 resulting conversion as fits in the output string is returned.
251 However, since the results are not complete, they should not be used as
252 input to the convert_access_class_$from_string entry point.
253 
254 If either of the access attributes is equal to the site access ceiling
255 as defined by the installation_parms and returned by
256 system_info_$access_ceiling, then "system_high" is returned in the
257 string for that attribute.
258 
259 
260 :Entry:  to_string_range_short: 02/27/85 convert_access_class_$to_string_range_short
261 
262 
263 Function:  This entry point is identical to the
264 convert_access_class_$to_string_range entry point except that the short
265 level/category names are returned.  Each short name has a maximum
266 length of eight characters.  This output is also suitable for input to
267 the convert_access_class_$from_string_range entry point.
268 
269 
270 Syntax:
271 declare convert_access_class_$to_string_range_short entry (bit(72)
272      aligned dimension(2),char(*), fixed bin(35);
273 call convert_access_class_$to_string_range_short (acc_att_range,
274      string, code);
275 
276 
277 Arguments:
278 acc_att_range
279    is the binary representation of an access attribute range range to
280    be converted.  (Input)
281 string
282    is the resultant character string (see "Notes" below).  (Output)
283 
284 
285 code
286    is a standard status code.  (Output) It may be one of the following:
287    error_table_$smallarg
288       string is too short to hold the converted result (see "Notes"
289       below).
290    error_table_$ai_invalid_binary
291       either the level number or category set is invalid; the resulting
292       output is also invalid.
293    error_table_$ai_invalid_range
294       no error in conversion; but acc_att_range (2) does not represent
295       an access attribute greater than or equal to acc_att_range (1).
296 
297 
298 Notes:  If either of the access attributes is equal to the site access
299 ceiling as defined by the installation_parms and returned by
300 system_info_$access_ceiling, then "system_high" is returned in the
301 string for that attribute.
302 
303 
304 :Entry:  to_string_short: 02/27/85 convert_access_class_$to_string_short
305 
306 
307 Function:  This entry point is identical to the
308 convert_access_class_$to_string entry point, except that the short
309 level/category names are returned.  Each short name has a maximum
310 length of eight characters.  This output is also suitable for input to
311 the convert_access_class_$from_string entry point.
312 
313 
314 Syntax:
315 declare convert_access_class_$to_string_short entry (bit(72) aligned,
316      char(*), fixed bin(35));
317 call convert_access_class_$to_string_short (acc_att, string, code);
318 
319 
320 Arguments:
321 acc_att
322    is the binary representation of an access attribute to be converted.
323    (Input)
324 string
325    is the resultant character string.  (Output)
326 code
327    is a standard status code.  (Output) It can be one of the following:
328    error_table_$smallarg
329       string is too short to hold the converted result (see "Notes"
330       below).
331    error_table_$ai_invalid_binary
332       either the level number or category set is invalid; the resulting
333       output is also invalid.