This function is used to open an album or track database if not already open.
The path may contain any of the escape sequences described in Escape Sequences. At runtime, the path to a database must be absolute (/) or relative to the home folder (~/) and must have a filename extension of .csv, .tsv or .tab.
The Update database values after opening option effectively causes an Update Database statement to be executed after the open.
The Readonly option will open the database as readonly. Note that when readonly, only manual editing of the database is disabled. The database can still be updated and changed via query database statements.
The Transient option is intended to be used when you create a database to be displayed to display transient information. ie. the actual files have no purpose once the database is displayed. When enabled, the database files will be deleted after opening the database. An attempt to save the file will result in a Save As. When opened, the database viewer's title bar icon will be a dim grey circle. No path will be displayed when right clicking on the title unless one is supplied in named variable Transient Database Path. The named variable must start with a / or it will be ignored. When Transient is enabled, the database is treated as readonly.
The Disable close in UI option prevents the database from being closed via the window's close button as long as an action is running. When action processing terminates, the database can be closed by the window's close button.
Database viewers have a help button which displays help on the various functionality in the viewer. You can override this help by specifying a named variable which contains the help text. Note this alternate help is only displayed when the database was opened by an action. The text can include markup sequences and any of the escape sequences described in Escape Sequences.
If alternate help is not supplied or the specified named variable is empty, a variable named Database Help-dbname is subsequently examined. dbname is the default title of the database. ie. the last path component without the filename extension.
This is useful when a database is being opened automatically when a batch process finishes. (A database created via a Create Album Database or Create Track Database statement). Setting this variable before the Batch End action is executed, will have the desired effect. For that reason, it may pay to define the variable in the Batch Start action.
The database window's title is typically the same as the last path component (without the filename extension) in its path. You can set any title you wish by setting the Database Title named variable to the desired title. Warning: the named variable must be set before executing the Open Database statement. The named variable is cleared when the database is opened.
This function is not valid when executing grouped.
If the file is not already open and it cannot be opened, the typical result is that an error message will be displayed and action processing will be terminated. You can change this behaviour by setting the Silent option. When the option is enabled, a failed open will result in the action test state being set to false. A successful open will set the action test state to true. When not batch processing if the path to the database is invalid an error will always be posted. Note that the silent setting is always treated as enabled when the statement is executed while batch processing.
When this statement is executed while batch processing, the opened database will only be accessible when the Action Pending window is displayed. Typically this is when the user is being prompted. Even when accessible, the database will have limited functionality. Typically open databases while batch processing should be employed as a means of user interaction. Note that when a database is opened in this manner, the loading of thumbnails will be halted unless the Action Pending window is displayed.
Many resource actions use discardable databases. If you wish to keep state as to the user's resized window you can configure named variable Auto Save Database Window Size as follows:
runtime action set name # runtime action set value
Example: to use the currently mapped action runtime set and a variable of wsize you would execute the following statement before opening the database.
Set named variable 'Auto Save Database Window Size' to "\?rs#wsize"
If a database is opened while action processing and there is no saved size in an associated plist file and the specified runtime setting value exists, it will be used to set the window's size. When a database is closed if the named variable was configured when first opened, the current window size will be retained. Note that this will work even if action processing has already terminated when the window is closed.
It is a good idea to empty the Auto Save Database Window Size named variable after opening the database so that it does not affect subsequent opens. Remember use of the named variable is not required in normal database usage as the window size is retained in the plist file.