Script Generator

With this tool, you can generate DQL, API, Docbasic or other scripts from a data list, either a DQL query result list or an external data list. The tool is available from the context menu of the list calling the function Generate Script.

Script Templates

A script template represents the basis for a script. It consists of three areas: header, body and footer. The header and the footer can only contain static text, added exactly once at the beginning and/or at the end of the script.

The script body is applied to each line of the data list. The script thereby contains one copy of the script body for each data record. The script body can contain text, placeholders for data from the data list and processing instructions.

With the generation of the script, the placeholders are replaced by data from the data list. The processing instructions are removed.

Placeholders

In the source data list, you need a placeholder consisting of a column name enclosed by curved clips, for example: {r_object_id} or {object_name}.

If the data list is a DQL query result list, placeholders can contain any attribute of the underlying object type. If this is available in the data list, the value is taken from there. If not, the value is loaded from the repository object.

To insert placeholders, click Insert Querycolumn from the context menu, then select one of the available placeholders that are part of the data list from the submenu.

Entering a left curved clip in the editor area or pressing strg+Space will open a selected list containing all the attributes of the referenced object type.

Placeholders with no reference to the data list will be displayed in cursive (italic).

Processing instructions

There are two processing instructions available: LOOP and IF EMPTY.

The LOOP Instruction

LOOP enables the processing of values of repeating attributes, for example:

{LOOP r_version_label} ...{r_version_label}... {END LOOP}

You must specify a repeating attribute in the LOOP instruction to resolve the attribute to single values. To process more than one repeating attribute simultaneously, you can specify all attributes using commas as separators:

{LOOP r_accessor_name, r_accessor_permit, r_accessor_xpermit}

This is called a combined loop. The recurrence frequency of a loop is determined by the amount of values in the first repeating attribute. You can create loops from the context menu.

The IF EMPTY Instruction

This instruction enables the processing of empty attributes. Example:

{IF EMPTY(title)} ... set,c,{r_object_id},title ... {ELSE} .... {END IF}

The attribute must be defined in brackets. Within a loop, repeating attributes can be processed.

IF EMPTY instructions must not be nested.

Examples

Example 1: Concatenate attribute values into a separate attribute.

This example will produce an API script that concatenates the values of object_name and title in the attribute subject, separated by a hyphen.

set,c,{r_object_id},subject {object_name}-{title} save,c,{r_object_id}

Example 2: Loop a repeating attribute.

This example turns all values of authors to capital letters. The basic DQL query (select *, Upper(authors) as uauthors from dm_document) supplies the values in capital letters in the repeating attribute uauthors.

truncate,c,{r_object_id},authors

{LOOP uauthors} append,c,{r_object_id},authors {uauthors} {END LOOP}

save,c,{r_object_id}

Manage Script Templates

You can save script templates for further use by clicking the Save button; you can open scripts by clicking the Load button on the toolbar and then selecting one from the Open File dialog box.

Click the downward arrow to open a submenu that contains all the templates saved in the subdirectory .\Scripttemplates inside the dqMan program directory.

The History Section

Recently created script templates are automatically stored in History. Click the Back and Next buttons to load templates from History.

Script Types and Options

Selecting the script type enables dqMan to enhance the script generation process.

Script Type	What It Does
API Script	Pastes API scripts into the API script view for execution. A syntax help for API commands is available.
DQL Script	Pastes DQL scripts into the DQL script view for execution. Command separation is also checked.
Docbasic Script	Opens Docbasic scripts inside a Docbasic interpreter, if available. You can define the Docbasic interpreter and the parameters in the Options dialog box.
Other...	You cannot execute scripts without type, you can only save them.
Translate Booleans	Automatic translation of Boolean values. DQL queries return for Boolean values either 0 or 1. API commands expect T or F. If this option is activated, the values will be translated, if an API script is generated. 0, T and t will be translated to T, all other values to F.
Mask single quotes	This option is not available for API scripts. If a string value contains a single quote, it is masked by another single quote. For example, if a value is Mark’s test, a generated DQL command would contain something like …set title=’Mark’s test’… . This will cause an error on execution. Activating this option will result in: … set title=’Mark’’s test’… that will be accepted by DQL processor and result in the correct title value.

Add Data Sources

You can generate a script from two data sources simultaneously, the additional source being another DQL query result or a data list. You can open the additional data source by clicking the Add Source button of the toolbar and then selecting from the possible data lists on the submenu.

The additional data source must be joined with the main data source to enable correlation of the data records. At least one column of the main data source must be joined with one column of the additional data source.

To join to columns, select the columns in both lists and click the Join button. You can also use drag-and-drop onto the opposite list. To delete a join, use the context menu of the Selected Columns grid.

After a successful join, you can add placeholders to the script template from the context menu or value lists. The placeholders have the following format:

{data:object_name}

Generate a Script

You can generate a script from the template by clicking the Generate button. During script generation, the Stop button is activated so that you can halt the generation process and return to the script template.

If the script is finished, the label changes to Template. Click it to go back to the script template.

You can save or execute a generated script.

Execute a Script

Click Execute Script to copy the script into the appropriate script view of the active dqMan session window or, depending on the script type, to open the Docbasic interpreter.

If the script should be executed in a different session, the available sessions are displayed in a submenu that you can open by clicking the downward arrow button.

You can also open a new session from this menu. The script generator closes automatically.

Type Dependent Script Templates

Type dependent script templates are a special variant as they are bound to a certain Documentum object type, identified by the type tag. This type of script template will be available directly in the DQL result list context menu, if the list contains a column with r_object_id values. Additionally, these script templates do not depend on the values of the result list. Only the r_object_id is mandatory. All other attribute values are loaded from Documentum during the generation process.

You can generate type dependent script templates using the script generator and you must save them in the subdirectory .\Scripttemplates within the dqMan program directory. Furthermore, while saving the script, you need to save the type Typescript in the Save File dialog box. In addition, you need to name the template and select a type tag in an additional dialog box.

Additional data sources are not allowed in type dependent script templates.

An example is available to you in dqMan: ACL Create Script:

Script Header:

# ACL Create Script Template # Created 06/26/2004 # --------------------------------------------------------------

Script Body:

# Create ACL {object_name} create,c,dm_acl set,c,l,object_name {object_name} set,c,l,description {description} set,c,l,owner_name dm_dbo set,c,l,acl_class {acl_class} {LOOP r_accessor_name,_accessor_name,_accessor_permit,_accessor_xpermit_names} grant,c,l,{_accessor_name},{_accessor_permit},{_accessor_xpermit_names} {END LOOP}

save,c,l # -------------------------------------------------------------

Script Footer: # END ACL Create Script

Note the use of the computed attributes _accessor_name, _accessor_permit and _accessor_xpermit_names in the LOOP instruction. Since computed repeating attributes are computed on demand, they usually return the wrong number of contained values.

To ensure the correct processing of the LOOP instruction, the regular attribute r_accessor_name of the type dm_acl is included in the loop attribute list at the first position, without being referenced within the loop.