Go to the Extras menu>Options to adapt the features and functionalities of dqMan.
The last open category is saved when leaving the options dialog and restored on the next visit.
The General category has four subsections:
| Setting Name | What It Does |
|---|---|
Object Functions and the DQL favorites are stored locally, therefore every instance of dqMan uses its own data. However, Favorites can be shared if the full paths to the shared favorite files are supplied. The XML files which contain the favorites and Object Functions (DQL-Repository.xml and Functions.xml) need to be copied to a network drive for sharing. If the shared files are not available, local versions will be used instead.
You can add and manage links to documents, URLs or program files to the Documentation menu using the function bar:
Grid Hints show additional information for single objects. They become faded in when the mouse is moved onto the row header (containing the row number).
Grid Hints can be defined for different object types. They consist of a hint template and translations. A Grid Hint template contains the following elements:
Translations turn values into readable designations. They are valid globally, that is, a translation for the attribute client_capability is valid for all defined Grid Hints.
These settings have already been described in #16.3.5.-describe-options.
In the Repository Navigator, you can manage the Cabinets/Folder Tree, the Object Type Tree and the Group Tree.
The Cabinets/Folder Tree
The Object Type Tree
The Group Tree
Functions are user programmable extensions. There are two different types of functions:
Object functions, available from the DQL result grid, can contain references to the DQL result grid, as known from the Script Generator. On execution, the function is executed once for every selected object whereby the references are replaced with values from the current result grid.
Session functions need a valid session and are executed only once. They cannot reference any values from the current session window.
dqMan is installed with a number of object and session functions that demonstrate the use of the extended functionality described below. If you have any more questions, send us an email at dqMan@fme.de.
This page displays all the available functions and provides tools to manage them, such as edit, copy a function, add and delete a function :
Edit a function
Copy a function
Add a function
Delete a function
Copy a function
Export selected functions to XML for exchange with other dqMan users.
Import functions from XML file.
You can deactivate object functions without deleting them, in which case the function name is cleared.
The Object Function Assistant is used for easy creation and modifying an assistant.
Settings:
Options
Targets
On the second page (not available for option Execute as Subquery), you can define global variables. When calling the function, these variables are filled in either by the user's manual input or by queries from the repository, using API commands. The values of the global variables are valid for all objects processed in one function call.
In the variables, you can also reference column values of the DQL result list (for example, {r_object_id}). In this case, the function can be executed for single objects only. The option Allow multiselect is deactivated automatically.
The DQL query:
Select full_format from dmr_content where any parent_id = '{r_object_id}’ order by 1
results in a pick list that contains all available formats of an object. The column r_object_id must be contained in the DQL result list and only one object must be selected, otherwise this function is disabled.
To check the syntax of a DQL query, click the Check syntax button, if a valid session is available in any session window.
Field type:
The third page of the dialog either displays a textfield for the API sequence or for a DQL query (the Execute as Subquery option).
The Basic API Sequence Syntax
The API sequence consists of a batch of API commands similar to an API script. References to values of the DQL result list are enclosed in curved clips. During execution, those references are replaced with values from the result list.
fetch,c,{r_object_id}
destroy,c,{r_object_id}
There are different placeholders to access the data of the result list:
Comments Each line beginning with the # character or with // is regarded as a comment line.
#fetch current object
fetch,c,{r_object_id}
# destroy the current object
destroy,c,{r_object_id}
Indenting For functions, indenting is allowed for all kinds of instructions. All leading spaces and tabs will be removed prior to executing the command. For multiline commands the same amount of leading characters will be removed from all lines as was done for the first line, except any valid char is found.
#Set ACL Domain
Set,c,{r_object_id},acl_domain
%ACL Domain%
If you create debug scripts, all indents are removed.
Variables There are three different kinds of variables:
Global variables, defined in the object function assistant and filled once at function initialization. Their values are valid for all processed objects.
Local variables, used within the API sequence, valid only for the processing of the current object:
Predefined variables, as you can see here:
Example:
# set ACL name
set,c,{r_object_id},acl_name
%ACL Name%
# Set ACL Domain
set,c,{r_object_id},acl_domain
%ACL Domain%
# Save
save,c,{r_object_id}
Script Commands Script commands extend the functionality of an object function. You can use placeholders or variables as parameters and they will be replaced by their values before executing the script command. Available script commands are:
Example for a collection loop:
%Collection%=readquery,c,select group_name from dm_group where any i_all_users_names = 'dmadmin'
#$Loop %Collection%
%group_name% = get,c,%Collection%,group_name
#$EndLoop
The handling of the collection is done by the #$EndLoop command. It is not necessary to add next or close commands.
The variable %LoopIndex<i>% does only exist within a loop and contains the current loop index, starting with 0. %Loopindex1% is the index of the first loop. %Loopindex2% would be the index of the second loop, if it is nested within the first loop.
Example for an attribute loop:
%id%= id,c,dm_document
#$Loop i_folder_id(%id%)
%Folder_ID% =get,c,%id%,i_folder_id[%LoopIndex1%]
#$Loop r_folder_path(%Folder_ID%)
%FolderPath%=get,c,%Folder_ID%,r_folder_path[%LoopIndex2%]
#$EndLoop
#$EndLoop
The variable %LoopIndex<i>% is incremented each time the #$EndLoop command is executed. It can be used as index for the repeating attribute values.
The DQL Query Syntax
In the DQL query text area any DQL query can be inserted that is executable by dqMan. This includes comments, template fields etc.
To reference any values of the underlying DQL result list, insert the attribute names in curved brackets. If any referenced attributes are not available in the DQL result list, the function is disabled.
The multiselect option is not available for this type of function.
Session functions are very similar to object functions. However, references to result list values, such as {r_object_id}, are not allowed; in addition, they are executed exactly once, independently from any selections made anywhere in the session window.
Go to the Functions menu to access installed session functions, which are only available if the active window is a session window with a valid session.
The security page allows hiding of one or more advanced “hazardous” admin features. You must proceed with caution as these features can easily create great damage, for example, the recursive destruction of complete folder tree branches. To avoid any mishaps, these features can be deactivated.
There is no protection for this setting. Every user can show or hide these functions according to their personal needs.
You can access the Security options by clicking Extras menu>Options>Security.
| Option | What It Does |
|---|---|
| Function Bar Element | What It Does |
|---|---|
| Command | What It Does |
|---|---|
| Setting | What It Does |
|---|---|
| Command | How It Affects Grid Colors |
|---|---|
| Grid Hint Element | Description |
|---|---|
| Translation Name | Role |
|---|---|
| Cabinets/Folder Tree Setting | What It Does |
|---|---|
| Object Type Tree Setting | What It Does |
|---|---|
| Group Tree Setting | What It Does |
|---|---|
| Setting | What It Does |
|---|---|
| Setting | What It Does/What It Is |
|---|---|
| Option Name | What It Does |
|---|---|
| Target Option | What It Does |
|---|---|
| Field Type Setting | What It Is/What It Does |
|---|---|
| Placeholder | What It Does |
|---|---|
| Local Variable Name | How to Use the Local Variable |
|---|---|
| Predefined Variable Name | How to Use the Predefined Variable |
|---|---|
| Script Command | What It Does |
|---|---|
Open session at startup
Automatically opens a session window at start up. Select the start view from the Start with list.
Restore last executed query from history
Restores the last executed DQL query from the history.
Show toolbar
Displays the toolbar.
Show tabs for open windows
Displays an additional toolbar with buttons for all open windows.
Save History Data
Saves DQL and API history data on local disk for later use. History size limits the size to the selected value. This limit is valid per session window.
Autosize row heights
Auto resizes the cells in the history list to Max Rows lines, if multi-line commands are displayed.
Save login info
Saves the login information, either with or without password. If the option always show next unused login is activated, the login dialog initializes with the credentials used for the most recent login.
Dump object with Autologin
If a dump from a repository without valid session is requested, credentials from login history will be used for a valid session.
Use full qualified repository names
If selected, fully qualified repository names (repository.content_server_name@host_name) are used to identify the repository.
Order login history by
Sorts the displayed order of saved logins in the login history.
Edit history
Modify the saved logins in the login history.
Show API hints
Shows hints with syntax information for API commands.
Clear input fields
After the successful execution of a command, the input controls are emptied. In case of error, the command remains for correction.
Reversed API log direction
Adds new lines at the top of the log.
DQL syntax help
Enables syntax help for DQL commands and functions.
Auto indent
Indents the cursor in new lines. Leading tabs and spaces will be copied from the proceeding line.
Restore column order and width
If the names and number of columns are not changed, the DQL result list settings (column width, column order and visible columns) will not change if DQL queries are executed again.
Reverse displayed order of repeating attributes
DQL queries usually return values of repeating attributes in reversed order. This option reverses the order again.
Move focus to DQL Result List after query execution
Moves the focus to the DQL Result grid if the query was successfully executed; If cleared, the focus remains in the DQL area.
Autosize columns
Column widths are adapted to the length of the represented data, with the limitation defined in the Max. Characters field.
Autosize rows
Row heights are adapted to the maximum number of lines of repeating attributes, with the limitation defined in the Max. Rows field. This option does only apply if the DQL query contains repeating attributes and their values are separated by carriage return.
Separate repeating attributes
Values of repeating attributes can be separated by comma/semicolon/carriage return/tab/custom string.
Enclose single values with
Encloses values of repeating attributes with single/double quotes or with no character at all if nothing is selected.
Highlight even lines (background)
Background color for even lines.
Marked lines (background)
Background color for marked rows.
Different columns (background)
Background color for cells with different content (from Compare data function)
Name
Freely selectable, shown in the grid hint list.
Typetag
Single Documentum type tag (for example, dm_document). Instead of a type tag, you can enter a type name that will be automatically replaced with the type tag.
Values
Hint template. References to attributes must be enclosed in curved clips and will be replaced automatically. All valid attributes of the type can be referenced. All other text and invalid attributes will be copied without changes.
Display repeating values in
You can displace repeating values in columns (the entire line is copied for each value in the attribute) or rows (values are comma separated).
If more than one repeating attribute is in the same line and displayed in column mode, the individual value indices are correlated (see Grid Hints for dm_acl objects).
Attribute
The name of the Documentum attribute.
Bitwise translation
Translates bitwise coded values, such as the attribute user_privileges of the type dm_user. Use comma separators for multiple values.
Values
Mapping of attribute values to displayed designations.
Auto expand at startup
The cabinet level is loaded and displayed on login.
Hide private cabinets
Private cabinets of other users get hidden. However, private cabinets of the current user are always visible.
Autoformat queries
Generated queries from query templates get formatted automatically.
Clear histories
Clicking this button clears the history for the Create Cabinet/Folder and Create Document functions.
Query templates
Queries the templates to generate DQL queries, displayed in the context menu of the repository tree.
A query template consists of:
- Name: Freely selectable name, displayed in the context menu.
- Query: Template of the DQL query. The code {*} is with the current folder path of the selected folder in the repository tree.
Select * from dm_document where folder ('{*}')
Additional available options:
- Use as default: Activate this option to define one standard template which is not displayed in the context menu but is called directly by left/center-clicking.
- Enable direct execution: If activated, the generated DQL query will be executed immediately. This sort of template is marked with a green arrow in the context menu.
Auto expand at startup
The first level is loaded and displayed on login.
Autoformat queries
Generated queries from query templates get formatted automatically.
Show customized types only
Only customized types and all types with customized subtypes are displayed in the tree. In addition, all Documentum base type tables are hidden, for example, dm_sysobject_s, whether registered or not.
Start with
Object type to start with (Type tree only).
Query templates
There are two kinds of query templates, for dm_type objects and for registered tables. For more information, see #the-cabinet-folder-tree.
Auto expand at startup
The first level is loaded and displayed on login.
Autoformat queries
Automatically formats queries generated from query templates.
Group top level by first <xx> characters
A repository can contain a large number of groups. This option lets you create an additional first level in the group tree for better overview by grouping the group names by their first <xx> characters.
Limit no. of groups to
Limits the number of queried groups.
Query templates
For more information, see #the-cabinet-folder-tree.
Clear script log at restart
Clears the script log area every time a script is executed.
Copy comments to script log
Copies comments in the script to the script log.
Add line numbers to script log
The line number of the command is added to the script log. If line numbers are stored, the context menu function Show command enables you to jump from any line in the log to the corresponding command in the script.
Synchronize log to file
Enables allows copying all log messages into a file. If selected, the user has to choose a target file every time a script is started. If an existing file is selected, the additional content will be appended to the existing file.
Log everything
Logs everything.
Log results only
Only logs results or error messages.
Log errors only
Only logs error messages.
Log nothing
Nothing is logged.
CSV format for query results
(Only valid for DQL script log) Results of DQL queries are logged in CSV format.
Fixed width for query results
(Only valid for DQL script log) Results of DQL queries are logged as lists with fixed width. If too long, the values can be truncated.
Next line
Color of the next script command to be executed (in debug mode only).
Error
Color of an incorrect script command (in debug mode only).
Name
Name of function, displayed in the context menu.
Typetag list
Comma separated list of Documentum type tags (for example, 09 = dm_document) to restrict the function to certain object types. You can use type tags instead of type names and they will automatically be replaced by type tags.
To assign a function to all object types, you can enter the * character.
If left blank, the function is always available. But it will only be executed once irrespective of the number of selected data records (the example function Last SQL statement uses this feature).
Repository List
Enables the allocation of functions to one or more repositories. Repositories can be either added manually or selected from a repository list. You need to use comma separators for multiple repository names. Adding an exclamation mark in front of the repository name (for example, ! testdocbase, hides this function if this repository is active.
Result
The result of a function execution can be presented in different ways:
- Count processed objects: Shows the number of processed objects in a dialog box.
- Show result in dialog: Shows the results in a dialog box.
- Open textwindow: Opens a text window to display the results.
- Pass to operating system: Passes the result to the operating system (e.g. result of a getfile command)
- Execute as Subquery: Opens a copy of the current session window and executes a DQL query.
- Do nothing: No action is taken.
(The Copy to Clipboard option has been replaced by the variable %Clipboard%, which provides more flexibility)
Category
Functions can be grouped by assigning a category. A category name represents a submenu of the context menu, where all functions of this category are listed.
Shortcut
A shortcut for the function can be set by selecting a value from the dropdown list.
Allow multiselect
Enables selection and processing of multiple objects.
Ask user before execution
Execution must be confirmed first.
Active
Inactive functions are not visible in the context menu.
Ignore errors
In case of error, the execution continues with the next object. Error messages are displayed in the function result message after processing all objects.
Create Debug Script
This option is for function development only. Instead of executing the function, the resulting API script opens in the API Script View, if the function was executed from a DQL Result List. If not, it will open in an extra text window and can be copied into any API Script view for execution. The generated debug script is full runnable in dqMan.
DQL Result List
Function is available in DQL Result List
Repository Navigator
Function is available in Repository Navigator
Object Navigator
Function is available in Object Navigator
Input field
For value input.
Input field with fixed valuelist
Input field with fixed value assistance that you must enter into the Valuelist Data control.
If items in the value list contain the characters||, the part before||is displayed in the control list; the part after ||will be returned as value (for example, Label||Value).
Input field with DQL query list
An input field with value assistance that is filled with the results of a DQL query. Enter The DQL in the respective field. If the selected list of the DQL query contains more than one attribute, the value of the first column is added to the value list and the value of the second column is returned as variable value. The query
Select object_name, r_object_id from dm_document fills the list with the object_name attribute of all dm_document objects. Selecting a name from the list returns r_object_id.
Date picker
Displays a date picker control.
File open dialog
An input field with a Browse button. You can enter a list of allowed file types in the File Formats control.
Directory selector
Enables you to select a directory from the local file system.
Cabinet/Folder selector
Enables you to select a cabinet or folder from the currently connected repository.
API Command
A single line API command, such as id,c,dm_acl. This command can reference the Results list columns by column names in curved clips, for example {r_object_id}.
It can also reference global variables with a lower index than itself (See function Change ACL under Change Obiecttype for more information).
Name
Name of the variable which you can use to reference the variable in the API sequence function.
Label
Caption displayed in the input dialog. If no label is available, the name will be displayed.
Default Value
The default value shown in the input control. If Show always is selected, this value always appears, otherwise it is only valid until another value is entered or selected. This new value will then be displayed the next time the function is executed.
You can reference columns of the DQL result grid using standard syntax, such as {object_name}.
Mandatory
Select if field is mandatory.
Use cached query
If selected, the result of the DQL query used to fill the value assistance is cached to improve performance, but changes to the underlying values will be ignored. Go to Session menu>Refresh Valuelists to clear cache. To add a new variable, click the Add variable button. To remove the current variable, click Delete Variable.
{*}
Rreferences the currently selected column of the Result list. If more than one column is selected, the function is deactivated.
{* ID}
The selected column must contain a valid object ID, otherwise the function is deactivated.
{* INT}
The selected column must contain an integer value.
{* TIME}
The selected column must contain a valid time value.
{* CHAR}
The selected column must contain a string value.
Naming conventions
You can freely any name but you must enclose it with %. They are not case sensitive. Examples:
%1%
%File-Contents%
%this is a variable%
Assignments
You can assign constants or results of API commands to a variable. Example:
%Repository_Owner%=dmadmin initializes the variable %Repository_Owner% with the value dmadmin(the Define command from earlier dqMan versions is not supported any more).
%ID% = id,c,dm_document, where object_name such as 'a%' assigns the result of the API command to the variable %ID%.
Concatenating values
You can concatenate values in two ways:
%ID% =+ Add this text
%ID% = %ID% Add this text
Usage
To use a variable, insert it at the appropriate position in the API command: get,c,%ID%,object_name
%result%
This variable saves the result to be returned, e.g. %result%=dump,c,{r_object_id}. If %result% does not exist within the API sequence, the result of the last executed API command is returned.
%CrLf%
This is a constant containing a carriage return and a line feed. You can use it for result formatting.
%Clipboard%
Enables text data exchange with the clipboard. If used, the current content of the clipboard is pasted. If a value is assigned, it will be stored in the clipboard.
Also, concatenation is possible:
%Clipboard% = Any text %Clipboard% and more
#$EditFile
Opens the currently processed object for editing and waits until the editor is closed.
#$Refresh <Column Name> {Column Name}
Refreshes the DQL result list by fetching the values of all attributes in the column list from the repository. If the char * was specified as column list, all currently selected columns are refreshed.
#$RemoveLine
Removes the currently processed line from the DQL result grid without destroying the Documentum object.
#$ShellExecute <Program> {Parameter}
Starts the <Program> with the supplied <Parameters> and returns control to dqMan without waiting for its termination.
The first parameter is the executable program. The number of parameters is free. Use space separators.
#$ShellExecuteAndWait <Program> {Parameter}
Works like #$ShellExecute, but dqMan waits for the program to finish its execution.
#$Sleep <time>
Pauses the function execution for <time> milliseconds.
#$Loop <collection identifier>
Start of a loop through a collection
#$Loop <attribute_name{(object_id)}>
Start of a loop through the values of the repeating attribute from the object identified by the object_id; object_id is not supplied, the ID of the currently processed object from the result list is used instead.
#$EndLoop
Marks the end of the loop.
#$FetchObject <r_object_id>
Opens the Object Navigator and loads the object identified by r_object_id.
Add item. When entering a URL or program file, type it into the cell manually.
Delete the selected entry.
Add a menu separator
Move selected entry upwards
Move selected entry downwards
