Exit Program for Copy Stream File (QHFCPYSF) API

Required Parameter Group:

1	Operation (CPYSF)	Input	Char(5)
2	File system job handle	Input	Char(16)
3	Reserved	Input	Char(20)
4	Source file path name	Input	Char(*)
5	Source file path name length	Input	Binary(4)
6	Copy information	Input	Char(6)
7	Target file path name	Input	Char(*)
8	Target file path name length	Input	Binary(4)
9	File system names	Input	Char(20)

Before applications can use the Copy Stream File (QHFCPYSF) API with your file system, you must:

Write an exit program that performs the copy stream file operation on behalf of the API. For a detailed description of the API and its calling parameters, see Copy Stream File (QHFCPYSF) API.
Give the exit program's name when you register the file system with the Register File System (QHFRGFS) API. In the registration-information parameter of the QHFRGFS API, indicate whether this exit program can be used for copy operations involving two different file systems.

After that, when an application calls the QHFCPYSF API, the API calls your exit program and passes it the parameters specified by the application. Your exit program performs the work and returns any data to the API. The API passes the data back to the calling application.

Authorities and Locks

None.

Required Parameter Group

The API passes this information to your exit program:

Operation (CPYSF): INPUT; CHAR(5)
The abbreviation for the operation being performed (CPYSF).
File system job handle: INPUT; CHAR(16)
The work area or job identifier for use by the file system.
Reserved: INPUT; CHAR(20)
Reserved for future use. This parameter is set to blanks.

Except as noted, the following parameters are the same as the parameters for the API.

Source file path name: INPUT; CHAR(*)
The API removes the file system name before passing the path name to the exit program.
Source file path name length: INPUT; BINARY(4)
Copy information: INPUT; CHAR(6)
Target file path name: INPUT; CHAR(*)
The API removes the file system name before passing the path name to the exit program.
Target file path name length: INPUT; BINARY(4)
File system names: INPUT; CHAR(20)
This is not an API parameter. The API derives this information from its source and target file path name parameters. The first 10 characters contain the name of the source file system, and the second 10 characters contain the name of the target file system.

API Functions

The QHFCPYSF API performs the standard functions described in Standard HFS API Functions.

When the source and target file systems are different, the API performs additional functions so that the file is copied by the most efficient means available. The following diagram outlines the processing steps. The steps are the same for copy and move operations. They are described in detail after the diagram.

After determining that the file systems differ, the API tries to perform the copy operation in several different ways. If a method fails, the API proceeds to the next method. The possible methods are to call the following exit programs in the sequence listed:

The source file system's Copy Stream File exit program
The target file system's Copy Stream File exit program
A series of other exit programs, such as those for opening, reading from, and writing to stream files, in the source and target file systems

The following paragraphs describe each method in detail.

The source file system's Copy Stream File exit program:
First, the API checks the information provided when the source file system was registered with the Register File System (QHFRGFS) API. The copy or move indicator is character 2 of the registration-information parameter described in the Register File System (QHFRGFS) API.

If the value of the source file system's copy or move indicator is 0 for no (indicating that this file system has no cross-file-system capability), the API proceeds to try the target file system.

If the value of the source file system's copy or move indicator is 1 for yes (indicating that this file system has some cross-file-system capability), the API calls the file system's Copy Stream File exit program.

If the exit program encounters an error in communicating with the source file system--for example, the exit program can work with some other file systems but not with this one--it returns message CPF1F88 to the API, which proceeds to the target file system.

If the exit program completes the copy or encounters any other type of error--for example, the exit program cannot find the file to be copied--it returns control to the API. The API resends any errors received from the exit program to the application and then returns control to the application.
The target file system's Copy Stream File exit program:
The API follows the same procedure as for the source file system, checking the copy or move indicator and then trying the target file system's Copy Stream File exit program. If the copy or move indicator is 0 for no or if the exit program returns message CPF1F88, the API proceeds to try the other exit programs.
A series of other exit programs in the source and target file systems:
If the source and target file systems' Copy Stream File exit programs have no cross-file-system capability at all, or if they have no such capability with respect to each other, the API might be able to perform a less efficient form of copy operation. If the following exit programs exist in the source and target file systems, the API tries to perform the copy operation. If any of these exit programs do not exist, the API returns message CPF1F82 and returns control to the application without performing the copy operation.

The required exit programs in the source file system are:
- Open Stream File (for the QHFOPNSF API)
- Read from Stream File (for the QHFRDSF API)
- Close Stream File (for the QHFCLOSF API)
- Retrieve Stream File Attributes (for the QHFRTVAT API)
- Delete Stream File (for the QHFDLTSF API). This exit program is required for both copy and move operations. However, it is used only during move operations.
The required exit programs in the target file system are:
- Open Stream File (for the QHFOPNSF API)
- Write to Stream File (for the QHFWRTSF API)
- Change File Pointer (for the QHFCHGFP API). This exit program is required for both copy and move operations. However, it is used only during copy operations in which the source file is being added to an existing target file.
- Close Stream File (for the QHFCLOSF API)
- Change Stream File Attributes (for the QHFCHGAT API)
- Delete Stream File (for the QHFDLTSF API)
The API uses the exit programs to perform their ordinary functions:
- The source file system's Open Stream File exit program opens the source file, and the target file system's Open Stream File exit program opens the target file.
- The source file system's Read from Stream File exit program and the target file system's Write to Stream File exit program repeatedly read from the source file and write to the target file until all the data has been copied from one to the other.
- The source file system's Retrieve Stream File Attributes exit program retrieves the attributes stored with the source file, and the target file system's Change Stream File Attributes exit program writes the attributes to the target file.
- The source and target file systems' Close Stream File exit programs close the source and target files.
- The source file system's Delete Stream File exit program deletes the source file after a successful move operation.
  The target file system's Delete Stream File exit program is used during unsuccessful copy and move operations. If errors cause the failure of the operation as a whole, the exit program deletes any incomplete target files created during the operation. Target files that existed before the operation began are not deleted but might be partly changed.

Exit Program Requirements

You must create an exit program that performs the standard functions described in Standard HFS Exit Program Requirements and these additional functions:

If the source and target paths to the files are the same, verifies that the source and target file names are different.
If the source and target file systems are different, takes these actions:
- Determines whether it is the source or the target file system by examining the exit program's file-system-names parameter.
- Performs the copy operation or returns control to the application or API as described in API Functions.
  When the exit program has some cross-file-system capability but cannot complete this specific copy operation, it should return message CPF1F88 to the API. This tells the API that it might still be possible to perform the copy operation by other means. If unavoidable errors occur--for example, if the file being copied does not exist--then the exit program should return those errors to the API.
Whether or not the QHFCPYSF API calls this exit program for cross-file-system operations depends on information provided when this file system was registered. If the second character of the registration-information parameter of the Register File System (QHFRGFS) API has a value of 1 (yes), the QHFCPYSF API calls this exit program. If that character has a value of 0 (no), the QHFCPYSF API does not call this exit program for cross-file-system operations; instead, the API bypasses this exit program and proceeds to try the next available method of copying files.
If the operation is replacing or adding a copy to a file, verifies that the target file exists.
Ensures that the user has the required authority to both the source and target paths and files.
Ensures that the user has read access to the source file and write access to the target file.

Error Messages for Exit Program Use

This section lists the messages that the exit program can return to the API.

Message ID	Error Message Text
CPF1F01 E	Directory name not valid.
CPF1F02 E	Directory not found.
CPF1F06 E	Directory in use.
CPF1F07 E	Authority not sufficient to access directory.
CPF1F08 E	Damaged directory.
CPF1F21 E	File name not valid.
CPF1F22 E	File not found.
CPF1F23 E	New file name same as old file name.
CPF1F24 E	File name already exists.
CPF1F26 E	File in use.
CPF1F27 E	Authority not sufficient to access file.
CPF1F28 E	Damaged file.
CPF1F29 E	Use of reserved file name not allowed.
CPF1F41 E	Severe error occurred while addressing parameter list.
CPF1F48 E	Path name not valid.
CPF1F51 E	Copy information value not valid.
CPF1F61 E	No free space available on media.
CPF1F62 E	Requested function failed.
CPF1F63 E	Media is write protected.
CPF1F66 E	Storage needed exceeds maximum limit for user profile &1.
CPF1F71 E	Exception specific to file system occurred.
CPF1F73 E	Not authorized to use command.
CPF1F74 E	Not authorized to object.
CPF1F75 E	Error occurred during start-job-session function.
CPF1F77 E	Severe parameter error occurred on call to file system.
CPF1F88 E	Unable to complete copy or move operation.

Note: You can use message CPF1F88 only when trying to perform cross-file-system copy operations. If you use it when copying files within a single file system, an Internal file system error message is returned to the application. You can use the exit program's file-system-names parameter to determine whether the move is across file systems.

Because this message does not always indicate an error, the application calling the QHFCPYSF API does not receive it. It is used only to communicate between the file system's exit program and the API.

Exit Program Introduced: V2R1

[ Back to top | Hierarchical File System APIs | APIs by category ]