Save the files in a directory into a Sculptor keyed file


Save the files in a directory into a Sculptor keyed file


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.


The identifying name of the Sculptor keyed file to receive the file list.


The name of the directory whose contents are to be returned, e.g.:


The directory can be on a server, and can contain environment variables.


This argument must be one of the following:


Selects all files


Selects all files with the extension x. x may be any number of characters.

No other patterns are supported.


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:


Return standard files.


Return directory names (pattern is ignored).


Remove filename extensions.


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:


An alphanumeric field to receive the file names. If the field is not long enough, the name is truncated.


A u1 type field to receive the file type (1=file, 2=directory). These are also defined in $SCULPTOR/include/files.h, as follows:






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:


The file size in bytes (field filled when DIRX_SIZE option is specified)


Date and time the file was created (field filled when DIRX_CREATED option is specified)


Date and time the file was last updated (field filled when DIRX_UPDATED option is specified)


Date and time the file was last accessed (field filled when DIRX_ACCESSED option is specified)


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.


Display file list in a file-driven table:


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"

     FileDir.Created->logical_type = LT_DTIME

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


File and directory handling functions