Programming interfaces (UDF)

You can create files or read files on Universal Disk Format (UDF) media by using either the Hierarchical File System (HFS) application programming interfaces (APIs) or the Integrated File System APIs. There are things specific to the IBM® i implementation of the UDF that application developers need to know.

National language support

The integrated file system interfaces assume that the coded character set identifier (CCSID) represents the path in effect for the job. The system then converts the path from the job CCSID to an internally used CCSID. The HFS APIs make no assumption about the CCSID of the path; therefore, the system performs no character set conversion on the path. This can produce undesirable side effects if an application used the two API sets interchangeably or if the application changed from using one API set to the other.

Do not create files through HFS and then try to read them by using the Integrated File System APIs. Depending on the characters that are used in the path name, a File not found error might result. This type of problem can be avoided if the application uses only invariant characters (for example, letters (A-Z), numbers (0-9), plus sign (+), equal sign (=), percent sign (%), ampersand (&), ( ), comma (,), underscore (_), period (.), colon (:), and semicolon (;)) for path names. Invariant characters are graphic characters that map to the same code point in all character sets.

Since UDF is an industry-standard media format, NLS compliance can be important because of the increased opportunity for media interchange across different operating system platforms. This causes the system to limit HFS interfaces to UDF media. Additionally, the system uses invariant characters to reduce the chance of media interchange problems that are related to file names. Assume that an HFS-based application absolutely requires the use of variant characters. You can use the Change Optical Attributes (CHGOPTA) CL command to allow variant characters through the HFS interface by specifying CHGOPTA ALWVRNT(*YES). After the system allows variant characters through HFS, there is no guarantee that path names will interchange correctly if accessed from another operating system. There is also no guarantee that path names will be consistent between the HFS and integrated file system interfaces.

Held optical files

The system does not create held files for UDF media. When a file fails to close on UDF, the system signals an error to the application. This error then closes the file without writing the data to optical disk. The application must rewrite the file (open, write, close) to ensure that the data is on optical disk. The exception to this is if the application performs a Force Buffered Data (QHFFRCSF) or fsync() API before the close operation.

These APIs force the writing of the data to the optical disk.

File sharing

Multiple jobs or threads can share files for a read operation, but writers are always exclusive. If one job or thread is writing to a file on UDF, you cannot use any other jobs or threads to open that file.

Therefore, when using the integrated file system open() or open64() API, the sharing modes O_SHARE_RDONLY, O_SHARE_WRONLY, and O_SHARE_RDWR do not provide the requested level of sharing when the access mode is O_RDWR or O_WRONLY. When the access method is O_RDWR or O_WRONLY, the resulting sharing mode will be equivalent to O_SHARE_NONE.

When using the HFS Open Stream File API, the lock modes deny none, deny write, and deny read do not provide the requested level of sharing when the access mode is write only or read/write. When the access method is write only or read/write, the resulting lock mode is deny read/write.

Mixed-case file name

When created through the integrated file system interfaces, files and directories created on UDF volumes preserve the case specified on the create operation. For example, if file Abc is specified on the open() API, Abc will be created on the media in the mixed-case form. Even though the system preserves case of the file name, file searches are not case sensitive, meaning that the system can read the file that uses any case, such as ABC or abc.

When created through the HFS or save and restore interfaces, the system stores files and directories that are created on the UDF volumes in uppercase. For example, if you specify file Abc on the Open Stream File (QHFOPNSF) API, the system creates ABC on the media. Again, file searches are not case sensitive, so you can specify any case to read the file.

File searches on UDF volumes created by IBM i are not case sensitive. For UDF media created or updated by another operating system platform, a case-sensitive search is performed. If no case-sensitive match is found, a match that is not case sensitive is returned if it exists. If multiple matches exist on the UDF volume that are not case sensitive, an error is returned indicating that ambiguous names exist on the media.