4D Doc Center : SET EXTERNAL DATA PATH

Home

4D v14.3

SET EXTERNAL DATA PATH


SET EXTERNAL DATA PATH ( aField ; path )

Parameter	Type	Description
aField	Text, BLOB, Picture	Field for which to set the storage location
path	Text, Longint	Pathname and file name of external storage or 0 = use structure definition 1 = use default folder

Description

The SET EXTERNAL DATA PATH command sets or modifies, for the current record, the external storage location for the aField field passed as parameter.

With 4D (beginning with version 13), it is possible to store Text, BLOB and Picture type fields outside of the data file. For a complete description of this functionality, refer to the Design Reference manual.

The setting defined by this command is only applied when the current record is saved on the disk. Storage parameters set in the application structure are not changed. If the current record is canceled, the command does nothing. Once this command is executed, 4D automatically maintains the link between the field of the record and the file on disk. You do not need to execute the command again (except if you need to change the path).

In path, you can pass either a custom pathname, or a constant designating an automatic location:

custom pathname to file
In this case, you use external storage in "custom mode." Certain 4D database functions are not available automatically in this mode (see the Design Reference manual).
You can pass either a path relative to the data file or an absolute path, including the name and extension of the storage file (to set a relative path, pass "../" at the start of the string). This extension must match the Real type of data (there is no conversion when it is saved). You must use the system syntax. You can designate any folder, including the default folder of database external files (databaseName.ExternalData) - in this case, these files are included when the database is saved. If a folder does not exist, 4D creates it automatically (an error is returned if creation fails, for example if there are not appropriate rights).
If you save the external file in the same folder as the data file or one of its subfolders, 4D considers that the path specified is relative to the data file and maintains the link even when the data file folder is moved or renamed.
Note that this means it is possible to "share" the same external file between several records. Any changes made to this external file are available in all the records. In this case, if several processes can write the same fields simultaneously, you must be careful to prevent concurrent accesses through semaphores, so as not to risk damaging the external files.

automatic location
You can designate two automatic locations using the following constants, found in the Data File Maintenance theme:

Constant	Type	Value	Comment
Use default folder	Longint	1	The data of the field passed as parameter are saved in the default folder, named databaseName.ExternalData and placed next to the data file. In this mode, external data are managed by 4D as if they were inside the data file.
Use structure definition	Longint	0	4D uses the parameters set in the structure for field storage (see the Design Reference manual). If you change from external storage to internal storage, the external file is not deleted.

Note: The SET EXTERNAL DATA PATH command can only be executed on a local 4D or on 4D Server. It does nothing when it is executed on a remote 4D.

Example 1

You want to save the contents of a picture file outside of the data when it exceeds a certain size. In the form validation button, you can write:

 If(Picture size([Photos]InputField)>1300000)

  // store large files outside data

    SET EXTERNAL DATA PATH([Photos]InputField;

    "C:\\Storage\\LargePicts\\" + String(Record number)+ ".jpg")

 Else

  // store smaller files as defined in structure

    SET EXTERNAL DATA PATH([Photos]InputField;Use structure definition)

 End if

Example 2

You want to save the contents of a picture field outside of the data and relative to the database data file:

 CREATE RECORD([Photos])

 [Photos]Thumbnail:=$small_pict

 SET EXTERNAL DATA PATH([Photos]Thumbnail;"../custom"+Folder separator+$pictname)

  //storage in "/custom/" folder next to the data file

 SAVE RECORD([Photos])