1 :Info: iox_: 1990-07-27 iox_
2
3 Performs I/O operations and some related functions. The user should be
4 familiar with the contents of "Multics Input/Output System" and "File
5 Input/Output" in the Programmer's Reference Manual AG91.
6
7 Each entry point documented here has an argument denoting the
8 particular I/O switch involved in the operation. For an entry point
9 that requires the I/O switch to be in the attached state, the
10 description of the function of the entry point applies only when the
11 switch is attached. For other states, see the description of the
12 particular I/O module. The standard system I/O modules are described
13 in Section 3 of the Multics Subroutines and I/O Modules manual AG93.
14
15
16 When an entry point requires the I/O switch to be opened and it is not
17 open, the state of the switch is not changed and the code
18 error_table_$not_open is returned. If the I/O switch is open but the
19 operation is not allowed for that opening mode, the state of the switch
20 is not changed and the code that is returned is
21 error_table_$no_operation.
22
23 Operations pertaining to files use four position designators for
24 reference: the next byte, the next record, the current record, and the
25 key for insertion.
26
27
28 Several operations involve the use of a buffer. A buffer is a block of
29 storage provided by the caller of the operation as the target for input
30 or the source for output. A buffer must be byte aligned; i.e., its bit
31 address and bit length must both be evenly divisible by 9.
32
33 The code returned by an entry point may be other than a standard status
34 code in cases where the I/O switch is attached via a nonstandard I/O
35 module. All entry points in iox_ are declared in the include file
36 iox_dcls.incl.pl1.
37
38
39 Entry points in iox_:
40 List is generated by the help command
41
42
43 :Entry: attach_loud: 1990-07-27 iox_$attach_loud
44
45
46 Function: This entry point is the same as iox_$attach_ptr except that
47 a call to this entry turns on the com_err_ switch of the I/O module.
48 This means that the attach routine of the I/O module calls com_err_
49 when an error is detected.
50
51
52 Syntax:
53 declare iox_$attach_loud entry ptr char* ptr
54 fixed bin35;
55 call iox_$attach_loud iocb_ptr atd ref_ptr code;
56
57
58 Arguments:
59 iocb_ptr
60 points to the switch's control block. Input
61 atd
62 is the attach description. Input
63 ref_ptr
64 is a pointer to the referencing procedure, used by the search
65 rules to find an I/O module. Input See hcs_$make_ptr for
66 more information about ref_ptr.
67 code
68 is an I/O system status code.
69
70
71 Notes: The code returned by an entry point may be other than a standard
72 status code in cases where the I/O switch is attached via a nonstandard
73 I/O module.
74
75
76 :Entry: attach_name: 1990-07-27 iox_$attach_name
77
78
79 Function: attaches an I/O switch in accordance with a specified attach
80 description. The switch is designated by name and a pointer to its
81 control block is returned. The control block is created if it does not
82 already exist. The form of an attach description is given in the
83 Programmer's Reference Manual.
84
85 The I/O module is located using the current search rules.
86
87
88 Syntax:
89 declare iox_$attach_name entry char* ptr char* ptr
90 fixed bin35;
91 call iox_$attach_name switch_name iocb_ptr atd ref_ptr code;
92
93
94 Arguments:
95 switch_name
96 is the name of the I/O switch. Input
97 iocb_ptr
98 points to the switch's control block. Output
99 atd
100 is the attach description. Input
101 ref_ptr
102 is a pointer to the referencing procedure, used by the search
103 rules to find an I/O module. Input If ref_ptr is null, then
104 the standard search rule specifying the referencing directory is
105 skipped.
106
107
108 code
109 is an I/O system status code. Output
110 error_table_$not_detached
111 the switch is not in the detached state. Its state is not
112 changed.
113
114
115 :Entry: attach_ptr: 1984-01-24 iox_$attach_ptr
116
117
118 Function: attaches an I/O switch in accordance with a specified attach
119 description. The I/O module is located using the current search rules.
120
121
122 Syntax:
123 declare iox_$attach_ptr entry ptr char* ptr fixed bin35;
124 call iox_$attach_ptr iocb_ptr atd ref_ptr code;
125
126
127 Arguments:
128 iocb_ptr
129 points to the switch's control block. Input
130 atd
131 is the attach description. Input
132 ref_ptr
133 is a pointer to the referencing procedure, used by the search
134 rules to find an I/O module. Input If ref_ptr is null, then
135 the standard search rule specifying the referencing directory is
136 skipped.
137 code
138 is an I/O system status code. Output
139 error_table_$not_detached
140 the switch is not in the detached state. Its state is not
141 changed.
142
143
144 Notes: The ref_ptr argument can be used to specify a particular I/O
145 module if one by that name is not already initiated, for example:
146 call iox_$attach_ptr iocb_ptr "discard_"
147 addr my_discard_$my_discard_attach code;
148
149
150 :Entry: close: 1984-01-24 iox_$close
151
152
153 Function: closes an I/O switch.
154
155
156 Syntax:
157 declare iox_$close entry ptr fixed bin35;
158 call iox_$close iocb_ptr code;
159
160
161 Arguments:
162 iocb_ptr
163 points to the switch's control block. Input
164 code
165 is an I/O system status code. Output
166 error_table_$not_open
167 is returned if the switch is not open. Its state is not changed.
168
169
170 :Entry: close_file: 1990-07-27 iox_$close_file
171
172
173 Function: This entry point closes an I/O switch. If the switch is not
174 open, its state is not changed and the code error_table_$not_open is
175 returned.
176
177 This entry point differs from the iox_$close entry point due to the
178 addition of the close description argument. For those I/O modules
179 that support the close_file entry, the close description offers a
180 means of providing file closing parameters such as a closing comment,
181 where to position to upon closing etc.
182
183
184 Syntax:
185 declare iox_$close_file entry ptr char * fixed bin35;
186 call iox_$close_file iocb_ptr cld code;
187
188
189 Arguments:
190 iocb_ptr
191 points to the switch's control block. Input
192 cld
193 is the close description. Input
194 code
195 is an I/O system status code. Output
196
197
198 :Entry: control: 1984-01-24 iox_$control
199
200
201 Function: performs a specified control order on an I/O switch. The
202 allowed control orders depend on the attachment of the switch. For
203 details on control orders, see the description of the particular I/O
204 module used in the attach operation.
205
206
207 Syntax:
208 declare iox_$control entry ptr char* ptr fixed bin35;
209 call iox_$control iocb_ptr order info_ptr code;
210
211
212 Arguments:
213 iocb_ptr
214 points to the switch's control block. Input
215 order
216 is the name of the control order. Input
217 info_ptr
218 is null or points to data whose form depends on the attachment.
219 Input
220
221
222 code
223 is an I/O system status code. Output
224 error_table_$no_operation
225 is returned if the switch is open for a control order which is
226 not supported for a particular attachment, or is returned by I/O
227 modules that support orders with the switch closed.
228 error_table_$not_open
229 is returned if the switch is closed.
230
231
232 :Entry: delete_record: 1984-01-24 iox_$delete_record
233
234
235 Function: deletes the current record from the file to which an I/O
236 switch is attached. The switch must be open for sequential_update,
237 keyed_sequential_update, or direct_update.
238
239 If the file is open for direct_update and the deletion takes place, the
240 current and next record positions are set to null. For
241 keyed_sequential_update, the current and next record positions are set
242 to the record following the deleted record or to end of file if there
243 is no such record.
244
245
246 Syntax:
247 declare iox_$delete_record entry ptr fixed bin35;
248 call iox_$delete_record iocb_ptr code;
249
250
251 Arguments:
252 iocb_ptr
253 points to the switch's control block. Input
254 code
255 is an I/O system status code. Output
256 error_table_$no_record
257 the current record is null. The file's position
258 is not changed.
259
260
261 :Entry: destroy_iocb: 1984-01-24 iox_$destroy_iocb
262
263
264 Function: frees the storage used by the control block for an I/O
265 switch. The switch must be in the detached state. Any existing
266 pointers to the control block become invalid.
267
268
269 Syntax:
270 declare iox_$destroy_iocb entry ptr fixed bin35;
271 call iox_$destroy_iocb iocb_ptr code;
272
273
274 Arguments:
275 iocb_ptr
276 points to the I/O control block to be freed. Input
277 code
278 is an I/O system status code. Output
279
280
281 :Entry: detach: 1990-07-24 iox_$detach
282
283 Function: detaches an I/O switch. If the switch is already detached,
284 its state is not changed and the code error_table_$not_attached is
285 returned. If the switch is open, its state is not changed and the
286 code error_table_$not_closed is returned.
287
288 This entry point differs from the iox_$detach_iocb entry point due to
289 the addition of the detach description argument. For those I/O modules
290 that support the detach entry, the detach description offers a means of
291 providing detach time parameters such as a resource disposition comment
292 to be sent to the system operator.
293
294
295 Syntax:
296 declare iox_$detach entry ptr char * fixed bin 35;
297 call iox_$detach iocb_ptr dtd code;
298
299
300 Arguments:
301 iocb_ptr
302 points to the switch's control block. Input
303 dtd
304 is the detach description. Input
305 code
306 is an I/O system status code. Output
307
308
309 :Entry: detach_iocb: 1984-01-24 iox_$detach_iocb
310
311
312 Function: detaches an I/O switch.
313
314
315 Syntax:
316 declare iox_$detach_iocb entry ptr fixed35;
317 call iox_$detach_iocb iocb_ptr code;
318
319
320 Arguments:
321 iocb_ptr
322 points to the switch's control block. Input
323 code
324 is an I/O system status code. Output
325 error_table_$not_attached
326 the switch is already detached. Its state is not changed.
327 error_table_$not_closed
328 the switch is open. Its state is not changed.
329
330
331 :Entry: err_no_operation: 1984-01-24 iox_$err_no_operation
332
333
334 Function: accepts any number of arguments, the last of which is
335 fixed bin 35. It sets the last argument to the code
336 error_table_$no_operation. This entry point is assigned to entry
337 variables in the I/O control block in order to return an error code
338 when that entry variable is called. See "Writing an I/O Module" in
339 the Programmer's Reference Manual for instructions on when to assign
340 this entry point to such an entry variable.
341
342
343 Syntax:
344 declare iox_$err_no_operation entry options variable;
345 call iox_$err_no_operation arg1 ... argN code;
346
347
348 Arguments:
349 argI
350 are user-supplied arguments. Input
351 code
352 is an I/O system status code. Output
353
354
355 :Entry: err_not_attached: 1984-01-24 iox_$err_not_attached
356
357
358 Function: accepts any number of arguments, the last of which is
359 fixed bin 35. It sets the last argument to the code
360 error_table_$not_attached. This entry point is assigned to entry
361 variables in the I/O control block in order to return an error code
362 when that entry variable is called. See "Writing an I/O Module" in
363 the Programmer's Reference Manual for instructions on when to assign
364 this entry point to such an entry variable.
365
366
367 Syntax:
368 declare iox_$err_not_attached entry options variable;
369 call iox_$err_not_attached arg1 ... argN code;
370
371
372 Arguments:
373 argI
374 are user-supplied arguments. Input
375 code
376 is an I/O system status code. Output
377
378
379 :Entry: err_not_closed: 1984-01-24 iox_$err_not_closed
380
381
382 Function: accepts any number of arguments, the last of which is
383 fixed bin 35. It sets the last argument to the code
384 error_table_$not_closed. This entry point is assigned to entry
385 variables in the I/O control block in order to return an error code
386 when that entry variable is called. See "Writing an I/O Module" in
387 the Programmer's Reference Manual for instructions on when to assign
388 this entry point to such an entry variable.
389
390
391 Syntax:
392 declare iox_$err_not_closed entry options variable;
393 call iox_$err_not_closed arg1 ... argN code;
394
395
396 Arguments:
397 argI
398 are user-supplied arguments. Input
399 code
400 is an I/O system status code. Output
401
402
403 :Entry: err_not_open: 1984-01-24 iox_$err_not_open
404
405
406 Function: accepts any number of arguments, the last of which is
407 fixed bin 35. It sets the last argument to the code
408 error_table_$not_open. This entry point is assigned to entry
409 variables in the I/O control block in order to return an error code
410 when that entry variable is called. See "Writing an I/O Module" in
411 the Programmer's Reference Manual for instructions on when to assign
412 this entry point to such an entry variable.
413
414
415 Syntax:
416 declare iox_$err_not_open entry options variable;
417 call iox_$err_not_open arg1 ... argN code;
418
419
420 Arguments:
421 argI
422 are user-supplied arguments. Input
423 code
424 is an I/O system status code. Output
425
426
427 :Entry: find_iocb: 1990-07-27 iox_$find_iocb
428
429
430 Function: returns a pointer to the control block for an I/O switch.
431 The control block is created if it does not already exist.
432
433
434 Syntax:
435 declare iox_$find_iocb entry char* ptr fixed bin35;
436 call iox_$find_iocb switch_name iocb_ptr code;
437
438
439 Arguments:
440 switch_name
441 is the name of the I/O switch. Input
442 iocb_ptr
443 points to the switch's control block. Output
444 code
445 is an I/O system status code. Output
446
447
448 Notes:
449 if the IOCB you need is for one of the four standard I/O
450 switches, you do not need iox_$find_iocb, but should use one of
451 the four standard external static pointers, iox_$user_io,
452 iox_$user_input, iox_$user_output, or iox_$error_output.
453 These pointers are declared in iox_dcls.incl.pl1.
454
455
456 :Entry: find_iocb_n: 1984-01-24 iox_$find_iocb_n
457
458
459 Function: may be used to find all existing I/O control blocks, whether
460 attached or detached. It returns a pointer to the n'th control block
461 in the calling ring, the numbering being arbitrary. If there are
462 fewer than n control blocks, a null pointer and the code
463 error_table_$no_iocb are returned. Creating or destroying control
464 blocks during a sequence of calls to this entry point should be
465 avoided, as it causes unpredictable changes to the numbering.
466
467
468 Syntax:
469 declare iox_$find_iocb_n entry fixed bin ptr fixed bin35;
470 call iox_$find_iocb_n n iocb_ptr code;
471
472
473 Arguments:
474 n
475 is the number of the I/O control block. Input
476 iocb_ptr
477 is a pointer to the control block. Output
478 code
479 is an I/O system status code. Output
480 error_table_$no_iocb
481 there are fewer than n control blocks.
482
483
484 :Entry: get_chars: 1990-07-27 iox_$get_chars
485
486
487 Function: reads 9-bit bytes from the unstructured file or device to
488 which an I/O switch is attached. The switch must be open for
489 stream_input or stream_input_output. The desired number of bytes, n,
490 is specified in the call. Some I/O modules may actually read fewer
491 than n bytes into the buffer, even though n bytes are available from
492 the file or device. The contents of the buffer beyond the last byte
493 read are undefined.
494
495 If the switch is attached to a file, bytes are read beginning with the
496 next byte, and the next byte position designator is advanced by the
497 number of bytes read.
498
499
500 It is possible to write a program which takes certain actions if a
501 call to iox_ takes longer than a certain amount of time. See the
502 timed_io_$get_chars entry point.
503
504
505 Syntax:
506 declare iox_$get_chars entry ptr ptr fixed bin21 fixed bin21
507 fixed bin35;
508 call iox_$get_chars iocb_ptr buff_ptr n n_read code;
509
510
511 Arguments:
512 iocb_ptr
513 points to the switch's control block. Input
514 buff_ptr
515 points to the byte-aligned buffer into which bytes are to be read.
516 Input
517 n
518 is the number of bytes to be read where n>=0. Input
519 n_read
520 is the number of bytes actually read. Output If code is 0, n_read
521 equals n.
522
523
524 code
525 is an I/O system status code. Output
526 error_table_$short_record
527 fewer than n bytes were read into the buffer. When this code is
528 returned, the caller may again call the iox_$get_chars entry
529 point to get more bytes.
530 If fewer than n bytes remain in the file, this code is returned,
531 and the next byte position is set to end of file.
532 error_table_$end_of_info
533 the next byte position is already at end of the file.
534
535
536 :Entry: get_line: 1990-07-27 iox_$get_line
537
538
539 Function: reads 9-bit bytes from the unstructured file or device to
540 which an I/O switch is attached. The switch must be open for
541 stream_input or stream_input_output. Bytes are read until the input
542 buffer is filled, a newline character is read, or end of file is
543 reached, whichever occurs first. The contents of the buffer beyond
544 the last byte read are undefined.
545
546 If the switch is attached to a file, bytes are read beginning with the
547 next byte, and the next byte position designator is advanced by the
548 number of bytes read.
549
550 It is possible to write a program which takes certain actions if a
551 call to iox_ takes longer than a certain amount of time. See the
552 timed_io_$get_line entry point.
553
554
555 Syntax:
556 declare iox_$get_line entry ptr ptr fixed bin21 fixed bin21
557 fixed bin35;
558 call iox_$get_line iocb_ptr buff_ptr buff_len n_read code;
559
560
561 Arguments:
562 iocb_ptr
563 points to the switch's control block. Input
564 buff_ptr
565 points to a byte-aligned buffer. Input
566 buff_len
567 is the length of the buffer in bytes. Input
568 n_read
569 is the number of bytes read into the buffer. Output
570
571
572 code
573 is an I/O system status code. Output
574 0 is returned if and only if a newline character is read into the
575 buffer it will be the last character read.
576 error_table_$long_record
577 the input buffer was filled without reading a newline character,
578 or the read operation occurred with the input buffer length at
579 zero.
580 error_table_$end_of_info
581 the next byte was initially at end of file.
582 error_table_$short_record
583 the end of file was reached without reading a newline character,
584 and the next byte position designator was set to end of file.
585
586
587 :Entry: init_standard_iocbs: 1990-07-27 iox_$init_standard_iocbs
588
589
590 Function: attaches the standard switches for a user process. These are
591 currently user_input, user_output, and error_output, and they are
592 attached with attach descriptions of:
593
594 syn_ user_i/o -inhibit close,put_chars
595 syn_ user_i/o -inhibit close,get_line,get_chars
596 syn_ user_i/o -inhibit close,get_line,get_chars
597
598 The variables iox_$user_input, iox_$user_output, and iox_$error_output
599 are set to the iocb pointers for these switches.
600
601
602 Syntax:
603 declare iox_$init_standard_iocbs entry ;
604 call iox_$init_standard_iocbs;
605
606
607 Notes: Should the standard attachments change, this program will change
608 to establish whatever they are. It should therefore be used in any
609 direct process overseer that wishes to establish standard attachments.
610
611
612 :Entry: look_iocb: 1984-01-24 iox_$look_iocb
613
614
615 Function: returns a pointer to the control block for a specified I/O
616 switch. If the control block does not exist, it is not created, and a
617 null pointer and the code error_table_$no_iocb are returned.
618
619
620 Syntax:
621 declare iox_$look_iocb entry char* ptr fixed bin35;
622 call iox_$look_iocb switch_name iocb_ptr code;
623
624
625 Arguments:
626 switch_name
627 is the name of the I/O switch. Input
628 iocb_ptr
629 is a pointer to the control block. Output
630 code
631 is an I/O system status code. Output
632 error_table_$no_iocb
633 the control block does not exist.
634
635
636 :Entry: modes: 1990-07-27 iox_$modes
637
638
639 Function: This entry point is used to obtain or set modes that affect
640 the subsequent behavior of an I/O switch. The switch must be attached
641 via an I/O module that supports modes. Each mode is a sequence of
642 nonblank characters. A mode string is a sequence of modes, separated
643 by commas and containing no blanks. For a list of valid modes, see
644 the particular I/O module involved.
645
646
647 Syntax:
648 declare iox_$modes entry ptr char* char* fixed bin35;
649 call iox_$modes iocb_ptr new_modes old_modes code;
650
651
652 Arguments:
653 iocb_ptr
654 points to the switch's control block. Input
655 new_modes
656 is the mode string containing the modes to be set. Input Other
657 modes are not affected. If this argument is the null string, no
658 modes are changed.
659 old_modes
660 is the string of modes in force when the call is made. Output If
661 this argument has length zero, this information is not returned.
662 This argument should be declared large enough to accommodate all the
663 modes supported by the I/O module; 512 characters should be large
664 enough for all system-supplied I/O modules.
665
666
667 code
668 is an I/O system status code. Output It can be:
669 error_table_$not_attached
670 the switch is not attached via an I/O module that supports modes.
671 error_table_$no_operation
672 the switch is attached, but modes are not supported for an open
673 switch.
674 error_table_$not_open
675 the switch is attached, but modes are not supported for a closed
676 switch.
677 error_table_$bad_mode
678 the switch is attached and modes are supported, but an invalid
679 mode is given.
680
681
682 :Entry: move_attach: 1984-01-24 iox_$move_attach
683
684
685 Function: moves an attachment from one I/O switch, s1, to another I/O
686 switch, s2. The s1 I/O switch must be in the attached state and the
687 s2 switch must be in the detached state when the entry point is
688 called.
689
690 Moving the attachment moves the attach description and open description
691 of the s1 I/O switch to the s2 I/O switch. All pointer values and
692 entry values are copied from the control block of the s1 I/O switch to
693 the control block of the s2 I/O switch. These values are listed in
694 "I/O Control Block" in the Programmer's Reference Manual. Attach and
695 open data blocks maintained by the I/O module if the s1 I/O switch is
696 attached are not affected. Finally, the s1 I/O switch is set to the
697 detached state and iox_$propagate is called for both I/O switches.
698
699
700 Syntax:
701 declare iox_$move_attach entry ptr ptr fixed bin35;
702 call iox_$move_attach iocb_ptr_1 iocb_ptr_2 code;
703
704
705 Arguments:
706 iocb_ptr_1
707 points to the control block for the I/O switch s1 that is
708 currently attached. Input
709 iocb_ptr_2
710 points to the control block for the I/O switch s2 that the user
711 intends to attach. Input
712 code
713 is an I/O system status code. Output
714 error_table_$not_attached
715 the I/O switch s1 was not attached. No change is made to either
716 I/O switch.
717 error_table_$not_detached
718 the I/O switch s2 was not detached. No change is made to either
719 I/O switch.
720
721
722 :Entry: open: 1984-01-24 iox_$open
723
724
725 Function: opens an I/O switch. The switch must be attached via an I/O
726 module that supports the specified opening mode, and it must be in the
727 closed state.
728
729 If the switch is attached to a file, the appropriate file position
730 designators are established, and an existing file may be replaced by an
731 empty file. This replacement may be avoided by specifying extension of
732 the file in the attach description. See the information on File
733 Input/Output in the Programmer's Reference Manual for details.
734
735
736 Syntax:
737 declare iox_$open ptr fixed bin bit 1 aligned fixed bin35;
738 call iox_$open iocb_ptr mode unused code;
739
740
741 Arguments:
742
743 iocb_ptr
744 is a pointer to the control block. Input
745 mode
746 is the number assigned to the mode, e.g., 1 for stream_input, 2 for
747 stream_output. Input Numbers associated with all allowed I/O
748 modes are described in the Programmer's Reference Manual as part of
749 the information on Input/Output Facilities. Named constant values
750 for these modes are defined in iox_modes.incl.pl1.
751
752
753 unused
754 must be "0"b. Input
755 code
756 is an I/O system status code. Output
757 error_table_$not_attached
758 the switch is not attached. Its state is not changed.
759 error_table_$not_closed
760 the switch is already open.
761
762
763 :Entry: open_file: 1990-07-27 iox_$open_file
764
765
766 Function: opens an I/O switch. The switch must be attached via an I/O
767 module that supports the specified opening mode, and it must be in the
768 closed state. If the switch is not attached, its state is not
769 changed and the code error_table_$not_attached is returned. If the
770 switch is already open, the code error_table_$not_closed is returned.
771
772
773 This entry point differs from the iox_$open entry point due to the
774 addition of the open description argument. For those I/O modules that
775 support the open_file entry, the open description offers a means of
776 providing file opening parameters such as format, block size, record
777 size, etc. The open description also allows the logical separation of
778 attachment of resources, such as tape volumes, with the
779 iox_$attach_name and iox_$attach_ptr entry points, and file specific
780 operations for those I/O modules that deal with multi-file resources.
781
782
783 Syntax:
784 declare iox_$open_file ptr fixed bin char* bit1 aligned
785 fixed bin 35;
786 call iox_$open_file iocb_ptr mode opd unused code;
787
788
789 Arguments:
790
791 iocb_ptr
792 is a pointer to the control block. Input
793 mode
794 is the number assigned to the mode as shown in the Programmer's
795 Reference Manual under "Input and Output Facilities". Input
796 For example, 1 for stream_input, 2 for stream_output. Named
797 constant values for these modes are defined in iox_modes.incl.pl1.
798 opd
799 is the open description. Input
800 unused
801 must be "0"b. Input
802 code
803 is an I/O system status code. Output
804
805
806 :Entry: position: 1990-07-27 iox_$position
807
808
809 Function: For an I/O switch attached to a file, this entry point
810 positions to the beginning or end of the file, or skips forward or
811 backward over a specified number of lines unstructured files or
812 records structured files. For an I/O switch attached to a device,
813 this operation reads and discards characters until a specified number
814 of newline characters have been skipped. The switch must be opened
815 in one of the following modes:
816 stream_input
817 stream_input_output
818 sequential_input
819 sequential_input_output
820 sequential_update
821 keyed_sequential_input
822 keyed_sequential_update
823
824
825 In addition, for keyed openings, the next record position should not be
826 null. If it is null, the code error_table_$no_record is returned.
827
828
829 Syntax:
830 declare iox_$position entry ptr fixed bin fixed bin21
831 fixed bin35;
832 call iox_$position iocb_ptr type n code;
833
834
835 Arguments:
836 iocb_ptr
837 is a pointer to the control block. Input
838 type
839 identifies the type of positioning. Input
840 -1 goes to the beginning of the file
841 +1 goes to the end of the file
842 0 skips newline characters or records
843 2 positions to an absolute character or record
844 3 skip characters stream input only
845 n
846 is the number of lines, records, or characters to be skipped
847 forward skip or the negative of that number backward skip, or
848 the absolute position. Input It may be 0.
849
850
851 code
852 is an I/O system status code. Output
853 error_table_$no_record
854 the next record position is null for keyed openings.
855 error_table_$end_of_info
856 the file contains too few characters. The next byte
857 position is at the end of file forward skip or beginning of
858 file backwards skip.
859
860
861 Notes: Absolute positioning moves the next byte or record position to
862 the location specified by n. Skipping characters moves the next byte
863 position forward or backward over n characters.
864
865 Positioning to the beginning of a nonempty file sets the next record
866 position at the first record in the file sequential and
867 keyed_sequential openings or sets the next byte position at the first
868 byte in the file stream openings. Positioning to the end of a file,
869 or to the beginning of an empty file, sets the relevant position
870 designator to the end-of-file position.
871
872
873 Successively skipping records sequential and keyed_sequential
874 openings moves the next record position forward or backward by the
875 specified number of records, n, provided that many records exist in the
876 indicated direction. For example, suppose that when the iox_$position
877 entry point is called, the next record is the mth record in the file,
878 and n records are to be skipped. Then for a successful forward skip,
879 the file must contain at least m+n-1 records, and the next record
880 will be set to record m+n if there are at least m+n records in the
881 file or to end of file if there are m+n-1 or fewer records in the
882 file. For a successfull backward skip, m must be greater than n, and
883 the next record position is set to record m-n.
884
885
886 Successively skipping forward over newline characters stream openings
887 advances the next byte position over the specified number, n, of
888 newline characters, leaving it at the byte following the nth newline
889 character or at end of file if the nth newline character is the last
890 byte in the file. Successively skipping backward over n newline
891 characters moves the next byte position backward to the nth preceding
892 newline character and then moves it further backward as far as is
893 possible without encountering another newline character. The effect is
894 to set the next byte position to the first character in a line.
895
896
897 If the relevant part of the file contains too few records or newline
898 characters, the next record position or next byte position is set to
899 the first record or byte backward skip with nonempty file or end of
900 file all other cases, and the code error_table_$end_of_info is
901 returned.
902
903 When a call to the iox_$position entry point specifies skipping zero
904 lines or records, the skip is successful, and the next record position
905 is undisturbed.
906
907 In openings for update, the current record position is set to the
908 resulting next record or null if the next record is at end of file.
909
910 In the case of keyed_sequential_update, the key for insertion is set to
911 null.
912
913
914 :Entry: propagate: 1984-01-24 iox_$propagate
915
916
917 Function: adjusts certain pointers and entry variables in an I/O
918 control block as required when changing between the states detached,
919 attached-closed, and attached-open. It also reflects modifications to
920 a control block to other control blocks that are synonyms immediate
921 or chained for it. This entry point must be called at certain points
922 in the code of an I/O module, and it must not be called in any other
923 circumstances. See "Writing an I/O Module" in the Programmer's
924 Reference Manual for instructions on when to call iox_$propagate.
925
926
927 Syntax:
928 declare iox_$propagate entry ptr;
929 call iox_$propagate iocb_ptr;
930
931
932 Arguments:
933 iocb_ptr
934 is a pointer to the control block. Input
935
936
937 :Entry: put_chars: 1990-07-27 iox_$put_chars
938
939
940 Function: writes a specified number of 9-bit bytes to the unstructured
941 file or device to which an I/O switch is attached. The switch must be
942 open for stream_output or stream_input_output.
943
944 In the case of a file, if the opening is for stream_output, the bytes
945 are simply added at the end of the file. However, if the opening is
946 for stream_input_output, and the next byte position is not at end of
947 file, the file is first truncated so that the byte preceding the next
948 byte becomes the last byte in the file. The bytes being written are
949 then added at the end of the file, and the next byte position is set to
950 end of file.
951
952 Truncation can be suppressed in storage system files by specifying an
953 appropriate attach option. See the description of the vfile_ I/O
954 module for details.
955
956
957 It is possible to write a program which takes certain actions if a
958 call to iox_ takes longer than a certain amount of time. See the
959 timed_io_$put_chars entry point.
960
961
962 Syntax:
963 declare iox_$put_chars entry ptr ptr fixed bin21 fixed bin35;
964 call iox_$put_chars iocb_ptr buff_ptr n code;
965
966
967 Arguments:
968 iocb_ptr
969 is a pointer to the control block. Input
970 buff_ptr
971 points to a byte-aligned buffer containing the bytes to be written.
972 Input
973 n
974 is the number of bytes to be written where n>=0. Input
975 code
976 is an I/O system status code. Output
977
978
979 :Entry: read_key: 1984-01-24 iox_$read_key
980
981
982 Function: returns both the key and length of the next record in an
983 indexed file attached to an I/O switch. The switch must be open for
984 keyed_sequential_input or keyed_sequential_update. The next record
985 position is unchanged and the current record position is set to the
986 next record if the operation is successful; otherwise, the current
987 record position is set to null.
988
989
990 Syntax:
991 declare iox_$read_key entry ptr char256 varying fixed bin21
992 fixed bin35;
993 call iox_$read_key iocb_ptr key rec_len code;
994
995
996 Arguments:
997 iocb_ptr
998 is a pointer to the control block. Input
999 key
1000 is the next record's key. Output
1001 rec_len
1002 is the next record's length in bytes. Output
1003 code
1004 is an I/O system status code. Output
1005 error_table_$end_of_info
1006 the next record position is at end of file.
1007 error_table_$no_record
1008 the next record position is null.
1009
1010
1011 :Entry: read_length: 1984-01-24 iox_$read_length
1012
1013
1014 Function: returns the length of the next record in a structured file
1015 attached to an I/O switch. The switch must be opened in one of the
1016 following modes:
1017 sequential_input
1018 sequential_input_output
1019 sequential_update
1020 keyed_sequential_input
1021 keyed_sequential_update
1022 direct_input
1023 direct_update
1024 The next record position is unchanged and the current record position
1025 is set to the next record if the operation is successful; otherwise,
1026 the current record position is set to null.
1027
1028
1029 Syntax:
1030 declare iox_$read_length entry ptr fixed bin21 fixed bin35;
1031 call iox_$read_length iocb_ptr rec_len code;
1032
1033
1034 Arguments:
1035 iocb_ptr
1036 is a pointer to the control block. Input
1037 rec_len
1038 is the next record's length in bytes. Output
1039 code
1040 is an I/O system status code. Output
1041 error_table_$end_of_info
1042 the next record position is at end of file.
1043 error_table_$no_record
1044 the next record position is null.
1045
1046
1047 :Entry: read_record: 1984-01-24 iox_$read_record
1048
1049
1050 Function: reads the next record in a structured file to which an I/O
1051 switch is attached. The switch must be opened in one of the following
1052 modes:
1053 sequential_input
1054 sequential_input_output
1055 sequential_update
1056 keyed_sequential_input
1057 keyed_sequential_update
1058 direct_input
1059 direct_update
1060 The read is successful if the next record position is at a record.
1061
1062
1063 In sequential and keyed_sequential openings, a successful read advances
1064 the next record position by one record; an unsuccessful read leaves it
1065 at the end of file or null. In direct openings, this operation always
1066 sets the next record position to null. In openings for update, a
1067 successful read sets the current record position to the record just
1068 read; an unsuccessful read sets it to null. In openings for
1069 keyed_sequential_update and direct_update, the key for insertion is
1070 always set to null.
1071
1072
1073 Syntax:
1074 declare iox_$read_record entry ptr ptr fixed bin21 fixed bin21
1075 fixed bin35;
1076 call iox_$read_record iocb_ptr buff_ptr buff_len rec_len code;
1077
1078
1079 Arguments:
1080 iocb_ptr
1081 is a pointer to the control block. Input
1082 buff_ptr
1083 points to a byte-aligned buffer into which the record is to be read.
1084 Input
1085 buff_len
1086 is the length of the buffer in bytes. Input
1087 rec_len
1088 is the length of the record in bytes. Output
1089
1090
1091 code
1092 is an I/O system status code. Output
1093 error_table_$end_of_info
1094 the next record position is at end of file.
1095 error_table_$no_record
1096 the next record position is null.
1097 error_table_$long_record
1098 the record is too long for the specified buffer. The first
1099 part of the record is read into the buffer, and as far as
1100 setting position indicators is concerned, this is considered a
1101 successful read. In all cases, the contents of the buffer
1102 beyond the last byte read are undefined.
1103
1104
1105 :Entry: rewrite_record: 1984-01-24 iox_$rewrite_record
1106
1107
1108 Function: replaces the current record in a structured file to
1109 which an I/O switch is attached. The switch must be open for
1110 sequential_update, keyed_sequential_update, or direct_update.
1111
1112 For keyed_sequential_update and sequential_update, this operation sets
1113 the next record position to the record immediately following the
1114 current record or to end of file if no such record exists. It is
1115 possible that the next record position may already be at this point.
1116 For direct_update, the next record position is set to null. No other
1117 changes are made to the position designators.
1118
1119
1120 Syntax:
1121 declare iox_$rewrite_record entry ptr ptr fixed bin21
1122 fixed bin35;
1123 call iox_$rewrite_record iocb_ptr buff_ptr rec_len code;
1124
1125
1126 Arguments:
1127 iocb_ptr
1128 is a pointer to the control block. Input
1129 buff_ptr
1130 points to a byte-aligned buffer containing the new record. Input
1131 rec_len
1132 is the length of the new record. Input
1133 code
1134 is an I/O system status code. Output
1135 error_table_$no_record
1136 the current record position is null.
1137
1138
1139 :Entry: seek_key: 1984-01-24 iox_$seek_key
1140
1141
1142 Function: searches for a record with a given key in an indexed file to
1143 which an I/O switch is attached. It also serves to define the key for
1144 a record to be added by a following write_record operation. The
1145 switch must be opened in one of the following modes:
1146 keyed_sequential_input
1147 keyed_sequential_output
1148 keyed_sequential_update
1149 direct_input
1150 direct_output
1151 direct_update
1152
1153
1154 Syntax:
1155 declare iox_$seek_key entry ptr char256 varying fixed bin21
1156 fixed bin35;
1157 call iox_$seek_key iocb_ptr key rec_len code;
1158
1159
1160 Arguments:
1161 iocb_ptr
1162 is a pointer to the control block. Input
1163 key
1164 contains the given key. Input All trailing blanks are removed
1165 from key to obtain the given key, and the result may be the null
1166 string.
1167 rec_len
1168 is the length in bytes of the record with the given key. Output
1169 code
1170 is an I/O system status code. Output
1171 See "Notes" below.
1172
1173
1174 Notes: For keyed_sequential_output, the given key should be greater
1175 according to the rules for character-string comparison than the key
1176 of the last record in the file. If it is, the code
1177 error_table_$no_record is returned, and the key for insertion is set
1178 to the given key. Otherwise, the code error_table_$key_order is
1179 returned, and the key for insertion is set to null.
1180
1181
1182 For other openings, this entry point performs as follows.
1183 1. If the file contains a record with the given key, a code of 0
1184 is returned, the record's length is returned, the next record
1185 position and current record position are set to the record,
1186 and the key for insertion is set to null. Not all of these
1187 position designators are applicable in all openings.
1188 2. If the file does not contain a record with the given key, the
1189 code error_table_$no_record is returned, the next record
1190 position and current record position are set to null, and the
1191 key for insertion is set to the given key. Not all of these
1192 position designators are applicable in all openings.
1193
1194
1195 :Entry: write_record: 1984-01-24 iox_$write_record
1196
1197
1198 Function: adds a record to a structured file to which an I/O switch is
1199 attached. The switch must be opened in one of the following modes:
1200 sequential_output
1201 sequential_update
1202 sequential_input_output
1203 keyed_sequential_output
1204 keyed_sequential_update
1205 direct_output
1206 direct_update
1207
1208
1209 Syntax:
1210 declare iox_$write_record entry ptr ptr fixed bin21
1211 fixed bin35;
1212 call iox_$write_record iocb_ptr buff_ptr rec_len code;
1213
1214
1215 Arguments:
1216 iocb_ptr
1217 is a pointer to the control block. Input
1218 buff_ptr
1219 points to a byte-aligned buffer containing the new record. Input
1220 rec_len
1221 is the length of the new record in bytes. Input
1222 code
1223 is an I/O system status code. Output
1224
1225
1226 Notes: If the switch is open for sequential_output, the record is
1227 added at the end of the file. If the switch is open for
1228 sequential_input_output, and the next record position is not at the
1229 end of the file, the file is truncated so that the record preceding
1230 the next record becomes the last record in the file. The new record
1231 is then added at the end of the file.
1232
1233 Truncation can be suppressed in sequential_input_output, and write
1234 operations can be performed in sequential_update openings of storage
1235 system files. See the description of the vfile_ I/O module for
1236 details.
1237
1238
1239 If the switch is open for keyed_sequential_output,
1240 keyed_sequential_update, direct_output, or direct_update, the key for
1241 insertion designator should designate a key. If it does not, the code
1242 error_table_$no_key is returned and nothing is changed. If there is a
1243 key for insertion, the new record is added to the file with that key
1244 and the key for insertion is set to null. For keyed_sequential_update,
1245 and sequential_update, the next record position is set to the record
1246 immediately following the new record or to end of file if there is no
1247 such record. For keyed_sequential_update, sequential_update, and
1248 direct_update, the current record position is set to the new record.
1249
1250
1251 :hcom:
1252
1253
1254
1255 /****^ HISTORY COMMENTS:
1256 1) change2020-11-22GDixon, approve2021-02-22MCR10088,
1257 audit2021-05-27Swenson, install2021-05-27MR12.6g-0056:
1258 A) Update heading date strings to iso_date format.
1259 B) Correct dates for iox_$open_file and iox_$detach, since these entry
1260 points were added to iox_ in 1990-07-27. Date for iox_$open was
1261 restored to 1984-01-24 since this was one of the original iox_ entry
1262 points.
1263 END HISTORY COMMENTS */
1264
1265
1266