File Open Exit Messages
The file open exit has four types of messages:
- FILE_OPEN_OUTPUT_MSG
- FILE_OPEN_OUTPUT_REPLY_MSG
- FILE_OPEN_INPUT_MSG
- FILE_OPEN_INPUT_REPLY_MSG
The file open exit has the following limitations:
- The oflag parameter passed to the user exit is already calculated based on the file disposition, as explicitly specified on the copy statement or using the default value. If the user exit changes the oflag to truncate and the original disposition is mod meaning the copy will append to the end of file if the file already exists, then the user exit causes the Process to behave differently from how the Process language is documented.
- If the oflag specifies opening a file with write access and the user exit changes access to read-only, IBM® Connect:Direct® will fail when it attempts to write to a read-only file.
- The upload and download parameters that restrict directory access are not enforced by Connect:Direct for UNIX when a file open exit is in use. These restrictions are passed into the file open exit and any enforcement action is the responsibility of the file open exit coder.
FILE_OPEN_OUTPUT_MSG
During the copy statement process, IBM Connect:Direct sends a FILE_OPEN_OUTPUT_MSG to the user exit program to open the destination file. The FILE_OPEN_OUTPUT_MSG contains:
- The open function oflag parameter (for example, O_CREAT|O_RDWR|O_TRUNC)
- The open function mode parameter, which controls file permissions
- UNIX user ID that will own the file
- UNIX group ID that will own the file
- UNIX user name
- A copy of the IBM Connect:Direct copy control block
- A copy of the IBM Connect:Direct parsed sysopts structure (the copy control block contains the actual raw version from the process)
FILE_OPEN_OUTPUT_REPLY_MSG
The user exit program sends a reply message to the IBM Connect:Direct FILE_OPEN_OUTPUT_MSG. The FILE_OPEN_OUTPUT_REPLY_MSG contains:
- Status value of zero for successful or non zero for failure
- Status text message (if status value is failure, status text message is included in the error message)
- Pipe pid (for pipe I/O, the UNIX process ID of the shell process that is performing the shell command for pipe I/O)
- Actual file name opened (to be used in statistics log messages)
If the status value is zero for successful, the user exit program must immediately call send_exit_file() or send_exit_file_c() to send the file descriptor of the opened file to IBM Connect:Direct.
FILE_OPEN_INPUT_MSG
During the copy statement Process, IBM Connect:Direct sends a FILE_OPEN_INPUT_MSG to the user exit program to open the source file. The FILE_OPEN_INPUT_MSG contains:
- The open function oflag parameter (for example, O_RDONLY)
- The open function mode parameter, which controls file permissions
- UNIX user ID that will own the file
- UNIX group ID that will own the file
- UNIX user name
- A copy of the IBM Connect:Direct copy control block
- A copy of the IBM Connect:Direct parsed sysopts structure (the copy control block contains the actual raw version from the Process)
FILE_OPEN_INPUT_REPLY_MSG
This message type is used when the user exit program sends a reply message to the IBM Connect:Direct FILE_OPEN_INPUT_MSG. The FILE_OPEN_INPUT_REPLY_MSG contains:
- Status value of zero for success or non zero for failure
- Status text message (if status value is failure, status text message is included in the error message)
- Pipe pid (for pipe I/O, the UNIX process ID of the shell process that is performing the shell command for pipe I/O)
- Actual file name opened (used in statistics log messages)