1C:Enterprise 8.3. Developer Guide. Contents

TEMPORARY STORAGE MECHANISM, WORKING WITH FILES AND PICTURES

1C:Enterprise features a temporary storage mechanism that can store data bound to sessions. Another mechanism is used to work with files; it supports file exchange between the infobase and client application. This mechanism is specifically designed for thin and web clients and accounts for Web browser-specific constraints applied to working with files.

The temporary storage mechanism combined with the file use mechanism provides a set that can be used to place locally stored data to the infobase temporary storage, transfer this information from the temporary storage to the database and retrieve it to the user machine. The most common application tasks solved by these mechanisms are storing extra information, such as product pictures, contract related documents, etc. Temporary storage and file use mechanisms are often used together, though they can also be used individually.

20.1. TEMPORARY STORAGE

Temporary storage is a specialized information storage where a value can be placed. Its main purpose is storing information temporarily before it is transferred to the database during client/server interaction.

Temporary storage might be required, for example, if Web browser operation model dictates the need to transfer user-selected file directly to the server without storing it at the client. During transmission the file is placed in the temporary storage and can later be used to write an object to the database.

Temporary storage can be used as a universal storage with controlled data lifetime:

„ If data placed in the temporary storage are bound to a form, their lifetime depends on the form lifetime. When the form object is removed, the storage is cleared of all related information.

„ If data placed in the temporary storage are not bound to a form, the storage is cleared in the following cases:

○ the next form request;

○ the next server call from client common module;

○ context and out-of-context client calls from the form;

○ server call from command module. If the server is called to place a value in the temporary storage, clearing is not performed. The storage is cleared after the call has completed.

It means one or more values can be placed in the temporary storage and used in the next call. After the value is used, but before the server call has completed, the value is automatically deleted.

The most typical application task solved by temporary storage is providing access to files or pictures before object is recorded in the infobase, e.g., in an item form.

Data placed in the storage are identified by a unique address that can later be used in write, read or delete operations. This address is returned by methods that write values to the temporary storage. A separate method of the 1C:Enterprise script can be used to determine if the passed address points to the data in the temporary storage.

20.2. WORKING WITH FILES AND TEMPORARY STORAGE

This section describes the most common applications of temporary storage and file use mechanisms.

20.2.1. Saving Data from File in Temporary Storage

20.2.1.1. Single File Placement

PutFile() method places a file from a local file system to the temporary storage. This method can receive a temporary storage address to be used for the file. If the address is undefined or is an empty string, a new address is created and returned by the method through a special parameter.

If interactive work mode parameter is True, the method displays a standard file selection dialog box where the user can select a file to be placed in the storage. In this case the method also returns address for the selected file.

The method returns False if the user cancels operation in the file selection dialog box in the interactive mode.

20.2.1.2. File Set Placement

PutFiles() method places multiple files to the temporary storage within a single call. This method can be used in different ways:

„ by generating a list of files to be added, e.g., when files to be placed in the infobase are preliminarily selected;

„ by passing file search mask to the method, e.g., when all files of a certain type (e.g., all pictures) need to be placed in the infobase;

„ by passing a predefined FileDialog object to the method in the open file mode.

Upon completion this method can return a list of added files.

//  FileList – attribute of ValueList type form
//  Containing a list of files to be added

FileArray  = New Array;
For  each ListItem From FileList Do

FileArray.Add(NewTransferableFileDescription(ListItem, ));

EndDo;

PlacedFiles  = New Array;
Result  = PutFiles(FileArray, PlacedFiles, ,False,UUID);

NOTE

To use the PutFiles() method enable an extension for working with files in the web client (see page 2-851).

20.2.2. Data Placement in Temporary Storage

PutToTempStorage() method is similar to PutFile(), except that data to be written in the temporary storage are represented as values rather than a file system path. Similarly, if no existing temporary storage address is specified, a new address is created. The address is returned as function result. Like files, data always belong to a form and are automatically deleted after form removal.

20.2.3. Data Retrieval from Temporary Storage

When writing an object to the infobase, the user might want to retrieve data from the temporary storage and place them, for example, in infobase object attribute. A special GetFromTempStorage() method can be used for this purpose. This method extracts data from the temporary storage and returns them in its execution result. To retrieve data the user needs to specify their address in the temporary storage. This address is returned by successfully completed methods that place data in the temporary storage (see previous sections).

NOTE

When you retrieve values from a temporary storage to the server, note that they are obtained via references. In fact, this reference points to a value stored in cache. The value will be stored in cache and then written to disc and removed from cache within 20 minutes of it being placed in the storage or after it is last called. The next time you call the value, it will be downloaded from disc and put into cache again.

20.2.4. Data Deletion from Temporary Storage

After data are saved in an infobase object attribute, they can be removed from the temporary storage. DeleteFromTempStorage() method can be used for deletion purposes. This method receives a temporary storage address as its parameter.

20.2.5. Address Check for Temporary Storage Membership

An address can point to either the temporary storage or an infobase attribute. Use IsTempStorageURL() method to check the address type.

It checks if the passed address points to the temporary storage. It returns True if the address belongs to the storage.

20.2.6. Attribute Address Retrieval

After data are placed in an infobase object attribute, the user might want to access them using file methods.

However, before retrieving data, for example, from the attribute, it is necessary to obtain the attribute address. A special GetURL() method can be used for this purpose.

It can use source parameters to return value address in the infobase. To achieve this pass an object key (it can be a reference to the object or an information register record key) and attribute name to the method. If address for a value stored in a tabular section attribute is required, add the tabular section name and a period (.) to the attribute name parameter.

Example:

Goods.Image

20.2.7. File Retrieval from Infobase

20.2.7.1. Single File Retrieval

GetFile() method gets an infobase file and saves it in the user's local file system. The first parameter defines file address in the infobase object attribute or temporary file storage. Data is not saved if the user on behalf of whom the operation is performed lacks View rights to an infobase object attribute. The second parameter specifies where the file is to be saved. A path is required in the non-interactive mode. This parameter is optional in the interactive mode.

By default this method runs in the interactive mode. In other words, it generates a dialog box where the user selects an action for the retrieved file: execute it or save in the user-selected file system location. If the interactive mode is selected, but File Name parameter is not specified, the open file operation is unavailable. This method returns a Boolean value. False means the user has cancelled the operation in the save file dialog box in the interactive mode.

20.2.7.2. File Set Retrieval

GetFiles() method can be used to get and save multiple files stored in the infobase in the user's local file system. A list of downloaded files is passed as the method parameter.

//  FileList – a list of values with references to items
//  of catalog with files to be downloaded
//  Value list presentation is the loaded file name

FileArray  = New Array;
For  each ListItem From FileList Do

File = New File(String(ListItem.Value));
ReceivedFile = New TransferableFileDescription;
ReceivedFile.Name = ListItem.Presentation;
ReceivedFile.Location = GetURL(ListItem.Value, "Data");
FileArray.Add(ReceivedFile);
EndDo;

ReceivedFiles  = New Array;
Result  = GetFiles(FileArray,ReceivedFiles,DownloadedFilesPath,False);

If  NOT Result Then

Message = New UserMessage;
Message.Text = "Error getting files!";
Message.Message();
EndIf;

Upon completion this method can return a list of downloaded files with their full names.

NOTE

To use the GetFiles() method enable an extension for working with files in the web client (see page 2-851).

If the Name property of the TransferableFileDescription object contains an absolute path to a file, the file is saved in this path with no regard to the FileLocation parameter.

The local file system path or a FileDialog object can be used as the FileLocation parameter in directory selection mode or file selection mode. If a FileDialog object is set as the FileLocation parameter in file save mode:

„ The dialog will be called for every sent file, except files for which the Name property of the TransferableFileDescription object contains an absolute path.

„ The value of the Name property of the TransferableFileDescription object will be used as the initial file name in the dialog.

„ If saving is cancelled for any file, the Name property of the Transferab- leFileDescription object will contain an empty string.

„ The GetFiles() method returns True if at least one file is successfully received.

„ Note that files are actually received after the user responds to prompts to specify the name and path of all received files.

„ If the user on behalf of whom the GetFiles()method is executed lacks View rights to at least one object attribute of an infobase from which files are received, the entire operation fails.

Example:

TranserredFiles  = New Array;
Details  = New TransferableFileDescription("Details", AddressFile);
TranserredFiles.Add(Details);

FileChoice  = New FileDialog(FileDialogMode.Save);
FileChoice.Title  = "Save Archive";
FileChoice.Extension  = "zip";
FileChoice.Filter  = "Archive(*.zip)|*.zip|All files|*.*";
FileChoice.FilterIndex  = 0;

GetFiles(TranserredFiles,  , FileChoice, False);

If interactive mode is selected for file directory selection, the web client also prompts the user to confirm that files with absolute paths are to be saved. If files are saved non-interactively (directory path is specified in the appropriate parameter), the query is executed for the entire list of files to be saved.

20.2.8. Example of File Method Use

//  Obtain file from disk in interactive mode
//  and place it in temporary storage.
&AtClient
Procedure  SelectFileFromDiskAndWrite()

Var SelectedName;
Var TempStorageURL;

NewObject = Object.Ref.IsEmpty();
If PutFile(TempStorageURL, "", SelectedName, True) Then

Object.FileName = SelectedName;
PutObjectFile(TempStorageURL);

EndIf;

EndProcedure

//  Copy file from temporary storage to attribute
//  of catalog, write object, delete file from temporary
//  storage.
&AtServer
Procedure  PutObjectFile(TempStorageURL)

CatalogItem = FormAttributeToValue("Object");
BinaryData = GetFromTempStorage(TempStorageURL);
CatalogItem.FileData = New ValueStorage(BinaryData, New  Deflation());

File = New File(CatalogItem.FileName);
CatalogItem.FileName = File.Name;
CatalogItem.Write();

Modified = False;
DeleteFromTempStorage(TempStorageURL);
ValueToFormAttribute(CatalogItem, "Object");

EndProcedure

//  Read file from attribute and store it
//  in local disk in interactive mode.
&AtClient
Procedure  ReadFileAndSaveToDisk()

Address =GetURL(Object.Ref,"FileData");
GetFile(Address, Object.FileName, True);

EndProcedure

20.2.9. Enabling Bulk File Operations

When certain operations are executed in the web client, you might need to get permission for some file operations. For example, should you need to receive a document from an infobase and then open the saved document using the associated application.

To do this, you have to answer the question about document saving and starting the application. More operations will cause more prompts to the user.

You can use the RequestUserPermission() method to reduce the number of prompts. When this method is used, a list of all operations to be executed is shown to the user, and the system requests permission to perform a group of operations. If the user allows it, the requested operations will be executed without additional user prompts. If the permission is denied, operations will be executed normally: one prompt per request.

NOTE

To use the RequestUserPermission() method in the web client, you need to connect the files operations extension (see page 2-851).

Let's take a look at an example of the code:

If  AttachFileSystemExtension() Then
Ref = GetURL(Object.Ref, "FileData");

// Generate description of the passed files (in this case one  file)
UploadingFiles = New Array;
Details = New TransferableFileDescription(Object.FileName, Ref);
UploadingFiles.Add(Details);

// Prepare object for receiving information about received files
UploadedFiles = New Array;

// Define other parameters of methods
StorageDirectory = "c:\temp";
Interactively = False;
UploadedFileName = StorageDirectory + "\" +  Object.FileName;

// Prepare description of methods for receipt of permissions
Methods = New Array;
Methods.Add(New Array);
Methods[0].Add("GetFiles");
Methods[0].Add(UploadingFiles);
Methods[0].Add(UploadedFiles);
Methods[0].Add(StorageDirectory);
Methods[0].Add(Interactively);
Methods.Add(New Array);
Methods[1].Add("RunApp");
Methods[1].Add(UploadedFileName);

If Not RequestUserPermission(Methods) Then

DoMessageBox("User declined the permission request.");
Return;

EndIf;

GetFiles(UploadingFiles, UploadedFiles, StorageDirectory,  Interactively);
RunApp(UploadedFileName);

Else

DoMessageBox("The operation is not supported. The File  Operations extension is not installed.");

EndIf;

We should note some of the specifics of using the RequestUserPermission() method:

„ Permission is requested only for the following methods:

○ GetFiles() ○ PutFiles()

○ FindFiles()

○ RunApp()

○ FileCopy() ○ MoveFile()

○ DeleteFiles()

„ Permission is requested for a specific set of method parameters. When the file method is actually executed, the parameter values will be different from those that were permitted. This permission will not be valid and the user will receive a separate prompt to confirm the operation.

„ If you need to perform two or more similar operations with a file (even with the same set of parameters), you should specify the corresponding number of items in the RequestUserPermission() method parameter array. For example, if you need to get the same file from an infobase twice and place it in a fixed file system location, request two operations.

„ If permission is requested for an operation that is related to execution of an interactive operation (such as the GetFiles() function receiving a FileDialog object as the parameter), such an operation is excluded from the request.

Received permissions are saved until the allowed call is executed or 1C:Enterprise script execution has been completed.

NOTE

In a thin and a thick client, the RequestUserPermission() method always returns True without user interaction.

20.2.10. Working with Temporary Storage in Background Job

Temporary storage mechanism allows passing data from background job to the initiating session. To do this, use the PutToTempStorage() method to place an empty value in the temporary storage in the parent session. Then pass the resulting address to the procedure through background job parameters. If the retrieved address is passed to the PutToTempStorage() method in the background job, the value is copied to the parent session with this address.

20.2.11. Address Support in Picture Box

Field form element of Image field type supports display of picture set by value address (value can be a picture or binary data) in the temporary storage or database.

For this purpose the Data property of the form element should be assigned a stringtype attribute. The value of this attribute is interpreted as picture address.

Fig. 314. Display of Picture in Form

//  Example 1
//  Bind picture box to picture address in temporary
//  storage. PictureAddress – string-type form attribute
PutFile(PictureAddress,  SourceName, SelectedName, True, UUID);

//  Example 2
//  Get picture address from attribute of
//  infobase object
PictureFile  = Object.PictureFile;
If  Not PictureFile.IsEmpty() Then
PictureAddress = GetURL(PictureFile, "FileData")
Else
PictureAddress = "";
EndIf;

20.2.12. Access to standard directories

When the system is used, there should be some location in the file system to store different file data that, on the one hand, are temporal data, but, on the other hand, must be kept for a long time. These files include drafts for document management systems, external components being run on the client computer side, etc.

To store these files, a special directory linked to a particular user of a particular database is designated. One user working with two infobases will have access to two different directories where user data is stored. The location of the directory is defined by applying the UserDataWorkDir() method. If the directory does not exist, it is created when you call it for the first time. If it is not possible to create it, the system calls the exception.

NOTE

The UserDataWorkDir() method cannot be accessed on the server side.

The operating system has a special directory designated to ensure permanent storage of user data. These can include any reports, printing forms of documents, etc. Data that can be passed to external consumers in the future is stored in this directory. The directory can be accessed via the DocumentsDir() method. The physical location of the directory depends on the operating system that runs the application.

„ In Windows, it is the OS current user’s documents directory.

„ In Linux, it is the OS current user’s home directory.

„ In MacOS, it is a system directory of documents.

„ In MacOS X, it is the current user’s documents directory.

20.3. SPECIFIC FEATURES OF USING IN WEB CLIENT

Certain constraints are applied to the described mechanism in the web client. These are related to the Web browser security model. Thus, the client cannot save files in the local file system, i.e. interactive mode is the only option for PutFile() and GetFile() methods. An attempt to use non-interactive mode generates an exception. Dialog boxes displayed in the interactive mode are browser-specific.

However, functionalities of working with files in the web client can be extended, if necessary. Use the extension for working with files for this purpose. After the extension is enabled, the following objects and methods for working with files become available in the web client:

„ Methods:

○     GetFiles() ○ PutFiles()

○ FindFiles()

○ RunApp()

○ CreateDirectory()

○ FileCopy() ○ MoveFile() ○ DeleteFiles()

„ Objects:

○     File

○ FileDialog

NOTE 1

For the file operations extension to work correctly, it is recommended to use Microsoft Core XML Services (MSXML) version 4.0 or 6.0 in Microsoft Internet Explorer.

NOTE 2

The file operations extension for Microsoft Internet Explorer is installed in %APPDATA%\1C\1CEWebExt\FileSystemExtIE.

Do the following before using these components:

„ Customize the web browser as necessary (for details see "1C:Enterprise 8.3. Administrator Guide").

„ Install the extension for working with files. Use the global context InstallFileSystemExtension() method for this purpose. This activity is interactive and has to be executed once for each local machine user working with the extension.

„ Enable the extension for working with files. Use the AttachFileSystemExtension() method for this purpose.