The DQL Script and API Script views are described together since they provide similar functionality for executing scripts. A script is a sequence of multiple DQL statements or API commands that will executed in succession.
It is not possible to mix DQL and API in the same script, hence the separate views for executing one or the other type of script.
The upper input area is where you enter the script and the script results are logged in the lower section.
Double-clicking an element in the script log copies the value to the clipboard. Press Ctrl when double-clicking to paste the value into the active input control at the current cursor position.
Click and hold the left mouse button for 1 second on any value representing a valid Documentum r_object_id to load the respective object into the Object Navigator (for more information, see Object Navigator).
The actual script can be typed/edited directly in the upper code editor area of the window, pasted from the clipboard, loaded from an external file or generated in dqMan using the built-in Script Generator:
Load from file: Either use the Load Script function from the Edit menu, or the Navigator (folder tree) or drag-and-drop the file to the input area.
Generate a script from a DQL resultset or imported tabular data using the Script Generator (see Script Generator).
API scripts typically consist of a sequence of individual API commands, one per line. API command that need an input value will have the command on the first line and the value on the following line.
DQL statements can consist of more than one line. Therefore DQL statements in scripts must be terminated by a semicolon ";"
Each line beginning with the the# or with the // is regarded as a comment line. Comments will be ignored during execution and have no effect on the result of the script.
You can execute scripts either end-to-end or step by step. You can control the execution using the toolbar or the context menu.
Note that some of the above commands may not be available depending on the type of code being executed and/or if execution times are too short for the user to interact with the buttons during runtime.
Additional functions are available in the context menu.
Run to Cursor executes all commands from the current cursor position or from the beginning to the selected line. The command in the current line is highlighted and debug mode is turned on.
In debug mode, you can select to execute the next command using Set Next Statement. This can be used to place the next statement/command that will be executed anywhere in the code, thus skipping errors or unneeded steps.
Breakpoints can also be set to control the execution of a script. Any number of breakpoints can be set anywhere in a script using the Set/Remove Breakpoint context menu items respectively. Breakpoints will be set/removed on the line where the context menu is opened, and will be marked with a red dot to the left of the line as well as highlight. It is also possible to remove all breakpoints at once when they are no longer needed using the Clear All Breakpoints content menu item.
Breakpoints cannot be set on empty lines or comments.
Breakpoints can only be set on the starting line of a statement/comment, not "inside" it.
Trying to set a breakpoint in a location where it is not allowed will move the breakpoint automatically to the starting line of the closest statement/command.
The Script Navigator is a directory tree for all available local drives, enabling fast access to stored API and DQL Scripts.
The Script Navigator is available in the API Script view and the DQL Script view, to the left of dqMan screen.
You can open a selected script using the Return key or by double-clicking it. Open scripts are marked as such until the session window is closed. Additionally, you can toggle the marks using the function Mark as New and/or Mark as Opened from the context menu.
Default settings for file extensions are .api, .apiscript, .dql and .dqlscript. You can filter them using the function Filter from the context menu.
The option Stop on Errors in the script editor's context menu defines the error handling behavior:
When this option is active, the script pauses in case of error and highlights the faulty statement/command. The statement or command affected by the current error will be highlighted in its entirety (even if it spans multiple lines) to clearly show which part of the script is affected.
In this case you can only resume script execution by fixing the error OR manually setting the next line to be executed beyond the point where the error occurred, thus skipping the error entirely (see description of Set Next Statement in #_toc105765626 above)
If this option is inactive, the script will not stop execution but will display error messages in the result log.
Error handling will always pause on any error, prompting you to take action before resuming execution (for example, to fix the error or place the cursor after the error to skip it).
In an API script, you can turn on/off error handling using the script command #$ StopOnErrors on|off.
You can use temporary variables in API scripts to store return values for further use. The values of the variables remain during a script run until either the execution of the script is terminated or the content of a variable is overwritten.
Variables in API scripts are not compatible to the Documentum API language. Scripts with variables cannot be executed by other applications. However, the command line program dqAPI and Pack&Go Scripts support variables.
Naming conventions The name of a variable can be chosen freely but it needs to be enclosed within percentage signs. They are not case sensitive. For example:
%1%
%File-Contents%
%this is a variable%
Assignments
You can assign constants or results of API commands to a variable. For example, %Repository_Owner% = dmadmin initializes the variable %Repository_Owner% with the value "dmadmin" (you can also use the Define command from earlier dqMan versions, but it is marked as deprecated). Also, %ID% = id,c,dm_document where object_name like '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.
Query variable contents When executing the script in debug mode, you can query the values of the variables. Click the variable and wait for the hint to appear.
Script commands are additional commands that expand the functionality of API scripts or object functions. Using script commands in API scripts is not compatible with the Documentum API language. Scripts with script commands cannot be executed by other applications, except dqAPI and Pack&Go Scripts.
Available script commands are:
Example of 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
#$ Print Group name %LoopIndex1%: %group_name%
#$EndLoop
Use the #$EndLoop command to handle the collection. You do not need to add next or close commands.
The %LoopIndex<i>% variable only exists within a loop and contains the current loop index, starting with 0. %Loopindex1% is the index of the first loop. %Loopindex2% should be the index of the second loop, if it is nested within the first loop.
Example of 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%]
#$ Print %FolderPath%
#$EndLoop
#$EndLoop
The %LoopIndex<i>% variable is incremented every time the #$EndLoop command is executed. It can be used as an index for the repeating attribute values.
During the execution of scripts, the result of the commands are logged in the result log. You can define logging behavior in the Settings of the result log context menu.
The following logging settings are available:
In the DQL View, you can execute single DQL queries.
To execute a DQL query, do one of the following:
Press F9 or Shift+Enter.
Go to the Edit menu>Run.
Click Run on the context menu.
Click the Run button on the toolbar.
Other actions you can perform in the DQL View:
Double-click a cell in the result grid to copy the value on the clipboard. Press Ctrl when double-clicking to insert the cell value into the code editor at the current cursor position. The latter can also be performed on the result grid's column headers to insert the respective column names as attribute names at the cursor position.
Double-click the messages in the status bar to copy them to the clipboard. Move the mouse cursor over the status bar to display the current message in a tooltip, if it does not fit into the message bar area.
You can see information about the latest executed action and the query result in the Messages area.
The status bar displays the complete execution time of the query, including the transfer of the query results to dqMan. The pure server response time without data transfer is labeled as Server response time.
You can enter one or several DQL queries in the SQL Query input area. When executing the query, all the content in the input area is regarded as one query and transferred to the Documentum server for execution. However, if only a part of a query is selected, then only this part is executed.
Use semicolons as separators for two or more queries. Setting the text cursor on one query selects this query for execution.
Moreover, you can add comments. Every line beginning with the # or // characters is regarded as a comment line.
A number of syntax assistance functions supports the creation of DQL queries:
Command syntax: Click a DQL command and wait for the hint to view the correct command syntax.
Function syntax: The syntax of functions, such as Dateadd, Datediff and so on, is displayed automatically while typing the DQL command. You can activate syntax assistance by pressing F1 on your keyboard.
Auto completion: Several dynamic values, such as object names, group names and so on, or allowed function values are faded in automatically in the form of a selection list. You can copy the values from selection lists by pressing Enter.
You can manually activate the selection list anywhere in the command area by pressing Ctrl+Space. The list is filled context dependent with the likely values at the current position. If none of the pre-defined lists applies, the list is filled with the possible attribute names.
Some of the selection lists are read dynamically from the repository when opening the session. The values in these lists can be subject to changes by other activities that will not be recognized by dqMan. In this case, you can reload and refresh the lists by clicking Session menu>Refresh Valuelists.
In the DQL View, you can use queries the attribute labels of any locale instead of the original attribute name. dqMan will replace labels with the attribute names at execution. Attribute labels must be placed in square brackets within the query.
Select r_object_id,object_name,[ACL Name],[Application type]
from dm_document where …
The Results list contains the results of the DQL queries.
Use your mouse to resize the columns and rows and reposition the columns in the Results list.
To search through the entire table, go to Edit menu>Search. Typing one or several initial letters within one column will scroll to the first matching value.
You can right-click the desired Results list column head and select to sort it alphabetically. Clicking an item to scroll the column into the visible range of the list.
On the data area, a list of functions is faded in for object processing. Available functions are:
Edit Starts the Results List Inline Editor. (!!!Make this a hyperlink: 3.1.5 The Results List Inline Editor!!!)
Copy This function copies the selected values to the clipboard. Rows will be separated with a linefeed and a carriage return character; columns will be separated with tabs.
Copy with Header This function copies the selected values to the clipboard, including the header names of the selected columns in the first line. Rows will be separated with a linefeed and a carriage return character; columns will be separated with tabs.
Duplicate Duplicate copies all selected values in a separate data grid.
Add to compare list The selected objects are added to the Object Compare list.
Sort Sorts the result data ascending or descending by the selected column.
Goto... Enables the fast change to a line or a column for the Results list. Entering a number enables vertical scroll, entering a column header or selecting one from the will enables horizontal scroll.
Marks Used to select different objects in the Results list. You can toggle or scroll marks to the next or previous marked object. Marks are mainly used by the Compare Data function, but can also be set manually.
Object functions Thisis where user-defined functions for objects in the Results list are provided, such as Change ACL, Dump Object, Last SQL statement, Request PDF rendition and so on. You can manage object functions in the Options Dialog. Object functions are available depending on the selected type of document and the individual configuration.
Export to Exports the selected cells of the Results list to CSV or Microsoft Excel (you need to have Excel installed to be able to export to this format). If the amount of exported data exceeds the Excel limitations of 65535 lines and 256 columns, more than one Excel tab sheet will be used. You cannot export data to Excel if a remote Office 365 installation is used; if this is the case, use the Copy with Header command.
Generate Script Opens the Script Generator that lets you generate DQL or API scripts from the selected data. Additional type dependent script templates will also be available, if the appropriate object type is selected.
Plugin Functions If dqMan Plugins that supply object related functions are installed, these functions will be displayed at the end of the context menu.
You can edit values directly in the Results list, if the results contain the r_object_id attribute.
Press Enter to save any changes.
Pressing Esc or moving the focus to any other control will close the editor without saving.
Single Attributes For single attributes, a standard input field will be created in the corresponding cell of the grid. Some attributes display a list with possible values. This list is filled in either with the values of a data dictionary value assistance or with manually configured values from the file dqManValuelists.xml.
Repeating Attributes You can modify Repeating Attributes within a small sub grid. As DQL results do not show the correct order of repeating attribute values, the contents of this list can differ from the displayed values in the Results list. The sub grid offers an own context menu for inserting, deleting or reordering values of the repeating attribute.
Multiple Single Attributes If the Results list contains more than one result, you can edit a single attribute of multiple objects simultaneously. Select more than one value in a column and start the editor. The values you enter are applied to all the selected objects.
Linked Repeating Attributes
You can modify linked repeating attributes of one object such as r_accessor_name, r_accessor_permit and r_accessor_xpermit of dm_acl in a multicolumn sub grid. Select more than one column of repeating attributes and start the editor.
Multiple standalone or linked repeating attributes You can also modify standalone or linked repeating attributes of more than one object at the same time, if the selection is extended to more than one object (line) in the result grid. The values you enter are applied to all the selected objects.0
You can filter query results by the queried values using the attribute filter, which can be open for each column. You can combine filters and use them for multiple columns using an “and” operation.
To open an attribute filter for a column, click the button in the column header and then, in the filter dialog box, you can see the filter options depending on the column data type.
Click Apply Filter to activate the filter after selecting the filter options. If a filter is active, the filter button in the column header and the row numbers are highlighted.
Additionally, all filter buttons in column headers have a context menu.
If at least one filter is active, the top left cell of the result grid also displays a filter button with an active context menu with one additional function: “Generate Predicate”. Executing this function generates a predicate (part of a "where" clause) from the current filter settings and copies it into the clipboard, enabling you to add it to the current query to replace the filter settings. Example:
(Upper(object_name) like 'DM%') and
(globally_managed in (0)) and
(acl_class < 3)
The Message Area logs the executed DQL commands and their results. The context menu offers some settings to influence the behavior:
Settings:
You can activate the Message Area from the View menu.
You can enter the Describe command in the DQL input window and it displays all attributes and selected characteristics for an object type.
Syntax:
Describe <type> [all|custom] [with name='<name>'][,locale=’<locale>{,<locale>}|all’]
Describe <table> [name='<identifier>']
Arguments:
You can modify attribute labels directly in the Results list, using the edit function from the context menu. Changed labels are published immediately. To delete labels, simply enter an empty value; in this case, the inherited label from the supertype is displayed.
Examples:
The Describe command is also available from the context menu of the input area. The function is activated if the context menu is open on the name of an object type or a registered table. This call corresponds to the Describe <type or table> all command.
Describe options: The Describe options enable you to customize the columns and their order of the describe Results list. Available columns are predefined and you can select them by selecting the respective checkbox. Moving columns upwards or downwards alters the default order.
The column “owner” is only displayed if the argument all or custom is used and attributes from different type levels in the hierarchy are displayed. In this case, also the type owned attributes can be marked by selecting the Mark owned attribute labels checkbox. This functions gives a good overview whether a type uses the inherited label or overwrites it with own values.
Template Queries are DQL queries that contain placeholders for values. When executing a Template Query, you need to enter values for the placeholders.
Placeholders consist of a freely selectable name, enclosed by { } characters. You can insert placeholders either manually or with a function available in the context menu of the input window. Template Queries can contain any number of placeholders.
If placeholders appear in a query more than once, they always represent the same value.
Placeholder names are case sensitive!
Also, if for any reason an opening curved clip is needed in the DQL query for another purpose than for beginning a placeholder, mask it with a double opening curved clip, like … where object_name like ‘{{%’.
You can improve the behavior of placeholders by adding placeholder options, using the Edit template field option from the context menu.
Various types of value lists are available in Value List Type, as follows:
If the result of a DQL query contains more than one attribute, the value of the first column will be displayed in the value list and the corresponding value of the second column will be inserted in the query.
In a fixed value list, you can make a distinction between the displayed value and the inserted value using the || separators (for example, Label||Value).
The query Select object_name, r_object_id from dm_documentwill fill the list with the object_name attribute of all dm_document objects. Selecting a name from the list returns the r_object_id for the placeholder value.
Using Check Syntax, you can verify the syntax of the current DQL query. This feature is only available, if a valid session exists.
You can format DQL queries automatically. The associated format templates are defined in the file dqManFormatTemplates.xml.
To format a query, click on the query in the DQL input area and select the function Auto Format Query from the context menu of the DQL input area.
The Query:
Select r_object_id, object_name, acl_name from dm_document
where object_name like 'dm_%' or object_name like 'xy_%' order by r_object_name, acl_name
Will be formatted to:
SELECT
r_object_id,
object_name,
acl_name
FROM
dm_document
WHERE
object_name like 'dm_%' or
object_name like 'xy_%'
ORDER BY
object_name, acl_name
To clear the formatting of a query (unformat), use the Unformat Query function from the context menu. Calling this function removes all tabs, multiple spaces, line feeds and carriage returns from the query, leaving a plain single line query.
The third formatting function Extract Query can be used to extract the DQL part out of a piece of program code. From this code:
String query = "Select * from pl_produkt (all) where i_chronicle_id = '" +
chronicle_id + "' and " +
"valid_from <= Date (Today) and " +
"Dateadd(day,1,valid_to) > Date(Today) and " +
"any r_version_label = '_NEW_'";
This query will be extracted:
Select * from pl_produkt (all) where i_chronicle_id = '' and valid_from <= Date (Today) and Dateadd(day,1,valid_to) > Date(Today) and any r_version_label = '_NEW_';
Note that the variable chronicle_id is removed, leaving an empty value to be filled …where i_chronicle_id = '' and…
DQL queries can be executed repeatedly and automatically in a selectable or freely definable interval, causing the results to be refreshed accordingly.
The function is available in the context menu of the DQL editor. (Repeat Query every…). After selecting the interval, a yellow notification bar is displayed at the top of the DQL editor counting down to the next query execution. Automatic execution can be stopped at any time by selecting Stop Repeat Query from the context menu or from the notification bar.
In case of automatic execution the message area will not be deleted and will display the full log containing all the executions.
| Command | What It Does |
|---|---|
| Script Command | What It Does |
|---|---|
| Command | What It Does |
|---|---|
To stop a running query, click the Stop button on the toolbar.
Click and hold the left mouse button for 1 second on any value representing a valid Documentum r_object_id to load the respective object into the Object Navigator (see ).
| Function | What It Does |
|---|
| Function | What It Does |
|---|
| Function | What It Does |
|---|
| Function | What It Is |
|---|
| Function | What It Does |
|---|
| Name | Function |
|---|
| Name | What It Does |
|---|
#$StopOnErrors on|off
Sets the error handling behavior during script execution.
#$Print <text>
Prints the text and/or the values of variables into the script log.
#$Sleep <time>
Pauses script 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 ID object_id.
#$EndLoop
Marks the end of the loop.
Log everything
Logs everything.
Log results only
Only logs results or error messages.
Log errors only
Only log errors.
Log nothing
Stops the logging activity.
Add comments
Copies comments from the scripo into the log.
Add line numbers
The line number of the command will be added to the script. If line numbers are stored, the function Show command enables you to jump from any line in the log to the corresponding command in the script.
Synchronize log to file
Copies all log messages into a file. If active, you need to select a target file every time a script starts. If an existing file is selected, the additional content will be appended to the existing content.
CSV format for Query results (Only valid for DQL Script Log)
Logs the DQL queries in CSV format.
Fixed width for Query results (Only valid for DQL Script Log)
Results of the DQL queries will be logged as a list with a fixed width. Values can be truncated, if too long.
Modify Filter | Opens the filter dialog box. |
Clear Filter | Clears the selected filter and updates the list. |
Filtered Columns | Displays the list of all active filters in the list. Select a column to scroll the list down to the corresponding column. |
Show marked objects only | Limits the filter to the marked objects, for example after using Compare Data function. |
Clear all OTHER Filter | Clears all other filters except for the selected one. |
Clear ALL Filter | Clears all filters. |
Copy | Copies selected text to clipboard |
Clear | Clears message Area |
Word Wrap | Toggles word wrap |
Auto Clear Log | Clears the Message Area before executing a query (this setting is ignored for auto repeated query). |
Log Query Results | Besides messages, DQL results will also be logged in the Message area. |
CSV Format for Query Results | Results of DQL queries will be logged in CSV format. |
Fixed Width for Query Results | Results of DQL queries will be logged as list with fixed width. Values can be truncated if too long. |
<type> | Object type, such as |
[all|custom] |
|
<table> | Name of a registered table, such as |
name='<name>' | Part of or complete attribute name and/or column name. Wildcards are "*" or "%". |
locale=’locale’ | Locale name for the attribute labels. Multiple locales can be separated by comma. |
Describe | Lists all |
Describe | Lists all |
Describe | Lists all customized |
Describe | List column definitions of the registered table |
Name | Name of the placeholder |
Label | Caption displayed in the input dialog. If no label is available, the name will be displayed. |
Default Value | The default value displayed in the input control. It remains valid until entering or selecting another value. |
Mandatory | Select this checkbox if the field is mandatory. |
Use cached query | If selected, the result of the DQL query used to fill the value assistance will be cached to improve performance, but will ignore the changes to the underlying values. Select Refresh Value lists from the Session menu to clear the cache. |
None | No value list. |
Fixed List | A list with fixed values that must be predefined in the control Values. |
DQL Query | A DQL query that fills in the list dynamically. |
Date Picker | Displays a date picker control. |
File Open Dialog | Opens a File>Open dialog box. You can define a list of available file types in the control Values. |
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. |
Starts the script and executes it end-to-end.
Executes the script one statement/command at a time, requiring the user to initiate each step by pressing this button repeatedly.
The next statement/command to be executed is always highlighted. This is ideal for debugging complex scripts or simply following the individual processing steps a script performs.
Pauses a running script and switches to debug mode. The next command will be highlighted.
Stops the execution.
Once logged in, you can work in the Session Window in any of the following editors/views:
DQL: DQL code editor/view
API: API command view
DQL Script: DQL script editor/view
API Script: API script editor/view
You can switch anytime between these views using the above toolbar buttons or the View menu. Changing the view does not delete any existing commands or results in other views; moreover, during script debugging, you can execute commands in other views without stopping the debug process.
The tab color can be set at each session for each user to be different. This setting is preserved after restarting dqMan. A user can set only one color on a repository. A user can reset the color at any time. Each user can have a different color on the same repository. A user can have several open repositories, each with a specific color set by the user.
You can use the below toolbar buttons to execute your DQL queries/API commands/scripts. It is possible to run/step into/pause/stop DQL queries/API commands/scripts.
Note that some of the above commands may not be available depending on the type of code being executed and/or if execution times are too short for the user to interact with the buttons during runtime.
In API View, you can execute API commands.
To execute an API command, do any of the following:
Press Enter
Press F9
Press Shift+Enter
In the Edit menu, select Run
Click the Run button on the toolbar.
Double-click an element in the result log to copy the value to the clipboard. Press Ctrl when double-clicking to paste the value into the active input control at the current cursor position.
Click and hold the left mouse button for 1 second on any value representing a valid Documentum r_object_id to load the respective object into the Object Navigator (see Object Navigator)
Certain API commands can be executed without a connected session (such as getservermap, getdocbrokermap or connect).
The context menu of the result log contains some additional functionality:
To open the API command help, click the API Command Help button to the right of the Command field. You can then search for API commands or you can insert a command by double-clicking the command input field.
| Menu item | What It Does |
|---|---|
Dump Object
Creates a dump of an r_object_id.
Open File
Opens the file if a full filename is supplied in the log, for example after a getfile command.
Login as…
Opens a new session with the login ticket data under the cursor after a getlogin command.
