Standard HFS API and Exit Program Functions

The HFS APIs and the file system's exit programs share the responsibility for validating input data, performing the functions requested by the application, reporting errors, and so on. The two sections that follow describe the standard functions that the HFS APIs perform for you and the standard functions that your exit programs must perform. A few APIs perform additional functions, and a few exit programs have additional requirements; these additions are listed at the end of each exit program description.

Standard HFS API Functions

This section describes the functions that the HFS APIs and HFS support perform for your file system. When an application calls an HFS API, it appears to the application that the HFS API performs all the resulting functions. In reality, the API and HFS support perform only some of the functions. The file system exit program performs the rest.

Use this information to plan and create exit programs to support the HFS APIs in new file systems. You do not need this information to use the HFS APIs in your applications.

In general, every HFS API performs these functions for your file system:

• Automatically calls the file system's Start Job Session exit program the first time a job refers to the file system in a call to an HFS API. For a detailed explanation, see Start Job Session Exit Program.
  
  
• Processes the path name parameter as follows:
  • Extracts the file system name from the path name parameter.
  • Verifies that the file system is registered for use with the HFS APIs.
  • Passes the part of the path name that follows the file system name to the file system. For example, if the path name received from the application is /QDLS/A/B/C, then /A/B/C is passed to file system QDLS.

    There is one exception to this: The Open Directory (QHFOPNDR) API allows jobs to open the directory representing the file system itself. In that case, the path name consists of a slash and a single element, such as /QDLS, and the API passes just the slash (/) to the file system.

  • Recomputes the length of the path name by subtracting the length of the extracted file system name, and passes the new length to the file system.
  • Verifies that there is at least one valid byte (the leading /) in the rest of the path name parameter.
  
  
• Verifies that a directory or file handle passed from the application to the API is valid, and looks up the corresponding directory or file handle to pass from the API to the file system.
  
  
• Verifies that API parameters contain allowable values, and that reserved portions are set to blanks. API parameters include all fixed-length character fields like the open information parameter of the Open Stream File (QHFOPNSF) API.
  
  
• Verifies that length parameters contain allowable values. These length parameters are verified:
  
  
  • Length of attribute selection table
  • Length of attribute information table
  • Length of data buffer to read directory entries into
• Verifies that numeric or counting parameters contain a valid value. These parameters are verified:
  
  
  • Number of directory entries to read
  • Number of bytes to read
  • Number of bytes to write
  
  
• Calls the appropriate file system exit program to perform the operation.
  
  
• Monitors for valid exceptions from the file system, and either returns these to the application or maps them into an error code, as the application requests in the API's error code parameter.
  
  
• Signals successful completion of the operation to the application by not returning any errors.
  
  
• Returns control to the application.

Standard HFS Exit Program Requirements

In general, every exit program you provide to support an HFS API must perform these functions:

• Verifies that the application has authority to perform the request ed operation on the specified objects.
  
  
• Verifies that parameter values meet the file system's criteria.
  
  
• Verifies that directories and files named in the path name parameter either exist in the file system or, during operations like create and rename, that new names conform to the file system's naming conventions.

  The path name that the API passes to the file system does not include the file system's name but only the rest of the path name. If an application calls the Open Directory (QHFOPNDR) API and passes a path name specifying only the directory consisting of the file system, such as /QDLS, the API passes only the slash (/) to the file system.

• Maintains API INPUT parameters as is, without changing their contents. If the file system must change these parameters, it must move them to another storage location. INPUT parameters must have the same value on entry to the file system exit program as on exit from the exit program. The file system can change OUTPUT parameters when the requested operation succeeds.
  
  
• Accepts attributes in the attribute selection and information tables used by HFS support, validates the data contained in the tables, and returns the appropriate data in the appropriate format.

  HFS support uses two common formats for passing attribute information between the application and the file system. These formats are described in AFS Attribute Selection Table and HFS Attribute Information Table.

• Performs the requested operation and returns any requested status information or data to the API.
  
  
• If the operation does not succeed, returns an exception describing the error to the API.

  The file system should return only the exceptions defined for the API because HFS support monitors only for those messages. If the file system sends any other message, the message Internal file system error occurred is returned to the application.

  If the file system needs to send its own messages, it can use the message Exception specific to file system occurred defined for each API. The file system's message ID is sent as insert data.