Troubleshooting
Problem
Certain applications might create files with invalid names in the Integrated File System. For example, a file name containing slashes or quotes is not valid and cannot be removed by using some IBM i interfaces. When trying to rename or delete these files, the IBM i interprets the slashes and quotes as part of the file name and generates an error:
CPFA0A9 - Object not found.
There are several characters which can cause problems when they are part of the name of a link. For example:
- < (less than)
- > (greater than)
- : (colon)
- " (double quote)
- / (forward slash)
- \ (backslash)
- | (vertical bar or pipe)
- ? (question mark)
- *(asterisk)
The following query can be used in Run SQL Scripts to find links that contain any of these characters except the forward slash (which is the default path delimiter character on IBM i, so it is part of every path name). This query might take a very long time to complete:
SELECT PATH_NAME
FROM TABLE (
QSYS2.IFS_OBJECT_STATISTICS(
START_PATH_NAME => '/', OMIT_LIST => '/QSYS.LIB /QNTC /QFILESVR.400 /QOpenSys', SUBTREE_DIRECTORIES => 'YES')
)
WHERE PATH_NAME LIKE '%\%'
OR PATH_NAME LIKE '%<%'
OR PATH_NAME LIKE '%>%'
OR PATH_NAME LIKE '%|%'
OR PATH_NAME LIKE '%*%'
OR PATH_NAME LIKE '%:%'
FROM TABLE (
QSYS2.IFS_OBJECT_STATISTICS(
START_PATH_NAME => '/', OMIT_LIST => '/QSYS.LIB /QNTC /QFILESVR.400 /QOpenSys', SUBTREE_DIRECTORIES => 'YES')
)
WHERE PATH_NAME LIKE '%\%'
OR PATH_NAME LIKE '%<%'
OR PATH_NAME LIKE '%>%'
OR PATH_NAME LIKE '%|%'
OR PATH_NAME LIKE '%*%'
OR PATH_NAME LIKE '%:%'
OR PATH_NAME LIKE '%"%'
OR PATH_NAME LIKE '%?%';
OR PATH_NAME LIKE '%?%';
Note if you want to run this in interactive SQL, remove the semicolon at the end of the statement and replace 'SELECT PATH_NAME' with 'SELECT CAST(PATH_NAME AS VARCHAR(32000))' to cast the DBCLOB result column to something displayable in interactive SQL.
Diagnosing The Problem
You can find links in the root file system that contain characters that many operating systems and applications cannot handle.
Resolving The Problem
The best way to remove or access these files is to use the same application that created them.
If the original application is not available or it is not able to remove these objects, there are some other options that can be used. These options include EDTF, FTP, Qshell, Access Client Solutions (ACS) Integrated File System function.
If the original application is not available or it is not able to remove these objects, there are some other options that can be used. These options include EDTF, FTP, Qshell, Access Client Solutions (ACS) Integrated File System function.
This document provides tips on how to delete documents and directories in the Integrated File System that were created with invalid names.
For demonstration, I create an invalidly named file by using Qshell:
$
> mkdir /tmp/testdir
$
> cd /tmp/testdir
$
> touch '\testfile.txt'
$ In the WRKLNK interface, the file looks like this:
An attempt to delete it with option "4=Remove" fails with:
CPFA0A9 - Object not found. Object is /tmp/testdir/testfile.txt.
Note: The WRKLNK command is not Unicode-enabled. It cannot work with files or directories that have ANSI or Unicode characters that do not exist in the operating system CCSID.
Choose one the following methods to remove the file:
Access Client Solutions (ACS) Integrated File System function:
The ACS IFS function is able to handle object names with back-slashes. Right-click on the object to rename or delete it.
EDTF:
EDTF STMF('/tmp/testdir')
EDTF STMF('/tmp/testdir')
...will list Stream Files and Directories in the IFS directory specified.
Use option "4=Delete File" to delete files or option "9=Recursive Delete" to delete a directory and its contents.
Use option "4=Delete File" to delete files or option "9=Recursive Delete" to delete a directory and its contents.
FTP:
FTP can be used to rename or delete files and directories with invalid names that contain only standard ANSI characters. For example, FTP can be used to delete or rename files with names containing a backslash ('\'), but cannot handle names with embedded nulls or Unicode characters.
FTP Commands: REN (rename) and DEL (delete) for files, RMDIR (remove directory) for directories.
Note: Directories must be empty before they can be removed with the RMDIR command.
Note: An FTP session can be started either from the IBM i Command Line (on the same IBM i system or on a different IBM i system) or it can be started from a PC DOS Command Prompt.
| 1. | To start an FTP session to the IBM i system, on the operating system command line type the following command: FTP <systemname> Press the Enter key. You are prompted to sign on and type your password. |
| 2. | Once signed on, change the naming format from operating system to UNIX by issuing the NAMEFMT 1 command (quote site namefmt 1, and press the Enter key). The FTP session will respond with 250 Now using naming format "1". |
| 3. | To change to the directory containing the file in question, type the following: cd /tmp/testdir Press the Enter key. Response from the IBM i system should be 250 "/tmp/testdir" is current directory. |
| 4. | Type the following: DEL \testfile.txt Press <Enter>. The response is 250 Deleted file /tmp/testdir/\testfile.txt. This also works with the RENAME command. |
Note: Due to UNIX naming format, file names are case-sensitive.
The same steps may be used for removing directories with invalid names (such as \MYDIR). To do so, follow the steps above substituting the RMDIR command in place of the DEL command used in the example. If the directory which has the invalid character in the name contains other DIRs or STMFs, you will probably need to do a REN on the directory with the invalid character in the name and give it a valid name. At this point, you can use normal methods to delete the contents of the directory and remove it as you normally would.
Qshell:
Qshell can be used to remove some invalid file names, including those that contain a backslash as part of the name. To remove a name with a backslash, escape the character with an additional backslash or place quotes around the name.
Example: To remove "myfi\le" use 'rm myfil\\le' or 'rm "myfi\le"'
To use Qshell to remove the files, do the following:
| 1. | From an operating system command line, type the following: STRQSH |
| 2. | To change directory to the directory containing the invalid file name, type the following: cd mydir |
| 3. | To remove the file, type the following: rm "invalid file name" |
| 4. | Press F3 to end Qshell. |
QP0FPTOS API:
Functions have been added to the "Perform Miscellaneous File System Functions (QP0FPTOS)" API that enable users to rename objects with unusable names. Below are steps to investigate potentially invalid object names and correct them:
1) CALL QP0FPTOS PARM(*DUMPDIR '/path/to/directory')
CALL QP0FPTOS PARM(*DUMPDIR '/path/to/directory' *PRBONLY)
The '/path/to/directory' must be specified in the current job CCSID. These invocations will dump the contents of the specified directory to a spooled file. The spooled file will contain each link name in the current job CCSID and a hexadecimal representation of the link name in CCSID 1200 (UTF-16). Certain entries may also indicate that a "problem" exists for the link name. A link name contains a "problem" if it contains any of the following:
- Characters that cannot be converted to the current job CCSID
- Slash (/)
- Backslash (\)
- Asterisk (*)
- Question mark (?)
- Single-quote (')
- Double-quote (")
- Tilde (~)
- Colon (:)
- Space ( )
If the optional third parameter is omitted, all entries in the directory will be dumped to the spool file. Entries that contain problems can be found by searching for the string "PROBLEM:". If *PRBONLY is specified as the third parameter, only entries containing problem characters will be dumped to the spool file.
2) CALL QP0FPTOS PARM(*RENAME 'old-hex-name' 'new-name')
This invocation will rename a link in the current working directory. The 'old-hex-name' is the hexadecimal representation of the name in CCSID 1200 (UTF-16) that is obtained from the *DUMPDIR output. In the *DUMPDIR output, this representation is titled 'UNICODE' rather than 'HEX'.
The 'new-name' is a name specified in the current job CCSID. For example, if directory '/A/B' contained a link name with slashes, '/C/D', the following commands could be used to rename the link to 'NEWNAME':
CHGCURDIR DIR('/A/B')
CALL QP0FPTOS PARM(*RENAME '002F0043002F0044' 'NEWNAME')
3) CALL QP0FPTOS PARM(*RENAMEPRB '/path/to/directory')
This invocation will rename all entries in the specified directory that contain the slash (/) character. All of the slash characters in the names will be changed to hyphens (-). For example, if directory '/A/B' contained several link names with slashes ('/C/D', '/E', '/F/G/H'), the following command could be used:
CALL QP0FPTOS PARM(*RENAMEPRB '/A/B')
When the command completed, the problem names would be '-C-D', '-E', and '-F-G-H'. These names can then be easily removed or further renamed through other normal interfaces. The command generates a spooled file where the success or failure of file system operations is reported.
1) CALL QP0FPTOS PARM(*DUMPDIR '/path/to/directory')
CALL QP0FPTOS PARM(*DUMPDIR '/path/to/directory' *PRBONLY)
The '/path/to/directory' must be specified in the current job CCSID. These invocations will dump the contents of the specified directory to a spooled file. The spooled file will contain each link name in the current job CCSID and a hexadecimal representation of the link name in CCSID 1200 (UTF-16). Certain entries may also indicate that a "problem" exists for the link name. A link name contains a "problem" if it contains any of the following:
- Characters that cannot be converted to the current job CCSID
- Slash (/)
- Backslash (\)
- Asterisk (*)
- Question mark (?)
- Single-quote (')
- Double-quote (")
- Tilde (~)
- Colon (:)
- Space ( )
If the optional third parameter is omitted, all entries in the directory will be dumped to the spool file. Entries that contain problems can be found by searching for the string "PROBLEM:". If *PRBONLY is specified as the third parameter, only entries containing problem characters will be dumped to the spool file.
2) CALL QP0FPTOS PARM(*RENAME 'old-hex-name' 'new-name')
This invocation will rename a link in the current working directory. The 'old-hex-name' is the hexadecimal representation of the name in CCSID 1200 (UTF-16) that is obtained from the *DUMPDIR output. In the *DUMPDIR output, this representation is titled 'UNICODE' rather than 'HEX'.
The 'new-name' is a name specified in the current job CCSID. For example, if directory '/A/B' contained a link name with slashes, '/C/D', the following commands could be used to rename the link to 'NEWNAME':
CHGCURDIR DIR('/A/B')
CALL QP0FPTOS PARM(*RENAME '002F0043002F0044' 'NEWNAME')
3) CALL QP0FPTOS PARM(*RENAMEPRB '/path/to/directory')
This invocation will rename all entries in the specified directory that contain the slash (/) character. All of the slash characters in the names will be changed to hyphens (-). For example, if directory '/A/B' contained several link names with slashes ('/C/D', '/E', '/F/G/H'), the following command could be used:
CALL QP0FPTOS PARM(*RENAMEPRB '/A/B')
When the command completed, the problem names would be '-C-D', '-E', and '-F-G-H'. These names can then be easily removed or further renamed through other normal interfaces. The command generates a spooled file where the success or failure of file system operations is reported.
Related Information
[{"Line of Business":{"code":"LOB68","label":"Power HW"},"Business Unit":{"code":"BU070","label":"IBM Infrastructure"},"Product":{"code":"SWG60","label":"IBM i"},"ARM Category":[{"code":"","label":""}],"Platform":[{"code":"PF012","label":"IBM i"}],"Version":"Version Independent"}]
Historical Number
15234725
Was this topic helpful?
Document Information
Modified date:
23 November 2025
UID
nas8N1019639