| 1 | File system name | Input | Char(10) |
| 2 | Version | Input | Char(6) |
| 3 | Registration information | Input | Char(6) |
| 4 | List of qualified exit program names | Input | Array of Char(20) |
| 5 | File system description | Input | Char(50) |
| 6 | Error code | I/O | Char(*) |
The Register File System (QHFRGFS) API adds a new file system to IBM® i HFS support and records the APIs that it supports so they are accessible to user applications. You must register a file system before users can access it with the HFS APIs.
The name of the file system being registered. The name can be 1-10 characters long. The first character must be a capital letter other than Q (Q is reserved for IBM-supplied file systems). The remaining characters can be any combination of capital letters (A-Z) and numbers (0-9). The name cannot contain lowercase letters (a-z), special characters, or quotation marks.
The file system name determines where calls to HFS APIs are sent. For example, a call that contains a path name beginning with NEWS, such as /NEWS/DIRA/FILE1, is sent to the NEWS file system.
Note: IBM preregisters the document library services (DLS) file system, QDLS. You cannot register or deregister it yourself.
The version indicates the level of HFS the file system chooses to use. Use the format VxRxMx where x stands for the version, release, and modification levels, respectively. The values indicate the different versions in which HFS enabled new support that the file systems can use. The valid versions are:
| V2R1M0 | Version 2 Release 1 Modification Level 0 |
| V2R3M0 | Version 2 Release 3 Modification Level 0 |
Additional information describing the actions to take during registration.
The characters in this parameter are:
| 1 | Whether to register a file system that is already registered. This character lets you reregister a changed file system without deregistering it first. Valid values are:
|
||||
| 2 | Which type of cross-file-system copy or move operation to perform. This character is called the copy or move indicator. HFS support checks its value only when an application specifies different source and target file systems in calls to the Copy Stream File (QHFCPYSF) or Move Stream File (QHFMOVSF) API.
This character has no effect on operations within the same file system. For cross-file-system operations, it tells the QHFCPYSF and QHFMOVSF APIs whether to call the source file system's copy and move exit programs to see if they can perform the operations. If they cannot, the API tries the exit programs for the target file system. If the source file system and the target file system cannot perform the operations, the API calls a series of other exit programs (such as those that open, read from, and write to stream files) to perform the operation. The last method is the least efficient. For a detailed explanation of cross-file-system copy and move processing, see Exit Program for Copy Stream File (QHFCPYSF) API. Valid values for this character are:
|
||||
| 3-6 | Reserved. These characters must be blank. |
An array listing the exit programs that perform the work for the HFS APIs. (An array is a list of items in a specific sequence.) The first 10 characters of each array element contain the exit program name, and the second 10 characters of each array element contain the name of the library in which the exit program resides.
If the file system being registered does not support a particular API and thus there is no exit program, specify *NONE for the program name and blanks for the library name. If an application calls an API for which there is no exit program, the API issues a message stating that the file system does not support that operation.
If the file system is written in a language that supports a variable number of input parameters, you can specify the same exit program for more than one function.
The sequence of array elements indicates the operation or API supported by the exit program specified there. For example, the exit program you specify in position 3 is called when an application calls the QHFCRTDR API. The sequence is as follows:
A brief description of the file system. This description is returned when applications use the List Registered File Systems (QHFLSTFS) or the Display Hierarchical File Systems (DSPHFS) command.
The structure in which to return error information. For the format of the structure, see Error code parameter.
The exit program that performs the Start Job Session operation controls user authority and locking for the file system as a whole. The Start Job Session exit program is called the first time a job uses a given file system. At that time, the system checks the job's authority to the Start Job Session exit program. Authority for this program gives the user authority to use all other valid exit programs for the file system. IBM i HFS support also obtains a shared read (*SHRRD) lock on the exit program and maintains it until the end of the job so that other jobs cannot deregister the file system while it is in use. For details about this exit program, see Start Job Session Exit Program.
HFS support maintains system pointers to the file system's exit programs. HFS support uses these pointers when your exit programs are called. If a system pointer to any exit program becomes inaccurate, as it does when the program is recompiled, HFS support updates the pointer. If the system pointer cannot be resolved to the object, an error is returned.
You can change and recompile any exit program without having to reregister your file system. You should remember that if others are using the file system, they will have a *SHRRD lock on the Start Job Session exit program. This may prevent recompilation of that program. You should only recompile the Start Job Session program when no one else is using the file system. You can use the Work with Object Locks (WRKOBJLCK) command on the Start Job Session program to see if any other job is using the file system.
| Message ID | Error Message Text |
|---|---|
| CPF1F41 E | Severe error occurred while addressing parameter list. |
| CPF1F52 E | Error code not valid. |
| CPF1F74 E | Not authorized to object. |
| CPF1F81 E | API specific error occurred. |
| CPF1F85 E | Not authorized to file system &1. |
| CPF1F9A E | Exit program list not valid. |
| CPF1F9B E | Reregister or deregister file system failed. |
| CPF1F91 E | File system name not valid. |
| CPF1F93 E | File system &1 already registered. |
| CPF1F94 E | Exit program &2 not found. |
| CPF1F95 E | Required exit program not specified. |
| CPF1F96 E | Version level &2 not valid. |
| CPF1F97 E | File system &1 in use. |
| CPF1F98 E | Registration or deregistration cannot be done now. |
| CPF1F99 E | Register information value not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
[ Back to top | Hierarchical File System APIs | APIs by category ]