Select File Transfer Mode
The File Transfer Mode "Read raw data file" is offered by default in a new Change Object.
However there are a number of file operations other than just reading and writing that are supported by Planimate®.
Click on the Mode Option in the Menu to display and select other Modes, which are as follows:
- 1 Read raw data file
- 2 Write raw data file
- 3 Execute command only
- 4 Play Sound
- 5 Test / read file size
- 6 Save window image
- 7 Rename file
- 8 Copy file
- 9 Delete file
- 10 Fetch hyperlink
- 11 Create folder
- 12 Delete Folder
- 13 Delete Empty Folder Hierarchy
- 14 Test/Read resource size
- 15 Delete resource
- 16 Acquire file lock
- 17 Release file lock
- 18 File Lock Status Codes
Read raw data file
Select the Mode Read Raw Data File from the File Transfer Options menu.
Choose the Target File from the File Access Options menu.
Select from the Options available, refer to File Transfer Options for details about options.
If you want to begin your File read other than at the start of the file, specify File Row and File Col offsets.
If you want to read a portion only of the File, specify the Limit Rows and Limit Cols ranges.
The above settings can make reference to numbers, or strings (labels) using the Attribute Value Selection Dialog.
If you wish to have a system command executed at the time of this file read, enter the command string in the Execute Option. Otherwise leave it blank.
Select the Target Attributes into which the data read from the file will be placed.
Tables will accept and read arbitrary length tables from a file. The table does not shrink if less data is loaded than required, but it will expand to fit total number of rows read.
Reading into a block offset is supported. The table is padded with rows to achieve the required block row offset.
For example if a block read is started at table row 1000, an empty table will have rows 1...999 inserted before row 1000 (the first read row)
The data importer also supports comma delimited data with commas inside quoted strings
Write raw data file
In the File Access Options Menu, first choose the Mode you wish to use by selecting the mode option.
The default mode is Write raw data file.
The File Transfer Mode item picker dialog displays other options available under Mode.
You then select the Target File option from the File Access Options menu.
Either type in a file name of you choice, or from the files displayed in the browser that appears, choose one.
Next select Options in the File Access Options Menu, and the File/Event Options list picker dialog appears.
The File Write Targets menu then appears.
Targets may be added by means of the Attribute Value Selection dialog that appears when " Add Target " is selected.
Execute command only
No file operation is performed here, you are offered a field in which you can enter a system command.
Offers a field in which you can enter a reference to a .WAV file. When an Item passes through this Change Object, the sound will be played asynchronously.
If you want the sound to be played synchronously, select the "Wait for File to Complete" option.
Test / read file size
This tests for the existence of a file, and deposits result into first attribute in the Data Targets list. It returns sizes of file (0..2Billion) or -1 if the file does not exist.
This operation also sets the "Error Result" attribute to the file size.
Save window image
Offers a File Name with which the currently-visible panel will be saved, in the form of a bitmap image ( .BMP extension).
This option also accept an optional data target.
IF provided, it is treated as a portal/panel reference, enabling the modeller to specify a single panel to save instead of the currently visible one.
This File operation can also be set to write to the clipboard.
Supply a filename of just "-" (using the dynamic filename option and a label list) and instead of the bitmap being written to a file, it will be placed into the clipboard, from which the user can paste the image into a graphics application.
Offers two fields for renaming files, from and to.
Offers two fields for copying files, from and to.
Offers a Field for naming the file to be deleted.
An option enables you to reference an Attribute (formatted with a Label List) to supply the name of the file to be deleted.
Initiates a URL read from a change object - no content is actually read from the web server yet.
The "from" spec can either be a file spec, in which case the URL is read from the first line of the file OR a direct URL reference.
In either case INI file mappings are applied to the from file name/URL
Offers a Field for naming the folder to be created.
An option enables you to reference an Attribute (formatted with a Label List) to supply the name of the folder to be created.
Note that this will create every folder specified in a multi-level folder specification.
Will delete the nominated folder only if it is empty.
Delete Empty Folder Hierarchy
Will delete all empty folders it finds within the specified folder and deletes the specified folder if it ends up empty.
Whilst this does not delete files, modellers must still be careful to call this with an intended folder.
Test/Read resource size
This mode is similar to the Test File Size routine mode except it looks in Planimate® databases as well.
In this mode, "Target File Attribute" names a file/resource.
If the name doesn't include an extension, "RTF" is assumed. The file operation sets the first "Data Target" (if any exist) and the "Error Result" to the file size (in bytes) of the resource or -1 if the resource is not found.
This is useful to test if RTF notes exist.
This is intended to be used to "clear out" RTF notes from a Planimate® database resource (.DB) file.
This will remove the specified item from the runtime database (if set up) otherwise the model database is used (if available, not for a standalone EXE).
If the name does not include an extension, "RTF" is assumed.
Acquire file lock
A file lock is a file that an instance of Planimate® keeps open to enable a mutual exclusion (mutex) mechanism to be set up.
This is often useful in database applications where you need to lock multiple users from accessing a resource simultaneously.
In this case the lock would reside in a shared directory.
(note: The supporting network must support file locking)
Planimate® opens/creates a lock file with shared read and exclusive write permissions.
This means other instances can read the file but not control it.
The target file (specified directly or via a label) is the lock file.
It is suggested that a ".LCK" extension be used.
THIS FILE WILL BE OVERWRITTEN so ensure it is not pointing at a data file.
If present, the first data target will be interpreted as a string and written to the file, as a "tag" to help identify who has the lock.
It may be useful to use the ability to specify a table row here so an informative line containing user name, time and computer name can be written.
If the lock is successful, the error result target is set to 0, otherwise a non zero error code (see below) is set.
If an error occurs, detail of this error is available as a string in the new system attribute "Last Lock File Error".
If the error is that another user has the lock, then this attribute will contain the "tag" and should be displayed to the user.
If acquiring a lock fails, the system will sleep 3 seconds and try again.
It will do this 3 times before returning a failure.
It is valid to acquire a lock on a file multiple times.
In this case the lock file is "verified" (against the original tag) to ensure the lock is still valid.
A lock can be lost (unknown to PL) if a network outage occurs or the server is rebooted.
Hence it is a good idea to verify locks which have been open for a long time at strategic times; eg before starting a data write after an edit session.
Locks persist when the simulation engine stops/restarts.
Release file lock
The target file specifies the lock file to close.
If this file is currently in the known lock list, it is verified that it in fact still has the correct "tag" and the file is closed and deleted.
If verification fails or the file was not originally acquired (or previously went stale and was removed from the lock list), an error code is returned (Stale Lock).
Both lock operations set the "Last File Accessed" system attribute to the actual name of the lock file, mainly to assist in debugging and diagnostics.
The Edit menu contains a "File Locks" option which will list any current open lock files and their tags.
The locks are also verified.
File Lock Status Codes
Both lock operations will return status codes from the following table:
- 0: Indicates the lock was acquired/confirmed or released without problem
- 1: Failed to acquire a lock; either the lock file is in use by another instance or there is a network problem. More detail is in the "Last Lock File Error" system attribute
- 2: Attempt to release a lock on a file that this instance did not have a lock registered
- 3: Stale Lock. This can occur either when reacquiring (verifying) a lock or releasing a lock. It indicates that the lock file is no longer valid perhaps because of a network outage.
It is recommended that lock files do not get kept open "all day" but rather that user interfaces are designed such that a user acquires a lock only when they are ready to make a change.
This will help reduce stale locks.
The System string attribute to get the current computer's name is useful for identifying file locks.
idkbase note 10119