Register File System (QHFRGFS) API

The Register File System (QHFRGFS) API adds a new file system to i5/OS 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.

Authorities and Locks

Exit Program Authority

*USE or higher for all exit programs being registered.

File System Authority

For information about users' authority to use the file systems you register, see User Authorizations and Locks for File System Functions.

Required Parameter Group

File system name

INPUT; CHAR(10)

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.

Version

INPUT; CHAR(6)

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

Registration information

INPUT; CHAR(6)

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: 0 Do not reregister the file system. 1 Reregister the file system.
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: 0 Do not call this file system's Copy Stream File or Move Stream File exit program when performing cross-file-system operations. The copy and move exit programs for this file system cannot communicate directly with any other file system, so the APIs should not waste time trying them. 1 Call this file system's Copy Stream File or Move Stream File exit program when performing cross-file-system operations. This file system's copy and move exit programs might be able to perform cross-file-system operations in some cases, so the APIs should try them before trying the less efficient copy and move method.
3-6	Reserved. These characters must be blank.

List of qualified exit program names

INPUT; ARRAY OF CHAR(20)

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:

1. Start Job Session Operation (required)
   
   
2. End Job Session Operation (required)
   
   
3. Create Directory (for the QHFCRTDR API)
   
   
4. Open Directory (for the QHFOPNDR API)
   
   
5. Read Directory Entries (for the QHFRDDR API)
   
   
6. Close Directory (for the QHFCLODR API; required if an Open Directory exit program is specified)
   
   
7. Retrieve Directory Entry Attributes (for the QHFRTVAT API)
   
   
8. Change Directory Entry Attributes (for the QHFCHGAT API)
   
   
9. Delete Directory (for the QHFDLTDR API)
   
   
10. Rename Directory (for the QHFRNMDR API)
    
    
11. Open Stream File (for the QHFOPNSF API)
    
    
12. Read from Stream File (for the QHFRDSF API)
    
    
13. Write to Stream File (for the QHFWRTSF API)
    
    
14. Lock and Unlock Range in Stream File (for the QHFLULSF API)
    
    
15. Change File Pointer (for the QHFCHGFP API)
    
    
16. Force Buffered Data (for the QHFFRCSF API)
    
    
17. Get Stream File Size (for the QHFGETSZ API)
    
    
18. Set Stream File Size (for the QHFSETSZ API)
    
    
19. Close Stream File (for the QHFCLOSF API; required if an Open Stream File exit program is specified)
    
    
20. Copy Stream File (for the QHFCPYSF API)
    
    
21. Delete Stream File (for the QHFDLTSF API)
    
    
22. Move Stream File (for the QHFMOVSF API)
    
    
23. Rename Stream File (for the QHFRNMSF API)
    
    
24. Control File System (for the QHFCTLFS API)
    
    

File system description

INPUT; CHAR(50)

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.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

User Authorizations and Locks for File System Functions

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. i5/OS 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.

Error Messages