Save the files in a directory into a Sculptor keyed file

dir_to_file()

Save the files in a directory into a Sculptor keyed file

SYNTAX

dir_to_file(file_id, directory, pattern, options)

This function is similar to dir() except that the file names and types are returned by inserting records into the specified Sculptor keyed file, which must be open in create or update mode. This avoids limitations with array sizes in the dir() function.

file_id	The identifying name of the Sculptor keyed file to receive the file list.
directory	The name of the directory whose contents are to be returned, e.g.: “.” “/usr/data” The directory can be on a server, and can contain environment variables.
pattern	This argument must be one of the following: “*” Selects all files “*.x“ Selects all files with the extension x. x may be any number of characters. No other patterns are supported.
options	One or more options. Multiple options are combined using the | operator. Options are defined in the standard include file $SCULPTOR/include/files.h. The options are: DIR_FILES Return standard files. DIR_DIRS Return directory names (pattern is ignored). DIR_RMEXTN Remove filename extensions. DIR_NATIVE Keep native filename. If this is specified, filenames are returned in native format with no conversion. If not, filenames in MS-DOS/Windows are folded to lower case. Either DIR_FILES, DIR_DIRS or both must be specified.

For each file, the function assigns values to the following “known” fields in the file buffer, then inserts a record into the file:

FileName	An alphanumeric field to receive the file names. If the field is not long enough, the name is truncated.
FileType	A u1 type field to receive the file type (1=file, 2=directory). These are also defined in $SCULPTOR/include/files.h, as follows: FILETYPE_FILE 1 FILETYPE_DIR 2
Count	An i4 type field, incremented by 1 before each new record is inserted.

Since Sculptor version 6.2.0 the following extra fields are now recognised:

FileSize,,i4	The file size in bytes (field filled when DIRX_SIZE option is specified)
Created,,i4/td	Date and time the file was created (field filled when DIRX_CREATED option is specified)
Updated,,i4/td	Date and time the file was last updated (field filled when DIRX_UPDATED option is specified)
Accessed,,i4/td	Date and time the file was last accessed (field filled when DIRX_ACCESSED option is specified)

Note

The /td type cannot be specified in the data dictionary. It must be assigned at runtime using the syntax:

FILEID.Updated->logical_type = LT_DTIME

All these fields are optional, though obviously FileName is normally needed. Other fields may exist and should be initialised as required. The Count field should be in initialised before calling the function, normally to 0, but another value can be used if required.

Any field may be a key field or a data field, but either the FileName or Count field should be in the key to ensure it is unique. Duplicate records are ignored and do not generate an error.

Normally the file should be created empty before calling this function, though it is possible to design a file that can have records added from different directories.

The function returns the number of files found if successful, or a negative value to indicate an error.

---

EXAMPLE

Display file list in a file-driven table:

dirtofile.d

Key fields
1: FileName,"File Name",a100

Data fields
2: FileType,"File Type",u1
3: Count,"Count",i4
4: Created,"Created",i4

!include <files.h>

!ofile FileDir "dirtofile" create

     +table FileTable at 49,96 {
          source_object = FileDir
          rows = 20
     }
     ...


     if (Dir = "" or access(Dir, TEST_EXISTS) <> 0) {
          error "Invalid directory"
          return
     }

     FileDir.Created->logical_type = LT_DTIME

     openfile FileDir create
     dir_to_file(FileDir, Dir, "*", DIR_FILES | DIR_DIRS | DIRX_CREATED)
     display FileTable

---

RELATED TOPICS

File and directory handling functions