Guardian Procedure Calls Reference Manual

Considerations
• File pointer action
The end-of-file pointer is set to 0 after the file is created.
• Disk allocation with FILE_CREATE_
Execution of the FILE_CREATE_ procedure does not allocate any disk area; it only provides
an entry in the volume's directory, indicating that the file exists.
• Altering file security
The file is created with the caller's process file security, which can be examined and set with
the PROCESS_SETINFO_ procedure. Once a file has been created, its file security can be
altered by opening the file and issuing the appropriate SETMODE and SETMODENOWAIT
procedure calls.
• Odd unstructured files
An odd unstructured file permits reading and writing of odd byte counts and positioning to
odd byte addresses.
If options.<15> is 1 and file-type is 0, an odd unstructured file is created. In that case,
the values of record-specifier, read-count, and write-count are all interpreted
exactly; for example, a write-count or read-count of 7 transfers exactly 7 bytes.
• Even unstructured files
If file-type is 0 and options.<15> is 0, an even unstructured file is created. In that case,
the values of read-count and write-count are each rounded up to an even number; for
example, a write-count or read-count of 7 is rounded up to 8, and 8 bytes are
transferred.
An even unstructured file must be positioned to an even byte address; otherwise, the
FILE_GETINFO_ procedure returns error 23 (bad address).
If you use the File Utility Program (FUP) CREATE or HP Tandem Advanced parameter Language
(TACL) CREATE parameter to create a file, it creates an even unstructured file by default.
• Upper limit for maximum-extents
There is no guarantee that a file will be created successfully if you specify a value greater
than 500 for maximum-extents. In addition, FILE_CREATE_ returns error 21 if the values
for primary-extent-size, secondary-extent-size, and maximum-extents yield
a file size greater than (2**32) - 4096 bytes (approximately four gigabytes) or a partition
size greater than 2**31 bytes (two gigabytes).
It is not always possible to allocate all of the extents specified by maximum-extents. The
actual number of extents that can be allocated depends on the amount of space in the file
label. If there are alternate keys or partitions, the maximum number of extents allowed is less
than 978. If you specify MAXEXTENTS, you must also consider the primary and secondary
extent sizes to avoid exceeding the maximum file size.
• For unstructured files on a disk device other than a legacy device with 514-byte sectors
4
, both
primary-extent-size and secondary-extent-size must be divisible by 14.
When you create an unstructured disk file, if you specify file extents that are not divisible by
14 in the FILE_CREATE_ call, the extents are automatically rounded up to the next multiple of
14, and the specified MAXEXTENTS is lowered to compensate. FILE_CREATE_ does not return
an error code to indicate this change. This change is visible only if you call FILE_GETINFOLIST_
to verify the extent size and the MAXEXTENTS attributes.
4. Devices with 514-byte sectors are not used on TNS/E systems.
FILE_CREATE_ Procedure 389