DQL/API Script View

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.

The DQL Script view

The API Script View

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.

Execute Scripts

You can execute scripts either end-to-end or step by step. You can control the execution using the toolbar or the context menu.

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

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

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.

Error Handling

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.

Using Variables in API Scripts

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.

Using Script Commands in API Scripts

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:

Script Command	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.

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.

Logging

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:

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