Start of change

IFS_RENAME scalar function

Edit online

The IFS_RENAME scalar function renames either a file or a directory in the Integrated File System.

The function requires that Option 13 (System Openness Includes) of the IBM i operating system is installed.

This function uses the Qp0lRenameUnlink()--Rename File or Directory, Unlink "new" If It Exists and Qp0lRenameKeep()--Rename File or Directory, Keep "new" If It Exists APIs to rename the object. Refer to the APIs for more detailed information.

Authorization: See Note below.

Read syntax diagramSkip visual syntax diagram IFS_RENAME ( FROM_OBJECT =>  from-object ,TO_OBJECT => to-object,REPLACE => replace )
The schema is SYSTOOLS.
from-object
A character string containing the path of the file or directory to be renamed.
to-object
A character string containing the new path name for the file or directory. If to-object exists, from-object and to-object must both be files or must both be directories.
replace
A character string that indicates whether an existing file or directory is replaced.
NO
An existing file or directory will not be replaced. If it already exists, the rename request will fail. This is the default.
YES
An existing file or directory will be replaced.
When replacing a directory, the replaced directory must be empty.
The result of the function is an integer. If the replace is successful, the function returns a value of 0. If the replace returns an error, the function returns the errno value from the API.

Note

This function is provided in the SYSTOOLS schema as an example of how to embed a C language interface in an SQL scalar function. Similar to other Db2® for i provided tools within SYSTOOLS, the SQL source can be extracted and used as a model for building similar helper functions, or to create a customized version within a user-specified schema.

Services provided in SYSTOOLS have authorization requirements that are determined by the interfaces used to implement the service. To understand the authority requirements, extract the SQL for the service and examine the implementation.

Example

Rename /usr/resultfile.txt to /usr/resultfileyymmdd.txt, where yymmdd is today's date.

VALUES SYSTOOLS.IFS_RENAME(
                           FROM_OBJECT => '/usr/resultfile.txt', 
                           TO_OBJECT   => '/usr/resultfile' concat 
                                          varchar_format(current date, 'YYMMDD') concat 
                                          '.txt',
                           REPLACE     => 'NO'
                           );
End of change