1 07/03/87 vfile_
2
3 Syntax: vfile_ path -control_args
4
5
6 Function: This I/O module supports I/O from/to files in the storage
7 system. All logical file types are supported.
8
9
10 Arguments:
11 path
12 is the absolute or relative pathname of the file.
13
14
15 Control Arguments:
16 -extend
17 specifies extension of the file if it already exists.
18 -truncate, -tc
19 specifies truncation of the file if it already exists. This control
20 argument is only meaningful with openings for output and
21 input_output.
22 -old
23 indicates that a new file is not to be created if an attempt
24 is made to open a nonexisting file.
25 -append
26 in input_output openings, this control argument causes
27 put_chars and write_record operations to add to end of file
28 instead of truncating when the file position is not at end
29 of file. An existing file is not truncated at open.
30 -ssf
31 restricts the file to a single segment.
32
33
34 -share N
35 allows a file to be open in more than one process at the
36 same time, even though not all openings are for input.
37 If specified, N is the maximum time in seconds that this
38 process waits to perform an operation on the file. A value
39 of -1 means the process may wait indefinitely. The default
40 value of N is 1.
41 -blocked N
42 specifies attachment to a blocked file. If a nonempty file
43 exists, N is ignored and may be omitted. Otherwise, N is
44 used to set the maximum record size bytes.
45 -no_end
46 permits positioning beyond end of file and then appending
47 to the file without encountering an error.
48
49
50 -dup_ok
51 indicates that the creation of duplicate keys is permitted.
52 -exclusive
53 causes the exclusion of all shared references in other
54 openings for the duration of this opening. The file must
55 be opened for modification. This control argument
56 conflicts with the -share control argument.
57 -stationary
58 causes newly created records to be of the stationary type,
59 and forces vfile_ to maintain a reference count during the
60 addition and removal of keys from such records.
61 -transaction tcf_sw, -trans tcf_sw
62 indicates that all operations on this switch are performed
63 within transactions associated with a control file attached
64 to the I/O switch named tcf_sw.
65
66 -header N
67 indicates that a header is expected in an existing file, or
68 is to be created for a new file. N is the optional file
69 identifier.
70 -no_trunc
71 indicates that a put_chars order into the middle of an
72 unstructured file is permitted, and no truncation is to
73 occur in such cases.
74
75
76 Notes:
77 The -extend, -append, and -no_trunc control arguments conflict;
78 only one of these may be specified.
79
80
81 List of control orders:
82 The following orders are supported by the vfile_ I/O module.
83 Control orders can also be performed using the io_call command.
84 add_key
85 delete_key
86 error_status
87 exclude
88 file_status
89 get_key
90 max_rec_len
91 min_block_size
92 read_position
93 reassign_key
94 record_status
95 seek_head
96 select
97 set_file_lock
98 set_wait_time
99 truncate
100
101
102 Syntax of control orders from command level:
103 io_call control switch_name order optional_args
104
105
106 Arguments:
107 order
108 is any of the control orders supported by vfile_, or the short name
109 of the control order, if it has one.
110 optional_args
111 are required for certain orders as indicated in the descriptions
112 of the orders.
113
114
115 Multiple Openings:
116 It is possible to have two or more open I/O switches attached to the
117 same file. The switches might be in the same process or in different
118 processes. The classes of multiple openings are:
119 1. Openings for input without the -share control argument.
120 2. Openings for output or input_output without the -extend
121 control argument.
122 3. Openings for update without the -share control argument and
123 for output or input_output without the -share control argument
124 and with the -extend control argument.
125 4. Openings with the -share control argument.
126
127
128 Control order: add_key:
129 creates a new index entry with a given key and record descriptor.
130
131 The I/O switch must be open for direct_output, direct_update,
132 keyed_sequential_output, or keyed_sequential_update. Current and
133 next record positions are unchanged.
134
135
136 The info_ptr argument must point to a structure of the following form:
137
138 dcl 1 ak_info based info_ptr,
139 2 flags aligned,
140 3 input_key bit1 unal,
141 3 input_desc bit1 unal,
142 3 mbz bit34 unal,
143 2 descrip fixed bin35,
144 2 key_len fixed bin,
145 2 key char256 referak_info.key_len;
146
147
148 Info structure:
149 input_key Input
150 indicates whether the new key is given in the info structure.
151 input_desc Input
152 indicates whether the new descriptor is given in the info structure.
153 descrip Input
154 is used only if the variable input_descrip is set to "1"b.
155 The descriptor is stored into the index together with its
156 associated key.
157 key_len Input
158 is the length of the key_string.
159 key Input
160 is used only if ak_info.input_key is set to "1"b. It defines
161 the key to be added to the index with the appropriate record
162 descriptor.
163 mbz Input
164 must be set to zero by the user.
165
166
167 Command Level:
168 io_call control switch_name ak flags key descrip
169
170 Arguments:
171 flags
172 is a string of two bits corresponding to the switch
173 settings for input_key and input_descrip. If one argument is
174 given, it is interpreted as a key to be added to the current
175 record, i.e., flags defaults to "10"b
176 key
177 is a character string that must be given if flags.input_key is set.
178 descrip
179 is an octal descriptor that must be supplied if flags.input_descrip
180 is set.
181
182
183 Possible error codes:
184 error_table_$key_duplication
185 error_table_$too_many_refs
186 error_table_$no_key
187
188
189 Control order: delete_key:
190 The delete_key order deletes a specified index entry.
191 The I/O switch must be open for direct_update or
192 keyed_sequential_update.
193
194
195 For this order, the info_ptr argument may be null, or it may
196 point to a structure whose form is identical to the structure for
197 the add_key order.
198
199
200 Command Level: io_call control switch_name dk args
201
202 Arguments:
203 are the same as for add_key above flags key descrip.
204 Optionally, if no arguments are given, the order is equivalent
205 to a delete_key order with no info structure null info_ptr.
206
207
208 Possible error codes:
209 error_table_$last_reference
210 error_table_$no_key
211 error_table_$no_record
212
213
214 Control order: error_status:
215 returns information about the most recent attempt to position
216 beyond either end of file in the current opening. The
217 error_status order is accepted when the I/O switch is open
218 and attached to an indexed or sequential file.
219
220
221 The info_ptr argument must point to a structure of the
222 following form:
223
224 dcl 1 error_info based info_ptr,
225 2 version fixed bin,
226 2 type fixed bin,
227 2 requested fixed bin34,
228 2 received fixed bin34;
229
230
231 Info structure:
232 version Input
233 must be set to one by the user.
234 type Output
235 indicates the type of error that has occurred.
236 0 no errors
237 1 attempt to position beyond end or beginning of file.
238 requested Output
239 gives the value of the position skip argument that led to
240 the most recent error.
241 received Output
242 gives the actual number of records successfully skipped
243 before encountering end or beginning of file negative if
244 backwards skip.
245
246
247 Command Level: io_call control switch_name er
248
249
250
251 Control order: exclude:
252 causes subsequent vfile_ operations to behave as if a subset of
253 records and their keys are absent from an indexed file.
254
255 The subset of interest may be specified in terms of ranges of
256 keys, a list of record descriptors, or an identifying number for a
257 previously formed subset.
258
259 Various items of information that may be returned include a
260 subset number, count of distinct descriptors, or an identifying
261 number for a previously formed subset. However, status_only may not
262 be requested via exclude.
263
264 None of the file position designators current and next record
265 positions are affected by this order.
266
267
268 For this order, the info_ptr argument must point to one of the
269 following structures:
270
271 dcl 1 common_sl_info based info_ptr,
272 2 flags aligned,
273 3 list_type fixed bin3 unal,
274 3 status_only bit1 unal,
275 3 output_descriptors bit1 unal,
276 3 delete_old_subsets bit1 unal,
277 3 mbz bit11 unal,
278 3 version fixed bin17 unal,
279 2 array_limit fixed bin19,
280 2 subset_no fixed bin,
281 2 count fixed bin34,
282 2 desc_arrayp ptr;
283
284
285 where common_sl_info.desc_arrayp may point to the following
286 structure--
287
288 dcl desc_array1:common_sl_info.count fixed bin35
289 based sl_info.desc_arrayp;
290 or--
291 dcl 1 hi_sl_info based info_ptr,
292 2 common like common_sl_info,
293 2 interval1:sl_array_limit refer hi_sl_info.array_limit,
294 3 first_head,
295 4 length fixed bin,
296 4 kptr ptr unal,
297 3 last_head,
298 4 length fixed bin,
299 4 kptr ptr unal;
300
301
302 or--
303 dcl 1 da_sl_info based info_ptr,
304 2 common like common_sl_info,
305 2 desc_array1:sl_array_limit referda_sl_info.array_limit
306 fixed bin35;
307 dcl sl_array_limit fixed bin;
308 dcl sl_info_version_0 static optionsconstant internal fixed bin init0;
309
310
311 Structure elements:
312 flags.list_type Input
313 is a code indicating the manner in which this info
314 structure specifies a subset:
315 list_type=0
316 causes the reuse of a subset formed earlier in this opening,
317 whose subset number is given in sl_info.subset_no.
318 list_type=1
319 indicates that the subset is specified in terms of ranges of
320 keys, or index intervals, using a structure like hi_sl_info.
321 list_type=2
322 indicates that a list of descriptors with a structure like
323 da_sl_info will be used to define the subset of interest.
324
325
326 flags.status_only Input
327 if set, status information will be returned for the current
328 subset without making any subset changes.
329 flags.output_descriptors Input
330 if set, causes a sorted list of descriptors for the
331 resulting subset to be output into the structure desc_array.
332 flags.delete_old_subsets Input
333 if set, and list_type=1 or 2, causes all existing subsets to
334 be deleted. The current subset number must be 0.
335 version Input
336 is the version number for this info structure, which should
337 be set to sl_info_version_0.
338 array_limit Input
339 gives the number of array elements in this info structure.
340 subset_no Input/Output
341 is an identifying number for the resulting subset, which
342 permits its subsequent reuse in the same opening.
343
344
345 count Output
346 is the number of distinct record descriptors for the
347 resulting current subset.
348 desc_arrayp Input/Output
349 is used only if the flag, output_descriptors, is set. If
350 null, the required desc_array structure will be allocated
351 in system_free_area, and its address will be returned in
352 desc_arrayp. Otherwise, desc_arrayp is assumed to point to
353 an already allocated structure of sufficient size, in which
354 the sorted list of descriptors with duplications removed
355 is returned.
356 desc_array Output
357 is an optionally returned list of record descriptors in the
358 current subset, sorted and with duplications removed.
359
360
361 first_head.length Input
362 is the number of bytes in the key string that defines the
363 starting head for this range of keys.
364 first_head.kptr Input
365 gives the location of the character string that specifies
366 the first head of this index interval.
367 last_head.length Input
368 is the number of bytes in the key string that defines the
369 end of this index interval.
370 last_head.kptr Input
371 gives the address of the last_head.
372 da_sl_info.desc_array Input
373 contains a list of record descriptors that define the
374 subset of interest.
375
376
377 Command Level: io_call control switch_name ex args
378
379 Arguments:
380 -brief, -bf
381 suppresses the printing of the current subset number,
382 descriptor count, and any error messages except the errors
383 no_operation and bad_arg.
384 -delete_old_subset, -dos
385 deletes all existing subsets, before the new subset is created.
386 This is incompatible with -list. The current subset number
387 must be 0.
388 -list, -ls
389 prints the list of descriptors for the resulting subset.
390 -key -head interval_spec1 -or -or_key
391 interval_spec2 -or -or_key interval_specN...
392 specifies the subset in terms of ranges of keys where:
393 interval_spec
394 is of the form: first_key -thru -to last_key
395
396
397 -key
398 indicates that the following interval is defined as
399 those keys exactly matching the specified first_key .
400 A last_key may not be given for this interval.
401 -head
402 indicates that the following interval starts with the
403 first key whose head is greater than or equal to the
404 specified first_key. This is the default.
405 first_key
406 is a character string that defines the starting point
407 for a range, or interval of keys.
408
409
410 last_key
411 is a character string giving the head that defines the
412 end of an index interval. Its default value is that
413 of the first_key.
414 -thru
415 separates the first and last key specifications for a
416 closed index interval.
417 -to
418 separates the first and last key specifications for an
419 open index interval.
420 -or
421 delimits the start of another interval specification
422 that is of the default type.
423 -or_key, -ork
424 delimits the start of an interval specification of the
425 type that follows the -key control argument.
426
427
428 -or -or_key interval_spec1 interval_spec2...
429 is the same as -key -head above, except:
430 -or
431 if the first argument, it is taken as the default
432 delimiter, and should be omitted between interval
433 specifications following on this command line.
434 -or_key, -ork
435 if the first argument, it is taken as the default
436 delimiter, and should be omitted between interval
437 specifications following on this command line.
438
439
440 -desc descriptor_list
441 specifies the subset in terms of a list of record
442 descriptors where:
443 -desc, -ds
444 indicates that the subset specification for this order
445 is in terms of a list of descriptors that follows.
446 descriptor_list
447 is a list of octal record descriptors.
448
449
450 -reset subset_number
451 specifies the subset in terms of an identifying number for
452 a previously formed subset where:
453 -reset, -rs
454 indicates that a previously formed subset is to be
455 reused. If no subset_number follows, subset 0 is
456 assumed.
457 subset_number
458 is the identifying subset number for the subset to be
459 reused.
460
461
462 Possible error codes:
463 error_table_$no_record
464 error_table_$no_operation
465 error_table_$bad_arg
466
467
468 Control order: file_status:
469 returns various items of information about the file. The info_ptr
470 argument must point to a structure identical to one of those required
471 for the vfile_status_ subroutine.
472
473 Command Level: io_call control switch_name fs
474
475
476 Control order: get_key:
477 returns both the key and the record descriptor for the specified
478 index entry in a file opened for keyed_sequential_input or
479 keyed_sequential_update.
480
481
482 The info_ptr argument must point to a structure of the following form:
483
484 dcl 1 gk_info based info_ptr,
485 2 flags aligned,
486 3 input_key bit1 unal,
487 3 input_desc bit1 unal,
488 3 desc_code fixed bin2 unal,
489 3 position_specification unal,
490 4 current bit1 unal,
491 4 rel_type fixed bin2 unal,
492 4 head_size bit9 unal,
493 3 reset_pos bit1 unal,
494 3 mbz bit8 unal,
495 3 version fixed bin8 unal,
496 2 descrip fixed bin35,
497 2 key_len fixed bin17,
498 2 key char256 refergk_info.key_len;
499 dcl gk_info_version_0 fixed bin static init0;
500
501
502 Info structure:
503 input_key Input
504 if set to "1"b indicates that the key in this info structure is
505 an input argument, which must bear the specified relationship to
506 a key in the index. Otherwise the key of interest is located
507 through either the next or the current position, according to
508 the setting of flags.current.
509 inputdesc Input
510 if set to "1"b indicates that the desired index entry must have
511 a descriptor that is equal to that given in this structure as an
512 input argument. Otherwise the descriptor may either have any
513 value or must be that of the current record, as specified by the
514 setting of flags.desc_code.
515
516
517 desc_code Input
518 is used only if flags.input_desc="0"b to specify the desired
519 descriptor portion of an index entry. If desc_code=0, then any
520 descriptor is satisfactory. If desc_code=1, then the index
521 entry of interest must be associated with the current record.
522 No other desc_code settings are defined in this implementation.
523 current Input
524 applies only if flags.input_key="0"b. If set to "1"b, this
525 indicates that the current index entry is the one of interest.
526 This control argument conflicts with the setting of
527 flags.input_desc to "1"b. Otherwise, if flags.current="0"b, the
528 next record position is used as a starting point to find the
529 desired index entry by scanning for the next occurrence of the
530 desired descriptor, until end of file is encountered, or until
531 the next key ceases to satisfy an immediately preceding
532 successful seek_head order.
533
534
535 rel_type Input
536 applies only if flags.input_key="1"b. This indicates the
537 desired relationship that the head of a key in the index must
538 have with the key_string given in this info structure. Allowed
539 values and their meanings are the same as those for the
540 seek_head order.
541 head_size Input
542 applies only if flags.input_key="1"b, specifying the number of
543 characters in the key_string contained in the desired head.
544 reset_pos Input
545 if set to "1"b, the state of the file position designators will
546 be left unchanged by this order. Otherwise the current and next
547 record positions will be left at the specified index entry.
548
549
550 version Input
551 is the version of this info structure, which should be set to
552 gk_info_version_0.
553 descrip Input/Output
554 is the record locator portion of the specified index entry. If
555 flags.input_desc="1"b, this is an input argument. Descriptors
556 may also be input to the control orders add_key, delete_key,
557 reassign_key, and record_status.
558 key_len Input/Output
559 is the length of the key for the specified index entry.
560 key Input/Output
561 if flags.input_key="1"b, this is an input argument that contains
562 the desired key head. The value that is returned is the key of
563 the specified index entry.
564 mbz Input
565 must be set to zero by the user.
566
567
568 Command Level: io_call control switch_name gk args
569
570 Arguments:
571 -brief, -bf
572 suppresses printing of the key, its descriptor, and any error
573 messages except for the errors no_operation and bad_arg.
574 key_specification
575 is either of the form: -head key_string -rel_type n
576 or: -cur_pos
577 where:
578 -head
579 indicates that the following argument is to be taken
580 as the key giving the head that must bear the specified
581 relationship to the key of the desired index entry.
582 key_string
583 defines the keyportion of the index entry of interest.
584
585
586 -rel_type, -rel
587 applies only when a key_string is specified. This
588 argument must be followed by a number that defines a
589 valid relationship between the given key_string and
590 the head of a key in the index. If not specified,
591 -rel 0 is assumed, when applicable.
592 n
593 has the same meaning and set of permissible values as
594 the corresponding argument in the seek_head order.
595 -cur_pos
596 indicates that the index entry of interest is at the
597 current record position. This control argument
598 conflicts with a key_string specification.
599
600
601 record_specification
602 is either: -current
603 or: -desc descriptor
604 where:
605 -current, -cur
606 specifies that the desired index entry belongs to the
607 current record.
608 -desc, -ds
609 specifies that the desired index entry has a given
610 descriptor, which must be the next argument.
611 descriptor
612 is an octal record descriptor, like those returned by
613 this order.
614
615
616 -reset, -rs
617 causes the final position to be left unchanged.
618 -substr_spec
619 suppresses printing of the record's descriptor, and is of the form:
620 -substr offsetlength
621 where:
622 -substr
623 specifies a substring of the key to be returned.
624 offset
625 is the starting character position of the key to be
626 returned.
627 length
628 is the length of the part of the key to be returned.
629
630
631 Possible error codes:
632 error_table_$no_record
633 error_table_$no_key
634 error_table_$no_operation
635 error_table_$bad_arg
636
637
638 Control order: max_rec_len:
639 returns the maximum record length bytes of the file. A new
640 maximum length can be set by specifying a nonzero value for the
641 second argument.
642
643 The info_ptr argument must point to a structure of the following form:
644
645 dcl 1 info based info_ptr,
646 2 old_max_recl fixed bin21, /*output*/
647 2 new_max_recl fixed bin21; /*input*/
648
649 Command Level: io_call control switch_name mx arg
650
651 Possible_error_codes:
652 error_table_$no_operation
653
654
655 Control order: min_block_size:
656 determines the minimum size for blocks of record space that are
657 subsequently allocated by write_record or rewrite_record operations
658 documented in the iox_ subroutine. The specification remains in
659 effect for the duration of the current opening or until another call
660 to this order is issued. The I/O switch must be attached to an
661 indexed file open for output or update.
662
663 The info_ptr argument must point to a structure of the following form:
664
665 dcl 1 min_blksz_info based info_ptr,
666 2 min_residue fixed bin21,
667 2 min_capacity fixed bin21;
668
669
670 Info structure:
671 min_residue Input
672 specifies the minimum unused capacity of a record block bytes;
673 i.e., the difference between the record's length and the maximum
674 length it can attain without requiring reallocation.
675 min_capacity Input
676 specifies the minimum total record capacity bytes; i.e., the
677 maximum length that the record can attain without requiring
678 reallocation.
679
680 Command Level: io_call control switch_name mb args
681
682 Arguments:
683 min_res
684 is an integer. The default is 0.
685 min_cap
686 is an integer. The default is 0.
687
688
689 Control order: read_position:
690 returns the ordinal position 0 1 2 ... of the next record
691 and that of the end of file, relative to the file base.
692
693 The info_ptr argument must point to a structure of the following form:
694
695 dcl 1 info based info_ptr,
696 2 next_position fixed bin34, /*output*/
697 2 last_position fixed bin34; /*output*/
698
699 Command Level: io_call control switch_name rp
700
701
702 Control order: reassign_key:
703 causes the descriptor portion of a specified index entry to be
704 replaced with a given value.
705
706 When the -stationary control argument is used, the reference
707 counts of any stationary records involved are adjusted accordingly,
708 as described for add_key and delete_key.
709
710
711 The info_ptr argument must point to a structure of the following form:
712
713 dcl 1 rk_info based info_ptr,
714 2 flags aligned,
715 3 input_key bit1 unal,
716 3 input_old_desc bit1 unal,
717 3 input_new_desc bit1 unal,
718 3 mbz bit33 unal,
719 2 old_descrip fixed bin35,
720 2 new_descrip fixed bin35,
721 2 key_len fixed bin,
722 2 key char256 referrk_info.key_len;
723
724
725 Info structure:
726 input_key Input
727 indicates whether the key is given in the info structure.
728 input_old_desc Input
729 indicates whether the old descriptor is given in the info structure.
730 input_new_desc Input
731 indicates whether the new descriptor is given in the info structure.
732 old_descrip Input
733 is used only if rk_info.input_old_desc equals "1"b. The entry
734 that is reassigned is the first whose descriptor matches this
735 value, among those index entries with the specified key.
736
737
738 new_descrip Input
739 is used only if rk_info.input_new_desc equals "1"b. This value
740 replaces the old descriptor of the specified index entry.
741 key_len Input
742 same as in the add_key_info structure above.
743 key Input
744 if rk_info.input_key equals "1"b, this argument defines the key
745 for which the index entry with the specified descriptor is to be
746 reassigned.
747
748
749 Command Level: io_call control switch_name rk flags args
750
751 Arguments:
752 flags
753 is a string of three bits corresponding to the switch
754 settings input_key, input_old_desc, input_new_desc.
755 key
756 is a character string that must be given if flags.input_key is set.
757 old_descrip
758 is an octal number required if flags.input_old_desc is set.
759 new_descrip
760 is an octal number required if flags.input_new_desc is set.
761
762
763 Possible error codes:
764 error_table_$last_reference
765 error_table_$too_many_refs
766 error_table_$no_key
767 error_table_$no_record
768
769
770 Control order: record_status:
771 returns information about a specified record in an indexed,
772 sequential, or blocked file, and optionally permits the user to
773 manipulate the lock of the record or to allocate an empty record
774 or both. The I/O switch must be open and attached to a structured
775 file.
776
777
778 The info_ptr argument must point to a structure of the following form:
779
780 dcl 1 rs_info based info_ptr aligned,
781 2 version fixed bin,
782 2 flags aligned,
783 3 lock_sw bit1 unal,
784 3 unlock_sw bit1 unal,
785 3 create_sw bit1 unal,
786 3 locate_sw bit1 unal,
787 3 inc_ref_count bit1 unal,
788 3 dec_ref_count bit1 unal,
789 3 locate_pos_sw bit1 unal,
790 3 mbz1 bit29 unal,
791 2 record_length fixed bin21,
792 2 max_rec_len fixed bin21,
793 2 record_ptr ptr,
794 2 descriptor fixed bin35,
795 2 ref_count fixed bin17,
796 2 time_last_modified fixed bin71,
797 2 modifier fixed bin34,
798 2 block_ptr ptr unal,
799 2 last_image_modifier fixed bin35,
800 2 mbz21 fixed bin;
801 dcl rs_info_version_2 static internal fixed bin init2;
802
803
804 Info structure:
805 version Input
806 is provided for compatibility with possible future
807 versions of this info structure. The user should set this
808 argument to rs_info_version_2.
809 lock_sw Input
810 indicates whether an attempt is made to lock the specified
811 record within the wait time limit given at attachment or
812 subsequently set via the set_wait_time order documented in
813 the MPM Subroutines.
814 Possible error codes:
815 error_table_$invalid_lock_reset
816 error_table_$locked_by_this_process
817 error_table_$record_busy
818 error_table_$no_room_for_lock
819 error_table_$higher_inconsistency
820
821
822 unlock_sw Input
823 indicates whether an attempt is made to unlock the record.
824 Possible error codes:
825 error_table_$lock_not_locked
826 error_table_$locked_by_other_process
827 error_table_$no_room_for_lock
828 create_sw Input
829 indicates whether a new record is allocated using the
830 record_len and max_rec_len arguments as input parameters.
831 locate_sw Input
832 indicates how the record of interest is located.
833 Possible error codes:
834 error_table_$no_record
835 error_table_$no_key
836
837
838 inc_ref_count Input
839 increments the reference count of the record.
840 Possible error codes:
841 error_table_$no_room_for_lock
842 error_table_$too_many_refs
843 dec_ref_count Input
844 if set to "1"b and the record is of the stationary type,
845 this causes its reference count to be decremented.
846 Possible error codes:
847 error_table_$last_reference
848 locate_pos_sw Input
849 if set to "1"b, the current and next record positions are first
850 set to the record whose ordinal position is given in
851 rs_info.record_length. The file must be either blocked or
852 sequential. If the file is sequential, then the descriptor of
853 the record must also be supplied as an input argument.
854
855
856 record_length Input/Output
857 gives the record's length in bytes. If create_sw equals
858 "1"b, this argument is input.
859 max_rec_len Input/Output
860 gives the maximum length that the record can attain bytes
861 without requiring reallocation.
862 record_ptr Output
863 is a pointer to the first byte of the allocated record, or
864 is set to null if no allocated record exists.
865 descriptor Input/Output
866 is a process-independent locator for the specified record.
867 This value is used as an input argument when locate_sw
868 equals "1"b and create_sw equals "0"b. The actual
869 structure of each descriptor is as follows:
870
871
872 dcl 1 descrip_struct based addrdescriptor aligned,
873 2 comp_num fixed bin17 unal,
874 2 word_offset bit18 unal;
875
876
877 Info structure:
878 comp_num
879 is the multisegment file component number of
880 the segment containing the record.
881 word_offset
882 is the word offset of the block of storage containing the
883 allocated record, relative to the base of its file component.
884
885 A zero descriptor designates an unallocated
886 zero-length record.
887
888
889 Descriptors may also be arguments to the add_key,
890 delete_key, reassign_key, and get_key orders. Note that at any
891 given time within a single file each record is uniquely located
892 by its descriptor, which remains valid only for the life of a
893 single allocation.
894
895
896 ref_count Output
897 is returned only if the record is of the stationary type, in
898 which case this is the reference count of the record. When the
899 -stationary control argument is used, vfile_ automatically
900 maintains the reference counts of stationary records to reflect
901 the number of keys on each record.
902 time_last_modified Output
903 contains a standard system clock time for the most recent
904 modification made to the current record. Applies only for
905 stationary records.
906 modifier Input/Output
907 is the identifying number of a transaction on whose behalf the
908 record was locked.
909
910
911 block_ptr Output
912 points to the start of the allocated block for the record.
913 last_image_modifier Output
914 is the transaction number for the most recent modification
915 of this record. If zero, then the most recent modification
916 was not made under the -transaction option.
917 mbz1, mbz2 Input
918 must be set to zero by the user.
919
920
921 Notes: Extreme caution must be exercised when using the orders
922 that take a descriptor as an input argument, especially in a
923 shared environment. The user is responsible for ensuring that
924 previously obtained descriptors and pointers are still valid
925 when they are used.
926
927
928 Command Level: io_call control switch_name rs args
929
930 Arguments:
931 -brief, -bf
932 suppresses the printing of status information.
933 flags, -pos
934 is a string of seven bits, corresponding to the switch settings
935 for lock_sw, unlock_sw, create_sw, locate_sw, inc_ref_count,
936 dec_ref_count, and locate_pos_sw. This argument defaults to
937 "0000000"b if not given. The setting of locate_pos_sw may also
938 be expressed by the use of the -pos control argument as an
939 abbreviation for the corresponding specification of flags.
940 recl
941 is an integer that must be given when flags.create_sw is
942 set. This determines the new record length.
943
944
945 maxl
946 is an optionally supplied integer that may be given with
947 recl to specify a maximum record length. This defaults to
948 recl if not given.
949 descrip
950 is an octal record descriptor required when flags.locate_sw
951 is set and flags.create_sw is not set.
952 pos_spec
953 is a number or pair of numbers specifying the record's
954 ordinal position. This specification is required
955 and applies only when flags.locate_pos_sw is set.
956
957
958 Control order: seek_head:
959 locates the first record with a key whose head has the
960 specified relation with the given search_key. The next record
961 position and the current record position are set to the record.
962
963 The info_ptr argument must point to a structure of the following form:
964
965 dcl 1 info based info_ptr,
966 2 relation_type fixed bin,
967 2 n fixed bin,
968 2 search_key char 256 refer info.n;
969
970
971 Command Level: io_call control switch_name sh args search_key
972
973 Arguments:
974 -brief, -bf
975 suppresses any error message except the no_operation and
976 bad_arg errors.
977 rel_type
978 is a single digit, 0, 1, or 2. If omitted, the last
979 argument is interpreted as a search_key, with a default
980 rel_type of 0.
981 search_key
982 is any character string.
983
984 Possible error codes:
985 error_table_$no_record
986
987
988 Control order: select:
989 causes subsequent vfile_ operations to behave as if a subset of all
990 the records and their keys were present in an file.
991
992 Use is the same as that described for the exclude order, except
993 that status_only may be requested via select.
994
995 Command Level: io_call control switch_name sl args
996
997 Arguments:
998 are the same as those described for the exclude order.
999
1000 Possible error codes:
1001 error_table_$no_record
1002
1003
1004
1005 Control order: set_file_lock:
1006 causes the file to be locked if possible within the wait_time limit
1007 or unlocked, depending on whether the user has set the first bit of
1008 info_ptr->set_lock_flag to "1"b or "0"b, respectively. It is accepted
1009 when the I/O switch is open for output or update and attached to an
1010 indexed file with the -share control argument.
1011
1012 The info_ptr argument must point to a variable of the following form:
1013
1014 dcl set_lock_flag bit2 aligned based info_ptr;
1015
1016
1017 Command Level: io_call control switch_name sf set_lock_flag
1018
1019 Arguments:
1020 set_lock_flag
1021 is a string of two bits.
1022
1023 Possible error codes:
1024 error_table_$locked_by_this_process
1025 error_table_$lock_not_locked
1026 error_table_$file_busy
1027
1028
1029 Control order: set_wait_time:
1030 specifies a limit on the time that the user's process waits to
1031 perform an order when the file is locked by another process. The
1032 interpretation of new_wait_time is the same as that described earlier
1033 for the argument N used with the -share control argument.
1034
1035 The info_ptr argument must point to one of the following structures:
1036
1037 dcl new_wait_time float based info_ptr;
1038 or:
1039 dcl 1 wt_info based info_ptr,
1040 2 version float, /*Input*/
1041 2 collection_delay_time float; /*Input*/
1042
1043
1044 If wt_info.version equals -2 -2.0e0, the second argument is
1045 taken as a new collection_delay_time, in seconds. Initially,
1046 in any opening, a default value of 0 applies.
1047
1048 Command Level: io_call control switch_name sw arg new_wait_time
1049
1050 Arguments:
1051 -collection_delay_time, -cdtm
1052 specifies the amount of time that must elapse after deleting a
1053 stationary record before its storage can be completely recovered.
1054 new_wait_time
1055 is a floating point number. If -cdtm is specified, new_wait_time
1056 is taken as the new collection delay time.
1057
1058
1059 Control order: truncate:
1060 truncates the file at the next record byte for unstructured files.
1061
1062 Command Level: io_call control switch_name tc
1063
1064 Possible error codes:
1065 error_table_$no_record