Control file system functions

Optical support provides Control File System (QHFCTLFS) functions to perform unique operations for the optical file system.

The functions described below are optical specific functions that are not otherwise available through the HFS APIs. Different functions are available for directly attached and LAN-attached optical devices.

The following control file system functions are available for directly attached media libraries:
  • SAV. Saves a held optical file.
  • RLS. Releases a held optical file.
  • SRD/VOL. Performs a sector read to an optical volume.
  • SRD/DEV. Performs a sector read to an optical device.
  • RTV/VOL. Returns volume-specific information.
  • GET. Reads file data directly from the media with minimal caching.

Control File System functions for directly attached optical devices

The following functions are available for directly attached optical devices.

Save held optical file function

Use the Control File System program to save a held optical file. A process must be allowed read access to a held optical file to save it.

The following is the syntax for the input buffer for the QHFCTLFS program:

'SAV' + '/' + held-file-path + '//' + destination-file-path

For example:
  • Input data buffer: SAV/VOLUME1/DIRECTORY1/FILE1//VOLUME2/DIRECTORY2/FILE2
  • Input data buffer length: 54

This function is also available using an option on the Work with Held Optical File (WRKHLDOPTF) display. However, unlike the save option on the Work with Held Optical File (WRKHLDOPTF) display, the save held optical file function of the control file system API does not automatically release a held file after it is saved. Therefore, an explicit release held optical file request is needed afterward.

Release held optical file function

Use the Control File System program to clear the held status of a file and release the optical file system from its obligation to write to the optical disk. A process must be allowed read and write access to a held file in order to release it; this means that no locks may currently be imposed on the file by other active jobs.

The following is the syntax for the input buffer for the QHFCTLFS program: 
'RLS' + '/' + held-file-path
For example:
  • Input data buffer: RLS/VOLUME1/DIRECTORY1/FILE1
  • Input data buffer length: 28

This function is also available using an option on the Work Held Optical File (WRKHLDOPTF) display.

Sector read function

The Control file system program can be used to do a sector reading of optical media. The sector read function is useful if the application knows precisely where data is stored on optical media. Sector read functions can be accomplished without opening and closing files and independently of all HFS APIs. Multiple sectors may be read at one time.

There are two variations of the input buffer for issuing the Control File System sector read function: 
SRD/VOL/volume_name/starting sector/number of sectors
SRD/DEV/device_name/starting sector/number of sectors

Both return the range of sectors requested by the user. Sectors can be requested from an optical volume or optical device. For example, if an application wanted to read five sectors of optical volume VOL01 beginning at sector 1000, the following is requested: SRD/VOL/VOL01/1000/5

Note: DEV is valid for stand-alone CD and DVD devices.

Retrieve volume information function

Use the Control File System program to retrieve information about a particular volume.

The following is the input buffer format for the QHFCTLFS program: 
RTV/VOL/volume_name

The format of the information returned in the output buffer is identical to the output file structure for volume attributes (QAMODVA).

Get file data

You can use the Control File System (QHFCTLFS) HFS API to read a block of data from a file directly into your output buffer. This function improves performance when reading an entire file sequentially or when reading large blocks of data. The optical file system will not copy or cache the data as it does through normal Open, Read, and Close Stream File HFS APIs. When doing random read operations to a file, the Open, Read, and Close Steam File option may still provide the best performance.

The following restrictions apply when using this API:
  • Align output buffer on a 512-byte boundary.
  • File offset must be 0 or a multiple of 4096.
  • Maximum-read size is 16␠384␠000 bytes.
  • The HFS API requires Shared No Update (*SHRNUP) access to the file.
  • Calling program must be in user (not system) state.
  • The HFS API requires *USE authority to the volume.
Here is the syntax for the input buffer for the QHFCTLFS program: 
'GET' + '/' + entire path + '//' + bytes to read + '/' + file offset
The following example will read 15 MB from FILE.XXX, starting at the beginning of the file with (offset=0):
  • Input data buffer: GET/VOL1/DIR1/SUBDIR1/FILE.XXX//15728640/0
  • Input data buffer length: 42

The number of bytes read is returned in the Length of data returned parameter. In the above example if FILE.XXX is only 50 KB in size, 51200 will be returned in the field. Therefore, it is not necessary to know the file size prior to issuing this request. Likewise, if 15728640 is returned in the Length of data returned parameter, the file is at least 15 MB in size. More read operations may be necessary to retrieve all the data.

It is not required that the number of bytes to read be a multiple of 4096. However, if the number is not a multiple of 4096, data may be read into the output buffer beyond the number of bytes requested. This is because the device does I/O in blocks of 4096 bytes. Therefore, reading data in multiples of 4096 bytes is advised in order to avoid this problem.

Errors from control file system (GET)

The following table shows some common application errors that may occur using this API.

Table 1. Common errors for the GET API
Message Error
OPT1812 with 6030 as unexpected return code File offset is beyond the end of file.
OPT1812 with A950 as unexpected return code Output buffer is not 512-byte aligned.
OPT1860 Bytes to read is greater than the buffer size.
OPT1812 with C060 as unexpected return code Attempted to read more than 16␠384␠000 bytes.
OPT1812 with C061 as unexpected return code File offset is not a 4096 multiple.
CPF1F48 Input buffer is not valid. Verify the syntax.

Control file system functions for LAN-attached optical devices

The following control file system functions are available for LAN-attached media libraries.
  • UPD/LAN - performs a dynamic refresh of the LAN volume lists.
  • UPD/VOL - returns volume-specific information.
  • RTV/VOL - returns volume-specific information.
  • RTV/DIR - returns subdirectory and file entries for a specified directory.

Update volume information

Use the Control File System program to retrieve information about a particular volume or to update the internal list of available volumes on a LAN.

The following is the input buffer format for the QHFCTLFS program: 
UPD/VOL/volume_name
It performs the following:
  • UPD/VOL/volume-name: Using this input buffer format returns the amount of free space on a volume, total user space, media type, and opposite-side volume ID. The format is shown here:
    • Bytes (1-32): Opposite-side volume ID.
    • Bytes (33): Reserved.
    • Bytes (34-37): User free space on the volume. This is a 4-byte binary field.
    • Bytes (38-41): Total free space on the volume. This consists of the user free space on the volume plus the reserved space on the volume. The reserved space on the volume is determined when setting the volume-full threshold for the volume. This is a 4-byte binary field.
    • Bytes (42): Media type. This is a 1-byte binary field that can have the following values.
      • 0 = Nonvalid Media or 3431 Standalone Drive
      • 1 = Write Once Read Many (WORM) media
      • 2 = Rewriteable media
    • Bytes (43): Magnitude of free space on the volume. This is a 1-byte binary field that can have the following values:
      • 0 = Space field is in number of bytes.
      • 1 = Space field is in number of kilobytes (1024).
      • 2 = Space field is in number of megabytes (1048576).
    • Bytes (44): Magnitude of Total Space on the Volume. This is a 1-byte binary field that can have the following values:
      • 0 = Space field is in number of bytes.
      • 1 = Space field is in number of kilobytes (1024).
      • 2 = Space field is in number of megabytes (1048576).
  • UPD/LAN: Using this input buffer format updates an internal list of available volumes on all activated servers. You can perform this function after adding or removing cartridges from data servers.

Retrieve volume information function

Use the Control File System program to retrieve information about a particular volume.

The following is the input buffer format for the QHFCTLFS program:
RTV/VOL/volume_name

The format of the information returned in the output buffer is identical to the output file structure for volume attributes (QAMODVA).

The system uses format QAMODVA for volumes in all optical device types. While the format is the same, not all fields contain a value for LAN volumes.

Retrieve directory information function

Use the Control File System program to retrieve a list of files and subdirectories for a particular directory.

The following is the input buffer for the QHFCTLFS program:
RTV/DIR/volume_name/directory_name
The directory information is returned in the output buffer in the following format:
  • CBdirectoryBCBdirectoryBCBfilenameBCBfilenameBB, whereas the following are:
    • C
      • D = Directory entry
      • F = File name entry
    • B = EBCDIC blank
    • BB = Double EBCDIC blanks to indicate end of string

The output buffer must be at least 31 KB long.

Parent topic: Hierarchical file system (HFS) programming