Back to Contents

File Management Class

Summary:

• Basics
• Syntax
• Methods
• Examples
  • Example 1: Extracting the parts of a file name
  • Example 2: Browsing directories

See also: Built-in Functions

Basics

The Path class provides functions to manipulate files and directories on the machine where the BDL program executes.

This API is provided as a Dynamic C Extension library; it is part of the standard package.

To use this extension, you must import the os package in your program:

IMPORT os

Note that in order to manipulate files, this API give you access to low-level system functions. Pay attention to operating system specific conventions like path separators. Some functions are OS specific, like rwx() which works only on UNIX systems.

Syntax

The Path class provides an interface to manipulate files and directories.

Syntax:

Notes:

1. This class does not have to be instantiated; it provides class methods for the current program.

Methods:

os.Path.separator

Purpose:

Returns the character used to separate path segments.

Syntax:

Notes:

1. separator contains the separator.
2. On Unix, the separator is '/'
3. On Windows, the separator is '\'

os.Path.pathseparator

Purpose:

Returns the character used in environment variables to separate path elements.

Syntax:

Notes:

1. separator contains the path separator.
2. On Unix, the separator is ':'
3. On Windows, the separator is ';'

Usage:

You typically use this method to build a path from two components.

os.Path.basename

Purpose:

This method returns the last element of a path.

Syntax:

Notes:

1. filename is the name of the file.
2. basename is the last element of the path.

Usage:

This method extracts the last component of a path. For example, if you pass "/root/dir1/file.ext" as the parameter, it will return "file.ext".

See Example 1 for more examples.

os.Path.dirname

Purpose:

Returns all components of a path excluding the last one.

Syntax:

Notes:

1. filename is the name of the file.
2. dirname contains all the elements of the path excluding the last one.

Usage:

This method removes the last component of a path. For example, if you pass "/root/dir1/file.ext" as the parameter, it will return "/root/dir1".

See Example 1 for more examples.

os.Path.rootname

Purpose:

Returns the file path without the file extension of the last element of the file path.

Syntax:

Notes:

1. filename is the file path.
2. rootname contains the file path without the file extension of the last element.

Usage:

This method removes the file extension from the path. For example, if you pass "/root/dir1/file.ext" as the parameter it will return "/root/dir1/file".

See Example 1 for more examples.

os.Path.join

Purpose:

Joins two path segments adding the platform-dependent separator.

Syntax:

Notes:

1. begin is the beginning path segment.
2. end is the ending path segment.
3. newpath contains the joined path segments.

Usage:

You typically use this method to construct a path with no system-specific code to use the correct path separator:

01   LET path = os.Path.join(os.Path.homedir(), name)

This method returns the ending path segment if it is an absolute path.

os.Path.pathtype

Purpose:

Checks if a path is a relative path or an absolute path.

Syntax:

Notes:

1. path is the path to check.
2. pathtype can be "absolute" if the path is an absolute path, or "relative" if the path is a relative path.

os.Path.exists

Purpose:

Checks if a file exists.

Syntax:

Notes:

1. fname is the file name.
2. result is TRUE if the file exists, FALSE otherwise.

os.Path.extension

Purpose:

Returns the file extension.

Syntax:

Notes:

1. fname is the file name.
2. extension is the string following the last dot found in fname.
3. If fname does not have an extension, the function returns NULL.

os.Path.readable

Purpose:

Checks if a file is readable.

Syntax:

Notes:

1. fname is the file name.
2. result is TRUE if the file is readable, FALSE otherwise.

os.Path.writable

Purpose:

Checks if a file is writable.

Syntax:

Notes:

1. fname is the file name.
2. result is TRUE if the file is writable, FALSE otherwise.

os.Path.executable

Purpose:

Checks if a file is executable.

Syntax:

Notes:

1. fname is the file name.
2. result is TRUE if the file is executable, FALSE otherwise.

os.Path.isfile

Purpose:

Checks if a file is a regular file.

Syntax:

Notes:

1. fname is the file name.
2. result is TRUE if the file is a regular file, FALSE otherwise.

os.Path.isdirectory

Purpose:

Checks if a file is a directory.

Syntax:

Notes:

1. fname is the file name.
2. result is TRUE if the file is a directory, FALSE otherwise.

os.Path.ishidden

Purpose:

Checks if a file is hidden.

Syntax:

Notes:

1. fname is the file name.
2. result is TRUE if the file is hidden, FALSE otherwise.

os.Path.islink

Purpose:

Checks if a file is UNIX symbolic link.

Syntax:

Notes:

1. fname is the file name.
2. result is TRUE if the file is a symbolic link, FALSE otherwise.

Usage:

This method can only be used on UNIX!

os.Path.isroot

Purpose:

Checks if a file path is a root path.

Syntax:

Notes:

1. path is the path to check.
2. result is TRUE if the path is a root path, FALSE otherwise.
3. On Unix the root path is '/'
4. On Windows the root path matches "[a-zA-Z]:\"

os.Path.type

Purpose:

Returns the file type as a string

Syntax:

Notes:

1. fname is the file name.
2. ftype can be one of:
   1. file : the file is a regular file
   2. directory : the file is a directory
   3. socket : the file is a socket
   4. fifo : the file is a fifo
   5. block : the file is a block device
   6. char : the file is a character device

Usage:

On UNIX, this method follows symbolic links. You must use the islink() method to identify symbolic links.

os.Path.size

Purpose:

Returns the size of a file.

Syntax:

Notes:

1. fname is the file name.
2. size is the file size

os.Path.atime

Purpose:

Returns the time of the last file access.

Syntax:

Notes:

1. fname is the name of the file.
2. atime is a string containing the last access time for the specified file in the standard format 'YYYY-MM-DD HH:MM:SS'.
3. If the function failed, it returns NULL.

os.Path.mtime

Purpose:

Returns the time of the last file modification.

Syntax:

Notes:

1. fname is the name of the file.
2. mtime is a string containing the last modification time for the specified file in the standard format 'YYYY-MM-DD HH:MM:SS'.
3. If the function failed, it returns NULL.

os.Path.rwx

Purpose:

Returns the UNIX file permissions of a file.

Syntax:

Notes:

1. fname is the name of the file.
2. mode is the combination of permissions for user, group and other.
3. Function returns -1 if it fails to get the permissions.

Usage:

This method can only be used on UNIX!

The mode is returned as a decimal value which is the combination of read, write and execution bits for the user, group and other part of the UNIX file permission. For example, if a file has the -rwxr-xr-x permissions, you get ( (4+2+1) * 64 + (4+1) * 8) + (4+1) ) = 493 from this method.

os.Path.chrwx

Purpose:

Changes the UNIX permissions of a file.

Syntax:

Notes:

1. fname is the name of the file.
2. mode is the UNIX permission combination in decimal (not octal!).
3. Function returns TRUE on success, FALSE otherwise.

Usage:

This method can only be used on UNIX!

The mode must be a decimal value which is the combination of read, write and execution bits for the user, group and other part of the UNIX file permission. Make sure to pass the mode as the decimal version of permissions, not as octal (the chrwx UNIX command takes an octal value as parameter). For example, to set -rw-r--r-- permissions, you must pass ( ((4+2) * 64) + (4 * 8) + 4 ) = 420 to this method.

os.Path.chown

Purpose:

Changes the UNIX owner and group of a file.

Syntax:

Notes:

1. fname is the name of the file.
2. uid is the user id.
3. gui is the group id.
4. Function returns TRUE on success, FALSE otherwise.

Usage:

This method can only be used on UNIX!

os.Path.uid

Purpose:

Returns the UNIX user id of a file.

Syntax:

Notes:

1. fname is the name of the file.
2. id is the user id.
3. Function returns -1 if it fails to get the user id.

Usage:

This method can only be used on UNIX!

os.Path.gid

Purpose:

Returns the UNIX group id of a file.

Syntax:

Notes:

1. fname is the name of the file.
2. id is the group id.
3. Function returns -1 if it fails to get the user id.

Usage:

This method can only be used on UNIX!

os.Path.homedir

Purpose:

Returns the path to the HOME directory of the current user.

Syntax:

Notes:

1. homedir Path to the HOME directory of the user.

os.Path.rootdir

Purpose:

Returns the root directory of the current working path.

Syntax:

Notes:

1. rootdir is the root directory of the current working path.
2. On Unix, it always returns '/'
3. On Windows it returns the current working drive as "[a-zA-Z]:\"

os.Path.dirfmask

Purpose:

Defines a filter mask for diropen.

Syntax:

Notes:

1. mask defines the filter mask (see below for possible values).

Usage:

When you call this function, you define the filter mask for any subsequent diropen call.

By default, all kinds of directory entries are selected by the diropen function. You can restrict the number of entries by using a filter mask.

The parameter of the dirfmask function must be a combination of the following bits:

• 0x01 = Exclude hidden files (.*)
• 0x02 = Exclude directories
• 0x04 = Exclude symbolic links
• 0x08 = Exclude regular files

For example, to retrieve only regular files, you must call:

01 CALL os.Path.dirfmask( 1 + 2 + 4 )

os.Path.dirsort

Purpose:

Defines the sort criteria and sort order for diropen.

Syntax:

Notes:

1. criteria is the sort criteria (see below for possible values).
2. order defines ascending (1) or descending (-1) order.

Usage:

When you call this function, you define the sort criteria and sort order for any subsequent diropen call.

The criteria parameter must be one of the following strings:

• "undefined" = No sort. This is the default. Entries are read as returned by the OS functions.
• "name" = Sort by file name.
• "size" = Sort by file size.
• "type" = Sort by file type (directory, link, regular file).
• "atime" = Sort by access time.
• "mtime" = Sort by modification time.
• "extension" = Sort by file extension.

When sorting by name, directory entries will be ordered according to the current locale.

When sorting by any criteria other than the file name, entries having the same value for the given criteria are ordered by name following the value of the order parameter.

os.Path.diropen

Purpose:

Opens a directory and returns an integer handle to this directory.

Syntax:

Notes:

1. dname is the name of the directory.
2. dirhandle is the directory handle. A dirhandle value of 0 indicates a failure when opening the directory.

Usage:

This function creates a list of directory

See also: dirfmask, dirsort

os.Path.dirclose

Purpose:

Closes the directory referenced by the directory handle dirhandle.

Syntax:

Notes:

1. dirhandle is the directory handle of the directory to close.

os.Path.dirnext

Purpose:

Reads the next entry in the directory.

Syntax:

Notes:

1. dirhandle is the directory handle of the directory to read.
2. direntry is the name of the entry read or NULL if all entries have been read.

os.Path.pwd

Purpose:

Returns the current working directory.

Syntax:

Notes:

1. cwd is the current working directory.

os.Path.chdir

Purpose:

Changes the current working directory.

Syntax:

Notes:

1. newdir is the directory to select.
2. result is TRUE if the current directory could be successfully selected.

os.Path.volumes

Purpose:

Returns the available volumes.

Syntax:

Notes:

1. volumes contains the list of all available volumes separated by "|".

os.Path.chvolume

Purpose:

Changes the current working volume.

Syntax:

Notes:

1. newvolume is the volume to select as the new current working volume.
2. result is TRUE if the current working volume could be successfully changed.
3. Sample : CALL os.Path.chvolume("C:\\") RETURNING result

os.Path.mkdir

Purpose:

Creates a new directory.

Syntax:

Notes:

1. dname is the name of the directory to create
2. result is TRUE if the directory has been successfully created, FALSE otherwise.

os.Path.delete

Purpose:

Deletes a file or a directory.

Syntax:

Notes:

1. dname is the name of the file or directory to delete
2. result is TRUE if the file or directory has been successfully deleted, FALSE otherwise.
3. A directory can only be deleted if it is empty.

os.Path.rename

Purpose:

Renames a file or a directory.

Syntax:

Notes:

1. oldname is the current name of the file or directory to be renamed.
2. newname is the new name to assign to the file or directory.
3. result is TRUE if the file or directory has been successfully renamed, FALSE otherwise.

os.Path.copy

Purpose:

Creates a new file by copying an existing file.

Syntax:

Notes:

1. source is the name of the file to copy.
2. dest is the destination name of the copied file.
3. result is TRUE if the file has been successfully copied, FALSE otherwise.

Examples:

Example 1: Extracting the parts of a file name

This program uses the file functions to extract the directory name, the base name, the root name, and the file extension:

01 IMPORT os
02 MAIN
03   DISPLAY "Dir name   = ", os.Path.dirname(arg_val(1))
04   DISPLAY "Base name  = ", os.Path.basename(arg_val(1))
05   DISPLAY "Root name  = ", os.Path.rootname(arg_val(1))
06   DISPLAY "Extension  = ", os.Path.extension(arg_val(1))
07 END MAIN

Example results:

Note that the above examples use Unix file names. On Windows the result would be different, as the file name separator is '\'.

Example 2: Browsing directories.

This program takes a directory path as an argument and scans the content recursively:

01 IMPORT os
02 MAIN
03   CALL showDir(arg_val(1))
04 END MAIN
05 FUNCTION showDir(path)
06   DEFINE path STRING
07   DEFINE child STRING
08   DEFINE h INTEGER
09   IF NOT os.Path.exists(path) THEN
10      RETURN
11   END IF
12   IF NOT os.Path.isdirectory(path) THEN
13      DISPLAY " ", os.Path.basename(path)
14      RETURN
15   END IF
16   DISPLAY "[", path, "]"
17   CALL os.Path.dirsort("name", 1)
18   LET h = os.Path.diropen(path)
19   WHILE h > 0
20      LET child = os.Path.dirnext(h)
21      IF child IS NULL THEN EXIT WHILE END IF
22      IF child == "." OR child == ".." THEN CONTINUE WHILE END IF
23      CALL showDir( os.Path.join( path, child ) )
24   END WHILE
25   CALL os.Path.dirclose(h)
26 END FUNCTION