Customize dqMan

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.

General

The General category has four subsections:

• Settings

• Login

• Shared Favorites

• Documentation

Settings

Setting Name	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.

Login

Option	What It Does
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.

Shared Favorites

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.

Documentation

You can add and manage links to documents, URLs or program files to the Documentation menu using the function bar:

Add documentation to the selected Job

Function Bar Element	What It Does
	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

The API Command View

Command	What It Does
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.

The DQL Command View

Settings

Setting	What It Does
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.

Code Editor: Grid Colors

Command	How It Affects Grid Colors
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)

Code Editor: Grid Hints

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:

Grid Hint Element	Description
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).

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.

Translation Name	Role
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.

Describe Options

These settings have already been described in #16.3.5.-describe-options.

The Repository Navigator

In the Repository Navigator, you can manage the Cabinets/Folder Tree, the Object Type Tree and the Group Tree.

• The Cabinets/Folder Tree

Cabinets/Folder Tree Setting	What It Does
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.

• The Object Type Tree

Object Type Tree Setting	What It Does
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.

• The Group Tree

Group Tree Setting	What It Does
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.

The Script Views

Setting	What It Does
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).

Functions

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 [e-mail].

Object Functions

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:

Setting	What It Does/What It Is
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.

Options

Option Name	What It Does
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.

Targets

Target Option	What It Does
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

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:

Field Type Setting	What It Is/What It Does
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.

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:

Placeholder	What It Does
{*}	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.

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:

Local Variable Name	How to Use the Local Variable
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

• Predefined variables, as you can see here:

Predefined Variable Name	How to Use the Predefined Variable
%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

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:

Script Command	What It Does
#$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.

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.

17.6.2 Session Functions

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.

Security

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.