1 01/12/2018 rdisk_
2
3 Function:
4 The rdisk_ I/O module supports I/O from/to disk packs. Sequential and
5 indexed file types are supported. This I/O module is a very
6 elementary, physical-device-oriented I/O facility, providing the basic
7 user-level interface to a disk device. All operations are performed
8 through calls to various I/O interfacer IOI mechanisms and resource
9 control package RCP entries. Detailed information can be found in
10 the Multics Subroutines and I/O Modules AG93.
11
12
13 Entries in this module are not called directly by users; rather, the
14 module is accessed through the I/O system. For a general description
15 of the I/O system and a discussion of files, see the Programmer's
16 Reference Manual.
17
18 All errors encountered by rdisk_ are reported via the sub_err_
19 subroutine with the "flags" variable set to ACTION_DEFAULT_RESTART.
20 The "info_ptr" variable passed to sub_err_ is set to null.
21
22
23 Syntax for Attach Description:
24 rdisk_ device_id pack_id -control_args
25
26
27 Arguments:
28 device_id
29 is a character string identifying the type number of the required
30 disk device. The supported disk devices are listed in the table
31 below, along with the character string to use for device_id:
32
33 device_id Device Type
34 --------- -----------
35 d181 DSU181
36 d190 DSU190
37 d191 or d400 DSU190/MSU0400 with the high-efficiency
38 format 40 sectors/track
39 d451 MSU0451
40 d500 MSU0500
41 d501 MSU0501
42 3380 MSU3380
43 3381 MSU3381
44
45
46 pack_id
47 is a character string identifying the disk pack to be mounted.
48
49
50 Control arguments:
51 -device, -dv DEVICE_NAME
52 indicates that disk drive DEVICE_NAME is to be attached. This is
53 useful when attaching to drives that do not have removable media.
54 DEVICE_NAME has the form of:
55
56 dskX_NNS
57
58 where:
59
60 X
61 is the subsystem name.
62 NN
63 is the device number.
64 S
65 is the subvolume name. Only valid for 3380 and 3381 devices.
66 Valid subvolume names for the 3380 are a and b, and for the 3381,
67 a, b, and c.
68 -size N
69 indicates that the value of N is to override the value of the
70 buff_len parameter as a record size limit for the read_record
71 operation. See "Notes" below.
72 -sys
73 indicates that the attachment is being made by a system process and
74 that a disk drive reserved for system functions is to be assigned.
75 -write
76 indicates that the disk pack may be written on. If omitted, the
77 operator is instructed to mount the pack with the PROTECT button
78 pressed so that writing is inhibited.
79
80
81 Notes: The attachment causes the specified disk pack to be mounted on
82 a drive of the specified type.
83
84 When the -device option is given with a subvolume, rdisk_ will perform
85 the address conversions in the same manner as the file system I/O.
86 More than one subvolume of a device may be attached by a process. The
87 device may only be attached to one process at any one time. If the
88 subvolume name is not given for a device that supports subvolumes,
89 then rdisk_ will not convert the addresses and the entire device may
90 be accessed.
91
92
93 Opening:
94 The following opening modes are supported:
95
96 sequential_input
97 sequential_output
98 sequential_update
99 direct_input
100 direct_update
101
102 Notice that if the opening mode is of the output or update type, the
103 attach description must include the -write control argument so that the
104 operator does not press the PROTECT button when the pack is mounted.
105
106
107 Position Operation:
108 This operation is supported for only the sequential_input and
109 sequential_update opening modes. The type and quantity values are
110 interpreted as follows:
111 TYPE QUANTITY ACTION
112 ---- -------- ------
113 -1 -- position to the beginning of the disk pack.
114 +1 -- position to the end of the disk pack.
115 0 N skip N sectors forward if N > 0; backward if
116 N < 0.
117 2 N position to sector N.
118
119
120 Read Record Operation:
121 If the amount of data to be read does not terminate on a sector
122 boundary, the excess portion of the last sector is discarded. A code
123 of 0 is returned in this case. See "Notes" below. This operation is
124 not supported for the sequential_output opening mode.
125
126
127 Rewrite Record Operation:
128 If the amount of data to be written does not terminate on a sector
129 boundary, the remaining portion of the last sector is filled with
130 spaces in sequential modes and binary zeros in direct modes. A code of
131 0 is returned in this case. See "Notes" below. This operation is
132 supported for only the update opening modes.
133
134
135 Seek Key Operation:
136 This operation returns a status code of 0 for any key that is a valid
137 sector number. The record length returned is always 256 current
138 physical sector size in characters for any valid key. The specified
139 key must be a character string that could have been produced by editing
140 through a PL/I picture of "89". See "Notes" below. This operation
141 is supported for only the direct opening modes.
142
143
144 List of control orders:
145 The following orders are supported when the I/O switch is open,
146 except for getbounds, which is supported while the switch is
147 attached.
148 changepack
149 causes the current pack to be dismounted and another pack to be
150 mounted in its place. The info_ptr should point to a varying
151 character string maximum of 32 characters containing the
152 identifier of the pack to be mounted. This operation is not allowed
153 for MSU0500 or MSU0501 devices.
154 device_info
155 causes information pertaining to the attached disk device to be
156 returned to the user. See the section "device_info_table Structure"
157 below for the structure to which the info_ptr should point.
158
159
160 format_trk
161 causes a format track command to be issued to the track that was
162 indicated by a preceding seek_key operation. This operation is not
163 allowed for MUS0500 or MSU0501 devices. The info_ptr should point
164 to a user supplied structure of the form described under
165 "format_trk_info Structure" below.
166 getbounds
167 causes the lowest and highest sector numbers accessible by the
168 caller under the current modes to be returned. The info_ptr should
169 point to a structure of the form described under "bounds Structure",
170 below.
171 rd_trk_header
172 causes a read track header command to be issued to the track that
173 was indicated by a preceding seek_key operation. This operation is
174 not allowed for MUS0500 or MSU0501 devices. The raw track header
175 information is passed to the user in a structure pointed to by
176 info_ptr of the form described under "trk_header_info Structure"
177 below.
178
179
180 tsize
181 causes the value of the record size override setting to be reset.
182 The info_ptr should point to an aligned fixed binary35 quantity
183 containing the new override value.
184
185
186 device_info_table Structure:
187 dcl 1 device_info_table aligned,
188 2 subsystem_name char 4,
189 2 device_name char 8,
190 2 sect_per_dev fixed bin 35,
191 2 cyl_per_dev fixed bin,
192 2 sect_per_cyl fixed bin,
193 2 sect_per_track fixed bin,
194 2 num_label_sect fixed bin,
195 2 num_alt_sect fixed bin,
196 2 sect_size fixed bin 12;
197
198 where:
199 subsystem_name
200 is the name of the disk subsystem in use i.e. D191.
201 device_name
202 is the name of the disk device in use i.e. dska_04.
203
204
205 sect_per_dev
206 is the total number of non-T&D sectors on the disk pack.
207 cyl_per_dev
208 is the total number of non-T&D cylinders on the disk pack.
209 sect_per_cyl
210 is the number of data sectors on each cylinder of a disk pack.
211 sect_per_track
212 is the number of data sectors on each track.
213 num_label_sect
214 is the number of data sectors to reserve for label information.
215 num_alt_sect
216 is the number of data sectors to reserve for alternate track
217 area.
218 sect_size
219 is the number of 36-bit words in each data sector.
220
221
222 format_trk_info Structure:
223 dcl 1 format_trk_info aligned,
224 2 hz bit 2
225 2 ti bit 2
226 2 adcyl fixed bin 16
227 2 adhd fixed bin 16 unaligned;
228 where:
229 hz
230 is a bit pattern indicating the state of the header bypass
231 switch. The hz bits are defined as follows:
232 h z bit pattern meaning.
233 0 0 format home address and all data records.
234 0 1 verify home address and record one, format home address
235 and all data records.
236 1 0 skip home address, format all data records.
237 1 1 verify home address and data record one, skip home address
238 and format all data records.
239
240
241 ti
242 is a bit pattern indicating the state of the track indicator
243 bits. The ti bits are defined as follows:
244 t i bit pattern meaning.
245 0 0 format track good.
246 0 1 format track alternate.
247 1 0 format track defective with alternate track assigned.
248 1 1 format track defective with no alternate track assigned.
249
250
251 adcyl, adhd
252 are the alternate or defective cylinder and head numbers used
253 when the track indicator bits equal "01"b or "10"b. These two
254 fields are defined as follows:
255
256 1. If the track indicator bits are set to "01"b alternate
257 track, then adcyl and adhd should be equal to the defective
258 pcylinder and head number for which the alternate track is being
259 formatted.
260
261
262 2. If the track indicator bits are set to "10"b defective with
263 alternate assigned, then adcyl and adhd should be equal to the
264 cylinder and head number of the alternate track. getbounds
265 causes the lowest and highest sector numbers accessible by the
266 caller under the current modes to be returned. The info_ptr
267 should point to a structure of the following form:
268
269 dcl 1 bounds,
270 2 low fixed bin35,
271 2 high fixed bin35;
272
273
274 trk_header_info Structure:
275 dcl 1 trk_header_info aligned,
276 2 ha_cyl bit 16
277 2 ha_head bit 16
278 2 pad1 bit 2
279 2 ha_ti bit 2
280 2 pad2 bit 10
281 2 rcd_0_ti bit 2
282 2 rcd_0_cyl bit 16
283 2 rcd_0_head bit 16
284 2 rcd_0_rn bit 8
285 2 pad3 bit 24
286 2 rcd_0_data 8 bit 8
287 2 pad4 bit 4 unaligned;
288
289
290 where:
291 ha_cyl
292 is the cylinder number read from the track home address.
293 ha_head
294 is the head number read from the track home address.
295 ha_ti
296 is the track indicator bits defined above in the format_trk
297 order read from the track home address.
298 rcd_0_ti
299 is the track indicator bits read from record zero. If the ha_ti
300 bits indicate "10"b, then rcd_0_ti should equal "01"b for
301 alternate track. If ha_ti indicates "01"b, then rcd_0_ti should
302 equal "10"b for defective track. Otherwise rcd_0_ti will equal
303 ha_ti.
304
305
306 rcd_0_cy, rcd_0_head
307 are the cylinder and head number read from record zero. If ha_ti
308 indicates "10"b, then rcd_0_cyl and rcd_0_head equal the cylinder
309 and head number of the alternate track. If ha_ti indicates
310 "01"b, then rcd_0_cyl and rcd_0_head contain the cylinder and
311 head number of the defective track. Otherwise, rcd_0_cyl and
312 rcd_0_head equal ha_cyl and ha_head.
313 rcd_0_rn
314 is the record number for record zero normally equal to zero.
315 rcd_0_data
316 is the eight data bytes in record zero not a normal data record
317 and is normally equal to zero.
318 padn
319 are unused bits that are returned as "0"b.
320
321
322 bounds Structure:
323 dcl 1 bounds,
324 2 low fixed bin 35,
325 2 high fixed bin 35;
326
327 where:
328 low
329 is the lowest sector number accessible by the caller.
330 high
331 is the highest sector number accessible by the caller.
332
333
334 Modes Operation:
335 The modes operation is supported when the I/O switch is attached. The
336 recognized modes are listed below. Each mode has a complement
337 indicated by the circumflex character ^ that turns the mode off.
338
339
340 List of modes:
341 label, ^label
342 specifies that a system-defined number of sectors at the beginning
343 of the pack are reserved for a pack label, and that a seek_key or
344 position operation is to treat any key or position within this area
345 as an invalid key. The default is on.
346 raw, ^raw
347 specifies that the entire disk pack is available to the user,
348 including the T&D cylinder the last cylinder on the disk pack.
349 The default is off.
350 alttrk, ^alttrk
351 specifies that the pack has been formatted with the assignment of
352 alternate tracks, so that a system-defined number of sectors at the
353 end of the pack are reserved for an alternate track area.
354 Therefore, a seek_key or position operation is to treat any key
355 within that area as an invalid key. The default is off. This
356 mode cannot be enabled for a MSU0500 or MSU0501 disk.
357
358
359 wrtcmp, ^wrtcmp
360 specifies that the write-and-compare instruction, rather than the
361 write instruction, is used for the rewrite_record operation. This
362 causes all data written to be read back and compared to the data as
363 it was prior to being written. This mode should be used with
364 discretion, since it doubles the data transfer time of every write.
365 The default is off.
366
367
368 Write Record Operation:
369 If the amount of data to be written does not terminate on a sector
370 boundary, the remaining portion of the last sector is filled with
371 spaces. A code of 0 is returned in this case. See "Notes" below.
372 This operation is supported for only the sequential_output opening
373 mode. A series of writes will write successive records.
374
375
376 Closing:
377 The closing has no effect on the physical device. For the
378 sequential_output opening mode, the effect is as if an end-of-file flag
379 is placed just beyond the end of the available disk area.
380
381
382 Detaching:
383 The detachment causes the disk pack to be detached from the users
384 process.
385
386
387 Syntax of Control Operations From Command Level:
388 io_call control switch order_arg
389
390
391 Arguments:
392 switch
393 is the name of the I/O switch.
394 order_arg
395 must be one of the following:
396 changepack newpack
397 where newpack is the name of the new pack to be mounted.
398 setsize newsize
399 where newsize is the new record size in words.
400 getbounds