CPGuide - File Management

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation

Control Program Programming Guide and Reference

Introduction to the Control Program Control Program Functions Keyboard Functions Mouse Functions Video Functions Data Types Errors Debugging Kernel Debugger Communications Protocol Device I/O Dynamic Linking Error Management Exception Management Extended Attributes File Management File Names File Systems Generic IOCtl Commands Memory Management Message Management National Language Support Pipes Program Execution Control Queues Semaphores Timers Notices Glossary

OS/2 provides a standard set of file system functions. This means that applications can create, open, read, write, copy, and delete files and directories by using the same functions, regardless of which file system is used. When an application calls a file system function, OS/2 passes the request to the dynamic link library that supports the file system. The dynamic link library carries out most file system processing, such as validating file names. If an error occurs, the file system returns the error to OS/2, which then passes it back to the calling application.

The OS/2 file system functions identify files and directories by their names. These functions store or search for the file or directory in the current directory on the current drive unless the name explicitly specifies a different directory and drive. Occasionally, a file system has control functions in addition to the standard file system functions. The control functions are specific to the given file system. An application can call a control function by using DosFSCtl, which directs OS/2 to pass the control-function information to the corresponding Installable File System (IFS).

The following topics are related to the information in this chapter:

• Files systems
• Files names
• Extended attributes
• Pipes
• Device I/O

About Volumes and Drives

OS/2 allows more than one file system on a single storage device. If the device can have more than one partition (or volume), each partition can be initialized as an OS/2 partition and given a valid OS/2 file system. For each volume, OS/2 determines the type of file system the first time the volume is accessed by a function or when the medium in the drive changes. After that, OS/2 manages all input and output to that volume by using the corresponding dynamic link library.

OS/2 uses the volume label and serial number to ensure that the medium in the drive does not change while there are outstanding requests for input and output. Each volume has a volume label and a 32-bit volume serial number, stored in a reserved location in logical sector 0 at the time of formatting. If the volume label and serial number do not match, OS/2 signals the critical error handler to prompt the user to insert the volume that has the specified serial number and label. OS/2 maintains the connection between the medium and the volume label and serial number until all open files on the volume are closed and all search references and cache buffer references are removed. The system redetermines the type of file system and the volume label and serial number only when the medium changes.

OS/2 enables applications to:

• Determine and set the default drive using DosQueryCurrentDisk and DosSetDefaultDisk, respectively.
• Determine and set drive information using DosQueryFSInfo and DosSetFSInfo.
• Determine and set the write verification switch using DosQueryVerify and DosSetVerify. If the write verification switch is on, each time data is written to the disk, the data is verified to ensure it has been recorded correctly. These functions are provided for recording critical data.

About Directories

When an application starts, it inherits the current directory and drive from the application that starts it. An application can determine which directory and drive are current by using DosQueryCurrentDir and DosQueryCurrentDisk. An application can change the current directory and drive of the file system by using DosSetCurrentDir and DosSetDefaultDisk.

When an application creates a new file, the system adds a file entry to the specified directory. Each directory can have any number of entries, up to the physical limit of the disk. An application can create new directories and delete existing directories by using DosCreateDir and DosDeleteDir. Before a directory can be deleted, it must be empty; if there are files or directories in that directory, they must be deleted or moved. An application can delete a file by using DosDelete or move a file to another directory by using DosMove.

Creating a Subdirectory

To create a new subdirectory, an application calls DosCreateDir and specifies a directory path name. If the call is successful, a new subdirectory is created at the end of the path on the specified disk. If no path name is specified, a new subdirectory is created at the end of the current directory for the process. If any subdirectories in the path do not exist, the subdirectory is not created.

Because a subdirectory is a file object, an application also can define an extended attribute for the directory when it is created during this call. See Extended Attributes for more information on extended attributes.

Determining and Changing the Current Directory

Calling DosQueryCurrentDir returns the full path name of the current directory for the specified drive. The string does not begin with a back slash (\) and it ends with a byte containing 00H, the NULL character.

To change the current directory, call DosQueryCurrentDir with the path name of the directory you want to make the current directory.

Deleting a Directory

A subdirectory cannot be removed if it is the current subdirectory or if it contains hidden files or subdirectory entries other than the "." and ".." entries. When these requirements for removal are met, DosDeleteDir can be called with a path name to remove the subdirectory from the disk.

About Files

A file is one or more bytes of data, usually stored on a disk. While the application that creates the file determines the format of the file, the file system determines how the file is stored on the disk and what actions can be performed on it. The file system also stores information about the file in file attributes and extended attributes.

Files are accessed through the file system using file handles. File handles are returned by DosOpen when the file is opened and are used for all subsequent accesses to the file. Files can be be opened, read from, written to, closed, copied, moved, deleted, renamed, and locked. Files can be searched for based on a metacharacter template.

Each open file has a file pointer that indicates the current reading or writing location within the file. The file pointer moves automatically with each read or write operation on the file and can be moved manually by the application.

File Attributes

Each directory entry includes a set of file attributes. File attributes specify whether the directory entry is for a file, a directory, or a volume identifier. The attributes also specify if the file is read-only, hidden, archived, or a system file.

A read-only file cannot be opened for writing, nor can it be deleted. A hidden file (or directory) cannot be displayed by using an ordinary directory listing. A system file is excluded from normal directory searches. The archived attribute is for use by special purpose applications to mark a file that has been changed since the last time the file was examined.

An application can retrieve and set the file attributes by using DosQueryFileInfo and DosSetFileInfo.

File Handles

OS/2 identifies each open file by assigning it a file handle when the application opens or creates the file. The file handle is a unique 32-bit integer. The application can use the handle in functions that read from and write to the file, depending on how the file was opened. The application can continue to use the handle until the file is closed.

The default maximum number of file handles for a process is 50. An application can change this maximum by using DosSetMaxFH. When this call is made, all currently open file handles are preserved.

In the past, the maximum number of file handles was 20. If you previously had code that increased the maximum file handles from 20 to less than 50, you can now remove this code.

When an application starts, it inherits all open file handles from the process that starts it. If the system's command processor starts an application, file handles 0, 1, and 2 represent the standard input, standard output, and standard error files. The standard input file is the keyboard; the standard output and standard error files are the screen. An application can read from the standard input file and write to the standard output and standard error files immediately; it does not have to open the files first.

An application can create a duplicate file handle for an open file by using DosDupHandle. A duplicate handle is identical to the original handle. Typically, duplicate handles are used to redirect the standard input and standard output files. For example, an application can open a disk file and duplicate the disk-file handle as handle 0. Thereafter, an application reading from the standard input file (handle 0) takes data from the disk file, not from the keyboard.

When devices and pipes are accessed through the file system functions (using DosOpen, DosRead, and so on), the devices and pipes are treated as files and are identified using file handles. The standard file handles can be redirected to a device or pipe.

File Pointer

Every open file has a file pointer that specifies the next byte to be read or the location to receive the next byte that is written. When a file is first opened, the system places the file pointer at the beginning of the file. As each byte is read or written, OS/2 advances the pointer.

An application can also move the pointer by using DosSetFilePtr. When the pointer reaches the end of the file and the application attempts to read from the file, no bytes are read and no error occurs. Thus, reading 0 bytes without an error means the program has reached the end of the file.

When an application writes to a disk file, the data being written is usually collected in an internal buffer. OS/2 writes to the disk only when the amount of data equals (or is a multiple of) the sector size of the disk. If there is data in the internal buffer when the file is closed, the system automatically writes the data to the disk before closing the file. An application can also flush the buffer (that is, write the contents of the buffer to the disk) by using DosResetBuffer.

Copying Files

DosCopy is used to copy files and subdirectories. Metacharacters (global file name characters) are not allowed, so only individual files or entire subdirectories can be copied with this function. The source and target can be on different drives.

When the source specified is a subdirectory and an I/O error occurs, the file being copied from the source directory to the target directory at the time of the error will be deleted from the target directory and DosCopy will be terminated.

When a file is being copied and an I/O error occurs,

• if the source file name is that of a file to be replaced, the file is deleted from the target path.
• if the source file name is that of a file to be appended, the target file is resized to its original size.

DosCopy will copy the attributes of the source file, such as date of creation, and time of creation to the target file. Additionally, DosCopy will copy the extended attributes of the source file when creating a new subdirectory or a new file, or when replacing an existing file.

Moving Files

DosMove is used to move a file from one subdirectory to another on the same drive. In the process of moving the file, its name can be changed. Metacharacters (global file name characters) are not permitted.

Deleting Files

Calling DosDelete removes the directory entry associated with a file name. Metacharacters (global file name characters) are not permitted.

Files whose read-only attribute is set cannot be deleted.

Changing File Sizes

DosSetFileSize is used to extend or truncate the size of a file that is open for Read/Write or Write-Only access.

When a file is extended, for example to reserve disk space, the value of the additional bytes allocated by the system is undefined.

Locking and Unlocking File Regions

Because OS/2 permits more than one application to open a file and write to it, it is important that the applications not write over each other's work. An application can protect against this problem by temporarily locking a region in a file.

DosSetFileLocks provides a simple mechanism that temporarily prevents access by other processes to regions within a file. DosSetFileLocks specifies a range of bytes in the file that is locked by an application and that can be accessed only by the application locking the region. The application uses the same function to free the locked region.

Locking and unlocking regions in a file enables sharing processes to coordinate their efforts. A process can lock a region in a file so the process can read and update the file region. A sharing process that attempts to lock the region before the other process finishes its update and unlocks the region receives an error code. When a lock is unsuccessful because a lock is already in place, ERROR_LOCK_VIOLATION is returned.

A lock that extends beyond end-of-file is not considered an error. However, a locked region cannot overlap another locked region, nor can it encompass a locked region. Any such conflicting locks must be cleared before a region can be locked.

When a file handle is duplicated, the duplicate handle has access to any locked regions currently being accessed by the original handle. Although a child process created with DosExecPgm can inherit the file handles of its parent process, it does not inherit access to locked regions in effect for a file handle unless the file handle is duplicated and passed to it.

Note

File locks are intended to be in effect for only short periods of time.

When a file with locks is closed, the locks are released in no defined order.

Searching for Files

An application can use DosFindFirst, DosFindNext, and DosFindClose to search the current directory for all file names that match a given pattern.

The pattern must be an OS/2 file name and can include metacharacters (global file name characters). The wildcard characters are the question mark (?) and the asterisk (*). The question mark matches any single character; the asterisk matches any combination of characters. For example, the pattern "A*" matches the names "ABC", "A23", and "ABCD", but the pattern "A?C" matches only the name "ABC".

Determining the Maximum Path Length

An application that recognizes long file names might be run on systems with or without installable file systems. Additionally, the maximum length of a file name might vary from one installable file system to another. So that an application can properly handle this variable condition (and, for example, allocate large enough buffers to hold file names), the application should call DosQuerySysInfo to determine the maximum path length supported by the file system.

Make this call before calling file system functions that require full path names.

Specifying an Extended LIBPATH

The LIBPATH, which is set in CONFIG.SYS, specifies a search path which OS/2 uses when searching for dynamic link libraries (DLLs). The LIBPATH is set during system startup and cannot be changed dynamically.

OS/2 provides the capability of specifying extensions to the LIBPATH. An Extended LIBPATH is a path which is searched in conjunction with the system LIBPATH, but which can be changed dynamically, either by the user from the command line, or by an application.

There are two Extended LIBPATHs: BeginLIBPATH, which is searched before the system LIBPATH, and EndLIBPATH, which is searched after the system LIBPATH.

Extended LIBPATHs are ASCIIZ strings which are formatted in the same manner as the system LIBPATH, that is, they contains a list of subdirectory paths separated by semicolons. The maximum size for each Extended LIBPATH is 1024 characters.

Applications can use DosSetExtLIBPATH to set the Extended LIBPATHs. Likewise, they can use DosQueryExtLIBPATH to query the value of either of the Extended LIBPATHs. A flag parameter for the function specifies whether the BeginLIBPATH or the EndLIBPATH is being set or queried. The flag allows two values: BEGIN_LIBPATH (1) which will set or query BeginLIBPATH, or END_LIBPATH (2) which will set or query EndLIBPATH.

You can call DosSetExtLIBPATH as often as you want. The new Extended LIBPATH that you pass in will replace the current Extended LIBPATH.

You can specify the current Extended LIBPATH as part of the argument by using the % symbol before and after the Extended LIBPATH variable name, that is, as %BeginLIBPATH% or %EndLIBPATH%. For example, suppose you set BeginLIBPATH to "D:\MYDLLS", then later you want to add "D:\TOMSDLLS" before the existing BeginLIBPATH, and "D:\JOESDLLS" after the existing BeginLIBPATH (that is, you want to change BeginLIBPATH to "D:\TOMSDLLS;D:\MYDLLS;D:\JOESDLLS"). You could accomplish this by using "D:\TOMSDLLS;%BeginLIBPATH%;D:\JOESDLLS" as the argument for DosSetExtLIBPATH.

The string argument can be up to 1024 characters long. However, if the resulting Extended LIBPATH is longer than 1024 characters, the function will return an error.

Devices

OS/2 enables you to access peripheral devices using file system commands, and treat those devices as file streams of data. These devices include:

Character devices

COM, clock, console (keyboard and screen), screen, keyboard, printer, null, pointer, and mouse devices.

Standard I/O devices

Character devices automatically installed by OS/2 and recognized by the file system as the standard input, standard output, and standard error devices.

Pseudocharacter devices

An application can attach a device name to a file system and use the file system as a pseudocharacter device (also called a single-file device). Attaching a device name to a file system allows an application to open the device associated with the file system as if it were a character device (for example, a serial port) and read from and write to the device by using DosRead and DosWrite.

In addition, an application can use DosSetFilePtr and DosSetFileLocks with a pseudocharacter device. Also, pseudocharacter devices can be redirected.

A file system that can be attached to a pseudocharacter device is typically associated with a single disk file or with a special storage device, such as a tape drive. The file system establishes a connection with the device and transfers requests and data between OS/2 and the device. The user perceives this file as a device name for a nonexistent device.

This file is seen as a character device because the current drive and directory have no effect on the name. A pseudocharacter device name is an ASCII string with the name of an OS/2 file in the form:

 \DEV\DEV_NAME

The "\dev\" is a required part of the name, but there is no actual subdirectory named "\dev\". This just lets OS/2 know that it is a pseudocharacter device name.

Logical file

devices The hard disk or floppy disk drives, or the partitions on the hard disk or floppy disk drives.